@amritk/lint 0.2.0 → 0.3.0

package/dist/functions/casing.js

@@ -2,11 +2,15 @@ const PATTERNS = {
     flat: '[a-z][a-z{d}]*',
     camel: '[a-z][a-z{d}]*(?:[A-Z{d}](?:[a-z{d}]+|$))*',
     pascal: '[A-Z][a-z{d}]*(?:[A-Z{d}](?:[a-z{d}]+|$))*',
-    kebab: '[a-z][a-z{d}]*(?:-[a-z][a-z{d}]*)*',
-    cobol: '[A-Z][A-Z{d}]*(?:-[A-Z][A-Z{d}]*)*',
-    snake: '[a-z][a-z{d}]*(?:_[a-z][a-z{d}]*)*',
-    macro: '[A-Z][A-Z{d}]*(?:_[A-Z][A-Z{d}]*)*',
+    // Segments after a separator may start with a digit, matching Spectral (so
+    // "foo-2fa" is valid kebab case). The sub-pattern is `[a-z{d}]+`, not the
+    // stricter `[a-z][a-z{d}]*` which would require a letter right after the sep.
+    kebab: '[a-z][a-z{d}]*(?:-[a-z{d}]+)*',
+    cobol: '[A-Z][A-Z{d}]*(?:-[A-Z{d}]+)*',
+    snake: '[a-z][a-z{d}]*(?:_[a-z{d}]+)*',
+    macro: '[A-Z][A-Z{d}]*(?:_[A-Z{d}]+)*',
 };
+const VALID_TYPES = Object.keys(PATTERNS);
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 const buildRegExp = (options) => {
     const digits = options.disallowDigits ? '' : '0-9';
@@ -19,10 +23,28 @@ const buildRegExp = (options) => {
 };
 /** Flags a string that does not match the configured casing style. */
 export const casing = (input, options) => {
+    if (!options?.type)
+        return [];
+    // Guard an unknown `type` before it reaches `PATTERNS[type]`, which would be
+    // `undefined` and crash on `.replace`. Mirror Spectral's option schema by
+    // naming every accepted value in a single, clear error finding.
+    if (!VALID_TYPES.includes(options.type)) {
+        return [
+            {
+                message: `"casing" function and its "type" option accept the following values: ${VALID_TYPES.join(', ')}`,
+            },
+        ];
+    }
     if (typeof input !== 'string' || input.length === 0)
         return [];
-    if (!options?.type)
+    // Spectral special-cases a lone separator char with `allowLeading` as valid.
+    // This is what keeps the OpenAPI root path "/" from being flagged.
+    if (input.length === 1 &&
+        options.separator !== undefined &&
+        options.separator.allowLeading === true &&
+        input === options.separator.char) {
         return [];
+    }
     if (!buildRegExp(options).test(input)) {
         return [{ message: `The value must be in ${options.type} case` }];
     }

package/dist/functions/enumeration.d.ts

@@ -1,5 +1,7 @@
 import type { RulesetFunction } from '../core/index.js';
-/** Flags a value that is not one of the allowed `values`. */
-export declare const enumeration: RulesetFunction<unknown, {
+/** Options for {@link enumeration}. */
+export type IEnumerationOptions = {
     values: unknown[];
-}>;
+};
+/** Flags a value that is not one of the allowed `values`. */
+export declare const enumeration: RulesetFunction<unknown, IEnumerationOptions>;

package/dist/functions/enumeration.js

@@ -1,6 +1,23 @@
+/**
+ * True for the primitive kinds Spectral's input schema accepts
+ * (`string`, `number`, `null`, `boolean`). Objects and arrays are excluded so
+ * they cannot slip through the reference-equality `includes` check below and be
+ * flagged against a list they could never be `===` to.
+ */
+const isPrimitive = (value) => value === null || (typeof value !== 'object' && typeof value !== 'function');
 /** Flags a value that is not one of the allowed `values`. */
 export const enumeration = (input, options) => {
-    const values = options?.values ?? [];
+    const values = options?.values;
+    // Without a valid list of allowed values there is nothing to compare against.
+    // Spectral requires `values` in its option schema and no-ops when it is
+    // missing, so skip rather than flag everything against an empty allow-list.
+    if (!Array.isArray(values))
+        return [];
+    // Spectral's input schema only lets primitives reach this function. `includes`
+    // uses reference equality, so a non-primitive would always be reported as
+    // "not allowed"; match Spectral by skipping objects and arrays entirely.
+    if (!isPrimitive(input))
+        return [];
     if (!values.includes(input)) {
         return [
             { message: `The value must be one of the allowed values: ${values.map((v) => JSON.stringify(v)).join(', ')}` },

package/dist/functions/index.d.ts

@@ -5,6 +5,7 @@ export { defined } from './defined.js';
 export { enumeration } from './enumeration.js';
 export { falsy } from './falsy.js';
 export { length } from './length.js';
+export { type IOrOptions, or } from './or.js';
 export { pattern } from './pattern.js';
 export { type ISchemaOptions, schema } from './schema.js';
 export { truthy } from './truthy.js';

package/dist/functions/index.js

@@ -4,6 +4,7 @@ import { defined } from './defined.js';
 import { enumeration } from './enumeration.js';
 import { falsy } from './falsy.js';
 import { length } from './length.js';
+import { or } from './or.js';
 import { pattern } from './pattern.js';
 import { schema } from './schema.js';
 import { truthy } from './truthy.js';
@@ -17,6 +18,7 @@ export { defined } from './defined.js';
 export { enumeration } from './enumeration.js';
 export { falsy } from './falsy.js';
 export { length } from './length.js';
+export { or } from './or.js';
 export { pattern } from './pattern.js';
 export { schema } from './schema.js';
 export { truthy } from './truthy.js';
@@ -32,6 +34,7 @@ export const builtinFunctions = {
     enumeration: enumeration,
     falsy,
     length: length,
+    or: or,
     pattern: pattern,
     schema: schema,
     truthy,

package/dist/functions/length.d.ts

@@ -1,6 +1,16 @@
 import type { RulesetFunction } from '../core/index.js';
-/** Flags a value whose size falls outside the `min`/`max` bounds. */
-export declare const length: RulesetFunction<unknown, {
+/** Options for {@link length}. */
+export type ILengthOptions = {
     min?: number;
     max?: number;
-}>;
+};
+/**
+ * Flags a value whose size falls outside the `min`/`max` bounds.
+ *
+ * With neither `min` nor `max` supplied this is a no-op on every node. That
+ * matches Spectral, which requires at least one bound in its option schema and
+ * simply produces no results once the options load without them. We also ignore
+ * a `min`/`max` that is not a number so a stray string like "3" cannot slip into
+ * the `<`/`>` comparison and be coerced into a misleading result.
+ */
+export declare const length: RulesetFunction<unknown, ILengthOptions>;

package/dist/functions/length.js

@@ -11,16 +11,24 @@ const measure = (input) => {
         return input;
     return undefined;
 };
-/** Flags a value whose size falls outside the `min`/`max` bounds. */
+/**
+ * Flags a value whose size falls outside the `min`/`max` bounds.
+ *
+ * With neither `min` nor `max` supplied this is a no-op on every node. That
+ * matches Spectral, which requires at least one bound in its option schema and
+ * simply produces no results once the options load without them. We also ignore
+ * a `min`/`max` that is not a number so a stray string like "3" cannot slip into
+ * the `<`/`>` comparison and be coerced into a misleading result.
+ */
 export const length = (input, options) => {
     const size = measure(input);
     if (size === undefined)
         return [];
     const results = [];
-    if (options?.min !== undefined && size < options.min) {
+    if (typeof options?.min === 'number' && size < options.min) {
         results.push({ message: `The value must not be shorter than ${options.min}` });
     }
-    if (options?.max !== undefined && size > options.max) {
+    if (typeof options?.max === 'number' && size > options.max) {
         results.push({ message: `The value must not be longer than ${options.max}` });
     }
     return results;

package/dist/functions/or.d.ts

@@ -0,0 +1,11 @@
+import type { RulesetFunction } from '../core/index.js';
+/** Options for {@link or}. */
+export type IOrOptions = {
+    properties: string[];
+};
+/**
+ * Flags an object when none of the listed `properties` is defined on it. Where
+ * {@link xor} requires exactly one, `or` requires at least one — it stays quiet
+ * as soon as a single listed property is present.
+ */
+export declare const or: RulesetFunction<Record<string, unknown>, IOrOptions>;

package/dist/functions/or.js

@@ -0,0 +1,25 @@
+/**
+ * Flags an object when none of the listed `properties` is defined on it. Where
+ * {@link xor} requires exactly one, `or` requires at least one — it stays quiet
+ * as soon as a single listed property is present.
+ */
+export const or = (input, options) => {
+    if (typeof input !== 'object' || input === null)
+        return [];
+    const properties = options?.properties;
+    // Spectral validates that at least two properties are supplied and no-ops when
+    // that is not the case, so we skip in silence rather than flag every node.
+    if (!Array.isArray(properties) || properties.length < 2)
+        return [];
+    const present = properties.filter((property) => property in input);
+    if (present.length > 0)
+        return [];
+    // Match Spectral's message: a long list is abbreviated to the first three
+    // properties plus a count of the rest so the finding stays readable.
+    if (properties.length > 4) {
+        const shortProps = properties.slice(0, 3);
+        const count = `${properties.length - 3} other properties must be defined`;
+        return [{ message: `At least one of "${shortProps.join('" or "')}" or ${count}` }];
+    }
+    return [{ message: `At least one of "${properties.join('" or "')}" must be defined` }];
+};

package/dist/functions/pattern.d.ts

@@ -1,6 +1,8 @@
 import type { RulesetFunction } from '../core/index.js';
-/** Flags a string that fails `match` or satisfies `notMatch`. */
-export declare const pattern: RulesetFunction<string, {
+/** Options for {@link pattern}. */
+export type IPatternOptions = {
     match?: string;
     notMatch?: string;
-}>;
+};
+/** Flags a string that fails `match` or satisfies `notMatch`. */
+export declare const pattern: RulesetFunction<string, IPatternOptions>;

package/dist/functions/pattern.js

@@ -1,20 +1,53 @@
-/** Parses a `/pattern/flags` string (or a bare pattern) into a RegExp. */
+// Compiling a RegExp is not free, and rules run this function once per matched
+// node, so we memoize by the raw pattern string (which carries its own flags in
+// the `/re/flags` form). A failed compile is cached as its `Error` so a bad
+// pattern is reported without being re-thrown on every node. Mirrors Spectral's
+// own module-level cache.
+const cache = new Map();
+/** Parses a `/pattern/flags` string (or a bare pattern) into a RegExp, or the compile error. */
 const toRegExp = (pattern) => {
-    const match = /^\/(.+)\/([a-z]*)$/s.exec(pattern);
-    if (match)
-        return new RegExp(match[1], match[2]);
-    return new RegExp(pattern);
+    const cached = cache.get(pattern);
+    if (cached !== undefined) {
+        // A cached RegExp carrying the `g`/`y` flag keeps `lastIndex` between calls,
+        // which would make `.test` skip characters on the next node. Reset it so a
+        // reused pattern behaves the same as a freshly compiled one.
+        if (cached instanceof RegExp)
+            cached.lastIndex = 0;
+        return cached;
+    }
+    let compiled;
+    try {
+        const match = /^\/(.+)\/([a-z]*)$/s.exec(pattern);
+        compiled = match ? new RegExp(match[1], match[2]) : new RegExp(pattern);
+    }
+    catch (error) {
+        compiled = error instanceof Error ? error : new Error(String(error));
+    }
+    cache.set(pattern, compiled);
+    return compiled;
 };
 /** Flags a string that fails `match` or satisfies `notMatch`. */
 export const pattern = (input, options) => {
     if (typeof input !== 'string')
         return [];
     const results = [];
-    if (options?.match !== undefined && !toRegExp(options.match).test(input)) {
-        results.push({ message: `The value must match the pattern "${options.match}"` });
+    if (options?.match !== undefined) {
+        const re = toRegExp(options.match);
+        if (re instanceof Error) {
+            results.push({ message: `The "match" option is not a valid regular expression: ${re.message}` });
+        }
+        else if (!re.test(input)) {
+            results.push({ message: `The value must match the pattern "${options.match}"` });
+        }
     }
-    if (options?.notMatch !== undefined && toRegExp(options.notMatch).test(input)) {
-        results.push({ message: `The value must not match the pattern "${options.notMatch}"` });
+    if (options?.notMatch !== undefined) {
+        const re = toRegExp(options.notMatch);
+        if (re instanceof Error) {
+            results.push({ message: `The "notMatch" option is not a valid regular expression: ${re.message}` });
+        }
+        else if (re.test(input)) {
+            results.push({ message: `The value must not match the pattern "${options.notMatch}"` });
+        }
     }
     return results;
 };

package/dist/functions/schema.d.ts

@@ -1,8 +1,21 @@
 import type { RulesetFunction } from '../core/index.js';
 /** Options for {@link schema}. */
 export type ISchemaOptions = {
+    /** The JSON Schema to validate the matched value against. */
     schema: object;
+    /**
+     * Report every validation error rather than stopping at the first. Defaults to
+     * `false`, matching Spectral (whose underlying ajv instance runs with
+     * `allErrors: false` unless told otherwise).
+     */
     allErrors?: boolean;
+    /**
+     * Accepted for Spectral compatibility but intentionally ignored. The draft is
+     * auto-detected by `@amritk/runtime-validators`, so both draft-4 constructs
+     * (boolean `exclusiveMinimum`) and draft-7 ones (tuple `items`) validate
+     * without the caller naming a dialect.
+     */
+    dialect?: string;
 };
 /** Validates a value against a JSON Schema supplied in the rule's options. */
 export declare const schema: RulesetFunction<unknown, ISchemaOptions>;

package/dist/functions/schema.js

@@ -13,6 +13,70 @@ const getValidator = (schema) => {
     }
     return validator;
 };
+const KNOWN_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'null', 'object', 'array']);
+// Keywords whose value is itself a schema, a list of schemas, or a map of
+// schemas. We recurse through them to reach every `type` a schema declares.
+const SCHEMA_VALUE_KEYS = ['additionalProperties', 'not', 'if', 'then', 'else', 'propertyNames', 'contains'];
+const SCHEMA_ITEMS_KEYS = ['items', 'additionalItems'];
+const SCHEMA_LIST_KEYS = ['allOf', 'anyOf', 'oneOf'];
+const SCHEMA_MAP_KEYS = ['properties', 'patternProperties', 'definitions', '$defs', 'dependencies'];
+/**
+ * Walks a schema looking for a `type` keyword whose value is not a JSON Schema
+ * type. `@amritk/runtime-validators` treats an unknown `type` as "always
+ * matches" (so it never rejects data it does not model), which means a typo like
+ * `type: "Pascal"` would silently disable the rule. Finding it up front lets us
+ * report it instead. Returns the offending type, or `undefined` when the schema
+ * only uses known types.
+ */
+const findInvalidType = (node) => {
+    if (Array.isArray(node) || typeof node !== 'object' || node === null)
+        return undefined;
+    const schema = node;
+    const declared = schema['type'];
+    if (declared !== undefined) {
+        const types = Array.isArray(declared) ? declared : [declared];
+        for (const type of types) {
+            if (typeof type !== 'string' || !KNOWN_TYPES.has(type)) {
+                return typeof type === 'string' ? type : String(type);
+            }
+        }
+    }
+    for (const key of SCHEMA_VALUE_KEYS) {
+        const found = findInvalidType(schema[key]);
+        if (found !== undefined)
+            return found;
+    }
+    for (const key of SCHEMA_ITEMS_KEYS) {
+        const value = schema[key];
+        const list = Array.isArray(value) ? value : [value];
+        for (const item of list) {
+            const found = findInvalidType(item);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    for (const key of SCHEMA_LIST_KEYS) {
+        const value = schema[key];
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                const found = findInvalidType(item);
+                if (found !== undefined)
+                    return found;
+            }
+        }
+    }
+    for (const key of SCHEMA_MAP_KEYS) {
+        const value = schema[key];
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            for (const item of Object.values(value)) {
+                const found = findInvalidType(item);
+                if (found !== undefined)
+                    return found;
+            }
+        }
+    }
+    return undefined;
+};
 const pointerToPath = (pointer) => pointer
     .split('/')
     .slice(1)
@@ -26,10 +90,39 @@ const formatError = (error) => {
 export const schema = (input, options, context) => {
     if (!options?.schema)
         return [];
-    const result = getValidator(options.schema)(input);
+    // A malformed schema would otherwise validate everything and silently disable
+    // the rule. Surface it as a finding, the way Spectral reports schema compile
+    // errors as results, so the ruleset author notices the mistake.
+    const invalidType = findInvalidType(options.schema);
+    if (invalidType !== undefined) {
+        return [
+            {
+                message: `Invalid schema: unknown type "${invalidType}". Valid types are: ${[...KNOWN_TYPES].join(', ')}`,
+                path: [...context.path],
+            },
+        ];
+    }
+    let result;
+    try {
+        result = getValidator(options.schema)(input);
+    }
+    catch (error) {
+        // Preparing or running the validator can throw on a schema shape we cannot
+        // interpret. Report it rather than letting it bubble up and crash the run.
+        return [
+            {
+                message: `Invalid schema: ${error instanceof Error ? error.message : String(error)}`,
+                path: [...context.path],
+            },
+        ];
+    }
     if (result === true)
         return [];
-    return result.errors.map((error) => ({
+    // Spectral's ajv defaults to `allErrors: false`, reporting only the first
+    // failure. Honor the same default and only expand to the full list when the
+    // caller opts in.
+    const errors = options.allErrors ? result.errors : result.errors.slice(0, 1);
+    return errors.map((error) => ({
         message: formatError(error),
         path: [...context.path, ...pointerToPath(error.path)],
     }));

package/dist/functions/typed-enum.js

@@ -15,7 +15,13 @@ export const typedEnum = (input, _options, context) => {
     const values = input['enum'];
     if (declaredType === undefined || !Array.isArray(values))
         return [];
-    const types = Array.isArray(declaredType) ? declaredType : [declaredType];
+    const types = Array.isArray(declaredType) ? [...declaredType] : [declaredType];
+    // A schema marked nullable (OpenAPI 3 `nullable` or the Swagger 2 `x-nullable`
+    // vendor extension) is allowed to hold `null` in addition to its declared
+    // type, so `null` must not be flagged as a type mismatch.
+    if ((input['nullable'] === true || input['x-nullable'] === true) && !types.includes('null')) {
+        types.push('null');
+    }
     const checkers = types
         .map((type) => JS_TYPES[String(type)])
         .filter((fn) => Boolean(fn));

package/dist/functions/unreferenced-reusable-object.d.ts

@@ -4,5 +4,11 @@ export type IUnreferencedReusableObjectOptions = {
     /** JSON pointer to the map of reusable objects, e.g. "#/components/schemas". */
     reusableObjectsLocation: string;
 };
-/** Flags entries in a reusable-object map that nothing `$ref`s. */
+/**
+ * Flags entries in a reusable-object map that nothing `$ref`s.
+ *
+ * This must run against the *unresolved* document: once `$ref`s are inlined by a
+ * resolver there are no references left to count, so every reusable object would
+ * look orphaned.
+ */
 export declare const unreferencedReusableObject: RulesetFunction<Record<string, unknown>, IUnreferencedReusableObjectOptions>;

package/dist/functions/unreferenced-reusable-object.js

@@ -14,7 +14,15 @@ const collectRefs = (node, into) => {
         }
     }
 };
-/** Flags entries in a reusable-object map that nothing `$ref`s. */
+/** Escapes a key for use in a JSON pointer segment (`~` -> `~0`, `/` -> `~1`). */
+const escapePointerSegment = (key) => key.replace(/~/g, '~0').replace(/\//g, '~1');
+/**
+ * Flags entries in a reusable-object map that nothing `$ref`s.
+ *
+ * This must run against the *unresolved* document: once `$ref`s are inlined by a
+ * resolver there are no references left to count, so every reusable object would
+ * look orphaned.
+ */
 export const unreferencedReusableObject = (input, options, context) => {
     if (typeof input !== 'object' || input === null)
         return [];
@@ -25,8 +33,15 @@ export const unreferencedReusableObject = (input, options, context) => {
     collectRefs(context.document.data, refs);
     const results = [];
     for (const key of Object.keys(input)) {
-        const pointer = `${location}/${key}`;
-        if (!refs.has(pointer)) {
+        // A key such as "a/b" appears in a pointer as "a~1b", so escape it before
+        // building the expected reference. Without this a legitimately referenced
+        // object with a special character in its name looks unreferenced.
+        const base = `${location}/${escapePointerSegment(key)}`;
+        // A reference can point straight at the object (`base`) or deeper into it
+        // (e.g. `base/properties/x`); either counts as a use, so match the exact
+        // pointer or any pointer nested beneath it.
+        const referenced = refs.has(base) || [...refs].some((ref) => ref.startsWith(`${base}/`));
+        if (!referenced) {
             results.push({
                 message: 'This reusable object is never referenced',
                 path: [...context.path, key],

package/dist/functions/xor.js

@@ -2,7 +2,14 @@
 export const xor = (input, options) => {
     if (typeof input !== 'object' || input === null)
         return [];
-    const properties = options?.properties ?? [];
+    const properties = options?.properties;
+    // Spectral validates the option schema (an array of at least two strings)
+    // before the function runs and no-ops when it fails, so with fewer than two
+    // properties there is nothing meaningful to check. We deliberately skip in
+    // silence rather than push an error: an empty or single-element list would
+    // otherwise flag every node with a message that names nothing useful.
+    if (!Array.isArray(properties) || properties.length < 2)
+        return [];
     const present = properties.filter((property) => property in input);
     if (present.length !== 1) {
         return [{ message: `Exactly one of ${properties.map((p) => `"${p}"`).join(', ')} must be defined` }];

package/dist/index.js

@@ -71,7 +71,11 @@ const loadFunctionByName = (basePath, dir, name) => {
  * the directory of the ruleset that declared it. YAML/JSON rulesets reference
  * functions by name; JS rulesets can instead pass direct references in `then`.
  */
-const collectCustomFunctions = (definition, basePath, into, seen) => {
+const collectCustomFunctions = (definition, basePath, into, 
+// Keyed by (basePath, reference) for string extends and by object identity for
+// inline ones. `loadRulesetFile` returns a fresh object per read, so object
+// identity alone would never dedupe a file cycle — we key on the resolved edge.
+seen) => {
     if (seen.has(definition))
         return;
     seen.add(definition);
@@ -80,6 +84,10 @@ const collectCustomFunctions = (definition, basePath, into, seen) => {
         for (const entry of entries) {
             const target = Array.isArray(entry) ? entry[0] : entry;
             if (typeof target === 'string') {
+                const key = `${basePath}\0${target}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
                 const resolved = resolveNamedRuleset(target, basePath);
                 collectCustomFunctions(resolved.definition, resolved.basePath, into, seen);
             }

package/dist/parsers/edit-model.d.ts

@@ -5,6 +5,21 @@ import type { JsonPath } from './types.js';
  * paths and values rather than raw character offsets. {@link applyEditOps} lowers
  * each op to a minimal text edit so that untouched parts of the source — including
  * comments, key order, and quoting — keep their original formatting.
+ *
+ * A few edits are deliberately conservative no-ops rather than risky rewrites:
+ *
+ * - Edits that traverse a YAML alias (`*ref`) or a `<<` merge key resolve to a
+ *   node the edit model cannot address structurally, so they are dropped. This is
+ *   safe — the source is left untouched — but it does mean a finding on data that
+ *   only exists via an alias/merge is not auto-fixed.
+ * - `setValue` on an *anchored* node (`&anchor`) rewrites the anchor's own text,
+ *   which every `*alias` to it re-reads; the change therefore propagates to every
+ *   alias use-site. That is the correct YAML semantics, but callers should be
+ *   aware the edit is not local to one path.
+ * - Multi-line *flow* collections (`[\n  a,\n  b\n]`) are rebuilt onto a single
+ *   line by {@link rewriteYamlSeq} and the flow-map insert, and any comments that
+ *   lived between their members are dropped. Block collections keep their layout
+ *   and comments; only flow ones are collapsed.
  */
 export type EditOp = 
 /** Replace the scalar value at `path` (the existing quoting style is preserved). */