@autotelic/joggle 0.8.1 → 0.9.0

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.
@@ -300,7 +300,11 @@ const writeAll = (fs, path, dir, layout, entries) => Effect.gen(function* () {
300
300
  yield* removeQuietly(fs, file);
301
301
  }
302
302
  else {
303
- yield* fs.writeFileString(file, renderShard(entries.values())).pipe(Effect.orElseSucceed(() => undefined));
303
+ // Temp then rename: a killed run must leave a whole ledger or the previous one, never
304
+ // half a line. A truncated tail decodes as "skipped lines", which loses answers
305
+ // silently -- exactly the failure an interruption is most likely to cause.
306
+ yield* Effect.orElseSucceed(fs.writeFileString(file + ".tmp", renderShard(entries.values())), () => undefined);
307
+ yield* Effect.orElseSucceed(fs.rename(file + ".tmp", file), () => undefined);
304
308
  }
305
309
  const names = yield* fs.readDirectory(target).pipe(Effect.orElseSucceed(() => []));
306
310
  for (const name of names) {
@@ -319,9 +323,10 @@ const writeAll = (fs, path, dir, layout, entries) => Effect.gen(function* () {
319
323
  }
320
324
  yield* fs.makeDirectory(target, { recursive: true }).pipe(Effect.orElseSucceed(() => undefined));
321
325
  for (const [shard, list] of grouped) {
322
- yield* fs
323
- .writeFileString(path.join(target, shard + ".jsonl"), renderShard(list))
324
- .pipe(Effect.orElseSucceed(() => undefined));
326
+ // Same rule as the single layout: a shard appears whole or not at all.
327
+ const file = path.join(target, shard + ".jsonl");
328
+ yield* Effect.orElseSucceed(fs.writeFileString(file + ".tmp", renderShard(list)), () => undefined);
329
+ yield* Effect.orElseSucceed(fs.rename(file + ".tmp", file), () => undefined);
325
330
  }
326
331
  const names = yield* fs.readDirectory(target).pipe(Effect.orElseSucceed(() => []));
327
332
  for (const name of names) {
package/dist/check.js CHANGED
@@ -12,6 +12,7 @@ import { loadParses } from "./parsecache.js";
12
12
  import { answerStoreBytes } from "./answer-store.js";
13
13
  import { baselinePath, manifestOf, readBaseline, readStored, writeBaseline, writeStored, } from "./run-cache.js";
14
14
  import { policy } from "./policy.js";
15
+ import { VERSION } from "./version.js";
15
16
  import { Rules } from "./rules/index.js";
16
17
  import { foldSiteDuplicates, funnelNotes, rankDiagnostics } from "./report.js";
17
18
  import { countUnjudged, everyFile, finding, inGraphScope, outcome, } from "./rule.js";
@@ -246,8 +247,10 @@ export const checkRepository = Effect.fn("joggle.check")(function* (options) {
246
247
  cause: new Error(`refusing to write ${options.updateBaselinePath}: ${unjudged} candidate(s) were not judged. ` +
247
248
  "Judging needs a model key in this run's environment (TYPESAFE_API_KEY); without one, " +
248
249
  "the same findings are named from what the rule could see alone, so a ledger written " +
249
- "now would not match a judged run. Judge first (raise --max-tokens if the budget was " +
250
- "the limit), or run scoped (--since <base>) to see the change judged with a pull " +
250
+ "now would not match a judged run. Judge first; if the limit was the run's token " +
251
+ "budget, raise --max-tokens or decision.maxInputTokens. A per-rule candidate " +
252
+ "ceiling is not that knob, and the report names the rule whose ceiling it was. " +
253
+ "Or run scoped (--since <base>) to see the change judged with a pull " +
251
254
  "request's budget — a scoped run reports the gate's answer but cannot write the " +
252
255
  "ledger. Pass --allow-unjudged-baseline only to accept the unjudged debt itself."),
253
256
  });
@@ -532,6 +535,9 @@ export const checkRepository = Effect.fn("joggle.check")(function* (options) {
532
535
  estimated += cost;
533
536
  allowed.push(chunk);
534
537
  }
538
+ // The denominator of the progress line: every question this run will resolve, replayed or
539
+ // judged. Set here because the plans are built after the judgement layer exists.
540
+ yield* decisionStats.setTotal(allowed.reduce((sum, chunk) => sum + chunk.plans.length, 0));
535
541
  // A chunk that fails is CUT AND RETRIED, not abandoned.
536
542
  //
537
543
  // The provider occasionally returns a distribution that does not sum to 1, and
@@ -960,7 +966,7 @@ export const checkRepository = Effect.fn("joggle.check")(function* (options) {
960
966
  // next full run is compared against.
961
967
  if (!options.changed && options.changedPaths === undefined) {
962
968
  yield* writeStored(fs, path, runCache, {
963
- version: policy.version,
969
+ version: VERSION,
964
970
  manifest,
965
971
  sources: workspace.files.map((file) => ({
966
972
  path: file.path,
package/dist/decision.js CHANGED
@@ -4,6 +4,7 @@ import { Decision, DecisionModel } from "effect/ai";
4
4
  import { TypeSafeClient, TypeSafeDecisionModel, TypeSafeSchema } from "@effect/ai-typesafe";
5
5
  import { canonical } from "./canonical.js";
6
6
  import { policy } from "./policy.js";
7
+ import { VERSION } from "./version.js";
7
8
  import { make as makeAnswerStore } from "./answer-store.js";
8
9
  import { answerOf, memoize, PlanAnswers, storedOf } from "./plans.js";
9
10
  // The judged half of joggle, as Effect's own DecisionModel.
@@ -30,6 +31,40 @@ import { answerOf, memoize, PlanAnswers, storedOf } from "./plans.js";
30
31
  /** The run's judgement accounting, read once at the end of a run. */
31
32
  export class DecisionStats extends Context.Service()("@joggle/DecisionStats") {
32
33
  }
34
+ /** How often a long run says where it is. */
35
+ const PROGRESS_INTERVAL_MS = 10_000;
36
+ /** Tokens, compact enough to read in a moving line. */
37
+ const compactTokens = (value) => value >= 1_000_000
38
+ ? (value / 1_000_000).toFixed(1) + "M"
39
+ : value >= 1_000
40
+ ? Math.round(value / 1_000) + "k"
41
+ : String(value);
42
+ /** Elapsed time as a person reads it. */
43
+ const elapsedText = (milliseconds) => {
44
+ const seconds = Math.floor(milliseconds / 1000);
45
+ const minutes = Math.floor(seconds / 60);
46
+ return minutes > 0 ? minutes + "m" + String(seconds % 60).padStart(2, "0") + "s" : seconds + "s";
47
+ };
48
+ /**
49
+ * The progress line, as one testable string.
50
+ *
51
+ * Counts only, and the two units are named separately: "findings" and "findings no judgement
52
+ * reached" added into one number is the misread that made 7,787 unjudged candidates look like
53
+ * 5,315 pieces of debt. No denominator before the plans are known, because a wrong one is
54
+ * worse than none.
55
+ */
56
+ export const progressLine = (input) => "joggle: " +
57
+ String(input.requests) +
58
+ (input.total === undefined ? "" : "/" + String(input.total)) +
59
+ " candidate(s) resolved (" +
60
+ String(input.calls) +
61
+ " judged, " +
62
+ String(input.replayed) +
63
+ " replayed) · " +
64
+ compactTokens(input.inputTokens) +
65
+ (input.budget === undefined ? "" : "/" + compactTokens(input.budget)) +
66
+ " input tokens · " +
67
+ elapsedText(input.elapsedMs);
33
68
  const emptyStats = {
34
69
  requests: 0,
35
70
  replayed: 0,
@@ -117,13 +152,64 @@ export const layer = (options) => Layer.effectContext(Effect.gen(function* () {
117
152
  });
118
153
  const entries = yield* Ref.make(yield* load);
119
154
  const stats = yield* Ref.make(emptyStats);
155
+ const planned = yield* Ref.make(undefined);
156
+ const startedAt = Date.now();
157
+ let lastBeatAt = startedAt;
158
+ /*
159
+ * Where a long run says it is.
160
+ *
161
+ * A judged run can take many minutes, and before this it printed NOTHING until the
162
+ * report: stdout and stderr both zero bytes, indistinguishable from hung. The only
163
+ * observable signal was the answer cache growing, which is not something a person
164
+ * should have to tail.
165
+ *
166
+ * Counts only, on stderr, so every machine format on stdout stays clean; the two units
167
+ * are named separately because "findings" and "findings no judgement reached" being
168
+ * added into one number is exactly the misread this line exists to prevent.
169
+ */
170
+ const beat = Effect.gen(function* () {
171
+ const now = Date.now();
172
+ if (now - lastBeatAt < PROGRESS_INTERVAL_MS)
173
+ return;
174
+ lastBeatAt = now;
175
+ const current = yield* Ref.get(stats);
176
+ const total = yield* Ref.get(planned);
177
+ const elapsedMs = now - startedAt;
178
+ const budget = options.inputBudget ?? policy.decision.maxInputTokens;
179
+ process.stderr.write(progressLine({
180
+ requests: current.requests,
181
+ calls: current.calls,
182
+ replayed: current.replayed,
183
+ inputTokens: current.inputTokens,
184
+ total,
185
+ budget,
186
+ elapsedMs,
187
+ }) + "\n");
188
+ if (options.progressFile === undefined || options.readOnly === true)
189
+ return;
190
+ // Temp then rename: a poller reads a whole document or the previous one, never half.
191
+ const document = JSON.stringify({
192
+ phase: "judging",
193
+ candidatesTotal: total ?? null,
194
+ candidatesResolved: current.requests,
195
+ judged: current.calls,
196
+ replayed: current.replayed,
197
+ apiCalls: current.calls,
198
+ inputTokens: current.inputTokens,
199
+ inputBudget: budget,
200
+ elapsedMs,
201
+ updatedAt: new Date(now).toISOString(),
202
+ }, null, 2) + "\n";
203
+ yield* Effect.orElseSucceed(fs.writeFileString(options.progressFile + ".tmp", document), () => undefined);
204
+ yield* Effect.orElseSucceed(fs.rename(options.progressFile + ".tmp", options.progressFile), () => undefined);
205
+ });
120
206
  // Decisions run concurrently, so several calls can finish at once and each
121
207
  // one writes the whole cache. The permit keeps one writer in the file at a
122
208
  // time, so a full write cannot interleave with another.
123
209
  const writer = yield* Semaphore.make(1);
124
210
  const flush = writer.withPermits(1)(Effect.gen(function* () {
125
211
  const current = yield* Ref.get(entries);
126
- const body = JSON.stringify({ version: policy.version, entries: current }, null, 2);
212
+ const body = JSON.stringify({ version: VERSION, entries: current }, null, 2);
127
213
  yield* Effect.orElseSucceed(fs.makeDirectory(options.cacheDir, { recursive: true }), () => undefined);
128
214
  yield* Effect.orElseSucceed(fs.writeFileString(file, body), () => undefined);
129
215
  }));
@@ -167,7 +253,7 @@ export const layer = (options) => Layer.effectContext(Effect.gen(function* () {
167
253
  yield* Ref.update(entries, (current) => ({ ...current, [key]: response }));
168
254
  yield* flush;
169
255
  return response;
170
- }),
256
+ }).pipe(Effect.ensuring(beat)),
171
257
  });
172
258
  const providerModel = yield* TypeSafeDecisionModel.make({ model: policy.model }).pipe(Effect.provideService(TypeSafeClient.TypeSafeClient, client));
173
259
  // The per-question cache, above the wire.
@@ -211,5 +297,8 @@ export const layer = (options) => Layer.effectContext(Effect.gen(function* () {
211
297
  answers: decided.answers,
212
298
  }))),
213
299
  }));
214
- return Context.make(DecisionModel.DecisionModel, decisionModel).pipe(Context.add(DecisionStats, { read: Ref.get(stats) }), Context.add(PlanAnswers, planAnswers));
300
+ return Context.make(DecisionModel.DecisionModel, decisionModel).pipe(Context.add(DecisionStats, {
301
+ read: Ref.get(stats),
302
+ setTotal: (total) => Ref.set(planned, total),
303
+ }), Context.add(PlanAnswers, planAnswers));
215
304
  }));
package/dist/main.js CHANGED
@@ -13,6 +13,7 @@ import { loadConfig, isEnabled, severityFor } from "./config.js";
13
13
  import { layer as gitLayer, Service as Git } from "./git.js";
14
14
  import { loadPlugins, withDefaults } from "./plugins.js";
15
15
  import { policy } from "./policy.js";
16
+ import { VERSION } from "./version.js";
16
17
  import { exitCodeFor, render } from "./report.js";
17
18
  import { applyDeclarationTypes, isRecord, loadWorkspace } from "./workspace.js";
18
19
  import { answerPlansRaw, chunkPlans } from "./plans.js";
@@ -184,6 +185,10 @@ const checkCommand = Command.make("check", {
184
185
  }).pipe(Effect.provide(Layer.mergeAll(rulesLayer, decisionLayer({
185
186
  cacheDir,
186
187
  wireCacheDir: machineCache,
188
+ // Machine-local, pollable, and never part of the committed ledger: it describes
189
+ // THIS run. A long judged run used to print nothing at all until the report.
190
+ progressFile: path.join(machineCache, "progress.json"),
191
+ inputBudget: Option.getOrUndefined(config.maxTokens) ?? effective.decision?.maxInputTokens,
187
192
  offline: config.offline,
188
193
  apiKey,
189
194
  layout: effective.cache?.layout,
@@ -691,7 +696,7 @@ const cli = Command.make("joggle").pipe(Command.withDescription("Cross-file patt
691
696
  { command: "joggle rules", description: "See what is enforced here." },
692
697
  ]), Command.withSubcommands([checkCommand, askCommand, rules, calibrateCommand, cacheCommand, mergeAnswers]));
693
698
  const services = Layer.mergeAll(NodeServices.layer, FetchHttpClient.layer, builtIn);
694
- const program = Command.run(cli, { version: policy.version }).pipe(Effect.provide(services));
699
+ const program = Command.run(cli, { version: VERSION }).pipe(Effect.provide(services));
695
700
  /*
696
701
  * Never fail silently. A typed failure, an interruption and a defect all have
697
702
  * to reach stderr with enough detail to act on. This is a CI gate, and a gate
package/dist/policy.js CHANGED
@@ -14,8 +14,6 @@
14
14
  * candidates is the code's.
15
15
  */
16
16
  export const policy = {
17
- /** Surfaced by `joggle --version`. */
18
- version: "0.1.0",
19
17
  /** The System One model every rule judges with. */
20
18
  model: "jev-latest",
21
19
  /**
@@ -465,7 +463,13 @@ export const policy = {
465
463
  * repository rather than a budget anybody should reach.
466
464
  */
467
465
  docMatchesCode: {
468
- maxDeclarations: 400,
466
+ /**
467
+ * Measured, not guessed: this workspace has 679 documented declarations, and at 400 the
468
+ * overflow was 279 candidates that no run could ever judge — the slice is deterministic,
469
+ * so a second run asks the same 400 again. A baseline that refuses to be written while
470
+ * candidates are unjudged cannot exist for a repository this size at that ceiling.
471
+ */
472
+ maxDeclarations: 1000,
469
473
  /** Tokens below which a declaration has nothing for a doc to describe. */
470
474
  minTokens: 40,
471
475
  },
@@ -650,8 +654,15 @@ export const policy = {
650
654
  * one run may judge, and how much evidence one candidate may carry.
651
655
  */
652
656
  strata: {
653
- /** Candidates one strata rule may judge in a run. */
654
- maxCandidates: 200,
657
+ /**
658
+ * Candidates one strata rule may judge in a run.
659
+ *
660
+ * 200 was a ceiling against a pathological repository, and this ordinary one reached it:
661
+ * `declared-staleness` had 538 projections (338 over) and `invariant-has-a-reconciler`
662
+ * 289 checks (89 over). The slice is deterministic, so the overflow was permanent rather
663
+ * than deferred to a later run.
664
+ */
665
+ maxCandidates: 1000,
655
666
  /** Fields two structures must share before their overlap is worth a question. */
656
667
  minSharedFields: 3,
657
668
  /** Tokens a function needs before a table read can be a check rather than a getter. */
@@ -111,7 +111,9 @@ export const singlePath = {
111
111
  ]),
112
112
  };
113
113
  }
114
- const budget = policy.evidence.maxMembers * 16;
114
+ // 16 members' worth of sites was 192 on this workspace, which has 408 string sites --
115
+ // 216 candidates sliced off every run. 64 members' worth (768) fits the measured tree.
116
+ const budget = policy.evidence.maxMembers * 64;
115
117
  const judged = candidates.slice(0, budget);
116
118
  const overBudget = candidates.slice(budget).map((candidate) => ({
117
119
  ruleId: RULE_ID,
@@ -90,7 +90,9 @@ export const typesOverLogic = {
90
90
  ]),
91
91
  };
92
92
  }
93
- const budget = policy.evidence.maxMembers * 16;
93
+ // The same measured ceiling as `single-path`: a 12-member evidence window times 16 was
94
+ // 192 guards, and a real workspace exceeds it. 64 keeps the bound without truncating.
95
+ const budget = policy.evidence.maxMembers * 64;
94
96
  const judged = candidates.slice(0, budget);
95
97
  const overBudget = candidates.slice(budget).map((candidate) => ({
96
98
  ruleId: RULE_ID,
package/dist/run-cache.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { Effect, FileSystem, Path, Result, Schema, SchemaParser } from "effect";
2
2
  import { policy } from "./policy.js";
3
+ import { VERSION } from "./version.js";
3
4
  import { shortHash } from "./state.js";
4
5
  import { Baseline, StoredRun } from "./schema.js";
5
6
  /**
@@ -110,7 +111,7 @@ export const writeBaseline = (fs, path, target, identities) => Effect.gen(functi
110
111
  yield* Effect.orElseSucceed(fs.makeDirectory(parent, { recursive: true }), () => undefined);
111
112
  // A ledger is a set: a merge that re-accepts an identity must not grow a duplicate row.
112
113
  const body = JSON.stringify({
113
- version: policy.version,
114
+ version: VERSION,
114
115
  identities: [...new Set(identities)].sort((left, right) => left.localeCompare(right)),
115
116
  }, null, 2);
116
117
  yield* Effect.orElseSucceed(fs.writeFileString(target, body), () => undefined);
@@ -0,0 +1,23 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { fileURLToPath } from "node:url";
3
+ import { Result, Schema, SchemaParser } from "effect";
4
+ /*
5
+ * The version this build actually is.
6
+ *
7
+ * `policy.version` held a hand-typed "0.1.0" while the package reached 0.8.1, and
8
+ * `joggle --version` printed it. A consumer comparing versions to prove a fix arrived read
9
+ * a number that never moved; so did every cache document that stamped it. The manifest is
10
+ * the one place a release writes, so the tool reads it instead of repeating it.
11
+ *
12
+ * Two path shapes resolve to the same file: `dist/version.js` and `src/version.ts` both sit
13
+ * one directory below the package root. A build that cannot read its own manifest reports
14
+ * 0.0.0 rather than failing, because the version is a label on a report, not an input to it.
15
+ */
16
+ const Packaged = Schema.Struct({ version: Schema.String });
17
+ const readVersion = () => {
18
+ const file = fileURLToPath(new URL("../package.json", import.meta.url));
19
+ const text = Result.getOrElse(Result.try(() => readFileSync(file, "utf8")), () => "");
20
+ const decoded = Result.getOrUndefined(SchemaParser.decodeResult(Schema.fromJsonString(Packaged))(text));
21
+ return decoded?.version ?? "0.0.0";
22
+ };
23
+ export const VERSION = readVersion();
@@ -0,0 +1,18 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { Result, Schema, SchemaParser } from "effect";
3
+ import { describe, expect, it } from "vitest";
4
+ import { VERSION } from "./version.js";
5
+ /*
6
+ * The label a consumer compares against npm.
7
+ *
8
+ * It was a constant, and the constant stopped moving while the package kept releasing. The
9
+ * claim worth pinning is not the string — it is that the string is the manifest's.
10
+ */
11
+ describe("VERSION", () => {
12
+ it("is the version in the package manifest", () => {
13
+ const Packaged = Schema.Struct({ version: Schema.String });
14
+ const manifest = Result.getOrThrow(SchemaParser.decodeResult(Schema.fromJsonString(Packaged))(readFileSync(new URL("../package.json", import.meta.url), "utf8")));
15
+ expect(VERSION).toBe(manifest.version);
16
+ expect(VERSION).not.toBe("0.0.0");
17
+ });
18
+ });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@autotelic/joggle",
3
- "version": "0.8.1",
3
+ "version": "0.9.0",
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",