repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(the-system): index document relationships

359e3db99e888ce2136c758e7c1ec6d7ebdce51e

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

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

Modified
5 5 import { afterEach, describe, it } from "vitest";
6 6 import {
7 7 discoverProjectRoot,
8 + indexDocuments,
8 9 parseDocumentId,
9 10 parseDocumentMetadata,
10 11 parseSystemConfig,
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),
228 +});
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"}'),
238 + ], "PX");
239 + assert.equal(result.documents.length, 5);
240 + assert.deepEqual(result.diagnostics, []);
241 + });
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":[]}'),
252 + ], "PX");
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.")));
260 + });
261 +});

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));
335 + try {
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 });
340 + } catch (error) {
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) {
359 + diagnostics.push(
360 + diagnostic(
361 + "graph.forbidden-edge",
362 + document.path,
363 + `${document.metadata.id} must reference ${expectedType}; ${targetId} is ${referencedType}`,
364 + ),
365 + );
366 + } else if (!target) {
367 + diagnostics.push(
368 + diagnostic(
369 + "graph.dangling-reference",
370 + document.path,
371 + `${document.metadata.id} references missing ${targetId}`,
372 + ),
373 + );
374 + } else if (target.metadata.type !== expectedType) {
375 + diagnostics.push(
376 + diagnostic(
377 + "graph.forbidden-edge",
378 + document.path,
379 + `${document.metadata.id} must reference ${expectedType}; ${targetId} is ${target.metadata.type}`,
380 + ),
381 + );
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) };