@vibe-agent-toolkit/utils 0.1.41 → 0.1.42

package/eslint/rules/no-bare-dynamic-import-path.cjs

@@ -0,0 +1,142 @@
+/**
+ * ESLint rule: no-bare-dynamic-import-path
+ *
+ * Prevents `await import(p)` where `p` is a raw filesystem path.
+ * On Windows, ESM dynamic import of a bare path fails — it requires a `file://`
+ * URL. Observed bug: `await import('D:\\a\\repo\\config.js')` throws.
+ *
+ * Fix: `await import(pathToFileURL(p).href)` from `node:url`, or
+ * `await dynamicImportPath(p)` from `@vibe-agent-toolkit/utils/fs`.
+ *
+ * Heuristic (intentionally narrow — some false positives are preferable to
+ * false negatives for a shift-left lint rule, but the user can suppress per line):
+ *   - String literal starting with `/` or `C:\` style absolute path → flag
+ *   - Call to `path.join`, `path.resolve`, `join`, `resolve`, `safePath.*` → flag
+ *   - Identifier whose name matches /path|file|config|module|dir/i → flag
+ *     (will have false positives on well-named variables that already hold
+ *     file:// URLs; suppress those call-sites with eslint-disable-next-line.)
+ *   - Template literal that embeds a path-shaped call → flag
+ *
+ * Does NOT flag:
+ *   - Relative module specifiers (`./foo.js`, `../bar.js`)
+ *   - Bare package names (`some-pkg`)
+ *   - Expressions ending in `.href` (assume correct `pathToFileURL(x).href`)
+ */
+
+'use strict';
+
+const {
+  SAFE_FS_MODULE,
+  SAFE_MODULE_ONLY_SCHEMA,
+  resolveSafeModule,
+} = require('./safe-import.cjs');
+
+const PATH_CALL_NAMES = new Set(['join', 'resolve']);
+const PATH_OBJECT_NAMES = new Set(['path', 'safePath']);
+const PATH_SHAPED_IDENTIFIER = /path|file|config|module|dir/i;
+const ABSOLUTE_PATH_LITERAL = /^(\/|[A-Za-z]:[\\/])/;
+
+function isPathCallExpression(node) {
+  if (node?.type !== 'CallExpression') return false;
+  const callee = node.callee;
+  // bare call: join(...), resolve(...)
+  if (callee.type === 'Identifier' && PATH_CALL_NAMES.has(callee.name)) {
+    return true;
+  }
+  // member call: path.join, path.resolve, safePath.join, safePath.resolve
+  if (
+    callee.type === 'MemberExpression' &&
+    callee.object.type === 'Identifier' &&
+    PATH_OBJECT_NAMES.has(callee.object.name) &&
+    callee.property.type === 'Identifier'
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function isHrefAccess(node) {
+  return (
+    node?.type === 'MemberExpression' &&
+    node.property.type === 'Identifier' &&
+    node.property.name === 'href'
+  );
+}
+
+function isRelativeOrBareSpecifier(value) {
+  if (typeof value !== 'string' || value.length === 0) return false;
+  if (value.startsWith('./') || value.startsWith('../') || value === '.' || value === '..') {
+    return true;
+  }
+  // Bare package name — no leading slash, no drive letter.
+  if (ABSOLUTE_PATH_LITERAL.test(value)) return false;
+  return !value.includes('\\');
+}
+
+function templateHasPathCall(node) {
+  if (node?.type !== 'TemplateLiteral') return false;
+  return node.expressions.some((expr) => isPathCallExpression(expr));
+}
+
+function classifyImportArgument(arg) {
+  if (!arg) return null;
+
+  // Literal string specifier — flag only if absolute path-shaped.
+  if (arg.type === 'Literal' && typeof arg.value === 'string') {
+    if (isRelativeOrBareSpecifier(arg.value)) return null;
+    if (ABSOLUTE_PATH_LITERAL.test(arg.value)) return 'absolute-literal';
+    return null;
+  }
+
+  // Template literal with a path call embedded.
+  if (arg.type === 'TemplateLiteral') {
+    if (templateHasPathCall(arg)) return 'template-with-path-call';
+    return null;
+  }
+
+  // `pathToFileURL(x).href` or similar — correct form, do not flag.
+  if (isHrefAccess(arg)) return null;
+
+  // path.join(...) / path.resolve(...) / join(...) / resolve(...)
+  if (isPathCallExpression(arg)) return 'path-call';
+
+  // Bare identifier whose name hints at a filesystem path.
+  if (arg.type === 'Identifier' && PATH_SHAPED_IDENTIFIER.test(arg.name)) {
+    return 'path-shaped-identifier';
+  }
+
+  return null;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow dynamic `import()` of a filesystem path; wrap with `pathToFileURL(p).href`.',
+      category: 'Cross-platform compatibility',
+      recommended: true,
+    },
+    messages: {
+      useFileUrl:
+        'Dynamic `import()` of a filesystem path fails on Windows. ' +
+        'Wrap with `pathToFileURL(p).href` from `node:url`, or use `dynamicImportPath(p)` from `{{safeModule}}`.',
+    },
+    schema: [SAFE_MODULE_ONLY_SCHEMA],
+  },
+
+  create(context) {
+    return {
+      ImportExpression(node) {
+        const kind = classifyImportArgument(node.source);
+        if (kind) {
+          context.report({
+            node,
+            messageId: 'useFileUrl',
+            data: { safeModule: resolveSafeModule(context, SAFE_FS_MODULE) },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-child-process-execSync.cjs

@@ -0,0 +1,23 @@
+/**
+ * ESLint rule: no-child-process-execSync
+ *
+ * Prevents usage of child_process.execSync() in favor of safeExecSync() from `@vibe-agent-toolkit/utils/process`
+ *
+ * Why: execSync() uses shell interpreter which enables command injection attacks.
+ * safeExecSync() uses direct spawn (no shell) with 'which' pattern for security.
+ *
+ * Auto-fix: Replaces execSync() with safeExecSync() and adds required import.
+ */
+
+const factory = require('./eslint-rule-factory.cjs');
+const { SAFE_PROCESS_MODULE } = require('./safe-import.cjs');
+
+module.exports = factory({
+  unsafeFn: 'execSync',
+  unsafeModule: 'node:child_process',
+  safeFn: 'safeExecSync',
+  safeModule: SAFE_PROCESS_MODULE,
+  message: 'Use safeExecSync() from {{safeModule}} instead of child_process.execSync() to prevent command injection (security + cross-platform)',
+  // No baked-in exemption: the file that implements safeExecSync() is
+  // repo-specific. Consumers declare it as { exemptFiles: [...] }.
+});

package/eslint/rules/no-command-direct-factory.cjs

@@ -0,0 +1,246 @@
+/**
+ * ESLint Rule Factory - Command Execution Checking
+ *
+ * Single source of truth for:
+ * 1. How commands can be executed (safeExecSync, spawn, execSync, etc.)
+ * 2. How to check those execution patterns
+ * 3. Creating rules that enforce command restrictions
+ *
+ * This module exports both the factory function and helper utilities
+ * so all command-checking rules reference the same execution patterns.
+ */
+
+const { createExemptDirectoryMatcher } = require('./exempt-path-matcher.cjs');
+
+// ============================================================================
+// COMMAND EXECUTION PATTERNS - Single Source of Truth
+// ============================================================================
+// If we add new execution methods (e.g., safeExecAsync), update this list
+// and all dependent rules automatically benefit.
+
+/**
+ * Check if execSync command string starts with the target command
+ *
+ * @param {Object} firstArg - AST node for first argument
+ * @param {string} command - Command to check for (e.g., 'git')
+ * @returns {boolean} True if command matches
+ */
+function commandMatchesExecSync(firstArg, command) {
+  // Check string literals: execSync('git status')
+  if (firstArg.type === 'Literal' && typeof firstArg.value === 'string') {
+    return firstArg.value.startsWith(`${command} `) || firstArg.value === command;
+  }
+
+  // Check template literals: execSync(`git ${args}`)
+  if (firstArg.type === 'TemplateLiteral' && firstArg.quasis.length > 0) {
+    const firstQuasi = firstArg.quasis[0].value.cooked || firstArg.quasis[0].value.raw;
+    return firstQuasi.startsWith(`${command} `) || firstQuasi === command;
+  }
+
+  return false;
+}
+
+/**
+ * Check shell-free command execution (safeExecSync, spawn, etc.)
+ * @private
+ */
+function checkShellFreeExecution(node, context, shouldReport, messageId) {
+  const firstArg = node.arguments[0];
+
+  if (firstArg.type !== 'Literal') {
+    return;
+  }
+
+  const result = shouldReport(node, firstArg);
+  if (result) {
+    context.report({
+      node,
+      messageId,
+      data: typeof result === 'object' ? result : undefined,
+    });
+  }
+}
+
+/**
+ * Check execSync command execution (shell-based)
+ * @private
+ */
+function checkExecSyncExecution(node, context, shouldReport, messageId) {
+  const firstArg = node.arguments[0];
+  const result = shouldReport(node, firstArg, commandMatchesExecSync);
+
+  if (result) {
+    context.report({
+      node,
+      messageId,
+      data: typeof result === 'object' ? result : undefined,
+    });
+  }
+}
+
+/**
+ * Check if function is a shell-free execution method
+ * @private
+ */
+function isShellFreeExecution(functionName) {
+  return (
+    functionName === 'safeExecSync' ||
+    functionName === 'safeExecResult' ||
+    functionName === 'spawn' ||
+    functionName === 'spawnSync'
+  );
+}
+
+/**
+ * Create a CallExpression checker that validates command execution calls
+ *
+ * This centralizes the logic for detecting command execution patterns across
+ * different ESLint rules, eliminating code duplication.
+ *
+ * @param {Object} options - Configuration options
+ * @param {Object} options.context - ESLint rule context
+ * @param {Function} options.shouldReport - Predicate that determines if violation should be reported
+ *   Can return:
+ *   - boolean: true to report with default messageData
+ *   - object: messageData to use for error message
+ *   - falsy: don't report
+ *   Signature: (node, firstArg, matchesExecSync) => boolean | object | falsy
+ * @param {string} options.messageId - ESLint message ID to report
+ * @returns {Object} ESLint CallExpression visitor
+ *
+ * @example
+ * // Simple boolean check:
+ * return {
+ *   CallExpression: createCommandChecker({
+ *     context,
+ *     shouldReport: (node, firstArg) => firstArg.value === 'git',
+ *     messageId: 'noGitDirect',
+ *   }),
+ * };
+ *
+ * @example
+ * // With dynamic messageData:
+ * return {
+ *   CallExpression: createCommandChecker({
+ *     context,
+ *     shouldReport: (node, firstArg) => {
+ *       if (UNIX_COMMANDS.includes(firstArg.value)) {
+ *         return { command: firstArg.value, alternative: getAlt(firstArg.value) };
+ *       }
+ *       return false;
+ *     },
+ *     messageId: 'unixCommand',
+ *   }),
+ * };
+ */
+function createCommandChecker(options) {
+  const { context, shouldReport, messageId } = options;
+
+  return function CallExpression(node) {
+    const functionName = node.callee.name;
+
+    if (node.arguments.length === 0) {
+      return;
+    }
+
+    // Check for shell-free command execution patterns:
+    // - safeExecSync('cmd', ...)
+    // - safeExecResult('cmd', ...)
+    // - spawn('cmd', ...)
+    // - spawnSync('cmd', ...)
+    if (isShellFreeExecution(functionName)) {
+      checkShellFreeExecution(node, context, shouldReport, messageId);
+      return;
+    }
+
+    // Check for execSync('cmd ...') or execSync(`cmd ...`)
+    // Note: execSync is discouraged for security reasons (uses shell)
+    if (functionName === 'execSync') {
+      checkExecSyncExecution(node, context, shouldReport, messageId);
+    }
+  };
+}
+
+// ============================================================================
+// FACTORY FUNCTION - Create Rules for Specific Commands
+// ============================================================================
+
+/**
+ * Factory: Create rule that prevents direct command execution
+ *
+ * @param {Object} config - Rule configuration
+ * @param {string} config.command - Command name to detect (e.g., 'git', 'gh')
+ * @param {string} config.packageName - Package containing wrappers (e.g., '@my-org/git')
+ * @param {string[]} config.availableFunctions - List of available wrapper functions
+ * @param {string} [config.exemptPackage] - Repo-relative directory of the package that
+ *   OWNS the wrappers, e.g. `'packages/git/'`. Matched at a path-segment boundary by
+ *   `exempt-path-matcher.cjs` — NOT as a substring, so `vendor/copy-packages/git/` is
+ *   still linted.
+ * @returns {Object} ESLint rule definition
+ *
+ * @example
+ * // no-git-commands-direct.cjs
+ * const { createNoCommandDirectRule } = require('./no-command-direct-factory.cjs');
+ * module.exports = createNoCommandDirectRule({
+ *   command: 'git',
+ *   packageName: '@my-org/git',
+ *   availableFunctions: ['executeGitCommand()', 'getTreeHash()', 'addNote()'],
+ *   exemptPackage: 'packages/git/',
+ * });
+ */
+
+function createNoCommandDirectRule(config) {
+  const { command, packageName, availableFunctions, exemptPackage } = config;
+
+  const isUnderExemptPackage = createExemptDirectoryMatcher(exemptPackage ? [exemptPackage] : []);
+  const functionList = availableFunctions.join(', ');
+  const messageId = `no${command.charAt(0).toUpperCase()}${command.slice(1)}Direct`;
+
+  return {
+    meta: {
+      type: 'problem',
+      docs: {
+        description: `Enforce use of ${packageName} functions instead of direct ${command} command execution`,
+        category: 'Architecture',
+        recommended: true,
+      },
+      fixable: null, // No auto-fix - requires manual refactoring
+      schema: [],
+      messages: {
+        [messageId]: `Use functions from ${packageName} instead of calling ${command} commands directly. Available functions: ${functionList}.`,
+      },
+    },
+
+    create(context) {
+      // Exempt the package itself (where centralization happens)
+      if (isUnderExemptPackage(context.getFilename())) {
+        return {};
+      }
+
+      return {
+        CallExpression: createCommandChecker({
+          context,
+          shouldReport: (node, firstArg, matchesExecSync) => {
+            // For shell-free execution (safeExecSync, spawn, etc.)
+            if (!matchesExecSync) {
+              return firstArg.value === command;
+            }
+            // For execSync (shell-based)
+            return matchesExecSync(firstArg, command);
+          },
+          messageId,
+        }),
+      };
+    },
+  };
+}
+
+// ============================================================================
+// EXPORTS - Factory + Helpers
+// ============================================================================
+// Export factory as default (for backward compatibility with existing rules)
+// and attach helpers as properties (for new rules like no-unix-shell-commands)
+
+module.exports = createNoCommandDirectRule;
+module.exports.createCommandChecker = createCommandChecker;
+module.exports.commandMatchesExecSync = commandMatchesExecSync;

package/eslint/rules/no-file-url-string-concat.cjs

@@ -0,0 +1,77 @@
+/**
+ * ESLint rule: no-file-url-string-concat
+ *
+ * Disallow constructing `file://` URLs by string concatenation or template
+ * literal interpolation. Filesystem paths on Windows contain `\` and `C:`,
+ * and naively prefixing them with `file://` produces non-canonical URLs that
+ * never compare equal to `import.meta.url`, never round-trip through `new URL`,
+ * and silently break entry-point checks like:
+ *
+ *   if (import.meta.url === `file://${process.argv[1]}`) { ... }   // ❌ Windows
+ *
+ * `pathToFileURL()` is the only correct constructor: it percent-encodes
+ * separators, prepends the right number of slashes for drive letters, and
+ * matches what Node produces for `import.meta.url`.
+ *
+ * @example
+ * // ❌ BAD — Windows-broken
+ * const u = `file://${process.argv[1]}`;
+ * const u2 = 'file://' + somePath;
+ *
+ * // ✅ GOOD
+ * import { pathToFileURL } from 'node:url';
+ * const u = pathToFileURL(process.argv[1]).href;
+ */
+
+'use strict';
+
+const FILE_URL_PREFIX = 'file://';
+
+function literalStartsWithFileUrl(node) {
+  if (!node) return false;
+  if (node.type === 'Literal') {
+    return typeof node.value === 'string' && node.value.startsWith(FILE_URL_PREFIX);
+  }
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0 && node.quasis.length > 0) {
+    const cooked = node.quasis[0].value.cooked;
+    return typeof cooked === 'string' && cooked.startsWith(FILE_URL_PREFIX);
+  }
+  return false;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow constructing `file://` URLs by string concatenation; use `pathToFileURL()` from `node:url`.',
+      category: 'Cross-platform compatibility',
+      recommended: true,
+    },
+    messages: {
+      useFileUrlBuilder:
+        'Do not build `file://` URLs by string concatenation — on Windows, paths contain `\\` and drive letters and produce non-canonical URLs that never compare equal to `import.meta.url`. Use `pathToFileURL(path).href` from `node:url`.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      TemplateLiteral(node) {
+        if (node.expressions.length === 0) return;
+        if (node.quasis.length === 0) return;
+        const cooked = node.quasis[0].value.cooked;
+        if (typeof cooked === 'string' && cooked.startsWith(FILE_URL_PREFIX)) {
+          context.report({ node, messageId: 'useFileUrlBuilder' });
+        }
+      },
+
+      BinaryExpression(node) {
+        if (node.operator !== '+') return;
+        if (literalStartsWithFileUrl(node.left) || literalStartsWithFileUrl(node.right)) {
+          context.report({ node, messageId: 'useFileUrlBuilder' });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-fs-mkdirSync.cjs

@@ -0,0 +1,23 @@
+/**
+ * ESLint rule: no-fs-mkdirSync
+ *
+ * Prevents usage of fs.mkdirSync() in favor of mkdirSyncReal() from `@vibe-agent-toolkit/utils/fs`
+ *
+ * Why: After mkdirSync(), the path might not match what the filesystem uses on Windows.
+ * mkdirSyncReal() returns the real (normalized) path to handle 8.3 short name issues.
+ *
+ * Auto-fix: Replaces fs.mkdirSync() with mkdirSyncReal() and adds required import.
+ */
+
+const factory = require('./eslint-rule-factory.cjs');
+const { SAFE_FS_MODULE } = require('./safe-import.cjs');
+
+module.exports = factory({
+  unsafeFn: 'mkdirSync',
+  unsafeModule: 'node:fs',
+  safeFn: 'mkdirSyncReal',
+  safeModule: SAFE_FS_MODULE,
+  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: [...] }.
+});

package/eslint/rules/no-fs-promises-cp.cjs

@@ -0,0 +1,36 @@
+/**
+ * ESLint rule: no-fs-promises-cp
+ *
+ * Prevents usage of cp() from node:fs/promises in favor of cpSync() from node:fs.
+ *
+ * Why: Node 22's async cp() with { recursive: true } silently drops files in
+ * nested directories (observed with .mjs files in deeply nested paths).
+ * The files are simply missing from the destination with no error thrown.
+ * cpSync() from node:fs does not have this bug and works correctly across
+ * all Node versions (22, 24+).
+ *
+ * This is a known Node.js issue, not a VAT bug. Until the Node.js team fixes
+ * the async cp() implementation, cpSync() is the safe default.
+ *
+ * If you need async cp() for a specific use case and have verified it works
+ * correctly with your file structure, disable this rule with an eslint-disable
+ * comment explaining why async is required.
+ *
+ * Auto-fix: Replaces cp() with cpSync() and updates import from node:fs/promises to node:fs.
+ */
+
+const factory = require('./eslint-rule-factory.cjs');
+
+module.exports = factory({
+  unsafeFn: 'cp',
+  unsafeModule: 'node:fs/promises',
+  safeFn: 'cpSync',
+  safeModule: 'node:fs',
+  // `{{safeModule}}` resolves to `node:fs` unless overridden. A builtin always
+  // resolves, so this rule has no seam problem — it takes the option only
+  // because it shares the factory.
+  message:
+    '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.',
+});

package/eslint/rules/no-fs-realpathSync.cjs

@@ -0,0 +1,23 @@
+/**
+ * ESLint rule: no-fs-realpathSync
+ *
+ * Prevents usage of fs.realpathSync() in favor of normalizePath() from `@vibe-agent-toolkit/utils/fs`
+ *
+ * Why: realpathSync() doesn't consistently resolve Windows 8.3 short paths across Node versions.
+ * normalizePath() uses realpathSync.native() with fallbacks for better cross-platform compatibility.
+ *
+ * Auto-fix: Replaces fs.realpathSync() with normalizePath() and adds required import.
+ */
+
+const factory = require('./eslint-rule-factory.cjs');
+const { SAFE_FS_MODULE } = require('./safe-import.cjs');
+
+module.exports = factory({
+  unsafeFn: 'realpathSync',
+  unsafeModule: 'node:fs',
+  safeFn: 'normalizePath',
+  safeModule: SAFE_FS_MODULE,
+  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: [...] }.
+});