@vibe-agent-toolkit/utils 0.2.0-rc.7 → 0.2.0-rc.8

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

@@ -0,0 +1,171 @@
+/**
+ * ESLint rule: no-blind-catch
+ *
+ * Flags a `catch` clause that never LOOKS at its error and never THROWS. Such
+ * a clause answers every failure the same way — a sentinel `return null`, a
+ * `continue`, an empty body, a fallback assignment — so the case it was
+ * written for (a file that is not there) becomes indistinguishable from the
+ * cases it was not (a permission refusal, a corrupt artifact, a `TypeError`
+ * from a bug two frames down). The result is a tool that is quietest exactly
+ * when it is most wrong: a directory the OS refused to list reports as empty,
+ * and a build that examined nothing exits 0.
+ *
+ * This is the class behind the worst finding in seven consecutive adversarial
+ * review rounds on one branch. A crawler learned to REFUSE an unreadable
+ * directory instead of skipping it; one caller's `catch { return null }`
+ * absorbed the refusal, and `vat audit` silently ran with no population. The
+ * fix was type-forcing the seam so `tsc` enumerated the callers — but a blind
+ * `catch` is the one seam `tsc` cannot see, because it compiles for every
+ * callee that ever learns to throw.
+ *
+ * ## What counts as handling
+ *
+ * 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'`),
+ *    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
+ *    clause's own level — a `throw` inside a nested function is a promise to
+ *    fail later, not a rethrow from this catch.
+ *
+ * A reference is a reference: the rule cannot tell `narrow(e)` from `log(e)`,
+ * and does not try. What it guarantees is the weaker, enforceable property —
+ * *the error was looked at before being discarded* — which is the property
+ * every one of the shipped defects lacked.
+ *
+ * ## What this rule does NOT catch
+ *
+ * - `catch (e) { void e; return null; }` — a reference written to dodge the
+ *   rule. Code review's job.
+ * - A narrowing that is wrong: `if (e instanceof Error) return null` looks at
+ *   the error and still absorbs everything. The rule sees a reference.
+ * - A catch whose body references the binding only to build a message it
+ *   then throws away.
+ *
+ * There is deliberately NO annotation escape hatch. Every site this rule
+ * flags has a legitimate rewrite — narrow and rethrow, or carry the error into
+ * the result — and an `eslint-disable` with a reason is already the escape
+ * hatch ESLint provides, visible in the diff and countable with
+ * `rg 'eslint-disable.*no-blind-catch'`.
+ *
+ * @example
+ * // BAD — "not there" and "refused" and "bug" all become null
+ * try { return statSync(p); } catch { return null; }
+ *
+ * // GOOD — narrowed to the case the sentinel means, everything else stays loud
+ * try { return statSync(p); } catch (e) {
+ *   if (isPathAbsentError(e)) return null;
+ *   throw e;
+ * }
+ *
+ * // GOOD — the error reaches the report instead of vanishing
+ * try { return parse(text); } catch (e) {
+ *   return { ok: false, reason: String(e) };
+ * }
+ */
+
+'use strict';
+
+/** Function-boundary node types: a `throw` inside one is not this clause's throw. */
+const FUNCTION_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+]);
+
+/** Keys on an ESTree node that point somewhere other than a child. */
+const NON_CHILD_KEYS = new Set(['parent', 'loc', 'range']);
+
+/** Whether `value` is an ESTree node (as opposed to a token, a literal, or null). */
+function isNode(value) {
+  return value !== null && typeof value === 'object' && typeof value.type === 'string';
+}
+
+/** Every child node of `node`, in no particular order. */
+function childNodes(node) {
+  const children = [];
+  for (const key of Object.keys(node)) {
+    if (NON_CHILD_KEYS.has(key)) {
+      continue;
+    }
+    const value = node[key];
+    const values = Array.isArray(value) ? value : [value];
+    children.push(...values.filter((child) => isNode(child)));
+  }
+  return children;
+}
+
+/**
+ * Whether `body` contains a `ThrowStatement` reachable without crossing a
+ * function boundary. Iterative so a deeply nested body cannot blow the stack.
+ */
+function throwsAtOwnLevel(body) {
+  const stack = [body];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (node.type === 'ThrowStatement') {
+      return true;
+    }
+    if (!FUNCTION_TYPES.has(node.type)) {
+      stack.push(...childNodes(node));
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether any binding the clause declares (`catch (e)`, `catch ({ code })`) is
+ * read in the body. A clause with no param declares nothing and reads nothing.
+ */
+function readsErrorBinding(sourceCode, node) {
+  if (node.param === null) {
+    return false;
+  }
+  const declared = sourceCode.getDeclaredVariables(node);
+  return declared.some((variable) => variable.references.length > 0);
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow a catch clause that neither reads its error nor throws — it absorbs a bug, a ' +
+        'permission refusal, or a corrupt artifact into the same answer as the case it was written for',
+      category: 'Error handling',
+      bans: 'a `catch` that neither reads its error nor throws',
+      useInstead: 'narrow on the error and rethrow the rest, or carry it into the result',
+      // `warn`, not `error`: the same migration-volume criterion as
+      // `no-raw-node-path`, without the autofix. A blind `catch` has no
+      // mechanical rewrite — each site is a decision about WHICH failure the
+      // sentinel stands for — and the first run on an existing tree is a long
+      // list (202 sites on this repo's own ~200k lines). `warn` makes that a
+      // backlog to burn down rather than a wall; the hazard is real at every one.
+      recommended: true,
+      recommendedSeverity: 'warn',
+    },
+    schema: [],
+    messages: {
+      blindCatch:
+        'This catch discards the error without looking at it, so a bug, a permission refusal, or a ' +
+        'corrupt artifact is absorbed into the same result as the case it was written for. Narrow it ' +
+        "to that case and rethrow the rest — `if (isPathAbsentError(e)) return null; throw e;` — or " +
+        'carry the error into the result so the report can show it.',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    return {
+      CatchClause(node) {
+        if (readsErrorBinding(sourceCode, node) || throwsAtOwnLevel(node.body)) {
+          return;
+        }
+        context.report({ node, messageId: 'blindCatch' });
+      },
+    };
+  },
+};

package/eslint/rules/no-child-process-execSync.cjs

@@ -20,4 +20,12 @@ module.exports = factory({
   message: 'Use safeExecSync() from {{safeModule}} instead of child_process.execSync() to prevent command injection (security + cross-platform)',
   // No baked-in exemption: the file that implements safeExecSync() is
   // repo-specific. Consumers declare it as { exemptFiles: [...] }.
+  docs: {
+    category: 'Filesystem and process',
+    bans: '`child_process.execSync()`',
+    useInstead: '`safeExecSync()`',
+    subpath: '/process',
+    recommended: true,
+    recommendedSeverity: 'error',
+  },
 });

package/eslint/rules/no-decaying-referent.cjs

@@ -0,0 +1,216 @@
+/**
+ * ESLint rule: no-decaying-referent
+ *
+ * Flags, in comments under `src/`, three kinds of referent that rot in place:
+ *
+ * - an issue or PR number (`#145`) — the issue closes, the PR merges, and the
+ *   comment keeps pointing at a discussion nobody reopens;
+ * - an ISO date (`2026-08-22`, `2026-08`) — "re-derived on" is a claim about
+ *   freshness that is false the day after it is written;
+ * - a named person (`Jeff`, configurable) — a ruling attributed to someone is a
+ *   ruling nobody else feels entitled to revisit.
+ *
+ * None of these is the RULE the comment exists to state. The rule stays; the
+ * history goes where history is kept — the commit message, the CHANGELOG, or
+ * `docs/contributing/` — and `git log -L` holds the rest without decaying.
+ *
+ * Scope: files with a `/src/` segment that are not test files. Tests and
+ * scripts are not linted here; Markdown never reaches ESLint. One report per
+ * comment block, on the FIRST referent found, whichever kind it is — the fix is
+ * to rewrite the comment, not to hunt tokens one at a time.
+ *
+ * Options:
+ * - `names: string[]` — whole-word, case-sensitive names to treat as referents
+ *   (default `['Jeff']`). Pass `[]` to disable the class.
+ * - `allowDates: boolean` — leave dates alone (default `false`).
+ *
+ * One line shape is exempt without an option: `@vendor-claim reviewed=<date>
+ * verify=<how>`. That date is READ by a freshness gate that fails the build when
+ * it ages past its budget — a date with a mechanism behind it is the opposite of
+ * a decaying one. The exemption covers only the line carrying the tag.
+ *
+ * @example
+ * // BAD — the reader must open #145 to learn what the code does
+ * // Fixed in #145 (Jeff, 2026-08-22): skip the second crawl.
+ *
+ * // GOOD — the rule, stated; the history is in `git log -L`
+ * // The second crawl is skipped: the first already answered from git.
+ */
+
+'use strict';
+
+const { isTestFile } = require('./exempt-path-matcher.cjs');
+
+/** `#12` … `#1234`, not preceded by a word/URL/entity character and not part of a longer number. */
+const ISSUE_REF = /(?<![\w/&#])#\d{2,4}(?!\d)/u;
+
+/**
+ * `20YY-MM` or `20YY-MM-DD`, standing alone. Glued to a word, a hyphen or a
+ * path separator it names a thing (`sweep-2026-09-12/`, a JSON Schema dialect's
+ * `draft/2020-12/schema`), not a day something was true.
+ */
+const ISO_DATE = /(?<![\w/-])20\d\d-\d\d(?:-\d\d)?(?![\w-])/u;
+
+/** A character that continues a word, for the whole-word check on names. */
+const WORD_CHAR = /\w/u;
+
+/** The one annotation whose date is machine-checked rather than left to rot. */
+const VENDOR_CLAIM_TAG = '@vendor-claim';
+
+/**
+ * `text` with every line carrying {@link VENDOR_CLAIM_TAG} blanked to spaces
+ * of the same length, so match indices still map onto the original comment.
+ */
+function blankVendorClaimLines(text) {
+  if (!text.includes(VENDOR_CLAIM_TAG)) {
+    return text;
+  }
+  return text
+    .split('\n')
+    .map((line) => (line.includes(VENDOR_CLAIM_TAG) ? ' '.repeat(line.length) : line))
+    .join('\n');
+}
+
+/**
+ * The first whole-word, case-sensitive occurrence of any of `names` in `text`,
+ * as a `{ index, match }` pair, or null. A hand search rather than a built
+ * RegExp so a configured name needs no escaping and the rule stays free of a
+ * non-literal RegExp constructor.
+ */
+function findWholeWordName(text, names) {
+  let best = null;
+  for (const name of names) {
+    let from = 0;
+    for (;;) {
+      const index = text.indexOf(name, from);
+      if (index === -1 || (best !== null && index >= best.index)) {
+        break;
+      }
+      const boundedBefore = index === 0 || !WORD_CHAR.test(text[index - 1]);
+      const boundedAfter = !WORD_CHAR.test(text[index + name.length] ?? '');
+      if (boundedBefore && boundedAfter) {
+        best = { index, match: name };
+        break;
+      }
+      from = index + 1;
+    }
+  }
+  return best;
+}
+
+/** Whether a linted filename is a non-test file under a `src/` directory. */
+function isSourceFile(filename) {
+  if (!filename) {
+    return false;
+  }
+  const normalized = String(filename).replaceAll('\\', '/');
+  return normalized.includes('/src/') && !isTestFile(normalized);
+}
+
+/**
+ * The earliest referent in `text` across the enabled classes, or null.
+ * Each class contributes at most its first match; the earliest of those wins.
+ */
+function firstReferent(text, matchers) {
+  let best = null;
+  for (const { kind, find } of matchers) {
+    const found = find(text);
+    if (found !== null && (best === null || found.index < best.index)) {
+      best = { kind, referent: found.match, index: found.index };
+    }
+  }
+  return best;
+}
+
+/** A matcher backed by a RegExp literal. */
+function regexMatcher(kind, pattern) {
+  return {
+    kind,
+    find(text) {
+      const match = pattern.exec(text);
+      return match === null ? null : { index: match.index, match: match[0] };
+    },
+  };
+}
+
+/**
+ * The source location of `index` within a comment's value, accounting for the
+ * two-character opener (`//`, `/*`, `#!`) and any newlines before the match.
+ */
+function locationInComment(comment, index) {
+  const before = comment.value.slice(0, index);
+  const lastNewline = before.lastIndexOf('\n');
+  const newlines = before.match(/\n/gu)?.length ?? 0;
+  const line = comment.loc.start.line + newlines;
+  const column = lastNewline === -1 ? comment.loc.start.column + 2 + index : index - lastNewline - 1;
+  return { line, column };
+}
+
+/** Build the enabled matcher table from the rule options. */
+function buildMatchers(options) {
+  const matchers = [regexMatcher('an issue or PR number', ISSUE_REF)];
+  if (options.allowDates !== true) {
+    matchers.push(regexMatcher('a date', ISO_DATE));
+  }
+  const names = (options.names ?? ['Jeff']).filter((name) => name.length > 0);
+  if (names.length > 0) {
+    matchers.push({ kind: 'a person', find: (text) => findWholeWordName(text, names) });
+  }
+  return matchers;
+}
+
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Disallow issue/PR numbers, ISO dates and named people in src comments — they decay in ' +
+        'place; the rule belongs in the comment and the history in the commit, CHANGELOG or docs',
+      recommended: false,
+      recommendedSeverity: 'warn',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          names: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+          allowDates: { type: 'boolean' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      decayingReferent:
+        'This comment cites {{kind}} ({{referent}}), which decays in place: nobody rewrites the ' +
+        'comment when the issue closes, the date passes, or the person moves on. Keep the rule the ' +
+        'comment states and move the history to the commit message, the CHANGELOG, or ' +
+        'docs/contributing/ — `git log -L` keeps the rest.',
+    },
+  },
+
+  create(context) {
+    const filename = context.filename ?? context.getFilename();
+    if (!isSourceFile(filename)) {
+      return {};
+    }
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const matchers = buildMatchers(context.options?.[0] ?? {});
+
+    return {
+      Program() {
+        for (const comment of sourceCode.getAllComments()) {
+          const found = firstReferent(blankVendorClaimLines(comment.value), matchers);
+          if (found === null) {
+            continue;
+          }
+          const start = locationInComment(comment, found.index);
+          context.report({
+            loc: { start, end: { line: start.line, column: start.column + found.referent.length } },
+            messageId: 'decayingReferent',
+            data: { kind: found.kind, referent: found.referent },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-dotdot-containment.cjs

@@ -0,0 +1,160 @@
+/**
+ * ESLint rule: no-dotdot-containment
+ *
+ * Flags a `..` string test used as a containment check on a path:
+ * `rel.startsWith('..')`, `rel.startsWith('../')`, `name.includes('..')`, and
+ * `p.split(sep).includes('..')` / `.some(s => …)` / `.indexOf('..')`.
+ *
+ * A string test answers "does this text contain two dots", which is not the
+ * question. The question is "does this resolve INSIDE the root", and the two
+ * come apart in every direction that matters:
+ *
+ * - a symlink inside the root that points outside has no `..` in its name;
+ * - `startsWith('..')` also refuses a sibling whose name merely BEGINS with
+ *   two dots (`..cache`), and `includes('..')` refuses `a..b`;
+ * - on Windows a drive letter or a UNC prefix escapes without a single dot;
+ * - the relative path was computed lexically, so a root that is itself a
+ *   symlink gives a different answer from the one the filesystem gives.
+ *
+ * The sweep behind this rule verified sinks — a delete, a copy, an uninstall —
+ * guarded by exactly these tests. The answer is one helper that asks the
+ * filesystem: `isUnderRoot(root, candidate)` from `@vibe-agent-toolkit/utils`,
+ * realpath-based, and honest about a candidate that does not exist yet.
+ *
+ * ## Scope
+ *
+ * The receiver must look like a path: an identifier or member whose name
+ * carries a path word (`path`, `dir`, `rel`, `root`, `file`, `name`, `id`,
+ * `target`, `dest`, `src`, `location`, `folder`), or any call result (a
+ * `relative(root, p)` is a path by construction). A segment normaliser's
+ * `segment === '..'` compares one segment and is not a containment test; it
+ * is left alone, as is `startsWith('./')` and any literal without a `..`
+ * segment.
+ *
+ * @example
+ * // BAD — misses a symlink, refuses `..cache`, blind to a drive letter
+ * if (safePath.relative(root, p).startsWith('..')) refuse();
+ *
+ * // GOOD — the filesystem answers
+ * if (!isUnderRoot(root, p)) refuse();
+ */
+
+'use strict';
+
+/** Words that mark a receiver as path-shaped. */
+const PATH_WORD = /path|dir|rel|root|file|name|id|target|dest|src|location|folder/u;
+
+/** A `..` segment at the start of a prefix literal: `..`, `../`, `..\`. */
+const DOTDOT_PREFIX = /^\.\.(?:$|[\\/])/u;
+
+/** A `..` segment anywhere in a substring literal: `..`, `/../`, `a/..`. */
+const DOTDOT_SEGMENT = /(?:^|[\\/])\.\.(?:$|[\\/])/u;
+
+/** Methods that, after a `.split(...)`, hunt for a segment. */
+const MEMBERSHIP_METHODS = new Set(['includes', 'some', 'every', 'indexOf', 'find', 'filter']);
+
+/** The non-computed method name of a call, or null. */
+function methodName(call) {
+  const { callee } = call;
+  if (callee.type !== 'MemberExpression' || callee.computed || callee.property.type !== 'Identifier') {
+    return null;
+  }
+  return callee.property.name;
+}
+
+/** The identifier name a receiver is known by, or null when it has none. */
+function receiverName(receiver) {
+  if (receiver.type === 'Identifier') {
+    return receiver.name;
+  }
+  if (receiver.type === 'MemberExpression' && !receiver.computed && receiver.property.type === 'Identifier') {
+    return receiver.property.name;
+  }
+  return null;
+}
+
+/** Whether the receiver is named like a path. */
+function isPathNamed(receiver) {
+  const name = receiverName(receiver);
+  return name !== null && PATH_WORD.test(name.toLowerCase());
+}
+
+/** The string value of the first argument when it is a literal, or null. */
+function firstStringArg(call) {
+  const arg = call.arguments[0];
+  return arg?.type === 'Literal' && typeof arg.value === 'string' ? arg.value : null;
+}
+
+/** `<path>.startsWith('..')` / `<path>.includes('..')` — a `..` test on a path or a call result. */
+function isDotdotStringTest(call, method) {
+  const literal = firstStringArg(call);
+  if (literal === null) {
+    return false;
+  }
+  const receiver = call.callee.object;
+  const pathLike = receiver.type === 'CallExpression' || isPathNamed(receiver);
+  if (!pathLike) {
+    return false;
+  }
+  if (method === 'startsWith') {
+    return DOTDOT_PREFIX.test(literal);
+  }
+  return method === 'includes' && DOTDOT_SEGMENT.test(literal);
+}
+
+/** A `'..'` literal (as an argument, or anywhere inside a callback). */
+const DOTDOT_LITERAL = /['"`]\.\.['"`]/u;
+
+/**
+ * `<path>.split(...).<membership>(...)` — hunting for a `..` segment. The
+ * membership call must actually mention `'..'` (as its argument, or inside
+ * its callback): `parts.split('/').filter(Boolean)` is splitting, not hunting.
+ */
+function isSplitSegmentHunt(call, method, sourceCode) {
+  if (!MEMBERSHIP_METHODS.has(method) || call.arguments.length === 0) {
+    return false;
+  }
+  const receiver = call.callee.object;
+  return (
+    receiver.type === 'CallExpression' &&
+    methodName(receiver) === 'split' &&
+    isPathNamed(receiver.callee.object) &&
+    DOTDOT_LITERAL.test(sourceCode.getText(call.arguments[0]))
+  );
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        "Disallow startsWith('..') / includes('..') / split-and-hunt as a path containment check — " +
+        'use the realpath-based isUnderRoot() helper',
+      recommended: false,
+      recommendedSeverity: 'warn',
+    },
+    schema: [],
+    messages: {
+      dotdotContainment:
+        'A `..` string test is not a containment check: it misses a symlink that points outside, ' +
+        'refuses a name that merely starts with two dots, and is blind to a Windows drive letter ' +
+        'or UNC prefix. Ask the filesystem: isUnderRoot(root, candidate) from ' +
+        '@vibe-agent-toolkit/utils.',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    return {
+      CallExpression(node) {
+        const method = methodName(node);
+        if (method === null) {
+          return;
+        }
+        if (isDotdotStringTest(node, method) || isSplitSegmentHunt(node, method, sourceCode)) {
+          context.report({ node, messageId: 'dotdotContainment' });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-file-url-string-concat.cjs

@@ -45,8 +45,11 @@ module.exports = {
     docs: {
       description:
         'Disallow constructing `file://` URLs by string concatenation; use `pathToFileURL()` from `node:url`.',
-      category: 'Cross-platform compatibility',
+      category: 'URLs and dynamic imports',
+      bans: '`` `file://${p}` ``',
+      useInstead: '`pathToFileURL(p).href`',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     messages: {
       useFileUrlBuilder:

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

@@ -178,8 +178,21 @@ module.exports = {
     docs: {
       description:
         'Ban entrypoint guards that silently answer false — `import.meta.main` (undefined before Node 24.2/22.18) and any raw compare of where the module lives to `process.argv[1]`, in URL space or path space (false through any symlink). Use `isEntrypoint()`.',
-      category: 'Cross-Platform',
+      category: 'Entrypoint guards',
+      bans: '`import.meta.main`; `import.meta.url === pathToFileURL(process.argv[1]).href`; `fileURLToPath(import.meta.url) === process.argv[1]`',
+      useInstead: '`isEntrypoint(import.meta.url)`',
+      subpath: '/process',
+      // Not in `recommended`: ONE of its two halves is a claim about the CONSUMER's
+      // 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
+      // 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
+      // — but the two share one rule id. VAT enables the whole rule explicitly.
       recommended: false,
+      recommendedSeverity: 'error',
     },
     messages: {
       importMetaMain:

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

@@ -20,4 +20,12 @@ module.exports = factory({
   message: 'Use mkdirSyncReal() from {{safeModule}} instead of fs.mkdirSync() for Windows path normalization',
   // No baked-in exemption: the file that implements mkdirSyncReal() is
   // repo-specific. Consumers declare it as { exemptFiles: [...] }.
+  docs: {
+    category: 'Filesystem and process',
+    bans: '`fs.mkdirSync()`',
+    useInstead: '`mkdirSyncReal()`',
+    subpath: '/fs',
+    recommended: true,
+    recommendedSeverity: 'error',
+  },
 });

package/eslint/rules/no-fs-promises-cp.cjs

@@ -33,4 +33,11 @@ module.exports = factory({
     'Use cpSync() from {{safeModule}} instead of cp() from node:fs/promises. ' +
     'Node 22 async cp({ recursive: true }) silently drops files in nested directories. ' +
     'cpSync() works correctly across all Node versions.',
+  docs: {
+    category: 'Filesystem and process',
+    bans: '`cp()` from `node:fs/promises` (drops nested files on Node 22)',
+    useInstead: '`cpSync()` from `node:fs`',
+    recommended: true,
+    recommendedSeverity: 'error',
+  },
 });

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

@@ -20,4 +20,12 @@ module.exports = factory({
   message: 'Use normalizePath() from {{safeModule}} instead of fs.realpathSync() for consistent Windows 8.3 path resolution',
   // No baked-in exemption: the file that implements normalizePath() is
   // repo-specific. Consumers declare it as { exemptFiles: [...] }.
+  docs: {
+    category: 'Filesystem and process',
+    bans: '`fs.realpathSync()`',
+    useInstead: '`normalizePath()`',
+    subpath: '/fs',
+    recommended: true,
+    recommendedSeverity: 'error',
+  },
 });

package/eslint/rules/no-hardcoded-path-split.cjs

@@ -36,9 +36,14 @@ module.exports = {
   meta: {
     type: 'problem',
     docs: {
-      description: 'Disallow splitting strings by hardcoded path separators',
-      category: 'Cross-platform compatibility',
+      description:
+        'Disallow splitting strings by hardcoded path separators',
+      category: 'Path handling',
+      bans: "`split('/')` / `split('\\\\')` on a path",
+      useInstead: '`path.basename()`, or `toForwardSlash()` first',
+      subpath: '/path',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     messages: {
       noHardcodedSplit: