@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,231 @@
|
|
|
1
|
+
import { Effect } from "effect";
|
|
2
|
+
import { Decision } from "effect/ai";
|
|
3
|
+
import { Atoms } from "../atoms.js";
|
|
4
|
+
import { locator, messages, reporter } from "../reporting.js";
|
|
5
|
+
import { layersFrom } from "../architecture.js";
|
|
6
|
+
import { classifyModules, moduleOf, modulesOf } from "../roles.js";
|
|
7
|
+
import { budgetNote, inGraphScope, outcome, qualityOf, } from "../rule.js";
|
|
8
|
+
import { verdictsOf } from "../plans.js";
|
|
9
|
+
import { verdictOf } from "../verdict.js";
|
|
10
|
+
const RULE_ID = "joggle/module-direction";
|
|
11
|
+
/**
|
|
12
|
+
* Dependencies point one way, where the roles say the way is.
|
|
13
|
+
*
|
|
14
|
+
* `layer-direction` does this against layers a repository DECLARES, and it is
|
|
15
|
+
* precise and free when they are written down. It has two problems that are not
|
|
16
|
+
* about precision. Its globs go stale silently -- eight modules fell out of
|
|
17
|
+
* joggle's own layering in one afternoon, and the rule reported zero upward
|
|
18
|
+
* imports over the twenty-eight files it still covered. And a repository with no
|
|
19
|
+
* config gets no direction check at all, which is two of the four repositories
|
|
20
|
+
* this has been run against.
|
|
21
|
+
*
|
|
22
|
+
* This is the same check with the order INFERRED. It cannot come from the import
|
|
23
|
+
* graph, because a topological order of the edges respects every edge by
|
|
24
|
+
* construction, so a layering derived from the graph can never be violated by it.
|
|
25
|
+
* It comes from what the roles mean instead: utilities and infrastructure sit
|
|
26
|
+
* below the domain, which sits below the transport and rendering edges. That is a
|
|
27
|
+
* fact about the words rather than a fact about this repository, so it needs no
|
|
28
|
+
* declaration and cannot go stale.
|
|
29
|
+
*
|
|
30
|
+
* When layers ARE declared this rule stays out of the way and says so. A written
|
|
31
|
+
* layering is more precise than a guessed one, and two rules reporting the same
|
|
32
|
+
* upward import is how a report doubles without informing.
|
|
33
|
+
*
|
|
34
|
+
* The rank arithmetic is the CANDIDATE, not the verdict. An edge whose target
|
|
35
|
+
* ranks above its source is worth asking about; whether it is a real upward
|
|
36
|
+
* dependency, or the inferred order is what is wrong, is the question -- the same
|
|
37
|
+
* question `layer-direction` asks, for the same reason. `rule-judgment` caught
|
|
38
|
+
* this rule asserting the verdict from the arithmetic, which is the tool's own
|
|
39
|
+
* rule applied to itself.
|
|
40
|
+
*/
|
|
41
|
+
export const moduleDirection = {
|
|
42
|
+
id: RULE_ID,
|
|
43
|
+
severity: "warn",
|
|
44
|
+
description: "A module depends on a module whose role sits above it.",
|
|
45
|
+
judged: true,
|
|
46
|
+
move: "contract",
|
|
47
|
+
onUnavailable: "propagate",
|
|
48
|
+
messages: messages({
|
|
49
|
+
upward_module: "A {{from}} module imports a {{to}} module: {{fromModule}} -> {{toModule}}.",
|
|
50
|
+
upward_module_help: "The roles are ordered {{order}}, and {{from}} sits below {{to}}. That order was inferred from what the two modules are, not from a declared layering -- write one in joggle.config.json if this repository disagrees, and this rule will step aside.{{unverified}}",
|
|
51
|
+
}),
|
|
52
|
+
plan: Effect.fn("joggle/module-direction")(function* (workspace, scope, context) {
|
|
53
|
+
const declared = layersFrom(context.config);
|
|
54
|
+
if (declared.length > 0) {
|
|
55
|
+
return {
|
|
56
|
+
plans: [],
|
|
57
|
+
read: () => outcome([], [
|
|
58
|
+
"layers are declared, so `layer-direction` owns this check and this rule stays out of it",
|
|
59
|
+
]),
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
const classified = yield* classifyModules(workspace, context, RULE_ID);
|
|
63
|
+
if (classified.roles.size === 0) {
|
|
64
|
+
return { plans: [], read: () => outcome([], classified.notes, classified.drops) };
|
|
65
|
+
}
|
|
66
|
+
const modules = modulesOf(workspace);
|
|
67
|
+
// One candidate per (source module, target module) pair. Forty edges between
|
|
68
|
+
// two modules are one architectural statement, not forty.
|
|
69
|
+
const seen = new Set();
|
|
70
|
+
const candidates = [];
|
|
71
|
+
for (const edge of workspace.imports.edges) {
|
|
72
|
+
if (edge.resolution === "unresolved" || edge.importer === edge.to)
|
|
73
|
+
continue;
|
|
74
|
+
// A scoped run asks about the change: an upward dependency is a candidate
|
|
75
|
+
// when one of its two ends moved. A pure rename counts -- the move itself
|
|
76
|
+
// can put a module on the wrong side of a boundary it used to respect.
|
|
77
|
+
if (!inGraphScope(scope, edge.importer) && !inGraphScope(scope, edge.to))
|
|
78
|
+
continue;
|
|
79
|
+
const from = classified.roles.get(moduleKey(edge.importer, workspace));
|
|
80
|
+
const to = classified.roles.get(moduleKey(edge.to, workspace));
|
|
81
|
+
if (from === undefined || to === undefined)
|
|
82
|
+
continue;
|
|
83
|
+
if (from === to)
|
|
84
|
+
continue;
|
|
85
|
+
// A module and its own subdirectory are not two layers. `src/react/rules`
|
|
86
|
+
// importing from `src/react` is a child reaching into its parent area,
|
|
87
|
+
// which is what nesting is for, and reporting it as an architectural
|
|
88
|
+
// violation is how a direction check becomes noise.
|
|
89
|
+
if (from.startsWith(to + "/") || to.startsWith(from + "/"))
|
|
90
|
+
continue;
|
|
91
|
+
const fromRank = classified.ranks.get(from);
|
|
92
|
+
const toRank = classified.ranks.get(to);
|
|
93
|
+
// A role with no rank is not part of the architecture: a test may import
|
|
94
|
+
// anything, a module nobody could classify is not a claim about anyone, and
|
|
95
|
+
// a run that could not order the roles reports no direction at all rather
|
|
96
|
+
// than inventing one.
|
|
97
|
+
if (fromRank === undefined || toRank === undefined)
|
|
98
|
+
continue;
|
|
99
|
+
// The rank order is the CANDIDATE: an edge whose target sits above its
|
|
100
|
+
// source is the one worth asking about.
|
|
101
|
+
if (toRank <= fromRank)
|
|
102
|
+
continue;
|
|
103
|
+
const key = from + "\u0000" + to;
|
|
104
|
+
if (seen.has(key))
|
|
105
|
+
continue;
|
|
106
|
+
seen.add(key);
|
|
107
|
+
candidates.push({
|
|
108
|
+
from,
|
|
109
|
+
to,
|
|
110
|
+
fromModule: moduleKey(edge.importer, workspace),
|
|
111
|
+
toModule: moduleKey(edge.to, workspace),
|
|
112
|
+
file: edge.importer,
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
const order = orderOf(classified.ranks);
|
|
116
|
+
const atoms = yield* Atoms;
|
|
117
|
+
const planned = yield* Effect.forEach(candidates, (candidate) => Effect.gen(function* () {
|
|
118
|
+
const id = yield* atoms.add({
|
|
119
|
+
from: candidate.from,
|
|
120
|
+
to: candidate.to,
|
|
121
|
+
fromModule: candidate.fromModule,
|
|
122
|
+
toModule: candidate.toModule,
|
|
123
|
+
order,
|
|
124
|
+
});
|
|
125
|
+
const plan = {
|
|
126
|
+
ruleId: RULE_ID,
|
|
127
|
+
subject: candidate.fromModule + " -> " + candidate.toModule,
|
|
128
|
+
concerns: [candidate.file],
|
|
129
|
+
atoms: [id],
|
|
130
|
+
violations: { verdict: ["upward"] },
|
|
131
|
+
decisions: {
|
|
132
|
+
verdict: Decision.classify({
|
|
133
|
+
instructions: [
|
|
134
|
+
`\`atoms[${id}].fromModule\` is a ${candidate.from} module and it imports \`atoms[${id}].toModule\`, a ${candidate.to} module.`,
|
|
135
|
+
`The inferred order is ${order}: the roles are ranked ${candidate.from} below ${candidate.to}, and the order came from what the roles mean, not from a declared layering.`,
|
|
136
|
+
"Is that an upward dependency to break, or is the inferred order what is wrong?",
|
|
137
|
+
"Answer `upward` when the dependency genuinely points the wrong way, so the shared piece should move down or be passed in.",
|
|
138
|
+
"Answer `order_wrong` when these two roles are actually the other way round, so nothing is broken and the inferred order is what needs fixing.",
|
|
139
|
+
"Answer `exception` when the upward edge is deliberate and acceptable.",
|
|
140
|
+
].join("\n"),
|
|
141
|
+
criteria: {
|
|
142
|
+
upward: "A real upward dependency. Move the shared piece down, or invert it.",
|
|
143
|
+
order_wrong: "These roles sit the other way round; the order is wrong, not the import.",
|
|
144
|
+
exception: "A deliberate, acceptable exception.",
|
|
145
|
+
},
|
|
146
|
+
}),
|
|
147
|
+
},
|
|
148
|
+
read: (answers) => answers,
|
|
149
|
+
};
|
|
150
|
+
return { candidate, id, plan };
|
|
151
|
+
}), { concurrency: "unbounded" });
|
|
152
|
+
const overBudget = [];
|
|
153
|
+
return {
|
|
154
|
+
plans: planned.map((entry) => entry.plan),
|
|
155
|
+
read: (answers) => {
|
|
156
|
+
const verdicts = verdictsOf(answers);
|
|
157
|
+
const diagnostics = [];
|
|
158
|
+
const drops = [...overBudget];
|
|
159
|
+
planned.forEach((entry, index) => {
|
|
160
|
+
const verdict = verdictOf(verdicts[index]?.["verdict"], ["upward"]);
|
|
161
|
+
const subject = entry.candidate.fromModule + " -> " + entry.candidate.toModule;
|
|
162
|
+
if (verdict === undefined || verdict.label !== "upward") {
|
|
163
|
+
if (verdict !== undefined) {
|
|
164
|
+
drops.push({
|
|
165
|
+
ruleId: RULE_ID,
|
|
166
|
+
subject,
|
|
167
|
+
stage: "declined",
|
|
168
|
+
reason: verdict.label === "order_wrong"
|
|
169
|
+
? "the inferred order is wrong, not the import"
|
|
170
|
+
: "a deliberate, acceptable exception",
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
return;
|
|
174
|
+
}
|
|
175
|
+
const quality = qualityOf({
|
|
176
|
+
score: verdict.probability,
|
|
177
|
+
margin: verdict.margin,
|
|
178
|
+
confidence: verdict.confidence,
|
|
179
|
+
});
|
|
180
|
+
if (quality.quality === "drop") {
|
|
181
|
+
drops.push({ ruleId: RULE_ID, subject, stage: "gated", reason: quality.reason });
|
|
182
|
+
return;
|
|
183
|
+
}
|
|
184
|
+
diagnostics.push(reporterFor(workspace)({
|
|
185
|
+
about: { file: entry.candidate.file, start: 0 },
|
|
186
|
+
messageId: "upward_module",
|
|
187
|
+
data: {
|
|
188
|
+
from: entry.candidate.from,
|
|
189
|
+
to: entry.candidate.to,
|
|
190
|
+
fromModule: entry.candidate.fromModule,
|
|
191
|
+
toModule: entry.candidate.toModule,
|
|
192
|
+
order,
|
|
193
|
+
},
|
|
194
|
+
helpId: "upward_module_help",
|
|
195
|
+
identity: [RULE_ID, entry.candidate.from, entry.candidate.to].join("\u0000"),
|
|
196
|
+
judged: true,
|
|
197
|
+
confidence: verdict.confidence,
|
|
198
|
+
severity: quality.quality === "review" ? "info" : "warn",
|
|
199
|
+
}));
|
|
200
|
+
});
|
|
201
|
+
return outcome(diagnostics, [
|
|
202
|
+
...classified.notes,
|
|
203
|
+
modules.size +
|
|
204
|
+
" module(s); " +
|
|
205
|
+
candidates.length +
|
|
206
|
+
" upward candidate pair(s), " +
|
|
207
|
+
diagnostics.length +
|
|
208
|
+
" reported",
|
|
209
|
+
...budgetNote({
|
|
210
|
+
unitKind: "module pairs",
|
|
211
|
+
judged: candidates.length,
|
|
212
|
+
candidates: candidates.length,
|
|
213
|
+
sample: [],
|
|
214
|
+
}),
|
|
215
|
+
], [...classified.drops, ...drops]);
|
|
216
|
+
},
|
|
217
|
+
};
|
|
218
|
+
}),
|
|
219
|
+
};
|
|
220
|
+
/** The reporter, built once per read. */
|
|
221
|
+
const reporterFor = (workspace) => reporter(moduleDirection, locator(workspace));
|
|
222
|
+
/** The module a file belongs to, without needing a declaration to ask about. */
|
|
223
|
+
const moduleKey = (file, workspace) => {
|
|
224
|
+
const unit = workspace.units.find((candidate) => candidate.file === file);
|
|
225
|
+
return unit === undefined ? file : moduleOf(unit);
|
|
226
|
+
};
|
|
227
|
+
/** The order, written once so the help and the candidate filter cannot disagree. */
|
|
228
|
+
const orderOf = (ranks) => [...ranks.entries()]
|
|
229
|
+
.sort((left, right) => left[1] - right[1] || left[0].localeCompare(right[0]))
|
|
230
|
+
.map(([role]) => role.replace(/_/g, " "))
|
|
231
|
+
.join(" below ");
|
|
@@ -0,0 +1,216 @@
|
|
|
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 { budgetNote, declined, marginOfAnswer, outcome, qualityOf, } from "../rule.js";
|
|
8
|
+
const RULE_ID = "joggle/name-as-address";
|
|
9
|
+
// A name too common to be an address.
|
|
10
|
+
//
|
|
11
|
+
// The reference material this rule comes from opens with the measurement that
|
|
12
|
+
// motivates it: an agent finds code by searching for a name, so `grep create`
|
|
13
|
+
// returning 1,585 hits is not a style problem, it is a retrieval problem.
|
|
14
|
+
//
|
|
15
|
+
// The CANDIDATE is structural and free: an exported single-word name, called from
|
|
16
|
+
// at least `minFiles` files, where the call RESOLVES to this declaration. The
|
|
17
|
+
// resolution matters -- thirty call sites named `parse` reaching three different
|
|
18
|
+
// functions are not sixty hits on any one of them -- and the single word matters,
|
|
19
|
+
// because `fetchPayrollProjections` used in thirty files is a good address used
|
|
20
|
+
// often.
|
|
21
|
+
//
|
|
22
|
+
// The JUDGEMENT is whether THIS word at THAT count fails as an address. The count
|
|
23
|
+
// is a fact; the verdict is not. `range` reached from thirty files is a bad
|
|
24
|
+
// address, while a one-word domain term reached from the same number may be the
|
|
25
|
+
// right one. The first version answered with the threshold and asserted the
|
|
26
|
+
// verdict in the message -- "searching for it finds everything and nothing" --
|
|
27
|
+
// which moved a judgement into code. The model answers now, and code reports what
|
|
28
|
+
// it picked.
|
|
29
|
+
//
|
|
30
|
+
/**
|
|
31
|
+
* True when a name is one lowercase word: no camel case, no separators, no digits.
|
|
32
|
+
*
|
|
33
|
+
* The SHAPE of a name, not its meaning, so `no-pattern-classifier` does not
|
|
34
|
+
* apply -- and written as the property it is rather than a pattern.
|
|
35
|
+
*/
|
|
36
|
+
const isSingleWord = (name) => name.length > 0 && name.split("").every((character) => character >= "a" && character <= "z");
|
|
37
|
+
/** The two questions about one name, pointing at its atom by id. */
|
|
38
|
+
const nameReview = (id) => ({
|
|
39
|
+
fails_as_address: Decision.probability({
|
|
40
|
+
instructions: [
|
|
41
|
+
`Is \`atoms[${id}].name.identifier\`, declared at \`atoms[${id}].name.declared\`, a bad retrieval address?`,
|
|
42
|
+
`It is a single-word export, and \`atoms[${id}].name.files\` files call it. \`atoms[${id}].name.callers\` is a sample of them.`,
|
|
43
|
+
"An agent finds code by searching for a name, so a name that matches everything finds nothing.",
|
|
44
|
+
"Answer true when the word is generic enough that a search cannot narrow to this declaration: `range`, `create`, `handle`, `parse`, `data`.",
|
|
45
|
+
"Answer false when the single word is a term specific to this codebase, or when the declaration is easy to reach from the callers anyway.",
|
|
46
|
+
].join("\n"),
|
|
47
|
+
criteria: {
|
|
48
|
+
false: "The name still finds this declaration.",
|
|
49
|
+
true: "The name finds everything and nothing.",
|
|
50
|
+
},
|
|
51
|
+
}),
|
|
52
|
+
address: Decision.classify({
|
|
53
|
+
instructions: `If \`atoms[${id}].name.identifier\` is a bad address, what kind of word is it? Choose \`no_issue\` when the name still finds the declaration.`,
|
|
54
|
+
criteria: {
|
|
55
|
+
generic_verb: "A generic verb: create, get, handle, parse, build.",
|
|
56
|
+
generic_noun: "A generic noun: data, config, value, state, item.",
|
|
57
|
+
overloaded_domain: "A domain word used for more than one thing.",
|
|
58
|
+
no_issue: "The name still finds the declaration.",
|
|
59
|
+
},
|
|
60
|
+
}),
|
|
61
|
+
});
|
|
62
|
+
export const nameAsAddress = {
|
|
63
|
+
id: RULE_ID,
|
|
64
|
+
severity: "info",
|
|
65
|
+
description: "A generic single-word export called from too many files to be searchable.",
|
|
66
|
+
judged: true,
|
|
67
|
+
move: "expand",
|
|
68
|
+
onUnavailable: "propagate",
|
|
69
|
+
messages: messages({
|
|
70
|
+
common_name: "`{{name}}` is called from {{count}} files, and it is a {{kind}} rather than an address.",
|
|
71
|
+
common_name_help: "A name is how this declaration is found: it is the address, not a summary. Rename it to say what it is for -- `{{name}}` gives a reader and an agent nothing to narrow by, while a name of two or three specific words makes every future search cheaper.{{review}}",
|
|
72
|
+
}),
|
|
73
|
+
plan: Effect.fn("joggle/name-as-address")(function* (workspace, scope) {
|
|
74
|
+
const report = reporter(nameAsAddress, locator(workspace));
|
|
75
|
+
const { minFiles, maxFiles, maxCallers } = policy.nameAsAddress;
|
|
76
|
+
const exported = workspace.units.filter((unit) => unit.exported);
|
|
77
|
+
// Which files call each declaration, by resolved identity.
|
|
78
|
+
const calledFrom = new Map();
|
|
79
|
+
for (const unit of workspace.units) {
|
|
80
|
+
for (const callee of unit.calls) {
|
|
81
|
+
const files = calledFrom.get(callee) ?? new Set();
|
|
82
|
+
files.add(unit.file);
|
|
83
|
+
calledFrom.set(callee, files);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
const candidates = exported
|
|
87
|
+
.filter((unit) => isSingleWord(unit.name))
|
|
88
|
+
.filter((unit) => scope.changed === undefined || scope.changed.has(unit.file))
|
|
89
|
+
.map((unit) => ({
|
|
90
|
+
unit,
|
|
91
|
+
callers: [...(calledFrom.get(unit.file + "#" + unit.name) ?? new Set())].sort(Order.String),
|
|
92
|
+
}))
|
|
93
|
+
.filter((entry) => entry.callers.length >= minFiles)
|
|
94
|
+
.sort((left, right) => right.callers.length - left.callers.length);
|
|
95
|
+
if (candidates.length === 0) {
|
|
96
|
+
return {
|
|
97
|
+
plans: [],
|
|
98
|
+
read: () => outcome([], [
|
|
99
|
+
exported.length +
|
|
100
|
+
" exported declaration(s), none of them a single-word name called from " +
|
|
101
|
+
minFiles +
|
|
102
|
+
" or more files",
|
|
103
|
+
]),
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
const judged = candidates.slice(0, maxFiles);
|
|
107
|
+
const atoms = yield* Atoms;
|
|
108
|
+
const planned = [];
|
|
109
|
+
for (const candidate of judged) {
|
|
110
|
+
const id = yield* atoms.add({
|
|
111
|
+
name: {
|
|
112
|
+
identifier: candidate.unit.name,
|
|
113
|
+
declared: candidate.unit.file,
|
|
114
|
+
files: candidate.callers.length,
|
|
115
|
+
callers: candidate.callers.slice(0, maxCallers),
|
|
116
|
+
},
|
|
117
|
+
});
|
|
118
|
+
planned.push({
|
|
119
|
+
candidate,
|
|
120
|
+
plan: {
|
|
121
|
+
ruleId: RULE_ID,
|
|
122
|
+
subject: candidate.unit.file + "#" + candidate.unit.name,
|
|
123
|
+
concerns: [candidate.unit.file],
|
|
124
|
+
atoms: [id],
|
|
125
|
+
violations: { fails_as_address: [] },
|
|
126
|
+
decisions: nameReview(id),
|
|
127
|
+
read: (answers) => answers,
|
|
128
|
+
},
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
const overflow = candidates.slice(maxFiles).map((candidate) => ({
|
|
132
|
+
ruleId: RULE_ID,
|
|
133
|
+
subject: candidate.unit.file + "#" + candidate.unit.name,
|
|
134
|
+
stage: "budget",
|
|
135
|
+
reason: "past the budget of " + maxFiles + " common names",
|
|
136
|
+
}));
|
|
137
|
+
return {
|
|
138
|
+
plans: planned.map((entry) => entry.plan),
|
|
139
|
+
read: (answers) => {
|
|
140
|
+
const verdicts = verdictsOf(answers);
|
|
141
|
+
const diagnostics = [];
|
|
142
|
+
const drops = [...overflow];
|
|
143
|
+
planned.forEach((entry, index) => {
|
|
144
|
+
const candidate = entry.candidate;
|
|
145
|
+
const answer = verdicts[index];
|
|
146
|
+
if (answer === undefined) {
|
|
147
|
+
drops.push({
|
|
148
|
+
ruleId: RULE_ID,
|
|
149
|
+
subject: candidate.unit.file + "#" + candidate.unit.name,
|
|
150
|
+
stage: "unreadable",
|
|
151
|
+
reason: "the response did not judge this name",
|
|
152
|
+
});
|
|
153
|
+
return;
|
|
154
|
+
}
|
|
155
|
+
const fails = answer["fails_as_address"];
|
|
156
|
+
const address = answer["address"];
|
|
157
|
+
if (fails === undefined || !("probability" in fails) || address === undefined || !("label" in address)) {
|
|
158
|
+
drops.push({
|
|
159
|
+
ruleId: RULE_ID,
|
|
160
|
+
subject: candidate.unit.file + "#" + candidate.unit.name,
|
|
161
|
+
stage: "unreadable",
|
|
162
|
+
reason: "the response did not contain a usable verdict",
|
|
163
|
+
});
|
|
164
|
+
return;
|
|
165
|
+
}
|
|
166
|
+
if (declined(address.label)) {
|
|
167
|
+
drops.push({
|
|
168
|
+
ruleId: RULE_ID,
|
|
169
|
+
subject: candidate.unit.file + "#" + candidate.unit.name,
|
|
170
|
+
stage: "declined",
|
|
171
|
+
reason: "the name still finds this declaration",
|
|
172
|
+
});
|
|
173
|
+
return;
|
|
174
|
+
}
|
|
175
|
+
const quality = qualityOf({
|
|
176
|
+
score: fails.probability,
|
|
177
|
+
margin: marginOfAnswer(address),
|
|
178
|
+
confidence: address.confidence,
|
|
179
|
+
});
|
|
180
|
+
if (quality.quality === "drop") {
|
|
181
|
+
drops.push({
|
|
182
|
+
ruleId: RULE_ID,
|
|
183
|
+
subject: candidate.unit.file + "#" + candidate.unit.name,
|
|
184
|
+
stage: "gated",
|
|
185
|
+
reason: quality.reason,
|
|
186
|
+
});
|
|
187
|
+
return;
|
|
188
|
+
}
|
|
189
|
+
const review = quality.quality === "review";
|
|
190
|
+
diagnostics.push(report({
|
|
191
|
+
about: candidate.unit,
|
|
192
|
+
messageId: "common_name",
|
|
193
|
+
data: {
|
|
194
|
+
name: candidate.unit.name,
|
|
195
|
+
count: candidate.callers.length,
|
|
196
|
+
kind: (address.label ?? "").replace(/_/g, " "),
|
|
197
|
+
review: review ? " For review: " + quality.reason + "." : "",
|
|
198
|
+
},
|
|
199
|
+
helpId: "common_name_help",
|
|
200
|
+
identity: [RULE_ID, candidate.unit.file, candidate.unit.name].join("\u0000"),
|
|
201
|
+
confidence: address.confidence ?? 1,
|
|
202
|
+
score: fails.probability,
|
|
203
|
+
judged: true,
|
|
204
|
+
severity: review ? "info" : "warn",
|
|
205
|
+
}));
|
|
206
|
+
});
|
|
207
|
+
return outcome(diagnostics, budgetNote({
|
|
208
|
+
unitKind: "common names",
|
|
209
|
+
judged: maxFiles,
|
|
210
|
+
candidates: candidates.length,
|
|
211
|
+
sample: candidates.slice(maxFiles).map((c) => c.unit.name),
|
|
212
|
+
}), drops);
|
|
213
|
+
},
|
|
214
|
+
};
|
|
215
|
+
})
|
|
216
|
+
};
|
|
@@ -0,0 +1,203 @@
|
|
|
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 { fieldGroups } from "../candidates.js";
|
|
6
|
+
import { verdictsOf } from "../plans.js";
|
|
7
|
+
import { locator, messages, reporter } from "../reporting.js";
|
|
8
|
+
import { verdictOf } from "../verdict.js";
|
|
9
|
+
import { budgetNote, outcome, qualityOf, } from "../rule.js";
|
|
10
|
+
import { typeUnits } from "../workspace.js";
|
|
11
|
+
const RULE_ID = "joggle/name-the-primitive";
|
|
12
|
+
/** Which labels mean this rule is violated -- the read and the calibration share it. */
|
|
13
|
+
const VIOLATIONS = { verdict: ["one_thing"] };
|
|
14
|
+
// A group of fields that always appears together and has no name.
|
|
15
|
+
//
|
|
16
|
+
// `compose-types` finds a type that repeats a NAMED type; this finds the shape
|
|
17
|
+
// nobody has named yet -- the three or four fields that appear together in nine
|
|
18
|
+
// declarations and are re-declared each time, so every new declaration is a
|
|
19
|
+
// chance to get one of them slightly wrong.
|
|
20
|
+
//
|
|
21
|
+
// What is deterministic is the mining. Pair co-occurrence, then the intersection
|
|
22
|
+
// of the declarations that carry a pair, gives GROUPS without mining every subset
|
|
23
|
+
// of every declaration. What a person then decides -- is this genuinely one
|
|
24
|
+
// thing? -- used to be left to the reader. It is now asked.
|
|
25
|
+
export const nameThePrimitive = {
|
|
26
|
+
id: RULE_ID,
|
|
27
|
+
severity: "info",
|
|
28
|
+
description: "A group of fields repeated across declarations with no name of its own.",
|
|
29
|
+
judged: true,
|
|
30
|
+
move: "expand",
|
|
31
|
+
onUnavailable: "report",
|
|
32
|
+
messages: messages({
|
|
33
|
+
fields_unnamed: "{{fields}} appear together in {{count}} declaration(s) and are never named as one thing.",
|
|
34
|
+
fields_unnamed_help: "Extract them as a named type and compose it, so the next declaration adds a field in one place instead of four. See {{file}}:{{line}}, where {{name}} repeats them.{{unverified}}",
|
|
35
|
+
}),
|
|
36
|
+
plan: Effect.fn("joggle/name-the-primitive")(function* (workspace, scope) {
|
|
37
|
+
const report = reporter(nameThePrimitive, locator(workspace));
|
|
38
|
+
const { minFields, minOccurrences, maxFindings } = policy.nameThePrimitive;
|
|
39
|
+
const types = workspace.units.filter(typeUnits(minFields));
|
|
40
|
+
if (types.length === 0) {
|
|
41
|
+
return {
|
|
42
|
+
plans: [],
|
|
43
|
+
read: () => outcome([], [
|
|
44
|
+
"no type declaration has " +
|
|
45
|
+
minFields +
|
|
46
|
+
" or more fields, so there was nothing to mine for repeated groups",
|
|
47
|
+
]),
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
// The mining lives in the candidate engine: pair co-occurrence, then the
|
|
51
|
+
// intersection of the declarations that carry a pair, which gives groups
|
|
52
|
+
// without mining every subset of every declaration.
|
|
53
|
+
const candidates = fieldGroups({ units: types, minFields, minOccurrences, scope });
|
|
54
|
+
if (candidates.length === 0) {
|
|
55
|
+
return {
|
|
56
|
+
plans: [],
|
|
57
|
+
read: () => outcome([], [
|
|
58
|
+
types.length +
|
|
59
|
+
" type declaration(s); no field group repeats in " +
|
|
60
|
+
minOccurrences +
|
|
61
|
+
" or more declarations without already having a name",
|
|
62
|
+
]),
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
const judged = candidates.slice(0, maxFindings);
|
|
66
|
+
const overBudget = candidates.slice(maxFindings).map((entry) => ({
|
|
67
|
+
ruleId: RULE_ID,
|
|
68
|
+
subject: "field group { " + entry.fields.join(", ") + " }",
|
|
69
|
+
stage: "budget",
|
|
70
|
+
reason: "past the budget of " + String(maxFindings) + " groups",
|
|
71
|
+
}));
|
|
72
|
+
const atoms = yield* Atoms;
|
|
73
|
+
const planned = yield* Effect.forEach(judged, (entry) => Effect.gen(function* () {
|
|
74
|
+
const first = entry.units[0];
|
|
75
|
+
if (first === undefined)
|
|
76
|
+
return undefined;
|
|
77
|
+
// The state is the field names and a bounded sample of the declarations
|
|
78
|
+
// that carry them, not every declaration's source.
|
|
79
|
+
const declarations = entry.units.slice(0, 4).map((unit) => ({
|
|
80
|
+
name: unit.name,
|
|
81
|
+
file: unit.file,
|
|
82
|
+
line: unit.location.line,
|
|
83
|
+
source: unit.text.slice(0, policy.evidence.maxSourceChars > 200 ? 200 : policy.evidence.maxSourceChars),
|
|
84
|
+
}));
|
|
85
|
+
// Each field's resolved type across the declarations, so a field that
|
|
86
|
+
// only shares a NAME is visible as two meanings rather than one shape.
|
|
87
|
+
const fieldTypes = entry.fields.map((field) => ({
|
|
88
|
+
field,
|
|
89
|
+
types: [
|
|
90
|
+
...new Set(entry.units
|
|
91
|
+
.map((unit) => {
|
|
92
|
+
const member = unit.typeFacts?.members.find((item) => item.name === field);
|
|
93
|
+
return member === undefined ? unit.fieldTypes.get(field) : member.type;
|
|
94
|
+
})
|
|
95
|
+
.filter((type) => type !== undefined)),
|
|
96
|
+
].slice(0, 4),
|
|
97
|
+
}));
|
|
98
|
+
const id = yield* atoms.add({
|
|
99
|
+
fields: entry.fields,
|
|
100
|
+
fieldTypes,
|
|
101
|
+
occurrences: entry.units.length,
|
|
102
|
+
declarations,
|
|
103
|
+
});
|
|
104
|
+
const plan = {
|
|
105
|
+
ruleId: RULE_ID,
|
|
106
|
+
subject: "field group { " + entry.fields.join(", ") + " }",
|
|
107
|
+
concerns: [...new Set(entry.units.map((unit) => unit.file))],
|
|
108
|
+
atoms: [id],
|
|
109
|
+
violations: VIOLATIONS,
|
|
110
|
+
decisions: {
|
|
111
|
+
verdict: Decision.classify({
|
|
112
|
+
instructions: [
|
|
113
|
+
`\`atoms[${id}].fields\` are ${entry.fields.length} field names that appear together in ${entry.units.length} declarations: ${entry.units.slice(0, 6).map((unit) => unit.name).join(", ")}. \`atoms[${id}].declarations\` shows a few of them.`,
|
|
114
|
+
"`atoms[" + id + "].fieldTypes` is each field's resolved type across the declarations. A field that means two different things is not one concept, whatever its name.",
|
|
115
|
+
"The fields appearing together in every one of those declarations is the signal: a set that always travels together is a shape, and each new declaration copies it from memory.",
|
|
116
|
+
"Is that set of fields ONE THING -- a primitive that deserves a name and should be composed everywhere it appears -- or do those declarations reuse the same field names for different reasons?",
|
|
117
|
+
"Answer `one_thing` when the fields always travel together as one concept, so one named type would replace all of them.",
|
|
118
|
+
"Answer `unrelated` only when the declarations genuinely use the fields for different purposes, so one type would be wrong however often they appear together.",
|
|
119
|
+
"Answer `already_named` when a declared type already names exactly this set.",
|
|
120
|
+
].join("\n"),
|
|
121
|
+
criteria: {
|
|
122
|
+
one_thing: "The fields are one concept. Extract a named type and compose it everywhere.",
|
|
123
|
+
unrelated: "The declarations use the fields for genuinely different purposes. No one type would be right.",
|
|
124
|
+
already_named: "A declared type already covers exactly this field set.",
|
|
125
|
+
},
|
|
126
|
+
}),
|
|
127
|
+
},
|
|
128
|
+
read: (answers) => answers,
|
|
129
|
+
};
|
|
130
|
+
return { entry, first, id, plan };
|
|
131
|
+
}), { concurrency: "unbounded" });
|
|
132
|
+
const present = planned.filter((value) => value !== undefined);
|
|
133
|
+
return {
|
|
134
|
+
plans: present.map((value) => value.plan),
|
|
135
|
+
read: (answers) => {
|
|
136
|
+
const verdicts = verdictsOf(answers);
|
|
137
|
+
const diagnostics = [];
|
|
138
|
+
const drops = [...overBudget];
|
|
139
|
+
present.forEach((value, index) => {
|
|
140
|
+
const { entry } = value;
|
|
141
|
+
const subject = "field group { " + entry.fields.join(", ") + " }";
|
|
142
|
+
const answer = verdicts[index];
|
|
143
|
+
const verdict = verdictOf(answer?.["verdict"], VIOLATIONS.verdict);
|
|
144
|
+
if (verdict === undefined) {
|
|
145
|
+
diagnostics.push(findingFor(report, value, undefined, "no judgement was available"));
|
|
146
|
+
return;
|
|
147
|
+
}
|
|
148
|
+
if (verdict.label !== "one_thing") {
|
|
149
|
+
drops.push({
|
|
150
|
+
ruleId: RULE_ID,
|
|
151
|
+
subject,
|
|
152
|
+
stage: "declined",
|
|
153
|
+
reason: verdict.label === "already_named"
|
|
154
|
+
? "a declared type already names this set"
|
|
155
|
+
: "the declarations reuse the field names for different reasons",
|
|
156
|
+
});
|
|
157
|
+
return;
|
|
158
|
+
}
|
|
159
|
+
const quality = qualityOf({
|
|
160
|
+
score: verdict.probability,
|
|
161
|
+
margin: verdict.margin,
|
|
162
|
+
confidence: verdict.confidence,
|
|
163
|
+
});
|
|
164
|
+
if (quality.quality === "drop") {
|
|
165
|
+
drops.push({
|
|
166
|
+
ruleId: RULE_ID,
|
|
167
|
+
subject,
|
|
168
|
+
stage: "gated",
|
|
169
|
+
reason: quality.reason,
|
|
170
|
+
});
|
|
171
|
+
return;
|
|
172
|
+
}
|
|
173
|
+
diagnostics.push(findingFor(report, value, verdict.confidence, undefined));
|
|
174
|
+
});
|
|
175
|
+
return outcome(diagnostics, budgetNote({
|
|
176
|
+
unitKind: "groups",
|
|
177
|
+
judged: maxFindings,
|
|
178
|
+
candidates: candidates.length,
|
|
179
|
+
sample: candidates.slice(maxFindings).map((entry) => entry.fields.join(", ")),
|
|
180
|
+
}), drops);
|
|
181
|
+
},
|
|
182
|
+
};
|
|
183
|
+
}),
|
|
184
|
+
};
|
|
185
|
+
const findingFor = (report, value, confidence, unverifiedReason) => {
|
|
186
|
+
const { entry, first } = value;
|
|
187
|
+
return report({
|
|
188
|
+
about: first,
|
|
189
|
+
messageId: "fields_unnamed",
|
|
190
|
+
data: {
|
|
191
|
+
fields: entry.fields.join(", "),
|
|
192
|
+
count: entry.units.length,
|
|
193
|
+
file: first.file,
|
|
194
|
+
line: first.location.line,
|
|
195
|
+
name: first.name,
|
|
196
|
+
unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
|
|
197
|
+
},
|
|
198
|
+
helpId: "fields_unnamed_help",
|
|
199
|
+
identity: [RULE_ID, entry.fields.join("\u0000")].join("\u0000"),
|
|
200
|
+
judged: unverifiedReason === undefined,
|
|
201
|
+
confidence,
|
|
202
|
+
});
|
|
203
|
+
};
|