@formicoidea/labre-framework-uml 0.42.0

package/dist/xmi-import.d.ts

@@ -0,0 +1,174 @@
+import type { InterchangeImportContext, InterchangeReport, SerializedElementProps } from '@formicoidea/labre-core/blocks/surface';
+import type { ForeignInterchange } from '@formicoidea/labre-core/std/gfx';
+import type { UmlBox } from './component.js';
+import type { UmlModel } from './model.js';
+/**
+ * An **XMI 2.5.1 document, read back as models** — the inverse of `xmi.ts`.
+ *
+ * ## The promise, and its exact shape
+ *
+ * The file our writer produces imports back to the model it was written from.
+ * That is the round-trip `__tests__/xmi-import.unit.spec.ts` pins golden by
+ * golden, and it is the only promise worth making about an interchange pair:
+ * an architect who exports a sheet, opens it in Papyrus and brings it back must
+ * find the same diagram, not a plausible one.
+ *
+ * What does NOT come back is what the writer never wrote (`xmi.ts`'s header
+ * says so in as many words): **not one coordinate**. A UML model file carries a
+ * model; the picture stays in Labre. So an import of our own export has no
+ * geometry, the materializer invents a layout, and the report says so (ADR 0012
+ * D4 — "it never claims a position it invented came from the file"). A file
+ * from a tool that DOES ship diagram interchange — Papyrus's `.notation`, a
+ * `umldi` island — is read for its shapes' bounds, and those are used verbatim.
+ *
+ * ## Preservation is the whole point (ADR 0012 D1, D2, D5)
+ *
+ * Everything this reader does not map is **quarantined verbatim**: the file's
+ * own bytes, sliced out of the source ({@link xmlFragmentOf}), filed under the
+ * nearest mapped ancestor's source id, and carried in the document forever.
+ *
+ * Quarantined and not *carried*, and the difference is not a hedge. D1's
+ * "carried" state promises re-emission in place, and this framework has no
+ * writer that could keep that promise: `xmi.ts` builds a document out of the IR
+ * alone and has no slot anywhere in it for a verbatim fragment. A state that
+ * says "kept, and deliberately not written back" is exactly D5's, and saying so
+ * is better than filing a fragment under a promise nothing can honour. The day
+ * the writer learns to splice fragments, the classification moves — the DATA
+ * does not, because it is all still there.
+ *
+ * Unknown ATTRIBUTES on an element that *was* mapped are carried rather than
+ * quarantined, under {@link ForeignInterchange.attrs}, because an attribute has
+ * somewhere to go back to and because tranche H reads association-end
+ * multiplicities out of exactly that slot.
+ *
+ * ## What is knowingly lost, and it is one thing
+ *
+ * **Containment.** A `packagedElement` inside a `uml:Package`, an
+ * `ownedUseCase` inside its subject: both are statements, and on this canvas
+ * both are made by DRAWING one box inside another — `xmi.ts`'s `containerOf`
+ * reads them off geometry and nothing stores them. A model file carries no
+ * geometry, so a sheet imported from one is laid out side by side and a second
+ * export writes the elements as siblings. Nothing is destroyed and nothing is
+ * mis-stated; the nesting is simply not re-drawn, and the report says so in the
+ * user's words so they can put the box back in one drag. A file that DOES carry
+ * diagram interchange keeps its nesting, because then the geometry is there.
+ *
+ * The round trip is therefore a **fixed point after one cycle**, which is D3's
+ * own phrase for identity and holds here for shape as well: export, import,
+ * export — and every export after that is byte-identical.
+ *
+ * ## Tolerant everywhere, refusing nowhere
+ *
+ * No throw, in any input. A root nobody recognises produces an empty result and
+ * a note; a half-written file produces what it said and a note; an association
+ * with one end produces a note and no relation. The reason is BPMN's inverted:
+ * that reader can refuse a `.dmn` because a `<definitions>` in the wrong
+ * namespace is provably another format, whereas "UML-ish XML" has a dozen
+ * dialects and refusing one of them over a spelling would refuse a real model.
+ *
+ * ## Pure
+ *
+ * A string in, records out. No `std`, no DOM (the tokenizer is `xml-reader.ts`,
+ * written for this reason), no clock, no randomness — `docs/adr/0012` P3.
+ */
+/** One diagram's worth of geometry, by SOURCE id — `{}` for a file with none. */
+export type UmlXmiLayout = Record<string, UmlBox>;
+export interface UmlXmiImport {
+    /**
+     * One model per top-level package, in document order.
+     *
+     * A package per diagram is what the writer produces (`diagramPackage`), and
+     * the only reading that keeps four sheets four sheets: a `uml:Model` whose
+     * classifiers hang loose is one namespace, and ADR 0017 refuses that merge on
+     * the canvas. A file with no packages at all — which is what Papyrus writes
+     * for a single-diagram model — is read as ONE model off the root.
+     */
+    models: UmlModel[];
+    /** Where the file's own diagram interchange, if any, drew each source id. */
+    layout: UmlXmiLayout;
+    /**
+     * What the file declares INSIDE what — child source id → container source id.
+     *
+     * An XMI model states containment structurally (`packagedElement`,
+     * `ownedUseCase`) and, unless it carries a `umldi` diagram, says nothing at
+     * all about where any of it is drawn. On this canvas containment IS geometry —
+     * `xmi.ts`'s own `containerOf` reads it back off the boxes — so the statement
+     * has to reach the materializer's invented layout or it is lost on the first
+     * export: a package imported empty, and every class of it laid out beside it.
+     *
+     * Handed over rather than applied here for the reason {@link foreign} is: this
+     * reader has no layout engine, and the one that has is shared with the other
+     * two formats.
+     */
+    containment: Record<string, string>;
+    /**
+     * Foreign matter, by the source id of the element it rides on (D2).
+     *
+     * The materializer owns the id map — it is the only thing that knows which
+     * serialized element props stand for which IR node — so it owns the
+     * attachment too, and this is handed to it rather than applied here.
+     */
+    foreign: Record<string, ForeignInterchange>;
+    report: InterchangeReport;
+}
+/** The reasons a fragment is kept and not written back (ADR 0012 D5). */
+export declare const UML_XMI_QUARANTINE_REASON: {
+    readonly unmapped: string;
+    readonly danglingEnd: string;
+};
+/**
+ * The remarks this reader raises whose wording is FIXED, as `[key, English]`
+ * pairs — the same table, the same shape and the same reasons as
+ * `UML_PLANTUML_REMARKS` (`plantuml-import.ts`, where the contract is written
+ * out) and BPMN's own `BPMN_IMPORT_REMARKS`: one entry per SHAPE of sentence,
+ * `{{name}}` holes filled at the call site by `InterchangeNote.messageParams`,
+ * the English kept here as the fallback so a playground with no catalogue
+ * reads exactly what it read before.
+ *
+ * {@link UML_XMI_QUARANTINE_REASON} above is NOT part of it, and cannot be:
+ * its plain string is also written verbatim into
+ * `ForeignInterchange.quarantined[].reason` — data, never translated — so it
+ * cannot become a `[key, english]` pair without breaking that contract. BPMN
+ * carries the identical constraint on its own quarantine reasons.
+ */
+export declare const UML_XMI_REMARKS: {
+    readonly mintedId: readonly ["com.labre.uml.import.xmi.minted-id", "<{{tag}}> carries no xmi:id, so one was minted for it. Nothing in the file can refer to it, and nothing does."];
+    readonly unlistedOperator: readonly ["com.labre.uml.import.xmi.unlisted-operator", "This combined fragment's operator is \"{{operator}}\", which UML 2.5.1 §17.6.4 does not list. It is drawn as an \"alt\" and the file's own word is kept beside it."];
+    readonly undrawnOccurrence: readonly ["com.labre.uml.import.xmi.undrawn-occurrence", "A message in \"{{name}}\" names an occurrence this sheet has no lifeline for, so it is not drawn. The file still says it, and nothing was removed from the document."];
+    readonly wrongRoot: readonly ["com.labre.uml.import.xmi.wrong-root", "A UML interchange file opens on <uml:Model> or <uml:Package>; this one opens on <{{tag}}>. Nothing was imported."];
+    readonly noXml: readonly ["com.labre.uml.import.xmi.no-xml", "There is no XML element in this file, so there is no model in it."];
+    readonly offSheetRelation: readonly ["com.labre.uml.import.xmi.off-sheet-relation", "A {{kind}} in \"{{name}}\" runs to an element that is not on this sheet, so it is not drawn. The file still says it, and nothing was removed from the document."];
+    readonly modelWithoutDiagram: readonly ["com.labre.uml.import.xmi.model-without-diagram", "This file carries a model and no diagram, which is what the UML interchange format is for. Every position on the canvas was invented; none of them came from the file."];
+    readonly nestedWithoutDrawing: readonly ["com.labre.uml.import.xmi.nested-without-drawing", "{{count}} element(s) are declared inside another in this file — a class in a package, a use case in its subject. Labre states that by DRAWING one box inside the other, and this file carries no drawing, so they were laid out side by side. Move them into the box to say it again."];
+};
+/**
+ * Read an XMI 2.5.1 document as models plus a report.
+ *
+ * See the module comment for the contract, and `docs/adr/0012` D1–D6 for why it
+ * is this contract and not a shorter one.
+ */
+export declare function importXmi(source: string, context?: InterchangeImportContext): UmlXmiImport;
+/**
+ * The materializer's elements, each carrying what the file said about it.
+ *
+ * ## Why this is a second pass and not an argument
+ *
+ * `umlElementsFromModel` already writes `interchange[formatId] = { id }` on
+ * every element it mints — the source id, verbatim, which is D3's fixed point —
+ * so the id map this needs is not a thing the parser has to be told: it is
+ * written on the elements. Merging here keeps the materializer one function of
+ * one IR, shared by three importers, none of which has to know what the others
+ * carry.
+ *
+ * The payload is written as ONE whole blob per format, never patched field by
+ * field: the `Y.Map` entry is the entire record, so a partial update is a
+ * last-write-wins overwrite of everything (D2).
+ *
+ * ## The residue (D6)
+ *
+ * A payload whose source id matched no element — the document-scope matter, a
+ * quarantined fragment off an element that was never drawn — rides on the FIRST
+ * element, which for this materializer is the first sheet's frame. Its accepted
+ * asymmetry is D6's own: delete that frame and what it carried goes with it.
+ */
+export declare function umlElementsWithForeign(elements: readonly SerializedElementProps[], foreign: Readonly<Record<string, ForeignInterchange>>, formatId: string): SerializedElementProps[];