@topogram/cli 0.3.63 → 0.3.65

package/src/import/core/shared/next-app.js

@@ -0,0 +1,389 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { relativeTo } from "../../../path-helpers.js";
+import { canonicalCandidateTerm, idHintify } from "./candidates.js";
+import { listFilesRecursive, readTextIfExists } from "./files.js";
+import {
+  inferApiCapabilityIdFromOperation,
+  inferRouteCapabilityId,
+  normalizeEndpointPathForMatch,
+  normalizeOpenApiPath
+} from "./api-routes.js";
+import { entityIdForRoute, screenIdForRoute, screenKindForRoute, uiCapabilityHintsForRoute } from "./ui-routes.js";
+
+/**
+ * @param {string} rootDir
+ * @returns {any}
+ */
+export function inferNextAppRoutes(rootDir) {
+  const appDir = path.join(rootDir, "app");
+  if (!fs.existsSync(appDir)) return [];
+  const routeFiles = listFilesRecursive(
+    appDir,
+    /** @param {any} child */ (child) => /\/page\.(tsx|ts|jsx|js|mdx)$/.test(child) || /\/route\.(tsx|ts|jsx|js)$/.test(child)
+  );
+  const routes = [];
+  for (const filePath of routeFiles) {
+    const relative = relativeTo(appDir, filePath);
+    const isPage = /\/page\.(tsx|ts|jsx|js|mdx)$/.test(`/${relative}`) || /^page\.(tsx|ts|jsx|js|mdx)$/.test(relative);
+    const normalizedPath = `/${relative}`
+      .replace(/\/page\.(tsx|ts|jsx|js|mdx)$/, "")
+      .replace(/\/route\.(tsx|ts|jsx|js)$/, "")
+      .replace(/\[(\.\.\.)?([^\]]+)\]/g, /** @param {any} _m @param {any} catchAll @param {any} name */ (_m, catchAll, name) => catchAll ? `:${name}*` : `:${name}`)
+      .replace(/\/index$/, "")
+      .replace(/^\/$/, "/");
+    routes.push({
+      path: normalizedPath === "" ? "/" : normalizedPath,
+      kind: isPage ? "page" : "route",
+      file: filePath
+    });
+  }
+  return routes.sort(/** @param {any} a @param {any} b */ (a, b) => a.path.localeCompare(b.path) || a.kind.localeCompare(b.kind));
+}
+
+/**
+ * @param {string} routePath
+ * @returns {any}
+ */
+export function nextScreenKindForRoute(routePath) {
+  const normalized = String(routePath || "");
+  if (/\/(login|register|setup)$/.test(normalized)) return "flow";
+  return screenKindForRoute(routePath);
+}
+
+/**
+ * @param {string} routePath
+ * @returns {any}
+ */
+export function nextScreenIdForRoute(routePath) {
+  const normalized = String(routePath || "");
+  if (normalized === "/") return "home";
+  if (/\/login$/.test(normalized)) return "login";
+  if (/\/register$/.test(normalized)) return "register";
+  if (/\/setup$/.test(normalized)) return "setup";
+  return screenIdForRoute(routePath);
+}
+
+/**
+ * @param {string} routePath
+ * @returns {any}
+ */
+export function entityIdForNextRoute(routePath) {
+  const normalized = String(routePath || "");
+  if (/^\/posts(\/|$)/.test(normalized)) return "entity_post";
+  if (/^\/users(\/|$)/.test(normalized)) return "entity_user";
+  return null;
+}
+
+/**
+ * @param {string} routePath
+ * @returns {any}
+ */
+export function conceptIdForNextRoute(routePath) {
+  const normalized = String(routePath || "");
+  if (normalized === "/") return "surface_home";
+  if (/\/login$/.test(normalized)) return "flow_login";
+  if (/\/register$/.test(normalized)) return "flow_register";
+  if (/\/setup$/.test(normalized)) return "flow_setup";
+  return entityIdForNextRoute(routePath) || entityIdForRoute(routePath);
+}
+
+/**
+ * @param {string} routePath
+ * @returns {any}
+ */
+export function uiCapabilityHintsForNextRoute(routePath) {
+  const normalized = String(routePath || "");
+  if (normalized === "/") return { load: null, submit: null, primary_action: null };
+  if (/\/login$/.test(normalized)) return { load: null, submit: "cap_sign_in_user", primary_action: "cap_sign_in_user" };
+  if (/\/register$/.test(normalized)) return { load: null, submit: "cap_register_user", primary_action: "cap_register_user" };
+  if (/\/setup$/.test(normalized)) return { load: null, submit: null, primary_action: null };
+  if (/^\/posts\/new$/.test(normalized)) return { load: null, submit: "cap_create_post", primary_action: "cap_create_post" };
+  if (/^\/posts\/:id$/.test(normalized) || /^\/posts\/:[^/]+$/.test(normalized)) return { load: "cap_get_post", submit: null, primary_action: "cap_update_post" };
+  if (/^\/posts$/.test(normalized)) return { load: "cap_list_posts", submit: null, primary_action: "cap_create_post" };
+  if (/^\/users\/new$/.test(normalized)) return { load: null, submit: "cap_create_user", primary_action: "cap_create_user" };
+  return uiCapabilityHintsForRoute(routePath);
+}
+
+/**
+ * @param {string} text
+ * @returns {any}
+ */
+export function inferRouteQueryParams(text) {
+  const params = new Set();
+  for (const match of String(text || "").matchAll(/\bquery\s*\(\s*["'`]([^"'`]+)["'`]\s*\)/g)) params.add(match[1]);
+  for (const match of String(text || "").matchAll(/\bquery\.([A-Za-z_][A-Za-z0-9_]*)\b/g)) params.add(match[1]);
+  return [...params].sort();
+}
+
+/**
+ * @param {string} routeArguments
+ * @param {string} handlerContext
+ * @returns {any}
+ */
+export function inferRouteAuthHint(routeArguments, handlerContext) {
+  const combined = `${routeArguments || ""}\n${handlerContext || ""}`.toLowerCase();
+  if (/\b(signin|sign_in|login|register|credentialsprovider)\b/.test(combined)) {
+    return "public";
+  }
+  return /\b(auth|session|permission|guard|protected|require_auth|requireauth|ensureauth)\b/.test(combined)
+    ? "secured"
+    : "unknown";
+}
+
+/**
+ * @param {string} text
+ * @param {string} exportName
+ * @returns {any}
+ */
+export function extractNamedExportBlock(text, exportName) {
+  const escapedName = exportName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = text.match(new RegExp(`export\\s+async\\s+function\\s+${escapedName}\\s*\\([^)]*\\)\\s*\\{([\\s\\S]{0,2000}?)\\n\\}`, "m"));
+  return match ? match[1] : "";
+}
+
+/**
+ * @param {string} text
+ * @returns {any}
+ */
+export function inferNextRequestSearchParams(text) {
+  const params = new Set();
+  for (const match of String(text || "").matchAll(/searchParams\.get\(\s*["'`]([^"'`]+)["'`]\s*\)/g)) {
+    params.add(match[1]);
+  }
+  return [...params].sort();
+}
+
+/**
+ * @param {string} text
+ * @returns {any}
+ */
+export function inferNextJsonFields(text) {
+  const fields = new Set();
+  for (const match of String(text || "").matchAll(/NextResponse\.json\(\s*\{([\s\S]{0,400}?)\}\s*\)/g)) {
+    for (const fieldMatch of match[1].matchAll(/\b([A-Za-z_][A-Za-z0-9_]*)\b\s*[:,]/g)) {
+      fields.add(fieldMatch[1]);
+    }
+  }
+  return [...fields].sort();
+}
+
+/**
+ * @param {string} text
+ * @param {string} handlerName
+ * @returns {any}
+ */
+export function extractHandlerContext(text, handlerName) {
+  if (!handlerName) return "";
+  const escapedName = handlerName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const patterns = [
+    new RegExp(`function\\s+${escapedName}\\s*\\([^)]*\\)\\s*\\{([\\s\\S]{0,1200}?)\\n\\}`, "m"),
+    new RegExp(`const\\s+${escapedName}\\s*=\\s*(?:async\\s*)?\\([^)]*\\)\\s*=>\\s*\\{([\\s\\S]{0,1200}?)\\n\\}`, "m")
+  ];
+  for (const pattern of patterns) {
+    const match = text.match(pattern);
+    if (match) return match[1];
+  }
+  return "";
+}
+
+/**
+ * @param {string} appRoot
+ * @param {string} filePath
+ * @returns {any}
+ */
+export function nextAppRoutePathFromFile(appRoot, filePath) {
+  const relative = relativeTo(appRoot, filePath);
+  return `/${relative}`
+    .replace(/\/actions\.(tsx|ts|jsx|js)$/, "")
+    .replace(/\/page\.(tsx|ts|jsx|js|mdx)$/, "")
+    .replace(/\[(\.\.\.)?([^\]]+)\]/g, /** @param {any} _match @param {any} catchAll @param {any} name */ (_match, catchAll, name) => catchAll ? `:${name}*` : `:${name}`)
+    .replace(/\/index$/, "")
+    .replace(/^\/$/, "/") || "/";
+}
+
+/**
+ * @param {string} text
+ * @returns {any}
+ */
+export function inferFormDataFields(text) {
+  const fields = new Set();
+  for (const match of String(text || "").matchAll(/formData\.get\(\s*["'`]([^"'`]+)["'`]\s*\)/g)) {
+    fields.add(match[1]);
+  }
+  return [...fields].sort();
+}
+
+/**
+ * @param {string} text
+ * @returns {any}
+ */
+export function inferInputNames(text) {
+  const fields = new Set();
+  for (const match of String(text || "").matchAll(/\bname=["'`]([^"'`]+)["'`]/g)) {
+    fields.add(match[1]);
+  }
+  return [...fields].sort();
+}
+
+/**
+ * @param {string} workspaceRoot
+ * @param {import("./types.d.ts").ImportReadHelpers} helpers
+ * @returns {any}
+ */
+export function inferNextApiRoutes(workspaceRoot, helpers = { readTextIfExists }) {
+  const apiRoot = path.join(workspaceRoot, "app", "api");
+  if (!fs.existsSync(apiRoot)) return [];
+  const routeFiles = listFilesRecursive(
+    apiRoot,
+    /** @param {any} child */ (child) => /\/route\.(tsx|ts|jsx|js)$/.test(child) || /^route\.(tsx|ts|jsx|js)$/.test(path.basename(child))
+  );
+  const routes = [];
+  for (const filePath of routeFiles) {
+    const text = helpers.readTextIfExists(filePath) || "";
+    const relative = relativeTo(apiRoot, filePath);
+    const routePath = `/${relative}`
+      .replace(/\/route\.(tsx|ts|jsx|js)$/, "")
+      .replace(/\[(\.\.\.)?([^\]]+)\]/g, /** @param {any} _match @param {any} catchAll @param {any} name */ (_match, catchAll, name) => catchAll ? `:${name}*` : `:${name}`);
+    for (const match of text.matchAll(/export\s+async\s+function\s+(GET|POST|PUT|PATCH|DELETE)\s*\(([^)]*)\)/g)) {
+      const method = match[1].toUpperCase();
+      const handlerContext = extractNamedExportBlock(text, match[1]) || "";
+      routes.push({
+        file: filePath,
+        method,
+        path: routePath === "" ? "/" : routePath,
+        handler_hint: match[1].toLowerCase(),
+        path_params: [...normalizeOpenApiPath(routePath).matchAll(/\{([^}]+)\}/g)].map(/** @param {any} entry */ (entry) => entry[1]),
+        query_params: inferNextRequestSearchParams(handlerContext),
+        output_fields: inferNextJsonFields(handlerContext),
+        auth_hint: inferRouteAuthHint(match[0], handlerContext),
+        source_kind: "route_code"
+      });
+    }
+  }
+  return routes;
+}
+
+/**
+ * @param {import("./types.d.ts").ImportRouteRecord} record
+ * @returns {any}
+ */
+export function inferCapabilityEntityId(record) {
+  if (record.entity_id) {
+    return record.entity_id;
+  }
+  const pathSegments = normalizeEndpointPathForMatch(record.endpoint?.path || "")
+    .split("/")
+    .filter(Boolean)
+    .filter(/** @param {any} segment */ (segment) => segment !== "{}");
+  const resourceSegment = pathSegments[0] || String(record.id_hint || "").replace(/^cap_(create|update|delete|get|list)_/, "");
+  return `entity_${idHintify(canonicalCandidateTerm(resourceSegment))}`;
+}
+
+/**
+ * @param {string} workspaceRoot
+ * @param {import("./types.d.ts").ImportReadHelpers} helpers
+ * @returns {any}
+ */
+export function inferNextServerActionCapabilities(workspaceRoot, helpers = { readTextIfExists }) {
+  const appRoot = path.join(workspaceRoot, "app");
+  if (!fs.existsSync(appRoot)) return [];
+  const actionFiles = listFilesRecursive(
+    appRoot,
+    /** @param {any} child */ (child) =>
+      /\/actions\.(tsx|ts|jsx|js)$/.test(child) ||
+      /\/page\.(tsx|ts|jsx|js|mdx)$/.test(child) ||
+      /^page\.(tsx|ts|jsx|js|mdx)$/.test(path.basename(child))
+  );
+  const capabilities = [];
+  for (const filePath of actionFiles) {
+    const text = helpers.readTextIfExists(filePath) || "";
+    const routePath = nextAppRoutePathFromFile(appRoot, filePath);
+    for (const match of text.matchAll(/(?:export\s+)?async\s+function\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(([^)]*)\)\s*\{([\s\S]{0,2400}?)\n\}/g)) {
+      const functionName = match[1];
+      const body = match[3] || "";
+      const trimmedBody = body.trimStart();
+      const isServerAction =
+        /\/actions\.(tsx|ts|jsx|js)$/.test(filePath) ||
+        trimmedBody.startsWith('"use server"') ||
+        trimmedBody.startsWith("'use server'");
+      if (!isServerAction) continue;
+      const routeLike = {
+        file: filePath,
+        method: "POST",
+        path: routePath,
+        handler_hint: functionName,
+        auth_hint: inferRouteAuthHint(functionName, body)
+      };
+      const idHint = inferRouteCapabilityId(routeLike);
+      capabilities.push({
+        file: filePath,
+        function_name: functionName,
+        method: "POST",
+        path: routePath,
+        id_hint: idHint,
+        input_fields: inferFormDataFields(body),
+        output_fields: [],
+        path_params: [...normalizeOpenApiPath(routePath).matchAll(/\{([^}]+)\}/g)].map(/** @param {any} entry */ (entry) => entry[1]),
+        auth_hint: routeLike.auth_hint,
+        entity_id: inferCapabilityEntityId({ endpoint: { path: routePath }, id_hint: idHint }),
+        source_kind: "route_code"
+      });
+    }
+  }
+  return capabilities.sort(/** @param {any} a @param {any} b */ (a, b) => a.id_hint.localeCompare(b.id_hint) || a.path.localeCompare(b.path));
+}
+
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {import("./types.d.ts").ImportReadHelpers} helpers
+ * @returns {any}
+ */
+export function inferNextAuthCapabilities(paths, helpers = { readTextIfExists }) {
+  const authConfigPath = path.join(paths.workspaceRoot, "auth.ts");
+  const authConfigText = helpers.readTextIfExists(authConfigPath) || "";
+  const hasCredentialsProvider = /CredentialsProvider\s*\(/.test(authConfigText);
+  const createsUserOnAuthorize = /prisma\.user\.create\s*\(/.test(authConfigText);
+  const pages = [
+    {
+      file: path.join(paths.workspaceRoot, "app", "login", "page.tsx"),
+      path: "/login",
+      id_hint: "cap_sign_in_user",
+      label: "Sign In User",
+      target_state: "authenticated"
+    },
+    {
+      file: path.join(paths.workspaceRoot, "app", "register", "page.tsx"),
+      path: "/register",
+      id_hint: "cap_register_user",
+      label: "Register User",
+      target_state: createsUserOnAuthorize ? "registered" : "created"
+    }
+  ];
+  const capabilities = [];
+  for (const page of pages) {
+    const text = helpers.readTextIfExists(page.file) || "";
+    if (!text || !/signIn\(\s*["'`]credentials["'`]/.test(text)) continue;
+    capabilities.push({
+      file: page.file,
+      function_name: page.id_hint.replace(/^cap_/, ""),
+      method: "POST",
+      path: page.path,
+      id_hint: page.id_hint,
+      label: page.label,
+      input_fields: inferInputNames(text),
+      output_fields: [],
+      path_params: [],
+      auth_hint: "public",
+      entity_id: "entity_user",
+      target_state: page.target_state,
+      provenance: [
+        relativeTo(paths.repoRoot, page.file),
+        ...(hasCredentialsProvider ? [relativeTo(paths.repoRoot, authConfigPath)] : [])
+      ],
+      source_kind: "route_code"
+    });
+  }
+  return capabilities.sort(/** @param {any} a @param {any} b */ (a, b) => a.id_hint.localeCompare(b.id_hint));
+}

package/src/import/core/shared/types.d.ts

@@ -0,0 +1,51 @@
+export type ImportPaths = {
+  repoRoot: string;
+  workspaceRoot: string;
+  topogramRoot: string;
+  [key: string]: any;
+};
+
+export type ImportReadHelpers = {
+  readTextIfExists(filePath: string): string | null;
+  [key: string]: any;
+};
+
+export type ImportRouteRecord = {
+  endpoint?: {
+    path?: string;
+  };
+  path?: string;
+  method?: string;
+  handler_hint?: string;
+  id_hint?: string;
+  entity_id?: string | null;
+  auth_hint?: string;
+  tags?: string[];
+  [key: string]: any;
+};
+
+export type ImportCandidateRecord = {
+  kind: string;
+  id?: string;
+  id_hint?: string;
+  idHint?: string;
+  label: string;
+  confidence?: string;
+  source_kind?: string;
+  source_of_truth?: string;
+  [key: string]: any;
+};
+
+export type NavigationStructure = {
+  hasHeader?: boolean;
+  hasSidebar?: boolean;
+  hasTopbar?: boolean;
+  hasBottomTabs?: boolean;
+  hasTabs?: boolean;
+  hasBreadcrumbs?: boolean;
+  hasCommandPalette?: boolean;
+  hasSegmentedControl?: boolean;
+  hasRail?: boolean;
+  navLinks?: string[];
+  [key: string]: any;
+};

package/src/import/core/shared/ui-routes.js

@@ -0,0 +1,230 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { relativeTo } from "../../../path-helpers.js";
+import { canonicalCandidateTerm } from "./candidates.js";
+import { listFilesRecursive, readTextIfExists } from "./files.js";
+
+/**
+ * @param {string} routePath
+ * @returns {any}
+ */
+export function routeSegments(routePath) {
+  return String(routePath || "")
+    .split("/")
+    .filter(Boolean)
+    .map(/** @param {any} segment */ (segment) => segment.replace(/^:/, ""));
+}
+
+/**
+ * @param {string} routePath
+ * @returns {any}
+ */
+export function screenKindForRoute(routePath) {
+  const normalized = String(routePath || "");
+  const segments = routeSegments(normalized);
+  if (/\/new$/.test(normalized)) return "form";
+  if (/\/:?[A-Za-z0-9_]+\/edit$/.test(normalized)) return "form";
+  if (segments.length >= 2 && !/\/new$/.test(normalized) && !/\/edit$/.test(normalized)) return "detail";
+  return "list";
+}
+
+/**
+ * @param {string} routePath
+ * @returns {any}
+ */
+export function screenIdForRoute(routePath) {
+  const segments = routeSegments(routePath);
+  const resource = canonicalCandidateTerm(segments[0] || "home");
+  const kind = screenKindForRoute(routePath);
+  if (kind === "form" && /\/new$/.test(routePath)) return `${resource}_create`;
+  if (kind === "form" && /\/edit$/.test(routePath)) return `${resource}_edit`;
+  if (kind === "detail") return `${resource}_detail`;
+  return `${resource}_list`;
+}
+
+/**
+ * @param {string} routePath
+ * @returns {any}
+ */
+export function uiCapabilityHintsForRoute(routePath) {
+  const segments = routeSegments(routePath);
+  const resource = canonicalCandidateTerm(segments[0] || "item");
+  const idSegment = segments[1] || null;
+  if (/\/new$/.test(routePath)) {
+    return { load: null, submit: `cap_create_${resource}`, primary_action: `cap_create_${resource}` };
+  }
+  if (/\/edit$/.test(routePath)) {
+    return { load: `cap_get_${resource}`, submit: `cap_update_${resource}`, primary_action: `cap_update_${resource}` };
+  }
+  if (idSegment && !/new|edit/.test(idSegment)) {
+    return { load: `cap_get_${resource}`, submit: null, primary_action: `cap_update_${resource}` };
+  }
+  return { load: `cap_list_${resource}s`, submit: null, primary_action: `cap_create_${resource}` };
+}
+
+/**
+ * @param {string} routePath
+ * @returns {any}
+ */
+export function entityIdForRoute(routePath) {
+  const segments = routeSegments(routePath);
+  return `entity_${canonicalCandidateTerm(segments[0] || "item")}`;
+}
+
+/**
+ * @param {string} rootDir
+ * @returns {any}
+ */
+export function inferReactRoutes(rootDir) {
+  const appPath = path.join(rootDir, "src", "App.tsx");
+  const text = readTextIfExists(appPath);
+  if (!text) return [];
+  const routes = new Set();
+  for (const match of text.matchAll(/path:\s*"([^"]+)"/g)) routes.add(match[1]);
+  for (const match of text.matchAll(/path="([^"]+)"/g)) routes.add(match[1]);
+  return [...routes].sort();
+}
+
+/**
+ * @param {string} rootDir
+ * @returns {any}
+ */
+export function inferSvelteRoutes(rootDir) {
+  const routesRoot = path.join(rootDir, "src", "routes");
+  if (!fs.existsSync(routesRoot)) return [];
+  const files = listFilesRecursive(routesRoot, /** @param {any} child */ (child) => child.endsWith("+page.svelte") || child.endsWith("+page.ts") || child.endsWith("+page.server.ts"));
+  const routes = new Set();
+  for (const filePath of files) {
+    const relative = relativeTo(routesRoot, filePath)
+      .replace(/(^|\/)\+page(\.server|)\.(svelte|ts)$/, "")
+      .replace(/\[(.+?)\]/g, ":$1")
+      .replace(/^$/, "/");
+    routes.add(relative.startsWith("/") ? relative : `/${relative}`);
+  }
+  return [...routes].sort();
+}
+
+/**
+ * @param {string} rootDir
+ * @param {any} options
+ * @returns {any}
+ */
+export function inferNavigationStructure(rootDir, options = {}) {
+  const filePatterns = options.filePatterns || [/(^|\/)App\.(tsx|jsx)$/i, /(^|\/)\+layout\.svelte$/i];
+  const files = listFilesRecursive(rootDir, /** @param {any} filePath */ (filePath) => filePatterns.some(/** @param {any} pattern */ (pattern) => pattern.test(filePath)));
+  const result = /** @type {any} */ ({
+    hasHeader: false,
+    hasSidebar: false,
+    hasTopbar: false,
+    hasBottomTabs: false,
+    hasTabs: false,
+    hasBreadcrumbs: false,
+    hasCommandPalette: false,
+    hasSegmentedControl: false,
+    navLinks: []
+  });
+
+  for (const filePath of files) {
+    const text = readTextIfExists(filePath) || "";
+    if (!text) continue;
+    if (/<header\b|class(Name)?=["'][^"']*(topbar|app-nav|navbar)/i.test(text)) {
+      result.hasHeader = true;
+      result.hasTopbar = true;
+    }
+    if (/<aside\b|class(Name)?=["'][^"']*(sidebar|side-nav|sidenav)/i.test(text)) {
+      result.hasSidebar = true;
+    }
+    if (/\bbottom[-_ ]tabs\b|\bTabBar\b|\bBottomNavigation\b/i.test(text)) {
+      result.hasBottomTabs = true;
+    }
+    if (/breadcrumb/i.test(text)) {
+      result.hasBreadcrumbs = true;
+    }
+    if (/\bcommand palette\b|\bCommandPalette\b/i.test(text)) {
+      result.hasCommandPalette = true;
+    }
+    if (/\bsegmented\b|\bSegmentedControl\b/i.test(text)) {
+      result.hasSegmentedControl = true;
+    }
+    if (/<nav\b|role=["']tablist["']|class(Name)?=["'][^"']*\btabs?\b/i.test(text)) {
+      result.hasTabs = result.hasTabs || /role=["']tablist["']|class(Name)?=["'][^"']*\btabs?\b/i.test(text);
+      for (const match of text.matchAll(/(?:href|to)=["'`]([^"'`]+)["'`]/g)) {
+        result.navLinks.push(match[1]);
+      }
+    }
+  }
+
+  result.navLinks = [...new Set(result.navLinks)].sort();
+  return result;
+}
+
+/**
+ * @param {import("./types.d.ts").NavigationStructure} navigation
+ * @returns {any}
+ */
+export function shellKindFromNavigation(navigation) {
+  if (!navigation) return null;
+  if (navigation.hasBottomTabs) return "bottom_tabs";
+  if (navigation.hasSidebar && navigation.hasHeader) return "split_view";
+  if (navigation.hasSidebar) return "sidebar";
+  if (navigation.hasTopbar || navigation.hasHeader) return "topbar";
+  return null;
+}
+
+/**
+ * @param {import("./types.d.ts").NavigationStructure} navigation
+ * @returns {any}
+ */
+export function navigationPatternsFromStructure(navigation) {
+  const patterns = new Set();
+  if (!navigation) return [];
+  if (navigation.hasTabs) patterns.add("tabs");
+  if (navigation.hasBreadcrumbs) patterns.add("breadcrumbs");
+  if (navigation.hasBottomTabs) patterns.add("bottom_tabs");
+  if (navigation.hasRail) patterns.add("navigation_rail");
+  if (navigation.hasCommandPalette) patterns.add("command_palette");
+  if (navigation.hasSegmentedControl) patterns.add("segmented_control");
+  if (navigation.hasSidebar && navigation.hasHeader) patterns.add("split_view");
+  return [...patterns].sort();
+}
+
+/**
+ * @param {string} rootDir
+ * @returns {any}
+ */
+export function detectUiPresentationFeatures(rootDir) {
+  const files = listFilesRecursive(rootDir, /** @param {any} filePath */ (filePath) => /\.(tsx|ts|jsx|js|svelte|vue|html)$/i.test(filePath));
+  const features = new Set();
+
+  for (const filePath of files) {
+    const text = readTextIfExists(filePath) || "";
+    if (!text) continue;
+    if (/\bDataGrid\b|\bag-grid\b|\bAGGrid\b|\bTanStackTable\b|\breact-data-grid\b|\bmui[-_ ]?datagrid\b/i.test(text)) {
+      features.add("data_grid");
+    }
+    if (/<table\b|react-table/i.test(text)) features.add("table");
+    if (/\b(card|cards|Card)\b/.test(text)) features.add("cards");
+    if (/\bkanban|board\b/i.test(text)) features.add("board");
+    if (/\bcalendar\b/i.test(text)) features.add("calendar");
+    if (/\bgallery\b/i.test(text)) features.add("gallery");
+    if (/\bmodal\b|Dialog|AlertDialog/i.test(text)) features.add("modal");
+    if (/\bdrawer\b|Sheet/i.test(text)) features.add("drawer");
+    if (/\bsheet\b|BottomSheet|ModalBottomSheet/i.test(text)) features.add("sheet");
+    if (/\bBottomSheet\b|\bModalBottomSheet\b/i.test(text)) features.add("bottom_sheet");
+    if (/\bFloatingActionButton\b|\bExtendedFloatingActionButton\b|\bfloating action button\b/i.test(text)) features.add("fab");
+    if (/\bempty state\b|empty-state|No results|No items/i.test(text)) features.add("empty_state");
+    if (/\berror state\b|Something went wrong|error/i.test(text)) features.add("error_state");
+    if (/\bloading\b|skeleton|spinner/i.test(text)) features.add("loading_state");
+    if (/\bbreadcrumb/i.test(text)) features.add("breadcrumbs");
+    if (/\bactivity\b|\btimeline\b|\bcomment/i.test(text)) features.add("activity");
+    if (/\bsettings\b|\bpreferences\b|\bbilling\b|\bsecurity\b/i.test(text)) features.add("settings");
+    if (/\bonboarding\b|\bwizard\b|\bstepper\b/i.test(text)) features.add("wizard");
+    if (/\bpull[-_ ]to[-_ ]refresh\b|SwipeRefresh|refreshable\b/i.test(text)) features.add("pull_to_refresh");
+    if (/\bcommand palette\b|\bCommandPalette\b/i.test(text)) features.add("command_palette");
+    if (/\binspector\b|\bDetailsPane\b|\bproperties pane\b/i.test(text)) features.add("inspector_pane");
+    if (/\bWindowGroup\b|\bBrowserWindow\b|\bmulti[-_ ]window\b/i.test(text)) features.add("multi_window");
+  }
+
+  return [...features].sort();
+}