Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion crates/socket-patch-cli/CLI_CONTRACT.md
Original file line number Diff line number Diff line change
Expand Up @@ -2607,7 +2607,7 @@ command's integration tests check its output.
| `redirect_withdrawn_restore_failed` | `warnings[]` (warning; human: `Warning: …` / `Error: …`) | scan `--mode hosted`: a pin whose patch is `withdrawn` / `not_found` could not be restored to its upstream registry entry (the restore refused it, writing the restored files failed, or the apply lock was held). The pin is kept and no `rolledBack` event is recorded for it; the detail names the remedy (`git checkout -- <lockfile>`, or re-run / `socket-patch rollback <purl>`). A write failure is one warning naming every pin it kept. Status and exit unchanged, unless the failed write could not put a file back: see `lockfile_write_failed`. |
| `patch_withdrawn` | `rolledBack` / `verified` (hosted event) | scan `--mode hosted`: the lockfile pinned a patch the server reports `withdrawn` or `not_found`; the pin was restored (dry run: would be) to its upstream registry entry. `reason` names the uuid and status. See "Withdrawn pins". |
| `vendor_prebuilt_stub_invalid` | `failed` | RubyGems: the server stub lacks required attributes or is otherwise invalid; no local stub fallback is permitted. |
| `bazelignore_not_updated` | run-level `warnings[]` | Go vendored and agent mode in a Bazel workspace (additive): the `.bazelignore` at the Bazel root, which keeps Bazel and gazelle out of the module copies under `.socket/vendor/golang` and `.socket/go-patches`, was not updated. It could not be read or written (a symbolic link or a directory in its place, a read-only directory, a read-only file). The detail names the line to add, or says that the lines of a copy that is gone can be deleted; the command's patch or undo stands and its exit code is unchanged. See docs/ecosystems.md "Bazel workspaces: `.bazelignore`". |
| `bazelignore_not_updated` | run-level `warnings[]` | Go vendored and agent mode, and Cargo vendored mode under a rules_rust crate hub, in a Bazel workspace (additive): the `.bazelignore` at the Bazel root, which keeps Bazel and gazelle out of the module copies under `.socket/vendor/golang` and `.socket/go-patches` and out of the crates under `.socket/vendor/cargo`, was not updated. It could not be read or written (a symbolic link or a directory in its place, a read-only directory, a read-only file). The detail names the line to add, or says that the lines of a copy that is gone can be deleted; the command's patch or undo stands and its exit code is unchanged. See docs/ecosystems.md "Bazel workspaces: `.bazelignore`". |
| `maven_bazel_hub_unpatched` | run-level `warnings[]` (human: `Warning: …`) | Maven in a Bazel workspace, vendored and agent mode (additive): a pinned rules_jvm_external hub of the root `MODULE.bazel` fetches the jar of a Maven patch that this run vendored or applied, or tried to (`vendor`, `apply`, and `get` / `scan` in those modes; in agent mode only for a package it found installed; never under `--global`), and the block that hosted mode keeps in `MODULE.bazel` holds no entry for that jar. The hub builds the jar its own lock (`maven_install.json`) names, so the patch does not reach the Bazel build: these modes patch no hub. One warning per purl; the detail names the lock, the hub, the file and line of its `maven.install`, and the hosted command that patches a pinned hub. The events, the exit code and every written file are those of the same run without the workspace. A `vendor` whose `--ecosystems` leaves Maven out gives none. A vendored run that takes a hosted pin over (`vendor`, `scan` / `get --mode vendored`, `vendor --revert`) leaves the block's entry for it as it is. A hosted run never gives it: see the `maven_bazel_*` rows below and docs/ecosystems.md "Bazel workspaces: Maven". |
| `maven_bazel_unreadable` | vendored / agent: run-level `warnings[]` (human: `Warning: …`); scan/get `--mode hosted`: `warnings[]` (warning) | Maven in a Bazel workspace (additive): whether a rules_jvm_external hub builds the jar of a Maven patch could not be told, because something could not be read with certainty: a hub without `lock_file` in vendored and agent mode (hosted mode gives `maven_bazel_not_pinned`), a `maven.artifact` or `maven.from_toml` tag that cannot be read, a lock that is missing, empty, not format 2 or 3, larger than 16 MiB or no JSON, a `WORKSPACE` file that calls `maven_install` or cannot be read while `.bazeliskrc` or `.bazelversion` at the Bazel root names no release of Bazel 9 or later, a `maven.install` whose `name` or `lock_file` is not a plain string, a construct of `MODULE.bazel` the reader does not follow, and, in vendored and agent mode, a `maven.override` of the artifact (hosted mode gives `maven_bazel_no_effect`). Hosted mode also gives it for a hub on an isolated `use_extension`, an rc file that cannot be read (also one that an import takes from outside the workspace by a relative path, and one with a line whose reading Bazel's own source calls an oversight: a quote that is never closed, a `\` with nothing after it), a `MODULE.bazel` that is a symbolic link, and a block of `MODULE.bazel` that was changed by hand (also in its first line alone), and then writes no entry for the hub. One warning per purl; the detail names the file, the line and the reason. |
| `maven_bazel_not_at_root` | `warnings[]` (warning; human: `Warning: …`) | scan/get `--mode hosted` in a Bazel workspace (additive): a rules_jvm_external hub builds the jar of a Maven patch, and the project is below the root of its Bazel workspace, in whose `MODULE.bazel` the patch of a hub is written. Like the five codes below and `maven_bazel_unreadable` in hosted mode, it means that the run wrote no entry for the jar in the block of the root `MODULE.bazel`, because it could not show from the checkout that the entry works. One warning per purl, in the place of `redirect_maven_no_pom` for that purl; the detail says why and ends with what the block of the root holds for the jar, which is read for a project below the root too (the detail then names the file as "the MODULE.bazel at the root"). Nothing: "socket-patch wrote nothing to MODULE.bazel for it, so the Bazel build keeps the upstream jar". The event is the one of the same run without the hub: `skipped` / `redirect_unconfirmed` in a tree only Bazel builds, `applied` beside a `pom.xml` or Gradle pin that landed. The entry of the patch, from an earlier run: that entry stays, the event is `applied`, and the detail ends "socket-patch left the entry that MODULE.bazel holds for it as it is". The entry of another patch of the same jar: it stays too, the event is the one without the hub, and the detail ends "socket-patch wrote nothing to MODULE.bazel for it: the entry of patch <id> remains there, and where the block is in effect the Bazel build takes that patch's jar". Exit code unchanged. With none of these codes the run writes the block: `redirect.rewrittenFiles` holds `MODULE.bazel`, the event is `applied`, and `rollback` / `remove` take the entry out. See docs/ecosystems.md "Bazel workspaces: Maven". |
Expand Down Expand Up @@ -3172,6 +3172,29 @@ detail names the entry and the declarations. Like the other unattested
references, re-vendoring cannot clear it, so it is not drift. The check never starts an API client or writes
lock/recovery files. `--check` conflicts with `--revert`.

One file that the ledger's inventory of a directory artifact does not list is not drift:
the `BUILD.bazel` that rules_rust's cargo-bazel (0.59.0 and newer) writes into a Cargo
copy each time Bazel evaluates a crate hub that takes the crate from that path. It is
left out of the comparison when it is a regular file of that name in the copy's own
directory, starts with cargo-bazel's banner (a line of `#`, `# @generated`, and a line
that starts with `# DO NOT MODIFY: This file is auto-generated by a crate_universe
tool.`), the project is in a Bazel workspace with a hub of its crates (the `MODULE.bazel`
at the Bazel root, or a file it includes, calls `crate.from_cargo` of rules_rust's
crate_universe extension as a statement of its own, and the call names the project's
`Cargo.lock` or root `Cargo.toml` by a label written out as a string), and a line of the
root's `.bazelignore` covers the copy, so that Bazel reads no package there. Only the
banner is read. The same holds wherever the committed
copy is verified in its place: `vex` attests the crate, `repair` leaves the copy alone,
and a second `scan --mode vendored` reports it `already_vendored` without a download.
Every recorded file, a `BUILD.bazel` the crate ships among them, and every other
unrecorded file is compared as before (`vendor_inventory_mismatch`), as is a download
staged for a copy, and outside such a workspace nothing changes. In such a workspace the
commands that can write or remove a vendored crate also keep a line for
`.socket/vendor/cargo` in the root's `.bazelignore` (the warning `bazelignore_not_updated`
when they cannot); with that line commented out, or missing, cargo-bazel's file is drift
as it was. See
[Bazel workspaces: the build file in a vendored crate](../../docs/ecosystems.md#bazel-workspaces-the-build-file-in-a-vendored-crate).

`vendor --check --local-repo <path>` additionally checks existing suffixed Maven
jar/POM copies for conflicting bytes. A suffixed Maven or sbt pom is also read
against its upstream parent poms when `--local-repo` or a Maven or Gradle cache
Expand Down
51 changes: 30 additions & 21 deletions crates/socket-patch-cli/src/commands/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -54,47 +54,56 @@ pub(crate) fn project_state_in_scope(common: &crate::args::GlobalArgs) -> bool {
}

/// In a Bazel workspace the root's `.bazelignore` names the directories of
/// the project's patched Go module copies, so that Bazel and gazelle read
/// no package there (`socket_patch_core::bazel::ignore`). A command that can
/// write or remove such a copy calls this once, after the last step that
/// can change a copy or take one back and before it gives up its apply
/// lock. Nothing is done in a dry run or a `--global` run, and a run whose
/// `--ecosystems` leaves `golang` out only takes away the pair of a copy
/// that is gone. So does the prune pass of a scan, which comes here after
/// its scan has (`adds` false) and can only have removed a copy: a file
/// it cannot write is left to the next command's warning.
/// the project's patched Go module copies, and of the vendored crates a
/// crate hub builds, so that Bazel and gazelle read no package there
/// (`socket_patch_core::bazel::ignore`). A command that can write or
/// remove such a copy calls this once, after the last step that can change
/// a copy or take one back and before it gives up its apply lock. Nothing
/// is done in a dry run or a `--global` run, and a run whose `--ecosystems`
/// leaves `golang` or `cargo` out only takes away that ecosystem's pair of
/// a copy that is gone. So does the prune pass of a scan, which comes here
/// after its scan has (`adds` false) and can only have removed a copy: a
/// file it cannot write is left to the next command's warning.
///
/// A human run is told here that the file changed, or why it could not be;
/// the result is that warning again, for the command's envelope.
pub(crate) async fn sync_bazelignore(
common: &crate::args::GlobalArgs,
adds: bool,
) -> Vec<crate::json_envelope::RunWarning> {
use socket_patch_core::{bazel::ignore, crawlers::Ecosystem::Golang};
use socket_patch_core::bazel::ignore;
use socket_patch_core::crawlers::Ecosystem::{Cargo, Golang};
let mut warnings = Vec::new();
if common.dry_run || common.is_global() {
return warnings;
}
// The agent copies are those of `--cwd`, the vendored ones those of
// the manifest's project. A root both are under is named once.
// the manifest's project.
let mut projects = vec![common.cwd.clone()];
if common.manifest_project_is_foreign() {
projects.push(common.project_root());
}
let (loud, mut told) = (!common.json && !common.silent, Vec::new());
let [go, cargo] = [Golang, Cargo].map(|eco| adds && common.ecosystem_selected(eco));
for project in projects {
match ignore::sync(&project, adds && common.ecosystem_selected(Golang)).await {
Ok(Some(file)) if loud && !told.contains(&file) => {
let (verb, what) = match file.exists() {
true => (
"Updated",
"the lines that keep patched Go module copies under .socket out of \
Bazel's packages",
match ignore::sync(&project, go, cargo).await {
Ok(Some((file, copies))) if loud => {
// A root that both projects are under is named once for
// each kind of copy whose lines changed there.
let (shown, copies) = (file.display(), copies.join(" and "));
let line = match file.exists() {
true => format!(
"Updated {shown}: the lines that keep patched {copies} copies under \
.socket out of Bazel's packages"
),
false => ("Removed", "no patched Go module copy is left under .socket"),
false => {
format!("Removed {shown}: no patched {copies} copy is left under .socket")
}
};
println!("{verb} {}: {what}", file.display());
told.push(file);
if !told.contains(&line) {
println!("{line}");
told.push(line);
}
}
Err(detail) if adds => {
if loud {
Expand Down
Loading
Loading