codex-plugin-doctor 1.74.1 → 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.74.1
+      - uses: Esquetta/CodexPluginDoctor@v1.76.0
         with:
-          version: "1.74.1"
+          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",
@@ -53,9 +106,9 @@ const MAX_NESTED_DEPTH = 8;
 // Keywords that only hold or name subschemas and never validate the object's own keys, so a
 // new property beside them stays compatible. Any other unclassified keyword may govern keys.
 const DEFINITION_KEYWORDS = new Set(["$defs", "definitions", "$id", "$anchor", "$dynamicAnchor"]);
-// `anyOf` alternatives beyond this many on either side are not paired.
+// `anyOf` or discriminated `oneOf` alternatives beyond this many on either side are not paired.
 const MAX_ALTERNATIVES = 32;
-// Composition wrappers (`allOf` and `anyOf`) followed along one path; deeper wrappers are unclassified.
+// Composition wrappers (`allOf`, `anyOf`, and discriminated `oneOf`) followed along one path; deeper wrappers are unclassified.
 const MAX_WRAPPER_HOPS = 16;
 // A `$ref` chain longer than this, such as an alias cycle, is not resolved.
 const MAX_REFERENCE_HOPS = 8;
@@ -258,18 +311,67 @@ function singleAllOf(schema) {
         return null;
     return Object.keys(schema).every((key) => key === "allOf" || DOCUMENTATION_KEYWORDS.has(key)) ? { inner: schema.allOf[0] } : null;
 }
-/** The alternatives of a schema that is only `anyOf` with documentation, or null. */
-function alternatives(schema) {
-    if (!isJsonObject(schema) || !Array.isArray(schema.anyOf))
+function discriminatorProperty(value) {
+    if (!isJsonObject(value) || typeof value.propertyName !== "string")
+        return null;
+    return Object.keys(value).every((key) => key === "propertyName" || key === "mapping") ? value.propertyName : null;
+}
+/**
+ * The discriminator value of each alternative, when every alternative resolves to an object schema
+ * that requires the property and fixes it to one value no other alternative uses; null otherwise.
+ * Such alternatives cannot both match one value, so their oneOf accepts what an anyOf would.
+ */
+function discriminatorValues(list, property, document) {
+    // Draft-04 has no const, and many validators of earlier drafts drop keywords beside a $ref.
+    if (list.length > MAX_ALTERNATIVES || (isJsonObject(document) && typeof document.$schema === "string" && /draft-0[34]/u.test(document.$schema)))
+        return null;
+    const values = new Map();
+    const seen = new Set();
+    for (const alternative of list) {
+        const schema = resolveReferences(alternative, document)?.schema;
+        if (!isJsonObject(schema))
+            return null;
+        const types = typeSet(schema);
+        const declared = objectMap(schema.properties)?.[property];
+        if (types === null || types.size !== 1 || !types.has("object") || !stringSet(schema.required)?.has(property)
+            || !isJsonObject(declared) || declared.$ref !== undefined)
+            return null;
+        const fixed = Object.hasOwn(declared, "const") ? [declared.const] : declared.enum;
+        if (!Array.isArray(fixed) || fixed.length !== 1 || (Array.isArray(declared.enum) && Object.hasOwn(declared, "const")
+            && !(declared.enum.length === 1 && Object.is(declared.enum[0], declared.const))))
+            return null;
+        const value = fixed[0];
+        if (value !== null && !["string", "number", "boolean"].includes(typeof value))
+            return null;
+        const key = JSON.stringify(value);
+        if (seen.has(key))
+            return null;
+        seen.add(key);
+        values.set(alternative, key);
+    }
+    return values;
+}
+/**
+ * The alternatives of a schema that is only `anyOf`, or only a discriminated `oneOf` whose
+ * alternatives exclude each other, with documentation beside it; null otherwise.
+ */
+function alternatives(schema, document) {
+    if (!isJsonObject(schema))
+        return null;
+    if (Array.isArray(schema.anyOf)) {
+        return Object.keys(schema).every((key) => key === "anyOf" || DOCUMENTATION_KEYWORDS.has(key)) ? { list: schema.anyOf, discriminator: null } : null;
+    }
+    if (!Array.isArray(schema.oneOf) || !Object.keys(schema).every((key) => key === "oneOf" || key === "discriminator" || DOCUMENTATION_KEYWORDS.has(key)))
         return null;
-    return Object.keys(schema).every((key) => key === "anyOf" || DOCUMENTATION_KEYWORDS.has(key)) ? schema.anyOf : null;
+    const property = discriminatorProperty(schema.discriminator);
+    return property !== null && discriminatorValues(schema.oneOf, property, document) !== null ? { list: schema.oneOf, discriminator: property } : null;
 }
-function isComposition(schema) {
-    return singleAllOf(schema) !== null || alternatives(schema) !== null;
+function isComposition(schema, document) {
+    return singleAllOf(schema) !== null || alternatives(schema, document) !== null;
 }
 /**
- * Compares two schemas when at least one is a one-element `allOf` or an `anyOf` with only
- * documentation beside it. Wrappers keep the depth, so their own count bounds how far one path unwraps.
+ * Compares two schemas when at least one is a one-element `allOf`, an `anyOf`, or a discriminated
+ * `oneOf` with only documentation beside it. Wrappers keep the depth, so their own count bounds how far one path unwraps.
  */
 function compareComposition(before, after, direction, depth, equal, reasons, scope) {
     if (scope.wrappers >= MAX_WRAPPER_HOPS) {
@@ -285,7 +387,9 @@ function compareComposition(before, after, direction, depth, equal, reasons, sco
     }
     else {
         // A schema that is not an anyOf compares as an anyOf with that schema as its only alternative.
-        compareAlternatives(alternatives(before) ?? [before], alternatives(after) ?? [after], direction, depth, equal, reasons, scope);
+        const beforeAlternatives = alternatives(before, scope.before) ?? { list: [before], discriminator: null };
+        const afterAlternatives = alternatives(after, scope.after) ?? { list: [after], discriminator: null };
+        compareAlternatives(beforeAlternatives, afterAlternatives, direction, depth, equal, reasons, scope);
     }
     scope.wrappers -= 1;
 }
@@ -298,19 +402,20 @@ function alternativeKey(alternative) {
     return alternative.type === undefined ? null : `type:${JSON.stringify(alternative.type)}`;
 }
 /**
- * Compares `anyOf` alternatives. A value is accepted when any alternative accepts it, so inputs stay
- * compatible when every earlier alternative is covered by a later one, and outputs when every later
- * alternative is covered by an earlier one. Identical alternatives match first, then alternatives with
- * the same reference target or type, then a single remaining alternative on each side.
+ * Compares `anyOf` alternatives, or discriminated `oneOf` alternatives that exclude each other. A
+ * value is accepted when any alternative accepts it, so inputs stay compatible when every earlier
+ * alternative is covered by a later one, and outputs when every later alternative is covered by an
+ * earlier one. Identical alternatives match first, then alternatives with the same discriminator
+ * value, then the same reference target or type, then a single remaining alternative on each side.
  */
 function compareAlternatives(before, after, direction, depth, equal, reasons, scope) {
     const codes = CODES[direction];
-    if (before.length > MAX_ALTERNATIVES || after.length > MAX_ALTERNATIVES) {
+    if (before.list.length > MAX_ALTERNATIVES || after.list.length > MAX_ALTERNATIVES) {
         reasons.add(codes.unclassified);
         return;
     }
-    const unpairedBefore = [...before];
-    const unpairedAfter = [...after];
+    const unpairedBefore = [...before.list];
+    const unpairedAfter = [...after.list];
     for (let index = unpairedBefore.length - 1; index >= 0; index -= 1) {
         const match = unpairedAfter.findIndex((candidate) => sameMeaning(unpairedBefore[index], candidate, equal, scope));
         if (match !== -1) {
@@ -319,17 +424,25 @@ function compareAlternatives(before, after, direction, depth, equal, reasons, sc
         }
     }
     const pairs = [];
-    for (const key of new Set(unpairedBefore.map(alternativeKey))) {
-        if (key === null)
-            continue;
-        const beforeMatches = unpairedBefore.filter((alternative) => alternativeKey(alternative) === key);
-        const afterMatches = unpairedAfter.filter((alternative) => alternativeKey(alternative) === key);
-        if (beforeMatches.length !== 1 || afterMatches.length !== 1)
-            continue;
-        pairs.push([beforeMatches[0], afterMatches[0]]);
-        unpairedBefore.splice(unpairedBefore.indexOf(beforeMatches[0]), 1);
-        unpairedAfter.splice(unpairedAfter.indexOf(afterMatches[0]), 1);
+    const pairBy = (beforeKey, afterKey) => {
+        for (const key of new Set(unpairedBefore.map(beforeKey))) {
+            if (key === null)
+                continue;
+            const beforeMatches = unpairedBefore.filter((alternative) => beforeKey(alternative) === key);
+            const afterMatches = unpairedAfter.filter((alternative) => afterKey(alternative) === key);
+            if (beforeMatches.length !== 1 || afterMatches.length !== 1)
+                continue;
+            pairs.push([beforeMatches[0], afterMatches[0]]);
+            unpairedBefore.splice(unpairedBefore.indexOf(beforeMatches[0]), 1);
+            unpairedAfter.splice(unpairedAfter.indexOf(afterMatches[0]), 1);
+        }
+    };
+    if (before.discriminator !== null && before.discriminator === after.discriminator) {
+        const beforeValues = discriminatorValues(before.list, before.discriminator, scope.before);
+        const afterValues = discriminatorValues(after.list, after.discriminator, scope.after);
+        pairBy((alternative) => beforeValues?.get(alternative) ?? null, (alternative) => afterValues?.get(alternative) ?? null);
     }
+    pairBy(alternativeKey, alternativeKey);
     if (unpairedBefore.length === 1 && unpairedAfter.length === 1) {
         pairs.push([unpairedBefore.pop(), unpairedAfter.pop()]);
     }
@@ -594,20 +707,47 @@ function compareSchema(before, after, direction, depth, equal, reasons, scope) {
     }
     // When only one side is a composition, the other keeps its reference unresolved, so it can still
     // pair with an alternative that refers to the same definition, as when a model becomes optional.
-    const beforeComposed = isComposition(resolvedBefore.schema);
-    const afterComposed = isComposition(resolvedAfter.schema);
+    const beforeComposed = isComposition(resolvedBefore.schema, scope.before);
+    const afterComposed = isComposition(resolvedAfter.schema, scope.after);
+    // True when the original schema, before its reference is resolved, pairs with an alternative of
+    // the composite, as a model or a union does with its nullable anyOf.
+    const pairsWithAlternative = (original, composite, document) => {
+        const key = alternativeKey(original);
+        return (alternatives(composite, document)?.list ?? [])
+            .some((alternative) => (key !== null && alternativeKey(alternative) === key) || sameMeaning(original, alternative, equal, scope));
+    };
     if (beforeComposed !== afterComposed) {
         // The reference is kept only when an alternative can pair with it; otherwise its target compares
         // with inline alternatives by type.
         const composite = beforeComposed ? resolvedBefore.schema : resolvedAfter.schema;
         const original = beforeComposed ? after : before;
-        const plainKey = alternativeKey(original);
-        const keepReference = (alternatives(composite) ?? [])
-            .some((alternative) => (plainKey !== null && alternativeKey(alternative) === plainKey) || sameMeaning(original, alternative, equal, scope));
+        const keepReference = pairsWithAlternative(original, composite, beforeComposed ? scope.before : scope.after);
         const plain = keepReference ? original : (beforeComposed ? resolvedAfter.schema : resolvedBefore.schema);
         compareComposition(beforeComposed ? composite : plain, beforeComposed ? plain : composite, direction, depth, equal, reasons, scope);
         return;
     }
+    if (beforeComposed && afterComposed) {
+        // A composite that appears whole as one alternative of the other side, such as a union made
+        // nullable, compares as that single alternative rather than alternative by alternative.
+        // A reference match counts only while the matched alternative is still a composite, so a
+        // definition that stopped being a union compares alternative by alternative instead.
+        const isWholeAlternative = (original, composite, document) => (alternatives(composite, document)?.list ?? []).some((alternative) => sameMeaning(original, alternative, equal, scope)
+            || (alternativeKey(original) !== null && alternativeKey(alternative) === alternativeKey(original)
+                && isComposition(resolveReferences(alternative, document)?.schema, document)));
+        const beforeIsAlternative = isWholeAlternative(before, resolvedAfter.schema, scope.after);
+        const afterIsAlternative = isWholeAlternative(after, resolvedBefore.schema, scope.before);
+        if (beforeIsAlternative !== afterIsAlternative) {
+            if (scope.wrappers >= MAX_WRAPPER_HOPS) {
+                reasons.add(codes.unclassified);
+                return;
+            }
+            const side = (whole, original, composite, document) => whole ? { list: [original], discriminator: null } : alternatives(composite, document) ?? { list: [composite], discriminator: null };
+            scope.wrappers += 1;
+            compareAlternatives(side(beforeIsAlternative, before, resolvedBefore.schema, scope.before), side(afterIsAlternative, after, resolvedAfter.schema, scope.after), direction, depth, equal, reasons, scope);
+            scope.wrappers -= 1;
+            return;
+        }
+    }
     if (resolvedBefore.ref !== undefined || resolvedAfter.ref !== undefined) {
         // A reference pair already being compared further up is assumed to hold, so recursive
         // definitions terminate; a pair with one inline side is bounded by the depth limit. A pair
@@ -665,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);
@@ -683,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
@@ -747,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"] };
@@ -755,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.74.1",
+  "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",