repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(the-system): validate authored document source

d0e6938fba3df09ac52b18d627b844a150fa08c6

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

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

Modified
6 6 import {
7 7 discoverProjectRoot,
8 8 parseDocumentId,
9 + parseDocumentMetadata,
9 10 parseSystemConfig,
10 11 resolveGovernedPath,
11 12 SystemDocumentError,
13 + validateAuthoredHtml,
12 14 validateFilename,
13 15 } from "../documents.ts";
167 +const shell = (metadata: string, body = "<header><h1>Title</h1></header><main><section><h2>Contract</h2><p>Readable.</p></section></main>") => `<!doctype html>
168 +<html lang="en"><head><meta charset="utf-8">
169 +<meta name="viewport" content="width=device-width, initial-scale=1">
170 +<title>Title</title><link rel="stylesheet" href="../system.css"></head>
171 +<body>${body}<script type="application/json" id="system-meta">${metadata}</script></body></html>`;
173 +describe("document metadata", () => {
174 + it.each([
175 + ['{"id":"PX-SPEC-001","type":"spec"}', { id: "PX-SPEC-001", type: "spec" }],
176 + ['{"id":"PX-ROADMAP-001","type":"roadmap","spec":"PX-SPEC-001"}', { id: "PX-ROADMAP-001", type: "roadmap", spec: "PX-SPEC-001" }],
177 + ['{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-001"}', { id: "PX-PLAN-001", type: "plan", spec: "PX-SPEC-001" }],
178 + ['{"id":"PX-PLAN-002","type":"plan","spec":"PX-SPEC-001","roadmap":"PX-ROADMAP-001","phase":2}', { id: "PX-PLAN-002", type: "plan", spec: "PX-SPEC-001", roadmap: "PX-ROADMAP-001", phase: 2 }],
179 + ['{"id":"PX-ISSUE-001","type":"issue","status":"open","specs":[]}', { id: "PX-ISSUE-001", type: "issue", status: "open", specs: [] }],
180 + ['{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-07-11","sources":["https://example.com/a"]}', { id: "PX-RESEARCH-001", type: "research", capturedAt: "2026-07-11", sources: ["https://example.com/a"] }],
181 + ] as const)("parses exact metadata %s", (json, expected) => assert.deepEqual(parseDocumentMetadata(shell(json), "PX"), expected));
183 + it.each([
184 + ["missing block", "<!doctype html><html lang=\"en\"></html>"],
185 + ["duplicate blocks", shell('{"id":"PX-SPEC-001","type":"spec"}') + '<script type="application/json" id="system-meta">{}</script>'],
186 + ["duplicate JSON key", shell('{"id":"PX-SPEC-001","id":"PX-SPEC-002","type":"spec"}')],
187 + ["unknown key", shell('{"id":"PX-SPEC-001","type":"spec","status":"open"}')],
188 + ["own ID/type mismatch", shell('{"id":"PX-PLAN-001","type":"spec"}')],
189 + ["one-sided roadmap", shell('{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-001","roadmap":"PX-ROADMAP-001"}')],
190 + ["duplicate issue specs", shell('{"id":"PX-ISSUE-001","type":"issue","status":"fixed","specs":["PX-SPEC-001","PX-SPEC-001"]}')],
191 + ["invalid date", shell('{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-02-30"}')],
192 + ["non-HTTPS source", shell('{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-07-11","sources":["http://example.com"]}')],
193 + ])("rejects %s", (_name, html) => assert.throws(() => parseDocumentMetadata(html, "PX"), SystemDocumentError));
194 +});
196 +describe("authored HTML", () => {
197 + it("accepts the complete semantic shell and inert progressive enhancement", () => {
198 + const html = shell('{"id":"PX-SPEC-001","type":"spec"}', "<header><h1>Title</h1></header><main><section><h2>Contract</h2><details><summary>More</summary><p>Text.</p></details></section></main><script>document.querySelector('details');</script>");
199 + assert.deepEqual(validateAuthoredHtml("specs/PX-SPEC-001-title.html", html), []);
200 + });
202 + it.each([
203 + ["document.doctype", shell('{"id":"PX-SPEC-001","type":"spec"}').replace("<!doctype html>", "")],
204 + ["document.language", shell('{"id":"PX-SPEC-001","type":"spec"}').replace('lang="en"', 'lang="fr"')],
205 + ["document.charset", shell('{"id":"PX-SPEC-001","type":"spec"}').replace('<meta charset="utf-8">', "")],
206 + ["document.viewport", shell('{"id":"PX-SPEC-001","type":"spec"}').replace(/<meta name="viewport"[^>]+>/, "")],
207 + ["document.title", shell('{"id":"PX-SPEC-001","type":"spec"}').replace("<title>Title</title>", "<title></title>")],
208 + ["document.stylesheet", shell('{"id":"PX-SPEC-001","type":"spec"}').replace("../system.css", "./local.css")],
209 + ["document.semantic-shell", shell('{"id":"PX-SPEC-001","type":"spec"}').replace(/<main>|<\/main>/g, "")],
210 + ["document.forbidden-tag", shell('{"id":"PX-SPEC-001","type":"spec"}', "<header><h1>X</h1></header><main><section><iframe src=\"x\"></iframe></section></main>")],
211 + ["document.event-handler", shell('{"id":"PX-SPEC-001","type":"spec"}', "<header><h1>X</h1></header><main><section onclick=\"x()\">X</section></main>")],
212 + ["document.executable-url", shell('{"id":"PX-SPEC-001","type":"spec"}', "<header><h1>X</h1></header><main><section><a href=\"javascript:x()\">X</a></section></main>")],
213 + ["document.external-script", shell('{"id":"PX-SPEC-001","type":"spec"}', "<header><h1>X</h1></header><main><section>X</section></main><script src=\"https://example.com/x.js\"></script>")],
214 + ["document.active-api", shell('{"id":"PX-SPEC-001","type":"spec"}', "<header><h1>X</h1></header><main><section>X</section></main><script>fetch('https://example.com')</script>")],
215 + ["document.css-resource", shell('{"id":"PX-SPEC-001","type":"spec"}', "<header><h1>X</h1></header><main><section>X</section></main><style>@import url('https://example.com/x.css');</style>")],
216 + ["document.meta-refresh", shell('{"id":"PX-SPEC-001","type":"spec"}').replace("</head>", '<meta http-equiv="refresh" content="0; url=x"></head>')],
217 + ])("reports %s", (code, html) => assert.ok(validateAuthoredHtml("doc.html", html).some((item) => item.code === code)));
219 + it("allows remote HTTPS navigation anchors", () => {
220 + const html = shell('{"id":"PX-SPEC-001","type":"spec"}', "<header><h1>X</h1></header><main><section><a href=\"https://example.com/reference\">Reference</a></section></main>");
221 + assert.deepEqual(validateAuthoredHtml("doc.html", html), []);
222 + });
223 +});

extensions/the-system/documents.ts

Modified
187 +const duplicateTopLevelKeys = (source: string): string[] => {
188 + const keys: string[] = [];
189 + const duplicates = new Set<string>();
190 + let depth = 0;
191 + let index = 0;
192 + while (index < source.length) {
193 + const character = source[index];
194 + if (character === "{") { depth += 1; index += 1; continue; }
195 + if (character === "}") { depth -= 1; index += 1; continue; }
196 + if (character !== '"') { index += 1; continue; }
197 + const start = index;
198 + index += 1;
199 + let escaped = false;
200 + while (index < source.length) {
201 + const current = source[index++];
202 + if (!escaped && current === '"') break;
203 + escaped = !escaped && current === "\\";
204 + if (current !== "\\") escaped = false;
206 + if (depth !== 1) continue;
207 + let cursor = index;
208 + while (/\s/.test(source[cursor] ?? "")) cursor += 1;
209 + if (source[cursor] !== ":") continue;
210 + const key = JSON.parse(source.slice(start, index)) as string;
211 + if (keys.includes(key)) duplicates.add(key);
212 + keys.push(key);
214 + return [...duplicates].sort();
217 +const stringArray = (value: unknown, label: string): string[] => {
218 + if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new SystemDocumentError("metadata.value", `${label} must be a string array`);
219 + if (new Set(value).size !== value.length) throw new SystemDocumentError("metadata.duplicate", `${label} must contain unique values`);
220 + return value;
222 +const validDate = (value: unknown) => {
223 + if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
224 + const date = new Date(`${value}T00:00:00Z`);
225 + return !Number.isNaN(date.valueOf()) && date.toISOString().slice(0, 10) === value;
227 +const httpsUrl = (value: string) => {
228 + try { return new URL(value).protocol === "https:"; } catch { return false; }
230 +const metadataScripts = (html: string) => [...html.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi)]
231 + .filter((match) => /\bid\s*=\s*(["'])system-meta\1/i.test(match[1]) && /\btype\s*=\s*(["'])application\/json\1/i.test(match[1]));
233 +export function parseDocumentMetadata(html: string, prefix: string): DocumentMetadata {
234 + const blocks = metadataScripts(html);
235 + if (blocks.length !== 1) throw new SystemDocumentError("metadata.block", `Expected exactly one system-meta block; received ${blocks.length}`);
236 + const json = blocks[0][2].trim();
237 + const duplicates = duplicateTopLevelKeys(json);
238 + if (duplicates.length) throw new SystemDocumentError("metadata.duplicate-key", `Duplicate metadata keys: ${duplicates.join(", ")}`);
239 + let parsed: unknown;
240 + try { parsed = JSON.parse(json); } catch { throw new SystemDocumentError("metadata.invalid-json", "Invalid system metadata JSON"); }
241 + const value = objectValue(parsed, "Metadata");
242 + if (typeof value.id !== "string" || typeof value.type !== "string") throw new SystemDocumentError("metadata.identity", "Metadata requires string id and type");
243 + const ownId = parseDocumentId(value.id, prefix);
244 + if (ownId.type !== value.type) throw new SystemDocumentError("metadata.identity", `Metadata ID/type mismatch: ${value.id} / ${value.type}`);
245 + const reference = (key: string) => {
246 + if (typeof value[key] !== "string") throw new SystemDocumentError("metadata.value", `${key} must be a document ID`);
247 + parseDocumentId(value[key] as string, prefix);
248 + return value[key] as string;
249 + };
250 + switch (value.type) {
251 + case "spec":
252 + exactKeys(value, ["id", "type"]);
253 + return { id: value.id, type: "spec" };
254 + case "roadmap":
255 + exactKeys(value, ["id", "type", "spec"]);
256 + return { id: value.id, type: "roadmap", spec: reference("spec") };
257 + case "plan": {
258 + exactKeys(value, ["id", "type", "spec"], ["roadmap", "phase"]);
259 + const hasRoadmap = "roadmap" in value;
260 + const hasPhase = "phase" in value;
261 + if (hasRoadmap !== hasPhase || (hasPhase && !positiveInteger(value.phase))) throw new SystemDocumentError("metadata.plan-phase", "Plan roadmap and positive phase must appear together");
262 + return hasRoadmap ? { id: value.id, type: "plan", spec: reference("spec"), roadmap: reference("roadmap"), phase: value.phase as number } : { id: value.id, type: "plan", spec: reference("spec") };
264 + case "issue": {
265 + exactKeys(value, ["id", "type", "status", "specs"]);
266 + if (value.status !== "open" && value.status !== "fixed") throw new SystemDocumentError("metadata.status", "Issue status must be open or fixed");
267 + const specs = stringArray(value.specs, "specs");
268 + for (const id of specs) parseDocumentId(id, prefix);
269 + return { id: value.id, type: "issue", status: value.status, specs };
271 + case "research": {
272 + exactKeys(value, ["id", "type", "capturedAt"], ["sources"]);
273 + if (!validDate(value.capturedAt)) throw new SystemDocumentError("metadata.date", "capturedAt must be a valid ISO date");
274 + const sources = "sources" in value ? stringArray(value.sources, "sources") : undefined;
275 + if (sources?.some((source) => !httpsUrl(source))) throw new SystemDocumentError("metadata.source", "Research sources must use HTTPS");
276 + return sources ? { id: value.id, type: "research", capturedAt: value.capturedAt as string, sources } : { id: value.id, type: "research", capturedAt: value.capturedAt as string };
278 + default:
279 + throw new SystemDocumentError("metadata.type", `Unsupported metadata type: ${value.type}`);
283 +export type Diagnostic = Readonly<{ code: string; path: string; message: string }>;
284 +const diagnostic = (code: string, path: string, message: string): Diagnostic => ({ code, path, message });
285 +const count = (source: string, expression: RegExp) => [...source.matchAll(expression)].length;
287 +export function validateAuthoredHtml(filename: string, html: string): readonly Diagnostic[] {
288 + const findings: Diagnostic[] = [];
289 + const requireOne = (code: string, expression: RegExp, message: string) => {
290 + if (count(html, expression) !== 1) findings.push(diagnostic(code, filename, message));
291 + };
292 + if (!/^<!doctype html>/i.test(html.trimStart())) findings.push(diagnostic("document.doctype", filename, "Document must begin with HTML doctype"));
293 + requireOne("document.language", /<html\b[^>]*\blang\s*=\s*(["'])en\1[^>]*>/gi, "Document requires one html lang=en root");
294 + requireOne("document.charset", /<meta\b[^>]*\bcharset\s*=\s*(["'])?utf-8\1[^>]*>/gi, "Document requires one UTF-8 charset meta");
295 + requireOne("document.viewport", /<meta\b[^>]*\bname\s*=\s*(["'])viewport\1[^>]*\bcontent\s*=\s*(["'])width=device-width,\s*initial-scale=1\2[^>]*>/gi, "Document requires one viewport meta");
296 + requireOne("document.title", /<title>\s*[^<\s][^<]*<\/title>/gi, "Document requires one nonempty title");
297 + requireOne("document.stylesheet", /<link\b(?=[^>]*\brel\s*=\s*(["'])stylesheet\1)(?=[^>]*\bhref\s*=\s*(["'])\.\.\/system\.css\2)[^>]*>/gi, "Document requires exactly ../system.css");
298 + if (count(html, /<link\b[^>]*\brel\s*=\s*(["'])stylesheet\1[^>]*>/gi) !== 1) findings.push(diagnostic("document.stylesheet", filename, "Additional or missing stylesheets are forbidden"));
299 + for (const tag of ["header", "main", "section"] as const) requireOne("document.semantic-shell", new RegExp(`<${tag}\\b`, "gi"), `Document requires one ${tag} element`);
300 + if (/<\/?(?:iframe|object|embed)\b/i.test(html)) findings.push(diagnostic("document.forbidden-tag", filename, "iframe, object, and embed are forbidden"));
301 + if (/<meta\b[^>]*\bhttp-equiv\s*=\s*(["'])refresh\1/i.test(html)) findings.push(diagnostic("document.meta-refresh", filename, "Meta refresh is forbidden"));
302 + if (/\son[a-z]+\s*=/i.test(html)) findings.push(diagnostic("document.event-handler", filename, "Event-handler attributes are forbidden"));
303 + if (/\b(?:href|src|action|formaction|xlink:href)\s*=\s*(["'])\s*(?:javascript|vbscript|data):/i.test(html)) findings.push(diagnostic("document.executable-url", filename, "Executable URL schemes are forbidden"));
304 + if (/<script\b[^>]*\bsrc\s*=/i.test(html)) findings.push(diagnostic("document.external-script", filename, "External script sources are forbidden"));
305 + if (/<(?:img|audio|video|source|track)\b[^>]*\bsrc\s*=\s*(["'])https?:/i.test(html)) findings.push(diagnostic("document.remote-resource", filename, "Remote media resources are forbidden"));
306 + if (/(?:@import|url\s*\(\s*["']?\s*(?:https?:|data:))/i.test(html)) findings.push(diagnostic("document.css-resource", filename, "CSS imports and remote/data URLs are forbidden"));
307 + const executable = [...html.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi)]
308 + .filter((match) => !/\btype\s*=\s*(["'])application\/json\1/i.test(match[1]))
309 + .map((match) => match[2]).join("\n");
310 + if (/\b(?:fetch|XMLHttpRequest|WebSocket|EventSource|importScripts|localStorage|sessionStorage|indexedDB)\b/.test(executable) || /\bimport\s*\(/.test(executable)) findings.push(diagnostic("document.active-api", filename, "Network, import, and browser storage APIs are forbidden"));
311 + return findings.sort(compareDiagnostics);
314 +const compareDiagnostics = (left: Diagnostic, right: Diagnostic) =>
315 + left.path.localeCompare(right.path) || left.code.localeCompare(right.code) || left.message.localeCompare(right.message);