@arcote.tech/arc-map 0.7.27

package/src/types.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared JSON shape exchanged between the map server (`/api/map`) and the
+ * React Flow front-end. Kept dependency-free so both Node/Bun and the browser
+ * bundle can import it.
+ */
+
+/** Kind of a context element, derived from its runtime metadata. */
+export type ElementKind =
+  | "aggregate"
+  | "command"
+  | "event"
+  | "view"
+  | "static-view"
+  | "listener"
+  | "route"
+  | "page"
+  | "unknown";
+
+/** Kind of a domain edge between two context elements. */
+export type EdgeKind = "emits" | "handles" | "listens" | "queries" | "mutates";
+
+/** A space (bounded context) — the grouping box on the map. */
+export interface MapSpace {
+  /** Stable `__contextId`, or `"ungrouped"` for module-less elements. */
+  id: string;
+  /** Human label: `__contextName` when set, otherwise the id. */
+  name: string;
+}
+
+/** A callable method exposed by an element (aggregate methods, etc.). */
+export interface MapElementMethod {
+  name: string;
+  kind: "mutate" | "query" | "cron" | "event";
+  description?: string;
+  /** Element names this method reads (per-method query dependencies). */
+  queryDeps?: string[];
+  /** Element names this method writes (per-method mutation dependencies). */
+  mutationDeps?: string[];
+}
+
+/** A single context element node. */
+export interface MapElement {
+  /** Element name — unique within the runtime context. */
+  id: string;
+  name: string;
+  kind: ElementKind;
+  /** Space (context) this element belongs to. */
+  spaceId: string;
+  /** Owning `module()` id/name, when the element was attached to a module. */
+  moduleId?: string;
+  moduleName?: string;
+  /** Module scope tag (e.g. `user` / `workspace`), when known. */
+  scope?: string;
+  description?: string;
+  /** Protection token names (from `protectedBy`). */
+  protections?: string[];
+  /** JSON schema of the element's primary data shape, when derivable. */
+  schema?: unknown;
+  /** Command/route params schema. */
+  params?: unknown;
+  /** Command results schema. */
+  results?: unknown;
+  /** Event payload schema. */
+  payload?: unknown;
+  /** Callable methods (mutate/query/cron) declared by the element. */
+  methods?: MapElementMethod[];
+  /** Event names an aggregate declares/emits. */
+  events?: string[];
+  /** HTTP path for route elements. */
+  path?: string;
+  /** Element-level query deps (command / listener / route). */
+  queryDeps?: string[];
+  /** Element-level mutation deps (command / listener / route). */
+  mutationDeps?: string[];
+}
+
+/** A domain edge between two elements (event-flow / data dependency). */
+export interface MapEdge {
+  id: string;
+  /** Source element id. */
+  source: string;
+  /** Target element id. */
+  target: string;
+  kind: EdgeKind;
+  /** True when source and target live in different spaces. */
+  crossContext: boolean;
+}
+
+/** A React component (or hook) that consumes context elements via a scope. */
+export interface MapComponent {
+  /** Stable id — workspace-relative file path. */
+  id: string;
+  /** Workspace-relative source file. */
+  file: string;
+  /** Component/function name, when resolvable. */
+  name?: string;
+  /** Owning workspace package name. */
+  package?: string;
+}
+
+/** An edge from a React component to a context element it uses. */
+export interface MapComponentEdge {
+  id: string;
+  /** Component id (file). */
+  source: string;
+  /** Target element id (element name). */
+  target: string;
+  /** Whether the element is read (`query`) or written (`mutation`). */
+  usage: "query" | "mutation";
+  /** Scope name the component used (e.g. `user` / `workspace`). */
+  scope?: string;
+  /** Methods invoked on the element (e.g. `getAll`, `rename`). */
+  methods: string[];
+  /** 1-based line of the first usage in the source file. */
+  line?: number;
+}
+
+/** Full payload returned by `GET /api/map`. */
+export interface MapJson {
+  spaces: MapSpace[];
+  elements: MapElement[];
+  edges: MapEdge[];
+  components: MapComponent[];
+  componentEdges: MapComponentEdge[];
+  /** ISO timestamp stamped by the server when the payload was built. */
+  generatedAt?: string;
+}
+
+/** The id used for elements that never belonged to any context/module. */
+export const UNGROUPED_SPACE_ID = "ungrouped";
+
+// ---------------------------------------------------------------------------
+// Use cases
+// ---------------------------------------------------------------------------
+
+/** A use-case MDX file discovered under `packages/<pkg>/use-cases/**`. */
+export interface UseCaseEntry {
+  /** Stable unique id — `${package}/${subPath}`. */
+  id: string;
+  /** Owning workspace package name (e.g. `@ndt/auth`). */
+  package: string;
+  /** Path relative to the package's `use-cases/` dir (e.g. `sub/renew.mdx`). */
+  subPath: string;
+  /** Title from frontmatter, falling back to the filename. */
+  title: string;
+  description?: string;
+  /** Optional ordering hint from frontmatter. */
+  order?: number;
+}
+
+/** Response of `GET /api/use-cases`. */
+export interface UseCaseListJson {
+  useCases: UseCaseEntry[];
+}

package/src/use-cases/discover.ts

@@ -0,0 +1,109 @@
+/**
+ * Discover use-case MDX files under `packages/<pkg>/use-cases/**` and read
+ * their frontmatter. Server-side only (Node/Bun fs). The discovered entries
+ * carry a package-relative `subPath` so the front can rebuild the folder tree.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { UseCaseEntry } from "../types";
+
+export interface UseCasePackage {
+  name: string;
+  /** Absolute package directory. */
+  path: string;
+}
+
+export interface DiscoveredUseCase extends UseCaseEntry {
+  /** Absolute file path — server-only, not sent to the client. */
+  absPath: string;
+}
+
+/** Minimal frontmatter parse: leading `---\n...\n---` block of `key: value` lines. */
+export function parseFrontmatter(text: string): {
+  data: Record<string, string>;
+  body: string;
+} {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+  if (!match) return { data: {}, body: text };
+  const data: Record<string, string> = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line);
+    if (!m) continue;
+    let value = m[2].trim();
+    // strip surrounding quotes
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    data[m[1]] = value;
+  }
+  return { data, body: text.slice(match[0].length) };
+}
+
+function walkMdx(dir: string, base: string, out: string[]): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir) as string[];
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    const full = join(dir, name);
+    let s;
+    try {
+      s = statSync(full);
+    } catch {
+      continue;
+    }
+    if (s.isDirectory()) walkMdx(full, base, out);
+    else if (name.endsWith(".mdx")) out.push(full);
+  }
+}
+
+/** Discover all use-case MDX files across the given packages. */
+export function discoverUseCases(packages: UseCasePackage[]): DiscoveredUseCase[] {
+  const result: DiscoveredUseCase[] = [];
+  for (const pkg of packages) {
+    const ucDir = join(pkg.path, "use-cases");
+    if (!existsSync(ucDir)) continue;
+    const files: string[] = [];
+    walkMdx(ucDir, ucDir, files);
+    for (const abs of files) {
+      const subPath = abs.slice(ucDir.length + 1).split("\\").join("/");
+      let title = subPath.replace(/\.mdx$/, "");
+      let description: string | undefined;
+      let order: number | undefined;
+      try {
+        const { data } = parseFrontmatter(readFileSync(abs, "utf-8"));
+        if (data.title) title = data.title;
+        if (data.description) description = data.description;
+        if (data.order !== undefined && data.order !== "") {
+          const n = Number(data.order);
+          if (!Number.isNaN(n)) order = n;
+        }
+      } catch {
+        // unreadable file — keep filename title
+      }
+      result.push({
+        id: `${pkg.name}/${subPath}`,
+        package: pkg.name,
+        subPath,
+        title,
+        description,
+        order,
+        absPath: abs,
+      });
+    }
+  }
+  // Stable sort: package, then order (if any), then subPath.
+  result.sort(
+    (a, b) =>
+      a.package.localeCompare(b.package) ||
+      (a.order ?? 1e9) - (b.order ?? 1e9) ||
+      a.subPath.localeCompare(b.subPath),
+  );
+  return result;
+}

package/tests/discover.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { discoverUseCases, parseFrontmatter } from "../src/use-cases/discover";
+
+const PKG_A = join(import.meta.dir, "fixtures/uc/pkgA");
+
+describe("parseFrontmatter", () => {
+  test("extracts key: value block, strips quotes, returns body", () => {
+    const { data, body } = parseFrontmatter(`---\ntitle: "Hi"\norder: 3\n---\nbody here`);
+    expect(data.title).toBe("Hi");
+    expect(data.order).toBe("3");
+    expect(body.trim()).toBe("body here");
+  });
+  test("no frontmatter → empty data, full body", () => {
+    const { data, body } = parseFrontmatter("# just markdown");
+    expect(data).toEqual({});
+    expect(body).toBe("# just markdown");
+  });
+});
+
+describe("discoverUseCases", () => {
+  test("walks use-cases/**, reads frontmatter, builds ids + subPaths", () => {
+    const found = discoverUseCases([{ name: "@x/pkgA", path: PKG_A }]);
+    const byId = new Map(found.map((u) => [u.id, u]));
+
+    const foo = byId.get("@x/pkgA/sub/foo.mdx");
+    expect(foo).toBeDefined();
+    expect(foo!.title).toBe("Foo use case");
+    expect(foo!.order).toBe(2);
+    expect(foo!.package).toBe("@x/pkgA");
+    expect(foo!.subPath).toBe("sub/foo.mdx");
+
+    const bar = byId.get("@x/pkgA/bar.mdx");
+    expect(bar).toBeDefined();
+    // no frontmatter → title falls back to filename-without-ext
+    expect(bar!.title).toBe("bar");
+  });
+
+  test("package without use-cases/ dir yields nothing", () => {
+    expect(discoverUseCases([{ name: "empty", path: join(import.meta.dir, "fixtures") }])).toEqual([]);
+  });
+});

package/tests/fixtures/pkg/detail-page.tsx

@@ -0,0 +1,11 @@
+import { usePlatformScope } from "@arcote.tech/platform";
+import { context } from "./ctx";
+export default function DetailPage() {
+  const s = usePlatformScope(context, "user");
+  const [me] = s.useQuery().userAccounts.getMe();
+  const commands = s.useMutation();
+  async function onSave() {
+    await commands.userAccounts.update({ id: me?.id });
+  }
+  return null;
+}

package/tests/fixtures/pkg/direct.tsx

@@ -0,0 +1,7 @@
+import { usePlatformScope } from "@arcote.tech/platform";
+import { context } from "./ctx";
+export function Direct() {
+  const s = usePlatformScope(context, "user");
+  const [me] = s.useQuery().userAccounts.getMe();
+  return null;
+}

package/tests/fixtures/pkg/list-page.tsx

@@ -0,0 +1,11 @@
+import { useContentScope } from "./scope";
+export function ListPage() {
+  const scope = useContentScope();
+  const commands = scope.useMutation();
+  const [topics] = scope.useQuery().contentTopic.getAll();
+  const [contents] = scope.useQuery().content.getAll();
+  async function onRename(id: string) {
+    await commands.contentTopic.rename({ id });
+  }
+  return null;
+}

package/tests/fixtures/pkg/routes.ts

@@ -0,0 +1,6 @@
+import { lazy } from "react";
+import { page } from "@arcote.tech/platform";
+
+const DetailPage = lazy(() => import("./detail-page"));
+
+export const detail = page("/detail/", DetailPage);

package/tests/fixtures/pkg/scope.ts

@@ -0,0 +1,4 @@
+import { usePlatformScope } from "@arcote.tech/platform";
+import { contentContext } from "./context";
+export const useContentScope = () => usePlatformScope(contentContext, "workspace");
+export const useUserContentScope = () => usePlatformScope(contentContext, "user");

package/tests/fixtures/uc/pkgA/use-cases/bar.mdx

@@ -0,0 +1,3 @@
+# Bar bez frontmatter
+
+<Arc aggregate="acc" mutationMethod="check">sprawdź</Arc>

package/tests/fixtures/uc/pkgA/use-cases/sub/foo.mdx

@@ -0,0 +1,9 @@
+---
+title: Foo use case
+description: przykład
+order: 2
+---
+
+# Foo
+
+Krok pierwszy: <Arc command="signIn">logowanie</Arc>.

package/tests/mapper.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from "bun:test";
+import {
+  aggregate,
+  command,
+  context,
+  event,
+  id,
+  listener,
+  string,
+} from "@arcote.tech/arc";
+import { buildMapJson, type ModuleInfo } from "../src/mapper";
+import type { MapComponentEdge } from "../src/types";
+
+function fixture() {
+  const taskId = id("task");
+  const Notify = event("notifyCreated", { taskId: string() });
+  const Task = aggregate("task", taskId, { title: string() })
+    .publicEvent("taskCreated", { taskId, title: string() }, async () => {})
+    .mutateMethod("create", (fn: any) => fn.withParams({ title: string() }).handle(async () => {}));
+  const createTask = command("createTask")
+    .mutate([Notify])
+    .withParams({ title: string() })
+    .handle(async () => ({}));
+  const onCreated = listener("onCreated").listenTo([Notify]).handle(async () => {});
+
+  const tasks = context([Task, createTask], { name: "tasks" });
+  const notifications = context([Notify, onCreated], { name: "notifications" });
+  // Runtime view is a single flat merge of both spaces.
+  return context([...tasks.elements, ...notifications.elements]);
+}
+
+describe("buildMapJson", () => {
+  test("groups elements into named spaces from __contextId", () => {
+    const map = buildMapJson({ context: fixture() });
+    const spaceNames = map.spaces.map((s) => s.name).sort();
+    expect(spaceNames).toEqual(["notifications", "tasks"]);
+
+    const byId = new Map(map.elements.map((e) => [e.id, e]));
+    expect(byId.get("task")!.spaceId).toBe(byId.get("createTask")!.spaceId);
+    expect(byId.get("notifyCreated")!.spaceId).not.toBe(byId.get("task")!.spaceId);
+  });
+
+  test("detects element kinds and aggregate metadata", () => {
+    const map = buildMapJson({ context: fixture() });
+    const byId = new Map(map.elements.map((e) => [e.id, e]));
+    expect(byId.get("task")!.kind).toBe("aggregate");
+    expect(byId.get("createTask")!.kind).toBe("command");
+    expect(byId.get("notifyCreated")!.kind).toBe("event");
+    expect(byId.get("onCreated")!.kind).toBe("listener");
+    expect(byId.get("task")!.events).toContain("taskCreated");
+    expect(byId.get("task")!.methods?.map((m) => m.name)).toContain("create");
+  });
+
+  test("synthesizes a node for inline aggregate events", () => {
+    const map = buildMapJson({ context: fixture() });
+    const synth = map.elements.find((e) => e.id === "taskCreated");
+    expect(synth).toBeDefined();
+    expect(synth!.kind).toBe("event");
+  });
+
+  test("builds typed edges and flags cross-context", () => {
+    const map = buildMapJson({ context: fixture() });
+    const e = (s: string, t: string, k: string) =>
+      map.edges.find((x) => x.source === s && x.target === t && x.kind === k);
+
+    expect(e("task", "taskCreated", "emits")).toBeDefined();
+    expect(e("onCreated", "notifyCreated", "listens")).toBeDefined();
+
+    // createTask (tasks) -mutates-> notifyCreated (notifications) => cross-context.
+    const cross = e("createTask", "notifyCreated", "mutates");
+    expect(cross).toBeDefined();
+    expect(cross!.crossContext).toBe(true);
+
+    // emits within the same space is not cross-context.
+    expect(e("task", "taskCreated", "emits")!.crossContext).toBe(false);
+  });
+
+  test("tags elements with module info", () => {
+    const moduleByElement = new Map<string, ModuleInfo>([
+      ["task", { moduleId: "m1", moduleName: "TasksModule", scope: "workspace" }],
+    ]);
+    const map = buildMapJson({ context: fixture(), moduleByElement });
+    const task = map.elements.find((e) => e.id === "task")!;
+    expect(task.moduleName).toBe("TasksModule");
+    expect(task.scope).toBe("workspace");
+  });
+
+  test("resolves namespaced aggregate event in listener listens edge", () => {
+    const oid = id("o");
+    const Order = aggregate("order", oid, { total: string() })
+      .publicEvent("orderPaid", { orderId: oid }, async () => {});
+    // Listener listens via getEvent → name may be namespaced (order.orderPaid),
+    // but the event node is registered under the short name "orderPaid".
+    const onPaid = listener("onPaid")
+      .listenTo([(Order as any).getEvent("orderPaid")])
+      .handle(async () => {});
+    const ctx = context([Order, onPaid]);
+    const map = buildMapJson({ context: ctx });
+    const listens = map.edges.find((e) => e.kind === "listens" && e.source === "onPaid");
+    expect(listens).toBeDefined();
+    expect(listens!.target).toBe("orderPaid"); // resolved to the short node id
+  });
+
+  test("keeps only component edges resolving to a known element", () => {
+    const componentEdges: MapComponentEdge[] = [
+      { id: "a", source: "pkg/x.tsx", target: "task", usage: "query", methods: ["getAll"], scope: "workspace" },
+      { id: "b", source: "pkg/x.tsx", target: "doesNotExist", usage: "mutation", methods: [] },
+    ];
+    const components = [{ id: "pkg/x.tsx", file: "pkg/x.tsx" }];
+    const map = buildMapJson({ context: fixture(), componentEdges, components });
+    expect(map.componentEdges).toHaveLength(1);
+    expect(map.componentEdges[0]!.target).toBe("task");
+    expect(map.components).toHaveLength(1);
+  });
+});

package/tests/refs.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { resolveRef, normalizePagePath } from "../src/refs";
+
+describe("normalizePagePath", () => {
+  test("strips query, hash and trailing slash; keeps root", () => {
+    expect(normalizePagePath("/checkout/success?orderId=1")).toBe("/checkout/success");
+    expect(normalizePagePath("/credits#top")).toBe("/credits");
+    expect(normalizePagePath("/checkout/")).toBe("/checkout");
+    expect(normalizePagePath("/")).toBe("/");
+  });
+});
+
+describe("resolveRef", () => {
+  test("page → identified by normalized path (not module key)", () => {
+    expect(resolveRef({ page: "/checkout/success?orderId=1" })).toMatchObject({
+      nodeId: "/checkout/success",
+      kind: "page",
+      key: "page:/checkout/success",
+    });
+  });
+
+
+  test("command / view / listener / route / event", () => {
+    expect(resolveRef({ command: "signIn" })).toMatchObject({ nodeId: "signIn", kind: "command", key: "command:signIn" });
+    expect(resolveRef({ view: "orders" })).toMatchObject({ nodeId: "orders", kind: "view" });
+    expect(resolveRef({ listener: "onX" })).toMatchObject({ nodeId: "onX", kind: "listener" });
+    expect(resolveRef({ route: "webhook" })).toMatchObject({ nodeId: "webhook", kind: "route" });
+    expect(resolveRef({ event: "taskCreated" })).toMatchObject({ nodeId: "taskCreated", kind: "event" });
+  });
+
+  test("aggregate alone → aggregate node", () => {
+    expect(resolveRef({ aggregate: "tasks" })).toMatchObject({ nodeId: "tasks", kind: "aggregate", key: "aggregate:tasks" });
+  });
+
+  test("aggregate + mutationMethod → aggregate node + method", () => {
+    const r = resolveRef({ aggregate: "userAccounts", mutationMethod: "checkEmail" });
+    expect(r).toMatchObject({
+      nodeId: "userAccounts",
+      kind: "aggregate",
+      method: { name: "checkEmail", kind: "mutation" },
+      key: "aggregate:userAccounts#mutate:checkEmail",
+    });
+  });
+
+  test("aggregate + queryMethod → query method", () => {
+    expect(resolveRef({ aggregate: "tasks", queryMethod: "getAll" })?.method).toEqual({ name: "getAll", kind: "query" });
+  });
+
+  test("aggregate + event → the event node", () => {
+    expect(resolveRef({ aggregate: "tasks", event: "taskCreated" })).toMatchObject({ nodeId: "taskCreated", kind: "event" });
+  });
+
+  test("no recognised prop → null", () => {
+    expect(resolveRef({})).toBeNull();
+  });
+});

package/tests/scan.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import { scanScopeUsages } from "../src/scan";
+
+const FIXTURES = `${import.meta.dir}/fixtures`;
+
+function scan() {
+  return scanScopeUsages({
+    globs: [`${FIXTURES}/**/*.{ts,tsx}`],
+    workspaceRoot: FIXTURES,
+  });
+}
+
+describe("scanScopeUsages", () => {
+  test("resolves wrapper-hook scope (inline + via-variable)", () => {
+    const { componentEdges } = scan();
+    const find = (file: string, target: string, usage: string) =>
+      componentEdges.find((e) => e.source === file && e.target === target && e.usage === usage);
+
+    // Inline: scope.useQuery().contentTopic.getAll() with useContentScope -> workspace
+    const topicQuery = find("pkg/list-page.tsx", "contentTopic", "query");
+    expect(topicQuery).toBeDefined();
+    expect(topicQuery!.scope).toBe("workspace");
+    expect(topicQuery!.methods).toContain("getAll");
+
+    // Via variable: const commands = scope.useMutation(); commands.contentTopic.rename()
+    const topicMutation = find("pkg/list-page.tsx", "contentTopic", "mutation");
+    expect(topicMutation).toBeDefined();
+    expect(topicMutation!.scope).toBe("workspace");
+    expect(topicMutation!.methods).toContain("rename");
+  });
+
+  test("resolves direct usePlatformScope(ctx, scope) call", () => {
+    const { componentEdges } = scan();
+    const me = componentEdges.find(
+      (e) => e.source === "pkg/direct.tsx" && e.target === "userAccounts",
+    );
+    expect(me).toBeDefined();
+    expect(me!.usage).toBe("query");
+    expect(me!.scope).toBe("user");
+    expect(me!.methods).toContain("getMe");
+  });
+
+  test("emits one component per scanned file with usages", () => {
+    const { components } = scan();
+    const ids = components.map((c) => c.id).sort();
+    expect(ids).toContain("pkg/list-page.tsx");
+    expect(ids).toContain("pkg/direct.tsx");
+  });
+
+  test("page() re-keys a page component's edges onto the route path", () => {
+    const { componentEdges, components } = scan();
+    // routes.ts: page("/detail/", DetailPage), DetailPage = lazy(import("./detail-page")).
+    // detail-page.tsx edges get re-keyed from the file id onto the normalized path.
+    const q = componentEdges.find((e) => e.source === "/detail" && e.target === "userAccounts" && e.usage === "query");
+    const m = componentEdges.find((e) => e.source === "/detail" && e.target === "userAccounts" && e.usage === "mutation");
+    expect(q).toBeDefined();
+    expect(m).toBeDefined();
+    // no edge keeps the original file id, and the orphan file node is dropped.
+    expect(componentEdges.some((e) => e.source === "pkg/detail-page.tsx")).toBe(false);
+    expect(components.some((c) => c.id === "pkg/detail-page.tsx")).toBe(false);
+  });
+
+  test("aggregates methods per (element, usage, scope) edge", () => {
+    const { componentEdges } = scan();
+    const contentQuery = componentEdges.find(
+      (e) => e.source === "pkg/list-page.tsx" && e.target === "content" && e.usage === "query",
+    );
+    expect(contentQuery).toBeDefined();
+    expect(contentQuery!.methods).toEqual(["getAll"]);
+  });
+});

package/tests/subgraph.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { buildSubgraph, neighborsOf } from "../src/app/subgraph";
+import type { MapEdge, MapJson } from "../src/types";
+
+function el(id: string, kind: any = "unknown") {
+  return { id, name: id, kind, spaceId: "s" };
+}
+function edge(source: string, target: string, kind: MapEdge["kind"] = "mutates"): MapEdge {
+  return { id: `${source}->${target}`, source, target, kind, crossContext: false };
+}
+
+// Graph:  A(command) --mutates--> E(event)  <--listens-- L(listener) --mutates--> E2(event) <--handles-- V(view)
+//         X is unrelated.
+const map: MapJson = {
+  spaces: [{ id: "s", name: "s" }],
+  elements: [el("A", "command"), el("E", "event"), el("L", "listener"), el("E2", "event"), el("V", "view"), el("X")],
+  edges: [edge("A", "E"), edge("L", "E", "listens"), edge("L", "E2"), edge("V", "E2", "handles")],
+  components: [],
+  componentEdges: [],
+};
+
+describe("buildSubgraph", () => {
+  test("referenced + 1-hop + connecting path (undirected through plumbing)", () => {
+    const sub = buildSubgraph({ map, referenced: ["A", "V"] });
+    // A..V connects via A-E-L-E2-V (undirected) — all included; X excluded.
+    expect([...sub.nodeIds].sort()).toEqual(["A", "E", "E2", "L", "V"]);
+    expect(sub.referencedIds).toEqual(["A", "V"]);
+    expect(sub.edges.length).toBe(4);
+  });
+
+  test("path cap drops too-long connectors", () => {
+    const sub = buildSubgraph({ map, referenced: ["A", "V"], maxPath: 2 });
+    // shortest A-V path is 4 hops > 2 → only referenced + their 1-hop neighbours.
+    expect(sub.nodeIds.has("A")).toBe(true);
+    expect(sub.nodeIds.has("E")).toBe(true); // 1-hop of A
+    expect(sub.nodeIds.has("E2")).toBe(true); // 1-hop of V
+    expect(sub.nodeIds.has("L")).toBe(false); // only reachable via the long path
+  });
+
+  test("unresolved references are filtered", () => {
+    const sub = buildSubgraph({ map, referenced: ["A", "ghost"] });
+    expect(sub.referencedIds).toEqual(["A"]);
+  });
+
+  test("expand adds a node and its neighbours", () => {
+    const sub = buildSubgraph({ map, referenced: ["A"], expanded: ["V"] });
+    expect(sub.nodeIds.has("V")).toBe(true);
+    expect(sub.nodeIds.has("E2")).toBe(true);
+  });
+
+  test("neighborsOf is undirected", () => {
+    expect(neighborsOf(map, "E").sort()).toEqual(["A", "L"]);
+  });
+});