@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/dist/src/report/colors.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Terminal colour, in about forty lines and zero dependencies.
+ *
+ * ANSI escape codes are just special character sequences: printing "\x1b[31m"
+ * tells the terminal "red from here", and "\x1b[0m" means "back to normal".
+ * Every colour library is a wrapper around that idea.
+ *
+ * We turn colour OFF when output is being piped into a file or another program
+ * (`process.stdout.isTTY` is false), and we honour the NO_COLOR convention,
+ * because escape codes in a log file are unreadable garbage.
+ */
+export declare const color: {
+    enabled: boolean;
+    bold: (text: string) => string;
+    dim: (text: string) => string;
+    italic: (text: string) => string;
+    underline: (text: string) => string;
+    red: (text: string) => string;
+    green: (text: string) => string;
+    yellow: (text: string) => string;
+    blue: (text: string) => string;
+    magenta: (text: string) => string;
+    cyan: (text: string) => string;
+    white: (text: string) => string;
+    gray: (text: string) => string;
+    bgRed: (text: string) => string;
+    bgYellow: (text: string) => string;
+};
+/** Word-wrap a paragraph to `width`, indenting every line after the first. */
+export declare function wrapText(text: string, width: number, indent: string): string;
+export declare function setAsciiMode(enabled: boolean): void;
+declare const GLYPHS: {
+    readonly rule: readonly ["─", "-"];
+    readonly vertical: readonly ["│", "|"];
+    readonly cornerTop: readonly ["┌", "+"];
+    readonly cornerBottom: readonly ["└", "+"];
+    readonly tick: readonly ["✓", "ok"];
+    readonly cross: readonly ["✗", "X"];
+    readonly dotFull: readonly ["●", "*"];
+    readonly dotHalf: readonly ["◐", "~"];
+    readonly dotEmpty: readonly ["○", "o"];
+    readonly middot: readonly ["·", "-"];
+    readonly arrow: readonly ["→", "->"];
+    readonly ellipsis: readonly ["…", "..."];
+    readonly warn: readonly ["⚠", "!"];
+};
+export type GlyphName = keyof typeof GLYPHS;
+/** The right spelling of a glyph for wherever this output is going. */
+export declare function g(name: GlyphName): string;
+export {};

package/dist/src/report/colors.js

@@ -0,0 +1,97 @@
+/**
+ * Terminal colour, in about forty lines and zero dependencies.
+ *
+ * ANSI escape codes are just special character sequences: printing "\x1b[31m"
+ * tells the terminal "red from here", and "\x1b[0m" means "back to normal".
+ * Every colour library is a wrapper around that idea.
+ *
+ * We turn colour OFF when output is being piped into a file or another program
+ * (`process.stdout.isTTY` is false), and we honour the NO_COLOR convention,
+ * because escape codes in a log file are unreadable garbage.
+ */
+const enabled = process.env['NO_COLOR'] === undefined &&
+    process.env['TERM'] !== 'dumb' &&
+    process.stdout.isTTY === true;
+function wrap(open, close) {
+    return (text) => (enabled ? `\x1b[${open}m${text}\x1b[${close}m` : text);
+}
+export const color = {
+    enabled,
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    italic: wrap(3, 23),
+    underline: wrap(4, 24),
+    red: wrap(31, 39),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    blue: wrap(34, 39),
+    magenta: wrap(35, 39),
+    cyan: wrap(36, 39),
+    white: wrap(37, 39),
+    gray: wrap(90, 39),
+    bgRed: wrap(41, 49),
+    bgYellow: wrap(43, 49),
+};
+/** Word-wrap a paragraph to `width`, indenting every line after the first. */
+export function wrapText(text, width, indent) {
+    const words = text.split(/\s+/).filter(Boolean);
+    const lines = [];
+    let current = '';
+    for (const word of words) {
+        if (current.length === 0) {
+            current = word;
+        }
+        else if (current.length + 1 + word.length <= width) {
+            current += ` ${word}`;
+        }
+        else {
+            lines.push(current);
+            current = word;
+        }
+    }
+    if (current)
+        lines.push(current);
+    return lines.join(`\n${indent}`);
+}
+/**
+ * BOX-DRAWING GLYPHS, AND WHY THEY NEED A FALLBACK
+ *
+ * The report uses characters like ─ ✓ ● because they read well in a terminal.
+ * They are also a portability hazard: they are multi-byte UTF-8, and the moment
+ * output leaves a UTF-8 terminal the bytes can be re-interpreted by something
+ * that assumes a legacy code page. Redirecting a scan to a file on Windows and
+ * opening it in Notepad turns every `──` into `ÔöÇÔöÇ` - the report becomes
+ * unreadable while the analysis behind it was perfectly correct.
+ *
+ * So: one table, two spellings, and a switch. ASCII is chosen automatically
+ * when output is being redirected on Windows (the case that actually breaks),
+ * and can be forced anywhere with --ascii or NS1_ASCII=1.
+ */
+let asciiMode = process.env['NS1_ASCII'] === '1' ||
+    (process.platform === 'win32' && process.stdout.isTTY !== true);
+export function setAsciiMode(enabled) {
+    asciiMode = enabled;
+}
+const GLYPHS = {
+    rule: ['\u2500', '-'],
+    vertical: ['\u2502', '|'],
+    cornerTop: ['\u250c', '+'],
+    cornerBottom: ['\u2514', '+'],
+    tick: ['\u2713', 'ok'],
+    cross: ['\u2717', 'X'],
+    dotFull: ['\u25cf', '*'],
+    dotHalf: ['\u25d0', '~'],
+    dotEmpty: ['\u25cb', 'o'],
+    middot: ['\u00b7', '-'],
+    arrow: ['\u2192', '->'],
+    ellipsis: ['\u2026', '...'],
+    // Windows PowerShell renders U+26A0 inconsistently; the ASCII fallback keeps
+    // the warning legible everywhere, which for a warning is the whole point.
+    warn: ['\u26a0', '!'],
+};
+/** The right spelling of a glyph for wherever this output is going. */
+export function g(name) {
+    const pair = GLYPHS[name];
+    return asciiMode ? pair[1] : pair[0];
+}
+//# sourceMappingURL=colors.js.map

package/dist/src/report/colors.js.map

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

package/dist/src/report/coverage-table.d.ts

@@ -0,0 +1,90 @@
+/** Opening and closing markers for a generated block in a markdown file. */
+export declare const BLOCK_START: (name: string) => string;
+export declare const BLOCK_END = "<!-- /derived -->";
+/**
+ * The rule × language coverage matrix.
+ *
+ * `Rule.support` is already a per-language honesty declaration with a REQUIRED
+ * note on every entry, printed at the end of every scan. The README's table was
+ * a second copy of it, kept by hand, and it is the copy that went stale.
+ */
+export declare function renderRuleMatrix(): string;
+/** One sentence naming the current totals, for use in running prose. */
+export declare function renderCounts(): string;
+export interface BenchmarkResult {
+    readonly scored: number;
+    readonly tp: number;
+    readonly fp: number;
+    readonly fn: number;
+    readonly tn: number;
+    readonly precision: string;
+    readonly recall: string;
+    readonly missedByCategory: Record<string, number>;
+    readonly filesParsed: number;
+    readonly parseErrors: number;
+    readonly durationMs: number;
+    /** False positives carrying BenchmarkJava's constant-branch decoy. */
+    readonly decoyFalsePositives: number;
+    readonly decoyShare: string;
+    readonly engineVersion: string;
+    readonly measuredAt: string;
+}
+/**
+ * The OWASP BenchmarkJava table.
+ *
+ * This one cannot be derived from the registry, because it is a MEASUREMENT
+ * rather than a declaration - so it is derived from the measurement instead.
+ * `npm run benchmark` writes docs/benchmark-result.json, this renders it, and
+ * the test compares the README against it. The loop closes: you cannot change
+ * the engine's score without the README either following or failing the build.
+ *
+ * The stale figures this replaced were 64.5% precision / 13.8% recall. They
+ * were honestly measured and then left behind by the Spring and JAX-RS source
+ * bindings and by declaredTypes(), which took recall to 76.4% and cost
+ * precision on the way - a real trade the old table could not show.
+ */
+export declare function renderBenchmark(result: BenchmarkResult): string;
+/** Replace the contents of one `<!-- derived:name -->` block. */
+export interface LabelSplitTier {
+    readonly label: string;
+    readonly tp: number;
+    readonly fp: number;
+    readonly fn: number;
+    readonly precision: string;
+    readonly recall: string;
+    readonly decoyFalsePositives: number;
+    readonly decoyShare: string;
+    readonly nonDecoyFalsePositives: number;
+}
+export interface LabelSplitResult {
+    readonly scored: number;
+    readonly findingsByConfidence: Record<string, number>;
+    readonly tiers: readonly LabelSplitTier[];
+    readonly engineVersion: string;
+    readonly measuredAt: string;
+}
+/**
+ * THE BLOCK THAT SCORES THE LABELS SEPARATELY.
+ *
+ * `renderBenchmark` reports one precision figure covering both labels mixed
+ * together. That figure is an average across two populations this whole tool
+ * exists to keep apart - the same blending it refuses to do inside a single
+ * finding, done one level up in the report about itself.
+ *
+ * So this renders the split, and like the benchmark block it derives its own
+ * interpretation rather than leaving a hand-written sentence to go stale
+ * underneath it. Two sentences are computed:
+ *
+ *   - whether the green label is actually worth more than the amber one, and
+ *     by how much. If a change ever made them equal, this block would say so
+ *     in the README rather than waiting for someone to notice.
+ *
+ *   - how much of the green tier's error is BenchmarkJava's synthetic decoy
+ *     rather than a real mistake. Quoting the decoy-excluded figure alone
+ *     would be picking the flattering number; quoting only the blended one
+ *     hides that the benchmark's traps dominate what is left.
+ */
+export declare function renderLabelSplit(result: LabelSplitResult): string;
+export declare function replaceBlock(markdown: string, name: string, body: string): string;
+/** Read the current contents of one block, for comparison. */
+export declare function readBlock(markdown: string, name: string): string | null;

package/dist/src/report/coverage-table.js

@@ -0,0 +1,291 @@
+/**
+ * THE README, DERIVED FROM THE REGISTRY.
+ * =====================================
+ *
+ * WHY THIS FILE EXISTS.
+ *
+ * Pointing a fresh reader at this repository produced a list of things the
+ * README asserts that the code contradicts:
+ *
+ *     README says   5 rules        registry ships   8
+ *     README says   5 languages    languages.ts     6   (PHP absent entirely)
+ *     README says   "Not SARIF"    src/report/sarif.ts is a SARIF 2.1.0 exporter
+ *     README says   13.8% recall   the scorer measures 76.4%
+ *
+ * Every one of those was true when it was written. The project simply moved and
+ * the prose did not, because the prose was a hand-maintained restatement of
+ * facts the registry already knew.
+ *
+ * THIS IS THE FOURTH TIME THIS EXACT CLASS HAS BITTEN, and the previous three
+ * are recorded elsewhere in this codebase: sources built from the frameworks we
+ * had been shown (elasticsearch), escapers likewise (Jenkins), test-path
+ * conventions likewise (cal.com). The pattern is always a list maintained by
+ * hand that looks complete until reality moves.
+ *
+ * What makes this instance the sharpest is where the stale list was. There IS a
+ * documentation-drift check in the suite, and it passed the whole time - because
+ * it greps the README for exactly one regex, the `npm test - N checks` line.
+ * A narrow instrument was trusted as a broad one. The checker itself was the
+ * hand-maintained list.
+ *
+ * So: the counts and the matrix are now GENERATED from ALL_RULES and LANGUAGES,
+ * the benchmark table is generated from the scorer's own output file, and
+ * `npm test` fails when the README disagrees with either. Prose that restates a
+ * fact the program knows is a bug waiting for a quiet afternoon.
+ */
+import { ALL_RULES } from '../rules/registry.js';
+import { LANGUAGES } from '../parse/languages.js';
+/** Opening and closing markers for a generated block in a markdown file. */
+export const BLOCK_START = (name) => `<!-- derived:${name} -->`;
+export const BLOCK_END = '<!-- /derived -->';
+const MARK = {
+    implemented: '●',
+    partial: '◐',
+    'not-implemented': '○',
+};
+const SHORT = {
+    javascript: 'JS',
+    typescript: 'TS',
+    python: 'PY',
+    java: 'JAVA',
+    php: 'PHP',
+    go: 'GO',
+};
+const columnLabel = (id) => SHORT[id] ?? id.toUpperCase();
+/**
+ * The rule × language coverage matrix.
+ *
+ * `Rule.support` is already a per-language honesty declaration with a REQUIRED
+ * note on every entry, printed at the end of every scan. The README's table was
+ * a second copy of it, kept by hand, and it is the copy that went stale.
+ */
+export function renderRuleMatrix() {
+    const languages = LANGUAGES.map((l) => l.id);
+    const header = `| Rule | CWE | OWASP | ${languages.map(columnLabel).join(' | ')} |`;
+    const divider = `|---|---|---|${languages.map(() => ':--:').join('|')}|`;
+    const rows = ALL_RULES.map((rule) => {
+        const cells = languages.map((id) => MARK[rule.support[id]?.status ?? 'not-implemented']);
+        return `| \`${rule.id}\` | ${rule.cwe} | ${rule.owasp} | ${cells.join(' | ')} |`;
+    });
+    return [
+        header,
+        divider,
+        ...rows,
+        '',
+        '● implemented  ◐ partial  ○ not implemented',
+        '',
+        `${ALL_RULES.length} rules across ${languages.length} languages. This table is generated from`,
+        '`ALL_RULES` and `LANGUAGES` by `npm run sync:readme`, and `npm test` fails if it',
+        'drifts - the counts in it are not maintained by hand.',
+    ].join('\n');
+}
+/** One sentence naming the current totals, for use in running prose. */
+export function renderCounts() {
+    const names = LANGUAGES.map((l) => l.displayName);
+    return (`**${ALL_RULES.length} rules** across **${names.length} languages** ` +
+        `(${names.join(', ')}).`);
+}
+/**
+ * The OWASP BenchmarkJava table.
+ *
+ * This one cannot be derived from the registry, because it is a MEASUREMENT
+ * rather than a declaration - so it is derived from the measurement instead.
+ * `npm run benchmark` writes docs/benchmark-result.json, this renders it, and
+ * the test compares the README against it. The loop closes: you cannot change
+ * the engine's score without the README either following or failing the build.
+ *
+ * The stale figures this replaced were 64.5% precision / 13.8% recall. They
+ * were honestly measured and then left behind by the Spring and JAX-RS source
+ * bindings and by declaredTypes(), which took recall to 76.4% and cost
+ * precision on the way - a real trade the old table could not show.
+ */
+export function renderBenchmark(result) {
+    /*
+     * THE HEADLINE IS DERIVED TOO, and that is the point of this function.
+     *
+     * The first version of this block generated the TABLE and left the sentence
+     * underneath it hand-written. That sentence read "Recall is low and that is
+     * the honest headline" - an interpretation of the OLD numbers, which went
+     * stale in the very commit that fixed the table it sat beneath. Deriving the
+     * facts and hand-keeping their meaning just moves the drift one line down.
+     *
+     * So the weak side is computed. More false positives than false negatives
+     * means precision is where the tool is worst; the reverse means recall is.
+     * Whichever it is, the README says it because the arithmetic said it.
+     */
+    const precisionIsWeaker = result.fp > result.fn;
+    const ratio = (Math.max(result.fp, result.fn) / Math.max(1, Math.min(result.fp, result.fn)))
+        .toFixed(1);
+    /*
+     * A ZERO IS NOT A RATIO. When the hunt for BenchmarkJava's 38 misses took
+     * false negatives to 0, this sentence printed "271 false positives against 0
+     * false negatives - 271.0x as many": arithmetic on a divide-by-one guard,
+     * dressed up as a measurement. A zero is said in words, and so is its limit:
+     * no misses HERE is a fact about these 1,210 test cases, not about your code.
+     */
+    const scope = 'That is a statement about these scored test cases, not about code in general - ' +
+        'the limitations list is where the misses this benchmark cannot show are written down.';
+    const headline = result.fn === 0 && result.fp > 0
+        ? `**Precision is the weak side.** ${result.fp} false positives and no false ` +
+            `negatives, so on this benchmark the cost of this engine is triage time, not ` +
+            `missed bugs. ${scope}`
+        : result.fp === 0 && result.fn > 0
+            ? `**Recall is the weak side.** ${result.fn} false negatives and no false ` +
+                `positives, so on this benchmark the cost of this engine is missed bugs, not ` +
+                `triage time. ${scope}`
+            : precisionIsWeaker
+                ? `**Precision is the weaker side.** ${result.fp} false positives against ` +
+                    `${result.fn} false negatives - ${ratio}x as many - so the cost of this engine ` +
+                    `is triage time, not missed bugs.`
+                : `**Recall is the weaker side.** ${result.fn} false negatives against ` +
+                    `${result.fp} false positives - ${ratio}x as many - so the cost of this engine ` +
+                    `is missed bugs, not triage time.`;
+    const missed = Object.entries(result.missedByCategory);
+    return [
+        '| | cases | TP | FP | FN | TN | precision | recall |',
+        '|---|--:|--:|--:|--:|--:|--:|--:|',
+        `| **overall** | **${result.scored}** | **${result.tp}** | **${result.fp}** | ` +
+            `**${result.fn}** | **${result.tn}** | **${result.precision}** | **${result.recall}** |`,
+        '',
+        `${result.filesParsed} files, ${result.parseErrors} parse errors, ` +
+            `${(result.durationMs / 1000).toFixed(1)} seconds, on engine ${result.engineVersion} ` +
+            `(${result.measuredAt}).`,
+        '',
+        headline,
+        '',
+        (missed.length > 0
+            ? `Missed by category: ${missed.map(([k, v]) => `${k} ${v}`).join(', ')}. `
+            : 'Nothing was missed in the scored categories. ') +
+            `Of the ${result.fp} false positives, **${result.decoyFalsePositives} ` +
+            `(${result.decoyShare})** carry the shape of BenchmarkJava's constant-branch decoy - ` +
+            `a condition like \`if ((7 * 42) - num > 200)\`. The data-flow pass, the SQL rule ` +
+            `and the command-injection rule all decide such a condition, so the shape alone ` +
+            `explains none of them: every false positive here is ours.`,
+        '',
+        'Every number above is generated by `npm run benchmark` into',
+        '`docs/benchmark-result.json` - including the sentence naming the weaker side,',
+        'because an interpretation kept by hand goes stale exactly like a figure does.',
+    ].join('\n');
+}
+/**
+ * THE BLOCK THAT SCORES THE LABELS SEPARATELY.
+ *
+ * `renderBenchmark` reports one precision figure covering both labels mixed
+ * together. That figure is an average across two populations this whole tool
+ * exists to keep apart - the same blending it refuses to do inside a single
+ * finding, done one level up in the report about itself.
+ *
+ * So this renders the split, and like the benchmark block it derives its own
+ * interpretation rather than leaving a hand-written sentence to go stale
+ * underneath it. Two sentences are computed:
+ *
+ *   - whether the green label is actually worth more than the amber one, and
+ *     by how much. If a change ever made them equal, this block would say so
+ *     in the README rather than waiting for someone to notice.
+ *
+ *   - how much of the green tier's error is BenchmarkJava's synthetic decoy
+ *     rather than a real mistake. Quoting the decoy-excluded figure alone
+ *     would be picking the flattering number; quoting only the blended one
+ *     hides that the benchmark's traps dominate what is left.
+ */
+export function renderLabelSplit(result) {
+    const pct = (s) => Number.parseFloat(s);
+    const verified = result.tiers.find((t) => t.label.startsWith('flow-verified'));
+    const signature = result.tiers.find((t) => t.label.startsWith('signature-only'));
+    const rows = result.tiers.map((t) => `| \`${t.label}\` | ${t.tp} | ${t.fp} | ${t.fn} | **${t.precision}** | ${t.recall} | ` +
+        `${t.decoyFalsePositives} (${t.decoyShare}) |`);
+    const lines = [
+        '| tier | TP | FP | FN | precision | recall | FPs that are decoys |',
+        '|---|--:|--:|--:|--:|--:|--:|',
+        ...rows,
+        '',
+        `${Object.entries(result.findingsByConfidence)
+            .map(([k, v]) => `${v} \`${k}\``)
+            .join(', ')} findings, on engine ${result.engineVersion} (${result.measuredAt}).`,
+        '',
+    ];
+    if (verified && signature) {
+        const gap = pct(verified.precision) - pct(signature.precision);
+        lines.push(gap > 0
+            ? `**The green label is worth ${gap.toFixed(1)} points.** \`flow-verified\` runs ` +
+                `${verified.precision} against \`signature-based\` at ${signature.precision}. The ` +
+                `gap is the whole claim this tool makes; it is measured here rather than asserted.`
+            : `**The labels are not separating.** \`flow-verified\` runs ${verified.precision} ` +
+                `against \`signature-based\` at ${signature.precision}, so the green label is ` +
+                `currently buying nothing. That is a defect, not a footnote.`);
+        lines.push('');
+        const real = verified.tp + verified.nonDecoyFalsePositives;
+        const excl = real === 0 ? 0 : (verified.tp / real) * 100;
+        /*
+         * TWO SENTENCES, AND WHICH ONE IS TRUE IS NOT OURS TO CHOOSE.
+         *
+         * For a long time the green label carried a large pile of the benchmark's
+         * constant-branch decoys, so the honest thing was to print the headline AND
+         * the decoy-excluded figure, and to say plainly that neither alone was the
+         * truth.
+         *
+         * Then constant-condition evaluation landed and the decoys went to zero.
+         * Keeping the old paragraph would have had the page arguing for a
+         * distinction between two numbers that are now identical - drift caused by
+         * an improvement, which is the sneakiest kind, because nothing failed and
+         * the prose simply stopped being about anything.
+         *
+         * So the branch is derived from the measurement, like every other sentence
+         * in this file. If decoys ever come back, so does the caveat.
+         */
+        if (verified.fp === 0) {
+            /*
+             * Zero is said in words, and so is its limit - the same rule the benchmark
+             * block follows for zero false negatives. "0 ordinary mistakes out of 456"
+             * would be arithmetic dressed as a boast.
+             */
+            lines.push(`**No false positive carries the green label here.** All ${verified.tp} ` +
+                `\`flow-verified\` claims on this benchmark are real vulnerabilities. That is a ` +
+                `statement about these scored test cases, not a promise about your code: a proof ` +
+                `means the path exists in the source, and the ways that can still be wrong are ` +
+                `the ones in the limitations list, which a synthetic benchmark does not exercise.`);
+        }
+        else if (verified.decoyFalsePositives === 0) {
+            lines.push(`**There is no footnote any more.** Not one of the ${verified.fp} false positives ` +
+                `still carrying the green label is a constant-branch decoy. Until constant ` +
+                `conditions were evaluated, that pile was most of them, and this paragraph had to ` +
+                `print two precision figures and explain why neither alone was the truth. ` +
+                `\`flow-verified\` now reads **${excl.toFixed(1)}%** with nothing set aside and ` +
+                `nothing excluded - ${verified.nonDecoyFalsePositives} ordinary mistakes out of ` +
+                `${verified.tp + verified.fp} claims.`);
+        }
+        else {
+            lines.push(`Of the ${verified.fp} false positives still carrying the green label, ` +
+                `**${verified.decoyFalsePositives} (${verified.decoyShare})** are BenchmarkJava's ` +
+                `constant-branch decoy - a path that genuinely exists inside a branch that cannot ` +
+                `run - leaving **${verified.nonDecoyFalsePositives}** that are ordinary mistakes. ` +
+                `Set the decoys aside and \`flow-verified\` precision is **${excl.toFixed(1)}%**. ` +
+                `Both figures are printed because neither alone is the truth: the first is ` +
+                `contaminated by synthetic traps, the second requires excluding cases, and a ` +
+                `reader deserves to see the size of that choice rather than inherit it.`);
+        }
+    }
+    return lines.join('\n');
+}
+export function replaceBlock(markdown, name, body) {
+    const start = BLOCK_START(name);
+    const from = markdown.indexOf(start);
+    if (from === -1)
+        throw new Error(`README has no block named "${name}"`);
+    const to = markdown.indexOf(BLOCK_END, from);
+    if (to === -1)
+        throw new Error(`block "${name}" is not closed with ${BLOCK_END}`);
+    return (markdown.slice(0, from + start.length) + '\n' + body + '\n' + markdown.slice(to));
+}
+/** Read the current contents of one block, for comparison. */
+export function readBlock(markdown, name) {
+    const start = BLOCK_START(name);
+    const from = markdown.indexOf(start);
+    if (from === -1)
+        return null;
+    const to = markdown.indexOf(BLOCK_END, from);
+    if (to === -1)
+        return null;
+    return markdown.slice(from + start.length, to).trim();
+}
+//# sourceMappingURL=coverage-table.js.map

package/dist/src/report/coverage-table.js.map

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

package/dist/src/report/html-report.d.ts

@@ -0,0 +1,66 @@
+/**
+ * THE CLIENT REPORT
+ * =================
+ *
+ * The terminal report is for the person who ran the scan. This one is for the
+ * person who did not: a project owner who will read it once, possibly printed,
+ * and decide what to do. It is one self-contained HTML file - no script, no
+ * stylesheet or font fetched from anywhere, the mark drawn inline - so it can
+ * be emailed, opened offline and printed to PDF from any browser.
+ *
+ * It says the same things the terminal does, in the same order of trust:
+ *
+ *   1. what was PROVEN, each with the path that proves it;
+ *   2. what was only MATCHED, said plainly to be unproven;
+ *   3. what was checked and CLEARED, with the reason;
+ *   4. what was NOT CHECKED at all.
+ *
+ * The fourth section is not an appendix to skip. A report that lists problems
+ * and stays silent about what it never looked at invites the reader to treat
+ * "not listed" as "fine" - the exact failure this tool exists to avoid - and a
+ * client report is where that misreading costs the most.
+ *
+ * Two labels, never blended: a proven finding is a filled dot, a guess a
+ * hollow ring, so the difference survives a black-and-white printer. The
+ * mark's purple is used on the mark and the name only.
+ *
+ * PLATFORM-FREE ON PURPOSE: string in, string out, no Node imports, so the
+ * browser UI can produce the same file from the same engine.
+ *
+ * EVERY PIECE OF TEXT FROM THE SCANNED CODE IS ESCAPED. A snippet is whatever
+ * the scanned project contains, and a report that rendered it as markup would
+ * be an XSS vector aimed at the person reading a security report. The test
+ * suite feeds it a hostile snippet to make sure.
+ */
+import type { ScanResult } from '../engine/scan.js';
+export interface HtmlReportOptions {
+    /** Shown as the project name. Defaults to the last segment of the target path. */
+    readonly projectName?: string;
+    /** Optional: the person or firm who ran the scan and reviewed the report. */
+    readonly preparedBy?: string;
+    /**
+     * Optional: one line printed under the header - that this is a sample, a
+     * draft, or which branch was scanned. Escaped like every other string here.
+     */
+    readonly note?: string;
+    /** When the scan ran. Passed in so the output is reproducible in tests. */
+    readonly generatedAt: Date;
+    /**
+     * The scanned folder as the finding paths spell it. The CLI writes paths
+     * relative to where it was run (`corpus/app/views.py`) while the target is
+     * absolute, so both prefixes are stripped to show `views.py`'s place in the
+     * project rather than on the scanning machine.
+     */
+    readonly root?: string;
+    /**
+     * Anything the shell that gathered the files left out on its own terms -
+     * the browser reads at most 4,000 files and none over 2 MB. Printed in
+     * section 4, because a file that never reached the engine is a gap the
+     * engine cannot report by itself.
+     */
+    readonly intake?: string;
+}
+/** Escape for HTML text and attribute values. Everything from the scan goes through this. */
+export declare function escapeHtml(text: string): string;
+export declare function maskSecretLiterals(snippet: string): string;
+export declare function renderHtmlReport(result: ScanResult, options: HtmlReportOptions): string;