@rejot-dev/thalo 0.0.0

package/dist/ast/ast-types.d.ts

@@ -0,0 +1,469 @@
+//#region src/ast/ast-types.d.ts
+/**
+ * AST (Abstract Syntax Tree) type definitions for the Thalo language.
+ *
+ * ## CST vs AST
+ *
+ * This module defines the **AST** - a cleaned-up, typed representation of Thalo source code.
+ * It is built from the **CST** (Concrete Syntax Tree) produced by tree-sitter.
+ *
+ * **CST (from tree-sitter grammar):**
+ * - Raw parse tree with all syntactic details
+ * - Node types like `primitive_type`, `unknown_type`, `timestamp`, etc.
+ * - May contain ERROR nodes for invalid syntax
+ * - Accessed via `SyntaxNode` interface
+ *
+ * **AST (this module):**
+ * - Typed, validated representation for semantic analysis
+ * - Converts CST nodes to typed interfaces (e.g., `PrimitiveType`, `Timestamp`)
+ * - Handles syntax errors gracefully via `SyntaxErrorNode` (e.g., unknown types become errors)
+ * - Uses `Result<T, E>` pattern for fields that may contain recoverable errors
+ *
+ * **Example:** The CST node `unknown_type` (for typos like "date-time") is converted to a
+ * `SyntaxErrorNode<"unknown_type">` in the AST, allowing the rest of the document to parse
+ * while still reporting the error precisely.
+ *
+ * The conversion happens in `extract.ts` (CST → AST) and `builder.ts` (timestamp decomposition).
+ *
+ * @module
+ */
+/**
+ * Tree-sitter Point interface (row and column).
+ *
+ * Compatible with both tree-sitter (native) and web-tree-sitter (web).
+ */
+interface Point {
+  row: number;
+  column: number;
+}
+/**
+ * Minimal SyntaxNode interface compatible with both tree-sitter and web-tree-sitter.
+ *
+ * This interface represents the common subset of properties and methods available
+ * in both tree-sitter's `SyntaxNode` and web-tree-sitter's `Node`.
+ *
+ * We define our own interface rather than importing from tree-sitter because:
+ * 1. tree-sitter is a peer dependency, not a regular dependency
+ * 2. The native and web versions have slightly different interfaces
+ * 3. We only need a minimal subset of the full tree-sitter API
+ *
+ * Note: In web-tree-sitter, namedChildren, children, and childrenForFieldName can
+ * contain null values. Native tree-sitter doesn't include nulls, but the type
+ * `(SyntaxNode | null)[]` is compatible with `SyntaxNode[]` (contravariance).
+ * Code should filter out nulls when needed using `.filter((c): c is SyntaxNode => c !== null)`.
+ */
+interface SyntaxNode {
+  readonly id: number;
+  readonly type: string;
+  readonly text: string;
+  readonly startIndex: number;
+  readonly endIndex: number;
+  readonly startPosition: Point;
+  readonly endPosition: Point;
+  readonly namedChildren: readonly (SyntaxNode | null)[];
+  readonly children: readonly (SyntaxNode | null)[];
+  readonly parent: SyntaxNode | null;
+  childForFieldName(fieldName: string): SyntaxNode | null;
+  childrenForFieldName(fieldName: string): (SyntaxNode | null)[];
+  descendantForPosition(start: Point, end?: Point): SyntaxNode | null;
+  descendantsOfType(type: string | string[], startPosition?: Point, endPosition?: Point): (SyntaxNode | null)[];
+  readonly hasError: boolean;
+}
+/**
+ * Location information for an AST node
+ */
+interface Location {
+  startIndex: number;
+  endIndex: number;
+  startPosition: Point;
+  endPosition: Point;
+}
+/**
+ * Base interface for all AST nodes
+ */
+interface AstNode {
+  type: string;
+  location: Location;
+  /** The underlying tree-sitter node */
+  syntaxNode: SyntaxNode;
+}
+/**
+ * Known syntax error codes that can be emitted by the AST builder.
+ * These represent recoverable syntax errors where we can still produce a partial AST.
+ */
+type SyntaxErrorCode = "missing_timezone" | "missing_entity" | "missing_title" | "missing_link_id" | "invalid_directive" | "invalid_timestamp" | "malformed_metadata" | "unknown_type" | "parse_error";
+/**
+ * A syntax error node that can appear inline in the AST.
+ * Represents recoverable syntax errors that don't prevent further parsing.
+ *
+ * @example
+ * // A timestamp without timezone would have:
+ * timestamp: {
+ *   type: "timestamp",
+ *   value: "2026-01-05T18:00",
+ *   date: { ... },
+ *   time: { ... },
+ *   timezone: {
+ *     type: "syntax_error",
+ *     code: "missing_timezone",
+ *     message: "Timestamp requires timezone",
+ *     text: "2026-01-05T18:00"
+ *   }
+ * }
+ */
+interface SyntaxErrorNode<Code extends SyntaxErrorCode = SyntaxErrorCode> extends AstNode {
+  type: "syntax_error";
+  /** The specific error code */
+  code: Code;
+  /** Human-readable error message */
+  message: string;
+  /** The malformed source text that caused the error */
+  text: string;
+}
+/**
+ * Result type for AST nodes that may contain syntax errors.
+ * Used to represent optional or validated fields that can fail gracefully.
+ *
+ * @example
+ * // In Timestamp type:
+ * timezone: Result<TimezonePart, "missing_timezone">
+ * // Can be either a valid TimezonePart or a SyntaxErrorNode with code "missing_timezone"
+ */
+type Result<T, E extends SyntaxErrorCode> = T | SyntaxErrorNode<E>;
+/**
+ * Type guard to check if a Result is a SyntaxErrorNode
+ */
+declare function isSyntaxError<T, E extends SyntaxErrorCode>(result: Result<T, E>): result is SyntaxErrorNode<E>;
+interface SourceFile extends AstNode {
+  type: "source_file";
+  entries: Entry[];
+  /** Root-level syntax errors (malformed entries that couldn't be parsed) */
+  syntaxErrors: SyntaxErrorNode[];
+}
+type Entry = InstanceEntry | SchemaEntry | SynthesisEntry | ActualizeEntry;
+interface InstanceEntry extends AstNode {
+  type: "instance_entry";
+  header: InstanceHeader;
+  metadata: Metadata[];
+  content: Content | null;
+}
+interface InstanceHeader extends AstNode {
+  type: "instance_header";
+  timestamp: Timestamp;
+  directive: InstanceDirective;
+  entity: Entity;
+  title: Title;
+  link: Link | null;
+  tags: Tag[];
+}
+type InstanceDirective = "create" | "update";
+type Entity = "lore" | "opinion" | "reference" | "journal";
+interface SchemaEntry extends AstNode {
+  type: "schema_entry";
+  header: SchemaHeader;
+  metadataBlock: MetadataBlock | null;
+  sectionsBlock: SectionsBlock | null;
+  removeMetadataBlock: RemoveMetadataBlock | null;
+  removeSectionsBlock: RemoveSectionsBlock | null;
+}
+interface SchemaHeader extends AstNode {
+  type: "schema_header";
+  timestamp: Timestamp;
+  directive: SchemaDirective;
+  entityName: Identifier;
+  title: Title;
+  link: Link | null;
+  tags: Tag[];
+}
+type SchemaDirective = "define-entity" | "alter-entity";
+interface SynthesisEntry extends AstNode {
+  type: "synthesis_entry";
+  header: SynthesisHeader;
+  metadata: Metadata[];
+  content: Content | null;
+}
+interface SynthesisHeader extends AstNode {
+  type: "synthesis_header";
+  timestamp: Timestamp;
+  title: Title;
+  linkId: Link;
+  tags: Tag[];
+}
+interface ActualizeEntry extends AstNode {
+  type: "actualize_entry";
+  header: ActualizeHeader;
+  metadata: Metadata[];
+}
+interface ActualizeHeader extends AstNode {
+  type: "actualize_header";
+  timestamp: Timestamp;
+  target: Link;
+}
+interface MetadataBlock extends AstNode {
+  type: "metadata_block";
+  fields: FieldDefinition[];
+}
+interface SectionsBlock extends AstNode {
+  type: "sections_block";
+  sections: SectionDefinition[];
+}
+interface RemoveMetadataBlock extends AstNode {
+  type: "remove_metadata_block";
+  fields: FieldRemoval[];
+}
+interface RemoveSectionsBlock extends AstNode {
+  type: "remove_sections_block";
+  sections: SectionRemoval[];
+}
+interface FieldDefinition extends AstNode {
+  type: "field_definition";
+  name: FieldName;
+  optional: boolean;
+  /** The type expression, or SyntaxErrorNode if an unknown type was used */
+  typeExpr: Result<TypeExpression, "unknown_type">;
+  defaultValue: DefaultValue | null;
+  description: Description | null;
+}
+interface FieldRemoval extends AstNode {
+  type: "field_removal";
+  name: FieldName;
+  reason: Description | null;
+}
+interface SectionDefinition extends AstNode {
+  type: "section_definition";
+  name: SectionName;
+  optional: boolean;
+  description: Description | null;
+}
+interface SectionRemoval extends AstNode {
+  type: "section_removal";
+  name: SectionName;
+  reason: Description | null;
+}
+type TypeExpression = PrimitiveType | LiteralType | ArrayType | UnionType;
+interface PrimitiveType extends AstNode {
+  type: "primitive_type";
+  name: "string" | "datetime" | "daterange" | "link" | "number";
+}
+interface LiteralType extends AstNode {
+  type: "literal_type";
+  value: string;
+}
+interface ArrayType extends AstNode {
+  type: "array_type";
+  elementType: PrimitiveType | LiteralType | UnionType;
+}
+interface UnionType extends AstNode {
+  type: "union_type";
+  members: (PrimitiveType | LiteralType | ArrayType)[];
+}
+interface Metadata extends AstNode {
+  type: "metadata";
+  key: Key;
+  value: Value;
+}
+interface Content extends AstNode {
+  type: "content";
+  children: (MarkdownHeader | ContentLine)[];
+}
+interface MarkdownHeader extends AstNode {
+  type: "markdown_header";
+  text: string;
+}
+interface ContentLine extends AstNode {
+  type: "content_line";
+  text: string;
+}
+/**
+ * The date portion of a timestamp (YYYY-MM-DD)
+ */
+interface DatePart extends AstNode {
+  type: "date_part";
+  year: number;
+  month: number;
+  day: number;
+  /** The formatted date string (YYYY-MM-DD) */
+  value: string;
+}
+/**
+ * The time portion of a timestamp (HH:MM)
+ */
+interface TimePart extends AstNode {
+  type: "time_part";
+  hour: number;
+  minute: number;
+  /** The formatted time string (HH:MM) */
+  value: string;
+}
+/**
+ * The timezone portion of a timestamp (e.g., "Z", "+05:30", "-08:00")
+ */
+interface TimezonePart extends AstNode {
+  type: "timezone_part";
+  /** The timezone string (e.g., "Z", "+05:30", "-08:00") */
+  value: string;
+  /** Offset from UTC in minutes (0 for Z, positive for east, negative for west) */
+  offsetMinutes: number;
+}
+/**
+ * A timestamp value with decomposed parts.
+ *
+ * The timezone can be a SyntaxErrorNode if missing.
+ *
+ * @example
+ * // Fully decomposed timestamp:
+ * {
+ *   type: "timestamp",
+ *   value: "2026-01-05T18:00Z",
+ *   date: { type: "date_part", year: 2026, month: 1, day: 5, value: "2026-01-05", ... },
+ *   time: { type: "time_part", hour: 18, minute: 0, value: "18:00", ... },
+ *   timezone: { type: "timezone_part", value: "Z", offsetMinutes: 0, ... }
+ * }
+ *
+ * @example
+ * // Timestamp with missing timezone (syntax error):
+ * {
+ *   type: "timestamp",
+ *   value: "2026-01-05T18:00",
+ *   date: { ... },
+ *   time: { ... },
+ *   timezone: { type: "syntax_error", code: "missing_timezone", message: "...", text: "..." }
+ * }
+ */
+interface Timestamp extends AstNode {
+  type: "timestamp";
+  /** The full timestamp string */
+  value: string;
+  /** Decomposed date part */
+  date: DatePart;
+  /** Decomposed time part */
+  time: TimePart;
+  /** Decomposed timezone part, or SyntaxErrorNode if missing */
+  timezone: Result<TimezonePart, "missing_timezone">;
+}
+interface Title extends AstNode {
+  type: "title";
+  /** The title text without surrounding quotes */
+  value: string;
+}
+interface Link extends AstNode {
+  type: "link";
+  /** The link ID without the ^ prefix */
+  id: string;
+}
+interface Tag extends AstNode {
+  type: "tag";
+  /** The tag name without the # prefix */
+  name: string;
+}
+interface Identifier extends AstNode {
+  type: "identifier";
+  value: string;
+}
+interface Key extends AstNode {
+  type: "key";
+  value: string;
+}
+interface Value extends AstNode {
+  type: "value";
+  /** The raw value text */
+  raw: string;
+  /** The typed value content */
+  content: ValueContent;
+}
+/**
+ * Typed value content from the grammar.
+ * All values must be explicitly typed (no plain/unquoted values).
+ */
+type ValueContent = QuotedValue | LinkValue | DatetimeValue | DaterangeValue | NumberValue | QueryValue | ValueArray;
+interface QuotedValue extends AstNode {
+  type: "quoted_value";
+  /** The quoted text without surrounding quotes */
+  value: string;
+}
+interface LinkValue extends AstNode {
+  type: "link_value";
+  /** The parsed link */
+  link: Link;
+}
+interface DatetimeValue extends AstNode {
+  type: "datetime_value";
+  /** The full datetime value string */
+  value: string;
+  /** The date part (YYYY-MM-DD) */
+  date: string;
+  /** The time part if present (HH:MM) */
+  time: string | null;
+  /** The timezone if present (Z or +/-HH:MM) */
+  tz: string | null;
+}
+interface DaterangeValue extends AstNode {
+  type: "daterange";
+  /** The raw date range text */
+  raw: string;
+}
+interface NumberValue extends AstNode {
+  type: "number_value";
+  /** The raw number string */
+  raw: string;
+  /** The parsed numeric value */
+  value: number;
+}
+interface QueryValue extends AstNode {
+  type: "query_value";
+  /** The parsed query */
+  query: Query;
+}
+interface ValueArray extends AstNode {
+  type: "value_array";
+  /** Elements of the array (links, quoted values, datetimes, dateranges, numbers, or queries) */
+  elements: (Link | QuotedValue | DatetimeValue | DaterangeValue | NumberValue | Query)[];
+}
+interface Query extends AstNode {
+  type: "query";
+  /** The entity type to query */
+  entity: string;
+  /** The conditions (ANDed together) */
+  conditions: QueryCondition[];
+}
+type QueryCondition = FieldCondition | TagCondition | LinkCondition;
+interface FieldCondition extends AstNode {
+  type: "field_condition";
+  /** The field name */
+  field: string;
+  /** The field value */
+  value: string;
+}
+interface TagCondition extends AstNode {
+  type: "tag_condition";
+  /** The tag (without #) */
+  tag: string;
+}
+interface LinkCondition extends AstNode {
+  type: "link_condition";
+  /** The link (without ^) */
+  linkId: string;
+}
+interface FieldName extends AstNode {
+  type: "field_name";
+  value: string;
+}
+interface SectionName extends AstNode {
+  type: "section_name";
+  value: string;
+}
+interface Description extends AstNode {
+  type: "description";
+  /** The description text without surrounding quotes */
+  value: string;
+}
+interface DefaultValue extends AstNode {
+  type: "default_value";
+  /** The raw default value text */
+  raw: string;
+  /** The typed value content (quoted_value, link, datetime, or number) */
+  content: QuotedValue | Link | DatetimeValue | NumberValue;
+}
+//#endregion
+export { ActualizeEntry, Entry, FieldName, Identifier, InstanceEntry, Key, Link, Location, Query, QueryCondition, SchemaEntry, SectionName, SourceFile, SyntaxNode, SynthesisEntry, Tag, Timestamp, TypeExpression, ValueContent, isSyntaxError };
+//# sourceMappingURL=ast-types.d.ts.map

package/dist/ast/ast-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-types.d.ts","names":[],"sources":["../../src/ast/ast-types.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/ast/ast-types.js

@@ -0,0 +1,11 @@
+//#region src/ast/ast-types.ts
+/**
+* Type guard to check if a Result is a SyntaxErrorNode
+*/
+function isSyntaxError(result) {
+	return result.type === "syntax_error";
+}
+
+//#endregion
+export { isSyntaxError };
+//# sourceMappingURL=ast-types.js.map

package/dist/ast/ast-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-types.js","names":[],"sources":["../../src/ast/ast-types.ts"],"sourcesContent":["/**\n * AST (Abstract Syntax Tree) type definitions for the Thalo language.\n *\n * ## CST vs AST\n *\n * This module defines the **AST** - a cleaned-up, typed representation of Thalo source code.\n * It is built from the **CST** (Concrete Syntax Tree) produced by tree-sitter.\n *\n * **CST (from tree-sitter grammar):**\n * - Raw parse tree with all syntactic details\n * - Node types like `primitive_type`, `unknown_type`, `timestamp`, etc.\n * - May contain ERROR nodes for invalid syntax\n * - Accessed via `SyntaxNode` interface\n *\n * **AST (this module):**\n * - Typed, validated representation for semantic analysis\n * - Converts CST nodes to typed interfaces (e.g., `PrimitiveType`, `Timestamp`)\n * - Handles syntax errors gracefully via `SyntaxErrorNode` (e.g., unknown types become errors)\n * - Uses `Result<T, E>` pattern for fields that may contain recoverable errors\n *\n * **Example:** The CST node `unknown_type` (for typos like \"date-time\") is converted to a\n * `SyntaxErrorNode<\"unknown_type\">` in the AST, allowing the rest of the document to parse\n * while still reporting the error precisely.\n *\n * The conversion happens in `extract.ts` (CST → AST) and `builder.ts` (timestamp decomposition).\n *\n * @module\n */\n\n/**\n * Tree-sitter Point interface (row and column).\n *\n * Compatible with both tree-sitter (native) and web-tree-sitter (web).\n */\nexport interface Point {\n  row: number;\n  column: number;\n}\n\n/**\n * Minimal SyntaxNode interface compatible with both tree-sitter and web-tree-sitter.\n *\n * This interface represents the common subset of properties and methods available\n * in both tree-sitter's `SyntaxNode` and web-tree-sitter's `Node`.\n *\n * We define our own interface rather than importing from tree-sitter because:\n * 1. tree-sitter is a peer dependency, not a regular dependency\n * 2. The native and web versions have slightly different interfaces\n * 3. We only need a minimal subset of the full tree-sitter API\n *\n * Note: In web-tree-sitter, namedChildren, children, and childrenForFieldName can\n * contain null values. Native tree-sitter doesn't include nulls, but the type\n * `(SyntaxNode | null)[]` is compatible with `SyntaxNode[]` (contravariance).\n * Code should filter out nulls when needed using `.filter((c): c is SyntaxNode => c !== null)`.\n */\nexport interface SyntaxNode {\n  readonly id: number;\n  readonly type: string;\n  readonly text: string;\n  readonly startIndex: number;\n  readonly endIndex: number;\n  readonly startPosition: Point;\n  readonly endPosition: Point;\n  readonly namedChildren: readonly (SyntaxNode | null)[];\n  readonly children: readonly (SyntaxNode | null)[];\n  readonly parent: SyntaxNode | null;\n  childForFieldName(fieldName: string): SyntaxNode | null;\n  childrenForFieldName(fieldName: string): (SyntaxNode | null)[];\n  descendantForPosition(start: Point, end?: Point): SyntaxNode | null;\n  descendantsOfType(\n    type: string | string[],\n    startPosition?: Point,\n    endPosition?: Point,\n  ): (SyntaxNode | null)[];\n  readonly hasError: boolean;\n}\n\n/**\n * Location information for an AST node\n */\nexport interface Location {\n  startIndex: number;\n  endIndex: number;\n  startPosition: Point;\n  endPosition: Point;\n}\n\n/**\n * Base interface for all AST nodes\n */\nexport interface AstNode {\n  type: string;\n  location: Location;\n  /** The underlying tree-sitter node */\n  syntaxNode: SyntaxNode;\n}\n\n// ===================\n// Syntax Errors\n// ===================\n\n/**\n * Known syntax error codes that can be emitted by the AST builder.\n * These represent recoverable syntax errors where we can still produce a partial AST.\n */\nexport type SyntaxErrorCode =\n  | \"missing_timezone\"\n  | \"missing_entity\"\n  | \"missing_title\"\n  | \"missing_link_id\"\n  | \"invalid_directive\"\n  | \"invalid_timestamp\"\n  | \"malformed_metadata\"\n  | \"unknown_type\"\n  | \"parse_error\";\n\n/**\n * A syntax error node that can appear inline in the AST.\n * Represents recoverable syntax errors that don't prevent further parsing.\n *\n * @example\n * // A timestamp without timezone would have:\n * timestamp: {\n *   type: \"timestamp\",\n *   value: \"2026-01-05T18:00\",\n *   date: { ... },\n *   time: { ... },\n *   timezone: {\n *     type: \"syntax_error\",\n *     code: \"missing_timezone\",\n *     message: \"Timestamp requires timezone\",\n *     text: \"2026-01-05T18:00\"\n *   }\n * }\n */\nexport interface SyntaxErrorNode<Code extends SyntaxErrorCode = SyntaxErrorCode> extends AstNode {\n  type: \"syntax_error\";\n  /** The specific error code */\n  code: Code;\n  /** Human-readable error message */\n  message: string;\n  /** The malformed source text that caused the error */\n  text: string;\n}\n\n/**\n * Result type for AST nodes that may contain syntax errors.\n * Used to represent optional or validated fields that can fail gracefully.\n *\n * @example\n * // In Timestamp type:\n * timezone: Result<TimezonePart, \"missing_timezone\">\n * // Can be either a valid TimezonePart or a SyntaxErrorNode with code \"missing_timezone\"\n */\nexport type Result<T, E extends SyntaxErrorCode> = T | SyntaxErrorNode<E>;\n\n/**\n * Type guard to check if a Result is a SyntaxErrorNode\n */\nexport function isSyntaxError<T, E extends SyntaxErrorCode>(\n  result: Result<T, E>,\n): result is SyntaxErrorNode<E> {\n  return (result as SyntaxErrorNode).type === \"syntax_error\";\n}\n\n/**\n * Type guard to check if a Result is a valid value (not a SyntaxErrorNode)\n */\nexport function isValidResult<T, E extends SyntaxErrorCode>(result: Result<T, E>): result is T {\n  return (result as SyntaxErrorNode).type !== \"syntax_error\";\n}\n\n// ===================\n// Source File\n// ===================\n\nexport interface SourceFile extends AstNode {\n  type: \"source_file\";\n  entries: Entry[];\n  /** Root-level syntax errors (malformed entries that couldn't be parsed) */\n  syntaxErrors: SyntaxErrorNode[];\n}\n\n// ===================\n// Entries\n// ===================\n\nexport type Entry = InstanceEntry | SchemaEntry | SynthesisEntry | ActualizeEntry;\n\n// ===================\n// Instance Entries (create/update)\n// ===================\n\nexport interface InstanceEntry extends AstNode {\n  type: \"instance_entry\";\n  header: InstanceHeader;\n  metadata: Metadata[];\n  content: Content | null;\n}\n\nexport interface InstanceHeader extends AstNode {\n  type: \"instance_header\";\n  timestamp: Timestamp;\n  directive: InstanceDirective;\n  entity: Entity;\n  title: Title;\n  link: Link | null;\n  tags: Tag[];\n}\n\nexport type InstanceDirective = \"create\" | \"update\";\n\nexport type Entity = \"lore\" | \"opinion\" | \"reference\" | \"journal\";\n\n// ===================\n// Schema Entries (define-entity/alter-entity)\n// ===================\n\nexport interface SchemaEntry extends AstNode {\n  type: \"schema_entry\";\n  header: SchemaHeader;\n  metadataBlock: MetadataBlock | null;\n  sectionsBlock: SectionsBlock | null;\n  removeMetadataBlock: RemoveMetadataBlock | null;\n  removeSectionsBlock: RemoveSectionsBlock | null;\n}\n\nexport interface SchemaHeader extends AstNode {\n  type: \"schema_header\";\n  timestamp: Timestamp;\n  directive: SchemaDirective;\n  entityName: Identifier;\n  title: Title;\n  link: Link | null;\n  tags: Tag[];\n}\n\nexport type SchemaDirective = \"define-entity\" | \"alter-entity\";\n\n// ===================\n// Synthesis Entries (define-synthesis)\n// ===================\n\nexport interface SynthesisEntry extends AstNode {\n  type: \"synthesis_entry\";\n  header: SynthesisHeader;\n  metadata: Metadata[];\n  content: Content | null;\n}\n\nexport interface SynthesisHeader extends AstNode {\n  type: \"synthesis_header\";\n  timestamp: Timestamp;\n  title: Title;\n  linkId: Link;\n  tags: Tag[];\n}\n\n// ===================\n// Actualize Entries (actualize-synthesis)\n// ===================\n\nexport interface ActualizeEntry extends AstNode {\n  type: \"actualize_entry\";\n  header: ActualizeHeader;\n  metadata: Metadata[];\n}\n\nexport interface ActualizeHeader extends AstNode {\n  type: \"actualize_header\";\n  timestamp: Timestamp;\n  target: Link;\n}\n\n// ===================\n// Schema Blocks\n// ===================\n\nexport interface MetadataBlock extends AstNode {\n  type: \"metadata_block\";\n  fields: FieldDefinition[];\n}\n\nexport interface SectionsBlock extends AstNode {\n  type: \"sections_block\";\n  sections: SectionDefinition[];\n}\n\nexport interface RemoveMetadataBlock extends AstNode {\n  type: \"remove_metadata_block\";\n  fields: FieldRemoval[];\n}\n\nexport interface RemoveSectionsBlock extends AstNode {\n  type: \"remove_sections_block\";\n  sections: SectionRemoval[];\n}\n\n// ===================\n// Field Definitions\n// ===================\n\nexport interface FieldDefinition extends AstNode {\n  type: \"field_definition\";\n  name: FieldName;\n  optional: boolean;\n  /** The type expression, or SyntaxErrorNode if an unknown type was used */\n  typeExpr: Result<TypeExpression, \"unknown_type\">;\n  defaultValue: DefaultValue | null;\n  description: Description | null;\n}\n\nexport interface FieldRemoval extends AstNode {\n  type: \"field_removal\";\n  name: FieldName;\n  reason: Description | null;\n}\n\n// ===================\n// Section Definitions\n// ===================\n\nexport interface SectionDefinition extends AstNode {\n  type: \"section_definition\";\n  name: SectionName;\n  optional: boolean;\n  description: Description | null;\n}\n\nexport interface SectionRemoval extends AstNode {\n  type: \"section_removal\";\n  name: SectionName;\n  reason: Description | null;\n}\n\n// ===================\n// Type Expressions\n// ===================\n\nexport type TypeExpression = PrimitiveType | LiteralType | ArrayType | UnionType;\n\nexport interface PrimitiveType extends AstNode {\n  type: \"primitive_type\";\n  name: \"string\" | \"datetime\" | \"daterange\" | \"link\" | \"number\";\n}\n\nexport interface LiteralType extends AstNode {\n  type: \"literal_type\";\n  value: string;\n}\n\nexport interface ArrayType extends AstNode {\n  type: \"array_type\";\n  elementType: PrimitiveType | LiteralType | UnionType;\n}\n\nexport interface UnionType extends AstNode {\n  type: \"union_type\";\n  members: (PrimitiveType | LiteralType | ArrayType)[];\n}\n\n// ===================\n// Metadata (instance entries)\n// ===================\n\nexport interface Metadata extends AstNode {\n  type: \"metadata\";\n  key: Key;\n  value: Value;\n}\n\n// ===================\n// Content (instance entries)\n// ===================\n\nexport interface Content extends AstNode {\n  type: \"content\";\n  children: (MarkdownHeader | ContentLine)[];\n}\n\nexport interface MarkdownHeader extends AstNode {\n  type: \"markdown_header\";\n  text: string;\n}\n\nexport interface ContentLine extends AstNode {\n  type: \"content_line\";\n  text: string;\n}\n\n// ===================\n// Terminal Nodes\n// ===================\n\n// ===================\n// Timestamp Parts (decomposed)\n// ===================\n\n/**\n * The date portion of a timestamp (YYYY-MM-DD)\n */\nexport interface DatePart extends AstNode {\n  type: \"date_part\";\n  year: number;\n  month: number;\n  day: number;\n  /** The formatted date string (YYYY-MM-DD) */\n  value: string;\n}\n\n/**\n * The time portion of a timestamp (HH:MM)\n */\nexport interface TimePart extends AstNode {\n  type: \"time_part\";\n  hour: number;\n  minute: number;\n  /** The formatted time string (HH:MM) */\n  value: string;\n}\n\n/**\n * The timezone portion of a timestamp (e.g., \"Z\", \"+05:30\", \"-08:00\")\n */\nexport interface TimezonePart extends AstNode {\n  type: \"timezone_part\";\n  /** The timezone string (e.g., \"Z\", \"+05:30\", \"-08:00\") */\n  value: string;\n  /** Offset from UTC in minutes (0 for Z, positive for east, negative for west) */\n  offsetMinutes: number;\n}\n\n/**\n * A timestamp value with decomposed parts.\n *\n * The timezone can be a SyntaxErrorNode if missing.\n *\n * @example\n * // Fully decomposed timestamp:\n * {\n *   type: \"timestamp\",\n *   value: \"2026-01-05T18:00Z\",\n *   date: { type: \"date_part\", year: 2026, month: 1, day: 5, value: \"2026-01-05\", ... },\n *   time: { type: \"time_part\", hour: 18, minute: 0, value: \"18:00\", ... },\n *   timezone: { type: \"timezone_part\", value: \"Z\", offsetMinutes: 0, ... }\n * }\n *\n * @example\n * // Timestamp with missing timezone (syntax error):\n * {\n *   type: \"timestamp\",\n *   value: \"2026-01-05T18:00\",\n *   date: { ... },\n *   time: { ... },\n *   timezone: { type: \"syntax_error\", code: \"missing_timezone\", message: \"...\", text: \"...\" }\n * }\n */\nexport interface Timestamp extends AstNode {\n  type: \"timestamp\";\n  /** The full timestamp string */\n  value: string;\n  /** Decomposed date part */\n  date: DatePart;\n  /** Decomposed time part */\n  time: TimePart;\n  /** Decomposed timezone part, or SyntaxErrorNode if missing */\n  timezone: Result<TimezonePart, \"missing_timezone\">;\n}\n\nexport interface Title extends AstNode {\n  type: \"title\";\n  /** The title text without surrounding quotes */\n  value: string;\n}\n\nexport interface Link extends AstNode {\n  type: \"link\";\n  /** The link ID without the ^ prefix */\n  id: string;\n}\n\nexport interface Tag extends AstNode {\n  type: \"tag\";\n  /** The tag name without the # prefix */\n  name: string;\n}\n\nexport interface Identifier extends AstNode {\n  type: \"identifier\";\n  value: string;\n}\n\nexport interface Key extends AstNode {\n  type: \"key\";\n  value: string;\n}\n\nexport interface Value extends AstNode {\n  type: \"value\";\n  /** The raw value text */\n  raw: string;\n  /** The typed value content */\n  content: ValueContent;\n}\n\n/**\n * Typed value content from the grammar.\n * All values must be explicitly typed (no plain/unquoted values).\n */\nexport type ValueContent =\n  | QuotedValue\n  | LinkValue\n  | DatetimeValue\n  | DaterangeValue\n  | NumberValue\n  | QueryValue\n  | ValueArray;\n\nexport interface QuotedValue extends AstNode {\n  type: \"quoted_value\";\n  /** The quoted text without surrounding quotes */\n  value: string;\n}\n\nexport interface LinkValue extends AstNode {\n  type: \"link_value\";\n  /** The parsed link */\n  link: Link;\n}\n\nexport interface DatetimeValue extends AstNode {\n  type: \"datetime_value\";\n  /** The full datetime value string */\n  value: string;\n  /** The date part (YYYY-MM-DD) */\n  date: string;\n  /** The time part if present (HH:MM) */\n  time: string | null;\n  /** The timezone if present (Z or +/-HH:MM) */\n  tz: string | null;\n}\n\nexport interface DaterangeValue extends AstNode {\n  type: \"daterange\";\n  /** The raw date range text */\n  raw: string;\n}\n\nexport interface NumberValue extends AstNode {\n  type: \"number_value\";\n  /** The raw number string */\n  raw: string;\n  /** The parsed numeric value */\n  value: number;\n}\n\nexport interface QueryValue extends AstNode {\n  type: \"query_value\";\n  /** The parsed query */\n  query: Query;\n}\n\nexport interface ValueArray extends AstNode {\n  type: \"value_array\";\n  /** Elements of the array (links, quoted values, datetimes, dateranges, numbers, or queries) */\n  elements: (Link | QuotedValue | DatetimeValue | DaterangeValue | NumberValue | Query)[];\n}\n\nexport interface Query extends AstNode {\n  type: \"query\";\n  /** The entity type to query */\n  entity: string;\n  /** The conditions (ANDed together) */\n  conditions: QueryCondition[];\n}\n\nexport type QueryCondition = FieldCondition | TagCondition | LinkCondition;\n\nexport interface FieldCondition extends AstNode {\n  type: \"field_condition\";\n  /** The field name */\n  field: string;\n  /** The field value */\n  value: string;\n}\n\nexport interface TagCondition extends AstNode {\n  type: \"tag_condition\";\n  /** The tag (without #) */\n  tag: string;\n}\n\nexport interface LinkCondition extends AstNode {\n  type: \"link_condition\";\n  /** The link (without ^) */\n  linkId: string;\n}\n\nexport interface FieldName extends AstNode {\n  type: \"field_name\";\n  value: string;\n}\n\nexport interface SectionName extends AstNode {\n  type: \"section_name\";\n  value: string;\n}\n\nexport interface Description extends AstNode {\n  type: \"description\";\n  /** The description text without surrounding quotes */\n  value: string;\n}\n\nexport interface DefaultValue extends AstNode {\n  type: \"default_value\";\n  /** The raw default value text */\n  raw: string;\n  /** The typed value content (quoted_value, link, datetime, or number) */\n  content: QuotedValue | Link | DatetimeValue | NumberValue;\n}\n"],"mappings":";;;;AA+JA,SAAgB,cACd,QAC8B;AAC9B,QAAQ,OAA2B,SAAS"}

package/dist/ast/builder.js

@@ -0,0 +1,158 @@
+import { formatTimestamp } from "../formatters.js";
+
+//#region src/ast/builder.ts
+/**
+* Extract location information from a tree-sitter node
+*/
+function extractLocation(node) {
+	return {
+		startIndex: node.startIndex,
+		endIndex: node.endIndex,
+		startPosition: node.startPosition,
+		endPosition: node.endPosition
+	};
+}
+/**
+* Create a synthetic location from two points
+*/
+function syntheticLocation(start, end) {
+	return {
+		startIndex: start.index,
+		endIndex: end.index,
+		startPosition: start.position,
+		endPosition: end.position
+	};
+}
+/**
+* Create a syntax error node for recoverable parse errors
+*/
+function createSyntaxError(code, message, text, node) {
+	return {
+		type: "syntax_error",
+		code,
+		message,
+		text,
+		location: extractLocation(node),
+		syntaxNode: node
+	};
+}
+/**
+* Create a syntax error node with a synthetic location
+*/
+function createSyntaxErrorAt(code, message, text, location, syntaxNode) {
+	return {
+		type: "syntax_error",
+		code,
+		message,
+		text,
+		location,
+		syntaxNode
+	};
+}
+/**
+* Parse a timezone string and return the offset in minutes
+*
+* @param tz - Timezone string like "Z", "+05:30", "-08:00"
+* @returns Offset from UTC in minutes (0 for Z, positive for east, negative for west)
+*/
+function parseTimezoneOffset(tz) {
+	if (tz === "Z") return 0;
+	const match = tz.match(/^([+-])(\d{2}):(\d{2})$/);
+	if (!match) throw new Error(`Invalid timezone format: "${tz}"`);
+	const sign = match[1] === "+" ? 1 : -1;
+	const hours = parseInt(match[2], 10);
+	const minutes = parseInt(match[3], 10);
+	return sign * (hours * 60 + minutes);
+}
+/**
+* Build a DatePart from a date string (YYYY-MM-DD)
+*/
+function buildDatePart(dateStr, location, syntaxNode) {
+	const match = dateStr.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+	if (!match) throw new Error(`Invalid date format: "${dateStr}"`);
+	return {
+		type: "date_part",
+		year: parseInt(match[1], 10),
+		month: parseInt(match[2], 10),
+		day: parseInt(match[3], 10),
+		value: dateStr,
+		location,
+		syntaxNode
+	};
+}
+/**
+* Build a TimePart from a time string (HH:MM)
+*/
+function buildTimePart(timeStr, location, syntaxNode) {
+	const match = timeStr.match(/^(\d{2}):(\d{2})$/);
+	if (!match) throw new Error(`Invalid time format: "${timeStr}"`);
+	return {
+		type: "time_part",
+		hour: parseInt(match[1], 10),
+		minute: parseInt(match[2], 10),
+		value: timeStr,
+		location,
+		syntaxNode
+	};
+}
+/**
+* Build a TimezonePart from a timezone string
+*/
+function buildTimezonePart(tzStr, location, syntaxNode) {
+	return {
+		type: "timezone_part",
+		value: tzStr,
+		offsetMinutes: parseTimezoneOffset(tzStr),
+		location,
+		syntaxNode
+	};
+}
+/**
+* Build a Timestamp with decomposed parts from tree-sitter child nodes.
+*
+* The grammar decomposes timestamp into:
+* - timestamp_date: "YYYY-MM-DD" (date)
+* - timestamp_t: "T" (separator, not a field)
+* - timestamp_time: "HH:MM" (time)
+* - timestamp_tz: "Z" or "±HH:MM" (optional timezone)
+*
+* If the timezone is missing, a SyntaxErrorNode is created for the timezone field.
+*
+* @param node - The tree-sitter timestamp node with date, time, and optional tz children
+* @returns Timestamp with decomposed date, time, and timezone parts
+*/
+function buildTimestamp(node) {
+	const text = node.text;
+	const dateNode = node.childForFieldName("date");
+	const timeNode = node.childForFieldName("time");
+	const tzNode = node.childForFieldName("tz");
+	if (!dateNode || !timeNode) throw new Error(`Invalid timestamp structure: missing date or time node in "${text}"`);
+	const dateLocation = extractLocation(dateNode);
+	const datePart = buildDatePart(dateNode.text, dateLocation, dateNode);
+	const timeLocation = extractLocation(timeNode);
+	const timePart = buildTimePart(timeNode.text, timeLocation, timeNode);
+	let timezone;
+	if (tzNode) {
+		const tzLocation = extractLocation(tzNode);
+		timezone = buildTimezonePart(tzNode.text, tzLocation, tzNode);
+	} else timezone = createSyntaxErrorAt("missing_timezone", "Timestamp requires timezone (e.g., Z or +05:30)", text, syntheticLocation({
+		index: timeNode.endIndex,
+		position: timeNode.endPosition
+	}, {
+		index: timeNode.endIndex,
+		position: timeNode.endPosition
+	}), node);
+	return {
+		type: "timestamp",
+		value: text,
+		date: datePart,
+		time: timePart,
+		timezone,
+		location: extractLocation(node),
+		syntaxNode: node
+	};
+}
+
+//#endregion
+export { buildTimestamp, createSyntaxError };
+//# sourceMappingURL=builder.js.map