sprig-universe

A minimal parser for the universe layer of Sprig, a declarative language for describing systems.

What it does

sprig-universe parses Sprig .prose files and extracts the universe structure, producing a JSON representation (UniverseGraph) that includes:

v0 Simplification:

• Automatic discovery: finds universe.prose marker and loads all prose files

• Dead simple defaults: no configuration required

• Single universe rule: exactly one universe declaration required across all files

• Nodes: Universe, series, book, and chapter declarations with their relationships

• Edges: relates declarations connecting concepts

• Describe blocks: Freeform text preserved exactly as authored

• Unknown blocks: Blocks like references and documentation are preserved with their raw content

• Source spans: File, line, column, and offset information for all nodes and blocks

• Diagnostics: Warnings for duplicate names and unresolved references

Installation

npm install

Usage

CLI

Compile (v0 - Recommended)

The compile command uses automatic discovery to find and compile all prose files:

sprig-universe compile

Discovery behavior:

• Walks upward from the current directory to find universe.prose marker file
• Loads all **/*.prose files under the discovered root
• Automatically excludes: .sprig/**, dist/**, node_modules/**, .git/**
• Requires exactly one universe declaration across all files

Options:

• --root <path> - Override discovery start path (default: current directory)
• --quiet - Suppress observable header output
• --config <path> - Path to sprig.config.json (optional, uses defaults if not found)

Observable header (shown unless --quiet):

Universe: <Name> (root: /path/to/root)
Loaded: <N> prose files
Ignored: .sprig/**, dist/**, node_modules/**, .git/**

Other commands:

• sprig-universe watch - Watch files and recompile on change
• sprig-universe check:references - Validate repository references
• sprig-universe validate - Validate scene sources

Parse (Legacy)

Parse a single file:

sprig-universe parse path/to/file.prose

Parse a directory (recursively finds all *.prose files):

sprig-universe parse path/to/directory

Output to a file:

sprig-universe parse path/to/file.prose --out output.json

The CLI exits with a non-zero code if there are any error-level diagnostics.

Programmatic API

import { parseFiles, parseText } from './src/index.js';

// Parse a single text string
const ast = parseText(sourceText, 'filename.prose');

// Parse multiple files into a single graph
const graph = parseFiles([
  { file: 'file1.prose', text: sourceText1 },
  { file: 'file2.prose', text: sourceText2 },
]);

Supported Syntax

The parser supports the universe layer of Sprig:

• universe <Name> { ... } - Top-level universe declaration
• series <Name> { ... } - Series within a universe
• book <Name> in <ParentName> { ... } - Book within a series or book
• chapter <Name> in <ParentName> { ... } - Chapter within a book
• relates <A> and <B> { ... } - Relationship between concepts
• describe { ... } - Freeform text block (preserves raw content including braces)
• Unknown blocks (e.g., references { ... }, documentation { ... }) - Preserved as-is

Comments start with -- and continue to the end of the line.

Output Format

The parser produces a UniverseGraph JSON structure:

{
  "version": 1,
  "universes": {
    "UniverseName": {
      "name": "UniverseName",
      "root": "UniverseName:universe:UniverseName"
    }
  },
  "nodes": {
    "UniverseName:series:SeriesName": {
      "id": "UniverseName:series:SeriesName",
      "kind": "series",
      "name": "SeriesName",
      "parent": "UniverseName:universe:UniverseName",
      "children": [],
      "describe": { "raw": "...", "source": {...} },
      "source": {...}
    }
  },
  "edges": {
    "UniverseName:relates:A--B:0": {
      "id": "UniverseName:relates:A--B:0",
      "kind": "relates",
      "a": { "text": "A", "target": "..." },
      "b": { "text": "B", "target": "..." },
      "source": {...}
    }
  },
  "diagnostics": []
}

Development

# Format code
npm run format

# Lint code
npm run lint

# Type check (JSDoc types)
npm run typecheck

# Run tests
npm test

License

ISC