qa-intelligence 1.1.0 → 1.1.1

package/README.md

@@ -1,6 +1,8 @@
-# qa-intelligence
+# QA Intelligence
 
-CI intelligence engine for Playwright test pipelines.
+**npm:** [`qa-intelligence`](https://www.npmjs.com/package/qa-intelligence)
+
+The intelligence engine for Playwright CI pipelines — install it into any project or use the full [QA Intelligence Framework](https://github.com/ardithaqi/qa-intelligence-framework) template.
 
 - AI-powered failure analysis
 - PR failure diff (new, flaky, still failing, fixed)
@@ -8,13 +10,18 @@ CI intelligence engine for Playwright test pipelines.
 - PR blocking on new non-flaky failures
 - Recurrence tracking ("3rd time since...")
 
-Use it **without the framework template** — install the package into any existing Playwright project.
+Use it **without the framework template** — install the package into your existing app repo.
+
+**Recommended layout:** create a `playwright/` subfolder at the repo root and keep all E2E tooling there, separate from your main app code. Full step-by-step guide (folder layout, `Dockerfile`, CI path changes): **[qa-intelligence-framework README](https://github.com/ardithaqi/qa-intelligence-framework#add-to-an-existing-project-npm-package)**.
 
 ---
 
 ## Install
 
+Run inside your `playwright/` folder (or your Playwright project root if tests already live there):
+
 ```bash
+cd playwright
 npm install qa-intelligence @playwright/test
 ```
 
@@ -22,7 +29,9 @@ npm automatically installs peer dependencies (`typescript`, `@types/node`) — n
 
 ---
 
-## Setup (existing Playwright project)
+## Setup
+
+All paths below are relative to `playwright/` when using the recommended subfolder layout.
 
 ### 1. Environment (`.env`)
 
@@ -98,9 +107,10 @@ import { BasePage } from "qa-intelligence/playwright/basePage";
 
 | You write | Package provides |
 |-----------|------------------|
-| `tests/` | Test hooks, artifact capture |
-| `.env` | Env validation |
-| `playwright.config.ts` | `globalSetup`, `globalTeardown`, AI teardown |
+| `playwright/tests/` | Test hooks, artifact capture |
+| `playwright/.env` | Env validation |
+| `playwright/playwright.config.ts` | `globalSetup`, `globalTeardown`, AI teardown |
+| `playwright/Dockerfile` | — (copy from [framework](https://github.com/ardithaqi/qa-intelligence-framework/blob/master/Dockerfile)) |
 | `.github/workflows/ci.yml` | `qa-intelligence-diff`, `qa-intelligence-history`, `qa-intelligence-comment` |
 | Page objects (optional) | `BasePage`, `step()` |
 
@@ -108,11 +118,11 @@ import { BasePage } from "qa-intelligence/playwright/basePage";
 
 ## CI setup (GitHub Actions)
 
-### Option A: Copy the full workflow (recommended)
+Copy [`.github/workflows/ci.yml`](https://github.com/ardithaqi/qa-intelligence-framework/blob/master/.github/workflows/ci.yml) and [`Dockerfile`](https://github.com/ardithaqi/qa-intelligence-framework/blob/master/Dockerfile) from the framework repo.
 
-Copy `.github/workflows/ci.yml` from the [framework template](https://github.com/ardithaqi/qa-intelligence-framework/blob/master/.github/workflows/ci.yml) into your repo.
+When using the `playwright/` subfolder layout, apply the CI path changes documented in the [framework adoption guide](https://github.com/ardithaqi/qa-intelligence-framework#add-to-an-existing-project-npm-package) (`working-directory: playwright`, artifact paths, etc.).
 
-It includes everything wired together:
+The workflow includes:
 
 - Docker test execution
 - Artifact upload on every run
@@ -125,28 +135,6 @@ Then update:
 - `BASE_URL` in the `docker run` step
 - GitHub secrets (see below)
 
-### Option B: Add to your existing workflow
-
-If you already run Playwright in CI, add these steps **after** tests run and `artifacts/` are uploaded:
-
-```bash
-npm install qa-intelligence
-npx qa-intelligence-diff --baseline baseline-artifacts --current artifacts
-npx qa-intelligence-history
-npx qa-intelligence-comment \
-  --diff failure-diff.json \
-  --repo owner/repo \
-  --pr 123 \
-  --token $GITHUB_TOKEN
-```
-
-You must also handle on your own:
-
-- Uploading `artifacts/` after each run
-- Downloading `baseline-artifacts/` from the target branch on PRs
-
-See the [framework CI workflow](https://github.com/ardithaqi/qa-intelligence-framework/blob/master/.github/workflows/ci.yml) for reference.
-
 ### Required GitHub secrets
 
 - `OPENAI_API_KEY` — enables AI failure analysis in teardown

package/dist/cli/history.js

@@ -10,10 +10,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const failureIdentity_1 = require("../lib/failureIdentity");
 const HISTORY_PATH = ".cache/failure-history.json";
 const MAX_RUNS = 20;
 function failureKey(f) {
-    return `${f.file}:${f.line}:${f.failure_type}`;
+    return (0, failureIdentity_1.failureDiffKey)(f.file, f.failure_type);
 }
 function loadHistory() {
     if (!fs_1.default.existsSync(HISTORY_PATH))

package/dist/lib/computeDiff.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeDiff = computeDiff;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const failureIdentity_1 = require("./failureIdentity");
 function extractTrailingJson(content) {
     const trimmed = content.trimEnd();
     for (let i = trimmed.lastIndexOf("{"); i >= 0; i = trimmed.lastIndexOf("{", i - 1)) {
@@ -16,39 +17,71 @@ function extractTrailingJson(content) {
     }
     return null;
 }
+function readMetaJson(aiTxtPath) {
+    const metaPath = path_1.default.join(path_1.default.dirname(aiTxtPath), "meta.json");
+    if (!fs_1.default.existsSync(metaPath))
+        return null;
+    try {
+        return JSON.parse(fs_1.default.readFileSync(metaPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function resolveFailure(aiTxtPath) {
+    const content = fs_1.default.readFileSync(aiTxtPath, "utf8");
+    const ai = extractTrailingJson(content);
+    if (!ai?.failure_type || typeof ai.severity !== "string")
+        return null;
+    if (typeof ai.confidence !== "number")
+        return null;
+    const meta = readMetaJson(aiTxtPath);
+    const fromStack = (0, failureIdentity_1.parseLocationFromStack)(meta?.stack);
+    const file = (0, failureIdentity_1.normalizeTestPath)(fromStack?.file ?? (typeof ai.file === "string" ? ai.file : ""));
+    const line = fromStack?.line ??
+        (typeof ai.line === "number" ? ai.line : Number(ai.line) || 0);
+    if (!file)
+        return null;
+    return {
+        file,
+        line,
+        failure_type: ai.failure_type,
+        severity: ai.severity,
+        confidence: ai.confidence,
+        is_flaky_suspected: ai.is_flaky_suspected ?? meta?.is_flaky_suspected ?? false,
+    };
+}
 function collectFailures(root) {
-    const failures = [];
     if (!fs_1.default.existsSync(root))
-        return failures;
+        return [];
+    const bestByKey = new Map();
     function walk(dir) {
         for (const file of fs_1.default.readdirSync(dir)) {
             const full = path_1.default.join(dir, file);
             if (fs_1.default.statSync(full).isDirectory()) {
                 walk(full);
+                continue;
             }
-            else if (file === "ai.txt") {
-                const content = fs_1.default.readFileSync(full, "utf8");
-                const data = extractTrailingJson(content);
-                if (!data)
-                    continue;
-                failures.push({
-                    file: data.file,
-                    line: data.line,
-                    failure_type: data.failure_type,
-                    severity: data.severity,
-                    confidence: data.confidence,
-                    is_flaky_suspected: data.is_flaky_suspected ?? false
-                });
+            if (file !== "ai.txt")
+                continue;
+            const failure = resolveFailure(full);
+            if (!failure)
+                continue;
+            const key = (0, failureIdentity_1.failureDiffKey)(failure.file, failure.failure_type);
+            const attempt = (0, failureIdentity_1.parseAttemptFromAiPath)(full);
+            const existing = bestByKey.get(key);
+            if (!existing || attempt >= existing.attempt) {
+                bestByKey.set(key, { failure, attempt });
             }
         }
     }
     walk(root);
-    return failures;
+    return [...bestByKey.values()].map((entry) => entry.failure);
 }
 function toMap(arr) {
     const map = new Map();
     for (const item of arr) {
-        const key = `${item.file}:${item.line}:${item.failure_type}`;
+        const key = (0, failureIdentity_1.failureDiffKey)(item.file, item.failure_type);
         map.set(key, item);
     }
     return map;
@@ -76,6 +109,6 @@ function computeDiff(baselineDir, currentDir) {
         newFailures,
         unchangedFailures,
         fixedFailures,
-        blockingFailures
+        blockingFailures,
     };
 }

package/dist/lib/failureIdentity.d.ts

@@ -0,0 +1,7 @@
+export declare function normalizeTestPath(file: string): string;
+export declare function parseLocationFromStack(stack?: string): {
+    file: string;
+    line: number;
+} | null;
+export declare function failureDiffKey(file: string, failure_type: string): string;
+export declare function parseAttemptFromAiPath(aiTxtPath: string): number;

package/dist/lib/failureIdentity.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeTestPath = normalizeTestPath;
+exports.parseLocationFromStack = parseLocationFromStack;
+exports.failureDiffKey = failureDiffKey;
+exports.parseAttemptFromAiPath = parseAttemptFromAiPath;
+function normalizeTestPath(file) {
+    const p = file.replace(/\\/g, "/").trim();
+    const testsIdx = p.indexOf("tests/");
+    if (testsIdx >= 0)
+        return p.slice(testsIdx);
+    return `tests/${p.replace(/^\//, "")}`;
+}
+function parseLocationFromStack(stack) {
+    if (!stack)
+        return null;
+    const normalized = stack.replace(/\\/g, "/");
+    const match = normalized.match(/(tests\/[^\s:)]+?\.ts):(\d+)/);
+    if (!match)
+        return null;
+    return {
+        file: match[1],
+        line: Number(match[2]),
+    };
+}
+function failureDiffKey(file, failure_type) {
+    return `${normalizeTestPath(file)}:${failure_type}`;
+}
+function parseAttemptFromAiPath(aiTxtPath) {
+    const normalized = aiTxtPath.replace(/\\/g, "/");
+    const match = normalized.match(/\/attempt-(\d+)\/ai\.txt$/);
+    if (!match)
+        return 0;
+    const attempt = Number(match[1]);
+    return Number.isFinite(attempt) ? attempt : 0;
+}

package/dist/lib/failureReader.js

@@ -7,6 +7,7 @@ exports.failureKey = failureKey;
 exports.readFailures = readFailures;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const failureIdentity_1 = require("./failureIdentity");
 function isDirectory(p) {
     return fs_1.default.existsSync(p) && fs_1.default.statSync(p).isDirectory();
 }
@@ -68,7 +69,7 @@ function parseAiTxt(filePath) {
         }
         const lineNum = typeof parsed.line === "string" ? Number(parsed.line) : parsed.line;
         const failure = {
-            file: parsed.file,
+            file: (0, failureIdentity_1.normalizeTestPath)(parsed.file),
             line: Number.isFinite(lineNum) ? lineNum : 0,
             failure_type: parsed.failure_type,
             expected: parsed.expected,
@@ -84,7 +85,7 @@ function parseAiTxt(filePath) {
     }
 }
 function failureKey(f) {
-    return `${f.file}:${f.line}:${f.failure_type}`;
+    return (0, failureIdentity_1.failureDiffKey)(f.file, f.failure_type);
 }
 function readFailures(options) {
     const root = options.rootDir;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "qa-intelligence",
-    "version": "1.1.0",
+    "version": "1.1.1",
     "engines": {
         "node": ">=18"
     },