Types

Types

Complete TypeScript type definitions exported by @korvol/fixwright.

Import

import type {
  FixWrightConfig,
  PartialFixWrightConfig,
  FixAttempt,
  FixAttemptStatus,
  FailureAnalysis,
  ProposedFix,
  ValidationResult,
  VerbosityLevel,
} from '@korvol/fixwright';

Configuration Types

FixWrightConfig

Full configuration interface.

interface FixWrightConfig {
  /** Claude API configuration */
  ai: {
    apiKey: string;
    model?: string;
    maxTokens?: number;
    temperature?: number;
  };

  /** Git configuration */
  git: {
    baseBranch: string;
    fixBranchPrefix: string;
    commitAuthor?: {
      name: string;
      email: string;
    };
  };

  /** GitHub configuration for PR creation */
  github?: {
    token: string;
    owner: string;
    repo: string;
  };

  /** Validation configuration */
  validation: {
    stepwrightPath: string;
    timeout?: number;
    retries?: number;
  };

  /** Fixing loop configuration */
  fixing: {
    maxAttempts: number;
    maxRetriesPerAttempt: number;
    cooldownMs?: number;
  };

  /** Working directory */
  workDir: string;

  /** Logging configuration */
  logging?: {
    level: 'debug' | 'info' | 'warn' | 'error';
    outputFile?: string;
  };

  /** Verbosity level */
  verbosity?: VerbosityLevel;
}

PartialFixWrightConfig

Configuration with optional fields for construction.

interface PartialFixWrightConfig {
  ai: {
    apiKey: string;
    model?: string;
    maxTokens?: number;
    temperature?: number;
  };
  git?: Partial<FixWrightConfig['git']>;
  github?: FixWrightConfig['github'];
  validation?: Partial<FixWrightConfig['validation']>;
  fixing?: Partial<FixWrightConfig['fixing']>;
  workDir?: string;
  logging?: FixWrightConfig['logging'];
  verbosity?: VerbosityLevel;
}

VerbosityLevel

Output verbosity levels.

type VerbosityLevel = 'quiet' | 'normal' | 'verbose';

DEFAULT_CONFIG

Default configuration values.

const DEFAULT_CONFIG = {
  git: {
    baseBranch: 'main',
    fixBranchPrefix: 'fix/stepwright-',
  },
  validation: {
    stepwrightPath: 'npx stepwright',
    timeout: 120000,
    retries: 2,
  },
  fixing: {
    maxAttempts: 3,
    maxRetriesPerAttempt: 2,
    cooldownMs: 1000,
  },
  logging: {
    level: 'info',
  },
  verbosity: 'normal',
};

Fix Attempt Types

FixAttempt

Represents a single fix attempt.

interface FixAttempt {
  /** Unique attempt ID */
  id: string;

  /** Parent failure case ID */
  failureCaseId: string;

  /** Attempt number (1-based) */
  attemptNumber: number;

  /** Current status */
  status: FixAttemptStatus;

  /** When the attempt started */
  startedAt: Date;

  /** When the attempt completed */
  completedAt?: Date;

  /** Analysis of the failure */
  analysis?: FailureAnalysis;

  /** Proposed fix */
  proposedFix?: ProposedFix;

  /** Validation result */
  validationResult?: ValidationResult;

  /** Error message if failed */
  error?: string;
}

FixAttemptStatus

Possible attempt statuses.

type FixAttemptStatus =
  | 'pending'
  | 'analyzing'
  | 'fixing'
  | 'validating'
  | 'success'
  | 'failed'
  | 'regression'
  | 'new_error';

FailureAnalysis

Analysis result from Claude.

interface FailureAnalysis {
  /** Identified cause type */
  causeType:
    | 'selector_changed'
    | 'timing_issue'
    | 'page_flow_change'
    | 'element_state'
    | 'api_change'
    | 'unknown';

  /** Explanation of the cause */
  explanation: string;

  /** Suggested approach to fix */
  suggestedApproach: string;

  /** Confidence score (0-1) */
  confidence: number;
}

ProposedFix

Proposed code fix.

interface ProposedFix {
  /** File path */
  filePath: string;

  /** Original code */
  originalCode: string;

  /** Fixed code */
  fixedCode: string;

  /** Line range affected */
  lineRange: {
    start: number;
    end: number;
  };

  /** Explanation of the fix */
  explanation: string;
}

ValidationResult

Result of validating a fix.

interface ValidationResult {
  /** Whether validation passed */
  success: boolean;

  /** Duration in milliseconds */
  duration: number;

  /** Error if failed */
  error?: string;

  /** Output from validation run */
  output?: string;
}

Agent Types

AgentFixerConfig

Configuration for AgentFixer.

interface AgentFixerConfig {
  model?: string;
  maxTurns?: number;
  timeout?: number;
  verbosity?: VerbosityLevel;
}

AgentFixResult

Result from an agent fix attempt.

interface AgentFixResult {
  success: boolean;
  analysis?: FailureAnalysis;
  proposedFix?: ProposedFix;
  sessionId?: string;
  error?: string;
  totalCostUsd?: number;
  duration?: number;
  edits?: EditInfo[];
}

EditInfo

Information about an edit operation.

interface EditInfo {
  filePath: string;
  oldString: string;
  newString: string;
  timestamp: Date;
}

ReadInfo

Information about a read operation.

interface ReadInfo {
  filePath: string;
  linesRead?: number;
  timestamp: Date;
}

BashInfo

Information about a bash command.

interface BashInfo {
  command: string;
  description?: string;
  timestamp: Date;
}

GrepInfo

Information about a grep search.

interface GrepInfo {
  pattern: string;
  path?: string;
  glob?: string;
  timestamp: Date;
}

GlobInfo

Information about a glob search.

interface GlobInfo {
  pattern: string;
  path?: string;
  timestamp: Date;
}

Git Types

GitConfig

Git manager configuration.

interface GitConfig {
  baseBranch: string;
  fixBranchPrefix: string;
  commitAuthor?: {
    name: string;
    email: string;
  };
}

GitManagerResult

Result from git operations.

interface GitManagerResult {
  success: boolean;
  output?: string;
  error?: string;
}

GitHub Types

GitHubConfig

GitHub configuration.

interface GitHubConfig {
  token: string;
  owner: string;
  repo: string;
}

PRCreateResult

Result from PR creation.

interface PRCreateResult {
  success: boolean;
  prNumber?: number;
  prUrl?: string;
  error?: string;
}

Event Types

FixWrightEvents

All events emitted by FixWright.

interface FixWrightEvents extends FixingLoopEvents {
  started: () => void;
  stopped: () => void;
  'failure:received': (failureCase: FailureCase) => void;
}

FixingLoopEvents

Events from the fixing loop.

interface FixingLoopEvents {
  'attempt:start': (attempt: FixAttempt) => void;
  'attempt:analyzing': (attempt: FixAttempt) => void;
  'attempt:fixing': (attempt: FixAttempt) => void;
  'attempt:validating': (attempt: FixAttempt) => void;
  'attempt:success': (attempt: FixAttempt) => void;
  'attempt:failed': (attempt: FixAttempt) => void;
  'attempt:regression': (attempt: FixAttempt) => void;
  'attempt:new_error': (attempt: FixAttempt, newError: string) => void;
  'failure:completed': (summary: FixCompletionSummary) => void;

  'agent:message': (message: SDKMessage) => void;
  'agent:error': (error: Error) => void;
  'agent:thinking': (text: string) => void;
  'agent:text': (text: string) => void;
  'agent:tool_use': (toolName: string, input: unknown) => void;
  'agent:read': (info: ReadInfo) => void;
  'agent:edit': (info: EditInfo) => void;
  'agent:bash': (info: BashInfo) => void;
  'agent:grep': (info: GrepInfo) => void;
  'agent:glob': (info: GlobInfo) => void;
  'agent:start': () => void;
  'agent:complete': (result: AgentFixResult) => void;

  'pr:created': (prUrl: string) => void;
  error: (error: Error) => void;
}

FixCompletionSummary

Summary when a failure case is completed.

interface FixCompletionSummary {
  failureCaseId: string;
  status: 'fixed' | 'unfixable';
  attempts: number;
  totalDuration: number;
  successfulAttempt?: FixAttempt;
  prNumber?: number;
  prUrl?: string;
  reason?: string;
}

Shared Types

FailureCase

Re-exported from @korvol/shared.

interface FailureCase {
  id: string;
  status: FailureCaseStatus;
  timestamp: string;
  script: { ... };
  failure: { ... };
}

type FailureCaseStatus = 'pending' | 'processing' | 'fixed' | 'unfixable';

See Also

• FixWright Class - Main class
• AgentFixer - Agent API
• FailureSource - Source API