@amritk/lint 0.2.0 → 0.3.0

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

@@ -1,8 +1,10 @@
 import { oasMediaExample, oasSchemaExample } from './example-validation.js';
 import { oasAdditionalOperations } from './oas-additional-operations.js';
 import { oasDiscriminator } from './oas-discriminator.js';
+import { oasExampleExternalValue } from './oas-example-external-value.js';
 import { oasExampleValue } from './oas-example-value.js';
 import { oasMutuallyExclusive } from './oas-mutually-exclusive.js';
+import { oasNoNullable } from './oas-no-nullable.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';
@@ -22,8 +24,10 @@ 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 { 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';
@@ -54,9 +58,10 @@ export const oasFunctions = {
     oasDiscriminator,
     oasServerVariables,
     oasSchemaExample,
-    oasMediaExample,
+    oasMediaExample: oasMediaExample,
     oasUnusedComponent,
     oasMutuallyExclusive: oasMutuallyExclusive,
+    oasNoNullable,
     oasSchema: oasSchema,
     oasAdditionalOperations,
     oasServerNameUnique,
@@ -64,4 +69,5 @@ export const oasFunctions = {
     oasSchemaExampleDeprecated,
     oasTagKind,
     oasExampleValue,
+    oasExampleExternalValue,
 };

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

@@ -1,8 +1,8 @@
-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']);
+import { isObject, OPERATION_METHODS } from './helpers.js';
+// Methods that have a dedicated fixed field on the Path Item Object (the eight
+// standard methods plus 3.2's `query`). These MUST NOT be redefined inside the
+// new `additionalOperations` map, which is reserved for non-standard methods.
+const FIXED_PATH_ITEM_METHODS = OPERATION_METHODS;
 /**
  * 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

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

@@ -0,0 +1,11 @@
+import type { RulesetFunction } from '../../../core/index.js';
+/**
+ * Enforces that an Example Object carries exactly one inline value source. Across
+ * all of OpenAPI 3.x an Example must use either `value` or `externalValue` (not
+ * both, not neither). OpenAPI 3.2 added `dataValue`/`serializedValue` as further
+ * ways to supply the example, so their presence also satisfies the "has an
+ * example" requirement — otherwise a valid 3.2 `dataValue`-only example would be
+ * wrongly flagged. The mutual exclusivity of the new fields is policed separately
+ * by `oas3_2-example-value`.
+ */
+export declare const oasExampleExternalValue: RulesetFunction;

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

@@ -0,0 +1,23 @@
+import { isObject } from './helpers.js';
+/**
+ * Enforces that an Example Object carries exactly one inline value source. Across
+ * all of OpenAPI 3.x an Example must use either `value` or `externalValue` (not
+ * both, not neither). OpenAPI 3.2 added `dataValue`/`serializedValue` as further
+ * ways to supply the example, so their presence also satisfies the "has an
+ * example" requirement — otherwise a valid 3.2 `dataValue`-only example would be
+ * wrongly flagged. The mutual exclusivity of the new fields is policed separately
+ * by `oas3_2-example-value`.
+ */
+export const oasExampleExternalValue = (example) => {
+    if (!isObject(example))
+        return [];
+    // A 3.2 dataValue/serializedValue already provides the example, so value /
+    // externalValue are optional in that case.
+    if (example['dataValue'] !== undefined || example['serializedValue'] !== undefined)
+        return [];
+    const present = ['value', 'externalValue'].filter((property) => property in example);
+    if (present.length !== 1) {
+        return [{ message: 'Example object must have exactly one of "value" or "externalValue"' }];
+    }
+    return [];
+};

package/dist/rules/openapi/functions/oas-no-nullable.d.ts

@@ -0,0 +1,13 @@
+import type { RulesetFunction } from '../../../core/index.js';
+/**
+ * Flags a Schema Object's `nullable` keyword, removed in OpenAPI 3.1+ (JSON
+ * Schema 2020-12 uses a `"null"` type instead). Targets the *parent* of a
+ * `nullable` key (`$..nullable^`) rather than `$..nullable` directly, which fixes
+ * two problems with the naive `then: falsy` approach:
+ *   - a property literally named `nullable` (`properties: { nullable: {...} }`)
+ *     is no longer flagged, because there the `nullable` value is a Schema Object,
+ *     not the boolean keyword, and
+ *   - `nullable: false` is flagged too (a boolean of either value counts as the
+ *     keyword being present), so the migration fixer can drop it.
+ */
+export declare const oasNoNullable: RulesetFunction;

package/dist/rules/openapi/functions/oas-no-nullable.js

@@ -0,0 +1,22 @@
+import { isObject } from './helpers.js';
+/**
+ * Flags a Schema Object's `nullable` keyword, removed in OpenAPI 3.1+ (JSON
+ * Schema 2020-12 uses a `"null"` type instead). Targets the *parent* of a
+ * `nullable` key (`$..nullable^`) rather than `$..nullable` directly, which fixes
+ * two problems with the naive `then: falsy` approach:
+ *   - a property literally named `nullable` (`properties: { nullable: {...} }`)
+ *     is no longer flagged, because there the `nullable` value is a Schema Object,
+ *     not the boolean keyword, and
+ *   - `nullable: false` is flagged too (a boolean of either value counts as the
+ *     keyword being present), so the migration fixer can drop it.
+ */
+export const oasNoNullable = (parent, _options, context) => {
+    if (!isObject(parent) || typeof parent['nullable'] !== 'boolean')
+        return [];
+    return [
+        {
+            message: 'nullable is not available in OpenAPI 3.1 or later; use a "null" type instead.',
+            path: [...context.path, 'nullable'],
+        },
+    ];
+};

package/dist/rules/openapi/functions/oas-op-id-unique.js

@@ -1,4 +1,4 @@
-import { isObject } from './helpers.js';
+import { isObject, OPERATION_METHODS } from './helpers.js';
 /** Ensures `operationId` values are unique across the document. */
 export const oasOpIdUnique = (paths, _options, context) => {
     if (!isObject(paths))
@@ -9,7 +9,9 @@ export const oasOpIdUnique = (paths, _options, context) => {
         if (!isObject(item))
             continue;
         for (const [method, operation] of Object.entries(item)) {
-            if (!isObject(operation))
+            // Only real operations carry an `operationId`; an `x-`extension object with
+            // an `operationId`-looking key would otherwise create a phantom duplicate.
+            if (!OPERATION_METHODS.has(method) || !isObject(operation))
                 continue;
             const id = operation['operationId'];
             if (typeof id !== 'string')

package/dist/rules/openapi/functions/oas-op-params.d.ts

@@ -1,3 +1,9 @@
 import type { RulesetFunction } from '../../../core/index.js';
-/** Flags duplicate `name`+`in` parameter combinations on an operation. */
+/**
+ * Validates an operation's `parameters` array, mirroring Spectral's `oasOpParams`:
+ * flags duplicate `name`+`in` combinations, and — for OpenAPI 2.0, where the body
+ * is a parameter — flags more than one `in: body` parameter (even with different
+ * names) as well as mixing `in: body` with `in: formData`. `$ref` entries are
+ * skipped because their real `name`/`in` is only known after resolution.
+ */
 export declare const oasOpParams: RulesetFunction;

package/dist/rules/openapi/functions/oas-op-params.js

@@ -1,21 +1,46 @@
 import { isObject } from './helpers.js';
-/** Flags duplicate `name`+`in` parameter combinations on an operation. */
+/**
+ * Validates an operation's `parameters` array, mirroring Spectral's `oasOpParams`:
+ * flags duplicate `name`+`in` combinations, and — for OpenAPI 2.0, where the body
+ * is a parameter — flags more than one `in: body` parameter (even with different
+ * names) as well as mixing `in: body` with `in: formData`. `$ref` entries are
+ * skipped because their real `name`/`in` is only known after resolution.
+ */
 export const oasOpParams = (params, _options, context) => {
     if (!Array.isArray(params))
         return [];
-    const seen = new Set();
     const results = [];
+    const seen = new Set();
+    const bodyIndices = [];
+    const formDataIndices = [];
     params.forEach((param, index) => {
-        if (!isObject(param) || param['name'] === undefined || param['in'] === undefined)
+        if (!isObject(param) || '$ref' in param)
             return;
-        const key = `${String(param['in'])}:${String(param['name'])}`;
-        if (seen.has(key)) {
-            results.push({
-                message: `Duplicate parameter "${String(param['name'])}" in "${String(param['in'])}"`,
-                path: [...context.path, index],
-            });
+        if (param['name'] !== undefined && param['in'] !== undefined) {
+            const key = `${String(param['in'])}:${String(param['name'])}`;
+            if (seen.has(key)) {
+                results.push({
+                    message: `Duplicate parameter "${String(param['name'])}" in "${String(param['in'])}"`,
+                    path: [...context.path, index],
+                });
+            }
+            seen.add(key);
         }
-        seen.add(key);
+        if (param['in'] === 'body')
+            bodyIndices.push(index);
+        else if (param['in'] === 'formData')
+            formDataIndices.push(index);
     });
+    // OAS2 allows at most one body parameter, and body and formData are mutually
+    // exclusive within a single operation.
+    if (bodyIndices.length > 0 && formDataIndices.length > 0) {
+        results.push({ message: 'Operation must not have both "in:body" and "in:formData" parameters' });
+    }
+    for (let i = 1; i < bodyIndices.length; i++) {
+        results.push({
+            message: 'Operation must not have more than a single instance of the "in:body" parameter',
+            path: [...context.path, bodyIndices[i]],
+        });
+    }
     return results;
 };

package/dist/rules/openapi/functions/oas-op-security-defined.js

@@ -1,4 +1,4 @@
-import { HTTP_METHODS, isObject } from './helpers.js';
+import { isObject, OPERATION_METHODS } from './helpers.js';
 /** Walks `path` into `root`, returning the nested value or undefined. */
 const getIn = (root, path) => {
     let current = root;
@@ -35,7 +35,7 @@ export const oasOpSecurityDefined = (root, options, context) => {
         if (!isObject(item))
             continue;
         for (const [method, operation] of Object.entries(item)) {
-            if (HTTP_METHODS.has(method) && isObject(operation)) {
+            if (OPERATION_METHODS.has(method) && isObject(operation)) {
                 check(operation['security'], [...context.path, 'paths', path, method, 'security']);
             }
         }

package/dist/rules/openapi/functions/oas-op-success-response.js

@@ -1,9 +1,14 @@
 import { isObject } from './helpers.js';
+// A success response is any 2xx/3xx status code, or a `2XX`/`3XX` wildcard (3.x).
+// `default` is intentionally NOT counted — it can carry any status, including an
+// error, so it does not prove the operation has a success response (this matches
+// Spectral, which counts only codes in the [200, 400) range plus the wildcards).
+const SUCCESS_CODE = /^[23](\d\d|XX)$/;
 /** Ensures every operation declares at least one 2xx or 3xx response. */
 export const oasOpSuccessResponse = (responses) => {
     if (!isObject(responses))
         return [];
-    const hasSuccess = Object.keys(responses).some((code) => /^[23]\d\d$/.test(code) || code === 'default');
+    const hasSuccess = Object.keys(responses).some((code) => SUCCESS_CODE.test(code));
     if (!hasSuccess) {
         return [{ message: 'Operation must define at least one 2xx or 3xx response' }];
     }

package/dist/rules/openapi/functions/oas-path-param.d.ts

@@ -1,3 +1,12 @@
 import type { RulesetFunction } from '../../../core/index.js';
-/** Validates path templating: declared `{params}` must have matching path parameters. */
+/**
+ * Validates path templating per operation, mirroring Spectral's `oasPathParam`.
+ * For each operation on a path it checks that (a) every `{template}` in the path
+ * has a matching `in: path` definition, (b) every `in: path` definition is used
+ * in the template, (c) path parameters carry `required: true`, (d) a template is
+ * not repeated in the path key, and (e) a parameter is not defined twice. Path
+ * Item level parameters are merged with the operation's own parameters. Runs on
+ * the resolved document (the rule is `resolved: true`), so `$ref`d parameters are
+ * already inlined.
+ */
 export declare const oasPathParam: RulesetFunction;

package/dist/rules/openapi/functions/oas-path-param.js

@@ -1,5 +1,40 @@
-import { HTTP_METHODS, isObject } from './helpers.js';
-/** Validates path templating: declared `{params}` must have matching path parameters. */
+import { isObject, OPERATION_METHODS } from './helpers.js';
+// Path template parameters, e.g. `{id}`. Matches Spectral's grammar so matrix
+// (`{;id}`), optional (`{id?}`), and explode (`{id*}`) markers are stripped off
+// the captured name before comparison.
+const PATH_TEMPLATE = /(\{;?\??[a-zA-Z0-9_-]+\*?\})/g;
+const namedPathParam = (param) => param['in'] === 'path' && typeof param['name'] === 'string' ? param['name'] : undefined;
+/**
+ * Records a single `in: path` definition, emitting Spectral's `required: true`
+ * and duplicate-definition findings. Returns the parameter name when it is the
+ * first definition seen (so the caller registers it as usable), else undefined.
+ */
+const recordPathParam = (param, definitionPath, seen, results) => {
+    const name = namedPathParam(param);
+    if (name === undefined)
+        return undefined;
+    if (param['required'] !== true) {
+        results.push({
+            message: `Path parameter "${name}" must have a "required" property that is set to "true"`,
+            path: definitionPath,
+        });
+    }
+    if (name in seen) {
+        results.push({ message: `Path parameter "${name}" must not be defined multiple times`, path: definitionPath });
+        return undefined;
+    }
+    return name;
+};
+/**
+ * Validates path templating per operation, mirroring Spectral's `oasPathParam`.
+ * For each operation on a path it checks that (a) every `{template}` in the path
+ * has a matching `in: path` definition, (b) every `in: path` definition is used
+ * in the template, (c) path parameters carry `required: true`, (d) a template is
+ * not repeated in the path key, and (e) a parameter is not defined twice. Path
+ * Item level parameters are merged with the operation's own parameters. Runs on
+ * the resolved document (the rule is `resolved: true`), so `$ref`d parameters are
+ * already inlined.
+ */
 export const oasPathParam = (paths, _options, context) => {
     if (!isObject(paths))
         return [];
@@ -7,38 +42,64 @@ export const oasPathParam = (paths, _options, context) => {
     for (const [path, item] of Object.entries(paths)) {
         if (!isObject(item))
             continue;
-        const templates = [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
-        const seen = new Set();
-        for (const template of templates) {
-            if (seen.has(template)) {
+        // (d) Templates declared in the path key, deduplicated (a repeat is an error).
+        const templates = [];
+        for (const match of path.matchAll(PATH_TEMPLATE)) {
+            const name = match[0].replace(/[{}?*;]/g, '');
+            if (templates.includes(name)) {
                 results.push({
-                    message: `Path "${path}" uses parameter "{${template}}" more than once`,
+                    message: `Path "${path}" must not use parameter "{${name}}" more than once`,
                     path: [...context.path, path],
                 });
             }
-            seen.add(template);
-        }
-        const declared = new Set();
-        const collect = (params) => {
-            if (!Array.isArray(params))
-                return;
-            for (const param of params) {
-                if (isObject(param) && param['in'] === 'path' && typeof param['name'] === 'string')
-                    declared.add(param['name']);
+            else {
+                templates.push(name);
             }
-        };
-        collect(item['parameters']);
-        for (const [method, operation] of Object.entries(item)) {
-            if (HTTP_METHODS.has(method) && isObject(operation))
-                collect(operation['parameters']);
         }
-        for (const template of seen) {
-            if (!declared.has(template)) {
-                results.push({
-                    message: `Path parameter "{${template}}" in "${path}" has no matching path parameter definition`,
-                    path: [...context.path, path],
+        // Path Item level parameters apply to every operation on the path.
+        const topParams = {};
+        if (Array.isArray(item['parameters'])) {
+            item['parameters'].forEach((param, index) => {
+                if (!isObject(param))
+                    return;
+                const definitionPath = [...context.path, path, 'parameters', index];
+                const name = recordPathParam(param, definitionPath, topParams, results);
+                if (name !== undefined)
+                    topParams[name] = definitionPath;
+            });
+        }
+        for (const [method, operation] of Object.entries(item)) {
+            if (method === 'parameters' || !OPERATION_METHODS.has(method) || !isObject(operation))
+                continue;
+            const operationPath = [...context.path, path, method];
+            // Each operation is evaluated against its own params plus the shared path-item ones.
+            const operationParams = {};
+            if (Array.isArray(operation['parameters'])) {
+                operation['parameters'].forEach((param, index) => {
+                    if (!isObject(param))
+                        return;
+                    const definitionPath = [...operationPath, 'parameters', index];
+                    const name = recordPathParam(param, definitionPath, operationParams, results);
+                    if (name !== undefined)
+                        operationParams[name] = definitionPath;
                 });
             }
+            const defined = { ...topParams, ...operationParams };
+            // (b) Every defined `in: path` parameter must appear in the path template.
+            for (const [name, definitionPath] of Object.entries(defined)) {
+                if (definitionPath && !templates.includes(name)) {
+                    results.push({ message: `Parameter "${name}" must be used in path "${path}"`, path: definitionPath });
+                }
+            }
+            // (a) Every `{template}` must have a matching definition on the operation.
+            for (const name of templates) {
+                if (!(name in defined)) {
+                    results.push({
+                        message: `Operation must define path parameter "{${name}}" as expected by path "${path}"`,
+                        path: operationPath,
+                    });
+                }
+            }
         }
     }
     return results;

package/dist/rules/openapi/functions/oas-server-variables.d.ts

@@ -1,3 +1,8 @@
 import type { RulesetFunction } from '../../../core/index.js';
-/** Validates server variables are declared and used. */
+/**
+ * Validates a Server Object's `variables`, mirroring Spectral's `serverVariables`:
+ * every `{template}` in the URL must have a matching variable and vice versa, and
+ * each defined variable must have a `default`, a non-empty `enum` when present,
+ * and a `default` that is listed in that `enum`.
+ */
 export declare const oasServerVariables: RulesetFunction;

package/dist/rules/openapi/functions/oas-server-variables.js

@@ -1,5 +1,10 @@
 import { isObject } from './helpers.js';
-/** Validates server variables are declared and used. */
+/**
+ * Validates a Server Object's `variables`, mirroring Spectral's `serverVariables`:
+ * every `{template}` in the URL must have a matching variable and vice versa, and
+ * each defined variable must have a `default`, a non-empty `enum` when present,
+ * and a `default` that is listed in that `enum`.
+ */
 export const oasServerVariables = (server, _options, context) => {
     if (!isObject(server) || typeof server['url'] !== 'string')
         return [];
@@ -11,13 +16,37 @@ export const oasServerVariables = (server, _options, context) => {
             results.push({ message: `Server variable "${template}" is not defined`, path: [...context.path, 'variables'] });
         }
     }
-    for (const name of Object.keys(variables)) {
+    for (const [name, variable] of Object.entries(variables)) {
         if (!templates.includes(name)) {
             results.push({
                 message: `Server variable "${name}" is not used in the URL`,
                 path: [...context.path, 'variables', name],
             });
         }
+        if (!isObject(variable))
+            continue;
+        const hasDefault = variable['default'] !== undefined;
+        if (!hasDefault) {
+            results.push({
+                message: `Server variable "${name}" has a missing default`,
+                path: [...context.path, 'variables', name],
+            });
+        }
+        if ('enum' in variable) {
+            const enumValues = Array.isArray(variable['enum']) ? variable['enum'] : [];
+            if (enumValues.length === 0) {
+                results.push({
+                    message: `Server variable "${name}" has an empty enum`,
+                    path: [...context.path, 'variables', name, 'enum'],
+                });
+            }
+            else if (hasDefault && !enumValues.includes(variable['default'])) {
+                results.push({
+                    message: `Server variable "${name}" has a default not listed in the enum`,
+                    path: [...context.path, 'variables', name, 'default'],
+                });
+            }
+        }
     }
     return results;
 };

package/dist/rules/openapi/functions/oas-unused-component.js

@@ -1,6 +1,7 @@
 import { isObject } from './helpers.js';
 // Reusable component types that are referenced via `$ref` (securitySchemes are
 // referenced by name in `security`, not via `$ref`, so they are excluded).
+// `pathItems` was added in OpenAPI 3.1 (referenced from `webhooks` / `callbacks`).
 const REUSABLE_COMPONENT_TYPES = [
     'schemas',
     'responses',
@@ -10,6 +11,7 @@ const REUSABLE_COMPONENT_TYPES = [
     'headers',
     'links',
     'callbacks',
+    'pathItems',
 ];
 /** Collects every `$ref` string anywhere in `node` into `into`. */
 const collectRefs = (node, into) => {
@@ -37,13 +39,24 @@ export const oasUnusedComponent = (components, _options, context) => {
         return [];
     const refs = new Set();
     collectRefs(context.document.data, refs);
+    // A component counts as used when a `$ref` targets it OR points *into* it
+    // (e.g. `#/components/schemas/Pet/properties/id` still uses `Pet`), so match by
+    // prefix rather than exact string — an interior ref must not leave the parent
+    // flagged as unused.
+    const isReferenced = (base) => {
+        for (const ref of refs) {
+            if (ref === base || ref.startsWith(`${base}/`))
+                return true;
+        }
+        return false;
+    };
     const results = [];
     for (const type of REUSABLE_COMPONENT_TYPES) {
         const group = components[type];
         if (!isObject(group))
             continue;
         for (const key of Object.keys(group)) {
-            if (!refs.has(`#/components/${type}/${key}`)) {
+            if (!isReferenced(`#/components/${type}/${key}`)) {
                 results.push({ message: 'Potentially unused component has been detected.', path: [...context.path, type, key] });
             }
         }