@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.
- 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,280 @@
|
|
|
1
|
+
import { Effect, Order } 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, inScope, outcome, qualityOf, } from "../rule.js";
|
|
9
|
+
import { unitFields } from "../workspace.js";
|
|
10
|
+
const RULE_ID = "joggle/object-shape";
|
|
11
|
+
/** Which labels mean this rule is violated -- the read and the calibration share it. */
|
|
12
|
+
const VIOLATIONS = { verdict: ["one_concept"] };
|
|
13
|
+
// Object literals that share a shape and have no name.
|
|
14
|
+
//
|
|
15
|
+
// The entropy machine called this `object-duplicate`: "define a named type or
|
|
16
|
+
// interface, type-annotate all occurrences with it". It is the runtime-value half
|
|
17
|
+
// of what `compose-types` does for declarations.
|
|
18
|
+
//
|
|
19
|
+
// What is deterministic is the state. A repeated key set is a fact: object
|
|
20
|
+
// literals are collected per file, the key sets are sorted (because `{a, b}` and
|
|
21
|
+
// `{b, a}` are one shape), and a shape shared by two or more files is a
|
|
22
|
+
// candidate. Whether that shape is ONE CONCEPT that deserves a name, or two
|
|
23
|
+
// concepts that happen to share field names, is not a fact. That is the question,
|
|
24
|
+
// and it used to be answered by the key set alone.
|
|
25
|
+
/**
|
|
26
|
+
* The rule's identity and its messages, in one place a reporter can be bound to
|
|
27
|
+
* without the rule having to name itself.
|
|
28
|
+
*/
|
|
29
|
+
const SPEC = {
|
|
30
|
+
id: RULE_ID,
|
|
31
|
+
severity: "info",
|
|
32
|
+
judged: true,
|
|
33
|
+
move: "expand",
|
|
34
|
+
messages: messages({
|
|
35
|
+
repeated_fields: "{{count}} object literal(s) in {{files}} file(s) share this shape: { {{fields}} }.",
|
|
36
|
+
repeated_fields_help: "Define a type with these fields and annotate every site with it. A shape nobody named is a shape nobody validates, and the sixth copy is written from memory: {{paths}}.{{unverified}}",
|
|
37
|
+
}),
|
|
38
|
+
};
|
|
39
|
+
export const objectShape = {
|
|
40
|
+
...SPEC,
|
|
41
|
+
description: "Object literals that share a shape with no type of their own.",
|
|
42
|
+
onUnavailable: "report",
|
|
43
|
+
plan: Effect.fn("joggle/object-shape")(function* (workspace, scope) {
|
|
44
|
+
const report = reporter(SPEC, locator(workspace));
|
|
45
|
+
const { minKeys, maxFindings, warnFromFiles } = policy.objectShape;
|
|
46
|
+
// A shape a declared type already names is not a shape nobody named. Every
|
|
47
|
+
// interface and type alias contributes its field set, plus the fields of the
|
|
48
|
+
// types it composes (`extends`, `A & B`, `type T = A`), resolved across files;
|
|
49
|
+
// a `Schema.Struct` field object contributes its keys. Without this, composing
|
|
50
|
+
// a type turned its own literals into findings.
|
|
51
|
+
const byId = new Map();
|
|
52
|
+
for (const unit of workspace.units) {
|
|
53
|
+
if (unit.kind !== "interface" && unit.kind !== "type")
|
|
54
|
+
continue;
|
|
55
|
+
byId.set(unit.file + "#" + unit.name, unit);
|
|
56
|
+
}
|
|
57
|
+
const complete = new Map();
|
|
58
|
+
const fieldsOfUnit = (unit, seen) => {
|
|
59
|
+
const id = unit.file + "#" + unit.name;
|
|
60
|
+
const cached = complete.get(id);
|
|
61
|
+
if (cached !== undefined)
|
|
62
|
+
return cached;
|
|
63
|
+
if (seen.has(id))
|
|
64
|
+
return new Set(unitFields(unit));
|
|
65
|
+
const next = new Set(seen);
|
|
66
|
+
next.add(id);
|
|
67
|
+
const fields = new Set(unitFields(unit));
|
|
68
|
+
for (const base of unit.composed) {
|
|
69
|
+
const target = byId.get(base.resolvedTo);
|
|
70
|
+
if (target === undefined)
|
|
71
|
+
continue;
|
|
72
|
+
for (const field of fieldsOfUnit(target, next))
|
|
73
|
+
fields.add(field);
|
|
74
|
+
}
|
|
75
|
+
complete.set(id, fields);
|
|
76
|
+
return fields;
|
|
77
|
+
};
|
|
78
|
+
const declared = [];
|
|
79
|
+
for (const unit of workspace.units) {
|
|
80
|
+
if (unit.kind !== "interface" && unit.kind !== "type")
|
|
81
|
+
continue;
|
|
82
|
+
const fields = fieldsOfUnit(unit, new Set());
|
|
83
|
+
if (fields.size < minKeys)
|
|
84
|
+
continue;
|
|
85
|
+
declared.push(fields);
|
|
86
|
+
}
|
|
87
|
+
for (const file of workspace.files) {
|
|
88
|
+
for (const site of file.facts.objects) {
|
|
89
|
+
if (!site.declared)
|
|
90
|
+
continue;
|
|
91
|
+
declared.push(new Set(site.keys));
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
const isDeclared = (keys) => declared.some((type) => [...keys].every((key) => type.has(key)));
|
|
95
|
+
const groups = new Map();
|
|
96
|
+
for (const file of workspace.files) {
|
|
97
|
+
// A shape nobody names is a real problem in application code and not one in
|
|
98
|
+
// a test, where a fixture is supposed to be repeated.
|
|
99
|
+
if (policy.testFiles.test(file.path))
|
|
100
|
+
continue;
|
|
101
|
+
for (const site of file.facts.objects) {
|
|
102
|
+
const keys = [...new Set(site.keys)];
|
|
103
|
+
if (keys.length < minKeys)
|
|
104
|
+
continue;
|
|
105
|
+
if (isDeclared(new Set(keys)))
|
|
106
|
+
continue;
|
|
107
|
+
const signature = [...keys].sort(Order.String).join("\u0000");
|
|
108
|
+
const existing = groups.get(signature);
|
|
109
|
+
if (existing === undefined)
|
|
110
|
+
groups.set(signature, [{ file: file.path, start: site.start }]);
|
|
111
|
+
else
|
|
112
|
+
existing.push({ file: file.path, start: site.start });
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
const repeated = [...groups.entries()]
|
|
116
|
+
.filter(([, sites]) => new Set(sites.map((site) => site.file)).size >= 2)
|
|
117
|
+
.filter(([, sites]) => sites.some((site) => scope.changed === undefined || inScope(scope, site.file)))
|
|
118
|
+
.sort((left, right) => right[1].length - left[1].length || left[0].localeCompare(right[0]));
|
|
119
|
+
if (repeated.length === 0) {
|
|
120
|
+
return {
|
|
121
|
+
plans: [],
|
|
122
|
+
read: () => outcome([], [
|
|
123
|
+
"no object literal with " +
|
|
124
|
+
minKeys +
|
|
125
|
+
" or more keys appears in two or more files, so there was no shape to name",
|
|
126
|
+
]),
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
const judged = repeated.slice(0, maxFindings);
|
|
130
|
+
const overBudget = repeated.slice(maxFindings).map(([signature, sites]) => ({
|
|
131
|
+
ruleId: RULE_ID,
|
|
132
|
+
subject: sites.length + " literal(s) of { " + signature.split("\u0000").join("; ") + " }",
|
|
133
|
+
stage: "budget",
|
|
134
|
+
reason: "past the budget of " + String(maxFindings) + " shapes",
|
|
135
|
+
}));
|
|
136
|
+
const textOf = new Map(workspace.files.map((file) => [file.path, file.text]));
|
|
137
|
+
const atoms = yield* Atoms;
|
|
138
|
+
const planned = yield* Effect.forEach(judged, ([signature, sites]) => Effect.gen(function* () {
|
|
139
|
+
const keys = signature.split("\u0000");
|
|
140
|
+
const files = [...new Set(sites.map((site) => site.file))];
|
|
141
|
+
const first = sites[0];
|
|
142
|
+
if (first === undefined)
|
|
143
|
+
return undefined;
|
|
144
|
+
// The state is the shape and a bounded sample of its sites, not every
|
|
145
|
+
// site's source: unrelated detail costs accuracy, and the shape is what
|
|
146
|
+
// the question is about.
|
|
147
|
+
const samples = sites.slice(0, 4).map((site) => {
|
|
148
|
+
const text = textOf.get(site.file) ?? "";
|
|
149
|
+
return { file: site.file, source: text.slice(site.start, site.start + 180) };
|
|
150
|
+
});
|
|
151
|
+
const id = yield* atoms.add({
|
|
152
|
+
fields: keys,
|
|
153
|
+
count: sites.length,
|
|
154
|
+
files,
|
|
155
|
+
samples,
|
|
156
|
+
});
|
|
157
|
+
const plan = {
|
|
158
|
+
ruleId: RULE_ID,
|
|
159
|
+
subject: "object shape { " + keys.join("; ") + " }",
|
|
160
|
+
concerns: files,
|
|
161
|
+
atoms: [id],
|
|
162
|
+
violations: VIOLATIONS,
|
|
163
|
+
decisions: {
|
|
164
|
+
verdict: Decision.classify({
|
|
165
|
+
instructions: [
|
|
166
|
+
`\`atoms[${id}].fields\` is a set of ${keys.length} field names. It appears as an object literal in ${sites.length} place(s) across ${files.length} file(s): ${files.slice(0, 6).join(", ")}. \`atoms[${id}].samples\` shows a few of them.`,
|
|
167
|
+
"Is that set of fields ONE CONCEPT that deserves a name -- a type every site should use -- or is the shared shape a coincidence?",
|
|
168
|
+
"Answer `one_concept` when the fields belong together as one thing and every site means the same thing by them.",
|
|
169
|
+
"Answer `coincidental` when the sites are different concepts that happen to share field names, so one type would be wrong.",
|
|
170
|
+
"A shape that is an external library's options object is `coincidental`: the fields are what a framework or a platform function expects, so the shape belongs to that library and this code is not missing a type.",
|
|
171
|
+
"Generic bookkeeping that unrelated modules carry for their own reasons (an id, a name, timestamps, a tenant) is `coincidental`, however many fields it has.",
|
|
172
|
+
"Answer `already_named` when some type in the codebase already names this exact shape.",
|
|
173
|
+
].join("\n"),
|
|
174
|
+
criteria: {
|
|
175
|
+
one_concept: "The fields are one thing. A named type should replace the literal everywhere.",
|
|
176
|
+
coincidental: "Different concepts that share field names, a library\u0027s options object, or generic bookkeeping. One type would be wrong.",
|
|
177
|
+
already_named: "A declared type already covers this field set.",
|
|
178
|
+
},
|
|
179
|
+
}),
|
|
180
|
+
},
|
|
181
|
+
read: (answers) => answers,
|
|
182
|
+
};
|
|
183
|
+
return { keys, sites, first, id, plan };
|
|
184
|
+
}), { concurrency: "unbounded" });
|
|
185
|
+
const present = planned.filter((entry) => entry !== undefined);
|
|
186
|
+
return {
|
|
187
|
+
plans: present.map((entry) => entry.plan),
|
|
188
|
+
read: (answers) => {
|
|
189
|
+
const verdicts = verdictsOf(answers);
|
|
190
|
+
const diagnostics = [];
|
|
191
|
+
const drops = [...overBudget];
|
|
192
|
+
present.forEach((entry, index) => {
|
|
193
|
+
const { keys } = entry;
|
|
194
|
+
const subject = "object shape { " + keys.join("; ") + " }";
|
|
195
|
+
const answer = verdicts[index];
|
|
196
|
+
const verdict = verdictOf(answer?.["verdict"], VIOLATIONS.verdict);
|
|
197
|
+
if (verdict === undefined) {
|
|
198
|
+
diagnostics.push(findingFor({
|
|
199
|
+
report,
|
|
200
|
+
entry,
|
|
201
|
+
confidence: undefined,
|
|
202
|
+
unverifiedReason: "no judgement was available",
|
|
203
|
+
notice: true,
|
|
204
|
+
}));
|
|
205
|
+
return;
|
|
206
|
+
}
|
|
207
|
+
if (verdict.label !== "one_concept") {
|
|
208
|
+
drops.push({
|
|
209
|
+
ruleId: RULE_ID,
|
|
210
|
+
subject,
|
|
211
|
+
stage: "declined",
|
|
212
|
+
reason: verdict.label === "already_named"
|
|
213
|
+
? "a declared type already covers this shape"
|
|
214
|
+
: "the sites are different concepts that share field names",
|
|
215
|
+
});
|
|
216
|
+
return;
|
|
217
|
+
}
|
|
218
|
+
const quality = qualityOf({
|
|
219
|
+
score: verdict.probability,
|
|
220
|
+
margin: verdict.margin,
|
|
221
|
+
confidence: verdict.confidence,
|
|
222
|
+
});
|
|
223
|
+
// A band is not a reason to discard an answer. A decisive
|
|
224
|
+
// `one_concept` is a warning -- somebody should name this shape -- and
|
|
225
|
+
// an answer the model shrugged across is a notice. Only a real no is
|
|
226
|
+
// recorded and withheld.
|
|
227
|
+
if (quality.quality === "drop") {
|
|
228
|
+
drops.push({
|
|
229
|
+
ruleId: RULE_ID,
|
|
230
|
+
subject,
|
|
231
|
+
stage: "gated",
|
|
232
|
+
reason: quality.reason,
|
|
233
|
+
});
|
|
234
|
+
return;
|
|
235
|
+
}
|
|
236
|
+
// The spread decides the band, not the rule: a shape in two files is a
|
|
237
|
+
// pair that may be coincidence, one in three or more is a pattern.
|
|
238
|
+
const spread = new Set(entry.sites.map((site) => site.file)).size;
|
|
239
|
+
diagnostics.push(findingFor({
|
|
240
|
+
report,
|
|
241
|
+
entry,
|
|
242
|
+
confidence: verdict.confidence,
|
|
243
|
+
unverifiedReason: undefined,
|
|
244
|
+
notice: quality.quality === "review" || spread < warnFromFiles,
|
|
245
|
+
}));
|
|
246
|
+
});
|
|
247
|
+
return outcome(diagnostics, budgetNote({
|
|
248
|
+
unitKind: "shapes",
|
|
249
|
+
judged: maxFindings,
|
|
250
|
+
candidates: repeated.length,
|
|
251
|
+
sample: repeated.slice(maxFindings).map(([signature]) => signature.split("\u0000").join("; ")),
|
|
252
|
+
}), drops);
|
|
253
|
+
},
|
|
254
|
+
};
|
|
255
|
+
}),
|
|
256
|
+
};
|
|
257
|
+
/** The finding for one shape: verified, or the fact with the reason it is not. */
|
|
258
|
+
const findingFor = ({ report, entry, confidence, unverifiedReason, notice = true, }) => {
|
|
259
|
+
const files = [...new Set(entry.sites.map((site) => site.file))];
|
|
260
|
+
const paths = files.slice(0, policy.evidence.maxListedPaths).join(", ") +
|
|
261
|
+
(files.length > policy.evidence.maxListedPaths
|
|
262
|
+
? " and " + (files.length - policy.evidence.maxListedPaths) + " more"
|
|
263
|
+
: "");
|
|
264
|
+
return report({
|
|
265
|
+
about: { file: entry.first.file, start: entry.first.start },
|
|
266
|
+
messageId: "repeated_fields",
|
|
267
|
+
data: {
|
|
268
|
+
count: entry.sites.length,
|
|
269
|
+
files: files.length,
|
|
270
|
+
fields: entry.keys.join("; "),
|
|
271
|
+
paths,
|
|
272
|
+
unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
|
|
273
|
+
},
|
|
274
|
+
helpId: "repeated_fields_help",
|
|
275
|
+
identity: [RULE_ID, entry.keys.join("\u0000")].join("\u0000"),
|
|
276
|
+
judged: unverifiedReason === undefined,
|
|
277
|
+
confidence,
|
|
278
|
+
severity: notice ? "info" : "warn",
|
|
279
|
+
});
|
|
280
|
+
};
|
|
@@ -0,0 +1,243 @@
|
|
|
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 {} from "../plans.js";
|
|
6
|
+
import { verdictsOf } from "../plans.js";
|
|
7
|
+
import { locator, messages, reporter, shortType, } from "../reporting.js";
|
|
8
|
+
import { verdictOf } from "../verdict.js";
|
|
9
|
+
import { budgetNote, inScope, outcome, qualityOf, } from "../rule.js";
|
|
10
|
+
const RULE_ID = "joggle/one-concept-one-type";
|
|
11
|
+
/** Which labels mean this rule is violated -- the read and the calibration share it. */
|
|
12
|
+
const VIOLATIONS = { verdict: ["one_concept", "two_concepts"] };
|
|
13
|
+
// One declared name, resolving to different types in different files.
|
|
14
|
+
//
|
|
15
|
+
// Text cannot see this. `User` in the API and `User` in the UI read identically
|
|
16
|
+
// and are two types; `User` written twice with the same members reads identically
|
|
17
|
+
// and is one type written twice. Only the compiler tells which, and the trace is
|
|
18
|
+
// its answer.
|
|
19
|
+
//
|
|
20
|
+
// The resolved type is a FACT. Whether two resolved meanings are one concept that
|
|
21
|
+
// should share a declaration, or two concepts that should have two names, is the
|
|
22
|
+
// judgement -- and it is the one a reader had to make from the help text.
|
|
23
|
+
export const oneConceptOneType = {
|
|
24
|
+
id: RULE_ID,
|
|
25
|
+
severity: "warn",
|
|
26
|
+
description: "One declared name resolving to different types.",
|
|
27
|
+
judged: true,
|
|
28
|
+
move: "contract",
|
|
29
|
+
onUnavailable: "report",
|
|
30
|
+
messages: messages({
|
|
31
|
+
one_name_many_types: "`{{name}}` resolves to {{meanings}} different types in {{places}} declaration(s) across {{files}} file(s).",
|
|
32
|
+
one_name_many_types_help: "{{lead}}The compiler resolved it to: {{resolved}}. Share one declaration, or give the two concepts two names.{{unverified}}",
|
|
33
|
+
}),
|
|
34
|
+
plan: Effect.fn("joggle/one-concept-one-type")(function* (workspace, scope) {
|
|
35
|
+
const report = reporter(oneConceptOneType, locator(workspace));
|
|
36
|
+
const byName = new Map();
|
|
37
|
+
for (const unit of workspace.units) {
|
|
38
|
+
// Functions are already compared as names and as call sequences, and a const
|
|
39
|
+
// beside a type of the same name is the schema idiom (`const S = Schema…`,
|
|
40
|
+
// `type S = typeof S.Type`), which is ONE declaration pair, not drift.
|
|
41
|
+
if (unit.kind === "function" || unit.kind === "const")
|
|
42
|
+
continue;
|
|
43
|
+
// A file-local name is a contract too: two declarations of one name in one
|
|
44
|
+
// module still compile against whichever one a reader imported, and the
|
|
45
|
+
// compiler is the only thing that can see they differ.
|
|
46
|
+
const fact = unit.typeFacts;
|
|
47
|
+
if (fact === undefined || fact.display === "")
|
|
48
|
+
continue;
|
|
49
|
+
const list = byName.get(unit.name) ?? [];
|
|
50
|
+
list.push({ unit, fact });
|
|
51
|
+
byName.set(unit.name, list);
|
|
52
|
+
}
|
|
53
|
+
if (byName.size === 0) {
|
|
54
|
+
return {
|
|
55
|
+
plans: [],
|
|
56
|
+
read: () => outcome([], [
|
|
57
|
+
workspace.types.sites === 0
|
|
58
|
+
? "no resolved types were available: run with --types to ask the compiler"
|
|
59
|
+
: "no type declaration carried a resolved type to compare",
|
|
60
|
+
]),
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
const candidates = [];
|
|
64
|
+
let divergent = 0;
|
|
65
|
+
for (const [name, entries] of byName) {
|
|
66
|
+
const files = new Set(entries.map((entry) => entry.unit.file));
|
|
67
|
+
// The STRUCTURE is the meaning. Two aliases that print differently and
|
|
68
|
+
// resolve alike are one type; two that print alike and resolve differently
|
|
69
|
+
// are two. The display was the string, and this is the proof.
|
|
70
|
+
const meanings = new Set(entries.map((entry) => entry.fact.structural || entry.fact.display));
|
|
71
|
+
if (meanings.size < 2)
|
|
72
|
+
continue;
|
|
73
|
+
if (!entries.some((entry) => inScope(scope, entry.unit.file)))
|
|
74
|
+
continue;
|
|
75
|
+
divergent += 1;
|
|
76
|
+
candidates.push({ name, entries, meanings: meanings.size, files: files.size });
|
|
77
|
+
}
|
|
78
|
+
if (candidates.length === 0) {
|
|
79
|
+
return {
|
|
80
|
+
plans: [],
|
|
81
|
+
read: () => outcome([], [
|
|
82
|
+
byName.size + " exported type name(s) with a resolved type; none resolve to more than one",
|
|
83
|
+
]),
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
const judged = candidates.slice(0, policy.oneConceptOneType.maxFindings);
|
|
87
|
+
const overBudget = candidates
|
|
88
|
+
.slice(policy.oneConceptOneType.maxFindings)
|
|
89
|
+
.map((candidate) => ({
|
|
90
|
+
ruleId: RULE_ID,
|
|
91
|
+
subject: candidate.name,
|
|
92
|
+
stage: "budget",
|
|
93
|
+
reason: "past the budget of " + String(policy.oneConceptOneType.maxFindings) + " names",
|
|
94
|
+
}));
|
|
95
|
+
const atoms = yield* Atoms;
|
|
96
|
+
const planned = yield* Effect.forEach(judged, (candidate) => Effect.gen(function* () {
|
|
97
|
+
// The state is the name and each resolved meaning, bounded, which is what
|
|
98
|
+
// the question needs: the compiler's answer, not the source.
|
|
99
|
+
const meanings = candidate.entries.slice(0, 6).map((entry) => ({
|
|
100
|
+
file: entry.unit.file,
|
|
101
|
+
line: entry.unit.location.line,
|
|
102
|
+
kind: entry.unit.kind,
|
|
103
|
+
display: shortType(entry.fact.display),
|
|
104
|
+
structural: shortType(entry.fact.structural),
|
|
105
|
+
}));
|
|
106
|
+
const id = yield* atoms.add({
|
|
107
|
+
name: candidate.name,
|
|
108
|
+
meaningCount: candidate.meanings,
|
|
109
|
+
fileCount: candidate.files,
|
|
110
|
+
meanings,
|
|
111
|
+
});
|
|
112
|
+
const plan = {
|
|
113
|
+
ruleId: RULE_ID,
|
|
114
|
+
subject: candidate.name,
|
|
115
|
+
concerns: [...new Set(candidate.entries.map((entry) => entry.unit.file))],
|
|
116
|
+
atoms: [id],
|
|
117
|
+
violations: VIOLATIONS,
|
|
118
|
+
decisions: {
|
|
119
|
+
verdict: Decision.classify({
|
|
120
|
+
instructions: [
|
|
121
|
+
`\`atoms[${id}].name\` is an exported type name that the compiler resolved to ${candidate.meanings} different types across ${candidate.files} files: \`atoms[${id}].meanings\` lists each declaration and what it resolved to.`,
|
|
122
|
+
"Are those meanings ONE concept that should share one declaration, or two concepts that should have two names?",
|
|
123
|
+
"Answer `one_concept` when they are the same idea written incompletely, so they should share one declaration.",
|
|
124
|
+
"Answer `two_concepts` when the name has been reused for different things, so one should be renamed.",
|
|
125
|
+
"Answer `intentional` when the divergence is deliberate and fine -- a name scoped per module, a generic used on purpose.",
|
|
126
|
+
].join("\n"),
|
|
127
|
+
criteria: {
|
|
128
|
+
one_concept: "One idea, written more than one way. Share one declaration.",
|
|
129
|
+
two_concepts: "One name, different things. Give one of them a new name.",
|
|
130
|
+
intentional: "A deliberate divergence. Nothing to change.",
|
|
131
|
+
},
|
|
132
|
+
}),
|
|
133
|
+
},
|
|
134
|
+
read: (answers) => answers,
|
|
135
|
+
};
|
|
136
|
+
return { candidate, id, plan };
|
|
137
|
+
}), { concurrency: "unbounded" });
|
|
138
|
+
return {
|
|
139
|
+
plans: planned.map((value) => value.plan),
|
|
140
|
+
read: (answers) => {
|
|
141
|
+
const verdicts = verdictsOf(answers);
|
|
142
|
+
const diagnostics = [];
|
|
143
|
+
const drops = [...overBudget];
|
|
144
|
+
planned.forEach((value, index) => {
|
|
145
|
+
const { candidate } = value;
|
|
146
|
+
const subject = candidate.name;
|
|
147
|
+
const answer = verdicts[index];
|
|
148
|
+
const verdict = verdictOf(answer?.["verdict"], VIOLATIONS.verdict);
|
|
149
|
+
if (verdict === undefined) {
|
|
150
|
+
diagnostics.push(findingFor({
|
|
151
|
+
report,
|
|
152
|
+
candidate,
|
|
153
|
+
confidence: undefined,
|
|
154
|
+
unverifiedReason: "no judgement was available",
|
|
155
|
+
}));
|
|
156
|
+
return;
|
|
157
|
+
}
|
|
158
|
+
if (verdict.label !== "one_concept" && verdict.label !== "two_concepts") {
|
|
159
|
+
drops.push({
|
|
160
|
+
ruleId: RULE_ID,
|
|
161
|
+
subject,
|
|
162
|
+
stage: "declined",
|
|
163
|
+
reason: "the divergence is deliberate",
|
|
164
|
+
});
|
|
165
|
+
return;
|
|
166
|
+
}
|
|
167
|
+
const quality = qualityOf({
|
|
168
|
+
score: verdict.probability,
|
|
169
|
+
margin: verdict.margin,
|
|
170
|
+
confidence: verdict.confidence,
|
|
171
|
+
});
|
|
172
|
+
if (quality.quality === "drop") {
|
|
173
|
+
drops.push({
|
|
174
|
+
ruleId: RULE_ID,
|
|
175
|
+
subject,
|
|
176
|
+
stage: "gated",
|
|
177
|
+
reason: quality.reason,
|
|
178
|
+
});
|
|
179
|
+
return;
|
|
180
|
+
}
|
|
181
|
+
const review = quality.quality === "review";
|
|
182
|
+
diagnostics.push(findingFor({
|
|
183
|
+
report,
|
|
184
|
+
candidate,
|
|
185
|
+
confidence: verdict.confidence,
|
|
186
|
+
unverifiedReason: undefined,
|
|
187
|
+
renamed: verdict.label === "two_concepts",
|
|
188
|
+
review,
|
|
189
|
+
}));
|
|
190
|
+
});
|
|
191
|
+
return outcome(diagnostics, [
|
|
192
|
+
byName.size +
|
|
193
|
+
" exported type name(s) with a resolved type; " +
|
|
194
|
+
divergent +
|
|
195
|
+
" resolve to more than one",
|
|
196
|
+
...budgetNote({
|
|
197
|
+
unitKind: "names",
|
|
198
|
+
judged: policy.oneConceptOneType.maxFindings,
|
|
199
|
+
candidates: candidates.length,
|
|
200
|
+
sample: candidates.slice(policy.oneConceptOneType.maxFindings).map((candidate) => candidate.name),
|
|
201
|
+
}),
|
|
202
|
+
], drops);
|
|
203
|
+
},
|
|
204
|
+
};
|
|
205
|
+
}),
|
|
206
|
+
};
|
|
207
|
+
const findingFor = ({ report, candidate, confidence, unverifiedReason, renamed = false, review = false, }) => {
|
|
208
|
+
const first = candidate.entries[0];
|
|
209
|
+
return report({
|
|
210
|
+
about: first?.unit ?? { file: "", start: 0 },
|
|
211
|
+
messageId: "one_name_many_types",
|
|
212
|
+
data: {
|
|
213
|
+
name: candidate.name,
|
|
214
|
+
meanings: candidate.meanings,
|
|
215
|
+
places: candidate.entries.length,
|
|
216
|
+
files: candidate.files,
|
|
217
|
+
lead: renamed
|
|
218
|
+
? "One name, different things. Give one of them its own name. "
|
|
219
|
+
: "One name should mean one type. ",
|
|
220
|
+
resolved: candidate.entries
|
|
221
|
+
.map((entry) => {
|
|
222
|
+
const display = shortType(entry.fact.display);
|
|
223
|
+
const structural = shortType(entry.fact.structural);
|
|
224
|
+
const proof = structural === "" || structural === display ? "" : " (" + structural + ")";
|
|
225
|
+
return (entry.unit.file +
|
|
226
|
+
":" +
|
|
227
|
+
String(entry.unit.location.line) +
|
|
228
|
+
" " +
|
|
229
|
+
entry.unit.kind +
|
|
230
|
+
" -> " +
|
|
231
|
+
display +
|
|
232
|
+
proof);
|
|
233
|
+
})
|
|
234
|
+
.join("; "),
|
|
235
|
+
unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
|
|
236
|
+
},
|
|
237
|
+
helpId: "one_name_many_types_help",
|
|
238
|
+
identity: [RULE_ID, candidate.name].join("\u0000"),
|
|
239
|
+
judged: unverifiedReason === undefined,
|
|
240
|
+
confidence,
|
|
241
|
+
severity: review ? "info" : "warn",
|
|
242
|
+
});
|
|
243
|
+
};
|