@dxos/diagram 0.11.1 → 0.13.0

package/src/architecture.ts

@@ -0,0 +1,215 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Architecture rules for a diagram's content: the software-engineering review rules the team applies
+// to code (`.agents/projects/architecture-rules`), restated for what a diagram shows — components,
+// the groups they belong to and who depends on whom. A decision model judges every rule in one call,
+// so grading a diagram costs one request however many rules there are.
+//
+
+import * as Decision from 'effect/ai/Decision';
+import * as DecisionModel from 'effect/ai/DecisionModel';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import type * as Mermaid from './mermaid.ts';
+import type * as Score from './score.ts';
+
+/** What a diagram says, plus optionally how it is drawn: the input every rule is judged against. */
+export const Content = Schema.Struct({
+  title: Schema.optional(Schema.String),
+  layout: Schema.optional(Schema.String).annotate({
+    description: 'A text rendering of the drawn page (`View`), so placement can be judged as a reader sees it.',
+  }),
+  groups: Schema.Array(Schema.Struct({ id: Schema.String, label: Schema.String })),
+  nodes: Schema.Array(
+    Schema.Struct({ id: Schema.String, label: Schema.String, group: Schema.optional(Schema.String) }),
+  ),
+  edges: Schema.Array(
+    Schema.Struct({
+      from: Schema.String,
+      to: Schema.String,
+      label: Schema.optional(Schema.String),
+      kind: Schema.optional(Schema.String).annotate({
+        description:
+          'Absent for a plain dependency; otherwise `inheritance`, `implements`, `hasMany`, `contains` (from owns ' +
+          'to) or `creates`.',
+      }),
+    }).annotate({ description: '`from` depends on, calls or owns `to`.' }),
+  ),
+});
+export type Content = Schema.Schema.Type<typeof Content>;
+
+/** The content of a parsed mermaid graph, with an optional caption and text rendering of its layout. */
+export const contentOf = (
+  graph: Mermaid.MermaidGraph,
+  { title, layout }: { title?: string; layout?: string } = {},
+): Content => ({
+  ...(title ? { title } : {}),
+  ...(layout ? { layout } : {}),
+  groups: graph.groups.map(({ id, label }) => ({ id, label })),
+  nodes: graph.nodes.map(({ id, label, group }) => ({ id, label, ...(group ? { group } : {}) })),
+  edges: graph.edges.map(({ from, to, label, kind }) => ({
+    from,
+    to,
+    ...(label ? { label } : {}),
+    ...(kind !== 'reference' ? { kind } : {}),
+  })),
+});
+
+export type Rule = {
+  /** Kebab-case, as the review rule it adapts is named. */
+  id: string;
+  /** Decision key: System One names questions by identifier. */
+  key: string;
+  description: string;
+  /** The question, phrased so `true` means the diagram follows the rule. */
+  instructions: string;
+  criteria: { false: string; true: string };
+};
+
+const HOW_TO_READ =
+  'The input is an architecture diagram: nodes are components, groups are layers or packages, and an edge ' +
+  '`from → to` means `from` depends on, calls or owns `to`. An `inheritance` or `implements` edge points from ' +
+  'the implementation to its abstraction, which by convention sits above it, so it is never a back-dependency. ' +
+  'When `layout` is present it shows the page as drawn.';
+
+const rule = (id: string, key: string, description: string, question: string, criteria: Rule['criteria']): Rule => ({
+  id,
+  key,
+  description,
+  instructions: `${HOW_TO_READ} ${question}`,
+  criteria,
+});
+
+/**
+ * The first batch of `architecture-rules`' recommended rules that a diagram can show, plus the
+ * bounded-state pair `non-negotiables.mdl` already enforces on code.
+ */
+export const RULES: readonly Rule[] = [
+  rule(
+    'dependency-direction',
+    'dependencyDirection',
+    'Dependencies point from higher-level layers to foundational ones, never back up.',
+    'Do all dependencies point one way, from higher-level or UI components towards foundational ones, with no ' +
+      'foundational component depending on a higher-level one and no cycle between groups?',
+    {
+      true: 'Every edge points downward in the layering; groups form a one-way stack.',
+      false: 'Some foundational component depends on a higher-level one, or two groups depend on each other.',
+    },
+  ),
+  rule(
+    'state-owned-once',
+    'stateOwnedOnce',
+    'Every piece of state has exactly one owner; others derive or subscribe.',
+    'Does the diagram show a single owner for each piece of state (store, table, cache, registry), with other ' +
+      'components reaching it through that owner rather than keeping mirrored copies or writing it directly?',
+    {
+      true: 'Each store has one owning component and everyone else goes through it.',
+      false: 'A store is written by several components, or state is mirrored in parallel copies.',
+    },
+  ),
+  rule(
+    'one-mechanism-per-concern',
+    'oneMechanismPerConcern',
+    'One mechanism serves each concern; no parallel components doing the same job.',
+    'Is each concern (transport, storage, scheduling, lookup, sync) served by one component, rather than two ' +
+      'parallel components that do the same job side by side?',
+    {
+      true: 'Every concern has one mechanism.',
+      false: 'Two components serve the same concern in parallel.',
+    },
+  ),
+  rule(
+    'no-pointless-indirection',
+    'noPointlessIndirection',
+    'Every node earns its place; no pass-through layer that only forwards to one other.',
+    'Does every component do real work of its own, rather than being a pass-through with one incoming and one ' +
+      'outgoing edge that only forwards calls?',
+    {
+      true: 'No node is a mere relay; each adds behavior, state or a boundary.',
+      false: 'At least one node only forwards to a single other node and could be removed.',
+    },
+  ),
+  rule(
+    'public-surface-only',
+    'publicSurfaceOnly',
+    "Consumers depend on a group's public entry point, not on its internals.",
+    'When an edge crosses from one group into another, does it land on the entry point or service that group ' +
+      'exposes, rather than reaching past it into an internal component?',
+    {
+      true: 'Cross-group edges land on each group’s entry point.',
+      false: 'Some edge from outside a group reaches an internal component directly.',
+    },
+  ),
+  rule(
+    'same-granularity',
+    'sameGranularity',
+    'Every box is a component at one level of abstraction.',
+    'Is every node a component at the same level of abstraction — services, modules or processes of comparable ' +
+      'weight — rather than a mix of components with their fields, caches, limits or data types drawn as boxes?',
+    {
+      true: 'All nodes are peers of comparable importance.',
+      false:
+        'Some nodes are internals of another node (a field, cache, limit or type) drawn as if they were components.',
+    },
+  ),
+  rule(
+    'bounded-live-state',
+    'boundedLiveState',
+    'Long-lived collections show who bounds them and who evicts finished entries.',
+    'For every long-lived collection the diagram shows (processes, invocations, queues, caches, indexes, records ' +
+      'of finished work), does it also show the component that owns it and so can bound it and evict finished ' +
+      'entries?',
+    {
+      true: 'Each long-lived collection has an owning component responsible for its limit and eviction.',
+      false: 'A collection grows with no owner shown that could bound it or evict from it.',
+    },
+  ),
+];
+
+/** The decision definition for a set of rules: one probability per rule, answered in one call. */
+export const definition = (rules: readonly Rule[] = RULES) =>
+  Decision.make({
+    input: Content,
+    decisions: Object.fromEntries(
+      rules.map(({ key, instructions, criteria }) => [key, Decision.probability({ instructions, criteria })]),
+    ),
+  });
+
+/**
+ * What a judge is shown: the diagram's content, and optionally the rendered page as images for a
+ * model that reads them (one that does not fails the call, which scores every rule as an error).
+ */
+export type Subject = { readonly content: Content; readonly images?: readonly DecisionModel.Image[] };
+
+/**
+ * Every rule as a score, from one `DecisionModel` call: the probability that the diagram follows the
+ * rule. A failed call scores every rule as an error rather than as 0, so an outage never reads as a
+ * bad diagram. `kind` labels the scores, so another rule set (e.g. `Aesthetics`) can share the judge.
+ */
+export const judge = (
+  rules: readonly Rule[] = RULES,
+  kind: Score.Kind = 'architecture',
+): Score.Batch<Subject, DecisionModel.DecisionModel> => {
+  const decisions = definition(rules);
+  return {
+    entries: rules.map(({ id, description }) => ({ id, kind, description })),
+    evaluate: ({ content, images }) =>
+      DecisionModel.decide(decisions, { input: content, ...(images?.length ? { images } : {}) }).pipe(
+        Effect.map(({ answers }) =>
+          rules.map(({ key }) => {
+            const answer = answers[key];
+            return answer ? { score: answer.probability } : { score: 0, error: 'No answer.' };
+          }),
+        ),
+        Effect.catch((error) =>
+          Effect.succeed(
+            rules.map(() => ({ score: 0, error: error instanceof Error ? error.message : String(error) })),
+          ),
+        ),
+      ),
+  };
+};

package/src/compact.test.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { compact } from './compact.ts';
+import type * as Scene from './scene.ts';
+
+const GEOMETRY = {
+  cell: { w: 192, h: 96 },
+  pitch: { x: 384, y: 224 },
+  framePad: 32,
+  frameLabel: 32,
+  frameGap: 32,
+};
+
+const at = (col: number, row: number): Scene.Point => ({ x: col * GEOMETRY.pitch.x, y: row * GEOMETRY.pitch.y });
+
+describe('compact', () => {
+  test('pulls a detached package up to the package it connects to', ({ expect }) => {
+    const graph = {
+      nodes: ['A', 'B', 'C', 'D'],
+      groups: [
+        { id: 'top', children: ['A', 'B'] },
+        { id: 'bottom', children: ['C', 'D'] },
+      ],
+      edges: [
+        { from: 'A', to: 'C' },
+        { from: 'C', to: 'D' },
+      ],
+    };
+    const positions = new Map([
+      ['A', at(0, 0)],
+      ['B', at(1, 0)],
+      ['C', at(0, 4)],
+      ['D', at(1, 4)],
+    ]);
+    const result = compact(graph, positions, GEOMETRY);
+
+    // One row of clearance holds both frames; the edge still runs down.
+    expect(result.get('A')).toEqual(at(0, 0));
+    expect(result.get('C')).toEqual(at(0, 1));
+    expect(result.get('D')).toEqual(at(1, 1));
+  });
+
+  test('never reverses an edge or stacks two boxes', ({ expect }) => {
+    const graph = {
+      nodes: ['A', 'B', 'C'],
+      groups: [],
+      edges: [
+        { from: 'A', to: 'B' },
+        { from: 'B', to: 'C' },
+      ],
+    };
+    const positions = new Map([
+      ['A', at(0, 0)],
+      ['B', at(0, 3)],
+      ['C', at(0, 6)],
+    ]);
+    const result = compact(graph, positions, GEOMETRY);
+    const rows = ['A', 'B', 'C'].map((id) => result.get(id)?.y ?? Number.NaN);
+
+    expect(rows).toEqual([at(0, 0).y, at(0, 1).y, at(0, 2).y]);
+    expect(new Set([...result.values()].map(({ x, y }) => `${x}:${y}`)).size).toBe(3);
+  });
+});

package/src/compact.ts

@@ -0,0 +1,219 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Post-placement compaction on the lattice. ELK spaces compound nodes by their padded extents and
+// quantization rounds every gap up, so a placement often carries empty lanes and packages parked
+// far from the package they talk to. A local search slides whole packages and single boxes by whole
+// lattice pitches toward their partners — never reversing an edge's direction on either axis, never
+// stacking two boxes and never bringing frames closer than their clearance — while the drawing's
+// connector length and extent fall.
+//
+
+import type * as Scene from './scene.ts';
+import { type Rect } from './uml-grid.ts';
+
+export type Geometry = {
+  /** Box size, shared by every node. */
+  cell: { w: number; h: number };
+  /** Lattice pitch; every move is a whole number of pitches. */
+  pitch: { x: number; y: number };
+  /** Inset of a frame around its members, and the label band above them. */
+  framePad: number;
+  frameLabel: number;
+  /** Clear space a frame keeps from other frames and from boxes outside it. */
+  frameGap: number;
+};
+
+export type Graph = {
+  nodes: readonly string[];
+  groups: readonly { id: string; children: readonly string[] }[];
+  edges: readonly { from: string; to: string }[];
+};
+
+/** Upper bound on improvement sweeps; each sweep tries every unit once. */
+const MAX_SWEEPS = 12;
+/** Farthest a unit moves in one step, in pitches per axis. */
+const MAX_REACH = 8;
+/** Cost of one connector whose ends share neither a row nor a column (it must bend). */
+const BEND_COST = 1;
+/** Cost of a lattice unit of drawing width or height, against one unit of connector length. */
+const EXTENT_COST = 1;
+
+type Points = Map<string, Scene.Point>;
+
+const sign = (value: number) => (value > 0 ? 1 : value < 0 ? -1 : 0);
+
+const orientation = (a: Scene.Point, b: Scene.Point, c: Scene.Point) =>
+  sign((b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x));
+
+/** Whether two segments properly cross; touching or collinear runs do not count. */
+const intersect = (a: Scene.Point, b: Scene.Point, c: Scene.Point, d: Scene.Point) => {
+  const [o1, o2, o3, o4] = [orientation(a, b, c), orientation(a, b, d), orientation(c, d, a), orientation(c, d, b)];
+  return o1 * o2 < 0 && o3 * o4 < 0;
+};
+
+const apart = (a: Rect, b: Rect, gap: number) =>
+  a.x + a.w + gap <= b.x || b.x + b.w + gap <= a.x || a.y + a.h + gap <= b.y || b.y + b.h + gap <= a.y;
+
+/**
+ * Compacts a lattice placement. Units are every package (moved rigidly) and every box (moved
+ * within or outside its package); a move is kept only when it lowers the cost — connector length
+ * plus bends plus the drawing's width and height, all in lattice units — and introduces no
+ * violation of the placement's invariants.
+ */
+export const compact = (graph: Graph, positions: ReadonlyMap<string, Scene.Point>, geometry: Geometry): Points => {
+  const { cell, pitch, framePad, frameLabel, frameGap } = geometry;
+  const edges = graph.edges.filter(
+    (edge) => positions.has(edge.from) && positions.has(edge.to) && edge.from !== edge.to,
+  );
+  const groups = graph.groups
+    .map((group) => ({ id: group.id, members: group.children.filter((id) => positions.has(id)) }))
+    .filter((group) => group.members.length > 0);
+  const grouped = new Set(groups.flatMap((group) => group.members));
+  const loose = [...positions.keys()].filter((id) => !grouped.has(id));
+  // Direction of every edge on each axis, which no move may reverse or flatten.
+  const signs = edges.map((edge) => {
+    const [from, to] = [positions.get(edge.from), positions.get(edge.to)];
+    return from && to ? { x: sign(to.x - from.x), y: sign(to.y - from.y) } : { x: 0, y: 0 };
+  });
+
+  const frameOf = (members: readonly string[], state: Points): Rect => {
+    const points = members.flatMap((id) => state.get(id) ?? []);
+    const x = Math.min(...points.map((point) => point.x)) - framePad;
+    const y = Math.min(...points.map((point) => point.y)) - framePad - frameLabel;
+    const right = Math.max(...points.map((point) => point.x)) + cell.w + framePad;
+    const bottom = Math.max(...points.map((point) => point.y)) + cell.h + framePad;
+    return { x, y, w: right - x, h: bottom - y };
+  };
+
+  /** Invariant breaches: stacked boxes, reversed edges, frames too close to frames or outside boxes. */
+  const violations = (state: Points) => {
+    let count = 0;
+    const taken = new Set<string>();
+    for (const point of state.values()) {
+      const key = `${point.x}:${point.y}`;
+      count += taken.has(key) ? 1 : 0;
+      taken.add(key);
+    }
+    edges.forEach((edge, index) => {
+      const [from, to] = [state.get(edge.from), state.get(edge.to)];
+      if (from && to && (sign(to.x - from.x) !== signs[index].x || sign(to.y - from.y) !== signs[index].y)) {
+        count++;
+      }
+    });
+    const frames = groups.map((group) => frameOf(group.members, state));
+    for (let index = 0; index < frames.length; index++) {
+      for (let other = index + 1; other < frames.length; other++) {
+        count += apart(frames[index], frames[other], frameGap) ? 0 : 1;
+      }
+      for (const id of loose) {
+        const point = state.get(id);
+        count += point && !apart(frames[index], { ...point, ...cell }, frameGap) ? 1 : 0;
+      }
+    }
+    return count;
+  };
+
+  // Straight centre-to-centre lines stand in for the routes, which do not exist yet; a move may not add crossings among them.
+  const crossings = (state: Points) => {
+    const center = (id: string) => {
+      const point = state.get(id);
+      return point ? { x: point.x + cell.w / 2, y: point.y + cell.h / 2 } : undefined;
+    };
+    const lines = edges.flatMap((edge) => {
+      const [from, to] = [center(edge.from), center(edge.to)];
+      return from && to ? [{ edge, from, to }] : [];
+    });
+    let count = 0;
+    for (let index = 0; index < lines.length; index++) {
+      for (let other = index + 1; other < lines.length; other++) {
+        const [a, b] = [lines[index], lines[other]];
+        const shared = [a.edge.from, a.edge.to].some((id) => id === b.edge.from || id === b.edge.to);
+        count += !shared && intersect(a.from, a.to, b.from, b.to) ? 1 : 0;
+      }
+    }
+    return count;
+  };
+
+  const cost = (state: Points) => {
+    let total = 0;
+    for (const edge of edges) {
+      const [from, to] = [state.get(edge.from), state.get(edge.to)];
+      if (from && to) {
+        const [dx, dy] = [Math.abs(to.x - from.x) / pitch.x, Math.abs(to.y - from.y) / pitch.y];
+        total += dx + dy + (dx > 0 && dy > 0 ? BEND_COST : 0);
+      }
+    }
+    const rects = [
+      ...groups.map((group) => frameOf(group.members, state)),
+      ...loose.flatMap((id) => {
+        const point = state.get(id);
+        return point ? [{ ...point, ...cell }] : [];
+      }),
+    ];
+    const width = Math.max(...rects.map((rect) => rect.x + rect.w)) - Math.min(...rects.map((rect) => rect.x));
+    const height = Math.max(...rects.map((rect) => rect.y + rect.h)) - Math.min(...rects.map((rect) => rect.y));
+    return total + EXTENT_COST * (width / pitch.x + height / pitch.y);
+  };
+
+  const units: (readonly string[])[] = [
+    ...groups.filter((group) => group.members.length > 1).map((group) => group.members),
+    ...[...positions.keys()].map((id) => [id]),
+  ];
+  const offsets = Array.from({ length: MAX_REACH * 2 + 1 }, (_, index) => index - MAX_REACH);
+  const moves = offsets
+    .flatMap((dx) => offsets.map((dy) => ({ dx, dy })))
+    .filter(({ dx, dy }) => dx !== 0 || dy !== 0)
+    .sort((left, right) => Math.abs(left.dx) + Math.abs(left.dy) - Math.abs(right.dx) - Math.abs(right.dy));
+
+  let state: Points = new Map(positions);
+  let current = cost(state);
+  let broken = violations(state);
+  let crossed = crossings(state);
+  for (let sweep = 0; sweep < MAX_SWEEPS; sweep++) {
+    let improved = false;
+    for (const unit of units) {
+      let best: { state: Points; cost: number; violations: number; crossings: number } | undefined;
+      for (const { dx, dy } of moves) {
+        const next = new Map(state);
+        for (const id of unit) {
+          const point = state.get(id);
+          if (point) {
+            next.set(id, { x: point.x + dx * pitch.x, y: point.y + dy * pitch.y });
+          }
+        }
+        const value = cost(next);
+        // Strictly cheaper by a margin, so float noise never shuffles equal layouts.
+        if (value < (best?.cost ?? current) - 1e-6) {
+          const breaches = violations(next);
+          const crossing = breaches <= broken ? crossings(next) : Infinity;
+          if (crossing <= crossed) {
+            best = { state: next, cost: value, violations: breaches, crossings: crossing };
+          }
+        }
+      }
+      if (best) {
+        state = best.state;
+        current = best.cost;
+        broken = best.violations;
+        crossed = best.crossings;
+        improved = true;
+      }
+    }
+    if (!improved) {
+      break;
+    }
+  }
+
+  // Keep the placement's top-left where it was, so a move of the first package does not shift the drawing.
+  const corner = (points: Iterable<Scene.Point>) => {
+    const list = [...points];
+    return { x: Math.min(...list.map((point) => point.x)), y: Math.min(...list.map((point) => point.y)) };
+  };
+  const [before, after] = [corner(positions.values()), corner(state.values())];
+  return new Map(
+    [...state].map(([id, point]) => [id, { x: point.x - after.x + before.x, y: point.y - after.y + before.y }]),
+  );
+};