lanekeep 0.10.0 → 0.11.0

package/index.d.ts

@@ -8,12 +8,14 @@
  * 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
+ * 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; and `types` is added
+ * 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.
  */
 
@@ -374,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
@@ -413,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. */
@@ -463,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`. */
@@ -474,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. */
@@ -557,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.10.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.10.0",
-    "@lanekeep/linux-arm64": "0.10.0",
-    "@lanekeep/linux-x64": "0.10.0",
-    "@lanekeep/win32-x64": "0.10.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",