lanekeep 0.8.1 → 0.10.0

package/README.md

@@ -7,6 +7,7 @@
 [![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)
+[![MSRV](https://img.shields.io/badge/MSRV-1.94-blue.svg)](Cargo.toml)
 
 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
@@ -67,20 +68,18 @@ Three things follow from who reads the output:
   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.
+  is measured in tens of milliseconds. The built-ins that ship as WebAssembly components are all
+  under 115 KB, so loading them is noise — a 12.4 MiB compiled-TypeScript component that once
+  cost new TypeScript projects ~6.5 seconds on their first run was reverted for exactly that
+  reason.
+  [`docs/architecture.md`](docs/architecture.md) §15 has the ledger.
 
 **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
+WebAssembly component, which is how four of the sixteen built-ins ship — two written in Rust
+and two written in Go; the other twelve run as QuickJS modules, three of them checking five of
+the six supported languages from a single source (every one but JavaScript). 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.
 
@@ -90,9 +89,10 @@ actual rule.
 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 --file src/a.ts  # exactly these files, repeatable, no git involved
 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 check --profile        # per rule: where the time went, and what it looked at
 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
@@ -183,7 +183,9 @@ Known gaps, stated rather than implied:
 - **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.
+- **No general type inference**, by design. Name resolution is syntactic; a rule that opts in
+  (`requires: ['types']`) gets a bounded within-file oracle that answers `undefined` rather than
+  guess — see §1 non-goals and §6.10.
 
 ## Documentation
 
@@ -204,7 +206,11 @@ In-repo, versioned with the code:
 | [`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 |
-| [`docs/adr/`](docs/adr/) | Decision records: why the design is the way it is |
+| [`docs/obligation-rules.md`](docs/obligation-rules.md) | Writing a rule that needs a resource released on every path |
+| [`docs/type-aware-rules.md`](docs/type-aware-rules.md) | Writing a rule that needs to know what a value's type is |
+| [`docs/authoring-rust-rules.md`](docs/authoring-rust-rules.md) | Writing a rule in Rust, shipped as a WebAssembly component |
+| [`docs/authoring-go-rules.md`](docs/authoring-go-rules.md) | Writing a rule in Go |
+| [`docs/authoring-python-rules.md`](docs/authoring-python-rules.md) | Writing a rule in Python |
 | [`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 |

package/index.d.ts

@@ -8,11 +8,13 @@
  * 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.
  * 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.
+ * 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 `types` is added
+ * to `RuleContext` because `ctx.types` — the bounded
+ * type oracle — is QuickJS-only and has no presence in `world.wit` at all: a component rule
+ * cannot declare `requires`, so there is nothing for the world to say about it. Nothing else is
+ * added or omitted by hand.
  */
 
 /**
@@ -78,7 +80,23 @@ export interface RuleCard {
   }
 }
 
-/** Cheap rejections applied before a file is read or parsed. */
+/**
+ * Cheap rejections applied before a file is read or parsed.
+ *
+ * A gate is declared, not derived: nothing here is computed from the rule's `query`, and
+ * nothing checks the two against each other. So a gate can change what the rule reports — a
+ * file it rejects is a file the rule never runs on, and a violation there is never found.
+ *
+ * A gate is neutral when it admits every file the rule would have reported on — yours to
+ * keep, and not something the engine can check. The safe way to keep it is to gate wider
+ * than the query, which is sufficient rather than necessary: a rule whose handler filters
+ * may gate far narrower and still be neutral. `--profile` prints, per rule, how many files
+ * each gate rejected and how many the rule actually parsed, which is where a suspected gate
+ * is settled. A nonzero `cached` means the columns to its right are
+ * incomplete for that run, since a cache hit returns before the content gates are consulted;
+ * pair `--profile` with `--no-cache` to read them. `path-gated` is unaffected, because a path
+ * gate runs before the cache is consulted at all.
+ */
 export interface Gates {
   /**
    * Glob patterns a file's path must match for the rule to consider it.
@@ -117,7 +135,13 @@ export interface Gates {
   fileNotContains?: string[]
 }
 
-/** A replacement a rule offers for a violation. */
+/**
+ * A replacement a rule offers for a violation.
+ *
+ * A per-file offer alone: a fix names a node, and the reduce phase consumes facts and the
+ * file list and nothing else — there is no parse tree there for `node` to name, which is why
+ * a reduce report's options carry a message and never a fix.
+ */
 export interface Fix {
   /** The node whose text is replaced. */
   node: Node
@@ -141,6 +165,20 @@ export interface ReportOptions {
   fix?: Fix
 }
 
+/** Options for a single reduce report. */
+export interface ReduceReportOptions {
+  /** Overrides the card's `message` for this one violation. */
+  message?: string
+  /**
+   * Never present. A fix replaces a node's text, and the reduce phase has no parse tree —
+   * `node` has nothing to name, and both hosts throw on a supplied fix rather than drop it.
+   * Typed `never` rather than left absent so offering one fails to compile even for an
+   * object built before the call, which a fresh literal's excess-property check alone would
+   * admit.
+   */
+  fix?: never
+}
+
 /**
  * A fact a rule emits for the reduce phase.
  *
@@ -191,6 +229,151 @@ export interface StructureFingerprint {
   nodes: number
 }
 
+/**
+ * Where a name came from. Returned by {@link TypeApi.symbolOf} directly, and nested under a
+ * {@link TypeInfo} whose `symbol` field is set.
+ *
+ * There is deliberately no `file` naming the declaring path, even now that declarations are
+ * read across files. It would be where a package happens to be installed —
+ * `node_modules/@types/money/index.d.ts` on one machine and a workspace path on another —
+ * so a rule branching on it would give different answers for one program. `module` is the
+ * stable identity, and `exported` is the name that module declares it under.
+ */
+export interface SymbolInfo {
+  /**
+   * The name as it appears at the use site, not at the declaration. For a renamed import —
+   * `import { Decimal as Money }` — this is the local alias `Money`. It is the spelling to
+   * quote in a message, because it is the spelling the reader has in front of them; compare
+   * `exported` when the question is which export of a module this is.
+   */
+  name: string
+  /**
+   * The name the module exports this under. For a named import — `import { Decimal }` and
+   * `import { Decimal as Money }` alike — this is `Decimal` when `m`'s declaration file is
+   * unreadable, and the name that file actually declares (following any re-export chain)
+   * when it is readable, which need not be `Decimal` at all. Copied even when nothing was
+   * renamed, so a comparison never needs a fallback to `name` that would silently accept
+   * every plain import if it were forgotten. For a default import this is the name the
+   * declaration file declares the default export under when that file is readable — `Big`
+   * for a package whose default export is `Big`, whatever the local binding is called — and
+   * falls back to the placeholder `default` only when the declaration is not readable.
+   * Absent for a namespace import, which binds the module object and has no single exported
+   * name, and absent for a local declaration, which was not imported at all.
+   */
+  exported?: string
+  /**
+   * The module it was imported from. Absent for a local declaration — that absence is what
+   * distinguishes an imported `Decimal` from a local class that happens to share the name.
+   */
+  module?: string
+}
+
+/**
+ * What the oracle established about an expression, from {@link TypeApi.typeOf}.
+ *
+ * At most one of `primitive`, `symbol` or `union` is set, matching which kind of type this
+ * is — a `union`'s members are already flattened one level and in canonical order. `text` is
+ * set alongside whichever it is, but it is **display-only**: what TypeScript itself would
+ * call the type, for a message a rule builds. Branch on `primitive` and `symbol`, never on
+ * `text`'s wording.
+ *
+ * All three can be unset at once: a *nominal* type whose name the resolver could not
+ * attribute — an unresolvable, global or ambient type such as `Date` used with no local
+ * declaration or import — carries only `text`. That is not a gap to code around; it is
+ * another shape of the same "I could not be sure" answer this whole surface is built on,
+ * the same posture `typeOf` itself takes by returning `undefined` rather than guessing. Do
+ * not assume the final branch of `if (primitive) … else if (symbol) … else` is unreachable
+ * — for this shape, it is not.
+ *
+ * There is deliberately no `complete` field on a *type*. Whether the oracle had a full view
+ * is a property of the file rather than of any one answer — `TypeApi.complete()` is where it
+ * is asked — and putting it here would invite a rule to read it per type and conclude
+ * something different on each.
+ */
+export interface TypeInfo {
+  /** What TypeScript would call this type. Display-only — branch on the fields below instead. */
+  text: string
+  /** Set when this is a primitive — exactly the set TypeScript itself recognizes as one. */
+  primitive?: 'number' | 'string' | 'boolean' | 'bigint' | 'symbol' | 'null' | 'undefined'
+  /**
+   * Set when this is a named type and the oracle could resolve where the name came from.
+   * Absent on an unresolvable, global or ambient nominal type — see the interface doc above.
+   */
+  symbol?: SymbolInfo
+  /** Set when this is a union. */
+  union?: TypeInfo[]
+}
+
+/**
+ * The type oracle, reached through `ctx.types`.
+ *
+ * Every question can come back with no answer, and no answer is a first-class result rather
+ * than a failure to work around: the oracle is conservative on purpose, and it would rather
+ * say nothing than say something wrong, because a rule reporting on a wrong type accuses
+ * correct code. A rule is expected to check for `undefined` and quietly stay silent, the same
+ * posture the rest of the navigation surface already takes on a dead handle.
+ *
+ * It reads the file in front of it **and the declaration files that file imports**, through
+ * the same tracked, confined reads `ctx.readFile` uses. Nothing above the project root is read,
+ * ever — so point lanekeep at the workspace root, the directory `node_modules` lives in,
+ * rather than at a package inside it. `--config` does not move the root.
+ */
+export interface TypeApi {
+  /**
+   * The type of the expression at `n`. `undefined` is that first-class no-answer, not a
+   * failure.
+   */
+  typeOf(n: Node): TypeInfo | undefined
+  /** Where the identifier at `n` was declared. `undefined` on the same terms as `typeOf`. */
+  symbolOf(n: Node): SymbolInfo | undefined
+  /**
+   * What calling the function at `n` yields.
+   *
+   * Separate from `typeOf` because a function declaration is not an expression. Accepts a
+   * call expression, a function-like declaration, or an identifier bound to one. An
+   * annotated signature answers its annotation; an unannotated one with a single `return`
+   * answers that expression's type; several returns answer their union when every member is
+   * known and `undefined` otherwise; a function with no `return` answers `undefined` rather
+   * than guessing `void`. Type arguments are dropped throughout — `useQuery<Balance[]>`
+   * answers by the result type's name, never by the argument.
+   */
+  returnTypeOf(n: Node): TypeInfo | undefined
+  /**
+   * Whether the type at `n` is the type `module` exports as `name`, or inherits from it.
+   *
+   * Nominal, never structural: a class reaches it through `extends` or `implements`, an
+   * interface through `extends`, an alias by being transparent, and a union only when *every*
+   * member does. A primitive answers `false` — but only when `module` and `name` resolve to a
+   * declaration; a target that does not resolve answers `undefined` whatever `n` is.
+   *
+   * **`undefined` is not `false`.** `false` means the walk completed and reached nothing;
+   * `undefined` means a link could not be read — an unresolvable import, a package that is
+   * not installed, a type with no symbol at all. A rule treating the two alike reports on
+   * code the oracle never saw.
+   */
+  isAssignableTo(n: Node, module: string, name: string): boolean | undefined
+  /**
+   * Whether every import in the file being checked resolved to something readable.
+   *
+   * `false` is the honest label on a partial view: some name in this file came from a module
+   * the oracle could not open, so an `undefined` anywhere in it may be ignorance rather than
+   * a considered answer. A rule that reports only on what it established does not need to
+   * ask; a rule that wants to say "I could not check this file" does.
+   *
+   * An import that resolves to a file which does not *parse* counts as unreadable too: the
+   * names outside the broken span still answer, the ones inside it come back `undefined`, and
+   * nothing on either answer says which. An import of something that is not code — a
+   * stylesheet, a JSON asset, an image — is not counted at all, since it is not a module the
+   * oracle reads.
+   *
+   * **The verdict is the whole file's, and a parse fault is the whole declaration file's.**
+   * One `ERROR` node anywhere in a fifty-thousand-line `@types` bundle makes every file that
+   * imports it `false`, however far that span is from the names the rule asked about. Silence
+   * is the safe direction; a narrower verdict is a refinement rather than a promise.
+   */
+  complete(): boolean
+}
+
 /** A rule's RuleContext surface. */
 export interface RuleContext {
   readonly filePath: string
@@ -217,8 +400,19 @@ export interface RuleContext {
   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[]
+  /**
+   * The type oracle, present only for a rule that declared `requires: ['types']`.
+   * Bounded by a fixed depth rather than by file: it follows an import into the
+   * declaration file that answers it, and the file after that.
+   *
+   * Typed as always present because there is no way to spell "present when
+   * this rule's own `requires` says so" as a type — so a rule that forgets the
+   * declaration still compiles. It finds out at the first call instead:
+   * `ctx.types` is `undefined` at run time, and `ctx.types.typeOf(...)` throws a
+   * `TypeError` rather than returning a quietly wrong answer. That loudness is
+   * deliberate.
+   */
+  types: TypeApi
 }
 
 /** A violation the reduce phase reports, which has no node to point at. */
@@ -235,7 +429,51 @@ export interface ReduceLocation {
 export interface ReduceContext {
   readonly files: string[]
   facts(kind?: string): EmittedFact[]
-  report(at: ReduceLocation, message?: string | ReportOptions): void
+  /** Takes a message; a supplied `fix` throws — there is no node to attach one to. */
+  report(at: ReduceLocation, message?: string | ReduceReportOptions): void
+}
+
+/** Queries whose named captures drive the taint analysis. */
+export type FlowSpec = {
+  /** Queries whose `@source` capture marks a tainted origin. */
+  sources: string[]
+  /** Queries whose `@sink` capture marks a forbidden destination. */
+  sinks: string[]
+  /** Queries whose `@sanitizer` capture clears taint from the value it produces. */
+  sanitizers?: string[]
+}
+
+/** One tainted flow: a source whose value reaches a sink with no intervening sanitizer. */
+export type FlowPath = {
+  readonly source: Node
+  readonly sink: Node
+  /** The assignments and calls between source and sink, in flow order. One canonical path. */
+  readonly steps: readonly Node[]
+}
+
+/**
+ * A typestate obligation: an acquired resource must reach a release on every
+ * path out of `scope`. Requires `requires: ['dataflow']`.
+ */
+export type ObligationSpec = {
+  /** Queries whose `@acquire` capture starts an obligation on the captured value. */
+  acquire: string[]
+  /** Queries whose `@release` capture discharges it. */
+  release: string[]
+  /**
+   * `'function'` — every path out of the enclosing function, `return`/`throw` included.
+   * `'block'` — every path out of the block the acquire is in.
+   */
+  scope: 'function' | 'block'
+}
+
+/** An acquire some path leaves undischarged, passed to `checkObligation`. */
+export type UnmetObligation = {
+  readonly acquire: Node
+  /** The exit the value escapes through — a `return`, a `throw`, or the implicit end. */
+  readonly exit: Node
+  /** Whether any path *did* discharge it: partial coverage reads differently to none. */
+  readonly partial: boolean
 }
 
 /** A rule, as `defineRule` takes it. */
@@ -256,6 +494,15 @@ export interface Rule {
    * or Rust rule means it silently never fires.
    */
   language?: LanguageId | LanguageId[]
+  /**
+   * Host analyses this rule needs before it can run.
+   *
+   * Absent means none, which is every rule today. A rule declaring one the engine cannot
+   * provide is refused at load rather than run without it: an analysis that silently goes
+   * missing makes the rule report nothing, and a rule reporting nothing is indistinguishable
+   * from a codebase with nothing to report.
+   */
+  requires?: Array<'types' | 'dataflow'>
   /** How serious a violation is, before any config override. */
   severity: Severity
   /** What the rule tells whoever has to act on it. */
@@ -269,6 +516,11 @@ export interface Rule {
    * what keeps a JavaScript rule affordable. Write the narrowest query that captures what
    * you need; `check` then only refines.
    *
+   * Optional — required only when `check` is present. A flow-only rule (`checkFlow` with no
+   * `check`) declares no top-level query; its file gate comes from the union of its `flow`
+   * queries instead (see {@link FlowSpec}). The type cannot express that conditional, so a
+   * `check` rule missing `query` type-checks here and is refused by the config loader instead.
+   *
    * 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`).
@@ -282,13 +534,29 @@ export interface Rule {
    * no backreferences or lookaround. `#is?`, `#is-not?`, `#set!`, or an operator the
    * binding does not know is refused at compile time.
    */
-  query: string | Partial<Record<LanguageId, string>>
+  query?: string | Partial<Record<LanguageId, 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 taint-flow specification: queries whose captures mark tainted origins, forbidden
+   * destinations, and the calls that neutralize a value. Requires `requires: ['dataflow']`
+   * and a `checkFlow` handler; a rule declaring one without the other is refused at load.
+   */
+  flow?: FlowSpec
+  /** Called once per canonical tainted flow from a source to a sink. */
+  checkFlow?(ctx: RuleContext, path: FlowPath): void
+  /**
+   * A typestate obligation: queries whose captures acquire an obligation on a value and
+   * queries that discharge it. Requires `requires: ['dataflow']` and a `checkObligation`
+   * handler; a rule declaring one without the other is refused at load.
+   */
+  obligation?: ObligationSpec
+  /** Called once per value left with an unmet obligation at the end of its scope. */
+  checkObligation?(ctx: RuleContext, unmet: UnmetObligation): void
 }
 
 /** A lanekeep configuration, as `defineConfig` takes it. */
@@ -307,6 +575,13 @@ export interface Config {
     rule?: number
     /** Wall-clock, for the whole run. */
     global?: number
+    /**
+     * Host-side type-provider work, across the whole run.
+     *
+     * Analysis time rather than elapsed time: only what the provider spends building
+     * programs and answering requests is charged against it.
+     */
+    analysis?: number
   }
   /** Policy for suppression directives. All off by default. */
   suppressions?: {
@@ -317,6 +592,19 @@ export interface Config {
     /** Any whole-file directive is reported. */
     forbidFileScope?: boolean
   }
+  /** Which type oracle answers `ctx.types`. */
+  types?: {
+    /**
+     * `builtin` is lanekeep's own bounded oracle and needs no toolchain. `tsc` drives the
+     * project's own `typescript` package through a sidecar process: wider answers, a slower
+     * run, and a pre-commit hook that builds the project's program before it checks anything.
+     */
+    provider?: 'builtin' | 'tsc'
+    /** How to launch the sidecar. `tsc` only. */
+    command?: string[]
+    /** The `typescript` package the sidecar loads, resolved from the project root. `tsc` only. */
+    typescript?: string
+  }
   /** The rules to run, in order. */
   rules: Rule[]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lanekeep",
-  "version": "0.8.1",
+  "version": "0.10.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.8.1",
-    "@lanekeep/linux-arm64": "0.8.1",
-    "@lanekeep/linux-x64": "0.8.1",
-    "@lanekeep/win32-x64": "0.8.1"
+    "@lanekeep/darwin-arm64": "0.10.0",
+    "@lanekeep/linux-arm64": "0.10.0",
+    "@lanekeep/linux-x64": "0.10.0",
+    "@lanekeep/win32-x64": "0.10.0"
   },
   "main": "index.js",
   "types": "index.d.ts",