@safegres/test 0.0.1 → 1.30.7

package/esm/report/pretty.js

@@ -0,0 +1,318 @@
+import yanse from 'yanse';
+import { renderCallGraph, renderCallGraphDiff } from './callgraph';
+import { baselineLabel, describeBaseline, formatDelta } from './compare';
+import { selectView } from './view';
+const SEV_LABEL = {
+    critical: 'CRIT',
+    high: 'HIGH',
+    medium: 'MED ',
+    low: 'LOW ',
+    info: 'INFO'
+};
+const SEV_PAINT = {
+    critical: (s) => yanse.bold(yanse.red(s)),
+    high: yanse.red,
+    medium: yanse.yellow,
+    low: yanse.cyan,
+    info: yanse.gray
+};
+const noop = (s) => s;
+export function renderPretty(report, options = {}) {
+    const colorEnabled = options.color ?? process.stdout.isTTY === true;
+    const paint = (sev, s) => (colorEnabled ? SEV_PAINT[sev](s) : noop(s));
+    const view = selectView(report, {
+        detail: options.summary ? 'summary' : options.verbose ? 'verbose' : 'normal',
+        ...(options.planes ? { planes: options.planes } : {}),
+        ...options.view
+    });
+    const verbose = view.detail === 'verbose';
+    const { summary: s, score, exposure } = report;
+    const lines = [
+        `safegres ${report.version}  (${report.generatedAt})`,
+        ...(report.provenance?.sealed
+            ? [`sealed: ${report.provenance.preset ?? 'recommended'}  ${report.provenance.fingerprint}`]
+            : []),
+        ''
+    ];
+    if (exposure) {
+        if (exposure.known) {
+            lines.push(`exposure: ${exposure.schemas.length} schema(s) via ${exposure.source}`
+                + `  — ${exposure.exposedTables}/${exposure.totalTables} tables exposed`);
+            if (exposure.roles && exposure.roles.length > 0) {
+                // Marking the anonymous ones answers the question a reader actually
+                // has: which of these does a caller reach with no credentials?
+                const anon = new Set(exposure.anonRoles ?? []);
+                const roles = exposure.roles.map((r) => (anon.has(r) ? `${r} (anon)` : r));
+                lines.push(`  api roles: ${roles.join(', ')}`);
+            }
+            if (exposure.unaddressable && exposure.unaddressable.length > 0) {
+                lines.push(`  ${exposure.unaddressable.length} relation(s) in those schemas the API cannot address: `
+                    + exposure.unaddressable.map((r) => `${r.schema}.${r.table}`).join(', '));
+            }
+        }
+        else {
+            lines.push(paint('medium', 'exposure: unknown — entire database assumed reachable (score capped)'));
+        }
+        lines.push('');
+    }
+    if (score) {
+        lines.push(...scoreLines('score', score, colorEnabled));
+        if (report.comparison?.security) {
+            lines.push(`  ${deltaLine(report.comparison.security, baselineLabel(report.comparison.previous), colorEnabled)}`);
+        }
+        lines.push('');
+    }
+    if (report.perf) {
+        lines.push(...scoreLines('perf score', report.perf.score, colorEnabled));
+        if (report.comparison?.perf) {
+            lines.push(`  ${deltaLine(report.comparison.perf, baselineLabel(report.comparison.previous), colorEnabled)}`);
+        }
+        lines.push('');
+    }
+    if (view.has('scorecards')) {
+        lines.push(...scorecardLines(view, colorEnabled), '');
+    }
+    if (view.has('planes')) {
+        lines.push(...planeLines(view, colorEnabled), '');
+    }
+    lines.push(`summary: ${paint('critical', String(s.critical))} critical  `
+        + `${paint('high', String(s.high))} high  `
+        + `${paint('medium', String(s.medium))} medium  `
+        + `${paint('low', String(s.low))} low  `
+        + `${paint('info', String(s.info))} info`);
+    // Which run the Δ above is against, or why there is none — a delta whose
+    // baseline the reader cannot see is a number they cannot check.
+    if (report.comparison) {
+        lines.push(`baseline: ${describeBaseline(report.comparison.previous, { link: false })}`);
+    }
+    else if (report.comparisonSkipped) {
+        lines.push(`no delta baseline: ${report.comparisonSkipped}`
+            + ' (absolute score and the perf baseline still gate this run)');
+    }
+    // --summary: score + counts only, no per-finding lines.
+    if (view.detail === 'summary') {
+        if (report.callGraph) {
+            lines.push('', renderCallGraph(report.callGraph, { color: colorEnabled, summary: true }));
+        }
+        if (report.callGraphDiff) {
+            lines.push('', renderCallGraphDiff(report.callGraphDiff, { color: colorEnabled }));
+        }
+        return lines.join('\n');
+    }
+    lines.push('');
+    // Perf findings render in their own section so the two dimensions never
+    // read as one list.
+    const { exposed, internal } = view.security;
+    for (const f of exposed) {
+        lines.push(renderFinding(f, paint));
+    }
+    if (internal.length > 0) {
+        // Collapse internal advisories to a count by default; --verbose lists them.
+        if (verbose) {
+            lines.push('', `internal advisories (${internal.length}) — not exposed via any API, excluded from the score:`, '');
+            for (const f of internal) {
+                lines.push(renderFinding(f, paint));
+            }
+        }
+        else {
+            lines.push('', paint('info', `internal advisories (${internal.length}) — not exposed via any API, `
+                + 'excluded from the score; run with --verbose to list.'));
+        }
+    }
+    if (exposed.length + internal.length === 0) {
+        lines.push('no findings.');
+    }
+    if (report.roleAccess && report.roleAccess.roles.length > 0) {
+        lines.push('', 'role access — effective grants (direct, PUBLIC, inherited):', '');
+        for (const entry of report.roleAccess.roles) {
+            lines.push(`  ${entry.role}: ${entry.accessibleTables} relation(s) accessible — `
+                + `${entry.unmediated.length} unmediated (no RLS), ${entry.mediated} policy-mediated`
+                + `${entry.dead > 0 ? `, ${entry.dead} dead (RLS default-deny)` : ''}`);
+            const shown = verbose ? entry.unmediated : entry.unmediated.slice(0, 20);
+            for (const r of shown) {
+                lines.push(paint('medium', `    ${r.schema}.${r.table}  ${r.privileges.join(', ')}`
+                    + `${r.columns ? ` on (${r.columns.join(', ')})` : ''}  (via ${r.via})`));
+            }
+            if (shown.length < entry.unmediated.length) {
+                lines.push(paint('info', `    … ${entry.unmediated.length - shown.length} more — run with --verbose to list.`));
+            }
+        }
+    }
+    if (report.perf?.diff) {
+        const { added, removed, accepted } = report.perf.diff;
+        lines.push('', 'performance vs baseline:', '');
+        if (added.length === 0) {
+            lines.push(`no new perf debt (${accepted.length} accepted, ${removed.length} fixed).`);
+        }
+        else {
+            lines.push(paint('high', `${added.length} new perf finding${added.length === 1 ? '' : 's'} since the baseline:`));
+            for (const f of added)
+                lines.push(renderFinding(f, paint));
+            lines.push(paint('info', `  (${accepted.length} accepted, ${removed.length} fixed)`));
+        }
+        if (removed.length > 0) {
+            lines.push(paint('info', `  fixed since the baseline: ${removed.map((r) => `${r.code} ${r.schema}.${r.table}`).join(', ')} — re-baseline to lock the win in`));
+        }
+    }
+    if (report.perf) {
+        const perfExposed = report.perf.findings.filter((f) => f.exposed !== false);
+        const perfInternal = report.perf.findings.length - perfExposed.length;
+        lines.push('', 'performance (index hygiene) — scored separately from security:', '');
+        if (perfExposed.length === 0) {
+            lines.push('no perf findings.');
+        }
+        else {
+            for (const f of perfExposed)
+                lines.push(renderFinding(f, paint));
+        }
+        if (perfInternal > 0 && !verbose) {
+            lines.push(paint('info', `  (${perfInternal} internal perf advisor${perfInternal === 1 ? 'y' : 'ies'} excluded from the perf score)`));
+        }
+        else if (perfInternal > 0) {
+            for (const f of report.perf.findings.filter((f) => f.exposed === false)) {
+                lines.push(renderFinding(f, paint));
+            }
+        }
+        const { paths, stats, explain } = report.perf;
+        if (paths && paths.writeOnceShaped > 0) {
+            const acted = { report: 'reported', demote: 'demoted to info', suppress: 'suppressed' }[paths.onWriteOncePointer];
+            lines.push(paint('info', `  access paths: ${paths.total} foreign keys — ${paths.read} read by a policy or view, `
+                + `${paths.writeOnceShaped} on ${paths.tables} tables write-once shaped (X1 ${acted})`));
+        }
+        if (stats) {
+            lines.push(paint('info', `  runtime statistics: ${stats.tables} tables, counters since ${stats.statsReset ?? 'server start'}`
+                + `${stats.scored ? '' : ' (S* findings advisory — perf.scoring.includeStats is false)'}`));
+            for (const note of stats.notes ?? [])
+                lines.push(paint('info', `  ${note}`));
+        }
+        if (explain) {
+            lines.push(paint('info', explain.unavailable
+                ?? `  planner proof: ${explain.confirmed} confirmed, ${explain.refuted} refuted, ${explain.inconclusive} inconclusive of ${explain.probed} probed`));
+        }
+    }
+    if (report.callGraph) {
+        lines.push('', renderCallGraph(report.callGraph, { color: colorEnabled }));
+    }
+    if (report.callGraphDiff) {
+        lines.push('', renderCallGraphDiff(report.callGraphDiff, { color: colorEnabled }));
+    }
+    return lines.join('\n');
+}
+/**
+ * The other named scores. One line each: the headline answers the question
+ * the preset was written for, and these answer the ones a particular team
+ * actually gates on. `raw` sits among them deliberately — a number no
+ * configuration softened, next to the one that was.
+ */
+function scorecardLines(view, colorEnabled) {
+    const lines = ['scorecards — the same findings, scored by question:'];
+    for (const card of view.scorecards) {
+        const grade = colorEnabled
+            ? gradePaintFor(card.score)(`${card.score.value} (${card.score.grade})`)
+            : `${card.score.value} (${card.score.grade})`;
+        lines.push(`  ${card.name}: ${grade}  — ${card.findings} finding(s)`
+            + (card.description ? `  ${card.description}` : ''));
+    }
+    return lines;
+}
+/**
+ * Secondary planes: one line each, because they are not the headline. The
+ * primary score answers "how safe is the product"; these answer "and what if
+ * somebody doesn't come through it" — worth seeing, not worth competing with
+ * the number the team is being graded on. `--plane <name>` expands one.
+ */
+function planeLines(view, colorEnabled) {
+    const lines = ['other access planes — advisory, not part of the score above:'];
+    for (const plane of view.planes) {
+        lines.push(`  ${planeLine(plane, colorEnabled)}`);
+    }
+    for (const plane of view.expandedPlanes) {
+        if (plane.skipped)
+            continue;
+        lines.push('', `plane ${plane.name}:`, ...scoreLines('  score', plane.score, colorEnabled));
+    }
+    if (view.expandedPlanes.length === 0 && view.planes.some((p) => !p.skipped)) {
+        lines.push('  (run with --plane <name> to expand one, or --plane \'*\' for all)');
+    }
+    return lines;
+}
+function planeLine(plane, colorEnabled) {
+    const who = plane.roles && plane.roles.length > 0
+        ? ` (${plane.roles.join(', ')})`
+        : plane.schemas.length > 0
+            ? ` (${plane.schemas.join(', ')})`
+            : '';
+    if (plane.skipped)
+        return `${plane.name}${who}: not graded — ${plane.skipped}`;
+    const grade = colorEnabled ? gradePaintFor(plane.score)(`${plane.score.value} (${plane.score.grade})`) : `${plane.score.value} (${plane.score.grade})`;
+    const via = plane.reachedVia ? `, reached via ${plane.reachedVia}` : '';
+    return `${plane.name} [${plane.kind}]${who}: ${grade}`
+        + `  — ${plane.exposedTables} relation(s)${via}`;
+}
+function gradePaintFor(score) {
+    if (score.grade.startsWith('A'))
+        return yanse.green;
+    return score.grade === 'B' || score.grade === 'C' ? yanse.yellow : yanse.red;
+}
+function scoreLines(label, score, colorEnabled) {
+    const gradePaint = colorEnabled ? gradePaintFor(score) : noop;
+    const capNote = score.cappedByUnknownExposure ? '  (capped: exposure unknown)' : '';
+    const lines = [
+        `${label}: ${gradePaint(`${score.value} (${score.grade})`)}  — model: ${score.model}${capNote}`
+    ];
+    const scored = score.deductions.filter((d) => !d.unscored);
+    const top = scored.slice(0, 3);
+    if (top.length > 0) {
+        lines.push(`  top deductions: ${top.map(deductionLabel).join('  ')}`);
+        // Payoff, not points: what the score becomes if the rule goes to zero.
+        lines.push(`  by rule: ${scored
+            .map((d) => `${d.code} ${d.grade} (+${d.potential.toFixed(1)})`)
+            .join('  ')}`);
+    }
+    const capped = scored.filter((d) => d.capped);
+    if (capped.length > 0) {
+        lines.push(`  capped: ${capped.map((d) => d.code).join(', ')}`
+            + '  — one rule cannot decide the grade; the finding count is unchanged');
+    }
+    const unscored = score.deductions.filter((d) => d.unscored);
+    if (unscored.length > 0) {
+        lines.push(`  unscored: ${unscored.map((d) => `${d.code} (×${d.count})`).join('  ')}`
+            + '  — zero-weight, fixing these cannot move the score');
+    }
+    return lines;
+}
+/**
+ * `L19 −664 (×568 → 166 fixes)` — the finding count and what it costs to
+ * clear are different numbers, and only the second one is charged.
+ */
+function deductionLabel(d) {
+    const count = d.units === undefined
+        ? `×${d.count}`
+        : `×${d.count} → ${d.units} fix${d.units === 1 ? '' : 'es'}`;
+    return `${d.code} −${d.points} (${count})`;
+}
+function deltaLine(d, ref, colorEnabled) {
+    const since = ref ? ` vs ${ref}` : ' vs previous run';
+    const arrow = d.delta > 0 ? '▲' : d.delta < 0 ? '▼' : '=';
+    // Same convention as the markdown report: green is the direction you want.
+    const paint = (better, s) => colorEnabled ? (better ? yanse.green(s) : yanse.red(s)) : s;
+    const movement = `${arrow} ${formatDelta(d.delta, 1)}`;
+    const score = d.delta === 0 ? movement : paint(d.delta > 0, movement);
+    const grade = d.gradeBefore === d.gradeAfter ? '' : `, ${d.gradeBefore} → ${d.gradeAfter}`;
+    const findingMove = `${d.findingsBefore} → ${d.findingsAfter}`;
+    const findings = d.findingsAfter === d.findingsBefore
+        ? findingMove
+        : paint(d.findingsAfter < d.findingsBefore, findingMove);
+    return `Δ${since}: ${score} (from ${d.before}${grade})  findings ${findings}`;
+}
+function renderFinding(f, paint) {
+    const label = paint(f.severity, SEV_LABEL[f.severity]);
+    const loc = [f.schema, f.table].filter(Boolean).join('.') + (f.policy ? `  (${f.policy})` : '');
+    const head = `[${label}] ${f.code}  ${loc}`;
+    const body = `    ${f.message}`;
+    const hint = f.hint ? `    hint: ${f.hint}` : '';
+    const evidence = f.evidence
+        ? `    plan (${f.evidence.status}): ${f.evidence.plan}${f.evidence.note ? ` — ${f.evidence.note}` : ''}`
+        : '';
+    return [head, body, hint, evidence].filter(Boolean).join('\n');
+}

package/esm/report/sarif.d.ts

@@ -0,0 +1,40 @@
+/**
+ * SARIF 2.1.0 rendering (`--format sarif`), so findings land in GitHub code
+ * scanning (Security tab + inline PR annotations) instead of only in a log.
+ *
+ * A code-scanning alert is a *file and a line*, but safegres reads the
+ * catalog — a live database has no source location. `buildSourceIndex()`
+ * closes that gap by scanning the SQL that produced the database
+ * (pgpm deploy scripts, migrations) for the `CREATE TABLE` / `CREATE POLICY`
+ * that defines each object, so `app_public.widgets` resolves to the line that
+ * created it. Findings that don't resolve are still emitted, without a
+ * location: GitHub drops those from the Security tab, but any other SARIF
+ * consumer keeps them, and the JSON format carries everything regardless.
+ */
+import type { Report } from '../types';
+export interface SourceLocation {
+    /** Repo-relative POSIX path, as GitHub expects it. */
+    file: string;
+    line: number;
+}
+/** `schema.table` → definition site, plus `schema.table:policy` for policies. */
+export type SourceIndex = Map<string, SourceLocation>;
+export interface RenderSarifOptions {
+    /** Definition sites for relations and policies (see `buildSourceIndex`). */
+    sources?: SourceIndex;
+    /** Absolute URI of the scanned repository root, if known. */
+    repoRoot?: string;
+}
+export declare function renderSarif(report: Report, options?: RenderSarifOptions): string;
+export interface BuildSourceIndexOptions {
+    /** Directory names to skip. Defaults to node_modules, .git, dist. */
+    skipDirs?: string[];
+    /** Paths in the index are relative to this. Defaults to `dir`. */
+    root?: string;
+}
+/**
+ * Scan a directory tree of `.sql` files for the statements that define the
+ * objects safegres reports on. First definition wins: a pgpm module deploys a
+ * table once, and a later `ALTER` is not where a reviewer wants the alert.
+ */
+export declare function buildSourceIndex(dir: string, options?: BuildSourceIndexOptions): SourceIndex;

package/esm/report/sarif.js

@@ -0,0 +1,189 @@
+/**
+ * SARIF 2.1.0 rendering (`--format sarif`), so findings land in GitHub code
+ * scanning (Security tab + inline PR annotations) instead of only in a log.
+ *
+ * A code-scanning alert is a *file and a line*, but safegres reads the
+ * catalog — a live database has no source location. `buildSourceIndex()`
+ * closes that gap by scanning the SQL that produced the database
+ * (pgpm deploy scripts, migrations) for the `CREATE TABLE` / `CREATE POLICY`
+ * that defines each object, so `app_public.widgets` resolves to the line that
+ * created it. Findings that don't resolve are still emitted, without a
+ * location: GitHub drops those from the Security tab, but any other SARIF
+ * consumer keeps them, and the JSON format carries everything regardless.
+ */
+import { readdirSync, readFileSync, statSync } from 'fs';
+import { join, relative, sep } from 'path';
+import { findingKey, subjectOf } from '../perf/baseline';
+import { dimensionOf, RULES } from '../rules/registry';
+const SARIF_VERSION = '2.1.0';
+const SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
+/** SARIF has three visible levels; five severities have to fold into them. */
+const LEVEL = {
+    critical: 'error',
+    high: 'error',
+    medium: 'warning',
+    low: 'note',
+    info: 'note'
+};
+/**
+ * GitHub reads `security-severity` (a CVSS-shaped number) to bucket an alert
+ * as critical/high/medium/low in the Security tab.
+ */
+const SECURITY_SEVERITY = {
+    critical: '9.0',
+    high: '7.0',
+    medium: '5.0',
+    low: '3.0',
+    info: '1.0'
+};
+export function renderSarif(report, options = {}) {
+    const findings = report.findings;
+    const emitted = new Set(findings.map((f) => f.code));
+    const sarif = {
+        $schema: SCHEMA,
+        version: SARIF_VERSION,
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'safegres',
+                        informationUri: 'https://github.com/constructive-io/constructive/tree/main/packages/safegres',
+                        semanticVersion: report.version,
+                        version: report.version,
+                        rules: RULES.filter((r) => emitted.has(r.code)).map((rule) => ({
+                            id: rule.code,
+                            name: rule.code,
+                            shortDescription: { text: rule.title },
+                            fullDescription: { text: rule.title },
+                            defaultConfiguration: { level: LEVEL[rule.defaultSeverity] },
+                            properties: {
+                                tags: [
+                                    dimensionOf(rule) === 'perf' ? 'performance' : 'security',
+                                    rule.category,
+                                    rule.direction
+                                ],
+                                'security-severity': SECURITY_SEVERITY[rule.defaultSeverity]
+                            }
+                        }))
+                    }
+                },
+                // Scores have nowhere to live in a SARIF result, so they ride along as
+                // run properties — enough for a consumer to gate on.
+                properties: {
+                    generatedAt: report.generatedAt,
+                    ...(report.score ? { score: report.score.value, grade: report.score.grade } : {}),
+                    ...(report.perf ? { perfScore: report.perf.score.value, perfGrade: report.perf.score.grade } : {})
+                },
+                results: findings.map((finding) => result(finding, options))
+            }
+        ]
+    };
+    return JSON.stringify(sarif, null, 2);
+}
+function result(finding, options) {
+    const location = resolve(finding, options.sources);
+    const relation = [finding.schema, finding.table].filter(Boolean).join('.');
+    return {
+        ruleId: finding.code,
+        level: LEVEL[finding.severity],
+        message: { text: relation ? `${relation}: ${finding.message}` : finding.message },
+        ...(location
+            ? {
+                locations: [
+                    {
+                        physicalLocation: {
+                            artifactLocation: {
+                                uri: location.file,
+                                ...(options.repoRoot ? { uriBaseId: '%SRCROOT%' } : {})
+                            },
+                            region: { startLine: location.line }
+                        }
+                    }
+                ]
+            }
+            : { locations: [] }),
+        // Identity, not text: the same key the perf baseline uses, so rewording a
+        // rule doesn't resolve-and-reopen every alert.
+        partialFingerprints: {
+            safegresFindingKey: findingKey({
+                code: finding.code,
+                schema: finding.schema,
+                table: finding.table,
+                policy: finding.policy,
+                subject: subjectOf(finding)
+            })
+        },
+        properties: {
+            severity: finding.severity,
+            category: finding.category,
+            dimension: finding.dimension ?? 'security',
+            ...(finding.direction ? { direction: finding.direction } : {}),
+            ...(finding.exposed === undefined ? {} : { exposed: finding.exposed }),
+            ...(finding.acknowledged ? { acknowledged: true } : {}),
+            ...(finding.policy ? { policy: finding.policy } : {}),
+            ...(finding.role ? { role: finding.role } : {}),
+            ...(finding.hint ? { hint: finding.hint } : {})
+        }
+    };
+}
+/** Policy site first — it's the precise line — then the table that owns it. */
+function resolve(finding, sources) {
+    if (!sources || !finding.schema || !finding.table)
+        return undefined;
+    const relation = `${finding.schema}.${finding.table}`;
+    if (finding.policy) {
+        const policy = sources.get(`${relation}:${finding.policy}`);
+        if (policy)
+            return policy;
+    }
+    return sources.get(relation);
+}
+const CREATE_TABLE = /^\s*create\s+(?:unlogged\s+|temp\w*\s+)?table\s+(?:if\s+not\s+exists\s+)?("?[\w$]+"?)\.("?[\w$]+"?)/i;
+const CREATE_POLICY = /^\s*create\s+policy\s+("?[\w$]+"?)\s+on\s+("?[\w$]+"?)\.("?[\w$]+"?)/i;
+/**
+ * Scan a directory tree of `.sql` files for the statements that define the
+ * objects safegres reports on. First definition wins: a pgpm module deploys a
+ * table once, and a later `ALTER` is not where a reviewer wants the alert.
+ */
+export function buildSourceIndex(dir, options = {}) {
+    const skip = new Set(options.skipDirs ?? ['node_modules', '.git', 'dist']);
+    const root = options.root ?? dir;
+    const index = new Map();
+    const walk = (current) => {
+        for (const entry of readdirSync(current)) {
+            if (skip.has(entry))
+                continue;
+            const path = join(current, entry);
+            const stat = statSync(path);
+            if (stat.isDirectory())
+                walk(path);
+            else if (entry.toLowerCase().endsWith('.sql'))
+                scan(path, root, index);
+        }
+    };
+    walk(dir);
+    return index;
+}
+function scan(path, root, index) {
+    const uri = relative(root, path).split(sep).join('/');
+    const lines = readFileSync(path, 'utf8').split('\n');
+    lines.forEach((line, i) => {
+        const table = CREATE_TABLE.exec(line);
+        if (table) {
+            add(index, `${unquote(table[1])}.${unquote(table[2])}`, uri, i + 1);
+            return;
+        }
+        const policy = CREATE_POLICY.exec(line);
+        if (policy) {
+            const relation = `${unquote(policy[2])}.${unquote(policy[3])}`;
+            add(index, `${relation}:${unquote(policy[1])}`, uri, i + 1);
+        }
+    });
+}
+function add(index, key, file, line) {
+    if (!index.has(key))
+        index.set(key, { file, line });
+}
+function unquote(identifier) {
+    return identifier.startsWith('"') ? identifier.slice(1, -1) : identifier.toLowerCase();
+}

package/esm/report/view.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Selection: the layer between analysis and rendering.
+ *
+ * A `Report` is what the audit found — pure data, the same for everybody. A
+ * `ReportView` is what one reader should see: which planes, which dimensions,
+ * which sections, how much detail. Renderers consume the view and decide only
+ * how it *looks*, so "the team wants the perf score and their direct-role
+ * planes in the PR comment" is answered once here, rather than four times in
+ * four renderers that drift apart.
+ */
+import type { ReportConfig } from '../config/types';
+import type { ScorecardReport } from '../score/scorecards';
+import type { Finding, PlaneReport, Report } from '../types';
+import type { ScoreDelta } from './compare';
+export type ViewSection = 'scores' | 'delta' | 'findings' | 'planes' | 'scorecards' | 'role-access' | 'call-graph';
+export declare const ALL_SECTIONS: ViewSection[];
+export type ViewDimension = 'security' | 'perf';
+export interface ViewConfig {
+    /**
+     * Planes to render in full, by name or glob (`*`, `direct:*`). The primary
+     * plane is always included. Default: primary only — secondaries are
+     * summarized, not expanded.
+     */
+    planes?: string[];
+    /** Dimensions to render. Default: whatever the report has. */
+    dimensions?: ViewDimension[];
+    /** Sections to render. Default: all of them the report has data for. */
+    sections?: ViewSection[];
+    /** How much of each section. Default `normal`. */
+    detail?: 'summary' | 'normal' | 'verbose';
+    /** Drop findings that are not on the primary surface entirely. */
+    exposedOnly?: boolean;
+}
+/** One score to render, with the delta that belongs to it. */
+export interface ViewScore {
+    /** `security`, `perf`, or `plane:<name>`. */
+    id: string;
+    label: string;
+    dimension: ViewDimension;
+    score: import('../score/score').Score;
+    /** Present for the primary security/perf scores when the run was compared. */
+    delta?: ScoreDelta;
+    /** The plane this score describes, when it is not the headline. */
+    plane?: PlaneReport;
+}
+export interface ViewFindings {
+    /** Reachable on the primary surface — the scored ones. */
+    exposed: Finding[];
+    /** Off the primary surface: reported, unscored. */
+    internal: Finding[];
+}
+export interface ReportView {
+    report: Report;
+    detail: 'summary' | 'normal' | 'verbose';
+    /** Headline scores, in render order. */
+    scores: ViewScore[];
+    /** Secondary planes to mention. Expanded ones are in `expandedPlanes`. */
+    planes: PlaneReport[];
+    /** Planes the view config asked to see in full. */
+    expandedPlanes: PlaneReport[];
+    /**
+     * Named scores other than `default`, which is the headline and is already
+     * rendered as the score. Kept in config order so the file decides what a
+     * reader sees first.
+     */
+    scorecards: ScorecardReport[];
+    security: ViewFindings;
+    perf?: ViewFindings;
+    has(section: ViewSection): boolean;
+}
+/** Glob match over plane names: `*` matches any run of characters. */
+export declare function matchPlane(pattern: string, name: string): boolean;
+/**
+ * Everything presentation-adjacent about a report, decided once.
+ *
+ * Selection never edits the report: `exposedOnly` narrows what the view
+ * exposes, and the underlying `report.findings` stays whole so a JSON dump
+ * beside a pretty print is still the full picture.
+ */
+export declare function selectView(report: Report, config?: ViewConfig): ReportView;
+/** The config-file half of a view: `report.planes` / `report.dimensions`. */
+export declare function viewConfigFromReportConfig(config: ReportConfig | undefined): ViewConfig;