@sprig-and-prose/sprig-universe 0.1.0

package/src/index.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Public API for Sprig universe parser
+ */
+
+import { scan } from './scanner.js';
+import { parse } from './parser.js';
+import { buildGraph } from './graph.js';
+import { convertToSceneManifest, convertFilesToSceneManifest } from './scene-manifest.js';
+import { validateScenes } from './validator.js';
+
+/**
+ * @typedef {import('./ir.js').UniverseGraph} UniverseGraph
+ * @typedef {import('./ast.js').FileAST} FileAST
+ */
+
+/**
+ * Parses a single text string into an AST
+ * @param {string} text - Source text
+ * @param {string} file - File path (for source spans)
+ * @returns {FileAST}
+ */
+export function parseText(text, file) {
+  const tokens = scan(text, file);
+  return parse(tokens, file, text);
+}
+
+/**
+ * Parses multiple files and builds a single UniverseGraph
+ * @param {Array<{ text: string, file: string }>} files - Array of file contents
+ * @returns {UniverseGraph}
+ */
+export function parseFiles(files) {
+  const fileASTs = files.map((f) => parseText(f.text, f.file));
+  return buildGraph(fileASTs);
+}
+
+// Export scene-related functions
+export { convertToSceneManifest, convertFilesToSceneManifest, validateScenes };
+
+/**
+ * Builds a UniverseGraph from parsed file ASTs
+ * @param {FileAST[]} fileASTs - Array of parsed file ASTs
+ * @returns {UniverseGraph}
+ */
+export { buildGraph };
+

package/src/ir.js

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview UniverseGraph IR type definitions
+ */
+
+/**
+ * @typedef {Object} SourceSpan
+ * @property {string} file - File path
+ * @property {{ line: number, col: number, offset: number }} start - Start position
+ * @property {{ line: number, col: number, offset: number }} end - End position
+ */
+
+/**
+ * @typedef {Object} TextBlock
+ * @property {string} raw - Raw text content (exactly as-authored)
+ * @property {string} [normalized] - Dedented/normalized text (optional, computed)
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} UnknownBlock
+ * @property {string} keyword - Block keyword (e.g., 'references', 'documentation')
+ * @property {string} raw - Raw inner content (without outer braces, exactly as-authored)
+ * @property {string} [normalized] - Dedented/normalized text (optional, computed)
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} NodeRef
+ * @property {string} text - Text as written
+ * @property {string} [target] - Resolved node ID if found
+ */
+
+/**
+ * @typedef {Object} Diagnostic
+ * @property {'error' | 'warning'} severity - Diagnostic severity
+ * @property {string} message - Diagnostic message
+ * @property {SourceSpan} [source] - Optional source span
+ */
+
+/**
+ * @typedef {string} NodeId - Node identifier: `${universeName}:${kind}:${name}`
+ */
+
+/**
+ * @typedef {string} EdgeId - Edge identifier: `${universeName}:relates:${aText}--${bText}:${index}`
+ */
+
+/**
+ * @typedef {Object} FromView
+ * @property {SourceSpan} source - Source span of the from block
+ * @property {{ values: string[], source: SourceSpan }} [relationships] - Relationships block if present
+ * @property {TextBlock} [describe] - Describe block if present
+ * @property {UnknownBlock[]} [unknownBlocks] - Unknown blocks if any
+ */
+
+/**
+ * @typedef {Object} NodeModel
+ * @property {NodeId} id - Node identifier
+ * @property {'universe' | 'anthology' | 'series' | 'book' | 'chapter' | 'concept' | 'relates'} kind - Node kind (declaration kind, not contract kind)
+ * @property {string} name - Node name
+ * @property {NodeId} [parent] - Tree parent node ID
+ * @property {NodeId[]} children - Child node IDs
+ * @property {NodeId} [container] - Container node ID (for book/chapter "in" relationship; always set for book/chapter nodes when resolved)
+ * @property {TextBlock} [describe] - Describe block if present
+ * @property {UnknownBlock[]} [unknownBlocks] - Unknown blocks if any
+ * @property {Array<{repository: string, paths: string[], kind?: string, describe?: TextBlock, source: SourceSpan}>} [references] - References if any
+ * @property {Array<{title?: string, kind: string, path: string, describe?: TextBlock, source: SourceSpan}>} [documentation] - Documentation if any
+ * @property {SourceSpan} source - Source span
+ * @property {NodeId[]} [endpoints] - Endpoint node IDs (for relates nodes)
+ * @property {string[]} [unresolvedEndpoints] - Unresolved endpoint names (for relates nodes)
+ * @property {Record<string, FromView>} [from] - From blocks keyed by endpoint node ID (for relates nodes)
+ */
+
+/**
+ * @typedef {Object} EdgeModel
+ * @property {EdgeId} id - Edge identifier
+ * @property {'relates'} kind - Edge kind
+ * @property {NodeRef} a - First endpoint
+ * @property {NodeRef} b - Second endpoint
+ * @property {TextBlock} [describe] - Describe block if present
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} UniverseModel
+ * @property {string} name - Universe name
+ * @property {NodeId} root - Root node ID (the universe node itself)
+ */
+
+/**
+ * @typedef {Object} NamedReferenceModel
+ * @property {string} name - Reference name
+ * @property {string} repository - Repository name
+ * @property {string[]} paths - Array of path strings
+ * @property {string} [kind] - Optional reference kind
+ * @property {TextBlock} [describe] - Optional describe block
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} NamedDocumentModel
+ * @property {string} name - Document name
+ * @property {string} kind - Document kind
+ * @property {string} path - Document path
+ * @property {TextBlock} [describe] - Optional describe block
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} UniverseGraph
+ * @property {number} version - Graph version (1)
+ * @property {Record<string, UniverseModel>} universes - Universes keyed by name
+ * @property {Record<NodeId, NodeModel>} nodes - Nodes keyed by ID
+ * @property {Record<EdgeId, EdgeModel>} edges - Edges keyed by ID
+ * @property {Diagnostic[]} diagnostics - Diagnostics
+ * @property {Record<string, any>} [repositories] - Repository configurations (from config)
+ * @property {string} [generatedAt] - ISO timestamp when manifest was generated
+ * @property {Record<string, Record<string, NamedReferenceModel>>} [referencesByName] - Named references by universe name, then by reference name
+ * @property {Record<string, Record<string, NamedDocumentModel>>} [documentsByName] - Named documents by universe name, then by document name
+ */
+