@webpieces/pr-gate 0.4.564 → 0.4.565

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/pr-gate",
-  "version": "0.4.564",
+  "version": "0.4.565",
   "description": "Gated PR system: 3-point squash-merge, merge validation gate, and red/yellow/green PR dashboard. Standalone scripts, no Nx dependency required.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -26,7 +26,7 @@
     "directory": "packages/tooling/pr-gate"
   },
   "dependencies": {
-    "@webpieces/rules-config": "0.4.564",
+    "@webpieces/rules-config": "0.4.565",
     "@inversifyjs/binding-decorators": "1.1.5",
     "inversify": "7.10.4",
     "reflect-metadata": "0.2.2"

package/src/dashboard/checklist-comment-row.d.ts

@@ -0,0 +1,42 @@
+/**
+ * One roster line of the checklist COMMENT: a defined checklist, whether its reviewer ran, and the evidence
+ * for WHY. Deliberately separate from {@link ChecklistRow} rather than five more fields on it — ChecklistRow
+ * also feeds the PR body and the squash-commit body, and roster evidence has no business travelling into
+ * main's git history or through every DashboardInput construction site.
+ *
+ * Kept in pr-gate, not rules-config: the shape of a GitHub comment is this package's concern, and
+ * rules-config is the dependency, not the dependent. Its own FILE (rather than sitting in dashboard.ts)
+ * per the one-class-per-file convention — dashboard.ts is a large renderer against a hard max-file-lines
+ * limit, while this is a data class its consumers construct directly: finish builds these, Dashboard only
+ * reads them.
+ */
+export declare class ChecklistCommentRow {
+    subagent: string;
+    status: string;
+    detail: string;
+    ran: boolean;
+    configuredPatterns: string[];
+    firedPatterns: string[];
+    matchedFiles: string[];
+    changedFileCount: number;
+    /**
+     * Whether this reviewer's own transcript shows it OPENING the extracted diff.
+     *
+     * '' = not assessed (no Claude Code session, or nothing was materialized) and prints nothing — "no
+     * evidence recorded" and "evidence says it never looked" are different claims, and conflating them
+     * would accuse a reviewer that ran perfectly well in CI. 'yes' | 'no' otherwise. Defaulted, so every
+     * existing construction site is unchanged.
+     */
+    diffRead: string;
+    /**
+     * The checklist's configured `required`. Published because "no verdict" means two opposite things and the
+     * roster is the only place a reader can tell them apart: a REQUIRED checklist with no verdict could not
+     * have opened this PR at all, so seeing one means something went wrong; an OPTIONAL one with no verdict
+     * is a review the human was offered and declined, which is the feature working.
+     *
+     * Defaulted to the blocking value so every existing construction site is unchanged and a row that forgets
+     * to set it is reported as the stricter of the two.
+     */
+    required: boolean;
+    constructor(subagent: string, status: string, detail: string, ran: boolean, configuredPatterns: string[], firedPatterns: string[], matchedFiles: string[], changedFileCount: number);
+}

package/src/dashboard/checklist-comment-row.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChecklistCommentRow = void 0;
+/**
+ * One roster line of the checklist COMMENT: a defined checklist, whether its reviewer ran, and the evidence
+ * for WHY. Deliberately separate from {@link ChecklistRow} rather than five more fields on it — ChecklistRow
+ * also feeds the PR body and the squash-commit body, and roster evidence has no business travelling into
+ * main's git history or through every DashboardInput construction site.
+ *
+ * Kept in pr-gate, not rules-config: the shape of a GitHub comment is this package's concern, and
+ * rules-config is the dependency, not the dependent. Its own FILE (rather than sitting in dashboard.ts)
+ * per the one-class-per-file convention — dashboard.ts is a large renderer against a hard max-file-lines
+ * limit, while this is a data class its consumers construct directly: finish builds these, Dashboard only
+ * reads them.
+ */
+class ChecklistCommentRow {
+    subagent; // the reviewer / checklist id
+    status; // CK_* verdict; '' when it did not run
+    detail; // verbatim reviewer output
+    ran; // false = skipped, which is a NORMAL, healthy outcome
+    // The checklist's CONFIGURED globs. The only safe signal for "always runs": a patternless checklist and
+    // a skipped one both have an empty `firedPatterns`, and they mean opposite things.
+    configuredPatterns;
+    firedPatterns; // which configured globs actually hit a changed file
+    matchedFiles;
+    changedFileCount; // how many files were considered at all — "0 of N" needs the N
+    /**
+     * Whether this reviewer's own transcript shows it OPENING the extracted diff.
+     *
+     * '' = not assessed (no Claude Code session, or nothing was materialized) and prints nothing — "no
+     * evidence recorded" and "evidence says it never looked" are different claims, and conflating them
+     * would accuse a reviewer that ran perfectly well in CI. 'yes' | 'no' otherwise. Defaulted, so every
+     * existing construction site is unchanged.
+     */
+    diffRead = '';
+    /**
+     * The checklist's configured `required`. Published because "no verdict" means two opposite things and the
+     * roster is the only place a reader can tell them apart: a REQUIRED checklist with no verdict could not
+     * have opened this PR at all, so seeing one means something went wrong; an OPTIONAL one with no verdict
+     * is a review the human was offered and declined, which is the feature working.
+     *
+     * Defaulted to the blocking value so every existing construction site is unchanged and a row that forgets
+     * to set it is reported as the stricter of the two.
+     */
+    required = true;
+    // eslint-disable-next-line @typescript-eslint/max-params
+    constructor(subagent, status, detail, ran, configuredPatterns, firedPatterns, matchedFiles, changedFileCount) {
+        this.subagent = subagent;
+        this.status = status;
+        this.detail = detail;
+        this.ran = ran;
+        this.configuredPatterns = configuredPatterns;
+        this.firedPatterns = firedPatterns;
+        this.matchedFiles = matchedFiles;
+        this.changedFileCount = changedFileCount;
+    }
+}
+exports.ChecklistCommentRow = ChecklistCommentRow;
+//# sourceMappingURL=checklist-comment-row.js.map

package/src/dashboard/checklist-comment-row.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checklist-comment-row.js","sourceRoot":"","sources":["../../../../../../packages/tooling/pr-gate/src/dashboard/checklist-comment-row.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;GAWG;AACH,MAAa,mBAAmB;IAC5B,QAAQ,CAAS,CAAC,8BAA8B;IAChD,MAAM,CAAS,CAAC,uCAAuC;IACvD,MAAM,CAAS,CAAC,2BAA2B;IAC3C,GAAG,CAAU,CAAC,sDAAsD;IACpE,wGAAwG;IACxG,mFAAmF;IACnF,kBAAkB,CAAW;IAC7B,aAAa,CAAW,CAAC,qDAAqD;IAC9E,YAAY,CAAW;IACvB,gBAAgB,CAAS,CAAC,+DAA+D;IACzF;;;;;;;OAOG;IACH,QAAQ,GAAW,EAAE,CAAC;IACtB;;;;;;;;OAQG;IACH,QAAQ,GAAY,IAAI,CAAC;IAEzB,yDAAyD;IACzD,YACI,QAAgB,EAChB,MAAc,EACd,MAAc,EACd,GAAY,EACZ,kBAA4B,EAC5B,aAAuB,EACvB,YAAsB,EACtB,gBAAwB;QAExB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;QAC7C,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;IAC7C,CAAC;CACJ;AAnDD,kDAmDC","sourcesContent":["/**\n * One roster line of the checklist COMMENT: a defined checklist, whether its reviewer ran, and the evidence\n * for WHY. Deliberately separate from {@link ChecklistRow} rather than five more fields on it — ChecklistRow\n * also feeds the PR body and the squash-commit body, and roster evidence has no business travelling into\n * main's git history or through every DashboardInput construction site.\n *\n * Kept in pr-gate, not rules-config: the shape of a GitHub comment is this package's concern, and\n * rules-config is the dependency, not the dependent. Its own FILE (rather than sitting in dashboard.ts)\n * per the one-class-per-file convention — dashboard.ts is a large renderer against a hard max-file-lines\n * limit, while this is a data class its consumers construct directly: finish builds these, Dashboard only\n * reads them.\n */\nexport class ChecklistCommentRow {\n    subagent: string; // the reviewer / checklist id\n    status: string; // CK_* verdict; '' when it did not run\n    detail: string; // verbatim reviewer output\n    ran: boolean; // false = skipped, which is a NORMAL, healthy outcome\n    // The checklist's CONFIGURED globs. The only safe signal for \"always runs\": a patternless checklist and\n    // a skipped one both have an empty `firedPatterns`, and they mean opposite things.\n    configuredPatterns: string[];\n    firedPatterns: string[]; // which configured globs actually hit a changed file\n    matchedFiles: string[];\n    changedFileCount: number; // how many files were considered at all — \"0 of N\" needs the N\n    /**\n     * Whether this reviewer's own transcript shows it OPENING the extracted diff.\n     *\n     * '' = not assessed (no Claude Code session, or nothing was materialized) and prints nothing — \"no\n     * evidence recorded\" and \"evidence says it never looked\" are different claims, and conflating them\n     * would accuse a reviewer that ran perfectly well in CI. 'yes' | 'no' otherwise. Defaulted, so every\n     * existing construction site is unchanged.\n     */\n    diffRead: string = '';\n    /**\n     * The checklist's configured `required`. Published because \"no verdict\" means two opposite things and the\n     * roster is the only place a reader can tell them apart: a REQUIRED checklist with no verdict could not\n     * have opened this PR at all, so seeing one means something went wrong; an OPTIONAL one with no verdict\n     * is a review the human was offered and declined, which is the feature working.\n     *\n     * Defaulted to the blocking value so every existing construction site is unchanged and a row that forgets\n     * to set it is reported as the stricter of the two.\n     */\n    required: boolean = true;\n\n    // eslint-disable-next-line @typescript-eslint/max-params\n    constructor(\n        subagent: string,\n        status: string,\n        detail: string,\n        ran: boolean,\n        configuredPatterns: string[],\n        firedPatterns: string[],\n        matchedFiles: string[],\n        changedFileCount: number,\n    ) {\n        this.subagent = subagent;\n        this.status = status;\n        this.detail = detail;\n        this.ran = ran;\n        this.configuredPatterns = configuredPatterns;\n        this.firedPatterns = firedPatterns;\n        this.matchedFiles = matchedFiles;\n        this.changedFileCount = changedFileCount;\n    }\n}\n"]}

package/src/dashboard/dashboard.d.ts

@@ -1,4 +1,5 @@
 import { GateDefinition, ReviewJson } from '@webpieces/rules-config';
+import { ChecklistCommentRow } from './checklist-comment-row';
 export declare const CHECKLIST_COMMENT_MARKER = "<!-- webpieces-checklists v2 -->";
 export declare class GateResult {
     name: string;
@@ -12,35 +13,6 @@ export declare class ChecklistRow {
     detail: string;
     constructor(title: string, status: string, detail?: string);
 }
-/**
- * One roster line of the checklist COMMENT: a defined checklist, whether its reviewer ran, and the evidence
- * for WHY. Deliberately separate from {@link ChecklistRow} rather than five more fields on it — ChecklistRow
- * also feeds the PR body and the squash-commit body, and roster evidence has no business travelling into
- * main's git history or through every DashboardInput construction site.
- *
- * Kept in pr-gate, not rules-config: the shape of a GitHub comment is this package's concern, and
- * rules-config is the dependency, not the dependent.
- */
-export declare class ChecklistCommentRow {
-    subagent: string;
-    status: string;
-    detail: string;
-    ran: boolean;
-    configuredPatterns: string[];
-    firedPatterns: string[];
-    matchedFiles: string[];
-    changedFileCount: number;
-    /**
-     * Whether this reviewer's own transcript shows it OPENING the extracted diff.
-     *
-     * '' = not assessed (no Claude Code session, or nothing was materialized) and prints nothing — "no
-     * evidence recorded" and "evidence says it never looked" are different claims, and conflating them
-     * would accuse a reviewer that ran perfectly well in CI. 'yes' | 'no' otherwise. Defaulted, so every
-     * existing construction site is unchanged.
-     */
-    diffRead: string;
-    constructor(subagent: string, status: string, detail: string, ran: boolean, configuredPatterns: string[], firedPatterns: string[], matchedFiles: string[], changedFileCount: number);
-}
 export declare class DisableCounts {
     webpiecesCount: number;
     eslintCount: number;
@@ -78,9 +50,27 @@ export declare class Dashboard {
      * Idempotent: keyed by the hidden marker so wp-finish PATCHes this same comment on every push.
      */
     renderChecklistComment(rows: readonly ChecklistCommentRow[], provenanceVerified: boolean, baseResolved: boolean): string;
+    /**
+     * 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.
+     */
+    private nothingRanNote;
     private rollupHeader;
     private rollupCounts;
     private rosterBullet;
+    /**
+     * Did a reviewer actually produce a verdict for this row?
+     *
+     * `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.
+     */
+    private reviewerRan;
+    private declined;
+    private optionalTag;
     /**
      * 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

package/src/dashboard/dashboard.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Dashboard = exports.DashboardInput = exports.DisableCounts = exports.ChecklistCommentRow = exports.ChecklistRow = exports.GateResult = exports.CHECKLIST_COMMENT_MARKER = void 0;
+exports.Dashboard = exports.DashboardInput = exports.DisableCounts = exports.ChecklistRow = exports.GateResult = exports.CHECKLIST_COMMENT_MARKER = void 0;
 const tslib_1 = require("tslib");
 const rules_config_1 = require("@webpieces/rules-config");
 const inversify_1 = require("inversify");
@@ -47,48 +47,6 @@ class ChecklistRow {
     }
 }
 exports.ChecklistRow = ChecklistRow;
-/**
- * One roster line of the checklist COMMENT: a defined checklist, whether its reviewer ran, and the evidence
- * for WHY. Deliberately separate from {@link ChecklistRow} rather than five more fields on it — ChecklistRow
- * also feeds the PR body and the squash-commit body, and roster evidence has no business travelling into
- * main's git history or through every DashboardInput construction site.
- *
- * Kept in pr-gate, not rules-config: the shape of a GitHub comment is this package's concern, and
- * rules-config is the dependency, not the dependent.
- */
-class ChecklistCommentRow {
-    subagent; // the reviewer / checklist id
-    status; // CK_* verdict; '' when it did not run
-    detail; // verbatim reviewer output
-    ran; // false = skipped, which is a NORMAL, healthy outcome
-    // The checklist's CONFIGURED globs. The only safe signal for "always runs": a patternless checklist and
-    // a skipped one both have an empty `firedPatterns`, and they mean opposite things.
-    configuredPatterns;
-    firedPatterns; // which configured globs actually hit a changed file
-    matchedFiles;
-    changedFileCount; // how many files were considered at all — "0 of N" needs the N
-    /**
-     * Whether this reviewer's own transcript shows it OPENING the extracted diff.
-     *
-     * '' = not assessed (no Claude Code session, or nothing was materialized) and prints nothing — "no
-     * evidence recorded" and "evidence says it never looked" are different claims, and conflating them
-     * would accuse a reviewer that ran perfectly well in CI. 'yes' | 'no' otherwise. Defaulted, so every
-     * existing construction site is unchanged.
-     */
-    diffRead = '';
-    // eslint-disable-next-line @typescript-eslint/max-params
-    constructor(subagent, status, detail, ran, configuredPatterns, firedPatterns, matchedFiles, changedFileCount) {
-        this.subagent = subagent;
-        this.status = status;
-        this.detail = detail;
-        this.ran = ran;
-        this.configuredPatterns = configuredPatterns;
-        this.firedPatterns = firedPatterns;
-        this.matchedFiles = matchedFiles;
-        this.changedFileCount = changedFileCount;
-    }
-}
-exports.ChecklistCommentRow = ChecklistCommentRow;
 /**
  * One severity bucket of the rolled-up **Checklists** dashboard row: its emoji, the words that describe it,
  * and which checklists landed in it. Data-only.
@@ -239,11 +197,24 @@ let Dashboard = class Dashboard {
             lines.push(this.rosterBullet(row));
         const header = lines.join('\n');
         if (ran.length === 0) {
-            return (`${header}\n\n_No reviewer had to run on this diff — every configured checklist was ` +
-                `evaluated and none of them applied._`);
+            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.
@@ -253,14 +224,19 @@ let Dashboard = class Dashboard {
                 `_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) => r.ran);
-        const skipped = rows.length - ran.length;
+        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 ✅` : '';
-        return `## 🔍 Company review checklists — ${rows.length} defined · ${ran.length} ran${breakdown}${skip}`;
+        // 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) {
@@ -277,22 +253,45 @@ let Dashboard = class Dashboard {
     // 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 = row.ran ? '- [x]' : '- [ ]';
-        return (`${box} ${this.verdictEmoji(row)} **${row.subagent}** — ${this.verdictWords(row)}${this.evidenceSuffix(row)}\n` +
+        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?
+     *
+     * `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 (!row.ran || row.diffRead === '')
+        if (!this.reviewerRan(row) || row.diffRead === '')
             return '';
         return row.diffRead === 'yes' ? ' _(diff read ✓)_' : ' _(⚠️ no diff read recorded)_';
     }
     verdictEmoji(row) {
-        if (!row.ran)
+        if (!this.reviewerRan(row))
             return '⚪';
         if (row.status === rules_config_1.CK_PASS)
             return '🟢';
@@ -307,6 +306,11 @@ let Dashboard = class Dashboard {
     // 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)
@@ -352,7 +356,7 @@ let Dashboard = class Dashboard {
     ranOrdered(rows) {
         const rank = [rules_config_1.CK_OVERRIDDEN, rules_config_1.CK_WARN, rules_config_1.CK_PASS];
         return rows
-            .filter((r) => r.ran)
+            .filter((r) => this.reviewerRan(r))
             .slice()
             .sort((a, b) => this.rankOf(rank, a.status) - this.rankOf(rank, b.status));
     }