@mandujs/ate 0.17.0

package/src/selector-map.ts

@@ -0,0 +1,191 @@
+import { existsSync } from "node:fs";
+import { getAtePaths, readJson, writeJson } from "./fs";
+
+/**
+ * Selector Map Schema
+ * Maps mandu-id to multiple selector strategies for resilient UI testing
+ */
+export interface SelectorMap {
+  schemaVersion: 1;
+  generatedAt: string;
+  entries: SelectorMapEntry[];
+}
+
+export interface SelectorMapEntry {
+  manduId: string;
+  file: string;
+  element: string; // e.g., "button", "input", "a"
+  primary: SelectorStrategy;
+  alternatives: SelectorStrategy[];
+}
+
+export interface SelectorStrategy {
+  type: "mandu-id" | "text" | "class" | "xpath" | "role";
+  value: string;
+  priority: number; // 0 = highest
+}
+
+/**
+ * Read selector-map.json from .mandu directory
+ */
+export function readSelectorMap(repoRoot: string): SelectorMap | null {
+  const paths = getAtePaths(repoRoot);
+  if (!existsSync(paths.selectorMapPath)) {
+    return null;
+  }
+  return readJson<SelectorMap>(paths.selectorMapPath);
+}
+
+/**
+ * Write selector-map.json to .mandu directory
+ */
+export function writeSelectorMap(repoRoot: string, map: SelectorMap): void {
+  const paths = getAtePaths(repoRoot);
+  writeJson(paths.selectorMapPath, map);
+}
+
+/**
+ * Initialize empty selector map
+ */
+export function initSelectorMap(): SelectorMap {
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    entries: [],
+  };
+}
+
+/**
+ * Add or update a selector entry
+ */
+export function addSelectorEntry(
+  map: SelectorMap,
+  entry: Omit<SelectorMapEntry, "alternatives"> & { alternatives?: SelectorStrategy[] }
+): SelectorMap {
+  const existing = map.entries.findIndex((e) => e.manduId === entry.manduId);
+
+  const fullEntry: SelectorMapEntry = {
+    ...entry,
+    alternatives: entry.alternatives ?? [],
+  };
+
+  if (existing >= 0) {
+    map.entries[existing] = fullEntry;
+  } else {
+    map.entries.push(fullEntry);
+  }
+
+  map.generatedAt = new Date().toISOString();
+  return map;
+}
+
+/**
+ * Generate alternative selectors for a given mandu-id element
+ *
+ * Fallback chain priority:
+ * 0. mandu-id (primary)
+ * 1. text-based (exact text match)
+ * 2. class-based (CSS class)
+ * 3. xpath (structural fallback)
+ * 4. role (ARIA role)
+ */
+export function generateAlternatives(opts: {
+  manduId: string;
+  element: string;
+  text?: string;
+  className?: string;
+  ariaRole?: string;
+}): SelectorStrategy[] {
+  const alternatives: SelectorStrategy[] = [];
+
+  // Text-based selector
+  if (opts.text) {
+    alternatives.push({
+      type: "text",
+      value: `:has-text("${opts.text}")`,
+      priority: 1,
+    });
+  }
+
+  // Class-based selector
+  if (opts.className) {
+    alternatives.push({
+      type: "class",
+      value: `.${opts.className}`,
+      priority: 2,
+    });
+  }
+
+  // ARIA role selector
+  if (opts.ariaRole) {
+    alternatives.push({
+      type: "role",
+      value: `role=${opts.ariaRole}`,
+      priority: 3,
+    });
+  }
+
+  // XPath fallback (structural)
+  const xpathValue = `//${opts.element}[@data-mandu-id="${opts.manduId}"]`;
+  alternatives.push({
+    type: "xpath",
+    value: xpathValue,
+    priority: 4,
+  });
+
+  return alternatives.sort((a, b) => a.priority - b.priority);
+}
+
+/**
+ * Get selector entry by mandu-id
+ */
+export function getSelectorEntry(
+  map: SelectorMap,
+  manduId: string
+): SelectorMapEntry | undefined {
+  return map.entries.find((e) => e.manduId === manduId);
+}
+
+/**
+ * Build Playwright .or() chain from selector entry
+ * Returns: page.locator(primary).or(alt1).or(alt2)...
+ */
+export function buildPlaywrightLocatorChain(entry: SelectorMapEntry): string {
+  const primaryLocator = `page.locator('[data-mandu-id="${entry.manduId}"]')`;
+
+  if (entry.alternatives.length === 0) {
+    return primaryLocator;
+  }
+
+  const alternativeChains = entry.alternatives
+    .map((alt) => {
+      switch (alt.type) {
+        case "text":
+          return `page.locator('${entry.element}${alt.value}')`;
+        case "class":
+          return `page.locator('${entry.element}${alt.value}')`;
+        case "role":
+          return `page.getByRole('${alt.value.replace("role=", "")}')`;
+        case "xpath":
+          return `page.locator('xpath=${alt.value}')`;
+        default:
+          return null;
+      }
+    })
+    .filter(Boolean);
+
+  if (alternativeChains.length === 0) {
+    return primaryLocator;
+  }
+
+  return `${primaryLocator}.or(${alternativeChains.join(").or(")})`;
+}
+
+/**
+ * Remove selector entry by mandu-id
+ */
+export function removeSelectorEntry(map: SelectorMap, manduId: string): SelectorMap {
+  map.entries = map.entries.filter((e) => e.manduId !== manduId);
+  map.generatedAt = new Date().toISOString();
+  return map;
+}

package/src/trace-parser.ts

@@ -0,0 +1,270 @@
+import { readFileSync } from "node:fs";
+import { gunzipSync } from "node:zlib";
+import type { JsonValue, JsonObject } from "./types";
+
+export interface TraceAction {
+  type: string;
+  selector?: string;
+  method?: string;
+  error?: string;
+  params?: JsonObject;
+  beforeSnapshot?: string;
+  afterSnapshot?: string;
+}
+
+export interface FailedLocator {
+  selector: string;
+  error: string;
+  context?: string;
+  actionType?: string;
+}
+
+export interface TraceParseResult {
+  actions: TraceAction[];
+  failedLocators: FailedLocator[];
+  metadata: {
+    testFile?: string;
+    testName?: string;
+    timestamp?: string;
+  };
+}
+
+/**
+ * Parse Playwright trace.zip file
+ * Trace format: ZIP archive containing trace JSON + resources
+ *
+ * @param tracePath - Path to trace.zip file
+ * @returns Parsed trace with failed locators
+ */
+export function parseTrace(tracePath: string): TraceParseResult {
+  let content: Buffer;
+
+  try {
+    content = readFileSync(tracePath);
+  } catch (err) {
+    throw new Error(`Failed to read trace file: ${tracePath}`);
+  }
+
+  // Playwright trace.zip is a ZIP archive
+  // For MVP: assume trace is actually JSON (playwright-report.json)
+  // Full ZIP parsing would require JSZip or similar
+
+  let traceData: JsonValue;
+  try {
+    const text = content.toString("utf8");
+    traceData = JSON.parse(text);
+  } catch {
+    // Try gunzip if it's compressed
+    try {
+      const decompressed = gunzipSync(content);
+      const text = decompressed.toString("utf8");
+      traceData = JSON.parse(text);
+    } catch (err) {
+      throw new Error(`Failed to parse trace JSON: ${String(err)}`);
+    }
+  }
+
+  const result: TraceParseResult = {
+    actions: [],
+    failedLocators: [],
+    metadata: {},
+  };
+
+  // Parse Playwright report structure
+  if (typeof traceData !== "object" || !traceData || Array.isArray(traceData)) {
+    return result;
+  }
+
+  const report = traceData as JsonObject;
+
+  // Extract metadata
+  if (typeof report.config === "object" && report.config) {
+    const config = report.config as JsonObject;
+    result.metadata.testFile = String(config.rootDir || "");
+  }
+
+  // Parse suites and tests
+  const suites = Array.isArray(report.suites) ? report.suites : [];
+
+  for (const suite of suites) {
+    if (typeof suite !== "object" || !suite) continue;
+    const suiteObj = suite as JsonObject;
+
+    const tests = Array.isArray(suiteObj.tests) ? suiteObj.tests : [];
+
+    for (const test of tests) {
+      if (typeof test !== "object" || !test) continue;
+      const testObj = test as JsonObject;
+
+      result.metadata.testName = String(testObj.title || "");
+
+      const results = Array.isArray(testObj.results) ? testObj.results : [];
+
+      for (const testResult of results) {
+        if (typeof testResult !== "object" || !testResult) continue;
+        const resultObj = testResult as JsonObject;
+
+        const steps = Array.isArray(resultObj.steps) ? resultObj.steps : [];
+
+        for (const step of steps) {
+          if (typeof step !== "object" || !step) continue;
+          const stepObj = step as JsonObject;
+
+          const action: TraceAction = {
+            type: String(stepObj.title || "unknown"),
+          };
+
+          // Extract error info
+          if (stepObj.error) {
+            const errorObj = typeof stepObj.error === "object" && stepObj.error ? stepObj.error as JsonObject : {};
+            action.error = String(errorObj.message || stepObj.error);
+
+            // Parse locator from error message
+            const errorMsg = action.error;
+            const locatorMatch = errorMsg.match(/locator\(['"](.+?)['"]\)/);
+            if (locatorMatch) {
+              action.selector = locatorMatch[1];
+            }
+
+            // Detect failed locator
+            if (errorMsg.includes("not found") || errorMsg.includes("timeout") || errorMsg.includes("failed")) {
+              const selector = action.selector || extractSelectorFromTitle(String(stepObj.title || ""));
+
+              if (selector) {
+                result.failedLocators.push({
+                  selector,
+                  error: errorMsg,
+                  context: String(stepObj.title || ""),
+                  actionType: detectActionType(String(stepObj.title || "")),
+                });
+              }
+            }
+          }
+
+          result.actions.push(action);
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Extract selector from step title
+ * Examples:
+ * - "click getByRole('button', { name: 'Submit' })" → "getByRole('button', { name: 'Submit' })"
+ * - "fill #username" → "#username"
+ */
+function extractSelectorFromTitle(title: string): string | null {
+  // getByRole, getByText, etc.
+  const playwrightMatch = title.match(/get\w+\([^)]+\)/);
+  if (playwrightMatch) {
+    return playwrightMatch[0];
+  }
+
+  // CSS selectors
+  const cssMatch = title.match(/[#.]\w[\w-]*/);
+  if (cssMatch) {
+    return cssMatch[0];
+  }
+
+  // XPath
+  const xpathMatch = title.match(/\/\/[\w/[\]@='".\s]+/);
+  if (xpathMatch) {
+    return xpathMatch[0];
+  }
+
+  return null;
+}
+
+/**
+ * Detect action type from step title
+ */
+function detectActionType(title: string): string {
+  const lower = title.toLowerCase();
+
+  if (lower.includes("click")) return "click";
+  if (lower.includes("fill") || lower.includes("type")) return "fill";
+  if (lower.includes("select")) return "select";
+  if (lower.includes("check")) return "check";
+  if (lower.includes("navigate") || lower.includes("goto")) return "navigate";
+  if (lower.includes("wait")) return "wait";
+
+  return "unknown";
+}
+
+/**
+ * Generate alternative selectors for a failed locator
+ *
+ * @param selector - Original failed selector
+ * @param actionType - Type of action (click, fill, etc.)
+ * @returns Array of alternative selectors to try
+ */
+export function generateAlternativeSelectors(selector: string, actionType?: string): string[] {
+  const alternatives: string[] = [];
+
+  // CSS ID → alternatives
+  if (selector.startsWith("#")) {
+    const id = selector.slice(1);
+    alternatives.push(
+      `[data-testid="${id}"]`,
+      `[id="${id}"]`,
+      `[name="${id}"]`,
+      `[aria-label="${id}"]`,
+    );
+  }
+
+  // CSS class → alternatives
+  if (selector.startsWith(".")) {
+    const cls = selector.slice(1);
+    alternatives.push(
+      `[data-testid="${cls}"]`,
+      `.${cls}`,
+      `[class*="${cls}"]`,
+    );
+  }
+
+  // getByRole → alternatives
+  if (selector.includes("getByRole")) {
+    const roleMatch = selector.match(/getByRole\(['"](\w+)['"]/);
+    const nameMatch = selector.match(/name:\s*['"](.+?)['"]/);
+
+    if (roleMatch && nameMatch) {
+      const role = roleMatch[1];
+      const name = nameMatch[1];
+
+      alternatives.push(
+        `getByRole('${role}', { name: /${name}/i })`,
+        `getByText('${name}')`,
+        `[aria-label="${name}"]`,
+        `button:has-text("${name}")`,
+      );
+    }
+  }
+
+  // getByText → alternatives
+  if (selector.includes("getByText")) {
+    const textMatch = selector.match(/getByText\(['"](.+?)['"]/);
+    if (textMatch) {
+      const text = textMatch[1];
+      alternatives.push(
+        `getByText(/${text}/i)`,
+        `text=${text}`,
+        `:has-text("${text}")`,
+      );
+    }
+  }
+
+  // Generic fallbacks
+  if (actionType === "click" || actionType === "fill") {
+    alternatives.push(
+      `[data-testid="${selector}"]`,
+      `[aria-label="${selector}"]`,
+      `[name="${selector}"]`,
+    );
+  }
+
+  // Remove duplicates
+  return [...new Set(alternatives)];
+}

package/src/types.ts

@@ -0,0 +1,106 @@
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+export type JsonObject = { [k: string]: JsonValue };
+
+export type OracleLevel = "L0" | "L1" | "L2" | "L3";
+
+export interface AtePaths {
+  repoRoot: string;
+  manduDir: string; // .mandu
+  interactionGraphPath: string;
+  selectorMapPath: string;
+  scenariosPath: string;
+  reportsDir: string;
+  autoE2eDir: string;
+  manualE2eDir: string;
+}
+
+export interface ExtractInput {
+  repoRoot: string;
+  tsconfigPath?: string;
+  routeGlobs?: string[];
+  buildSalt?: string;
+}
+
+export interface InteractionGraph {
+  schemaVersion: 1;
+  generatedAt: string;
+  buildSalt: string;
+  nodes: InteractionNode[];
+  edges: InteractionEdge[];
+  stats: {
+    routes: number;
+    navigations: number;
+    modals: number;
+    actions: number;
+  };
+}
+
+export type InteractionNode =
+  | { kind: "route"; id: string; file: string; path: string }
+  | { kind: "modal"; id: string; file: string; name: string }
+  | { kind: "action"; id: string; file: string; name: string };
+
+export type InteractionEdge =
+  | { kind: "navigate"; from?: string; to: string; file: string; source: string }
+  | { kind: "openModal"; from?: string; modal: string; file: string; source: string }
+  | { kind: "runAction"; from?: string; action: string; file: string; source: string };
+
+export interface GenerateInput {
+  repoRoot: string;
+  oracleLevel?: OracleLevel;
+  onlyRoutes?: string[];
+}
+
+export interface RunInput {
+  repoRoot: string;
+  baseURL?: string;
+  ci?: boolean;
+  headless?: boolean;
+  browsers?: ("chromium" | "firefox" | "webkit")[];
+}
+
+export interface ImpactInput {
+  repoRoot: string;
+  base?: string;
+  head?: string;
+}
+
+export interface HealInput {
+  repoRoot: string;
+  runId: string;
+}
+
+export interface SummaryJson {
+  schemaVersion: 1;
+  runId: string;
+  startedAt: string;
+  finishedAt: string;
+  ok: boolean;
+  oracle: {
+    level: OracleLevel;
+    l0: { ok: boolean; errors: string[] };
+    l1: { ok: boolean; signals: string[] };
+    l2: { ok: boolean; signals: string[] };
+    l3: { ok: boolean; notes: string[] };
+  };
+  playwright: {
+    exitCode: number;
+    reportDir: string;
+    jsonReportPath?: string;
+    junitPath?: string;
+  };
+  mandu: {
+    interactionGraphPath?: string;
+    selectorMapPath?: string;
+    scenariosPath?: string;
+  };
+  heal: {
+    attempted: boolean;
+    suggestions: Array<{ kind: string; title: string; diff: string }>;
+  };
+  impact: {
+    mode: "full" | "subset";
+    changedFiles: string[];
+    selectedRoutes: string[];
+  };
+}