@webpieces/pr-gate 0.4.593 → 0.4.595

package/src/dashboard/dashboard.js

@@ -1,24 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Dashboard = exports.DashboardInput = exports.DisableCounts = exports.ChecklistRow = exports.GateResult = exports.CHECKLIST_COMMENT_MARKER = void 0;
+exports.Dashboard = exports.DashboardInput = exports.DisableCounts = exports.ChecklistRow = exports.GateResult = exports.DETAIL_COMMENT_MARKER = void 0;
 const tslib_1 = require("tslib");
 const rules_config_1 = require("@webpieces/rules-config");
 const inversify_1 = require("inversify");
-// Hidden marker on the checklist review COMMENT, so wp-finish can find + PATCH its own comment on every
-// push instead of appending a new one. Versioned so the format can evolve without matching an old shape.
-// v2 = the full roster (every DEFINED checklist, matched or not) + tri-state verdicts.
-exports.CHECKLIST_COMMENT_MARKER = '<!-- webpieces-checklists v2 -->';
-const COMMENT_LIMIT = 65000; // under GitHub's 65536-char cap, with headroom for the marker + roll-up.
-// One checklist section for the combined comment (heading + verbatim reviewer output), so oversize
-// truncation can shrink the longest BODY without ever dropping a verdict heading.
-class CommentSection {
-    heading;
-    body;
-    constructor(heading, body) {
-        this.heading = heading;
-        this.body = body;
-    }
-}
+/**
+ * Hidden marker on the FULL-DASHBOARD comment — the "1st comment" the PR description points at — so
+ * finish PATCHes its own comment on every push instead of appending a new one, exactly like the checklist
+ * comment (see ChecklistCommentRenderer, which owns the 2nd).
+ *
+ * This comment did not exist before the PR description became the git-log body: the dashboard WAS the
+ * description. Moving it here is what keeps a risk table out of every squash commit on main.
+ */
+exports.DETAIL_COMMENT_MARKER = '<!-- webpieces-pr-detail v1 -->';
+/**
+ * Footer on the full-dashboard comment. Names the tooling by REPO URL so a reader landing on a
+ * generated comment in any consumer repo can find what generated it.
+ *
+ * It deliberately no longer asserts "build ran via nx affected — not self-attested": that sentence was
+ * hard-coded and therefore wrong on every repo whose `buildCommand` is not nx. The build command is now
+ * named for real, from config, in the PR-body footer — see {@link Dashboard.renderPrBody}.
+ */
+const DETAIL_COMMENT_FOOTER = 'Generated by https://github.com/deanhiller/webpieces-ts  wp-finish-upsert-pr';
+/**
+ * The last bullet of the PR description, and therefore of every squash commit body.
+ *
+ * Positional ("1st"/"2nd") on purpose — it is what a reader of `git log` can actually act on, far more
+ * useful than naming an HTML marker they cannot see. On a PR opened by an OLDER release the checklist
+ * comment already exists, so the dashboard comment lands second and this reads one off for that PR's
+ * remaining life; it is cosmetic and self-corrects on the next PR.
+ */
+const DETAIL_POINTER = '(Full dashboard in 1st comment, reviewer checklist in 2nd — kept out of git log)';
 class GateResult {
     name;
     warningColor; // 'yellow' | 'red' — the color shown WHEN files matched (green is implicit)
@@ -87,8 +99,21 @@ class DashboardInput {
     mainHead;
     review; // AI-authored risk/violations/summary (from review.json)
     checklists; // consumer checklists this branch triggered; [] for non-adopting repos
+    /**
+     * `commands.pr-gate.buildCommand` VERBATIM, named in the PR-body footer so `git log` records WHICH
+     * command vouched for the commit. Read from config rather than hard-coded because the footer used to
+     * assert "build ran via nx affected" on every repo, including those whose buildCommand is not nx.
+     *
+     * REQUIRED, with no default, and `checklists` lost its `= []` for the same reason. A defaulted
+     * `buildCommand: string = ''` let every pre-existing 9-argument construction keep compiling while
+     * silently rendering a footer that claims nothing — an absence that quietly means "no build was
+     * named", which is the widening-by-omission the compatibility policy calls out. Making it required
+     * means every caller states what vouched for the commit, and the empty string stays available for a
+     * repo that genuinely has no build command, but only when someone writes it down.
+     */
+    buildCommand;
     // eslint-disable-next-line @typescript-eslint/max-params
-    constructor(title, gateResults, disables, buildPassed, forkPoint, featureHead, mainHead, review, checklists = []) {
+    constructor(title, gateResults, disables, buildPassed, forkPoint, featureHead, mainHead, review, checklists, buildCommand) {
         this.title = title;
         this.gateResults = gateResults;
         this.disables = disables;
@@ -98,6 +123,7 @@ class DashboardInput {
         this.mainHead = mainHead;
         this.review = review;
         this.checklists = checklists;
+        this.buildCommand = buildCommand;
     }
 }
 exports.DashboardInput = DashboardInput;
@@ -134,7 +160,20 @@ let Dashboard = class Dashboard {
         }
         return new DisableCounts(webpiecesCount, eslintCount, Array.from(rules).sort());
     }
-    renderDashboard(input) {
+    /**
+     * The FULL dashboard — every row (green included), the whole summary, the 3-point hash points.
+     *
+     * This is the **1st PR comment**, not the PR description. It used to be the description, and that is
+     * exactly what put it into main's history: GitHub's `squash_merge_commit_message: PR_BODY` copies the
+     * description verbatim into the squash commit, so every `git log` entry carried the risk table, the
+     * hash points and the gate token. The description now holds {@link renderPrBody}'s compact form, and
+     * everything long-form lives here where a reader can open it and `git log` never sees it.
+     *
+     * Machine-facing content belongs HERE too — this comment carries the HMAC gate token. That is the
+     * whole rule that keeps the description clean: an HTML comment is invisible in rendered markdown but
+     * perfectly visible in `git log`, so nothing hidden may live in the description.
+     */
+    renderDetailComment(input) {
         const lines = [];
         lines.push('## 🚦 PR Gate Dashboard');
         lines.push('');
@@ -165,271 +204,75 @@ let Dashboard = class Dashboard {
         lines.push(`- Feature HEAD (B): \`${input.featureHead.slice(0, 12)}\``);
         lines.push(`- Main HEAD (C): \`${input.mainHead.slice(0, 12)}\``);
         lines.push('');
-        lines.push('<sub>🤖 Generated by `pnpm wp-finish-upsert-pr` (build ran via nx affected — not self-attested).</sub>');
+        lines.push(`<sub>🤖 ${DETAIL_COMMENT_FOOTER}</sub>`);
         return lines.join('\n');
     }
     /**
-     * The ONE combined PR comment. Two halves, in this order:
+     * The PR DESCRIPTION — which is also, byte for byte, the squash-commit body that lands in main.
      *
-     *   1. A roll-up plus the FULL ROSTER — every DEFINED checklist as a checkbox, each with a sub-bullet
-     *      stating exactly which globs fired against which files, or which did not and out of how many.
-     *      Skipped checklists are listed on purpose: skipping is the normal, healthy outcome, and a comment
-     *      that names only the reviewers that fired cannot distinguish "evaluated and irrelevant" from
-     *      "never wired up" — nor answer "why did the DB reviewer run on my frontend PR?".
-     *   2. One section per reviewer that RAN, carrying its full `output` — the depth a verdict line throws
-     *      away. Overridden first, then warned, then passed: a reader should meet the exceptions first.
+     * ─── Why one string serves both ─────────────────────────────────────────────────────────────────
+     * There used to be two: a long dashboard in the description and this compact form passed to
+     * `gh pr merge --body-file`. That made the good `git log` reachable ONLY through an explicit
+     * `--body-file` merge, because every other route (the GitHub Merge button, a bare `gh pr merge`)
+     * takes its body from the repo's `squash_merge_commit_message`, and on `PR_BODY` that copied the
+     * whole dashboard into history. Two repos ran that way for months.
      *
-     * Idempotent: keyed by the hidden marker so wp-finish PATCHes this same comment on every push.
-     */
-    renderChecklistComment(rows, provenanceVerified, baseResolved) {
-        const ran = this.ranOrdered(rows);
-        const prov = provenanceVerified
-            ? '_Each reviewer ran as its own independent subagent, verified from the Claude Code harness._'
-            : '_⚠️ Reviewer provenance was NOT verified (no Claude Code session) — treat these as unverified._';
-        // The roster lives in the HEADER, never in a section: fitComment only ever shrinks section bodies,
-        // so a roster line can never be the thing an oversize comment silently drops.
-        const lines = [exports.CHECKLIST_COMMENT_MARKER, this.rollupHeader(rows, baseResolved)];
-        // No reviewer ran ⇒ no provenance claim to make. Printing one either way would attest to nothing.
-        if (ran.length > 0)
-            lines.push(prov);
-        lines.push('', `### Checklists (all ${rows.length})`);
-        for (const row of rows)
-            lines.push(this.rosterBullet(row));
-        const header = lines.join('\n');
-        if (ran.length === 0) {
-            return `${header}\n\n${this.nothingRanNote(rows)}`;
-        }
-        return this.fitComment(`${header}\n\n### Reviews that ran`, ran.map((r) => this.commentSection(r)));
-    }
-    /**
-     * The closing note when no reviewer produced a verdict. The original wording — "every configured
-     * checklist was evaluated and none of them applied" — is an all-clear, and it becomes FALSE the moment a
-     * checklist did apply and was declined. That sentence under a PR nobody reviewed is precisely the
-     * misreport this feature could otherwise introduce, so the declined case gets its own words.
-     */
-    nothingRanNote(rows) {
-        const declined = rows.filter((r) => this.declined(r));
-        if (declined.length === 0) {
-            return '_No reviewer had to run on this diff — every configured checklist was evaluated and none of them applied._';
-        }
-        return (`_No reviewer ran. ${declined.length} OPTIONAL checklist(s) DID apply to this diff and were not ` +
-            `run; the rest were evaluated and did not apply._`);
-    }
-    // The roll-up line. `baseResolved:false` replaces it entirely: with no fork point the changed-file set is
-    // EMPTY, so nothing matched — including patternless ALWAYS-RUNS checklists — and reporting that as
-    // "all skipped ✅" would post a green all-clear for a PR where nothing was actually evaluated.
-    rollupHeader(rows, baseResolved) {
-        if (!baseResolved) {
-            return (`## 🔍 Company review checklists — ⚠️ NOT EVALUATED (${rows.length} defined)\n` +
-                `_No diff base (fork point of main) could be resolved, so no checklist was matched against ` +
-                `anything. This is **not** an all-clear._`);
-        }
-        const ran = rows.filter((r) => this.reviewerRan(r));
-        const declined = rows.filter((r) => this.declined(r));
-        const skipped = rows.length - ran.length - declined.length;
-        const parts = [];
-        for (const pair of this.rollupCounts(ran))
-            parts.push(pair);
-        const breakdown = parts.length > 0 ? ` (${parts.join(' · ')})` : '';
-        const skip = skipped > 0 ? ` · ${skipped} skipped ✅` : '';
-        // Counted SEPARATELY from "skipped", and without a ✅. A declined optional review is a legitimate
-        // outcome, but it is not the same good news as a checklist that had nothing to look at — folding the
-        // two together would let a PR that declined every optional review read as fully covered.
-        const notRun = declined.length > 0 ? ` · ${declined.length} optional not run` : '';
-        return `## 🔍 Company review checklists — ${rows.length} defined · ${ran.length} ran${breakdown}${skip}${notRun}`;
-    }
-    // `🟢 2 · 🟡 1` — only the non-zero buckets, so a clean run reads as one number rather than four.
-    rollupCounts(ran) {
-        const counts = [];
-        const emojiFor = ['🟢', '🟡', '🟠'];
-        const statusFor = [rules_config_1.CK_PASS, rules_config_1.CK_WARN, rules_config_1.CK_OVERRIDDEN];
-        statusFor.forEach((status, i) => {
-            const n = ran.filter((r) => r.status === status).length;
-            if (n > 0)
-                counts.push(`${emojiFor[i]} ${n}`);
-        });
-        return counts;
-    }
-    // One roster line + its why sub-bullet. A checked box means a reviewer ran; an unchecked one means the
-    // checklist was evaluated and did not apply, which the words state as the good news it is.
-    rosterBullet(row) {
-        const box = this.reviewerRan(row) ? '- [x]' : '- [ ]';
-        return (`${box} ${this.verdictEmoji(row)} **${row.subagent}**${this.optionalTag(row)} — ` +
-            `${this.verdictWords(row)}${this.evidenceSuffix(row)}\n` +
-            `  - ${this.whyLine(row)}`);
-    }
-    /**
-     * Did a reviewer actually produce a verdict for this row?
+     * Making the DESCRIPTION the compact form inverts it: `PR_BODY` now yields exactly the right commit,
+     * so the UI button, a bare `gh pr merge`, `wp-land-pr` and finish's own auto-merge all converge on
+     * identical bytes. The consumer requirement is two repo settings — `squash_merge_commit_title:
+     * PR_TITLE` and `squash_merge_commit_message: PR_BODY` — not a config key and not a command anyone
+     * has to remember. That convergence is the point, and `pr-body-is-merge-body.spec.ts` pins it.
      *
-     * `row.ran` is really "this checklist APPLIED to the diff" — for a required checklist the two are the
-     * same thing, because the PR cannot open otherwise, and the field was named before optional checklists
-     * existed. For a DECLINED optional one they diverge, and using `ran` alone would put a checked box and a
-     * reviewer section on a review that nobody performed.
-     */
-    reviewerRan(row) {
-        return row.ran && !this.declined(row);
-    }
-    // Applied, optional, and carrying no verdict — i.e. the human was offered this review and said no (or
-    // `--no-optional` skipped the offer). Never true of a required checklist: one of those with no verdict
-    // does not reach a PR at all.
-    declined(row) {
-        return row.ran && !row.required && (row.status === rules_config_1.CK_MISSING || row.status === '');
-    }
-    // Marks which rows the human could have declined. Without it a reader cannot tell a review that was
-    // skippable from one that simply passed, and so cannot judge how much this PR was actually reviewed.
-    optionalTag(row) {
-        return row.required ? '' : ' _(optional)_';
-    }
-    /**
-     * Whether the reviewer demonstrably opened the diff, read from its own transcript. A QUALITY signal and
-     * never a blocker (see SubagentProvenanceService.evidenceFor) — but published, because "wrote a verdict
-     * without reading the change" is exactly what a reader of this comment would want to weigh.
-     */
-    evidenceSuffix(row) {
-        if (!this.reviewerRan(row) || row.diffRead === '')
-            return '';
-        return row.diffRead === 'yes' ? ' _(diff read ✓)_' : ' _(⚠️ no diff read recorded)_';
-    }
-    verdictEmoji(row) {
-        if (!this.reviewerRan(row))
-            return '⚪';
-        if (row.status === rules_config_1.CK_PASS)
-            return '🟢';
-        if (row.status === rules_config_1.CK_WARN)
-            return '🟡';
-        if (row.status === rules_config_1.CK_OVERRIDDEN)
-            return '🟠';
-        if (row.status === rules_config_1.CK_FAIL)
-            return '🔴';
-        return '⚪';
-    }
-    // SHORT words for a roster line / section heading. Short on purpose: the reviewer's own output and any
-    // override justification get their own section below, and a roster exists to be scanned.
-    verdictWords(row) {
-        // Two different unchecked boxes, two different sentences. "Not applicable" is the diff's doing;
-        // "not run" is a person's, and reporting the second as the first would quietly credit a review that
-        // a human deliberately declined.
-        if (this.declined(row))
-            return 'OPTIONAL — applied to this diff but was NOT run (not selected)';
-        if (!row.ran)
-            return 'skipped, not applicable to this diff (expected ✅)';
-        if (row.status === rules_config_1.CK_PASS)
-            return 'passed';
-        if (row.status === rules_config_1.CK_WARN)
-            return 'passed with concerns';
-        if (row.status === rules_config_1.CK_OVERRIDDEN)
-            return 'OVERRIDDEN — shipped with a stated justification';
-        if (row.status === rules_config_1.CK_FAIL)
-            return 'FAILED review';
-        if (row.status === rules_config_1.CK_MISSING)
-            return 'no verdict written';
-        return `unknown verdict (${row.status})`;
-    }
-    /**
-     * WHY this checklist ran or did not — the line that answers "why was this reviewer involved?". Branches
-     * on `configuredPatterns`, NEVER on `firedPatterns.length`: a patternless checklist and a skipped one
-     * both fired zero globs and they mean opposite things, so keying off the fired list would tell every
-     * skipped checklist's reader that the whole diff had been in its scope.
+     * ─── The shape, and why each part earns its line ────────────────────────────────────────────────
+     * The URL leads, labelled `(for git log)` so nobody deletes it as redundant while reading the PR on
+     * GitHub — on the page it is obviously the page you are on; in `git log` it is the only way back.
+     * Then the risk score (always). Then ONLY the non-green flags: a commit log should surface what
+     * stands out, and the green rows are in the 1st comment. The last bullet is always the pointer to
+     * that comment, so a reader of main's history is never left thinking this is all there was. Then the
+     * summary capped at 4 sentences, then the footer naming the build command that vouched for it.
+     *
+     * The hidden gate-token marker is appended AFTER this by the caller, so it is the very last line of
+     * the description and therefore of the commit. It stays an HTML comment — invisible on the PR page,
+     * visible in `git log` — which is a deliberate accepted trade: the alternative was reshaping a live
+     * CI-critical surface that two consumer repos verify on every PR, to save one line of history.
      */
-    whyLine(row) {
-        const total = row.changedFileCount;
-        if (row.configuredPatterns.length === 0) {
-            // State the fact, not a suspicion. Patternless is a deliberate configuration — an always-runs
-            // gate (every PR names a ticket, every PR has an owner) is exactly what it is FOR — so telling
-            // every such row to "add `patterns` if that is not intended" nags the repos that meant it, on
-            // every PR, forever. A reader who wants to know whether it was intended can read the config.
-            return (`ALWAYS RUNS (no patterns) — whole diff in scope, ${total} changed file(s): ` +
-                `${(0, rules_config_1.formatFileList)(row.matchedFiles)}`);
-        }
-        const configured = this.asCode(row.configuredPatterns);
-        if (row.firedPatterns.length === 0) {
-            return `${configured} matched 0 of ${total} changed file(s)`;
-        }
-        return (`matched ${this.asCode(row.firedPatterns)} → ${row.matchedFiles.length} of ${total} ` +
-            `changed file(s): ${(0, rules_config_1.formatFileList)(row.matchedFiles)}`);
-    }
-    asCode(patterns) {
-        return patterns.map((p) => `\`${p}\``).join(', ');
-    }
-    // Reviewers that ran, exceptions first (overridden → warned → passed) so a reader meets what needs
-    // attention before a wall of green.
-    ranOrdered(rows) {
-        const rank = [rules_config_1.CK_OVERRIDDEN, rules_config_1.CK_WARN, rules_config_1.CK_PASS];
-        return rows
-            .filter((r) => this.reviewerRan(r))
-            .slice()
-            .sort((a, b) => this.rankOf(rank, a.status) - this.rankOf(rank, b.status));
-    }
-    rankOf(rank, status) {
-        const idx = rank.indexOf(status);
-        return idx < 0 ? rank.length : idx;
-    }
-    commentSection(row) {
-        const heading = `#### ${this.verdictEmoji(row)} ${row.subagent} — ${this.verdictWords(row)}`;
-        const body = row.detail.trim() !== '' ? row.detail.trim() : '_(reviewer recorded no output)_';
-        return new CommentSection(heading, body);
-    }
-    // Keep the comment under GitHub's size cap by shrinking the LONGEST section body first (so a short
-    // overridden note is never cut to make room for a long passing one), never dropping a verdict heading.
-    fitComment(header, sections) {
-        const assemble = () => `${header}\n\n${sections.map((s) => `${s.heading}\n\n${s.body}`).join('\n\n')}`;
-        const trunc = '\n\n…_[truncated to fit the GitHub comment size limit]_';
-        let out = assemble();
-        while (out.length > COMMENT_LIMIT) {
-            const idx = this.longestBodyIndex(sections);
-            if (idx < 0 || sections[idx].body.length <= trunc.length + 1)
-                break;
-            const over = out.length - COMMENT_LIMIT;
-            const keep = Math.max(0, sections[idx].body.length - over - trunc.length - 8);
-            sections[idx].body = sections[idx].body.slice(0, keep).trimEnd() + trunc;
-            out = assemble();
-        }
-        return out;
-    }
-    longestBodyIndex(sections) {
-        let idx = -1;
-        let max = -1;
-        sections.forEach((s, i) => {
-            if (s.body.length > max) {
-                max = s.body.length;
-                idx = i;
-            }
-        });
-        return idx;
-    }
-    // The squash-merge COMMIT body that lands in main's history (subject is the PR title, passed to
-    // `gh pr merge --subject`). Deliberately compact — unlike the full PR-body dashboard: the PR link
-    // FIRST, then the risk score (always), every NON-green flag (green rows omitted — a commit log
-    // should surface only what stands out), and the summary capped at 4 sentences.
-    //
-    // The link leads because `git log` reads subject-then-body top-down, and the ONE thing a reader of
-    // main's history wants from a squash commit is the way back to the full dashboard. It used to be the
-    // last line, below a summary that `git log --oneline`-adjacent tools and pagers routinely cut off,
-    // which put the only navigable thing in the commit in the one place most likely to be unread.
-    renderCommitBody(input, prUrl) {
+    renderPrBody(input, prUrl) {
         const lines = [];
         if (prUrl !== '') {
-            lines.push(prUrl);
+            lines.push(`${prUrl} (for git log)`);
             lines.push('');
         }
         lines.push(`Risk: ${this.riskBar(input.review.riskScore)} ${input.review.riskScore}/100 ${input.review.riskEmoji} (${input.review.riskLevel})`);
         lines.push('');
         const flags = this.nonGreenFlags(input);
-        if (flags.length === 0) {
-            lines.push('Flags: 🟢 all green');
-        }
-        else {
-            lines.push('Flags (non-green):');
-            for (const flag of flags)
-                lines.push(`- ${flag}`);
-        }
+        lines.push(flags.length === 0 ? 'Flags: 🟢 all green' : 'Flags (non-green):');
+        for (const flag of flags)
+            lines.push(`- ${flag}`);
+        // ALWAYS the last bullet, green case included. Without it the compact body reads as the whole
+        // record, and the reader never learns that every green row, the full summary and each reviewer's
+        // output are one click away.
+        lines.push(`- ${DETAIL_POINTER}`);
         const summary = this.firstSentences(input.review.summary.trim(), 4);
         if (summary !== '') {
             lines.push('');
             lines.push(summary);
         }
+        lines.push('');
+        lines.push(this.prBodyFooter(input.buildCommand));
         return lines.join('\n');
     }
+    /**
+     * The footer, naming the build command from `commands.pr-gate.buildCommand` VERBATIM.
+     *
+     * No backticks: this string's primary home is `git log` in a terminal, where markdown ticks are
+     * literal punctuation. "run locally" is the honest claim — this is the LOCAL gate's receipt, and the
+     * server-side proof is the gate token in the 1st comment, not this sentence.
+     */
+    prBodyFooter(buildCommand) {
+        const cmd = buildCommand.trim();
+        const ran = cmd === '' ? '' : ` (${cmd} run locally)`;
+        return `Generated by webpieces-ts wp-finish-upsert-pr${ran}`;
+    }
     // Every dashboard row that is NOT green, as a flat bullet list for the commit body. Green rows
     // (build passed, gate did not match, zero disables/violations) are intentionally omitted.
     nonGreenFlags(input) {