appsec-agent 2.4.5 → 2.6.0

package/dist/src/schemas/codebase_graph.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Codebase-graph context input (v2.6.0 / parent-app plan §8.18 Phase 2) —
+ * per-changed-file structural-graph summary passed to `pr_reviewer` so the LLM
+ * can factor symbol-level callers/callees and downstream blast-radius into its
+ * severity + confidence calls.
+ *
+ * Distinct from `--import-graph-context` (file-level inbound import counts via
+ * SCIP). This context is *symbol-level* (cbm tree-sitter graph; 155 languages):
+ *   - `callers`        — qualified symbol names whose body invokes a symbol
+ *                        defined in the changed file.
+ *   - `callees`        — qualified symbol names invoked from a symbol defined
+ *                        in the changed file.
+ *   - `blast_radius_files_count` — number of unique files reachable via
+ *                        outbound CALLS edges within the configured depth.
+ *
+ * The parent app's `composeCodebaseGraphContextPayload`
+ * (`<parent-app>/backend/src/services/codebaseGraph/`) does the cbm MCP queries
+ * (`search_graph` to find symbols defined in each changed file →
+ * `trace_path(direction=both, mode=calls, depth=2)` per symbol) and writes the
+ * JSON file. The agent here only parses + formats it for the prompt — no MCP
+ * query at agent runtime (Phase 3 is the live-MCP variant).
+ *
+ * Shape mirrors the v5.4.0 import-graph and v2.3.0 runtime-enrichment patterns
+ * exactly so that `prScanProcessor` can reuse the same fail-open + size-cap +
+ * coverage tagging conventions across all three structural-context families.
+ *
+ * **§8.5 PHI gate**: cbm sees only source-code text from CapsuleHealth-owned
+ * repos (no PHI). The schema accepts only structural-edge fields; any extras
+ * on per-file entries are silently dropped (mirrors runtime-enrichment's PHI
+ * minimization invariant defensively, even though cbm's input surface
+ * cannot contain PHI by construction).
+ */
+export interface CodebaseGraphFileEntry {
+    /** Repository-relative file path. Must be non-empty after trimming. */
+    file: string;
+    /**
+     * Optional list of qualified symbol names defined in this file that the PR
+     * actually changes. When present, the parent app scoped the
+     * callers/callees query to these symbols only (instead of every symbol
+     * defined in the file). Truncated at 20 to bound the prompt budget.
+     */
+    symbols_changed?: string[];
+    /**
+     * Inbound callers — qualified symbol names whose body invokes a symbol
+     * defined in this file. Truncated at 20 (most-popular first per the
+     * parent app's ranking) so the most structurally-important callers
+     * survive the prompt-budget cap.
+     */
+    callers?: string[];
+    /**
+     * Outbound callees — qualified symbol names invoked from any symbol
+     * defined in this file. Same truncation contract as `callers`.
+     */
+    callees?: string[];
+    /**
+     * Number of unique files reachable from this file via outbound CALLS
+     * edges within the parent app's configured `trace_path` depth (default
+     * 2). The LLM uses this as a "blast radius" signal — high counts
+     * indicate the changed file sits structurally upstream of much of the
+     * codebase, so a regression here propagates broadly.
+     *
+     * Coerced to a non-negative integer (fractional values floored,
+     * negatives clamped to 0).
+     */
+    blast_radius_files_count: number;
+    /**
+     * Per-file resolution outcome:
+     *   - `ok`         — symbols found in cbm graph; callers/callees populated
+     *                    from `trace_path` results.
+     *   - `no_symbols` — file is in the changed set but cbm's `search_graph`
+     *                    returned no Function/Method nodes for it (data file,
+     *                    config, generated code, language not in cbm's 155).
+     *   - `missing`    — cbm artifact for the project's current head SHA was
+     *                    not found on the PVC; the parent app's load step
+     *                    short-circuited with an empty entry per file.
+     *   - `partial`    — at least one `trace_path` query failed (cbm
+     *                    transient error, depth limit, or query timeout); the
+     *                    callers/callees lists may be incomplete.
+     */
+    graph_status?: 'ok' | 'no_symbols' | 'missing' | 'partial';
+}
+export interface CodebaseGraphContext {
+    /** Optional default-branch SHA the cbm artifact was indexed from. */
+    default_branch_sha?: string;
+    /**
+     * Optional ISO-8601 timestamp recorded when the parent app composed
+     * this payload. Useful for forensic debugging if the soak shows
+     * unexpected behavior; not surfaced in the prompt.
+     */
+    parsed_at?: string;
+    /**
+     * Roll-up resolution status across all files in the request:
+     *   - `full`    — every changed file was found in the cbm graph and at
+     *                 least one symbol traced.
+     *   - `partial` — some files traced cleanly, others were `no_symbols` or
+     *                 `partial`.
+     *   - `none`    — the cbm artifact was loaded but no changed file
+     *                 produced traceable symbols (highly unusual; surface
+     *                 to ops via `coverage` panel).
+     *   - `empty`   — the parent app could not load a cbm artifact for the
+     *                 current head SHA (`codebase_graph_heads` row missing
+     *                 or stale). Fail-open; the LLM ignores this block.
+     */
+    coverage?: 'full' | 'partial' | 'none' | 'empty';
+    /**
+     * Per-file rows — already filtered by the parent app to the PR's
+     * changed-file set, so the LLM sees a compact "files touched by this
+     * PR with their structural-graph context" slice. Empty array means
+     * "graph configured but no overlap" — the formatter short-circuits
+     * to empty string in that case.
+     */
+    files: CodebaseGraphFileEntry[];
+    /** Optional metadata block for forensic/debug correlation; not surfaced in prompt. */
+    metadata?: {
+        project_name?: string;
+    };
+}
+/**
+ * Parse and validate a codebase-graph context JSON payload (throws on
+ * structural error). Caps mirror import-graph (500 files, 20 callers per
+ * file) so the prompt-budget worst case is symmetric across the two
+ * structural contexts.
+ */
+export declare function parseCodebaseGraphContext(data: unknown): CodebaseGraphContext;
+/**
+ * Format the context for inclusion in a PR-reviewer user prompt. Compact by
+ * design — symbol lists are truncated and the table renders only the most
+ * structurally-significant signals so the block stays well under the
+ * import-graph + runtime-enrichment budget envelope.
+ *
+ * Files are rendered most-blast-radius first to anchor the LLM's attention
+ * on the structurally-upstream files when the prompt is truncated.
+ */
+export declare function formatCodebaseGraphContextForPrompt(ctx: CodebaseGraphContext): string;
+//# sourceMappingURL=codebase_graph.d.ts.map

package/dist/src/schemas/codebase_graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebase_graph.d.ts","sourceRoot":"","sources":["../../../src/schemas/codebase_graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;;;;OASG;IACH,wBAAwB,EAAE,MAAM,CAAC;IACjC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,IAAI,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;CAC5D;AAED,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACjD;;;;;;OAMG;IACH,KAAK,EAAE,sBAAsB,EAAE,CAAC;IAChC,sFAAsF;IACtF,QAAQ,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACtC;AA+BD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,OAAO,GAAG,oBAAoB,CA8D7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM,CAkDrF"}

package/dist/src/schemas/codebase_graph.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Codebase-graph context input (v2.6.0 / parent-app plan §8.18 Phase 2) —
+ * per-changed-file structural-graph summary passed to `pr_reviewer` so the LLM
+ * can factor symbol-level callers/callees and downstream blast-radius into its
+ * severity + confidence calls.
+ *
+ * Distinct from `--import-graph-context` (file-level inbound import counts via
+ * SCIP). This context is *symbol-level* (cbm tree-sitter graph; 155 languages):
+ *   - `callers`        — qualified symbol names whose body invokes a symbol
+ *                        defined in the changed file.
+ *   - `callees`        — qualified symbol names invoked from a symbol defined
+ *                        in the changed file.
+ *   - `blast_radius_files_count` — number of unique files reachable via
+ *                        outbound CALLS edges within the configured depth.
+ *
+ * The parent app's `composeCodebaseGraphContextPayload`
+ * (`<parent-app>/backend/src/services/codebaseGraph/`) does the cbm MCP queries
+ * (`search_graph` to find symbols defined in each changed file →
+ * `trace_path(direction=both, mode=calls, depth=2)` per symbol) and writes the
+ * JSON file. The agent here only parses + formats it for the prompt — no MCP
+ * query at agent runtime (Phase 3 is the live-MCP variant).
+ *
+ * Shape mirrors the v5.4.0 import-graph and v2.3.0 runtime-enrichment patterns
+ * exactly so that `prScanProcessor` can reuse the same fail-open + size-cap +
+ * coverage tagging conventions across all three structural-context families.
+ *
+ * **§8.5 PHI gate**: cbm sees only source-code text from CapsuleHealth-owned
+ * repos (no PHI). The schema accepts only structural-edge fields; any extras
+ * on per-file entries are silently dropped (mirrors runtime-enrichment's PHI
+ * minimization invariant defensively, even though cbm's input surface
+ * cannot contain PHI by construction).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCodebaseGraphContext = parseCodebaseGraphContext;
+exports.formatCodebaseGraphContextForPrompt = formatCodebaseGraphContextForPrompt;
+const MAX_FILES = 500;
+const MAX_CALLERS_PER_FILE = 20;
+const MAX_CALLEES_PER_FILE = 20;
+const MAX_SYMBOLS_PER_FILE = 20;
+const VALID_GRAPH_STATUSES = new Set([
+    'ok',
+    'no_symbols',
+    'missing',
+    'partial',
+]);
+const VALID_COVERAGE_VALUES = new Set([
+    'full',
+    'partial',
+    'none',
+    'empty',
+]);
+const sanitizeStringArray = (input, cap) => {
+    if (!Array.isArray(input)) {
+        return undefined;
+    }
+    const cleaned = input
+        .filter((c) => typeof c === 'string' && c.trim().length > 0)
+        .slice(0, cap);
+    return cleaned.length > 0 ? cleaned : undefined;
+};
+/**
+ * Parse and validate a codebase-graph context JSON payload (throws on
+ * structural error). Caps mirror import-graph (500 files, 20 callers per
+ * file) so the prompt-budget worst case is symmetric across the two
+ * structural contexts.
+ */
+function parseCodebaseGraphContext(data) {
+    if (!data || typeof data !== 'object') {
+        throw new Error('Codebase-graph context must be a JSON object');
+    }
+    const o = data;
+    if (!Array.isArray(o.files)) {
+        throw new Error('Codebase-graph context must include a "files" array');
+    }
+    if (o.files.length > MAX_FILES) {
+        throw new Error(`Codebase-graph context supports at most ${MAX_FILES} files per run`);
+    }
+    const files = [];
+    for (const item of o.files) {
+        if (!item || typeof item !== 'object') {
+            throw new Error('Each codebase-graph file entry must be an object');
+        }
+        const f = item;
+        if (typeof f.file !== 'string' || !f.file.trim()) {
+            throw new Error('Each codebase-graph file entry must have a non-empty string "file"');
+        }
+        if (typeof f.blast_radius_files_count !== 'number' ||
+            !Number.isFinite(f.blast_radius_files_count)) {
+            throw new Error('Each codebase-graph file entry must have a numeric "blast_radius_files_count"');
+        }
+        const graphStatus = typeof f.graph_status === 'string' &&
+            VALID_GRAPH_STATUSES.has(f.graph_status)
+            ? f.graph_status
+            : undefined;
+        files.push({
+            file: String(f.file),
+            symbols_changed: sanitizeStringArray(f.symbols_changed, MAX_SYMBOLS_PER_FILE),
+            callers: sanitizeStringArray(f.callers, MAX_CALLERS_PER_FILE),
+            callees: sanitizeStringArray(f.callees, MAX_CALLEES_PER_FILE),
+            blast_radius_files_count: Math.max(0, Math.trunc(f.blast_radius_files_count)),
+            graph_status: graphStatus,
+        });
+    }
+    const coverage = typeof o.coverage === 'string' &&
+        VALID_COVERAGE_VALUES.has(o.coverage)
+        ? o.coverage
+        : undefined;
+    return {
+        default_branch_sha: typeof o.default_branch_sha === 'string' ? o.default_branch_sha : undefined,
+        parsed_at: typeof o.parsed_at === 'string' ? o.parsed_at : undefined,
+        coverage,
+        files,
+        metadata: o.metadata && typeof o.metadata === 'object'
+            ? {
+                project_name: typeof o.metadata.project_name === 'string'
+                    ? o.metadata.project_name
+                    : undefined,
+            }
+            : undefined,
+    };
+}
+/**
+ * Format the context for inclusion in a PR-reviewer user prompt. Compact by
+ * design — symbol lists are truncated and the table renders only the most
+ * structurally-significant signals so the block stays well under the
+ * import-graph + runtime-enrichment budget envelope.
+ *
+ * Files are rendered most-blast-radius first to anchor the LLM's attention
+ * on the structurally-upstream files when the prompt is truncated.
+ */
+function formatCodebaseGraphContextForPrompt(ctx) {
+    if (ctx.files.length === 0) {
+        return '';
+    }
+    const sorted = [...ctx.files].sort((a, b) => b.blast_radius_files_count - a.blast_radius_files_count);
+    const lines = [];
+    lines.push('### Codebase-graph context (symbol-level callers/callees, plan §8.18 Phase 2)');
+    lines.push('For each changed file below, the parent app queried the codebase-memory-mcp graph for symbols defined in the file and traced their inbound (callers) and outbound (callees) CALLS edges. Use this as a structural-impact signal: a high `blast radius` means a regression in the file propagates to many downstream files; a non-empty `callers` list means the changed code is reached by other code paths and is more likely to fire under realistic traffic.');
+    lines.push('Treat this as advisory — when callers ≥ 1 and blast radius ≥ 5, lean toward keeping medium/high-severity findings on the file even if the diff alone looks low-risk. When `graph_status` is `no_symbols` (data file, generated code, unsupported language), structural reach is not measurable from this signal — fall back to your default judgment.');
+    if (ctx.default_branch_sha) {
+        lines.push(`Graph built from default-branch SHA \`${ctx.default_branch_sha.slice(0, 12)}\`.`);
+    }
+    if (ctx.coverage && ctx.coverage !== 'full') {
+        lines.push(`_Coverage: **${ctx.coverage}** — entries with \`graph_status=missing\` or \`partial\` will **not** be downranked (fail-open)._`);
+    }
+    lines.push('');
+    lines.push('| File | Callers | Callees | Blast radius | Status |');
+    lines.push('|---|---|---|---:|:---:|');
+    for (const f of sorted) {
+        const status = f.graph_status ?? 'ok';
+        const callers = f.callers && f.callers.length > 0
+            ? f.callers
+                .slice(0, 3)
+                .map((c) => `\`${c}\``)
+                .join(', ') + (f.callers.length > 3 ? ` (+${f.callers.length - 3})` : '')
+            : '—';
+        const callees = f.callees && f.callees.length > 0
+            ? f.callees
+                .slice(0, 3)
+                .map((c) => `\`${c}\``)
+                .join(', ') + (f.callees.length > 3 ? ` (+${f.callees.length - 3})` : '')
+            : '—';
+        lines.push(`| \`${f.file}\` | ${callers} | ${callees} | ${f.blast_radius_files_count} | ${status} |`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=codebase_graph.js.map

package/dist/src/schemas/codebase_graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebase_graph.js","sourceRoot":"","sources":["../../../src/schemas/codebase_graph.ts"],"names":[],"mappings":"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"}

package/dist/src/schemas/learned_guidance.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Learned-guidance synthesizer schemas (v2.5.0 / parent-app plan §3.8 — CLLG).
+ *
+ * The parent app collects three signal streams (dismissal validations,
+ * `addressed` PR outcomes, 👍 feedback) and buckets them by CWE. For each
+ * eligible bucket it asks this role to emit ONE short policy bullet that
+ * captures the class-level pattern (e.g. *"Trust the CSRF middleware in
+ * `auth/csrf.ts`; do not flag PR routes that go through it."*).
+ *
+ * Input file shape (passed via `--inputs <file>`; matches the JSON the
+ * parent app's `runSynthesizerAgent` writes in `learnedGuidanceSynthesizer.ts`):
+ *
+ *     {
+ *       "buckets": [
+ *         {
+ *           "cwe": "CWE-79",
+ *           "signal_count": 12,
+ *           "example_dismissal_reasons": [
+ *             "duplicate of issue #4321 - already mitigated by helmet middleware",
+ *             "auto-escaped by React JSX",
+ *             ...
+ *           ]
+ *         },
+ *         ...
+ *       ]
+ *     }
+ *
+ * Output shape on stdout (structured JSON, written to `-o <file>` per the
+ * parent app's spawn contract; backend rejects anything off-schema with
+ * `outcome=validation_error`):
+ *
+ *     {
+ *       "bullets": [
+ *         {
+ *           "cwe": "CWE-79",
+ *           "bullet": "≤300 chars positive-form rule the pr_reviewer can apply",
+ *           "confidence": 0.85
+ *         },
+ *         ...
+ *       ]
+ *     }
+ *
+ * The role is a pure transform: no Read/Grep tools, no source-tree
+ * access. Output is constrained by `LEARNED_GUIDANCE_OUTPUT_SCHEMA` so a
+ * malformed bullet list never reaches the parent app's prompt budget.
+ */
+export interface LearnedGuidanceBucketInput {
+    cwe: string;
+    signal_count: number;
+    example_dismissal_reasons: string[];
+}
+export interface LearnedGuidanceInputs {
+    buckets: LearnedGuidanceBucketInput[];
+}
+/** Output character cap. Stays in lockstep with the parent app's `MAX_BULLET_LEN = 300`. */
+export declare const MAX_BULLET_LEN = 300;
+export interface LearnedGuidanceBullet {
+    cwe: string;
+    bullet: string;
+    confidence: number;
+}
+export interface LearnedGuidanceOutput {
+    bullets: LearnedGuidanceBullet[];
+}
+/**
+ * Parse and validate a `LearnedGuidanceInputs` object loaded from the
+ * `--inputs` JSON file. Throws on any structural deviation; the CLI
+ * wrapper in `main.ts` exits non-zero so the parent app sees the error
+ * via stderr (and stays fail-closed: zero bullets persisted).
+ */
+export declare function parseLearnedGuidanceInputs(data: unknown): LearnedGuidanceInputs;
+/**
+ * Convenience loader matching the pattern used by `loadRetestContext`
+ * etc. — read JSON from disk, parse, validate, return.
+ *
+ * Caller is responsible for path validation (we expect `main.ts` to run
+ * the file path through `validateInputFilePath` before calling this so
+ * traversal attempts never reach the loader).
+ */
+export declare function loadLearnedGuidanceInputs(absolutePath: string): LearnedGuidanceInputs;
+/**
+ * Build the user-facing prompt for the synthesizer role. The prompt:
+ *   1. States the task and the success bar (positive-form rule, not generic).
+ *   2. Lists each bucket with its CWE, signal count, and a few example reasons.
+ *   3. Reminds the model of the schema, the per-bullet length cap, and the
+ *      confidence scale.
+ *
+ * The system prompt (set in `agent_options.ts`) plus the JSON schema
+ * enforcement (set on `Options.outputFormat`) enforce the structural
+ * contract; this prompt focuses on the *content* contract.
+ */
+export declare function buildLearnedGuidanceUserPrompt(inputs: LearnedGuidanceInputs): string;
+export declare const LEARNED_GUIDANCE_OUTPUT_SCHEMA: Record<string, unknown>;
+/** Convenience empty-output shell for tests / agent-side fallback. */
+export declare function emptyLearnedGuidanceOutput(): LearnedGuidanceOutput;
+//# sourceMappingURL=learned_guidance.d.ts.map

package/dist/src/schemas/learned_guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learned_guidance.d.ts","sourceRoot":"","sources":["../../../src/schemas/learned_guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAQH,MAAM,WAAW,0BAA0B;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,yBAAyB,EAAE,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,0BAA0B,EAAE,CAAC;CACvC;AAaD,4FAA4F;AAC5F,eAAO,MAAM,cAAc,MAAM,CAAC;AAMlC,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,qBAAqB,EAAE,CAAC;CAClC;AAMD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,OAAO,GAAG,qBAAqB,CA2D/E;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,qBAAqB,CAYrF;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAmDpF;AAMD,eAAO,MAAM,8BAA8B,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAoClE,CAAC;AAEF,sEAAsE;AACtE,wBAAgB,0BAA0B,IAAI,qBAAqB,CAElE"}