@autotelic/joggle 0.3.0 → 0.4.1

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
@@ -455,6 +455,34 @@ what a person reviewed, and one written over unjudged candidates ratifies what
455
455
  nobody looked at. `--allow-unjudged-baseline` is the explicit override; `jig
456
456
  init` passes it, because a ledger born on day one has no review to protect yet.
457
457
 
458
+ The reason an unjudged ledger is worse than an incomplete one: judgement is part of
459
+ the analysis, not a badge on it. Without a model key (`TYPESAFE_API_KEY` in the
460
+ run's environment) the same candidates are clustered and named from what the rules
461
+ could see alone, so one group can be one finding locally and three in CI. The two
462
+ runs are two analyses with two identity sets, and a ledger written by the unkeyed
463
+ one does not hold against the keyed one — locally green, red in CI, both "passing"
464
+ their own run. A CI ledger must be written by a run with the key; a local run
465
+ without one is for reading, and `jig baseline` refuses unverified findings for the
466
+ same reason. In a stack, seed a child from its parent instead of re-judging:
467
+ `git checkout <parent> -- .jig-baseline.json .joggle/answers.jsonl` reuses every
468
+ identity the branch inherits and asks only for the ones it adds.
469
+
470
+ In a stack the run that works is scoped, because a full-repository run has a
471
+ full-repository budget: at ~2.5k candidates a keyed run, a repository with 12k
472
+ unjudged candidates is a 25-minute run that still refuses to write.
473
+
474
+ ```sh
475
+ joggle check --types --no-replay --since origin/<parent> \
476
+ --baseline .joggle/baseline --update-baseline .joggle/baseline --merge-baseline
477
+ ```
478
+
479
+ A scoped run judges every candidate in the files it read, so its identities are
480
+ a pull request's worth and not the repository's. `--merge-baseline` keeps the
481
+ identities already accepted and adds those; without it, `--update-baseline`
482
+ writes the file as this run alone, which for a scoped run would truncate the
483
+ ledger. `--allow-unjudged-baseline` is not the shortcut here: it ratifies the
484
+ thousands nobody looked at, which is a commit nobody can defend.
485
+
458
486
  The baseline is by identity, not by line: rule, kept symbol and cluster
459
487
  membership. Code moves constantly, and a baseline that reports every edit as a
460
488
  new finding is a baseline nobody reads. A rename or a new member does change the
package/dist/check.js CHANGED
@@ -223,13 +223,33 @@ export const checkRepository = Effect.fn("joggle.check")(function* (options) {
223
223
  path: options.updateBaselinePath,
224
224
  operation: "baseline",
225
225
  cause: new Error(`refusing to write ${options.updateBaselinePath}: ${unjudged} candidate(s) were not judged. ` +
226
- "Pass --allow-unjudged-baseline to accept that, or judge the run first."),
226
+ "Judging needs a model key in this run's environment (TYPESAFE_API_KEY); without one, " +
227
+ "the same findings are named from what the rule could see alone, so a ledger written " +
228
+ "now would not match a judged run. Judge first (raise --max-tokens if the budget was " +
229
+ "the limit), or scope the run to the change: --since origin/<base> judges every " +
230
+ "candidate in the files it read, so --update-baseline <file> --merge-baseline grows " +
231
+ "the ledger by one pull request's identities instead of re-judging the repository. " +
232
+ "Pass --allow-unjudged-baseline only to accept the unjudged debt itself."),
227
233
  });
228
234
  }
229
- const identities = report.diagnostics
235
+ const target = baselinePath(path, options.updateBaselinePath);
236
+ const fresh = report.diagnostics
230
237
  .map((entry) => entry.identity)
231
238
  .filter((identity) => identity !== undefined);
232
- yield* writeBaseline(fs, path, baselinePath(path, options.updateBaselinePath), identities);
239
+ // A scoped run reports only what it judged in its own files; writing it alone would
240
+ // truncate the ledger to this pull request's identities. Merging keeps the accepted
241
+ // state and adds the run's — the hand-union an adopter had to do by hand.
242
+ const known = options.mergeBaseline === true ? yield* readBaseline(fs, path, target) : undefined;
243
+ const identities = known === undefined ? fresh : [...known, ...fresh];
244
+ yield* writeBaseline(fs, path, target, identities);
245
+ // An empty ledger is still a ledger: without this line a caller's merge step has to
246
+ // infer "nothing new" from an empty array, or worse, from a file it never looked for.
247
+ if (fresh.length === 0) {
248
+ notes.push({
249
+ ruleId: "joggle",
250
+ reason: `wrote 0 identities to ${target}: nothing new to accept`,
251
+ });
252
+ }
233
253
  }
234
254
  return notes.length === 0
235
255
  ? { ...report, diagnostics }
package/dist/main.js CHANGED
@@ -87,6 +87,7 @@ const checkCommand = Command.make("check", {
87
87
  prNumber: Flag.String("pr-number").pipe(Flag.withDescription("Scope to a specific pull request, by number or URL."), Flag.optional),
88
88
  baseline: Flag.String("baseline").pipe(Flag.withDescription("Report only findings not already accepted in this baseline file."), Flag.optional),
89
89
  updateBaseline: Flag.String("update-baseline").pipe(Flag.withDescription("Write the current findings to this file as the accepted baseline."), Flag.optional),
90
+ mergeBaseline: Flag.Boolean("merge-baseline").pipe(Flag.withDescription("With --update-baseline, keep the identities already in that file and add this run's. A scoped run (--since) judges all of its own files, so this grows a ledger by one change instead of replacing it."), Flag.withDefault(false)),
90
91
  allowUnjudgedBaseline: Flag.Boolean("allow-unjudged-baseline").pipe(Flag.withDescription("Write the baseline even though some candidates were not judged. A baseline is what was reviewed; this is the explicit way to accept that some of it was not."), Flag.withDefault(false)),
91
92
  cacheDir: Flag.String("cache-dir").pipe(Flag.withDescription("Where the answer cache lives: <cwd>/.joggle when it exists (an onboarded repository), otherwise the machine cache."), Flag.optional),
92
93
  cwd: Flag.String("cwd").pipe(Flag.withDescription("Project root to analyse (default: the current directory)."), Flag.optional),
@@ -163,6 +164,7 @@ const checkCommand = Command.make("check", {
163
164
  baselinePath: Option.getOrUndefined(config.baseline),
164
165
  updateBaselinePath: Option.getOrUndefined(config.updateBaseline),
165
166
  allowUnjudgedBaseline: config.allowUnjudgedBaseline,
167
+ mergeBaseline: config.mergeBaseline,
166
168
  }).pipe(Effect.provide(Layer.mergeAll(rulesLayer, decisionLayer({
167
169
  cacheDir,
168
170
  wireCacheDir: machineCache,
package/dist/run-cache.js CHANGED
@@ -108,7 +108,11 @@ export const writeBaseline = (fs, path, target, identities) => Effect.gen(functi
108
108
  if (target.endsWith(".json")) {
109
109
  const parent = path.dirname(target);
110
110
  yield* Effect.orElseSucceed(fs.makeDirectory(parent, { recursive: true }), () => undefined);
111
- const body = JSON.stringify({ version: policy.version, identities: [...identities].sort((left, right) => left.localeCompare(right)) }, null, 2);
111
+ // A ledger is a set: a merge that re-accepts an identity must not grow a duplicate row.
112
+ const body = JSON.stringify({
113
+ version: policy.version,
114
+ identities: [...new Set(identities)].sort((left, right) => left.localeCompare(right)),
115
+ }, null, 2);
112
116
  yield* Effect.orElseSucceed(fs.writeFileString(target, body), () => undefined);
113
117
  return;
114
118
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@autotelic/joggle",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
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",
@@ -64,7 +64,7 @@
64
64
  "oxc-parser": "0.150.0"
65
65
  },
66
66
  "devDependencies": {
67
- "@autotelic/plumb": "0.6.2",
67
+ "@autotelic/plumb": "0.6.3",
68
68
  "@effect/tsgo": "0.56.0",
69
69
  "@effect/vitest": "4.0.5",
70
70
  "@types/node": "24.13.5",