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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprig-and-prose/sprig-universe",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Minimal universe parser for sprig",
   "main": "src/index.js",

package/src/ast.js

@@ -23,37 +23,23 @@
  */
 
 /**
- * @typedef {Object} ReferenceBlock
+ * @typedef {Object} ReferenceDecl
  * @property {string} kind - Always 'reference'
- * @property {string} repository - Repository name (string literal)
- * @property {string[]} paths - Array of path strings (string literals)
- * @property {string} [referenceKind] - Optional reference kind (e.g., 'api', 'data')
+ * @property {string} [name] - Optional reference name (identifier)
+ * @property {string} [repositoryName] - Optional repository name from "in RepoName"
+ * @property {string} [url] - Optional raw URL (string literal)
+ * @property {string[]} [paths] - Optional array of path strings (string literals)
+ * @property {string} [referenceKind] - Optional reference kind (user-facing classification)
  * @property {DescribeBlock} [describe] - Optional describe block
- * @property {SourceSpan} source - Source span
- */
-
-/**
- * @typedef {Object} NamedReferenceBlock
- * @property {string} kind - Always 'named-reference'
- * @property {string} name - Reference name (identifier)
- * @property {string} repository - Repository name (string literal)
- * @property {string[]} paths - Array of path strings (string literals)
- * @property {string} [referenceKind] - Optional reference kind (e.g., 'api', 'data')
- * @property {DescribeBlock} [describe] - Optional describe block
- * @property {SourceSpan} source - Source span
- */
-
-/**
- * @typedef {Object} UsingInReferencesBlock
- * @property {string} kind - Always 'using-in-references'
- * @property {string[]} names - Array of identifier names to reference
+ * @property {NoteBlock} [note] - Optional note block
+ * @property {TitleBlock} [title] - Optional title block
  * @property {SourceSpan} source - Source span
  */
 
 /**
  * @typedef {Object} ReferencesBlock
  * @property {string} kind - Always 'references'
- * @property {Array<ReferenceBlock | UsingInReferencesBlock>} references - Array of reference blocks and using blocks
+ * @property {Array<{ name: string, source: SourceSpan }>} items - Array of identifier paths to references
  * @property {SourceSpan} source - Source span
  */
 
@@ -91,6 +77,13 @@
  * @property {SourceSpan} source - Source span
  */
 
+/**
+ * @typedef {Object} NoteBlock
+ * @property {string} kind - Always 'note'
+ * @property {string} raw - Raw text content (without outer braces)
+ * @property {SourceSpan} source - Source span
+ */
+
 /**
  * @typedef {Object} TitleBlock
  * @property {string} kind - Always 'title'
@@ -102,8 +95,11 @@
  * @typedef {Object} RepositoryDecl
  * @property {string} kind - Always 'repository'
  * @property {string} name - Repository name (identifier)
- * @property {string | number} repositoryKind - Repository kind (string, identifier, or number)
- * @property {Record<string, string | number>} options - Repository options
+ * @property {string} [parentName] - Optional parent name (from "in ParentName")
+ * @property {string} [url] - Repository base URL (string literal)
+ * @property {DescribeBlock} [describe] - Optional describe block
+ * @property {NoteBlock} [note] - Optional note block
+ * @property {TitleBlock} [title] - Optional title block
  * @property {SourceSpan} source - Source span
  */
 
@@ -111,7 +107,7 @@
  * @typedef {Object} UniverseDecl
  * @property {string} kind - Always 'universe'
  * @property {string} name - Universe name
- * @property {Array<AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | NamedReferenceBlock | NamedDocumentBlock | RepositoryDecl | UnknownBlock>} body - Body declarations
+ * @property {Array<AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | RepositoryDecl | ReferenceDecl | NamedDocumentBlock | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
@@ -119,7 +115,8 @@
  * @typedef {Object} AnthologyDecl
  * @property {string} kind - Always 'anthology'
  * @property {string} name - Anthology name
- * @property {Array<DescribeBlock | TitleBlock | ReferencesBlock | DocumentationBlock | UnknownBlock>} body - Body declarations
+ * @property {string} [parentName] - Optional parent universe name (from "in UniverseName")
+ * @property {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
@@ -128,7 +125,7 @@
  * @property {string} kind - Always 'series'
  * @property {string} name - Series name
  * @property {string} [parentName] - Optional parent anthology name (from "in AnthologyName")
- * @property {Array<BookDecl | ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | DocumentationBlock | UnknownBlock>} body - Body declarations
+ * @property {Array<BookDecl | ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
@@ -137,7 +134,7 @@
  * @property {string} kind - Always 'book'
  * @property {string} name - Book name
  * @property {string} parentName - Parent name (from "in ParentName")
- * @property {Array<ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | DocumentationBlock | UnknownBlock>} body - Body declarations
+ * @property {Array<ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
@@ -146,7 +143,7 @@
  * @property {string} kind - Always 'chapter'
  * @property {string} name - Chapter name
  * @property {string} parentName - Parent name (from "in ParentName")
- * @property {Array<DescribeBlock | ReferencesBlock | DocumentationBlock | UnknownBlock>} body - Body declarations
+ * @property {Array<DescribeBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
@@ -155,7 +152,7 @@
  * @property {string} kind - Always 'concept'
  * @property {string} name - Concept name
  * @property {string} [parentName] - Optional parent name (from "in ParentName")
- * @property {Array<DescribeBlock | ReferencesBlock | DocumentationBlock | UnknownBlock>} body - Body declarations
+ * @property {Array<DescribeBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
@@ -244,7 +241,7 @@
  */
 
 /**
- * @typedef {UniverseDecl | AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | FromBlock | RelationshipsBlock | ReferencesBlock | ReferenceBlock | NamedReferenceBlock | DocumentationBlock | DocumentBlock | NamedDocumentBlock | RepositoryDecl | UnknownBlock | SceneDecl | UsingBlock | ActorDecl | TypeBlock | IdentityBlock | SourceBlock | TransformsBlock | TransformBlock} ASTNode
+ * @typedef {UniverseDecl | AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | NoteBlock | TitleBlock | FromBlock | RelationshipsBlock | ReferencesBlock | ReferenceDecl | DocumentationBlock | DocumentBlock | NamedDocumentBlock | RepositoryDecl | UnknownBlock | SceneDecl | UsingBlock | ActorDecl | TypeBlock | IdentityBlock | SourceBlock | TransformsBlock | TransformBlock} ASTNode
  */
 
 /**
@@ -252,6 +249,7 @@
  * @property {string} file - File path
  * @property {UniverseDecl[]} universes - Top-level universe declarations
  * @property {SceneDecl[]} scenes - Top-level scene declarations
+ * @property {Array<AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | RepositoryDecl | ReferenceDecl | ReferencesBlock | DocumentationBlock | NamedDocumentBlock | UnknownBlock>} [topLevelDecls] - Unscoped top-level declarations
  * @property {SourceSpan} [source] - File-level source span
  */
 

package/src/cli.js

@@ -12,10 +12,9 @@ import { validateScenes } from './validator.js';
 import chokidar from 'chokidar';
 import { globSync } from 'glob';
 
-// Get the directory where this CLI script is located (sprig-universe package root)
+// Get the directory where this CLI script is located
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const PACKAGE_ROOT = resolve(__dirname, '..');
 
 const DEFAULT_EXCLUDES = ['.sprig/**', 'dist/**', 'node_modules/**', '.git/**'];
 
@@ -24,7 +23,6 @@ function printGlobalHelp() {
   console.log('Commands:');
   console.log('  compile           Compile universe and scene files to manifests');
   console.log('  watch             Watch universe and scene files and recompile on change');
-  console.log('  check:references  Validate repository references');
   console.log('  validate          Validate scene file sources');
   console.log('  parse             Parse files (legacy command)');
   console.log('');
@@ -79,21 +77,6 @@ function printValidateHelp() {
   console.log('  --quiet          Suppress observable header output');
 }
 
-function printCheckReferencesHelp() {
-  console.log('Usage: sprig-universe check:references [--root <path>] [--quiet]');
-  console.log('');
-  console.log('Validates repository references in the universe manifest.');
-  console.log('');
-  console.log('Discovery:');
-  console.log('  - Walks upward from current directory (or --root) to find universe.prose');
-  console.log('  - Loads all **/*.prose files under the discovered root');
-  console.log('  - Excludes: .sprig/**, dist/**, node_modules/**, .git/**');
-  console.log('');
-  console.log('Options:');
-  console.log('  --root <path>    Override discovery start path (default: current directory)');
-  console.log('  --quiet          Suppress observable header output');
-}
-
 function printParseHelp() {
   console.log('Usage: sprig-universe parse <fileOrDir> [--out <path>]');
   console.log('');
@@ -253,90 +236,6 @@ function findSceneFiles(dir) {
   return files;
 }
 
-/**
- * Validate repository kinds exist in repositories directory
- * @param {Record<string, any>} repositories - Repository config
- * @param {string} universeRoot - Universe root directory (unused, kept for API compatibility)
- * @returns {boolean} - True if valid, false otherwise
- */
-function validateRepositoryKinds(repositories, universeRoot) {
-  // Repositories are located in the sprig-universe package directory, not in the universe project
-  const repositoriesDir = join(PACKAGE_ROOT, 'repositories');
-  const errors = [];
-
-  for (const [repoName, repoConfig] of Object.entries(repositories)) {
-    const kind = repoConfig.kind;
-    if (!kind) {
-      errors.push(`Repository "${repoName}" has no kind specified`);
-      continue;
-    }
-
-    const kindDir = join(repositoriesDir, kind);
-    const indexFile = join(kindDir, 'index.js');
-
-    if (!existsSync(indexFile)) {
-      errors.push(`Repository kind "${kind}" not found. Expected: ${indexFile}`);
-    }
-  }
-
-  if (errors.length > 0) {
-    console.error('Error: Invalid repository configurations:');
-    for (const error of errors) {
-      console.error(`  - ${error}`);
-    }
-    return false;
-  }
-
-  return true;
-}
-
-/**
- * Validate repository references
- * @param {any} graph - Parsed graph
- * @param {Record<string, any>} repositories - Repository config
- * @returns {boolean} - True if valid, false otherwise
- */
-function validateReferences(graph, repositories) {
-  const repoKeys = new Set(Object.keys(repositories || {}));
-  /** @type {Map<string, { count: number, examples: Array<{ file: string, line: number }> }>} */
-  const unknownRepos = new Map();
-
-  for (const node of Object.values(graph.nodes)) {
-    if (!node.references) continue;
-
-    for (const ref of node.references) {
-      if (repoKeys.has(ref.repository)) continue;
-
-      const source = ref.source;
-      const entry = unknownRepos.get(ref.repository) || { count: 0, examples: [] };
-      entry.count += 1;
-
-      if (entry.examples.length < 3 && source?.file && source?.start?.line) {
-        entry.examples.push({ file: source.file, line: source.start.line });
-      }
-
-      unknownRepos.set(ref.repository, entry);
-    }
-  }
-
-  if (unknownRepos.size === 0) {
-    return true;
-  }
-
-  console.error('Error: Reference(s) to unknown repositories:');
-  for (const [repo, info] of unknownRepos.entries()) {
-    const exampleText =
-      info.examples.length > 0
-        ? ` (e.g. ${info.examples
-            .map((ex) => `${ex.file}:${ex.line}`)
-            .join(', ')})`
-        : '';
-    console.error(`  - ${repo}: ${info.count} occurrence(s)${exampleText}`);
-  }
-
-  return false;
-}
-
 /**
  * Main CLI entry point
  */
@@ -364,10 +263,6 @@ function main() {
       printValidateHelp();
       return;
     }
-    if (command === 'check:references') {
-      printCheckReferencesHelp();
-      return;
-    }
     if (command === 'parse') {
       printParseHelp();
       return;
@@ -379,11 +274,6 @@ function main() {
     return;
   }
 
-  if (command === 'check:references') {
-    handleCheckReferences(commandArgs);
-    return;
-  }
-
   if (command === 'validate' || command === 'check') {
     handleValidate(commandArgs);
     return;
@@ -630,16 +520,6 @@ function compileUniverseWithFiles(universeRoot, files, silent = false) {
       return false;
     }
 
-    // Validate repository kinds exist
-    if (!validateRepositoryKinds(graph.repositories || {}, universeRoot)) {
-      return false;
-    }
-
-    // Validate references
-    if (!validateReferences(graph, graph.repositories || {})) {
-      return false;
-    }
-
     // Get series names for status message
     const seriesNames = Object.values(graph.nodes)
       .filter((node) => node.kind === 'series')
@@ -715,7 +595,6 @@ function compileUniverseWithFiles(universeRoot, files, silent = false) {
  */
 function compileUniverse(config, configPath, silent = false) {
   const universeConfig = config.universe;
-  const repositories = config.repositories || {};
 
   if (!universeConfig) {
     console.error('Error: Missing "universe" section in config');
@@ -756,11 +635,6 @@ function compileUniverse(config, configPath, silent = false) {
   try {
     const graph = parseFiles(fileContents);
 
-    // Validate references
-    if (!validateReferences(graph, repositories)) {
-      return false;
-    }
-
     // Get series names for status message
     const seriesNames = Object.values(graph.nodes)
       .filter((node) => node.kind === 'series')
@@ -770,7 +644,6 @@ function compileUniverse(config, configPath, silent = false) {
     // Add repositories and metadata to manifest
     const manifest = {
       ...graph,
-      repositories,
       generatedAt: new Date().toISOString(),
     };
 
@@ -1358,88 +1231,6 @@ function handleWatch(args) {
   });
 }
 
-/**
- * Handle check:references command
- * @param {string[]} args
- */
-function handleCheckReferences(args) {
-  const quiet = hasQuietFlag(args);
-  const rootStart = resolveRootPath(args);
-  
-  // Discover universe root
-  const universeRoot = discoverUniverseRoot(rootStart);
-  if (!universeRoot) {
-    console.error(`Error: Could not find universe.prose marker. Searched upward from: ${rootStart}`);
-    process.exit(1);
-  }
-  
-  // Load prose files using new discovery mechanism
-  const proseFiles = loadProseFiles(universeRoot);
-  if (proseFiles.length === 0) {
-    console.error(`Error: No .prose files found under root: ${universeRoot}`);
-    process.exit(1);
-  }
-  
-  // Parse files to get universe info for header
-  const fileContents = proseFiles.map((file) => ({
-    file,
-    text: readFileSync(file, 'utf-8'),
-  }));
-  
-  let graph;
-  try {
-    graph = parseFiles(fileContents);
-  } catch (error) {
-    console.error(`Error parsing files: ${error.message}`);
-    process.exit(1);
-  }
-  
-  // Validate exactly one universe
-  const validation = validateUniverseCount(graph);
-  if (!validation.valid) {
-    console.error(`Error: ${validation.error}`);
-    process.exit(1);
-  }
-  
-  // Print observable header unless quiet
-  if (!quiet) {
-    printObservableHeader(validation.universeName, universeRoot, proseFiles.length);
-  }
-
-  // Validate repository kinds exist
-  if (!validateRepositoryKinds(graph.repositories || {}, universeRoot)) {
-    console.error('❌ Repository kind validation failed');
-    process.exit(1);
-  }
-
-  // Validate references
-  if (!validateReferences(graph, graph.repositories || {})) {
-    console.error('❌ Reference validation failed');
-    process.exit(1);
-  }
-
-  // Check for parsing errors
-  const hasErrors = graph.diagnostics.some((d) => d.severity === 'error');
-  if (hasErrors) {
-    process.exit(1);
-  }
-
-  // Display warnings
-  const warnings = graph.diagnostics.filter((d) => d.severity === 'warning');
-  if (warnings.length > 0) {
-    console.warn(`\n⚠️  ${warnings.length} warning(s):`);
-    for (const warning of warnings) {
-      const source = warning.source
-        ? `${warning.source.file}:${warning.source.start.line}:${warning.source.start.col}`
-        : 'unknown location';
-      console.warn(`   ${source}: ${warning.message}`);
-    }
-    console.warn('');
-  }
-
-  console.log('✅ All references are valid');
-}
-
 /**
  * Handle parse command (legacy)
  * @param {string[]} args