pi-ext bugabingas pi extensions
owned by bugabinga
README Source History Refs Compare Notes Search feat(the-system): index document relationships
359e3db99e888ce2136c758e7c1ec6d7ebdce51e
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 5 5 import { afterEach, describe, it }
from "vitest" ;
9 10 parseDocumentMetadata,
221 222 assert.
deepEqual (
validateAuthoredHtml (
"doc.html" , html), []);
226 + const source = (folder
: string , id
: string , slug
: string , metadata
: string )
=> ({
227 + path:
`/project/.system/${folder}/${id}-${slug}.html` , html:
shell (metadata),
230 + describe (
"document index" , ()
=> {
231 + it (
"indexes a valid complete graph without diagnostics" , ()
=> {
232 + const result
= indexDocuments ([
233 + source (
"specs" ,
"PX-SPEC-001" ,
"login" ,
'{"id":"PX-SPEC-001","type":"spec"}' ),
234 + source (
"roadmaps" ,
"PX-ROADMAP-001" ,
"login" ,
'{"id":"PX-ROADMAP-001","type":"roadmap","spec":"PX-SPEC-001"}' ),
235 + source (
"plans" ,
"PX-PLAN-001" ,
"login-phase-2" ,
'{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-001","roadmap":"PX-ROADMAP-001","phase":2}' ),
236 + source (
"issues" ,
"PX-ISSUE-001" ,
"login-error" ,
'{"id":"PX-ISSUE-001","type":"issue","status":"open","specs":["PX-SPEC-001"]}' ),
237 + source (
"research" ,
"PX-RESEARCH-001" ,
"login" ,
'{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-07-11"}' ),
239 + assert.
equal (result.documents.
length ,
5 );
240 + assert.
deepEqual (result.diagnostics, []);
243 + it (
"sorts stable duplicate, filename, dangling, and forbidden-edge diagnostics" , ()
=> {
244 + const result
= indexDocuments ([
245 + source (
"specs" ,
"PX-SPEC-001" ,
"one" ,
'{"id":"PX-SPEC-001","type":"spec"}' ),
246 + source (
"specs" ,
"PX-SPEC-002" ,
"two" ,
'{"id":"PX-SPEC-001","type":"spec"}' ),
247 + source (
"roadmaps" ,
"PX-ROADMAP-001" ,
"wrong-target" ,
'{"id":"PX-ROADMAP-001","type":"roadmap","spec":"PX-PLAN-009"}' ),
248 + source (
"plans" ,
"PX-PLAN-001" ,
"dangling" ,
'{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-404"}' ),
249 + source (
"plans" ,
"PX-PLAN-002" ,
"crossed" ,
'{"id":"PX-PLAN-002","type":"plan","spec":"PX-SPEC-001","roadmap":"PX-ROADMAP-002","phase":1}' ),
250 + source (
"roadmaps" ,
"PX-ROADMAP-002" ,
"other" ,
'{"id":"PX-ROADMAP-002","type":"roadmap","spec":"PX-SPEC-003"}' ),
251 + source (
"issues" ,
"PX-ISSUE-001" ,
"unknown" ,
'{"id":"PX-ISSUE-001","type":"issue","status":"open","specs":[]}' ),
253 + assert.
deepEqual (result.diagnostics.
map (({ code })
=> code), [
... result.diagnostics].
sort ((a, b)
=> a.path.
localeCompare (b.path)
|| a.
code .
localeCompare (b.
code )
|| a.message.
localeCompare (b.message)).
map (({ code })
=> code));
254 + assert.
ok (result.diagnostics.
some ((item)
=> item.
code === "graph.duplicate-id" && item.message.
includes (
"PX-SPEC-001" )));
255 + assert.
ok (result.diagnostics.
some ((item)
=> item.
code === "document.filename" ));
256 + assert.
ok (result.diagnostics.
some ((item)
=> item.
code === "graph.dangling-reference" && item.message.
includes (
"PX-SPEC-404" )));
257 + assert.
ok (result.diagnostics.
some ((item)
=> item.
code === "graph.forbidden-edge" && item.message.
includes (
"must reference spec" )));
258 + assert.
ok (result.diagnostics.
some ((item)
=> item.
code === "graph.forbidden-edge" && item.message.
includes (
"belongs to PX-SPEC-003" )));
259 + assert.
ok (
! result.diagnostics.
some ((item)
=> item.path.
includes (
"PX-ISSUE-001" )
&& item.
code .
startsWith (
"graph." )));
extensions/the-system/documents.ts Modified 314 314 const compareDiagnostics = (left
: Diagnostic , right
: Diagnostic )
=> 315 315 left.path.
localeCompare (right.path)
|| left.
code .
localeCompare (right.
code )
|| left.message.
localeCompare (right.message);
317 + export type DocumentSource = Readonly <{ path
: string ; html
: string }>;
318 + export type DocumentRecord = Readonly <{ path
: string ; metadata
: DocumentMetadata }>;
319 + export type DocumentIndex = Readonly <{ documents
: readonly DocumentRecord []; diagnostics
: readonly Diagnostic [] }>;
321 + const references = (metadata
: DocumentMetadata )
: readonly [
string ,
"spec" | "roadmap" ][]
=> {
322 + switch (metadata.
type ) {
323 + case "roadmap" :
return [[metadata.spec,
"spec" ]];
324 + case "plan" :
return [[metadata.spec,
"spec" ],
... (metadata.roadmap
? [[metadata.roadmap,
"roadmap" ]
as const ]
: [])];
325 + case "issue" :
return metadata.specs.
map ((id)
=> [id,
"spec" ]
as const );
326 + default :
return [];
330 + export function indexDocuments (sources
: readonly DocumentSource [], prefix
: string )
: DocumentIndex {
331 + const documents
: DocumentRecord []
= [];
332 + const diagnostics
: Diagnostic []
= [];
333 + for (
const item
of [
... sources].
sort ((left, right)
=> left.path.
localeCompare (right.path))) {
334 + diagnostics.
push (
... validateAuthoredHtml (item.path, item.html));
336 + const metadata
= parseDocumentMetadata (item.html, prefix);
337 + try {
validateFilename (item.path, metadata, prefix); }
338 + catch (error) { diagnostics.
push (
diagnostic (
"document.filename" , item.path, (error
as Error ).message)); }
339 + documents.
push ({ path: item.path, metadata });
341 + const value
= error
as SystemDocumentError ;
342 + diagnostics.
push (
diagnostic (
"document.metadata" , item.path,
`${value. code }: ${value.message}` ));
345 + const groups
= new Map <
string ,
DocumentRecord []>();
346 + for (
const document
of documents) groups.
set (
document .metadata.
id , [
... (groups.
get (
document .metadata.
id )
?? []),
document ]);
347 + for (
const [id, records]
of groups) {
348 + if (records.
length > 1 ) {
349 + const paths
= records.
map ((record)
=> record.path).
sort ();
350 + for (
const record
of records) diagnostics.
push (
diagnostic (
"graph.duplicate-id" , record.path,
`Duplicate ID ${id}: ${paths. join (", ")}` ));
353 + const unique
= new Map ([
... groups].
filter (([, records])
=> records.
length === 1 ).
map (([id, records])
=> [id, records[
0 ]]));
354 + for (
const document
of documents) {
355 + for (
const [targetId, expectedType]
of references (
document .metadata)) {
356 + const referencedType
= parseDocumentId (targetId, prefix).
type ;
357 + const target
= unique.
get (targetId);
358 + if (referencedType
!== expectedType) {
361 + "graph.forbidden-edge" ,
363 + `${ document .metadata. id } must reference ${expectedType}; ${targetId} is ${referencedType}` ,
366 + }
else if (
! target) {
369 + "graph.dangling-reference" ,
371 + `${ document .metadata. id } references missing ${targetId}` ,
374 + }
else if (target.metadata.
type !== expectedType) {
377 + "graph.forbidden-edge" ,
379 + `${ document .metadata. id } must reference ${expectedType}; ${targetId} is ${target.metadata. type }` ,
384 + if (
document .metadata.
type === "plan" && document .metadata.roadmap) {
385 + const roadmap
= unique.
get (
document .metadata.roadmap);
386 + if (roadmap?.metadata.
type === "roadmap" && roadmap.metadata.spec
!== document .metadata.spec) {
387 + diagnostics.
push (
diagnostic (
"graph.forbidden-edge" ,
document .path,
`${ document .metadata.roadmap} belongs to ${roadmap.metadata.spec}, not ${ document .metadata.spec}` ));
391 + return { documents, diagnostics: diagnostics.
sort (compareDiagnostics) };