@arcote.tech/arc-map 0.7.27

package/src/scan.ts

@@ -0,0 +1,393 @@
+/**
+ * TSX scanner — statically maps React `useScope` usages to context elements.
+ *
+ * Strategy (convention-based, no full type-checker):
+ *  Phase A — discover scope wrappers across the whole project:
+ *            `usePlatformScope(ctx, "scope")` and `createScope("scope")` calls,
+ *            recording the enclosing hook name -> scope.
+ *  Phase B — per file, resolve scope-bearing variables and accessor variables,
+ *            then collect `<accessor>.<element>.<method>()` chains in both the
+ *            inline and via-variable shapes.
+ *
+ * Joining element name -> map node happens in the mapper; here we only emit
+ * `{ file, element, usage, scope, methods }`.
+ */
+
+import { dirname, relative, resolve as resolvePath } from "node:path";
+import {
+  Node,
+  Project,
+  SyntaxKind,
+  type CallExpression,
+  type SourceFile,
+} from "ts-morph";
+import type { MapComponent, MapComponentEdge } from "./types";
+import { normalizePagePath } from "./refs";
+
+export interface ScanInput {
+  /** Absolute glob(s) or file paths of TSX sources to scan. */
+  globs: string[];
+  /** Workspace root, used to relativize component ids. */
+  workspaceRoot: string;
+  /** Maps an absolute file path to its owning workspace package name. */
+  packageOf?: (absFile: string) => string | undefined;
+  /** Optional tsconfig for module resolution (not required for the AST pass). */
+  tsConfigFilePath?: string;
+}
+
+export interface ScanResult {
+  components: MapComponent[];
+  componentEdges: MapComponentEdge[];
+}
+
+type Usage = "query" | "mutation";
+
+const SCOPE_FACTORY = "usePlatformScope";
+const SCOPE_CREATE = "createScope";
+
+// ---------------------------------------------------------------------------
+// AST helpers
+// ---------------------------------------------------------------------------
+
+function callName(call: CallExpression): string | undefined {
+  const expr = call.getExpression();
+  if (Node.isIdentifier(expr)) return expr.getText();
+  if (Node.isPropertyAccessExpression(expr)) return expr.getName();
+  return undefined;
+}
+
+function stringArg(call: CallExpression, index: number): string | undefined {
+  const arg = call.getArguments()[index];
+  if (arg && Node.isStringLiteral(arg)) return arg.getLiteralValue();
+  return undefined;
+}
+
+/** Name of the function/variable that lexically encloses a node. */
+function enclosingHookName(node: Node): string | undefined {
+  let cur: Node | undefined = node;
+  while (cur) {
+    if (Node.isFunctionDeclaration(cur)) return cur.getName();
+    if (Node.isVariableDeclaration(cur)) return cur.getName();
+    cur = cur.getParent();
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Phase A — project-wide scope wrapper discovery
+// ---------------------------------------------------------------------------
+
+/** hook name (e.g. `useContentScope`) -> scope name (e.g. `workspace`). */
+function discoverScopeWrappers(sourceFiles: SourceFile[]): Map<string, string> {
+  const wrappers = new Map<string, string>();
+  for (const sf of sourceFiles) {
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      const name = callName(call);
+      let scope: string | undefined;
+      if (name === SCOPE_FACTORY) scope = stringArg(call, 1);
+      else if (name === SCOPE_CREATE) scope = stringArg(call, 0);
+      if (!scope) continue;
+      const hook = enclosingHookName(call);
+      if (hook) wrappers.set(hook, scope);
+    }
+  }
+  return wrappers;
+}
+
+// ---------------------------------------------------------------------------
+// Phase B — per-file resolution
+// ---------------------------------------------------------------------------
+
+interface FileScopeState {
+  /** variable name -> scope name (e.g. `scope` -> `workspace`). */
+  scopeVars: Map<string, string | undefined>;
+  /** accessor variable -> { usage, scope } (e.g. `commands` -> mutation). */
+  accessorVars: Map<string, { usage: Usage; scope?: string }>;
+}
+
+/** Resolve the scope name of an expression that yields a scope object. */
+function resolveScopeExpr(
+  expr: Node,
+  wrappers: Map<string, string>,
+  scopeVars: Map<string, string | undefined>,
+): string | undefined {
+  if (Node.isIdentifier(expr)) {
+    if (scopeVars.has(expr.getText())) return scopeVars.get(expr.getText());
+    return undefined;
+  }
+  if (Node.isCallExpression(expr)) {
+    const name = callName(expr);
+    if (name === SCOPE_FACTORY) return stringArg(expr, 1);
+    if (name && wrappers.has(name)) return wrappers.get(name);
+  }
+  return undefined;
+}
+
+/** If `call` is `<scopeExpr>.useQuery()/.useMutation()`, return its usage + scope. */
+function asAccessorCall(
+  call: CallExpression,
+  wrappers: Map<string, string>,
+  scopeVars: Map<string, string | undefined>,
+): { usage: Usage; scope?: string } | undefined {
+  const expr = call.getExpression();
+  if (!Node.isPropertyAccessExpression(expr)) return undefined;
+  const m = expr.getName();
+  if (m !== "useQuery" && m !== "useMutation") return undefined;
+  const usage: Usage = m === "useQuery" ? "query" : "mutation";
+  return { usage, scope: resolveScopeExpr(expr.getExpression(), wrappers, scopeVars) };
+}
+
+function buildFileState(
+  sf: SourceFile,
+  wrappers: Map<string, string>,
+): FileScopeState {
+  const scopeVars = new Map<string, string | undefined>();
+  const accessorVars = new Map<string, { usage: Usage; scope?: string }>();
+
+  for (const decl of sf.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+    const init = decl.getInitializer();
+    if (!init) continue;
+    const nameNode = decl.getNameNode();
+
+    // const scope = useXxxScope()  |  const scope = usePlatformScope(ctx, "user")
+    if (Node.isIdentifier(nameNode) && Node.isCallExpression(init)) {
+      const name = callName(init);
+      if (name === SCOPE_FACTORY) {
+        scopeVars.set(nameNode.getText(), stringArg(init, 1));
+        continue;
+      }
+      if (name && wrappers.has(name)) {
+        scopeVars.set(nameNode.getText(), wrappers.get(name));
+        continue;
+      }
+    }
+
+    // const commands = scope.useMutation()  |  const q = scope.useQuery()
+    if (Node.isCallExpression(init)) {
+      const accessor = asAccessorCall(init, wrappers, scopeVars);
+      if (accessor && Node.isIdentifier(nameNode)) {
+        accessorVars.set(nameNode.getText(), accessor);
+      }
+    }
+  }
+
+  return { scopeVars, accessorVars };
+}
+
+// ---------------------------------------------------------------------------
+// Usage collection
+// ---------------------------------------------------------------------------
+
+interface RawUsage {
+  element: string;
+  method?: string;
+  usage: Usage;
+  scope?: string;
+  line: number;
+}
+
+/**
+ * Given the expression node that yields the accessor (the object before
+ * `.<element>`), return the usage + scope, or undefined if it isn't an accessor.
+ */
+function resolveAccessor(
+  obj: Node,
+  state: FileScopeState,
+  wrappers: Map<string, string>,
+): { usage: Usage; scope?: string } | undefined {
+  // Inline: (scope.useQuery()).contentTopic
+  if (Node.isCallExpression(obj)) {
+    return asAccessorCall(obj, wrappers, state.scopeVars);
+  }
+  // Via variable: commands.creatorWorkspaces
+  if (Node.isIdentifier(obj)) {
+    return state.accessorVars.get(obj.getText());
+  }
+  return undefined;
+}
+
+function collectUsages(
+  sf: SourceFile,
+  state: FileScopeState,
+  wrappers: Map<string, string>,
+): RawUsage[] {
+  const usages: RawUsage[] = [];
+
+  for (const pa of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
+    // pa = <obj>.<element>
+    const obj = pa.getExpression();
+    const elementName = pa.getName();
+    if (elementName === "useQuery" || elementName === "useMutation") continue;
+
+    const accessor = resolveAccessor(obj, state, wrappers);
+    if (!accessor) continue;
+
+    // Optional method: <obj>.<element>.<method>(...)
+    let method: string | undefined;
+    const parent = pa.getParent();
+    if (parent && Node.isPropertyAccessExpression(parent)) {
+      method = parent.getName();
+    }
+
+    usages.push({
+      element: elementName,
+      method,
+      usage: accessor.usage,
+      scope: accessor.scope,
+      line: pa.getStartLineNumber(),
+    });
+  }
+
+  return usages;
+}
+
+// ---------------------------------------------------------------------------
+// Page() ↔ component-file linking
+// ---------------------------------------------------------------------------
+
+/** Resolve the import specifier that backs a component identifier — both the
+ *  `const X = lazy(() => import("./x"))` and `import X from "./x"` shapes. */
+function importSpecifierForIdent(sf: SourceFile, name: string): string | undefined {
+  const decl = sf.getVariableDeclaration(name);
+  const init = decl?.getInitializer();
+  if (init) {
+    for (const call of init.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      if (call.getExpression().getKind() === SyntaxKind.ImportKeyword) {
+        const a = call.getArguments()[0];
+        if (a && Node.isStringLiteral(a)) return a.getLiteralValue();
+      }
+    }
+  }
+  for (const imp of sf.getImportDeclarations()) {
+    if (imp.getDefaultImport()?.getText() === name)
+      return imp.getModuleSpecifierValue();
+    if (imp.getNamedImports().some((ni) => ni.getName() === name))
+      return imp.getModuleSpecifierValue();
+  }
+  return undefined;
+}
+
+/** Match a relative import specifier (resolved against the declaring file) to a
+ *  scanned component id, trying common extensions / index files. */
+function matchComponentId(
+  specifier: string,
+  declFileAbs: string,
+  workspaceRoot: string,
+  componentIds: Set<string>,
+): string | undefined {
+  if (!specifier.startsWith(".")) return undefined;
+  const abs = resolvePath(dirname(declFileAbs), specifier);
+  const rel = relative(workspaceRoot, abs).replace(/\\/g, "/");
+  for (const c of [rel, `${rel}.tsx`, `${rel}.ts`, `${rel}/index.tsx`, `${rel}/index.ts`]) {
+    if (componentIds.has(c)) return c;
+  }
+  return undefined;
+}
+
+/** component-file id -> page route path, for every `page("/path", Comp)` whose
+ *  component resolves to a scanned file. */
+function discoverPageFiles(
+  sourceFiles: SourceFile[],
+  workspaceRoot: string,
+  componentIds: Set<string>,
+): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const sf of sourceFiles) {
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      if (callName(call) !== "page") continue;
+      const path = stringArg(call, 0);
+      const compArg = call.getArguments()[1];
+      if (!path || !compArg || !Node.isIdentifier(compArg)) continue;
+      const spec = importSpecifierForIdent(sf, compArg.getText());
+      if (!spec) continue;
+      const compId = matchComponentId(spec, sf.getFilePath(), workspaceRoot, componentIds);
+      if (compId) out.set(compId, normalizePagePath(path));
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function scanScopeUsages(input: ScanInput): ScanResult {
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+    compilerOptions: { allowJs: true, jsx: 4 /* react-jsx */ },
+  });
+  project.addSourceFilesAtPaths(input.globs);
+  const sourceFiles = project.getSourceFiles();
+
+  const wrappers = discoverScopeWrappers(sourceFiles);
+
+  const components = new Map<string, MapComponent>();
+  // key: file|element|usage|scope -> edge accumulator
+  const edges = new Map<string, MapComponentEdge>();
+
+  for (const sf of sourceFiles) {
+    const abs = sf.getFilePath();
+    const state = buildFileState(sf, wrappers);
+    const usages = collectUsages(sf, state, wrappers);
+    if (usages.length === 0) continue;
+
+    const rel = relative(input.workspaceRoot, abs);
+    const compId = rel;
+    if (!components.has(compId)) {
+      components.set(compId, {
+        id: compId,
+        file: rel,
+        name: baseName(rel),
+        package: input.packageOf?.(abs),
+      });
+    }
+
+    for (const u of usages) {
+      const key = `${compId}|${u.element}|${u.usage}|${u.scope ?? ""}`;
+      const existing = edges.get(key);
+      if (existing) {
+        if (u.method && !existing.methods.includes(u.method)) existing.methods.push(u.method);
+        if (u.line < (existing.line ?? Infinity)) existing.line = u.line;
+        continue;
+      }
+      edges.set(key, {
+        id: key,
+        source: compId,
+        target: u.element,
+        usage: u.usage,
+        scope: u.scope,
+        methods: u.method ? [u.method] : [],
+        line: u.line,
+      });
+    }
+  }
+
+  // Link page() registrations: re-key a page component's scope-usage edges onto
+  // the page PATH so they attach to the page node (buildPageNodes, id = path) —
+  // the screen connects to the elements it uses. The now-orphan file node drops.
+  const pageByFile = discoverPageFiles(
+    sourceFiles,
+    input.workspaceRoot,
+    new Set(components.keys()),
+  );
+  if (pageByFile.size) {
+    for (const e of edges.values()) {
+      const path = pageByFile.get(e.source);
+      if (!path) continue;
+      e.source = path;
+      e.id = `${path}|${e.target}|${e.usage}|${e.scope ?? ""}`;
+    }
+    for (const fileId of pageByFile.keys()) components.delete(fileId);
+  }
+
+  return {
+    components: [...components.values()],
+    componentEdges: [...edges.values()],
+  };
+}
+
+function baseName(rel: string): string {
+  const file = rel.split("/").pop() ?? rel;
+  return file.replace(/\.(tsx|ts|jsx|js)$/, "");
+}

package/src/server.ts

@@ -0,0 +1,262 @@
+/**
+ * Arc Context Map dev server.
+ *
+ * A small standalone Bun.serve that:
+ *  - bundles the React Flow front once via Bun.build,
+ *  - serves the shell HTML + bundle,
+ *  - computes `/api/map` on demand from the live context (+ cached TSX scan),
+ *  - exposes an SSE stream so the UI auto-refreshes when the host calls
+ *    {@link MapServer.notifyReload} (wired to platform-dev's file watcher).
+ *
+ * Decoupled from the CLI: the host injects how to read the live context, the
+ * module index, and the scan globs.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { ArcContextAny } from "@arcote.tech/arc";
+import { buildModuleIndex, buildPageNodes } from "./module-index";
+import { buildMapJson, type ModuleInfo } from "./mapper";
+import { scanScopeUsages, type ScanInput } from "./scan";
+import { discoverUseCases, type UseCasePackage } from "./use-cases/discover";
+import type { MapJson, UseCaseEntry } from "./types";
+
+export interface MapServerOptions {
+  /** Returns the current live context (recomputed by the host on rebuild). */
+  getContext: () => ArcContextAny | null | undefined;
+  /** TSX scan configuration (globs + workspace root + package attribution). */
+  scan: ScanInput;
+  /** Preferred port; auto-increments if busy. Defaults to 5006. */
+  port?: number;
+  /**
+   * Optional element->module index provider. Defaults to reading the platform
+   * registry via {@link buildModuleIndex}.
+   */
+  getModuleIndex?: () => Map<string, ModuleInfo>;
+  /** Override the React app entry (absolute path). Mostly for tests. */
+  appEntry?: string;
+  /** Packages to scan for `use-cases/**\/*.mdx`. Enables the use-case mode. */
+  useCasePackages?: UseCasePackage[];
+}
+
+export interface MapServer {
+  server: ReturnType<typeof Bun.serve>;
+  port: number;
+  url: string;
+  /** Invalidate the scan cache and tell connected UIs to refetch. */
+  notifyReload: () => void;
+  stop: () => void;
+}
+
+const DEFAULT_PORT = 5006;
+const MAX_PORT_TRIES = 20;
+
+function shellHtml(): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Arc Context Map</title>
+  <link rel="stylesheet" href="/app.css" />
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" />
+  <style>
+    html, body, #root { height: 100%; margin: 0; }
+    body {
+      color: #2a173f;
+      font-family: "Inter", ui-sans-serif, system-ui, sans-serif;
+      background-color: #ffffff;
+      background-image: linear-gradient(135deg,#dbeafe 0%,#ffffff 48%,#f3e8ff 100%);
+      background-attachment: fixed;
+    }
+    .react-flow__attribution { display: none; }
+    .react-flow__controls-button {
+      background: rgba(255,255,255,0.8) !important;
+      border-bottom: 1px solid rgba(168,85,247,0.25) !important;
+      color: #2a173f !important;
+    }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/app.js"></script>
+</body>
+</html>`;
+}
+
+async function buildApp(appEntry: string): Promise<{ js: string; css: string }> {
+  const result = await Bun.build({
+    entrypoints: [appEntry],
+    target: "browser",
+    minify: false,
+    define: { "process.env.NODE_ENV": '"development"' },
+  });
+  if (!result.success) {
+    const msg = result.logs.map((l) => String(l)).join("\n");
+    throw new Error(`arc-map: failed to build front bundle:\n${msg}`);
+  }
+  let js = "";
+  let css = "";
+  for (const out of result.outputs) {
+    if (out.path.endsWith(".css")) css += await out.text();
+    else if (out.path.endsWith(".js")) js += await out.text();
+  }
+  return { js, css };
+}
+
+const CORS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type",
+};
+
+export async function startMapServer(opts: MapServerOptions): Promise<MapServer> {
+  const appEntry =
+    opts.appEntry ?? fileURLToPath(new URL("./app/index.tsx", import.meta.url));
+  const { js, css } = await buildApp(appEntry);
+
+  // Cached TSX scan — recomputed lazily, invalidated on notifyReload.
+  let scanCache: ReturnType<typeof scanScopeUsages> | null = null;
+  const getScan = () => {
+    if (!scanCache) scanCache = scanScopeUsages(opts.scan);
+    return scanCache;
+  };
+
+  const buildPayload = (): MapJson => {
+    const context = opts.getContext();
+    if (!context) {
+      return { spaces: [], elements: [], edges: [], components: [], componentEdges: [] };
+    }
+    const scan = getScan();
+    const moduleByElement = (opts.getModuleIndex ?? buildModuleIndex)();
+    return buildMapJson({
+      context,
+      moduleByElement,
+      componentEdges: scan.componentEdges,
+      components: scan.components,
+      pages: buildPageNodes(),
+      generatedAt: new Date().toISOString(),
+    });
+  };
+
+  // Cached use-case discovery — invalidated on notifyReload (file changes).
+  let useCaseCache: ReturnType<typeof discoverUseCases> | null = null;
+  const getUseCases = () => {
+    if (!useCaseCache) useCaseCache = discoverUseCases(opts.useCasePackages ?? []);
+    return useCaseCache;
+  };
+
+  const sseClients = new Set<ReadableStreamDefaultController>();
+  const notifyReload = () => {
+    scanCache = null;
+    useCaseCache = null;
+    for (const c of sseClients) {
+      try {
+        c.enqueue("data: reload\n\n");
+      } catch {
+        sseClients.delete(c);
+      }
+    }
+  };
+
+  const handler = (req: Request): Response => {
+    const url = new URL(req.url);
+    if (req.method === "OPTIONS") return new Response(null, { headers: CORS });
+
+    switch (url.pathname) {
+      case "/app.js":
+        return new Response(js, {
+          headers: { "Content-Type": "text/javascript", "Cache-Control": "no-cache" },
+        });
+      case "/app.css":
+        return new Response(css, {
+          headers: { "Content-Type": "text/css", "Cache-Control": "no-cache" },
+        });
+      case "/api/map": {
+        let body: string;
+        try {
+          body = JSON.stringify(buildPayload());
+        } catch (e) {
+          return new Response(
+            JSON.stringify({ error: (e as Error).message }),
+            { status: 500, headers: { ...CORS, "Content-Type": "application/json" } },
+          );
+        }
+        return new Response(body, {
+          headers: { ...CORS, "Content-Type": "application/json", "Cache-Control": "no-cache" },
+        });
+      }
+      case "/api/use-cases": {
+        const list: UseCaseEntry[] = getUseCases().map(
+          ({ absPath, ...e }) => e,
+        );
+        return new Response(JSON.stringify({ useCases: list }), {
+          headers: { ...CORS, "Content-Type": "application/json", "Cache-Control": "no-cache" },
+        });
+      }
+      case "/api/use-cases/raw": {
+        const id = url.searchParams.get("id");
+        const hit = id ? getUseCases().find((u) => u.id === id) : undefined;
+        if (!hit) {
+          return new Response("Not Found", { status: 404, headers: CORS });
+        }
+        let text: string;
+        try {
+          text = readFileSync(hit.absPath, "utf-8");
+        } catch (e) {
+          return new Response((e as Error).message, { status: 500, headers: CORS });
+        }
+        return new Response(text, {
+          headers: { ...CORS, "Content-Type": "text/markdown; charset=utf-8", "Cache-Control": "no-cache" },
+        });
+      }
+      case "/api/reload-stream": {
+        const stream = new ReadableStream({
+          start(controller) {
+            sseClients.add(controller);
+            controller.enqueue("data: connected\n\n");
+          },
+          cancel(controller) {
+            sseClients.delete(controller);
+          },
+        });
+        return new Response(stream, {
+          headers: {
+            ...CORS,
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+          },
+        });
+      }
+      default:
+        return new Response(shellHtml(), {
+          headers: { "Content-Type": "text/html" },
+        });
+    }
+  };
+
+  // Port auto-increment.
+  const basePort = opts.port ?? DEFAULT_PORT;
+  let server: ReturnType<typeof Bun.serve> | null = null;
+  let port = basePort;
+  for (let i = 0; i < MAX_PORT_TRIES; i++) {
+    try {
+      server = Bun.serve({ port: basePort + i, fetch: handler });
+      port = basePort + i;
+      break;
+    } catch (e) {
+      if (i === MAX_PORT_TRIES - 1) throw e;
+    }
+  }
+  if (!server) throw new Error("arc-map: could not bind a port");
+
+  return {
+    server,
+    port,
+    url: `http://localhost:${port}`,
+    notifyReload,
+    stop: () => server!.stop(true),
+  };
+}