@amritk/lint 0.2.0 → 0.3.0

package/dist/parsers/yaml.js

@@ -1,54 +1,202 @@
-import { isMap, isPair, isScalar, isSeq, parseDocument } from '@amritk/yaml';
+import { isAlias, isMap, isPair, isScalar, isSeq, parseAllDocuments, } from '@amritk/yaml';
 import { createLineMap } from './lines.js';
 import { DiagnosticSeverity, } from './types.js';
-const pathKey = (path) => path.join('\0');
+/**
+ * Encodes a path into a lookup key. Each segment is tagged by kind (`.` for a
+ * key, `[]` for an index) so distinct paths cannot collide: a plain `join` turns
+ * a `null` map key into `''` (colliding with the root path `[]`) and cannot tell
+ * the numeric index `0` from the string key `"0"`. The tags keep them apart.
+ */
+const pathKey = (path) => path.map((segment) => (typeof segment === 'number' ? `[${segment}]` : `.${segment}`)).join('');
+/**
+ * Canonically serializes a complex (map/seq) mapping key into a stable, distinct
+ * segment. `toJS`'s `keyText` collapses every complex key to `''`, so two
+ * distinct complex keys (and their whole value subtrees) would share one index
+ * slot and clobber each other. A structural serialization keeps them apart:
+ * `[a,b]` for a sequence key, `{k:v}` for a mapping key, recursively. Strings are
+ * quoted so a scalar member can't be confused with structure, and aliases render
+ * as `*name` (never expanded, so this stays bounded regardless of the anchor).
+ */
+const serializeComplexKey = (node) => {
+    if (isSeq(node))
+        return `[${node.items.map(serializeComplexKey).join(',')}]`;
+    if (isMap(node)) {
+        return `{${node.items
+            .filter(isPair)
+            .map((pair) => `${serializeComplexKey(pair.key)}:${pair.value ? serializeComplexKey(pair.value) : 'null'}`)
+            .join(',')}}`;
+    }
+    if (isAlias(node))
+        return `*${node.source}`;
+    const v = node.value;
+    return typeof v === 'string' ? JSON.stringify(v) : v === null ? 'null' : String(v);
+};
+/**
+ * Stringifies a mapping key into an index segment. Scalar, null, and alias keys
+ * match `toJS`'s `keyText` (`null`, the `String()` form, `*name`) so scalar-keyed
+ * paths line up with the projected data. Complex (map/seq) keys — which `toJS`
+ * cannot address individually — get a canonical structural serialization instead
+ * of collapsing to `''`, so distinct complex keys occupy distinct index slots.
+ */
+const keyToString = (key) => {
+    if (isScalar(key)) {
+        const v = key.value;
+        return typeof v === 'string' ? v : v === null ? 'null' : String(v);
+    }
+    if (isAlias(key))
+        return `*${key.source}`;
+    return serializeComplexKey(key);
+};
 /**
  * Parses YAML (a JSON superset, so this handles both) into data plus a source
  * map, surfacing duplicate-key and incompatible-value diagnostics per `options`.
+ *
+ * A `---`-separated stream is parsed as multiple documents (via
+ * `parseAllDocuments`), each linted independently: `data` becomes an array of
+ * per-document values and every position key / finding path is prefixed with the
+ * zero-based document index, so a violation in a later document resolves to its
+ * own range instead of being silently dropped. A single-document source keeps the
+ * flat shape — `data` is the document value and paths are unprefixed — so existing
+ * callers and rulesets are unaffected. Node ranges are absolute offsets into the
+ * shared source, so diagnostics and positions in later documents are already
+ * correct without any per-document offset arithmetic.
  */
 export const parseYaml = (source, options = {}) => {
     const lineMap = createLineMap(source);
-    const dedupe = options.duplicateKeys === 'off' || options.duplicateKeys === false;
-    const doc = parseDocument(source, { uniqueKeys: !dedupe });
+    const duplicateKeys = options.duplicateKeys;
+    const dedupe = duplicateKeys === 'off' || duplicateKeys === false;
+    // A configured severity (Warning/Information/Hint) still detects duplicates; we
+    // just re-map the reported severity below. Only `off`/`false` turns detection off.
+    const dupSeverity = typeof duplicateKeys === 'number' ? duplicateKeys : DiagnosticSeverity.Error;
+    // Incompatible-value detection is opt-in: it runs only when a severity is
+    // configured. `undefined`/`off`/`false` leaves it disabled.
+    const incompatibleValues = options.incompatibleValues;
+    const incompatSeverity = typeof incompatibleValues === 'number' ? incompatibleValues : undefined;
+    const docs = parseAllDocuments(source, { uniqueKeys: !dedupe });
     const index = new Map();
+    const diagnostics = [];
+    const pushError = (severity, message, start, end, code) => {
+        diagnostics.push({
+            ...(code !== undefined ? { code } : {}),
+            message,
+            severity,
+            range: { start: lineMap.positionAt(start), end: lineMap.positionAt(end) },
+        });
+    };
     const rangeOf = (node) => ({
         start: lineMap.positionAt(node.start),
         end: lineMap.positionAt(node.end),
     });
+    // Aliases are re-expanded into every path that reaches them, so nested aliases
+    // (the "billion laughs" shape) can fan out super-linearly. Bound the total
+    // nodes walked across the whole stream; on exhaustion we stop extending the
+    // index rather than throw — untouched paths simply fall back to the closest
+    // indexed ancestor.
+    let budget = Math.max(100_000, source.length * 100);
+    /** True when a pair is a `<<` merge key, whose value folds into the parent map. */
+    const isMergePair = (pair) => isScalar(pair.key) && pair.key.source === '<<';
+    /**
+     * Indexes the keys of a merged map (or list of maps, reached through the `<<`
+     * value) at the parent `path`. A merged key is skipped when the path is already
+     * occupied — by an explicit key or an earlier merge — mirroring `toJS`, where
+     * explicit keys and earlier merges win over later ones.
+     */
+    const walkMerge = (node, path) => {
+        const target = node != null && isAlias(node) ? node.target : node;
+        if (target == null)
+            return;
+        if (isSeq(target)) {
+            for (const item of target.items)
+                walkMerge(item, path);
+            return;
+        }
+        if (!isMap(target))
+            return;
+        for (const item of target.items) {
+            if (!isPair(item))
+                continue;
+            if (isMergePair(item)) {
+                walkMerge(item.value, path);
+                continue;
+            }
+            const childPath = [...path, keyToString(item.key)];
+            if (!index.has(pathKey(childPath)))
+                walk(item.value, childPath);
+        }
+    };
     const walk = (node, path) => {
-        if (node == null)
+        if (node == null || budget-- <= 0)
             return;
         index.set(pathKey(path), rangeOf(node));
-        if (isMap(node)) {
-            for (const item of node.items) {
+        if (isScalar(node)) {
+            // The core schema projects `.nan`/`.inf`/`-.inf` to non-finite JS numbers,
+            // which `JSON.stringify` silently rewrites to `null`. Report them when the
+            // caller opted in, so a value that won't survive a JSON round-trip is caught.
+            const value = node.value;
+            if (incompatSeverity !== undefined && typeof value === 'number' && !Number.isFinite(value)) {
+                pushError(incompatSeverity, `Value ${String(value)} cannot be represented in JSON and will serialize to null.`, node.start, node.end, 'INCOMPATIBLE_VALUE');
+            }
+            return;
+        }
+        // Follow an alias to its anchor definition so paths reachable only through the
+        // alias resolve to the anchored node (the alias itself keeps the range set
+        // above); an unresolved alias has no target and simply stops here.
+        const target = isAlias(node) ? node.target : node;
+        if (target == null)
+            return;
+        if (isMap(target)) {
+            const merges = [];
+            for (const item of target.items) {
                 if (!isPair(item))
                     continue;
-                const key = item.key;
-                const keyName = isScalar(key) ? key.value : String(key);
-                walk(item.value, [...path, keyName]);
+                if (isMergePair(item)) {
+                    merges.push(item.value);
+                    continue;
+                }
+                walk(item.value, [...path, keyToString(item.key)]);
             }
+            // Merged keys fill positions the explicit keys above did not claim.
+            for (const merge of merges)
+                walkMerge(merge, path);
         }
-        else if (isSeq(node)) {
-            node.items.forEach((item, i) => {
+        else if (isSeq(target)) {
+            target.items.forEach((item, i) => {
                 walk(item, [...path, i]);
             });
         }
     };
-    walk(doc.contents, []);
-    const data = doc.toJS();
-    const diagnostics = [];
-    const pushError = (severity, message, start, end) => {
-        diagnostics.push({
-            message,
-            severity,
-            range: { start: lineMap.positionAt(start), end: lineMap.positionAt(end) },
-        });
+    const collectProblems = (doc) => {
+        for (const err of doc.errors) {
+            // Duplicate keys honor the configured severity; every other parser error is
+            // a hard error.
+            const severity = err.code === 'DUPLICATE_KEY' ? dupSeverity : DiagnosticSeverity.Error;
+            pushError(severity, err.message, err.start, err.end);
+        }
+        for (const warn of doc.warnings) {
+            pushError(DiagnosticSeverity.Warning, warn.message, warn.start, warn.end);
+        }
     };
-    for (const err of doc.errors) {
-        pushError(DiagnosticSeverity.Error, err.message, err.start, err.end);
+    let data;
+    if (docs.length > 1) {
+        // Multi-document stream: index each document under its own `[i, …]` prefix and
+        // project to an array of per-document values.
+        data = docs.map((doc, i) => {
+            walk(doc.contents, [i]);
+            collectProblems(doc);
+            return doc.toJS();
+        });
     }
-    for (const warn of doc.warnings) {
-        pushError(DiagnosticSeverity.Warning, warn.message, warn.start, warn.end);
+    else {
+        // Single document (or an empty stream): keep the flat, unprefixed shape.
+        const doc = docs[0];
+        if (doc) {
+            walk(doc.contents, []);
+            collectProblems(doc);
+            data = doc.toJS();
+        }
+        else {
+            data = null;
+        }
     }
     const getLocationForJsonPath = (path, closest = false) => {
         const p = path.slice();
@@ -61,5 +209,5 @@ export const parseYaml = (source, options = {}) => {
             p.pop();
         }
     };
-    return { data, diagnostics, getLocationForJsonPath };
+    return { data: data, diagnostics, getLocationForJsonPath };
 };

package/dist/rules/openapi/fixers.js

@@ -10,6 +10,24 @@ const getAtPath = (data, path) => {
 };
 const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value);
 const stripTrailingSlash = (value) => value.replace(/\/+$/, '');
+/**
+ * A deterministic, order-independent serialization used as an equality key. Plain
+ * `JSON.stringify` is sensitive to object key order (`{a,b}` vs `{b,a}`), so two
+ * deeply-equal enum entries could be seen as different and left un-deduplicated —
+ * disagreeing with the `duplicated-entry-in-enum` rule (which compares by value)
+ * and preventing `--fix` from converging. Sorting keys recursively fixes that.
+ */
+const canonicalKey = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalKey).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalKey(value[key])}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+};
 /**
  * `oas2-host-trailing-slash` / `oas3-server-trailing-slash`: drop the trailing
  * slash from a string value (host or server URL).
@@ -29,13 +47,19 @@ const trailingSlashValue = {
 /** `path-keys-no-trailing-slash`: rename a `paths` key to drop its trailing slash. */
 const pathKeyTrailingSlash = {
     safe: true,
-    fix: ({ diagnostic }) => {
+    fix: ({ diagnostic, data }) => {
         const key = diagnostic.path[diagnostic.path.length - 1];
         if (typeof key !== 'string')
             return undefined;
         const stripped = stripTrailingSlash(key);
         if (stripped === key || stripped === '')
             return undefined;
+        // Renaming `/foo/` onto an existing `/foo` would collide and silently drop a
+        // path, so skip when the stripped key already exists (same guard as
+        // `pathKeyQueryString`).
+        const paths = getAtPath(data, diagnostic.path.slice(0, -1));
+        if (isObject(paths) && stripped in paths)
+            return undefined;
         return { op: 'renameProperty', path: diagnostic.path, newKey: stripped };
     },
 };
@@ -58,7 +82,7 @@ const duplicatedEnum = {
         const seen = new Set();
         const duplicates = [];
         array.forEach((item, index) => {
-            const key = JSON.stringify(item);
+            const key = canonicalKey(item);
             if (seen.has(key))
                 duplicates.push(index);
             else
@@ -69,6 +93,14 @@ const duplicatedEnum = {
         return { op: 'removeItems', path: diagnostic.path, indices: duplicates };
     },
 };
+// Mirror the `alphabetical` built-in's comparator exactly so that sorting here
+// produces an order the rule considers sorted — otherwise `--fix` could reorder
+// into a sequence the rule still flags and never converge.
+const compareAlphabetical = (a, b) => {
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    return String(a).localeCompare(String(b));
+};
 /** `openapi-tags-alphabetical`: reorder the top-level `tags` array by `name`. */
 const tagsAlphabetical = {
     safe: true,
@@ -78,8 +110,8 @@ const tagsAlphabetical = {
         const array = getAtPath(data, arrayPath);
         if (!Array.isArray(array))
             return undefined;
-        const nameOf = (item) => item != null && typeof item === 'object' ? String(item['name']) : String(item);
-        const order = array.map((_, index) => index).sort((a, b) => nameOf(array[a]).localeCompare(nameOf(array[b])));
+        const nameOf = (item) => item != null && typeof item === 'object' ? item['name'] : item;
+        const order = array.map((_, index) => index).sort((a, b) => compareAlphabetical(nameOf(array[a]), nameOf(array[b])));
         if (order.every((value, index) => value === index))
             return undefined;
         return { op: 'reorderArray', path: arrayPath, order };
@@ -169,6 +201,32 @@ const noNullable = {
         return remove;
     },
 };
+/**
+ * `oas3_1-schema-example-deprecated`: migrate a Schema Object's singular
+ * `example` to the JSON Schema 2020-12 `examples` array (`example: X` →
+ * `examples: [X]`). Safe and mechanical, but skipped when an `examples` array is
+ * already present so an existing one is never clobbered. The finding points at
+ * the `example` key, whose parent is the schema.
+ */
+const schemaExampleDeprecated = {
+    safe: true,
+    fix: ({ diagnostic, data }) => {
+        const schemaPath = diagnostic.path.slice(0, -1);
+        const schema = getAtPath(data, schemaPath);
+        if (!isObject(schema) || !('example' in schema))
+            return undefined;
+        // Do not overwrite an already-present `examples` array.
+        if ('examples' in schema)
+            return undefined;
+        return [
+            // `insertProperty` (not `setValue`) because `examples` is a new key: an
+            // op whose path doesn't already resolve is a no-op, and only
+            // `insertProperty` adds a missing key to the existing schema object.
+            { op: 'insertProperty', path: schemaPath, key: 'examples', value: [schema['example']] },
+            { op: 'removeProperty', path: diagnostic.path },
+        ];
+    },
+};
 /**
  * Auto-fixers for the mechanically-repairable OpenAPI rules, keyed by rule
  * code. Pass these to `@amritk/lint`'s `fixDocument` (as its `fixers`), or wrap
@@ -186,4 +244,5 @@ export const oasFixers = {
     'oas3-unused-component': unusedComponent,
     'oas2-unused-definition': unusedComponent,
     'oas3_1-no-nullable': noNullable,
+    'oas3_1-schema-example-deprecated': schemaExampleDeprecated,
 };

package/dist/rules/openapi/formats.js

@@ -1,15 +1,22 @@
 const isObject = (value) => typeof value === 'object' && value !== null;
 const openapiVersion = (document) => isObject(document) && typeof document['openapi'] === 'string' ? document['openapi'] : undefined;
+// Minor versions are matched with an anchored `3.N` followed by a `.` or the
+// end of string, so a future `3.10.x` is not mistaken for `3.1.x` — a plain
+// `startsWith('3.1')` prefix check would misclassify `3.10.0` as OpenAPI 3.1.
+const matchesMinor = (document, minor) => {
+    const version = openapiVersion(document);
+    return version !== undefined && new RegExp(`^3\\.${minor}(\\.|$)`).test(version);
+};
 /** Matches OpenAPI/Swagger 2.0 (`swagger: "2.0"`). */
 export const oas2 = (document) => isObject(document) && document['swagger'] === '2.0';
 /** Matches any OpenAPI 3.x (`openapi: 3.*`). */
-export const oas3 = (document) => openapiVersion(document)?.startsWith('3.') ?? false;
+export const oas3 = (document) => /^3\.\d/.test(openapiVersion(document) ?? '');
 /** Matches OpenAPI 3.0.x specifically. */
-export const oas3_0 = (document) => openapiVersion(document)?.startsWith('3.0') ?? false;
+export const oas3_0 = (document) => matchesMinor(document, 0);
 /** Matches OpenAPI 3.1.x specifically. */
-export const oas3_1 = (document) => openapiVersion(document)?.startsWith('3.1') ?? false;
+export const oas3_1 = (document) => matchesMinor(document, 1);
 /** Matches OpenAPI 3.2.x specifically. */
-export const oas3_2 = (document) => openapiVersion(document)?.startsWith('3.2') ?? false;
+export const oas3_2 = (document) => matchesMinor(document, 2);
 /** OpenAPI format detectors keyed by Loupe-compatible names. */
 export const oasFormats = {
     oas2,

package/dist/rules/openapi/functions/example-validation.d.ts

@@ -1,5 +1,18 @@
 import type { RulesetFunction } from '../../../core/index.js';
-/** Validates a schema object's inline `example` against the schema itself. */
+/** Options selecting the OpenAPI major version an example rule runs against. */
+export type IOasExampleOptions = {
+    /** 2 for OpenAPI 2.0 (Swagger), 3 for OpenAPI 3.x. Defaults to 3. */
+    oasVersion?: number;
+};
+/** Validates a schema object's inline `example` and `default` against the schema itself. */
 export declare const oasSchemaExample: RulesetFunction;
-/** Validates media type / parameter `example` and `examples` against the schema. */
-export declare const oasMediaExample: RulesetFunction;
+/**
+ * Validates a Media Type / Response / Parameter object's examples against its
+ * `schema`. Version-split because OpenAPI 2.0 and 3.x model examples differently:
+ * - OAS3: a singular `example` value plus an `examples` map of Example Objects,
+ *   each of which carries the value under `value`.
+ * - OAS2: `examples` is a MIME-type → value map (`{ 'application/json': value }`),
+ *   with no Example Objects and no singular `example` on the media object — so the
+ *   3.x logic validated nothing at all for a real 2.0 document.
+ */
+export declare const oasMediaExample: RulesetFunction<unknown, IOasExampleOptions>;

package/dist/rules/openapi/functions/example-validation.js

@@ -7,59 +7,103 @@ import { isObject } from './helpers.js';
 // so it is also CSP/edge-runtime safe. Returns undefined for a non-object or a
 // schema the validator can't build (mirrors the old skip-on-compile-failure
 // behavior).
+//
+// Formats are asserted (`formats: 'all'`) to match Spectral, whose example rules
+// run ajv with `ajv-formats` enabled — otherwise a format-violating example (a
+// bad `email`/`date`/`uuid`) would slip through. This mirrors the core `schema`
+// built-in's option exactly; `@amritk/runtime-validators` treats the OAS-specific
+// numeric/binary formats (`int32`/`int64`/`float`/`byte`/`binary`) as non-failing.
 const buildValidator = (schema) => {
     if (!isObject(schema))
         return undefined;
+    let validator;
     try {
-        return validate(schema);
+        validator = validate(schema, { formats: 'all' });
     }
     catch {
         return undefined;
     }
+    // A schema can carry a `$ref` the runtime validator cannot resolve (an external
+    // or cyclic ref left behind after `$ref` inlining), which throws at *run* time
+    // rather than build time. Treat that as "cannot validate — skip" (returning a
+    // valid result) so an unresolvable example schema never crashes the whole lint.
+    return (input) => {
+        try {
+            return validator(input);
+        }
+        catch {
+            return true;
+        }
+    };
 };
 const buildValidatorOrNull = (schema) => buildValidator(schema) ?? null;
 // Keyed by the Schema Object node; `oasSchemaExample` validates a schema's own
-// `example` against the schema minus its `example`/`examples` keywords.
+// `example`/`default` against the schema minus its `example`/`examples` keywords.
 const schemaExampleResults = new WeakMap();
-// Keyed by the Media Type Object node; `oasMediaExample` validates the media's
-// `example`/`examples` against the media's `schema`. The node (not the schema) is
-// the cache key because two media objects can share a `schema` but carry different
-// examples.
+// Keyed by the Media Type / Response Object node; `oasMediaExample` validates the
+// object's example(s) against its `schema`. The node (not the schema) is the cache
+// key because two media objects can share a `schema` but carry different examples.
 const mediaExampleResults = new WeakMap();
 const withPath = (findings, path) => {
     if (findings.length === 0)
         return [];
     return findings.map((finding) => ({ message: finding.message, path: [...path, ...finding.suffix] }));
 };
-/** Validates a schema object's inline `example` against the schema itself. */
+// A schema node reached via `$..[?(...)]` might be a `properties`/`patternProperties`
+// *map* whose keys happen to look like schema keywords (e.g. a property literally
+// named `type`). Those maps are not Schema Objects, so we never validate them.
+const isPropertiesMap = (path) => {
+    const tail = path[path.length - 1];
+    return tail === 'properties' || tail === 'patternProperties';
+};
+/** Validates a schema object's inline `example` and `default` against the schema itself. */
 export const oasSchemaExample = (schema, _options, context) => {
-    if (!isObject(schema) || schema['example'] === undefined)
+    if (!isObject(schema))
+        return [];
+    if (schema['example'] === undefined && schema['default'] === undefined)
+        return [];
+    if (isPropertiesMap(context.path))
         return [];
     let findings = schemaExampleResults.get(schema);
     if (findings === undefined) {
         findings = [];
+        // `example`/`examples` are annotations, not constraints, so drop them before
+        // building the validator; `default` stays (it is not a validation keyword).
         const { example, examples, ...rest } = schema;
         void example;
         void examples;
         const check = buildValidatorOrNull(rest);
         if (check) {
-            const result = check(schema['example']);
-            if (result !== true) {
-                for (const error of result.errors)
-                    findings.push({ message: `"example" ${error.message}`.trim(), suffix: ['example'] });
+            for (const field of ['example', 'default']) {
+                if (schema[field] === undefined)
+                    continue;
+                const result = check(schema[field]);
+                if (result !== true) {
+                    for (const error of result.errors)
+                        findings.push({ message: `"${field}" ${error.message}`.trim(), suffix: [field] });
+                }
             }
         }
         schemaExampleResults.set(schema, findings);
     }
     return withPath(findings, context.path);
 };
-/** Validates media type / parameter `example` and `examples` against the schema. */
-export const oasMediaExample = (media, _options, context) => {
+/**
+ * Validates a Media Type / Response / Parameter object's examples against its
+ * `schema`. Version-split because OpenAPI 2.0 and 3.x model examples differently:
+ * - OAS3: a singular `example` value plus an `examples` map of Example Objects,
+ *   each of which carries the value under `value`.
+ * - OAS2: `examples` is a MIME-type → value map (`{ 'application/json': value }`),
+ *   with no Example Objects and no singular `example` on the media object — so the
+ *   3.x logic validated nothing at all for a real 2.0 document.
+ */
+export const oasMediaExample = (media, options, context) => {
     if (!isObject(media) || !isObject(media['schema']))
         return [];
-    // Skip building a validator when there is no example to check (most media
-    // objects in a large spec have a schema but no example).
-    const hasExample = media['example'] !== undefined || isObject(media['examples']);
+    const oasVersion = options?.oasVersion ?? 3;
+    // Skip building a validator when there is nothing to check — most media objects
+    // in a large spec have a schema but no example. (OAS2 only has the map form.)
+    const hasExample = (oasVersion !== 2 && media['example'] !== undefined) || isObject(media['examples']);
     if (!hasExample)
         return [];
     let findings = mediaExampleResults.get(media);
@@ -67,31 +111,50 @@ export const oasMediaExample = (media, _options, context) => {
         findings = [];
         const check = buildValidatorOrNull(media['schema']);
         if (check) {
-            if (media['example'] !== undefined) {
-                const result = check(media['example']);
-                if (result !== true) {
-                    for (const error of result.errors)
-                        findings.push({ message: `"example" ${error.message}`.trim(), suffix: ['example'] });
-                }
+            if (oasVersion === 2)
+                collectOas2(media, check, findings);
+            else
+                collectOas3(media, check, findings);
+        }
+        mediaExampleResults.set(media, findings);
+    }
+    return withPath(findings, context.path);
+};
+/** OAS2: validate each `examples[mimeType]` value against the sibling `schema`. */
+const collectOas2 = (media, check, findings) => {
+    const examples = isObject(media['examples']) ? media['examples'] : undefined;
+    if (!examples)
+        return;
+    for (const [mimeType, value] of Object.entries(examples)) {
+        const result = check(value);
+        if (result !== true) {
+            for (const error of result.errors) {
+                findings.push({ message: `Example "${mimeType}" ${error.message}`.trim(), suffix: ['examples', mimeType] });
             }
-            const examples = isObject(media['examples']) ? media['examples'] : undefined;
-            if (examples) {
-                for (const [name, example] of Object.entries(examples)) {
-                    if (isObject(example) && example['value'] !== undefined) {
-                        const result = check(example['value']);
-                        if (result !== true) {
-                            for (const error of result.errors) {
-                                findings.push({
-                                    message: `Example "${name}" ${error.message}`.trim(),
-                                    suffix: ['examples', name, 'value'],
-                                });
-                            }
-                        }
-                    }
+        }
+    }
+};
+/** OAS3: validate the singular `example` and each `examples[name].value` against the `schema`. */
+const collectOas3 = (media, check, findings) => {
+    if (media['example'] !== undefined) {
+        const result = check(media['example']);
+        if (result !== true) {
+            for (const error of result.errors)
+                findings.push({ message: `"example" ${error.message}`.trim(), suffix: ['example'] });
+        }
+    }
+    const examples = isObject(media['examples']) ? media['examples'] : undefined;
+    if (!examples)
+        return;
+    for (const [name, example] of Object.entries(examples)) {
+        // An external-value example is fetched elsewhere, so there is nothing inline to check.
+        if (isObject(example) && example['value'] !== undefined) {
+            const result = check(example['value']);
+            if (result !== true) {
+                for (const error of result.errors) {
+                    findings.push({ message: `Example "${name}" ${error.message}`.trim(), suffix: ['examples', name, 'value'] });
                 }
             }
         }
-        mediaExampleResults.set(media, findings);
     }
-    return withPath(findings, context.path);
 };

package/dist/rules/openapi/functions/helpers.d.ts

@@ -1,3 +1,4 @@
 /** True for a non-null, non-array object (an OpenAPI "object" value). */
 export declare const isObject: (value: unknown) => value is Record<string, unknown>;
 export declare const HTTP_METHODS: Set<string>;
+export declare const OPERATION_METHODS: Set<string>;

package/dist/rules/openapi/functions/helpers.js

@@ -3,3 +3,8 @@ export const isObject = (value) => typeof value === 'object' && value !== null &
 // The eight standard HTTP methods that have a dedicated fixed field on the Path
 // Item Object. Shared by the rules that iterate a path item's operations.
 export const HTTP_METHODS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+// OpenAPI 3.2 promoted `query` to a fixed Path Item Object operation field, so the
+// rules that walk a path item's operations must consider it too. Including it is
+// harmless on older versions, which never carry a `query` operation, so the same
+// set works across every OpenAPI version.
+export const OPERATION_METHODS = new Set([...HTTP_METHODS, 'query']);

package/dist/rules/openapi/functions/index.d.ts

@@ -1,9 +1,11 @@
 import type { FunctionRegistry } from '../../../core/index.js';
-export { oasMediaExample, oasSchemaExample } from './example-validation.js';
+export { type IOasExampleOptions, oasMediaExample, oasSchemaExample } from './example-validation.js';
 export { oasAdditionalOperations } from './oas-additional-operations.js';
 export { oasDiscriminator } from './oas-discriminator.js';
+export { oasExampleExternalValue } from './oas-example-external-value.js';
 export { oasExampleValue } from './oas-example-value.js';
 export { oasMutuallyExclusive } from './oas-mutually-exclusive.js';
+export { oasNoNullable } from './oas-no-nullable.js';
 export { oasOpFormDataConsumeCheck } from './oas-op-form-data-consume-check.js';
 export { oasOpIdUnique } from './oas-op-id-unique.js';
 export { oasOpParams } from './oas-op-params.js';