@xdbml/parse 0.3.2 → 0.5.0

package/dist/parser.js

@@ -13,11 +13,37 @@ import { TokenKind, tokenize, } from "./lexer.js";
 import { resolveImport, classifyModuleSource, ModuleSourceError } from "./module-resolver.js";
 export class ParseError extends Error {
     position;
-    constructor(message, position) {
+    /**
+     * Optional machine-readable reason. Set for the errors a caller may want
+     * to tell apart from a plain syntax error: `unsupported-version` when a
+     * document declares a newer version than this parser supports (spec 4.1).
+     */
+    code;
+    constructor(message, position, code) {
         super(`${message} (line ${position.line}, column ${position.column})`);
         this.position = position;
+        if (code)
+            this.code = code;
     }
 }
+/**
+ * The newest specification version this parser implements. A document
+ * declaring a later version is refused (spec 4.1) rather than parsed with
+ * semantics it does not have.
+ */
+export const SUPPORTED_XDBML_VERSION = '0.5';
+/** Compare dotted version strings numerically: -1, 0 or 1. */
+export function compareVersions(a, b) {
+    const pa = a.split('.').map((n) => Number(n) || 0);
+    const pb = b.split('.').map((n) => Number(n) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
 /* -------------------------------------------------------------------------
  * Keyword recognition.
  *
@@ -31,13 +57,13 @@ const CONTAINER_KEYWORDS = new Set([
 const ENTITY_KEYWORDS = new Set(['table', 'entity', 'collection', 'record']);
 /**
  * Element-type keywords accepted in module-system import items
- * (spec §26.3). Stored lowercased; matching is case-insensitive.
+ * (spec §27.3). Stored lowercased; matching is case-insensitive.
  *
  * `field` is recognized but explicitly rejected by parseImportItem in P4
  * (field-level imports have special declaration-vs-placement semantics
  * that will land in a later batch).
  *
- * `project` is intentionally excluded -- spec §26.1 forbids importing
+ * `project` is intentionally excluded -- spec §27.1 forbids importing
  * Project declarations.
  */
 const IMPORT_ELEMENT_TYPES = new Set([
@@ -45,7 +71,7 @@ const IMPORT_ELEMENT_TYPES = new Set([
     'enum', 'tablepartial', 'note',
     'schema', 'container', 'tablegroup',
     'type', 'edge', 'view', 'diagramview',
-    'field',
+    'field', 'supertypegroup',
 ]);
 const STRUCTURAL_TYPE_KEYWORDS = new Set([
     'object', 'struct', 'record', 'array', 'list', 'map', 'dict', 'dictionary',
@@ -98,7 +124,7 @@ export class Parser {
      * 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
+     * directive rather than recursing (matching spec §27.15: cycles are
      * allowed; name resolution handles them). The set is passed by reference
      * across recursive parse() calls so all transitive levels see it.
      *
@@ -179,6 +205,11 @@ export class Parser {
         this.advance(); // xdbml
         this.expect(TokenKind.Colon, "Expected ':' after 'xdbml'");
         const numTok = this.expect(TokenKind.NumberLiteral, 'Expected version number');
+        if (compareVersions(numTok.text, SUPPORTED_XDBML_VERSION) > 0) {
+            throw new ParseError(`This document declares 'xdbml: ${numTok.text}', which is newer than the ` +
+                `latest version this parser supports (${SUPPORTED_XDBML_VERSION}). ` +
+                'Use a newer parser, or declare a supported version.', numTok.start, 'unsupported-version');
+        }
         return {
             kind: 'VersionDeclaration',
             version: numTok.text,
@@ -231,6 +262,8 @@ export class Parser {
             return this.parseTablePartial();
         if (k === 'tablegroup')
             return this.parseTableGroup();
+        if (k === 'supertypegroup')
+            return this.parseSupertypeGroup();
         if (k === 'note')
             return this.parseNoteDeclaration();
         if (k === 'records')
@@ -477,7 +510,7 @@ export class Parser {
         };
     }
     /**
-     * Parse a `records { ... }` block inside an entity body (§25.1, implicit
+     * Parse a `records { ... }` block inside an entity body (§26.1, implicit
      * column list). Values are stored as SettingValue cells; row boundaries
      * are determined by source line (see `parseRecordRow`).
      */
@@ -497,7 +530,7 @@ export class Parser {
         };
     }
     /**
-     * Top-level records declaration (§25.2, new in v0.2):
+     * Top-level records declaration (§26.2, new in v0.2):
      *
      *     records users (id, name, email) { ... }
      *     records core.users (id, name, email) { ... }
@@ -587,7 +620,7 @@ export class Parser {
             span: this.spanFrom(start),
         };
     }
-    /* ----- Module-system directives (spec §26, new in v0.2) ----- */
+    /* ----- Module-system directives (spec §27, new in v0.2) ----- */
     /**
      * Parse a `use` or `reuse` directive. Called from both the top-level
      * dispatcher and the Container body dispatcher; the caller indicates
@@ -701,7 +734,7 @@ export class Parser {
                         resolvedPath = result.resolvedPath;
                         break;
                     case 'cycle':
-                        // Per spec §26.15, cycles are allowed; the parser produces a
+                        // Per spec §27.15, cycles are allowed; the parser produces a
                         // directive with no clone, and name resolution (P6+) is
                         // expected to bridge the cycle. We leave clone undefined.
                         resolvedPath = result.resolvedPath;
@@ -759,12 +792,12 @@ export class Parser {
                 `Expected one of: ${Array.from(IMPORT_ELEMENT_TYPES).join(', ')}.`, elemTok.start);
         }
         if (elementType === 'field' && context !== 'file-scope') {
-            // Spec §26.8: field imports must appear at file scope. Inside a
+            // Spec §27.8: field imports must appear at file scope. Inside a
             // Container body, the field's eventual placement (as a Named Type)
             // would have no meaningful container scope -- field imports are
             // always lifted to file scope by flatten(), regardless of where
             // the directive sits.
-            throw new ParseError(`Field-level imports must appear at file scope, not inside a Container body (spec §26.8).`, elemTok.start);
+            throw new ParseError(`Field-level imports must appear at file scope, not inside a Container body (spec §27.8).`, elemTok.start);
         }
         this.advance(); // consume element type keyword
         // Dotted source path.
@@ -795,12 +828,12 @@ export class Parser {
      * 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
+     * Per spec §27.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
+     * Container, etc.). The exception is field imports (§27.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
@@ -816,7 +849,7 @@ export class Parser {
                 statements.push(this.parseTopLevelStatement());
             }
             else {
-                // Bare field declaration -- the field-import case. Per spec §26.6
+                // Bare field declaration -- the field-import case. Per spec §27.6
                 // the field appears without an entity wrapper.
                 statements.push(this.parseFieldDeclaration());
             }
@@ -1284,7 +1317,7 @@ export class Parser {
         }
         throw new ParseError(`Expected type parameter, got ${t.kind}`, t.start);
     }
-    /* ----- Type declaration (§13) ----- */
+    /* ----- Type declaration (§15) ----- */
     parseTypeDecl() {
         const start = this.peek().start;
         this.advance(); // Type
@@ -1293,7 +1326,7 @@ export class Parser {
         //
         //   { ... }                           v0.1 object form, no pre-body settings
         //   [ settings ] { ... }              v0.1 object form, pre-body settings (permissive)
-        //   typeExpression                    v0.2 scalar form (spec §14.7)
+        //   typeExpression                    v0.2 scalar form (spec §15.7)
         //   typeExpression [ settings ]       v0.2 scalar form with field-level settings
         //
         // Note that LBrace and LBracket are distinct from any start-of-type-expression
@@ -1494,8 +1527,12 @@ export class Parser {
             settings = this.maybeSettingsBlock();
         }
         else if (this.match(TokenKind.LBrace)) {
-            // long form: `Ref name { a > b }`
+            // long form: `Ref name { a > b }`, or, since v0.4, with a settings
+            // block after the relationship expression: `Ref name { a > b [flag] }`.
+            // Accepting settings here puts every setting of spec 11.9 in all three
+            // declaration forms; a long form written without one parses as before.
             spec = this.parseRefSpec();
+            settings = this.maybeSettingsBlock();
             this.expect(TokenKind.RBrace, "Expected '}' closing Ref body");
         }
         else {
@@ -1568,7 +1605,7 @@ export class Parser {
         };
     }
     /**
-     * Parse a dotted path with the §18 segment vocabulary:
+     * Parse a dotted path with the §20 segment vocabulary:
      *
      *   IDENTIFIER                  -- a field segment
      *   .IDENTIFIER                 -- field
@@ -1742,6 +1779,67 @@ export class Parser {
             span: this.spanFrom(start),
         };
     }
+    /* ----- SupertypeGroup (spec §12, new in v0.5) ----- */
+    /**
+     * `SupertypeGroup <name> [supertype: X, ...] { Sub1  Sub2 [strategy: y] }`.
+     * Members are separated like TableGroup members: newline, comma or
+     * semicolon (spec §3.9). A name is required (§12.1); a writer exporting a
+     * group that has none emits `undefinedGroup1`, `undefinedGroup2`, ... so
+     * the parser never supplies one. Values are validated after parsing, by
+     * `checkSupertypeGroups()`, so an unknown value gets a located diagnostic
+     * rather than stopping the parse.
+     */
+    parseSupertypeGroup() {
+        const start = this.peek().start;
+        this.advance(); // SupertypeGroup
+        const nameTok = this.peek();
+        if (nameTok.kind !== TokenKind.Identifier && nameTok.kind !== TokenKind.QuotedIdentifier) {
+            throw new ParseError('Expected a name after SupertypeGroup. Every group has a name (spec §12.1); ' +
+                'a group exported without one is written undefinedGroup1, undefinedGroup2, ...', nameTok.start);
+        }
+        const name = this.parseIdentLikeName('SupertypeGroup name');
+        const settings = this.maybeSettingsBlock();
+        this.expect(TokenKind.LBrace, "Expected '{' after SupertypeGroup name and settings");
+        const members = [];
+        while (!this.check(TokenKind.RBrace) && !this.check(TokenKind.EOF)) {
+            const t = this.peek();
+            if (t.kind === TokenKind.Identifier || t.kind === TokenKind.QuotedIdentifier) {
+                const memberStart = t.start;
+                this.advance();
+                let n = t.kind === TokenKind.QuotedIdentifier ? (t.value ?? '') : t.text;
+                while (this.check(TokenKind.Dot)) {
+                    this.advance();
+                    const next = this.peek();
+                    if (next.kind !== TokenKind.Identifier && next.kind !== TokenKind.QuotedIdentifier) {
+                        throw new ParseError('Expected identifier after dot in subtype path', next.start);
+                    }
+                    this.advance();
+                    n += `.${next.kind === TokenKind.QuotedIdentifier ? (next.value ?? '') : next.text}`;
+                }
+                const memberSettings = this.maybeSettingsBlock();
+                members.push({
+                    kind: 'SupertypeGroupMember',
+                    name: n,
+                    settings: memberSettings,
+                    span: this.spanFrom(memberStart),
+                });
+            }
+            else if (t.kind === TokenKind.Semicolon || t.kind === TokenKind.Comma) {
+                this.advance();
+            }
+            else {
+                throw new ParseError(`Unexpected ${t.kind} in SupertypeGroup body; expected a subtype entity name`, t.start);
+            }
+        }
+        this.expect(TokenKind.RBrace, "Expected '}' closing SupertypeGroup");
+        return {
+            kind: 'SupertypeGroupDeclaration',
+            name,
+            settings,
+            members,
+            span: this.spanFrom(start),
+        };
+    }
     /* ----- Indexes ----- */
     parseIndexes() {
         const start = this.peek().start;

package/dist/relationships.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Relationship helpers and checks (spec 11.10 through 11.12, new in v0.4).
+ *
+ * A `Ref` carries its relationship type in its settings block. The
+ * `foreign_master` flag marks denormalized replication: the parent endpoint
+ * holds the master value for a copy held at the child endpoint. Absence of
+ * the flag marks a referential relationship, the foreign key.
+ *
+ * This module holds three things:
+ *
+ *   1. `relationshipType()` and `isForeignMaster()` -- one definition of the
+ *      type test, so the renderer, the MCP server, and any generator agree
+ *      rather than each re-reading the settings array.
+ *
+ *   2. `refChildEndpoint()` / `refParentEndpoint()` -- which side of a Ref is
+ *      the child. The cardinality operator decides: `>` and `-` put the child
+ *      on the left, `<` puts it on the right. `<>` has no single child.
+ *
+ *   3. `checkRelationships()` -- the semantic rules of spec 11.11 that the
+ *      grammar cannot express. Called from `resolveNames()`, so every
+ *      consumer of the resolver's diagnostics gets them without opting in.
+ */
+import type { Diagnostic } from './name-resolver.ts';
+import type { PathSegment, RefDeclaration, RefEndpoint, RefValue, Setting, XDbmlDocument } from './ast.ts';
+export type RelationshipType = 'referential' | 'foreign_master';
+/** The flag name, spelled once. */
+export declare const FOREIGN_MASTER_FLAG = "foreign_master";
+/** Accepted values of the `constraint_type` setting (spec 11.15). */
+export declare const CONSTRAINT_TYPES: readonly ["identifying", "non_identifying"];
+export type ConstraintType = (typeof CONSTRAINT_TYPES)[number];
+/**
+ * Relationship settings introduced in v0.4 alongside the foreign master
+ * flag. Gated on the declared version like the flag itself, so a document
+ * declaring an earlier version does not quietly carry v0.4 semantics.
+ */
+export declare const V04_RELATIONSHIP_SETTINGS: readonly ["source_role", "target_role", "source_verb", "target_verb", "constraint_type"];
+/** The `constraint_type` a Ref declares, or undefined when unstated. */
+export declare function constraintType(ref: RefDeclaration): ConstraintType | undefined;
+/** True when the Ref is marked `undirected: true` (spec 11.16.2). */
+export declare function isUndirected(ref: RefDeclaration): boolean;
+/**
+ * True when a settings array carries the `foreign_master` flag. The flag
+ * takes no value, so presence is the whole test; a `foreign_master: true`
+ * spelling is accepted as well rather than silently ignored, since a user
+ * reaching for the more explicit form means the same thing.
+ */
+export declare function hasForeignMasterFlag(settings: ReadonlyArray<Setting>): boolean;
+/** The relationship type a Ref declares. */
+export declare function relationshipType(ref: RefDeclaration): RelationshipType;
+/** Convenience wrapper over `relationshipType`. */
+export declare function isForeignMaster(ref: RefDeclaration): boolean;
+/**
+ * The child endpoint of a Ref, i.e. the side holding the copy (for a foreign
+ * master) or the foreign key (for a referential relationship).
+ *
+ *   a.x > b.y    many a to one b     -> a.x is the child
+ *   a.x < b.y    one a to many b     -> b.y is the child
+ *   a.x - b.y    one to one          -> a.x is the child, by convention
+ *   a.x <> b.y   many to many        -> no single child; returns undefined
+ */
+export declare function refChildEndpoint(ref: RefDeclaration): RefEndpoint | undefined;
+/** The parent endpoint of a Ref, i.e. the opposite side of the child. */
+export declare function refParentEndpoint(ref: RefDeclaration): RefEndpoint | undefined;
+/**
+ * Every name an entity answers to in a document: its own name, and its
+ * container-qualified name where it sits inside one. Mirrors the index the
+ * renderer builds, so both agree on what an entity-level path looks like.
+ */
+export declare function entityNames(doc: XDbmlDocument): Set<string>;
+/**
+ * True when an endpoint names an entity and stops there (spec 11.16), as in
+ * `Customer` or `shop.orders`. A structural test is not enough: `b.aid` has
+ * the same shape and names a field, so the whole path is checked against the
+ * entities the document declares.
+ */
+export declare function isEntityLevelEndpoint(endpoint: RefEndpoint, names: Set<string>): boolean;
+/** Render a path as a dotted string, for messages and for identity keys. */
+export declare function pathToString(path: ReadonlyArray<PathSegment>): string;
+/**
+ * True when the document declares at least `min`. A document with no version
+ * declaration is plain DBML and supports no xDBML construct, so it fails
+ * every gate.
+ *
+ * Kept general rather than special-cased to the foreign master flag: the
+ * module-system gates described in the grammar notes are not implemented yet
+ * and can adopt this helper when they are.
+ */
+export declare function versionAtLeast(doc: XDbmlDocument, min: string): boolean;
+/**
+ * Semantic checks for foreign master relationships (spec 11.11), plus the
+ * inline-form rule of 11.10.2 and the version gate of section 4.
+ *
+ * The composite rule is checked here rather than in the grammar so the error
+ * can name the flag that makes the composite invalid, instead of failing on
+ * a form that is perfectly legal for a referential relationship.
+ */
+export declare function checkRelationships(doc: XDbmlDocument): Diagnostic[];
+/** Re-exported for consumers that only need the inline ref value shape. */
+export type { RefValue };