@amritk/lint 0.1.0 → 0.2.0

package/README.md

@@ -19,7 +19,9 @@
 
 `@amritk/lint` lints **any** JSON or YAML document against a ruleset you define. A rule matches nodes with a **JSONPath** (`given`) and runs a **function** (`then`) over each match — structural validation against a **JSON Schema**, style checks (`casing`, `pattern`, `alphabetical`, `length`, …), or your own custom function. Every finding carries an exact `line:column` range, because the parser keeps source positions on every node.
 
-It is **format-agnostic**: the engine ships no built-in ruleset and knows nothing about OpenAPI or any other schema — you bring the rules. This is JSON/YAML style-guide linting with JSON Schema and custom rules, and nothing else.
+It is **format-agnostic**: the core engine ships no built-in ruleset and knows nothing about OpenAPI or any other schema — you bring the rules. This is JSON/YAML style-guide linting with JSON Schema and custom rules at its core.
+
+For OpenAPI specifically, the `@amritk/lint/rules/openapi` subpath ships a ready-made preset on top of that engine — see [OpenAPI ruleset](#openapi-ruleset) below.
 
 The CLI lives in the [`mjst`](../cli) binary as `mjst lint`; this package is the programmatic library behind it.
 
@@ -181,6 +183,37 @@ The engine internals (`createDocument`, `lint`, `query`, `validateRuleset`, `par
 
 ---
 
+## OpenAPI ruleset
+
+The core package is format-agnostic, but OpenAPI is common enough to ship a ready-made preset. It lives at the **`@amritk/lint/rules/openapi`** subpath — a self-contained layer on top of the engine that adds **no dependencies** beyond what `@amritk/lint` already uses.
+
+```ts
+import { lint } from '@amritk/lint'
+import { createOpenApiRuleset } from '@amritk/lint/rules/openapi'
+
+// Defaults to `extends: [oas]` (recommended rules only, like `spectral:oas`).
+const ruleset = createOpenApiRuleset()
+const findings = await lint(spec, { ruleset })
+```
+
+`createOpenApiRuleset(definition?, basePath?)` builds a runnable `Ruleset` with the OpenAPI functions and format detectors layered over the built-ins, and with `extends` resolution that understands the `oas` / `loupe:oas` / `spectral:oas` names (the last two accepted so existing Spectral-style rulesets extend unchanged). Enable every rule with `createOpenApiRuleset({ extends: [['oas', 'all']] })`, or pass your own definition to override severities, add rules, or point `extends` at a file/npm package.
+
+| Export | What it does |
+| --- | --- |
+| `createOpenApiRuleset(definition?, basePath?)` | Build a runnable OpenAPI `Ruleset` (functions + formats + `extends` resolution). |
+| `resolveOpenApiRuleset(name, basePath?)` | Resolve an `extends` reference, including the `oas` / `loupe:oas` / `spectral:oas` names. |
+| `oas` | The built-in OpenAPI ruleset definition. |
+| `oasFunctions` / `allFunctions` | The OpenAPI-specific functions; `allFunctions` = built-ins + OpenAPI. |
+| `oasFormats` | OpenAPI version detectors (`oas2`, `oas3`, `oas3.0`, `oas3.1`, `oas3.2`). |
+| `oasFixers` | Auto-fixers for the mechanically-repairable OpenAPI rules (pass to `fixDocument`). |
+| `loadOasSchema(version)` | Lazily load one OpenAPI version's official structural meta-schema (`'2.0'` / `'3.0'` / `'3.1'` / `'3.2'`), vendored as raw `.json` from `spec.openapis.org` (3.0/3.1/3.2 verbatim; 2.0 with its external draft-04 metaschema refs inlined). See [`schemas/README.md`](./src/rules/openapi/schemas/README.md). |
+
+The structural rules validate against the **official `spec.openapis.org` meta-schemas, vendored as raw `.json`** ([`schemas/`](./src/rules/openapi/schemas/)). 3.0/3.1/3.2 are byte-for-byte verbatim; only 2.0 differs (its external draft-04 metaschema refs are inlined, since the offline interpreter never fetches remote refs). OpenAPI 3.1/3.2 express Schema Objects as JSON Schema 2020-12 via a local `$dynamicRef`/`$dynamicAnchor`, which `@amritk/runtime-validators` resolves natively — so the whole document envelope is validated against the official schema with no bundling or dialect engine, while Schema Object internals stay permissive.
+
+`$ref` resolution stays the caller's job: the preset doesn't pull in a resolver, so for rules that need the dereferenced document (`resolved: true`) pass a `resolve` function to the core `lintWithResult` (for example wrapping [`@amritk/resolve-refs`](../resolve-refs)). The `mjst lint` CLI already wires one up.
+
+---
+
 ## License
 
 MIT

package/dist/rules/openapi/fixers.d.ts

@@ -0,0 +1,7 @@
+import type { FixerRegistry } from '../../fix/index.js';
+/**
+ * Auto-fixers for the mechanically-repairable OpenAPI rules, keyed by rule
+ * code. Pass these to `@amritk/lint`'s `fixDocument` (as its `fixers`), or wrap
+ * them with `createFixPlugin` for a lower-level plugin.
+ */
+export declare const oasFixers: FixerRegistry;

package/dist/rules/openapi/fixers.js

@@ -0,0 +1,189 @@
+/** Reads the value at `path` in the parsed document, or `undefined` if absent. */
+const getAtPath = (data, path) => {
+    let current = data;
+    for (const segment of path) {
+        if (current == null || typeof current !== 'object')
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+};
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value);
+const stripTrailingSlash = (value) => value.replace(/\/+$/, '');
+/**
+ * `oas2-host-trailing-slash` / `oas3-server-trailing-slash`: drop the trailing
+ * slash from a string value (host or server URL).
+ */
+const trailingSlashValue = {
+    safe: true,
+    fix: ({ diagnostic, data }) => {
+        const value = getAtPath(data, diagnostic.path);
+        if (typeof value !== 'string')
+            return undefined;
+        const stripped = stripTrailingSlash(value);
+        if (stripped === value || stripped === '')
+            return undefined;
+        return { op: 'setValue', path: diagnostic.path, value: stripped };
+    },
+};
+/** `path-keys-no-trailing-slash`: rename a `paths` key to drop its trailing slash. */
+const pathKeyTrailingSlash = {
+    safe: true,
+    fix: ({ diagnostic }) => {
+        const key = diagnostic.path[diagnostic.path.length - 1];
+        if (typeof key !== 'string')
+            return undefined;
+        const stripped = stripTrailingSlash(key);
+        if (stripped === key || stripped === '')
+            return undefined;
+        return { op: 'renameProperty', path: diagnostic.path, newKey: stripped };
+    },
+};
+/** `no-$ref-siblings`: delete the sibling key that sits next to a `$ref`. */
+const refSibling = {
+    safe: true,
+    fix: ({ diagnostic }) => {
+        if (diagnostic.path.length === 0)
+            return undefined;
+        return { op: 'removeProperty', path: diagnostic.path };
+    },
+};
+/** `duplicated-entry-in-enum`: remove the later copies of each repeated enum value. */
+const duplicatedEnum = {
+    safe: true,
+    fix: ({ diagnostic, data }) => {
+        const array = getAtPath(data, diagnostic.path);
+        if (!Array.isArray(array))
+            return undefined;
+        const seen = new Set();
+        const duplicates = [];
+        array.forEach((item, index) => {
+            const key = JSON.stringify(item);
+            if (seen.has(key))
+                duplicates.push(index);
+            else
+                seen.add(key);
+        });
+        if (duplicates.length === 0)
+            return undefined;
+        return { op: 'removeItems', path: diagnostic.path, indices: duplicates };
+    },
+};
+/** `openapi-tags-alphabetical`: reorder the top-level `tags` array by `name`. */
+const tagsAlphabetical = {
+    safe: true,
+    fix: ({ diagnostic, data }) => {
+        // Findings point at the out-of-order item; the array is its parent.
+        const arrayPath = diagnostic.path.slice(0, -1);
+        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])));
+        if (order.every((value, index) => value === index))
+            return undefined;
+        return { op: 'reorderArray', path: arrayPath, order };
+    },
+};
+/** `path-not-include-query`: drop the `?query` portion from a `paths` key. */
+const pathKeyQueryString = {
+    safe: true,
+    fix: ({ diagnostic, data }) => {
+        const key = diagnostic.path[diagnostic.path.length - 1];
+        if (typeof key !== 'string')
+            return undefined;
+        const stripped = key.replace(/\?.*$/, '');
+        if (stripped === key || stripped === '')
+            return undefined;
+        // Renaming onto an existing path would collide and silently drop a path, so skip.
+        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 };
+    },
+};
+/** `openapi-tags-uniqueness`: remove the later copies of each repeated tag name. */
+const tagsUnique = {
+    safe: true,
+    fix: ({ diagnostic, data }) => {
+        // Findings point at `tags[index].name`, so the array sits two segments up.
+        const arrayPath = diagnostic.path.slice(0, -2);
+        const array = getAtPath(data, arrayPath);
+        if (!Array.isArray(array))
+            return undefined;
+        const seen = new Set();
+        const duplicates = [];
+        array.forEach((tag, index) => {
+            const name = isObject(tag) ? tag['name'] : undefined;
+            if (typeof name !== 'string')
+                return;
+            if (seen.has(name))
+                duplicates.push(index);
+            else
+                seen.add(name);
+        });
+        if (duplicates.length === 0)
+            return undefined;
+        return { op: 'removeItems', path: arrayPath, indices: duplicates };
+    },
+};
+/**
+ * `oas3-unused-component` / `oas2-unused-definition`: delete the unreferenced
+ * component. Marked unsafe because a component can be referenced from another
+ * document or resolved dynamically, so removing it may not be semantics-preserving
+ * — it only applies under `--fix-unsafe`.
+ */
+const unusedComponent = {
+    safe: false,
+    fix: ({ diagnostic }) => {
+        if (diagnostic.path.length === 0)
+            return undefined;
+        return { op: 'removeProperty', path: diagnostic.path };
+    },
+};
+/**
+ * `oas3_1-no-nullable`: migrate the 3.0-era `nullable` keyword to its OpenAPI
+ * 3.1 (JSON Schema 2020-12) equivalent. `nullable: false` is the schema default,
+ * so it is simply dropped; `nullable: true` folds a `"null"` member into the
+ * sibling `type` before the keyword is removed. Marked unsafe because it rewrites
+ * the schema's `type`, so it only applies under `--fix-unsafe`.
+ */
+const noNullable = {
+    safe: false,
+    fix: ({ diagnostic, data }) => {
+        const value = getAtPath(data, diagnostic.path);
+        const remove = { op: 'removeProperty', path: diagnostic.path };
+        // `nullable: false` (or any non-true value) is the default — drop the keyword.
+        if (value !== true)
+            return remove;
+        const typePath = [...diagnostic.path.slice(0, -1), 'type'];
+        const type = getAtPath(data, typePath);
+        if (typeof type === 'string' && type !== 'null') {
+            return [{ op: 'setValue', path: typePath, value: [type, 'null'] }, remove];
+        }
+        if (Array.isArray(type) && !type.includes('null')) {
+            return [{ op: 'insertItem', path: typePath, value: 'null' }, remove];
+        }
+        // No type to widen (the schema already permits any value, null included) or
+        // `null` is already allowed — removing the keyword is enough.
+        return remove;
+    },
+};
+/**
+ * Auto-fixers for the mechanically-repairable OpenAPI rules, keyed by rule
+ * code. Pass these to `@amritk/lint`'s `fixDocument` (as its `fixers`), or wrap
+ * them with `createFixPlugin` for a lower-level plugin.
+ */
+export const oasFixers = {
+    'oas2-host-trailing-slash': trailingSlashValue,
+    'oas3-server-trailing-slash': trailingSlashValue,
+    'path-keys-no-trailing-slash': pathKeyTrailingSlash,
+    'path-not-include-query': pathKeyQueryString,
+    'no-$ref-siblings': refSibling,
+    'duplicated-entry-in-enum': duplicatedEnum,
+    'openapi-tags-alphabetical': tagsAlphabetical,
+    'openapi-tags-uniqueness': tagsUnique,
+    'oas3-unused-component': unusedComponent,
+    'oas2-unused-definition': unusedComponent,
+    'oas3_1-no-nullable': noNullable,
+};

package/dist/rules/openapi/formats.d.ts

@@ -0,0 +1,13 @@
+import type { Format } from '../../core/index.js';
+/** Matches OpenAPI/Swagger 2.0 (`swagger: "2.0"`). */
+export declare const oas2: Format;
+/** Matches any OpenAPI 3.x (`openapi: 3.*`). */
+export declare const oas3: Format;
+/** Matches OpenAPI 3.0.x specifically. */
+export declare const oas3_0: Format;
+/** Matches OpenAPI 3.1.x specifically. */
+export declare const oas3_1: Format;
+/** Matches OpenAPI 3.2.x specifically. */
+export declare const oas3_2: Format;
+/** OpenAPI format detectors keyed by Loupe-compatible names. */
+export declare const oasFormats: Record<string, Format>;

package/dist/rules/openapi/formats.js

@@ -0,0 +1,23 @@
+const isObject = (value) => typeof value === 'object' && value !== null;
+const openapiVersion = (document) => isObject(document) && typeof document['openapi'] === 'string' ? document['openapi'] : undefined;
+/** 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;
+/** Matches OpenAPI 3.0.x specifically. */
+export const oas3_0 = (document) => openapiVersion(document)?.startsWith('3.0') ?? false;
+/** Matches OpenAPI 3.1.x specifically. */
+export const oas3_1 = (document) => openapiVersion(document)?.startsWith('3.1') ?? false;
+/** Matches OpenAPI 3.2.x specifically. */
+export const oas3_2 = (document) => openapiVersion(document)?.startsWith('3.2') ?? false;
+/** OpenAPI format detectors keyed by Loupe-compatible names. */
+export const oasFormats = {
+    oas2,
+    oas3,
+    'oas3.0': oas3_0,
+    oas3_0,
+    'oas3.1': oas3_1,
+    oas3_1,
+    'oas3.2': oas3_2,
+    oas3_2,
+};

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

@@ -0,0 +1,5 @@
+import type { RulesetFunction } from '../../../core/index.js';
+/** Validates a schema object's inline `example` against the schema itself. */
+export declare const oasSchemaExample: RulesetFunction;
+/** Validates media type / parameter `example` and `examples` against the schema. */
+export declare const oasMediaExample: RulesetFunction;

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

@@ -0,0 +1,97 @@
+import { validate } from '@amritk/runtime-validators';
+import { isObject } from './helpers.js';
+// The example schemas come from the *linted document*, so they are only known at
+// runtime. `@amritk/runtime-validators` interprets a schema directly — no
+// `ajv.compile` (whose codegen dominated lint time on large specs, recompiling
+// `$ref`-duplicated schemas tens of thousands of times) and no `new Function`,
+// 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).
+const buildValidator = (schema) => {
+    if (!isObject(schema))
+        return undefined;
+    try {
+        return validate(schema);
+    }
+    catch {
+        return undefined;
+    }
+};
+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.
+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.
+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. */
+export const oasSchemaExample = (schema, _options, context) => {
+    if (!isObject(schema) || schema['example'] === undefined)
+        return [];
+    let findings = schemaExampleResults.get(schema);
+    if (findings === undefined) {
+        findings = [];
+        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'] });
+            }
+        }
+        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) => {
+    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']);
+    if (!hasExample)
+        return [];
+    let findings = mediaExampleResults.get(media);
+    if (findings === undefined) {
+        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'] });
+                }
+            }
+            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'],
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        mediaExampleResults.set(media, findings);
+    }
+    return withPath(findings, context.path);
+};

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

@@ -0,0 +1,3 @@
+/** 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>;

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

@@ -0,0 +1,5 @@
+/** True for a non-null, non-array object (an OpenAPI "object" value). */
+export const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// 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']);

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

@@ -0,0 +1,24 @@
+import type { FunctionRegistry } from '../../../core/index.js';
+export { oasMediaExample, oasSchemaExample } from './example-validation.js';
+export { oasAdditionalOperations } from './oas-additional-operations.js';
+export { oasDiscriminator } from './oas-discriminator.js';
+export { oasExampleValue } from './oas-example-value.js';
+export { oasMutuallyExclusive } from './oas-mutually-exclusive.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';
+export { oasOpSecurityDefined } from './oas-op-security-defined.js';
+export { oasOpSuccessResponse } from './oas-op-success-response.js';
+export { oasPathParam } from './oas-path-param.js';
+export { type IOasSchemaOptions, oasSchema } from './oas-schema.js';
+export { oasSchemaExampleDeprecated } from './oas-schema-example-deprecated.js';
+export { oasServerNameUnique } from './oas-server-name-unique.js';
+export { oasServerVariables } from './oas-server-variables.js';
+export { oasTagDefined } from './oas-tag-defined.js';
+export { oasTagKind } from './oas-tag-kind.js';
+export { oasTagParentDefined } from './oas-tag-parent-defined.js';
+export { oasTagsUnique } from './oas-tags-unique.js';
+export { oasUnusedComponent } from './oas-unused-component.js';
+export { refSiblings } from './ref-siblings.js';
+/** The OpenAPI-specific custom functions, keyed by name for ruleset `then` references. */
+export declare const oasFunctions: FunctionRegistry;

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

@@ -0,0 +1,67 @@
+import { oasMediaExample, oasSchemaExample } from './example-validation.js';
+import { oasAdditionalOperations } from './oas-additional-operations.js';
+import { oasDiscriminator } from './oas-discriminator.js';
+import { oasExampleValue } from './oas-example-value.js';
+import { oasMutuallyExclusive } from './oas-mutually-exclusive.js';
+import { oasOpFormDataConsumeCheck } from './oas-op-form-data-consume-check.js';
+import { oasOpIdUnique } from './oas-op-id-unique.js';
+import { oasOpParams } from './oas-op-params.js';
+import { oasOpSecurityDefined } from './oas-op-security-defined.js';
+import { oasOpSuccessResponse } from './oas-op-success-response.js';
+import { oasPathParam } from './oas-path-param.js';
+import { oasSchema } from './oas-schema.js';
+import { oasSchemaExampleDeprecated } from './oas-schema-example-deprecated.js';
+import { oasServerNameUnique } from './oas-server-name-unique.js';
+import { oasServerVariables } from './oas-server-variables.js';
+import { oasTagDefined } from './oas-tag-defined.js';
+import { oasTagKind } from './oas-tag-kind.js';
+import { oasTagParentDefined } from './oas-tag-parent-defined.js';
+import { oasTagsUnique } from './oas-tags-unique.js';
+import { oasUnusedComponent } from './oas-unused-component.js';
+import { refSiblings } from './ref-siblings.js';
+export { oasMediaExample, oasSchemaExample } from './example-validation.js';
+export { oasAdditionalOperations } from './oas-additional-operations.js';
+export { oasDiscriminator } from './oas-discriminator.js';
+export { oasExampleValue } from './oas-example-value.js';
+export { oasMutuallyExclusive } from './oas-mutually-exclusive.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';
+export { oasOpSecurityDefined } from './oas-op-security-defined.js';
+export { oasOpSuccessResponse } from './oas-op-success-response.js';
+export { oasPathParam } from './oas-path-param.js';
+export { oasSchema } from './oas-schema.js';
+export { oasSchemaExampleDeprecated } from './oas-schema-example-deprecated.js';
+export { oasServerNameUnique } from './oas-server-name-unique.js';
+export { oasServerVariables } from './oas-server-variables.js';
+export { oasTagDefined } from './oas-tag-defined.js';
+export { oasTagKind } from './oas-tag-kind.js';
+export { oasTagParentDefined } from './oas-tag-parent-defined.js';
+export { oasTagsUnique } from './oas-tags-unique.js';
+export { oasUnusedComponent } from './oas-unused-component.js';
+export { refSiblings } from './ref-siblings.js';
+/** The OpenAPI-specific custom functions, keyed by name for ruleset `then` references. */
+export const oasFunctions = {
+    refSiblings,
+    oasOpSuccessResponse,
+    oasTagDefined,
+    oasOpIdUnique,
+    oasPathParam,
+    oasOpParams,
+    oasTagsUnique,
+    oasOpSecurityDefined: oasOpSecurityDefined,
+    oasOpFormDataConsumeCheck,
+    oasDiscriminator,
+    oasServerVariables,
+    oasSchemaExample,
+    oasMediaExample,
+    oasUnusedComponent,
+    oasMutuallyExclusive: oasMutuallyExclusive,
+    oasSchema: oasSchema,
+    oasAdditionalOperations,
+    oasServerNameUnique,
+    oasTagParentDefined,
+    oasSchemaExampleDeprecated,
+    oasTagKind,
+    oasExampleValue,
+};

package/dist/rules/openapi/functions/oas-additional-operations.d.ts

@@ -0,0 +1,8 @@
+import type { RulesetFunction } from '../../../core/index.js';
+/**
+ * Flags standard HTTP methods inside an OpenAPI 3.2 `additionalOperations` map.
+ * The spec reserves that map for methods without a dedicated fixed field, so a
+ * standard method key (sent uppercase, e.g. `POST`) belongs in the lowercase
+ * fixed field (`post`) instead.
+ */
+export declare const oasAdditionalOperations: RulesetFunction;

package/dist/rules/openapi/functions/oas-additional-operations.js

@@ -0,0 +1,25 @@
+import { HTTP_METHODS, isObject } from './helpers.js';
+// HTTP methods that have a dedicated fixed field on the Path Item Object. In
+// OpenAPI 3.2 `query` joined the original eight, and these MUST NOT be redefined
+// inside the new `additionalOperations` map (which is for non-standard methods).
+const FIXED_PATH_ITEM_METHODS = new Set([...HTTP_METHODS, 'query']);
+/**
+ * Flags standard HTTP methods inside an OpenAPI 3.2 `additionalOperations` map.
+ * The spec reserves that map for methods without a dedicated fixed field, so a
+ * standard method key (sent uppercase, e.g. `POST`) belongs in the lowercase
+ * fixed field (`post`) instead.
+ */
+export const oasAdditionalOperations = (input, _options, context) => {
+    if (!isObject(input))
+        return [];
+    const results = [];
+    for (const method of Object.keys(input)) {
+        if (FIXED_PATH_ITEM_METHODS.has(method.toLowerCase())) {
+            results.push({
+                message: `"additionalOperations" must not redefine the standard method "${method}"; use the "${method.toLowerCase()}" field instead`,
+                path: [...context.path, method],
+            });
+        }
+    }
+    return results;
+};

package/dist/rules/openapi/functions/oas-discriminator.d.ts

@@ -0,0 +1,3 @@
+import type { RulesetFunction } from '../../../core/index.js';
+/** Validates a v2 discriminator references a required property. */
+export declare const oasDiscriminator: RulesetFunction;

package/dist/rules/openapi/functions/oas-discriminator.js

@@ -0,0 +1,23 @@
+import { isObject } from './helpers.js';
+/** Validates a v2 discriminator references a required property. */
+export const oasDiscriminator = (schema, _options, context) => {
+    if (!isObject(schema) || typeof schema['discriminator'] !== 'string')
+        return [];
+    const property = schema['discriminator'];
+    const required = Array.isArray(schema['required']) ? schema['required'] : [];
+    const properties = isObject(schema['properties']) ? schema['properties'] : {};
+    const results = [];
+    if (!(property in properties)) {
+        results.push({
+            message: `Discriminator "${property}" must be defined in properties`,
+            path: [...context.path, 'discriminator'],
+        });
+    }
+    if (!required.includes(property)) {
+        results.push({
+            message: `Discriminator "${property}" must be a required property`,
+            path: [...context.path, 'discriminator'],
+        });
+    }
+    return results;
+};

package/dist/rules/openapi/functions/oas-example-value.d.ts

@@ -0,0 +1,3 @@
+import type { RulesetFunction } from '../../../core/index.js';
+/** Flags forbidden field combinations on an OpenAPI 3.2 Example Object. */
+export declare const oasExampleValue: RulesetFunction;

package/dist/rules/openapi/functions/oas-example-value.js

@@ -0,0 +1,31 @@
+import { isObject } from './helpers.js';
+// OpenAPI 3.2 Example Object exclusivity (MUST-level, per the spec's field
+// table). The `value`/`externalValue` pair is intentionally omitted here — the
+// 3.x-wide `oas3-examples-value-or-externalValue` rule already covers it, so we
+// only police the constraints introduced with the new `dataValue` /
+// `serializedValue` fields to avoid double-reporting.
+const EXAMPLE_EXCLUSIONS = [
+    // dataValue MUST NOT accompany value.
+    { field: 'dataValue', conflicts: ['value'] },
+    // serializedValue MUST NOT accompany value or externalValue.
+    { field: 'serializedValue', conflicts: ['value', 'externalValue'] },
+];
+/** Flags forbidden field combinations on an OpenAPI 3.2 Example Object. */
+export const oasExampleValue = (example, _options, context) => {
+    if (!isObject(example))
+        return [];
+    const results = [];
+    for (const { field, conflicts } of EXAMPLE_EXCLUSIONS) {
+        if (example[field] === undefined)
+            continue;
+        for (const other of conflicts) {
+            if (example[other] !== undefined) {
+                results.push({
+                    message: `"${field}" must not be used together with "${other}"`,
+                    path: [...context.path, other],
+                });
+            }
+        }
+    }
+    return results;
+};

package/dist/rules/openapi/functions/oas-mutually-exclusive.d.ts

@@ -0,0 +1,10 @@
+import type { RulesetFunction } from '../../../core/index.js';
+/**
+ * Flags objects that carry more than one of a set of mutually exclusive
+ * properties. OpenAPI 3.1's License Object, for example, defines `identifier`
+ * (SPDX) as "mutually exclusive of the url field" — neither, or exactly one, is
+ * allowed, but not both.
+ */
+export declare const oasMutuallyExclusive: RulesetFunction<Record<string, unknown>, {
+    properties: string[];
+}>;

package/dist/rules/openapi/functions/oas-mutually-exclusive.js

@@ -0,0 +1,20 @@
+import { isObject } from './helpers.js';
+/**
+ * Flags objects that carry more than one of a set of mutually exclusive
+ * properties. OpenAPI 3.1's License Object, for example, defines `identifier`
+ * (SPDX) as "mutually exclusive of the url field" — neither, or exactly one, is
+ * allowed, but not both.
+ */
+export const oasMutuallyExclusive = (input, options, context) => {
+    if (!isObject(input))
+        return [];
+    const present = (options?.properties ?? []).filter((property) => input[property] !== undefined);
+    if (present.length <= 1)
+        return [];
+    // The first present property is the "anchor"; flag every later one as the conflict.
+    const [anchor, ...conflicts] = present;
+    return conflicts.map((property) => ({
+        message: `"${property}" must not be used together with "${anchor}" (mutually exclusive)`,
+        path: [...context.path, property],
+    }));
+};

package/dist/rules/openapi/functions/oas-op-form-data-consume-check.d.ts

@@ -0,0 +1,3 @@
+import type { RulesetFunction } from '../../../core/index.js';
+/** Validates OpenAPI v2 formData operations declare a compatible `consumes`. */
+export declare const oasOpFormDataConsumeCheck: RulesetFunction;