@qulib/core 0.11.0 → 0.12.0

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

@@ -5,6 +5,24 @@ export interface ConfidenceOptions {
     repo?: string;
     json?: boolean;
 }
+export interface ConfidenceGateResult {
+    /** Whether any gate (--fail-on / --min-score) was requested. */
+    requested: boolean;
+    /** True when the release passes the requested gate (or none was requested). */
+    passed: boolean;
+    /** Human-readable explanation of the gate outcome. */
+    reason: string;
+}
+/**
+ * Evaluate a CI gate against a release-confidence result. Pure + side-effect-free
+ * so it is unit-testable; the CLI action turns a failed gate into a non-zero exit.
+ *
+ * - `failOn`: fail when the verdict is at or worse than this threshold
+ *   (e.g. `--fail-on hold` fails on `hold` or `block`).
+ * - `minScore`: fail when the confidence score is below this (a `null` score —
+ *   nothing evaluable — always fails a min-score gate).
+ */
+export declare function evaluateConfidenceGate(rc: ReleaseConfidence, failOn?: string, minScore?: number): ConfidenceGateResult;
 /** Render the human-friendly report for a ReleaseConfidence result. */
 export declare function formatConfidenceReport(rc: ReleaseConfidence, subjectRef: string): string;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"confidence-run.d.ts","sourceRoot":"","sources":["../../src/cli/confidence-run.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAGzE,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAiBD,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAuCxF;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,iBAAiB,EAC1B,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkC,GACxD,OAAO,CAAC,iBAAiB,CAAC,CAmE5B;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuBhE"}
+{"version":3,"file":"confidence-run.d.ts","sourceRoot":"","sources":["../../src/cli/confidence-run.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAGzE,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAKD,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,SAAS,EAAE,OAAO,CAAC;IACnB,+EAA+E;IAC/E,MAAM,EAAE,OAAO,CAAC;IAChB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,iBAAiB,EACrB,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,oBAAoB,CAuCtB;AAiBD,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAuCxF;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,iBAAiB,EAC1B,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkC,GACxD,OAAO,CAAC,iBAAiB,CAAC,CAmE5B;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2ChE"}

package/dist/cli/confidence-run.js

@@ -21,6 +21,50 @@ import { discoverApiSurfaceWithRepo } from '../tools/repo/api-surface.js';
 import { computeApiCoverage } from '../tools/scoring/api-coverage.js';
 import { buildConfidenceInputFromQulib } from '../tools/scoring/confidence-from-qulib.js';
 import { computeReleaseConfidence } from '../tools/scoring/confidence.js';
+/** Verdict severity, best (0) → worst (3). Used by the CI gate. */
+const VERDICT_RANK = { ship: 0, caution: 1, hold: 2, block: 3 };
+/**
+ * Evaluate a CI gate against a release-confidence result. Pure + side-effect-free
+ * so it is unit-testable; the CLI action turns a failed gate into a non-zero exit.
+ *
+ * - `failOn`: fail when the verdict is at or worse than this threshold
+ *   (e.g. `--fail-on hold` fails on `hold` or `block`).
+ * - `minScore`: fail when the confidence score is below this (a `null` score —
+ *   nothing evaluable — always fails a min-score gate).
+ */
+export function evaluateConfidenceGate(rc, failOn, minScore) {
+    const failOnNorm = failOn?.trim().toLowerCase();
+    const hasFailOn = Boolean(failOnNorm);
+    const hasMinScore = typeof minScore === 'number' && !Number.isNaN(minScore);
+    if (!hasFailOn && !hasMinScore) {
+        return { requested: false, passed: true, reason: 'no gate requested' };
+    }
+    const reasons = [];
+    let passed = true;
+    if (hasFailOn) {
+        if (!(failOnNorm in VERDICT_RANK)) {
+            throw new Error(`--fail-on must be one of: ship, caution, hold, block (got "${failOn}")`);
+        }
+        const verdictRank = VERDICT_RANK[rc.verdict] ?? 99;
+        if (verdictRank >= VERDICT_RANK[failOnNorm]) {
+            passed = false;
+            reasons.push(`verdict '${rc.verdict}' is at or worse than --fail-on '${failOnNorm}'`);
+        }
+    }
+    if (hasMinScore) {
+        const score = rc.confidenceScore;
+        if (score === null || score < minScore) {
+            passed = false;
+            reasons.push(`confidence score ${score === null ? 'null (nothing evaluable)' : score} is below --min-score ${minScore}`);
+        }
+    }
+    const scoreSuffix = rc.confidenceScore !== null ? `, score ${rc.confidenceScore}` : '';
+    return {
+        requested: true,
+        passed,
+        reason: passed ? `verdict '${rc.verdict}'${scoreSuffix} meets the gate` : reasons.join('; '),
+    };
+}
 /**
  * Resolve and validate an optional --repo path. Returns null if none was provided.
  */
@@ -152,11 +196,24 @@ export function registerConfidenceCommand(program) {
         .option('--url <url>', 'URL of the deployed app to analyze')
         .option('--repo <path>', 'Path to the local repository to score')
         .option('--json', 'Emit the full ReleaseConfidence object as JSON to stdout', false)
+        .option('--fail-on <verdict>', 'CI gate: exit non-zero when the verdict is at or worse than this (caution | hold | block)')
+        .option('--min-score <n>', 'CI gate: exit non-zero when the confidence score is below this (0–100)', (v) => parseInt(v, 10))
         .action(async (options) => {
-        await runConfidence({
+        const rc = await runConfidence({
             url: options.url,
             repo: options.repo,
             json: Boolean(options.json),
         });
+        const gate = evaluateConfidenceGate(rc, options.failOn, options.minScore);
+        if (gate.requested) {
+            const line = `[qulib] GATE: ${gate.passed ? 'PASS' : 'FAIL'} — ${gate.reason}`;
+            // Keep stdout pure JSON in --json mode; the gate line goes to stderr there.
+            if (options.json)
+                console.error(line);
+            else
+                console.log(line);
+            if (!gate.passed)
+                process.exitCode = 1;
+        }
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qulib/core",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Qulib — release confidence for deployed web apps. Fuses live-app quality, automation maturity, and API coverage into a single ship/caution/hold/block verdict.",
   "license": "MIT",
   "author": "Tapesh Nagarwal",