@amritk/lint 0.4.7 → 0.5.0

package/dist/ruleset-files.d.ts

@@ -0,0 +1,47 @@
+import type { ResolvedExtend } from './core/index.js';
+import type { FunctionRegistry, RulesetDefinition, RulesetFunction } from './core/types.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;
+};
+/** Enforces {@link IRulesetTrustOptions.restrictTo}, if one was configured, on a resolved file path. */
+export declare const assertWithinRoot: (file: string, restrictTo: string | undefined, what: string) => void;
+/** Loads a ruleset definition from a file path by extension (YAML/JSON parsed, JS/CJS/MJS required). */
+export declare const loadRulesetFile: (file: string) => RulesetDefinition;
+/**
+ * Resolves an `extends` reference that names a file or an npm package:
+ * - local file paths (relative to `basePath`, or absolute): `.yaml` / `.yml` / `.json` / `.js`,
+ * - npm package specifiers (resolved from `basePath`), including subpaths.
+ *
+ * Callers that also recognize named presets (`@amritk/lint/rules/openapi` knows
+ * `oas`) check those first and only fall through to here.
+ */
+export declare const resolveRulesetFile: (name: string, basePath: string, options?: IRulesetTrustOptions) => ResolvedExtend;
+/** Loads a single custom function module (`<dir>/<name>.{js,cjs,mjs}` or a bare path). */
+export declare const loadFunctionByName: (basePath: string, dir: string, name: string, restrictTo: string | undefined) => RulesetFunction;
+/** How {@link collectCustomFunctions} follows a string `extends` target. */
+export type ICollectOptions = IRulesetTrustOptions & {
+    /**
+     * Resolves a string `extends` target to its definition and base directory.
+     * Return `undefined` for a name that is a built-in preset rather than a file —
+     * such a target has no directory of its own to load functions from.
+     */
+    resolveExtend: (name: string, basePath: string) => ResolvedExtend | undefined;
+};
+/**
+ * Walks a ruleset definition (and its string `extends`) collecting custom
+ * functions declared via `functions` / `functionsDir`, each loaded relative to
+ * the directory of the ruleset that declared it. YAML/JSON rulesets reference
+ * functions by name; JS rulesets can instead pass direct references in `then`.
+ */
+export declare const collectCustomFunctions: (definition: RulesetDefinition, basePath: string, into: FunctionRegistry, seen: Set<unknown>, options: ICollectOptions) => void;

package/dist/ruleset-files.js

@@ -0,0 +1,92 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, resolve as resolvePath, sep } from "node:path";
+import { setOwnKey } from "./core/own-key.js";
+import { parseWithPointers } from "./parsers/index.js";
+const require2 = createRequire(import.meta.url);
+const assertWithinRoot = (file, restrictTo, what) => {
+  if (restrictTo === void 0)
+    return;
+  const root = resolvePath(restrictTo);
+  const resolved = resolvePath(file);
+  if (resolved !== root && !resolved.startsWith(root.endsWith(sep) ? root : `${root}${sep}`)) {
+    throw new Error(`${what} "${file}" resolves outside the permitted root ${root}`);
+  }
+};
+const loadRulesetFile = (file) => {
+  if (/\.(ya?ml|json)$/i.test(file)) {
+    return parseWithPointers(readFileSync(file, "utf8")).data;
+  }
+  const module = require2(file);
+  return module.default ?? module;
+};
+const resolveRulesetFile = (name, basePath, options = {}) => {
+  if (name.startsWith(".") || isAbsolute(name)) {
+    const file2 = resolvePath(basePath, name);
+    assertWithinRoot(file2, options.restrictTo, "Extended ruleset");
+    return { definition: loadRulesetFile(file2), basePath: dirname(file2) };
+  }
+  let file;
+  try {
+    file = require2.resolve(name, { paths: [basePath] });
+  } catch {
+    throw new Error(`Cannot resolve extended ruleset "${name}" from ${basePath}`);
+  }
+  assertWithinRoot(file, options.restrictTo, "Extended ruleset");
+  return { definition: loadRulesetFile(file), basePath: dirname(file) };
+};
+const loadFunctionByName = (basePath, dir, name, restrictTo) => {
+  const baseFile = resolvePath(basePath, dir, name);
+  assertWithinRoot(baseFile, restrictTo, "Custom function");
+  for (const candidate of [baseFile, `${baseFile}.js`, `${baseFile}.cjs`, `${baseFile}.mjs`]) {
+    try {
+      const resolvedFile = require2.resolve(candidate);
+      const module = require2(resolvedFile);
+      const fn = module.default ?? module;
+      if (typeof fn !== "function")
+        throw new Error(`"${name}" did not export a function`);
+      return fn;
+    } catch (error) {
+      if (error.code !== "MODULE_NOT_FOUND")
+        throw error;
+    }
+  }
+  throw new Error(`Cannot resolve custom function "${name}" from ${resolvePath(basePath, dir)}`);
+};
+const collectCustomFunctions = (definition, basePath, into, seen, options) => {
+  if (typeof definition !== "object" || definition === null)
+    return;
+  if (seen.has(definition))
+    return;
+  seen.add(definition);
+  if (definition.extends) {
+    const entries = Array.isArray(definition.extends) ? definition.extends : [definition.extends];
+    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 = options.resolveExtend(target, basePath);
+        if (resolved)
+          collectCustomFunctions(resolved.definition, resolved.basePath, into, seen, options);
+      } else {
+        collectCustomFunctions(target, basePath, into, seen, options);
+      }
+    }
+  }
+  if (Array.isArray(definition.functions)) {
+    const dir = definition.functionsDir ?? "functions";
+    for (const name of definition.functions) {
+      setOwnKey(into, name, loadFunctionByName(basePath, dir, name, options.restrictTo));
+    }
+  }
+};
+export {
+  assertWithinRoot,
+  collectCustomFunctions,
+  loadFunctionByName,
+  loadRulesetFile,
+  resolveRulesetFile
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/lint",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "A fast, format-agnostic JSON/YAML style-guide linter with JSON Schema and custom rules.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -60,17 +60,21 @@
     "./rules/openapi": {
       "types": "./dist/rules/openapi/index.d.ts",
       "default": "./dist/rules/openapi/index.js"
+    },
+    "./rules/asyncapi": {
+      "types": "./dist/rules/asyncapi/index.d.ts",
+      "default": "./dist/rules/asyncapi/index.js"
     }
   },
   "dependencies": {
-    "@amritk/runtime-validators": "^0.10.1",
-    "@amritk/yaml": "^0.7.1",
+    "@amritk/runtime-validators": "^0.12.0",
+    "@amritk/yaml": "^0.7.2",
     "jsonc-parser": "^3.3.1"
   },
   "devDependencies": {
-    "@amritk/resolve-refs": "^0.5.1",
+    "@amritk/resolve-refs": "^0.7.1",
     "@stoplight/spectral-core": "^1.23.1",
     "@stoplight/spectral-parsers": "^1.0.5",
-    "@stoplight/spectral-rulesets": "^1.22.6"
+    "@stoplight/spectral-rulesets": "^1.22.7"
   }
 }