lanekeep 0.6.1 → 0.8.0

package/README.md

@@ -12,220 +12,77 @@ lanekeep enforces the conventions that live in your team's heads and your review
 the ones a language model cannot infer from the code it is shown. Every rule is a codified answer
 to **"the agent keeps doing this wrong."**
 
-Checks **TypeScript, JavaScript, Python, Go and Rust**. Ships as a single static binary with no runtime
-dependency.
+It ships as a single static binary with no runtime dependency.
 
 ---
 
-## Quick start
+## Languages
 
-Sixty seconds, from nothing to a rule catching something.
+Each guide covers installing lanekeep in that ecosystem, configuring it, the built-in rules that
+apply, a worked custom rule, and the name-resolution behavior specific to that language.
 
-**1. Install** — whichever fits the project you are adding it to:
+| Language | Extensions | Install | Guide |
+| --- | --- | --- | --- |
+| Go | `.go` | `go get -tool github.com/fmsouza/lanekeep/cmd/lanekeep` | **[Go](https://github.com/fmsouza/lanekeep/wiki/Go)** |
+| Python | `.py`, `.pyi` | `pip install lanekeep` | **[Python](https://github.com/fmsouza/lanekeep/wiki/Python)** |
+| Rust | `.rs` | `cargo install lanekeep-cli` | **[Rust](https://github.com/fmsouza/lanekeep/wiki/Rust)** |
+| TypeScript / JavaScript | `.ts`, `.mts`, `.cts`, `.tsx`, `.js`, `.mjs`, `.cjs`, `.jsx` | `npm install --save-dev lanekeep` | **[TypeScript and JavaScript](https://github.com/fmsouza/lanekeep/wiki/TypeScript-and-JavaScript)** |
 
-```bash
-npm install --save-dev lanekeep
-```
-
-<details>
-<summary>Python, Go, Homebrew, cargo, or a raw binary</summary>
-
-```bash
-pip install lanekeep                                      # Python
-go get -tool github.com/fmsouza/lanekeep/cmd/lanekeep     # Go
-brew install fmsouza/tap/lanekeep                         # macOS / Linux, system-wide
-cargo install lanekeep-cli                                # from source
-```
-
-Or download from the [releases page](https://github.com/fmsouza/lanekeep/releases).
-
-</details>
+`brew install fmsouza/tap/lanekeep` works anywhere, as does a binary from the
+[releases page](https://github.com/fmsouza/lanekeep/releases). Every channel delivers the same
+build, so the bytes are identical whichever you pick.
 
-**2. Scaffold a config and a first rule:**
+Whatever the project, the first two commands are the same:
 
 ```bash
-npx lanekeep init
+lanekeep init     # detects the project and writes a config plus a starter rule
+lanekeep check
 ```
 
-That writes two files, both runnable:
-
-```
-lanekeep.json                 # what to check, and with which rules
-lanekeep/rules/<starter>.ts   # a worked example you can edit
-```
-
-It detects whether the project is Go, Python or TypeScript and scaffolds accordingly — the
-right glob, a starter rule in that language, and a built-in worth having on.
-
-**3. Check:**
-
-```bash
-npx lanekeep check
-```
-
-```
-src/payment.ts:12:3 error [local/no-debugger] debugger statement
-  → remove it before committing
-
-✖ 1 error(s) across 1 file(s) checked
-```
-
-> **If it says `0 file(s) checked`**, nothing matched the config's `include`. The scaffold starts
-> with `src/**/*.{ts,tsx}` — widen it to wherever your code actually lives.
-
-That is the whole loop. Everything below is detail.
-
----
+New here? **[Getting Started](https://github.com/fmsouza/lanekeep/wiki/Getting-Started)** is about
+a minute, end to end.
 
 ## What it is
 
 lanekeep is not a linter in the ESLint sense. ESLint enforces language-level correctness; lanekeep
-enforces *project-specific* conventions. The two do not overlap much, and lanekeep is not a
-replacement for either your linter or your formatter.
-
-Rules are TypeScript programs. Here is one checking **Go**:
-
-```ts
-import { defineRule } from 'lanekeep'
-
-export default defineRule({
-  id: 'local/no-fmt-println',
-  language: 'go',
-  severity: 'error',
-
-  card: {
-    message: 'fmt.Println in library code',
-    remediation: 'use log/slog, so the output has a level and a destination',
-    examples: {
-      bad: 'fmt.Println("saved", count)',
-      good: 'slog.Info("saved", "count", count)',
-    },
-  },
-
-  // Matched in Rust, at native speed. Your code runs only on matches.
-  query: `
-    (call_expression
-      function: (selector_expression
-        operand: (identifier) @pkg
-        field: (field_identifier) @fn)) @call
-  `,
-
-  check(ctx, m) {
-    if (ctx.text(m.pkg) !== 'fmt') return
-    if (ctx.text(m.fn) !== 'Println') return
-
-    // The line that makes this a rule rather than a grep: a local variable
-    // named `fmt` is not the standard library package.
-    if (ctx.bindingKind(m.pkg) !== 'import') return
-
-    ctx.report(m.call)
-  },
-})
-```
-
-**Rules are TypeScript whatever they check** — that is one embedded language, not a JavaScript
-bias. Rules need to be *programs*, because the conventions worth enforcing are too specific for
-any fixed vocabulary of predicates, and one language keeps the sandbox, the cache and the host
-API single-implementation.
-
-**Configuration is not TypeScript.** `lanekeep.json` is plain data, so a Go or Python team never
-writes a `.ts` file except when authoring an actual rule.
-
-`check` is ordinary TypeScript. Loop, accumulate state, build data structures, read other files,
-import shared helpers — there is no expressiveness ceiling and no DSL to learn beyond the query
-that gates it.
-
-**The card is not documentation.** `message`, `remediation` and `examples` are mandatory, because
-they are what gets fed back to whoever has to act on the violation — increasingly an agent.
-
-**Editor types ship with the npm package.** `npm install --save-dev lanekeep` gives you the
-binary *and* TypeScript definitions for the whole host API, so `ctx` autocompletes and a typo'd
-method is a compile error rather than a rule that throws in the sandbox. They are checked
-against the engine's own registration, so they cannot drift from what actually exists.
-
-A Go, Python or Rust project that wants them can add the npm package as a dev dependency
-purely for authoring — nothing about the checker needs Node.
-
-## Supported languages
-
-Each guide covers installing lanekeep in that ecosystem, what to put in the config, which
-built-in rules apply, a worked custom rule, and the resolution behavior specific to it.
-
-| Language | Guide | Extensions |
-| --- | --- | --- |
-| Go | **[Go guide](https://github.com/fmsouza/lanekeep/wiki/Go)** | `.go` |
-| Python | **[Python guide](https://github.com/fmsouza/lanekeep/wiki/Python)** | `.py`, `.pyi` |
-| Rust | **[Rust guide](https://github.com/fmsouza/lanekeep/wiki/Rust)** | `.rs` |
-| TypeScript / JavaScript | **[TypeScript and JavaScript guide](https://github.com/fmsouza/lanekeep/wiki/TypeScript-and-JavaScript)** | `.ts`, `.mts`, `.cts`, `.tsx`, `.js`, `.mjs`, `.cjs`, `.jsx` |
-
-Every one carries syntactic binding resolution, so a rule can ask where a name came from rather
-than matching text — `ctx.bindingKind`, `ctx.resolvesToImport` and `ctx.isShadowed` answer for
-all of them.
-
-**The grammar is chosen by the file, not by the rule.** A rule declares which languages it
-applies to and does not run on files of any other, defaulting to `['typescript', 'tsx']` when it
-says nothing. That default is the one thing to get right on a non-TypeScript rule: omit
-`language` on a Go rule and it silently never fires.
-
-## Configuration
-
-`lanekeep.json`, at the project root. `lanekeep init` writes one for you, matched to the
-project it finds.
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/fmsouza/lanekeep/main/schema/lanekeep.schema.json",
-
-  "include": ["**/*.go"],
-  "exclude": ["**/*_test.go"],
-
-  "rules": [
-    "lanekeep/no-package-init",
-    { "rule": "lanekeep/no-restricted-imports", "options": { "restrictions": [
-      { "module": "database/sql", "from": ["!internal/store/**"], "reason": "go through the store package" }
-    ] } },
-    "./lanekeep/rules/no-fmt-println.ts"
-  ]
-}
-```
-
-A string uses a rule as it comes; the object form calls it with options. `$schema` is what
-gives you **completion and validation in your editor with nothing installed** — VS Code and
-most others read it directly.
-
-**Rules are TypeScript, configuration is not.** A rule is a program, and that is the point of
-the tool; saying which rules to run is data. A Go or Python team should not have to write a
-`.ts` file to do the second, which is why the config is JSON and only the rules are not.
-
-Rule ids are namespaced. `lanekeep/` is reserved for built-ins and `local/` needs no
-declaration; any other prefix must be listed in `namespaces`, so a typo in an id is an error
-rather than a rule that silently never runs.
-
-Ten rules ship built in — four for TypeScript and JavaScript, two each for Python, Go and Rust. See
-[`docs/built-in-rules.md`](docs/built-in-rules.md) for what each one checks and its options.
-
-<details>
-<summary>Configuring in TypeScript instead</summary>
-
-`lanekeep.config.ts` still works, and is the better choice when the config computes something
-or shares a preset across repositories — composition is then ordinary `import`, with no
-bespoke `extends` mechanism to learn.
-
-```ts
-import { defineConfig } from 'lanekeep'
-import noDefaultExport from 'lanekeep/no-default-export'
-import noDebugger from './lanekeep/rules/no-debugger'
-
-export default defineConfig({
-  include: ['src/**/*.{ts,tsx}'],
-  rules: [noDefaultExport, noDebugger],
-})
-```
-
-Both formats compile to the same thing before anything reads them, so they cannot differ in
-behavior. `lanekeep.json` wins if a project somehow has both.
-
-</details>
+enforces *project-specific* conventions. The two barely overlap, and lanekeep replaces neither your
+linter nor your formatter.
+
+A rule is a **program**, not a configuration entry. It declares a
+[tree-sitter query](https://tree-sitter.github.io/tree-sitter/using-parsers/queries/1-syntax.html)
+that Rust matches at native speed, and a handler that runs only on matches — where it can loop,
+accumulate state, read other files and ask where a name came from.
+
+That matters because the conventions worth enforcing are the ones specific enough that nobody
+else would ever write them, which is exactly the population a fixed vocabulary of predicates
+fails. See **[Writing Rules](https://github.com/fmsouza/lanekeep/wiki/Writing-Rules)** for the
+anatomy and the full host API, and each language guide for a worked example in that language.
+
+Three things follow from who reads the output:
+
+- **Every rule carries its own fix.** `message`, `remediation` and `examples` are mandatory
+  fields, not documentation — they are the card fed back to whoever has to act on the violation,
+  increasingly an agent.
+- **Output is deterministic.** Violations are always sorted by `(ruleId, file, line, column)`, and
+  the sandbox withholds the clock and randomness, so two runs over identical input produce
+  byte-identical output. An agent reading it twice must not see reordering as change.
+- **It runs in the inner loop.** Agents and developers invoke it after every edit, so a warm run
+  is measured in tens of milliseconds — for a config whose rules are all TypeScript modules. A
+  rule that ships as a compiled component has to be loaded first, and the four TypeScript
+  built-ins share a 12.4 MiB one: a config naming all four of them costs **about 6.5 seconds on a
+  project's first run** and **about 0.2 seconds on every run after it** — the component is
+  deserialized once per run, not once per rule — and leaves 33 MiB in `.lanekeep`.
+  `lanekeep init` scaffolds one of those four, so that is what a new TypeScript project meets
+  first. [`docs/architecture.md`](docs/architecture.md) §15 has the table and what is owed.
+
+**Rules are authored in TypeScript whatever language they check** — that is the form to start
+from, and it is the one most teams already have someone who writes. A rule may also be a
+WebAssembly component, which is how eight of the ten built-ins ship — two written in Rust, two
+written in Go, and four compiled ahead of time from the same TypeScript they were already
+written in. Every form reaches the same host API and is held to the same limits, and a config
+names a rule rather than its implementation. **Configuration is neither** — `lanekeep.json` is
+plain data, so a Go, Python or Rust team never writes a `.ts` file except when authoring an
+actual rule.
 
 ## Using it
 
@@ -238,97 +95,100 @@ lanekeep check --fix            # apply the safe fixes, report what is left
 lanekeep check --profile        # where the run spent its time, per rule
 lanekeep rules                  # what this project has configured
 lanekeep explain <rule-id>      # one rule's card, without opening its source
+lanekeep server                 # LSP for an editor, or --protocol mcp for an agent host
 ```
 
-`--staged` and `--since` are intersected with the config's `include`/`exclude`, and both **skip
-cross-file rules** — a whole-corpus rule over a subset gives a wrong answer rather than a smaller
-one, so they are skipped and named on stderr instead of quietly producing one.
-
-**Fixes.** Only a fix its rule marked as behavior-preserving is applied. Anything else is a
-suggestion — shown, never written — because the cautious mistake costs a manual edit and the other
-one rewrites your code silently.
-
-**Suppressions** carry a mandatory reason and an optional expiry. A directive that does not work
-says so, rather than silently doing nothing:
-
-```ts
-// lanekeep-ignore-next-line lanekeep/no-default-export reason: legacy entry point
-export default parse
-```
-
-Run `lanekeep check --report-unused-suppressions` to find the ones that no longer silence
-anything.
-
-**Output.** `--format` takes `human` (default), `json` (versioned, stable schema), `sarif` (GitHub
-code scanning) and `agent` — token-minimal, grouped by rule rather than by file, with each card
-stated once instead of once per violation. Diagnostics always go to stderr, so piping into a
-parser works even when something fails.
-
 **Exit codes:** `0` clean, `1` violations found, `2` the checker could not run. A caller has to be
 able to tell "your code has problems" from "the tool is broken". `--warn-only` reports violations
 but exits `0`, for a phased rollout.
 
-## In CI, editors and agents
+**Output formats** via `--format`: `human` (default), `json` (versioned, stable schema), `sarif`
+(GitHub code scanning), and `agent` — token-minimal, grouped by rule rather than by file. Diagnostics
+always go to stderr, so piping into a parser works even when something fails.
 
-```bash
-lanekeep check --staged                 # pre-commit
-lanekeep check --format sarif           # GitHub code scanning
-lanekeep server                         # LSP, for any editor
-lanekeep server --protocol mcp          # MCP, for an agent host
-```
-
-MCP exposes three tools — `lanekeep_check`, `lanekeep_rules`, `lanekeep_explain` — so an agent
-can ask what it broke and what the rule wants without shelling out and parsing text.
+**Fixes** are applied only when the rule marked them behavior-preserving; anything else is shown
+and never written. **Suppressions** carry a mandatory reason and an optional expiry, and a directive
+that does not work says so rather than silently doing nothing.
 
-Worked examples for each, including SARIF upload and adopting on an existing codebase, are in
-**[CI and Editors](https://github.com/fmsouza/lanekeep/wiki/CI-and-Editors)**.
+Configuration reference, CI recipes, editor setup and the MCP tool list are in the
+[wiki](https://github.com/fmsouza/lanekeep/wiki).
 
 ## How it stays fast with programmable rules
 
 The usual problem with a native tool that runs JavaScript plugins is the boundary between them:
 dispatching into JS once per AST node means tens of thousands of crossings per file.
 
-lanekeep dispatches once per **query match** instead. The tree-sitter query runs in Rust across a
-single shared parse; only matches reach your handler. That is typically two to three orders of
-magnitude fewer crossings, and it is the reason a Rust engine still earns its place once rules are
-TypeScript.
+lanekeep dispatches once per **query match** instead. The query runs in Rust across a single shared
+parse; only matches reach your handler. That is typically two to three orders of magnitude fewer
+crossings, and it is the reason a Rust engine still earns its place once rules are programs.
 
 ```
 discover paths (globs, gitignore-aware)
   └─> for each file, in parallel:
         cache key ──hit──> validate tracked deps ──> cached violations + facts
                   └─miss─> path and raw-text gates reject before any parse
-                           └─> parse ─> match queries in Rust
-                               └─> invoke the TypeScript handler, per match only
+                           └─> parse once ─> match queries in Rust
+                               └─> invoke the handler, per match only
   └─> reduce phase: cross-file rules consume facts only, never parse trees
   └─> filter suppressions ─> sort ─> report
 ```
 
 A warm run with no changes executes no JavaScript at all — every file is a cache hit.
 
-Violations are always sorted by `(ruleId, file, line, column)`, and the sandbox withholds the clock
-and randomness, so two runs over identical input produce byte-identical output. An agent reading
-the output twice must not see reordering as change.
-
-## Installing without a package manager
+## Platforms
 
 Prebuilt for macOS on Apple silicon, Linux on x86-64 and arm64, and Windows on x86-64. The Linux
 binaries are built against **glibc 2.17**, so they run on anything from RHEL 7 onwards.
 
+**No runtime is required to run lanekeep.** Node, Python or Go is needed only to install it from
+that ecosystem, where it picks which binary to fetch. Nothing is pulled in as a dependency any of
+those ways.
+
 Intel macOS is not prebuilt — `cargo install lanekeep-cli` builds it from source, and both the npm
 launcher and the Homebrew formula say so rather than failing obscurely.
 
-**No runtime is required to run lanekeep**, even though rules are written in TypeScript. Node,
-Python or Go is needed only to install it from that ecosystem, where it picks which binary to
-fetch. Nothing is pulled in as a dependency any of those ways.
+## Security
+
+lanekeep is meant to run as a pre-commit hook and inside CI, which makes it a supply-chain target.
+Rules are executable code, so the posture is about confinement rather than absence:
+
+- **No ambient authority.** A TypeScript rule runs in an embedded QuickJS sandbox and a
+  WebAssembly rule under wasmtime; both reach exactly the host functions lanekeep exposes. `fs`,
+  `process`, `child_process`, network and dynamic import are not restricted — they do not exist in
+  the context. A component imports one interface and is refused at load if it imports another.
+- **No network access.** Ever, in any mode, with no configuration that enables it.
+- **Filesystem confinement.** Reads go through a tracked host call, confined to the project root.
+  Writes happen only under `--fix`, only to matched files, only within reported ranges.
+- **Bounded execution.** A per-invocation timeout, a global run budget and a per-runtime memory
+  ceiling, none disableable — a rule that hangs a pre-commit hook is indistinguishable from a
+  broken tool. Breaching any of them cancels the run and exits `2`, rather than reporting a partial
+  result as a clean one.
+- **Deterministic by construction.** The sandbox withholds the clock and randomness, so a rule
+  cannot introduce nondeterminism even by accident.
+
+This bounds blast radius and makes third-party rule sets reviewable. It is not a boundary against
+someone who can already commit to the repository being checked. To report a vulnerability, see
+[`SECURITY.md`](SECURITY.md).
+
+## Project status
+
+**Released and usable**, on every channel in the table above — one build feeding all of them.
+
+It is **0.x**, and this repository treats that as semver does: a minor bump may break a public Rust
+API. Rule authors are insulated from that — host API methods and the config shape are additive —
+but pin a version if you embed the crates.
+
+Known gaps, stated rather than implied:
 
-The Go package is a small launcher, because Go can only install and pin things written in Go: it
-fetches the real binary on first use, verifies it against the release's published checksums, and
-caches it. Set `LANEKEEP_BINARY` to an already-installed lanekeep and it fetches nothing.
+- **Two of the three performance budgets in [`docs/architecture.md`](docs/architecture.md)
+  §15 are not met.** The cold budget is; they are targets, and that section says by how much
+  and where the remaining time goes.
+- **No type-aware analysis**, by design. Name resolution is syntactic — see §1 non-goals.
 
 ## Documentation
 
-**The [wiki](https://github.com/fmsouza/lanekeep/wiki) is the place to start** — it is task-shaped and organized by language.
+**The [wiki](https://github.com/fmsouza/lanekeep/wiki) is the place to start** — it is task-shaped
+and organized by language.
 
 | Page | Purpose |
 | --- | --- |
@@ -336,7 +196,6 @@ caches it. Set `LANEKEEP_BINARY` to an already-installed lanekeep and it fetches
 | [Configuration](https://github.com/fmsouza/lanekeep/wiki/Configuration) | `lanekeep.json`, every field |
 | [Writing Rules](https://github.com/fmsouza/lanekeep/wiki/Writing-Rules) | Rule anatomy and the full host API |
 | [CI and Editors](https://github.com/fmsouza/lanekeep/wiki/CI-and-Editors) | Pre-commit, GitHub Actions, LSP, MCP |
-| [Go](https://github.com/fmsouza/lanekeep/wiki/Go) · [Python](https://github.com/fmsouza/lanekeep/wiki/Python) · [Rust](https://github.com/fmsouza/lanekeep/wiki/Rust) · [TypeScript and JavaScript](https://github.com/fmsouza/lanekeep/wiki/TypeScript-and-JavaScript) | Per-language guides |
 
 In-repo, versioned with the code:
 
@@ -352,46 +211,6 @@ In-repo, versioned with the code:
 | [`docs/releasing.md`](docs/releasing.md) | How a release is built, gated and published |
 | [`CHANGELOG.md`](CHANGELOG.md) | What changed, per release |
 
-## Security
-
-lanekeep is meant to run as a pre-commit hook and inside CI, which makes it a supply-chain target.
-Rules are executable code, so the posture is about confinement rather than absence:
-
-- **No ambient authority.** Rules run in an embedded QuickJS sandbox and reach exactly the host
-  functions lanekeep exposes. `fs`, `process`, `child_process`, network and dynamic import are not
-  restricted — they do not exist in the context.
-- **No network access.** Ever, in any mode, with no configuration that enables it.
-- **Filesystem confinement.** Reads go through a tracked `ctx.readFile`, confined to the project
-  root. Writes happen only under `--fix`, only to matched files, only within reported ranges.
-- **Bounded execution.** A per-invocation timeout, a global run budget and a per-runtime memory
-  ceiling, none disableable — a rule that hangs a pre-commit hook is indistinguishable from a
-  broken tool. Breaching any of them cancels the run and exits `2`, rather than reporting a partial
-  result as a clean one.
-- **Deterministic by construction.** The sandbox withholds the clock and randomness, so a rule
-  cannot introduce nondeterminism even by accident.
-
-This bounds blast radius and makes third-party rule sets reviewable. It is not a boundary against
-someone who can already commit to the repository being checked. To report a vulnerability, see
-[`SECURITY.md`](SECURITY.md).
-
-## Project status
-
-**Released and usable.** The current version is on [crates.io](https://crates.io/crates/lanekeep-cli),
-[npm](https://www.npmjs.com/package/lanekeep), [PyPI](https://pypi.org/project/lanekeep/), Homebrew,
-and as a Go module — one build feeding every channel, so the bytes are identical whichever you use.
-
-It is **0.x**, and this repository treats that as semver does: a minor bump may break a public Rust
-API. Rule authors are insulated from that — `ctx` methods and the config shape are additive — but
-pin a version if you embed the crates.
-
-Known gaps, stated rather than implied:
-
-- **No editor types for rule authors yet** (above).
-- **The performance budgets in [`docs/architecture.md`](docs/architecture.md) §15 are not met.**
-  They are targets, and that document says by how much and what the levers are. The tool is fast;
-  the numbers are simply ambitious.
-- **No type-aware analysis**, by design. Binding resolution is syntactic — see §1 non-goals.
-
 ## Contributing
 
 Contributions are welcome, particularly new built-in rules and new host API surface. Start with

package/builtin.d.ts

@@ -1,20 +1,12 @@
 /**
- * Types reached through the `typesVersions` mapping in `package.json`.
+ * Types for the importable built-in subpaths — the module built-ins, reached through the
+ * per-name `exports`/`typesVersions` entries `crates/lanekeep-package-gen` generates from
+ * `COMPONENT_RULES`. A component built-in has no entry there, so importing one is a compile
+ * error rather than a default export that lies.
  *
- * That mapping points *every* specifier here, the bare `lanekeep` included — TypeScript's
- * `"*"` pattern does not exclude the package root, and a narrower pattern would have to
- * predict what future built-ins are called. So this file is a superset: it re-exports
- * everything `index.d.ts` has, and adds the default export a built-in subpath needs.
- *
- * A `declare module 'lanekeep/*'` block inside `index.d.ts` would have been the obvious way
- * to do this and does nothing at all: a `declare module` inside a file that has its own
- * imports or exports is module augmentation, not an ambient declaration, so TypeScript
- * ignores it and the import stays unresolved. That failed silently until a compile test
- * caught it.
- *
- * The default covers both shapes a built-in can take, because which one it is cannot be known
- * from the specifier: a rule taking options is a factory — `noRestrictedImports({ ... })` —
- * and one taking none is the rule itself.
+ * The default covers the two shapes an importable built-in can take, because which one it is
+ * cannot be known from the specifier: a rule taking options is a factory —
+ * `noRestrictedImports({ ... })` — and one taking none is the rule itself.
  */
 export * from './index'
 

package/index.d.ts

@@ -1,26 +1,27 @@
 /**
  * Type definitions for authoring lanekeep rules.
  *
+ * **Generated from `crates/lanekeep-wasm/wit/world.wit` by `crates/lanekeep-types-gen`.** Do not
+ * edit by hand — run `just generate-index-dts` and commit the result.
+ *
  * These describe the host API a rule reaches inside lanekeep's sandbox. Nothing here runs in
  * Node: `defineRule` and `defineConfig` are identity functions whose only job is to give the
  * compiler something to check against, and `RuleContext` is provided by lanekeep at run time.
- *
- * Every member below is asserted against the host's own registration in
- * `crates/lanekeep-js/tests/host_types.rs`. A method that exists here and not there — or the
- * reverse — fails that test, because a definition that drifts from the engine is worse than
- * none: it produces confident autocomplete for something that does not exist.
+ * The world is the single source of truth for every member the renderer emits straight from it.
+ * Two members deviate from the world on purpose, and both are QuickJS-shaped: `today` is omitted
+ * from `RuleContext` because QuickJS exposes it as a conditional property rather than a callable,
+ * a shape this renderer cannot state honestly from the world; and `facts` is added to
+ * `RuleContext` because QuickJS hands a per-file rule `facts` that the world declares only on
+ * `reduce-context`. Nothing else is added or omitted by hand.
  */
 
 /**
  * A node in the parse tree.
  *
  * Deliberately opaque. Nodes cross into the sandbox as integer handles rather than objects,
- * which is one of the one-way doors in the architecture — and the reason this is a branded
- * type rather than `number` is that **the root node's handle is `0`**. Written as a plain
- * number, `if (!node)` looks like a null check and silently discards the root, which is how
- * a rule loses its whole top-level case without any error.
- *
- * Compare against `undefined` explicitly.
+ * and the reason this is a branded type rather than `number` is that **the root node's handle
+ * is `0`** — written as a plain number, `if (!node)` looks like a null check and silently
+ * discards the root. Compare against `undefined` explicitly.
  */
 export type Node = number & { readonly __lanekeepNode: unique symbol }
 
@@ -77,8 +78,27 @@ export interface RuleCard {
   }
 }
 
-/** Cheap rejections applied before a file is parsed. */
+/** Cheap rejections applied before a file is read or parsed. */
 export interface Gates {
+  /**
+   * Glob patterns a file's path must match for the rule to consider it.
+   *
+   * The path is relative to the project root, and the pattern must match the whole path —
+   * anchored, not a substring search. Patterns use the `globset` dialect, matched
+   * case-sensitively: `*` matches any run of characters (including `/`), `?` any single
+   * character, `[ab]`/`[!ab]` character classes and `{a,b}` alternates work, and `**`
+   * recurses directories — `src/**` admits everything under `src`, and `**` in front
+   * of `*.test.ts` admits a test file at any depth.
+   */
+  pathMatches?: string[]
+  /**
+   * Glob patterns that skip a file — a path matching any of these is never parsed. Checked
+   * before `pathMatches` and winning over it: a path a `pathMatches` pattern would have
+   * admitted is still skipped when a `pathNotMatches` pattern matches it.
+   *
+   * Same dialect and anchoring as `pathMatches`.
+   */
+  pathNotMatches?: string[]
   /**
    * Literal substrings a file's raw bytes must contain. A file missing any one of them is
    * never parsed.
@@ -89,6 +109,12 @@ export interface Gates {
    * form; omit the gate when no single substring covers every case.
    */
   fileContains?: string[]
+  /**
+   * Literal substrings that skip a file — a file whose raw bytes contain **any** of them is
+   * never parsed. The mirror image of `fileContains`'s *and*: where that gate requires every
+   * listed substring, this one rejects on the first that is present.
+   */
+  fileNotContains?: string[]
 }
 
 /** A replacement a rule offers for a violation. */
@@ -134,74 +160,65 @@ export interface EmittedFact extends Fact {
   file: string
 }
 
-/** What a rule's `check` handler reaches. */
+/**
+ * A node's location: the file, line and column `ctx.loc` returns.
+ *
+ * `line` and `column` are required here, unlike on `ReduceLocation`: `ctx.loc` either
+ * resolves the node and returns all three together, or the node does not resolve and the
+ * call returns `undefined` entirely — there is no partial state to leave room for.
+ */
+export interface NodeLocation {
+  /** Path relative to the project root. */
+  file: string
+  /** One-based. */
+  line: number
+  /** One-based. */
+  column: number
+}
+
+/**
+ * A subtree's structural fingerprint: identifiers and literal values erased.
+ *
+ * Computed host-side in one walk, so a rule does not pay a per-node boundary crossing to
+ * inspect a tree's shape. Two functions differing only in identifier names, literal values
+ * or comments hash identically; differing in an operator or a statement, differently. A
+ * dead handle yields `undefined`, like `kind` and `loc`.
+ */
+export interface StructureFingerprint {
+  /** blake3 of the normalized fold, lowercase hex. */
+  hash: string
+  /** How many nodes the fold covered — the thresholding input. */
+  nodes: number
+}
+
+/** A rule's RuleContext surface. */
 export interface RuleContext {
-  /** Path of the file being checked, relative to the project root. */
   readonly filePath: string
-  /** The whole file, as text. */
   readonly fileText: string
-  /** The tree's root node. Its handle is `0` — see {@link Node}. */
   readonly root: Node
-
-  /** The node's kind, as tree-sitter names it. */
-  kind(node: Node): string
-  /** The source text the node spans. */
-  text(node: Node): string
-  /** Whether this is a named node rather than an anonymous token. */
-  isNamed(node: Node): boolean
-  /** One-based line of the node's start. */
-  line(node: Node): number
-  /** One-based column of the node's start. */
-  column(node: Node): number
-
-  /** The node's parent, or `undefined` at the root. */
-  parent(node: Node): Node | undefined
-  /** Every child, including anonymous tokens. */
-  children(node: Node): Node[]
-  /** Named children only. */
-  namedChildren(node: Node): Node[]
-  /** Every ancestor, innermost first. */
-  ancestors(node: Node): Node[]
-
-  /**
-   * Whether an identifier resolves to a given import.
-   *
-   * Handles aliasing, so `import { makeStyles as ms }` resolves correctly. This is the call
-   * that separates a rule from a grep: a text match both misses the alias and fires on a
-   * local of the same name.
-   *
-   * @param name Which export. Omit to match the module regardless of which name was taken.
-   */
-  resolvesToImport(node: Node, module: string, name?: string): boolean
-  /** Whether an identifier came from a module matching this glob. */
-  isImportedFrom(node: Node, pattern: string): boolean
-  /** How the name was introduced, or `undefined` when it does not resolve. */
-  bindingKind(node: Node): BindingKind | undefined
-  /** Whether an outer binding of the same name is hidden by this one. */
-  isShadowed(node: Node): boolean
-
-  /** Run a query inside a subtree. */
-  querySubtree(node: Node, query: string): Match[]
-  /** The nearest ancestor matching a query, with its captures. */
-  closestAncestor(node: Node, query: string): Match | undefined
-
-  /**
-   * Read another file, relative to the project root.
-   *
-   * Tracked: the read becomes part of the cache key, so a change to that file invalidates
-   * this one's result. Confined to the project root; `undefined` when absent or outside.
-   */
+  kind(n: Node): string | undefined
+  text(n: Node): string | undefined
+  isNamed(n: Node): boolean
+  line(n: Node): number | undefined
+  column(n: Node): number | undefined
+  parent(n: Node): Node | undefined
+  children(n: Node): Node[]
+  namedChildren(n: Node): Node[]
+  ancestors(n: Node): Node[]
+  structureFingerprint(n: Node): StructureFingerprint | undefined
+  resolvesToImport(n: Node, module: string, name?: string): boolean
+  isImportedFrom(n: Node, pattern: string): boolean
+  bindingKind(n: Node): BindingKind | undefined
+  isShadowed(n: Node): boolean
+  querySubtree(n: Node, query: string): Match[]
+  closestAncestor(n: Node, query: string): Match | undefined
   readFile(path: string): string | undefined
-  /** Whether a file exists, tracked the same way. */
   fileExists(path: string): boolean
-
-  /** Emit a fact for the reduce phase. */
   emitFact(fact: Fact): void
+  loc(n: Node): NodeLocation | undefined
+  report(at: Node, message?: string | ReportOptions): void
   /** Facts emitted so far, optionally filtered by `kind`. */
   facts(kind?: string): EmittedFact[]
-
-  /** Report a violation at a node. */
-  report(at: Node, message?: string | ReportOptions): void
 }
 
 /** A violation the reduce phase reports, which has no node to point at. */
@@ -214,19 +231,10 @@ export interface ReduceLocation {
   column?: number
 }
 
-/**
- * What a rule's `reduce` handler reaches.
- *
- * Deliberately smaller than {@link RuleContext}: **the reduce phase never touches parse
- * trees.** Facts are small and serializable, which is what keeps cross-file rules parallel
- * and cacheable — handing a tree to `reduce` would make the whole corpus resident.
- */
+/** A rule's ReduceContext surface. */
 export interface ReduceContext {
-  /** Every file the run checked, relative to the project root. */
   readonly files: string[]
-  /** Facts from every file, optionally filtered by `kind`. */
   facts(kind?: string): EmittedFact[]
-  /** Report a violation against a file. */
   report(at: ReduceLocation, message?: string | ReportOptions): void
 }
 
@@ -260,8 +268,21 @@ export interface Rule {
    * Rust matches it across a single shared parse and only matches reach `check`, which is
    * what keeps a JavaScript rule affordable. Write the narrowest query that captures what
    * you need; `check` then only refines.
+   *
+   * A single string applies to every declared language. An object maps each declared
+   * language to its own query — required when the grammars do not share node vocabulary
+   * (Python spells a call `call`, the other supported grammars say `call_expression`).
+   * Every declared language must have an entry and every entry must name a declared
+   * language; a mismatch is a config-load error naming the language.
+   *
+   * Text predicates filter matches in Rust before the handler, so a predicate can only
+   * narrow, never widen, what `check` sees: `#eq?`, `#not-eq?`, `#match?`, `#not-match?`,
+   * `#any-of?` and `#not-any-of?` are supported (plus the `any-` forms of `eq?`/`match?`).
+   * `#match?`/`#not-match?` run on the `regex` crate, which is deterministic and supports
+   * no backreferences or lookaround. `#is?`, `#is-not?`, `#set!`, or an operator the
+   * binding does not know is refused at compile time.
    */
-  query: string
+  query: string | Partial<Record<LanguageId, string>>
   /** A per-invocation budget overriding the default, in milliseconds. */
   timeout?: number
   /** Called once per query match. */
@@ -287,6 +308,15 @@ export interface Config {
     /** Wall-clock, for the whole run. */
     global?: number
   }
+  /** Policy for suppression directives. All off by default. */
+  suppressions?: {
+    /** A valid directive with no `expires:` is reported. */
+    requireExpiry?: boolean
+    /** An expiry more than this many days after today is reported. */
+    maxExpiryDays?: number
+    /** Any whole-file directive is reported. */
+    forbidFileScope?: boolean
+  }
   /** The rules to run, in order. */
   rules: Rule[]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lanekeep",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Deterministic, AST-based architectural conformance checking",
   "license": "MIT OR Apache-2.0",
   "repository": {
@@ -23,10 +23,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@lanekeep/darwin-arm64": "0.6.1",
-    "@lanekeep/linux-arm64": "0.6.1",
-    "@lanekeep/linux-x64": "0.6.1",
-    "@lanekeep/win32-x64": "0.6.1"
+    "@lanekeep/darwin-arm64": "0.8.0",
+    "@lanekeep/linux-arm64": "0.8.0",
+    "@lanekeep/linux-x64": "0.8.0",
+    "@lanekeep/win32-x64": "0.8.0"
   },
   "main": "index.js",
   "types": "index.d.ts",