@xdbml/parse 0.4.0 → 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
@@ -1572,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
@@ -1746,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/supertypes.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Supertype groups (spec §12, new in v0.5).
+ *
+ * Three things live here:
+ *
+ *   - Setting normalization. `completeness`, `exclusivity`, `strategy` and
+ *     `merge` accept a canonical value and a set of aliases (spec §12.2).
+ *     The AST keeps what was written; `supertypeGroupSettings()` returns
+ *     the canonical values.
+ *   - Member resolution. The supertype and every subtype name an entity by
+ *     path, bare (`Person`) or container-qualified (`crm.Person`), with the
+ *     same reading as an entity-level `Ref` endpoint (spec §11.16.3).
+ *   - The validation rules summarized in spec §12.8, run by `resolveNames()`
+ *     on the flattened document so imported and cloned groups are checked
+ *     like local ones.
+ *
+ * Nothing here computes the attributes or keys a subtype would hold in a
+ * physical model. A subtype declares its own attributes only; placing the
+ * supertype's attributes in stored structures is derivation output (spec
+ * §12.5, §12.7). Supertype chains are computed for the structural checks
+ * and for tools that display the hierarchy.
+ */
+import type { Diagnostic } from './name-resolver.ts';
+import type { SupertypeGroupDeclaration, SupertypeGroupMember, XDbmlDocument } from './ast.ts';
+export type Completeness = 'total' | 'partial';
+export type Exclusivity = 'disjoint' | 'overlapping';
+export type MaterializationStrategy = 'preserved_hierarchy' | 'roll_up' | 'roll_down';
+export type MergeOption = 'flat' | 'nested';
+/**
+ * Accepted spellings, keyed by lowercase spelling, mapped to the canonical
+ * value. Canonical values map to themselves.
+ */
+export declare const SUPERTYPE_GROUP_VALUES: {
+    readonly completeness: {
+        readonly total: "total";
+        readonly complete: "total";
+        readonly partial: "partial";
+        readonly incomplete: "partial";
+    };
+    readonly exclusivity: {
+        readonly disjoint: "disjoint";
+        readonly exclusive: "disjoint";
+        readonly overlapping: "overlapping";
+        readonly non_exclusive: "overlapping";
+    };
+    readonly strategy: {
+        readonly preserved_hierarchy: "preserved_hierarchy";
+        readonly class_table: "preserved_hierarchy";
+        readonly joined: "preserved_hierarchy";
+        readonly roll_up: "roll_up";
+        readonly single_table: "roll_up";
+        readonly roll_down: "roll_down";
+        readonly concrete_table: "roll_down";
+        readonly table_per_class: "roll_down";
+    };
+    readonly merge: {
+        readonly flat: "flat";
+        readonly flat_with_discriminator: "flat";
+        readonly nested: "nested";
+    };
+};
+export type SupertypeGroupValueSetting = keyof typeof SUPERTYPE_GROUP_VALUES;
+/** The canonical value for a spelling, or undefined when it is not recognized. */
+export declare function canonicalSupertypeGroupValue(setting: SupertypeGroupValueSetting, raw: string): string | undefined;
+/** A group's settings with canonical values. Unrecognized values are left out. */
+export interface SupertypeGroupSettings {
+    supertype?: string;
+    completeness?: Completeness;
+    exclusivity?: Exclusivity;
+    strategy?: MaterializationStrategy;
+    merge?: MergeOption;
+    discriminator?: string;
+    note?: string;
+}
+export declare function supertypeGroupSettings(decl: SupertypeGroupDeclaration): SupertypeGroupSettings;
+/** A subtype member's own `strategy` (spec §12.7.4), canonical, or undefined. */
+export declare function subtypeStrategy(member: SupertypeGroupMember): MaterializationStrategy | undefined;
+/** One group with its members resolved to entity ids where they resolve. */
+export interface ResolvedSupertypeGroup {
+    declaration: SupertypeGroupDeclaration;
+    settings: SupertypeGroupSettings;
+    /** Entity id of the supertype, when it resolves. */
+    supertype?: string;
+    subtypes: Array<{
+        member: SupertypeGroupMember;
+        /** Entity id of the subtype, when it resolves. */
+        entity?: string;
+        /** The member's own strategy, canonical, when stated and recognized. */
+        strategy?: MaterializationStrategy;
+    }>;
+}
+/**
+ * Every SupertypeGroup of a document with its members resolved. Pass the
+ * flattened document (see `flatten()`) so imported and cloned declarations
+ * are visible. Entity ids are container-qualified for entities declared in
+ * a Container, bare otherwise.
+ */
+export declare function resolveSupertypeGroups(doc: XDbmlDocument): ResolvedSupertypeGroup[];
+/**
+ * For each entity that is a subtype, its chain of supertypes, nearest
+ * first: `Employee -> [Person, Party]`. When an entity is listed as a
+ * subtype in several groups (an error), the first group wins; a chain that
+ * loops stops before repeating an entity.
+ */
+export declare function supertypeChains(doc: XDbmlDocument): Map<string, string[]>;
+/**
+ * The rules of spec §12.8. Run by `resolveNames()` on the flattened
+ * document; exported for callers that check groups on their own.
+ */
+export declare function checkSupertypeGroups(doc: XDbmlDocument): Diagnostic[];