@formicoidea/labre-framework-bpmn 0.40.0 → 0.42.0

package/dist/export.js

@@ -763,6 +763,72 @@ class IdMinter {
         return unique;
     }
 }
+/**
+ * The ten export-warning keys, each paired with its English fallback
+ * (`{{name}}` placeholders included) — declared ONCE, here, and read both by
+ * the `if` blocks below (which add the live `params`) and by
+ * `translations.ts`'s manifest (which needs the pair with no board to run
+ * against).
+ */
+// Each fallback below is ONE unbroken literal rather than the `+`-joined
+// pieces an earlier draft used: `manifest.unit.spec.ts`'s drift check reads a
+// key/fallback PAIR as two adjacent literals in one argument list, and a
+// concatenation left it seeing only the first piece — a drift the check
+// itself then (correctly) flagged. A long line is the trade for a fallback
+// the check can actually confirm against the manifest.
+const UNDRAWN_ARTEFACTS_WARNING = [
+    'com.labre.bpmn.export.warning.undrawn',
+    '{{count}} artefact(s) are drawn outside every pool. They are in the file, but most BPMN tools will not draw them: only a pool has a shape to hold them. Draw them inside a pool to make them visible.',
+];
+const DROPPED_MESSAGE_FLOWS_WARNING = [
+    'com.labre.bpmn.export.warning.dropped-message-flows',
+    '{{count}} message flow(s) were left out: a message flow runs between participants, and this board has no pool. Draw the pools it runs between, or say "is followed by" instead.',
+];
+const SUBSTITUTED_IDS_WARNING = [
+    'com.labre.bpmn.export.warning.substituted-ids',
+    '{{count}} element(s) imported from a BPMN file could not keep their original id: it was already taken in this file. A new id was written instead; nothing else changed.',
+];
+const DISPLACED_SHAPES_WARNING = [
+    'com.labre.bpmn.export.warning.displaced-shapes',
+    '{{count}} shape(s) imported from a BPMN file are kept exactly as the file drew them, and the rest of this drawing has moved since. They will open beside the process rather than inside it. Nothing was lost: they are in the file, at the position the original gave them.',
+];
+const CONTRADICTING_DECLARATIONS_WARNING = [
+    'com.labre.bpmn.export.warning.contradicting-declarations',
+    "This board came from a BPMN file that used {{names}} for something other than what BPMN means by them. Labre writes its own, so the file's declarations were left out rather than allowed to redefine the diagram's own namespaces. They are still in the document. Anything the file wrote under those prefixes is still in the export and will now be read under Labre's meaning of them, which is not the meaning the original had.",
+];
+const DISAGREEING_DECLARATIONS_WARNING = [
+    'com.labre.bpmn.export.warning.disagreeing-declarations',
+    "Two pools on this board disagree about {{names}}: they came from BPMN files that gave the same name two different values. The last was written and the other left out, so matter carried from the first file is now read under the second's meaning. Both are still in the document.",
+];
+const CONFLICTING_IDS_WARNING = [
+    'com.labre.bpmn.export.warning.conflicting-ids',
+    '{{count}} element(s) imported from a BPMN file could not be written back: {{names}} name(s) an id another imported element had already claimed, and a BPMN id must be unique across a document. The first was kept. The other(s) are still in the document; they are not in this file.',
+];
+const REFUSED_ATTRIBUTE_NAMES_WARNING = [
+    'com.labre.bpmn.export.warning.refused-attribute-names',
+    '{{count}} carried attribute(s) could not be written back, because their name(s) are not a valid XML name. They are still in the document. This is a sign the payload was edited by something other than a BPMN import.',
+];
+const UNWRITABLE_EDGES_WARNING = [
+    'com.labre.bpmn.export.warning.unwritable-edges',
+    '{{count}} arrow(s) were left out: BPMN requires both ends of a flow to be named, and they have an end that is loose or attached to something that is not a BPMN artefact.',
+];
+const LEFT_OUT_WARNING = [
+    'com.labre.bpmn.export.warning.left-out',
+    '{{count}} element(s) inside the pool are not BPMN elements and were left out of the .bpmn file. Export SVG to get everything drawn in the pool.',
+];
+/** All ten, for `translations.ts`'s manifest contribution. */
+export const BPMN_EXPORT_WARNING_KEYS = [
+    UNDRAWN_ARTEFACTS_WARNING,
+    DROPPED_MESSAGE_FLOWS_WARNING,
+    SUBSTITUTED_IDS_WARNING,
+    DISPLACED_SHAPES_WARNING,
+    CONTRADICTING_DECLARATIONS_WARNING,
+    DISAGREEING_DECLARATIONS_WARNING,
+    CONFLICTING_IDS_WARNING,
+    REFUSED_ATTRIBUTE_NAMES_WARNING,
+    UNWRITABLE_EDGES_WARNING,
+    LEFT_OUT_WARNING,
+];
 /* ── The plan ─────────────────────────────────────────────────────────── */
 /**
  * Which element an artefact is written INSIDE.
@@ -1364,9 +1430,11 @@ export function exportBpmnXmlWithWarnings(board, options = {}) {
             id: minter.mint('Shape', node.id),
             bpmnElement: node.id,
         };
-        // The pack draws the COLLAPSED sub-process only — a task-sized box with a
-        // `+` — and `isExpanded="false"` is how DI says exactly that. Without it a
-        // tool is free to draw an expanded container the author never made.
+        // The pack draws the COLLAPSED sub-process only — a task-sized box, with
+        // no body folded open inside it — and `isExpanded="false"` is how DI says
+        // exactly that. Without it a tool is free to draw an expanded container the
+        // author never made. (Labre leaves the `+` marker itself off the box, which
+        // is a drawing choice and says nothing about the DI flag.)
         if (node.model.kind === 'subProcess' ||
             node.model.kind === 'callActivity') {
             attrs.isExpanded = 'false';
@@ -1465,6 +1533,14 @@ export function exportBpmnXmlWithWarnings(board, options = {}) {
         ...slot(document, 'relationship'),
     ]);
     /* ── What the format refused to carry ────────────────────────────── */
+    //
+    // Each warning is a KEY plus its English fallback and params — see
+    // `BpmnExportWarning`. This function stays `std`-free (like every other
+    // pure exporter in the pack), so it cannot ask a host's catalogue itself;
+    // `exportBpmnXmlFile` (`actions.ts`) resolves every one of these through
+    // `translateKey` before showing them. The fallback is deliberately NEUTRAL
+    // on number ("{{count}} element(s)") rather than branching singular/plural
+    // English by hand: pluralisation is the host's, off `count`.
     const warnings = [];
     // Flow objects drawn beside the pools. They are in the file and correct for
     // any tool that reads the MODEL, and a collaboration plane has no shape to
@@ -1478,18 +1554,12 @@ export function exportBpmnXmlWithWarnings(board, options = {}) {
         ? planned.filter(node => node.scope === orphanProcess).length
         : 0;
     if (undrawn > 0) {
-        warnings.push(`${undrawn} ${undrawn === 1 ? 'artefact is' : 'artefacts are'} drawn ` +
-            `outside every pool. ${undrawn === 1 ? 'It is' : 'They are'} in the ` +
-            `file, but most BPMN tools will not draw ${undrawn === 1 ? 'it' : 'them'}: ` +
-            `only a pool has a shape to hold ${undrawn === 1 ? 'it' : 'them'}. ` +
-            `Draw ${undrawn === 1 ? 'it' : 'them'} inside a pool to make ` +
-            `${undrawn === 1 ? 'it' : 'them'} visible.`);
+        const [key, fallback] = UNDRAWN_ARTEFACTS_WARNING;
+        warnings.push({ key, fallback, params: { count: undrawn } });
     }
     if (droppedMessageFlows > 0) {
-        warnings.push(`${droppedMessageFlows} message ${droppedMessageFlows === 1 ? 'flow was' : 'flows were'} ` +
-            `left out: a message flow runs between participants, and this board ` +
-            `has no pool. Draw the pools it runs between, or say "is followed by" ` +
-            `instead.`);
+        const [key, fallback] = DROPPED_MESSAGE_FLOWS_WARNING;
+        warnings.push({ key, fallback, params: { count: droppedMessageFlows } });
     }
     // An id a file gave us that we could not give back (ADR 0012 D3). It happens
     // when two elements carry the same recorded id — a merged document, an
@@ -1497,11 +1567,8 @@ export function exportBpmnXmlWithWarnings(board, options = {}) {
     // file is correct either way; what the author loses is the continuity of one
     // name between the document they imported and the one they are exporting.
     if (minter.substituted > 0) {
-        warnings.push(`${minter.substituted} ${minter.substituted === 1 ? 'element' : 'elements'} ` +
-            `imported from a BPMN file could not keep ` +
-            `${minter.substituted === 1 ? 'its' : 'their'} original id: ` +
-            `${minter.substituted === 1 ? 'it was' : 'they were'} already taken in ` +
-            `this file. A new id was written instead; nothing else changed.`);
+        const [key, fallback] = SUBSTITUTED_IDS_WARNING;
+        warnings.push({ key, fallback, params: { count: minter.substituted } });
     }
     // A carried diagram element keeps the source file's own coordinates, and the
     // rest of the drawing has just been translated to the plane origin (§12.3).
@@ -1510,44 +1577,28 @@ export function exportBpmnXmlWithWarnings(board, options = {}) {
     // once anything has been dragged. Nothing is lost; something is displaced,
     // and the person who clicked Export is the one entitled to hear about it.
     if (carriedPlane.length > 0 && (dx !== 0 || dy !== 0)) {
-        const count = carriedPlane.length;
-        warnings.push(`${count} ${count === 1 ? 'shape' : 'shapes'} imported from a BPMN file ` +
-            `${count === 1 ? 'is' : 'are'} kept exactly as the file drew ` +
-            `${count === 1 ? 'it' : 'them'}, and the rest of this drawing has ` +
-            `moved since. ${count === 1 ? 'It' : 'They'} will open beside the ` +
-            `process rather than inside it. Nothing was lost: ` +
-            `${count === 1 ? 'it is' : 'they are'} in the file, at the position ` +
-            `the original gave ${count === 1 ? 'it' : 'them'}.`);
+        const [key, fallback] = DISPLACED_SHAPES_WARNING;
+        warnings.push({ key, fallback, params: { count: carriedPlane.length } });
     }
     if (contradictingDeclarations.length > 0) {
-        const one = contradictingDeclarations.length === 1;
-        warnings.push(`This board came from a BPMN file that used ` +
-            `${contradictingDeclarations.join(' and ')} for something other than ` +
-            `what BPMN means by ${one ? 'it' : 'them'}. ` +
-            `Labre writes its own, so the file's ` +
-            `${one ? 'declaration was' : 'declarations were'} ` +
-            `left out rather than allowed to redefine the diagram's own namespaces. ` +
-            `${one ? 'It is' : 'They are'} still in the document. ` +
-            // The half a reader would otherwise have to work out: the DECLARATION
-            // is what was dropped, and the matter written under it was not — so it
-            // is now read under Labre's binding of the same prefix, which means
-            // something else. That is the larger of the two changes and it was the
-            // silent one.
-            `Anything the file wrote under ` +
-            `${one ? 'that prefix' : 'those prefixes'} is still in the export and ` +
-            `will now be read under Labre's meaning of ` +
-            `${one ? 'it' : 'them'}, which is not the meaning the original had.`);
+        const [key, fallback] = CONTRADICTING_DECLARATIONS_WARNING;
+        warnings.push({
+            key,
+            fallback,
+            params: { names: contradictingDeclarations.join(' and ') },
+        });
     }
     // Two pools, two source files, one prefix bound two ways. Last one wins —
     // there is one attribute of each name on `definitions` and something has to
     // be written — but a rebinding nobody was told about is how a fragment comes
     // to mean something else with no trace of when.
     if (disagreeingDeclarations.length > 0) {
-        warnings.push(`Two pools on this board disagree about ` +
-            `${disagreeingDeclarations.join(' and ')}: they came from BPMN files ` +
-            `that gave the same name two different values. The last was written ` +
-            `and the other left out, so matter carried from the first file is now ` +
-            `read under the second's meaning. Both are still in the document.`);
+        const [key, fallback] = DISAGREEING_DECLARATIONS_WARNING;
+        warnings.push({
+            key,
+            fallback,
+            params: { names: disagreeingDeclarations.join(' and ') },
+        });
     }
     // A carried element claiming an id another has already written back. The
     // duplicate-by-paste case is silent on purpose — one thing carried twice is
@@ -1555,32 +1606,34 @@ export function exportBpmnXmlWithWarnings(board, options = {}) {
     // fragments claiming one id, which is a file that cannot hold both.
     const conflicting = [...new Set(carried.conflictingIds)];
     if (conflicting.length > 0) {
-        const one = conflicting.length === 1;
-        warnings.push(`${conflicting.length} ${one ? 'element' : 'elements'} imported from a ` +
-            `BPMN file could not be written back: ` +
-            `${conflicting.map(id => `"${id}"`).join(', ')} ` +
-            `${one ? 'names an id' : 'name ids'} another imported element had ` +
-            `already claimed, and a BPMN id must be unique across a document. The ` +
-            `first was kept. ${one ? 'The other is' : 'The others are'} still in ` +
-            `the document; ${one ? 'it is' : 'they are'} not in this file.`);
+        const [key, fallback] = CONFLICTING_IDS_WARNING;
+        warnings.push({
+            key,
+            fallback,
+            params: {
+                count: conflicting.length,
+                names: conflicting.map(id => `"${id}"`).join(', '),
+            },
+        });
     }
     // An attribute NAME that is not a name. It cannot be written without
     // unbalancing the document — the serializer interpolates a name and escapes
     // only a value — so it is dropped rather than allowed to corrupt the file.
     const refusedNames = [...new Set(carried.refusedNames)];
     if (refusedNames.length > 0) {
-        const one = refusedNames.length === 1;
-        warnings.push(`${refusedNames.length} carried ${one ? 'attribute' : 'attributes'} ` +
-            `could not be written back, because ` +
-            `${one ? 'its name is not' : 'their names are not'} a valid XML name. ` +
-            `${one ? 'It is' : 'They are'} still in the document. This is a sign ` +
-            `the payload was edited by something other than a BPMN import.`);
+        const [key, fallback] = REFUSED_ATTRIBUTE_NAMES_WARNING;
+        warnings.push({ key, fallback, params: { count: refusedNames.length } });
     }
     if (unwritableEdges > 0) {
-        warnings.push(`${unwritableEdges} ${unwritableEdges === 1 ? 'arrow was' : 'arrows were'} ` +
-            `left out: BPMN requires both ends of a flow to be named, and ` +
-            `${unwritableEdges === 1 ? 'this one has' : 'these have'} an end that ` +
-            `is loose or attached to something that is not a BPMN artefact.`);
+        const [key, fallback] = UNWRITABLE_EDGES_WARNING;
+        warnings.push({ key, fallback, params: { count: unwritableEdges } });
+    }
+    // What the PICKING left behind (see {@link BpmnExportBoard.leftOut}). One
+    // line for the whole pool, because the point is not which shape it was: it is
+    // that the file is the process and the SVG is the picture.
+    if (board.leftOut !== undefined && board.leftOut > 0) {
+        const [key, fallback] = LEFT_OUT_WARNING;
+        warnings.push({ key, fallback, params: { count: board.leftOut } });
     }
     return {
         text: `<?xml version="1.0" encoding="UTF-8"?>\n${serializeElement(definitions, '')}\n`,

package/dist/import.d.ts

@@ -1,22 +1,34 @@
-import type { InterchangeImportContext, InterchangeImportResult } from '@formicoidea/labre-core/blocks/surface';
+import { type InterchangeImportContext, type InterchangeImportResult } from '@formicoidea/labre-core/blocks/surface';
 import type { BpmnNodeKind } from '@formicoidea/labre-core/model';
 import { BPMN_SCOPE } from './export.js';
 /**
- * The remarks whose wording is FIXED, as `[key, English]` pairs.
+ * The remarks 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 (`<boundaryEvent>`, an id, a count of lanes)
+ * carries `{{name}}` / `{{count}}` 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 on
- * the note and `reportInterchangeImport` resolves it when it draws the report
- * (`InterchangeNote.messageKey`). 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.
+ * 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.
  *
- * These three and no others, and the line is not arbitrary: every remaining
- * remark NAMES something out of the file — `<boundaryEvent>`, an id, a count of
- * lanes — and the seam has neither interpolation nor pluralisation. A key for
- * one of those would be a sentence with holes in it that a translator cannot
- * see the shape of, which is the same refusal the interchange count labels
- * already make (`interchange-import.ts`).
+ * Plural wording is the host's: where a count can be 0, 1 or many, the
+ * fallback stays grammatically neutral (`'{{count}} lane(s)…'`) rather than
+ * picking English's own singular/plural — the same rule
+ * `interchange-import.ts`'s own count labels follow.
+ *
+ * `BPMN_QUARANTINE_REASON` (declared further down, with its own key pairing)
+ * is the one exception: 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.
  *
  * They are contributed to the manifest by `./translations.ts`, with the
  * framework, because they ship in the BPMN bundle rather than in core.
@@ -25,6 +37,32 @@ export declare const BPMN_IMPORT_REMARKS: {
     readonly inventedPool: readonly ["com.labre.bpmn.import.remark.invented-pool", "This file names no participant, so its process was drawn in a pool of Labre's own. The pool is not the file's: exporting writes the process back without one."];
     readonly laneGap: readonly ["com.labre.bpmn.import.remark.lane-gap", "The lanes of this pool are drawn with a gap or an overlap between them. Labre lays its bands end to end, so their heights were kept in proportion and the space between them was closed."];
     readonly mustUnderstand: readonly ["com.labre.bpmn.import.remark.must-understand", "The file declares an extension that it says MUST be understood to read the model correctly. Labre does not understand it: the import went ahead, and this reading of the process may be wrong."];
+    readonly duplicateId: readonly ["com.labre.bpmn.import.remark.duplicate-id", "Two elements in this file share the id \"{{id}}\", which BPMN requires to be unique across a document. Both were imported; the second will be written back under an id Labre mints."];
+    readonly carriedChild: readonly ["com.labre.bpmn.import.remark.carried-child", "<{{tag}}> has no Labre artefact, so it is kept verbatim on the nearest element that has one. It is not drawn, and no validation rule sees it."];
+    readonly inventedPoolLayout: readonly ["com.labre.bpmn.import.remark.invented-pool-layout", "The participant \"{{name}}\" arrived with no diagram, so Labre placed its pool beside the drawing."];
+    readonly inventedLaneLayout: readonly ["com.labre.bpmn.import.remark.invented-lane-layout", "{{count}} lane(s) arrived with no diagram, so Labre split the pool into equal bands. The proportions are Labre's and not the file's."];
+    readonly undrawnTrigger: readonly ["com.labre.bpmn.import.remark.undrawn-trigger", "<{{tag}}> names its trigger by reference to \"{{ref}}\", which Labre does not draw. The event was kept whole rather than drawn as a plain one."];
+    readonly inventedNodeLayout: readonly ["com.labre.bpmn.import.remark.invented-node-layout", "<{{tag}}> arrived with no diagram, so Labre placed it beside the drawing. Its position is Labre's and not the file's."];
+    readonly singleEndedFlow: readonly ["com.labre.bpmn.import.remark.single-ended-flow", "<{{tag}}> names only one of its two ends, so there is no arrow to draw between them. It was left out."];
+    readonly danglingFlowEnd: readonly ["com.labre.bpmn.import.remark.dangling-flow-end", "<{{tag}}> runs to {{ends}}, not drawn on this canvas. The flow is kept whole beside them rather than drawn with a loose end."];
+    readonly undeclaredShape: readonly ["com.labre.bpmn.import.remark.undeclared-shape", "The diagram draws \"{{id}}\", which the file does not declare. The shape is kept, and nothing is drawn for it."];
+    readonly noProcessResidue: readonly ["com.labre.bpmn.import.remark.no-process-residue", "This file declares {{count}} root element(s) and no process to draw, so there was no artefact for them to be kept on. Nothing was imported."];
+    readonly laneDrift: readonly ["com.labre.bpmn.import.remark.lane-drift", "The file lists this artefact in the lane \"{{listedLane}}\" and draws it in \"{{drawnLane}}\". Labre reads the drawing: a lane holds what is drawn inside it."];
+    readonly inventedRouting: readonly ["com.labre.bpmn.import.remark.invented-routing", "{{count}} flow(s) carry an explicit routing in the file. Labre routes a flow between its two ends and re-routes it whenever they move, so their bend points are not kept."];
+};
+/**
+ * The reader's own refusals, as `[key, English]` pairs — thrown via
+ * {@link InterchangeImportError}, never returned, because none of these say
+ * "this is a file I can partly read" (see `parseDefinitions` and the
+ * choreography refusal, below). Same shape and the same reason as
+ * {@link BPMN_IMPORT_REMARKS}: one entry per shape of refusal, `{{name}}`
+ * holes filled by `InterchangeImportError.messageParams`.
+ */
+export declare const BPMN_IMPORT_ERRORS: {
+    readonly malformedXml: readonly ["com.labre.bpmn.import.error.malformed-xml", "This file is not well-formed XML, so no BPMN can be read out of it: {{detail}}"];
+    readonly notDefinitions: readonly ["com.labre.bpmn.import.error.not-definitions", "A BPMN file opens on <definitions>; this one opens on <{{tag}}>."];
+    readonly wrongNamespace: readonly ["com.labre.bpmn.import.error.wrong-namespace", "This <definitions> is in \"{{namespace}}\", not in BPMN 2.0's (\"{{bpmnNamespace}}\"). A DMN decision model and a BPMN process open on the same element name and are not the same file."];
+    readonly declinedRootKind: readonly ["com.labre.bpmn.import.error.declined-root-kind", "This file is a BPMN {{kind}}, which Labre does not draw. Only a process or a collaboration can be imported."];
 };
 /**
  * `startEvent` + `messageEventDefinition` → `startEventMessage`, and the
@@ -60,6 +98,20 @@ export declare const BPMN_QUARANTINE_REASON: {
     readonly nestedLanes: string;
     readonly imported: string;
 };
+/**
+ * {@link BPMN_QUARANTINE_REASON}'s own i18n keys, one per reason.
+ *
+ * A SEPARATE table rather than folding the key into each reason string
+ * (`BPMN_IMPORT_REMARKS`'s `[key, english]` shape): `BPMN_QUARANTINE_REASON`'s
+ * plain strings are ALSO written verbatim into
+ * `ForeignInterchange.quarantined[].reason` — a DATA field the reader hands
+ * the writer, never re-emitted, never shown, and pinned in
+ * `import.unit.spec.ts` as the literal English text — so it cannot become a
+ * tuple without breaking that contract. Only the REPORT note (`messageKey`
+ * below) is resolved through the host's catalogue; the carried `reason` data
+ * stays English, exactly as it always has.
+ */
+export declare const BPMN_QUARANTINE_REASON_KEY: Record<keyof typeof BPMN_QUARANTINE_REASON, string>;
 /**
  * Read a BPMN 2.0 interchange document as element props plus a report.
  *