canary-test-cli 6.8.1 → 7.1.0

package/dist/engine/guardian/agent-tier.js

@@ -8,7 +8,7 @@
  * `tier.ts`), which imports it never (SC-11). Under the chosen **Option A**
  * invocation mechanism it **never calls an LLM directly**: it (i) turns
  * deterministic Tier-0 gaps into structured authoring intents, (ii) parses and
- * validates agent results into `Finding`/`GeneratedTest` records, and (iii)
+ * validates agent results into `GuardianFinding`/`GeneratedTest` records, and (iii)
  * enforces the write-safety model (opt-in, fork, collision, loop-guard) and the
  * block-once decision. It reaches an agent runtime only through an injected
  * `AgentInvoker` **port**; the production default (`RecordingInvoker`) records
@@ -26,7 +26,7 @@
  */
 import { existsSync } from 'node:fs';
 import { Severity } from './impact-mapper.js';
-import { Finding } from './pr-check.js';
+import { GuardianFinding } from './pr-check.js';
 /** Construct a {@link ReviewRequest} (a frozen dataclass in Python). */
 function reviewRequest(test_paths) {
     return { test_paths };
@@ -98,7 +98,7 @@ function parseReviewFindings(transcript) {
         if (severity === undefined)
             continue;
         const path = match.groups['path'];
-        findings.push(new Finding({
+        findings.push(new GuardianFinding({
             path,
             unit: path,
             kind: 'weak-test',

package/dist/engine/guardian/analysis-emit.js

@@ -14,7 +14,7 @@
  *     canary's records -- they never clobber a harness record and always pass
  *     `AnalysisArchive.safePath` (no traversal).
  *   - {@link buildAnalysisRecord} -- the v1.0 envelope wrapping the verbatim
- *     `render(fmt="json")` findings array.
+ *     `renderFindings(fmt="json")` findings array.
  *
  * SC-11 boundary: this module is deterministic filesystem/JSON only. It imports
  * no `AgentTier`/LLM-SDK module (only intra-guardian, agent-free helpers).
@@ -34,36 +34,21 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { mkdirSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { ensureAscii } from '../util/ensure-ascii.js';
 import { coverageDegradedNotice, coverageStatus, } from './coverage.js';
-import { combineNotices, render } from './pr-check.js';
+import { combineNotices, renderFindings } from './pr-check.js';
 // 1.1 adds the additive `coverage` block (#554); readers of 1.0 are unaffected.
 // 1.2 adds the additive `skipped` list (#582). Additive again, and bumped again
 // for the reason recorded in #572: a reader that pins a version must be able to
 // tell which fields it can rely on being present, and silence about a new field
 // is indistinguishable from the field being absent for a real reason.
 export const SCHEMA_VERSION = '1.2';
-export const SOURCE = 'canary-pr-guardian';
+const ANALYSIS_SOURCE = 'canary-pr-guardian';
 const REF_SAFE = /[^A-Za-z0-9._-]/g;
 const REF_MAX = 100; // cap the sanitized ref so a long branch never hits ENAMETOOLONG
 // The loud-fallback notices carry an em-dash (U+2014) as output data; written as
 // an escape to honor the ASCII-source rule.
 const EM_DASH = '\u{2014}';
-/**
- * Escape every non-ASCII (>= U+0080) code unit to a `\uXXXX` sequence, matching
- * Python's `json.dumps(..., ensure_ascii=True)` (the library default).
- */
-function ensureAscii(json) {
-    // Escape every UTF-16 code UNIT >= 0x80 to \uXXXX, matching Python
-    // json.dumps(ensure_ascii=True). Iterating by unit (not code point) means an
-    // astral char's surrogate pair emits \udXXX\udXXX, like Python; a code-point
-    // regex would stop at U+FFFF and leave astral chars raw.
-    let out = '';
-    for (let i = 0; i < json.length; i++) {
-        const c = json.charCodeAt(i);
-        out += c >= 0x80 ? '\\u' + c.toString(16).padStart(4, '0') : json[i];
-    }
-    return out;
-}
 /** Trim leading/trailing `-` characters (Python `str.strip("-")`). */
 function stripDashes(value) {
     return value.replace(/^-+/, '').replace(/-+$/, '');
@@ -76,7 +61,7 @@ function stripDashes(value) {
  * `REF_MAX` chars with a short hash suffix appended to preserve uniqueness --
  * only when truncation actually happens. Short refs are unchanged.
  */
-export function analysisFilename(ref, source = SOURCE) {
+export function analysisFilename(ref, source = ANALYSIS_SOURCE) {
     let safe = stripDashes(ref.replace(REF_SAFE, '-')) || 'local';
     if (safe.length > REF_MAX) {
         // sha1 is a filename disambiguator (not a security digest); it matches the
@@ -96,7 +81,8 @@ function isoUtcNow() {
     return new Date().toISOString().replace('Z', '+00:00');
 }
 /**
- * Build the v1.0 envelope. `findings` is exactly `render(fmt='json')`'s array.
+ * Build the v1.0 envelope. `findings` is exactly the array from
+ * `renderFindings(fmt='json')`.
  */
 export function buildAnalysisRecord(findings, args) {
     const { ref, gate, effective_tier, degraded_notice, exit_code } = args;
@@ -104,7 +90,7 @@ export function buildAnalysisRecord(findings, args) {
     // input's — so "no findings" can never be read as "coverage said so".
     const coverage = args.coverage ?? null;
     const notice = combineNotices(degraded_notice, coverage ? coverageDegradedNotice(coverage) : null);
-    const inner = JSON.parse(render(findings, 'json', effective_tier, notice));
+    const inner = JSON.parse(renderFindings(findings, 'json', effective_tier, notice));
     const active = findings.filter((f) => !f.suppressed);
     const suppressed = findings.filter((f) => f.suppressed);
     const byFidelity = {};
@@ -113,7 +99,7 @@ export function buildAnalysisRecord(findings, args) {
     }
     return {
         schemaVersion: SCHEMA_VERSION,
-        source: SOURCE,
+        source: ANALYSIS_SOURCE,
         ref,
         gate,
         exitCode: exit_code,
@@ -151,7 +137,7 @@ export const emitSeams = {
  * The analyses dir itself is created on demand by {@link emitAnalysis} (mirroring
  * harness `AnalysisArchive.save`'s recursive `mkdir`).
  */
-export function channelAvailable(analysesDir) {
+export function isChannelAvailable(analysesDir) {
     try {
         return statSync(dirname(analysesDir)).isDirectory();
     }
@@ -168,7 +154,7 @@ export function channelAvailable(analysesDir) {
  */
 export function emitAnalysis(findings, args) {
     const { analysesDir } = args;
-    if (!channelAvailable(analysesDir)) {
+    if (!isChannelAvailable(analysesDir)) {
         return {
             action: 'unavailable',
             path: null,
@@ -178,8 +164,8 @@ export function emitAnalysis(findings, args) {
     }
     const target = join(analysesDir, analysisFilename(args.ref));
     try {
-        // Build INSIDE the try: a non-I/O error (from JSON/render) would otherwise
-        // crash pr-check instead of degrading.
+        // Build INSIDE the try: a non-I/O error (from JSON/renderFindings) would
+        // otherwise crash pr-check instead of degrading.
         const record = emitSeams.buildAnalysisRecord(findings, args);
         mkdirSync(analysesDir, { recursive: true });
         // Atomic write: stage into a same-dir temp then rename (atomic on one

package/dist/engine/guardian/cli.js

@@ -13,8 +13,8 @@
  *     `_branch_protection_client` seams were replaced.
  *   - Commands are THIN: parse -> call the already-ported guardian library ->
  *     emit. No business logic lives in a handler.
- *   - Business exit codes are carried by throwing {@link CliExit} (Python's
- *     `typer.Exit(n)`); `parseAsync` from a test catches it to read the code.
+ *   - Business exit codes are carried by throwing {@link CliExitError}
+ *     (Python's `typer.Exit(n)`); a test's `parseAsync` catches it to read it.
  *     `.exitOverride()` turns commander's own usage errors into throws too, so a
  *     test never terminates the process.
  *
@@ -58,7 +58,8 @@ import { buildApiDelta, writeApiDelta } from './delta-emitter.js';
 import { extractApiDiff } from './diff-extractor.js';
 import { HardGateAbstained, HardGateBlocked, RestBranchProtectionClient, applyHardGate, renderPlaybook, } from './hard-gate.js';
 import { mapImpact } from './impact-mapper.js';
-import { applySuppressions, buildFindings, buildWeakTestFindings, computeExitCode, effectiveGraphDepth, filterHeuristicNoise, filterSkipped, filterTestSupportUnits, filterTestUnits, filterTypeOnlyUnits, findReexportOnly, loadGuardianConfig, render, scopeDiff, } from './pr-check.js';
+import { ensureAscii } from '../util/ensure-ascii.js';
+import { applySuppressions, buildFindings, buildWeakTestFindings, computeExitCode, effectiveGraphDepth, filterHeuristicNoise, filterSkipped, filterTestSupportUnits, filterTestUnits, filterTypeOnlyUnits, findReexportOnly, loadGuardianConfig, renderFindings, scopeDiff, } from './pr-check.js';
 import { RestGitHubClient, degradationAnnotation, upsertStickyComment, } from './pr-comment.js';
 import { buildSummary } from './summary-emitter.js';
 import { resolveTier } from './tier.js';
@@ -71,12 +72,12 @@ const CROSS = '\u{2717}';
  * Business exit signal. Thrown from a handler to carry an exit code the way
  * Python's `typer.Exit(code)` did; the runner catches it to read the code.
  */
-export class CliExit extends Error {
+export class CliExitError extends Error {
     code;
     constructor(code) {
         super(`exit ${code}`);
         this.code = code;
-        this.name = 'CliExit';
+        this.name = 'CliExitError';
     }
 }
 /**
@@ -94,10 +95,10 @@ function normalizeUsageExit(err) {
     throw err;
 }
 /** Raised by `deps.sleep` to break the `watch` poll loop (Ctrl+C analog). */
-export class WatchInterrupt extends Error {
+export class WatchInterruptError extends Error {
     constructor() {
         super('watch interrupted');
-        this.name = 'WatchInterrupt';
+        this.name = 'WatchInterruptError';
     }
 }
 /** Process-backed defaults for production (the `guardianCommand` export). */
@@ -148,21 +149,6 @@ export function defaultDeps() {
         sleep: (secs) => new Promise((resolve) => setTimeout(resolve, secs * 1000)),
     };
 }
-/**
- * Escape non-ASCII to `\uXXXX`, matching Python `json.dumps(ensure_ascii=True)`.
- */
-function ensureAscii(json) {
-    // Escape every UTF-16 code UNIT >= 0x80 to \uXXXX, matching Python
-    // json.dumps(ensure_ascii=True). Iterating by unit (not code point) means an
-    // astral char's surrogate pair emits \udXXX\udXXX, like Python; a code-point
-    // regex would stop at U+FFFF and leave astral chars raw.
-    let out = '';
-    for (let i = 0; i < json.length; i++) {
-        const c = json.charCodeAt(i);
-        out += c >= 0x80 ? '\\u' + c.toString(16).padStart(4, '0') : json[i];
-    }
-    return out;
-}
 /** ISO-8601 UTC timestamp with a `+00:00` offset (Python `isoformat`-shaped). */
 function isoUtcNow() {
     return new Date().toISOString().replace('Z', '+00:00');
@@ -212,8 +198,9 @@ export function prContextFromEnv(env) {
  * the contributor's branch and stays resolvable.
  *
  * Returns `null` rather than a partial URL whenever repo or SHA is missing, so
- * {@link render} falls back to plain code text. That degradation is deliberate:
- * an unresolvable link still *looks* clickable, which is worse than no link.
+ * {@link renderFindings} falls back to plain code text. That degradation is
+ * deliberate: an unresolvable link still *looks* clickable, which is worse than
+ * no link.
  */
 export function blobBaseFromEnv(env) {
     const repo = env['GITHUB_REPOSITORY'];
@@ -513,7 +500,7 @@ function warnIfEmptyCiDiff(resolved, unitCount, deps) {
 function loadSpec(path, deps) {
     if (!existsSync(path)) {
         deps.err(`Spec file not found: ${path}`);
-        throw new CliExit(2);
+        throw new CliExitError(2);
     }
     const text = readFileSync(path, 'utf-8');
     // Python `_load_spec`: `.json` -> json.loads; otherwise yaml.safe_load (with a
@@ -627,16 +614,16 @@ function validateCoverageCmd(path, opts, deps) {
         const st = statSync(path);
         if (st.isDirectory() || st.size > MAX_COVERAGE_BYTES) {
             deps.out(`${pc.red(pc.bold(`${CROSS} cannot read ${path}:`))} not a readable file within the size limit`);
-            throw new CliExit(2);
+            throw new CliExitError(2);
         }
         text = readFileSync(path, 'utf-8');
     }
     catch (exc) {
-        if (exc instanceof CliExit)
+        if (exc instanceof CliExitError)
             throw exc;
         const msg = exc instanceof Error ? exc.message : String(exc);
         deps.out(`${pc.red(pc.bold(`${CROSS} cannot read ${path}:`))} ${msg}`);
-        throw new CliExit(2);
+        throw new CliExitError(2);
     }
     let data;
     try {
@@ -645,7 +632,7 @@ function validateCoverageCmd(path, opts, deps) {
     catch (exc) {
         const msg = exc instanceof Error ? exc.message : String(exc);
         deps.out(`${pc.red(pc.bold(`${CROSS} ${path} is not valid JSON:`))} ${msg}`);
-        throw new CliExit(2);
+        throw new CliExitError(2);
     }
     const problems = validateCoverageJson(data);
     const errors = problems.filter((p) => p.severity === 'error');
@@ -692,7 +679,7 @@ function validateCoverageCmd(path, opts, deps) {
         }
     }
     if (errors.length > 0 || (opts.strict && warnings.length > 0)) {
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
 }
 /**
@@ -713,7 +700,7 @@ async function hardenGateCmd(opts, deps) {
     const repo = opts.repo;
     if (!repo) {
         deps.out(`${pc.red(pc.bold(`${CROSS} no repo`))} ${EM_DASH} pass --repo owner/repo or set GITHUB_REPOSITORY.`);
-        throw new CliExit(2);
+        throw new CliExitError(2);
     }
     const playbook = renderPlaybook(repo, opts.branch, opts.check);
     // #490: the readiness evidence the promotion is supposed to rest on.
@@ -730,7 +717,7 @@ async function hardenGateCmd(opts, deps) {
     if (!opts.token) {
         deps.out(`${pc.red(pc.bold(`${CROSS} --apply needs an admin token`))} (pass --token or set GITHUB_TOKEN).\n`);
         deps.out(playbook);
-        throw new CliExit(2);
+        throw new CliExitError(2);
     }
     const client = deps.buildBranchProtectionClient(repo, opts.token);
     let plan;
@@ -745,12 +732,12 @@ async function hardenGateCmd(opts, deps) {
             deps.out(outcome.summaryLine);
             deps.out(`${pc.red(pc.bold(`${CROSS} ${exc.reason}`))}\n`);
             deps.out(exc.playbook);
-            throw new CliExit(outcome.exitCode); // 3, never 1
+            throw new CliExitError(outcome.exitCode); // 3, never 1
         }
         if (exc instanceof HardGateBlocked) {
             deps.out(`${pc.red(pc.bold(`${CROSS} ${exc.reason}`))}\n`);
             deps.out(exc.playbook);
-            throw new CliExit(1);
+            throw new CliExitError(1);
         }
         throw exc;
     }
@@ -785,7 +772,7 @@ async function collectAdjudicationsCmd(opts, deps) {
     }
     if (!repo || prNumber === undefined) {
         deps.out(`${pc.red(pc.bold(`${CROSS} no PR context`))} ${EM_DASH} pass --repo and --pr, or run in Actions.`);
-        throw new CliExit(2);
+        throw new CliExitError(2);
     }
     const client = deps.buildReactionsClient(repo, prNumber);
     const res = await collectAdjudications(client, {
@@ -811,7 +798,7 @@ async function collectAdjudicationsCmd(opts, deps) {
     }
     if (res.action === 'unavailable') {
         deps.out(pc.red(pc.bold(`${CROSS} ${res.notice ?? 'not persisted'}`)));
-        throw new CliExit(1);
+        throw new CliExitError(1);
     }
 }
 /** Aggregate the persisted adjudications into the promotion evidence (#490). */
@@ -835,7 +822,7 @@ function precisionCmd(opts, deps) {
  * read-only-token degradation is surfaced LOUDLY.
  */
 async function postStickyComment(findings, resolution, deps, gateMeta = null) {
-    const body = render(findings, 'comment', resolution.effective, resolution.degraded_notice, gateMeta, blobBaseFromEnv(deps.env));
+    const body = renderFindings(findings, 'comment', resolution.effective, resolution.degraded_notice, gateMeta, blobBaseFromEnv(deps.env));
     const ctx = prContextFromEnv(deps.env);
     if (ctx === null) {
         deps.out(`guardian: no PR context in env ${EM_DASH} printing instead.`);
@@ -905,7 +892,7 @@ function abstainPrCheck(skipped, format, deps) {
         // only surface a machine can read.
         { findings: [], tier: 0, checked: 0, abstained: true, skipped }, null, 2)));
     }
-    throw new CliExit(outcome.exitCode); // EXIT_ABSTAINED
+    throw new CliExitError(outcome.exitCode); // EXIT_ABSTAINED
 }
 /** Resolve the analyses-channel dir (test override, else repo-root default). */
 function resolveAnalysesDir(override, deps) {
@@ -968,7 +955,7 @@ async function prCheckCmd(opts, deps) {
     // entirely (no diff scoped, no comment posted, exit 0).
     if (opts.postComment && !config.pr_enabled) {
         deps.out(`guardian: pr.enabled is false ${EM_DASH} skipping PR surface.`);
-        throw new CliExit(0);
+        throw new CliExitError(0);
     }
     const effectiveGate = opts.gate ?? config.pr_gate;
     // #490: read reviewer 👍/👎 off the PREVIOUS run's sticky comment before this
@@ -1109,9 +1096,9 @@ async function prCheckCmd(opts, deps) {
     }
     else if (!opts.emitAnalysis && !opts.postComment) {
         // Local, non-posting default: render to stdout in `--format`.
-        deps.out(render(findings, opts.format, resolution.effective, resolution.degraded_notice, gateMeta, blobBaseFromEnv(deps.env)));
+        deps.out(renderFindings(findings, opts.format, resolution.effective, resolution.degraded_notice, gateMeta, blobBaseFromEnv(deps.env)));
     }
-    throw new CliExit(exitCode);
+    throw new CliExitError(exitCode);
 }
 // --- author-plan --------------------------------------------------------------
 /**
@@ -1246,7 +1233,7 @@ async function watchCmd(opts, deps) {
         }
     }
     catch (exc) {
-        if (exc instanceof WatchInterrupt) {
+        if (exc instanceof WatchInterruptError) {
             deps.out(`\n${pc.yellow('Watch stopped.')}`);
             return;
         }
@@ -1262,7 +1249,7 @@ function collect(value, previous) {
  * Build a fresh `guardian` command wired to `depsInit` (process-backed defaults
  * fill any gap). Every subcommand uses `.exitOverride()` so a usage error throws
  * a `CommanderError` rather than terminating the process -- tests read the exit
- * code from the thrown error (or from {@link CliExit} for business exits).
+ * code from the thrown error (or from {@link CliExitError} for business exits).
  */
 export function createGuardianCommand(depsInit = {}) {
     const deps = { ...defaultDeps(), ...depsInit };