argus-reviewer-e2e 0.1.2 → 0.2.0

package/dist/review/adjudicate.d.ts

@@ -0,0 +1,63 @@
+import { DecisionClient } from '../vision/decisions.js';
+/**
+ * U8 finding adjudication — one batched Jev decide() scores each
+ * synthesized finding's true-positive probability before posting. Same
+ * posture as the secrets lane: Jev annotates/routes, never gates.
+ * `p` lands on the finding record and the sticky confidence column;
+ * suppression is scoped to `nit`/`q` severities whose false-positive
+ * confidence exceeds `findingThreshold` — `bug`/`risk` are never
+ * suppressed, and a Jev outage leaves every finding unadjudicated and
+ * unsuppressed (degrade open).
+ *
+ * `findingThreshold` is the required P(false positive): a nit/q is
+ * suppressed when `1 - p > threshold`, i.e. `p < 1 - threshold`.
+ * Default 1.0 → nothing can exceed 100% FP → annotate-only.
+ */
+export interface AdjudicableFinding {
+    file: string;
+    line?: number;
+    severity: string;
+    category?: string;
+    message: string;
+}
+export interface FindingAdjudicationRecord {
+    file: string;
+    line?: number;
+    severity: string;
+    category?: string;
+    /** Finding text — capped; suppressed findings keep their message in audit. */
+    message: string;
+    adjudicated: boolean;
+    /** Jev P(true positive) for this finding. */
+    p?: number;
+    /** nit/q below the FP bar — kept for audit, removed from findings. */
+    suppressed?: boolean;
+}
+/** The audit half of the result — what report.findingAdjudication stores. */
+export interface FindingAdjudicationAudit {
+    records: FindingAdjudicationRecord[];
+    /** Findings past MAX_CANDIDATES — unadjudicated, never suppressed. */
+    overflow: number;
+    /** Whole-call failure — nothing adjudicated, nothing suppressed. */
+    unadjudicated?: boolean;
+}
+export interface FindingAdjudicationResult<T extends AdjudicableFinding> extends FindingAdjudicationAudit {
+    /** Surviving findings — adjudicated ones carry `p`. */
+    findings: (T & {
+        p?: number;
+    })[];
+}
+export declare function adjudicateFindings<T extends AdjudicableFinding>(opts: {
+    findings: T[];
+    /** PR file patches keyed by filename — Jev state context. */
+    patchByFile?: Map<string, string>;
+    threshold: number;
+    /**
+     * User-configured blocking severities — a severity listed here drives
+     * the verdict, so it must never be suppressed even if it is nit/q
+     * (otherwise Jev suppression could flip the commit-status gate).
+     */
+    blockSeverities?: string[];
+    client: DecisionClient;
+    model?: string;
+}): Promise<FindingAdjudicationResult<T>>;

package/dist/review/adjudicate.js

@@ -0,0 +1,111 @@
+import { debug } from '../debug.js';
+import { describeDecisionError, isNoulAnswer, MAX_CANDIDATES, } from '../vision/decisions.js';
+/** Suppression is scoped to severities that never drive the verdict. */
+const SUPPRESSIBLE = new Set(['nit', 'q']);
+const MAX_PATCH_EXCERPT = 4000;
+/** Aggregate patch-state bound — 50 unique files x 4KB is still ~200KB. */
+const MAX_PATCH_STATE_CHARS = 24_000;
+/** Audit-record message bound — full text already lives in findings. */
+const MAX_RECORD_MESSAGE = 300;
+export async function adjudicateFindings(opts) {
+    const capped = opts.findings.slice(0, MAX_CANDIDATES);
+    const overflow = opts.findings.length - capped.length;
+    const pByIdx = new Array(capped.length);
+    let adjudicationFailed = false;
+    if (capped.length > 0) {
+        try {
+            const questions = {};
+            capped.forEach((_f, i) => {
+                questions[`f_${i}`] = {
+                    type: 'noul',
+                    instructions: `state.findings[${i}]: is this code-review finding a real problem the ` +
+                        'PR author should act on? Its file patch is under state.patches. ' +
+                        'Answer no for speculative style nits, issues already handled by ' +
+                        'guards visible in the patch, and findings that merely restate ' +
+                        'what the code does.',
+                };
+            });
+            // Each finding references its patch by filename — sending patches
+            // once keyed by file avoids repeating a 4KB excerpt per finding
+            // on the same file; an aggregate bound caps the whole state.
+            const patches = {};
+            let patchBudget = MAX_PATCH_STATE_CHARS;
+            for (const f of capped) {
+                if (patchBudget <= 0)
+                    break;
+                if (patches[f.file] !== undefined)
+                    continue;
+                const p = opts.patchByFile?.get(f.file);
+                if (p !== undefined) {
+                    const excerpt = p.slice(0, Math.min(MAX_PATCH_EXCERPT, patchBudget));
+                    patches[f.file] = excerpt;
+                    patchBudget -= excerpt.length;
+                }
+            }
+            const state = {
+                findings: capped.map((f) => ({
+                    file: f.file,
+                    line: f.line,
+                    severity: f.severity,
+                    message: f.message,
+                })),
+                patches,
+            };
+            const { answers } = await opts.client.decide({
+                ...(opts.model !== undefined ? { model: opts.model } : {}),
+                state,
+                questions,
+            });
+            capped.forEach((_f, i) => {
+                const a = answers[`f_${i}`];
+                pByIdx[i] = a !== undefined && isNoulAnswer(a) ? a.noul : undefined;
+            });
+        }
+        catch (e) {
+            adjudicationFailed = true;
+            debug('adjudicate', `decision call failed — no suppression: ${describeDecisionError(e)}`);
+        }
+    }
+    const blocking = new Set(opts.blockSeverities ?? []);
+    // Only Jev may attach p — a model-emitted p on an unadjudicated
+    // finding is spoofed confidence, so strip it.
+    const stripP = (f) => {
+        const out = { ...f };
+        delete out.p;
+        return out;
+    };
+    const findings = [];
+    const records = [];
+    capped.forEach((f, i) => {
+        const p = pByIdx[i];
+        const adjudicated = p !== undefined && !adjudicationFailed;
+        const suppress = adjudicated &&
+            SUPPRESSIBLE.has(f.severity) &&
+            !blocking.has(f.severity) &&
+            p !== undefined &&
+            p < 1 - opts.threshold;
+        records.push({
+            file: f.file,
+            ...(f.line !== undefined ? { line: f.line } : {}),
+            severity: f.severity,
+            ...(f.category !== undefined ? { category: f.category } : {}),
+            message: f.message.slice(0, MAX_RECORD_MESSAGE),
+            adjudicated,
+            ...(p !== undefined ? { p } : {}),
+            ...(suppress ? { suppressed: true } : {}),
+        });
+        if (!suppress) {
+            findings.push(p !== undefined ? { ...stripP(f), p } : stripP(f));
+        }
+    });
+    // Overflow findings keep their place — never adjudicated, never
+    // suppressed; count-only in the audit record like the secrets lane.
+    for (const f of opts.findings.slice(MAX_CANDIDATES))
+        findings.push(stripP(f));
+    return {
+        findings,
+        records,
+        overflow,
+        ...(adjudicationFailed ? { unadjudicated: true } : {}),
+    };
+}

package/dist/review/secrets.d.ts

@@ -0,0 +1,88 @@
+import { type ExecFn } from '../detect.js';
+import { DecisionClient } from '../vision/decisions.js';
+/**
+ * Deterministic secrets scan over the PR's local merge-base diff,
+ * optionally adjudicated by the Decisions API (Jev). The lane is
+ * additive-only: findings are unioned into the review AFTER model
+ * synthesis so a prompt-injected synthesis can never erase them, and a
+ * Jev outage degrades to regex-only findings rather than silence.
+ *
+ * Masking contract: raw literals transit to Jev inside `state` (KTD9 —
+ * adjudication needs the shape, and the full diff already crosses to
+ * OpenRouter in the review call) and appear NOWHERE else — not in
+ * findings, comments, the report, or logs.
+ */
+export interface SecretCandidate {
+    file: string;
+    /** Line number in the post-change file. */
+    line: number;
+    patternClass: string;
+    /** Diff line text with every occurrence of the literal replaced by `***`. */
+    contextExcerpt: string;
+    /** Raw literal — Jev `state` only, never emitted. */
+    literal: string;
+    /** Full raw added-line text — Jev `state` only, never emitted. */
+    rawText: string;
+}
+export interface SecretScanRecord {
+    file: string;
+    line: number;
+    patternClass: string;
+    /** True when Jev answered for this candidate. */
+    adjudicated: boolean;
+    pLive?: number;
+    /** Jev scored below threshold — recorded for audit, not a finding. */
+    suppressed?: boolean;
+}
+export interface SecretsScanResult {
+    /** Findings to union into the review — messages are fully masked. */
+    findings: {
+        file: string;
+        line?: number;
+        severity: string;
+        category?: string;
+        message: string;
+    }[];
+    /** Audit records for report.secretsScan — literals never included. */
+    records: SecretScanRecord[];
+    /** Candidates past MAX_CANDIDATES — reported count-only, never sent to Jev. */
+    overflow: number;
+    /** Why the lane produced nothing (e.g. base unfetchable). */
+    skipped?: string;
+}
+export { MAX_CANDIDATES } from '../vision/decisions.js';
+export declare const DEFAULT_SECRETS_THRESHOLD = 0.3;
+/**
+ * Parse `git diff` text into secret candidates from added (`+`) lines.
+ * Removed/context lines are not scanned — a rotated-out-but-live secret
+ * in a `-` line is a deliberate open question (plan OQ), and context
+ * lines would re-flag pre-existing secrets the PR did not introduce.
+ */
+export declare function scanDiffForSecrets(diffText: string): SecretCandidate[];
+/**
+ * Materialize the merge-base diff locally — the PR-files API `patch`
+ * field omits large/binary files, so the API diff is not a complete
+ * scan surface.
+ */
+export declare function materializeMergeBaseDiff(opts: {
+    cwd: string;
+    baseSha: string;
+    token?: string;
+    exec?: ExecFn;
+}): Promise<{
+    diff: string;
+} | {
+    skipped: string;
+}>;
+/**
+ * Full lane: scan candidates (capped), Jev-adjudicate when a client and
+ * threshold are available, and emit masked findings + audit records.
+ * `client === undefined` (decisionModel unset) or any DecisionError →
+ * every candidate unadjudicated — regex-only mode, never silence.
+ */
+export declare function scanSecrets(opts: {
+    diff: string;
+    threshold?: number;
+    client?: DecisionClient;
+    model?: string;
+}): Promise<SecretsScanResult>;

package/dist/review/secrets.js

@@ -0,0 +1,220 @@
+import { defaultExec } from '../detect.js';
+import { debug } from '../debug.js';
+import { describeDecisionError, isNoulAnswer, MAX_CANDIDATES, } from '../vision/decisions.js';
+// Owned by vision/decisions.ts — re-exported here so existing import
+// paths (tests, lanes) keep resolving.
+export { MAX_CANDIDATES } from '../vision/decisions.js';
+export const DEFAULT_SECRETS_THRESHOLD = 0.3;
+const PATTERNS = [
+    {
+        cls: 'private-key',
+        re: /-----BEGIN (?:RSA |EC |OPENSSH |PGP |DSA )?PRIVATE KEY(?: BLOCK)?-----/,
+    },
+    { cls: 'aws-access-key', re: /\bAKIA[0-9A-Z]{16}\b/ },
+    { cls: 'stripe-live', re: /\b(?:sk|rk)_live_[0-9a-zA-Z]{16,}\b/ },
+    { cls: 'stripe-webhook-secret', re: /\bwhsec_[0-9a-zA-Z]{16,}\b/ },
+    { cls: 'github-pat', re: /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{22,})\b/ },
+    { cls: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+    {
+        cls: 'jwt',
+        re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}\b/,
+    },
+    {
+        cls: 'generic-assignment',
+        re: /(?:api[_-]?key|token|secret|passwd|password)\s*[:=]\s*['"]?([A-Za-z0-9/+_.=-]{12,})/i,
+        group: 1,
+    },
+];
+/**
+ * Parse `git diff` text into secret candidates from added (`+`) lines.
+ * Removed/context lines are not scanned — a rotated-out-but-live secret
+ * in a `-` line is a deliberate open question (plan OQ), and context
+ * lines would re-flag pre-existing secrets the PR did not introduce.
+ */
+export function scanDiffForSecrets(diffText) {
+    const out = [];
+    let file = '';
+    let newLine = 0;
+    // `+++ `/`--- ` are file headers only in the pre-hunk zone — inside a
+    // hunk they are added/removed content lines (`+` + `++ x`, `-` + `-- x`)
+    // and must not reset `file` or `inHunk`.
+    let inHunk = false;
+    for (const raw of diffText.split('\n')) {
+        if (raw.startsWith('diff --git')) {
+            inHunk = false;
+            continue;
+        }
+        if (raw.startsWith('@@')) {
+            inHunk = true;
+            const m = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);
+            newLine = m !== null ? parseInt(m[1], 10) : 0;
+            continue;
+        }
+        if (!inHunk) {
+            if (raw.startsWith('+++ ')) {
+                const m = /^\+\+\+ b\/(.+)$/.exec(raw);
+                file = m?.[1] ?? '';
+            }
+            continue;
+        }
+        // Context lines consume a new-file line number; `-` lines don't.
+        if (raw.startsWith(' ')) {
+            newLine++;
+            continue;
+        }
+        if (!raw.startsWith('+') || file === '')
+            continue;
+        const text = raw.slice(1);
+        for (const { cls, re, group } of PATTERNS) {
+            const m = re.exec(text);
+            if (m === null)
+                continue;
+            const literal = group !== undefined ? (m[group] ?? m[0]) : m[0];
+            out.push({
+                file,
+                line: newLine,
+                patternClass: cls,
+                contextExcerpt: text.replaceAll(literal, '***'),
+                literal,
+                rawText: text,
+            });
+            break; // first matching class wins — one candidate per line
+        }
+        newLine++;
+    }
+    return out;
+}
+function maskFindingMessage(c, adjudicated) {
+    const verdict = adjudicated
+        ? 'live-looking credential'
+        : 'secret-shaped literal (unadjudicated — decision model unavailable)';
+    return (`L${c.line}: ${adjudicated ? '🔴' : '🟡'} ${adjudicated ? 'bug' : 'risk'}: ` +
+        `${verdict} (${c.patternClass}) added in this PR at \`${c.file}\`. ` +
+        `Rotate it and purge it from history.`);
+}
+/** `git cat-file -e` + shallow-fetch fallback — mirrors probe/queue.ts. */
+async function ensureBaseObject(exec, cwd, baseSha, token) {
+    const have = await exec('git', ['-C', cwd, 'cat-file', '-e', `${baseSha}^{commit}`], 15_000);
+    if (have.code === 0)
+        return true;
+    if (token === undefined)
+        return false;
+    // Auth rides env config like actions/checkout's extraheader — keeps the
+    // token out of process argv where co-tenant jobs could scrape /proc.
+    const fetched = await exec('git', ['-C', cwd, 'fetch', '--depth', '1', 'origin', baseSha], 60_000, {
+        GIT_CONFIG_COUNT: '1',
+        GIT_CONFIG_KEY_0: 'http.https://github.com/.extraheader',
+        GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${Buffer.from(`x-access-token:${token}`).toString('base64')}`,
+    });
+    return fetched.code === 0;
+}
+/**
+ * Materialize the merge-base diff locally — the PR-files API `patch`
+ * field omits large/binary files, so the API diff is not a complete
+ * scan surface.
+ */
+export async function materializeMergeBaseDiff(opts) {
+    const exec = opts.exec ?? defaultExec;
+    const have = await ensureBaseObject(exec, opts.cwd, opts.baseSha, opts.token);
+    if (!have) {
+        return { skipped: `base ${opts.baseSha.slice(0, 12)} not available locally and unfetchable` };
+    }
+    // core.quotePath=false — the default C-escapes non-ASCII/odd-byte paths
+    // ("b/\"f\\303\\251e.ts\""), mangling `file` in findings.
+    const diff = await exec('git', ['-c', 'core.quotePath=false', '-C', opts.cwd, 'diff', `${opts.baseSha}..HEAD`], 60_000);
+    if (diff.code !== 0) {
+        return { skipped: `git diff failed: ${diff.stderr.trim().slice(0, 200)}` };
+    }
+    return { diff: diff.stdout };
+}
+/**
+ * Full lane: scan candidates (capped), Jev-adjudicate when a client and
+ * threshold are available, and emit masked findings + audit records.
+ * `client === undefined` (decisionModel unset) or any DecisionError →
+ * every candidate unadjudicated — regex-only mode, never silence.
+ */
+export async function scanSecrets(opts) {
+    const threshold = opts.threshold ?? DEFAULT_SECRETS_THRESHOLD;
+    const all = scanDiffForSecrets(opts.diff);
+    const candidates = all.slice(0, MAX_CANDIDATES);
+    const overflow = all.length - candidates.length;
+    const pLiveByIdx = new Array(candidates.length);
+    let adjudicationFailed = false;
+    if (opts.client !== undefined && candidates.length > 0) {
+        try {
+            const questions = {};
+            candidates.forEach((c, i) => {
+                questions[`cand_${i}`] = {
+                    type: 'noul',
+                    instructions: `state[${i}]: is 'literal' a real, usable credential committed to source? ` +
+                        'Answer no for documentation examples, placeholders, test fixtures, ' +
+                        'and revoked or sample values.',
+                };
+            });
+            const state = candidates.map((c) => ({
+                file: c.file,
+                line: c.line,
+                lineText: c.rawText,
+                literal: c.literal,
+            }));
+            const { answers } = await opts.client.decide({
+                ...(opts.model !== undefined ? { model: opts.model } : {}),
+                state,
+                questions,
+            });
+            candidates.forEach((_c, i) => {
+                const a = answers[`cand_${i}`];
+                pLiveByIdx[i] = a !== undefined && isNoulAnswer(a) ? a.noul : undefined;
+            });
+        }
+        catch (e) {
+            adjudicationFailed = true;
+            debug('secrets', `adjudication failed — degrading to regex-only: ${describeDecisionError(e)}`);
+        }
+    }
+    const findings = [];
+    const records = [];
+    candidates.forEach((c, i) => {
+        const pLive = pLiveByIdx[i];
+        const adjudicated = pLive !== undefined && !adjudicationFailed;
+        if (adjudicated && pLive !== undefined && pLive < threshold) {
+            records.push({
+                file: c.file,
+                line: c.line,
+                patternClass: c.patternClass,
+                adjudicated: true,
+                pLive,
+                suppressed: true,
+            });
+            return;
+        }
+        findings.push({
+            file: c.file,
+            line: c.line,
+            severity: adjudicated ? 'bug' : 'risk',
+            category: 'security',
+            message: maskFindingMessage(c, adjudicated),
+        });
+        records.push({
+            file: c.file,
+            line: c.line,
+            patternClass: c.patternClass,
+            adjudicated,
+            ...(pLive !== undefined ? { pLive } : {}),
+        });
+    });
+    // Candidates past the cap were never adjudicated — a real secret could
+    // sit in the overflow. Surface that gap as a finding, not just a count.
+    if (overflow > 0) {
+        findings.push({
+            file: '-',
+            line: 0,
+            severity: 'risk',
+            category: 'security',
+            message: `L0: 🟡 risk: ${overflow} secret-shaped literal(s) exceeded the ` +
+                `${MAX_CANDIDATES}-candidate adjudication cap and were not evaluated — ` +
+                'review the diff for secrets manually.',
+        });
+    }
+    return { findings, records, overflow };
+}

package/dist/review/triage.d.ts

@@ -0,0 +1,76 @@
+import { type DecisionClient } from '../vision/decisions.js';
+declare const RISK_AREA_CRITERIA: {
+    readonly auth: "authentication, authorization, tokens, sessions, permissions";
+    readonly billing: "payments, invoices, usage metering, cost accounting";
+    readonly data: "persistence, migrations, integrity, serialization, caching";
+    readonly ops: "CI, deploy, infra, configuration, tooling, observability";
+    readonly none: "no meaningful risk area in this diff";
+};
+export declare const TRIAGE_AREAS: TriageArea[];
+export type TriageArea = keyof typeof RISK_AREA_CRITERIA;
+export interface TriageRecord {
+    mode: 'annotate' | 'route';
+    /** noul 0–1 — does this PR warrant careful review. */
+    needsDeepReview?: number;
+    /** score 1–5 blast-radius rubric. */
+    risk?: number;
+    topRiskArea?: TriageArea;
+    /** Choice-answer confidence when the API provides one. */
+    topRiskAreaConfidence?: number;
+    /** Chars of diff evidence Jev saw — route mode won't downgrade on 0. */
+    diffExcerptChars?: number;
+    /** decide() failed or answers failed validation — degrade-open marker. */
+    unadjudicated?: boolean;
+    /** Decision model that produced (or attempted) the record. */
+    model: string;
+}
+export interface TriageState {
+    title: string;
+    body: string;
+    files: string[];
+    totalFiles: number;
+    diffExcerpt: string;
+}
+export declare function buildTriageState(opts: {
+    title?: string | undefined;
+    body?: string | undefined;
+    files: {
+        filename: string;
+        patch?: string;
+    }[];
+}): TriageState;
+export declare function triagePr(opts: {
+    client: DecisionClient;
+    model?: string;
+    state: TriageState;
+    mode: 'annotate' | 'route';
+}): Promise<TriageRecord>;
+/**
+ * 'route' mode model selection — cheap tier only on a clear low-risk
+ * signal (risk ≤ 2 AND deep-review < 0.5) backed by actual diff
+ * evidence. Any ambiguity (missing fields, unadjudicated, unset
+ * lowRiskModel, or a title/body-only triage — fully attacker-steerable
+ * text) keeps the configured model: coverage stays constant and the
+ * expensive path is the default.
+ */
+export declare function routeModel(opts: {
+    record: TriageRecord | undefined;
+    configured: string;
+    lowRiskModel: string | undefined;
+}): {
+    model: string;
+    reason: string;
+};
+/** U9 ordering signal consumed by the probe lane. */
+export interface TriageAreaSignal {
+    area: TriageArea;
+    confidence: number;
+}
+/**
+ * U9 — the probe lane's advisory ordering signal. Present only when
+ * triage adjudicated a real area with its confidence attached; 'none'
+ * is the null-area sentinel, not an ordering signal, and the
+ * confidence floor itself is queue policy (MIN_AREA_CONFIDENCE).
+ */
+export declare function triageAreaSignal(rec: TriageRecord | undefined): TriageAreaSignal | undefined;
+export {};