lanekeep 0.4.0 → 0.6.0

package/README.md

@@ -2,220 +2,355 @@
 
 **Deterministic, AST-based architectural conformance checking for AI-generated and human-written code.**
 
+[![crates.io](https://img.shields.io/crates/v/lanekeep-cli?label=crates.io)](https://crates.io/crates/lanekeep-cli)
+[![npm](https://img.shields.io/npm/v/lanekeep?label=npm)](https://www.npmjs.com/package/lanekeep)
+[![PyPI](https://img.shields.io/pypi/v/lanekeep?label=pypi)](https://pypi.org/project/lanekeep/)
+[![CI](https://github.com/fmsouza/lanekeep/actions/workflows/ci.yml/badge.svg)](https://github.com/fmsouza/lanekeep/actions/workflows/ci.yml)
 [![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)
 
-> **Status: early development.** Nothing is released yet and the CLI described below is not
-> usable. The architecture is settled — see [`docs/architecture.md`](docs/architecture.md) — and
-> the work is tracked as a sequence of milestones. Do not depend on this yet.
+lanekeep enforces the conventions that live in your team's heads and your reviewers' comments —
+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.
 
 ---
 
-## What it is
+## Quick start
+
+Sixty seconds, from nothing to a rule catching something.
+
+**1. Install** — whichever fits the project you are adding it to:
+
+```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>
+
+**2. Scaffold a config and a first rule:**
 
-lanekeep is not a linter in the ESLint sense. ESLint enforces language-level correctness.
-lanekeep enforces *project-specific conventions* — the ones a language model has no way to infer
-from the code it is shown, because they live in your team's heads and your reviewers' comments.
+```bash
+npx lanekeep init
+```
+
+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.
 
-Every rule is a codified answer to **"the agent keeps doing this wrong."**
+**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
+```
 
-Rules are TypeScript programs, written in the same language as the code they inspect:
+> **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.
+
+---
+
+## 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-numeric-sizes',
+  id: 'local/no-fmt-println',
+  language: 'go',
   severity: 'error',
 
   card: {
-    message: 'Literal numeric size inside makeStyles',
-    remediation: 'Use theme.spacing.*, theme.borderRadius.* or theme.borders.*',
-    examples: { bad: 'padding: 12', good: 'padding: theme.spacing.md' },
+    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: `
-    (pair
-      key: (property_identifier) @prop
-      value: [(number) (unary_expression operand: (number))] @value) @match
+    (call_expression
+      function: (selector_expression
+        operand: (identifier) @pkg
+        field: (field_identifier) @fn)) @call
   `,
 
   check(ctx, m) {
-    if (!/^(padding|margin|gap|borderRadius)/.test(ctx.text(m.prop))) return
-    if (Number(ctx.text(m.value)) === 0) return
+    if (ctx.text(m.pkg) !== 'fmt') return
+    if (ctx.text(m.fn) !== 'Println') return
 
-    const call = ctx.closestAncestor(m.match, '(call_expression function: (identifier) @f)')
-    if (!call) return
-    if (!ctx.resolvesToImport(call.f, { module: '@rneui/themed', name: 'makeStyles' })) 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.match)
+    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.
 
-## Why it exists
+**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.
 
-An agent that writes code against your codebase will violate your conventions confidently and
-repeatedly, because those conventions are invisible in the code it was shown. Telling it again in
-the next prompt does not scale. Encoding the convention as a rule does.
+**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.
 
-That makes the design constraints unusual for a static analyzer:
+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.
 
-- **It runs in the inner loop.** Agents and developers invoke it after every edit, so a cold run
-  on a couple of thousand files has a sub-second budget and a warm run has a sub-25ms one.
-- **Its output is read by a machine.** Violations are sorted deterministically, because an agent
-  that reads the output twice must not see reordering as change.
-- **Every rule carries its own fix.** `message`, `remediation` and `examples` are mandatory
-  fields, not documentation — they are the rule card that gets fed back to the agent.
+## Supported languages
 
-## How it stays fast with programmable rules
+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.
 
-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.
+| 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` |
 
-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.
+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.
 
-```
-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
-  └─> reduce phase: cross-file rules consume facts only, never parse trees
-  └─> filter suppressions ─> sort ─> report
-```
+**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.
 
-A warm run with no changes executes no JavaScript at all — every file is a cache hit.
+## Configuration
 
-## Installation
+`lanekeep.json`, at the project root. `lanekeep init` writes one for you, matched to the
+project it finds.
 
-Pick whichever matches the project you are adding it to:
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/fmsouza/lanekeep/main/schema/lanekeep.schema.json",
 
-```bash
-npm install --save-dev lanekeep      # Node
-pip install lanekeep                 # Python
-brew install fmsouza/tap/lanekeep    # macOS and Linux, system-wide
-cargo install lanekeep-cli           # from source
-```
+  "include": ["**/*.go"],
+  "exclude": ["**/*_test.go"],
 
-For a Go project, pin it in `go.mod` alongside your other tools:
-
-```bash
-go get -tool github.com/fmsouza/lanekeep/cmd/lanekeep
+  "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"
+  ]
+}
 ```
 
-then `go tool lanekeep check ./...`. Go can only install and pin things written in Go, so
-that package is a small launcher which 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.
+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.
 
-Or download a binary from the [releases page](https://github.com/fmsouza/lanekeep/releases).
+**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.
 
-A single static binary with the JavaScript engine compiled in. **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.
+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.
 
-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.
-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.
+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.
 
-See [`docs/releasing.md`](docs/releasing.md) for how a release is cut.
+<details>
+<summary>Configuring in TypeScript instead</summary>
 
-## What it looks like
+`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.
 
-```
-$ lanekeep check
-src/also.ts:2:1 error [lanekeep/no-default-export] default export
-  → use a named export, so the symbol has one name every importer must use
-src/bad.ts:2:1 error [lanekeep/no-default-export] default export
-  → use a named export, so the symbol has one name every importer must use
+```ts
+import { defineConfig } from 'lanekeep'
+import noDefaultExport from 'lanekeep/no-default-export'
+import noDebugger from './lanekeep/rules/no-debugger'
 
-✖ 2 error(s) across 2 file(s) checked
+export default defineConfig({
+  include: ['src/**/*.{ts,tsx}'],
+  rules: [noDefaultExport, noDebugger],
+})
 ```
 
-Rules may offer a fix, applied with `--fix`:
+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.
 
-```
-$ lanekeep check --fix
-fixed 2 violation(s) in 2 file(s)
+</details>
+
+## Using it
+
+```bash
+lanekeep check                  # the whole project
+lanekeep check --staged         # only what is about to be committed
+lanekeep check --since main     # only what changed against a ref
+lanekeep check --watch          # re-check on every change, until Ctrl-C
+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
 ```
 
-Only fixes a rule marked as behavior-preserving are 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.
+`--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.
 
-Suppressions carry a mandatory reason and an optional expiry, and a directive that does not
-work says so — a missing reason, a bare rule id, or an unreadable date is reported rather
-than silently doing nothing:
+**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
 ```
 
-```
-$ lanekeep check --report-unused-suppressions
-```
+Run `lanekeep check --report-unused-suppressions` to find the ones that no longer silence
+anything.
 
-To start from nothing:
+**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.
 
-```
-$ lanekeep init          # a config plus a first rule, both runnable
-```
+**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.
 
-To find out where a run spent its time — the split says whether the query or the code is
-the problem:
+## In CI, editors and agents
 
-```
-$ lanekeep check --profile
+```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
 ```
 
-To find out what a rule wants without opening its source:
+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.
 
-```
-$ lanekeep explain lanekeep/no-default-export
-$ lanekeep rules --json
-```
+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)**.
 
-For fast feedback on what you touched:
+## 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 check --staged     # what is about to be committed
-$ lanekeep check --since main # what changed against a ref
+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
+  └─> reduce phase: cross-file rules consume facts only, never parse trees
+  └─> filter suppressions ─> sort ─> report
 ```
 
-Both 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, not a smaller one, so they are
-skipped and named on stderr rather than quietly producing one.
+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
+
+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.
 
-Exit `0` when clean, `1` when violations are found, `2` when the checker could not run —
-a caller has to be able to tell "your code has problems" from "the tool is broken".
-Four output formats: `human` (default), `json` (versioned, stable schema), `sarif` (GitHub
-code scanning), and `agent` — token-minimal, grouped by rule rather than by file, with each
-rule's card stated once instead of once per violation. Diagnostics always go to stderr, so
-piping into a parser works even when something fails.
+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.
+
+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.
 
 ## Documentation
 
+**The [wiki](https://github.com/fmsouza/lanekeep/wiki) is the place to start** — it is task-shaped and organized by language.
+
+| Page | Purpose |
+| --- | --- |
+| [Getting Started](https://github.com/fmsouza/lanekeep/wiki/Getting-Started) | Install and catch something, in about a minute |
+| [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:
+
 | Document | Purpose |
 | --- | --- |
 | [`docs/architecture.md`](docs/architecture.md) | The full design: execution model, host API, cache, milestones |
 | [`docs/built-in-rules.md`](docs/built-in-rules.md) | The rules lanekeep ships with, and their options |
 | [`docs/cross-file-rules.md`](docs/cross-file-rules.md) | Writing a rule that needs a whole-corpus view |
-| [`AGENTS.md`](AGENTS.md) | How to work in this repository — for coding agents and humans alike |
+| [`docs/adr/`](docs/adr/) | Decision records: why the design is the way it is |
 | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Setup, commands, and the pull request process |
+| [`AGENTS.md`](AGENTS.md) | How to work in this repository — for coding agents and humans alike |
 | [`SECURITY.md`](SECURITY.md) | Threat model and how to report a vulnerability |
 | [`docs/releasing.md`](docs/releasing.md) | How a release is built, gated and published |
+| [`CHANGELOG.md`](CHANGELOG.md) | What changed, per release |
 
 ## Security
 
@@ -228,10 +363,10 @@ Rules are executable code, so the posture is about confinement rather than absen
 - **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 15-second 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.
+- **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.
 
@@ -239,14 +374,33 @@ This bounds blast radius and makes third-party rule sets reviewable. It is not a
 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 [`CONTRIBUTING.md`](CONTRIBUTING.md) — `./scripts/setup-dev.sh` installs everything and
-wires the git hooks.
+Contributions are welcome, particularly new built-in rules and new host API surface. Start with
+[`CONTRIBUTING.md`](CONTRIBUTING.md) — `./scripts/setup-dev.sh` installs everything and wires the
+git hooks, and `just check` is the same gate CI runs.
 
-All work ships as squashed pull requests with [Conventional Commits](https://www.conventionalcommits.org/)
-titles. `main` is protected and takes no direct pushes.
+All work ships as squashed pull requests with
+[Conventional Commits](https://www.conventionalcommits.org/) titles. `main` is protected and takes
+no direct pushes.
 
 ## License
 

package/builtin.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Types reached through the `typesVersions` mapping in `package.json`.
+ *
+ * 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.
+ */
+export * from './index'
+
+import type { Rule } from './index'
+
+declare const rule: Rule & ((options?: Record<string, unknown>) => Rule)
+export default rule

package/index.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Type definitions for authoring lanekeep rules.
+ *
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+export type Node = number & { readonly __lanekeepNode: unique symbol }
+
+/** How a name was introduced, as `ctx.bindingKind` reports it. */
+export type BindingKind =
+  | 'import'
+  | 'const'
+  | 'let'
+  | 'var'
+  | 'param'
+  | 'function'
+  | 'class'
+  | 'catch-param'
+  | 'assignment'
+  | 'loop'
+  | 'context-manager'
+  | 'comprehension'
+  | 'type'
+  | 'receiver'
+  | 'type-param'
+  | 'module'
+  | 'trait'
+
+/** A language lanekeep can parse. */
+export type LanguageId = 'typescript' | 'tsx' | 'javascript' | 'python' | 'go' | 'rust'
+
+/** How serious a violation is. */
+export type Severity = 'error' | 'warn' | 'off'
+
+/**
+ * The captures of one query match, keyed by capture name without the `@`.
+ *
+ * A capture that did not participate in the match is absent, which is why the values are
+ * optional — an alternation like `[(a) (b)] @x` binds `@x` either way, but two separate
+ * patterns capturing different names do not.
+ */
+export type Match = Record<string, Node | undefined>
+
+/**
+ * What a rule tells whoever has to act on the violation — increasingly an agent.
+ *
+ * Not documentation, and not optional. `remediation` is the field worth the effort: it should
+ * say what to do, not restate the problem.
+ */
+export interface RuleCard {
+  /** What is wrong, in a few words. */
+  message: string
+  /** What to do about it. */
+  remediation: string
+  /** One example each way. */
+  examples: {
+    bad: string
+    good: string
+  }
+}
+
+/** Cheap rejections applied before a file is parsed. */
+export interface Gates {
+  /**
+   * Literal substrings a file's raw bytes must contain. A file missing any one of them is
+   * never parsed.
+   *
+   * **This is an *and*, not an *or*.** A rule matching either of two tokens cannot express
+   * its gate as `['a', 'b']` — that rejects any file containing only one, which is usually
+   * most of them, and the rule then reports nothing while looking healthy. There is no `or`
+   * form; omit the gate when no single substring covers every case.
+   */
+  fileContains?: string[]
+}
+
+/** A replacement a rule offers for a violation. */
+export interface Fix {
+  /** The node whose text is replaced. */
+  node: Node
+  /** What to replace it with. */
+  text: string
+  /**
+   * Whether the fix preserves behavior.
+   *
+   * Only a fix marked `true` is applied by `--fix`. Anything else is a suggestion — shown,
+   * never written — because the cautious mistake costs a manual edit and the other one
+   * rewrites someone's code silently.
+   */
+  safe?: boolean
+}
+
+/** Options for a single report. */
+export interface ReportOptions {
+  /** Overrides the card's `message` for this one violation. */
+  message?: string
+  /** A replacement to offer. */
+  fix?: Fix
+}
+
+/**
+ * A fact a rule emits for the reduce phase.
+ *
+ * `kind` is required and must be non-empty, because it is what `ctx.facts('...')` filters on.
+ * A fact without one could never be retrieved, so emitting it is always a mistake — and a
+ * silent one, since the rule would look like it was working right up until `reduce` found
+ * nothing. lanekeep throws rather than accept it.
+ */
+export interface Fact {
+  kind: string
+  [key: string]: unknown
+}
+
+/** A fact as `reduce` receives it, with the file that emitted it. */
+export interface EmittedFact extends Fact {
+  /** Path of the file this came from, relative to the project root. */
+  file: string
+}
+
+/** What a rule's `check` handler reaches. */
+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.
+   */
+  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
+  /** 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. */
+export interface ReduceLocation {
+  /** Path relative to the project root. */
+  file: string
+  /** One-based. */
+  line?: number
+  /** One-based. */
+  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.
+ */
+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
+}
+
+/** A rule, as `defineRule` takes it. */
+export interface Rule {
+  /**
+   * Namespaced identifier, as `namespace/name`.
+   *
+   * `local/` needs no declaration and `lanekeep/` is reserved for built-ins; any other
+   * namespace must be listed in the config's `namespaces`.
+   */
+  id: string
+  /**
+   * Which languages this rule applies to.
+   *
+   * **Defaults to `['typescript', 'tsx']`**, and this is the field most worth getting right
+   * on a rule for anything else. The grammar is chosen by the file, not by the rule, and a
+   * rule does not run on a file whose language it does not name — so omitting this on a Go
+   * or Rust rule means it silently never fires.
+   */
+  language?: LanguageId | LanguageId[]
+  /** How serious a violation is, before any config override. */
+  severity: Severity
+  /** What the rule tells whoever has to act on it. */
+  card: RuleCard
+  /** Cheap rejections before parsing. */
+  gates?: Gates
+  /**
+   * The tree-sitter query gating the handler.
+   *
+   * 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.
+   */
+  query: string
+  /** A per-invocation budget overriding the default, in milliseconds. */
+  timeout?: number
+  /** Called once per query match. */
+  check?(ctx: RuleContext, match: Match): void
+  /** Called once per run, after every file, with facts only. */
+  reduce?(ctx: ReduceContext): void
+}
+
+/** A lanekeep configuration, as `defineConfig` takes it. */
+export interface Config {
+  /** Globs selecting files to check, relative to the project root. */
+  include?: string[]
+  /** Globs removing files from that selection. */
+  exclude?: string[]
+  /** Rule-id namespaces this project uses beyond `local`. */
+  namespaces?: string[]
+  /** Override a rule's own severity, by id. */
+  severity?: Record<string, Severity>
+  /** Execution budgets, in milliseconds. */
+  timeouts?: {
+    /** Per rule invocation. */
+    rule?: number
+    /** Wall-clock, for the whole run. */
+    global?: number
+  }
+  /** The rules to run, in order. */
+  rules: Rule[]
+}
+
+/**
+ * Define a rule.
+ *
+ * An identity function. It exists so the compiler checks the object against {@link Rule}
+ * where it is written, rather than reporting a mismatch from wherever it is imported.
+ */
+export declare function defineRule(rule: Rule): Rule
+
+/**
+ * Define a configuration.
+ *
+ * An identity function, for the same reason as {@link defineRule}. Most projects will write
+ * `lanekeep.json` instead — configuration is data, and only rules need to be programs.
+ */
+export declare function defineConfig(config: Config): Config

package/index.js

@@ -0,0 +1,15 @@
+// The runtime half of the authoring package.
+//
+// Rules never execute in Node — lanekeep evaluates them in its own sandbox, where `lanekeep`
+// resolves to a host module rather than to this file. These exports exist so that a tool
+// which *does* load a rule under Node (a bundler, a test runner, an editor's type server
+// following the import) finds something coherent instead of a missing module.
+//
+// Identity functions, which is also what they are inside the sandbox: their entire job is to
+// give the compiler a place to check the object against a type.
+'use strict'
+
+const identity = (value) => value
+
+module.exports = { defineRule: identity, defineConfig: identity }
+module.exports.default = module.exports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lanekeep",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Deterministic, AST-based architectural conformance checking",
   "license": "MIT OR Apache-2.0",
   "repository": {
@@ -14,15 +14,27 @@
   "files": [
     "bin/lanekeep",
     "resolve.js",
+    "index.js",
+    "index.d.ts",
+    "builtin.d.ts",
     "README.md"
   ],
   "engines": {
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@lanekeep/darwin-arm64": "0.4.0",
-    "@lanekeep/linux-arm64": "0.4.0",
-    "@lanekeep/linux-x64": "0.4.0",
-    "@lanekeep/win32-x64": "0.4.0"
+    "@lanekeep/darwin-arm64": "0.6.0",
+    "@lanekeep/linux-arm64": "0.6.0",
+    "@lanekeep/linux-x64": "0.6.0",
+    "@lanekeep/win32-x64": "0.6.0"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "builtin.d.ts"
+      ]
+    }
   }
 }