@kirill.konshin/lint 0.6.0 → 0.6.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.
Files changed (51) hide show
  1. package/README.md +8 -8
  2. package/dist/lib.js +2 -1
  3. package/package.json +4 -6
  4. package/skills/spec-steward/SKILL.md +2 -2
  5. package/skills/spec-steward/references/contract.md +7 -7
  6. package/skills/spec-tools/SKILL.md +3 -1
  7. package/skills/spec-tools/references/contract.md +5 -5
  8. package/skills/spec-tools/references/gitlab.md +26 -35
  9. package/skills/spec-tools/scripts/cli.js +8155 -0
  10. package/skills/spec-verify/SKILL.md +6 -6
  11. package/skills/spec-steward/scripts/lib/align.mjs +0 -127
  12. package/skills/spec-steward/scripts/lib/checks.mjs +0 -589
  13. package/skills/spec-steward/scripts/lib/citations.mjs +0 -156
  14. package/skills/spec-steward/scripts/lib/corpus.mjs +0 -256
  15. package/skills/spec-steward/scripts/lib/coverage.mjs +0 -123
  16. package/skills/spec-steward/scripts/lib/evidence.mjs +0 -189
  17. package/skills/spec-steward/scripts/lib/git.mjs +0 -138
  18. package/skills/spec-steward/scripts/lib/review.mjs +0 -347
  19. package/skills/spec-steward/scripts/lib/scan.mjs +0 -364
  20. package/skills/spec-steward/scripts/lib/util.mjs +0 -161
  21. package/skills/spec-steward/scripts/lib/wire.mjs +0 -333
  22. package/skills/spec-steward/scripts/steward.mjs +0 -289
  23. package/spec-tools/dist/audit-DkZZulq6.mjs +0 -130
  24. package/spec-tools/dist/auditChanged-CNGjlake.mjs +0 -1
  25. package/spec-tools/dist/auditChanged-CZCvMgyZ.mjs +0 -618
  26. package/spec-tools/dist/auditReport-xgq4wK2i.mjs +0 -458
  27. package/spec-tools/dist/auditScope-CBuBtfPG.mjs +0 -104
  28. package/spec-tools/dist/changeGates-DdeQKfle.mjs +0 -333
  29. package/spec-tools/dist/changeGates-uy4Ti8rK.mjs +0 -1
  30. package/spec-tools/dist/ci-BUewHJS3.mjs +0 -143
  31. package/spec-tools/dist/ci-CFBzn8Of.mjs +0 -1
  32. package/spec-tools/dist/cli.mjs +0 -93
  33. package/spec-tools/dist/comment-szasMMg2.mjs +0 -57
  34. package/spec-tools/dist/files-Bppsb34B.mjs +0 -1
  35. package/spec-tools/dist/files-QlzY687_.mjs +0 -38
  36. package/spec-tools/dist/html-BMTkpbUN.mjs +0 -1766
  37. package/spec-tools/dist/jsonrepair-Dlm5dEen.mjs +0 -742
  38. package/spec-tools/dist/repo-CjIoUPYl.mjs +0 -16
  39. package/spec-tools/dist/repo-DUcnJw3c.mjs +0 -1
  40. package/spec-tools/dist/run-BElA9du3.mjs +0 -67
  41. package/spec-tools/dist/specDiff-8G56jMYn.mjs +0 -123
  42. package/spec-tools/dist/steward-DeieyOcj.mjs +0 -34
  43. package/spec-tools/dist/stewardAudit-BRMM0lrD.mjs +0 -1
  44. package/spec-tools/dist/stewardAudit-v0vOMfLN.mjs +0 -271
  45. package/spec-tools/dist/tier-Cn0P7juM.mjs +0 -1
  46. package/spec-tools/dist/tier-c3s_mA_I.mjs +0 -65
  47. package/spec-tools/dist/util-wnxhsnWO.mjs +0 -49
  48. package/spec-tools/dist/verdict-BFfN9PO8.mjs +0 -58
  49. package/spec-tools/dist/workers-BcIgckeq.mjs +0 -417
  50. package/spec-tools/dist/workflowEvidence-DyBj8EdG.mjs +0 -1
  51. package/spec-tools/dist/workflowEvidence-oui6ghPI.mjs +0 -78
@@ -1,189 +0,0 @@
1
- // @ts-check
2
- /**
3
- * Evidence for an audit, assembled mechanically so a reader judges instead of searching. For every requirement: the
4
- * tests bound to it and its scenarios, and where its own terms occur in the sources with comments stripped. Code
5
- * citations are optional pointers, listed when present and never evidence. Every excerpt keeps its file's own line
6
- * numbers, as one JSON model (`evidence --json`) — what spec-tools assembles each audit's evidence files from.
7
- */
8
- import fs from 'node:fs';
9
- import path from 'node:path';
10
-
11
- import { isTestFile } from './citations.mjs';
12
- import { allRequirements } from './corpus.mjs';
13
- import { listFiles } from './git.mjs';
14
- import { stripComments } from './scan.mjs';
15
- import { codeTokens, jaccard, words } from './util.mjs';
16
-
17
- /**
18
- * @typedef {import('./corpus.mjs').Corpus} Corpus
19
- * @typedef {import('./corpus.mjs').Requirement} Requirement
20
- * @typedef {import('./citations.mjs').Citation} Citation
21
- * @typedef {{ file: string, text: string, lines: string[] }} Source text has its comments blanked; lines are as written
22
- */
23
-
24
- const SOURCE_EXT = /\.(?:[cm]?[jt]sx?|ya?ml|json|sh|py|go|conf|toml|sql|tpl|Dockerfile)$|(?:^|\/)Dockerfile[^/]*$/;
25
- const SOURCE_SKIP =
26
- /(?:^|\/)(?:node_modules|dist|build|coverage|\.nx|\.yarn|\.yalc|\.git|docs\/build|\.docusaurus)(?:\/|$)|^openspec\/|(?:^|\/)(?:yarn\.lock|package-lock\.json|pnpm-lock\.yaml)$/;
27
- const COMMON = new Set([
28
- 'true',
29
- 'false',
30
- 'null',
31
- 'undefined',
32
- 'string',
33
- 'number',
34
- 'object',
35
- 'id',
36
- 'url',
37
- 'name',
38
- 'type',
39
- ]);
40
-
41
- /**
42
- * The non-test source files of a repository, read once, comments blanked for searching.
43
- * @param {string} root
44
- * @returns {Source[]}
45
- */
46
- export function sourceIndex(root) {
47
- return (listFiles(root) ?? [])
48
- .filter((f) => SOURCE_EXT.test(f) && !SOURCE_SKIP.test(f) && !isTestFile(f))
49
- .flatMap((file) => {
50
- try {
51
- const raw = fs.readFileSync(path.join(root, file), 'utf8');
52
- return raw.length < 400_000 && !raw.includes('\0')
53
- ? [{ file, text: stripComments(file, raw), lines: raw.split('\n') }]
54
- : [];
55
- } catch {
56
- return [];
57
- }
58
- });
59
- }
60
-
61
- /** Terms worth searching for: the identifiers a requirement names in backticks. @param {Requirement} r */
62
- export const searchTerms = (r) =>
63
- [...new Set(codeTokens(r.block))].filter(
64
- (t) => t.length >= 3 && /^[\w$.@/:<>-]+$/.test(t) && !COMMON.has(t.toLowerCase()),
65
- );
66
-
67
- /** A term as a pattern: an identifier-like end never matches inside a longer identifier. @param {string} term */
68
- const termPattern = (term) =>
69
- new RegExp(
70
- `${/^[\w$]/.test(term) ? '(?<![\\w$])' : ''}${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}${/[\w$]$/.test(term) ? '(?![\\w$])' : ''}`,
71
- 'g',
72
- );
73
-
74
- /**
75
- * Every line of a source the term occurs on, comments stripped.
76
- * @param {string} term
77
- * @param {Source[]} sources
78
- * @returns {{ file: string, line: number }[]}
79
- */
80
- export function termHits(term, sources) {
81
- const re = termPattern(term);
82
- const hits = [];
83
- for (const s of sources) {
84
- let line = 1;
85
- let from = 0;
86
- let last = -1;
87
- for (const m of s.text.matchAll(re)) {
88
- for (let i = s.text.indexOf('\n', from); i >= 0 && i < (m.index ?? 0); i = s.text.indexOf('\n', i + 1)) {
89
- line++;
90
- from = i + 1;
91
- }
92
- if (line !== last) hits.push({ file: s.file, line });
93
- last = line;
94
- }
95
- }
96
- return hits;
97
- }
98
-
99
- /**
100
- * Requirements sharing terms or wording with `r`, strongest first.
101
- * @param {Requirement} r
102
- * @param {{ corpus: Corpus, requirement: Requirement }[]} everywhere
103
- * @param {Corpus} corpus
104
- */
105
- function relatedOf(r, everywhere, corpus) {
106
- const mine = new Set(searchTerms(r));
107
- const myWords = words(r.statement);
108
- return everywhere
109
- .filter((x) => x.requirement.id !== r.id || x.corpus.name !== corpus.name)
110
- .map((x) => {
111
- const shared = searchTerms(x.requirement).filter((t) => mine.has(t));
112
- return { x, shared, score: shared.length + jaccard(myWords, words(x.requirement.statement)) * 3 };
113
- })
114
- .filter((y) => y.shared.length || y.score >= 1.2)
115
- .sort((a, b) => b.score - a.score)
116
- .slice(0, 5);
117
- }
118
-
119
- /** The citations of a requirement's anchors. @param {Requirement} r @param {Citation[]} citations */
120
- function citationsOf(r, citations) {
121
- const anchors = new Set([`${r.file}#${r.slug}`, ...r.scenarios.map((s) => `${r.file}#${s.slug}`)]);
122
- return citations.filter((c) => c.anchor && c.resolves && anchors.has(`${c.target}#${c.anchor}`));
123
- }
124
-
125
- /**
126
- * The audit's evidence model for one repository, `spec-evidence.json`.
127
- * @param {Corpus} corpus
128
- * @param {Citation[]} citations
129
- * @param {Source[]} sources
130
- */
131
- export function evidenceModel(corpus, citations, sources) {
132
- const everywhere = allRequirements(corpus).map((requirement) => ({ corpus, requirement }));
133
- /** @type {Map<string, { file: string, line: number }[]>} */
134
- const hitsByTerm = new Map();
135
- const hitsOf = (/** @type {string} */ term) => {
136
- if (!hitsByTerm.has(term)) hitsByTerm.set(term, termHits(term, sources));
137
- return /** @type {{ file: string, line: number }[]} */ (hitsByTerm.get(term));
138
- };
139
- return {
140
- version: 1,
141
- root: corpus.name,
142
- requirements: allRequirements(corpus).map((r) => {
143
- const cites = citationsOf(r, citations);
144
- const bound = new Set(cites.filter((c) => c.binding).map((c) => c.anchor));
145
- return {
146
- id: r.id,
147
- capability: r.capability,
148
- file: r.file,
149
- line: r.line,
150
- end: r.end,
151
- block: r.block,
152
- class: r.advisory ? 'advisory' : 'required',
153
- gaps: r.gaps.map((g) => ({
154
- tracker: g.tracker,
155
- text: g.text,
156
- line: g.line,
157
- exempts: g.exempts,
158
- })),
159
- scenarios: r.scenarios.map((s) => ({
160
- slug: s.slug,
161
- line: s.line,
162
- end: s.end,
163
- block: s.block,
164
- bound: bound.has(s.slug) || (r.scenarios.length === 1 && bound.has(r.slug)),
165
- })),
166
- bindings: cites
167
- .filter((c) => c.binding)
168
- .map((c) => ({
169
- file: c.file,
170
- line: c.line,
171
- anchor: c.anchor,
172
- kind: c.binding,
173
- title: c.testTitle ?? null,
174
- window: c.window,
175
- })),
176
- pointers: cites
177
- .filter((c) => !c.binding)
178
- .map((c) => ({
179
- file: c.file,
180
- line: c.line,
181
- anchor: c.anchor,
182
- kind: c.kind === 'doc' ? 'doc' : 'code',
183
- })),
184
- terms: searchTerms(r).map((term) => ({ term, hits: hitsOf(term) })),
185
- related: relatedOf(r, everywhere, corpus).map(({ x, shared }) => ({ id: x.requirement.id, shared })),
186
- };
187
- }),
188
- };
189
- }
@@ -1,138 +0,0 @@
1
- // @ts-check
2
- /** The few git reads steward needs; every one degrades to "nothing" outside a repository. */
3
- import { execFileSync } from 'node:child_process';
4
-
5
- /**
6
- * @param {string} cwd
7
- * @param {string[]} args
8
- * @returns {string | null} stdout, or null when git fails
9
- */
10
- export function git(cwd, args) {
11
- try {
12
- return execFileSync('git', args, {
13
- cwd,
14
- encoding: 'utf8',
15
- maxBuffer: 256 * 1024 * 1024,
16
- stdio: ['ignore', 'pipe', 'ignore'],
17
- });
18
- } catch {
19
- return null;
20
- }
21
- }
22
-
23
- /** Answers a process asks more than once (git can be slow on a large or busy worktree). */
24
- const memo = new Map();
25
- /** @template T @param {string} key @param {() => T} read @returns {T} */
26
- const once = (key, read) => {
27
- if (!memo.has(key)) memo.set(key, read());
28
- return memo.get(key);
29
- };
30
- /** Forget what git answered, before a run that must see the tree as it is now. */
31
- export const forget = () => memo.clear();
32
-
33
- /** Repository root containing `dir`, or null. @param {string} dir */
34
- export const toplevel = (dir) =>
35
- once(`toplevel:${dir}`, () => git(dir, ['rev-parse', '--show-toplevel'])?.trim() || null);
36
-
37
- /**
38
- * Tracked plus untracked-but-not-ignored files, repository-relative; null when git cannot list them.
39
- * @param {string} root
40
- * @returns {string[] | null}
41
- */
42
- export function listFiles(root) {
43
- return once(`files:${root}`, () => {
44
- const out = git(root, ['ls-files', '--cached', '--others', '--exclude-standard', '-z']);
45
- return out === null ? null : [...new Set(out.split('\0').filter(Boolean))];
46
- });
47
- }
48
-
49
- /** A file's content at a ref, or null when it did not exist there. @param {string} root @param {string} ref @param {string} file */
50
- export const show = (root, ref, file) => git(root, ['show', `${ref}:${file}`]);
51
-
52
- /**
53
- * Many files' contents at a ref in one git process; a file absent there maps to null.
54
- * @param {string} root
55
- * @param {string} ref
56
- * @param {string[]} files
57
- * @returns {Map<string, string | null>}
58
- */
59
- export function showMany(root, ref, files) {
60
- const out = new Map(files.map((f) => [f, /** @type {string | null} */ (null)]));
61
- if (!files.length) return out;
62
- let buf;
63
- try {
64
- buf = execFileSync('git', ['cat-file', '--batch'], {
65
- cwd: root,
66
- input: files.map((f) => `${ref}:${f}\n`).join(''),
67
- maxBuffer: 256 * 1024 * 1024,
68
- stdio: ['pipe', 'pipe', 'ignore'],
69
- });
70
- } catch {
71
- return out;
72
- }
73
- let at = 0;
74
- for (const file of files) {
75
- const eol = buf.indexOf(10, at);
76
- if (eol < 0) break;
77
- const header = buf.subarray(at, eol).toString('utf8');
78
- at = eol + 1;
79
- const size = /^[0-9a-f]+ blob (\d+)$/.exec(header)?.[1];
80
- if (size === undefined) continue;
81
- out.set(file, buf.subarray(at, at + Number(size)).toString('utf8'));
82
- at += Number(size) + 1;
83
- }
84
- return out;
85
- }
86
-
87
- /** The commit a ref names, or null when the repository has no such object. @param {string} root @param {string} ref */
88
- export const commitOf = (root, ref) =>
89
- git(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])?.trim() || null;
90
-
91
- /** The merge base of `ref` and HEAD — what a branch is compared against — or `ref` itself when there is none. */
92
- export const mergeBase = (/** @type {string} */ root, /** @type {string} */ ref) =>
93
- git(root, ['merge-base', ref, 'HEAD'])?.trim() || ref;
94
-
95
- /** Files under `dir` at `ref`. @param {string} root @param {string} ref @param {string} dir */
96
- export function filesAt(root, ref, dir) {
97
- const out = git(root, ['ls-tree', '-r', '--name-only', '-z', ref, '--', dir]);
98
- return out ? out.split('\0').filter(Boolean) : [];
99
- }
100
-
101
- /**
102
- * Files the working tree changes against `ref`: tracked edits, additions, deletions and renames, plus untracked files.
103
- * @param {string} root
104
- * @param {string} ref
105
- */
106
- export function changedFiles(root, ref) {
107
- const tracked = git(root, ['diff', '--name-only', '-z', ref, '--']) ?? '';
108
- const untracked = git(root, ['ls-files', '--others', '--exclude-standard', '-z']) ?? '';
109
- return new Set([...tracked.split('\0'), ...untracked.split('\0')].filter(Boolean));
110
- }
111
-
112
- /**
113
- * The base `--base` names (R-004): a merge request's diff base in CI, nothing in another CI pipeline, the merge base
114
- * with `origin/HEAD` (or `origin/main`) locally; an explicit ref is compared through its merge base with HEAD.
115
- * @param {string} root
116
- * @param {string | true} given `auto`, a ref, or true when the flag had no value
117
- * @param {Record<string, string | undefined>} env
118
- * @returns {{ ref: string | null, how: string } | { error: string }}
119
- */
120
- export function resolveBase(root, given, env = process.env) {
121
- if (given !== 'auto') {
122
- if (given === true || !given) return { error: '--base needs a ref, or auto' };
123
- if (!commitOf(root, given)) return { error: `base ref ${given} not found — git fetch origin` };
124
- return { ref: mergeBase(root, given), how: `merge base of ${given}` };
125
- }
126
- const sha = env.CI_MERGE_REQUEST_DIFF_BASE_SHA;
127
- if (sha) {
128
- if (!commitOf(root, sha)) return { error: `CI_MERGE_REQUEST_DIFF_BASE_SHA ${sha} is not in this clone` };
129
- return { ref: sha, how: 'the merge request diff base' };
130
- }
131
- if (env.CI) return { ref: null, how: 'none — a CI pipeline outside a merge request' };
132
- for (const upstream of ['origin/HEAD', 'origin/main']) {
133
- if (!commitOf(root, upstream)) continue;
134
- const ref = git(root, ['merge-base', upstream, 'HEAD'])?.trim();
135
- if (ref) return { ref, how: `merge base of ${upstream}` };
136
- }
137
- return { error: 'no origin/HEAD or origin/main to compare against — git fetch origin' };
138
- }
@@ -1,347 +0,0 @@
1
- // @ts-check
2
- /**
3
- * The review file: rendered from audit findings, answered by the owner item by item, processed round by round.
4
- * Format: references/review-format.md.
5
- */
6
- import fs from 'node:fs';
7
- import path from 'node:path';
8
-
9
- import { normalize, parseArgs } from './util.mjs';
10
-
11
- /**
12
- * @typedef {{
13
- * repo: string, file: string, line: number, quote: string, ruleName?: string, criteria?: number[], layer: string,
14
- * whatsWrong: string, proposed: string, evidence?: string[], crossRefs?: string[], needsHumanIntent?: boolean,
15
- * reversesPastDecision?: string, area?: string, note?: string, cid?: string
16
- * }} Finding
17
- * @typedef {{ key?: string, title: string, whatsWrong: string, proposed: string, layer: string, criteria?: number[],
18
- * needsHumanIntent?: boolean, members: Finding[] }} Theme
19
- * @typedef {{ id: string, line: number, end: number, heading: string, theme: boolean,
20
- * members: { quote: string, location: string, line: number, comments: string[] }[],
21
- * quote: string, location: string, response: string, responseLine: number, state: string, applied: string[] }} Item
22
- */
23
-
24
- const RESPONSE_STATES = ['open', 'accepted', 'accepted-with-comment', 'comment', 'rejected', 'rejected-with-comment'];
25
-
26
- /** @param {string} text */
27
- const oneLine = (text) => normalize(String(text ?? '')).replace(/\s*\n\s*/g, ' ');
28
- /** @param {Finding} f */
29
- const location = (f) => `\`${f.repo} ${f.file}:${f.line}\``;
30
- /** @param {string} q */
31
- const quoted = (q) => `“${oneLine(q).replace(/[“”]/g, '"')}”`;
32
-
33
- /**
34
- * The extra context a reader needs to decide: evidence, cross references, intent, reversal.
35
- * @param {Finding | Theme} f
36
- */
37
- function context(f) {
38
- const parts = [];
39
- if ('reversesPastDecision' in f && f.reversesPastDecision)
40
- parts.push(`Reverses an earlier decision: ${oneLine(f.reversesPastDecision).replace(/[.\s]+$/, '')}.`);
41
- if ('evidence' in f && f.evidence?.length)
42
- parts.push(
43
- `Evidence: ${f.evidence
44
- .slice(0, 6)
45
- .map((e) => `\`${e}\``)
46
- .join(', ')}.`,
47
- );
48
- if ('crossRefs' in f && f.crossRefs?.length) parts.push(`See also: ${f.crossRefs.slice(0, 6).join(', ')}.`);
49
- return parts.length ? ` ${parts.join(' ')}` : '';
50
- }
51
-
52
- /**
53
- * One item in the mandated five-bullet shape.
54
- * @param {string} id
55
- * @param {Finding | Theme} item
56
- * @param {boolean} theme
57
- */
58
- export function renderItem(id, item, theme) {
59
- const crit = (item.criteria ?? []).join(', ');
60
- const intent = item.needsHumanIntent ? ' · ❓ intent' : '';
61
- if (!theme) {
62
- const f = /** @type {Finding} */ (item);
63
- return [
64
- `### ${id} · ${f.layer} · ${f.repo} ${f.area ?? ''}`.trimEnd() + `${crit ? ` · ${crit}` : ''}${intent}`,
65
- '',
66
- `* Rule: ${quoted(f.quote)}`,
67
- ` * Location: ${location(f)}`,
68
- ` * What’s wrong: ${oneLine(f.whatsWrong)}${context(f)}`,
69
- ` * Proposed: ${oneLine(f.proposed)}`,
70
- ` * My response: ⬜`,
71
- '',
72
- ].join('\n');
73
- }
74
- const t = /** @type {Theme} */ (item);
75
- return [
76
- `### ${id} · ${t.layer} · Theme: ${oneLine(t.title)}${crit ? ` · ${crit}` : ''}${intent}`,
77
- '',
78
- `* Rule: ${quoted(t.title)} — ${t.members.length} rules:`,
79
- ...t.members.map((m) => ` * ${quoted(m.quote)} — ${location(m)}${m.note ? ` — ${oneLine(m.note)}` : ''}`),
80
- ` * Location: each member above`,
81
- ` * What’s wrong: ${oneLine(t.whatsWrong)}`,
82
- ` * Proposed: ${oneLine(t.proposed)}`,
83
- ` * My response: ⬜`,
84
- '',
85
- ].join('\n');
86
- }
87
-
88
- /**
89
- * Render audit output into review sections.
90
- * @param {{ themes?: Theme[], findings?: Finding[] }} data
91
- * @param {{ start?: number, sections?: { key: string, title: string, areas?: string[], intro?: string }[] }} opts
92
- */
93
- export function render(data, { start = 1, sections } = {}) {
94
- let n = start;
95
- const next = () => `R-${String(n++).padStart(3, '0')}`;
96
- const themes = data.themes ?? [];
97
- const findings = data.findings ?? [];
98
- const areaOfTheme = (/** @type {Theme} */ t) => {
99
- const counts = new Map();
100
- for (const m of t.members) counts.set(m.area, (counts.get(m.area) ?? 0) + 1);
101
- return [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
102
- };
103
- const layout =
104
- sections ??
105
- [...new Set([...themes.map(areaOfTheme), ...findings.map((f) => f.area)])].map((a) => ({
106
- key: a ?? 'other',
107
- title: a ?? 'Other',
108
- areas: [a],
109
- }));
110
- const out = [];
111
- for (const s of layout) {
112
- const areas = new Set(s.areas ?? [s.key]);
113
- const ts = themes.filter((t) => areas.has(areaOfTheme(t)));
114
- const fs = findings.filter((f) => areas.has(f.area));
115
- if (!ts.length && !fs.length) continue;
116
- out.push(`## ${s.title}`, '');
117
- if (s.intro) out.push(s.intro, '');
118
- for (const t of ts) out.push(renderItem(next(), t, true));
119
- for (const f of fs.sort(
120
- (a, b) => a.repo.localeCompare(b.repo) || a.file.localeCompare(b.file) || a.line - b.line,
121
- ))
122
- out.push(renderItem(next(), f, false));
123
- }
124
- return { markdown: out.join('\n'), next: n };
125
- }
126
-
127
- const ITEM = /^###\s+(R-\d+)\b(.*)$/;
128
- const FIELD =
129
- /^\s*[*-]\s+(Rule|Location|What[’']s wrong|Proposed|My response|Applied|Previous response[^:]*)\s*:\s?(.*)$/;
130
- const MEMBER = /^\s{2,}[*-]\s+“(.+?)”\s+—\s+`([^`]+)`/;
131
-
132
- /** @param {string} response */
133
- export function stateOf(response) {
134
- const r = response.trim();
135
- if (!r || r === '⬜') return 'open';
136
- if (r.startsWith('✅')) return r.replace('✅', '').trim() ? 'accepted-with-comment' : 'accepted';
137
- if (r.startsWith('❌')) return r.replace('❌', '').trim() ? 'rejected-with-comment' : 'rejected';
138
- if (r.startsWith('⬜')) return r.replace('⬜', '').trim() ? 'comment' : 'open';
139
- return 'comment';
140
- }
141
-
142
- /**
143
- * Parse a review file into items.
144
- * @param {string} text
145
- * @returns {Item[]}
146
- */
147
- export function parseReview(text) {
148
- const lines = text.split('\n');
149
- /** @type {Item[]} */
150
- const items = [];
151
- /** @type {Item | null} */
152
- let cur = null;
153
- let field = '';
154
- lines.forEach((line, i) => {
155
- const h = ITEM.exec(line);
156
- if (h || /^#{1,3}\s/.test(line)) {
157
- if (cur) cur.end = i;
158
- cur = null;
159
- field = '';
160
- if (h) {
161
- cur = {
162
- id: h[1],
163
- line: i + 1,
164
- end: lines.length,
165
- heading: h[2],
166
- theme: /Theme:/.test(h[2]),
167
- members: [],
168
- quote: '',
169
- location: '',
170
- response: '',
171
- responseLine: 0,
172
- state: 'open',
173
- applied: [],
174
- };
175
- items.push(cur);
176
- }
177
- return;
178
- }
179
- if (!cur) return;
180
- const f = FIELD.exec(line);
181
- if (f) {
182
- field = f[1].replace('’', "'");
183
- if (field === 'Rule') cur.quote = f[2];
184
- else if (field === 'Location') cur.location = f[2];
185
- else if (field === 'My response') {
186
- cur.response = f[2];
187
- cur.responseLine = i + 1;
188
- } else if (field === 'Applied') cur.applied.push(f[2]);
189
- return;
190
- }
191
- const m = MEMBER.exec(line);
192
- if (m && cur.theme && field === 'Rule') {
193
- cur.members.push({ quote: m[1], location: m[2], line: i + 1, comments: [] });
194
- return;
195
- }
196
- if (!line.trim()) return;
197
- if (field === 'My response') cur.response += `\n${line.trim()}`;
198
- else if (field === 'Rule' && cur.members.length) cur.members[cur.members.length - 1].comments.push(line.trim());
199
- });
200
- for (const it of items) it.state = stateOf(it.response);
201
- return items;
202
- }
203
-
204
- /**
205
- * Locations a review names: `NAME path:line`.
206
- * @param {string} loc
207
- */
208
- const parseLocation = (loc) => {
209
- const m = /`?([\w-]+)\s+([^`\s]+):(\d+)`?/.exec(loc);
210
- return m ? { repo: m[1], file: m[2], line: Number(m[3]) } : null;
211
- };
212
-
213
- /**
214
- * Every quote must be found, fragment by fragment in order, at its location (a window from the line on).
215
- * @param {Item[]} items
216
- * @param {Map<string, string>} roots NAME → absolute path
217
- */
218
- export function verify(items, roots) {
219
- const problems = [];
220
- const cache = new Map();
221
- const check = (/** @type {string} */ id, /** @type {string} */ quote, /** @type {string} */ loc) => {
222
- const at = parseLocation(loc);
223
- if (!at) return problems.push(`${id}: location not understood: ${loc}`);
224
- const root = roots.get(at.repo);
225
- if (!root) return problems.push(`${id}: unknown repository ${at.repo} (pass --root ${at.repo}=<path>)`);
226
- const abs = path.join(root, at.file);
227
- if (!cache.has(abs)) cache.set(abs, fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8').split('\n') : null);
228
- const lines = cache.get(abs);
229
- if (!lines) return problems.push(`${id}: ${at.repo} ${at.file} does not exist`);
230
- if (at.line < 1 || at.line > lines.length)
231
- return problems.push(`${id}: ${at.repo} ${at.file}:${at.line} is past the end (${lines.length} lines)`);
232
- const window = normalize(lines.slice(at.line - 1, at.line + 59).join(' ')).replace(/[“”]/g, '"');
233
- const q = quote.replace(/^“|”$/g, '').replace(/[“”]/g, '"');
234
- let from = 0;
235
- for (const frag of q
236
- .split(/…|\.\.\./)
237
- .map((x) => normalize(x))
238
- .filter((x) => x.length > 2)) {
239
- const idx = window.indexOf(frag, from);
240
- if (idx < 0)
241
- return problems.push(
242
- `${id}: quote not found at ${at.repo} ${at.file}:${at.line}: "${frag.slice(0, 80)}"`,
243
- );
244
- from = idx + frag.length;
245
- }
246
- };
247
- for (const it of items) {
248
- if (it.theme) for (const m of it.members) check(it.id, m.quote, m.location);
249
- else check(it.id, it.quote.replace(/^\s*/, ''), it.location);
250
- }
251
- return problems;
252
- }
253
-
254
- /** @param {string} text @param {Item[]} items */
255
- export function lint(text, items) {
256
- const problems = [];
257
- const seen = new Set();
258
- const lines = text.split('\n');
259
- for (const it of items) {
260
- if (seen.has(it.id)) problems.push(`${it.id}: duplicate id`);
261
- seen.add(it.id);
262
- const body = lines.slice(it.line - 1, it.end).join('\n');
263
- for (const field of ['Rule', 'Location', "What’s wrong|What's wrong", 'Proposed', 'My response'])
264
- if (!new RegExp(`^\\s*[*-]\\s+(?:${field})\\s*:`, 'm').test(body))
265
- problems.push(`${it.id}: missing "${field.split('|')[0]}"`);
266
- if (!it.theme && !/^\s*“.+”/.test(it.quote)) problems.push(`${it.id}: the rule is not quoted “…”`);
267
- if (!it.theme && !parseLocation(it.location)) problems.push(`${it.id}: location is not \`NAME path:line\``);
268
- if (it.theme && !it.members.length) problems.push(`${it.id}: a theme lists no members`);
269
- if (!it.responseLine) problems.push(`${it.id}: no response line`);
270
- }
271
- return problems;
272
- }
273
-
274
- /** @param {Item[]} items */
275
- export function status(items) {
276
- const counts = Object.fromEntries(RESPONSE_STATES.map((s) => [s, 0]));
277
- for (const it of items) counts[it.state]++;
278
- const pending = items.filter((it) => it.state.startsWith('accepted') && !it.applied.length).map((it) => it.id);
279
- const memberComments = items.filter((it) => it.members.some((m) => m.comments.length)).map((it) => it.id);
280
- return {
281
- total: items.length,
282
- counts,
283
- open: items.filter((it) => it.state === 'open').map((it) => it.id),
284
- comments: items.filter((it) => it.state === 'comment' || it.state.endsWith('-with-comment')).map((it) => it.id),
285
- acceptedNotApplied: pending,
286
- rejected: items.filter((it) => it.state.startsWith('rejected')).map((it) => it.id),
287
- memberComments,
288
- resolved: items.every(
289
- (it) =>
290
- it.state !== 'open' &&
291
- it.state !== 'comment' &&
292
- (!it.state.startsWith('accepted') || it.applied.length),
293
- ),
294
- };
295
- }
296
-
297
- /**
298
- * @param {string[]} argv `render <data.json> [--out f] [--append] [--sections s.json]` | `status <file>` | `verify <file>` | `lint <file>`
299
- * @param {{ name: string, path: string }[]} roots
300
- */
301
- export function reviewCli(argv, roots) {
302
- const [sub, ...rest] = argv;
303
- const opts = parseArgs(rest, ['root']);
304
- const file = opts._[0];
305
- if (sub === 'render') {
306
- const data = JSON.parse(fs.readFileSync(file, 'utf8'));
307
- const existing = opts.out && opts.append && fs.existsSync(opts.out) ? fs.readFileSync(opts.out, 'utf8') : '';
308
- const last = Math.max(0, ...parseReview(existing).map((it) => Number(it.id.slice(2))));
309
- const sections = opts.sections ? JSON.parse(fs.readFileSync(opts.sections, 'utf8')) : undefined;
310
- const { markdown } = render(data, { start: last + 1, sections });
311
- const round = opts.round ? `## Round ${opts.round} — new\n\n` : '';
312
- const out = existing ? `${existing.trimEnd()}\n\n${round}${markdown}` : markdown;
313
- if (opts.out) fs.writeFileSync(opts.out, out.trimEnd() + '\n');
314
- else process.stdout.write(out);
315
- return 0;
316
- }
317
- const text = fs.readFileSync(file, 'utf8');
318
- const items = parseReview(text);
319
- if (sub === 'status') {
320
- const s = status(items);
321
- if (opts.json) process.stdout.write(JSON.stringify(s, null, 2) + '\n');
322
- else {
323
- process.stdout.write(
324
- `${s.total} items — ${Object.entries(s.counts)
325
- .map(([k, v]) => `${k} ${v}`)
326
- .join(', ')}\n`,
327
- );
328
- if (s.open.length) process.stdout.write(`open: ${s.open.join(' ')}\n`);
329
- if (s.comments.length) process.stdout.write(`with comments: ${s.comments.join(' ')}\n`);
330
- if (s.memberComments.length)
331
- process.stdout.write(`themes with member comments: ${s.memberComments.join(' ')}\n`);
332
- if (s.acceptedNotApplied.length)
333
- process.stdout.write(`accepted, not yet applied: ${s.acceptedNotApplied.join(' ')}\n`);
334
- process.stdout.write(s.resolved ? 'resolved: every item answered and applied\n' : 'not resolved\n');
335
- }
336
- return s.resolved ? 0 : 1;
337
- }
338
- if (sub === 'verify' || sub === 'lint') {
339
- const problems =
340
- sub === 'lint' ? lint(text, items) : verify(items, new Map(roots.map((r) => [r.name, r.path])));
341
- for (const p of problems) process.stdout.write(p + '\n');
342
- process.stderr.write(`${items.length} items, ${problems.length} problem(s)\n`);
343
- return problems.length ? 1 : 0;
344
- }
345
- process.stderr.write('usage: steward review render|status|verify|lint <file>\n');
346
- return 2;
347
- }