@formicoidea/labre-core 0.40.0 → 0.42.0

package/dist/_pkgs/affine-block-surface/extensions/validation.d.ts

@@ -89,8 +89,23 @@ export type ProfileSeverity = ViolationSeverity | 'off';
  *   VIEW rather than of the artefact: every other one starts from a subject and
  *   looks around it, this one starts from the sheet and asks what has been
  *   drawn on it.
+ * - `label-syntax` — the subject's words must be SPELLED the way the notation
+ *   spells them. `label-presence` asks whether anything is written; this one
+ *   asks whether what is written parses. The first family whose verdict comes
+ *   out of a function the FRAMEWORK ships rather than out of a table the engine
+ *   interprets — a notation's grammar is a grammar, and no amount of declarative
+ *   data is going to express `[<visibility>] [/] <name> [: <type>]`. See
+ *   {@link LabelSyntaxDef} and `docs/adr/0021`.
+ * - `border-proximity` — the subject must sit ON the OUTLINE of a carrier NODE,
+ *   within a declared tolerance. The family of "a port is a small square on the
+ *   border of the component that owns it" (UML §11.3.4), and the first one whose
+ *   frame of reference is another ARTEFACT's edge rather than the sheet's:
+ *   `attachment` measures a distance to a PATH and refuses a node carrier,
+ *   `element-in-background` demands full containment — which a glyph straddling
+ *   the edge breaks by construction — and `no-overlap` has the opposite polarity
+ *   and no tolerance. See {@link BorderProximityDef} and `docs/adr/0024`.
  */
-export type RuleFamily = 'element-in-background' | 'orientation-against-axis' | 'attachment' | 'no-overlap' | 'relative-order-along-axis' | 'relation-endpoints' | 'element-in-zone' | 'tone-convention' | 'majority-fact' | 'edge-degree' | 'role-count' | 'edge-locality' | 'reachability' | 'label-presence' | 'view-admissibility';
+export type RuleFamily = 'element-in-background' | 'orientation-against-axis' | 'attachment' | 'no-overlap' | 'relative-order-along-axis' | 'relation-endpoints' | 'element-in-zone' | 'tone-convention' | 'majority-fact' | 'edge-degree' | 'role-count' | 'edge-locality' | 'reachability' | 'label-presence' | 'label-syntax' | 'view-admissibility' | 'border-proximity';
 /**
  * What a verdict on one subject depends on (PF5.3). Ordered: each level
  * includes the previous.
@@ -844,6 +859,116 @@ export interface LabelPresenceDef {
      */
     present: true;
 }
+/**
+ * WHICH of an element's labels a `label-syntax` rule reads.
+ *
+ * `'center-label'` is the element's own `text` — the one property every
+ * artefact-bearing model carries, and the same slot {@link elementLabel} reads.
+ * The other two are the connector's per-END labels (`docs/adr/0020`), which is
+ * the whole reason this discriminant exists: a multiplicity is written at the
+ * end of an association and NOT in the middle of it, so a rule about `0..*` has
+ * to be able to say which of the three labels it is about.
+ *
+ * `'end-labels'` is the two ends TOGETHER, one per line. §11.5.4 puts the same
+ * grammar at both ends of an association, so a rule naming one end could only
+ * ever check half of every line drawn — and two rules would be two ids, two
+ * sentences and two entries in every profile table for one requirement. The
+ * per-line walk is what makes this honest rather than a shortcut: each end is
+ * judged on its own, and the finding quotes whichever one is wrong.
+ *
+ * Named after the notation's positions rather than after the props they live in,
+ * so a rule reads as a sentence about a drawing and the mapping to model props
+ * stays one table in this file ({@link LABEL_PROPS}).
+ */
+export type LabelTarget = 'center-label' | 'source-label' | 'target-label' | 'end-labels';
+/** What a {@link LabelSyntaxDef.parse} says about ONE line. */
+export interface LabelSyntaxVerdict {
+    /** The line is spelled the way the notation spells it. */
+    ok: boolean;
+    /**
+     * WHY it is not, in the framework's own words, when it is not — a fragment,
+     * not a sentence: "no parentheses", "the multiplicity is not a range". The
+     * family prints it after the offending line, so the two read together.
+     *
+     * Absent on an `ok` verdict, and absent on a failure the framework has nothing
+     * more precise to say about. English, like every other `*Fallback` in a rule
+     * declaration: the framework owns the word, the engine never invents one.
+     */
+    reason?: string;
+}
+/**
+ * `label-syntax` configuration — the subject's words must PARSE.
+ *
+ * The sibling of {@link LabelPresenceDef}, one question further on. That family
+ * asks whether an artefact says anything at all; this one asks whether what it
+ * says is spelled the way the notation spells it — `- balance : Money = 0`
+ * against §9.5.4, `0..*` against §7.5.4, `after 5 s [ready] / open` against
+ * §14.2.4.8.
+ *
+ * ## The parser belongs to the FRAMEWORK, and there is no way round it
+ *
+ * Every other family in this file is a table the engine interprets: a matrix of
+ * triplets, a set of zone ids, a pair of bounds. A NOTATION'S GRAMMAR is not a
+ * table. `[<visibility>] [`/`] <name> [`:` <type>] [`[` <mult> `]`] [`=` <def>]
+ * [`{` <mods> `}`]` is a parser, and a declarative encoding of it would be a
+ * parser generator shipped inside a validation engine — for one clause of one
+ * specification, with a second dialect arriving with every notation after it.
+ *
+ * So the rule carries the FUNCTION, and the family owns only the WALK: which
+ * label to read, how to cut it into lines, which lines are notation rather than
+ * content, how to turn a `false` into a finding attributed to a frame. The
+ * framework already owns its grammar — `gfx/uml/src/grammar.ts` is that grammar,
+ * written for the exporters, and a rule that calls it is a rule that can never
+ * disagree with the file the same diagram exports to.
+ *
+ * ## What that costs, stated
+ *
+ * A rule of this family is NOT serializable. Every other rule in this library is
+ * plain data a host could ship over a wire; this one holds a closure, and a
+ * round trip through JSON loses it. The family answers that the way it answers a
+ * malformed declaration anywhere else: a rule whose `parse` is not a function
+ * evaluates NOTHING and says so once ({@link warnOnce}), rather than quietly
+ * passing every line. Nothing in this library serializes a rule today, and the
+ * day something does, the families that carry only data keep working.
+ *
+ * ## Purity, and why the engine leans on it
+ *
+ * `parse` is called once per line per evaluation, inside the pass the bench
+ * measures. It must be pure and total — strings in, a verdict out, no throw, no
+ * clock, no allocation the caller cannot name. `grammar.ts` opens with exactly
+ * that promise for exactly that reason. The family does NOT wrap the call in a
+ * `try`: a parser that throws is a bug in the framework, and swallowing it would
+ * turn a crash into a silently unchecked compartment.
+ */
+export interface LabelSyntaxDef {
+    /**
+     * The framework's own reading of ONE line — see the header on why this is a
+     * function and not a table.
+     *
+     * Handed a line already trimmed, NFC-normalised and stripped of invisible code
+     * points, and never an empty one: the walk drops those before it asks. So a
+     * checker is free to assume it has been given something a reader can see.
+     */
+    parse: (line: string) => LabelSyntaxVerdict;
+    /**
+     * `true` (the default) — the label is a LIST and each line of it is judged on
+     * its own: a compartment of attributes, a compartment of operations.
+     *
+     * `false` — the label is ONE expression and a newline inside it is still part
+     * of it: a transition's `trigger [guard] / effect`, an association end's
+     * multiplicity. The whole text, trimmed, is handed to {@link parse} as a
+     * single subject.
+     *
+     * Either way the two notational lines below are dropped, because in both
+     * readings they are notation rather than content: a BLANK line (spacing) and
+     * an ELLIPSIS — `...` or `…` — which is §9.2.4's elision marker and means
+     * "there are more, not shown". A rule that indicted one would be indicting the
+     * author for saying they had left something out.
+     */
+    perLine?: boolean;
+    /** Which label is read. Absent is `'center-label'`, the element's own text. */
+    target?: LabelTarget;
+}
 /**
  * `view-admissibility` configuration — WHICH ROLES the frame admits, given the
  * level the frame itself declares.
@@ -938,6 +1063,86 @@ export interface ElementInZoneDef {
      */
     measure?: 'center' | 'extent';
 }
+/**
+ * `border-proximity` configuration — "this small glyph belongs ON the edge of
+ * that box" (ADR 0024).
+ *
+ * The family UML §11.3.4 asked for and no other one could answer. A Port is a
+ * square drawn on the boundary of the component that owns it: half of it inside
+ * and half outside is the clause's own preferred drawing, tangent inside is
+ * just as legible, and the same square dragged into the middle of the component
+ * has stopped saying anything at all. Three families sound like the answer and
+ * none of them is:
+ *
+ * - `attachment` measures a distance to a PATH and warns once on a `node`
+ *   carrier, because a box has no path;
+ * - `element-in-background` demands FULL containment, which the straddling
+ *   drawing breaks by construction — and it frames against the sheet, not
+ *   against a neighbour;
+ * - `no-overlap` is the only family evaluating PAIRS and its polarity is the
+ *   opposite one: it forbids a collision and cannot require a proximity.
+ *
+ * So this is the first family whose frame of reference is another ARTEFACT's
+ * outline. It is not a fourth membership family: nothing about the sheet takes
+ * part in the verdict, and the rule's {@link ValidationRule.backgroundRole} is
+ * read for attribution alone, exactly as `no-overlap` reads it.
+ *
+ * ## The two roles, and where each is declared
+ *
+ * The CARRIED role is the rule's own {@link ValidationRule.appliesTo} — the
+ * subject, like every element-shaped family — and the CARRIER role is
+ * {@link carrierRole} here. Same split `attachment` makes, and for the same
+ * reason: one of the two is what the finding is about and the other is what it
+ * is measured against.
+ *
+ * ## The geometry, in one sentence
+ *
+ * The carried element's CENTRE must be within {@link tolerance} of the OUTLINE
+ * — the rectangular perimeter, not the area — of a carrier it overlaps.
+ *
+ * Centre and not extent, which is the opposite of what `attachment` measures
+ * across a transition band and is the right answer for the opposite reason: a
+ * band is wide and the subject is asked to COVER it, whereas an outline is a
+ * line and the subject is asked to SIT on it. A glyph whose box happens to clip
+ * the edge of a component it is drawn well inside of would pass an extent test
+ * while failing the eye.
+ *
+ * ## A carried element touching NO carrier is silence
+ *
+ * Not a finding, and the requirement that makes the family shippable. A square
+ * dropped on blank canvas, or beside a component while the sheet is being
+ * rearranged, is somebody drawing — and a rule that answered "this belongs on a
+ * border" would be indicting the act of sketching (PRD principle 8). The family
+ * only speaks once the author has ALREADY put the glyph on a box: the mistake it
+ * reports is a glyph that has drifted INTO one, never one that has left.
+ */
+export interface BorderProximityDef {
+    /**
+     * The role of the element the subject must be posed on.
+     *
+     * It has to be a **node** role: "on the border" is measured against a box's
+     * outline, and an edge has none. A rule naming an `edge` or a `text` role here
+     * matches nothing and warns once rather than failing silently — the same
+     * contract {@link AttachmentDef.carrierRole} states in the other direction.
+     */
+    carrierRole: RoleId;
+    /**
+     * How far, in model units, the subject's CENTRE may sit from that outline.
+     *
+     * An absolute number and deliberately not a ratio, which is the opposite
+     * choice from {@link RelativeOrderDef.toleranceRatio} and the right one here:
+     * a glyph's own footprint is what makes "on the border" legible, and a
+     * notation that draws it at a fixed size (UML's port is 16 units square) means
+     * the same thing whether the component beside it is small or enormous. A
+     * tolerance proportional to the carrier would let a port sit a hundred units
+     * inside a large component and call it a border.
+     *
+     * Absent or `0` means the centre must be exactly on the line, which no hand
+     * and no snap ever produces — a rule declaring neither is a rule that indicts
+     * every subject on the board, so the family warns once and evaluates nothing.
+     */
+    tolerance: number;
+}
 /**
  * WHERE a rule's authority comes from.
  *
@@ -965,7 +1170,7 @@ export type ProvenanceSource = 'standard' | 'recommendation' | 'labre-convention
  *
  * ## Purely descriptive
  *
- * **No evaluator reads it.** Not one of the fourteen family functions branches
+ * **No evaluator reads it.** Not one of the seventeen family functions branches
  * on it, `evaluateRules` and `evaluateCheckup` never look at it, and a rule
  * declaring it evaluates identically to the same rule with the field removed
  * ({@link ValidationRule.provenance} is pinned inert by a test). It exists for
@@ -1091,6 +1296,11 @@ export interface ValidationRule extends RuleMessage {
     endpoints?: RelationEndpointsDef;
     /** `element-in-zone` only. */
     inZone?: ElementInZoneDef;
+    /**
+     * `border-proximity` only: the CARRIED elements are named by
+     * {@link appliesTo}, the carrier by {@link BorderProximityDef.carrierRole}.
+     */
+    borderProximity?: BorderProximityDef;
     /**
      * `no-overlap` only: how DEEP a collision has to be, in model units, before
      * it is worth reporting. Absent or `0` means any shared area at all.
@@ -1120,6 +1330,11 @@ export interface ValidationRule extends RuleMessage {
     reachability?: ReachabilityDef;
     /** `label-presence` only: the subjects are named by {@link appliesTo}. */
     label?: LabelPresenceDef;
+    /**
+     * `label-syntax` only: the subjects are named by {@link appliesTo}, and WHICH
+     * of their labels is read by {@link LabelSyntaxDef.target}.
+     */
+    labelSyntax?: LabelSyntaxDef;
     /**
      * `view-admissibility` only: the views are named by {@link backgroundRole},
      * and the subjects by the level the view declares.
@@ -1305,12 +1520,12 @@ export type ExemptionScope = 'element' | 'map';
  * measures against have nothing to invalidate — and a framework whose only rules
  * are on-demand has no incremental pass to protect in the first place.
  *
- * The DECLARED moment, deliberately, and not the one the levels in force decide
- * ({@link momentOf}): this is a set of ids and not a verdict, so an audit rule
- * whose frames it guards costs one extra id and can never make an answer wrong,
- * where reading the levels here would mean re-reading the surface for it.
+ * The moment is read STATICALLY ({@link couldBeRealtime}) and not per instance:
+ * this is a set of ids and not a verdict, so a rule some level could promote
+ * costs one extra id and can never make an answer wrong, where reading the
+ * chosen levels here would mean re-reading the surface for it.
  */
-export declare function backgroundElementIds(rules: readonly ValidationRule[], elements: readonly GfxPrimitiveElementModel[]): ReadonlySet<string>;
+export declare function backgroundElementIds(rules: readonly ValidationRule[], elements: readonly GfxPrimitiveElementModel[], profiles?: readonly ValidationProfile[]): ReadonlySet<string>;
 /**
  * The tone families a colour can fall into — the granularity a colour CONVENTION
  * is actually written at ("the landscape is grey, red is what changes"), and
@@ -1337,7 +1552,7 @@ export declare function toneOf(value: string | undefined): ColourTone | undefine
  * where exactly that is known; every other caller — the first evaluation, a
  * gesture that must land immediately, the bench, a test — evaluates in full.
  *
- * Since PF5.4 the TWELVE families that are not `'surface'` honour it, and not
+ * Since PF5.4 the THIRTEEN families that are not `'surface'` honour it, and not
  * one of them computes what it means: {@link runRules} derives the SUBJECTS
  * each rule must judge from {@link dirtyClosure} — which reads {@link scopeOf}
  * and nothing else — and hands them down. A family's whole part in this is one
@@ -1437,11 +1652,14 @@ export declare function scopeOf(rule: ValidationRule): RuleScope;
  * it, an incremental pass keeps verdicts measured against a map the user has
  * just stopped calling a map, or judged at a level nobody holds any more.
  *
- * Real-time rules only, and the DECLARED moment, exactly like
- * {@link backgroundElementIds} and for the same reason: an on-demand rule never
- * takes part in an incremental pass, so it has nothing to invalidate.
+ * Real-time rules only, read statically ({@link couldBeRealtime}), exactly like
+ * {@link backgroundElementIds} and for the same reason: an on-demand rule no
+ * level can promote never takes part in an incremental pass, so it has nothing
+ * to invalidate — and one that a level CAN promote has to be remembered here
+ * before anybody chooses that level, because the memory is what the pass after
+ * the choice reads.
  */
-export declare function frameMembership(rules: readonly ValidationRule[], elements: readonly GfxPrimitiveElementModel[]): ReadonlyMap<string, readonly string[]>;
+export declare function frameMembership(rules: readonly ValidationRule[], elements: readonly GfxPrimitiveElementModel[], profiles?: readonly ValidationProfile[]): ReadonlyMap<string, readonly string[]>;
 /**
  * What ONE pass has to re-judge, and what it may keep — derived from the dirty
  * set and {@link scopeOf}, and from nothing else.
@@ -1823,24 +2041,31 @@ export declare const VERDICT_PROPS: string[];
  *
  * ## `text`, and why it is not in the constant
  *
- * `label-presence` is the one family whose verdict turns on an element's words,
- * and words are what a user changes by TYPING. Watched unconditionally, every
- * keystroke in every shape on the board would wake the debounced evaluation —
- * a cost paid by every document, for a question most of them never ask.
- *
- * So it is added exactly when a REAL-TIME rule of that family is registered.
- * The moment filter is deliberate and mirrors {@link backgroundElementIds}: an
- * on-demand rule is never evaluated on the gesture path, so waking that path for
- * it would hand back precisely what declaring the second moment bought — and a
- * framework that wants its naming checked while the user types says so by
- * declaring the rule real-time, which is the one place that decision belongs.
- *
- * The DECLARED moment, like {@link backgroundElementIds} and for the same
- * reason: this set is computed ONCE per manager, before any surface exists to
- * read a level from, and watching a prop nothing turns out to need costs a
+ * `label-presence` and `label-syntax` are the two families whose verdict turns
+ * on an element's words, and words are what a user changes by TYPING. Watched
+ * unconditionally, every keystroke in every shape on the board would wake the
+ * debounced evaluation — a cost paid by every document, for a question most of
+ * them never ask.
+ *
+ * So it is added exactly when a rule of either family COULD reach the gesture
+ * path — it declares the real-time moment, or some registered level promotes it
+ * ({@link couldBeRealtime}). The filter mirrors {@link backgroundElementIds}: an
+ * on-demand rule no level can promote is never evaluated on the gesture path, so
+ * waking that path for it would hand back precisely what declaring the second
+ * moment bought.
+ *
+ * The level half of that test is what makes "Specification is the check-up"
+ * true for the two families that read WORDS. `uml.strict` promotes six spelling
+ * rules and three naming ones; without the promoted rules' `text` in this set,
+ * choosing Specification would raise them once, on the switch, and then never
+ * again while the user retyped the very word the finding is about.
+ *
+ * Read STATICALLY, like {@link backgroundElementIds} and for the same reason:
+ * this set is computed ONCE per manager, before any surface exists to read a
+ * chosen level from, and watching a prop nothing turns out to need costs a
  * debounced pass that finds nothing — never a wrong verdict.
  */
-export declare function verdictPropsOf(rules: readonly ValidationRule[]): ReadonlySet<string>;
+export declare function verdictPropsOf(rules: readonly ValidationRule[], profiles?: readonly ValidationProfile[]): ReadonlySet<string>;
 /**
  * Whether an `elementUpdated` payload can have changed a verdict.
  *