codex-plugin-doctor 1.26.0 → 1.27.0

package/README.md

@@ -336,16 +336,27 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `fix --dry-run` renders safe automatic fix plans without changing files. `fix --interactive --backup` shows the same numbered plan, then applies everything after `yes` or only selected action numbers such as `1,3`. `fix --apply --backup` applies supported safe fixes, such as manifest defaults and missing skills directories, after creating backups.
 
-Optional local policy file:
-
-```json
-{
-  "ignoreRules": ["plugin.heuristic.description.too_long"],
-  "failOnWarnings": true
-}
-```
-
-Run these when you want Codex Plugin Doctor to find plugins from the local Codex installation:
+Optional local policy file:
+
+```json
+{
+  "ignoreRules": ["plugin.heuristic.description.too_long"],
+  "suppressions": [
+    {
+      "fingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+      "reason": "Accepted until the upstream package layout is corrected.",
+      "expiresAt": "2026-07-31"
+    }
+  ],
+  "failOnWarnings": true
+}
+```
+
+`ignoreRules` disables every finding with a matching rule ID. Prefer `suppressions` when accepting one specific finding instance: each record requires the exact 64-character lowercase SHA-256 fingerprint shown in Doctor reports, a non-empty review reason, and a real `YYYY-MM-DD` expiration date.
+
+Active suppressions remove only the matching finding from the active result and preserve it under `suppressedFindings` for audit output. Expired or invalid records do not suppress findings; Doctor emits `suppression.expired` or `suppression.invalid` warnings instead. Duplicate active records use the first valid match.
+
+Run these when you want Codex Plugin Doctor to find plugins from the local Codex installation:
 
 ```bash
 codex-plugin-doctor list --installed
@@ -370,9 +381,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.26.0
+      - uses: Esquetta/CodexPluginDoctor@v1.27.0
         with:
-          version: "1.26.0"
+          version: "1.27.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/doctor-config.d.ts

@@ -2,6 +2,9 @@ import type { CheckResult } from "../domain/types.js";
 export interface DoctorConfig {
     ignoreRules: string[];
     failOnWarnings: boolean;
+    suppressions: unknown[];
 }
 export declare function loadDoctorConfig(targetPath: string, explicitConfigPath?: string | null): Promise<DoctorConfig>;
-export declare function applyDoctorConfig(result: CheckResult, config: DoctorConfig): CheckResult;
+export declare function applyDoctorConfig(result: CheckResult, config: DoctorConfig, options?: {
+    now?: Date;
+}): CheckResult;

package/dist/core/doctor-config.js

@@ -1,8 +1,10 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { withFindingFingerprint } from "../reporting/finding-fingerprint.js";
 const defaultConfig = {
     ignoreRules: [],
-    failOnWarnings: false
+    failOnWarnings: false,
+    suppressions: []
 };
 function isStringArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === "string");
@@ -19,15 +21,69 @@ export async function loadDoctorConfig(targetPath, explicitConfigPath) {
                 : defaultConfig.ignoreRules,
             failOnWarnings: typeof parsed.failOnWarnings === "boolean"
                 ? parsed.failOnWarnings
-                : defaultConfig.failOnWarnings
+                : defaultConfig.failOnWarnings,
+            suppressions: Array.isArray(parsed.suppressions)
+                ? parsed.suppressions
+                : defaultConfig.suppressions
         };
     }
     catch {
         return defaultConfig;
     }
 }
-export function applyDoctorConfig(result, config) {
-    const findings = result.findings.filter((finding) => !config.ignoreRules.includes(finding.id));
+export function applyDoctorConfig(result, config, options = {}) {
+    const configuredFindings = result.findings.filter((finding) => !config.ignoreRules.includes(finding.id));
+    const now = options.now ?? new Date();
+    const activeSuppressions = new Map();
+    const governanceWarnings = [];
+    const summary = {
+        applied: 0,
+        expired: 0,
+        invalid: 0
+    };
+    for (const [index, suppression] of config.suppressions.entries()) {
+        const validation = validateSuppression(suppression);
+        if (!validation.valid) {
+            summary.invalid += 1;
+            governanceWarnings.push(buildGovernanceWarning(result.targetPath, "suppression.invalid", "A targeted suppression record is invalid and was not applied.", "Invalid suppression records can create false confidence because they do not match or expire as intended.", "Fix or remove the invalid suppression record in `.codex-doctor.json`.", {
+                suppressionIndex: index,
+                field: validation.field
+            }));
+            continue;
+        }
+        if (isExpired(validation.expiresAt, now)) {
+            summary.expired += 1;
+            governanceWarnings.push(buildGovernanceWarning(result.targetPath, "suppression.expired", "A targeted suppression has expired and was not applied.", "Expired risk acceptance must be reviewed again before the finding can be suppressed.", "Remove the expired suppression or replace it with a newly reviewed expiration date.", {
+                suppressionIndex: index,
+                fingerprint: validation.fingerprint,
+                expiresAt: validation.expiresAt
+            }));
+            continue;
+        }
+        if (!activeSuppressions.has(validation.fingerprint)) {
+            activeSuppressions.set(validation.fingerprint, {
+                reason: validation.reason,
+                expiresAt: validation.expiresAt
+            });
+        }
+    }
+    const findings = [];
+    const suppressedFindings = [];
+    for (const finding of configuredFindings) {
+        const suppression = finding.fingerprint
+            ? activeSuppressions.get(finding.fingerprint)
+            : undefined;
+        if (!suppression) {
+            findings.push(finding);
+            continue;
+        }
+        summary.applied += 1;
+        suppressedFindings.push({
+            ...finding,
+            suppression
+        });
+    }
+    findings.push(...governanceWarnings);
     const hasFailures = findings.some((finding) => finding.severity === "fail");
     const hasWarnings = findings.some((finding) => finding.severity === "warn");
     const warningFailure = config.failOnWarnings && hasWarnings;
@@ -40,6 +96,63 @@ export function applyDoctorConfig(result, config) {
         ...result,
         status,
         exitCode: status === "fail" ? 1 : 0,
-        findings
+        findings,
+        ...(config.suppressions.length > 0
+            ? {
+                suppressedFindings,
+                suppressionSummary: summary
+            }
+            : {})
     };
 }
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRealDate(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (!match) {
+        return false;
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return (date.getUTCFullYear() === year &&
+        date.getUTCMonth() === month - 1 &&
+        date.getUTCDate() === day);
+}
+function validateSuppression(value) {
+    if (!isPlainObject(value)) {
+        return { valid: false, field: "record" };
+    }
+    if (typeof value.fingerprint !== "string" ||
+        !/^[a-f0-9]{64}$/.test(value.fingerprint)) {
+        return { valid: false, field: "fingerprint" };
+    }
+    if (typeof value.reason !== "string" || value.reason.trim().length === 0) {
+        return { valid: false, field: "reason" };
+    }
+    if (typeof value.expiresAt !== "string" || !isRealDate(value.expiresAt)) {
+        return { valid: false, field: "expiresAt" };
+    }
+    return {
+        valid: true,
+        fingerprint: value.fingerprint,
+        reason: value.reason.trim(),
+        expiresAt: value.expiresAt
+    };
+}
+function isExpired(expiresAt, now) {
+    const expirationBoundary = Date.parse(`${expiresAt}T00:00:00.000Z`) + 86_400_000;
+    return now.getTime() >= expirationBoundary;
+}
+function buildGovernanceWarning(targetPath, id, message, impact, suggestedFix, evidence) {
+    return withFindingFingerprint({
+        id,
+        severity: "warn",
+        message,
+        impact,
+        suggestedFix,
+        evidence
+    }, targetPath);
+}

package/dist/domain/types.d.ts

@@ -10,11 +10,25 @@ export interface Finding {
     evidence?: FindingEvidence;
     fingerprint?: string;
 }
+export interface FindingSuppression {
+    reason: string;
+    expiresAt: string;
+}
+export interface SuppressedFinding extends Finding {
+    suppression: FindingSuppression;
+}
+export interface SuppressionSummary {
+    applied: number;
+    expired: number;
+    invalid: number;
+}
 export interface CheckResult {
     targetPath: string;
     status: "pass" | "warn" | "fail";
     exitCode: 0 | 1;
     findings: Finding[];
+    suppressedFindings?: SuppressedFinding[];
+    suppressionSummary?: SuppressionSummary;
     runtimeScorecard?: RuntimeScorecard;
 }
 export interface CheckOptions {
@@ -50,6 +64,8 @@ export interface JsonReport {
     generatedAt: string;
     summary: JsonReportSummary;
     findings: Finding[];
+    suppressedFindings?: SuppressedFinding[];
+    suppressionSummary?: SuppressionSummary;
 }
 export type RuntimeCapabilityStatus = "pass" | "fail" | "warn" | "skipped" | "unsupported";
 export interface RuntimeScorecard {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { CheckOptions, CheckResult } from "./domain/types.js";
+export { applyDoctorConfig, loadDoctorConfig, type DoctorConfig } from "./core/doctor-config.js";
 export { buildFindingFingerprint, formatFindingFingerprintLine, withFindingFingerprint, withFindingFingerprints } from "./reporting/finding-fingerprint.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard, type SecurityAudit } from "./security/security-audit.js";
 export { buildTrustScore, renderTrustScore, renderTrustScoreJson, type BuildTrustScoreOptions, type TrustScoreReport } from "./security/trust-score.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 import { validatePlugin } from "./core/validate-plugin.js";
+export { applyDoctorConfig, loadDoctorConfig } from "./core/doctor-config.js";
 export { buildFindingFingerprint, formatFindingFingerprintLine, withFindingFingerprint, withFindingFingerprints } from "./reporting/finding-fingerprint.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard } from "./security/security-audit.js";
 export { buildTrustScore, renderTrustScore, renderTrustScoreJson } from "./security/trust-score.js";

package/dist/reporting/render-json-report.js

@@ -18,7 +18,13 @@ export function buildJsonReport(result, options) {
                 total: result.findings.length
             }
         },
-        findings: result.findings
+        findings: result.findings,
+        ...(result.suppressedFindings
+            ? { suppressedFindings: result.suppressedFindings }
+            : {}),
+        ...(result.suppressionSummary
+            ? { suppressionSummary: result.suppressionSummary }
+            : {})
     };
 }
 export function renderJsonReport(result, options) {

package/dist/reporting/render-markdown-report.js

@@ -16,7 +16,10 @@ export function buildMarkdownReport(result, options) {
         `| Warn Findings | ${warnCount} |`,
         `| Total Findings | ${result.findings.length} |`
     ];
-    if (result.findings.length === 0) {
+    if (result.suppressionSummary) {
+        lines.push(`| Suppressions Applied | ${result.suppressionSummary.applied} |`, `| Suppressions Expired | ${result.suppressionSummary.expired} |`, `| Suppressions Invalid | ${result.suppressionSummary.invalid} |`);
+    }
+    if (result.findings.length === 0 && !result.suppressedFindings?.length) {
         lines.push("", "No findings.");
         return lines.join("\n");
     }
@@ -33,22 +36,39 @@ export function buildMarkdownReport(result, options) {
         lines.push(`| prompts/list | ${result.runtimeScorecard.promptsList.toUpperCase()} |`);
         lines.push(`| prompts/get | ${result.runtimeScorecard.promptGet.toUpperCase()} |`);
     }
-    lines.push("", "## Findings", "");
-    for (const finding of result.findings) {
-        lines.push(`### ${finding.severity.toUpperCase()} \`${finding.id}\``);
-        lines.push("");
-        lines.push(`- Message: ${finding.message}`);
-        lines.push(`- Impact: ${finding.impact}`);
-        lines.push(`- Suggested fix: ${finding.suggestedFix}`);
-        const fingerprint = formatFindingFingerprintLine(finding);
-        if (fingerprint) {
-            lines.push(`- Fingerprint: \`${fingerprint}\``);
+    if (result.findings.length > 0) {
+        lines.push("", "## Findings", "");
+        for (const finding of result.findings) {
+            lines.push(`### ${finding.severity.toUpperCase()} \`${finding.id}\``);
+            lines.push("");
+            lines.push(`- Message: ${finding.message}`);
+            lines.push(`- Impact: ${finding.impact}`);
+            lines.push(`- Suggested fix: ${finding.suggestedFix}`);
+            const fingerprint = formatFindingFingerprintLine(finding);
+            if (fingerprint) {
+                lines.push(`- Fingerprint: \`${fingerprint}\``);
+            }
+            const evidence = formatFindingEvidenceLine(finding);
+            if (evidence) {
+                lines.push(`- Evidence: ${evidence}`);
+            }
+            lines.push("");
         }
-        const evidence = formatFindingEvidenceLine(finding);
-        if (evidence) {
-            lines.push(`- Evidence: ${evidence}`);
+    }
+    else {
+        lines.push("", "No active findings.");
+    }
+    if (result.suppressedFindings?.length) {
+        lines.push("", "## Suppressed Findings", "");
+        for (const finding of result.suppressedFindings) {
+            lines.push(`### ${finding.severity.toUpperCase()} \`${finding.id}\``);
+            lines.push("");
+            lines.push(`- Message: ${finding.message}`);
+            lines.push(`- Fingerprint: \`${finding.fingerprint ?? "unavailable"}\``);
+            lines.push(`- Reason: ${finding.suppression.reason}`);
+            lines.push(`- Expires: ${finding.suppression.expiresAt}`);
+            lines.push("");
         }
-        lines.push("");
     }
     return lines.join("\n");
 }

package/dist/reporting/render-sarif-report.js

@@ -55,7 +55,15 @@ export function renderSarifReport(result) {
                         }
                         : {}),
                     ...(finding.evidence ? { properties: { evidence: finding.evidence } } : {})
-                }))
+                })),
+                ...(result.suppressionSummary
+                    ? {
+                        properties: {
+                            suppressionSummary: result.suppressionSummary,
+                            suppressedFindings: result.suppressedFindings ?? []
+                        }
+                    }
+                    : {})
             }
         ]
     };

package/dist/reporting/render-text-report.js

@@ -35,7 +35,10 @@ export function renderTextReport(result, options = {}) {
         `Target: ${result.targetPath}`,
         `Summary: ${failCount} fail, ${warnCount} warn, ${totalCount} total`
     ];
-    if (result.findings.length === 0) {
+    if (result.suppressionSummary) {
+        lines.push(`Suppressions: ${result.suppressionSummary.applied} applied, ${result.suppressionSummary.expired} expired, ${result.suppressionSummary.invalid} invalid`);
+    }
+    if (result.findings.length === 0 && !result.suppressedFindings?.length) {
         if (result.runtimeScorecard) {
             lines.push("", "Runtime Scorecard", "----------------");
             lines.push(`initialize: ${result.runtimeScorecard.initialize}`);
@@ -82,6 +85,16 @@ export function renderTextReport(result, options = {}) {
     };
     appendSection("Failures", failures, glyphs.fail);
     appendSection("Warnings", warnings, glyphs.warn);
+    if (result.suppressedFindings?.length) {
+        lines.push("", "Suppressed Findings", "-------------------");
+        for (const finding of result.suppressedFindings) {
+            lines.push(`- ${finding.id}`);
+            lines.push(`  Message: ${finding.message}`);
+            lines.push(`  Fingerprint: ${finding.fingerprint ?? "unavailable"}`);
+            lines.push(`  Reason: ${finding.suppression.reason}`);
+            lines.push(`  Expires: ${finding.suppression.expiresAt}`);
+        }
+    }
     if (result.runtimeScorecard) {
         lines.push("", "Runtime Scorecard", "----------------");
         lines.push(`initialize: ${result.runtimeScorecard.initialize}`);

package/dist/rules/rule-catalog.d.ts

@@ -1,4 +1,4 @@
-export type RuleCategory = "package" | "skill" | "mcp" | "runtime" | "security";
+export type RuleCategory = "package" | "skill" | "mcp" | "runtime" | "security" | "configuration";
 export type RuleSeverity = "fail" | "warn";
 export interface RuleDefinition {
     id: string;

package/dist/rules/rule-catalog.js

@@ -1,4 +1,22 @@
 export const ruleCatalog = [
+    {
+        id: "suppression.invalid",
+        category: "configuration",
+        defaultSeverity: "warn",
+        summary: "A targeted suppression record is invalid.",
+        why: "Invalid suppression records are not applied and can create false confidence about accepted findings.",
+        fix: "Fix or remove the invalid suppression record in `.codex-doctor.json`.",
+        example: '{ "fingerprint": "<64 lowercase hex characters>", "reason": "Reviewed exception.", "expiresAt": "2026-07-31" }'
+    },
+    {
+        id: "suppression.expired",
+        category: "configuration",
+        defaultSeverity: "warn",
+        summary: "A targeted suppression has expired.",
+        why: "Expired risk acceptance must be reviewed again before the finding can be suppressed.",
+        fix: "Remove the expired record or replace it with a newly reviewed expiration date.",
+        example: '{ "fingerprint": "<fingerprint>", "reason": "Reviewed again.", "expiresAt": "2026-08-31" }'
+    },
     {
         id: "plugin.manifest.missing",
         category: "package",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",