@kainappsinc/factory 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +25 -0
- package/LICENSE +21 -0
- package/README.md +342 -2
- package/package.json +76 -4
- package/src/cli/args.ts +48 -0
- package/src/cli/baseline.ts +57 -0
- package/src/cli/check.ts +104 -0
- package/src/cli/factory.schema.json +96 -0
- package/src/cli/git.ts +73 -0
- package/src/cli/glob.ts +46 -0
- package/src/cli/index.ts +7 -0
- package/src/cli/io.ts +46 -0
- package/src/cli/main.ts +99 -0
- package/src/cli/manifest.ts +230 -0
- package/src/cli/ratchet.ts +522 -0
- package/src/cli/risk.ts +104 -0
- package/src/depcruise/index.cjs +85 -0
- package/src/depcruise/index.d.cts +7 -0
- package/src/eslint/ast.ts +62 -0
- package/src/eslint/config.ts +86 -0
- package/src/eslint/index.ts +26 -0
- package/src/eslint/messages.ts +43 -0
- package/src/eslint/rules/import-suffix.ts +79 -0
- package/src/eslint/rules/no-json-parse-cast.ts +46 -0
- package/src/eslint/rules/no-raw-request-json.ts +46 -0
- package/src/eslint/rules/no-untracked-todo.ts +37 -0
- package/src/eslint/tester.ts +19 -0
- package/src/packs/ts-bun/classic-typescript.ts +149 -0
- package/src/packs/ts-bun/counter-cli.ts +69 -0
- package/src/packs/ts-bun/depcruise-counts.ts +114 -0
- package/src/packs/ts-bun/eslint-counts.ts +123 -0
|
@@ -0,0 +1,522 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { baselineIds, baselinePath, type Counts, formatBaseline, isCount, parseBaseline, readBaseline, writeBaseline } from './baseline.js';
|
|
4
|
+
import { changedFiles, headSha, listFiles, mergeBase, resolveCommit, showFile } from './git.js';
|
|
5
|
+
import { selectFiles } from './glob.js';
|
|
6
|
+
import { EXIT_FAIL, EXIT_OK, FactoryError, type Io, table } from './io.js';
|
|
7
|
+
import {
|
|
8
|
+
type Allowance, DEFAULT_BASELINES_DIR, MANIFEST_FILE, type Manifest, type MaxLinesRatchet, parseYaml, type PatternRatchet, type Ratchet, TOTAL_KEY, validateManifest,
|
|
9
|
+
} from './manifest.js';
|
|
10
|
+
|
|
11
|
+
/** Most locations printed for one ratchet; the rest are summarised. */
|
|
12
|
+
export const LOCATION_CAP = 30;
|
|
13
|
+
|
|
14
|
+
export interface Location { file: string; line?: number; text: string }
|
|
15
|
+
export interface Measured { counts: Counts; locations: Location[]; error?: string }
|
|
16
|
+
|
|
17
|
+
type TextCache = Map<string, string | null>;
|
|
18
|
+
|
|
19
|
+
function readText(root: string, file: string, cache: TextCache): string | null {
|
|
20
|
+
if (!cache.has(file)) {
|
|
21
|
+
let text: string | null = null;
|
|
22
|
+
try { text = readFileSync(join(root, file), 'utf8'); } catch { /* a directory symlink or unreadable: not a text file */ }
|
|
23
|
+
cache.set(file, text);
|
|
24
|
+
}
|
|
25
|
+
return cache.get(file) ?? null;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export function lineCount(text: string): number {
|
|
29
|
+
if (text === '') return 0;
|
|
30
|
+
return text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** What a file-based ratchet finds in one file's text. */
|
|
34
|
+
function locator(ratchet: PatternRatchet | MaxLinesRatchet): (file: string, text: string) => Location[] {
|
|
35
|
+
if (ratchet.kind === 'pattern') {
|
|
36
|
+
const re = new RegExp(ratchet.pattern);
|
|
37
|
+
return (file, text) => {
|
|
38
|
+
const found: Location[] = [];
|
|
39
|
+
text.split('\n').forEach((raw, i) => {
|
|
40
|
+
const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
|
|
41
|
+
if (re.test(line)) found.push({ file, line: i + 1, text: line.trim() });
|
|
42
|
+
});
|
|
43
|
+
return found;
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
return (file, text) => {
|
|
47
|
+
const n = lineCount(text);
|
|
48
|
+
return n > ratchet.max_lines ? [{ file, text: `${n} lines` }] : [];
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Computes one ratchet's counts. `files` is the repository's file list (see listFiles). */
|
|
53
|
+
export function measure(root: string, ratchet: Ratchet, files: readonly string[], cache: TextCache = new Map()): Measured {
|
|
54
|
+
if (ratchet.kind === 'run') return measureCommand(root, ratchet.run);
|
|
55
|
+
const locate = locator(ratchet);
|
|
56
|
+
const locations: Location[] = [];
|
|
57
|
+
for (const file of selectFiles(files, ratchet)) {
|
|
58
|
+
const text = readText(root, file, cache);
|
|
59
|
+
if (text !== null) locations.push(...locate(file, text));
|
|
60
|
+
}
|
|
61
|
+
return { counts: { total: locations.length }, locations };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function measureCommand(root: string, command: string): Measured {
|
|
65
|
+
const failure = (error: string): Measured => ({ counts: {}, locations: [], error });
|
|
66
|
+
const proc = Bun.spawnSync(['sh', '-c', command], { cwd: root, stdout: 'pipe', stderr: 'pipe' });
|
|
67
|
+
const stdout = proc.stdout.toString();
|
|
68
|
+
if (proc.exitCode !== 0) {
|
|
69
|
+
const tail = proc.stderr.toString().trim().split('\n').slice(-5).join('\n ');
|
|
70
|
+
return failure(`\`${command}\` exited ${proc.exitCode}${tail ? `:\n ${tail}` : ''}`);
|
|
71
|
+
}
|
|
72
|
+
let parsed: unknown;
|
|
73
|
+
try { parsed = JSON.parse(stdout); } catch {
|
|
74
|
+
return failure(`\`${command}\` must print one JSON object of counts on stdout, got: ${stdout.trim().slice(0, 200) || '(nothing)'}`);
|
|
75
|
+
}
|
|
76
|
+
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
|
|
77
|
+
return failure(`\`${command}\` must print a JSON object {"key": count}, got ${stdout.trim().slice(0, 200)}`);
|
|
78
|
+
}
|
|
79
|
+
const counts: Counts = {};
|
|
80
|
+
for (const [k, v] of Object.entries(parsed)) {
|
|
81
|
+
if (!isCount(v)) return failure(`\`${command}\` printed ${JSON.stringify(k)}: ${JSON.stringify(v)}; every count must be a non-negative integer`);
|
|
82
|
+
counts[k] = v;
|
|
83
|
+
}
|
|
84
|
+
return { counts, locations: [] };
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
export interface Delta { key: string; base: number; now: number }
|
|
88
|
+
|
|
89
|
+
/** Keys that differ between a baseline and a measurement; a missing key counts as 0. */
|
|
90
|
+
export function deltas(base: Counts, now: Counts): { over: Delta[]; under: Delta[] } {
|
|
91
|
+
const over: Delta[] = [];
|
|
92
|
+
const under: Delta[] = [];
|
|
93
|
+
for (const key of [...new Set([...Object.keys(base), ...Object.keys(now)])].sort()) {
|
|
94
|
+
const d = { key, base: base[key] ?? 0, now: now[key] ?? 0 };
|
|
95
|
+
if (d.now > d.base) over.push(d);
|
|
96
|
+
else if (d.now < d.base) under.push(d);
|
|
97
|
+
}
|
|
98
|
+
return { over, under };
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** Increases on keys `base` has; a key it never had is a new sub-count, not an increase. */
|
|
102
|
+
function increasesOnKnownKeys(base: Counts, now: Counts): Delta[] {
|
|
103
|
+
return deltas(base, now).over.filter((d) => d.key in base);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
const signed = (n: number) => (n > 0 ? `+${n}` : `${n}`);
|
|
107
|
+
function describe(ds: readonly Delta[]): string {
|
|
108
|
+
return ds.map((d) => `${d.key === 'total' ? '' : `${d.key} `}${d.base} -> ${d.now} (${signed(d.now - d.base)})`).join(', ');
|
|
109
|
+
}
|
|
110
|
+
const sum = (c: Counts) => Object.values(c).reduce((a, b) => a + b, 0);
|
|
111
|
+
/** Keys `a` has and `b` does not. */
|
|
112
|
+
const keysMissingFrom = (a: Counts, b: Counts) => Object.keys(a).filter((k) => !(k in b)).sort();
|
|
113
|
+
|
|
114
|
+
/** Whether two ratchets count the same thing: kind, counter and file selection; `why` and `show` are ignored. */
|
|
115
|
+
export function sameDefinition(a: Ratchet, b: Ratchet): boolean {
|
|
116
|
+
const shape = (r: Ratchet) => JSON.stringify(r.kind === 'run'
|
|
117
|
+
? { kind: r.kind, run: r.run }
|
|
118
|
+
: {
|
|
119
|
+
kind: r.kind,
|
|
120
|
+
counter: r.kind === 'pattern' ? r.pattern : r.max_lines,
|
|
121
|
+
include: [...r.include].sort(),
|
|
122
|
+
exclude: [...r.exclude].sort(),
|
|
123
|
+
});
|
|
124
|
+
return shape(a) === shape(b);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
export interface RatchetOptions {
|
|
128
|
+
update?: boolean;
|
|
129
|
+
allowIncrease?: boolean;
|
|
130
|
+
/** A git ref; baselines may not be higher here than there. */
|
|
131
|
+
against?: string;
|
|
132
|
+
only?: string;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
interface RefState {
|
|
136
|
+
label: string;
|
|
137
|
+
commit: string;
|
|
138
|
+
baselinesDir: string;
|
|
139
|
+
/** Ratchet ids in the ref's manifest; null when the ref has no readable manifest. */
|
|
140
|
+
ids: Set<string> | null;
|
|
141
|
+
/** The ref's ratchet definitions; null when its manifest is missing or invalid. */
|
|
142
|
+
defs: Map<string, Ratchet> | null;
|
|
143
|
+
/** The ref's allowances; none when its manifest is missing, invalid or has no `allowances`. */
|
|
144
|
+
allowances: Allowance[];
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/** What the manifest at a ref says about ratchets. */
|
|
148
|
+
function refState(root: string, ref: string, say: (s: string) => void): RefState {
|
|
149
|
+
const commit = resolveCommit(root, ref);
|
|
150
|
+
const none: RefState = { label: ref, commit, baselinesDir: DEFAULT_BASELINES_DIR, ids: null, defs: null, allowances: [] };
|
|
151
|
+
const text = showFile(root, commit, MANIFEST_FILE);
|
|
152
|
+
if (text === null) return none;
|
|
153
|
+
let raw: unknown;
|
|
154
|
+
try { raw = parseYaml(text, `${MANIFEST_FILE} at ${ref}`); } catch { return none; }
|
|
155
|
+
const { manifest } = validateManifest(raw);
|
|
156
|
+
if (manifest) {
|
|
157
|
+
const defs = new Map(manifest.ratchets.map((r) => [r.id, r]));
|
|
158
|
+
return { ...none, baselinesDir: manifest.baselines_dir, ids: new Set(defs.keys()), defs, allowances: manifest.allowances };
|
|
159
|
+
}
|
|
160
|
+
// An invalid manifest at the ref: compare baselines only, as before definitions were judged; no allowances.
|
|
161
|
+
say(`NOTE ${MANIFEST_FILE} at ${ref} is not a valid manifest: ratchets are compared by baseline only, not judged by ${ref}'s definitions.`);
|
|
162
|
+
const obj = (typeof raw === 'object' && raw !== null ? raw : {}) as Record<string, unknown>;
|
|
163
|
+
const ids = new Set<string>();
|
|
164
|
+
if (Array.isArray(obj.ratchets)) {
|
|
165
|
+
for (const r of obj.ratchets) {
|
|
166
|
+
const id = (r as Record<string, unknown> | null)?.id;
|
|
167
|
+
if (typeof id === 'string') ids.add(id);
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
const dir = typeof obj.baselines_dir === 'string' ? obj.baselines_dir : DEFAULT_BASELINES_DIR;
|
|
171
|
+
return { ...none, baselinesDir: dir, ids };
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
/** What every ratchet step reads from and reports to. */
|
|
175
|
+
interface Ctx {
|
|
176
|
+
root: string;
|
|
177
|
+
manifest: Manifest;
|
|
178
|
+
/** The repository's file list; empty when nothing needs it. */
|
|
179
|
+
files: readonly string[];
|
|
180
|
+
cache: TextCache;
|
|
181
|
+
/** Files this branch touched: their occurrences are listed first. */
|
|
182
|
+
changed: ReadonlySet<string>;
|
|
183
|
+
say: (s: string) => void;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** One ratchet's summary row, and whether it counts as a problem. */
|
|
187
|
+
interface Outcome { row: string[]; failed: boolean }
|
|
188
|
+
|
|
189
|
+
function baselineFile(manifest: Manifest, id: string): string {
|
|
190
|
+
return baselinePath(manifest.baselines_dir, id);
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
function summaryRow(id: string, base: Counts | undefined, now: Counts, result: string): string[] {
|
|
194
|
+
return [id, base ? String(sum(base)) : '-', String(sum(now)), result];
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
function selectRatchets(manifest: Manifest, only: string | undefined): Ratchet[] {
|
|
198
|
+
if (only === undefined) return manifest.ratchets;
|
|
199
|
+
const ratchets = manifest.ratchets.filter((r) => r.id === only);
|
|
200
|
+
if (!ratchets.length) {
|
|
201
|
+
throw new FactoryError(`no ratchet "${only}" in ${MANIFEST_FILE} (ratchets: ${manifest.ratchets.map((r) => r.id).join(', ') || 'none'})`);
|
|
202
|
+
}
|
|
203
|
+
return ratchets;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/** Files changed since the merge base with the ref, or since HEAD; empty without history to compare with. */
|
|
207
|
+
function changedSince(root: string, ref: RefState | null): Set<string> {
|
|
208
|
+
try {
|
|
209
|
+
const from = ref ? mergeBase(root, ref.commit, 'HEAD') : headSha(root);
|
|
210
|
+
if (from) return new Set(changedFiles(root, from));
|
|
211
|
+
} catch { /* no history to compare with: plain order */ }
|
|
212
|
+
return new Set();
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* `factory ratchet`. Every count must equal its baseline: above fails (new debt),
|
|
217
|
+
* below fails too (stale baseline, which would let the slack be spent again).
|
|
218
|
+
* `--update` lowers baselines; raising or creating one needs `--allow-increase`.
|
|
219
|
+
* `--against <ref>` also judges the change by the ref's definitions and baselines.
|
|
220
|
+
*/
|
|
221
|
+
export function runRatchet(root: string, manifest: Manifest, opts: RatchetOptions, io: Io): number {
|
|
222
|
+
const ratchets = selectRatchets(manifest, opts.only);
|
|
223
|
+
if (opts.allowIncrease && !opts.update) throw new FactoryError('--allow-increase only applies together with --update');
|
|
224
|
+
const say = (s: string) => io.out(`${s}\n`);
|
|
225
|
+
const ref = opts.against !== undefined ? refState(root, opts.against, say) : null;
|
|
226
|
+
const needFiles = ratchets.some((r) => r.kind !== 'run') || ref?.defs != null;
|
|
227
|
+
const files = needFiles ? listFiles(root) : [];
|
|
228
|
+
const ctx: Ctx = { root, manifest, files, cache: new Map(), changed: changedSince(root, ref), say };
|
|
229
|
+
|
|
230
|
+
let failed = 0;
|
|
231
|
+
const summary: string[][] = [['ratchet', 'baseline', 'now', 'result']];
|
|
232
|
+
for (const r of ratchets) {
|
|
233
|
+
const outcome = judgeRatchet(ctx, r, opts);
|
|
234
|
+
summary.push(outcome.row);
|
|
235
|
+
if (outcome.failed) failed++;
|
|
236
|
+
}
|
|
237
|
+
if (ref) failed += checkAgainst(ctx, ratchets, ref, opts.only === undefined);
|
|
238
|
+
if (opts.only === undefined) noteOrphanBaselines(ctx);
|
|
239
|
+
|
|
240
|
+
io.out(`\n${table(summary)}`);
|
|
241
|
+
if (failed) {
|
|
242
|
+
io.out(`${failed} ratchet problem${failed === 1 ? '' : 's'}. Counts may only go down: fix the code, not the baseline.\n`);
|
|
243
|
+
return EXIT_FAIL;
|
|
244
|
+
}
|
|
245
|
+
io.out(opts.update ? 'Baselines match the counts.\n' : 'All ratchets hold.\n');
|
|
246
|
+
return EXIT_OK;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** Measures one ratchet and loads its baseline, then updates or checks it. */
|
|
250
|
+
function judgeRatchet(ctx: Ctx, r: Ratchet, opts: RatchetOptions): Outcome {
|
|
251
|
+
const { say } = ctx;
|
|
252
|
+
const m = measure(ctx.root, r, ctx.files, ctx.cache);
|
|
253
|
+
if (m.error) {
|
|
254
|
+
say(`FAIL ${r.id}: could not count: ${m.error}`);
|
|
255
|
+
say(` Do: fix the counter command in ${MANIFEST_FILE} (ratchets.${r.id}.run) so it prints {"key": count}.`);
|
|
256
|
+
return { row: [r.id, '-', '-', 'error'], failed: true };
|
|
257
|
+
}
|
|
258
|
+
const loaded = readBaseline(ctx.root, ctx.manifest.baselines_dir, r.id);
|
|
259
|
+
if (typeof loaded === 'string') {
|
|
260
|
+
say(`FAIL ${r.id}: ${loaded}`);
|
|
261
|
+
say(` Do: restore the file from git (git checkout -- ${baselineFile(ctx.manifest, r.id)}); do not edit baselines by hand.`);
|
|
262
|
+
return { row: [r.id, '?', String(sum(m.counts)), 'error'], failed: true };
|
|
263
|
+
}
|
|
264
|
+
const base = loaded?.counts;
|
|
265
|
+
return opts.update ? updateBaseline(ctx, r, m, base, opts.allowIncrease === true) : checkBaseline(ctx, r, m, base);
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/** `--update`: writes lower baselines; a higher or new one only with `--allow-increase`. */
|
|
269
|
+
function updateBaseline(ctx: Ctx, r: Ratchet, m: Measured, base: Counts | undefined, allowIncrease: boolean): Outcome {
|
|
270
|
+
const { root, manifest, say } = ctx;
|
|
271
|
+
const now = m.counts;
|
|
272
|
+
const file = baselineFile(manifest, r.id);
|
|
273
|
+
const row = (result: string): string[] => summaryRow(r.id, base, now, result);
|
|
274
|
+
const { over, under } = base ? deltas(base, now) : { over: [], under: [] };
|
|
275
|
+
|
|
276
|
+
if (!base || over.length) {
|
|
277
|
+
if (!allowIncrease) {
|
|
278
|
+
if (base) say(`REFUSED ${r.id}: ${describe(over)}; --update only lowers baselines`);
|
|
279
|
+
else say(`REFUSED ${r.id}: no baseline yet (count is ${sum(now)}); creating one needs --allow-increase`);
|
|
280
|
+
say(` Why the rule exists: ${r.why}`);
|
|
281
|
+
printLocations(m, ctx.changed, say);
|
|
282
|
+
printShow(r, over, say);
|
|
283
|
+
say(base
|
|
284
|
+
? ` Do: fix the new occurrences. Raising a baseline needs an allowance in ${MANIFEST_FILE} on the target branch first (merged in its own, reviewed merge request), then --allow-increase.`
|
|
285
|
+
: ` Do: a new ratchet starts at today's count: ${manifest.cli} ratchet --update --allow-increase --only ${r.id}`);
|
|
286
|
+
return { row: row('refused'), failed: true };
|
|
287
|
+
}
|
|
288
|
+
writeBaseline(root, manifest.baselines_dir, r.id, now);
|
|
289
|
+
if (base) say(`RAISED ${r.id}: ${describe(over)} (written to ${file})`);
|
|
290
|
+
else say(`CREATED ${r.id}: baseline ${sum(now)} (written to ${file})`);
|
|
291
|
+
return { row: row(base ? 'raised' : 'created'), failed: false };
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
// Lowered, or the same counts with a zero key added or dropped: the file is rewritten either way.
|
|
295
|
+
if (under.length || formatBaseline(r.id, now) !== formatBaseline(r.id, base)) {
|
|
296
|
+
writeBaseline(root, manifest.baselines_dir, r.id, now);
|
|
297
|
+
const dropped = keysMissingFrom(base, now);
|
|
298
|
+
const added = keysMissingFrom(now, base);
|
|
299
|
+
const what = [
|
|
300
|
+
describe(under),
|
|
301
|
+
dropped.length ? `dropped ${dropped.join(', ')}` : '',
|
|
302
|
+
added.length ? `added ${added.join(', ')} at 0` : '',
|
|
303
|
+
].filter(Boolean).join('; ');
|
|
304
|
+
say(`LOWERED ${r.id}: ${what} (written to ${file}; commit it)`);
|
|
305
|
+
return { row: row('lowered'), failed: false };
|
|
306
|
+
}
|
|
307
|
+
return { row: row('ok'), failed: false };
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/** The plain check: every count must equal its baseline. */
|
|
311
|
+
function checkBaseline(ctx: Ctx, r: Ratchet, m: Measured, base: Counts | undefined): Outcome {
|
|
312
|
+
const { manifest, say } = ctx;
|
|
313
|
+
const now = m.counts;
|
|
314
|
+
const file = baselineFile(manifest, r.id);
|
|
315
|
+
const row = (result: string): string[] => summaryRow(r.id, base, now, result);
|
|
316
|
+
|
|
317
|
+
if (!base) {
|
|
318
|
+
say(`FAIL ${r.id}: no baseline (${file} is missing); the count is ${sum(now)}`);
|
|
319
|
+
say(` Do: a new ratchet starts at today's count: ${manifest.cli} ratchet --update --allow-increase --only ${r.id}, then commit the file.`);
|
|
320
|
+
printLocations(m, ctx.changed, say);
|
|
321
|
+
return { row: row('no baseline'), failed: true };
|
|
322
|
+
}
|
|
323
|
+
// Output only: a missing key counts as 0, so an orphan key fails only if its baseline is above 0 (stale).
|
|
324
|
+
const orphans = keysMissingFrom(base, now);
|
|
325
|
+
if (orphans.length) {
|
|
326
|
+
const pronoun = orphans.length === 1 ? 'it' : 'them';
|
|
327
|
+
say(`NOTE ${r.id}: the count no longer has ${orphans.join(', ')}; \`${manifest.cli} ratchet --update\` drops ${pronoun} from ${file}.`);
|
|
328
|
+
}
|
|
329
|
+
const { over, under } = deltas(base, now);
|
|
330
|
+
if (over.length) {
|
|
331
|
+
say(`FAIL ${r.id}: ${describe(over)}`);
|
|
332
|
+
say(` Why the rule exists: ${r.why}`);
|
|
333
|
+
say(` Do: remove the new occurrences${m.locations.length ? ' (files changed on this branch are listed first)' : ''}. Do not raise the baseline.`);
|
|
334
|
+
printLocations(m, ctx.changed, say);
|
|
335
|
+
printShow(r, over, say);
|
|
336
|
+
return { row: row('over'), failed: true };
|
|
337
|
+
}
|
|
338
|
+
if (under.length) {
|
|
339
|
+
say(`FAIL ${r.id}: ${describe(under)}: the count went down, so the baseline is stale`);
|
|
340
|
+
say(` Do: run \`${manifest.cli} ratchet --update\` and commit ${file}, so the freed slack cannot be spent again.`);
|
|
341
|
+
return { row: row('stale'), failed: true };
|
|
342
|
+
}
|
|
343
|
+
return { row: row('ok'), failed: false };
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
/** For a run ratchet with `show`: the command that lists the occurrences of the keys that rose. */
|
|
347
|
+
export function showCommand(r: Ratchet, over: readonly Delta[]): string | undefined {
|
|
348
|
+
if (r.kind !== 'run' || r.show === undefined) return undefined;
|
|
349
|
+
return r.show.replaceAll('{keys}', over.map((d) => d.key).join(','));
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
function printShow(r: Ratchet, over: readonly Delta[], say: (s: string) => void): void {
|
|
353
|
+
const cmd = showCommand(r, over);
|
|
354
|
+
if (cmd !== undefined) say(` See them (file:line): ${cmd}`);
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
function printLocations(m: Measured, changed: ReadonlySet<string>, say: (s: string) => void): void {
|
|
358
|
+
if (!m.locations.length) return;
|
|
359
|
+
const sorted = [...m.locations].sort((a, b) => Number(changed.has(b.file)) - Number(changed.has(a.file)));
|
|
360
|
+
say(` Occurrences (${m.locations.length}${m.locations.length > LOCATION_CAP ? `, first ${LOCATION_CAP}` : ''}):`);
|
|
361
|
+
for (const loc of sorted.slice(0, LOCATION_CAP)) {
|
|
362
|
+
const where = loc.line === undefined ? loc.file : `${loc.file}:${loc.line}`;
|
|
363
|
+
say(` ${where}${changed.has(loc.file) ? ' (changed)' : ''} ${loc.text.slice(0, 160)}`);
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
function noteOrphanBaselines(ctx: Ctx): void {
|
|
368
|
+
const known = new Set(ctx.manifest.ratchets.map((r) => r.id));
|
|
369
|
+
for (const id of baselineIds(ctx.root, ctx.manifest.baselines_dir)) {
|
|
370
|
+
if (!known.has(id)) ctx.say(`NOTE ${baselineFile(ctx.manifest, id)} has no ratchet in ${MANIFEST_FILE}; delete the file or restore the ratchet.`);
|
|
371
|
+
}
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* The MR rules, judged by the ref: a ratchet whose definition is unchanged may
|
|
376
|
+
* not have a higher baseline than at the ref; one whose definition changed is
|
|
377
|
+
* measured with the ref's definition, and that count may not exceed the ref's
|
|
378
|
+
* baseline (so loosening a regex cannot hide new debt); a ratchet at the ref
|
|
379
|
+
* may only disappear when listed under `retired`. Returns the failure count.
|
|
380
|
+
*/
|
|
381
|
+
function checkAgainst(ctx: Ctx, ratchets: readonly Ratchet[], ref: RefState, all: boolean): number {
|
|
382
|
+
if (ref.ids === null) {
|
|
383
|
+
ctx.say(`NOTE ${MANIFEST_FILE} does not exist at ${ref.label} (or is unreadable there): every ratchet is new.`);
|
|
384
|
+
return 0;
|
|
385
|
+
}
|
|
386
|
+
let failed = 0;
|
|
387
|
+
for (const r of ratchets) if (compareWithRef(ctx, r, ref)) failed++;
|
|
388
|
+
if (all) failed += checkRemoved(ctx, ref.label, ref.ids);
|
|
389
|
+
return failed;
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
/** One ratchet's baseline against the ref's; true when it fails. */
|
|
393
|
+
function compareWithRef(ctx: Ctx, r: Ratchet, ref: RefState): boolean {
|
|
394
|
+
const { say } = ctx;
|
|
395
|
+
const here = readBaseline(ctx.root, ctx.manifest.baselines_dir, r.id);
|
|
396
|
+
if (here === null || typeof here === 'string') return false; // already reported by judgeRatchet
|
|
397
|
+
const path = baselinePath(ref.baselinesDir, r.id);
|
|
398
|
+
const text = showFile(ctx.root, ref.commit, path);
|
|
399
|
+
if (text === null) {
|
|
400
|
+
say(`NEW ${r.id}: no baseline at ${ref.label}; it starts at ${sum(here.counts)} here.`);
|
|
401
|
+
return false;
|
|
402
|
+
}
|
|
403
|
+
const there = parseBaseline(text, r.id, `${path} at ${ref.label}`);
|
|
404
|
+
if (typeof there === 'string') {
|
|
405
|
+
say(`NOTE ${there}; skipped the comparison for ${r.id}.`);
|
|
406
|
+
return false;
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
const refDef = ref.defs?.get(r.id);
|
|
410
|
+
if (refDef && !sameDefinition(r, refDef)) return judgeByRefDefinition(ctx, r, refDef, ref, there.counts);
|
|
411
|
+
|
|
412
|
+
// A key the ref never had is a new sub-count (for example a new lint rule): reported, allowed.
|
|
413
|
+
const fresh = Object.keys(here.counts).filter((k) => !(k in there.counts));
|
|
414
|
+
if (fresh.length) say(`NEW ${r.id}: keys not at ${ref.label}: ${fresh.join(', ')}`);
|
|
415
|
+
const { uncovered, failed } = useAllowances(ctx, r, ref, increasesOnKnownKeys(there.counts, here.counts));
|
|
416
|
+
if (!uncovered.length) return failed;
|
|
417
|
+
say(`FAIL ${r.id}: this change raises its own baseline against ${ref.label}: ${describe(uncovered)}`);
|
|
418
|
+
say(` Why the rule exists: ${r.why}`);
|
|
419
|
+
say(` Do: a merge request cannot raise its own baseline. Restore ${baselineFile(ctx.manifest, r.id)} from ${ref.label} and bring the count back down.`);
|
|
420
|
+
sayHowToAllow(ctx, r, ref, uncovered);
|
|
421
|
+
printShow(r, uncovered, say);
|
|
422
|
+
return true;
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
/** A redefined ratchet: the working tree, counted with the ref's definition, may not exceed the ref's baseline. */
|
|
426
|
+
function judgeByRefDefinition(ctx: Ctx, r: Ratchet, refDef: Ratchet, ref: RefState, refCounts: Counts): boolean {
|
|
427
|
+
const { say } = ctx;
|
|
428
|
+
const { label } = ref;
|
|
429
|
+
say(`CHANGED ${r.id}: definition differs from ${label}; judged by ${label}'s definition, needs a reviewer`);
|
|
430
|
+
const m = measure(ctx.root, refDef, ctx.files, ctx.cache);
|
|
431
|
+
if (m.error) {
|
|
432
|
+
say(`FAIL ${r.id}: could not count with ${label}'s definition: ${m.error}`);
|
|
433
|
+
say(` Do: check whether ${label}'s command runs a path this branch removed. If so, keep a thin shim there for this merge request and remove it in a follow-up.`);
|
|
434
|
+
return true;
|
|
435
|
+
}
|
|
436
|
+
// Keys the ref never had cannot be judged by it; the working-tree rule still covers them.
|
|
437
|
+
// The ref's allowances cover a rise here too: its limit per key is baseline + allowance.
|
|
438
|
+
const { uncovered: added, failed } = useAllowances(ctx, r, ref, increasesOnKnownKeys(refCounts, m.counts));
|
|
439
|
+
if (!added.length) return failed;
|
|
440
|
+
const n = added.reduce((a, d) => a + d.now - d.base, 0);
|
|
441
|
+
say(`FAIL ${r.id}: under the definition on ${label} this change adds ${n}: ${describe(added)}`);
|
|
442
|
+
say(` Why the rule exists: ${r.why}`);
|
|
443
|
+
say(` Do: remove the new occurrences. Changing a ratchet's definition cannot hide them.`);
|
|
444
|
+
sayHowToAllow(ctx, r, ref, added);
|
|
445
|
+
printLocations(m, ctx.changed, say);
|
|
446
|
+
printShow(refDef, added, say);
|
|
447
|
+
return true;
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
/** The allowances for one ratchet key. */
|
|
451
|
+
function allowancesOn(allowances: readonly Allowance[], ratchet: string, key: string): Allowance[] {
|
|
452
|
+
return allowances.filter((x) => x.ratchet === ratchet && x.key === key);
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
/** Sum of the allowances for one ratchet key. */
|
|
456
|
+
function allowanceFor(allowances: readonly Allowance[], ratchet: string, key: string): number {
|
|
457
|
+
return allowancesOn(allowances, ratchet, key).reduce((a, x) => a + x.by, 0);
|
|
458
|
+
}
|
|
459
|
+
|
|
460
|
+
/**
|
|
461
|
+
* Rises on keys the ref knows, set against the ref's allowances. A rise of n is allowed when the
|
|
462
|
+
* ref's allowances for that key sum to at least n; it is then used, so this branch's manifest may
|
|
463
|
+
* hold at most (ref's sum - n) for the key. Prints ALLOWED for each allowed rise and FAIL for an
|
|
464
|
+
* allowance kept after use. Returns the rises no allowance covers, for the caller to report.
|
|
465
|
+
*/
|
|
466
|
+
function useAllowances(ctx: Ctx, r: Ratchet, ref: RefState, rises: readonly Delta[]): { uncovered: Delta[]; failed: boolean } {
|
|
467
|
+
const { say } = ctx;
|
|
468
|
+
const uncovered: Delta[] = [];
|
|
469
|
+
let failed = false;
|
|
470
|
+
for (const d of rises) {
|
|
471
|
+
const n = d.now - d.base;
|
|
472
|
+
const allowed = allowanceFor(ref.allowances, r.id, d.key);
|
|
473
|
+
if (n > allowed) { uncovered.push(d); continue; }
|
|
474
|
+
const left = allowed - n;
|
|
475
|
+
const kept = allowanceFor(ctx.manifest.allowances, r.id, d.key);
|
|
476
|
+
if (kept > left) {
|
|
477
|
+
failed = true;
|
|
478
|
+
say(`FAIL ${r.id}: ${describe([d])} uses an allowance on ${ref.label}, but this branch still holds ${kept} for ${keyName(d.key)} in ${MANIFEST_FILE}`);
|
|
479
|
+
say(left === 0
|
|
480
|
+
? ` Do: delete the used allowance (ratchet: ${r.id}, key: ${d.key}) from ${MANIFEST_FILE}, so it cannot be used again.`
|
|
481
|
+
: ` Do: lower the allowance (ratchet: ${r.id}, key: ${d.key}) in ${MANIFEST_FILE} to by: ${left}, so the used part cannot be used again.`);
|
|
482
|
+
continue;
|
|
483
|
+
}
|
|
484
|
+
const whys = allowancesOn(ref.allowances, r.id, d.key).map((x) => x.why).join('; ');
|
|
485
|
+
say(`ALLOWED ${r.id}: ${describe([d])} by an allowance on ${ref.label}: ${whys}`);
|
|
486
|
+
}
|
|
487
|
+
return { uncovered, failed };
|
|
488
|
+
}
|
|
489
|
+
|
|
490
|
+
const keyName = (key: string) => (key === TOTAL_KEY ? 'the count' : `key ${key}`);
|
|
491
|
+
|
|
492
|
+
/** After a rise no allowance covers: what the ref allows today, and how to get an allowance. */
|
|
493
|
+
function sayHowToAllow(ctx: Ctx, r: Ratchet, ref: RefState, uncovered: readonly Delta[]): void {
|
|
494
|
+
for (const d of uncovered) {
|
|
495
|
+
const allowed = allowanceFor(ref.allowances, r.id, d.key);
|
|
496
|
+
if (allowed > 0) ctx.say(` ${ref.label} allows ${keyName(d.key)} to rise by ${allowed}; this change raises it by ${d.now - d.base}.`);
|
|
497
|
+
}
|
|
498
|
+
const keys = [...new Set(uncovered.map((d) => d.key))];
|
|
499
|
+
const keyField = keys.length === 1 && keys[0] === TOTAL_KEY ? '' : `, key: ${keys.join(' | ')}`;
|
|
500
|
+
ctx.say(` If the new occurrence is justified: first merge a merge request that only adds an allowance to ${MANIFEST_FILE} `
|
|
501
|
+
+ `(allowances: ratchet: ${r.id}${keyField}, by: <n>, why: <reason>), which a person reviews. `
|
|
502
|
+
+ `Then, in this change, raise the baseline with ${ctx.manifest.cli} ratchet --update --allow-increase --only ${r.id} and delete the allowance.`);
|
|
503
|
+
}
|
|
504
|
+
|
|
505
|
+
/** Ratchets at the ref that are gone here must be listed under `retired`. Returns the failure count. */
|
|
506
|
+
function checkRemoved(ctx: Ctx, label: string, refIds: ReadonlySet<string>): number {
|
|
507
|
+
const here = new Set(ctx.manifest.ratchets.map((r) => r.id));
|
|
508
|
+
const retired = new Map(ctx.manifest.retired.map((r) => [r.id, r.why]));
|
|
509
|
+
let failed = 0;
|
|
510
|
+
for (const id of [...refIds].sort()) {
|
|
511
|
+
if (here.has(id)) continue;
|
|
512
|
+
const why = retired.get(id);
|
|
513
|
+
if (why !== undefined) {
|
|
514
|
+
ctx.say(`RETIRED ${id}: ${why}`);
|
|
515
|
+
continue;
|
|
516
|
+
}
|
|
517
|
+
failed++;
|
|
518
|
+
ctx.say(`FAIL removed ratchet ${id}: it exists in ${MANIFEST_FILE} at ${label} but not here.`);
|
|
519
|
+
ctx.say(` Do: put it back, or retire it on purpose: list it under retired: in ${MANIFEST_FILE} with an id and a why (a reviewed change to the factory).`);
|
|
520
|
+
}
|
|
521
|
+
return failed;
|
|
522
|
+
}
|
package/src/cli/risk.ts
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { changedFiles, mergeBase, resolveCommit, showFile } from './git.js';
|
|
4
|
+
import { compileGlobs, globProblem } from './glob.js';
|
|
5
|
+
import { EXIT_OK, EXIT_RISK, FactoryError, type Io } from './io.js';
|
|
6
|
+
import { MANIFEST_FILE, parseYaml } from './manifest.js';
|
|
7
|
+
|
|
8
|
+
export interface RiskOptions {
|
|
9
|
+
base: string;
|
|
10
|
+
/** A commit to compare; omitted means the working tree (committed or not, plus untracked files). */
|
|
11
|
+
head?: string;
|
|
12
|
+
json?: boolean;
|
|
13
|
+
failOnRisk?: boolean;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export interface RiskReport {
|
|
17
|
+
base: string;
|
|
18
|
+
head: string;
|
|
19
|
+
merge_base: string;
|
|
20
|
+
zones_from: 'base' | 'working-copy';
|
|
21
|
+
files: string[];
|
|
22
|
+
zones: Record<string, string[]>;
|
|
23
|
+
unzoned: string[];
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Reads risk_zones from manifest text, leniently: only that section has to be well formed. */
|
|
27
|
+
function zonesFrom(text: string, source: string): Record<string, string[]> {
|
|
28
|
+
const raw = parseYaml(text, source);
|
|
29
|
+
const zones = (raw as Record<string, unknown> | null)?.risk_zones;
|
|
30
|
+
if (zones === undefined) return {};
|
|
31
|
+
if (typeof zones !== 'object' || zones === null || Array.isArray(zones)) throw new FactoryError(`${source}: risk_zones must be a mapping of zone name to glob list`);
|
|
32
|
+
const out: Record<string, string[]> = {};
|
|
33
|
+
for (const [name, list] of Object.entries(zones)) {
|
|
34
|
+
if (!Array.isArray(list) || list.some((g) => typeof g !== 'string' || globProblem(g) !== null)) {
|
|
35
|
+
throw new FactoryError(`${source}: risk_zones.${name} must be a list of valid glob patterns`);
|
|
36
|
+
}
|
|
37
|
+
out[name] = list as string[];
|
|
38
|
+
}
|
|
39
|
+
return out;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export function classify(files: readonly string[], zones: Record<string, string[]>): { zones: Record<string, string[]>; unzoned: string[] } {
|
|
43
|
+
const hit: Record<string, string[]> = {};
|
|
44
|
+
const zoned = new Set<string>();
|
|
45
|
+
for (const [name, globs] of Object.entries(zones)) {
|
|
46
|
+
const match = compileGlobs(globs);
|
|
47
|
+
const inZone = files.filter(match);
|
|
48
|
+
if (inZone.length) {
|
|
49
|
+
hit[name] = inZone;
|
|
50
|
+
inZone.forEach((f) => zoned.add(f));
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
return { zones: hit, unzoned: files.filter((f) => !zoned.has(f)) };
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* `factory risk`: which risk zones a change touches. The zones come from the
|
|
58
|
+
* manifest at the base ref, never the working copy, so a change cannot take
|
|
59
|
+
* itself out of a zone by editing factory.yaml.
|
|
60
|
+
*/
|
|
61
|
+
export function runRisk(root: string, opts: RiskOptions, io: Io): number {
|
|
62
|
+
const baseCommit = resolveCommit(root, opts.base);
|
|
63
|
+
const headCommit = resolveCommit(root, opts.head || 'HEAD');
|
|
64
|
+
const mb = mergeBase(root, baseCommit, headCommit);
|
|
65
|
+
const files = changedFiles(root, mb, opts.head ? headCommit : undefined);
|
|
66
|
+
|
|
67
|
+
const notes: string[] = [];
|
|
68
|
+
let zones: Record<string, string[]>;
|
|
69
|
+
let from: RiskReport['zones_from'] = 'base';
|
|
70
|
+
const atBase = showFile(root, baseCommit, MANIFEST_FILE);
|
|
71
|
+
if (atBase !== null) {
|
|
72
|
+
zones = zonesFrom(atBase, `${MANIFEST_FILE} at ${opts.base}`);
|
|
73
|
+
} else {
|
|
74
|
+
from = 'working-copy';
|
|
75
|
+
const path = join(root, MANIFEST_FILE);
|
|
76
|
+
zones = existsSync(path) ? zonesFrom(readFileSync(path, 'utf8'), MANIFEST_FILE) : {};
|
|
77
|
+
notes.push(`${MANIFEST_FILE} does not exist at ${opts.base}: the risk zones come from the working copy, which this change can edit.`);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
const { zones: hit, unzoned } = classify(files, zones);
|
|
81
|
+
const report: RiskReport = {
|
|
82
|
+
base: opts.base, head: opts.head ?? 'working tree', merge_base: mb, zones_from: from, files, zones: hit, unzoned,
|
|
83
|
+
};
|
|
84
|
+
const risky = Object.keys(hit).length > 0;
|
|
85
|
+
|
|
86
|
+
if (opts.json) {
|
|
87
|
+
io.out(`${JSON.stringify({ ...report, notes }, null, 2)}\n`);
|
|
88
|
+
} else {
|
|
89
|
+
io.out(`Changes from merge-base ${mb.slice(0, 12)} (${opts.base}) to ${report.head}: ${files.length} file${files.length === 1 ? '' : 's'}\n`);
|
|
90
|
+
io.out(`Risk zones read from ${from === 'base' ? `${MANIFEST_FILE} at ${opts.base}` : `the working copy's ${MANIFEST_FILE}`}.\n`);
|
|
91
|
+
for (const n of notes) io.out(`NOTE ${n}\n`);
|
|
92
|
+
if (risky) {
|
|
93
|
+
io.out(`\nRisk zones touched (${Object.keys(hit).length}): a person must review these files before merge.\n`);
|
|
94
|
+
for (const [name, list] of Object.entries(hit)) {
|
|
95
|
+
io.out(` ${name} (${list.length})\n`);
|
|
96
|
+
for (const f of list) io.out(` ${f}\n`);
|
|
97
|
+
}
|
|
98
|
+
} else {
|
|
99
|
+
io.out('\nNo risk zone touched.\n');
|
|
100
|
+
}
|
|
101
|
+
io.out(`\nOutside every zone: ${unzoned.length} file${unzoned.length === 1 ? '' : 's'}.\n`);
|
|
102
|
+
}
|
|
103
|
+
return risky && opts.failOnRisk ? EXIT_RISK : EXIT_OK;
|
|
104
|
+
}
|