@diagc/core 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# @diagc/core
+
+The diagram model behind [`diagc`](https://www.npmjs.com/package/diagc): the `DiagramModel` types, `validate()`, the builder DSL, and the view compiler. No React, no filesystem — it does not know it is going to be drawn.
+
+```bash
+npm i -D @diagc/core
+```
+
+Install it alongside `diagc` to get types and completion when authoring `.diagram.ts` files:
+
+```ts
+import { model } from '@diagc/core';
+
+const m = model('acme', { name: 'Acme platform' });
+const web = m.node('web', { name: 'Web app', type: 'service' });
+m.relate(web, m.node('db', { name: 'Postgres', type: 'database' }), { kind: 'reads' });
+
+export default m;
+```
+
+`diagc compile` executes the file and validates whatever it exports, so the CLI works with or without this package installed — it only changes what your editor knows.
+
+Docs and the full model reference: <https://github.com/Ferroman/diagc>
+
+## License
+
+MIT

package/dist/builder.d.ts

@@ -0,0 +1,381 @@
+import type { Column, DiagramLegend, DiagramModel, EdgeLabel, FontScale, LayerRule, NotationId, Polarity, RelationStyle, TextAlign, TextRun, Threat } from './types.js';
+import { type FishbonePreset } from './fishbone.js';
+import { type Valence } from './second-order.js';
+import { type ThreatTarget } from './threat-model.js';
+export interface NodeOpts {
+    type?: string;
+    name?: string;
+    icon?: string;
+    /** silhouette-mask ref (see DiagramNode.shape) */
+    shape?: string;
+    /** image ref for image-typed nodes (see DiagramNode.image) */
+    image?: string;
+    /** fill/accent color (see DiagramNode.color) */
+    color?: string;
+    /** label color override (see DiagramNode.textColor) */
+    textColor?: string;
+    /** implementation technology (see DiagramNode.technology) */
+    technology?: string;
+    /** navigation target (see DiagramNode.link) */
+    link?: string;
+    description?: string;
+    /** rich-text label runs (see DiagramNode.rich) */
+    rich?: TextRun[];
+    /** label alignment (see DiagramNode.textAlign) */
+    textAlign?: TextAlign;
+    /** label size step (see DiagramNode.fontScale) */
+    fontScale?: FontScale;
+    metadata?: Record<string, unknown>;
+    /** cross-diagram identity (see DiagramNode.key) */
+    key?: string;
+    /** compose another diagram's content under this node (see DiagramNode.include) */
+    include?: string;
+    /** structure plane to graft from the include (see DiagramNode.includePlane) */
+    includePlane?: string;
+    /** carry the include's planes over (see DiagramNode.includePlanes) */
+    includePlanes?: boolean;
+    /** restrict this node to a single plane (see DiagramNode.plane) */
+    plane?: string;
+    /** transparent-sheet membership (see DiagramNode.layer) */
+    layer?: string;
+    /** ER-table rows (see DiagramNode.columns) */
+    columns?: Column[];
+    /** STRIDE findings (see DiagramNode.threats) */
+    threats?: Threat[];
+}
+export interface RelateOpts {
+    kind: string;
+    /** explicit relation id; when omitted the builder synthesizes `${from}->${to}#${n}`.
+     * The pair counter advances either way, so a later un-id'd relation on the same
+     * pair gets the same suffix it would have gotten without the override. */
+    id?: string;
+    label?: string;
+    /** positioned edge labels (see DiagramRelation.labels) */
+    labels?: EdgeLabel[];
+    style?: RelationStyle;
+    description?: string;
+    layer?: string;
+    polarity?: Polarity;
+    delay?: boolean;
+    /** FK column on the source table (see DiagramRelation.fromColumn) */
+    fromColumn?: string;
+    /** referenced column on the target table (see DiagramRelation.toColumn) */
+    toColumn?: string;
+    /** STRIDE findings (see DiagramRelation.threats) */
+    threats?: Threat[];
+}
+/** A threat as authored: the id is synthesized (`t1`, `t2`, …) unless given. */
+export type ThreatOpts = Omit<Threat, 'id'> & {
+    id?: string;
+};
+export interface ContainsOpts {
+    /** plane the containment belongs to; defaults to the model's first-declared plane */
+    plane?: string;
+}
+export declare class NodeRef {
+    readonly id: string;
+    private readonly builder;
+    constructor(id: string, builder: ModelBuilder);
+    /** children, optionally followed by a trailing `{ plane }` options object */
+    contains(...args: (NodeRef | ContainsOpts)[]): this;
+    /** A STRIDE finding against this element. On every node ref, not just the
+     * threat-model ones: threat-modelling an existing C4 or ER diagram annotates
+     * the nodes it already has. */
+    threat(opts: ThreatOpts): this;
+}
+export interface CommitOpts {
+    /** default `${branchId}-${n}`, n = this branch's 1-based commit count */
+    id?: string;
+    /** the label drawn above the circle; absent = untagged (name '') */
+    tag?: string;
+    /** start a new segment branched off this commit (on another branch) — no
+     * `commit` link from the lane's previous commit */
+    from?: CommitRef;
+    /** empty columns to leave before this commit (`metadata.gap`) */
+    gap?: number;
+    color?: string;
+}
+export type MergeOpts = Omit<CommitOpts, 'from'>;
+export declare class CommitRef extends NodeRef {
+    readonly branch: BranchRef;
+    constructor(id: string, builder: ModelBuilder, branch: BranchRef);
+}
+/** One lane of a git graph. `commit()` chains from the lane's last commit; `merge()`
+ * adds a commit that absorbs another lane's. Both hand back CommitRefs, which are
+ * NodeRefs — relate them, layer them, describe them like any node. */
+export declare class BranchRef extends NodeRef {
+    private readonly m;
+    private count;
+    private latest;
+    constructor(id: string, m: ModelBuilder);
+    commit(tagOrOpts?: string | CommitOpts): CommitRef;
+    merge(src: CommitRef, opts?: MergeOpts): CommitRef;
+    private create;
+}
+export interface StageOpts {
+    /** the label drawn at the top of the frame; defaults to the id */
+    name?: string;
+    /** the commit whose column the frame starts at */
+    from: CommitRef;
+    /** the commit whose column it ends at (inclusive); defaults to `from` */
+    to?: CommitRef;
+    color?: string;
+}
+export declare class GitGraphBuilder {
+    private readonly m;
+    constructor(m: ModelBuilder);
+    /** A named frame across every lane, spanning the columns of `from`…`to` —
+     * a phase of the history ("Development", "Release candidates"). Declare it
+     * after the commits it names. */
+    stage(id: string, opts: StageOpts): NodeRef;
+    /** lanes are drawn top-to-bottom in the order they are declared */
+    branch(id: string, opts?: {
+        name?: string;
+        color?: string;
+    }): BranchRef;
+}
+export interface ConsequenceOpts {
+    /** good, bad or neutral (the default) — picks the node type */
+    valence?: Valence;
+    /** a label on the arrow that leads here */
+    label?: string;
+    description?: string;
+    color?: string;
+}
+/** A decision or a consequence. `then()` IS the method of second-order
+ * thinking — "and then what?" — so a chain of calls reads as the reasoning. */
+export declare class ConsequenceRef extends NodeRef {
+    private readonly m;
+    constructor(id: string, m: ModelBuilder);
+    /** what follows from this: a new consequence, and the arrow that leads to it */
+    then(id: string, name?: string, opts?: ConsequenceOpts): ConsequenceRef;
+    /** join two branches: this also leads to a consequence declared elsewhere */
+    leadsTo(to: NodeRef, opts?: {
+        label?: string;
+    }): this;
+}
+export declare class SecondOrderBuilder {
+    private readonly m;
+    constructor(m: ModelBuilder);
+    /** the root of a tree; several decisions share one set of bands */
+    decision(id: string, name?: string, opts?: Omit<ConsequenceOpts, 'valence' | 'label'>): ConsequenceRef;
+}
+export interface FishboneOpts {
+    description?: string;
+    color?: string;
+}
+/** A cause (level 2) or a sub-cause (level 3). The level rides on the ref so a
+ * fourth `.cause()` fails at build time, where the author is, rather than as a
+ * validation issue at compile time. */
+export declare class CauseRef extends NodeRef {
+    private readonly m;
+    private readonly level;
+    constructor(id: string, m: ModelBuilder, level: 2 | 3);
+    /** a sub-cause of this cause, and the arrow from it to here */
+    cause(id: string, name?: string, opts?: FishboneOpts): CauseRef;
+}
+export declare class CategoryRef extends NodeRef {
+    private readonly m;
+    constructor(id: string, m: ModelBuilder);
+    /** a cause on this bone, and the arrow from it to here */
+    cause(id: string, name?: string, opts?: FishboneOpts): CauseRef;
+}
+export declare class FishboneBuilder {
+    private readonly m;
+    private readonly effect;
+    constructor(m: ModelBuilder, effect: NodeRef);
+    /** a major bone, and the arrow from it to the effect */
+    category(id: string, name?: string, opts?: FishboneOpts): CategoryRef;
+    /** the bones of a standard set, keyed by their slug ids (`presetId`) */
+    categories(preset: FishbonePreset): Record<string, CategoryRef>;
+}
+/** A data flow: a relation ref that takes threats, the way a NodeRef does. */
+export declare class FlowRef {
+    readonly id: string;
+    private readonly m;
+    constructor(id: string, m: ModelBuilder);
+    threat(opts: ThreatOpts): this;
+}
+/** A DFD element's node options, minus the two its helper already supplies:
+ * `type` from the helper itself, `name` from its second argument. */
+export type ElementOpts = Omit<NodeOpts, 'type' | 'name'>;
+/** The four DFD element kinds plus flows. Everything it hands back is an
+ * ordinary NodeRef/FlowRef, so the rest of the builder — contains, relate,
+ * layers, threat — composes with it unchanged. */
+export declare class ThreatModelBuilder {
+    private readonly m;
+    constructor(m: ModelBuilder);
+    private element;
+    /** an external entity: a user, a third party, anything outside the system */
+    entity(id: string, name?: string, opts?: ElementOpts): NodeRef;
+    /** a process: something the system does with the data */
+    process(id: string, name?: string, opts?: ElementOpts): NodeRef;
+    /** a data store: where the data rests */
+    store(id: string, name?: string, opts?: ElementOpts): NodeRef;
+    /** a trust boundary: nest elements with `.contains()` */
+    boundary(id: string, name?: string, opts?: ElementOpts): NodeRef;
+    /** a data flow; a string is its label */
+    flow(from: NodeRef, to: NodeRef, labelOrOpts?: string | Omit<RelateOpts, 'kind'>): FlowRef;
+}
+export interface ActivityElementOpts {
+    color?: string;
+}
+/** Shared element surface of a lane and a region: each helper creates a typed
+ * node contained by this scope and hands back a plain NodeRef, so everything
+ * composes with the rest of the builder (relate, layers, contains). */
+export declare abstract class ActivityScope extends NodeRef {
+    protected readonly m: ModelBuilder;
+    private counters;
+    constructor(id: string, m: ModelBuilder);
+    /** `${scopeId}-<suffix>` for the first of a kind, `-<n>` after — deterministic
+     * from declaration order, so layout-overlay keys stay stable. */
+    protected autoId(suffix: string): string;
+    protected element(id: string, type: string, name: string, opts?: ActivityElementOpts): NodeRef;
+    action(id: string, name: string, opts?: ActivityElementOpts): NodeRef;
+    object(id: string, name: string, opts?: ActivityElementOpts): NodeRef;
+    send(id: string, name: string, opts?: ActivityElementOpts): NodeRef;
+    receive(id: string, name: string, opts?: ActivityElementOpts): NodeRef;
+    note(id: string, text: string): NodeRef;
+    decision(id?: string, name?: string): NodeRef;
+    bar(id?: string): NodeRef;
+    start(id?: string): NodeRef;
+    end(id?: string): NodeRef;
+}
+export declare class RegionRef extends ActivityScope {
+}
+export declare class LaneRef extends ActivityScope {
+    /** interruptible region: a dashed container inside this lane */
+    region(id?: string, name?: string): RegionRef;
+}
+/** One activity diagram: the frame node itself (this IS its NodeRef) plus lane
+ * and cross-lane flow helpers. Call m.activity() once per frame — several
+ * frames coexist on one canvas. */
+export declare class ActivityBuilder extends NodeRef {
+    private readonly b;
+    constructor(id: string, b: ModelBuilder);
+    /** lanes are drawn top-to-bottom in the order they are declared */
+    lane(id: string, opts?: {
+        name?: string;
+        color?: string;
+    }): LaneRef;
+    flow(from: NodeRef, to: NodeRef, label?: string): this;
+    objectFlow(from: NodeRef, to: NodeRef, label?: string): this;
+    interrupt(from: NodeRef, to: NodeRef, label?: string): this;
+    noteLink(note: NodeRef, target: NodeRef): this;
+}
+export declare class ModelBuilder {
+    private readonly id;
+    private readonly name;
+    private nodes;
+    private containment;
+    private relations;
+    private layers;
+    private planes;
+    private legendConfig;
+    private typeColorMap;
+    private layerRuleList;
+    private modelNotation;
+    private modelStyle;
+    private pairCounters;
+    private git;
+    private so;
+    private fb;
+    private tm;
+    constructor(id: string, name: string);
+    node(id: string, opts?: NodeOpts): NodeRef;
+    /** ER table: a node of type 'db-table' carrying `columns`. */
+    table(id: string, opts: Omit<NodeOpts, 'type'> & {
+        columns: Column[];
+    }): NodeRef;
+    /**
+     * Foreign key: a `kind:'fk'` relation from `from.fromColumn` to `to.toColumn`.
+     * `toColumn` defaults to the target table's single primary-key column; declare
+     * the target table (with its PK) before calling.
+     */
+    fk(from: NodeRef, fromColumn: string, to: NodeRef, toColumn?: string, opts?: Omit<RelateOpts, 'kind' | 'fromColumn' | 'toColumn'>): this;
+    /** internal — used by NodeRef */
+    addContainment(parent: string, child: string, plane?: string): void;
+    /** internal — appends a threat to the node or relation `target` names; used by
+     * NodeRef.threat() and FlowRef.threat() */
+    addThreat(target: ThreatTarget, opts: ThreatOpts): void;
+    relate(from: NodeRef, to: NodeRef, opts: RelateOpts): this;
+    /** internal — like relate(), but returns the new relation's id (FlowRef needs
+     * it to hang threats off the flow) */
+    addRelation(from: NodeRef, to: NodeRef, opts: RelateOpts): string;
+    layer(id: string, opts?: {
+        name?: string;
+        tint?: string;
+    }): this;
+    plane(id: string, opts?: {
+        name?: string;
+        containmentOf?: string;
+        layers?: string[];
+        baseRelations?: boolean;
+        notation?: NotationId;
+        hides?: string[];
+        hidesTree?: string[];
+    }): this;
+    /**
+     * Declare this model a git graph: a plane with the `git-graph` notation that
+     * must be the default (first-declared) plane, so the lanes' containment needs
+     * no plane tag. Returns the builder for lanes; see BranchRef.
+     */
+    gitGraph(opts?: {
+        plane?: string;
+        name?: string;
+    }): GitGraphBuilder;
+    /**
+     * Declare a second-order thinking diagram. With no `plane` the NOTATION is
+     * model-wide (nothing about it needs a plane — the notation is flat); name a
+     * plane to keep it beside other views of the same model.
+     */
+    secondOrder(opts?: {
+        plane?: string;
+        name?: string;
+    }): SecondOrderBuilder;
+    /**
+     * Declare a fishbone diagram: the effect at the head, then `.category()` /
+     * `.cause()` to hang bones on it. With no `plane` the NOTATION is model-wide
+     * (the notation is flat); name a plane to keep it beside other views of the
+     * same model. The effect's own options ride in `opts` too.
+     */
+    fishbone(id: string, name?: string, opts?: FishboneOpts & {
+        plane?: string;
+        planeName?: string;
+    }): FishboneBuilder;
+    /**
+     * Declare a threat model (STRIDE data-flow diagram). With no `plane` the
+     * NOTATION is model-wide; name a plane to threat-model an existing
+     * architecture beside its other views — the plane holds its own boundary
+     * containment over the same nodes.
+     */
+    threatModel(opts?: {
+        plane?: string;
+        name?: string;
+    }): ThreatModelBuilder;
+    /** Declare an activity diagram: a framed swimlane flow. Repeatable — each
+     * call is one frame; frames are ordinary containers on whatever plane the
+     * model uses (no notation, no plane creation). */
+    activity(id: string, opts?: {
+        name?: string;
+    }): ActivityBuilder;
+    /** Declare a legend. Bare `legend()` means derived sections only. */
+    legend(opts?: DiagramLegend): this;
+    /** Default accent colour per node type; `*` is the fallback for the rest.
+     * The one way to colour nodes a composed diagram did not author. Successive
+     * calls merge, last wins per key; a node's own `color` still wins over both. */
+    typeColors(map: Record<string, string>): this;
+    /** Put unlayered relations on layers by class (`kind` and/or `style.color`),
+     * first match wins. The one way a composed diagram can layer relations an
+     * include brought in. Successive calls append; an explicit relation `layer`
+     * still beats every rule. */
+    layerRules(rules: LayerRule[]): this;
+    /** pin the whole diagram's visual language (see DiagramModel.notation) */
+    notation(id: string): this;
+    /** pin the model-level renderer style preset (see DiagramModel.style) */
+    style(id: string): this;
+    toJSON(): DiagramModel;
+}
+export declare function model(id: string, opts?: {
+    name?: string;
+}): ModelBuilder;