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

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

@@ -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:

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

@@ -0,0 +1,128 @@
+/**
+ * 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;
+  }
+  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

@@ -33,9 +33,14 @@ 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, '/')`",
+      useInstead: '`toForwardSlash()`',
+      subpath: '/path',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     fixable: 'code',
     messages: {

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:

package/eslint/rules/no-process-exit-in-phase.cjs

@@ -93,8 +93,18 @@ module.exports = {
     docs: {
       description:
         'Forbid process.exit() inside a phase entry point, where it would end the whole orchestrated run',
-      category: 'Agentic Code Safety',
-      recommended: true,
+      category: 'Process control',
+      bans: '`process.exit()` inside a function named `…Phase`',
+      useInstead: 'return the exit code from the phase; only the command wrapper exits',
+      // Not in `recommended`: it keys on a NAMING CONVENTION that is VAT's, not a
+      // portable fact. The hazard is real and general (an in-process orchestrator
+      // whose step calls `process.exit()` silently skips every later step), but
+      // the marker is the `…Phase` suffix, and an adopter with an unrelated
+      // `computeRenderPhase()` that legitimately exits would get a finding they
+      // cannot act on. VAT enables it explicitly, repo-wide, so a NEW phase is
+      // covered the moment it is named like one.
+      recommended: false,
+      recommendedSeverity: 'error',
     },
     fixable: null,
     schema: [],