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

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

@@ -0,0 +1,228 @@
+/**
+ * ESLint rule: no-fragile-entrypoint-guard
+ *
+ * Ban the two "am I the script Node was asked to run?" idioms that answer
+ * **false for the script they are guarding**, so the process exits 0 having done
+ * nothing at all.
+ *
+ * @example
+ * // ❌ BAD — undefined before Node 24.2 / 22.18
+ * if (import.meta.main) { await main(); }
+ *
+ * // ❌ BAD — raw string compare, no realpath: false through any `.bin` symlink
+ * if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { … }
+ *
+ * // ❌ BAD — the same compare done in path space instead of URL space
+ * if (fileURLToPath(import.meta.url) === process.argv[1]) { … }
+ *
+ * // ✅ GOOD
+ * import { isEntrypoint } from '@vibe-agent-toolkit/utils/process';
+ * if (isEntrypoint(import.meta.url)) { await main(); }
+ *
+ * ## Why a lint rule and not a comment
+ *
+ * Both defects have already shipped in this repo, and both were invisible to
+ * every gate:
+ *
+ * - `import.meta.main` was added in Node **24.2 / 22.18**. Measured on the exact
+ *   floor this repo declares — `>=22.13.0` — the property is `undefined`:
+ *
+ *   ```
+ *   $ node-v22.13.0 --input-type=module -e "console.log(import.meta.main)"  -> undefined
+ *   $ node-v24.13.1 --input-type=module -e "console.log(import.meta.main)"  -> true
+ *   ```
+ *
+ *   So a repository-structure gate guarded this way printed nothing and exited 0
+ *   on the very Node its own CI job installs. A contributor sitting exactly on
+ *   the supported floor got a green pre-commit gate that had run no rule.
+ *
+ * - `import.meta.url === pathToFileURL(process.argv[1]).href` compares two
+ *   strings with no realpath pass. Invoked through a `node_modules/.bin` shim —
+ *   i.e. the normal way a package's own bin is run — `process.argv[1]` is the
+ *   SYMLINK and `import.meta.url` is the resolved target, the strings differ,
+ *   and the guard is false. Measured false on Node 22.14.0 and 24.13.1 alike,
+ *   where `isEntrypoint()` is true.
+ *
+ *   ⚠️ That defect is about the MISSING REALPATH, not about URLs, so it has a
+ *   second spelling that is just as common and just as wrong:
+ *   `fileURLToPath(import.meta.url) === process.argv[1]` converts the module URL
+ *   to a path instead of converting the invoked path to a URL, and then compares
+ *   the same two unresolved strings. A matcher that only knew the URL-space form
+ *   would be a mechanism with a hole in the middle of its own premise, which is
+ *   the thing this rule exists to refuse. Both directions of both spellings are
+ *   flagged, under one message, because they are one defect.
+ *
+ * The first of those was fixed once already and the fix was pinned by nothing:
+ * reverting all three call sites to `if (import.meta.main)` left the entire test
+ * suite green, because the only thing standing against it was three prose
+ * comments addressed to a human. A banner is not a mechanism. This rule is.
+ *
+ * ## What it does NOT flag
+ *
+ * `import.meta.url`, `import.meta.dirname` and `import.meta.filename` are all
+ * fine and all common — only `.main` is the unavailable one. And
+ * `pathToFileURL(x).href` is only a finding when it is being compared to
+ * `import.meta.url`; on its own it is just a URL.
+ *
+ * ## No `exemptFiles`
+ *
+ * Unlike the wrapper rules in this pack, there is no implementation file that
+ * has to call the banned thing: `isEntrypoint()` is written in terms of
+ * `process.argv[1]` and a realpath comparison, and touches neither idiom. An
+ * exemption option here would only ever be used to opt a file out of a fix.
+ */
+
+'use strict';
+
+/** `import.meta`, as the parser sees it. */
+function isImportMeta(node) {
+  return (
+    node?.type === 'MetaProperty' && node.meta?.name === 'import' && node.property?.name === 'meta'
+  );
+}
+
+/**
+ * `import.meta.<name>` — a static, non-computed member of `import.meta`.
+ *
+ * @param {object} node - Any node.
+ * @param {string} name - The property to match, e.g. `main`.
+ * @returns {boolean}
+ */
+function isImportMetaMember(node, name) {
+  return (
+    node?.type === 'MemberExpression' &&
+    node.computed === false &&
+    isImportMeta(node.object) &&
+    node.property?.type === 'Identifier' &&
+    node.property.name === name
+  );
+}
+
+/**
+ * The called function's NAME, whether called bare or off a namespace.
+ *
+ * `pathToFileURL(p)` and `url.pathToFileURL(p)` are the same call, and a matcher
+ * that only understood the bare form would be blind to every file that imports
+ * `node:url` as a namespace.
+ *
+ * @param {object} callee - The `callee` of a CallExpression.
+ * @returns {string | undefined}
+ */
+function calleeName(callee) {
+  if (callee === null || callee === undefined) return undefined;
+  if (callee.type === 'Identifier') return callee.name;
+  if (callee.type === 'MemberExpression' && callee.computed === false) {
+    return callee.property?.type === 'Identifier' ? callee.property.name : undefined;
+  }
+  return undefined;
+}
+
+/** `pathToFileURL(…).href`, in either import style. */
+function isPathToFileUrlHref(node) {
+  return (
+    node?.type === 'MemberExpression' &&
+    node.computed === false &&
+    node.property?.type === 'Identifier' &&
+    node.property.name === 'href' &&
+    node.object?.type === 'CallExpression' &&
+    calleeName(node.object.callee) === 'pathToFileURL'
+  );
+}
+
+/** `fileURLToPath(import.meta.url)`, in either import style. */
+function isFileUrlToPathOfImportMetaUrl(node) {
+  return (
+    node?.type === 'CallExpression' &&
+    calleeName(node.callee) === 'fileURLToPath' &&
+    isImportMetaMember(node.arguments?.[0], 'url')
+  );
+}
+
+/**
+ * `process.argv[1]` — and the `const { argv } = process` spelling of it.
+ *
+ * The index is pinned to `1` on purpose: `argv[2]` and up are ordinary CLI
+ * arguments, and comparing one of those to anything is not this defect.
+ */
+function isArgvEntry(node) {
+  if (node === null || node === undefined) return false;
+  if (node.type !== 'MemberExpression' || node.computed !== true) return false;
+  if (node.property?.type !== 'Literal' || node.property.value !== 1) return false;
+
+  const target = node.object;
+  if (target?.type === 'Identifier') return target.name === 'argv';
+  return (
+    target?.type === 'MemberExpression' &&
+    target.computed === false &&
+    target.property?.type === 'Identifier' &&
+    target.property.name === 'argv'
+  );
+}
+
+/** Where THIS module lives, in whichever space the comparison is written in. */
+function isModuleLocation(node) {
+  return isImportMetaMember(node, 'url') || isFileUrlToPathOfImportMetaUrl(node);
+}
+
+/** The script Node was ASKED to run, in whichever space the comparison uses. */
+function isInvokedScript(node) {
+  return isArgvEntry(node) || isPathToFileUrlHref(node);
+}
+
+/** Identity comparisons; `==`/`!=` on these operands never occurs and is not the idiom. */
+const IDENTITY_OPERATORS = new Set(['===', '!==']);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    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: '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:
+        '`import.meta.main` is undefined before Node 24.2 / 22.18, so this guard is FALSE on older supported Node and the script exits 0 having done nothing. Use `isEntrypoint(import.meta.url)` from `@vibe-agent-toolkit/utils/process`.',
+      rawEntrypointCompare:
+        'Comparing where this module lives to `process.argv[1]` (as `import.meta.url === pathToFileURL(argv[1]).href`, or as `fileURLToPath(import.meta.url) === argv[1]`) is a raw string compare with no realpath pass, so it is FALSE whenever the script is reached through a symlink (any `node_modules/.bin` shim) and the script exits 0 having done nothing. Use `isEntrypoint(import.meta.url)` from `@vibe-agent-toolkit/utils/process`.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (isImportMetaMember(node, 'main')) {
+          context.report({ node, messageId: 'importMetaMain' });
+        }
+      },
+
+      BinaryExpression(node) {
+        if (!IDENTITY_OPERATORS.has(node.operator)) return;
+
+        // Either operand order: a matcher keyed on side would be half blind.
+        const compares =
+          (isModuleLocation(node.left) && isInvokedScript(node.right)) ||
+          (isModuleLocation(node.right) && isInvokedScript(node.left));
+
+        if (compares) {
+          context.report({ node, messageId: 'rawEntrypointCompare' });
+        }
+      },
+    };
+  },
+};

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

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