@sprig-and-prose/sprig-universe 0.1.0

package/PHILOSOPHY.md

@@ -0,0 +1,201 @@
+# 🌱 Why sprig exists
+
+Modern systems are hard to understand — not because they’re poorly built, but because they’re *alive*.
+
+They grow over time.
+They accumulate history.
+They reflect decisions made by different people, under different constraints, at different moments.
+
+Most tooling assumes the opposite.
+
+Most tooling assumes:
+
+* there is a single source of truth
+* that truth is owned
+* and the primary goal is to *enforce* it
+
+sprig starts from a different premise.
+
+---
+
+## sprig exists to help people **understand systems as they are**
+
+sprig is not an ORM.
+It is not a schema language.
+It is not a framework that asks to be “in charge.”
+
+Instead, sprig is an ecosystem for **describing**, **grounding**, and **gently interacting with** real systems over time.
+
+It is designed to be useful:
+
+* before execution
+* before adoption is complete
+* before certainty exists
+
+Sometimes even *before intent exists*.
+
+---
+
+## Nouns before verbs
+
+sprig favors **nouns over verbs**.
+
+You describe:
+
+* what exists
+* how things relate
+* what shape reality seems to have
+* what identifiers appear to matter
+
+You do not start by declaring:
+
+* how things must change
+* who owns enforcement
+* or what actions are allowed
+
+Verbs — migrations, transformations, ownership — are optional, explicit, and unlockable later.
+
+This keeps sprig readable, calm, and safe to approach.
+
+---
+
+## Fuzzy first, precise later
+
+Real systems are rarely known all at once.
+
+sprig is designed for:
+
+* partial knowledge
+* evolving understanding
+* incremental refinement
+
+You can begin with:
+
+* rough shapes
+* optional fields
+* multiple perspectives
+* incomplete grounding
+
+And move toward:
+
+* tighter validation
+* clearer identities
+* stronger guarantees
+
+Without losing information along the way.
+
+sprig is **lossless by design**.
+
+---
+
+## Description is valuable on its own
+
+A core belief of sprig is that **description has intrinsic value**.
+
+Even without validation.
+Even without execution.
+Even without enforcement.
+
+The Universe layer exists to support this:
+
+* human-first modeling
+* narrative structure
+* exploration and orientation
+* shared language across experience levels
+
+New engineers learn faster.
+Experienced engineers continue learning safely.
+
+sprig helps systems be *read*.
+
+---
+
+## Grounding, not control
+
+When sprig touches reality, it does so gently.
+
+Scenes describe how abstract concepts appear in the real world:
+
+* files
+* databases
+* tables
+* shapes
+* identifiers
+
+Validation observes reality and reports back — calmly.
+
+It does not punish.
+It does not assume ownership.
+It does not demand compliance.
+
+Errors are grouped, contextualized, and human.
+
+sprig doesn’t say *“this is wrong.”*
+It says *“this is what I see.”*
+
+---
+
+## Sensing before changing
+
+sprig’s natural evolution is:
+
+**description → grounding → sensing → care**
+
+Before systems change, they should be *felt*:
+
+* row counts
+* file counts
+* freshness
+* drift
+* validation status
+
+Observability is not a bolt-on feature — it is a continuation of grounding.
+
+Only after sensing does it make sense to talk about:
+
+* evolution helpers
+* migrations
+* safety analysis
+* slowly unlocked verbs
+
+Even then, everything remains optional.
+
+---
+
+## sprig is local-first and non-invasive
+
+sprig runs where your systems live.
+
+It reads files.
+It connects locally.
+It links to repositories without owning them.
+
+You can adopt sprig:
+
+* per directory
+* per entity
+* per scene
+* per moment in time
+
+There is no cliff.
+There is no rewrite.
+There is no lock-in.
+
+sprig should *touch* systems — not dominate them.
+
+---
+
+## The goal
+
+sprig exists to make systems:
+
+* more legible
+* more humane
+* easier to learn
+* safer to evolve
+
+It is a companion, not a commander.
+
+A field guide, not a rulebook.
+
+🌱

package/README.md

@@ -0,0 +1,168 @@
+# 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
+
+```bash
+npm install
+```
+
+## Usage
+
+### CLI
+
+#### Compile (v0 - Recommended)
+
+The `compile` command uses automatic discovery to find and compile all prose files:
+
+```bash
+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:
+
+```bash
+sprig-universe parse path/to/file.prose
+```
+
+Parse a directory (recursively finds all `*.prose` files):
+
+```bash
+sprig-universe parse path/to/directory
+```
+
+Output to a file:
+
+```bash
+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
+
+```javascript
+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:
+
+```json
+{
+  "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
+
+```bash
+# Format code
+npm run format
+
+# Lint code
+npm run lint
+
+# Type check (JSDoc types)
+npm run typecheck
+
+# Run tests
+npm test
+```
+
+## License
+
+ISC

package/REFERENCE.md

@@ -0,0 +1,355 @@
+# 🌱 sprig Universe Prose — Quick Reference
+
+*A compact guide to the universe layer of prose.*
+
+---
+
+## What the Universe layer is for
+
+Use the Universe layer to:
+
+* describe **what exists**
+* name **concepts and domains**
+* express **relationships and perspectives**
+* provide **human-first orientation**
+* link concepts to real artifacts (repos, paths, docs)
+
+The Universe layer is:
+
+* read-first
+* plural by convention
+* non-executable
+* safe to explore without intent to change anything
+
+### String literals
+
+All string literals in prose use **single quotes (`'`)**, not double quotes.
+
+Single quotes are intentionally chosen to read as static, descriptive values,
+not dynamic or interpolated strings.
+
+In practice, this is not a usability burden:
+most writing in prose happens inside `describe`, `note`, and `documentation`
+blocks, which do not require quoting at all.
+
+---
+
+## Core blocks
+
+### `universe`
+
+Top-level container for a body of knowledge.
+
+```sprig
+universe GameWorld {
+  describe {
+    A high-level model of the game’s systems and domains.
+  }
+}
+```
+
+* Usually singular and conceptual
+* Holds series, books, or entities directly
+
+---
+
+### `series`
+
+Groups related books or topics.
+
+```sprig
+series Items {
+  describe {
+    Everything related to items and inventories.
+  }
+}
+```
+
+* Optional
+* Useful for large domains
+* Named in the plural
+
+---
+
+### `book`
+
+A readable unit of knowledge about a domain.
+
+```sprig
+book Items {
+  describe {
+    Items represent objects that can exist in the world.
+  }
+}
+```
+
+* Plural by convention
+* Think “a book about X”
+* Can contain chapters and relationships
+
+---
+
+### `chapter`
+
+A subsection within a book.
+
+```sprig
+chapter Quality {
+  describe {
+    Item quality affects rarity and behavior.
+  }
+}
+```
+
+* Optional
+* Use for structure and scannability
+* Reads like documentation, not schema
+
+---
+
+## Relationships
+
+### `relates A and B`
+
+Declares a relationship between two universe entities.
+
+```sprig
+relates Items and Skills {
+  from Items {
+    relationships { 'can grant' }
+  }
+
+  from Skills {
+    relationships { 'can be granted by' }
+  }
+
+  describe {
+    Certain items grant skills when equipped or consumed.
+  }
+}
+```
+
+Key points:
+
+* Relationships are **plural**
+* Perspectives are symmetric but labeled differently
+* `describe` provides narrative context
+* No directionality is enforced — this is about understanding
+
+---
+
+## Documentation blocks
+
+### `describe`
+
+Human explanation. The most important block.
+
+```sprig
+describe {
+  Items can be stored, consumed, equipped, or traded.
+}
+```
+
+* Freeform text
+* Encouraged everywhere
+* No required format
+* Calm, explanatory tone preferred
+
+---
+
+### `title`
+
+Entities are automatically converted into title-case, but sometimes that's not enough.
+
+```sprig
+chapter TimeBasedEffects {
+  title { Time-Based Effects }
+}
+```
+
+* Follows the same rules as `describe`
+
+### `note`
+
+Notes are developer artifacts. They shouldn't be rendered, but they should be parsed and preserved for posterity. They are not intended for end-user documentation.
+
+```sprig
+chapter CodeMonsters {
+  note {
+    Remember to write about that one time I accidentally hard-deleted 400,000 documents.
+  }
+}
+```
+
+* Follows the same rules as `describe`
+
+### `documentation`
+
+Longer-form or structured explanation.
+
+```sprig
+documentation {
+  document DocumentName {
+    kind { 'internal' }
+    path { '/docs/items/document-name.md' }
+    describe {
+      This document contains additional details about documents.
+    }
+  }
+
+  document {
+    ...
+  }
+}
+```
+
+* Optional
+* Use when `describe` isn’t enough
+* May render differently in UI later
+
+---
+
+### `references`
+
+Links to real-world artifacts.
+
+```sprig
+references {
+  reference {
+    describe {
+      These files contain information about references.
+    }
+
+    repository { 'repo-name' }
+    paths {
+      '/data/references.yaml',
+      '/data/references.json',
+    }
+  }
+
+  reference {
+    repository { 'repo-name' }
+    paths { '/src/routers/references.js' }
+  }
+}
+```
+
+You can also reuse named references defined at the universe scope:
+
+```sprig
+references {
+  reference {
+    repository { 'repo-name' }
+    paths { '/src/helpers.ts' }
+  }
+
+  using { ItemRouter, PlayerRouter }
+}
+```
+
+* Non-owning
+* Informational only
+* Used for navigation and grounding
+* `paths` may contain one or more file paths
+* Mix inline `reference { ... }` entries with `using { Name }` to reuse named references 
+
+---
+
+## Named artifacts
+
+### Named references
+
+Define reusable references at the universe scope:
+
+```sprig
+universe GameWorld {
+  reference ItemRouter {
+    repository { 'amaranthine-backend' }
+    paths { '/src/routers/items.ts' }
+    describe { Routes that implement item endpoints. }
+  }
+
+  reference PlayerRouter {
+    repository { 'amaranthine-backend' }
+    paths { '/src/routers/players.ts' }
+  }
+
+  series Items {
+    references {
+      using { ItemRouter }
+    }
+  }
+}
+```
+
+* Named references are defined at universe scope
+* Can be reused via `using { Name }` inside `references` blocks
+* Useful for common references shared across multiple entities
+* Each name must be unique within a universe
+
+### Named documents
+
+Define reusable documents at the universe scope:
+
+```sprig
+universe GameWorld {
+  document ItemsDesignDoc {
+    kind { 'internal' }
+    path { '/docs/items/overview.md' }
+    describe { High-level items design notes. }
+  }
+
+  series Items {
+    documentation {
+      document {
+        kind { 'internal' }
+        path { '/docs/items/details.md' }
+      }
+    }
+  }
+}
+```
+
+* Named documents are defined at universe scope
+* Can be referenced later (future: via `using { Name }` in `documentation` blocks)
+* Useful for shared documentation artifacts
+* Each name must be unique within a universe
+
+---
+
+## Naming conventions (recommended)
+
+| Context           | Convention         | Rationale                      |
+| ----------------- | ------------------ | ------------------------------ |
+| Universe entities | **Plural**         | You are reading about a domain |
+| Books / series    | **Plural**         | Bodies of knowledge            |
+| Chapters          | Singular or plural | Natural language               |
+| Relationships     | Plural             | Express populations            |
+| Scenes / actors   | **Singular**       | Describe one participant       |
+
+These are conventions, not enforcement.
+
+---
+
+## What Universe prose does *not* do
+
+* No validation
+* No execution
+* No ownership
+* No enforcement
+* No “correctness” guarantees
+
+Universe prose exists to be:
+
+* read
+* explored
+* understood
+* evolved over time
+
+---
+
+## Mental model
+
+> Universe prose is closer to a field guide than a schema.
+> It tells you what kinds of things exist and how they relate —
+> not what you must do with them.