@amritk/lint 0.3.2 → 0.4.0

package/AI.md

@@ -0,0 +1,55 @@
+# @amritk/lint — notes for AI coding agents
+
+A fast, format-agnostic JSON/YAML style-guide linter: JSON Schema validation
+plus custom rules, emitting findings with exact `line:column` ranges. Full
+reference is [README.md](./README.md).
+
+> Pre-alpha: APIs change in **minor** versions.
+
+## Minimal example
+
+```ts
+import { lintDocument } from '@amritk/lint'
+
+const ruleset = {
+  rules: {
+    'require-name': { given: '$', severity: 'error', then: { field: 'name', function: 'truthy' } },
+  },
+}
+
+const findings = await lintDocument('version: 1\n', { ruleset, source: 'service.yaml' })
+```
+
+## Gotchas — where agents fail
+
+1. **Two `severity` vocabularies.** In a **ruleset** you author strings
+   (`'error' | 'warn' | 'info' | 'hint' | 'off'`). In a **finding** `severity`
+   is **numeric** (`0` error, `1` warn, `2` info, `3` hint). Don't cross them.
+2. **Ranges are zero-based** (`{ line, character }` from 0). Add 1 to both to
+   print `file:line:col`.
+3. **The engine ships no resolver, no built-in ruleset, no fixers.** `$ref`s are
+   only dereferenced if you pass a `resolve` hook (e.g. wrapping
+   `@amritk/resolve-refs`); `fixDocument` is a no-op until you supply a
+   `FixerRegistry`; `createRuleset()` with no argument runs zero rules.
+4. **`extends` targets are file paths or npm packages only** — there are no
+   named built-in rulesets in core. String `extends` resolve relative to
+   `rulesetBasePath` (or the ruleset file's own directory).
+5. **OpenAPI support is a separate subpath**, `@amritk/lint/rules/openapi`
+   (`createOpenApiRuleset`, `oas`, `oasFixers`, …) — not the package root.
+
+## Exports
+
+- `lintDocument(input, options?)` → findings only.
+- `lintDocumentWithResult(input, options?)` → `{ diagnostics, output?, pluginData }`.
+- `fixDocument(input, options?)` → `{ output, fixed, applied, remaining }` (needs `fixers`).
+- `createRuleset(def?, basePath?)`, `resolveNamedRuleset(name, basePath?)`,
+  `builtinFunctions` (`alphabetical`, `casing`, `truthy`, `pattern`, `schema`, …).
+
+## Subpaths
+
+| Import | Purpose |
+|---|---|
+| `@amritk/lint` | core engine, `lintDocument`/`fixDocument`, built-in functions |
+| `@amritk/lint/rules/openapi` | ready-made OpenAPI preset (`createOpenApiRuleset`, `oas`) |
+
+Install: `bun add @amritk/lint`.

package/dist/core/document.js

@@ -1,11 +1,13 @@
-import { parseWithPointers, } from '../parsers/index.js';
-/** Parses `input` into a {@link Document} with a source map for position lookups. */
-export const createDocument = (input, options = {}) => {
-    const parsed = parseWithPointers(input, options);
-    return {
-        source: options.source,
-        data: parsed.data,
-        diagnostics: parsed.diagnostics,
-        getLocationForJsonPath: (path, closest = false) => parsed.getLocationForJsonPath(path, closest),
-    };
+import { parseWithPointers } from "../parsers/index.js";
+const createDocument = (input, options = {}) => {
+  const parsed = parseWithPointers(input, options);
+  return {
+    source: options.source,
+    data: parsed.data,
+    diagnostics: parsed.diagnostics,
+    getLocationForJsonPath: (path, closest = false) => parsed.getLocationForJsonPath(path, closest)
+  };
+};
+export {
+  createDocument
 };

package/dist/core/formats.js

@@ -1,14 +1,11 @@
-/**
- * Returns the set of registered format names that match the document. The
- * `formats` registry is supplied by the caller (a preset provides its own
- * format detectors); the engine itself is format-agnostic, so the
- * default registry is empty and rules with no `formats` gate run regardless.
- */
-export const detectFormats = (document, formats = {}) => {
-    const matched = new Set();
-    for (const [name, detector] of Object.entries(formats)) {
-        if (detector(document))
-            matched.add(name);
-    }
-    return matched;
+const detectFormats = (document, formats = {}) => {
+  const matched = /* @__PURE__ */ new Set();
+  for (const [name, detector] of Object.entries(formats)) {
+    if (detector(document))
+      matched.add(name);
+  }
+  return matched;
+};
+export {
+  detectFormats
 };

package/dist/core/glob.js

@@ -1,132 +1,110 @@
-/**
- * Minimal glob → RegExp for matching override `files` patterns against document
- * paths. Supports `**` (any path segments), `*` (within a segment), `?`, and
- * brace expansion (`{a,b}`).
- */
 const REGEXP_SPECIAL = /[\\^$.*+?()[\]{}|/]/;
-/** Splits brace-group content on top-level commas (commas nested in inner braces stay put). */
 const splitTopLevel = (body) => {
-    const parts = [];
-    let depth = 0;
-    let current = '';
-    for (const ch of body) {
-        if (ch === '{')
-            depth++;
-        else if (ch === '}')
-            depth--;
-        if (ch === ',' && depth === 0) {
-            parts.push(current);
-            current = '';
-            continue;
-        }
-        current += ch;
+  const parts = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of body) {
+    if (ch === "{")
+      depth++;
+    else if (ch === "}")
+      depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+      continue;
     }
-    parts.push(current);
-    return parts;
+    current += ch;
+  }
+  parts.push(current);
+  return parts;
 };
-/**
- * Expands brace alternations (`a.{yaml,yml}` → `a.yaml`, `a.yml`) into concrete
- * globs, cartesian across multiple groups. A group with no top-level comma is
- * left literal (mirroring minimatch), so `{}` in a path does not vanish.
- */
 const expandBraces = (glob) => {
-    const open = glob.indexOf('{');
-    if (open === -1)
-        return [glob];
-    let depth = 0;
-    let close = -1;
-    for (let i = open; i < glob.length; i++) {
-        if (glob[i] === '{')
-            depth++;
-        else if (glob[i] === '}') {
-            depth--;
-            if (depth === 0) {
-                close = i;
-                break;
-            }
-        }
+  const open = glob.indexOf("{");
+  if (open === -1)
+    return [glob];
+  let depth = 0;
+  let close = -1;
+  for (let i = open; i < glob.length; i++) {
+    if (glob[i] === "{")
+      depth++;
+    else if (glob[i] === "}") {
+      depth--;
+      if (depth === 0) {
+        close = i;
+        break;
+      }
     }
-    if (close === -1)
-        return [glob];
-    const prefix = glob.slice(0, open);
-    const body = glob.slice(open + 1, close);
-    const suffix = glob.slice(close + 1);
-    const options = splitTopLevel(body);
-    if (options.length === 1) {
-        // No alternation — keep the braces as literal characters.
-        return expandBraces(suffix).map((rest) => `${prefix}{${body}}${rest}`);
+  }
+  if (close === -1)
+    return [glob];
+  const prefix = glob.slice(0, open);
+  const body = glob.slice(open + 1, close);
+  const suffix = glob.slice(close + 1);
+  const options = splitTopLevel(body);
+  if (options.length === 1) {
+    return expandBraces(suffix).map((rest) => `${prefix}{${body}}${rest}`);
+  }
+  const results = [];
+  for (const option of options) {
+    for (const expandedOption of expandBraces(option)) {
+      for (const expandedSuffix of expandBraces(suffix)) {
+        results.push(prefix + expandedOption + expandedSuffix);
+      }
     }
-    const results = [];
-    for (const option of options) {
-        for (const expandedOption of expandBraces(option)) {
-            for (const expandedSuffix of expandBraces(suffix)) {
-                results.push(prefix + expandedOption + expandedSuffix);
-            }
-        }
-    }
-    return results;
+  }
+  return results;
 };
-/** Compiles a single (brace-free) glob into an un-anchored RegExp source. */
 const globInnerSource = (glob) => {
-    let source = '';
-    for (let i = 0; i < glob.length; i++) {
-        const char = glob[i];
-        if (char === '*') {
-            if (glob[i + 1] === '*') {
-                i++;
-                if (glob[i + 1] === '/') {
-                    i++;
-                    source += '(?:.*/)?';
-                }
-                else {
-                    source += '.*';
-                }
-            }
-            else {
-                source += '[^/]*';
-            }
-        }
-        else if (char === '?') {
-            source += '[^/]';
-        }
-        else if (char && REGEXP_SPECIAL.test(char)) {
-            source += `\\${char}`;
-        }
-        else {
-            source += char;
+  let source = "";
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i];
+    if (char === "*") {
+      if (glob[i + 1] === "*") {
+        i++;
+        if (glob[i + 1] === "/") {
+          i++;
+          source += "(?:.*/)?";
+        } else {
+          source += ".*";
         }
+      } else {
+        source += "[^/]*";
+      }
+    } else if (char === "?") {
+      source += "[^/]";
+    } else if (char && REGEXP_SPECIAL.test(char)) {
+      source += `\\${char}`;
+    } else {
+      source += char;
     }
-    return source;
+  }
+  return source;
 };
-// Compiled patterns are cached by their glob string; the ruleset's override
-// globs are re-tested against every linted source, so compiling once matters.
-const regexCache = new Map();
-/** Compiles a glob pattern (`**`, `*`, `?`, `{a,b}`) into an anchored RegExp, cached by string. */
-export const globToRegExp = (glob) => {
-    const cached = regexCache.get(glob);
-    if (cached)
-        return cached;
-    const alternatives = expandBraces(glob).map(globInnerSource);
-    const regex = new RegExp(`^(?:${alternatives.join('|')})$`);
-    regexCache.set(glob, regex);
-    return regex;
+const regexCache = /* @__PURE__ */ new Map();
+const globToRegExp = (glob) => {
+  const cached = regexCache.get(glob);
+  if (cached)
+    return cached;
+  const alternatives = expandBraces(glob).map(globInnerSource);
+  const regex = new RegExp(`^(?:${alternatives.join("|")})$`);
+  regexCache.set(glob, regex);
+  return regex;
 };
-/** Returns true if `path` matches any of the glob patterns. */
-export const matchesGlob = (path, patterns) => {
-    const basename = path.split('/').pop() ?? path;
-    return patterns.some((pattern) => {
-        const regex = globToRegExp(pattern);
-        if (regex.test(path))
-            return true;
-        // A pattern without a slash also matches the basename.
-        if (!pattern.includes('/'))
-            return regex.test(basename);
-        // A relative pattern that contains a slash matches an absolute source by
-        // suffix, so `src/api.yaml` matches `/home/user/repo/src/api.yaml` — the
-        // minimatch/Spectral behavior for override globs against absolute paths.
-        if (!pattern.startsWith('/') && !pattern.startsWith('**')) {
-            return globToRegExp(`**/${pattern}`).test(path);
-        }
-        return false;
-    });
+const matchesGlob = (path, patterns) => {
+  const basename = path.split("/").pop() ?? path;
+  return patterns.some((pattern) => {
+    const regex = globToRegExp(pattern);
+    if (regex.test(path))
+      return true;
+    if (!pattern.includes("/"))
+      return regex.test(basename);
+    if (!pattern.startsWith("/") && !pattern.startsWith("**")) {
+      return globToRegExp(`**/${pattern}`).test(path);
+    }
+    return false;
+  });
+};
+export {
+  globToRegExp,
+  matchesGlob
 };

package/dist/core/index.d.ts

@@ -7,5 +7,4 @@ export { type LintPlugin, type LintPluginContext, type LintPluginResult, type Pl
 export { pointerToPath, resolveSourceOrigin, resolveSourceOriginFromMap, resolveSourcePath, } from './pointers.js';
 export { type AliasDefinition, createRuleset, type ExtendModifier, type ExtendResolver, type ResolvedExtend, type Ruleset, type RulesetOptions, } from './ruleset.js';
 export { createLinter, type IRunOptions, type Linter } from './runner.js';
-export * from './types.js';
 export { type IRulesetProblem, validateRuleset } from './validate-ruleset.js';

package/dist/core/index.js

@@ -1,11 +1,30 @@
-export { createDocument } from './document.js';
-export { detectFormats } from './formats.js';
-export { globToRegExp, matchesGlob } from './glob.js';
-export { compileQuery, query, queryCompiled, queryMany } from './jsonpath.js';
-export { lint, lintWithResult, } from './lint.js';
-export { runPlugins, } from './plugin.js';
-export { pointerToPath, resolveSourceOrigin, resolveSourceOriginFromMap, resolveSourcePath, } from './pointers.js';
-export { createRuleset, } from './ruleset.js';
-export { createLinter } from './runner.js';
-export * from './types.js';
-export { validateRuleset } from './validate-ruleset.js';
+import { createDocument } from "./document.js";
+import { detectFormats } from "./formats.js";
+import { globToRegExp, matchesGlob } from "./glob.js";
+import { compileQuery, query, queryCompiled, queryMany } from "./jsonpath.js";
+import { lint, lintWithResult } from "./lint.js";
+import { runPlugins } from "./plugin.js";
+import { pointerToPath, resolveSourceOrigin, resolveSourceOriginFromMap, resolveSourcePath } from "./pointers.js";
+import { createRuleset } from "./ruleset.js";
+import { createLinter } from "./runner.js";
+import { validateRuleset } from "./validate-ruleset.js";
+export {
+  compileQuery,
+  createDocument,
+  createLinter,
+  createRuleset,
+  detectFormats,
+  globToRegExp,
+  lint,
+  lintWithResult,
+  matchesGlob,
+  pointerToPath,
+  query,
+  queryCompiled,
+  queryMany,
+  resolveSourceOrigin,
+  resolveSourceOriginFromMap,
+  resolveSourcePath,
+  runPlugins,
+  validateRuleset
+};