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

package/eslint/index.cjs

@@ -9,7 +9,7 @@
  * than in CI on a different OS.
  *
  * They ship as a SUBPATH rather than a separate package because an ESLint plugin
- * is data, not code that runs: every module below exports a plain rule object and
+ * is data, not code that runs: every rule module exports a plain rule object and
  * none of them `require('eslint')`. So this entry resolves — and the other twelve
  * subpaths keep resolving — whether or not ESLint is installed, which is why
  * `eslint` is declared as an OPTIONAL peer dependency. One install, one version,
@@ -20,6 +20,28 @@
  * entry point can be both `require()`d from an `eslint.config.cjs` and `import`ed
  * from an `eslint.config.js`/`.mjs`.
  *
+ * ## The manifest is the directory
+ *
+ * There is no hand-maintained list of rules here. Every `rules/*.cjs` whose
+ * export carries a `meta` object IS a rule, keyed by its basename; the modules
+ * that export a factory or a helper object (`eslint-rule-factory`,
+ * `no-command-direct-factory`, `exempt-path-matcher`, `safe-import`,
+ * `dead-import`) have no `meta` and are skipped. Each rule then declares its own
+ * place in `configs.recommended` through `meta.docs.recommended` and
+ * `meta.docs.recommendedSeverity`, beside the rule it describes — so adding a
+ * rule is one file, and the README/docs table is generated from the same
+ * metadata (`bun run generate:eslint-rules-doc` in `packages/utils`).
+ *
+ * The last hand list here held 27 entries and was mirrored by three literal
+ * counts in two test files and two prose counts in two docs, every one of which
+ * had drifted at least once. A directory listing cannot drift.
+ *
+ * `node:fs` and `node:path` are the ONLY external modules this subpath reaches,
+ * and only from this file: the rule modules themselves still require nothing —
+ * `test/eslint/subpath-purity.test.ts` pins both halves. Two builtins that ship
+ * with every Node install do not change the optional-peer property, which was
+ * only ever about `eslint` and third-party packages.
+ *
  * Rules whose exemptions name a file (the ONE implementation file allowed to call
  * the primitive) take an `exemptFiles` option — see README.md. The shipped
  * defaults are EMPTY: an exemption is a claim about a specific repo's layout, and
@@ -29,109 +51,75 @@
 
 'use strict';
 
-const rules = {
-  'no-child-process-execSync': require('./rules/no-child-process-execSync.cjs'),
-  'no-hardcoded-path-split': require('./rules/no-hardcoded-path-split.cjs'),
-  'no-path-startswith': require('./rules/no-path-startswith.cjs'),
-  'no-unix-shell-commands': require('./rules/no-unix-shell-commands.cjs'),
-  'no-os-tmpdir': require('./rules/no-os-tmpdir.cjs'),
-  'no-fs-mkdirSync': require('./rules/no-fs-mkdirSync.cjs'),
-  'no-fs-realpathSync': require('./rules/no-fs-realpathSync.cjs'),
-  'no-manual-path-normalize': require('./rules/no-manual-path-normalize.cjs'),
-  'no-path-sep-in-strings': require('./rules/no-path-sep-in-strings.cjs'),
-  'no-path-operations-in-comparisons': require('./rules/no-path-operations-in-comparisons.cjs'),
-  'no-path-join': require('./rules/no-path-join.cjs'),
-  'no-path-resolve': require('./rules/no-path-resolve.cjs'),
-  'no-path-relative': require('./rules/no-path-relative.cjs'),
-  'no-test-scoped-functions': require('./rules/no-test-scoped-functions.cjs'),
-  'no-fs-promises-cp': require('./rules/no-fs-promises-cp.cjs'),
-  'no-url-pathname-for-fs': require('./rules/no-url-pathname-for-fs.cjs'),
-  'no-bare-dynamic-import-path': require('./rules/no-bare-dynamic-import-path.cjs'),
-  'no-file-url-string-concat': require('./rules/no-file-url-string-concat.cjs'),
-  'prefer-startswith-over-regex': require('./rules/prefer-startswith-over-regex.cjs'),
-  'no-unsafe-root-join': require('./rules/no-unsafe-root-join.cjs'),
-  'require-justified-skip': require('./rules/require-justified-skip.cjs'),
-};
+const { readdirSync } = require('node:fs');
+const path = require('node:path');
+
+const RULES_DIR = path.join(__dirname, 'rules');
 
 /**
- * Rules deliberately LEFT OUT of `configs.recommended`.
- *
- * `recommended` is the cross-platform-safety core: every rule in it flags a call
- * that is wrong (or unportable) regardless of how the adopting project likes to
- * write tests. The two below are neither — they encode a position on TEST STYLE:
- *
- * - `require-justified-skip` — a specific annotation grammar (`SKIP(#123): reason`)
- *   for a disabled test, plus a view on what counts as a tautological assertion.
- * - `no-test-scoped-functions` — a view on WHERE a test helper may be declared
- *   (module scope, never inside `describe`/`it`).
- *
- * Someone installing this package for `safePath.join()` should not silently
- * inherit either. Both ship in `rules` and stay enabled explicitly:
- *
- *   '@vibe-agent-toolkit/require-justified-skip': 'error',
- *
- * That is exactly what VAT's own `eslint.config.js` does — it does not consume
- * `configs.recommended` at all, so this exclusion changes nothing about how this
- * repo lints itself.
+ * The two values `recommendedSeverity` may take. A rule that is not
+ * recommended may still declare one — it is the severity the rule WOULD ride
+ * at, and the generated docs table prints it — but `off` is not a spelling: a
+ * rule that wants to be off is a rule with `recommended: false`.
  */
-const RECOMMENDED_EXCLUDE = new Set([
-  'require-justified-skip',
-  'no-test-scoped-functions',
-  // Excluded for a DIFFERENT reason than the two above: not a style opinion, but
-  // an unsound heuristic. It keys on whether an identifier's name ends in `root`
-  // rather than on whether any segment is caller-controlled, which makes it
-  // simultaneously noisy and blind. Measured on a 4,670-file adopter tree: 108
-  // findings, 0 autofixable, and every one of these verified by execution here:
-  //
-  //   FIRES   safePath.join(repoRoot, 'docs', 'product')  <- all literals, cannot escape
-  //   FIRES   safePath.resolve(packageRoot, '..', '..')   <- escaping IS the intent; the fix breaks it
-  //   FIRES   safePath.join(repoRoot)                     <- one argument, no segment at all
-  //   silent  safePath.join(base, userInput)              <- THE dangerous shape, missed
-  //
-  // A rule that misses the case it exists to catch must not ride in a config
-  // named `recommended` at any severity — a safety core that cries wolf teaches
-  // people to ignore it, which costs the true positives too. It still ships, and
-  // it still earns `error` where scoped to directories in which a path escape is
-  // a security boundary (this repo scopes it to the skill-test staging code).
-  // Re-include it when it keys on taint rather than on naming.
-  'no-unsafe-root-join',
-]);
+const RECOMMENDED_SEVERITIES = new Set(['error', 'warn']);
 
 /**
- * Default severities for `configs.recommended`.
- *
- * `error` is the default: every rule below flags a call whose replacement is a
- * one-line swap, and a wrong answer is a real bug on some platform.
- *
- * `warn` is reserved for the case where a fresh adopter's first run would
- * otherwise be a wall of blocking errors they cannot triage in one sitting:
- * `no-path-join` / `no-path-resolve` / `no-path-relative`, the highest-churn
- * rules by far (they fire on every raw `node:path` call in the codebase).
- * Measured on a 4,670-file adopter tree: 3,963 + 372 + 1 findings, **all
- * autofixable**. All three auto-fix, so `warn` lets a project run `--fix` and
- * burn the list down incrementally instead of blocking CI on day one.
- *
- * Raise them to `error` once the backlog is clear — that is what VAT itself does.
+ * Read a rule's `meta.docs` and refuse anything a rule in this pack must not ship
+ * without. Thrown at load time, so a malformed rule fails every consumer's
+ * `eslint` run at startup rather than silently landing outside `recommended`.
+ */
+function validateRuleDocs(name, rule) {
+  if (typeof rule.create !== 'function') {
+    throw new TypeError(`eslint rule '${name}' exports a meta but no create function`);
+  }
+  const docs = rule.meta.docs;
+  if (typeof docs?.description !== 'string' || docs.description.length === 0) {
+    throw new TypeError(`eslint rule '${name}' has no meta.docs.description`);
+  }
+  if (typeof docs.recommended !== 'boolean') {
+    throw new TypeError(`eslint rule '${name}' must declare meta.docs.recommended as a boolean`);
+  }
+  if (docs.recommendedSeverity !== undefined && !RECOMMENDED_SEVERITIES.has(docs.recommendedSeverity)) {
+    throw new TypeError(`eslint rule '${name}' declares meta.docs.recommendedSeverity outside 'error' | 'warn'`);
+  }
+  if (docs.recommended && docs.recommendedSeverity === undefined) {
+    throw new TypeError(`eslint rule '${name}' is recommended but declares no meta.docs.recommendedSeverity`);
+  }
+}
+
+/**
+ * Every rule module under `rules/`, keyed by basename, in directory order
+ * (which `readdirSync` returns sorted on every platform this package supports).
  *
- * The criterion for `warn` is MIGRATION VOLUME, not how real the finding is. Every
- * rule in this pack either prevents a bug or shifts a static-analysis finding left of
- * a merge, and both are worth blocking on; what `warn` buys is a first run that reads
- * as a backlog to `--fix` rather than a wall. `prefer-startswith-over-regex` was
- * briefly graded on a different axis ("style, not a defect") and demoted — that was
- * wrong twice over: avoiding a SonarQube S6557 at lint time instead of at merge time
- * is a real saving, and the rule's matcher rejects any regex containing a
- * metacharacter, so it only fires on true literal prefixes and has near-zero churn.
- * It is `error`.
+ * Distinguished from the factories and helpers by a `meta` export, not by
+ * filename: a naming convention is a claim nobody checks, and a factory that
+ * happened to be named `no-…` would otherwise be registered as a rule whose
+ * `create` is a function that builds rules.
  */
-const RECOMMENDED_WARN = new Set([
-  'no-path-join',
-  'no-path-resolve',
-  'no-path-relative',
-]);
+function discoverRules(rulesDir = RULES_DIR) {
+  const rules = {};
+  for (const file of readdirSync(rulesDir)) {
+    if (!file.endsWith('.cjs')) {
+      continue;
+    }
+    // eslint-disable-next-line security/detect-non-literal-require -- the directory listing IS the manifest; every entry is a file this package ships
+    const candidate = require(path.join(rulesDir, file));
+    if (typeof candidate !== 'object' || candidate === null || typeof candidate.meta !== 'object') {
+      continue;
+    }
+    const name = file.slice(0, -'.cjs'.length);
+    validateRuleDocs(name, candidate);
+    rules[name] = candidate;
+  }
+  return rules;
+}
+
+const rules = discoverRules();
 
 /**
  * Plugin namespace an adopter gets from `configs.recommended`, and therefore the
- * prefix on every rule id (`@vibe-agent-toolkit/no-path-join`).
+ * prefix on every rule id (`@vibe-agent-toolkit/no-raw-node-path`).
  *
  * Deliberately the SCOPE, not the full subpath specifier: rule ids are the surface
  * adopters type into `rules`, `eslint-disable` comments and CI baselines, and they
@@ -146,15 +134,41 @@ const plugin = {
   },
   rules,
   configs: {},
+  /** Test seam: the discovery walk over an arbitrary directory, so the load-time refusals can be exercised on a fixture. */
+  __internal: { discoverRules },
 };
 
+/**
+ * `configs.recommended` is the cross-platform-safety core: every rule whose
+ * `meta.docs.recommended` is true, at the severity it declares.
+ *
+ * `error` is the norm: every such rule flags a call whose replacement is a
+ * one-line swap, and a wrong answer is a real bug on some platform. `warn` is
+ * reserved for the case where a fresh adopter's first run would otherwise be a
+ * wall of blocking errors they cannot triage in one sitting — the criterion is
+ * MIGRATION VOLUME, not how real the finding is. A rule whose findings were
+ * doubted would be out of `recommended` entirely, not demoted.
+ *
+ * Each rule that opts OUT states why beside its own `recommended: false`. The
+ * reasons fall into a few families — a position on TEST STYLE
+ * (`require-justified-skip`, `no-test-scoped-functions`), a heuristic that keys
+ * on a NAMING CONVENTION rather than the property it cares about
+ * (`no-unsafe-root-join`, `no-process-exit-in-phase`), a SEAM that only exists
+ * once the consumer writes it (`no-raw-text-decode`), a REQUIRED OPTION this
+ * config cannot supply (`no-self-package-import`), and a claim about the
+ * CONSUMER's environment that is right for some and wrong for others
+ * (`no-fragile-entrypoint-guard`, `no-bare-symlink-in-tests`). Someone installing
+ * this package for `safePath.join()` should not silently inherit any of them.
+ * All still ship in `rules` and are enabled by naming them — which is what
+ * VAT's own `eslint.config.js` does; it does not consume `configs.recommended`.
+ */
 plugin.configs.recommended = {
   name: '@vibe-agent-toolkit/utils/eslint/recommended',
   plugins: { [NAMESPACE]: plugin },
   rules: Object.fromEntries(
-    Object.keys(rules)
-      .filter((name) => !RECOMMENDED_EXCLUDE.has(name))
-      .map((name) => [`${NAMESPACE}/${name}`, RECOMMENDED_WARN.has(name) ? 'warn' : 'error']),
+    Object.entries(rules)
+      .filter(([, rule]) => rule.meta.docs.recommended)
+      .map(([name, rule]) => [`${NAMESPACE}/${name}`, rule.meta.docs.recommendedSeverity]),
   ),
 };
 

package/eslint/index.d.cts

@@ -37,20 +37,30 @@ declare namespace plugin {
   interface FlatConfig {
     name: string;
     plugins: Record<string, Plugin>;
-    /** Rule id → severity. Keys are namespaced: `@vibe-agent-toolkit/no-path-join`. */
+    /** Rule id → severity. Keys are namespaced: `@vibe-agent-toolkit/no-raw-node-path`. */
     rules: Record<string, 'error' | 'warn' | 'off'>;
   }
 
   interface Plugin {
     meta: { name: string };
-    /** Rule name WITHOUT the namespace prefix, e.g. `no-path-join`. */
+    /** Rule name WITHOUT the namespace prefix, e.g. `no-raw-node-path`. */
     rules: Record<string, RuleModule>;
     configs: {
       /**
-       * The cross-platform safety core: 18 of the 21 rules, 15 `error` / 3 `warn`.
-       * `no-test-scoped-functions` and `require-justified-skip` are excluded — they
-       * are positions on test style, not portability facts. Both still ship in
-       * `rules` and are enabled by naming them.
+       * The cross-platform safety core: every rule whose `meta.docs.recommended`
+       * is true, at the severity its `meta.docs.recommendedSeverity` declares.
+       *
+       * No count lives here on purpose. This comment once read "18 of the 22
+       * rules, four are excluded" while the registry held 24 and the exclude
+       * set six, and later "19 of the 27" — a number in prose is a claim the
+       * manifest cannot check. The generated table in `README.md` carries the
+       * live counts, and `test/eslint/rule-manifest.test.ts` asserts the
+       * config against the directory rather than against a literal.
+       *
+       * Every rule that opts out states why beside its own `recommended: false`
+       * in `rules/<name>.cjs`; all of them still ship in `rules` and are
+       * enabled by naming them — which is what this repo's own
+       * `eslint.config.js` does.
        */
       recommended: FlatConfig;
     };

package/eslint/rules/callee-name.cjs

@@ -0,0 +1,23 @@
+/**
+ * Shared by the rules that match a call by name: the identifier a call is
+ * made through, bare (`spawn(…)`) or as the last member of a non-computed
+ * member expression (`cp.spawn(…)`), or `null` for any other callee.
+ *
+ * Not a rule — exports no `meta`, so `index.cjs` never registers it.
+ */
+
+'use strict';
+
+/** @param {object} call - ESTree `CallExpression` node. */
+function calleeName(call) {
+  const { callee } = call;
+  if (callee.type === 'Identifier') {
+    return callee.name;
+  }
+  if (callee.type === 'MemberExpression' && !callee.computed && callee.property.type === 'Identifier') {
+    return callee.property.name;
+  }
+  return null;
+}
+
+module.exports = { calleeName };

package/eslint/rules/commands-import-boundary.cjs

@@ -0,0 +1,148 @@
+/**
+ * ESLint rule: commands-import-boundary
+ *
+ * In a command module — a file under one of the configured command
+ * directories — flags any import of the filesystem (`node:fs`,
+ * `node:fs/promises`, `fs`, `fs/promises`) and any import whose specifier
+ * matches a configured forbidden-module pattern (a package's internals, a
+ * local parser or walker module).
+ *
+ * A command's job is to parse arguments, call a seam, and render a report. The
+ * moment it opens a directory itself it has become a fifth enumeration lane
+ * nobody documented: `docs/contributing/command-lane-table.md` names the
+ * walkers every population must come through, and one command carrying its
+ * own ~700-line walker beside them was the audit finding behind this rule.
+ * The boundary is syntactic — an import is an import — so it holds at the
+ * desk rather than in a review.
+ *
+ * Shapes covered: static `import`, `import type` is IGNORED (a type does no
+ * I/O), `export … from`, dynamic `import('…')` and `require('…')` with a
+ * literal specifier.
+ *
+ * Options:
+ * - `commandGlobs: string[]` — repo-relative directories that hold commands
+ *   (default `['packages/cli/src/commands/']`). A trailing `/**` is accepted
+ *   and ignored; matching is by anchored directory prefix, so nested command
+ *   directories are covered.
+ * - `forbiddenModules: string[]` — regex sources tested against the import
+ *   specifier (default `['^@vibe-agent-toolkit/resources/']`: the barrel is a
+ *   seam, a subpath is an internal).
+ * - `allowFiles: string[]` — repo-relative paths of today's offenders, the
+ *   ratchet. Name files, never directories.
+ *
+ * @example
+ * // BAD — the command is now a walker
+ * import { readdirSync } from 'node:fs';
+ *
+ * // GOOD — the population comes through a declared lane
+ * import { crawlDirectory } from '@vibe-agent-toolkit/utils/crawl';
+ */
+
+'use strict';
+
+const {
+  createExemptDirectoryMatcher,
+  createExemptPathMatcher,
+} = require('./exempt-path-matcher.cjs');
+
+const FS_MODULES = new Set(['node:fs', 'node:fs/promises', 'fs', 'fs/promises']);
+const DEFAULT_COMMAND_DIRS = ['packages/cli/src/commands/'];
+const DEFAULT_FORBIDDEN = ['^@vibe-agent-toolkit/resources/'];
+
+/** Strip a trailing glob so `packages/cli/src/commands/**` reads as its directory. */
+function toDirectory(entry) {
+  return entry.endsWith('/**') ? entry.slice(0, -2) : entry;
+}
+
+/** The string value of a literal module specifier, or null. */
+function literalSpecifier(node) {
+  return node?.type === 'Literal' && typeof node.value === 'string' ? node.value : null;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow filesystem and internal-module imports in command modules — a command calls a ' +
+        'declared enumeration lane, it does not become one',
+      recommended: false,
+      recommendedSeverity: 'warn',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          commandGlobs: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+          forbiddenModules: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+          allowFiles: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      fsImport:
+        "Command modules do not import '{{source}}': reading the tree here makes this command an " +
+        'undeclared enumeration lane. Go through a seam in @vibe-agent-toolkit/utils or ' +
+        '@vibe-agent-toolkit/resources (see docs/contributing/command-lane-table.md).',
+      forbiddenModule:
+        "Command modules do not import '{{source}}' (matches forbidden pattern /{{pattern}}/): " +
+        'it is an internal, not a seam. Import the barrel or the declared lane instead.',
+    },
+  },
+
+  create(context) {
+    const options = context.options?.[0] ?? {};
+    const filename = context.filename ?? context.getFilename();
+    const commandDirs = (options.commandGlobs ?? DEFAULT_COMMAND_DIRS).map(toDirectory);
+    const isCommandFile = createExemptDirectoryMatcher(commandDirs);
+    const isAllowed = createExemptPathMatcher(options.allowFiles ?? []);
+    if (!isCommandFile(filename) || isAllowed(filename)) {
+      return {};
+    }
+
+    const forbidden = (options.forbiddenModules ?? DEFAULT_FORBIDDEN).map((pattern) => ({
+      pattern,
+      // eslint-disable-next-line security/detect-non-literal-regexp -- the option is a regex source by contract: a config-time string written by the repo, not user data
+      regex: new RegExp(pattern, 'u'),
+    }));
+
+    function check(node, source) {
+      if (source === null) {
+        return;
+      }
+      if (FS_MODULES.has(source)) {
+        context.report({ node, messageId: 'fsImport', data: { source } });
+        return;
+      }
+      const hit = forbidden.find(({ regex }) => regex.test(source));
+      if (hit) {
+        context.report({ node, messageId: 'forbiddenModule', data: { source, pattern: hit.pattern } });
+      }
+    }
+
+    return {
+      ImportDeclaration(node) {
+        if (node.importKind !== 'type') {
+          check(node, literalSpecifier(node.source));
+        }
+      },
+      ExportNamedDeclaration(node) {
+        if (node.source && node.exportKind !== 'type') {
+          check(node, literalSpecifier(node.source));
+        }
+      },
+      ExportAllDeclaration(node) {
+        check(node, literalSpecifier(node.source));
+      },
+      ImportExpression(node) {
+        check(node, literalSpecifier(node.source));
+      },
+      CallExpression(node) {
+        if (node.callee.type === 'Identifier' && node.callee.name === 'require') {
+          check(node, literalSpecifier(node.arguments[0]));
+        }
+      },
+    };
+  },
+};

package/eslint/rules/dead-import.cjs

@@ -233,7 +233,7 @@ function reportDeadUnsafeImports(
       },
       // `fixer.remove(node)` takes the declaration and leaves its newline, so a
       // blank line remains where the import was. That is exactly what the
-      // specifier-removal leg in `path-function-rule-factory.cjs` has always
+      // specifier-removal leg in `no-raw-node-path.cjs` has always
       // done — its fixtures pin the leading `\n` — and matching it keeps one
       // behaviour rather than two. Extending the range through a trailing
       // whitespace-only remainder would tidy both, and should be done to both at