@arcote.tech/arc-map 0.7.28 → 0.7.29

package/src/app/usecase-model.ts

@@ -1,346 +0,0 @@
-/**
- * Use-case data-flow model. Turns the ordered `<Arc>` occurrences + the full
- * map into a per-step model:
- *
- *  - steps: one node PER occurrence (no dedup); existing or missing.
- *  - connectors: elements on the shortest undirected path between two existing
- *    steps (the plumbing the author didn't narrate).
- *  - per step: related elements that are NOT already visible, grouped by relation
- *    kind, ready to be collapsed into badges / expanded into columns.
- *
- * Pure and dependency-free (testable in bun).
- */
-
-import type { MapEdge, MapElement, MapJson } from "../types";
-import type { ResolvedRef } from "../refs";
-import type { PathSeg } from "./contexts";
-
-export const DEFAULT_MAX_PATH = 5;
-
-/** Relation kinds surfaced as badges / expandable columns. */
-export type RelKind =
-  | "queries" // forward: this step reads X                  → left column
-  | "mutates" // forward: this step writes X                 → right column
-  | "mutatedBy" // reverse: X is written by others (producers) → left column (arrows in)
-  | "queriedBy" // reverse: X is read by others               → left column
-  | "handledBy" // reverse: X (event) handled/observed by others → left column
-  | "usedByUI"; // reverse: React components/pages that use X (ts-morph) → left column
-
-/**
- * Which side a relation expands to. Forward outputs (`mutates`) go right; every
- * INCOMING relationship — what feeds the step (`queries`) and everyone who acts
- * on / reads / observes / renders it (`mutatedBy`, `queriedBy`, `handledBy`,
- * `usedByUI`) — goes left. Edge arrows keep their semantic direction regardless.
- */
-export const REL_SIDE: Record<RelKind, "left" | "right"> = {
-  queries: "left",
-  queriedBy: "left",
-  mutatedBy: "left",
-  handledBy: "left",
-  usedByUI: "left",
-  mutates: "right",
-};
-
-export interface OccurrenceRef {
-  occId: string;
-  ref: ResolvedRef | null;
-  label: string;
-  /** Structural path (parallel/branch/lane/step) from the MDX. */
-  path?: PathSeg[];
-}
-
-export interface StepNode {
-  occId: string;
-  seq: number;
-  ref: ResolvedRef | null;
-  exists: boolean;
-  element?: MapElement;
-  label: string;
-  /** Method name actually used (aggregate mutationMethod/queryMethod), if any. */
-  method?: { name: string; kind: "mutation" | "query" };
-  /** Related elements NOT already visible, grouped by relation kind. */
-  badges: Partial<Record<RelKind, string[]>>;
-  /** Horizontal position (time / dependency depth), 0-based. */
-  depth: number;
-  /** Vertical track (parallel / branch lane), 0-based. */
-  lane: number;
-  /** True for branch (alternative / XOR) lanes. */
-  alt?: boolean;
-  /** Label of the enclosing `<Step>` phase, if any. */
-  stepTitle?: string;
-  /** Label of the enclosing `<Lane>`, if any. */
-  laneTitle?: string;
-  /** Id of the enclosing parallel/branch block, if any. */
-  blockId?: string;
-}
-
-export interface ConnectorNode {
-  id: string;
-  element: MapElement;
-  /** seq of the two narrated steps this connector sits between, flow-ordered
-   *  [upstream → downstream]. */
-  between: [number, number];
-  /** 1-based position among the intermediates on the directed path. */
-  order: number;
-  /** Total intermediates on that path (for spreading between the two steps). */
-  count: number;
-}
-
-export interface UseCaseModel {
-  steps: StepNode[];
-  connectors: ConnectorNode[];
-  /** Visible element ids: existing step elements + connectors. */
-  visible: Set<string>;
-  /** element id -> seq of its first existing step occurrence. */
-  firstSeqByElement: Map<string, number>;
-  /** Pseudo-elements for React components/pages (UI layer) by id. */
-  uiById: Map<string, MapElement>;
-}
-
-// ---------------------------------------------------------------------------
-// Graph helpers (directed flow adjacency + BFS shortest path)
-// ---------------------------------------------------------------------------
-
-/**
- * Directed left→right flow adjacency: each edge points producer→consumer, so a
- * BFS path follows the actual data flow.
- *  - mutates/emits: source produces target            → source → target
- *  - queries/listens/handles: source consumes target  → target → source
- * Mirrors the layout's INPUT/OUTPUT edge orientation, so a connector found here
- * lies on the same flow the diagram draws — i.e. genuinely BETWEEN the two
- * narrated steps, never a shared upstream/downstream they both happen to touch.
- */
-function flowAdjacency(edges: MapEdge[]): Map<string, Set<string>> {
-  const adj = new Map<string, Set<string>>();
-  const link = (a: string, b: string) => {
-    let s = adj.get(a);
-    if (!s) adj.set(a, (s = new Set()));
-    s.add(b);
-  };
-  for (const e of edges) {
-    if (e.kind === "mutates" || e.kind === "emits") link(e.source, e.target);
-    else link(e.target, e.source);
-  }
-  return adj;
-}
-
-function shortestPath(
-  adj: Map<string, Set<string>>,
-  start: string,
-  goal: string,
-  maxLen: number,
-): string[] | null {
-  if (start === goal) return [start];
-  const prev = new Map<string, string>();
-  const depth = new Map<string, number>([[start, 0]]);
-  const queue = [start];
-  while (queue.length) {
-    const cur = queue.shift()!;
-    const d = depth.get(cur)!;
-    if (d >= maxLen) continue;
-    for (const nb of adj.get(cur) ?? []) {
-      if (depth.has(nb)) continue;
-      depth.set(nb, d + 1);
-      prev.set(nb, cur);
-      if (nb === goal) {
-        const path = [goal];
-        let p = cur;
-        while (p !== start) {
-          path.push(p);
-          p = prev.get(p)!;
-        }
-        path.push(start);
-        return path.reverse();
-      }
-      queue.push(nb);
-    }
-  }
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Reverse relation index
-// ---------------------------------------------------------------------------
-
-function reverseSources(edges: MapEdge[], target: string, kinds: MapEdge["kind"][]): string[] {
-  const out = new Set<string>();
-  for (const e of edges) {
-    if (e.target === target && kinds.includes(e.kind)) out.add(e.source);
-  }
-  return [...out];
-}
-
-function forwardDeps(step: StepNode): { queries: string[]; mutates: string[] } {
-  const el = step.element;
-  if (!el) return { queries: [], mutates: [] };
-  if (step.method) {
-    const m = el.methods?.find((x) => x.name === step.method!.name);
-    return { queries: m?.queryDeps ?? [], mutates: m?.mutationDeps ?? [] };
-  }
-  return { queries: el.queryDeps ?? [], mutates: el.mutationDeps ?? [] };
-}
-
-// ---------------------------------------------------------------------------
-// Public builder
-// ---------------------------------------------------------------------------
-
-export interface BuildModelInput {
-  map: MapJson;
-  occurrences: OccurrenceRef[];
-  maxPath?: number;
-}
-
-/**
- * Assign depth (time, x) and lane (parallel/branch track, y) from the structural
- * paths. Plain steps flow as a sequence; a `<Parallel>`/`<Branch>` block places
- * its members at the same base depth on separate lanes (sequences within a lane
- * extend the depth). The whole block occupies one slot of the outer sequence.
- */
-function assignDepthLane(steps: StepNode[], occurrences: OccurrenceRef[]): void {
-  let depthCursor = 0;
-  let block: { id: string; base: number; maxLocal: number; laneDepth: Map<number, number> } | null = null;
-  const finalize = () => {
-    if (block) {
-      depthCursor = block.base + block.maxLocal + 1;
-      block = null;
-    }
-  };
-  steps.forEach((step, i) => {
-    const path = occurrences[i].path ?? [];
-    const P = path.find((s) => s.type === "parallel" || s.type === "branch");
-    if (!P) {
-      finalize();
-      step.depth = depthCursor;
-      step.lane = 0;
-      depthCursor += 1;
-      return;
-    }
-    if (!block || block.id !== P.id) {
-      finalize();
-      block = { id: P.id, base: depthCursor, maxLocal: 0, laneDepth: new Map() };
-    }
-    const lane = P.laneIndex ?? 0;
-    const local = block.laneDepth.get(lane) ?? 0;
-    step.depth = block.base + local;
-    step.lane = lane;
-    step.alt = P.type === "branch";
-    step.blockId = P.id;
-    block.laneDepth.set(lane, local + 1);
-    block.maxLocal = Math.max(block.maxLocal, local);
-  });
-  finalize();
-}
-
-export function buildUseCaseModel(input: BuildModelInput): UseCaseModel {
-  const { map, occurrences, maxPath = DEFAULT_MAX_PATH } = input;
-  const elementById = new Map(map.elements.map((e) => [e.id, e]));
-
-  // Pseudo-elements for React components (ts-morph UI layer). Referenced via
-  // `<Arc component>` and surfaced as the `usedByUI` badge.
-  const uiById = new Map<string, MapElement>();
-  for (const c of map.components) {
-    uiById.set(c.id, { id: c.id, name: c.name ?? c.file, kind: "page", spaceId: "ui" });
-  }
-  const resolve = (id: string) => elementById.get(id) ?? uiById.get(id);
-
-  // 1) Steps — one per occurrence.
-  const steps: StepNode[] = occurrences.map((o, i) => {
-    const exists = !!o.ref && !!resolve(o.ref.nodeId);
-    const path = o.path ?? [];
-    return {
-      occId: o.occId,
-      seq: i + 1,
-      ref: o.ref,
-      exists,
-      element: exists ? resolve(o.ref!.nodeId) : undefined,
-      label: o.label,
-      method: o.ref?.method,
-      badges: {},
-      depth: 0,
-      lane: 0,
-      stepTitle: path.find((s) => s.type === "step")?.title,
-      laneTitle: path.find((s) => s.type === "lane")?.title,
-    };
-  });
-
-  assignDepthLane(steps, occurrences);
-
-  // First occurrence seq per existing element id.
-  const firstSeqByElement = new Map<string, number>();
-  for (const s of steps) {
-    if (s.exists && !firstSeqByElement.has(s.element!.id)) {
-      firstSeqByElement.set(s.element!.id, s.seq);
-    }
-  }
-  const stepElementIds = [...firstSeqByElement.keys()];
-
-  // 2) Connectors — elements on a DIRECTED flow path between two narrated steps.
-  // Following flow direction (not undirected) guarantees the connector sits
-  // BETWEEN the two steps left→right, never a node that's upstream of both.
-  const flowAdj = flowAdjacency(map.edges);
-  const connectorMap = new Map<string, ConnectorNode>();
-  for (let i = 0; i < stepElementIds.length; i++) {
-    for (let j = i + 1; j < stepElementIds.length; j++) {
-      const a = stepElementIds[i];
-      const b = stepElementIds[j];
-      // Try both flow orientations; keep the first directed path found.
-      let path = shortestPath(flowAdj, a, b, maxPath);
-      let from = a;
-      let to = b;
-      if (!path) {
-        path = shortestPath(flowAdj, b, a, maxPath);
-        from = b;
-        to = a;
-      }
-      if (!path) continue;
-      // Intermediates only: drop the endpoints and any other narrated step that
-      // happens to fall on the path (those render as steps, not connectors).
-      const intermediates = path.filter((id) => !firstSeqByElement.has(id));
-      const between: [number, number] = [
-        firstSeqByElement.get(from)!,
-        firstSeqByElement.get(to)!,
-      ];
-      intermediates.forEach((id, k) => {
-        const el = elementById.get(id);
-        if (!el || connectorMap.has(id)) return;
-        connectorMap.set(id, {
-          id,
-          element: el,
-          between,
-          order: k + 1,
-          count: intermediates.length,
-        });
-      });
-    }
-  }
-  const connectors = [...connectorMap.values()];
-
-  // 3) Visible set.
-  const visible = new Set<string>([...stepElementIds, ...connectorMap.keys()]);
-
-  // 4) Per-step badges — related elements NOT visible, grouped by relation kind.
-  for (const s of steps) {
-    if (!s.exists) continue;
-    const id = s.element!.id;
-    const fwd = forwardDeps(s);
-    const usedByUI = map.componentEdges.filter((e) => e.target === id).map((e) => e.source);
-    const groups: Partial<Record<RelKind, string[]>> = {
-      queries: fwd.queries,
-      mutates: fwd.mutates,
-      mutatedBy: reverseSources(map.edges, id, ["mutates", "emits"]),
-      queriedBy: reverseSources(map.edges, id, ["queries"]),
-      handledBy: reverseSources(map.edges, id, ["handles", "listens"]),
-      usedByUI,
-    };
-    const badges: Partial<Record<RelKind, string[]>> = {};
-    for (const [kind, list] of Object.entries(groups) as [RelKind, string[]][]) {
-      // UI badge targets live in uiById; the rest are context elements.
-      const known = kind === "usedByUI" ? uiById : elementById;
-      const filtered = [...new Set(list)].filter((t) => t !== id && !visible.has(t) && known.has(t));
-      if (filtered.length) badges[kind] = filtered;
-    }
-    s.badges = badges;
-  }
-
-  return { steps, connectors, visible, firstSeqByElement, uiById };
-}

package/src/refs.ts

@@ -1,121 +0,0 @@
-/**
- * Resolution of `<Arc>` use-case references to map nodes.
- *
- * Dependency-free (no React) so it is unit-testable and importable by both the
- * `<Arc>` component and the subgraph builder. The `<Arc>` props are a typed
- * union per element kind; `resolveRef` maps them to a target node id (an
- * element name present in `MapJson.elements`) plus an optional aggregate method.
- */
-
-/** Props accepted by the `<Arc>` component (one kind per element). */
-export interface ArcRefProps {
-  command?: string;
-  event?: string;
-  view?: string;
-  staticView?: string;
-  listener?: string;
-  route?: string;
-  aggregate?: string;
-  /** With `aggregate`: target a mutation method. */
-  mutationMethod?: string;
-  /** With `aggregate`: target a query method. */
-  queryMethod?: string;
-  /** A registered page (arc `page()`), referenced by its route path. */
-  page?: string;
-  /** A React component / UI file (matched against the ts-morph scan). */
-  component?: string;
-}
-
-export type ArcRefKind =
-  | "command"
-  | "event"
-  | "view"
-  | "static-view"
-  | "listener"
-  | "route"
-  | "aggregate"
-  | "page";
-
-export interface ResolvedRef {
-  /** Target node id — an element name in MapJson. */
-  nodeId: string;
-  kind: ArcRefKind;
-  /** Aggregate method, when the ref targets one. */
-  method?: { name: string; kind: "mutation" | "query" };
-  /** Canonical key for dedup / chip<->node linking. */
-  key: string;
-}
-
-/**
- * Canonical page identity = its route PATH, stripped of query/hash and any
- * trailing slash (root "/" kept). Pages are identified by path, never by the
- * module's page key — the key (`{ checkout: page("/checkout", …) }`) is a
- * module-local name absent from the fragment, while the path is the stable
- * identity `buildPageNodes` registers nodes under. Normalizing here AND in
- * buildPageNodes guarantees `<Arc page="/checkout">` and a node registered as
- * `/checkout` collapse to the same node regardless of incidental `?query`.
- */
-export function normalizePagePath(path: string): string {
-  let p = path.split("?")[0].split("#")[0].trim();
-  if (p.length > 1 && p.endsWith("/")) p = p.slice(0, -1);
-  return p;
-}
-
-/**
- * Map `<Arc>` props to a resolved reference, or null if no recognised kind is
- * present. Resolution is purely structural — whether the node actually exists
- * is validated separately against MapJson (front-side red-border).
- */
-export function resolveRef(props: ArcRefProps): ResolvedRef | null {
-  if (props.command) {
-    return { nodeId: props.command, kind: "command", key: `command:${props.command}` };
-  }
-  if (props.view) {
-    return { nodeId: props.view, kind: "view", key: `view:${props.view}` };
-  }
-  if (props.staticView) {
-    return { nodeId: props.staticView, kind: "static-view", key: `static-view:${props.staticView}` };
-  }
-  if (props.listener) {
-    return { nodeId: props.listener, kind: "listener", key: `listener:${props.listener}` };
-  }
-  if (props.route) {
-    return { nodeId: props.route, kind: "route", key: `route:${props.route}` };
-  }
-  if (props.page) {
-    const path = normalizePagePath(props.page);
-    return { nodeId: path, kind: "page", key: `page:${path}` };
-  }
-  if (props.component) {
-    return { nodeId: props.component, kind: "page", key: `component:${props.component}` };
-  }
-  if (props.aggregate) {
-    if (props.mutationMethod) {
-      return {
-        nodeId: props.aggregate,
-        kind: "aggregate",
-        method: { name: props.mutationMethod, kind: "mutation" },
-        key: `aggregate:${props.aggregate}#mutate:${props.mutationMethod}`,
-      };
-    }
-    if (props.queryMethod) {
-      return {
-        nodeId: props.aggregate,
-        kind: "aggregate",
-        method: { name: props.queryMethod, kind: "query" },
-        key: `aggregate:${props.aggregate}#query:${props.queryMethod}`,
-      };
-    }
-    // `<Arc aggregate="x" event="e">` — the inline event is a node of its own
-    // (the mapper synthesises event nodes for aggregate events).
-    if (props.event) {
-      return { nodeId: props.event, kind: "event", key: `event:${props.event}` };
-    }
-    return { nodeId: props.aggregate, kind: "aggregate", key: `aggregate:${props.aggregate}` };
-  }
-  // Standalone event (no aggregate).
-  if (props.event) {
-    return { nodeId: props.event, kind: "event", key: `event:${props.event}` };
-  }
-  return null;
-}

package/tests/refs.test.ts

@@ -1,56 +0,0 @@
-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/subgraph.test.ts

@@ -1,54 +0,0 @@
-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"]);
-  });
-});