@amritk/lint 0.4.8 → 0.5.0

package/AI.md

@@ -20,6 +20,43 @@ const ruleset = {
 const findings = await lintDocument('version: 1\n', { ruleset, source: 'service.yaml' })
 ```
 
+## Presets: OpenAPI and AsyncAPI
+
+The core engine knows no spec. Two ready-made rulesets live in subpaths — build
+one and hand the **result** to `lintDocument`:
+
+```ts
+import { lintDocument } from '@amritk/lint'
+import { createAsyncApiRuleset } from '@amritk/lint/rules/asyncapi'
+import { resolveRefs } from '@amritk/resolve-refs' // any resolver will do
+
+// Recommended rules only: 48 of 56. For all 56, pass the `all` modifier:
+//   createAsyncApiRuleset({ extends: [['asyncapi', 'all']] })
+const ruleset = createAsyncApiRuleset()
+
+const findings = await lintDocument(source, {
+  ruleset,
+  source: 'asyncapi.yaml',
+  // Optional, and load-bearing — see the gotcha below.
+  resolve: (document) => ({ resolved: resolveRefs(document.data).resolved }),
+})
+```
+
+`createOpenApiRuleset()` is the same shape (66 rules, `oas` / `loupe:oas` /
+`spectral:oas` in `extends`) and additionally ships `oasFixers` for
+`fixDocument`. **There are no AsyncAPI fixers**, so `fixDocument` with an
+AsyncAPI ruleset changes nothing.
+
+Rule names match Spectral's, so a `.spectral.yml` that re-severities individual
+rules ports over. Override by name in your own definition:
+
+```ts
+createAsyncApiRuleset({
+  extends: [['asyncapi', 'all']],
+  rules: { 'asyncapi-info-license': 'off', 'asyncapi-tag-description': 'error' },
+})
+```
+
 ## Gotchas — where agents fail
 
 1. **Two `severity` vocabularies.** In a **ruleset** you author strings
@@ -34,8 +71,15 @@ const findings = await lintDocument('version: 1\n', { ruleset, source: 'service.
 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.
+5. **OpenAPI and AsyncAPI support are separate subpaths**,
+   `@amritk/lint/rules/openapi` (`createOpenApiRuleset`, `oas`, `oasFixers`, …)
+   and `@amritk/lint/rules/asyncapi` (`createAsyncApiRuleset`, `asyncapi`, …) —
+   not the package root. Build one with `createOpenApiRuleset()` /
+   `createAsyncApiRuleset()` and hand the *result* to `lintDocument` /
+   `fixDocument` as `ruleset`. Passing the `oas` or `asyncapi` definition as data
+   instead silently produces nothing: its custom functions are unknown at the
+   package root, and its `formats` gate matches nothing without that spec's
+   detectors.
 6. **A ruleset is privileged; a document is not.** Linted documents cannot
    execute anything, and `[?(...)]` filters in a `given` are parsed and
    interpreted rather than evaluated as JavaScript. But `extends` follows any
@@ -47,10 +91,34 @@ const findings = await lintDocument('version: 1\n', { ruleset, source: 'service.
 7. **`createRuleset` is memoized** per `(definition object, basePath,
    restrictTo)`. Mutating a definition you already passed in will not rebuild the
    ruleset — pass a fresh object instead.
+8. **Most AsyncAPI rules are gated per major** (11 of the 56 apply to both).
+   The 3.x-only rules are named with an `asyncapi-3-` prefix
+   (`asyncapi-3-operation-description`) and the 2.x ones are not, because 3.0
+   moved operations to the top level and tags under `info`. Re-severitying
+   `asyncapi-operation-description` does nothing to a 3.0 document. The
+   structural rules pick their meta-schema from the `asyncapi` field, and a
+   version with no bundled schema (a future `2.7`, say) reports nothing rather
+   than being judged against a neighbouring version's.
+9. **Without a `resolve` hook, nothing behind a `$ref` is checked** — quietly.
+   The rules that validate schema *content* (payloads, headers, message
+   examples) need the dereferenced tree; given `payload: { $ref: … }` and no
+   resolver they see an opaque reference and stay silent rather than guess. You
+   get findings, just fewer of them, with no warning that a resolver would have
+   found more. Rules that read what the author wrote (addresses, server
+   variables, tag names) run unresolved by design and are unaffected.
+
+   The flip side: with a resolver, a rule that validates content matches a
+   reusable `components` definition once per `$ref` reaching it. Each match is
+   reported at the definition, so the copies are identical and only the first is
+   returned — you do not need to de-duplicate a report yourself. Two findings
+   that share a `line:column` are genuinely two problems (the classic case:
+   `info.contact` missing `name`, `url` and `email` all carry the `contact`
+   object's range), so key on `path` if you need to tell them apart.
 
 ## Exports
 
-- `lintDocument(input, options?)` → findings only.
+- `lintDocument(input, options?)` → findings only. `options.ruleset` is either a
+  definition to build or an already-built `Ruleset`.
 - `lintDocumentWithResult(input, options?)` → `{ diagnostics, output?, pluginData }`.
 - `fixDocument(input, options?)` → `{ output, fixed, applied, remaining, converged, passes }`
   (needs `fixers`; `converged: false` means the 10-pass cap was hit with the
@@ -64,6 +132,7 @@ const findings = await lintDocument('version: 1\n', { ruleset, source: 'service.
 | Import | Purpose |
 |---|---|
 | `@amritk/lint` | core engine, `lintDocument`/`fixDocument`, built-in functions |
-| `@amritk/lint/rules/openapi` | ready-made OpenAPI preset (`createOpenApiRuleset`, `oas`) |
+| `@amritk/lint/rules/openapi` | OpenAPI 2.0/3.0/3.1/3.2 preset — 66 rules, plus `oasFixers` |
+| `@amritk/lint/rules/asyncapi` | AsyncAPI 2.0–2.6 / 3.0 preset — 56 rules, no fixers |
 
 Install: `bun add @amritk/lint`.

package/README.md

@@ -21,7 +21,7 @@
 
 It is **format-agnostic**: the core engine ships no built-in ruleset and knows nothing about OpenAPI or any other schema — you bring the rules. This is JSON/YAML style-guide linting with JSON Schema and custom rules at its core.
 
-For OpenAPI specifically, the `@amritk/lint/rules/openapi` subpath ships a ready-made preset on top of that engine — see [OpenAPI ruleset](#openapi-ruleset) below.
+For OpenAPI and AsyncAPI specifically, the `@amritk/lint/rules/openapi` and `@amritk/lint/rules/asyncapi` subpaths ship ready-made presets on top of that engine — see [OpenAPI ruleset](#openapi-ruleset) and [AsyncAPI ruleset](#asyncapi-ruleset) below.
 
 The CLI lives in the [`mjst`](../cli) binary as `mjst lint`; this package is the programmatic library behind it.
 
@@ -123,7 +123,9 @@ await lintDocument(source, {
 })
 ```
 
-`restrictTo` is off by default and narrows *which* files a ruleset can name. It is not a sandbox: a `.js` file inside the permitted root still runs with full privileges.
+`restrictTo` is off by default and narrows *which* files a ruleset can name. It is not a sandbox: a `.js` file inside the permitted root still runs with full privileges. The OpenAPI preset takes the same option — `createOpenApiRuleset(definition, basePath, { restrictTo })`.
+
+One thing `restrictTo` does not cover: a regular expression a ruleset writes — in `pattern`'s `match`/`notMatch`, or as a literal inside a `[?(...)]` filter — is compiled and run against text from the document. An ambiguous pattern (nested quantifiers over overlapping character classes) can backtrack catastrophically on an input crafted to trigger it, so a hostile *document* can hang the linter through a regex the *ruleset* provided. The built-in rules avoid such patterns deliberately (see the note in `casing`); keep the same discipline in rules you write, and prefer anchored patterns with unambiguous alternatives.
 
 ### Auto-fix
 
@@ -147,11 +149,23 @@ const { output, applied, remaining } = await fixDocument('host: api.example.com/
 
 The engine ships no built-in fixers (rule codes are yours to define), so the default registry is empty and `fixDocument` is a no-op until you supply one.
 
+`options.ruleset` takes either a definition (built here with the built-in functions) or a `Ruleset` you built yourself. Pass a built one whenever the rules need functions or format detectors the package root does not have — an OpenAPI preset, for instance, whose rules would otherwise all be skipped as unknown-function/unmatched-format:
+
+```ts
+import { fixDocument } from '@amritk/lint'
+import { createOpenApiRuleset, oasFixers } from '@amritk/lint/rules/openapi'
+
+const { output, applied } = await fixDocument(source, {
+  ruleset: createOpenApiRuleset(),
+  fixers: oasFixers,
+})
+```
+
 Fixing runs to a fixpoint, capped at 10 passes. The result reports how that ended: **`converged`** is `false` when the cap was hit while the document was still changing (usually two fixers undoing each other), and **`passes`** counts the passes that changed something. `applied` is de-duplicated by rule code and path, so a report can safely say "fixed N problems".
 
 ### Rendering findings
 
-`lintDocument` returns structured `IDiagnostic[]` — each with a `code`, `message`, `path`, `severity`, `source`, and a zero-based `range`. **Rendering is the caller's job**: print them, serialize them to JSON, or map them to whatever your editor or CI consumes. The linter deliberately ships no output "formatter" layer (that is not the same thing as `prettier`/`biome format`, which reformat source).
+`lintDocument` returns structured `IDiagnostic[]` — each with a `code`, `message`, `path`, `severity`, `source`, and a zero-based `range`. `source`, `path` and `range` all describe the same node in the same document: the one the author wrote. A rule that runs against the dereferenced tree matches inside an inlined `$ref` target, and its finding is reported at the declaration that target came from, not at the `$ref` site. Two `$ref`s to the same mistake therefore produce one finding, not two. **Rendering is the caller's job**: print them, serialize them to JSON, or map them to whatever your editor or CI consumes. The linter deliberately ships no output "formatter" layer (that is not the same thing as `prettier`/`biome format`, which reformat source).
 
 ```ts
 const findings = await lintDocument(source, { ruleset, source: 'doc.yaml' })
@@ -209,7 +223,7 @@ Anything outside that grammar is a ruleset error (`createRuleset` throws and nam
 
 | Export | What it does |
 | --- | --- |
-| `lintDocument(input, options?)` | Parse `input` and lint it against `options.ruleset`; returns `IDiagnostic[]`. |
+| `lintDocument(input, options?)` | Parse `input` and lint it against `options.ruleset` — a definition, or a `Ruleset` you already built; returns `IDiagnostic[]`. |
 | `lintDocumentWithResult(input, options?)` | Like `lintDocument`, but returns `{ diagnostics, output?, pluginData }` (including any plugin's rewritten `output`). |
 | `fixDocument(input, options?)` | Lint and apply `options.fixers` to a fixpoint; returns `{ output, fixed, applied, remaining, converged, passes }`. |
 | `createRuleset(definition?, basePath?, options?)` | Normalize a ruleset definition into a runnable `Ruleset`, layering the built-in functions and resolving `extends`. Memoized per `(definition object, basePath, restrictTo)` — treat a definition you have passed in as frozen. |
@@ -233,16 +247,16 @@ const ruleset = createOpenApiRuleset()
 const findings = await lint(spec, { ruleset })
 ```
 
-`createOpenApiRuleset(definition?, basePath?)` builds a runnable `Ruleset` with the OpenAPI functions and format detectors layered over the built-ins, and with `extends` resolution that understands the `oas` / `loupe:oas` / `spectral:oas` names (the last two accepted so existing Spectral-style rulesets extend unchanged). Enable every rule with `createOpenApiRuleset({ extends: [['oas', 'all']] })`, or pass your own definition to override severities, add rules, or point `extends` at a file/npm package.
+`createOpenApiRuleset(definition?, basePath?, options?)` builds a runnable `Ruleset` with the OpenAPI functions and format detectors layered over the built-ins, and with `extends` resolution that understands the `oas` / `loupe:oas` / `spectral:oas` names (the last two accepted so existing Spectral-style rulesets extend unchanged). Enable every rule with `createOpenApiRuleset({ extends: [['oas', 'all']] })`, or pass your own definition to override severities, add rules, or point `extends` at a file/npm package. `options.restrictTo` applies the same [trust boundary](#trust-boundary--who-may-write-a-ruleset) the package root's `restrictTo` does.
 
 | Export | What it does |
 | --- | --- |
-| `createOpenApiRuleset(definition?, basePath?)` | Build a runnable OpenAPI `Ruleset` (functions + formats + `extends` resolution). |
-| `resolveOpenApiRuleset(name, basePath?)` | Resolve an `extends` reference, including the `oas` / `loupe:oas` / `spectral:oas` names. |
+| `createOpenApiRuleset(definition?, basePath?, options?)` | Build a runnable OpenAPI `Ruleset` (functions + formats + `extends` resolution). |
+| `resolveOpenApiRuleset(name, basePath?, options?)` | Resolve an `extends` reference, including the `oas` / `loupe:oas` / `spectral:oas` names. |
 | `oas` | The built-in OpenAPI ruleset definition. |
 | `oasFunctions` / `allFunctions` | The OpenAPI-specific functions; `allFunctions` = built-ins + OpenAPI. |
 | `oasFormats` | OpenAPI version detectors (`oas2`, `oas3`, `oas3.0`, `oas3.1`, `oas3.2`). |
-| `oasFixers` | Auto-fixers for the mechanically-repairable OpenAPI rules (pass to `fixDocument`). |
+| `oasFixers` | Auto-fixers for the mechanically-repairable OpenAPI rules (pass to `fixDocument` alongside a built OpenAPI ruleset). |
 | `loadOasSchema(version)` | Lazily load one OpenAPI version's official structural meta-schema (`'2.0'` / `'3.0'` / `'3.1'` / `'3.2'`), vendored as raw `.json` from `spec.openapis.org` (3.0/3.1/3.2 verbatim; 2.0 with its external draft-04 metaschema refs inlined). See [`schemas/README.md`](./src/rules/openapi/schemas/README.md). |
 
 The structural rules validate against the **official `spec.openapis.org` meta-schemas, vendored as raw `.json`** ([`schemas/`](./src/rules/openapi/schemas/)). 3.0/3.1/3.2 are byte-for-byte verbatim; only 2.0 differs (its external draft-04 metaschema refs are inlined, since the offline interpreter never fetches remote refs). OpenAPI 3.1/3.2 express Schema Objects as JSON Schema 2020-12 via a local `$dynamicRef`/`$dynamicAnchor`, which `@amritk/runtime-validators` resolves natively — so the whole document envelope is validated against the official schema with no bundling or dialect engine, while Schema Object internals stay permissive.
@@ -251,21 +265,58 @@ The structural rules validate against the **official `spec.openapis.org` meta-sc
 
 ---
 
+## AsyncAPI ruleset
+
+The same treatment for event-driven APIs. The **`@amritk/lint/rules/asyncapi`** subpath ships a preset covering **AsyncAPI 2.0–2.6 and 3.0**, layered on the same engine and adding **no dependencies**.
+
+```ts
+import { lint } from '@amritk/lint'
+import { createAsyncApiRuleset } from '@amritk/lint/rules/asyncapi'
+
+// Defaults to `extends: [asyncapi]` (recommended rules only, like `spectral:asyncapi`).
+const ruleset = createAsyncApiRuleset()
+const findings = await lint(document, { ruleset })
+```
+
+`createAsyncApiRuleset(definition?, basePath?, options?)` mirrors its OpenAPI counterpart: functions and format detectors layered over the built-ins, and `extends` resolution that understands the `asyncapi` / `loupe:asyncapi` / `spectral:asyncapi` names (the last two so existing Spectral-style rulesets extend unchanged). Enable every rule with `createAsyncApiRuleset({ extends: [['asyncapi', 'all']] })`. `options.restrictTo` applies the same [trust boundary](#trust-boundary--who-may-write-a-ruleset).
+
+| Export | What it does |
+| --- | --- |
+| `createAsyncApiRuleset(definition?, basePath?, options?)` | Build a runnable AsyncAPI `Ruleset` (functions + formats + `extends` resolution). |
+| `resolveAsyncApiRuleset(name, basePath?, options?)` | Resolve an `extends` reference, including the `asyncapi` / `loupe:asyncapi` / `spectral:asyncapi` names. |
+| `asyncapi` | The built-in AsyncAPI ruleset definition. |
+| `aasFunctions` / `allFunctions` | The AsyncAPI-specific functions; `allFunctions` = built-ins + AsyncAPI. |
+| `aasFormats` | AsyncAPI version detectors (`aas2`, `aas2.0`–`aas2.6`, `aas3`, `aas3.0`). |
+| `loadAsyncApiSchema(version)` | Lazily load one version's official structural meta-schema (`'2.0'`–`'2.6'`, `'3.0'`). See [`schemas/README.md`](./src/rules/asyncapi/schemas/README.md). |
+| `ASYNCAPI_VERSIONS` / `LATEST_ASYNCAPI_VERSION` / `asyncApiSchemaVersion(declared)` | The bundled versions, the newest one, and the mapping from a document's `asyncapi` field to the minor whose schema covers it (`'2.6.4'` → `'2.6'`; an unbundled minor → `undefined`). |
+
+Both majors are covered, and the rules are gated by format so a 2.x document never picks up a 3.x rule. The 3.0-specific ones carry an `asyncapi-3-` prefix, matching Spectral's names so a `.spectral.yml` that re-severities individual rules keeps working.
+
+The structural rules validate against the **official [`asyncapi/spec-json-schemas`](https://github.com/asyncapi/spec-json-schemas) meta-schemas, vendored as raw `.json`** ([`schemas/`](./src/rules/asyncapi/schemas/)). These are draft-07 documents that reference their own subschemas by absolute `$id` URI rather than by JSON Pointer — nothing is fetched, because every target is declared inside the same document. Each file is byte-for-byte upstream apart from **three regular expressions**, one of which is genuinely exponential on a failing input; each is replaced by a provably equivalent pattern with a single unambiguous quantifier, and the test suite asserts the equivalence over a generated corpus. See the [schemas README](./src/rules/asyncapi/schemas/README.md).
+
+Structural validation runs **once per document, against the document as written** (`resolved: false`), matching the `oas*-schema` rules above. That is a deliberate choice rather than an oversight: validating the dereferenced tree instead re-checks every `components` entry once per `$ref` that reaches it, so a single mistake in a reusable message reported three times in a document that used it twice. The trade-off is what a `$ref` hides: content pulled in from another file is not structurally checked, and neither is a same-file reference that points at the wrong kind of object (a `messages` entry aimed at `components.schemas`, say) — the reference itself is well-formed, and only the dereferenced tree would show the mismatch. That is the same gap the OpenAPI preset has. Everything written in the document itself, `components` included, is validated exactly once.
+
+---
+
 ## Benchmarks
 
-The `bench/` suite pits `@amritk/lint` head-to-head against **[Spectral](https://github.com/stoplightio/spectral)** — the OpenAPI linter this package is modelled on (hence the `spectral:oas` alias) — over the real-world specs the test suite lints: Swagger's petstore, the DigitalOcean API, and the OpenAI API (~17 KB to ~2.8 MB, spanning a small config and a genuinely large document). Both do the same job: **parse → dereference internal `$ref`s → run their recommended OpenAPI ruleset** (mjst dereferences in memory with [`@amritk/resolve-refs`](../resolve-refs), exactly as the CLI does; Spectral uses its own default resolver). Representative numbers (Bun 1.3, Linux x64 — your hardware will differ, run `bun run bench` yourself):
+The `bench/` suite pits `@amritk/lint` head-to-head against **[Spectral](https://github.com/stoplightio/spectral)** — the OpenAPI linter this package is modelled on (hence the `spectral:oas` alias) — over the real-world specs the test suite lints: Swagger's petstore, the DigitalOcean API, and the OpenAI API (~17 KB to ~2.8 MB, spanning a small config and a genuinely large document). Both do the same job: **parse → dereference internal `$ref`s → run their recommended OpenAPI ruleset** (mjst dereferences in memory with [`@amritk/resolve-refs`](../resolve-refs), exactly as the CLI does; Spectral uses its own default resolver). Representative numbers (Bun 1.4, Linux x64 — your hardware will differ, run `bun run bench` yourself):
 
 | document | size | mjst | Spectral | speedup | findings (mjst / Spectral) |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| petstore (Swagger) | 17 KB | ~8 ms | ~93 ms | **~11×** | 2 / 2 |
-| digitalocean | 105 KB | ~31 ms | ~351 ms | **~11×** | 2411 / 4319 |
-| openai | 2.8 MB | ~1.4 s | errored¹ | — | 1278 / — |
+| petstore (Swagger) | 17 KB | ~5 ms | ~95 ms | **~19×** | 2 / 2 |
+| digitalocean | 105 KB | ~27 ms | ~375 ms | **~14×** | 2411 / 4319 |
+| openai | 2.8 MB | ~0.73 s | ~7.4 s | **~10×** | 1278 / 474 |
 
-¹ Spectral's JSONPath engine (`nimma`) throws on the 2.8 MB OpenAI spec under Bun, so that row is mjst-only; mjst lints it end to end.
+An earlier revision of this table reported the OpenAI row as mjst-only, because
+Spectral's JSONPath engine (`nimma`) threw on that spec under Bun. It no longer
+does, so the row is a real comparison now. The bench still guards the Spectral
+side and reports `errored` rather than aborting the run, since that failure was
+runtime-specific and may come back.
 
 Each `lint` figure is the mean wall time of one whole pass — **every rule, not a subset** — dominated by real work: JSONPath matching, the rule functions, and the dereference pass. A fresh document is parsed on every iteration on both sides, matching how the tools are actually called. The finding counts differ because the two rulesets are not byte-identical (different rule implementations and `$ref` resolution), so this is a **throughput** comparison rather than a correctness parity check — but on petstore both land on the same two findings.
 
-**Assembling the ruleset** is timed separately, because a process pays it once and then lints many documents: `createOpenApiRuleset` (compiling every rule's JSONPath and wiring up functions and format detectors) measures **~0.07 ms**, versus **~0.27 ms** for `new Spectral()` + `setRuleset(oas)`. The benchmark warms up before timing and reports the mean over a fixed time budget; micro-benchmark figures vary by machine and runtime.
+**Assembling the ruleset** is timed separately, because a process pays it once and then lints many documents: `createOpenApiRuleset` (compiling every rule's JSONPath and wiring up functions and format detectors) measures **~0.07 ms**, versus **~0.28 ms** for `new Spectral()` + `setRuleset(oas)`. The benchmark warms up before timing and reports the mean over a fixed time budget; micro-benchmark figures vary by machine and runtime.
 
 ---
 

package/dist/core/filter-expression.js

@@ -1,3 +1,4 @@
+const MAX_FILTER_DEPTH = 100;
 const CONTEXT_TOKENS = {
   "@": "value",
   "@property": "property",
@@ -161,15 +162,20 @@ const ALLOWED_METHODS = /* @__PURE__ */ new Set([
   "trim"
 ]);
 const parseFilterExpression = (source) => {
+  const quoted = source.length > 120 ? `${source.slice(0, 120)}\u2026` : source;
+  const describe = (error) => {
+    const syntax = error;
+    return { error: `${syntax.message} at offset ${syntax.offset} in filter "${quoted}"` };
+  };
   let tokens;
   try {
     tokens = tokenize(source);
   } catch (error) {
-    const syntax = error;
-    return { error: `${syntax.message} at offset ${syntax.offset} in filter "${source}"` };
+    return describe(error);
   }
   let position = 0;
   let usesPath = false;
+  let depth = 0;
   const peek = () => tokens[position];
   const offsetOf = (token) => token?.start ?? source.length;
   const eatPunct = (text) => {
@@ -255,6 +261,14 @@ const parseFilterExpression = (source) => {
     return fail(`Unexpected token "${token.text}"`, token.start);
   };
   const parseUnary = () => {
+    if (++depth > MAX_FILTER_DEPTH) {
+      fail(`Filter expression nests deeper than ${MAX_FILTER_DEPTH} levels`, offsetOf(peek()));
+    }
+    const node = parseUnaryInner();
+    depth--;
+    return node;
+  };
+  const parseUnaryInner = () => {
     const token = peek();
     if (token?.kind === "punct" && (token.text === "!" || token.text === "-")) {
       position++;
@@ -311,8 +325,7 @@ const parseFilterExpression = (source) => {
       fail(`Unexpected token "${"text" in trailing ? trailing.text : ""}"`, trailing.start);
     return { node, usesPath };
   } catch (error) {
-    const syntax = error;
-    return { error: `${syntax.message} at offset ${syntax.offset} in filter "${source}"` };
+    return describe(error);
   }
 };
 export {

package/dist/core/filter.js

@@ -19,7 +19,7 @@ const readMember = (object, name) => {
     return Number.isInteger(index) ? object[index] : void 0;
   }
   if (isPlainObject(object))
-    return Object.hasOwn(object, name) ? object[name] : void 0;
+    return Object.prototype.propertyIsEnumerable.call(object, name) ? object[name] : void 0;
   return void 0;
 };
 const toStringArgument = (value) => {
@@ -129,63 +129,110 @@ const compareRelational = (operator, left, right) => {
       return a >= b;
   }
 };
-const evaluate = (node, context) => {
+const compileNode = (node) => {
   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");
+    case "regex": {
+      const constant = node.value;
+      return () => constant;
+    }
+    case "context": {
+      switch (node.ref) {
+        case "value":
+          return (value) => value;
+        case "property":
+          return (_value, property) => property;
+        case "parent":
+          return (_value, _property, parent) => parent;
+        case "parentProperty":
+          return (_value, _property, _parent, parentProperty) => parentProperty;
+        case "path":
+          return (_value, _property, _parent, _parentProperty, path) => path;
+        default:
+          return (_value, _property, _parent, _parentProperty, _path, root) => root;
       }
-      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 "member": {
+      const object = compileNode(node.object);
+      const name = node.name;
+      return (value, property, parent, parentProperty, path, root) => readMember(object(value, property, parent, parentProperty, path, root), name);
+    }
+    case "computed": {
+      const object = compileNode(node.object);
+      const index = compileNode(node.index);
+      return (value, property, parent, parentProperty, path, root) => {
+        const key = index(value, property, parent, parentProperty, path, root);
+        if (typeof key !== "string" && typeof key !== "number") {
+          throw filterRuntimeError("A computed member must be a string or a number");
+        }
+        return readMember(object(value, property, parent, parentProperty, path, root), key);
+      };
+    }
+    case "call": {
+      const object = compileNode(node.object);
+      const name = node.name;
+      const args = node.args.map(compileNode);
+      const arity = args.length;
+      return (value, property, parent, parentProperty, path, root) => {
+        const values = new Array(arity);
+        for (let i = 0; i < arity; i++) {
+          values[i] = args[i](value, property, parent, parentProperty, path, root);
+        }
+        return callMethod(object(value, property, parent, parentProperty, path, root), name, values);
+      };
+    }
     case "unary": {
-      if (node.operator === "!")
-        return !evaluate(node.operand, context);
+      const operand = compileNode(node.operand);
+      if (node.operator === "!") {
+        return (value, property, parent, parentProperty, path, root) => !operand(value, property, parent, parentProperty, path, root);
+      }
       if (node.operator === "void") {
-        evaluate(node.operand, context);
-        return void 0;
+        return (value, property, parent, parentProperty, path, root) => {
+          operand(value, property, parent, parentProperty, path, root);
+          return void 0;
+        };
       }
-      return -Number(evaluate(node.operand, context));
+      return (value, property, parent, parentProperty, path, root) => -Number(operand(value, property, parent, parentProperty, path, root));
     }
     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);
+      const left = compileNode(node.left);
+      const right = compileNode(node.right);
+      if (node.operator === "&&") {
+        return (value, property, parent, parentProperty, path, root) => {
+          const outcome = left(value, property, parent, parentProperty, path, root);
+          return outcome ? right(value, property, parent, parentProperty, path, root) : outcome;
+        };
+      }
+      return (value, property, parent, parentProperty, path, root) => {
+        const outcome = left(value, property, parent, parentProperty, path, root);
+        return outcome ? outcome : right(value, property, parent, parentProperty, path, root);
+      };
     }
     case "comparison": {
-      const left = evaluate(node.left, context);
-      const right = evaluate(node.right, context);
+      const left = compileNode(node.left);
+      const right = compileNode(node.right);
       switch (node.operator) {
         case "===":
-          return left === right;
+          return (value, property, parent, parentProperty, path, root) => left(value, property, parent, parentProperty, path, root) === right(value, property, parent, parentProperty, path, root);
         case "!==":
-          return left !== right;
+          return (value, property, parent, parentProperty, path, root) => left(value, property, parent, parentProperty, path, root) !== right(value, property, parent, parentProperty, path, root);
         case "==":
-          return looseEquals(left, right);
+          return (value, property, parent, parentProperty, path, root) => looseEquals(left(value, property, parent, parentProperty, path, root), right(value, property, parent, parentProperty, path, root));
         case "!=":
-          return !looseEquals(left, right);
-        default:
-          return compareRelational(node.operator, left, right);
+          return (value, property, parent, parentProperty, path, root) => !looseEquals(left(value, property, parent, parentProperty, path, root), right(value, property, parent, parentProperty, path, root));
+        default: {
+          const operator = node.operator;
+          return (value, property, parent, parentProperty, path, root) => compareRelational(operator, left(value, property, parent, parentProperty, path, root), right(value, property, parent, parentProperty, path, root));
+        }
       }
     }
   }
 };
 const toFilterFn = (parsed) => {
-  const { node } = parsed;
+  const test = compileNode(parsed.node);
   return (value, property, parent, root, path, parentProperty) => {
     try {
-      return Boolean(evaluate(node, { value, property, parent, parentProperty, path, root }));
+      return Boolean(test(value, property, parent, parentProperty, path, root));
     } catch {
       return false;
     }

package/dist/core/glob.js

@@ -1,3 +1,4 @@
+import { createBoundedCache } from "./bounded-cache.js";
 const REGEXP_SPECIAL = /[\\^$.*+?()[\]{}|/]/;
 const splitTopLevel = (body) => {
   const parts = [];
@@ -18,46 +19,40 @@ const splitTopLevel = (body) => {
   parts.push(current);
   return parts;
 };
-const expandBraces = (glob) => {
-  const open = glob.indexOf("{");
-  if (open === -1)
-    return [glob];
+const findBraceEnd = (glob, open) => {
   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) {
-    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);
-      }
+      if (depth === 0)
+        return i;
     }
   }
-  return results;
+  return -1;
 };
-const globInnerSource = (glob) => {
+const globSource = (glob, braces) => {
   let source = "";
   for (let i = 0; i < glob.length; i++) {
     const char = glob[i];
+    if (char === "{" && braces) {
+      const close = findBraceEnd(glob, i);
+      if (close === -1)
+        return source + globSource(glob.slice(i), false);
+      const body = glob.slice(i + 1, close);
+      const options = splitTopLevel(body);
+      if (options.length === 1) {
+        source += `\\{${globSource(body, false)}\\}`;
+        i = close;
+        continue;
+      }
+      const followedBySlash = glob[close + 1] === "/";
+      const compile = (option) => globSource(followedBySlash ? `${option}/` : option, true);
+      source += `(?:${options.map(compile).join("|")})`;
+      i = followedBySlash ? close + 1 : close;
+      continue;
+    }
     if (char === "*") {
       if (glob[i + 1] === "*") {
         i++;
@@ -80,13 +75,12 @@ const globInnerSource = (glob) => {
   }
   return source;
 };
-const regexCache = /* @__PURE__ */ new Map();
+const regexCache = createBoundedCache(500);
 const globToRegExp = (glob) => {
   const cached = regexCache.get(glob);
   if (cached)
     return cached;
-  const alternatives = expandBraces(glob).map(globInnerSource);
-  const regex = new RegExp(`^(?:${alternatives.join("|")})$`);
+  const regex = new RegExp(`^(?:${globSource(glob, true)})$`);
   regexCache.set(glob, regex);
   return regex;
 };

package/dist/core/jsonpath.d.ts

@@ -5,9 +5,17 @@ export type IQueryMatch = {
     value: unknown;
     path: JsonPath;
 };
-type Selector = {
+type Selector = 
+/**
+ * `.name` / `['name']`. `index` is the same name read as an array index, or
+ * `undefined` when it is not all digits — precomputed here because the check
+ * used to run as a regex against the *same* name on every array node the
+ * descent reached.
+ */
+{
     kind: 'child';
     name: string;
+    index: number | undefined;
 } | {
     kind: 'index';
     index: number;