@autotelic/joggle 0.0.0-stage → 0.1.2
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.
- package/JOGGLE.md +634 -0
- package/LICENSE +21 -0
- package/README.md +88 -2
- package/bin/joggle.js +6 -0
- package/dist/answer-store.js +305 -0
- package/dist/architecture.js +190 -0
- package/dist/ask.js +184 -0
- package/dist/astro.js +75 -0
- package/dist/atoms.js +76 -0
- package/dist/bundles.js +156 -0
- package/dist/calibration.js +60 -0
- package/dist/candidates.js +561 -0
- package/dist/canonical.js +24 -0
- package/dist/cascade.js +98 -0
- package/dist/check.js +854 -0
- package/dist/cluster.js +69 -0
- package/dist/config.js +195 -0
- package/dist/content-mappers.js +83 -0
- package/dist/decision.js +203 -0
- package/dist/fingerprint.js +61 -0
- package/dist/git.js +127 -0
- package/dist/gitignore.js +65 -0
- package/dist/glob.js +51 -0
- package/dist/imports.js +153 -0
- package/dist/jsonc.js +95 -0
- package/dist/main.js +630 -0
- package/dist/manifest.js +42 -0
- package/dist/meta.js +170 -0
- package/dist/moves.js +47 -0
- package/dist/operation.js +133 -0
- package/dist/parsecache.js +264 -0
- package/dist/plans.js +425 -0
- package/dist/plugin.js +71 -0
- package/dist/plugins.js +136 -0
- package/dist/policy.js +676 -0
- package/dist/presets/composition.js +32 -0
- package/dist/report.js +474 -0
- package/dist/reporting.js +132 -0
- package/dist/result.js +28 -0
- package/dist/roles.js +303 -0
- package/dist/rule.js +194 -0
- package/dist/rules/append-only-honoured.js +190 -0
- package/dist/rules/bundle-conformance.js +245 -0
- package/dist/rules/call-pattern.js +209 -0
- package/dist/rules/cluster-verdict.js +700 -0
- package/dist/rules/compose-types.js +250 -0
- package/dist/rules/data-error-as-outage.js +482 -0
- package/dist/rules/declared-staleness.js +242 -0
- package/dist/rules/dependency-fit.js +297 -0
- package/dist/rules/deviation-has-a-shape.js +225 -0
- package/dist/rules/doc-matches-code.js +191 -0
- package/dist/rules/duplicate-call-run.js +240 -0
- package/dist/rules/duplicate-implementation.js +89 -0
- package/dist/rules/duplicate-meaning.js +130 -0
- package/dist/rules/fact-or-derivation.js +202 -0
- package/dist/rules/field-type-drift.js +373 -0
- package/dist/rules/generic-carries-a-caller.js +198 -0
- package/dist/rules/hoist-to-domain.js +288 -0
- package/dist/rules/import-architecture.js +393 -0
- package/dist/rules/index.js +105 -0
- package/dist/rules/inferred-over-recorded.js +214 -0
- package/dist/rules/intent-drift.js +286 -0
- package/dist/rules/invariant-has-a-reconciler.js +190 -0
- package/dist/rules/language-drift.js +234 -0
- package/dist/rules/meaning-switched-by-flag.js +189 -0
- package/dist/rules/module-direction.js +231 -0
- package/dist/rules/name-as-address.js +216 -0
- package/dist/rules/name-the-primitive.js +203 -0
- package/dist/rules/naming-drift.js +218 -0
- package/dist/rules/nullability-drift.js +220 -0
- package/dist/rules/object-shape.js +280 -0
- package/dist/rules/one-concept-one-type.js +243 -0
- package/dist/rules/page-needs-composition.js +227 -0
- package/dist/rules/reimplemented-primitive.js +283 -0
- package/dist/rules/reversal.js +264 -0
- package/dist/rules/rule-judgment.js +252 -0
- package/dist/rules/schema-excludes-domain-value.js +190 -0
- package/dist/rules/shallow-module.js +204 -0
- package/dist/rules/single-path.js +237 -0
- package/dist/rules/structural-collapse.js +198 -0
- package/dist/rules/temporal-coupling.js +205 -0
- package/dist/rules/types-over-logic.js +198 -0
- package/dist/rules/unaccounted-drop.js +190 -0
- package/dist/rules/unbounded-default-read.js +227 -0
- package/dist/run-cache.js +132 -0
- package/dist/schema.js +285 -0
- package/dist/similarity.js +119 -0
- package/dist/source.js +30 -0
- package/dist/sql.js +34 -0
- package/dist/stages.js +39 -0
- package/dist/state.js +65 -0
- package/dist/testing.js +131 -0
- package/dist/tsconfig-scope.js +32 -0
- package/dist/tsgo.js +127 -0
- package/dist/typefacts.js +455 -0
- package/dist/typetrace.js +283 -0
- package/dist/verdict.js +65 -0
- package/dist/vocabulary.js +365 -0
- package/dist/workspace.js +1963 -0
- package/extensions/joggle.ts +454 -0
- package/package.json +85 -3
|
@@ -0,0 +1,214 @@
|
|
|
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 { verdictOf } from "../verdict.js";
|
|
9
|
+
const RULE_ID = "joggle/inferred-over-recorded";
|
|
10
|
+
// A fact the code derives that a field already records.
|
|
11
|
+
//
|
|
12
|
+
// From PR 1570: the mode is inferred from the sums, but the payroll already
|
|
13
|
+
// records `use_swa_day_rate` -- "could we pass that through and make this
|
|
14
|
+
// deterministic?". The derivation is a second source of truth, and the two
|
|
15
|
+
// disagree the moment one changes.
|
|
16
|
+
//
|
|
17
|
+
// Three facts, and none classifies:
|
|
18
|
+
//
|
|
19
|
+
// the comparison an AST `BinaryExpression` with a comparison operator -- a
|
|
20
|
+
// language construct, and the unit returns
|
|
21
|
+
// the row a type the unit names, from `typeRefs`
|
|
22
|
+
// the record a `boolean` field on that type that the unit does not read
|
|
23
|
+
//
|
|
24
|
+
// Whether the computation RECONSTRUCTS the recorded field is the question.
|
|
25
|
+
//
|
|
26
|
+
// An earlier shape asked the CHECKER whether the returned expression is a
|
|
27
|
+
// boolean. Neither type layer answers that: the node-type layer resolves the
|
|
28
|
+
// token at a position (hover), so a binary expression's offset answers its left
|
|
29
|
+
// operand, and the declaration trace carries interfaces and aliases rather than
|
|
30
|
+
// function signatures. A comparison is a language construct read from the AST,
|
|
31
|
+
// not a repository idiom, so it is a fact -- the same standing as a guard shape.
|
|
32
|
+
const declaredOf = (annotation) => annotation.replace(/^\s*:\s*/, "").replace(/\s+/g, " ").trim();
|
|
33
|
+
export const inferredOverRecorded = {
|
|
34
|
+
id: RULE_ID,
|
|
35
|
+
severity: "warn",
|
|
36
|
+
description: "A value the code derives that a field already records.",
|
|
37
|
+
judged: true,
|
|
38
|
+
move: "contract",
|
|
39
|
+
onUnavailable: "report",
|
|
40
|
+
messages: messages({
|
|
41
|
+
inferred: "{{unit}} derives a boolean though `{{type}}` records one in `{{flag}}`.",
|
|
42
|
+
inferred_help: "Read `{{flag}}` instead of deriving it. Two sources of truth for one fact drift: the recorded field is written when the row is saved and the derivation is computed when it is read, and the first time they disagree nobody can tell which is right.{{unverified}}",
|
|
43
|
+
}),
|
|
44
|
+
plan: Effect.fn("joggle/inferred-over-recorded")(function* (workspace, scope) {
|
|
45
|
+
const report = reporter(inferredOverRecorded, locator(workspace));
|
|
46
|
+
// The boolean fields, by the type that declares them.
|
|
47
|
+
const booleanFields = new Map();
|
|
48
|
+
const unitOfType = new Map();
|
|
49
|
+
for (const unit of workspace.units) {
|
|
50
|
+
if (unit.kind !== "interface" && unit.kind !== "type")
|
|
51
|
+
continue;
|
|
52
|
+
for (const [field, annotation] of unit.fieldTypes) {
|
|
53
|
+
if (declaredOf(annotation) !== "boolean")
|
|
54
|
+
continue;
|
|
55
|
+
const fields = booleanFields.get(unit.name) ?? [];
|
|
56
|
+
fields.push(field);
|
|
57
|
+
booleanFields.set(unit.name, fields);
|
|
58
|
+
unitOfType.set(unit.name, unit);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
const candidates = [];
|
|
62
|
+
for (const file of workspace.files) {
|
|
63
|
+
if (scope.changed !== undefined && !inScope(scope, file.path))
|
|
64
|
+
continue;
|
|
65
|
+
for (const unit of file.units) {
|
|
66
|
+
if (unit.kind !== "function")
|
|
67
|
+
continue;
|
|
68
|
+
if (unit.text.length > policy.evidence.maxSourceChars)
|
|
69
|
+
continue;
|
|
70
|
+
// The comparison must be the value the unit RETURNS. A function that
|
|
71
|
+
// merely contains a comparison and then hands back a list or a number
|
|
72
|
+
// derives no boolean; `scriptsFrom`, `readIgnoreFile` and
|
|
73
|
+
// `timeoutMilliseconds` each did, and each was a false candidate.
|
|
74
|
+
const returnsTheComparison = file.facts.returns.some((returned) => returned.start >= unit.start &&
|
|
75
|
+
returned.end <= unit.end &&
|
|
76
|
+
file.facts.comparisons.some((comparison) => comparison.start >= returned.start && comparison.end <= returned.end));
|
|
77
|
+
if (!returnsTheComparison)
|
|
78
|
+
continue;
|
|
79
|
+
for (const type of new Set(unit.typeRefs)) {
|
|
80
|
+
const fields = booleanFields.get(type);
|
|
81
|
+
if (fields === undefined)
|
|
82
|
+
continue;
|
|
83
|
+
// A flag the unit already reads is not being inferred; it is being read.
|
|
84
|
+
const flag = fields.find((field) => !unit.text.includes(field));
|
|
85
|
+
if (flag === undefined)
|
|
86
|
+
continue;
|
|
87
|
+
candidates.push({ unit, type, flag, start: unit.start });
|
|
88
|
+
break;
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
if (candidates.length === 0) {
|
|
93
|
+
return {
|
|
94
|
+
plans: [],
|
|
95
|
+
read: () => outcome([], [
|
|
96
|
+
"no unit returns a boolean while naming a type that records one it does not read",
|
|
97
|
+
]),
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
const budget = policy.evidence.maxMembers * 12;
|
|
101
|
+
const judged = candidates.slice(0, budget);
|
|
102
|
+
const overBudget = candidates.slice(budget).map((candidate) => ({
|
|
103
|
+
ruleId: RULE_ID,
|
|
104
|
+
subject: candidate.unit.name,
|
|
105
|
+
stage: "budget",
|
|
106
|
+
reason: "past the budget of " + String(budget) + " derivations",
|
|
107
|
+
}));
|
|
108
|
+
const atoms = yield* Atoms;
|
|
109
|
+
const planned = yield* Effect.forEach(judged, (candidate) => Effect.gen(function* () {
|
|
110
|
+
const id = yield* atoms.add({
|
|
111
|
+
derivation: { unit: candidate.unit.name, file: candidate.unit.file },
|
|
112
|
+
recorded: {
|
|
113
|
+
type: candidate.type,
|
|
114
|
+
flag: candidate.flag,
|
|
115
|
+
owner: unitOfType.get(candidate.type)?.file ?? candidate.unit.file,
|
|
116
|
+
},
|
|
117
|
+
source: candidate.unit.text.slice(0, policy.evidence.maxSourceChars),
|
|
118
|
+
});
|
|
119
|
+
const plan = {
|
|
120
|
+
ruleId: RULE_ID,
|
|
121
|
+
subject: candidate.unit.name + " (derives " + candidate.flag + "?)",
|
|
122
|
+
concerns: [candidate.unit.file, unitOfType.get(candidate.type)?.file ?? candidate.unit.file],
|
|
123
|
+
atoms: [id],
|
|
124
|
+
violations: { verdict: ["inferred"] },
|
|
125
|
+
decisions: {
|
|
126
|
+
verdict: Decision.classify({
|
|
127
|
+
instructions: [
|
|
128
|
+
`\`atoms[${id}].source\` computes a boolean and returns it. \`atoms[${id}].recorded.type\` records a boolean \`atoms[${id}].recorded.flag\` that this unit does not read.`,
|
|
129
|
+
"Does the computation reconstruct the recorded field -- the same fact derived a second way?",
|
|
130
|
+
"Answer `inferred` when the returned boolean IS what the field records, so the derivation is a second source of truth for one fact.",
|
|
131
|
+
"Answer `independent` when the returned boolean is a different question from the recorded one, even if the two often agree.",
|
|
132
|
+
"Answer `not_applicable` when the type is not the row this unit reads, or the field is unrelated.",
|
|
133
|
+
].join("\n"),
|
|
134
|
+
criteria: {
|
|
135
|
+
inferred: "The same fact, derived a second time. Read the field.",
|
|
136
|
+
independent: "A different question that often agrees.",
|
|
137
|
+
not_applicable: "Not the same row or the same fact.",
|
|
138
|
+
},
|
|
139
|
+
}),
|
|
140
|
+
},
|
|
141
|
+
read: (answers) => answers,
|
|
142
|
+
};
|
|
143
|
+
return { candidate, plan };
|
|
144
|
+
}), { concurrency: "unbounded" });
|
|
145
|
+
return {
|
|
146
|
+
plans: planned.map((entry) => entry.plan),
|
|
147
|
+
read: (answers) => {
|
|
148
|
+
const verdicts = verdictsOf(answers);
|
|
149
|
+
const diagnostics = [];
|
|
150
|
+
const drops = [...overBudget];
|
|
151
|
+
planned.forEach((entry, index) => {
|
|
152
|
+
const { candidate } = entry;
|
|
153
|
+
const subject = candidate.unit.name + " (derives " + candidate.flag + "?)";
|
|
154
|
+
const verdict = verdictOf(verdicts[index]?.["verdict"], ["inferred"]);
|
|
155
|
+
if (verdict === undefined) {
|
|
156
|
+
diagnostics.push(findingFor({
|
|
157
|
+
report,
|
|
158
|
+
entry,
|
|
159
|
+
confidence: undefined,
|
|
160
|
+
unverifiedReason: "no judgement was available",
|
|
161
|
+
}));
|
|
162
|
+
return;
|
|
163
|
+
}
|
|
164
|
+
if (verdict.label !== "inferred") {
|
|
165
|
+
drops.push({
|
|
166
|
+
ruleId: RULE_ID,
|
|
167
|
+
subject,
|
|
168
|
+
stage: "declined",
|
|
169
|
+
reason: verdict.label === "independent" ? "a different question" : "not the same row or fact",
|
|
170
|
+
});
|
|
171
|
+
return;
|
|
172
|
+
}
|
|
173
|
+
const quality = qualityOf({
|
|
174
|
+
score: verdict.probability,
|
|
175
|
+
margin: verdict.margin,
|
|
176
|
+
confidence: verdict.confidence,
|
|
177
|
+
});
|
|
178
|
+
if (quality.quality === "drop") {
|
|
179
|
+
drops.push({ ruleId: RULE_ID, subject, stage: "gated", reason: quality.reason });
|
|
180
|
+
return;
|
|
181
|
+
}
|
|
182
|
+
diagnostics.push(findingFor({
|
|
183
|
+
report,
|
|
184
|
+
entry,
|
|
185
|
+
confidence: verdict.confidence,
|
|
186
|
+
unverifiedReason: undefined,
|
|
187
|
+
review: quality.quality === "review",
|
|
188
|
+
}));
|
|
189
|
+
});
|
|
190
|
+
return outcome(diagnostics, budgetNote({
|
|
191
|
+
unitKind: "derivations",
|
|
192
|
+
judged: budget,
|
|
193
|
+
candidates: candidates.length,
|
|
194
|
+
sample: candidates.slice(budget).map((candidate) => candidate.unit.name),
|
|
195
|
+
}), drops);
|
|
196
|
+
},
|
|
197
|
+
};
|
|
198
|
+
}),
|
|
199
|
+
};
|
|
200
|
+
const findingFor = ({ report, entry, confidence, unverifiedReason, review = false, }) => report({
|
|
201
|
+
about: entry.candidate.unit,
|
|
202
|
+
messageId: "inferred",
|
|
203
|
+
data: {
|
|
204
|
+
unit: entry.candidate.unit.name,
|
|
205
|
+
type: entry.candidate.type,
|
|
206
|
+
flag: entry.candidate.flag,
|
|
207
|
+
unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
|
|
208
|
+
},
|
|
209
|
+
helpId: "inferred_help",
|
|
210
|
+
identity: [RULE_ID, entry.candidate.unit.file, entry.candidate.unit.name, entry.candidate.type, entry.candidate.flag].join("\u0000"),
|
|
211
|
+
judged: unverifiedReason === undefined,
|
|
212
|
+
confidence,
|
|
213
|
+
severity: review ? "info" : "warn",
|
|
214
|
+
});
|
|
@@ -0,0 +1,286 @@
|
|
|
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 { verdictOf } from "../verdict.js";
|
|
8
|
+
import { budgetNote, inGraphScope, inScope, outcome, qualityOf, } from "../rule.js";
|
|
9
|
+
const RULE_ID = "joggle/intent-drift";
|
|
10
|
+
// meta-allow: no-pattern-classifier -- the regexes read TypeScript and JSDoc SYNTAX
|
|
11
|
+
// (a tag, an identifier, an import line), not meaning. Whether a live import is a
|
|
12
|
+
// defect is the model's question.
|
|
13
|
+
/** Which labels mean the migration promise is broken. */
|
|
14
|
+
const VIOLATIONS = { verdict: ["migrate", "fix_tag"] };
|
|
15
|
+
const isViolating = (label) => label === "migrate" || label === "fix_tag";
|
|
16
|
+
/**
|
|
17
|
+
* The names a `@deprecated` tag says to reach for.
|
|
18
|
+
*
|
|
19
|
+
* Backticked identifiers are unambiguous. Unbackticked names must be capitalized, which
|
|
20
|
+
* keeps ordinary prose ("use the new API") from becoming a phantom replacement. The tag
|
|
21
|
+
* ends at the next JSDoc tag, so a `@deprecated` line in a long doc block cannot borrow a
|
|
22
|
+
* name from `@param`.
|
|
23
|
+
*/
|
|
24
|
+
const replacementsOf = (doc) => {
|
|
25
|
+
if (doc === undefined)
|
|
26
|
+
return [];
|
|
27
|
+
const tag = /@deprecated\b([\s\S]*?)(?:\n\s*\*\s*@|$)/iu.exec(doc)?.[1] ?? "";
|
|
28
|
+
const names = new Set();
|
|
29
|
+
for (const match of tag.matchAll(/`([A-Za-z_$][\w$]*)`/gu)) {
|
|
30
|
+
if (match[1] !== undefined)
|
|
31
|
+
names.add(match[1]);
|
|
32
|
+
}
|
|
33
|
+
for (const match of tag.matchAll(/\b(?:use|prefer|replace(?:d)?\s+with|switch\s+to)\s+(?:`([^`]+)`|([A-Z][A-Za-z0-9_$]*))/gu)) {
|
|
34
|
+
const name = match[1] ?? match[2];
|
|
35
|
+
if (name !== undefined && !name.includes(" "))
|
|
36
|
+
names.add(name);
|
|
37
|
+
}
|
|
38
|
+
return [...names];
|
|
39
|
+
};
|
|
40
|
+
const isDeprecated = (unit) => /\B@deprecated\b/u.test(unit.doc ?? "");
|
|
41
|
+
/** Find the import statement and the binding, so the finding lands where a reader looks. */
|
|
42
|
+
const importSite = (file, edge, name) => {
|
|
43
|
+
if (file === undefined)
|
|
44
|
+
return { file: edge.importer, line: 1, column: 1 };
|
|
45
|
+
const lines = file.text.split("\n");
|
|
46
|
+
const start = lines.findIndex((line) => line.includes(edge.specifier) && /\b(?:import|export)\b/u.test(line));
|
|
47
|
+
const from = start === -1 ? 0 : start;
|
|
48
|
+
const end = Math.min(lines.length, from + 12);
|
|
49
|
+
for (let index = from; index < end; index += 1) {
|
|
50
|
+
if (name === "default" || name === "*") {
|
|
51
|
+
return { file: edge.importer, line: index + 1, column: 1 };
|
|
52
|
+
}
|
|
53
|
+
const line = lines[index] ?? "";
|
|
54
|
+
const at = line.indexOf(name);
|
|
55
|
+
if (at >= 0)
|
|
56
|
+
return { file: edge.importer, line: index + 1, column: at + 1 };
|
|
57
|
+
}
|
|
58
|
+
return { file: edge.importer, line: from + 1, column: 1 };
|
|
59
|
+
};
|
|
60
|
+
const replacementLabel = (names) => names.map((name) => `\`${name}\``).join(" or ");
|
|
61
|
+
/**
|
|
62
|
+
* Every diagnostic a candidate supports, narrowed to the repair the verdict chose.
|
|
63
|
+
*
|
|
64
|
+
* `unjudged` reports both halves, because without a verdict the facts are all a reader
|
|
65
|
+
* has. `migrate` reports only call sites and `fix_tag` only broken targets, so a model
|
|
66
|
+
* that picks one repair cannot make the rule print the other.
|
|
67
|
+
*/
|
|
68
|
+
const findingsFor = (report, candidate, mode, provenance, confidence) => {
|
|
69
|
+
const { judged, review } = provenance;
|
|
70
|
+
const diagnostics = [];
|
|
71
|
+
const severity = review ? "info" : undefined;
|
|
72
|
+
for (const name of mode === "migrate" ? [] : candidate.unknown) {
|
|
73
|
+
diagnostics.push(report({
|
|
74
|
+
about: candidate.unit,
|
|
75
|
+
messageId: "missing_replacement",
|
|
76
|
+
data: { name: candidate.unit.name, replacement: replacementLabel([name]) },
|
|
77
|
+
helpId: "missing_replacement_help",
|
|
78
|
+
judged,
|
|
79
|
+
...(severity === undefined ? {} : { severity }),
|
|
80
|
+
...(confidence === undefined ? {} : { confidence }),
|
|
81
|
+
identity: [RULE_ID, candidate.unit.file, candidate.unit.name, name].join("\u0000"),
|
|
82
|
+
}));
|
|
83
|
+
}
|
|
84
|
+
const hasTarget = candidate.declared.length > 0;
|
|
85
|
+
for (const { edge, site } of mode === "fix_tag" ? [] : candidate.imports) {
|
|
86
|
+
diagnostics.push(report({
|
|
87
|
+
about: site,
|
|
88
|
+
messageId: hasTarget ? "deprecated_import" : "deprecated_import_no_target",
|
|
89
|
+
data: {
|
|
90
|
+
name: candidate.unit.name,
|
|
91
|
+
replacement: replacementLabel(candidate.declared),
|
|
92
|
+
file: candidate.unit.file,
|
|
93
|
+
},
|
|
94
|
+
...(hasTarget
|
|
95
|
+
? { helpId: "deprecated_import_help" }
|
|
96
|
+
: { helpId: "deprecated_import_no_target_help" }),
|
|
97
|
+
judged,
|
|
98
|
+
...(severity === undefined ? {} : { severity }),
|
|
99
|
+
...(confidence === undefined ? {} : { confidence }),
|
|
100
|
+
identity: [RULE_ID, edge.importer, candidate.unit.name].join("\u0000"),
|
|
101
|
+
}));
|
|
102
|
+
}
|
|
103
|
+
return diagnostics;
|
|
104
|
+
};
|
|
105
|
+
export const intentDrift = {
|
|
106
|
+
id: RULE_ID,
|
|
107
|
+
severity: "warn",
|
|
108
|
+
description: "A deprecated declaration with no replacement, or a replacement still imported.",
|
|
109
|
+
judged: true,
|
|
110
|
+
move: "expand",
|
|
111
|
+
onUnavailable: "report",
|
|
112
|
+
messages: messages({
|
|
113
|
+
deprecated_import: "`{{name}}` is deprecated; use {{replacement}} instead.",
|
|
114
|
+
deprecated_import_help: "{{file}} marks `{{name}}` deprecated. Update the import, or remove the deprecation if the old name is still the right one.",
|
|
115
|
+
deprecated_import_no_target: "`{{name}}` is deprecated and imported, but its deprecation names no replacement.",
|
|
116
|
+
deprecated_import_no_target_help: "A deprecation without a replacement is a dead end for the reader. Name the part to migrate to in the `@deprecated` tag.",
|
|
117
|
+
missing_replacement: "`{{name}}` is deprecated in favor of {{replacement}}, which no declaration exports.",
|
|
118
|
+
missing_replacement_help: "The migration target must exist before the deprecation can be followed. Rename the target or correct the tag.",
|
|
119
|
+
}),
|
|
120
|
+
plan: Effect.fn("joggle/intent-drift")(function* (workspace, scope) {
|
|
121
|
+
const files = new Map(workspace.files.map((file) => [file.path, file]));
|
|
122
|
+
const candidates = [];
|
|
123
|
+
for (const unit of workspace.units) {
|
|
124
|
+
if (!isDeprecated(unit))
|
|
125
|
+
continue;
|
|
126
|
+
const replacements = replacementsOf(unit.doc);
|
|
127
|
+
const declared = replacements.filter((name) => {
|
|
128
|
+
if (name === unit.name)
|
|
129
|
+
return false;
|
|
130
|
+
return (workspace.byName.get(name) ?? []).some((candidate) => candidate.exported && !(candidate.file === unit.file && candidate.name === unit.name));
|
|
131
|
+
});
|
|
132
|
+
const unknown = replacements.filter((name) => !declared.includes(name));
|
|
133
|
+
const imports = workspace.imports
|
|
134
|
+
.importersOfName(unit.file, unit.name)
|
|
135
|
+
.filter((edge) => edge.importer !== unit.file)
|
|
136
|
+
.filter((edge) => inGraphScope(scope, edge.importer) || inGraphScope(scope, unit.file))
|
|
137
|
+
.slice(0, policy.intentDrift.maxImports)
|
|
138
|
+
.map((edge) => ({ edge, site: importSite(files.get(edge.importer), edge, unit.name) }));
|
|
139
|
+
// A broken tag is only in scope when its declaration is; a call site is enough
|
|
140
|
+
// on its own, because a scoped run is asking what the change introduced.
|
|
141
|
+
const reportedUnknown = inScope(scope, unit.file) ? unknown : [];
|
|
142
|
+
if (reportedUnknown.length === 0 && imports.length === 0)
|
|
143
|
+
continue;
|
|
144
|
+
candidates.push({
|
|
145
|
+
unit,
|
|
146
|
+
replacements,
|
|
147
|
+
declared,
|
|
148
|
+
unknown: reportedUnknown,
|
|
149
|
+
imports,
|
|
150
|
+
});
|
|
151
|
+
}
|
|
152
|
+
if (candidates.length === 0) {
|
|
153
|
+
return {
|
|
154
|
+
plans: [],
|
|
155
|
+
read: () => outcome([], ["no deprecated declaration has a live import or a missing target"]),
|
|
156
|
+
};
|
|
157
|
+
}
|
|
158
|
+
const budget = policy.intentDrift.maxDeclarations;
|
|
159
|
+
const judged = candidates.slice(0, budget);
|
|
160
|
+
const atoms = yield* Atoms;
|
|
161
|
+
const planned = yield* Effect.forEach(judged, (candidate) => Effect.gen(function* () {
|
|
162
|
+
const id = yield* atoms.add({
|
|
163
|
+
declaration: {
|
|
164
|
+
name: candidate.unit.name,
|
|
165
|
+
file: candidate.unit.file,
|
|
166
|
+
doc: (candidate.unit.doc ?? "").slice(0, policy.evidence.maxSourceChars),
|
|
167
|
+
},
|
|
168
|
+
replacements: candidate.replacements,
|
|
169
|
+
missing: candidate.unknown,
|
|
170
|
+
imports: candidate.imports.map(({ edge, site }) => ({
|
|
171
|
+
file: edge.importer,
|
|
172
|
+
line: site.line,
|
|
173
|
+
specifier: edge.specifier,
|
|
174
|
+
})),
|
|
175
|
+
});
|
|
176
|
+
const plan = {
|
|
177
|
+
ruleId: RULE_ID,
|
|
178
|
+
subject: candidate.unit.file + ":" + candidate.unit.name,
|
|
179
|
+
concerns: [
|
|
180
|
+
candidate.unit.file,
|
|
181
|
+
...candidate.imports.map(({ edge }) => edge.importer),
|
|
182
|
+
],
|
|
183
|
+
atoms: [id],
|
|
184
|
+
violations: VIOLATIONS,
|
|
185
|
+
decisions: {
|
|
186
|
+
verdict: Decision.classify({
|
|
187
|
+
instructions: [
|
|
188
|
+
`\`atoms[${id}].declaration\` carries an \`@deprecated\` tag.`,
|
|
189
|
+
`\`atoms[${id}].replacements\` are the names the tag says to use.`,
|
|
190
|
+
`\`atoms[${id}].missing\` are replacement names with no exported declaration.`,
|
|
191
|
+
`\`atoms[${id}].imports\` are the call sites that still import the old name.`,
|
|
192
|
+
"What should happen?",
|
|
193
|
+
"Answer `migrate` when a replacement exists and the imports should move to it.",
|
|
194
|
+
"Answer `fix_tag` when the replacement the tag names does not exist, so the tag or the target is wrong.",
|
|
195
|
+
"Answer `keep` when the old path is deliberately still in use -- a test, a compatibility shim, a staged migration -- or the tag itself is wrong.",
|
|
196
|
+
].join("\n"),
|
|
197
|
+
criteria: {
|
|
198
|
+
migrate: "The replacement exists; move the imports.",
|
|
199
|
+
fix_tag: "The named replacement does not exist; fix the tag or add the target.",
|
|
200
|
+
keep: "The old path is intentional, or the deprecation is wrong. Change nothing.",
|
|
201
|
+
},
|
|
202
|
+
}),
|
|
203
|
+
},
|
|
204
|
+
read: (answers) => answers,
|
|
205
|
+
};
|
|
206
|
+
return { candidate, plan };
|
|
207
|
+
}), { concurrency: "unbounded" });
|
|
208
|
+
const overBudget = candidates.slice(budget).map((candidate) => ({
|
|
209
|
+
ruleId: RULE_ID,
|
|
210
|
+
subject: candidate.unit.file + ":" + candidate.unit.name,
|
|
211
|
+
stage: "budget",
|
|
212
|
+
reason: "past the budget of " + String(budget) + " deprecated declarations",
|
|
213
|
+
}));
|
|
214
|
+
return {
|
|
215
|
+
plans: planned.map((entry) => entry.plan),
|
|
216
|
+
read: (answers) => {
|
|
217
|
+
const report = reporter(intentDrift, locator(workspace));
|
|
218
|
+
const verdicts = verdictsOf(answers);
|
|
219
|
+
const diagnostics = [];
|
|
220
|
+
const drops = [...overBudget];
|
|
221
|
+
planned.forEach(({ candidate, plan }, index) => {
|
|
222
|
+
const answer = verdicts[index];
|
|
223
|
+
const verdict = verdictOf(answer?.["verdict"], VIOLATIONS.verdict);
|
|
224
|
+
if (verdict === undefined) {
|
|
225
|
+
diagnostics.push(...findingsFor(report, candidate, "unjudged", { judged: false, review: false }, undefined));
|
|
226
|
+
return;
|
|
227
|
+
}
|
|
228
|
+
const quality = qualityOf({
|
|
229
|
+
score: verdict.probability,
|
|
230
|
+
margin: verdict.margin,
|
|
231
|
+
confidence: verdict.confidence,
|
|
232
|
+
});
|
|
233
|
+
if (quality.quality === "drop") {
|
|
234
|
+
drops.push({
|
|
235
|
+
ruleId: RULE_ID,
|
|
236
|
+
subject: plan.subject,
|
|
237
|
+
stage: "gated",
|
|
238
|
+
reason: quality.reason,
|
|
239
|
+
});
|
|
240
|
+
return;
|
|
241
|
+
}
|
|
242
|
+
if (!isViolating(verdict.label)) {
|
|
243
|
+
drops.push({
|
|
244
|
+
ruleId: RULE_ID,
|
|
245
|
+
subject: plan.subject,
|
|
246
|
+
stage: "declined",
|
|
247
|
+
reason: "the old path is intentional",
|
|
248
|
+
});
|
|
249
|
+
return;
|
|
250
|
+
}
|
|
251
|
+
// A model can name a repair the facts do not support. Keep the facts
|
|
252
|
+
// authoritative about WHICH repair is available; the model decides whether
|
|
253
|
+
// anything should change at all.
|
|
254
|
+
if (verdict.label === "migrate" && candidate.declared.length === 0) {
|
|
255
|
+
drops.push({
|
|
256
|
+
ruleId: RULE_ID,
|
|
257
|
+
subject: plan.subject,
|
|
258
|
+
stage: "gated",
|
|
259
|
+
reason: "the tag names no existing replacement",
|
|
260
|
+
});
|
|
261
|
+
return;
|
|
262
|
+
}
|
|
263
|
+
if (verdict.label === "fix_tag" && candidate.unknown.length === 0) {
|
|
264
|
+
drops.push({
|
|
265
|
+
ruleId: RULE_ID,
|
|
266
|
+
subject: plan.subject,
|
|
267
|
+
stage: "gated",
|
|
268
|
+
reason: "the tag names no missing replacement",
|
|
269
|
+
});
|
|
270
|
+
return;
|
|
271
|
+
}
|
|
272
|
+
const repair = verdict.label === "migrate" ? "migrate" : "fix_tag";
|
|
273
|
+
diagnostics.push(...findingsFor(report, candidate, repair, { judged: true, review: quality.quality === "review" }, verdict.confidence));
|
|
274
|
+
});
|
|
275
|
+
return outcome(diagnostics, [
|
|
276
|
+
...budgetNote({
|
|
277
|
+
unitKind: "deprecated declarations",
|
|
278
|
+
judged: budget,
|
|
279
|
+
candidates: candidates.length,
|
|
280
|
+
sample: candidates.slice(budget).map((candidate) => candidate.unit.name),
|
|
281
|
+
}),
|
|
282
|
+
], drops);
|
|
283
|
+
},
|
|
284
|
+
};
|
|
285
|
+
}),
|
|
286
|
+
};
|