@vibe-agent-toolkit/utils 0.1.41 → 0.1.42-rc.1

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) },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/path-function-rule-factory.cjs

@@ -0,0 +1,216 @@
+/**
+ * ESLint Rule Factory for banning specific path functions from node:path
+ *
+ * Handles both import styles:
+ * - Named: import { join } from 'node:path' → join(...)
+ * - Default/namespace: import path from 'node:path' → path.join(...)
+ *
+ * Auto-fixes to safePath.fn() from `@vibe-agent-toolkit/utils/path` — the narrow
+ * subpath that owns `safePath`, NOT the barrel. See `safe-import.cjs`.
+ */
+
+const {
+  UNANCHORED_EXEMPT_FILE,
+  UNANCHORED_EXEMPT_MESSAGE,
+  createConfigurableExemptPathMatcher,
+  reportUnanchoredExemptEntries,
+} = require('./exempt-path-matcher.cjs');
+const {
+  EXEMPT_AND_SAFE_MODULE_SCHEMA,
+  SAFE_PATH_MODULE,
+  isNameAlreadyBound,
+  resolveSafeModule,
+} = require('./safe-import.cjs');
+
+const PATH_MODULES = new Set(['node:path', 'path']);
+const SAFE_OBJECT = 'safePath';
+
+/**
+ * The files allowed to call raw `node:path` functions are whichever ones the
+ * CONSUMING repo says implement (or assert) its `safePath` wrappers — declared
+ * per-rule as `{ exemptFiles: [...] }`, matched at a path-segment boundary (see
+ * `exempt-path-matcher.cjs` for why these are not substrings).
+ *
+ * This list used to be hardcoded to VAT's own `packages/utils/src/path-core.ts`
+ * et al. Those paths are meaningless in an adopter's tree and actively harmful
+ * as a default — a same-named file at the same repo-relative path would inherit
+ * an exemption it never declared. Default: nothing is exempt.
+ */
+const exemptMatcherFor = createConfigurableExemptPathMatcher();
+
+/**
+ * Remove a named import specifier, handling comma cleanup.
+ */
+function removeSpecifier(fixer, sourceCode, importNode, spec) {
+  if (importNode.specifiers.length === 1) {
+    return [fixer.remove(importNode)];
+  }
+  const comma = sourceCode.getTokenAfter(spec);
+  if (comma?.value === ',') {
+    return [fixer.removeRange([spec.range[0], comma.range[1]])];
+  }
+  const commaBefore = sourceCode.getTokenBefore(spec);
+  if (commaBefore?.value === ',') {
+    return [fixer.removeRange([commaBefore.range[0], spec.range[1]])];
+  }
+  return [fixer.remove(spec)];
+}
+
+/**
+ * Track path module specifiers from an import declaration.
+ */
+function trackPathImport(node, unsafeFn, state) {
+  for (const spec of node.specifiers) {
+    if (spec.type === 'ImportSpecifier' && spec.imported.name === unsafeFn) {
+      state.namedImportSpec = spec;
+      state.namedImportNode = node;
+    }
+    if (spec.type === 'ImportDefaultSpecifier' || spec.type === 'ImportNamespaceSpecifier') {
+      state.defaultImportName = spec.local.name;
+    }
+  }
+}
+
+/**
+ * Track safe module import from an import declaration.
+ */
+function trackSafeImport(node, state) {
+  state.safeImportNode = node;
+  for (const spec of node.specifiers) {
+    if (spec.type === 'ImportSpecifier' && spec.imported.name === SAFE_OBJECT) {
+      state.hasSafePathImport = true;
+    }
+  }
+}
+
+/**
+ * Check if a call expression is an unsafe path function call.
+ * Returns { isUnsafe, isNamed } or null if not a match.
+ */
+function classifyCall(node, unsafeFn, state) {
+  // Direct call from named import: join(...)
+  if (
+    node.callee.type === 'Identifier' &&
+    node.callee.name === unsafeFn &&
+    state.namedImportSpec
+  ) {
+    return { isNamed: true };
+  }
+  // Member expression: path.join(...)
+  if (
+    node.callee.type === 'MemberExpression' &&
+    node.callee.object.type === 'Identifier' &&
+    node.callee.object.name === state.defaultImportName &&
+    node.callee.property.type === 'Identifier' &&
+    node.callee.property.name === unsafeFn
+  ) {
+    return { isNamed: false };
+  }
+  return null;
+}
+
+/**
+ * Build auto-fix for an unsafe path function call.
+ */
+function buildFix(fixer, node, unsafeFn, isNamed, sourceCode, state) {
+  const fixes = [fixer.replaceText(node.callee, `${SAFE_OBJECT}.${unsafeFn}`)];
+
+  if (!state.hasSafePathImport) {
+    if (state.safeImportNode) {
+      const lastSpec = state.safeImportNode.specifiers.at(-1);
+      fixes.push(fixer.insertTextAfter(lastSpec, `, ${SAFE_OBJECT}`));
+    } else {
+      const targetNode = state.namedImportNode || sourceCode.ast.body[0];
+      fixes.push(fixer.insertTextAfter(targetNode, `\nimport { ${SAFE_OBJECT} } from '${state.safeModule}';`));
+    }
+    state.hasSafePathImport = true;
+  }
+
+  if (isNamed && state.namedImportNode) {
+    fixes.push(...removeSpecifier(fixer, sourceCode, state.namedImportNode, state.namedImportSpec));
+  }
+
+  return fixes;
+}
+
+module.exports = function createPathFunctionRule(config) {
+  const { unsafeFn, message } = config;
+
+  return {
+    meta: {
+      type: 'problem',
+      docs: {
+        description: `Enforce safePath.${unsafeFn}() instead of path.${unsafeFn}()`,
+        category: 'Cross-platform compatibility',
+        recommended: true,
+      },
+      fixable: 'code',
+      schema: [EXEMPT_AND_SAFE_MODULE_SCHEMA],
+      messages: {
+        noUnsafePathFn: message,
+        [UNANCHORED_EXEMPT_FILE]: UNANCHORED_EXEMPT_MESSAGE,
+      },
+    },
+
+    create(context) {
+      if (exemptMatcherFor(context)(context.getFilename())) {
+        // Still surface a malformed exemption list: the file we are standing in
+        // may be exempt only BECAUSE the entry is unanchored.
+        return {
+          Program(node) {
+            reportUnanchoredExemptEntries(context, node);
+          },
+        };
+      }
+
+      const sourceCode = context.getSourceCode();
+      const state = {
+        // Resolved per invocation — the option belongs to the consuming repo,
+        // which may point different rules at different re-export entries.
+        safeModule: resolveSafeModule(context, SAFE_PATH_MODULE),
+        namedImportSpec: null,
+        namedImportNode: null,
+        defaultImportName: null,
+        // Seeded from SCOPE, not from "did I see an import from SAFE_MODULE?".
+        // A file already importing `safePath` from the barrel needs the call
+        // rewritten but must NOT gain a second binding of the same name.
+        hasSafePathImport: isNameAlreadyBound(sourceCode, SAFE_OBJECT),
+        safeImportNode: null,
+      };
+
+      return {
+        Program(node) {
+          reportUnanchoredExemptEntries(context, node);
+        },
+
+        ImportDeclaration(node) {
+          if (PATH_MODULES.has(node.source.value)) {
+            trackPathImport(node, unsafeFn, state);
+          }
+          if (node.source.value === state.safeModule) {
+            trackSafeImport(node, state);
+          }
+        },
+
+        CallExpression(node) {
+          const classification = classifyCall(node, unsafeFn, state);
+          if (!classification) {
+            return;
+          }
+
+          context.report({
+            node,
+            messageId: 'noUnsafePathFn',
+            // The module name reaches the message through `{{safeModule}}` rather
+            // than being spelled out in each rule's string, so the advice cannot
+            // drift from where the fixer actually writes the import.
+            data: { safeModule: state.safeModule },
+            fix(fixer) {
+              return buildFix(fixer, node, unsafeFn, classification.isNamed, sourceCode, state);
+            },
+          });
+        },
+      };
+    },
+  };
+};

package/eslint/rules/prefer-startswith-over-regex.cjs

@@ -0,0 +1,111 @@
+/**
+ * ESLint rule: prefer-startswith-over-regex
+ *
+ * Catches `/^literal/.test(s)` and `/literal$/.test(s)` patterns where the
+ * literal portion contains only plain characters and `\/` escape sequences,
+ * and recommends `s.startsWith('literal')` / `s.endsWith('literal')`.
+ *
+ * Why a local rule?
+ * `unicorn/prefer-string-starts-ends-with` already handles the simple case
+ * but conservatively rejects any pattern containing `\` — including the
+ * common `\/` (escaped slash) sequence. SonarCloud's S6557 catches these,
+ * but only post-merge. This rule shifts that detection left into ESLint.
+ *
+ * Examples:
+ *   /^file:\/\//.test(s)   →  s.startsWith('file://')
+ *   /^https?:\/\//.test(s) →  NOT flagged (contains `?` quantifier)
+ *   /^[a-z]+/.test(s)      →  NOT flagged (contains `[` character class)
+ *   /\.txt$/.test(s)       →  NOT flagged (contains `.` metachar)
+ */
+
+'use strict';
+
+const METACHARS = new Set(['^', '$', '+', '[', '{', '(', '.', '?', '*', '|']);
+
+/**
+ * Treat `\/` as a single literal `/` and check the remainder for any
+ * regex metacharacter or other backslash-escape we don't understand.
+ * Returns the literal string if safely convertible, otherwise null.
+ */
+function literalEquivalent(patternBody) {
+  // Step 1: collapse `\/` (the only escape we accept) into a literal `/`.
+  const flattened = patternBody.replaceAll(String.raw`\/`, '/');
+  // Step 2: any remaining `\` is an escape we don't understand (\d, \w, \\, etc.).
+  if (flattened.includes('\\')) {
+    return null;
+  }
+  // Step 3: reject any regex metacharacter we'd be silently flattening.
+  for (const ch of flattened) {
+    if (METACHARS.has(ch)) {
+      return null;
+    }
+  }
+  return flattened;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        String.raw`Prefer String#startsWith / String#endsWith over /^literal/.test() — even when the literal includes \/ escape sequences`,
+      recommended: true,
+    },
+    messages: {
+      preferStartsWith:
+        "Prefer `<string>.startsWith('{{literal}}')` over `/{{pattern}}/.test(<string>)`. " +
+        String.raw`Treat \/ as the literal / character.`,
+      preferEndsWith:
+        "Prefer `<string>.endsWith('{{literal}}')` over `/{{pattern}}/.test(<string>)`. " +
+        String.raw`Treat \/ as the literal / character.`,
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (
+          node.callee.type !== 'MemberExpression' ||
+          node.callee.property.type !== 'Identifier' ||
+          node.callee.property.name !== 'test'
+        ) {
+          return;
+        }
+        const obj = node.callee.object;
+        if (obj.type !== 'Literal' || !obj.regex) {
+          return;
+        }
+        const { pattern, flags } = obj.regex;
+        if (flags.includes('i') || flags.includes('m')) {
+          return;
+        }
+
+        if (pattern.startsWith('^')) {
+          const body = pattern.slice(1);
+          const literal = literalEquivalent(body);
+          if (literal !== null && literal !== '') {
+            context.report({
+              node,
+              messageId: 'preferStartsWith',
+              data: { literal, pattern },
+            });
+            return;
+          }
+        }
+
+        if (pattern.endsWith('$') && !pattern.endsWith(String.raw`\$`)) {
+          const body = pattern.slice(0, -1);
+          const literal = literalEquivalent(body);
+          if (literal !== null && literal !== '') {
+            context.report({
+              node,
+              messageId: 'preferEndsWith',
+              data: { literal, pattern },
+            });
+          }
+        }
+      },
+    };
+  },
+};