codex-plugin-doctor 0.5.0 → 0.6.0

package/README.md

@@ -65,8 +65,9 @@ Output formats:
 - human text output
 - JSON reports
 - Markdown reports
-- Shields-compatible badge JSON and static badge Markdown
-- `--output` file writing
+- Shields-compatible badge JSON and static badge Markdown
+- validation history JSONL and trend summaries
+- `--output` file writing
 - CI summary and artifact generation
 
 ## Quick Start
@@ -184,10 +185,14 @@ codex-plugin-doctor check . --badge-markdown
 codex-plugin-doctor check . --sarif --output results.sarif
 codex-plugin-doctor check . --ascii
 codex-plugin-doctor check . --no-animations
-codex-plugin-doctor check . --runtime
-codex-plugin-doctor check . --config .codex-doctor.json
-codex-plugin-doctor check . --json --runtime --verbose-runtime
-```
+codex-plugin-doctor check . --runtime
+codex-plugin-doctor check . --config .codex-doctor.json
+codex-plugin-doctor check . --history validation-history.jsonl
+codex-plugin-doctor history validation-history.jsonl
+codex-plugin-doctor history validation-history.jsonl --json
+codex-plugin-doctor history validation-history.jsonl --fail-on-regression
+codex-plugin-doctor check . --json --runtime --verbose-runtime
+```
 
 `self-test` runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after `npm install -g codex-plugin-doctor`.
 
@@ -197,7 +202,9 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `compat --scorecard` turns the compatibility matrix into a compact score summary. `PASS` maps to `100`, `WARN` maps to `70`, and `FAIL` or `SKIPPED` maps to `0`.
 
-`check --badge-json` emits Shields endpoint-compatible JSON such as `{"schemaVersion":1,"label":"doctor","message":"PASS","color":"brightgreen"}`. `check --badge-markdown` emits a static shields.io Markdown badge for README or release notes. Badge output is intentionally limited to single package checks, not `check --installed`.
+`check --badge-json` emits Shields endpoint-compatible JSON such as `{"schemaVersion":1,"label":"doctor","message":"PASS","color":"brightgreen"}`. `check --badge-markdown` emits a static shields.io Markdown badge for README or release notes. Badge output is intentionally limited to single package checks, not `check --installed`.
+
+`check --history <path>` appends a compact JSONL validation snapshot after a single package check. `history <path>` reads the JSONL file and compares the latest run to the previous run, including status, finding-count deltas, and whether the latest run regressed. Add `history --json` for automation output or `history --fail-on-regression` when CI should fail after a worse latest run.
 
 Optional local policy file:
 
@@ -232,11 +239,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: Esquetta/CodexPluginDoctor@v0.5.0
-        with:
-          version: "0.5.0"
-          path: .
-          runtime: "false"
+      - uses: Esquetta/CodexPluginDoctor@v0.6.0
+        with:
+          version: "0.6.0"
+          path: .
+          runtime: "false"
 ```
 
 For runtime probing, SARIF output, installed plugin cache checks, and pinned release examples, see [GitHub Action Usage](./docs/engineering/github-action-usage.md).

package/dist/core/validation-history.d.ts

@@ -0,0 +1,33 @@
+import type { CheckResult } from "../domain/types.js";
+export interface ValidationHistoryEntry {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    targetPath: string;
+    status: CheckResult["status"];
+    runtimeProbeEnabled: boolean;
+    findingCounts: {
+        fail: number;
+        warn: number;
+        total: number;
+    };
+}
+export interface ValidationHistorySummary {
+    schemaVersion: "1.0.0";
+    runs: number;
+    latest: ValidationHistoryEntry;
+    previous: ValidationHistoryEntry | null;
+    delta: {
+        fail: number;
+        warn: number;
+        total: number;
+    };
+    regression: boolean;
+}
+export declare function buildValidationHistoryEntry(result: CheckResult, options: {
+    runtimeProbeEnabled: boolean;
+}): ValidationHistoryEntry;
+export declare function appendValidationHistoryEntry(historyPath: string, result: CheckResult, options: {
+    runtimeProbeEnabled: boolean;
+}): Promise<void>;
+export declare function readValidationHistory(historyPath: string): Promise<ValidationHistoryEntry[]>;
+export declare function summarizeValidationHistory(entries: ValidationHistoryEntry[]): ValidationHistorySummary;

package/dist/core/validation-history.js

@@ -0,0 +1,64 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+const statusRank = {
+    pass: 0,
+    warn: 1,
+    fail: 2
+};
+function countFindings(result) {
+    return {
+        fail: result.findings.filter((finding) => finding.severity === "fail").length,
+        warn: result.findings.filter((finding) => finding.severity === "warn").length,
+        total: result.findings.length
+    };
+}
+export function buildValidationHistoryEntry(result, options) {
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        targetPath: result.targetPath,
+        status: result.status,
+        runtimeProbeEnabled: options.runtimeProbeEnabled,
+        findingCounts: countFindings(result)
+    };
+}
+export async function appendValidationHistoryEntry(historyPath, result, options) {
+    const absoluteHistoryPath = path.resolve(historyPath);
+    await mkdir(path.dirname(absoluteHistoryPath), { recursive: true });
+    await writeFile(absoluteHistoryPath, `${JSON.stringify(buildValidationHistoryEntry(result, options))}\n`, { encoding: "utf8", flag: "a" });
+}
+export async function readValidationHistory(historyPath) {
+    const content = await readFile(path.resolve(historyPath), "utf8");
+    return content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+export function summarizeValidationHistory(entries) {
+    if (entries.length === 0) {
+        throw new Error("No validation history entries found.");
+    }
+    const latest = entries[entries.length - 1];
+    const previous = entries.length > 1 ? entries[entries.length - 2] : null;
+    const delta = previous
+        ? {
+            fail: latest.findingCounts.fail - previous.findingCounts.fail,
+            warn: latest.findingCounts.warn - previous.findingCounts.warn,
+            total: latest.findingCounts.total - previous.findingCounts.total
+        }
+        : { fail: 0, warn: 0, total: 0 };
+    const regression = previous
+        ? statusRank[latest.status] > statusRank[previous.status]
+            || delta.fail > 0
+            || delta.warn > 0
+        : false;
+    return {
+        schemaVersion: "1.0.0",
+        runs: entries.length,
+        latest,
+        previous,
+        delta,
+        regression
+    };
+}

package/dist/reporting/render-history-summary.d.ts

@@ -0,0 +1,2 @@
+import { type ValidationHistoryEntry } from "../core/validation-history.js";
+export declare function renderHistorySummary(entries: ValidationHistoryEntry[]): string;

package/dist/reporting/render-history-summary.js

@@ -0,0 +1,23 @@
+import { summarizeValidationHistory } from "../core/validation-history.js";
+function formatDelta(value) {
+    return value > 0 ? `+${value}` : String(value);
+}
+export function renderHistorySummary(entries) {
+    const summary = summarizeValidationHistory(entries);
+    const { latest, previous } = summary;
+    const lines = [
+        "Validation History",
+        "==================",
+        `Runs: ${summary.runs}`,
+        `Latest: ${latest.status.toUpperCase()}`,
+        `Target: ${latest.targetPath}`,
+        `Generated: ${latest.generatedAt}`,
+        `Fail findings: ${latest.findingCounts.fail}`,
+        `Warn findings: ${latest.findingCounts.warn}`,
+        `Regression: ${summary.regression ? "YES" : "NO"}`
+    ];
+    if (previous) {
+        lines.push("", `Previous: ${previous.status.toUpperCase()}`, `Fail findings: ${formatDelta(summary.delta.fail)}`, `Warn findings: ${formatDelta(summary.delta.warn)}`);
+    }
+    return lines.join("\n");
+}

package/dist/run-cli.js

@@ -2,6 +2,7 @@ import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
+import { appendValidationHistoryEntry, readValidationHistory, summarizeValidationHistory } from "./core/validation-history.js";
 import { buildCompatibilityMatrix, matrixExitCode } from "./compatibility/compatibility-matrix.js";
 import { applyInstallPreview, renderApplyInstallResult } from "./compatibility/apply-install-preview.js";
 import { buildClaudeDesktopInstallPreview, renderClaudeDesktopInstallPreview } from "./compatibility/claude-desktop-install-preview.js";
@@ -13,6 +14,7 @@ import { renderInstalledSummary } from "./reporting/render-installed-summary.js"
 import { renderBadgeJson, renderBadgeMarkdown } from "./reporting/render-badge-report.js";
 import { renderCompatibilityScorecard } from "./reporting/render-compatibility-scorecard.js";
 import { renderCompatibilityReport } from "./reporting/render-compatibility-report.js";
+import { renderHistorySummary } from "./reporting/render-history-summary.js";
 import { renderJsonReport } from "./reporting/render-json-report.js";
 import { buildMarkdownReport } from "./reporting/render-markdown-report.js";
 import { renderRuleExplanation } from "./reporting/render-rule-explanation.js";
@@ -32,7 +34,7 @@ const defaultIo = {
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]\n       codex-plugin-doctor compat <path> [--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]\n       codex-plugin-doctor compat <path> [--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -118,6 +120,31 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStdout(renderRuleExplanation(rule));
         return 0;
     }
+    if (command === "history") {
+        if (!maybePath || maybePath.startsWith("--")) {
+            io.writeStderr("Missing history path. Usage: codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]");
+            return 2;
+        }
+        try {
+            const entries = await readValidationHistory(maybePath);
+            const summary = summarizeValidationHistory(entries);
+            const jsonOutput = remainingArgs.includes("--json");
+            const failOnRegression = remainingArgs.includes("--fail-on-regression");
+            io.writeStdout(jsonOutput
+                ? JSON.stringify(summary, null, 2)
+                : renderHistorySummary(entries));
+            if (failOnRegression && summary.regression) {
+                io.writeStderr("Validation history regression detected.");
+                return 1;
+            }
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unable to read validation history.";
+            io.writeStderr(message);
+            return 1;
+        }
+    }
     if (command === "self-test" || command === "demo") {
         const targetPath = resolveBundledSelfTestTarget();
         const runCheckImpl = options.runCheckImpl ?? runCheck;
@@ -260,6 +287,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
     const outputPath = outputIndex === -1 ? null : normalizedFlags[outputIndex + 1];
     const configIndex = normalizedFlags.indexOf("--config");
     const configPath = configIndex === -1 ? null : normalizedFlags[configIndex + 1];
+    const historyIndex = normalizedFlags.indexOf("--history");
+    const historyPath = historyIndex === -1 ? null : normalizedFlags[historyIndex + 1];
     if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
         io.writeStderr("Missing path after --output.");
         return 2;
@@ -268,10 +297,18 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("Missing path after --config.");
         return 2;
     }
+    if (historyIndex !== -1 && (!historyPath || historyPath.startsWith("--"))) {
+        io.writeStderr("Missing path after --history.");
+        return 2;
+    }
     if (checkInstalled && (badgeJsonOutput || badgeMarkdownOutput)) {
         io.writeStderr("Badge output requires a single package target.");
         return 2;
     }
+    if (checkInstalled && historyPath) {
+        io.writeStderr("History output requires a single package target.");
+        return 2;
+    }
     const outputPolicy = determineOutputPolicy({
         jsonOutput: jsonOutput || badgeJsonOutput,
         markdownOutput: markdownOutput || badgeMarkdownOutput,
@@ -354,6 +391,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
     if (outputPath) {
         await writeFile(outputPath, report, "utf8");
     }
+    if (historyPath) {
+        await appendValidationHistoryEntry(historyPath, result, { runtimeProbeEnabled });
+    }
     io.writeStdout(report);
     return result.exitCode;
 }

package/package.json

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