@diagc/core 0.1.0

package/dist/second-order.js

@@ -0,0 +1,86 @@
+/** The notation id a plane (or the model) declares to be drawn as a consequence tree. */
+export const SECOND_ORDER_NOTATION = 'second-order';
+export const SO_DECISION_TYPE = 'so-decision';
+/** Valence is a TYPE VARIANT, not a field: a registry and palette entry, no
+ * schema change — the same trick C4 uses for its `-external` stencils. */
+export const SO_CONSEQUENCE_TYPES = ['so-consequence-positive', 'so-consequence-negative', 'so-consequence-neutral'];
+/** The kind the builder and the studio create. The derivation below does NOT
+ * filter by it (see consequenceOrders). */
+export const SO_LEADS_TO_KIND = 'leads-to';
+const TYPE_OF = {
+    '+': 'so-consequence-positive',
+    '-': 'so-consequence-negative',
+    '0': 'so-consequence-neutral',
+};
+export const consequenceTypeOf = (v) => TYPE_OF[v];
+export function valenceOf(type) {
+    return Object.keys(TYPE_OF).find((v) => TYPE_OF[v] === type);
+}
+export const isSecondOrderNode = (n) => n.type === SO_DECISION_TYPE || valenceOf(n.type) !== undefined;
+/**
+ * Which band each decision and consequence belongs to. This is the ONE place
+ * that answers it, so the layout's partitions, the band overlay, the studio
+ * panel and validation cannot disagree.
+ *
+ * The order is the LONGEST path from a decision: every cause then sits in an
+ * earlier band than its effect, and no arrow ever runs inside a band — which is
+ * also exactly what lets elk take the orders as layer partitions.
+ *
+ * Reads the MODEL's relations, never drawn edges: toggling a layer must not
+ * move a box. Any kind of relation between two second-order nodes counts, so
+ * restyling an arrow can never drop a node out of its band. Never throws.
+ */
+export function consequenceOrders(model) {
+    const nodes = model.nodes.filter(isSecondOrderNode);
+    const ids = new Set(nodes.map((n) => n.id));
+    const next = new Map(nodes.map((n) => [n.id, []]));
+    const prev = new Map(nodes.map((n) => [n.id, []]));
+    const seen = new Set();
+    for (const r of model.relations) {
+        if (r.from === r.to || !ids.has(r.from) || !ids.has(r.to))
+            continue;
+        const pair = `${r.from}\u0000${r.to}`;
+        if (seen.has(pair))
+            continue;
+        seen.add(pair);
+        next.get(r.from).push(r.to);
+        prev.get(r.to).push(r.from);
+    }
+    // Kahn: whatever is never released sits on a loop or behind one.
+    const waiting = new Map(nodes.map((n) => [n.id, prev.get(n.id).length]));
+    const topo = nodes.filter((n) => waiting.get(n.id) === 0).map((n) => n.id);
+    for (let i = 0; i < topo.length; i++) {
+        for (const to of next.get(topo[i])) {
+            const left = waiting.get(to) - 1;
+            waiting.set(to, left);
+            if (left === 0)
+                topo.push(to);
+        }
+    }
+    if (topo.length < nodes.length) {
+        // Peel what merely hangs OFF the loop (nothing stuck follows from it), so
+        // the report names the loop itself.
+        const released = new Set(topo);
+        const stuck = new Set(nodes.map((n) => n.id).filter((id) => !released.has(id)));
+        for (let peeled = true; peeled;) {
+            peeled = false;
+            for (const id of stuck) {
+                if (next.get(id).some((to) => stuck.has(to)))
+                    continue;
+                stuck.delete(id);
+                peeled = true;
+            }
+        }
+        return { orders: new Map(), cycle: nodes.map((n) => n.id).filter((id) => stuck.has(id)), unreachable: [] };
+    }
+    const typeOf = new Map(nodes.map((n) => [n.id, n.type]));
+    const orders = new Map();
+    for (const id of topo) {
+        const causes = prev.get(id).map((p) => orders.get(p)).filter((o) => o !== undefined);
+        if (causes.length > 0)
+            orders.set(id, Math.max(...causes) + 1);
+        else if (typeOf.get(id) === SO_DECISION_TYPE)
+            orders.set(id, 0);
+    }
+    return { orders, unreachable: nodes.map((n) => n.id).filter((id) => !orders.has(id)) };
+}

package/dist/text.d.ts

@@ -0,0 +1,5 @@
+import type { TextRun } from './types.js';
+export declare function runsToPlainText(runs: TextRun[]): string;
+/** Canonical form: drop empty runs, coerce falsey marks away, merge adjacent
+ * runs whose marks match. */
+export declare function normalizeRuns(runs: TextRun[]): TextRun[];

package/dist/text.js

@@ -0,0 +1,25 @@
+export function runsToPlainText(runs) {
+    return runs.map((r) => r.text).join('');
+}
+/** Canonical form: drop empty runs, coerce falsey marks away, merge adjacent
+ * runs whose marks match. */
+export function normalizeRuns(runs) {
+    const out = [];
+    for (const r of runs) {
+        if (r.text === '')
+            continue;
+        const run = { text: r.text };
+        if (r.bold === true)
+            run.bold = true;
+        if (r.italic === true)
+            run.italic = true;
+        const prev = out[out.length - 1];
+        if (prev !== undefined && Boolean(prev.bold) === Boolean(run.bold) && Boolean(prev.italic) === Boolean(run.italic)) {
+            prev.text += run.text;
+        }
+        else {
+            out.push(run);
+        }
+    }
+    return out;
+}

package/dist/threat-model.d.ts

@@ -0,0 +1,88 @@
+import { type DiagramModel, type DiagramNode, type LayoutOverlay, type StrideCategory, type Threat, type ThreatStatus } from './types.js';
+/** The notation id a plane (or the model) declares to be drawn as a STRIDE
+ * data-flow diagram. */
+export declare const TM_NOTATION: "threat-model";
+export declare const TM_ENTITY_TYPE: "tm-entity";
+export declare const TM_PROCESS_TYPE: "tm-process";
+export declare const TM_STORE_TYPE: "tm-store";
+/** A trust boundary is a CONTAINER, never a box with arrows: "this flow crosses
+ * a boundary" is then derived from containment (see crossings) instead of being
+ * authored, and cannot disagree with the drawing. */
+export declare const TM_BOUNDARY_TYPE: "tm-boundary";
+export declare const TM_FLOW_KIND: "data-flow";
+export declare const TM_TYPES: ReadonlySet<string>;
+export declare const isThreatModelNode: (n: DiagramNode) => boolean;
+export declare const STRIDE_NAMES: Record<StrideCategory, string>;
+/** The title a threat gets when it is added from the canvas, before anyone has
+ * typed one. It is a real title rather than `''` because a threat with an empty
+ * title fails validation (`threat-title`) — and the studio autosaves on a timer,
+ * so an empty one would reach the save handler as a 400 while the user is still
+ * typing. Lives in core so every host seeds the same word, and so "was this ever
+ * titled?" is one comparison rather than a per-host convention. */
+export declare const NEW_THREAT_TITLE = "New threat";
+/** which element a threat command or register row refers to */
+export type ThreatTarget = {
+    node: string;
+} | {
+    relation: string;
+};
+/** The overlay key a threat target is filed under (`LayoutOverlay.notes`). Node
+ * and relation ids are separate namespaces — nothing stops a node and a relation
+ * sharing an id — so one flat map needs the prefix. */
+export declare const threatTargetKey: (t: ThreatTarget) => string;
+/** The element's threat list — `[]` when it carries none, undefined when there
+ * is no such element. The two are different answers: a note is drawn for the
+ * first case's element and the second is a dangling reference. */
+export declare function threatsOf(m: DiagramModel, t: ThreatTarget): readonly Threat[] | undefined;
+/** First free `t<n>`. Ids are scoped to their element, so a removed `t2` is
+ * handed out again rather than the counter climbing forever. */
+export declare function nextThreatId(threats: readonly Threat[]): string;
+/** the boundaries a relation's ends sit in; an absent side is "outside every boundary" */
+export interface Crossing {
+    from?: string;
+    to?: string;
+}
+export interface ThreatRow {
+    target: ThreatTarget;
+    /** the element's display name — a flow reads `from → to (label)` */
+    name: string;
+    threat: Threat;
+}
+export declare const isOpen: (t: Threat) => boolean;
+export declare function strideFor(typeOrKind: string | undefined): readonly StrideCategory[];
+/** The nearest trust boundary above `nodeId` on the viewed plane, or undefined
+ * outside every boundary. Containment is a DAG; the first parent by declaration
+ * order is the one followed — the same pick a reader makes from the drawing. */
+export declare function boundaryOf(m: DiagramModel, plane: string | undefined, nodeId: string): string | undefined;
+/** Every relation whose two ends sit in different boundaries — the flows STRIDE
+ * cares about. Derived from containment, not authored, and not filtered by kind:
+ * a boundary crossing is a fact about the drawing, whatever the arrow means. */
+export declare function crossings(m: DiagramModel, plane: string | undefined): ReadonlyMap<string, Crossing>;
+/** One end of a crossing, as a reader sees it: *outside* where the end sits in
+ * no boundary at all, otherwise the boundary node's name — or, for an id no node
+ * carries, the id itself, so a broken model still says which one it means. */
+export declare function boundaryName(m: DiagramModel, id: string | undefined): string;
+/** `DMZ ⇢ Backend`: a crossing read between the two BOUNDARIES its ends sit in.
+ * The other arrow is the whole point — a flow's own line reads `from → to` and
+ * names the elements, this one names the trust zones the flow leaves and enters.
+ * Formatted here rather than at each call site so the studio panel and the
+ * published table cannot word the same fact differently. */
+export declare function crossingLabel(m: DiagramModel, crossing: Crossing): string;
+/** The register: every threat in the model, nodes first then relations, each in
+ * declaration order — the one order the studio list and the published table share. */
+export declare function threatRegister(m: DiagramModel): ThreatRow[];
+export declare function threatSummary(threats: readonly Threat[] | undefined): {
+    open: number;
+    total: number;
+};
+/** the status a bubble's chip advances to on a click: the THREAT_STATUSES
+ * order, wrapping — an absent status is `open`, as isOpen reads it */
+export declare function nextThreatStatus(t: Threat): ThreatStatus;
+/**
+ * Whether every threat-bearing element in the model has an open bubble on
+ * `planeKey` — the studio's `Notes` chip reads pressed exactly then, so a
+ * press always does the thing the picture is missing (opens the rest, or
+ * closes all). Model-wide, like set-notes-open: the chip and the command must
+ * agree on what "all" means. False when nothing carries a threat.
+ */
+export declare function allNotesOpen(model: DiagramModel, layout: LayoutOverlay, planeKey: string): boolean;

package/dist/threat-model.js

@@ -0,0 +1,188 @@
+import { relationLabels } from './labels.js';
+import { STRIDE, THREAT_STATUSES, } from './types.js';
+import { containmentPlaneOf } from './view/hierarchy.js';
+/** The notation id a plane (or the model) declares to be drawn as a STRIDE
+ * data-flow diagram. */
+export const TM_NOTATION = 'threat-model';
+export const TM_ENTITY_TYPE = 'tm-entity';
+export const TM_PROCESS_TYPE = 'tm-process';
+export const TM_STORE_TYPE = 'tm-store';
+/** A trust boundary is a CONTAINER, never a box with arrows: "this flow crosses
+ * a boundary" is then derived from containment (see crossings) instead of being
+ * authored, and cannot disagree with the drawing. */
+export const TM_BOUNDARY_TYPE = 'tm-boundary';
+export const TM_FLOW_KIND = 'data-flow';
+export const TM_TYPES = new Set([TM_ENTITY_TYPE, TM_PROCESS_TYPE, TM_STORE_TYPE, TM_BOUNDARY_TYPE]);
+export const isThreatModelNode = (n) => n.type !== undefined && TM_TYPES.has(n.type);
+export const STRIDE_NAMES = {
+    S: 'Spoofing',
+    T: 'Tampering',
+    R: 'Repudiation',
+    I: 'Information disclosure',
+    D: 'Denial of service',
+    E: 'Elevation of privilege',
+};
+/** The title a threat gets when it is added from the canvas, before anyone has
+ * typed one. It is a real title rather than `''` because a threat with an empty
+ * title fails validation (`threat-title`) — and the studio autosaves on a timer,
+ * so an empty one would reach the save handler as a 400 while the user is still
+ * typing. Lives in core so every host seeds the same word, and so "was this ever
+ * titled?" is one comparison rather than a per-host convention. */
+export const NEW_THREAT_TITLE = 'New threat';
+/** The overlay key a threat target is filed under (`LayoutOverlay.notes`). Node
+ * and relation ids are separate namespaces — nothing stops a node and a relation
+ * sharing an id — so one flat map needs the prefix. */
+export const threatTargetKey = (t) => ('node' in t ? `node:${t.node}` : `relation:${t.relation}`);
+/** The element's threat list — `[]` when it carries none, undefined when there
+ * is no such element. The two are different answers: a note is drawn for the
+ * first case's element and the second is a dangling reference. */
+export function threatsOf(m, t) {
+    const el = 'node' in t ? m.nodes.find((n) => n.id === t.node) : m.relations.find((r) => r.id === t.relation);
+    return el === undefined ? undefined : (el.threats ?? []);
+}
+/** First free `t<n>`. Ids are scoped to their element, so a removed `t2` is
+ * handed out again rather than the counter climbing forever. */
+export function nextThreatId(threats) {
+    const taken = new Set(threats.map((t) => t.id));
+    let n = 1;
+    while (taken.has(`t${n}`))
+        n += 1;
+    return `t${n}`;
+}
+export const isOpen = (t) => (t.status ?? 'open') === 'open';
+/** STRIDE-per-element (the Microsoft table): which categories apply to a DFD
+ * element. A type outside the DFD vocabulary — a C4 container being
+ * threat-modelled on its own plane — gets every category offered. */
+const STRIDE_FOR = {
+    [TM_ENTITY_TYPE]: ['S', 'R'],
+    [TM_PROCESS_TYPE]: STRIDE,
+    [TM_STORE_TYPE]: ['T', 'R', 'I', 'D'],
+    [TM_FLOW_KIND]: ['T', 'I', 'D'],
+};
+export function strideFor(typeOrKind) {
+    return (typeOrKind !== undefined ? STRIDE_FOR[typeOrKind] : undefined) ?? STRIDE;
+}
+/** child → parents on the plane a view of `plane` uses (containmentOf resolved;
+ * an untagged edge belongs to the first-declared plane), declaration order kept */
+function planeParents(m, plane) {
+    const active = containmentPlaneOf(m, plane);
+    const defaultPlane = m.planes?.[0]?.id;
+    const parents = new Map();
+    for (const e of m.containment) {
+        if ((e.plane ?? defaultPlane) !== active)
+            continue;
+        parents.set(e.child, [...(parents.get(e.child) ?? []), e.parent]);
+    }
+    return parents;
+}
+function nearestBoundary(parents, typeOf, id) {
+    const seen = new Set();
+    let cur = parents.get(id)?.[0];
+    // `seen` is belt-and-braces: validation rejects containment cycles, but a
+    // derivation that runs every frame must not be able to spin on a bad model.
+    while (cur !== undefined && !seen.has(cur)) {
+        if (typeOf.get(cur) === TM_BOUNDARY_TYPE)
+            return cur;
+        seen.add(cur);
+        cur = parents.get(cur)?.[0];
+    }
+    return undefined;
+}
+/** The nearest trust boundary above `nodeId` on the viewed plane, or undefined
+ * outside every boundary. Containment is a DAG; the first parent by declaration
+ * order is the one followed — the same pick a reader makes from the drawing. */
+export function boundaryOf(m, plane, nodeId) {
+    return nearestBoundary(planeParents(m, plane), new Map(m.nodes.map((n) => [n.id, n.type])), nodeId);
+}
+/** Every relation whose two ends sit in different boundaries — the flows STRIDE
+ * cares about. Derived from containment, not authored, and not filtered by kind:
+ * a boundary crossing is a fact about the drawing, whatever the arrow means. */
+export function crossings(m, plane) {
+    const parents = planeParents(m, plane);
+    const typeOf = new Map(m.nodes.map((n) => [n.id, n.type]));
+    const cache = new Map();
+    const bOf = (id) => {
+        if (!cache.has(id))
+            cache.set(id, nearestBoundary(parents, typeOf, id));
+        return cache.get(id);
+    };
+    const out = new Map();
+    for (const r of m.relations) {
+        const from = bOf(r.from);
+        const to = bOf(r.to);
+        if (from === to)
+            continue;
+        // an absent side means "outside every boundary" — omitted rather than
+        // `undefined` so a serialized Crossing stays minimal
+        out.set(r.id, { ...(from !== undefined ? { from } : {}), ...(to !== undefined ? { to } : {}) });
+    }
+    return out;
+}
+/** One end of a crossing, as a reader sees it: *outside* where the end sits in
+ * no boundary at all, otherwise the boundary node's name — or, for an id no node
+ * carries, the id itself, so a broken model still says which one it means. */
+export function boundaryName(m, id) {
+    return id === undefined ? 'outside' : (m.nodes.find((n) => n.id === id)?.name ?? id);
+}
+/** `DMZ ⇢ Backend`: a crossing read between the two BOUNDARIES its ends sit in.
+ * The other arrow is the whole point — a flow's own line reads `from → to` and
+ * names the elements, this one names the trust zones the flow leaves and enters.
+ * Formatted here rather than at each call site so the studio panel and the
+ * published table cannot word the same fact differently. */
+export function crossingLabel(m, crossing) {
+    return `${boundaryName(m, crossing.from)} ⇢ ${boundaryName(m, crossing.to)}`;
+}
+/** The register: every threat in the model, nodes first then relations, each in
+ * declaration order — the one order the studio list and the published table share. */
+export function threatRegister(m) {
+    const rows = [];
+    for (const n of m.nodes)
+        for (const threat of n.threats ?? [])
+            rows.push({ target: { node: n.id }, name: n.name, threat });
+    const nameOf = (id) => m.nodes.find((n) => n.id === id)?.name ?? id;
+    for (const r of m.relations) {
+        if (r.threats === undefined || r.threats.length === 0)
+            continue;
+        const label = relationLabels(r)[0]?.text;
+        const name = `${nameOf(r.from)} → ${nameOf(r.to)}${label !== undefined && label !== '' ? ` (${label})` : ''}`;
+        for (const threat of r.threats)
+            rows.push({ target: { relation: r.id }, name, threat });
+    }
+    return rows;
+}
+export function threatSummary(threats) {
+    const list = threats ?? [];
+    return { open: list.filter(isOpen).length, total: list.length };
+}
+/** the status a bubble's chip advances to on a click: the THREAT_STATUSES
+ * order, wrapping — an absent status is `open`, as isOpen reads it */
+export function nextThreatStatus(t) {
+    const i = THREAT_STATUSES.indexOf(t.status ?? 'open');
+    return THREAT_STATUSES[(i + 1) % THREAT_STATUSES.length] ?? 'open';
+}
+/**
+ * Whether every threat-bearing element in the model has an open bubble on
+ * `planeKey` — the studio's `Notes` chip reads pressed exactly then, so a
+ * press always does the thing the picture is missing (opens the rest, or
+ * closes all). Model-wide, like set-notes-open: the chip and the command must
+ * agree on what "all" means. False when nothing carries a threat.
+ */
+export function allNotesOpen(model, layout, planeKey) {
+    const bucket = layout.notes?.[planeKey];
+    let any = false;
+    for (const n of model.nodes) {
+        if ((n.threats?.length ?? 0) === 0)
+            continue;
+        any = true;
+        if (bucket?.[threatTargetKey({ node: n.id })]?.open !== true)
+            return false;
+    }
+    for (const r of model.relations) {
+        if ((r.threats?.length ?? 0) === 0)
+            continue;
+        any = true;
+        if (bucket?.[threatTargetKey({ relation: r.id })]?.open !== true)
+            return false;
+    }
+    return any;
+}