@gobing-ai/spur 0.3.95 → 0.3.96

package/plugins/sp/lib/quality-gate.generated.d.mts

@@ -0,0 +1,104 @@
+/**
+ * GENERATED by scripts/commands/bundle-plugin-lib.ts — do not edit.
+ * Source of truth: packages/app/src/services/quality-gate.ts (task 1006 R1).
+ */
+export declare const MAX_GATE_ATTEMPTS: number;
+export declare const MAX_FINDINGS: number;
+export declare const RETRY_DELAY_MS_DEFAULT: number;
+export declare const RETRY_DELAY_MS_ENV: string;
+export declare const LOCKED_PATTERN: RegExp;
+export declare const FINDINGS_PATTERN: RegExp;
+export declare const COVERAGE_ROW_PATTERN: RegExp;
+export declare const RECEIPT_SCHEMA_VERSION: 'check-receipt/v1';
+export declare interface QualityGateEnv {
+    wbs: string;
+    qualityGateCmd?: string;
+    gateProbeCmd?: string;
+    proofDigest?: string;
+    runId?: string;
+    [key: string]: string | undefined;
+}
+export declare interface QualityGateOptions {
+    cwd?: string;
+}
+export declare interface QualityGateResult {
+    status: 'PASS' | 'FAIL';
+    attempts: number;
+    logFile: string;
+    findingsFile: string;
+    statusFile: string;
+    attemptFile: string;
+    receiptFile?: string;
+}
+export declare function isTransientLock(attemptOutput: string): boolean;
+export declare function extractFindings(logText: string): string;
+export declare function tailLines(text: string, count: number): string;
+export declare function retryMessage(attempt: number): string;
+export declare interface CoverageThreshold {
+    functions?: number;
+    lines?: number;
+}
+export declare function parseCoverageThreshold(bunfigText: string): CoverageThreshold | null;
+export declare function scanCoverageShortfalls(logText: string, threshold: CoverageThreshold): string[];
+export declare type ReceiptTier = 'full' | 'light';
+export declare type CheckStatus = 'PASS' | 'FAIL';
+export declare type ReceiptReuseReason = 'missing' | 'failed' | 'stale' | 'light-only';
+export declare interface CheckReceiptRow {
+    id: string;
+    cmd: string;
+    status: CheckStatus;
+    durationMs: number;
+    logPath: string;
+}
+export declare interface CheckReceipt {
+    schemaVersion: 'check-receipt/v1';
+    wbs: string;
+    runId: string;
+    tier: ReceiptTier;
+    inputDigest: string;
+    checks: CheckReceiptRow[];
+    status: CheckStatus;
+    completedAt: string;
+}
+export declare interface ReceiptReadStatus {
+    reuse: boolean;
+    reason: ReceiptReuseReason | 'ok';
+}
+export declare interface BuildReceiptInput {
+    wbs: string;
+    runId: string;
+    tier: ReceiptTier;
+    inputDigest: string;
+    checks: CheckReceiptRow[];
+    completedAt: string;
+}
+export declare function buildReceipt(input: BuildReceiptInput): CheckReceipt;
+export declare function receiptFailsAtDigest(receipt: CheckReceipt | null, currentDigest: string): boolean;
+export declare function readReceiptStatus(receiptPath: string, currentDigest: string): ReceiptReadStatus;
+export declare interface LightScope {
+    files: string[];
+    workspaces: string[];
+    tests: string[];
+}
+export declare function lightScope(changedFiles: string[], exists?: (p: string) => boolean): LightScope;
+export declare function shQuote(arg: string): string;
+export declare interface LightCheckPlan {
+    id: string;
+    cmd: string;
+}
+export declare function workspaceHasTypecheck(workspace: string): boolean;
+export declare function planLightChecks(scope: LightScope, hasTypecheck?: (workspace: string) => boolean): LightCheckPlan[];
+export declare interface LightGateResult {
+    status: CheckStatus;
+    scope: LightScope;
+    checks: CheckReceiptRow[];
+    logFile: string;
+    receiptFile: string;
+}
+export declare function runLightGate(env: QualityGateEnv, options?: QualityGateOptions): LightGateResult;
+export declare function runShellCommand(cmd: string, cwd: string | undefined): { output: string; code: number };
+export declare function runQualityGate(
+    mode: 'run' | 'recheck',
+    env: QualityGateEnv,
+    options?: QualityGateOptions,
+): QualityGateResult;

package/plugins/sp/lib/quality-gate.generated.mjs

@@ -0,0 +1,438 @@
+// packages/app/src/services/quality-gate.ts
+import { spawnSync } from "node:child_process";
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+var MAX_GATE_ATTEMPTS = 5;
+var MAX_FINDINGS = 20;
+var RETRY_DELAY_MS_DEFAULT = 1e4;
+var RETRY_DELAY_MS_ENV = "SPUR_QUALITY_GATE_RETRY_DELAY_MS";
+var LOCKED_PATTERN = /SQLiteError: database is locked|SQLite database .*is busy|SQLITE_BUSY/;
+var FINDINGS_PATTERN = /[A-Za-z0-9_./-]+\.[A-Za-z]+:[0-9]+/g;
+var COVERAGE_ROW_PATTERN = /^\s*(\S+\.[A-Za-z]+)\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|\s*(\S*)/;
+function isTransientLock(attemptOutput) {
+  return LOCKED_PATTERN.test(attemptOutput);
+}
+function extractFindings(logText) {
+  const found = new Set;
+  for (const match of logText.matchAll(FINDINGS_PATTERN))
+    found.add(match[0]);
+  return [...found].sort().slice(0, MAX_FINDINGS).map((anchor) => `${anchor} `).join("");
+}
+function tailLines(text, count) {
+  const lines = text.split(`
+`);
+  if (lines.length > 0 && lines[lines.length - 1] === "")
+    lines.pop();
+  const tail = lines.slice(Math.max(0, lines.length - count));
+  return tail.length === 0 ? "" : `${tail.join(`
+`)}
+`;
+}
+function retryMessage(attempt) {
+  return `quality gate: database is locked; retrying (${attempt}/${MAX_GATE_ATTEMPTS}) in 10s
+`;
+}
+function parseCoverageThreshold(bunfigText) {
+  const block = bunfigText.match(/coverageThreshold\s*=\s*\{([^}]*)\}/);
+  if (!block)
+    return null;
+  const threshold = {};
+  for (const axis of ["functions", "lines"]) {
+    const raw = block[1]?.match(new RegExp(`\\b${axis}\\s*=\\s*([\\d.]+)`))?.[1];
+    const value = raw === undefined ? Number.NaN : Number.parseFloat(raw);
+    if (Number.isFinite(value))
+      threshold[axis] = value;
+  }
+  return threshold.functions === undefined && threshold.lines === undefined ? null : threshold;
+}
+function scanCoverageShortfalls(logText, threshold) {
+  const shortfalls = new Map;
+  for (const line of logText.split(`
+`)) {
+    const row = line.match(COVERAGE_ROW_PATTERN);
+    if (!row)
+      continue;
+    const [, path, funcs, lines, uncovered] = row;
+    if (!path || path === "All files" || shortfalls.has(path))
+      continue;
+    const belowFunctions = threshold.functions !== undefined && Number.parseFloat(funcs ?? "") < threshold.functions * 100;
+    const belowLines = threshold.lines !== undefined && Number.parseFloat(lines ?? "") < threshold.lines * 100;
+    if (!belowFunctions && !belowLines)
+      continue;
+    const firstUncovered = uncovered?.match(/\d+/)?.[0] ?? "1";
+    shortfalls.set(path, `quality gate: coverage shortfall ${path}:${firstUncovered} funcs=${funcs} lines=${lines}`);
+  }
+  return [...shortfalls.values()];
+}
+var RECEIPT_SCHEMA_VERSION = "check-receipt/v1";
+function buildReceipt(input) {
+  return {
+    schemaVersion: RECEIPT_SCHEMA_VERSION,
+    wbs: input.wbs,
+    runId: input.runId,
+    tier: input.tier,
+    inputDigest: input.inputDigest,
+    checks: input.checks,
+    status: input.checks.every((row) => row.status === "PASS") ? "PASS" : "FAIL",
+    completedAt: input.completedAt
+  };
+}
+function readReceipt(receiptPath) {
+  try {
+    return JSON.parse(readFileSync(receiptPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function receiptFailsAtDigest(receipt, currentDigest) {
+  return receipt !== null && receipt.schemaVersion === RECEIPT_SCHEMA_VERSION && receipt.tier === "full" && receipt.status === "FAIL" && currentDigest.length > 0 && receipt.inputDigest === currentDigest;
+}
+function readReceiptStatus(receiptPath, currentDigest) {
+  const receipt = readReceipt(receiptPath);
+  if (receipt === null || receipt.schemaVersion !== RECEIPT_SCHEMA_VERSION) {
+    return { reuse: false, reason: "missing" };
+  }
+  if (receipt.status !== "PASS")
+    return { reuse: false, reason: "failed" };
+  if (currentDigest.length === 0 || receipt.inputDigest !== currentDigest) {
+    return { reuse: false, reason: "stale" };
+  }
+  if (receipt.tier !== "full")
+    return { reuse: false, reason: "light-only" };
+  return { reuse: true, reason: "ok" };
+}
+var TEST_FILE_PATTERN = /\.test\.tsx?$/;
+function workspaceOf(file, exists) {
+  const segments = file.split("/");
+  for (let depth = 1;depth < segments.length; depth++) {
+    const prefix = segments.slice(0, depth).join("/");
+    if (exists(`${prefix}/package.json`))
+      return prefix;
+  }
+  return null;
+}
+function lightScope(changedFiles, exists = existsSync) {
+  const files = [];
+  const workspaces = new Set;
+  const tests = new Set;
+  for (const file of changedFiles) {
+    files.push(file);
+    const workspace = workspaceOf(file, exists);
+    if (workspace === null)
+      continue;
+    workspaces.add(workspace);
+    const rest = file.slice(workspace.length + 1);
+    if (rest.startsWith("src/")) {
+      const candidate = `${workspace}/tests/${rest.slice("src/".length).replace(/\.tsx?$/, (ext) => `.test${ext}`)}`;
+      if (exists(candidate))
+        tests.add(candidate);
+    } else if (rest.startsWith("tests/") && TEST_FILE_PATTERN.test(rest)) {
+      tests.add(file);
+    }
+  }
+  return { files, workspaces: [...workspaces].sort(), tests: [...tests].sort() };
+}
+function shQuote(arg) {
+  return /^[\w./@+-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+function workspaceHasTypecheck(workspace) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(workspace, "package.json"), "utf8"));
+    return typeof pkg.scripts?.typecheck === "string";
+  } catch {
+    return false;
+  }
+}
+function planLightChecks(scope, hasTypecheck = workspaceHasTypecheck) {
+  const plans = [];
+  if (scope.files.length > 0) {
+    plans.push({ id: "format-lint:changed", cmd: `bunx biome check ${scope.files.map(shQuote).join(" ")}` });
+  }
+  for (const workspace of scope.workspaces) {
+    if (hasTypecheck(workspace)) {
+      plans.push({ id: `typecheck:${workspace}`, cmd: `cd ${shQuote(workspace)} && bun run typecheck` });
+    }
+  }
+  const testsByWorkspace = new Map;
+  for (const test of scope.tests) {
+    const workspace = test.slice(0, test.indexOf("/tests/"));
+    const paths = testsByWorkspace.get(workspace) ?? [];
+    paths.push(test.slice(workspace.length + 1));
+    testsByWorkspace.set(workspace, paths);
+  }
+  for (const [workspace, paths] of testsByWorkspace) {
+    plans.push({
+      id: `test:${workspace}`,
+      cmd: `cd ${shQuote(workspace)} && bun test ${paths.map(shQuote).join(" ")}`
+    });
+  }
+  return plans;
+}
+function gitChangedFiles(cwd) {
+  const abs = (p) => cwd ? join(cwd, p) : p;
+  const changed = new Set;
+  for (const cmd of ["git diff --name-only HEAD", "git ls-files --others --exclude-standard"]) {
+    const result = runShellCommand(cmd, cwd);
+    for (const line of result.output.split(`
+`)) {
+      const file = line.trim();
+      if (file.length > 0 && existsSync(abs(file)))
+        changed.add(file);
+    }
+  }
+  return [...changed].sort();
+}
+function receiptRunId(env) {
+  return (env.runId ?? "").length > 0 ? env.runId : `pipeline-${env.wbs}`;
+}
+function runLightGate(env, options = {}) {
+  const cwd = options.cwd;
+  const abs = (p) => cwd ? join(cwd, p) : p;
+  const runDir = join(".spur", "run");
+  mkdirSync(abs(runDir), { recursive: true });
+  const logFile = join(runDir, `${env.wbs}-light-gate.log`);
+  const receiptFile = join(runDir, `${env.wbs}-check-receipt.json`);
+  writeFileSync(abs(logFile), "");
+  const digest = env.proofDigest ?? "";
+  const scope = lightScope(gitChangedFiles(cwd), (p) => existsSync(abs(p)));
+  const plans = planLightChecks(scope, (workspace) => workspaceHasTypecheck(abs(workspace)));
+  const reusable = new Map;
+  let preserveFullReceipt = false;
+  if (digest.length > 0) {
+    try {
+      const prior = JSON.parse(readFileSync(abs(receiptFile), "utf8"));
+      if (prior?.schemaVersion === RECEIPT_SCHEMA_VERSION && prior.inputDigest === digest) {
+        if (prior.tier === "full") {
+          preserveFullReceipt = true;
+        } else {
+          for (const row of prior.checks ?? [])
+            if (row.status === "PASS")
+              reusable.set(row.id, row);
+        }
+      }
+    } catch {}
+  }
+  const checks = [];
+  let skipped = 0;
+  for (const plan of plans) {
+    const priorRow = reusable.get(plan.id);
+    if (priorRow !== undefined) {
+      checks.push(priorRow);
+      skipped++;
+      const line = `--- light ${plan.id}: check.reused — skipped (PASS at the same input digest)
+`;
+      process.stdout.write(line);
+      appendFileSync(abs(logFile), line);
+      continue;
+    }
+    const startedAtMs = Date.now();
+    const result = runShellCommand(plan.cmd, cwd);
+    const durationMs = Date.now() - startedAtMs;
+    const status = result.code === 0 ? "PASS" : "FAIL";
+    appendFileSync(abs(logFile), `--- light ${plan.id}: ${status} (${durationMs}ms)
+${result.output}`);
+    checks.push({ id: plan.id, cmd: plan.cmd, status, durationMs, logPath: logFile });
+  }
+  const receipt = buildReceipt({
+    wbs: env.wbs,
+    runId: receiptRunId(env),
+    tier: "light",
+    inputDigest: digest,
+    checks,
+    completedAt: new Date().toISOString()
+  });
+  if (preserveFullReceipt) {
+    appendFileSync(abs(logFile), `--- light receipt: not written — the full-tier receipt at the same input digest is preserved
+`);
+    process.stdout.write(`light gate ${receipt.status} (${scope.files.length} changed files; checks: ${checks.length},` + ` skipped: ${skipped}; receipt: ${receiptFile} preserved (full tier); log: ${logFile})
+`);
+  } else {
+    writeFileSync(abs(receiptFile), `${JSON.stringify(receipt, null, 2)}
+`);
+    process.stdout.write(`light gate ${receipt.status} (${scope.files.length} changed files; checks: ${checks.length},` + ` skipped: ${skipped}; receipt: ${receiptFile}; log: ${logFile})
+`);
+  }
+  return { status: receipt.status, scope, checks, logFile, receiptFile };
+}
+function retryDelayMs(env) {
+  const raw = Number.parseInt(env[RETRY_DELAY_MS_ENV] ?? "", 10);
+  return Number.isFinite(raw) && raw >= 0 ? raw : RETRY_DELAY_MS_DEFAULT;
+}
+function gateSleep(ms) {
+  if (ms > 0)
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function runShellCommand(cmd, cwd) {
+  const dir = mkdtempSync(join(tmpdir(), "spur-quality-gate-"));
+  const path = join(dir, "output");
+  const fd = openSync(path, "w");
+  try {
+    const result = spawnSync("sh", ["-c", cmd], { cwd, stdio: ["ignore", fd, fd] });
+    if (result.error !== undefined) {
+      return { output: `sh -c failed: ${result.error.message}
+`, code: 1 };
+    }
+    return { output: readFileSync(path, "utf8"), code: result.status ?? 1 };
+  } finally {
+    closeSync(fd);
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+function runQualityGate(mode, env, options = {}) {
+  const cwd = options.cwd;
+  const runDir = join(".spur", "run");
+  mkdirSync(cwd ? join(cwd, runDir) : runDir, { recursive: true });
+  const rel = (name) => join(runDir, `${env.wbs}${name}`);
+  const logFile = rel("-test-gate.log");
+  const findingsFile = rel("-test-gate.findings");
+  const statusFile = rel("-test-gate.status");
+  const attemptFile = rel("-test-fix-attempt");
+  const abs = (p) => cwd ? join(cwd, p) : p;
+  writeFileSync(abs(logFile), "");
+  if (mode === "run")
+    writeFileSync(abs(attemptFile), `0
+`);
+  const gateStartedAtMs = Date.now();
+  let gateRc = 0;
+  let gateAttempt = 0;
+  const reusePass = readReceiptStatus(abs(rel("-check-receipt.json")), env.proofDigest ?? "").reuse;
+  if (reusePass) {
+    const line = `check.reused — full-tier PASS receipt at input digest ${env.proofDigest ?? ""}; gate skipped
+`;
+    process.stdout.write(line);
+    appendFileSync(abs(logFile), line);
+    writeFileSync(abs(findingsFile), extractFindings(readFileSync(abs(logFile), "utf8")));
+    writeFileSync(abs(statusFile), `PASS
+`);
+    return { status: "PASS", attempts: 0, logFile, findingsFile, statusFile, attemptFile };
+  }
+  const noProgressSkip = mode === "recheck" && receiptFailsAtDigest(readReceipt(abs(rel("-check-receipt.json"))), env.proofDigest ?? "");
+  if (noProgressSkip) {
+    const line = `check.skipped-no-progress — full-tier FAIL receipt at input digest ${env.proofDigest ?? ""}; recheck skipped
+`;
+    process.stdout.write(line);
+    appendFileSync(abs(logFile), line);
+    gateRc = 1;
+  }
+  if (mode === "recheck" && !noProgressSkip && (env.gateProbeCmd ?? "").length > 0) {
+    const probe = runShellCommand(env.gateProbeCmd ?? "", cwd);
+    writeFileSync(abs(`${logFile}.probe`), probe.output);
+    gateRc = probe.code;
+    appendFileSync(abs(logFile), probe.output);
+    rmSync(abs(`${logFile}.probe`), { force: true });
+  }
+  if (gateRc === 0) {
+    const delayMs = retryDelayMs(env);
+    for (gateAttempt = 1;gateAttempt <= MAX_GATE_ATTEMPTS; gateAttempt++) {
+      const attemptLogPath = `${logFile}.attempt-${gateAttempt}`;
+      const attempt = runShellCommand(env.qualityGateCmd ?? "", cwd);
+      writeFileSync(abs(attemptLogPath), attempt.output);
+      const locked = isTransientLock(attempt.output);
+      appendFileSync(abs(logFile), attempt.output);
+      rmSync(abs(attemptLogPath), { force: true });
+      gateRc = attempt.code;
+      if (gateRc === 0 || !locked || gateAttempt >= MAX_GATE_ATTEMPTS)
+        break;
+      const line = retryMessage(gateAttempt);
+      process.stdout.write(line);
+      appendFileSync(abs(logFile), line);
+      gateSleep(delayMs);
+    }
+  }
+  if (gateRc !== 0) {
+    const gateLog = existsSync(abs(logFile)) ? readFileSync(abs(logFile), "utf8") : "";
+    if (/^\s*0 fail\b/m.test(gateLog) && !/^\s*[1-9]\d*\s+fail\b/m.test(gateLog)) {
+      const bunfigPath = cwd ? join(cwd, "bunfig.toml") : "bunfig.toml";
+      const threshold = existsSync(bunfigPath) ? parseCoverageThreshold(readFileSync(bunfigPath, "utf8")) : null;
+      if (threshold) {
+        for (const shortfall of scanCoverageShortfalls(gateLog, threshold)) {
+          process.stdout.write(`${shortfall}
+`);
+          appendFileSync(abs(logFile), `${shortfall}
+`);
+        }
+      }
+    }
+  }
+  if (gateRc === 0) {
+    const bytes = existsSync(abs(logFile)) ? statSync(abs(logFile)).size : 0;
+    const attemptsLabel = gateAttempt > 0 ? String(gateAttempt) : "";
+    process.stdout.write(`quality gate PASS (attempts: ${attemptsLabel}; log: ${logFile}; bytes: ${bytes})
+`);
+  } else {
+    process.stdout.write(`quality gate FAIL — last 40 lines follow (full log: ${logFile})
+`);
+    process.stdout.write(tailLines(readFileSync(abs(logFile), "utf8"), 40));
+  }
+  writeFileSync(abs(findingsFile), extractFindings(readFileSync(abs(logFile), "utf8")));
+  const status = gateRc === 0 ? "PASS" : "FAIL";
+  writeFileSync(abs(statusFile), `${status}
+`);
+  appendFileSync(abs(logFile), `proof-digest: ${env.proofDigest ?? ""}
+`);
+  let receiptFile;
+  if (!noProgressSkip) {
+    if ((env.proofDigest ?? "").length > 0) {
+      receiptFile = join(runDir, `${env.wbs}-check-receipt.json`);
+      const receipt = buildReceipt({
+        wbs: env.wbs,
+        runId: receiptRunId(env),
+        tier: "full",
+        inputDigest: env.proofDigest ?? "",
+        checks: [
+          {
+            id: "test",
+            cmd: env.qualityGateCmd ?? "",
+            status,
+            durationMs: Date.now() - gateStartedAtMs,
+            logPath: logFile
+          }
+        ],
+        completedAt: new Date().toISOString()
+      });
+      writeFileSync(abs(receiptFile), `${JSON.stringify(receipt, null, 2)}
+`);
+    } else {
+      appendFileSync(abs(logFile), "check-receipt: not written — env `proofDigest` is not set\n");
+    }
+  }
+  return { status, attempts: gateAttempt, logFile, findingsFile, statusFile, attemptFile, receiptFile };
+}
+export {
+  workspaceHasTypecheck,
+  tailLines,
+  shQuote,
+  scanCoverageShortfalls,
+  runShellCommand,
+  runQualityGate,
+  runLightGate,
+  retryMessage,
+  receiptFailsAtDigest,
+  readReceiptStatus,
+  planLightChecks,
+  parseCoverageThreshold,
+  lightScope,
+  isTransientLock,
+  extractFindings,
+  buildReceipt,
+  RETRY_DELAY_MS_ENV,
+  RETRY_DELAY_MS_DEFAULT,
+  RECEIPT_SCHEMA_VERSION,
+  MAX_GATE_ATTEMPTS,
+  MAX_FINDINGS,
+  LOCKED_PATTERN,
+  FINDINGS_PATTERN,
+  COVERAGE_ROW_PATTERN
+};

package/plugins/sp/lib/residual-scan.generated.d.mts

@@ -0,0 +1,62 @@
+/**
+ * GENERATED by scripts/commands/bundle-plugin-lib.ts — do not edit.
+ * Source of truth: packages/app/src/services/residual-scan.ts (task 1003 R5).
+ */
+export declare type ResidualCategory = 'review-finding' | 'diff-marker' | 'unchecked-box' | 'staging-residue';
+export declare type ResidualClass = 'blocking' | 'deferrable' | 'advisory' | 'housekeeping';
+export declare interface ResidualItem {
+    id: string;
+    category: ResidualCategory;
+    class: ResidualClass;
+    priority?: string;
+    location: string;
+    text: string;
+}
+export declare interface ResidualArtifact {
+    wbs: string;
+    base: string | null;
+    scanned: Record<ResidualCategory, boolean>;
+    items: ResidualItem[];
+    counts: { blocking: number; deferrable: number; advisory: number; housekeeping: number };
+}
+export declare interface Deferral {
+    id: string;
+    reason: string;
+}
+export declare interface ResidualScanInputs {
+    wbs: string;
+    base: string | null;
+    taskContent: string;
+    addedLines: Array<{ file: string; line: number; text: string }>;
+    stagingResidue: string[];
+    deferrals: Deferral[];
+}
+export declare interface FoldResult {
+    verdict: 'PASS' | 'PARTIAL' | 'FAIL';
+    checks: Array<{ name: string; status: string; evidence: string }>;
+    findings: string;
+}
+export declare const ALLOW_PRAGMA: 'residual-scan:allow';
+export declare function makeItemId(category: ResidualCategory, location: string, text: string): string;
+export declare function normalizeAnchor(location: string): string;
+export declare function locationOf(locationCell: string, finding: string): string;
+export declare function parseReviewFindings(
+    taskContent: string,
+): Array<{ priority: string; location: string; text: string; deferral?: string }>;
+export declare function parseDiffMarkers(
+    addedLines: Array<{ file: string; line: number; text: string }>,
+): Array<{ location: string; text: string }>;
+export declare function findUncheckedBoxes(taskContent: string): Array<{ location: string; text: string }>;
+export declare function classify(
+    items: Array<Omit<ResidualItem, 'id' | 'class'> & { category: ResidualCategory }>,
+    deferrals: Deferral[],
+): ResidualItem[];
+export declare function scanResiduals(inputs: ResidualScanInputs): ResidualArtifact;
+export declare function blockingAnchors(items: ResidualItem[]): string[];
+export declare function foldVerdict(
+    verdict: { verdict: string; checks: Array<{ name: string; status: string; evidence: string }> },
+    scan: ResidualArtifact,
+    existingFindings: string,
+    maxFindings?: number,
+): FoldResult;
+export declare function renderReport(wbs: string, items: ResidualItem[], attemptCount: number): string;