@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,242 @@
|
|
|
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 { readsIn } from "../sql.js";
|
|
9
|
+
import { verdictOf } from "../verdict.js";
|
|
10
|
+
import { unitFields } from "../workspace.js";
|
|
11
|
+
const RULE_ID = "joggle/declared-staleness";
|
|
12
|
+
// A projection is a materialized function: it is a function of facts, it has an
|
|
13
|
+
// age, and it has a refresh. A projection that states none of the three has
|
|
14
|
+
// staleness by assumption, and the assumption lives in someone's head.
|
|
15
|
+
//
|
|
16
|
+
// The deterministic half is the shape: a read of a table, or a type whose fields
|
|
17
|
+
// repeat a table's columns. There is no list of names that mean "cache". Whether
|
|
18
|
+
// the data may be stale, and whether anything near the read says so, are two
|
|
19
|
+
// questions -- the second is asked because recognising a declaration by token is
|
|
20
|
+
// exactly the kind of hand-maintained vocabulary the classifier replaces.
|
|
21
|
+
export const declaredStaleness = {
|
|
22
|
+
id: RULE_ID,
|
|
23
|
+
severity: "warn",
|
|
24
|
+
description: "A projection whose allowed staleness is not declared.",
|
|
25
|
+
judged: true,
|
|
26
|
+
onUnavailable: "report",
|
|
27
|
+
messages: messages({
|
|
28
|
+
assumed: "`{{unit}}` is a projection, and nothing near it says how stale it may be.",
|
|
29
|
+
assumed_help: "A projection is a materialized function. Say what it is a function of, how stale it may be, and how it is refreshed -- a TTL, a refresh call, or a policy constant beside the read. Until then, freshness is an assumption.{{unverified}}",
|
|
30
|
+
}),
|
|
31
|
+
plan: Effect.fn("joggle/declared-staleness")(function* (workspace, scope) {
|
|
32
|
+
const report = reporter(declaredStaleness, locator(workspace));
|
|
33
|
+
// Columns by table, from the migrations the workspace already parsed.
|
|
34
|
+
const columnsOf = new Map();
|
|
35
|
+
for (const file of workspace.files) {
|
|
36
|
+
for (const column of file.facts.columns) {
|
|
37
|
+
const found = columnsOf.get(column.table) ?? new Set();
|
|
38
|
+
found.add(column.column);
|
|
39
|
+
columnsOf.set(column.table, found);
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
const candidates = [];
|
|
43
|
+
for (const file of workspace.files) {
|
|
44
|
+
if (scope.changed !== undefined && !inScope(scope, file.path))
|
|
45
|
+
continue;
|
|
46
|
+
const reads = readsIn(file.text);
|
|
47
|
+
for (const unit of file.units) {
|
|
48
|
+
if (!unit.exported)
|
|
49
|
+
continue;
|
|
50
|
+
if (reads.length > 0) {
|
|
51
|
+
candidates.push({ unit, reads });
|
|
52
|
+
continue;
|
|
53
|
+
}
|
|
54
|
+
// A type whose fields repeat a table's columns is a denormalised
|
|
55
|
+
// structure even when nothing in this file reads it.
|
|
56
|
+
if (unit.kind === "function")
|
|
57
|
+
continue;
|
|
58
|
+
const fields = unitFields(unit);
|
|
59
|
+
const repeated = [...columnsOf.keys()].some((table) => {
|
|
60
|
+
const columns = columnsOf.get(table);
|
|
61
|
+
if (columns === undefined)
|
|
62
|
+
return false;
|
|
63
|
+
const shared = fields.filter((field) => columns.has(field)).length;
|
|
64
|
+
return shared >= policy.strata.minSharedFields;
|
|
65
|
+
});
|
|
66
|
+
if (repeated)
|
|
67
|
+
candidates.push({ unit, reads: [] });
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
if (candidates.length === 0) {
|
|
71
|
+
return {
|
|
72
|
+
plans: [],
|
|
73
|
+
read: () => outcome([], [
|
|
74
|
+
"no exported read of a table, and no type repeating a table's columns, was found",
|
|
75
|
+
]),
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
const judged = candidates.slice(0, policy.strata.maxCandidates);
|
|
79
|
+
const overBudget = candidates
|
|
80
|
+
.slice(policy.strata.maxCandidates)
|
|
81
|
+
.map((candidate) => ({
|
|
82
|
+
ruleId: RULE_ID,
|
|
83
|
+
subject: candidate.unit.name,
|
|
84
|
+
stage: "budget",
|
|
85
|
+
reason: "past the budget of " + String(policy.strata.maxCandidates) + " projections",
|
|
86
|
+
}));
|
|
87
|
+
const atoms = yield* Atoms;
|
|
88
|
+
const planned = yield* Effect.forEach(judged, (candidate) => Effect.gen(function* () {
|
|
89
|
+
const id = yield* atoms.add({
|
|
90
|
+
projection: {
|
|
91
|
+
unit: candidate.unit.name,
|
|
92
|
+
kind: candidate.unit.kind,
|
|
93
|
+
file: candidate.unit.file,
|
|
94
|
+
reads: [...candidate.reads],
|
|
95
|
+
},
|
|
96
|
+
documentation: (candidate.unit.doc ?? "").slice(0, policy.evidence.maxDocChars),
|
|
97
|
+
source: candidate.unit.text.slice(0, policy.evidence.maxSourceChars),
|
|
98
|
+
});
|
|
99
|
+
const plan = {
|
|
100
|
+
ruleId: RULE_ID,
|
|
101
|
+
subject: candidate.unit.name,
|
|
102
|
+
concerns: [candidate.unit.file],
|
|
103
|
+
atoms: [id],
|
|
104
|
+
violations: { verdict: ["allowed"] },
|
|
105
|
+
decisions: {
|
|
106
|
+
verdict: Decision.classify({
|
|
107
|
+
instructions: {
|
|
108
|
+
question: "May this data be stale?",
|
|
109
|
+
projection: `\`atoms[${id}].projection.unit\` reads \`atoms[${id}].projection.reads\`; its documentation is \`atoms[${id}].documentation\`.`,
|
|
110
|
+
compare: [
|
|
111
|
+
`atoms[${id}].projection`,
|
|
112
|
+
`atoms[${id}].source`,
|
|
113
|
+
`atoms[${id}].documentation`,
|
|
114
|
+
],
|
|
115
|
+
focus: "Answer `allowed` when freshness is a business choice, NOT when the code is merely convenient. `must_be_current` is a decision that changes when the data is old. `not_a_projection` is a value computed at read time or not derived from stored rows.",
|
|
116
|
+
},
|
|
117
|
+
criteria: {
|
|
118
|
+
allowed: {
|
|
119
|
+
means: "This data may be stale; the business tolerates an age.",
|
|
120
|
+
excludes: "A value a decision is made from, or anything whose reader assumes it is current.",
|
|
121
|
+
},
|
|
122
|
+
must_be_current: {
|
|
123
|
+
means: "The read must reflect current facts; staleness would change a decision.",
|
|
124
|
+
excludes: "A dashboard or summary whose age is stated.",
|
|
125
|
+
},
|
|
126
|
+
not_a_projection: {
|
|
127
|
+
means: "The value is computed at read time from current state, or is not derived data.",
|
|
128
|
+
excludes: "A stored copy that is refreshed.",
|
|
129
|
+
},
|
|
130
|
+
},
|
|
131
|
+
}),
|
|
132
|
+
undeclared: Decision.probability({
|
|
133
|
+
instructions: {
|
|
134
|
+
question: "Is this projection's staleness left undeclared?",
|
|
135
|
+
evidence: `Read \`atoms[${id}].source\` and \`atoms[${id}].documentation\`.`,
|
|
136
|
+
focus: "A declaration says what the projection is a function of, how stale it may be, and how it is refreshed -- a TTL, a policy constant, a scheduler call, or a sentence beside the read. Answer true when nothing here says it.",
|
|
137
|
+
},
|
|
138
|
+
criteria: {
|
|
139
|
+
false: "Something here states the bound or the refresh.",
|
|
140
|
+
true: "Nothing here states the bound or the refresh.",
|
|
141
|
+
},
|
|
142
|
+
}),
|
|
143
|
+
},
|
|
144
|
+
read: (answers) => answers,
|
|
145
|
+
};
|
|
146
|
+
return { candidate, plan };
|
|
147
|
+
}), { concurrency: "unbounded" });
|
|
148
|
+
return {
|
|
149
|
+
plans: planned.map((entry) => entry.plan),
|
|
150
|
+
read: (answers) => {
|
|
151
|
+
const verdicts = verdictsOf(answers);
|
|
152
|
+
const diagnostics = [];
|
|
153
|
+
const drops = [...overBudget];
|
|
154
|
+
planned.forEach((entry, index) => {
|
|
155
|
+
const { candidate } = entry;
|
|
156
|
+
const verdict = verdictOf(verdicts[index]?.["verdict"], ["allowed"]);
|
|
157
|
+
if (verdict === undefined) {
|
|
158
|
+
diagnostics.push(findingFor({
|
|
159
|
+
report,
|
|
160
|
+
entry,
|
|
161
|
+
confidence: undefined,
|
|
162
|
+
unverifiedReason: "no judgement was available",
|
|
163
|
+
}));
|
|
164
|
+
return;
|
|
165
|
+
}
|
|
166
|
+
if (verdict.label !== "allowed") {
|
|
167
|
+
drops.push({
|
|
168
|
+
ruleId: RULE_ID,
|
|
169
|
+
subject: candidate.unit.name,
|
|
170
|
+
stage: "declined",
|
|
171
|
+
reason: verdict.label === "must_be_current"
|
|
172
|
+
? "declared current"
|
|
173
|
+
: "not a projection",
|
|
174
|
+
});
|
|
175
|
+
return;
|
|
176
|
+
}
|
|
177
|
+
const undeclared = verdictOf(verdicts[index]?.["undeclared"], []);
|
|
178
|
+
if (undeclared === undefined) {
|
|
179
|
+
diagnostics.push(findingFor({
|
|
180
|
+
report,
|
|
181
|
+
entry,
|
|
182
|
+
confidence: verdict.confidence,
|
|
183
|
+
unverifiedReason: "the staleness declaration could not be judged",
|
|
184
|
+
}));
|
|
185
|
+
return;
|
|
186
|
+
}
|
|
187
|
+
if (undeclared.probability < policy.decision.gates.probabilityFloor) {
|
|
188
|
+
drops.push({
|
|
189
|
+
ruleId: RULE_ID,
|
|
190
|
+
subject: candidate.unit.name,
|
|
191
|
+
stage: "declined",
|
|
192
|
+
reason: "staleness is declared",
|
|
193
|
+
});
|
|
194
|
+
return;
|
|
195
|
+
}
|
|
196
|
+
const quality = qualityOf({
|
|
197
|
+
score: verdict.probability,
|
|
198
|
+
margin: verdict.margin,
|
|
199
|
+
confidence: verdict.confidence,
|
|
200
|
+
});
|
|
201
|
+
if (quality.quality === "drop") {
|
|
202
|
+
drops.push({
|
|
203
|
+
ruleId: RULE_ID,
|
|
204
|
+
subject: candidate.unit.name,
|
|
205
|
+
stage: "gated",
|
|
206
|
+
reason: quality.reason,
|
|
207
|
+
});
|
|
208
|
+
return;
|
|
209
|
+
}
|
|
210
|
+
diagnostics.push(findingFor({
|
|
211
|
+
report,
|
|
212
|
+
entry,
|
|
213
|
+
confidence: verdict.confidence,
|
|
214
|
+
unverifiedReason: undefined,
|
|
215
|
+
review: quality.quality === "review",
|
|
216
|
+
}));
|
|
217
|
+
});
|
|
218
|
+
return outcome(diagnostics, budgetNote({
|
|
219
|
+
unitKind: "projections",
|
|
220
|
+
judged: judged.length,
|
|
221
|
+
candidates: candidates.length,
|
|
222
|
+
sample: candidates
|
|
223
|
+
.slice(policy.strata.maxCandidates)
|
|
224
|
+
.map((candidate) => candidate.unit.name),
|
|
225
|
+
}), drops);
|
|
226
|
+
},
|
|
227
|
+
};
|
|
228
|
+
}),
|
|
229
|
+
};
|
|
230
|
+
const findingFor = ({ report, entry, confidence, unverifiedReason, review = false, }) => report({
|
|
231
|
+
about: entry.candidate.unit,
|
|
232
|
+
messageId: "assumed",
|
|
233
|
+
data: {
|
|
234
|
+
unit: entry.candidate.unit.name,
|
|
235
|
+
unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
|
|
236
|
+
},
|
|
237
|
+
helpId: "assumed_help",
|
|
238
|
+
identity: [RULE_ID, entry.candidate.unit.file, entry.candidate.unit.name].join("\u0000"),
|
|
239
|
+
judged: unverifiedReason === undefined,
|
|
240
|
+
confidence,
|
|
241
|
+
severity: review ? "info" : "warn",
|
|
242
|
+
});
|
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
import { Effect } from "effect";
|
|
2
|
+
import { builtinModules } from "node:module";
|
|
3
|
+
import { Decision } from "effect/ai";
|
|
4
|
+
import { Atoms } from "../atoms.js";
|
|
5
|
+
import { policy } from "../policy.js";
|
|
6
|
+
import { verdictsOf } from "../plans.js";
|
|
7
|
+
import { locator, messages, reporter } from "../reporting.js";
|
|
8
|
+
import { budgetNote, inGraphScope, marginOfAnswer, outcome, } from "../rule.js";
|
|
9
|
+
import { packageNameOf } from "../roles.js";
|
|
10
|
+
import { dependencyVocabulary } from "../vocabulary.js";
|
|
11
|
+
// meta-allow: no-pattern-classifier -- a file-extension test (`/\.(?:[cm]?[jt]sx?)$/`) on an import specifier -- a
|
|
12
|
+
// language fact about what a source file is called, not this repository's naming. docs/rule-coupling.md.
|
|
13
|
+
const RULE_ID = "joggle/dependency-fit";
|
|
14
|
+
/**
|
|
15
|
+
* The module a file belongs to, from its path alone.
|
|
16
|
+
*
|
|
17
|
+
* Two segments: `services/ui/app/routes/x.ts` is `services/ui`. This is a
|
|
18
|
+
* heuristic, and the only one in this rule -- but it is DERIVED from the paths
|
|
19
|
+
* rather than declared, so it cannot go stale, and a repository that groups its
|
|
20
|
+
* code some other way still gets questions about the groups it actually has.
|
|
21
|
+
*/
|
|
22
|
+
const moduleOf = (file) => file.split("/").slice(0, 2).join("/");
|
|
23
|
+
/**
|
|
24
|
+
* Node's own modules, which no manifest declares and no repository should.
|
|
25
|
+
*
|
|
26
|
+
* From the runtime rather than a written list: `import { builtinModules } from
|
|
27
|
+
* "node:module"` is the same set the interpreter enforces, so it cannot go stale
|
|
28
|
+
* as Node adds modules.
|
|
29
|
+
*/
|
|
30
|
+
const BUILTINS = new Set([...builtinModules, ...builtinModules.map((name) => "node:" + name)]);
|
|
31
|
+
/**
|
|
32
|
+
* Whether a specifier names something inside this repository.
|
|
33
|
+
*
|
|
34
|
+
* An unresolved import is not automatically a dependency. `src/authorization/
|
|
35
|
+
* index.js` in 37 files and `@shared/types/safety-forms` are paths and path
|
|
36
|
+
* aliases that the resolver could not follow -- tsconfig `paths` are not read --
|
|
37
|
+
* and reporting them as undeclared dependencies is noise that buries the seven
|
|
38
|
+
* real ones.
|
|
39
|
+
*
|
|
40
|
+
* Derived from the file set rather than from a list of aliases: the directories
|
|
41
|
+
* the repository actually contains. A specifier that mentions one of them names
|
|
42
|
+
* something here, whatever prefix it wears.
|
|
43
|
+
*/
|
|
44
|
+
const internalNames = (workspace) => {
|
|
45
|
+
const names = new Set();
|
|
46
|
+
for (const file of workspace.files) {
|
|
47
|
+
const parts = file.path.split("/");
|
|
48
|
+
for (const part of parts.slice(0, -1))
|
|
49
|
+
names.add(part);
|
|
50
|
+
}
|
|
51
|
+
return names;
|
|
52
|
+
};
|
|
53
|
+
const isInternalPath = (specifier, internal) => {
|
|
54
|
+
// A specifier with a source extension names a file.
|
|
55
|
+
if (/\.(?:[cm]?[jt]sx?)$/.test(specifier))
|
|
56
|
+
return true;
|
|
57
|
+
return specifier.split("/").some((segment) => internal.has(segment));
|
|
58
|
+
};
|
|
59
|
+
const dependenciesIn = (workspace) => {
|
|
60
|
+
const internal = internalNames(workspace);
|
|
61
|
+
const grouped = new Map();
|
|
62
|
+
for (const edge of workspace.imports.edges) {
|
|
63
|
+
// Internal imports are `layer-direction`'s business, and a relative specifier
|
|
64
|
+
// cannot be a dependency on a framework.
|
|
65
|
+
if (edge.resolution === "resolved")
|
|
66
|
+
continue;
|
|
67
|
+
if (edge.specifier.startsWith(".") || edge.specifier.startsWith("/"))
|
|
68
|
+
continue;
|
|
69
|
+
if (BUILTINS.has(edge.specifier))
|
|
70
|
+
continue;
|
|
71
|
+
// A path into an installed tree is not an import of a package, and a package
|
|
72
|
+
// importing itself is internal structuring rather than a dependency.
|
|
73
|
+
if (edge.specifier.includes("/node_modules/"))
|
|
74
|
+
continue;
|
|
75
|
+
if (isInternalPath(edge.specifier, internal))
|
|
76
|
+
continue;
|
|
77
|
+
const cut = edge.importer.lastIndexOf("/");
|
|
78
|
+
const directory = cut === -1 ? "." : edge.importer.slice(0, cut);
|
|
79
|
+
const manifest = workspace.manifests.get(directory);
|
|
80
|
+
// The package's own name is a better grouping than two path segments: it is
|
|
81
|
+
// what the package IS rather than where it happens to sit, and it collapses
|
|
82
|
+
// `packages/fasdentify/src/a.ts` and `packages/fasdentify/test/b.ts` into one
|
|
83
|
+
// thing without guessing at a directory depth.
|
|
84
|
+
const path = manifest?.name ?? moduleOf(edge.importer);
|
|
85
|
+
if (path.length === 0)
|
|
86
|
+
continue;
|
|
87
|
+
const key = path + "\u0000" + edge.specifier;
|
|
88
|
+
const existing = grouped.get(key);
|
|
89
|
+
if (existing === undefined) {
|
|
90
|
+
grouped.set(key, {
|
|
91
|
+
path,
|
|
92
|
+
directory,
|
|
93
|
+
declares: manifest?.declares ?? [],
|
|
94
|
+
specifier: edge.specifier,
|
|
95
|
+
count: 1,
|
|
96
|
+
examples: [edge.importer],
|
|
97
|
+
});
|
|
98
|
+
continue;
|
|
99
|
+
}
|
|
100
|
+
existing.count += 1;
|
|
101
|
+
if (existing.examples.length < policy.evidence.maxListedPaths)
|
|
102
|
+
existing.examples.push(edge.importer);
|
|
103
|
+
}
|
|
104
|
+
const sorted = [...grouped.values()].sort((left, right) => left.path.localeCompare(right.path) || left.specifier.localeCompare(right.specifier));
|
|
105
|
+
// A dependency the package declares for itself is answered before it is asked.
|
|
106
|
+
// This is the case that made the rule look foolish: `packages/fasdentify
|
|
107
|
+
// depends on fastify in 29 files` is not a violation, it is what fasdentify is
|
|
108
|
+
// FOR, and its own manifest said so all along. No call, no judgement, no
|
|
109
|
+
// configuration -- a fact, derived from the file the package already keeps.
|
|
110
|
+
const dependencies = [];
|
|
111
|
+
const declared = [];
|
|
112
|
+
for (const entry of sorted) {
|
|
113
|
+
const named = packageNameOf(entry.specifier);
|
|
114
|
+
const manifest = workspace.manifests.get(entry.directory);
|
|
115
|
+
if (manifest !== undefined && manifest.name === named)
|
|
116
|
+
continue;
|
|
117
|
+
if (entry.declares.includes(named)) {
|
|
118
|
+
declared.push({ dependency: entry, specifier: entry.specifier });
|
|
119
|
+
continue;
|
|
120
|
+
}
|
|
121
|
+
dependencies.push(entry);
|
|
122
|
+
}
|
|
123
|
+
return { dependencies, declared };
|
|
124
|
+
};
|
|
125
|
+
/** The one question about one dependency, pointing at its atom by id. */
|
|
126
|
+
const dependencyReview = (id) => ({
|
|
127
|
+
fit: Decision.classify({
|
|
128
|
+
instructions: [
|
|
129
|
+
`Does \`atoms[${id}].dependency.specifier\` belong in \`atoms[${id}].package.path\`?`,
|
|
130
|
+
`Inspect \`atoms[${id}].package\` and \`atoms[${id}].dependency\`.`,
|
|
131
|
+
`\`atoms[${id}].package.describes_itself_as\` is what this package says it is, and \`atoms[${id}].repository\` describes what the codebase is trying to be. Judge the dependency against BOTH: a Fastify plugin importing fastify is a package doing its job, and the same import in a domain package is the thing the architecture exists to prevent. Do not apply a constraint that belongs to one package to every package.`,
|
|
132
|
+
"Choose `belongs` unless something is clearly wrong. This rule is meant to be quiet.",
|
|
133
|
+
].join("\n"),
|
|
134
|
+
criteria: dependencyVocabulary,
|
|
135
|
+
}),
|
|
136
|
+
});
|
|
137
|
+
// meta-allow: band-the-answer -- the finding is the FACT (an undeclared import),
|
|
138
|
+
// which is true whatever the model says; the judgement only qualifies it, so
|
|
139
|
+
// there is no judged finding to withhold.
|
|
140
|
+
export const dependencyFit = {
|
|
141
|
+
id: RULE_ID,
|
|
142
|
+
severity: "warn",
|
|
143
|
+
description: "A package depends on something its architecture says it should not.",
|
|
144
|
+
judged: true,
|
|
145
|
+
// The finding is a fact -- an undeclared import -- and the rule reads the
|
|
146
|
+
// absence of a judgement itself, so the engine must call it rather than skip it.
|
|
147
|
+
onUnavailable: "report",
|
|
148
|
+
messages: messages({
|
|
149
|
+
undeclared_dependency: "{{path}} imports {{specifier}} in {{count}} file(s) but does not declare it.",
|
|
150
|
+
undeclared_dependency_help: "Add {{package}} to the package's manifest: an undeclared import resolves only because something else hoisted it into the tree. {{qualifier}}",
|
|
151
|
+
}),
|
|
152
|
+
plan: Effect.fn("joggle/dependency-fit")(function* (workspace, scope, context) {
|
|
153
|
+
const report = reporter(dependencyFit, locator(workspace));
|
|
154
|
+
const { dependencies: all, declared } = dependenciesIn(workspace);
|
|
155
|
+
// A scoped run asks about the CHANGE, and the change to a dependency is an
|
|
156
|
+
// IMPORT: the candidate is in scope when one of the files that imports it
|
|
157
|
+
// moved. Judging every undeclared import in the repository on every push is
|
|
158
|
+
// the full cost with none of the scoping.
|
|
159
|
+
const dependencies = scope.changed === undefined
|
|
160
|
+
? all
|
|
161
|
+
: all.filter((dependency) => dependency.examples.some((file) => inGraphScope(scope, file)));
|
|
162
|
+
if (dependencies.length === 0 && declared.length === 0) {
|
|
163
|
+
return {
|
|
164
|
+
plans: [],
|
|
165
|
+
read: () => outcome([], [
|
|
166
|
+
"no external dependency needed judging: everything imported is declared by its package or built into node",
|
|
167
|
+
]),
|
|
168
|
+
};
|
|
169
|
+
}
|
|
170
|
+
const budget = policy.dependencyFit.maxDependencies;
|
|
171
|
+
const judged = dependencies.slice(0, budget);
|
|
172
|
+
const label = (dependency) => dependency.path + " -> " + dependency.specifier;
|
|
173
|
+
const answeredItself = declared.map((entry) => ({
|
|
174
|
+
ruleId: RULE_ID,
|
|
175
|
+
subject: label(entry.dependency),
|
|
176
|
+
stage: "declined",
|
|
177
|
+
reason: "the package declares " +
|
|
178
|
+
entry.specifier +
|
|
179
|
+
" in its own manifest, so importing it is what the package is for",
|
|
180
|
+
}));
|
|
181
|
+
// Declared dependencies are drops, not answers: the funnel has to account for
|
|
182
|
+
// every candidate, and 129 of 241 never reached the model. This was computed
|
|
183
|
+
// and then thrown away until plumb's no-unused-vars reported it, which is a
|
|
184
|
+
// per-file rule finding a bug in the cross-file tool's own reporting.
|
|
185
|
+
const overBudget = dependencies.slice(budget).map((dependency) => ({
|
|
186
|
+
ruleId: RULE_ID,
|
|
187
|
+
subject: label(dependency),
|
|
188
|
+
stage: "budget",
|
|
189
|
+
reason: "this run judged " + budget + " dependencies and this one was past the budget",
|
|
190
|
+
}));
|
|
191
|
+
const atoms = yield* Atoms;
|
|
192
|
+
const planned = [];
|
|
193
|
+
for (const dependency of judged) {
|
|
194
|
+
const manifest = workspace.manifests.get(dependency.directory);
|
|
195
|
+
const id = yield* atoms.add({
|
|
196
|
+
repository: context.config.evidence?.repository ?? null,
|
|
197
|
+
package: {
|
|
198
|
+
path: dependency.path,
|
|
199
|
+
// What the package says it IS. Without this the panel is asked whether
|
|
200
|
+
// a package should import a framework while being told nothing about
|
|
201
|
+
// the package -- and answers correctly for the wrong package.
|
|
202
|
+
name: manifest?.name ?? null,
|
|
203
|
+
describes_itself_as: manifest?.summary ?? null,
|
|
204
|
+
imports_this_in: dependency.count,
|
|
205
|
+
examples: dependency.examples,
|
|
206
|
+
},
|
|
207
|
+
dependency: { specifier: dependency.specifier },
|
|
208
|
+
});
|
|
209
|
+
planned.push({
|
|
210
|
+
dependency,
|
|
211
|
+
plan: {
|
|
212
|
+
ruleId: RULE_ID,
|
|
213
|
+
subject: label(dependency),
|
|
214
|
+
concerns: dependency.examples,
|
|
215
|
+
atoms: [id],
|
|
216
|
+
violations: { fit: ["violates"] },
|
|
217
|
+
decisions: dependencyReview(id),
|
|
218
|
+
read: (answers) => answers,
|
|
219
|
+
},
|
|
220
|
+
});
|
|
221
|
+
}
|
|
222
|
+
return {
|
|
223
|
+
plans: planned.map((entry) => entry.plan),
|
|
224
|
+
read: (answers) => {
|
|
225
|
+
const verdicts = verdictsOf(answers);
|
|
226
|
+
const diagnostics = [];
|
|
227
|
+
const drops = [...answeredItself, ...overBudget];
|
|
228
|
+
planned.forEach((entry, index) => {
|
|
229
|
+
const dependency = entry.dependency;
|
|
230
|
+
const answer = verdicts[index];
|
|
231
|
+
if (answer === undefined) {
|
|
232
|
+
drops.push({
|
|
233
|
+
ruleId: RULE_ID,
|
|
234
|
+
subject: label(dependency),
|
|
235
|
+
stage: "unreadable",
|
|
236
|
+
reason: "the response contained nothing for this dependency",
|
|
237
|
+
});
|
|
238
|
+
return;
|
|
239
|
+
}
|
|
240
|
+
const verdict = answer["fit"];
|
|
241
|
+
if (verdict === undefined || !("label" in verdict)) {
|
|
242
|
+
drops.push({
|
|
243
|
+
ruleId: RULE_ID,
|
|
244
|
+
subject: label(dependency),
|
|
245
|
+
stage: "unreadable",
|
|
246
|
+
reason: "the response contained nothing for this dependency",
|
|
247
|
+
});
|
|
248
|
+
return;
|
|
249
|
+
}
|
|
250
|
+
// The model only decides WHICH of two problems this is. That the package
|
|
251
|
+
// imports something it does not declare is a fact, and it is the more
|
|
252
|
+
// common one: `@autotelic/fasdentify` imports `fastify` in 29 files and its
|
|
253
|
+
// manifest has no `fastify` entry. That works on a developer's machine and
|
|
254
|
+
// fails on a clean install, because it is only there by hoisting.
|
|
255
|
+
// A Choice that barely won is not a decision, and a package that imports
|
|
256
|
+
// something it does not declare is a fact regardless of what the model
|
|
257
|
+
// thinks of it -- so the gate decides the QUALIFIER, not the finding.
|
|
258
|
+
const margin = marginOfAnswer(verdict);
|
|
259
|
+
const decisive = margin >= policy.decision.gates.minMargin;
|
|
260
|
+
// The FACT leads and the judgement qualifies it. That the package imports
|
|
261
|
+
// something it does not declare is derived, not decided -- and it is the
|
|
262
|
+
// finding that matters most here, because it works on a developer's machine
|
|
263
|
+
// and fails on a clean install.
|
|
264
|
+
const misplaced = verdict.label === "violates";
|
|
265
|
+
diagnostics.push(report({
|
|
266
|
+
about: { file: dependency.examples[0] ?? dependency.path, start: 0 },
|
|
267
|
+
messageId: "undeclared_dependency",
|
|
268
|
+
data: {
|
|
269
|
+
path: dependency.path,
|
|
270
|
+
specifier: dependency.specifier,
|
|
271
|
+
count: dependency.count,
|
|
272
|
+
package: packageNameOf(dependency.specifier),
|
|
273
|
+
qualifier: misplaced && decisive
|
|
274
|
+
? "It also does not appear to fit what this package is for, so consider removing it instead."
|
|
275
|
+
: "The dependency itself fits what this package does.",
|
|
276
|
+
},
|
|
277
|
+
helpId: "undeclared_dependency_help",
|
|
278
|
+
identity: [
|
|
279
|
+
RULE_ID,
|
|
280
|
+
misplaced ? "misplaced" : "undeclared",
|
|
281
|
+
dependency.path,
|
|
282
|
+
dependency.specifier,
|
|
283
|
+
].join("\u0000"),
|
|
284
|
+
confidence: verdict.confidence ?? 1,
|
|
285
|
+
judged: false,
|
|
286
|
+
}));
|
|
287
|
+
});
|
|
288
|
+
return outcome(diagnostics, budgetNote({
|
|
289
|
+
unitKind: "dependencies",
|
|
290
|
+
judged: budget,
|
|
291
|
+
candidates: dependencies.length,
|
|
292
|
+
sample: dependencies.slice(budget).map(label),
|
|
293
|
+
}), drops);
|
|
294
|
+
},
|
|
295
|
+
};
|
|
296
|
+
})
|
|
297
|
+
};
|