eslint-plugin-ownership 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# eslint-plugin-ownership
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Path-sensitive local ownership checking for TypeScript and roblox-ts. **v0.4.0 auto-discovers contracts from JSDoc** through TypeScript symbols. No method lists are needed in ESLint configuration.
+
+## Install
+
+```bash
+npm install -D eslint @typescript-eslint/parser typescript ./tools/eslint-plugin-ownership
+```
+
+Use a typed parser (TypeScript project service is required for annotation discovery):
+
+```js
+// eslint.config.mjs
+import tsParser from "@typescript-eslint/parser";
+import ownership from "eslint-plugin-ownership";
+
+export default [{
+  files: ["**/*.ts", "**/*.tsx"],
+  languageOptions: {
+    parser: tsParser,
+    parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
+  },
+  plugins: { ownership },
+  rules: { "ownership/must-consume": "error" },
+}];
+```
+
+## Add to your existing typescript-eslint flat config
+
+Your `typescript-eslint` type-checked presets already configure the parser. Add
+this import, plugin entry, and rule to your existing configuration:
+
+```js
+import ownership from "eslint-plugin-ownership";
+
+// Inside your existing defineConfig({ ... }):
+// plugins: { async: asyncPlugin, exhaustive: exhaustivePlugin,
+//            result: resultPlugin, roblox: robloxPlugin, ownership },
+// rules: { ...yourRules, "ownership/must-consume": "error" },
+```
+
+Keep `languageOptions.parserOptions.projectService: true`. No separate
+`@typescript-eslint/utils` dependency is required by this plugin. Tested with
+ESLint 10.8.1, TypeScript 5.9.3, and `@typescript-eslint/parser` 8.72.2.
+
+## Annotate APIs, not ESLint configuration
+
+```ts
+interface Transaction {
+  /** @ownership.consume */
+  commit(): Promise<void>;
+  /** @ownership.consume */
+  rollback(): Promise<void>;
+}
+
+interface Database {
+  /** @ownership.acquire */
+  beginTransaction(): Promise<Transaction>;
+}
+
+/** @ownership.transfer tx */
+declare function adopt(tx: Transaction): void;
+
+/** @ownership.borrow tx */
+declare function logTransaction(tx: Transaction): void;
+```
+
+- `@ownership.acquire` on a function or method: its return value is owned. A `Promise<T>` should be awaited before binding.
+- `@ownership.consume` on a resource method: consumes the receiver on that execution path; if `requireAwait` is true (default), calls must be awaited.
+- `@ownership.transfer <parameterName>` on a function or method: ownership transfers when a tracked resource is passed to that named parameter.
+- `@ownership.borrow <parameterName>`: passing the resource is permitted but does not consume it.
+
+Annotations work on declarations in imported TypeScript modules and `.d.ts` files when the parser's TypeScript project can resolve them. The rule reads declarations using TypeScript symbol resolution, not by matching names globally. An unannotated unrelated `commit()` is ignored. JSDoc has no roblox-ts runtime footprint.
+
+```ts
+const tx = await db.beginTransaction();
+await doWork(); // ERROR: tx not consumed on every exit path
+```
+
+```ts
+const tx = await db.beginTransaction();
+try {
+  await doWork();
+  await tx.commit();
+} catch (error) {
+  await tx.rollback();
+  throw error;
+}
+```
+
+## Explicit opt-in legacy configuration
+
+Existing resource registries are still accepted:
+
+```js
+"ownership/must-consume": ["error", {
+  resources: [{
+    type: "Transaction",
+    acquire: ["beginTransaction"],
+    consume: ["commit", "rollback"],
+  }],
+}]
+```
+
+Or use `acquire` and `consume` method lists for name-only compatibility. **Name-only detection is disabled by default**, avoiding false positives on unannotated APIs. Annotations take precedence when present. The options `requireAwait`, `maxPaths`, and `maxLoopIterations` still apply.
+
+## Analysis limitations
+
+This is a conservative intraprocedural checker with branch-sensitive states, aliases, and a bounded loop worklist. It does not prove behavior across arbitrary called functions, reassignment, destructuring, closure capture, all exceptions, or complex property aliases. Unannotated function calls receiving owned values are reported as escapes. Finalizer calls are assumed to complete ownership transitions when awaited; a rejected finalizer is **not** modeled as an exception preserving ownership. Complex `switch` and labeled control flow are unsupported. The rule does not perform whole-program ownership inference.
+
+Run `npm test` after installing dependencies.

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "eslint-plugin-ownership",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "peerDependencies": {
+    "eslint": "10.8.1",
+    "typescript": "5.9.3",
+    "@typescript-eslint/parser": "^8.0.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/index.js

@@ -0,0 +1,6 @@
+import { mustConsume } from "./must-consume.js";
+
+export default {
+  meta: { name: "eslint-plugin-ownership", version: "0.4.0" },
+  rules: { "must-consume": mustConsume },
+};

package/src/must-consume.js

@@ -0,0 +1,436 @@
+import ts from "typescript";
+/**
+ * Local, path-sensitive resource ownership checker for TypeScript/roblox-ts.
+ * A tracked resource is an affine value: every reachable function exit must
+ * consume it exactly once. This is a conservative intraprocedural analysis.
+ */
+const DEFAULTS = {
+  resources: [],
+  acquire: [],
+  consume: [],
+  transfer: [],
+  requireAwait: true,
+  maxPaths: 256,
+  maxLoopIterations: 64,
+};
+const FUNCTIONS = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
+const WRAPPERS = new Set(["TSAsExpression", "TSTypeAssertion", "TSNonNullExpression", "TSSatisfiesExpression", "ChainExpression"]);
+const LOOPS = new Set(["WhileStatement", "DoWhileStatement", "ForStatement", "ForOfStatement", "ForInStatement"]);
+const UNSUPPORTED = new Set(["SwitchStatement", "LabeledStatement", "WithStatement"]);
+const unwrap = node => { while (node && (WRAPPERS.has(node.type) || node.type === "AwaitExpression")) node = node.type === "AwaitExpression" ? node.argument : node.expression; return node; };
+const nameOf = node => node?.type === "Identifier" ? node.name : null;
+function methodCall(node) {
+  node = unwrap(node);
+  if (node?.type !== "CallExpression" || node.optional || node.callee?.type !== "MemberExpression" || node.callee.optional || node.callee.computed) return null;
+  return { call: node, receiver: unwrap(node.callee.object), method: nameOf(node.callee.property) };
+}
+const clone = (p, exit = p.exit) => ({ states: new Map(p.states), aliases: new Map(p.aliases), exit });
+const outcome = (p, exit) => ({ ...p, exit });
+
+export const mustConsume = {
+  meta: {
+    type: "problem",
+    docs: { description: "Require typed resources to be consumed on every control-flow exit" },
+    schema: [{
+      type: "object", additionalProperties: false,
+      properties: {
+        resources: { type: "array", items: { type: "object", additionalProperties: false, required: ["type", "acquire", "consume"], properties: {
+          type: { type: "string" },
+          declarationFile: { type: "string" },
+          acquire: { type: "array", items: { type: "string" }, minItems: 1 },
+          consume: { type: "array", items: { type: "string" }, minItems: 1 },
+          transfer: { type: "array", items: { type: "string" } },
+          requireAwait: { type: "boolean" },
+        } } },
+        acquire: { type: "array", items: { type: "string" } },
+        consume: { type: "array", items: { type: "string" } },
+        transfer: { type: "array", items: { type: "string" } },
+        requireAwait: { type: "boolean" },
+        maxPaths: { type: "integer", minimum: 2, maximum: 4096 },
+        maxLoopIterations: { type: "integer", minimum: 2, maximum: 4096 },
+      },
+    }],
+    messages: {
+      leaked: "Resource '{{name}}' is not consumed on every exit path.",
+      doubleConsume: "Resource '{{name}}' is already consumed on this path.",
+      escape: "Resource '{{name}}' escapes without an explicit ownership-transfer contract.",
+      untracked: "Acquired resource must be bound to a local identifier.",
+      unawaited: "Finalizer for '{{name}}' must be awaited.",
+      unsupported: "Cannot prove ownership through '{{kind}}'; refactor this construct.",
+      limit: "Ownership analysis exceeded the configured {{kind}} limit; safety cannot be proven.",
+      typeInfo: "Ownership JSDoc annotations and typed resource contracts require @typescript-eslint/parser with projectService or project enabled.",
+    },
+  },
+  create(context) {
+    const opt = { ...DEFAULTS, ...context.options[0] };
+    const src = context.sourceCode;
+    const ps = src.parserServices ?? {};
+    const checker = ps.program?.getTypeChecker();
+    const reported = new Set();
+    function report(node, messageId, data = {}) {
+      const key = `${node?.range?.[0] ?? node?.start}:${messageId}:${data.name ?? ""}:${data.kind ?? ""}`;
+      if (reported.has(key)) return;
+      reported.add(key);
+      context.report({ node, messageId, data });
+    }
+    const hasLegacy = opt.acquire.length > 0;
+    const contracts = opt.resources.length ? opt.resources.map((r, i) => ({ ...r, id: i, acquireSet: new Set(r.acquire), consumeSet: new Set(r.consume), transferSet: new Set(r.transfer ?? []), requireAwait: r.requireAwait ?? opt.requireAwait }))
+      : hasLegacy ? [{ id: 0, type: null, acquireSet: new Set(opt.acquire), consumeSet: new Set(opt.consume), transferSet: new Set(opt.transfer), requireAwait: opt.requireAwait }] : [];
+    // JSDoc annotations are compile-time only; roblox-ts does not emit them.
+    // TypeScript parses `@ownership.acquire` as tag `ownership` and comment
+    // `.acquire`, so inspect the declaration AST rather than relying on a
+    // nonexistent tag named `ownership.acquire`.
+    function tsSymbol(node) {
+      if (!checker || !ps.esTreeNodeToTSNodeMap || !node) return null;
+      const target = ps.esTreeNodeToTSNodeMap.get(node);
+      if (!target) return null;
+      let symbol = checker.getSymbolAtLocation(target);
+      if (symbol && (symbol.flags & ts.SymbolFlags.Alias)) symbol = checker.getAliasedSymbol(symbol);
+      return symbol ?? null;
+    }
+    const annotationCache = new Map();
+    function annotations(symbol) {
+      if (!symbol) return [];
+      if (annotationCache.has(symbol)) return annotationCache.get(symbol);
+      const results = [];
+      for (const declaration of symbol.declarations ?? []) {
+        for (const tag of ts.getJSDocTags(declaration)) {
+          const name = tag.tagName.text;
+          const raw = typeof tag.comment === "string" ? tag.comment :
+            (tag.comment ?? []).map(x => x.text ?? "").join("");
+          const full = name === "ownership" ? raw.trim().replace(/^\./, "") :
+            name.startsWith("ownership.") ? name.slice("ownership.".length) + " " + raw : "";
+          const match = /^(acquire|consume|transfer|borrow)(?:\s+(.+))?$/.exec(full.trim());
+          if (match) results.push({ kind: match[1], parameter: match[2]?.trim() });
+        }
+      }
+      annotationCache.set(symbol, results);
+      return results;
+    }
+    const hasTag = (symbol, kind) => annotations(symbol).some(t => t.kind === kind);
+    function callSymbol(call) {
+      const callee = unwrap(call.callee);
+      if (!callee) return null;
+      return tsSymbol(callee.type === "MemberExpression" && !callee.computed ? callee.property : callee);
+    }
+    function annotationContract(call) {
+      const symbol = callSymbol(call);
+      if (!hasTag(symbol, "acquire")) return null;
+      return { id: symbol, annotated: true, type: null,
+        requireAwait: opt.requireAwait, consumeSet: new Set(), transferSet: new Set() };
+    }
+    function parameterEffects(call, p) {
+      const symbol = callSymbol(call);
+      const tags = annotations(symbol).filter(t => t.kind === "transfer" || t.kind === "borrow");
+      if (!tags.length) return { transferred: [], borrowed: [] };
+      const params = (symbol?.declarations ?? []).find(d => d.parameters)?.parameters ?? [];
+      const transferred = [], borrowed = [];
+      for (const tag of tags) {
+        const index = params.findIndex(param => ts.isIdentifier(param.name) && param.name.text === tag.parameter);
+        if (index < 0 || index >= call.arguments.length) continue;
+        const arg = call.arguments[index];
+        const v = bindingOf(unwrap(arg.type === "SpreadElement" ? arg.argument : arg), p);
+        if (!v) continue;
+        (tag.kind === "transfer" ? transferred : borrowed).push(v);
+      }
+      return { transferred, borrowed };
+    }
+    // Compare TS declaration symbols, not text rendered by typeToString().
+    // declarationFile disambiguates same-named symbols from separate modules.
+    function matchesSymbol(symbol, contract) {
+      if (!symbol || symbol.getName() !== contract.type) return false;
+      if (!contract.declarationFile) return true;
+      const file = contract.declarationFile.replaceAll("\\", "/");
+      return (symbol.declarations ?? []).some(d =>
+        d.getSourceFile().fileName.replaceAll("\\", "/").endsWith(file));
+    }
+    function typeMatches(node, contract) {
+      if (!contract.type) return true;
+      if (!checker || !ps.esTreeNodeToTSNodeMap) return false;
+      const tsNode = ps.esTreeNodeToTSNodeMap.get(node);
+      if (!tsNode) return false;
+      let type = checker.getTypeAtLocation(tsNode);
+      type = checker.getAwaitedType?.(type) ?? type;
+      const seen = new Set();
+      function matches(t) {
+        if (!t || seen.has(t)) return false;
+        seen.add(t);
+        if (t.isUnionOrIntersection?.()) return t.types.some(matches);
+        if (matchesSymbol(t.aliasSymbol, contract) || matchesSymbol(t.symbol, contract)) return true;
+        // Interfaces and classes may derive from a declared resource contract.
+        return (t.getBaseTypes?.() ?? []).some(matches);
+      }
+      return matches(type);
+    }
+    function resolvedMember(m) {
+      if (!checker || !ps.esTreeNodeToTSNodeMap) return true; // name-only legacy mode
+      const property = ps.esTreeNodeToTSNodeMap.get(m.call.callee.property);
+      const receiver = ps.esTreeNodeToTSNodeMap.get(m.receiver);
+      if (!property || !receiver) return false;
+      const actual = checker.getSymbolAtLocation(property);
+      const expected = checker.getPropertyOfType(checker.getTypeAtLocation(receiver), m.method);
+      return Boolean(actual && expected && actual === expected);
+    }
+    function variableFor(id) {
+      if (id?.type !== "Identifier") return null;
+      for (let scope = src.getScope(id); scope; scope = scope.upper) {
+        const variable = scope.set.get(id.name);
+        if (variable) return variable;
+      }
+      return null;
+    }
+    function bindingOf(id, p) {
+      const v = variableFor(id);
+      if (!v) return null;
+      return p.aliases.get(v) ?? (p.states.has(v) ? v : null);
+    }
+    function awaited(call) {
+      let parent = call.parent;
+      while (parent && WRAPPERS.has(parent.type)) parent = parent.parent;
+      return parent?.type === "AwaitExpression";
+    }
+    function keyOf(p) {
+      const states = [...p.states].map(([v, s]) => `${v.identifiers[0]?.range?.[0] ?? v.name}:${s}`).sort().join(",");
+      const aliases = [...p.aliases].map(([v, target]) => `${v.identifiers[0]?.range?.[0] ?? v.name}->${target.identifiers[0]?.range?.[0] ?? target.name}`).sort().join(",");
+      return `${p.exit}|${states}|${aliases}`;
+    }
+    function dedup(paths, node) {
+      const unique = [...new Map(paths.map(p => [keyOf(p), p])).values()];
+      if (unique.length > opt.maxPaths) {
+        report(node, "limit", { kind: "maxPaths" });
+        // Do not silently drop unproven ownership paths.
+        for (const p of unique) for (const [v, state] of p.states) if (state === "acquired") report(v.identifiers[0] ?? node, "leaked", { name: v.name });
+      }
+      return unique.slice(0, opt.maxPaths);
+    }
+    function checkEscape(node, p) {
+      const id = unwrap(node);
+      const resource = bindingOf(id, p);
+      if (resource) report(id, "escape", { name: resource.name });
+    }
+    function acquisition(node) {
+      const call = unwrap(node);
+      if (call?.type !== "CallExpression") return null;
+      const annotated = annotationContract(call);
+      if (annotated) return annotated;
+      const m = methodCall(call);
+      if (!m) return null;
+      return contracts.find(c => c.acquireSet.has(m.method) && typeMatches(m.call, c) && (!c.type || resolvedMember(m))) ?? null;
+    }
+    function finalized(m, p) {
+      const resource = bindingOf(m.receiver, p);
+      if (!resource) return null;
+      const contract = resourceContracts.get(resource);
+      if (!contract) return null;
+      if (contract.annotated) {
+        return hasTag(callSymbol(m.call), "consume") ? { resource, contract } : null;
+      }
+      return contract.consumeSet.has(m.method) && (!contract.type || (typeMatches(m.receiver, contract) && resolvedMember(m))) ? { resource, contract } : null;
+    }
+    function transferCall(node, p) {
+      const callee = unwrap(node.callee);
+      const fn = nameOf(callee) ?? (callee?.type === "MemberExpression" && !callee.computed ? nameOf(callee.property) : null);
+      const targets = [];
+      for (const arg of node.arguments) {
+        const v = bindingOf(unwrap(arg.type === "SpreadElement" ? arg.argument : arg), p);
+        if (v && resourceContracts.get(v)?.transferSet.has(fn)) targets.push(v);
+      }
+      return targets;
+    }
+    const resourceContracts = new Map();
+    function expression(node, p) {
+      if (!node || FUNCTIONS.has(node.type) || p.exit !== "normal") return [p];
+      if (WRAPPERS.has(node.type)) return expression(node.expression, p);
+      if (node.type === "AwaitExpression") {
+        const m = methodCall(node.argument);
+        const isFinal = m && finalized(m, p);
+        const isAcquire = acquisition(node.argument);
+        // An acquisition failure creates no owned value; caller handles the successful binding.
+        const failures = isFinal || isAcquire ? [] : [clone(p, "throw")];
+        return dedup([...failures, ...expression(node.argument, p)], node);
+      }
+      if (node.type === "CallExpression") {
+        const m = methodCall(node);
+        if (acquisition(node)) { report(node, "untracked"); return [p]; }
+        const final = m && finalized(m, p);
+        const next = clone(p);
+        if (final) {
+          if (final.contract.requireAwait && !awaited(node)) report(node, "unawaited", { name: final.resource.name });
+          else if (next.states.get(final.resource) === "consumed") report(node, "doubleConsume", { name: final.resource.name });
+          else next.states.set(final.resource, "consumed");
+        }
+        const effects = parameterEffects(node, next);
+        const transferred = [...new Set([...transferCall(node, next), ...effects.transferred])];
+        for (const v of transferred) {
+          if (next.states.get(v) === "consumed") report(node, "doubleConsume", { name: v.name });
+          next.states.set(v, "consumed");
+        }
+        for (const arg of node.arguments) {
+          const value = arg.type === "SpreadElement" ? arg.argument : arg;
+          const v = bindingOf(unwrap(value), next);
+          if (v && !transferred.includes(v) && !effects.borrowed.includes(v)) checkEscape(value, next);
+        }
+        let paths = [next];
+        if (m && !final) paths = paths.flatMap(q => expression(m.receiver, q));
+        else if (node.callee.type !== "Identifier" && !m) paths = paths.flatMap(q => expression(node.callee, q));
+        for (const arg of node.arguments) paths = paths.flatMap(q => expression(arg.type === "SpreadElement" ? arg.argument : arg, q));
+        return dedup(paths, node);
+      }
+      if (node.type === "Identifier" || node.type === "Literal" || node.type === "ThisExpression") return [p];
+      if (node.type === "AssignmentExpression") {
+        checkEscape(node.left, p);
+        checkEscape(node.right, p);
+        return expression(node.right, p);
+      }
+      if (node.type === "UpdateExpression") { checkEscape(node.argument, p); return [p]; }
+      if (node.type === "ConditionalExpression") return expression(node.test, p).flatMap(q => q.exit !== "normal" ? [q] : [...expression(node.consequent, clone(q)), ...expression(node.alternate, clone(q))]);
+      if (node.type === "LogicalExpression") return expression(node.left, p).flatMap(q => q.exit !== "normal" ? [q] : [clone(q), ...expression(node.right, clone(q))]);
+      if (node.type === "SequenceExpression") return sequence(node.expressions, [p], expression);
+      if (node.type === "MemberExpression") return expression(node.object, p);
+      if (node.type === "BinaryExpression") return expression(node.left, p).flatMap(q => expression(node.right, q));
+      if (node.type === "UnaryExpression") return expression(node.argument, p);
+      if (node.type === "ArrayExpression" || node.type === "ObjectExpression") {
+        const els = node.type === "ArrayExpression" ? node.elements : node.properties.map(x => x.value ?? x.argument);
+        for (const el of els) checkEscape(el, p);
+        return sequence(els.filter(Boolean), [p], expression);
+      }
+      if (node.type === "NewExpression") {
+        for (const arg of node.arguments ?? []) checkEscape(arg, p);
+        return sequence(node.arguments ?? [], [p], expression);
+      }
+      if (node.type === "TSInstantiationExpression") return expression(node.expression, p);
+      return [p];
+    }
+    function sequence(nodes, initial, visit) {
+      return nodes.reduce((paths, node) => dedup(paths.flatMap(p => p.exit === "normal" ? visit(node, p) : [p]), node), initial);
+    }
+    function block(nodes, initial) { return sequence(nodes, initial, statement); }
+    function loop(node, p) {
+      // Worklist fixpoint over a finite lattice of {acquired, consumed} states,
+      // alias mappings, and exit kinds. A loop is not accepted simply because
+      // its body contains a finalizer: the zero-iteration path is retained.
+      const isDo = node.type === "DoWhileStatement";
+      const isFor = node.type === "ForStatement";
+      const isIter = node.type === "ForOfStatement" || node.type === "ForInStatement";
+      let starts = [p];
+      if (isFor && node.init) starts = node.init.type === "VariableDeclaration" ? starts.flatMap(q => statement(node.init, q)) : starts.flatMap(q => expression(node.init, q));
+      if (isIter) starts = starts.flatMap(q => expression(node.right, q));
+      const exits = [];
+      let pending = starts;
+      const visited = new Set();
+      let iterations = 0;
+      while (pending.length && iterations++ < opt.maxLoopIterations) {
+        const current = pending;
+        pending = [];
+        for (const entry of current) {
+          if (entry.exit !== "normal") { exits.push(entry); continue; }
+          const key = keyOf(entry);
+          if (visited.has(key)) continue;
+          visited.add(key);
+          const tests = !isDo && node.test ? expression(node.test, entry) : [entry];
+          for (const t of tests) {
+            if (t.exit !== "normal") { exits.push(t); continue; }
+            if (!isDo) exits.push(clone(t)); // loop can finish without executing body
+            let bodyPaths = statement(node.body, clone(t));
+            for (let b of bodyPaths) {
+              if (b.exit === "break") { exits.push(clone(b, "normal")); continue; }
+              if (b.exit !== "normal" && b.exit !== "continue") { exits.push(b); continue; }
+              b = clone(b, "normal");
+              if (isFor && node.update) {
+                for (const u of expression(node.update, b)) pending.push(u);
+              } else if (isDo && node.test) {
+                for (const u of expression(node.test, b)) {
+                  if (u.exit === "normal") { exits.push(clone(u)); pending.push(u); }
+                  else exits.push(u);
+                }
+              } else pending.push(b);
+            }
+          }
+        }
+        pending = dedup(pending, node);
+      }
+      if (pending.length) {
+        report(node, "limit", { kind: "maxLoopIterations" });
+        // Preserve unproven paths as exits: never pronounce a possibly-live resource safe.
+        exits.push(...pending);
+      }
+      return dedup(exits, node);
+    }
+    function statement(node, p) {
+      switch (node.type) {
+        case "BlockStatement": return block(node.body, [p]);
+        case "ExportNamedDeclaration":
+        case "ExportDefaultDeclaration":
+          if (!node.declaration) return [p];
+          return node.declaration.type.endsWith("Declaration")
+            ? statement(node.declaration, p)
+            : expression(node.declaration, p);
+        case "VariableDeclaration": {
+          let paths = [p];
+          for (const decl of node.declarations) {
+            paths = paths.flatMap(q => {
+              if (q.exit !== "normal") return [q];
+              const contract = acquisition(decl.init);
+              if (contract) {
+                if (decl.id.type !== "Identifier") { report(decl, "untracked"); return [q]; }
+                const variable = variableFor(decl.id);
+                if (!variable) { report(decl, "untracked"); return [q]; }
+                resourceContracts.set(variable, contract);
+                const next = clone(q);
+                if (next.states.get(variable) === "acquired") {
+                  report(decl.id, "leaked", { name: variable.name });
+                }
+                // A new loop iteration creates a fresh resource. Old aliases
+                // cannot safely stand for this new value.
+                for (const [alias, target] of next.aliases) {
+                  if (target === variable) next.aliases.delete(alias);
+                }
+                next.states.set(variable, "acquired");
+                return decl.init?.type === "AwaitExpression" ? [clone(q, "throw"), next] : [next];
+              }
+              const alias = bindingOf(unwrap(decl.init), q);
+              if (alias && decl.id.type === "Identifier") {
+                const v = variableFor(decl.id);
+                if (v) { const next = clone(q); next.aliases.set(v, alias); return [next]; }
+              }
+              return expression(decl.init, q);
+            });
+          }
+          return dedup(paths, node);
+        }
+        case "ExpressionStatement": return expression(node.expression, p);
+        case "IfStatement": return expression(node.test, p).flatMap(q => q.exit !== "normal" ? [q] : dedup([
+          ...statement(node.consequent, clone(q)), ...(node.alternate ? statement(node.alternate, clone(q)) : [clone(q)]),
+        ], node));
+        case "TryStatement": {
+          const attempted = statement(node.block, p);
+          const caught = attempted.flatMap(q => q.exit === "throw" && node.handler ? statement(node.handler.body, clone(q, "normal")) : [q]);
+          if (!node.finalizer) return caught;
+          return dedup(caught.flatMap(q => statement(node.finalizer, clone(q, "normal")).map(f => f.exit === "normal" ? outcome(f, q.exit) : f)), node);
+        }
+        case "ReturnStatement":
+        case "ThrowStatement":
+          checkEscape(node.argument, p);
+          return expression(node.argument, p).map(q => q.exit === "normal" ? outcome(q, node.type === "ReturnStatement" ? "return" : "throw") : q);
+        case "BreakStatement": return [clone(p, "break")];
+        case "ContinueStatement": return [clone(p, "continue")];
+        case "EmptyStatement": case "FunctionDeclaration": case "TSInterfaceDeclaration": case "TSTypeAliasDeclaration": return [p];
+        default:
+          if (LOOPS.has(node.type)) return loop(node, p);
+          if (UNSUPPORTED.has(node.type) && [...p.states.values()].includes("acquired")) report(node, "unsupported", { kind: node.type });
+          return [p];
+      }
+    }
+    function analyze(node) {
+      if ((opt.resources.length || !hasLegacy) && !checker) { report(node, "typeInfo"); return; }
+      resourceContracts.clear();
+      const initial = { states: new Map(), aliases: new Map(), exit: "normal" };
+      const body = node.type === "Program" ? node.body : node.body?.type === "BlockStatement" ? node.body.body : null;
+      const paths = body ? block(body, [initial]) : expression(node.body, initial);
+      for (const p of paths) for (const [v, state] of p.states) {
+        if (state === "acquired") report(v.identifiers[0] ?? node, "leaked", { name: v.name });
+      }
+    }
+    return { Program: analyze, FunctionDeclaration: analyze, FunctionExpression: analyze, ArrowFunctionExpression: analyze };
+  },
+};

package/tests/annotations.test.js

@@ -0,0 +1,64 @@
+import { RuleTester } from "eslint";
+import parser from "@typescript-eslint/parser";
+import { mustConsume } from "../src/must-consume.js";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(fileURLToPath(import.meta.url));
+const tester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: {
+      projectService: { allowDefaultProject: ["*.ts"], maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 30 },
+      tsconfigRootDir: root,
+    },
+  },
+});
+const declarations = `
+interface Transaction {
+  /** @ownership.consume */
+  commit(): Promise<void>;
+  /** @ownership.consume */
+  rollback(): Promise<void>;
+  inspect(): void;
+}
+declare const db: {
+  /** @ownership.acquire */
+  beginTransaction(): Promise<Transaction>;
+};
+declare function work(): Promise<void>;
+declare function shouldCommit(): boolean;
+/** @ownership.transfer tx */
+declare function adopt(tx: Transaction): void;
+/** @ownership.borrow tx */
+declare function observe(tx: Transaction): void;
+declare const unrelated: { commit(): Promise<void> };
+/** @ownership.acquire */
+declare function getResource(): Transaction;
+`;
+const code = body => declarations + `\nasync function example() { ${body} }`;
+const valid = (name, body) => ({ filename: `annotation-${name}.ts`, code: code(body) });
+const invalid = (name, body, errors) => ({ filename: `annotation-${name}.ts`, code: code(body), errors: errors.map(messageId => ({ messageId })) });
+
+tester.run("must-consume (JSDoc auto-discovery)", mustConsume, {
+  valid: [
+    valid("commit", `const tx = await db.beginTransaction(); await tx.commit();`),
+    valid("rollback", `const tx = await db.beginTransaction(); await tx.rollback();`),
+    valid("try", `const tx = await db.beginTransaction(); try { await work(); await tx.commit(); } catch (e) { await tx.rollback(); throw e; }`),
+    valid("transfer", `const tx = await db.beginTransaction(); adopt(tx);`),
+    valid("borrow", `const tx = await db.beginTransaction(); observe(tx); await tx.rollback();`),
+    valid("alias", `const tx = await db.beginTransaction(); const alias = tx; await alias.commit();`),
+    valid("function", `const tx = getResource(); await tx.rollback();`),
+    valid("unrelated", `await unrelated.commit();`),
+    valid("loop", `while (shouldCommit()) { const tx = await db.beginTransaction(); await tx.rollback(); }`),
+  ],
+  invalid: [
+    invalid("leak", `const tx = await db.beginTransaction(); await work();`, ["leaked"]),
+    invalid("conditional", `const tx = await db.beginTransaction(); if (shouldCommit()) await tx.commit();`, ["leaked"]),
+    invalid("double", `const tx = await db.beginTransaction(); await tx.commit(); await tx.rollback();`, ["doubleConsume"]),
+    invalid("unawaited", `const tx = await db.beginTransaction(); tx.commit();`, ["leaked", "unawaited"]),
+    invalid("borrow-leak", `const tx = await db.beginTransaction(); observe(tx);`, ["leaked"]),
+    invalid("escape", `const tx = await db.beginTransaction(); work(tx);`, ["leaked", "escape"]),
+    invalid("loop-zero", `const tx = await db.beginTransaction(); while (shouldCommit()) await tx.commit();`, ["leaked", "doubleConsume"]),
+  ],
+});

package/tests/integration.test.js

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { Linter } from "eslint";
+import { defineConfig } from "eslint/config";
+import parser from "@typescript-eslint/parser";
+import ownership from "../src/index.js";
+
+test("flat config discovers annotations through typed parser services", () => {
+  const config = defineConfig({
+    files: ["**/*.ts"],
+    languageOptions: {
+      parser,
+      parserOptions: {
+        projectService: { allowDefaultProject: ["integration.ts"] },
+        tsconfigRootDir: process.cwd(),
+      },
+    },
+    plugins: { ownership },
+    rules: { "ownership/must-consume": "error" },
+  });
+  const declarations = `
+    interface Resource {
+      /** @ownership.consume */
+      close(): void;
+    }
+    /** @ownership.acquire */
+    declare function acquire(): Resource;
+  `;
+  const linter = new Linter();
+  const lint = body => linter.verify(declarations + body, config, { filename: "integration.ts" });
+  assert.deepEqual(lint("export const resource = acquire();").map(m => m.messageId), ["leaked"]);
+  assert.deepEqual(lint("async function run() { const resource = acquire(); await resource.close(); }"), []);
+  assert.equal(ownership.meta.version, "0.4.0");
+});

package/tests/must-consume.test.js

@@ -0,0 +1,114 @@
+import { RuleTester } from "eslint";
+import parser from "@typescript-eslint/parser";
+import { mustConsume } from "../src/must-consume.js";
+
+const tester = new RuleTester({
+  languageOptions: { parser, parserOptions: { ecmaVersion: "latest", sourceType: "module" } },
+});
+
+const legacy = { acquire: ["beginTransaction"], consume: ["commit", "rollback"] };
+tester.run("must-consume", mustConsume, {
+  valid: [
+    `async function work() {
+      const transaction = await db.beginTransaction();
+      try { await doWork(); await transaction.commit(); }
+      catch (error) { await transaction.rollback(); throw error; }
+    }`,
+    `async function work(flag: boolean) {
+      const tx = await db.beginTransaction();
+      if (flag) await tx.commit(); else await tx.rollback();
+    }`,
+    `async function work() {
+      const tx = await db.beginTransaction();
+      try { await doWork(); } finally { await tx.rollback(); }
+    }`,
+    `async function work() {
+      const tx = await db.beginTransaction();
+      const alias = tx;
+      await alias.rollback();
+    }`,
+    `async function work() {
+      while (ready()) {
+        const tx = await db.beginTransaction();
+        await tx.commit();
+      }
+    }`,
+    `async function work() {
+      for (let i = 0; i < 3; i++) {
+        const tx = await db.beginTransaction();
+        await tx.rollback();
+      }
+    }`,
+    {
+      code: `async function work() {
+        const tx = await db.beginTransaction();
+        handOff(tx);
+      }`,
+      options: [{ transfer: ["handOff"] }],
+    },
+  ].map(item => typeof item === "string" ? { code: item, options: [legacy] } : { ...item, options: [{ ...legacy, ...(item.options?.[0] ?? {}) }] }),
+  invalid: [
+    {
+      code: `export const tx = await db.beginTransaction();`,
+      errors: [{ messageId: "leaked" }],
+    },
+    {
+      code: `async function work() {
+        while (ready()) {
+          const tx = await db.beginTransaction();
+          if (ready()) continue;
+          await tx.commit();
+        }
+      }`,
+      errors: [{ messageId: "leaked" }],
+    },
+    {
+      code: `async function work() { const tx = await db.beginTransaction(); await doWork(); }`,
+      errors: [{ messageId: "leaked" }],
+    },
+    {
+      code: `async function work(flag: boolean) {
+        const tx = await db.beginTransaction();
+        if (flag) await tx.commit();
+      }`,
+      errors: [{ messageId: "leaked" }],
+    },
+    {
+      code: `async function work() { const tx = await db.beginTransaction(); return 123; }`,
+      errors: [{ messageId: "leaked" }],
+    },
+    {
+      code: `async function work() { const tx = await db.beginTransaction(); tx.commit(); }`,
+      errors: [{ messageId: "leaked" }, { messageId: "unawaited" }],
+    },
+    {
+      code: `async function work() {
+        const tx = await db.beginTransaction();
+        await tx.commit(); await tx.rollback();
+      }`,
+      errors: [{ messageId: "doubleConsume" }],
+    },
+    {
+      code: `async function work() {
+        const tx = await db.beginTransaction();
+        const ref = tx;
+        await ref.commit(); await tx.rollback();
+      }`,
+      errors: [{ messageId: "doubleConsume" }],
+    },
+    {
+      code: `async function work() {
+        const tx = await db.beginTransaction();
+        while (ready()) await tx.commit();
+      }`,
+      errors: [{ messageId: "leaked" }, { messageId: "doubleConsume" }],
+    },
+    {
+      code: `async function work() {
+        const tx = await db.beginTransaction();
+        consumeElsewhere(tx);
+      }`,
+      errors: [{ messageId: "leaked" }, { messageId: "escape" }],
+    },
+  ].map(item => ({ ...item, options: [legacy] })),
+});

package/tests/typed.test.js

@@ -0,0 +1,82 @@
+import { RuleTester } from "eslint";
+import parser from "@typescript-eslint/parser";
+import { mustConsume } from "../src/must-consume.js";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+
+const root = dirname(fileURLToPath(import.meta.url));
+const config = [{ resources: [{ type: "Transaction", acquire: ["beginTransaction"], consume: ["commit", "rollback"] }] }];
+const prelude = `
+interface Transaction { commit(): Promise<void>; rollback(): Promise<void> }
+interface Other { commit(): Promise<void> }
+declare const db: { beginTransaction(): Promise<Transaction> };
+declare const other: { beginTransaction(): Promise<Other> };
+declare function work(): Promise<void>;
+declare function ready(): boolean;
+`;
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: {
+      projectService: { allowDefaultProject: ["*.ts"] },
+      tsconfigRootDir: root,
+    },
+  },
+});
+
+tester.run("must-consume (typed)", mustConsume, {
+  valid: [
+    {
+      filename: "typed-valid.ts",
+      options: config,
+      code: prelude + `async function f() {
+        const tx = await db.beginTransaction();
+        try { await work(); await tx.commit(); }
+        catch (e) { await tx.rollback(); throw e; }
+      }`,
+    },
+    {
+      filename: "typed-unrelated.ts",
+      options: config,
+      code: prelude + `async function f() { const value = await other.beginTransaction(); }`,
+    },
+    {
+      filename: "typed-loop-good.ts",
+      options: config,
+      code: prelude + `async function f() {
+        while (ready()) {
+          const tx = await db.beginTransaction();
+          await tx.rollback();
+        }
+      }`,
+    },
+  ],
+  invalid: [
+    {
+      filename: "typed-leak.ts",
+      options: config,
+      code: prelude + `async function f() { const tx = await db.beginTransaction(); await work(); }`,
+      errors: [{ messageId: "leaked" }],
+    },
+    {
+      filename: "typed-loop-leak.ts",
+      options: config,
+      code: prelude + `async function f() {
+        const tx = await db.beginTransaction();
+        while (ready()) await tx.commit();
+      }`,
+      errors: [{ messageId: "leaked" }, { messageId: "doubleConsume" }],
+    },
+    {
+      filename: "typed-double.ts",
+      options: config,
+      code: prelude + `async function f() {
+        const tx = await db.beginTransaction();
+        await tx.commit();
+        await tx.rollback();
+      }`,
+      errors: [{ messageId: "doubleConsume" }],
+    },
+  ],
+});