@vibe-agent-toolkit/utils 0.1.41 → 0.1.42

package/eslint/rules/no-hardcoded-path-split.cjs

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ *
+ * This rule is smart enough to detect when paths are already normalized:
+ * - Inline: toForwardSlash(path).split('/') ✅
+ * - Variable: const normalized = toForwardSlash(path); normalized.split('/') ✅
+ *
+ * @example
+ * // ❌ BAD - breaks on Windows (paths use backslashes)
+ * const filename = filePath.split('/').pop();
+ * const parts = filePath.split('\\');
+ *
+ * // ✅ GOOD - use path.basename() for filename
+ * import { basename } from 'node:path';
+ * const filename = basename(filePath);
+ *
+ * // ✅ GOOD - normalize then split (inline)
+ * import { toForwardSlash } from '@vibe-agent-toolkit/utils/path';
+ * const parts = toForwardSlash(filePath).split('/');
+ *
+ * // ✅ GOOD - normalize then split (variable)
+ * const normalizedPath = toForwardSlash(filePath);
+ * const parts = normalizedPath.split('/');
+ */
+
+const {
+  SAFE_MODULE_ONLY_SCHEMA,
+  SAFE_PATH_MODULE,
+  resolveSafeModule,
+} = require('./safe-import.cjs');
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow splitting strings by hardcoded path separators',
+      category: 'Cross-platform compatibility',
+      recommended: true,
+    },
+    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.',
+    },
+    schema: [SAFE_MODULE_ONLY_SCHEMA],
+  },
+
+  create(context) {
+    const reportData = { safeModule: resolveSafeModule(context, SAFE_PATH_MODULE) };
+    // Track variables that were assigned from toForwardSlash()
+    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'
+        ) {
+          normalizedVariables.add(node.id.name);
+        }
+      },
+
+      CallExpression(node) {
+        // Check if this is a .split() call
+        if (
+          node.callee.type !== 'MemberExpression' ||
+          node.callee.property.type !== 'Identifier' ||
+          node.callee.property.name !== 'split'
+        ) {
+          return;
+        }
+
+        // Check if the argument is a hardcoded path separator
+        const firstArg = node.arguments[0];
+        if (!firstArg) {
+          return;
+        }
+
+        // Check for literal '/' or '\\'
+        const isPathSeparator =
+          (firstArg.type === 'Literal' &&
+            typeof firstArg.value === 'string' &&
+            (firstArg.value === '/' || firstArg.value === '\\')) ||
+          // Check for regex like /[/\\]/ or /\//
+          (firstArg.type === 'Literal' &&
+            firstArg.value instanceof RegExp &&
+            (firstArg.value.source.includes('/') ||
+              firstArg.value.source.includes('\\\\')));
+
+        if (!isPathSeparator) {
+          return;
+        }
+
+        // Check if this is a safe usage (normalized path)
+        const object = node.callee.object;
+
+        // Case 1: Inline normalization - toForwardSlash(...).split('/')
+        if (
+          object.type === 'CallExpression' &&
+          object.callee.type === 'Identifier' &&
+          object.callee.name === 'toForwardSlash'
+        ) {
+          return; // Safe - normalized inline
+        }
+
+        // Case 2: Variable that was normalized earlier
+        if (
+          object.type === 'Identifier' &&
+          normalizedVariables.has(object.name)
+        ) {
+          return; // Safe - variable was normalized
+        }
+
+        // Case 3: Check if variable name suggests normalization
+        // Common patterns: normalizedPath, unixPath, forwardSlashPath
+        if (
+          object.type === 'Identifier' &&
+          (object.name.toLowerCase().includes('normalized') ||
+           object.name.toLowerCase().includes('unix') ||
+           object.name.toLowerCase().includes('forward'))
+        ) {
+          return; // Safe - variable naming suggests normalization
+        }
+
+        // Not safe - report the issue
+        context.report({
+          node,
+          messageId: 'noHardcodedSplit',
+          data: reportData,
+        });
+      },
+    };
+  },
+};

package/eslint/rules/no-manual-path-normalize.cjs

@@ -0,0 +1,161 @@
+/**
+ * ESLint rule to enforce using toForwardSlash() instead of manual normalization
+ *
+ * Detects manual path normalization patterns and suggests using the utility function.
+ *
+ * @example
+ * // ❌ BAD - manual normalization
+ * const normalized = relativePath.split(path.sep).join('/');
+ * const normalized = somePath.split('\\').join('/');
+ *
+ * // ✅ GOOD - use utility function
+ * import { toForwardSlash } from '@vibe-agent-toolkit/utils/path';
+ * const normalized = toForwardSlash(relativePath);
+ */
+
+const {
+  DEAD_UNSAFE_IMPORT,
+  DEAD_UNSAFE_IMPORT_MESSAGE,
+  reportDeadUnsafeImports,
+} = require('./dead-import.cjs');
+const {
+  SAFE_MODULE_ONLY_SCHEMA,
+  SAFE_PATH_MODULE,
+  insertAboveWithComments,
+  isNameAlreadyBound,
+  resolveSafeModule,
+} = require('./safe-import.cjs');
+
+const SAFE_FN = 'toForwardSlash';
+const PATH_MODULES = new Set(['node:path', 'path']);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow manual path normalization patterns',
+      category: 'Cross-platform compatibility',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      useToForwardSlash:
+        'Use toForwardSlash() from {{safeModule}} instead of manual path normalization. ' +
+        'Manual normalization is error-prone and less maintainable.',
+      [DEAD_UNSAFE_IMPORT]: DEAD_UNSAFE_IMPORT_MESSAGE,
+    },
+    schema: [SAFE_MODULE_ONLY_SCHEMA],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode();
+    const targetModule = resolveSafeModule(context, SAFE_PATH_MODULE);
+    // Seeded from SCOPE: a file that already imports `toForwardSlash` from the
+    // barrel must have the call rewritten WITHOUT gaining a second binding of
+    // the same name — that is a SyntaxError. See `safe-import.cjs`.
+    let hasToForwardSlashImport = isNameAlreadyBound(sourceCode, SAFE_FN);
+    // Never mutated — the dead-import leg must not be armed by a flag that a
+    // suppressed report's `fix()` can spend. See `dead-import.cjs`.
+    const safeBoundInSource = hasToForwardSlashImport;
+    let utilsImportNode = null;
+    // `path.sep` is the last `path.*` reference in plenty of files, and
+    // `toForwardSlash(raw)` consumes it — leaving the same dead `node:path`
+    // binding the `safePath` rules used to leave.
+    const pathImportNodes = [];
+
+    return {
+      'Program:exit'() {
+        reportDeadUnsafeImports(context, sourceCode, pathImportNodes, safeBoundInSource);
+      },
+
+      ImportDeclaration(node) {
+        if (PATH_MODULES.has(node.source.value)) {
+          pathImportNodes.push(node);
+        }
+        if (node.source.value === targetModule) {
+          utilsImportNode = node;
+          for (const spec of node.specifiers) {
+            if (spec.type === 'ImportSpecifier' && spec.imported.name === SAFE_FN) {
+              hasToForwardSlashImport = true;
+            }
+          }
+        }
+      },
+
+      CallExpression(node) {
+        // Check for .split(...).join('/') pattern
+        if (
+          node.callee.type === 'MemberExpression' &&
+          node.callee.property.name === 'join' &&
+          node.arguments.length === 1 &&
+          node.arguments[0].type === 'Literal' &&
+          node.arguments[0].value === '/'
+        ) {
+          // Check if the object is a .split() call
+          const splitCall = node.callee.object;
+          if (
+            splitCall.type === 'CallExpression' &&
+            splitCall.callee.type === 'MemberExpression' &&
+            splitCall.callee.property.name === 'split' &&
+            splitCall.arguments.length === 1
+          ) {
+            const splitArg = splitCall.arguments[0];
+
+            // Check if splitting by path.sep, '\\', or '\\\\'
+            const isSplittingByPathSep =
+              (splitArg.type === 'MemberExpression' &&
+                splitArg.object.name === 'path' &&
+                splitArg.property.name === 'sep') ||
+              (splitArg.type === 'Literal' && (splitArg.value === '\\' || splitArg.value === '\\\\'));
+
+            if (isSplittingByPathSep) {
+              const variableBeingSplit = splitCall.callee.object;
+
+              context.report({
+                node,
+                messageId: 'useToForwardSlash',
+                data: { safeModule: targetModule },
+                fix(fixer) {
+                  const fixes = [];
+
+                  // Replace the entire .split(...).join('/') with toForwardSlash(...)
+                  const originalVar = sourceCode.getText(variableBeingSplit);
+                  fixes.push(fixer.replaceText(node, `${SAFE_FN}(${originalVar})`));
+
+                  // Add import if needed
+                  if (!hasToForwardSlashImport) {
+                    if (utilsImportNode) {
+                      // Add to existing utils import
+                      const lastSpecifier = utilsImportNode.specifiers.at(-1);
+                      fixes.push(fixer.insertTextAfter(lastSpecifier, `, ${SAFE_FN}`));
+                    } else {
+                      // Create new import at the top
+                      const firstNode = sourceCode.ast.body[0];
+                      const newImport = `import { ${SAFE_FN} } from '${targetModule}';\n`;
+                      fixes.push(insertAboveWithComments(fixer, sourceCode, firstNode, newImport));
+                    }
+                    // NOT latched. The comment here used to claim that without a
+                    // `hasToForwardSlashImport = true` a second occurrence would
+                    // insert the import twice; an adversarial run could not
+                    // reproduce that at any occurrence count. It cannot happen:
+                    // both reports insert identical text at the identical anchor,
+                    // so the ranges coincide and ESLint applies one and drops the
+                    // other as overlapping.
+                    //
+                    // Latching it is not free, either. ESLint runs `fix()` for a
+                    // SUPPRESSED problem before the `eslint-disable` filter
+                    // discards it, so the first report could spend the flag and
+                    // then be thrown away — leaving later occurrences rewritten
+                    // to a `toForwardSlash` nothing imports.
+                  }
+
+                  return fixes;
+                },
+              });
+            }
+          }
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-os-tmpdir.cjs

@@ -0,0 +1,24 @@
+/**
+ * ESLint rule: no-os-tmpdir
+ *
+ * Prevents usage of os.tmpdir() in favor of normalizedTmpdir() from `@vibe-agent-toolkit/utils/fs`
+ *
+ * Why: os.tmpdir() returns Windows 8.3 short paths (RUNNER~1) which cause module loading
+ * errors when paths are passed to child processes or used with import statements.
+ *
+ * Auto-fix: Replaces os.tmpdir() with normalizedTmpdir() and adds required import.
+ */
+
+const factory = require('./eslint-rule-factory.cjs');
+const { SAFE_FS_MODULE } = require('./safe-import.cjs');
+
+module.exports = factory({
+  unsafeFn: 'tmpdir',
+  unsafeModule: 'node:os',
+  safeFn: 'normalizedTmpdir',
+  safeModule: SAFE_FS_MODULE,
+  message: 'Use normalizedTmpdir() from {{safeModule}} instead of os.tmpdir() for Windows compatibility (prevents 8.3 short name issues like RUNNER~1)',
+  // No baked-in exemption: the file that implements normalizedTmpdir() is
+  // repo-specific. Consumers declare it as { exemptFiles: [...] }.
+  checkMemberExpression: true, // Catch os.tmpdir() pattern
+});

package/eslint/rules/no-path-join.cjs

@@ -0,0 +1,14 @@
+/**
+ * ESLint rule: no-path-join
+ *
+ * Bans path.join() from node:path. Use safePath.join() from `@vibe-agent-toolkit/utils/path`.
+ * safePath.join() wraps path.join() + toForwardSlash() to prevent Windows backslash bugs.
+ */
+const factory = require('./path-function-rule-factory.cjs');
+
+module.exports = factory({
+  unsafeFn: 'join',
+  message:
+    'Use safePath.join() from {{safeModule}} instead of path.join(). ' +
+    'path.join() returns backslashes on Windows, causing Map key mismatches and path comparison bugs.',
+});

package/eslint/rules/no-path-operations-in-comparisons.cjs

@@ -0,0 +1,148 @@
+/**
+ * ESLint rule to enforce normalizing path operations before string comparisons
+ *
+ * path.relative(), path.dirname(), path.basename(), path.join() return OS-specific separators.
+ * When comparing with literal strings (especially in markdown), normalize to forward slashes.
+ *
+ * @example
+ * // ❌ BAD - path.relative() returns backslashes on Windows
+ * const relativePath = path.relative(baseDir, filePath);
+ * if (content.includes(relativePath)) { ... }  // FAILS on Windows!
+ *
+ * // ✅ GOOD - normalize before comparison
+ * import { toForwardSlash } from '@vibe-agent-toolkit/utils/path';
+ * const relativePath = toForwardSlash(path.relative(baseDir, filePath));
+ * if (content.includes(relativePath)) { ... }
+ */
+
+const {
+  SAFE_MODULE_ONLY_SCHEMA,
+  SAFE_PATH_MODULE,
+  resolveSafeModule,
+} = require('./safe-import.cjs');
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow using path operations directly in string comparisons',
+      category: 'Cross-platform compatibility',
+      recommended: true,
+    },
+    messages: {
+      normalizePathOperation:
+        'Wrap path.{{method}}() with toForwardSlash() from {{safeModule}} before using in string operations. ' +
+        'Path operations return OS-specific separators that fail in cross-platform comparisons.',
+    },
+    schema: [SAFE_MODULE_ONLY_SCHEMA],
+  },
+
+  create(context) {
+    const safeModule = resolveSafeModule(context, SAFE_PATH_MODULE);
+    // Path methods that return paths with OS-specific separators
+    const pathMethodsReturningPaths = new Set([
+      'relative',
+      'dirname',
+      'basename',
+      'join',
+      'resolve',
+      'normalize',
+    ]);
+
+    // String methods that compare/search strings
+    const stringComparisonMethods = new Set([
+      'includes',
+      'indexOf',
+      'lastIndexOf',
+      'startsWith',
+      'endsWith',
+      'split',
+      'replace',
+      'replaceAll',
+      'match',
+      'search',
+    ]);
+
+    // Track variables that hold unwrapped path operation results
+    const unwrappedPathVariables = new Set();
+    const wrappedPathVariables = new Set();
+
+    // If `node` is a `path.<method>(...)` call where method returns
+    // OS-specific separators, return that method name. Otherwise undefined.
+    const unnormalizedPathCallMethod = (node) =>
+      node?.type === 'CallExpression' &&
+      node.callee.type === 'MemberExpression' &&
+      node.callee.object.type === 'Identifier' &&
+      node.callee.object.name === 'path' &&
+      pathMethodsReturningPaths.has(node.callee.property.name)
+        ? node.callee.property.name
+        : undefined;
+
+    const isStringComparisonCall = (node) =>
+      node.callee.type === 'MemberExpression' &&
+      stringComparisonMethods.has(node.callee.property.name);
+
+    const reportPathArgument = (arg) => {
+      const method = unnormalizedPathCallMethod(arg);
+      if (method !== undefined) {
+        context.report({ node: arg, messageId: 'normalizePathOperation', data: { method, safeModule } });
+        return;
+      }
+      if (
+        arg.type === 'Identifier' &&
+        unwrappedPathVariables.has(arg.name) &&
+        !wrappedPathVariables.has(arg.name)
+      ) {
+        context.report({
+          node: arg,
+          messageId: 'normalizePathOperation',
+          data: { method: 'operation', safeModule },
+        });
+      }
+    };
+
+    const reportTemplateLiteralExpressions = (templateLiteral) => {
+      for (const expr of templateLiteral.expressions) {
+        const method = unnormalizedPathCallMethod(expr);
+        if (method !== undefined) {
+          context.report({
+            node: expr,
+            messageId: 'normalizePathOperation',
+            data: { method, safeModule },
+          });
+        }
+      }
+    };
+
+    return {
+      VariableDeclarator(node) {
+        if (!node.init || node.id.type !== 'Identifier') return;
+
+        if (unnormalizedPathCallMethod(node.init) !== undefined) {
+          unwrappedPathVariables.add(node.id.name);
+          return;
+        }
+
+        // Initializer is `toForwardSlash(<expr>)` — treat the variable as wrapped.
+        if (
+          node.init.type === 'CallExpression' &&
+          node.init.callee.type === 'Identifier' &&
+          node.init.callee.name === 'toForwardSlash' &&
+          node.init.arguments.length === 1
+        ) {
+          wrappedPathVariables.add(node.id.name);
+        }
+      },
+
+      CallExpression(node) {
+        if (!isStringComparisonCall(node)) return;
+        for (const arg of node.arguments) {
+          reportPathArgument(arg);
+          if (arg.type === 'TemplateLiteral') {
+            reportTemplateLiteralExpressions(arg);
+          }
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-path-relative.cjs

@@ -0,0 +1,14 @@
+/**
+ * ESLint rule: no-path-relative
+ *
+ * Bans path.relative() from node:path. Use safePath.relative() from `@vibe-agent-toolkit/utils/path`.
+ * safePath.relative() wraps path.relative() + toForwardSlash() to prevent Windows backslash bugs.
+ */
+const factory = require('./path-function-rule-factory.cjs');
+
+module.exports = factory({
+  unsafeFn: 'relative',
+  message:
+    'Use safePath.relative() from {{safeModule}} instead of path.relative(). ' +
+    'path.relative() returns backslashes on Windows, causing Map key mismatches and path comparison bugs.',
+});

package/eslint/rules/no-path-resolve.cjs

@@ -0,0 +1,14 @@
+/**
+ * ESLint rule: no-path-resolve
+ *
+ * Bans path.resolve() from node:path. Use safePath.resolve() from `@vibe-agent-toolkit/utils/path`.
+ * safePath.resolve() wraps path.resolve() + toForwardSlash() to prevent Windows backslash bugs.
+ */
+const factory = require('./path-function-rule-factory.cjs');
+
+module.exports = factory({
+  unsafeFn: 'resolve',
+  message:
+    'Use safePath.resolve() from {{safeModule}} instead of path.resolve(). ' +
+    'path.resolve() returns backslashes on Windows, causing Map key mismatches and path comparison bugs.',
+});

package/eslint/rules/no-path-sep-in-strings.cjs

@@ -0,0 +1,130 @@
+/**
+ * ESLint rule to disallow using path.sep in string operations
+ *
+ * path.sep is '\\' on Windows and '/' on Unix, which causes cross-platform issues
+ * when used in string operations. Use toForwardSlash() to normalize paths instead.
+ *
+ * @example
+ * // ❌ BAD - path.sep varies by platform
+ * const parts = filePath.split(path.sep);
+ * if (filePath.includes(path.sep)) { ... }
+ *
+ * // ✅ GOOD - normalize then split
+ * import { toForwardSlash } from '@vibe-agent-toolkit/utils/path';
+ * const parts = toForwardSlash(filePath).split('/');
+ * if (toForwardSlash(filePath).includes('/')) { ... }
+ */
+
+const {
+  SAFE_MODULE_ONLY_SCHEMA,
+  SAFE_PATH_MODULE,
+  resolveSafeModule,
+} = require('./safe-import.cjs');
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow using path.sep in string operations',
+      category: 'Cross-platform compatibility',
+      recommended: true,
+    },
+    messages: {
+      noPathSep:
+        'Avoid using path.sep in string operations (split, includes, indexOf, etc.). ' +
+        'Use toForwardSlash() from {{safeModule}} to normalize paths to forward slashes first.',
+    },
+    schema: [SAFE_MODULE_ONLY_SCHEMA],
+  },
+
+  create(context) {
+    const reportData = { safeModule: resolveSafeModule(context, SAFE_PATH_MODULE) };
+    // String methods that take a separator/search argument
+    const stringMethodsWithSeparator = new Set([
+      'split',
+      'includes',
+      'indexOf',
+      'lastIndexOf',
+      'startsWith',
+      'endsWith',
+      'replace',
+      'replaceAll',
+    ]);
+
+    return {
+      CallExpression(node) {
+        // Check if this is a string method call
+        if (
+          node.callee.type !== 'MemberExpression' ||
+          node.callee.property.type !== 'Identifier' ||
+          !stringMethodsWithSeparator.has(node.callee.property.name)
+        ) {
+          return;
+        }
+
+        // Check if any argument is path.sep
+        const hasPathSepArg = node.arguments.some(
+          (arg) =>
+            arg.type === 'MemberExpression' &&
+            arg.object.type === 'Identifier' &&
+            arg.object.name === 'path' &&
+            arg.property.type === 'Identifier' &&
+            arg.property.name === 'sep',
+        );
+
+        if (hasPathSepArg) {
+          context.report({
+            node,
+            messageId: 'noPathSep',
+            data: reportData,
+          });
+        }
+      },
+
+      // Also catch template literals and binary expressions using path.sep
+      TemplateLiteral(node) {
+        const hasPathSep = node.expressions.some(
+          (expr) =>
+            expr.type === 'MemberExpression' &&
+            expr.object.type === 'Identifier' &&
+            expr.object.name === 'path' &&
+            expr.property.type === 'Identifier' &&
+            expr.property.name === 'sep',
+        );
+
+        if (hasPathSep) {
+          context.report({
+            node,
+            messageId: 'noPathSep',
+            data: reportData,
+          });
+        }
+      },
+
+      BinaryExpression(node) {
+        // Check for string concatenation with path.sep
+        if (node.operator === '+') {
+          const hasPathSep =
+            (node.left.type === 'MemberExpression' &&
+              node.left.object.type === 'Identifier' &&
+              node.left.object.name === 'path' &&
+              node.left.property.type === 'Identifier' &&
+              node.left.property.name === 'sep') ||
+            (node.right.type === 'MemberExpression' &&
+              node.right.object.type === 'Identifier' &&
+              node.right.object.name === 'path' &&
+              node.right.property.type === 'Identifier' &&
+              node.right.property.name === 'sep');
+
+          if (hasPathSep) {
+            context.report({
+              node,
+              messageId: 'noPathSep',
+              data: reportData,
+            });
+          }
+        }
+      },
+    };
+  },
+};