@formicoidea/labre-framework-c4 0.33.0

package/dist/roles.d.ts

@@ -0,0 +1,116 @@
+import type { C4BoundaryVariant, C4NodeKind } from '@formicoidea/labre-core/model';
+import type { RoleDefs, RoleId } from '@formicoidea/labre-core/std/gfx';
+/**
+ * C4 role vocabulary.
+ *
+ * A role is the semantic identity of a C4 artefact, and here it is the ONLY
+ * thing that carries it: three of the four levels are drawn as the same rounded
+ * rectangle, so a rule that read the shape would find a box and learn nothing.
+ * The `kind` discriminant answers a different question (which glyph and which
+ * blue to paint); the role answers what the box MEANS.
+ *
+ * Hierarchy is DATA (`parent`), never TS inheritance. One specialisation is
+ * declared and it is the one C4 itself makes: a `c4:database` IS a
+ * `c4:container` — the notation gives it a cylinder instead of a box, but it is
+ * a container of the system all the same, so everything written about containers
+ * applies to it for free (see `roleIsA`). `mobile` and `browser` are the same
+ * statement without even a role of their own: they map straight onto
+ * `c4:container`, because a phone app and a single-page app are containers with
+ * a picture, and inventing a role per picture would let a rule about containers
+ * miss two of them.
+ *
+ * The four levels are deliberately FLAT — `c4:component` is not a child of
+ * `c4:container`, nor `c4:container` of `c4:system`. The relation between the
+ * levels is COMPOSITION ("a container is part of a system"), not
+ * specialisation ("a container is a kind of system"), and `roleIsA` means the
+ * second: filing them in a chain would make "every rule about a system also
+ * falls on every container" true, which is the opposite of what C4 says. What
+ * composition there is on the canvas is drawn — a boundary round the parts —
+ * and that is where a later rule must read it from.
+ *
+ * The **board** and the **boundary** are parent-less, the same call
+ * `wardley:map` and `bpmn:pool` both make: they are the FRAME the elements are
+ * drawn in and drawn round, and a rule written on the artefacts must never fall
+ * on the sheet holding them.
+ *
+ * The boundary is the ONE frame with children, and they are the second
+ * specialisation in the pack: `c4:system-boundary` and `c4:container-boundary`.
+ * Unlike the four levels, this really IS specialisation — a system boundary is a
+ * boundary, in the way a database is a container — and the split exists because
+ * C4's levels are ZOOMS of one element: the frame says which zoom the sheet is
+ * at, and what may be drawn inside it follows from that. Everything already
+ * written on `c4:boundary` keeps falling on both through `roleIsA`, which is what
+ * lets the two membership rules and the legend stay written on the parent.
+ *
+ * ## Compatibility
+ *
+ * Nothing is backfilled. A diagram drawn before today carries 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).
+ *
+ * And nothing is REWRITTEN either, which the boundary split is the first
+ * occasion to say out loud: a boundary drawn before it carries the PARENT role,
+ * `c4:boundary`, and that stays a role the vocabulary declares rather than a
+ * legacy alias to be migrated away. A rule framed against the parent reaches it;
+ * a rule framed against a child does not, and that asymmetry is deliberate — a
+ * zoom rule that needs to know WHICH level the frame is at cannot honestly guess
+ * it from a boundary that never said.
+ */
+/** Every role this framework declares. */
+export type C4Role = 'person' | 'system' | 'container' | 'database' | 'component' | 'title' | 'type-line' | 'description' | 'board' | 'boundary' | 'system-boundary' | 'container-boundary' | 'relationship';
+export type C4RoleId = `c4:${C4Role}`;
+/**
+ * Role ids, keyed by their own name.
+ *
+ * Keyed by the ROLE and not by the `kind`, unlike BPMN's table: C4 has nine
+ * kinds and five element roles, because four of the kinds are a second drawing
+ * of a level rather than a level of their own. {@link C4_ROLE_OF_KIND} is the
+ * bridge, and it is the only place the two vocabularies meet.
+ */
+export declare const C4_ROLE: {
+    readonly person: "c4:person";
+    readonly system: "c4:system";
+    readonly container: "c4:container";
+    readonly database: "c4:database";
+    readonly component: "c4:component";
+    readonly title: "c4:title";
+    readonly 'type-line': "c4:type-line";
+    readonly description: "c4:description";
+    readonly board: "c4:board";
+    readonly boundary: "c4:boundary";
+    readonly 'system-boundary': "c4:system-boundary";
+    readonly 'container-boundary': "c4:container-boundary";
+    readonly relationship: "c4:relationship";
+};
+export declare const C4_ROLES: RoleDefs;
+/**
+ * The `kind` discriminant → the role it means.
+ *
+ * `kind` drives the renderer and is what the palette writes; the ROLE is the
+ * semantic authority. The two are posted side by side at every creation site,
+ * the way Wardley and BPMN already do it, and this table is the single place
+ * that says which kind means which role. Total over {@link C4NodeKind} by its
+ * type, so a new kind cannot land without being given a meaning.
+ *
+ * Note what it collapses: `person-ext` means `c4:person` and `system-ext` means
+ * `c4:system`, because an external system is a system — the grey says it is out
+ * of scope, not that it is a different sort of thing. `mobile` and `browser`
+ * mean `c4:container` for the same reason.
+ */
+export declare const C4_ROLE_OF_KIND: Record<C4NodeKind, RoleId>;
+/**
+ * The boundary's `variant` → the role it means.
+ *
+ * The frame's twin of {@link C4_ROLE_OF_KIND}, and it exists for the same
+ * reason: the renderer and the exporter read `variant` (it picks the bracket
+ * line under the corner, `background.ts`), the RULES read the role, and this
+ * table is the single place that says the two are the same statement.
+ *
+ * Total over `C4BoundaryVariant` by its type, so a third kind of boundary cannot
+ * land without being given a meaning — and `createC4Boundary` writes both fields
+ * from it in one call, which is what keeps them from ever disagreeing. A
+ * boundary whose `variant` was never written carries the PARENT role and no
+ * bracket line: that is the pre-split document, and it is left exactly as it was
+ * found.
+ */
+export declare const C4_BOUNDARY_ROLE: Record<C4BoundaryVariant, RoleId>;

package/dist/roles.js

@@ -0,0 +1,303 @@
+/**
+ * Role ids, keyed by their own name.
+ *
+ * Keyed by the ROLE and not by the `kind`, unlike BPMN's table: C4 has nine
+ * kinds and five element roles, because four of the kinds are a second drawing
+ * of a level rather than a level of their own. {@link C4_ROLE_OF_KIND} is the
+ * bridge, and it is the only place the two vocabularies meet.
+ */
+export const C4_ROLE = {
+    person: 'c4:person',
+    system: 'c4:system',
+    container: 'c4:container',
+    database: 'c4:database',
+    component: 'c4:component',
+    title: 'c4:title',
+    'type-line': 'c4:type-line',
+    description: 'c4:description',
+    board: 'c4:board',
+    boundary: 'c4:boundary',
+    'system-boundary': 'c4:system-boundary',
+    'container-boundary': 'c4:container-boundary',
+    relationship: 'c4:relationship',
+};
+const _everyRoleIsMapped = true;
+void _everyRoleIsMapped;
+/**
+ * ## The i18n keys, and when they arrived
+ *
+ * The model slice shipped this vocabulary with its English wording and NO keys,
+ * deliberately: a framework contributes manifest entries through
+ * `FRAMEWORK_TRANSLATION_GROUPS`, whose `owner` must be a `FrameworkId` — which
+ * in turn must be a tooling flag key with a `FrameworkDescriptor` behind it
+ * (`frameworks.ts`: a senior button, an icon, a bundle). A key the manifest
+ * cannot name is a key a host meets and cannot translate, which
+ * `packages/affine/all/src/__tests__/translations/manifest.unit.spec.ts` fails
+ * the build over.
+ *
+ * The tooling slice gives C4 that identity, so the keys land here together with
+ * the `c4TranslationEntries` export that puts them in the manifest. Nothing in
+ * a stored document changed: an element persists the ROLE ID, never its label.
+ */
+/** i18n key stem of a role id: `c4:person` → `com.labre.c4.role.person`. */
+const roleKey = (id) => `com.labre.c4.role.${id.slice('c4:'.length)}`;
+/**
+ * The four levels of the C4 model, flat — see the note at the top of this file
+ * on why composition is not specialisation — plus the one specialisation C4
+ * itself draws, the database under the container.
+ */
+const ELEMENT_DEFS = [
+    {
+        id: C4_ROLE.person,
+        kind: 'node',
+        labelKey: roleKey(C4_ROLE.person),
+        labelFallback: 'Person',
+    },
+    {
+        id: C4_ROLE.system,
+        kind: 'node',
+        labelKey: roleKey(C4_ROLE.system),
+        labelFallback: 'Software system',
+    },
+    {
+        id: C4_ROLE.container,
+        kind: 'node',
+        labelKey: roleKey(C4_ROLE.container),
+        labelFallback: 'Container',
+    },
+    // The one specialisation in the pack. A data store is a container that keeps
+    // state — the stencil draws it as a cylinder — so a rule about containers
+    // reaches it, and a rule about persistence can single it out.
+    {
+        id: C4_ROLE.database,
+        parent: C4_ROLE.container,
+        kind: 'node',
+        labelKey: roleKey(C4_ROLE.database),
+        labelFallback: 'Database',
+    },
+    {
+        id: C4_ROLE.component,
+        kind: 'node',
+        labelKey: roleKey(C4_ROLE.component),
+        labelFallback: 'Component',
+    },
+];
+/**
+ * The three written tiers of an element's label — its NAME, its type line and
+ * its description — as roles on the canvas TEXT elements that carry them.
+ *
+ * ## Why the tiers have roles at all
+ *
+ * Because a C4 component is a GROUP (PO recette, 28/08/2026): the shape and
+ * three texts, every one of them edited in place exactly like any other words on
+ * the canvas. Which leaves one question — given a group of three texts and a
+ * box, WHICH text is the name and which is the technology? — and the platform
+ * already has an answer for "what is this element, semantically". Roles survive
+ * what the alternatives do not: a child reordered inside its group, a group
+ * ungrouped and regrouped, a tier copied to another node, a tier deleted and
+ * redrawn. Position in `children` survives none of those.
+ *
+ * `kind: 'text'`, which is the same call `wardley:label` makes and for the same
+ * reason: these are free text elements whose BOX is a creation-time default and
+ * not a statement about anything. A rule measuring one must measure its ink.
+ *
+ * ## `c4:title` is where an element's NAME lives
+ *
+ * For one iteration the name was the shape's own native inner text and only the
+ * other two tiers were elements. The PO's follow-up closed that: two kinds of
+ * text in one component meant two editors, two toolbars and two sets of rules
+ * for the same three lines, and the odd one out was the one that mattered most.
+ * A C4 element's name is now `c4:title`, on equal terms with the tiers under it,
+ * and the shape carries no text at all.
+ *
+ * It is the role a rule about naming must read. Everything that asks "is this
+ * element named?" — for any of the nine artefacts, at any of the four levels —
+ * asks it of the `c4:title` grouped with the shape. The exporter still falls
+ * back to the shape's own inner text for an element drawn before this change,
+ * which is where those names really are; a rule may do the same or not, but it
+ * must not look for a name on the shape FIRST.
+ *
+ * ## What they are NOT
+ *
+ * Not levels of the model, not artefacts, and not a fourth thing a C4 diagram
+ * can contain. They are three lines of ONE element's label, which is why they
+ * are parent-less and why nothing in the pack maps a `kind` to them
+ * ({@link C4_ROLE_OF_KIND} stays the nine artefacts). The role stamped on the
+ * artefact stays on the SHAPE alone — the rules, the facts and the export all
+ * key on it, and a rule that fell on a type line would be asking a subtitle to
+ * have a name of its own.
+ *
+ * The GROUP itself is deliberately role-less, for the reason `legend.ts` gives
+ * about legend glyphs: a role makes an element count as an artefact for every
+ * rule written against roles, and the wrapper round a box is not a second box.
+ */
+const TIER_DEFS = [
+    {
+        id: C4_ROLE.title,
+        kind: 'text',
+        labelKey: roleKey(C4_ROLE.title),
+        labelFallback: 'Name',
+    },
+    {
+        id: C4_ROLE['type-line'],
+        kind: 'text',
+        labelKey: roleKey(C4_ROLE['type-line']),
+        labelFallback: 'Type line',
+    },
+    {
+        id: C4_ROLE.description,
+        kind: 'text',
+        labelKey: roleKey(C4_ROLE.description),
+        labelFallback: 'Description',
+    },
+];
+/**
+ * The frames: the sheet a diagram is drawn on, the dashed rectangle drawn round
+ * part of it, and the two LEVELS that rectangle can be drawn at.
+ *
+ * The board and the boundary are parent-less, and not related to each other
+ * either. A board is where the diagram lives; a boundary is a statement made
+ * INSIDE it about which elements belong to one system or one container. Neither
+ * is an element of the model, so a rule about people, systems, containers or
+ * components must fall on neither.
+ *
+ * ## Why the boundary has two children
+ *
+ * Because C4's four levels are ZOOMS of one element — "a software system is made
+ * up of containers, each of which contains components" — and the boundary is
+ * where the canvas says which zoom this part of the sheet is at. Until the
+ * children existed, "inside a boundary" was one undifferentiated fact, and the
+ * rules that read it could only ask whether an element was framed by SOMETHING;
+ * they could not ask the question the model actually poses, which is whether it
+ * is framed by the right LEVEL. A container drawn inside a container boundary is
+ * that boundary — drawn inside itself — and no rule could say so.
+ *
+ * They mirror the parent's `kind` (both are `node`, both are drawn as the same
+ * dashed rectangle) and specialise it, so everything already written on
+ * `c4:boundary` — `c4.homeless-component`, `c4.person-in-boundary`, the legend's
+ * "Boundary" row, the frame gate that decides where a profile may be chosen —
+ * keeps reaching them through `roleIsA` with nothing restated.
+ *
+ * A boundary is stamped with its child role and its `variant` at ONE place
+ * ({@link C4_BOUNDARY_ROLE}, read by `createC4Boundary`); nothing else writes
+ * either, and the two must never be made to disagree.
+ */
+const FRAME_DEFS = [
+    {
+        id: C4_ROLE.board,
+        kind: 'node',
+        labelKey: roleKey(C4_ROLE.board),
+        labelFallback: 'C4 diagram',
+    },
+    {
+        id: C4_ROLE.boundary,
+        kind: 'node',
+        labelKey: roleKey(C4_ROLE.boundary),
+        labelFallback: 'Boundary',
+    },
+    {
+        id: C4_ROLE['system-boundary'],
+        parent: C4_ROLE.boundary,
+        kind: 'node',
+        labelKey: roleKey(C4_ROLE['system-boundary']),
+        labelFallback: 'System boundary',
+    },
+    {
+        id: C4_ROLE['container-boundary'],
+        parent: C4_ROLE.boundary,
+        kind: 'node',
+        labelKey: roleKey(C4_ROLE['container-boundary']),
+        labelFallback: 'Container boundary',
+    },
+];
+/**
+ * The relationship — the only connecting object C4 has, and a typed edge under
+ * `docs/adr/0010`.
+ *
+ * Tier 1 of that ADR is generic — `source` is the subject of the role's verb,
+ * `target` its object — and it already applies: the source is the element that
+ * has the need and the target the one that meets it. Tier 2 is the `direction`
+ * block below. C4 asks every relationship to be READ as a sentence ("Customer
+ * uses Internet Banking System"), which is exactly what the direction reveal
+ * reads back, and it is why one role suffices where BPMN needs three: there is
+ * one kind of line on this canvas, and its LABEL is where the author says which
+ * kind of using it is.
+ */
+const RELATIONSHIP_DEFS = [
+    {
+        id: C4_ROLE.relationship,
+        kind: 'edge',
+        labelKey: roleKey(C4_ROLE.relationship),
+        labelFallback: 'Relationship',
+        /**
+         * The verb is **"uses"** — the one C4 falls back to when an author writes
+         * nothing on the arrow, and the reading that decides which end is which: the
+         * source is the element with the need, the target the one that meets it.
+         *
+         * It is deliberately the weakest verb in the pack. "Sends a request to",
+         * "reads from", "authenticates against" are all relationships an author
+         * writes ON the line, and the role must not claim one of them: a default
+         * that guessed would put words in the diagram's mouth every time somebody
+         * dragged an arrow and moved on.
+         */
+        direction: {
+            verbKey: `${roleKey(C4_ROLE.relationship)}.verb`,
+            verbFallback: 'uses',
+            gestureHintKey: `${roleKey(C4_ROLE.relationship)}.gesture`,
+            gestureHintFallback: 'Drag from the element that has the need to the one that meets it.',
+        },
+    },
+];
+const DEFS = [
+    ...ELEMENT_DEFS,
+    ...TIER_DEFS,
+    ...FRAME_DEFS,
+    ...RELATIONSHIP_DEFS,
+];
+// Null prototype: this is a lookup table keyed by ids that may one day come
+// from host-supplied packs, so `defs['toString']` must not resolve.
+export const C4_ROLES = Object.assign(Object.create(null), Object.fromEntries(DEFS.map(def => [def.id, def])));
+/**
+ * The `kind` discriminant → the role it means.
+ *
+ * `kind` drives the renderer and is what the palette writes; the ROLE is the
+ * semantic authority. The two are posted side by side at every creation site,
+ * the way Wardley and BPMN already do it, and this table is the single place
+ * that says which kind means which role. Total over {@link C4NodeKind} by its
+ * type, so a new kind cannot land without being given a meaning.
+ *
+ * Note what it collapses: `person-ext` means `c4:person` and `system-ext` means
+ * `c4:system`, because an external system is a system — the grey says it is out
+ * of scope, not that it is a different sort of thing. `mobile` and `browser`
+ * mean `c4:container` for the same reason.
+ */
+export const C4_ROLE_OF_KIND = {
+    person: C4_ROLE.person,
+    'person-ext': C4_ROLE.person,
+    system: C4_ROLE.system,
+    'system-ext': C4_ROLE.system,
+    container: C4_ROLE.container,
+    database: C4_ROLE.database,
+    mobile: C4_ROLE.container,
+    browser: C4_ROLE.container,
+    component: C4_ROLE.component,
+};
+/**
+ * The boundary's `variant` → the role it means.
+ *
+ * The frame's twin of {@link C4_ROLE_OF_KIND}, and it exists for the same
+ * reason: the renderer and the exporter read `variant` (it picks the bracket
+ * line under the corner, `background.ts`), the RULES read the role, and this
+ * table is the single place that says the two are the same statement.
+ *
+ * Total over `C4BoundaryVariant` by its type, so a third kind of boundary cannot
+ * land without being given a meaning — and `createC4Boundary` writes both fields
+ * from it in one call, which is what keeps them from ever disagreeing. A
+ * boundary whose `variant` was never written carries the PARENT role and no
+ * bracket line: that is the pre-split document, and it is left exactly as it was
+ * found.
+ */
+export const C4_BOUNDARY_ROLE = {
+    system: C4_ROLE['system-boundary'],
+    container: C4_ROLE['container-boundary'],
+};

package/dist/rules.d.ts

@@ -0,0 +1,95 @@
+import type { EndpointTriplet, ValidationRule } from '@formicoidea/labre-core/blocks/surface';
+/**
+ * Every ordered pair of the four levels — the ALPHABET, and nothing more.
+ *
+ * Not a grammar: this table sanctions all sixteen sentences, person → person
+ * included. It exists so {@link untypedLink} can say "between two C4 elements"
+ * — which is the only thing `flagNeutral` reads a matrix FOR — without also
+ * inheriting a judgement that belongs to {@link relationshipEndpoints}.
+ *
+ * ## Why the two tables are not one, which they were for a day
+ *
+ * `relation-endpoints` raises an off-matrix finding for every rule declaring a
+ * matrix, so two rules sharing one grammar report the same wrong sentence
+ * TWICE, with two brackets and two suggestions for one gesture to fix. BPMN
+ * never met this because its neutral-link rule reuses a matrix on which
+ * off-matrix is structurally unreachable (one triplet, one role). C4's grammar
+ * has exactly one removal, so it is reachable, and the alphabet has to be
+ * declared separately for the neutral rule to stay the single-verdict rule its
+ * own comment promises.
+ */
+export declare const C4_ELEMENT_MATRIX: readonly EndpointTriplet[];
+/**
+ * The sanctioned sentences of a relationship: **anything uses anything, except
+ * a person using a person.**
+ *
+ * C4 is deliberately permissive here and the matrix says so. A person uses a
+ * system; a container reads from a database; a component calls a system. The
+ * notation puts no level barrier on an arrow — a C4 diagram is drawn at one
+ * level, so the pairs that would be odd are odd because of the SHEET they are
+ * on, which is a judgement this pack cannot make (see the header on D3).
+ *
+ * The one sentence C4 does not have is **person → person**. Two people talking
+ * to each other is a true and important thing about an organisation, and it is
+ * not software: the model has no drawing for it, and a diagram that shows one
+ * is a diagram whose author reached for the wrong canvas. It is the only
+ * removal, and it is why the grammar is the alphabet minus one line rather than
+ * fifteen lines written out — the rule is "all of them but that one", and the
+ * data reads best when it says what the rule says.
+ *
+ * Exported so a test asserts THIS table rather than a copy of it.
+ */
+export declare const C4_RELATIONSHIP_MATRIX: readonly EndpointTriplet[];
+/**
+ * ## And the two levels that declare no rule at all
+ *
+ * C4 is named after its four C's — Context, Containers, Components, Code — and
+ * the picker offers all four (`levels.ts`). Two of them are levels a board can
+ * carry and NOTHING in this pack judges, deliberately, and it is worth saying
+ * why rather than leaving a reader to notice the gap.
+ *
+ * **`component`** — a component diagram shows one container's components, and
+ * around them it legitimately shows the containers they talk to, the systems
+ * behind those, and the people at the top of the chain: C4 draws the neighbours
+ * at every level. The frame it is defined by is a container boundary, which is
+ * therefore legal too, and a system boundary drawn round that is the ordinary
+ * nesting. That leaves no role a component diagram refuses.
+ *
+ * **`code`** — for the opposite reason. Not "nothing is forbidden" but "we know
+ * nothing yet": the editor draws no code-level artefact, so the pack has no
+ * vocabulary in which to say what such a sheet admits or refuses. The
+ * declaration is still the author's to make — that is a decision about the
+ * NOTATION's vocabulary, not about our tooling (`C4BoardLevel` says so at
+ * length) — and the tool records it without pretending to check it.
+ *
+ * A rule declared for either would be an empty `forbidden` list — data that can
+ * never fire, which this file already calls the worst thing declarative data can
+ * do. So there are two rules and not four, and {@link ViewAdmissibilityDef} is
+ * built to make that the natural outcome: a level absent from the table is a
+ * level the rule has nothing to say about, and the engine walks nothing for it.
+ */
+/**
+ * The pack, whole: sixteen rules, all registered, all live.
+ *
+ * FIVE families, where fourteen rules needed four. C4 has one connecting object,
+ * four flat levels and two frames, so there is still no swimlane question, no
+ * graph traversal and no cardinality per frame to ask about — and the three zoom
+ * rules added nothing to the list, being two more `element-in-zone` rules and one
+ * more `element-in-background` rule, because the split that made them askable
+ * happened in the role VOCABULARY and not in the engine.
+ *
+ * The two LEVEL rules are the exception, and the fifth family is the honest
+ * reason: their question is asked of the SHEET, off a fact the sheet declares,
+ * and no family that starts from an artefact can express it. That is also why
+ * `view-admissibility` is generic and lives in the engine — C4 is its first
+ * consumer, not its owner.
+ *
+ * Sixteen and not fifteen because the grammar and the self-loop are two rules
+ * (see {@link relationshipSelfLoop}); sixteen and not nineteen because the four
+ * per-level naming rules collapsed into {@link unnamedElement} the moment an
+ * element's name became one text role instead of four shapes' inner text; and
+ * sixteen and not eighteen because two of the four levels a board can declare
+ * are judged by nothing — `component` forbids nothing and `code` is a level this
+ * pack cannot yet speak about (see above).
+ */
+export declare const C4_RULES: readonly ValidationRule[];