@kirill.konshin/lint 0.5.2 → 0.5.4
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/README.md +1 -1
- package/dist/lintPrepare.d.ts +9 -8
- package/dist/lintPrepare.d.ts.map +1 -1
- package/dist/lintPrepare.js +20 -14
- package/package.json +5 -3
- package/rules/github.md +0 -76
- package/rules/gitlab.md +0 -72
- package/rules/nextjs.md +2 -55
- package/rules/openspec.md +12 -0
- package/rules/storybook.md +2 -0
- package/rules/tailwind.md +1 -1
- package/rules/testing.md +1 -0
- package/rules/webstorm.md +6 -214
- package/skills/lint-github/SKILL.md +78 -0
- package/skills/lint-gitlab/SKILL.md +76 -0
- package/skills/lint-nextjs/SKILL.md +59 -0
- package/skills/{lint-repo.md → lint-repo/SKILL.md} +1 -1
- package/skills/lint-webstorm/SKILL.md +201 -0
- package/skills/lint-worktree/SKILL.md +28 -0
- package/skills/spec-steward/SKILL.md +76 -0
- package/skills/spec-steward/references/apply.md +18 -0
- package/skills/spec-steward/references/audit.md +57 -0
- package/skills/spec-steward/references/contract.md +186 -0
- package/skills/spec-steward/references/criteria.md +59 -0
- package/skills/spec-steward/references/model.md +71 -0
- package/skills/spec-steward/references/review-format.md +61 -0
- package/skills/spec-steward/references/wiring.md +19 -0
- package/skills/spec-steward/scripts/lib/align.mjs +126 -0
- package/skills/spec-steward/scripts/lib/checks.mjs +584 -0
- package/skills/spec-steward/scripts/lib/citations.mjs +156 -0
- package/skills/spec-steward/scripts/lib/corpus.mjs +259 -0
- package/skills/spec-steward/scripts/lib/coverage.mjs +124 -0
- package/skills/spec-steward/scripts/lib/evidence.mjs +335 -0
- package/skills/spec-steward/scripts/lib/git.mjs +138 -0
- package/skills/spec-steward/scripts/lib/review.mjs +347 -0
- package/skills/spec-steward/scripts/lib/scan.mjs +364 -0
- package/skills/spec-steward/scripts/lib/util.mjs +161 -0
- package/skills/spec-steward/scripts/lib/wire.mjs +331 -0
- package/skills/spec-steward/scripts/steward.mjs +350 -0
- package/skills/spec-steward/workflows/audit.js +539 -0
|
@@ -0,0 +1,584 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
/**
|
|
3
|
+
* Deterministic checks over the corpus, a diff of it, and the citations of it. Every kind is cheap and mechanical;
|
|
4
|
+
* judgement stays with the reader. Severity: `error` fails the run, `warn` fails it under --strict, `info` is a prompt
|
|
5
|
+
* that never fails. Under a base, prompts are limited to what the diff added or edited.
|
|
6
|
+
*/
|
|
7
|
+
import fs from 'node:fs';
|
|
8
|
+
import path from 'node:path';
|
|
9
|
+
|
|
10
|
+
import { boundAnchors } from './citations.mjs';
|
|
11
|
+
import { ADVISORY, allRequirements, DEFAULT_MARKERS, gapExempts, KNOWN_GAP, RETIRED } from './corpus.mjs';
|
|
12
|
+
import {
|
|
13
|
+
absolutesIn,
|
|
14
|
+
codeTokens,
|
|
15
|
+
containment,
|
|
16
|
+
exceptionsIn,
|
|
17
|
+
jaccard,
|
|
18
|
+
normalize,
|
|
19
|
+
sentences,
|
|
20
|
+
wordCount,
|
|
21
|
+
words,
|
|
22
|
+
} from './util.mjs';
|
|
23
|
+
|
|
24
|
+
export { DEFAULT_MARKERS };
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* @typedef {import('./corpus.mjs').Corpus} Corpus
|
|
28
|
+
* @typedef {import('./corpus.mjs').Requirement} Requirement
|
|
29
|
+
* @typedef {import('./corpus.mjs').Scenario} Scenario
|
|
30
|
+
* @typedef {import('./citations.mjs').Citation} Citation
|
|
31
|
+
* @typedef {'error' | 'warn' | 'info'} Severity
|
|
32
|
+
* @typedef {{
|
|
33
|
+
* kind: string, severity: Severity, file: string, line: number, id?: string, scenario?: string, message: string,
|
|
34
|
+
* fix?: { file: string, from: string, to: string, all?: boolean }[]
|
|
35
|
+
* }} Finding
|
|
36
|
+
* @typedef {{ reqBlocks: Set<string>, scenarioBlocks: Set<string> }} BaseIndex
|
|
37
|
+
* @typedef {{
|
|
38
|
+
* maxWords?: [number, number], maxObligations?: [number, number], files?: Set<string>, base?: BaseIndex | null
|
|
39
|
+
* }} CheckOptions
|
|
40
|
+
*/
|
|
41
|
+
|
|
42
|
+
/** The size lines: [prompt, failing] for a block's words and a statement's obligations. */
|
|
43
|
+
export const SIZE = {
|
|
44
|
+
words: /** @type {[number, number]} */ ([300, 500]),
|
|
45
|
+
obligations: /** @type {[number, number]} */ ([5, 8]),
|
|
46
|
+
};
|
|
47
|
+
/** The kinds that need a base, skipped when there is none. */
|
|
48
|
+
export const DIFF_KINDS = ['weakened', 'new-requirement', 'renamed-anchor', 'scenario-unproven', 'non-ears', 'non-bdd'];
|
|
49
|
+
|
|
50
|
+
const VAGUE =
|
|
51
|
+
/\b(appropriate(?:ly)?|reasonabl[ey]|sensibl[ey]|cleanly|lean|simplest|properly|efficient(?:ly)?|minimal(?:ly)?|best|prefer(?:s|ably|red)?|as needed|where possible|if possible|generally|typically|ideally|robust(?:ly)?|gracefully|user-friendly|well-defined|readable|maintainable|elegant(?:ly)?|badly|good)\b/i;
|
|
52
|
+
const FILE_PATH = /(?<![\w/:])(?:[\w@.-]+\/)+[\w.-]+\.(?:[cm]?[jt]sx?|json|ya?ml|sh|py|go|sql|toml|conf)\b/g;
|
|
53
|
+
const CALL_SYMBOL = /^(?:[a-z][\w$]*\.)*[a-z][\w$]*\(\)$/;
|
|
54
|
+
const CLASS_SYMBOL =
|
|
55
|
+
/^[A-Z][a-zA-Z0-9]+(?:Service|Controller|Module|Provider|Factory|Middleware|Repository|Helper|Manager|Adapter|Handler|Builder|Utils?)$/;
|
|
56
|
+
const READS =
|
|
57
|
+
/\b(?:readFileSync|readFile|readdirSync|readJson(?:Sync)?|globSync|fs\.promises\.readFile|Bun\.file)\s*\(/;
|
|
58
|
+
const READ_TARGET =
|
|
59
|
+
/['"`][^'"`\n]*(?:\.(?:[cm]?[jt]sx?|mdx?|ya?ml|json)|package\.json|AGENTS\.md|SKILL\.md|\/src|src\/)['"`]/;
|
|
60
|
+
const FIXTURE = /fixture|__fixtures__|testdata|test-data/i;
|
|
61
|
+
const TEXT_ASSERT =
|
|
62
|
+
/\.(?:toContain|toMatch|toMatchInlineSnapshot|toMatchSnapshot|toInclude)\(|\.includes\(|\.match\(|new RegExp\(|\/[^/\n]{2,}\/[gimsuy]*\.test\(/;
|
|
63
|
+
const OBLIGATION = /\b(?:MUST|SHALL|REQUIRED|SHOULD|RECOMMENDED|MAY|OPTIONAL)\b/;
|
|
64
|
+
const EARS = /^(?:When|While|Where)\b|^If\b[\s\S]*\bthen\b|\bSHALL\b/;
|
|
65
|
+
const EARS_FORMS =
|
|
66
|
+
'When <trigger>, the <system> SHALL <response>; While <state>, …; If <condition>, then …; Where <feature>, …; or The <system> SHALL …';
|
|
67
|
+
|
|
68
|
+
/** @param {Corpus} corpus */
|
|
69
|
+
const reqIndex = (corpus) => new Map(allRequirements(corpus).map((r) => [r.id, r]));
|
|
70
|
+
/** Body without its heading, normalized: identity apart from name. @param {string} block */
|
|
71
|
+
const bodyKey = (block) => normalize(block.split('\n').slice(1).join('\n'));
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* What the base corpus holds, for telling added or edited text from text it already had (a verbatim move is neither).
|
|
75
|
+
* @param {Corpus} base
|
|
76
|
+
* @returns {BaseIndex}
|
|
77
|
+
*/
|
|
78
|
+
export function baseIndex(base) {
|
|
79
|
+
const reqs = allRequirements(base);
|
|
80
|
+
return {
|
|
81
|
+
reqBlocks: new Set(reqs.map((r) => normalize(r.block))),
|
|
82
|
+
scenarioBlocks: new Set(reqs.flatMap((r) => r.scenarios.map((s) => normalize(s.block)))),
|
|
83
|
+
};
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Compare a base corpus with the head: removals, weaker obligations, dropped absolutes, added exceptions, new advisory
|
|
88
|
+
* markers — and renames (same body, new heading or file), which are not weakening but move every anchor citing them.
|
|
89
|
+
* @param {Corpus} base
|
|
90
|
+
* @param {Corpus} head
|
|
91
|
+
* @returns {{ findings: Finding[], renames: { from: string, to: string }[] }}
|
|
92
|
+
*/
|
|
93
|
+
export function diffCorpus(base, head) {
|
|
94
|
+
/** @type {Finding[]} */
|
|
95
|
+
const findings = [];
|
|
96
|
+
const renames = [];
|
|
97
|
+
const b = reqIndex(base);
|
|
98
|
+
const h = reqIndex(head);
|
|
99
|
+
const headByBody = new Map([...h.values()].map((r) => [bodyKey(r.block), r]));
|
|
100
|
+
const renamedTo = new Set();
|
|
101
|
+
|
|
102
|
+
for (const [id, old] of b) {
|
|
103
|
+
const now = h.get(id);
|
|
104
|
+
if (!now) {
|
|
105
|
+
const moved = headByBody.get(bodyKey(old.block));
|
|
106
|
+
if (moved && !b.has(moved.id)) {
|
|
107
|
+
renamedTo.add(moved.id);
|
|
108
|
+
renames.push({ from: `${old.file}#${old.slug}`, to: `${moved.file}#${moved.slug}` });
|
|
109
|
+
continue;
|
|
110
|
+
}
|
|
111
|
+
findings.push({
|
|
112
|
+
kind: 'weakened',
|
|
113
|
+
severity: 'warn',
|
|
114
|
+
file: old.file,
|
|
115
|
+
line: old.line,
|
|
116
|
+
id,
|
|
117
|
+
message: `requirement removed: "${old.name}" — never delete a rule to make code pass; the owner decides`,
|
|
118
|
+
});
|
|
119
|
+
continue;
|
|
120
|
+
}
|
|
121
|
+
const nowScen = new Map(now.scenarios.map((s) => [s.slug, s]));
|
|
122
|
+
const nowScenBody = new Map(now.scenarios.map((s) => [bodyKey(s.block), s]));
|
|
123
|
+
for (const s of old.scenarios) {
|
|
124
|
+
if (nowScen.has(s.slug)) continue;
|
|
125
|
+
const moved = nowScenBody.get(bodyKey(s.block));
|
|
126
|
+
if (moved) {
|
|
127
|
+
renames.push({ from: `${old.file}#${s.slug}`, to: `${now.file}#${moved.slug}` });
|
|
128
|
+
continue;
|
|
129
|
+
}
|
|
130
|
+
findings.push({
|
|
131
|
+
kind: 'weakened',
|
|
132
|
+
severity: 'warn',
|
|
133
|
+
file: now.file,
|
|
134
|
+
line: now.line,
|
|
135
|
+
id,
|
|
136
|
+
message: `scenario removed: "${s.name}"`,
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
/** @type {string[]} */
|
|
140
|
+
const why = [];
|
|
141
|
+
if (now.strong < old.strong) why.push(`MUST/SHALL ${old.strong} → ${now.strong}`);
|
|
142
|
+
const absOld = absolutesIn(old.statement).length;
|
|
143
|
+
const absNow = absolutesIn(now.statement).length;
|
|
144
|
+
if (absNow < absOld) why.push(`absolutes ${absOld} → ${absNow}`);
|
|
145
|
+
const exOld = exceptionsIn(old.block).length;
|
|
146
|
+
const exNow = exceptionsIn(now.block).length;
|
|
147
|
+
if (exNow > exOld) why.push(`exceptions ${exOld} → ${exNow}`);
|
|
148
|
+
if (now.advisory && !old.advisory) why.push('newly marked advisory');
|
|
149
|
+
if (why.length)
|
|
150
|
+
findings.push({
|
|
151
|
+
kind: 'weakened',
|
|
152
|
+
severity: 'warn',
|
|
153
|
+
file: now.file,
|
|
154
|
+
line: now.line,
|
|
155
|
+
id,
|
|
156
|
+
message: `"${now.name}": ${why.join(', ')} — weakening a rule needs the owner's word, never done to make code pass`,
|
|
157
|
+
});
|
|
158
|
+
}
|
|
159
|
+
for (const [id, r] of h) {
|
|
160
|
+
if (b.has(id) || renamedTo.has(id)) continue;
|
|
161
|
+
findings.push({
|
|
162
|
+
kind: 'new-requirement',
|
|
163
|
+
severity: 'info',
|
|
164
|
+
file: r.file,
|
|
165
|
+
line: r.line,
|
|
166
|
+
id,
|
|
167
|
+
message: `new requirement "${r.name}": name the observable failure it prevents and the cheapest evidence that catches it (types > lint/static > behavioural test > integration > review); if there is none it is advisory or belongs elsewhere (see the steward model)`,
|
|
168
|
+
});
|
|
169
|
+
}
|
|
170
|
+
return { findings, renames };
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* The marker findings of one requirement: retired, tracker-less, misplaced or misspelled markers grant nothing until
|
|
175
|
+
* they are fixed, and say so.
|
|
176
|
+
* @param {Requirement} r
|
|
177
|
+
* @returns {Finding[]}
|
|
178
|
+
*/
|
|
179
|
+
function markerFindings(r) {
|
|
180
|
+
/** @type {Finding[]} */
|
|
181
|
+
const out = [];
|
|
182
|
+
const warn = (/** @type {number} */ line, /** @type {string} */ message, /** @type {any} */ fix) =>
|
|
183
|
+
out.push({
|
|
184
|
+
kind: 'marker-hygiene',
|
|
185
|
+
severity: 'warn',
|
|
186
|
+
file: r.file,
|
|
187
|
+
line,
|
|
188
|
+
id: r.id,
|
|
189
|
+
message,
|
|
190
|
+
...(fix && { fix }),
|
|
191
|
+
});
|
|
192
|
+
for (const m of r.markers) {
|
|
193
|
+
if (m.inline) warn(m.line, `a ${m.label} marker inside a line is not read — put it on a line of its own`);
|
|
194
|
+
else if (m.label === RETIRED)
|
|
195
|
+
warn(
|
|
196
|
+
m.line,
|
|
197
|
+
`**⚠️ Unenforced:** is retired and grants nothing — reclassify it: ${DEFAULT_MARKERS[0]} (review is its evidence), ${DEFAULT_MARKERS[1]} (behaviour or its evidence is missing), or no marker (a test, lint or build proves it)`,
|
|
198
|
+
);
|
|
199
|
+
else if (m.label === KNOWN_GAP && !m.tracker)
|
|
200
|
+
warn(m.line, `a Known gap names its tracker — ${DEFAULT_MARKERS[1]}; without one it grants nothing`);
|
|
201
|
+
else if (m.label === ADVISORY && m.scenario)
|
|
202
|
+
warn(
|
|
203
|
+
m.line,
|
|
204
|
+
"Advisory is the requirement's class — put it directly under the requirement heading; in a scenario it grants nothing",
|
|
205
|
+
);
|
|
206
|
+
else {
|
|
207
|
+
const canon = m.label === ADVISORY ? DEFAULT_MARKERS[0] : `**⚠️ Known gap (${m.tracker}):**`;
|
|
208
|
+
if (!m.text.startsWith(canon)) {
|
|
209
|
+
const fixed = m.text.replace(/^\s*\*\*[^*]*\*\*(?:\s*:)?/u, canon);
|
|
210
|
+
warn(m.line, `marker should read ${canon}`, [{ file: r.file, from: m.text, to: fixed }]);
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
for (const g of r.gaps)
|
|
215
|
+
if (g.named && !g.exempts.some((s) => s !== g.scenario))
|
|
216
|
+
warn(
|
|
217
|
+
g.line,
|
|
218
|
+
'names no scenario of this requirement by its title — a Known gap exempts only the scenarios it names',
|
|
219
|
+
);
|
|
220
|
+
return out;
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* Checks over one corpus and its citations.
|
|
225
|
+
* @param {Corpus} corpus
|
|
226
|
+
* @param {Citation[]} citations
|
|
227
|
+
* @param {CheckOptions} opts
|
|
228
|
+
* @returns {Finding[]}
|
|
229
|
+
*/
|
|
230
|
+
export function checkCorpus(corpus, citations, opts = {}) {
|
|
231
|
+
/** @type {Finding[]} */
|
|
232
|
+
const out = [];
|
|
233
|
+
const [wordsInfo, wordsFail] = opts.maxWords ?? SIZE.words;
|
|
234
|
+
const [obligationsInfo, obligationsFail] = opts.maxObligations ?? SIZE.obligations;
|
|
235
|
+
const bound = boundAnchors(citations);
|
|
236
|
+
const inScope = (/** @type {string} */ f) => !opts.files || opts.files.has(f);
|
|
237
|
+
const base = opts.base ?? null;
|
|
238
|
+
|
|
239
|
+
for (const cap of corpus.capabilities) {
|
|
240
|
+
if (!inScope(cap.file)) continue;
|
|
241
|
+
for (const d of cap.duplicates)
|
|
242
|
+
out.push({
|
|
243
|
+
kind: 'duplicate-anchor',
|
|
244
|
+
severity: 'error',
|
|
245
|
+
file: cap.file,
|
|
246
|
+
line: d.line,
|
|
247
|
+
message: `renders #${d.slug} as line ${d.first} does — a citation reaches only the first; rename one`,
|
|
248
|
+
});
|
|
249
|
+
for (const r of cap.requirements) {
|
|
250
|
+
const at = (/** @type {number} */ line, /** @type {Scenario | undefined} */ s = undefined) => ({
|
|
251
|
+
file: r.file,
|
|
252
|
+
line,
|
|
253
|
+
id: r.id,
|
|
254
|
+
...(s && { scenario: s.slug }),
|
|
255
|
+
});
|
|
256
|
+
const stmtWords = words(r.statement);
|
|
257
|
+
const binds = (/** @type {Scenario} */ s) =>
|
|
258
|
+
bound.has(`${r.file}#${s.slug}`) || (r.scenarios.length === 1 && bound.has(`${r.file}#${r.slug}`));
|
|
259
|
+
|
|
260
|
+
const paths = [...r.block.matchAll(FILE_PATH)].map((m) => m[0]).filter((p) => !p.includes('openspec/'));
|
|
261
|
+
const symbols = codeTokens(r.block).filter((t) => CALL_SYMBOL.test(t) || CLASS_SYMBOL.test(t));
|
|
262
|
+
if (paths.length || symbols.length)
|
|
263
|
+
out.push({
|
|
264
|
+
kind: 'impl-detail',
|
|
265
|
+
severity: 'info',
|
|
266
|
+
...at(r.line),
|
|
267
|
+
message: `names ${[...new Set([...paths, ...symbols])].slice(0, 6).join(', ')} — would it survive a rewrite that keeps the contract? If not, it is not spec text`,
|
|
268
|
+
});
|
|
269
|
+
|
|
270
|
+
const obligationSentences = sentences(r.statement).filter((s) => OBLIGATION.test(s));
|
|
271
|
+
for (const s of obligationSentences) {
|
|
272
|
+
if (!/\b(MUST|SHALL|REQUIRED)\b/.test(s)) continue;
|
|
273
|
+
const v = VAGUE.exec(s);
|
|
274
|
+
if (v)
|
|
275
|
+
out.push({
|
|
276
|
+
kind: 'vague-obligation',
|
|
277
|
+
severity: 'info',
|
|
278
|
+
...at(r.statementLine),
|
|
279
|
+
message: `"${v[0]}" inside an obligation — no test can fail on it; a candidate for advisory`,
|
|
280
|
+
});
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
const abs = absolutesIn(r.statement);
|
|
284
|
+
const anyBound =
|
|
285
|
+
bound.has(`${r.file}#${r.slug}`) || r.scenarios.some((s) => bound.has(`${r.file}#${s.slug}`));
|
|
286
|
+
if (!r.advisory && abs.length && !exceptionsIn(r.statement).length && !anyBound)
|
|
287
|
+
out.push({
|
|
288
|
+
kind: 'absolute-unproven',
|
|
289
|
+
severity: 'info',
|
|
290
|
+
...at(r.line),
|
|
291
|
+
message: `absolute (${[...new Set(abs)].join(', ')}) with no named exception and nothing binding it — name its exceptions, or say there are none, for the owner's review`,
|
|
292
|
+
});
|
|
293
|
+
|
|
294
|
+
for (const s of r.scenarios) {
|
|
295
|
+
const sw = words(s.steps.map((x) => x.text).join(' '));
|
|
296
|
+
if (sw.length >= 3 && containment(sw, stmtWords) >= 0.85)
|
|
297
|
+
out.push({
|
|
298
|
+
kind: 'restating-scenario',
|
|
299
|
+
severity: 'info',
|
|
300
|
+
...at(s.line, s),
|
|
301
|
+
message: `scenario "${s.name}" restates the requirement — it adds no precision`,
|
|
302
|
+
});
|
|
303
|
+
if (base && (!s.steps.some((x) => x.kw === 'WHEN') || !s.steps.some((x) => x.kw === 'THEN')))
|
|
304
|
+
out.push({
|
|
305
|
+
kind: 'non-bdd',
|
|
306
|
+
severity: 'info',
|
|
307
|
+
...at(s.line, s),
|
|
308
|
+
message: `scenario "${s.name}" lacks WHEN/THEN steps — Given/When/Then, Given only where a precondition matters`,
|
|
309
|
+
});
|
|
310
|
+
if (
|
|
311
|
+
base &&
|
|
312
|
+
!r.advisory &&
|
|
313
|
+
!base.scenarioBlocks.has(normalize(s.block)) &&
|
|
314
|
+
!binds(s) &&
|
|
315
|
+
!gapExempts(r, s)
|
|
316
|
+
)
|
|
317
|
+
out.push({
|
|
318
|
+
kind: 'scenario-unproven',
|
|
319
|
+
severity: 'error',
|
|
320
|
+
...at(s.line, s),
|
|
321
|
+
message: `scenario "${s.name}" is new or changed in a REQUIRED requirement and nothing binds it — cite #${s.slug} on the test block, type assertion or lint entry that proves it, or name it in a ${DEFAULT_MARKERS[1]} line`,
|
|
322
|
+
});
|
|
323
|
+
}
|
|
324
|
+
for (let i = 0; i < r.scenarios.length; i++)
|
|
325
|
+
for (let j = i + 1; j < r.scenarios.length; j++) {
|
|
326
|
+
const a = words(r.scenarios[i].block.split('\n').slice(1).join(' '));
|
|
327
|
+
const bb = words(r.scenarios[j].block.split('\n').slice(1).join(' '));
|
|
328
|
+
if (a.length >= 4 && jaccard(a, bb) >= 0.9)
|
|
329
|
+
out.push({
|
|
330
|
+
kind: 'duplicate-scenario',
|
|
331
|
+
severity: 'info',
|
|
332
|
+
...at(r.scenarios[j].line, r.scenarios[j]),
|
|
333
|
+
message: `"${r.scenarios[j].name}" repeats "${r.scenarios[i].name}"`,
|
|
334
|
+
});
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
const w = wordCount(r.block);
|
|
338
|
+
const o = r.strong + r.weak;
|
|
339
|
+
if (w > wordsInfo)
|
|
340
|
+
out.push({
|
|
341
|
+
kind: 'size',
|
|
342
|
+
severity: w > wordsFail ? 'error' : 'info',
|
|
343
|
+
...at(r.line),
|
|
344
|
+
message:
|
|
345
|
+
w > wordsFail
|
|
346
|
+
? `${w} words (> ${wordsFail}) — over the failing line: split it into coherent areas that fit under it`
|
|
347
|
+
: `${w} words (> ${wordsInfo})`,
|
|
348
|
+
});
|
|
349
|
+
if (o > obligationsInfo)
|
|
350
|
+
out.push({
|
|
351
|
+
kind: 'size',
|
|
352
|
+
severity: o > obligationsFail ? 'error' : 'info',
|
|
353
|
+
...at(r.line),
|
|
354
|
+
message:
|
|
355
|
+
o > obligationsFail
|
|
356
|
+
? `${o} obligations in the statement (> ${obligationsFail}) — over the failing line: move the detail into scenarios`
|
|
357
|
+
: `${o} obligations in the statement (> ${obligationsInfo})`,
|
|
358
|
+
});
|
|
359
|
+
if (base && !obligationSentences.length)
|
|
360
|
+
out.push({
|
|
361
|
+
kind: 'non-ears',
|
|
362
|
+
severity: 'info',
|
|
363
|
+
...at(r.line),
|
|
364
|
+
message: `the statement issues no obligation — EARS: ${EARS_FORMS}`,
|
|
365
|
+
});
|
|
366
|
+
else if (base && !EARS.test(obligationSentences[0]))
|
|
367
|
+
out.push({
|
|
368
|
+
kind: 'non-ears',
|
|
369
|
+
severity: 'info',
|
|
370
|
+
...at(r.line),
|
|
371
|
+
message: `its first obligation matches no EARS template — ${EARS_FORMS}`,
|
|
372
|
+
});
|
|
373
|
+
|
|
374
|
+
out.push(...markerFindings(r));
|
|
375
|
+
}
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
out.push(...duplicateRequirements(corpus).filter((f) => inScope(f.file)));
|
|
379
|
+
out.push(...citationFindings(corpus, citations, inScope));
|
|
380
|
+
return out;
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
/**
|
|
384
|
+
* The same requirement name in two capabilities, or two requirements with the same body up to whitespace.
|
|
385
|
+
* @param {Corpus} corpus
|
|
386
|
+
* @returns {Finding[]}
|
|
387
|
+
*/
|
|
388
|
+
function duplicateRequirements(corpus) {
|
|
389
|
+
/** @type {Finding[]} */
|
|
390
|
+
const out = [];
|
|
391
|
+
/** @type {Map<string, Requirement[]>} */
|
|
392
|
+
const byName = new Map();
|
|
393
|
+
/** @type {Map<string, Requirement[]>} */
|
|
394
|
+
const byBody = new Map();
|
|
395
|
+
for (const r of allRequirements(corpus)) {
|
|
396
|
+
const name = r.name.toLowerCase();
|
|
397
|
+
byName.set(name, [...(byName.get(name) ?? []), r]);
|
|
398
|
+
const body = bodyKey(r.block);
|
|
399
|
+
if (body) byBody.set(body, [...(byBody.get(body) ?? []), r]);
|
|
400
|
+
}
|
|
401
|
+
for (const group of byName.values()) {
|
|
402
|
+
if (new Set(group.map((r) => r.capability)).size < 2) continue;
|
|
403
|
+
for (const r of group.slice(1))
|
|
404
|
+
out.push({
|
|
405
|
+
kind: 'duplicate-requirement',
|
|
406
|
+
severity: 'error',
|
|
407
|
+
file: r.file,
|
|
408
|
+
line: r.line,
|
|
409
|
+
id: r.id,
|
|
410
|
+
message: `"${r.name}" is also a requirement of ${group[0].capability} — one rule, one home`,
|
|
411
|
+
});
|
|
412
|
+
}
|
|
413
|
+
for (const group of byBody.values())
|
|
414
|
+
for (const r of group.slice(1))
|
|
415
|
+
out.push({
|
|
416
|
+
kind: 'duplicate-requirement',
|
|
417
|
+
severity: 'error',
|
|
418
|
+
file: r.file,
|
|
419
|
+
line: r.line,
|
|
420
|
+
id: r.id,
|
|
421
|
+
message: `same text as ${group[0].id} (${group[0].file}:${group[0].line})`,
|
|
422
|
+
});
|
|
423
|
+
return out;
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
/**
|
|
427
|
+
* Citations that do not resolve, tests that assert on text, and bindings that do not seem to prove what they cite.
|
|
428
|
+
* @param {Corpus} corpus
|
|
429
|
+
* @param {Citation[]} citations
|
|
430
|
+
* @param {(file: string) => boolean} inScope
|
|
431
|
+
* @returns {Finding[]}
|
|
432
|
+
*/
|
|
433
|
+
function citationFindings(corpus, citations, inScope) {
|
|
434
|
+
/** @type {Finding[]} */
|
|
435
|
+
const out = [];
|
|
436
|
+
const reqs = allRequirements(corpus);
|
|
437
|
+
/** @type {Map<string, Requirement>} */
|
|
438
|
+
const byScenario = new Map();
|
|
439
|
+
for (const r of reqs) for (const s of r.scenarios) byScenario.set(`${r.file}#${s.slug}`, r);
|
|
440
|
+
const reqByAnchor = new Map(reqs.map((r) => [`${r.file}#${r.slug}`, r]));
|
|
441
|
+
|
|
442
|
+
/** @type {Map<string, Citation[]>} */
|
|
443
|
+
const testsByFile = new Map();
|
|
444
|
+
for (const c of citations) {
|
|
445
|
+
if (!inScope(c.file)) continue;
|
|
446
|
+
if (!c.resolves)
|
|
447
|
+
out.push({
|
|
448
|
+
kind: 'dangling-citation',
|
|
449
|
+
severity: 'error',
|
|
450
|
+
file: c.file,
|
|
451
|
+
line: c.line,
|
|
452
|
+
message: `${c.target}${c.anchor ? `#${c.anchor}` : ''}: ${c.reason}`,
|
|
453
|
+
});
|
|
454
|
+
if (c.kind === 'test') testsByFile.set(c.file, [...(testsByFile.get(c.file) ?? []), c]);
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
for (const [file, cites] of testsByFile) {
|
|
458
|
+
const abs = path.join(corpus.path, file);
|
|
459
|
+
if (!fs.existsSync(abs)) continue;
|
|
460
|
+
const text = fs.readFileSync(abs, 'utf8');
|
|
461
|
+
if (READS.test(text) && READ_TARGET.test(text) && TEXT_ASSERT.test(text)) {
|
|
462
|
+
const targets = [...text.matchAll(new RegExp(READ_TARGET.source, 'g'))]
|
|
463
|
+
.map((m) => m[0])
|
|
464
|
+
.filter((t) => !FIXTURE.test(t));
|
|
465
|
+
if (targets.length)
|
|
466
|
+
out.push({
|
|
467
|
+
kind: 'textual-test',
|
|
468
|
+
severity: 'warn',
|
|
469
|
+
file,
|
|
470
|
+
line: cites[0].line,
|
|
471
|
+
message: `reads ${[...new Set(targets)].slice(0, 4).join(', ')} and asserts on text — that proves text is present, not behaviour; prefer a behavioural test, or a lint/dependency rule for structure`,
|
|
472
|
+
});
|
|
473
|
+
}
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
const linesOf = new Map();
|
|
477
|
+
for (const c of citations) {
|
|
478
|
+
if (!inScope(c.file) || !c.binding || !c.resolves || !c.anchor) continue;
|
|
479
|
+
const key = `${c.target}#${c.anchor}`;
|
|
480
|
+
const req = reqByAnchor.get(key);
|
|
481
|
+
if (req && req.scenarios.length > 1) {
|
|
482
|
+
out.push({
|
|
483
|
+
kind: 'unbound-test',
|
|
484
|
+
severity: 'info',
|
|
485
|
+
file: c.file,
|
|
486
|
+
line: c.line,
|
|
487
|
+
message: `cites the requirement "${req.name}", not the scenario it proves — a requirement anchor binds only a requirement's one scenario`,
|
|
488
|
+
});
|
|
489
|
+
continue;
|
|
490
|
+
}
|
|
491
|
+
if (c.binding !== 'test') continue;
|
|
492
|
+
const owner = byScenario.get(key);
|
|
493
|
+
const scen = owner?.scenarios.find((s) => `${owner.file}#${s.slug}` === key);
|
|
494
|
+
if (!scen) continue;
|
|
495
|
+
const terms = codeTokens(scen.block).filter((t) => t.length >= 3 && !/\s/.test(t));
|
|
496
|
+
if (!terms.length) continue;
|
|
497
|
+
if (!linesOf.has(c.file))
|
|
498
|
+
linesOf.set(c.file, fs.readFileSync(path.join(corpus.path, c.file), 'utf8').split('\n'));
|
|
499
|
+
const body = linesOf
|
|
500
|
+
.get(c.file)
|
|
501
|
+
.slice(c.window[0] - 1, c.window[1])
|
|
502
|
+
.join('\n');
|
|
503
|
+
if (!terms.some((t) => body.includes(t)))
|
|
504
|
+
out.push({
|
|
505
|
+
kind: 'unbound-test',
|
|
506
|
+
severity: 'info',
|
|
507
|
+
file: c.file,
|
|
508
|
+
line: c.line,
|
|
509
|
+
message: `cites "${scen.name}" but mentions none of its terms (${terms.slice(0, 4).join(', ')}) — does it exercise it?`,
|
|
510
|
+
});
|
|
511
|
+
}
|
|
512
|
+
return out;
|
|
513
|
+
}
|
|
514
|
+
|
|
515
|
+
/**
|
|
516
|
+
* Prompts limited to what the diff added or edited: a requirement or scenario whose text the base holds nowhere, and
|
|
517
|
+
* citations in changed files. Errors and warnings stay corpus-wide.
|
|
518
|
+
* @param {Finding[]} findings
|
|
519
|
+
* @param {Corpus} head
|
|
520
|
+
* @param {BaseIndex} base
|
|
521
|
+
* @param {Set<string>} changed files the working tree changes against the base
|
|
522
|
+
*/
|
|
523
|
+
export function scopePrompts(findings, head, base, changed) {
|
|
524
|
+
const edited = new Set();
|
|
525
|
+
for (const r of allRequirements(head)) {
|
|
526
|
+
if (!base.reqBlocks.has(normalize(r.block))) edited.add(r.id);
|
|
527
|
+
for (const s of r.scenarios) if (!base.scenarioBlocks.has(normalize(s.block))) edited.add(`${r.id}|${s.slug}`);
|
|
528
|
+
}
|
|
529
|
+
return findings.filter(
|
|
530
|
+
(f) =>
|
|
531
|
+
f.severity !== 'info' ||
|
|
532
|
+
(f.id ? edited.has(f.scenario ? `${f.id}|${f.scenario}` : f.id) : changed.has(f.file)),
|
|
533
|
+
);
|
|
534
|
+
}
|
|
535
|
+
|
|
536
|
+
/**
|
|
537
|
+
* Fixes for anchors a diff renamed: every citation of the old anchor is rewritten to the new one.
|
|
538
|
+
* @param {{ from: string, to: string }[]} renames
|
|
539
|
+
* @param {Citation[]} citations
|
|
540
|
+
* @returns {Finding[]}
|
|
541
|
+
*/
|
|
542
|
+
export function renameFindings(renames, citations) {
|
|
543
|
+
/** @type {Finding[]} */
|
|
544
|
+
const out = [];
|
|
545
|
+
for (const { from, to } of renames) {
|
|
546
|
+
const hits = citations.filter((c) => c.anchor && `${c.target}#${c.anchor}` === from);
|
|
547
|
+
for (const c of hits)
|
|
548
|
+
out.push({
|
|
549
|
+
kind: 'renamed-anchor',
|
|
550
|
+
severity: 'error',
|
|
551
|
+
file: c.file,
|
|
552
|
+
line: c.line,
|
|
553
|
+
message: `cites ${from}, renamed to ${to}`,
|
|
554
|
+
fix: [{ file: c.file, from, to, all: true }],
|
|
555
|
+
});
|
|
556
|
+
}
|
|
557
|
+
return out;
|
|
558
|
+
}
|
|
559
|
+
|
|
560
|
+
/**
|
|
561
|
+
* Apply every finding's fix; each file is rewritten once. A rename replaces whole anchors only (`#x` never `#x-y`).
|
|
562
|
+
* @param {string} root
|
|
563
|
+
* @param {Finding[]} findings
|
|
564
|
+
* @returns {string[]} files changed
|
|
565
|
+
*/
|
|
566
|
+
export function applyFixes(root, findings) {
|
|
567
|
+
/** @type {Map<string, string>} */
|
|
568
|
+
const texts = new Map();
|
|
569
|
+
for (const f of findings)
|
|
570
|
+
for (const fix of f.fix ?? []) {
|
|
571
|
+
const abs = path.join(root, fix.file);
|
|
572
|
+
const text = texts.get(abs) ?? fs.readFileSync(abs, 'utf8');
|
|
573
|
+
const whole = new RegExp(`${fix.from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w-])`, 'g');
|
|
574
|
+
texts.set(abs, fix.all ? text.replace(whole, () => fix.to) : text.replace(fix.from, () => fix.to));
|
|
575
|
+
}
|
|
576
|
+
const changed = [];
|
|
577
|
+
for (const [abs, text] of texts) {
|
|
578
|
+
if (fs.readFileSync(abs, 'utf8') !== text) {
|
|
579
|
+
fs.writeFileSync(abs, text);
|
|
580
|
+
changed.push(path.relative(root, abs));
|
|
581
|
+
}
|
|
582
|
+
}
|
|
583
|
+
return changed;
|
|
584
|
+
}
|