@autotelic/joggle 0.0.0-stage → 0.1.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.
Files changed (101) hide show
  1. package/JOGGLE.md +634 -0
  2. package/LICENSE +21 -0
  3. package/README.md +88 -2
  4. package/bin/joggle.js +6 -0
  5. package/dist/answer-store.js +305 -0
  6. package/dist/architecture.js +190 -0
  7. package/dist/ask.js +184 -0
  8. package/dist/astro.js +75 -0
  9. package/dist/atoms.js +76 -0
  10. package/dist/bundles.js +156 -0
  11. package/dist/calibration.js +60 -0
  12. package/dist/candidates.js +561 -0
  13. package/dist/canonical.js +24 -0
  14. package/dist/cascade.js +98 -0
  15. package/dist/check.js +854 -0
  16. package/dist/cluster.js +69 -0
  17. package/dist/config.js +195 -0
  18. package/dist/content-mappers.js +83 -0
  19. package/dist/decision.js +203 -0
  20. package/dist/fingerprint.js +61 -0
  21. package/dist/git.js +127 -0
  22. package/dist/gitignore.js +65 -0
  23. package/dist/glob.js +51 -0
  24. package/dist/imports.js +153 -0
  25. package/dist/jsonc.js +95 -0
  26. package/dist/main.js +630 -0
  27. package/dist/manifest.js +42 -0
  28. package/dist/meta.js +170 -0
  29. package/dist/moves.js +47 -0
  30. package/dist/operation.js +133 -0
  31. package/dist/parsecache.js +264 -0
  32. package/dist/plans.js +425 -0
  33. package/dist/plugin.js +71 -0
  34. package/dist/plugins.js +136 -0
  35. package/dist/policy.js +676 -0
  36. package/dist/presets/composition.js +32 -0
  37. package/dist/report.js +474 -0
  38. package/dist/reporting.js +132 -0
  39. package/dist/result.js +28 -0
  40. package/dist/roles.js +303 -0
  41. package/dist/rule.js +194 -0
  42. package/dist/rules/append-only-honoured.js +190 -0
  43. package/dist/rules/bundle-conformance.js +245 -0
  44. package/dist/rules/call-pattern.js +209 -0
  45. package/dist/rules/cluster-verdict.js +700 -0
  46. package/dist/rules/compose-types.js +250 -0
  47. package/dist/rules/data-error-as-outage.js +482 -0
  48. package/dist/rules/declared-staleness.js +242 -0
  49. package/dist/rules/dependency-fit.js +297 -0
  50. package/dist/rules/deviation-has-a-shape.js +225 -0
  51. package/dist/rules/doc-matches-code.js +191 -0
  52. package/dist/rules/duplicate-call-run.js +240 -0
  53. package/dist/rules/duplicate-implementation.js +89 -0
  54. package/dist/rules/duplicate-meaning.js +130 -0
  55. package/dist/rules/fact-or-derivation.js +202 -0
  56. package/dist/rules/field-type-drift.js +373 -0
  57. package/dist/rules/generic-carries-a-caller.js +198 -0
  58. package/dist/rules/hoist-to-domain.js +288 -0
  59. package/dist/rules/import-architecture.js +393 -0
  60. package/dist/rules/index.js +105 -0
  61. package/dist/rules/inferred-over-recorded.js +214 -0
  62. package/dist/rules/intent-drift.js +286 -0
  63. package/dist/rules/invariant-has-a-reconciler.js +190 -0
  64. package/dist/rules/language-drift.js +234 -0
  65. package/dist/rules/meaning-switched-by-flag.js +189 -0
  66. package/dist/rules/module-direction.js +231 -0
  67. package/dist/rules/name-as-address.js +216 -0
  68. package/dist/rules/name-the-primitive.js +203 -0
  69. package/dist/rules/naming-drift.js +218 -0
  70. package/dist/rules/nullability-drift.js +220 -0
  71. package/dist/rules/object-shape.js +280 -0
  72. package/dist/rules/one-concept-one-type.js +243 -0
  73. package/dist/rules/page-needs-composition.js +227 -0
  74. package/dist/rules/reimplemented-primitive.js +283 -0
  75. package/dist/rules/reversal.js +264 -0
  76. package/dist/rules/rule-judgment.js +252 -0
  77. package/dist/rules/schema-excludes-domain-value.js +190 -0
  78. package/dist/rules/shallow-module.js +204 -0
  79. package/dist/rules/single-path.js +237 -0
  80. package/dist/rules/structural-collapse.js +198 -0
  81. package/dist/rules/temporal-coupling.js +205 -0
  82. package/dist/rules/types-over-logic.js +198 -0
  83. package/dist/rules/unaccounted-drop.js +190 -0
  84. package/dist/rules/unbounded-default-read.js +227 -0
  85. package/dist/run-cache.js +132 -0
  86. package/dist/schema.js +285 -0
  87. package/dist/similarity.js +119 -0
  88. package/dist/source.js +30 -0
  89. package/dist/sql.js +34 -0
  90. package/dist/stages.js +39 -0
  91. package/dist/state.js +65 -0
  92. package/dist/testing.js +131 -0
  93. package/dist/tsconfig-scope.js +32 -0
  94. package/dist/tsgo.js +127 -0
  95. package/dist/typefacts.js +455 -0
  96. package/dist/typetrace.js +283 -0
  97. package/dist/verdict.js +65 -0
  98. package/dist/vocabulary.js +365 -0
  99. package/dist/workspace.js +1963 -0
  100. package/extensions/joggle.ts +454 -0
  101. package/package.json +85 -3
package/dist/main.js ADDED
@@ -0,0 +1,630 @@
1
+ import { Cause, Config, Effect, Exit, FileSystem, Layer, Option, Path, Predicate, Result, Runtime } from "effect";
2
+ import { Argument, Command, Flag } from "effect/cli";
3
+ import { Decision, DecisionModel } from "effect/ai";
4
+ import * as FetchHttpClient from "effect/http/FetchHttpClient";
5
+ import { NodeRuntime, NodeServices } from "@effect/platform-node";
6
+ import { checkRepository } from "./check.js";
7
+ import { layer as decisionLayer } from "./decision.js";
8
+ import { make as makeAnswerStore, mergeShardText, prune as pruneAnswers } from "./answer-store.js";
9
+ import { ask } from "./ask.js";
10
+ import { cacheDirFor, runCacheDirFor, shortHash } from "./state.js";
11
+ import { canonical } from "./canonical.js";
12
+ import { loadConfig, isEnabled, severityFor } from "./config.js";
13
+ import { layer as gitLayer, Service as Git } from "./git.js";
14
+ import { loadPlugins, withDefaults } from "./plugins.js";
15
+ import { policy } from "./policy.js";
16
+ import { exitCodeFor, render } from "./report.js";
17
+ import { applyDeclarationTypes, isRecord, loadWorkspace } from "./workspace.js";
18
+ import { answerPlansRaw, chunkPlans } from "./plans.js";
19
+ import { layer as atomsLayer } from "./atoms.js";
20
+ import { summarizeCalibration } from "./calibration.js";
21
+ import { verdictOf } from "./verdict.js";
22
+ import { everyFile, qualityOf } from "./rule.js";
23
+ import { allRules, builtIn, Rules } from "./rules/index.js";
24
+ import { layerFromConfig as tsgoLayer } from "./tsgo.js";
25
+ import { emptyTypeIndex, loadTypeFacts } from "./typetrace.js";
26
+ import { indexOfNodeTypes, loadDeclarationTypes, typesAtPositions, } from "./typefacts.js";
27
+ import { manifestOf } from "./run-cache.js";
28
+ import { sourceFingerprint } from "./fingerprint.js";
29
+ /**
30
+ * One report, written and then WAITED for.
31
+ *
32
+ * It used to be `Console.log`, which queues the write and returns. To a pipe --
33
+ * how a caller, CI and `jig` all read this -- stdout is asynchronous, so the
34
+ * bytes leave only once the reader has taken them; this process's own teardown
35
+ * then ends it with `process.exit`, which discards whatever is still queued. A
36
+ * report past the pipe's 64 KiB buffer was therefore cut off mid-sentence, and
37
+ * a JSON report cut off mid-sentence is not a clean run: the reader gets an
38
+ * unparseable engine and loses everything the run found. Measured against this
39
+ * repository, whose report is past the buffer: piped, `check --format json`
40
+ * delivered 65536 bytes and failed to parse; with the callback, all 97020
41
+ * arrive. The newline is explicit so the output stays byte-identical.
42
+ */
43
+ const write = (text) => Effect.callback((resume) => {
44
+ process.stdout.write(text.endsWith("\n") ? text : `${text}\n`, () => resume(Effect.void));
45
+ });
46
+ /**
47
+ * The repository's rule set: its config, its plugins, and the layer the run
48
+ * reads.
49
+ *
50
+ * One function so `check` and `rules` cannot disagree about what is enforced.
51
+ * They did: `rules` listed the built-ins while `check` ran the configured
52
+ * preset, which is the one output a reader uses to answer "what is enforced".
53
+ */
54
+ const ruleSetFor = (cwd, configFile) => Effect.gen(function* () {
55
+ const path = yield* Path.Path;
56
+ const settings = yield* loadConfig(path.resolve(cwd, configFile ?? "joggle.config.json"));
57
+ const loaded = yield* loadPlugins([...(settings.presets ?? []), ...(settings.plugins ?? [])], cwd);
58
+ // A preset's severities and scoping sit under the repository's own, per rule:
59
+ // enabling twenty opinions and then turning one off should not mean
60
+ // restating the other nineteen.
61
+ const effective = withDefaults({ defaults: loaded.config, own: settings });
62
+ // The repository's rules join the built-in ones here, once, so the run
63
+ // itself reads one rule set from the context and never sees a plugin.
64
+ return {
65
+ settings,
66
+ loaded,
67
+ effective,
68
+ rules: [...allRules, ...loaded.rules],
69
+ layer: Layer.succeed(Rules, [...allRules, ...loaded.rules]),
70
+ };
71
+ });
72
+ const checkCommand = Command.make("check", {
73
+ paths: Argument.String("paths").pipe(Argument.withDescription("Files or directories to analyse. Default: whatever tsgo says the project is."), Argument.variadic()),
74
+ rule: Flag.String("rule").pipe(Flag.withDescription("Only run these rule ids, comma-separated."), Flag.optional),
75
+ format: Flag.Literals("format", ["text", "stylish", "unix", "json", "github"]).pipe(Flag.withDescription("How to render the report."), Flag.withDefault("text")),
76
+ maxWarnings: Flag.Int("max-warnings").pipe(Flag.withDescription("Exit non-zero when warnings exceed this count (-1 disables)."), Flag.withDefault(-1)),
77
+ typecheck: Flag.Boolean("typecheck").pipe(Flag.withDescription("Include tsgo's own diagnostics as joggle/typecheck."), Flag.withDefault(false)),
78
+ types: Flag.Boolean("types").pipe(Flag.withDescription("Resolve declaration types through tsgo's trace (enables type-aware rules)."), Flag.withDefault(false)),
79
+ maxTokens: Flag.Int("max-tokens").pipe(Flag.withDescription("Input-token budget for judgement in this run."), Flag.withDefault(policy.decision.maxInputTokens)),
80
+ offline: Flag.Boolean("offline").pipe(Flag.withDescription("Answer only from the committed judgement cache; never call the model."), Flag.withDefault(false)),
81
+ noTsgo: Flag.Boolean("no-tsgo").pipe(Flag.withDescription("Never invoke tsgo; walk the paths on disk instead."), Flag.withDefault(false)),
82
+ runExternalCode: Flag.Boolean("run-external-code").pipe(Flag.withDescription("Allow tsc to execute content-mapper packages declared in tsconfig (TypeScript 7.1+). Off by default: a mapper is arbitrary code."), Flag.withDefault(false)),
83
+ noReplay: Flag.Boolean("no-replay").pipe(Flag.withDescription("Do not reuse the stored run when nothing changed."), Flag.withDefault(false)),
84
+ changed: Flag.Boolean("changed").pipe(Flag.withDescription("Scope to files changed since the stored run (machine-local)."), Flag.withDefault(false)),
85
+ since: Flag.String("since").pipe(Flag.withDescription("Scope to files changed since a git revision (for example origin/main)."), Flag.optional),
86
+ pr: Flag.Boolean("pr").pipe(Flag.withDescription("Scope to the pull request for the current branch."), Flag.withDefault(false)),
87
+ prNumber: Flag.String("pr-number").pipe(Flag.withDescription("Scope to a specific pull request, by number or URL."), Flag.optional),
88
+ baseline: Flag.String("baseline").pipe(Flag.withDescription("Report only findings not already accepted in this baseline file."), Flag.optional),
89
+ updateBaseline: Flag.String("update-baseline").pipe(Flag.withDescription("Write the current findings to this file as the accepted baseline."), Flag.optional),
90
+ 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),
91
+ cwd: Flag.String("cwd").pipe(Flag.withDescription("Project root to analyse (default: the current directory)."), Flag.optional),
92
+ config: Flag.String("config").pipe(Flag.withDescription("Config file, relative to the project root (default joggle.config.json)."), Flag.optional),
93
+ }, (config) => Effect.gen(function* () {
94
+ const path = yield* Path.Path;
95
+ // Absolute at the boundary. Everything downstream compares paths -- tsgo's
96
+ // file list against the root, git's changed files against the workspace --
97
+ // and a relative root makes those comparisons fail quietly.
98
+ const cwd = path.resolve(Option.getOrUndefined(config.cwd) ?? process.cwd());
99
+ const cacheDir = yield* cacheDirFor(cwd, Option.getOrUndefined(config.cacheDir));
100
+ const apiKey = yield* Config.option(Config.String("TYPESAFE_API_KEY"));
101
+ const ruleFlag = Option.getOrUndefined(config.rule);
102
+ const rules = ruleFlag === undefined
103
+ ? undefined
104
+ : ruleFlag
105
+ .split(",")
106
+ .map((id) => id.trim())
107
+ .filter((id) => id.length > 0);
108
+ // Relative to the analysed root, so a config travels with the repository it
109
+ // describes rather than with the shell that invoked the tool.
110
+ const ruleSet = yield* ruleSetFor(cwd, Option.getOrUndefined(config.config));
111
+ const { loaded, effective } = ruleSet;
112
+ const rulesLayer = ruleSet.layer;
113
+ // The git base, resolved before the run so the engine never has to know
114
+ // about git. `--pr` wins when both are given: it is the more specific
115
+ // question, and its answer already implies a base. An empty string is the
116
+ // adapter's spelling of "the pull request for this branch".
117
+ const since = Option.getOrUndefined(config.since);
118
+ const prNumber = Option.getOrUndefined(config.prNumber);
119
+ const git = yield* Git;
120
+ const gitScope = config.pr || prNumber !== undefined
121
+ ? { pr: prNumber ?? "" }
122
+ : since === undefined
123
+ ? undefined
124
+ : { since };
125
+ const changedSet = gitScope === undefined ? undefined : yield* git.changedFiles(cwd, gitScope);
126
+ const changedPaths = changedSet?.changed;
127
+ const movedPaths = changedSet?.renamed;
128
+ const changedBase = gitScope === undefined
129
+ ? undefined
130
+ : gitScope.pr !== undefined
131
+ ? gitScope.pr === ""
132
+ ? "the current branch's pull request"
133
+ : "PR " + gitScope.pr
134
+ : gitScope.since;
135
+ // The machine cache holds the run cache and the wire cache. The
136
+ // per-decision answer cache in `cacheDir` is the one CI replays.
137
+ const machineCache = yield* runCacheDirFor(cwd);
138
+ const report = yield* checkRepository({
139
+ config: effective,
140
+ plugins: loaded,
141
+ cwd,
142
+ paths: config.paths,
143
+ rules,
144
+ typecheck: config.typecheck,
145
+ types: config.types ? "trace" : "off",
146
+ maxInputTokens: config.maxTokens,
147
+ useTsgo: !config.noTsgo,
148
+ runExternalCode: config.runExternalCode || effective.runExternalCode === true,
149
+ cacheDirExplicit: Option.isSome(config.cacheDir),
150
+ cacheDir,
151
+ // The run cache is machine-local on purpose: it is a performance
152
+ // artifact, and a run should not write a report into a repository it is
153
+ // only visiting.
154
+ runCacheDir: machineCache,
155
+ // A git-scoped run is never a replay: the stored report is the whole
156
+ // repository, and the caller asked about a slice of it.
157
+ replayUnchanged: !config.noReplay && changedPaths === undefined,
158
+ changed: config.changed,
159
+ changedPaths,
160
+ movedPaths,
161
+ changedBase,
162
+ baselinePath: Option.getOrUndefined(config.baseline),
163
+ updateBaselinePath: Option.getOrUndefined(config.updateBaseline),
164
+ }).pipe(Effect.provide(Layer.mergeAll(rulesLayer, decisionLayer({ cacheDir, wireCacheDir: machineCache, offline: config.offline, apiKey }), tsgoLayer(cwd, {
165
+ runExternalCode: config.runExternalCode || effective.runExternalCode === true,
166
+ }))));
167
+ yield* write(render(report, config.format, { color: process.stdout.isTTY === true }));
168
+ yield* Effect.sync(() => {
169
+ process.exitCode = exitCodeFor(report, config.maxWarnings);
170
+ });
171
+ }).pipe(Effect.provide(gitLayer))).pipe(Command.withDescription("Report cross-file duplication and naming drift. With no paths, analyse the project tsgo sees. --since, --pr and --pr-number answer what a change introduced; --changed does the same against the last stored run."), Command.withShortDescription("Report cross-file duplication and naming drift."), Command.withExamples([
172
+ { command: "joggle check", description: "Analyse the project tsgo sees." },
173
+ {
174
+ command: "joggle check src --format stylish",
175
+ description: "Read findings for a directory, grouped by file.",
176
+ },
177
+ {
178
+ command: "joggle check --pr",
179
+ description: "Report only what this branch's pull request introduced.",
180
+ },
181
+ {
182
+ command: "joggle check --since origin/main",
183
+ description: "Report only what this branch introduced, from git.",
184
+ },
185
+ {
186
+ command: "joggle check --offline",
187
+ description: "Replay committed judgements; never call the model.",
188
+ },
189
+ { command: "joggle check --format github", description: "Emit GitHub Actions annotations." },
190
+ ]));
191
+ const askCommand = Command.make("ask", {
192
+ query: Argument.String("query").pipe(Argument.withDescription('A question in prose, for example "where is the retry policy defined?".')),
193
+ paths: Argument.String("paths").pipe(Argument.withDescription("Files or directories to rank against. Default: the whole project."), Argument.variadic()),
194
+ 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),
195
+ maxTokens: Flag.Int("max-tokens").pipe(Flag.withDescription("Input-token budget; candidates are trimmed to fit and the request is halved if the provider still rejects it."), Flag.withDefault(policy.ask.maxInputTokens)),
196
+ cwd: Flag.String("cwd").pipe(Flag.withDescription("Project root to analyse (default: the current directory)."), Flag.optional),
197
+ }, (config) => Effect.gen(function* () {
198
+ const path = yield* Path.Path;
199
+ const cwd = path.resolve(Option.getOrUndefined(config.cwd) ?? process.cwd());
200
+ const cacheDir = yield* cacheDirFor(cwd, Option.getOrUndefined(config.cacheDir));
201
+ const apiKey = yield* Config.option(Config.String("TYPESAFE_API_KEY"));
202
+ const workspace = yield* loadWorkspace(cwd, config.paths.length > 0 ? config.paths : ["."]);
203
+ const answer = yield* ask(workspace, config.query, { maxInputTokens: config.maxTokens }).pipe(Effect.provide(decisionLayer({
204
+ cacheDir,
205
+ wireCacheDir: yield* runCacheDirFor(cwd),
206
+ offline: false,
207
+ apiKey,
208
+ })));
209
+ yield* write([
210
+ answer.exists.toFixed(2) +
211
+ " that the code answers this; " +
212
+ answer.considered +
213
+ " declaration(s) ranked",
214
+ ...answer.matches.map((match) => match.confidence.toFixed(3) +
215
+ " " +
216
+ match.file +
217
+ ":" +
218
+ match.line +
219
+ " " +
220
+ match.symbol +
221
+ " (" +
222
+ match.symbolKind +
223
+ ")"),
224
+ ].join("\n"));
225
+ })).pipe(Command.withDescription("Ask a question about the code; rank the declarations that answer it."), Command.withShortDescription("Rank declarations that answer a question."), Command.withExamples([
226
+ {
227
+ command: 'joggle ask "where is the retry policy defined?"',
228
+ description: "Rank the declarations that answer a question.",
229
+ },
230
+ ]));
231
+ const rules = Command.make("rules", {
232
+ cwd: Flag.String("cwd").pipe(Flag.withDescription("Project root whose config to read (default: the current directory)."), Flag.optional),
233
+ config: Flag.String("config").pipe(Flag.withDescription("Config file, relative to the project root (default joggle.config.json)."), Flag.optional),
234
+ }, (config) => Effect.gen(function* () {
235
+ const path = yield* Path.Path;
236
+ const cwd = path.resolve(Option.getOrUndefined(config.cwd) ?? process.cwd());
237
+ // The same rule set the check runs, so this answers "what is enforced"
238
+ // rather than "what ships".
239
+ const ruleSet = yield* ruleSetFor(cwd, Option.getOrUndefined(config.config));
240
+ const all = ruleSet.rules.filter((rule) => isEnabled(ruleSet.effective, rule.id, rule.severity));
241
+ const width = all.reduce((max, rule) => Math.max(max, rule.id.length), 0);
242
+ const lines = all.map((rule) => `${rule.id.padEnd(width)} ${severityFor(ruleSet.effective, rule.id, rule.severity).padEnd(5)} ${rule.judged ? "judged" : "static"} ${rule.description}`);
243
+ // A plugin that failed to load is the difference between "not enforced"
244
+ // and "silently absent", and this is the command that should say so.
245
+ for (const failure of ruleSet.loaded.failures) {
246
+ lines.push(`note: ${failure.specifier} was not loaded: ${failure.reason}`);
247
+ }
248
+ yield* write(lines.join("\n"));
249
+ })).pipe(Command.withDescription("List the rules this repository enforces, with their severities."), Command.withShortDescription("List the enforced rules."), Command.withExamples([
250
+ { command: "joggle rules", description: "What the current repository enforces." },
251
+ {
252
+ command: "joggle rules --cwd ../other-repo",
253
+ description: "What another repository enforces.",
254
+ },
255
+ ]));
256
+ const calibrateCommand = Command.make("calibrate", {
257
+ paths: Argument.String("paths").pipe(Argument.withDescription("Files or directories whose candidates to calibrate against. Default: the whole project."), Argument.variadic()),
258
+ rule: Flag.String("rule").pipe(Flag.withDescription("Only calibrate these rule ids (comma-separated)."), Flag.optional),
259
+ cwd: Flag.String("cwd").pipe(Flag.withDescription("Project root to analyse (default: the current directory)."), Flag.optional),
260
+ config: Flag.String("config").pipe(Flag.withDescription("Config file, relative to the project root (default joggle.config.json)."), Flag.optional),
261
+ cacheDir: Flag.String("cache-dir").pipe(Flag.withDescription("Where answers are cached: <cwd>/.joggle when it exists, otherwise the machine cache."), Flag.optional),
262
+ format: Flag.Literals("format", ["text", "json"]).pipe(Flag.withDescription("Output format (default text)."), Flag.withDefault("text")),
263
+ types: Flag.Boolean("types").pipe(Flag.withDescription("Resolve types, so the type rules can be calibrated: the declaration trace and the per-expression node types. Costs a program, like check --types."), Flag.withDefault(false)),
264
+ runExternalCode: Flag.Boolean("run-external-code").pipe(Flag.withDescription("Allow tsc to execute content-mapper packages declared in tsconfig (TypeScript 7.1+). Off by default."), Flag.withDefault(false)),
265
+ }, (config) => Effect.gen(function* () {
266
+ const path = yield* Path.Path;
267
+ const cwd = path.resolve(Option.getOrUndefined(config.cwd) ?? process.cwd());
268
+ const ruleSet = yield* ruleSetFor(cwd, Option.getOrUndefined(config.config));
269
+ const wanted = Option.getOrUndefined(config.rule)
270
+ ?.split(",")
271
+ .map((id) => id.trim())
272
+ .filter((id) => id !== "");
273
+ // Only judged rules have a question to calibrate.
274
+ const rules = ruleSet.rules.filter((rule) => "plan" in rule &&
275
+ isEnabled(ruleSet.effective, rule.id, rule.severity) &&
276
+ (wanted === undefined || wanted.includes(rule.id)));
277
+ // A plain rule answers its own questions, so it never reaches the plan
278
+ // engine. The layer's observer records what it asked, and the rule declares
279
+ // which labels violate, so the staged cascade is measurable too.
280
+ const plainRules = ruleSet.rules.filter((rule) => !("plan" in rule) &&
281
+ rule.judged &&
282
+ isEnabled(ruleSet.effective, rule.id, rule.severity) &&
283
+ (wanted === undefined || wanted.includes(rule.id)));
284
+ const recorded = [];
285
+ const cacheDir = yield* cacheDirFor(cwd, Option.getOrUndefined(config.cacheDir));
286
+ const apiKey = yield* Config.option(Config.String("TYPESAFE_API_KEY"));
287
+ const inputs = config.paths.length > 0 ? config.paths : ["."];
288
+ const rows = yield* Effect.gen(function* () {
289
+ // A type rule cannot be calibrated without the facts it reads, and there
290
+ // are two: the declaration trace (`workspace.types`, for a guard's declared
291
+ // type) and the node types (`RunContext.nodeTypes`, for a returned
292
+ // expression's resolved type). Both cost a program, so it is opt-in. This
293
+ // is inside the effect that provides tsgo, which is why it is here and not
294
+ // beside the other loading above.
295
+ let types = emptyTypeIndex;
296
+ if (config.types) {
297
+ const tool = yield* sourceFingerprint(policy.analysisVersion);
298
+ // The same manifest rule `checkRepository` follows: the config is part
299
+ // of the key, so a config edit retires a cached trace instead of
300
+ // borrowing one it did not earn. The trace itself depends only on the
301
+ // code and the tool, so this over-invalidates -- the safe direction.
302
+ const manifest = manifestOf({
303
+ root: cwd,
304
+ files: [],
305
+ contents: new Map(),
306
+ ruleIds: rules.map((rule) => rule.id),
307
+ tool,
308
+ settings: shortHash(canonical({ config: ruleSet.effective, types: config.types })),
309
+ });
310
+ // The machine cache, like the declaration facts: a trace is a function
311
+ // of the whole program, so it is a performance artifact and not a
312
+ // decision a repository should carry in its diff.
313
+ const loaded = yield* loadTypeFacts({
314
+ root: cwd,
315
+ cacheDir: yield* runCacheDirFor(cwd),
316
+ tool,
317
+ manifest,
318
+ });
319
+ types = loaded.index;
320
+ }
321
+ const workspace = yield* loadWorkspace(cwd, inputs, { types });
322
+ // The checker's per-declaration facts, always: a calibration that could
323
+ // not see the members a rule reads would measure the old rule, not this
324
+ // one. Cheap after the first run -- the manifest keys the cache.
325
+ {
326
+ const tool = yield* sourceFingerprint(policy.analysisVersion);
327
+ const factsManifest = manifestOf({
328
+ root: cwd,
329
+ files: [],
330
+ contents: new Map(),
331
+ ruleIds: rules.map((rule) => rule.id),
332
+ tool,
333
+ settings: shortHash(canonical({ config: ruleSet.effective, types: "declarations" })),
334
+ });
335
+ const declarations = yield* loadDeclarationTypes({
336
+ root: cwd,
337
+ tsconfig: policy.typeFacts.tsconfig,
338
+ // The machine cache, not the committed one: the facts are a function of
339
+ // the whole program, so they are a performance artifact and never a
340
+ // decision a repository should carry in its diff.
341
+ cacheDir: yield* runCacheDirFor(cwd),
342
+ tool,
343
+ manifest: factsManifest,
344
+ maxMembers: policy.typeFacts.maxMembers,
345
+ maxStrings: policy.typeFacts.maxStrings,
346
+ requests: workspace.units.map((unit) => ({ file: unit.file, position: unit.namePosition })),
347
+ });
348
+ applyDeclarationTypes(workspace, declarations.index);
349
+ }
350
+ let nodeTypes;
351
+ if (config.types) {
352
+ const requests = workspace.files
353
+ .flatMap((file) => file.facts.returns.map((entry) => ({ file: file.path, position: entry.start })))
354
+ .slice(0, 2000);
355
+ if (requests.length > 0) {
356
+ const found = yield* Effect.tryPromise(() => typesAtPositions({ cwd, tsconfig: "tsconfig.json", requests })).pipe(Effect.orElseSucceed(() => ({ found: [], unresolved: 0 })));
357
+ nodeTypes = indexOfNodeTypes(found.found);
358
+ }
359
+ }
360
+ const out = [];
361
+ for (const rule of rules) {
362
+ const planned = yield* rule.plan(workspace, everyFile, { config: ruleSet.effective, nodeTypes });
363
+ // Chunked like the engine: one rule's candidates can exceed the
364
+ // provider's token ceiling, so they travel in as many requests as fit.
365
+ //
366
+ // The provider occasionally returns a distribution that does not sum to
367
+ // 1 for one decision, and the whole request is rejected for it. Split
368
+ // and retry, so one bad decision loses its own plan rather than every
369
+ // rule in the chunk. A single plan that still fails reads as undefined,
370
+ // which is an unreadable candidate, not a lost rule.
371
+ const answerChunk = (plans, retried = false) => Effect.gen(function* () {
372
+ const attempt = yield* Effect.result(answerPlansRaw(plans));
373
+ if (Result.isSuccess(attempt))
374
+ return attempt.success;
375
+ // A lone request the provider answered with a distribution that
376
+ // does not sum to 1: ask once more before giving the candidate up.
377
+ // The provider is nondeterministic, so this is an instrument fault
378
+ // rather than an answer.
379
+ if (plans.length <= 1)
380
+ return retried ? [undefined] : yield* answerChunk(plans, true);
381
+ const middle = Math.ceil(plans.length / 2);
382
+ const left = yield* answerChunk(plans.slice(0, middle));
383
+ const right = yield* answerChunk(plans.slice(middle));
384
+ return [...left, ...right];
385
+ });
386
+ const answers = [];
387
+ for (const chunk of yield* chunkPlans(planned.plans, policy.decision.maxStateChars)) {
388
+ answers.push(...(yield* answerChunk(chunk.plans)));
389
+ }
390
+ const unreadable = answers.filter((answer) => answer === undefined).length;
391
+ const rejected = unreadable > 0 ? String(unreadable) + " candidate(s) the provider rejected" : "";
392
+ // One row per DECISION that declares its violating labels, so a rule
393
+ // that composes several questions is calibrated question by question
394
+ // rather than named and skipped.
395
+ const byDecision = new Map();
396
+ planned.plans.forEach((plan, index) => {
397
+ for (const [decision, labels] of Object.entries(plan.violations ?? {})) {
398
+ const verdict = verdictOf(answers[index]?.[decision], labels);
399
+ if (verdict === undefined)
400
+ continue;
401
+ const quality = qualityOf({
402
+ score: verdict.probability,
403
+ margin: verdict.margin,
404
+ confidence: verdict.confidence,
405
+ });
406
+ const states = byDecision.get(decision) ?? [];
407
+ states.push({ probability: verdict.probability, acted: quality.quality === "act" });
408
+ byDecision.set(decision, states);
409
+ }
410
+ });
411
+ const sample = planned.plans.slice(0, 3).map((plan) => plan.subject);
412
+ const note = rejected !== "" ? "provider rejected the answers: " + rejected : "";
413
+ if (byDecision.size === 0) {
414
+ out.push({
415
+ rule: rule.id,
416
+ decision: "-",
417
+ summary: summarizeCalibration([]),
418
+ sample,
419
+ note: note === "" ? "no violating decision declared" : note,
420
+ });
421
+ continue;
422
+ }
423
+ for (const [decision, states] of byDecision) {
424
+ out.push({ rule: rule.id, decision, summary: summarizeCalibration(states), sample, note });
425
+ }
426
+ }
427
+ for (const rule of plainRules) {
428
+ recorded.length = 0;
429
+ const ran = yield* Effect.result(rule.run(workspace, everyFile, { config: ruleSet.effective, nodeTypes }));
430
+ if (Result.isFailure(ran)) {
431
+ out.push({
432
+ rule: rule.id,
433
+ decision: "-",
434
+ summary: summarizeCalibration([]),
435
+ sample: [],
436
+ note: "the rule could not run: " + String(ran.failure),
437
+ });
438
+ continue;
439
+ }
440
+ const byDecision = new Map();
441
+ for (const event of recorded) {
442
+ for (const [decision, labels] of Object.entries(rule.violations ?? {})) {
443
+ const verdict = verdictOf(event.answers[decision], labels);
444
+ if (verdict === undefined)
445
+ continue;
446
+ const quality = qualityOf({
447
+ score: verdict.probability,
448
+ margin: verdict.margin,
449
+ confidence: verdict.confidence,
450
+ });
451
+ const states = byDecision.get(decision) ?? [];
452
+ states.push({ probability: verdict.probability, acted: quality.quality === "act" });
453
+ byDecision.set(decision, states);
454
+ }
455
+ }
456
+ if (byDecision.size === 0) {
457
+ out.push({
458
+ rule: rule.id,
459
+ decision: "-",
460
+ summary: summarizeCalibration([]),
461
+ sample: [],
462
+ note: "no violating decision was declared or asked",
463
+ });
464
+ continue;
465
+ }
466
+ for (const [decision, states] of byDecision) {
467
+ out.push({ rule: rule.id, decision, summary: summarizeCalibration(states), sample: [], note: "" });
468
+ }
469
+ }
470
+ return out;
471
+ }).pipe(Effect.provide(Layer.mergeAll(atomsLayer, decisionLayer({
472
+ cacheDir,
473
+ wireCacheDir: yield* runCacheDirFor(cwd),
474
+ offline: false,
475
+ apiKey,
476
+ onAnswer: (event) => recorded.push({ answers: event.answers }),
477
+ }),
478
+ // The trace and the node types both run tsgo; the calibrate command
479
+ // provides it only because `--types` may have asked for them.
480
+ tsgoLayer(cwd, {
481
+ runExternalCode: config.runExternalCode || ruleSet.effective.runExternalCode === true,
482
+ }))));
483
+ if (config.format === "json") {
484
+ yield* write(JSON.stringify(rows, null, 2));
485
+ return;
486
+ }
487
+ const width = rows.reduce((max, row) => Math.max(max, (row.rule + "#" + row.decision).length), 0);
488
+ const lines = [
489
+ "rule#decision".padEnd(width) + " states verdict median min max fired",
490
+ ...rows.map((row) => (row.rule + "#" + row.decision).padEnd(width) +
491
+ " " + String(row.summary.states).padStart(6) +
492
+ " " + row.summary.verdict.padEnd(8) +
493
+ " " + row.summary.median.toFixed(2).padStart(6) +
494
+ " " + row.summary.min.toFixed(2).padStart(5) +
495
+ " " + row.summary.max.toFixed(2).padStart(5) +
496
+ " " + String(row.summary.fired).padStart(5) +
497
+ (row.note === "" ? "" : " (" + row.note + ")")),
498
+ ];
499
+ yield* write(lines.join("\n"));
500
+ })).pipe(Command.withDescription("Replay each question over the candidates this project produces, and label it decisive, weak, noisy or skipped."), Command.withShortDescription("Calibrate the questions."), Command.withExamples([
501
+ { command: "joggle calibrate", description: "Calibrate every judged question." },
502
+ { command: "joggle calibrate --rule joggle/object-shape", description: "Calibrate one question." },
503
+ ]));
504
+ /**
505
+ * The merge driver git invokes for one answer shard, registered in
506
+ * `.joggle/.gitattributes` and in the user's git config.
507
+ *
508
+ * A shard is line-oriented and keyed, so a union by key is the whole merge. It
509
+ * declines (non-zero, no write) when a side is not a shard at all, so git
510
+ * records an ordinary conflict rather than a union that dropped lines.
511
+ */
512
+ const mergeAnswers = Command.make("merge-answers", {
513
+ base: Argument.String("base").pipe(Argument.withDescription("The merge base shard (git %O). Not consulted: every line is either present or not.")),
514
+ ours: Argument.String("ours").pipe(Argument.withDescription("Our shard, and where the result is written (git %A).")),
515
+ theirs: Argument.String("theirs").pipe(Argument.withDescription("Their shard (git %B).")),
516
+ }, (config) => Effect.gen(function* () {
517
+ const fs = yield* FileSystem.FileSystem;
518
+ const read = (file) => fs.readFileString(file).pipe(Effect.orElseSucceed(() => ""));
519
+ const merged = yield* Effect.result(mergeShardText({ ours: yield* read(config.ours), theirs: yield* read(config.theirs) }));
520
+ if (Result.isFailure(merged)) {
521
+ yield* write("joggle: merge-answers: the " + merged.failure.side + " side is not an answer shard; resolve this conflict by hand");
522
+ yield* Effect.sync(() => {
523
+ process.exitCode = 1;
524
+ });
525
+ return;
526
+ }
527
+ yield* fs.writeFileString(config.ours, merged.success).pipe(Effect.orElseSucceed(() => undefined));
528
+ })).pipe(Command.withDescription("Merge one answer shard by key. A git merge driver, not a command to run by hand; see docs/artifacts.md."), Command.withShortDescription("Merge one answer shard (git driver)."));
529
+ const cachePrune = Command.make("prune", {
530
+ cwd: Flag.String("cwd").pipe(Flag.withDescription("Project root whose cache to prune (default: the current directory)."), Flag.optional),
531
+ cacheDir: Flag.String("cache-dir").pipe(Flag.withDescription("Where the answer cache lives: <cwd>/.joggle when it exists, otherwise the machine cache."), Flag.optional),
532
+ maxAge: Flag.Int("max-age").pipe(Flag.withDescription("Drop entries written more than this many days ago."), Flag.optional),
533
+ maxBytes: Flag.Int("max-bytes").pipe(Flag.withDescription("After the age cut, drop oldest-first until the store is at or under this many bytes."), Flag.optional),
534
+ }, (config) => Effect.gen(function* () {
535
+ const fs = yield* FileSystem.FileSystem;
536
+ const path = yield* Path.Path;
537
+ const cwd = path.resolve(Option.getOrUndefined(config.cwd) ?? process.cwd());
538
+ const dir = yield* cacheDirFor(cwd, Option.getOrUndefined(config.cacheDir));
539
+ const days = Option.getOrUndefined(config.maxAge);
540
+ const result = yield* pruneAnswers(fs, path, dir, {
541
+ olderThanSeconds: days === undefined ? undefined : days * 24 * 60 * 60,
542
+ maxBytes: Option.getOrUndefined(config.maxBytes),
543
+ });
544
+ const noun = result.removed === 1 ? "entry" : "entries";
545
+ yield* write("joggle: pruned " + result.removed + " " + noun + "; " + result.kept + " kept, " + result.bytes + " bytes");
546
+ })).pipe(Command.withDescription("Drop old answer-cache entries by age and size. The cache is regenerable; pruning it is safe, and a store that only grows is not a cache."), Command.withShortDescription("Prune the answer cache."), Command.withExamples([
547
+ { command: "joggle cache prune --max-age 90", description: "Drop answers older than 90 days." },
548
+ {
549
+ command: "joggle cache prune --max-bytes 4000000",
550
+ description: "Cap the committed cache, oldest answers first.",
551
+ },
552
+ ]));
553
+ const cacheMigrate = Command.make("migrate", {
554
+ cwd: Flag.String("cwd").pipe(Flag.withDescription("Project root whose cache to migrate (default: the current directory)."), Flag.optional),
555
+ cacheDir: Flag.String("cache-dir").pipe(Flag.withDescription("Where the answer cache lives: <cwd>/.joggle when it exists, otherwise the machine cache."), Flag.optional),
556
+ }, (config) => Effect.gen(function* () {
557
+ const fs = yield* FileSystem.FileSystem;
558
+ const path = yield* Path.Path;
559
+ const cwd = path.resolve(Option.getOrUndefined(config.cwd) ?? process.cwd());
560
+ const dir = yield* cacheDirFor(cwd, Option.getOrUndefined(config.cacheDir));
561
+ const store = yield* makeAnswerStore(fs, path, dir);
562
+ const written = yield* store.migrate;
563
+ yield* write("joggle: wrote " + written + " answer(s) to " + path.join(dir, "answers"));
564
+ })).pipe(Command.withDescription("Rewrite the cache in the sharded shape, and remove a legacy answers.json. Idempotent."), Command.withShortDescription("Migrate the cache to shards."));
565
+ const cacheCommand = Command.make("cache", {}, () => write("joggle cache: run `joggle cache prune`, or read docs/artifacts.md for the layout.")).pipe(Command.withDescription("Work on the answer cache itself: prune it, migrate it, and see how it is laid out."), Command.withShortDescription("Prune the answer cache."), Command.withSubcommands([cachePrune, cacheMigrate]));
566
+ const cli = Command.make("joggle").pipe(Command.withDescription("Cross-file patterns and idioms for TypeScript, enforced like a linter: deterministic where it can prove, System One where it has to judge."), Command.withExamples([
567
+ {
568
+ command: "joggle check --pr",
569
+ description: "Check only what this branch's pull request changed.",
570
+ },
571
+ { command: "joggle check --since origin/main", description: "Check only what this branch changed." },
572
+ { command: "joggle rules", description: "See what is enforced here." },
573
+ ]), Command.withSubcommands([checkCommand, askCommand, rules, calibrateCommand, cacheCommand, mergeAnswers]));
574
+ const services = Layer.mergeAll(NodeServices.layer, FetchHttpClient.layer, builtIn);
575
+ const program = Command.run(cli, { version: policy.version }).pipe(Effect.provide(services));
576
+ /*
577
+ * Never fail silently. A typed failure, an interruption and a defect all have
578
+ * to reach stderr with enough detail to act on. This is a CI gate, and a gate
579
+ * that exits non-zero without saying why is worse than no gate at all.
580
+ */
581
+ /**
582
+ * A typed failure deserves a sentence, not a stack.
583
+ *
584
+ * `Cause.pretty` prints the operation, the cause and the whole trace, which is
585
+ * right for a defect and wrong for "you did not pass a path": the one line that
586
+ * matters ends up buried under the machinery that produced it.
587
+ */
588
+ const describeFailure = (cause) => {
589
+ if (!isRecord(cause))
590
+ return undefined;
591
+ const record = cause;
592
+ const tag = record["_tag"];
593
+ if (tag === "joggle/WorkspaceError") {
594
+ const original = record["cause"];
595
+ const detail = original instanceof Error ? original.message : Predicate.isString(original) ? original : "";
596
+ return String(record["operation"]) + ": " + detail;
597
+ }
598
+ // Git and tsgo already carry the one sentence that matters: the command and
599
+ // what it said. A stack trace here buries it.
600
+ if (tag === "joggle/GitError" || tag === "joggle/TsgoError") {
601
+ return String(record["operation"]) + ": " + (Predicate.isString(record["detail"]) ? record["detail"] : "");
602
+ }
603
+ // Any other typed failure -- AiError, ConfigError -- has a message, and that
604
+ // sentence is what a person needs. The stack is for a defect.
605
+ if (Predicate.isString(record["message"]) && record["message"] !== "") {
606
+ return record["message"];
607
+ }
608
+ return undefined;
609
+ };
610
+ /**
611
+ * One sentence for a typed failure, and the runtime owns the rest.
612
+ *
613
+ * `NodeRuntime.runMain` sets the exit code, handles Ctrl+C, and runs finalizers.
614
+ * The teardown only has to say WHY, and to keep a success's own exit code -- the
615
+ * lint gate writes one into `process.exitCode`.
616
+ */
617
+ // The parameter annotations are load-bearing: `Runtime.Teardown` is a two-argument
618
+ // call signature from Effect, so a payload object cannot satisfy it. Annotating
619
+ // both parameters distinctly is what keeps a transposition from compiling.
620
+ const teardown = (exit, onExit) => {
621
+ if (Exit.isSuccess(exit)) {
622
+ onExit(Predicate.isNumber(process.exitCode) ? process.exitCode : 0);
623
+ return;
624
+ }
625
+ const failure = Cause.findErrorOption(exit.cause);
626
+ const described = Option.isSome(failure) ? describeFailure(failure.value) : undefined;
627
+ process.stderr.write(described === undefined ? `${Cause.pretty(exit.cause)}\n` : `${described}\n`);
628
+ onExit(1);
629
+ };
630
+ NodeRuntime.runMain(program, { disableErrorReporting: true, teardown });