Repository navigation
Expand file tree
/
Copy pathreadme-sample.ts
More file actions
193 lines (177 loc) · 7.55 KB
/
Copy pathreadme-sample.ts
File metadata and controls
193 lines (177 loc) · 7.55 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
#!/usr/bin/env bun
// Enforce, on `x verify`'s `manifest` step, that the root README's code sample IS the file it
// quotes. A hand-written sample is the first code a stranger reads and the first to rot: the one this
// replaced named fields no action takes. A `<!-- readme-sample: <path> -->` marker binds the fence
// under it to a real file; `--write` rewrites the fence from the file.
//
// bun run scripts/readme-sample.ts [--json] [--write]
// why: Bun exposes no path-join primitive; Bun.file takes one already joined.
import { join } from 'node:path';
import { flagBool, parseScriptArgs } from './lib/args';
import type { Finding } from './lib/log';
import { report } from './lib/log';
import { repoRoot } from './lib/run';
export const README_FILE = 'README.md';
export const SAMPLE_MARKER = 'readme-sample';
export const WRITE_COMMAND = 'bun run scripts/readme-sample.ts --write';
const MARKER = /^<!--\s*readme-sample:\s*(\S+)\s*-->\s*$/;
const OPEN = /^```[A-Za-z0-9+#-]*\s*$/;
const CLOSE = /^```\s*$/;
/** One marker, and the fence under it — `start`/`end` are the fence's own lines, 0-based. */
export interface Sample {
readonly file: string;
readonly markerLine: number;
readonly code: readonly string[] | undefined;
readonly start: number;
readonly end: number;
}
/**
* What a README quotes of a file: everything below its leading `//` header. The header states the
* file's responsibility to a reader of the repository; quoted on the front page it is noise, and
* quoting from the first statement keeps the sample short without hand-trimming it.
*/
export function sampleBody(source: string): readonly string[] {
const lines = source.split('\n');
let from = 0;
while (from < lines.length && /^\s*(\/\/.*)?$/.test(lines[from] ?? '')) from += 1;
let to = lines.length;
while (to > from && (lines[to - 1] ?? '').trim() === '') to -= 1;
return lines.slice(from, to);
}
/** Every marker, in order. A marker binds the fence on the very next line, and nothing else. */
export function readSamples(markdown: string): readonly Sample[] {
const lines = markdown.split('\n');
const samples: Sample[] = [];
for (let index = 0; index < lines.length; index += 1) {
const marked = MARKER.exec(lines[index] ?? '');
if (marked === null) continue;
const file = marked[1] ?? '';
const start = index + 1;
if (!OPEN.test(lines[start] ?? '')) {
samples.push({ file, markerLine: index, code: undefined, start, end: start });
continue;
}
let end = start + 1;
while (end < lines.length && !CLOSE.test(lines[end] ?? '')) end += 1;
samples.push({ file, markerLine: index, code: lines.slice(start + 1, end), start, end });
}
return samples;
}
/** `unmarked` is the vacuous green: a README with no marker would make this rule check nothing. */
export type SampleGapKind = 'drift' | 'missing' | 'unfenced' | 'unmarked';
export interface SampleGap {
readonly kind: SampleGapKind;
readonly file: string;
/** 1-based README line of the marker. */
readonly line: number;
}
export type ReadFile = (path: string) => string | undefined;
/** Pure over the markdown and a reader, so every negative case is a fixture. */
export function checkSamples(markdown: string, read: ReadFile): readonly SampleGap[] {
const samples = readSamples(markdown);
if (samples.length === 0) return [{ kind: 'unmarked', file: '', line: 0 }];
const gaps: SampleGap[] = [];
for (const sample of samples) {
const line = sample.markerLine + 1;
if (sample.code === undefined) {
gaps.push({ kind: 'unfenced', file: sample.file, line });
continue;
}
const source = read(sample.file);
if (source === undefined) {
gaps.push({ kind: 'missing', file: sample.file, line });
continue;
}
if (sample.code.join('\n') !== sampleBody(source).join('\n')) {
gaps.push({ kind: 'drift', file: sample.file, line });
}
}
return gaps;
}
/** Each bound fence replaced by its file's body; a fence whose file is gone is left as it was. */
export function writeSamples(markdown: string, read: ReadFile): string {
const lines = markdown.split('\n');
for (const sample of [...readSamples(markdown)].reverse()) {
const source = read(sample.file);
if (sample.code === undefined || source === undefined) continue;
lines.splice(sample.start + 1, sample.end - sample.start - 1, ...sampleBody(source));
}
return lines.join('\n');
}
const FINDINGS = {
drift: (gap) => ({
code: 'X_README_SAMPLE_DRIFT',
cause: `${README_FILE}:${gap.line} quotes ${gap.file}, and the fence under it is not that file's code any more`,
fix: WRITE_COMMAND,
at: `${README_FILE}:${gap.line}`,
}),
missing: (gap) => ({
code: 'X_README_SAMPLE_DRIFT',
cause: `${README_FILE}:${gap.line} quotes ${gap.file}, which does not exist`,
fix: `grep -n readme-sample README.md # point that marker at a file that exists under examples/dummy`,
at: `${README_FILE}:${gap.line}`,
}),
unfenced: (gap) => ({
code: 'X_README_SAMPLE_DRIFT',
cause: `${README_FILE}:${gap.line} names ${gap.file} as a sample, with no code fence on the next line`,
fix: `grep -n readme-sample README.md # put a fence directly under that marker, then: ${WRITE_COMMAND}`,
at: `${README_FILE}:${gap.line}`,
}),
unmarked: () => ({
code: 'X_README_SAMPLE_DRIFT',
cause: `${README_FILE} carries no readme-sample marker, so its code sample is hand-written and checked by nothing`,
fix: "grep -n '^```' README.md # put <!-- readme-sample: examples/dummy/apps/web/app/runs/actions/cancel-run.ts --> above the sample fence, then: bun run scripts/readme-sample.ts --write",
at: README_FILE,
}),
} satisfies Readonly<Record<SampleGapKind, (gap: SampleGap) => Finding>>;
/** A `switch`, not `FINDINGS[gap.kind]`: a computed read of a Record trips `proto-index`. */
export const sampleFindingFor = (gap: SampleGap): Finding => {
switch (gap.kind) {
case 'drift':
return FINDINGS.drift(gap);
case 'missing':
return FINDINGS.missing(gap);
case 'unfenced':
return FINDINGS.unfenced(gap);
case 'unmarked':
return FINDINGS.unmarked();
}
};
/** Every file the markers name, read once — so the check above stays pure and synchronous. */
async function readerAt(root: string, markdown: string): Promise<ReadFile> {
const read = new Map<string, string>();
for (const sample of readSamples(markdown)) {
const file = Bun.file(join(root, sample.file));
if (await file.exists()) read.set(sample.file, await file.text());
}
return (path) => read.get(path);
}
/** A root with no README makes no sample claim — a fixture tree, never this repository's. */
export async function readmeSampleFindings(root: string): Promise<readonly Finding[]> {
const readme = Bun.file(join(root, README_FILE));
if (!(await readme.exists())) return [];
const markdown = await readme.text();
return checkSamples(markdown, await readerAt(root, markdown)).map(sampleFindingFor);
}
if (import.meta.main) {
const args = parseScriptArgs(Bun.argv.slice(2));
const root = repoRoot();
if (flagBool(args, 'write')) {
const path = join(root, README_FILE);
const markdown = await Bun.file(path).text();
await Bun.write(path, writeSamples(markdown, await readerAt(root, markdown)));
}
const findings = await readmeSampleFindings(root);
report(
{
ok: findings.length === 0,
script: 'readme-sample',
summary:
findings.length === 0
? `${README_FILE}'s code sample is the file it quotes`
: `${findings.length} README sample(s) differ from their file`,
findings,
},
args.json,
);
}