@xdbml/parse 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -32,6 +32,8 @@ export { flatten } from './module-resolver.ts';
 export { classifyModuleSource, isUrlKey, ModuleSourceError, } from './module-resolver.ts';
 export type { ModuleSource } from './module-resolver.ts';
 export { resolveNames, SymbolTable } from './name-resolver.ts';
+export { FOREIGN_MASTER_FLAG, checkRelationships, hasForeignMasterFlag, isForeignMaster, pathToString, refChildEndpoint, refParentEndpoint, relationshipType, versionAtLeast, CONSTRAINT_TYPES, V04_RELATIONSHIP_SETTINGS, constraintType, entityNames, isEntityLevelEndpoint, isUndirected, } from './relationships.ts';
+export type { RelationshipType, ConstraintType } from './relationships.ts';
 export type { Diagnostic, DiagnosticCode, ResolutionResult, SymbolEntry, SymbolKind, } from './name-resolver.ts';
 export { xdbmlLanguageConfig, xdbmlMonarchTokensProvider, } from './monarch.ts';
 export type { XDbmlLanguageConfiguration, XDbmlMonarchLanguage, } from './monarch.ts';

package/dist/index.js

@@ -30,4 +30,5 @@ export { parse, Parser, ParseError } from "./parser.js";
 export { flatten } from "./module-resolver.js";
 export { classifyModuleSource, isUrlKey, ModuleSourceError, } from "./module-resolver.js";
 export { resolveNames, SymbolTable } from "./name-resolver.js";
+export { FOREIGN_MASTER_FLAG, checkRelationships, hasForeignMasterFlag, isForeignMaster, pathToString, refChildEndpoint, refParentEndpoint, relationshipType, versionAtLeast, CONSTRAINT_TYPES, V04_RELATIONSHIP_SETTINGS, constraintType, entityNames, isEntityLevelEndpoint, isUndirected, } from "./relationships.js";
 export { xdbmlLanguageConfig, xdbmlMonarchTokensProvider, } from "./monarch.js";

package/dist/keywords.d.ts

@@ -38,8 +38,8 @@ export declare const STRUCTURAL_TYPE_KEYWORDS: readonly ["object", "struct", "ar
 export declare const POLYMORPHISM_KEYWORDS: readonly ["union", "oneof", "anyof", "allof"];
 export declare const SCALAR_TYPES: readonly ["tinyint", "smallint", "mediumint", "int", "integer", "bigint", "int32", "int64", "float", "double", "decimal", "dec", "numeric", "real", "bit", "bool", "boolean", "char", "varchar", "varchar2", "nvarchar", "nvarchar2", "nchar", "text", "mediumtext", "longtext", "string", "ntext", "binary", "varbinary", "blob", "mediumblob", "longblob", "tinyblob", "tinytext", "json", "jsonb", "variant", "xml", "date", "time", "datetime", "datetime2", "timestamp", "timestamptz", "year", "uuid", "inet6", "money", "smallmoney", "enum"];
 export declare const BSON_TYPES: readonly ["objectid", "decimal128", "bindata", "minkey", "maxkey", "symbol", "regex", "long", "double"];
-export declare const SETTING_FLAGS: readonly ["pk", "primary", "key", "unique", "null", "not", "required", "increment", "inactive"];
-export declare const SETTING_KEYS: readonly ["note", "default", "ref", "name", "color", "headercolor", "as", "check", "type", "target", "targets", "database_type", "source", "source_cardinality", "target_cardinality", "min_source", "max_source", "min_target", "max_target", "undirected", "discriminator", "source_query", "materialized", "refresh_schedule", "refresh_on", "source_database", "storage_options", "pattern", "format", "minlength", "maxlength", "minimum", "maximum", "exclusiveminimum", "exclusivemaximum", "multipleof", "minitems", "maxitems", "uniqueitems", "minproperties", "maxproperties", "synonyms", "business_term", "granularity", "tags", "delete", "update", "indexes", "checks", "replication", "location", "default_charset", "cloned_at"];
+export declare const SETTING_FLAGS: readonly ["pk", "primary", "key", "unique", "null", "not", "required", "increment", "inactive", "foreign_master"];
+export declare const SETTING_KEYS: readonly ["note", "default", "ref", "name", "color", "headercolor", "as", "check", "type", "target", "targets", "database_type", "source", "source_cardinality", "target_cardinality", "min_source", "max_source", "min_target", "max_target", "undirected", "source_role", "target_role", "source_verb", "target_verb", "constraint_type", "discriminator", "source_query", "materialized", "refresh_schedule", "refresh_on", "source_database", "storage_options", "pattern", "format", "minlength", "maxlength", "minimum", "maximum", "exclusiveminimum", "exclusivemaximum", "multipleof", "minitems", "maxitems", "uniqueitems", "minproperties", "maxproperties", "synonyms", "business_term", "granularity", "tags", "delete", "update", "indexes", "checks", "replication", "location", "default_charset", "cloned_at"];
 export declare const GRANULARITY_VALUES: readonly ["year", "quarter", "month", "week", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond"];
 export declare const DIRECTIVE_KEYWORDS: readonly ["xdbml", "experimental"];
 export declare const MODULE_KEYWORDS: readonly ["use", "reuse", "from", "as"];

package/dist/keywords.js

@@ -164,6 +164,7 @@ export const SETTING_FLAGS = [
     'required',
     'increment',
     'inactive', // v0.2 §11.9: Ref flag for visualization-only deactivation
+    'foreign_master', // v0.4 §11.10: Ref flag for denormalized replication
 ];
 export const SETTING_KEYS = [
     // General
@@ -188,6 +189,12 @@ export const SETTING_KEYS = [
     'min_target',
     'max_target',
     'undirected',
+    // v0.4 relationship documentation (spec 11.14, 11.15)
+    'source_role',
+    'target_role',
+    'source_verb',
+    'target_verb',
+    'constraint_type',
     'discriminator',
     'source_query',
     'materialized',

package/dist/name-resolver.d.ts

@@ -67,7 +67,7 @@ export interface SymbolEntry {
  * Stable diagnostic code. Tooling can match on these to filter or style
  * messages without parsing the human-readable text.
  */
-export type DiagnosticCode = 'duplicate-declaration' | 'unresolved-type' | 'unresolved-entity' | 'unresolved-field' | 'unresolved-partial' | 'unresolved-tablegroup-member' | 'unresolved-records-entity' | 'unresolved-records-column' | 'empty-import' | 'invalid-nested-path';
+export type DiagnosticCode = 'duplicate-declaration' | 'unresolved-type' | 'unresolved-entity' | 'unresolved-field' | 'unresolved-partial' | 'unresolved-tablegroup-member' | 'unresolved-records-entity' | 'unresolved-records-column' | 'empty-import' | 'invalid-nested-path' | 'foreign-master-composite' | 'foreign-master-duplicate-child' | 'foreign-master-without-ref' | 'construct-requires-version' | 'ambiguous-ref-endpoint' | 'invalid-constraint-type' | 'constraint-type-on-foreign-master' | 'invalid-undirected' | 'entity-level-many-to-many';
 /**
  * A single resolution diagnostic. Severity is currently always `error`,
  * but the field is included to leave room for future warnings (e.g.,

package/dist/name-resolver.js

@@ -40,6 +40,7 @@
  */
 import { SCALAR_TYPES, BSON_TYPES } from "./keywords.js";
 import { flatten } from "./module-resolver.js";
+import { checkRelationships } from "./relationships.js";
 /**
  * Read-only handle on the collected symbol table.
  *
@@ -134,6 +135,8 @@ export function resolveNames(doc) {
     const symbols = new SymbolTable(entries);
     // Pass 2: resolve references.
     resolveReferences(flat, symbols, diagnostics);
+    // Pass 3: relationship rules that the grammar cannot express (spec 11.11).
+    diagnostics.push(...checkRelationships(flat));
     return { diagnostics, symbols };
 }
 /* -------------------------------------------------------------------------
@@ -507,8 +510,28 @@ function resolveRefSpec(endpoint, symbols, diagnostics) {
     else {
         maxEntityLen = leadingFields.length - 1;
     }
-    if (maxEntityLen < 1)
+    // An entity-level endpoint (spec 11.16) names an entity and stops there:
+    // `Customer`, or `shop.orders` for an entity inside a container. It is
+    // checked as a fallback rather than first, so an endpoint that already
+    // resolved as entity-plus-attribute keeps that reading and every document
+    // that parsed before this means what it meant before.
+    const wholePath = leadingFields.join('.');
+    const entityLevelMatch = (!hasComposite && !hasNonFieldTail)
+        ? resolveEntityRef(wholePath, symbols)
+        : undefined;
+    if (maxEntityLen < 1) {
+        // A single segment cannot be entity-plus-attribute, so it is either an
+        // entity-level endpoint or a reference to something undeclared.
+        if (!entityLevelMatch) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'unresolved-entity',
+                message: `Relationship endpoint references unknown entity '${wholePath}'.`,
+                span: endpoint.span,
+            });
+        }
         return;
+    }
     // PHASE 1 (cont'd): longest-prefix entity match.
     let entity;
     let entityPrefixLen = 0;
@@ -522,15 +545,29 @@ function resolveRefSpec(endpoint, symbols, diagnostics) {
         }
     }
     if (!entity) {
+        if (entityLevelMatch)
+            return; // entity-level endpoint; nothing further to check
         const guess = leadingFields.slice(0, maxEntityLen).join('.');
         diagnostics.push({
             severity: 'error',
             code: 'unresolved-entity',
-            message: `Foreign-key endpoint references unknown entity '${guess}'.`,
+            message: `Relationship endpoint references unknown entity '${guess}'.`,
             span: endpoint.span,
         });
         return;
     }
+    if (entityLevelMatch) {
+        // Both readings exist: `a.b` names an entity, and `a` names an entity
+        // with a field `b`. The attribute reading wins, and the collision is
+        // reported so the author can qualify the path differently.
+        diagnostics.push({
+            severity: 'warning',
+            code: 'ambiguous-ref-endpoint',
+            message: `Endpoint '${wholePath}' names both an entity and a field of entity '${entity.qualifiedName}'. ` +
+                'Reading it as the field; rename one of them or qualify the path to remove the ambiguity.',
+            span: endpoint.span,
+        });
+    }
     if (entity.declaration.kind !== 'EntityDeclaration')
         return;
     // PHASE 2: compute the post-entity portion of endpoint.path.

package/dist/parser.d.ts

@@ -216,6 +216,15 @@ export declare class Parser {
      * otherwise the first thing is the bare type.
      */
     private parseArrayType;
+    /** array/set sugar: fold a following comma-list of union-eligible members
+     *  (`[T1, T2, ...]`) into a UnionType. Applies only when the element is a
+     *  scalar/named type with no per-member settings; `null` is allowed as a
+     *  later member. Object shapes use `oneOf`, positional layouts use a tuple. */
+    private maybeFoldUnionSugar;
+    /** A type usable as a `union` member (and thus foldable from array sugar).
+     *  `null` is only ever a later member (parsed via parseUnionMember), never
+     *  the first standalone element type, so it is not listed here. */
+    private isUnionMemberType;
     /** True if the token looks like the start of a TypeExpression. */
     private tokenStartsType;
     private parseTupleElements;

package/dist/parser.js

@@ -1020,8 +1020,11 @@ export class Parser {
             && this.tokenStartsType(second)) {
             elementName = this.advance().text;
         }
-        const elementType = this.parseTypeExpression();
+        const elemStart = this.peek().start;
+        let elementType = this.parseTypeExpression();
         const elementSettings = this.maybeSettingsBlock();
+        // Sugar: `array [T1, T2, ...]` == `array [union [T1, T2, ...]]` (see helper).
+        elementType = this.maybeFoldUnionSugar(elementType, elemStart, elementSettings.length === 0);
         this.expect(TokenKind.RBracket, "Expected ']' closing array");
         return {
             kind: 'ArrayType',
@@ -1032,6 +1035,33 @@ export class Parser {
             span: this.spanFrom(start),
         };
     }
+    /** array/set sugar: fold a following comma-list of union-eligible members
+     *  (`[T1, T2, ...]`) into a UnionType. Applies only when the element is a
+     *  scalar/named type with no per-member settings; `null` is allowed as a
+     *  later member. Object shapes use `oneOf`, positional layouts use a tuple. */
+    maybeFoldUnionSugar(elementType, elemStart, noElementSettings) {
+        if (noElementSettings
+            && this.check(TokenKind.Comma)
+            && this.isUnionMemberType(elementType)) {
+            const members = [elementType];
+            while (this.match(TokenKind.Comma)) {
+                members.push(this.parseUnionMember());
+            }
+            return {
+                kind: 'UnionType',
+                members,
+                span: this.spanFrom(elemStart),
+            };
+        }
+        return elementType;
+    }
+    /** A type usable as a `union` member (and thus foldable from array sugar).
+     *  `null` is only ever a later member (parsed via parseUnionMember), never
+     *  the first standalone element type, so it is not listed here. */
+    isUnionMemberType(t) {
+        return t.kind === 'ScalarType'
+            || t.kind === 'NamedTypeReference';
+    }
     /** True if the token looks like the start of a TypeExpression. */
     tokenStartsType(t) {
         if (t.kind === TokenKind.LBrace)
@@ -1095,7 +1125,11 @@ export class Parser {
         const start = this.peek().start;
         this.advance(); // set
         this.expect(TokenKind.LBracket, "Expected '[' after set");
-        const elementType = this.parseTypeExpression();
+        const elemStart = this.peek().start;
+        let elementType = this.parseTypeExpression();
+        // Sugar: `set [T1, T2, ...]` == `set [union [T1, T2, ...]]` (set has no
+        // per-element settings, so the fold is always eligible).
+        elementType = this.maybeFoldUnionSugar(elementType, elemStart, true);
         this.expect(TokenKind.RBracket, "Expected ']' closing set");
         return {
             kind: 'SetType',
@@ -1460,8 +1494,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 {

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 };

package/dist/relationships.js

@@ -0,0 +1,436 @@
+/**
+ * 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.
+ */
+/** The flag name, spelled once. */
+export const FOREIGN_MASTER_FLAG = 'foreign_master';
+/** Accepted values of the `constraint_type` setting (spec 11.15). */
+export const CONSTRAINT_TYPES = ['identifying', 'non_identifying'];
+/**
+ * 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 const V04_RELATIONSHIP_SETTINGS = [
+    'source_role',
+    'target_role',
+    'source_verb',
+    'target_verb',
+    'constraint_type',
+];
+/** The `constraint_type` a Ref declares, or undefined when unstated. */
+export function constraintType(ref) {
+    const s = ref.settings.find((x) => x.name === 'constraint_type');
+    if (!s || !s.value)
+        return undefined;
+    const raw = settingText(s);
+    return CONSTRAINT_TYPES.includes(raw)
+        ? raw
+        : undefined;
+}
+/** True when the Ref is marked `undirected: true` (spec 11.16.2). */
+export function isUndirected(ref) {
+    const s = ref.settings.find((x) => x.name === 'undirected');
+    return !!s && !!s.value && settingText(s) === 'true';
+}
+/** The text of a setting value, for the string-ish value kinds. */
+function settingText(s) {
+    const v = s.value;
+    if (!v)
+        return '';
+    switch (v.kind) {
+        case 'StringValue':
+        case 'IdentifierValue':
+        case 'NumberValue':
+            return String(v.value);
+        case 'BooleanValue':
+            return String(v.value);
+        default:
+            return '';
+    }
+}
+/**
+ * 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 function hasForeignMasterFlag(settings) {
+    return settings.some((s) => s.name === FOREIGN_MASTER_FLAG);
+}
+/** The relationship type a Ref declares. */
+export function relationshipType(ref) {
+    return hasForeignMasterFlag(ref.settings) ? 'foreign_master' : 'referential';
+}
+/** Convenience wrapper over `relationshipType`. */
+export function isForeignMaster(ref) {
+    return relationshipType(ref) === 'foreign_master';
+}
+/* -------------------------------------------------------------------------
+ * Which end is the child
+ * ----------------------------------------------------------------------- */
+/**
+ * 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 function refChildEndpoint(ref) {
+    switch (ref.spec.operator) {
+        case '>':
+        case '-':
+            return ref.spec.source;
+        case '<':
+            return ref.spec.target;
+        default:
+            return undefined;
+    }
+}
+/** The parent endpoint of a Ref, i.e. the opposite side of the child. */
+export function refParentEndpoint(ref) {
+    switch (ref.spec.operator) {
+        case '>':
+        case '-':
+            return ref.spec.target;
+        case '<':
+            return ref.spec.source;
+        default:
+            return 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 function entityNames(doc) {
+    const names = new Set();
+    const add = (name, container) => {
+        names.add(name);
+        if (container)
+            names.add(`${container}.${name}`);
+    };
+    for (const stmt of doc.statements) {
+        if (stmt.kind === 'EntityDeclaration')
+            add(stmt.name);
+        else if (stmt.kind === 'ContainerDeclaration') {
+            for (const item of stmt.body) {
+                if (item.kind === 'EntityDeclaration')
+                    add(item.name, stmt.name);
+            }
+        }
+    }
+    return names;
+}
+/**
+ * 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 function isEntityLevelEndpoint(endpoint, names) {
+    if (endpoint.compositeFields && endpoint.compositeFields.length > 0)
+        return false;
+    if (!endpoint.path.every((seg) => seg.kind === 'PathField'))
+        return false;
+    return names.has(pathToString(endpoint.path));
+}
+/** Render a path as a dotted string, for messages and for identity keys. */
+export function pathToString(path) {
+    return path
+        .map((seg) => {
+        switch (seg.kind) {
+            case 'PathField': return seg.name;
+            case 'PathArrayIndex': return `[${seg.index}]`;
+            case 'PathArrayWildcard': return '[*]';
+            case 'PathMapKey': return `[${seg.key}]`;
+            default: return '?';
+        }
+    })
+        .join('.');
+}
+/* -------------------------------------------------------------------------
+ * Version gating
+ * ----------------------------------------------------------------------- */
+/**
+ * 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 function versionAtLeast(doc, min) {
+    if (!doc.version)
+        return false;
+    const parse = (v) => v.split('.').map((n) => Number(n) || 0);
+    const have = parse(doc.version.version);
+    const want = parse(min);
+    for (let i = 0; i < Math.max(have.length, want.length); i++) {
+        const a = have[i] ?? 0;
+        const b = want[i] ?? 0;
+        if (a !== b)
+            return a > b;
+    }
+    return true;
+}
+/* -------------------------------------------------------------------------
+ * Checks
+ * ----------------------------------------------------------------------- */
+/**
+ * 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 function checkRelationships(doc) {
+    const diagnostics = [];
+    // Child endpoints already claimed by a foreign master, so a second one
+    // into the same attribute can be reported. Keyed by the dotted path.
+    const claimedChildren = new Map();
+    let sawForeignMaster = false;
+    const noteForeignMaster = () => { sawForeignMaster = true; };
+    /* ---- top-level and container-level Ref declarations ---- */
+    const declaredEntities = entityNames(doc);
+    // Any v0.4 relationship setting present anywhere in the document, so the
+    // version gate below covers the documentation settings as well as the flag.
+    let sawV04Setting = false;
+    const checkRelationshipSettings = (ref) => {
+        const entityLevel = isEntityLevelEndpoint(ref.spec.source, declaredEntities)
+            && isEntityLevelEndpoint(ref.spec.target, declaredEntities);
+        for (const setting of ref.settings) {
+            if (V04_RELATIONSHIP_SETTINGS.includes(setting.name)) {
+                sawV04Setting = true;
+            }
+            // 11.15: the value vocabulary is closed, so a typo is an error rather
+            // than a silently ignored setting.
+            if (setting.name === 'constraint_type') {
+                const raw = settingText(setting);
+                if (!CONSTRAINT_TYPES.includes(raw)) {
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'invalid-constraint-type',
+                        message: `'${raw || '(no value)'}' is not a constraint type. ` +
+                            `Use ${CONSTRAINT_TYPES.map((v) => `'${v}'`).join(' or ')}.`,
+                        span: setting.span,
+                    });
+                }
+                else if (isForeignMaster(ref)) {
+                    // 11.15: a foreign master carries no key dependency, so there is
+                    // nothing for identifying or non-identifying to describe.
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'constraint-type-on-foreign-master',
+                        message: "'constraint_type' does not apply to a foreign master relationship, which carries no key dependency.",
+                        span: setting.span,
+                    });
+                }
+            }
+            if (setting.name === 'undirected') {
+                const raw = settingText(setting);
+                if (raw !== 'true' && raw !== 'false') {
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'invalid-undirected',
+                        message: `'undirected' takes true or false, not '${raw || '(no value)'}'.`,
+                        span: setting.span,
+                    });
+                }
+            }
+        }
+        // 11.16.2: many-to-many states a cardinality, and an entity-level
+        // relationship states none. A many-to-many that carries its own
+        // attributes is an Edge.
+        if (entityLevel && ref.spec.operator === '<>') {
+            diagnostics.push({
+                severity: 'error',
+                code: 'entity-level-many-to-many',
+                message: "'<>' is not available on a relationship between entities: many-to-many states a cardinality, " +
+                    'which an entity-level relationship leaves unstated. Declare an Edge if the relationship carries its own attributes.',
+                span: ref.spec.span ?? ref.span,
+            });
+        }
+    };
+    const checkRefDeclaration = (ref) => {
+        checkRelationshipSettings(ref);
+        if (!isForeignMaster(ref))
+            return;
+        noteForeignMaster();
+        // 11.11: neither endpoint may be composite.
+        for (const [label, endpoint] of [
+            ['source', ref.spec.source],
+            ['target', ref.spec.target],
+        ]) {
+            if (endpoint.compositeFields && endpoint.compositeFields.length > 0) {
+                diagnostics.push({
+                    severity: 'error',
+                    code: 'foreign-master-composite',
+                    message: `A foreign master relationship takes a single attribute on each side; the ${label} endpoint is composite. ` +
+                        'Write one foreign master relationship per duplicated attribute.',
+                    span: endpoint.span,
+                });
+            }
+        }
+        // 11.11: at most one master per child attribute.
+        const child = refChildEndpoint(ref);
+        if (child) {
+            const key = pathToString(child.path);
+            const previous = claimedChildren.get(key);
+            if (previous) {
+                diagnostics.push({
+                    severity: 'error',
+                    code: 'foreign-master-duplicate-child',
+                    message: `'${key}' already has a foreign master. A copied attribute has one master, ` +
+                        'so a child attribute is the child of at most one foreign master relationship.',
+                    span: child.span,
+                });
+            }
+            else {
+                claimedChildren.set(key, child.span);
+            }
+        }
+    };
+    /* ---- inline refs on fields ---- */
+    const checkField = (field, ownerPath) => {
+        const flag = field.settings.find((s) => s.name === FOREIGN_MASTER_FLAG);
+        if (!flag)
+            return;
+        noteForeignMaster();
+        const inlineRef = field.settings.find((s) => s.value && s.value.kind === 'RefValue');
+        // 11.10.2: the flag qualifies an inline ref: and is an error without one.
+        if (!inlineRef) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'foreign-master-without-ref',
+                message: "The 'foreign_master' flag qualifies an inline 'ref:' in the same settings block; " +
+                    'this field declares no inline ref.',
+                span: flag.span,
+            });
+            return;
+        }
+        // 11.11: at most one master per child attribute. For an inline ref the
+        // child is always the field carrying the setting, whatever the operator.
+        const key = `${ownerPath}.${field.name}`;
+        const previous = claimedChildren.get(key);
+        if (previous) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'foreign-master-duplicate-child',
+                message: `'${key}' already has a foreign master. A copied attribute has one master, ` +
+                    'so a child attribute is the child of at most one foreign master relationship.',
+                span: field.span,
+            });
+        }
+        else {
+            claimedChildren.set(key, field.span);
+        }
+        // 11.11: an inline foreign master cannot be composite, because the
+        // grammar gives an inline ref a single target; nothing to check here.
+    };
+    /* ---- walk ---- */
+    const walkFields = (items, ownerPath) => {
+        for (const item of items) {
+            if (item.kind !== 'FieldDeclaration')
+                continue;
+            const field = item;
+            checkField(field, ownerPath);
+            // Descend into nested object/array bodies so a flag on a nested field
+            // is checked too. Nested field containers vary by type expression;
+            // `nestedFields` below normalizes the shapes the AST uses.
+            for (const nested of nestedFields(field)) {
+                walkFields([nested], `${ownerPath}.${field.name}`);
+            }
+        }
+    };
+    const walkEntity = (entity, containerName) => {
+        const ownerPath = containerName ? `${containerName}.${entity.name}` : entity.name;
+        walkFields(entity.body, ownerPath);
+    };
+    for (const stmt of doc.statements) {
+        switch (stmt.kind) {
+            case 'RefDeclaration':
+                checkRefDeclaration(stmt);
+                break;
+            case 'EntityDeclaration':
+                walkEntity(stmt);
+                break;
+            case 'ContainerDeclaration': {
+                // Ref declarations are top-level only (spec 11.2), so a container
+                // body holds entities, views, edges, enums and notes but no refs.
+                const container = stmt;
+                for (const item of container.body) {
+                    if (item.kind === 'EntityDeclaration')
+                        walkEntity(item, container.name);
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    // Section 4: the construct requires a document declaring 0.4 or later.
+    if ((sawForeignMaster || sawV04Setting) && !versionAtLeast(doc, '0.4')) {
+        const what = sawForeignMaster
+            ? "The 'foreign_master' relationship flag"
+            : 'Relationship roles, verbs and constraint type';
+        diagnostics.push({
+            severity: 'error',
+            code: 'construct-requires-version',
+            message: `${what} requires a document declaring 'xdbml: 0.4' or later.`,
+            span: doc.version ? doc.version.span : doc.span,
+        });
+    }
+    return diagnostics;
+}
+/* -------------------------------------------------------------------------
+ * Helpers
+ * ----------------------------------------------------------------------- */
+/**
+ * The field declarations nested inside a field's type expression, for the
+ * object and array shapes the AST produces. Returns an empty array for
+ * scalar fields and for type expressions with no inner field list.
+ */
+function nestedFields(field) {
+    const out = [];
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const rec = node;
+        if (rec.kind === 'FieldDeclaration') {
+            out.push(rec);
+            return; // walkFields recurses into this one itself
+        }
+        for (const value of Object.values(rec)) {
+            if (Array.isArray(value))
+                value.forEach(visit);
+            else if (value && typeof value === 'object')
+                visit(value);
+        }
+    };
+    visit(field.type);
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdbml/parse",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Parser for xDBML (eXtended Database Markup Language), a strict superset of DBML 3.13.6: tokenizer, parser, module resolver, and name resolver.",
   "license": "Apache-2.0",
   "author": "Hackolade",
@@ -42,6 +42,7 @@
     "node": ">=22"
   },
   "devDependencies": {
+    "@types/node": "^26.1.1",
     "typescript": "^5.7.3"
   },
   "publishConfig": {