@vibe-agent-toolkit/utils 0.1.41 → 0.1.42

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

@@ -0,0 +1,139 @@
+/**
+ * ESLint rule to enforce using toForwardSlash() before path.startsWith()
+ *
+ * Cross-platform path comparisons fail on Windows when mixing backslashes and forward slashes.
+ * This rule enforces using toForwardSlash() from `@vibe-agent-toolkit/utils/path` for consistent behavior.
+ *
+ * @example
+ * // ❌ BAD - fails on Windows
+ * if (pluginDir.startsWith(marketplaceDir)) { ... }
+ *
+ * // ✅ GOOD - works cross-platform
+ * import { toForwardSlash } from '@vibe-agent-toolkit/utils/path';
+ * const normalizedPlugin = toForwardSlash(pluginDir);
+ * const normalizedMarketplace = toForwardSlash(marketplaceDir);
+ * if (normalizedPlugin.startsWith(normalizedMarketplace)) { ... }
+ */
+
+/**
+ * Check if the comparison argument is a URL scheme or absolute path indicator
+ * These don't need normalization: 'http://', 'https://', 'file://', '/', '#'
+ */
+function isUrlSchemeOrAbsoluteCheck(node) {
+  if (node.arguments.length === 0 || node.arguments[0]?.type !== 'Literal') {
+    return false;
+  }
+
+  const compareValue = node.arguments[0].value;
+  if (typeof compareValue !== 'string') {
+    return false;
+  }
+
+  return (
+    compareValue === '/' ||
+    compareValue === '#' ||
+    compareValue.startsWith('http://') ||
+    compareValue.startsWith('https://') ||
+    compareValue.startsWith('file://')
+  );
+}
+
+/**
+ * Check if a variable name contains path-related keywords
+ */
+function hasPathKeyword(name) {
+  const lowerName = name.toLowerCase();
+  return (
+    lowerName.includes('path') ||
+    lowerName.includes('dir') ||
+    lowerName.includes('file') ||
+    lowerName.includes('location')
+  );
+}
+
+/**
+ * Check if a variable name indicates it's already normalized
+ */
+function isNormalizedVariable(name) {
+  return name.toLowerCase().startsWith('normalized');
+}
+
+const {
+  SAFE_MODULE_ONLY_SCHEMA,
+  SAFE_PATH_MODULE,
+  resolveSafeModule,
+} = require('./safe-import.cjs');
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow direct path.startsWith() without normalization',
+      category: 'Cross-platform compatibility',
+      recommended: true,
+    },
+    messages: {
+      useNormalizeHelper:
+        'Use toForwardSlash() from {{safeModule}} before path.startsWith() for cross-platform compatibility. ' +
+        'Direct string comparison fails on Windows with mixed separators.',
+    },
+    schema: [SAFE_MODULE_ONLY_SCHEMA],
+  },
+
+  create(context) {
+    const reportData = { safeModule: resolveSafeModule(context, SAFE_PATH_MODULE) };
+    return {
+      CallExpression(node) {
+        // Check if this is a .startsWith() call
+        if (
+          node.callee.type !== 'MemberExpression' ||
+          node.callee.property.type !== 'Identifier' ||
+          node.callee.property.name !== 'startsWith'
+        ) {
+          return;
+        }
+
+        // Skip URL scheme and absolute path checks
+        if (isUrlSchemeOrAbsoluteCheck(node)) {
+          return;
+        }
+
+        const objectNode = node.callee.object;
+
+        // Check identifier variables (e.g., pluginPath.startsWith(...))
+        if (objectNode.type === 'Identifier') {
+          const varName = objectNode.name;
+
+          if (isNormalizedVariable(varName)) {
+            return;
+          }
+
+          if (hasPathKeyword(varName)) {
+            context.report({
+              node,
+              messageId: 'useNormalizeHelper',
+              data: reportData,
+            });
+          }
+        }
+
+        // Check member expressions (e.g., resource.filePath.startsWith(...))
+        if (objectNode.type === 'MemberExpression' && objectNode.property.type === 'Identifier') {
+          const propName = objectNode.property.name;
+
+          if (isNormalizedVariable(propName)) {
+            return;
+          }
+
+          if (hasPathKeyword(propName)) {
+            context.report({
+              node,
+              messageId: 'useNormalizeHelper',
+              data: reportData,
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-test-scoped-functions.cjs

@@ -0,0 +1,134 @@
+/**
+ * ESLint rule to disallow function declarations inside test blocks
+ *
+ * Catches the SonarQube code smell: "Move function to the outer scope" (S1515)
+ * Functions defined inside describe/it/test blocks should be moved to module scope
+ * for better reusability and to prevent the code smell.
+ *
+ * Why: Helper functions inside test blocks are harder to:
+ * - Reuse across test files
+ * - Test independently
+ * - Understand (hidden inside blocks)
+ * - Maintain (scattered throughout test suites)
+ *
+ * @example
+ * // BAD - Function inside describe block
+ * describe('validate command', () => {
+ *   function setupWorkingDirectoryMocks(configDir, treeHash) {
+ *     // ... setup code
+ *   }
+ *
+ *   it('should work', () => {
+ *     setupWorkingDirectoryMocks('/path', 'abc123');
+ *   });
+ * });
+ *
+ * // GOOD - Function at module scope
+ * function setupWorkingDirectoryMocks(configDir, treeHash) {
+ *   // ... setup code
+ * }
+ *
+ * describe('validate command', () => {
+ *   it('should work', () => {
+ *     setupWorkingDirectoryMocks('/path', 'abc123');
+ *   });
+ * });
+ */
+
+const TEST_BLOCK_PATTERN = /^(describe|it|test|before|after|beforeEach|afterEach|beforeAll|afterAll)$/i;
+
+/**
+ * Check if a node is a test-related call expression
+ * (describe, it, test, beforeEach, afterEach, beforeAll, afterAll, etc.)
+ */
+function isTestBlock(node) {
+  if (node.type !== 'CallExpression') {
+    return false;
+  }
+
+  const callee = node.callee;
+
+  // Direct calls: describe(), it(), test(), etc.
+  if (callee.type === 'Identifier') {
+    return TEST_BLOCK_PATTERN.test(callee.name);
+  }
+
+  // Member calls: test.describe(), test.it(), etc. (Playwright)
+  if (
+    callee.type === 'MemberExpression' &&
+    callee.property.type === 'Identifier'
+  ) {
+    return TEST_BLOCK_PATTERN.test(callee.property.name);
+  }
+
+  return false;
+}
+
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow function declarations inside test blocks (SonarQube S1515)',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    messages: {
+      moveToModuleScope:
+        'Move function \'{{name}}\' to module scope (outside describe/it/test blocks). ' +
+        'Helper functions inside test blocks are harder to reuse and maintain. ' +
+        'This matches SonarQube rule S1515 (Intentionality/Maintainability).',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allowedFunctionNames: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Function names that are allowed inside test blocks',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+
+  create(context) {
+    let testBlockDepth = 0;
+    const allowedNames = new Set(
+      context.options[0]?.allowedFunctionNames || []
+    );
+
+    return {
+      CallExpression(node) {
+        if (isTestBlock(node)) {
+          testBlockDepth++;
+        }
+      },
+
+      'CallExpression:exit'(node) {
+        if (isTestBlock(node)) {
+          testBlockDepth--;
+        }
+      },
+
+      FunctionDeclaration(node) {
+        if (testBlockDepth > 0) {
+          const functionName = node.id?.name || '<anonymous>';
+
+          if (allowedNames.has(functionName)) {
+            return;
+          }
+
+          context.report({
+            node,
+            messageId: 'moveToModuleScope',
+            data: {
+              name: functionName,
+            },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-unix-shell-commands.cjs

@@ -0,0 +1,152 @@
+/**
+ * ESLint rule: no-unix-shell-commands
+ *
+ * Prevents usage of Unix-specific commands in exec/spawn calls that break cross-platform compatibility.
+ *
+ * Why: Commands like 'tar', 'ls', 'touch', 'grep' are Unix-specific and fail on Windows.
+ * Use cross-platform alternatives: Node.js fs APIs, or cross-platform npm packages.
+ *
+ * Detects Unix commands in:
+ * - safeExecSync('tar', ...)
+ * - safeExecResult('ls', ...)
+ * - spawn('grep', ...)
+ * - spawnSync('find', ...)
+ * - execSync('tar xzf file.tar.gz')
+ */
+
+const { isTestFile } = require('./exempt-path-matcher.cjs');
+
+/**
+ * Unix-specific commands that should not be used
+ * Categorized for better documentation
+ */
+const UNIX_COMMANDS = {
+  // File operations
+  fileOps: ['ls', 'touch', 'rm', 'mv', 'cp', 'ln', 'chmod', 'chown', 'chgrp'],
+
+  // Archiving/compression
+  archive: ['tar', 'gzip', 'gunzip', 'zip', 'unzip', 'bzip2'],
+
+  // Text processing
+  // Note on `echo`: on Windows `echo` is a shell builtin (cmd.exe / PowerShell),
+  // not an .EXE on PATH — except inside Git Bash's MSYS, where `/usr/bin/echo.exe`
+  // ships from coreutils. So `safeExecSync('echo', …)` works only when the
+  // launching shell happens to have `C:\Program Files\Git\usr\bin` on PATH
+  // (e.g., Git Bash, or GitHub-hosted windows-latest runners that add it).
+  // Use Node (`safeExecSync('node', [echoFixturePath, …])`) instead, pointing at
+  // a committed one-line script fixture that prints its argv.
+  text: ['grep', 'sed', 'awk', 'cat', 'head', 'tail', 'wc', 'cut', 'sort', 'uniq', 'tr', 'echo'],
+
+  // File searching
+  search: ['find', 'locate'],
+
+  // System info
+  system: ['ps', 'top', 'kill', 'df', 'du', 'who', 'uname'],
+
+  // Networking
+  network: ['curl', 'wget', 'ping', 'netstat', 'ifconfig'],
+
+  // Shell utilities
+  shell: ['sh', 'bash', 'zsh', 'source', 'export', 'env'],
+};
+
+// Flatten to single array for easier checking
+const ALL_UNIX_COMMANDS = Object.values(UNIX_COMMANDS).flat();
+
+/**
+ * Get cross-platform alternatives for common Unix commands
+ */
+function getAlternatives(command) {
+  const alternatives = {
+    ls: 'fs.readdirSync() or Glob tool',
+    touch: 'fs.writeFileSync(path, "") or fs.utimesSync()',
+    rm: 'fs.unlinkSync() or fs.rmSync()',
+    mv: 'fs.renameSync()',
+    cp: 'fs.copyFileSync()',
+    cat: 'fs.readFileSync() or Read tool',
+    grep: 'Grep tool or string.includes()',
+    find: 'Glob tool or fs.readdirSync() with recursion',
+    tar: 'tar-fs or tar-stream npm package',
+    gzip: 'zlib module',
+    chmod: 'fs.chmodSync()',
+    chown: 'fs.chownSync()',
+    head: 'Read tool with limit parameter',
+    tail: 'Read tool with offset parameter',
+    sed: 'Edit tool or string.replace()',
+    awk: 'string.split() and array methods',
+    echo: 'safeExecSync(\'node\', [echoFixturePath, ...args]) using a committed script fixture that prints its argv — `echo` is only present on Windows when Git\'s coreutils are on PATH',
+  };
+
+   
+  return alternatives[command] || 'Node.js fs module or cross-platform npm package';
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Prevent Unix-specific commands that break Windows compatibility',
+      category: 'Cross-Platform',
+      recommended: true,
+    },
+    fixable: null, // No auto-fix - requires manual refactoring
+    schema: [],
+    messages: {
+      noUnixCommand:
+        'Unix-specific command "{{command}}" breaks Windows compatibility. Use: {{alternative}}',
+    },
+  },
+
+  create(context) {
+    // Exempt test files that specifically test Unix command detection.
+    // Anchored on the basename by `exempt-path-matcher.cjs` — a substring check
+    // also exempted `example.test.ts.bak`, a `.test.ts-helpers/` directory, and
+    // `tsconfig.test.json` (via the `.test.js` spelling).
+    if (isTestFile(context.getFilename())) {
+      return {};
+    }
+
+    const factory = require('./no-command-direct-factory.cjs');
+    const { createCommandChecker } = factory;
+
+    return {
+      CallExpression: createCommandChecker({
+        context,
+        shouldReport: (node, firstArg, matchesExecSync) => {
+          // For shell-free execution (safeExecSync, spawn, etc.)
+          if (!matchesExecSync) {
+            if (typeof firstArg.value === 'string' && ALL_UNIX_COMMANDS.includes(firstArg.value)) {
+              return {
+                command: firstArg.value,
+                alternative: getAlternatives(firstArg.value),
+              };
+            }
+            return undefined;
+          }
+
+          // For execSync (shell-based) - check if any Unix command is in the string
+          for (const unixCmd of ALL_UNIX_COMMANDS) {
+            if (matchesExecSync(firstArg, unixCmd)) {
+              // Extract command name for better error message
+              let command = unixCmd;
+              if (firstArg.type === 'Literal') {
+                command = firstArg.value.trim().split(/\s+/)[0];
+              } else if (firstArg.type === 'TemplateLiteral') {
+                const firstQuasi = firstArg.quasis[0].value.cooked || firstArg.quasis[0].value.raw;
+                command = firstQuasi.trim().split(/\s+/)[0];
+              }
+
+              return {
+                command,
+                alternative: getAlternatives(command),
+              };
+            }
+          }
+
+          return undefined;
+        },
+        messageId: 'noUnixCommand',
+      }),
+    };
+  },
+};

package/eslint/rules/no-unsafe-root-join.cjs

@@ -0,0 +1,85 @@
+/**
+ * ESLint rule: no-unsafe-root-join
+ *
+ * Flags `safePath.join(<root>, …)` and `safePath.resolve(<root>, …)` where
+ * the first argument is an identifier whose name ends in "root" (case-insensitive,
+ * e.g. harnessRoot, stagedRoot, pluginRoot). These are security-root path joins
+ * that should use `safePath.joinUnderRoot()` to prevent caller-controlled segments
+ * from escaping the root on Windows via drive-letter or absolute path injection.
+ *
+ * Rule is intentionally narrow: only *Root-named first arguments are flagged to
+ * avoid false positives on ordinary joins.
+ *
+ * @example
+ * // ❌ BAD — silent escape on Windows if item.name is 'C:\evil'
+ * const dest = safePath.join(harnessRoot, stagedDirName(item.name));
+ *
+ * // ✅ GOOD — throws on Windows drive-letter or absolute segment
+ * const dest = safePath.joinUnderRoot(harnessRoot, stagedDirName(item.name));
+ */
+
+'use strict';
+
+/** Return true when the identifier name ends with 'root' (case-insensitive). */
+function isRootIdentifier(name) {
+  return name.toLowerCase().endsWith('root');
+}
+
+/**
+ * Return true when the first argument of a CallExpression is an Identifier
+ * whose name ends in 'root' (case-insensitive).
+ */
+function firstArgIsRootIdentifier(node) {
+  if (node.arguments.length === 0) return false;
+  const first = node.arguments[0];
+  return first.type === 'Identifier' && isRootIdentifier(first.name);
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Enforce safePath.joinUnderRoot() for joins whose first arg is a security root variable (name ends in "Root").',
+      category: 'Security',
+      recommended: true,
+    },
+    messages: {
+      useJoinUnderRoot:
+        'Use safePath.joinUnderRoot({{root}}, …) instead of safePath.{{method}}({{root}}, …) ' +
+        'when the first argument is a security root. ' +
+        'safePath.{{method}}() does not prevent caller-controlled segments from escaping the root on Windows.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        // Must be a MemberExpression: safePath.<method>(...)
+        if (node.callee.type !== 'MemberExpression') return;
+
+        const obj = node.callee.object;
+        const prop = node.callee.property;
+
+        // Object must be the identifier 'safePath'
+        if (obj.type !== 'Identifier' || obj.name !== 'safePath') return;
+
+        // Method must be 'join' or 'resolve'
+        if (prop.type !== 'Identifier') return;
+        const method = prop.name;
+        if (method !== 'join' && method !== 'resolve') return;
+
+        // First argument must be an identifier ending in 'root'
+        if (!firstArgIsRootIdentifier(node)) return;
+
+        const rootName = node.arguments[0].name;
+        context.report({
+          node,
+          messageId: 'useJoinUnderRoot',
+          data: { root: rootName, method },
+        });
+      },
+    };
+  },
+};

package/eslint/rules/no-url-pathname-for-fs.cjs

@@ -0,0 +1,107 @@
+/**
+ * ESLint rule: no-url-pathname-for-fs
+ *
+ * Prevents `.pathname` access on a `URL` constructed from `import.meta.url`.
+ * On Windows, `new URL('../x', import.meta.url).pathname` returns `/D:/...`
+ * which breaks `fs` operations (ENOENT or `D:\D:\...`).
+ *
+ * Fix: use `fileURLToPath(new URL(...))` from `node:url`, or
+ * `resolveFromImportMeta()` from `@vibe-agent-toolkit/utils/fs`.
+ *
+ * @example
+ * // ❌ BAD — Windows-broken
+ * const p = new URL('../fixtures/x.yaml', import.meta.url).pathname;
+ *
+ * // ✅ GOOD
+ * import { fileURLToPath } from 'node:url';
+ * const p = fileURLToPath(new URL('../fixtures/x.yaml', import.meta.url));
+ */
+
+'use strict';
+
+const {
+  SAFE_FS_MODULE,
+  SAFE_MODULE_ONLY_SCHEMA,
+  resolveSafeModule,
+} = require('./safe-import.cjs');
+
+/**
+ * Returns true if `node` is the `import.meta.url` `MemberExpression`.
+ */
+function isImportMetaUrl(node) {
+  return (
+    node?.type === 'MemberExpression' &&
+    node.object?.type === 'MetaProperty' &&
+    node.object.meta?.name === 'import' &&
+    node.object.property?.name === 'meta' &&
+    node.property?.name === 'url'
+  );
+}
+
+const SKIP_KEYS = new Set(['parent', 'loc', 'range']);
+
+function childIsAstNode(value) {
+  return value && typeof value === 'object' && typeof value.type === 'string';
+}
+
+/**
+ * Walks an AST subtree looking for `import.meta.url`.
+ * Returns true if found, false otherwise.
+ */
+function containsImportMetaUrl(node) {
+  if (!node || typeof node !== 'object') return false;
+  if (isImportMetaUrl(node)) return true;
+  for (const key of Object.keys(node)) {
+    if (SKIP_KEYS.has(key)) continue;
+     
+    const value = node[key];
+    if (Array.isArray(value) && value.some((item) => containsImportMetaUrl(item))) {
+      return true;
+    }
+    if (childIsAstNode(value) && containsImportMetaUrl(value)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isUrlConstructorWithImportMeta(node) {
+  if (node?.type !== 'NewExpression') return false;
+  if (node.callee?.name !== 'URL') return false;
+  return node.arguments.some((arg) => containsImportMetaUrl(arg));
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow `.pathname` on a URL built from `import.meta.url`; use `fileURLToPath()` instead.',
+      category: 'Cross-platform compatibility',
+      recommended: true,
+    },
+    messages: {
+      useFileURLToPath:
+        'Do not use `.pathname` on `new URL(..., import.meta.url)` — on Windows it returns `/D:/...` and breaks `fs`. ' +
+        'Use `fileURLToPath(new URL(...))` from `node:url` or `resolveFromImportMeta()` from `{{safeModule}}`.',
+    },
+    schema: [SAFE_MODULE_ONLY_SCHEMA],
+  },
+
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (node.property.type !== 'Identifier' || node.property.name !== 'pathname') {
+          return;
+        }
+        if (isUrlConstructorWithImportMeta(node.object)) {
+          context.report({
+            node,
+            messageId: 'useFileURLToPath',
+            data: { safeModule: resolveSafeModule(context, SAFE_FS_MODULE) },
+          });
+        }
+      },
+    };
+  },
+};