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

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

@@ -2,10 +2,13 @@
  * ESLint rule to disallow splitting strings by hardcoded path separators
  *
  * Using .split('/') or .split('\\') on file paths breaks on Windows/Unix.
- * Use path.basename(), path.dirname(), or normalize with toForwardSlash() first.
+ * Use path.basename(), path.dirname(), or normalize first: toForwardSlash() for a
+ * NATIVE path (fs, path.*, the VCS — converts only where the host separator is a
+ * backslash), toForwardSlashAnyPlatform() for AUTHOR-WRITTEN text (hrefs, globs,
+ * config values, archive entries — converts every backslash on every host).
  *
  * This rule is smart enough to detect when paths are already normalized:
- * - Inline: toForwardSlash(path).split('/') ✅
+ * - Inline: toForwardSlash(path).split('/') ✅ (either converter)
  * - Variable: const normalized = toForwardSlash(path); normalized.split('/') ✅
  *
  * @example
@@ -24,6 +27,9 @@
  * // ✅ GOOD - normalize then split (variable)
  * const normalizedPath = toForwardSlash(filePath);
  * const parts = normalizedPath.split('/');
+ *
+ * // ✅ GOOD - authored text (a glob, an href) converts on every host
+ * const segments = toForwardSlashAnyPlatform(pattern).split('/');
  */
 
 const {
@@ -32,37 +38,46 @@ const {
   resolveSafeModule,
 } = require('./safe-import.cjs');
 
+/** The converters whose result is forward-slashed, so splitting it on `/` is safe. */
+const NORMALIZERS = new Set(['toForwardSlash', 'toForwardSlashAnyPlatform']);
+
+/** A direct call to one of {@link NORMALIZERS}? */
+function isNormalizerCall(node) {
+  return node?.type === 'CallExpression' && node.callee.type === 'Identifier' && NORMALIZERS.has(node.callee.name);
+}
+
 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()` / `toForwardSlashAnyPlatform()` first',
+      subpath: '/path',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     messages: {
       noHardcodedSplit:
         String.raw`Avoid .split('/') or .split('\') on file paths (breaks on Windows/Unix). ` +
-        'Use path.basename() to extract filename, or toForwardSlash() from {{safeModule}} to normalize paths first.',
+        'Use path.basename() to extract filename, or normalize first with toForwardSlash() (native paths) ' +
+        'or toForwardSlashAnyPlatform() (authored text such as globs and hrefs) from {{safeModule}}.',
     },
     schema: [SAFE_MODULE_ONLY_SCHEMA],
   },
 
   create(context) {
     const reportData = { safeModule: resolveSafeModule(context, SAFE_PATH_MODULE) };
-    // Track variables that were assigned from toForwardSlash()
+    // Track variables that were assigned from a normalizer
     const normalizedVariables = new Set();
 
     return {
       // Track variable declarations
       VariableDeclarator(node) {
-        // Check if this variable is assigned from toForwardSlash()
-        if (
-          node.init?.type === 'CallExpression' &&
-          node.init.callee.type === 'Identifier' &&
-          node.init.callee.name === 'toForwardSlash' &&
-          node.id.type === 'Identifier'
-        ) {
+        // Check if this variable is assigned from a normalizer
+        if (isNormalizerCall(node.init) && node.id.type === 'Identifier') {
           normalizedVariables.add(node.id.name);
         }
       },
@@ -102,11 +117,7 @@ module.exports = {
         const object = node.callee.object;
 
         // Case 1: Inline normalization - toForwardSlash(...).split('/')
-        if (
-          object.type === 'CallExpression' &&
-          object.callee.type === 'Identifier' &&
-          object.callee.name === 'toForwardSlash'
-        ) {
+        if (isNormalizerCall(object)) {
           return; // Safe - normalized inline
         }
 

package/eslint/rules/no-io-in-unit-tier.cjs

@@ -0,0 +1,129 @@
+/**
+ * ESLint rule: no-io-in-unit-tier
+ *
+ * In a UNIT-tier test file, flags an import of `node:child_process` /
+ * `child_process` and any call to `mkdtemp`, `mkdtempSync`, `spawn`,
+ * `spawnSync`, `execSync` or `execFileSync` — bare or through a namespace.
+ *
+ * The tiers are a promise about cost and about what is being tested: a unit
+ * test exercises logic and finishes in milliseconds; an integration test
+ * wires real components; a system test runs the real binary. A `*.test.ts`
+ * that spawns `git` or mints a temp directory has silently moved tiers
+ * without moving files — it runs under the unit budget, it is coverage-
+ * instrumented as if it were pure, and it is the first thing to flake on a
+ * loaded CI runner. The audit measured the class at 93 unit files touching
+ * the real filesystem and 5 spawning real processes. Moving a file to the
+ * tier it belongs to is a rename; this rule makes the rename happen at the
+ * desk rather than in a 53-second package run.
+ *
+ * ## The tier boundary, as this rule reads it
+ *
+ * A file is unit-tier when it is a test file (`*.test.ts` and friends) under
+ * `packages/<pkg>/test/` at any depth, EXCEPT when it sits under an
+ * `integration/` or `system/` directory or carries the `.integration.test.`
+ * / `.system.test.` suffix. Helpers (`test-helpers.ts`) are not test files
+ * and are not checked here; a helper that spawns is caught at the unit file
+ * that calls it only if the call is visible there, which is a known floor.
+ *
+ * Option `allowFiles: string[]` — repo-relative paths of today's offenders,
+ * the ratchet. Name files, never directories.
+ *
+ * @example
+ * // BAD in packages/x/test/thing.test.ts — a system test wearing a unit name
+ * const out = spawnSync('node', [bin, '--json']);
+ *
+ * // GOOD — same code, in packages/x/test/system/thing.system.test.ts
+ */
+
+'use strict';
+
+const { calleeName } = require('./callee-name.cjs');
+const { createExemptPathMatcher, isTestFile } = require('./exempt-path-matcher.cjs');
+
+const CHILD_PROCESS_MODULES = new Set(['node:child_process', 'child_process']);
+const IO_CALLS = new Set(['mkdtemp', 'mkdtempSync', 'spawn', 'spawnSync', 'execSync', 'execFileSync']);
+
+/** `packages/<pkg>/test/` anywhere in the path, with either separator already normalised. */
+const PACKAGE_TEST_DIR = /(?:^|\/)packages\/[^/]+\/test\//u;
+
+/** The integration and system tiers, by directory or by suffix. */
+const OTHER_TIER = /\/(?:integration|system)\/|\.(?:integration|system)\.test\./u;
+
+/** Whether `filename` is a unit-tier test file under a package's `test/`. */
+function isUnitTierFile(filename) {
+  if (!filename) {
+    return false;
+  }
+  // eslint-disable-next-line local/no-manual-path-normalize -- the rule pack is standalone CommonJS and cannot import the ESM helper; config paths and linted filenames are matched separator-agnostically on purpose.
+  const normalized = String(filename).replaceAll('\\', '/');
+  return isTestFile(normalized) && PACKAGE_TEST_DIR.test(normalized) && !OTHER_TIER.test(normalized);
+}
+
+/** The banned callee name of a call, bare (`spawn(…)`) or namespaced (`cp.spawn(…)`), or null. */
+function bannedCallName(call) {
+  const name = calleeName(call);
+  return name !== null && IO_CALLS.has(name) ? name : null;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow child_process imports and mkdtemp/spawn/exec calls in unit-tier test files — ' +
+        'a test that spawns or writes to disk belongs in the integration or system tier',
+      recommended: false,
+      recommendedSeverity: 'warn',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allowFiles: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      childProcessImport:
+        "A unit-tier test imports '{{source}}': spawning a process is integration or system work. " +
+        'Move the file to test/integration/ (*.integration.test.ts) or test/system/ ' +
+        '(*.system.test.ts), or mock the module.',
+      ioCall:
+        'A unit-tier test calls {{name}}(): real processes and temp directories belong to the ' +
+        'integration or system tier. Move the file to that tier, or test the logic without the I/O.',
+    },
+  },
+
+  create(context) {
+    const filename = context.filename ?? context.getFilename();
+    const isAllowed = createExemptPathMatcher(context.options?.[0]?.allowFiles ?? []);
+    if (!isUnitTierFile(filename) || isAllowed(filename)) {
+      return {};
+    }
+
+    function checkModule(node, sourceNode) {
+      const source = sourceNode?.type === 'Literal' ? sourceNode.value : null;
+      if (typeof source === 'string' && CHILD_PROCESS_MODULES.has(source)) {
+        context.report({ node, messageId: 'childProcessImport', data: { source } });
+      }
+    }
+
+    return {
+      ImportDeclaration(node) {
+        if (node.importKind !== 'type') {
+          checkModule(node, node.source);
+        }
+      },
+      ImportExpression(node) {
+        checkModule(node, node.source);
+      },
+      CallExpression(node) {
+        const name = bannedCallName(node);
+        if (name !== null) {
+          context.report({ node, messageId: 'ioCall', data: { name } });
+        }
+      },
+    };
+  },
+};

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

@@ -0,0 +1,129 @@
+/**
+ * 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.
+ *
+ * @example
+ * // BAD — 1 means what, exactly?
+ * process.exit(1);
+ *
+ * // GOOD — the meaning is the code
+ * process.exit(ExitCode.FINDINGS);
+ */
+
+'use strict';
+
+const { createExemptPathMatcher } = require('./exempt-path-matcher.cjs');
+
+/** 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 },
+        },
+        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.',
+    },
+  },
+
+  create(context) {
+    const allow = context.options?.[0]?.allow ?? [];
+    const filename = context.filename ?? context.getFilename();
+    if (createExemptPathMatcher(allow)(filename)) {
+      return {};
+    }
+
+    function reportLiteral(node, expr, messageId) {
+      const leaf = numericLiteralLeaf(expr);
+      if (leaf !== null) {
+        context.report({ node, messageId, data: { literal: String(leaf.raw ?? leaf.value) } });
+      }
+    }
+
+    return {
+      CallExpression(node) {
+        if (isProcessMember(node.callee, 'exit') && node.arguments.length > 0) {
+          reportLiteral(node, node.arguments[0], 'literalExit');
+        }
+      },
+      AssignmentExpression(node) {
+        if (isProcessMember(node.left, 'exitCode')) {
+          reportLiteral(node, node.right, 'literalExitCode');
+        }
+      },
+    };
+  },
+};

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',
+  },
 });