@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,190 @@
|
|
|
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 { queryCallsIn } from "../sql.js";
|
|
9
|
+
import { verdictOf } from "../verdict.js";
|
|
10
|
+
const RULE_ID = "joggle/append-only-honoured";
|
|
11
|
+
// A query-builder call that may rewrite a record.
|
|
12
|
+
//
|
|
13
|
+
// The deterministic half is the call: a table, a method and the unit that makes
|
|
14
|
+
// it. There is deliberately no list of write verbs and no list of record-like
|
|
15
|
+
// table names. `update` on `ledger` and `insert` on `payroll_audit` are the same
|
|
16
|
+
// shape here; whether the first rewrites the past and the second extends it is
|
|
17
|
+
// the question, and the classifier reads the names and the call.
|
|
18
|
+
//
|
|
19
|
+
// This rule is the second law of the strata made checkable: a fact is never
|
|
20
|
+
// re-derived, and a record is never corrected. The repair it proposes is
|
|
21
|
+
// `expand`: add a supersession row, leave the original.
|
|
22
|
+
export const appendOnlyHonoured = {
|
|
23
|
+
id: RULE_ID,
|
|
24
|
+
severity: "warn",
|
|
25
|
+
description: "A query-builder call that rewrites a structure recording the past.",
|
|
26
|
+
judged: true,
|
|
27
|
+
move: "expand",
|
|
28
|
+
onUnavailable: "report",
|
|
29
|
+
messages: messages({
|
|
30
|
+
rewritten: "`{{method}}` on `{{table}}` changes a row `{{caller}}` records the past in.",
|
|
31
|
+
rewritten_help: "A record is a decision frozen at an instant. Changing it makes the past depend on today's rules: add a row that supersedes it, and leave the original alone.{{unverified}}",
|
|
32
|
+
}),
|
|
33
|
+
plan: Effect.fn("joggle/append-only-honoured")(function* (workspace, scope) {
|
|
34
|
+
const report = reporter(appendOnlyHonoured, locator(workspace));
|
|
35
|
+
const candidates = [];
|
|
36
|
+
for (const file of workspace.files) {
|
|
37
|
+
if (scope.changed !== undefined && !inScope(scope, file.path))
|
|
38
|
+
continue;
|
|
39
|
+
for (const call of queryCallsIn(file.text)) {
|
|
40
|
+
const unit = file.units.find((candidate) => call.start >= candidate.start && call.start <= candidate.end);
|
|
41
|
+
if (unit === undefined)
|
|
42
|
+
continue;
|
|
43
|
+
candidates.push({ unit, call });
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
if (candidates.length === 0) {
|
|
47
|
+
return {
|
|
48
|
+
plans: [],
|
|
49
|
+
read: () => outcome([], [
|
|
50
|
+
"no query-builder call on a named table was found",
|
|
51
|
+
]),
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
const judged = candidates.slice(0, policy.strata.maxCandidates);
|
|
55
|
+
const overBudget = candidates
|
|
56
|
+
.slice(policy.strata.maxCandidates)
|
|
57
|
+
.map((candidate) => ({
|
|
58
|
+
ruleId: RULE_ID,
|
|
59
|
+
subject: candidate.call.method + " " + candidate.call.table,
|
|
60
|
+
stage: "budget",
|
|
61
|
+
reason: "past the budget of " + String(policy.strata.maxCandidates) + " calls",
|
|
62
|
+
}));
|
|
63
|
+
const atoms = yield* Atoms;
|
|
64
|
+
const planned = yield* Effect.forEach(judged, (candidate) => Effect.gen(function* () {
|
|
65
|
+
const id = yield* atoms.add({
|
|
66
|
+
call: {
|
|
67
|
+
method: candidate.call.method,
|
|
68
|
+
table: candidate.call.table,
|
|
69
|
+
caller: candidate.unit.name,
|
|
70
|
+
file: candidate.unit.file,
|
|
71
|
+
},
|
|
72
|
+
source: candidate.unit.text.slice(0, policy.evidence.maxSourceChars),
|
|
73
|
+
});
|
|
74
|
+
const plan = {
|
|
75
|
+
ruleId: RULE_ID,
|
|
76
|
+
subject: candidate.call.method + " " + candidate.call.table,
|
|
77
|
+
concerns: [candidate.unit.file],
|
|
78
|
+
atoms: [id],
|
|
79
|
+
violations: { verdict: ["supersede_only"] },
|
|
80
|
+
decisions: {
|
|
81
|
+
verdict: Decision.classify({
|
|
82
|
+
instructions: {
|
|
83
|
+
question: "May this record be rewritten?",
|
|
84
|
+
call: `\`atoms[${id}].call.caller\` calls \`atoms[${id}].call.table\`.\`atoms[${id}].call.method\``,
|
|
85
|
+
compare: [
|
|
86
|
+
`atoms[${id}].call.method`,
|
|
87
|
+
`atoms[${id}].call.table`,
|
|
88
|
+
`atoms[${id}].source`,
|
|
89
|
+
],
|
|
90
|
+
focus: "Read what the call DOES to the structure. A method that adds a row is how a record grows and is honoured; a method that changes or removes an existing row rewrites the past. A status transition on a mutable work item that happens to be named like a record is `mutable`: the name was never a promise.",
|
|
91
|
+
},
|
|
92
|
+
criteria: {
|
|
93
|
+
supersede_only: {
|
|
94
|
+
means: "The structure holds decisions frozen at an instant, and this call changes one that is already recorded.",
|
|
95
|
+
excludes: "Appending a new row, and current state that is allowed to change.",
|
|
96
|
+
},
|
|
97
|
+
mutable: {
|
|
98
|
+
means: "The structure is current state, and changing it in place is the intended operation.",
|
|
99
|
+
excludes: "A recorded decision whose history a reader depends on.",
|
|
100
|
+
},
|
|
101
|
+
not_a_record: {
|
|
102
|
+
means: "The structure is not append-only, or the call only adds a row rather than rewriting one.",
|
|
103
|
+
excludes: "A call that changes or removes a recorded row.",
|
|
104
|
+
},
|
|
105
|
+
},
|
|
106
|
+
}),
|
|
107
|
+
},
|
|
108
|
+
read: (answers) => answers,
|
|
109
|
+
};
|
|
110
|
+
return { candidate, plan };
|
|
111
|
+
}), { concurrency: "unbounded" });
|
|
112
|
+
return {
|
|
113
|
+
plans: planned.map((entry) => entry.plan),
|
|
114
|
+
read: (answers) => {
|
|
115
|
+
const verdicts = verdictsOf(answers);
|
|
116
|
+
const diagnostics = [];
|
|
117
|
+
const drops = [...overBudget];
|
|
118
|
+
planned.forEach((entry, index) => {
|
|
119
|
+
const { candidate } = entry;
|
|
120
|
+
const subject = candidate.call.method + " " + candidate.call.table;
|
|
121
|
+
const verdict = verdictOf(verdicts[index]?.["verdict"], ["supersede_only"]);
|
|
122
|
+
if (verdict === undefined) {
|
|
123
|
+
diagnostics.push(findingFor({
|
|
124
|
+
report,
|
|
125
|
+
entry,
|
|
126
|
+
confidence: undefined,
|
|
127
|
+
unverifiedReason: "no judgement was available",
|
|
128
|
+
}));
|
|
129
|
+
return;
|
|
130
|
+
}
|
|
131
|
+
if (verdict.label !== "supersede_only") {
|
|
132
|
+
drops.push({
|
|
133
|
+
ruleId: RULE_ID,
|
|
134
|
+
subject,
|
|
135
|
+
stage: "declined",
|
|
136
|
+
reason: verdict.label === "mutable"
|
|
137
|
+
? "current state, allowed to change"
|
|
138
|
+
: "not a record, or the call only appends",
|
|
139
|
+
});
|
|
140
|
+
return;
|
|
141
|
+
}
|
|
142
|
+
const quality = qualityOf({
|
|
143
|
+
score: verdict.probability,
|
|
144
|
+
margin: verdict.margin,
|
|
145
|
+
confidence: verdict.confidence,
|
|
146
|
+
});
|
|
147
|
+
if (quality.quality === "drop") {
|
|
148
|
+
drops.push({ ruleId: RULE_ID, subject, stage: "gated", reason: quality.reason });
|
|
149
|
+
return;
|
|
150
|
+
}
|
|
151
|
+
diagnostics.push(findingFor({
|
|
152
|
+
report,
|
|
153
|
+
entry,
|
|
154
|
+
confidence: verdict.confidence,
|
|
155
|
+
unverifiedReason: undefined,
|
|
156
|
+
review: quality.quality === "review",
|
|
157
|
+
}));
|
|
158
|
+
});
|
|
159
|
+
return outcome(diagnostics, budgetNote({
|
|
160
|
+
unitKind: "queries",
|
|
161
|
+
judged: judged.length,
|
|
162
|
+
candidates: candidates.length,
|
|
163
|
+
sample: candidates
|
|
164
|
+
.slice(policy.strata.maxCandidates)
|
|
165
|
+
.map((candidate) => candidate.call.method + " " + candidate.call.table),
|
|
166
|
+
}), drops);
|
|
167
|
+
},
|
|
168
|
+
};
|
|
169
|
+
}),
|
|
170
|
+
};
|
|
171
|
+
const findingFor = ({ report, entry, confidence, unverifiedReason, review = false, }) => report({
|
|
172
|
+
about: { file: entry.candidate.unit.file, start: entry.candidate.call.start },
|
|
173
|
+
messageId: "rewritten",
|
|
174
|
+
data: {
|
|
175
|
+
method: entry.candidate.call.method,
|
|
176
|
+
table: entry.candidate.call.table,
|
|
177
|
+
caller: entry.candidate.unit.name,
|
|
178
|
+
unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
|
|
179
|
+
},
|
|
180
|
+
helpId: "rewritten_help",
|
|
181
|
+
identity: [
|
|
182
|
+
RULE_ID,
|
|
183
|
+
entry.candidate.unit.file,
|
|
184
|
+
entry.candidate.call.table,
|
|
185
|
+
entry.candidate.call.method,
|
|
186
|
+
].join("\u0000"),
|
|
187
|
+
judged: unverifiedReason === undefined,
|
|
188
|
+
confidence,
|
|
189
|
+
severity: review ? "info" : "warn",
|
|
190
|
+
});
|
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
import { Effect } from "effect";
|
|
2
|
+
import { Decision } from "effect/ai";
|
|
3
|
+
import { blocksIn, findBundles, orphanBlocks, TRIPARTITE, unexportedBlocks, } from "../bundles.js";
|
|
4
|
+
import { Atoms } from "../atoms.js";
|
|
5
|
+
import {} from "../plans.js";
|
|
6
|
+
import { verdictsOf } from "../plans.js";
|
|
7
|
+
import { locator, messages, reporter } from "../reporting.js";
|
|
8
|
+
import { verdictOf } from "../verdict.js";
|
|
9
|
+
import { bundleNote, inScope, outcome, qualityOf, } from "../rule.js";
|
|
10
|
+
/** Which labels mean this rule is violated -- the read and the calibration share it. */
|
|
11
|
+
const VIOLATIONS = { verdict: ["violation"] };
|
|
12
|
+
/** Every composition-pattern rule reports through these. */
|
|
13
|
+
const BUNDLE_MESSAGES = messages({
|
|
14
|
+
pattern_problem: "{{subject}}: {{count}} problem(s) with the composition pattern.",
|
|
15
|
+
pattern_problem_help: "{{problems}}{{unverified}}",
|
|
16
|
+
});
|
|
17
|
+
const ruleFor = (spec) => ({
|
|
18
|
+
id: spec.id,
|
|
19
|
+
severity: spec.severity,
|
|
20
|
+
description: spec.description,
|
|
21
|
+
judged: true,
|
|
22
|
+
onUnavailable: "report",
|
|
23
|
+
messages: BUNDLE_MESSAGES,
|
|
24
|
+
plan: Effect.fn(`joggle/${spec.id}`)(function* (workspace, scope) {
|
|
25
|
+
const report = reporter({ id: spec.id, severity: spec.severity, judged: true, messages: BUNDLE_MESSAGES }, locator(workspace));
|
|
26
|
+
const bundles = findBundles(workspace).filter((bundle) => inScope(scope, bundle.dir));
|
|
27
|
+
const candidates = bundles
|
|
28
|
+
.map((bundle) => ({ bundle, problems: spec.problems(bundle) }))
|
|
29
|
+
.filter((candidate) => candidate.problems.length > 0);
|
|
30
|
+
if (candidates.length === 0) {
|
|
31
|
+
return {
|
|
32
|
+
plans: [],
|
|
33
|
+
read: () => outcome([], bundleNote({ bundles: bundles.length, broken: 0 })),
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
const atoms = yield* Atoms;
|
|
37
|
+
const planned = yield* Effect.forEach(candidates, (candidate) => Effect.gen(function* () {
|
|
38
|
+
const { bundle, problems } = candidate;
|
|
39
|
+
const id = yield* atoms.add({
|
|
40
|
+
bundle: bundle.name,
|
|
41
|
+
dir: bundle.dir,
|
|
42
|
+
index: bundle.indexFile?.path ?? null,
|
|
43
|
+
problems,
|
|
44
|
+
});
|
|
45
|
+
const plan = {
|
|
46
|
+
ruleId: spec.id,
|
|
47
|
+
subject: spec.describe(bundle),
|
|
48
|
+
concerns: [bundle.dir],
|
|
49
|
+
atoms: [id],
|
|
50
|
+
violations: VIOLATIONS,
|
|
51
|
+
decisions: {
|
|
52
|
+
verdict: Decision.classify({
|
|
53
|
+
instructions: [
|
|
54
|
+
`\`atoms[${id}].bundle\` is a composition bundle at \`atoms[${id}].dir\`. It breaks the pattern in ${problems.length} way(s): ${problems.join("; ")}.`,
|
|
55
|
+
"Is that departure a defect, or a deliberate variation this repository can live with?",
|
|
56
|
+
"Answer `violation` when the bundle breaks the pattern and should be brought back into line.",
|
|
57
|
+
"Answer `acceptable` when the departure is deliberate and fine.",
|
|
58
|
+
"Answer `different_pattern` when this directory is not following the composition pattern at all.",
|
|
59
|
+
].join("\n"),
|
|
60
|
+
criteria: {
|
|
61
|
+
violation: "A real defect. Bring the bundle back into line.",
|
|
62
|
+
acceptable: "A deliberate variation. Nothing to change.",
|
|
63
|
+
different_pattern: "This is not a composition bundle.",
|
|
64
|
+
},
|
|
65
|
+
}),
|
|
66
|
+
},
|
|
67
|
+
read: (answers) => answers,
|
|
68
|
+
};
|
|
69
|
+
return { candidate, id, plan };
|
|
70
|
+
}), { concurrency: "unbounded" });
|
|
71
|
+
return {
|
|
72
|
+
plans: planned.map((value) => value.plan),
|
|
73
|
+
read: (answers) => {
|
|
74
|
+
const verdicts = verdictsOf(answers);
|
|
75
|
+
const diagnostics = [];
|
|
76
|
+
const drops = [];
|
|
77
|
+
planned.forEach((value, index) => {
|
|
78
|
+
const { bundle, problems } = value.candidate;
|
|
79
|
+
const subject = spec.describe(bundle);
|
|
80
|
+
const answer = verdicts[index];
|
|
81
|
+
const verdict = verdictOf(answer?.["verdict"], VIOLATIONS.verdict);
|
|
82
|
+
if (verdict === undefined) {
|
|
83
|
+
diagnostics.push(findingFor({
|
|
84
|
+
report,
|
|
85
|
+
spec,
|
|
86
|
+
bundle,
|
|
87
|
+
problems,
|
|
88
|
+
confidence: undefined,
|
|
89
|
+
unverifiedReason: "no judgement was available",
|
|
90
|
+
}));
|
|
91
|
+
return;
|
|
92
|
+
}
|
|
93
|
+
if (verdict.label !== "violation") {
|
|
94
|
+
drops.push({
|
|
95
|
+
ruleId: spec.id,
|
|
96
|
+
subject,
|
|
97
|
+
stage: "declined",
|
|
98
|
+
reason: verdict.label === "acceptable"
|
|
99
|
+
? "a deliberate variation"
|
|
100
|
+
: "not following the composition pattern",
|
|
101
|
+
});
|
|
102
|
+
return;
|
|
103
|
+
}
|
|
104
|
+
const quality = qualityOf({
|
|
105
|
+
score: verdict.probability,
|
|
106
|
+
margin: verdict.margin,
|
|
107
|
+
confidence: verdict.confidence,
|
|
108
|
+
});
|
|
109
|
+
if (quality.quality === "drop") {
|
|
110
|
+
drops.push({
|
|
111
|
+
ruleId: spec.id,
|
|
112
|
+
subject,
|
|
113
|
+
stage: "gated",
|
|
114
|
+
reason: quality.reason,
|
|
115
|
+
});
|
|
116
|
+
return;
|
|
117
|
+
}
|
|
118
|
+
const review = quality.quality === "review";
|
|
119
|
+
diagnostics.push(findingFor({
|
|
120
|
+
report,
|
|
121
|
+
spec,
|
|
122
|
+
bundle,
|
|
123
|
+
problems,
|
|
124
|
+
confidence: verdict.confidence,
|
|
125
|
+
unverifiedReason: undefined,
|
|
126
|
+
review,
|
|
127
|
+
}));
|
|
128
|
+
});
|
|
129
|
+
return outcome(diagnostics, bundleNote({ bundles: bundles.length, broken: diagnostics.length }), drops);
|
|
130
|
+
},
|
|
131
|
+
};
|
|
132
|
+
}),
|
|
133
|
+
});
|
|
134
|
+
const findingFor = ({ report, spec, bundle, problems, confidence, unverifiedReason, review = false, }) => report({
|
|
135
|
+
about: bundle.indexFile ?? { file: bundle.dir, start: 0 },
|
|
136
|
+
messageId: "pattern_problem",
|
|
137
|
+
data: {
|
|
138
|
+
subject: spec.describe(bundle),
|
|
139
|
+
count: problems.length,
|
|
140
|
+
problems: problems.join("; "),
|
|
141
|
+
unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
|
|
142
|
+
},
|
|
143
|
+
helpId: "pattern_problem_help",
|
|
144
|
+
identity: [spec.id, bundle.dir].join("\u0000"),
|
|
145
|
+
judged: unverifiedReason === undefined,
|
|
146
|
+
confidence,
|
|
147
|
+
severity: review ? "info" : spec.severity,
|
|
148
|
+
});
|
|
149
|
+
const blockFiles = (bundle) => bundle.blocks.map((file) => file.path);
|
|
150
|
+
/** 1. The index must export the blocks under one name, by dot notation. */
|
|
151
|
+
export const dotNotationExport = ruleFor({
|
|
152
|
+
id: "joggle/bundle-dot-notation",
|
|
153
|
+
severity: "warn",
|
|
154
|
+
description: "A composition bundle whose index does not export its blocks by dot notation.",
|
|
155
|
+
describe: (bundle) => `${bundle.name} (${bundle.dir})`,
|
|
156
|
+
problems: (bundle) => {
|
|
157
|
+
if (bundle.indexFile === undefined) {
|
|
158
|
+
return [`no index file, so there is no \`${bundle.name}.Block\` to import`];
|
|
159
|
+
}
|
|
160
|
+
if (bundle.dotExportKeys.length === 0) {
|
|
161
|
+
return [
|
|
162
|
+
`index exports named symbols instead of one object; the pattern wants \`export const ${bundle.name} = { Provider, ... }\``,
|
|
163
|
+
];
|
|
164
|
+
}
|
|
165
|
+
const missing = unexportedBlocks(bundle);
|
|
166
|
+
const orphans = orphanBlocks(bundle);
|
|
167
|
+
const problems = [];
|
|
168
|
+
if (missing.length > 0)
|
|
169
|
+
problems.push(`index exports ${missing.join(", ")} but no block declares them`);
|
|
170
|
+
if (orphans.length > 0)
|
|
171
|
+
problems.push(`blocks not exported by the index: ${orphans.join(", ")}`);
|
|
172
|
+
return problems;
|
|
173
|
+
},
|
|
174
|
+
});
|
|
175
|
+
/** 2. The provider's context value must be exactly state / actions / meta. */
|
|
176
|
+
export const tripartiteValue = ruleFor({
|
|
177
|
+
id: "joggle/bundle-tripartite-value",
|
|
178
|
+
severity: "warn",
|
|
179
|
+
description: "A composition bundle whose context value is not { state, actions, meta }.",
|
|
180
|
+
describe: (bundle) => `${bundle.name} (${bundle.dir})`,
|
|
181
|
+
problems: (bundle) => {
|
|
182
|
+
if (bundle.providerFile === undefined) {
|
|
183
|
+
return ["no file renders a Provider, so the blocks have no composition root"];
|
|
184
|
+
}
|
|
185
|
+
const keys = bundle.providerValueKeys;
|
|
186
|
+
if (keys === undefined) {
|
|
187
|
+
return [`${bundle.providerFile.path} passes no object with \`state\` and \`actions\` as the context value`];
|
|
188
|
+
}
|
|
189
|
+
const present = TRIPARTITE.filter((key) => keys.includes(key));
|
|
190
|
+
const extra = keys.filter((key) => !TRIPARTITE.includes(key));
|
|
191
|
+
const problems = [];
|
|
192
|
+
if (present.length < TRIPARTITE.length) {
|
|
193
|
+
const missing = TRIPARTITE.filter((key) => !keys.includes(key));
|
|
194
|
+
problems.push(`context value is missing ${missing.join(", ")}`);
|
|
195
|
+
}
|
|
196
|
+
if (extra.length > 0)
|
|
197
|
+
problems.push(`context value carries ${extra.join(", ")}, which belongs inside state, actions or meta`);
|
|
198
|
+
return problems;
|
|
199
|
+
},
|
|
200
|
+
});
|
|
201
|
+
/** 3. One file per block, and no orphans in either direction. */
|
|
202
|
+
export const oneFilePerBlock = ruleFor({
|
|
203
|
+
id: "joggle/bundle-one-file-per-block",
|
|
204
|
+
severity: "warn",
|
|
205
|
+
description: "A composition bundle that does not keep one block per file.",
|
|
206
|
+
describe: (bundle) => `${bundle.name} (${bundle.dir})`,
|
|
207
|
+
problems: (bundle) => {
|
|
208
|
+
const problems = [];
|
|
209
|
+
for (const file of bundle.blocks) {
|
|
210
|
+
const names = blocksIn(file);
|
|
211
|
+
if (names.length > 1) {
|
|
212
|
+
problems.push(`${file.path} declares ${names.length} exported blocks (${names.join(", ")}); the pattern is one per file`);
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
if (bundle.blocks.length === 0)
|
|
216
|
+
problems.push("no block files: a bundle needs at least one");
|
|
217
|
+
if (problems.length === 0 && blockFiles(bundle).length > 0 && bundle.dotExportKeys.length === 0) {
|
|
218
|
+
problems.push("blocks exist but the index exports nothing");
|
|
219
|
+
}
|
|
220
|
+
return problems;
|
|
221
|
+
},
|
|
222
|
+
});
|
|
223
|
+
/** 4. The bundle's hook must read the context and refuse to work outside it. */
|
|
224
|
+
export const contextHook = ruleFor({
|
|
225
|
+
id: "joggle/bundle-context-hook",
|
|
226
|
+
severity: "warn",
|
|
227
|
+
description: "A composition bundle with no hook, or a hook that does not read the context.",
|
|
228
|
+
describe: (bundle) => `${bundle.name} (${bundle.dir})`,
|
|
229
|
+
problems: (bundle) => {
|
|
230
|
+
if (bundle.hookNames.length === 0) {
|
|
231
|
+
return [`no \`use${bundle.name}\` hook, so blocks cannot read the context without importing it directly`];
|
|
232
|
+
}
|
|
233
|
+
const readsContext = bundle.hookFiles.some((file) => file.facts.callSites.some((site) => site.name === "useContext" || site.name.endsWith(".useContext")));
|
|
234
|
+
if (!readsContext) {
|
|
235
|
+
return [`${bundle.hookNames.join(", ")} does not call \`useContext\`, so it is not the bundle's context hook`];
|
|
236
|
+
}
|
|
237
|
+
return [];
|
|
238
|
+
},
|
|
239
|
+
});
|
|
240
|
+
export const bundleRules = [
|
|
241
|
+
dotNotationExport,
|
|
242
|
+
tripartiteValue,
|
|
243
|
+
oneFilePerBlock,
|
|
244
|
+
contextHook,
|
|
245
|
+
];
|
|
@@ -0,0 +1,209 @@
|
|
|
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
|
+
const RULE_ID = "joggle/call-pattern";
|
|
10
|
+
/** Which labels mean this rule is violated -- the read and the calibration share it. */
|
|
11
|
+
const VIOLATIONS = { verdict: ["same_orchestration"] };
|
|
12
|
+
// Two declarations that make the same calls in the same order.
|
|
13
|
+
//
|
|
14
|
+
// The one thing a body-shape comparison cannot see. `duplicate-implementation`
|
|
15
|
+
// hashes what a declaration LOOKS like, and a re-implementation can look nothing
|
|
16
|
+
// like its original while doing exactly the same things in exactly the same
|
|
17
|
+
// order -- validate, then save, then notify.
|
|
18
|
+
//
|
|
19
|
+
// What is deterministic is the grouping. `unit.callSignature` is the resolved
|
|
20
|
+
// call list, so "the same calls" is identity rather than spelling, and two
|
|
21
|
+
// declarations that share a signature are a candidate. Whether that shared
|
|
22
|
+
// sequence is ONE ORCHESTRATION written twice, or two operations that happen to
|
|
23
|
+
// compose the same helpers, used to be decided by the signature alone.
|
|
24
|
+
export const callPattern = {
|
|
25
|
+
id: RULE_ID,
|
|
26
|
+
severity: "info",
|
|
27
|
+
description: "Declarations that make the same calls in the same order with different bodies.",
|
|
28
|
+
judged: true,
|
|
29
|
+
move: "contract",
|
|
30
|
+
onUnavailable: "report",
|
|
31
|
+
messages: messages({
|
|
32
|
+
same_calls: "{{names}} make the same {{count}} call(s) in the same order, written {{ways}} different ways.",
|
|
33
|
+
same_calls_help: "One of these is the original and the rest re-implement it: {{calls}}. Compare them and keep one, or make the shared part a function the others call.{{unverified}}",
|
|
34
|
+
}),
|
|
35
|
+
plan: Effect.fn("joggle/call-pattern")(function* (workspace, scope) {
|
|
36
|
+
const report = reporter(callPattern, locator(workspace));
|
|
37
|
+
const { minCalls, maxFindings } = policy.callPattern;
|
|
38
|
+
const eligible = workspace.units.filter((unit) => unit.calls.length >= minCalls &&
|
|
39
|
+
unit.kind === "function" &&
|
|
40
|
+
// A framework export cannot be merged however alike two of them are: the
|
|
41
|
+
// framework calls each one by file.
|
|
42
|
+
!policy.frameworkExports.some((name) => name === unit.name));
|
|
43
|
+
if (eligible.length === 0) {
|
|
44
|
+
return {
|
|
45
|
+
plans: [],
|
|
46
|
+
read: () => outcome([], [
|
|
47
|
+
"no function makes " +
|
|
48
|
+
minCalls +
|
|
49
|
+
" or more resolved calls, so nothing had an orchestration to compare",
|
|
50
|
+
]),
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
const groups = new Map();
|
|
54
|
+
for (const unit of eligible) {
|
|
55
|
+
const existing = groups.get(unit.callSignature);
|
|
56
|
+
if (existing === undefined)
|
|
57
|
+
groups.set(unit.callSignature, [unit]);
|
|
58
|
+
else
|
|
59
|
+
existing.push(unit);
|
|
60
|
+
}
|
|
61
|
+
const candidates = [...groups.entries()]
|
|
62
|
+
.filter(([, units]) => units.length > 1)
|
|
63
|
+
.sort((left, right) => right[1].length - left[1].length || left[0].localeCompare(right[0]))
|
|
64
|
+
.filter(([, units]) => units.some((unit) => scope.changed === undefined || scope.changed.has(unit.file)))
|
|
65
|
+
// Bodies that are ALSO identical are `duplicate-implementation`'s finding,
|
|
66
|
+
// not this one: two declarations with the same shape and the same calls are
|
|
67
|
+
// one declaration written twice.
|
|
68
|
+
.filter(([, units]) => new Set(units.map((unit) => unit.normalizedHash)).size > 1)
|
|
69
|
+
.filter(([, units]) => units[0] !== undefined);
|
|
70
|
+
if (candidates.length === 0) {
|
|
71
|
+
return {
|
|
72
|
+
plans: [],
|
|
73
|
+
read: () => outcome([], [
|
|
74
|
+
eligible.length +
|
|
75
|
+
" function(s) with " +
|
|
76
|
+
minCalls +
|
|
77
|
+
" or more resolved calls; no two share a call sequence without also sharing a body",
|
|
78
|
+
]),
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
const judged = candidates.slice(0, maxFindings);
|
|
82
|
+
const overBudget = candidates.slice(maxFindings).map(([, units]) => ({
|
|
83
|
+
ruleId: RULE_ID,
|
|
84
|
+
subject: units.map((unit) => unit.name).join(", "),
|
|
85
|
+
stage: "budget",
|
|
86
|
+
reason: "past the budget of " + String(maxFindings) + " groups",
|
|
87
|
+
}));
|
|
88
|
+
const atoms = yield* Atoms;
|
|
89
|
+
const planned = yield* Effect.forEach(judged, ([, units]) => Effect.gen(function* () {
|
|
90
|
+
const first = units[0];
|
|
91
|
+
if (first === undefined)
|
|
92
|
+
return undefined;
|
|
93
|
+
const calls = first.calls.map(stripFile);
|
|
94
|
+
// The state is the shared call sequence and a bounded sample of the
|
|
95
|
+
// members, not every member's source.
|
|
96
|
+
const members = units.slice(0, 5).map((unit) => ({
|
|
97
|
+
name: unit.name,
|
|
98
|
+
file: unit.file,
|
|
99
|
+
line: unit.location.line,
|
|
100
|
+
source: unit.text.slice(0, 180),
|
|
101
|
+
}));
|
|
102
|
+
const id = yield* atoms.add({ calls, count: units.length, members });
|
|
103
|
+
const plan = {
|
|
104
|
+
ruleId: RULE_ID,
|
|
105
|
+
subject: units.map((unit) => unit.name).join(", ") + " (" + calls.length + " calls)",
|
|
106
|
+
concerns: [...new Set(units.map((unit) => unit.file))],
|
|
107
|
+
atoms: [id],
|
|
108
|
+
violations: VIOLATIONS,
|
|
109
|
+
decisions: {
|
|
110
|
+
verdict: Decision.classify({
|
|
111
|
+
instructions: [
|
|
112
|
+
`\`atoms[${id}].members\` are ${units.length} declarations that make the same ${calls.length} calls in the same order: ${calls.join(" -> ")}.`,
|
|
113
|
+
"Are they ONE orchestration written more than once -- the same work on the same inputs, so one can call another -- or do they reuse the same sequence for different purposes?",
|
|
114
|
+
"Answer `same_orchestration` when they do the same work on the same inputs and one is the original the others re-implement.",
|
|
115
|
+
"Answer `different_inputs` when they run the same helpers over different data, so they are two operations.",
|
|
116
|
+
"Answer `different_work` when one does something the others do not, beyond the shared calls.",
|
|
117
|
+
"Answer `coincidental` when they are unrelated and only the helper sequence lines up.",
|
|
118
|
+
].join("\n"),
|
|
119
|
+
criteria: {
|
|
120
|
+
same_orchestration: "The same work on the same inputs, in the same order. One can call another.",
|
|
121
|
+
different_inputs: "Same helpers, different data. Two operations, not one.",
|
|
122
|
+
different_work: "They do not do the same thing.",
|
|
123
|
+
coincidental: "Unrelated declarations whose helper sequence happens to line up.",
|
|
124
|
+
},
|
|
125
|
+
}),
|
|
126
|
+
},
|
|
127
|
+
read: (answers) => answers,
|
|
128
|
+
};
|
|
129
|
+
return { units, first, calls, id, plan };
|
|
130
|
+
}), { concurrency: "unbounded" });
|
|
131
|
+
const present = planned.filter((value) => value !== undefined);
|
|
132
|
+
return {
|
|
133
|
+
plans: present.map((value) => value.plan),
|
|
134
|
+
read: (answers) => {
|
|
135
|
+
const verdicts = verdictsOf(answers);
|
|
136
|
+
const diagnostics = [];
|
|
137
|
+
const drops = [...overBudget];
|
|
138
|
+
present.forEach((value, index) => {
|
|
139
|
+
const { units } = value;
|
|
140
|
+
const subject = units.map((unit) => unit.name).join(", ");
|
|
141
|
+
const answer = verdicts[index];
|
|
142
|
+
const verdict = verdictOf(answer?.["verdict"], VIOLATIONS.verdict);
|
|
143
|
+
if (verdict === undefined) {
|
|
144
|
+
diagnostics.push(findingFor(report, value, undefined, "no judgement was available"));
|
|
145
|
+
return;
|
|
146
|
+
}
|
|
147
|
+
if (verdict.label !== "same_orchestration") {
|
|
148
|
+
drops.push({
|
|
149
|
+
ruleId: RULE_ID,
|
|
150
|
+
subject,
|
|
151
|
+
stage: "declined",
|
|
152
|
+
reason: "the model read them as " + (verdict.label ?? "unreadable").replace(/_/g, " "),
|
|
153
|
+
});
|
|
154
|
+
return;
|
|
155
|
+
}
|
|
156
|
+
const quality = qualityOf({
|
|
157
|
+
score: verdict.probability,
|
|
158
|
+
margin: verdict.margin,
|
|
159
|
+
confidence: verdict.confidence,
|
|
160
|
+
});
|
|
161
|
+
if (quality.quality === "drop") {
|
|
162
|
+
drops.push({
|
|
163
|
+
ruleId: RULE_ID,
|
|
164
|
+
subject,
|
|
165
|
+
stage: "gated",
|
|
166
|
+
reason: quality.reason,
|
|
167
|
+
});
|
|
168
|
+
return;
|
|
169
|
+
}
|
|
170
|
+
diagnostics.push(findingFor(report, value, verdict.confidence, undefined));
|
|
171
|
+
});
|
|
172
|
+
return outcome(diagnostics, budgetNote({
|
|
173
|
+
unitKind: "groups",
|
|
174
|
+
judged: maxFindings,
|
|
175
|
+
candidates: candidates.length,
|
|
176
|
+
sample: candidates.slice(maxFindings).map(([, units]) => units.map((unit) => unit.name).join(", ")),
|
|
177
|
+
}), drops);
|
|
178
|
+
},
|
|
179
|
+
};
|
|
180
|
+
}),
|
|
181
|
+
};
|
|
182
|
+
const findingFor = (report, value, confidence, unverifiedReason) => {
|
|
183
|
+
const { units, first, calls } = value;
|
|
184
|
+
return report({
|
|
185
|
+
about: first,
|
|
186
|
+
messageId: "same_calls",
|
|
187
|
+
data: {
|
|
188
|
+
names: units.map((unit) => unit.name).join(", "),
|
|
189
|
+
count: calls.length,
|
|
190
|
+
ways: units.length,
|
|
191
|
+
calls: calls.join(" -> "),
|
|
192
|
+
unverified: unverifiedReason === undefined ? "" : " Not verified: " + unverifiedReason + ".",
|
|
193
|
+
},
|
|
194
|
+
helpId: "same_calls_help",
|
|
195
|
+
identity: [RULE_ID, first.callSignature].join("\u0000"),
|
|
196
|
+
judged: unverifiedReason === undefined,
|
|
197
|
+
confidence,
|
|
198
|
+
});
|
|
199
|
+
};
|
|
200
|
+
/** `path/to/file.ts#name` reads better as `file:name` in a sentence. */
|
|
201
|
+
export function stripFile(resolved) {
|
|
202
|
+
const cut = resolved.lastIndexOf("#");
|
|
203
|
+
if (cut === -1)
|
|
204
|
+
return resolved;
|
|
205
|
+
const path = resolved.slice(0, cut);
|
|
206
|
+
const name = resolved.slice(cut + 1);
|
|
207
|
+
const slash = path.lastIndexOf("/");
|
|
208
|
+
return (slash === -1 ? path : path.slice(slash + 1)) + ":" + name;
|
|
209
|
+
}
|