hexwright 0.1.0 → 0.2.0

package/README.md

@@ -90,19 +90,63 @@ as a hub with the domains that touch it around it.
 | `impact` | the above plus everything that depends on a changed type |
 | `core` | Entity · Service · UseCase · Port · Event — the whole shape |
 | `all` | everything, adapters and DTOs included |
+| `violations` | only the breaches, and the types they run through |
 | `domain:<name>` | one bounded context and what it touches |
 
+`violations` is a **state** view: it draws what is wrong now, not what this branch
+changed. Unlike the toggle in the web UI it is not narrowed by component, because
+a violation with one end hidden reads as no violation at all.
+
+### Before and after
+
+A branch that *removes* violations, or swaps one port for another, is not
+described by the delta alone. The picture worth showing is the state it started
+from — which is exactly the state the working tree no longer has. `--at base`
+draws the same types in their pre-branch state:
+
+```bash
+hexwright render --repo . --base main --at base --image before.png
+hexwright render --repo . --base main            --image after.png
+```
+
+The before picture carries **no delta styling** — nothing in a picture of the past
+can be added or modified — and violations stay red, which is the question it
+exists to answer. It needs `--base`. A branch that only adds types has no before
+state at all; the command says so and exits 0.
+
+A before/after pair **lines up**. Positions, domain boxes, colours and canvas
+width all follow the set of types being laid out, and the two halves differ by
+whatever the branch added or removed — so each render lays out from the union of
+both and draws only its own half. A type keeps its place across the pair, and a
+deletion leaves the gap where it used to be. Neither command needs a flag for
+this and neither can be run "wrong": both derive the union from the same two
+graphs.
+
 There is no browser involved — the coordinates are a pure function, so the SVG
 is written directly and CI needs no headless Chrome. The same graph always draws
-the same file, which is what makes two branches comparable.
+the same file.
 
 `--image x.png` also writes `x.svg`. PNG needs the optional `@resvg/resvg-js`;
 without it the SVG is still written and the command says so. GitHub does not
 render SVG in comments, so attach the PNG there and keep the SVG as the artifact.
 
-Layout follows the view — `organic` for `delta` and `domain:`, `hex` for `core`
-and `all` (concentric rings, read as a shape). `--layout organic|grid|hex`
-overrides; `grid` lists domains left to right, ignoring coupling.
+Layout follows the view — `organic` for `delta`, `domain:` and `violations`, `hex`
+for `core` and `all` (concentric rings, read as a shape). `--layout
+organic|grid|hex` overrides; `grid` lists domains left to right, ignoring
+coupling.
+
+## Exit codes
+
+| command | 1 | 0 |
+|---|---|---|
+| `check` | the repository has a violation — with `--scope delta`, only one the branch introduced | otherwise |
+| `render` | a bad argument, or a base ref that is not in the clone | an image was written, **or there was nothing to draw** |
+| `extract` | the source root or the base ref cannot be read | otherwise |
+
+`render` treats an empty picture as an answer rather than a failure. `--view
+violations` on the branch that removed the last one, and `--at base` on a branch
+that only adds types, both print what happened and exit 0 — a non-zero exit there
+would break the very script that produces the pair.
 
 ## MCP
 
@@ -331,6 +375,30 @@ is a violation:
 - a DTO or UseCase exposing an Entity — domain model leaked into a contract
 - application/domain referencing adapter — layer back-reference
 
+## Releasing
+
+Trunk-based, tag-triggered. There is no release branch: `main` is the only branch
+that ships, and one can always be cut from a tag later if a backport ever needs
+one.
+
+```bash
+npm version minor -m "release: v%s"   # bumps package.json, commits, tags
+git push --follow-tags
+```
+
+Pushing the tag runs [`release.yml`](.github/workflows/release.yml), which
+refuses to publish unless the tagged commit is on `main` and the tag matches the
+version in `package.json` — a tag that disagrees with what npm receives is worse
+than a failed release, because it is only found out later. It then runs the same
+gate a pull request has to clear, publishes with provenance, and opens a GitHub
+Release for the tag.
+
+There is no npm token. npm is configured to trust this repository and this
+workflow **by filename**, and the OIDC token GitHub mints for the job is exchanged
+for publish rights — so nothing has to be stored, rotated, or kept from expiring.
+The catch is the filename: renaming `release.yml` breaks publishing until npm's
+trusted-publisher entry is updated to match.
+
 ## Status
 
 Early. Kotlin extractor only; validated against one production codebase

package/dist/cli.js

@@ -146,6 +146,10 @@ async function serveStdio(getQuery, project) {
   await server.connect(new StdioServerTransport());
 }
 
+// src/model.ts
+var nodeIndex = (g) => new Map(g.nodes.map((n) => [n.id, n]));
+var edgeKey = (e) => `${e.src}\0${e.dst}\0${e.rel}`;
+
 // src/output/tsv.ts
 function toTsv(g) {
   const prefix = commonPrefix(g.nodes.map((n) => n.id));
@@ -583,7 +587,9 @@ function gridLayout(g, maxWidth = 3e3) {
 }
 
 // src/render/select.ts
-function select(g, view, showIdentifiers = false) {
+var NothingToDraw = class extends Error {
+};
+function select(g, view, showIdentifiers = false, changed) {
   const byId = new Map(g.nodes.map((n) => [n.id, n]));
   const real = g.edges.filter((e) => showIdentifiers || !e.identifierOnly);
   const withNeighbours = (seed) => {
@@ -595,6 +601,13 @@ function select(g, view, showIdentifiers = false) {
     return out;
   };
   const changedSet = () => {
+    if (changed) {
+      const seed2 = new Set([...changed].filter((id) => byId.has(id)));
+      if (!seed2.size) {
+        throw new NothingToDraw("nothing this branch touches exists here \u2014 nothing to draw");
+      }
+      return seed2;
+    }
     const seed = new Set(
       g.nodes.filter((n) => n.status === "added" || n.status === "modified").map((n) => n.id)
     );
@@ -613,7 +626,18 @@ function select(g, view, showIdentifiers = false) {
   };
   let keep;
   let label;
-  if (view === "all") {
+  let violatingEdgesOnly = false;
+  if (view === "violations") {
+    keep = /* @__PURE__ */ new Set();
+    for (const e of real) {
+      if (!e.violation) continue;
+      keep.add(e.src);
+      keep.add(e.dst);
+    }
+    if (!keep.size) throw new NothingToDraw("no violations \u2014 nothing to draw");
+    violatingEdgesOnly = true;
+    label = "every boundary violation, and the types they run through";
+  } else if (view === "all") {
     keep = new Set(g.nodes.map((n) => n.id));
     label = "all types";
   } else if (view === "core") {
@@ -632,14 +656,16 @@ function select(g, view, showIdentifiers = false) {
     keep = changedSet();
     const linked = real.filter((e) => keep.has(e.src) && keep.has(e.dst)).length;
     if (linked) {
-      label = "what this branch added and changed";
+      label = changed ? "the types this branch touches, as they stand" : "what this branch added and changed";
     } else {
       keep = dependents(keep);
-      label = "what this branch changed (no new relations \u2014 showing dependents)";
+      label = changed ? "the types this branch touches, and their dependents, as they stand" : "what this branch changed (no new relations \u2014 showing dependents)";
     }
   }
   const nodes = g.nodes.filter((n) => keep.has(n.id));
-  const edges = real.filter((e) => keep.has(e.src) && keep.has(e.dst));
+  const edges = real.filter(
+    (e) => keep.has(e.src) && keep.has(e.dst) && (!violatingEdgesOnly || e.violation)
+  );
   return { graph: { ...g, nodes, edges }, label };
 }
 
@@ -762,16 +788,18 @@ function gridWidthFor(g) {
 }
 function renderSvg(g, opt = {}) {
   const layout = opt.layout ?? "hex";
-  const hueOf = hueMap(g.nodes.map((n) => n.domain));
-  const place = layout === "hex" ? hexLayout(g) : layout === "organic" ? organicLayout(g) : gridLayout(g, gridWidthFor(g));
+  const frame = opt.frame ?? g;
+  const hueOf = hueMap(frame.nodes.map((n) => n.domain));
+  const place = layout === "hex" ? hexLayout(frame) : layout === "organic" ? organicLayout(frame) : gridLayout(frame, gridWidthFor(frame));
   const coords = new Map(place.map((p) => [p.id, p]));
-  const placed = g.nodes.map((n) => {
+  const sit = (n) => {
     const c = coords.get(n.id) ?? { x: 0, y: 0 };
     return { n, x: c.x, y: c.y, ...sizeOf(n) };
-  });
+  };
+  const placed = g.nodes.map(sit);
   const at = new Map(placed.map((p) => [p.n.id, p]));
   const domains = /* @__PURE__ */ new Map();
-  for (const p of placed) {
+  for (const p of frame === g ? placed : frame.nodes.map(sit)) {
     const b = domains.get(p.n.domain);
     const x1 = Math.min(b ? b.x : Number.POSITIVE_INFINITY, p.x - p.w / 2);
     const y1 = Math.min(b ? b.y : Number.POSITIVE_INFINITY, p.y - p.h / 2);
@@ -965,13 +993,15 @@ function legendBlock(g, w, top, hueOf) {
     `<path d="M${x},${y} L${x + 34},${y}" stroke="${VIOLATION}" stroke-width="3.4" fill="none"/>`,
     `<text x="${x + 40}" y="${y + 4}" font-size="11" fill="${VIOLATION}">boundary violation</text>`
   );
-  x += 150;
-  rows.push(
-    `<rect x="${x}" y="${y - 7}" width="14" height="14" rx="3" fill="none" stroke="${ADDED}" stroke-width="3"/>`,
-    `<text x="${x + 20}" y="${y + 4}" font-size="11" fill="${ADDED}">added</text>`,
-    `<rect x="${x + 66}" y="${y - 7}" width="14" height="14" rx="3" fill="none" stroke="${MODIFIED}" stroke-width="2.6" stroke-dasharray="7 4"/>`,
-    `<text x="${x + 86}" y="${y + 4}" font-size="11" fill="${MODIFIED}">modified</text>`
-  );
+  if (g.nodes.some((n) => n.status === "added" || n.status === "modified")) {
+    x += 150;
+    rows.push(
+      `<rect x="${x}" y="${y - 7}" width="14" height="14" rx="3" fill="none" stroke="${ADDED}" stroke-width="3"/>`,
+      `<text x="${x + 20}" y="${y + 4}" font-size="11" fill="${ADDED}">added</text>`,
+      `<rect x="${x + 66}" y="${y - 7}" width="14" height="14" rx="3" fill="none" stroke="${MODIFIED}" stroke-width="2.6" stroke-dasharray="7 4"/>`,
+      `<text x="${x + 86}" y="${y + 4}" font-size="11" fill="${MODIFIED}">modified</text>`
+    );
+  }
   y += 26;
   x = 26;
   rows.push(`<text x="${x}" y="${y + 4}" font-size="11" fill="${DIM}">domain</text>`);
@@ -998,10 +1028,6 @@ function legendBlock(g, w, top, hueOf) {
 import { readdirSync as readdirSync3, statSync as statSync3 } from "fs";
 import { join as join4 } from "path";
 
-// src/model.ts
-var nodeIndex = (g) => new Map(g.nodes.map((n) => [n.id, n]));
-var edgeKey = (e) => `${e.src}\0${e.dst}\0${e.rel}`;
-
 // src/delta.ts
 function diff(base, head) {
   const b = nodeIndex(base);
@@ -1088,6 +1114,13 @@ var MODS = "(?:public |internal |private |protected |open |abstract |sealed |dat
 var DECL = new RegExp(
   `^(?<mods>${MODS})(?<kw>class|interface|object)\\s+(?<name>[A-Za-z_]\\w*)`
 );
+var TOP_MODS = "(?:public |internal |private |expect |actual |external |inline |suspend |operator |infix |tailrec |const |lateinit )*";
+var TYPEALIAS = new RegExp(
+  `^${TOP_MODS}typealias\\s+(\\w+)(?:<[^>]*>)?\\s*=\\s*(.+?)\\s*$`
+);
+var TOP_LEVEL = new RegExp(
+  `^(?:@\\w+(?:\\([^)]*\\))?\\s+)*${TOP_MODS}(?:typealias|fun|va[lr])\\s`
+);
 var FUN_MODS = "(?:override |open |abstract |suspend |operator |private |internal |protected |inline |final )*";
 var SIG = new RegExp(
   `^\\s+(?:@\\w+(?:\\([^)]*\\))?\\s*)*(?<mods>${FUN_MODS})fun\\s+(?<name>\\w+)\\s*\\(`
@@ -1113,45 +1146,97 @@ function structOf(kind) {
   if (kind === "object") return "Object";
   return "Class";
 }
-function stripComments(text) {
+function stripNonCode(text) {
   const out = [];
-  let inBlock = false;
-  let inLine = false;
-  let inStr = false;
-  for (let i = 0; i < text.length; i++) {
+  const n = text.length;
+  const stack = [{ kind: "code", raw: false, depth: 0 }];
+  const blank = (c) => out.push(c === "\n" ? "\n" : " ");
+  let i = 0;
+  while (i < n) {
+    const f = stack[stack.length - 1];
     const c = text[i];
-    if (inLine) {
-      if (c === "\n") {
-        inLine = false;
-        out.push("\n");
-      } else out.push(" ");
-      continue;
-    }
-    if (inBlock) {
-      if (c === "*" && text[i + 1] === "/") {
-        out.push("  ");
+    if (f.kind === "code") {
+      if (c === "/" && text[i + 1] === "/") {
+        while (i < n && text[i] !== "\n") {
+          out.push(" ");
+          i++;
+        }
+        continue;
+      }
+      if (c === "/" && text[i + 1] === "*") {
+        out.push(" ", " ");
+        i += 2;
+        while (i < n && !(text[i] === "*" && text[i + 1] === "/")) blank(text[i++]);
+        if (i < n) {
+          out.push(" ", " ");
+          i += 2;
+        }
+        continue;
+      }
+      if (c === '"') {
+        const raw = text[i + 1] === '"' && text[i + 2] === '"';
+        const q = raw ? 3 : 1;
+        for (let k = 0; k < q; k++) out.push('"');
+        i += q;
+        stack.push({ kind: "str", raw, depth: 0 });
+        continue;
+      }
+      if (c === "'") {
+        out.push("'");
         i++;
-        inBlock = false;
+        while (i < n && text[i] !== "'" && text[i] !== "\n") {
+          if (text[i] === "\\" && i + 1 < n) {
+            out.push(" ");
+            i++;
+          }
+          blank(text[i++]);
+        }
+        if (i < n && text[i] === "'") {
+          out.push("'");
+          i++;
+        }
         continue;
       }
-      out.push(c === "\n" ? "\n" : " ");
+      if (c === "{") f.depth++;
+      else if (c === "}") {
+        if (f.depth === 0 && stack.length > 1) {
+          out.push("}");
+          stack.pop();
+          i++;
+          continue;
+        }
+        f.depth--;
+      }
+      out.push(c);
+      i++;
       continue;
     }
-    if (!inStr && c === "/" && text[i + 1] === "*") {
-      inBlock = true;
-      out.push("  ");
-      i++;
+    if (!f.raw && c === "\\" && i + 1 < n) {
+      out.push(" ", " ");
+      i += 2;
       continue;
     }
-    if (!inStr && c === "/" && text[i + 1] === "/") {
-      inLine = true;
-      out.push("  ");
+    if (!f.raw && c === "\n") {
+      out.push("\n");
+      stack.pop();
       i++;
       continue;
     }
-    if (c === '"') inStr = !inStr;
-    else if (c === "\n") inStr = false;
-    out.push(c);
+    if (c === '"' && (!f.raw || text[i + 1] === '"' && text[i + 2] === '"')) {
+      const q = f.raw ? 3 : 1;
+      for (let k = 0; k < q; k++) out.push('"');
+      i += q;
+      stack.pop();
+      continue;
+    }
+    if (c === "$" && text[i + 1] === "{") {
+      out.push("$", "{");
+      i += 2;
+      stack.push({ kind: "code", raw: false, depth: 0 });
+      continue;
+    }
+    blank(c);
+    i++;
   }
   return out.join("");
 }
@@ -1316,6 +1401,12 @@ function supertypeNames(text, seenColon) {
 }
 
 // src/extract/kotlin.ts
+function bodyEnd(fi, di) {
+  const d = fi.decls[di];
+  let end = di + 1 < fi.decls.length ? fi.decls[di + 1].line : fi.lines.length;
+  for (const s of fi.stops) if (s > d.line && s < end) end = s;
+  return end;
+}
 function walk(dir, out = []) {
   for (const e of readdirSync2(dir)) {
     const p = join2(dir, e);
@@ -1343,10 +1434,12 @@ function extractKotlin(srcRoot, profile, project, ref) {
   for (const abs of files) {
     const rel = relative2(srcRoot, abs);
     if (isExcluded(profile, `/${rel}`)) continue;
-    const lines = stripComments(readFileSync3(abs, "utf8")).split("\n");
+    const lines = stripNonCode(readFileSync3(abs, "utf8")).split("\n");
     let pkg = "";
     const imports = /* @__PURE__ */ new Map();
     const decls = [];
+    const aliases = /* @__PURE__ */ new Map();
+    const stops = [];
     for (let i = 0; i < lines.length; i++) {
       const line = lines[i];
       const pm = PACKAGE.exec(line);
@@ -1367,10 +1460,58 @@ function extractKotlin(srcRoot, profile, project, ref) {
           line: i,
           kind: kindOf(dm.groups.mods ?? "", dm.groups.kw)
         });
+        continue;
       }
+      const am = TYPEALIAS.exec(line);
+      if (am) {
+        aliases.set(am[1], am[2]);
+        stops.push(i);
+        continue;
+      }
+      if (TOP_LEVEL.test(line)) stops.push(i);
     }
     rawPkgs.push(pkg);
-    infos.push({ rel, pkg, imports, decls, lines, layer: layerOf(profile, `/${rel}`) });
+    infos.push({
+      rel,
+      pkg,
+      imports,
+      decls,
+      lines,
+      layer: layerOf(profile, `/${rel}`),
+      aliases,
+      stops
+    });
+  }
+  const aliasByFq = /* @__PURE__ */ new Map();
+  for (const fi of infos) {
+    for (const [name, rhs] of fi.aliases) aliasByFq.set(`${fi.pkg}.${name}`, { rhs, from: fi });
+  }
+  for (const fi of infos) {
+    const reach = /* @__PURE__ */ new Map();
+    for (const [name, rhs] of fi.aliases) reach.set(name, { rhs, from: fi });
+    for (const [simple, fq] of fi.imports) {
+      const a = aliasByFq.get(fq);
+      if (a) reach.set(simple, a);
+    }
+    for (const [fq, a] of aliasByFq) {
+      const dot = fq.lastIndexOf(".");
+      const name = fq.slice(dot + 1);
+      if (fq.slice(0, dot) === fi.pkg && !reach.has(name)) reach.set(name, a);
+    }
+    if (!reach.size) continue;
+    for (const { rhs, from } of reach.values()) {
+      if (from === fi) continue;
+      for (const [name] of rhs.matchAll(TYPENAME)) {
+        const nm = name;
+        if (!fi.imports.has(nm)) fi.imports.set(nm, from.imports.get(nm) ?? `${from.pkg}.${nm}`);
+      }
+    }
+    for (let pass = 0; pass < 2; pass++) {
+      for (const [name, a] of reach) {
+        const re = new RegExp(`\\b${name}\\b`, "g");
+        fi.lines = fi.lines.map((l) => TYPEALIAS.test(l) ? l : l.replace(re, a.rhs));
+      }
+    }
   }
   const base = profile.domain.base || inferBasePackage(rawPkgs);
   const domainOf = (pkg) => {
@@ -1388,7 +1529,7 @@ function extractKotlin(srcRoot, profile, project, ref) {
     const domain = domainOf(fi.pkg);
     for (let di = 0; di < fi.decls.length; di++) {
       const d = fi.decls[di];
-      const end = di + 1 < fi.decls.length ? fi.decls[di + 1].line : fi.lines.length;
+      const end = bodyEnd(fi, di);
       const body = fi.lines.slice(d.line, end);
       const struct = structOf(d.kind);
       const sigs = collectSigs(body);
@@ -1448,7 +1589,7 @@ function extractKotlin(srcRoot, profile, project, ref) {
     for (let di = 0; di < fi.decls.length; di++) {
       const d = fi.decls[di];
       const id = `${fi.pkg}.${d.name}`;
-      const end = di + 1 < fi.decls.length ? fi.decls[di + 1].line : fi.lines.length;
+      const end = bodyEnd(fi, di);
       const body = fi.lines.slice(d.line, end).join("\n");
       for (const sup of parseSupertypes(fi.lines, d.line)) {
         const tgt = visible.get(sup);
@@ -1493,7 +1634,7 @@ function extractKotlin(srcRoot, profile, project, ref) {
     for (let di = 0; di < fi.decls.length; di++) {
       const d = fi.decls[di];
       const id = `${fi.pkg}.${d.name}`;
-      const end = di + 1 < fi.decls.length ? fi.decls[di + 1].line : fi.lines.length;
+      const end = bodyEnd(fi, di);
       const body = fi.lines.slice(d.line, end).join("\n");
       const bind = /* @__PURE__ */ new Map();
       for (const m of body.matchAll(FIELD)) {
@@ -1795,6 +1936,10 @@ var GraphSource = class {
     this.graph();
     return this.last?.delta;
   }
+  /**
+   * The graph as it stands at the base ref. Extracted once and cached — the ref is
+   * immutable, so a base-state render costs nothing a delta has not already paid.
+   */
   base() {
     if (this.baseGraph) return this.baseGraph;
     const { repo, srcRel, profile, project, base } = this.cfg;
@@ -2006,11 +2151,23 @@ check only
                        has violations without fixing them all first.
 
 render only
-  --view <v>           delta | impact | core | all | domain:<name>   [delta]
+  --view <v>           delta | impact | core | all | violations | domain:<name>
+                       [delta]
+                       violations = only the breaches and the types they run
+                       through. A state view: it draws what is wrong now, not
+                       what this branch changed.
+  --at <s>             head | base   [head]
+                       base draws the same types in their pre-branch state, for
+                       the "before" half of a before/after pair. Requires --base.
+                       Delta styling is dropped \u2014 nothing is added or modified in
+                       a picture of the past \u2014 and violations stay in red.
   --layout <l>         organic | grid | hex
-                       [organic for delta\xB7domain, hex for core\xB7all]
+                       [organic for delta\xB7domain\xB7violations, hex for core\xB7all]
   --image <file>       output path; .svg, or .png to rasterize  [graph.svg]
   --identifiers        include identifier-only references (FamilyId\xB7UserId)
+
+  Nothing to draw \u2014 no violations, or a branch that only adds types and so has
+  no before state \u2014 is reported on stdout and exits 0.
 `;
 function main() {
   const { values: v, positionals } = parseArgs({
@@ -2028,6 +2185,7 @@ function main() {
       mcp: { type: "boolean", default: false },
       scope: { type: "string", default: "all" },
       view: { type: "string", default: "delta" },
+      at: { type: "string", default: "head" },
       layout: { type: "string" },
       // no default — chosen to suit the view
       image: { type: "string" },
@@ -2098,26 +2256,58 @@ function main() {
   }
   if (cmd === "render") {
     const out = v.image ?? "graph.svg";
+    if (v.at !== "head" && v.at !== "base") {
+      process.stderr.write(`--at takes head or base, not '${v.at}'
+`);
+      return 1;
+    }
+    const atBase = v.at === "base";
+    if (atBase && !v.base) {
+      process.stderr.write("--at base needs --base <ref> to know which state to draw\n");
+      return 1;
+    }
+    const changed = d ? /* @__PURE__ */ new Set([...d.addedNodes, ...d.modifiedNodes, ...d.removedNodes]) : void 0;
+    const target = atBase ? source.base() : graph;
     let sel;
     try {
-      sel = select(graph, v.view, v.identifiers);
+      sel = select(target, v.view, v.identifiers, atBase ? changed : void 0);
     } catch (e) {
+      if (e instanceof NothingToDraw) {
+        process.stdout.write(`${project} @ ${target.ref}
+  ${e.message}
+`);
+        return 0;
+      }
       process.stderr.write(`${e.message}
 `);
       return 1;
     }
+    let frame;
+    if (v.base && changed) {
+      const half = (gr, ch) => {
+        try {
+          return select(gr, v.view, v.identifiers, ch).graph;
+        } catch {
+          return void 0;
+        }
+      };
+      const head = half(graph);
+      const base = half(source.base(), changed);
+      if (head && base) frame = union(head, base);
+    }
     const layout = v.layout === "hex" || v.layout === "grid" || v.layout === "organic" ? v.layout : v.view === "core" || v.view === "all" ? "hex" : "organic";
     const svg = renderSvg(sel.graph, {
       layout,
       viewLabel: sel.label,
-      showIdentifiers: v.identifiers
+      showIdentifiers: v.identifiers,
+      ...frame ? { frame } : {}
     });
     const dir = dirname2(resolve(out));
     mkdirSync(dir, { recursive: true });
     const svgPath = out.endsWith(".png") ? `${out.slice(0, -4)}.svg` : out;
     writeFileSync(svgPath, svg);
     process.stdout.write(
-      `${project} @ ${graph.ref}
+      `${project} @ ${target.ref}
   view    ${sel.label}
   drew    ${sel.graph.nodes.length} types \xB7 ${sel.graph.edges.length} relations \xB7 ${sel.graph.edges.filter((e) => e.violation).length} violations
   wrote   ${svgPath}  (${Math.round(svg.length / 1024)} KB)
@@ -2127,8 +2317,7 @@ function main() {
       const px = toPng(svg, out);
       process.stdout.write(
         px ? `  wrote   ${out}  (${px})
-` : `  note    PNG skipped \u2014 install @resvg/resvg-js for rasterizing
-`
+` : "  note    PNG skipped \u2014 install @resvg/resvg-js for rasterizing\n"
       );
     }
     return 0;
@@ -2205,6 +2394,19 @@ wrote ${join6(v.out, "graph.json")} \xB7 graph.tsv
   }
   return cmd === "check" && gated.length ? 1 : 0;
 }
+function union(a, b) {
+  const nodes = new Map(a.nodes.map((n) => [n.id, n]));
+  for (const n of b.nodes) if (!nodes.has(n.id)) nodes.set(n.id, n);
+  const edges = new Map(a.edges.map((e) => [edgeKey(e), e]));
+  for (const e of b.edges) if (!edges.has(edgeKey(e))) edges.set(edgeKey(e), e);
+  return {
+    ...a,
+    nodes: [...nodes.values()].sort((x, y) => x.id.localeCompare(y.id)),
+    edges: [...edges.values()].sort(
+      (x, y) => x.src.localeCompare(y.src) || x.dst.localeCompare(y.dst) || x.rel.localeCompare(y.rel)
+    )
+  };
+}
 function toPng(svg, out) {
   try {
     const req = createRequire(import.meta.url);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hexwright",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Design graph for hexagonal-architecture codebases. Renders what a branch changed as one picture a human can confirm at a glance, and gives a coding agent boundary verdicts it can run on itself before asking for review.",
   "keywords": [
     "hexagonal-architecture",
@@ -61,7 +61,7 @@
     "esbuild": "^0.28.1",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.10"
   },
   "optionalDependencies": {
     "@resvg/resvg-js": "^2.6.2"