@autotelic/joggle 0.4.1 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/JOGGLE.md CHANGED
@@ -483,6 +483,39 @@ writes the file as this run alone, which for a scoped run would truncate the
483
483
  ledger. `--allow-unjudged-baseline` is not the shortcut here: it ratifies the
484
484
  thousands nobody looked at, which is a commit nobody can defend.
485
485
 
486
+ A scoped accept is necessary, not sufficient. Cross-file rules only fire over the
487
+ whole repository, and a scoped run folds some findings into another rule at the same
488
+ site (the note counts them), so an identity CI fails on can be one this run never had.
489
+ Use the scoped accept to keep a stack moving and treat the full run as the authority:
490
+ when CI names an identity the scoped ledger lacks, accept that one and move on. Budget
491
+ one full judged run for the stack's head, not one per branch.
492
+
493
+ ### The cascade, not the conflicts
494
+
495
+ In a deep stack the conflicts are the easy half. Every one of them is a committed
496
+ artifact — a baseline, an answer ledger, a generated catalog — so
497
+ `git rebase -X theirs <parent>` clears the text and the artifacts are rebuilt
498
+ rather than merged.
499
+
500
+ The hard half is ordering. Accepting an identity, or rebuilding a catalog, adds a
501
+ commit to the parent, and that commit re-dirties every child above it: with 21
502
+ children, one fix is 21 re-dirties, and a cascade run between fixes runs once per
503
+ fix. A 22-branch migration spent five cascades that way, not because any rebase
504
+ was hard, but because each pass moved the parent again.
505
+
506
+ So the recipe is three passes, not one per branch:
507
+
508
+ 1. **Finish every accept and every rebuild first**, on every branch. Nothing is
509
+ rebased until the artifacts have stopped moving.
510
+ 2. **Then rebase bottom-up, once**, with `-X theirs` for the artifact conflicts.
511
+ 3. **Then push once**, bottom-up, with `--force-with-lease`.
512
+
513
+ `gh stack rebase` and the stacked-PR bots do exactly these three steps in one pass,
514
+ which is why they exist. An interrupted rebase leaves `rebase-merge/` or
515
+ `index.lock` behind and the next branch fails with "there is already a rebase-merge
516
+ directory": `git rebase --abort` clears it, and a scripted cascade belongs in a
517
+ `trap` that aborts rather than in a run that stops half-rebased.
518
+
486
519
  The baseline is by identity, not by line: rule, kept symbol and cluster
487
520
  membership. Code moves constantly, and a baseline that reports every edit as a
488
521
  new finding is a baseline nobody reads. A rename or a new member does change the
package/dist/check.js CHANGED
@@ -827,7 +827,13 @@ export const checkRepository = Effect.fn("joggle.check")(function* (options) {
827
827
  notes.push({
828
828
  ruleId: "joggle",
829
829
  reason: folded.folded +
830
- " finding(s) reported a site another rule already reported with more evidence, and were folded into it",
830
+ " finding(s) reported a site another rule already reported with more evidence, and were folded into it" +
831
+ // In a scoped run the fold is a ledger hazard, not just a readability note: the folded
832
+ // finding has no identity in this run, so an accept written from a scoped run can be
833
+ // missing exactly the identity a full run reports (and CI fails on).
834
+ (options.changedPaths === undefined
835
+ ? ""
836
+ : "; a folded finding's identity is not in this run, so an accept taken from a scoped run can miss one a full run reports"),
831
837
  });
832
838
  }
833
839
  // The workspace's own phases, alongside the per-rule timings. A run that says
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@autotelic/joggle",
3
- "version": "0.4.1",
3
+ "version": "0.4.3",
4
4
  "type": "module",
5
5
  "description": "Cross-file patterns and idioms for TypeScript — the layer above the linter and the typechecker.",
6
6
  "license": "MIT",