@sprig-and-prose/sprig-universe 0.3.3 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprig-and-prose/sprig-universe",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "type": "module",
   "description": "Minimal universe parser for sprig",
   "main": "src/index.js",
@@ -27,4 +27,3 @@
     "typescript": "^5.7.2"
   }
 }
-

package/src/ast.js

@@ -43,6 +43,13 @@
  * @property {SourceSpan} source - Source span
  */
 
+/**
+ * @typedef {Object} OrderingBlock
+ * @property {string} kind - Always 'ordering'
+ * @property {string[]} identifiers - Array of identifier names
+ * @property {SourceSpan} source - Source span
+ */
+
 /**
  * @typedef {Object} DocumentBlock
  * @property {string} kind - Always 'document'
@@ -106,60 +113,85 @@
 /**
  * @typedef {Object} UniverseDecl
  * @property {string} kind - Always 'universe'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} name - Universe name
- * @property {Array<AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | DescribeBlock | TitleBlock | RepositoryDecl | ReferenceDecl | NamedDocumentBlock | UnknownBlock>} body - Body declarations
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
+ * @property {Array<AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | RelationshipDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | RepositoryDecl | ReferenceDecl | NamedDocumentBlock | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
 /**
  * @typedef {Object} AnthologyDecl
  * @property {string} kind - Always 'anthology'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} name - Anthology name
  * @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 {Record<string, string>} [aliases] - Alias mappings declared in this scope
+ * @property {Array<SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | RelationshipDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
 /**
  * @typedef {Object} SeriesDecl
  * @property {string} kind - Always 'series'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} name - Series name
  * @property {string} [parentName] - Optional parent anthology name (from "in AnthologyName")
- * @property {Array<BookDecl | ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
+ * @property {Array<BookDecl | ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
 /**
  * @typedef {Object} BookDecl
  * @property {string} kind - Always 'book'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} name - Book name
  * @property {string} [parentName] - Optional parent name (from "in ParentName")
- * @property {Array<ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
+ * @property {Array<ChapterDecl | DescribeBlock | TitleBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
 /**
  * @typedef {Object} ChapterDecl
  * @property {string} kind - Always 'chapter'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} name - Chapter name
  * @property {string} parentName - Parent name (from "in ParentName")
- * @property {Array<DescribeBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
+ * @property {Array<DescribeBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
 /**
  * @typedef {Object} ConceptDecl
  * @property {string} kind - Always 'concept'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} name - Concept name
  * @property {string} [parentName] - Optional parent name (from "in ParentName")
- * @property {Array<DescribeBlock | ReferencesBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
+ * @property {Array<DescribeBlock | ReferencesBlock | OrderingBlock | DocumentationBlock | RepositoryDecl | ReferenceDecl | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
 
+/**
+ * @typedef {Object} RelationshipTarget
+ * @property {string} id - Target identifier
+ * @property {DescribeBlock} [metadata] - Optional metadata block (describe) attached to this target
+ */
+
+/**
+ * @typedef {Object} RelationshipEntry
+ * @property {string} relationshipId - Relationship identifier being used
+ * @property {RelationshipTarget[]} targets - Array of target identifiers with optional metadata
+ */
+
 /**
  * @typedef {Object} RelationshipsBlock
  * @property {string} kind - Always 'relationships'
- * @property {string[]} values - Array of string literal values
+ * @property {RelationshipEntry[]} entries - Array of relationship entries (new syntax)
+ * @property {string[]} [values] - Array of string literal values (legacy syntax for relates blocks)
  * @property {SourceSpan} source - Source span
  */
 
@@ -171,11 +203,33 @@
  * @property {SourceSpan} source - Source span
  */
 
+/**
+ * @typedef {Object} RelationshipFromSide
+ * @property {string} [label] - Optional label string
+ * @property {DescribeBlock} [describe] - Optional describe block
+ */
+
+/**
+ * @typedef {Object} RelationshipDecl
+ * @property {string} kind - Always 'relationship'
+ * @property {string} spelledKind - Kind token as written (may be alias)
+ * @property {'symmetric' | 'paired'} type - Relationship type
+ * @property {string} [id] - Relationship identifier (for symmetric)
+ * @property {string} [leftId] - Left side identifier (for paired)
+ * @property {string} [rightId] - Right side identifier (for paired)
+ * @property {DescribeBlock} [describe] - Optional pair-level describe block
+ * @property {string} [label] - Optional label (for symmetric)
+ * @property {Record<string, RelationshipFromSide>} [from] - Per-side metadata (for paired)
+ * @property {SourceSpan} source - Source span
+ */
+
 /**
  * @typedef {Object} RelatesDecl
  * @property {string} kind - Always 'relates'
+ * @property {string} spelledKind - Kind token as written (may be alias)
  * @property {string} a - First endpoint text
  * @property {string} b - Second endpoint text
+ * @property {Record<string, string>} [aliases] - Alias mappings declared in this scope
  * @property {Array<DescribeBlock | TitleBlock | FromBlock | RelationshipsBlock | UnknownBlock>} body - Body declarations
  * @property {SourceSpan} source - Source span
  */
@@ -241,7 +295,7 @@
  */
 
 /**
- * @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
+ * @typedef {UniverseDecl | AnthologyDecl | SeriesDecl | BookDecl | ChapterDecl | ConceptDecl | RelatesDecl | RelationshipDecl | DescribeBlock | NoteBlock | TitleBlock | FromBlock | RelationshipsBlock | ReferencesBlock | ReferenceDecl | DocumentationBlock | DocumentBlock | NamedDocumentBlock | RepositoryDecl | UnknownBlock | SceneDecl | UsingBlock | ActorDecl | TypeBlock | IdentityBlock | SourceBlock | TransformsBlock | TransformBlock} ASTNode
  */
 
 /**