codex-plugin-doctor 1.66.0 → 1.67.0

package/README.md

@@ -121,8 +121,9 @@ 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. Incomplete inputs, invalid definitions, or duplicate names
-prevent a comparison. Impact labels are root-level schema heuristics, not proof
-of compatibility.
+prevent a comparison. Impact labels follow nested object properties, array
+items, and common length and range bounds, but remain heuristics, not proof of
+compatibility.
 See [Offline MCP Tool Diff](docs/guides/offline-tool-diff.md) for matching rules,
 privacy, limits, and exit codes.
 
@@ -562,9 +563,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.66.0
+      - uses: Esquetta/CodexPluginDoctor@v1.67.0
         with:
-          version: "1.66.0"
+          version: "1.67.0"
           path: .
           runtime: "true"
           policy: codex-publish

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

@@ -1,6 +1,6 @@
 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-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-schema-unclassified", "annotation-safety-reduced", "other-fields-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 ToolChangeClassification {
     impact: ToolChangeImpact;

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

@@ -5,6 +5,7 @@ export const TOOL_CHANGE_REASONS = [
     "input-property-removed",
     "input-property-type-narrowed",
     "input-property-enum-narrowed",
+    "input-constraint-tightened",
     "input-additional-properties-closed",
     "input-schema-unclassified",
     "output-schema-removed",
@@ -13,6 +14,7 @@ export const TOOL_CHANGE_REASONS = [
     "output-guarantee-removed",
     "output-property-type-widened",
     "output-property-enum-widened",
+    "output-constraint-loosened",
     "output-schema-unclassified",
     "annotation-safety-reduced",
     "other-fields-unclassified"
@@ -25,7 +27,33 @@ const UNCLASSIFIED_REASONS = new Set([
 // Keywords that document a schema without constraining accepted or produced values.
 const DOCUMENTATION_KEYWORDS = new Set(["title", "description", "examples", "default", "deprecated", "$comment"]);
 const ROOT_STRUCTURAL_KEYWORDS = new Set(["type", "properties", "required", "additionalProperties", "$schema"]);
-const PROPERTY_STRUCTURAL_KEYWORDS = new Set(["type", "enum"]);
+const LOWER_BOUND_KEYWORDS = ["minimum", "minLength", "minItems"];
+const UPPER_BOUND_KEYWORDS = ["maximum", "maxLength", "maxItems"];
+const NESTED_STRUCTURAL_KEYWORDS = new Set([
+    "type", "enum", "properties", "required", "additionalProperties", "items", ...LOWER_BOUND_KEYWORDS, ...UPPER_BOUND_KEYWORDS
+]);
+// Subschemas nested deeper than this below the root are not compared and stay unclassified.
+const MAX_NESTED_DEPTH = 8;
+const CODES = {
+    input: {
+        unclassified: "input-schema-unclassified",
+        rootType: "input-type-narrowed",
+        propertyType: "input-property-type-narrowed",
+        enumChanged: "input-property-enum-narrowed",
+        constraint: "input-constraint-tightened",
+        required: "input-required-added",
+        propertyRemoved: "input-property-removed"
+    },
+    output: {
+        unclassified: "output-schema-unclassified",
+        rootType: "output-type-widened",
+        propertyType: "output-property-type-widened",
+        enumChanged: "output-property-enum-widened",
+        constraint: "output-constraint-loosened",
+        required: "output-guarantee-removed",
+        propertyRemoved: "output-property-removed"
+    }
+};
 // MCP tool annotation defaults, oriented so `true` is the safer reading.
 const SAFETY_HINTS = [
     { key: "readOnlyHint", absent: false, safe: true },
@@ -91,62 +119,104 @@ function keywordsOutside(schema, allowed) {
     }
     return rest;
 }
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+/** Flags bounds of `outer` that `inner` does not satisfy, so `inner` values may fall outside `outer`. */
+function compareBounds(inner, outer, codes, reasons) {
+    for (const [keywords, covered] of [
+        [LOWER_BOUND_KEYWORDS, (innerBound, outerBound) => innerBound >= outerBound],
+        [UPPER_BOUND_KEYWORDS, (innerBound, outerBound) => innerBound <= outerBound]
+    ]) {
+        for (const keyword of keywords) {
+            const outerBound = outer[keyword];
+            const innerBound = inner[keyword];
+            if ((outerBound !== undefined && !isFiniteNumber(outerBound)) || (innerBound !== undefined && !isFiniteNumber(innerBound))) {
+                reasons.add(codes.unclassified);
+            }
+            else if (outerBound !== undefined && (innerBound === undefined || !covered(innerBound, outerBound))) {
+                reasons.add(codes.constraint);
+            }
+        }
+    }
+}
 /**
- * Compares one property subschema. `direction` is "input" when callers must keep being
- * accepted (after must cover before) and "output" when consumers must keep understanding
- * results (before must cover after).
+ * Compares one schema and its object and array subschemas. `direction` is "input" when callers
+ * must keep being accepted (after must cover before) and "output" when consumers must keep
+ * understanding results (before must cover after). Depth 0 is the tool's root schema.
  */
-function compareProperty(before, after, direction, equal, reasons) {
+function compareSchema(before, after, direction, depth, equal, reasons) {
     if (equal(before, after))
         return;
-    const unclassified = direction === "input" ? "input-schema-unclassified" : "output-schema-unclassified";
-    if (!isJsonObject(before) || !isJsonObject(after)
-        || !equal(keywordsOutside(before, PROPERTY_STRUCTURAL_KEYWORDS), keywordsOutside(after, PROPERTY_STRUCTURAL_KEYWORDS))) {
-        reasons.add(unclassified);
+    const codes = CODES[direction];
+    const root = depth === 0;
+    const structural = root ? ROOT_STRUCTURAL_KEYWORDS : NESTED_STRUCTURAL_KEYWORDS;
+    if (depth > MAX_NESTED_DEPTH || !isJsonObject(before) || !isJsonObject(after)
+        || !equal(keywordsOutside(before, structural), keywordsOutside(after, structural))
+        || !equal(before.$schema, after.$schema)) {
+        reasons.add(codes.unclassified);
         return;
     }
     const [inner, outer] = direction === "input" ? [before, after] : [after, before];
-    if (!typesCovered(typeSet(inner), typeSet(outer))) {
-        reasons.add(direction === "input" ? "input-property-type-narrowed" : "output-property-type-widened");
+    // unevaluatedItems/unevaluatedProperties apply to whatever items/additionalProperties leave
+    // uncovered, so a change in either cannot be judged on its own.
+    const unevaluated = ["unevaluatedItems", "unevaluatedProperties"].some((key) => before[key] !== undefined || after[key] !== undefined);
+    if (!typesCovered(typeSet(inner), typeSet(outer)))
+        reasons.add(root ? codes.rootType : codes.propertyType);
+    if (!root) {
+        const enumResult = enumCovered(inner.enum, outer.enum, equal);
+        if (enumResult === null)
+            reasons.add(codes.unclassified);
+        else if (!enumResult)
+            reasons.add(codes.enumChanged);
+        compareBounds(inner, outer, codes, reasons);
+        if (!equal(before.items, after.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);
+        }
     }
-    const enumResult = enumCovered(inner.enum, outer.enum, equal);
-    if (enumResult === null)
-        reasons.add(unclassified);
-    else if (!enumResult)
-        reasons.add(direction === "input" ? "input-property-enum-narrowed" : "output-property-enum-widened");
-}
-function classifyInputSchema(before, after, equal, reasons) {
-    if (!isJsonObject(before) || !isJsonObject(after)
-        || !equal(keywordsOutside(before, ROOT_STRUCTURAL_KEYWORDS), keywordsOutside(after, ROOT_STRUCTURAL_KEYWORDS))
-        || !equal(before.$schema, after.$schema)) {
-        reasons.add("input-schema-unclassified");
-        return;
-    }
-    if (!typesCovered(typeSet(before), typeSet(after)))
-        reasons.add("input-type-narrowed");
-    const beforeRequired = stringSet(before.required);
-    const afterRequired = stringSet(after.required);
+    const innerRequired = stringSet(inner.required);
+    const outerRequired = stringSet(outer.required);
     const beforeProperties = objectMap(before.properties);
     const afterProperties = objectMap(after.properties);
-    if (beforeRequired === null || afterRequired === null || beforeProperties === null || afterProperties === null) {
-        reasons.add("input-schema-unclassified");
+    if (innerRequired === null || outerRequired === null || beforeProperties === null || afterProperties === null) {
+        reasons.add(codes.unclassified);
         return;
     }
-    for (const key of afterRequired) {
-        if (!beforeRequired.has(key))
-            reasons.add("input-required-added");
+    for (const key of outerRequired) {
+        if (!innerRequired.has(key))
+            reasons.add(codes.required);
     }
     for (const key of Object.keys(beforeProperties)) {
         if (!Object.hasOwn(afterProperties, key))
-            reasons.add("input-property-removed");
+            reasons.add(codes.propertyRemoved);
         else
-            compareProperty(beforeProperties[key], afterProperties[key], "input", equal, reasons);
+            compareSchema(beforeProperties[key], afterProperties[key], direction, depth + 1, equal, reasons);
     }
+    // In a nested object whose undeclared keys were open or governed by other keywords, a newly
+    // declared property can reject values callers send (input) or produce values consumers did
+    // not expect (output).
+    const addedKeys = Object.keys(afterProperties).filter((key) => !Object.hasOwn(beforeProperties, key));
+    if (!root && addedKeys.length > 0) {
+        const governed = isJsonObject(before.additionalProperties) || Object.keys(keywordsOutside(before, structural)).length > 0;
+        const open = Object.keys(beforeProperties).length === 0 && before.additionalProperties !== false;
+        if (governed || (direction === "input" && open))
+            reasons.add(codes.unclassified);
+    }
+    // Callers already send a key that was required before it was declared, with any value.
+    if (direction === "input" && addedKeys.some((key) => innerRequired.has(key)))
+        reasons.add(codes.unclassified);
     if (!equal(before.additionalProperties, after.additionalProperties)) {
-        if (after.additionalProperties === false)
+        if (unevaluated)
+            reasons.add(codes.unclassified);
+        else if (direction === "input" && after.additionalProperties === false)
             reasons.add("input-additional-properties-closed");
-        else if (!(after.additionalProperties === undefined || after.additionalProperties === true))
-            reasons.add("input-schema-unclassified");
+        else if (direction === "output" || !(after.additionalProperties === undefined || after.additionalProperties === true))
+            reasons.add(codes.unclassified);
     }
 }
 function classifyOutputSchema(before, after, equal, reasons) {
@@ -156,34 +226,7 @@ function classifyOutputSchema(before, after, equal, reasons) {
         reasons.add("output-schema-removed");
         return;
     }
-    if (!isJsonObject(before) || !isJsonObject(after)
-        || !equal(keywordsOutside(before, ROOT_STRUCTURAL_KEYWORDS), keywordsOutside(after, ROOT_STRUCTURAL_KEYWORDS))
-        || !equal(before.$schema, after.$schema)) {
-        reasons.add("output-schema-unclassified");
-        return;
-    }
-    if (!typesCovered(typeSet(after), typeSet(before)))
-        reasons.add("output-type-widened");
-    const beforeRequired = stringSet(before.required);
-    const afterRequired = stringSet(after.required);
-    const beforeProperties = objectMap(before.properties);
-    const afterProperties = objectMap(after.properties);
-    if (beforeRequired === null || afterRequired === null || beforeProperties === null || afterProperties === null) {
-        reasons.add("output-schema-unclassified");
-        return;
-    }
-    for (const key of beforeRequired) {
-        if (!afterRequired.has(key))
-            reasons.add("output-guarantee-removed");
-    }
-    for (const key of Object.keys(beforeProperties)) {
-        if (!Object.hasOwn(afterProperties, key))
-            reasons.add("output-property-removed");
-        else
-            compareProperty(beforeProperties[key], afterProperties[key], "output", equal, reasons);
-    }
-    if (!equal(before.additionalProperties, after.additionalProperties))
-        reasons.add("output-schema-unclassified");
+    compareSchema(before, after, "output", 0, equal, reasons);
 }
 function hint(annotations, key, absent) {
     if (annotations === undefined)
@@ -219,7 +262,7 @@ export function classifyAddedTool() {
 export function classifyChangedTool(before, after, fields, equal) {
     const reasons = new Set();
     if (fields.includes("inputSchema"))
-        classifyInputSchema(before.inputSchema, after.inputSchema, equal, reasons);
+        compareSchema(before.inputSchema, after.inputSchema, "input", 0, equal, reasons);
     if (fields.includes("outputSchema"))
         classifyOutputSchema(before.outputSchema, after.outputSchema, equal, reasons);
     if (fields.includes("annotations"))

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

@@ -19,7 +19,7 @@ export function renderMcpToolDiffReport(report) {
         `Server catalog: ${report.coverage.serverCatalog}`,
         `Tool execution: ${report.coverage.toolExecution}`,
         `Impact classification: ${report.coverage.impactClassification}`,
-        "Only the supplied responses are compared. Impact labels are root-level schema heuristics: a compatible label or an unchanged result does not establish compatibility.",
+        "Only the supplied responses are compared. Impact labels are schema heuristics: a compatible label or an unchanged result does not establish compatibility.",
         ...["before", "after"].flatMap((side) => {
             const source = report[side];
             const label = side === "before" ? "Before" : "After";

package/package.json

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