lanekeep 0.9.0 → 0.11.0

package/README.md

@@ -89,6 +89,7 @@ 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        # per rule: where the time went, and what it looked at

package/index.d.ts

@@ -10,11 +10,12 @@
  * The world is the single source of truth for every member the renderer emits straight from it.
  * Three members deviate from the world on purpose, and all three 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; `facts` is added to
- * `RuleContext` because QuickJS hands a per-file rule `facts` that the world declares only on
- * `reduce-context`; and `types` is added to `RuleContext` because `ctx.types` — the bounded
+ * callable, a shape this renderer cannot state honestly from the world; `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
+ * cannot declare `requires`, so there is nothing for the world to say about it; and `flow` is
+ * added to `RuleContext` for the same reason — `ctx.flow`, the taint-analysis completeness
+ * surface, is QuickJS-only too and has no presence in `world.wit` either. Nothing else is
  * added or omitted by hand.
  */
 
@@ -136,7 +137,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
@@ -160,6 +167,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.
  *
@@ -355,6 +376,18 @@ export interface TypeApi {
   complete(): boolean
 }
 
+/**
+ * The taint-analysis completeness surface, present on `ctx.flow` for a rule that declares
+ * `flow`. Answers whether the analysis saw through every construct in the file being checked
+ * — so a rule can say "I could not verify this file" rather than nothing.
+ */
+export interface FlowApi {
+  /** `true` iff the analysis dropped no construct in this file (`dropped === 0`). */
+  complete(): boolean
+  /** How many constructs the analysis could not see through in this file. */
+  readonly dropped: number
+}
+
 /** A rule's RuleContext surface. */
 export interface RuleContext {
   readonly filePath: string
@@ -381,8 +414,6 @@ 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
@@ -396,6 +427,11 @@ export interface RuleContext {
    * deliberate.
    */
   types: TypeApi
+  /**
+   * The taint-analysis completeness surface, present only in the flow phase
+   * of a rule that declares `flow` (inside `checkFlow` / `checkFile`).
+   */
+  flow: FlowApi
 }
 
 /** A violation the reduce phase reports, which has no node to point at. */
@@ -412,7 +448,8 @@ 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. */
@@ -445,8 +482,18 @@ export type ObligationSpec = {
   /**
    * `'function'` — every path out of the enclosing function, `return`/`throw` included.
    * `'block'` — every path out of the block the acquire is in.
+   * `'module'` — a matching-`@key` release must exist somewhere in the file.
+   * `'class'` — a matching-`@key` release must exist in the same class.
+   * `'component'` — a matching-`@key` release must exist in the same React function component.
    */
-  scope: 'function' | 'block'
+  scope: 'function' | 'block' | 'module' | 'class' | 'component'
+  /**
+   * How a `@key` correlates an acquire with a release. `'text'` (default) — exact captured
+   * text. `'binding'` — shared value origin (follows copies/wrappers/ternaries); requires
+   * `@key`. Note: `'binding'` does not correlate distinct per-frame parameters — use `'text'`
+   * for the sibling-callback pattern.
+   */
+  keyBy?: 'text' | 'binding'
 }
 
 /** An acquire some path leaves undischarged, passed to `checkObligation`. */
@@ -456,6 +503,11 @@ export type UnmetObligation = {
   readonly exit: Node
   /** Whether any path *did* discharge it: partial coverage reads differently to none. */
   readonly partial: boolean
+  /**
+   * The acquire's `@key` capture, when the rule's acquire/release queries bind one — so a
+   * report can name the value. Absent for an un-keyed obligation.
+   */
+  readonly key?: Node
 }
 
 /** A rule, as `defineRule` takes it. */
@@ -539,6 +591,12 @@ export interface Rule {
   obligation?: ObligationSpec
   /** Called once per value left with an unmet obligation at the end of its scope. */
   checkObligation?(ctx: RuleContext, unmet: UnmetObligation): void
+  /**
+   * Called once per file the rule's flow phase examined, including files with no flow.
+   * Read `ctx.flow.complete()` / `ctx.flow.dropped` and report at `ctx.root` when the taint
+   * analysis could not see through every construct. Requires `flow`.
+   */
+  checkFile?(ctx: RuleContext): void
 }
 
 /** A lanekeep configuration, as `defineConfig` takes it. */

package/package.json

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