@safegres/test 0.0.2 → 1.30.7

package/report/github.d.ts

@@ -0,0 +1,74 @@
+/**
+ * GitHub Actions output: job summary, workflow annotations, and a sticky PR
+ * comment.
+ *
+ * This is a *renderer*, not a second audit — everything here reads the same
+ * `ReportView` the terminal renderer reads, so what CI says and what a
+ * developer sees locally cannot disagree.
+ *
+ * On color: GitHub Markdown has none. The only way to get a real green/red
+ * score is an image, so scores render as shields.io badges by default, with
+ * 🟢/🟡/🔴 as the offline fallback (`report.github.badges: false`).
+ */
+import type { GithubReportConfig } from '../config/types';
+import type { Grade } from '../config/types';
+import type { Score } from '../score/score';
+import type { Finding, Report } from '../types';
+import { type ViewConfig } from './view';
+/** Marker that makes the PR comment sticky: one comment, edited in place. */
+export declare const COMMENT_MARKER = "<!-- safegres-report -->";
+export interface GithubRenderOptions {
+    config?: GithubReportConfig;
+    /** Findings that tripped a gate, for `annotations: 'gate-failures'`. */
+    gateFailures?: Finding[];
+    /** Extra view selection (planes, dimensions) from `report` config. */
+    view?: ViewConfig;
+}
+/** A score as a shields.io badge, or as a colored dot when badges are off. */
+export declare function scoreBadge(label: string, score: Score, badges: boolean): string;
+export declare function gradeBadge(label: string, grade: Grade, badges: boolean): string;
+/**
+ * The job summary: the badges a reviewer reads first, then the full markdown
+ * report. `summary` picks which scores get a badge — `security`, `perf`, and
+ * `planes:<glob>` for the secondary planes a team cares about.
+ */
+export declare function renderGithubSummary(report: Report, options?: GithubRenderOptions): string;
+/**
+ * GitHub rejects an issue comment body over 65536 characters, and a comment
+ * that fails to post is worse than a short one — so a comment carrying the
+ * report degrades (verbose → normal → summary → a pointer at the job summary)
+ * rather than being truncated at a byte boundary by the API.
+ */
+export declare const COMMENT_MAX_CHARS = 65536;
+/**
+ * The sticky PR comment: shorter than the summary by default. A comment is read
+ * on the way past, so out of the box it carries the scores, the movement, and
+ * what is new, with the full finding tables in the job summary and the SARIF
+ * alerts.
+ *
+ * `comment.sections` chooses what it says. `report` puts the whole markdown
+ * report in the comment at `comment.detail` (default `summary`: scores,
+ * exposure, counts, the delta and the ratchet verdict — no per-finding tables),
+ * which is the same render the job summary uses, so the two cannot disagree.
+ */
+export declare function renderGithubComment(report: Report, options?: GithubRenderOptions): string;
+/**
+ * Workflow annotations. Default `gate-failures`: annotating every advisory on
+ * a large schema buries the one finding that actually blocked the merge.
+ */
+export declare function renderAnnotations(report: Report, options?: GithubRenderOptions): string[];
+/**
+ * Write the summary to `$GITHUB_STEP_SUMMARY` and print the annotations.
+ * Returns false when not running under GitHub Actions, so a caller can fall
+ * back to stdout rather than silently producing nothing.
+ */
+export declare function emitGithub(report: Report, options?: GithubRenderOptions): boolean;
+/**
+ * Upsert the sticky comment on the current pull request. No-op (returning a
+ * reason) when the environment has no PR or no token: a report is not worth
+ * failing a build over, but silence about *why* is how integrations rot.
+ */
+export declare function postStickyComment(body: string, env?: NodeJS.ProcessEnv): Promise<{
+    posted: boolean;
+    reason?: string;
+}>;

package/report/github.js

@@ -0,0 +1,333 @@
+"use strict";
+/**
+ * GitHub Actions output: job summary, workflow annotations, and a sticky PR
+ * comment.
+ *
+ * This is a *renderer*, not a second audit — everything here reads the same
+ * `ReportView` the terminal renderer reads, so what CI says and what a
+ * developer sees locally cannot disagree.
+ *
+ * On color: GitHub Markdown has none. The only way to get a real green/red
+ * score is an image, so scores render as shields.io badges by default, with
+ * 🟢/🟡/🔴 as the offline fallback (`report.github.badges: false`).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMENT_MAX_CHARS = exports.COMMENT_MARKER = void 0;
+exports.scoreBadge = scoreBadge;
+exports.gradeBadge = gradeBadge;
+exports.renderGithubSummary = renderGithubSummary;
+exports.renderGithubComment = renderGithubComment;
+exports.renderAnnotations = renderAnnotations;
+exports.emitGithub = emitGithub;
+exports.postStickyComment = postStickyComment;
+const fs = __importStar(require("fs"));
+const compare_1 = require("./compare");
+const markdown_1 = require("./markdown");
+const view_1 = require("./view");
+/** Marker that makes the PR comment sticky: one comment, edited in place. */
+exports.COMMENT_MARKER = '<!-- safegres-report -->';
+const GRADE_COLOR = {
+    'A+': 'brightgreen',
+    A: 'brightgreen',
+    B: 'green',
+    C: 'yellow',
+    D: 'orange',
+    F: 'red'
+};
+const GRADE_DOT = {
+    'A+': '🟢',
+    A: '🟢',
+    B: '🟢',
+    C: '🟡',
+    D: '🟠',
+    F: '🔴'
+};
+/** A score as a shields.io badge, or as a colored dot when badges are off. */
+function scoreBadge(label, score, badges) {
+    const color = GRADE_COLOR[score.grade] ?? 'lightgrey';
+    if (!badges)
+        return `${GRADE_DOT[score.grade] ?? '⚪'} **${label} ${score.value} (${score.grade})**`;
+    const text = encodeURIComponent(`${score.value} (${score.grade})`);
+    const name = encodeURIComponent(label);
+    return `![${label} ${score.value} ${score.grade}](https://img.shields.io/badge/${name}-${text}-${color})`;
+}
+function gradeBadge(label, grade, badges) {
+    const color = GRADE_COLOR[grade] ?? 'lightgrey';
+    if (!badges)
+        return `${GRADE_DOT[grade] ?? '⚪'} **${label} ${grade}**`;
+    return `![${label} ${grade}](https://img.shields.io/badge/${encodeURIComponent(label)}-${grade}-${color})`;
+}
+/**
+ * The job summary: the badges a reviewer reads first, then the full markdown
+ * report. `summary` picks which scores get a badge — `security`, `perf`, and
+ * `planes:<glob>` for the secondary planes a team cares about.
+ */
+function renderGithubSummary(report, options = {}) {
+    const config = options.config ?? {};
+    const badges = config.badges !== false;
+    const selectors = config.summary ?? ['security', 'perf'];
+    const viewConfig = {
+        planes: planePatterns(selectors),
+        ...(config.detail ? { detail: config.detail } : {}),
+        ...options.view
+    };
+    const view = (0, view_1.selectView)(report, viewConfig);
+    const out = [];
+    const line = selectedScores(view.scores, selectors)
+        .map((s) => scoreBadge(s.label, s.score, badges))
+        .join(' ');
+    if (line)
+        out.push(line, '');
+    out.push((0, markdown_1.renderMarkdown)(report, { view: viewConfig }));
+    return out.join('\n');
+}
+/**
+ * GitHub rejects an issue comment body over 65536 characters, and a comment
+ * that fails to post is worse than a short one — so a comment carrying the
+ * report degrades (verbose → normal → summary → a pointer at the job summary)
+ * rather than being truncated at a byte boundary by the API.
+ */
+exports.COMMENT_MAX_CHARS = 65536;
+/**
+ * The sticky PR comment: shorter than the summary by default. A comment is read
+ * on the way past, so out of the box it carries the scores, the movement, and
+ * what is new, with the full finding tables in the job summary and the SARIF
+ * alerts.
+ *
+ * `comment.sections` chooses what it says. `report` puts the whole markdown
+ * report in the comment at `comment.detail` (default `summary`: scores,
+ * exposure, counts, the delta and the ratchet verdict — no per-finding tables),
+ * which is the same render the job summary uses, so the two cannot disagree.
+ */
+function renderGithubComment(report, options = {}) {
+    const wanted = options.config?.comment?.detail ?? 'summary';
+    const chain = wanted === 'verbose' ? ['verbose', 'normal', 'summary'] : wanted === 'normal' ? ['normal', 'summary'] : ['summary'];
+    for (const detail of chain) {
+        const body = commentBody(report, options, detail);
+        if (body.length <= exports.COMMENT_MAX_CHARS)
+            return body;
+    }
+    return commentBody(report, options, null);
+}
+/**
+ * One comment body. `detail` is the report section's detail, or null to drop
+ * the report and say where it went — which is how the size cap is honored.
+ */
+function commentBody(report, options, detail) {
+    const config = options.config ?? {};
+    const badges = config.badges !== false;
+    const sections = new Set(config.comment?.sections ?? ['scores', 'delta', 'new-findings']);
+    const selectors = config.summary ?? ['security', 'perf'];
+    const view = (0, view_1.selectView)(report, { planes: planePatterns(selectors), ...options.view });
+    // `findings` is the old name for `report`; both mean "the markdown report".
+    const wantsReport = sections.has('report') || sections.has('findings');
+    const withReport = wantsReport && detail != null;
+    const out = [exports.COMMENT_MARKER, '## safegres', ''];
+    if (sections.has('scores')) {
+        out.push(selectedScores(view.scores, selectors)
+            .map((s) => scoreBadge(s.label, s.score, badges))
+            .join(' '), '');
+        // Everything below is in the report too, so it is said once.
+        if (report.exposure && !withReport) {
+            out.push(report.exposure.known
+                ? `Exposure (${report.exposure.source}): **${report.exposure.exposedTables}/`
+                    + `${report.exposure.totalTables}** tables reachable.`
+                : '> [!WARNING]\n> Exposure unknown — the whole database is assumed reachable, '
+                    + 'and the score is capped.', '');
+        }
+    }
+    if (sections.has('planes') && view.planes.length > 0) {
+        out.push('| Plane | Kind | Relations | Grade |', '| --- | --- | ---: | --- |', ...view.planes.map((p) => p.skipped
+            ? `| \`${p.name}\` | ${p.kind} | — | not graded |`
+            : `| \`${p.name}\` | ${p.kind} | ${p.exposedTables} | **${p.score.grade}** (${p.score.value}) |`), '');
+    }
+    // The report renders the comparison (or the reason there is none) itself.
+    const wantsDelta = sections.has('delta') && !withReport;
+    if (wantsDelta && report.comparison) {
+        const cmp = report.comparison;
+        const since = (0, compare_1.describeBaseline)(cmp.previous);
+        if (cmp.unchanged) {
+            out.push(`_No change since ${since}._`, '');
+        }
+        else {
+            out.push(`**Changes since ${since}**`, '');
+            for (const [dimension, d] of [
+                ['security', cmp.security],
+                ['performance', cmp.perf]
+            ]) {
+                if (!d)
+                    continue;
+                const arrow = d.delta > 0 ? '🟢 ▲' : d.delta < 0 ? '🔴 ▼' : '⚪';
+                out.push(`- ${dimension}: ${arrow} ${d.delta > 0 ? '+' : ''}${d.delta.toFixed(1)} `
+                    + `(${d.before} → ${d.after}${d.gradeBefore === d.gradeAfter ? '' : `, ${d.gradeBefore} → ${d.gradeAfter}`})`);
+            }
+            out.push('');
+        }
+    }
+    else if (wantsDelta && report.comparisonSkipped) {
+        out.push(`_No delta baseline: ${report.comparisonSkipped}. `
+            + 'The absolute score and the perf baseline still gate this run._', '');
+    }
+    if (sections.has('new-findings')) {
+        const diff = report.perf?.diff;
+        // The ratchet's verdict, even when it is "nothing new": a comment that only
+        // speaks up on new debt cannot be distinguished from one that never ran.
+        // The report carries this line itself, so it is not repeated under it.
+        if (diff && !withReport) {
+            out.push(`Perf baseline: **${diff.added.length} new**, ${diff.accepted.length} accepted, `
+                + `${diff.removed.length} resolved.`, '');
+        }
+        const added = diff?.added ?? [];
+        if (added.length > 0) {
+            out.push(`**${added.length} new performance finding${added.length === 1 ? '' : 's'} since the baseline**`, '', ...added.slice(0, 10).map((f) => `- \`${f.code}\` ${location(f)} — ${f.message}`), '');
+        }
+    }
+    if (withReport) {
+        out.push((0, markdown_1.renderMarkdown)(report, { title: 'Report', view: { detail, ...options.view } }), '');
+    }
+    else if (wantsReport) {
+        out.push('_The report is too large for a PR comment — it is in the job summary and the '
+            + 'reports artifact._', '');
+    }
+    return out.join('\n');
+}
+/**
+ * Workflow annotations. Default `gate-failures`: annotating every advisory on
+ * a large schema buries the one finding that actually blocked the merge.
+ */
+function renderAnnotations(report, options = {}) {
+    const mode = options.config?.annotations ?? 'gate-failures';
+    if (mode === 'none')
+        return [];
+    const findings = mode === 'all'
+        ? report.findings.filter((f) => f.exposed !== false && !f.acknowledged)
+        : (options.gateFailures ?? []);
+    return findings.map((f) => {
+        const level = f.severity === 'critical' || f.severity === 'high' ? 'error' : 'warning';
+        const title = `${f.code} ${location(f)}`.trim();
+        return `::${level} title=${escapeProperty(title)}::${escapeData(f.message)}`;
+    });
+}
+/**
+ * Write the summary to `$GITHUB_STEP_SUMMARY` and print the annotations.
+ * Returns false when not running under GitHub Actions, so a caller can fall
+ * back to stdout rather than silently producing nothing.
+ */
+function emitGithub(report, options = {}) {
+    const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+    for (const annotation of renderAnnotations(report, options)) {
+        process.stdout.write(`${annotation}\n`);
+    }
+    if (!summaryPath)
+        return false;
+    fs.appendFileSync(summaryPath, `${renderGithubSummary(report, options)}\n`);
+    return true;
+}
+/**
+ * Upsert the sticky comment on the current pull request. No-op (returning a
+ * reason) when the environment has no PR or no token: a report is not worth
+ * failing a build over, but silence about *why* is how integrations rot.
+ */
+async function postStickyComment(body, env = process.env) {
+    const token = env.GITHUB_TOKEN ?? env.INPUT_GITHUB_TOKEN;
+    const repo = env.GITHUB_REPOSITORY;
+    if (!token)
+        return { posted: false, reason: 'no GITHUB_TOKEN in the environment' };
+    if (!repo)
+        return { posted: false, reason: 'no GITHUB_REPOSITORY in the environment' };
+    const pr = pullRequestNumber(env);
+    if (pr == null)
+        return { posted: false, reason: 'not running on a pull_request event' };
+    const api = env.GITHUB_API_URL ?? 'https://api.github.com';
+    const headers = {
+        accept: 'application/vnd.github+json',
+        authorization: `Bearer ${token}`,
+        'content-type': 'application/json'
+    };
+    const listed = await fetch(`${api}/repos/${repo}/issues/${pr}/comments?per_page=100`, { headers });
+    if (!listed.ok) {
+        return { posted: false, reason: `GitHub API ${listed.status} listing comments` };
+    }
+    const comments = (await listed.json());
+    const existing = comments.find((c) => c.body?.includes(exports.COMMENT_MARKER));
+    const target = existing
+        ? `${api}/repos/${repo}/issues/comments/${existing.id}`
+        : `${api}/repos/${repo}/issues/${pr}/comments`;
+    const written = await fetch(target, {
+        method: existing ? 'PATCH' : 'POST',
+        headers,
+        body: JSON.stringify({ body })
+    });
+    if (!written.ok)
+        return { posted: false, reason: `GitHub API ${written.status} writing comment` };
+    return { posted: true };
+}
+function pullRequestNumber(env) {
+    const eventPath = env.GITHUB_EVENT_PATH;
+    if (!eventPath || !fs.existsSync(eventPath))
+        return null;
+    try {
+        const event = JSON.parse(fs.readFileSync(eventPath, 'utf8'));
+        return event.pull_request?.number ?? event.issue?.number ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `planes:direct:*` in a summary selector is a plane glob for the view. */
+function planePatterns(selectors) {
+    return selectors
+        .filter((s) => s.startsWith('planes:'))
+        .map((s) => s.slice('planes:'.length));
+}
+function selectedScores(scores, selectors) {
+    const planes = planePatterns(selectors);
+    return scores.filter((s) => {
+        if (s.plane)
+            return planes.some((p) => (0, view_1.matchPlane)(p, s.plane.name));
+        return selectors.includes(s.id);
+    });
+}
+function location(f) {
+    return [f.schema, f.table].filter(Boolean).join('.') + (f.policy ? ` (${f.policy})` : '');
+}
+// https://github.com/actions/toolkit/blob/main/packages/core/src/command.ts
+function escapeData(value) {
+    return value.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+}
+function escapeProperty(value) {
+    return escapeData(value).replace(/:/g, '%3A').replace(/,/g, '%2C');
+}

package/report/json.d.ts

@@ -0,0 +1,4 @@
+import type { Report } from '../types';
+export declare function renderJson(report: Report, options?: {
+    pretty?: boolean;
+}): string;

package/report/json.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderJson = renderJson;
+function renderJson(report, options = {}) {
+    return options.pretty ? JSON.stringify(report, null, 2) : JSON.stringify(report);
+}

package/report/markdown.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 type { Report } from '../types';
+import { type ViewConfig } from './view';
+export interface RenderMarkdownOptions {
+    /** Scores and counts only — no per-finding tables. */
+    summary?: boolean;
+    /** Expand internal (non-exposed) advisories instead of collapsing them. */
+    verbose?: boolean;
+    /** Heading text. Default `safegres`. */
+    title?: string;
+    /** Secondary planes to expand, by name or glob. Default: one summary table. */
+    planes?: string[];
+    /** Everything else the view layer selects. Beats the flags above. */
+    view?: ViewConfig;
+}
+export declare function renderMarkdown(report: Report, options?: RenderMarkdownOptions): string;