@diagrammo/dgmo 0.47.0 → 0.48.0

package/src/utils/arrows.ts

@@ -1,227 +0,0 @@
-// ============================================================
-// Shared Arrow Parsing Utility
-// ============================================================
-//
-// Labeled arrow syntax (always left-to-right):
-//   Sync:  `-label->`
-//   Async: `~label~>`
-//
-// In-arrow label character-set contract (see docs/dgmo-language-spec.md
-// §"In-Arrow Message Labels"):
-//   - Allowed: any codepoint except the forbidden substrings and forbidden
-//     control characters below.
-//   - Forbidden substrings: "->", "~>" (arrow-token lookalikes inside labels).
-//     Use the post-colon form for labels that need these symbols:
-//       `A -> B: uses -> to chain`
-//   - Forbidden characters: C0 control chars U+0000–U+001F EXCEPT U+0009 (tab),
-//     and U+007F (DEL).
-//   - Whitespace: leading/trailing trimmed; internal runs (incl. tab, NBSP,
-//     ZWSP) preserved — never collapsed.
-//   - Plain text only: no markdown interpretation. `*`, `_`, backticks,
-//     `[`, `]`, `{`, `}` are literal characters.
-
-import type { DgmoError } from '../diagnostics';
-import { makeDgmoError } from '../diagnostics';
-
-interface ParsedArrow {
-  from: string;
-  to: string;
-  label: string;
-  async: boolean;
-}
-
-// ============================================================
-// Diagnostic codes (TD-16)
-// ============================================================
-
-/**
- * Stable diagnostic codes for in-arrow label parsing errors.
- *
- * **Active codes** — emitted by the parser pipeline today:
- *   - `ARROW_SUBSTRING_IN_LABEL` (TD-13)
- *   - `CONTROL_CHAR_IN_LABEL` (TD-14)
- *
- * See `docs/dgmo-language-spec-decisions.md` → TD-16 for the rationale.
- */
-export const ARROW_DIAGNOSTIC_CODES = {
-  /** Active: label contains `->` or `~>` substring (TD-13). */
-  ARROW_SUBSTRING_IN_LABEL: 'E_ARROW_SUBSTRING_IN_LABEL',
-  /** Active: label contains a forbidden control character (TD-14). */
-  CONTROL_CHAR_IN_LABEL: 'E_CONTROL_CHAR_IN_LABEL',
-} as const;
-
-// ============================================================
-// validateLabelCharacters (TD-13, TD-14)
-// ============================================================
-
-/**
- * Validate an in-arrow label against the TD-13 and TD-14 character-set
- * contract. Returns diagnostics (possibly empty). Does NOT mutate the label —
- * callers that want a normalized label should trim before calling.
- *
- * TD-13: label must not contain the substrings "->" or "~>".
- * TD-14: label must not contain C0 control chars other than tab, and no DEL.
- */
-export function validateLabelCharacters(
-  label: string,
-  lineNumber: number
-): DgmoError[] {
-  const out: DgmoError[] = [];
-
-  // TD-13: forbidden substrings
-  if (label.includes('->') || label.includes('~>')) {
-    out.push(
-      makeDgmoError(
-        lineNumber,
-        'Arrow symbols (-> or ~>) are not allowed inside a label. ' +
-          'Move the label after the arrow: "A -> B: uses -> to chain". ' +
-          'See "In-Arrow Message Labels" → Forbidden.',
-        'error',
-        ARROW_DIAGNOSTIC_CODES.ARROW_SUBSTRING_IN_LABEL
-      )
-    );
-  }
-
-  // TD-14: control chars (iterate codepoints to handle surrogate pairs)
-  for (const ch of label) {
-    const cp = ch.codePointAt(0)!;
-    const isC0 = cp >= 0x00 && cp <= 0x1f && cp !== 0x09; // allow tab
-    const isDel = cp === 0x7f;
-    if (isC0 || isDel) {
-      const hex = cp.toString(16).toUpperCase().padStart(4, '0');
-      out.push(
-        makeDgmoError(
-          lineNumber,
-          `Label contains a control character (U+${hex}). ` +
-            'Remove it and use plain text.',
-          'error',
-          ARROW_DIAGNOSTIC_CODES.CONTROL_CHAR_IN_LABEL
-        )
-      );
-      break; // one diagnostic per label is enough
-    }
-  }
-
-  return out;
-}
-
-// ============================================================
-// parseInArrowLabel (TD-1, TD-8, TD-10, TD-13, TD-14)
-// ============================================================
-
-export interface ParseInArrowLabelResult {
-  /** Cleaned label (trimmed; `undefined` if empty after trim per TD-10). */
-  label: string | undefined;
-  diagnostics: DgmoError[];
-}
-
-/**
- * Normalize and validate a raw in-arrow label.
- *
- * Behavior:
- *   - Trims leading/trailing whitespace (TD-8: internal whitespace preserved).
- *   - Empty-after-trim → `{ label: undefined }` (TD-10 normalization).
- *   - TD-13: emits `E_ARROW_SUBSTRING_IN_LABEL` if `->` or `~>` is present.
- *   - TD-14: emits `E_CONTROL_CHAR_IN_LABEL` for forbidden control chars.
- *
- * This helper is intentionally chart-agnostic: it operates on an already
- * extracted label string, leaving each chart's existing arrow-finding
- * tokenization in place. Edges no longer have a color slot on any chart
- * type (see spec §1.7 "Edge color is not a feature"); arrow content is
- * pure label text.
- */
-export function parseInArrowLabel(
-  rawLabel: string,
-  lineNumber: number
-): ParseInArrowLabelResult {
-  const trimmed = rawLabel.trim();
-
-  // TD-10: empty/whitespace-only label normalizes to undefined
-  if (trimmed.length === 0) {
-    return { label: undefined, diagnostics: [] };
-  }
-
-  // TD-13 / TD-14 validation
-  const diagnostics = validateLabelCharacters(trimmed, lineNumber);
-
-  return { label: trimmed, diagnostics };
-}
-
-// Forward (call) patterns — participant names may contain spaces, so use non-greedy (.+?)
-const SYNC_LABELED_RE = /^(.+?)\s*-(.+)->\s*(.+)$/;
-const ASYNC_LABELED_RE = /^(.+?)\s*~(.+)~>\s*(.+)$/;
-
-// Deprecated patterns — produce errors
-const RETURN_SYNC_LABELED_RE = /^(.+?)\s*<-(.+)-\s*(.+)$/;
-const RETURN_ASYNC_LABELED_RE = /^(.+?)\s*<~(.+)~\s*(.+)$/;
-const BIDI_SYNC_RE = /^(.+?)\s*<-(.+)->\s*(.+)$/;
-const BIDI_ASYNC_RE = /^(.+?)\s*<~(.+)~>\s*(.+)$/;
-
-/**
- * Try to parse a labeled arrow from a trimmed line.
- *
- * Returns:
- *  - `ParsedArrow` if matched and valid
- *  - `{ error: string }` if matched but invalid (deprecated syntax)
- *  - `null` if not a labeled arrow (caller should fall through to bare patterns)
- *
- * Note: arrow-char-in-label validation (TD-13) is NOT performed here —
- * callers must route the returned `label` through `parseInArrowLabel` or
- * `validateLabelCharacters` to get the unified `E_ARROW_SUBSTRING_IN_LABEL`
- * diagnostic with the correct code. In practice this path is unreachable
- * because arrow regexes are greedy enough to absorb inner `->`/`~>` tokens
- * into the source/destination captures, but the check remains at the
- * validator level for defense in depth.
- */
-export function parseArrow(
-  line: string
-): ParsedArrow | { error: string } | null {
-  // Check bidi patterns first — return error
-  if (BIDI_SYNC_RE.test(line) || BIDI_ASYNC_RE.test(line)) {
-    return {
-      error:
-        "Bidirectional arrows are no longer supported. Use two separate lines: 'A -msg-> B' and 'B -msg-> A'",
-    };
-  }
-
-  // Check deprecated return arrow patterns — return error
-  if (RETURN_SYNC_LABELED_RE.test(line) || RETURN_ASYNC_LABELED_RE.test(line)) {
-    const m =
-      line.match(RETURN_SYNC_LABELED_RE) ?? line.match(RETURN_ASYNC_LABELED_RE);
-    // RETURN_*_LABELED_RE both have 3 capture groups by construction.
-    const from = m![3]!;
-    const to = m![1]!;
-    const label = m![2]!.trim();
-    return {
-      error: `Left-pointing arrows are no longer supported. Write '${from} -${label}-> ${to}' instead`,
-    };
-  }
-
-  const patterns: {
-    re: RegExp;
-    async: boolean;
-  }[] = [
-    { re: SYNC_LABELED_RE, async: false },
-    { re: ASYNC_LABELED_RE, async: true },
-  ];
-
-  for (const { re, async: isAsync } of patterns) {
-    const m = line.match(re);
-    if (!m) continue;
-
-    // SYNC_LABELED_RE / ASYNC_LABELED_RE both have 3 capture groups.
-    const label = m[2]!.trim();
-
-    // Empty label (e.g. `--> B`) — fall through to plain arrow handling
-    if (!label) return null;
-
-    return {
-      from: m[1]!,
-      to: m[3]!,
-      label,
-      async: isAsync,
-    };
-  }
-
-  return null;
-}

package/src/utils/brand.ts

@@ -1,61 +0,0 @@
-// ============================================================
-// Branded types — compile-time nominal typing
-// ============================================================
-//
-// `Brand<T, B>` produces a type that is structurally `T` but
-// nominally distinct from other brands and from plain `T`. The
-// brand-marker property is `__brand` and is never actually written
-// at runtime — TypeScript intersects the type purely for compile-
-// time tracking.
-//
-// Used to catch ID-mixing bugs at compile time:
-//
-//   type NodeId = Brand<string, 'NodeId'>;
-//   type GroupId = Brand<string, 'GroupId'>;
-//
-//   function findNode(id: NodeId): Node;
-//   findNode(someGroupId);  // Type error — GroupId not assignable to NodeId.
-//
-// Brands erase fully at compile time: zero runtime cost, no
-// transformation, no extra JS output.
-
-/**
- * Tag a primitive type `T` with a phantom brand `B`. The brand
- * exists only in the type system — `Brand<string, 'X'>` is a `string`
- * at runtime, but TypeScript treats it as nominally distinct from
- * plain `string` and from any other `Brand<string, ...>`.
- */
-export type Brand<T, B extends string> = T & { readonly __brand: B };
-
-// ============================================================
-// Writable<T> — escape hatch for parsers that need a mutable
-// construction phase before returning a `readonly`-typed value.
-// ============================================================
-//
-// Usage:
-//
-//   interface ParsedKanban {
-//     readonly columns: readonly KanbanColumn[];
-//     ...
-//   }
-//
-//   function parseKanban(): ParsedKanban {
-//     const result: Writable<ParsedKanban> = { columns: [], ... };
-//     result.columns.push(...); // OK — Writable strips the readonly
-//     return result;             // OK — assignable back to ParsedKanban
-//   }
-//
-// `Writable<T>` flips `readonly` modifiers off shallowly. Nested
-// `readonly` arrays/objects keep their immutability — `WritableDeep`
-// is intentionally NOT provided because parsers rarely need it and
-// it's a sharp tool.
-
-/**
- * Strip top-level `readonly` modifiers from an object type, including
- * unwrapping `readonly T[]` array fields to mutable `T[]`. Element types
- * inside arrays/objects keep their own immutability — Writable is
- * intentionally shallow.
- */
-export type Writable<T> = {
-  -readonly [K in keyof T]: T[K] extends readonly (infer U)[] ? U[] : T[K];
-};

package/src/utils/card.ts

@@ -1,183 +0,0 @@
-// ============================================================
-// Node-card door (Story 111.1)
-// ============================================================
-//
-// The node card described in docs/architecture/diagram-visual-conventions.md §1
-// (rect → label → header separator → metadata rows) and the collapse accent bar
-// (§3) were hand-rolled inline in every structured-diagram renderer. This module
-// owns that drawing behind one interface, mirroring the `renderIntegratedLegend`
-// door (utils/legend-integration.ts): the renderer creates its wrapper `<g>` and
-// resolves geometry + colors (scaling and palette stay the renderer's job — see
-// ScaleContext / 111.3), then makes one call.
-//
-// Output is byte-identical to the prior inline code: same element order, same
-// attributes, same values. Scaled numbers are passed IN (the door never calls
-// ScaleContext), so rounding order is unchanged.
-
-import type { D3Sel } from './legend-types';
-import { measureText } from './text-measure';
-
-/** One resolved metadata row: a display key (already mapped) and its value. */
-export type CardMetaRow = readonly [displayKey: string, value: string];
-
-export interface CardMetaOptions {
-  /** Rows in display order. */
-  rows: readonly CardMetaRow[];
-  /** Scaled metadata font size. */
-  fontSize: number;
-  /** Scaled metadata line height. */
-  lineHeight: number;
-  /** Scaled gap between the header separator and the first row baseline. */
-  separatorGap: number;
-  /** Header separator stroke color (callers pass `solid ? labelColor : stroke`). */
-  separatorColor: string;
-  /** Fill for both key and value text (node cards use the label color for both). */
-  textColor: string;
-  /** Left inset for the key column (defaults to 10, the convention value). */
-  keyX?: number;
-}
-
-export interface NodeCardOptions {
-  /** Card width (already laid out). */
-  width: number;
-  /** Card height (already laid out). */
-  height: number;
-  /** Scaled corner radius. */
-  rx: number;
-  /** Resolved card fill. */
-  fill: string;
-  /** Resolved card stroke. */
-  stroke: string;
-  /** Scaled stroke width. */
-  strokeWidth: number;
-  /** Dashed border (e.g. org `isContainer`); uses the `'6 3'` convention pattern. */
-  dashed?: boolean;
-  /** Label text. */
-  label: string;
-  /** Resolved label color (also used for metadata text). */
-  labelColor: string;
-  /** Scaled label font size. */
-  labelFontSize: number;
-  /** Scaled header band height (positions the label and the separator). */
-  headerHeight: number;
-  /** Metadata block; omit (or pass empty rows) for a card with no separator/meta. */
-  meta?: CardMetaOptions;
-}
-
-/**
- * Draw a node card (rect → label → optional separator + metadata rows) into
- * `container` (the renderer's wrapper `<g>`). Reproduces conventions §1 exactly.
- */
-export function renderNodeCard(container: D3Sel, opts: NodeCardOptions): void {
-  const rect = container
-    .append('rect')
-    .attr('x', 0)
-    .attr('y', 0)
-    .attr('width', opts.width)
-    .attr('height', opts.height)
-    .attr('rx', opts.rx)
-    .attr('fill', opts.fill)
-    .attr('stroke', opts.stroke)
-    .attr('stroke-width', opts.strokeWidth);
-
-  if (opts.dashed) {
-    rect.attr('stroke-dasharray', '6 3');
-  }
-
-  container
-    .append('text')
-    .attr('x', opts.width / 2)
-    .attr('y', opts.headerHeight / 2 + opts.labelFontSize / 2 - 2)
-    .attr('text-anchor', 'middle')
-    .attr('fill', opts.labelColor)
-    .attr('font-size', opts.labelFontSize)
-    .attr('font-weight', 'bold')
-    .text(opts.label);
-
-  const meta = opts.meta;
-  if (!meta || meta.rows.length === 0) return;
-
-  container
-    .append('line')
-    .attr('x1', 0)
-    .attr('y1', opts.headerHeight)
-    .attr('x2', opts.width)
-    .attr('y2', opts.headerHeight)
-    .attr('stroke', meta.separatorColor)
-    .attr('stroke-opacity', 0.3)
-    .attr('stroke-width', 1);
-
-  const keyX = meta.keyX ?? 10;
-  const maxKeyWidth = Math.max(
-    ...meta.rows.map(([key]) => measureText(`${key}: `, meta.fontSize))
-  );
-  const valueX = keyX + maxKeyWidth;
-  const metaStartY = opts.headerHeight + meta.separatorGap + meta.fontSize;
-
-  for (let i = 0; i < meta.rows.length; i++) {
-    const [displayKey, value] = meta.rows[i]!;
-    const rowY = metaStartY + i * meta.lineHeight;
-
-    container
-      .append('text')
-      .attr('x', keyX)
-      .attr('y', rowY)
-      .attr('fill', meta.textColor)
-      .attr('font-size', meta.fontSize)
-      .text(`${displayKey}: `);
-
-    container
-      .append('text')
-      .attr('x', valueX)
-      .attr('y', rowY)
-      .attr('fill', meta.textColor)
-      .attr('font-size', meta.fontSize)
-      .text(value);
-  }
-}
-
-export interface CollapseBarOptions {
-  /** Card width. */
-  width: number;
-  /** Card height (the bar sits at the bottom). */
-  height: number;
-  /** Scaled bar height. */
-  barHeight: number;
-  /** Scaled horizontal inset from each edge (usually 0). */
-  inset: number;
-  /** Scaled corner radius for the clip rect (matches the card). */
-  rx: number;
-  /** Bar fill (callers pass `solid ? labelColor : stroke`). */
-  fill: string;
-  /** Unique clip-path id (kept renderer-local to avoid collisions). */
-  clipId: string;
-  /** Wrapper class for the bar rect (e.g. `org-collapse-bar`). */
-  className: string;
-}
-
-/**
- * Draw the collapse accent bar (conventions §3) at the bottom of a card,
- * clipped to the card's rounded corners. Reproduces the prior inline code.
- */
-export function renderCollapseBar(
-  container: D3Sel,
-  opts: CollapseBarOptions
-): void {
-  container
-    .append('clipPath')
-    .attr('id', opts.clipId)
-    .append('rect')
-    .attr('width', opts.width)
-    .attr('height', opts.height)
-    .attr('rx', opts.rx);
-
-  container
-    .append('rect')
-    .attr('x', opts.inset)
-    .attr('y', opts.height - opts.barHeight)
-    .attr('width', opts.width - opts.inset * 2)
-    .attr('height', opts.barHeight)
-    .attr('fill', opts.fill)
-    .attr('clip-path', `url(#${opts.clipId})`)
-    .attr('class', opts.className);
-}

package/src/utils/collapse-engine/tree-edges.ts

@@ -1,115 +0,0 @@
-// ============================================================
-// Collapse Engine — edge re-termination for trees (Story 110.1)
-// ============================================================
-//
-// The remap phase for hierarchical chart types with cross-links (sitemap). An
-// edge whose endpoint was pruned is walked up the ORIGINAL tree to the
-// outermost visible collapsed-container ancestor and re-terminated there.
-// Matches sitemap semantics exactly: no dedup (parallel edges keep distinct
-// labels for multigraph routing), self-loops dropped, unreachable edges dropped.
-
-import type { TreeCollapseShape } from './tree';
-import { collectTreeIds } from './tree';
-
-type NodeShape<N> = Pick<TreeCollapseShape<N>, 'getId' | 'getChildren'>;
-
-export interface EdgeEndpointShape<E> {
-  getSource(edge: E): string;
-  getTarget(edge: E): string;
-  /** Return a copy of `edge` with re-terminated endpoints. */
-  withEndpoints(edge: E, source: string, target: string): E;
-}
-
-function buildParentMap<N>(
-  roots: readonly N[],
-  shape: NodeShape<N>
-): Map<string, string> {
-  const map = new Map<string, string>();
-  const walk = (nodes: readonly N[]): void => {
-    for (const node of nodes) {
-      for (const child of shape.getChildren(node)) {
-        map.set(shape.getId(child), shape.getId(node));
-        walk([child]);
-      }
-    }
-  };
-  walk(roots);
-  return map;
-}
-
-/**
- * Walk up the original tree to the outermost visible ancestor that is itself a
- * collapsed container — the node that should absorb the edge endpoint.
- */
-function findVisibleAncestor(
-  nodeId: string,
-  parentMap: Map<string, string>,
-  visibleIds: Set<string>,
-  collapsedIds: Set<string>
-): string | null {
-  let current = nodeId;
-  while (true) {
-    const parentId = parentMap.get(current);
-    if (!parentId) return null;
-    if (visibleIds.has(parentId) && collapsedIds.has(parentId)) {
-      return parentId;
-    }
-    current = parentId;
-  }
-}
-
-/**
- * Re-terminate edges that reference pruned nodes. Both-visible edges pass
- * through (shallow-copied via `withEndpoints`); a hidden endpoint re-terminates
- * to its visible collapsed-container ancestor, or the edge is dropped if there
- * is none; resulting self-loops are dropped.
- */
-export function reterminateEdges<N, E>(
-  originalRoots: readonly N[],
-  prunedRoots: readonly N[],
-  edges: readonly E[],
-  collapsedIds: Set<string>,
-  nodeShape: NodeShape<N>,
-  edgeShape: EdgeEndpointShape<E>
-): E[] {
-  const visibleIds = collectTreeIds(prunedRoots, nodeShape);
-  const parentMap = buildParentMap(originalRoots, nodeShape);
-  const result: E[] = [];
-
-  for (const edge of edges) {
-    let sourceId = edgeShape.getSource(edge);
-    let targetId = edgeShape.getTarget(edge);
-    const sourceVisible = visibleIds.has(sourceId);
-    const targetVisible = visibleIds.has(targetId);
-
-    if (sourceVisible && targetVisible) {
-      result.push(edgeShape.withEndpoints(edge, sourceId, targetId));
-      continue;
-    }
-
-    if (!sourceVisible) {
-      const ancestor = findVisibleAncestor(
-        sourceId,
-        parentMap,
-        visibleIds,
-        collapsedIds
-      );
-      if (!ancestor) continue;
-      sourceId = ancestor;
-    }
-    if (!targetVisible) {
-      const ancestor = findVisibleAncestor(
-        targetId,
-        parentMap,
-        visibleIds,
-        collapsedIds
-      );
-      if (!ancestor) continue;
-      targetId = ancestor;
-    }
-
-    if (sourceId === targetId) continue;
-    result.push(edgeShape.withEndpoints(edge, sourceId, targetId));
-  }
-  return result;
-}