appsec-agent 2.5.0 → 2.6.1

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/context_extraction.d.ts

@@ -2,7 +2,7 @@
  * Context Extraction Schemas
  *
  * Defines the input context and output for the context_extractor role.
- * ExtractionContext is assembled by sast-ai-app and passed via --extract-context JSON file.
+ * ExtractionContext is assembled by the parent app and passed via --extract-context JSON file.
  * The structured output contains project intelligence fields used to reduce false positives.
  */
 export interface ExtractionContextFile {

package/dist/src/schemas/context_extraction.js

@@ -3,7 +3,7 @@
  * Context Extraction Schemas
  *
  * Defines the input context and output for the context_extractor role.
- * ExtractionContext is assembled by sast-ai-app and passed via --extract-context JSON file.
+ * ExtractionContext is assembled by the parent app and passed via --extract-context JSON file.
  * The structured output contains project intelligence fields used to reduce false positives.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {

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

@@ -2,7 +2,7 @@
  * Finding Validator Context and Verdict Schemas
  *
  * Defines the input context and output verdict for the finding_validator role.
- * RetestContext is assembled by sast-ai-app and passed via --retest-context JSON file.
+ * RetestContext is assembled by the parent app and passed via --retest-context JSON file.
  * RetestVerdict is the structured output returned by the finding_validator agent.
  */
 export interface RetestContextFinding {
@@ -24,6 +24,37 @@ export interface RetestVerdict {
     reasoning: string;
     current_line: number | null;
 }
+/**
+ * Discriminator for `RetestContextValidationError` — see usage in `main.ts`
+ * for the operational contract.
+ *
+ * Parent apps that spawn `agent-run -r finding_validator` should treat exit
+ * code 2 + a stderr line beginning with `RETEST_CONTEXT_INVALID_SIGNAL` as
+ * "caller-side input invalid; do not retry without fixing the context",
+ * vs. exit code 1 ("agent crash; safe to retry").
+ *
+ * The signal prefix is intentionally short + greppable + free of regex
+ * metacharacters so a parent's `stderr.includes(...)` check is robust.
+ */
+export declare const RETEST_CONTEXT_INVALID_SIGNAL = "[finding_validator] retest_context_invalid";
+/**
+ * Thrown by {@link loadRetestContext} when the caller-supplied context
+ * fails validation. Distinct from generic `Error` so `main.ts` can
+ * cleanly route it to exit code 2 (caller-input invalid) rather than the
+ * default unhandled-exception path that surfaces as exit code 1 + a Node
+ * stack trace.
+ *
+ * Parent apps (e.g., a `findingRetestService` spawn wrapper) historically
+ * captured only the last N chars of stderr, which truncated the
+ * throwing-site frame and left only the bottom-of-stack
+ * `Module._compile` / `executeUserEntryPoint` frames in their logs.
+ * `RETEST_CONTEXT_INVALID_SIGNAL` is emitted to stderr as the FIRST
+ * line of the failure so even a 200-char capture window catches it.
+ */
+export declare class RetestContextValidationError extends Error {
+    readonly kind: string;
+    constructor(kind: string, message: string);
+}
 export declare function loadRetestContext(filePath: string, cwd: string): RetestContext;
 export declare const RETEST_VERDICT_SCHEMA: Record<string, unknown>;
 //# sourceMappingURL=finding_validator.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"finding_validator.d.ts","sourceRoot":"","sources":["../../../src/schemas/finding_validator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,oBAAoB,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;CACtB;AAMD,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAMD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAsB9E;AAMD,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAuBzD,CAAC"}
+{"version":3,"file":"finding_validator.d.ts","sourceRoot":"","sources":["../../../src/schemas/finding_validator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,oBAAoB,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;CACtB;AAMD,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAMD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,+CAA+C,CAAC;AAE1F;;;;;;;;;;;;;GAaG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAUD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CA4B9E;AAMD,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAuBzD,CAAC"}

package/dist/src/schemas/finding_validator.js

@@ -3,7 +3,7 @@
  * Finding Validator Context and Verdict Schemas
  *
  * Defines the input context and output verdict for the finding_validator role.
- * RetestContext is assembled by sast-ai-app and passed via --retest-context JSON file.
+ * RetestContext is assembled by the parent app and passed via --retest-context JSON file.
  * RetestVerdict is the structured output returned by the finding_validator agent.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -40,31 +40,81 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RETEST_VERDICT_SCHEMA = void 0;
+exports.RETEST_VERDICT_SCHEMA = exports.RetestContextValidationError = exports.RETEST_CONTEXT_INVALID_SIGNAL = void 0;
 exports.loadRetestContext = loadRetestContext;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 // ---------------------------------------------------------------------------
 // Context loader
 // ---------------------------------------------------------------------------
+/**
+ * Discriminator for `RetestContextValidationError` — see usage in `main.ts`
+ * for the operational contract.
+ *
+ * Parent apps that spawn `agent-run -r finding_validator` should treat exit
+ * code 2 + a stderr line beginning with `RETEST_CONTEXT_INVALID_SIGNAL` as
+ * "caller-side input invalid; do not retry without fixing the context",
+ * vs. exit code 1 ("agent crash; safe to retry").
+ *
+ * The signal prefix is intentionally short + greppable + free of regex
+ * metacharacters so a parent's `stderr.includes(...)` check is robust.
+ */
+exports.RETEST_CONTEXT_INVALID_SIGNAL = '[finding_validator] retest_context_invalid';
+/**
+ * Thrown by {@link loadRetestContext} when the caller-supplied context
+ * fails validation. Distinct from generic `Error` so `main.ts` can
+ * cleanly route it to exit code 2 (caller-input invalid) rather than the
+ * default unhandled-exception path that surfaces as exit code 1 + a Node
+ * stack trace.
+ *
+ * Parent apps (e.g., a `findingRetestService` spawn wrapper) historically
+ * captured only the last N chars of stderr, which truncated the
+ * throwing-site frame and left only the bottom-of-stack
+ * `Module._compile` / `executeUserEntryPoint` frames in their logs.
+ * `RETEST_CONTEXT_INVALID_SIGNAL` is emitted to stderr as the FIRST
+ * line of the failure so even a 200-char capture window catches it.
+ */
+class RetestContextValidationError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = 'RetestContextValidationError';
+        this.kind = kind;
+    }
+}
+exports.RetestContextValidationError = RetestContextValidationError;
+function fail(kind, message) {
+    // Emit the structured signal FIRST so parent apps with small stderr
+    // capture windows still see the prefix; the longer human-readable
+    // message follows but is not load-bearing.
+    console.error(`${exports.RETEST_CONTEXT_INVALID_SIGNAL}: ${kind}: ${message}`);
+    throw new RetestContextValidationError(kind, message);
+}
 function loadRetestContext(filePath, cwd) {
     const resolved = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
     if (!fs.existsSync(resolved)) {
-        throw new Error(`Retest context file not found: ${resolved}`);
+        fail('file_not_found', `Retest context file not found: ${resolved}`);
     }
     const content = fs.readFileSync(resolved, 'utf-8');
-    const ctx = JSON.parse(content);
+    let ctx;
+    try {
+        ctx = JSON.parse(content);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        fail('json_parse_error', `Retest context JSON parse error: ${msg}`);
+    }
     if (!ctx.finding || typeof ctx.finding !== 'object') {
-        throw new Error('Retest context must include a valid finding object');
+        fail('missing_finding', 'Retest context must include a valid finding object');
     }
     if (!ctx.finding.title || typeof ctx.finding.title !== 'string') {
-        throw new Error('Retest context finding must include a valid title');
+        fail('missing_finding_title', 'Retest context finding must include a valid title');
     }
     if (!ctx.finding.file || typeof ctx.finding.file !== 'string') {
-        throw new Error('Retest context finding must include a valid file path');
+        fail('missing_finding_file', 'Retest context finding must include a valid file path');
     }
     if (!ctx.code_snippet || typeof ctx.code_snippet !== 'string') {
-        throw new Error('Retest context must include a valid code_snippet');
+        fail('missing_code_snippet', 'Retest context must include a valid code_snippet');
     }
     return ctx;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"finding_validator.js","sourceRoot":"","sources":["../../../src/schemas/finding_validator.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCH,8CAsBC;AA3DD,uCAAyB;AACzB,2CAA6B;AAgC7B,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,SAAgB,iBAAiB,CAAC,QAAgB,EAAE,GAAW;IAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACjF,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,kCAAkC,QAAQ,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAkB,CAAC;IAEjD,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,8EAA8E;AAC9E,8DAA8D;AAC9D,8EAA8E;AAEjE,QAAA,qBAAqB,GAA4B;IAC5D,IAAI,EAAE,QAAQ;IACd,QAAQ,EAAE,CAAC,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,CAAC;IACtE,UAAU,EAAE;QACV,aAAa,EAAE;YACb,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,gEAAgE;SAC9E;QACD,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC;YAC/B,WAAW,EAAE,oCAAoC;SAClD;QACD,SAAS,EAAE;YACT,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,iEAAiE;SAC/E;QACD,YAAY,EAAE;YACZ,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC;YACxB,WAAW,EAAE,yDAAyD;SACvE;KACF;IACD,oBAAoB,EAAE,KAAK;CAC5B,CAAC"}
+{"version":3,"file":"finding_validator.js","sourceRoot":"","sources":["../../../src/schemas/finding_validator.ts"],"names":[],"mappings":"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"}

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

@@ -4,7 +4,7 @@
  * into its confidence calls.
  *
  * The authoritative post-LLM confidence downrank lives in the parent app
- * (`sast-ai-app/backend/src/services/importGraphDecision.ts`). The context
+ * (an `importGraphDecision`-style service). The context
  * here is advisory — it lets the LLM see what the post-pass will see and
  * avoid raising a HIGH-confidence finding on an unreachable helper file.
  *

package/dist/src/schemas/import_graph.js

@@ -5,7 +5,7 @@
  * into its confidence calls.
  *
  * The authoritative post-LLM confidence downrank lives in the parent app
- * (`sast-ai-app/backend/src/services/importGraphDecision.ts`). The context
+ * (an `importGraphDecision`-style service). The context
  * here is advisory — it lets the LLM see what the post-pass will see and
  * avoid raising a HIGH-confidence finding on an unreachable helper file.
  *

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

@@ -2,7 +2,7 @@
  * QA Verification Context and Verdict Schemas
  *
  * Defines the input context and output verdict for the qa_verifier role.
- * QaContext is assembled by sast-ai-app and passed via --qa-context JSON file.
+ * QaContext is assembled by the parent app and passed via --qa-context JSON file.
  * QaVerdict is the structured output returned by the qa_verifier agent.
  */
 export interface QaContext {

package/dist/src/schemas/qa_context.js

@@ -3,7 +3,7 @@
  * QA Verification Context and Verdict Schemas
  *
  * Defines the input context and output verdict for the qa_verifier role.
- * QaContext is assembled by sast-ai-app and passed via --qa-context JSON file.
+ * QaContext is assembled by the parent app and passed via --qa-context JSON file.
  * QaVerdict is the structured output returned by the qa_verifier agent.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {

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

@@ -1,12 +1,12 @@
 /**
- * Runtime-enrichment context input (v2.3.0 / sast-ai-app plan §4 + §8.14) —
+ * Runtime-enrichment context input (v2.3.0 / parent-app plan §4 + §8.14) —
  * per-file production-incident summary passed to `pr_reviewer` so the LLM can
  * factor incident history into its severity + confidence calls.
  *
  * The authoritative post-LLM gate override lives in the parent app
- * (`sast-ai-app/backend/src/routes/prScanProcessor.ts` — partition findings
- * into hot/cold and apply the §4 transform `medium → low / 0.6 → 0.4` per
- * file). The context here is advisory — it lets the LLM see what the
+ * (a `prScanProcessor`-style route — partition findings into hot/cold and
+ * apply the §4 transform `medium → low / 0.6 → 0.4` per file). The context
+ * here is advisory — it lets the LLM see what the
  * post-pass will see and avoid raising HIGH-confidence findings on
  * operationally-fragile files that the gate-override will then have to
  * "rescue" anyway, AND avoid suppressing low-severity findings on hot files

package/dist/src/schemas/runtime_enrichment.js

@@ -1,13 +1,13 @@
 "use strict";
 /**
- * Runtime-enrichment context input (v2.3.0 / sast-ai-app plan §4 + §8.14) —
+ * Runtime-enrichment context input (v2.3.0 / parent-app plan §4 + §8.14) —
  * per-file production-incident summary passed to `pr_reviewer` so the LLM can
  * factor incident history into its severity + confidence calls.
  *
  * The authoritative post-LLM gate override lives in the parent app
- * (`sast-ai-app/backend/src/routes/prScanProcessor.ts` — partition findings
- * into hot/cold and apply the §4 transform `medium → low / 0.6 → 0.4` per
- * file). The context here is advisory — it lets the LLM see what the
+ * (a `prScanProcessor`-style route — partition findings into hot/cold and
+ * apply the §4 transform `medium → low / 0.6 → 0.4` per file). The context
+ * here is advisory — it lets the LLM see what the
  * post-pass will see and avoid raising HIGH-confidence findings on
  * operationally-fragile files that the gate-override will then have to
  * "rescue" anyway, AND avoid suppressing low-severity findings on hot files

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

@@ -2,7 +2,7 @@
  * JSON Schema and TypeScript interfaces for Security Fix Output
  *
  * Defines the structured output schema for the code_fixer agent role.
- * The agent receives a FixContext (enriched finding data from sast-ai-app)
+ * The agent receives a FixContext (enriched finding data from the parent app)
  * and returns a FixOutput (structured fix via Claude SDK outputFormat).
  *
  * Author: Sam Li

package/dist/src/schemas/security_fix.js

@@ -3,7 +3,7 @@
  * JSON Schema and TypeScript interfaces for Security Fix Output
  *
  * Defines the structured output schema for the code_fixer agent role.
- * The agent receives a FixContext (enriched finding data from sast-ai-app)
+ * The agent receives a FixContext (enriched finding data from the parent app)
  * and returns a FixOutput (structured fix via Claude SDK outputFormat).
  *
  * Author: Sam Li

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "appsec-agent",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "TypeScript package for AppSec AI Agent management",
   "author": "Sam Li",
-  "date": "May 03 2026",
-  "license": "MIT",
+  "date": "May 12 2026",
+  "license": "Apache-2.0",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "files": [