@vibefoundry/vibe-shield 0.0.0-stage → 1.1.0

package/dist/src/reporter/console-reporter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * vibe-shield :: terminal reporter
+ * --------------------------------
+ * The scorecard is the product. It has one job: make a developer *feel* the
+ * number of critical findings in under a second, then hand them exact
+ * `file:line` citations they can click in a terminal.
+ *
+ * No colour is required for meaning — every status is also spelled out — so the
+ * output survives CI logs, `--no-color`, and screen readers.
+ */
+import type { ScanResult, Severity } from '../scanner/types';
+export interface Colorizer {
+    enabled: boolean;
+    red(text: string): string;
+    green(text: string): string;
+    yellow(text: string): string;
+    blue(text: string): string;
+    magenta(text: string): string;
+    cyan(text: string): string;
+    gray(text: string): string;
+    bold(text: string): string;
+    dim(text: string): string;
+    underline(text: string): string;
+}
+/** Build a colouriser honouring `NO_COLOR`, `FORCE_COLOR` and TTY detection. */
+export declare function createColorizer(stream?: {
+    isTTY?: boolean;
+}): Colorizer;
+declare const severityPaint: (color: Colorizer, severity: Severity) => ((text: string) => string);
+/** Strip ANSI codes to measure true display width. */
+declare const visibleLength: (text: string) => number;
+/** Pad `text` to `width` visible characters. */
+export declare const pad: (text: string, width: number) => string;
+declare const GRADE_ICON: Record<string, string>;
+export interface ReportOptions {
+    color?: Colorizer;
+    /** Terminal width. Defaults to `process.stdout.columns` or 100. */
+    width?: number;
+    /** Cap the per-finding list (0 = all). Default 50. */
+    maxFindings?: number;
+    /** Show timing / throughput statistics. */
+    showStats?: boolean;
+    /** Absolute root used to shorten paths (defaults to `result.rootDir`). */
+    cwd?: string;
+}
+/** Shown instead of a grade when discovery matched nothing: silence is not a pass. */
+export declare const NOTHING_SCANNED = "\u26A0  NO FILES SCANNED \u2014 this is not a pass";
+/** The one-line verdict, e.g. `💀 GRADE F — 0/100 · 6 critical`. */
+export declare function verdictLine(result: ScanResult, color: Colorizer): string;
+/** Full scorecard as an array of lines (no trailing newline). */
+export declare function renderConsoleReport(result: ScanResult, options?: ReportOptions): string[];
+/** Print the scorecard to a stream. */
+export declare function reportConsole(result: ScanResult, stream?: {
+    write(chunk: string): unknown;
+    isTTY?: boolean;
+    columns?: number;
+}, options?: ReportOptions): void;
+export { GRADE_ICON, severityPaint, visibleLength };

package/dist/src/reporter/console-reporter.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * vibe-shield :: terminal reporter
+ * --------------------------------
+ * The scorecard is the product. It has one job: make a developer *feel* the
+ * number of critical findings in under a second, then hand them exact
+ * `file:line` citations they can click in a terminal.
+ *
+ * No colour is required for meaning — every status is also spelled out — so the
+ * output survives CI logs, `--no-color`, and screen readers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.visibleLength = exports.severityPaint = exports.GRADE_ICON = exports.NOTHING_SCANNED = exports.pad = void 0;
+exports.createColorizer = createColorizer;
+exports.verdictLine = verdictLine;
+exports.renderConsoleReport = renderConsoleReport;
+exports.reportConsole = reportConsole;
+const types_1 = require("../scanner/types");
+const ANSI = {
+    red: [31, 39],
+    green: [32, 39],
+    yellow: [33, 39],
+    blue: [34, 39],
+    magenta: [35, 39],
+    cyan: [36, 39],
+    gray: [90, 39],
+    bold: [1, 22],
+    dim: [2, 22],
+    underline: [4, 24],
+};
+/** Build a colouriser honouring `NO_COLOR`, `FORCE_COLOR` and TTY detection. */
+function createColorizer(stream = process.stdout) {
+    const env = process.env;
+    const forced = env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== '0';
+    const disabled = env.NO_COLOR !== undefined || env.TERM === 'dumb';
+    const enabled = forced || (!disabled && stream.isTTY === true);
+    const wrap = (code, close) => (text) => (enabled ? `\u001B[${code}m${text}\u001B[${close}m` : text);
+    return {
+        enabled,
+        red: wrap(...ANSI.red),
+        green: wrap(...ANSI.green),
+        yellow: wrap(...ANSI.yellow),
+        blue: wrap(...ANSI.blue),
+        magenta: wrap(...ANSI.magenta),
+        cyan: wrap(...ANSI.cyan),
+        gray: wrap(...ANSI.gray),
+        bold: wrap(...ANSI.bold),
+        dim: wrap(...ANSI.dim),
+        underline: wrap(...ANSI.underline),
+    };
+}
+const SEVERITY_COLORS = {
+    critical: 'red',
+    high: 'magenta',
+    medium: 'yellow',
+    low: 'blue',
+    info: 'gray',
+};
+const severityPaint = (color, severity) => color[SEVERITY_COLORS[severity]];
+exports.severityPaint = severityPaint;
+/* -------------------------------------------------------------------------- */
+/* Layout helpers                                                             */
+/* -------------------------------------------------------------------------- */
+/** Strip ANSI codes to measure true display width. */
+const visibleLength = (text) => text.replace(/\u001B\[[0-9;]*m/g, '').length;
+exports.visibleLength = visibleLength;
+/** Pad `text` to `width` visible characters. */
+const pad = (text, width) => text + ' '.repeat(Math.max(0, width - visibleLength(text)));
+exports.pad = pad;
+const truncate = (text, width) => text.length <= width ? text : `${text.slice(0, Math.max(0, width - 1))}…`;
+const GRADE_ICON = {
+    'A+': '🏆',
+    A: '✅',
+    'A-': '✅',
+    'B+': '🟢',
+    B: '🟢',
+    'B-': '🟡',
+    'C+': '🟡',
+    C: '🟠',
+    'C-': '🟠',
+    'D+': '🔴',
+    D: '🔴',
+    'D-': '🔴',
+    F: '💀',
+};
+exports.GRADE_ICON = GRADE_ICON;
+const DEFAULT_WIDTH = 100;
+/** Shown instead of a grade when discovery matched nothing: silence is not a pass. */
+exports.NOTHING_SCANNED = '⚠  NO FILES SCANNED — this is not a pass';
+/** The one-line verdict, e.g. `💀 GRADE F — 0/100 · 6 critical`. */
+function verdictLine(result, color) {
+    if (result.stats.filesScanned === 0)
+        return color.yellow(exports.NOTHING_SCANNED);
+    const icon = GRADE_ICON[result.score.grade] ?? '•';
+    const grade = color.bold(severityPaint(color, result.score.counts.critical > 0 ? 'critical' : result.score.counts.high > 0 ? 'high' : result.score.counts.medium > 0 ? 'medium' : 'low')(result.score.grade));
+    const counts = ['critical', 'high', 'medium', 'low']
+        .filter((severity) => result.score.counts[severity] > 0)
+        .map((severity) => `${result.score.counts[severity]} ${severity}`)
+        .join(' · ');
+    return `${icon} GRADE ${grade} — ${result.score.score}/100${counts ? ` · ${counts}` : ''}`;
+}
+/** Render the header block: brand, version, target and verdict. */
+function renderHeader(result, color, width) {
+    const lines = [];
+    const title = color.bold(color.cyan('🛡️  vibe-shield'));
+    const version = color.dim(`v${result.version}`);
+    const mode = result.command === 'audit-skills' ? 'agent surface audit' : 'security scan';
+    lines.push(`${title} ${version} ${color.dim(`· ${mode}`)}`);
+    lines.push(color.dim(`target  ${truncate(result.rootDir, width - 10)}`));
+    lines.push('');
+    lines.push(verdictLine(result, color));
+    return lines;
+}
+/** A horizontal bar for the severity histogram. */
+function histogram(result, color) {
+    const counts = result.score.counts;
+    const order = ['critical', 'high', 'medium', 'low', 'info'];
+    const lines = [];
+    for (const severity of order) {
+        const count = counts[severity];
+        if (!count)
+            continue;
+        const paint = severityPaint(color, severity);
+        const bar = paint('█'.repeat(Math.min(40, count)));
+        lines.push(`  ${(0, exports.pad)(paint(severity.toUpperCase()), 8)} ${(0, exports.pad)(String(count), 4)} ${bar}`);
+    }
+    return lines;
+}
+/** All findings grouped by file, with exact citations. */
+function renderFindings(findings, color, options) {
+    const lines = [];
+    const maxFindings = options.maxFindings ?? 50;
+    // Severity is the outer sort key (what to fix first); file is the inner one so
+    // each file's findings stay together and the list reads like a patch.
+    const ordered = [...findings].sort((a, b) => types_1.SEVERITY_WEIGHT[b.severity] - types_1.SEVERITY_WEIGHT[a.severity] ||
+        a.filePath.localeCompare(b.filePath) ||
+        a.line - b.line);
+    const shown = maxFindings > 0 ? ordered.slice(0, maxFindings) : ordered;
+    let currentFile = '';
+    for (const finding of shown) {
+        if (finding.filePath !== currentFile) {
+            currentFile = finding.filePath;
+            lines.push('');
+            lines.push(color.bold(color.underline(currentFile)));
+        }
+        const paint = severityPaint(color, finding.severity);
+        const location = color.cyan(`${finding.line}:${finding.column}`);
+        lines.push(`  ${paint(finding.severity.toUpperCase().padEnd(8))} ${location.padEnd(color.enabled ? 22 : 8)} ${color.dim(finding.ruleId)}  ${finding.title}`);
+        if (finding.snippet)
+            lines.push(`           ${color.gray(truncate(finding.snippet, 110))}`);
+    }
+    if (maxFindings > 0 && findings.length > maxFindings) {
+        lines.push('');
+        lines.push(color.dim(`  … and ${findings.length - maxFindings} more. Run with --format json or --max-findings 0 to see every finding.`));
+    }
+    return lines;
+}
+/** Category breakdown, useful when the list is long. */
+function renderCategories(result, color) {
+    const byCategory = new Map();
+    for (const finding of result.findings) {
+        const bucket = byCategory.get(finding.category) ?? [];
+        bucket.push(finding);
+        byCategory.set(finding.category, bucket);
+    }
+    if (byCategory.size <= 1)
+        return [];
+    const lines = ['', color.bold('By category')];
+    const sorted = [...byCategory.entries()].sort((a, b) => b[1].length - a[1].length);
+    for (const [category, findings] of sorted) {
+        const worst = findings.reduce((acc, finding) => (types_1.SEVERITY_WEIGHT[finding.severity] > types_1.SEVERITY_WEIGHT[acc] ? finding.severity : acc), 'info');
+        const paint = severityPaint(color, worst);
+        lines.push(`  ${paint('●')} ${(0, exports.pad)(types_1.CATEGORY_TITLES[category] ?? category, 44)} ${findings.length}`);
+    }
+    return lines;
+}
+/** Timing / throughput footer. */
+function renderStats(result, color) {
+    const { stats } = result;
+    const parts = [
+        `${stats.filesScanned} ${stats.filesScanned === 1 ? 'file' : 'files'}`,
+    ];
+    parts.push(stats.bytesScanned >= 1024
+        ? `${(stats.bytesScanned / 1024).toFixed(0)} KiB`
+        : `${stats.bytesScanned} B`);
+    parts.push(`${stats.filesPerSecond} files/s`, `${stats.durationMs} ms`, `${result.ruleCount} rules`);
+    if (stats.cacheHits > 0)
+        parts.push(`${stats.cacheHits} cached`);
+    if (result.suppressedCount > 0)
+        parts.push(`${result.suppressedCount} suppressed`);
+    const line = color.dim(`  ${parts.join('  ·  ')}`);
+    return ['', line];
+}
+/** Next steps, tailored to what was found. */
+function renderFooter(result, color) {
+    const lines = [''];
+    if (result.stats.filesScanned === 0) {
+        for (const notice of result.notices)
+            lines.push(color.dim(`  ${notice}`));
+        lines.push(color.dim('  No grade is given for an empty scan — check the path, --include-docs/--include-tests, and .vibe-shieldignore.'));
+        return lines;
+    }
+    if (result.findings.length === 0) {
+        lines.push(color.green('  Nothing to fix. Keep the shield up. 🛡️'));
+        // The engine's "no vulnerabilities found" notice says the same thing in
+        // different words; drop it so a clean run stays one line.
+        for (const notice of result.notices) {
+            if (/^no vulnerabilities found/i.test(notice))
+                continue;
+            lines.push(color.dim(`  ${notice}`));
+        }
+        return lines;
+    }
+    const worst = result.findings[0]?.severity ?? 'info';
+    const critical = result.score.counts.critical;
+    if (critical > 0) {
+        lines.push(color.red(`  ⚠  ${critical} critical finding${critical === 1 ? '' : 's'} — rotate any exposed credential before anything else.`));
+    }
+    lines.push(`  ${color.bold('Fix it')}      npx github:avivgerz-hue/vibe-shield scan --fix-prompt    ${color.dim('# writes SECURITY_PATCH_PROMPT.md for your agent')}`);
+    lines.push(`  ${color.bold('Explain')}     npx github:avivgerz-hue/vibe-shield explain ${result.findings[0]?.ruleId ?? 'VSB-AI-001'}`);
+    lines.push(`  ${color.bold('Gate CI')}     npx github:avivgerz-hue/vibe-shield scan --fail-on ${worst} --format github`);
+    for (const notice of result.notices)
+        lines.push(color.dim(`  ${notice}`));
+    return lines;
+}
+/** Full scorecard as an array of lines (no trailing newline). */
+function renderConsoleReport(result, options = {}) {
+    const color = options.color ?? createColorizer();
+    const width = options.width ?? process.stdout.columns ?? DEFAULT_WIDTH;
+    const lines = [];
+    lines.push(...renderHeader(result, color, width));
+    const bars = histogram(result, color);
+    if (bars.length) {
+        lines.push('');
+        lines.push(...bars);
+    }
+    lines.push(...renderCategories(result, color));
+    if (result.findings.length) {
+        lines.push('');
+        lines.push(color.bold('Findings'));
+        lines.push(...renderFindings(result.findings, color, options));
+    }
+    if (options.showStats !== false)
+        lines.push(...renderStats(result, color));
+    lines.push(...renderFooter(result, color));
+    return lines;
+}
+/** Print the scorecard to a stream. */
+function reportConsole(result, stream = process.stdout, options = {}) {
+    const color = options.color ?? createColorizer(stream);
+    const width = options.width ?? stream.columns ?? DEFAULT_WIDTH;
+    const lines = renderConsoleReport(result, { ...options, color, width });
+    stream.write(`${lines.join('\n')}\n`);
+}

package/dist/src/reporter/formatters.d.ts

@@ -0,0 +1,38 @@
+/**
+ * vibe-shield :: machine-readable output
+ * --------------------------------------
+ * Five formats, one contract: every field the console shows is available
+ * structured, so nothing is lost when the report goes to a machine.
+ *
+ *  - `json`     the full `ScanResult` (stable, versioned by `schemaVersion`)
+ *  - `compact`  one line per finding — what CI actually needs
+ *  - `summary`  counts + grade only — for dashboards and PR comments
+ *  - `sarif`    SARIF 2.1.0 for GitHub code scanning (`--format sarif`)
+ *  - `github`   GitHub Actions workflow commands (annotations in the diff)
+ */
+import type { Finding, ScanResult } from '../scanner/types';
+export declare const OUTPUT_FORMATS: readonly ["console", "compact", "summary", "json", "sarif", "github"];
+export type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+export declare const isOutputFormat: (value: unknown) => value is OutputFormat;
+/** Bump when the JSON shape changes in a breaking way. */
+export declare const SCHEMA_VERSION = 1;
+/** Full machine-readable report. */
+export declare function formatJson(result: ScanResult): string;
+/** Counts and grade only. */
+export declare function formatSummary(result: ScanResult): string;
+/** One line per finding: `path:line:col severity ruleId message`. */
+export declare function formatCompact(result: ScanResult): string;
+/**
+ * GitHub Actions annotations. Each finding becomes an inline comment on the
+ * diff when the workflow runs on a pull request.
+ */
+export declare function formatGithub(result: ScanResult): string;
+/**
+ * SARIF 2.1.0 document accepted by GitHub code scanning, VS Code SARIF viewer,
+ * and every other consumer of the format.
+ */
+export declare function formatSarif(result: ScanResult): string;
+/** Render `result` in the requested format. */
+export declare function formatResult(result: ScanResult, format: OutputFormat): string;
+/** Group findings by file for reporters that render trees. */
+export declare function groupByFile(findings: readonly Finding[]): Map<string, Finding[]>;

package/dist/src/reporter/formatters.js

@@ -0,0 +1,262 @@
+"use strict";
+/**
+ * vibe-shield :: machine-readable output
+ * --------------------------------------
+ * Five formats, one contract: every field the console shows is available
+ * structured, so nothing is lost when the report goes to a machine.
+ *
+ *  - `json`     the full `ScanResult` (stable, versioned by `schemaVersion`)
+ *  - `compact`  one line per finding — what CI actually needs
+ *  - `summary`  counts + grade only — for dashboards and PR comments
+ *  - `sarif`    SARIF 2.1.0 for GitHub code scanning (`--format sarif`)
+ *  - `github`   GitHub Actions workflow commands (annotations in the diff)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_VERSION = exports.isOutputFormat = exports.OUTPUT_FORMATS = void 0;
+exports.formatJson = formatJson;
+exports.formatSummary = formatSummary;
+exports.formatCompact = formatCompact;
+exports.formatGithub = formatGithub;
+exports.formatSarif = formatSarif;
+exports.formatResult = formatResult;
+exports.groupByFile = groupByFile;
+exports.OUTPUT_FORMATS = ['console', 'compact', 'summary', 'json', 'sarif', 'github'];
+const isOutputFormat = (value) => typeof value === 'string' && exports.OUTPUT_FORMATS.includes(value);
+exports.isOutputFormat = isOutputFormat;
+/** Bump when the JSON shape changes in a breaking way. */
+exports.SCHEMA_VERSION = 1;
+const SEVERITY_TO_SARIF = {
+    critical: 'error',
+    high: 'error',
+    medium: 'warning',
+    low: 'note',
+    info: 'note',
+};
+const SEVERITY_TO_GITHUB = {
+    critical: 'error',
+    high: 'error',
+    medium: 'warning',
+    low: 'notice',
+    info: 'notice',
+};
+/* -------------------------------------------------------------------------- */
+/* json / summary                                                            */
+/* -------------------------------------------------------------------------- */
+/** Full machine-readable report. */
+function formatJson(result) {
+    return `${JSON.stringify({ schemaVersion: exports.SCHEMA_VERSION, ...result }, null, 2)}\n`;
+}
+/** Counts and grade only. */
+function formatSummary(result) {
+    const payload = {
+        schemaVersion: exports.SCHEMA_VERSION,
+        command: result.command,
+        version: result.version,
+        rootDir: result.rootDir,
+        score: result.score.score,
+        grade: result.score.grade,
+        total: result.score.total,
+        counts: result.score.counts,
+        filesScanned: result.stats.filesScanned,
+        durationMs: result.stats.durationMs,
+        ruleCount: result.ruleCount,
+        suppressed: result.suppressedCount,
+        notices: result.notices,
+    };
+    return `${JSON.stringify(payload, null, 2)}\n`;
+}
+/* -------------------------------------------------------------------------- */
+/* compact                                                                   */
+/* -------------------------------------------------------------------------- */
+/** One line per finding: `path:line:col severity ruleId message`. */
+function formatCompact(result) {
+    const lines = result.findings.map((finding) => `${finding.filePath}:${finding.line}:${finding.column} ${finding.severity} ${finding.ruleId} ${finding.message.replace(/\s+/g, ' ')}`);
+    const counts = result.score.counts;
+    lines.push(`${result.score.score}/100 (${result.score.grade}) — ${counts.critical} critical, ${counts.high} high, ${counts.medium} medium, ${counts.low} low, ${counts.info} info across ${result.stats.filesScanned} ${result.stats.filesScanned === 1 ? 'file' : 'files'}`);
+    return `${lines.join('\n')}\n`;
+}
+/* -------------------------------------------------------------------------- */
+/* github actions annotations                                                */
+/* -------------------------------------------------------------------------- */
+/** Escape a value for a `::error ...::` workflow command. */
+const escapeGithubData = (value) => value.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+const escapeGithubProperty = (value) => escapeGithubData(value).replace(/:/g, '%3A').replace(/,/g, '%2C');
+/**
+ * GitHub Actions annotations. Each finding becomes an inline comment on the
+ * diff when the workflow runs on a pull request.
+ */
+function formatGithub(result) {
+    const lines = [];
+    for (const finding of result.findings) {
+        const level = SEVERITY_TO_GITHUB[finding.severity];
+        const props = [
+            `file=${escapeGithubProperty(finding.filePath)}`,
+            `line=${finding.line}`,
+            `col=${finding.column}`,
+            `title=${escapeGithubProperty(`vibe-shield ${finding.ruleId}: ${finding.title}`)}`,
+        ].join(',');
+        lines.push(`::${level} ${props}::${escapeGithubData(`${finding.message} (${finding.cwe.id})`)}`);
+    }
+    lines.push(`::notice title=vibe-shield::Scanned ${result.stats.filesScanned} files in ${result.stats.durationMs}ms — score ${result.score.score}/100 (${result.score.grade}), ${result.score.total} finding(s).`);
+    return `${lines.join('\n')}\n`;
+}
+/** CVSS-ish score so GitHub can rank the alert. */
+const securitySeverity = (severity) => {
+    switch (severity) {
+        case 'critical':
+            return '9.5';
+        case 'high':
+            return '8.1';
+        case 'medium':
+            return '5.5';
+        case 'low':
+            return '3.1';
+        default:
+            return '0.0';
+    }
+};
+/**
+ * SARIF 2.1.0 document accepted by GitHub code scanning, VS Code SARIF viewer,
+ * and every other consumer of the format.
+ */
+function formatSarif(result) {
+    const ruleMap = new Map();
+    for (const finding of result.findings) {
+        if (ruleMap.has(finding.ruleId))
+            continue;
+        ruleMap.set(finding.ruleId, {
+            id: finding.ruleId,
+            name: finding.slug.replace(/[^A-Za-z0-9]/g, '_'),
+            shortDescription: { text: finding.title },
+            fullDescription: { text: finding.message },
+            help: {
+                text: [
+                    finding.title,
+                    '',
+                    'Vulnerable:',
+                    finding.insecureExample,
+                    '',
+                    'Fixed:',
+                    finding.secureExample,
+                    '',
+                    ...finding.remediation.map((step, index) => `${index + 1}. ${step}`),
+                ].join('\n'),
+                markdown: [
+                    `**${finding.title}**`,
+                    '',
+                    '```ts',
+                    finding.insecureExample,
+                    '```',
+                    '',
+                    '**Fix**',
+                    '',
+                    ...finding.remediation.map((step) => `- ${step}`),
+                ].join('\n'),
+            },
+            defaultConfiguration: { level: SEVERITY_TO_SARIF[finding.severity] },
+            properties: {
+                tags: ['security', finding.category, finding.cwe.id, 'vibe-shield'],
+                'security-severity': securitySeverity(finding.severity),
+                precision: finding.confidence,
+                category: finding.category,
+                cwe: finding.cwe.id,
+            },
+            relationships: [{ target: { id: finding.cwe.id, toolComponent: { name: 'CWE' } } }],
+            helpUri: finding.references[0],
+        });
+    }
+    const sarif = {
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'vibe-shield',
+                        version: result.version,
+                        informationUri: 'https://github.com/avivgerz-hue/vibe-shield',
+                        semanticVersion: result.version,
+                        rules: [...ruleMap.values()],
+                    },
+                },
+                invocations: [
+                    {
+                        executionSuccessful: true,
+                        commandLine: `vibe-shield ${result.command}`,
+                        startTimeUtc: result.startedAt,
+                        endTimeUtc: result.finishedAt,
+                        properties: {
+                            score: result.score.score,
+                            grade: result.score.grade,
+                            filesScanned: result.stats.filesScanned,
+                        },
+                    },
+                ],
+                originalUriBaseIds: {
+                    '%SRCROOT%': { uri: `${result.rootDir.split('\\').join('/')}/` },
+                },
+                results: result.findings.map((finding) => ({
+                    ruleId: finding.ruleId,
+                    ruleIndex: [...ruleMap.keys()].indexOf(finding.ruleId),
+                    level: SEVERITY_TO_SARIF[finding.severity],
+                    message: { text: `${finding.message} [${finding.cwe.id}: ${finding.cwe.name}]` },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: { uri: finding.filePath, uriBaseId: '%SRCROOT%' },
+                                region: {
+                                    startLine: finding.line,
+                                    startColumn: finding.column,
+                                    endLine: finding.line,
+                                    endColumn: finding.column + Math.max(1, finding.matched.length),
+                                    snippet: { text: finding.snippet },
+                                },
+                            },
+                        },
+                    ],
+                    partialFingerprints: {
+                        'vibe-shield/v1': `${finding.ruleId}:${finding.filePath}:${finding.line}`,
+                    },
+                    properties: {
+                        severity: finding.severity,
+                        confidence: finding.confidence,
+                        cwe: finding.cwe.id,
+                        remediation: finding.remediation,
+                        secureExample: finding.secureExample,
+                    },
+                })),
+            },
+        ],
+    };
+    return `${JSON.stringify(sarif, null, 2)}\n`;
+}
+/* -------------------------------------------------------------------------- */
+/* dispatcher                                                                */
+/* -------------------------------------------------------------------------- */
+/** Render `result` in the requested format. */
+function formatResult(result, format) {
+    switch (format) {
+        case 'json':
+            return formatJson(result);
+        case 'summary':
+            return formatSummary(result);
+        case 'compact':
+            return formatCompact(result);
+        case 'sarif':
+            return formatSarif(result);
+        case 'github':
+            return formatGithub(result);
+        default:
+            throw new Error(`format "${String(format)}" is not a machine format`);
+    }
+}
+/** Group findings by file for reporters that render trees. */
+function groupByFile(findings) {
+    const map = new Map();
+    for (const finding of findings) {
+        const bucket = map.get(finding.filePath) ?? [];
+        bucket.push(finding);
+        map.set(finding.filePath, bucket);
+    }
+    return map;
+}

package/dist/src/reporter/patch-prompt-writer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * vibe-shield :: SECURITY_PATCH_PROMPT.md
+ * ---------------------------------------
+ * `--fix-prompt` writes the file an autonomous agent can *execute*. That means
+ * every finding must be self-contained: exact location, the vulnerable code,
+ * why it is exploitable, the exact replacement, and a verification command.
+ *
+ * The document is ordered by severity and grouped by file so an agent reads one
+ * file's problems, patches them, and moves on — instead of thrashing between
+ * unrelated modules.
+ */
+import type { ScanResult } from '../scanner/types';
+export declare const PATCH_PROMPT_FILENAME = "SECURITY_PATCH_PROMPT.md";
+export interface PatchPromptOptions {
+    /** File name to write (default `SECURITY_PATCH_PROMPT.md`). */
+    fileName?: string;
+    /** Skip findings below this severity. */
+    minSeverity?: 'critical' | 'high' | 'medium' | 'low' | 'info';
+    /** Maximum findings to include (0 = all). Default 200. */
+    maxFindings?: number;
+    /** Include the full rule description for each finding. */
+    verbose?: boolean;
+}
+/**
+ * Build the patch prompt document.
+ *
+ * The prompt is written *for an agent*: imperative, unambiguous, and explicit
+ * about what must not change. It ends with a self-check the agent is told to run
+ * before reporting the task as done — the same discipline `SKILL.md` enforces.
+ */
+export declare function buildPatchPrompt(result: ScanResult, options?: PatchPromptOptions): string;
+/** Write the patch prompt and return the absolute path written. */
+export declare function writePatchPrompt(result: ScanResult, options?: PatchPromptOptions & {
+    outDir?: string;
+}): Promise<string>;