@formicoidea/labre-framework-uml 0.42.0

package/dist/grammar.d.ts

@@ -0,0 +1,695 @@
+/**
+ * The UML member grammar, as pure parsers.
+ *
+ * ## What these read
+ *
+ * Nine BNFs, transcribed from UML 2.5.1 and cited where they are used. The
+ * first three are phase 1's, and they are the STRUCTURAL half — what a
+ * compartment of a classifier says. Three more arrived with the behaviour sheets
+ * and are the same discipline applied to a LINE rather than to a box: what a
+ * transition, an activity edge and a state's internal compartment say. The
+ * seventh is what is written beside ONE END of a line. The last two are the
+ * sequence sheet's, and they are the same discipline applied to an INTERACTION:
+ * what a lifeline's head says and what an arrow between two of them says.
+ *
+ *  - **§9.5.4** (printed p. 113) — a Property:
+ *    `[<visibility>] [`/`] <name> [`:` <prop-type>] [`[` <multiplicity-range> `]`]
+ *     [`=` <default>] [`{` <prop-modifier> [`,` <prop-modifier>]* `}`]`
+ *  - **§9.6.4** (p. 117) — an Operation:
+ *    `[<visibility>] <name> `(` [<parameter-list>] `)` [`:` [<return-type>]
+ *     [`[` <multiplicity-range> `]`] [`{` <oper-property>* `}`]]`, with
+ *    `<parameter>` from §9.4.4 (p. 110):
+ *    `[<direction>] <parameter-name> `:` <type-expression>
+ *     [`[`<multiplicity-range>`]`] [`=` <default>]`
+ *  - **§7.5.4** (p. 34) — a multiplicity range: `[ <lower> `..` ] <upper>`
+ *  - **§11.5.4** (p. 201) — what may be written beside an Association end: a
+ *    name string, a multiplicity, a `<prop-modifier>` in braces, a
+ *    `<visibility>` symbol
+ *  - **§14.2.4.8** (p. 331) — a Transition label:
+ *    `[<trigger> [`,` <trigger>]*] [`[` <guard> `]`] [`/` <behavior-expression>]`,
+ *    with `<trigger>` from §13.3.4 (p. 293): a call or signal event's name, a
+ *    `when` change event, an `after` / `at` time event, or the bare `all`
+ *  - **§15.2.4** (p. 379) — an ActivityEdge's annotations: a name near the
+ *    arrow, a guard "as text in square brackets near tail of the line", and
+ *    `weight-annotation ::= `{` `weight` `=` <value-specification> `}``
+ *  - **§14.2.4.4** (p. 320) — a State's internal activities:
+ *    `<behavior-type-label> [`/` <behavior-expression>]`, the label being one of
+ *    `entry`, `do` and `exit`
+ *  - **§17.3.4** (p. 572) — a Lifeline head:
+ *    `[<connectable-element-name> [`[` <selector> `]`]] [`:`
+ *     <connectable-element-type>] [<decomposition>]`, or the bare `self`
+ *  - **§17.4.4** (p. 576) — a Message label, request and reply together:
+ *    `[<assignment-target> `=`] <message-name> [`(` [<argument-list>] `)`]
+ *     [`:` <value-specification>]`, or the bare `*`
+ *
+ * ## Why they never throw
+ *
+ * A compartment is FREE TEXT an architect types while thinking. Half of it is a
+ * half-finished line at any moment, and a parser that threw would turn a
+ * keystroke into a broken export. So every entry point degrades: a line the
+ * grammar does not recognise comes back as `{ name: <the line> }` and travels
+ * through the exporters as an element named exactly what the author wrote. The
+ * picture keeps saying what it said; the file says the same thing, less
+ * structured.
+ *
+ * ## Purity
+ *
+ * Strings in, plain records out. No `std`, no DOM, no clock, no randomness — the
+ * same discipline `c4/export.ts` and `bpmn/export.ts` hold, and for the same
+ * reason: a host can call these, a test can call them with literals, and the
+ * same compartment always parses to the same record.
+ */
+/** The four VisibilityKind values UML's `<visibility>` terminal can spell. */
+export type UmlVisibility = 'public' | 'private' | 'protected' | 'package';
+/**
+ * A visibility marker as its VisibilityKind — `undefined` for anything else.
+ *
+ * `~` is `package` and not "default": §7.4 gives all four a glyph, and an
+ * omitted marker means the author has not said, which is a different statement
+ * from package visibility and is why the callers leave the field absent.
+ */
+export declare function visibilityOf(marker: string): UmlVisibility | undefined;
+/**
+ * A multiplicity range — `0..*` as `{ lower: 0, upper: '*' }`.
+ *
+ * `upper` is `number | '*'` rather than a number with `Infinity` or `-1` as a
+ * sentinel, because `*` is what the file has to say: XMI writes it as the
+ * `value` of a `LiteralUnlimitedNatural`, and PlantUML prints it. A sentinel
+ * would have to be translated back at both ends and is one convention away from
+ * a `-1` reaching a document.
+ */
+export interface UmlMultiplicity {
+    lower: number;
+    upper: number | '*';
+}
+/**
+ * A multiplicity range, brackets optional — `undefined` when it is not one.
+ *
+ * §7.5.4's `[ <lower> '..' ] <upper>`, plus the two readings the clause states
+ * around it:
+ *
+ *  - a bare `<upper>` means `lower = upper` — `1` is exactly one;
+ *  - `*` is the unlimited upper bound, and a bare `*` is §7.5.4's shorthand for
+ *    `0..*` (the clause's own "0..* … may be abbreviated to *").
+ *
+ * The brackets are stripped rather than required, because the SAME range is
+ * written both ways depending on where it sits: `[0..1]` inside a property line
+ * (§9.5.4 puts it in brackets) and `0..1` beside an association end (§11.5.4
+ * does not). One parser, both call sites.
+ *
+ * `<lower>` and `<upper>` are ValueSpecifications in the metamodel, so `n..m`
+ * with symbolic bounds is legal UML. It parses to `undefined` here on purpose:
+ * this module's callers write bounds into files as integers, and a made-up
+ * integer for `n` would be a fact the author never stated. A symbolic range
+ * survives instead as part of the line's own text.
+ */
+export declare function parseMultiplicity(raw: string): UmlMultiplicity | undefined;
+/** One line of an attribute compartment, as the grammar reads it. */
+export interface UmlProperty {
+    /** Absent when the author wrote no marker — see {@link visibilityOf}. */
+    visibility?: UmlVisibility;
+    /** The `/` of §9.5.4: this Property is derived. */
+    isDerived: boolean;
+    name: string;
+    /** `<prop-type>` — the name of a Classifier, resolved by the exporters. */
+    type?: string;
+    multiplicity?: UmlMultiplicity;
+    /** `<default>`, verbatim: it is an expression, and we do not evaluate it. */
+    defaultValue?: string;
+    /** `<prop-modifier>`s, in order, each trimmed and otherwise verbatim. */
+    modifiers: string[];
+    /**
+     * `true` only when `{static}` was written.
+     *
+     * A static feature is UNDERLINED in UML (§9.2.4), and an underline is not a
+     * character: nothing in a plain-text compartment can carry it, so it cannot be
+     * detected here. `{static}` is the spelling that survives a text round-trip,
+     * and the field is absent rather than `false` when nothing said so — "not
+     * stated" and "stated not static" are different, and only one of them is in
+     * the line.
+     */
+    isStatic?: boolean;
+}
+/**
+ * One attribute line, per §9.5.4.
+ *
+ * Parsed from the RIGHT, which is what makes the optional parts optional: the
+ * modifier group, then the default, then the multiplicity, then the type — each
+ * peeled off the tail it is the last thing on. Parsing left to right would have
+ * to guess where the name ends, and a name with a space in it (`order date`) is
+ * legal UML.
+ *
+ * `=` is split on its FIRST occurrence, because §9.5.4 puts the default last of
+ * the three and an expression may contain `==`. A `:` inside a default —
+ * `= {a: 1}` — therefore survives, since the type split happens on what is left
+ * after the default is gone.
+ *
+ * A line the grammar cannot see structure in keeps all of itself:
+ * `parseProperty('???')` is a property NAMED `???`. That is the degradation
+ * contract at the top of this file, and it is what lets a compartment be typed
+ * into rather than filled in.
+ */
+export declare function parseProperty(line: string): UmlProperty;
+/** `<direction>` — §9.4.4's three, plus the one XMI writes for a result. */
+export type UmlParameterDirection = 'in' | 'out' | 'inout' | 'return';
+/** One entry of a `<parameter-list>`. */
+export interface UmlParameter {
+    /**
+     * Absent when the author wrote none. §9.4.4 says an omitted direction
+     * "defaults to `in`", and the DEFAULT is applied by the writer that needs one
+     * rather than invented here: the parsers report what the line says.
+     */
+    direction?: UmlParameterDirection;
+    name: string;
+    type?: string;
+    multiplicity?: UmlMultiplicity;
+    defaultValue?: string;
+}
+/** One line of an operation compartment, as the grammar reads it. */
+export interface UmlOperation {
+    visibility?: UmlVisibility;
+    name: string;
+    parameters: UmlParameter[];
+    returnType?: string;
+    returnMultiplicity?: UmlMultiplicity;
+    /** `<oper-property>`s — `query`, `redefines x`, `ordered`, a constraint. */
+    modifiers: string[];
+    /** See {@link UmlProperty.isStatic}: `{static}`, never an underline. */
+    isStatic?: boolean;
+    /** `{abstract}` — §9.2.4's text alternative to an italic name. */
+    isAbstract?: boolean;
+}
+/**
+ * One operation line, per §9.6.4.
+ *
+ * The parentheses are the anchor: everything before the `(` is the visibility
+ * and the name, everything inside is the `<parameter-list>`, and everything
+ * after is the optional return part and the `<oper-property>` group. A line with
+ * no parentheses is not an operation the grammar can see — it degrades to a
+ * NAME, exactly as a property does, and an author halfway through typing
+ * `place` keeps their word.
+ *
+ * `{abstract}` is reported separately from `modifiers` (which keeps it too),
+ * because §9.2.4's marker decides a metamodel FLAG — `isAbstract` on the
+ * Operation — where the rest of the group is notation a writer passes through.
+ */
+export declare function parseOperation(line: string): UmlOperation;
+/**
+ * The lines of a compartment that SAY something — trimmed, in order.
+ *
+ * Two kinds of line are dropped and both are notation rather than content:
+ *
+ *  - a blank line, which is spacing;
+ *  - an ellipsis — `...` or `…` — which is §9.2.4's ELISION marker. It means
+ *    "there are more features, not shown", and a file that wrote it back as a
+ *    property named `...` would turn "some are hidden" into "one is called dot
+ *    dot dot".
+ */
+export declare function parseCompartment(text: string | undefined | null): string[];
+/**
+ * What is written BESIDE one end of an association line.
+ *
+ * §11.5.4 (printed p. 201) names exactly what may sit there: "A name string may
+ * be placed near the end of the line to show the name of the Association end",
+ * and "various other notations can be placed near the end of the line as
+ * follows: a multiplicity … a `<prop-modifier>` enclosed in curly braces … a
+ * `<visibility>` symbol".
+ *
+ * Three of the four are read; the modifier group is not, and that is the same
+ * call {@link parseActivityEdge} makes about `{stream}` — it is notation this
+ * pack does not model, and folding it into the role would rename the end. It
+ * survives in {@link raw}, which is why {@link raw} is not optional: whatever
+ * the author typed is kept verbatim, so a label the grammar reads as nothing at
+ * all is still the author's words on the board and in the file.
+ */
+export interface UmlAssociationEnd {
+    /** §7.5.4's range, brackets optional — `0..*`, `1`, `[0..1]`. */
+    multiplicity?: UmlMultiplicity;
+    /** The end's NAME — the Property the far classifier sees (§11.5.4). */
+    role?: string;
+    /** Absent when the author wrote no marker — see {@link visibilityOf}. */
+    visibility?: UmlVisibility;
+    /** Exactly what was written beside the end, trimmed. Never absent. */
+    raw: string;
+}
+/**
+ * `0..* items` → a multiplicity and a role; `- owner` → a private role.
+ *
+ * MULTIPLICITY FIRST, and only from the leading token: §11.5.4 places both a
+ * name and a range beside the end with no separator between them, so something
+ * has to decide which half is which, and the leading token is the half that can
+ * be decided WITHOUT guessing — `0..*`, `1`, `*` and `[0..1]` are a closed
+ * grammar (§7.5.4), and a word is not. A leading token that does not parse as a
+ * range therefore stays part of the name, which is what keeps `1st choice` an
+ * end called "1st choice" rather than a multiplicity of one.
+ *
+ * The visibility marker is read on either side of the range — `- owner` and
+ * `+ 0..1 a` both — because §11.5.4 lists the three adornments without fixing an
+ * order between them, and an author who writes the marker first is writing the
+ * order §9.5.4 uses for a property.
+ *
+ * Never throws and never returns nothing: an end label is free text an architect
+ * typed beside a line, and the same degradation the rest of this module holds to
+ * applies — a label the grammar recognises nothing in comes back as `{ raw }`
+ * plus a role that is the whole of it.
+ */
+export declare function parseEndLabel(label: string | undefined | null): UmlAssociationEnd;
+/** The glyph §7.4 gives a VisibilityKind — the inverse of {@link visibilityOf}. */
+export declare function visibilityMarker(visibility: UmlVisibility): string;
+/**
+ * §7.5.4's range, spelled the way a diagram spells it — `1`, `0..1`, `0..*`.
+ *
+ * Only ONE of the clause's two abbreviations is used: an exact range is written
+ * as the single bound (`1..1` is `1`, which is how every diagram in the
+ * specification writes it), and an unbounded one is written in full (`0..*`
+ * rather than the bare `*` §7.5.4 also permits). The asymmetry is deliberate —
+ * `*` is the spelling that reads as "unfinished" beside a line, and the full
+ * form is what PlantUML, Papyrus and draw.io all print. Both parse back to the
+ * same record, so nothing is lost either way; this is the one that is read.
+ */
+export declare function formatMultiplicity(multiplicity: UmlMultiplicity): string;
+/**
+ * An end's adornments, back in one string — `0..* -items`.
+ *
+ * The inverse of {@link parseEndLabel}, in §11.5.4's own order: the range, then
+ * the visibility glyph, then the name. An end the grammar read nothing
+ * structural out of prints its {@link UmlAssociationEnd.raw} instead, so a label
+ * this module does not understand still comes back exactly as it was typed —
+ * the whole point of keeping `raw`.
+ */
+export declare function formatEndLabel(end: UmlAssociationEnd): string;
+/**
+ * WHICH of §13.3.4's five notations a trigger is written in.
+ *
+ * `call-or-signal` is one value for two metaclasses, and the specification is
+ * the reason: "SignalEvent triggers and CallEvent triggers are not
+ * distinguishable by syntax and must be discriminated by their declaration
+ * elsewhere" (§14.2.4.8). A canvas holds no such declaration, so a parser that
+ * returned one of the two would be inventing the half of the fact the notation
+ * does not carry. The XMI writer therefore mints the one metaclass that is true
+ * of both readings, and the drawing keeps what the author typed.
+ */
+export type UmlTriggerKind = 'call-or-signal' | 'any-receive' | 'change' | 'relative-time' | 'absolute-time';
+/** One `<trigger>` of §13.3.4, classified and kept whole. */
+export interface UmlTrigger {
+    kind: UmlTriggerKind;
+    /** The trigger as the author wrote it, trimmed — what a writer prints back. */
+    text: string;
+    /**
+     * What follows the KEYWORD: `5 seconds` after an `after`, `Jan 1` after an
+     * `at`, `stock = 0` after a `when`. Absent for `all`, which has no argument,
+     * and for a call or signal event, whose payload is {@link UmlTrigger.name}.
+     */
+    expression?: string;
+    /** The Operation's or the Signal's name — a call or signal event only. */
+    name?: string;
+    /** `(a, b)`'s contents, verbatim — §13.3.4's `<assignment-specification>`. */
+    assignment?: string;
+}
+/**
+ * One trigger, classified per §13.3.4.
+ *
+ * Total and never throwing, exactly like every parser above it: a word the
+ * clause has no notation for is a `call-or-signal`, which is the reading
+ * §14.2.4.8 itself gives to an undecorated name. So the fallback is the
+ * specification's own default rather than an error state.
+ *
+ * The keywords are matched case-insensitively and reported LOWERCASE in
+ * {@link UmlTrigger.kind} while {@link UmlTrigger.text} keeps the author's
+ * capitals: the classification is a fact about the notation, the text is a fact
+ * about the drawing, and neither should be made to speak for the other.
+ */
+export declare function parseTrigger(raw: string): UmlTrigger;
+/**
+ * The inside of a `[…]` guard — `undefined` when there is nothing in it.
+ *
+ * The brackets are OPTIONAL on the way in, for the same reason
+ * {@link parseMultiplicity} strips its own: the same guard is written both ways
+ * depending on where it sits. §15.2.4 puts an activity edge's guard in brackets
+ * beside the line and §14.2.4.8 puts a transition's in brackets inside the
+ * label, while a caller that has already split a label on its brackets holds the
+ * bare expression. One parser, both call sites.
+ */
+export declare function parseGuard(raw: string | undefined | null): string | undefined;
+/** A transition label, as §14.2.4.8's three optional parts. */
+export interface UmlTransitionLabel {
+    /** `<trigger> [',' <trigger>]*`, in order, each trimmed and verbatim. */
+    triggers: string[];
+    /** `'[' <guard> ']'`, without its brackets. */
+    guard?: string;
+    /** `'/' <behavior-expression>` — an expression, kept exactly as written. */
+    effect?: string;
+}
+/**
+ * One transition label, per §14.2.4.8:
+ *
+ * `[<trigger> [',' <trigger>]*] ['[' <guard> ']'] ['/' <behavior-expression>]`
+ *
+ * Every part is optional and an empty label is a legal transition — §14.2.4.8's
+ * outermost brackets say so, and a completion transition (one that fires when
+ * its source state finishes) is written with no label at all. So the empty
+ * string parses to `{ triggers: [] }` rather than to a trigger named nothing.
+ *
+ * ## Read left to right, and anchored on the GUARD
+ *
+ * The guard is the only part with a delimiter at both ends, so it is found
+ * first: the first top-level `[` opens it and its matching `]` closes it.
+ * Everything before is the trigger list, and the first top-level `/` after it
+ * opens the effect. A label with no guard splits on its first top-level `/`
+ * instead, which is the same rule with the anchor missing.
+ *
+ * ## The one degradation, stated
+ *
+ * A bare change event holding a slash — `when x/2 > 1`, with no guard and no
+ * effect — reads its `/` as the effect separator and comes back as the trigger
+ * `when x` with the effect `2 > 1`. §13.3.4's `<value-specification>` is an
+ * arbitrary expression and the notation gives it no delimiters, so no reading of
+ * a flat string can tell the two apart; bracketing the expression, which is
+ * legal, resolves it. Stated here rather than discovered in an export.
+ */
+export declare function parseTransition(label: string | undefined | null): UmlTransitionLabel;
+/** What an activity edge's label says — §15.2.4's name, guard and weight. */
+export interface UmlActivityEdgeLabel {
+    /** The edge's own name, "notated near the arrow" (§15.2.4). */
+    name?: string;
+    /** "Guards are shown as text in square brackets near tail of the line." */
+    guard?: string;
+    /**
+     * `{weight = <value-specification>}`, as the VALUE alone.
+     *
+     * A string rather than a number because §15.2.4's own grammar admits `*` for
+     * an unlimited weight and a ValueSpecification for everything else — an
+     * expression, a constant, the name of a Property. The same call
+     * {@link UmlMultiplicity} makes about `*`, one clause over.
+     */
+    weight?: string;
+}
+/**
+ * One activity edge's centre label, split into what §15.2.4 writes around a
+ * line.
+ *
+ * Three annotations sharing one text, because this canvas gives a connector ONE
+ * label (`docs/adr/0018`) where the notation places three things at three points
+ * along the arrow. The delimiters are the notation's own — brackets for the
+ * guard, braces for the weight — so an author who writes
+ * `ready [stock > 0] {weight = 2}` gets all three read back, and one who writes
+ * only a word gets a named edge.
+ *
+ * Whatever is left once the bracketed and braced groups are lifted out is the
+ * NAME, which is why a label with no delimiters is a name and not a guard: a
+ * guard is bracketed in §15.2.4 and inventing one from a bare word would put a
+ * condition in a file that the drawing does not show.
+ *
+ * A braced group that is not a `weight-annotation` — `{stream}`, `{ordered}` —
+ * is dropped rather than folded into the name: it is notation this pack does not
+ * model, and gluing it onto the edge's name would rename the edge.
+ */
+export declare function parseActivityEdge(label: string | undefined | null): UmlActivityEdgeLabel;
+/** Which of §14.2.4.4's three `<behavior-type-label>`s a line carries. */
+export type UmlStateBehaviorKind = 'entry' | 'do' | 'exit';
+/** One line of a state's internal activities compartment. */
+export interface UmlStateBehavior {
+    kind: UmlStateBehaviorKind;
+    /**
+     * `<behavior-expression>` — absent when the author wrote the label and no
+     * expression, which is a line somebody is halfway through.
+     */
+    expression?: string;
+}
+/**
+ * `entry / x`, `do / y`, `exit / z` — §14.2.4.4's internal activities.
+ *
+ * `undefined` for every other line, and that is what makes the reading safe: a
+ * state's compartment holds internal TRANSITIONS too (§14.2.4.4's next
+ * compartment, `{<trigger>}* ['[' <guard> ']'] [/<behavior-expression>]`) and
+ * ordinary prose besides. Only the three labels the clause names are lifted out;
+ * everything else stays a line of the compartment, which is what
+ * {@link parseCompartment} already hands over.
+ *
+ * The separator is optional on the way in — `entry x` reads as `entry / x` —
+ * because the slash is the one character of this syntax an author routinely
+ * forgets, and the label alone is unambiguous about what the rest of the line
+ * is.
+ */
+export declare function parseStateBehavior(line: string): UmlStateBehavior | undefined;
+/**
+ * §15.2.4's three annotations, back in one string — `name [guard] {weight = w}`.
+ *
+ * The inverse of {@link parseActivityEdge}, and it lives beside it for the
+ * reason every parser and printer pair should: the notation is one grammar, and
+ * two files spelling it separately is how a guard comes back without its
+ * brackets. Read by the PlantUML writer (which puts it on the arrow) and by the
+ * importers' materializer (which puts it in the connector's centre label), so a
+ * flow drawn from a file and one exported to one carry the same words.
+ */
+export declare function formatActivityEdgeLabel(label: UmlActivityEdgeLabel): string;
+/**
+ * §14.2.4.8's label, back in one string — `trigger1, trigger2 [guard] / effect`.
+ *
+ * The inverse of {@link parseTransition}, and a round trip rather than the
+ * author's own text passed through: the model holds the parsed parts, and
+ * printing them in the BNF's own order is what makes a label somebody typed
+ * loosely — a guard before its trigger, a missing space — come out spelled the
+ * way the clause spells it.
+ */
+export declare function formatTransitionLabel(label: UmlTransitionLabel): string;
+/**
+ * The STRICT half of this module, and the `label-syntax` rules' whole verdict.
+ *
+ * Everything above degrades: a line the grammar cannot see structure in comes
+ * back as `{ name: <the line> }` and travels through the exporters as an element
+ * named exactly what the author wrote. That is the right answer for a WRITER —
+ * the picture keeps saying what it said — and it is no answer at all for a
+ * CHECKER, which is being asked precisely whether the degradation happened.
+ *
+ * So the checkers below re-ask the same question with the opposite bias, and
+ * they change nothing about the parsers: `parseProperty`, `parseOperation`,
+ * `parseTransition` and `parseMultiplicity` return exactly what they returned
+ * before this section existed, and the exporters read exactly what they read.
+ *
+ * ## The one rule every checker follows
+ *
+ * **A line is `ok: false` when the lenient parse LOST something.** Not when it
+ * is terse, not when it omits an optional part — §9.5.4 makes everything but
+ * `<name>` optional and a bare `balance` is a conformant Property — but when a
+ * part the author actually WROTE is not in the record: a `:` with no type after
+ * it, a `[…]` that is not a multiplicity range, an operation with no parameter
+ * list, a `/` with no behaviour behind it. Those are the cases where the drawing
+ * and the exported file stop saying the same thing, and they are the only ones
+ * a user can act on.
+ *
+ * That rule is what keeps these checks honest about the specification. A stricter
+ * reading — "an attribute must carry a type" — would indict a conformant line,
+ * and the `provenance: 'standard'` these rules declare would be claiming UML
+ * forbids what UML does not.
+ *
+ * ## The reason is a FRAGMENT, in English
+ *
+ * The engine prints it after the offending line (`validation.ts`
+ * `evaluateLabelSyntax`), so the two read as one sentence. The framework owns
+ * the word, as it owns every other `*Fallback` it ships.
+ */
+export interface UmlSyntaxCheck {
+    /** The line is spelled the way the clause spells it. */
+    ok: boolean;
+    /** Why it is not, when it is not — see the header. */
+    reason?: string;
+}
+/**
+ * One attribute line, checked against §9.5.4 —
+ * `[<visibility>] ['/'] <name> [':' <type>] ['[' <mult> ']'] ['=' <default>]
+ * ['{' <modifiers> '}']`.
+ *
+ * Built on {@link parseProperty} and changing nothing about it. An empty line is
+ * `ok`: the family that calls this never passes one, and a total function is
+ * easier to reason about than one with a precondition.
+ *
+ * ## The parenthesis case, and why it is worth its own sentence
+ *
+ * `place(order)` typed into the ATTRIBUTES compartment is the single most common
+ * mistake this rule catches, and it is not a spelling mistake — it is a line in
+ * the wrong box. The check runs on what is left once the default value is peeled
+ * off, so `origin : Point = Point(0, 0)` keeps its parentheses and its silence.
+ */
+export declare function checkPropertyLine(line: string): UmlSyntaxCheck;
+/**
+ * One operation line, checked against §9.6.4 —
+ * `[<visibility>] <name> '(' [<parameter-list>] ')' [':' [<return-type>]
+ * ['[' <mult> ']'] ['{' <oper-property>* '}']]`.
+ *
+ * Built on {@link parseOperation} and changing nothing about it. This is the one
+ * checker with a genuine FALL-BACK to report: a line with no parentheses is not
+ * an operation the grammar can see at all, and `parseOperation` says so by
+ * returning the whole line as a name. An author halfway through typing `place`
+ * gets that silence from the rule's `audit` severity, not from the grammar.
+ */
+export declare function checkOperationLine(line: string): UmlSyntaxCheck;
+/**
+ * One transition label, checked against §14.2.4.8 —
+ * `[<trigger> [',' <trigger>]*] ['[' <guard> ']'] ['/' <behavior-expression>]`.
+ *
+ * Built on {@link parseTransition} and changing nothing about it. An EMPTY label
+ * is `ok` and that is the clause's own reading: a completion transition — one
+ * that fires when its source state finishes — is written with no label at all,
+ * so a rule indicting the empty string would indict half the state machines ever
+ * drawn.
+ *
+ * The parser's two documented tolerances are exactly what this reports: an
+ * unclosed `[` ("a guard somebody is still typing") and a `/` with nothing
+ * behind it.
+ */
+export declare function checkTransitionLabel(label: string | undefined | null): UmlSyntaxCheck;
+/**
+ * One multiplicity, checked against §7.5.4 — `[<lower> '..'] <upper>`, brackets
+ * optional.
+ *
+ * The thinnest of the four: {@link parseMultiplicity} already answers
+ * `undefined` for everything that is not a range, so this is that answer with a
+ * sentence attached. The one case worth naming is the SYMBOLIC range — `n..m` is
+ * legal UML and parses to `undefined` here on purpose (the module's callers write
+ * integer bounds into files, and inventing one for `n` would be a fact the author
+ * never stated), so the reason says what the writers can hold rather than what
+ * the specification permits.
+ */
+export declare function checkMultiplicity(raw: string): UmlSyntaxCheck;
+/**
+ * The multiplicity an ASSOCIATION END's label opens with, when it opens with one
+ * at all — §11.5.4 beside §7.5.4.
+ *
+ * Reads the label exactly as {@link parseEndLabel} does (visibility marker off
+ * the front, then the leading token, brackets optional) and then asks
+ * {@link checkMultiplicity} about that token — but only when the token is an
+ * attempt at a range. Everything else on an end label is the ROLE name, which is
+ * free text and has no syntax to be wrong about.
+ *
+ * So `0..*`, `1`, `[0..1]` and `0..* items` are silent, `1..n` and `0...*` are
+ * reported, and `items`, `- owner` and `1st choice` are none of this rule's
+ * business.
+ */
+export declare function checkEndLabelMultiplicity(label: string | undefined | null): UmlSyntaxCheck;
+/**
+ * What a LIFELINE's head says, per §17.3.4 —
+ * `[<name> ['[' <selector> ']']] [':' <type>]`.
+ *
+ * Every part is optional, and the specification means it: `: Order` is an
+ * anonymous participant of a known type, `o` is a named one of no stated type,
+ * and `self` is the object that encloses the Interaction (which this parser
+ * reads as a lifeline NAMED `self` — the grammar's own alternative, kept as
+ * words rather than promoted to a flag nothing here would read).
+ *
+ * `<decomposition>` — §17.3.4's trailing `ref <interactionident> [strict]` — is
+ * NOT modelled: an interaction use is drawn on this canvas as a fragment with
+ * the `ref` operator (ADR 0022), so a decomposition written into a head has no
+ * second home and stays part of whichever part it was typed into.
+ */
+export interface UmlLifelineIdent {
+    /** `<connectable-element-name>`. Absent when the head names no participant. */
+    name?: string;
+    /** `<connectable-element-type>` — what follows the `:`. */
+    type?: string;
+    /** `<selector>` — the expression inside the `[ ]` after the name. */
+    selector?: string;
+}
+/**
+ * One lifeline head, per §17.3.4.
+ *
+ * Peeled from the RIGHT like every other parser here: the `:` type first (the
+ * last of the three parts), then the trailing `[ ]` selector, and what is left
+ * is the name. Splitting on the FIRST top-level `:` keeps a type expression that
+ * carries one of its own (`: Map[String, Int]`) whole, and the depth count is
+ * what keeps a selector holding a colon (`accounts[k : Key]`) out of the split.
+ *
+ * Degrades like the rest of this module: a head the grammar cannot see structure
+ * in is a lifeline NAMED exactly what the author wrote, and an empty head is an
+ * empty record rather than a throw — §17.3.4 says a `<lifelineident>` cannot be
+ * empty, and reporting that is `label-presence`'s job and not a parser's.
+ */
+export declare function parseLifelineIdent(text: string | undefined | null): UmlLifelineIdent;
+/**
+ * What a MESSAGE's label says, per §17.4.4 — the request and the reply
+ * productions read as ONE shape, because an arrow on this canvas carries one
+ * text and the reader is not told which of the two grammars to use.
+ *
+ * `<request-message-label> ::= <message-name> ['(' [<input-argument-list>] ')']`
+ * is the reply production minus the assignment target and the return value, so a
+ * parser for the wider one reads both and a request label simply comes back with
+ * those two absent. The rule that reads this (`uml.message-syntax`) is written
+ * on `uml:message`, the parent of all five sorts, for exactly that reason.
+ */
+export interface UmlMessageLabel {
+    /** `<assignment-target>` — what is written before the `=`. */
+    assign?: string;
+    /**
+     * `<message-name>`. Always present, `''` when the label has none: the checker
+     * is what reports that, and a caller writing a file wants one slot to read.
+     */
+    name: string;
+    /**
+     * The argument list, RAW and in order — `[]` for `m()`, absent for `m`.
+     *
+     * The distinction is the clause's own: §17.4.4 says an empty pair of
+     * parentheses may still be written after the name, so "no list at all" and
+     * "an empty list" are two things an author typed differently and a writer
+     * should be able to tell apart.
+     *
+     * Each entry is the text between two top-level commas, trimmed — never parsed
+     * further. §17.4.4 admits four spellings of an argument (`v`, `-`, `n = v`,
+     * `n : v`) and what a writer does with them differs per format, so the split
+     * is shared and the reading is not.
+     */
+    args?: string[];
+    /** `<value-specification>` — what follows the `:` at the very end. */
+    returnValue?: string;
+}
+/**
+ * One message label, per §17.4.4.
+ *
+ * The parentheses are the anchor, exactly as they are for an operation
+ * ({@link parseOperation}): everything before the `(` is the assignment target
+ * and the name, everything inside is the argument list, and everything after is
+ * the optional `: <value-specification>`. A label with no parentheses is split
+ * on its first top-level `:` instead, so `ok : true` still says what it says.
+ *
+ * `*` — §17.4.4's shorthand for "a message of any type" — comes back as a
+ * message NAMED `*`. That is the degradation contract of this module rather than
+ * a reading of the clause: the shorthand stands for a combined fragment this
+ * canvas does not draw (ADR 0022), so the honest thing is to keep the author's
+ * character and let the writers pass it through.
+ */
+export declare function parseMessageLabel(text: string | undefined | null): UmlMessageLabel;
+/**
+ * One lifeline head, checked against §17.3.4 —
+ * `[<name> ['[' <selector> ']']] [':' <type>]`.
+ *
+ * Built on {@link parseLifelineIdent} and changing nothing about it. An empty
+ * head is `ok` here even though §17.3.4 says a `<lifelineident>` cannot be
+ * empty: the family that calls this never passes an empty line, and "this
+ * lifeline has no name" is a question `label-presence` already asks with its own
+ * id and its own sentence (`uml.unnamed-lifeline`). Two rules reporting one
+ * emptied head would be two brackets on one word to fix.
+ *
+ * ## The parenthesis case
+ *
+ * `place(order)` typed into a lifeline head is a MESSAGE label written on the
+ * wrong artefact, which is the same mistake — and the same sentence — that
+ * {@link checkPropertyLine} catches when an operation is typed into an attribute
+ * compartment. §17.3.4 gives a head no parentheses at all.
+ */
+export declare function checkLifelineIdent(line: string | undefined | null): UmlSyntaxCheck;
+/**
+ * One message label, checked against §17.4.4 — the request and the reply
+ * productions together, since the arrow carries one text.
+ *
+ * Built on {@link parseMessageLabel} and changing nothing about it. An EMPTY
+ * label is `ok`, and that is the clause's own reading twice over: §17.4.4 makes
+ * the label optional, and a sequence diagram is drawn arrows-first with the
+ * words added afterwards. `*` is `ok` for the same reason
+ * {@link parseMessageLabel} keeps it — it is a spelling the specification
+ * prints.
+ *
+ * Reports exactly the four ways the lenient parse LOSES something: a bracket
+ * still open, an argument between two commas, text after the `)` that is neither
+ * a return value nor nothing, and a `:` or an `=` with nothing on the side that
+ * has to carry words.
+ */
+export declare function checkMessageLabel(line: string | undefined | null): UmlSyntaxCheck;