@xdbml/parse 0.1.0-poc.1

package/dist/parser.d.ts

@@ -0,0 +1,331 @@
+/**
+ * xDBML parser.
+ *
+ * Hand-written recursive-descent. Reads the token stream produced by the
+ * Lexer and emits the AST defined in ./ast.ts. Pragmatic and intentionally
+ * permissive at the parse level: several spec constraints (tuple position
+ * contiguity, named-type vs. builtin shadowing, ref-path array-crossing,
+ * polymorphic alternative selectors in paths) are deferred to a future
+ * semantic-analysis pass. The grammar test cases the parser passes are
+ * the official xDBML example files in /examples.
+ */
+import type { ParseOptions, Position, XDbmlDocument } from './ast.ts';
+import type { Token } from './lexer.ts';
+export declare class ParseError extends Error {
+    position: Position;
+    constructor(message: string, position: Position);
+}
+export declare class Parser {
+    private tokens;
+    private idx;
+    /**
+     * Parse-time options (v0.2 / P5+). Carries the importer's filePath, the
+     * optional readFile resolver, and the maxDepth bound. Used by
+     * parseModuleDirective to resolve reference-only directives. May be an
+     * empty object when no options were supplied (the public `parse(source)`
+     * 1-arg form).
+     */
+    private options;
+    /**
+     * The set of file paths currently being parsed in the resolution chain.
+     * Used for cycle detection: when resolving a directive whose `from` path
+     * is already in this set, the parser produces an empty clone for that
+     * directive rather than recursing (matching spec §26.15: cycles are
+     * allowed; name resolution handles them). The set is passed by reference
+     * across recursive parse() calls so all transitive levels see it.
+     *
+     * The set contains the resolved ABSOLUTE paths (post-readFile-key path
+     * computation), not the source-text `from` strings, so two directives
+     * that name the same file via different relative paths still collide.
+     */
+    private resolutionStack;
+    /**
+     * Current recursion depth. Incremented before each recursive parse(),
+     * compared against options.maxDepth. Reaching the limit throws.
+     */
+    private depth;
+    constructor(tokens: Token[], options?: ParseOptions, resolutionStack?: ReadonlySet<string>, depth?: number);
+    private peek;
+    private advance;
+    private check;
+    private match;
+    private expect;
+    private spanFrom;
+    parseDocument(): XDbmlDocument;
+    private parseVersionDeclaration;
+    private parseExperimentalDeclaration;
+    private parseTopLevelStatement;
+    private parseProject;
+    /**
+     * A Note inside a Project/Container/Entity body. May appear as:
+     *   Note: 'short text'
+     *   Note: '''long text'''
+     *   Note { '''long text''' }
+     */
+    private parseNoteBlockOrSetting;
+    private parseSettingValueExpectingString;
+    /**
+     * Top-level `Note name { '''...''' }` standalone declaration.
+     */
+    private parseNoteDeclaration;
+    /**
+     * Parse a `name: value` line inside a Project body. Used for project
+     * settings like `targets: PostgreSQL` or `database_type: 'MySQL'`.
+     */
+    private parseLineSetting;
+    private parseContainer;
+    private parseEntity;
+    /**
+     * Entity names may be bare (`users`), dotted (`core.users` — implicit
+     * container), or quoted (`"my-table"`).
+     */
+    private parseEntityName;
+    private parseEntityBody;
+    private parsePartialInjection;
+    /**
+     * Parse a `records { ... }` block inside an entity body (§25.1, implicit
+     * column list). Values are stored as SettingValue cells; row boundaries
+     * are determined by source line (see `parseRecordRow`).
+     */
+    private parseRecordsBlock;
+    /**
+     * Top-level records declaration (§25.2, new in v0.2):
+     *
+     *     records users (id, name, email) { ... }
+     *     records core.users (id, name, email) { ... }
+     *
+     * The entity reference can be a bare name or a dotted path for cross-
+     * container references. The column list is required; it tells the
+     * generator which columns each row's values are populating.
+     */
+    private parseTopLevelRecords;
+    /**
+     * Parse a single row of comma-separated values.
+     *
+     * Row delimiter rule: a comma continues the row only when the next value
+     * is on the same source line as the comma. If the comma is followed by
+     * a token on a later line (or the closing `}`), the comma is treated as
+     * a trailing comma and the row ends. This rule:
+     *
+     *   - Tolerates trailing commas at end of row
+     *   - Supports triple-quoted multi-line string VALUES (the comma after
+     *     the closing `'''` is on the line of the closing triple, and the
+     *     next value sits on that same line)
+     *   - Does NOT support multi-line rows where a row's values are spread
+     *     across multiple source lines connected by commas
+     */
+    private parseRecordRow;
+    /**
+     * Parse a `use` or `reuse` directive. Called from both the top-level
+     * dispatcher and the Container body dispatcher; the caller indicates
+     * which context via the `context` argument. The context affects which
+     * placements are legal (e.g., field imports must be at file scope) but
+     * does NOT affect the directive's syntactic shape.
+     *
+     * Grammar:
+     *
+     *     ('use' | 'reuse') importSpec 'from' StringLiteral metadataSettings? cloneBlock?
+     *
+     *     importSpec ::= '*'  |  '{' importItem (',' importItem)* '}'
+     *     importItem ::= elementType path ('as' Identifier)?
+     *     elementType ::= 'table' | 'entity' | 'collection' | 'record' |
+     *                     'enum' | 'tablepartial' | 'note' | 'schema' |
+     *                     'container' | 'tablegroup' | 'type' | 'edge' |
+     *                     'view' | 'diagramview' | 'field'
+     *     metadataSettings ::= '[' setting (',' setting)* ']'
+     *     cloneBlock ::= '{' topLevelStatement* '}'
+     */
+    private parseModuleDirective;
+    /**
+     * Parse one import item: an element-type keyword, a dotted source path,
+     * and an optional `as <alias>`.
+     *
+     *     entity core.dim_customer
+     *     type Email
+     *     type Email as PII_Email
+     *     field core.dim_customer.email          (rejected in P4)
+     */
+    private parseImportItem;
+    /**
+     * Parse a clone block. The block contains zero or more declarations
+     * that match the import items by name and element type (matching is
+     * downstream-consumer's job; the parser is permissive).
+     *
+     * Per spec §26.6, clone content uses the importing file's vocabulary
+     * (aliases already applied) and is parsed under the importing file's
+     * xdbml version directive.
+     *
+     * Most clone-block content uses TopLevelStatement shapes (Entity, Type,
+     * Container, etc.). The exception is field imports (§26.8): when the
+     * directive imports one or more fields via `field <path>` items, the
+     * clone block holds each field as a bare FieldDeclaration with no entity
+     * wrapper. The dispatch below checks whether the next token starts a
+     * known top-level keyword and falls through to FieldDeclaration when
+     * it doesn't.
+     */
+    private parseCloneBlock;
+    /**
+     * Lookahead helper: does the current token start a top-level statement?
+     *
+     * Used by parseCloneBlock to dispatch between "this is a top-level
+     * declaration" (Entity, Type, Container, etc.) and "this is a bare
+     * field declaration" (for field imports). A field declaration starts
+     * with an identifier followed by a type expression; a top-level
+     * statement starts with one of the known top-level keywords.
+     *
+     * Mirrors the dispatch in parseTopLevelStatement(). If we add new
+     * top-level constructs there, this set should grow in parallel.
+     */
+    private isCloneTopLevelStart;
+    /**
+     * `field_name typeExpression [settings]` or `"quoted name" typeExpression [settings]`.
+     *
+     * Critical lookahead point: we're invoked from a context where the next
+     * token MUST be a field name (Identifier or QuotedIdentifier), and the
+     * token after it is a type expression. If the next thing is a Note block
+     * or a partial injection or `indexes`, those should have been handled by
+     * the caller already.
+     */
+    private parseFieldDeclaration;
+    /**
+     * Parse a type expression. Dispatch on the leading keyword/identifier:
+     *
+     *   - `object { ... }` (and synonyms struct/record)
+     *   - `array [ ... ]` (and synonym list)
+     *   - `map [k, v]` (and synonyms dict/dictionary)
+     *   - `set [t]`
+     *   - `union [ ... ]`
+     *   - `oneOf { ... }` / `anyOf { ... }` / `allOf { ... }`
+     *   - `json { ... }` (and synonyms jsonb/variant; block optional)
+     *   - Otherwise: scalar / named-type reference. With optional `(p, s)`.
+     */
+    private parseTypeExpression;
+    private parseObjectType;
+    /**
+     * `array [ ... ]`. The bracket body has several forms:
+     *
+     *   1. `[varchar]`               -- bare element type
+     *   2. `[varchar [not null]]`    -- element type with settings
+     *   3. `[line_item object { ... }]` -- named element type (common with object)
+     *   4. `[[0] x object {...}, [1] y object {...}]` -- tuple type
+     *
+     * Disambiguation: if the first token inside the bracket is `[`, it's a
+     * tuple (each tuple element starts with `[N]`). Otherwise we look at the
+     * shape: if the first thing is an identifier and the second is also an
+     * identifier or a structural-type keyword, it's `name type` form;
+     * otherwise the first thing is the bare type.
+     */
+    private parseArrayType;
+    /** True if the token looks like the start of a TypeExpression. */
+    private tokenStartsType;
+    private parseTupleElements;
+    private parseMapType;
+    private parseSetType;
+    /**
+     * `union [t1, t2, null]`. Members are scalars or null.
+     */
+    private parseUnionType;
+    private parseUnionMember;
+    private parsePolymorphicType;
+    /** `alternative_name typeExpression [settings]` -- shape is the same as a field declaration, context disambiguates */
+    private parsePolymorphicAlternative;
+    private parseJsonType;
+    /**
+     * Scalar type or named-type reference. Both look like an Identifier with
+     * optional `(p, s)` parameter list. The distinction is made later at the
+     * semantic-analysis stage (named types are user-declared identifiers that
+     * resolve to a TypeDeclaration; scalars are the open set of built-ins).
+     *
+     * Resolution heuristic for the PoC: if the identifier's lowercase form is
+     * a known SQL/BSON scalar name, we tag ScalarType; otherwise we'd ideally
+     * defer to the semantic pass. For the PoC we always emit ScalarType for
+     * common scalar names and ScalarType for everything else too; callers
+     * that need to distinguish can post-process.
+     *
+     * Actually a cleaner choice: emit ScalarType when there are parameters
+     * (no named type takes `(p,s)`), and otherwise emit NamedTypeReference
+     * iff the name's first character is uppercase (heuristic) -- but that
+     * conflicts with Decimal128 etc. So: always emit ScalarType; the
+     * semantic-analysis pass walks Type declarations and rewrites scalars
+     * whose names resolve to user types as NamedTypeReference. The PoC keeps
+     * the AST shape consistent regardless.
+     */
+    private parseScalarOrNamedType;
+    private parseTypeParam;
+    private parseTypeDecl;
+    /**
+     * Finish parsing a v0.1 object-form Type after the name (and optional
+     * pre-body settings) have been consumed. Handles the `{ ...body }` part.
+     */
+    private finishObjectTypeDecl;
+    private parseEdge;
+    private parseView;
+    private parseSourceQueryItem;
+    private parseEnum;
+    private parseRef;
+    private parseRefSpec;
+    private parseCardinalityOperator;
+    private parseRefEndpoint;
+    /**
+     * Parse a dotted path with the §18 segment vocabulary:
+     *
+     *   IDENTIFIER                  -- a field segment
+     *   .IDENTIFIER                 -- field
+     *   .[N]                        -- array index (positional)
+     *   .[*]                        -- array wildcard (via ArrayWildcard token)
+     *   ."quoted name"              -- quoted-identifier field
+     *   .["literal key"]            -- map literal key
+     *
+     * We start by consuming an identifier/qualified head, then walk pathTail.
+     * The JSONPath-alias forms `[N]`, `[*]` without a leading dot are
+     * recognized as well; they normalize to the dot-prefixed form.
+     *
+     * For the PoC we stop at the first token that doesn't continue a path
+     * (e.g., a cardinality operator, a comma, a settings bracket).
+     */
+    private parsePathSegments;
+    private parseTablePartial;
+    private parseTableGroup;
+    private parseIndexes;
+    private parseIndexEntry;
+    private parseIndexComponent;
+    private parseChecks;
+    private parseCheckEntry;
+    private maybeSettingsBlock;
+    /**
+     * A single setting. Forms:
+     *   flag                  -- bare identifier(s), e.g. `pk`, `not null`
+     *   name: value           -- key/value, e.g. `default: 'x'`, `synonyms: [...]`
+     *   ref: > target         -- inline ref
+     *
+     * The grammar for "flag" is annoying because `not null` is two words but is
+     * still one flag. We handle the multi-word flags by greedy lowercase prefix
+     * match: `not` followed by `null` becomes `not null`; `primary` followed by
+     * `key` becomes `primary key`.
+     */
+    private parseSetting;
+    /**
+     * A setting value. Open-vocabulary:
+     *   string literal, multi-line string, number, boolean, null, identifier
+     *   (or dotted identifier path), expression literal, list `[...]`
+     */
+    private parseSettingValue;
+    private parseIdentLikeName;
+}
+/**
+ * Parse xDBML source.
+ *
+ * - 1-argument form `parse(source)` parses self-contained documents (any
+ *   module directive must carry an inline clone block; reference-only
+ *   directives throw).
+ * - 2-argument form `parse(source, options)` accepts a `readFile`
+ *   resolver for cross-file `use`/`reuse` directives and a `filePath`
+ *   identifying the source for relative-path resolution. See
+ *   `ParseOptions` for the full shape.
+ *
+ * The function is fully synchronous. Async file loading and incremental
+ * resolution are intentionally out of scope -- callers needing async I/O
+ * should pre-load their module graph and supply a `readFile` callback
+ * that returns from an in-memory map.
+ */
+export declare function parse(source: string, options?: ParseOptions): XDbmlDocument;