@xdbml/parse 0.5.1 → 0.6.0

package/dist/ast.d.ts

@@ -68,7 +68,7 @@ export interface EntityDeclaration {
     span: Span;
 }
 export type EntityKeyword = 'Table' | 'Entity' | 'Collection' | 'Record';
-export type EntityBodyItem = FieldDeclaration | IndexesBlock | ChecksBlock | NoteBlock | PartialInjection | RecordsBlock;
+export type EntityBodyItem = FieldDeclaration | IndexesBlock | ChecksBlock | ConstraintsBlock | NoteBlock | PartialInjection | RecordsBlock;
 export interface FieldDeclaration {
     kind: 'FieldDeclaration';
     name: string;
@@ -328,12 +328,34 @@ export interface ChecksBlock {
 }
 export interface CheckEntry {
     kind: 'CheckEntry';
-    /** Source text inside the backticks, no surrounding backticks. */
+    /** Source text inside the delimiters, without them. */
     expression: string;
+    /**
+     * How the source wrote the expression (spec §10.5, v0.6): in backticks,
+     * or in single or triple quotes. Both mean the same check; the raw AST
+     * keeps the form. Absent on entries built by older code paths, which
+     * only ever read backticks.
+     */
+    delimiter?: 'backtick' | 'quote';
     /** Optional settings -- typically `name:` and/or `note:`. */
     settings: Setting[];
     span: Span;
 }
+export interface ConstraintsBlock {
+    kind: 'ConstraintsBlock';
+    entries: ConstraintEntry[];
+    span: Span;
+}
+export type ConstraintEntry = KeyConstraintEntry | CheckEntry;
+export interface KeyConstraintEntry {
+    kind: 'KeyConstraintEntry';
+    /** One path per key field, in key order. */
+    fields: PathSegment[][];
+    /** True when the source wrote the fields in parentheses. */
+    parenthesized: boolean;
+    settings: Setting[];
+    span: Span;
+}
 export interface TablePartialDeclaration {
     kind: 'TablePartialDeclaration';
     name: string;
@@ -500,6 +522,12 @@ export interface Setting {
     nameSource: string;
     /** Value, if any. A pure flag like `pk` has `value: null`. */
     value: SettingValue | null;
+    /**
+     * True on a setting the parser added rather than read: `not null` on a
+     * primary key field of a v0.6 document (spec §10.4). Its span is the
+     * field's span.
+     */
+    implied?: true;
     span: Span;
 }
 export type SettingValue = StringValue | NumberValue | BooleanValue | NullValue | IdentifierValue | ExpressionValue | ListValue | RefValue;

package/dist/constraints.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Constraints (spec §10, new in v0.6) and referenced keys (spec §11.17).
+ *
+ * Three jobs:
+ *
+ *   1. `bodyConstraints()` / `entityConstraints()` gather every key and
+ *      check of an entity into one list, whatever form declared it: a line
+ *      in `constraints { }` or `checks { }`, `[pk]` / `[unique]` on a
+ *      field, a `pk` entry in `indexes`, a field-level `check:`. This is
+ *      the Constraint node of spec §28.6, and what the renderer and the
+ *      playground read, so a consumer finds the primary key in one place.
+ *
+ *   2. `markPrimaryKeyNotNull()` adds an implied `not null` to each
+ *      primary key field of a v0.6 document (spec §10.4). The parser calls
+ *      it once the document is built.
+ *
+ *   3. `checkConstraints()` reports the conditions of spec §10.10 and the
+ *      referenced-key rule of spec §11.17. Conditions on constructs that
+ *      earlier versions and DBML accept are errors in a document declaring
+ *      0.6 or later and warnings otherwise, so a document stays valid under
+ *      the version it declares.
+ */
+import type { EntityBodyItem, PathSegment, Span, XDbmlDocument } from './ast.ts';
+import type { Diagnostic } from './name-resolver.ts';
+/** Where a constraint was declared. The raw AST keeps the form; this list does not. */
+export type ConstraintSource = 'constraints' | 'checks' | 'inline' | 'indexes' | 'field-check';
+export interface KeyConstraint {
+    kind: 'key';
+    keyKind: 'primary' | 'unique';
+    /** Dotted field paths, in key order. */
+    fields: string[];
+    name?: string;
+    note?: string;
+    source: ConstraintSource;
+    span: Span;
+}
+export interface CheckConstraint {
+    kind: 'check';
+    expression: string;
+    name?: string;
+    note?: string;
+    /** For a field-level `check:`, the field it sits on. */
+    field?: string;
+    source: ConstraintSource;
+    span: Span;
+}
+export type Constraint = KeyConstraint | CheckConstraint;
+type Body = ReadonlyArray<EntityBodyItem>;
+/** Dotted form of a key or index path; only field segments carry names. */
+export declare function keyPathString(path: ReadonlyArray<PathSegment>): string;
+/**
+ * The constraints one body declares itself, TablePartial injections left
+ * out. `quotedFieldChecks` reads a quoted field-level `check:` as a check
+ * (v0.6 §10.5); in earlier versions a quoted value there is a string.
+ */
+export declare function bodyConstraints(body: Body, quotedFieldChecks?: boolean): Constraint[];
+/**
+ * Every constraint of an entity (or edge, or partial): its own, plus those
+ * of the TablePartials it injects. One primary key results: the entity's
+ * own when it declares one, otherwise the last injected partial's (§10.4,
+ * following the conflict resolution of §17.1).
+ */
+export declare function entityConstraints(decl: {
+    body: Body;
+}, doc: XDbmlDocument): Constraint[];
+/** The primary key of an entity, or undefined. */
+export declare function primaryKey(decl: {
+    body: Body;
+}, doc: XDbmlDocument): KeyConstraint | undefined;
+/**
+ * Add an implied `not null` to every field of the primary key of each
+ * entity, edge and partial the document declares itself, unless the field
+ * states its nullability. `null` on a primary key field is left in place
+ * for checkConstraints to report. Keys naming a partial's field from the
+ * injecting entity are not marked: the field belongs to the partial.
+ */
+export declare function markPrimaryKeyNotNull(doc: XDbmlDocument): void;
+/** True for a target name the §11.17 rule covers. Unlisted names are not relational. */
+export declare function isRelationalTarget(name: string): boolean;
+export declare function checkConstraints(doc: XDbmlDocument): Diagnostic[];
+export {};

package/dist/constraints.js

@@ -0,0 +1,585 @@
+/**
+ * Constraints (spec §10, new in v0.6) and referenced keys (spec §11.17).
+ *
+ * Three jobs:
+ *
+ *   1. `bodyConstraints()` / `entityConstraints()` gather every key and
+ *      check of an entity into one list, whatever form declared it: a line
+ *      in `constraints { }` or `checks { }`, `[pk]` / `[unique]` on a
+ *      field, a `pk` entry in `indexes`, a field-level `check:`. This is
+ *      the Constraint node of spec §28.6, and what the renderer and the
+ *      playground read, so a consumer finds the primary key in one place.
+ *
+ *   2. `markPrimaryKeyNotNull()` adds an implied `not null` to each
+ *      primary key field of a v0.6 document (spec §10.4). The parser calls
+ *      it once the document is built.
+ *
+ *   3. `checkConstraints()` reports the conditions of spec §10.10 and the
+ *      referenced-key rule of spec §11.17. Conditions on constructs that
+ *      earlier versions and DBML accept are errors in a document declaring
+ *      0.6 or later and warnings otherwise, so a document stays valid under
+ *      the version it declares.
+ */
+import { hasForeignMasterFlag, isForeignMaster, versionAtLeast } from "./relationships.js";
+const hasFlag = (settings, ...names) => settings.some((s) => names.includes(s.name) && s.value === null);
+const stringSetting = (settings, name) => {
+    const s = settings.find((x) => x.name === name);
+    return s?.value?.kind === 'StringValue' ? s.value.value : undefined;
+};
+const isPk = (settings) => hasFlag(settings, 'pk', 'primary key');
+/** Dotted form of a key or index path; only field segments carry names. */
+export function keyPathString(path) {
+    return path.map((seg) => (seg.kind === 'PathField' ? seg.name : '[]')).join('.');
+}
+const checkFromEntry = (e, source) => ({
+    kind: 'check',
+    expression: e.expression,
+    name: stringSetting(e.settings, 'name'),
+    note: stringSetting(e.settings, 'note'),
+    source,
+    span: e.span,
+});
+/**
+ * The constraints one body declares itself, TablePartial injections left
+ * out. `quotedFieldChecks` reads a quoted field-level `check:` as a check
+ * (v0.6 §10.5); in earlier versions a quoted value there is a string.
+ */
+export function bodyConstraints(body, quotedFieldChecks = true) {
+    const out = [];
+    const inlinePk = [];
+    for (const item of body) {
+        if (item.kind === 'FieldDeclaration') {
+            if (isPk(item.settings))
+                inlinePk.push(item);
+            if (hasFlag(item.settings, 'unique')) {
+                out.push({ kind: 'key', keyKind: 'unique', fields: [item.name], source: 'inline', span: item.span });
+            }
+            for (const s of item.settings) {
+                if (s.name !== 'check' || !s.value)
+                    continue;
+                const expression = checkExpression(s.value, quotedFieldChecks);
+                if (expression !== undefined) {
+                    out.push({ kind: 'check', expression, field: item.name, source: 'field-check', span: s.span });
+                }
+            }
+        }
+        else if (item.kind === 'ConstraintsBlock') {
+            for (const e of item.entries) {
+                if (e.kind === 'CheckEntry') {
+                    out.push(checkFromEntry(e, 'constraints'));
+                    continue;
+                }
+                const pk = isPk(e.settings);
+                const unique = hasFlag(e.settings, 'unique');
+                if (pk === unique)
+                    continue; // neither or both: reported by checkConstraints
+                out.push({
+                    kind: 'key',
+                    keyKind: pk ? 'primary' : 'unique',
+                    fields: e.fields.map(keyPathString),
+                    name: stringSetting(e.settings, 'name'),
+                    note: stringSetting(e.settings, 'note'),
+                    source: 'constraints',
+                    span: e.span,
+                });
+            }
+        }
+        else if (item.kind === 'ChecksBlock') {
+            for (const e of item.entries)
+                out.push(checkFromEntry(e, 'checks'));
+        }
+        else if (item.kind === 'IndexesBlock') {
+            for (const e of item.entries) {
+                if (!isPk(e.settings))
+                    continue;
+                const fields = e.components.flatMap((c) => (c.kind === 'IndexPathComponent' ? [keyPathString(c.path)] : []));
+                out.push({
+                    kind: 'key',
+                    keyKind: 'primary',
+                    fields,
+                    name: stringSetting(e.settings, 'name'),
+                    note: stringSetting(e.settings, 'note'),
+                    source: 'indexes',
+                    span: e.span,
+                });
+            }
+        }
+    }
+    if (inlinePk.length > 0) {
+        // Several inline [pk] fields form one composite key in field order (§10.3).
+        out.unshift({
+            kind: 'key',
+            keyKind: 'primary',
+            fields: inlinePk.map((f) => f.name),
+            source: 'inline',
+            span: inlinePk[0].span,
+        });
+    }
+    return out;
+}
+function checkExpression(value, quoted) {
+    if (value.kind === 'ExpressionValue')
+        return value.expression;
+    if (quoted && value.kind === 'StringValue')
+        return value.value;
+    return undefined;
+}
+/**
+ * Every constraint of an entity (or edge, or partial): its own, plus those
+ * of the TablePartials it injects. One primary key results: the entity's
+ * own when it declares one, otherwise the last injected partial's (§10.4,
+ * following the conflict resolution of §17.1).
+ */
+export function entityConstraints(decl, doc) {
+    const quoted = versionAtLeast(doc, '0.6');
+    const partials = partialIndex(doc);
+    const own = bodyConstraints(decl.body, quoted);
+    const injected = [];
+    let partialPk;
+    for (const item of decl.body) {
+        if (item.kind !== 'PartialInjection')
+            continue;
+        const p = partials.get(item.partialName);
+        if (!p)
+            continue;
+        for (const c of bodyConstraints(p.body, quoted)) {
+            if (c.kind === 'key' && c.keyKind === 'primary')
+                partialPk = c;
+            else
+                injected.push(c);
+        }
+    }
+    const ownPk = own.find((c) => c.kind === 'key' && c.keyKind === 'primary');
+    const out = [...own, ...injected];
+    if (!ownPk && partialPk)
+        out.unshift(partialPk);
+    return out;
+}
+/** The primary key of an entity, or undefined. */
+export function primaryKey(decl, doc) {
+    return entityConstraints(decl, doc).find((c) => c.kind === 'key' && c.keyKind === 'primary');
+}
+function bodies(doc) {
+    const out = [];
+    for (const s of doc.statements) {
+        if (s.kind === 'EntityDeclaration' || s.kind === 'EdgeDeclaration' || s.kind === 'TablePartialDeclaration') {
+            out.push({ decl: s });
+        }
+        else if (s.kind === 'ContainerDeclaration') {
+            for (const b of s.body) {
+                if (b.kind === 'EntityDeclaration' || b.kind === 'EdgeDeclaration')
+                    out.push({ decl: b, container: s });
+            }
+        }
+    }
+    return out;
+}
+function partialIndex(doc) {
+    const m = new Map();
+    for (const s of doc.statements)
+        if (s.kind === 'TablePartialDeclaration')
+            m.set(s.name, s);
+    return m;
+}
+function typeIndex(doc) {
+    const m = new Map();
+    for (const s of doc.statements)
+        if (s.kind === 'TypeDeclaration')
+            m.set(s.name, s);
+    return m;
+}
+/** Top-level fields of a body, including those of injected partials. */
+function topFields(body, partials, seen = new Set()) {
+    const out = [];
+    for (const item of body) {
+        if (item.kind === 'FieldDeclaration')
+            out.push(item);
+        else if (item.kind === 'PartialInjection' && !seen.has(item.partialName)) {
+            const p = partials.get(item.partialName);
+            if (p) {
+                seen.add(item.partialName);
+                out.push(...topFields(p.body, partials, seen));
+            }
+        }
+    }
+    return out;
+}
+/** The fields of an object-shaped type, or undefined for any other type. */
+function objectFields(t, types) {
+    if (t.kind === 'ObjectType')
+        return t.fields;
+    if (t.kind === 'ScalarType' || t.kind === 'NamedTypeReference') {
+        const td = types.get(t.name);
+        if (td && !td.scalarBase)
+            return td.body;
+    }
+    return undefined;
+}
+const COLLECTION_KINDS = new Set(['ArrayType', 'TupleType', 'MapType', 'SetType']);
+/**
+ * Follow a key path through object fields (§10.2). Reports the first field
+ * that is missing, or the first step through an array, tuple or map.
+ */
+function walkKeyPath(path, fields, types) {
+    let current = fields;
+    const walked = [];
+    for (let i = 0; i < path.length; i++) {
+        const seg = path[i];
+        if (seg.kind !== 'PathField')
+            return { kind: 'collection', at: walked.join('.') || '(start)' };
+        walked.push(seg.name);
+        const f = current.find((x) => x.name === seg.name);
+        if (!f)
+            return { kind: 'missing', at: walked.join('.') };
+        if (i === path.length - 1)
+            return undefined;
+        if (COLLECTION_KINDS.has(f.type.kind))
+            return { kind: 'collection', at: walked.join('.') };
+        const next = objectFields(f.type, types);
+        if (!next)
+            return { kind: 'missing', at: `${walked.join('.')}.${path[i + 1].name ?? ''}` };
+        current = next.filter((x) => x.kind === 'FieldDeclaration');
+    }
+    return undefined;
+}
+/* -------------------------------------------------------------------------
+ * Primary key fields are not null (§10.4)
+ * ----------------------------------------------------------------------- */
+const NULLABILITY = ['null', 'not null'];
+/**
+ * Add an implied `not null` to every field of the primary key of each
+ * entity, edge and partial the document declares itself, unless the field
+ * states its nullability. `null` on a primary key field is left in place
+ * for checkConstraints to report. Keys naming a partial's field from the
+ * injecting entity are not marked: the field belongs to the partial.
+ */
+export function markPrimaryKeyNotNull(doc) {
+    if (!versionAtLeast(doc, '0.6'))
+        return;
+    for (const { decl } of bodies(doc)) {
+        const pk = bodyConstraints(decl.body).find((c) => c.kind === 'key' && c.keyKind === 'primary');
+        if (!pk)
+            continue;
+        for (const dotted of pk.fields) {
+            const field = findField(decl.body, dotted.split('.'));
+            if (!field || field.settings.some((s) => NULLABILITY.includes(s.name)))
+                continue;
+            field.settings.push({ kind: 'Setting', name: 'not null', nameSource: 'not null', value: null, implied: true, span: field.span });
+        }
+    }
+}
+function findField(body, names) {
+    let current = body;
+    let found;
+    for (const n of names) {
+        found = current.find((x) => x.kind === 'FieldDeclaration' && x.name === n);
+        if (!found)
+            return undefined;
+        current = found.type.kind === 'ObjectType' ? found.type.fields : [];
+    }
+    return found;
+}
+/* -------------------------------------------------------------------------
+ * Targets (§5.1)
+ * ----------------------------------------------------------------------- */
+/** Canonical relational targets and their aliases, lower-cased (§5.1). */
+const RELATIONAL_TARGETS = new Set([
+    'oracle',
+    'postgresql', 'postgres', 'pg',
+    'sql server', 'mssql', 'microsoft sql server', 't-sql',
+    'mysql', 'mariadb', 'sqlite',
+    'db2', 'ibm db2', 'db2 luw', 'db2 for z/os', 'db2 z/os',
+    'teradata', 'snowflake', 'databricks',
+    'bigquery', 'google bigquery',
+    'redshift', 'amazon redshift',
+    'synapse analytics', 'azure synapse',
+    'timescaledb',
+]);
+/** True for a target name the §11.17 rule covers. Unlisted names are not relational. */
+export function isRelationalTarget(name) {
+    return RELATIONAL_TARGETS.has(name.trim().toLowerCase());
+}
+function settingValues(v) {
+    if (!v)
+        return [];
+    if (v.kind === 'ListValue')
+        return v.items.flatMap(settingValues);
+    if (v.kind === 'StringValue')
+        return [v.value];
+    if (v.kind === 'IdentifierValue')
+        return [v.value];
+    return [];
+}
+/** The document-wide target when the Project declares exactly one. */
+function projectTarget(doc) {
+    for (const s of doc.statements) {
+        if (s.kind !== 'ProjectDeclaration')
+            continue;
+        for (const item of s.body) {
+            if (item.kind === 'Setting' && (item.name === 'targets' || item.name === 'database_type')) {
+                const values = settingValues(item.value).filter((x) => x !== '');
+                return values.length === 1 ? values[0] : undefined;
+            }
+        }
+    }
+    return undefined;
+}
+function effectiveTarget(p, project) {
+    const own = p.container?.settings.find((s) => s.name === 'target');
+    const values = settingValues(own?.value ?? null).filter((x) => x !== '');
+    return values[0] ?? project;
+}
+/* -------------------------------------------------------------------------
+ * Checks (§10.10, §11.17)
+ * ----------------------------------------------------------------------- */
+export function checkConstraints(doc) {
+    const diagnostics = [];
+    const v06 = versionAtLeast(doc, '0.6');
+    // Conditions on constructs that earlier versions accept (§10.10).
+    const olderSeverity = v06 ? 'error' : 'warning';
+    const partials = partialIndex(doc);
+    const types = typeIndex(doc);
+    const versionSpan = (fallback) => (doc.version ? doc.version.span : fallback);
+    for (const { decl } of bodies(doc)) {
+        const fields = topFields(decl.body, partials);
+        const blocks = decl.body.filter((b) => b.kind === 'ConstraintsBlock');
+        for (const [i, block] of blocks.entries()) {
+            if (block.kind !== 'ConstraintsBlock')
+                continue;
+            if (!v06) {
+                diagnostics.push({
+                    severity: 'error',
+                    code: 'construct-requires-version',
+                    message: "The constraints block requires a document declaring 'xdbml: 0.6' or later.",
+                    span: versionSpan(block.span),
+                });
+            }
+            if (i > 0) {
+                diagnostics.push({
+                    severity: 'error',
+                    code: 'duplicate-constraints-block',
+                    message: `'${decl.name}' declares a second constraints block; one body holds at most one.`,
+                    span: block.span,
+                });
+            }
+            for (const e of block.entries) {
+                if (e.kind === 'CheckEntry')
+                    continue;
+                const pk = isPk(e.settings);
+                const unique = hasFlag(e.settings, 'unique');
+                if (pk === unique) {
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'invalid-key-flags',
+                        message: pk
+                            ? 'A key line carries both pk and unique; it takes exactly one.'
+                            : 'A key line needs pk or unique.',
+                        span: e.span,
+                    });
+                }
+                for (const path of e.fields) {
+                    const problem = walkKeyPath(path, fields, types);
+                    if (problem?.kind === 'missing') {
+                        diagnostics.push({
+                            severity: 'error',
+                            code: 'unresolved-key-field',
+                            message: `Key field '${problem.at}' is not declared in '${decl.name}'.`,
+                            span: e.span,
+                        });
+                    }
+                    else if (problem?.kind === 'collection') {
+                        diagnostics.push({
+                            severity: 'error',
+                            code: 'key-path-crosses-collection',
+                            message: `Key path '${keyPathString(path)}' crosses an array, tuple or map at '${problem.at}'; a key path steps through object fields only.`,
+                            span: e.span,
+                        });
+                    }
+                }
+            }
+        }
+        // Quoted checks are v0.6 syntax (§10.5).
+        if (!v06) {
+            for (const item of decl.body) {
+                if (item.kind !== 'ChecksBlock' && item.kind !== 'ConstraintsBlock')
+                    continue;
+                for (const e of item.entries) {
+                    if (e.kind === 'CheckEntry' && e.delimiter === 'quote') {
+                        diagnostics.push({
+                            severity: 'error',
+                            code: 'construct-requires-version',
+                            message: "A check expression in quotes requires a document declaring 'xdbml: 0.6' or later; use backticks.",
+                            span: e.span,
+                        });
+                    }
+                }
+            }
+        }
+        // Index fields must be declared (§9, §10.10). Only the first segment is
+        // checked: deeper segments may iterate arrays implicitly (§9.3).
+        for (const item of decl.body) {
+            if (item.kind !== 'IndexesBlock')
+                continue;
+            for (const e of item.entries) {
+                for (const c of e.components) {
+                    if (c.kind !== 'IndexPathComponent')
+                        continue;
+                    const first = c.path[0];
+                    if (first?.kind === 'PathField' && !fields.some((f) => f.name === first.name)) {
+                        diagnostics.push({
+                            severity: olderSeverity,
+                            code: 'unresolved-index-field',
+                            message: `Index field '${first.name}' is not declared in '${decl.name}'.`,
+                            span: c.span,
+                        });
+                    }
+                }
+            }
+        }
+        // One primary key, declared in one place (§10.4). Inline [pk] fields
+        // count as one declaration.
+        const own = bodyConstraints(decl.body, v06);
+        const pks = own.filter((c) => c.kind === 'key' && c.keyKind === 'primary');
+        for (const extra of pks.slice(1)) {
+            diagnostics.push({
+                severity: olderSeverity,
+                code: 'duplicate-primary-key',
+                message: `'${decl.name}' declares a second primary key; an entity has one, declared in one place.`,
+                span: extra.span,
+            });
+        }
+        // `null` on a primary key field (§10.4).
+        for (const pk of pks.slice(0, 1)) {
+            for (const dotted of pk.fields) {
+                const f = findField(decl.body, dotted.split('.'));
+                const nullSetting = f?.settings.find((s) => s.name === 'null' && !s.implied);
+                if (nullSetting) {
+                    diagnostics.push({
+                        severity: olderSeverity,
+                        code: 'null-in-primary-key',
+                        message: `'${decl.name}.${dotted}' is part of the primary key and cannot be null.`,
+                        span: nullSetting.span,
+                    });
+                }
+            }
+        }
+    }
+    diagnostics.push(...checkReferencedKeys(doc, olderSeverity));
+    return diagnostics;
+}
+function entityIndex(doc) {
+    const m = new Map();
+    const bare = new Map();
+    for (const p of bodies(doc)) {
+        if (p.decl.kind !== 'EntityDeclaration')
+            continue;
+        const e = { placed: p, decl: p.decl };
+        const q = p.container ? `${p.container.name}.${p.decl.name}` : p.decl.name;
+        m.set(q, e);
+        const b = p.decl.name.split('.').pop() ?? p.decl.name;
+        bare.set(b, [...(bare.get(b) ?? []), e]);
+    }
+    for (const [b, list] of bare)
+        if (list.length === 1 && !m.has(b))
+            m.set(b, list[0]);
+    return m;
+}
+/** Longest prefix naming an entity; the rest is a field path. Entity-level ends return undefined fields. */
+function resolveEnd(ep, index) {
+    const names = ep.path.map((s) => (s.kind === 'PathField' ? s.name : '[]'));
+    for (let i = names.length; i >= 1; i--) {
+        const entity = index.get(names.slice(0, i).join('.'));
+        if (!entity)
+            continue;
+        if (ep.compositeFields && ep.compositeFields.length > 0)
+            return { entity, fields: [...ep.compositeFields] };
+        const rest = names.slice(i).join('.');
+        return rest ? { entity, fields: [rest] } : 'entity-level';
+    }
+    return undefined;
+}
+const sameSet = (a, b) => a.length === b.length && a.every((x) => b.includes(x));
+/** Keys a referenced end may match: keys, plus DBML unique indexes (§11.17). */
+function referenceableKeys(decl, doc) {
+    const keys = entityConstraints(decl, doc)
+        .filter((c) => c.kind === 'key')
+        .map((k) => k.fields);
+    for (const item of decl.body) {
+        if (item.kind !== 'IndexesBlock')
+            continue;
+        for (const e of item.entries) {
+            if (isPk(e.settings) || !hasFlag(e.settings, 'unique'))
+                continue;
+            keys.push(e.components.flatMap((c) => (c.kind === 'IndexPathComponent' ? [keyPathString(c.path)] : [])));
+        }
+    }
+    return keys;
+}
+function checkReferencedKeys(doc, severity) {
+    const diagnostics = [];
+    const index = entityIndex(doc);
+    const project = projectTarget(doc);
+    const exemptTarget = (e) => {
+        const t = effectiveTarget(e.placed, project);
+        return t !== undefined && !isRelationalTarget(t);
+    };
+    const check = (source, operator, target, span) => {
+        if (operator === '<>')
+            return;
+        const s = resolveEnd(source, index);
+        const t = resolveEnd(target, index);
+        if (!s || !t || s === 'entity-level' || t === 'entity-level')
+            return;
+        if (exemptTarget(s.entity) || exemptTarget(t.entity))
+            return;
+        const sides = operator === '>' ? [t] : operator === '<' ? [s] : [s, t];
+        const withKeys = sides
+            .map((side) => ({ side, keys: referenceableKeys(side.entity.decl, doc) }))
+            .filter((x) => x.keys.length > 0);
+        if (withKeys.length === 0)
+            return; // no key declared: a tool MAY promote (§11.17)
+        if (withKeys.some((x) => x.keys.some((k) => sameSet(k, x.side.fields))))
+            return;
+        const first = withKeys[0];
+        const pk = primaryKey(first.side.entity.decl, doc);
+        const where = `${first.side.entity.decl.name}.${first.side.fields.length > 1 ? `(${first.side.fields.join(', ')})` : first.side.fields[0]}`;
+        diagnostics.push({
+            severity,
+            code: 'ref-target-not-key',
+            message: `Relationship references '${where}', which is not the primary key or a unique key of '${first.side.entity.decl.name}'` +
+                (pk ? ` (primary key: ${pk.fields.join(', ')}).` : '.') +
+                ' Declare those fields unique, or reference a key.',
+            span,
+        });
+    };
+    const visitRef = (ref) => {
+        if (isForeignMaster(ref))
+            return;
+        check(ref.spec.source, ref.spec.operator, ref.spec.target, ref.span);
+    };
+    for (const s of doc.statements) {
+        if (s.kind === 'RefDeclaration')
+            visitRef(s);
+    }
+    // Inline refs on top-level fields.
+    for (const p of bodies(doc)) {
+        if (p.decl.kind !== 'EntityDeclaration')
+            continue;
+        const owner = p.container ? `${p.container.name}.${p.decl.name}` : p.decl.name;
+        for (const item of p.decl.body) {
+            if (item.kind !== 'FieldDeclaration' || hasForeignMasterFlag(item.settings))
+                continue;
+            for (const st of item.settings) {
+                if (st.name !== 'ref' || st.value?.kind !== 'RefValue')
+                    continue;
+                const source = {
+                    kind: 'RefEndpoint',
+                    path: [...owner.split('.'), item.name].map((name) => ({ kind: 'PathField', name, span: item.span })),
+                    span: item.span,
+                };
+                check(source, st.value.operator, st.value.target, st.span);
+            }
+        }
+    }
+    return diagnostics;
+}

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 { bodyConstraints, checkConstraints, entityConstraints, isRelationalTarget, keyPathString, markPrimaryKeyNotNull, primaryKey, } from './constraints.ts';
+export type { CheckConstraint, Constraint, ConstraintSource, KeyConstraint } from './constraints.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 { SUPERTYPE_GROUP_VALUES, canonicalSupertypeGroupValue, checkSupertypeGroups, resolveSupertypeGroups, subtypeStrategy, supertypeChains, supertypeGroupSettings, } from './supertypes.ts';

package/dist/index.js

@@ -30,6 +30,7 @@ export { parse, Parser, ParseError, SUPPORTED_XDBML_VERSION, compareVersions } f
 export { flatten } from "./module-resolver.js";
 export { classifyModuleSource, isUrlKey, ModuleSourceError, } from "./module-resolver.js";
 export { resolveNames, SymbolTable } from "./name-resolver.js";
+export { bodyConstraints, checkConstraints, entityConstraints, isRelationalTarget, keyPathString, markPrimaryKeyNotNull, primaryKey, } from "./constraints.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 { SUPERTYPE_GROUP_VALUES, canonicalSupertypeGroupValue, checkSupertypeGroups, resolveSupertypeGroups, subtypeStrategy, supertypeChains, supertypeGroupSettings, } from "./supertypes.js";
 export { xdbmlLanguageConfig, xdbmlMonarchTokensProvider, } from "./monarch.js";

package/dist/keywords.d.ts

@@ -40,7 +40,7 @@ export declare const SCALAR_TYPES: readonly ["tinyint", "smallint", "mediumint",
 export declare const BSON_TYPES: readonly ["objectid", "decimal128", "bindata", "minkey", "maxkey", "symbol", "regex", "long", "double"];
 export declare const TARGET_NATIVE_TYPES: readonly ["number", "binary_float", "binary_double", "clob", "nclob", "bfile", "raw", "rowid", "urowid", "xmltype", "sdo_geometry", "interval", "serial", "smallserial", "bigserial", "serial2", "serial4", "serial8", "int2", "int4", "int8", "float4", "float8", "bytea", "citext", "inet", "cidr", "macaddr", "macaddr8", "tsvector", "tsquery", "hstore", "jsonpath", "timetz", "varbit", "int4range", "int8range", "numrange", "tsrange", "tstzrange", "daterange", "uniqueidentifier", "datetimeoffset", "smalldatetime", "rowversion", "hierarchyid", "sql_variant", "timestamp_ntz", "timestamp_ltz", "timestamp_tz", "vector", "float64", "bignumeric", "bigdecimal", "bytes", "geometry", "geography", "ascii", "varint", "timeuuid", "uint32", "uint64", "sint32", "sint64", "fixed32", "fixed64", "sfixed32", "sfixed64", "uint8", "uint16", "int16", "float32"];
 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", "supertype", "completeness", "exclusivity", "strategy", "merge", "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_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", "supertype", "completeness", "exclusivity", "strategy", "merge", "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", "constraints", "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

@@ -286,6 +286,7 @@ export const SETTING_KEYS = [
     // Block keywords (entity-body or top-level)
     'indexes',
     'checks', // v0.2 §10: entity-level checks block
+    'constraints', // v0.6 §10: keys and checks block
     // Container settings
     'replication',
     'location',

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' | 'possible-type-typo' | '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' | 'missing-supertype' | 'unresolved-supertype-group-member' | 'invalid-supertype-group-value' | 'duplicate-subtype' | 'supertype-is-subtype' | 'subtype-in-multiple-groups' | 'supertype-cycle' | 'supertype-attribute-redeclared' | 'discriminator-on-overlapping-group' | 'merge-without-roll-up' | 'empty-supertype-group';
+export type DiagnosticCode = 'duplicate-declaration' | 'unresolved-type' | 'possible-type-typo' | 'unresolved-key-field' | 'unresolved-index-field' | 'key-path-crosses-collection' | 'invalid-key-flags' | 'duplicate-primary-key' | 'null-in-primary-key' | 'duplicate-constraints-block' | 'ref-target-not-key' | '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' | 'missing-supertype' | 'unresolved-supertype-group-member' | 'invalid-supertype-group-value' | 'duplicate-subtype' | 'supertype-is-subtype' | 'subtype-in-multiple-groups' | 'supertype-cycle' | 'supertype-attribute-redeclared' | 'discriminator-on-overlapping-group' | 'merge-without-roll-up' | 'empty-supertype-group';
 /**
  * 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

@@ -42,6 +42,7 @@ import { SCALAR_TYPES, BSON_TYPES } from "./keywords.js";
 import { flatten } from "./module-resolver.js";
 import { checkRelationships } from "./relationships.js";
 import { checkSupertypeGroups } from "./supertypes.js";
+import { checkConstraints } from "./constraints.js";
 /**
  * Read-only handle on the collected symbol table.
  *
@@ -228,6 +229,8 @@ export function resolveNames(doc) {
     diagnostics.push(...checkRelationships(flat));
     // Pass 4: supertype group rules (spec 12.8).
     diagnostics.push(...checkSupertypeGroups(flat));
+    // Pass 5: constraints and referenced keys (spec §10.10, §11.17).
+    diagnostics.push(...checkConstraints(flat));
     return { diagnostics, symbols };
 }
 /* -------------------------------------------------------------------------

package/dist/parser.d.ts

@@ -26,7 +26,7 @@ export declare class ParseError extends Error {
  * declaring a later version is refused (spec 4.1) rather than parsed with
  * semantics it does not have.
  */
-export declare const SUPPORTED_XDBML_VERSION = "0.5";
+export declare const SUPPORTED_XDBML_VERSION = "0.6";
 /** Compare dotted version strings numerically: -1, 0 or 1. */
 export declare function compareVersions(a: string, b: string): number;
 export declare class Parser {
@@ -326,6 +326,8 @@ export declare class Parser {
     private parseIndexComponent;
     private parseChecks;
     private parseCheckEntry;
+    private parseConstraints;
+    private parseKeyConstraintEntry;
     private maybeSettingsBlock;
     /**
      * A single setting. Forms:

package/dist/parser.js

@@ -9,6 +9,7 @@
  * semantic-analysis pass. The grammar test cases the parser passes are
  * the official xDBML example files in /examples.
  */
+import { markPrimaryKeyNotNull } from "./constraints.js";
 import { TokenKind, tokenize, } from "./lexer.js";
 import { resolveImport, classifyModuleSource, ModuleSourceError } from "./module-resolver.js";
 export class ParseError extends Error {
@@ -31,7 +32,7 @@ export class ParseError extends Error {
  * 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';
+export const SUPPORTED_XDBML_VERSION = '0.6';
 /** Compare dotted version strings numerically: -1, 0 or 1. */
 export function compareVersions(a, b) {
     const pa = a.split('.').map((n) => Number(n) || 0);
@@ -191,13 +192,16 @@ export class Parser {
         while (!this.check(TokenKind.EOF)) {
             statements.push(this.parseTopLevelStatement());
         }
-        return {
+        const doc = {
             kind: 'XDbmlDocument',
             version,
             experimental,
             statements,
             span: this.spanFrom(start),
         };
+        // v0.6 §10.4: primary key fields are not null in the AST.
+        markPrimaryKeyNotNull(doc);
+        return doc;
     }
     /* ----- version & experimental ----- */
     parseVersionDeclaration() {
@@ -487,6 +491,11 @@ export class Parser {
             else if (k === 'checks') {
                 body.push(this.parseChecks());
             }
+            else if (k === 'constraints' && this.peek(1).kind === TokenKind.LBrace) {
+                // v0.6 §10.1: a keyword only when `{` follows, so a field may keep
+                // the name `constraints`.
+                body.push(this.parseConstraints());
+            }
             else if (k === 'records') {
                 body.push(this.parseRecordsBlock());
             }
@@ -1932,17 +1941,71 @@ export class Parser {
     parseCheckEntry() {
         const start = this.peek().start;
         const exprTok = this.peek();
-        if (exprTok.kind !== TokenKind.ExpressionLiteral) {
-            throw new ParseError(`Expected backtick-wrapped check expression, got ${exprTok.kind} ${JSON.stringify(exprTok.text)}`, exprTok.start);
+        // v0.6 §10.5: single (or triple) quotes are the standard form and
+        // backticks an alias. The resolver rejects the quoted form in documents
+        // declaring an earlier version.
+        const quoted = exprTok.kind === TokenKind.StringLiteral || exprTok.kind === TokenKind.MultilineString;
+        if (exprTok.kind !== TokenKind.ExpressionLiteral && !quoted) {
+            throw new ParseError(`Expected a check expression in quotes or backticks, got ${exprTok.kind} ${JSON.stringify(exprTok.text)}`, exprTok.start);
         }
         this.advance();
-        // The expression is opaque to xDBML per spec §10.3. The value field of
-        // an ExpressionLiteral token already has the surrounding backticks stripped.
+        // The expression is opaque to xDBML (spec §10.5). The token value
+        // already has the delimiters stripped.
         const expression = exprTok.value ?? '';
         const settings = this.maybeSettingsBlock();
         return {
             kind: 'CheckEntry',
             expression,
+            delimiter: quoted ? 'quote' : 'backtick',
+            settings,
+            span: this.spanFrom(start),
+        };
+    }
+    /* ----- constraints block (v0.6 §10) ----- */
+    parseConstraints() {
+        const start = this.peek().start;
+        this.advance(); // constraints
+        this.expect(TokenKind.LBrace, "Expected '{' after constraints");
+        const entries = [];
+        while (!this.check(TokenKind.RBrace) && !this.check(TokenKind.EOF)) {
+            const t = this.peek();
+            if (t.kind === TokenKind.StringLiteral ||
+                t.kind === TokenKind.MultilineString ||
+                t.kind === TokenKind.ExpressionLiteral) {
+                entries.push(this.parseCheckEntry());
+            }
+            else {
+                entries.push(this.parseKeyConstraintEntry());
+            }
+        }
+        this.expect(TokenKind.RBrace, "Expected '}' closing constraints");
+        return {
+            kind: 'ConstraintsBlock',
+            entries,
+            span: this.spanFrom(start),
+        };
+    }
+    parseKeyConstraintEntry() {
+        const start = this.peek().start;
+        const fields = [];
+        let parenthesized = false;
+        if (this.check(TokenKind.LParen)) {
+            parenthesized = true;
+            this.advance(); // (
+            fields.push(this.parsePathSegments());
+            while (this.match(TokenKind.Comma)) {
+                fields.push(this.parsePathSegments());
+            }
+            this.expect(TokenKind.RParen, "Expected ')' closing the fields of a key");
+        }
+        else {
+            fields.push(this.parsePathSegments());
+        }
+        const settings = this.maybeSettingsBlock();
+        return {
+            kind: 'KeyConstraintEntry',
+            fields,
+            parenthesized,
             settings,
             span: this.spanFrom(start),
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdbml/parse",
-  "version": "0.5.1",
+  "version": "0.6.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",