@arcote.tech/arc-map 0.7.27

package/src/mapper.ts

@@ -0,0 +1,392 @@
+/**
+ * Mapper — turns a live Arc context into the JSON the map UI consumes.
+ *
+ * Pure and dependency-light: it reads metadata off element instances via the
+ * accessors documented in the element classes (`@arcote.tech/arc`). The caller
+ * supplies the module index and the React component edges, keeping this unit
+ * testable in isolation.
+ */
+
+import {
+  ArcAggregateElement,
+  ArcCommand,
+  ArcEvent,
+  ArcListener,
+  ArcRoute,
+  ArcStaticView,
+  ArcView,
+  type ArcContextAny,
+  type ArcContextElementAny,
+} from "@arcote.tech/arc";
+import {
+  UNGROUPED_SPACE_ID,
+  type ElementKind,
+  type MapComponent,
+  type MapComponentEdge,
+  type MapEdge,
+  type MapElement,
+  type MapElementMethod,
+  type MapJson,
+  type MapSpace,
+} from "./types";
+
+/** Per-element module attribution, computed by the caller from the registry. */
+export interface ModuleInfo {
+  moduleId: string;
+  moduleName: string;
+  scope?: string;
+}
+
+export interface BuildMapInput {
+  context: ArcContextAny;
+  /** element name -> owning module info (best effort). */
+  moduleByElement?: Map<string, ModuleInfo>;
+  /** React component -> element edges from the ts-morph scan. */
+  componentEdges?: MapComponentEdge[];
+  components?: MapComponent[];
+  /** Page nodes (from arc `page()` registry), appended as kind `page`. */
+  pages?: MapElement[];
+  /** ISO timestamp; injected so the function stays deterministic for tests. */
+  generatedAt?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Kind detection
+// ---------------------------------------------------------------------------
+
+function detectKind(el: ArcContextElementAny): ElementKind {
+  if (el instanceof ArcAggregateElement) return "aggregate";
+  if (el instanceof ArcCommand) return "command";
+  if (el instanceof ArcEvent) return "event";
+  if (el instanceof ArcStaticView) return "static-view";
+  if (el instanceof ArcView) return "view";
+  if (el instanceof ArcListener) return "listener";
+  if (el instanceof ArcRoute) return "route";
+  return "unknown";
+}
+
+// ---------------------------------------------------------------------------
+// Small safe accessors
+// ---------------------------------------------------------------------------
+
+function toJsonSchema(schema: unknown): unknown {
+  const fn = (schema as { toJsonSchema?: () => unknown })?.toJsonSchema;
+  if (typeof fn === "function") {
+    try {
+      return fn.call(schema);
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/** Read protection token names off any element exposing `.protections`. */
+function protectionNames(el: any): string[] | undefined {
+  const list = el?.protections;
+  if (!Array.isArray(list) || list.length === 0) return undefined;
+  const names = list
+    .map((p: any) => p?.token?.name)
+    .filter((n: unknown): n is string => typeof n === "string");
+  return names.length ? names : undefined;
+}
+
+/**
+ * Resolve which space an element belongs to. Prefers the core `__contextId`
+ * stamp (true context boundary), then falls back to the owning module — so the
+ * map still groups by module on a stock runtime where core hasn't been rebuilt
+ * with the stamp. Last resort: a shared "ungrouped" bucket.
+ */
+/** Element names from an array of element instances (dep arrays). */
+function depNames(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value
+        .map((t) => (t && typeof (t as any).name === "string" ? (t as any).name : null))
+        .filter((n): n is string => !!n)
+    : [];
+}
+
+function spaceOf(
+  el: ArcContextElementAny | undefined,
+  module?: ModuleInfo,
+): string {
+  // Group by module NAME first: it is the feature-level unit. A single feature
+  // is often split across many `context()` calls (distinct __contextId each) and
+  // many module() registrations (distinct id, shared name) — keying on the name
+  // collapses them into one box. __contextId / __contextName only group elements
+  // that have no module attribution.
+  if (module?.moduleName) return `mod:${module.moduleName}`;
+  const contextId = (el as any)?.__contextId;
+  if (contextId) return contextId;
+  if (module?.moduleId) return `mod:${module.moduleId}`;
+  return UNGROUPED_SPACE_ID;
+}
+
+function spaceLabelOf(
+  el: ArcContextElementAny | undefined,
+  module?: ModuleInfo,
+): string | undefined {
+  return module?.moduleName ?? (el as any)?.__contextName;
+}
+
+// ---------------------------------------------------------------------------
+// Element extraction
+// ---------------------------------------------------------------------------
+
+function extractElement(
+  el: ArcContextElementAny,
+  kind: ElementKind,
+  module: ModuleInfo | undefined,
+): MapElement {
+  const data = (el as any).data ?? {};
+  const base: MapElement = {
+    id: el.name,
+    name: el.name,
+    kind,
+    spaceId: spaceOf(el, module),
+    moduleId: module?.moduleId,
+    moduleName: module?.moduleName,
+    scope: module?.scope,
+    description: data.description,
+    protections: protectionNames(el),
+  };
+
+  switch (kind) {
+    case "aggregate": {
+      const Agg = (el as any).Aggregate;
+      const events: string[] = (Agg?.__aggregateEvents ?? [])
+        .map((e: any) => e?.event?.name)
+        .filter(Boolean);
+      const mutate: MapElementMethod[] = (Agg?.__aggregateMutateMethods ?? []).map(
+        (m: any) => ({
+          name: m.name,
+          kind: "mutate" as const,
+          queryDeps: depNames(m?.queryElements),
+          mutationDeps: depNames(m?.mutationElements),
+        }),
+      );
+      const query: MapElementMethod[] = (Agg?.__aggregateQueryMethods ?? []).map(
+        (m: any) => ({ name: m.name, kind: "query" as const }),
+      );
+      const cron: MapElementMethod[] = (Agg?.__aggregateCronMethods ?? []).map(
+        (m: any) => ({ name: m.name, kind: "cron" as const }),
+      );
+      return {
+        ...base,
+        schema: toJsonSchema(Agg?.__aggregateSchema ?? (el as any).schema),
+        events,
+        methods: [...mutate, ...query, ...cron],
+        protections: protectionNames({ protections: Agg?.__aggregateProtections }),
+      };
+    }
+    case "command":
+      return {
+        ...base,
+        params: toJsonSchema(data.params),
+        results: Array.isArray(data.results)
+          ? data.results.map(toJsonSchema).filter(Boolean)
+          : undefined,
+        queryDeps: depNames(data.queryElements),
+        mutationDeps: depNames(data.mutationElements),
+      };
+    case "listener":
+      return {
+        ...base,
+        queryDeps: depNames(data.queryElements),
+        mutationDeps: depNames(data.mutationElements),
+      };
+    case "event":
+      return { ...base, payload: toJsonSchema((el as any).payload) };
+    case "view":
+    case "static-view":
+      return { ...base, schema: toJsonSchema((el as any).schema) };
+    case "route":
+      return {
+        ...base,
+        path: (el as any).routePath,
+        queryDeps: depNames(data.queryElements),
+        mutationDeps: depNames(data.mutationElements),
+      };
+    default:
+      return base;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Edge extraction
+// ---------------------------------------------------------------------------
+
+interface RawEdge {
+  source: string;
+  targets: ArcContextElementAny[];
+  kind: MapEdge["kind"];
+}
+
+function depTargets(value: unknown): ArcContextElementAny[] {
+  return Array.isArray(value)
+    ? value.filter((t): t is ArcContextElementAny => !!t && typeof (t as any).name === "string")
+    : [];
+}
+
+function collectRawEdges(el: ArcContextElementAny, kind: ElementKind): RawEdge[] {
+  const data = (el as any).data ?? {};
+  const edges: RawEdge[] = [];
+  const push = (k: MapEdge["kind"], targets: ArcContextElementAny[]) => {
+    if (targets.length) edges.push({ source: el.name, targets, kind: k });
+  };
+
+  // Shared query/mutate dependency arrays (command / route / listener).
+  push("queries", depTargets(data.queryElements));
+  push("mutates", depTargets(data.mutationElements));
+
+  if (kind === "listener") {
+    push("listens", depTargets((el as any).eventElements));
+  }
+
+  if (kind === "view" || kind === "static-view") {
+    const handled = typeof (el as any).getElements === "function" ? (el as any).getElements() : [];
+    push("handles", depTargets(handled));
+  }
+
+  if (kind === "aggregate") {
+    const Agg = (el as any).Aggregate;
+    // Emitted events (inline + public) — targets resolved by name later.
+    const emitted = depTargets((Agg?.__aggregateEvents ?? []).map((e: any) => e?.event));
+    push("emits", emitted);
+    // External events handled by the aggregate.
+    const handled = typeof (el as any).getElements === "function" ? (el as any).getElements() : [];
+    push("handles", depTargets(handled));
+    // Per-method query/mutate dependencies.
+    for (const m of Agg?.__aggregateMutateMethods ?? []) {
+      push("queries", depTargets(m?.queryElements));
+      push("mutates", depTargets(m?.mutationElements));
+    }
+  }
+
+  return edges;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function buildMapJson(input: BuildMapInput): MapJson {
+  const { context, moduleByElement, componentEdges = [], components = [] } = input;
+  const elements: MapElement[] = [];
+  const nodeIndex = new Map<string, MapElement>();
+  const spaceIndex = new Map<string, MapSpace>();
+
+  const registerSpace = (id: string, name?: string) => {
+    const existing = spaceIndex.get(id);
+    if (existing) {
+      if (name && existing.name === existing.id) existing.name = name;
+      return;
+    }
+    spaceIndex.set(id, { id, name: name ?? id });
+  };
+
+  // 1) Element nodes from the live context.
+  for (const el of context.elements as ArcContextElementAny[]) {
+    const module = moduleByElement?.get(el.name);
+    let mapped: MapElement;
+    try {
+      const kind = detectKind(el);
+      mapped = extractElement(el, kind, module);
+    } catch {
+      mapped = {
+        id: el.name,
+        name: el.name,
+        kind: "unknown",
+        spaceId: spaceOf(el, module),
+      };
+    }
+    if (nodeIndex.has(mapped.id)) continue;
+    elements.push(mapped);
+    nodeIndex.set(mapped.id, mapped);
+    registerSpace(mapped.spaceId, spaceLabelOf(el, module));
+  }
+
+  // 1b) Page nodes (arc page() registry) — UI layer, no domain edges.
+  for (const page of input.pages ?? []) {
+    if (nodeIndex.has(page.id)) continue;
+    elements.push(page);
+    nodeIndex.set(page.id, page);
+    registerSpace(page.spaceId, page.moduleName);
+  }
+
+  // 2) Synthesize event nodes for aggregate-declared events not present as
+  //    standalone elements, so `emits` edges always have a target.
+  for (const el of context.elements as ArcContextElementAny[]) {
+    if (!(el instanceof ArcAggregateElement)) continue;
+    const Agg = (el as any).Aggregate;
+    const aggModule = moduleByElement?.get(el.name);
+    for (const entry of Agg?.__aggregateEvents ?? []) {
+      const ev = entry?.event;
+      const name: string | undefined = ev?.name;
+      if (!name || nodeIndex.has(name)) continue;
+      const spaceId = spaceOf(el, aggModule);
+      const synth: MapElement = {
+        id: name,
+        name,
+        kind: "event",
+        spaceId,
+        payload: toJsonSchema(ev?.payload),
+      };
+      elements.push(synth);
+      nodeIndex.set(name, synth);
+    }
+  }
+
+  // Resolve a referenced name to a node — with a fallback for namespaced event
+  // names: aggregate inline events are referenced as `aggregate.eventName` by
+  // listeners/views (via getEvent) but registered under the short `eventName`.
+  const resolveNode = (name: string): MapElement | undefined => {
+    const direct = nodeIndex.get(name);
+    if (direct) return direct;
+    const dot = name.lastIndexOf(".");
+    return dot >= 0 ? nodeIndex.get(name.slice(dot + 1)) : undefined;
+  };
+
+  // 3) Domain edges (only those whose target resolves to a known node).
+  const edges: MapEdge[] = [];
+  const seenEdge = new Set<string>();
+  for (const el of context.elements as ArcContextElementAny[]) {
+    let raw: RawEdge[] = [];
+    try {
+      raw = collectRawEdges(el, detectKind(el));
+    } catch {
+      raw = [];
+    }
+    for (const r of raw) {
+      const sourceNode = resolveNode(r.source);
+      for (const target of r.targets) {
+        const targetNode = resolveNode(target.name);
+        if (!sourceNode || !targetNode || sourceNode.id === targetNode.id) continue;
+        const id = `${sourceNode.id}->${targetNode.id}:${r.kind}`;
+        if (seenEdge.has(id)) continue;
+        seenEdge.add(id);
+        edges.push({
+          id,
+          source: sourceNode.id,
+          target: targetNode.id,
+          kind: r.kind,
+          crossContext: sourceNode.spaceId !== targetNode.spaceId,
+        });
+      }
+    }
+  }
+
+  // 4) Keep only component edges that resolve to a known element node.
+  const resolvedComponentEdges = componentEdges.filter((e) => nodeIndex.has(e.target));
+  const usedComponentIds = new Set(resolvedComponentEdges.map((e) => e.source));
+  const resolvedComponents = components.filter((c) => usedComponentIds.has(c.id));
+
+  return {
+    spaces: [...spaceIndex.values()],
+    elements,
+    edges,
+    components: resolvedComponents,
+    componentEdges: resolvedComponentEdges,
+    generatedAt: input.generatedAt,
+  };
+}

package/src/module-index.ts

@@ -0,0 +1,70 @@
+/**
+ * Builds an element-name -> module attribution index from the platform
+ * registry. Best-effort and defensive: the map is a UI tag, so any registry
+ * shape mismatch degrades to an empty index rather than throwing.
+ */
+
+import {
+  getContextElementFragments,
+  getModule,
+  getPageFragments,
+} from "@arcote.tech/platform";
+import type { ModuleInfo } from "./mapper";
+import type { MapElement } from "./types";
+import { normalizePagePath } from "./refs";
+
+export function buildModuleIndex(): Map<string, ModuleInfo> {
+  const index = new Map<string, ModuleInfo>();
+  try {
+    for (const frag of getContextElementFragments()) {
+      const element = (frag as any).element;
+      const moduleId = (frag as any).moduleId;
+      const name = element?.name;
+      if (!name || !moduleId) continue;
+      // First module to own an element wins (mirrors element __contextId origin).
+      if (index.has(name)) continue;
+      const mod = getModule(moduleId) as any;
+      index.set(name, {
+        moduleId,
+        moduleName: mod?.name ?? moduleId,
+        scope: mod?.scope,
+      });
+    }
+  } catch {
+    // registry shape changed — leave the index empty.
+  }
+  return index;
+}
+
+/** Page nodes from the arc `page()` registry (UI layer), flattened over children. */
+export function buildPageNodes(): MapElement[] {
+  const out: MapElement[] = [];
+  const seen = new Set<string>();
+  const walk = (frags: any[]) => {
+    for (const p of frags ?? []) {
+      // Identify the page by its normalized route PATH (never the module key) so
+      // it collapses onto the same node `<Arc page="…">` resolves to.
+      const path: string | undefined = p?.path ? normalizePagePath(p.path) : undefined;
+      if (path && !seen.has(path)) {
+        seen.add(path);
+        const mod = p.moduleId ? (getModule(p.moduleId) as any) : undefined;
+        out.push({
+          id: path,
+          name: path,
+          kind: "page",
+          spaceId: mod?.name ? `mod:${mod.name}` : "pages",
+          moduleName: mod?.name,
+          description: typeof p.label === "string" ? p.label : undefined,
+          path,
+        });
+      }
+      if (p?.children?.length) walk(p.children);
+    }
+  };
+  try {
+    walk(getPageFragments());
+  } catch {
+    // registry shape changed — no pages.
+  }
+  return out;
+}

package/src/refs.ts

@@ -0,0 +1,121 @@
+/**
+ * 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;
+}