@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 +28 -0
- package/dist/check.js +23 -3
- package/dist/main.js +2 -0
- package/dist/run-cache.js +5 -1
- package/package.json +2 -2
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
|
-
"
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
+
"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.
|
|
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",
|