qa-intelligence 1.0.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,19 +10,28 @@ 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
 ```
 
+npm automatically installs peer dependencies (`typescript`, `@types/node`) — no separate dev-deps step needed.
+
 ---
 
-## Quick setup (existing project)
+## Setup
+
+All paths below are relative to `playwright/` when using the recommended subfolder layout.
 
 ### 1. Environment (`.env`)
 
@@ -31,7 +42,26 @@ PW_WORKERS=2
 PW_RETRIES=1
 ```
 
-### 2. `playwright.config.ts`
+### 2. `tsconfig.json` (TypeScript projects)
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "types": ["node"],
+    "skipLibCheck": true
+  },
+  "include": ["tests/**/*", "playwright.config.ts"]
+}
+```
+
+> `module` and `moduleResolution` must both be `"Node16"` so TypeScript resolves the package `exports` map.
+
+### 3. `playwright.config.ts`
 
 ```ts
 import { defineConfig } from "@playwright/test";
@@ -53,7 +83,7 @@ export default defineConfig({
 });
 ```
 
-### 3. Write tests
+### 4. Write tests
 
 Always import `test` from the package — **not** directly from Playwright:
 
@@ -73,13 +103,14 @@ import { step } from "qa-intelligence/playwright/steps";
 import { BasePage } from "qa-intelligence/playwright/basePage";
 ```
 
-### 4. What you provide
+### 5. What you provide
 
 | 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()` |
 
@@ -87,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
@@ -104,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
@@ -179,6 +188,12 @@ The template uses this package under the hood.
 
 ---
 
+## Author
+
+Built as the intelligence engine behind QA automation — Playwright hooks, AI failure analysis, and PR-aware CI. If you use this package, consider leaving a star or linking back—contributions are welcome.
+
+---
+
 ## License
 
 MIT

package/dist/ai/failureAnalyzer.d.ts

@@ -0,0 +1,2 @@
+export declare function analyzeFailureFile(jsonFilePath: string): Promise<string | null>;
+export declare function analyzeLatestFailure(): Promise<string | null>;

package/dist/cli/diff.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/history.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Enriches failure-diff with recurrence: first_seen, occurrence_count.
+ * Persists run history in a cache file for the next run.
+ */
+export {};

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/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/postComment.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/config/env.d.ts

@@ -0,0 +1,7 @@
+export declare const env: {
+    ENV: "dev" | "staging" | "prod";
+    BASE_URL: string;
+    HEADLESS: boolean;
+    PW_WORKERS: number;
+    PW_RETRIES: number;
+};

package/dist/lib/computeDiff.d.ts

@@ -0,0 +1,14 @@
+export interface Failure {
+    file: string;
+    line: number;
+    failure_type: string;
+    severity: string;
+    confidence: number;
+    is_flaky_suspected?: boolean;
+}
+export declare function computeDiff(baselineDir: string, currentDir: string): {
+    newFailures: Failure[];
+    unchangedFailures: Failure[];
+    fixedFailures: Failure[];
+    blockingFailures: Failure[];
+};

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.d.ts

@@ -0,0 +1,10 @@
+import { AiFailure, FailureKey } from "./types";
+export type ReadFailuresOptions = {
+    rootDir: string;
+};
+export declare function failureKey(f: AiFailure): FailureKey;
+export declare function readFailures(options: ReadFailuresOptions): {
+    failures: AiFailure[];
+    byKey: Map<FailureKey, AiFailure>;
+    sourceFiles: string[];
+};

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/dist/lib/format.d.ts

@@ -0,0 +1,3 @@
+import { DiffResult } from "./types";
+export declare function formatDiffComment(diff: DiffResult): string;
+export declare function hasFailureChanges(diff: DiffResult): boolean;

package/dist/lib/types.d.ts

@@ -0,0 +1,21 @@
+export type Severity = "low" | "medium" | "high";
+export type FailureType = "assertion_mismatch" | "selector_not_found" | "timeout" | "navigation_failure" | "environment_error" | "unknown";
+export type AiFailure = {
+    file: string;
+    line: number;
+    failure_type: FailureType | string;
+    expected?: number | string;
+    received?: number | string;
+    is_flaky_suspected?: boolean;
+    severity: Severity | string;
+    confidence: number;
+    first_seen?: string;
+    occurrence_count?: number;
+};
+export type FailureKey = string;
+export type DiffResult = {
+    newFailures: AiFailure[];
+    unchangedFailures: AiFailure[];
+    fixedFailures: AiFailure[];
+    blockingFailures?: AiFailure[];
+};

package/dist/playwright/basePage.d.ts

@@ -0,0 +1,6 @@
+import { Page } from "@playwright/test";
+export declare class BasePage {
+    protected page: Page;
+    constructor(page: Page);
+    protected navigate(path: string): Promise<void>;
+}

package/dist/playwright/baseTest.d.ts

@@ -0,0 +1,5 @@
+import { expect } from "@playwright/test";
+import { env } from "../config/env";
+import "./testHooks";
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export { expect, env };

package/dist/playwright/globalSetup.d.ts

@@ -0,0 +1 @@
+export default function globalSetup(): Promise<void>;

package/dist/playwright/globalTeardown.d.ts

@@ -0,0 +1 @@
+export default function globalTeardown(): Promise<void>;

package/dist/playwright/steps.d.ts

@@ -0,0 +1 @@
+export declare function step<T>(name: string, fn: () => Promise<T>): Promise<T>;

package/dist/playwright/testHooks.d.ts

@@ -0,0 +1 @@
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;

package/dist/reporting/logger.d.ts

@@ -0,0 +1,7 @@
+export declare const logger: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    debug: (msg: string) => void;
+};
+export declare function getLogFilePath(): string;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "qa-intelligence",
-    "version": "1.0.0",
+    "version": "1.1.1",
     "engines": {
         "node": ">=18"
     },
@@ -25,15 +25,35 @@
     "type": "commonjs",
     "main": "dist/index.js",
     "exports": {
-        "./playwright": "./dist/playwright/baseTest.js",
-        "./playwright/globalSetup": "./dist/playwright/globalSetup.js",
-        "./playwright/globalTeardown": "./dist/playwright/globalTeardown.js",
-        "./playwright/basePage": "./dist/playwright/basePage.js",
-        "./playwright/steps": "./dist/playwright/steps.js",
-        "./config/env": "./dist/config/env.js"
+        "./playwright": {
+            "types": "./dist/playwright/baseTest.d.ts",
+            "default": "./dist/playwright/baseTest.js"
+        },
+        "./playwright/globalSetup": {
+            "types": "./dist/playwright/globalSetup.d.ts",
+            "default": "./dist/playwright/globalSetup.js"
+        },
+        "./playwright/globalTeardown": {
+            "types": "./dist/playwright/globalTeardown.d.ts",
+            "default": "./dist/playwright/globalTeardown.js"
+        },
+        "./playwright/basePage": {
+            "types": "./dist/playwright/basePage.d.ts",
+            "default": "./dist/playwright/basePage.js"
+        },
+        "./playwright/steps": {
+            "types": "./dist/playwright/steps.d.ts",
+            "default": "./dist/playwright/steps.js"
+        },
+        "./config/env": {
+            "types": "./dist/config/env.d.ts",
+            "default": "./dist/config/env.js"
+        }
     },
     "peerDependencies": {
-        "@playwright/test": ">=1.40.0"
+        "@playwright/test": ">=1.40.0",
+        "typescript": ">=5.0.0",
+        "@types/node": ">=18.0.0"
     },
     "bin": {
         "qa-intelligence": "dist/cli/index.js",