@formicoidea/labre-framework-bpmn 0.32.0 → 0.34.1

package/dist/profiles.js

@@ -0,0 +1,189 @@
+/**
+ * BPMN validation profiles (backlog item B6 — not the rule of that number; see
+ * the numbering note in `rules.ts`).
+ *
+ * DATA owned by the framework, like its rules and its roles. A profile is chosen
+ * per POOL — the framework's root instance — and the choice rides on the pool
+ * element itself, so two participants at two levels of requirement coexist on one
+ * canvas: the pool somebody is still sketching stays a sketch while the one
+ * that is being handed over is held to the norm.
+ *
+ * Registered from the flag-gated `BpmnViewExtension`, beside the rules:
+ * switching the `bpmn` flag off takes the choice away with the rest of the
+ * tooling, and a pool already set to `descriptive` simply stops being checked
+ * until it comes back — the id stays written, untouched.
+ *
+ * ## Two today, and the two that are future DATA
+ *
+ * BPMN 2.0 defines three conformance sub-classes, each a superset of the last:
+ * DESCRIPTIVE (the visual subset a business reader can follow — the one this
+ * pack draws), ANALYTIC (every event type, every gateway, the full flow
+ * semantics) and COMMON EXECUTABLE (what an engine can run: data mappings,
+ * expressions, message correlation). Only the first is meaningful against the
+ * twenty-two rules that exist, because the other two are levels of requirement
+ * about artefacts this pack does not yet draw.
+ *
+ * They arrive as PROFILES and not as engine work when they arrive: a level of
+ * requirement is a table of severities per rule id, so `bpmn.analytic` is an
+ * entry in the array at the bottom of this file plus whatever new rules the new
+ * artefacts bring. Nothing in the pipework has to learn a third word.
+ *
+ * ## Both tables spell out all TWENTY-TWO ids
+ *
+ * Every severity a user can get is either the one its rule declares or one of
+ * these lines — nothing is raised implicitly (PF9.4). Spelling them all out is
+ * also what let eight of these rules wait a review cycle for the engine fields
+ * they needed and then arrive already governed, rather than arriving and
+ * quietly keeping their own severity at a level nobody had chosen.
+ */
+/**
+ * Sketch: every rule demoted to `audit`. Findings still reach `violations$` —
+ * a host panel and a conformance report see them — and the canvas says nothing.
+ *
+ * The DEFAULT, and deliberately so (PRD principle 3). A process is drawn in a
+ * workshop, at speed, with the steps going down before anybody decides where the
+ * pools are: for the first minutes of that, EVERY task is a dead end, no pool has
+ * a start event, and half the links are still plain connectors somebody
+ * quick-dragged. A tool arguing with that hand is a tool switched off within the
+ * hour, and it would be arguing about a diagram the author already knows is
+ * unfinished.
+ *
+ * The sketch PRIMES: the findings are computed, collected and available the
+ * moment the author asks — through the panel, through a check-up, through the
+ * profile switch — so nothing has to be re-derived when they decide the drawing
+ * is a deliverable. Being the default also means it WRITES NOTHING: a pool on
+ * `sketch` carries no profile key, so every process ever drawn is on it, with no
+ * migration and no backfill.
+ */
+const sketch = {
+    id: 'bpmn.sketch',
+    framework: 'bpmn',
+    labelKey: 'com.labre.bpmn.profile.sketch',
+    fallback: 'Sketch',
+    isDefault: true,
+    rules: {
+        'bpmn.sequence-flow-endpoints': 'audit',
+        'bpmn.sequence-flow-self-loop': 'audit',
+        'bpmn.message-flow-endpoints': 'audit',
+        'bpmn.association-endpoints': 'audit',
+        'bpmn.untyped-flow': 'audit',
+        'bpmn.duplicate-sequence-flow': 'audit',
+        'bpmn.start-event-no-inflow': 'audit',
+        'bpmn.start-event-must-exit': 'audit',
+        'bpmn.end-event-no-outflow': 'audit',
+        'bpmn.end-event-must-be-reached': 'audit',
+        'bpmn.activity-dead-end': 'audit',
+        'bpmn.sequence-flow-stays-home': 'audit',
+        'bpmn.message-flow-crosses-pools': 'audit',
+        'bpmn.unreachable-step': 'audit',
+        'bpmn.pool-end-without-start': 'audit',
+        'bpmn.pool-start-without-end': 'audit',
+        'bpmn.single-blank-start': 'audit',
+        'bpmn.gateway-must-branch': 'audit',
+        'bpmn.gateway-join-and-fork': 'audit',
+        'bpmn.fake-join': 'audit',
+        'bpmn.implicit-split': 'audit',
+        'bpmn.unlabeled-step': 'audit',
+    },
+};
+/**
+ * Descriptive: the BPMN 2.0 DESCRIPTIVE conformance posture — a diagram a
+ * business reader can be handed and will read correctly.
+ *
+ * Every rule at the severity its own declaration carries, spelled out rather
+ * than left absent, so the answer is readable in one place. That is the point of
+ * a profile table: a reviewer asking "what does this level actually require"
+ * reads twenty-two lines instead of twenty-two files, and a rule added later
+ * cannot join
+ * a level silently — it arrives with its own severity until somebody writes it
+ * down here.
+ *
+ * ## Nothing is `blocking-overridable`, and one line each is what changes that
+ *
+ * Nothing in this library implements refusal — no gesture is declined anywhere —
+ * so declaring the level would be data claiming an effect that does not exist
+ * (the `wardley/rules.ts:30` promise, kept). FOUR rules would sit there the day
+ * a gesture refusal lands, and each moves in one line, here:
+ *
+ * - `bpmn.start-event-no-inflow` and `bpmn.end-event-no-outflow` (p.244 / p.248)
+ *   — both say the process runs backwards, and neither has a reading in which
+ *   the author is right;
+ * - `bpmn.pool-end-without-start` and `bpmn.pool-start-without-end` — verbatim
+ *   normative MUSTs, guard included: "If there is an End Event, then there MUST
+ *   be at least one Start Event" (p.238) and its mirror (p.246). The pack argued
+ *   the pairing into existence before somebody read the pages; the specification
+ *   simply states it.
+ *
+ * ## The five that do not move
+ *
+ * `bpmn.activity-dead-end`, `bpmn.fake-join`, `bpmn.implicit-split`,
+ * `bpmn.single-blank-start` and `bpmn.unlabeled-step` stay `audit` HERE TOO, and
+ * they are the reason a profile spells everything out.
+ *
+ * The first three report shapes the specification explicitly SANCTIONS: an
+ * activity with no outgoing sequence flow is a way to end a path (BPMN 2.0.2,
+ * p.151), and an activity with several incoming or several outgoing flows has
+ * defined token semantics on the same page. A warning would be the tool arguing
+ * with a house style the standard allows. They stay in the pack because on a
+ * diagram meant to be READ each of them is a question the drawing no longer asks
+ * out loud — which is a remark for the conformance panel, at every level of
+ * requirement. Every one of them is quieter than bpmnlint's own level for the
+ * same shape, deliberately.
+ *
+ * The last two report a diagram that is UNFINISHED rather than wrong — two
+ * indistinguishable blank starts, a step nobody has named — and "not done" is
+ * what a panel is for.
+ *
+ * The exact `context-map.acl-on-customer-supplier` shape, one layer over: a
+ * judgement the diagram cannot make on the author's behalf, so it is collected
+ * and never interrupts.
+ *
+ * ## Which line is which, now that a rule says so itself
+ *
+ * Every rule declares {@link ValidationRule.provenance}, so the question this
+ * table used to answer only in prose — is this a conformance defect or a
+ * suggestion — is readable off the rule. Twelve of them read a normative
+ * sentence of the standard, and those are not judgement calls: a message flow
+ * inside one pool is a sentence BPMN does not have. The other ten are a linter's
+ * rule, a reading nudge, or our own house style, and the bubble now says which
+ * before the user decides how much to care.
+ */
+const descriptive = {
+    id: 'bpmn.descriptive',
+    framework: 'bpmn',
+    labelKey: 'com.labre.bpmn.profile.descriptive',
+    fallback: 'Descriptive',
+    rules: {
+        'bpmn.sequence-flow-endpoints': 'warning',
+        // A LABRE convention (see B1a), and the one line of this table where that
+        // is worth knowing: an organisation that does not share the house style
+        // switches it off here without touching p.95, which is the whole point of
+        // having split it out of the endpoints rule.
+        'bpmn.sequence-flow-self-loop': 'warning',
+        'bpmn.message-flow-endpoints': 'warning',
+        'bpmn.association-endpoints': 'warning',
+        'bpmn.untyped-flow': 'warning',
+        'bpmn.duplicate-sequence-flow': 'warning',
+        'bpmn.start-event-no-inflow': 'warning',
+        'bpmn.start-event-must-exit': 'warning',
+        'bpmn.end-event-no-outflow': 'warning',
+        'bpmn.end-event-must-be-reached': 'warning',
+        // The five that do not move — see the header.
+        'bpmn.activity-dead-end': 'audit',
+        'bpmn.sequence-flow-stays-home': 'warning',
+        'bpmn.message-flow-crosses-pools': 'warning',
+        'bpmn.unreachable-step': 'warning',
+        'bpmn.pool-end-without-start': 'warning',
+        'bpmn.pool-start-without-end': 'warning',
+        'bpmn.single-blank-start': 'audit',
+        'bpmn.gateway-must-branch': 'warning',
+        'bpmn.gateway-join-and-fork': 'warning',
+        'bpmn.fake-join': 'audit',
+        'bpmn.implicit-split': 'audit',
+        'bpmn.unlabeled-step': 'audit',
+    },
+};
+export const BPMN_PROFILES = [
+    sketch,
+    descriptive,
+];

package/dist/roles.d.ts

@@ -0,0 +1,96 @@
+import type { BpmnNodeKind } from '@formicoidea/labre-core/model';
+import type { RoleDefs, RoleId } from '@formicoidea/labre-core/std/gfx';
+/**
+ * BPMN role vocabulary (B1).
+ *
+ * A role is the semantic identity of a BPMN artefact — no rule will ever look at
+ * a shape type, and none ever could here: the whole notation is drawn with three
+ * native shapes, and an ellipse is a start event, an end event or somebody's
+ * doodle depending entirely on what the author meant. The `kind` discriminant
+ * the pack already carries answers a different question (which glyph to paint);
+ * the role answers what the glyph MEANS.
+ *
+ * Hierarchy is DATA (`parent`), never TS inheritance: `bpmn:start-event` and
+ * `bpmn:end-event` specialise `bpmn:event`, so a rule written on the parent
+ * applies to both for free (see `roleIsA`). The three families were declared
+ * while the lean pack still shipped one or two children each, precisely so that
+ * the descriptive profile could land underneath them without a reshuffle — and
+ * that is what happened: the message and timer starts, the message and terminate
+ * ends, the user and service tasks, the sub-process, the call activity and the
+ * parallel gateway all arrived as LEAVES, and everything already written about
+ * "an event" or "an activity" stayed written.
+ *
+ * The tree is FOUR levels deep on two branches — `bpmn:message-start-event` is a
+ * `bpmn:start-event` is a `bpmn:event` is a `bpmn:flow-object`, and
+ * `bpmn:user-task` is a `bpmn:task` is a `bpmn:activity` is a
+ * `bpmn:flow-object` — which `roleIsA` walks for free.
+ *
+ * `bpmn:flow-object` arrived with the rules, for the reason its own block gives:
+ * a sequence flow chains flow objects and a step must be reachable from the
+ * start, and both sentences are about events, activities and gateways at once.
+ * It is the one word BPMN itself uses, so the rules say it once instead of
+ * enumerating three families and forgetting the fourth.
+ *
+ * The **pool** is parent-less on purpose, the same call `wardley:map` makes: it
+ * is the FRAME the flow objects are drawn in, and a rule written on the artefacts
+ * must never fall on the lane they sit in — nor, therefore, under
+ * `bpmn:flow-object`. `bpmn:data` is a family of its own for
+ * the same reason inverted: a data object is not a flow object, it is never
+ * executed, and a rule about the WORK must not fall on the paperwork. And the
+ * two artifacts — `bpmn:text-annotation` and `bpmn:group` — are parent-less AND
+ * childless, because they are what the author drew ON the picture rather than
+ * IN it: a note and a lasso, neither of which says anything the process does.
+ * The group's isolation is the spec's own (BPMN 2.0.2 §10.4 exempts it from
+ * every connection and containment constraint there is), and the tree is where
+ * that exemption is written down.
+ *
+ * ## Compatibility
+ *
+ * Nothing is backfilled. A process drawn before today carries nodes, pools and
+ * connectors with no role, so it is never evaluated and never says a word — the
+ * same promise every role in this library has made (PRD principle 8).
+ */
+/** Every role this framework declares. */
+export type BpmnRole = 'flow-object' | 'event' | 'start-event' | 'message-start-event' | 'timer-start-event' | 'end-event' | 'message-end-event' | 'terminate-end-event' | 'activity' | 'task' | 'user-task' | 'service-task' | 'sub-process' | 'call-activity' | 'gateway' | 'gateway-exclusive' | 'parallel-gateway' | 'data' | 'data-object' | 'data-store' | 'text-annotation' | 'group' | 'pool' | 'sequence-flow' | 'message-flow' | 'association';
+export type BpmnRoleId = `bpmn:${BpmnRole}`;
+/** Role ids, keyed by the `kind` used at the creation sites. */
+export declare const BPMN_ROLE: {
+    readonly flowObject: "bpmn:flow-object";
+    readonly event: "bpmn:event";
+    readonly startEvent: "bpmn:start-event";
+    readonly startEventMessage: "bpmn:message-start-event";
+    readonly startEventTimer: "bpmn:timer-start-event";
+    readonly endEvent: "bpmn:end-event";
+    readonly endEventMessage: "bpmn:message-end-event";
+    readonly endEventTerminate: "bpmn:terminate-end-event";
+    readonly activity: "bpmn:activity";
+    readonly task: "bpmn:task";
+    readonly taskUser: "bpmn:user-task";
+    readonly taskService: "bpmn:service-task";
+    readonly subProcess: "bpmn:sub-process";
+    readonly callActivity: "bpmn:call-activity";
+    readonly gateway: "bpmn:gateway";
+    readonly gatewayExclusive: "bpmn:gateway-exclusive";
+    readonly gatewayParallel: "bpmn:parallel-gateway";
+    readonly data: "bpmn:data";
+    readonly dataObject: "bpmn:data-object";
+    readonly dataStore: "bpmn:data-store";
+    readonly textAnnotation: "bpmn:text-annotation";
+    readonly group: "bpmn:group";
+    readonly pool: "bpmn:pool";
+    readonly sequenceFlow: "bpmn:sequence-flow";
+    readonly messageFlow: "bpmn:message-flow";
+    readonly association: "bpmn:association";
+};
+export declare const BPMN_ROLES: RoleDefs;
+/**
+ * The legacy `kind` discriminant → the role it means.
+ *
+ * `kind` STAYS: it is persisted, it drives the renderer and it is what the
+ * palette writes. What it is not, from today, is the semantic authority — the
+ * ROLE is. The two are posted side by side at every creation site, the way
+ * Wardley already does it, and this table is the single place that says which
+ * kind means which role. Total over {@link BpmnNodeKind} by its type, so a new
+ * kind cannot land without being given a meaning.
+ */
+export declare const BPMN_ROLE_OF_KIND: Record<BpmnNodeKind, RoleId>;