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

package/eslint/rules/fs-binding-scan.cjs

@@ -0,0 +1,278 @@
+/**
+ * Shared scanner: every read of a named `node:fs` function, however it is reached.
+ *
+ * `no-existssync` and `no-link-following-fs` both ban functions of the fs module,
+ * and both must see the same shapes — 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.name` (or `fs.promises.name`), the same read straight off the
+ * loading expression (`require('node:fs').name`), a destructure of it out of any
+ * of those, and a re-export. One copy, so the two rules cannot drift apart on what
+ * counts as a use.
+ *
+ * It follows bindings through scope, not values through data flow: an fs namespace
+ * copied first (`const f = fs`) or passed as an argument, `import('node:fs').then`,
+ * and a `require` built by `createRequire` are not seen. A project module that
+ * re-exports a banned function is caught at its own re-export.
+ *
+ * Also the one shape of such a rule ({@link productSourceFsBan}): its scope, its `allowFiles`
+ * option and its report — each rule supplies only what it bans and why.
+ *
+ * Exports no `meta`, so the plugin entry point does not register it as a rule.
+ */
+
+'use strict';
+
+const { createExemptPathMatcher, isTestFile, normalizeForMatch } = require('./exempt-path-matcher.cjs');
+
+/** `packages/<pkg>/src/` anywhere in a forward-slashed path. */
+const PACKAGE_SRC_DIR = /(?:^|\/)packages\/[^/]+\/src\//u;
+
+/** Whether `filename` is product source: under a package's `src/`, and not a test file. */
+function isProductSource(filename) {
+  if (!filename) {
+    return false;
+  }
+  const normalized = normalizeForMatch(filename);
+  return PACKAGE_SRC_DIR.test(normalized) && !isTestFile(normalized);
+}
+
+/** The string a key spells: an identifier's name or a string literal's value, else null. */
+function spelledName(node, computed) {
+  if (node?.type === 'Literal' && typeof node.value === 'string') {
+    return node.value;
+  }
+  return !computed && node?.type === 'Identifier' ? node.name : null;
+}
+
+/** TypeScript wrappers that change a value's type, never the value: `x as T`, `x!`, `x satisfies T`. */
+const TYPE_ONLY_WRAPPERS = new Set(['TSAsExpression', 'TSNonNullExpression', 'TSSatisfiesExpression']);
+
+/** `node` with every type-only wrapper and one `await` peeled off. */
+function unwrapped(node) {
+  let expr = node;
+  while (TYPE_ONLY_WRAPPERS.has(expr?.type)) {
+    expr = expr.expression;
+  }
+  return expr?.type === 'AwaitExpression' ? unwrapped(expr.argument) : expr;
+}
+
+/**
+ * The module a `require('x')`, `import('x')` or `await import('x')` initialiser
+ * loads (a `require('x') as typeof X` too), or null for any other initialiser
+ * (or a computed specifier).
+ */
+function loadedModuleOf(init) {
+  const expr = unwrapped(init);
+  if (expr?.type === 'ImportExpression') {
+    return spelledName(expr.source, true);
+  }
+  const isRequire = expr?.type === 'CallExpression' && expr.callee.type === 'Identifier' && expr.callee.name === 'require';
+  return isRequire ? spelledName(expr.arguments[0], true) : null;
+}
+
+/** The namespace of the fs module's promise API, read off the module: `fs.promises`. */
+const PROMISES = 'promises';
+
+/**
+ * The visitors that report every use of a `banned` function of a `modules` module.
+ *
+ * @param {import('eslint').Rule.RuleContext} context - The rule's context
+ * @param {{ modules: ReadonlySet<string>, banned: ReadonlySet<string>, report: (node: object, name: string) => void }} spec
+ *   - `modules`: the specifiers that load the fs module (`node:fs`, `fs`, and any promise flavour)
+ *   - `banned`: the function names to report
+ *   - `report`: called once per use, with the node and the banned name it reaches
+ */
+function fsBindingVisitors(context, { modules, banned, report }) {
+  const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+  /** Every read of a binding that holds a banned function itself. */
+  function reportReads(variable, name) {
+    for (const ref of variable?.references ?? []) {
+      if (ref.isRead()) {
+        report(ref.identifier, name);
+      }
+    }
+  }
+
+  /** `const { name } = <fs>`: the bindings the pattern makes of a banned function, or of `promises`. */
+  function reportDestructured(declarator) {
+    if (declarator.id.type !== 'ObjectPattern') {
+      return;
+    }
+    const variables = sourceCode.getDeclaredVariables(declarator);
+    for (const prop of declarator.id.properties) {
+      const key = prop.type === 'Property' ? spelledName(prop.key, prop.computed) : null;
+      if (prop.type !== 'Property' || prop.value.type !== 'Identifier' || key === null) {
+        continue;
+      }
+      const variable = variables.find((candidate) => candidate.name === prop.value.name);
+      if (banned.has(key)) {
+        reportReads(variable, key);
+      } else if (key === PROMISES) {
+        scanNamespace(variable);
+      }
+    }
+  }
+
+  /** `<ns>.name`, `<ns>['name']` and `<ns>.promises.name` off one namespace expression. */
+  function scanMember(node) {
+    const parent = node.parent;
+    if (parent.type !== 'MemberExpression' || parent.object !== node) {
+      return;
+    }
+    const name = spelledName(parent.property, parent.computed);
+    if (banned.has(name)) {
+      report(parent, name);
+    } else if (name === PROMISES) {
+      scanMember(parent);
+    }
+  }
+
+  /** A binding of the whole fs module: `fs.name` / `fs['name']`, and a destructure of it. */
+  function scanNamespace(variable) {
+    for (const ref of variable?.references ?? []) {
+      const id = ref.identifier;
+      const parent = id.parent;
+      if (!ref.isRead()) {
+        continue;
+      }
+      if (parent.type === 'VariableDeclarator' && parent.init === id) {
+        reportDestructured(parent);
+      } else {
+        scanMember(id);
+      }
+    }
+  }
+
+  return {
+    ImportDeclaration(node) {
+      if (node.importKind === 'type' || !modules.has(node.source.value)) {
+        return;
+      }
+      for (const spec of node.specifiers) {
+        const [variable] = sourceCode.getDeclaredVariables(spec);
+        const imported = spec.type === 'ImportSpecifier' ? spelledName(spec.imported, false) : null;
+        if (spec.type !== 'ImportSpecifier' || imported === PROMISES) {
+          scanNamespace(variable);
+        } else if (spec.importKind !== 'type' && banned.has(imported)) {
+          reportReads(variable, imported);
+        }
+      }
+    },
+    // `import fs = require('node:fs')`.
+    TSImportEqualsDeclaration(node) {
+      const ref = node.moduleReference;
+      if (ref.type === 'TSExternalModuleReference' && modules.has(spelledName(ref.expression, true))) {
+        scanNamespace(sourceCode.getDeclaredVariables(node)[0]);
+      }
+    },
+    VariableDeclarator(node) {
+      if (!modules.has(loadedModuleOf(node.init))) {
+        return;
+      }
+      if (node.id.type === 'Identifier') {
+        scanNamespace(sourceCode.getDeclaredVariables(node)[0]);
+      } else {
+        reportDestructured(node);
+      }
+    },
+    // `require('node:fs').name` / `(await import('node:fs')).name`: no binding to follow.
+    MemberExpression(node) {
+      const name = spelledName(node.property, node.computed);
+      if (banned.has(name) && modules.has(loadedModuleOf(node.object))) {
+        report(node, name);
+      }
+    },
+    ExportNamedDeclaration(node) {
+      if (!modules.has(node.source?.value)) {
+        return;
+      }
+      for (const spec of node.specifiers) {
+        const name = spelledName(spec.local, false);
+        if (banned.has(name)) {
+          report(spec, name);
+        }
+      }
+    },
+    ExportAllDeclaration(node) {
+      if (modules.has(node.source.value)) {
+        report(node, '*');
+      }
+    },
+  };
+}
+
+/** The syntax of a value that is a function, never a link type: `() => …`, `function () {}`. */
+const FUNCTION_LITERALS = new Set(['ArrowFunctionExpression', 'FunctionExpression']);
+
+/**
+ * Whether the use at `node` is a CALL that passes a third argument which can be a link type — not a
+ * function literal (a callback), not `undefined`, not `null`. Syntax only: a callback passed by
+ * name in the third place (`fs.symlink(t, p, done)`) reads as a type, as a variable holding one does.
+ */
+function passesThirdArgument(node) {
+  const call = node.parent;
+  if (call?.type !== 'CallExpression' || call.callee !== node) {
+    return false;
+  }
+  const third = call.arguments[2];
+  if (third === undefined || FUNCTION_LITERALS.has(third.type)) {
+    return false;
+  }
+  return !(third.type === 'Identifier' && third.name === 'undefined') && !(third.type === 'Literal' && third.value === null);
+}
+
+/**
+ * A rule banning fs functions in product source (`packages/<pkg>/src/`, not a test file), with an
+ * `allowFiles: string[]` option of repo-relative paths it skips. Not recommended: the scope is a
+ * claim about this repo's layout, and an adopter's tree has its own.
+ *
+ * @param {object} spec
+ * @param {{ description: string, bans: string, useInstead: string }} spec.docs - The rule's docs
+ * @param {string} spec.messageId - The id of its message for a `banned` function
+ * @param {string} spec.message - The message; `{{name}}` is the banned function's name
+ * @param {Set<string>} spec.modules - The module specifiers whose functions are banned
+ * @param {Set<string>} spec.banned - The function names banned in every use
+ * @param {{ names: Set<string>, messageId: string, message: string } | null} spec.untyped - Functions
+ *   banned in every use EXCEPT a call that passes a third (type) argument — `symlink`, whose type
+ *   Node on Windows otherwise picks by following the target — and their message; `null` for none
+ */
+function productSourceFsBan({ docs, messageId, message, modules, banned, untyped }) {
+  const untypedNames = untyped?.names ?? new Set();
+  const scanned = new Set([...banned, ...untypedNames]);
+  const messages = untyped === null ? { [messageId]: message } : { [messageId]: message, [untyped.messageId]: untyped.message };
+  return {
+    meta: {
+      type: 'problem',
+      docs: { ...docs, category: 'Filesystem and process', recommended: false, recommendedSeverity: 'error' },
+      schema: [
+        {
+          type: 'object',
+          properties: {
+            allowFiles: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+          },
+          additionalProperties: false,
+        },
+      ],
+      messages,
+    },
+
+    create(context) {
+      const filename = context.filename ?? context.getFilename();
+      const isAllowed = createExemptPathMatcher(context.options?.[0]?.allowFiles ?? []);
+      if (!isProductSource(filename) || isAllowed(filename)) {
+        return {};
+      }
+      const report = (node, name) => {
+        if (!untypedNames.has(name)) {
+          context.report({ node, messageId, data: { name } });
+        } else if (!passesThirdArgument(node)) {
+          context.report({ node, messageId: untyped.messageId, data: { name } });
+        }
+      };
+      return fsBindingVisitors(context, { modules, banned: scanned, report });
+    },
+  };
+}
+
+module.exports = { fsBindingVisitors, isProductSource, productSourceFsBan };

package/eslint/rules/no-adhoc-errno.cjs

@@ -0,0 +1,364 @@
+/**
+ * ESLint rule: no-adhoc-errno
+ *
+ * Bans classifying a filesystem failure by hand. An errno name written as a string
+ * in a classifying position is a private errno table, and every private table
+ * decides a refusal code a little differently from its neighbours. One classifier
+ * (`fsFaultOf` / `classifyFsFault`, plus the single-errno predicates such as
+ * `isPathAbsentError`) owns the vocabulary; everything else asks it.
+ *
+ * Two reports:
+ *
+ * - `literal` — an errno name as a string that is (a) an operand of `===` `!==`
+ *   `==` `!=`, (b) a `switch` `case` test, (c) an element of an array literal that
+ *   is passed to `new Set(...)` or bound to a `const`, or (d) the argument of
+ *   `.has()` / `.includes()`. (d) also catches the message match
+ *   `errorMessage.includes('ENOENT')`, which hides an errno in prose.
+ * - `adhocRefusal` — inside a `catch (e)`, a `new CommandRefusalError(...)` or
+ *   `new VatError(...)` whose options carry `cause: e`, where the same catch body
+ *   also reads `e.code` or calls `fsFaultOf(e)` / `isPathAbsentError(e)`. The catch
+ *   is deciding the refusal itself; `classifyFsFault` decides it once.
+ *
+ * An inline array is a lookup table too: `['ENOENT', 'EACCES'].includes(e.code)` (and
+ * `.some` / `.indexOf` / `.find` / `.findIndex` / `.every`). An identifier bound once
+ * by `const` to an errno string (`const C = 'ENOENT'; e.code === C`) is flagged at its
+ * use, and a template literal with no expressions counts as the string it spells.
+ *
+ * What counts as an errno is a SET, not a pattern: the union of
+ * `os.constants.errno` across hosts, plus `EFTYPE` and `UNKNOWN` (libuv names Node
+ * does not export) and `EHOSTDOWN` (which Node on macOS omits). A name that merely
+ * looks like one (`EXAMPLE`) is not flagged, and `EOF` is not an errno, so it needs
+ * no special case.
+ *
+ * Deliberately out of scope (each is a position this rule does not read):
+ * - helper-call arguments, `isErr(e, 'ENOENT')`: the callee is the private table,
+ *   and judging arbitrary calls would flag every legitimate use of a name;
+ * - object literals, `{ code: 'ENOENT' }` / `{ ENOENT: 1 }`: those build or describe
+ *   an error (fixtures, tables keyed by name), they do not classify one;
+ * - dynamic strings, built with a template expression or `+`: not decidable statically.
+ *
+ * Exempt: test files, and the files named by `exemptFiles` (the ones that must name
+ * errnos: the errno table, the git-stderr parser, the fault-injecting fs). No
+ * default exemption ships, so a consumer declares its own.
+ */
+
+const {
+  EXEMPT_FILES_SCHEMA,
+  UNANCHORED_EXEMPT_FILE,
+  UNANCHORED_EXEMPT_MESSAGE,
+  createConfigurableExemptPathMatcher,
+  isTestFile,
+  reportUnanchoredExemptEntries,
+} = require('./exempt-path-matcher.cjs');
+
+/**
+ * The errno vocabulary, spelled out so the set is identical on every host.
+ *
+ * `os.constants.errno` differs by platform (Linux exports names macOS omits, and
+ * macOS omits `EHOSTDOWN`), so reading it at lint time would make the rule pass on
+ * one CI leg and fail on another. A rule module also may not require any external
+ * module (`subpath-purity.test.ts`). So the union is written out here, and
+ * `no-adhoc-errno.test.ts` fails if this host's `os.constants.errno` has a key the
+ * list lacks. `EFTYPE` and `UNKNOWN` are libuv names Node does not export.
+ */
+const ERRNO_NAMES = new Set([
+  'E2BIG', 'EACCES', 'EADDRINUSE', 'EADDRNOTAVAIL', 'EAFNOSUPPORT', 'EAGAIN', 'EALREADY',
+  'EBADF', 'EBADMSG', 'EBUSY', 'ECANCELED', 'ECHILD', 'ECONNABORTED', 'ECONNREFUSED',
+  'ECONNRESET', 'EDEADLK', 'EDESTADDRREQ', 'EDOM', 'EDQUOT', 'EEXIST', 'EFAULT', 'EFBIG',
+  'EHOSTUNREACH', 'EIDRM', 'EILSEQ', 'EINPROGRESS', 'EINTR', 'EINVAL', 'EIO', 'EISCONN',
+  'EISDIR', 'ELOOP', 'EMFILE', 'EMLINK', 'EMSGSIZE', 'EMULTIHOP', 'ENAMETOOLONG', 'ENETDOWN',
+  'ENETRESET', 'ENETUNREACH', 'ENFILE', 'ENOBUFS', 'ENODATA', 'ENODEV', 'ENOENT', 'ENOEXEC',
+  'ENOLCK', 'ENOLINK', 'ENOMEM', 'ENOMSG', 'ENOPROTOOPT', 'ENOSPC', 'ENOSR', 'ENOSTR',
+  'ENOSYS', 'ENOTCONN', 'ENOTDIR', 'ENOTEMPTY', 'ENOTSOCK', 'ENOTSUP', 'ENOTTY', 'ENXIO',
+  'EOPNOTSUPP', 'EOVERFLOW', 'EPERM', 'EPIPE', 'EPROTO', 'EPROTONOSUPPORT', 'EPROTOTYPE',
+  'ERANGE', 'EROFS', 'ESPIPE', 'ESRCH', 'ESTALE', 'ETIME', 'ETIMEDOUT', 'ETXTBSY',
+  'EWOULDBLOCK', 'EXDEV',
+  // Linux-only names:
+  'EADV', 'EBADE', 'EBADFD', 'EBADR', 'EBADRQC', 'EBADSLT', 'EBFONT', 'ECHRNG', 'ECOMM',
+  'EDEADLOCK', 'EDOTDOT', 'EISNAM', 'EKEYEXPIRED', 'EKEYREJECTED', 'EKEYREVOKED', 'EL2HLT',
+  'EL2NSYNC', 'EL3HLT', 'EL3RST', 'ELIBACC', 'ELIBBAD', 'ELIBEXEC', 'ELIBMAX', 'ELIBSCN',
+  'ELNRNG', 'EMEDIUMTYPE', 'ENAVAIL', 'ENOANO', 'ENOKEY', 'ENOMEDIUM', 'ENONET', 'ENOPKG',
+  'ENOTBLK', 'ENOTNAM', 'ENOTRECOVERABLE', 'ENOTUNIQ', 'EOWNERDEAD', 'EPFNOSUPPORT', 'EREMCHG',
+  'EREMOTE', 'EREMOTEIO', 'ERESTART', 'ERFKILL', 'ESHUTDOWN', 'ESOCKTNOSUPPORT', 'ESRMNT',
+  'ESTRPIPE', 'ETOOMANYREFS', 'EUCLEAN', 'EUNATCH', 'EUSERS', 'EXFULL',
+  // Not in os.constants.errno on every host:
+  'EFTYPE', 'UNKNOWN', 'EHOSTDOWN',
+]);
+
+const COMPARISON_OPERATORS = new Set(['===', '!==', '==', '!=']);
+const MEMBERSHIP_METHODS = new Set(['has', 'includes']);
+/** Methods that make an INLINE array literal a lookup table: `['ENOENT'].includes(e.code)`. */
+const ARRAY_LOOKUP_METHODS = new Set(['includes', 'some', 'indexOf', 'find', 'findIndex', 'every']);
+const FUNCTION_TYPES = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression']);
+const REFUSAL_CLASSES = new Set(['CommandRefusalError', 'VatError']);
+const ERRNO_PREDICATES = new Set(['fsFaultOf', 'isPathAbsentError']);
+
+/**
+ * The string a literal spells: a string `Literal`, or a template literal with no
+ * expressions (a backticked ENOENT is the same literal).
+ *
+ * @returns {string | undefined}
+ */
+function literalText(node) {
+  if (node?.type === 'Literal') {
+    return typeof node.value === 'string' ? node.value : undefined;
+  }
+  if (node?.type === 'TemplateLiteral' && node.expressions.length === 0 && node.quasis.length === 1) {
+    return node.quasis[0].value.cooked ?? undefined;
+  }
+  return undefined;
+}
+
+/** @returns {boolean} True when `node` is a string literal naming an errno. */
+function isErrnoLiteral(node) {
+  const text = literalText(node);
+  return text !== undefined && ERRNO_NAMES.has(text);
+}
+
+/** The declaring variable of an identifier, found by walking out through its scopes. */
+function resolveVariable(sourceCode, node) {
+  for (let scope = sourceCode.getScope(node); scope; scope = scope.upper) {
+    const variable = scope.set.get(node.name);
+    if (variable) {
+      return variable;
+    }
+  }
+  return undefined;
+}
+
+/** True when `node` is an identifier bound once, by `const`, to an errno literal. */
+function isConstErrnoAlias(sourceCode, node) {
+  if (node.type !== 'Identifier') {
+    return false;
+  }
+  const variable = resolveVariable(sourceCode, node);
+  const definition = variable?.defs.length === 1 ? variable.defs[0] : undefined;
+  return (
+    definition?.type === 'Variable' &&
+    definition.parent?.kind === 'const' &&
+    definition.node.id.type === 'Identifier' &&
+    isErrnoLiteral(unwrapExpression(definition.node.init))
+  );
+}
+
+/** Step over `as const`, `satisfies` and `!` wrappers to the expression inside. */
+function unwrapExpression(node) {
+  let current = node;
+  while (
+    current &&
+    (current.type === 'TSAsExpression' ||
+      current.type === 'TSSatisfiesExpression' ||
+      current.type === 'TSNonNullExpression')
+  ) {
+    current = current.expression;
+  }
+  return current;
+}
+
+/** The array literal's enclosing context: the thing that makes it a lookup table. */
+function isLookupArray(arrayNode) {
+  // Climb through `as const` wrappers so `['ENOENT'] as const` is seen as bound.
+  let child = arrayNode;
+  let parent = arrayNode.parent;
+  while (parent && unwrapExpression(parent) !== parent && parent.expression === child) {
+    child = parent;
+    parent = parent.parent;
+  }
+  if (parent?.type === 'MemberExpression') {
+    return (
+      parent.object === child &&
+      !parent.computed &&
+      parent.property.type === 'Identifier' &&
+      ARRAY_LOOKUP_METHODS.has(parent.property.name)
+    );
+  }
+  if (parent?.type === 'NewExpression') {
+    return parent.callee.type === 'Identifier' && parent.callee.name === 'Set' && parent.arguments[0] === child;
+  }
+  return (
+    parent?.type === 'VariableDeclarator' &&
+    parent.init === child &&
+    parent.parent?.type === 'VariableDeclaration' &&
+    parent.parent.kind === 'const'
+  );
+}
+
+/** @returns {boolean} True when the literal sits in one of the four classifying positions. */
+function isClassifyingPosition(node) {
+  const parent = node.parent;
+  switch (parent?.type) {
+    case 'BinaryExpression':
+      return COMPARISON_OPERATORS.has(parent.operator);
+    case 'SwitchCase':
+      return parent.test === node;
+    case 'ArrayExpression':
+      return isLookupArray(parent);
+    case 'CallExpression':
+      return (
+        parent.arguments.includes(node) &&
+        parent.callee.type === 'MemberExpression' &&
+        !parent.callee.computed &&
+        parent.callee.property.type === 'Identifier' &&
+        MEMBERSHIP_METHODS.has(parent.callee.property.name)
+      );
+    default:
+      return false;
+  }
+}
+
+/** Every AST child of `node`, skipping the back-pointer. */
+function childNodes(node) {
+  const children = [];
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'parent') {
+      continue;
+    }
+    for (const item of Array.isArray(value) ? value : [value]) {
+      if (item && typeof item.type === 'string') {
+        children.push(item);
+      }
+    }
+  }
+  return children;
+}
+
+/**
+ * Collect every node under `root` (inclusive) that `predicate` accepts, without
+ * descending into a nested catch or function: those judge their own bodies, so a
+ * re-wrap is reported once, by the catch that owns it.
+ */
+function collectNodes(root, predicate) {
+  const found = [];
+  const pending = [root];
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (predicate(node)) {
+      found.push(node);
+    }
+    if (node.type !== 'CatchClause' && !FUNCTION_TYPES.has(node.type)) {
+      pending.push(...childNodes(node));
+    }
+  }
+  return found;
+}
+
+const isIdentifier = (node, name) => node?.type === 'Identifier' && node.name === name;
+
+/** `e.code`, `fsFaultOf(e)` or `isPathAbsentError(e)` for the catch parameter `name`. */
+function inspectsErrno(node, name) {
+  if (node.type === 'MemberExpression') {
+    return (
+      isIdentifier(node.object, name) &&
+      ((!node.computed && isIdentifier(node.property, 'code')) ||
+        (node.computed && node.property.type === 'Literal' && node.property.value === 'code'))
+    );
+  }
+  return (
+    node.type === 'CallExpression' &&
+    node.callee.type === 'Identifier' &&
+    ERRNO_PREDICATES.has(node.callee.name) &&
+    isIdentifier(node.arguments[0], name)
+  );
+}
+
+/** `new CommandRefusalError(...)` / `new VatError(...)` carrying `cause: <name>`. */
+function wrapsCause(node, name) {
+  return (
+    node.type === 'NewExpression' &&
+    node.callee.type === 'Identifier' &&
+    REFUSAL_CLASSES.has(node.callee.name) &&
+    node.arguments.some(
+      (argument) =>
+        argument.type === 'ObjectExpression' &&
+        argument.properties.some(
+          (property) =>
+            property.type === 'Property' &&
+            !property.computed &&
+            (isIdentifier(property.key, 'cause') || property.key.value === 'cause') &&
+            isIdentifier(property.value, name),
+        ),
+    )
+  );
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ban classifying a filesystem failure by hand: an errno name as a string in a comparison, case, Set/const array or .has()/.includes(), and a catch that inspects the errno then wraps it as a refusal cause',
+      category: 'Filesystem and process',
+      bans: 'an errno name (`ENOENT`, `EACCES`, …) as a string in a classifying position, and a catch that reads `e.code` then builds a refusal with `cause: e`',
+      useInstead: '`fsFaultOf(e)` / `classifyFsFault(e, …)`, or a single-errno predicate such as `isPathAbsentError(e)`',
+      // Not in `recommended`: the remedy names this repo's own classifier
+      // (`fsFaultOf`, `classifyFsFault`) and the refusal classes `CommandRefusalError` /
+      // `VatError`, none of which an adopter has. VAT enables it explicitly, naming
+      // the files that must spell errnos (the table, the git-stderr parser, the
+      // fault-injecting fs).
+      recommended: false,
+      recommendedSeverity: 'error',
+    },
+    fixable: null,
+    schema: [EXEMPT_FILES_SCHEMA],
+    messages: {
+      literal:
+        "Errno name '{{name}}' written as a string classifies a filesystem failure by hand. " +
+        'Ask the one classifier instead: fsFaultOf(e)?.faultClass, classifyFsFault(e, …), or a ' +
+        'single-errno predicate such as isPathAbsentError(e). A private errno table drifts from its neighbours.',
+      adhocRefusal:
+        'This catch inspects the errno ({{param}}.code / fsFaultOf / isPathAbsentError) and then builds a refusal ' +
+        'with cause: {{param}} by hand. Let classifyFsFault({{param}}, …) pick the refusal once.',
+      [UNANCHORED_EXEMPT_FILE]: UNANCHORED_EXEMPT_MESSAGE,
+    },
+  },
+
+  create(context) {
+    const filename = context.getFilename();
+
+    if (createConfigurableExemptPathMatcher([])(context)(filename)) {
+      // Still surface a malformed exemption list: this file may be exempt only
+      // BECAUSE an entry is unanchored.
+      return {
+        Program(node) {
+          reportUnanchoredExemptEntries(context, node);
+        },
+      };
+    }
+
+    if (isTestFile(filename)) {
+      return {};
+    }
+
+    return {
+      Program(node) {
+        reportUnanchoredExemptEntries(context, node);
+      },
+
+      'Literal, TemplateLiteral'(node) {
+        if (isErrnoLiteral(node) && isClassifyingPosition(node)) {
+          context.report({ node, messageId: 'literal', data: { name: literalText(node) } });
+        }
+      },
+
+      // `const C = 'ENOENT'; e.code === C`: flagged at the use, where the check is.
+      Identifier(node) {
+        if (isClassifyingPosition(node) && isConstErrnoAlias(context.sourceCode, node)) {
+          context.report({ node, messageId: 'literal', data: { name: node.name } });
+        }
+      },
+
+      CatchClause(node) {
+        if (node.param?.type !== 'Identifier') {
+          return;
+        }
+        const param = node.param.name;
+        if (collectNodes(node.body, (child) => inspectsErrno(child, param)).length === 0) {
+          return;
+        }
+        for (const wrapped of collectNodes(node.body, (child) => wrapsCause(child, param))) {
+          context.report({ node: wrapped, messageId: 'adhocRefusal', data: { param } });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-bare-symlink-in-tests.cjs

@@ -11,9 +11,8 @@
  *   production code at it would be worse advice than the bare call. Prefer a
  *   junction for a directory link on win32, or catch the failure and name the
  *   missing privilege. An `eslint-disable` justification is the sanctioned way
- *   to say "this platform is deliberately out of scope" — see
- *   `cli/src/commands/agent/install.ts`, where `--dev` is knowingly unavailable
- *   on an unprivileged Windows and fails saying exactly that.
+ *   to say "this is the guarded form" — see `dev-tools/src/link-workspace-packages.ts`,
+ *   which makes a junction on win32 and names the package a failure was for.
  *
  * ⚠️ **The name is now narrower than the rule.** It covers shipped code too;
  * renaming it is a public-API change to `@vibe-agent-toolkit/utils/eslint` and

package/eslint/rules/no-blind-catch.cjs

@@ -23,7 +23,7 @@
  * The rule is a FLOOR, deliberately syntactic: the clause is fine if either
  *
  * 1. the error binding is REFERENCED anywhere in the body — narrowing on it
- *    (`isFilesystemAccessError(e)`, `e instanceof X`, `e.code === 'ENOENT'`),
+ *    (`fsFaultOf(e)`, `e instanceof X`, `e.code === 'ENOENT'`),
  *    carrying it into a report (`errors.push(String(e))`, `{ ok: false, error }`),
  *    or logging it — or
  * 2. the body THROWS (a rethrow, or a translation into a louder error), at the