@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/policy.js ADDED
@@ -0,0 +1,676 @@
1
+ /**
2
+ * Configuration for the search, and nothing else.
3
+ *
4
+ * The first version of this file held sixteen numbers that *decided* things:
5
+ * probability floors, weights for a hand-rolled composite score, confidence
6
+ * gates. That is the entropy machine's disease with an API bill -- a person's
7
+ * guess wearing a number, unreviewable and impossible to argue with, and the
8
+ * reason the earlier rules could only be improved by fiddling.
9
+ *
10
+ * Every decision now belongs to exactly one Effect Decision, and code reads its
11
+ * answer. Numbers survive only where they bound *search*: how similar a pair
12
+ * must be before it is worth a call, and how many calls a run may make. Those
13
+ * are recall and cost knobs. Judging a candidate is the model's job; finding
14
+ * candidates is the code's.
15
+ */
16
+ export const policy = {
17
+ /** Surfaced by `joggle --version`. */
18
+ version: "0.1.0",
19
+ /** The System One model every rule judges with. */
20
+ model: "jev-latest",
21
+ /**
22
+ * Part of the judgement cache key. Bump it when a question's wording, options
23
+ * or evidence change, so verdicts produced by older questions are not replayed
24
+ * against newer ones.
25
+ */
26
+ decisionVersion: "2026-11-05",
27
+ /**
28
+ * The declared analysis version: a FALLBACK and an OVERRIDE, not the gate.
29
+ *
30
+ * This used to be the gate, and a hand-bumped gate is a promise to remember.
31
+ * Forgetting it means the next run replays a report produced by rules that no
32
+ * longer exist -- which happened twice in one session, and both times the output
33
+ * looked entirely plausible, because a stale report is not malformed, it is just
34
+ * wrong.
35
+ *
36
+ * The unchanged-run short-circuit now keys on a hash of the tool's own source
37
+ * (see fingerprint.ts), so a change to a rule, a threshold or a question cannot
38
+ * be missed. Question versioning still covers question WORDING, because the
39
+ * judgement cache keys on it directly.
40
+ *
41
+ * This string survives for the case a hash cannot serve: when the sources cannot
42
+ * be read, so a run in an unusual installation degrades to the old behaviour
43
+ * rather than breaking.
44
+ *
45
+ * There is deliberately no way to opt out of the hash yet. A cosmetic edit
46
+ * therefore invalidates the run cache, which is the conservative direction: the
47
+ * cost is re-analysis, the cost of the other direction is a wrong report. An
48
+ * override that skips the hash is the obvious next step and does not exist.
49
+ */
50
+ analysisVersion: "2026-09-05",
51
+ decision: {
52
+ baseUrl: "https://api.typesafe.ai",
53
+ /**
54
+ * How many times a Noul is asked, in one request.
55
+ *
56
+ * A yes/no comes back as one number with no second signal: `verdictOf` gives a
57
+ * Choice a margin from its distribution and gives a Noul nothing, so a Noul is
58
+ * gated by the probability floor alone. Asking it again and reading the
59
+ * AGREEMENT gives it the margin a Choice gets for free -- the self-consistency
60
+ * cookbook's pattern, and jev is built to be stable across repeats. A Choice
61
+ * is asked once: its distribution already carries the signal, and repeating it
62
+ * would spend a call to learn nothing.
63
+ */
64
+ consistency: { repeats: 3 },
65
+ /**
66
+ * Characters of shared state one request may carry.
67
+ *
68
+ * The engine batches every planned rule's questions into one request, and the
69
+ * provider has a token ceiling: a run of joggle against itself sent 105
70
+ * candidates' evidence at once and came back HTTP 400
71
+ * `max_tokens_exceeded`, which every judged rule then read as "unreadable".
72
+ * So the plans are cut into requests that fit. The per-question cache keeps a
73
+ * chunk boundary from costing a re-judgement.
74
+ */
75
+ maxStateChars: 24000,
76
+ /**
77
+ * Input tokens one run may spend on judgement.
78
+ *
79
+ * A backstop, not a target. The per-decision cache means a run pays only for
80
+ * evidence never judged before, so a push costs almost nothing and a cold run
81
+ * on a large repository costs a lot once. This bounds the runaway: when the
82
+ * estimate passes it, the run stops judging and reports what it did not judge
83
+ * as budget drops.
84
+ */
85
+ maxInputTokens: 1000000,
86
+ /** How long a successful judgement stays fresh, in days. */
87
+ timeToLiveDays: 30,
88
+ /**
89
+ * Candidates per request. ONE, and the measurement is why.
90
+ *
91
+ * The parallel-questions cookbook reports batching 13 questions onto one
92
+ * shared document as 12.2x cheaper and 10x faster with no change in answers,
93
+ * and it says exactly when that applies: "the document dominates every
94
+ * request, so N single-question calls pay for it N times... The bigger the
95
+ * document, the closer the saving gets to a full Nx."
96
+ *
97
+ * Our candidates are not one shared document. They are different clusters
98
+ * with different evidence, so there is nothing to amortise -- the saving is
99
+ * the per-request boilerplate and nothing else. Measured on 80 identical
100
+ * requests judged both ways:
101
+ *
102
+ * unbatched 80 calls 101,903 input tokens
103
+ * batched 5 calls 82,091 input tokens (19%, not 12x)
104
+ * identical verdicts: 37/80 = 46%
105
+ *
106
+ * And the disagreements were systematic rather than noisy: redundancy
107
+ * scores fell by 0.05-0.10 across the board, and `member_0` started winning
108
+ * the canonical choice far more often. That is context rot and position
109
+ * bias, exactly what the primitives page warns about when it says to give
110
+ * each question only the context it needs.
111
+ *
112
+ * So batching is OFF by default and the speed comes from concurrency, which
113
+ * is the other pattern the docs prescribe -- the re-ranking cookbook fires
114
+ * 1,200 independent calls through a thread pool and calls it cheap. The
115
+ * batching machinery stays because it is the right lever for a state that IS
116
+ * shared, such as a naming family judged one member per question.
117
+ */
118
+ batchCandidates: 1,
119
+ /** Independent requests in flight at once. */
120
+ requestConcurrency: 16,
121
+ /**
122
+ * How good an answer has to be before a rule may act on it.
123
+ *
124
+ * A probability decision is a yes/no question, so its answer is a VERDICT,
125
+ * not a ranking: 0.2 is the model saying no. Nothing read that. `worth_fixing`
126
+ * and `one_concept` and `redundant` were kept only as sort keys while the
127
+ * classification decided, so on Shakti 237 findings were reported where the model had
128
+ * already answered "not worth a reviewer's time" and been overruled by a
129
+ * different question.
130
+ *
131
+ * The margin is winner minus runner-up in the classification's own distribution:
132
+ * whether the model picked an option or shrugged across two. Raw `confidence`
133
+ * measured uninformative here and is still only reported, but `probabilities`
134
+ * arrived with every answer from the first day and nothing ever read it.
135
+ */
136
+ gates: {
137
+ probabilityFloor: 0.5,
138
+ minMargin: 0.25,
139
+ /**
140
+ * Below this, an answer is reported for review rather than acted on.
141
+ *
142
+ * TypeSafe's confidence is the shape of the probability distribution: a
143
+ * clear winner is near 1, a shrug across the options is low. The docs route
144
+ * on it in three ranges -- act, review, drop -- and joggle had only two.
145
+ * A non-decisive choice was dropped as if the model had said no, when it
146
+ * was saying "I am not sure", which is a different answer and belongs in
147
+ * the report as an info finding a reader can weigh.
148
+ */
149
+ reviewFloor: 0.6,
150
+ /**
151
+ * The share of a Noul's repeated asks that must agree before the agreement
152
+ * counts as a margin at all.
153
+ *
154
+ * Mapping agreement straight onto the margin let a 2-1 split through: it
155
+ * reads as 0.33, over `minMargin`, the same as a 67/33 Choice. But a Choice's
156
+ * distribution is the model's own spread, and a split among three asks is a
157
+ * sample of three -- one a coin flip produces three times in four. So below
158
+ * this share the asks disagreed, the margin is 0, and the answer is reviewed
159
+ * rather than acted on. At three repeats it means every ask agreed.
160
+ */
161
+ minAgreement: 1,
162
+ },
163
+ /** Token budget for one request when batching is used. Around 32,000 is the
164
+ * API limit, shared between state and questions. */
165
+ batchTokens: 20000,
166
+ },
167
+ /**
168
+ * Near-duplicate search. These bound how many pairs are offered to the model,
169
+ * never whether a pair is duplication.
170
+ */
171
+ duplicateMeaning: {
172
+ /** Structural overlap below which a pair is not worth a call. */
173
+ minSimilarity: 0.7,
174
+ /** Very short bodies match by accident; skip them. */
175
+ minTokens: 12,
176
+ /** At 1.0 the exact-duplicate rule already owns the pair. */
177
+ maxSimilarity: 0.995,
178
+ /**
179
+ * Clusters sent for judgement in one run.
180
+ *
181
+ * This used to cap *pairs*, applied by sorting them by similarity and
182
+ * slicing. That is a selection, not a bound: on one codebase forty
183
+ * high-scoring pairs elsewhere in the tree spent the whole budget and the
184
+ * eighteen definitions of `formatDate` were never compared at all. Pair
185
+ * generation is now complete up to a provable length filter, and the only
186
+ * remaining bound is on how many clusters get judged -- with the overflow
187
+ * named in the report rather than dropped.
188
+ */
189
+ maxClusters: 400,
190
+ },
191
+ /**
192
+ * Groups of fields that repeat without a name.
193
+ *
194
+ * `minOccurrences` is a search bound and the only number here that decides what
195
+ * is worth reporting: two declarations sharing three fields is a coincidence,
196
+ * nine is a concept. Everything else bounds the work.
197
+ */
198
+ nameThePrimitive: {
199
+ minFields: 3,
200
+ minOccurrences: 6,
201
+ maxFindings: 400,
202
+ },
203
+ /**
204
+ * Export names a framework calls by file.
205
+ *
206
+ * A `loader` is not a hoist candidate and two `loader`s are not shared logic,
207
+ * whatever they contain: the framework asks for one per route and calls it by
208
+ * name, so there is nothing to consolidate and nothing to move. Kept here rather
209
+ * than in a rule because two rules need it and a second copy is a second thing
210
+ * to update.
211
+ */
212
+ frameworkExports: [
213
+ "loader",
214
+ "action",
215
+ "clientLoader",
216
+ "clientAction",
217
+ "meta",
218
+ "links",
219
+ "headers",
220
+ "ErrorBoundary",
221
+ "HydrateFallback",
222
+ "shouldRevalidate",
223
+ "middleware",
224
+ // Migrations and seeds: the runner calls these by name, one per file.
225
+ "up",
226
+ "down",
227
+ "seed",
228
+ // Test runners. A hook is scaffolding for an assertion, not a rule.
229
+ "beforeAll",
230
+ "afterAll",
231
+ "beforeEach",
232
+ "afterEach",
233
+ ],
234
+ /**
235
+ * Name retrieval cost.
236
+ *
237
+ * `minFiles` is the candidate filter, not the verdict: a single word reached
238
+ * from fewer files than this is not worth judging. Whether a name at or above
239
+ * it actually fails as an address is the model's call.
240
+ */
241
+ nameAsAddress: {
242
+ minFiles: 12,
243
+ /** Names judged per run. */
244
+ maxFiles: 200,
245
+ /** Calling files shown to the model, as a sample. */
246
+ maxCallers: 30,
247
+ },
248
+ /*
249
+ * Name retrieval cost.
250
+ *
251
+ * `minFiles` was chosen from the distribution rather than guessed. Measured
252
+ * across four repositories, the reach of a single-word export is bimodal: one
253
+ * name at 14 files and everything else at 4 or fewer. `cn`, the classname
254
+ * helper, is that one name -- and a two-letter export used in twenty-one files
255
+ * is precisely the address the reference material describes as unsearchable.
256
+ * Twelve sits in the empty middle of the distribution, where the two modes
257
+ * separate and no threshold in between would change the answer.
258
+ */
259
+ /**
260
+ * Orchestration comparison (kept for the call-pattern rule below).
261
+ *
262
+ * `minCalls` is what makes a shared call sequence mean something: two functions
263
+ * that each make one call are not "the same orchestration", they are two
264
+ * functions with one call. It is a search bound, and the only number here.
265
+ */
266
+ callPattern: {
267
+ minCalls: 4,
268
+ maxFindings: 400,
269
+ },
270
+ /**
271
+ * How many modules one run will classify.
272
+ *
273
+ * One question per module, batched, and content-addressed, so a second rule
274
+ * asking about the same modules replays rather than calls. The bound is against
275
+ * a pathological repository rather than a budget anybody should reach.
276
+ */
277
+ moduleRoles: {
278
+ maxModules: 600,
279
+ },
280
+ /**
281
+ * Object literals that should be a named type.
282
+ *
283
+ * `minKeys` is what separates a shape from a coincidence: two literals sharing
284
+ * one key are two literals, not a missing type.
285
+ */
286
+ objectShape: {
287
+ minKeys: 3,
288
+ maxFindings: 300,
289
+ /**
290
+ * How many files a shape must span before the finding is a warning.
291
+ *
292
+ * A shape in two files is a pair that may be a coincidence; one in three or
293
+ * more is a pattern somebody keeps re-writing. Both are reported -- the pair
294
+ * as a notice -- because the difference is what a reader needs, not a reason
295
+ * to discard the pair.
296
+ */
297
+ warnFromFiles: 3,
298
+ },
299
+ /**
300
+ * Field-set composition analysis.
301
+ *
302
+ * Both numbers bound SEARCH, not judgement: this rule is deterministic and
303
+ * compares sets, so the only question is how many types one run will look at.
304
+ */
305
+ composeTypes: {
306
+ /** Fewer than this and a shared field set means nothing. */
307
+ minFields: 3,
308
+ /** Types compared per run. Beyond this the report says what it skipped. */
309
+ maxTypes: 4000,
310
+ },
311
+ /**
312
+ * Package-and-dependency pairs sent for judgement in one run.
313
+ *
314
+ * The candidate set is small by construction -- distinct pairs, not import
315
+ * statements -- so this is a ceiling against a pathological repository rather
316
+ * than a budget anybody should reach.
317
+ */
318
+ dependencyFit: {
319
+ maxDependencies: 400,
320
+ },
321
+ /**
322
+ * Semantic search over the declarations.
323
+ *
324
+ * One request ranks the candidates with a Choice and asks a Noul whether the
325
+ * codebase answers at all. `maxCandidates` is the context bound -- the model
326
+ * reads worse as unrelated state grows -- and the keyword prefilter is what
327
+ * keeps the state to what the query is plausibly about.
328
+ */
329
+ ask: {
330
+ /** Tokens below which a declaration has nothing to match a query against. */
331
+ minTokens: 20,
332
+ /** Candidates per request. The state bound, not a cost bound. */
333
+ maxCandidates: 200,
334
+ /** Characters of a candidate's body sent as state. */
335
+ maxSourceChars: 800,
336
+ /**
337
+ * Input tokens one ask may cost. One request carries a decision per
338
+ * candidate, so the candidate list is trimmed to this before it is sent --
339
+ * a whole-repository ask otherwise exceeds the provider's output ceiling.
340
+ * Smaller than the check's budget on purpose: check chunks, ask does not.
341
+ */
342
+ maxInputTokens: 8000,
343
+ /** Matches printed. */
344
+ top: 10,
345
+ },
346
+ /**
347
+ * A run of calls two declarations share without sharing the whole sequence.
348
+ *
349
+ * `minCalls` is what makes a shared run mean something: three calls in a row
350
+ * can be a habit, and a longer run is a helper someone inlined. Deterministic,
351
+ * so this only bounds the work and the report.
352
+ */
353
+ duplicateCallRun: {
354
+ minCalls: 4,
355
+ maxFindings: 200,
356
+ },
357
+ /**
358
+ * A function that inlines what an existing declaration already does.
359
+ *
360
+ * Lower than the call-run floor, because the claim is stronger: the whole body
361
+ * of an existing declaration appears inside another one, so there is a name to
362
+ * call rather than a run to extract.
363
+ */
364
+ reimplementedPrimitive: {
365
+ minCalls: 3,
366
+ /** Pairs handed to one request. Above this the run's budget bounds it. */
367
+ maxPairs: 200,
368
+ },
369
+ /**
370
+ * A file with a wide surface and little behind it.
371
+ *
372
+ * Ousterhout's ratio: implementation lines over exports. `minExports` keeps a
373
+ * small file out of it, and `minDepth` is the score below which a wide file is
374
+ * a grab bag rather than a module.
375
+ */
376
+ shallowModule: {
377
+ minExports: 5,
378
+ minDepth: 2,
379
+ /** Files judged per run. */
380
+ maxFiles: 400,
381
+ },
382
+ /**
383
+ * Functions sent for a paired-operation judgement in one run.
384
+ *
385
+ * The candidate filter is exact -- one half of a pair and not the other -- so
386
+ * this is a ceiling rather than a budget.
387
+ */
388
+ temporalCoupling: {
389
+ maxDeclarations: 400,
390
+ /**
391
+ * Operations that acquire or open a resource, and the call that releases it.
392
+ *
393
+ * A DECLARED convention, not a fact about this repository: which operations
394
+ * pair is knowledge the author has about resource APIs, and it is not
395
+ * derivable from the code -- `lock`/`unlock` is English, not structure. It
396
+ * lives here, reviewable and overridable, rather than hidden in the rule; the
397
+ * rule's JUDGEMENT (is this acquire unpaired?) is still the model's. See the
398
+ * "declared conventions" section of docs/rule-coupling.md.
399
+ */
400
+ pairs: [
401
+ ["lock", "unlock"],
402
+ ["acquire", "release"],
403
+ ["connect", "disconnect"],
404
+ ["subscribe", "unsubscribe"],
405
+ ["mount", "unmount"],
406
+ ],
407
+ },
408
+ /**
409
+ * Rule files sent for a self-audit in one run.
410
+ *
411
+ * The candidate filter is a `defineRule` call. The ceiling is against a
412
+ * repository with an unusual number of rules.
413
+ */
414
+ ruleJudgment: {
415
+ maxRules: 200,
416
+ },
417
+ /**
418
+ * A domain word the prose repeats and no name uses.
419
+ *
420
+ * `minMentions` is what separates a concept from a turn of phrase: a word the
421
+ * prose says once is a word, one it repeats is a thing.
422
+ */
423
+ languageDrift: {
424
+ minMentions: 3,
425
+ /** Files judged per run. */
426
+ maxFiles: 200,
427
+ },
428
+ /**
429
+ * Deprecation promises checked in one run.
430
+ *
431
+ * Deprecated declarations are rare by construction, so this is a guard against a
432
+ * pathological repository rather than a budget anybody should reach. The import
433
+ * ceiling is per declaration because one old primitive can have hundreds of call
434
+ * sites, and the question is the same for all of them.
435
+ */
436
+ intentDrift: {
437
+ maxDeclarations: 200,
438
+ maxImports: 20,
439
+ },
440
+ /**
441
+ * One field name with incompatible types in two declarations.
442
+ *
443
+ * Deterministic: it compares the recorded type text of every interface and type
444
+ * alias field. The bound is against a pathological repository rather than a
445
+ * budget anybody should reach.
446
+ */
447
+ fieldTypeDrift: {
448
+ maxFindings: 200,
449
+ /**
450
+ * Words a field name must have before its type is compared.
451
+ *
452
+ * A single-word field is a generic slot: `id`, `name`, `type`, `files` mean
453
+ * whatever their declaration says, and two of them with different types are
454
+ * two concepts, not one that drifted. A name of two words or more is a
455
+ * concept -- `supervisorRate`, `regularPayTotal` -- and one concept with two
456
+ * types is the defect.
457
+ */
458
+ minWords: 2,
459
+ },
460
+ /**
461
+ * Documented declarations sent for a doc-vs-code check in one run.
462
+ *
463
+ * The candidate filter is structural: an exported declaration with a doc block
464
+ * and enough body to document. The ceiling is against a pathological
465
+ * repository rather than a budget anybody should reach.
466
+ */
467
+ docMatchesCode: {
468
+ maxDeclarations: 400,
469
+ /** Tokens below which a declaration has nothing for a doc to describe. */
470
+ minTokens: 40,
471
+ },
472
+ /**
473
+ * Declarations sent for judgement in one run.
474
+ *
475
+ * The candidate filter is structural and deliberately narrow -- an exported
476
+ * function, not a component, not a framework export, with enough in it to hold
477
+ * a rule -- so this is a ceiling rather than a budget.
478
+ */
479
+ hoistToDomain: {
480
+ maxDeclarations: 600,
481
+ /** Tokens below which a declaration cannot be holding a rule. */
482
+ minTokens: 40,
483
+ },
484
+ duplicateImplementation: {
485
+ maxClusters: 500,
486
+ /**
487
+ * Tokens below which a declaration is too small to be a duplicate of
488
+ * anything.
489
+ *
490
+ * Shape equality is exact, so this rule had no floor at all and grouped
491
+ * `type ErrorResponse = any` with `type ShippingTax = any` -- three
492
+ * one-line placeholders in two different apps, reported as "they are one
493
+ * thing". They are not; they are both `any`. The near-duplicate rule has
494
+ * carried a floor for this reason from the start.
495
+ */
496
+ minTokens: 8,
497
+ },
498
+ /**
499
+ * Name-family search.
500
+ *
501
+ * A pair of names is judged on its own; the rule does not cluster, because
502
+ * "is this name another spelling of that one" is a question about two things.
503
+ * Union-find over a non-transitive relation chained every `*Modal` in one
504
+ * codebase into a single eighty-seven member "concept", which is not a
505
+ * judgement anyone can make or act on.
506
+ */
507
+ namingDrift: {
508
+ /** Name-root overlap below which a pair is not worth a call. */
509
+ minScore: 0.5,
510
+ /**
511
+ * Words two names must share beyond a category noun. `AddContactModal` and
512
+ * `DeleteTaskModal` share one word and are two members of a category; two
513
+ * spellings of one concept share at least two.
514
+ */
515
+ minSharedWords: 2,
516
+ /**
517
+ * High on purpose. Name pairs are cheap to enumerate and cheap to judge, and
518
+ * a budget that truncates 1,564 of 1,864 real candidates is a bigger problem
519
+ * than the time it saves: it hides the rule's actual yield. Raise the
520
+ * evidence cost or tighten the candidate filter instead of capping this.
521
+ */
522
+ maxClusters: 4000,
523
+ },
524
+ /**
525
+ * When a page's own state and markup look like they belong in a bundle.
526
+ *
527
+ * These are TRIGGERS, not verdicts. The first version of this rule treated
528
+ * every file under `routes/` as a page that should conform, which produced
529
+ * 1,216 candidates against Shakti's 280 real route and modal files, flagged
530
+ * 392 of them, and gave the model almost nothing to be confident about: 237 of
531
+ * the flagged pages scored under 0.3. A page that composes local components
532
+ * and shares no state needs no bundle, so the rule now asks only about pages
533
+ * under actual state pressure.
534
+ */
535
+ pageNeedsComposition: {
536
+ /** useState calls before a page's state looks like a provider's business. */
537
+ minLocalState: 3,
538
+ /** Inline JSX elements before a page's markup looks like someone's block. */
539
+ minInlineElements: 15,
540
+ maxPages: 400,
541
+ },
542
+ /**
543
+ * The staged reversal: contract, then combine, then expand.
544
+ *
545
+ * `minTokens` is the floor below which a declaration is too small to be a copy
546
+ * of anything. `maxSites` bounds the judged stages; the contract stage is a
547
+ * proof and is never truncated.
548
+ */
549
+ reversal: {
550
+ minTokens: 8,
551
+ maxSites: 200,
552
+ },
553
+ /**
554
+ * Groups of differently named declarations the compiler proves are one type.
555
+ *
556
+ * A search bound, not a threshold: the proof is the checker's, so the only
557
+ * question is how many findings one report carries.
558
+ */
559
+ structuralCollapse: {
560
+ maxFindings: 200,
561
+ },
562
+ /**
563
+ * One name, several resolved types.
564
+ *
565
+ * Deterministic, because the compiler already decided: two declarations of one
566
+ * name that resolve to different printed types ARE two types. The finding is a
567
+ * fact; whether they should be one is the reader's call, and the help names
568
+ * every declaration so the reader can make it.
569
+ */
570
+ oneConceptOneType: {
571
+ /** Findings reported before the rest are counted and not listed. */
572
+ maxFindings: 20,
573
+ /** Characters of a resolved type shown before it is cut. */
574
+ maxTypeChars: 120,
575
+ },
576
+ /**
577
+ * The amplifier: a 5xx answer to a row that is simply not there.
578
+ *
579
+ * A missing row is a normal outcome -- a wrong id, a deleted record -- and
580
+ * answering "the server is broken" turns one bad request into an outage signal.
581
+ * There are no lookup-name lists here on purpose: which calls read a row is a
582
+ * judgement (`about_a_row`), not a name convention, and naming it in code was
583
+ * the classifier's work done ahead of time.
584
+ */
585
+ dataError: {
586
+ /** Handlers judged before the rest are counted and not asked about. */
587
+ maxHandlers: 40,
588
+ },
589
+ /**
590
+ * The compiler's per-declaration facts.
591
+ *
592
+ * `maxMembers` bounds how much of a type is printed: past it the structural
593
+ * fingerprint is partial, so the type gets no identicalGroup rather than a wrong
594
+ * one. `maxStrings` is the whole-run budget for the expensive call, and both are
595
+ * reported when they bite.
596
+ */
597
+ typeFacts: {
598
+ tsconfig: "tsconfig.json",
599
+ maxMembers: 64,
600
+ maxStrings: 12000,
601
+ },
602
+ /**
603
+ * How much of a cluster is described to the model.
604
+ *
605
+ * A cluster of two hundred declarations is one decision but not one question:
606
+ * sending every member's source blew the request budget and the API answered
607
+ * 400. The first N members are described and the rest are counted, so the
608
+ * decision still stands on the whole cluster even when the detail is bounded.
609
+ */
610
+ evidence: {
611
+ maxMembers: 12,
612
+ maxSourceChars: 1500,
613
+ /** Characters of a doc comment kept as evidence. */
614
+ maxDocChars: 400,
615
+ /** Paths listed in a finding's help before it says "and N more". */
616
+ maxListedPaths: 4,
617
+ },
618
+ /**
619
+ * What a test file looks like.
620
+ *
621
+ * Test files were 24 of 196 findings on one real repository, and the worst of
622
+ * them are not wrong: a factory or a fixture helper is SUPPOSED to be repeated,
623
+ * because that is what makes it a factory. A linter that reports it is
624
+ * reporting the technique. jev carries this regex; joggle had no notion of a
625
+ * test file at all, so a spec's helpers were held to the same standard as an
626
+ * API's.
627
+ */
628
+ testFiles: /(?:^|\/)(?:tests?|__tests__|specs?)(?:\/|$)|\.(?:spec|test)\.[cm]?[jt]sx?$/,
629
+ /**
630
+ * A shared path that discards items and does not say so.
631
+ *
632
+ * `nonDataReturns` is a DECLARED convention: the scalar types that cannot carry
633
+ * the items a caller reads. A function that returns only a flag or nothing does
634
+ * not shorten the caller's data, whatever `continue` it contains -- the review
635
+ * case returns a list, and the false candidate in this repository answers one
636
+ * boolean question. The filter only ever drops a declaration whose every
637
+ * recorded return is one of these; an array, a number or an unknown type stays.
638
+ */
639
+ unaccountedDrop: {
640
+ nonDataReturns: ["void", "undefined", "null", "boolean", "bigint", "symbol", "never"],
641
+ },
642
+ /**
643
+ * The strata a domain migration moves through.
644
+ *
645
+ * Everything here is a SEARCH BOUND, never a word list. Which table is a
646
+ * record, which value is a projection and which function is an invariant are
647
+ * questions for the classifier; a hand-maintained vocabulary of `ledger`,
648
+ * `snapshot` and `reconcile` would decide those questions in code, in the
649
+ * place least able to keep them current. What is left is how many candidates
650
+ * one run may judge, and how much evidence one candidate may carry.
651
+ */
652
+ strata: {
653
+ /** Candidates one strata rule may judge in a run. */
654
+ maxCandidates: 200,
655
+ /** Fields two structures must share before their overlap is worth a question. */
656
+ minSharedFields: 3,
657
+ /** Tokens a function needs before a table read can be a check rather than a getter. */
658
+ minInvariantTokens: 20,
659
+ },
660
+ /** Files and directories the workspace scan never enters. */
661
+ ignoredDirectories: [
662
+ "node_modules",
663
+ // Nested checkouts, as this repository keeps them: analysing them as part of
664
+ // the parent repo reports the child's own demo pages as the parent's.
665
+ "repos",
666
+ ".git",
667
+ "dist",
668
+ "build",
669
+ "out",
670
+ "coverage",
671
+ ".next",
672
+ ".turbo",
673
+ ".vercel",
674
+ ".cache",
675
+ ],
676
+ };