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

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: [],