@elench/testkit 0.1.63 → 0.1.65

package/node_modules/@elench/next-analysis/src/server-actions.mjs

@@ -0,0 +1,53 @@
+import fs from "fs";
+import path from "path";
+import { extractBackendRefs } from "./backend-links.mjs";
+import { isServerActionFile, isSourceModuleFile, normalizePath } from "./shared.mjs";
+import { collectExportedCallables, collectTopLevelFunctions, parseModule } from "./swc.mjs";
+
+export function discoverServerActions({ rootDir, appRoot }) {
+  const actionEntries = [];
+  for (const absolutePath of walkFiles(appRoot)) {
+    if (!isSourceModuleFile(absolutePath)) continue;
+    const content = fs.readFileSync(absolutePath, "utf8");
+    if (!isServerActionFile(content)) continue;
+    const filePath = normalizePath(path.relative(rootDir, absolutePath));
+    const ast = parseModule(content, filePath);
+    const topLevelFunctions = collectTopLevelFunctions(ast);
+    const { exports } = collectExportedCallables(ast, topLevelFunctions);
+    const backendRefs = extractBackendRefs({
+      ast,
+      rootDir,
+      filePath,
+      readSourceFile: (targetPath) => fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : null,
+    });
+
+    for (const [exportName] of exports.entries()) {
+      actionEntries.push({
+        id: `server-action:${filePath}#${exportName}`,
+        kind: "server_action",
+        filePath,
+        exportName,
+        backendRefs,
+      });
+    }
+  }
+  return actionEntries.sort((left, right) => left.filePath.localeCompare(right.filePath) || left.exportName.localeCompare(right.exportName));
+}
+
+function walkFiles(rootDir) {
+  const results = [];
+  const queue = [rootDir];
+  while (queue.length > 0) {
+    const current = queue.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const absolutePath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        queue.push(absolutePath);
+      } else if (entry.isFile()) {
+        results.push(absolutePath);
+      }
+    }
+  }
+  return results.sort((left, right) => left.localeCompare(right));
+}

package/node_modules/@elench/next-analysis/src/server-actions.test.mjs

@@ -0,0 +1,37 @@
+import path from "path";
+import { describe, expect, it } from "vitest";
+import { createNextAnalysisProject } from "./index.mjs";
+
+const fixtureRoot = path.resolve(
+  "/home/georgedlr/workspace/elench/testkit/test/fixtures/integration/next-server-actions-product"
+);
+
+describe("@elench/next-analysis server actions", () => {
+  it("discovers server action exports and links them from route trees", () => {
+    const project = createNextAnalysisProject({ rootDir: fixtureRoot });
+    const actions = project.discoverServerActions();
+    expect(actions).toEqual([
+      expect.objectContaining({
+        exportName: "saveSettings",
+        filePath: "src/app/settings/actions.ts",
+      }),
+    ]);
+
+    const routeTree = project.analyzeRouteTree("/settings");
+    expect(routeTree.surfaces).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          targetHint: expect.objectContaining({ value: "settings-save-button" }),
+        }),
+      ])
+    );
+    expect(routeTree.serverActionRefs).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          exportKey: "src/app/settings/actions.ts#saveSettings",
+          ownerKind: "action",
+        }),
+      ])
+    );
+  });
+});

package/node_modules/@elench/next-analysis/src/shared.mjs

@@ -0,0 +1,209 @@
+import fs from "fs";
+import path from "path";
+
+export const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+export const HTTP_WRAPPER_METHODS = {
+  getJson: "GET",
+  postJson: "POST",
+  putJson: "PUT",
+  patchJson: "PATCH",
+  deleteJson: "DELETE",
+};
+export const DYNAMIC_SEGMENT_TOKEN = "__TESTKIT_DYNAMIC_SEGMENT__";
+export const SURFACE_COMPONENT_NAMES = new Set(["button", "Button", "form", "Form", "a", "Link", "input"]);
+
+export function normalizePath(filePath) {
+  return String(filePath || "").split(path.sep).join("/");
+}
+
+export function normalizeRoute(value) {
+  const trimmed = String(value || "/").trim();
+  if (!trimmed || trimmed === "/") return "/";
+  const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return withLeadingSlash.length > 1 ? withLeadingSlash.replace(/\/+$/u, "") : withLeadingSlash;
+}
+
+export function normalizeRouteSegments(segments) {
+  const normalizedSegments = [...segments]
+    .filter(Boolean)
+    .map(String)
+    .filter((segment) => !segment.startsWith("(") || !segment.endsWith(")"))
+    .filter((segment) => !segment.startsWith("@"))
+    .filter((segment) => segment !== "page" && segment !== "route" && segment !== "layout");
+  return normalizeRoute(`/${normalizedSegments.join("/")}`);
+}
+
+export function toApiRequestPath(route) {
+  return normalizeRoute(`/api${route === "/" ? "" : route}`);
+}
+
+export function pageLabelFromRoute(route) {
+  if (route === "/") return "Home";
+  return route
+    .split("/")
+    .filter(Boolean)
+    .map((segment) => {
+      if (segment.startsWith("[") && segment.endsWith("]")) return segment.slice(1, -1);
+      return segment;
+    })
+    .map((segment) => segment.replace(/[-_]+/gu, " "))
+    .map((segment) => segment.replace(/^\w/u, (char) => char.toUpperCase()))
+    .join(" ");
+}
+
+export function humanizeTagName(tagName) {
+  return String(tagName).replace(/([a-z])([A-Z])/gu, "$1 $2").replace(/^\w/u, (char) => char.toUpperCase());
+}
+
+export function dedupeById(entries) {
+  const seen = new Set();
+  return entries.filter((entry) => {
+    if (seen.has(entry.id)) return false;
+    seen.add(entry.id);
+    return true;
+  });
+}
+
+export function dedupeRequests(requests) {
+  const seen = new Set();
+  return requests.filter((request) => {
+    const key = `${request.ownerId}:${request.method}:${request.path}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function dedupeRefs(refs) {
+  const seen = new Set();
+  return refs.filter((ref) => {
+    const key = `${ref.ownerId || ""}:${ref.exportKey || ref.id || ""}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function modulePathKey(filePath) {
+  const normalized = normalizePath(filePath);
+  const ext = path.extname(normalized);
+  if (path.basename(normalized, ext) === "index") {
+    return normalizePath(path.dirname(normalized));
+  }
+  return normalized.slice(0, normalized.length - ext.length);
+}
+
+export function isServerActionFile(content) {
+  const trimmed = String(content || "").trimStart();
+  return trimmed.startsWith('"use server"') || trimmed.startsWith("'use server'");
+}
+
+export function isBackendSpecifier(specifier) {
+  return (
+    specifier.startsWith("@/backend/server/") ||
+    specifier.includes("/backend/server/") ||
+    specifier.startsWith("./backend/server/") ||
+    specifier.startsWith("../backend/server/")
+  );
+}
+
+export function isDataSpecifier(specifier) {
+  return (
+    specifier.startsWith("@/backend/data/") ||
+    specifier.startsWith("@/backend/dal/") ||
+    specifier.includes("/backend/data/") ||
+    specifier.includes("/backend/dal/") ||
+    specifier.includes("/db/") ||
+    specifier.includes("/repository/") ||
+    specifier.includes("/repositories/")
+  );
+}
+
+export function isSourceModuleFile(filePath) {
+  return /\.(?:ts|tsx|js|jsx|mjs)$/u.test(filePath);
+}
+
+export function isPageFile(filePath) {
+  return /\/page\.(?:ts|tsx|js|jsx)$/u.test(normalizePath(filePath));
+}
+
+export function isLayoutFile(filePath) {
+  return /\/layout\.(?:ts|tsx|js|jsx)$/u.test(normalizePath(filePath));
+}
+
+export function isRouteHandlerFile(filePath) {
+  return /\/route\.(?:ts|tsx|js|jsx)$/u.test(normalizePath(filePath));
+}
+
+export function fileExists(filePath) {
+  try {
+    return fs.existsSync(filePath) && fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function directoryExists(filePath) {
+  try {
+    return fs.existsSync(filePath) && fs.statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function readFileIfExists(filePath) {
+  return fileExists(filePath) ? fs.readFileSync(filePath, "utf8") : null;
+}
+
+export function resolveSourceCandidate(basePath) {
+  const direct = [basePath, `${basePath}.ts`, `${basePath}.tsx`, `${basePath}.js`, `${basePath}.jsx`, `${basePath}.mjs`];
+  for (const candidate of direct) {
+    if (fileExists(candidate)) return candidate;
+  }
+
+  const indexed = [
+    path.join(basePath, "index.ts"),
+    path.join(basePath, "index.tsx"),
+    path.join(basePath, "index.js"),
+    path.join(basePath, "index.jsx"),
+    path.join(basePath, "index.mjs"),
+  ];
+  for (const candidate of indexed) {
+    if (fileExists(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+export function findLineNumber(content, spanStart) {
+  const source = String(content || "");
+  const target = Math.max(0, Number(spanStart || 0) - 1);
+  let line = 1;
+  for (let index = 0; index < source.length && index < target; index += 1) {
+    if (source[index] === "\n") line += 1;
+  }
+  return line;
+}
+
+export function ensureArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+export function createDiagnostic({ level = "info", code, message, filePath = null, line = null, relatedIds = [] }) {
+  return {
+    level,
+    code,
+    message,
+    ...(filePath ? { filePath } : {}),
+    ...(line ? { line } : {}),
+    ...(relatedIds.length > 0 ? { relatedIds } : {}),
+  };
+}
+
+export function compareByRoute(left, right) {
+  return left.route.localeCompare(right.route) || left.filePath.localeCompare(right.filePath);
+}
+
+export function compareByPath(left, right) {
+  return left.filePath.localeCompare(right.filePath);
+}

package/node_modules/@elench/next-analysis/src/swc.mjs

@@ -0,0 +1,388 @@
+import { parseSync } from "@swc/core";
+import {
+  DYNAMIC_SEGMENT_TOKEN,
+  directoryExists,
+  findLineNumber,
+  HTTP_WRAPPER_METHODS,
+  isServerActionFile,
+  normalizeRoute,
+  readFileIfExists,
+  resolveSourceCandidate,
+} from "./shared.mjs";
+import { requestPathPatternFromLiteral } from "./routes.mjs";
+
+export function parseModule(content, filePath) {
+  return parseSync(content, {
+    syntax: "typescript",
+    tsx: /\.(?:tsx|jsx)$/u.test(filePath),
+    target: "es2022",
+  });
+}
+
+export function resolveImportToSourceFile(rootDir, fromFilePath, specifier) {
+  const sourceRoot = directoryExists(`${rootDir}/src`) ? `${rootDir}/src` : rootDir;
+  const absoluteFrom = `${rootDir}/${fromFilePath}`;
+  const candidates = [];
+
+  if (specifier.startsWith("@/")) {
+    candidates.push(`${sourceRoot}/${specifier.slice(2)}`);
+  } else if (specifier.startsWith("./") || specifier.startsWith("../")) {
+    candidates.push(new URL(specifier, `file://${absoluteFrom}`).pathname);
+  } else {
+    return null;
+  }
+
+  for (const candidate of candidates) {
+    const resolved = resolveSourceCandidate(candidate);
+    if (resolved) return resolved.slice(rootDir.length + 1).split("\\").join("/");
+  }
+
+  return null;
+}
+
+export function collectImports(ast, { rootDir, filePath, readSourceFile = readFileIfExists } = {}) {
+  const imports = new Map();
+  for (const statement of ast.body || []) {
+    if (statement.type !== "ImportDeclaration") continue;
+    const specifier = statement.source?.value || null;
+    if (!specifier) continue;
+    const resolvedFilePath = rootDir && filePath ? resolveImportToSourceFile(rootDir, filePath, specifier) : null;
+    const sourceContent = resolvedFilePath ? readSourceFile(`${rootDir}/${resolvedFilePath}`) : null;
+    const serverActionImport = Boolean(sourceContent && isServerActionFile(sourceContent));
+
+    for (const entry of statement.specifiers || []) {
+      if (entry.type === "ImportDefaultSpecifier") {
+        imports.set(entry.local.value, {
+          importedName: "default",
+          specifier,
+          resolvedFilePath,
+          isServerAction: serverActionImport,
+        });
+        continue;
+      }
+
+      if (entry.type === "ImportSpecifier") {
+        imports.set(entry.local.value, {
+          importedName: entry.imported?.value || entry.local.value,
+          specifier,
+          resolvedFilePath,
+          isServerAction: serverActionImport,
+        });
+      }
+    }
+  }
+  return imports;
+}
+
+export function collectTopLevelFunctions(ast) {
+  const functions = new Map();
+  for (const statement of ast.body || []) {
+    if (statement.type === "FunctionDeclaration" && statement.identifier) {
+      functions.set(statement.identifier.value, statement);
+      continue;
+    }
+
+    if (statement.type === "VariableDeclaration") {
+      collectFunctionVariableDeclarations(statement, functions);
+      continue;
+    }
+
+    if (statement.type === "ExportDeclaration") {
+      const { declaration } = statement;
+      if (declaration?.type === "FunctionDeclaration" && declaration.identifier) {
+        functions.set(declaration.identifier.value, declaration);
+      } else if (declaration?.type === "VariableDeclaration") {
+        collectFunctionVariableDeclarations(declaration, functions);
+      }
+    }
+  }
+  return functions;
+}
+
+function collectFunctionVariableDeclarations(statement, target) {
+  for (const declaration of statement.declarations || []) {
+    if (declaration.id?.type !== "Identifier" || !declaration.init) continue;
+    if (declaration.init.type === "ArrowFunctionExpression" || declaration.init.type === "FunctionExpression") {
+      target.set(declaration.id.value, declaration.init);
+    } else if (declaration.init.type === "Identifier") {
+      target.set(declaration.id.value, declaration.init);
+    }
+  }
+}
+
+export function collectExportedCallables(ast, topLevelFunctions) {
+  const exports = new Map();
+  let defaultExport = null;
+
+  for (const statement of ast.body || []) {
+    if (statement.type === "ExportDeclaration") {
+      const { declaration } = statement;
+      if (declaration?.type === "FunctionDeclaration" && declaration.identifier) {
+        exports.set(declaration.identifier.value, declaration);
+      } else if (declaration?.type === "VariableDeclaration") {
+        for (const declarator of declaration.declarations || []) {
+          if (declarator.id?.type !== "Identifier") continue;
+          const name = declarator.id.value;
+          if (declarator.init?.type === "ArrowFunctionExpression" || declarator.init?.type === "FunctionExpression") {
+            exports.set(name, declarator.init);
+          } else if (declarator.init?.type === "Identifier") {
+            const referenced = topLevelFunctions.get(declarator.init.value);
+            if (referenced) exports.set(name, referenced);
+          }
+        }
+      }
+      continue;
+    }
+
+    if (statement.type === "ExportNamedDeclaration") {
+      for (const specifier of statement.specifiers || []) {
+        if (specifier.type !== "ExportSpecifier") continue;
+        const exportedName = specifier.exported?.value || specifier.orig?.value;
+        const origName = specifier.orig?.value;
+        if (exportedName && origName && topLevelFunctions.get(origName)) {
+          exports.set(exportedName, topLevelFunctions.get(origName));
+        }
+      }
+      continue;
+    }
+
+    if (statement.type === "ExportDefaultDeclaration") {
+      defaultExport = statement.decl;
+      continue;
+    }
+
+    if (statement.type === "ExportDefaultExpression" && statement.expression?.type === "Identifier") {
+      defaultExport = topLevelFunctions.get(statement.expression.value) || null;
+    }
+  }
+
+  return { exports, defaultExport };
+}
+
+export function collectScopeLocalFunctions(node) {
+  const functions = new Map();
+  const body = node?.body?.stmts ? node.body : node?.body?.type === "BlockStatement" ? node.body : null;
+  if (!body) return functions;
+
+  for (const statement of body.stmts || []) {
+    if (statement.type === "FunctionDeclaration" && statement.identifier) {
+      functions.set(statement.identifier.value, statement);
+    } else if (statement.type === "VariableDeclaration") {
+      collectFunctionVariableDeclarations(statement, functions);
+    }
+  }
+
+  return functions;
+}
+
+export function collectJsxAttributes(opening) {
+  const attributes = {};
+  for (const attribute of opening.attributes || []) {
+    if (attribute.type !== "JSXAttribute") continue;
+    const name = attribute.name?.value || attribute.name?.name || null;
+    if (!name) continue;
+    const value = attribute.value;
+    if (!value) {
+      attributes[name] = { stringValue: "true", expression: null };
+    } else if (value.type === "StringLiteral") {
+      attributes[name] = { stringValue: value.value, expression: null };
+    } else if (value.type === "JSXExpressionContainer") {
+      attributes[name] = {
+        stringValue: extractStringLiteral(value.expression),
+        expression: value.expression || null,
+      };
+    }
+  }
+  return attributes;
+}
+
+export function flattenJsxText(children = []) {
+  let text = "";
+  for (const child of children) {
+    if (child.type === "JSXText") {
+      text += child.value.replace(/\s+/gu, " ");
+    } else if (child.type === "JSXExpressionContainer" && child.expression?.type === "StringLiteral") {
+      text += child.expression.value;
+    } else if (child.type === "JSXElement") {
+      text += flattenJsxText(child.children);
+    }
+  }
+  return text;
+}
+
+export function extractJsxLabel(node, attributes) {
+  const ariaLabel = attributes["aria-label"]?.stringValue || attributes.title?.stringValue || null;
+  if (ariaLabel) return ariaLabel;
+  if (node.type === "JSXElement") {
+    const text = flattenJsxText(node.children).trim();
+    if (text) return text;
+  }
+  return null;
+}
+
+export function walkJsx(node, visitor) {
+  const visit = (current, formContext = null) => {
+    let nextFormContext = formContext;
+    if (current?.type === "JSXElement" || current?.type === "JSXOpeningElement") {
+      nextFormContext = visitor(current, formContext);
+    }
+
+    if (current?.type === "JSXElement") {
+      for (const child of current.children || []) visit(child, nextFormContext);
+      return;
+    }
+
+    forEachChild(current, (child) => visit(child, nextFormContext));
+  };
+
+  visit(node, null);
+}
+
+export function forEachChild(node, visitor) {
+  if (!node || typeof node !== "object") return;
+  for (const value of Object.values(node)) {
+    if (!value) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item && typeof item === "object" && item.type) visitor(item);
+      }
+      continue;
+    }
+    if (value && typeof value === "object" && value.type) visitor(value);
+  }
+}
+
+export function extractStringLiteral(node) {
+  if (!node) return null;
+  if (node.type === "StringLiteral") return node.value;
+  if (node.type === "TemplateLiteral") {
+    let value = node.quasis?.[0]?.raw || "";
+    for (let index = 0; index < (node.expressions || []).length; index += 1) {
+      value += DYNAMIC_SEGMENT_TOKEN;
+      value += node.quasis?.[index + 1]?.raw || "";
+    }
+    return value;
+  }
+  return null;
+}
+
+export function extractRouteLiteral(node) {
+  const literal = extractStringLiteral(node);
+  if (!literal) return null;
+  const normalized = literal.split("?")[0];
+  const requestPath = requestPathPatternFromLiteral(normalized);
+  return requestPath ? normalizeRoute(requestPath) : null;
+}
+
+export function extractFetchMethod(node) {
+  if (!node || node.type !== "ObjectExpression") return null;
+  for (const property of node.properties || []) {
+    if (property.type !== "KeyValueProperty") continue;
+    const key = property.key?.value || property.key?.name?.value || property.key?.name || property.key?.value;
+    if (key !== "method") continue;
+    const value = extractStringLiteral(property.value);
+    return value ? value.toUpperCase() : null;
+  }
+  return null;
+}
+
+export function extractHttpRequests(rootNode) {
+  const requests = [];
+  walkNode(rootNode, (node) => {
+    if (node.type !== "CallExpression") return;
+    const request = resolveHttpRequestCall(node);
+    if (request) requests.push(request);
+  });
+  return requests;
+}
+
+export function resolveHttpRequestCall(callExpression) {
+  const callee = callExpression.callee;
+  if (callee?.type === "Identifier") {
+    if (callee.value === "fetch") {
+      const path = extractRouteLiteral(callExpression.arguments?.[0]?.expression);
+      if (!path || !path.startsWith("/api/")) return null;
+      return {
+        method: extractFetchMethod(callExpression.arguments?.[1]?.expression) || "GET",
+        path,
+        confidence: "high",
+      };
+    }
+
+    const method = HTTP_WRAPPER_METHODS[callee.value];
+    if (method) {
+      const path = extractRouteLiteral(callExpression.arguments?.[0]?.expression);
+      if (!path || !path.startsWith("/api/")) return null;
+      return {
+        method,
+        path,
+        confidence: "high",
+      };
+    }
+
+    if (callee.value === "rawReq") {
+      const methodLiteral = extractStringLiteral(callExpression.arguments?.[0]?.expression);
+      const path = extractRouteLiteral(callExpression.arguments?.[1]?.expression);
+      if (!methodLiteral || !path) return null;
+      return {
+        method: methodLiteral.toUpperCase(),
+        path,
+        confidence: "high",
+      };
+    }
+  }
+
+  if (callee?.type === "MemberExpression" && callee.property?.type === "Identifier" && callee.property.value === "rawReq") {
+    const methodLiteral = extractStringLiteral(callExpression.arguments?.[0]?.expression);
+    const path = extractRouteLiteral(callExpression.arguments?.[1]?.expression);
+    if (!methodLiteral || !path) return null;
+    return {
+      method: methodLiteral.toUpperCase(),
+      path,
+      confidence: "high",
+    };
+  }
+
+  return null;
+}
+
+export function extractPlaywrightVisitedRoutes(rootNode) {
+  const routes = [];
+  walkNode(rootNode, (node) => {
+    if (node.type !== "CallExpression") return;
+    const route = resolveGotoRoute(node);
+    if (route) routes.push(route);
+  });
+  return [...new Set(routes)];
+}
+
+function resolveGotoRoute(callExpression) {
+  const callee = callExpression.callee;
+  if (callee?.type !== "MemberExpression") return null;
+  const property = callee.property;
+  if (property?.type !== "Identifier" || property.value !== "goto") return null;
+  const literal = extractStringLiteral(callExpression.arguments?.[0]?.expression);
+  if (!literal) return null;
+  if (/^https?:\/\//u.test(literal)) {
+    try {
+      const parsed = new URL(literal);
+      if (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1") {
+        return normalizeRoute(parsed.pathname.split("?")[0]);
+      }
+    } catch {
+      return null;
+    }
+    return null;
+  }
+  return normalizeRoute(literal.split("?")[0]);
+}
+
+export function walkNode(node, visitor) {
+  if (!node || typeof node !== "object") return;
+  visitor(node);
+  forEachChild(node, (child) => walkNode(child, visitor));
+}
+
+export function extractLineNumber(content, node) {
+  return findLineNumber(content, node?.span?.start);
+}

package/node_modules/@elench/testkit-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-bridge",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "description": "Browser bridge helpers for testkit",
   "type": "module",
   "main": "./src/index.mjs",
@@ -11,7 +11,7 @@
     "src/"
   ],
   "dependencies": {
-    "@elench/testkit-protocol": "0.1.63"
+    "@elench/testkit-protocol": "0.1.65"
   },
   "private": false
 }