lanekeep 0.5.0 → 0.6.0

package/README.md

@@ -138,10 +138,13 @@ 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 are not shipped yet.** `defineRule` and `defineConfig` resolve inside lanekeep's
-> sandbox at run time, so rules execute correctly, but there is no published package supplying
-> TypeScript definitions for the host API — you will not get autocomplete on `ctx` today.
-> [`docs/architecture.md`](docs/architecture.md) §6 documents the full surface in the meantime.
+**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
 

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.5.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.5.0",
-    "@lanekeep/linux-arm64": "0.5.0",
-    "@lanekeep/linux-x64": "0.5.0",
-    "@lanekeep/win32-x64": "0.5.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"
+      ]
+    }
   }
 }