@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.
- package/README.md +8 -8
- package/dist/lib.js +2 -1
- package/package.json +4 -6
- package/skills/spec-steward/SKILL.md +2 -2
- package/skills/spec-steward/references/contract.md +7 -7
- package/skills/spec-tools/SKILL.md +3 -1
- package/skills/spec-tools/references/contract.md +5 -5
- package/skills/spec-tools/references/gitlab.md +26 -35
- package/skills/spec-tools/scripts/cli.js +8155 -0
- package/skills/spec-verify/SKILL.md +6 -6
- package/skills/spec-steward/scripts/lib/align.mjs +0 -127
- package/skills/spec-steward/scripts/lib/checks.mjs +0 -589
- package/skills/spec-steward/scripts/lib/citations.mjs +0 -156
- package/skills/spec-steward/scripts/lib/corpus.mjs +0 -256
- package/skills/spec-steward/scripts/lib/coverage.mjs +0 -123
- package/skills/spec-steward/scripts/lib/evidence.mjs +0 -189
- package/skills/spec-steward/scripts/lib/git.mjs +0 -138
- package/skills/spec-steward/scripts/lib/review.mjs +0 -347
- package/skills/spec-steward/scripts/lib/scan.mjs +0 -364
- package/skills/spec-steward/scripts/lib/util.mjs +0 -161
- package/skills/spec-steward/scripts/lib/wire.mjs +0 -333
- package/skills/spec-steward/scripts/steward.mjs +0 -289
- package/spec-tools/dist/audit-DkZZulq6.mjs +0 -130
- package/spec-tools/dist/auditChanged-CNGjlake.mjs +0 -1
- package/spec-tools/dist/auditChanged-CZCvMgyZ.mjs +0 -618
- package/spec-tools/dist/auditReport-xgq4wK2i.mjs +0 -458
- package/spec-tools/dist/auditScope-CBuBtfPG.mjs +0 -104
- package/spec-tools/dist/changeGates-DdeQKfle.mjs +0 -333
- package/spec-tools/dist/changeGates-uy4Ti8rK.mjs +0 -1
- package/spec-tools/dist/ci-BUewHJS3.mjs +0 -143
- package/spec-tools/dist/ci-CFBzn8Of.mjs +0 -1
- package/spec-tools/dist/cli.mjs +0 -93
- package/spec-tools/dist/comment-szasMMg2.mjs +0 -57
- package/spec-tools/dist/files-Bppsb34B.mjs +0 -1
- package/spec-tools/dist/files-QlzY687_.mjs +0 -38
- package/spec-tools/dist/html-BMTkpbUN.mjs +0 -1766
- package/spec-tools/dist/jsonrepair-Dlm5dEen.mjs +0 -742
- package/spec-tools/dist/repo-CjIoUPYl.mjs +0 -16
- package/spec-tools/dist/repo-DUcnJw3c.mjs +0 -1
- package/spec-tools/dist/run-BElA9du3.mjs +0 -67
- package/spec-tools/dist/specDiff-8G56jMYn.mjs +0 -123
- package/spec-tools/dist/steward-DeieyOcj.mjs +0 -34
- package/spec-tools/dist/stewardAudit-BRMM0lrD.mjs +0 -1
- package/spec-tools/dist/stewardAudit-v0vOMfLN.mjs +0 -271
- package/spec-tools/dist/tier-Cn0P7juM.mjs +0 -1
- package/spec-tools/dist/tier-c3s_mA_I.mjs +0 -65
- package/spec-tools/dist/util-wnxhsnWO.mjs +0 -49
- package/spec-tools/dist/verdict-BFfN9PO8.mjs +0 -58
- package/spec-tools/dist/workers-BcIgckeq.mjs +0 -417
- package/spec-tools/dist/workflowEvidence-DyBj8EdG.mjs +0 -1
- 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
|
-
}
|