@amritk/lint 0.1.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.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,248 @@
+/** 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(/\/+$/, '');
+/**
+ * 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).
+ */
+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, 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 };
+    },
+};
+/** `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 = canonicalKey(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 };
+    },
+};
+// 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,
+    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' ? 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 };
+    },
+};
+/** `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;
+    },
+};
+/**
+ * `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
+ * 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,
+    'oas3_1-schema-example-deprecated': schemaExampleDeprecated,
+};

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,30 @@
+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) => /^3\.\d/.test(openapiVersion(document) ?? '');
+/** Matches OpenAPI 3.0.x specifically. */
+export const oas3_0 = (document) => matchesMinor(document, 0);
+/** Matches OpenAPI 3.1.x specifically. */
+export const oas3_1 = (document) => matchesMinor(document, 1);
+/** Matches OpenAPI 3.2.x specifically. */
+export const oas3_2 = (document) => matchesMinor(document, 2);
+/** 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,18 @@
+import type { RulesetFunction } from '../../../core/index.js';
+/** 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 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>;