playwright-smart-test 0.0.0-stage → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ujjwal S S
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,290 @@
-# Temporary Holding Version
+# 🎭 Playwright Smart Test (`playwright-smart-test`)
 
-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.
+[![npm version](https://img.shields.io/npm/v/playwright-smart-test.svg?style=flat-square&color=007acc)](https://www.npmjs.com/package/playwright-smart-test)
+[![Playwright](https://img.shields.io/badge/Playwright-Tested-45ba4b?style=flat-square&logo=playwright&logoColor=white)](https://playwright.dev/)
+[![Google Gemini](https://img.shields.io/badge/Powered%20By-Google%20Gemini-4285F4?style=flat-square&logo=google&logoColor=white)](https://ai.google.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+> AI-powered regression test selection for Playwright test suites. Analyzes Pull Request diffs with Google Gemini, traces cross-component ripple effects, and executes only impacted tests with safety guardrails.
+
+---
+
+## Overview
+
+In end-to-end Playwright testing, running every test on every Pull Request can take significant CI time.
+
+Static AST import analyzers often fail in E2E environments because:
+1. **App code is decoupled from E2E tests**: Tests drive a browser over CDP/WebSocket rather than importing application components directly.
+2. **Playwright Fixtures**: Tests import shared `fixtures.ts` files, causing static tools to flag all tests on any change.
+
+`playwright-smart-test` combines **Google Gemini** for semantic analysis with **safety guardrails** to select and run only the tests affected by your PR.
+
+---
+
+## 🏗️ Architecture
+
+```
+                       Pull Request Git Diff
+                                 │
+                                 ▼
+    ┌─────────────────────────────────────────────────────────┐
+    │              PHASE 1: PRE-AI SAFETY GATES               │
+    │  • Docs/Asset Fast-Path (0 tests for markdown/images)   │
+    │  • Domain Scatter Guard (>8 architectural domains)      │
+    │  • Lockfile & Bundle Noise Sanitizer                    │
+    └────────────────────────────┬────────────────────────────┘
+                                 │
+                    (If smart selection eligible)
+                                 │
+                                 ▼
+    ┌─────────────────────────────────────────────────────────┐
+    │                     THE LLM BRAIN                       │
+    │  • Google Gemini analyzes code diffs & business logic   │
+    │  • Evaluates catalog (specs, describe blocks, @tags)    │
+    │  • Evaluates playwright.config diffs intelligently      │
+    │  • Fail-safe fallback: If uncertain ──► Run Full Suite  │
+    └────────────────────────────┬────────────────────────────┘
+                                 │
+                                 ▼
+    ┌─────────────────────────────────────────────────────────┐
+    │           PHASE 3: POST-AI GUARDRAILS & GATES           │
+    │  • Direct Test Invariant (touched specs always run)     │
+    │  • Deleted File Purge (prevents Playwright crashes)     │
+    │  • Catalog Whitelist Filter (blocks hallucinations)     │
+    │  • Zero-Test Smoke Safety Net (runs @smoke on 0 tests)  │
+    └────────────────────────────┬────────────────────────────┘
+                                 │
+                                 ▼
+                    Execute Targeted Playwright Tests
+```
+
+---
+
+## 🛡️ Safety Guardrails
+
+| Guardrail | Purpose | Behavior |
+| :--- | :--- | :--- |
+| **1. Docs Fast-Path** | Efficiency | If only documentation, markdown, or assets are modified, exits immediately with 0 tests run without calling Gemini. |
+| **2. Domain Scatter Guard** | Blast radius | If changes touch more than 8 independent directories/domains, triggers full regression. Large PRs localized to a single feature folder remain targeted. |
+| **3. Lockfile Sanitizer** | Prompt efficiency | Omits lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) from Gemini prompts, sending version updates as brief summaries. |
+| **4. Safe Default Fallback** | Reliability | If Gemini times out (20s), is unavailable, or indicates uncertain blast radius, safely defaults to running all tests. |
+| **5. Direct Test Invariant** | Accuracy | Any `.spec.ts` modified in the PR is unconditionally included in the test run. |
+| **6. Deleted File Purge** | Stability | Automatically excludes deleted test files from the execution list. |
+| **7. Catalog Whitelist** | Validation | Cross-references recommendations against tests found on disk; unverified paths are discarded. |
+| **8. Smoke Safety Net** | Safety net | If application code was changed but no specific test was matched, runs tests tagged `@smoke` as a baseline. |
+
+---
+
+## 📦 Installation & Quick Start
+
+### 1. Install as a dev dependency
+
+```bash
+# npm
+npm install --save-dev playwright-smart-test
+
+# pnpm
+pnpm add -D playwright-smart-test
+
+# yarn
+yarn add -D playwright-smart-test
+```
+
+### 2. Configure Gemini API Key
+Obtain a free API key from [Google AI Studio](https://aistudio.google.com/). Set it in your environment or in a `.env` file in your project root:
+
+```bash
+export GEMINI_API_KEY="your-gemini-api-key"
+```
+
+### 3. Initialize Configuration
+Generate `playwright-smart-test.config.json` in your repository root:
+
+```bash
+npx playwright-smart-test init
+```
+
+### 4. Run Analysis or Execute Tests
+
+```bash
+# Analyze PR diff against main branch (preview selection)
+npx playwright-smart-test analyze --base origin/main
+
+# Run only the impacted Playwright tests
+npx playwright-smart-test run --base origin/main
+```
+
+---
+
+## ⚙️ Configuration (`playwright-smart-test.config.json`)
+
+Generate a starter configuration with `npx playwright-smart-test init` or create `playwright-smart-test.config.json` manually:
+
+```json
+{
+  "testDir": "tests",
+  "testMatch": ["**/*.spec.ts", "**/*.test.ts"],
+  "pageObjectsDir": "src/pages",
+  "components": [
+    {
+      "name": "checkout",
+      "patterns": ["src/**/checkout*", "src/**/Checkout*"],
+      "description": "Checkout flow, promo codes, and order calculation"
+    },
+    {
+      "name": "payment",
+      "patterns": ["src/**/payment*", "src/**/billing*"],
+      "description": "Payment gateways, tokenization, and invoices"
+    },
+    {
+      "name": "cart",
+      "patterns": ["src/**/cart*", "src/**/basket*"],
+      "description": "Shopping cart items, inventory checks, and quantities"
+    }
+  ],
+  "safetyRules": {
+    "maxChangedDomainsForFullRun": 8,
+    "maxImpactRatioForFullRun": 0.7,
+    "smokeTag": "@smoke",
+    "smokeSpecPattern": "**/*smoke*.spec.ts",
+    "docsOnlyPatterns": [
+      "**/*.md",
+      "docs/**",
+      "LICENSE",
+      "**/.gitignore",
+      "**/assets/**"
+    ],
+    "fullRunPatterns": []
+  },
+  "ai": {
+    "provider": "gemini",
+    "model": "gemini-3.8-flash",
+    "temperature": 0.2
+  }
+}
+```
+
+> **Model Flexibility**: You can configure any Gemini model (e.g. `gemini-3.8-flash`, `gemini-2.5-flash`, `gemini-1.5-pro`) or override it dynamically via the `GEMINI_MODEL` environment variable.
+
+---
+
+## 🚀 CLI Commands
+
+| Command | Description |
+| :--- | :--- |
+| `playwright-smart-test analyze` | Analyzes Git diff and outputs terminal impact table without executing tests. |
+| `playwright-smart-test run` | Analyzes Git diff and executes **only** the impacted Playwright specs. |
+| `playwright-smart-test comment` | Analyzes diff, generates GitHub Flavored Markdown, and outputs PR report. |
+| `playwright-smart-test init` | Generates a starter `playwright-smart-test.config.json` configuration file. |
+
+### CLI Options
+* `-b, --base <ref>`: Target Git branch or commit to diff against (e.g. `origin/main` or `HEAD~1`).
+* `-h, --head <ref>`: Head Git commit/branch (default: working directory / `HEAD`).
+* `--staged`: Analyze only staged git changes.
+* `-c, --config <path>`: Path to custom configuration file.
+* `-o, --output <path>`: Save report to `.md` or `.json` (e.g. `--output report.md`).
+* `--dry-run`: Prints the generated Playwright test command without running it.
+
+---
+
+## 🔌 GitHub Actions CI/CD Integration
+
+Add this step to your Pull Request workflow (`.github/workflows/regression.yml`):
+
+```yaml
+name: Playwright Smart Regression
+
+on:
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history needed for git diff
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Install Playwright Browsers
+        run: npx playwright install --with-deps
+
+      - name: Run Smart Regression Analysis
+        id: smart-regression
+        env:
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+        run: |
+          npx playwright-smart-test analyze --base "origin/${{ github.base_ref }}" --output pr-report.md
+          npx playwright-smart-test run --base "origin/${{ github.base_ref }}"
+
+      - name: Post PR Comment
+        if: always()
+        uses: thollander/actions-comment-pull-request@v2
+        with:
+          filePath: pr-report.md
+          comment_tag: smart-regression-report
+```
+
+---
+
+## 📊 Sample PR Impact Report
+
+When running `playwright-smart-test comment` or saving with `--output`, the agent produces clean GitHub Flavored Markdown:
+
+```markdown
+## 🤖 Playwright Smart Regression Selection Report
+
+**Risk Level:** 🟠 **HIGH**
+
+| Scope | Identified Areas |
+| :--- | :--- |
+| **Changed Components** | `checkout`, `payment` |
+| **Potentially Impacted Areas** | `cart`, `order-summary` |
+
+### 🧠 AI Semantic Rationale
+- **Direct Impact:** Modified voucher code calculation logic in CheckoutPage.
+- **Ripple Effects:** Discount changes propagate into final payment charge payload.
+
+### 🧪 Selected Regression Tests (3)
+
+| Spec File | Selection Type | Rationale |
+| :--- | :---: | :--- |
+| `tests/checkout.spec.ts` | 🟢 Direct | Directly touches changed component 'checkout'. |
+| `tests/payment.spec.ts` | 🟡 Ripple | Indirectly impacted by ripple effects on domain 'payment'. |
+| `tests/cart.spec.ts` | 🟡 Ripple | Indirectly impacted by ripple effects on domain 'cart'. |
+
+### ⚡ Playwright Execution Command
+```bash
+npx playwright test "tests/checkout.spec.ts" "tests/payment.spec.ts" "tests/cart.spec.ts"
+```
+```
+
+---
+
+## ❓ Frequently Asked Questions
+
+#### What happens if the Gemini API goes down or times out?
+The agent includes a **Safe Default Fallback**: if the API is unreachable, times out after 20 seconds, or encounters a quota limit, the agent safely runs the full Playwright regression suite so your CI pipeline is never blocked or compromised.
+
+#### Does this work with custom Playwright fixtures?
+Yes. Unlike static AST import tools that break on `test.extend<{ page }>`, the LLM Brain reads test files, test signatures, and tags directly. It understands fixture context without being tricked by shared `fixtures.ts` files.
+
+#### Does it run tests if I only edit `README.md` or static assets?
+No. **Guardrail 1 (Docs Fast-Path)** intercepts documentation and asset changes in 50ms, exiting with 0 tests run and 0 API calls.
+
+---
+
+## 📄 License
+
+MIT © [Ujjwal S S](https://github.com/Ujjwal-S-S)

package/dist/ai/ai-analyzer.d.ts

@@ -0,0 +1,17 @@
+import { AIImpactAnalysis, DiffFile, SpecCatalogEntry, SmartRegressionConfig } from '../config/schema.js';
+export declare class AISemanticAnalyzer {
+    private config;
+    private genAI?;
+    private apiKey?;
+    private modelName;
+    constructor(config: SmartRegressionConfig);
+    analyzeImpact(changedFiles: DiffFile[], catalog: SpecCatalogEntry[]): Promise<AIImpactAnalysis>;
+    private callGeminiWithModel;
+    buildPrompt(changedFiles: DiffFile[], catalog: SpecCatalogEntry[]): string;
+    /**
+     * Deterministic semantic heuristic engine
+     * Applied when no network/API key is provided or as offline fallback.
+     * Understands domain relationships like checkout -> payment + basket.
+     */
+    inferSemanticImpactLocally(changedFiles: DiffFile[], catalog: SpecCatalogEntry[]): AIImpactAnalysis;
+}

package/dist/ai/ai-analyzer.js

@@ -0,0 +1,224 @@
+import { GoogleGenAI } from '@google/genai';
+import { AIImpactAnalysisSchema, } from '../config/schema.js';
+export class AISemanticAnalyzer {
+    config;
+    genAI;
+    apiKey;
+    modelName;
+    constructor(config) {
+        this.config = config;
+        this.apiKey = config.ai.apiKey || process.env.GEMINI_API_KEY;
+        this.modelName = config.ai.model || 'gemini-3.8-flash';
+        if (this.apiKey) {
+            this.genAI = new GoogleGenAI({ apiKey: this.apiKey });
+        }
+    }
+    async analyzeImpact(changedFiles, catalog) {
+        if (changedFiles.length === 0) {
+            return {
+                changedComponents: [],
+                impactedComponents: [],
+                directReason: 'No changed files detected in PR diff.',
+                rippleEffectReason: 'No regression tests needed.',
+                riskScore: 'LOW',
+                requiresFullRegression: false,
+                confidenceScore: 'HIGH',
+                recommendedTests: [],
+            };
+        }
+        if (this.genAI && this.apiKey) {
+            const candidateModels = [this.modelName, 'gemini-2.0-flash', 'gemini-1.5-flash'];
+            const uniqueModels = Array.from(new Set(candidateModels));
+            for (const model of uniqueModels) {
+                for (let attempt = 1; attempt <= 3; attempt++) {
+                    try {
+                        return await this.callGeminiWithModel(model, changedFiles, catalog);
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        const isRetryable = msg.includes('503') ||
+                            msg.includes('429') ||
+                            msg.includes('high demand') ||
+                            msg.includes('UNAVAILABLE') ||
+                            msg.includes('overloaded');
+                        if (isRetryable && attempt < 3) {
+                            const delay = attempt * 1500;
+                            console.warn(`[smart-test] Gemini ${model} temporarily busy (503/429). Retrying in ${delay}ms (attempt ${attempt}/3)...`);
+                            await new Promise((res) => setTimeout(res, delay));
+                        }
+                        else if (attempt === 3) {
+                            console.warn(`[smart-test] Model ${model} unavailable after 3 attempts (${msg}).`);
+                            break;
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                }
+            }
+            console.warn(`[smart-test] All Gemini model attempts exhausted. Falling back to built-in semantic inference.`);
+        }
+        return this.inferSemanticImpactLocally(changedFiles, catalog);
+    }
+    async callGeminiWithModel(modelName, changedFiles, catalog) {
+        const prompt = this.buildPrompt(changedFiles, catalog);
+        const timeoutMs = 20000;
+        const generatePromise = this.genAI.models.generateContent({
+            model: modelName,
+            contents: prompt,
+            config: {
+                responseMimeType: 'application/json',
+                temperature: this.config.ai.temperature ?? 0.2,
+            },
+        });
+        const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Gemini request timed out after ${timeoutMs}ms`)), timeoutMs));
+        const response = await Promise.race([generatePromise, timeoutPromise]);
+        const responseText = response.text || '';
+        const parsedJson = JSON.parse(responseText);
+        return AIImpactAnalysisSchema.parse(parsedJson);
+    }
+    buildPrompt(changedFiles, catalog) {
+        const lockfileNames = ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lockb'];
+        const diffsSummary = changedFiles.map((f) => {
+            const isLockfile = lockfileNames.some((l) => f.path.endsWith(l));
+            const patchPreview = isLockfile
+                ? '(Lockfile content omitted - dependency versions updated)'
+                : f.patch
+                    ? f.patch.slice(0, 3000)
+                    : '(No patch content)';
+            return `File: ${f.path} [${f.status}] (+${f.additions}/-${f.deletions})\nDiff:\n${patchPreview}`;
+        }).join('\n\n--- FILE BREAK ---\n\n');
+        const componentRulesSummary = (this.config.components && this.config.components.length > 0)
+            ? `\nPROJECT COMPONENT MAPPINGS:\n` +
+                this.config.components.map((c) => `- Component '${c.name}': patterns [${c.patterns.join(', ')}]${c.description ? ` (${c.description})` : ''}`).join('\n') + '\n'
+            : '';
+        const catalogSummary = catalog.map((s) => {
+            return `- Spec: ${s.filePath}\n  Tests: ${s.testTitles.slice(0, 5).join(', ') || 'N/A'}\n  Tags: ${s.tags.join(', ') || 'none'}\n  Imports: ${s.importedModules.join(', ')}`;
+        }).join('\n');
+        return `You are a Principal Test Automation Architect and AI Regression Agent for Playwright.
+Analyze the following Pull Request Git diff and determine the exact regression test suite required.
+
+PR MODIFIED FILES & DIFFS:
+${diffsSummary}
+${componentRulesSummary}
+AVAILABLE PLAYWRIGHT TEST SPECS IN THE REPOSITORY:
+${catalogSummary}
+
+DOMAIN & WORKFLOW HEURISTICS TO EVALUATE:
+1. Identify all functional components changed (e.g. checkout, cart/basket, payment, auth, dashboard).
+2. Trace ripple effects:
+   - For example: if 'checkout' changes, examine if upstream pre-conditions (basket/cart validation, order calculations) and downstream steps (payment processing, order confirmation) are impacted.
+   - If an auth token or session logic changes, examine checkout, user profile, and protected dashboards.
+3. Playwright config evaluation:
+   - If playwright.config.* was modified: inspect whether it changes global runtime behavior (such as baseURL, globalSetup, storageState, or browser projects matrix). If so, set requiresFullRegression = true.
+   - If it only changes non-functional settings (such as timeouts, retries, reporters), do NOT trigger a full regression; select only specs affected by accompanying changes.
+4. Uncertainty & Blast Radius:
+   - If changes alter shared core infrastructure where blast radius cannot be safely isolated, or if you cannot determine the impact, set requiresFullRegression = true and confidenceScore = "LOW".
+5. Select the minimal necessary Playwright test specs from the catalog that MUST run to guarantee no regression.
+6. Assess the overall risk score (LOW, MEDIUM, HIGH, CRITICAL).
+
+CRITICAL REQUIREMENT:
+Respond ONLY with a valid JSON object matching this schema:
+{
+  "changedComponents": string[],
+  "impactedComponents": string[],
+  "directReason": string,
+  "rippleEffectReason": string,
+  "riskScore": "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
+  "requiresFullRegression": boolean,
+  "confidenceScore": "HIGH" | "MEDIUM" | "LOW",
+  "recommendedTests": [
+    {
+      "specFile": string (must match an existing spec from the catalog),
+      "testTitles": string[] (optional specific tests),
+      "reason": string,
+      "isIndirectImpact": boolean
+    }
+  ]
+}`;
+    }
+    /**
+     * Deterministic semantic heuristic engine
+     * Applied when no network/API key is provided or as offline fallback.
+     * Understands domain relationships like checkout -> payment + basket.
+     */
+    inferSemanticImpactLocally(changedFiles, catalog) {
+        const changedComponents = new Set();
+        const impactedComponents = new Set();
+        const recommendedTests = [];
+        const domainRippleMap = {
+            checkout: ['payment', 'cart', 'basket', 'order'],
+            payment: ['checkout', 'order', 'billing'],
+            cart: ['checkout', 'basket', 'inventory'],
+            basket: ['checkout', 'cart', 'inventory'],
+            auth: ['login', 'profile', 'checkout', 'dashboard'],
+            login: ['auth', 'dashboard', 'checkout'],
+            product: ['catalog', 'search', 'cart'],
+        };
+        for (const file of changedFiles) {
+            const lower = file.path.toLowerCase();
+            for (const domain of Object.keys(domainRippleMap)) {
+                if (lower.includes(domain)) {
+                    changedComponents.add(domain);
+                }
+            }
+        }
+        if (changedComponents.size === 0) {
+            for (const file of changedFiles) {
+                const parts = file.path.split('/');
+                const name = parts[parts.length - 1].replace(/\.[^/.]+$/, '');
+                changedComponents.add(name);
+            }
+        }
+        for (const comp of Array.from(changedComponents)) {
+            const ripples = domainRippleMap[comp] || [];
+            for (const r of ripples) {
+                impactedComponents.add(r);
+            }
+        }
+        for (const spec of catalog) {
+            const lowerSpec = spec.filePath.toLowerCase();
+            let matchedDirect = false;
+            let matchedIndirect = false;
+            let reason = '';
+            for (const comp of Array.from(changedComponents)) {
+                if (lowerSpec.includes(comp) || spec.tags.some((t) => t.toLowerCase().includes(comp))) {
+                    matchedDirect = true;
+                    reason = `Directly touches changed component '${comp}'.`;
+                    break;
+                }
+            }
+            if (!matchedDirect) {
+                for (const ripple of Array.from(impactedComponents)) {
+                    if (lowerSpec.includes(ripple) || spec.tags.some((t) => t.toLowerCase().includes(ripple))) {
+                        matchedIndirect = true;
+                        reason = `Indirectly impacted by ripple effects on domain '${ripple}'.`;
+                        break;
+                    }
+                }
+            }
+            if (matchedDirect || matchedIndirect) {
+                recommendedTests.push({
+                    specFile: spec.filePath,
+                    testTitles: spec.testTitles.slice(0, 3),
+                    reason,
+                    isIndirectImpact: matchedIndirect,
+                });
+            }
+        }
+        const changedList = Array.from(changedComponents);
+        const impactedList = Array.from(impactedComponents);
+        return {
+            changedComponents: changedList,
+            impactedComponents: impactedList,
+            directReason: `PR modified files in component(s): ${changedList.join(', ')}.`,
+            rippleEffectReason: impactedList.length > 0
+                ? `Workflow analysis identified potential ripple effects across connected business flows: ${impactedList.join(', ')}.`
+                : 'Isolated component changes without cross-domain ripple effects.',
+            riskScore: changedList.includes('checkout') || changedList.includes('payment') ? 'HIGH' : 'MEDIUM',
+            requiresFullRegression: false,
+            confidenceScore: 'MEDIUM',
+            recommendedTests,
+        };
+    }
+}

package/dist/catalog/test-catalog.d.ts

@@ -0,0 +1,8 @@
+import { SpecCatalogEntry } from '../config/schema.js';
+export declare class TestCatalogIndexer {
+    private cwd;
+    constructor(cwd?: string);
+    scanTestFiles(testDir?: string, testMatch?: string[]): Promise<SpecCatalogEntry[]>;
+    private recursiveScan;
+    private indexSpecFile;
+}

package/dist/catalog/test-catalog.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { glob } from 'glob';
+import ts from 'typescript';
+export class TestCatalogIndexer {
+    cwd;
+    constructor(cwd = process.cwd()) {
+        this.cwd = cwd;
+    }
+    async scanTestFiles(testDir = 'tests', testMatch = ['**/*.spec.ts', '**/*.test.ts']) {
+        const fullTestDir = path.resolve(this.cwd, testDir);
+        if (!fs.existsSync(fullTestDir)) {
+            return [];
+        }
+        const matchedFiles = [];
+        for (const pattern of testMatch) {
+            try {
+                const found = await glob(pattern, {
+                    cwd: fullTestDir,
+                    nodir: true,
+                    posix: true,
+                });
+                matchedFiles.push(...found);
+            }
+            catch {
+                const files = this.recursiveScan(fullTestDir);
+                for (const f of files) {
+                    if (f.endsWith('.spec.ts') || f.endsWith('.test.ts')) {
+                        matchedFiles.push(path.relative(fullTestDir, f).replace(/\\/g, '/'));
+                    }
+                }
+            }
+        }
+        const uniqueFiles = Array.from(new Set(matchedFiles)).map((rel) => path.join(testDir, rel).replace(/\\/g, '/'));
+        const catalog = [];
+        for (const fileRelPath of uniqueFiles) {
+            const fullPath = path.resolve(this.cwd, fileRelPath);
+            if (fs.existsSync(fullPath)) {
+                const entry = this.indexSpecFile(fullPath, fileRelPath);
+                catalog.push(entry);
+            }
+        }
+        return catalog;
+    }
+    recursiveScan(dir) {
+        const results = [];
+        if (!fs.existsSync(dir))
+            return results;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                results.push(...this.recursiveScan(full));
+            }
+            else if (entry.isFile()) {
+                results.push(full);
+            }
+        }
+        return results;
+    }
+    indexSpecFile(fullPath, relativePath) {
+        const content = fs.readFileSync(fullPath, 'utf8');
+        const sourceFile = ts.createSourceFile(fullPath, content, ts.ScriptTarget.Latest, true);
+        const testTitles = [];
+        const tags = [];
+        const importedModules = [];
+        const visit = (node) => {
+            if (ts.isImportDeclaration(node)) {
+                if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+                    importedModules.push(node.moduleSpecifier.text);
+                }
+            }
+            if (ts.isCallExpression(node)) {
+                const expr = node.expression;
+                let callName = '';
+                if (ts.isIdentifier(expr)) {
+                    callName = expr.text;
+                }
+                else if (ts.isPropertyAccessExpression(expr)) {
+                    callName = `${expr.expression.getText(sourceFile)}.${expr.name.text}`;
+                }
+                if (callName === 'test' ||
+                    callName === 'test.describe' ||
+                    callName === 'test.only' ||
+                    callName === 'it' ||
+                    callName === 'describe') {
+                    const firstArg = node.arguments[0];
+                    if (firstArg && (ts.isStringLiteral(firstArg) || ts.isNoSubstitutionTemplateLiteral(firstArg))) {
+                        testTitles.push(firstArg.text);
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+        const tagMatches = content.match(/@[a-zA-Z0-9_\-]+/g);
+        if (tagMatches) {
+            for (const t of tagMatches) {
+                if (!tags.includes(t)) {
+                    tags.push(t);
+                }
+            }
+        }
+        return {
+            filePath: relativePath,
+            testTitles,
+            tags,
+            importedModules,
+        };
+    }
+}

package/dist/cli/index.d.ts

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