repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(the-system): add read-only project doctor

835b2005a5a418dbf22dbb66120f2d7ea89c732f

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (3)

extensions/the-system/__tests__/doctor.test.ts

Added
new file mode 100644
1 +import assert from "node:assert/strict";
2 +import {
3 + mkdirSync,
4 + mkdtempSync,
5 + readFileSync,
6 + readdirSync,
7 + rmSync,
8 + statSync,
9 + writeFileSync,
10 +} from "node:fs";
11 +import { tmpdir } from "node:os";
12 +import path from "node:path";
13 +import { afterEach, describe, it } from "vitest";
14 +import { runDoctor } from "../doctor.ts";
16 +const roots: string[] = [];
17 +const temporaryRoot = () => {
18 + const root = mkdtempSync(path.join(tmpdir(), "the-system-doctor-"));
19 + roots.push(root);
20 + mkdirSync(path.join(root, ".git"));
21 + return root;
22 +};
23 +const write = (root: string, relative: string, content = "") => {
24 + const target = path.join(root, relative);
25 + mkdirSync(path.dirname(target), { recursive: true });
26 + writeFileSync(target, content, "utf8");
27 +};
28 +const metadata = (value: object) =>
29 + `<script type="application/json" id="system-meta">${JSON.stringify(value)}</script>`;
30 +const html = (meta: object, body = "<p>contract</p>") => `<!doctype html>
31 +<html lang="en">
32 +<head>
33 +<meta charset="utf-8">
34 +<meta name="viewport" content="width=device-width, initial-scale=1">
35 +<title>Fixture</title>
36 +<link rel="stylesheet" href="../system.css">
37 +${metadata(meta)}
38 +</head>
39 +<body><header><h1>Fixture</h1></header><main><section>${body}</section></main></body>
40 +</html>`;
41 +const validSystem = (root: string) => {
42 + for (const directory of ["specs", "roadmaps", "plans", "issues", "research"])
43 + mkdirSync(path.join(root, ".system", directory), { recursive: true });
44 + for (const file of ["SYSTEM.md", "MISSION.md", "RULES.md"])
45 + write(root, `.system/${file}`, `# ${file}\n`);
46 + write(
47 + root,
48 + ".system/config.json",
49 + '{"prefix":"PX","schemaVersion":1,"styleVersion":1}',
50 + );
51 + write(root, ".system/system.css", "/* The System styleVersion: 1 */\n");
52 +};
54 +afterEach(() => {
55 + for (const root of roots.splice(0))
56 + rmSync(root, { recursive: true, force: true });
57 +});
59 +describe("system doctor", () => {
60 + it("reports every required path in stable path/code order", () => {
61 + const root = temporaryRoot();
62 + const result = runDoctor(path.join(root, "nested"));
64 + assert.equal(result.root, root);
65 + assert.equal(result.exitCode, 1);
66 + assert.deepEqual(
67 + result.diagnostics.map(({ code, path }) => `${path} ${code}`),
68 + [
69 + ".system filesystem.missing",
70 + ".system/MISSION.md filesystem.missing",
71 + ".system/RULES.md filesystem.missing",
72 + ".system/SYSTEM.md filesystem.missing",
73 + ".system/config.json filesystem.missing",
74 + ".system/issues filesystem.missing",
75 + ".system/plans filesystem.missing",
76 + ".system/research filesystem.missing",
77 + ".system/roadmaps filesystem.missing",
78 + ".system/specs filesystem.missing",
79 + ".system/system.css filesystem.missing",
80 + ],
81 + );
82 + });
84 + it("combines machine-state, kernel, mockup, and test-reference findings", () => {
85 + const root = temporaryRoot();
86 + validSystem(root);
87 + write(
88 + root,
89 + ".system/config.json",
90 + '{"prefix":"PX","schemaVersion":2,"styleVersion":2}',
91 + );
92 + write(root, ".system/system.css", "/* The System styleVersion: 1 */\n");
93 + write(
94 + root,
95 + ".system/specs/PX-SPEC-001-contract.html",
96 + html({ id: "PX-SPEC-001", type: "spec" }),
97 + );
98 + write(
99 + root,
100 + ".system/plans/PX-PLAN-001-work.html",
101 + html({ id: "PX-PLAN-001", type: "plan", spec: "PX-SPEC-999" }),
102 + );
103 + write(
104 + root,
105 + ".system/specs/PX-SPEC-404-gone-mockup-empty.html",
106 + "<!doctype html><title>asset</title>",
107 + );
108 + write(
109 + root,
110 + "tests/contract.test.ts",
111 + "// SYSTEM-SPEC: PX-SPEC-001\n// SYSTEM-SPEC: PX-SPEC-999\n",
112 + );
114 + const result = runDoctor(root);
116 + assert.deepEqual(result.references, [
117 + { path: "tests/contract.test.ts", spec: "PX-SPEC-001" },
118 + { path: "tests/contract.test.ts", spec: "PX-SPEC-999" },
119 + ]);
120 + assert.deepEqual(
121 + result.diagnostics.map(({ code, path }) => `${path} ${code}`),
123 + ".system/config.json config.schema-outdated",
124 + ".system/config.json config.style-outdated",
125 + ".system/plans/PX-PLAN-001-work.html graph.dangling-reference",
126 + ".system/specs/PX-SPEC-404-gone-mockup-empty.html mockup.orphaned",
127 + ".system/system.css css.version-mismatch",
128 + "tests/contract.test.ts test.dangling-reference",
129 + ],
130 + );
131 + assert.equal(result.exitCode, 1);
132 + });
134 + it("returns green for a complete system and ignores symlinks and non-HTML files", () => {
135 + const root = temporaryRoot();
136 + validSystem(root);
137 + write(
138 + root,
139 + ".system/specs/PX-SPEC-001-contract.html",
140 + html({ id: "PX-SPEC-001", type: "spec" }),
141 + );
142 + write(root, ".system/specs/notes.txt", "not authored HTML");
143 + write(root, "src/value.ts", "export const value = 1;\n");
145 + const result = runDoctor(root);
147 + assert.deepEqual(result.diagnostics, []);
148 + assert.deepEqual(result.references, []);
149 + assert.equal(result.exitCode, 0);
150 + });
151 +});

extensions/the-system/doctor.ts

Added
new file mode 100644
1 +import { readFileSync, readdirSync, statSync } from "node:fs";
2 +import path from "node:path";
3 +import {
4 + type Diagnostic,
5 + discoverProjectRoot,
6 + indexDocuments,
7 + parseSystemConfig,
8 + SCHEMA_VERSION,
9 + STYLE_VERSION,
10 + SystemDocumentError,
11 + validateAuthoredHtml,
12 +} from "./documents.ts";
14 +export type TestReference = Readonly<{ path: string; spec: string }>;
15 +export type DoctorResult = Readonly<{
16 + root: string;
17 + diagnostics: readonly Diagnostic[];
18 + references: readonly TestReference[];
19 + exitCode: 0 | 1;
20 +}>;
22 +const SYSTEM_DIRECTORIES = [
23 + ".system",
24 + ".system/specs",
25 + ".system/roadmaps",
26 + ".system/plans",
27 + ".system/issues",
28 + ".system/research",
29 +] as const;
30 +const SYSTEM_FILES = [
31 + ".system/config.json",
32 + ".system/system.css",
33 + ".system/SYSTEM.md",
34 + ".system/MISSION.md",
35 + ".system/RULES.md",
36 +] as const;
37 +const DOCUMENT_DIRECTORIES = [
38 + "specs",
39 + "roadmaps",
40 + "plans",
41 + "issues",
42 + "research",
43 +] as const;
44 +const TEST_DIRECTORIES = ["test", "tests", "__tests__"] as const;
45 +const TEST_REFERENCE = /SYSTEM-SPEC:\s*([A-Z][A-Z0-9]{1,7}-SPEC-[0-9]{3,})/g;
46 +const MOCKUP = /^(.*)-mockup-[a-z0-9]+(?:-[a-z0-9]+)*\.html$/;
48 +const diagnostic = (code: string, path: string, message: string): Diagnostic => ({
49 + code,
50 + path,
51 + message,
52 +});
53 +const compareText = (left: string, right: string) =>
54 + left < right ? -1 : left > right ? 1 : 0;
55 +const compareDiagnostics = (left: Diagnostic, right: Diagnostic) =>
56 + compareText(left.path, right.path) ||
57 + compareText(left.code, right.code) ||
58 + compareText(left.message, right.message);
59 +const relativePath = (root: string, target: string) =>
60 + path.relative(root, target).split(path.sep).join("/");
61 +const isDirectory = (target: string) => {
62 + try {
63 + return statSync(target, { throwIfNoEntry: false })?.isDirectory() === true;
64 + } catch {
65 + return false;
66 + }
67 +};
68 +const isFile = (target: string) => {
69 + try {
70 + return statSync(target, { throwIfNoEntry: false })?.isFile() === true;
71 + } catch {
72 + return false;
73 + }
74 +};
76 +const collectDocumentSources = (root: string) => {
77 + const sources: { path: string; html: string }[] = [];
78 + const mockups: string[] = [];
79 + for (const directory of DOCUMENT_DIRECTORIES) {
80 + const absoluteDirectory = path.join(root, ".system", directory);
81 + if (!isDirectory(absoluteDirectory)) continue;
82 + for (const entry of readdirSync(absoluteDirectory, { withFileTypes: true })) {
83 + if (!entry.isFile() || !entry.name.endsWith(".html")) continue;
84 + const relative = `.system/${directory}/${entry.name}`;
85 + if (directory === "specs" && MOCKUP.test(entry.name)) {
86 + mockups.push(relative);
87 + continue;
88 + }
89 + sources.push({
90 + path: relative,
91 + html: readFileSync(path.join(absoluteDirectory, entry.name), "utf8"),
92 + });
93 + }
94 + }
95 + return {
96 + sources: sources.sort((left, right) => left.path.localeCompare(right.path)),
97 + mockups: mockups.sort(),
98 + };
99 +};
101 +const collectTestReferences = (root: string): TestReference[] => {
102 + const references: TestReference[] = [];
103 + const visited = new Set<string>();
104 + const scan = (directory: string) => {
105 + const resolved = path.resolve(directory);
106 + if (visited.has(resolved) || !isDirectory(resolved)) return;
107 + visited.add(resolved);
108 + for (const entry of readdirSync(resolved, { withFileTypes: true }).sort(
109 + (left, right) => left.name.localeCompare(right.name),
110 + )) {
111 + if ([".git", ".jj", ".system", "node_modules"].includes(entry.name))
112 + continue;
113 + const target = path.join(resolved, entry.name);
114 + if (entry.isDirectory()) {
115 + scan(target);
116 + continue;
118 + if (!entry.isFile()) continue;
119 + const source = readFileSync(target, "utf8");
120 + for (const match of source.matchAll(TEST_REFERENCE))
121 + references.push({ path: relativePath(root, target), spec: match[1] });
123 + };
124 + for (const directory of TEST_DIRECTORIES) scan(path.join(root, directory));
125 + return references.sort(
126 + (left, right) =>
127 + left.path.localeCompare(right.path) || left.spec.localeCompare(right.spec),
128 + );
131 +export function runDoctor(cwd: string): DoctorResult {
132 + let root: string;
133 + try {
134 + root = discoverProjectRoot(cwd);
135 + } catch (error) {
136 + const value = error as SystemDocumentError;
137 + const diagnostics = [diagnostic(value.code, path.resolve(cwd), value.message)];
138 + return { root: path.resolve(cwd), diagnostics, references: [], exitCode: 1 };
141 + const diagnostics: Diagnostic[] = [];
142 + for (const relative of SYSTEM_DIRECTORIES) {
143 + const target = path.join(root, relative);
144 + if (!isDirectory(target))
145 + diagnostics.push(
146 + diagnostic("filesystem.missing", relative, `Missing directory ${relative}`),
147 + );
149 + for (const relative of SYSTEM_FILES) {
150 + const target = path.join(root, relative);
151 + if (!isFile(target))
152 + diagnostics.push(
153 + diagnostic("filesystem.missing", relative, `Missing file ${relative}`),
154 + );
157 + let prefix: string | undefined;
158 + let configuredStyleVersion = STYLE_VERSION;
159 + const configPath = path.join(root, ".system/config.json");
160 + if (isFile(configPath)) {
161 + try {
162 + const config = parseSystemConfig(readFileSync(configPath, "utf8"));
163 + prefix = config.prefix;
164 + configuredStyleVersion = config.styleVersion;
165 + if (config.schemaVersion !== SCHEMA_VERSION)
166 + diagnostics.push(
167 + diagnostic(
168 + "config.schema-outdated",
169 + ".system/config.json",
170 + `Schema version ${config.schemaVersion}; installed ${SCHEMA_VERSION}`,
171 + ),
172 + );
173 + if (config.styleVersion !== STYLE_VERSION)
174 + diagnostics.push(
175 + diagnostic(
176 + "config.style-outdated",
177 + ".system/config.json",
178 + `Style version ${config.styleVersion}; installed ${STYLE_VERSION}`,
179 + ),
180 + );
181 + } catch (error) {
182 + const value = error as SystemDocumentError;
183 + diagnostics.push(
184 + diagnostic(value.code, ".system/config.json", value.message),
185 + );
189 + const cssPath = path.join(root, ".system/system.css");
190 + if (isFile(cssPath)) {
191 + const css = readFileSync(cssPath, "utf8");
192 + const version = /The System styleVersion:\s*([0-9]+)/.exec(css)?.[1];
193 + if (!version)
194 + diagnostics.push(
195 + diagnostic(
196 + "css.version",
197 + ".system/system.css",
198 + "Missing The System styleVersion marker",
199 + ),
200 + );
201 + else if (Number(version) !== configuredStyleVersion)
202 + diagnostics.push(
203 + diagnostic(
204 + "css.version-mismatch",
205 + ".system/system.css",
206 + `Stylesheet version ${version}; configured ${configuredStyleVersion}`,
207 + ),
208 + );
211 + const { sources, mockups } = collectDocumentSources(root);
212 + let specIds = new Set<string>();
213 + if (prefix) {
214 + const index = indexDocuments(sources, prefix);
215 + diagnostics.push(...index.diagnostics);
216 + specIds = new Set(
217 + index.documents
218 + .filter((document) => document.metadata.type === "spec")
219 + .map((document) => document.metadata.id),
220 + );
221 + } else {
222 + for (const source of sources)
223 + diagnostics.push(...validateAuthoredHtml(source.path, source.html));
226 + const sourcePaths = new Set(sources.map((source) => source.path));
227 + for (const mockup of mockups) {
228 + const filename = path.posix.basename(mockup);
229 + const owner = MOCKUP.exec(filename)?.[1];
230 + const ownerPath = `.system/specs/${owner}.html`;
231 + if (!owner || !sourcePaths.has(ownerPath))
232 + diagnostics.push(
233 + diagnostic(
234 + "mockup.orphaned",
235 + mockup,
236 + `Mockup owner is missing: ${ownerPath}`,
237 + ),
238 + );
241 + const references = collectTestReferences(root);
242 + for (const reference of references)
243 + if (prefix && !specIds.has(reference.spec))
244 + diagnostics.push(
245 + diagnostic(
246 + "test.dangling-reference",
247 + reference.path,
248 + `Test references missing ${reference.spec}`,
249 + ),
250 + );
252 + diagnostics.sort(compareDiagnostics);
253 + return {
254 + root,
255 + diagnostics,
256 + references,
257 + exitCode: diagnostics.length === 0 ? 0 : 1,
258 + };

mise.toml

Modified
50 50 npm run test --{% for arg in usage.args %} "{{ arg }}"{% endfor %}
53 +[tasks.typecheck]
54 +description = "Typecheck TypeScript"
55 +depends = ["install"]
56 +run = "npm run typecheck"
53 58 [tasks.bench-q]
54 59 description = "Run q heuristic extractor benchmark"
55 60 depends = ["install"]