codex-plugin-doctor 1.75.0 → 1.76.0

package/README.md

@@ -120,7 +120,8 @@ codex-plugin-doctor doctor tools-diff --before ./tools-old.json --after ./tools-
 This reports added, removed, and structurally changed definitions using numeric
 locations, and labels each change `breaking`, `compatible`, or `unclassified`
 with fixed reason codes. Add `--fail-on breaking` to fail CI only on breaking or
-unclassified changes, and `--markdown` for pull request tables. Incomplete inputs, invalid definitions, or duplicate names
+unclassified changes, `--markdown` for pull request tables, and `--show-names`
+locally to see tool names and the JSON Pointer of each reason. Incomplete inputs, invalid definitions, or duplicate names
 prevent a comparison. Impact labels follow nested object properties, array
 items, and common length and range bounds, but remain heuristics, not proof of
 compatibility.
@@ -589,9 +590,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.75.0
+      - uses: Esquetta/CodexPluginDoctor@v1.76.0
         with:
-          version: "1.75.0"
+          version: "1.76.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/mcp-tool-diff.d.ts

@@ -1,4 +1,4 @@
-import { type ToolChangeImpact, type ToolChangeReason } from "./mcp-tool-impact.js";
+import { type ToolChangeImpact, type ToolChangeLocation, type ToolChangeReason } from "./mcp-tool-impact.js";
 import { type McpToolFileReport } from "./mcp-tool-file.js";
 type DiffField = "inputSchema" | "outputSchema" | "description" | "title" | "annotations" | "other";
 export interface McpToolDiffReport {
@@ -32,7 +32,12 @@ export interface McpToolDiffReport {
         fields: DiffField[];
         impact: ToolChangeImpact;
         reasons: ToolChangeReason[];
+        name?: string;
+        locations?: ToolChangeLocation[];
     }>;
 }
-export declare function compareMcpToolFiles(beforePath: string, afterPath: string): Promise<McpToolDiffReport>;
+export interface McpToolDiffOptions {
+    showNames?: boolean;
+}
+export declare function compareMcpToolFiles(beforePath: string, afterPath: string, options?: McpToolDiffOptions): Promise<McpToolDiffReport>;
 export {};

package/dist/core/mcp-tool-diff.js

@@ -85,7 +85,7 @@ function incompleteReport(before, after, status, reason) {
         changes: []
     };
 }
-export async function compareMcpToolFiles(beforePath, afterPath) {
+export async function compareMcpToolFiles(beforePath, afterPath, options = {}) {
     const [beforeSnapshot, afterSnapshot] = await Promise.all([
         loadMcpToolFileSnapshot(beforePath),
         loadMcpToolFileSnapshot(afterPath)
@@ -106,6 +106,7 @@ export async function compareMcpToolFiles(beforePath, afterPath) {
     if (beforeDefinitions === null || afterDefinitions === null) {
         return incompleteReport(before, after, "incomplete", "ambiguous-names");
     }
+    const named = (name) => (options.showNames === true ? { name } : {});
     const changes = [];
     let added = 0;
     let removed = 0;
@@ -115,7 +116,7 @@ export async function compareMcpToolFiles(beforePath, afterPath) {
         const afterDefinition = afterDefinitions.get(name);
         if (afterDefinition === undefined) {
             removed += 1;
-            changes.push({ kind: "removed", beforeToolIndex: beforeDefinition.index, afterToolIndex: null, fields: [], ...classifyRemovedTool() });
+            changes.push({ kind: "removed", ...named(name), beforeToolIndex: beforeDefinition.index, afterToolIndex: null, fields: [], ...classifyRemovedTool() });
             continue;
         }
         const fields = changedFields(beforeDefinition.value, afterDefinition.value);
@@ -126,17 +127,18 @@ export async function compareMcpToolFiles(beforePath, afterPath) {
             changed += 1;
             changes.push({
                 kind: "changed",
+                ...named(name),
                 beforeToolIndex: beforeDefinition.index,
                 afterToolIndex: afterDefinition.index,
                 fields,
-                ...classifyChangedTool(beforeDefinition.value, afterDefinition.value, fields, structurallyEqual)
+                ...classifyChangedTool(beforeDefinition.value, afterDefinition.value, fields, structurallyEqual, { locate: options.showNames === true })
             });
         }
     }
     for (const [name, afterDefinition] of afterDefinitions) {
         if (!beforeDefinitions.has(name)) {
             added += 1;
-            changes.push({ kind: "added", beforeToolIndex: null, afterToolIndex: afterDefinition.index, fields: [], ...classifyAddedTool() });
+            changes.push({ kind: "added", ...named(name), beforeToolIndex: null, afterToolIndex: afterDefinition.index, fields: [], ...classifyAddedTool() });
         }
     }
     return {

package/dist/core/mcp-tool-impact.d.ts

@@ -2,12 +2,21 @@ type JsonObject = Record<string, unknown>;
 export type ToolChangeImpact = "breaking" | "compatible" | "unclassified";
 export declare const TOOL_CHANGE_REASONS: readonly ["tool-removed", "input-type-narrowed", "input-required-added", "input-property-removed", "input-property-type-narrowed", "input-property-enum-narrowed", "input-constraint-tightened", "input-additional-properties-closed", "input-schema-unclassified", "output-schema-removed", "output-type-widened", "output-property-removed", "output-guarantee-removed", "output-property-type-widened", "output-property-enum-widened", "output-constraint-loosened", "output-schema-unclassified", "annotation-safety-reduced", "other-fields-unclassified"];
 export type ToolChangeReason = (typeof TOOL_CHANGE_REASONS)[number];
+export interface ToolChangeLocation {
+    reason: ToolChangeReason;
+    pointer: string;
+}
 export interface ToolChangeClassification {
     impact: ToolChangeImpact;
     reasons: ToolChangeReason[];
+    locations?: ToolChangeLocation[];
 }
+export declare const MAX_TOOL_CHANGE_LOCATIONS = 100;
+export declare const MAX_TOOL_CHANGE_POINTER_LENGTH = 1000;
 type Equal = (left: unknown, right: unknown) => boolean;
 export declare function classifyRemovedTool(): ToolChangeClassification;
 export declare function classifyAddedTool(): ToolChangeClassification;
-export declare function classifyChangedTool(before: JsonObject, after: JsonObject, fields: readonly string[], equal: Equal): ToolChangeClassification;
+export declare function classifyChangedTool(before: JsonObject, after: JsonObject, fields: readonly string[], equal: Equal, options?: {
+    locate?: boolean;
+}): ToolChangeClassification;
 export {};

package/dist/core/mcp-tool-impact.js

@@ -19,6 +19,59 @@ export const TOOL_CHANGE_REASONS = [
     "annotation-safety-reduced",
     "other-fields-unclassified"
 ];
+export const MAX_TOOL_CHANGE_LOCATIONS = 100;
+// Longer pointers are not recorded, so a long property name cannot make locating costly or the report large.
+export const MAX_TOOL_CHANGE_POINTER_LENGTH = 1_000;
+/**
+ * A reason set that also records, for each reason, the JSON Pointer of the schema position being
+ * compared when it was added. A shared definition is compared once, so it is located at the first
+ * reference that reached it.
+ */
+class LocatingReasons extends Set {
+    locations = [];
+    // Escaped pointer segments of the position being compared, and the pointer length at each one;
+    // a segment that would pass the length limit is left empty, with an infinite length.
+    segments = [];
+    lengths = [0];
+    seen = new Set();
+    enter(tokens) {
+        for (const token of tokens) {
+            const previous = this.lengths[this.lengths.length - 1];
+            const segment = previous + 1 + token.length > MAX_TOOL_CHANGE_POINTER_LENGTH ? "" : `/${token.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+            this.segments.push(segment);
+            this.lengths.push(segment === "" || previous + segment.length > MAX_TOOL_CHANGE_POINTER_LENGTH ? Infinity : previous + segment.length);
+        }
+    }
+    leave(count) {
+        this.segments.length -= count;
+        this.lengths.length -= count;
+    }
+    add(reason) {
+        if (this.locations.length < MAX_TOOL_CHANGE_LOCATIONS && this.lengths[this.lengths.length - 1] !== Infinity) {
+            const pointer = this.segments.join("");
+            const key = `${reason} ${pointer}`;
+            if (!this.seen.has(key)) {
+                this.seen.add(key);
+                this.locations.push({ reason, pointer });
+            }
+        }
+        return super.add(reason);
+    }
+}
+/** Runs `compare` with `tokens` appended to the recorded location, when locations are recorded. */
+function within(reasons, tokens, compare) {
+    if (!(reasons instanceof LocatingReasons)) {
+        compare();
+        return;
+    }
+    reasons.enter(tokens);
+    try {
+        compare();
+    }
+    finally {
+        reasons.leave(tokens.length);
+    }
+}
 const UNCLASSIFIED_REASONS = new Set([
     "input-schema-unclassified",
     "output-schema-unclassified",
@@ -752,12 +805,14 @@ function compareSchema(before, after, direction, depth, equal, reasons, scope) {
         compareNumericAndArrayConstraints(inner, outer, codes, reasons);
         compareStringConstraints(inner, outer, codes, reasons);
         if (!sameMeaning(before.items, after.items, equal, scope)) {
-            if (unevaluated)
-                reasons.add(codes.unclassified);
-            else if (outer.items !== undefined && inner.items === undefined)
-                reasons.add(codes.constraint);
-            else if (outer.items !== undefined)
-                compareSchema(before.items, after.items, direction, depth + 1, equal, reasons, scope);
+            within(reasons, ["items"], () => {
+                if (unevaluated)
+                    reasons.add(codes.unclassified);
+                else if (outer.items !== undefined && inner.items === undefined)
+                    reasons.add(codes.constraint);
+                else if (outer.items !== undefined)
+                    compareSchema(before.items, after.items, direction, depth + 1, equal, reasons, scope);
+            });
         }
     }
     const innerRequired = stringSet(inner.required);
@@ -770,13 +825,15 @@ function compareSchema(before, after, direction, depth, equal, reasons, scope) {
     }
     for (const key of outerRequired) {
         if (!innerRequired.has(key))
-            reasons.add(codes.required);
+            within(reasons, ["properties", key], () => reasons.add(codes.required));
     }
     for (const key of Object.keys(beforeProperties)) {
-        if (!Object.hasOwn(afterProperties, key))
-            reasons.add(codes.propertyRemoved);
-        else
-            compareSchema(beforeProperties[key], afterProperties[key], direction, depth + 1, equal, reasons, scope);
+        within(reasons, ["properties", key], () => {
+            if (!Object.hasOwn(afterProperties, key))
+                reasons.add(codes.propertyRemoved);
+            else
+                compareSchema(beforeProperties[key], afterProperties[key], direction, depth + 1, equal, reasons, scope);
+        });
     }
     // In an object whose undeclared keys were governed by other keywords, or a nested input object
     // that left them open, a newly declared property can reject values callers send (input) or
@@ -834,7 +891,7 @@ function result(reasons) {
     const impact = ordered.some((reason) => !UNCLASSIFIED_REASONS.has(reason))
         ? "breaking"
         : ordered.length > 0 ? "unclassified" : "compatible";
-    return { impact, reasons: ordered };
+    return reasons instanceof LocatingReasons ? { impact, reasons: ordered, locations: reasons.locations } : { impact, reasons: ordered };
 }
 export function classifyRemovedTool() {
     return { impact: "breaking", reasons: ["tool-removed"] };
@@ -842,15 +899,15 @@ export function classifyRemovedTool() {
 export function classifyAddedTool() {
     return { impact: "compatible", reasons: [] };
 }
-export function classifyChangedTool(before, after, fields, equal) {
-    const reasons = new Set();
+export function classifyChangedTool(before, after, fields, equal, options = {}) {
+    const reasons = options.locate ? new LocatingReasons() : new Set();
     if (fields.includes("inputSchema")) {
-        compareSchema(before.inputSchema, after.inputSchema, "input", 0, equal, reasons, referenceScope(before.inputSchema, after.inputSchema));
+        within(reasons, ["inputSchema"], () => compareSchema(before.inputSchema, after.inputSchema, "input", 0, equal, reasons, referenceScope(before.inputSchema, after.inputSchema)));
     }
     if (fields.includes("outputSchema"))
-        classifyOutputSchema(before.outputSchema, after.outputSchema, equal, reasons);
+        within(reasons, ["outputSchema"], () => classifyOutputSchema(before.outputSchema, after.outputSchema, equal, reasons));
     if (fields.includes("annotations"))
-        classifyAnnotations(before.annotations, after.annotations, reasons);
+        within(reasons, ["annotations"], () => classifyAnnotations(before.annotations, after.annotations, reasons));
     if (fields.includes("other"))
         reasons.add("other-fields-unclassified");
     return result(reasons);

package/dist/core/output-contract.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { packageVersion } from "../version.js";
-import { TOOL_CHANGE_REASONS } from "./mcp-tool-impact.js";
+import { MAX_TOOL_CHANGE_LOCATIONS, MAX_TOOL_CHANGE_POINTER_LENGTH, TOOL_CHANGE_REASONS } from "./mcp-tool-impact.js";
 import { ruleCatalog } from "../rules/rule-catalog.js";
 const runtimeCapabilityStatusSchema = {
     type: "string",
@@ -836,7 +836,17 @@ publicSchemaDefinitions.push({
                     afterToolIndex: { type: ["integer", "null"], minimum: 1, maximum: 500 },
                     fields: { type: "array", maxItems: 6, uniqueItems: true, items: { enum: ["inputSchema", "outputSchema", "description", "title", "annotations", "other"] } },
                     impact: { enum: ["breaking", "compatible", "unclassified"] },
-                    reasons: { type: "array", maxItems: TOOL_CHANGE_REASONS.length, uniqueItems: true, items: { enum: [...TOOL_CHANGE_REASONS] } }
+                    reasons: { type: "array", maxItems: TOOL_CHANGE_REASONS.length, uniqueItems: true, items: { enum: [...TOOL_CHANGE_REASONS] } },
+                    // Only with --show-names.
+                    name: { type: "string" },
+                    locations: {
+                        type: "array", maxItems: MAX_TOOL_CHANGE_LOCATIONS,
+                        items: {
+                            type: "object", required: ["reason", "pointer"],
+                            properties: { reason: { enum: [...TOOL_CHANGE_REASONS] }, pointer: { type: "string", maxLength: MAX_TOOL_CHANGE_POINTER_LENGTH } },
+                            additionalProperties: false
+                        }
+                    }
                 }, additionalProperties: false
             }
         }

package/dist/reporting/quote-server-text.d.ts

@@ -0,0 +1,2 @@
+/** Quotes server-supplied text, such as a tool name or a JSON Pointer, as a JSON string that only holds printable characters. */
+export declare function quoteServerText(text: string): string;

package/dist/reporting/quote-server-text.js

@@ -0,0 +1,7 @@
+// Control, format, and line or paragraph separator characters, which can drive a terminal, end a line,
+// reorder text, or hide in it; JSON escapes only the C0 controls among them.
+const UNSAFE_TEXT = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
+/** Quotes server-supplied text, such as a tool name or a JSON Pointer, as a JSON string that only holds printable characters. */
+export function quoteServerText(text) {
+    return JSON.stringify(text).replace(UNSAFE_TEXT, (character) => Array.from({ length: character.length }, (_, index) => `\\u${character.charCodeAt(index).toString(16).padStart(4, "0")}`).join(""));
+}

package/dist/reporting/render-mcp-tool-diff-markdown.js

@@ -1,11 +1,26 @@
+import { quoteServerText } from "./quote-server-text.js";
 function count(value) {
     return value === null || value === undefined ? "not compared" : String(value);
 }
 function toolIndex(value) {
     return value === null ? "-" : String(value);
 }
+// Names and pointers come from the server, so they are quoted and put in a code span, where Markdown,
+// HTML, mentions, and links stay inert; the fence outgrows any backtick run, and pipes are escaped for the table.
+function code(text) {
+    const quoted = quoteServerText(text);
+    let run = 0;
+    let longest = 0;
+    for (const character of quoted) {
+        run = character === "`" ? run + 1 : 0;
+        longest = Math.max(longest, run);
+    }
+    const fence = "`".repeat(longest + 1);
+    return `${fence}${quoted.replace(/\|/gu, "\\|")}${fence}`;
+}
 export function renderMcpToolDiffMarkdown(report) {
     const comparison = report.comparison;
+    const named = report.changes.some((change) => change.name !== undefined);
     const lines = [
         "## MCP Tool Definition Diff",
         "",
@@ -16,7 +31,11 @@ export function renderMcpToolDiffMarkdown(report) {
         `| ${count(comparison.added)} | ${count(comparison.removed)} | ${count(comparison.changed)} | ${count(comparison.unchanged)} | ${count(comparison.breaking)} | ${count(comparison.unclassified)} |`
     ];
     if (report.changes.length > 0) {
-        lines.push("", "### Changes", "", "| Change | Before tool | After tool | Fields | Impact | Reasons |", "| --- | --- | --- | --- | --- | --- |", ...report.changes.map((change) => `| ${change.kind} | ${toolIndex(change.beforeToolIndex)} | ${toolIndex(change.afterToolIndex)} | ${change.fields.map((field) => `\`${field}\``).join(", ") || "-"} | **${change.impact}** | ${change.reasons.map((reason) => `\`${reason}\``).join(", ") || "-"} |`));
+        lines.push("", "### Changes", "", named ? "| Change | Tool | Before tool | After tool | Fields | Impact | Reasons |" : "| Change | Before tool | After tool | Fields | Impact | Reasons |", named ? "| --- | --- | --- | --- | --- | --- | --- |" : "| --- | --- | --- | --- | --- | --- |", ...report.changes.map((change) => `| ${change.kind}${named ? ` | ${change.name === undefined ? "-" : code(change.name)}` : ""} | ${toolIndex(change.beforeToolIndex)} | ${toolIndex(change.afterToolIndex)} | ${change.fields.map((field) => `\`${field}\``).join(", ") || "-"} | **${change.impact}** | ${change.reasons.map((reason) => `\`${reason}\``).join(", ") || "-"} |`));
+    }
+    const located = report.changes.flatMap((change) => (change.locations ?? []).map((location) => `| ${change.name === undefined ? "-" : code(change.name)} | \`${location.reason}\` | ${location.pointer === "" ? "(tool)" : code(location.pointer)} |`));
+    if (located.length > 0) {
+        lines.push("", "### Locations", "", "| Tool | Reason | Location |", "| --- | --- | --- |", ...located);
     }
     const findings = ["before", "after"].flatMap((side) => report[side].findings.map((finding) => {
         const location = finding.location;
@@ -28,6 +47,8 @@ export function renderMcpToolDiffMarkdown(report) {
     if (findings.length > 0) {
         lines.push("", "### Input Findings", "", "| Severity | Finding | Location | Message |", "| --- | --- | --- | --- |", ...findings);
     }
-    lines.push("", `Tool numbers are one-based positions in the before and after files; names and schema values are not reported. Impact labels are ${report.coverage.impactClassification} schema checks, not proof of compatibility.`);
+    lines.push("", named
+        ? `Tool names and schema locations are shown because --show-names was used; schema values are not reported. Impact labels are ${report.coverage.impactClassification} schema checks, not proof of compatibility.`
+        : `Tool numbers are one-based positions in the before and after files; names and schema values are not reported. Impact labels are ${report.coverage.impactClassification} schema checks, not proof of compatibility.`);
     return lines.join("\n");
 }

package/dist/reporting/render-mcp-tool-diff-report.js

@@ -1,3 +1,4 @@
+import { quoteServerText } from "./quote-server-text.js";
 export function renderMcpToolDiffReport(report) {
     const comparison = report.comparison;
     return [
@@ -39,7 +40,9 @@ export function renderMcpToolDiffReport(report) {
                 ...(change.afterToolIndex === null ? [] : [`after tool ${change.afterToolIndex}`])
             ];
             const impact = `${change.impact}${change.reasons.length ? ` (${change.reasons.join(", ")})` : ""}`;
-            return `${change.kind.toUpperCase()} [${locations.join(" -> ")}]${change.fields.length ? `: ${change.fields.join(", ")}` : ""}\n  Impact: ${impact}`;
+            const name = change.name === undefined ? "" : ` ${quoteServerText(change.name)}`;
+            const at = (change.locations ?? []).map((location) => `\n  At ${location.pointer === "" ? "(tool)" : quoteServerText(location.pointer)}: ${location.reason}`).join("");
+            return `${change.kind.toUpperCase()}${name} [${locations.join(" -> ")}]${change.fields.length ? `: ${change.fields.join(", ")}` : ""}\n  Impact: ${impact}${at}`;
         })
     ].join("\n");
 }

package/dist/run-cli.js

@@ -111,7 +111,7 @@ function writeExactStdout(io, message) {
 }
 class CliUsageError extends Error {
 }
-const toolsDiffUsage = "Usage: codex-plugin-doctor doctor tools-diff --before <path> --after <path> [--json|--markdown] [--fail-on any|breaking]";
+const toolsDiffUsage = "Usage: codex-plugin-doctor doctor tools-diff --before <path> --after <path> [--json|--markdown] [--fail-on any|breaking] [--show-names]";
 const toolsFileUsage = "Usage: codex-plugin-doctor doctor tools-file <path> [--json]";
 const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json] [--save-response <path>] [--bearer-token-env <NAME>]\n       codex-plugin-doctor doctor tools <path> --server <name> --runtime [--sandbox docker [--env <NAME>]...] [--require-runtime-approval [--runtime-approval-digest <digest>]] [--json] [--save-response <path>]";
 const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json] [--bearer-token-env <NAME>]";
@@ -1393,17 +1393,22 @@ export async function runCli(args, io = defaultIo, options = {}) {
     if (command === "doctor") {
         if (maybePath === "tools-diff") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
-                io.writeStdout(`${toolsDiffUsage}\nCompares two saved MCP tools/list responses offline. Changes are classified heuristically as breaking, compatible, or unclassified; compatibility is not tested.\n--fail-on breaking exits 1 only for breaking or unclassified changes (default: any change or input warning).`);
+                io.writeStdout(`${toolsDiffUsage}\nCompares two saved MCP tools/list responses offline. Changes are classified heuristically as breaking, compatible, or unclassified; compatibility is not tested.\n--fail-on breaking exits 1 only for breaking or unclassified changes (default: any change or input warning).
+--show-names adds tool names and the JSON Pointer of each reason; reports omit both by default, so keep it out of public output such as pull request comments.`);
                 return 0;
             }
             let beforePath;
             let afterPath;
             let format;
             let failOn;
+            let showNames = false;
             let invalid = false;
             for (let index = 0; index < remainingArgs.length; index += 1) {
                 const flag = remainingArgs[index];
-                if ((flag === "--json" || flag === "--markdown") && format === undefined) {
+                if (flag === "--show-names" && !showNames) {
+                    showNames = true;
+                }
+                else if ((flag === "--json" || flag === "--markdown") && format === undefined) {
                     format = flag === "--json" ? "json" : "markdown";
                 }
                 else if (flag === "--fail-on" && failOn === undefined) {
@@ -1436,7 +1441,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 io.writeStderr(`Invalid comparison arguments. ${toolsDiffUsage}`);
                 return 2;
             }
-            const report = await (options.compareMcpToolFilesImpl ?? compareMcpToolFiles)(beforePath, afterPath);
+            const compare = options.compareMcpToolFilesImpl ?? compareMcpToolFiles;
+            const report = await (showNames ? compare(beforePath, afterPath, { showNames: true }) : compare(beforePath, afterPath));
             io.writeStdout(format === "json" ? JSON.stringify(report, null, 2)
                 : format === "markdown" ? renderMcpToolDiffMarkdown(report)
                     : renderMcpToolDiffReport(report));

package/package.json

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