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
Addednew file mode 100644 1 +import assert
from "node:assert/strict";
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-"));
20 + mkdirSync(path.
join(
root,
".git"));
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");
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> 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"> 39 +<body><header><h1>Fixture</h1></header><main><section>${body}</section></main></body> 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`);
48 + ".system/config.json",
49 + '{"prefix":"PX","schemaVersion":1,"styleVersion":1}',
51 + write(
root,
".system/system.css",
"/* The System styleVersion: 1 */\n");
55 + for (
const root
of roots.
splice(
0))
56 + rmSync(
root, { recursive:
true, force:
true });
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);
67 + result.diagnostics.
map(({ code, path })
=> `${path} ${code}`),
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",
84 + it(
"combines machine-state, kernel, mockup, and test-reference findings", ()
=> {
85 + const root
= temporaryRoot();
89 + ".system/config.json",
90 + '{"prefix":"PX","schemaVersion":2,"styleVersion":2}',
92 + write(
root,
".system/system.css",
"/* The System styleVersion: 1 */\n");
95 + ".system/specs/PX-SPEC-001-contract.html",
96 + html({ id:
"PX-SPEC-001", type:
"spec" }),
100 + ".system/plans/PX-PLAN-001-work.html",
101 + html({ id:
"PX-PLAN-001", type:
"plan", spec:
"PX-SPEC-999" }),
105 + ".system/specs/PX-SPEC-404-gone-mockup-empty.html",
106 + "<!doctype html><title>asset</title>",
110 + "tests/contract.test.ts",
111 + "// SYSTEM-SPEC: PX-SPEC-001\n// SYSTEM-SPEC: PX-SPEC-999\n",
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" },
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",
131 + assert.
equal(result.exitCode,
1);
134 + it(
"returns green for a complete system and ignores symlinks and non-HTML files", ()
=> {
135 + const root
= temporaryRoot();
139 + ".system/specs/PX-SPEC-001-contract.html",
140 + html({ id:
"PX-SPEC-001", type:
"spec" }),
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);
extensions/the-system/doctor.ts
Addednew file mode 100644 1 +import { readFileSync, readdirSync, statSync }
from "node:fs";
2 +import path
from "node:path";
10 + SystemDocumentError,
11 + validateAuthoredHtml,
12 +}
from "./documents.ts";
14 +export type TestReference = Readonly<{ path
: string; spec
: string }>;
15 +export type DoctorResult = Readonly<{
17 + diagnostics
: readonly Diagnostic[];
18 + references
: readonly TestReference[];
22 +const SYSTEM_DIRECTORIES
= [
30 +const SYSTEM_FILES
= [
31 + ".system/config.json",
32 + ".system/system.css",
33 + ".system/SYSTEM.md",
34 + ".system/MISSION.md",
37 +const DOCUMENT_DIRECTORIES
= [
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 => ({
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)
=> {
63 + return statSync(target, { throwIfNoEntry:
false })?.
isDirectory()
=== true;
68 +const isFile = (target
: string)
=> {
70 + return statSync(target, { throwIfNoEntry:
false })?.
isFile()
=== true;
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);
91 + html:
readFileSync(path.
join(absoluteDirectory, entry.
name),
"utf8"),
96 + sources: sources.
sort((left, right)
=> left.path.
localeCompare(right.path)),
97 + mockups: mockups.
sort(),
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),
111 + if ([
".git",
".jj",
".system",
"node_modules"].
includes(entry.
name))
113 + const target
= path.
join(resolved, entry.
name);
114 + if (entry.
isDirectory()) {
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] });
124 + for (
const directory
of TEST_DIRECTORIES)
scan(path.
join(
root, directory));
125 + return references.
sort(
127 + left.path.
localeCompare(right.path)
|| left.spec.
localeCompare(right.spec),
131 +export function runDoctor(cwd
: string)
: DoctorResult {
134 + root = discoverProjectRoot(cwd);
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))
146 + diagnostic(
"filesystem.missing", relative,
`Missing directory ${relative}`),
149 + for (
const relative
of SYSTEM_FILES) {
150 + const target
= path.
join(
root, relative);
151 + if (
!isFile(target))
153 + diagnostic(
"filesystem.missing", relative,
`Missing file ${relative}`),
157 + let prefix
: string | undefined;
158 + let configuredStyleVersion
= STYLE_VERSION;
159 + const configPath
= path.
join(
root,
".system/config.json");
160 + if (
isFile(configPath)) {
162 + const config
= parseSystemConfig(
readFileSync(configPath,
"utf8"));
163 + prefix
= config.
prefix;
164 + configuredStyleVersion
= config.styleVersion;
165 + if (config.schemaVersion
!== SCHEMA_VERSION)
168 + "config.schema-outdated",
169 + ".system/config.json",
170 + `Schema version ${config.schemaVersion}; installed ${SCHEMA_VERSION}`,
173 + if (config.styleVersion
!== STYLE_VERSION)
176 + "config.style-outdated",
177 + ".system/config.json",
178 + `Style version ${config.styleVersion}; installed ${STYLE_VERSION}`,
182 + const value
= error
as SystemDocumentError;
184 + diagnostic(value.
code,
".system/config.json", value.message),
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];
197 + ".system/system.css",
198 + "Missing The System styleVersion marker",
201 + else if (
Number(version)
!== configuredStyleVersion)
204 + "css.version-mismatch",
205 + ".system/system.css",
206 + `Stylesheet version ${version}; configured ${configuredStyleVersion}`,
211 + const { sources, mockups }
= collectDocumentSources(
root);
212 + let specIds
= new Set<
string>();
214 + const index
= indexDocuments(sources, prefix);
215 + diagnostics.
push(
...index.diagnostics);
218 + .
filter((document)
=> document.metadata.
type === "spec")
219 + .
map((document)
=> document.metadata.
id),
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))
236 + `Mockup owner is missing: ${ownerPath}`,
241 + const references
= collectTestReferences(
root);
242 + for (
const reference
of references)
243 + if (prefix
&& !specIds.
has(reference.spec))
246 + "test.dangling-reference",
248 + `Test references missing ${reference.spec}`,
252 + diagnostics.
sort(compareDiagnostics);
257 + exitCode: diagnostics.
length === 0 ? 0 : 1,
50 50 npm run test --{% for arg in usage.args %} "{{ arg }}"{% endfor %}
54 +description =
"Typecheck TypeScript" 55 +depends = [
"install"]
56 +run =
"npm run typecheck" 54 59 description =
"Run q heuristic extractor benchmark" 55 60 depends = [
"install"]