@prodcycle/prodcycle 0.4.2 → 0.6.0

package/README.md

@@ -31,18 +31,27 @@ npm install @prodcycle/prodcycle
 ### CLI
 
 ```bash
-# Scan current directory against SOC 2 and HIPAA
+# Scan current directory against all 3 frameworks (default: soc2, hipaa, nist-csf).
+# Auto-flips to SARIF in known CI environments so output drops into
+# code-scanning dashboards without extra wiring.
+prodcycle scan .
+
+# Pin a specific framework or subset
 prodcycle scan . --framework soc2,hipaa
+prodcycle scan . --framework hipaa --severity-threshold high
 
-# Output as SARIF for GitHub Code Scanning
-prodcycle scan . --framework soc2 --format sarif --output results.sarif
+# Explicit SARIF (overrides the CI auto-flip)
+prodcycle scan . --format sarif --output results.sarif
 
-# Set severity threshold (only report HIGH and above)
-prodcycle scan . --framework hipaa --severity-threshold high
+# CI: scan only files changed in the PR
+prodcycle scan . --pr origin/main..HEAD
 
 # Auto-configure compliance hooks/instructions for your coding agents
 # (Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, Gemini CLI)
 prodcycle init --agent all
+
+# Scaffold a CI workflow that delegates to prodcycle/actions/compliance
+prodcycle init --ci github     # also: gitlab | circleci
 ```
 
 Subcommands: `scan` (full repo scan), `gate` (JSON payload from stdin), `hook` (coding-agent post-edit hook), `init` (agent setup).

package/dist/api-client.d.ts

@@ -16,11 +16,164 @@ export interface GateOptions {
     apiUrl?: string;
     config?: Record<string, unknown>;
 }
+/**
+ * Set when `validateChunked`'s post-`/complete` enrichment GET failed and the
+ * structured `findings` could not be recovered. Distinguishable from the
+ * server-side `scannerError`: this signals "we know there are N findings (per
+ * the summary) but we couldn't fetch them — retry with `prodcycle scans
+ * <id>`," not "we couldn't certify the scan." Surfaced as a named field
+ * (rather than via the `[key: string]: unknown` index signature) so
+ * TypeScript callers get a typed contract instead of `unknown`.
+ *
+ * `code` distinguishes:
+ *   - `BACKFILL_GET_FAILED`: GET threw / non-2xx — backfill couldn't run
+ *   - `BACKFILL_GET_RETURNED_EMPTY`: GET succeeded but findings were still
+ *     empty despite `summary.total > 0`. Usually means eventual consistency
+ *     between the `/complete` writer and the scan-record reader; retrying
+ *     after a short delay typically populates the findings. Surfaced as a
+ *     separate code so SARIF/dashboard consumers can decide whether to
+ *     auto-retry vs. surface as a hard error.
+ */
+export interface BackfillError {
+    code: 'BACKFILL_GET_FAILED' | 'BACKFILL_GET_RETURNED_EMPTY';
+    message: string;
+    scanId: string;
+    summaryTotal: number;
+}
+export interface ScanResult {
+    scanId?: string;
+    passed: boolean;
+    findingsCount?: number;
+    findings?: unknown[];
+    summary?: unknown;
+    prompt?: string;
+    status?: 'IN_PROGRESS' | 'COMPLETED' | 'FAILED';
+    backfillError?: BackfillError;
+    [key: string]: unknown;
+}
+interface ApiErrorBody {
+    status: 'error';
+    statusCode: number;
+    error?: {
+        type?: string;
+        message?: string;
+        suggestion?: string;
+        details?: {
+            maxBytes?: number;
+            maxFiles?: number;
+            chunkSizeBytes?: number;
+            receivedBytes?: number;
+            suggestedEndpoint?: string;
+            [key: string]: unknown;
+        };
+    };
+}
+/**
+ * Error thrown for any non-2xx response. Carries the parsed body + status so
+ * callers can branch on `details.suggestedEndpoint` (413 → chunked-session
+ * fallback) or `Retry-After` (429 / 503 → backoff + retry).
+ */
+export declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly body: ApiErrorBody | null;
+    readonly retryAfterSeconds: number | null;
+    constructor(statusCode: number, body: ApiErrorBody | null, retryAfterSeconds: number | null, message: string);
+}
 export declare class ComplianceApiClient {
     private apiUrl;
     private apiKey;
     constructor(apiUrl?: string, apiKey?: string);
-    validate(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<any>;
-    hook(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<any>;
-    private post;
+    /**
+     * Synchronous validate. On a 413 with `details.suggestedEndpoint ===
+     * '/v1/compliance/scans'`, silently falls back to the chunked-session
+     * flow so large-repo CI jobs don't have to know the difference.
+     */
+    validate(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<ScanResult>;
+    /**
+     * Hook endpoint — small per-write call from coding agents. No
+     * suggestedEndpoint fallback because /hook keeps the historical 50 MB
+     * ceiling; if a single hook write exceeds that, the caller's batching
+     * is the bug to fix.
+     */
+    hook(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<ScanResult>;
+    /**
+     * Open a chunked scan session. Returns a `scanId` that subsequent
+     * `appendChunk` / `completeSession` calls reference. Server-side TTL is
+     * 30 minutes by default — abandoned sessions self-clean via the
+     * stale-session reaper.
+     */
+    openSession(frameworks: string[], options?: ScanOptions): Promise<{
+        scanId: string;
+        chunkSizeBytes: number;
+        maxFilesPerChunk: number;
+        expiresAt: string;
+    }>;
+    /**
+     * Append a chunk of files to an open session. Each call has its own
+     * /hook-style cap (50 MB / 2000 files). The server caches per-content
+     * findings, so re-scans of unchanged files are O(1).
+     */
+    appendChunk(scanId: string, files: Record<string, string>): Promise<{
+        filesScanned: number;
+        cachedFiles: number;
+        findingsAdded: number;
+    }>;
+    /**
+     * Finalize a chunked session: flips status to COMPLETED, computes
+     * summary + passed, returns final findings.
+     */
+    completeSession(scanId: string): Promise<ScanResult>;
+    /**
+     * High-level helper: open → append (in chunks) → complete. Returns the
+     * same shape as `validate()` so callers that auto-fallback don't have
+     * to special-case the result.
+     *
+     * Caller can pre-set `chunkMaxBytes` / `chunkMaxFiles` on `options.config`
+     * to override the conservative defaults.
+     */
+    validateChunked(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<ScanResult>;
+    /**
+     * Some server versions of `POST /scans/:id/complete` return only the summary,
+     * leaving `findings` empty even when `summary.total > 0`. The findings are
+     * persisted on the scan record and recoverable via `GET /scans/:id`. Call
+     * this after `completeSession` (and any other path where the response shape
+     * may be summary-only) so SARIF/JSON consumers always see structured findings,
+     * not just a count. No-op when findings are already present or the scan is
+     * genuinely clean.
+     *
+     * Timeout: the follow-up GET goes through `this.request`, which wraps every
+     * fetch with `AbortSignal.timeout(REQUEST_TIMEOUT_MS)` (120 s default,
+     * tunable via `PC_REQUEST_TIMEOUT_MS`). A stalled server can't hang
+     * `validateChunked` indefinitely; if the abort fires, the catch below
+     * falls through with the original summary-only result.
+     */
+    private backfillFindingsIfMissing;
+    /**
+     * Async-validate: returns a `scanId` immediately; caller polls
+     * `getScan(scanId)` until status is COMPLETED or FAILED. Useful for CI
+     * runners that don't want to hold a connection for a 60 s scan.
+     */
+    validateAsync(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<{
+        scanId: string;
+    }>;
+    /**
+     * Fetch the current state of any scan (sync, async, or chunked-session).
+     */
+    getScan(scanId: string): Promise<ScanResult>;
+    /**
+     * High-level helper: kicks off an async-validate, polls until terminal,
+     * returns the same shape as `validate()`.
+     */
+    validateAndPoll(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<ScanResult>;
+    private buildOptions;
+    /**
+     * Single HTTP request with:
+     *   - auth header
+     *   - 429/503 + Retry-After honoring (up to MAX_RETRY_ATTEMPTS)
+     *   - structured error with parsed body so callers can introspect
+     *     `details.suggestedEndpoint` etc.
+     */
+    private request;
 }
+export declare function chunkFiles(files: Record<string, string>, maxBytes: number, maxFiles: number): Record<string, string>[];
+export {};