@autotelic/joggle 0.0.0-stage → 0.1.2
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,264 @@
|
|
|
1
|
+
import { Effect, Result, Schema } from "effect";
|
|
2
|
+
import { Decision, DecisionModel } from "effect/ai";
|
|
3
|
+
import { containmentPairs, exactGroups, fieldGroups } from "../candidates.js";
|
|
4
|
+
import { policy } from "../policy.js";
|
|
5
|
+
import { locator, messages, reporter } from "../reporting.js";
|
|
6
|
+
import { budgetNote, outcome, qualityOf } from "../rule.js";
|
|
7
|
+
import { stagedInput } from "../stages.js";
|
|
8
|
+
import { verdictOf } from "../verdict.js";
|
|
9
|
+
import {} from "../workspace.js";
|
|
10
|
+
const RULE_ID = "joggle/reversal";
|
|
11
|
+
// One site, one move.
|
|
12
|
+
//
|
|
13
|
+
// The three moves are a SEQUENCE, and they used to be three scanners with three
|
|
14
|
+
// candidate generators: a copy was reported by the duplicate rules, a repeated
|
|
15
|
+
// part by compose-types, an unnamed field set by name-the-primitive. Each was
|
|
16
|
+
// right on its own and the same declaration could appear in all three, with no
|
|
17
|
+
// way to read which move the code actually needs first.
|
|
18
|
+
//
|
|
19
|
+
// This rule walks a site through the stages and stops at the first that answers:
|
|
20
|
+
//
|
|
21
|
+
// 1. contract the declaration is a copy of one that exists. A fact; no model.
|
|
22
|
+
// 2. combine its fields are a named part plus more. A fact: the containment
|
|
23
|
+
// is decidable from the two field sets.
|
|
24
|
+
// 3. expand a group of fields repeats and no declaration names it. Asked,
|
|
25
|
+
// because whether they are one idea is the question.
|
|
26
|
+
//
|
|
27
|
+
// The earlier stage's outcome is in the next stage's state, so a site that
|
|
28
|
+
// stopped at combine and a site that fell through to expand never share a cached
|
|
29
|
+
// answer.
|
|
30
|
+
const ExpandPanel = Schema.Struct({
|
|
31
|
+
fields: Schema.Array(Schema.String),
|
|
32
|
+
occurrences: Schema.Number,
|
|
33
|
+
declarations: Schema.Array(Schema.String),
|
|
34
|
+
fieldTypes: Schema.Array(Schema.Struct({ field: Schema.String, types: Schema.Array(Schema.String) })),
|
|
35
|
+
});
|
|
36
|
+
const expandDefinition = Decision.make({
|
|
37
|
+
input: stagedInput(ExpandPanel),
|
|
38
|
+
decisions: {
|
|
39
|
+
expand: Decision.classify({
|
|
40
|
+
instructions: [
|
|
41
|
+
"`panel.fields` appear together in `panel.occurrences` declarations and no declared type names them.",
|
|
42
|
+
"`panel.fieldTypes` is each field's resolved type across those declarations.",
|
|
43
|
+
"`earlier` is what the earlier stages said: no copy to contract, and no named part to combine.",
|
|
44
|
+
"Is that set of fields ONE THING -- a primitive that deserves a name and should be composed everywhere it appears -- or do those declarations reuse the names for different reasons?",
|
|
45
|
+
"Answer `one_thing` when the fields always travel together as one concept.",
|
|
46
|
+
"Answer `unrelated` when the declarations genuinely use them for different purposes.",
|
|
47
|
+
"Answer `already_named` when a declared type already names exactly this set.",
|
|
48
|
+
].join("\n"),
|
|
49
|
+
criteria: {
|
|
50
|
+
one_thing: "The fields are one concept. Extract a named type and compose it everywhere.",
|
|
51
|
+
unrelated: "Different purposes. No one type would be right.",
|
|
52
|
+
already_named: "A declared type already covers exactly this field set.",
|
|
53
|
+
},
|
|
54
|
+
}),
|
|
55
|
+
},
|
|
56
|
+
});
|
|
57
|
+
/** A declaration's identity for "the same site". */
|
|
58
|
+
const siteKey = (unit) => unit.file + "\u0000" + unit.name + "\u0000" + String(unit.start);
|
|
59
|
+
/** The names of a group, in a stable order, capped for a message. */
|
|
60
|
+
const namesOf = (units) => [...new Set(units.map((unit) => unit.name))].sort((left, right) => left.localeCompare(right));
|
|
61
|
+
export const reversal = {
|
|
62
|
+
id: RULE_ID,
|
|
63
|
+
severity: "info",
|
|
64
|
+
description: "One site, one move: contract a copy, combine a named part, or expand the vocabulary.",
|
|
65
|
+
judged: true,
|
|
66
|
+
move: "contract",
|
|
67
|
+
// Stage 3's question, declared for calibration: a plain rule has no plans,
|
|
68
|
+
// so the instrument reads its violating label from here.
|
|
69
|
+
violations: { expand: ["one_thing"] },
|
|
70
|
+
messages: messages({
|
|
71
|
+
stops_at_contract: "{{names}} are one declaration written {{count}} times: {{at}}.",
|
|
72
|
+
stops_at_contract_help: "This is the contract stage: a primitive already exists. Keep one declaration, import it everywhere, and delete the copies. Nothing else has to change.",
|
|
73
|
+
stops_at_combine: "`{{whole}}` repeats every field of `{{part}}` and adds {{count}}: {{added}}.",
|
|
74
|
+
stops_at_combine_help: "This is the combine stage: the parts exist and the combination was never written. Declare `{{whole}}` as `{{part}} & { {{added}} }` so the shared part stays canonical ({{partAt}}){{tail}}.",
|
|
75
|
+
stops_at_expand: "{{fields}} appear together in {{occurrences}} declarations and have no name.",
|
|
76
|
+
stops_at_expand_help: "This is the expand stage: neither a copy nor a named part. The vocabulary has to grow -- extract these fields as a named type and compose it everywhere they appear ({{first}}){{tail}}.",
|
|
77
|
+
}),
|
|
78
|
+
run: Effect.fn("joggle/reversal")(function* (workspace, scope) {
|
|
79
|
+
const report = reporter(reversal, locator(workspace));
|
|
80
|
+
const diagnostics = [];
|
|
81
|
+
const drops = [];
|
|
82
|
+
const consumed = new Set();
|
|
83
|
+
let unjudged = 0;
|
|
84
|
+
// Stage 1 -- contract. A fact, so this stage never asks and never waits.
|
|
85
|
+
const copies = exactGroups({
|
|
86
|
+
units: workspace.units,
|
|
87
|
+
kinds: ["shape"],
|
|
88
|
+
minTokens: policy.reversal.minTokens,
|
|
89
|
+
distinctFiles: true,
|
|
90
|
+
separateTests: true,
|
|
91
|
+
scope,
|
|
92
|
+
});
|
|
93
|
+
for (const group of copies) {
|
|
94
|
+
const names = namesOf(group.members);
|
|
95
|
+
const first = [...group.members].sort((left, right) => left.file.localeCompare(right.file))[0];
|
|
96
|
+
diagnostics.push(report({
|
|
97
|
+
about: first ?? { file: "", start: 0 },
|
|
98
|
+
messageId: "stops_at_contract",
|
|
99
|
+
data: {
|
|
100
|
+
names: names.slice(0, 4).join(", "),
|
|
101
|
+
count: group.members.length,
|
|
102
|
+
// Where each copy is. A name alone is not a site: two files can hold
|
|
103
|
+
// the same pair of names and a reader needs the paths to act.
|
|
104
|
+
at: group.members
|
|
105
|
+
.filter((unit) => names.slice(0, 4).includes(unit.name))
|
|
106
|
+
.slice(0, 4)
|
|
107
|
+
.map((unit) => unit.name + " at " + unit.file + ":" + String(unit.location.line))
|
|
108
|
+
.join("; "),
|
|
109
|
+
},
|
|
110
|
+
helpId: "stops_at_contract_help",
|
|
111
|
+
identity: [
|
|
112
|
+
RULE_ID,
|
|
113
|
+
"contract",
|
|
114
|
+
...group.members.map((unit) => unit.file + "#" + unit.name).sort((left, right) => left.localeCompare(right)),
|
|
115
|
+
].join("\u0000"),
|
|
116
|
+
judged: false,
|
|
117
|
+
severity: "warn",
|
|
118
|
+
move: "contract",
|
|
119
|
+
stoppedAt: "contract",
|
|
120
|
+
}));
|
|
121
|
+
for (const unit of group.members)
|
|
122
|
+
consumed.add(siteKey(unit));
|
|
123
|
+
}
|
|
124
|
+
// Stage 2 -- combine. The containment is a FACT: the whole's own field set is
|
|
125
|
+
// a proper superset of a named part's. Whether the two are genuinely one
|
|
126
|
+
// composition is the reader's call; the finding names the part and what was
|
|
127
|
+
// added, and the only judgement left in this cascade is stage 3's.
|
|
128
|
+
const combineOutcomes = new Map();
|
|
129
|
+
const contained = containmentPairs({
|
|
130
|
+
units: workspace.units,
|
|
131
|
+
kinds: ["interface", "type"],
|
|
132
|
+
minFields: policy.composeTypes.minFields,
|
|
133
|
+
maxTypes: policy.composeTypes.maxTypes,
|
|
134
|
+
scope,
|
|
135
|
+
}).filter((pair) => !consumed.has(siteKey(pair.whole)));
|
|
136
|
+
const combineBudget = Math.min(contained.length, policy.reversal.maxSites);
|
|
137
|
+
for (const pair of contained.slice(0, combineBudget)) {
|
|
138
|
+
combineOutcomes.set(siteKey(pair.whole), { stage: "combine", outcome: "contained" });
|
|
139
|
+
diagnostics.push(report({
|
|
140
|
+
about: pair.whole,
|
|
141
|
+
messageId: "stops_at_combine",
|
|
142
|
+
data: {
|
|
143
|
+
whole: pair.whole.name,
|
|
144
|
+
part: pair.part.name,
|
|
145
|
+
count: pair.added.length,
|
|
146
|
+
added: pair.added.join(", "),
|
|
147
|
+
partAt: pair.part.file + ":" + String(pair.part.location.line),
|
|
148
|
+
tail: "",
|
|
149
|
+
},
|
|
150
|
+
helpId: "stops_at_combine_help",
|
|
151
|
+
identity: [RULE_ID, "combine", pair.whole.file, pair.whole.name, pair.part.name].join("\u0000"),
|
|
152
|
+
judged: false,
|
|
153
|
+
severity: "info",
|
|
154
|
+
move: "combine",
|
|
155
|
+
stoppedAt: "combine",
|
|
156
|
+
}));
|
|
157
|
+
consumed.add(siteKey(pair.whole));
|
|
158
|
+
}
|
|
159
|
+
// Stage 3 -- expand. Asked, and its state carries what the earlier stages
|
|
160
|
+
// said about the site.
|
|
161
|
+
const groups = fieldGroups({
|
|
162
|
+
units: workspace.units.filter((unit) => unit.kind === "interface" || unit.kind === "type"),
|
|
163
|
+
minFields: policy.nameThePrimitive.minFields,
|
|
164
|
+
minOccurrences: policy.nameThePrimitive.minOccurrences,
|
|
165
|
+
scope,
|
|
166
|
+
}).filter((entry) => entry.units.some((unit) => !consumed.has(siteKey(unit))));
|
|
167
|
+
const expandBudget = Math.min(groups.length, policy.reversal.maxSites);
|
|
168
|
+
for (const entry of groups.slice(0, expandBudget)) {
|
|
169
|
+
const first = entry.units.find((unit) => !consumed.has(siteKey(unit))) ?? entry.units[0];
|
|
170
|
+
if (first === undefined)
|
|
171
|
+
continue;
|
|
172
|
+
const earlier = [
|
|
173
|
+
{ stage: "contract", outcome: "none" },
|
|
174
|
+
combineOutcomes.get(siteKey(first)) ?? { stage: "combine", outcome: "not_applicable" },
|
|
175
|
+
];
|
|
176
|
+
const decided = yield* Effect.result(DecisionModel.decide(expandDefinition, {
|
|
177
|
+
input: {
|
|
178
|
+
stage: "expand",
|
|
179
|
+
earlier,
|
|
180
|
+
panel: {
|
|
181
|
+
fields: entry.fields,
|
|
182
|
+
occurrences: entry.units.length,
|
|
183
|
+
declarations: entry.units.slice(0, 6).map((unit) => unit.name),
|
|
184
|
+
fieldTypes: entry.fields.map((field) => ({
|
|
185
|
+
field,
|
|
186
|
+
types: [
|
|
187
|
+
...new Set(entry.units
|
|
188
|
+
.map((unit) => {
|
|
189
|
+
const member = unit.typeFacts?.members.find((item) => item.name === field);
|
|
190
|
+
return member === undefined ? unit.fieldTypes.get(field) : member.type;
|
|
191
|
+
})
|
|
192
|
+
.filter((type) => type !== undefined)),
|
|
193
|
+
].slice(0, 4),
|
|
194
|
+
})),
|
|
195
|
+
},
|
|
196
|
+
},
|
|
197
|
+
}));
|
|
198
|
+
if (Result.isFailure(decided)) {
|
|
199
|
+
unjudged += 1;
|
|
200
|
+
continue;
|
|
201
|
+
}
|
|
202
|
+
const verdict = verdictOf(decided.success.answers["expand"], ["one_thing"]);
|
|
203
|
+
if (verdict === undefined || verdict.label !== "one_thing") {
|
|
204
|
+
drops.push({
|
|
205
|
+
ruleId: RULE_ID,
|
|
206
|
+
subject: "field group { " + entry.fields.join(", ") + " }",
|
|
207
|
+
stage: "declined",
|
|
208
|
+
reason: verdict === undefined
|
|
209
|
+
? "the answer could not be read"
|
|
210
|
+
: verdict.label === "already_named"
|
|
211
|
+
? "a declared type already names this set"
|
|
212
|
+
: "the declarations use the fields for different purposes",
|
|
213
|
+
});
|
|
214
|
+
continue;
|
|
215
|
+
}
|
|
216
|
+
const quality = qualityOf({
|
|
217
|
+
score: verdict.probability,
|
|
218
|
+
margin: verdict.margin,
|
|
219
|
+
confidence: verdict.confidence,
|
|
220
|
+
});
|
|
221
|
+
if (quality.quality === "drop") {
|
|
222
|
+
drops.push({
|
|
223
|
+
ruleId: RULE_ID,
|
|
224
|
+
subject: "field group { " + entry.fields.join(", ") + " }",
|
|
225
|
+
stage: "gated",
|
|
226
|
+
reason: quality.reason,
|
|
227
|
+
});
|
|
228
|
+
continue;
|
|
229
|
+
}
|
|
230
|
+
diagnostics.push(report({
|
|
231
|
+
about: first,
|
|
232
|
+
messageId: "stops_at_expand",
|
|
233
|
+
data: {
|
|
234
|
+
fields: entry.fields.join(", "),
|
|
235
|
+
occurrences: entry.units.length,
|
|
236
|
+
first: first.file + ":" + String(first.location.line),
|
|
237
|
+
tail: "",
|
|
238
|
+
},
|
|
239
|
+
helpId: "stops_at_expand_help",
|
|
240
|
+
identity: [RULE_ID, "expand", entry.fields.join("\u0000")].join("\u0000"),
|
|
241
|
+
confidence: verdict.confidence,
|
|
242
|
+
severity: quality.quality === "review" ? "info" : "warn",
|
|
243
|
+
move: "expand",
|
|
244
|
+
stoppedAt: "expand",
|
|
245
|
+
}));
|
|
246
|
+
}
|
|
247
|
+
const notes = [
|
|
248
|
+
...budgetNote({
|
|
249
|
+
unitKind: "sites",
|
|
250
|
+
judged: policy.reversal.maxSites,
|
|
251
|
+
candidates: contained.length + groups.length,
|
|
252
|
+
sample: contained
|
|
253
|
+
.slice(combineBudget)
|
|
254
|
+
.map((pair) => pair.whole.name)
|
|
255
|
+
.concat(groups.slice(expandBudget).map((entry) => entry.fields.join(", ")))
|
|
256
|
+
.slice(0, 3),
|
|
257
|
+
}),
|
|
258
|
+
...(unjudged === 0
|
|
259
|
+
? []
|
|
260
|
+
: [unjudged + " staged question(s) could not be read; only the facts were reported"]),
|
|
261
|
+
];
|
|
262
|
+
return outcome(diagnostics, notes, drops);
|
|
263
|
+
}),
|
|
264
|
+
};
|
|
@@ -0,0 +1,252 @@
|
|
|
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, declined, marginOfAnswer, outcome, qualityOf, } from "../rule.js";
|
|
8
|
+
// meta-allow: no-pattern-classifier -- it reads RULE source for `id:` and `judged:` -- a structural scan of rule files,
|
|
9
|
+
// which is what the rule is for. docs/rule-coupling.md.
|
|
10
|
+
const RULE_ID = "joggle/rule-judgment";
|
|
11
|
+
/**
|
|
12
|
+
* A rule that decides in code a question only a judgement can answer.
|
|
13
|
+
*
|
|
14
|
+
* This is the tool applied to itself. joggle's own rule is: code finds the
|
|
15
|
+
* candidate, the model makes the judgement. A rule that computes a structural
|
|
16
|
+
* signal and then asserts a semantic quality from it has moved the judgement back
|
|
17
|
+
* into code, which is the disease this program exists to remove -- a person's
|
|
18
|
+
* guess wearing a number.
|
|
19
|
+
*
|
|
20
|
+
* The candidate is structural: one `defineRule` call. One call is one rule, so a
|
|
21
|
+
* file that defines four rules is four candidates rather than one, and the source
|
|
22
|
+
* sent is that call's span rather than the whole file. The first version sent the
|
|
23
|
+
* file, which meant a file with one bad rule among five got one verdict, and the
|
|
24
|
+
* `judged` flag was a text scan of the whole file rather than of the rule.
|
|
25
|
+
*
|
|
26
|
+
* The judgement is the model's, because "is this a fact or an opinion?" is not
|
|
27
|
+
* checkable by a linter either.
|
|
28
|
+
*
|
|
29
|
+
* `rule.judged` is part of the state on purpose. A rule that already asks the
|
|
30
|
+
* model is not deciding in code, and the model should be told which it is looking
|
|
31
|
+
* at rather than inferring it from an import.
|
|
32
|
+
*/
|
|
33
|
+
const ruleReview = (id) => ({
|
|
34
|
+
decides_in_code: Decision.probability({
|
|
35
|
+
instructions: [
|
|
36
|
+
`Does the rule \`atoms[${id}].rule.id\` in \`atoms[${id}].rule.path\` decide in code a question that needs a judgement?`,
|
|
37
|
+
"`atoms[" + id + "].rule.message` is the literal text the rule emits, and it is the finding. The rule's `description` and `help` are prose written for the report; a quality asserted there is not the finding. Judge the message and the computation behind it.",
|
|
38
|
+
"A rule that states a measurement is NOT deciding in code: it says what it found and the reader decides. \"This file exports nine things over twenty lines\" is a fact, even when the description calls it shallow or the help suggests a fix.",
|
|
39
|
+
"A rule DOES decide in code when either:",
|
|
40
|
+
"- a NUMBER in it decides a verdict rather than bounding a search: a rule that reports a name as unsearchable because it is reached from fewer than N files, or a file as shallow because a ratio is below a threshold;",
|
|
41
|
+
"- its MESSAGE asserts a quality rather than a measurement: \"these are one thing\", \"this is a grab bag\", \"this name is an address\", \"this is not worth keeping\".",
|
|
42
|
+
"A number that only bounds how much work a run does -- a budget, a maximum, a token limit -- is not a judgement.",
|
|
43
|
+
`\`atoms[${id}].rule.judged\` says whether the rule already asks the model. A rule that asks the model is not deciding in code, whatever its candidate filter looks like.`,
|
|
44
|
+
`A rule whose \`atoms[${id}].rule.preset\` is true checks conformance to a pattern the repository DECLARES. That pattern is the contract, so checking it is a fact about the declaration rather than a judgement about the code.`,
|
|
45
|
+
].join("\n"),
|
|
46
|
+
criteria: {
|
|
47
|
+
false: "The rule states a fact, or it already asks the model.",
|
|
48
|
+
true: "The rule decides a judgement in code.",
|
|
49
|
+
},
|
|
50
|
+
}),
|
|
51
|
+
kind: Decision.classify({
|
|
52
|
+
instructions: [
|
|
53
|
+
`If \`atoms[${id}].rule.id\` decides in code, what kind of judgement is it?`,
|
|
54
|
+
"Choose `no_issue` when the rule states a fact, or when it already asks the model.",
|
|
55
|
+
].join("\n"),
|
|
56
|
+
criteria: {
|
|
57
|
+
semantic_verdict: "It computes something structural and then asserts a semantic quality from it.",
|
|
58
|
+
magic_threshold: "A number in the rule encodes a person's opinion rather than a bound on search.",
|
|
59
|
+
name_meaning: "It matches names and then asserts what they mean.",
|
|
60
|
+
no_issue: "It states a fact, or it already asks the model.",
|
|
61
|
+
},
|
|
62
|
+
}),
|
|
63
|
+
});
|
|
64
|
+
/**
|
|
65
|
+
* Whether the rule file ships in a preset.
|
|
66
|
+
*
|
|
67
|
+
* A preset is a module that imports rules and re-exports them, so the edge from a
|
|
68
|
+
* `presets/` file to this one is the declaration that the rule is opt-in.
|
|
69
|
+
*/
|
|
70
|
+
const isPreset = (workspace, path) => workspace.imports.edges.some((edge) => edge.to === path && edge.importer.includes("/presets/"));
|
|
71
|
+
/**
|
|
72
|
+
* The string literals in the rule's `message:` argument.
|
|
73
|
+
*
|
|
74
|
+
* A message is built by concatenation, so the literals are the fixed text and the
|
|
75
|
+
* variables are the measurements. " is called from " and " files" carry no claim;
|
|
76
|
+
* " so searching for it finds everything and nothing" does.
|
|
77
|
+
*/
|
|
78
|
+
const messageLiterals = (source) => {
|
|
79
|
+
const at = source.lastIndexOf("message:");
|
|
80
|
+
if (at < 0)
|
|
81
|
+
return [];
|
|
82
|
+
// Stop at `help:`, or the advice leaks in and the model reads the fix as the
|
|
83
|
+
// finding -- which is exactly the mistake this field exists to prevent.
|
|
84
|
+
const helpAt = source.indexOf("help:", at);
|
|
85
|
+
const rest = source.slice(at, helpAt < 0 ? at + 2000 : helpAt);
|
|
86
|
+
const literals = [];
|
|
87
|
+
// Single-line literals only, so the `+` and the variable names between them do
|
|
88
|
+
// not become part of the text.
|
|
89
|
+
for (const match of rest.matchAll(/"([^"\\\n]*)"/g)) {
|
|
90
|
+
const literal = match[1];
|
|
91
|
+
if (literal !== undefined && literal.trim() !== "")
|
|
92
|
+
literals.push(literal);
|
|
93
|
+
}
|
|
94
|
+
return literals;
|
|
95
|
+
};
|
|
96
|
+
/** One candidate per `defineRule` call: one call is one rule. */
|
|
97
|
+
const candidatesIn = (workspace, scope) => {
|
|
98
|
+
const found = [];
|
|
99
|
+
for (const file of workspace.files) {
|
|
100
|
+
if (scope.changed !== undefined && !scope.changed.has(file.path))
|
|
101
|
+
continue;
|
|
102
|
+
const sites = file.facts.callSites.filter((site) => site.name === "defineRule");
|
|
103
|
+
if (sites.length === 0)
|
|
104
|
+
continue;
|
|
105
|
+
const preset = isPreset(workspace, file.path);
|
|
106
|
+
sites.forEach((site, index) => {
|
|
107
|
+
// The call's span, so the source is the rule and not the file around it.
|
|
108
|
+
// Sending LESS than this is worse, not better: the design comments above
|
|
109
|
+
// each rule are what let the model tell a fact from a verdict, and cutting
|
|
110
|
+
// to the `run` body alone lost them and raised the false-positive count.
|
|
111
|
+
const source = file.text.slice(site.start, site.end);
|
|
112
|
+
found.push({
|
|
113
|
+
source: file,
|
|
114
|
+
message: messageLiterals(source).join(" \u00b7 "),
|
|
115
|
+
id: /id:\s*"([^"]+)"/.exec(source)?.[1] ??
|
|
116
|
+
/RULE_ID = "([^"]+)"/.exec(file.text)?.[1] ??
|
|
117
|
+
file.path + " (rule " + (index + 1) + ")",
|
|
118
|
+
judged: /judged:\s*true/.test(source),
|
|
119
|
+
preset,
|
|
120
|
+
ruleSource: source.slice(0, policy.evidence.maxSourceChars * 8),
|
|
121
|
+
});
|
|
122
|
+
});
|
|
123
|
+
}
|
|
124
|
+
return found;
|
|
125
|
+
};
|
|
126
|
+
export const ruleJudgment = {
|
|
127
|
+
id: RULE_ID,
|
|
128
|
+
severity: "info",
|
|
129
|
+
description: "A rule that decides in code a question only a judgement can answer.",
|
|
130
|
+
judged: true,
|
|
131
|
+
onUnavailable: "propagate",
|
|
132
|
+
messages: messages({
|
|
133
|
+
code_decides: "{{id}} decides in code what only a judgement can decide: {{kind}}.",
|
|
134
|
+
code_decides_help: "Code should find the candidate; the model should make the call. Keep the structural filter and ask a Decision for the verdict.{{review}}",
|
|
135
|
+
}),
|
|
136
|
+
plan: Effect.fn("joggle/rule-judgment")(function* (workspace, scope) {
|
|
137
|
+
const report = reporter(ruleJudgment, locator(workspace));
|
|
138
|
+
const candidates = candidatesIn(workspace, scope);
|
|
139
|
+
if (candidates.length === 0) {
|
|
140
|
+
return {
|
|
141
|
+
plans: [],
|
|
142
|
+
read: () => outcome([], ["no file calls defineRule, so there was no rule to audit"]),
|
|
143
|
+
};
|
|
144
|
+
}
|
|
145
|
+
const budget = policy.ruleJudgment.maxRules;
|
|
146
|
+
const judged = candidates.slice(0, budget);
|
|
147
|
+
const atoms = yield* Atoms;
|
|
148
|
+
const planned = [];
|
|
149
|
+
for (const candidate of judged) {
|
|
150
|
+
const id = yield* atoms.add({
|
|
151
|
+
rule: {
|
|
152
|
+
id: candidate.id,
|
|
153
|
+
path: candidate.source.path,
|
|
154
|
+
judged: candidate.judged,
|
|
155
|
+
preset: candidate.preset,
|
|
156
|
+
message: candidate.message,
|
|
157
|
+
source: candidate.ruleSource,
|
|
158
|
+
},
|
|
159
|
+
});
|
|
160
|
+
planned.push({
|
|
161
|
+
candidate,
|
|
162
|
+
plan: {
|
|
163
|
+
ruleId: RULE_ID,
|
|
164
|
+
subject: candidate.id,
|
|
165
|
+
concerns: [candidate.source.path],
|
|
166
|
+
atoms: [id],
|
|
167
|
+
violations: { decides_in_code: [] },
|
|
168
|
+
decisions: ruleReview(id),
|
|
169
|
+
read: (answers) => answers,
|
|
170
|
+
},
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
const overflow = candidates.slice(budget).map((candidate) => ({
|
|
174
|
+
ruleId: RULE_ID,
|
|
175
|
+
subject: candidate.id,
|
|
176
|
+
stage: "budget",
|
|
177
|
+
reason: "past the budget of " + budget + " rules",
|
|
178
|
+
}));
|
|
179
|
+
return {
|
|
180
|
+
plans: planned.map((entry) => entry.plan),
|
|
181
|
+
read: (answers) => {
|
|
182
|
+
const verdicts = verdictsOf(answers);
|
|
183
|
+
const diagnostics = [];
|
|
184
|
+
const drops = [...overflow];
|
|
185
|
+
planned.forEach((entry, index) => {
|
|
186
|
+
const candidate = entry.candidate;
|
|
187
|
+
const answer = verdicts[index];
|
|
188
|
+
if (answer === undefined) {
|
|
189
|
+
drops.push({
|
|
190
|
+
ruleId: RULE_ID,
|
|
191
|
+
subject: candidate.id,
|
|
192
|
+
stage: "unreadable",
|
|
193
|
+
reason: "the response did not audit this rule",
|
|
194
|
+
});
|
|
195
|
+
return;
|
|
196
|
+
}
|
|
197
|
+
const decides = answer["decides_in_code"];
|
|
198
|
+
const kind = answer["kind"];
|
|
199
|
+
if (decides === undefined || !("probability" in decides) || kind === undefined || !("label" in kind)) {
|
|
200
|
+
drops.push({
|
|
201
|
+
ruleId: RULE_ID,
|
|
202
|
+
subject: candidate.id,
|
|
203
|
+
stage: "unreadable",
|
|
204
|
+
reason: "the response did not contain a usable verdict",
|
|
205
|
+
});
|
|
206
|
+
return;
|
|
207
|
+
}
|
|
208
|
+
if (declined(kind.label)) {
|
|
209
|
+
drops.push({
|
|
210
|
+
ruleId: RULE_ID,
|
|
211
|
+
subject: candidate.id,
|
|
212
|
+
stage: "declined",
|
|
213
|
+
reason: "the rule states a fact or already asks the model",
|
|
214
|
+
});
|
|
215
|
+
return;
|
|
216
|
+
}
|
|
217
|
+
const quality = qualityOf({
|
|
218
|
+
score: decides.probability,
|
|
219
|
+
margin: marginOfAnswer(kind),
|
|
220
|
+
confidence: kind.confidence,
|
|
221
|
+
});
|
|
222
|
+
if (quality.quality === "drop") {
|
|
223
|
+
drops.push({ ruleId: RULE_ID, subject: candidate.id, stage: "gated", reason: quality.reason });
|
|
224
|
+
return;
|
|
225
|
+
}
|
|
226
|
+
const review = quality.quality === "review";
|
|
227
|
+
diagnostics.push(report({
|
|
228
|
+
about: candidate.source,
|
|
229
|
+
messageId: "code_decides",
|
|
230
|
+
data: {
|
|
231
|
+
id: candidate.id,
|
|
232
|
+
kind: kind.label.replace(/_/g, " "),
|
|
233
|
+
review: review ? " For review: " + quality.reason + "." : "",
|
|
234
|
+
},
|
|
235
|
+
helpId: "code_decides_help",
|
|
236
|
+
identity: [RULE_ID, candidate.id].join("\u0000"),
|
|
237
|
+
confidence: kind.confidence ?? 1,
|
|
238
|
+
score: decides.probability,
|
|
239
|
+
judged: true,
|
|
240
|
+
severity: review ? "info" : "warn",
|
|
241
|
+
}));
|
|
242
|
+
});
|
|
243
|
+
return outcome(diagnostics, budgetNote({
|
|
244
|
+
unitKind: "rules",
|
|
245
|
+
judged: budget,
|
|
246
|
+
candidates: candidates.length,
|
|
247
|
+
sample: candidates.slice(budget).map((candidate) => candidate.id),
|
|
248
|
+
}), drops);
|
|
249
|
+
},
|
|
250
|
+
};
|
|
251
|
+
})
|
|
252
|
+
};
|