@amritk/lint 0.1.0 → 0.3.0

package/dist/rules/openapi/index.js

@@ -0,0 +1,127 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, resolve as resolvePath } from 'node:path';
+import { createRuleset as createCoreRuleset, } from '../../core/index.js';
+import { builtinFunctions } from '../../functions/index.js';
+import { parseWithPointers } from '../../parsers/index.js';
+import { oasFormats } from './formats.js';
+import { oasFunctions } from './functions/index.js';
+import { oas } from './oas.js';
+export { oasFixers } from './fixers.js';
+export { oas2, oas3, oas3_0, oas3_1, oas3_2, oasFormats } from './formats.js';
+export { oasFunctions } from './functions/index.js';
+export { oas } from './oas.js';
+export { loadOasSchema } from './schemas/index.js';
+/** The built-in `@amritk/lint` functions plus the OpenAPI-specific ones, keyed by name. */
+export const allFunctions = { ...builtinFunctions, ...oasFunctions };
+const require = createRequire(import.meta.url);
+/** The names that resolve to the built-in OpenAPI ruleset (incl. the legacy Spectral alias). */
+const OAS_RULESET_NAMES = new Set(['oas', 'loupe:oas', 'spectral:oas']);
+/** Loads a ruleset definition from a file path by extension (YAML/JSON parsed, JS/CJS/MJS required). */
+const loadRulesetFile = (file) => {
+    if (/\.(ya?ml|json)$/i.test(file)) {
+        return parseWithPointers(readFileSync(file, 'utf8')).data;
+    }
+    const module = require(file);
+    return (module.default ?? module);
+};
+/**
+ * Resolves an `extends` reference to a ruleset definition. Extends the generic
+ * file/package resolution with the OpenAPI preset names:
+ * - `oas` / `loupe:oas` / `spectral:oas` → the built-in {@link oas} ruleset,
+ * - local file paths (relative to `basePath`, or absolute): `.yaml` / `.yml` / `.json` / `.js`,
+ * - npm package specifiers (resolved from `basePath`), including subpaths.
+ */
+export const resolveOpenApiRuleset = (name, basePath = process.cwd()) => {
+    if (OAS_RULESET_NAMES.has(name))
+        return { definition: oas, basePath };
+    if (name.startsWith('.') || isAbsolute(name)) {
+        const file = resolvePath(basePath, name);
+        return { definition: loadRulesetFile(file), basePath: dirname(file) };
+    }
+    let file;
+    try {
+        file = require.resolve(name, { paths: [basePath] });
+    }
+    catch {
+        throw new Error(`Cannot resolve extended ruleset "${name}" from ${basePath}`);
+    }
+    return { definition: loadRulesetFile(file), basePath: dirname(file) };
+};
+/** Loads a single custom function module (`<dir>/<name>.{js,cjs,mjs}` or a bare path). */
+const loadFunctionByName = (basePath, dir, name) => {
+    const baseFile = resolvePath(basePath, dir, name);
+    for (const candidate of [baseFile, `${baseFile}.js`, `${baseFile}.cjs`, `${baseFile}.mjs`]) {
+        try {
+            const resolvedFile = require.resolve(candidate);
+            const module = require(resolvedFile);
+            const fn = module.default ?? module;
+            if (typeof fn !== 'function')
+                throw new Error(`"${name}" did not export a function`);
+            return fn;
+        }
+        catch (error) {
+            if (error.code !== 'MODULE_NOT_FOUND')
+                throw error;
+        }
+    }
+    throw new Error(`Cannot resolve custom function "${name}" from ${resolvePath(basePath, dir)}`);
+};
+/**
+ * Walks a ruleset definition (and its string `extends`) collecting custom
+ * functions declared via `functions` / `functionsDir`, each loaded relative to
+ * the directory of the ruleset that declared it. The built-in `oas` names carry
+ * no custom functions, so they are skipped.
+ */
+const collectCustomFunctions = (definition, basePath, into, seen) => {
+    if (seen.has(definition))
+        return;
+    seen.add(definition);
+    if (definition.extends) {
+        const entries = Array.isArray(definition.extends) ? definition.extends : [definition.extends];
+        for (const entry of entries) {
+            const target = Array.isArray(entry) ? entry[0] : entry;
+            if (typeof target === 'string') {
+                if (OAS_RULESET_NAMES.has(target))
+                    continue;
+                const resolved = resolveOpenApiRuleset(target, basePath);
+                collectCustomFunctions(resolved.definition, resolved.basePath, into, seen);
+            }
+            else {
+                collectCustomFunctions(target, basePath, into, seen);
+            }
+        }
+    }
+    if (Array.isArray(definition.functions)) {
+        const dir = definition.functionsDir ?? 'functions';
+        for (const name of definition.functions)
+            into[name] = loadFunctionByName(basePath, dir, name);
+    }
+};
+/**
+ * Builds a runnable {@link Ruleset} for OpenAPI, layering the built-in and
+ * OpenAPI functions (plus any custom ones the definition declares), the OpenAPI
+ * `formats`, and `extends` resolution that understands the `oas` / `loupe:oas` /
+ * `spectral:oas` names. With no definition it defaults to `extends: [oas]`
+ * (recommended rules only). Feed the result to `@amritk/lint`'s core
+ * `lintWithResult` (with a `$ref` resolver for `resolved: true` rules).
+ */
+export const createOpenApiRuleset = (definition, basePath) => {
+    // With no explicit ruleset, behave like `extends: [oas]` so only `recommended`
+    // rules run by default. A user-supplied ruleset is used as-is (its own rules
+    // run regardless of `recommended`).
+    const resolved = definition ?? { extends: [oas] };
+    // Custom functions referenced by name (YAML/JSON rulesets) are loaded relative
+    // to the declaring ruleset's directory and layered over the built-ins.
+    let functions = allFunctions;
+    const custom = {};
+    collectCustomFunctions(resolved, basePath ?? process.cwd(), custom, new Set());
+    if (Object.keys(custom).length > 0)
+        functions = { ...allFunctions, ...custom };
+    return createCoreRuleset(resolved, {
+        functions,
+        formats: oasFormats,
+        resolve: resolveOpenApiRuleset,
+        ...(basePath !== undefined ? { basePath } : {}),
+    });
+};

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

@@ -0,0 +1,3 @@
+import type { RulesetDefinition } from '../../core/index.js';
+/** Loupe's built-in OpenAPI ruleset (`loupe:oas`). */
+export declare const oas: RulesetDefinition;

package/dist/rules/openapi/oas.js

@@ -0,0 +1,549 @@
+// `query` is a fixed operation field from OpenAPI 3.2 onward. Including it in the
+// operation selectors is harmless on older versions (which never carry a `query`
+// operation) and lets the operation-scoped rules cover 3.2 `query` operations.
+const OPERATIONS = '$.paths[*][get,put,post,delete,options,head,patch,trace,query]';
+const WEBHOOK_OPERATIONS = '$.webhooks[*][get,put,post,delete,options,head,patch,trace,query]';
+const OPERATION_ID_URL_SAFE = "^[A-Za-z0-9-._~:/?#\\[\\]@!\\$&'()*+,;=]*$";
+// Matches every Schema Object that carries an inline `example` or `default` and
+// looks like a schema (it has a JSON Schema keyword), while skipping the
+// `properties`/`patternProperties` *maps* — whose keys can coincidentally be
+// named like schema keywords. A single filter given (rather than a `$..example^`
+// / `$..default^` union) keeps each schema node matched exactly once, so the
+// `oasSchemaExample` finding for a schema is never duplicated.
+const SCHEMA_EXAMPLE_GIVEN = "$..[?(@property !== 'properties' && @property !== 'patternProperties' && @ && (@.example !== void 0 || @.default !== void 0) && (@.type || @.enum || @.format || @.$ref || @.properties || @.items || @.allOf || @.anyOf || @.oneOf))]";
+/** Rules shared across OpenAPI v2 and v3. */
+const sharedRules = {
+    'contact-properties': {
+        description: 'Contact object must have name, url, and email.',
+        given: '$.info.contact',
+        severity: 'warn',
+        recommended: false,
+        then: [
+            { field: 'name', function: 'truthy' },
+            { field: 'url', function: 'truthy' },
+            { field: 'email', function: 'truthy' },
+        ],
+    },
+    'duplicated-entry-in-enum': {
+        description: 'Enum values must not have duplicate entries.',
+        given: '$..enum',
+        severity: 'warn',
+        then: { function: 'schema', functionOptions: { schema: { type: 'array', uniqueItems: true } } },
+    },
+    'info-contact': {
+        description: 'Info object must have a contact object.',
+        given: '$.info',
+        then: { field: 'contact', function: 'truthy' },
+    },
+    'info-description': {
+        description: 'Info object must have a description.',
+        given: '$.info',
+        then: { field: 'description', function: 'truthy' },
+    },
+    'info-license': {
+        description: 'Info object should have a license.',
+        given: '$.info',
+        severity: 'warn',
+        recommended: false,
+        then: { field: 'license', function: 'truthy' },
+    },
+    'license-url': {
+        description: 'License object should have a url.',
+        given: '$.info.license',
+        severity: 'warn',
+        recommended: false,
+        then: { field: 'url', function: 'truthy' },
+    },
+    'no-$ref-siblings': {
+        description: 'Sibling values alongside $ref are ignored.',
+        // OpenAPI 3.1 (JSON Schema 2020-12) permits siblings next to `$ref`, so this
+        // rule is gated to 2.0 / 3.0 — matching `spectral:oas`.
+        formats: ['oas2', 'oas3_0'],
+        given: '$..$ref^',
+        severity: 'error',
+        resolved: false,
+        then: { function: 'refSiblings' },
+    },
+    'no-eval-in-markdown': {
+        description: 'Markdown descriptions must not contain "eval(".',
+        // Spectral scans both `description` and `title` markdown fields.
+        given: ['$..description', '$..title'],
+        then: { function: 'pattern', functionOptions: { notMatch: 'eval\\(' } },
+    },
+    'no-script-tags-in-markdown': {
+        description: 'Markdown descriptions must not contain <script> tags.',
+        given: ['$..description', '$..title'],
+        then: { function: 'pattern', functionOptions: { notMatch: '<script' } },
+    },
+    'openapi-tags': {
+        description: 'Top-level tags should be present and non-empty.',
+        given: '$.tags',
+        severity: 'warn',
+        recommended: false,
+        then: { function: 'length', functionOptions: { min: 1 } },
+    },
+    'openapi-tags-alphabetical': {
+        description: 'Top-level tags should be in alphabetical order.',
+        given: '$.tags',
+        severity: 'warn',
+        recommended: false,
+        then: { function: 'alphabetical', functionOptions: { keyedBy: 'name' } },
+    },
+    'openapi-tags-uniqueness': {
+        description: 'Top-level tag names must be unique.',
+        given: '$.tags',
+        severity: 'error',
+        then: { function: 'oasTagsUnique' },
+    },
+    'operation-description': {
+        description: 'Operation must have a description.',
+        given: OPERATIONS,
+        then: { field: 'description', function: 'truthy' },
+    },
+    'operation-operationId': {
+        description: 'Operation must have an operationId.',
+        given: OPERATIONS,
+        then: { field: 'operationId', function: 'truthy' },
+    },
+    'operation-operationId-unique': {
+        description: 'Every operationId must be unique.',
+        given: '$.paths',
+        severity: 'error',
+        then: { function: 'oasOpIdUnique' },
+    },
+    'operation-operationId-valid-in-url': {
+        description: 'operationId must use URL-safe characters.',
+        given: OPERATIONS,
+        then: { field: 'operationId', function: 'pattern', functionOptions: { match: OPERATION_ID_URL_SAFE } },
+    },
+    'operation-parameters': {
+        description: 'Operation parameters must be unique and non-repeating.',
+        given: '$.paths[*][*].parameters',
+        then: { function: 'oasOpParams' },
+    },
+    'operation-singular-tag': {
+        description: 'Operation should have a single tag.',
+        given: OPERATIONS,
+        severity: 'warn',
+        recommended: false,
+        then: { field: 'tags', function: 'length', functionOptions: { max: 1 } },
+    },
+    'operation-success-response': {
+        description: 'Operation must have at least one 2xx or 3xx response.',
+        given: OPERATIONS,
+        then: { field: 'responses', function: 'oasOpSuccessResponse' },
+    },
+    'operation-tags': {
+        description: 'Operation must have non-empty tags.',
+        given: OPERATIONS,
+        then: { field: 'tags', function: 'truthy' },
+    },
+    'operation-tag-defined': {
+        description: 'Operation tags must be defined in the global tags list.',
+        given: OPERATIONS,
+        then: { function: 'oasTagDefined' },
+    },
+    'path-declarations-must-exist': {
+        description: 'Path parameter declarations must not be empty ({}).',
+        given: '$.paths',
+        then: { field: '@key', function: 'pattern', functionOptions: { notMatch: '{}' } },
+    },
+    'path-keys-no-trailing-slash': {
+        description: 'Path keys should not end with a slash.',
+        given: '$.paths',
+        then: { field: '@key', function: 'pattern', functionOptions: { notMatch: '.+\\/$' } },
+    },
+    'path-not-include-query': {
+        description: 'Path keys should not include query strings.',
+        given: '$.paths',
+        then: { field: '@key', function: 'pattern', functionOptions: { notMatch: '\\?' } },
+    },
+    'path-params': {
+        description: 'Path parameters must be defined and not duplicated.',
+        given: '$.paths',
+        severity: 'error',
+        then: { function: 'oasPathParam' },
+    },
+    'tag-description': {
+        description: 'Tags should have a description.',
+        given: '$.tags[*]',
+        severity: 'warn',
+        recommended: false,
+        then: { field: 'description', function: 'truthy' },
+    },
+    'typed-enum': {
+        description: 'Enum values must respect the specified type.',
+        given: '$..enum^',
+        then: { function: 'typedEnum' },
+    },
+    'array-items': {
+        // Not part of `spectral:oas` — a Loupe extension. `type: array` without
+        // `items` is valid in JSON Schema 2020-12 (OpenAPI 3.1/3.2), so this is gated
+        // to the versions where `items` is genuinely required (2.0 and 3.0.x) to
+        // avoid false positives on valid 3.1+ tuple/unconstrained-array schemas.
+        description: 'Schemas of type array must define items (OpenAPI 2.0 / 3.0 only; Loupe extension).',
+        formats: ['oas2', 'oas3_0'],
+        given: "$..[?(@ && @.type === 'array')]",
+        severity: 'error',
+        then: { field: 'items', function: 'defined' },
+    },
+};
+/** OpenAPI v2.0-only rules. */
+const oas2Rules = {
+    'oas2-anyOf': {
+        description: 'anyOf is not available in OpenAPI v2.0.',
+        formats: ['oas2'],
+        given: '$..anyOf',
+        then: { function: 'falsy' },
+    },
+    'oas2-oneOf': {
+        description: 'oneOf is not available in OpenAPI v2.0.',
+        formats: ['oas2'],
+        given: '$..oneOf',
+        then: { function: 'falsy' },
+    },
+    'oas2-api-host': {
+        description: 'OpenAPI host must be present and non-empty.',
+        formats: ['oas2'],
+        given: '$',
+        then: { field: 'host', function: 'truthy' },
+    },
+    'oas2-api-schemes': {
+        description: 'OpenAPI schemes must be present and non-empty.',
+        formats: ['oas2'],
+        // Target the root and the `schemes` field so a *missing* `schemes` (not just
+        // an empty array) is reported — `given: '$.schemes'` matches nothing when the
+        // key is absent, so the rule never fired for a document with no schemes.
+        given: '$',
+        then: {
+            field: 'schemes',
+            function: 'schema',
+            functionOptions: { schema: { type: 'array', minItems: 1 } },
+        },
+    },
+    'oas2-discriminator': {
+        description: 'Discriminator must reference a required property.',
+        formats: ['oas2'],
+        given: '$.definitions[*]',
+        severity: 'error',
+        then: { function: 'oasDiscriminator' },
+    },
+    'oas2-host-not-example': {
+        description: 'Host should not point to example.com.',
+        formats: ['oas2'],
+        given: '$',
+        severity: 'warn',
+        recommended: false,
+        then: { field: 'host', function: 'pattern', functionOptions: { notMatch: 'example\\.com' } },
+    },
+    'oas2-host-trailing-slash': {
+        description: 'Host should not have a trailing slash.',
+        formats: ['oas2'],
+        given: '$',
+        then: { field: 'host', function: 'pattern', functionOptions: { notMatch: '/$' } },
+    },
+    'oas2-operation-formData-consume-check': {
+        description: 'formData operations must consume form media types.',
+        formats: ['oas2'],
+        given: OPERATIONS,
+        then: { function: 'oasOpFormDataConsumeCheck' },
+    },
+    'oas2-operation-security-defined': {
+        description: 'Operation security must reference defined securityDefinitions.',
+        formats: ['oas2'],
+        given: '$',
+        then: { function: 'oasOpSecurityDefined', functionOptions: { schemesPath: ['securityDefinitions'] } },
+    },
+    'oas2-parameter-description': {
+        description: 'Parameters should have a description.',
+        formats: ['oas2'],
+        given: '$..parameters[*]',
+        severity: 'warn',
+        recommended: false,
+        then: { field: 'description', function: 'truthy' },
+    },
+    'oas2-unused-definition': {
+        description: 'Definitions should be referenced.',
+        formats: ['oas2'],
+        given: '$.definitions',
+        severity: 'warn',
+        resolved: false,
+        then: { function: 'unreferencedReusableObject', functionOptions: { reusableObjectsLocation: '#/definitions' } },
+    },
+    'oas2-valid-schema-example': {
+        description: 'Schema examples must be valid against their schema.',
+        formats: ['oas2'],
+        given: SCHEMA_EXAMPLE_GIVEN,
+        severity: 'error',
+        then: { function: 'oasSchemaExample' },
+    },
+    'oas2-valid-media-example': {
+        description: 'Media type examples must be valid against their schema.',
+        formats: ['oas2'],
+        // In OpenAPI 2.0 examples live on the Response Object as a MIME-type → value
+        // map alongside a sibling `schema`, so target responses that have both.
+        given: '$..responses..[?(@ && @.schema && @.examples)]',
+        severity: 'error',
+        then: { function: 'oasMediaExample', functionOptions: { oasVersion: 2 } },
+    },
+    'oas2-schema': {
+        description: 'Validate structure of OpenAPI v2 specification.',
+        formats: ['oas2'],
+        severity: 'error',
+        recommended: true,
+        resolved: false,
+        given: '$',
+        then: { function: 'oasSchema', functionOptions: { version: '2.0' } },
+    },
+};
+/** OpenAPI v3.x rules. */
+const oas3Rules = {
+    'oas3-api-servers': {
+        description: 'OpenAPI 3 documents must have a non-empty servers array.',
+        formats: ['oas3'],
+        // Target the root and the `servers` field so a *missing* `servers` (not just
+        // an empty array) is reported — `given: '$.servers'` matches nothing when the
+        // key is absent, so the rule never fired for a document with no servers.
+        given: '$',
+        then: {
+            field: 'servers',
+            function: 'schema',
+            functionOptions: { schema: { type: 'array', minItems: 1, items: { type: 'object' } } },
+        },
+    },
+    'oas3-examples-value-or-externalValue': {
+        description: 'Example objects must use either value or externalValue, not both.',
+        formats: ['oas3'],
+        given: [
+            '$.components.examples[*]',
+            '$..content[*].examples[*]',
+            '$..parameters[*].examples[*]',
+            '$..headers[*].examples[*]',
+        ],
+        then: { function: 'oasExampleExternalValue' },
+    },
+    'oas3-operation-security-defined': {
+        description: 'Operation security must reference defined securitySchemes.',
+        formats: ['oas3'],
+        given: '$',
+        then: { function: 'oasOpSecurityDefined', functionOptions: { schemesPath: ['components', 'securitySchemes'] } },
+    },
+    'oas3-parameter-description': {
+        description: 'Parameters should have a description.',
+        formats: ['oas3'],
+        given: '$..parameters[*]',
+        severity: 'warn',
+        recommended: false,
+        then: { field: 'description', function: 'truthy' },
+    },
+    'oas3-server-not-example.com': {
+        description: 'Server URLs should not point to example.com.',
+        formats: ['oas3'],
+        given: '$.servers[*].url',
+        severity: 'warn',
+        recommended: false,
+        then: { function: 'pattern', functionOptions: { notMatch: 'example\\.com' } },
+    },
+    'oas3-server-trailing-slash': {
+        description: 'Server URLs should not have trailing slashes.',
+        formats: ['oas3'],
+        given: '$.servers[*].url',
+        then: { function: 'pattern', functionOptions: { notMatch: './$' } },
+    },
+    'oas3-server-variables': {
+        description: 'Server variables must be defined and used.',
+        formats: ['oas3'],
+        // Servers can appear at the root, on a path item, on an operation, and on a
+        // Link Object, so cover every location rather than just the root servers.
+        given: [
+            '$.servers[*]',
+            '$.paths[*].servers[*]',
+            '$.paths[*][*].servers[*]',
+            '$..links[*].server',
+            '$.webhooks[*].servers[*]',
+            '$.webhooks[*][*].servers[*]',
+        ],
+        severity: 'error',
+        then: { function: 'oasServerVariables' },
+    },
+    'oas3-callbacks-in-callbacks': {
+        description: 'Callbacks must not be defined within other callbacks.',
+        formats: ['oas3'],
+        given: '$..callbacks..callbacks',
+        then: { function: 'falsy' },
+    },
+    'oas3-unused-component': {
+        description: 'Reusable components should be referenced.',
+        formats: ['oas3'],
+        given: '$.components',
+        severity: 'warn',
+        resolved: false,
+        then: { function: 'oasUnusedComponent' },
+    },
+    'oas3-valid-schema-example': {
+        description: 'Schema examples must be valid against their schema.',
+        formats: ['oas3'],
+        given: SCHEMA_EXAMPLE_GIVEN,
+        severity: 'error',
+        then: { function: 'oasSchemaExample' },
+    },
+    'oas3-valid-media-example': {
+        description: 'Media type examples must be valid against their schema.',
+        formats: ['oas3'],
+        // Spectral validates examples on media types, parameters, and headers.
+        given: ['$..content[*]', '$..parameters[*]', '$..headers[*]'],
+        severity: 'error',
+        then: { function: 'oasMediaExample', functionOptions: { oasVersion: 3 } },
+    },
+    'oas3-schema': {
+        description: 'Validate structure of OpenAPI v3.0.x specification.',
+        formats: ['oas3_0'],
+        severity: 'error',
+        recommended: true,
+        resolved: false,
+        given: '$',
+        then: { function: 'oasSchema', functionOptions: { version: '3.0' } },
+    },
+};
+/** Rules for features introduced in OpenAPI 3.1 (and still in 3.2). */
+const oas31Rules = {
+    'oas3_1-servers-in-webhook': {
+        description: 'Webhooks must not define servers.',
+        // Servers can sit on the webhook Path Item itself (`$.webhooks[*]`) as well as
+        // on each operation, so target both. Also applies to 3.2.
+        formats: ['oas3_1', 'oas3_2'],
+        given: [WEBHOOK_OPERATIONS, '$.webhooks[*]'],
+        then: { field: 'servers', function: 'falsy' },
+    },
+    'oas3_1-callbacks-in-webhook': {
+        description: 'Webhooks must not define callbacks.',
+        formats: ['oas3_1', 'oas3_2'],
+        given: WEBHOOK_OPERATIONS,
+        then: { field: 'callbacks', function: 'falsy' },
+    },
+    'oas3_1-no-nullable': {
+        // `nullable` was removed in OpenAPI 3.1 (JSON Schema 2020-12 uses a `null`
+        // type instead) and stays gone in 3.2 — mirroring the oas2-anyOf/oneOf
+        // "feature not available in this version" rules. A custom function (targeting
+        // the parent of a `nullable` key) is used instead of `$..nullable` + `falsy`
+        // so a property literally named `nullable` is not flagged and `nullable: false`
+        // still is (so the migration fixer can drop it).
+        description: 'nullable is not available in OpenAPI 3.1 or later; use a "null" type instead.',
+        formats: ['oas3_1', 'oas3_2'],
+        given: '$..nullable^',
+        then: { function: 'oasNoNullable' },
+    },
+    'oas3_1-license-identifier': {
+        // The License Object's `identifier` (SPDX) field was added in 3.1 and is
+        // "mutually exclusive of the url field".
+        description: 'License object identifier and url are mutually exclusive.',
+        formats: ['oas3_1', 'oas3_2'],
+        given: '$.info.license',
+        severity: 'error',
+        then: { function: 'oasMutuallyExclusive', functionOptions: { properties: ['identifier', 'url'] } },
+    },
+    'oas3_1-schema': {
+        // The official, self-contained OpenAPI 3.1 meta-schema (spec.openapis.org).
+        // 3.1 realigned Schema Objects with JSON Schema 2020-12, so the official
+        // schema validates the whole document *envelope* while leaving Schema Object
+        // internals permissive (a local `$dynamicRef` "#meta" that the runtime
+        // validator resolves natively). The 3.0-only `oas3-schema` rule does not
+        // apply to 3.1 (different `openapi` version and structure).
+        description: 'Validate structure of OpenAPI v3.1 specification.',
+        formats: ['oas3_1'],
+        severity: 'error',
+        recommended: true,
+        resolved: false,
+        given: '$',
+        then: { function: 'oasSchema', functionOptions: { version: '3.1' } },
+    },
+    'oas3_1-schema-example-deprecated': {
+        // JSON Schema 2020-12 deprecates a Schema Object's singular `example` in
+        // favor of the `examples` array. Off by default (recommended: false) since
+        // singular examples remain widespread and valid-but-deprecated.
+        description: 'Schema "example" is deprecated in OpenAPI 3.1; use "examples" instead.',
+        formats: ['oas3_1', 'oas3_2'],
+        given: '$..example^',
+        severity: 'warn',
+        recommended: false,
+        then: { function: 'oasSchemaExampleDeprecated' },
+    },
+};
+/** Rules for features introduced in OpenAPI 3.2. */
+const oas32Rules = {
+    'oas3_2-schema': {
+        // The official, self-contained OpenAPI 3.2 meta-schema (spec.openapis.org).
+        // Like `oas3_1-schema`, it validates the document envelope and leaves Schema
+        // Object internals to JSON Schema 2020-12 via a local `$dynamicRef`.
+        description: 'Validate structure of OpenAPI v3.2 specification.',
+        formats: ['oas3_2'],
+        severity: 'error',
+        recommended: true,
+        resolved: false,
+        given: '$',
+        then: { function: 'oasSchema', functionOptions: { version: '3.2' } },
+    },
+    'oas3_2-additional-operations-standard-method': {
+        // `additionalOperations` is for HTTP methods without a dedicated fixed
+        // field; the spec forbids redefining a standard method there.
+        description: 'additionalOperations must not redefine a standard HTTP method that has its own fixed field.',
+        formats: ['oas3_2'],
+        given: '$..additionalOperations',
+        severity: 'error',
+        then: { function: 'oasAdditionalOperations' },
+    },
+    'oas3_2-server-name-unique': {
+        description: 'Server names should be unique across the servers array.',
+        formats: ['oas3_2'],
+        given: '$.servers',
+        severity: 'warn',
+        then: { function: 'oasServerNameUnique' },
+    },
+    'oas3_2-tag-parent-defined': {
+        // Tag hierarchies (3.2): a `parent` must name a defined tag, with no cycles.
+        // Mirrors `operation-tag-defined` for the new nesting feature.
+        description: 'Tag parent must reference a tag defined in the global tags list, without cycles.',
+        formats: ['oas3_2'],
+        given: '$.tags',
+        severity: 'warn',
+        then: { function: 'oasTagParentDefined' },
+    },
+    'oas3_2-tag-kind': {
+        // `kind` is free-form with a community registry of conventional values, so
+        // this is off by default (recommended: false) to avoid flagging valid
+        // custom kinds. Only a present-but-unregistered value is flagged.
+        description: 'Tag kind should use a registered value (nav, badge, audience).',
+        formats: ['oas3_2'],
+        given: '$.tags[*]',
+        severity: 'warn',
+        recommended: false,
+        then: { function: 'oasTagKind' },
+    },
+    'oas3_2-example-value': {
+        // 3.2 added `dataValue`/`serializedValue` to the Example Object with
+        // MUST-level exclusivity: dataValue excludes value; serializedValue excludes
+        // value and externalValue. (The value/externalValue pair is left to the
+        // 3.x-wide oas3-examples-value-or-externalValue rule.)
+        description: 'Example object dataValue/serializedValue must not be combined with value or externalValue.',
+        formats: ['oas3_2'],
+        given: [
+            '$.components.examples[*]',
+            '$..content[*].examples[*]',
+            '$..parameters[*].examples[*]',
+            '$..headers[*].examples[*]',
+        ],
+        severity: 'error',
+        then: { function: 'oasExampleValue' },
+    },
+};
+/** Loupe's built-in OpenAPI ruleset (`loupe:oas`). */
+export const oas = {
+    formats: ['oas2', 'oas3'],
+    rules: {
+        ...sharedRules,
+        ...oas2Rules,
+        ...oas3Rules,
+        ...oas31Rules,
+        ...oas32Rules,
+    },
+};