@formicoidea/labre-framework-uml 0.42.0

package/dist/plantuml.d.ts

@@ -0,0 +1,94 @@
+import { type UmlModel } from './model.js';
+/**
+ * One diagram as **PlantUML** source (https://plantuml.com/class-diagram).
+ *
+ * ## Why PlantUML beside XMI
+ *
+ * They answer different questions. XMI is what a MODELLING TOOL reads — it
+ * carries the metamodel, and no human opens it. PlantUML is what a repository
+ * reads: it goes in a `docs/` folder beside the code, it diffs line by line in a
+ * review, and the architect who wrote the diagram can still read it a year
+ * later. A framework that only exported XMI would be a framework whose diagrams
+ * cannot live in version control.
+ *
+ * ## What it writes, and what it declines to
+ *
+ * No `skinparam`, not one line. A `skinparam` is a THEME, and a theme baked into
+ * an exported file overrides whatever the repository it lands in has decided
+ * about how its diagrams look — silently, and in every diagram, forever. Labre's
+ * canvas colours are Labre's; the file carries the model.
+ *
+ * Member lines are written back VERBATIM, and that is a decision rather than
+ * laziness: PlantUML's member syntax IS UML's own §9.5.4 / §9.6.4 notation, the
+ * same grammar the author typed in the compartment. Re-spelling a parsed
+ * property could only lose what the parser did not model — a constraint, an
+ * unusual modifier, a qualified redefinition — so the parser is used where
+ * PlantUML needs STRUCTURE it cannot infer (an enumeration's literals, an
+ * object's slots) and nowhere else.
+ *
+ * ## The one thing it drops, said out loud
+ *
+ * A PORT. §11.3.4's small square has a place in the XMI file — it is an
+ * `ownedAttribute` of its component, with an id other elements can point at —
+ * and in a `.puml` it would have to be a `port` declaration inside a
+ * `component … { }` block, which is a recent addition to the language and not
+ * one every renderer in a repository's toolchain has. What the port CARRIES is
+ * not lost: the lollipops and sockets drawn on it are attributed to its
+ * component by `model.ts` and written below, so the picture still says which
+ * contracts the component offers and needs. Only the square itself goes, and
+ * the day the `port` syntax is safe to assume it is four lines here and a
+ * golden.
+ *
+ * ## Pure
+ *
+ * A model in, a string out. No `std`, no DOM, no clock — `docs/adr/0012` P3.
+ */
+/**
+ * An alias — the identifier every declaration takes and every relation refers
+ * back to.
+ *
+ * Derived from the NAME rather than from the surface id, because an alias is
+ * READ: `customer --> order` says what it relates and `_x7fQa --> _9bTz1` says
+ * nothing at all to the person who opens the file. The folding is deliberately
+ * lossy — ASCII only, since PlantUML's bare identifier is a word and a unicode
+ * one needs quoting everywhere — and the NAME is preserved separately, in the
+ * quoted label every declaration carries.
+ */
+export declare function toPlantumlAlias(raw: string): string;
+/**
+ * A label, as something PlantUML can carry inside `"…"`.
+ *
+ * Two transformations, and both are a thing the grammar cannot express:
+ *
+ * - **a line break becomes `\n`**, PlantUML's own escape. A declaration is one
+ *   line and a canvas label routinely is not — it is how a class name fits in
+ *   its box — so a raw newline would end the statement halfway through;
+ * - **`"` becomes `'`**, because PlantUML has no escape for a double quote
+ *   inside a quoted label: the first one ENDS it, and the rest of the line is
+ *   read as syntax.
+ *
+ * Nothing else is touched. Accents, CJK and emoji go through unharmed: they are
+ * text, PlantUML carries text, and folding them would be this exporter
+ * rewriting somebody's diagram.
+ */
+export declare function toPlantumlLabel(raw: string): string;
+/**
+ * One diagram, as one complete PlantUML document.
+ *
+ * Elements first, nested in the packages and subjects they are drawn inside,
+ * then every relationship — PlantUML resolves an arrow by alias, and an element
+ * declared after the line referring to it renders as a bare box with none of its
+ * members.
+ *
+ * Containment is geometric, exactly as it is in `xmi.ts` and for the same
+ * reason: on a UML diagram, a class drawn inside a package IS in that package
+ * (§12.2.4), and a use case inside the subject rectangle IS the subject's
+ * (§18.1.4). Layout is the statement here, which is the one place this exporter
+ * reads geometry at all.
+ *
+ * The `title` is the diagram's own HEADING — `class Orders`, Annex A's frame tag
+ * — and there is no option to override it: the document's name is a different
+ * fact about a different thing, and substituting it would drop the kind tag,
+ * which is the half of the heading a `.puml` has nowhere else to put.
+ */
+export declare function exportPlantuml(model: UmlModel): string;