@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/charting/diagrams/ArchimateModelChecker.js

@@ -0,0 +1,125 @@
+import { ViewSetChecker } from '../diagramModel/ViewSetChecker.js';
+import { ArchimateValidator } from './ArchimateValidator.js';
+import { viewNestings, nestingRelationships } from './nesting.js';
+import { duplicateGroups, UNPRINTABLE } from './duplicates.js';
+
+/**
+ * ArchimateModelChecker — the checks Archi's validator makes over a model,
+ * on top of the view-set ones (empty views): relationships the specification
+ * does not allow, elements that look like the same thing twice, and elements
+ * and relationships no view shows (a relationship a nesting stands for counts
+ * as shown), and elements nested in another with no relationship for it.
+ * Findings name elements, relationships or views (`kind`).
+ */
+export class ArchimateModelChecker extends ViewSetChecker {
+    /**
+     * @param {ArchimateModel} model
+     * @param {Object} [options]
+     * @param {string} [options.version] - ArchiMate version for the relationship check ('3.2' | '4')
+     */
+    constructor(model, { version = '4' } = {}) {
+        super(model);
+        this.version = version;
+    }
+
+    checks() {
+        return [this.invalidRelationships, this.possibleDuplicates, this.unusedElements, this.unusedRelationships, this.nestedWithoutRelationship, this.unprintableText, ...super.checks()];
+    }
+
+    /** Elements drawn on no view. */
+    unusedElements() {
+        const drawn = new Set(this.model.views().flatMap(v => [...v.elementInstances.values()].map(i => i.elementId)));
+        return this.model.elements()
+            .filter(e => !drawn.has(e.id))
+            .map(e => ({ code: 'unused-element', severity: 'info', kind: 'element', ids: [e.id], message: `"${this._name(e)}" is in no view` }));
+    }
+
+    /** Relationships drawn on no view, nor shown by a nesting (an element drawn inside another). */
+    unusedRelationships() {
+        const drawn = new Set(this.model.views().flatMap(v => [...v.relationshipInstances.values()].map(i => i.relationshipId)));
+        for (const n of this.model.views().flatMap(v => viewNestings(v))) {
+            for (const r of nestingRelationships(this.model, n.parentElementId, n.childElementId)) drawn.add(r.id);
+        }
+        return this.model.relationships()
+            .filter(r => !drawn.has(r.id))
+            .map(r => ({ code: 'unused-relationship', severity: 'info', kind: 'relationship', ids: [r.id], message: `${this._relationshipText(r)} is in no view` }));
+    }
+
+    /**
+     * Elements drawn inside another on a view with no relationship from the
+     * parent to it that a nesting stands for (NESTING_KINDS): the drawing says
+     * more than the model does. One finding per view and pair.
+     */
+    nestedWithoutRelationship() {
+        const seen = new Set();
+        return this.model.views().flatMap(v => viewNestings(v))
+            .filter(n => !nestingRelationships(this.model, n.parentElementId, n.childElementId).length)
+            .filter(n => { const key = `${n.view.id}\u0000${n.parentElementId}\u0000${n.childElementId}`; return !seen.has(key) && seen.add(key); })
+            .map(n => {
+                const [parent, child] = [n.parentElementId, n.childElementId].map(id => this.model.getElement(id));
+                return {
+                    code: 'nested-without-relationship', severity: 'warning', kind: 'element', ids: [n.childElementId], viewId: n.view.id,
+                    message: `"${this._name(child)}" is drawn inside "${this._name(parent)}" on "${n.view.name || n.view.id}" with no relationship between them`,
+                };
+            });
+    }
+
+    /**
+     * Elements of the same type whose names have the same words (ignoring
+     * case, punctuation, word order and filler words: duplicates.js): likely
+     * one thing twice. The finding names them all, so they can be merged.
+     */
+    possibleDuplicates() {
+        return duplicateGroups(this.model.elements()).map(g => {
+            // Names that differ only in case and spacing are one name to the reader.
+            const byLook = new Map();
+            for (const e of g) {
+                const look = this._name(e).trim().replace(/\s+/g, ' ').toLowerCase();
+                if (!byLook.has(look)) byLook.set(look, this._name(e).trim());
+            }
+            const names = [...byLook.values()];
+            return {
+                code: 'possible-duplicate', severity: 'warning', kind: 'element', ids: g.map(e => e.id),
+                message: names.length === 1
+                    ? `${g.length} ${g[0].type} elements are named "${names[0]}"`
+                    : `${g.length} ${g[0].type} elements look the same: ${names.map(n => `"${n}"`).join(', ')}`,
+            };
+        });
+    }
+
+    /** Names and documentation of elements and relationships with characters that should not be there (control characters, zero-width spaces). */
+    unprintableText() {
+        const found = [];
+        const look = (kind, item) => {
+            const fields = [['name', UNPRINTABLE.name], ['documentation', UNPRINTABLE.documentation]].filter(([f, re]) => re.test(String(item[f] ?? '')));
+            if (fields.length) {
+                found.push({
+                    code: 'unprintable-text', severity: 'warning', kind, ids: [item.id],
+                    message: `${kind === 'element' ? `"${this._name(item).replace(UNPRINTABLE.name, '?')}"` : this._relationshipText(item)} has unprintable characters in its ${fields.map(([f]) => f).join(' and ')}`,
+                });
+            }
+        };
+        this.model.elements().forEach(e => look('element', e));
+        this.model.relationships().forEach(r => look('relationship', r));
+        return found;
+    }
+
+    /** Relationships the ArchiMate specification does not allow between their ends. */
+    invalidRelationships() {
+        const warnings = ArchimateValidator.validateModel(this.model.elements(), this.model.relationships(), this.version);
+        return warnings
+            .filter(w => w.type === 'relationship' && w.relationship)
+            .map(w => ({ code: w.code ?? 'invalid-relationship', severity: 'warning', kind: 'relationship', ids: [w.relationship.id], message: `${this._relationshipText(w.relationship)}: ${w.message}` }));
+    }
+
+    /** @private */
+    _name(element) {
+        return element?.name || element?.id || '?';
+    }
+
+    /** @private */
+    _relationshipText(r) {
+        const end = (id) => { const e = this.model.getElement(id); return e ? this._name(e) : id; };
+        return `${r.kind || 'association'} from "${end(r.source)}" to "${end(r.target)}"`;
+    }
+}

package/src/charting/diagrams/ArchimateModelReport.js

@@ -0,0 +1,128 @@
+import { ModelReport } from '../diagramModel/ModelReport.js';
+import { ArchimateDiagram } from './ArchimateDiagram.js';
+import { TREE_LAYERS, treeLayerOf } from '../modelTree/treeLayers.js';
+import { typeTitle } from '../archimate/archimateNames.js';
+
+/**
+ * ArchimateModelReport — the report of an ArchiMate model (as Archi's HTML
+ * report): on top of the views, a page per element (its type and layer
+ * colour, documentation, properties, its relationships with the element at
+ * the other end, the views it is on) and per relationship (its source and
+ * target, the views it is on); a view's page lists its elements and
+ * relationships. The tree has Elements by layer, as the model tree has them,
+ * and Relationships by kind.
+ */
+export class ArchimateModelReport extends ModelReport {
+    modelFacts() {
+        return [
+            { label: 'Elements', text: String(this.model.elements().length) },
+            { label: 'Relationships', text: String(this.model.relationships().length) },
+            ...super.modelFacts(),
+        ];
+    }
+
+    viewType(view) {
+        return view.constructor.kind === 'canvas' ? 'Canvas' : 'View';
+    }
+
+    viewFacts(view) {
+        return view.viewpoint ? [{ label: 'Viewpoint', text: typeTitle(String(view.viewpoint)) }] : [];
+    }
+
+    /** A view's elements and relationships, each once, in the order they were placed. */
+    viewLists(view) {
+        const once = (ids) => [...new Set(ids)];
+        const elementIds = once([...(view.elementInstances?.values() ?? [])].map(i => i.elementId))
+            .filter(id => id && this.model.getElement(id));
+        const relationshipIds = once([...(view.relationshipInstances?.values() ?? [])].map(i => i.relationshipId))
+            .filter(id => id && this.model.getRelationship(id));
+        return [
+            { title: 'Elements', rows: elementIds.map(id => ({ key: this.key('element', id), note: typeTitle(this.model.getElement(id).type ?? '') })) },
+            // A named relationship's row says which elements it joins; an unnamed one's name already does.
+            { title: 'Relationships', rows: relationshipIds.map(id => { const rel = this.model.getRelationship(id); return { key: this.key('relationship', id), ...(rel.name && { note: this.ends(rel) }) }; }) },
+        ];
+    }
+
+    conceptItems() {
+        return [...this.model.elements().map(e => this.elementItem(e)), ...this.model.relationships().map(r => this.relationshipItem(r))];
+    }
+
+    /** An element's page. */
+    elementItem(element) {
+        const { incoming, outgoing } = this.model.relationshipsFor(element.id);
+        // An unnamed relationship's name already says which elements it joins; a named one's row says the other end.
+        const row = (rel, other, arrow) => ({ key: this.key('relationship', rel.id), ...(rel.name && { note: `${arrow} ${this.nameOf(other)}` }) });
+        return this.item('element', element.id, {
+            name: element.name,
+            type: typeTitle(element.type ?? 'element'),
+            color: this.colorOf(element),
+            documentation: element.documentation,
+            properties: element.properties,
+            facts: [{ label: 'Layer', text: typeTitle(treeLayerOf(element)) }],
+            lists: [
+                { title: 'Relationships', rows: [...outgoing.map(r => row(r, r.target, '→')), ...incoming.map(r => row(r, r.source, '←'))] },
+                { title: 'Views', rows: this.model.views().filter(v => v.elementInstancesFor?.(element.id).length).map(v => ({ key: this.key('view', v.id) })) },
+            ],
+        });
+    }
+
+    /** A relationship's page. */
+    relationshipItem(rel) {
+        const end = (label, id) => (this.model.getElement(id) ? { label, key: this.key('element', id) } : { label, text: String(id ?? '') });
+        return this.item('relationship', rel.id, {
+            name: this.relationshipName(rel),
+            type: `${typeTitle(this.kindOf(rel))} relationship`,
+            documentation: rel.documentation,
+            properties: rel.properties,
+            facts: [end('Source', rel.source), end('Target', rel.target)],
+            lists: [{ title: 'Views', rows: this.model.views().filter(v => v.relationshipInstancesFor?.(rel.id).length).map(v => ({ key: this.key('view', v.id) })) }],
+        });
+    }
+
+    /** A relationship's name, or (most have none) its kind and ends. */
+    relationshipName(rel) {
+        return rel.name || `${typeTitle(this.kindOf(rel))}: ${this.ends(rel)}`;
+    }
+
+    /** Elements by layer (in the model tree's order), then relationships by kind. */
+    conceptSections() {
+        const elements = this.model.elements();
+        const relationships = this.model.relationships();
+        const byLayer = TREE_LAYERS.map(layer => ({
+            title: typeTitle(layer),
+            keys: this.sorted(elements.filter(e => treeLayerOf(e) === layer)).map(e => this.key('element', e.id)),
+        }));
+        const kinds = [...new Set(relationships.map(r => this.kindOf(r)))].sort();
+        const byKind = kinds.map(kind => ({
+            title: typeTitle(kind),
+            keys: this.sorted(relationships.filter(r => this.kindOf(r) === kind), r => this.relationshipName(r))
+                .map(r => this.key('relationship', r.id)),
+        }));
+        return [{ title: 'Elements', groups: byLayer }, { title: 'Relationships', groups: byKind }];
+    }
+
+    /** A relationship's kind ('serving', ...): `kind`, or `type` as some sources write it. */
+    kindOf(rel) {
+        return rel.kind ?? rel.type ?? 'relationship';
+    }
+
+    /** "Source → Target" by name. */
+    ends(rel) {
+        return `${this.nameOf(rel.source)} → ${this.nameOf(rel.target)}`;
+    }
+
+    /** @private */
+    nameOf(elementId) {
+        return this.model.getElement(elementId)?.name || elementId || '?';
+    }
+
+    /** @private */
+    colorOf(element) {
+        return element.fillColor || ArchimateDiagram.layerColor(ArchimateDiagram.elementLayer(element));
+    }
+
+    /** @private */
+    sorted(items, name = (i) => i.name ?? '') {
+        return [...items].sort((a, b) => String(name(a)).localeCompare(String(name(b))));
+    }
+}

package/src/charting/diagrams/ArchimateModelSearch.js

@@ -0,0 +1,41 @@
+import { ModelSearch } from '../diagramModel/ModelSearch.js';
+import { ViewObjectInstance } from './ViewObjectInstance.js';
+
+/**
+ * ArchimateModelSearch — find and replace in an ArchiMate model (as Archi's
+ * Find/Replace): on top of the model and views (ModelSearch), every element's
+ * and relationship's name, documentation and properties, and the text of the
+ * notes on each view.
+ */
+export class ArchimateModelSearch extends ModelSearch {
+    conceptTargets() {
+        const concept = (kind, c) => {
+            const owner = { kind, id: c.id, owner: c.name || c.id };
+            return [this.text(owner, 'name', c), this.text(owner, 'documentation', c), ...this.propertyTargets(owner, c.properties)];
+        };
+        return [
+            ...this.model.elements().flatMap(e => concept('element', e)),
+            ...this.model.relationships().flatMap(r => concept('relationship', r)),
+        ];
+    }
+
+    /** Elements and relationships hold properties too. */
+    propertyHolders() {
+        return [
+            ...super.propertyHolders(),
+            ...this.model.elements().map(e => ({ owner: `element ${e.id}`, object: e })),
+            ...this.model.relationships().map(r => ({ owner: `relationship ${r.id}`, object: r })),
+        ];
+    }
+
+    /** A note's text (its `label`, and the `name` it is listed by), which belongs to its view. */
+    viewItemTargets(view) {
+        return [...(view.elementInstances?.values() ?? [])]
+            .filter(inst => inst instanceof ViewObjectInstance && inst.content.shape === 'note')
+            .map(inst => ({
+                kind: 'note', id: inst.id, viewId: view.id, owner: 'Note', field: 'name', fieldLabel: 'Text',
+                read: () => inst.content.label ?? '',
+                write: (text) => { inst.content.label = text; inst.content.name = text; },
+            }));
+    }
+}

package/src/charting/diagrams/ArchimateValidator.js

@@ -0,0 +1,357 @@
+import { ArchimateNotation, ArchimateViewpoints, archimate32Type } from '../../archimate.js';
+import { ITIconNotation } from '../../itIcons.js';
+import { RELATIONSHIP_LETTERS, RELATIONSHIP_TABLE_CONCEPTS, RELATIONSHIP_TABLE_ROWS, RELATIONSHIP_TABLE_VERSION } from '../../archimateRelationshipTable.js';
+
+/** source type -> target type -> Set of allowed kinds, from the specification's table (built on first use). */
+let SPEC_TABLE = null;
+function specTable() {
+    if (SPEC_TABLE) return SPEC_TABLE;
+    SPEC_TABLE = new Map();
+    for (const [source, row] of Object.entries(RELATIONSHIP_TABLE_ROWS)) {
+        const targets = new Map();
+        row.split(',').forEach((letters, i) => {
+            targets.set(RELATIONSHIP_TABLE_CONCEPTS[i], new Set([...letters].map(c => RELATIONSHIP_LETTERS[c]).filter(Boolean)));
+        });
+        SPEC_TABLE.set(source, targets);
+    }
+    return SPEC_TABLE;
+}
+
+/**
+ * ArchimateValidator — DOM-free ArchiMate standard-alignment checks.
+ *
+ * The validator is advisory: it returns warnings, it never blocks rendering.
+ * Rules are encoded as data so they can be tuned as the standard interpretation
+ * evolves. Custom/unofficial element types are allowed through without warnings
+ * unless the relationship kind is clearly nonsensical for the resolved aspects.
+ *
+ * Coverage:
+ *   - Relationship validity by source/target aspect and layer.
+ *   - v4 Common Domain elements (process/function/service/interaction/event)
+ *     must carry an explicit `layer` field (their type no longer implies one).
+ *   - v3.2 types used under v4 are flagged as migrated/retired.
+ */
+export class ArchimateValidator {
+    /** The 11 official relationship kinds (plus the directed-association alias). */
+    static RELATIONSHIP_KINDS = [
+        'composition', 'aggregation', 'assignment', 'realization',
+        'specialization', 'access', 'serving', 'influence', 'triggering', 'flow',
+        'association', 'association-directed',
+    ];
+
+    /**
+     * Allow-rule matrix, for element types the specification's table does not
+     * cover (custom and IT types; see specificationKinds). Each rule describes
+     * when a given set of relationship kinds is valid between a source and target. The first matching rule wins;
+     * if no rule matches, the relationship is flagged as a warning.
+     * Association is the final, permissive fallback. A rule may also name the
+     * element types it applies to (`fromTypes`, `toTypes`) when the standard
+     * allows a pairing for those types only.
+     */
+    static RULES = [
+        // Structural: whole-part, same-aspect, same-layer preferred.
+        {
+            kinds: ['composition', 'aggregation'],
+            sameAspect: true,
+            sameLayer: true,
+            message: 'Composition and aggregation are normally used between elements of the same aspect and layer',
+        },
+        // Assignment between named active-structure types: "a business actor may
+        // be assigned to one or more business roles" (ArchiMate 3.2, 8.2.1; also 4).
+        {
+            kinds: ['assignment'],
+            fromTypes: ['business-actor'],
+            toTypes: ['business-role'],
+            message: 'A business actor is assigned to the business roles it fulfils',
+        },
+        // Assignment: active structure performs/responsible for behavior or passive structure.
+        {
+            kinds: ['assignment'],
+            fromAspect: 'active-structure',
+            toAspects: ['behavior', 'passive-structure'],
+            message: 'Assignment usually goes from an active-structure element to a behavior or passive-structure element',
+        },
+        // Realization: behavior (or active structure) realizes a passive structure.
+        {
+            kinds: ['realization'],
+            fromAspects: ['behavior', 'active-structure'],
+            toAspect: 'passive-structure',
+            message: 'Realization usually goes from a behavior or active-structure element to a passive-structure element',
+        },
+        // Specialization: same aspect/layer.
+        {
+            kinds: ['specialization'],
+            sameAspect: true,
+            sameLayer: true,
+            message: 'Specialization is normally between elements of the same aspect and layer',
+        },
+        // Access: behavior reads/writes passive structure.
+        {
+            kinds: ['access'],
+            fromAspect: 'behavior',
+            toAspect: 'passive-structure',
+            message: 'Access usually goes from a behavior element to a passive-structure element',
+        },
+        // Serving: behavior serves behavior, may cross layers.
+        {
+            kinds: ['serving'],
+            fromAspect: 'behavior',
+            toAspect: 'behavior',
+            crossLayer: true,
+            message: 'Serving usually goes from one behavior element to another',
+        },
+        // Triggering: behavior triggers behavior.
+        {
+            kinds: ['triggering'],
+            fromAspects: ['behavior', 'motivation'],
+            toAspects: ['behavior', 'motivation'],
+            message: 'Triggering usually goes from one behavior or event element to another',
+        },
+        // Flow: behavior to behavior or passive structure to passive structure.
+        {
+            kinds: ['flow'],
+            sameAspect: true,
+            aspects: ['behavior', 'passive-structure'],
+            message: 'Flow is normally between behavior elements, or between passive-structure elements',
+        },
+        // Influence: very broad, but motivation elements are the natural source.
+        {
+            kinds: ['influence'],
+            message: 'Influence is broadly allowed; ensure the direction matches your intent',
+            severity: 'info',
+        },
+        // Association: permissive fallback.
+        {
+            kinds: ['association', 'association-directed'],
+            message: 'Association is the permissive fallback relationship',
+            severity: 'info',
+        },
+    ];
+
+    /**
+     * Validate a single relationship.
+     * @param {object} sourceElement
+     * @param {object} targetElement
+     * @param {string} kind
+     * @param {'3.2'|'4'} [version='4']
+     * @returns {{valid: boolean, code?: string, message?: string, severity?: string, suggestedKinds?: string[]}}
+     */
+    static validateRelationship(sourceElement, targetElement, kind, version = '4') {
+        const source = this._resolve(sourceElement, version);
+        const target = this._resolve(targetElement, version);
+        const normalizedKind = kind || 'association';
+
+        // Unknown kind is itself a warning (fall back to association notation).
+        if (!this.RELATIONSHIP_KINDS.includes(normalizedKind)) {
+            return {
+                valid: false,
+                code: 'unknown-kind',
+                message: `Unknown relationship kind "${normalizedKind}"; falling back to association`,
+                severity: 'warning',
+                suggestedKinds: ['association'],
+            };
+        }
+
+        // Custom/unofficial types on both ends are allowed any relationship so
+        // validation stays helpful without punishing informal extensions.
+        if (source.isCustom && target.isCustom) {
+            return { valid: true };
+        }
+
+        // Two ArchiMate types: the specification's own table decides.
+        const allowed = this.specificationKinds(sourceElement, targetElement);
+        if (allowed) {
+            if (allowed.has(normalizedKind)) return { valid: true };
+            const suggested = this.RELATIONSHIP_KINDS.filter(k => allowed.has(k));
+            return {
+                valid: false,
+                code: 'not-in-specification',
+                message: `ArchiMate ${RELATIONSHIP_TABLE_VERSION} does not allow ${normalizedKind} from ${archimate32Type(sourceElement)} to ${archimate32Type(targetElement)}`,
+                severity: 'warning',
+                suggestedKinds: suggested.length ? suggested : ['association'],
+            };
+        }
+
+        const rule = this._matchingRule(normalizedKind, source, target);
+        if (rule) {
+            return { valid: true };
+        }
+
+        const suggested = this.allowedKinds(sourceElement, targetElement, version)
+            .filter(k => k !== normalizedKind);
+        return {
+            valid: false,
+            code: 'aspect-or-layer-mismatch',
+            message: `Relationship "${normalizedKind}" is unusual between a ${source.aspect} element and a ${target.aspect} element`,
+            severity: 'warning',
+            suggestedKinds: suggested.length ? suggested : ['association'],
+        };
+    }
+
+    /**
+     * Validate an entire model.
+     * @param {Array<object>} elements
+     * @param {Array<object>} relationships
+     * @param {'3.2'|'4'} [version='4']
+     * @returns {Array<object>} warnings, each with {type, code, message, severity, element?, relationship?, source?, target?}
+     */
+    static validateModel(elements, relationships, version = '4', viewpoint = null, customViewpoints = []) {
+        const warnings = [];
+        const byId = new Map((elements || []).map(e => [e.id, e]));
+
+        for (const element of elements || []) {
+            // Diagram annotations are not ArchiMate model elements; skip them.
+            if (element?.shape === 'note' || element?.annotation === true) continue;
+            const elementWarnings = this._validateElement(element, version);
+            for (const w of elementWarnings) {
+                warnings.push({ ...w, type: 'element', element });
+            }
+            if (viewpoint && viewpoint !== 'All') {
+                const vpWarning = ArchimateViewpoints.validateElement(element, viewpoint, version, customViewpoints);
+                if (vpWarning) {
+                    warnings.push({ type: 'element', code: 'viewpoint-mismatch', severity: 'warning', message: vpWarning, element });
+                }
+            }
+        }
+
+        for (const relationship of relationships || []) {
+            const source = byId.get(relationship.source);
+            const target = byId.get(relationship.target);
+            if (!source) {
+                warnings.push({ type: 'relationship', code: 'missing-source', relationship, severity: 'warning', message: `Relationship references missing source "${relationship.source}"` });
+                continue;
+            }
+            if (!target) {
+                warnings.push({ type: 'relationship', code: 'missing-target', relationship, severity: 'warning', message: `Relationship references missing target "${relationship.target}"` });
+                continue;
+            }
+            const result = this.validateRelationship(source, target, relationship.kind, version);
+            if (!result.valid) {
+                warnings.push({
+                    type: 'relationship',
+                    code: result.code,
+                    severity: result.severity,
+                    message: result.message,
+                    suggestedKinds: result.suggestedKinds,
+                    relationship,
+                    source,
+                    target,
+                });
+            }
+        }
+
+        return warnings;
+    }
+
+    /**
+     * Return the relationship kinds permitted between two elements.
+     * @param {object} sourceElement
+     * @param {object} targetElement
+     * @param {'3.2'|'4'} [version='4']
+     * @returns {string[]}
+     */
+    static allowedKinds(sourceElement, targetElement, version = '4') {
+        const source = this._resolve(sourceElement, version);
+        const target = this._resolve(targetElement, version);
+        if (source.isCustom && target.isCustom) {
+            return [...this.RELATIONSHIP_KINDS];
+        }
+        const allowed = this.specificationKinds(sourceElement, targetElement);
+        if (allowed) return this.RELATIONSHIP_KINDS.filter(kind => allowed.has(kind));
+        return this.RELATIONSHIP_KINDS.filter(kind => this._matchingRule(kind, source, target));
+    }
+
+    /**
+     * The relationship kinds the ArchiMate specification's relationship table
+     * (Appendix B) allows from one element to another, or null when either is
+     * not an ArchiMate type (a custom or IT type: RULES apply instead). An
+     * ArchiMate 4 type is looked up as its 3.2 type (archimate32Type). A
+     * directed association is an association.
+     * @param {object} sourceElement
+     * @param {object} targetElement
+     * @returns {Set<string>|null}
+     */
+    static specificationKinds(sourceElement, targetElement) {
+        const row = specTable().get(archimate32Type(sourceElement ?? {}));
+        const kinds = row?.get(archimate32Type(targetElement ?? {}));
+        if (!kinds) return null;
+        return kinds.has('association') ? new Set([...kinds, 'association-directed']) : kinds;
+    }
+
+    static _resolve(element, version) {
+        const typeName = element?.type;
+        // A 3.2 type retired in 4 keeps its 3.2 layer and aspect, so its relationships
+        // are still checked; _validateElement flags the retirement itself.
+        const type = typeof typeName === 'string'
+            ? (ArchimateNotation.elementType(typeName, version)
+                || ArchimateNotation.elementType(typeName, '3.2')
+                || ITIconNotation.elementType(typeName))
+            : undefined;
+        const layerName = element?.layer
+            ? element.layer
+            : (type?.layer?.name || ArchimateNotation.elementLayer(element, version));
+        const aspect = type?.aspect || element?.aspect || 'other';
+        return {
+            type: typeName,
+            resolvedType: type,
+            layer: layerName,
+            aspect,
+            isCustom: !type,
+            isCommonDomain: type && type.layer === null && !element?.layer,
+        };
+    }
+
+    static _validateElement(element, version) {
+        const warnings = [];
+        const type = typeof element?.type === 'string' ? ArchimateNotation.elementType(element.type, version) : undefined;
+
+        if (!type && element?.type && !ArchimateNotation.elementType(element.type, '3.2')) {
+            // Custom types are allowed; no warning. (A 3.2 type under 4 is retired, not custom.)
+            return warnings;
+        }
+
+        if (version === '4' && type?.layer === null && !element?.layer) {
+            warnings.push({
+                code: 'common-domain-missing-layer',
+                severity: 'warning',
+                message: `Element "${element.name || element.id}" is a Common Domain type (${element.type}) and needs an explicit layer in ArchiMate 4`,
+            });
+        }
+
+        if (version === '4' && ArchimateNotation.elementType(element?.type, '3.2') && !ArchimateNotation.elementType(element?.type, '4')) {
+            warnings.push({
+                code: 'retired-type-in-v4',
+                severity: 'warning',
+                message: `Element type "${element.type}" is retired in ArchiMate 4; use migrateElementToV4() or switch to archimateVersion:"3.2"`,
+            });
+        }
+
+        return warnings;
+    }
+
+    static _matchingRule(kind, source, target) {
+        for (const rule of this.RULES) {
+            if (!rule.kinds.includes(kind)) continue;
+
+            const sourceAspects = rule.fromAspects || (rule.fromAspect ? [rule.fromAspect] : undefined);
+            const targetAspects = rule.toAspects || (rule.toAspect ? [rule.toAspect] : undefined);
+            const allAspects = rule.aspects;
+
+            if (rule.fromTypes && !rule.fromTypes.includes(source.type)) continue;
+            if (rule.toTypes && !rule.toTypes.includes(target.type)) continue;
+            if (sourceAspects && !sourceAspects.includes(source.aspect)) continue;
+            if (targetAspects && !targetAspects.includes(target.aspect)) continue;
+            if (allAspects && (!allAspects.includes(source.aspect) || !allAspects.includes(target.aspect))) continue;
+
+            if (rule.sameAspect && source.aspect !== target.aspect) continue;
+            if (rule.sameLayer && source.layer !== target.layer) continue;
+            if (rule.crossLayer === false && source.layer !== target.layer) continue;
+
+            if (rule.fromLayer && rule.fromLayer !== source.layer) continue;
+            if (rule.toLayer && rule.toLayer !== target.layer) continue;
+
+            return rule;
+        }
+        return null;
+    }
+}