@githolon/dsl 0.1.0

package/src/codegen_dot.ts

@@ -0,0 +1,466 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * Graphviz `.dot` ENTITY-RELATIONSHIP emitter (DSL decision-6's diagram projection:
+ * the SAME in-memory `DomainModule` that lowers to TS/Dart/manifest ALSO renders to a
+ * human-readable ER diagram). It is a PURE function `DomainModule -> string`: no file
+ * reads, no clock, no IO. Like every other Nomos artifact it is DETERMINISTIC — every
+ * collection (aggregates, fields, edges, contexts) is SORTED so the same domain yields
+ * BYTE-IDENTICAL `.dot` every run ([[determinism-or-death]] applies to generated
+ * artifacts too: a diff in the diagram must mean a diff in the domain).
+ *
+ * This is an OPTIONAL, OFF-BY-DEFAULT projection: nothing here is part of the domain
+ * IDENTITY (`manifest.ts`) — it is a pure presentation layer, like `codegen_dart.ts`.
+ * The emit step writes `<domain>.dot` ONLY when its caller passes the `--emit-dot`
+ * compiler flag; when the flag is absent this module is never reached and not one
+ * existing generated byte changes.
+ *
+ * What it draws:
+ *   - each AGGREGATE as a Graphviz record/HTML-table node listing its fields
+ *     (`name : kind`), marking the id field (🔑), ref fields (→Target), and OPTIONAL
+ *     fields; engine-projected DERIVED / COMBINED read fields render in a distinct
+ *     italic compartment (they live ONLY in the read model, never the ledger).
+ *   - each REF/RELATION as an edge `source → target` with a CARDINALITY marker drawn
+ *     in crow's-foot notation (an aggregate that REFERENCES another is the "many"
+ *     end pointing at the "one" end of its target).
+ *   - aggregates GROUPED by BOUNDED CONTEXT — the set of directives that own (write)
+ *     an aggregate via `.creates/.mutates/.ensures/.archives`. Each context is a
+ *     coloured `subgraph cluster_*`.
+ *   - cross-workspace RELATION declarations (`relation(...).proposes(...)`) as dashed
+ *     PR-tier edges annotated with the proposed directive + the disclosure read.
+ *   - a header comment naming the domain + "generated by the Nomos DSL".
+ */
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field, FieldKind } from "./fields.js";
+import type { Directive } from "./directive.js";
+import type { RelationDecl } from "./relation.js";
+import type { DerivedDecl } from "./derived.js";
+import type { CombinedDecl } from "./combined.js";
+import type { DomainModule } from "./codegen_dart.js";
+
+/** A directive of any payload type — the emitter only introspects the contract shape. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyDirective = Directive<any>;
+
+/** Options for the ER emitter. Both default to OFF / minimal, so the smallest call
+ * `emitDomainDot(mod)` produces the clean core diagram. */
+export interface DotOptions {
+  /** Also draw the cross-workspace RELATION declarations as dashed PR-tier edges. Default true. */
+  readonly relations?: boolean;
+  /** Annotate aggregate-invariant presence with a guard badge on the node. Default true. */
+  readonly invariants?: boolean;
+}
+
+/** A palette of distinct, light, print-friendly fills — one per bounded context.
+ * Indexed by the context's SORTED position so colour assignment is deterministic. */
+const CONTEXT_FILLS: readonly string[] = [
+  "#E8F0FE", // blue
+  "#E6F4EA", // green
+  "#FEF7E0", // amber
+  "#FCE8E6", // red
+  "#F3E8FD", // purple
+  "#E4F7FB", // cyan
+  "#FFF0E6", // orange
+  "#EFEFEF", // grey
+];
+/** The matching darker border per fill (same index). */
+const CONTEXT_BORDERS: readonly string[] = [
+  "#1A73E8",
+  "#34A853",
+  "#F9AB00",
+  "#EA4335",
+  "#A142F4",
+  "#12B5CB",
+  "#FA7B17",
+  "#9AA0A6",
+];
+
+/** Escape a string for inclusion inside a Graphviz HTML-like label (table cells). */
+function htmlEscape(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/** Escape a string for a Graphviz quoted attribute value (edge/graph labels). */
+function attrEscape(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/** A Graphviz-safe node id: only `[A-Za-z0-9_]`, so a wire id with odd chars is safe.
+ * Deterministic + injective for the id space the DSL allows (alnum + `_`). */
+function nodeId(aggregateId: string): string {
+  return "agg_" + aggregateId.replace(/[^A-Za-z0-9_]/g, "_");
+}
+
+/** A short human kind label for a field — the type shown after the field name. For a
+ * ref it names the TARGET aggregate type (`→Target`); a map shows its value kind. */
+function fieldKindLabel(field: Field): string {
+  const kind: FieldKind = field.kind;
+  if (kind === "ref") {
+    const target = field.refAggregateId ?? "?";
+    const ws = field.refWorkspace !== undefined ? `@${field.refWorkspace} ` : "";
+    return `ref →${ws}${target}`;
+  }
+  if (kind === "map") {
+    return `map<${field.mapValueKind ?? "json"}>`;
+  }
+  return kind;
+}
+
+/** Heuristic: which field is the aggregate's IDENTITY field? The DSL has no explicit
+ * id marker, but the universal convention (every golden + tenant domain) is a field
+ * named exactly `<lowerFirst(typeStem)>Id` or simply `id`. We pick, deterministically:
+ *   1. a field literally named `id`, else
+ *   2. the first (sorted) field whose name ends in `Id` AND is a non-ref scalar.
+ * Returns `undefined` when nothing matches (still a valid node — just no 🔑). */
+function idFieldOf(agg: AggregateHandle): string | undefined {
+  const names = Object.keys(agg.fields).sort();
+  if (names.includes("id")) return "id";
+  for (const n of names) {
+    const f = (agg.fields as Record<string, Field>)[n]!;
+    if (n.endsWith("Id") && f.kind !== "ref") return n;
+  }
+  return undefined;
+}
+
+/** Resolve, per aggregate id, the SORTED set of directive ids that WRITE it (its
+ * bounded context membership). An aggregate written by directives is owned by the
+ * context those directives form; an aggregate NOBODY writes (a pure read target /
+ * cross-workspace endpoint) lands in a synthetic `(unowned)` context. */
+function ownersByAggregate(directives: readonly AnyDirective[]): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  for (const d of directives) {
+    const list = out.get(d.aggregateId) ?? [];
+    list.push(d.id);
+    out.set(d.aggregateId, list);
+  }
+  for (const [k, v] of out) out.set(k, [...new Set(v)].sort());
+  return out;
+}
+
+/**
+ * The BOUNDED CONTEXT key for an aggregate — its ownership cluster. An aggregate is
+ * OWNED by the directives that DECLARE it as their referential target
+ * (`.creates/.mutates/.ensures/.archives`); the context is named, deterministically, by
+ * the lexicographically-FIRST owning directive id. An aggregate NOBODY writes (a pure
+ * read target / cross-workspace endpoint) lands in a synthetic `<id> (unowned)` context.
+ *
+ * Grouping uses union-find over each directive's declared target set so that, the day a
+ * directive can declare MULTIPLE targets, co-declared aggregates collapse into one
+ * context automatically. Today each directive declares a single `aggregateId` (plan-body
+ * fan-out to sibling aggregates is executable behaviour the emitter cannot statically
+ * see), so each declared aggregate forms its own context — the honest, knowable grouping.
+ */
+function contextOf(
+  aggregates: readonly AggregateHandle[],
+  directives: readonly AnyDirective[],
+): Map<string, string> {
+  // union-find over aggregate ids
+  const parent = new Map<string, string>();
+  const find = (x: string): string => {
+    let r = x;
+    while (parent.get(r) !== r) r = parent.get(r)!;
+    // path-compress
+    let c = x;
+    while (parent.get(c) !== r) {
+      const n = parent.get(c)!;
+      parent.set(c, r);
+      c = n;
+    }
+    return r;
+  };
+  const union = (a: string, b: string): void => {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra === rb) return;
+    // deterministic merge: the lexicographically-smaller root wins
+    if (ra < rb) parent.set(rb, ra);
+    else parent.set(ra, rb);
+  };
+  for (const a of aggregates) if (!parent.has(a.id)) parent.set(a.id, a.id);
+  // any aggregate only referenced by a directive must also exist as a node root
+  for (const d of directives) if (!parent.has(d.aggregateId)) parent.set(d.aggregateId, d.aggregateId);
+
+  // group aggregates co-written by one directive (multi-aggregate plans bind contexts)
+  const byDirective = new Map<string, string[]>();
+  for (const d of directives) {
+    const list = byDirective.get(d.id) ?? [];
+    list.push(d.aggregateId);
+    byDirective.set(d.id, list);
+  }
+  for (const aggs of byDirective.values()) {
+    for (let i = 1; i < aggs.length; i++) union(aggs[0]!, aggs[i]!);
+  }
+
+  // context label = the SORTED-first owning directive id of the group, else the root
+  // aggregate id itself (for an unowned aggregate). Build root → label deterministically.
+  const owners = ownersByAggregate(directives);
+  const rootLabel = new Map<string, string>();
+  const allRoots = [...new Set([...parent.keys()].map(find))].sort();
+  for (const root of allRoots) {
+    // gather every aggregate id in this root's group
+    const members = [...parent.keys()].filter((k) => find(k) === root).sort();
+    // the group's owning directives, sorted; first = label, else "(unowned)"
+    const dirs = members.flatMap((m) => owners.get(m) ?? []);
+    const uniq = [...new Set(dirs)].sort();
+    rootLabel.set(root, uniq.length > 0 ? uniq[0]! : `${root} (unowned)`);
+  }
+
+  const out = new Map<string, string>();
+  for (const a of aggregates) out.set(a.id, rootLabel.get(find(a.id))!);
+  // also place referenced-only aggregates if any (defensive — usually all are in `aggregates`)
+  return out;
+}
+
+/** Build the HTML-like record label for ONE aggregate node. */
+function aggregateLabel(
+  agg: AggregateHandle,
+  border: string,
+  deriveds: readonly DerivedDecl[],
+  combineds: readonly CombinedDecl[],
+  showInvariant: boolean,
+): string {
+  const idField = idFieldOf(agg);
+  const fieldNames = Object.keys(agg.fields).sort();
+  const guard = showInvariant && agg.hasInvariant === true ? " 🛡" : "";
+
+  const titleRow =
+    `<TR><TD BGCOLOR="${border}" ALIGN="CENTER">` +
+    `<FONT COLOR="white"><B>${htmlEscape(agg.id)}${guard}</B></FONT></TD></TR>`;
+
+  const fieldRows = fieldNames
+    .map((name) => {
+      const f = (agg.fields as Record<string, Field>)[name]!;
+      const key = name === idField ? "🔑 " : "";
+      const opt = f.isOptional ? "?" : "";
+      const kindLabel = fieldKindLabel(f);
+      // a ref field is highlighted (it is the edge source); optional fields are dimmed.
+      const nameHtml = `<B>${htmlEscape(key + name)}${opt}</B>`;
+      const kindHtml = `<FONT COLOR="#5F6368"><I> : ${htmlEscape(kindLabel)}</I></FONT>`;
+      return `<TR><TD ALIGN="LEFT" PORT="${attrEscape(name)}">${nameHtml}${kindHtml}</TD></TR>`;
+    })
+    .join("");
+
+  // engine-projected READ fields (derived + combined) — a distinct compartment; these
+  // live ONLY in the read model, NEVER the ledger, so they are drawn italic + dimmed.
+  const readFields = [
+    ...deriveds.map((d) => ({ id: d.id, kind: "derived" })),
+    ...combineds.map((c) => ({ id: c.id, kind: `combined ←${c.reads}` })),
+  ].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const readRows =
+    readFields.length === 0
+      ? ""
+      : `<TR><TD ALIGN="CENTER" BGCOLOR="#F1F3F4">` +
+        `<FONT COLOR="#5F6368" POINT-SIZE="9"><I>projection (derived)</I></FONT></TD></TR>` +
+        readFields
+          .map(
+            (r) =>
+              `<TR><TD ALIGN="LEFT"><FONT COLOR="#5F6368"><I>∂ ${htmlEscape(r.id)} : ${htmlEscape(
+                r.kind,
+              )}</I></FONT></TD></TR>`,
+          )
+          .join("");
+
+  return (
+    `<<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">` +
+    titleRow +
+    fieldRows +
+    readRows +
+    `</TABLE>>`
+  );
+}
+
+interface DotEdge {
+  /** sort key — the full edge text, for deterministic ordering */
+  readonly key: string;
+  readonly line: string;
+}
+
+/**
+ * Emit the Graphviz `.dot` ENTITY-RELATIONSHIP diagram for one domain module.
+ *
+ * PURE + DETERMINISTIC: every collection is sorted, so the same `DomainModule` yields
+ * byte-identical output. The result renders cleanly with `dot -Tpng`.
+ */
+export function emitDomainDot(mod: DomainModule, opts: DotOptions = {}): string {
+  const drawRelations = opts.relations ?? true;
+  const drawInvariants = opts.invariants ?? true;
+
+  const aggregates = [...mod.aggregates].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const directives = [...mod.directives].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const knownIds = new Set(aggregates.map((a) => a.id));
+
+  // derived/combined read fields grouped by owner aggregate type.
+  const derivedsByType = new Map<string, DerivedDecl[]>();
+  for (const d of mod.deriveds ?? []) {
+    const list = derivedsByType.get(d.of) ?? [];
+    list.push(d);
+    derivedsByType.set(d.of, list);
+  }
+  const combinedsByType = new Map<string, CombinedDecl[]>();
+  for (const c of mod.combineds ?? []) {
+    const list = combinedsByType.get(c.of) ?? [];
+    list.push(c);
+    combinedsByType.set(c.of, list);
+  }
+
+  // ---- bounded contexts (deterministic colour assignment) -------------------
+  const ctxByAgg = contextOf(aggregates, directives);
+  const contextLabels = [...new Set(ctxByAgg.values())].sort();
+  const ctxIndex = new Map<string, number>();
+  contextLabels.forEach((label, i) => ctxIndex.set(label, i));
+  const fillFor = (label: string): string =>
+    CONTEXT_FILLS[ctxIndex.get(label)! % CONTEXT_FILLS.length]!;
+  const borderFor = (label: string): string =>
+    CONTEXT_BORDERS[ctxIndex.get(label)! % CONTEXT_BORDERS.length]!;
+
+  // ---- header ---------------------------------------------------------------
+  const lines: string[] = [];
+  lines.push(`// Entity-relationship diagram for domain "${mod.name}"`);
+  lines.push(`// generated by the Nomos DSL — codegen_dot.ts (deterministic, sorted)`);
+  lines.push(`// boxes = aggregates · crow's-foot edges = refs · clusters = bounded contexts`);
+  lines.push(`digraph ${nodeId(mod.name)}_er {`);
+  lines.push(`  graph [rankdir=LR, splines=polyline, nodesep=0.6, ranksep=1.2, fontname="Helvetica", labelloc="t", label="${attrEscape(mod.name)} — Nomos domain ER"];`);
+  lines.push(`  node  [shape=plaintext, fontname="Helvetica"];`);
+  lines.push(`  edge  [fontname="Helvetica", fontsize=10, color="#5F6368"];`);
+  lines.push("");
+
+  // ---- one cluster per bounded context, nodes sorted within -----------------
+  contextLabels.forEach((label, i) => {
+    const members = aggregates.filter((a) => ctxByAgg.get(a.id) === label);
+    if (members.length === 0) return;
+    const fill = fillFor(label);
+    const border = borderFor(label);
+    lines.push(`  subgraph cluster_ctx_${i} {`);
+    lines.push(`    label="context: ${attrEscape(label)}";`);
+    lines.push(`    style="rounded,filled"; color="${border}"; fillcolor="${fill}"; fontname="Helvetica-Bold"; fontsize=11;`);
+    for (const agg of members) {
+      const label2 = aggregateLabel(
+        agg,
+        border,
+        derivedsByType.get(agg.id) ?? [],
+        combinedsByType.get(agg.id) ?? [],
+        drawInvariants,
+      );
+      lines.push(`    ${nodeId(agg.id)} [label=${label2}];`);
+    }
+    lines.push(`  }`);
+    lines.push("");
+  });
+
+  // ---- REF edges (intra/inter-aggregate references) -------------------------
+  // crow's-foot: the referencing aggregate is the MANY end (crow + tee = "one or many"
+  // pointing at the target's ONE end). We draw arrowtail at the source (crow) and
+  // arrowhead at the target (none, classic ER "one"). A ref field's edge is labelled
+  // with the field name + cardinality `*..1`.
+  const refEdges: DotEdge[] = [];
+  for (const agg of aggregates) {
+    const fieldNames = Object.keys(agg.fields).sort();
+    for (const name of fieldNames) {
+      const f = (agg.fields as Record<string, Field>)[name]!;
+      if (f.kind !== "ref" || f.refAggregateId === undefined) continue;
+      const target = f.refAggregateId;
+      const targetNode = knownIds.has(target) ? nodeId(target) : nodeId(target);
+      const cross = f.refWorkspace !== undefined ? ` @${f.refWorkspace}` : "";
+      // many (source) -> one (target): crow's-foot at the source tail.
+      const line =
+        `  ${nodeId(agg.id)}:${attrEscape(name)} -> ${targetNode} ` +
+        `[arrowtail=crowtee, arrowhead=none, dir=both, ` +
+        `label="${attrEscape(name)}${cross}", taillabel="*", headlabel="1"];`;
+      refEdges.push({ key: `${agg.id}.${name}->${target}`, line });
+      // ensure a referenced-but-undeclared target still appears as a node.
+      if (!knownIds.has(target)) {
+        refEdges.push({
+          key: `~node~${target}`,
+          line: `  ${nodeId(target)} [label="${attrEscape(target)}", shape=box, style="dashed,filled", fillcolor="#FFFFFF", color="#9AA0A6"];`,
+        });
+      }
+    }
+  }
+  // dedupe synthetic-node lines + sort all edges for determinism.
+  const seen = new Set<string>();
+  const refLines = refEdges
+    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+    .filter((e) => {
+      if (seen.has(e.key)) return false;
+      seen.add(e.key);
+      return true;
+    })
+    .map((e) => e.line);
+  if (refLines.length > 0) {
+    lines.push(`  // --- references (crow's-foot: * -> 1) ---`);
+    lines.push(...refLines);
+    lines.push("");
+  }
+
+  // ---- cross-workspace RELATION edges (dashed PR-tier) ----------------------
+  if (drawRelations) {
+    const relEdges: DotEdge[] = [];
+    // relation endpoints (source/target aggregate TYPEs) that are NOT declared in THIS
+    // domain — they live in another workspace/domain. Draw them as dashed "external"
+    // boxes so the edge lands on a labelled node, not a bare default. Deduped + sorted.
+    const externalEndpoints = new Set<string>();
+    for (const d of directives) {
+      for (const rel of d.declaredRelations ?? []) {
+        relEdges.push(relationEdge(rel, knownIds));
+        if (!knownIds.has(rel.source)) externalEndpoints.add(rel.source);
+        if (!knownIds.has(rel.target)) externalEndpoints.add(rel.target);
+      }
+    }
+    for (const ext of [...externalEndpoints].sort()) {
+      relEdges.push({
+        key: `~ext~${ext}`,
+        line:
+          `  ${nodeId(ext)} [label="${attrEscape(ext)}\\n(external domain)", shape=box, ` +
+          `style="dashed,filled,rounded", fillcolor="#FFFFFF", color="#9AA0A6", fontcolor="#5F6368"];`,
+      });
+    }
+    const relLines = relEdges
+      .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+      .map((e) => e.line);
+    if (relLines.length > 0) {
+      lines.push(`  // --- cross-workspace relations (dashed: PR-tier, source proposes -> target adjudicates) ---`);
+      lines.push(...relLines);
+      lines.push("");
+    }
+  }
+
+  lines.push(`}`);
+  // trailing newline keeps the artifact POSIX-clean + byte-stable.
+  return lines.join("\n") + "\n";
+}
+
+/** Render one cross-workspace relation as a dashed PR-tier edge `source → target`,
+ * annotated with the proposed directive + the disclosed read (the disclosure contract). */
+function relationEdge(rel: RelationDecl, knownIds: Set<string>): DotEdge {
+  const src = nodeId(rel.source);
+  const tgt = nodeId(rel.target);
+  const guard = rel.hasInvariant ? " 🛡" : "";
+  const select = [...rel.evidence.select].sort().join(",");
+  // Each segment is attr-escaped INDIVIDUALLY, then joined with a literal Graphviz line
+  // break (`\n` — the two source chars backslash-n, NOT escaped, so the renderer wraps).
+  const label = [
+    `${attrEscape(rel.id)}${guard}`,
+    `proposes ${attrEscape(rel.proposes)}`,
+    `discloses {${attrEscape(select)}}`,
+  ].join("\\n");
+  // a relation proposes a contribution INTO the target → arrow points at the target;
+  // it is a 0..* (many sources may propose) to 1..1 (one target directive) PR edge.
+  const line =
+    `  ${src} -> ${tgt} [style=dashed, color="#A142F4", penwidth=1.5, ` +
+    `arrowhead=veevee, arrowtail=odot, dir=both, fontcolor="#A142F4", ` +
+    `label="${label}", taillabel="0..*", headlabel="1"];`;
+  // best-effort: if an endpoint is unknown it still resolves to a node id (Graphviz
+  // creates a default box). `knownIds` is accepted for parity with refEdges; relation
+  // endpoints are aggregate TYPE ids that may live in another domain entirely.
+  void knownIds;
+  return { key: `rel:${rel.id}:${rel.source}->${rel.target}`, line };
+}