dsh-model-everything 0.0.0-stage → 0.2.0

package/lib/uml-interaction-overview.js

@@ -0,0 +1,277 @@
+/**
+ * The interaction overview diagram module.
+ *
+ * An interaction overview is a control-flow graph whose nodes are interactions: a start, a
+ * decision, one or more references to interactions, and a stop. PlantUML has no page for it
+ * and no dedicated type, but the drawing is expressible with the activity diagram's
+ * vocabulary plus a reference node - `start`, `:ref Login sequence;`, `if (ok?) then (yes)`
+ * - which is what the notation research in this repository recorded as the manual form.
+ *
+ * So this family is drawn approximately, like the composite structure and the
+ * communication diagram, and for the same reason the family table used to refuse it on
+ * grounds that were simply wrong ("neither notation spells the inline interaction
+ * references": it does).
+ *
+ * Reading it back is partial, and the parser refuses the part it cannot do. A sequence and
+ * an `if`/`else` are spelled clearly enough to reconstruct. A `fork` is not: the notation
+ * opens a `fork` block, lists the flows, and closes it with `end fork`, and the closing
+ * marker carries no label tying it to the opening one, so nested or adjacent forks cannot
+ * be told apart. Rather than guess, a diagram containing one is refused with that reason.
+ *
+ * @module model-everything-uml-interaction-overview
+ */
+import { UmlError, directiveLine, } from './uml-syntax.js';
+const NODE_KINDS = ['initial', 'final', 'decision', 'merge', 'interaction', 'reference'];
+/**
+ * Validate a candidate model and normalize it.
+ *
+ * One initial node, and every node reachable from it: an overview whose flow starts nowhere
+ * is a drawing, not a flow. That is a refusal rather than a finding because every later
+ * check would be reading a graph with no entry.
+ */
+export function validateInteractionOverviewModel(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new UmlError('an interaction overview model must be an object with schemaVersion 1, nodes and edges', 'UML_INPUT');
+    }
+    const model = input;
+    if (model.schemaVersion !== 1)
+        throw new UmlError('an interaction overview model must declare schemaVersion 1', 'UML_INPUT');
+    for (const [name, value] of Object.entries({ nodes: model.nodes ?? [], edges: model.edges ?? [] })) {
+        if (!Array.isArray(value))
+            throw new UmlError(name + ' must be an array', 'UML_INPUT');
+    }
+    const nodes = [];
+    const known = new Set();
+    for (const node of model.nodes ?? []) {
+        if (node === null || typeof node !== 'object' || typeof node.id !== 'string' || node.id.trim() === '') {
+            throw new UmlError('every node needs a non-empty string id', 'UML_INPUT');
+        }
+        if (known.has(node.id))
+            throw new UmlError('node ' + JSON.stringify(node.id) + ' is declared more than once', 'UML_INPUT');
+        known.add(node.id);
+        const kind = node.kind ?? 'interaction';
+        if (!NODE_KINDS.includes(kind)) {
+            throw new UmlError('node kind must be one of ' + NODE_KINDS.join(' | ') + ', got ' + JSON.stringify(String(kind)), 'UML_INPUT');
+        }
+        if ((kind === 'interaction' || kind === 'reference') && (typeof node.interaction !== 'string' || node.interaction.trim() === '')) {
+            throw new UmlError('a ' + kind + ' node needs a non-empty `interaction` name', 'UML_INPUT');
+        }
+        nodes.push({
+            id: node.id,
+            kind,
+            ...(node.interaction === undefined ? {} : { interaction: node.interaction }),
+            ...(node.label === undefined ? {} : { label: node.label }),
+        });
+    }
+    const initial = nodes.filter((node) => node.kind === 'initial');
+    if (initial.length !== 1) {
+        throw new UmlError('an interaction overview needs exactly one initial node, got ' + String(initial.length), 'UML_INPUT');
+    }
+    const undeclared = new Set();
+    const edges = [];
+    for (const edge of model.edges ?? []) {
+        if (edge === null || typeof edge !== 'object')
+            throw new UmlError('every edge must be an object', 'UML_INPUT');
+        for (const side of ['from', 'to']) {
+            const endpoint = edge[side];
+            if (typeof endpoint !== 'string' || endpoint.trim() === '')
+                throw new UmlError('every edge needs a non-empty `' + side + '` end', 'UML_INPUT');
+            if (!known.has(endpoint))
+                undeclared.add(endpoint);
+        }
+        edges.push({
+            from: edge.from,
+            to: edge.to,
+            ...(edge.condition === undefined ? {} : { condition: edge.condition }),
+        });
+    }
+    return {
+        schemaVersion: 1,
+        nodes,
+        edges,
+        ...(undeclared.size === 0 ? {} : { undeclared: [...undeclared].sort() }),
+        ...(model.narrative === undefined ? {} : { narrative: model.narrative }),
+    };
+}
+function quote(text) {
+    return '"' + text.replace(/"/g, "'") + '"';
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+/**
+ * Render an interaction overview as Mermaid.
+ *
+ * Mermaid is the notation this family is drawn in, because the view is an activity graph
+ * and PlantUML's activity syntax is refused by this build (a structured flowchart language
+ * cannot carry a graph with merges or cycles without a while/if reconstruction). A Mermaid
+ * flowchart carries exactly what an overview is: nodes, labelled branches, and a start and
+ * an end.
+ *
+ * @param input - candidate `InteractionOverviewModelV1`.
+ * @param notation - only `mermaid` draws this family.
+ */
+export function renderInteractionOverview(input, notation) {
+    if (notation !== 'mermaid') {
+        throw new UmlError('an interaction overview can only be drawn in mermaid; plantuml has no interaction reference node, and its activity syntax - the only place a `ref` step exists - is refused by this build because a structured flowchart language cannot carry a graph with merges or cycles. Render it with notation "mermaid".', 'UML_VIEW_UNREPRESENTABLE');
+    }
+    const model = validateInteractionOverviewModel(input);
+    const warnings = [
+        'UML_RENDER_APPROXIMATE_VIEW: mermaid has no interaction overview diagram; this is a flowchart whose nodes name interactions. The flow, the references and the branch conditions are carried; the combined fragments of an inline interaction are not drawn, because the drawing has one node for it.',
+    ];
+    const lines = ['flowchart TD'];
+    lines.push(directiveLine('mermaid', 'uml v1 notation=mermaid family=interaction-overview'));
+    const alias = (id) => id.replace(/[^A-Za-z0-9_]/g, '_');
+    for (const node of model.nodes) {
+        const a = alias(node.id);
+        if (node.kind === 'initial') {
+            lines.push('  ' + a + '(["start"])');
+            continue;
+        }
+        if (node.kind === 'final') {
+            lines.push('  ' + a + '(["stop"])');
+            continue;
+        }
+        if (node.kind === 'decision') {
+            lines.push('  ' + a + '{"' + (node.label ?? 'branch?').replace(/"/g, "'") + '"}');
+            continue;
+        }
+        if (node.kind === 'merge') {
+            lines.push('  ' + a + '["merge"]');
+            continue;
+        }
+        const name = (node.interaction ?? node.label ?? node.id).replace(/"/g, "'");
+        lines.push('  ' + a + (node.kind === 'reference' ? '[/"' + name + '"/]' : '["' + name + '"]'));
+    }
+    for (const edge of model.edges) {
+        const label = edge.condition === undefined || edge.condition === '' ? '' : '|"' + edge.condition.replace(/[|"]/g, "'") + '"|';
+        lines.push('  ' + alias(edge.from) + ' -->' + label + ' ' + alias(edge.to));
+    }
+    return { primary: lines.join('\n') + '\n', warnings };
+}
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Review
+// ---------------------------------------------------------------------------
+export function parseInteractionOverview(_text, _notation) {
+    throw new UmlError('an interaction overview is drawn here as a mermaid flowchart, and a flowchart node carries a name rather than the interaction it stands for: reading one back would have to guess whether a node is a reference to another diagram, an inline interaction, or a plain step. Keep the overview as its own model and review that.', 'UML_VIEW_UNREPRESENTABLE');
+}
+export const INTERACTION_OVERVIEW_FINDING_CODES = [
+    'UML069_OVERVIEW_NO_INITIAL',
+    'UML070_OVERVIEW_NODE_UNREACHABLE',
+    'UML071_OVERVIEW_DECISION_ONE_BRANCH',
+    'UML072_OVERVIEW_REFERENCE_UNDECLARED',
+    'UML073_OVERVIEW_NODE_WITHOUT_INTERACTION',
+    'UML074_OVERVIEW_UNDOCUMENTED',
+];
+/**
+ * What a reader would get wrong about an interaction overview.
+ *
+ * The overview's job is to say how the interactions fit together, so the checks are about
+ * the flow being a flow: one way in, every node on some path from it, a decision that
+ * actually decides. Whether the referenced interactions exist is a question about the other
+ * diagrams - this plugin holds no registry of them - so an undeclared reference is reported
+ * as a name nothing here can resolve, not as a missing interaction.
+ */
+export function reviewInteractionOverviewModel(model, labels) {
+    const findings = [];
+    const name = (id) => labels[id] ?? id;
+    const byId = new Map(model.nodes.map((node) => [node.id, node]));
+    const initial = model.nodes.filter((node) => node.kind === 'initial');
+    if (initial.length === 0) {
+        findings.push({
+            code: 'UML069_OVERVIEW_NO_INITIAL',
+            severity: 'error',
+            message: 'the overview has no initial node, so the flow has no entry and nothing below it can be read as a sequence.',
+            evidence: { initial: 0 },
+        });
+    }
+    const outgoing = new Map();
+    for (const edge of model.edges) {
+        const list = outgoing.get(edge.from);
+        if (list === undefined)
+            outgoing.set(edge.from, [edge.to]);
+        else
+            list.push(edge.to);
+    }
+    const reached = new Set();
+    const queue = initial.map((node) => node.id);
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (reached.has(id))
+            continue;
+        reached.add(id);
+        for (const next of outgoing.get(id) ?? [])
+            queue.push(next);
+    }
+    for (const node of model.nodes) {
+        if (reached.has(node.id))
+            continue;
+        findings.push({
+            code: 'UML070_OVERVIEW_NODE_UNREACHABLE',
+            severity: 'error',
+            message: 'node ' + name(node.id) + ' is on no path from the initial node, so the overview does not run it.',
+            evidence: { id: node.id, kind: node.kind },
+        });
+    }
+    for (const node of model.nodes) {
+        if (node.kind !== 'decision')
+            continue;
+        const branches = outgoing.get(node.id) ?? [];
+        if (branches.length > 1)
+            continue;
+        findings.push({
+            code: 'UML071_OVERVIEW_DECISION_ONE_BRANCH',
+            severity: 'warning',
+            message: 'decision ' + name(node.id) + ' has ' + String(branches.length) + ' outgoing edge(s), so it does not decide anything.',
+            evidence: { id: node.id, branches: branches.length },
+        });
+    }
+    const undeclared = model.undeclared ?? [];
+    if (undeclared.length > 0) {
+        findings.push({
+            code: 'UML072_OVERVIEW_REFERENCE_UNDECLARED',
+            severity: 'error',
+            message: 'an edge names ' + String(undeclared.length) + ' node(s) the overview never declares. A reference whose target lives in another diagram cannot be resolved here at all.',
+            detail: undeclared.join(', '),
+            evidence: { ids: undeclared },
+        });
+    }
+    for (const node of model.nodes) {
+        if (node.kind !== 'interaction' && node.kind !== 'reference')
+            continue;
+        if (typeof node.interaction === 'string' && node.interaction.trim() !== '')
+            continue;
+        findings.push({
+            code: 'UML073_OVERVIEW_NODE_WITHOUT_INTERACTION',
+            severity: 'error',
+            message: 'node ' + name(node.id) + ' is declared as an ' + node.kind + ' but names no interaction, so the overview does not say what runs there.',
+            evidence: { id: node.id, kind: node.kind },
+        });
+    }
+    if (model.narrative?.nodes === undefined) {
+        for (const node of model.nodes) {
+            if (node.label !== undefined || node.interaction !== undefined || labels[node.id] !== undefined)
+                continue;
+            findings.push({
+                code: 'UML074_OVERVIEW_UNDOCUMENTED',
+                severity: 'info',
+                message: 'node ' + node.id + ' carries no name a reader can map back to the design: give it a label, an interaction or a narrative entry.',
+                evidence: { id: node.id },
+            });
+        }
+    }
+    return findings;
+}
+/** The interaction overview family, as the engine's registry expects it. */
+export const interactionOverviewModule = {
+    id: 'interaction-overview',
+    // Mermaid is the only notation this family is drawn in: PlantUML's activity syntax, the
+    // one place a `ref` step exists, is refused by this build.
+    notation: 'mermaid',
+    render: (input, notation, _options) => renderInteractionOverview(input, notation),
+    parse: (text, notation) => parseInteractionOverview(text, notation),
+    review: (model, labels) => reviewInteractionOverviewModel(model, labels),
+};

package/lib/uml-profile.js

@@ -0,0 +1,373 @@
+/**
+ * The profile diagram module.
+ *
+ * A profile is a package that extends the metamodel: stereotypes, the metaclasses they
+ * extend, and the profiles applied to a package. That is a shape of its own, so it has
+ * its own model rather than being flattened into a class diagram.
+ *
+ * PlantUML draws one *approximately*: it has `metaclass` and `stereotype` elements and
+ * `class X <<stereotype>>`, and the relation set of its class diagram, but no `profile`
+ * keyword and no Profile/ProfileApplication element. The drawing is therefore one-way.
+ * Reading the text back would have to guess which `--|>` is a stereotype extending a
+ * metaclass and which is one stereotype specialising another — two different facts about
+ * the profile, drawn identically — so the parse is refused by name instead of inventing
+ * the one the reader cannot see. That refusal is the family table's `parseable: false`.
+ *
+ * @module model-everything-uml-profile
+ */
+import { UmlError, UML_PLAIN_ID, directiveLine, } from './uml-syntax.js';
+const MULTIPLICITIES = ['0..1', '1'];
+/** PlantUML ids that cannot stand alone in a declaration. */
+const RESERVED_IDS = new Set(['class', 'metaclass', 'stereotype', 'enum', 'interface', 'abstract', 'package', 'end', 'note', 'hide', 'show', 'skinparam', 'title', 'left', 'right', 'top', 'bottom']);
+function isPlainId(id) {
+    return UML_PLAIN_ID.test(id) && !RESERVED_IDS.has(id.toLowerCase());
+}
+function quote(text) {
+    return '"' + text.replace(/"/g, "'") + '"';
+}
+/**
+ * Validate a candidate model and normalize it.
+ *
+ * The contract every family keeps: an undeclared key or a wrong type is a refusal with
+ * `UML_INPUT`, never a silently dropped field.
+ */
+export function validateProfileModel(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new UmlError('a profile model must be an object with schemaVersion 1, a profile, stereotypes, metaclasses and extensions', 'UML_INPUT');
+    }
+    const model = input;
+    if (model.schemaVersion !== 1)
+        throw new UmlError('a profile model must declare schemaVersion 1', 'UML_INPUT');
+    const profile = model.profile;
+    if (profile === null || typeof profile !== 'object' || typeof profile.id !== 'string' || profile.id.trim() === '') {
+        throw new UmlError('a profile model needs a `profile` with a non-empty id', 'UML_INPUT');
+    }
+    const lists = {
+        stereotypes: model.stereotypes ?? [],
+        metaclasses: model.metaclasses ?? [],
+        extensions: model.extensions ?? [],
+        applications: model.applications ?? [],
+        generalizations: model.generalizations ?? [],
+    };
+    for (const [name, value] of Object.entries(lists)) {
+        if (!Array.isArray(value))
+            throw new UmlError(name + ' must be an array', 'UML_INPUT');
+    }
+    const stereotypeIds = new Set();
+    for (const stereotype of lists.stereotypes) {
+        if (stereotype === null || typeof stereotype !== 'object' || typeof stereotype.id !== 'string' || stereotype.id.trim() === '') {
+            throw new UmlError('every stereotype needs a non-empty string id', 'UML_INPUT');
+        }
+        if (stereotypeIds.has(stereotype.id))
+            throw new UmlError('duplicate stereotype id ' + quote(stereotype.id), 'UML_INPUT');
+        stereotypeIds.add(stereotype.id);
+    }
+    const metaclassIds = new Set();
+    for (const metaclass of lists.metaclasses) {
+        if (metaclass === null || typeof metaclass !== 'object' || typeof metaclass.id !== 'string' || metaclass.id.trim() === '') {
+            throw new UmlError('every metaclass needs a non-empty string id', 'UML_INPUT');
+        }
+        if (metaclassIds.has(metaclass.id))
+            throw new UmlError('duplicate metaclass id ' + quote(metaclass.id), 'UML_INPUT');
+        metaclassIds.add(metaclass.id);
+    }
+    for (const id of [...stereotypeIds]) {
+        if (metaclassIds.has(id))
+            throw new UmlError(quote(id) + ' is declared as both a stereotype and a metaclass', 'UML_INPUT');
+    }
+    const undeclared = new Set();
+    const extensions = [];
+    for (const extension of lists.extensions) {
+        if (extension === null || typeof extension !== 'object')
+            throw new UmlError('every extension must be an object', 'UML_INPUT');
+        if (typeof extension.stereotype !== 'string' || extension.stereotype.trim() === '')
+            throw new UmlError('every extension needs the stereotype that extends', 'UML_INPUT');
+        if (typeof extension.metaclass !== 'string' || extension.metaclass.trim() === '')
+            throw new UmlError('every extension needs the metaclass it extends', 'UML_INPUT');
+        if (!stereotypeIds.has(extension.stereotype))
+            undeclared.add(extension.stereotype);
+        if (!metaclassIds.has(extension.metaclass))
+            undeclared.add(extension.metaclass);
+        if (extension.multiplicity !== undefined && !MULTIPLICITIES.includes(extension.multiplicity)) {
+            throw new UmlError('extension multiplicity must be ' + MULTIPLICITIES.join(' | ') + ', got ' + quote(String(extension.multiplicity)), 'UML_INPUT');
+        }
+        extensions.push({
+            stereotype: extension.stereotype,
+            metaclass: extension.metaclass,
+            ...(extension.multiplicity === undefined ? {} : { multiplicity: extension.multiplicity }),
+            ...(extension.label === undefined ? {} : { label: extension.label }),
+        });
+    }
+    const generalizations = [];
+    for (const generalization of lists.generalizations) {
+        if (generalization === null || typeof generalization !== 'object')
+            throw new UmlError('every generalization must be an object', 'UML_INPUT');
+        for (const side of ['general', 'specific']) {
+            const id = generalization[side];
+            if (typeof id !== 'string' || id.trim() === '')
+                throw new UmlError('every generalization needs a non-empty `' + side + '` stereotype id', 'UML_INPUT');
+            if (!stereotypeIds.has(id))
+                undeclared.add(id);
+        }
+        if (generalization.general === generalization.specific) {
+            throw new UmlError('stereotype ' + quote(generalization.general) + ' cannot generalize itself', 'UML_INPUT');
+        }
+        generalizations.push({ general: generalization.general, specific: generalization.specific });
+    }
+    const applications = [];
+    for (const application of lists.applications) {
+        if (application === null || typeof application !== 'object')
+            throw new UmlError('every application must be an object', 'UML_INPUT');
+        for (const side of ['profile', 'applyTo']) {
+            const value = application[side];
+            if (typeof value !== 'string' || value.trim() === '')
+                throw new UmlError('every application needs a non-empty `' + side + '`', 'UML_INPUT');
+        }
+        if (application.profile !== profile.id)
+            undeclared.add(application.profile);
+        applications.push({ profile: application.profile, applyTo: application.applyTo });
+    }
+    return {
+        schemaVersion: 1,
+        profile: { id: profile.id, ...(profile.label === undefined ? {} : { label: profile.label }) },
+        stereotypes: lists.stereotypes.map((stereotype) => ({ id: stereotype.id, ...(stereotype.label === undefined ? {} : { label: stereotype.label }) })),
+        metaclasses: lists.metaclasses.map((metaclass) => ({ id: metaclass.id, ...(metaclass.label === undefined ? {} : { label: metaclass.label }) })),
+        extensions,
+        applications,
+        generalizations,
+        ...(undeclared.size === 0 ? {} : { undeclared: [...undeclared].sort() }),
+        ...(model.narrative === undefined ? {} : { narrative: model.narrative }),
+    };
+}
+function labelOf(element) {
+    return element.label ?? element.id;
+}
+/**
+ * How one element is declared, and the alias the rest of the diagram uses.
+ *
+ * PlantUML puts the label where the name goes, so an id that needs no alias is used
+ * directly and one that does gets a generated id plus an `alias` directive. That is the
+ * same shape the use case module uses, for the same reason: the round trip has to come
+ * back with the id the model wrote.
+ */
+function declaredAs(element, taken) {
+    if (isPlainId(element.id) && !taken.has(element.id)) {
+        taken.add(element.id);
+        return { id: element.id, alias: element.id };
+    }
+    let index = 1;
+    let candidate = 'E' + String(index);
+    while (taken.has(candidate)) {
+        index += 1;
+        candidate = 'E' + String(index);
+    }
+    taken.add(candidate);
+    return { id: element.id, alias: candidate };
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+/**
+ * Render a profile as PlantUML.
+ *
+ * The drawing is the approximation the family table declares: stereotypes and
+ * metaclasses as the class diagram draws them, extensions and generalizations both as a
+ * `--|>` because the notation has no second arrow for the first. Everything the drawing
+ * cannot carry — which arrow is which, the extension multiplicity and role, the
+ * applications — is written as a directive, so the text is a faithful record of the
+ * model even though the picture is not.
+ *
+ * @param input - candidate `ProfileModelV1`.
+ * @param notation - only `plantuml` draws a profile; mermaid has no view of this family.
+ */
+export function renderProfile(input, notation) {
+    if (notation !== 'plantuml') {
+        throw new UmlError('a profile diagram can only be drawn in plantuml; mermaid has no profile diagram: it has no metaclass or stereotype elements. Render it with notation "plantuml".', 'UML_VIEW_UNREPRESENTABLE');
+    }
+    const model = validateProfileModel(input);
+    const warnings = [
+        'UML_RENDER_APPROXIMATE_VIEW: plantuml has no profile element, so the profile package itself is not drawn; stereotypes and metaclasses are drawn as a class diagram draws them, and an extension and a generalization are both a --|> arrow.',
+    ];
+    const lines = ['@startuml'];
+    lines.push(directiveLine('plantuml', 'uml v1 notation=plantuml family=profile'));
+    lines.push(directiveLine('plantuml', 'profile ' + model.profile.id));
+    const taken = new Set();
+    const aliasOf = new Map();
+    for (const metaclass of model.metaclasses) {
+        const declared = declaredAs(metaclass, taken);
+        aliasOf.set(metaclass.id, declared.alias);
+        if (declared.alias !== metaclass.id)
+            lines.push(directiveLine('plantuml', 'alias ' + declared.alias + ' ' + metaclass.id));
+        lines.push('metaclass ' + quote(labelOf(metaclass)) + ' as ' + declared.alias);
+    }
+    for (const stereotype of model.stereotypes) {
+        const declared = declaredAs(stereotype, taken);
+        aliasOf.set(stereotype.id, declared.alias);
+        if (declared.alias !== stereotype.id)
+            lines.push(directiveLine('plantuml', 'alias ' + declared.alias + ' ' + stereotype.id));
+        lines.push('class ' + quote(labelOf(stereotype)) + ' <<stereotype>> as ' + declared.alias);
+    }
+    // The directives come before the arrows: they are what tells the arrows apart on the
+    // way back, and a reader of the text sees the legend before the drawing.
+    for (const extension of model.extensions) {
+        lines.push(directiveLine('plantuml', 'profileExtension ' + extension.stereotype + ' -> ' + extension.metaclass +
+            (extension.multiplicity === undefined ? '' : ' ' + extension.multiplicity) +
+            (extension.label === undefined ? '' : ' ' + extension.label)));
+    }
+    for (const application of model.applications) {
+        lines.push(directiveLine('plantuml', 'profileApply ' + application.profile + ' -> ' + application.applyTo));
+    }
+    for (const extension of model.extensions) {
+        lines.push((aliasOf.get(extension.stereotype) ?? extension.stereotype) + ' --|> ' + (aliasOf.get(extension.metaclass) ?? extension.metaclass));
+    }
+    for (const generalization of model.generalizations) {
+        lines.push((aliasOf.get(generalization.specific) ?? generalization.specific) + ' --|> ' + (aliasOf.get(generalization.general) ?? generalization.general));
+    }
+    lines.push('@enduml');
+    return { primary: lines.join('\n') + '\n', warnings };
+}
+export const PROFILE_FINDING_CODES = [
+    'UML050_PROFILE_NO_STEREOTYPES',
+    'UML051_PROFILE_UNUSED_STEREOTYPE',
+    'UML052_PROFILE_EXTENSION_MISSING',
+    'UML053_PROFILE_GENERALIZATION_CYCLE',
+    'UML054_PROFILE_UNDECLARED_REFERENCE',
+    'UML055_PROFILE_APPLICATION_MISSING',
+    'UML056_PROFILE_UNDOCUMENTED',
+];
+/**
+ * What a reader would get wrong about a profile.
+ *
+ * The checks read the model alone. Whether a profile is *right* for the metamodel it
+ * extends is a question about the specification being profiled, and this does not answer
+ * it: the codes below are about the profile being internally complete and readable.
+ */
+export function reviewProfileModel(model, labels) {
+    const findings = [];
+    const name = (id) => labels[id] ?? id;
+    if (model.stereotypes.length === 0) {
+        findings.push({
+            code: 'UML050_PROFILE_NO_STEREOTYPES',
+            severity: 'error',
+            message: 'the profile declares no stereotype, so it extends the metamodel with nothing.',
+            evidence: { stereotypes: 0 },
+        });
+    }
+    const extended = new Set(model.extensions.map((extension) => extension.stereotype));
+    const specialized = new Set(model.generalizations.flatMap((generalization) => [generalization.general, generalization.specific]));
+    for (const stereotype of model.stereotypes) {
+        if (extended.has(stereotype.id) || specialized.has(stereotype.id))
+            continue;
+        findings.push({
+            code: 'UML051_PROFILE_UNUSED_STEREOTYPE',
+            severity: 'warning',
+            message: 'stereotype ' + name(stereotype.id) + ' extends no metaclass and specialises no other stereotype: nothing in the profile uses it.',
+            evidence: { id: stereotype.id },
+        });
+    }
+    for (const metaclass of model.metaclasses) {
+        if (model.extensions.some((extension) => extension.metaclass === metaclass.id))
+            continue;
+        findings.push({
+            code: 'UML052_PROFILE_EXTENSION_MISSING',
+            severity: 'warning',
+            message: 'metaclass ' + name(metaclass.id) + ' is declared but no stereotype extends it, so the profile does not change it.',
+            evidence: { id: metaclass.id },
+        });
+    }
+    // A stereotype hierarchy must be acyclic: the specification requires it, and a cycle
+    // means no reader can tell which stereotype is the general one.
+    const adjacency = new Map();
+    for (const generalization of model.generalizations) {
+        const list = adjacency.get(generalization.specific);
+        if (list === undefined)
+            adjacency.set(generalization.specific, [generalization.general]);
+        else
+            list.push(generalization.general);
+    }
+    const state = new Map();
+    const path = [];
+    const walk = (node) => {
+        const seen = state.get(node);
+        if (seen === 'visiting')
+            return [...path.slice(path.indexOf(node)), node];
+        if (seen === 'done')
+            return undefined;
+        state.set(node, 'visiting');
+        path.push(node);
+        for (const next of adjacency.get(node) ?? []) {
+            const cycle = walk(next);
+            if (cycle !== undefined)
+                return cycle;
+        }
+        path.pop();
+        state.set(node, 'done');
+        return undefined;
+    };
+    for (const node of adjacency.keys()) {
+        const cycle = walk(node);
+        if (cycle === undefined)
+            continue;
+        findings.push({
+            code: 'UML053_PROFILE_GENERALIZATION_CYCLE',
+            severity: 'error',
+            message: 'the stereotype hierarchy is cyclic, so which stereotype is the general one has no answer.',
+            detail: cycle.map((id) => name(id)).join(' -> '),
+            evidence: { path: cycle },
+        });
+        break;
+    }
+    const undeclared = model.undeclared ?? [];
+    if (undeclared.length > 0) {
+        findings.push({
+            code: 'UML054_PROFILE_UNDECLARED_REFERENCE',
+            severity: 'error',
+            message: 'the profile refers to ' + String(undeclared.length) + ' element(s) it never declares, so the arrow points at nothing a reader can look up.',
+            detail: undeclared.join(', '),
+            evidence: { ids: undeclared },
+        });
+    }
+    if (model.applications.length === 0) {
+        findings.push({
+            code: 'UML055_PROFILE_APPLICATION_MISSING',
+            severity: 'info',
+            message: 'the profile is not applied to any package: nothing says where it is meant to be used.',
+            evidence: { applications: 0 },
+        });
+    }
+    if (model.profile.label === undefined && labels[model.profile.id] === undefined) {
+        findings.push({
+            code: 'UML056_PROFILE_UNDOCUMENTED',
+            severity: 'info',
+            message: 'the profile itself carries no name a reader can map back to the specification it extends: give it a display label or a narrative entry.',
+            evidence: { id: model.profile.id },
+        });
+    }
+    for (const stereotype of model.stereotypes) {
+        if (stereotype.label !== undefined || labels[stereotype.id] !== undefined)
+            continue;
+        findings.push({
+            code: 'UML056_PROFILE_UNDOCUMENTED',
+            severity: 'info',
+            message: 'stereotype ' + stereotype.id + ' carries no name a reader can map back to the specification: give it a display label or a narrative entry.',
+            evidence: { id: stereotype.id },
+        });
+    }
+    return findings;
+}
+/**
+ * The profile family, as the engine's registry expects it.
+ *
+ * `parse` refuses with the family table's own words. It has to exist because the module
+ * contract requires it, and it must refuse rather than return something: a parse would
+ * have to decide which `--|>` is an extension and which is a generalization, and the
+ * notation does not say.
+ */
+export const profileModule = {
+    id: 'profile',
+    render: (input, notation, _options) => renderProfile(input, notation),
+    parse: () => {
+        throw new UmlError('a profile diagram cannot be read back out of plantuml: it has no profile element, and an extension and a stereotype generalization are both a --|> arrow, so a parse would have to guess which fact the arrow carries. Keep the profile as its own model and review that.', 'UML_VIEW_UNREPRESENTABLE');
+    },
+    review: (model, labels) => reviewProfileModel(model, labels),
+};