pi-ext bugabingas pi extensions
owned by bugabinga
README Source History Refs Compare Notes Search feat(the-system): validate authored document source
d0e6938fba3df09ac52b18d627b844a150fa08c6
Oliver Jan Krylow <oliver@bugabinga.net > · 12 Jul 2026
unsigned
Browse files Compare with HEAD
Changed files (2) extensions/the-system/__tests__/documents.test.ts Modified 9 + parseDocumentMetadata,
10 11 resolveGovernedPath,
11 12 SystemDocumentError,
13 + validateAuthoredHtml,
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" , ()
=> {
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));
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));
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), []);
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), []);
extensions/the-system/documents.ts Modified 187 + const duplicateTopLevelKeys = (source
: string )
: string []
=> {
188 + const keys
: string []
= [];
189 + const duplicates
= new Set <
string >();
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;
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);
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` );
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)
=> / \b id\s * =\s * (["'])system-meta \1 / i .
test (match[
1 ])
&& / \b type\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 ;
250 + switch (value.
type ) {
252 + exactKeys (value, [
"id" ,
"type" ]);
253 + return { id: value.
id , type:
"spec" };
255 + exactKeys (value, [
"id" ,
"type" ,
"spec" ]);
256 + return { id: value.
id , type:
"roadmap" , spec:
reference (
"spec" ) };
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" ) };
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 };
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 };
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));
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 [ ^ >] *\b lang\s * =\s * (["'])en \1 [ ^ >] * >/ gi ,
"Document requires one html lang=en root" );
294 + requireOne (
"document.charset" ,
/<meta \b [ ^ >] *\b charset\s * =\s * (["']) ? utf-8 \1 [ ^ >] * >/ gi ,
"Document requires one UTF-8 charset meta" );
295 + requireOne (
"document.viewport" ,
/<meta \b [ ^ >] *\b name\s * =\s * (["'])viewport \1 [ ^ >] *\b content\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 (?=[ ^ >] *\b rel\s * =\s * (["'])stylesheet \1 )(?=[ ^ >] *\b href\s * =\s * (["'])\.\.\/system\.css \2 )[ ^ >] * >/ gi ,
"Document requires exactly ../system.css" );
298 + if (
count (html,
/<link \b [ ^ >] *\b rel\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 [ ^ >] *\b http-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 [ ^ >] *\b src\s * =/ i .
test (html)) findings.
push (
diagnostic (
"document.external-script" , filename,
"External script sources are forbidden" ));
305 + if (
/<(?:img | audio | video | source | track) \b [ ^ >] *\b src\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)
=> ! / \b type\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)
|| / \b import\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);