@snaplens/healwright 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @snaplens/healwright
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Causal E2E regression healer for Playwright powered by git diff and AST analysis.**
+
+[![npm version](https://img.shields.io/npm/v/@snaplens/healwright.svg)](https://www.npmjs.com/package/@snaplens/healwright)
+[![license](https://img.shields.io/npm/l/@snaplens/healwright.svg)](https://github.com/snaplens/healwright/blob/main/LICENSE)
+
+Healwright automatically detects when Playwright tests break due to intentional frontend component refactors (e.g. renamed IDs, modernized testids, altered labels), cross-references the failures with your Git diff, and heals the broken locators in your test files.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Initialize Healwright in your Playwright project
+
+```bash
+npx @snaplens/healwright init
+```
+This automatically configures `playwright.config.ts` with the `@snaplens/healwright-playwright/reporter` and trace retention.
+
+### 2. Auto-heal broken tests
+
+Whenever a Playwright test fails:
+```bash
+npx @snaplens/healwright heal
+```
+
+In CI / GitHub Actions:
+```bash
+npx @snaplens/healwright heal --base origin/main --ci
+```
+
+---
+
+## 📄 License
+
+MIT © [Snaplens](https://github.com/snaplens)

package/dist/cli.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_fs2 = __toESM(require("fs"));
+var import_path2 = __toESM(require("path"));
+var import_healwright_core = require("@snaplens/healwright-core");
+
+// src/commands/init.ts
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+var import_ts_morph = require("ts-morph");
+var REPORTER_PACKAGE = "@snaplens/healwright-playwright/reporter";
+function findPlaywrightConfig(cwd) {
+  const candidates = [
+    "playwright.config.ts",
+    "playwright.config.js",
+    "playwright.config.mts",
+    "playwright.config.mjs"
+  ];
+  for (const file of candidates) {
+    const fullPath = import_path.default.join(cwd, file);
+    if (import_fs.default.existsSync(fullPath)) return fullPath;
+  }
+  return null;
+}
+function getRootConfigObject(sourceFile) {
+  const defineConfigCall = sourceFile.getDescendantsOfKind(import_ts_morph.SyntaxKind.CallExpression).find((call) => call.getExpression().getText() === "defineConfig");
+  if (defineConfigCall) {
+    const firstArg = defineConfigCall.getArguments()[0];
+    if (firstArg && import_ts_morph.Node.isObjectLiteralExpression(firstArg)) return firstArg;
+  }
+  const exportAssignment = sourceFile.getExportAssignment((d) => !d.isExportEquals());
+  if (exportAssignment) {
+    const expr = exportAssignment.getExpression();
+    if (import_ts_morph.Node.isObjectLiteralExpression(expr)) return expr;
+  }
+  return null;
+}
+function patchReporterProperty(configObj) {
+  const reporterProp = configObj.getProperty("reporter");
+  if (!reporterProp) {
+    configObj.addPropertyAssignment({
+      name: "reporter",
+      initializer: `[['list'], ['${REPORTER_PACKAGE}']]`
+    });
+    return "added";
+  }
+  if (!import_ts_morph.Node.isPropertyAssignment(reporterProp)) return "unchanged";
+  const initializer = reporterProp.getInitializer();
+  if (!initializer || initializer.getText().includes(REPORTER_PACKAGE)) return "unchanged";
+  if (import_ts_morph.Node.isStringLiteral(initializer)) {
+    const existing = initializer.getLiteralValue();
+    initializer.replaceWithText(`[['${existing}'], ['${REPORTER_PACKAGE}']]`);
+    return "updated";
+  }
+  if (import_ts_morph.Node.isArrayLiteralExpression(initializer)) {
+    initializer.addElement(`['${REPORTER_PACKAGE}']`);
+    return "updated";
+  }
+  return "unchanged";
+}
+function patchTraceSetting(configObj) {
+  const useProp = configObj.getProperty("use");
+  if (!useProp) {
+    configObj.addPropertyAssignment({
+      name: "use",
+      initializer: `{ trace: 'retain-on-failure' }`
+    });
+    return "added";
+  }
+  if (!import_ts_morph.Node.isPropertyAssignment(useProp)) return "unchanged";
+  const useInit = useProp.getInitializer();
+  if (!useInit || !import_ts_morph.Node.isObjectLiteralExpression(useInit)) return "unchanged";
+  const traceProp = useInit.getProperty("trace");
+  if (!traceProp) {
+    useInit.addPropertyAssignment({
+      name: "trace",
+      initializer: `'retain-on-failure'`
+    });
+    return "added";
+  }
+  if (import_ts_morph.Node.isPropertyAssignment(traceProp)) {
+    const traceInit = traceProp.getInitializer();
+    if (traceInit && import_ts_morph.Node.isStringLiteral(traceInit) && traceInit.getLiteralValue() === "off") {
+      traceInit.replaceWithText(`'retain-on-failure'`);
+      return "updated";
+    }
+  }
+  return "unchanged";
+}
+function updateGitignore(cwd) {
+  const gitignorePath = import_path.default.join(cwd, ".gitignore");
+  const entries = ["healwright-payload.json", ".healwright/"];
+  const content = import_fs.default.existsSync(gitignorePath) ? import_fs.default.readFileSync(gitignorePath, "utf-8") : "";
+  const missing = entries.filter((entry) => !content.includes(entry));
+  if (missing.length === 0) return false;
+  const prefix = content.length > 0 && !content.endsWith("\n") ? "\n\n" : content.length > 0 ? "\n" : "";
+  import_fs.default.writeFileSync(gitignorePath, `${content}${prefix}# Healwright
+${missing.join("\n")}
+`, "utf-8");
+  return true;
+}
+function scaffoldGithubWorkflow(cwd, provider) {
+  const workflowDir = import_path.default.join(cwd, ".github", "workflows");
+  const workflowPath = import_path.default.join(workflowDir, "healwright.yml");
+  if (import_fs.default.existsSync(workflowPath)) return "exists";
+  import_fs.default.mkdirSync(workflowDir, { recursive: true });
+  const secretMap = {
+    anthropic: "ANTHROPIC_API_KEY",
+    openai: "OPENAI_API_KEY",
+    gemini: "GEMINI_API_KEY"
+  };
+  const secretName = secretMap[provider];
+  const apiKeyLine = secretName ? `          api-key: \${{ secrets.${secretName} }}
+` : "";
+  const yaml = `name: Healwright Causal Regression Check
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  e2e-and-heal:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - name: Run Playwright Regression Suite
+        id: playwright
+        continue-on-error: true
+        run: npx playwright test
+      - name: Run Causal Diff Analysis & Auto-Heal
+        if: steps.playwright.outcome == 'failure'
+        uses: healwright/action@v1
+        with:
+          base-ref: origin/\${{ github.base_ref }}
+          provider: ${provider}
+${apiKeyLine}`;
+  import_fs.default.writeFileSync(workflowPath, yaml, "utf-8");
+  return "created";
+}
+async function runInit(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const provider = options.provider ?? "ollama";
+  const configPath = findPlaywrightConfig(cwd);
+  if (!configPath) {
+    console.error("\u274C Could not find playwright.config.ts (or .js/.mts/.mjs) in this directory.");
+    process.exit(1);
+  }
+  const project = new import_ts_morph.Project();
+  const sourceFile = project.addSourceFileAtPath(configPath);
+  const configObj = getRootConfigObject(sourceFile);
+  if (!configObj) {
+    console.error(`\u26A0\uFE0F Could not statically parse root config object in ${import_path.default.basename(configPath)}.`);
+    process.exit(1);
+  }
+  const reporterStatus = patchReporterProperty(configObj);
+  const traceStatus = patchTraceSetting(configObj);
+  if (reporterStatus !== "unchanged" || traceStatus !== "unchanged") {
+    sourceFile.saveSync();
+  }
+  const gitignoreUpdated = updateGitignore(cwd);
+  console.log(`
+\u{1F691} Healwright initialized in ${import_path.default.basename(configPath)}:`);
+  console.log(`   \u2022 Reporter (${REPORTER_PACKAGE}): ${reporterStatus}`);
+  console.log(`   \u2022 Zero-touch failure trace ('retain-on-failure'): ${traceStatus}`);
+  console.log(`   \u2022 .gitignore rules: ${gitignoreUpdated ? "updated" : "already present"}`);
+  if (options.withGithubAction) {
+    const wfStatus = scaffoldGithubWorkflow(cwd, provider);
+    console.log(`   \u2022 GitHub Actions workflow (.github/workflows/healwright.yml): ${wfStatus}`);
+  }
+}
+
+// src/cli.ts
+function getFlagValue(args, flag) {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && args[idx + 1] && !args[idx + 1].startsWith("--") ? args[idx + 1] : void 0;
+}
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  if (command === "init") {
+    const providerArg = getFlagValue(args, "--provider");
+    await runInit({
+      withGithubAction: args.includes("--ci"),
+      provider: providerArg ?? "ollama"
+    });
+    return;
+  }
+  if (command === "heal") {
+    const baseRef = getFlagValue(args, "--base") ?? "HEAD";
+    const provider = getFlagValue(args, "--provider") ?? process.env.HEALWRIGHT_PROVIDER ?? "ollama";
+    const llmConfig = {
+      provider,
+      apiKey: getFlagValue(args, "--api-key") ?? process.env.HEALWRIGHT_API_KEY,
+      model: getFlagValue(args, "--model") ?? process.env.HEALWRIGHT_MODEL
+    };
+    const payloadPath = import_path2.default.join(process.cwd(), "healwright-payload.json");
+    if (!import_fs2.default.existsSync(payloadPath)) {
+      console.error("\u274C No healwright-payload.json found. Run a failing Playwright suite first.");
+      process.exit(1);
+    }
+    const payloads = JSON.parse(import_fs2.default.readFileSync(payloadPath, "utf-8"));
+    const { mutations, rawDiff } = (0, import_healwright_core.getFrontendMutations)(baseRef);
+    console.log(`\u{1F50D} Scanned git diff (${baseRef}): found ${mutations.length} JSX element mutations.`);
+    let bugsCaught = 0;
+    for (const payload of payloads) {
+      console.log(
+        `
+\u{1F9EA} Evaluating: "${payload.testTitle}" (${import_path2.default.basename(payload.file)}:${payload.line})`
+      );
+      const verdict = await (0, import_healwright_core.evaluateCausality)(payload, mutations, rawDiff, llmConfig);
+      if (verdict.status === "bug") {
+        bugsCaught++;
+        console.log(`\u{1F6A8} REGRESSION BUG \u2014 Refusing to heal.`);
+        console.log(`   Reason: ${verdict.reason}`);
+        continue;
+      }
+      const patched = (0, import_healwright_core.applyLocatorPatch)(payload.file, payload.line, verdict.newCallExpression);
+      if (patched) {
+        console.log(`\u2705 HEALED [${verdict.method}] -> ${verdict.newCallExpression}`);
+        console.log(`   Proof: ${verdict.evidence}`);
+      } else {
+        console.log(
+          `\u26A0\uFE0F Causal match found (${verdict.evidence}), but could not locate AST call near line ${payload.line}.`
+        );
+      }
+    }
+    if (args.includes("--ci") && bugsCaught > 0) {
+      process.exit(1);
+    }
+    return;
+  }
+  console.log(`
+\u{1F691} Healwright \u2014 Causal Regression Healer for Playwright
+
+Commands:
+  npx healwright init [--ci] [--provider ollama|anthropic|openai|gemini]
+  npx healwright heal [--base HEAD|origin/main] [--provider ...] [--ci]
+`);
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@snaplens/healwright",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Causal E2E regression healer powered by git diff + AST analysis",
+  "keywords": [
+    "playwright",
+    "self-healing",
+    "cli",
+    "ast",
+    "git-diff",
+    "e2e-testing",
+    "causal-regression"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "bin": {
+    "healwright": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@snaplens/healwright-core": "0.1.1",
+    "ts-morph": "^24.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format cjs --clean",
+    "typecheck": "tsc --noEmit"
+  }
 }