@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/src/passes/screen-preview.ts

@@ -0,0 +1,295 @@
+/**
+ * Bounded static page structure for the page inspector: JSX sections nested one inside the
+ * other, with component identifiers resolved through the module graph.
+ *
+ * This is not a rendering. It deliberately stops at explicit limits (depth, node count,
+ * component cycles) and marks conditional/map branches as dynamic; anything outside the
+ * bounded subset is omitted rather than guessed.
+ */
+
+import { asNode, nodeArray, unwrapExpression, type AstNode } from "../ast/node.ts";
+import type { ModuleGraph } from "../module-graph.ts";
+import type { PagePreview, PagePreviewNode } from "../types-graph.ts";
+import { jsxTextFields, type JsxTextFields } from "./jsx-text.ts";
+import {
+  elementName,
+  jsxAttributeValue,
+  jsxAttributes,
+  jsxChildren,
+  jsxElementValue,
+} from "./jsx.ts";
+import {
+  canExpand,
+  componentExpression,
+  firstComponentName,
+  lineRef,
+  resolveComponent,
+  returnedExpression,
+} from "./screen-components.ts";
+import { planIntrinsic } from "./screen-intrinsics.ts";
+
+const MAX_NODES = 60;
+/**
+ * Content intrinsics spend their own smaller budget, so a copy-heavy page cannot displace the
+ * structural nodes (sections/components) the preview already drew before content facts existed.
+ */
+const MAX_CONTENT_NODES = 30;
+const MAX_DEPTH = 4;
+
+/** A route element, its source file and the child route that replaces its <Outlet>. */
+export interface PreviewRoot {
+  readonly element: AstNode;
+  readonly originFile: string;
+  readonly outletChild: PreviewRoot | null;
+}
+
+export interface PagePreviewInput {
+  readonly graph: ModuleGraph;
+  readonly pagePath: string;
+  /** Route-table chain for this page; null for an unrouted page. */
+  readonly root: PreviewRoot | null;
+  /** Component name used when the page is not reached through the route table. */
+  readonly pageName: string | null;
+  readonly routePaths: readonly string[];
+}
+
+/** Build the bounded static structure for one page. */
+export function buildPagePreview(input: PagePreviewInput): PagePreview {
+  const { graph, pagePath } = input;
+  const nodes: PagePreviewNode[] = [];
+  const active = new Set<string>();
+  let truncated = false;
+  let structuralNodes = 0;
+  let contentNodes = 0;
+
+  const addNode = (
+    parentId: string | null,
+    name: string,
+    kind: PagePreviewNode["kind"],
+    file: string | null,
+    source: PagePreviewNode["source"],
+    dynamic: boolean,
+    text?: JsxTextFields,
+    content = false,
+  ): string | null => {
+    if (content ? contentNodes >= MAX_CONTENT_NODES : structuralNodes >= MAX_NODES) {
+      truncated = true;
+      return null;
+    }
+    if (content) contentNodes += 1;
+    else structuralNodes += 1;
+    const id = "p" + nodes.length;
+    nodes.push({ id, parentId, name, kind, file, source, dynamic, ...text });
+    return id;
+  };
+
+  const appendChildren = (
+    node: AstNode,
+    originFile: string,
+    parentId: string | null,
+    depth: number,
+    dynamic: boolean,
+    outletChild: PreviewRoot | null,
+  ): void => {
+    for (const child of jsxChildren(node)) {
+      if (child.type === "JSXExpressionContainer") {
+        appendExpression(
+          asNode(child.expression),
+          originFile,
+          parentId,
+          depth,
+          dynamic,
+          outletChild,
+        );
+      } else if (child.type === "JSXElement" || child.type === "JSXFragment") {
+        appendJsx(child, originFile, parentId, depth, dynamic, outletChild);
+      }
+    }
+  };
+
+  const appendJsx = (
+    node: AstNode,
+    originFile: string,
+    parentId: string | null,
+    depth: number,
+    dynamic: boolean,
+    outletChild: PreviewRoot | null,
+  ): void => {
+    if (node.type === "JSXFragment") {
+      appendChildren(node, originFile, parentId, depth, dynamic, outletChild);
+      return;
+    }
+    const name = elementName(node);
+    if (name === null) return;
+    if (name === "Outlet") {
+      if (outletChild !== null) {
+        appendRoot(outletChild, parentId, depth, dynamic);
+        return;
+      }
+      addNode(
+        parentId,
+        "Outlet",
+        "slot",
+        null,
+        lineRef(graph, originFile, node),
+        dynamic,
+        jsxTextFields(node),
+      );
+      return;
+    }
+    const intrinsic = name[0] !== undefined && name[0] === name[0].toLowerCase();
+    if (intrinsic) {
+      const plan = planIntrinsic(node, name);
+      if (plan === null) {
+        appendChildren(node, originFile, parentId, depth, dynamic, outletChild);
+        return;
+      }
+      const id = addNode(
+        parentId,
+        name,
+        "intrinsic",
+        null,
+        lineRef(graph, originFile, node),
+        dynamic,
+        plan.fields,
+        plan.content,
+      );
+      if (id !== null) appendChildren(node, originFile, id, depth + 1, dynamic, outletChild);
+      return;
+    }
+    const ref = resolveComponent(graph, originFile, name);
+    const id = addNode(
+      parentId,
+      name,
+      "component",
+      ref?.file ?? null,
+      lineRef(graph, originFile, node),
+      dynamic,
+      jsxTextFields(node),
+    );
+    if (id === null) return;
+    // JSX-valued props are real sections too (AuthShell footer, Page actions, ...).
+    for (const attribute of jsxAttributes(node)) {
+      if (attribute.type !== "JSXAttribute") continue;
+      const value = jsxElementValue(jsxAttributeValue(attribute));
+      if (value === undefined) continue;
+      const attributeName = asNode(attribute.name);
+      const slotName =
+        attributeName !== undefined && typeof attributeName.name === "string"
+          ? attributeName.name
+          : "slot";
+      const slotId = addNode(id, slotName, "slot", null, lineRef(graph, originFile, node), dynamic);
+      if (slotId !== null) appendJsx(value, originFile, slotId, depth + 1, dynamic, null);
+    }
+    // The component's own JSX children are its content slot; keep them visible even when the
+    // component definition is expanded (its `{children}` expression is not JSX we can splice).
+    appendChildren(node, originFile, id, depth + 1, dynamic, null);
+    const expand = ref !== null && canExpand(ref.file) && depth < MAX_DEPTH;
+    if (!expand) return;
+    const key = ref.file + "#" + ref.name;
+    const expression = active.has(key) ? undefined : componentExpression(graph, ref.file, ref.name);
+    if (expression === undefined) return;
+    active.add(key);
+    appendExpression(expression, ref.file, id, depth + 1, dynamic, outletChild);
+    active.delete(key);
+  };
+
+  const appendExpression = (
+    node: AstNode | undefined,
+    originFile: string,
+    parentId: string | null,
+    depth: number,
+    dynamic: boolean,
+    outletChild: PreviewRoot | null,
+  ): void => {
+    if (node === undefined) return;
+    const expression = unwrapExpression(node) ?? node;
+    if (expression.type === "JSXElement" || expression.type === "JSXFragment") {
+      appendJsx(expression, originFile, parentId, depth, dynamic, outletChild);
+      return;
+    }
+    if (expression.type === "ConditionalExpression") {
+      appendExpression(
+        asNode(expression.consequent),
+        originFile,
+        parentId,
+        depth,
+        true,
+        outletChild,
+      );
+      appendExpression(
+        asNode(expression.alternate),
+        originFile,
+        parentId,
+        depth,
+        true,
+        outletChild,
+      );
+      return;
+    }
+    if (expression.type === "LogicalExpression") {
+      appendExpression(asNode(expression.right), originFile, parentId, depth, true, outletChild);
+      return;
+    }
+    if (expression.type === "ArrayExpression") {
+      for (const element of nodeArray(expression, "elements")) {
+        appendExpression(element, originFile, parentId, depth, dynamic, outletChild);
+      }
+      return;
+    }
+    if (expression.type === "CallExpression") {
+      const callee = asNode(expression.callee);
+      const property =
+        callee === undefined || callee.type !== "MemberExpression"
+          ? undefined
+          : asNode(callee.property);
+      if (property !== undefined && typeof property.name === "string" && property.name === "map") {
+        const callback = nodeArray(expression, "arguments")[0];
+        const body = callback === undefined ? undefined : asNode(callback.body);
+        const returned =
+          body === undefined
+            ? undefined
+            : body.type === "BlockStatement"
+              ? returnedExpression(body)
+              : body;
+        appendExpression(returned, originFile, parentId, depth, true, outletChild);
+      }
+    }
+  };
+
+  const appendRoot = (
+    root: PreviewRoot | null,
+    parentId: string | null,
+    depth: number,
+    dynamic: boolean,
+  ): void => {
+    if (root === null) return;
+    appendExpression(root.element, root.originFile, parentId, depth, dynamic, root.outletChild);
+  };
+
+  if (input.root !== null) {
+    appendRoot(input.root, null, 0, false);
+  } else if (input.pageName !== null) {
+    const file = graph.file(pagePath);
+    if (file !== undefined) {
+      const id = addNode(
+        null,
+        input.pageName,
+        "component",
+        pagePath,
+        lineRef(graph, pagePath, file.program),
+        false,
+      );
+      const expression =
+        id === null ? undefined : componentExpression(graph, pagePath, input.pageName);
+      if (id !== null && expression !== undefined)
+        appendExpression(expression, pagePath, id, 1, false, null);
+    }
+  }
+
+  return { routePaths: input.routePaths, nodes, truncated };
+}
+
+export function pageComponentName(graph: ModuleGraph, pagePath: string): string | null {
+  return firstComponentName(graph, pagePath);
+}

package/src/passes/screens.ts

@@ -0,0 +1,291 @@
+/**
+ * Static screen facts for the project graph: route-table paths, a bounded component preview
+ * per page and explicit page-to-page navigation links.
+ *
+ * Only explicit client navigation counts (react-router `Link`, `NavLink`, `useNavigate`).
+ * Guards and `<Navigate>` redirects are intentionally out of scope for the graph: they are
+ * conditional control flow, not a link the page declares.
+ */
+
+import { asNode, nodeArray, unwrapExpression, type AstNode } from "../ast/node.ts";
+import { walk } from "../ast/walk.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import { evaluateStatic } from "../static-eval.ts";
+import type { PageFact, PageLink, PagePreview, ScreenFacts } from "../types.ts";
+import { elementName, jsxAttribute, jsxAttributeValue } from "./jsx.ts";
+import { buildRouteTable, type RouteEntry } from "./route-table.ts";
+import { buildPagePreview, pageComponentName, type PreviewRoot } from "./screen-preview.ts";
+
+function resolvePage(graph: ModuleGraph, originFile: string, name: string): string | null {
+  const local = name.includes(".") ? name.slice(0, name.indexOf(".")) : name;
+  const binding = graph.resolveBinding(originFile, local);
+  if (binding === null) return null;
+  const file = graph.file(binding.file);
+  return file !== undefined && file.path.startsWith("src/pages/") ? file.path : null;
+}
+
+/** First component in a route element that resolves to a file under src/pages/. */
+function pagePathOfElement(
+  graph: ModuleGraph,
+  originFile: string,
+  element: AstNode,
+): string | null {
+  let found: string | null = null;
+  walk(element, (node) => {
+    if (found !== null || node.type !== "JSXElement") return;
+    const name = elementName(node);
+    if (name === null || name[0] === name[0]?.toLowerCase()) return;
+    found = resolvePage(graph, originFile, name);
+  });
+  return found;
+}
+
+function appFileOf(graph: ModuleGraph): ProjectFile | null {
+  const direct = graph.file("src/app.tsx");
+  if (direct !== undefined) return direct;
+  for (const file of graph.files.values()) {
+    if (!file.path.startsWith("src/")) continue;
+    if (buildRouteTable(graph, file).length > 0) return file;
+  }
+  return null;
+}
+
+/** Only page/layout/app components own page links; providers and guards are shared chrome. */
+function isLinkSourceFile(file: string): boolean {
+  if (file.startsWith("src/components/ui/")) return false;
+  return (
+    file.startsWith("src/pages/") ||
+    file.startsWith("src/layouts/") ||
+    file.startsWith("src/components/")
+  );
+}
+
+interface PageRoute {
+  readonly index: number;
+  readonly path: string;
+}
+
+function routesByPage(
+  graph: ModuleGraph,
+  appFile: ProjectFile,
+  entries: readonly RouteEntry[],
+): Map<string, PageRoute[]> {
+  const byPage = new Map<string, PageRoute[]>();
+  entries.forEach((entry, index) => {
+    if (entry.element === null) return;
+    const pagePath = pagePathOfElement(graph, appFile.path, entry.element);
+    if (pagePath === null) return;
+    const list = byPage.get(pagePath) ?? [];
+    list.push({ index, path: entry.path });
+    byPage.set(pagePath, list);
+  });
+  return byPage;
+}
+
+function previewRoot(
+  entries: readonly RouteEntry[],
+  pageEntry: number,
+  appPath: string,
+): PreviewRoot | null {
+  let root: PreviewRoot | null = null;
+  let current: number | null = pageEntry;
+  while (current !== null) {
+    const entry: RouteEntry | undefined = entries[current];
+    if (entry === undefined) break;
+    if (entry.element !== null) {
+      root = { element: entry.element, originFile: appPath, outletChild: root };
+    }
+    current = entry.parentIndex;
+  }
+  return root;
+}
+
+function pathSegments(path: string): string[] {
+  return path.split("/").filter(Boolean);
+}
+
+function pathMatches(pattern: string, target: string): boolean {
+  if (pattern === target) return true;
+  if (pattern === "*") return false;
+  const patternParts = pathSegments(pattern);
+  const targetParts = pathSegments(target);
+  if (patternParts.length !== targetParts.length) return false;
+  return patternParts.every((part, index) => {
+    if (part === "*") return true;
+    if (part.startsWith(":") || (part.startsWith("{") && part.endsWith("}"))) return true;
+    return part === targetParts[index];
+  });
+}
+
+function targetPathOf(
+  node: AstNode | undefined,
+  graph: ModuleGraph,
+  file: ProjectFile,
+): string | null {
+  if (node === undefined) return null;
+  const evaluated = evaluateStatic(node, { graph, file: file.path });
+  if (!evaluated.ok) return null;
+  const value = evaluated.value;
+  if (typeof value === "string") return value;
+  if (typeof value === "object" && value !== null && "pathname" in value) {
+    const pathname = (value as { pathname?: unknown }).pathname;
+    return typeof pathname === "string" ? pathname : null;
+  }
+  return null;
+}
+
+function stripLocation(path: string): string {
+  const cut = path.search(/[?#]/);
+  return cut === -1 ? path : path.slice(0, cut);
+}
+
+interface LinkBindings {
+  readonly links: ReadonlyMap<string, "link" | "navlink">;
+  readonly navigate: ReadonlySet<string>;
+}
+
+function linkBindings(file: ProjectFile): LinkBindings {
+  const links = new Map<string, "link" | "navlink">();
+  const useNavigate = new Set<string>();
+  for (const imported of file.module.imports) {
+    if (imported.specifier !== "react-router-dom") continue;
+    if (imported.imported === "Link") links.set(imported.local, "link");
+    if (imported.imported === "NavLink") links.set(imported.local, "navlink");
+    if (imported.imported === "useNavigate") useNavigate.add(imported.local);
+  }
+  const navigate = new Set<string>();
+  if (useNavigate.size === 0) return { links, navigate };
+  walk(file.program, (node) => {
+    if (node.type !== "VariableDeclarator") return;
+    const id = asNode(node.id);
+    const init = unwrapExpression(asNode(node.init));
+    if (id === undefined || typeof id.name !== "string" || init === undefined) return;
+    if (init.type !== "CallExpression") return;
+    const callee = unwrapExpression(init.callee);
+    if (
+      callee?.type === "Identifier" &&
+      useNavigate.has(typeof callee.name === "string" ? callee.name : "")
+    ) {
+      navigate.add(id.name);
+    }
+  });
+  return { links, navigate };
+}
+
+function linksInFile(
+  graph: ModuleGraph,
+  file: ProjectFile,
+): { to: string; kind: "link" | "navlink" | "navigate"; source: { file: string; line: number } }[] {
+  const bindings = linkBindings(file);
+  if (bindings.links.size === 0 && bindings.navigate.size === 0) return [];
+  const found: {
+    to: string;
+    kind: "link" | "navlink" | "navigate";
+    source: { file: string; line: number };
+  }[] = [];
+  walk(file.program, (node) => {
+    if (node.type === "JSXElement") {
+      const name = elementName(node);
+      const kind = name === null ? undefined : bindings.links.get(name);
+      if (kind === undefined) return;
+      const value = jsxAttributeValue(jsxAttribute(node, "to"));
+      const to = targetPathOf(value, graph, file);
+      if (to !== null) {
+        found.push({ to, kind, source: lineOf(file, node) });
+      }
+      return;
+    }
+    if (node.type !== "CallExpression") return;
+    const callee = unwrapExpression(node.callee);
+    if (callee?.type !== "Identifier" || typeof callee.name !== "string") return;
+    if (!bindings.navigate.has(callee.name)) return;
+    const to = targetPathOf(nodeArray(node, "arguments")[0], graph, file);
+    if (to !== null) found.push({ to, kind: "navigate", source: lineOf(file, node) });
+  });
+  return found;
+}
+
+function lineOf(file: ProjectFile, node: AstNode): { file: string; line: number } {
+  const offset = typeof node.start === "number" ? node.start : 0;
+  let line = 1;
+  for (let index = 0; index < offset && index < file.source.length; index += 1) {
+    if (file.source.charCodeAt(index) === 10) line += 1;
+  }
+  return { file: file.path, line };
+}
+
+/** Build route paths, page previews and explicit page links from the project snapshot. */
+export function buildScreens(graph: ModuleGraph, pages: readonly PageFact[]): ScreenFacts {
+  const appFile = appFileOf(graph);
+  const entries = appFile === null ? [] : buildRouteTable(graph, appFile);
+  const byPage =
+    appFile === null ? new Map<string, PageRoute[]>() : routesByPage(graph, appFile, entries);
+  const pathToPage = new Map<string, string>();
+  for (const entry of entries) {
+    if (entry.element === null || appFile === null) continue;
+    const pagePath = pagePathOfElement(graph, appFile.path, entry.element);
+    if (pagePath !== null && !pathToPage.has(entry.path)) pathToPage.set(entry.path, pagePath);
+  }
+  const resolveTarget = (target: string): string | null => {
+    const path = stripLocation(target);
+    if (!path.startsWith("/") && path !== "*") return null;
+    const exact = pathToPage.get(path);
+    if (exact !== undefined) return exact;
+    for (const entry of entries) {
+      if (!pathMatches(entry.path, path)) continue;
+      if (entry.element === null || appFile === null) continue;
+      const pagePath = pagePathOfElement(graph, appFile.path, entry.element);
+      if (pagePath !== null) return pagePath;
+    }
+    return null;
+  };
+
+  const previews: Record<string, PagePreview> = {};
+  for (const page of pages) {
+    if (page.kind !== "page") continue;
+    const pageRoutes = byPage.get(page.path) ?? [];
+    const first = pageRoutes[0];
+    const root =
+      appFile === null || first === undefined
+        ? null
+        : previewRoot(entries, first.index, appFile.path);
+    previews[page.path] = buildPagePreview({
+      graph,
+      pagePath: page.path,
+      root,
+      pageName: root === null ? pageComponentName(graph, page.path) : null,
+      routePaths: pageRoutes.map((entry) => entry.path),
+    });
+  }
+
+  const links: PageLink[] = [];
+  const seen = new Set<string>();
+  for (const page of pages) {
+    if (page.kind !== "page") continue;
+    const preview = previews[page.path];
+    const files = new Set<string>([page.path]);
+    for (const node of preview?.nodes ?? []) {
+      if (node.file !== null && isLinkSourceFile(node.file)) files.add(node.file);
+    }
+    for (const filePath of files) {
+      const file = graph.file(filePath);
+      if (file === undefined) continue;
+      for (const link of linksInFile(graph, file)) {
+        const target = resolveTarget(link.to);
+        if (target === null || target === page.path) continue;
+        const key = page.path + "\u0000" + target + "\u0000" + link.kind + "\u0000" + link.to;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        links.push({
+          from: page.path,
+          to: target,
+          toPath: stripLocation(link.to),
+          kind: link.kind,
+          source: link.source,
+        });
+      }
+    }
+  }
+
+  return { previews, links };
+}