@biffo/cli 0.316.3 → 0.317.1

package/_skeletons/plugin-template/scripts/error_branch_coverage.py

@@ -204,7 +204,57 @@ class Branch:
     label: str
 
     def key(self) -> str:
-        return f"{self.path}:{self.kind}:{self.label}"
+        """The ratchet's identity for this branch. Must not collide (#2026).
+
+        Two textually-identical branches in one file — two different
+        functions each with a bare `except ValueError:` — are common: the
+        vocabulary of exception type names is finite and heavily reused, and
+        `label` for a `fallback` is truncated to 50 chars on top of that. A
+        key of `path:kind:label` alone collapses both onto one entry, so a
+        second, genuinely new, never-executed branch sharing a label with an
+        already-baselined one in the same file was silently absorbed into
+        that entry: it was printed (the analyser saw it) but never marked
+        NEW, and `--check` exited 0 over an unverified branch nobody had
+        looked at. Confirmed live: a second unexecuted `except ValueError`
+        added in the same file as an already-baselined one produced no NEW
+        marker and exit 0, while a distinctly-labeled addition in the same
+        run was correctly flagged — isolating the cause to the missing
+        position, not to anything else about the change.
+
+        `line` is included to close that gap, chosen deliberately over an
+        occurrence ordinal among same-labeled branches in the file (e.g.
+        "2nd `except ValueError` in this file"). Both carry a cost and
+        neither is free:
+
+        - **Line number** (chosen): a new branch cannot collide with an
+          existing key at all, short of landing on the exact line number a
+          deleted branch used to occupy — vanishingly unlikely, since that
+          requires a line-count-preserving edit that puts an unrelated new
+          branch at that exact spot. The cost is churn: an unrelated edit
+          that shifts a baselined branch down a few lines (an import added
+          above it, a docstring reflowed) makes its key change too, so it
+          reads as NEW and the gate cries wolf until `--write` re-accepts
+          it. `unexecuted()`'s own docstring already documents that this
+          script's line-based coverage join is shift-sensitive in exactly
+          this way, so this does not introduce a new fragility, only extends
+          an existing one from the coverage join into the baseline key.
+        - **Occurrence ordinal** (rejected): stable under a line shift
+          elsewhere in the file, but ambiguous under reordering. If a
+          baselined branch is removed and an unrelated new same-labeled
+          branch appears earlier in the file than a survivor, the survivor's
+          ordinal shifts onto the new branch's — reproducing this exact
+          issue by a different route, because an ordinal is still a
+          position, just a fragile relative one instead of a stable
+          absolute one.
+
+        Level reached: 3 (fail-closed) rather than 4 (detect-only) — a
+        distinct line number for every distinct AST node means a genuinely
+        new branch cannot be absorbed into an existing entry at all, not
+        merely flagged more often. Changing this format means every
+        instance's committed baseline must be regenerated; see the PR that
+        introduced this comment for the exact command.
+        """
+        return f"{self.path}:{self.line}:{self.kind}:{self.label}"
 
 
 def _handler_label(node: ast.ExceptHandler) -> str:

package/_skeletons/sibling-template/scripts/error_branch_coverage.py

@@ -204,7 +204,57 @@ class Branch:
     label: str
 
     def key(self) -> str:
-        return f"{self.path}:{self.kind}:{self.label}"
+        """The ratchet's identity for this branch. Must not collide (#2026).
+
+        Two textually-identical branches in one file — two different
+        functions each with a bare `except ValueError:` — are common: the
+        vocabulary of exception type names is finite and heavily reused, and
+        `label` for a `fallback` is truncated to 50 chars on top of that. A
+        key of `path:kind:label` alone collapses both onto one entry, so a
+        second, genuinely new, never-executed branch sharing a label with an
+        already-baselined one in the same file was silently absorbed into
+        that entry: it was printed (the analyser saw it) but never marked
+        NEW, and `--check` exited 0 over an unverified branch nobody had
+        looked at. Confirmed live: a second unexecuted `except ValueError`
+        added in the same file as an already-baselined one produced no NEW
+        marker and exit 0, while a distinctly-labeled addition in the same
+        run was correctly flagged — isolating the cause to the missing
+        position, not to anything else about the change.
+
+        `line` is included to close that gap, chosen deliberately over an
+        occurrence ordinal among same-labeled branches in the file (e.g.
+        "2nd `except ValueError` in this file"). Both carry a cost and
+        neither is free:
+
+        - **Line number** (chosen): a new branch cannot collide with an
+          existing key at all, short of landing on the exact line number a
+          deleted branch used to occupy — vanishingly unlikely, since that
+          requires a line-count-preserving edit that puts an unrelated new
+          branch at that exact spot. The cost is churn: an unrelated edit
+          that shifts a baselined branch down a few lines (an import added
+          above it, a docstring reflowed) makes its key change too, so it
+          reads as NEW and the gate cries wolf until `--write` re-accepts
+          it. `unexecuted()`'s own docstring already documents that this
+          script's line-based coverage join is shift-sensitive in exactly
+          this way, so this does not introduce a new fragility, only extends
+          an existing one from the coverage join into the baseline key.
+        - **Occurrence ordinal** (rejected): stable under a line shift
+          elsewhere in the file, but ambiguous under reordering. If a
+          baselined branch is removed and an unrelated new same-labeled
+          branch appears earlier in the file than a survivor, the survivor's
+          ordinal shifts onto the new branch's — reproducing this exact
+          issue by a different route, because an ordinal is still a
+          position, just a fragile relative one instead of a stable
+          absolute one.
+
+        Level reached: 3 (fail-closed) rather than 4 (detect-only) — a
+        distinct line number for every distinct AST node means a genuinely
+        new branch cannot be absorbed into an existing entry at all, not
+        merely flagged more often. Changing this format means every
+        instance's committed baseline must be regenerated; see the PR that
+        introduced this comment for the exact command.
+        """
+        return f"{self.path}:{self.line}:{self.kind}:{self.label}"
 
 
 def _handler_label(node: ast.ExceptHandler) -> str:

package/dist/index.js

@@ -10330,7 +10330,8 @@ async function checkViaProvenance(name, record, repoUrl, git) {
       name,
       status: "cannot-tell",
       method: "unresolvable",
-      detail: `could not reach ${repoUrl} (network or authentication failure)`
+      detail: `could not reach ${repoUrl} (network or authentication failure)`,
+      source: repoUrl
     };
   }
   if (remoteHeadSha === record.sha) {
@@ -10338,7 +10339,8 @@ async function checkViaProvenance(name, record, repoUrl, git) {
       name,
       status: "up-to-date",
       method: "provenance",
-      detail: `matches ${repoUrl}'s default branch (${shortSha(remoteHeadSha)})`
+      detail: `matches ${repoUrl}'s default branch (${shortSha(remoteHeadSha)})`,
+      source: repoUrl
     };
   }
   let clone;
@@ -10349,7 +10351,8 @@ async function checkViaProvenance(name, record, repoUrl, git) {
       name,
       status: "cannot-tell",
       method: "unresolvable",
-      detail: `could not clone ${repoUrl} to count commits behind (network or authentication failure)`
+      detail: `could not clone ${repoUrl} to count commits behind (network or authentication failure)`,
+      source: repoUrl
     };
   }
   try {
@@ -10359,7 +10362,8 @@ async function checkViaProvenance(name, record, repoUrl, git) {
         name,
         status: "cannot-tell",
         method: "unresolvable",
-        detail: `recorded commit ${shortSha(record.sha)} was not found in ${repoUrl}'s history (rebased or force-pushed?) \u2014 cannot count commits behind`
+        detail: `recorded commit ${shortSha(record.sha)} was not found in ${repoUrl}'s history (rebased or force-pushed?) \u2014 cannot count commits behind`,
+        source: repoUrl
       };
     }
     if (commitsBehind === 0) {
@@ -10367,7 +10371,8 @@ async function checkViaProvenance(name, record, repoUrl, git) {
         name,
         status: "up-to-date",
         method: "provenance",
-        detail: `matches ${repoUrl}'s default branch (${shortSha(remoteHeadSha)})`
+        detail: `matches ${repoUrl}'s default branch (${shortSha(remoteHeadSha)})`,
+        source: repoUrl
       };
     }
     return {
@@ -10375,7 +10380,8 @@ async function checkViaProvenance(name, record, repoUrl, git) {
       status: "behind",
       commitsBehind,
       method: "provenance",
-      detail: `${commitsBehind} commit(s) behind ${repoUrl}'s default branch`
+      detail: `${commitsBehind} commit(s) behind ${repoUrl}'s default branch`,
+      source: repoUrl
     };
   } finally {
     git.cleanup(clone);
@@ -10392,7 +10398,8 @@ async function checkViaContentDiff(name, pluginDir2, sourceDir, opts, git) {
         name,
         status: "cannot-tell",
         method: "unresolvable",
-        detail: `could not clone ${sourceDir} for a content comparison (network or authentication failure)`
+        detail: `could not clone ${sourceDir} for a content comparison (network or authentication failure)`,
+        source: sourceDir
       };
     }
     effectiveSourceDir = cloneDir;
@@ -10406,7 +10413,8 @@ async function checkViaContentDiff(name, pluginDir2, sourceDir, opts, git) {
         status: "up-to-date",
         method: "content-diff",
         filesDiffering: 0,
-        detail: `byte-identical to ${originDescription} (no provenance recorded, so an exact commit could not be named)`
+        detail: `byte-identical to ${originDescription} (no provenance recorded, so an exact commit could not be named)`,
+        source: originDescription
       };
     }
     return {
@@ -10414,7 +10422,8 @@ async function checkViaContentDiff(name, pluginDir2, sourceDir, opts, git) {
       status: "behind",
       filesDiffering,
       method: "content-diff",
-      detail: `${filesDiffering} file(s) differ from ${originDescription} (no provenance recorded, so an exact commit count could not be determined)`
+      detail: `${filesDiffering} file(s) differ from ${originDescription} (no provenance recorded, so an exact commit count could not be determined)`,
+      source: originDescription
     };
   } finally {
     if (cloneDir) git.cleanup(cloneDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.316.3",
+  "version": "0.317.1",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",