@safegres/test 0.0.2 → 1.30.7

package/esm/report/markdown.js

@@ -0,0 +1,352 @@
+/**
+ * Markdown rendering (`--format markdown`), for the places CI reads a report:
+ * a GitHub job summary (`$GITHUB_STEP_SUMMARY`) or a PR comment.
+ *
+ * The pretty renderer is a terminal artifact — ANSI colors, fixed-width
+ * severity labels, a long scrollable list. A PR comment is read once, by
+ * someone deciding whether to look further, so this renders the same report
+ * as tables: scores first, then findings grouped by rule, with the noisy
+ * parts (internal advisories, accepted debt) collapsed into `<details>`.
+ */
+import { describeBaseline, formatDelta } from './compare';
+import { selectView } from './view';
+const SEV_ICON = {
+    critical: '🔴',
+    high: '🟠',
+    medium: '🟡',
+    low: '🔵',
+    info: '⚪'
+};
+/**
+ * Movement, colored by whether it is good news — the severity icons already
+ * spend red on "this is serious", so a delta that reuses red for "+15 info
+ * findings" reads as a fire when nothing is burning. Green is fewer findings /
+ * a higher score, red is the reverse, grey is neither.
+ */
+function movement(delta, betterWhen, digits = 0) {
+    if (delta === 0)
+        return `⚪ ${formatDelta(0)}`;
+    const improved = betterWhen === 'lower' ? delta < 0 : delta > 0;
+    const arrow = delta > 0 ? '▲' : '▼';
+    return `${improved ? '🟢' : '🔴'} ${arrow} ${formatDelta(delta, digits)}`;
+}
+export function renderMarkdown(report, options = {}) {
+    const view = selectView(report, {
+        detail: options.summary ? 'summary' : options.verbose ? 'verbose' : 'normal',
+        ...(options.planes ? { planes: options.planes } : {}),
+        ...options.view
+    });
+    const out = [`## ${options.title ?? 'safegres'}`, ''];
+    out.push(...scoreTable(report, options), '');
+    if (report.exposure) {
+        const { known, source, exposedTables, totalTables, roles, unaddressable } = report.exposure;
+        out.push(known
+            ? `Exposure (${source}): **${exposedTables}/${totalTables}** tables reachable`
+                + `${roles && roles.length > 0 ? ` via \`${roles.join('`, `')}\`` : ''}.`
+                + (unaddressable && unaddressable.length > 0
+                    ? ` ${unaddressable.length} relation(s) in those schemas are declared unaddressable`
+                        + ` by the API: ${unaddressable.map((r) => `\`${r.schema}.${r.table}\``).join(', ')}.`
+                    : '')
+            : '> [!WARNING]\n> Exposure unknown — the entire database is assumed reachable and the score is capped.', '');
+    }
+    if (view.has('scorecards'))
+        out.push(...scorecardSection(view), '');
+    if (view.has('planes'))
+        out.push(...planeSection(view), '');
+    out.push(countsTable(report), '');
+    if (report.comparison)
+        out.push(...comparisonSection(report.comparison), '');
+    else if (report.comparisonSkipped)
+        out.push(...noBaselineSection(report.comparisonSkipped), '');
+    if (view.detail === 'summary') {
+        // The ratchet's verdict is the one perf number a summary reader needs:
+        // the absolute score is dominated by accepted debt, the delta is not.
+        const diff = report.perf?.diff;
+        if (diff) {
+            out.push(`Perf baseline: **${diff.added.length} new**, ${diff.accepted.length} accepted, `
+                + `${diff.removed.length} resolved.`, '');
+        }
+        return out.join('\n');
+    }
+    out.push(...findingSection('Security findings', [...view.security.exposed, ...view.security.internal], options), '');
+    if (report.roleAccess && report.roleAccess.roles.length > 0) {
+        out.push(...roleAccessSection(report.roleAccess.roles), '');
+    }
+    if (report.perf) {
+        out.push(...findingSection('Performance findings', report.perf.findings, options));
+        const { paths, stats, explain, diff } = report.perf;
+        const notes = [];
+        if (paths && paths.writeOnceShaped > 0) {
+            const acted = {
+                report: 'X1 still asks for an index on each of them',
+                demote: 'their X1 findings are demoted to `info`',
+                suppress: 'their X1 findings are suppressed'
+            }[paths.onWriteOncePointer];
+            notes.push(`Access paths: of ${paths.total} foreign keys, ${paths.read} are named by an RLS policy `
+                + `or a view, and ${paths.writeOnceShaped} across ${paths.tables} tables look like `
+                + `write-once provisioning pointers — ${acted}. A shape is not proof that nothing `
+                + 'queries the relation (`perf.paths.onWriteOncePointer` to change what X1 does).');
+        }
+        if (stats) {
+            notes.push(`Runtime statistics: ${stats.tables} tables, counters since ${stats.statsReset ?? 'server start'}`
+                + `${stats.scored ? '' : ' (advisory — `includeStats` is false)'}.`);
+            for (const note of stats.notes ?? [])
+                notes.push(note);
+        }
+        if (explain) {
+            notes.push(explain.unavailable
+                ?? `Planner proof: ${explain.confirmed} confirmed, ${explain.refuted} refuted, `
+                    + `${explain.inconclusive} inconclusive of ${explain.probed} probed.`);
+        }
+        if (notes.length > 0)
+            out.push('', notes.map((n) => `_${n}_`).join('  \n'));
+        if (diff) {
+            out.push('', '### Performance vs baseline', '');
+            out.push(diff.added.length === 0
+                ? `No new perf debt (${diff.accepted.length} accepted, ${diff.removed.length} fixed).`
+                : `**${diff.added.length} new** since the baseline `
+                    + `(${diff.accepted.length} accepted, ${diff.removed.length} fixed):`);
+            if (diff.added.length > 0)
+                out.push('', findingTable(diff.added));
+        }
+        out.push('');
+    }
+    return out.join('\n');
+}
+/**
+ * The other ways in, as one table. Secondary planes are advisory by
+ * construction — an internal role reaching internal tables is the schema
+ * working as designed — so they read as context under the headline rather
+ * than as a second verdict competing with it.
+ */
+/**
+ * The other named scores. Same findings, different questions — which is the
+ * point: a team that gates on `anon-surface` is not being asked to care
+ * about the headline, and `raw` is there so nobody has to trust that the
+ * config was written in good faith.
+ */
+function scorecardSection(view) {
+    const out = [
+        '### Scorecards',
+        '',
+        '_The same findings, scored by question. Nothing here filters the report — '
+            + 'a scorecard decides what a number is *about*, never what is reported._',
+        '',
+        '| Scorecard | Score | Grade | Findings | Question |',
+        '| --- | ---: | --- | ---: | --- |'
+    ];
+    for (const card of view.scorecards) {
+        out.push(`| \`${card.name}\` | ${card.score.value} | **${card.score.grade}** | ${card.findings} `
+            + `| ${card.description ?? card.title ?? ''} |`);
+    }
+    return out;
+}
+function planeSection(view) {
+    const out = [
+        '### Other access planes',
+        '',
+        '_Advisory: these are not the score above. The headline grades the declared API surface; '
+            + 'a plane grades what somebody reaches without going through it._',
+        '',
+        '| Plane | Kind | Reaches | Relations | Score | Grade |',
+        '| --- | --- | --- | ---: | ---: | --- |'
+    ];
+    for (const plane of view.planes)
+        out.push(planeRow(plane));
+    for (const plane of view.expandedPlanes) {
+        if (plane.skipped || plane.score.deductions.length === 0)
+            continue;
+        out.push('', `#### Plane \`${plane.name}\` by rule`, '', '| Rule | Findings | Points | Grade | Payoff |', '| --- | ---: | ---: | --- | ---: |', ...plane.score.deductions.map(deductionRow));
+    }
+    return out;
+}
+function planeRow(plane) {
+    const who = plane.roles && plane.roles.length > 0
+        ? plane.roles.map((r) => `\`${r}\``).join(', ')
+        : plane.schemas.map((s) => `\`${s}\``).join(', ') || '—';
+    if (plane.skipped) {
+        return `| \`${plane.name}\` | ${plane.kind} | ${who} | — | — | not graded — ${plane.skipped} |`;
+    }
+    const via = plane.reachedVia ? ` (via ${plane.reachedVia})` : '';
+    return `| \`${plane.name}\` | ${plane.kind} | ${who}${via} | ${plane.exposedTables} `
+        + `| **${plane.score.value}** | **${plane.score.grade}** |`;
+}
+/**
+ * The direct answer to "what can role X access?" — effective grants
+ * (direct, TO PUBLIC, inherited), classified by whether RLS mediates them.
+ */
+function roleAccessSection(roles) {
+    const out = ['### Role access', ''];
+    for (const entry of roles) {
+        out.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)` : ''}.`, '');
+        if (entry.unmediated.length > 0) {
+            out.push('| Relation | Privileges | Via |', '| --- | --- | --- |', ...entry.unmediated.map((r) => `| \`${r.schema}.${r.table}\` | ${r.privileges.join(', ')}`
+                + `${r.columns ? ` (${r.columns.join(', ')})` : ''} | ${r.via} |`), '');
+        }
+    }
+    return out;
+}
+function scoreTable(report, options) {
+    const cmp = report.comparison;
+    const rows = [];
+    if (report.score)
+        rows.push(scoreRow('Security', report.score, !!cmp, cmp?.security));
+    if (report.perf)
+        rows.push(scoreRow('Performance', report.perf.score, !!cmp, cmp?.perf));
+    if (rows.length === 0)
+        return [];
+    const deltaHeader = cmp ? ` Δ vs ${cmp.previous.ref ?? 'previous run'} |` : '';
+    return [
+        `| Dimension | Score | Grade |${deltaHeader} Top deductions |`,
+        `| --- | --- | --- |${cmp ? ' --- |' : ''} --- |`,
+        ...rows,
+        '',
+        ...ruleTable('Security', report.score, options),
+        ...ruleTable('Performance', report.perf?.score, options)
+    ];
+}
+function scoreRow(label, score, compared, delta) {
+    const top = score.deductions
+        .filter((d) => !d.unscored)
+        .slice(0, 3)
+        .map((d) => `\`${d.code}\` −${d.points} (×${d.count})`)
+        .join(', ');
+    const capped = score.cappedByUnknownExposure ? ' (capped)' : '';
+    // The column exists for the whole table or not at all: a dimension the
+    // previous run didn't have still needs its cell.
+    const deltaCell = compared ? ` ${delta ? scoreDeltaCell(delta) : '— (new)'} |` : '';
+    return `| ${label} | **${score.value}**${capped} | **${score.grade}** |${deltaCell} ${top || '—'} |`;
+}
+/**
+ * The movement, made legible at a glance: an arrow for the direction, the
+ * grade transition when it crossed a band, and the finding count either way —
+ * a score can hold still while findings move underneath it.
+ */
+function scoreDeltaCell(d) {
+    const score = d.delta === 0 ? '⚪ no change' : `${movement(d.delta, 'higher', 1)} (from ${d.before})`;
+    const grade = d.gradeBefore === d.gradeAfter ? '' : ` · ${d.gradeBefore} → ${d.gradeAfter}`;
+    const findings = d.findingsAfter === d.findingsBefore
+        ? ''
+        : ` · ${d.findingsBefore} → ${d.findingsAfter} findings `
+            + `${movement(d.findingsAfter - d.findingsBefore, 'lower')}`;
+    return `${score}${grade}${findings}`;
+}
+/**
+ * A rule with no previous reading is not movement: the previous run simply did
+ * not report the code (a rule added since, or a dimension it never ran).
+ */
+function ruleDeltaCell(r) {
+    return r.unmeasuredBefore ? '⚪ not measured before' : movement(r.delta, 'lower');
+}
+/**
+ * Rendered after the counts so the two tables can be read together: what the
+ * numbers are, then which way they moved.
+ */
+function comparisonSection(cmp) {
+    const since = describeBaseline(cmp.previous);
+    if (cmp.unchanged)
+        return ['', `_No change since ${since}._`];
+    const out = [
+        '',
+        `<details open><summary>Changes since ${since}</summary>`,
+        '',
+        '🟢 improvement · 🔴 regression · ⚪ no change or no previous reading',
+        ''
+    ];
+    const severities = ['critical', 'high', 'medium', 'low', 'info'];
+    const moved = severities.filter((sev) => cmp.summary[sev].delta !== 0);
+    if (moved.length > 0) {
+        out.push(`| ${moved.map((sev) => `${SEV_ICON[sev]} ${sev}`).join(' | ')} |`, `| ${moved.map(() => '---').join(' | ')} |`, `| ${moved
+            .map((sev) => {
+            const s = cmp.summary[sev];
+            return `${s.before} → **${s.after}** ${movement(s.delta, 'lower')}`;
+        })
+            .join(' | ')} |`, '');
+    }
+    if (cmp.rules.length > 0) {
+        out.push('| Rule | Dimension | Before | After | Δ |', '| --- | --- | ---: | ---: | --- |', ...cmp.rules.map((r) => `| \`${r.code}\` | ${r.dimension} | ${r.unmeasuredBefore ? '—' : r.before} | `
+            + `${r.after} | ${ruleDeltaCell(r)} |`), '');
+    }
+    out.push('</details>');
+    return out;
+}
+/**
+ * A delta was asked for and none was trustworthy. Said out loud, because an
+ * absent delta is indistinguishable from "nothing changed" — and because the
+ * gates that do not read the comparison are still in force.
+ */
+function noBaselineSection(reason) {
+    return [
+        '',
+        `> [!NOTE]`,
+        `> No delta baseline: ${reason}. The absolute score and the perf baseline still gate this run.`
+    ];
+}
+/**
+ * Per-rule breakdown. `Payoff` is what the dimension score becomes if that
+ * rule alone goes to zero — the number worth ranking work by, and not
+ * proportional to the finding count, because the curve is exponential.
+ */
+/**
+ * One rule's row. Findings and fixes are different numbers when a rule fans
+ * out over a single repair, and points are charged on the second.
+ */
+function deductionRow(d) {
+    const found = d.units === undefined ? `${d.count}` : `${d.count} (${d.units} fixes)`;
+    const points = d.capped ? `−${d.points} (capped)` : `−${d.points}`;
+    return d.unscored
+        ? `| \`${d.code}\` | ${found} | — | — | *unscored* |`
+        : `| \`${d.code}\` | ${found} | ${points} | **${d.grade}** | +${d.potential.toFixed(1)} |`;
+}
+function ruleTable(label, score, options) {
+    if (!score || score.deductions.length === 0)
+        return [];
+    const table = [
+        '| Rule | Findings | Points | Grade | Payoff |',
+        '| --- | ---: | ---: | --- | ---: |',
+        ...score.deductions.map(deductionRow)
+    ];
+    return options.verbose
+        ? [`### ${label} by rule`, '', ...table, '']
+        : [`<details><summary>${label} by rule</summary>`, '', ...table, '', '</details>', ''];
+}
+function countsTable(report) {
+    const s = report.summary;
+    return [
+        '| 🔴 critical | 🟠 high | 🟡 medium | 🔵 low | ⚪ info |',
+        '| --- | --- | --- | --- | --- |',
+        `| ${s.critical} | ${s.high} | ${s.medium} | ${s.low} | ${s.info} |`
+    ].join('\n');
+}
+function findingSection(heading, findings, options) {
+    const out = [`### ${heading}`, ''];
+    const exposed = findings.filter((f) => f.exposed !== false);
+    const internal = findings.filter((f) => f.exposed === false);
+    if (exposed.length === 0)
+        out.push('No findings.');
+    else
+        out.push(findingTable(exposed));
+    if (internal.length > 0) {
+        const table = findingTable(internal);
+        out.push('', options.verbose
+            ? table
+            : `<details><summary>${internal.length} internal `
+                + `advisor${internal.length === 1 ? 'y' : 'ies'} — not exposed via any API, `
+                + `excluded from the score</summary>\n\n${table}\n\n</details>`);
+    }
+    return out;
+}
+function findingTable(findings) {
+    const rows = findings.map((f) => {
+        const where = [f.schema, f.table].filter(Boolean).join('.') || '—';
+        const policy = f.policy ? ` \`${f.policy}\`` : '';
+        return `| ${SEV_ICON[f.severity]} ${f.severity} | \`${f.code}\` | ${where}${policy} | ${escapeCell(f.message)} |`;
+    });
+    return ['| Severity | Rule | Relation | Finding |', '| --- | --- | --- | --- |', ...rows].join('\n');
+}
+/** Keep a message inside its table cell: no pipes, no line breaks. */
+function escapeCell(value) {
+    return value.replace(/\|/g, '\\|').replace(/\s*\n\s*/g, ' ');
+}

package/esm/report/pretty.d.ts

@@ -0,0 +1,14 @@
+import type { Report } from '../types';
+import { type ViewConfig } from './view';
+export interface RenderPrettyOptions {
+    color?: boolean;
+    /** Only render the exposure line, score, and severity summary — no per-finding lines. */
+    summary?: boolean;
+    /** Expand the internal (non-exposed) advisories instead of collapsing them to a count. */
+    verbose?: boolean;
+    /** Secondary planes to expand, by name or glob. Default: summarized in one line each. */
+    planes?: string[];
+    /** Everything else the view layer selects. Beats the flags above. */
+    view?: ViewConfig;
+}
+export declare function renderPretty(report: Report, options?: RenderPrettyOptions): string;