@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,225 @@
|
|
|
1
|
+
import { Effect } from "effect";
|
|
2
|
+
import { Decision } from "effect/ai";
|
|
3
|
+
import { Atoms } from "../atoms.js";
|
|
4
|
+
import { policy } from "../policy.js";
|
|
5
|
+
import { verdictsOf } from "../plans.js";
|
|
6
|
+
import { locator, messages, reporter } from "../reporting.js";
|
|
7
|
+
import { budgetNote, inScope, outcome, qualityOf, } from "../rule.js";
|
|
8
|
+
import { verdictOf } from "../verdict.js";
|
|
9
|
+
import { unitFields } from "../workspace.js";
|
|
10
|
+
const RULE_ID = "joggle/deviation-has-a-shape";
|
|
11
|
+
/** Whether a field's annotation admits an absent value. */
|
|
12
|
+
const admitsAbsence = (annotation) => annotation.includes("null") || annotation.includes("undefined");
|
|
13
|
+
/** Whether a declared field is optional (`name?:`), which is absence by another spelling. */
|
|
14
|
+
const optionalIn = (unit, field) => unit.text.includes(field + "?:");
|
|
15
|
+
/**
|
|
16
|
+
* The shape a deviation leaves behind: a boolean that gates nullable siblings,
|
|
17
|
+
* or a cluster of fields that can each be absent.
|
|
18
|
+
*
|
|
19
|
+
* Those are structural facts, not names. Which of them is a deliberate override
|
|
20
|
+
* and which is a state of the world is the question; the field names go into the
|
|
21
|
+
* panel and the classifier reads them, rather than a suffix list deciding that
|
|
22
|
+
* `_override` means deviation and `ended_at` does not.
|
|
23
|
+
*/
|
|
24
|
+
export const deviationHasAConcept = {
|
|
25
|
+
id: RULE_ID,
|
|
26
|
+
severity: "warn",
|
|
27
|
+
description: "A type that encodes a deviation as flags or a cluster of absent fields.",
|
|
28
|
+
judged: true,
|
|
29
|
+
onUnavailable: "report",
|
|
30
|
+
messages: messages({
|
|
31
|
+
conceptless: "`{{name}}` encodes a deviation as a flag or a cluster of absent fields.",
|
|
32
|
+
conceptless_help: "A deviation is a choice that contradicts a rule on purpose, so it needs an authority, an instant, a reason and a link to what it contradicted. A boolean gating nullable siblings, or a set of fields that are only sometimes present, is that concept deciding not to be one.{{unverified}}",
|
|
33
|
+
}),
|
|
34
|
+
plan: Effect.fn("joggle/deviation-has-a-shape")(function* (workspace, scope) {
|
|
35
|
+
const report = reporter(deviationHasAConcept, locator(workspace));
|
|
36
|
+
const candidates = [];
|
|
37
|
+
for (const file of workspace.files) {
|
|
38
|
+
if (scope.changed !== undefined && !inScope(scope, file.path))
|
|
39
|
+
continue;
|
|
40
|
+
for (const unit of file.units) {
|
|
41
|
+
if (unit.kind === "function")
|
|
42
|
+
continue;
|
|
43
|
+
const flags = unitFields(unit).filter((field) => unit.fieldTypes.get(field)?.trim() === "boolean");
|
|
44
|
+
const absent = unitFields(unit).filter((field) => {
|
|
45
|
+
const annotation = unit.fieldTypes.get(field) ?? "";
|
|
46
|
+
return admitsAbsence(annotation) || optionalIn(unit, field);
|
|
47
|
+
});
|
|
48
|
+
const deviates = (flags.length > 0 && absent.length > 0) || absent.length >= 2;
|
|
49
|
+
if (!deviates)
|
|
50
|
+
continue;
|
|
51
|
+
candidates.push({
|
|
52
|
+
unit,
|
|
53
|
+
flags: flags.slice(0, policy.evidence.maxMembers),
|
|
54
|
+
absent: absent.slice(0, policy.evidence.maxMembers),
|
|
55
|
+
});
|
|
56
|
+
}
|
|
57
|
+
// A `Schema.Struct` declaration is one object literal in the facts. Its
|
|
58
|
+
// boolean fields and nullable keys are the same shape as a type's.
|
|
59
|
+
for (const object of file.facts.objects) {
|
|
60
|
+
if (!object.declared)
|
|
61
|
+
continue;
|
|
62
|
+
const flags = object.keys.filter((key) => object.schemas[key]?.includes("Boolean") === true);
|
|
63
|
+
const absent = object.nullable;
|
|
64
|
+
const deviates = (flags.length > 0 && absent.length > 0) || absent.length >= 2;
|
|
65
|
+
if (!deviates)
|
|
66
|
+
continue;
|
|
67
|
+
const unit = file.units.find((candidate) => object.start >= candidate.start && object.start <= candidate.end);
|
|
68
|
+
if (unit === undefined || unit.kind === "function")
|
|
69
|
+
continue;
|
|
70
|
+
if (candidates.some((candidate) => candidate.unit.file === unit.file && candidate.unit.name === unit.name)) {
|
|
71
|
+
continue;
|
|
72
|
+
}
|
|
73
|
+
candidates.push({
|
|
74
|
+
unit,
|
|
75
|
+
flags: flags.slice(0, policy.evidence.maxMembers),
|
|
76
|
+
absent: absent.slice(0, policy.evidence.maxMembers),
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
if (candidates.length === 0) {
|
|
81
|
+
return {
|
|
82
|
+
plans: [],
|
|
83
|
+
read: () => outcome([], [
|
|
84
|
+
"no type carries a boolean beside absent fields, and no type has a cluster of absent fields",
|
|
85
|
+
]),
|
|
86
|
+
};
|
|
87
|
+
}
|
|
88
|
+
const judged = candidates.slice(0, policy.strata.maxCandidates);
|
|
89
|
+
const overBudget = candidates
|
|
90
|
+
.slice(policy.strata.maxCandidates)
|
|
91
|
+
.map((candidate) => ({
|
|
92
|
+
ruleId: RULE_ID,
|
|
93
|
+
subject: candidate.unit.name,
|
|
94
|
+
stage: "budget",
|
|
95
|
+
reason: "past the budget of " + String(policy.strata.maxCandidates) + " shapes",
|
|
96
|
+
}));
|
|
97
|
+
const atoms = yield* Atoms;
|
|
98
|
+
const planned = yield* Effect.forEach(judged, (candidate) => Effect.gen(function* () {
|
|
99
|
+
const id = yield* atoms.add({
|
|
100
|
+
declaration: {
|
|
101
|
+
name: candidate.unit.name,
|
|
102
|
+
kind: candidate.unit.kind,
|
|
103
|
+
file: candidate.unit.file,
|
|
104
|
+
flags: [...candidate.flags],
|
|
105
|
+
absent: [...candidate.absent],
|
|
106
|
+
fields: unitFields(candidate.unit)
|
|
107
|
+
.slice(0, policy.evidence.maxMembers)
|
|
108
|
+
.map((field) => ({
|
|
109
|
+
name: field,
|
|
110
|
+
type: candidate.unit.fieldTypes.get(field) ?? "",
|
|
111
|
+
})),
|
|
112
|
+
},
|
|
113
|
+
source: candidate.unit.text.slice(0, policy.evidence.maxSourceChars),
|
|
114
|
+
});
|
|
115
|
+
const plan = {
|
|
116
|
+
ruleId: RULE_ID,
|
|
117
|
+
subject: candidate.unit.name,
|
|
118
|
+
concerns: [candidate.unit.file],
|
|
119
|
+
atoms: [id],
|
|
120
|
+
violations: { verdict: ["deviation"] },
|
|
121
|
+
decisions: {
|
|
122
|
+
verdict: Decision.classify({
|
|
123
|
+
instructions: {
|
|
124
|
+
question: "Is this a decision that contradicts a rule, or a state of the world?",
|
|
125
|
+
declaration: `\`atoms[${id}].declaration.flags\` gate \`atoms[${id}].shape.absent\` on \`atoms[${id}].shape.fields\`.`,
|
|
126
|
+
compare: [
|
|
127
|
+
`atoms[${id}].declaration`,
|
|
128
|
+
`atoms[${id}].source`,
|
|
129
|
+
],
|
|
130
|
+
focus: "`deviation` means an override, approval, dispute or exception that intentionally contradicts a rule. `state` means the fields describe the world -- an end date that may not have happened, an optional note. `neither` means this is not a classification at all. Where plumb reports the boolean shape, this reports whether the concept behind it is missing.",
|
|
131
|
+
},
|
|
132
|
+
criteria: {
|
|
133
|
+
deviation: {
|
|
134
|
+
means: "A choice that contradicts a rule on purpose, currently encoded as flags or a cluster of sometimes-present fields.",
|
|
135
|
+
excludes: "Ordinary optionality that describes the world.",
|
|
136
|
+
},
|
|
137
|
+
state: {
|
|
138
|
+
means: "The absent fields and flags describe states of the world, each with one meaning.",
|
|
139
|
+
excludes: "An override that needs an authority and a reason.",
|
|
140
|
+
},
|
|
141
|
+
neither: {
|
|
142
|
+
means: "The shape is not a deviation and not a state classification.",
|
|
143
|
+
excludes: "An override cluster.",
|
|
144
|
+
},
|
|
145
|
+
},
|
|
146
|
+
}),
|
|
147
|
+
},
|
|
148
|
+
read: (answers) => answers,
|
|
149
|
+
};
|
|
150
|
+
return { candidate, plan };
|
|
151
|
+
}), { concurrency: "unbounded" });
|
|
152
|
+
return {
|
|
153
|
+
plans: planned.map((entry) => entry.plan),
|
|
154
|
+
read: (answers) => {
|
|
155
|
+
const verdicts = verdictsOf(answers);
|
|
156
|
+
const diagnostics = [];
|
|
157
|
+
const drops = [...overBudget];
|
|
158
|
+
planned.forEach((entry, index) => {
|
|
159
|
+
const { candidate } = entry;
|
|
160
|
+
const verdict = verdictOf(verdicts[index]?.["verdict"], ["deviation"]);
|
|
161
|
+
if (verdict === undefined) {
|
|
162
|
+
diagnostics.push(findingFor({
|
|
163
|
+
report,
|
|
164
|
+
entry,
|
|
165
|
+
confidence: undefined,
|
|
166
|
+
unverifiedReason: "no judgement was available",
|
|
167
|
+
}));
|
|
168
|
+
return;
|
|
169
|
+
}
|
|
170
|
+
if (verdict.label !== "deviation") {
|
|
171
|
+
drops.push({
|
|
172
|
+
ruleId: RULE_ID,
|
|
173
|
+
subject: candidate.unit.name,
|
|
174
|
+
stage: "declined",
|
|
175
|
+
reason: verdict.label === "state" ? "a state of the world" : "neither shape",
|
|
176
|
+
});
|
|
177
|
+
return;
|
|
178
|
+
}
|
|
179
|
+
const quality = qualityOf({
|
|
180
|
+
score: verdict.probability,
|
|
181
|
+
margin: verdict.margin,
|
|
182
|
+
confidence: verdict.confidence,
|
|
183
|
+
});
|
|
184
|
+
if (quality.quality === "drop") {
|
|
185
|
+
drops.push({
|
|
186
|
+
ruleId: RULE_ID,
|
|
187
|
+
subject: candidate.unit.name,
|
|
188
|
+
stage: "gated",
|
|
189
|
+
reason: quality.reason,
|
|
190
|
+
});
|
|
191
|
+
return;
|
|
192
|
+
}
|
|
193
|
+
diagnostics.push(findingFor({
|
|
194
|
+
report,
|
|
195
|
+
entry,
|
|
196
|
+
confidence: verdict.confidence,
|
|
197
|
+
unverifiedReason: undefined,
|
|
198
|
+
review: quality.quality === "review",
|
|
199
|
+
}));
|
|
200
|
+
});
|
|
201
|
+
return outcome(diagnostics, budgetNote({
|
|
202
|
+
unitKind: "deviation shapes",
|
|
203
|
+
judged: judged.length,
|
|
204
|
+
candidates: candidates.length,
|
|
205
|
+
sample: candidates
|
|
206
|
+
.slice(policy.strata.maxCandidates)
|
|
207
|
+
.map((candidate) => candidate.unit.name),
|
|
208
|
+
}), drops);
|
|
209
|
+
},
|
|
210
|
+
};
|
|
211
|
+
}),
|
|
212
|
+
};
|
|
213
|
+
const findingFor = ({ report, entry, confidence, unverifiedReason, review = false, }) => report({
|
|
214
|
+
about: entry.candidate.unit,
|
|
215
|
+
messageId: "conceptless",
|
|
216
|
+
data: {
|
|
217
|
+
name: entry.candidate.unit.name,
|
|
218
|
+
unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
|
|
219
|
+
},
|
|
220
|
+
helpId: "conceptless_help",
|
|
221
|
+
identity: [RULE_ID, entry.candidate.unit.file, entry.candidate.unit.name].join("\u0000"),
|
|
222
|
+
judged: unverifiedReason === undefined,
|
|
223
|
+
confidence,
|
|
224
|
+
severity: review ? "info" : "warn",
|
|
225
|
+
});
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
import { Effect } from "effect";
|
|
2
|
+
import { Decision } from "effect/ai";
|
|
3
|
+
import { Atoms } from "../atoms.js";
|
|
4
|
+
import { policy } from "../policy.js";
|
|
5
|
+
import { verdictsOf } from "../plans.js";
|
|
6
|
+
import { locator, messages, reporter } from "../reporting.js";
|
|
7
|
+
import { verdictOf } from "../verdict.js";
|
|
8
|
+
import { budgetNote, declined, outcome, qualityOf, } from "../rule.js";
|
|
9
|
+
const RULE_ID = "joggle/doc-matches-code";
|
|
10
|
+
/** Which labels mean this rule is violated -- the read and the calibration share it. */
|
|
11
|
+
const VIOLATIONS = { verdict: ["stale_reference", "wrong_contract", "wrong_behavior"] };
|
|
12
|
+
/**
|
|
13
|
+
* A JSDoc that makes a claim the implementation contradicts.
|
|
14
|
+
*
|
|
15
|
+
* Three comments in three merged PRs on one repository were the same defect: a
|
|
16
|
+
* doc block that had drifted from the code it sat on.
|
|
17
|
+
*
|
|
18
|
+
* "comment says 'null for people with no project role' but band is typed as
|
|
19
|
+
* ReportingBand (not nullable)"
|
|
20
|
+
* "This points at a compareYears note that does not exist."
|
|
21
|
+
* "JSDoc says title-cased but there is no capitalization in here"
|
|
22
|
+
*
|
|
23
|
+
* None is a type error and none is a lint error. The type checker reads the type,
|
|
24
|
+
* not the prose, and a linter reads syntax. The doc is the one artefact with no
|
|
25
|
+
* checker at all, which is why it is the one that drifts.
|
|
26
|
+
*
|
|
27
|
+
* The model is the right instrument because the question is about meaning: does
|
|
28
|
+
* the sentence describe what the code does? The prompt is strict on purpose --
|
|
29
|
+
* a concrete contradiction only -- so the rule reports drift rather than style.
|
|
30
|
+
*/
|
|
31
|
+
const docReview = (id) => ({
|
|
32
|
+
verdict: Decision.classify({
|
|
33
|
+
instructions: [
|
|
34
|
+
`Does the JSDoc on \`atoms[${id}].declaration.name\` state a fact that \`atoms[${id}].declaration.source\` contradicts?`,
|
|
35
|
+
"Choose `no_issue` when the doc states no fact the code contradicts. This is the answer for a doc that is short, informal, high-level, or a summary rather than a full description.",
|
|
36
|
+
"Choose a contradiction ONLY when you can point to the source that contradicts the doc:",
|
|
37
|
+
"- `stale_reference`: the doc names a symbol, note, option or parameter that does not exist.",
|
|
38
|
+
"- `wrong_contract`: the doc states a nullability, default, type, casing or format the code contradicts.",
|
|
39
|
+
"- `wrong_behavior`: the doc describes behaviour the code does not have.",
|
|
40
|
+
].join("\n"),
|
|
41
|
+
criteria: {
|
|
42
|
+
no_issue: "The doc states no fact the code contradicts.",
|
|
43
|
+
stale_reference: "The doc names a symbol, note, option or parameter that does not exist.",
|
|
44
|
+
wrong_contract: "The doc states a nullability, default, type, casing or format the code contradicts.",
|
|
45
|
+
wrong_behavior: "The doc describes behaviour the code does not have.",
|
|
46
|
+
},
|
|
47
|
+
}),
|
|
48
|
+
});
|
|
49
|
+
/**
|
|
50
|
+
* The prose of a doc block.
|
|
51
|
+
*
|
|
52
|
+
* `@param`, `@returns` and `@see` are a second contract, and the type checker
|
|
53
|
+
* already reads the real one. Comparing the tags to the code reports the tag's
|
|
54
|
+
* wording rather than the doc's meaning, so the model sees the prose only.
|
|
55
|
+
*/
|
|
56
|
+
const proseOf = (doc) => doc
|
|
57
|
+
.split("\n")
|
|
58
|
+
.filter((line) => !line.trim().startsWith("@"))
|
|
59
|
+
.join("\n")
|
|
60
|
+
.trim();
|
|
61
|
+
/** An exported declaration with a doc block and enough in it to document. */
|
|
62
|
+
const candidatesIn = (workspace, scope) => workspace.units
|
|
63
|
+
.filter((unit) => unit.exported && unit.doc !== undefined && unit.doc.trim().length > 0)
|
|
64
|
+
.filter((unit) => unit.tokens.length >= policy.docMatchesCode.minTokens)
|
|
65
|
+
.filter((unit) => scope.changed === undefined || scope.changed.has(unit.file))
|
|
66
|
+
.sort((left, right) => left.file.localeCompare(right.file) || left.start - right.start);
|
|
67
|
+
export const docMatchesCode = {
|
|
68
|
+
id: RULE_ID,
|
|
69
|
+
severity: "warn",
|
|
70
|
+
description: "A JSDoc that makes a claim the implementation contradicts.",
|
|
71
|
+
judged: true,
|
|
72
|
+
onUnavailable: "propagate",
|
|
73
|
+
messages: messages({
|
|
74
|
+
doc_contradicts: "{{where}} has a doc block that contradicts the code: {{contradiction}}.",
|
|
75
|
+
doc_contradicts_help: "Fix the doc to match the code, or the code to match the doc. The doc is the one artefact no checker reads, so it is the one that drifts.",
|
|
76
|
+
}),
|
|
77
|
+
plan: Effect.fn("joggle/doc-matches-code")(function* (workspace, scope) {
|
|
78
|
+
const report = reporter(docMatchesCode, locator(workspace));
|
|
79
|
+
const candidates = candidatesIn(workspace, scope);
|
|
80
|
+
if (candidates.length === 0) {
|
|
81
|
+
return {
|
|
82
|
+
plans: [],
|
|
83
|
+
read: () => outcome([], [
|
|
84
|
+
"no exported declaration carries a doc block long enough to document a contract",
|
|
85
|
+
]),
|
|
86
|
+
};
|
|
87
|
+
}
|
|
88
|
+
const budget = policy.docMatchesCode.maxDeclarations;
|
|
89
|
+
const judged = candidates.slice(0, budget);
|
|
90
|
+
const label = (unit) => unit.name + " (" + unit.file + ")";
|
|
91
|
+
const atoms = yield* Atoms;
|
|
92
|
+
const planned = [];
|
|
93
|
+
for (const unit of judged) {
|
|
94
|
+
const id = yield* atoms.add({
|
|
95
|
+
declaration: {
|
|
96
|
+
name: unit.name,
|
|
97
|
+
path: unit.file,
|
|
98
|
+
kind: unit.kind,
|
|
99
|
+
doc: proseOf(unit.doc ?? "").slice(0, policy.evidence.maxDocChars * 4),
|
|
100
|
+
source: unit.text.slice(0, policy.evidence.maxSourceChars * 2),
|
|
101
|
+
types: unit.typeRefs,
|
|
102
|
+
},
|
|
103
|
+
});
|
|
104
|
+
planned.push({
|
|
105
|
+
unit,
|
|
106
|
+
plan: {
|
|
107
|
+
ruleId: RULE_ID,
|
|
108
|
+
subject: label(unit),
|
|
109
|
+
concerns: [unit.file],
|
|
110
|
+
atoms: [id],
|
|
111
|
+
violations: VIOLATIONS,
|
|
112
|
+
decisions: docReview(id),
|
|
113
|
+
read: (answers) => answers,
|
|
114
|
+
},
|
|
115
|
+
});
|
|
116
|
+
}
|
|
117
|
+
const overflow = candidates.slice(budget).map((unit) => ({
|
|
118
|
+
ruleId: RULE_ID,
|
|
119
|
+
subject: label(unit),
|
|
120
|
+
stage: "budget",
|
|
121
|
+
reason: "past the budget of " + budget + " documented declarations",
|
|
122
|
+
}));
|
|
123
|
+
return {
|
|
124
|
+
plans: planned.map((entry) => entry.plan),
|
|
125
|
+
read: (answers) => {
|
|
126
|
+
const verdicts = verdictsOf(answers);
|
|
127
|
+
const diagnostics = [];
|
|
128
|
+
const drops = [...overflow];
|
|
129
|
+
planned.forEach((entry, index) => {
|
|
130
|
+
const unit = entry.unit;
|
|
131
|
+
const answer = verdicts[index];
|
|
132
|
+
if (answer === undefined) {
|
|
133
|
+
drops.push({
|
|
134
|
+
ruleId: RULE_ID,
|
|
135
|
+
subject: label(unit),
|
|
136
|
+
stage: "unreadable",
|
|
137
|
+
reason: "the response did not judge this doc block",
|
|
138
|
+
});
|
|
139
|
+
return;
|
|
140
|
+
}
|
|
141
|
+
const verdict = verdictOf(answer["verdict"], VIOLATIONS.verdict);
|
|
142
|
+
if (verdict === undefined) {
|
|
143
|
+
drops.push({
|
|
144
|
+
ruleId: RULE_ID,
|
|
145
|
+
subject: label(unit),
|
|
146
|
+
stage: "unreadable",
|
|
147
|
+
reason: "the response did not contain a usable verdict",
|
|
148
|
+
});
|
|
149
|
+
return;
|
|
150
|
+
}
|
|
151
|
+
if (verdict.label === "no_issue" || declined(verdict.label)) {
|
|
152
|
+
drops.push({
|
|
153
|
+
ruleId: RULE_ID,
|
|
154
|
+
subject: label(unit),
|
|
155
|
+
stage: "declined",
|
|
156
|
+
reason: "the doc matches the code",
|
|
157
|
+
});
|
|
158
|
+
return;
|
|
159
|
+
}
|
|
160
|
+
const quality = qualityOf({ score: verdict.probability, margin: verdict.margin, confidence: verdict.confidence });
|
|
161
|
+
if (quality.quality === "drop") {
|
|
162
|
+
drops.push({
|
|
163
|
+
ruleId: RULE_ID,
|
|
164
|
+
subject: label(unit),
|
|
165
|
+
stage: "gated",
|
|
166
|
+
reason: quality.reason,
|
|
167
|
+
});
|
|
168
|
+
return;
|
|
169
|
+
}
|
|
170
|
+
diagnostics.push(report({
|
|
171
|
+
about: unit,
|
|
172
|
+
messageId: "doc_contradicts",
|
|
173
|
+
data: { where: label(unit), contradiction: (verdict.label ?? "unreadable").replace(/_/g, " ") },
|
|
174
|
+
helpId: "doc_contradicts_help",
|
|
175
|
+
identity: [RULE_ID, unit.file, unit.name].join("\u0000"),
|
|
176
|
+
confidence: verdict.confidence ?? 1,
|
|
177
|
+
score: verdict.probability,
|
|
178
|
+
judged: true,
|
|
179
|
+
severity: quality.quality === "review" ? "info" : "warn",
|
|
180
|
+
}));
|
|
181
|
+
});
|
|
182
|
+
return outcome(diagnostics, budgetNote({
|
|
183
|
+
unitKind: "documented declarations",
|
|
184
|
+
judged: budget,
|
|
185
|
+
candidates: candidates.length,
|
|
186
|
+
sample: candidates.slice(budget).map(label),
|
|
187
|
+
}), drops);
|
|
188
|
+
},
|
|
189
|
+
};
|
|
190
|
+
})
|
|
191
|
+
};
|
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
import { Effect } from "effect";
|
|
2
|
+
import { Decision } from "effect/ai";
|
|
3
|
+
import { Atoms } from "../atoms.js";
|
|
4
|
+
import { policy } from "../policy.js";
|
|
5
|
+
import { verdictsOf } from "../plans.js";
|
|
6
|
+
import { locator, messages, reporter } from "../reporting.js";
|
|
7
|
+
import { verdictOf } from "../verdict.js";
|
|
8
|
+
import { budgetNote, outcome, qualityOf, } from "../rule.js";
|
|
9
|
+
import { stripFile } from "./call-pattern.js";
|
|
10
|
+
const RULE_ID = "joggle/duplicate-call-run";
|
|
11
|
+
/** Which labels mean this rule is violated -- the read and the calibration share it. */
|
|
12
|
+
const VIOLATIONS = { verdict: ["shared_helper"] };
|
|
13
|
+
// A run of calls one declaration shares with another, without sharing the whole
|
|
14
|
+
// sequence.
|
|
15
|
+
//
|
|
16
|
+
// `call-pattern` compares the WHOLE sequence. But when the shared run is the body
|
|
17
|
+
// of a helper that already exists, the longer function has inlined it and should
|
|
18
|
+
// call it instead. That is the case a whole-sequence comparison cannot see, and it
|
|
19
|
+
// is how a shared filter, validation or query chain gets copied into a second
|
|
20
|
+
// call site.
|
|
21
|
+
//
|
|
22
|
+
// What is deterministic is the run. Calls are resolved, so "the same call" is
|
|
23
|
+
// identity, and the run is extended left and right from a shared n-gram so the
|
|
24
|
+
// candidate names the longest one. Whether that run is a helper somebody inlined
|
|
25
|
+
// -- or a common idiom both functions happen to perform -- is the question.
|
|
26
|
+
export const duplicateCallRun = {
|
|
27
|
+
id: RULE_ID,
|
|
28
|
+
severity: "info",
|
|
29
|
+
description: "A run of calls one declaration shares with another, without the whole sequence.",
|
|
30
|
+
judged: true,
|
|
31
|
+
move: "contract",
|
|
32
|
+
onUnavailable: "report",
|
|
33
|
+
messages: messages({
|
|
34
|
+
shared_run: "{{left}} and {{right}} share {{count}} call(s) in the same order, but are not the same function.",
|
|
35
|
+
shared_run_help: "A shared run this long is a helper one of them has inlined: {{steps}}. If it is one thing, make it a function and call it from both.{{unverified}}",
|
|
36
|
+
}),
|
|
37
|
+
plan: Effect.fn("joggle/duplicate-call-run")(function* (workspace, scope) {
|
|
38
|
+
const report = reporter(duplicateCallRun, locator(workspace));
|
|
39
|
+
const { minCalls, maxFindings } = policy.duplicateCallRun;
|
|
40
|
+
const eligible = workspace.units.filter((unit) => unit.kind === "function" &&
|
|
41
|
+
unit.calls.length >= minCalls &&
|
|
42
|
+
!policy.frameworkExports.some((name) => name === unit.name));
|
|
43
|
+
if (eligible.length === 0) {
|
|
44
|
+
return {
|
|
45
|
+
plans: [],
|
|
46
|
+
read: () => outcome([], [
|
|
47
|
+
"no function makes " + minCalls + " or more resolved calls, so nothing had a run to share",
|
|
48
|
+
]),
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
// Every function is indexed by each run of `minCalls` calls it contains, so
|
|
52
|
+
// two functions that share a run meet at that run.
|
|
53
|
+
const grams = new Map();
|
|
54
|
+
for (const unit of eligible) {
|
|
55
|
+
for (let start = 0; start + minCalls <= unit.calls.length; start += 1) {
|
|
56
|
+
const key = unit.calls.slice(start, start + minCalls).join("\u0000");
|
|
57
|
+
const list = grams.get(key) ?? [];
|
|
58
|
+
list.push({ unit, start });
|
|
59
|
+
grams.set(key, list);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
const runs = new Map();
|
|
63
|
+
for (const list of grams.values()) {
|
|
64
|
+
const bounded = list.slice(0, 50);
|
|
65
|
+
for (let one = 0; one < bounded.length; one += 1) {
|
|
66
|
+
for (let two = one + 1; two < bounded.length; two += 1) {
|
|
67
|
+
const a = bounded[one];
|
|
68
|
+
const b = bounded[two];
|
|
69
|
+
if (a === undefined || b === undefined)
|
|
70
|
+
continue;
|
|
71
|
+
if (a.unit.file === b.unit.file)
|
|
72
|
+
continue;
|
|
73
|
+
// The whole sequence matching is `call-pattern`'s finding.
|
|
74
|
+
if (a.unit.callSignature === b.unit.callSignature)
|
|
75
|
+
continue;
|
|
76
|
+
let left = 0;
|
|
77
|
+
while (a.start - left - 1 >= 0 &&
|
|
78
|
+
b.start - left - 1 >= 0 &&
|
|
79
|
+
a.unit.calls[a.start - left - 1] === b.unit.calls[b.start - left - 1]) {
|
|
80
|
+
left += 1;
|
|
81
|
+
}
|
|
82
|
+
let right = minCalls;
|
|
83
|
+
while (a.start + right < a.unit.calls.length &&
|
|
84
|
+
b.start + right < b.unit.calls.length &&
|
|
85
|
+
a.unit.calls[a.start + right] === b.unit.calls[b.start + right]) {
|
|
86
|
+
right += 1;
|
|
87
|
+
}
|
|
88
|
+
const length = left + right;
|
|
89
|
+
if (length < minCalls)
|
|
90
|
+
continue;
|
|
91
|
+
const start = a.start - left;
|
|
92
|
+
const key = [a.unit.file, a.unit.name, b.unit.file, b.unit.name]
|
|
93
|
+
.sort((one_, two_) => one_.localeCompare(two_))
|
|
94
|
+
.join("\u0000");
|
|
95
|
+
const existing = runs.get(key);
|
|
96
|
+
if (existing === undefined || length > existing.length) {
|
|
97
|
+
runs.set(key, { left: a.unit, right: b.unit, length, start, rightStart: b.start - left });
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
const reported = [...runs.values()]
|
|
103
|
+
.filter((run) => scope.changed === undefined ||
|
|
104
|
+
scope.changed.has(run.left.file) ||
|
|
105
|
+
scope.changed.has(run.right.file))
|
|
106
|
+
.sort((one_, two_) => two_.length - one_.length ||
|
|
107
|
+
one_.left.file.localeCompare(two_.left.file) ||
|
|
108
|
+
one_.left.name.localeCompare(two_.left.name));
|
|
109
|
+
if (reported.length === 0) {
|
|
110
|
+
return {
|
|
111
|
+
plans: [],
|
|
112
|
+
read: () => outcome([], [
|
|
113
|
+
eligible.length +
|
|
114
|
+
" function(s) with " +
|
|
115
|
+
minCalls +
|
|
116
|
+
" or more resolved calls; no two share a run without sharing the whole sequence",
|
|
117
|
+
]),
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
const judged = reported.slice(0, maxFindings);
|
|
121
|
+
const overBudget = reported.slice(maxFindings).map((run) => ({
|
|
122
|
+
ruleId: RULE_ID,
|
|
123
|
+
subject: run.left.name + " / " + run.right.name,
|
|
124
|
+
stage: "budget",
|
|
125
|
+
reason: "past the budget of " + String(maxFindings) + " runs",
|
|
126
|
+
}));
|
|
127
|
+
const atoms = yield* Atoms;
|
|
128
|
+
const planned = yield* Effect.forEach(judged, (run) => Effect.gen(function* () {
|
|
129
|
+
const steps = run.left.calls.slice(run.start, run.start + run.length).map(stripFile);
|
|
130
|
+
// The state is the shared run and what each side does immediately around
|
|
131
|
+
// it, which is what separates "a helper somebody inlined" from "a common
|
|
132
|
+
// idiom both perform".
|
|
133
|
+
const before = run.left.calls.slice(0, run.start).map(stripFile);
|
|
134
|
+
const leftAfter = run.left.calls.slice(run.start + run.length).map(stripFile);
|
|
135
|
+
const rightAfter = run.right.calls.slice(run.rightStart + run.length).map(stripFile);
|
|
136
|
+
const id = yield* atoms.add({
|
|
137
|
+
left: { name: run.left.name, file: run.left.file, line: run.left.location.line },
|
|
138
|
+
right: { name: run.right.name, file: run.right.file, line: run.right.location.line },
|
|
139
|
+
steps,
|
|
140
|
+
before,
|
|
141
|
+
leftAfter,
|
|
142
|
+
rightAfter,
|
|
143
|
+
});
|
|
144
|
+
const plan = {
|
|
145
|
+
ruleId: RULE_ID,
|
|
146
|
+
subject: run.left.name + " / " + run.right.name,
|
|
147
|
+
concerns: [run.left.file, run.right.file],
|
|
148
|
+
atoms: [id],
|
|
149
|
+
violations: VIOLATIONS,
|
|
150
|
+
decisions: {
|
|
151
|
+
verdict: Decision.classify({
|
|
152
|
+
instructions: [
|
|
153
|
+
`\`atoms[${id}].left\` (${run.left.name}) and \`atoms[${id}].right\` (${run.right.name}) share ${run.length} calls in the same order: ${steps.join(" -> ")}.`,
|
|
154
|
+
`\`atoms[${id}].before\` runs before the shared run on the left; \`atoms[${id}].leftAfter\` and \`atoms[${id}].rightAfter\` run after it on each side.`,
|
|
155
|
+
"Is that shared run ONE THING that should be a function both call, or a common sequence the two perform for their own reasons?",
|
|
156
|
+
"Answer `shared_helper` when the run is a self-contained step one of them has inlined, so both should call one function for it.",
|
|
157
|
+
"Answer `common_idiom` when the run is a recurring sequence -- logging, auth, a standard query chain -- that both perform as part of their own work.",
|
|
158
|
+
"Answer `coincidental` when the two sequences only line up by chance.",
|
|
159
|
+
].join("\n"),
|
|
160
|
+
criteria: {
|
|
161
|
+
shared_helper: "A self-contained step. Extract it and call it from both.",
|
|
162
|
+
common_idiom: "A recurring sequence each performs for its own reasons. Not a helper.",
|
|
163
|
+
coincidental: "The calls line up by chance.",
|
|
164
|
+
},
|
|
165
|
+
}),
|
|
166
|
+
},
|
|
167
|
+
read: (answers) => answers,
|
|
168
|
+
};
|
|
169
|
+
return { run, steps, id, plan };
|
|
170
|
+
}), { concurrency: "unbounded" });
|
|
171
|
+
return {
|
|
172
|
+
plans: planned.map((value) => value.plan),
|
|
173
|
+
read: (answers) => {
|
|
174
|
+
const verdicts = verdictsOf(answers);
|
|
175
|
+
const diagnostics = [];
|
|
176
|
+
const drops = [...overBudget];
|
|
177
|
+
planned.forEach((value, index) => {
|
|
178
|
+
const { run } = value;
|
|
179
|
+
const subject = run.left.name + " / " + run.right.name;
|
|
180
|
+
const answer = verdicts[index];
|
|
181
|
+
const verdict = verdictOf(answer?.["verdict"], VIOLATIONS.verdict);
|
|
182
|
+
if (verdict === undefined) {
|
|
183
|
+
diagnostics.push(findingFor(report, value, undefined, "no judgement was available"));
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
if (verdict.label !== "shared_helper") {
|
|
187
|
+
drops.push({
|
|
188
|
+
ruleId: RULE_ID,
|
|
189
|
+
subject,
|
|
190
|
+
stage: "declined",
|
|
191
|
+
reason: verdict.label === "common_idiom"
|
|
192
|
+
? "the shared run is a common idiom, not a helper"
|
|
193
|
+
: "the two sequences line up by chance",
|
|
194
|
+
});
|
|
195
|
+
return;
|
|
196
|
+
}
|
|
197
|
+
const quality = qualityOf({
|
|
198
|
+
score: verdict.probability,
|
|
199
|
+
margin: verdict.margin,
|
|
200
|
+
confidence: verdict.confidence,
|
|
201
|
+
});
|
|
202
|
+
if (quality.quality === "drop") {
|
|
203
|
+
drops.push({
|
|
204
|
+
ruleId: RULE_ID,
|
|
205
|
+
subject,
|
|
206
|
+
stage: "gated",
|
|
207
|
+
reason: quality.reason,
|
|
208
|
+
});
|
|
209
|
+
return;
|
|
210
|
+
}
|
|
211
|
+
diagnostics.push(findingFor(report, value, verdict.confidence, undefined));
|
|
212
|
+
});
|
|
213
|
+
return outcome(diagnostics, budgetNote({
|
|
214
|
+
unitKind: "runs",
|
|
215
|
+
judged: maxFindings,
|
|
216
|
+
candidates: reported.length,
|
|
217
|
+
sample: reported.slice(maxFindings).map((run) => run.left.name + "/" + run.right.name),
|
|
218
|
+
}), drops);
|
|
219
|
+
},
|
|
220
|
+
};
|
|
221
|
+
}),
|
|
222
|
+
};
|
|
223
|
+
const findingFor = (report, value, confidence, unverifiedReason) => {
|
|
224
|
+
const { run, steps } = value;
|
|
225
|
+
return report({
|
|
226
|
+
about: run.left,
|
|
227
|
+
messageId: "shared_run",
|
|
228
|
+
data: {
|
|
229
|
+
left: run.left.name,
|
|
230
|
+
right: run.right.name,
|
|
231
|
+
count: run.length,
|
|
232
|
+
steps: steps.join(" -> "),
|
|
233
|
+
unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
|
|
234
|
+
},
|
|
235
|
+
helpId: "shared_run_help",
|
|
236
|
+
identity: [RULE_ID, run.left.file, run.left.name, run.right.file, run.right.name].join("\u0000"),
|
|
237
|
+
judged: unverifiedReason === undefined,
|
|
238
|
+
confidence,
|
|
239
|
+
});
|
|
240
|
+
};
|