playwright-intelligence-engine 0.0.0-stage → 2.0.1

package/src/repair/statement-patcher.ts

@@ -0,0 +1,544 @@
+import { Project, SyntaxKind, Node, Statement } from 'ts-morph';
+import fs from 'node:fs';
+import path from 'node:path';
+import { AbstentionError } from '../core/errors/engine-errors.js';
+import { AstPatcher } from './ast-patcher.js';
+import { AssertionHasher } from './assertion-hasher.js';
+
+export type StatementPatchOperation =
+  | 'replace-timeout-with-wait'
+  | 'wrap-action-with-response'
+  | 'insert-readiness-check'
+  | 'replace-inline-locator'
+  | 'replace-statement';
+
+export interface BaseStatementPatchPlan {
+  kind: StatementPatchOperation;
+  /** 1-based line number in the source file. If omitted, matching is done by text pattern. */
+  targetLine?: number;
+}
+
+export interface ReplaceTimeoutPlan extends BaseStatementPatchPlan {
+  kind: 'replace-timeout-with-wait';
+  /** Replacement wait statement, e.g. "await expect(page.getByRole('button', { name: 'Submit' })).toBeVisible({ timeout: 5000 });" */
+  replacementWaitStatement: string;
+}
+
+export interface WrapActionWithResponsePlan extends BaseStatementPatchPlan {
+  kind: 'wrap-action-with-response';
+  /** Target action substring to locate if targetLine is omitted, e.g. "click()" or locator name */
+  targetActionSubstring?: string;
+  /** Predicate string for page.waitForResponse, e.g. "resp => resp.url().includes('/api/auth') && resp.status() === 200" */
+  responsePredicate: string;
+  /** Optional custom timeout in ms for waitForResponse */
+  timeoutMs?: number;
+  /** Optional explicit page variable name, defaults to auto-detected or "page" */
+  pageVarName?: string;
+}
+
+export interface InsertReadinessCheckPlan extends BaseStatementPatchPlan {
+  kind: 'insert-readiness-check';
+  /** Target action substring to locate if targetLine is omitted */
+  targetActionSubstring?: string;
+  /** Statement to insert before action, e.g. "await expect(page.getByRole('button', { name: 'Submit' })).toBeEnabled();" */
+  readinessStatement: string;
+}
+
+export interface ReplaceInlineLocatorPlan extends BaseStatementPatchPlan {
+  kind: 'replace-inline-locator';
+  /** Old locator text in statement, e.g. "page.locator('.btn-login')" */
+  oldLocatorText: string;
+  /** New locator expression, e.g. "page.getByRole('button', { name: 'Log In' })" */
+  newLocatorExpression: string;
+}
+
+export interface ReplaceStatementPlan extends BaseStatementPatchPlan {
+  kind: 'replace-statement';
+  /** Target substring to locate statement if targetLine is omitted */
+  targetSubstring?: string;
+  /** Complete new statement to replace existing one */
+  newStatement: string;
+}
+
+export type StatementPatchPlan =
+  | ReplaceTimeoutPlan
+  | WrapActionWithResponsePlan
+  | InsertReadinessCheckPlan
+  | ReplaceInlineLocatorPlan
+  | ReplaceStatementPlan;
+
+export interface StatementPatchResult {
+  success: boolean;
+  operation: StatementPatchOperation;
+  originalStatement: string;
+  replacementStatement: string;
+  patchedSource: string;
+  diff: string;
+  importAdded?: boolean;
+}
+
+export class StatementPatcher {
+  private project: Project;
+
+  constructor(tsConfigFilePath?: string) {
+    if (tsConfigFilePath) {
+      this.project = new Project({
+        tsConfigFilePath,
+        skipAddingFilesFromTsConfig: false,
+      });
+    } else {
+      this.project = new Project({
+        skipAddingFilesFromTsConfig: true,
+      });
+    }
+  }
+
+  /**
+   * Patches a test source string in-memory without touching disk.
+   */
+  public patchStatementInMemory(
+    sourceText: string,
+    plan: StatementPatchPlan,
+    fileName = 'test.spec.ts'
+  ): StatementPatchResult {
+    const tempProject = new Project({ skipAddingFilesFromTsConfig: true });
+    const sourceFile = tempProject.createSourceFile(fileName, sourceText);
+
+    let importAdded = false;
+
+    // Check if expect import is needed
+    if (
+      plan.kind === 'replace-timeout-with-wait' ||
+      plan.kind === 'insert-readiness-check' ||
+      plan.kind === 'replace-statement'
+    ) {
+      const codeToCheck =
+        plan.kind === 'replace-timeout-with-wait'
+          ? plan.replacementWaitStatement
+          : plan.kind === 'insert-readiness-check'
+            ? plan.readinessStatement
+            : plan.newStatement;
+
+      if (codeToCheck.includes('expect(')) {
+        importAdded = this.ensurePlaywrightExpectImport(sourceFile);
+      }
+    }
+
+    let result: {
+      originalStatement: string;
+      replacementStatement: string;
+    };
+
+    switch (plan.kind) {
+      case 'replace-timeout-with-wait':
+        result = this.executeReplaceTimeout(sourceFile, plan);
+        break;
+      case 'wrap-action-with-response':
+        result = this.executeWrapActionWithResponse(sourceFile, plan);
+        break;
+      case 'insert-readiness-check':
+        result = this.executeInsertReadinessCheck(sourceFile, plan);
+        break;
+      case 'replace-inline-locator':
+        result = this.executeReplaceInlineLocator(sourceFile, plan);
+        break;
+      case 'replace-statement':
+        result = this.executeReplaceStatement(sourceFile, plan);
+        break;
+      default:
+        throw new AbstentionError(
+          `Unsupported statement patch operation: ${(plan as BaseStatementPatchPlan).kind}`,
+          'AST_UNSUPPORTED_STATEMENT_OPERATION'
+        );
+    }
+
+    // Validate that syntax remains valid after patching
+    const diagnostics = tempProject.getProgram().getSyntacticDiagnostics(sourceFile);
+    if (diagnostics.length > 0) {
+      const firstError = diagnostics[0]?.getMessageText();
+      const errorMsg = typeof firstError === 'string' ? firstError : firstError?.getMessageText();
+      throw new AbstentionError(
+        `Syntax error after applying statement patch: ${errorMsg ?? 'unknown syntax error'}`,
+        'AST_SYNTAX_ERROR'
+      );
+    }
+
+    const patchedSource = sourceFile.getFullText();
+    const diff = AstPatcher.generateDiff(sourceText, patchedSource, fileName);
+
+    return {
+      success: true,
+      operation: plan.kind,
+      originalStatement: result.originalStatement,
+      replacementStatement: result.replacementStatement,
+      patchedSource,
+      diff,
+      importAdded,
+    };
+  }
+
+  /**
+   * Patches a test file on disk atomically.
+   */
+  public patchStatementInFile(filePath: string, plan: StatementPatchPlan): StatementPatchResult {
+    const resolvedPath = path.resolve(filePath);
+    if (!fs.existsSync(resolvedPath)) {
+      throw new AbstentionError(`Target file not found at ${resolvedPath}`, 'AST_FILE_NOT_FOUND');
+    }
+
+    const sourceFile = this.project.getSourceFile(resolvedPath) ?? this.project.addSourceFileAtPath(resolvedPath);
+    const sourceText = sourceFile.getFullText();
+    const fileName = path.basename(resolvedPath);
+    const result = this.patchStatementInMemory(sourceText, plan, fileName);
+
+    const targetDir = path.dirname(resolvedPath);
+    const tempFile = path.join(
+      targetDir,
+      `.${path.basename(resolvedPath)}.${Date.now()}.${Math.random().toString(36).substring(2, 6)}.tmp`
+    );
+
+    try {
+      fs.writeFileSync(tempFile, result.patchedSource, 'utf8');
+      fs.renameSync(tempFile, resolvedPath);
+      sourceFile.refreshFromFileSystemSync();
+      return result;
+    } catch (err: any) {
+      if (fs.existsSync(tempFile)) {
+        try {
+          fs.unlinkSync(tempFile);
+        } catch {
+          // ignore cleanup failure
+        }
+      }
+      throw err;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Execution Handlers
+  // ---------------------------------------------------------------------------
+
+  private executeReplaceTimeout(
+    sourceFile: import('ts-morph').SourceFile,
+    plan: ReplaceTimeoutPlan
+  ): { originalStatement: string; replacementStatement: string } {
+    const candidateStatements = this.findStatements(sourceFile, plan.targetLine, (stmt) => {
+      const text = stmt.getText();
+      return text.includes('waitForTimeout');
+    });
+
+    const targetStatement = this.selectSingleTargetStatement(candidateStatements, plan, 'waitForTimeout');
+    const originalStatement = targetStatement.getText();
+    const replacement = plan.replacementWaitStatement.trim().endsWith(';')
+      ? plan.replacementWaitStatement.trim()
+      : `${plan.replacementWaitStatement.trim()};`;
+
+    targetStatement.replaceWithText(replacement);
+
+    return {
+      originalStatement,
+      replacementStatement: replacement,
+    };
+  }
+
+  private executeWrapActionWithResponse(
+    sourceFile: import('ts-morph').SourceFile,
+    plan: WrapActionWithResponsePlan
+  ): { originalStatement: string; replacementStatement: string } {
+    const candidateStatements = this.findStatements(sourceFile, plan.targetLine, (stmt) => {
+      const text = stmt.getText();
+      if (plan.targetActionSubstring) {
+        return text.includes(plan.targetActionSubstring);
+      }
+      return (
+        text.includes('.click(') ||
+        text.includes('.fill(') ||
+        text.includes('.press(') ||
+        text.includes('.selectOption(') ||
+        text.includes('.check(')
+      );
+    });
+
+    const targetStatement = this.selectSingleTargetStatement(
+      candidateStatements,
+      plan,
+      plan.targetActionSubstring ?? 'action'
+    );
+    const originalStatement = targetStatement.getText();
+
+    // Extract bare expression without leading await and trailing semicolon
+    let bareAction = originalStatement.trim();
+    if (bareAction.startsWith('await ')) {
+      bareAction = bareAction.substring(6).trim();
+    }
+    if (bareAction.endsWith(';')) {
+      bareAction = bareAction.substring(0, bareAction.length - 1).trim();
+    }
+
+    // Auto-detect page variable
+    let pageVar = plan.pageVarName ?? 'page';
+    if (!plan.pageVarName) {
+      const pageMatch = bareAction.match(/(\b\w*[pP]age\w*)\./);
+      if (pageMatch && pageMatch[1]) {
+        pageVar = pageMatch[1];
+      }
+    }
+
+    const timeoutArg = plan.timeoutMs ? `, { timeout: ${plan.timeoutMs} }` : '';
+    const replacementStatement = `await Promise.all([\n  ${pageVar}.waitForResponse(${plan.responsePredicate}${timeoutArg}),\n  ${bareAction},\n]);`;
+
+    targetStatement.replaceWithText(replacementStatement);
+
+    return {
+      originalStatement,
+      replacementStatement,
+    };
+  }
+
+  private executeInsertReadinessCheck(
+    sourceFile: import('ts-morph').SourceFile,
+    plan: InsertReadinessCheckPlan
+  ): { originalStatement: string; replacementStatement: string } {
+    const candidateStatements = this.findStatements(sourceFile, plan.targetLine, (stmt) => {
+      const text = stmt.getText();
+      if (plan.targetActionSubstring) {
+        return text.includes(plan.targetActionSubstring);
+      }
+      return text.includes('.click(') || text.includes('.fill(');
+    });
+
+    const targetStatement = this.selectSingleTargetStatement(
+      candidateStatements,
+      plan,
+      plan.targetActionSubstring ?? 'click/fill'
+    );
+    const originalStatement = targetStatement.getText();
+    const parent = targetStatement.getParent();
+
+    const readinessCode = plan.readinessStatement.trim().endsWith(';')
+      ? plan.readinessStatement.trim()
+      : `${plan.readinessStatement.trim()};`;
+
+    if (Node.isBlock(parent)) {
+      const index = targetStatement.getChildIndex();
+      parent.insertStatements(index, readinessCode);
+    } else {
+      // Fallback: replace target statement with readiness + target
+      targetStatement.replaceWithText(`${readinessCode}\n${originalStatement}`);
+    }
+
+    return {
+      originalStatement,
+      replacementStatement: `${readinessCode}\n${originalStatement}`,
+    };
+  }
+
+  private executeReplaceInlineLocator(
+    sourceFile: import('ts-morph').SourceFile,
+    plan: ReplaceInlineLocatorPlan
+  ): { originalStatement: string; replacementStatement: string } {
+    const candidateStatements = this.findStatements(sourceFile, plan.targetLine, (stmt) => {
+      return stmt.getText().includes(plan.oldLocatorText);
+    });
+
+    const targetStatement = this.selectSingleTargetStatement(
+      candidateStatements,
+      plan,
+      `'${plan.oldLocatorText}'`
+    );
+    const originalStatement = targetStatement.getText();
+
+    // AST-level node replacement
+    let replacedInAst = false;
+    const calls = targetStatement.getDescendantsOfKind(SyntaxKind.CallExpression);
+    for (const call of calls) {
+      if (call.getText().trim() === plan.oldLocatorText.trim()) {
+        call.replaceWithText(plan.newLocatorExpression);
+        replacedInAst = true;
+        break;
+      }
+    }
+
+    if (!replacedInAst) {
+      targetStatement.forEachDescendant((node) => {
+        if (!replacedInAst && node.getText().trim() === plan.oldLocatorText.trim()) {
+          node.replaceWithText(plan.newLocatorExpression);
+          replacedInAst = true;
+        }
+      });
+    }
+
+    if (!replacedInAst) {
+      const patchedStatementText = originalStatement.replace(plan.oldLocatorText, plan.newLocatorExpression);
+      if (patchedStatementText === originalStatement) {
+        throw new AbstentionError(
+          `Failed to replace '${plan.oldLocatorText}' with '${plan.newLocatorExpression}'`,
+          'AST_REPLACEMENT_FAILED'
+        );
+      }
+      targetStatement.replaceWithText(patchedStatementText);
+    }
+
+    return {
+      originalStatement,
+      replacementStatement: targetStatement.getText(),
+    };
+  }
+
+  private executeReplaceStatement(
+    sourceFile: import('ts-morph').SourceFile,
+    plan: ReplaceStatementPlan
+  ): { originalStatement: string; replacementStatement: string } {
+    const candidateStatements = this.findStatements(sourceFile, plan.targetLine, (stmt) => {
+      if (plan.targetSubstring) {
+        return stmt.getText().includes(plan.targetSubstring);
+      }
+      return true;
+    });
+
+    const targetStatement = this.selectSingleTargetStatement(
+      candidateStatements,
+      plan,
+      plan.targetSubstring ?? 'target'
+    );
+    const originalStatement = targetStatement.getText();
+    const replacement = plan.newStatement.trim().endsWith(';')
+      ? plan.newStatement.trim()
+      : `${plan.newStatement.trim()};`;
+
+    targetStatement.replaceWithText(replacement);
+
+    return {
+      originalStatement,
+      replacementStatement: replacement,
+    };
+  }
+
+  private selectSingleTargetStatement(
+    candidates: Statement[],
+    plan: BaseStatementPatchPlan,
+    label: string
+  ): Statement {
+    if (candidates.length === 0) {
+      throw new AbstentionError(
+        plan.targetLine
+          ? `No ${label} statement found at line ${plan.targetLine}`
+          : `No ${label} statement found in source file`,
+        'AST_STATEMENT_NOT_FOUND'
+      );
+    }
+    if (candidates.length > 1) {
+      throw new AbstentionError(
+        plan.targetLine
+          ? `Ambiguous statement match on line ${plan.targetLine}: found ${candidates.length} matching ${label} statements. Provide a more specific targetSubstring or unique locator to disambiguate.`
+          : `Ambiguous statement match: found ${candidates.length} ${label} statements. Provide targetLine to specify which statement to transform.`,
+        'AST_AMBIGUOUS_STATEMENT_TARGET'
+      );
+    }
+    const stmt = candidates[0]!;
+    this.assertNotAssertion(stmt);
+    return stmt;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Helper Methods
+  // ---------------------------------------------------------------------------
+
+  private findStatements(
+    sourceFile: import('ts-morph').SourceFile,
+    targetLine?: number,
+    predicate?: (stmt: Statement) => boolean
+  ): Statement[] {
+    const statements: Statement[] = [];
+
+    // Traverse all expression statements and variable statements in tests/blocks
+    const allStatements = [
+      ...sourceFile.getDescendantsOfKind(SyntaxKind.ExpressionStatement),
+      ...sourceFile.getDescendantsOfKind(SyntaxKind.VariableStatement),
+    ];
+
+    for (const stmt of allStatements) {
+      // Exclude outer test wrapper calls (e.g. test('...', () => { ... }))
+      if (Node.isExpressionStatement(stmt)) {
+        const expr = stmt.getExpression();
+        if (Node.isCallExpression(expr)) {
+          const callText = expr.getExpression().getText();
+          if (
+            callText === 'test' ||
+            callText === 'test.describe' ||
+            callText === 'test.step' ||
+            callText === 'describe' ||
+            callText === 'it'
+          ) {
+            continue;
+          }
+        }
+      }
+
+      if (targetLine !== undefined) {
+        const startLine = stmt.getStartLineNumber();
+        const endLine = stmt.getEndLineNumber();
+        if (targetLine < startLine || targetLine > endLine) {
+          continue;
+        }
+      }
+
+      if (predicate && !predicate(stmt)) {
+        continue;
+      }
+
+      statements.push(stmt);
+    }
+
+    return statements;
+  }
+
+  private assertNotAssertion(stmt: Statement): void {
+    const identifiers = AssertionHasher.discoverAssertionIdentifiers(stmt);
+
+    // Guard against removing or tampering with assertions (standard or aliased)
+    const callExpressions = stmt.getDescendantsOfKind(SyntaxKind.CallExpression);
+    for (const call of callExpressions) {
+      if (AssertionHasher.isAssertionCall(call, identifiers)) {
+        throw new AbstentionError(
+          'Modifying or removing test assertions via StatementPatcher is strictly prohibited',
+          'AST_ASSERTION_TAMPERING_PROHIBITED'
+        );
+      }
+    }
+
+    const trimmed = stmt.getText().trim();
+    for (const id of identifiers) {
+      if (trimmed.startsWith(`${id}(`) || trimmed.startsWith(`await ${id}(`)) {
+        throw new AbstentionError(
+          'Modifying or removing test assertions via StatementPatcher is strictly prohibited',
+          'AST_ASSERTION_TAMPERING_PROHIBITED'
+        );
+      }
+    }
+  }
+
+  private ensurePlaywrightExpectImport(sourceFile: import('ts-morph').SourceFile): boolean {
+    const importDecls = sourceFile.getImportDeclarations();
+    const pwImport = importDecls.find((decl) => {
+      const spec = decl.getModuleSpecifierValue();
+      return spec === '@playwright/test';
+    });
+
+    if (pwImport) {
+      const namedImports = pwImport.getNamedImports().map((i) => i.getName());
+      if (!namedImports.includes('expect')) {
+        pwImport.addNamedImport('expect');
+        return true;
+      }
+      return false;
+    }
+
+    // No @playwright/test import found; add one at the top of the file
+    sourceFile.insertImportDeclaration(0, {
+      moduleSpecifier: '@playwright/test',
+      namedImports: ['expect'],
+    });
+    return true;
+  }
+}

package/src/repair/verification-gates.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { BusinessOracleStatus } from '../core/types/repair-evidence.js';
+
+export const VerificationGateInputSchema = z.object({
+  executionPassed: z.boolean(),
+  targetIdentityPreserved: z.boolean(),
+  assertionsIntact: z.boolean(),
+  fixturesIntact: z.boolean(),
+  diffAllowlistPassed: z.boolean(),
+  regressionPassed: z.boolean(),
+  operationValidated: z.boolean(),
+  businessOracleStatus: z.enum(['verified', 'contradicted', 'unavailable']),
+  requireBusinessOracle: z.boolean().default(false),
+});
+
+export type VerificationGateInput = z.input<typeof VerificationGateInputSchema>;
+
+export interface VerificationGateResult {
+  isPromotable: boolean;
+  failedGates: string[];
+  businessOracleStatus: BusinessOracleStatus;
+}
+
+export function evaluateVerificationGates(input: VerificationGateInput): VerificationGateResult {
+  const normalized = VerificationGateInputSchema.parse(input);
+  const failedGates: string[] = [];
+
+  if (!normalized.executionPassed) failedGates.push('executionPassed');
+  if (!normalized.targetIdentityPreserved) failedGates.push('targetIdentityPreserved');
+  if (!normalized.assertionsIntact) failedGates.push('assertionsIntact');
+  if (!normalized.fixturesIntact) failedGates.push('fixturesIntact');
+  if (!normalized.diffAllowlistPassed) failedGates.push('diffAllowlistPassed');
+  if (!normalized.regressionPassed) failedGates.push('regressionPassed');
+  if (!normalized.operationValidated) failedGates.push('operationValidated');
+  if (normalized.businessOracleStatus === 'contradicted') failedGates.push('businessOracleContradicted');
+  if (normalized.requireBusinessOracle && normalized.businessOracleStatus !== 'verified') {
+    failedGates.push('businessOracleRequired');
+  }
+
+  return {
+    isPromotable: failedGates.length === 0,
+    failedGates,
+    businessOracleStatus: normalized.businessOracleStatus,
+  };
+}
+

package/src/repair/workflow-plan.ts

@@ -0,0 +1,59 @@
+import { DiffAllowlistValidator } from './diff-allowlist.js';
+import { RepairOperation, validateRepairOperation } from './repair-operations.js';
+
+export type WorkflowPlanStep =
+  | { kind: 'replace_locator'; target: string; locator: string }
+  | { kind: 'add_frame_scope'; target: string; frameLocator: string }
+  | { kind: 'add_shadow_scope'; target: string; shadowPath: string[] }
+  | { kind: 'dismiss_overlay'; locator: string }
+  | { kind: 'satisfy_prerequisite'; prerequisite: string }
+  | { kind: 'replace_select_with_combobox_flow'; target: string; steps: string[] }
+  | { kind: 'replace_unstable_wait_with_state_wait'; target: string; steps: string[] };
+
+export interface WorkflowPlan {
+  status: 'EXECUTABLE' | 'ABSTAIN';
+  steps: WorkflowPlanStep[];
+  errors: string[];
+}
+
+export function compileWorkflowPlan(operations: RepairOperation[]): WorkflowPlan {
+  const errors: string[] = [];
+  const steps: WorkflowPlanStep[] = [];
+
+  for (const operation of operations) {
+    const validation = validateRepairOperation(operation);
+    if (!validation.isValid || !validation.operation) {
+      errors.push(validation.reason ?? 'Invalid repair operation');
+      continue;
+    }
+
+    const valid = validation.operation;
+    if (valid.kind === 'abstain') {
+      if (operations.length !== 1) errors.push('An abstention must be the only operation in a workflow plan');
+      continue;
+    }
+
+    if (valid.kind === 'replace_locator') {
+      const grammar = DiffAllowlistValidator.validateLocatorGrammar(valid.locator!);
+      if (!grammar.isValid) errors.push(grammar.reason ?? 'Locator grammar rejected');
+      else steps.push({ kind: valid.kind, target: valid.target!, locator: valid.locator! });
+    } else if (valid.kind === 'add_frame_scope') {
+      steps.push({ kind: valid.kind, target: valid.target!, frameLocator: valid.frameLocator! });
+    } else if (valid.kind === 'add_shadow_scope') {
+      steps.push({ kind: valid.kind, target: valid.target!, shadowPath: valid.shadowPath! });
+    } else if (valid.kind === 'dismiss_overlay') {
+      steps.push({ kind: valid.kind, locator: valid.locator! });
+    } else if (valid.kind === 'satisfy_prerequisite') {
+      steps.push({ kind: valid.kind, prerequisite: valid.prerequisite! });
+    } else if (valid.kind === 'replace_select_with_combobox_flow') {
+      steps.push({ kind: valid.kind, target: valid.target!, steps: valid.steps! });
+    } else if (valid.kind === 'replace_unstable_wait_with_state_wait') {
+      steps.push({ kind: valid.kind, target: valid.target!, steps: valid.steps! });
+    }
+  }
+
+  if (errors.length > 0) return { status: 'ABSTAIN', steps: [], errors };
+  if (operations.some((operation) => operation.kind === 'abstain')) return { status: 'ABSTAIN', steps: [], errors: ['Proposal requested abstention'] };
+  return { status: 'EXECUTABLE', steps, errors: [] };
+}
+