@sprig-and-prose/sprig-universe 0.1.0

package/biome.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "always"
+    }
+  }
+}
+

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@sprig-and-prose/sprig-universe",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Minimal universe parser for sprig",
+  "main": "src/index.js",
+  "bin": {
+    "sprig-universe": "./src/cli.js"
+  },
+  "scripts": {
+    "format": "biome format . --write",
+    "lint": "biome lint .",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "chokidar": "^3.6.0",
+    "glob": "^13.0.0",
+    "mysql2": "^3.11.5",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "typescript": "^5.7.2"
+  }
+}
+

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

@@ -0,0 +1,29 @@
+/**
+ * @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;
+

package/src/ast.js

@@ -0,0 +1,257 @@
+/**
+ * @fileoverview AST node 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
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} UnknownBlock
+ * @property {string} keyword - Block keyword
+ * @property {string} raw - Raw inner content (without outer braces)
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} ReferenceBlock
+ * @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 {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 {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 {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} DocumentBlock
+ * @property {string} kind - Always 'document'
+ * @property {string} [title] - Optional title identifier
+ * @property {string} documentKind - Document kind (e.g., 'internal')
+ * @property {string} path - Document path (e.g., '/docs/items/containers.md')
+ * @property {DescribeBlock} [describe] - Optional describe block
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} NamedDocumentBlock
+ * @property {string} kind - Always 'named-document'
+ * @property {string} name - Document name (identifier)
+ * @property {string} documentKind - Document kind (e.g., 'internal')
+ * @property {string} path - Document path (e.g., '/docs/items/containers.md')
+ * @property {DescribeBlock} [describe] - Optional describe block
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} DocumentationBlock
+ * @property {string} kind - Always 'documentation'
+ * @property {DocumentBlock[]} documents - Array of document blocks
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} DescribeBlock
+ * @property {string} kind - Always 'describe'
+ * @property {string} raw - Raw text content (without outer braces)
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} TitleBlock
+ * @property {string} kind - Always 'title'
+ * @property {string} raw - Raw text content (without outer braces)
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @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 {SourceSpan} source - Source span
+ */
+
+/**
+ * @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 {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} AnthologyDecl
+ * @property {string} kind - Always 'anthology'
+ * @property {string} name - Anthology name
+ * @property {Array<DescribeBlock | TitleBlock | ReferencesBlock | DocumentationBlock | UnknownBlock>} body - Body declarations
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} SeriesDecl
+ * @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 {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} BookDecl
+ * @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 {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} ChapterDecl
+ * @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 {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} ConceptDecl
+ * @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 {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} RelationshipsBlock
+ * @property {string} kind - Always 'relationships'
+ * @property {string[]} values - Array of string literal values
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} FromBlock
+ * @property {string} kind - Always 'from'
+ * @property {string} endpoint - Endpoint identifier
+ * @property {Array<RelationshipsBlock | DescribeBlock | TitleBlock | UnknownBlock>} body - Body declarations
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} RelatesDecl
+ * @property {string} kind - Always 'relates'
+ * @property {string} a - First endpoint text
+ * @property {string} b - Second endpoint text
+ * @property {Array<DescribeBlock | TitleBlock | FromBlock | UnknownBlock>} body - Body declarations
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} UsingBlock
+ * @property {string} kind - Always 'using'
+ * @property {string[]} identifiers - List of identifiers
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} TypeBlock
+ * @property {string} kind - Always 'type'
+ * @property {string} raw - Raw inner content (for future parsing)
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} IdentityBlock
+ * @property {string} kind - Always 'identity'
+ * @property {string} raw - Raw inner content (for future parsing)
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} SourceBlock
+ * @property {string} kind - Always 'source'
+ * @property {string} sourceType - 'file', 'sqlite', or 'mysql'
+ * @property {string} raw - Raw inner content
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} TransformBlock
+ * @property {string} kind - Always 'transform'
+ * @property {string} raw - Raw inner content
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} TransformsBlock
+ * @property {string} kind - Always 'transforms'
+ * @property {TransformBlock[]} transforms - Array of transform blocks
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} ActorDecl
+ * @property {string} kind - Always 'actor'
+ * @property {string} name - Actor name
+ * @property {Array<DescribeBlock | TypeBlock | IdentityBlock | SourceBlock | TransformsBlock | UnknownBlock>} body - Body declarations
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @typedef {Object} SceneDecl
+ * @property {string} kind - Always 'scene'
+ * @property {string} name - Scene name
+ * @property {string} target - Target namespace path (from "for Namespace.Path")
+ * @property {Array<UsingBlock | ActorDecl | DescribeBlock | UnknownBlock>} body - Body declarations
+ * @property {SourceSpan} source - Source span
+ */
+
+/**
+ * @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 {Object} FileAST
+ * @property {string} file - File path
+ * @property {UniverseDecl[]} universes - Top-level universe declarations
+ * @property {SceneDecl[]} scenes - Top-level scene declarations
+ * @property {SourceSpan} [source] - File-level source span
+ */
+