dsh-model-everything 0.0.0-stage → 0.2.0

package/lib/structure.js

@@ -0,0 +1,711 @@
+import { createHash } from 'node:crypto';
+/**
+ * Structure-diagram review: a dependency graph is not a state machine.
+ *
+ * The state-machine front end (`uml.ts`) reads a component, package, class or
+ * deployment diagram as a *by-product* and says so (`UML_NOT_A_STATE_DIAGRAM`).
+ * This module reads the same text as what it actually is — a directed graph of
+ * nodes and dependency edges — and audits it against a declared dependency matrix.
+ *
+ * The checks are the structural ones a reader performs by eye and gets wrong:
+ * an isolated node nobody notices, an arrow whose endpoint was never declared, a
+ * dependency cycle, an edge that violates the allowed-dependency matrix, a child
+ * depending on its parent, and an edge the matrix says must exist but the diagram
+ * does not draw. Every finding names the rule id it hit, so the diagram and the
+ * source-side checker can be reconciled rule by rule.
+ *
+ * @module model-everything-structure
+ */
+import { REPORT_SCHEMAS, canonicalJson, verdictOfFindings } from './engine.js';
+const CONSTRUCT_KIND = {
+    component: 'component',
+    class: 'class',
+    interface: 'interface',
+    abstract: 'class',
+    enum: 'class',
+    object: 'component',
+    actor: 'actor',
+    usecase: 'component',
+    database: 'database',
+    node: 'node',
+    artifact: 'node',
+    deployment: 'node',
+    rectangle: 'rectangle',
+    folder: 'package',
+    frame: 'rectangle',
+    cloud: 'cloud',
+    queue: 'queue',
+    stack: 'queue',
+    storage: 'database',
+    collections: 'queue',
+    agent: 'component',
+    boundary: 'component',
+    control: 'component',
+    entity: 'component',
+    package: 'package',
+    namespace: 'package',
+    module: 'package',
+    componentDiagram: 'component',
+};
+const CONTAINER_KINDS = new Set(['package']);
+/** Constructs that declare a node in a PlantUML structure diagram. */
+const DECLARATION = /^\s*(component|componentDiagram|class|abstract|interface|enum|object|actor|usecase|database|node|artifact|deployment|rectangle|folder|frame|cloud|queue|stack|storage|collections|agent|boundary|control|entity|package|namespace|module)\b\s*(.*)$/i;
+/** PlantUML arrow forms used between structure nodes. */
+const PLANTUML_EDGE = /^\s*(.+?)\s*(-->|->|\.\.>|--|==>|<--|<\.\.)\s*(.+?)\s*$/;
+/** Mermaid class-diagram edge forms: `A --> B : label`, `A ..|> B`, `A -- B`. */
+const MERMAID_CLASS_EDGE = /^\s*(.+?)\s*(-->|\.\.>|--\|>|\.\.\|>|--|\.\.)\s*(.+?)\s*$/;
+const MERMAID_CLASS_DECLARATION = /^\s*class\s+([A-Za-z_][A-Za-z0-9_.-]*)\s*(?:\["([^"]*)"\])?\s*$/;
+const MERMAID_CLASS_MEMBER = /^\s*([A-Za-z_][A-Za-z0-9_.-]*)\s*(?::|\{)/;
+/**
+ * Parse a structure diagram (PlantUML component/package/class/deployment, Mermaid
+ * class diagram) into nodes and dependency edges.
+ *
+ * A structure diagram is *not* refused here: refusing is the state-machine front
+ * end's job (`parseUml`). This parser is the honest reading of the same text.
+ */
+export function parseStructure(text, notation = 'auto') {
+    const resolved = notation === 'auto' ? detectStructureNotation(text) : notation;
+    return resolved === 'mermaid' ? parseMermaidClass(text) : parsePlantUmlStructure(text);
+}
+function detectStructureNotation(text) {
+    if (/^\s*@start/m.test(text))
+        return 'plantuml';
+    if (/^\s*classDiagram\b/m.test(text))
+        return 'mermaid';
+    if (/^\s*(component|package|deployment)\b/im.test(text))
+        return 'plantuml';
+    return 'plantuml';
+}
+/** Read `X as Y`, `"X" as Y`, `[X] as Y`, `X` → the node id (and its display label). */
+function readDeclarationTarget(rest) {
+    const trimmed = rest.trim().replace(/[;{]\s*$/, '').trim();
+    if (trimmed === '')
+        return {};
+    const aliased = /^(.*?)\s+as\s+([A-Za-z_][A-Za-z0-9_.-]*)\s*$/.exec(trimmed);
+    if (aliased !== null)
+        return { id: aliased[2], label: cleanLabel(aliased[1]) };
+    const bare = /^([A-Za-z_][A-Za-z0-9_.-]*)\s*$/.exec(trimmed);
+    if (bare !== null)
+        return { id: bare[1] };
+    const quoted = /^"([^"]+)"\s*$/.exec(trimmed);
+    if (quoted !== null)
+        return { id: quoted[1], label: quoted[1] };
+    // `[Order Service]` and other bracketed spellings become their own id when nothing
+    // else is available: an unnamed node still has to appear in the graph.
+    const bracketed = /^\[([^\]]+)\]\s*$/.exec(trimmed);
+    if (bracketed !== null)
+        return { id: bracketed[1].trim(), label: bracketed[1].trim() };
+    return { label: cleanLabel(trimmed) };
+}
+function cleanLabel(value) {
+    const trimmed = value.trim().replace(/^\[|\]$/g, '').replace(/^"|"$/g, '').trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/** Strip a trailing `: label` from an edge target and return both halves. */
+function splitEdgeTarget(text) {
+    const colon = text.indexOf(':');
+    if (colon < 0)
+        return { id: text.trim() };
+    return { id: text.slice(0, colon).trim(), label: text.slice(colon + 1).trim() };
+}
+function nodeIdFromReference(reference) {
+    const trimmed = reference.trim();
+    const quoted = /^"([^"]+)"$/.exec(trimmed);
+    if (quoted !== null)
+        return quoted[1];
+    const bracketed = /^\[([^\]]+)\]$/.exec(trimmed);
+    if (bracketed !== null)
+        return bracketed[1].trim();
+    return trimmed.replace(/^"|"$/g, '');
+}
+function declareNode(builder, id, kind, line, label) {
+    const existing = builder.nodes.get(id);
+    const container = CONTAINER_KINDS.has(kind);
+    if (existing === undefined) {
+        builder.nodes.set(id, {
+            id,
+            kind,
+            container,
+            line,
+            declared: true,
+            ...(label === undefined ? {} : { label }),
+            ...(builder.stack.length === 0 ? {} : { parent: builder.stack[builder.stack.length - 1] }),
+        });
+        return;
+    }
+    // A second declaration upgrades an implicitly-created node and keeps the first line.
+    existing.declared = true;
+    existing.kind = kind;
+    existing.container = container;
+    if (label !== undefined && existing.label === undefined)
+        existing.label = label;
+    if (existing.line === undefined)
+        existing.line = line;
+}
+/** A node that only an edge mentioned: kept, and reported as dangling (UML021). */
+function referenceNode(builder, id, line) {
+    if (builder.nodes.has(id))
+        return;
+    builder.nodes.set(id, {
+        id,
+        kind: 'unknown',
+        container: false,
+        line,
+        declared: false,
+        ...(builder.stack.length === 0 ? {} : { parent: builder.stack[builder.stack.length - 1] }),
+    });
+}
+function parsePlantUmlStructure(text) {
+    const builder = { nodes: new Map(), edges: [], warnings: [], stack: [] };
+    const lines = text.split(/\r?\n/);
+    let inNote = false;
+    lines.forEach((rawLine, index) => {
+        const lineNumber = index + 1;
+        const line = rawLine.trim();
+        if (line === '')
+            return;
+        if (/^@start|^@end/.test(line))
+            return;
+        if (/^'/i.test(line) || /^\/\//.test(line))
+            return;
+        const noteStart = /^note\b/i.test(line);
+        const noteEnd = /^end\s*note$/i.test(line);
+        if (noteEnd) {
+            inNote = false;
+            return;
+        }
+        if (inNote)
+            return;
+        if (noteStart && !/:\s*.+$/.test(line)) {
+            inNote = true;
+            return;
+        }
+        if (noteStart)
+            return;
+        if (/^skinparam\b|^scale\b|^title\b|^hide\b|^left to right direction|^top to bottom direction|^!theme|^legend\b|^end legend$/i.test(line))
+            return;
+        if (/^\/'/.test(line) || /^'/i.test(line))
+            return;
+        if (line === '}') {
+            builder.stack.pop();
+            return;
+        }
+        const declaration = DECLARATION.exec(line);
+        if (declaration !== null) {
+            const kind = CONSTRUCT_KIND[declaration[1].toLowerCase()] ?? 'unknown';
+            const target = readDeclarationTarget(declaration[2]);
+            const id = target.id ?? declaration[2].trim();
+            if (id !== '') {
+                declareNode(builder, id, kind, lineNumber, target.label);
+                if (line.endsWith('{'))
+                    builder.stack.push(id);
+            }
+            return;
+        }
+        const edge = PLANTUML_EDGE.exec(line);
+        if (edge !== null) {
+            const from = nodeIdFromReference(edge[1]);
+            const target = splitEdgeTarget(edge[3]);
+            const to = nodeIdFromReference(target.id);
+            if (from === '' || to === '')
+                return;
+            referenceNode(builder, from, lineNumber);
+            referenceNode(builder, to, lineNumber);
+            builder.edges.push({ from, to, line: lineNumber, ...(target.label === undefined ? {} : { label: target.label }) });
+            return;
+        }
+        builder.warnings.push('STRUCTURE_IGNORED_LINE: "' + line + '" is not a component, package, class or edge statement; it was ignored.');
+    });
+    return { notation: 'plantuml', nodes: [...builder.nodes.values()], edges: builder.edges, warnings: builder.warnings };
+}
+function parseMermaidClass(text) {
+    const builder = { nodes: new Map(), edges: [], warnings: [], stack: [] };
+    const lines = text.split(/\r?\n/);
+    for (const [index, rawLine] of lines.entries()) {
+        const lineNumber = index + 1;
+        const line = rawLine.trim();
+        if (line === '' || /^classDiagram\b/.test(line) || /^%%/.test(line))
+            continue;
+        if (line === '}') {
+            builder.stack.pop();
+            continue;
+        }
+        const declaration = MERMAID_CLASS_DECLARATION.exec(line);
+        if (declaration !== null) {
+            declareNode(builder, declaration[1], 'class', lineNumber, declaration[2]);
+            continue;
+        }
+        // `class OrderService { ... }` opens a member block; members are not dependency nodes.
+        const block = /^class\s+([A-Za-z_][A-Za-z0-9_.-]*)\s*\{$/.exec(line);
+        if (block !== null) {
+            declareNode(builder, block[1], 'class', lineNumber);
+            builder.stack.push(block[1]);
+            continue;
+        }
+        const edge = MERMAID_CLASS_EDGE.exec(line);
+        if (edge !== null) {
+            const from = nodeIdFromReference(edge[1]);
+            const target = splitEdgeTarget(edge[3]);
+            const to = nodeIdFromReference(target.id);
+            if (from === '' || to === '')
+                continue;
+            referenceNode(builder, from, lineNumber);
+            referenceNode(builder, to, lineNumber);
+            builder.edges.push({ from, to, line: lineNumber, ...(target.label === undefined ? {} : { label: target.label }) });
+            continue;
+        }
+        if (builder.stack.length > 0)
+            continue; // a member line inside `class X { ... }`
+        if (MERMAID_CLASS_MEMBER.test(line)) {
+            // `Service : +read()` declares a node with a member description.
+            const id = MERMAID_CLASS_MEMBER.exec(line)[1];
+            declareNode(builder, id, 'class', lineNumber);
+            continue;
+        }
+        builder.warnings.push('STRUCTURE_IGNORED_LINE: "' + line + '" is not a class or edge statement; it was ignored.');
+    }
+    return { notation: 'mermaid', nodes: [...builder.nodes.values()], edges: builder.edges, warnings: builder.warnings };
+}
+// ---------------------------------------------------------------------------
+// Dependency matrix
+// ---------------------------------------------------------------------------
+/** `*` matches any run of characters, `?` exactly one. Ids keep their own punctuation. */
+export function globMatches(pattern, value) {
+    if (pattern === value)
+        return true;
+    if (!pattern.includes('*') && !pattern.includes('?'))
+        return false;
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.');
+    return new RegExp('^' + escaped + '$').test(value);
+}
+function matchesAny(patterns, value) {
+    if (patterns === undefined)
+        return undefined;
+    return patterns.find((pattern) => globMatches(pattern, value));
+}
+export function validateMatrix(input) {
+    const errors = [];
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        return { ok: false, errors: ['matrix: must be an object'] };
+    }
+    const root = input;
+    const allowed = new Set(['rules', 'layers', 'default']);
+    for (const key of Object.keys(root)) {
+        if (!allowed.has(key))
+            errors.push('matrix.' + key + ': unknown field (allowed: rules, layers, default)');
+    }
+    if (root.default !== undefined && root.default !== 'allow' && root.default !== 'deny') {
+        errors.push("matrix.default: must be 'allow' or 'deny'");
+    }
+    if (root.rules !== undefined) {
+        if (!Array.isArray(root.rules))
+            errors.push('matrix.rules: must be an array');
+        else {
+            const seen = new Set();
+            root.rules.forEach((entry, index) => {
+                const path = 'matrix.rules[' + String(index) + ']';
+                if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+                    errors.push(path + ': must be an object');
+                    return;
+                }
+                const rule = entry;
+                for (const key of Object.keys(rule)) {
+                    if (!['id', 'source', 'allow', 'deny', 'require'].includes(key))
+                        errors.push(path + '.' + key + ': unknown field (allowed: id, source, allow, deny, require)');
+                }
+                if (typeof rule.id !== 'string' || rule.id === '')
+                    errors.push(path + '.id: must be a non-empty string');
+                else if (seen.has(rule.id))
+                    errors.push(path + '.id: duplicate rule id ' + rule.id);
+                else
+                    seen.add(rule.id);
+                if (rule.source !== undefined && typeof rule.source !== 'string')
+                    errors.push(path + '.source: must be a string');
+                for (const list of ['allow', 'deny']) {
+                    if (rule[list] === undefined)
+                        continue;
+                    if (!Array.isArray(rule[list]) || rule[list].length === 0)
+                        errors.push(path + '.' + list + ': must be a non-empty array');
+                    else if (rule[list].some((value) => typeof value !== 'string' || value === ''))
+                        errors.push(path + '.' + list + ': every entry must be a non-empty string');
+                }
+                if (rule.require !== undefined && typeof rule.require !== 'boolean')
+                    errors.push(path + '.require: must be a boolean');
+                if (rule.require === true && rule.allow === undefined)
+                    errors.push(path + '.require: needs `allow` to say which edges must exist');
+            });
+        }
+    }
+    if (root.layers !== undefined) {
+        if (!Array.isArray(root.layers))
+            errors.push('matrix.layers: must be an array');
+        else {
+            root.layers.forEach((entry, index) => {
+                const path = 'matrix.layers[' + String(index) + ']';
+                if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+                    errors.push(path + ': must be an object');
+                    return;
+                }
+                const layer = entry;
+                for (const key of Object.keys(layer)) {
+                    if (!['name', 'members'].includes(key))
+                        errors.push(path + '.' + key + ': unknown field (allowed: name, members)');
+                }
+                if (typeof layer.name !== 'string' || layer.name === '')
+                    errors.push(path + '.name: must be a non-empty string');
+                if (!Array.isArray(layer.members) || layer.members.length === 0)
+                    errors.push(path + '.members: must be a non-empty array');
+                else if (layer.members.some((value) => typeof value !== 'string' || value === ''))
+                    errors.push(path + '.members: every entry must be a non-empty string');
+            });
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, matrix: root };
+}
+/** The layer index of a node id, or undefined when no layer claims it. */
+function layerOf(layers, id) {
+    for (const [index, layer] of layers.entries()) {
+        if (matchesAny(layer.members, id) !== undefined)
+            return index;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Checks
+// ---------------------------------------------------------------------------
+/** Shortest directed cycle through the graph, as a node path with the start repeated. */
+export function shortestCycle(nodes, edges) {
+    const adjacency = new Map();
+    for (const node of nodes)
+        adjacency.set(node, []);
+    for (const edge of edges) {
+        if (edge.from === edge.to)
+            return [edge.from, edge.from];
+        const list = adjacency.get(edge.from);
+        if (list !== undefined && !list.includes(edge.to))
+            list.push(edge.to);
+    }
+    let best;
+    for (const start of nodes) {
+        // BFS from `start` back to `start`; the first hit is the shortest cycle through it.
+        const previous = new Map();
+        const queue = [start];
+        const seen = new Set([start]);
+        let found = false;
+        while (queue.length > 0 && !found) {
+            const current = queue.shift();
+            for (const next of adjacency.get(current) ?? []) {
+                if (next === start) {
+                    // `previous` holds back-pointers from `start`, so walk them to `current`,
+                    // reverse into forward order, then close the loop.
+                    const chain = [];
+                    let cursor = current;
+                    while (cursor !== start) {
+                        chain.push(cursor);
+                        cursor = previous.get(cursor);
+                    }
+                    const path = [start, ...chain.reverse(), start];
+                    if (best === undefined || path.length < best.length)
+                        best = path;
+                    found = true;
+                    break;
+                }
+                if (seen.has(next))
+                    continue;
+                seen.add(next);
+                previous.set(next, current);
+                queue.push(next);
+            }
+        }
+    }
+    return best;
+}
+/**
+ * Audit a structure diagram. Every check is structural: it reads the drawn graph and
+ * the declared matrix, and never claims anything about the code behind them.
+ */
+/**
+ * The diagram text, or a refusal naming what arrived instead.
+ *
+ * `reviewStructure({ diagram: 42 })` threw `text.split is not a function`, and `{}` threw a read of
+ * `undefined`. The shape of the argument is the caller's mistake, and the caller can route on a
+ * code but not on a TypeError. A raw throw is also indistinguishable, at the tool boundary, from a
+ * crash inside the engine.
+ */
+function requireDiagramText(value) {
+    if (typeof value !== 'string') {
+        const arrived = value === null ? 'null' : Array.isArray(value) ? 'an array' : typeof value;
+        throw new Error('diagram must be a string of diagram text, got ' + arrived + '. Pass the diagram source itself.');
+    }
+    return value;
+}
+export function reviewStructure(options) {
+    // Not `if (options.diagram !== undefined)`: a missing `diagram` reached the parser as `undefined`
+    // and threw a read of `split` on it - the same defect, one guard narrower.
+    requireDiagramText(options.diagram);
+    const graph = parseStructure(options.diagram, options.notation ?? 'auto');
+    const warnings = [...graph.warnings];
+    const findings = [];
+    const nodes = graph.nodes;
+    const nodeIds = nodes.map((node) => node.id);
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    if (nodes.length === 0) {
+        findings.push({
+            code: 'UML026_NO_NODES',
+            severity: 'error',
+            message: 'no node was declared in this text, so there is no structure to review.',
+            evidence: { notation: graph.notation },
+        });
+    }
+    // -- UML021 dangling references: an endpoint no declaration ever introduced -----
+    const dangling = nodes.filter((node) => !node.declared);
+    if (dangling.length > 0) {
+        findings.push({
+            code: 'UML021_DANGLING_REFERENCE',
+            severity: 'error',
+            message: String(dangling.length) + ' arrow endpoint(s) are used without ever being declared: ' + dangling.map((node) => node.id).join(', ') + '. In a component diagram this is how a dependency on a component that does not exist stays invisible.',
+            evidence: { nodes: dangling.map((node) => ({ id: node.id, line: node.line })) },
+        });
+    }
+    // -- UML020 isolated nodes: declared, but nothing depends on it and it depends on nothing --
+    const degree = new Map();
+    for (const id of nodeIds)
+        degree.set(id, 0);
+    for (const edge of graph.edges) {
+        // A container's members are not its dependencies, so only real edges count.
+        degree.set(edge.from, (degree.get(edge.from) ?? 0) + 1);
+        degree.set(edge.to, (degree.get(edge.to) ?? 0) + 1);
+    }
+    const isolated = nodes.filter((node) => !node.container && node.declared && (degree.get(node.id) ?? 0) === 0);
+    if (isolated.length > 0) {
+        findings.push({
+            code: 'UML020_ISOLATED_NODE',
+            severity: 'warning',
+            message: String(isolated.length) + ' node(s) have no edge at all: ' + isolated.map((node) => node.id).join(', ') + '. Either they are dead entries or the diagram is missing their dependencies.',
+            evidence: { nodes: isolated.map((node) => ({ id: node.id, line: node.line })) },
+        });
+    }
+    // -- UML022 cycles --------------------------------------------------------------
+    const cycle = shortestCycle(nodeIds, graph.edges);
+    if (cycle !== undefined) {
+        findings.push({
+            code: 'UML022_CYCLE',
+            severity: 'error',
+            message: 'the dependency graph has a directed cycle: ' + cycle.join(' → ') + '. A cycle means no build order and no layering can hold.',
+            path: cycle.slice(0, -1).map((from, index) => ({ from, event: 'depends-on', to: cycle[index + 1] })),
+            evidence: { cycle },
+        });
+    }
+    // -- Matrix checks: UML023 disallowed edge, UML024 layer violation, UML025 missing edge --
+    const edgeVerdicts = [];
+    let rules = [];
+    let layers = [];
+    let matrixDefault = 'allow';
+    if (options.matrix !== undefined) {
+        const validation = validateMatrix(options.matrix);
+        if (!validation.ok) {
+            const matrixFindings = validation.errors.map((message) => ({ code: 'MATRIX_INVALID', severity: 'error', message }));
+            findings.push(...matrixFindings);
+        }
+        else {
+            rules = validation.matrix.rules ?? [];
+            layers = validation.matrix.layers ?? [];
+            matrixDefault = validation.matrix.default ?? 'allow';
+            // A matrix that judges nothing, or a layer order computed over names that are not nodes.
+            //
+            // These are warnings rather than errors because the diagram is not wrong: the MATRIX is
+            // incomplete, and the report would otherwise say `verdict: 'pass'` with
+            // `summary.layerViolations: 0` - which reads as "the layering holds" when in truth no layer
+            // rule was ever consulted. A reader cannot tell an empty rule from a satisfied one.
+            //
+            // A rule whose source matches nothing is NOT reported here: `UML025_MISSING_EXPECTED_EDGE`
+            // already covers it, with `noSourceMatch` in its evidence, and `default: 'allow'` is a
+            // documented permissive mode in which an unlisted edge passing through is not a finding.
+            const nodeIds = new Set(nodes.map((node) => node.id));
+            if (rules.length === 0 && layers.length === 0) {
+                findings.push({
+                    code: 'MATRIX_JUDGES_NOTHING',
+                    severity: 'warning',
+                    message: 'the dependency matrix carries no rules and no layers, so every edge was judged by `default: ' + matrixDefault + '` alone. The matrix takes no part in this verdict.',
+                    detail: 'An empty matrix reads as a satisfied one. Either declare the rules and layers, or omit the matrix so the report does not imply a check that never ran.',
+                });
+            }
+            if (layers.length > 0) {
+                for (const layer of layers) {
+                    for (const member of layer.members) {
+                        if (nodeIds.has(member))
+                            continue;
+                        findings.push({
+                            code: 'MATRIX_LAYER_MEMBER_UNKNOWN',
+                            severity: 'warning',
+                            message: 'layer ' + layer.name + ' lists ' + JSON.stringify(member) + ', which is not a node of the diagram.',
+                            detail: 'A member that is not a node cannot break a layer order, so listing it hides the member that should have been there.',
+                        });
+                    }
+                }
+                // A node no layer claims is exempt from UML024 entirely: it has no rank to compare, so an
+                // edge through it can never be an upward edge as far as this matrix is concerned.
+                for (const node of nodes) {
+                    if (layers.some((layer) => layer.members.includes(node.id)))
+                        continue;
+                    findings.push({
+                        code: 'MATRIX_NODE_UNLAYERED',
+                        severity: 'warning',
+                        message: node.id + ' belongs to no declared layer, so every edge touching it is exempt from the layer order.',
+                        detail: 'A node with no rank cannot be compared to one, which is why the exemption exists - but it also means an edge that skips layers through this node is never reported. Add it to a layer, or remove it from the diagram.',
+                    });
+                }
+            }
+        }
+    }
+    for (const edge of graph.edges) {
+        const matchedRules = [];
+        let deniedBy;
+        let allowedBy;
+        for (const rule of rules) {
+            if (rule.source === undefined)
+                continue;
+            if (matchesAny([rule.source], edge.from) === undefined)
+                continue;
+            matchedRules.push(rule.id);
+            if (matchesAny(rule.deny, edge.to) !== undefined && deniedBy === undefined)
+                deniedBy = rule;
+            if (matchesAny(rule.allow, edge.to) !== undefined && allowedBy === undefined)
+                allowedBy = rule;
+        }
+        // Deny wins globally: a later rule's allow must not resurrect an edge an earlier
+        // rule forbade, or the matrix would depend on rule order.
+        let allowed;
+        let basis;
+        if (deniedBy !== undefined) {
+            allowed = false;
+            basis = 'deny';
+        }
+        else if (allowedBy !== undefined) {
+            allowed = true;
+            basis = 'allow';
+        }
+        else if (matrixDefault === 'deny') {
+            allowed = false;
+            basis = 'unlisted';
+        }
+        else {
+            allowed = true;
+            basis = 'default';
+        }
+        edgeVerdicts.push({ from: edge.from, to: edge.to, line: edge.line, matchedRules, allowed, basis });
+        if (!allowed) {
+            const rule = deniedBy;
+            findings.push({
+                code: 'UML023_DISALLOWED_EDGE',
+                severity: 'error',
+                message: rule === undefined
+                    ? 'edge ' + edge.from + ' → ' + edge.to + ' is not permitted: no rule allows it and the matrix default is deny.'
+                    : 'edge ' + edge.from + ' → ' + edge.to + ' violates rule ' + rule.id + (rule.deny === undefined ? '' : ' (deny ' + rule.deny.join(', ') + ')') + '.',
+                // `rule` is omitted rather than set to undefined: a tool result must stay lossless JSON.
+                evidence: { edge: { from: edge.from, to: edge.to, line: edge.line }, matchedRules, basis, ...(rule === undefined ? {} : { rule: rule.id }) },
+            });
+        }
+    }
+    // UML024: an edge from a lower layer into a higher one (a child depending on its parent).
+    const layerViolations = [];
+    if (layers.length > 0) {
+        for (const edge of graph.edges) {
+            const fromLayer = layerOf(layers, edge.from);
+            const toLayer = layerOf(layers, edge.to);
+            if (fromLayer === undefined || toLayer === undefined)
+                continue;
+            if (fromLayer > toLayer) {
+                layerViolations.push({ from: edge.from, to: edge.to, fromLayer: layers[fromLayer].name, toLayer: layers[toLayer].name, line: edge.line });
+            }
+        }
+        if (layerViolations.length > 0) {
+            findings.push({
+                code: 'UML024_LAYER_VIOLATION',
+                severity: 'error',
+                message: String(layerViolations.length) + ' edge(s) point from a lower layer into a higher one: ' + layerViolations.map((entry) => entry.from + ' (' + entry.fromLayer + ') → ' + entry.to + ' (' + entry.toLayer + ')').join('; ') + '. Declared layers allow downward dependencies only.',
+                evidence: { violations: layerViolations },
+            });
+        }
+    }
+    // UML025: an edge the matrix requires but the diagram does not draw. The check is
+    // pattern-based on purpose: a required target that the diagram does not contain at
+    // all is the strongest form of "missing", and deriving the expectation from declared
+    // nodes would hide exactly that case.
+    const missing = [];
+    for (const rule of rules) {
+        if (rule.require !== true || rule.source === undefined || rule.allow === undefined)
+            continue;
+        const sources = nodeIds.filter((id) => matchesAny([rule.source], id) !== undefined);
+        if (sources.length === 0) {
+            missing.push({ rule: rule.id, source: rule.source, expected: rule.allow, unsatisfiedFrom: [], noSourceMatch: true });
+            continue;
+        }
+        const unsatisfied = sources.filter((source) => !graph.edges.some((edge) => edge.from === source && matchesAny(rule.allow, edge.to) !== undefined));
+        if (unsatisfied.length > 0)
+            missing.push({ rule: rule.id, source: rule.source, expected: rule.allow, unsatisfiedFrom: unsatisfied, noSourceMatch: false });
+    }
+    if (missing.length > 0) {
+        findings.push({
+            code: 'UML025_MISSING_EXPECTED_EDGE',
+            severity: 'warning',
+            message: String(missing.length) + ' required edge(s) are absent from the diagram: ' + missing.map((entry) => entry.noSourceMatch
+                ? entry.rule + ' requires an edge from ' + entry.source + ' to ' + entry.expected.join(', ') + ', but no node matches ' + entry.source
+                : entry.rule + ' requires an edge from ' + entry.unsatisfiedFrom.join(', ') + ' to ' + entry.expected.join(', ') + ', and the diagram draws none').join('; ') + '. The matrix and the diagram disagree.',
+            evidence: { missing },
+        });
+    }
+    const errors = findings.filter((finding) => finding.severity === 'error').length;
+    const warningCount = findings.filter((finding) => finding.severity === 'warning').length;
+    const summary = {
+        nodes: nodes.length,
+        edges: graph.edges.length,
+        containers: nodes.filter((node) => node.container).length,
+        isolated: isolated.length,
+        dangling: dangling.length,
+        cycles: cycle === undefined ? 0 : 1,
+        disallowedEdges: edgeVerdicts.filter((verdict) => !verdict.allowed).length,
+        layerViolations: layerViolations.length,
+        missingExpectedEdges: missing.length,
+        errors,
+        warnings: warningCount,
+        rules: rules.length,
+    };
+    const nextSteps = [];
+    if (errors > 0)
+        nextSteps.push('Resolve the error findings first: a dangling endpoint or a layer violation means the diagram and the intended architecture disagree.');
+    if (rules.length === 0)
+        nextSteps.push('Supply a dependency matrix (rules/layers) to have every edge judged and named; without one only the structural checks run.');
+    nextSteps.push('Reconcile the result with the source-side checker: this audits the diagram, an include/graph scan audits the code, and the difference between them is the finding worth chasing.');
+    if (graph.notation === 'plantuml')
+        nextSteps.push('State machines are a different question — for a state or activity diagram use uml action=review and model_verify.');
+    return {
+        ok: true,
+        ran: true,
+        ...verdictOfFindings(findings),
+        schema: REPORT_SCHEMAS.structure,
+        notation: graph.notation,
+        graph,
+        ...(options.matrix === undefined ? {} : { edgeVerdicts }),
+        findings,
+        summary,
+        hashes: {
+            diagram: createHash('sha256').update(options.diagram).digest('hex'),
+            ...(options.matrix === undefined ? {} : { matrix: createHash('sha256').update(canonicalJson(options.matrix)).digest('hex') }),
+        },
+        warnings,
+        nextSteps,
+    };
+}
+/** The finding codes this module can emit, for documentation and tests. */
+export const STRUCTURE_FINDING_CODES = [
+    'UML020_ISOLATED_NODE',
+    'UML021_DANGLING_REFERENCE',
+    'UML022_CYCLE',
+    'UML023_DISALLOWED_EDGE',
+    'UML024_LAYER_VIOLATION',
+    'UML025_MISSING_EXPECTED_EDGE',
+    'UML026_NO_NODES',
+];