@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,89 @@
1
+ import { Effect } from "effect";
2
+ import { policy } from "../policy.js";
3
+ import { exactGroups } from "../candidates.js";
4
+ import { clusterOf } from "../cluster.js";
5
+ import { budgetNote, outcome } from "../rule.js";
6
+ import { clusterReporter, collapseQuestionnaire, planClusters, readClusters, unverifiedFinding, } from "./cluster-verdict.js";
7
+ import { layersFrom } from "../architecture.js";
8
+ const spec = {
9
+ ruleId: "joggle/duplicate-implementation",
10
+ severity: "warn",
11
+ move: "contract",
12
+ // Shape equality is a fact, so an unjudged cluster is still worth reporting.
13
+ onUnavailable: "report",
14
+ questionnaire: collapseQuestionnaire,
15
+ nameOf: (cluster) => {
16
+ const names = [...new Set(cluster.members.map((member) => member.name))];
17
+ return names.length === 1
18
+ ? `\`${names[0] ?? "?"}\` is declared ${cluster.members.length} times`
19
+ : `${cluster.members.length} declarations share one shape`;
20
+ },
21
+ };
22
+ /**
23
+ * A shape group *is* a cluster: every member has the same shape hash and the
24
+ * same resolved type identity. Broad on purpose -- over-production is the
25
+ * judge's problem, a missed copy is not.
26
+ */
27
+ const find = (workspace, scope) => exactGroups({
28
+ units: workspace.units,
29
+ kinds: ["shape"],
30
+ minTokens: policy.duplicateImplementation.minTokens,
31
+ distinctFiles: true,
32
+ separateTests: true,
33
+ scope,
34
+ }).map((group) => clusterOf(group.members, true, 1));
35
+ /** Largest clusters first when a budget bites, so the note names what matters. */
36
+ const largestOf = (clusters) => [...clusters]
37
+ .sort((a, b) => b.members.length - a.members.length)
38
+ .slice(0, 3)
39
+ .map((cluster) => `${cluster.members.length}× ${spec.nameOf(cluster)}`);
40
+ export const duplicateImplementation = {
41
+ id: spec.ruleId,
42
+ severity: spec.severity,
43
+ description: "One declaration written more than once across files.",
44
+ judged: true,
45
+ move: "contract",
46
+ onUnavailable: spec.onUnavailable,
47
+ plan: Effect.fn("joggle/duplicate-implementation")(function* (workspace, scope, context) {
48
+ const clusters = find(workspace, scope);
49
+ if (clusters.length === 0) {
50
+ return {
51
+ plans: [],
52
+ read: () => outcome([], ["no two declarations share a shape, so there was nothing to compare"]),
53
+ };
54
+ }
55
+ const budget = policy.duplicateImplementation.maxClusters;
56
+ const shapeOnly = clusters.filter((cluster) => !cluster.typed).length;
57
+ const phase = yield* planClusters(spec, clusters.slice(0, budget), scope, workspace);
58
+ const layers = layersFrom(context.config);
59
+ // Over budget: the fact is still reported, unjudged and labelled as such.
60
+ const report = clusterReporter(spec, workspace);
61
+ const overflow = clusters
62
+ .slice(budget)
63
+ .map((cluster) => unverifiedFinding({ report, rule: spec, cluster }))
64
+ .filter((entry) => entry !== undefined);
65
+ const notes = [
66
+ ...budgetNote({
67
+ unitKind: "clusters",
68
+ judged: budget,
69
+ candidates: clusters.length,
70
+ sample: largestOf(clusters.slice(budget)),
71
+ }),
72
+ // Visibility for the missing type signal. In a `.js` codebase every
73
+ // cluster is shape-only, and a reader who cannot see that will read the
74
+ // findings as typed evidence.
75
+ ...(shapeOnly === 0
76
+ ? []
77
+ : [
78
+ `${shapeOnly} of ${clusters.length} cluster(s) were compared by shape alone: no member carries a type annotation`,
79
+ ]),
80
+ ];
81
+ return {
82
+ plans: phase.planned.map((entry) => entry.plan),
83
+ read: (answers) => {
84
+ const judged = readClusters(spec, workspace, phase, layers, answers);
85
+ return outcome([...judged.diagnostics, ...overflow], notes, judged.drops);
86
+ },
87
+ };
88
+ }),
89
+ };
@@ -0,0 +1,130 @@
1
+ import { Effect } from "effect";
2
+ import { policy } from "../policy.js";
3
+ import { rankSpeculative, similarClusters, similarPairs, strengthOf } from "../candidates.js";
4
+ import {} from "../cluster.js";
5
+ import { budgetNote, outcome } from "../rule.js";
6
+ import { collapseQuestionnaire, planClusters, readClusters } from "./cluster-verdict.js";
7
+ import { layersFrom } from "../architecture.js";
8
+ import { nameList } from "../cluster.js";
9
+ const spec = {
10
+ ruleId: "joggle/duplicate-meaning",
11
+ severity: "warn",
12
+ move: "contract",
13
+ // A near-duplicate is a guess until a judgement says otherwise, so an
14
+ // unjudged cluster is silence and the rule reports itself as skipped.
15
+ onUnavailable: "propagate",
16
+ questionnaire: collapseQuestionnaire,
17
+ nameOf: (cluster) => `${cluster.members.length} declarations that may be one thing: ${nameList({ cluster })}`,
18
+ };
19
+ const find = (workspace, scope) => {
20
+ const { minSimilarity, maxSimilarity, minTokens } = policy.duplicateMeaning;
21
+ const pairs = similarPairs({
22
+ units: workspace.units,
23
+ minTokens,
24
+ minSimilarity,
25
+ maxSimilarity,
26
+ // Every kind is eligible; the engine keeps a pair to one kind.
27
+ kinds: undefined,
28
+ scope,
29
+ separateTests: true,
30
+ });
31
+ const clustered = similarClusters({
32
+ units: workspace.units,
33
+ pairs,
34
+ separateTests: true,
35
+ });
36
+ // A cluster bigger than the evidence panel cannot be a question. Only
37
+ // `policy.evidence.maxMembers` of its members are ever shown, so the model is
38
+ // asked about 105 declarations while looking at 12 of them -- and its answer
39
+ // is the only one available: no. One repository produced "105 declarations
40
+ // that may be one thing: down": every migration's `down` function, chained by
41
+ // union-find, none of which can be deleted.
42
+ //
43
+ // The bound is not a new threshold. It is the size at which the evidence stops
44
+ // being complete, which is the point at which the question stops being
45
+ // answerable.
46
+ const answerable = clustered.clusters.filter((cluster) => cluster.members.length <= policy.evidence.maxMembers);
47
+ return {
48
+ clusters: answerable,
49
+ oversized: clustered.clusters.filter((cluster) => cluster.members.length > policy.evidence.maxMembers),
50
+ chained: clustered.chained,
51
+ };
52
+ };
53
+ export const duplicateMeaning = {
54
+ id: spec.ruleId,
55
+ severity: spec.severity,
56
+ description: "Near-duplicates where a judgement says one declaration replaces the other.",
57
+ judged: true,
58
+ move: "contract",
59
+ onUnavailable: spec.onUnavailable,
60
+ plan: Effect.fn("joggle/duplicate-meaning")(function* (workspace, scope, context) {
61
+ const { clusters, oversized, chained } = find(workspace, scope);
62
+ const budget = policy.duplicateMeaning.maxClusters;
63
+ // Over budget, the clusters that get judged are the ones a reader is most
64
+ // likely to care about: a relevance judgement over a deterministic window,
65
+ // never a global sort by similarity (which is a selection, not a bound).
66
+ const ordered = yield* rankSpeculative({
67
+ budget,
68
+ items: clusters.map((cluster) => ({
69
+ item: cluster,
70
+ strength: strengthOf({ score: cluster.overlap, members: cluster.members.length }),
71
+ evidence: {
72
+ names: cluster.members.slice(0, 4).map((member) => member.name),
73
+ files: [...new Set(cluster.members.map((member) => member.file))].slice(0, 4),
74
+ signal: Math.round(cluster.overlap * 100) + "% structurally similar",
75
+ },
76
+ })),
77
+ });
78
+ const phase = yield* planClusters(spec, ordered.slice(0, budget), scope, workspace);
79
+ const layers = layersFrom(context.config);
80
+ const largest = ordered
81
+ .slice(budget)
82
+ .sort((a, b) => b.members.length - a.members.length)
83
+ .slice(0, 3)
84
+ .map((cluster) => `${cluster.members.length}× ${spec.nameOf(cluster)}`);
85
+ // Reported as drops rather than dropped silently: "476 declarations across 9
86
+ // clusters were generated from one template" is a fact about the codebase,
87
+ // and the only thing wrong with it was asking the model to confirm it.
88
+ const tooManyToShow = oversized.map((cluster) => ({
89
+ ruleId: spec.ruleId,
90
+ subject: spec.nameOf(cluster),
91
+ stage: "no_evidence",
92
+ reason: cluster.members.length +
93
+ " declarations share a shape, which is more than the " +
94
+ policy.evidence.maxMembers +
95
+ " the evidence panel can show at once",
96
+ }));
97
+ const notes = [
98
+ ...budgetNote({
99
+ unitKind: "clusters",
100
+ judged: budget,
101
+ candidates: clusters.length,
102
+ sample: largest,
103
+ }),
104
+ ...(oversized.length === 0
105
+ ? []
106
+ : [
107
+ oversized.length +
108
+ " cluster(s) were too large to be one decision (" +
109
+ oversized.reduce((sum, cluster) => sum + cluster.members.length, 0) +
110
+ " declarations): generated from one template rather than duplicated",
111
+ ]),
112
+ // What the clique requirement left out, because a silent narrowing is the
113
+ // thing this program keeps having to design against. These are members
114
+ // that resembled their neighbours without resembling each other.
115
+ ...(chained === 0
116
+ ? []
117
+ : [
118
+ chained +
119
+ " declaration(s) were left out of a cluster: they resembled a neighbour without resembling every member, so grouping them would have made a chain rather than a family",
120
+ ]),
121
+ ];
122
+ return {
123
+ plans: phase.planned.map((entry) => entry.plan),
124
+ read: (answers) => {
125
+ const judged = readClusters(spec, workspace, phase, layers, answers);
126
+ return outcome(judged.diagnostics, notes, [...tooManyToShow, ...judged.drops]);
127
+ },
128
+ };
129
+ }),
130
+ };
@@ -0,0 +1,202 @@
1
+ import { Effect } from "effect";
2
+ import { Decision } from "effect/ai";
3
+ import { Atoms } from "../atoms.js";
4
+ import { policy } from "../policy.js";
5
+ import { verdictsOf } from "../plans.js";
6
+ import { locator, messages, reporter } from "../reporting.js";
7
+ import { budgetNote, inScope, outcome, qualityOf, } from "../rule.js";
8
+ import { queryCallsIn } from "../sql.js";
9
+ import { verdictOf } from "../verdict.js";
10
+ const RULE_ID = "joggle/fact-or-derivation";
11
+ // One column, two possible meanings: a decision frozen at an instant, or a
12
+ // cheap recomputation of current data.
13
+ //
14
+ // `inferred-over-recorded` catches the small case in one function. This is the
15
+ // same defect at the size of a job: a call writes a column that a reader treats
16
+ // as recorded, so every change to the rules silently rewrites the past.
17
+ //
18
+ // The deterministic half is the call and the reader -- a structural shape, not
19
+ // a guess from the method name or the table's name. Which of the two meanings
20
+ // the column has belongs to the business, and the question says so.
21
+ export const factOrDerivation = {
22
+ id: RULE_ID,
23
+ severity: "warn",
24
+ description: "A call that recomputes a column a reader treats as a record.",
25
+ judged: true,
26
+ move: "expand",
27
+ onUnavailable: "report",
28
+ messages: messages({
29
+ recomputed: "`{{caller}}` recomputes `{{table}}`, which `{{reader}}` treats as recorded.",
30
+ recomputed_help: "A fact is what was decided on a date, from inputs that may since have changed; a derivation is cheap data recomputed now. If `{{table}}` records the past, stop refreshing it -- add a new row and leave the decision where it was made.{{unverified}}",
31
+ }),
32
+ plan: Effect.fn("joggle/fact-or-derivation")(function* (workspace, scope) {
33
+ const report = reporter(factOrDerivation, locator(workspace));
34
+ // A reader is any unit that names the table. This is a candidate filter,
35
+ // not proof: a unit may mention a table in a comment. The question is what
36
+ // the reader DOES with the value.
37
+ const readersOf = (table, writer) => workspace.units.filter((unit) => !(unit.file === writer.file && unit.name === writer.name) &&
38
+ unit.text.includes(table));
39
+ const candidates = [];
40
+ for (const file of workspace.files) {
41
+ if (scope.changed !== undefined && !inScope(scope, file.path))
42
+ continue;
43
+ for (const call of queryCallsIn(file.text)) {
44
+ const unit = file.units.find((candidate) => call.start >= candidate.start && call.start <= candidate.end);
45
+ if (unit === undefined)
46
+ continue;
47
+ const readers = readersOf(call.table, unit).slice(0, policy.evidence.maxListedPaths);
48
+ if (readers.length === 0)
49
+ continue;
50
+ candidates.push({ unit, call, readers });
51
+ }
52
+ }
53
+ if (candidates.length === 0) {
54
+ return {
55
+ plans: [],
56
+ read: () => outcome([], [
57
+ "no query-builder call reaches a table another unit reads",
58
+ ]),
59
+ };
60
+ }
61
+ const judged = candidates.slice(0, policy.strata.maxCandidates);
62
+ const overBudget = candidates
63
+ .slice(policy.strata.maxCandidates)
64
+ .map((candidate) => ({
65
+ ruleId: RULE_ID,
66
+ subject: candidate.unit.name,
67
+ stage: "budget",
68
+ reason: "past the budget of " + String(policy.strata.maxCandidates) + " writes",
69
+ }));
70
+ const atoms = yield* Atoms;
71
+ const planned = yield* Effect.forEach(judged, (candidate) => Effect.gen(function* () {
72
+ const id = yield* atoms.add({
73
+ column: {
74
+ table: candidate.call.table,
75
+ method: candidate.call.method,
76
+ writer: candidate.unit.name,
77
+ file: candidate.unit.file,
78
+ },
79
+ readers: candidate.readers.map((reader) => ({
80
+ name: reader.name,
81
+ file: reader.file,
82
+ })),
83
+ source: candidate.unit.text.slice(0, policy.evidence.maxSourceChars),
84
+ });
85
+ const plan = {
86
+ ruleId: RULE_ID,
87
+ subject: candidate.unit.name + " -> " + candidate.call.table,
88
+ concerns: [
89
+ candidate.unit.file,
90
+ ...candidate.readers.map((reader) => reader.file),
91
+ ],
92
+ atoms: [id],
93
+ violations: { verdict: ["recomputation"] },
94
+ decisions: {
95
+ verdict: Decision.classify({
96
+ instructions: {
97
+ question: "Is this column a decision frozen at an instant, or a cheap recomputation of current data?",
98
+ write: `\`atoms[${id}].column.writer\` calls \`atoms[${id}].column.table\`.\`atoms[${id}].column.method\``,
99
+ compare: [
100
+ `atoms[${id}].column`,
101
+ `atoms[${id}].readers`,
102
+ `atoms[${id}].source`,
103
+ ],
104
+ focus: "The readers are the tell. A reader that reports a number for today tolerates recomputation; a reader that reproduces what was decided on a date does not. Answer `recomputation` only when the structure is supposed to be append-only. A cheap derived column that policy refreshes is `neither`: staleness is `declared-staleness`'s question, and counting it here would ask it twice.",
105
+ },
106
+ criteria: {
107
+ fact: {
108
+ means: "The column freezes what was decided, with the inputs and authority of that instant.",
109
+ excludes: "A cached answer that may be recomputed from current rows.",
110
+ },
111
+ recomputation: {
112
+ means: "The column is recomputed from current rows, though the structure is supposed to record the past; changing the rules changes the record.",
113
+ excludes: "A projection whose staleness is a declared business choice.",
114
+ },
115
+ neither: {
116
+ means: "The column is not a derivation of recorded data, or it is a projection refreshed by policy.",
117
+ excludes: "A recomputation that silently rewrites a record.",
118
+ },
119
+ },
120
+ }),
121
+ },
122
+ read: (answers) => answers,
123
+ };
124
+ return { candidate, plan };
125
+ }), { concurrency: "unbounded" });
126
+ return {
127
+ plans: planned.map((entry) => entry.plan),
128
+ read: (answers) => {
129
+ const verdicts = verdictsOf(answers);
130
+ const diagnostics = [];
131
+ const drops = [...overBudget];
132
+ planned.forEach((entry, index) => {
133
+ const { candidate } = entry;
134
+ const subject = candidate.unit.name + " -> " + candidate.call.table;
135
+ const verdict = verdictOf(verdicts[index]?.["verdict"], ["recomputation"]);
136
+ if (verdict === undefined) {
137
+ diagnostics.push(findingFor({
138
+ report,
139
+ entry,
140
+ confidence: undefined,
141
+ unverifiedReason: "no judgement was available",
142
+ }));
143
+ return;
144
+ }
145
+ if (verdict.label !== "recomputation") {
146
+ drops.push({
147
+ ruleId: RULE_ID,
148
+ subject,
149
+ stage: "declined",
150
+ reason: verdict.label === "fact" ? "a frozen fact" : "not a derivation of a record",
151
+ });
152
+ return;
153
+ }
154
+ const quality = qualityOf({
155
+ score: verdict.probability,
156
+ margin: verdict.margin,
157
+ confidence: verdict.confidence,
158
+ });
159
+ if (quality.quality === "drop") {
160
+ drops.push({ ruleId: RULE_ID, subject, stage: "gated", reason: quality.reason });
161
+ return;
162
+ }
163
+ diagnostics.push(findingFor({
164
+ report,
165
+ entry,
166
+ confidence: verdict.confidence,
167
+ unverifiedReason: undefined,
168
+ review: quality.quality === "review",
169
+ }));
170
+ });
171
+ return outcome(diagnostics, budgetNote({
172
+ unitKind: "writes with a reader",
173
+ judged: judged.length,
174
+ candidates: candidates.length,
175
+ sample: candidates
176
+ .slice(policy.strata.maxCandidates)
177
+ .map((candidate) => candidate.unit.name + " -> " + candidate.call.table),
178
+ }), drops);
179
+ },
180
+ };
181
+ }),
182
+ };
183
+ const findingFor = ({ report, entry, confidence, unverifiedReason, review = false, }) => report({
184
+ about: { file: entry.candidate.unit.file, start: entry.candidate.call.start },
185
+ messageId: "recomputed",
186
+ data: {
187
+ caller: entry.candidate.unit.name,
188
+ table: entry.candidate.call.table,
189
+ reader: entry.candidate.readers[0]?.name ?? "a reader",
190
+ unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
191
+ },
192
+ helpId: "recomputed_help",
193
+ identity: [
194
+ RULE_ID,
195
+ entry.candidate.unit.file,
196
+ entry.candidate.unit.name,
197
+ entry.candidate.call.table,
198
+ ].join("\u0000"),
199
+ judged: unverifiedReason === undefined,
200
+ confidence,
201
+ severity: review ? "info" : "warn",
202
+ });