codex-plugin-doctor 1.74.1 → 1.75.0

package/README.md

@@ -589,9 +589,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.74.1
+      - uses: Esquetta/CodexPluginDoctor@v1.75.0
         with:
-          version: "1.74.1"
+          version: "1.75.0"
           path: .
           runtime: "true"
           policy: codex-publish

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

@@ -53,9 +53,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 +258,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(schema).every((key) => key === "anyOf" || DOCUMENTATION_KEYWORDS.has(key)) ? schema.anyOf : null;
+    return Object.keys(value).every((key) => key === "propertyName" || key === "mapping") ? value.propertyName : null;
 }
-function isComposition(schema) {
-    return singleAllOf(schema) !== null || alternatives(schema) !== 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;
 }
 /**
- * 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.
+ * 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;
+    const property = discriminatorProperty(schema.discriminator);
+    return property !== null && discriminatorValues(schema.oneOf, property, document) !== null ? { list: schema.oneOf, discriminator: property } : 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`, 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 +334,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 +349,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 +371,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 +654,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

package/package.json

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