@vibe-agent-toolkit/utils 0.2.0-rc.10 → 0.2.0-rc.12

package/eslint/rules/no-destructive-fs.cjs

@@ -0,0 +1,359 @@
+/**
+ * ESLint rule: no-destructive-fs
+ *
+ * Bans every recursive remove, rename and copy of a filesystem tree outside the one
+ * module that owns them. A hand-rolled `rm` + `rename` + `cp` sequence is a private
+ * swap protocol, and each one decided differently what happens when the disk fills, a
+ * file is unreadable, a name differs only by case, or the process dies between two
+ * steps. The tree-change primitive (`planTreeChanges` / `applyTreePlan`, plus
+ * `replaceFile`, `renameFileAtomic`, `withTempDir`, `disposeTempDir`, `copyTree`) is
+ * the single protocol; everything else asks it.
+ *
+ * The rule judges REFERENCES to a banned function, not only calls, using the scope
+ * manager. A binding is banned when it comes from `node:fs` / `node:fs/promises` (or
+ * the unprefixed names) by named import (`import { rmSync as r }`), by destructuring a
+ * namespace (`const { rmSync } = fs`, `const { promises: { rm } } = fs`), or by a
+ * dynamic `import()` / `require()`; a namespace is a default or namespace import, a
+ * `promises` binding, `fs.promises`, an alias of one, or a dynamic `import()` /
+ * `require()`. A local that shadows an imported name is not the fs function.
+ *
+ * - `recursiveRm` — `rm` / `rmSync`, unless the reference is a call whose options are
+ *   provably non-recursive: an object literal with no `recursive` key or `recursive:
+ *   false`. An identifier, a call, a spread (`rmSync(...args)`), a computed key, a
+ *   non-literal value, or a use as a value (`names.map(rmSync)`, `.call`, `.apply`)
+ *   counts as recursive. `rm(file)` and `rm(file, { force: true })` are one file.
+ * - `rmdir`, `rename`, `cp`, `copyFile` — every reference: a call, a value use
+ *   (`names.map(fs.renameSync)`, `fs['renameSync']`), `.call` / `.apply` / `.bind`, a
+ *   re-export (`export { renameSync } from 'node:fs'`). A file rename goes through
+ *   `renameFileAtomic`, which owns the Windows retry.
+ * - `reexport` — `export * from 'node:fs'`, which hands every banned function on.
+ *
+ * `unlink` is allowed: removing one file is not a tree change.
+ *
+ * Exempt: test files, and the entries of `exemptFiles`. An entry ending in `/` is a
+ * DIRECTORY (anchored at a path-segment boundary: the primitive's directory, the test
+ * infrastructure that lives in `src`); any other entry is one file. A bare name (`x.ts`
+ * or `tree-change/`) is reported as unanchored, because it would exempt that name in
+ * every package. No default exemption ships, so a consumer declares its own.
+ */
+
+const {
+  EXEMPT_FILES_SCHEMA,
+  UNANCHORED_EXEMPT_FILE,
+  UNANCHORED_EXEMPT_MESSAGE,
+  createExemptDirectoryMatcher,
+  createExemptPathMatcher,
+  isTestFile,
+  normalizeForMatch,
+  reportUnanchoredExemptEntries,
+} = require('./exempt-path-matcher.cjs');
+
+const FS_MODULES = new Set(['fs', 'node:fs', 'fs/promises', 'node:fs/promises']);
+
+/** `fs` function name -> the messageId that reports it. `rm` is judged by its options. */
+const MESSAGE_FOR = new Map([
+  ['rm', 'recursiveRm'],
+  ['rmSync', 'recursiveRm'],
+  ['rmdir', 'rmdir'],
+  ['rmdirSync', 'rmdir'],
+  ['rename', 'rename'],
+  ['renameSync', 'rename'],
+  ['cp', 'cp'],
+  ['cpSync', 'cp'],
+  ['copyFile', 'copyFile'],
+  ['copyFileSync', 'copyFile'],
+]);
+
+const UNANCHORED_EXEMPT_DIRECTORY = 'unanchoredExemptDirectory';
+const FUNCTION_TYPES = new Set(['FunctionExpression', 'ArrowFunctionExpression']);
+/** Wrappers that pass a value through unchanged. */
+const TRANSPARENT_TYPES = new Set(['AwaitExpression', 'TSAsExpression', 'TSNonNullExpression', 'TSSatisfiesExpression']);
+
+/** The string a property key or member property spells, or undefined when not static. */
+function staticName(node, computed) {
+  if (!computed) {
+    return node.type === 'Identifier' ? node.name : undefined;
+  }
+  return node.type === 'Literal' && typeof node.value === 'string' ? node.value : undefined;
+}
+
+/** True when `node` is a string literal naming an fs module. */
+function isFsModuleLiteral(node) {
+  return node?.type === 'Literal' && FS_MODULES.has(node.value);
+}
+
+/**
+ * True when the `rm` options (the call's arguments) are, or may be, recursive. Only an
+ * object literal that provably does not turn recursion on is safe.
+ */
+function mayBeRecursive(args) {
+  if (args.slice(0, 2).some((argument) => argument.type === 'SpreadElement')) {
+    return true;
+  }
+  const options = args[1];
+  if (options === undefined || FUNCTION_TYPES.has(options.type)) {
+    return false;
+  }
+  if (options.type !== 'ObjectExpression') {
+    return true;
+  }
+  return options.properties.some((property) => {
+    if (property.type !== 'Property') {
+      return true;
+    }
+    const key = staticName(property.key, property.computed);
+    if (key === undefined) {
+      return true;
+    }
+    return key === 'recursive' && !(property.value.type === 'Literal' && property.value.value === false);
+  });
+}
+
+/** `require('fs')` or `import('fs')`: an expression whose value is an fs namespace (a promise, for import). */
+function isDynamicFsSource(node) {
+  if (node.type === 'ImportExpression') {
+    return isFsModuleLiteral(node.source);
+  }
+  return (
+    node.type === 'CallExpression' &&
+    node.callee.type === 'Identifier' &&
+    node.callee.name === 'require' &&
+    isFsModuleLiteral(node.arguments[0])
+  );
+}
+
+/** The directory entries of `exemptFiles` that name no parent: `tree-change/`. */
+function bareDirectoryEntries(exemptFiles) {
+  return exemptFiles.filter((entry) => {
+    const normalized = normalizeForMatch(entry).replace(/^\/+/, '');
+    return normalized.endsWith('/') && !normalized.slice(0, -1).includes('/');
+  });
+}
+
+/** Match each exemption entry to the matcher its shape asks for. */
+function createExemptMatcher(exemptFiles) {
+  const normalized = exemptFiles.map((entry) => normalizeForMatch(entry));
+  const isUnderDirectory = createExemptDirectoryMatcher(normalized.filter((entry) => entry.endsWith('/')));
+  const isFile = createExemptPathMatcher(normalized.filter((entry) => !entry.endsWith('/')));
+  return (filename) => isUnderDirectory(filename) || isFile(filename);
+}
+
+/**
+ * Judges every use of the fs names in one file, through the scope manager.
+ *
+ * `namespaces` holds the variables whose value is an fs namespace; `banned` maps a
+ * variable to the fs function name it holds. Both grow as destructures and aliases are
+ * followed, and each variable is judged once.
+ */
+class FsUseJudge {
+  constructor(context) {
+    this.context = context;
+    this.sourceCode = context.sourceCode;
+    this.namespaces = new Set();
+    this.banned = new Map();
+    this.pending = [];
+  }
+
+  /** Seed from the imports and the dynamic sources, then follow every binding to a fixed point. */
+  run(programNode, dynamicSources) {
+    for (const statement of programNode.body) {
+      if (statement.type === 'ImportDeclaration' && isFsModuleLiteral(statement.source)) {
+        for (const specifier of statement.specifiers) this.seedImport(specifier);
+      }
+    }
+    for (const source of dynamicSources) this.useNamespace(source);
+    while (this.pending.length > 0) {
+      this.followReferences(this.pending.pop());
+    }
+  }
+
+  seedImport(specifier) {
+    const variable = this.sourceCode.getDeclaredVariables(specifier)[0];
+    const imported = specifier.type === 'ImportSpecifier' ? (specifier.imported.name ?? specifier.imported.value) : undefined;
+    if (imported === undefined || imported === 'promises') {
+      this.markNamespace(variable);
+    } else if (MESSAGE_FOR.has(imported)) {
+      this.markBanned(variable, imported);
+    }
+  }
+
+  followReferences(variable) {
+    const isNamespace = this.namespaces.has(variable);
+    for (const reference of variable.references.filter((candidate) => !candidate.init)) {
+      if (isNamespace) {
+        this.useNamespace(reference.identifier);
+      } else {
+        this.judgeBanned(reference.identifier, this.banned.get(variable));
+      }
+    }
+  }
+
+  markNamespace(variable) {
+    if (variable && !this.namespaces.has(variable)) {
+      this.namespaces.add(variable);
+      this.pending.push(variable);
+    }
+  }
+
+  markBanned(variable, name) {
+    if (variable && !this.banned.has(variable)) {
+      this.banned.set(variable, name);
+      this.pending.push(variable);
+    }
+  }
+
+  variableNamed(declaration, name) {
+    return this.sourceCode.getDeclaredVariables(declaration).find((variable) => variable.name === name);
+  }
+
+  /** Bind the names a destructuring pattern takes from an fs namespace. */
+  bindPattern(pattern, declaration) {
+    if (pattern.type === 'Identifier') {
+      this.markNamespace(this.variableNamed(declaration, pattern.name));
+    } else if (pattern.type === 'ObjectPattern') {
+      for (const property of pattern.properties) this.bindProperty(property, declaration);
+    }
+  }
+
+  bindProperty(property, declaration) {
+    if (property.type === 'RestElement') {
+      this.bindPattern(property.argument, declaration);
+      return;
+    }
+    const key = staticName(property.key, property.computed);
+    const target = property.value.type === 'AssignmentPattern' ? property.value.left : property.value;
+    if (key === 'promises') {
+      this.bindPattern(target, declaration);
+    } else if (MESSAGE_FOR.has(key) && target.type === 'Identifier') {
+      this.markBanned(this.variableNamed(declaration, target.name), key);
+    }
+  }
+
+  /** A banned function reached as `node`: report anything but a provably non-recursive `rm` call. */
+  judgeBanned(node, name) {
+    const parent = node.parent;
+    const isCall = parent.type === 'CallExpression' && parent.callee === node;
+    const isRm = MESSAGE_FOR.get(name) === 'recursiveRm';
+    if (isCall && isRm && !mayBeRecursive(parent.arguments)) {
+      return;
+    }
+    this.context.report({ node, messageId: MESSAGE_FOR.get(name), data: { name } });
+  }
+
+  /** `node` evaluates to an fs namespace: follow what its parent does with it. */
+  useNamespace(node) {
+    let current = node;
+    while (TRANSPARENT_TYPES.has(current.parent?.type)) {
+      current = current.parent;
+    }
+    const parent = current.parent;
+    if (parent?.type === 'MemberExpression' && parent.object === current) {
+      this.useMember(parent);
+    } else if (parent?.type === 'VariableDeclarator' && parent.init === current) {
+      this.bindPattern(parent.id, parent);
+    }
+  }
+
+  useMember(member) {
+    const name = staticName(member.property, member.computed);
+    if (name === 'promises') {
+      this.useNamespace(member);
+    } else if (MESSAGE_FOR.has(name)) {
+      this.judgeBanned(member, name);
+    }
+  }
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ban recursive rm, rmdir, rename, cp and copyFile outside the tree-change primitive: every tree change goes through one plan/apply protocol',
+      category: 'Filesystem and process',
+      bans: 'recursive `rm`/`rmSync`, `rmdir`, `rename`, `cp` and `copyFile` from `node:fs` / `node:fs/promises` (and their `Sync` forms), called or passed as values',
+      useInstead: '`planTreeChanges()` / `applyTreePlan()`, `renameFileAtomic()`, `replaceFile()`, `copyTree()`, `withTempDir()` / `disposeTempDir()`',
+      // Not in `recommended`: the remedy names this repo's own tree-change primitive,
+      // which an adopter does not have. VAT enables it explicitly, naming the
+      // primitive's directory and the test infrastructure that lives in `src`.
+      recommended: false,
+      recommendedSeverity: 'error',
+    },
+    fixable: null,
+    schema: [EXEMPT_FILES_SCHEMA],
+    messages: {
+      recursiveRm:
+        '{{name}} removes a tree, or may (its options are not a literal that rules recursion out). ' +
+        'Plan the removal with planTreeChanges() / applyTreePlan(), or dispose a temp dir with withTempDir() / disposeTempDir(). ' +
+        'Removing one file is fine: rm(file, { force: true }) or unlink().',
+      rmdir: '{{name}} is a tree removal. Use planTreeChanges() / applyTreePlan() (op: remove) or disposeTempDir().',
+      rename:
+        '{{name}} is half a swap protocol. Replace a tree with planTreeChanges() / applyTreePlan(); ' +
+        'rename a single file with renameFileAtomic(), which owns the Windows retry.',
+      cp: '{{name}} copies a tree outside the primitive. Use copyTree(), or a replace change in planTreeChanges().',
+      copyFile: '{{name}} copies a file outside the primitive. Use copyTree() or replaceFile().',
+      reexport: 'Re-exporting every node:fs function hands on rm, rename, cp and copyFile. Export the names you need.',
+      [UNANCHORED_EXEMPT_FILE]: UNANCHORED_EXEMPT_MESSAGE,
+      [UNANCHORED_EXEMPT_DIRECTORY]:
+        'exemptFiles entry "{{entry}}" is a bare directory name, so it exempts EVERY directory named ' +
+        '"{{entry}}" in the repo — including ones added later. Give the repo-relative path instead ' +
+        '(e.g. "packages/utils/src/{{entry}}").',
+    },
+  },
+
+  create(context) {
+    const filename = context.getFilename();
+    const configured = context.options?.[0]?.exemptFiles;
+    const exemptFiles = Array.isArray(configured) ? configured : [];
+    const isExempt = createExemptMatcher(exemptFiles);
+
+    /** Surface a malformed exemption list even for an exempt file: it may be exempt only BECAUSE of it. */
+    const reportExemptions = (node) => {
+      reportUnanchoredExemptEntries(context, node);
+      for (const entry of bareDirectoryEntries(exemptFiles)) {
+        context.report({ node, messageId: UNANCHORED_EXEMPT_DIRECTORY, data: { entry } });
+      }
+    };
+
+    if (isExempt(filename)) {
+      return { Program: reportExemptions };
+    }
+    if (isTestFile(filename)) {
+      return {};
+    }
+
+    const dynamicSources = [];
+
+    return {
+      Program: reportExemptions,
+
+      'CallExpression, ImportExpression'(node) {
+        if (isDynamicFsSource(node)) {
+          dynamicSources.push(node);
+        }
+      },
+
+      ExportNamedDeclaration(node) {
+        if (!isFsModuleLiteral(node.source)) {
+          return;
+        }
+        for (const specifier of node.specifiers) {
+          const name = specifier.local.name ?? specifier.local.value;
+          if (MESSAGE_FOR.has(name)) {
+            context.report({ node: specifier, messageId: MESSAGE_FOR.get(name), data: { name } });
+          }
+        }
+      },
+
+      ExportAllDeclaration(node) {
+        if (isFsModuleLiteral(node.source)) {
+          context.report({ node, messageId: 'reexport' });
+        }
+      },
+
+      'Program:exit'(node) {
+        new FsUseJudge(context).run(node, dynamicSources);
+      },
+    };
+  },
+};

package/eslint/rules/no-existssync.cjs

@@ -0,0 +1,70 @@
+/**
+ * ESLint rule: no-existssync
+ *
+ * In product source, flags every use of `existsSync` from `node:fs` / `fs`:
+ * a named import (aliased too) that is called or handed on as a value, a
+ * namespace, default, `require()` or `await import()` binding read as
+ * `fs.existsSync`, the same read straight off the loading expression
+ * (`require('node:fs').existsSync`, `(await import('node:fs')).existsSync`), a
+ * destructure of it out of any of those, and a re-export.
+ *
+ * `existsSync` answers `false` for `ENOENT` — and equally for `EACCES` (a
+ * parent the process may not search), `ELOOP` and every other errno. So a
+ * path the OS would not let VAT look at reads as "absent", and the run goes on
+ * as if it were: a LICENSE is skipped, a manifest is "not found", a plugin
+ * directory is missing. The replacement asks the one errno classifier:
+ * `pathPresent(path, mode, sideOf, absence)` from `@vibe-agent-toolkit/utils` answers
+ * `false` only for an absence, and throws every other errno as a classified
+ * `FS_FAULT` on the caller's side.
+ *
+ * ## Scope
+ *
+ * Product source: a file under `packages/<pkg>/src/` that is not itself a test
+ * file. Tests and test-support (`packages/<pkg>/test/`) are not linted — a
+ * fixture asking whether its own scratch file exists is not a run deciding
+ * what to do. Like `no-io-in-unit-tier`, the layout is this repo's, which is
+ * why the rule is not in `configs.recommended`.
+ *
+ * ## The floor — what this rule cannot see
+ *
+ * It follows bindings through scope, not values through data flow:
+ * - an fs namespace copied first (`const f = fs; f.existsSync(p)`) or passed
+ *   as an argument;
+ * - `import('node:fs').then((fs) => fs.existsSync(p))`, and a `require`
+ *   built by `createRequire`;
+ * - a project module that re-exports it under another name is caught at its
+ *   own `export { existsSync } from 'node:fs'`, not at the importers of that
+ *   module.
+ *
+ * Option `allowFiles: string[]` — repo-relative paths of today's offenders,
+ * the ratchet. Name files, never directories.
+ *
+ * @example
+ * // BAD — an EACCES parent reads as "no manifest"
+ * if (!existsSync(manifestPath)) return emptyInventory();
+ *
+ * // GOOD — absent is false; a refused stat throws a classified FS_FAULT
+ * if (!pathPresent(manifestPath, { follow: pluginDir }, everywhere('source'), 'probe')) return emptyInventory();
+ */
+
+'use strict';
+
+const { productSourceFsBan } = require('./fs-binding-scan.cjs');
+
+module.exports = productSourceFsBan({
+  docs: {
+    description:
+      'Disallow existsSync from node:fs in product source — it answers false for a path it could not ' +
+      'look at (EACCES, ELOOP) exactly as for one that is not there',
+    bans: '`existsSync()` from `node:fs` — called, handed on, destructured or re-exported — under `packages/*/src/`',
+    useInstead: '`pathPresent(path, mode, sideOf, absence)` (absent only on an absence; every other errno a classified `FS_FAULT`)',
+  },
+  messageId: 'existsSync',
+  message:
+    'existsSync answers false for a path it could not look at (EACCES, ELOOP) exactly as for one that is ' +
+    'not there, so "could not look" goes on as "absent". Use pathPresent(path, mode, sideOf, absence) from ' +
+    '@vibe-agent-toolkit/utils: false only for an absence, every other errno a classified FS_FAULT.',
+  modules: new Set(['node:fs', 'fs']),
+  banned: new Set(['existsSync']),
+  untyped: null,
+});

package/eslint/rules/no-fragile-entrypoint-guard.cjs

@@ -25,7 +25,8 @@
  * every gate:
  *
  * - `import.meta.main` was added in Node **24.2 / 22.18**. Measured on the exact
- *   floor this repo declares — `>=22.13.0` — the property is `undefined`:
+ *   floor this repo declares — `>=22.16.0`, and on 22.13.0 before it — the
+ *   property is `undefined`:
  *
  *   ```
  *   $ node-v22.13.0 --input-type=module -e "console.log(import.meta.main)"  -> undefined
@@ -186,7 +187,7 @@ module.exports = {
       // Node floor rather than a portable fact. `import.meta.main` shipped in Node
       // 24.2 / 22.18; an adopter whose floor is at or above that writes it
       // correctly and would get a finding they cannot act on. This package's own
-      // floor spans 22.13–22.17 where the property is `undefined`, so the hazard
+      // floor spans 22.16–22.17 where the property is `undefined`, so the hazard
       // is real for some adopters and absent for others, and only they know which.
       // The other half (`rawEntrypointCompare`) has no such dependency — a raw
       // string compare misses a symlinked entry on every Node there has ever been

package/eslint/rules/no-link-following-fs.cjs

@@ -0,0 +1,68 @@
+/**
+ * ESLint rule: no-link-following-fs
+ *
+ * In product source, flags every use of an fs call that FOLLOWS a symbolic link —
+ * `stat`, `statSync`, `existsSync`, `realpath`, `realpathSync` (and their
+ * `.native` forms), from `node:fs`, `fs`, `node:fs/promises` or `fs/promises`,
+ * however reached (see `fs-binding-scan.cjs`).
+ *
+ * A Windows kernel asked to follow a link to `\\host\share` opens an SMB session
+ * and offers the operator's NTLM credentials to that host before any answer comes
+ * back. So the kernel may be asked to follow a link only once the chain to it has
+ * been read by its text, hop by hop, and shown local — which the one guarded module
+ * does (`@vibe-agent-toolkit/utils` `followedStatSync`, `followedKindSync`,
+ * `realpathNativeSync`, `pathPresent(path, { follow: within }, …)`). Three rounds of
+ * hand sweeps for "the sites that resolve links" each missed sites; this rule is
+ * the sweep.
+ *
+ * `symlink` and `symlinkSync` are flagged unless CALLED with a third argument (the
+ * link's type): with none, Node on Windows `stat`s the target to pick `file` or `dir`,
+ * so creating a link is a follow of its unread text. The type is read syntactically —
+ * a callback passed by name in the third place reads as a type.
+ *
+ * `lstat`, `fstat`, a file handle's `stat()` and `readlink` follow nothing and are
+ * not flagged. Opening or reading a file through a link is outside this rule.
+ *
+ * ## Scope
+ *
+ * Product source: a file under `packages/<pkg>/src/` that is not itself a test
+ * file — the layout is this repo's, which is why the rule is not in
+ * `configs.recommended`.
+ *
+ * Option `allowFiles: string[]` — repo-relative paths: the guarded module itself,
+ * and files whose every such call acts on the operator's own path, each with its
+ * reason beside it in the config. The repo's config derives the list from
+ * `LINK_FOLLOWING_FS_CALLS`, which pins how many calls each listed file holds;
+ * `dev-tools/test/eslint-allowlist-ratchets.test.ts` asserts that count exactly —
+ * one more call in a listed file is red, and so is one fewer.
+ */
+
+'use strict';
+
+const { productSourceFsBan } = require('./fs-binding-scan.cjs');
+
+module.exports = productSourceFsBan({
+  docs: {
+    description:
+      'Disallow fs calls that follow a symbolic link (stat, existsSync, realpath) in product source outside the ' +
+      'guarded module — the kernel would follow a link no walk has read',
+    bans: '`stat`/`statSync`/`existsSync`/`realpath`/`realpathSync`, and `symlink`/`symlinkSync` called with no type, from `node:fs` or `node:fs/promises` under `packages/*/src/`',
+    useInstead: '`followedStatSync`/`followedKindSync`/`realpathNativeSync(path, within)` or `pathPresent(path, { follow: within }, …)`',
+  },
+  messageId: 'follows',
+  message:
+    '`{{name}}` follows a symbolic link with no walk of its chain first: on Windows a link to \\\\host\\share ' +
+    'sends the operator\'s credentials to that host. Use followedStatSync / followedKindSync / ' +
+    'realpathNativeSync(path, within) or pathPresent(path, { follow: within }, …) from @vibe-agent-toolkit/utils.',
+  modules: new Set(['node:fs', 'fs', 'node:fs/promises', 'fs/promises']),
+  banned: new Set(['stat', 'statSync', 'existsSync', 'realpath', 'realpathSync']),
+  untyped: {
+    names: new Set(['symlink', 'symlinkSync']),
+    messageId: 'untypedLink',
+    message:
+      '`{{name}}` with no type has Node on Windows `stat` the target to pick `file` or `dir` — the kernel ' +
+      'follows a link text no walk has read, and a text naming a network share sends the operator\'s ' +
+      'credentials to the share\'s host. Pass the type, decided from what VAT already read — for a link being ' +
+      'copied, from its chain read by text (`copyTree` asks `linkCopyType` in utils `link-following.ts`).',
+  },
+});

package/eslint/rules/no-literal-process-exit.cjs

@@ -20,17 +20,68 @@
  * segment boundary via `exempt-path-matcher.cjs`; give the full repo-relative
  * path, not a bare basename.
  *
+ * ## Option `derived` — the code is DERIVED from the document, not chosen
+ *
+ * Naming a member is not enough. `process.exit(refused ? ExitCode.FINDINGS :
+ * ExitCode.OK)` names members and still re-decides, beside the document, what
+ * the document means — and one outcome shipped with different codes in
+ * different verbs that way (a budget kill 1-or-2 by timing; an unreadable root
+ * 2 in one verb and 1 in another). Under `derived.paths`:
+ *
+ * - `ExitCode.FINDINGS` may not be NAMED at all. "What it examined failed its
+ *   gate" is a claim about a published document, so it comes from
+ *   `exitCodeForReport(document)` (`@vibe-agent-toolkit/schema`) and nowhere else.
+ * - `process.exit(x)` / `process.exitCode = x` takes `ExitCode.OK`,
+ *   `ExitCode.ERROR`, or a call to one of `derived.calls` (the derivations:
+ *   `exitCodeForReport`, `exitCodeOfChild`, …). A ternary, a variable or a
+ *   forwarded field is a code decided somewhere this rule cannot see.
+ * - No file under `derived.paths` is exempt: the migration ratchet that once
+ *   listed the undelivered verbs reached zero and went, and the option with it.
+ *
+ * ⚠️ What this cannot see: a document verb ending on a bare `ExitCode.OK` over a
+ * document that says `error`. That is a runtime fact, pinned by the exit-code
+ * matrix system test, not a syntactic one.
+ *
  * @example
  * // BAD — 1 means what, exactly?
  * process.exit(1);
  *
- * // GOOD — the meaning is the code
- * process.exit(ExitCode.FINDINGS);
+ * // BAD under `derived` — the call site decides what the document means
+ * process.exit(errors > 0 ? ExitCode.FINDINGS : ExitCode.OK);
+ *
+ * // GOOD — derived from what was published
+ * process.exit(exitCodeForReport(report));
  */
 
 'use strict';
 
-const { createExemptPathMatcher } = require('./exempt-path-matcher.cjs');
+const { createExemptDirectoryMatcher, createExemptPathMatcher, isTestFile } = require('./exempt-path-matcher.cjs');
+
+/** The members a call site may name outright: neither is a claim about a document. */
+const UNDERIVED_MEMBERS = new Set(['OK', 'ERROR']);
+
+/** Whether `node` is `ExitCode.<name>` (non-computed). */
+function isExitCodeMember(node, name) {
+  return (
+    node.type === 'MemberExpression' &&
+    !node.computed &&
+    node.object.type === 'Identifier' &&
+    node.object.name === 'ExitCode' &&
+    node.property.type === 'Identifier' &&
+    (name === undefined ? UNDERIVED_MEMBERS.has(node.property.name) : node.property.name === name)
+  );
+}
+
+/** The called function's own name — `f(…)` or `x.f(…)` — or null. */
+function calleeName(node) {
+  if (node.type !== 'CallExpression') return null;
+  const { callee } = node;
+  if (callee.type === 'Identifier') return callee.name;
+  if (callee.type === 'MemberExpression' && !callee.computed && callee.property.type === 'Identifier') {
+    return callee.property.name;
+  }
+  return null;
+}
 
 /** Whether `node` is the member expression `process.<name>` (non-computed). */
 function isProcessMember(node, name) {
@@ -84,6 +135,15 @@ module.exports = {
         type: 'object',
         properties: {
           allow: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+          derived: {
+            type: 'object',
+            properties: {
+              paths: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+              calls: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+            },
+            required: ['paths', 'calls'],
+            additionalProperties: false,
+          },
         },
         additionalProperties: false,
       },
@@ -96,34 +156,62 @@ module.exports = {
       literalExitCode:
         'process.exitCode = {{literal}} re-decides the exit contract at this site. Assign an ' +
         'ExitCode member from @vibe-agent-toolkit/schema instead.',
+      findingsNotDerived:
+        'ExitCode.FINDINGS is a claim about a published document ("what it examined failed its ' +
+        'gate"). Derive it: process.exit(exitCodeForReport(document)) — never name it at a call site.',
+      exitNotDerived:
+        'This exit code is decided here, beside the document, where it can disagree with it. Exit ' +
+        'with ExitCode.OK, ExitCode.ERROR, or a derivation: {{calls}}.',
     },
   },
 
   create(context) {
     const allow = context.options?.[0]?.allow ?? [];
+    const derived = context.options?.[0]?.derived;
     const filename = context.filename ?? context.getFilename();
     if (createExemptPathMatcher(allow)(filename)) {
       return {};
     }
 
+    const inDerived = derived !== undefined
+      && !isTestFile(filename)
+      && createExemptDirectoryMatcher(derived.paths)(filename);
+    const derivations = new Set(derived?.calls ?? []);
+
+    function reportDerived(node, messageId) {
+      context.report({ node, messageId, data: { calls: [...derivations].join(', ') } });
+    }
+
+    /** @returns {boolean} Whether a literal was reported (so nothing else is). */
     function reportLiteral(node, expr, messageId) {
       const leaf = numericLiteralLeaf(expr);
-      if (leaf !== null) {
-        context.report({ node, messageId, data: { literal: String(leaf.raw ?? leaf.value) } });
-      }
+      if (leaf === null) return false;
+      context.report({ node, messageId, data: { literal: String(leaf.raw ?? leaf.value) } });
+      return true;
+    }
+
+    function checkExitValue(node, expr, literalMessageId) {
+      if (reportLiteral(node, expr, literalMessageId) || !inDerived) return;
+      if (isExitCodeMember(expr) || derivations.has(calleeName(expr))) return;
+      // `ExitCode.FINDINGS` itself is reported by the member visitor below.
+      if (isExitCodeMember(expr, 'FINDINGS')) return;
+      reportDerived(node, 'exitNotDerived');
     }
 
     return {
       CallExpression(node) {
         if (isProcessMember(node.callee, 'exit') && node.arguments.length > 0) {
-          reportLiteral(node, node.arguments[0], 'literalExit');
+          checkExitValue(node, node.arguments[0], 'literalExit');
         }
       },
       AssignmentExpression(node) {
         if (isProcessMember(node.left, 'exitCode')) {
-          reportLiteral(node, node.right, 'literalExitCode');
+          checkExitValue(node, node.right, 'literalExitCode');
         }
       },
+      MemberExpression(node) {
+        if (inDerived && isExitCodeMember(node, 'FINDINGS')) reportDerived(node, 'findingsNotDerived');
+      },
     };
   },
 };