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

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

@@ -1,9 +1,9 @@
 /**
  * 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')`.
+ * Catches `/^literal/.test(s)` and `/literal$/.test(s)` patterns whose body
+ * flattens to a plain string, and recommends `s.startsWith('literal')` /
+ * `s.endsWith('literal')`.
  *
  * Why a local rule?
  * `unicorn/prefer-string-starts-ends-with` already handles the simple case
@@ -11,11 +11,32 @@
  * common `\/` (escaped slash) sequence. SonarCloud's S6557 catches these,
  * but only post-merge. This rule shifts that detection left into ESLint.
  *
+ * ## Two shapes this rule deliberately does NOT limit itself to
+ *
+ * Both were narrowings in the first draft, and an adopter found each of them
+ * the same way: SonarCloud raised a MAJOR S6557 on code this rule had reported
+ * green.
+ *
+ * 1. **The regex need not be inline.** `const RE = /^x/; RE.test(s)` is the
+ *    same violation as `/^x/.test(s)` — see {@link resolveRegex}.
+ * 2. **An escaped non-special character is a literal character.** `\*` is an
+ *    unambiguous `*`; refusing every escape but `\/` skipped it — see
+ *    {@link literalEquivalent}.
+ *
+ * Neither could have been caught by scanning an adopter's tree. The rule runs
+ * at `error` there, so its finding count is zero BY CONSTRUCTION — lint cannot
+ * go green while a violation exists. A 0-vs-0 tie against another
+ * implementation is not agreement, it is two rules both failing to fire. For
+ * any rule an adopter reports zero findings for, that rule is *unmeasured*.
+ *
  * Examples:
  *   /^file:\/\//.test(s)   →  s.startsWith('file://')
+ *   /^\*glob/.test(s)      →  s.startsWith('*glob')
+ *   const R = /^a/; R.test(s) →  s.startsWith('a')
  *   /^https?:\/\//.test(s) →  NOT flagged (contains `?` quantifier)
  *   /^[a-z]+/.test(s)      →  NOT flagged (contains `[` character class)
- *   /\.txt$/.test(s)       →  NOT flagged (contains `.` metachar)
+ *   /\.txt$/.test(s)       →  NOT flagged (`.` is a metachar; `\.` would flag)
+ *   /^\d+/.test(s)         →  NOT flagged (`\d` is a character class)
  */
 
 'use strict';
@@ -23,24 +44,149 @@
 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.
+ * Escape sequences whose meaning is NOT "the character that follows the
+ * backslash": character classes (`\d`, `\w`, `\s`, `\p`), assertions (`\b`),
+ * numeric escapes and backreferences (`\0`–`\9`, `\k`), and the code-point
+ * forms (`\x`, `\u`, `\c`). `\n`, `\r`, `\t`, `\v`, `\f` ARE single literal
+ * characters, but flattening them would put a raw control character into the
+ * suggested `startsWith('…')` string, so they are rejected too.
+ *
+ * Every other escape — `\/`, `\.`, `\*`, `\+`, `\(`, `\\`, `\-` … — is an
+ * identity escape, and the character it protects is exactly what a
+ * `startsWith` comparison would look for.
+ */
+const MEANINGFUL_ESCAPE = /[0-9BDPSWbcdfknprstuvwx]/;
+
+/**
+ * Flatten a regex body to the plain string it is equivalent to.
+ *
+ * Returns the literal string if safely convertible, otherwise null. Scans
+ * character by character rather than doing a `replaceAll` of the one escape we
+ * happen to like: `\/` was accepted and `\*` was not, though both denote a
+ * single literal character and neither is a metacharacter once escaped.
  */
 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)) {
+  let literal = '';
+
+  for (let index = 0; index < patternBody.length; index += 1) {
+    const char = patternBody[index];
+
+    if (char === '\\') {
+      const escaped = patternBody[index + 1];
+      // A trailing lone backslash is not a valid pattern; refuse to guess.
+      if (escaped === undefined || MEANINGFUL_ESCAPE.test(escaped)) {
+        return null;
+      }
+      literal += escaped;
+      index += 1;
+      continue;
+    }
+
+    // Unescaped metacharacter: flattening it would change what matches.
+    if (METACHARS.has(char)) {
       return null;
     }
+    literal += char;
+  }
+
+  return literal;
+}
+
+/**
+ * Count the run of consecutive `\\` characters immediately preceding `index`
+ * in `text`.
+ *
+ * Used to decide whether a trailing `$` is an anchor or an escaped literal
+ * dollar sign: an EVEN run (including zero) means the `$` itself is
+ * unescaped — a genuine end-of-string anchor. An ODD run means the last of
+ * those backslashes escapes the `$`, making it a literal character. Looking
+ * only at the last two characters of the pattern (`\\$`) gets this wrong for
+ * two or more consecutive backslashes: `/\\\\$/` (an escaped backslash `\\\\`
+ * followed by an unescaped `$` anchor) also ends in the two characters `\\$`,
+ * but the `$` there IS an anchor.
+ */
+function countTrailingBackslashes(text, index) {
+  let count = 0;
+  let position = index - 1;
+  while (position >= 0 && text[position] === '\\') {
+    count += 1;
+    position -= 1;
+  }
+  return count;
+}
+
+/**
+ * Find the variable `identifier` resolves to, searching outward from its scope.
+ */
+function findVariable(sourceCode, identifier) {
+  for (let scope = sourceCode.getScope(identifier); scope; scope = scope.upper) {
+    const found = scope.variables.find((variable) => variable.name === identifier.name);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+/**
+ * The regex `node` denotes: itself when it is a regex literal, or the literal
+ * a single-assignment variable was initialised with.
+ *
+ * The indirection matters because hoisting a regex to a module-level `const` is
+ * the normal way to write one — and examining only inline literals meant the
+ * rule went quiet on exactly the code most likely to run hot.
+ *
+ * Conservative on purpose: one definition, one write, and that write is a regex
+ * literal. A binding assigned more than once could hold anything by the time
+ * `.test()` runs, and nothing here proves which value that is.
+ *
+ * `indirect` is what lets the caller treat a hoisted regex differently from an
+ * inline one — see the `g`/`y` guard, which only a shared object can trip.
+ *
+ * @returns {{pattern: string, flags: string, indirect: boolean} | null}
+ */
+function resolveRegex(sourceCode, node) {
+  if (node.type === 'Literal' && node.regex) {
+    return { ...node.regex, indirect: false };
+  }
+  if (node.type !== 'Identifier') {
+    return null;
+  }
+
+  const variable = findVariable(sourceCode, node);
+  if (variable?.defs.length !== 1) {
+    return null;
+  }
+  const [definition] = variable.defs;
+  if (definition.type !== 'Variable' || !definition.node.init) {
+    return null;
+  }
+  if (variable.references.filter((reference) => reference.isWrite()).length !== 1) {
+    return null;
   }
-  return flattened;
+
+  const { init } = definition.node;
+  return init.type === 'Literal' && init.regex ? { ...init.regex, indirect: true } : null;
+}
+
+/**
+ * Render the flattened literal as JS SOURCE, not as a bare character run.
+ *
+ * The literal is a string of characters; the message drops it into
+ * `startsWith(…)`, which a human reads as source. Those are different
+ * languages, and interpolating one into the other loses exactly the characters
+ * that matter. `/^C:\\Users/` flattens to `C:\Users` — one backslash — and
+ * emitting it raw produced the advice `startsWith('C:\Users')`, which JavaScript
+ * reads back as `"C:Users"`. Worse in the realistic case: a `/^\\\\/` UNC check
+ * became `startsWith('\\')`, i.e. ONE backslash, silently true for any
+ * single-backslash path. A literal containing `'` produced advice that is a
+ * `SyntaxError` outright.
+ *
+ * This rule has no fixer, so the message IS the deliverable — there is no
+ * autofixer downstream that would have escaped it correctly.
+ */
+function asSourceLiteral(literal) {
+  return JSON.stringify(literal);
 }
 
 module.exports = {
@@ -48,21 +194,26 @@ module.exports = {
     type: 'problem',
     docs: {
       description:
-        String.raw`Prefer String#startsWith / String#endsWith over /^literal/.test() — even when the literal includes \/ escape sequences`,
+        String.raw`Prefer String#startsWith / String#endsWith over /^literal/.test() — including escaped literals such as \/ and \*, and regexes held in a const`,
       recommended: true,
     },
     messages: {
+      // `{{pattern}}` carries its FLAGS. Rendering `/^abc/` for a source
+      // `/^abc/g` hid the one character that decides whether the advice is
+      // right, from the one person positioned to notice.
       preferStartsWith:
-        "Prefer `<string>.startsWith('{{literal}}')` over `/{{pattern}}/.test(<string>)`. " +
-        String.raw`Treat \/ as the literal / character.`,
+        'Prefer `<string>.startsWith({{literal}})` over `/{{pattern}}/{{flags}}.test(<string>)`. ' +
+        String.raw`An escaped character such as \/ or \* is the literal character itself.`,
       preferEndsWith:
-        "Prefer `<string>.endsWith('{{literal}}')` over `/{{pattern}}/.test(<string>)`. " +
-        String.raw`Treat \/ as the literal / character.`,
+        'Prefer `<string>.endsWith({{literal}})` over `/{{pattern}}/{{flags}}.test(<string>)`. ' +
+        String.raw`An escaped character such as \/ or \* is the literal character itself.`,
     },
     schema: [],
   },
 
   create(context) {
+    const sourceCode = context.getSourceCode();
+
     return {
       CallExpression(node) {
         if (
@@ -72,37 +223,55 @@ module.exports = {
         ) {
           return;
         }
-        const obj = node.callee.object;
-        if (obj.type !== 'Literal' || !obj.regex) {
+        // `startsWith` needs a string receiver where `.test()` would have
+        // coerced one. Arity is the only part of that this rule can check
+        // without types — a zero-argument `.test()` coerces `undefined` to
+        // "undefined" and is nobody's prefix check. A non-string ARGUMENT
+        // (`/^\[object/.test(v)`) remains a known limitation: `.test` coerces,
+        // `startsWith` throws, and only a type checker can tell them apart.
+        if (node.arguments.length !== 1) {
+          return;
+        }
+
+        const regex = resolveRegex(sourceCode, node.callee.object);
+        if (!regex) {
           return;
         }
-        const { pattern, flags } = obj.regex;
+        const { pattern, flags, indirect } = regex;
         if (flags.includes('i') || flags.includes('m')) {
           return;
         }
+        // `g` and `y` make `.test()` STATEFUL through `lastIndex`. A regex
+        // LITERAL is reconstructed on every evaluation, so its cursor is always
+        // 0 and the flags are inert; a hoisted `const` is one object that
+        // remembers. `const RE = /^abc/g` answers [true, false, true, false] to
+        // four calls on the same string where `startsWith` answers true four
+        // times — so resolving through a binding is precisely what makes this
+        // advice wrong, and precisely where it must not be given.
+        if (indirect && (flags.includes('g') || flags.includes('y'))) {
+          return;
+        }
+
+        const report = (messageId, literal) => {
+          context.report({
+            node,
+            messageId,
+            data: { literal: asSourceLiteral(literal), pattern, flags },
+          });
+        };
 
         if (pattern.startsWith('^')) {
-          const body = pattern.slice(1);
-          const literal = literalEquivalent(body);
+          const literal = literalEquivalent(pattern.slice(1));
           if (literal !== null && literal !== '') {
-            context.report({
-              node,
-              messageId: 'preferStartsWith',
-              data: { literal, pattern },
-            });
+            report('preferStartsWith', literal);
             return;
           }
         }
 
-        if (pattern.endsWith('$') && !pattern.endsWith(String.raw`\$`)) {
-          const body = pattern.slice(0, -1);
-          const literal = literalEquivalent(body);
+        if (pattern.endsWith('$') && countTrailingBackslashes(pattern, pattern.length - 1) % 2 === 0) {
+          const literal = literalEquivalent(pattern.slice(0, -1));
           if (literal !== null && literal !== '') {
-            context.report({
-              node,
-              messageId: 'preferEndsWith',
-              data: { literal, pattern },
-            });
+            report('preferEndsWith', literal);
           }
         }
       },

package/eslint/rules/safe-import.cjs

@@ -68,6 +68,28 @@ function isNameAlreadyBound(sourceCode, name) {
   return scope.variables.some((variable) => variable.name === name);
 }
 
+/**
+ * Insert `text` above `node`, ABOVE its leading comments.
+ *
+ * `fixer.insertTextBefore(node)` uses the node's own start offset, which is
+ * after any comment attached to it — so inserting an import before the first
+ * statement dropped it BETWEEN an `eslint-disable-next-line` and the line that
+ * directive protects. The directive then applies to the inserted import, and
+ * the statement the developer had deliberately suppressed silently becomes
+ * fixable. A fixer that can revoke a suppression is a fixer that edits code
+ * nobody asked it to touch.
+ *
+ * @param {object} fixer - ESLint rule fixer.
+ * @param {object} sourceCode - ESLint `SourceCode` for the file being fixed.
+ * @param {object} node - The node to insert above.
+ * @param {string} text - Text to insert, including its own trailing newline.
+ */
+function insertAboveWithComments(fixer, sourceCode, node, text) {
+  const comments = sourceCode.getCommentsBefore(node);
+  const start = (comments[0] ?? node).range[0];
+  return fixer.insertTextBeforeRange([start, start], text);
+}
+
 /**
  * The `safeModule` rule option: point the fixer at YOUR re-export seam.
  *
@@ -135,6 +157,7 @@ module.exports = {
   SAFE_MODULE_ONLY_SCHEMA,
   SAFE_PATH_MODULE,
   SAFE_PROCESS_MODULE,
+  insertAboveWithComments,
   isNameAlreadyBound,
   resolveSafeModule,
   withSafeModuleOption,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/utils",
-  "version": "0.1.42-rc.1",
+  "version": "0.2.0-rc.1",
   "type": "module",
   "description": "Core utility functions shared across the vibe-agent-toolkit packages",
   "sideEffects": false,
@@ -84,7 +84,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc && tsx ../dev-tools/src/copy-yaml-assets.ts",
+    "build": "rimraf --glob dist \"*.tsbuildinfo\" && tsc && tsx ../dev-tools/src/copy-yaml-assets.ts",
     "test:unit": "vitest run",
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "test:system": "vitest run --config vitest.system.config.ts",