@formicoidea/labre-framework-uml 0.42.0

package/dist/rules.d.ts

@@ -0,0 +1,267 @@
+import type { EndpointTriplet, ValidationRule } from '@formicoidea/labre-core/blocks/surface';
+/**
+ * Every ordered pair of the element roles — the ALPHABET, and not a grammar.
+ *
+ * This table sanctions all four hundred and forty-one sentences — twenty-one
+ * element roles squared, since the behaviour vocabulary joined the alphabet —
+ * so a rule holding it judges none of them. It exists so {@link untypedEdge}
+ * can say "between two
+ * UML artefacts" — which is the only thing `flagNeutral` reads a matrix FOR —
+ * without inheriting a judgement that belongs to {@link actorActorAssociation}.
+ */
+export declare const UML_ELEMENT_MATRIX: readonly EndpointTriplet[];
+export declare const UML_ASSOCIATION_MATRIX: readonly EndpointTriplet[];
+/**
+ * The permissive table — every ordered pair of {@link UML_GENERALIZATION_ROLES}.
+ *
+ * Held by {@link generalizationSelfLoop} alone, for the reason C4 states: a
+ * second rule carrying the real grammar would report every wrong sentence a
+ * second time, with two brackets and two suggestions for one gesture to fix. The
+ * loop rule needs the same ALPHABET (so a generalization looped onto a note or a
+ * frame stays outside the conversation) and no grammar at all.
+ */
+export declare const UML_GENERALIZATION_ALPHABET: readonly EndpointTriplet[];
+/**
+ * The generalization GRAMMAR: like specialises like, and an instance is not a
+ * kind of anything.
+ *
+ * Four diagonal sentences and one ALPHABET entry. The fifth triplet is a link
+ * between two instances (§9.8.4) — a true sentence, carrying the ASSOCIATION
+ * role — and it is here so that `uml:object` is a role this rule speaks about:
+ * without it a generalization drawn onto an instance would be outside the
+ * alphabet and silently unjudged. `inMatrix` matches the edge role with
+ * `roleIsA`, so it can never sanction a generalization.
+ *
+ * The enumeration is absent from both ends, and that is a silence rather than a
+ * permission: a generalization between two enumerations is legal in the
+ * metamodel (an Enumeration is a DataType) and vanishingly rare on a drawing, so
+ * the pack declines to have an opinion about it.
+ */
+export declare const UML_GENERALIZATION_MATRIX: readonly EndpointTriplet[];
+/**
+ * What a REALIZATION points at: an interface, and nothing else (§10.4.3, whose
+ * `contract` end is typed `Interface`).
+ *
+ * One sentence, and an alphabet of one role — `uml:interface` specialises
+ * `uml:classifier`, so the source entry covers both ends of every realization
+ * drawn between two compartmented boxes. A realization onto a package, an
+ * object, an actor or a use case is outside the alphabet and is not judged:
+ * those are drawings of something else entirely, and the notation has no reading
+ * of them to correct.
+ */
+export declare const UML_REALIZATION_MATRIX: readonly EndpointTriplet[];
+export declare const UML_DEPENDENCY_MATRIX: readonly EndpointTriplet[];
+/**
+ * The use case diagram's grammar, whole — read by TWO rules, each seeing the
+ * slice its own edge role selects.
+ *
+ * §18.1.3 types both ends of an Include (`addition: UseCase`) and both ends of
+ * an Extend (`extendedCase: UseCase`), so the only sentence either sanctions is
+ * use case → use case. That alone would give each rule an alphabet of one role
+ * and nothing it could ever report — an include drawn from an ACTOR, which is
+ * the mistake these two exist for, would be outside the alphabet and silent.
+ *
+ * The two ASSOCIATION triplets are what fix that. They are true sentences of
+ * §18.1.3 (an actor associates with a use case) and they carry the association
+ * role, so `inMatrix` — which matches a triplet's edge with `roleIsA` — can never
+ * let them sanction an include or an extend. Their only effect is to put
+ * `uml:actor` in the alphabet both rules speak.
+ *
+ * The two rules never double-report: an edge carries one role, and the include
+ * rule reads `uml:include` while the extend rule reads `uml:extend` — flat
+ * siblings, so neither reaches the other's edges, and neither reaches the
+ * associations this table also describes.
+ */
+export declare const UML_USE_CASE_MATRIX: readonly EndpointTriplet[];
+/**
+ * What a DEPLOY may run between: an artefact onto a node, and nothing else.
+ *
+ * §19.4.4 draws it as the dashed arrow with the `«deploy»` keyword, and §19.2.3
+ * types its two ends — a DeployedArtifact onto a DeploymentTarget. `uml:node` is
+ * the parent of `uml:device` and `uml:execution-environment` (`roles.ts`), so the
+ * single sentence below reaches all three targets through `roleIsA` rather than
+ * being restated once per cube.
+ *
+ * The second triplet is an ALPHABET entry, the device the file header explains:
+ * a manifestation is a true sentence of §19.3.4, it carries the `uml:manifest`
+ * role and can therefore never sanction a deploy, and its whole effect is to put
+ * `uml:component` into the alphabet this rule speaks. Without it a `«deploy»`
+ * drawn from a component — which is the mistake this rule exists for, since a
+ * component is not what gets deployed, its artefact is — would be outside the
+ * alphabet and silently unjudged.
+ */
+export declare const UML_DEPLOY_MATRIX: readonly EndpointTriplet[];
+/**
+ * What a MANIFEST may run between: an artefact onto the element it embodies.
+ *
+ * §19.3.3 — "An Artifact may embody, or manifest, a number of model elements" —
+ * and §19.3.4 draws it as the dashed open arrow labelled `«manifest»`. The
+ * metamodel's `utilizedElement` is a PackageableElement, so a manifestation may
+ * point at a great many things; this pack draws the one §19.3.5's own figure
+ * draws, "A Manifestation relationship between an Artifact and a Component",
+ * because a component diagram is where a manifestation is drawn at all.
+ *
+ * {@link UML_DEPLOY_MATRIX}'s twin, mirrored: the foreign triplet here is the
+ * DEPLOY, which puts `uml:node` in the alphabet so that a `«manifest»` aimed at
+ * a cube — the same arrow drawn at the wrong end of the deployment story — is a
+ * finding rather than silence.
+ */
+export declare const UML_MANIFEST_MATRIX: readonly EndpointTriplet[];
+/**
+ * What a COMMUNICATION PATH may run between: two nodes.
+ *
+ * §19.4.3 is as narrow as a clause gets — "A CommunicationPath is an Association
+ * between two DeploymentTargets, through which they may exchange Signals and
+ * Messages" — and §19.4.4 draws it as the plain association link between two
+ * cubes. One sentence, and `uml:node` on both ends, so a device talking to an
+ * execution environment is sanctioned through the parent role.
+ *
+ * TWO alphabet entries this time, and both are foreign edges: they put
+ * `uml:artifact` and `uml:component` into the alphabet, which is what makes a
+ * network line drawn onto a `.jar` or onto a component box a finding. A
+ * communication path is about MACHINES talking to machines, and the wire drawn
+ * to the software running on one of them is the confusion the rule is for.
+ */
+export declare const UML_COMMUNICATION_PATH_MATRIX: readonly EndpointTriplet[];
+/**
+ * What a CONTROL FLOW may run between: the activity vertices, and never an
+ * object node.
+ *
+ * §15.7.9.4 is one of the few constraints in Clause 15 that OCL can state in a
+ * line — "ControlFlows may not have ObjectNodes at either end, except for
+ * ObjectNodes with control type" — and the exception is the reason the rule that
+ * holds this table stays a remark rather than a defect: `isControlType` is a
+ * property of the metamodel with no notation at all (§15.4.4 draws the same
+ * rectangle either way), so a canvas cannot say which of the two an author meant.
+ * The table therefore reports the drawing the specification's own default
+ * forbids, and the rule's suggestion names the exception.
+ *
+ * Twenty-five sentences over five roles, plus the four alphabet entries: the
+ * grammar judges WHICH vertices, never how many edges reach one. The counts are
+ * {@link initialNoIncomingFlow}, {@link activityFinalNoOutgoing},
+ * {@link flowFinalNoOutgoing} and {@link decisionIncomingCount}, and keeping the
+ * two apart is what stops one wrong arrow being reported twice.
+ */
+export declare const UML_CONTROL_FLOW_MATRIX: readonly EndpointTriplet[];
+export declare const UML_OBJECT_FLOW_MATRIX: readonly EndpointTriplet[];
+/**
+ * What a TRANSITION may run between: the vertices of a state machine, and
+ * nothing else.
+ *
+ * §14.5.12 in one sentence — "A Transition is a single directed arc originating
+ * from a single source Vertex and terminating on a single target Vertex" — and a
+ * Vertex is a State, a FinalState or a Pseudostate (§14.5.14). So the table is
+ * the full square over {@link UML_STATE_VERTEX_ROLES}: twenty-five sentences,
+ * judging WHICH vertices and not how many arcs reach one.
+ *
+ * ## The square is deliberate, and it is what stops the double report
+ *
+ * A transition INTO an initial disc and a transition OUT OF a final state are
+ * both wrong, and both are already said — by {@link initialNoIncomingTransition}
+ * and {@link finalStateNoOutgoing}, each of which names the side the author has
+ * to act on. Removing those two sentences from this table would make the same
+ * arrow off-matrix as well, and the user would get two brackets and two
+ * suggestions for one drag to fix. The DEGREE rules own the counts; this table
+ * owns the vocabulary.
+ */
+export declare const UML_TRANSITION_MATRIX: readonly EndpointTriplet[];
+/**
+ * What a MESSAGE may run between, sort by sort — §17.4.4, which is the one place
+ * in Clause 17 where the notation constrains an ARROW's ends rather than its
+ * shape.
+ *
+ * Three of the five sorts are the full square over {@link UML_MESSAGE_ENDS}: a
+ * call, a signal and a reply run from a participant to a participant, and the
+ * clause says nothing more. The other two each carry a sentence the
+ * specification states outright:
+ *
+ *  - a **create** message "has a dashed line with an open arrow head" and is
+ *    drawn to the HEAD of the lifeline it brings into existence (§17.4.4,
+ *    Figure 17.13), so its target is a LIFELINE and never an execution — there
+ *    is nothing to be executing on a participant that does not exist yet;
+ *  - a **delete** message "must end in a DestructionOccurrenceSpecification"
+ *    (§17.4.4, quoted in the rule's provenance), which is the X this canvas
+ *    draws as `uml:destruction`. The LIFELINE is admitted beside it, and that is
+ *    a deliberate tolerance rather than a reading of the clause: an author draws
+ *    the arrow first and drops the cross on its end afterwards, and a grammar
+ *    that indicted the intermediate state would be indicting the gesture.
+ *    `uml.strict` promotes this rule, so the tolerance is the same at both
+ *    levels — the finding that is worth having is the delete drawn onto an
+ *    EXECUTION, which is a participant carrying on after it has been destroyed.
+ *
+ * Self-loops are NOT forbidden, and §17.4.4 is explicit about why: "The send and
+ * receive events may both be on the same lifeline." A participant calling itself
+ * is the notation's own figure for a nested activation.
+ */
+export declare const UML_MESSAGE_MATRIX: readonly EndpointTriplet[];
+/**
+ * The pack, whole: forty-three rules over ten families.
+ *
+ * Sixteen in phase 1, and not that brief's seventeen ids because the actor's
+ * name and the use case's name are ONE rule: they are the same tier role, and
+ * two rules on one role report one emptied word twice (see
+ * {@link unnamedActorOrUseCase}). The structural sheets appended three — the
+ * grammars of the three edges they draw — and skipped two the engine could not
+ * be asked; one of those two came back as the forty-third rule below, once the
+ * engine grew the family it needed. The BEHAVIOUR sheets appended fifteen, which is the largest single
+ * addition this library has taken: an activity and a state machine are the two
+ * diagrams UML constrains arithmetically, so where a class diagram's pack is
+ * mostly a vocabulary these are counts, degrees and a graph walk.
+ *
+ * The SEQUENCE sheet appended four, and all four are families this pack already
+ * had — which says something about the notation rather than about the effort:
+ * an interaction's whole grammar is "who may exchange a message with whom",
+ * "what a message label says", and the two questions any tier is asked about
+ * the words in a lifeline's head. Those last two are the ones that cost a role:
+ * `uml:lifeline-ident` exists because §17.3.4 prints a BNF for a head and
+ * §18.1.4 prints none for an actor's word, and one tier carrying both would have
+ * had to ask them the same question (`roles.ts`, {@link unnamedLifeline}). The
+ * four requirements Clause 17 states that this library CANNOT state — a message
+ * never traversed upwards (§17.4.4), an execution bar sat on a lifeline's spine
+ * (§17.3.4), a create message landing on a head, an operand's guard written in
+ * brackets (§17.6.4) — are each a geometry no family expresses, and they are
+ * recorded in `docs/adr/0022` rather than approximated here. A rule that fires
+ * on the wrong thing costs more than a requirement nobody checks.
+ *
+ * The PO recette of 2026-09-16 appended the forty-third, and it is the one rule
+ * in the pack that was written down as impossible before it was written: a port
+ * dragged into the middle of its component (§11.3.4). See {@link portOnBorder},
+ * and the paragraph above the six remaining gaps on how it left that list.
+ *
+ * ## TWO of the ten families are new to the ENGINE, and they are the only ones
+ *
+ * `label-syntax` (`docs/adr/0021`) arrived with four spelling rules and carries
+ * six, and it was the first family this library added for a reason no table
+ * could meet: a notation's GRAMMAR is a parser, and the clauses these rules cite
+ * are already written as one in `grammar.ts` for the exporters.
+ * `border-proximity` (`docs/adr/0024`) is the second, and its reason is the
+ * opposite one — pure geometry that three existing families each get NEARLY
+ * right and none of them states: a distance from a glyph's centre to another
+ * artefact's outline. In both cases the family owns the walk and the pack owns
+ * the reading, and in both cases the alternative on the table was approximating
+ * the requirement with a neighbouring family. Everything else the thirty-odd
+ * roles of phases 2 and 3 needed, the engine already had.
+ *
+ * ## The other eight are the engine's, and two of them are BPMN's
+ *
+ * `role-count` and `reachability` are BPMN's, registered here with UML's own
+ * roles and nothing else: a state machine with two beginnings and a ring of
+ * states nothing enters are the same two questions a pool with two start events
+ * and an unreachable task ask. So the claim `docs/add-a-framework` makes about
+ * the seam survives the largest notation in the library twice over — the
+ * fifteen edge roles are fifteen readings of `relation-endpoints`, the four
+ * frames are the membership families C4 already uses, and the sheet's own
+ * declaration is the `view-admissibility` C4 opened.
+ *
+ * ## Several rules say one sentence twice, and the reason is always the same
+ *
+ * Five pairs — the two histories, the two initial-node counts, the two finals,
+ * the two reachability walks — are one requirement declared twice because the
+ * family that answers it names ONE role: one subject role, or one edge role.
+ * They never double-report (an element carries one role, an edge carries one
+ * role, and each pair's two halves are flat siblings), and each half carries the
+ * sentence and the authority its own half of the notation has. Where the pair
+ * could have been collapsed by inventing an ancestor role, it was not: this
+ * vocabulary's whole authority is that every role in it is the specification's.
+ */
+export declare const UML_RULES: readonly ValidationRule[];