@prodcycle/prodcycle 0.4.2 → 0.6.0

package/dist/cli.js

@@ -34,7 +34,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCiEnvironment = isCiEnvironment;
 const commander_1 = require("commander");
+const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const index_1 = require("./index");
@@ -43,6 +45,7 @@ const sarif_1 = require("./formatters/sarif");
 const prompt_1 = require("./formatters/prompt");
 const KNOWN_COMMANDS = new Set([
     'scan',
+    'scans',
     'gate',
     'hook',
     'init',
@@ -110,36 +113,116 @@ program
     .name('prodcycle')
     .description('Multi-framework policy-as-code compliance scanner for infrastructure and application code.')
     .version(PKG_VERSION);
+/**
+ * Detect CI environment via well-known env vars set by the major
+ * platforms. When CI is detected, default `--format` flips to `sarif`
+ * (so output drops straight into GitHub code scanning / GitLab security
+ * dashboards / etc. without extra configuration). Users can still
+ * override with `--format table|json|prompt`.
+ *
+ * The flip is opt-out (set `--format table` explicitly to keep the
+ * human-readable output in CI logs). Heuristic, not load-bearing — if
+ * we miss a CI platform here the user gets the same default they
+ * would have anyway (`table`), they just have to add `--format sarif`
+ * by hand.
+ */
+function isCiEnvironment(env = process.env) {
+    // Generic `CI`: match any non-empty value. Most platforms set `CI=true`
+    // but some (Drone CI, Woodpecker CI, custom Jenkins pipelines) use
+    // `CI=1` or another truthy string. Specific platforms below cover the
+    // happy path; this is a defense-in-depth fallback so we don't miss
+    // edge-case environments.
+    return ((env['CI'] != null && env['CI'] !== '') ||
+        env['GITHUB_ACTIONS'] === 'true' ||
+        env['GITLAB_CI'] === 'true' ||
+        env['CIRCLECI'] === 'true' ||
+        env['JENKINS_URL'] != null ||
+        env['BUILDKITE'] === 'true' ||
+        env['TRAVIS'] === 'true' ||
+        env['BITBUCKET_BUILD_NUMBER'] != null);
+}
 // ── scan ────────────────────────────────────────────────────────────────────
 program
     .command('scan [repo_path]')
     .description('Scan a repository for compliance violations')
-    .option('--framework <ids>', 'Comma-separated framework IDs to evaluate', 'soc2')
-    .option('--format <format>', 'Output format: json, sarif, table, prompt', 'table')
-    .option('--severity-threshold <severity>', 'Minimum severity to include in report', 'low')
+    // Default frameworks: all three. The unique value of this scanner is
+    // cross-framework evaluation in one pass; defaulting to `soc2` only
+    // hid the HIPAA + NIST CSF capability from users who never thought
+    // to override the flag. If users need only one framework they can
+    // still pass `--framework soc2` explicitly.
+    .option('--framework <ids>', 'Comma-separated framework IDs to evaluate', 'soc2,hipaa,nist-csf')
+    // Default format: `table` for interactive use, but auto-flipped to
+    // `sarif` when CI is detected (see isCiEnvironment above) so GitHub
+    // Code Scanning / GitLab dashboards pick the report up without any
+    // extra wiring. The CLI's --format flag overrides the auto-flip.
+    .option('--format <format>', 'Output format: json, sarif, table, prompt (auto-defaults to sarif in CI)', undefined)
+    // Default severity-threshold: `medium`. `low` includes too many
+    // tier-3 advisory findings that are typically noise unless the user
+    // explicitly opts in; `high` would hide medium-severity weak-crypto
+    // findings that ARE actionable. Medium is the right balance for
+    // first-time users.
+    .option('--severity-threshold <severity>', 'Minimum severity to include in report', 'medium')
     .option('--fail-on <levels>', 'Comma-separated severities that cause non-zero exit', 'critical,high')
     .option('--include <patterns>', 'Comma-separated glob patterns to include')
     .option('--exclude <patterns>', 'Comma-separated glob patterns to exclude')
     .option('--output <file>', 'Write report to file')
     .option('--api-url <url>', 'Compliance API base URL (or PC_API_URL env)')
     .option('--api-key <key>', 'API key for compliance API (or PC_API_KEY env)')
+    .option('--async', 'Use the async-validate flow (server returns 202 immediately; CLI polls until COMPLETED). Useful for large scans where holding a connection isn’t practical.')
+    .option('--chunked', 'Force the chunked-session flow regardless of payload size. The default already auto-falls-back to chunked when /validate returns 413 with a chunked-endpoint suggestion.')
+    .option('--pr <range>', 'Scan only files changed in a git diff range (e.g. "origin/main..HEAD"). Cuts CI scan time on large repos by skipping unchanged files. Requires baseDir to be the git repo root.')
     .action(async (repoPath, opts) => {
     try {
         const target = repoPath ?? '.';
-        const frameworks = parseList(opts.framework) ?? ['soc2'];
+        const frameworks = parseList(opts.framework) ?? ['soc2', 'hipaa', 'nist-csf'];
         const failOn = parseList(opts.failOn) ?? ['critical', 'high'];
-        const format = (opts.format ?? 'table');
-        console.error(`Scanning ${path.resolve(target)} for ${frameworks.join(', ')}...`);
+        // Format resolution:
+        //   1. explicit --format wins
+        //   2. otherwise: sarif when CI is detected, table when interactive
+        // SARIF in CI lets GitHub code scanning / GitLab security dashboards
+        // ingest results with zero extra configuration; table in interactive
+        // shells gives the human-readable summary first-time users expect.
+        const format = (opts.format ?? (isCiEnvironment() ? 'sarif' : 'table'));
+        // --async and --chunked are mutually exclusive; pick the explicit
+        // mode if either flag is set, otherwise let `scan()` pick (sync
+        // with auto-fallback to chunked on 413).
+        let mode = 'sync';
+        if (opts.async && opts.chunked) {
+            console.error('scan: --async and --chunked are mutually exclusive.');
+            process.exit(2);
+        }
+        if (opts.async)
+            mode = 'async';
+        else if (opts.chunked)
+            mode = 'chunked';
+        // --pr: restrict the scan to files in `git diff --name-only <range>`.
+        // Empty diff → exit 0 immediately (nothing to scan).
+        let include = parseList(opts.include);
+        if (opts.pr) {
+            const changed = computeChangedFiles(target, opts.pr);
+            if (changed.length === 0) {
+                console.error(`No files changed in range "${opts.pr}". Nothing to scan.`);
+                process.exit(0);
+            }
+            console.error(`--pr ${opts.pr}: restricting scan to ${changed.length} changed file(s).`);
+            // Use the diff list as exact-match include patterns. minimatch treats
+            // ordinary paths (no glob chars) as literal matches against relPath.
+            include = changed;
+        }
+        console.error(`Scanning ${path.resolve(target)} for ${frameworks.join(', ')}` +
+            (mode === 'sync' ? '' : ` (${mode} mode)`) +
+            '...');
         const response = await (0, index_1.scan)({
             repoPath: target,
             frameworks,
             options: {
                 severityThreshold: opts.severityThreshold,
                 failOn: failOn,
-                include: parseList(opts.include),
+                include,
                 exclude: parseList(opts.exclude),
                 apiUrl: opts.apiUrl,
                 apiKey: opts.apiKey,
+                config: { mode },
             },
         });
         writeOutput(renderReport(response, format), opts.output);
@@ -196,6 +279,54 @@ program
         process.exit(2);
     }
 });
+// ── scans ───────────────────────────────────────────────────────────────────
+// Fetch the current status / final result of any scan by ID. Useful with
+// `--async` to resume a poll loop after a CI step boundary, or to inspect
+// a chunked session that was abandoned mid-flight.
+program
+    .command('scans <scanId>')
+    .description('Get the status + findings of a scan by ID')
+    .option('--format <format>', 'Output format: json, sarif, table, prompt', 'json')
+    .option('--output <file>', 'Write report to file')
+    .option('--api-url <url>', 'Compliance API base URL (or PC_API_URL env)')
+    .option('--api-key <key>', 'API key for compliance API (or PC_API_KEY env)')
+    .action(async (scanId, opts) => {
+    try {
+        const format = (opts.format ?? 'json');
+        const { ComplianceApiClient } = await Promise.resolve().then(() => __importStar(require('./api-client')));
+        const client = new ComplianceApiClient(opts.apiUrl, opts.apiKey);
+        const scan = await client.getScan(scanId);
+        // Same scannerError / exit-code-2 plumbing as scan() / gate(): a
+        // user retrieving a stored scan that failed for scanner reasons
+        // must see the same distinction (exit 2, scannerError surfaced).
+        const scannerError = scan.scannerError;
+        const exitCode = scannerError ? 2 : scan.passed ? 0 : 1;
+        const payload = {
+            scanId,
+            passed: scan.passed,
+            status: scan.status ?? 'COMPLETED',
+            findings: scan.findings ?? [],
+            summary: scan.summary,
+            exitCode,
+            ...(scannerError ? { scannerError } : {}),
+        };
+        // Use the same renderer as `scan` so format=table/sarif/prompt all work.
+        writeOutput(renderReport(payload, format), opts.output);
+        if (scannerError)
+            (0, index_1.emitScannerErrorWarning)(scannerError);
+        // Exit 2 if scan is still in progress — the CLI run shouldn't gate on
+        // an indeterminate result.
+        if (scan.status === 'IN_PROGRESS') {
+            console.error(`Scan ${scanId} is still IN_PROGRESS. Re-run the same command to keep polling, or use 'pc scan --async' to wait for completion.`);
+            process.exit(2);
+        }
+        process.exit(exitCode);
+    }
+    catch (error) {
+        console.error(`✗ Error: ${error.message}`);
+        process.exit(2);
+    }
+});
 // ── hook ────────────────────────────────────────────────────────────────────
 program
     .command('hook')
@@ -290,18 +421,22 @@ async function collectHookFiles(filePath) {
 // ── init ────────────────────────────────────────────────────────────────────
 program
     .command('init')
-    .description('Configure compliance hooks for coding agents')
+    .description('Configure compliance hooks for coding agents and/or CI workflows')
     .option('--agent <agents>', 'Comma-separated agents to configure (claude, cursor, codex, opencode, github-copilot, gemini-cli). Use "all" to configure every agent. Default: auto-detect.')
+    .option('--ci <providers>', 'Comma-separated CI providers to scaffold (github, gitlab, circleci). Use "all" for every provider. Opt-in only \u2014 never auto-detected.')
     .option('--force', 'Overwrite existing compliance hook entries')
     .option('--dir <path>', 'Project directory to configure', '.')
     .action((opts) => {
     try {
         const dir = path.resolve(opts.dir ?? '.');
         const agents = resolveAgents(opts.agent, dir);
-        if (agents.length === 0) {
-            console.error('init: no agents selected and none auto-detected. ' +
-                'Use --agent <name> to configure explicitly (claude, cursor, codex, ' +
-                'opencode, github-copilot, gemini-cli, or "all").');
+        const ciProviders = resolveCiProviders(opts.ci);
+        if (agents.length === 0 && ciProviders.length === 0) {
+            console.error('init: nothing to do. ' +
+                'Use --agent <name> to configure a coding agent (claude, cursor, codex, ' +
+                'opencode, github-copilot, gemini-cli, or "all"), and/or --ci <provider> ' +
+                'to scaffold CI workflows (github, gitlab, circleci, or "all"). ' +
+                'Without --agent the CLI also auto-detects agents already in use.');
             process.exit(2);
         }
         let anyFailed = false;
@@ -312,6 +447,12 @@ program
             if (result.status === 'failed')
                 anyFailed = true;
         }
+        for (const provider of ciProviders) {
+            const result = configureCiProvider(provider, dir, !!opts.force);
+            process.stdout.write(result.message + '\n');
+            if (result.status === 'failed')
+                anyFailed = true;
+        }
         process.exit(anyFailed ? 1 : 0);
     }
     catch (error) {
@@ -547,6 +688,224 @@ function configureInstructionFile(agent, dir, relPath, force, writtenPaths) {
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+const ALL_CI_PROVIDERS = ['github', 'gitlab', 'circleci'];
+function isCiProvider(name) {
+    return ALL_CI_PROVIDERS.includes(name);
+}
+function resolveCiProviders(userChoice) {
+    if (!userChoice)
+        return [];
+    const list = parseList(userChoice) ?? [];
+    if (list.length === 1 && list[0] === 'all')
+        return ALL_CI_PROVIDERS.slice();
+    const valid = [];
+    for (const name of list) {
+        if (isCiProvider(name))
+            valid.push(name);
+        else
+            console.error(`init: unknown CI provider "${name}" — ignoring`);
+    }
+    return valid;
+}
+function configureCiProvider(provider, dir, force) {
+    switch (provider) {
+        case 'github':
+            return writeCiFile(provider, dir, path.join('.github', 'workflows', 'prodcycle.yml'), GITHUB_WORKFLOW, force);
+        case 'gitlab':
+            return writeCiFile(provider, dir, '.gitlab-ci.prodcycle.yml', GITLAB_WORKFLOW, force);
+        case 'circleci':
+            return writeCiFile(provider, dir, path.join('.circleci', 'prodcycle.yml'), CIRCLECI_WORKFLOW, force);
+    }
+}
+function writeCiFile(provider, dir, relPath, content, force) {
+    const fullPath = path.join(dir, relPath);
+    if (fs.existsSync(fullPath) && !force) {
+        return {
+            status: 'already',
+            message: `[ci:${provider}] ${relPath} already exists. Use --force to overwrite.`,
+        };
+    }
+    const parent = path.dirname(fullPath);
+    if (!fs.existsSync(parent))
+        fs.mkdirSync(parent, { recursive: true });
+    fs.writeFileSync(fullPath, content);
+    // GitHub uses the `prodcycle/actions/compliance` action, which reads
+    // its key from `secrets.PRODCYCLE_API_KEY`. GitLab and CircleCI invoke
+    // the CLI directly, which reads `PC_API_KEY` from the environment.
+    const followup = provider === 'gitlab'
+        ? `Include it from .gitlab-ci.yml: \`include: '${relPath}'\`. `
+        : provider === 'circleci'
+            ? `Reference it from .circleci/config.yml or merge the contents in. `
+            : '';
+    const secretName = provider === 'github' ? 'PRODCYCLE_API_KEY' : 'PC_API_KEY';
+    return {
+        status: 'installed',
+        message: `[ci:${provider}] wrote ${fullPath}. ` +
+            followup +
+            `Set ${secretName} as a secret/variable in your ${provider} project before the first run.`,
+    };
+}
+// GitHub: delegate to the dedicated `prodcycle/actions/compliance` GitHub
+// Action rather than calling the CLI directly. The action handles diff vs
+// full-repo scan automatically (PR events vs push events), posts inline
+// annotations on the PR diff, and writes a summary comment — none of
+// which the CLI's own SARIF output reproduces. See
+// https://github.com/prodcycle/actions for the full input reference.
+const GITHUB_WORKFLOW = `name: Prodcycle Compliance
+
+on:
+  pull_request:
+  push:
+    # Update this list to match your repo's default branch (e.g. master,
+    # develop). GitHub Actions does not support a dynamic
+    # \$default-branch / \${{ github.event.repository.default_branch }}
+    # value here, so the branch name has to be literal.
+    branches: [main]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: prodcycle/actions/compliance@v2
+        with:
+          api-key: \${{ secrets.PRODCYCLE_API_KEY }}
+`;
+const GITLAB_WORKFLOW = `# Prodcycle compliance scan. Include from your main .gitlab-ci.yml:
+#   include:
+#     - local: .gitlab-ci.prodcycle.yml
+#
+# Set PC_API_KEY as a CI/CD variable (Settings → CI/CD → Variables) before
+# the first run. Mark it Masked + Protected.
+
+prodcycle:
+  stage: test
+  image: node:22-alpine
+  variables:
+    GIT_DEPTH: "0"
+  before_script:
+    - apk add --no-cache git
+  script:
+    - |
+      if [ "$CI_PIPELINE_SOURCE" = "merge_request_event" ]; then
+        git fetch --no-tags origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+        npx --yes prodcycle scan . \\
+          --pr "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME..HEAD" \\
+          --format sarif --output prodcycle.sarif
+      else
+        npx --yes prodcycle scan . --format sarif --output prodcycle.sarif
+      fi
+  artifacts:
+    when: always
+    paths:
+      - prodcycle.sarif
+    reports:
+      sast: prodcycle.sarif
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+`;
+const CIRCLECI_WORKFLOW = `# Prodcycle compliance scan. To use this, either replace .circleci/config.yml
+# or include it as a continuation/orb. Minimum example:
+#
+#   version: 2.1
+#   workflows:
+#     compliance:
+#       jobs:
+#         - prodcycle-scan
+#
+# Set PC_API_KEY as a project environment variable in CircleCI before the
+# first run.
+#
+# CircleCI does not expose the PR target branch as a built-in env var
+# (\`CIRCLE_BASE_BRANCH\` does not exist; see
+# https://circleci.com/docs/reference/variables/), so to scope PR scans
+# to changed files only, set a project-level env var \`PRODCYCLE_PR_BASE\`
+# to the branch your PRs target (e.g. \`main\`, \`develop\`). When unset,
+# this template runs a full-repo scan.
+
+version: 2.1
+jobs:
+  prodcycle-scan:
+    docker:
+      - image: cimg/node:22.0
+    steps:
+      - checkout
+      - run:
+          name: Run Prodcycle compliance scan
+          command: |
+            if [ -n "\${PRODCYCLE_PR_BASE:-}" ] && [ -n "\${CIRCLE_PULL_REQUEST:-}" ]; then
+              git fetch --no-tags origin "$PRODCYCLE_PR_BASE"
+              npx --yes prodcycle scan . \\
+                --pr "origin/$PRODCYCLE_PR_BASE..HEAD" \\
+                --format sarif --output prodcycle.sarif
+            else
+              npx --yes prodcycle scan . --format sarif --output prodcycle.sarif
+            fi
+      # \`when: always\` so the SARIF artifact uploads even when the scan
+      # exits non-zero — compliance scanners exit 1 when findings exist,
+      # which is precisely the case where you want the report preserved.
+      - store_artifacts:
+          path: prodcycle.sarif
+          destination: prodcycle-sarif
+          when: always
+
+workflows:
+  compliance:
+    jobs:
+      - prodcycle-scan
+`;
+/**
+ * Compute the list of files changed in a git diff range, relative to repo root.
+ * Filters to ACMR (Added/Copied/Modified/Renamed) so deleted files don't get
+ * scanned (they're not on disk anymore, and walk() would skip them anyway).
+ *
+ * Errors handled explicitly:
+ *   - `ENOENT` (git not in PATH) → actionable "git executable not found"
+ *   - `ETIMEDOUT` (git stalled — credential helper / auth prompt / etc.)
+ *     → fail fast with a 30s timeout so CI jobs don't hang
+ *   - non-zero exit → forward git's stderr so the user can see e.g. the
+ *     "fatal: bad revision" message and fix the range argument
+ *
+ * Output paths are normalised to the platform separator: git emits POSIX
+ * forward-slashes always, but the file walker on Windows produces
+ * back-slashed `relPath` values. Without this conversion the literal
+ * minimatch comparison silently excludes every changed file on Windows.
+ */
+const GIT_DIFF_TIMEOUT_MS = 30_000;
+function computeChangedFiles(repoPath, range) {
+    let stdout;
+    try {
+        stdout = (0, child_process_1.execFileSync)('git', ['-C', repoPath, 'diff', '--name-only', '--diff-filter=ACMR', range], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: GIT_DIFF_TIMEOUT_MS,
+        });
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT') {
+            console.error('--pr: git executable not found in PATH');
+            process.exit(2);
+        }
+        if (e?.code === 'ETIMEDOUT' || e?.signal === 'SIGTERM') {
+            console.error(`--pr: git diff timed out after ${GIT_DIFF_TIMEOUT_MS}ms (range "${range}"). ` +
+                'Check that the range does not require network access or credentials.');
+            process.exit(2);
+        }
+        const stderr = e?.stderr?.toString?.() ?? e?.message ?? 'unknown error';
+        console.error(`--pr: git diff failed for range "${range}": ${stderr.trim()}`);
+        process.exit(2);
+    }
+    return stdout
+        .split('\n')
+        .map((s) => s.trim().split('/').join(path.sep))
+        .filter(Boolean);
+}
 function readStdin() {
     return new Promise((resolve, reject) => {
         if (process.stdin.isTTY) {
@@ -559,4 +918,10 @@ function readStdin() {
         process.stdin.on('error', reject);
     });
 }
-program.parse(injectScanDefault(process.argv));
+// Only auto-parse when invoked as a script (i.e. via the `prodcycle`
+// bin entry). Importing this module from tests must NOT execute the
+// CLI — otherwise `node --test` triggers a real `program.parse` and
+// fails before the test cases can run.
+if (require.main === module) {
+    program.parse(injectScanDefault(process.argv));
+}

package/dist/index.d.ts

@@ -1,35 +1,75 @@
-import { ScanOptions, GateOptions } from './api-client';
+import { ScanOptions, GateOptions, BackfillError } from './api-client';
 export * from './api-client';
 export * from './formatters/table';
 export * from './formatters/prompt';
 export * from './formatters/sarif';
 /**
- * Scan a repository by collecting files and sending them to the API
+ * Set when the server-side scanner threw and the API was configured to
+ * fail closed (the default). When this is present, callers MUST treat
+ * `passed: false` as "scanner unavailable — cannot certify compliance"
+ * rather than "code is dirty." Mirrors the API's `ScannerErrorInfo`
+ * shape; see `packages/compliance-code-scanner/api/src/domain/services/
+ * compliance-scan.service.ts` (`ScannerErrorInfo`) for the field
+ * contract.
+ *
+ * Without this surfaced to the CLI's --output JSON, a benchmark or CI
+ * report shows `passed: false, findings: []` and the user can't tell
+ * whether the code passed (no findings, all clean) from whether the
+ * scanner failed (no findings because nothing got evaluated).
+ */
+export interface ScannerError {
+    code: 'SCANNER_GATE_THREW';
+    message: string;
+    errorClass?: string;
+    errorCode?: string;
+}
+interface ScanReturn {
+    scanId?: string;
+    passed: boolean;
+    exitCode: number;
+    findings: unknown[];
+    report: unknown;
+    summary: unknown;
+    scannerError?: ScannerError;
+    /**
+     * Set when `validateChunked`'s findings-backfill GET failed. The summary
+     * still reflects the real finding count, but the structured findings are
+     * unavailable in this response. Callers should retry via `prodcycle scans
+     * <scanId>` to recover them. SARIF/JSON consumers branch on this to flag
+     * the result as incomplete rather than mistakenly clean.
+     */
+    backfillError?: BackfillError;
+}
+/**
+ * Format and write the scanner-error warning to stderr. Centralized so the
+ * wording stays consistent across `scan()`, `gate()`, and the `scans <id>`
+ * CLI subcommand.
+ */
+export declare function emitScannerErrorWarning(scannerError: ScannerError): void;
+/**
+ * Scan a repository by collecting files and sending them to the API.
+ *
+ * Modes (selectable via `options.config`):
+ *   - default: synchronous validate; auto-falls-back to chunked sessions
+ *     if the server returns 413 with `suggestedEndpoint=/v1/compliance/scans`
+ *   - `mode: 'async'`: kicks off a 202 async-validate and polls until
+ *     terminal (returns same shape as default)
+ *   - `mode: 'chunked'`: explicit chunked-session flow regardless of size
  */
 export declare function scan(params: {
     repoPath: string;
     frameworks?: string[];
     options?: ScanOptions;
-}): Promise<{
-    passed: boolean;
-    exitCode: number;
-    findings: never[];
-    report: null;
-    summary?: undefined;
-} | {
-    passed: any;
-    exitCode: number;
-    findings: any;
-    report: any;
-    summary: any;
-}>;
+}): Promise<ScanReturn>;
 /**
- * Gate code strings directly without writing to disk
+ * Gate code strings directly without writing to disk (low-latency hook
+ * endpoint, used by coding-agent post-edit hooks).
  */
 export declare function gate(options: GateOptions): Promise<{
-    passed: any;
+    scannerError?: ScannerError | undefined;
+    passed: boolean;
     exitCode: number;
-    findings: any;
-    prompt: any;
-    summary: any;
+    findings: unknown[];
+    prompt: string | undefined;
+    summary: unknown;
 }>;