1 -import { existsSync }
from "node:fs";
1 +import { existsSync, lstatSync, readdirSync, readFileSync }
from "node:fs";
2 2 import path
from "node:path";
5 + type MarkdownDocumentError,
7 +}
from "./markdown.ts";
4 -export const SCHEMA_VERSION
= 1;
5 -export const STYLE_VERSION
= 1;
9 +export const SCHEMA_VERSION
= 2;
7 11 export class SystemDocumentError extends Error {
8 12 readonly code
: string;
17 21 const nearestMarker = (
20 - markerExists: (path
: string)
=> boolean,
24 + markerExists: (candidate
: string)
=> boolean,
22 26 let current
= path.
resolve(cwd);
35 39 const resolvedCwd
= path.
resolve(cwd);
36 40 const jj
= nearestMarker(resolvedCwd,
".jj", markerExists);
37 41 const git
= nearestMarker(resolvedCwd,
".git", markerExists);
38 - if (jj
&& git
&& jj
!== git) {
42 + if (jj
&& git
&& jj
!== git)
39 43 throw new SystemDocumentError(
41 45 `Conflicting project roots: Git ${git}; JJ ${jj}`,
44 47 return jj
?? git
?? resolvedCwd;
52 55 relative
=== ".." || 53 56 relative.
startsWith(
`..${path.sep}`)
|| 54 57 path.
isAbsolute(relative)
56 59 throw new SystemDocumentError(
57 60 "path.outside-root",
58 61 `Path is outside project root: ${candidate}`,
71 73 export type DocumentType = (
typeof DOCUMENT_TYPES)[
number];
72 -export type SystemConfig = Readonly<{
74 - schemaVersion
: number;
75 - styleVersion
: number;
74 +export type SystemConfig = Readonly<{ prefix
: string; schemaVersion
: number }>;
75 +export type InspectedSystemConfig = Readonly<{
76 + config
: SystemConfig;
77 + legacyStyleVersion
?: number;
77 79 export type ParsedDocumentId = Readonly<{
113 115 | ResearchMetadata;
116 +export type Diagnostic = Readonly<{
121 +export type AuthoredDocument = Readonly<{
122 + metadata
: DocumentMetadata;
123 + frontmatter
: FrontmatterMap;
125 +export type BundleDocumentSource = Readonly<{ path
: string; markdown
: string }>;
126 +export type BundleDocumentRecord = Readonly<{
128 + metadata
: DocumentMetadata;
129 + frontmatter
: FrontmatterMap;
131 +export type BundleDocumentIndex = Readonly<{
132 + documents
: readonly BundleDocumentRecord[];
133 + diagnostics
: readonly Diagnostic[];
135 +export type BundleDiscovery = Readonly<{
136 + sources
: readonly BundleDocumentSource[];
137 + diagnostics
: readonly Diagnostic[];
115 140 const PREFIX
= /^[A-Z][A-Z0-9]{1,7}$/;
116 141 const SLUG
= "[a-z0-9]+(?:-[a-z0-9]+)*";
131 156 )
: Record<
string,
unknown>
=> {
132 - if (
typeof value
!== "object" || value
=== null || Array.
isArray(value)) {
157 + if (
typeof value
!== "object" || value
=== null || Array.
isArray(value))
133 158 throw new SystemDocumentError(
135 160 `${label} must be a JSON object`,
138 162 return value
as Record<
string,
unknown>;
140 164 const exactKeys = (
141 165 value
: Record<
string,
unknown>,
142 166 required
: readonly string[],
143 - optional
: readonly string[]
= [],
145 168 const actual
= Object.
keys(value).
sort();
146 - const allowed
= new Set([
...required,
...optional]);
148 170 required.
some((key)
=> !(key
in value))
|| 149 - actual.
some((key)
=> !allowed.
has(key))
171 + actual.
some((key)
=> !required.
includes(key))
151 173 throw new SystemDocumentError(
153 - `Expected keys ${[...required, ...optional].sort().join(", ")}; received ${actual.join(", ")}`,
175 + `Expected keys ${[...required].sort().join(", ")}; received ${actual.join(", ")}`,
157 178 const positiveInteger = (value
: unknown)
=> 158 179 typeof value
=== "number" && Number.
isInteger(value)
&& value
> 0;
160 -export function parseSystemConfig(source
: string)
: SystemConfig {
161 - let parsed
: unknown;
163 - parsed
= JSON.
parse(source);
165 - throw new SystemDocumentError(
"config.invalid-json",
"Invalid config JSON");
167 - const duplicates
= duplicateTopLevelKeys(source);
168 - if (duplicates.
length)
169 - throw new SystemDocumentError(
170 - "config.duplicate-key",
171 - `Duplicate config keys: ${duplicates.join(", ")}`,
173 - const value
= objectValue(parsed,
"Config");
174 - exactKeys(value, [
"prefix",
"schemaVersion",
"styleVersion"]);
175 - if (
typeof value.
prefix !== "string" || !PREFIX.
test(value.
prefix)) {
176 - throw new SystemDocumentError(
"config.prefix",
"Invalid project prefix");
179 - !positiveInteger(value.schemaVersion)
|| 180 - !positiveInteger(value.styleVersion)
182 - throw new SystemDocumentError(
184 - "Schema and style versions must be positive integers",
188 - prefix: value.
prefix,
189 - schemaVersion: value.schemaVersion
as number,
190 - styleVersion: value.styleVersion
as number,
194 -export function parseDocumentId(
196 - expectedPrefix
?: string,
197 -)
: ParsedDocumentId {
199 - /^([A-Z][A-Z0-9]{1,7})-(SPEC|ROADMAP|PLAN|ISSUE|RESEARCH)-([0-9]{3,})$/.
exec(
202 - const sequence
= match
? Number(match[
3])
: 0;
203 - const canonical
= sequence
> 0 ? String(sequence).
padStart(
3,
"0")
: "";
204 - if (
!match
|| match[
3]
!== canonical) {
205 - throw new SystemDocumentError(
207 - `Invalid document ID: ${source}`,
210 - if (expectedPrefix
&& match[
1]
!== expectedPrefix) {
211 - throw new SystemDocumentError(
213 - `Document ID must use prefix ${expectedPrefix}: ${source}`,
219 - type: TYPE_BY_TOKEN.
get(match[
2])
as DocumentType,
224 -export function validateFilename(
226 - metadata
: DocumentMetadata,
229 - const parsed
= parseDocumentId(metadata.
id, prefix);
230 - const expectedDirectory
= DIRECTORY_BY_TYPE[metadata.
type];
231 - const directory
= path.
basename(path.
dirname(filename));
232 - const pattern
= new RegExp(
`^${metadata.id}-${SLUG}\\.html$`);
234 - parsed.
type !== metadata.
type || 235 - directory
!== expectedDirectory
|| 236 - !pattern.
test(path.
basename(filename))
238 - throw new SystemDocumentError(
239 - "document.filename",
240 - `Filename mismatch for ${metadata.id}: ${filename}`,
245 180 const duplicateTopLevelKeys = (source
: string)
: string[]
=> {
246 181 const keys
: string[]
= [];
247 182 const duplicates
= new Set<
string>();
266 - const start
= index;
201 + const start
= index
++;
268 202 let escaped
= false;
269 203 while (index
< source.
length) {
270 204 const current
= source[index
++];
283 217 return [
...duplicates].
sort();
286 -const stringArray = (value
: unknown, label
: string)
: string[]
=> {
287 - if (
!Array.
isArray(value)
|| value.
some((item)
=> typeof item
!== "string"))
220 +export function parseSystemConfig(source
: string)
: SystemConfig {
221 + let parsed
: unknown;
223 + parsed
= JSON.
parse(source);
225 + throw new SystemDocumentError(
"config.invalid-json",
"Invalid config JSON");
227 + const duplicates
= duplicateTopLevelKeys(source);
228 + if (duplicates.
length)
288 229 throw new SystemDocumentError(
290 - `${label} must be a string array`,
230 + "config.duplicate-key",
231 + `Duplicate config keys: ${duplicates.join(", ")}`,
292 - if (
new Set(value).
size !== value.
length)
233 + const value
= objectValue(parsed,
"Config");
234 + exactKeys(value, [
"prefix",
"schemaVersion"]);
235 + if (
typeof value.
prefix !== "string" || !PREFIX.
test(value.
prefix))
236 + throw new SystemDocumentError(
"config.prefix",
"Invalid project prefix");
237 + if (
!positiveInteger(value.schemaVersion))
293 238 throw new SystemDocumentError(
294 - "metadata.duplicate",
295 - `${label} must contain unique values`,
240 + "Schema version must be a positive integer",
242 + return { prefix: value.
prefix, schemaVersion: value.schemaVersion
as number };
245 +export function inspectSystemConfig(source
: string)
: InspectedSystemConfig {
247 + return { config:
parseSystemConfig(source) };
248 + }
catch (currentError) {
249 + let parsed
: unknown;
251 + parsed
= JSON.
parse(source);
253 + throw currentError;
255 + if (
duplicateTopLevelKeys(source).
length > 0)
throw currentError;
256 + let value
: Record<
string,
unknown>;
258 + value
= objectValue(parsed,
"Legacy config");
259 + exactKeys(value, [
"prefix",
"schemaVersion",
"styleVersion"]);
261 + throw currentError;
263 + if (value.schemaVersion
!== 1 || !positiveInteger(value.styleVersion))
264 + throw currentError;
265 + const config
= parseSystemConfig(
267 + prefix: value.
prefix,
268 + schemaVersion: value.schemaVersion,
271 + return { config, legacyStyleVersion: value.styleVersion
as number };
275 +export function parseDocumentId(
277 + expectedPrefix
?: string,
278 +)
: ParsedDocumentId {
280 + /^([A-Z][A-Z0-9]{1,7})-(SPEC|ROADMAP|PLAN|ISSUE|RESEARCH)-([0-9]{3,})$/.
exec(
283 + const sequence
= match
? Number(match[
3])
: 0;
284 + const canonical
= sequence
> 0 ? String(sequence).
padStart(
3,
"0")
: "";
285 + if (
!match
|| match[
3]
!== canonical)
286 + throw new SystemDocumentError(
288 + `Invalid document ID: ${source}`,
290 + if (expectedPrefix
&& match[
1]
!== expectedPrefix)
291 + throw new SystemDocumentError(
293 + `Document ID must use prefix ${expectedPrefix}: ${source}`,
298 + type: TYPE_BY_TOKEN.
get(match[
2])
as DocumentType,
303 +export function validateDocumentPath(
304 + documentPath
: string,
305 + metadata
: DocumentMetadata,
308 + const parsed
= parseDocumentId(metadata.
id, prefix);
309 + const expectedDirectory
= DIRECTORY_BY_TYPE[metadata.
type];
310 + const pattern
= new RegExp(
`^${metadata.id}-${SLUG}$`);
311 + const parts
= documentPath.
split(
"/");
313 + parsed.
type !== metadata.
type || 314 + parts.
length !== 4 || 315 + parts[
0]
!== ".system" || 316 + parts[
1]
!== expectedDirectory
|| 317 + !pattern.
test(parts[
2]
?? "")
|| 318 + parts[
3]
!== "index.md" 320 + throw new SystemDocumentError(
322 + `Bundle path mismatch for ${metadata.id}: ${documentPath}`,
299 326 const validDate = (value
: unknown)
=> {
300 327 if (
typeof value
!== "string" || !/^\d{4}-\d{2}-\d{2}$/.
test(value))
304 331 !Number.
isNaN(date.
valueOf())
&& date.
toISOString().
slice(
0,
10)
=== value
307 -const httpsUrl = (value
: string)
=> {
309 - return new URL(value).
protocol === "https:";
334 +const requiredStringField = (fields
: FrontmatterMap, key
: string)
: string => {
335 + const value
= fields.
get(key);
336 + if (
typeof value
!== "string")
337 + throw new SystemDocumentError(
"metadata.value",
`${key} must be a string`);
314 -type HtmlTag = Readonly<{
319 - attributes
: ReadonlyMap<
string,
string | undefined>;
322 -const withoutHtmlComments = (html
: string)
=> 323 - html.
replace(
/<!--[\s\S]*?(?:-->|$)/g, (comment)
=> 324 - comment.
replace(
/[^\r\n]/g,
" "),
327 -const scanAttributes = (
329 -)
: ReadonlyMap<
string,
string | undefined>
=> {
330 - const attributes
= new Map<
string,
string | undefined>();
332 - while (index
< source.
length) {
333 - while (
/\s|\//.
test(source[index]
?? "")) index
+= 1;
334 - const start
= index;
335 - while (
!/[\s=/>]/.
test(source[index]
?? ">")) index
+= 1;
336 - if (start
=== index)
break;
337 - const name
= source.
slice(start, index).
toLowerCase();
338 - while (
/\s/.
test(source[index]
?? "")) index
+= 1;
339 - let value
: string | undefined;
340 - if (source[index]
=== "=") {
342 - while (
/\s/.
test(source[index]
?? "")) index
+= 1;
344 - source[index]
=== '"' || source[index]
=== "'" 347 - const valueStart
= index;
349 - while (index
< source.
length && source[index]
!== quote) index
+= 1;
351 - while (index
< source.
length && !/[\s>]/.
test(source[index]))
353 - value
= source.
slice(valueStart, index);
354 - if (quote
&& source[index]
=== quote) index
+= 1;
356 - if (
!attributes.
has(name)) attributes.
set(name, value);
340 +const optionalUniqueStrings = (
341 + fields
: FrontmatterMap,
343 +)
: readonly string[]
| undefined => {
344 + const value
= fields.
get(key);
345 + if (value
=== undefined)
return undefined;
346 + if (
!Array.
isArray(value)
|| value.
some((item)
=> typeof item
!== "string"))
347 + throw new SystemDocumentError(
349 + `${key} must be a string array`,
351 + if (
new Set(value).
size !== value.
length)
352 + throw new SystemDocumentError(
353 + "metadata.duplicate",
354 + `${key} must contain unique values`,
356 + return value
as readonly string[];
361 -const scanHtmlTags = (html
: string)
: readonly HtmlTag[]
=> {
362 - const source
= withoutHtmlComments(html);
363 - const tags
: HtmlTag[]
= [];
365 - while (index
< source.
length) {
366 - const start
= source.
indexOf(
"<", index);
367 - if (start
< 0)
break;
368 - let cursor
= start
+ 1;
369 - const closing
= source[cursor]
=== "/";
370 - if (closing) cursor
+= 1;
371 - while (
/\s/.
test(source[cursor]
?? "")) cursor
+= 1;
372 - const nameStart
= cursor;
373 - while (
/[A-Za-z0-9:-]/.
test(source[cursor]
?? "")) cursor
+= 1;
374 - if (cursor
=== nameStart) {
378 - const name
= source.
slice(nameStart, cursor).
toLowerCase();
379 - let quote
: string | undefined;
381 - for (; end
< source.
length; end
+= 1) {
382 - const character
= source[end];
384 - if (character
=== quote) quote
= undefined;
385 - }
else if (character
=== '"' || character
=== "'") quote
= character;
386 - else if (character
=== ">")
break;
388 - if (end
>= source.
length)
break;
394 - attributes: closing
396 - : scanAttributes(source.
slice(cursor, end)),
403 -const namedEntities
: Readonly<
Record<
string,
string>>
= {
413 -const decodeBasicEntities = (value
: string)
=> 415 - /&(?:#(\d+)|#x([\da-f]+)|([a-z][a-z\d]+));?/gi,
416 - (entity, decimal
: string, hexadecimal
: string, named
: string)
=> {
417 - if (named)
return namedEntities[named.
toLowerCase()]
?? entity;
418 - const point
= Number.
parseInt(decimal
?? hexadecimal, decimal
? 10 : 16);
420 - return String.
fromCodePoint(point);
426 -const attributeValue = (tag
: HtmlTag, name
: string)
=> {
427 - const value
= tag.
attributes.
get(name);
428 - return value
=== undefined ? undefined : decodeBasicEntities(value);
430 -const normalizedUrl = (value
: string)
=> 431 - decodeBasicEntities(value)
432 - .
replace(
/[\u0000-\u001f\u007f-\u009f]/g,
"")
435 -const scriptBlocks = (html
: string, tags
= scanHtmlTags(html))
=> {
436 - const blocks
: { tag
: HtmlTag; content
: string }[]
= [];
437 - for (
let index
= 0; index
< tags.
length; index
+= 1) {
438 - const tag
= tags[index];
439 - if (tag.
name !== "script" || tag.closing)
continue;
442 - .
find((item)
=> item.
name === "script" && item.closing);
443 - if (close) blocks.
push({ tag, content: html.
slice(tag.end, close.
start) });
448 -const metadataScripts = (html
: string)
=> 449 - scriptBlocks(html).
filter(
451 - attributeValue(tag,
"id")?.
toLowerCase()
=== "system-meta" && 452 - attributeValue(tag,
"type")?.
toLowerCase()
=== "application/json",
455 -export function parseDocumentMetadata(
358 +const projectMetadata = (
359 + fields
: FrontmatterMap,
458 -)
: DocumentMetadata {
459 - const blocks
= metadataScripts(html);
460 - if (blocks.
length !== 1)
461 - throw new SystemDocumentError(
463 - `Expected exactly one system-meta block; received ${blocks.length}`,
465 - const json
= blocks[
0].
content.
trim();
466 - let parsed
: unknown;
467 - let duplicates
: string[];
469 - parsed
= JSON.
parse(json);
470 - duplicates
= duplicateTopLevelKeys(json);
472 - throw new SystemDocumentError(
473 - "metadata.invalid-json",
474 - "Invalid system metadata JSON",
477 - if (duplicates.
length)
478 - throw new SystemDocumentError(
479 - "metadata.duplicate-key",
480 - `Duplicate metadata keys: ${duplicates.join(", ")}`,
482 - const value
= objectValue(parsed,
"Metadata");
483 - if (
typeof value.
id !== "string" || typeof value.
type !== "string")
361 +)
: DocumentMetadata => {
362 + const id
= requiredStringField(fields,
"id");
363 + const type
= requiredStringField(fields,
"type");
364 + const own
= parseDocumentId(id, prefix);
365 + if (own.
type !== type)
484 366 throw new SystemDocumentError(
485 367 "metadata.identity",
486 - "Metadata requires string id and type",
488 - const ownId
= parseDocumentId(value.
id, prefix);
489 - if (ownId.
type !== value.
type)
490 - throw new SystemDocumentError(
491 - "metadata.identity",
492 - `Metadata ID/type mismatch: ${value.id} / ${value.type}`,
368 + `Metadata ID/type mismatch: ${id} / ${type}`,
494 370 const reference = (key
: string)
=> {
495 - if (
typeof value[key]
!== "string")
496 - throw new SystemDocumentError(
498 - `${key} must be a document ID`,
500 - parseDocumentId(value[key]
as string, prefix);
501 - return value[key]
as string;
371 + const value
= requiredStringField(fields, key);
372 + parseDocumentId(value, prefix);
503 - switch (value.
type) {
505 - exactKeys(value, [
"id",
"type"]);
506 - return { id: value.
id, type:
"spec" };
377 + return { id, type };
508 - exactKeys(value, [
"id",
"type",
"spec"]);
509 - return { id: value.
id, type:
"roadmap", spec:
reference(
"spec") };
379 + return { id, type, spec:
reference(
"spec") };
511 - exactKeys(value, [
"id",
"type",
"spec"], [
"roadmap",
"phase"]);
512 - const hasRoadmap
= "roadmap" in value;
513 - const hasPhase
= "phase" in value;
381 + const roadmap
= fields.
get(
"roadmap");
382 + const phase
= fields.
get(
"phase");
515 - hasRoadmap
!== hasPhase
|| 516 - (hasPhase
&& !positiveInteger(value.phase))
384 + (roadmap
=== undefined)
!== (phase
=== undefined)
|| 385 + (roadmap
!== undefined && 386 + (
typeof roadmap
!== "string" || !positiveInteger(phase)))
518 388 throw new SystemDocumentError(
519 389 "metadata.plan-phase",
520 390 "Plan roadmap and positive phase must appear together",
392 + return roadmap
=== undefined 393 + ? { id, type, spec:
reference(
"spec") }
526 397 spec:
reference(
"spec"),
527 - roadmap:
reference(
"roadmap"),
528 - phase: value.phase
as number,
530 - : { id: value.
id, type:
"plan", spec:
reference(
"spec") };
399 + phase: phase
as number,
533 - exactKeys(value, [
"id",
"type",
"status",
"specs"]);
534 - if (value.
status !== "open" && value.
status !== "fixed")
403 + const status
= requiredStringField(fields,
"status");
404 + if (status
!== "open" && status
!== "fixed")
535 405 throw new SystemDocumentError(
536 406 "metadata.status",
537 407 "Issue status must be open or fixed",
539 - const specs
= stringArray(value.specs,
"specs");
540 - for (
const id
of specs)
parseDocumentId(id, prefix);
541 - return { id: value.
id, type:
"issue", status: value.
status, specs };
409 + const specs
= optionalUniqueStrings(fields,
"specs");
411 + throw new SystemDocumentError(
413 + "specs must be a string array",
415 + for (
const spec
of specs)
parseDocumentId(spec, prefix);
416 + return { id, type, status, specs };
543 418 case "research": {
544 - exactKeys(value, [
"id",
"type",
"capturedAt"], [
"sources"]);
545 - if (
!validDate(value.capturedAt))
419 + const capturedAt
= requiredStringField(fields,
"capturedAt");
420 + if (
!validDate(capturedAt))
546 421 throw new SystemDocumentError(
548 423 "capturedAt must be a valid ISO date",
551 - "sources" in value
? stringArray(value.sources,
"sources")
: undefined;
552 - if (sources?.
some((source)
=> !httpsUrl(source)))
553 - throw new SystemDocumentError(
555 - "Research sources must use HTTPS",
425 + const sources
= optionalUniqueStrings(fields,
"sources");
561 - capturedAt: value.capturedAt
as string,
567 - capturedAt: value.capturedAt
as string,
427 + ? { id, type, capturedAt, sources }
428 + : { id, type, capturedAt };
571 431 throw new SystemDocumentError(
573 - `Unsupported metadata type: ${value.type}`,
433 + `Unsupported metadata type: ${type}`,
438 +export function parseAuthoredDocument(
441 +)
: AuthoredDocument {
442 + const parsed
= parseRichMarkdown(source);
444 + metadata:
projectMetadata(parsed.frontmatter, prefix),
445 + frontmatter: parsed.frontmatter,
578 -export type Diagnostic = Readonly<{
583 449 const diagnostic = (
451 + diagnosticPath
: string,
587 -)
: Diagnostic => ({ code, path, message });
588 -const tagsNamed = (tags
: readonly HtmlTag[], name
: string, closing
= false)
=> 589 - tags.
filter((tag)
=> tag.
name === name
&& tag.closing
=== closing);
590 -const isExecutableUrl = (value
: string)
=> 591 - /^(?:javascript|vbscript|data):/i.
test(
normalizedUrl(value));
592 -const isRemoteUrl = (value
: string)
=> 593 - /^(?:https?:|\/\/)/i.
test(
normalizedUrl(value));
594 -const srcsetUrls = (value
: string)
=> 595 - decodeBasicEntities(value)
597 - .
map((candidate)
=> candidate.
trim().
split(
/\s+/)[
0]
?? "");
598 -const srcsetHasRemoteUrl = (value
: string)
=> 599 - srcsetUrls(value).
some(isRemoteUrl);
601 -export function validateAuthoredHtml(
604 -)
: readonly Diagnostic[] {
605 - const findings
: Diagnostic[]
= [];
606 - const cleanHtml
= withoutHtmlComments(html);
607 - const tags
= scanHtmlTags(html);
608 - const opening = (name
: string)
=> tagsNamed(tags, name);
609 - const closing = (name
: string)
=> tagsNamed(tags, name,
true);
610 - const add = (code
: string, message
: string)
=> 611 - findings.
push(
diagnostic(code, filename, message));
613 - if (
!/^<!doctype html>/i.
test(cleanHtml.
trimStart()))
614 - add(
"document.doctype",
"Document must begin with HTML doctype");
616 - const htmlOpen
= opening(
"html");
617 - const htmlClose
= closing(
"html");
618 - const headOpen
= opening(
"head");
619 - const headClose
= closing(
"head");
620 - const bodyOpen
= opening(
"body");
621 - const bodyClose
= closing(
"body");
623 - htmlOpen.
length !== 1 || 624 - htmlClose.
length !== 1 || 625 - headOpen.
length !== 1 || 626 - headClose.
length !== 1 || 627 - bodyOpen.
length !== 1 || 628 - bodyClose.
length !== 1 || 629 - !(htmlOpen[
0]?.
start < headOpen[
0]?.
start)
|| 630 - !(headOpen[
0]?.
start < headClose[
0]?.
start)
|| 631 - !(headClose[
0]?.
start < bodyOpen[
0]?.
start)
|| 632 - !(bodyOpen[
0]?.
start < bodyClose[
0]?.
start)
|| 633 - !(bodyClose[
0]?.
start < htmlClose[
0]?.
start)
636 - "document.structure",
637 - "Document requires one complete html, head, and body structure",
641 - htmlOpen.
length !== 1 || 642 - attributeValue(htmlOpen[
0],
"lang")?.
toLowerCase()
!== "en" 644 - add(
"document.language",
"Document requires one html lang=en root");
646 - const meta
= opening(
"meta");
649 - (tag)
=> attributeValue(tag,
"charset")?.
toLowerCase()
=== "utf-8",
652 - add(
"document.charset",
"Document requires one UTF-8 charset meta");
656 - attributeValue(tag,
"name")?.
toLowerCase()
=== "viewport" && 657 - /^width=device-width,\s*initial-scale=1$/i.
test(
658 - attributeValue(tag,
"content")
?? "",
662 - add(
"document.viewport",
"Document requires one viewport meta");
664 - const titleOpen
= opening(
"title");
665 - const titleClose
= closing(
"title");
667 - titleOpen.
length !== 1 || 668 - titleClose.
length !== 1 || 669 - titleOpen[
0].end
>= titleClose[
0].
start || 670 - !html.
slice(titleOpen[
0].end, titleClose[
0].
start).
trim()
672 - add(
"document.title",
"Document requires one nonempty title");
674 - const stylesheets
= opening(
"link").
filter((tag)
=> 675 - (
attributeValue(tag,
"rel")
?? "")
678 - .
includes(
"stylesheet"),
681 - stylesheets.
length !== 1 || 682 - attributeValue(stylesheets[
0],
"href")
!== "../system.css" 685 - "document.stylesheet",
686 - "Document requires exactly one ../system.css stylesheet",
690 - header: { open:
opening(
"header"), close:
closing(
"header") },
691 - main: { open:
opening(
"main"), close:
closing(
"main") },
692 - section: { open:
opening(
"section"), close:
closing(
"section") },
694 - for (
const name
of [
"header",
"main",
"section"]
as const) {
695 - const pair
= semantic[name];
697 - pair.open.
length !== 1 || 698 - pair.close.
length !== 1 || 699 - pair.open[
0].
start >= pair.close[
0].
start 702 - "document.semantic-shell",
703 - `Document requires one complete ${name} element`,
707 - bodyOpen.
length === 1 && 708 - bodyClose.
length === 1 && 709 - semantic.header.open.
length === 1 && 710 - semantic.header.close.
length === 1 && 711 - semantic.main.open.
length === 1 && 712 - semantic.main.close.
length === 1 && 713 - semantic.section.open.
length === 1 && 714 - semantic.section.close.
length === 1 && 716 - bodyOpen[
0].
start < semantic.header.open[
0].
start && 717 - semantic.header.close[
0].
start < semantic.main.open[
0].
start && 718 - semantic.main.open[
0].
start < semantic.section.open[
0].
start && 719 - semantic.section.close[
0].
start < semantic.main.close[
0].
start && 720 - semantic.main.close[
0].
start < bodyClose[
0].
start 724 - "document.semantic-shell",
725 - "Document requires header then main with one contained section",
728 - if (tags.
some((tag)
=> [
"iframe",
"object",
"embed"].
includes(tag.
name)))
729 - add(
"document.forbidden-tag",
"iframe, object, and embed are forbidden");
732 - (tag)
=> attributeValue(tag,
"http-equiv")?.
toLowerCase()
=== "refresh",
735 - add(
"document.meta-refresh",
"Meta refresh is forbidden");
740 - [
...tag.
attributes].
some(([name])
=> /^on[a-z]+$/i.
test(name)),
743 - add(
"document.event-handler",
"Event-handler attributes are forbidden");
745 - const urlAttributes
= new Set([
754 - let executableUrl
= false;
755 - let remoteResource
= false;
756 - for (
const tag
of tags) {
757 - if (tag.closing)
continue;
758 - for (
const [name, rawValue]
of tag.
attributes) {
759 - if (
!urlAttributes.
has(name)
|| rawValue
=== undefined)
continue;
761 - isExecutableUrl(rawValue)
|| 762 - (name
=== "srcset" && srcsetUrls(rawValue).
some(isExecutableUrl))
764 - executableUrl
= true;
766 - ((name
=== "src" || name
=== "poster")
&& isRemoteUrl(rawValue))
|| 767 - (name
=== "srcset" && srcsetHasRemoteUrl(rawValue))
|| 768 - ((name
=== "href" || name
=== "xlink:href")
&& 769 - tag.
name !== "a" && 770 - tag.
name !== "area" && 771 - isRemoteUrl(rawValue))
773 - remoteResource
= true;
777 - add(
"document.executable-url",
"Executable URL schemes are forbidden");
778 - if (remoteResource)
779 - add(
"document.remote-resource",
"Remote runtime resources are forbidden");
780 - if (
opening(
"script").
some((tag)
=> tag.
attributes.
has(
"src")))
781 - add(
"document.external-script",
"External script sources are forbidden");
782 - if (
/(?:@import|url\s*\(\s*["']?\s*(?:https?:|data:))/i.
test(cleanHtml))
784 - "document.css-resource",
785 - "CSS imports and remote/data URLs are forbidden",
788 - const executable
= scriptBlocks(html, tags)
791 - attributeValue(tag,
"type")?.
toLowerCase()
!== "application/json",
793 - .
map(({ content })
=> content)
796 - /\b(?:fetch|XMLHttpRequest|WebSocket|EventSource|importScripts|localStorage|sessionStorage|indexedDB)\b/.
test(
799 - /\bimport\s*\(/.
test(executable)
802 - "document.active-api",
803 - "Network, import, and browser storage APIs are forbidden",
805 - return findings.
sort(compareDiagnostics);
453 +)
: Diagnostic => ({ code, path: diagnosticPath, message });
808 454 const compareDiagnostics = (left
: Diagnostic, right
: Diagnostic)
=> 809 455 left.path.
localeCompare(right.path)
|| 810 456 left.
code.
localeCompare(right.
code)
|| 811 457 left.message.
localeCompare(right.message);
458 +const scanBundleAssets = (
461 + findings
: Diagnostic[],
463 + for (
const entry
of readdirSync(absolute, { withFileTypes:
true }).
sort(
464 + (left, right)
=> left.
name.
localeCompare(right.
name),
466 + if (relative.
split(
"/").
length === 3 && entry.
name === "index.md")
continue;
467 + const childAbsolute
= path.
join(absolute, entry.
name);
468 + const childRelative
= `${relative}/${entry.name}`;
469 + const stats
= lstatSync(childAbsolute, { throwIfNoEntry:
false });
470 + if (
!stats)
continue;
471 + if (stats.
isSymbolicLink())
474 + "bundle.symbolic-link",
476 + `Bundle path is a symbolic link: ${childRelative}`,
479 + else if (stats.
isDirectory())
480 + scanBundleAssets(childAbsolute, childRelative, findings);
813 -export type DocumentSource = Readonly<{ path
: string; html
: string }>;
814 -export type DocumentRecord = Readonly<{
816 - metadata
: DocumentMetadata;
818 -export type DocumentIndex = Readonly<{
819 - documents
: readonly DocumentRecord[];
820 - diagnostics
: readonly Diagnostic[];
484 +export function discoverDocumentBundles(root
: string)
: BundleDiscovery {
485 + const sources
: BundleDocumentSource[]
= [];
486 + const diagnostics
: Diagnostic[]
= [];
487 + const systemRoot
= path.
join(
root,
".system");
488 + if (
lstatSync(systemRoot, { throwIfNoEntry:
false })?.
isSymbolicLink())
493 + "bundle.symbolic-link",
495 + "Bundle path is a symbolic link: .system",
499 + for (
const directory
of Object.
values(DIRECTORY_BY_TYPE)) {
500 + const relativeDirectory
= `.system/${directory}`;
501 + const absoluteDirectory
= path.
join(
root, relativeDirectory);
502 + const directoryStats
= lstatSync(absoluteDirectory, {
503 + throwIfNoEntry:
false,
505 + if (
!directoryStats?.
isDirectory()
|| directoryStats.
isSymbolicLink())
507 + for (
const entry
of readdirSync(absoluteDirectory, {
508 + withFileTypes:
true,
509 + }).
sort((left, right)
=> left.
name.
localeCompare(right.
name))) {
510 + const bundleRelative
= `${relativeDirectory}/${entry.name}`;
511 + const bundleAbsolute
= path.
join(absoluteDirectory, entry.
name);
512 + const bundleStats
= lstatSync(bundleAbsolute, { throwIfNoEntry:
false });
513 + if (bundleStats?.
isSymbolicLink()) {
516 + "bundle.symbolic-link",
518 + `Bundle path is a symbolic link: ${bundleRelative}`,
523 + if (
!bundleStats?.
isDirectory()) {
526 + "bundle.expected-directory",
528 + `Expected a document bundle directory: ${bundleRelative}`,
533 + const indexRelative
= `${bundleRelative}/index.md`;
534 + const indexAbsolute
= path.
join(bundleAbsolute,
"index.md");
535 + const indexStats
= lstatSync(indexAbsolute, { throwIfNoEntry:
false });
539 + "bundle.missing-index",
541 + `Bundle is missing index.md: ${bundleRelative}`,
544 + else if (indexStats.
isSymbolicLink())
547 + "bundle.symbolic-link",
549 + `Bundle path is a symbolic link: ${indexRelative}`,
552 + else if (
!indexStats.
isFile())
555 + "bundle.expected-file",
557 + `Expected a regular index.md: ${indexRelative}`,
562 + path: indexRelative,
563 + markdown:
readFileSync(indexAbsolute,
"utf8"),
565 + scanBundleAssets(bundleAbsolute, bundleRelative, diagnostics);
569 + sources: sources.
sort((left, right)
=> left.path.
localeCompare(right.path)),
570 + diagnostics: diagnostics.
sort(compareDiagnostics),
823 574 const references = (
824 575 metadata
: DocumentMetadata,
825 -)
: readonly (
readonly [
string,
"spec" | "roadmap"])[]
=> {
576 +)
: readonly (
readonly [
string,
DocumentType])[]
=> {
826 577 switch (metadata.
type) {
828 579 return [[metadata.spec,
"spec"]];
831 582 [metadata.spec,
"spec"],
832 - ...(metadata.roadmap
? [[metadata.roadmap,
"roadmap"]
as const]
: []),
583 + ...(metadata.roadmap
? ([[metadata.roadmap,
"roadmap"]]
as const)
: []),
835 - return metadata.specs.
map((id)
=> [id,
"spec"]
as const);
586 + return metadata.specs.
map((spec)
=> [spec,
"spec"]
as const);
841 591 const diagnosticIdentity = (item
: Diagnostic)
=> 842 592 JSON.
stringify([item.path, item.
code, item.message]);
844 -export function validateDocumentCandidate(
845 - current
: readonly DocumentSource[],
846 - candidate
: DocumentSource,
594 +export function indexBundleDocuments(
595 + sources
: readonly BundleDocumentSource[],
848 -)
: readonly Diagnostic[] {
849 - const baseline
= new Set(
850 - indexDocuments(current, prefix).diagnostics.
map(diagnosticIdentity),
852 - const next
= indexDocuments(
853 - [
...current.
filter((source)
=> source.path
!== candidate.path), candidate],
856 - return next.diagnostics.
filter(
858 - item.path
=== candidate.path
|| 859 - (
!baseline.
has(
diagnosticIdentity(item))
&& 860 - item.
code !== "graph.duplicate-id"),
864 -export function indexDocuments(
865 - sources
: readonly DocumentSource[],
868 - const documents
: DocumentRecord[]
= [];
869 - const graphEligible
: DocumentRecord[]
= [];
597 +)
: BundleDocumentIndex {
598 + const documents
: BundleDocumentRecord[]
= [];
599 + const graphEligible
: BundleDocumentRecord[]
= [];
870 600 const diagnostics
: Diagnostic[]
= [];
871 601 for (
const item
of [
...sources].
sort((left, right)
=> 872 602 left.path.
localeCompare(right.path),
874 - const htmlDiagnostics
= validateAuthoredHtml(item.path, item.html);
875 - diagnostics.
push(
...htmlDiagnostics);
877 - const metadata
= parseDocumentMetadata(item.html, prefix);
878 - let filenameValid
= true;
605 + const parsed
= parseAuthoredDocument(item.markdown, prefix);
606 + let pathValid
= true;
880 - validateFilename(item.path, metadata, prefix);
608 + validateDocumentPath(item.path, parsed.metadata, prefix);
881 609 }
catch (error) {
882 - filenameValid
= false;
883 611 diagnostics.
push(
884 - diagnostic(
"document.filename", item.path, (error
as Error).message),
612 + diagnostic(
"document.path", item.path, (error
as Error).message),
887 - const record
= { path: item.path, metadata };
617 + metadata: parsed.metadata,
618 + frontmatter: parsed.frontmatter,
888 620 documents.
push(record);
889 - if (filenameValid
&& htmlDiagnostics.
length === 0)
890 - graphEligible.
push(record);
621 + if (pathValid) graphEligible.
push(record);
891 622 }
catch (error) {
892 - const value
= error
as SystemDocumentError;
623 + const value
= error
as SystemDocumentError | MarkdownDocumentError;
893 624 diagnostics.
push(
895 626 "document.metadata",
902 - const groups
= new Map<
string,
DocumentRecord[]>();
633 + const groups
= new Map<
string,
BundleDocumentRecord[]>();
903 634 for (
const document
of graphEligible)
904 635 groups.
set(
document.metadata.
id, [
905 636 ...(groups.
get(
document.metadata.
id)
?? []),
908 639 for (
const [id, records]
of groups) {
909 - if (records.
length > 1) {
910 - const paths
= records.
map((record)
=> record.path).
sort();
911 - for (
const record
of records)
914 - "graph.duplicate-id",
916 - `Duplicate ID ${id}: ${paths.join(", ")}`,
640 + if (records.
length < 2)
continue;
641 + const paths
= records.
map((record)
=> record.path).
sort();
642 + for (
const record
of records)
645 + "graph.duplicate-id",
647 + `Duplicate ID ${id}: ${paths.join(", ")}`,
921 651 const unique
= new Map(
923 - .
filter(([, records])
=> records.
length === 1)
924 - .
map(([id, records])
=> [id, records[
0]]),
652 + [
...groups].
flatMap(([id, records])
=> {
653 + const [record]
= records;
654 + return records.
length === 1 && record
? [[id, record]
as const]
: [];
926 657 for (
const document
of graphEligible) {
927 658 for (
const [targetId, expectedType]
of references(
document.metadata)) {
928 659 const referencedType
= parseDocumentId(targetId, prefix).
type;
929 660 const target
= unique.
get(targetId);
930 - if (referencedType
!== expectedType) {
661 + if (referencedType
!== expectedType)
931 662 diagnostics.
push(
933 664 "graph.forbidden-edge",
935 666 `${document.metadata.id} must reference ${expectedType}; ${targetId} is ${referencedType}`,
938 - }
else if (
!target) {
939 670 diagnostics.
push(
941 672 "graph.dangling-reference",
943 674 `${document.metadata.id} references missing ${targetId}`,
946 - }
else if (target.metadata.
type !== expectedType) {
677 + else if (target.metadata.
type !== expectedType)
947 678 diagnostics.
push(
949 680 "graph.forbidden-edge",
951 682 `${document.metadata.id} must reference ${expectedType}; ${targetId} is ${target.metadata.type}`,
956 686 if (
document.metadata.
type === "plan" && document.metadata.roadmap) {
957 687 const roadmap
= unique.
get(
document.metadata.roadmap);
959 689 roadmap?.metadata.
type === "roadmap" && 960 690 roadmap.metadata.spec
!== document.metadata.spec
962 692 diagnostics.
push(
964 694 "graph.forbidden-edge",
966 696 `${document.metadata.roadmap} belongs to ${roadmap.metadata.spec}, not ${document.metadata.spec}`,
972 701 return { documents, diagnostics: diagnostics.
sort(compareDiagnostics) };
704 +export function validateBundleCandidate(
705 + current
: readonly BundleDocumentSource[],
706 + candidate
: BundleDocumentSource,
708 +)
: readonly Diagnostic[] {
709 + const baseline
= new Set(
710 + indexBundleDocuments(current, prefix).diagnostics.
map(diagnosticIdentity),
712 + const next
= indexBundleDocuments(
713 + [
...current.
filter((source)
=> source.path
!== candidate.path), candidate],
716 + return next.diagnostics.
filter(
718 + item.path
=== candidate.path
|| 719 + (
!baseline.
has(
diagnosticIdentity(item))
&& 720 + item.
code !== "graph.duplicate-id"),