@formicoidea/labre-framework-uml 0.42.0

package/dist/operators.d.ts

@@ -0,0 +1,45 @@
+import type { UmlFragmentOperator } from '@formicoidea/labre-core/model';
+/**
+ * The INTERACTION OPERATOR a combined fragment declares, as the picker offers
+ * it — DATA, exactly like `UML_DIAGRAM_KIND_MENU` in `kinds.ts`, and shaped the
+ * same way for the same reason: the manifest walks declarations, so every key
+ * below reaches a host's catalogue without being restated anywhere.
+ *
+ * ## The operator is the whole of what a fragment says
+ *
+ * §17.6.4 draws every combined fragment as the same rectangle with the same
+ * cut-corner pentagon in its corner. An `alt` and a `loop` are one picture and
+ * two entirely different statements, and the only thing that separates them is
+ * the word in the tag — so picking one here changes what the box MEANS, not how
+ * it looks. That is why this is a picker on a stored field and not a morph
+ * between elements (`morph.ts` is for artefacts that are drawn differently).
+ *
+ * ## Thirteen, and the thirteenth is not an operator
+ *
+ * Twelve of these are §17.6.4's own `InteractionOperatorKind`. `ref` is
+ * §17.7.4's InteractionUse — a different metaclass, drawn as the same rectangle
+ * with the same pentagon — and it is offered from the same menu because that is
+ * where every tool puts it and where every architect looks for it. The model's
+ * own union records the same choice.
+ *
+ * ## The order
+ *
+ * The four an architect actually draws first (`alt`, `opt`, `loop`, `par`),
+ * then `ref`, which is the next most reached for; then the rest of §17.6.4 in
+ * its own order. A menu that listed twelve operators alphabetically would put
+ * `assert` above `alt`, which is a list sorted for a machine.
+ */
+export interface UmlFragmentOperatorOption {
+    /** What gets written in the pentagon. Never `undefined`: the field is required. */
+    operator: UmlFragmentOperator;
+    /** i18n key of the entry's words; resolved by the host. */
+    labelKey: string;
+    /** The framework's own wording, for a host that ships no catalogue. */
+    labelFallback: string;
+}
+/** The picker, whole: its heading and its thirteen entries. */
+export declare const UML_FRAGMENT_OPERATOR_MENU: {
+    labelKey: string;
+    labelFallback: string;
+    options: readonly UmlFragmentOperatorOption[];
+};

package/dist/operators.js

@@ -0,0 +1,75 @@
+/** i18n key stem: `alt` → `com.labre.uml.operator.alt`. */
+const operatorKey = (name) => `com.labre.uml.operator.${name}`;
+/** The picker, whole: its heading and its thirteen entries. */
+export const UML_FRAGMENT_OPERATOR_MENU = {
+    labelKey: operatorKey('section'),
+    labelFallback: 'Operator',
+    options: [
+        {
+            operator: 'alt',
+            labelKey: operatorKey('alt'),
+            labelFallback: 'Alternatives',
+        },
+        {
+            operator: 'opt',
+            labelKey: operatorKey('opt'),
+            labelFallback: 'Option',
+        },
+        {
+            operator: 'loop',
+            labelKey: operatorKey('loop'),
+            labelFallback: 'Loop',
+        },
+        {
+            operator: 'par',
+            labelKey: operatorKey('par'),
+            labelFallback: 'Parallel',
+        },
+        {
+            // §17.7.4, not §17.6.4 — see the header on why it is in this menu.
+            operator: 'ref',
+            labelKey: operatorKey('ref'),
+            labelFallback: 'Interaction use',
+        },
+        {
+            operator: 'break',
+            labelKey: operatorKey('break'),
+            labelFallback: 'Break',
+        },
+        {
+            operator: 'critical',
+            labelKey: operatorKey('critical'),
+            labelFallback: 'Critical region',
+        },
+        {
+            operator: 'seq',
+            labelKey: operatorKey('seq'),
+            labelFallback: 'Weak sequencing',
+        },
+        {
+            operator: 'strict',
+            labelKey: operatorKey('strict'),
+            labelFallback: 'Strict sequencing',
+        },
+        {
+            operator: 'neg',
+            labelKey: operatorKey('neg'),
+            labelFallback: 'Negative',
+        },
+        {
+            operator: 'assert',
+            labelKey: operatorKey('assert'),
+            labelFallback: 'Assertion',
+        },
+        {
+            operator: 'ignore',
+            labelKey: operatorKey('ignore'),
+            labelFallback: 'Ignore',
+        },
+        {
+            operator: 'consider',
+            labelKey: operatorKey('consider'),
+            labelFallback: 'Consider',
+        },
+    ],
+};

package/dist/plantuml-import.d.ts

@@ -0,0 +1,113 @@
+import type { InterchangeNote } from '@formicoidea/labre-core/blocks/surface';
+import type { UmlModel } from './model.js';
+/**
+ * **PlantUML source, read back** — the inverse of `plantuml.ts` over the
+ * vocabulary that writer emits, and a tolerant reading of the rest of the
+ * language (`docs/adr/0012`, D1–D6).
+ *
+ * ## What it is for, and it is not symmetry
+ *
+ * A `.puml` is the format UML diagrams actually live in: it sits in a `docs/`
+ * folder beside the code, it diffs line by line in review, and every
+ * architecture repository already has some. An importer is what turns that
+ * corpus into boards somebody can edit, and it is the only one of the three
+ * readers whose input a human wrote by hand — which is why the contract below is
+ * "never throw" rather than "refuse what is malformed".
+ *
+ * ## Never a throw, always a report
+ *
+ * PlantUML is a large language with a preprocessor, sprites, styles, JSON and
+ * YAML diagrams and a dozen shorthands per relationship. This reads the UML
+ * subset and files EVERY line it does not understand as a `carried` remark
+ * naming the line, so an import of a file half of which is `!include` and
+ * `skinparam` produces the diagram it does understand and tells the user
+ * precisely what it left on the floor. The alternative — an exception — would
+ * turn one unknown directive into a file nobody can open.
+ *
+ * That is a deliberate departure from `gfx/bpmn/src/import.ts`, which throws: an
+ * XML document either is a BPMN interchange file or is not, and there is a root
+ * element to ask. A text file has no such question to answer.
+ *
+ * ## The fixed point
+ *
+ * Our own export re-imports to the model it was written from, and re-exports to
+ * the same bytes. `__tests__/import-roundtrip.unit.spec.ts` pins it on the
+ * phase-1 fixtures and `__tests__/plantuml-import.unit.spec.ts` on the corpus
+ * file an earlier build actually produced. That property is what makes a `.puml`
+ * a place a Labre board can be kept.
+ *
+ * ## The loss table
+ *
+ * | what                                                    | state    | after a round trip |
+ * | ------------------------------------------------------- | -------- | ------------------ |
+ * | classes, interfaces, enums, objects and their members   | mapped   | drawn, and written back verbatim |
+ * | packages, subjects, actors, use cases, notes            | mapped   | drawn, and nested as the file nested them |
+ * | every relationship operator, and the keyword on it      | mapped   | the role, and the arrow it is drawn as |
+ * | components, artifacts, cubes, declared interfaces       | mapped   | drawn; a lollipop comes back as `interface` + the two arrows §10.4.4 says it IS |
+ * | state machines — states, pseudostates, transitions      | mapped   | drawn on an `stm` sheet |
+ * | end multiplicities (`"1" -- "0..*"`)                    | carried  | named in the report. The IR has no end labels until tranche H, so they are not drawn and not written back |
+ * | `skinparam`, `!include`, styles, sprites, preprocessor  | carried  | named in the report, one line each. A theme in an exported file overrides the repository it lands in, which is why this pack writes none |
+ * | the alias a declaration was written under               | mapped   | kept as the element's source id (D3); the export re-derives an alias from the NAME, so a file whose aliases are hashes comes back readable |
+ * | **layout**                                              | invented | PlantUML carries no coordinates. Rows by generalization depth, containers sized to fit — and the report says so (D4) |
+ * | a direction hint inside an arrow (`-down->`)            | **lost** | read as the plain arrow: Labre lays the diagram out itself |
+ * | `hide`, `remove`, `together`, layout directives         | carried  | named; they say how to DRAW, and the drawing is the board's |
+ */
+export interface UmlPlantumlImport {
+    /**
+     * One model per `@startuml … @enduml` block.
+     *
+     * A LIST and not one model, because `exportUmlPlantuml` writes one document
+     * per diagram and concatenates them: a file holding four blocks is four
+     * sheets, and collapsing them would lose exactly the fact ADR 0017 is about.
+     * A source with no `@startuml` at all is read as one unwrapped block, which is
+     * what half the snippets in the wild are.
+     */
+    models: UmlModel[];
+    notes: InterchangeNote[];
+}
+/**
+ * The remarks this reader raises whose wording is FIXED, as `[key, English]`
+ * pairs — one entry per SHAPE of sentence, never one per exact string: a
+ * remark that names something out of the file (a line of PlantUML, a
+ * declaration's alias) carries `{{name}}` holes in the fallback here, filled
+ * at the call site by `messageParams` (`InterchangeNote.messageParams`) —
+ * never by minting a new key for every value the file happens to carry.
+ *
+ * A reader is a pure function of text (`docs/adr/0012`, P3) and has no `std`,
+ * so it cannot ask the host's catalogue for anything: it declares the key
+ * (and, where the sentence has a hole, the params) on the note, and
+ * `reportInterchangeImport` resolves both when it draws the report
+ * (`InterchangeNote.messageKey` / `.messageParams`). The English string stays
+ * here and stays the fallback, so the console table and a playground with no
+ * catalogue read exactly what they read before: `translateKey` fills a `{{…}}`
+ * hole from `messageParams` even with no `TranslationProvider` registered
+ * (`fillPlaceholders`), so the ENGLISH sentence a call site builds is
+ * unchanged by giving it a key. BPMN's `BPMN_IMPORT_REMARKS` is the same table
+ * for the same reasons, and this one is written to match it — including
+ * declaring it in the reader's OWN file rather than in a shared one, so the
+ * wording sits beside the line that raises it.
+ *
+ * Plural wording is the host's: where a count can be 0, 1 or many, the
+ * fallback stays grammatically neutral (`'{{count}} element(s)'`) rather than
+ * picking English's own singular/plural.
+ *
+ * They are contributed to the manifest by `./translations.ts`, with the
+ * framework, because they ship in the UML bundle rather than in core.
+ */
+export declare const UML_PLANTUML_REMARKS: {
+    readonly relationEnd: readonly ["com.labre.uml.import.plantuml.relation-end", "The {{side}} end of the {{kind}} between \"{{left}}\" and \"{{right}}\" is written \"{{raw}}\". It is drawn on the board, but UML gives that relationship's ends no multiplicity, so no export writes it."];
+    readonly duplicateDeclaration: readonly ["com.labre.uml.import.plantuml.duplicate-declaration", "This document declares \"{{name}}\" twice. The second declaration was read as a separate artefact under an id of Labre's own."];
+    readonly renderDirective: readonly ["com.labre.uml.import.plantuml.render-directive", "\"{{line}}\" says how to DRAW the diagram. Labre's canvas has a look of its own, so the directive is recorded here and not applied."];
+    readonly unreadLine: readonly ["com.labre.uml.import.plantuml.unread-line", "Labre does not read \"{{line}}\", so it is not on the board. The line is recorded here exactly as the file wrote it."];
+    readonly stateSyntax: readonly ["com.labre.uml.import.plantuml.state-syntax", "\"{{heading}}\" is written in PlantUML's state-diagram syntax, which Labre reads as a state machine. The frame keeps the kind the title gave it."];
+    readonly autonumber: readonly ["com.labre.uml.import.plantuml.autonumber", "\"{{line}}\" numbers the messages as the renderer draws them. A Labre board writes no numbers on its arrows, so the directive is recorded here and not applied."];
+    readonly inventedSequenceLayout: readonly ["com.labre.uml.import.plantuml.invented-sequence-layout", "PlantUML carries no coordinates, so \"{{heading}}\" was laid out by Labre — the participants side by side in the order the file declares them, and one step down the page per message. The ORDER is the file's; the positions are ours."];
+    readonly inventedLayout: readonly ["com.labre.uml.import.plantuml.invented-layout", "PlantUML carries no coordinates, so \"{{heading}}\" was laid out by Labre — in rows by generalization depth, with every container sized to fit what it holds. The positions are ours, not the file's."];
+};
+/**
+ * Read PlantUML source as one model per `@startuml … @enduml` block.
+ *
+ * Pure: a string in, records out. No `std`, no DOM, no clock, no randomness —
+ * the same source always produces the same models, down to the coordinates.
+ */
+export declare function importPlantuml(source: string): UmlPlantumlImport;