playwright-intelligence-engine 0.0.0-stage → 2.0.1

package/src/collectors/static-ast-collector.ts

@@ -0,0 +1,226 @@
+import { Project, SyntaxKind } from 'ts-morph';
+import * as fs from 'fs';
+import { EvidenceCollector } from './collector-interface.js';
+import { UnifiedEvidenceRecord } from '../evidence/evidence-model.js';
+
+export interface StaticAstInput {
+  targetFilePath: string;
+  sourceContent?: string;
+  executionId?: string;
+}
+
+export interface ExtractedLocatorAst {
+  className: string | undefined;
+  propertyName: string;
+  method: string;
+  selectorText: string;
+  line: number;
+  pattern: 'property-initializer' | 'getter' | 'constructor-assignment' | 'inline';
+}
+
+export interface ExtractedActionAst {
+  action: string;
+  line: number;
+  text: string;
+}
+
+export interface ExtractedAssertionAst {
+  assertion: string;
+  line: number;
+  text: string;
+}
+
+export class StaticAstCollector implements EvidenceCollector<StaticAstInput> {
+  public readonly name = 'StaticAstCollector';
+  public readonly source = 'static-ast' as const;
+
+  public async collect(input: StaticAstInput): Promise<UnifiedEvidenceRecord[]> {
+    const executionId = input.executionId ?? `exec-${Date.now()}`;
+    const timestamp = Date.now();
+
+    let content = input.sourceContent;
+    if (!content && fs.existsSync(input.targetFilePath)) {
+      content = fs.readFileSync(input.targetFilePath, 'utf-8');
+    }
+
+    if (!content) {
+      return [
+        {
+          evidenceId: `ast-${timestamp}-${Math.random().toString(36).slice(2, 8)}`,
+          executionId,
+          source: 'static-ast',
+          timestamp,
+          evidenceType: 'ast-analysis',
+          payload: {
+            filePath: input.targetFilePath,
+            error: 'File does not exist or empty content',
+            locators: [],
+            actions: [],
+            assertions: [],
+            imports: [],
+            isPageObject: false,
+            isSpec: false,
+          },
+          reliability: 'LOW',
+          provenance: {
+            collector: this.name,
+            collectedAt: timestamp,
+            captureMethod: 'ts-morph-ast-inspection',
+            sourceUri: input.targetFilePath,
+          },
+          redactionStatus: { isRedacted: false },
+        },
+      ];
+    }
+
+    const project = new Project({ useInMemoryFileSystem: true });
+    const sourceFile = project.createSourceFile(input.targetFilePath, content);
+
+    const locators: ExtractedLocatorAst[] = [];
+    const actions: ExtractedActionAst[] = [];
+    const assertions: ExtractedAssertionAst[] = [];
+    const imports: string[] = [];
+
+    // Check imports
+    for (const imp of sourceFile.getImportDeclarations()) {
+      imports.push(imp.getModuleSpecifierValue());
+    }
+
+    const classes = sourceFile.getClasses();
+    const isPageObject = classes.length > 0;
+    const isSpec = input.targetFilePath.includes('.spec.') || input.targetFilePath.includes('.test.');
+
+    // 1. Inspect Classes for Page Object locators
+    for (const cls of classes) {
+      // Property initializers
+      for (const prop of cls.getProperties()) {
+        const init = prop.getInitializer();
+        if (init && (init.getText().includes('.locator(') || init.getText().includes('.getBy'))) {
+          locators.push({
+            className: cls.getName(),
+            propertyName: prop.getName(),
+            method: this.extractLocatorMethod(init.getText()),
+            selectorText: init.getText(),
+            line: prop.getStartLineNumber(),
+            pattern: 'property-initializer',
+          });
+        }
+      }
+
+      // Getters
+      for (const getProp of cls.getGetAccessors()) {
+        const returnStmt = getProp.getFirstDescendantByKind(SyntaxKind.ReturnStatement);
+        if (returnStmt) {
+          const expr = returnStmt.getExpression();
+          if (expr && (expr.getText().includes('.locator(') || expr.getText().includes('.getBy'))) {
+            locators.push({
+              className: cls.getName(),
+              propertyName: getProp.getName(),
+              method: this.extractLocatorMethod(expr.getText()),
+              selectorText: expr.getText(),
+              line: getProp.getStartLineNumber(),
+              pattern: 'getter',
+            });
+          }
+        }
+      }
+
+      // Constructor assignments
+      for (const ctor of cls.getConstructors()) {
+        for (const stmt of ctor.getStatements()) {
+          const text = stmt.getText();
+          if (text.startsWith('this.') && (text.includes('.locator(') || text.includes('.getBy'))) {
+            const parts = text.split('=');
+            const propName = (parts[0] ?? '').replace('this.', '').trim();
+            locators.push({
+              className: cls.getName(),
+              propertyName: propName,
+              method: this.extractLocatorMethod(text),
+              selectorText: text,
+              line: stmt.getStartLineNumber(),
+              pattern: 'constructor-assignment',
+            });
+          }
+        }
+      }
+    }
+
+    // 2. Inspect CallExpressions for test actions and assertions (only inline calls outside class members)
+    for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      const expr = call.getExpression();
+      const exprText = expr.getText();
+
+      // Inline locators (page.locator(...)) - only record if not already part of a class member
+      const isInsideClass = call.getFirstAncestorByKind(SyntaxKind.ClassDeclaration);
+      if (!isInsideClass && (exprText.endsWith('.locator') || exprText.includes('.getBy'))) {
+        locators.push({
+          className: undefined,
+          propertyName: 'inline',
+          method: this.extractLocatorMethod(call.getText()),
+          selectorText: call.getText(),
+          line: call.getStartLineNumber(),
+          pattern: 'inline',
+        });
+      }
+
+      // Actions
+      if (
+        exprText.endsWith('.click') ||
+        exprText.endsWith('.fill') ||
+        exprText.endsWith('.press') ||
+        exprText.endsWith('.type') ||
+        exprText.endsWith('.check') ||
+        exprText.endsWith('.selectOption') ||
+        exprText.endsWith('.goto')
+      ) {
+        actions.push({
+          action: exprText.split('.').pop() ?? 'action',
+          line: call.getStartLineNumber(),
+          text: call.getText(),
+        });
+      }
+
+      // Assertions
+      if (exprText.startsWith('expect(')) {
+        assertions.push({
+          assertion: call.getText(),
+          line: call.getStartLineNumber(),
+          text: call.getText(),
+        });
+      }
+    }
+
+    return [
+      {
+        evidenceId: `ast-${timestamp}-${Math.random().toString(36).slice(2, 8)}`,
+        executionId,
+        source: 'static-ast',
+        timestamp,
+        evidenceType: 'ast-analysis',
+        payload: {
+          filePath: input.targetFilePath,
+          isPageObject,
+          isSpec,
+          classesCount: classes.length,
+          locators,
+          actions,
+          assertions,
+          imports,
+        },
+        reliability: 'HIGH',
+        provenance: {
+          collector: this.name,
+          collectedAt: timestamp,
+          captureMethod: 'ts-morph-ast-inspection',
+          sourceUri: input.targetFilePath,
+        },
+        redactionStatus: { isRedacted: false },
+      },
+    ];
+  }
+
+  private extractLocatorMethod(text: string): string {
+    const match = text.match(/(locator|getByRole|getByText|getByTestId|getByLabel|getByPlaceholder|getByAltText|getByTitle)/);
+    return match && match[1] ? match[1] : 'locator';
+  }
+}

package/src/collectors/trace-collector.ts

@@ -0,0 +1,66 @@
+import { EvidenceCollector } from './collector-interface.js';
+import { UnifiedEvidenceRecord } from '../evidence/evidence-model.js';
+import { ArchiveReader } from '../trace/archive-reader.js';
+import { TraceParser } from '../trace/trace-parser.js';
+import { EvidenceNormalizer } from '../evidence/evidence-normalizer.js';
+
+export interface TraceCollectorInput {
+  archivePath: string;
+  executionId?: string;
+}
+
+export class TraceCollector implements EvidenceCollector<TraceCollectorInput> {
+  public readonly name = 'TraceCollector';
+  public readonly source = 'trace' as const;
+
+  public async collect(input: TraceCollectorInput): Promise<UnifiedEvidenceRecord[]> {
+    const executionId = input.executionId ?? `exec-${Date.now()}`;
+    const timestamp = Date.now();
+
+    try {
+      const { traceEntryName, networkEntryName, traceEntryNames, networkEntryNames } = ArchiveReader.findTraceFileEntries(input.archivePath);
+      if (!traceEntryName) {
+        throw new Error(`No .trace entry found inside archive: ${input.archivePath}`);
+      }
+      const traceText = await ArchiveReader.readEntriesAsText(input.archivePath, traceEntryNames ?? [traceEntryName]);
+      const networkText = (networkEntryNames ?? (networkEntryName ? [networkEntryName] : [])).length > 0
+        ? await ArchiveReader.readEntriesAsText(input.archivePath, networkEntryNames ?? [networkEntryName!])
+        : '';
+      const traceLines = traceText.split('\n');
+      const networkLines = networkText ? networkText.split('\n') : [];
+      const context = TraceParser.assembleDiagnosticContext(traceLines, networkLines);
+
+      const records = EvidenceNormalizer.fromDiagnosticContext(context, executionId);
+
+      // Enhance provenance with archive file path
+      for (const rec of records) {
+        rec.provenance.sourceUri = input.archivePath;
+      }
+
+      return records;
+    } catch (err: any) {
+      return [
+        {
+          evidenceId: `trace-err-${timestamp}`,
+          executionId,
+          source: 'trace',
+          timestamp,
+          evidenceType: 'trace-ingestion-failure',
+          payload: {
+            archivePath: input.archivePath,
+            error: err?.message || 'Failed to parse trace archive',
+          },
+          reliability: 'LOW',
+          provenance: {
+            collector: this.name,
+            collectedAt: timestamp,
+            captureMethod: 'archive-reader',
+            sourceUri: input.archivePath,
+          },
+          redactionStatus: { isRedacted: false },
+          limitations: [err?.message || 'Trace parse failure'],
+        },
+      ];
+    }
+  }
+}

package/src/config/project-config.ts

@@ -0,0 +1,114 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const PROJECT_CONFIG_VERSION = 1;
+
+export interface PieProjectConfig {
+  version: typeof PROJECT_CONFIG_VERSION;
+  projectRoot: string;
+  createdAt: string;
+  updatedAt: string;
+  test: {
+    packageManager: 'npm' | 'pnpm' | 'yarn' | 'unknown';
+    command?: string | undefined;
+    traceDirectories: string[];
+  };
+  diagnostics: {
+    failClosed: true;
+    requireDomEvidence: boolean;
+    allowDirectWorkspaceMutation: false;
+  };
+  memory: {
+    ledgerPath: string;
+    repositoryProfilePath: string;
+  };
+}
+
+export interface InitProjectOptions {
+  force?: boolean | undefined;
+  now?: Date | undefined;
+}
+
+export interface InitProjectResult {
+  config: PieProjectConfig;
+  configPath: string;
+  created: boolean;
+}
+
+function packageManagerFromFiles(files: Set<string>): PieProjectConfig['test']['packageManager'] {
+  if (files.has('pnpm-lock.yaml')) return 'pnpm';
+  if (files.has('yarn.lock')) return 'yarn';
+  if (files.has('package-lock.json')) return 'npm';
+  return 'unknown';
+}
+
+async function readPackageScripts(projectRoot: string): Promise<Record<string, string>> {
+  try {
+    const raw = await fs.readFile(path.join(projectRoot, 'package.json'), 'utf8');
+    const parsed = JSON.parse(raw) as { scripts?: Record<string, string> };
+    return parsed.scripts ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function chooseTestCommand(scripts: Record<string, string>): string | undefined {
+  return ['test:e2e', 'test:smoke', 'test', 'e2e'].find((name) => Boolean(scripts[name]));
+}
+
+export async function initProjectConfig(
+  workspaceRoot = process.cwd(),
+  options: InitProjectOptions = {},
+): Promise<InitProjectResult> {
+  const projectRoot = path.resolve(workspaceRoot);
+  const pieDirectory = path.join(projectRoot, '.pie');
+  const configPath = path.join(pieDirectory, 'config.json');
+  const exists = await fs.access(configPath).then(() => true).catch(() => false);
+
+  if (exists && !options.force) {
+    const existing = await loadProjectConfig(projectRoot);
+    return { config: existing, configPath, created: false };
+  }
+
+  const entries = await fs.readdir(projectRoot, { withFileTypes: true });
+  const fileNames = new Set(entries.filter((entry) => entry.isFile()).map((entry) => entry.name));
+  const scripts = await readPackageScripts(projectRoot);
+  const timestamp = (options.now ?? new Date()).toISOString();
+  const config: PieProjectConfig = {
+    version: PROJECT_CONFIG_VERSION,
+    projectRoot,
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    test: {
+      packageManager: packageManagerFromFiles(fileNames),
+      command: chooseTestCommand(scripts),
+      traceDirectories: ['test-results'],
+    },
+    diagnostics: {
+      failClosed: true,
+      requireDomEvidence: true,
+      allowDirectWorkspaceMutation: false,
+    },
+    memory: {
+      ledgerPath: '.pw-intelligence/stability-ledger.json',
+      repositoryProfilePath: '.pie/repository-profile.json',
+    },
+  };
+
+  await fs.mkdir(pieDirectory, { recursive: true });
+  await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  return { config, configPath, created: true };
+}
+
+export async function loadProjectConfig(workspaceRoot = process.cwd()): Promise<PieProjectConfig> {
+  const configPath = path.join(path.resolve(workspaceRoot), '.pie', 'config.json');
+  const raw = await fs.readFile(configPath, 'utf8');
+  const parsed = JSON.parse(raw) as Partial<PieProjectConfig>;
+  if (parsed.version !== PROJECT_CONFIG_VERSION) {
+    throw new Error(`Unsupported PIE project config version '${String(parsed.version)}'`);
+  }
+  if (!parsed.projectRoot || !parsed.test || !parsed.diagnostics || !parsed.memory) {
+    throw new Error(`Invalid PIE project config at '${configPath}'`);
+  }
+  return parsed as PieProjectConfig;
+}

package/src/core/errors/engine-errors.ts

@@ -0,0 +1,90 @@
+export class PlaywrightIntelligenceError extends Error {
+  constructor(message: string, public readonly code: string) {
+    super(message);
+    this.name = 'PlaywrightIntelligenceError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class UnsupportedTraceVersionError extends PlaywrightIntelligenceError {
+  constructor(version: number | string, message?: string) {
+    super(
+      message ?? `Unsupported Playwright trace version: ${version}`,
+      'UNSUPPORTED_TRACE_VERSION'
+    );
+    this.name = 'UnsupportedTraceVersionError';
+  }
+}
+
+export class TraceCorruptedError extends PlaywrightIntelligenceError {
+  constructor(path: string, reason: string) {
+    super(`Trace archive at ${path} is corrupted: ${reason}`, 'TRACE_CORRUPTED');
+    this.name = 'TraceCorruptedError';
+  }
+}
+
+export class ZipSlipSecurityError extends PlaywrightIntelligenceError {
+  constructor(entryPath: string) {
+    super(
+      `Security violation: Zip entry ${entryPath} attempts path traversal outside target directory`,
+      'ZIP_SLIP_ATTACK_DETECTED'
+    );
+    this.name = 'ZipSlipSecurityError';
+  }
+}
+
+export class AbstentionError extends PlaywrightIntelligenceError {
+  constructor(public readonly reason: string, public readonly failureCategory: string) {
+    super(`Engine abstains from repair: ${reason} (Category: ${failureCategory})`, 'REPAIR_ABSTAINED');
+    this.name = 'AbstentionError';
+  }
+}
+
+export class AssertionTamperedError extends PlaywrightIntelligenceError {
+  constructor(expectedFingerprint: string, actualFingerprint: string) {
+    super(
+      `Intent violation: Assertion SHA-256 fingerprint changed after patch (expected ${expectedFingerprint}, got ${actualFingerprint})`,
+      'ASSERTION_TAMPERED'
+    );
+    this.name = 'AssertionTamperedError';
+  }
+}
+
+export class WorktreeOperationError extends PlaywrightIntelligenceError {
+  constructor(operation: string, details: string) {
+    super(`Worktree operation '${operation}' failed: ${details}`, 'WORKTREE_ERROR');
+    this.name = 'WorktreeOperationError';
+  }
+}
+
+export class UnauthorizedAstModificationError extends PlaywrightIntelligenceError {
+  constructor(details: string) {
+    super(
+      `Diff allowlist violation: Unauthorized AST modification detected (${details}). Only targeted locator declarations may be altered.`,
+      'UNAUTHORIZED_AST_MODIFICATION'
+    );
+    this.name = 'UnauthorizedAstModificationError';
+  }
+}
+
+export class IntentInvariantViolationError extends PlaywrightIntelligenceError {
+  constructor(invariantName: string, details: string) {
+    super(
+      `Intent Invariant v2 violation [${invariantName}]: ${details}`,
+      'INTENT_INVARIANT_VIOLATION'
+    );
+    this.name = 'IntentInvariantViolationError';
+  }
+}
+
+export class InsufficientIdentifiersError extends PlaywrightIntelligenceError {
+  constructor(tag: string, details?: string) {
+    super(
+      `Element <${tag}> lacks distinctive identifying attributes: ${details ?? 'Bare tag fallbacks are strictly prohibited.'}`,
+      'INSUFFICIENT_IDENTIFIERS'
+    );
+    this.name = 'InsufficientIdentifiersError';
+  }
+}
+
+

package/src/core/types/diagnostic-context.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+
+export const NetworkEventSchema = z.object({
+  url: z.string(),
+  method: z.string(),
+  status: z.number(),
+  statusText: z.string().optional(),
+  headers: z.record(z.string(), z.string()).optional(),
+  timestamp: z.number(),
+  durationMs: z.number().optional(),
+  errorText: z.string().optional(),
+  requestId: z.string().optional(),
+  frameId: z.string().optional(),
+  resourceType: z.string().optional(),
+  initiator: z.string().optional(),
+});
+
+export type NetworkEvent = z.infer<typeof NetworkEventSchema>;
+
+export const ConsoleEventSchema = z.object({
+  type: z.enum(['log', 'info', 'warn', 'error', 'debug']),
+  text: z.string(),
+  timestamp: z.number(),
+  location: z.object({
+    url: z.string().optional(),
+    lineNumber: z.number().optional(),
+    columnNumber: z.number().optional(),
+  }).optional(),
+});
+
+export type ConsoleEvent = z.infer<typeof ConsoleEventSchema>;
+
+export const FailureCategorySchema = z.enum([
+  'LOCATOR_DRIFT',
+  'AUTH_EXPIRED',
+  'AUTH_SESSION_EXPIRED',
+  'TIMING_RACE',
+  'DYNAMIC_CONTENT_SLOW',
+  'BACKEND_500',
+  'ENVIRONMENT_FAILURE',
+  'ASSERTION_FAILURE',
+  'ASSERTION_FAILED',
+  'NETWORK_OFFLINE',
+  'AMBIGUOUS_MATCH',
+  'OBSTRUCTED_ELEMENT',
+  'DISABLED_ELEMENT',
+  'FRAME_OR_IFRAME',
+  'HYDRATION_OR_TIMING',
+  'MIXED_FAILURE',
+  'INCOMPLETE_EVIDENCE',
+  'UNSUPPORTED_TRACE_FORMAT',
+  'UNKNOWN_ERROR',
+]);
+
+export type FailureCategory = z.infer<typeof FailureCategorySchema>;
+
+export const FailedActionSchema = z.object({
+  callId: z.string(),
+  action: z.string(),             // e.g. "click", "fill", "waitFor"
+  selector: z.string().optional(), // original failed locator
+  sourceFile: z.string().optional(),
+  line: z.number().optional(),
+  column: z.number().optional(),
+  errorStack: z.string().optional(),
+  errorMessage: z.string().optional(),
+  durationMs: z.number().optional(),
+  timestamp: z.number().optional(),
+  frameId: z.string().optional(),
+  logs: z.array(z.string()).optional(),
+});
+
+export type FailedAction = z.infer<typeof FailedActionSchema>;
+
+export const DiagnosticContextSchema = z.object({
+  playwrightVersion: z.string(),
+  traceFormatVersion: z.number(),
+  failedAction: FailedActionSchema,
+  snapshots: z.object({
+    before: z.string().optional(),
+    action: z.string().optional(),
+    after: z.string().optional(),
+  }),
+  networkEvents: z.array(NetworkEventSchema),
+  consoleEvents: z.array(ConsoleEventSchema),
+  failureCategory: FailureCategorySchema.optional(),
+  evidenceCompleteness: z.object({
+    domAvailable: z.boolean(),
+    networkAvailable: z.boolean(),
+    sourceAvailable: z.boolean(),
+  }),
+});
+
+export type DiagnosticContext = z.infer<typeof DiagnosticContextSchema>;
+

package/src/core/types/repair-evidence.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+
+export const SourceLocationSchema = z.object({
+  filePath: z.string(),
+  className: z.string(),
+  memberName: z.string(),
+  nodeKind: z.enum([
+    'property',
+    'constructor-assignment',
+    'getter-return',
+    'parameterless-factory',
+    'locator-constant',
+  ]),
+  line: z.number(),
+  column: z.number().optional(),
+});
+
+export type SourceLocation = z.infer<typeof SourceLocationSchema>;
+
+export const BusinessOracleStatusSchema = z.enum([
+  'verified',
+  'contradicted',
+  'unavailable',
+]);
+
+export type BusinessOracleStatus = z.infer<typeof BusinessOracleStatusSchema>;
+
+export const RepairEvidenceSchema = z.object({
+  originalActionId: z.string(),
+  originalSelector: z.string(),
+  candidateSelector: z.string(),
+  candidateScore: z.number(),
+  sourceLocation: SourceLocationSchema,
+  targetIdentityEvidence: z.array(z.string()),
+  assertionFingerprint: z.string(),    // SHA-256 of AST expect() blocks (must remain identical)
+  businessOracleStatus: BusinessOracleStatusSchema,
+  verificationWorktreeId: z.string(),
+  repairedTestDurationMs: z.number(),
+  timestamp: z.number(),
+  repairedSuccessfully: z.boolean(),
+  notes: z.string().optional(),
+});
+
+export type RepairEvidence = z.infer<typeof RepairEvidenceSchema>;
+

package/src/core/version.ts

@@ -0,0 +1,25 @@
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Product identity is kept in one place so the CLI, MCP server, and execution
+ * proofs cannot silently advertise different versions.
+ */
+export const PACKAGE_VERSION = '2.0.1';
+export const ENGINE_MILESTONE = '2.0.1';
+export const PROOF_VERSION = ENGINE_MILESTONE;
+
+export interface RuntimeProvenance {
+  sourceRevision: string;
+  workspaceDirty: boolean;
+}
+
+export function getRuntimeProvenance(root = process.cwd()): RuntimeProvenance {
+  try {
+    const sourceRevision = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || 'unknown';
+    const status = execFileSync('git', ['status', '--porcelain'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return { sourceRevision, workspaceDirty: status.trim().length > 0 };
+  } catch {
+    return { sourceRevision: 'unknown', workspaceDirty: false };
+  }
+}
+