playwright-intelligence-engine 0.0.0-stage → 2.0.1

package/src/repair/repair-workflow.ts

@@ -0,0 +1,241 @@
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { ArchiveReader } from '../trace/archive-reader.js';
+import { TraceParser } from '../trace/trace-parser.js';
+import { EvidenceCorrelator, CorrelatedEvidence } from '../diagnostics/evidence-correlator.js';
+import { DiagnosticReportGenerator } from '../diagnostics/diagnostic-report.js';
+import { bootstrapProjectIntelligence, recordProjectSemanticVerification } from '../intelligence/project-intelligence.js';
+import { parseExternalFailureEvidence, supplementDiagnosticContext } from '../diagnostics/external-failure-evidence.js';
+import { ApprovalService, StagedProposal } from './approval-service.js';
+import { RepairPlanner, RepairProposal, VerifiedRepairResult } from './repair-planner.js';
+import { WorktreeManager, WorktreeInfo } from '../sandbox/worktree-manager.js';
+import { recordRepairWorkflow } from '../governance/workflow-audit.js';
+import { compileSafeRepairOperation } from './safe-operation-compiler.js';
+import { discoverRepairSourceMapping } from './source-mapper.js';
+
+export type RepairWorkflowStatus = 'ABSTAINED' | 'INPUT_REQUIRED' | 'OPERATION_PROPOSAL_ONLY' | 'PROPOSAL_READY' | 'VERIFIED_READY_FOR_APPROVAL' | 'REJECTED';
+
+export interface RepairWorkflowInput {
+  tracePath: string;
+  workspaceRoot?: string | undefined;
+  errorContextPath?: string | undefined;
+  testFilePath?: string | undefined;
+  pomFilePath?: string | undefined;
+  className?: string | undefined;
+  memberName?: string | undefined;
+  configPath?: string | undefined;
+  project?: string | undefined;
+  execute?: boolean | undefined;
+  worktreeId?: string | undefined;
+  operation?: unknown;
+  requireOperationTargetMatch?: boolean | undefined;
+}
+
+export interface RepairWorkflowResult {
+  status: RepairWorkflowStatus;
+  correlated: CorrelatedEvidence;
+  proposedLocator?: string | undefined;
+  candidate?: {
+    locatorExpression: string;
+    score: number;
+    element: RepairProposal['candidateElement'];
+  } | undefined;
+  proposal?: RepairProposal | undefined;
+  stagedProposal?: StagedProposal | undefined;
+  worktree?: WorktreeInfo | undefined;
+  verification?: VerifiedRepairResult | undefined;
+  reason?: string | undefined;
+}
+
+function assertWorkspacePath(root: string, target: string, label: string): string {
+  const canonicalRoot = fsSync.realpathSync(root);
+  const resolved = path.resolve(root, target);
+  if (!fsSync.existsSync(resolved)) throw new Error(`${label} not found: '${resolved}'`);
+  const canonicalTarget = fsSync.realpathSync(resolved);
+  const relative = path.relative(canonicalRoot, canonicalTarget);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`${label} escapes workspace root: '${target}'`);
+  return canonicalTarget;
+}
+
+function resolveReadOnlyPath(root: string, target: string, label: string): string {
+  const resolved = path.isAbsolute(target) ? target : path.resolve(root, target);
+  if (!fsSync.existsSync(resolved)) throw new Error(`${label} not found: '${resolved}'`);
+  return fsSync.realpathSync(resolved);
+}
+
+async function loadCorrelatedEvidence(input: RepairWorkflowInput, workspaceRoot: string): Promise<CorrelatedEvidence> {
+  const tracePath = resolveReadOnlyPath(workspaceRoot, input.tracePath, 'Trace archive');
+  const { traceEntryName, networkEntryName, traceEntryNames, networkEntryNames } = ArchiveReader.findTraceFileEntries(tracePath);
+  if (!traceEntryName) throw new Error(`No .trace event stream found in archive '${tracePath}'`);
+  const traceText = await ArchiveReader.readEntriesAsText(tracePath, traceEntryNames ?? [traceEntryName]);
+  const networkText = (networkEntryNames ?? (networkEntryName ? [networkEntryName] : [])).length > 0
+    ? await ArchiveReader.readEntriesAsText(tracePath, networkEntryNames ?? [networkEntryName!])
+    : '';
+  let context = TraceParser.assembleDiagnosticContext(traceText.split('\n'), networkText.split('\n'));
+  if (input.errorContextPath) {
+    const errorContextPath = resolveReadOnlyPath(workspaceRoot, input.errorContextPath, 'Error context');
+    context = supplementDiagnosticContext(context, parseExternalFailureEvidence(await fs.readFile(errorContextPath, 'utf8')));
+  }
+  return EvidenceCorrelator.correlate(context);
+}
+
+function stageProposal(proposal: RepairProposal, worktreeId: string): StagedProposal {
+  const testFileContent = fsSync.readFileSync(proposal.testFilePath, 'utf8');
+  return ApprovalService.getInstance().stageProposal({
+    targetFilePath: proposal.pomFilePath,
+    targetClassName: proposal.className,
+    targetMemberName: proposal.memberName,
+    originalSourceContent: proposal.originalSource,
+    replacementSelector: proposal.replacementSelector,
+    fullDiff: proposal.fullDiff ?? '',
+    patchedSource: proposal.proposedPatchedSource,
+    testFilePath: proposal.testFilePath,
+    testFileContent,
+    worktreeId,
+  });
+}
+
+/**
+ * Trace-to-repair bridge. It is proposal-only by default. `execute: true`
+ * creates a dedicated worktree and runs the existing verification lifecycle;
+ * it never writes the active workspace or issues an approval token.
+ */
+export async function runRepairWorkflow(input: RepairWorkflowInput): Promise<RepairWorkflowResult> {
+  const workspaceRoot = path.resolve(input.workspaceRoot ?? process.cwd());
+  if (!fsSync.existsSync(workspaceRoot)) throw new Error(`Workspace root does not exist: '${workspaceRoot}'`);
+  const correlated = await loadCorrelatedEvidence(input, workspaceRoot);
+  const intelligence = await bootstrapProjectIntelligence(workspaceRoot);
+  const selected = DiagnosticReportGenerator.selectRepairCandidate(correlated, intelligence);
+
+  if (correlated.classification.shouldAbstain) {
+    const result = { status: 'ABSTAINED' as const, correlated, reason: correlated.classification.abstentionReason ?? correlated.classification.reason };
+    await recordRepairWorkflow(workspaceRoot, { status: result.status, category: correlated.classification.category });
+    return result;
+  }
+  if (!selected) {
+    const result = { status: 'ABSTAINED' as const, correlated, reason: 'No unique, semantically compatible repair candidate survived PIE abstention gates.' };
+    await recordRepairWorkflow(workspaceRoot, { status: result.status, category: correlated.classification.category });
+    return result;
+  }
+
+  const candidate = { locatorExpression: selected.locatorExpression, score: selected.breakdown.score, element: selected.element };
+  let explicitReplacement: string | undefined;
+  if (input.operation !== undefined) {
+    if (input.requireOperationTargetMatch === true) {
+      const operation = input.operation && typeof input.operation === 'object' ? input.operation as Record<string, unknown> : undefined;
+      const failedSelector = correlated.context.failedAction.selector?.trim();
+      const operationTarget = typeof operation?.target === 'string' ? operation.target.trim() : undefined;
+      if (!failedSelector || !operationTarget || operationTarget !== failedSelector) {
+        const result = { status: 'ABSTAINED' as const, correlated, proposedLocator: selected.locatorExpression, candidate, reason: 'The proposed operation target does not exactly match the deterministic failed selector.' };
+        await recordRepairWorkflow(workspaceRoot, { status: result.status, category: correlated.classification.category });
+        return result;
+      }
+    }
+    const compiled = compileSafeRepairOperation(input.operation);
+    if (compiled.readiness === 'ABSTAIN') {
+      const result = { status: 'ABSTAINED' as const, correlated, proposedLocator: selected.locatorExpression, candidate, reason: compiled.reason };
+      await recordRepairWorkflow(workspaceRoot, { status: result.status, category: correlated.classification.category });
+      return result;
+    }
+    if (compiled.readiness === 'PROPOSAL_ONLY') {
+      const result = { status: 'OPERATION_PROPOSAL_ONLY' as const, correlated, proposedLocator: selected.locatorExpression, candidate, reason: compiled.reason };
+      await recordRepairWorkflow(workspaceRoot, { status: result.status, category: correlated.classification.category });
+      return result;
+    }
+    explicitReplacement = compiled.replacementLocator;
+  }
+  const mapping = input.testFilePath && input.pomFilePath && input.className && input.memberName
+    ? undefined
+    : await discoverRepairSourceMapping({ workspaceRoot, failedAction: correlated.context.failedAction });
+  const resolvedTestFilePath = input.testFilePath ?? mapping?.testFilePath;
+  const resolvedPomFilePath = input.pomFilePath ?? mapping?.pomFilePath;
+  const resolvedClassName = input.className ?? mapping?.className;
+  const resolvedMemberName = input.memberName ?? mapping?.memberName;
+  const required = [
+    ['testFilePath', resolvedTestFilePath],
+    ['pomFilePath', resolvedPomFilePath],
+    ['className', resolvedClassName],
+    ['memberName', resolvedMemberName],
+  ] as const;
+  const missing = required.filter(([, value]) => !value).map(([name]) => name);
+  if (missing.length > 0) {
+    const result = { status: 'INPUT_REQUIRED' as const, correlated, proposedLocator: selected.locatorExpression, candidate, reason: `Repair mapping is required: ${missing.join(', ')}` };
+    await recordRepairWorkflow(workspaceRoot, { status: result.status, category: correlated.classification.category });
+    return result;
+  }
+
+  const testFilePath = assertWorkspacePath(workspaceRoot, resolvedTestFilePath!, 'Test file');
+  const pomFilePath = assertWorkspacePath(workspaceRoot, resolvedPomFilePath!, 'Page Object file');
+  const proposal = RepairPlanner.planRepair({
+    originalActionId: correlated.context.failedAction.callId,
+    originalSelector: correlated.context.failedAction.selector ?? '',
+    candidateElement: selected.element,
+    candidateScore: selected.breakdown.score,
+    testFilePath,
+    pomFilePath,
+    className: resolvedClassName!,
+    memberName: resolvedMemberName!,
+    intendedAction: correlated.context.failedAction.action,
+    replacementSelector: explicitReplacement,
+    worktreeId: input.worktreeId,
+  });
+
+  if (!input.execute) {
+    const stagedProposal = stageProposal(proposal, 'proposal-only');
+    await recordRepairWorkflow(workspaceRoot, {
+      status: 'PROPOSAL_READY',
+      category: correlated.classification.category,
+      proposalId: stagedProposal.proposalId,
+    });
+    return { status: 'PROPOSAL_READY', correlated, proposedLocator: selected.locatorExpression, candidate, proposal, stagedProposal };
+  }
+
+  const configPath = input.configPath
+    ? assertWorkspacePath(workspaceRoot, input.configPath, 'Playwright config')
+    : undefined;
+  const manager = new WorktreeManager(workspaceRoot);
+  const worktree = await manager.createWorktree(input.worktreeId);
+  const verification = await RepairPlanner.executeAndVerifyInWorktree({
+    proposal,
+    worktreePath: worktree.worktreePath,
+    worktreeId: worktree.id,
+    workspaceRoot,
+    configPath,
+    project: input.project,
+  });
+  const stagedProposal = ApprovalService.getInstance().stageProposal({
+    targetFilePath: proposal.pomFilePath,
+    targetClassName: proposal.className,
+    targetMemberName: proposal.memberName,
+    originalSourceContent: proposal.originalSource,
+    replacementSelector: proposal.replacementSelector,
+    fullDiff: proposal.fullDiff ?? '',
+    patchedSource: proposal.proposedPatchedSource,
+    testFilePath: proposal.testFilePath,
+    testFileContent: fsSync.readFileSync(proposal.testFilePath, 'utf8'),
+    worktreeId: worktree.id,
+    ...(verification.isReadyForApproval ? { proof: verification.executionProof } : {}),
+  });
+  await recordRepairWorkflow(workspaceRoot, {
+    status: verification.isReadyForApproval ? 'VERIFIED_READY_FOR_APPROVAL' : 'REJECTED',
+    category: correlated.classification.category,
+    proposalId: stagedProposal.proposalId,
+    worktreeId: worktree.id,
+    executionPassed: verification.executionProof.passed,
+  });
+  if (verification.isReadyForApproval) {
+    await recordProjectSemanticVerification(workspaceRoot, proposal.replacementSelector);
+  }
+  return {
+    status: verification.isReadyForApproval ? 'VERIFIED_READY_FOR_APPROVAL' : 'REJECTED',
+    correlated,
+    proposedLocator: selected.locatorExpression,
+    candidate,
+    proposal,
+    stagedProposal,
+    worktree,
+    verification,
+    reason: verification.isReadyForApproval ? 'Isolated verification passed; explicit approval is still required.' : 'Isolated verification did not satisfy all repair gates.',
+  };
+}

package/src/repair/safe-operation-compiler.ts

@@ -0,0 +1,68 @@
+import { DiffAllowlistValidator } from './diff-allowlist.js';
+import { RepairOperation, validateRepairOperation } from './repair-operations.js';
+
+export type SafeOperationReadiness = 'READY_FOR_ISOLATED_VERIFICATION' | 'PROPOSAL_ONLY' | 'ABSTAIN';
+
+export interface CompiledSafeOperation {
+  readiness: SafeOperationReadiness;
+  kind: RepairOperation['kind'];
+  target?: string | undefined;
+  replacementLocator?: string | undefined;
+  reason: string;
+}
+
+function quote(value: string): string {
+  return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+function composeFrameScope(target: string, frameLocator: string): string | undefined {
+  const rootMatch = target.match(/^(this\.page|page)\.(.+)$/);
+  if (!rootMatch) return undefined;
+  return `${rootMatch[1]}.frameLocator(${quote(frameLocator)}).${rootMatch[2]}`;
+}
+
+function composeShadowScope(target: string, shadowPath: string[]): string {
+  return shadowPath.reduce((expression, selector) => `${expression}.locator(${quote(selector)})`, target);
+}
+
+/**
+ * Converts allowlisted workflow operations into immutable locator proposals.
+ * It never writes source files and never claims browser execution succeeded.
+ */
+export function compileSafeRepairOperation(input: unknown): CompiledSafeOperation {
+  const validation = validateRepairOperation(input);
+  if (!validation.isValid || !validation.operation) {
+    return { readiness: 'ABSTAIN', kind: 'abstain', reason: validation.reason ?? 'Invalid repair operation' };
+  }
+
+  const operation = validation.operation;
+  if (operation.kind === 'abstain') {
+    return { readiness: 'ABSTAIN', kind: operation.kind, reason: operation.reason ?? 'Proposal requested abstention' };
+  }
+
+  let replacementLocator: string | undefined;
+  if (operation.kind === 'replace_locator') replacementLocator = operation.locator;
+  if (operation.kind === 'add_frame_scope') replacementLocator = composeFrameScope(operation.target!, operation.frameLocator!);
+  if (operation.kind === 'add_shadow_scope') replacementLocator = composeShadowScope(operation.target!, operation.shadowPath!);
+
+  if (replacementLocator) {
+    const grammar = DiffAllowlistValidator.validateLocatorGrammar(replacementLocator);
+    if (!grammar.isValid) {
+      return { readiness: 'ABSTAIN', kind: operation.kind, target: operation.target, replacementLocator, reason: grammar.reason ?? 'Locator grammar rejected' };
+    }
+    return {
+      readiness: 'READY_FOR_ISOLATED_VERIFICATION',
+      kind: operation.kind,
+      target: operation.target,
+      replacementLocator,
+      reason: 'Static locator transformation passed the PIE allowlist and requires isolated browser verification',
+    };
+  }
+
+  return {
+    readiness: 'PROPOSAL_ONLY',
+    kind: operation.kind,
+    target: operation.target,
+    reason: `Operation '${operation.kind}' requires a dedicated browser-aware executor and remains proposal-only`,
+  };
+}

package/src/repair/source-mapper.ts

@@ -0,0 +1,156 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { FailedAction } from '../core/types/diagnostic-context.js';
+import { StaticAstCollector, ExtractedLocatorAst } from '../collectors/static-ast-collector.js';
+
+export interface RepairSourceMapping {
+  testFilePath: string;
+  pomFilePath: string;
+  className: string;
+  memberName: string;
+  confidence: number;
+  evidence: string[];
+}
+
+interface AstPayload {
+  isPageObject?: boolean;
+  locators?: ExtractedLocatorAst[];
+}
+
+async function listSourceFiles(root: string, depth = 0): Promise<string[]> {
+  if (depth > 6) return [];
+  const ignored = new Set([
+    'node_modules', '.git', 'dist', 'build', 'coverage', 'test-results',
+    'playwright-report', '.next', '.turbo', '.pie', '.pw-intelligence',
+    'repositories', 'pie-evaluation', 'generation', 'repair-worktrees',
+    'temp', 'tmp'
+  ]);
+  let entries;
+  try {
+    entries = await fs.readdir(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files: string[] = [];
+  for (const entry of entries) {
+    if (ignored.has(entry.name)) continue;
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) files.push(...await listSourceFiles(fullPath, depth + 1));
+    else if (/\.(?:ts|tsx|js|jsx|mjs|cjs)$/i.test(entry.name)) files.push(fullPath);
+  }
+  return files;
+}
+
+function normalize(value: string): string {
+  return value.replace(/\s+/g, '').replace(/;$/, '');
+}
+
+function selectorMatches(selector: string, locator: ExtractedLocatorAst): { score: number; evidence: string[] } | undefined {
+  const wanted = normalize(selector);
+  const source = normalize(locator.selectorText);
+  if (!wanted || !source) return undefined;
+
+  if (source.includes(wanted)) {
+    return { score: 100, evidence: ['Failed selector expression matched a Page Object locator expression'] };
+  }
+
+  // Trace formats sometimes emit only the locator argument (for example
+  // "#submit") instead of the full page.locator("#submit") expression.
+  const argumentMatch = source.match(/(?:locator|getByRole|getByText|getByTestId|getByLabel|getByPlaceholder|getByAltText|getByTitle)\((.*)\)/);
+  if (argumentMatch?.[1] && (argumentMatch[1].includes(wanted) || wanted.includes(argumentMatch[1]))) {
+    return { score: 80, evidence: ['Failed selector value matched a Page Object locator argument'] };
+  }
+  return undefined;
+}
+
+function normalizedPath(value: string): string {
+  return value.replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase();
+}
+
+/**
+ * Trace source locations frequently point at a disposable checkout used by
+ * Playwright. Resolve that location back into the active repository only when
+ * the suffix identifies exactly one source file; never guess between twins.
+ */
+function resolveTestSourcePath(root: string, sourceFiles: string[], sourceFile: string | undefined): { path?: string; remapped: boolean } {
+  if (!sourceFile) return { remapped: false };
+  const resolved = path.resolve(root, sourceFile);
+  const inside = path.relative(root, resolved);
+  if (!inside.startsWith('..') && !path.isAbsolute(inside)) {
+    const exact = sourceFiles.find((file) => path.resolve(file) === resolved);
+    if (exact) return { path: exact, remapped: false };
+  }
+
+  const wanted = normalizedPath(sourceFile);
+  const suffixMatches = sourceFiles.filter((file) => {
+    const candidate = normalizedPath(path.relative(root, file));
+    return wanted.endsWith(`/${candidate}`) || candidate.endsWith(`/${wanted}`) || candidate === wanted;
+  });
+  if (suffixMatches.length === 1 && suffixMatches[0]) return { path: suffixMatches[0], remapped: true };
+
+  const basename = path.basename(sourceFile).toLowerCase();
+  const basenameMatches = sourceFiles.filter((file) => path.basename(file).toLowerCase() === basename);
+  return basenameMatches.length === 1 && basenameMatches[0]
+    ? { path: basenameMatches[0], remapped: true }
+    : { remapped: false };
+}
+
+/**
+ * Finds a unique Page Object locator for a failed trace action. This is
+ * intentionally selector-based and fail-closed; it does not infer a class or
+ * member from naming conventions when the selector evidence is absent.
+ */
+export async function discoverRepairSourceMapping(input: {
+  workspaceRoot: string;
+  failedAction: FailedAction;
+}): Promise<RepairSourceMapping | undefined> {
+  const root = path.resolve(input.workspaceRoot);
+  const selector = input.failedAction.selector?.trim();
+  if (!selector) return undefined;
+  const normalizedSelector = normalize(selector);
+  const sourceFiles = await listSourceFiles(root);
+  const resolvedTestSource = resolveTestSourcePath(root, sourceFiles, input.failedAction.sourceFile);
+  if (input.failedAction.sourceFile && !resolvedTestSource.path) return undefined;
+  const matches: Array<RepairSourceMapping & { score: number }> = [];
+
+  for (const filePath of sourceFiles) {
+    // Avoid parsing every source file in large repositories. AST inspection is
+    // reserved for files containing the failed selector text.
+    let sourceText: string;
+    try {
+      sourceText = await fs.readFile(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+    if (!normalize(sourceText).includes(normalizedSelector)) continue;
+    const result = await new StaticAstCollector().collect({ targetFilePath: filePath });
+    const payload = result[0]?.payload as AstPayload | undefined;
+    if (!payload?.isPageObject || !payload.locators) continue;
+    for (const locator of payload.locators) {
+      if (!locator.className || locator.pattern === 'inline') continue;
+      const matched = selectorMatches(input.failedAction.selector ?? '', locator);
+      if (!matched) continue;
+      matches.push({
+        testFilePath: resolvedTestSource.path ?? '',
+        pomFilePath: filePath,
+        className: locator.className,
+        memberName: locator.propertyName,
+        confidence: matched.score / 100,
+        evidence: [
+          ...matched.evidence,
+          ...(resolvedTestSource.remapped ? ['Trace source path remapped to the unique active-repository source file'] : []),
+          `Page Object member ${locator.className}.${locator.propertyName}`,
+          `Source location ${path.relative(root, filePath)}:${locator.line}`,
+        ],
+        score: matched.score,
+      });
+    }
+  }
+
+  if (matches.length === 0) return undefined;
+  const unique = [...new Map(matches.map((match) => [`${match.pomFilePath}:${match.className}:${match.memberName}`, match])).values()];
+  if (unique.length !== 1) return undefined;
+  const match = unique[0]!;
+  if (!match.testFilePath || !path.extname(match.testFilePath)) return undefined;
+  return match;
+}