@sprig-and-prose/sprig-universe 0.1.0

package/test/universe-basic.test.js

@@ -0,0 +1,804 @@
+/**
+ * @fileoverview Basic tests for universe parser
+ */
+
+import { test } from 'node:test';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { parseFiles } from '../src/index.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const fixturesDir = join(__dirname, 'fixtures');
+
+test('parses amaranthine-mini.prose', () => {
+  const file = join(fixturesDir, 'amaranthine-mini.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  // Check universe exists
+  assert(graph.universes.Amaranthine !== undefined, 'Universe Amaranthine should exist');
+  assert(graph.universes.Amaranthine.name === 'Amaranthine', 'Universe name should match');
+
+  // Check nodes exist
+  const universeNodeId = graph.universes.Amaranthine.root;
+  const universeNode = graph.nodes[universeNodeId];
+  assert(universeNode !== undefined, 'Universe node should exist');
+  assert(universeNode.kind === 'universe', 'Universe node kind should be universe');
+  assert(universeNode.name === 'Amaranthine', 'Universe node name should match');
+
+  // Check series nodes
+  const playerNodeId = `${universeNodeId.split(':')[0]}:series:Player`;
+  const playerNode = graph.nodes[playerNodeId];
+  assert(playerNode !== undefined, 'Player series node should exist');
+  assert(playerNode.kind === 'series', 'Player node kind should be series');
+  assert(playerNode.name === 'Player', 'Player node name should match');
+  assert(playerNode.parent === universeNodeId, 'Player should be child of universe');
+
+  const itemNodeId = `${universeNodeId.split(':')[0]}:series:Item`;
+  const itemNode = graph.nodes[itemNodeId];
+  assert(itemNode !== undefined, 'Item series node should exist');
+
+  // Check book nodes
+  const equipmentNodeId = `${universeNodeId.split(':')[0]}:book:Equipment`;
+  const equipmentNode = graph.nodes[equipmentNodeId];
+  assert(equipmentNode !== undefined, 'Equipment book node should exist');
+  assert(equipmentNode.kind === 'book', 'Equipment node kind should be book');
+  assert(equipmentNode.container === itemNodeId, 'Equipment should be in Item');
+  assert('container' in equipmentNode, 'Book node should have container field');
+
+  // Check chapter node
+  const toolNodeId = `${universeNodeId.split(':')[0]}:chapter:Tool`;
+  const toolNode = graph.nodes[toolNodeId];
+  assert(toolNode !== undefined, 'Tool chapter node should exist');
+  assert(toolNode.kind === 'chapter', 'Tool node kind should be chapter');
+  assert(toolNode.container === equipmentNodeId, 'Tool should be in Equipment');
+  assert('container' in toolNode, 'Chapter node should have container field');
+
+  // Check describe blocks
+  assert(universeNode.describe !== undefined, 'Universe should have describe block');
+  assert(
+    universeNode.describe.raw.includes('persistent text-based roleplaying game'),
+    'Universe describe should contain expected text',
+  );
+  assert(universeNode.describe.source !== undefined, 'Describe should have source span');
+  assert(
+    universeNode.describe.normalized !== undefined,
+    'Describe block should have normalized field',
+  );
+  assert(
+    typeof universeNode.describe.normalized === 'string',
+    'Normalized field should be a string',
+  );
+
+  // Check references block (parsed correctly, not as unknown)
+  assert(playerNode.references !== undefined, 'Player should have references');
+  assert(playerNode.references.length > 0, 'Player should have at least one reference');
+  const ref = playerNode.references[0];
+  assert(ref !== undefined, 'Player should have a reference');
+  assert(ref.repository === 'amaranthine', 'Reference should have repository');
+  assert(ref.paths !== undefined, 'Reference should have paths');
+  assert(ref.paths.length > 0, 'Reference should have at least one path');
+  assert(ref.source !== undefined, 'Reference should have source location');
+
+  // Check source spans
+  assert(universeNode.source !== undefined, 'Universe node should have source span');
+  assert(universeNode.source.start !== undefined, 'Source span should have start');
+  assert(universeNode.source.end !== undefined, 'Source span should have end');
+  assert(
+    universeNode.source.start.offset < universeNode.source.end.offset,
+    'Source span offsets should be monotonic',
+  );
+});
+
+test('parses sprig-meta-mini.prose', () => {
+  const file = join(fixturesDir, 'sprig-meta-mini.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  // Check universe exists
+  assert(graph.universes.Sprig !== undefined, 'Universe Sprig should exist');
+
+  const universeNodeId = graph.universes.Sprig.root;
+  const universeNode = graph.nodes[universeNodeId];
+
+  // Check series nodes
+  const languageNodeId = `${universeNodeId.split(':')[0]}:series:Language`;
+  const structureNodeId = `${universeNodeId.split(':')[0]}:series:Structure`;
+  assert(graph.nodes[languageNodeId] !== undefined, 'Language series should exist');
+  assert(graph.nodes[structureNodeId] !== undefined, 'Structure series should exist');
+
+  // Check book nodes in Structure
+  const universeBookId = `${universeNodeId.split(':')[0]}:book:Universe`;
+  const universeBook = graph.nodes[universeBookId];
+  assert(universeBook !== undefined, 'Universe book should exist');
+  assert(universeBook.container === structureNodeId, 'Universe book should be in Structure');
+
+  // Check relates edges
+  const edgeKeys = Object.keys(graph.edges);
+  assert(edgeKeys.length >= 3, 'Should have at least 3 relates edges');
+
+  const universeSeriesEdge = edgeKeys.find((k) => k.includes('Universe--Series'));
+  assert(universeSeriesEdge !== undefined, 'Should have Universe--Series edge');
+  const edge = graph.edges[universeSeriesEdge];
+  assert(edge.kind === 'relates', 'Edge kind should be relates');
+  assert(edge.a.text === 'Universe', 'Edge A should be Universe');
+  assert(edge.b.text === 'Series', 'Edge B should be Series');
+  assert(edge.describe !== undefined, 'Edge should have describe block');
+  assert(edge.describe.raw.includes('composed'), 'Edge describe should contain expected text');
+  assert(
+    edge.describe.normalized !== undefined,
+    'Edge describe should have normalized field',
+  );
+
+  // Check edge resolution
+  assert(edge.a.target !== undefined, 'Edge A should be resolved');
+  assert(edge.b.target !== undefined, 'Edge B should be resolved');
+});
+
+test('preserves describe block formatting', () => {
+  const file = join(fixturesDir, 'amaranthine-mini.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  const universeNodeId = graph.universes.Amaranthine.root;
+  const universeNode = graph.nodes[universeNodeId];
+
+  // Check that newlines are preserved
+  assert(
+    universeNode.describe.raw.includes('\n'),
+    'Describe block should preserve newlines',
+  );
+  assert(
+    universeNode.describe.raw.includes('semi-afk game'),
+    'Describe block should preserve content',
+  );
+});
+
+test('handles multiple files', () => {
+  const file1 = join(fixturesDir, 'amaranthine-mini.prose');
+  const file2 = join(fixturesDir, 'sprig-meta-mini.prose');
+  const text1 = readFileSync(file1, 'utf-8');
+  const text2 = readFileSync(file2, 'utf-8');
+
+  const graph = parseFiles([
+    { file: file1, text: text1 },
+    { file: file2, text: text2 },
+  ]);
+
+  // Both universes should exist
+  assert(graph.universes.Amaranthine !== undefined, 'Amaranthine universe should exist');
+  assert(graph.universes.Sprig !== undefined, 'Sprig universe should exist');
+
+  // Nodes from both universes should exist
+  const amaranthineRoot = graph.universes.Amaranthine.root;
+  const sprigRoot = graph.universes.Sprig.root;
+  assert(graph.nodes[amaranthineRoot] !== undefined, 'Amaranthine root node should exist');
+  assert(graph.nodes[sprigRoot] !== undefined, 'Sprig root node should exist');
+});
+
+test('source spans are present and valid', () => {
+  const file = join(fixturesDir, 'amaranthine-mini.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  // Check all nodes have source spans
+  for (const nodeId in graph.nodes) {
+    const node = graph.nodes[nodeId];
+    assert(node.source !== undefined, `Node ${nodeId} should have source span`);
+    assert(node.source.file === file, `Node ${nodeId} source should reference correct file`);
+    assert(node.source.start !== undefined, `Node ${nodeId} source should have start`);
+    assert(node.source.end !== undefined, `Node ${nodeId} source should have end`);
+    assert(
+      node.source.start.offset <= node.source.end.offset,
+      `Node ${nodeId} source offsets should be monotonic`,
+    );
+  }
+
+  // Check all edges have source spans
+  for (const edgeId in graph.edges) {
+    const edge = graph.edges[edgeId];
+    assert(edge.source !== undefined, `Edge ${edgeId} should have source span`);
+  }
+});
+
+test('normalizes prose blocks with first-line-aware dedent', () => {
+  const file = join(fixturesDir, 'first-line-aware.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  const universeNodeId = graph.universes.Test.root;
+  const universeNode = graph.nodes[universeNodeId];
+
+  // Check universe describe: first line has 0 indent, subsequent lines indented
+  assert(
+    universeNode.describe !== undefined,
+    'Universe should have describe block',
+  );
+  const normalized = universeNode.describe.normalized;
+  assert(normalized !== undefined, 'Normalized should exist');
+  
+  const normalizedLines = normalized.split('\n');
+  // First line should remain unchanged (starts with "This")
+  assert(
+    normalizedLines[0].trim() === 'This is a test universe',
+    'First line should remain unchanged',
+  );
+  // Subsequent lines should have indentation removed
+  // Line 1 should be "with multiple lines" (no leading spaces after normalization)
+  assert(normalizedLines.length > 1, 'Should have at least 2 lines');
+  const secondLine = normalizedLines[1];
+  // The second line should have had its 4-space indent removed
+  assert(
+    secondLine === 'with multiple lines',
+    `Second line should be 'with multiple lines', got: ${JSON.stringify(secondLine)}`,
+  );
+  // But internal indentation should be preserved
+  const indentedLine = normalizedLines.find((l) => l.includes('and indented content'));
+  assert(
+    indentedLine !== undefined && indentedLine.includes('  '),
+    'Internal indentation should be preserved',
+  );
+
+  // Check series describe block
+  const seriesNodeId = `${universeNodeId.split(':')[0]}:series:Example`;
+  const seriesNode = graph.nodes[seriesNodeId];
+  assert(seriesNode !== undefined, 'Example series should exist');
+  assert(seriesNode.describe !== undefined, 'Series should have describe block');
+  
+  const seriesNormalized = seriesNode.describe.normalized;
+  assert(seriesNormalized !== undefined, 'Series normalized should exist');
+  
+  const seriesNormalizedLines = seriesNormalized.split('\n');
+  // First non-empty line should start with "This" (no leading spaces)
+  const firstSeriesLine = seriesNormalizedLines.find((l) => l.trim().length > 0);
+  assert(
+    firstSeriesLine !== undefined && firstSeriesLine.trim().startsWith('This'),
+    'First line should start flush-left',
+  );
+  // Subsequent lines should have common indent removed
+  // The minimum indent (4 spaces) should be removed from all lines
+  // Line 1 has 8 spaces, so after removing 4, it should have 4 spaces remaining
+  // But we check that at least some indent was removed (it shouldn't start with 8 spaces)
+  const secondSeriesLine = seriesNormalizedLines[1]; // Second line
+  assert(
+    secondSeriesLine !== undefined,
+    'Should have a second line',
+  );
+  // After normalization, line 1 should have less indent than the raw (8 -> 4 spaces)
+  // So it should NOT start with 8 spaces (which would be '        ')
+  assert(
+    !secondSeriesLine.startsWith('        '),
+    `Subsequent lines should have some indentation removed, got: ${JSON.stringify(secondSeriesLine)}`,
+  );
+
+  // Check single-line describe (should remain unchanged)
+  const singleLineNodeId = `${universeNodeId.split(':')[0]}:book:SingleLine`;
+  const singleLineNode = graph.nodes[singleLineNodeId];
+  assert(singleLineNode !== undefined, 'SingleLine book should exist');
+  assert(singleLineNode.describe !== undefined, 'SingleLine should have describe block');
+  const singleLineNormalized = singleLineNode.describe.normalized;
+  // Single line should remain unchanged (no lines after first non-empty line)
+  assert(
+    singleLineNormalized === singleLineNode.describe.raw,
+    'Single-line describe should remain unchanged',
+  );
+
+  // Check all-indented describe (all lines share same indent)
+  const allIndentedNodeId = `${universeNodeId.split(':')[0]}:book:AllIndented`;
+  const allIndentedNode = graph.nodes[allIndentedNodeId];
+  assert(allIndentedNode !== undefined, 'AllIndented book should exist');
+  assert(allIndentedNode.describe !== undefined, 'AllIndented should have describe block');
+  const allIndentedNormalized = allIndentedNode.describe.normalized;
+  const allIndentedNormalizedLines = allIndentedNormalized.split('\n');
+  // First non-empty line should have indent removed
+  const firstAllIndentedLine = allIndentedNormalizedLines.find((l) => l.trim().length > 0);
+  assert(
+    firstAllIndentedLine !== undefined && !firstAllIndentedLine.startsWith('      '),
+    'First line should have indent removed',
+  );
+});
+
+test('emits warnings for unresolved relates endpoints', () => {
+  const file = join(fixturesDir, 'unresolved-relates.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  // Should have warnings for unresolved endpoint
+  const warnings = graph.diagnostics.filter((d) => d.severity === 'warning');
+  const unresolvedWarnings = warnings.filter((w) =>
+    w.message.includes('Unresolved relates endpoint'),
+  );
+  assert(
+    unresolvedWarnings.length > 0,
+    'Should have warnings for unresolved relates endpoints',
+  );
+  
+  const nonexistentWarning = unresolvedWarnings.find((w) =>
+    w.message.includes('Nonexistent'),
+  );
+  assert(
+    nonexistentWarning !== undefined,
+    'Should have warning for Nonexistent endpoint',
+  );
+  assert(
+    nonexistentWarning.source !== undefined,
+    'Warning should have source span',
+  );
+
+  // Edge should still exist with unresolved target
+  const edgeKeys = Object.keys(graph.edges);
+  const unresolvedEdge = edgeKeys.find((k) => k.includes('Nonexistent'));
+  assert(unresolvedEdge !== undefined, 'Edge with unresolved endpoint should exist');
+  
+  const edge = graph.edges[unresolvedEdge];
+  assert(edge.a.target !== undefined, 'Edge A should be resolved');
+  assert(edge.b.target === undefined, 'Edge B should be unresolved');
+});
+
+test('emits warnings for duplicate node names', () => {
+  const file = join(fixturesDir, 'duplicate-names.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  // Should have warnings for duplicate names
+  const warnings = graph.diagnostics.filter((d) => d.severity === 'warning');
+  const duplicateWarnings = warnings.filter((w) =>
+    w.message.includes('Duplicate concept name'),
+  );
+  assert(
+    duplicateWarnings.length >= 2,
+    'Should have warnings for duplicate concept names',
+  );
+  
+  const duplicateSeriesWarning = duplicateWarnings.find((w) =>
+    w.message.includes('Duplicate') && w.message.includes('series'),
+  );
+  assert(
+    duplicateSeriesWarning !== undefined,
+    'Should have warning for duplicate series name',
+  );
+  assert(
+    duplicateSeriesWarning.source !== undefined,
+    'Warning should have source span',
+  );
+  // Verify the warning shows both kinds
+  assert(
+    duplicateSeriesWarning.message.includes('already defined as series'),
+    'Warning should show the first occurrence kind',
+  );
+  assert(
+    duplicateSeriesWarning.message.includes('now also defined as series'),
+    'Warning should show the duplicate kind',
+  );
+
+  // Note: Duplicate nodes have the same ID, so the second overwrites the first in the nodes map
+  // But both are processed and warnings are emitted. The nameMap resolves to the first encountered.
+  const universeNodeId = graph.universes.Test.root;
+  const universePrefix = universeNodeId.split(':')[0];
+  const duplicateId = `${universePrefix}:series:Duplicate`;
+  const duplicateNode = graph.nodes[duplicateId];
+  assert(duplicateNode !== undefined, 'Duplicate node should exist (second overwrites first)');
+  
+  // Check that duplicate book names also produce warnings
+  const duplicateBookWarnings = duplicateWarnings.filter((w) =>
+    w.message.includes('Book1') && w.message.includes('book'),
+  );
+  assert(
+    duplicateBookWarnings.length > 0,
+    'Should have warning for duplicate book names',
+  );
+  // Verify the warning shows both kinds
+  assert(
+    duplicateBookWarnings[0].message.includes('already defined as book'),
+    'Warning should show the first occurrence kind for books',
+  );
+  assert(
+    duplicateBookWarnings[0].message.includes('now also defined as book'),
+    'Warning should show the duplicate kind for books',
+  );
+});
+
+test('merges multiple files with same universe name', () => {
+  const fileA = join(fixturesDir, 'multi-file-universe-a.prose');
+  const fileB = join(fixturesDir, 'multi-file-universe-b.prose');
+  const textA = readFileSync(fileA, 'utf-8');
+  const textB = readFileSync(fileB, 'utf-8');
+  const graph = parseFiles([
+    { file: fileA, text: textA },
+    { file: fileB, text: textB },
+  ]);
+
+  // Should have exactly one universe
+  assert(Object.keys(graph.universes).length === 1, 'Should have exactly one universe');
+  assert(graph.universes.Amaranthine !== undefined, 'Universe Amaranthine should exist');
+
+  const universeNodeId = graph.universes.Amaranthine.root;
+  const universeNode = graph.nodes[universeNodeId];
+  assert(universeNode !== undefined, 'Universe node should exist');
+
+  // Both series should exist (merged from both files)
+  const itemsNodeId = `${universeNodeId.split(':')[0]}:series:Items`;
+  const skillsNodeId = `${universeNodeId.split(':')[0]}:series:Skills`;
+  assert(graph.nodes[itemsNodeId] !== undefined, 'Items series should exist');
+  assert(graph.nodes[skillsNodeId] !== undefined, 'Skills series should exist');
+
+  // References should be merged (both files had references)
+  assert(universeNode.references !== undefined, 'Universe should have references');
+  assert(universeNode.references.length === 2, 'Universe should have 2 references (one from each file)');
+
+  // No errors should be present
+  const errors = graph.diagnostics.filter((d) => d.severity === 'error');
+  assert(errors.length === 0, `Should have no errors, but found: ${errors.map((e) => e.message).join('; ')}`);
+});
+
+test('errors on conflicting universe names', () => {
+  const fileA = join(fixturesDir, 'conflicting-universes-a.prose');
+  const fileB = join(fixturesDir, 'conflicting-universes-b.prose');
+  const textA = readFileSync(fileA, 'utf-8');
+  const textB = readFileSync(fileB, 'utf-8');
+  const graph = parseFiles([
+    { file: fileA, text: textA },
+    { file: fileB, text: textB },
+  ]);
+
+  // Should have error about multiple universes
+  const errors = graph.diagnostics.filter((d) => d.severity === 'error');
+  const universeError = errors.find((e) => e.message.includes('Multiple distinct universes'));
+  assert(universeError !== undefined, 'Should have error about multiple distinct universes');
+  assert(
+    universeError.message.includes('Amaranthine'),
+    'Error should mention Amaranthine universe',
+  );
+  assert(
+    universeError.message.includes('OtherUniverse'),
+    'Error should mention OtherUniverse universe',
+  );
+});
+
+test('errors on conflicting describe blocks', () => {
+  const fileA = join(fixturesDir, 'amaranthine-mini.prose');
+  const fileB = join(fixturesDir, 'multi-file-universe-conflict-desc.prose');
+  const textA = readFileSync(fileA, 'utf-8');
+  const textB = readFileSync(fileB, 'utf-8');
+  const graph = parseFiles([
+    { file: fileA, text: textA },
+    { file: fileB, text: textB },
+  ]);
+
+  // Should have error about conflicting describe blocks
+  const errors = graph.diagnostics.filter((d) => d.severity === 'error');
+  const describeError = errors.find((e) => e.message.includes('multiple describe blocks'));
+  assert(describeError !== undefined, 'Should have error about multiple describe blocks');
+  assert(
+    describeError.message.includes('Amaranthine'),
+    'Error should mention universe name',
+  );
+  assert(describeError.source !== undefined, 'Error should have source location');
+});
+
+test('errors on conflicting title blocks', () => {
+  const fileA = join(fixturesDir, 'multi-file-universe-with-title.prose');
+  const fileB = join(fixturesDir, 'multi-file-universe-conflict-title.prose');
+  const textA = readFileSync(fileA, 'utf-8');
+  const textB = readFileSync(fileB, 'utf-8');
+  const graph = parseFiles([
+    { file: fileA, text: textA },
+    { file: fileB, text: textB },
+  ]);
+
+  // Should have error about conflicting title blocks
+  const errors = graph.diagnostics.filter((d) => d.severity === 'error');
+  const titleError = errors.find((e) => e.message.includes('multiple title blocks'));
+  assert(titleError !== undefined, 'Should have error about multiple title blocks');
+  assert(
+    titleError.message.includes('Amaranthine'),
+    'Error should mention universe name',
+  );
+  assert(titleError.source !== undefined, 'Error should have source location');
+});
+
+test('preserves source locations for merged content', () => {
+  const fileA = join(fixturesDir, 'multi-file-universe-a.prose');
+  const fileB = join(fixturesDir, 'multi-file-universe-b.prose');
+  const textA = readFileSync(fileA, 'utf-8');
+  const textB = readFileSync(fileB, 'utf-8');
+  const graph = parseFiles([
+    { file: fileA, text: textA },
+    { file: fileB, text: textB },
+  ]);
+
+  const universeNodeId = graph.universes.Amaranthine.root;
+  const universeNode = graph.nodes[universeNodeId];
+
+  // References should preserve source locations from their respective files
+  assert(universeNode.references !== undefined, 'Universe should have references');
+  assert(universeNode.references.length === 2, 'Should have 2 references');
+  
+  // Check that references have source locations
+  for (const ref of universeNode.references) {
+    assert(ref.source !== undefined, 'Reference should have source location');
+    assert(ref.source.file !== undefined, 'Reference source should have file path');
+  }
+
+  // Series nodes should preserve source locations
+  const itemsNodeId = `${universeNodeId.split(':')[0]}:series:Items`;
+  const skillsNodeId = `${universeNodeId.split(':')[0]}:series:Skills`;
+  assert(graph.nodes[itemsNodeId].source !== undefined, 'Items series should have source');
+  assert(graph.nodes[itemsNodeId].source.file === fileA, 'Items series should be from fileA');
+  assert(graph.nodes[skillsNodeId].source !== undefined, 'Skills series should have source');
+  assert(graph.nodes[skillsNodeId].source.file === fileB, 'Skills series should be from fileB');
+});
+
+test('deterministic output order', () => {
+  const fileA = join(fixturesDir, 'multi-file-universe-a.prose');
+  const fileB = join(fixturesDir, 'multi-file-universe-b.prose');
+  const textA = readFileSync(fileA, 'utf-8');
+  const textB = readFileSync(fileB, 'utf-8');
+
+  // Parse in one order
+  const graph1 = parseFiles([
+    { file: fileA, text: textA },
+    { file: fileB, text: textB },
+  ]);
+
+  // Parse in reverse order
+  const graph2 = parseFiles([
+    { file: fileB, text: textB },
+    { file: fileA, text: textA },
+  ]);
+
+  // Both should have the same universe
+  assert(graph1.universes.Amaranthine !== undefined, 'Graph1 should have Amaranthine');
+  assert(graph2.universes.Amaranthine !== undefined, 'Graph2 should have Amaranthine');
+
+  // Both should have the same series (order may differ, but both should exist)
+  const universeNodeId1 = graph1.universes.Amaranthine.root;
+  const universeNodeId2 = graph2.universes.Amaranthine.root;
+  const itemsNodeId = `${universeNodeId1.split(':')[0]}:series:Items`;
+  const skillsNodeId = `${universeNodeId1.split(':')[0]}:series:Skills`;
+  
+  assert(graph1.nodes[itemsNodeId] !== undefined, 'Graph1 should have Items');
+  assert(graph1.nodes[skillsNodeId] !== undefined, 'Graph1 should have Skills');
+  assert(graph2.nodes[itemsNodeId] !== undefined, 'Graph2 should have Items');
+  assert(graph2.nodes[skillsNodeId] !== undefined, 'Graph2 should have Skills');
+
+  // References should be merged in both (order may differ, but count should match)
+  assert(
+    graph1.nodes[universeNodeId1].references?.length === 2,
+    'Graph1 should have 2 references',
+  );
+  assert(
+    graph2.nodes[universeNodeId2].references?.length === 2,
+    'Graph2 should have 2 references',
+  );
+});
+
+test('parses named reference blocks at universe scope', () => {
+  const file = join(fixturesDir, 'named-reference.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  // Check universe exists
+  assert(graph.universes.Test !== undefined, 'Universe Test should exist');
+
+  const universeNodeId = graph.universes.Test.root;
+  const universeNode = graph.nodes[universeNodeId];
+  assert(universeNode !== undefined, 'Universe node should exist');
+
+  // Check named reference exists in registry
+  assert(graph.referencesByName !== undefined, 'referencesByName registry should exist');
+  assert(graph.referencesByName.Test !== undefined, 'Universe Test should have referencesByName');
+  assert(graph.referencesByName.Test.ItemRouter !== undefined, 'ItemRouter named reference should exist');
+
+  const namedRef = graph.referencesByName.Test.ItemRouter;
+  assert(namedRef.name === 'ItemRouter', 'Named reference should have correct name');
+  assert(namedRef.repository === 'amaranthine-backend', 'Named reference should have repository');
+  assert(namedRef.paths.length === 1, 'Named reference should have paths');
+  assert(namedRef.paths[0] === '/src/routers/items.ts', 'Named reference should have correct path');
+  assert(namedRef.describe !== undefined, 'Named reference should have describe');
+  assert(namedRef.describe.raw.includes('Routes that implement item endpoints'), 'Named reference describe should contain expected text');
+  assert(namedRef.source !== undefined, 'Named reference should have source location');
+
+  // Check that inline reference still works
+  const itemsNodeId = `${universeNodeId.split(':')[0]}:series:Items`;
+  const itemsNode = graph.nodes[itemsNodeId];
+  assert(itemsNode !== undefined, 'Items series should exist');
+  assert(itemsNode.references !== undefined, 'Items series should have references');
+  assert(itemsNode.references.length === 1, 'Items series should have one inline reference');
+  assert(itemsNode.references[0].repository === 'amaranthine-backend', 'Inline reference should have repository');
+});
+
+test('parses named document blocks at universe scope', () => {
+  const file = join(fixturesDir, 'named-document.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  // Check universe exists
+  assert(graph.universes.Test !== undefined, 'Universe Test should exist');
+
+  const universeNodeId = graph.universes.Test.root;
+
+  // Check named document exists in registry
+  assert(graph.documentsByName !== undefined, 'documentsByName registry should exist');
+  assert(graph.documentsByName.Test !== undefined, 'Universe Test should have documentsByName');
+  assert(graph.documentsByName.Test.ItemsDesignDoc !== undefined, 'ItemsDesignDoc named document should exist');
+
+  const namedDoc = graph.documentsByName.Test.ItemsDesignDoc;
+  assert(namedDoc.name === 'ItemsDesignDoc', 'Named document should have correct name');
+  assert(namedDoc.kind === 'internal', 'Named document should have kind');
+  assert(namedDoc.path === '/docs/items/overview.md', 'Named document should have path');
+  assert(namedDoc.describe !== undefined, 'Named document should have describe');
+  assert(namedDoc.describe.raw.includes('High-level items design notes'), 'Named document describe should contain expected text');
+  assert(namedDoc.source !== undefined, 'Named document should have source location');
+
+  // Check that inline document still works
+  const itemsNodeId = `${universeNodeId.split(':')[0]}:series:Items`;
+  const itemsNode = graph.nodes[itemsNodeId];
+  assert(itemsNode !== undefined, 'Items series should exist');
+  assert(itemsNode.documentation !== undefined, 'Items series should have documentation');
+  assert(itemsNode.documentation.length === 1, 'Items series should have one inline document');
+  assert(itemsNode.documentation[0].kind === 'internal', 'Inline document should have kind');
+});
+
+test('detects duplicate named reference and document names', () => {
+  const file = join(fixturesDir, 'named-duplicate.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  // Should have errors for duplicate names (2 errors per duplicate: one for duplicate, one pointing to first)
+  const errors = graph.diagnostics.filter((d) => d.severity === 'error');
+  const duplicateRefErrors = errors.filter((e) => e.message.includes('Duplicate named reference') || e.message.includes('First declaration of named reference'));
+  const duplicateDocErrors = errors.filter((e) => e.message.includes('Duplicate named document') || e.message.includes('First declaration of named document'));
+
+  assert(duplicateRefErrors.length >= 2, `Should have errors for duplicate named reference (duplicate + first declaration), got ${duplicateRefErrors.length}: ${duplicateRefErrors.map(e => e.message).join('; ')}`);
+  assert(duplicateDocErrors.length >= 2, `Should have errors for duplicate named document (duplicate + first declaration), got ${duplicateDocErrors.length}: ${duplicateDocErrors.map(e => e.message).join('; ')}`);
+
+  // Check that error messages include both locations
+  const refError = duplicateRefErrors.find((e) => e.message.includes('ItemRouter') && e.message.includes('Duplicate'));
+  assert(refError !== undefined, 'Should have error for duplicate ItemRouter');
+  assert(refError.source !== undefined, 'Error should have source location');
+  assert(refError.message.includes('First declared at'), 'Error should mention first declaration location');
+
+  const docError = duplicateDocErrors.find((e) => e.message.includes('ItemsDesignDoc') && e.message.includes('Duplicate'));
+  assert(docError !== undefined, 'Should have error for duplicate ItemsDesignDoc');
+  assert(docError.source !== undefined, 'Error should have source location');
+  assert(docError.message.includes('First declared at'), 'Error should mention first declaration location');
+});
+
+test('preserves source locations for named blocks', () => {
+  const file = join(fixturesDir, 'named-reference.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  const namedRef = graph.referencesByName.Test.ItemRouter;
+  assert(namedRef.source !== undefined, 'Named reference should have source');
+  assert(namedRef.source.file === file, 'Named reference source should reference correct file');
+  assert(namedRef.source.start !== undefined, 'Named reference source should have start');
+  assert(namedRef.source.end !== undefined, 'Named reference source should have end');
+  assert(namedRef.source.start.offset < namedRef.source.end.offset, 'Source offsets should be monotonic');
+
+  const file2 = join(fixturesDir, 'named-document.prose');
+  const text2 = readFileSync(file2, 'utf-8');
+  const graph2 = parseFiles([{ file: file2, text: text2 }]);
+
+  const namedDoc = graph2.documentsByName.Test.ItemsDesignDoc;
+  assert(namedDoc.source !== undefined, 'Named document should have source');
+  assert(namedDoc.source.file === file2, 'Named document source should reference correct file');
+  assert(namedDoc.source.start !== undefined, 'Named document source should have start');
+  assert(namedDoc.source.end !== undefined, 'Named document source should have end');
+});
+
+test('parses using blocks in references', () => {
+  const file = join(fixturesDir, 'using-in-references.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  // Check universe exists
+  assert(graph.universes.Test !== undefined, 'Universe Test should exist');
+
+  const universeNodeId = graph.universes.Test.root;
+
+  // Check that named references exist
+  assert(graph.referencesByName.Test.ItemRouter !== undefined, 'ItemRouter named reference should exist');
+  assert(graph.referencesByName.Test.PlayerRouter !== undefined, 'PlayerRouter named reference should exist');
+
+  // Check Items series has using block resolved
+  const itemsNodeId = `${universeNodeId.split(':')[0]}:series:Items`;
+  const itemsNode = graph.nodes[itemsNodeId];
+  assert(itemsNode !== undefined, 'Items series should exist');
+  assert(itemsNode.references !== undefined, 'Items series should have references');
+  assert(itemsNode.references.length === 1, 'Items series should have one reference from using');
+  assert(itemsNode.references[0].repository === 'amaranthine-backend', 'Resolved reference should have repository');
+  assert(itemsNode.references[0].paths[0] === '/src/routers/items.ts', 'Resolved reference should have correct path');
+  assert(itemsNode.references[0].describe !== undefined, 'Resolved reference should have describe');
+});
+
+test('parses mixed inline and using blocks in references', () => {
+  const file = join(fixturesDir, 'using-in-references.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  const universeNodeId = graph.universes.Test.root;
+
+  // Check Players series has both inline and using references
+  const playersNodeId = `${universeNodeId.split(':')[0]}:series:Players`;
+  const playersNode = graph.nodes[playersNodeId];
+  assert(playersNode !== undefined, 'Players series should exist');
+  assert(playersNode.references !== undefined, 'Players series should have references');
+  assert(playersNode.references.length === 2, 'Players series should have 2 references (inline + using)');
+  
+  // First should be inline reference
+  assert(playersNode.references[0].repository === 'amaranthine-backend', 'First reference should have repository');
+  assert(playersNode.references[0].paths[0] === '/src/players/helpers.ts', 'First reference should be inline');
+  
+  // Second should be resolved from using
+  assert(playersNode.references[1].repository === 'amaranthine-backend', 'Second reference should have repository');
+  assert(playersNode.references[1].paths[0] === '/src/routers/players.ts', 'Second reference should be from using');
+});
+
+test('parses multiple names in using block', () => {
+  const file = join(fixturesDir, 'using-in-references.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  const universeNodeId = graph.universes.Test.root;
+
+  // Check Mixed series has multiple references from single using block
+  const mixedNodeId = `${universeNodeId.split(':')[0]}:series:Mixed`;
+  const mixedNode = graph.nodes[mixedNodeId];
+  assert(mixedNode !== undefined, 'Mixed series should exist');
+  assert(mixedNode.references !== undefined, 'Mixed series should have references');
+  assert(mixedNode.references.length === 2, 'Mixed series should have 2 references from using block');
+  
+  // Both should be resolved
+  assert(mixedNode.references[0].paths[0] === '/src/routers/items.ts', 'First reference should be ItemRouter');
+  assert(mixedNode.references[1].paths[0] === '/src/routers/players.ts', 'Second reference should be PlayerRouter');
+});
+
+test('errors on unknown reference name in using block', () => {
+  const file = join(fixturesDir, 'using-unknown.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  // Should have error for unknown reference
+  const errors = graph.diagnostics.filter((d) => d.severity === 'error');
+  const unknownRefErrors = errors.filter((e) => e.message.includes('Unknown reference'));
+  
+  assert(unknownRefErrors.length > 0, 'Should have error for unknown reference');
+  const error = unknownRefErrors.find((e) => e.message.includes('UnknownRouter'));
+  assert(error !== undefined, 'Should have error for UnknownRouter');
+  assert(error.source !== undefined, 'Error should have source location');
+  assert(error.message.includes("Unknown reference 'UnknownRouter'"), 'Error message should mention UnknownRouter');
+});
+
+test('inline references still work unchanged', () => {
+  const file = join(fixturesDir, 'amaranthine-mini.prose');
+  const text = readFileSync(file, 'utf-8');
+  const graph = parseFiles([{ file, text }]);
+
+  const universeNodeId = graph.universes.Amaranthine.root;
+
+  // Check Player series has inline references (baseline)
+  const playerNodeId = `${universeNodeId.split(':')[0]}:series:Player`;
+  const playerNode = graph.nodes[playerNodeId];
+  assert(playerNode !== undefined, 'Player series should exist');
+  assert(playerNode.references !== undefined, 'Player should have references');
+  assert(playerNode.references.length === 1, 'Player should have one inline reference');
+  assert(playerNode.references[0].repository === 'amaranthine', 'Inline reference should have repository');
+  assert(playerNode.references[0].paths[0] === '/backends/api/src/routers/players.js', 'Inline reference should have path');
+});
+
+/**
+ * Simple assertion helper
+ * @param {boolean} condition
+ * @param {string} message
+ */
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+