@qulib/core 0.7.0 → 0.9.0

package/README.md

@@ -140,16 +140,38 @@ After a normal **`analyze`**, `output/report.json` includes **`gapAnalysis.costI
 Re-print that block from disk:
 
 ```bash
-npx tsx src/cli/index.ts cost doctor
-# or: npx tsx src/cli/index.ts cost doctor --report output/report.json
+qulib cost doctor
+# or: qulib cost doctor --report output/report.json
 ```
 
 ## CLI (from npm)
 
+**Release confidence — the flagship command:**
+
+```bash
+npx @qulib/core confidence --url https://example.com
+```
+
+Returns ship / caution / hold / block with a 0–100 score, top risks, and recommended next checks. Add `--repo` to also score test-automation maturity and API coverage.
+
+**Analyze (full gap report):**
+
 ```bash
 npx @qulib/core analyze --url https://example.com
 ```
 
+**Scaffold a test suite:**
+
+```bash
+npx @qulib/core scaffold --url https://example.com --framework cypress-e2e
+```
+
+**Score automation maturity (repo-only, no URL needed):**
+
+```bash
+npx @qulib/core score-automation --repo /path/to/repo
+```
+
 Use `npx playwright install chromium` the first time you scan (Playwright is a dependency).
 
 ## Programmatic API
@@ -344,10 +366,13 @@ Use these as conservative reference numbers:
 
 | Tool | When to use | Key input |
 |---|---|---|
-| `analyze_app` | Main QA scan for release confidence + gaps | `url`, optional `auth`, optional LLM knobs |
-| `detect_auth` | Fast single-pass auth pattern guess | `url`, optional `timeoutMs` |
+| **`qulib_score_confidence`** | **Flagship.** Fused verdict (ship/caution/hold/block) from all collectors | `url` and/or `repoPath`, optional `includeViews.replay` |
+| `analyze_app` | Live-app QA scan: release confidence + gaps + a11y | `url`, optional `auth`, optional LLM knobs |
+| `qulib_score_automation` | Score local repo test-automation maturity | absolute `repoPath`, optional `includeFullDimensions` |
+| `qulib_score_api` | Discover API endpoints and score their test coverage | absolute `repoPath`, optional `enableTier3`, `includeEndpointDetail` |
+| `qulib_scaffold_tests` | Generate Cypress/Playwright scaffold from a live URL | `url`, optional `framework`, `maxPagesToScan`, `recipes` |
 | `explore_auth` | Deeper auth-path discovery on unfamiliar apps | `url`, optional `timeoutMs` |
-| `qulib_score_automation` | Score local repo automation maturity | absolute `repoPath`, optional `includeFullDimensions` |
+| `detect_auth` | Fast single-pass auth pattern guess | `url`, optional `timeoutMs` |
 
 ## Output directories
 

package/bin/qulib.js

@@ -5,10 +5,9 @@ import { dirname, resolve } from 'node:path';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const cliPath = resolve(__dirname, '../src/cli/index.ts');
+const cliPath = resolve(__dirname, '../dist/cli/index.js');
 
-const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-const child = spawn(npxCmd, ['tsx', cliPath, ...process.argv.slice(2)], {
+const child = spawn(process.execPath, [cliPath, ...process.argv.slice(2)], {
   stdio: 'inherit',
 });
 

package/dist/__tests__/fixtures/api-fixture-repo/app/api/orders/route.d.ts

@@ -0,0 +1,7 @@
+export declare function DELETE(request: {
+    url: string;
+}): Promise<{
+    deleted: boolean;
+    id: string | null;
+}>;
+//# sourceMappingURL=route.d.ts.map

package/dist/__tests__/fixtures/api-fixture-repo/app/api/orders/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../../../src/__tests__/fixtures/api-fixture-repo/app/api/orders/route.ts"],"names":[],"mappings":"AAGA,wBAAsB,MAAM,CAAC,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE;;;GAIpD"}

package/dist/__tests__/fixtures/api-fixture-repo/app/api/orders/route.js

@@ -0,0 +1,7 @@
+// Fixture: Next.js App Router API route for orders (DELETE only — high severity untested)
+// This file is a static analysis fixture only — not compiled.
+export async function DELETE(request) {
+    const url = new URL(request.url);
+    const id = url.searchParams.get('id');
+    return { deleted: true, id };
+}

package/dist/__tests__/fixtures/api-fixture-repo/app/api/users/route.d.ts

@@ -0,0 +1,10 @@
+export declare function GET(): Promise<{
+    users: never[];
+}>;
+export declare function POST(request: {
+    json: () => Promise<unknown>;
+}): Promise<{
+    created: boolean;
+    user: unknown;
+}>;
+//# sourceMappingURL=route.d.ts.map

package/dist/__tests__/fixtures/api-fixture-repo/app/api/users/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../../../src/__tests__/fixtures/api-fixture-repo/app/api/users/route.ts"],"names":[],"mappings":"AAGA,wBAAsB,GAAG;;GAExB;AAED,wBAAsB,IAAI,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE;;;GAGnE"}

package/dist/__tests__/fixtures/api-fixture-repo/app/api/users/route.js

@@ -0,0 +1,9 @@
+// Fixture: Next.js App Router API route for users
+// This file is a static analysis fixture only — not compiled.
+export async function GET() {
+    return { users: [] };
+}
+export async function POST(request) {
+    const body = await request.json();
+    return { created: true, user: body };
+}

package/dist/__tests__/fixtures/api-fixture-repo/pages/api/health.d.ts

@@ -0,0 +1,9 @@
+export default function handler(req: {
+    method?: string;
+}, res: {
+    status: (code: number) => {
+        json: (data: unknown) => void;
+        end: () => void;
+    };
+}): void;
+//# sourceMappingURL=health.d.ts.map

package/dist/__tests__/fixtures/api-fixture-repo/pages/api/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../../../../src/__tests__/fixtures/api-fixture-repo/pages/api/health.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,OAAO,UAAU,OAAO,CAC7B,GAAG,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,EACxB,GAAG,EAAE;IAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;QAAC,GAAG,EAAE,MAAM,IAAI,CAAA;KAAE,CAAA;CAAE,QAOtF"}

package/dist/__tests__/fixtures/api-fixture-repo/pages/api/health.js

@@ -0,0 +1,10 @@
+// Fixture: Next.js Pages API route
+// This file is a static analysis fixture only — not compiled.
+export default function handler(req, res) {
+    if (req.method === 'GET') {
+        res.status(200).json({ status: 'ok' });
+    }
+    else {
+        res.status(405).end();
+    }
+}

package/dist/__tests__/playwright-available.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Lightweight helper used by test files that require a Playwright Chromium
+ * installation. Checks for the browser at the filesystem level — no side
+ * effects, no subprocess launch.
+ *
+ * Two ways to skip:
+ *   1. Set PLAYWRIGHT_SKIP=1 in the environment — explicit opt-out, useful for
+ *      fresh-clone CI jobs that intentionally skip browser tests.
+ *   2. The Playwright Chromium executable is simply absent from the expected
+ *      install path (e.g. the developer never ran `npx playwright install`).
+ *
+ * Usage in test files:
+ *
+ *   import { chromiumAvailable, CHROMIUM_SKIP_REASON } from './playwright-available.js';
+ *
+ *   test('my browser test', { skip: !chromiumAvailable, skipMessage: CHROMIUM_SKIP_REASON }, () => { ... });
+ *
+ * Or for a subtree of tests (t.before guard):
+ *
+ *   if (!chromiumAvailable) { t.skip(); return; }
+ */
+/**
+ * True when a Playwright Chromium browser binary is present on disk AND the
+ * caller has not set PLAYWRIGHT_SKIP=1.
+ */
+export declare const chromiumAvailable: boolean;
+/**
+ * Human-readable reason string passed to `t.skip()` / `skipMessage` so the
+ * skip is self-documenting in test output.
+ */
+export declare const CHROMIUM_SKIP_REASON: string;
+//# sourceMappingURL=playwright-available.d.ts.map

package/dist/__tests__/playwright-available.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-available.d.ts","sourceRoot":"","sources":["../../src/__tests__/playwright-available.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAC0C,CAAC;AAE3E;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAEqE,CAAC"}

package/dist/__tests__/playwright-available.js

@@ -0,0 +1,35 @@
+/**
+ * Lightweight helper used by test files that require a Playwright Chromium
+ * installation. Checks for the browser at the filesystem level — no side
+ * effects, no subprocess launch.
+ *
+ * Two ways to skip:
+ *   1. Set PLAYWRIGHT_SKIP=1 in the environment — explicit opt-out, useful for
+ *      fresh-clone CI jobs that intentionally skip browser tests.
+ *   2. The Playwright Chromium executable is simply absent from the expected
+ *      install path (e.g. the developer never ran `npx playwright install`).
+ *
+ * Usage in test files:
+ *
+ *   import { chromiumAvailable, CHROMIUM_SKIP_REASON } from './playwright-available.js';
+ *
+ *   test('my browser test', { skip: !chromiumAvailable, skipMessage: CHROMIUM_SKIP_REASON }, () => { ... });
+ *
+ * Or for a subtree of tests (t.before guard):
+ *
+ *   if (!chromiumAvailable) { t.skip(); return; }
+ */
+import { chromium } from '@playwright/test';
+import { existsSync } from 'node:fs';
+/**
+ * True when a Playwright Chromium browser binary is present on disk AND the
+ * caller has not set PLAYWRIGHT_SKIP=1.
+ */
+export const chromiumAvailable = !process.env['PLAYWRIGHT_SKIP'] && existsSync(chromium.executablePath());
+/**
+ * Human-readable reason string passed to `t.skip()` / `skipMessage` so the
+ * skip is self-documenting in test output.
+ */
+export const CHROMIUM_SKIP_REASON = process.env['PLAYWRIGHT_SKIP']
+    ? 'PLAYWRIGHT_SKIP=1 is set — browser tests opted out. Unset PLAYWRIGHT_SKIP to enable.'
+    : 'Playwright Chromium is not installed. Run `npx playwright install chromium` to enable these tests.';

package/dist/adapters/api-adapter.d.ts

@@ -1,8 +1,34 @@
 import type { TestAdapter } from './adapter.interface.js';
 import type { NeutralScenario, GeneratedTest } from '../schemas/gap-analysis.schema.js';
+import type { ApiSurface } from '../tools/repo/api-surface.js';
+/**
+ * TestAdapter implementation for API testing via supertest.
+ *
+ * `render` / `renderAll`: convert gap-analysis NeutralScenarios that carry
+ *   `api-call` steps into supertest specs. Used by the standard adapter pipeline.
+ *
+ * `scaffoldApiTests`: separate entry point for the repo-first API toolshed flow.
+ *   Accepts discovered endpoints (ApiSurface) and generates a ready-to-run
+ *   supertest test file — NOT URL-based.
+ */
 export declare class ApiAdapter implements TestAdapter {
     readonly adapterType = "api";
     render(scenario: NeutralScenario): GeneratedTest;
     renderAll(scenarios: NeutralScenario[]): GeneratedTest[];
+    /**
+     * Generate a supertest-based test file from discovered API endpoints.
+     * This is the repo-first entry point — does NOT require a running URL.
+     *
+     * Endpoints are grouped into a single test file. Each endpoint gets one
+     * `it` block that:
+     *   - Makes the correct HTTP method call
+     *   - Asserts status < 500 (smoke-level assertion, safely runnable against a live app)
+     *   - POST/PUT/PATCH endpoints include a TODO for request body
+     *
+     * The file is NOT associated with a NeutralScenario; it uses a fixed scenarioId.
+     */
+    scaffoldApiTests(apiSurface: ApiSurface, options?: {
+        appImportPath?: string;
+    }): GeneratedTest;
 }
 //# sourceMappingURL=api-adapter.d.ts.map

package/dist/adapters/api-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/api-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAExF,qBAAa,UAAW,YAAW,WAAW;IAC5C,QAAQ,CAAC,WAAW,SAAS;IAE7B,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IAIhD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE;CAGzD"}
+{"version":3,"file":"api-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/api-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,KAAK,EAAsB,UAAU,EAAE,MAAM,8BAA8B,CAAC;AASnF;;;;;;;;;GASG;AACH,qBAAa,UAAW,YAAW,WAAW;IAC5C,QAAQ,CAAC,WAAW,SAAS;IAE7B,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IAuDhD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE;IAIxD;;;;;;;;;;;OAWG;IACH,gBAAgB,CACd,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO,GACvC,aAAa;CAoDjB"}

package/dist/adapters/api-adapter.js

@@ -1,9 +1,163 @@
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * TestAdapter implementation for API testing via supertest.
+ *
+ * `render` / `renderAll`: convert gap-analysis NeutralScenarios that carry
+ *   `api-call` steps into supertest specs. Used by the standard adapter pipeline.
+ *
+ * `scaffoldApiTests`: separate entry point for the repo-first API toolshed flow.
+ *   Accepts discovered endpoints (ApiSurface) and generates a ready-to-run
+ *   supertest test file — NOT URL-based.
+ */
 export class ApiAdapter {
     adapterType = 'api';
     render(scenario) {
-        throw new Error('Not implemented');
+        const slug = slugify(scenario.title);
+        const filename = `${slug}.api.test.ts`;
+        const stepLines = scenario.steps
+            .map((step) => {
+            if (step.action === 'api-call') {
+                const path = step.target ?? step.value ?? '/';
+                return [
+                    `    // ${step.description}`,
+                    `    const res = await request(app).get(${JSON.stringify(path)});`,
+                    `    expect(res.status).toBe(200);`,
+                ].join('\n');
+            }
+            if (step.action === 'navigate') {
+                const path = step.target ?? step.value ?? '/';
+                return [
+                    `    // ${step.description}`,
+                    `    const res = await request(app).get(${JSON.stringify(path)});`,
+                    `    expect(res.status).toBeLessThan(500);`,
+                ].join('\n');
+            }
+            return `    // TODO (${step.action}): ${step.description}`;
+        })
+            .join('\n');
+        const code = [
+            `// ${scenario.description}`,
+            `// qulib-generated — scenario: ${scenario.id}`,
+            ``,
+            `import request from 'supertest';`,
+            `import { describe, it, expect } from 'vitest';`,
+            ``,
+            `// TODO: import or create your Express/Fastify/Hono app here`,
+            `// import { app } from '../src/app.js';`,
+            `declare const app: unknown;`,
+            ``,
+            `describe(${JSON.stringify(scenario.title)}, () => {`,
+            `  it(${JSON.stringify(scenario.description)}, async () => {`,
+            stepLines || `    // no api-call steps — add assertions for: ${scenario.targetPath}`,
+            `  });`,
+            `});`,
+            ``,
+        ].join('\n');
+        return {
+            scenarioId: scenario.id,
+            adapter: 'api',
+            filename,
+            code,
+            source: 'template',
+            outputPath: `tests/api/${filename}`,
+        };
     }
     renderAll(scenarios) {
-        throw new Error('Not implemented');
+        return scenarios.map((s) => this.render(s));
+    }
+    /**
+     * Generate a supertest-based test file from discovered API endpoints.
+     * This is the repo-first entry point — does NOT require a running URL.
+     *
+     * Endpoints are grouped into a single test file. Each endpoint gets one
+     * `it` block that:
+     *   - Makes the correct HTTP method call
+     *   - Asserts status < 500 (smoke-level assertion, safely runnable against a live app)
+     *   - POST/PUT/PATCH endpoints include a TODO for request body
+     *
+     * The file is NOT associated with a NeutralScenario; it uses a fixed scenarioId.
+     */
+    scaffoldApiTests(apiSurface, options = {}) {
+        const appImport = options.appImportPath ?? '../src/app.js';
+        const endpoints = apiSurface.endpoints;
+        if (endpoints.length === 0) {
+            const code = [
+                `// qulib-generated API scaffold — no endpoints discovered`,
+                `// qulib-generated — repo: ${apiSurface.repoPath}`,
+                ``,
+                `// No API endpoints were discovered in this repository.`,
+                `// If your app has REST endpoints, ensure they are declared in a supported`,
+                `// framework (Next.js route.ts, Express, Fastify, NestJS) or an OpenAPI spec.`,
+                ``,
+            ].join('\n');
+            return {
+                scenarioId: 'qulib-api-scaffold',
+                adapter: 'api',
+                filename: 'api-scaffold.test.ts',
+                code,
+                source: 'template',
+                outputPath: 'tests/api/api-scaffold.test.ts',
+            };
+        }
+        const itBlocks = endpoints.map((ep) => renderEndpointTest(ep)).join('\n\n');
+        const code = [
+            `// qulib-generated API scaffold — ${endpoints.length} endpoint(s) discovered`,
+            `// qulib-generated — repo: ${apiSurface.repoPath}`,
+            `// Discovery tier breakdown: ${describeDiscoveryTiers(endpoints)}`,
+            ``,
+            `import request from 'supertest';`,
+            `import { describe, it, expect, beforeAll, afterAll } from 'vitest';`,
+            ``,
+            `// TODO: replace with your actual app export`,
+            `import { app } from ${JSON.stringify(appImport)};`,
+            ``,
+            `describe('API surface smoke tests (qulib-generated)', () => {`,
+            itBlocks,
+            `});`,
+            ``,
+        ].join('\n');
+        return {
+            scenarioId: 'qulib-api-scaffold',
+            adapter: 'api',
+            filename: 'api-scaffold.test.ts',
+            code,
+            source: 'template',
+            outputPath: 'tests/api/api-scaffold.test.ts',
+        };
     }
 }
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function renderEndpointTest(ep) {
+    const method = ep.method === 'unknown' ? 'GET' : ep.method;
+    const methodLower = method.toLowerCase();
+    const hasBody = method === 'POST' || method === 'PUT' || method === 'PATCH';
+    const sourceLine = `  // Source: ${ep.sourceFile} (${ep.sourceTier}, confidence: ${ep.confidence})`;
+    const itTitle = `${method} ${ep.path}`;
+    const requestLine = hasBody
+        ? `      const res = await request(app).${methodLower}(${JSON.stringify(ep.path)});\n      // TODO: add request body — e.g. .send({ ... })`
+        : `      const res = await request(app).${methodLower}(${JSON.stringify(ep.path)});`;
+    const summaryLine = ep.summary ? `  // ${ep.summary}\n` : '';
+    return [
+        summaryLine + sourceLine,
+        `  it(${JSON.stringify(itTitle)}, async () => {`,
+        requestLine,
+        `      expect(res.status).toBeLessThan(500);`,
+        `  });`,
+    ].join('\n');
+}
+function describeDiscoveryTiers(endpoints) {
+    const counts = { openapi: 0, framework: 0, heuristic: 0 };
+    for (const ep of endpoints)
+        counts[ep.sourceTier]++;
+    return Object.entries(counts)
+        .filter(([, v]) => v > 0)
+        .map(([k, v]) => `${v} ${k}`)
+        .join(', ');
+}

package/dist/adapters/ci-results-adapter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * CI-results evidence adapter (P4 — evidence collectors).
+ *
+ * Maps a CI run summary (test pass/fail counts, build status, optional flakiness
+ * data) into an `EvidenceItem` for `computeReleaseConfidence`, using the
+ * `ci-results` source kind reserved in confidence.schema.ts.
+ *
+ * Design:
+ *   - Pure function — no I/O, no side effects. The caller owns fetching the CI data
+ *     (e.g. from the `gh` API or a CI provider webhook); this adapter scores + maps.
+ *   - Applicability:
+ *       `applicable`     — a real run with ≥1 test executed
+ *       `not_applicable` — no CI run on record for this ref (e.g. no CI configured)
+ *       `unknown`        — run exists but results are incomplete/in-progress
+ *   - Score formula: pass-rate * build-weight * freshness-factor
+ *       pass-rate     = passed / (passed + failed + errored)  [0..1]
+ *       build-weight  = 0.85 if build succeeded, 0.0 if build failed (a build failure
+ *                       overrides the test pass-rate — tests that never ran are not "passing")
+ *       freshness      = 1.0 when ageSeconds < FRESH_THRESHOLD, decaying linearly to
+ *                       MIN_FRESHNESS over STALE_THRESHOLD. Beyond STALE_THRESHOLD the
+ *                       applicability is coerced to `unknown` (matches §2.6 rule 3 of the spec).
+ *   - A build failure OR 0 tests passing marks evidence ['critical'] and forces a
+ *     blocking recommendation (the aggregator uses recommendations for narrative).
+ *   - Multi-tenant: tenantId flows through unchanged (caller sets it on the EvidenceItem
+ *     via the `collector.tool` string; the full tenant stamp is the subject, not the item).
+ */
+import type { EvidenceItem } from '../schemas/confidence.schema.js';
+/**
+ * Raw CI run data the caller provides (from `gh run view --json`, provider API, etc.).
+ * Only the counts matter for scoring; everything else is for evidence strings + provenance.
+ */
+export interface CiRunInput {
+    /** ISO-8601 timestamp when the run completed. */
+    completedAt: string;
+    /** Whether the CI build step itself succeeded (compilation, lint, etc. — before tests). */
+    buildPassed: boolean;
+    /** Number of test cases that passed. */
+    testsPassed: number;
+    /** Number of test cases that failed (hard). */
+    testsFailed: number;
+    /** Number of test cases that errored (infra/setup failure, not assertion failure). */
+    testsErrored: number;
+    /**
+     * Optional: number of tests that were flaky (passed on retry). Presence lowers score
+     * slightly but doesn't fail the run — flaky tests are a warn, not a block.
+     */
+    testsFlaky?: number;
+    /**
+     * Optional: CI provider URL for the run (e.g. `https://github.com/…/actions/runs/…`).
+     * Never fabricated — omit rather than invent.
+     */
+    runUrl?: string;
+    /** Optional: CI workflow/pipeline name for the evidence string. */
+    workflowName?: string;
+    /**
+     * Optional: collector freshness budget override (seconds). Defaults to 24 h for stale.
+     */
+    staleAfterSeconds?: number;
+}
+/**
+ * Produce a `ci-results` EvidenceItem from a raw CI run summary.
+ *
+ * Deterministic and pure. Returns `not_applicable` when the run is absent, `unknown`
+ * when stale or incomplete, and `applicable` with a real score otherwise.
+ */
+export declare function ciResultsToEvidence(run: CiRunInput, collectedAt?: string): EvidenceItem;
+//# sourceMappingURL=ci-results-adapter.d.ts.map

package/dist/adapters/ci-results-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-results-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/ci-results-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,iCAAiC,CAAC;AASxF;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,WAAW,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY,CA+GvF"}

package/dist/adapters/ci-results-adapter.js

@@ -0,0 +1,143 @@
+/**
+ * CI-results evidence adapter (P4 — evidence collectors).
+ *
+ * Maps a CI run summary (test pass/fail counts, build status, optional flakiness
+ * data) into an `EvidenceItem` for `computeReleaseConfidence`, using the
+ * `ci-results` source kind reserved in confidence.schema.ts.
+ *
+ * Design:
+ *   - Pure function — no I/O, no side effects. The caller owns fetching the CI data
+ *     (e.g. from the `gh` API or a CI provider webhook); this adapter scores + maps.
+ *   - Applicability:
+ *       `applicable`     — a real run with ≥1 test executed
+ *       `not_applicable` — no CI run on record for this ref (e.g. no CI configured)
+ *       `unknown`        — run exists but results are incomplete/in-progress
+ *   - Score formula: pass-rate * build-weight * freshness-factor
+ *       pass-rate     = passed / (passed + failed + errored)  [0..1]
+ *       build-weight  = 0.85 if build succeeded, 0.0 if build failed (a build failure
+ *                       overrides the test pass-rate — tests that never ran are not "passing")
+ *       freshness      = 1.0 when ageSeconds < FRESH_THRESHOLD, decaying linearly to
+ *                       MIN_FRESHNESS over STALE_THRESHOLD. Beyond STALE_THRESHOLD the
+ *                       applicability is coerced to `unknown` (matches §2.6 rule 3 of the spec).
+ *   - A build failure OR 0 tests passing marks evidence ['critical'] and forces a
+ *     blocking recommendation (the aggregator uses recommendations for narrative).
+ *   - Multi-tenant: tenantId flows through unchanged (caller sets it on the EvidenceItem
+ *     via the `collector.tool` string; the full tenant stamp is the subject, not the item).
+ */
+// Freshness constants (seconds). Configurable at call-site via CiRunInput.
+const DEFAULT_FRESH_THRESHOLD_S = 60 * 60 * 4; // 4 h
+const DEFAULT_STALE_THRESHOLD_S = 60 * 60 * 24; // 24 h
+const MIN_FRESHNESS = 0.5; // floor before we coerce to unknown
+const CI_WEIGHT = 0.10; // matches DEFAULT_WEIGHTS['ci-results'] in confidence.ts
+/**
+ * Produce a `ci-results` EvidenceItem from a raw CI run summary.
+ *
+ * Deterministic and pure. Returns `not_applicable` when the run is absent, `unknown`
+ * when stale or incomplete, and `applicable` with a real score otherwise.
+ */
+export function ciResultsToEvidence(run, collectedAt) {
+    const now = collectedAt ?? new Date().toISOString();
+    const source = 'ci-results';
+    const weight = CI_WEIGHT;
+    // Freshness computation.
+    const ageMs = Date.parse(now) - Date.parse(run.completedAt);
+    const ageS = Math.max(0, ageMs / 1000);
+    const staleThreshold = run.staleAfterSeconds ?? DEFAULT_STALE_THRESHOLD_S;
+    if (ageS > staleThreshold) {
+        return {
+            source,
+            score: 0,
+            weight,
+            applicability: 'unknown',
+            blocking: false,
+            evidence: [
+                `CI run completed at ${run.completedAt} — stale (${Math.round(ageS / 3600)}h > ${staleThreshold / 3600}h threshold).`,
+            ],
+            recommendations: ['Re-run CI against the current commit before shipping.'],
+            reason: `CI run is stale (${Math.round(ageS / 3600)}h old, threshold ${staleThreshold / 3600}h).`,
+            collectedAt: now,
+            collector: { tool: 'qulib.ci-results-adapter' },
+        };
+    }
+    const total = run.testsPassed + run.testsFailed + run.testsErrored;
+    // Build failure: tests may not even have run — score 0, blocking recommendation.
+    if (!run.buildPassed) {
+        const evidence = [`Build FAILED (${run.workflowName ?? 'CI workflow'}).`];
+        if (total > 0)
+            evidence.push(`${run.testsPassed}/${total} tests passed before build failure.`);
+        if (run.runUrl)
+            evidence.push(`Run: ${run.runUrl}`);
+        return {
+            source,
+            score: 0,
+            weight,
+            applicability: 'applicable',
+            blocking: false, // the aggregator decides blocking; we report honestly
+            evidence,
+            recommendations: ['Fix the build failure before shipping.'],
+            collectedAt: now,
+            collector: { tool: 'qulib.ci-results-adapter', inputRef: run.runUrl },
+        };
+    }
+    // No tests ran at all — cannot score honestly.
+    if (total === 0) {
+        return {
+            source,
+            score: 0,
+            weight,
+            applicability: 'unknown',
+            blocking: false,
+            evidence: [
+                `Build passed (${run.workflowName ?? 'CI workflow'}) but 0 tests executed.`,
+                ...(run.runUrl ? [`Run: ${run.runUrl}`] : []),
+            ],
+            recommendations: ['Add a test suite to CI for a meaningful confidence signal.'],
+            reason: 'Build passed but zero tests were executed — no test signal.',
+            collectedAt: now,
+            collector: { tool: 'qulib.ci-results-adapter', inputRef: run.runUrl },
+        };
+    }
+    // Normal case: compute pass-rate.
+    const passRate = run.testsPassed / total; // 0..1
+    const freshnessRatio = ageS <= DEFAULT_FRESH_THRESHOLD_S
+        ? 1.0
+        : MIN_FRESHNESS +
+            (1 - MIN_FRESHNESS) *
+                (1 - (ageS - DEFAULT_FRESH_THRESHOLD_S) / (staleThreshold - DEFAULT_FRESH_THRESHOLD_S));
+    const rawScore = passRate * freshnessRatio;
+    const score = Math.round(Math.max(0, Math.min(100, rawScore * 100)));
+    const evidence = [];
+    evidence.push(`${run.testsPassed}/${total} tests passed` +
+        (run.testsFailed > 0 ? ` (${run.testsFailed} failed)` : '') +
+        (run.testsErrored > 0 ? ` (${run.testsErrored} errored)` : '') +
+        ` — ${Math.round(passRate * 100)}% pass-rate.`);
+    if (run.workflowName)
+        evidence.push(`Workflow: ${run.workflowName}.`);
+    if (run.testsFlaky && run.testsFlaky > 0) {
+        evidence.push(`${run.testsFlaky} test(s) flaky (passed on retry).`);
+    }
+    if (run.runUrl)
+        evidence.push(`Run: ${run.runUrl}`);
+    if (freshnessRatio < 1.0) {
+        evidence.push(`Freshness factor ${freshnessRatio.toFixed(2)} applied (run age ${Math.round(ageS / 3600)}h).`);
+    }
+    const recommendations = [];
+    if (run.testsFailed > 0)
+        recommendations.push(`Fix ${run.testsFailed} failing test(s) before shipping.`);
+    if (run.testsErrored > 0)
+        recommendations.push(`Investigate ${run.testsErrored} errored test(s) (infra/setup).`);
+    if (run.testsFlaky && run.testsFlaky > 0) {
+        recommendations.push(`Stabilize ${run.testsFlaky} flaky test(s) to improve signal quality.`);
+    }
+    return {
+        source,
+        score,
+        weight,
+        applicability: 'applicable',
+        blocking: false,
+        evidence,
+        recommendations,
+        collectedAt: now,
+        collector: { tool: 'qulib.ci-results-adapter', inputRef: run.runUrl },
+    };
+}

package/dist/adapters/cypress-e2e-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cypress-e2e-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/cypress-e2e-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAY,MAAM,mCAAmC,CAAC;AA2ClG,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,WAAW,iBAAiB;IAErC,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IA4BhD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE;CAGzD"}
+{"version":3,"file":"cypress-e2e-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/cypress-e2e-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAY,MAAM,mCAAmC,CAAC;AA+DlG,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,WAAW,iBAAiB;IAErC,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IAiChD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE;CAGzD"}