safegres 1.23.0 → 1.25.0

package/README.md

@@ -435,13 +435,20 @@ Or the first-party action, which installs the CLI, runs that config, and turns t
 job summary, annotations and a sticky PR comment:
 
 ```yaml
-      - uses: constructive-io/constructive/packages/safegres@main
+      - uses: constructive-io/constructive/packages/safegres@safegres-action-v1
         with:
-          out: safegres-reports
           comment: true          # sticky PR comment (needs pull-requests: write)
           upload-sarif: true     # code scanning (needs security-events: write)
 ```
 
+`safegres-action-v1` is a moving tag on the action's latest v1; `@main` tracks the monorepo tip.
+The reports are uploaded as the `safegres-reports` artifact by default — that artifact *is* the
+next run's baseline, so a job that suppresses it (`upload-reports: false`) can never show a delta.
+
+Auditing a pgpm workspace (`source.pgpm`) adds `version: local`, which runs the repo's own safegres
+rather than installing one: that path deploys through `pgsql-test`, an optional peer only the
+workspace has.
+
 On a pull request it also measures the delta for you: it picks the base branch's most recent run
 that *is* a sane comparison — succeeded, younger than 48 hours, and audited a commit in this
 branch's merge-base history — downloads its report, and names the run it chose in the summary and

package/config/schema.js

@@ -131,7 +131,13 @@ const FAIL_ON = {
 };
 const GITHUB_COMMENT = {
     sticky: bool('Reuse one comment per PR instead of appending. Default true.'),
-    sections: list('Sections to include. Default scores, delta, new-findings.', str('Section', ['scores', 'delta', 'new-findings', 'findings', 'planes']))
+    sections: list('Sections to include. Default scores, delta, new-findings. `report` adds the '
+        + 'markdown report (`findings` is its old name).', str('Section', ['scores', 'delta', 'new-findings', 'report', 'findings', 'planes'])),
+    detail: str('How much of the report the report section carries. Default summary.', [
+        'summary',
+        'normal',
+        'verbose'
+    ])
 };
 const GITHUB = {
     summary: list('Scores in the job summary, in order (security, perf, planes:<glob>)', str('Score')),

package/config/types.d.ts

@@ -479,8 +479,23 @@ export interface GithubReportConfig {
 export interface GithubCommentConfig {
     /** Reuse one comment per PR instead of appending. Default `true`. */
     sticky?: boolean;
-    /** Sections to include. Default `['scores', 'delta', 'new-findings']`. */
-    sections?: Array<'scores' | 'delta' | 'new-findings' | 'findings' | 'planes'>;
+    /**
+     * Sections to include, in this order: `scores` (badges + exposure), `planes`,
+     * `delta`, `new-findings` (the perf ratchet verdict and what it caught), and
+     * `report` — the same markdown report the job summary carries, at `detail`.
+     * `findings` is the old name for `report`. Default
+     * `['scores', 'delta', 'new-findings']`; add `report` to review the audit
+     * without leaving the PR.
+     */
+    sections?: Array<'scores' | 'delta' | 'new-findings' | 'report' | 'findings' | 'planes'>;
+    /**
+     * How much of the report the `report` section carries. Default `summary` —
+     * scores, exposure, counts, the delta and the ratchet verdict, with no
+     * per-finding tables, because a comment is read on the way past and GitHub
+     * rejects a body over 64 KB. `normal`/`verbose` add the finding tables and
+     * degrade back to `summary` when the body would not fit.
+     */
+    detail?: 'summary' | 'normal' | 'verbose';
 }
 /**
  * The full safegres configuration, loadable from `safegres.config.{ts,js,mjs,cjs}`,

package/esm/config/schema.js

@@ -127,7 +127,13 @@ const FAIL_ON = {
 };
 const GITHUB_COMMENT = {
     sticky: bool('Reuse one comment per PR instead of appending. Default true.'),
-    sections: list('Sections to include. Default scores, delta, new-findings.', str('Section', ['scores', 'delta', 'new-findings', 'findings', 'planes']))
+    sections: list('Sections to include. Default scores, delta, new-findings. `report` adds the '
+        + 'markdown report (`findings` is its old name).', str('Section', ['scores', 'delta', 'new-findings', 'report', 'findings', 'planes'])),
+    detail: str('How much of the report the report section carries. Default summary.', [
+        'summary',
+        'normal',
+        'verbose'
+    ])
 };
 const GITHUB = {
     summary: list('Scores in the job summary, in order (security, perf, planes:<glob>)', str('Score')),

package/esm/config/types.d.ts

@@ -479,8 +479,23 @@ export interface GithubReportConfig {
 export interface GithubCommentConfig {
     /** Reuse one comment per PR instead of appending. Default `true`. */
     sticky?: boolean;
-    /** Sections to include. Default `['scores', 'delta', 'new-findings']`. */
-    sections?: Array<'scores' | 'delta' | 'new-findings' | 'findings' | 'planes'>;
+    /**
+     * Sections to include, in this order: `scores` (badges + exposure), `planes`,
+     * `delta`, `new-findings` (the perf ratchet verdict and what it caught), and
+     * `report` — the same markdown report the job summary carries, at `detail`.
+     * `findings` is the old name for `report`. Default
+     * `['scores', 'delta', 'new-findings']`; add `report` to review the audit
+     * without leaving the PR.
+     */
+    sections?: Array<'scores' | 'delta' | 'new-findings' | 'report' | 'findings' | 'planes'>;
+    /**
+     * How much of the report the `report` section carries. Default `summary` —
+     * scores, exposure, counts, the delta and the ratchet verdict, with no
+     * per-finding tables, because a comment is read on the way past and GitHub
+     * rejects a body over 64 KB. `normal`/`verbose` add the finding tables and
+     * degrade back to `summary` when the body would not fit.
+     */
+    detail?: 'summary' | 'normal' | 'verbose';
 }
 /**
  * The full safegres configuration, loadable from `safegres.config.{ts,js,mjs,cjs}`,

package/esm/report/github.d.ts

@@ -34,9 +34,22 @@ export declare function gradeBadge(label: string, grade: Grade, badges: boolean)
  */
 export declare function renderGithubSummary(report: Report, options?: GithubRenderOptions): string;
 /**
- * The sticky PR comment: shorter than the summary by design. A comment is read
- * on the way past, so it carries the scores, the movement, and what is new —
- * the full finding tables live in the job summary and the SARIF alerts.
+ * 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;
 /**

package/esm/report/github.js

@@ -72,22 +72,53 @@ export function renderGithubSummary(report, options = {}) {
     return out.join('\n');
 }
 /**
- * The sticky PR comment: shorter than the summary by design. A comment is read
- * on the way past, so it carries the scores, the movement, and what is new —
- * the full finding tables live in the job summary and the SARIF alerts.
+ * 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 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 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 <= 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 = 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 = [COMMENT_MARKER, '## safegres', ''];
     if (sections.has('scores')) {
         out.push(selectedScores(view.scores, selectors)
             .map((s) => scoreBadge(s.label, s.score, badges))
             .join(' '), '');
-        if (report.exposure) {
+        // 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.`
@@ -100,7 +131,9 @@ export function renderGithubComment(report, options = {}) {
             ? `| \`${p.name}\` | ${p.kind} | — | not graded |`
             : `| \`${p.name}\` | ${p.kind} | ${p.exposedTables} | **${p.score.grade}** (${p.score.value}) |`), '');
     }
-    if (sections.has('delta') && report.comparison) {
+    // 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 = describeBaseline(cmp.previous);
         if (cmp.unchanged) {
@@ -121,18 +154,30 @@ export function renderGithubComment(report, options = {}) {
             out.push('');
         }
     }
-    else if (sections.has('delta') && report.comparisonSkipped) {
+    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 added = report.perf?.diff?.added ?? [];
+        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 (sections.has('findings')) {
-        out.push(renderMarkdown(report, { title: 'Findings', view: options.view }), '');
+    if (withReport) {
+        out.push(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');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safegres",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "Postgres security and performance auditor: RLS, grants and effective-access analysis plus index and policy-cost checks, scored on two independent axes. One connection, no framework.",
   "main": "index.js",
@@ -57,16 +57,16 @@
     "safegres"
   ],
   "dependencies": {
-    "@inquirerer/utils": "^3.3.12",
-    "@pgpmjs/logger": "^2.25.0",
+    "@inquirerer/utils": "^3.3.13",
+    "@pgpmjs/logger": "^2.25.1",
     "@pgsql/lint": "^18.2.5",
     "@pgsql/traverse": "^18.7.7",
     "@pgsql/types": "^18.0.0",
     "confstash": "^0.1.2",
-    "inquirerer": "^4.9.3",
+    "inquirerer": "^4.9.4",
     "libpg-query": "^18.1.4",
     "pg": "^8.21.0",
-    "pg-env": "^1.31.0",
+    "pg-env": "^1.31.1",
     "pgsql-deparser": "^18.3.6",
     "pgsql-parser": "^18.2.6",
     "yanse": "^0.2.2"
@@ -82,8 +82,8 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/pg": "^8.20.4",
-    "makage": "^0.3.0",
-    "pgsql-test": "^5.13.1"
+    "makage": "^0.8.0",
+    "pgsql-test": "^5.13.3"
   },
-  "gitHead": "bfded396aef6eccc75fc6f289a9f8dc46df8a678"
+  "gitHead": "5e0bfead2856d1a062b495d343a43e543343f9b8"
 }

package/report/github.d.ts

@@ -34,9 +34,22 @@ export declare function gradeBadge(label: string, grade: Grade, badges: boolean)
  */
 export declare function renderGithubSummary(report: Report, options?: GithubRenderOptions): string;
 /**
- * The sticky PR comment: shorter than the summary by design. A comment is read
- * on the way past, so it carries the scores, the movement, and what is new —
- * the full finding tables live in the job summary and the SARIF alerts.
+ * 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;
 /**

package/report/github.js

@@ -45,7 +45,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COMMENT_MARKER = void 0;
+exports.COMMENT_MAX_CHARS = exports.COMMENT_MARKER = void 0;
 exports.scoreBadge = scoreBadge;
 exports.gradeBadge = gradeBadge;
 exports.renderGithubSummary = renderGithubSummary;
@@ -115,22 +115,53 @@ function renderGithubSummary(report, options = {}) {
     return out.join('\n');
 }
 /**
- * The sticky PR comment: shorter than the summary by design. A comment is read
- * on the way past, so it carries the scores, the movement, and what is new —
- * the full finding tables live in the job summary and the SARIF alerts.
+ * 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(' '), '');
-        if (report.exposure) {
+        // 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.`
@@ -143,7 +174,9 @@ function renderGithubComment(report, options = {}) {
             ? `| \`${p.name}\` | ${p.kind} | — | not graded |`
             : `| \`${p.name}\` | ${p.kind} | ${p.exposedTables} | **${p.score.grade}** (${p.score.value}) |`), '');
     }
-    if (sections.has('delta') && report.comparison) {
+    // 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) {
@@ -164,18 +197,30 @@ function renderGithubComment(report, options = {}) {
             out.push('');
         }
     }
-    else if (sections.has('delta') && report.comparisonSkipped) {
+    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 added = report.perf?.diff?.added ?? [];
+        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 (sections.has('findings')) {
-        out.push((0, markdown_1.renderMarkdown)(report, { title: 'Findings', view: options.view }), '');
+    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');
 }

package/schema/safegres.schema.json

@@ -1044,12 +1044,22 @@
                       "scores",
                       "delta",
                       "new-findings",
+                      "report",
                       "findings",
                       "planes"
                     ],
                     "description": "Section"
                   },
-                  "description": "Sections to include. Default scores, delta, new-findings."
+                  "description": "Sections to include. Default scores, delta, new-findings. `report` adds the markdown report (`findings` is its old name)."
+                },
+                "detail": {
+                  "type": "string",
+                  "enum": [
+                    "summary",
+                    "normal",
+                    "verbose"
+                  ],
+                  "description": "How much of the report the report section carries. Default summary."
                 }
               },
               "description": "Sticky PR comment"