@sprig-and-prose/sprig-universe 0.1.1 → 0.3.0

package/test/fixtures/amaranthine-mini.prose

@@ -5,6 +5,18 @@ universe Amaranthine {
     progress your character.
   }
 
+  repository AmaranthineRepo {
+    url { 'https://example.com/amaranthine' }
+  }
+
+  reference PlayerRouter in AmaranthineRepo {
+    paths { '/backends/api/src/routers/players.js' }
+  }
+
+  reference ItemData in AmaranthineRepo {
+    paths { '/data/items/*.yaml' }
+  }
+
   series Player {
     describe {
       The player is central to everything. From chat to skills to inventory,
@@ -12,10 +24,7 @@ universe Amaranthine {
     }
 
     references {
-      reference {
-        repository { 'amaranthine' }
-        paths { '/backends/api/src/routers/players.js' }
-      }
+      PlayerRouter
     }
   }
 
@@ -25,10 +34,7 @@ universe Amaranthine {
     }
 
     references {
-      reference {
-        repository { 'amaranthine' }
-        paths { '/data/items/*.yaml' }
-      }
+      ItemData
     }
   }
 

package/test/fixtures/multi-file-universe-a.prose

@@ -1,4 +1,12 @@
 universe Amaranthine {
+  repository AmaranthineRepo {
+    url { 'https://example.com/amaranthine' }
+  }
+
+  reference ItemsData in AmaranthineRepo {
+    paths { '/data/items.yaml' }
+  }
+
   series Items {
     describe {
       Items are objects that can exist in the world.
@@ -6,10 +14,7 @@ universe Amaranthine {
   }
 
   references {
-    reference {
-      repository { 'amaranthine' }
-      paths { '/data/items.yaml' }
-    }
+    ItemsData
   }
 }
 

package/test/fixtures/multi-file-universe-b.prose

@@ -1,4 +1,8 @@
 universe Amaranthine {
+  reference SkillsData in AmaranthineRepo {
+    paths { '/data/skills.yaml' }
+  }
+
   series Skills {
     describe {
       Skills represent abilities that players can learn.
@@ -6,10 +10,7 @@ universe Amaranthine {
   }
 
   references {
-    reference {
-      repository { 'amaranthine' }
-      paths { '/data/skills.yaml' }
-    }
+    SkillsData
   }
 }
 

package/test/fixtures/named-duplicate.prose

@@ -1,11 +1,13 @@
 universe Test {
-  reference ItemRouter {
-    repository { 'amaranthine-backend' }
+  repository BackendRepo {
+    url { 'https://example.com/backend' }
+  }
+
+  reference ItemRouter in BackendRepo {
     paths { '/src/routers/items.ts' }
   }
 
-  reference ItemRouter {
-    repository { 'amaranthine-backend' }
+  reference ItemRouter in BackendRepo {
     paths { '/src/routers/items-v2.ts' }
   }
 

package/test/fixtures/reference-attachments.prose

@@ -0,0 +1,19 @@
+universe Test {
+  repository Repo {
+    url { 'https://example.com/base' }
+  }
+
+  reference Alpha in Repo {
+    paths { '/alpha' }
+  }
+
+  reference Beta in Repo {
+    paths { '/beta' }
+  }
+
+  concept Widget {
+    references { Alpha Beta }
+  }
+}
+
+

package/test/fixtures/reference-commas.prose

@@ -0,0 +1,15 @@
+universe Test {
+  repository Repo {
+    url { 'https://example.com' }
+  }
+
+  reference PathsRef in Repo {
+    paths { '/a', '/b', '/c' }
+  }
+
+  series Things {
+    references { PathsRef, }
+  }
+}
+
+

package/test/fixtures/reference-inline.prose

@@ -0,0 +1,14 @@
+universe Test {
+  repository Repo {
+    url { 'https://example.com/base' }
+  }
+
+  concept Widget {
+    reference in Repo {
+      paths { '/widgets/loader.js' }
+      kind { 'data loader' }
+    }
+  }
+}
+
+

package/test/fixtures/reference-raw-url.prose

@@ -0,0 +1,9 @@
+universe Test {
+  reference ConfluenceDoc {
+    url { 'https://example.com/docs/confluence' }
+    kind { 'documentation' }
+    title { 'Confluence Doc' }
+  }
+}
+
+

package/test/fixtures/reference-repo-paths.prose

@@ -0,0 +1,11 @@
+universe Test {
+  repository ExternalRepo {
+    url { 'https://example.com/base/' }
+  }
+
+  reference DataFiles in ExternalRepo {
+    paths { '/data/items' 'data/other' }
+  }
+}
+
+

package/test/fixtures/reference-unknown.prose

@@ -0,0 +1,7 @@
+universe Test {
+  concept Widget {
+    references { MissingRef }
+  }
+}
+
+

package/test/references.test.js

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Tests for repositories + references
+ */
+
+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');
+
+function loadGraph(fixtureName) {
+  const file = join(fixturesDir, fixtureName);
+  const text = readFileSync(file, 'utf-8');
+  return parseFiles([{ file, text }]);
+}
+
+test('raw url reference parses with computed urls', () => {
+  const graph = loadGraph('reference-raw-url.prose');
+  const ref = graph.references['Test:reference:ConfluenceDoc'];
+  assert(ref !== undefined, 'Reference should exist');
+  assert(ref.urls.length === 1, 'Reference should have one URL');
+  assert(
+    ref.urls[0] === 'https://example.com/docs/confluence',
+    'Reference should preserve raw URL',
+  );
+});
+
+test('repository references compute urls with join rules', () => {
+  const graph = loadGraph('reference-repo-paths.prose');
+  const ref = graph.references['Test:reference:DataFiles'];
+  assert(ref !== undefined, 'Reference should exist');
+  assert(ref.urls.length === 2, 'Reference should have two URLs');
+  assert(
+    ref.urls[0] === 'https://example.com/base/data/items',
+    'Reference should join base + leading-slash path',
+  );
+  assert(
+    ref.urls[1] === 'https://example.com/base/data/other',
+    'Reference should join base + non-leading path',
+  );
+});
+
+test('commas are ignored in paths and references lists', () => {
+  const graph = loadGraph('reference-commas.prose');
+  const ref = graph.references['Test:reference:PathsRef'];
+  assert(ref !== undefined, 'Reference should exist');
+  assert(ref.paths.length === 3, 'Paths list should contain 3 entries');
+
+  const seriesNode = graph.nodes['Test:series:Things'];
+  assert(seriesNode !== undefined, 'Series node should exist');
+  assert(seriesNode.references?.length === 1, 'Series should have one reference attached');
+  assert(seriesNode.references[0] === 'Test:reference:PathsRef', 'Reference ID should resolve');
+});
+
+test('references list attaches to concepts and resolves', () => {
+  const graph = loadGraph('reference-attachments.prose');
+  const conceptNode = graph.nodes['Test:concept:Widget'];
+  assert(conceptNode !== undefined, 'Concept node should exist');
+  assert(conceptNode.references?.length === 2, 'Concept should have two references');
+  assert(
+    conceptNode.references.includes('Test:reference:Alpha'),
+    'Concept should include Alpha reference',
+  );
+  assert(
+    conceptNode.references.includes('Test:reference:Beta'),
+    'Concept should include Beta reference',
+  );
+});
+
+test('unknown reference names emit a calm error but do not crash', () => {
+  const graph = loadGraph('reference-unknown.prose');
+  const errors = graph.diagnostics.filter((d) => d.severity === 'error');
+  const unknownErrors = errors.filter((e) => e.message.includes('Unknown reference'));
+  assert(unknownErrors.length > 0, 'Should have error for unknown reference');
+  assert(graph.universes.Test !== undefined, 'Graph should still be constructed');
+});
+
+test('inline reference in block attaches with derived name', () => {
+  const graph = loadGraph('reference-inline.prose');
+  const conceptNode = graph.nodes['Test:concept:Widget'];
+  assert(conceptNode !== undefined, 'Concept node should exist');
+  assert(conceptNode.references?.length === 1, 'Concept should have one reference');
+  const refId = conceptNode.references[0];
+  const ref = graph.references[refId];
+  assert(ref !== undefined, 'Reference should exist');
+  assert(ref.urls.length === 1, 'Reference should have one URL');
+});
+
+/**
+ * Simple assertion helper
+ * @param {boolean} condition
+ * @param {string} message
+ */
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+

package/test/universe-basic.test.js

@@ -73,15 +73,19 @@ test('parses amaranthine-mini.prose', () => {
     'Normalized field should be a string',
   );
 
-  // Check references block (parsed correctly, not as unknown)
+  // Check references list
   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');
+  const refId = playerNode.references[0];
+  assert(refId !== undefined, 'Player should have a reference id');
+  const ref = graph.references[refId];
+  assert(ref !== undefined, 'Reference should exist in graph');
+  assert(ref.name === 'PlayerRouter', 'Reference should have correct name');
+  assert(ref.urls.length === 1, 'Reference should have one URL');
+  assert(
+    ref.urls[0] === 'https://example.com/amaranthine/backends/api/src/routers/players.js',
+    'Reference should have correct computed URL',
+  );
 
   // Check source spans
   assert(universeNode.source !== undefined, 'Universe node should have source span');
@@ -428,6 +432,9 @@ test('merges multiple files with same universe name', () => {
   // 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)');
+  for (const refId of universeNode.references) {
+    assert(graph.references[refId] !== undefined, 'Reference id should resolve');
+  }
 
   // No errors should be present
   const errors = graph.diagnostics.filter((d) => d.severity === 'error');
@@ -517,8 +524,10 @@ test('preserves source locations for merged content', () => {
   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) {
+  // Check that reference models have source locations
+  for (const refId of universeNode.references) {
+    const ref = graph.references[refId];
+    assert(ref !== undefined, 'Reference should exist in graph');
     assert(ref.source !== undefined, 'Reference should have source location');
     assert(ref.source.file !== undefined, 'Reference source should have file path');
   }
@@ -576,41 +585,6 @@ test('deterministic output order', () => {
   );
 });
 
-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');
@@ -643,43 +617,24 @@ test('parses named document blocks at universe scope', () => {
   assert(itemsNode.documentation[0].kind === 'internal', 'Inline document should have kind');
 });
 
-test('detects duplicate named reference and document names', () => {
+test('detects duplicate named 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)
+  // Should have errors for duplicate named documents (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');
-
+test('preserves source locations for named documents', () => {
   const file2 = join(fixturesDir, 'named-document.prose');
   const text2 = readFileSync(file2, 'utf-8');
   const graph2 = parseFiles([{ file: file2, text: text2 }]);
@@ -691,106 +646,6 @@ test('preserves source locations for named blocks', () => {
   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

package/repositories/sprig-repository-github/index.js

@@ -1,29 +0,0 @@
-/**
- * @fileoverview GitHub repository handler for Sprig
- * 
- * This repository handler provides functionality for working with GitHub repositories.
- * It can be extended to support cloning, fetching, and other GitHub-specific operations.
- */
-
-/**
- * Repository handler interface
- * @typedef {Object} RepositoryHandler
- * @property {string} kind - Repository kind identifier
- * @property {Function} [clone] - Clone repository function (optional)
- * @property {Function} [fetch] - Fetch repository function (optional)
- */
-
-/**
- * GitHub repository handler
- * @param {Record<string, string | number>} options - Repository options
- * @returns {RepositoryHandler}
- */
-export function createGitHubRepository(options) {
-  return {
-    kind: 'sprig-repository-github',
-    // Future: Add clone, fetch, and other GitHub-specific operations here
-  };
-}
-
-export default createGitHubRepository;
-