@peter.prib/renderengine 0.14.0 → 0.15.0

package/src/charting/datamodel/ArchimateDataLink.js

@@ -0,0 +1,70 @@
+/**
+ * ArchimateDataLink — connects data model concepts to ArchiMate model elements.
+ * Aligns with DMBOK2's Data Architecture and TOGAF/ArchiMate standards:
+ * - Conceptual concepts realise ArchiMate Business Objects (Business Layer)
+ * - Logical and physical entities realise ArchiMate Data Objects (Application Layer) or Artifacts (Technology Layer)
+ * - Service domains link to ArchiMate Business Services or Application Services
+ */
+export class ArchimateDataLink {
+    /**
+     * @param {Object} spec
+     * @param {string} spec.dataModelEntityId - Entity id in DataModel
+     * @param {'conceptual'|'logical'|'physical'} [spec.level='conceptual']
+     * @param {string} spec.archimateElementId - ArchiMate element id
+     * @param {string} [spec.archimateType='business-object'] - 'business-object', 'data-object', 'artifact', etc.
+     * @param {string} [spec.archimateModelId]
+     * @param {string} [spec.notes]
+     */
+    constructor({
+        dataModelEntityId,
+        level = 'conceptual',
+        archimateElementId,
+        archimateType = 'business-object',
+        archimateModelId = null,
+        notes = '',
+    } = {}) {
+        if (!dataModelEntityId || !archimateElementId) {
+            throw new TypeError('ArchimateDataLink requires dataModelEntityId and archimateElementId');
+        }
+        this.dataModelEntityId = dataModelEntityId;
+        this.level = level;
+        this.archimateElementId = archimateElementId;
+        this.archimateType = archimateType;
+        this.archimateModelId = archimateModelId;
+        this.notes = notes;
+    }
+
+    /**
+     * Validates whether the ArchiMate type aligns with DMBOK2 layer expectations.
+     * Conceptual entities should realise Business Objects;
+     * Logical and physical entities should realise Data Objects or Artifacts.
+     * @returns {{ valid: boolean, recommendation?: string }}
+     */
+    validateLayerAlignment() {
+        if (this.level === 'conceptual' && this.archimateType !== 'business-object') {
+            return {
+                valid: false,
+                recommendation: 'Conceptual data model concepts should realise ArchiMate Business Objects in the Business layer.',
+            };
+        }
+        if ((this.level === 'logical' || this.level === 'physical') &&
+            !['data-object', 'artifact'].includes(this.archimateType)) {
+            return {
+                valid: false,
+                recommendation: `${this.level} data entities should realise ArchiMate Data Objects (Application layer) or Artifacts (Technology layer).`,
+            };
+        }
+        return { valid: true };
+    }
+
+    toJSON() {
+        return {
+            dataModelEntityId: this.dataModelEntityId,
+            level: this.level,
+            archimateElementId: this.archimateElementId,
+            archimateType: this.archimateType,
+            archimateModelId: this.archimateModelId,
+            notes: this.notes,
+        };
+    }
+}

package/src/charting/datamodel/DataLineage.js

@@ -0,0 +1,150 @@
+/**
+ * DataLineage — end-to-end data lineage and impact analysis across models and levels.
+ * Traces source-to-target provenance forward and backward (DMBOK2 Integration & Interoperability).
+ */
+export class DataLineage {
+    /**
+     * @param {Object} [options]
+     * @param {Array<ModelMapping>} [options.modelMappings]
+     * @param {Array<LevelMapping>} [options.levelMappings]
+     */
+    constructor({ modelMappings = [], levelMappings = [] } = {}) {
+        this.modelMappings = [...modelMappings];
+        this.levelMappings = [...levelMappings];
+    }
+
+    addModelMapping(mapping) {
+        this.modelMappings.push(mapping);
+    }
+
+    /**
+     * Trace upstream lineage of a target attribute back to its source attributes.
+     * Traverses multi-hop transformations across models.
+     * @param {string} targetEntityId
+     * @param {string} [targetAttribute]
+     * @returns {Array<Object>} Chain of lineage hops with transformations
+     */
+    traceLineage(targetEntityId, targetAttribute = null) {
+        const chain = [];
+        const visited = new Set();
+        const queue = [{ entity: targetEntityId, attribute: targetAttribute, depth: 0 }];
+
+        while (queue.length) {
+            const current = queue.shift();
+            const key = `${current.entity}:${current.attribute || '*'}`;
+            if (visited.has(key)) continue;
+            visited.add(key);
+
+            for (const map of this.modelMappings) {
+                for (const attrMap of map.attributeMappings) {
+                    if (attrMap.targetEntityId === current.entity &&
+                        (!current.attribute || attrMap.targetAttribute === current.attribute)) {
+                        const step = {
+                            sourceModel: map.sourceModel,
+                            targetModel: map.targetModel,
+                            sourceEntityId: attrMap.sourceEntityId,
+                            sourceAttribute: attrMap.sourceAttribute,
+                            targetEntityId: attrMap.targetEntityId,
+                            targetAttribute: attrMap.targetAttribute,
+                            transformation: attrMap.transformation,
+                            rule: attrMap.rule,
+                            depth: current.depth + 1,
+                        };
+                        chain.push(step);
+                        queue.push({
+                            entity: attrMap.sourceEntityId,
+                            attribute: attrMap.sourceAttribute,
+                            depth: current.depth + 1,
+                        });
+                    }
+                }
+            }
+        }
+        return chain;
+    }
+
+    /**
+     * Trace downstream impact of changing a source attribute forward to targets.
+     * Traverses multi-hop dependencies across models.
+     * @param {string} sourceEntityId
+     * @param {string} [sourceAttribute]
+     * @returns {Array<Object>} Affected downstream entities and attributes
+     */
+    traceImpact(sourceEntityId, sourceAttribute = null) {
+        const impacts = [];
+        const visited = new Set();
+        const queue = [{ entity: sourceEntityId, attribute: sourceAttribute, depth: 0 }];
+
+        while (queue.length) {
+            const current = queue.shift();
+            const key = `${current.entity}:${current.attribute || '*'}`;
+            if (visited.has(key)) continue;
+            visited.add(key);
+
+            for (const map of this.modelMappings) {
+                for (const attrMap of map.attributeMappings) {
+                    if (attrMap.sourceEntityId === current.entity &&
+                        (!current.attribute || attrMap.sourceAttribute === current.attribute)) {
+                        const step = {
+                            sourceModel: map.sourceModel,
+                            targetModel: map.targetModel,
+                            sourceEntityId: attrMap.sourceEntityId,
+                            sourceAttribute: attrMap.sourceAttribute,
+                            targetEntityId: attrMap.targetEntityId,
+                            targetAttribute: attrMap.targetAttribute,
+                            transformation: attrMap.transformation,
+                            rule: attrMap.rule,
+                            depth: current.depth + 1,
+                        };
+                        impacts.push(step);
+                        queue.push({
+                            entity: attrMap.targetEntityId,
+                            attribute: attrMap.targetAttribute,
+                            depth: current.depth + 1,
+                        });
+                    }
+                }
+            }
+        }
+        return impacts;
+    }
+
+    /**
+     * Generates a graph representation of the lineage suitable for diagramming or export.
+     * @returns {{ nodes: Array<{id: string, entity: string, attribute: string, model: string}>, edges: Array<{source: string, target: string, transformation: string, rule: string}> }}
+     */
+    toGraph() {
+        const nodes = new Map();
+        const edges = [];
+
+        for (const map of this.modelMappings) {
+            for (const m of map.attributeMappings) {
+                const srcId = `${map.sourceModel || 'source'}:${m.sourceEntityId}.${m.sourceAttribute}`;
+                const tgtId = `${map.targetModel || 'target'}:${m.targetEntityId}.${m.targetAttribute}`;
+                if (!nodes.has(srcId)) {
+                    nodes.set(srcId, {
+                        id: srcId,
+                        model: map.sourceModel || 'source',
+                        entity: m.sourceEntityId,
+                        attribute: m.sourceAttribute,
+                    });
+                }
+                if (!nodes.has(tgtId)) {
+                    nodes.set(tgtId, {
+                        id: tgtId,
+                        model: map.targetModel || 'target',
+                        entity: m.targetEntityId,
+                        attribute: m.targetAttribute,
+                    });
+                }
+                edges.push({
+                    source: srcId,
+                    target: tgtId,
+                    transformation: m.transformation,
+                    rule: m.rule,
+                });
+            }
+        }
+        return { nodes: [...nodes.values()], edges };
+    }
+}

package/src/charting/datamodel/DataModel.js

@@ -15,6 +15,9 @@ import { NamingStandard } from './naming/NamingStandard.js';
 import { ClassificationScheme } from './ClassificationScheme.js';
 import { ModelScorecard } from './scorecard/ModelScorecard.js';
 import { ServiceLandscape } from './ServiceLandscape.js';
+import { ModelMapping } from './ModelMapping.js';
+import { DataLineage } from './DataLineage.js';
+import { ArchimateDataLink } from './ArchimateDataLink.js';
 import {
     LevelEntitiesCompared, LevelRelationshipsCompared, MappingsCompared, ContextsCompared, PerspectivesCompared, DataTypesCompared,
 } from './DataModelCompared.js';
@@ -44,7 +47,7 @@ const LEVELS = Object.freeze(['conceptual', 'logical', 'physical']);
  */
 export class DataModel extends EditableModel {
     /** What a snapshot puts back (EditableModel#restore). */
-    static STATE = Object.freeze(['name', 'levels', 'mappings', 'mappingLayout', 'noteLayout', 'perspectives', 'contexts', 'dataTypes', 'namingStandard', 'classificationScheme', 'scorecard']);
+    static STATE = Object.freeze(['name', 'levels', 'mappings', 'mappingLayout', 'noteLayout', 'perspectives', 'contexts', 'dataTypes', 'namingStandard', 'classificationScheme', 'scorecard', 'modelMappings', 'archimateLinks']);
 
     /** The levels, outermost first. */
     static LEVELS = LEVELS;
@@ -149,6 +152,8 @@ export class DataModel extends EditableModel {
         this.classificationScheme = spec.classificationScheme instanceof ClassificationScheme ? spec.classificationScheme : new ClassificationScheme(spec.classificationScheme ?? {});
         /** What a reviewer said on the Scorecard, and the weights reviewed by (ModelScorecard), or null. */
         this.scorecard = spec.scorecard ? JSON.parse(JSON.stringify(spec.scorecard)) : null;
+        this.modelMappings = (spec.modelMappings ?? []).map(m => m instanceof ModelMapping ? m : new ModelMapping(m));
+        this.archimateLinks = (spec.archimateLinks ?? []).map(l => l instanceof ArchimateDataLink ? l : new ArchimateDataLink(l));
     }
 
     /** The model scored on the Data Model Scorecard (ModelScorecard). */
@@ -919,6 +924,83 @@ ${theirs}` : theirs;
             ...(this.namingStandard && { namingStandard: this.namingStandard.toJSON() }),
             ...(!this.classificationScheme.isDefault && { classificationScheme: this.classificationScheme.toJSON() }),
             ...(this.scorecard && { scorecard: JSON.parse(JSON.stringify(this.scorecard)) }),
+            ...(this.modelMappings.length && { modelMappings: this.modelMappings.map(m => m.toJSON()) }),
+            ...(this.archimateLinks.length && { archimateLinks: this.archimateLinks.map(l => l.toJSON()) }),
         };
     }
+
+    /** Add a cross-model mapping (DMBOK2 Integration & Interoperability). */
+    addModelMapping(mapping) {
+        const m = mapping instanceof ModelMapping ? mapping : new ModelMapping(mapping);
+        this.modelMappings.push(m);
+        return m;
+    }
+
+    /** End-to-end data lineage across models and internal level mappings (DMBOK2). */
+    crossModelLineage() {
+        return new DataLineage({ modelMappings: this.modelMappings, levelMappings: this.mappings });
+    }
+
+    /** Link a data model concept to an ArchiMate model element (DMBOK2 Data Architecture). */
+    linkToArchimate({ entityId, level = 'conceptual', archimateElementId, archimateType = 'business-object', archimateModelId = null, notes = '' }) {
+        this.unlinkFromArchimate(entityId, archimateElementId);
+        const link = new ArchimateDataLink({
+            dataModelEntityId: entityId,
+            level,
+            archimateElementId,
+            archimateType,
+            archimateModelId,
+            notes,
+        });
+        this.archimateLinks.push(link);
+        return link;
+    }
+
+    /** Remove a link to an ArchiMate element. */
+    unlinkFromArchimate(entityId, archimateElementId) {
+        this.archimateLinks = this.archimateLinks.filter(l => !(l.dataModelEntityId === entityId && l.archimateElementId === archimateElementId));
+    }
+
+    /** Links for a specific data model entity. */
+    archimateLinksFor(entityId) {
+        return this.archimateLinks.filter(l => l.dataModelEntityId === entityId);
+    }
+
+    /**
+     * Validate linked ArchiMate elements against an ArchiMate model (DMBOK2 Data Architecture).
+     * Verifies existence, element type and layer alignment.
+     * @param {ArchimateModel} archimateModel
+     * @returns {Array<{ link: ArchimateDataLink, valid: boolean, errors: Array<string> }>}
+     */
+    validateArchimateRealization(archimateModel) {
+        const results = [];
+        for (const link of this.archimateLinks) {
+            const errors = [];
+            const el = typeof archimateModel.getElement === 'function' ? archimateModel.getElement(link.archimateElementId) : null;
+            if (!el) {
+                errors.push(`Referenced ArchiMate element "${link.archimateElementId}" not found in ArchiMate model`);
+            } else if (el.type !== link.archimateType) {
+                errors.push(`Type mismatch: link specifies "${link.archimateType}" but model element is "${el.type}"`);
+            }
+            const layerCheck = link.validateLayerAlignment();
+            if (!layerCheck.valid) {
+                errors.push(layerCheck.recommendation);
+            }
+            results.push({ link, valid: errors.length === 0, errors });
+        }
+        return results;
+    }
+
+    /**
+     * Create an ArchiMate realization view on the given ArchiMate model showing the data architecture realization.
+     * @param {ArchimateModel} archimateModel
+     * @param {string} [viewTitle='Data Architecture Realization']
+     * @returns {ArchimateView}
+     */
+    createArchimateRealizationView(archimateModel, viewTitle = 'Data Architecture Realization') {
+        const elementIds = [...new Set(this.archimateLinks.map(l => l.archimateElementId))];
+        const view = archimateModel.createView(viewTitle);
+        view.elementIds = elementIds;
+        return view;
+    }
 }

package/src/charting/datamodel/ModelMapping.js

@@ -0,0 +1,87 @@
+/**
+ * ModelMapping — mappings between distinct data models (DMBOK2 Integration & Interoperability).
+ * Maps source model entities and attributes to target model entities and attributes,
+ * with transformation rules and expressions.
+ */
+export class ModelMapping {
+    /**
+     * @param {Object} spec
+     * @param {string} [spec.id]
+     * @param {string} [spec.name]
+     * @param {string} [spec.sourceModel] - Name or identifier of the source data model
+     * @param {string} [spec.targetModel] - Name or identifier of the target data model
+     * @param {Array<Object>} [spec.entityMappings]
+     * @param {Array<Object>} [spec.attributeMappings]
+     * @param {string} [spec.documentation]
+     */
+    constructor({
+        id,
+        name = 'Cross-Model Mapping',
+        sourceModel = '',
+        targetModel = '',
+        entityMappings = [],
+        attributeMappings = [],
+        documentation = '',
+    } = {}) {
+        this.id = id || `mapping-${Date.now().toString(36)}`;
+        this.name = name;
+        this.sourceModel = sourceModel;
+        this.targetModel = targetModel;
+        this.documentation = documentation;
+        this.entityMappings = entityMappings.map(e => ({ ...e }));
+        this.attributeMappings = attributeMappings.map(a => ({ ...a }));
+    }
+
+    /**
+     * Add an entity-level mapping between source and target entities.
+     */
+    addEntityMapping({ sourceEntityId, targetEntityId, name = '', description = '' } = {}) {
+        if (!sourceEntityId || !targetEntityId) {
+            throw new TypeError('Entity mapping requires sourceEntityId and targetEntityId');
+        }
+        if (!this.entityMappings.some(m => m.sourceEntityId === sourceEntityId && m.targetEntityId === targetEntityId)) {
+            this.entityMappings.push({ sourceEntityId, targetEntityId, name, description });
+        }
+    }
+
+    /**
+     * Add an attribute-level field mapping with transformation rule.
+     */
+    addAttributeMapping({ sourceEntityId, sourceAttribute, targetEntityId, targetAttribute, transformation = 'direct', rule = '' } = {}) {
+        if (!sourceEntityId || !sourceAttribute || !targetEntityId || !targetAttribute) {
+            throw new TypeError('Attribute mapping requires sourceEntityId, sourceAttribute, targetEntityId, and targetAttribute');
+        }
+        const existing = this.attributeMappings.find(m =>
+            m.sourceEntityId === sourceEntityId && m.sourceAttribute === sourceAttribute &&
+            m.targetEntityId === targetEntityId && m.targetAttribute === targetAttribute
+        );
+        if (existing) {
+            existing.transformation = transformation;
+            existing.rule = rule;
+        } else {
+            this.attributeMappings.push({ sourceEntityId, sourceAttribute, targetEntityId, targetAttribute, transformation, rule });
+        }
+    }
+
+    /** All attribute mappings targeting an entity. */
+    attributesTargeting(entityId) {
+        return this.attributeMappings.filter(m => m.targetEntityId === entityId);
+    }
+
+    /** All attribute mappings sourced from an entity. */
+    attributesSourcedFrom(entityId) {
+        return this.attributeMappings.filter(m => m.sourceEntityId === entityId);
+    }
+
+    toJSON() {
+        return {
+            id: this.id,
+            name: this.name,
+            sourceModel: this.sourceModel,
+            targetModel: this.targetModel,
+            documentation: this.documentation,
+            entityMappings: this.entityMappings.map(e => ({ ...e })),
+            attributeMappings: this.attributeMappings.map(a => ({ ...a })),
+        };
+    }
+}

package/src/charting/datamodel/SqlDdl.js

@@ -1,85 +1,110 @@
-/** Words SQL keeps for itself that a name may not be left bare as. */
-const RESERVED = new Set(['user', 'order', 'group', 'table', 'select', 'from', 'where', 'by', 'to', 'key', 'check', 'default', 'index', 'primary', 'foreign', 'references', 'unique', 'column', 'constraint', 'value', 'values', 'date', 'time', 'timestamp', 'level', 'position', 'role']);
-
-/**
- * SqlDdl — a model's physical level as SQL DDL (DMBOK2's data integration: the
- * design handed to a database): a CREATE TABLE per table, its columns with
- * their types (`defaultType` where a column has none) and NOT NULL where
- * required, its primary key and UNIQUE columns; a FOREIGN KEY per column that
- * references another (`references`: a table, or `table.column`, by id or name;
- * a table alone: its primary key); and COMMENT ONs for definitions. Names are
- * quoted where SQL would not take them bare. ANSI SQL, as PostgreSQL reads it.
- */
-export class SqlDdl {
-    /**
-     * @param {Object} [options]
-     * @param {string} [options.defaultType] - A column's type when it names none
-     * @param {boolean} [options.comments] - Whether definitions become COMMENT ONs
-     */
-    constructor({ defaultType = 'VARCHAR(255)', comments = true } = {}) {
-        this.defaultType = defaultType;
-        this.comments = comments;
-    }
-
-    /** A name as SQL takes it: bare when it can be, else double-quoted. */
-    static name(text) {
-        const s = String(text);
-        return /^[a-z_][a-z0-9_]*$/.test(s) && !RESERVED.has(s) ? s : `"${s.replace(/"/g, '""')}"`;
-    }
-
-    /**
-     * A table's name as SQL takes it: a schema-qualified one (`sales.customer`)
-     * each part as name() has it, so it names the table in its schema rather
-     * than one table called "sales.customer".
-     */
-    static tableName(text) {
-        return String(text).split('.').map(SqlDdl.name).join('.');
-    }
-
-    /** A text as an SQL string literal. */
-    static literal(text) {
-        return `'${String(text).replace(/'/g, "''")}'`;
-    }
-
-    /** The DDL for a model's physical level. @returns {string} */
-    write(model) {
-        const schema = model.level('physical');
-        const tables = schema.entities;
-        const table = SqlDdl.tableName;
-        const out = [`-- ${model.name || 'Data model'}: the physical level, ${tables.length} table${tables.length === 1 ? '' : 's'}`, ''];
-        for (const t of tables) {
-            const columns = t.attributes ?? [];
-            const keys = columns.filter(c => c.isPK).map(c => SqlDdl.name(c.name));
-            const lines = [
-                ...columns.map(c => `    ${SqlDdl.name(c.name)} ${c.type || this.defaultType}${c.required || c.isPK ? ' NOT NULL' : ''}`),
-                ...(keys.length ? [`    PRIMARY KEY (${keys.join(', ')})`] : []),
-                ...columns.filter(c => c.isUnique && !c.isPK).map(c => `    UNIQUE (${SqlDdl.name(c.name)})`),
-            ];
-            out.push(`CREATE TABLE ${table(t.name)} (`, lines.join(',\n'), ');', '');
-        }
-        for (const t of tables) {
-            for (const c of (t.attributes ?? []).filter(a => a.isFK && a.references)) {
-                const ref = schema.resolveReference(c.references);
-                if (!ref) {
-                    out.push(`-- ${t.name}.${c.name} references ${c.references}, which is not a table here`);
-                    continue;
-                }
-                const theirs = ref.column ? [ref.column] : (ref.entity.attributes ?? []).filter(a => a.isPK).map(a => a.name);
-                if (!theirs.length) {
-                    out.push(`-- ${t.name}.${c.name} references ${ref.entity.name}, which has no primary key`);
-                    continue;
-                }
-                out.push(`ALTER TABLE ${table(t.name)} ADD CONSTRAINT ${SqlDdl.name(`fk_${t.name}_${c.name}`.toLowerCase().replace(/[^a-z0-9_]+/g, '_'))}`
-                    + ` FOREIGN KEY (${SqlDdl.name(c.name)}) REFERENCES ${table(ref.entity.name)} (${theirs.map(SqlDdl.name).join(', ')});`);
-            }
-        }
-        if (this.comments) {
-            const notes = tables.flatMap(t => [
-                ...(t.description ? [`COMMENT ON TABLE ${table(t.name)} IS ${SqlDdl.literal(t.description)};`] : []),
-                ...(t.attributes ?? []).filter(c => c.description).map(c => `COMMENT ON COLUMN ${table(t.name)}.${SqlDdl.name(c.name)} IS ${SqlDdl.literal(c.description)};`),
-            ]);
-            if (notes.length) out.push('', ...notes);
-        }
-        return `${out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`;
-    }
-}
+/** Words SQL keeps for itself that a name may not be left bare as. */
+const RESERVED = new Set(['user', 'order', 'group', 'table', 'select', 'from', 'where', 'by', 'to', 'key', 'check', 'default', 'index', 'primary', 'foreign', 'references', 'unique', 'column', 'constraint', 'value', 'values', 'date', 'time', 'timestamp', 'level', 'position', 'role']);
+
+/**
+ * SqlDdl — a model's physical level as SQL DDL (DMBOK2's data integration: the
+ * design handed to a database): a CREATE TABLE per table, its columns with
+ * their types (`defaultType` where a column has none) and NOT NULL where
+ * required, its primary key and UNIQUE columns; a FOREIGN KEY per column that
+ * references another (`references`: a table, or `table.column`, by id or name;
+ * a table alone: its primary key); and COMMENT ONs for definitions. Names are
+ * quoted where SQL would not take them bare. ANSI SQL, as PostgreSQL reads it.
+ */
+export class SqlDdl {
+    /**
+     * @param {Object} [options]
+     * @param {string} [options.defaultType] - A column's type when it names none
+     * @param {boolean} [options.comments] - Whether definitions become COMMENT ONs
+     * @param {boolean|Array<string>|Set<string>|Object} [options.external] - Trust foreign keys to tables outside the model
+     */
+    constructor({ defaultType = 'VARCHAR(255)', comments = true, external = false } = {}) {
+        this.defaultType = defaultType;
+        this.comments = comments;
+        this.external = external;
+    }
+
+    /** A name as SQL takes it: bare when it can be, else double-quoted. */
+    static name(text) {
+        const s = String(text);
+        return /^[a-z_][a-z0-9_]*$/.test(s) && !RESERVED.has(s) ? s : `"${s.replace(/"/g, '""')}"`;
+    }
+
+    /**
+     * A table's name as SQL takes it: a schema-qualified one (`sales.customer`)
+     * each part as name() has it, so it names the table in its schema rather
+     * than one table called "sales.customer".
+     */
+    static tableName(text) {
+        return String(text).split('.').map(SqlDdl.name).join('.');
+    }
+
+    /** A text as an SQL string literal. */
+    static literal(text) {
+        return `'${String(text).replace(/'/g, "''")}'`;
+    }
+
+    /** The DDL for a model's physical level. @returns {string} */
+    write(model, { external = this.external } = {}) {
+        const schema = model.level('physical');
+        const tables = schema.entities;
+        const table = SqlDdl.tableName;
+        const out = [`-- ${model.name || 'Data model'}: the physical level, ${tables.length} table${tables.length === 1 ? '' : 's'}`, ''];
+        for (const t of tables) {
+            const columns = t.attributes ?? [];
+            const keys = columns.filter(c => c.isPK).map(c => SqlDdl.name(c.name));
+            const lines = [
+                ...columns.map(c => `    ${SqlDdl.name(c.name)} ${c.type || this.defaultType}${c.required || c.isPK ? ' NOT NULL' : ''}`),
+                ...(keys.length ? [`    PRIMARY KEY (${keys.join(', ')})`] : []),
+                ...columns.filter(c => c.isUnique && !c.isPK).map(c => `    UNIQUE (${SqlDdl.name(c.name)})`),
+            ];
+            out.push(`CREATE TABLE ${table(t.name)} (`, lines.join(',\n'), ');', '');
+        }
+
+        const isExternalTrusted = (tableName) => {
+            if (external === true) return true;
+            if (external instanceof Set) return external.has(tableName);
+            if (Array.isArray(external)) return external.includes(tableName);
+            if (external && typeof external === 'object') return !!external[tableName];
+            return false;
+        };
+
+        for (const t of tables) {
+            for (const c of (t.attributes ?? []).filter(a => a.isFK && a.references)) {
+                const ref = schema.resolveReference(c.references);
+                if (!ref) {
+                    const raw = String(c.references).trim();
+                    const dot = raw.lastIndexOf('.');
+                    let targetTable = raw;
+                    let targetCol = null;
+                    if (dot > 0) {
+                        targetTable = raw.slice(0, dot);
+                        targetCol = raw.slice(dot + 1);
+                    }
+                    if (isExternalTrusted(targetTable)) {
+                        const colRef = targetCol ? ` (${SqlDdl.name(targetCol)})` : '';
+                        out.push(`ALTER TABLE ${table(t.name)} ADD CONSTRAINT ${SqlDdl.name(`fk_${t.name}_${c.name}`.toLowerCase().replace(/[^a-z0-9_]+/g, '_'))}`
+                            + ` FOREIGN KEY (${SqlDdl.name(c.name)}) REFERENCES ${table(targetTable)}${colRef};`);
+                    } else {
+                        out.push(`-- ${t.name}.${c.name} references ${c.references}, which is not a table here`);
+                    }
+                    continue;
+                }
+                const theirs = ref.column ? [ref.column] : (ref.entity.attributes ?? []).filter(a => a.isPK).map(a => a.name);
+                if (!theirs.length) {
+                    out.push(`-- ${t.name}.${c.name} references ${ref.entity.name}, which has no primary key`);
+                    continue;
+                }
+                out.push(`ALTER TABLE ${table(t.name)} ADD CONSTRAINT ${SqlDdl.name(`fk_${t.name}_${c.name}`.toLowerCase().replace(/[^a-z0-9_]+/g, '_'))}`
+                    + ` FOREIGN KEY (${SqlDdl.name(c.name)}) REFERENCES ${table(ref.entity.name)} (${theirs.map(SqlDdl.name).join(', ')});`);
+            }
+        }
+        if (this.comments) {
+            const notes = tables.flatMap(t => [
+                ...(t.description ? [`COMMENT ON TABLE ${table(t.name)} IS ${SqlDdl.literal(t.description)};`] : []),
+                ...(t.attributes ?? []).filter(c => c.description).map(c => `COMMENT ON COLUMN ${table(t.name)}.${SqlDdl.name(c.name)} IS ${SqlDdl.literal(c.description)};`),
+            ]);
+            if (notes.length) out.push('', ...notes);
+        }
+        return `${out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`;
+    }
+}

package/src/charting/datamodel/index.js

@@ -19,3 +19,6 @@ export { DataModelFileFormat } from './DataModelFileFormat.js';
 export { SqlDdl } from './SqlDdl.js';
 export { SqlDdlFileFormat } from './SqlDdlFileFormat.js';
 export { LevelEntitiesCompared, LevelRelationshipsCompared, MappingsCompared, ContextsCompared, PerspectivesCompared, DataTypesCompared } from './DataModelCompared.js';
+export { ModelMapping } from './ModelMapping.js';
+export { DataLineage } from './DataLineage.js';
+export { ArchimateDataLink } from './ArchimateDataLink.js';