@amritk/lint 0.4.2 → 0.4.4

package/dist/core/filter.js

@@ -0,0 +1,206 @@
+import { createBoundedCache } from "./bounded-cache.js";
+import { parseFilterExpression } from "./filter-expression.js";
+const filterRuntimeError = (message) => new Error(message);
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const readMember = (object, name) => {
+  if (object === null || object === void 0) {
+    throw filterRuntimeError(`Cannot read "${name}" of ${object === null ? "null" : "undefined"}`);
+  }
+  if (typeof object === "string") {
+    if (name === "length")
+      return object.length;
+    const index = typeof name === "number" ? name : Number(name);
+    return Number.isInteger(index) ? object[index] : void 0;
+  }
+  if (Array.isArray(object)) {
+    if (name === "length")
+      return object.length;
+    const index = typeof name === "number" ? name : Number(name);
+    return Number.isInteger(index) ? object[index] : void 0;
+  }
+  if (isPlainObject(object))
+    return Object.hasOwn(object, name) ? object[name] : void 0;
+  return void 0;
+};
+const toStringArgument = (value) => {
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number" || typeof value === "boolean" || value === null || value === void 0) {
+    return String(value);
+  }
+  throw filterRuntimeError("Expected a string-like argument");
+};
+const toRegExpArgument = (value) => {
+  if (value instanceof RegExp)
+    return value;
+  if (typeof value === "string")
+    return new RegExp(value);
+  throw filterRuntimeError("Expected a regular expression argument");
+};
+const callMethod = (receiver, name, args) => {
+  const [first] = args;
+  switch (name) {
+    case "indexOf":
+    case "lastIndexOf": {
+      if (typeof receiver === "string") {
+        return name === "indexOf" ? receiver.indexOf(toStringArgument(first)) : receiver.lastIndexOf(toStringArgument(first));
+      }
+      if (Array.isArray(receiver))
+        return name === "indexOf" ? receiver.indexOf(first) : receiver.lastIndexOf(first);
+      throw filterRuntimeError(`"${name}" is not a function`);
+    }
+    case "includes": {
+      if (typeof receiver === "string")
+        return receiver.includes(toStringArgument(first));
+      if (Array.isArray(receiver))
+        return receiver.includes(first);
+      throw filterRuntimeError('"includes" is not a function');
+    }
+    case "startsWith":
+      if (typeof receiver !== "string")
+        throw filterRuntimeError('"startsWith" is not a function');
+      return receiver.startsWith(toStringArgument(first));
+    case "endsWith":
+      if (typeof receiver !== "string")
+        throw filterRuntimeError('"endsWith" is not a function');
+      return receiver.endsWith(toStringArgument(first));
+    case "match":
+      if (typeof receiver !== "string")
+        throw filterRuntimeError('"match" is not a function');
+      return receiver.match(toRegExpArgument(first));
+    case "test": {
+      if (!(receiver instanceof RegExp))
+        throw filterRuntimeError('"test" is not a function');
+      receiver.lastIndex = 0;
+      return receiver.test(toStringArgument(first));
+    }
+    case "toLowerCase":
+      if (typeof receiver !== "string")
+        throw filterRuntimeError('"toLowerCase" is not a function');
+      return receiver.toLowerCase();
+    case "toUpperCase":
+      if (typeof receiver !== "string")
+        throw filterRuntimeError('"toUpperCase" is not a function');
+      return receiver.toUpperCase();
+    case "trim":
+      if (typeof receiver !== "string")
+        throw filterRuntimeError('"trim" is not a function');
+      return receiver.trim();
+    default:
+      throw filterRuntimeError(`"${name}" is not a function`);
+  }
+};
+const looseEquals = (left, right) => {
+  if (left === null || left === void 0)
+    return right === null || right === void 0;
+  if (right === null || right === void 0)
+    return false;
+  if (typeof left === typeof right)
+    return left === right;
+  if (typeof left === "object" || typeof right === "object")
+    return false;
+  return Number(left) === Number(right);
+};
+const compareRelational = (operator, left, right) => {
+  if (typeof left === "string" && typeof right === "string") {
+    switch (operator) {
+      case "<":
+        return left < right;
+      case "<=":
+        return left <= right;
+      case ">":
+        return left > right;
+      default:
+        return left >= right;
+    }
+  }
+  const a = Number(left);
+  const b = Number(right);
+  if (Number.isNaN(a) || Number.isNaN(b))
+    return false;
+  switch (operator) {
+    case "<":
+      return a < b;
+    case "<=":
+      return a <= b;
+    case ">":
+      return a > b;
+    default:
+      return a >= b;
+  }
+};
+const evaluate = (node, context) => {
+  switch (node.kind) {
+    case "literal":
+      return node.value;
+    case "regex":
+      return node.value;
+    case "context":
+      return context[node.ref];
+    case "member":
+      return readMember(evaluate(node.object, context), node.name);
+    case "computed": {
+      const index = evaluate(node.index, context);
+      if (typeof index !== "string" && typeof index !== "number") {
+        throw filterRuntimeError("A computed member must be a string or a number");
+      }
+      return readMember(evaluate(node.object, context), index);
+    }
+    case "call":
+      return callMethod(evaluate(node.object, context), node.name, node.args.map((argument) => evaluate(argument, context)));
+    case "unary": {
+      if (node.operator === "!")
+        return !evaluate(node.operand, context);
+      if (node.operator === "void") {
+        evaluate(node.operand, context);
+        return void 0;
+      }
+      return -Number(evaluate(node.operand, context));
+    }
+    case "logical": {
+      const left = evaluate(node.left, context);
+      if (node.operator === "&&")
+        return left ? evaluate(node.right, context) : left;
+      return left ? left : evaluate(node.right, context);
+    }
+    case "comparison": {
+      const left = evaluate(node.left, context);
+      const right = evaluate(node.right, context);
+      switch (node.operator) {
+        case "===":
+          return left === right;
+        case "!==":
+          return left !== right;
+        case "==":
+          return looseEquals(left, right);
+        case "!=":
+          return !looseEquals(left, right);
+        default:
+          return compareRelational(node.operator, left, right);
+      }
+    }
+  }
+};
+const toFilterFn = (parsed) => {
+  const { node } = parsed;
+  return (value, property, parent, root, path, parentProperty) => {
+    try {
+      return Boolean(evaluate(node, { value, property, parent, parentProperty, path, root }));
+    } catch {
+      return false;
+    }
+  };
+};
+const filterCache = createBoundedCache(500);
+const compileFilter = (source) => {
+  const cached = filterCache.get(source);
+  if (cached)
+    return cached;
+  const parsed = parseFilterExpression(source);
+  const compiled = "error" in parsed ? { error: parsed.error } : { test: toFilterFn(parsed), usesPath: parsed.usesPath };
+  filterCache.set(source, compiled);
+  return compiled;
+};
+export {
+  compileFilter
+};

package/dist/core/index.d.ts

@@ -1,4 +1,6 @@
+export { type BoundedCache, createBoundedCache } from './bounded-cache.js';
 export { createDocument, type Document, type IDocumentOptions } from './document.js';
+export { type CompiledFilter, compileFilter, type FilterFn } from './filter.js';
 export { detectFormats, type Format } from './formats.js';
 export { globToRegExp, matchesGlob } from './glob.js';
 export { type CompiledPath, compileQuery, type IQueryMatch, query, queryCompiled, queryMany } from './jsonpath.js';

package/dist/core/index.js

@@ -1,4 +1,6 @@
+import { createBoundedCache } from "./bounded-cache.js";
 import { createDocument } from "./document.js";
+import { compileFilter } from "./filter.js";
 import { detectFormats } from "./formats.js";
 import { globToRegExp, matchesGlob } from "./glob.js";
 import { compileQuery, query, queryCompiled, queryMany } from "./jsonpath.js";
@@ -9,7 +11,9 @@ import { createRuleset } from "./ruleset.js";
 import { createLinter } from "./runner.js";
 import { validateRuleset } from "./validate-ruleset.js";
 export {
+  compileFilter,
   compileQuery,
+  createBoundedCache,
   createDocument,
   createLinter,
   createRuleset,

package/dist/core/jsonpath.d.ts

@@ -1,10 +1,10 @@
+import { type FilterFn } from './filter.js';
 import type { JsonPath } from './types.js';
 /** A single JSONPath match: the matched value and its concrete path from the root. */
 export type IQueryMatch = {
     value: unknown;
     path: JsonPath;
 };
-type FilterFn = (value: unknown, property: string | number | undefined, parent: unknown, root: unknown, path: string, parentProperty: string | number | undefined) => boolean;
 type Selector = {
     kind: 'child';
     name: string;

package/dist/core/jsonpath.js

@@ -1,3 +1,5 @@
+import { createBoundedCache } from "./bounded-cache.js";
+import { compileFilter } from "./filter.js";
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const normalizeSegment = (segment) => {
   if (typeof segment === "number")
@@ -17,69 +19,7 @@ const pathToJsonPathString = (path) => {
   }
   return out;
 };
-const compileCache = /* @__PURE__ */ new Map();
-const filterCache = /* @__PURE__ */ new Map();
-const substituteContext = (source) => {
-  let out = "";
-  let quote = "";
-  for (let i = 0; i < source.length; i++) {
-    const ch = source[i];
-    if (quote) {
-      out += ch;
-      if (ch === "\\" && i + 1 < source.length) {
-        out += source[i + 1];
-        i++;
-      } else if (ch === quote) {
-        quote = "";
-      }
-      continue;
-    }
-    if (ch === '"' || ch === "'") {
-      quote = ch;
-      out += ch;
-      continue;
-    }
-    if (ch === "@") {
-      const rest = source.slice(i);
-      if (rest.startsWith("@parentProperty")) {
-        out += "_pp";
-        i += "@parentProperty".length - 1;
-      } else if (rest.startsWith("@parent")) {
-        out += "_parent";
-        i += "@parent".length - 1;
-      } else if (rest.startsWith("@property")) {
-        out += "_prop";
-        i += "@property".length - 1;
-      } else if (rest.startsWith("@path")) {
-        out += "_path";
-        i += "@path".length - 1;
-      } else if (rest.startsWith("@root")) {
-        out += "_root";
-        i += "@root".length - 1;
-      } else {
-        out += "_v";
-      }
-      continue;
-    }
-    out += ch;
-  }
-  return out;
-};
-const compileFilter = (source) => {
-  const cached = filterCache.get(source);
-  if (cached)
-    return cached;
-  const body = substituteContext(source);
-  let fn;
-  try {
-    const compiled = new Function("_v", "_prop", "_parent", "_root", "_path", "_pp", `try { return !!(${body}); } catch (_e) { return false; }`);
-    fn = compiled;
-  } catch {
-    fn = () => false;
-  }
-  filterCache.set(source, fn);
-  return fn;
-};
+const compileCache = createBoundedCache(500);
 const splitUnion = (content) => {
   const parts = [];
   let depth = 0;
@@ -168,7 +108,12 @@ const bracketSelector = (content, onError) => {
     const open = trimmed.indexOf("(");
     const close = trimmed.lastIndexOf(")");
     const expr = open !== -1 && close > open ? trimmed.slice(open + 1, close) : trimmed.slice(1);
-    return { kind: "filter", test: compileFilter(expr), source: expr, usesPath: expr.includes("@path") };
+    const filter = compileFilter(expr);
+    if ("error" in filter) {
+      onError(filter.error);
+      return { kind: "none" };
+    }
+    return { kind: "filter", test: filter.test, source: expr, usesPath: filter.usesPath };
   }
   if (trimmed.startsWith("(") && trimmed.endsWith(")")) {
     const inner = trimmed.slice(1, -1).trim();
@@ -451,14 +396,21 @@ const applySelector = (node, selector, root, out) => {
   }
 };
 const walkDescendants = (node, visit) => {
-  visit(node);
-  const value = node.value;
-  if (Array.isArray(value)) {
-    for (let idx = 0; idx < value.length; idx++)
-      walkDescendants({ value: value[idx], parent: node, key: idx }, visit);
-  } else if (isObject(value)) {
-    for (const key of Object.keys(value))
-      walkDescendants({ value: value[key], parent: node, key }, visit);
+  const stack = [node];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    visit(current);
+    const value = current.value;
+    if (Array.isArray(value)) {
+      for (let idx = value.length - 1; idx >= 0; idx--)
+        stack.push({ value: value[idx], parent: current, key: idx });
+    } else if (isObject(value)) {
+      const keys = Object.keys(value);
+      for (let k = keys.length - 1; k >= 0; k--) {
+        const key = keys[k];
+        stack.push({ value: value[key], parent: current, key });
+      }
+    }
   }
 };
 const applySteps = (root, initial, steps) => {

package/dist/functions/alphabetical.js

@@ -1,10 +1,12 @@
 const isRecord = (value) => typeof value === "object" && value !== null;
 const isStringOrNumber = (value) => typeof value === "string" || typeof value === "number";
 const isIntegerLike = (value) => typeof value === "string" && /^(?:0|[1-9]\d*)$/.test(value);
+const DECIMAL_NUMBER = /^-?\d+(?:\.\d+)?$/;
+const isNumeric = (value) => typeof value === "number" || typeof value === "string" && DECIMAL_NUMBER.test(value);
 const compare = (a, b) => {
   if (isIntegerLike(a) && isIntegerLike(b))
     return Math.sign(Number(a) - Number(b));
-  if ((typeof a === "number" || !Number.isNaN(Number(a))) && (typeof b === "number" || !Number.isNaN(Number(b)))) {
+  if (isNumeric(a) && isNumeric(b)) {
     return Math.min(1, Math.max(-1, Number(a) - Number(b)));
   }
   if (typeof a !== "string" || typeof b !== "string")

package/dist/functions/casing.js

@@ -1,25 +1,28 @@
 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}]+|$))*",
+  flat: { body: "[a-z][a-z{d}]*" },
+  camel: { body: "[a-z][a-z{d}]*(?:[A-Z][a-z{d}]+)*", tail: "[A-Z]?" },
+  pascal: { body: "[A-Z][a-z{d}]*(?:[A-Z][a-z{d}]+)*", tail: "[A-Z]?" },
   // 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}]+)*"
+  kebab: { body: "[a-z][a-z{d}]*(?:-[a-z{d}]+)*", separator: "-" },
+  cobol: { body: "[A-Z][A-Z{d}]*(?:-[A-Z{d}]+)*", separator: "-" },
+  snake: { body: "[a-z][a-z{d}]*(?:_[a-z{d}]+)*", separator: "_" },
+  macro: { body: "[A-Z][A-Z{d}]*(?:_[A-Z{d}]+)*", separator: "_" }
 };
 const VALID_TYPES = Object.keys(PATTERNS);
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 const buildRegExp = (options) => {
   const digits = options.disallowDigits ? "" : "0-9";
-  const base = PATTERNS[options.type].replace(/\{d\}/g, digits);
+  const pattern = PATTERNS[options.type];
+  const base = pattern.body.replace(/\{d\}/g, digits);
+  const tail = pattern.tail ?? "";
   if (!options.separator)
-    return new RegExp(`^${base}$`);
+    return new RegExp(`^${base}${tail}$`);
   const sep = escapeRegExp(options.separator.char);
   const leading = options.separator.allowLeading ? `${sep}?` : "";
-  return new RegExp(`^${leading}${base}(?:${sep}${base})*$`);
+  const repeated = options.separator.char === pattern.separator ? "" : `(?:${sep}${base})*`;
+  return new RegExp(`^${leading}${base}${repeated}${tail}$`);
 };
 const casing = (input, options) => {
   if (!options?.type)

package/dist/functions/pattern.js

@@ -1,4 +1,5 @@
-const cache = /* @__PURE__ */ new Map();
+import { createBoundedCache } from "../core/bounded-cache.js";
+const cache = createBoundedCache(500);
 const toRegExp = (pattern2) => {
   const cached = cache.get(pattern2);
   if (cached !== void 0) {

package/dist/index.d.ts

@@ -5,6 +5,20 @@ export { type AliasDefinition, type CompiledPath, compileQuery, createDocument,
 export { type AppliedFix, type ApplyFixesOptions, applyFixes, createFixPlugin, type EditOp, FIX_PLUGIN_NAME, type FixContext, type Fixer, type FixerRegistry, type FixPluginData, type FixResult, type ParserFormat, } from './fix/index.js';
 export { alphabetical, builtinFunctions, type CasingType, casing, defined, enumeration, falsy, type IAlphabeticalOptions, type ICasingOptions, type IOrOptions, type ISchemaOptions, type IUnreferencedReusableObjectOptions, type IXorOptions, length, or, pattern, schema, truthy, typedEnum, undefinedFn, unreferencedReusableObject, xor, } from './functions/index.js';
 export { detectFormat, parseWithPointers } from './parsers/index.js';
+/**
+ * An optional directory that everything a ruleset pulls off disk — `extends`
+ * targets and custom function modules — must resolve inside.
+ *
+ * This is opt-in and off by default, because `basePath` on its own is only a
+ * *resolution origin*: an `extends` of `/etc/thing.js` or `../../../elsewhere`
+ * resolves and loads exactly as written. See the "Trust boundary" section of the
+ * README — a ruleset that can name a `.js` file can run code, restricted root or
+ * not. This narrows *which* files it can name; it is not a sandbox.
+ */
+export type IRulesetTrustOptions = {
+    /** Directory that `extends` files and custom functions must resolve under. */
+    restrictTo?: string;
+};
 /**
  * Resolves an `extends` reference to a ruleset definition. Supports:
  * - local file paths (relative to `basePath`, or absolute): `.yaml` / `.yml` / `.json` / `.js`,
@@ -12,22 +26,40 @@ export { detectFormat, parseWithPointers } from './parsers/index.js';
  *
  * The engine ships no named built-in rulesets, so every string `extends` target
  * is a file path or an npm package.
+ *
+ * Note what this does *not* do by default: `basePath` is where resolution starts,
+ * not a boundary. An absolute path or a `../`-escaping one is followed, and a
+ * `.js` target is `require`d — meaning it runs. Pass `restrictTo` to confine
+ * resolution to one directory tree when the ruleset is not fully trusted.
  */
-export declare const resolveNamedRuleset: (name: string, basePath?: string) => ResolvedExtend;
+export declare const resolveNamedRuleset: (name: string, basePath?: string, options?: IRulesetTrustOptions) => 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).
+ *
+ * The result is memoized per `(definition object, basePath, restrictTo)` triple,
+ * so linting many documents against the same definition builds it once. Treat a
+ * definition you have passed in as frozen: mutating it afterwards will not
+ * rebuild the ruleset. Pass a fresh object (or a shallow copy) when you genuinely
+ * want a rebuild — for example after a ruleset file on disk has changed.
  */
-export declare const createRuleset: (definition?: RulesetDefinition, basePath?: string) => Ruleset;
+export declare const createRuleset: (definition?: RulesetDefinition, basePath?: string, options?: IRulesetTrustOptions) => 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;
+    /**
+     * Optional root that every file the ruleset pulls in (`extends` targets,
+     * custom functions) must resolve under. Off by default — `rulesetBasePath` is
+     * only where resolution starts, not a boundary. See the README's "Trust
+     * boundary" section for what this does and does not protect against.
+     */
+    restrictTo?: string;
     /**
      * Produces the resolved (`$ref`-dereferenced) tree for rules with
      * `resolved: true`. The engine ships no resolver; pass one (for example
@@ -87,10 +119,24 @@ export type IFixResult = {
     output: string;
     /** Whether any fix changed the document. */
     fixed: boolean;
-    /** The findings that were repaired, across every fix pass. */
+    /**
+     * The findings that were repaired, de-duplicated by rule code and path. Two
+     * fixers that undo each other would otherwise report the same finding once per
+     * pass, and a `--fix` summary would claim to have fixed eleven problems when
+     * there was only ever one.
+     */
     applied: AppliedFix[];
     /** Findings that remain after fixing, re-linted against the fixed document. */
     remaining: IDiagnostic[];
+    /**
+     * Whether the document stopped changing on its own. `false` means the loop hit
+     * {@link MAX_FIX_PASSES} while the document was still changing — usually two
+     * fixers undoing each other — and `output` is simply wherever it happened to
+     * stop. A caller reporting results should say so rather than claim success.
+     */
+    converged: boolean;
+    /** How many passes actually changed the document. */
+    passes: number;
 };
 /**
  * Lints a document and applies the supplied `fixers` repeatedly until the