@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
@@ -0,0 +1,561 @@
1
+ import { Effect, Option, Order, Predicate, Schema } from "effect";
2
+ import { Decision, DecisionModel } from "effect/ai";
3
+ import { clusterOf, components } from "./cluster.js";
4
+ import { inScope } from "./rule.js";
5
+ import { allPairs } from "./similarity.js";
6
+ import { unitFields } from "./workspace.js";
7
+ /**
8
+ * The key one declaration contributes for a join, or undefined when it has none.
9
+ *
10
+ * `shape` includes the resolved type NAMES because two helpers that read
11
+ * identically and reference different declared types are not the same helper.
12
+ * `structure` is the checker's fingerprint, so it is the strongest key available
13
+ * and the only one that can prove two differently spelled declarations equal.
14
+ */
15
+ const keyOf = (unit, kind) => {
16
+ switch (kind) {
17
+ case "shape":
18
+ return Option.some(unit.kind + "\u0000" + unit.normalizedHash + "\u0000" + unit.typeSignature);
19
+ case "calls":
20
+ return unit.callSignature === ""
21
+ ? Option.none()
22
+ : Option.some(unit.kind + "\u0000" + unit.callSignature);
23
+ case "fields": {
24
+ const fields = [...unitFields(unit)].sort(Order.String);
25
+ return fields.length === 0 ? Option.none() : Option.some(fields.join("\u0000"));
26
+ }
27
+ case "structure": {
28
+ const facts = unit.typeFacts;
29
+ if (facts === undefined || facts.truncated)
30
+ return Option.none();
31
+ return Option.some(facts.structural);
32
+ }
33
+ case "values":
34
+ return unit.values.length === 0
35
+ ? Option.none()
36
+ : Option.some([...unit.values].sort(Order.String).join("\u0000"));
37
+ }
38
+ };
39
+ /**
40
+ * Every group an exact key forms, in one pass per key.
41
+ *
42
+ * When a declaration has several keys it can appear in several groups, and that
43
+ * is correct: one helper that shares a shape with one declaration and a call
44
+ * sequence with another is two real candidates. The caller decides which join it
45
+ * is asking about by naming the kinds.
46
+ */
47
+ export const exactGroups = (input) => {
48
+ const minMembers = input.minMembers === undefined ? 2 : input.minMembers;
49
+ const groups = [];
50
+ for (const keyKind of input.kinds) {
51
+ const byKey = new Map();
52
+ for (const unit of input.units) {
53
+ if (unit.tokens.length < input.minTokens)
54
+ continue;
55
+ const key = keyOf(unit, keyKind);
56
+ if (Option.isNone(key))
57
+ continue;
58
+ const composed = input.sameKind === true ? unit.kind + "\u0000" + key.value : key.value;
59
+ const existing = byKey.get(composed);
60
+ if (existing === undefined)
61
+ byKey.set(composed, [unit]);
62
+ else
63
+ existing.push(unit);
64
+ }
65
+ for (const members of byKey.values()) {
66
+ if (members.length < minMembers)
67
+ continue;
68
+ if (input.distinctFiles && new Set(members.map((unit) => unit.file)).size < 2)
69
+ continue;
70
+ if (input.distinctNames === true && new Set(members.map((unit) => unit.name)).size < 2)
71
+ continue;
72
+ if (input.separateTests === true && members.every((unit) => unit.test))
73
+ continue;
74
+ if (!members.some((unit) => inScope(input.scope, unit.file)))
75
+ continue;
76
+ groups.push({
77
+ keyKind,
78
+ members,
79
+ proof: true,
80
+ // Bigger is stronger for an exact proof: four copies are more evidence
81
+ // than two, and the ordering only decides which groups a budget keeps.
82
+ strength: Math.min(1, members.length / 10),
83
+ });
84
+ }
85
+ }
86
+ return groups.sort((left, right) => right.members.length - left.members.length ||
87
+ (left.members[0]?.name ?? "").localeCompare(right.members[0]?.name ?? ""));
88
+ };
89
+ /**
90
+ * Structurally close pairs, from the shingle sweep.
91
+ *
92
+ * Complete up to the provable length filter in {@link allPairs}: no qualifying
93
+ * pair is missed, so a budget is spent on judgement rather than on selection.
94
+ * The caller turns pairs into clusters; similarity is not transitive, so a
95
+ * cluster is a clique and that is the caller's invariant, not this one's.
96
+ */
97
+ export const similarPairs = (input) => {
98
+ const eligible = [];
99
+ input.units.forEach((unit, index) => {
100
+ if (unit.tokens.length < input.minTokens)
101
+ return;
102
+ if (input.kinds !== undefined && !input.kinds.includes(unit.kind))
103
+ return;
104
+ eligible.push({ unit, index });
105
+ });
106
+ const pairs = allPairs(eligible.map((entry) => ({ position: entry.index, shingles: entry.unit.shingles })), input.minSimilarity);
107
+ const found = [];
108
+ for (const pair of pairs) {
109
+ const left = input.units[pair.left];
110
+ const right = input.units[pair.right];
111
+ if (left === undefined || right === undefined)
112
+ continue;
113
+ if (pair.score > input.maxSimilarity)
114
+ continue;
115
+ if (left.file === right.file || left.kind !== right.kind)
116
+ continue;
117
+ if (input.separateTests === true && left.test && right.test)
118
+ continue;
119
+ if (!inScope(input.scope, left.file) && !inScope(input.scope, right.file))
120
+ continue;
121
+ found.push({ left, right, score: pair.score });
122
+ }
123
+ return found;
124
+ };
125
+ /**
126
+ * Turn a pair set into cliques, one cluster per clique.
127
+ *
128
+ * @param input.units - the declarations the pairs refer to.
129
+ * @param input.pairs - the pairs, already filtered.
130
+ * @param input.separateTests - true to drop a cluster that is test code only.
131
+ * @returns the clusters, and how many members a chain left out.
132
+ */
133
+ export const similarClusters = (input) => {
134
+ const positionOf = new Map();
135
+ input.units.forEach((unit, index) => positionOf.set(unit, index));
136
+ const scoreOf = new Map();
137
+ const adjacency = new Map();
138
+ const link = (from, to) => {
139
+ const existing = adjacency.get(from);
140
+ if (existing === undefined)
141
+ adjacency.set(from, new Set([to]));
142
+ else
143
+ existing.add(to);
144
+ };
145
+ const edges = [];
146
+ for (const pair of input.pairs) {
147
+ const left = positionOf.get(pair.left);
148
+ const right = positionOf.get(pair.right);
149
+ if (left === undefined || right === undefined)
150
+ continue;
151
+ scoreOf.set(left + ":" + right, pair.score);
152
+ scoreOf.set(right + ":" + left, pair.score);
153
+ link(left, right);
154
+ link(right, left);
155
+ edges.push([left, right]);
156
+ }
157
+ const adjacent = (one, other) => adjacency.get(one)?.has(other) === true;
158
+ const clusters = [];
159
+ let chained = 0;
160
+ for (const group of components(input.units.length, edges)) {
161
+ if (group.length < 2)
162
+ continue;
163
+ const ordered = [...group].sort((left, right) => (adjacency.get(right)?.size ?? 0) - (adjacency.get(left)?.size ?? 0));
164
+ const clique = [];
165
+ for (const index of ordered) {
166
+ if (clique.every((member) => adjacent(index, member)))
167
+ clique.push(index);
168
+ }
169
+ chained += group.length - clique.length;
170
+ if (clique.length < 2)
171
+ continue;
172
+ const members = clique
173
+ .map((index) => input.units[index])
174
+ .filter((unit) => unit !== undefined);
175
+ if (members.length < 2)
176
+ continue;
177
+ if (input.separateTests === true && members.every((unit) => unit.test))
178
+ continue;
179
+ let overlap = 0;
180
+ for (let a = 0; a < clique.length; a += 1) {
181
+ for (let b = a + 1; b < clique.length; b += 1) {
182
+ const left = clique[a];
183
+ const right = clique[b];
184
+ if (left === undefined || right === undefined)
185
+ continue;
186
+ const score = scoreOf.get(left + ":" + right) ?? 0;
187
+ if (score > overlap)
188
+ overlap = score;
189
+ }
190
+ }
191
+ clusters.push(clusterOf(members, false, overlap));
192
+ }
193
+ return { clusters, chained };
194
+ };
195
+ /* -------------------------------------------------------------------------- */
196
+ /* Names */
197
+ /* -------------------------------------------------------------------------- */
198
+ /**
199
+ * The words a name is made of.
200
+ *
201
+ * Split on case and separators, lowercased. The SHAPE of a name, not its
202
+ * meaning, which is why this is a lexical helper and not a classifier.
203
+ */
204
+ export const words = (name) => name
205
+ .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
206
+ .replace(/[_-]+/g, " ")
207
+ .toLowerCase()
208
+ .split(/\s+/)
209
+ .filter((word) => word.length > 0);
210
+ /**
211
+ * Abbreviations expanded before two names are compared.
212
+ *
213
+ * The one hand-written table in the join, and it exists so the judgement sees
214
+ * `orgId` and `organizationId` as the same phrase rather than as two strings.
215
+ */
216
+ const abbreviations = {
217
+ arg: "argument",
218
+ auth: "authentication",
219
+ cfg: "configuration",
220
+ config: "configuration",
221
+ ctx: "context",
222
+ db: "database",
223
+ dir: "directory",
224
+ doc: "document",
225
+ env: "environment",
226
+ err: "error",
227
+ fn: "function",
228
+ id: "identifier",
229
+ idx: "index",
230
+ img: "image",
231
+ impl: "implementation",
232
+ info: "information",
233
+ init: "initialize",
234
+ msg: "message",
235
+ nav: "navigation",
236
+ num: "number",
237
+ org: "organization",
238
+ param: "parameter",
239
+ prev: "previous",
240
+ repo: "repository",
241
+ req: "request",
242
+ res: "response",
243
+ spec: "specification",
244
+ src: "source",
245
+ stat: "statistic",
246
+ str: "string",
247
+ temp: "temporary",
248
+ tmp: "temporary",
249
+ util: "utility",
250
+ utils: "utility",
251
+ };
252
+ /** The same table, by word, so a lookup does not need an index signature. */
253
+ const ABBREVIATIONS = new Map(Object.entries(abbreviations));
254
+ /** Split a name into words and expand the abbreviations in the table. */
255
+ export const expanded = (name) => words(name).map((word) => ABBREVIATIONS.get(word) ?? word);
256
+ /**
257
+ * Jaccard over expanded words.
258
+ *
259
+ * @param input.one - the first name.
260
+ * @param input.two - the second name.
261
+ * @returns the overlap on [0, 1]; 0 when either name has no words.
262
+ */
263
+ export const nameScore = (input) => {
264
+ const left = new Set(expanded(input.one));
265
+ const right = new Set(expanded(input.two));
266
+ let intersection = 0;
267
+ for (const word of left)
268
+ if (right.has(word))
269
+ intersection += 1;
270
+ const union = left.size + right.size - intersection;
271
+ return union === 0 ? 0 : intersection / union;
272
+ };
273
+ /**
274
+ * Whether a pair of names is worth asking about.
275
+ *
276
+ * The whole difference between a rule that costs money and one that spends it.
277
+ * Identical expanded words always qualify (the spellings differ and nothing
278
+ * else); a name nested in the other by exactly one word qualifies, because
279
+ * whether that word carries meaning is the question the rule exists to ask.
280
+ */
281
+ export const worthJudging = (pair) => {
282
+ if (pair.one === pair.two)
283
+ return false;
284
+ const first = new Set(expanded(pair.one));
285
+ const second = new Set(expanded(pair.two));
286
+ let common = 0;
287
+ for (const word of first)
288
+ if (second.has(word))
289
+ common += 1;
290
+ const differs = first.size - common + (second.size - common);
291
+ if (differs === 0)
292
+ return true;
293
+ const nested = common === first.size || common === second.size;
294
+ return nested && differs === 1;
295
+ };
296
+ /**
297
+ * Words two names have in common, after expansion.
298
+ *
299
+ * @param input.one - the first name.
300
+ * @param input.two - the second name.
301
+ * @returns the count of shared words.
302
+ */
303
+ export const sharedWords = (input) => {
304
+ const first = new Set(expanded(input.one));
305
+ let shared = 0;
306
+ for (const word of new Set(expanded(input.two)))
307
+ if (first.has(word))
308
+ shared += 1;
309
+ return shared;
310
+ };
311
+ /**
312
+ * Pairs of exported names in the same head-noun family, one pair per question.
313
+ *
314
+ * There is no clustering: "is this name another spelling of that one" is a
315
+ * question about two things, and union-find over it chained every `*Modal` into
316
+ * one eighty-seven member "concept".
317
+ */
318
+ export const namePairs = (input) => {
319
+ const byHead = new Map();
320
+ for (const unit of input.units) {
321
+ if (input.exportedOnly && !unit.exported)
322
+ continue;
323
+ const head = expanded(unit.name).at(-1);
324
+ if (head === undefined)
325
+ continue;
326
+ const existing = byHead.get(head);
327
+ if (existing === undefined)
328
+ byHead.set(head, [unit]);
329
+ else
330
+ existing.push(unit);
331
+ }
332
+ const found = [];
333
+ for (const family of byHead.values()) {
334
+ for (let a = 0; a < family.length; a += 1) {
335
+ for (let b = a + 1; b < family.length; b += 1) {
336
+ const one = family[a];
337
+ const two = family[b];
338
+ if (one === undefined || two === undefined)
339
+ continue;
340
+ if (one.name === two.name || one.file === two.file || one.kind !== two.kind)
341
+ continue;
342
+ if (one.test && two.test)
343
+ continue;
344
+ if (sharedWords({ one: one.name, two: two.name }) < input.minSharedWords)
345
+ continue;
346
+ if (!inScope(input.scope, one.file) && !inScope(input.scope, two.file))
347
+ continue;
348
+ const score = nameScore({ one: one.name, two: two.name });
349
+ if (score < input.minScore)
350
+ continue;
351
+ if (!worthJudging({ one: one.name, two: two.name }))
352
+ continue;
353
+ found.push({ left: one, right: two, score });
354
+ }
355
+ }
356
+ }
357
+ return found.sort((left, right) => right.score - left.score ||
358
+ left.left.name.localeCompare(right.left.name) ||
359
+ left.right.name.localeCompare(right.right.name));
360
+ };
361
+ /* -------------------------------------------------------------------------- */
362
+ /* Field sets */
363
+ /* -------------------------------------------------------------------------- */
364
+ /**
365
+ * Field groups that repeat without a name.
366
+ *
367
+ * Pair co-occurrence, then the intersection of the declarations that carry a
368
+ * pair, gives GROUPS without mining every subset of every declaration. The
369
+ * result is a group of field names and the declarations that contain all of
370
+ * them, which is exactly what `name-the-primitive` asks about.
371
+ */
372
+ export const fieldGroups = (input) => {
373
+ const signatureOf = (fields) => [...fields].sort(Order.String).join("\u0000");
374
+ const named = new Set(input.units.map((unit) => signatureOf(unitFields(unit))));
375
+ const pairOccurrences = new Map();
376
+ for (const unit of input.units) {
377
+ const fields = [...new Set(unitFields(unit))];
378
+ for (let a = 0; a < fields.length; a += 1) {
379
+ for (let b = a + 1; b < fields.length; b += 1) {
380
+ const left = fields[a];
381
+ const right = fields[b];
382
+ if (left === undefined || right === undefined)
383
+ continue;
384
+ const key = signatureOf([left, right]);
385
+ const existing = pairOccurrences.get(key);
386
+ if (existing === undefined)
387
+ pairOccurrences.set(key, [unit]);
388
+ else
389
+ existing.push(unit);
390
+ }
391
+ }
392
+ }
393
+ const considered = [...pairOccurrences.entries()]
394
+ .filter(([, units]) => units.length >= input.minOccurrences)
395
+ .sort((left, right) => right[1].length - left[1].length || left[0].localeCompare(right[0]));
396
+ const groups = [];
397
+ for (const [, units] of considered) {
398
+ const first = units[0];
399
+ if (first === undefined)
400
+ continue;
401
+ let group = new Set(unitFields(first));
402
+ for (const unit of units) {
403
+ const fields = new Set(unitFields(unit));
404
+ group = new Set([...group].filter((field) => fields.has(field)));
405
+ }
406
+ if (group.size < input.minFields)
407
+ continue;
408
+ if (named.has(signatureOf([...group])))
409
+ continue;
410
+ groups.push({ units, fields: [...group].sort(Order.String) });
411
+ }
412
+ groups.sort((left, right) => right.fields.length - left.fields.length ||
413
+ right.units.length - left.units.length ||
414
+ left.fields.join(",").localeCompare(right.fields.join(",")));
415
+ // A group already contained in a larger reported group is the same finding
416
+ // twice: `{id, project}` beside the five-field group that contains it.
417
+ const kept = [];
418
+ const candidates = [];
419
+ for (const entry of groups) {
420
+ const first = entry.units[0];
421
+ if (first === undefined)
422
+ continue;
423
+ if (!inScope(input.scope, first.file))
424
+ continue;
425
+ if (kept.some((seen) => entry.fields.every((field) => seen.includes(field))))
426
+ continue;
427
+ kept.push(entry.fields);
428
+ candidates.push(entry);
429
+ }
430
+ return candidates;
431
+ };
432
+ /**
433
+ * Containment pairs: one declaration's field set is a proper subset of another's.
434
+ *
435
+ * Field-NAME containment is the fact. Whether the two are genuinely one type
436
+ * composed of another is the question, and the word-subset test that used to
437
+ * live here decided a type question in code.
438
+ */
439
+ export const containmentPairs = (input) => {
440
+ const all = input.units.filter((unit) => input.kinds.includes(unit.kind) && unitFields(unit).length >= input.minFields);
441
+ const bounded = all.slice(0, input.maxTypes);
442
+ const signatureOf = (unit) => [...unitFields(unit)].sort(Order.String).join("\u0000");
443
+ const parts = new Map();
444
+ for (const unit of bounded) {
445
+ const signature = signatureOf(unit);
446
+ if (!parts.has(signature))
447
+ parts.set(signature, unit);
448
+ }
449
+ const candidates = [];
450
+ for (const whole of bounded) {
451
+ if (!inScope(input.scope, whole.file))
452
+ continue;
453
+ const wholeFields = new Set(unitFields(whole));
454
+ let best;
455
+ for (const part of parts.values()) {
456
+ if (unitFields(part).length >= unitFields(whole).length)
457
+ continue;
458
+ if (best !== undefined && unitFields(part).length <= unitFields(best).length)
459
+ continue;
460
+ if (unitFields(whole).length - unitFields(part).length > unitFields(part).length)
461
+ continue;
462
+ const contained = unitFields(part).every((field) => wholeFields.has(field));
463
+ if (contained)
464
+ best = part;
465
+ }
466
+ if (best === undefined)
467
+ continue;
468
+ candidates.push({
469
+ whole,
470
+ part: best,
471
+ added: unitFields(whole).filter((field) => !unitFields(best).includes(field)),
472
+ });
473
+ }
474
+ return candidates;
475
+ };
476
+ /* -------------------------------------------------------------------------- */
477
+ /* Ranking (the one judgement) */
478
+ /* -------------------------------------------------------------------------- */
479
+ /** What the ranker sees about one speculative candidate. Bounded by construction. */
480
+ export const RankEvidence = Schema.Struct({
481
+ names: Schema.Array(Schema.String),
482
+ files: Schema.Array(Schema.String),
483
+ signal: Schema.String,
484
+ });
485
+ const RankInput = Schema.Struct({
486
+ candidates: Schema.Array(RankEvidence),
487
+ });
488
+ const RANK_INSTRUCTIONS = [
489
+ "Each entry of `candidates` is a pair or group of declarations a mechanical join put together.",
490
+ "Answer whether a reader who is fixing one of them would need to look at the others: does comparing them change what someone would do?",
491
+ "Answer true when they could be one concept written twice, or two spellings of one name.",
492
+ "Answer false when they are unrelated declarations that only scored alike: different purposes, a generic utility, a test fixture beside the code it tests.",
493
+ ].join("\n");
494
+ /**
495
+ * Reorder speculative candidates by one relevance judgement, in one request.
496
+ *
497
+ * Only ever called with GUESSES. A proof -- identical shape, identical resolved
498
+ * type, identical call sequence -- is never passed through here, because a
499
+ * relevance answer cannot overrule the compiler.
500
+ *
501
+ * The deterministic strength orders the candidates BEFORE the request and bounds
502
+ * the window the model sees: a thousand name pairs are trimmed to twice the
503
+ * budget so the request stays inside the provider's ceiling, and the judgement
504
+ * decides which half of that window is worth it. Everything beyond the window
505
+ * keeps its deterministic order and stays named in the caller's note.
506
+ *
507
+ * @param input.items - the candidates, in deterministic order.
508
+ * @param input.budget - how many the caller will judge.
509
+ * @returns every item, reordered: the judged window first by probability, then the rest.
510
+ */
511
+ export const rankSpeculative = (input) => {
512
+ const ordered = [...input.items].sort((left, right) => right.strength - left.strength ||
513
+ (left.evidence.names[0] ?? "").localeCompare(right.evidence.names[0] ?? ""));
514
+ if (ordered.length <= input.budget)
515
+ return Effect.succeed(ordered.map((entry) => entry.item));
516
+ const window = ordered.slice(0, Math.max(input.budget, input.budget * 2));
517
+ const rest = ordered.slice(window.length);
518
+ const decide = Effect.gen(function* () {
519
+ const decisions = {};
520
+ window.forEach((_entry, index) => {
521
+ decisions["keep_" + String(index)] = Decision.probability({
522
+ instructions: RANK_INSTRUCTIONS,
523
+ criteria: {
524
+ false: "Unrelated. Comparing them would not change what someone does.",
525
+ true: "Worth comparing. They may be one concept or one name spelled twice.",
526
+ },
527
+ });
528
+ });
529
+ const definition = Decision.make({
530
+ input: RankInput,
531
+ decisions,
532
+ });
533
+ const decided = yield* DecisionModel.decide(definition, {
534
+ input: { candidates: window.map((entry) => entry.evidence) },
535
+ });
536
+ const scored = window.map((entry, index) => {
537
+ const answer = decided.answers["keep_" + String(index)];
538
+ const probability = answer !== undefined && "probability" in answer ? answer.probability : 0;
539
+ return { entry, probability };
540
+ });
541
+ scored.sort((left, right) => right.probability - left.probability ||
542
+ right.entry.strength - left.entry.strength ||
543
+ (left.entry.evidence.names[0] ?? "").localeCompare(right.entry.evidence.names[0] ?? ""));
544
+ return [...scored.map((entry) => entry.entry.item), ...rest.map((entry) => entry.item)];
545
+ });
546
+ // A ranker that cannot answer is not a reason to lose the rule: the
547
+ // deterministic order is already the fallback, and the caller's note still says
548
+ // how many were not judged. Swallowing every failure is deliberate -- the
549
+ // question only reorders a budget, so a broken model costs ordering, not a
550
+ // candidate.
551
+ return decide.pipe(Effect.orElseSucceed(() => [
552
+ ...window.map((entry) => entry.item),
553
+ ...rest.map((entry) => entry.item),
554
+ ]));
555
+ };
556
+ /**
557
+ * A deterministic strength for a pair, from the evidence a join already has.
558
+ *
559
+ * Used only to order the window the ranker sees; it never decides a finding.
560
+ */
561
+ export const strengthOf = (input) => Math.min(1, input.score + Math.min(0.2, input.members / 50));
@@ -0,0 +1,24 @@
1
+ import { isRecord } from "./workspace.js";
2
+ /**
3
+ * Stable JSON, for a content-addressed cache key.
4
+ *
5
+ * The key must not depend on property insertion order, or a replay in CI would
6
+ * miss the judgement recorded locally. It is deliberately untyped: its whole job
7
+ * is to accept whatever JSON a request carries and produce the same string for
8
+ * the same value, and a domain type here would lie about what it does.
9
+ */
10
+ export const canonical = (value) => {
11
+ const encode = (input) => {
12
+ if (Array.isArray(input))
13
+ return input.map((item) => encode(item));
14
+ if (isRecord(input)) {
15
+ const out = {};
16
+ for (const key of Object.keys(input).sort((left, right) => left.localeCompare(right))) {
17
+ out[key] = encode(input[key]);
18
+ }
19
+ return out;
20
+ }
21
+ return input;
22
+ };
23
+ return JSON.stringify(encode(value));
24
+ };
@@ -0,0 +1,98 @@
1
+ import { lineStarts } from "./workspace.js";
2
+ /**
3
+ * The 1-based line of a character offset.
4
+ *
5
+ * @param starts - The offsets from {@link lineStarts}.
6
+ * @param offset - The character offset to locate.
7
+ * @returns The 1-based line number.
8
+ */
9
+ export const lineAt = (starts, offset) => {
10
+ let low = 0;
11
+ let high = starts.length - 1;
12
+ while (low < high) {
13
+ const middle = Math.ceil((low + high) / 2);
14
+ if ((starts[middle] ?? 0) <= offset)
15
+ low = middle;
16
+ else
17
+ high = middle - 1;
18
+ }
19
+ return low + 1;
20
+ };
21
+ /**
22
+ * Every site that must change when `keep` replaces `drops`.
23
+ *
24
+ * Three walks, because there are three ways to name a declaration: the import,
25
+ * the call, and the type. Code computes all three.
26
+ *
27
+ * This is the half of a repair the model must never produce. A model that listed
28
+ * forty-seven call sites would invent some of them, and an invented site is a
29
+ * broken edit that looks exactly like a real one. The model decides identity --
30
+ * these declarations are one thing -- and this decides what that costs.
31
+ *
32
+ * @param workspace - The analysed workspace, whose graphs carry the edges.
33
+ * @param keep - The declaration that survives.
34
+ * @param drops - The declarations that go.
35
+ * @returns The edits, in the order a person would make them: imports, calls, types.
36
+ */
37
+ export const cascadeOf = (workspace, keep, drops) => {
38
+ const edits = [];
39
+ const seen = new Set();
40
+ const starts = new Map();
41
+ const push = (edit) => {
42
+ const key = [edit.file, edit.line, edit.column, edit.instruction].join("\u0000");
43
+ if (seen.has(key))
44
+ return;
45
+ seen.add(key);
46
+ edits.push(edit);
47
+ };
48
+ const startsOf = (file, text) => {
49
+ const known = starts.get(file);
50
+ if (known !== undefined)
51
+ return known;
52
+ const found = lineStarts(text);
53
+ starts.set(file, found);
54
+ return found;
55
+ };
56
+ for (const drop of drops) {
57
+ const identity = drop.file + "#" + drop.name;
58
+ // 1. The importers. They must take the survivor's name from the survivor.
59
+ for (const edge of workspace.imports.importersOfName(drop.file, drop.name)) {
60
+ push({
61
+ file: edge.importer,
62
+ line: 1,
63
+ column: 1,
64
+ instruction: "import `" + keep.name + "` from `" + keep.file + "` instead of `" +
65
+ drop.name + "` from `" + drop.file + "`",
66
+ });
67
+ }
68
+ // 2. The call sites. `unit.calls` is built from the same filter in the same
69
+ // order, so the index pairs a resolved callee with the span that made it.
70
+ for (const file of workspace.files) {
71
+ for (const unit of file.units) {
72
+ const sites = file.facts.callSites.filter((site) => site.start >= unit.start && site.end <= unit.end);
73
+ sites.forEach((site, index) => {
74
+ if (unit.calls[index] !== identity)
75
+ return;
76
+ push({
77
+ file: file.path,
78
+ line: lineAt(startsOf(file.path, file.text), site.start),
79
+ column: 1,
80
+ instruction: "call `" + keep.name + "` in " + keep.file,
81
+ });
82
+ });
83
+ }
84
+ }
85
+ // 3. The type names, so the shape follows the name.
86
+ for (const unit of workspace.units) {
87
+ if (!unit.typeSignature.split("|").includes(identity))
88
+ continue;
89
+ push({
90
+ file: unit.file,
91
+ line: unit.location.line,
92
+ column: 1,
93
+ instruction: "`" + drop.name + "` now resolves to " + keep.file,
94
+ });
95
+ }
96
+ }
97
+ return edits;
98
+ };