@qulib/core 0.8.2 → 0.9.0

package/dist/cli/scaffold-run.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `qulib scaffold` — Q2 (scaffold-cli subtask).
+ *
+ * Wraps `scaffoldTests(url, options)` from ../scaffold-tests.js as a first-class
+ * CLI surface (scaffold was previously only reachable programmatically / via MCP).
+ *
+ * This file owns the `scaffold` subcommand end-to-end and is registered from
+ * cli/index.ts via `registerScaffoldCommand(program)` so this build agent never
+ * edits index.ts itself (avoids collision with score-automation). It mirrors the
+ * dynamic-import command style used by `cost` and the output-mode conventions of
+ * `analyze` (write-to-disk by default, `--json` for a stdout-only run).
+ *
+ * Output modes (one stdout shape, mutually exclusive with disk writes):
+ *   default            → write projectConfig + generated specs under --out (./qulib-scaffold)
+ *   --json             → no disk writes; print the full ScaffoldResult-shaped JSON on stdout
+ *
+ * Honesty rules (root design principle: never emit false confidence):
+ *   - If analyze produced ZERO scenarios, we do NOT write an empty-but-confident
+ *     scaffold. Write mode exits non-zero with a clear message; --json emits an
+ *     explicit `{ empty: true, ... }` payload so a caller/agent can branch on it.
+ *   - `--framework playwright` currently maps to a not-implemented adapter
+ *     (PlaywrightAdapter.renderAll throws). Rather than surfacing a raw stack, we
+ *     translate it into an actionable error pointing at the supported framework.
+ */
+import type { Command } from 'commander';
+import { type ScaffoldResult } from '../scaffold-tests.js';
+import type { SpecValidationReport } from '../adapters/validate-specs.js';
+import { type RecipeId } from '../schemas/recipe.schema.js';
+/** Frameworks `scaffoldTests` accepts. Mirrors its `ScaffoldOptions['framework']`. */
+declare const FRAMEWORKS: readonly ["cypress-e2e", "playwright"];
+type ScaffoldFramework = (typeof FRAMEWORKS)[number];
+/** A single file the scaffold wants on disk, with its repo-relative path. */
+interface ScaffoldFile {
+    /** Path relative to the --out root. */
+    relativePath: string;
+    contents: string;
+}
+interface ScaffoldRunOptions {
+    url: string;
+    framework: ScaffoldFramework;
+    maxPages?: number;
+    out: string;
+    json: boolean;
+    recipes?: RecipeId[];
+    /**
+     * When true, fail the command (non-zero exit) if any generated spec does not
+     * parse/compile. The dry-run validation always runs; this flag controls
+     * whether a validation failure is fatal vs merely reported.
+     */
+    validateSpecs?: boolean;
+}
+/**
+ * Raised when `--validate-specs` is set and at least one generated spec fails
+ * the dry-run. Carries a non-zero `exitCode` so the CLI surfaces a hard failure
+ * instead of writing a known-broken scaffold and exiting green.
+ */
+export declare class SpecValidationError extends Error {
+    readonly exitCode = 1;
+    constructor(message: string);
+}
+/**
+ * Flatten a ScaffoldResult into the concrete files a scaffold project needs:
+ * the framework config file, any support files, and one spec per generated test
+ * (each at its own `outputPath`, which the adapter already namespaces e.g.
+ * `cypress/e2e/<slug>.cy.ts`). Pure + side-effect-free so tests can assert on it.
+ */
+export declare function collectScaffoldFiles(result: ScaffoldResult): ScaffoldFile[];
+/**
+ * Apply the dry-run validation gate.
+ *
+ * Pure + side-effect-free (returns the warning text instead of logging) so it
+ * is unit-testable in isolation: feed it an `ok: false` report and assert it
+ * throws; feed it an `ok: true` report and assert it returns null. This is the
+ * discrimination witness for the fatal path — `runScaffold` cannot produce a
+ * broken spec on demand (the adapters always render valid code), so the gate's
+ * reject-vs-pass behavior is proven here directly against a report.
+ *
+ * @returns a non-null warning string when validation failed but `validateSpecs`
+ *   was not set (caller should log it); null when all specs parsed.
+ * @throws SpecValidationError when validation failed AND `validateSpecs` is set.
+ */
+export declare function enforceSpecValidation(validation: SpecValidationReport, validateSpecs: boolean): string | null;
+export declare function runScaffold(options: ScaffoldRunOptions): Promise<void>;
+export declare function registerScaffoldCommand(program: Command): void;
+export {};
+//# sourceMappingURL=scaffold-run.d.ts.map

package/dist/cli/scaffold-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-run.d.ts","sourceRoot":"","sources":["../../src/cli/scaffold-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAI5E,sFAAsF;AACtF,QAAA,MAAM,UAAU,wCAAyC,CAAC;AAC1D,KAAK,iBAAiB,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAKrD,6EAA6E;AAC7E,UAAU,YAAY;IACpB,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,kBAAkB;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,iBAAiB,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,KAAK;gBACV,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,EAAE,CAgC3E;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,oBAAoB,EAChC,aAAa,EAAE,OAAO,GACrB,MAAM,GAAG,IAAI,CAef;AA+BD,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiG5E;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkE9D"}

package/dist/cli/scaffold-run.js

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+import { scaffoldTests } from '../scaffold-tests.js';
+import { RecipeIdSchema } from '../schemas/recipe.schema.js';
+const ScaffoldUrlSchema = z.string().url();
+/** Frameworks `scaffoldTests` accepts. Mirrors its `ScaffoldOptions['framework']`. */
+const FRAMEWORKS = ['cypress-e2e', 'playwright'];
+const FrameworkSchema = z.enum(FRAMEWORKS);
+const DEFAULT_OUT_DIR = 'qulib-scaffold';
+/**
+ * Raised when `--validate-specs` is set and at least one generated spec fails
+ * the dry-run. Carries a non-zero `exitCode` so the CLI surfaces a hard failure
+ * instead of writing a known-broken scaffold and exiting green.
+ */
+export class SpecValidationError extends Error {
+    exitCode = 1;
+    constructor(message) {
+        super(message);
+        this.name = 'SpecValidationError';
+    }
+}
+/**
+ * Flatten a ScaffoldResult into the concrete files a scaffold project needs:
+ * the framework config file, any support files, and one spec per generated test
+ * (each at its own `outputPath`, which the adapter already namespaces e.g.
+ * `cypress/e2e/<slug>.cy.ts`). Pure + side-effect-free so tests can assert on it.
+ */
+export function collectScaffoldFiles(result) {
+    const files = [];
+    const { projectConfig, generatedTests } = result;
+    files.push({
+        relativePath: projectConfig.configFile.filename,
+        contents: projectConfig.configFile.code,
+    });
+    for (const support of projectConfig.supportFiles) {
+        files.push({ relativePath: support.filename, contents: support.code });
+    }
+    for (const spec of generatedTests) {
+        files.push({ relativePath: spec.outputPath, contents: spec.code });
+    }
+    // A package.json fragment is informational (devDeps + scripts) — surface it as
+    // a file so the scaffold is runnable without the caller re-deriving it.
+    files.push({
+        relativePath: 'package.json',
+        contents: JSON.stringify({
+            name: 'qulib-scaffolded-suite',
+            private: true,
+            scripts: projectConfig.packageJson.scripts,
+            devDependencies: projectConfig.packageJson.devDependencies,
+        }, null, 2) + '\n',
+    });
+    return files;
+}
+/** True when scaffold produced nothing actionable (no scenarios → no specs). */
+function isEmptyScaffold(result) {
+    return result.scenarios.length === 0 || result.generatedTests.length === 0;
+}
+/**
+ * Apply the dry-run validation gate.
+ *
+ * Pure + side-effect-free (returns the warning text instead of logging) so it
+ * is unit-testable in isolation: feed it an `ok: false` report and assert it
+ * throws; feed it an `ok: true` report and assert it returns null. This is the
+ * discrimination witness for the fatal path — `runScaffold` cannot produce a
+ * broken spec on demand (the adapters always render valid code), so the gate's
+ * reject-vs-pass behavior is proven here directly against a report.
+ *
+ * @returns a non-null warning string when validation failed but `validateSpecs`
+ *   was not set (caller should log it); null when all specs parsed.
+ * @throws SpecValidationError when validation failed AND `validateSpecs` is set.
+ */
+export function enforceSpecValidation(validation, validateSpecs) {
+    if (validation.ok)
+        return null;
+    const failed = validation.results.filter((r) => !r.valid);
+    const detail = failed
+        .map((r) => `  ✗ ${r.outputPath}\n      ${r.errors.join('\n      ')}`)
+        .join('\n');
+    const summary = `${validation.invalidCount} of ${validation.total} generated spec(s) failed dry-run validation ` +
+        `(they do not parse/compile):\n${detail}`;
+    if (validateSpecs) {
+        throw new SpecValidationError(summary);
+    }
+    return summary;
+}
+/**
+ * Translate the known not-implemented-adapter failure into an actionable message.
+ * Re-throws anything else unchanged so real failures stay loud.
+ */
+function rethrowScaffoldError(error, framework) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/not implemented/i.test(message)) {
+        throw new Error(`The "${framework}" test adapter is not implemented yet, so qulib cannot render specs for it. ` +
+            `Re-run with --framework cypress-e2e (the supported scaffolder) until the ${framework} adapter ships.`);
+    }
+    throw error instanceof Error ? error : new Error(message);
+}
+async function writeScaffoldToDisk(files, outDir) {
+    const fs = await import('node:fs/promises');
+    const path = await import('node:path');
+    const outRoot = path.resolve(process.cwd(), outDir);
+    const written = [];
+    for (const file of files) {
+        const dest = path.join(outRoot, file.relativePath);
+        await fs.mkdir(path.dirname(dest), { recursive: true });
+        await fs.writeFile(dest, file.contents, 'utf8');
+        written.push(dest);
+    }
+    return written;
+}
+export async function runScaffold(options) {
+    const url = ScaffoldUrlSchema.parse(options.url);
+    const framework = FrameworkSchema.parse(options.framework);
+    if (options.json) {
+        console.error('[qulib] Scaffold JSON mode: no disk writes; full result JSON on stdout');
+    }
+    else {
+        console.error(`[qulib] Scaffolding ${framework} tests for ${url}`);
+        console.error('[qulib] Analyzing the deployed surface to derive scenarios — this may take a moment...');
+    }
+    let result;
+    try {
+        result = await scaffoldTests(url, {
+            framework,
+            ...(options.maxPages !== undefined && { maxPagesToScan: options.maxPages }),
+            ...(options.recipes && options.recipes.length > 0 && { recipes: options.recipes }),
+        });
+    }
+    catch (error) {
+        rethrowScaffoldError(error, framework);
+    }
+    // Honest empty handling — no false-confidence scaffolds.
+    if (isEmptyScaffold(result)) {
+        if (options.json) {
+            console.log(JSON.stringify({
+                url: result.url,
+                framework: result.framework,
+                empty: true,
+                scenarioCount: 0,
+                generatedTestCount: 0,
+                note: 'Analysis surfaced no scenarios for this URL, so no tests were generated. ' +
+                    'This is honest output, not a failure: there was nothing concrete to scaffold. ' +
+                    'Try a different URL, raise --max-pages, or provide authenticated access if the app is behind a login.',
+            }, null, 2));
+            return;
+        }
+        throw new Error('No scenarios were derived for this URL, so qulib generated no tests. ' +
+            'Refusing to write an empty scaffold (no false confidence). ' +
+            'Try a different URL, raise --max-pages, or supply auth if the app is behind a login.');
+    }
+    // Dry-run gate: the scaffold already validated every generated spec through
+    // the TS compiler. Surface a failure here so a broken generator output never
+    // silently lands on disk. With --validate-specs this is fatal (non-zero exit
+    // via SpecValidationError); without it we still warn so the signal is never
+    // hidden. The gate logic lives in enforceSpecValidation (unit-tested).
+    const validation = result.specValidation;
+    const warning = enforceSpecValidation(validation, Boolean(options.validateSpecs));
+    if (warning) {
+        console.error(`[qulib] WARNING — ${warning}`);
+        console.error('[qulib] Re-run with --validate-specs to make this a hard (non-zero) failure.');
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            url: result.url,
+            framework: result.framework,
+            empty: false,
+            scenarioCount: result.scenarios.length,
+            generatedTestCount: result.generatedTests.length,
+            scenarios: result.scenarios,
+            generatedTests: result.generatedTests,
+            projectConfig: result.projectConfig,
+            specValidation: result.specValidation,
+        }, null, 2));
+        return;
+    }
+    const files = collectScaffoldFiles(result);
+    const written = await writeScaffoldToDisk(files, options.out);
+    const path = await import('node:path');
+    const outRoot = path.resolve(process.cwd(), options.out);
+    console.error(`\n[qulib] Scaffold complete — ${framework}`);
+    console.error(`  Scenarios derived:   ${result.scenarios.length}`);
+    console.error(`  Specs generated:     ${result.generatedTests.length}`);
+    console.error(`  Specs validated:     ${validation.total - validation.invalidCount}/${validation.total} parse cleanly`);
+    console.error(`  Files written:       ${written.length}`);
+    console.error(`  Output directory:    ${outRoot}`);
+    console.error(`  Config:              ${result.projectConfig.configFile.filename}`);
+    console.error('\n[qulib] Next: cd into the output dir, `npm install`, then run the test script.');
+}
+export function registerScaffoldCommand(program) {
+    program
+        .command('scaffold')
+        .description('Generate a runnable test suite (config + specs) for a deployed app by analyzing its surface')
+        .requiredOption('--url <url>', 'Base URL of the app to scaffold tests for')
+        .option('--framework <framework>', `Test framework: ${FRAMEWORKS.join(' | ')}`, 'cypress-e2e')
+        .option('--max-pages <n>', 'Maximum number of pages to scan while deriving scenarios')
+        .option('--out <dir>', 'Directory to write the scaffolded project into', DEFAULT_OUT_DIR)
+        .option('--json', 'Do not write to disk — print the full scaffold result as JSON on stdout (use for MCP/CI)', false)
+        .option('--recipes <ids>', 'Comma-separated recipe ids to append proven test patterns: auth,a11y,nav,seed (e.g. --recipes auth,a11y)')
+        .option('--validate-specs', 'Fail (non-zero exit) if any generated spec does not parse/compile. Validation always runs; this makes a failure fatal.', false)
+        .action(async (options) => {
+        const parsedFramework = FrameworkSchema.safeParse(options.framework);
+        if (!parsedFramework.success) {
+            throw new Error(`Invalid --framework "${options.framework}". Supported: ${FRAMEWORKS.join(', ')}.`);
+        }
+        let maxPages;
+        if (options.maxPages !== undefined) {
+            const n = Number(options.maxPages);
+            if (!Number.isInteger(n) || n <= 0) {
+                throw new Error(`--max-pages must be a positive integer, got "${options.maxPages}".`);
+            }
+            maxPages = n;
+        }
+        let recipes;
+        if (options.recipes) {
+            const ids = options.recipes.split(',').map((s) => s.trim()).filter(Boolean);
+            const parsed = ids.map((id) => RecipeIdSchema.safeParse(id));
+            const invalid = parsed.map((p, i) => (!p.success ? ids[i] : null)).filter(Boolean);
+            if (invalid.length > 0) {
+                throw new Error(`Invalid --recipes value(s): ${invalid.join(', ')}. Supported: auth, a11y, nav, seed.`);
+            }
+            recipes = parsed.map((p) => (p.success ? p.data : null)).filter(Boolean);
+        }
+        await runScaffold({
+            url: options.url,
+            framework: parsedFramework.data,
+            maxPages,
+            out: options.out,
+            json: Boolean(options.json),
+            recipes,
+            validateSpecs: Boolean(options.validateSpecs),
+        });
+    });
+}

package/dist/cli/score-automation-run.d.ts

@@ -0,0 +1,25 @@
+import type { Command } from 'commander';
+import type { AutomationMaturity } from '../schemas/automation-maturity.schema.js';
+export interface ScoreAutomationOptions {
+    /** Path to the local repo to score (required). */
+    repo: string;
+    /** Emit the full AutomationMaturity object as JSON to stdout instead of the human report. */
+    json?: boolean;
+}
+/**
+ * Resolve `--repo` to an absolute path and assert it is an existing directory.
+ * Fails fast with a clear, actionable message rather than letting glob silently
+ * scan nothing and report a falsely-confident "everything is uncovered" score.
+ */
+export declare function resolveRepoPath(repoOption: string | undefined, cwd?: string): string;
+/** Build the human-readable report as a single string (kept pure so tests can assert on it). */
+export declare function formatHumanReport(maturity: AutomationMaturity): string;
+/**
+ * Core of the command, factored out of the action handler so node:test can drive it
+ * directly against a fixture repo without spawning a process.
+ *
+ * Reuses scanRepo (static repo intelligence) then computes maturity explicitly.
+ */
+export declare function runScoreAutomation(options: ScoreAutomationOptions, out?: (line: string) => void): Promise<AutomationMaturity>;
+export declare function registerScoreAutomationCommand(program: Command): void;
+//# sourceMappingURL=score-automation-run.d.ts.map

package/dist/cli/score-automation-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-automation-run.d.ts","sourceRoot":"","sources":["../../src/cli/score-automation-run.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EACV,kBAAkB,EAEnB,MAAM,0CAA0C,CAAC;AAIlD,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAYnG;AA+BD,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAiBtE;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,sBAAsB,EAC/B,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkC,GACxD,OAAO,CAAC,kBAAkB,CAAC,CAW7B;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAWrE"}

package/dist/cli/score-automation-run.js

@@ -0,0 +1,123 @@
+/**
+ * `qulib score-automation` — score a local repo's test-automation maturity.
+ *
+ * Wraps `computeAutomationMaturity(repo)` (../tools/scoring/automation-maturity.js)
+ * as a first-class CLI surface. Until now the maturity score was only produced as a
+ * side-effect of `analyze --repo`; this exposes it standalone so an agent or CI can
+ * score a repo's automation directly, without a deployed URL to crawl.
+ *
+ * How a RepoAnalysis is obtained (smallest honest path, no duplicated logic):
+ *   `scanRepo(repoPath)` (../tools/repo/scan.js) is a pure static scan — it infers
+ *   routes, test files, test-id hygiene, CI presence and Cypress structure straight
+ *   from the repo layout, with no browser/URL dependency. We reuse it (root CLAUDE.md:
+ *   shared logic lives in core, never duplicate) and then call computeAutomationMaturity
+ *   on its result so the printed report reflects a freshly-computed maturity object.
+ *
+ * Output honesty (root design principle — no false confidence):
+ *   Per-dimension applicability (`applicable | not_applicable | unknown`) is surfaced
+ *   verbatim. A `not_applicable` or `unknown` dimension reads as honest uncertainty
+ *   with its reason/guidance — it is NEVER rendered as a "0/100" that looks like a
+ *   real failing score. The overall score is normalized over applicable dimensions
+ *   only (see computeAutomationMaturity), so absent capabilities don't drag it down.
+ *
+ * This file owns the `score-automation` subcommand end-to-end and is registered from
+ * cli/index.ts via `registerScoreAutomationCommand(program)`, so this command's build
+ * never edits index.ts (avoids collision with the parallel scaffold command).
+ */
+import { resolve } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import { scanRepo } from '../tools/repo/scan.js';
+import { computeAutomationMaturity } from '../tools/scoring/automation-maturity.js';
+/**
+ * Resolve `--repo` to an absolute path and assert it is an existing directory.
+ * Fails fast with a clear, actionable message rather than letting glob silently
+ * scan nothing and report a falsely-confident "everything is uncovered" score.
+ */
+export function resolveRepoPath(repoOption, cwd = process.cwd()) {
+    if (!repoOption || !repoOption.trim()) {
+        throw new Error('score-automation requires --repo <path> pointing at a local repository to score.');
+    }
+    const abs = resolve(cwd, repoOption.trim());
+    if (!existsSync(abs)) {
+        throw new Error(`--repo path does not exist: ${abs}`);
+    }
+    if (!statSync(abs).isDirectory()) {
+        throw new Error(`--repo path is not a directory: ${abs}`);
+    }
+    return abs;
+}
+/** Single-letter glyph + word for a dimension's applicability, for the human report. */
+function applicabilityTag(dim) {
+    const applicability = dim.applicability ?? 'applicable';
+    switch (applicability) {
+        case 'not_applicable':
+            return 'n/a';
+        case 'unknown':
+            return 'unknown';
+        default:
+            return 'applicable';
+    }
+}
+/**
+ * Render one dimension line. For applicable dimensions we show the score; for
+ * not_applicable / unknown we show the word and the reason — NOT a misleading "0".
+ */
+function formatDimensionLine(dim) {
+    const applicability = dim.applicability ?? 'applicable';
+    const weightPct = `${Math.round(dim.weight * 100)}%`;
+    const head = `  - ${dim.dimension} [w=${weightPct}]`;
+    if (applicability === 'applicable') {
+        return `${head}: ${dim.score}/100`;
+    }
+    // Honest-uncertainty rendering: surface the label + reason, never a bare 0.
+    const reason = dim.reason ? ` — ${dim.reason}` : '';
+    return `${head}: ${applicabilityTag(dim)} (excluded from overall)${reason}`;
+}
+/** Build the human-readable report as a single string (kept pure so tests can assert on it). */
+export function formatHumanReport(maturity) {
+    const lines = [];
+    lines.push(`[qulib] Automation maturity for ${maturity.repoPath}`);
+    lines.push(`  overall: ${maturity.overallScore}/100  —  ${maturity.label} (level ${maturity.level})`);
+    lines.push('  dimensions:');
+    for (const dim of maturity.dimensions) {
+        lines.push(formatDimensionLine(dim));
+    }
+    if (maturity.topRecommendations.length > 0) {
+        lines.push('  top recommendations:');
+        for (const rec of maturity.topRecommendations) {
+            lines.push(`    • ${rec}`);
+        }
+    }
+    else {
+        lines.push('  top recommendations: none — applicable dimensions are at/above target.');
+    }
+    return lines.join('\n');
+}
+/**
+ * Core of the command, factored out of the action handler so node:test can drive it
+ * directly against a fixture repo without spawning a process.
+ *
+ * Reuses scanRepo (static repo intelligence) then computes maturity explicitly.
+ */
+export async function runScoreAutomation(options, out = (line) => console.log(line)) {
+    const repoPath = resolveRepoPath(options.repo);
+    const repo = await scanRepo(repoPath);
+    const maturity = computeAutomationMaturity(repo);
+    if (options.json) {
+        out(JSON.stringify(maturity, null, 2));
+    }
+    else {
+        out(formatHumanReport(maturity));
+    }
+    return maturity;
+}
+export function registerScoreAutomationCommand(program) {
+    program
+        .command('score-automation')
+        .description("Score a local repo's test-automation maturity (overall + per-dimension, with honest applicability)")
+        .requiredOption('--repo <path>', 'Path to the local repository to score')
+        .option('--json', 'Emit the full AutomationMaturity object as JSON to stdout', false)
+        .action(async (options) => {
+        await runScoreAutomation({ repo: options.repo, json: Boolean(options.json) });
+    });
+}

package/dist/examples/notquality-dogfood/fixture.d.ts

@@ -0,0 +1,166 @@
+/**
+ * notquality DOGFOOD — real delivery signals fixture.
+ *
+ * P5 — qulib ingests notquality's own delivery signals → Release Confidence.
+ *
+ * PROVENANCE (all signals gathered 2026-06-04 via `gh` CLI against TapeshN/notquality):
+ *
+ *   E2E run:  gh run view 26931370208 -R TapeshN/notquality
+ *             branch: notquality-app/prod-migrate
+ *             sha:    5732ed5a37ba46c503d1319da83c5c6f4c8e5cb6
+ *             workflow: E2E (playwright job, job ID 79451559555)
+ *             completed: 2026-06-04T04:46:20Z  (duration: ~6m4s)
+ *             conclusion: success
+ *             test files: 29 spec files on origin/main (git ls-tree -r origin/main)
+ *             test cases: 194 total test() calls across 29 spec files
+ *             fixme/skip: 26 test.fixme / test.skip markers
+ *             active (non-fixme): 194 - 26 = 168 runnable tests
+ *             all passed (CI conclusion: success)
+ *
+ *   CI run:   gh run view 26931370215 -R TapeshN/notquality
+ *             branch: notquality-app/prod-migrate
+ *             sha:    5732ed5a37ba46c503d1319da83c5c6f4c8e5cb6
+ *             workflow: CI (validate job, job ID 79451559554)
+ *             completed: 2026-06-04T04:46:20Z  (duration: ~1m13s)
+ *             conclusion: success
+ *             steps: typecheck, lint, validate:bugs, prisma generate, build — all green
+ *
+ *   PR:       gh pr view 52 -R TapeshN/notquality --json number,url,reviewDecision,mergeable,statusCheckRollup
+ *             title: "Run prisma migrate deploy before build on Vercel"
+ *             branch: notquality-app/prod-migrate
+ *             number: 52
+ *             url: https://github.com/TapeshN/notquality/pull/52
+ *             reviewDecision: "" (no review assigned — open PR, no blocking change requests)
+ *             mergeable: MERGEABLE
+ *             status checks: CI validate → SUCCESS, E2E playwright → SUCCESS, Vercel → SUCCESS
+ *
+ *   Repo inventory (gh ls-tree -r origin/main, 2026-06-04):
+ *             29 spec files, 77 source .ts/.tsx files (excl. e2e), 19 route pages
+ *             playwright.config.ts present (.github/workflows/e2e.yml present)
+ *             CI: .github/workflows/ci.yml present (typecheck + lint + validate:bugs + build)
+ *             auth: dual auth (iron-session playground + NextAuth platform)
+ *             test-id hygiene: data-testid used in app/ + e2e/ (29 spec files use getByTestId)
+ *             challenges: 1 seeded (legacy-bug-hunt-1); 16-card static list page (P5 truth-fix target)
+ *
+ * COLLECTION TIMESTAMP: 2026-06-04T09:00:00.000Z
+ *
+ * This fixture is intentionally FROZEN at this point in time. When real delivery
+ * signals are updated, create a NEW fixture version (fixture-v2.ts, etc.) and
+ * update the integration tests to use the latest. Never silently mutate this file —
+ * the provenance citation is load-bearing for the eval/audit trail.
+ */
+export declare const FIXTURE_COLLECTION_TS = "2026-06-04T09:00:00.000Z";
+/**
+ * Real CI run data from notquality E2E workflow (run #26931370208).
+ * Source: gh run view 26931370208 -R TapeshN/notquality
+ */
+export declare const NOTQUALITY_E2E_RUN: {
+    /** ISO-8601 timestamp of run completion. */
+    readonly completedAt: "2026-06-04T04:46:20.000Z";
+    /** CI build step succeeded (typecheck, lint, validate:bugs, prisma generate, build). */
+    readonly buildPassed: true;
+    /**
+     * 168 runnable tests (194 total test() calls − 26 test.fixme/test.skip markers).
+     * All 168 passed in this run. Source: spec-file grep + run conclusion=success.
+     */
+    readonly testsPassed: 168;
+    readonly testsFailed: 0;
+    readonly testsErrored: 0;
+    /**
+     * 26 tests marked test.fixme or test.skip across 16 spec files.
+     * These are known quarantined defects (color-contrast a11y, label regression,
+     * EVT-001, duplicate challenge-title) — intentional, not infra failures.
+     */
+    readonly testsFlaky: 0;
+    readonly runUrl: "https://github.com/TapeshN/notquality/actions/runs/26931370208";
+    readonly workflowName: "E2E (playwright)";
+};
+/**
+ * Real CI validate-job data from notquality CI workflow (run #26931370215).
+ * Source: gh run view 26931370215 -R TapeshN/notquality
+ */
+export declare const NOTQUALITY_CI_RUN: {
+    readonly completedAt: "2026-06-04T04:46:20.000Z";
+    readonly buildPassed: true;
+    readonly testsPassed: 0;
+    readonly testsFailed: 0;
+    readonly testsErrored: 0;
+    readonly runUrl: "https://github.com/TapeshN/notquality/actions/runs/26931370215";
+    readonly workflowName: "CI (validate)";
+};
+/**
+ * Real PR #52 metadata from notquality.
+ * Source: gh pr view 52 -R TapeshN/notquality --json number,url,reviewDecision,mergeable,statusCheckRollup
+ */
+export declare const NOTQUALITY_PR_52: {
+    readonly number: 52;
+    readonly url: "https://github.com/TapeshN/notquality/pull/52";
+    readonly reviewDecision: null;
+    readonly mergeable: "MERGEABLE";
+    readonly statusCheckRollup: readonly [{
+        readonly state: "SUCCESS";
+        readonly name: "validate";
+        readonly targetUrl: "https://github.com/TapeshN/notquality/actions/runs/26931370215/job/79451559554";
+    }, {
+        readonly state: "SUCCESS";
+        readonly name: "playwright";
+        readonly targetUrl: "https://github.com/TapeshN/notquality/actions/runs/26931370208/job/79451559555";
+    }, {
+        readonly state: "SUCCESS";
+        readonly name: "Vercel";
+        readonly targetUrl: "https://vercel.com/tapeshnagarwal-7364s-projects/notquality-app/5mSLRhKKEdwvnqMoTY4XWxSePFYB";
+    }, {
+        readonly state: "SUCCESS";
+        readonly name: "Vercel Preview Comments";
+        readonly targetUrl: "https://vercel.com/github";
+    }];
+    readonly noPr: false;
+};
+/**
+ * Repo-level automation maturity facts (from static scan of origin/main, 2026-06-04).
+ * These facts drive the test-automation EvidenceItem used when qulib_score_automation
+ * is held (no live local scan in this fixture — see HELD note below).
+ *
+ * HELD: The live qulib_score_automation(repoPath) call requires the notquality
+ * repo to be available at an absolute path on the build machine and needs the full
+ * qulib CLI. The integration test uses these pre-scored facts instead of a live scan.
+ * The live scan is operator-gated (run `qulib score-automation <path>` locally).
+ */
+export declare const NOTQUALITY_AUTOMATION_MATURITY: {
+    /**
+     * Estimated overall automation maturity score (0–100).
+     * Basis: Playwright present (framework-adoption ✓), 29 spec files covering 19 routes
+     * (test-coverage-breadth ~72%), e2e.yml + ci.yml present (ci-integration ✓),
+     * auth-test-coverage present (iron-session + NextAuth both tested ✓),
+     * data-testid used in spec files (test-id-hygiene present but not perfect — duplicate
+     * challenge-title test-id is a known defect, P5 truth-fix target), no component/unit
+     * tests yet (component-test-ratio = 0). Estimated L3 (60–79 range).
+     * Conservative estimate: 65/100.
+     */
+    readonly overallScore: 65;
+    readonly level: 3;
+    readonly label: "L3 — building maturity";
+    /**
+     * Key facts cited (no live scan was run; these are statically-derived):
+     * - framework: Playwright (playwright.config.ts present on origin/main)
+     * - specFiles: 29 (git ls-tree origin/main | grep "e2e/" | grep "spec.ts")
+     * - routePages: 19 (git ls-tree origin/main | grep "app/" | grep "page.tsx")
+     * - ciWorkflows: 2 (.github/workflows/ci.yml + e2e.yml)
+     * - authTests: yes (e2e/specs/auth/ — 3 spec files, 18 test() calls)
+     * - testIdHygiene: partial (data-testid used; duplicate challenge-title known defect)
+     * - componentTests: 0 (no vitest/jest unit tests in repo)
+     */
+    readonly topRecommendations: readonly ["Add vitest/jest unit tests for lib/ (scoring, API helpers) to raise component-test-ratio.", "Fix duplicate data-testid=\"challenge-title\" (breadcrumb vs h1) for unambiguous E2E selectors.", "Add dedicated challenges list + attempt E2E specs once fake list page is replaced with DB truth."];
+    readonly computedAt: "2026-06-04T09:00:00.000Z";
+    readonly repoPath: "TapeshN/notquality@5732ed5a (origin/main, 2026-06-04)";
+};
+/**
+ * Repository context for the ConfidenceSubject.
+ * ref: the commit SHA + branch context; tenantId: 'notquality' (multi-tenant from day one).
+ */
+export declare const NOTQUALITY_SUBJECT: {
+    readonly kind: "release";
+    readonly ref: "TapeshN/notquality@5732ed5a (notquality-app/prod-migrate)";
+    readonly tenantId: "notquality";
+};
+//# sourceMappingURL=fixture.d.ts.map

package/dist/examples/notquality-dogfood/fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture.d.ts","sourceRoot":"","sources":["../../../src/examples/notquality-dogfood/fixture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,eAAO,MAAM,qBAAqB,6BAA6B,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,kBAAkB;IAC7B,4CAA4C;;IAE5C,wFAAwF;;IAExF;;;OAGG;;;;IAIH;;;;OAIG;;;;CAIK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;CAQpB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;6BAGH,IAAI;;;;;;;;;;;;;;;;;;;;CAyBpB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B;IACzC;;;;;;;;;OASG;;;;IAIH;;;;;;;;;OASG;;;;CAQK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;CAIrB,CAAC"}