canary-test-cli 5.15.0 → 6.0.0

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

@@ -0,0 +1,338 @@
+/**
+ * Agent-tier capability boundary for canary-pr-guardian (Phase 4).
+ *
+ * Faithful TypeScript port of `agent/guardian/agent_tier.py`.
+ *
+ * This is the **one** module where agent orchestration is allowed -- it sits
+ * OUTSIDE the Tier-0 deterministic engine (`pr-check.ts`/`coverage.ts`/
+ * `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)
+ * 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
+ * an intent and calls nothing, while the `canary-pr-guardian` SKILL fulfils it
+ * in-session.
+ *
+ * Python->TS nuances:
+ *   - `pathlib.Path` fields become plain POSIX path strings (`test_paths`,
+ *     `repo_root`), matching how the rest of the ts port models paths.
+ *   - `dataclasses.replace(...)` becomes constructing a fresh `GeneratedTest`
+ *     with a spread override (the invoker test double does this).
+ *   - `_target_test_path` reimplements the `pathlib` parent/stem/suffix/as_posix
+ *     algebra directly so a bare filename yields no `./` prefix (Python drops
+ *     the `.` parent on join).
+ */
+import { existsSync } from 'node:fs';
+import { Severity } from './impact-mapper.js';
+import { Finding } from './pr-check.js';
+/** Construct a {@link ReviewRequest} (a frozen dataclass in Python). */
+export function reviewRequest(test_paths) {
+    return { test_paths };
+}
+/**
+ * An authoring intent and its (eventual) result.
+ *
+ * v1 `status`: `'planned'` (the {@link RecordingInvoker} default -- the SKILL
+ * fulfils it in-session), `'authored'` (a fake/real invoker wrote it), or
+ * `'skipped'` (a safety guard blocked it, with `skip_reason`).
+ */
+export class GeneratedTest {
+    gap;
+    target_path;
+    requirement; // NL requirement -> /canary-write-test $ARGUMENTS
+    status; // planned | authored | skipped
+    written_path;
+    skip_reason;
+    constructor(init) {
+        this.gap = init.gap;
+        this.target_path = init.target_path;
+        this.requirement = init.requirement;
+        this.status = init.status ?? 'planned';
+        this.written_path = init.written_path ?? null;
+        this.skip_reason = init.skip_reason ?? null;
+    }
+}
+/**
+ * Default production invoker: calls NOTHING.
+ *
+ * Returns an empty transcript and a still-`planned` intent so the SKILL fulfils
+ * the work in-session (Option A). This is what keeps the deterministic layer
+ * LLM-free.
+ */
+export class RecordingInvoker {
+    review(_request) {
+        void _request;
+        return ''; // nothing reviewed here; SKILL drives canary-test-reviewer
+    }
+    author(intent) {
+        return intent; // status stays 'planned'; SKILL drives canary-test-author
+    }
+}
+// A canary-test-reviewer transcript line: `[severity] path:line <message>`.
+// The message tail is optional and captured as evidence. Anchored ^...$ with no
+// flags -- matched per-line (the transcript is split first), so `$` binds the
+// end of each line and `.` never needs to span newlines.
+const REVIEW_LINE_RE = /^\s*\[(?<severity>[^\]]+)\]\s+(?<path>\S+?):(?<line>\d+)(?:\s+(?<msg>.*))?$/;
+// Case-insensitive lookup of a reviewer severity token -> the Tier-0 Severity.
+const SEVERITY_BY_NAME = new Map(Object.values(Severity).map((s) => [s, s]));
+/**
+ * Parse `canary-test-reviewer`'s `[severity] path:line` lines into `weak-test`
+ * Findings.
+ *
+ * A malformed line (no `[severity] path:line` shape) or an unknown severity
+ * token is skipped, never raised. An empty transcript (the {@link
+ * RecordingInvoker} default) yields `[]` -- the SKILL reports its review
+ * directly in-session.
+ */
+export function parseReviewFindings(transcript) {
+    const findings = [];
+    for (const raw of transcript.split(/\r\n|\r|\n/)) {
+        const match = REVIEW_LINE_RE.exec(raw);
+        if (match === null || match.groups === undefined)
+            continue;
+        // `severity` and `path` are required capture groups -- present on any match.
+        const severityToken = match.groups['severity'];
+        const severity = SEVERITY_BY_NAME.get(severityToken.trim().toLowerCase());
+        if (severity === undefined)
+            continue;
+        const path = match.groups['path'];
+        findings.push(new Finding({
+            path,
+            unit: path,
+            kind: 'weak-test',
+            severity,
+            evidence: (match.groups['msg'] ?? '').trim(),
+        }));
+    }
+    return findings;
+}
+/**
+ * v1 {@link AgentTier}: drives `canary-test-reviewer`/`-author` via an injected
+ * invoker. Calls NO LLM itself (Option A) -- the invoker is the port.
+ */
+export class InSessionAgentTier {
+    invoker;
+    constructor(init = {}) {
+        this.invoker = init.invoker ?? new RecordingInvoker();
+    }
+    /**
+     * Tier 1 (read-only): ask the reviewer to audit `affected_tests` and parse the
+     * transcript into `weak-test` Findings. Writes nothing.
+     */
+    audit_test_quality(affected_tests) {
+        const transcript = this.invoker.review(reviewRequest([...affected_tests]));
+        return parseReviewFindings(transcript);
+    }
+    /**
+     * Tier 2: plan the safe authoring intents, then hand each `planned` intent to
+     * the injected invoker (the {@link RecordingInvoker} default leaves it
+     * `planned` -- Option A; a fake/real invoker returns `authored`). `skipped`
+     * records pass through untouched. Absent `ctx` the caller gets the fail-closed
+     * default (opt-in off, tier 0 -> everything skipped).
+     */
+    author_tests(gaps, ctx = null) {
+        const plan = planAuthoring(gaps, ctx ?? new AuthoringContext(false, 0));
+        const out = [];
+        for (const intent of plan) {
+            if (intent.status === 'planned') {
+                out.push(this.invoker.author(intent)); // -> authored (fake/real)
+            }
+            else {
+                out.push(intent); // skipped, unchanged
+            }
+        }
+        return out;
+    }
+}
+/**
+ * Reports the agent tier ceiling from an explicit opt-in signal.
+ *
+ * Reads env `CANARY_GUARDIAN_AGENT` (`0|1|2`), which the SKILL exports when it
+ * runs in-session. Unset or invalid -> `0` (so CI, where the env is unset, stays
+ * Tier-0). Returns an `int` only -- imports no LLM (SC-11), so it drops into
+ * `resolveTier` unchanged as the real `AgentCapabilityProbe`.
+ */
+export class InSessionAgentProbe {
+    env;
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    availableTier() {
+        const raw = this.env['CANARY_GUARDIAN_AGENT'] ?? '0';
+        return raw === '0' || raw === '1' || raw === '2'
+            ? Number.parseInt(raw, 10)
+            : 0;
+    }
+}
+// --- Tier-2 authoring safety model (D4 guards a-d) -- pure, writes nothing. ---
+// Language-specific test-path templates (peer-layout mirror).
+const TS_JS_SUFFIXES = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts']);
+/**
+ * Everything `planAuthoring` needs to apply the four safety guards.
+ *
+ * All fields are supplied by the caller (the `author-plan` CLI seam); this keeps
+ * the guards pure and deterministic. `repo_root` is a POSIX path string (the
+ * Python `pathlib.Path` field).
+ */
+export class AuthoringContext {
+    author_tests_optin; // config.precommit_author_tests (default False) -- (d)
+    effective_tier; // from resolveTier (2 == can author)
+    is_fork; // reuse Phase-2 fork/403 detection -- (b)
+    repo_root; // collision + sentinel base
+    authored_sentinel_present; // loop-guard -- (a)
+    constructor(author_tests_optin, effective_tier, init = {}) {
+        this.author_tests_optin = author_tests_optin;
+        this.effective_tier = effective_tier;
+        this.is_fork = init.is_fork ?? false;
+        this.repo_root = init.repo_root ?? '.';
+        this.authored_sentinel_present = init.authored_sentinel_present ?? false;
+    }
+}
+/** POSIX `parent`/`stem`/`suffix` split mirroring `pathlib.PurePosixPath`. */
+function posixParts(path) {
+    const segments = path.split('/');
+    const base = segments.pop() ?? '';
+    const parent = segments.join('/');
+    const dot = base.lastIndexOf('.');
+    if (dot > 0) {
+        return { parent, stem: base.slice(0, dot), suffix: base.slice(dot) };
+    }
+    return { parent, stem: base, suffix: '' };
+}
+/** Join a POSIX parent and child the way `pathlib` `/` + `as_posix()` does. */
+function joinPosix(parent, child) {
+    return parent === '' || parent === '.' ? child : `${parent}/${child}`;
+}
+/**
+ * Deterministic target test path for a gap, mirroring peer test layout.
+ *
+ * - `.py` source -> `{parent}/test_{stem}.py` (pytest convention);
+ * - TS/JS source -> `{parent}/{stem}.test{suffix}` (jest/vitest convention);
+ * - anything else -> `{parent}/{stem}.test{suffix}` as a safe default.
+ *
+ * Returns a repo-relative POSIX path string.
+ */
+export function targetTestPath(gap) {
+    const { parent, stem, suffix } = posixParts(gap.path);
+    let targetName;
+    if (suffix === '.py') {
+        targetName = `test_${stem}.py`;
+    }
+    else if (TS_JS_SUFFIXES.has(suffix)) {
+        targetName = `${stem}.test${suffix}`;
+    }
+    else {
+        targetName = `${stem}.test${suffix || ''}`;
+    }
+    return joinPosix(parent, targetName);
+}
+/**
+ * NL requirement string the `/canary-write-test` command consumes as
+ * `$ARGUMENTS` -- names the unit and the untested change.
+ */
+function requirementFor(gap) {
+    return (`Write tests for \`${gap.unit}\` in \`${gap.path}\` covering the newly ` +
+        `added, currently-untested code (guardian finding: ${gap.kind}).`);
+}
+// The skip-reason strings carry an em-dash (U+2014) as load-bearing output data
+// (surfaced to the SKILL); written as an escape to honor the ASCII-source rule.
+const EM_DASH = '\u{2014}';
+/**
+ * Return the first failing guard's reason, or `null` if all guards pass.
+ *
+ * Guard order (fail-closed, cheapest/broadest first): (d) opt-in, (d) tier,
+ * (b) fork, (a) loop-guard, (c) collision.
+ */
+function authoringSkipReason(gap, ctx) {
+    if (!ctx.author_tests_optin) {
+        return `opt-in: preCommit.authorTests is not enabled ${EM_DASH} authoring is off by default`;
+    }
+    if (ctx.effective_tier < 2) {
+        return `tier: effective tier ${ctx.effective_tier} < 2 ${EM_DASH} cannot author`;
+    }
+    if (ctx.is_fork) {
+        return `fork: read-only ${EM_DASH} guardian never writes on a fork PR`;
+    }
+    if (ctx.authored_sentinel_present) {
+        return `loop-guard: guardian tests already authored this run ${EM_DASH} not re-authoring`;
+    }
+    const target = joinPosix(ctx.repo_root, targetTestPath(gap));
+    if (existsSync(target)) {
+        return `collision: ${targetTestPath(gap)} exists ${EM_DASH} another PR/session may own it`;
+    }
+    return null;
+}
+/**
+ * Apply the four D4 guards and emit one {@link GeneratedTest} per gap.
+ *
+ * A gap that clears every guard becomes a `planned` intent (non-empty
+ * `requirement` + `target_path`); any guard failure becomes a `skipped` record
+ * carrying the reason. Pure -- reads disk only to detect collisions (guard c)
+ * and writes **nothing**.
+ */
+export function planAuthoring(gaps, ctx) {
+    const out = [];
+    for (const gap of gaps) {
+        const target = targetTestPath(gap);
+        const requirement = requirementFor(gap);
+        const reason = authoringSkipReason(gap, ctx);
+        if (reason === null) {
+            out.push(new GeneratedTest({
+                gap,
+                target_path: target,
+                requirement,
+                status: 'planned',
+            }));
+        }
+        else {
+            out.push(new GeneratedTest({
+                gap,
+                target_path: target,
+                requirement,
+                status: 'skipped',
+                skip_reason: reason,
+            }));
+        }
+    }
+    return out;
+}
+/** The pre-commit block-once decision computed from an authoring run. */
+export class BlockDecision {
+    block;
+    message;
+    authored_count;
+    constructor(block, message, authored_count) {
+        this.block = block;
+        this.message = message;
+        this.authored_count = authored_count;
+    }
+}
+// The block message carries a no-entry sign (U+26D4) and an em-dash (U+2014) as
+// load-bearing output data (shown to the committer); written as escapes.
+const NO_ENTRY_SIGN = '\u{26D4}';
+/**
+ * Block the commit ONCE iff >=1 ACTIONABLE (non-`skipped`) intent this run.
+ *
+ * Under Option A the production {@link RecordingInvoker} leaves every intent
+ * `planned` -- the SKILL then authors each non-`skipped` intent in-session -- so
+ * blocking only on `authored` would never gate the real path (the bug FIX 1
+ * fixes). An intent is actionable when its `status != "skipped"` (`planned` OR
+ * `authored`); an all-`skipped` run changed nothing, so it never blocks.
+ * `authored_count` counts those actionable intents (the field name the
+ * CLI/JSON/SKILL read). The message instructs "review ... then re-commit" (D4);
+ * the actual sentinel write + `git add` happen in the hook/SKILL -- this is pure
+ * decision logic.
+ */
+export function decideBlock(results) {
+    const actionable = results.filter((r) => r.status !== 'skipped');
+    const count = actionable.length;
+    if (count === 0) {
+        return new BlockDecision(false, '', 0);
+    }
+    const message = `${NO_ENTRY_SIGN} canary-guardian: ${count} test(s) authored & staged ` +
+        `${EM_DASH} review the generated code, then re-commit.`;
+    return new BlockDecision(true, message, count);
+}
+//# sourceMappingURL=agent-tier.js.map

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

@@ -0,0 +1,201 @@
+/**
+ * Deterministic emit for the harness reverse-handoff (#899) producer contract.
+ *
+ * Faithful TypeScript port of `agent/guardian/analysis_emit.py`.
+ *
+ * Phase 5 turns the guardian's Tier-0 result into a **structured canary
+ * analysis** that a future harness gate surface can consume in-flow. This module
+ * owns the producer half:
+ *
+ *   - {@link analysisFilename} -- the `canary-pr-guardian-<ref>.json` naming
+ *     convention. The `canary-pr-guardian-` prefix is load-bearing: harness's own
+ *     `AnalysisArchive` stores records as `<issueId>.json` and reads *every*
+ *     `*.json` in `.harness/analyses/`, so the prefix + sanitized ref namespaces
+ *     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.
+ *
+ * SC-11 boundary: this module is deterministic filesystem/JSON only. It imports
+ * no `AgentTier`/LLM-SDK module (only intra-guardian, agent-free helpers).
+ *
+ * Python->TS nuances:
+ *   - `json.dumps(record, indent=2)` becomes `ensureAscii(JSON.stringify(record,
+ *     null, 2))`. `JSON.stringify` with indent 2 matches Python's `(', ', ': ')`
+ *     separators byte-for-byte; `ensureAscii` restores the `ensure_ascii=True`
+ *     default so a non-ASCII evidence char (em-dash) escapes identically.
+ *   - insertion-ordered object literals reproduce Python dict key order, and a
+ *     first-seen-ordered plain object reproduces `Counter` -> `dict` order for
+ *     `byFidelity`.
+ *   - `tempfile.mkstemp` + `os.replace` becomes a same-dir random temp +
+ *     `renameSync`, both behind {@link emitSeams} so tests can spy them the way
+ *     the Python tests monkeypatch `emit_mod.os.replace` / `build_analysis_record`.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdirSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { render } from './pr-check.js';
+export const SCHEMA_VERSION = '1.0';
+export const 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(/-+$/, '');
+}
+/**
+ * `<source>-<sanitized-ref>.json`; empty/blank ref -> `<source>-local.json`.
+ *
+ * A very long ref would produce a filename that trips `ENAMETOOLONG` (always
+ * degrades, never uses the channel), so the sanitized ref is truncated to
+ * `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) {
+    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
+        // Python oracle's hashlib.sha1(ref)[:8] cache-filename contract and the
+        // input is a non-secret git ref. Changing it would break that byte contract.
+        const algo = 'sha1'; // harness-ignore SEC-CRY-001: filename hash, not crypto
+        const digest = createHash(algo)
+            .update(ref, 'utf-8')
+            .digest('hex')
+            .slice(0, 8);
+        safe = `${safe.slice(0, REF_MAX)}-${digest}`;
+    }
+    return `${source}-${safe}.json`;
+}
+/** ISO-8601 UTC timestamp with a `+00:00` offset (Python `isoformat`-shaped). */
+function isoUtcNow() {
+    return new Date().toISOString().replace('Z', '+00:00');
+}
+/**
+ * Build the v1.0 envelope. `findings` is exactly `render(fmt='json')`'s array.
+ */
+export function buildAnalysisRecord(findings, args) {
+    const { ref, gate, effective_tier, degraded_notice, exit_code } = args;
+    const inner = JSON.parse(render(findings, 'json', effective_tier, degraded_notice));
+    const active = findings.filter((f) => !f.suppressed);
+    const suppressed = findings.filter((f) => f.suppressed);
+    const byFidelity = {};
+    for (const f of findings) {
+        byFidelity[f.fidelity] = (byFidelity[f.fidelity] ?? 0) + 1;
+    }
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        source: SOURCE,
+        ref,
+        gate,
+        exitCode: exit_code,
+        tier: effective_tier,
+        degradedNotice: degraded_notice,
+        summary: {
+            total: findings.length,
+            unaddressed: active.length,
+            suppressed: suppressed.length,
+            byFidelity,
+        },
+        findings: inner.findings,
+        analyzedAt: args.analyzed_at ?? isoUtcNow(),
+    };
+}
+/**
+ * Seams the tests spy: `buildAnalysisRecord` (Python monkeypatches
+ * `build_analysis_record`) and `replace` (Python monkeypatches `os.replace`).
+ * `emitAnalysis` calls them through this object so a `vi.spyOn(emitSeams, ...)`
+ * takes effect exactly like the Python `monkeypatch.setattr`.
+ */
+export const emitSeams = {
+    buildAnalysisRecord,
+    replace: (src, dst) => renameSync(src, dst),
+};
+/**
+ * True iff the harness home (`dirname(analysesDir)`, i.e. `.harness/`) exists.
+ *
+ * The analyses dir itself is created on demand by {@link emitAnalysis} (mirroring
+ * harness `AnalysisArchive.save`'s recursive `mkdir`).
+ */
+export function channelAvailable(analysesDir) {
+    try {
+        return statSync(dirname(analysesDir)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write one record to `analysesDir/<filename>`.
+ *
+ * On an absent channel or an I/O error (read-only FS, permission), return an
+ * `'unavailable'` {@link EmitResult} carrying a loud notice -- never silently
+ * drop the record (SC-10 fallback).
+ */
+export function emitAnalysis(findings, args) {
+    const { analysesDir } = args;
+    if (!channelAvailable(analysesDir)) {
+        return {
+            action: 'unavailable',
+            path: null,
+            notice: 'guardian: harness analyses channel unavailable ' +
+                `(.harness/ absent) ${EM_DASH} falling back to the sticky comment`,
+        };
+    }
+    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.
+        const record = emitSeams.buildAnalysisRecord(findings, args);
+        mkdirSync(analysesDir, { recursive: true });
+        // Atomic write: stage into a same-dir temp then rename (atomic on one
+        // filesystem). A torn/partial file would break the harness consumer.
+        const tmp = join(analysesDir, `.tmp-${randomBytes(8).toString('hex')}.json`);
+        writeFileSync(tmp, ensureAscii(JSON.stringify(record, null, 2)), 'utf-8');
+        try {
+            emitSeams.replace(tmp, target);
+        }
+        catch (err) {
+            // Clean up the staged temp so a failed rename leaves no leftover.
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                // best-effort
+            }
+            throw err;
+        }
+    }
+    catch (exc) {
+        // Broadened beyond I/O: any build/render/write failure degrades to the LOUD
+        // fallback rather than crashing pr-check (the CLI turns this notice into a
+        // `::warning::` + sticky comment).
+        const message = exc instanceof Error ? exc.message : String(exc);
+        return {
+            action: 'unavailable',
+            path: null,
+            notice: `guardian: analyses build/write failed (${message}) ${EM_DASH} ` +
+                'falling back to the sticky comment',
+        };
+    }
+    return { action: 'emitted', path: String(target), notice: null };
+}
+//# sourceMappingURL=analysis-emit.js.map