@amritk/lint 0.0.0 → 0.2.0

package/dist/fix/types.d.ts

@@ -0,0 +1,39 @@
+import type { IDiagnostic, JsonPath } from '../core/index.js';
+import type { EditOp, ParserFormat } from '../parsers/index.js';
+export type { EditOp, ParserFormat };
+/** What a {@link Fixer} is handed for a single finding it might repair. */
+export type FixContext = {
+    /** The finding to fix. */
+    diagnostic: IDiagnostic;
+    /** The parsed, *unresolved* document data — fixers read the real node to derive the edit. */
+    data: unknown;
+    /** The document's format, in case a fixer needs to vary its output. */
+    format: ParserFormat;
+};
+/**
+ * A repair for the findings of one rule. `fix` inspects the finding (and the
+ * underlying data) and returns the structural edit(s) that resolve it, or
+ * `undefined` if it can't. `safe` marks whether the fix is semantics-preserving
+ * enough to apply automatically; `lint --fix` applies safe fixes only.
+ */
+export type Fixer = {
+    /** Defaults to `true`. Set `false` for fixes that may change behavior (opt-in only). */
+    safe?: boolean;
+    fix: (context: FixContext) => EditOp[] | EditOp | undefined;
+};
+/** Fixers keyed by the rule `code` whose findings they repair. */
+export type FixerRegistry = Record<string, Fixer>;
+/** A finding that a fixer produced edits for. */
+export type AppliedFix = {
+    code: string | number;
+    path: JsonPath;
+};
+/** The outcome of {@link applyFixes}. */
+export type FixResult = {
+    /** The rewritten document text (identical to the input when nothing applied). */
+    output: string;
+    /** The findings that were repaired. */
+    applied: AppliedFix[];
+    /** Whether `output` differs from the input. */
+    changed: boolean;
+};

package/dist/functions/alphabetical.d.ts

@@ -0,0 +1,8 @@
+import type { RulesetFunction } from '../core/index.js';
+/** Options for {@link alphabetical}. */
+export type IAlphabeticalOptions = {
+    /** Compare objects by this property instead of the value itself. */
+    keyedBy?: string;
+};
+/** Flags array items or object keys that are not in ascending (optionally `keyedBy`) order. */
+export declare const alphabetical: RulesetFunction<unknown, IAlphabeticalOptions>;

package/dist/functions/alphabetical.js

@@ -0,0 +1,28 @@
+const compare = (a, b) => {
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    return String(a).localeCompare(String(b));
+};
+/** Flags array items or object keys that are not in ascending (optionally `keyedBy`) order. */
+export const alphabetical = (input, options, context) => {
+    if (typeof input !== 'object' || input === null)
+        return [];
+    const isArray = Array.isArray(input);
+    const items = isArray ? input : Object.keys(input);
+    const keyedBy = options?.keyedBy;
+    const results = [];
+    for (let i = 0; i < items.length - 1; i++) {
+        let current = items[i];
+        let next = items[i + 1];
+        if (keyedBy) {
+            current = isRecord(current) ? current[keyedBy] : current;
+            next = isRecord(next) ? next[keyedBy] : next;
+        }
+        if (compare(current, next) > 0) {
+            const path = isArray ? [...context.path, i + 1] : [...context.path, items[i + 1]];
+            results.push({ message: 'The items must be in alphabetical order', path });
+        }
+    }
+    return results;
+};
+const isRecord = (value) => typeof value === 'object' && value !== null;

package/dist/functions/casing.d.ts

@@ -0,0 +1,14 @@
+import type { RulesetFunction } from '../core/index.js';
+/** The supported casing styles a value can be checked against. */
+export type CasingType = 'flat' | 'camel' | 'pascal' | 'kebab' | 'cobol' | 'snake' | 'macro';
+/** Options for {@link casing}. */
+export type ICasingOptions = {
+    type: CasingType;
+    disallowDigits?: boolean;
+    separator?: {
+        char: string;
+        allowLeading?: boolean;
+    };
+};
+/** Flags a string that does not match the configured casing style. */
+export declare const casing: RulesetFunction<string, ICasingOptions>;

package/dist/functions/casing.js

@@ -0,0 +1,30 @@
+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}]*)*',
+};
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const buildRegExp = (options) => {
+    const digits = options.disallowDigits ? '' : '0-9';
+    const base = PATTERNS[options.type].replace(/\{d\}/g, digits);
+    if (!options.separator)
+        return new RegExp(`^${base}$`);
+    const sep = escapeRegExp(options.separator.char);
+    const leading = options.separator.allowLeading ? `${sep}?` : '';
+    return new RegExp(`^${leading}${base}(?:${sep}${base})*$`);
+};
+/** Flags a string that does not match the configured casing style. */
+export const casing = (input, options) => {
+    if (typeof input !== 'string' || input.length === 0)
+        return [];
+    if (!options?.type)
+        return [];
+    if (!buildRegExp(options).test(input)) {
+        return [{ message: `The value must be in ${options.type} case` }];
+    }
+    return [];
+};

package/dist/functions/defined.d.ts

@@ -0,0 +1,3 @@
+import type { RulesetFunction } from '../core/index.js';
+/** Flags a value that is `undefined`. */
+export declare const defined: RulesetFunction;

package/dist/functions/defined.js

@@ -0,0 +1,6 @@
+/** Flags a value that is `undefined`. */
+export const defined = (input) => {
+    if (input === undefined)
+        return [{ message: 'The value must be defined' }];
+    return [];
+};

package/dist/functions/enumeration.d.ts

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

package/dist/functions/enumeration.js

@@ -0,0 +1,10 @@
+/** Flags a value that is not one of the allowed `values`. */
+export const enumeration = (input, options) => {
+    const values = options?.values ?? [];
+    if (!values.includes(input)) {
+        return [
+            { message: `The value must be one of the allowed values: ${values.map((v) => JSON.stringify(v)).join(', ')}` },
+        ];
+    }
+    return [];
+};

package/dist/functions/falsy.d.ts

@@ -0,0 +1,3 @@
+import type { RulesetFunction } from '../core/index.js';
+/** Flags a value that is not falsy. */
+export declare const falsy: RulesetFunction;

package/dist/functions/falsy.js

@@ -0,0 +1,6 @@
+/** Flags a value that is not falsy. */
+export const falsy = (input) => {
+    if (input)
+        return [{ message: 'The value must be falsy' }];
+    return [];
+};

package/dist/functions/index.d.ts

@@ -0,0 +1,16 @@
+import type { FunctionRegistry } from '../core/index.js';
+export { alphabetical, type IAlphabeticalOptions } from './alphabetical.js';
+export { type CasingType, casing, type ICasingOptions } from './casing.js';
+export { defined } from './defined.js';
+export { enumeration } from './enumeration.js';
+export { falsy } from './falsy.js';
+export { length } from './length.js';
+export { pattern } from './pattern.js';
+export { type ISchemaOptions, schema } from './schema.js';
+export { truthy } from './truthy.js';
+export { typedEnum } from './typed-enum.js';
+export { undefinedFn } from './undefined.js';
+export { type IUnreferencedReusableObjectOptions, unreferencedReusableObject } from './unreferenced-reusable-object.js';
+export { type IXorOptions, xor } from './xor.js';
+/** All built-in functions, keyed by their Linter-compatible names. */
+export declare const builtinFunctions: FunctionRegistry;

package/dist/functions/index.js

@@ -0,0 +1,42 @@
+import { alphabetical } from './alphabetical.js';
+import { casing } from './casing.js';
+import { defined } from './defined.js';
+import { enumeration } from './enumeration.js';
+import { falsy } from './falsy.js';
+import { length } from './length.js';
+import { pattern } from './pattern.js';
+import { schema } from './schema.js';
+import { truthy } from './truthy.js';
+import { typedEnum } from './typed-enum.js';
+import { undefinedFn } from './undefined.js';
+import { unreferencedReusableObject } from './unreferenced-reusable-object.js';
+import { xor } from './xor.js';
+export { alphabetical } from './alphabetical.js';
+export { casing } from './casing.js';
+export { defined } from './defined.js';
+export { enumeration } from './enumeration.js';
+export { falsy } from './falsy.js';
+export { length } from './length.js';
+export { pattern } from './pattern.js';
+export { schema } from './schema.js';
+export { truthy } from './truthy.js';
+export { typedEnum } from './typed-enum.js';
+export { undefinedFn } from './undefined.js';
+export { unreferencedReusableObject } from './unreferenced-reusable-object.js';
+export { xor } from './xor.js';
+/** All built-in functions, keyed by their Linter-compatible names. */
+export const builtinFunctions = {
+    alphabetical: alphabetical,
+    casing: casing,
+    defined,
+    enumeration: enumeration,
+    falsy,
+    length: length,
+    pattern: pattern,
+    schema: schema,
+    truthy,
+    undefined: undefinedFn,
+    unreferencedReusableObject: unreferencedReusableObject,
+    xor: xor,
+    typedEnum: typedEnum,
+};

package/dist/functions/length.d.ts

@@ -0,0 +1,6 @@
+import type { RulesetFunction } from '../core/index.js';
+/** Flags a value whose size falls outside the `min`/`max` bounds. */
+export declare const length: RulesetFunction<unknown, {
+    min?: number;
+    max?: number;
+}>;

package/dist/functions/length.js

@@ -0,0 +1,27 @@
+/**
+ * Returns the comparable size of a value: string/array length, object key count,
+ * or the number itself. `undefined` for anything else (so the rule is skipped).
+ */
+const measure = (input) => {
+    if (typeof input === 'string' || Array.isArray(input))
+        return input.length;
+    if (typeof input === 'object' && input !== null)
+        return Object.keys(input).length;
+    if (typeof input === 'number')
+        return input;
+    return undefined;
+};
+/** Flags a value whose size falls outside the `min`/`max` bounds. */
+export const length = (input, options) => {
+    const size = measure(input);
+    if (size === undefined)
+        return [];
+    const results = [];
+    if (options?.min !== undefined && size < options.min) {
+        results.push({ message: `The value must not be shorter than ${options.min}` });
+    }
+    if (options?.max !== undefined && size > options.max) {
+        results.push({ message: `The value must not be longer than ${options.max}` });
+    }
+    return results;
+};

package/dist/functions/pattern.d.ts

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

package/dist/functions/pattern.js

@@ -0,0 +1,20 @@
+/** Parses a `/pattern/flags` string (or a bare pattern) into a RegExp. */
+const toRegExp = (pattern) => {
+    const match = /^\/(.+)\/([a-z]*)$/s.exec(pattern);
+    if (match)
+        return new RegExp(match[1], match[2]);
+    return new RegExp(pattern);
+};
+/** 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?.notMatch !== undefined && toRegExp(options.notMatch).test(input)) {
+        results.push({ message: `The value must not match the pattern "${options.notMatch}"` });
+    }
+    return results;
+};

package/dist/functions/schema.d.ts

@@ -0,0 +1,8 @@
+import type { RulesetFunction } from '../core/index.js';
+/** Options for {@link schema}. */
+export type ISchemaOptions = {
+    schema: object;
+    allErrors?: boolean;
+};
+/** 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

@@ -0,0 +1,36 @@
+import { validate as buildValidator } from '@amritk/runtime-validators';
+// The rule's `options.schema` is a stable object, so cache the prepared
+// validator by identity. `@amritk/runtime-validators` interprets the schema at
+// runtime (no `new Function`), keeping this eval-free and dependency-light.
+const validators = new WeakMap();
+const getValidator = (schema) => {
+    let validator = validators.get(schema);
+    if (!validator) {
+        // The `schema` built-in historically enforced string formats (ajv
+        // `validateFormats: true`); keep that by opting into all formats here.
+        validator = buildValidator(schema, { formats: 'all' });
+        validators.set(schema, validator);
+    }
+    return validator;
+};
+const pointerToPath = (pointer) => pointer
+    .split('/')
+    .slice(1)
+    .map((segment) => segment.replace(/~1/g, '/').replace(/~0/g, '~'))
+    .map((segment) => (/^\d+$/.test(segment) ? Number(segment) : segment));
+const formatError = (error) => {
+    const location = error.path || 'value';
+    return `${location} ${error.message}`.trim();
+};
+/** Validates a value against a JSON Schema supplied in the rule's options. */
+export const schema = (input, options, context) => {
+    if (!options?.schema)
+        return [];
+    const result = getValidator(options.schema)(input);
+    if (result === true)
+        return [];
+    return result.errors.map((error) => ({
+        message: formatError(error),
+        path: [...context.path, ...pointerToPath(error.path)],
+    }));
+};

package/dist/functions/truthy.d.ts

@@ -0,0 +1,3 @@
+import type { RulesetFunction } from '../core/index.js';
+/** Flags a value that is not truthy. */
+export declare const truthy: RulesetFunction;

package/dist/functions/truthy.js

@@ -0,0 +1,6 @@
+/** Flags a value that is not truthy. */
+export const truthy = (input) => {
+    if (!input)
+        return [{ message: 'The value must be truthy' }];
+    return [];
+};

package/dist/functions/typed-enum.d.ts

@@ -0,0 +1,3 @@
+import type { RulesetFunction } from '../core/index.js';
+/** Validates that each `enum` entry matches the schema's declared `type`. */
+export declare const typedEnum: RulesetFunction<Record<string, unknown>, never>;

package/dist/functions/typed-enum.js

@@ -0,0 +1,34 @@
+const JS_TYPES = {
+    string: (v) => typeof v === 'string',
+    number: (v) => typeof v === 'number',
+    integer: (v) => typeof v === 'number' && Number.isInteger(v),
+    boolean: (v) => typeof v === 'boolean',
+    null: (v) => v === null,
+    array: (v) => Array.isArray(v),
+    object: (v) => typeof v === 'object' && v !== null && !Array.isArray(v),
+};
+/** Validates that each `enum` entry matches the schema's declared `type`. */
+export const typedEnum = (input, _options, context) => {
+    if (typeof input !== 'object' || input === null)
+        return [];
+    const declaredType = input['type'];
+    const values = input['enum'];
+    if (declaredType === undefined || !Array.isArray(values))
+        return [];
+    const types = Array.isArray(declaredType) ? declaredType : [declaredType];
+    const checkers = types
+        .map((type) => JS_TYPES[String(type)])
+        .filter((fn) => Boolean(fn));
+    if (checkers.length === 0)
+        return [];
+    const results = [];
+    values.forEach((value, index) => {
+        if (!checkers.some((check) => check(value))) {
+            results.push({
+                message: `Enum value \`${JSON.stringify(value)}\` must be of type "${types.join(' | ')}"`,
+                path: [...context.path, 'enum', index],
+            });
+        }
+    });
+    return results;
+};

package/dist/functions/undefined.d.ts

@@ -0,0 +1,6 @@
+import type { RulesetFunction } from '../core/index.js';
+/**
+ * Flags a value that is defined. Exported as `undefinedFn` because `undefined`
+ * is a reserved identifier; it is registered under the name `undefined`.
+ */
+export declare const undefinedFn: RulesetFunction;

package/dist/functions/undefined.js

@@ -0,0 +1,9 @@
+/**
+ * Flags a value that is defined. Exported as `undefinedFn` because `undefined`
+ * is a reserved identifier; it is registered under the name `undefined`.
+ */
+export const undefinedFn = (input) => {
+    if (input !== undefined)
+        return [{ message: 'The value must be undefined' }];
+    return [];
+};

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

@@ -0,0 +1,8 @@
+import type { RulesetFunction } from '../core/index.js';
+/** Options for {@link unreferencedReusableObject}. */
+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. */
+export declare const unreferencedReusableObject: RulesetFunction<Record<string, unknown>, IUnreferencedReusableObjectOptions>;

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

@@ -0,0 +1,37 @@
+/** Collects every `$ref` string anywhere in `node` into `into`. */
+const collectRefs = (node, into) => {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectRefs(item, into);
+        return;
+    }
+    if (typeof node === 'object' && node !== null) {
+        for (const [key, value] of Object.entries(node)) {
+            if (key === '$ref' && typeof value === 'string')
+                into.add(value);
+            else
+                collectRefs(value, into);
+        }
+    }
+};
+/** Flags entries in a reusable-object map that nothing `$ref`s. */
+export const unreferencedReusableObject = (input, options, context) => {
+    if (typeof input !== 'object' || input === null)
+        return [];
+    const location = options?.reusableObjectsLocation;
+    if (!location)
+        return [];
+    const refs = new Set();
+    collectRefs(context.document.data, refs);
+    const results = [];
+    for (const key of Object.keys(input)) {
+        const pointer = `${location}/${key}`;
+        if (!refs.has(pointer)) {
+            results.push({
+                message: 'This reusable object is never referenced',
+                path: [...context.path, key],
+            });
+        }
+    }
+    return results;
+};

package/dist/functions/xor.d.ts

@@ -0,0 +1,7 @@
+import type { RulesetFunction } from '../core/index.js';
+/** Options for {@link xor}. */
+export type IXorOptions = {
+    properties: string[];
+};
+/** Flags an object unless exactly one of the listed `properties` is present. */
+export declare const xor: RulesetFunction<Record<string, unknown>, IXorOptions>;

package/dist/functions/xor.js

@@ -0,0 +1,11 @@
+/** Flags an object unless exactly one of the listed `properties` is present. */
+export const xor = (input, options) => {
+    if (typeof input !== 'object' || input === null)
+        return [];
+    const properties = options?.properties ?? [];
+    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` }];
+    }
+    return [];
+};

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import { type IDiagnostic, type IDocumentOptions, type LintPlugin, type LintResolver, type ResolvedExtend, type Ruleset, type RulesetDefinition } from './core/index.js';
+import { type AppliedFix, type FixerRegistry } from './fix/index.js';
+export * from './core/index.js';
+export * from './fix/index.js';
+export * from './functions/index.js';
+export { detectFormat, parseWithPointers } from './parsers/index.js';
+/**
+ * Resolves an `extends` reference to a ruleset definition. Supports:
+ * - local file paths (relative to `basePath`, or absolute): `.yaml` / `.yml` / `.json` / `.js`,
+ * - npm package specifiers (resolved from `basePath`), including subpaths.
+ *
+ * The engine ships no named built-in rulesets, so every string `extends` target
+ * is a file path or an npm package.
+ */
+export declare const resolveNamedRuleset: (name: string, basePath?: string) => ResolvedExtend;
+/**
+ * Builds a runnable {@link Ruleset} from a ruleset definition, layering the
+ * built-in functions (plus any custom ones the definition declares via
+ * `functions` / `functionsDir`) over the core engine and wiring up `extends`
+ * resolution against files and npm packages. With no definition it produces an
+ * empty ruleset (no rules run).
+ */
+export declare const createRuleset: (definition?: RulesetDefinition, basePath?: string) => Ruleset;
+/** Options for {@link lintDocument}: the document options plus ruleset controls. */
+export type ILintOptions = IDocumentOptions & {
+    /** The ruleset definition to evaluate. When omitted, no rules run. */
+    ruleset?: RulesetDefinition;
+    /** Directory that the ruleset's string `extends` references resolve relative to. */
+    rulesetBasePath?: string;
+    /**
+     * Produces the resolved (`$ref`-dereferenced) tree for rules with
+     * `resolved: true`. The engine ships no resolver; pass one (for example
+     * wrapping `@amritk/resolve-refs`) to enable `$ref` dereferencing. When
+     * omitted, rules see the raw parsed document.
+     */
+    resolve?: LintResolver;
+    /**
+     * Plugins run after the rule pass. Use {@link lintDocumentWithResult} (not
+     * {@link lintDocument}) to read what they return — e.g. the auto-fix plugin's
+     * rewritten `output`.
+     */
+    plugins?: LintPlugin[];
+};
+/** The full result of a lint run: findings plus anything the plugins produced. */
+export type ILintResult = {
+    diagnostics: IDiagnostic[];
+    /** A rewritten document, when a plugin (e.g. auto-fix) produced one. */
+    output?: string;
+    /** Per-plugin structured output, keyed by plugin name. */
+    pluginData: Record<string, unknown>;
+};
+/**
+ * Lints a JSON/YAML `input` end to end: parses with source maps and applies the
+ * ruleset. Returns just the findings; use {@link lintDocumentWithResult} for the
+ * full result.
+ */
+export declare const lintDocument: (input: string, options?: ILintOptions) => Promise<IDiagnostic[]>;
+/**
+ * Like {@link lintDocument}, but returns the full {@link ILintResult} — including
+ * anything the configured `plugins` produced (e.g. the auto-fix plugin's
+ * rewritten `output`).
+ */
+export declare const lintDocumentWithResult: (input: string, options?: ILintOptions) => Promise<ILintResult>;
+/** Options for {@link fixDocument}: the lint options plus auto-fix controls. */
+export type IFixOptions = Omit<ILintOptions, 'plugins'> & {
+    /** The fixers to apply, keyed by rule code. Defaults to an empty registry (no fixes). */
+    fixers?: FixerRegistry;
+    /** When false, also apply fixers marked `safe: false`. Defaults to true. */
+    safeOnly?: boolean;
+};
+/** The result of {@link fixDocument}. */
+export type IFixResult = {
+    /** The fixed document text (identical to the input when nothing was fixed). */
+    output: string;
+    /** Whether any fix changed the document. */
+    fixed: boolean;
+    /** The findings that were repaired, across every fix pass. */
+    applied: AppliedFix[];
+    /** Findings that remain after fixing, re-linted against the fixed document. */
+    remaining: IDiagnostic[];
+};
+/**
+ * Lints a document and applies the supplied `fixers` repeatedly until the
+ * document stops changing (or {@link MAX_FIX_PASSES} is reached), then re-lints
+ * so `remaining` reflects the fixed document. A one-call convenience over
+ * {@link lintDocumentWithResult} + `createFixPlugin`. With no `fixers` this is a
+ * no-op that just returns the findings.
+ */
+export declare const fixDocument: (input: string, options?: IFixOptions) => Promise<IFixResult>;