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

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

@@ -0,0 +1,230 @@
+/**
+ * ESLint rule: no-literal-process-exit
+ *
+ * Flags `process.exit(<number>)` and `process.exitCode = <number>`. A numeric
+ * exit code written at the call site re-decides the exit contract inline: one
+ * command exits 1 for "findings" and another exits 1 for "the config was
+ * unreadable", and nothing but a reader comparing two files can tell. The
+ * allowed shape names the meaning — `process.exit(ExitCode.FINDINGS)` — so the
+ * contract lives in one enum and every command shares it.
+ *
+ * The literal may hide inside an expression: `ok ? 0 : 1`, `status ?? 1`,
+ * `-1`. Those are flagged too, because each branch is still a number chosen at
+ * this site. Any non-literal argument — an identifier, a member, a call
+ * result — is accepted; the rule is a syntactic floor and does not chase what
+ * a variable holds.
+ *
+ * Option `allow: string[]` — repo-relative paths of the files permitted to
+ * exit with a literal (the one `bin.ts` last-resort fallback that runs when
+ * the enum module itself failed to load). Entries are matched at a path
+ * 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.
+ * - `derived.legacy` names the files not yet migrated. It is a RATCHET asserted
+ *   both ways: a listed file that no longer decides a code by hand is itself an
+ *   error (`staleLegacy`), so the list can only shrink and never holds a dead entry.
+ *
+ * ⚠️ 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);
+ *
+ * // 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 { 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) {
+  return (
+    node.type === 'MemberExpression' &&
+    !node.computed &&
+    node.object.type === 'Identifier' &&
+    node.object.name === 'process' &&
+    node.property.type === 'Identifier' &&
+    node.property.name === name
+  );
+}
+
+/**
+ * The first numeric literal reachable through the expression's value
+ * branches, or null. Walks conditionals, nullish/logical fallbacks, unary
+ * minus, and TypeScript wrappers — every path a number can take to become the
+ * exit code without passing through a name.
+ */
+function numericLiteralLeaf(expr) {
+  switch (expr.type) {
+    case 'Literal':
+      return typeof expr.value === 'number' ? expr : null;
+    case 'UnaryExpression':
+      return numericLiteralLeaf(expr.argument);
+    case 'ConditionalExpression':
+      return numericLiteralLeaf(expr.consequent) ?? numericLiteralLeaf(expr.alternate);
+    case 'LogicalExpression':
+      return numericLiteralLeaf(expr.left) ?? numericLiteralLeaf(expr.right);
+    case 'TSAsExpression':
+    case 'TSNonNullExpression':
+    case 'TSSatisfiesExpression':
+      return numericLiteralLeaf(expr.expression);
+    default:
+      return null;
+  }
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow process.exit(<number>) and process.exitCode = <number> — name the meaning with ' +
+        'the ExitCode enum so every command shares one exit contract',
+      recommended: false,
+      recommendedSeverity: 'warn',
+    },
+    schema: [
+      {
+        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 },
+              legacy: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+            },
+            required: ['paths', 'calls', 'legacy'],
+            additionalProperties: false,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      literalExit:
+        'process.exit({{literal}}) re-decides the exit contract at this call site. Use the ' +
+        'ExitCode enum from @vibe-agent-toolkit/schema — process.exit(ExitCode.X) — so the code ' +
+        'means the same thing in every command.',
+      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}}.',
+      staleLegacy:
+        'This file is listed in no-literal-process-exit derived.legacy but decides no exit code by ' +
+        'hand any more. Remove it from the list — the ratchet only shrinks.',
+    },
+  },
+
+  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 isLegacy = inDerived && createExemptPathMatcher(derived.legacy)(filename);
+    const derivations = new Set(derived?.calls ?? []);
+    let handDecided = 0;
+
+    /** Report a derivation violation — or, in a legacy file, only count it. */
+    function reportDerived(node, messageId) {
+      handDecided += 1;
+      if (isLegacy) return;
+      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) 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) {
+          checkExitValue(node, node.arguments[0], 'literalExit');
+        }
+      },
+      AssignmentExpression(node) {
+        if (isProcessMember(node.left, 'exitCode')) {
+          checkExitValue(node, node.right, 'literalExitCode');
+        }
+      },
+      MemberExpression(node) {
+        if (inDerived && isExitCodeMember(node, 'FINDINGS')) reportDerived(node, 'findingsNotDerived');
+      },
+      'Program:exit'(node) {
+        if (isLegacy && handDecided === 0) context.report({ node, messageId: 'staleLegacy' });
+      },
+    };
+  },
+};

package/eslint/rules/no-manual-path-normalize.cjs

@@ -1,16 +1,32 @@
 /**
- * ESLint rule to enforce using toForwardSlash() instead of manual normalization
+ * ESLint rule to enforce the forward-slash converters instead of hand-rolled
+ * normalization.
  *
- * Detects manual path normalization patterns and suggests using the utility function.
+ * Two converters, because a backslash means two different things:
+ *
+ * - `toForwardSlash(p)` — a NATIVE path (from `fs`, `path.*`, git). Converts
+ *   only where the host's separator is a backslash; on POSIX a backslash is a
+ *   filename character and is kept. `split(path.sep).join('/')` is exactly
+ *   this, so it autofixes here.
+ * - `toForwardSlashAnyPlatform(text)` — AUTHOR-WRITTEN text (an href, a glob, a
+ *   config value, an archive entry name). Converts every backslash on every
+ *   host. A literal-backslash `split('\\').join('/')`, `replaceAll('\\', '/')`
+ *   or `replace(/\\/g, '/')` is exactly this, so each autofixes here — never to
+ *   `toForwardSlash`, which would silently stop converting on POSIX.
+ *
+ * Whether a given literal-backslash site is really author text is the author's
+ * call; the fix preserves behaviour, and a native-path site should then be
+ * switched to `toForwardSlash` by hand.
  *
  * @example
  * // ❌ BAD - manual normalization
- * const normalized = relativePath.split(path.sep).join('/');
- * const normalized = somePath.split('\\').join('/');
+ * const a = relativePath.split(path.sep).join('/');
+ * const b = href.replaceAll('\\', '/');
  *
- * // ✅ GOOD - use utility function
- * import { toForwardSlash } from '@vibe-agent-toolkit/utils/path';
- * const normalized = toForwardSlash(relativePath);
+ * // ✅ GOOD - use the utility functions
+ * import { toForwardSlash, toForwardSlashAnyPlatform } from '@vibe-agent-toolkit/utils/path';
+ * const a = toForwardSlash(relativePath);
+ * const b = toForwardSlashAnyPlatform(href);
  */
 
 const {
@@ -26,22 +42,85 @@ const {
   resolveSafeModule,
 } = require('./safe-import.cjs');
 
-const SAFE_FN = 'toForwardSlash';
+const NATIVE_FN = 'toForwardSlash';
+const ANY_PLATFORM_FN = 'toForwardSlashAnyPlatform';
+const MESSAGE_FOR = { [NATIVE_FN]: 'useToForwardSlash', [ANY_PLATFORM_FN]: 'useToForwardSlashAnyPlatform' };
 const PATH_MODULES = new Set(['node:path', 'path']);
+const BACKSLASH = '\\';
+
+/** `.name(...)` on some receiver, with exactly `arity` arguments? */
+function isMethodCall(node, name, arity) {
+  return (
+    node?.type === 'CallExpression' &&
+    node.callee.type === 'MemberExpression' &&
+    node.callee.property.name === name &&
+    node.arguments.length === arity
+  );
+}
+
+function isStringLiteral(node, value) {
+  return node.type === 'Literal' && node.value === value;
+}
+
+/** `/\\/g` — one literal backslash, global. */
+function isGlobalBackslashRegex(node) {
+  return node.type === 'Literal' && node.regex?.pattern === String.raw`\\` && node.regex.flags.includes('g');
+}
+
+function isPathSep(node) {
+  return node.type === 'MemberExpression' && node.object.name === 'path' && node.property.name === 'sep';
+}
+
+/**
+ * `<x>.split(<sep>).join('/')` → the converter it is equivalent to.
+ *
+ * Splitting on a TWO-backslash SEQUENCE (e.g. collapsing a UNC server prefix)
+ * is a different operation that neither converter matches, so it is not
+ * reported.
+ */
+function matchSplitJoin(node) {
+  if (!isMethodCall(node, 'join', 1) || !isStringLiteral(node.arguments[0], '/')) return undefined;
+  const split = node.callee.object;
+  if (!isMethodCall(split, 'split', 1)) return undefined;
+  const [separator] = split.arguments;
+  if (isPathSep(separator)) return { receiver: split.callee.object, fn: NATIVE_FN };
+  if (isStringLiteral(separator, BACKSLASH)) return { receiver: split.callee.object, fn: ANY_PLATFORM_FN };
+  return undefined;
+}
+
+/** `<x>.replaceAll('\\', '/')` or `<x>.replace(/\\/g, '/')` → the any-platform converter. */
+function matchReplace(node) {
+  const isReplace = isMethodCall(node, 'replace', 2) || isMethodCall(node, 'replaceAll', 2);
+  if (!isReplace || !isStringLiteral(node.arguments[1], '/')) return undefined;
+  const [pattern] = node.arguments;
+  const allBackslashes =
+    isGlobalBackslashRegex(pattern) ||
+    (node.callee.property.name === 'replaceAll' && isStringLiteral(pattern, BACKSLASH));
+  return allBackslashes ? { receiver: node.callee.object, fn: ANY_PLATFORM_FN } : undefined;
+}
 
 module.exports = {
   meta: {
     type: 'problem',
     docs: {
-      description: 'Disallow manual path normalization patterns',
-      category: 'Cross-platform compatibility',
+      description:
+        'Disallow manual path normalization patterns',
+      category: 'Path handling',
+      bans: "hand-rolled `.replace(/\\\\/g, '/')` / `split(path.sep).join('/')`",
+      useInstead: '`toForwardSlash()` (native paths) / `toForwardSlashAnyPlatform()` (authored text)',
+      subpath: '/path',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     fixable: 'code',
     messages: {
       useToForwardSlash:
         'Use toForwardSlash() from {{safeModule}} instead of manual path normalization. ' +
-        'Manual normalization is error-prone and less maintainable.',
+        'It converts a native path only where the host separator is a backslash.',
+      useToForwardSlashAnyPlatform:
+        'Use toForwardSlashAnyPlatform() from {{safeModule}} instead of a hand-rolled backslash replace. ' +
+        'If this string is a native filesystem/git path rather than authored text, use toForwardSlash() — ' +
+        'on POSIX a backslash is a filename character.',
       [DEAD_UNSAFE_IMPORT]: DEAD_UNSAFE_IMPORT_MESSAGE,
     },
     schema: [SAFE_MODULE_ONLY_SCHEMA],
@@ -50,24 +129,43 @@ module.exports = {
   create(context) {
     const sourceCode = context.getSourceCode();
     const targetModule = resolveSafeModule(context, SAFE_PATH_MODULE);
-    // Seeded from SCOPE: a file that already imports `toForwardSlash` from the
-    // barrel must have the call rewritten WITHOUT gaining a second binding of
-    // the same name — that is a SyntaxError. See `safe-import.cjs`.
-    let hasToForwardSlashImport = isNameAlreadyBound(sourceCode, SAFE_FN);
+    // Seeded from SCOPE: a file that already binds the name must have the call
+    // rewritten WITHOUT gaining a second binding of the same name — that is a
+    // SyntaxError. See `safe-import.cjs`.
+    const bound = {
+      [NATIVE_FN]: isNameAlreadyBound(sourceCode, NATIVE_FN),
+      [ANY_PLATFORM_FN]: isNameAlreadyBound(sourceCode, ANY_PLATFORM_FN),
+    };
     // Never mutated — the dead-import leg must not be armed by a flag that a
     // suppressed report's `fix()` can spend. See `dead-import.cjs`.
-    const safeBoundInSource = hasToForwardSlashImport;
+    const safeBoundInSource = bound[NATIVE_FN];
     // The dead-import leg's OTHER gate: a `toForwardSlash(…)` call is the text
-    // this fixer writes, and the only evidence available that it wrote it here.
-    // Without it, any file with `toForwardSlash` in scope armed the leg — see
-    // `dead-import.cjs`. Read from the source, never from a `fix()`.
+    // this fixer writes for `path.sep`, and the only evidence available that it
+    // wrote it here. Read from the source, never from a `fix()`.
     let safeReplacementCalled = false;
     let utilsImportNode = null;
     // `path.sep` is the last `path.*` reference in plenty of files, and
-    // `toForwardSlash(raw)` consumes it — leaving the same dead `node:path`
-    // binding the `safePath` rules used to leave.
+    // `toForwardSlash(raw)` consumes it — leaving a dead `node:path` binding.
     const pathImportNodes = [];
 
+    /**
+     * Add `fn` to the import, when nothing binds it yet.
+     *
+     * NOT latched: two reports insert identical text at the identical anchor, so
+     * ESLint applies one and drops the other as overlapping. Latching is not
+     * free — ESLint runs `fix()` for a SUPPRESSED problem before the
+     * `eslint-disable` filter discards it, so a latch could be spent by a report
+     * that is then thrown away.
+     */
+    function importFix(fixer, fn) {
+      if (bound[fn]) return [];
+      if (utilsImportNode) {
+        return [fixer.insertTextAfter(utilsImportNode.specifiers.at(-1), `, ${fn}`)];
+      }
+      const newImport = `import { ${fn} } from '${targetModule}';\n`;
+      return [insertAboveWithComments(fixer, sourceCode, sourceCode.ast.body[0], newImport)];
+    }
+
     return {
       'Program:exit'() {
         reportDeadUnsafeImports(
@@ -83,99 +181,30 @@ module.exports = {
         if (PATH_MODULES.has(node.source.value)) {
           pathImportNodes.push(node);
         }
-        if (node.source.value === targetModule) {
-          utilsImportNode = node;
-          for (const spec of node.specifiers) {
-            if (spec.type === 'ImportSpecifier' && spec.imported.name === SAFE_FN) {
-              hasToForwardSlashImport = true;
-            }
+        if (node.source.value !== targetModule) return;
+        utilsImportNode = node;
+        for (const spec of node.specifiers) {
+          if (spec.type === 'ImportSpecifier' && spec.imported.name in bound) {
+            bound[spec.imported.name] = true;
           }
         }
       },
 
       CallExpression(node) {
-        if (node.callee.type === 'Identifier' && node.callee.name === SAFE_FN) {
+        if (node.callee.type === 'Identifier' && node.callee.name === NATIVE_FN) {
           safeReplacementCalled = true;
         }
-
-        // Check for .split(...).join('/') pattern
-        if (
-          node.callee.type === 'MemberExpression' &&
-          node.callee.property.name === 'join' &&
-          node.arguments.length === 1 &&
-          node.arguments[0].type === 'Literal' &&
-          node.arguments[0].value === '/'
-        ) {
-          // Check if the object is a .split() call
-          const splitCall = node.callee.object;
-          if (
-            splitCall.type === 'CallExpression' &&
-            splitCall.callee.type === 'MemberExpression' &&
-            splitCall.callee.property.name === 'split' &&
-            splitCall.arguments.length === 1
-          ) {
-            const splitArg = splitCall.arguments[0];
-
-            // Split on path.sep, or on a single backslash character
-            // (source literal '\\'). Splitting on a two-backslash SEQUENCE
-            // (source literal '\\\\', decoded value: two backslash characters)
-            // is a different, rarer operation -- e.g. collapsing a UNC path's
-            // leading double-backslash server prefix -- and toForwardSlash()
-            // is not equivalent to it. Autofixing that case would silently
-            // change program behavior, so it is deliberately excluded here.
-            const isSplittingByPathSep =
-              (splitArg.type === 'MemberExpression' &&
-                splitArg.object.name === 'path' &&
-                splitArg.property.name === 'sep') ||
-              (splitArg.type === 'Literal' && splitArg.value === '\\');
-
-            if (isSplittingByPathSep) {
-              const variableBeingSplit = splitCall.callee.object;
-
-              context.report({
-                node,
-                messageId: 'useToForwardSlash',
-                data: { safeModule: targetModule },
-                fix(fixer) {
-                  const fixes = [];
-
-                  // Replace the entire .split(...).join('/') with toForwardSlash(...)
-                  const originalVar = sourceCode.getText(variableBeingSplit);
-                  fixes.push(fixer.replaceText(node, `${SAFE_FN}(${originalVar})`));
-
-                  // Add import if needed
-                  if (!hasToForwardSlashImport) {
-                    if (utilsImportNode) {
-                      // Add to existing utils import
-                      const lastSpecifier = utilsImportNode.specifiers.at(-1);
-                      fixes.push(fixer.insertTextAfter(lastSpecifier, `, ${SAFE_FN}`));
-                    } else {
-                      // Create new import at the top
-                      const firstNode = sourceCode.ast.body[0];
-                      const newImport = `import { ${SAFE_FN} } from '${targetModule}';\n`;
-                      fixes.push(insertAboveWithComments(fixer, sourceCode, firstNode, newImport));
-                    }
-                    // NOT latched. The comment here used to claim that without a
-                    // `hasToForwardSlashImport = true` a second occurrence would
-                    // insert the import twice; an adversarial run could not
-                    // reproduce that at any occurrence count. It cannot happen:
-                    // both reports insert identical text at the identical anchor,
-                    // so the ranges coincide and ESLint applies one and drops the
-                    // other as overlapping.
-                    //
-                    // Latching it is not free, either. ESLint runs `fix()` for a
-                    // SUPPRESSED problem before the `eslint-disable` filter
-                    // discards it, so the first report could spend the flag and
-                    // then be thrown away — leaving later occurrences rewritten
-                    // to a `toForwardSlash` nothing imports.
-                  }
-
-                  return fixes;
-                },
-              });
-            }
-          }
-        }
+        const match = matchSplitJoin(node) ?? matchReplace(node);
+        if (!match) return;
+        context.report({
+          node,
+          messageId: MESSAGE_FOR[match.fn],
+          data: { safeModule: targetModule },
+          fix(fixer) {
+            const receiver = sourceCode.getText(match.receiver);
+            return [fixer.replaceText(node, `${match.fn}(${receiver})`), ...importFix(fixer, match.fn)];
+          },
+        });
       },
     };
   },

package/eslint/rules/no-os-tmpdir.cjs

@@ -21,4 +21,12 @@ module.exports = factory({
   // No baked-in exemption: the file that implements normalizedTmpdir() is
   // repo-specific. Consumers declare it as { exemptFiles: [...] }.
   checkMemberExpression: true, // Catch os.tmpdir() pattern
+  docs: {
+    category: 'Filesystem and process',
+    bans: '`os.tmpdir()` (8.3 short names on Windows)',
+    useInstead: '`normalizedTmpdir()`',
+    subpath: '/fs',
+    recommended: true,
+    recommendedSeverity: 'error',
+  },
 });

package/eslint/rules/no-path-operations-in-comparisons.cjs

@@ -25,9 +25,14 @@ module.exports = {
   meta: {
     type: 'problem',
     docs: {
-      description: 'Disallow using path operations directly in string comparisons',
-      category: 'Cross-platform compatibility',
+      description:
+        'Disallow using path operations directly in string comparisons',
+      category: 'Path handling',
+      bans: 'raw `path.*()` results in string comparisons',
+      useInstead: 'wrap in `toForwardSlash()`',
+      subpath: '/path',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     messages: {
       normalizePathOperation:

package/eslint/rules/no-path-sep-in-strings.cjs

@@ -25,9 +25,14 @@ module.exports = {
   meta: {
     type: 'problem',
     docs: {
-      description: 'Disallow using path.sep in string operations',
-      category: 'Cross-platform compatibility',
+      description:
+        'Disallow using path.sep in string operations',
+      category: 'Path handling',
+      bans: '`path.sep` embedded in a string literal',
+      useInstead: '`toForwardSlash()`',
+      subpath: '/path',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     messages: {
       noPathSep:

package/eslint/rules/no-path-startswith.cjs

@@ -68,9 +68,14 @@ module.exports = {
   meta: {
     type: 'problem',
     docs: {
-      description: 'Disallow direct path.startsWith() without normalization',
-      category: 'Cross-platform compatibility',
+      description:
+        'Disallow direct path.startsWith() without normalization',
+      category: 'Path handling',
+      bans: '`path.startsWith()` on a raw path',
+      useInstead: '`toForwardSlash()` first',
+      subpath: '/path',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     messages: {
       useNormalizeHelper: