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

package/eslint/rules/dirent-type-needs-symlink-check.cjs

@@ -0,0 +1,282 @@
+/**
+ * ESLint rule: dirent-type-needs-symlink-check
+ *
+ * Flags `.isFile()` / `.isDirectory()` on a Dirent whose binding is never
+ * asked `.isSymbolicLink()`.
+ *
+ * A Dirent describes the entry itself, not what it points at, so for a
+ * symlink BOTH `isFile()` and `isDirectory()` are false. A walk written as
+ * `if (e.isDirectory()) recurse(); else if (e.isFile()) read();` therefore
+ * does not refuse a link, and does not follow it either — it drops the entry
+ * on the floor without a word. The sweep found staged skill trees, size
+ * accounting and packaging walks with exactly that shape, and every one
+ * reported a tree with a symlink in it as clean. The decision about a link —
+ * refuse, follow, record — has to be made where it can be seen, on the same
+ * binding, before the type test.
+ *
+ * ## How a binding is known to be a Dirent
+ *
+ * - the result of `readdir` / `readdirSync` called with `{ withFileTypes: true }`
+ *   (any receiver: bare, `fs.`, `fs.promises.`), stored in a variable, assigned
+ *   later, or iterated directly by `for…of`;
+ * - the result of `opendir` / `opendirSync`, iterated by `for await`;
+ * - an element of such a collection, via `for…of` or a callback to `filter` /
+ *   `map` / `some` / `every` / `find` / `forEach` / `flatMap` — whether the
+ *   collection is a variable or the `readdir` call itself, chained
+ *   (`readdirSync(d, { withFileTypes: true }).filter(e => e.isDirectory())`),
+ *   including through a `filter` / `toSorted` / `slice` that keeps the
+ *   collection a Dirent collection;
+ * - a parameter or variable annotated `Dirent`, `Dirent[]`,
+ *   `readonly Dirent[]` or `Array<Dirent>`.
+ *
+ * A Stats object from `stat()` / `lstat()` is NOT a Dirent and is never
+ * flagged: `stat` already followed the link, and `lstat` callers are asking a
+ * different question. A `readdir` without `withFileTypes` yields strings.
+ *
+ * The guard must be on the SAME binding: an `lstat(e.name).isSymbolicLink()`
+ * beside an unguarded `e.isDirectory()` is two questions about two objects,
+ * and the rule cannot know they agree.
+ *
+ * @example
+ * // BAD — a symlinked directory is neither, so it silently vanishes
+ * for (const e of readdirSync(dir, { withFileTypes: true })) {
+ *   if (e.isDirectory()) walk(e); else if (e.isFile()) read(e);
+ * }
+ *
+ * // GOOD — the link is decided first, visibly
+ * for (const e of readdirSync(dir, { withFileTypes: true })) {
+ *   if (e.isSymbolicLink()) { refuse(e); continue; }
+ *   if (e.isDirectory()) walk(e); else if (e.isFile()) read(e);
+ * }
+ */
+
+'use strict';
+
+const { calleeName } = require('./callee-name.cjs');
+
+const READDIR_FUNCTIONS = new Set(['readdir', 'readdirSync']);
+const OPENDIR_FUNCTIONS = new Set(['opendir', 'opendirSync']);
+const ELEMENT_CALLBACK_METHODS = new Set([
+  'filter', 'map', 'some', 'every', 'find', 'forEach', 'flatMap', 'findIndex', 'findLast',
+]);
+/** Array methods whose RESULT is still the same Dirent collection (a `map` is not: it produced something else). */
+const COLLECTION_PRESERVING_METHODS = new Set(['filter', 'toSorted', 'toReversed', 'slice', 'reverse', 'sort']);
+const TYPE_TESTS = new Set(['isFile', 'isDirectory']);
+const FUNCTION_TYPES = ['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression'];
+
+/** Whether some argument is an object literal carrying `withFileTypes: true`. */
+function hasWithFileTypes(call) {
+  return call.arguments.some(
+    (arg) =>
+      arg.type === 'ObjectExpression' &&
+      arg.properties.some(
+        (prop) =>
+          prop.type === 'Property' &&
+          !prop.computed &&
+          (prop.key.name ?? prop.key.value) === 'withFileTypes' &&
+          prop.value.type === 'Literal' &&
+          prop.value.value === true,
+      ),
+  );
+}
+
+/** Whether `expr` (possibly awaited) produces Dirents when stored or iterated. */
+function isDirentCollectionCall(expr) {
+  const call = expr?.type === 'AwaitExpression' ? expr.argument : expr;
+  if (call?.type !== 'CallExpression') {
+    return false;
+  }
+  const name = calleeName(call);
+  return OPENDIR_FUNCTIONS.has(name) || (READDIR_FUNCTIONS.has(name) && hasWithFileTypes(call));
+}
+
+/** Whether a TS type node is the bare `Dirent` reference. */
+function isDirentType(typeNode) {
+  return (
+    typeNode?.type === 'TSTypeReference' &&
+    typeNode.typeName.type === 'Identifier' &&
+    typeNode.typeName.name === 'Dirent'
+  );
+}
+
+/**
+ * 'element' for `Dirent`, 'collection' for `Dirent[]` / `readonly Dirent[]` /
+ * `Array<Dirent>` / `ReadonlyArray<Dirent>`, null otherwise.
+ */
+function direntKindOfAnnotation(annotation) {
+  const typeNode = annotation?.typeAnnotation;
+  if (!typeNode) {
+    return null;
+  }
+  if (isDirentType(typeNode)) {
+    return 'element';
+  }
+  if (typeNode.type === 'TSTypeOperator') {
+    return direntKindOfAnnotation({ typeAnnotation: typeNode.typeAnnotation }) === 'collection' ? 'collection' : null;
+  }
+  if (typeNode.type === 'TSArrayType') {
+    return isDirentType(typeNode.elementType) ? 'collection' : null;
+  }
+  const generic = typeNode.type === 'TSTypeReference' ? typeNode.typeArguments ?? typeNode.typeParameters : null;
+  return generic && isDirentType(generic.params[0]) ? 'collection' : null;
+}
+
+/** The kind of member call a reference participates in: `{ name, call }` or null. */
+function memberCallOf(identifier) {
+  const member = identifier.parent;
+  if (member?.type !== 'MemberExpression' || member.object !== identifier || member.computed) {
+    return null;
+  }
+  const call = member.parent;
+  if (call?.type !== 'CallExpression' || call.callee !== member || member.property.type !== 'Identifier') {
+    return null;
+  }
+  return { name: member.property.name, call };
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require an isSymbolicLink() check on a Dirent before isFile()/isDirectory() — both are ' +
+        'false for a symlink, so an unchecked walk drops links silently',
+      recommended: false,
+      recommendedSeverity: 'warn',
+    },
+    schema: [],
+    messages: {
+      direntTypeWithoutSymlinkCheck:
+        'A symlink answers false to BOTH isFile() and isDirectory(), so this walk drops every link ' +
+        'without a word. Decide the link on this same binding first — ' +
+        'if ({{name}}.isSymbolicLink()) { refuse / follow / record } — then test the type.',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const collections = new Set();
+    const elements = new Set();
+
+    /** The variable an identifier REFERENCE resolves to, or null. */
+    function resolvedVariable(identifier) {
+      const reference = sourceCode.getScope(identifier).references.find((ref) => ref.identifier === identifier);
+      return reference?.resolved ?? null;
+    }
+
+    function markDeclared(node, kind) {
+      for (const variable of sourceCode.getDeclaredVariables(node)) {
+        (kind === 'element' ? elements : collections).add(variable);
+      }
+    }
+
+    function markAnnotatedParams(fn) {
+      const declared = sourceCode.getDeclaredVariables(fn);
+      for (const param of fn.params) {
+        const kind = param.type === 'Identifier' ? direntKindOfAnnotation(param.typeAnnotation) : null;
+        const variable = kind ? declared.find((candidate) => candidate.name === param.name) : null;
+        if (variable) {
+          (kind === 'element' ? elements : collections).add(variable);
+        }
+      }
+    }
+
+    function isCollectionIdentifier(expr) {
+      return expr.type === 'Identifier' && collections.has(resolvedVariable(expr));
+    }
+
+    /**
+     * Whether `expr` is a Dirent collection: a bound variable, the `readdir`
+     * call itself (possibly awaited or parenthesised), or a chain of
+     * collection-preserving array methods on one of those.
+     */
+    function isDirentCollection(expr) {
+      if (!expr) {
+        return false;
+      }
+      if (isCollectionIdentifier(expr) || isDirentCollectionCall(expr)) {
+        return true;
+      }
+      const { callee } = expr.type === 'CallExpression' ? expr : {};
+      return (
+        callee?.type === 'MemberExpression' &&
+        callee.property.type === 'Identifier' &&
+        COLLECTION_PRESERVING_METHODS.has(callee.property.name) &&
+        isDirentCollection(callee.object)
+      );
+    }
+
+    function reportUnguarded(variable) {
+      let guarded = false;
+      const typeTests = [];
+      for (const reference of variable.references) {
+        const use = memberCallOf(reference.identifier);
+        if (use?.name === 'isSymbolicLink') {
+          guarded = true;
+        } else if (use && TYPE_TESTS.has(use.name)) {
+          typeTests.push(use.call);
+        }
+      }
+      if (guarded) {
+        return;
+      }
+      for (const call of typeTests) {
+        context.report({ node: call, messageId: 'direntTypeWithoutSymlinkCheck', data: { name: variable.name } });
+      }
+    }
+
+    return {
+      VariableDeclarator(node) {
+        if (isDirentCollectionCall(node.init)) {
+          markDeclared(node, 'collection');
+        } else if (node.id.type === 'Identifier') {
+          const kind = direntKindOfAnnotation(node.id.typeAnnotation);
+          if (kind) {
+            markDeclared(node, kind);
+          }
+        }
+      },
+      AssignmentExpression(node) {
+        if (node.left.type === 'Identifier' && isDirentCollectionCall(node.right)) {
+          const variable = resolvedVariable(node.left);
+          if (variable) {
+            collections.add(variable);
+          }
+        }
+      },
+      ForOfStatement(node) {
+        if (node.left.type !== 'VariableDeclaration') {
+          return;
+        }
+        if (isDirentCollection(node.right)) {
+          markDeclared(node.left, 'element');
+        }
+      },
+      CallExpression(node) {
+        const { callee } = node;
+        const callback = node.arguments[0];
+        if (
+          callee.type === 'MemberExpression' &&
+          callee.property.type === 'Identifier' &&
+          ELEMENT_CALLBACK_METHODS.has(callee.property.name) &&
+          isDirentCollection(callee.object) &&
+          callback &&
+          FUNCTION_TYPES.includes(callback.type) &&
+          callback.params[0]?.type === 'Identifier'
+        ) {
+          const declared = sourceCode.getDeclaredVariables(callback);
+          const first = declared.find((variable) => variable.name === callback.params[0].name);
+          if (first) {
+            elements.add(first);
+          }
+        }
+      },
+      [FUNCTION_TYPES.join(',')]: markAnnotatedParams,
+      'Program:exit'() {
+        for (const variable of elements) {
+          reportUnguarded(variable);
+        }
+      },
+    };
+  },
+};

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

@@ -18,6 +18,9 @@
  *   in one repo, so a baked-in default is a hole in every OTHER repo. Consumers
  *   declare their own via the rule option (see `exempt-path-matcher.cjs`).
  * @param {boolean} [config.checkMemberExpression] - Check for obj.method() calls (default: false)
+ * @param {Object} config.docs - The rule's `meta.docs` manifest entry: `category`,
+ *   `bans`, `useInstead`, optional `subpath`, and `recommended` /
+ *   `recommendedSeverity` (what `index.cjs` builds `configs.recommended` from).
  * @returns {Object} ESLint rule definition
  *
  * @example
@@ -147,6 +150,7 @@ module.exports = function createNoUnsafeRule(config) {
     safeFn,
     safeModule,
     message,
+    docs,
     exemptFiles = [],
     checkMemberExpression = false,
   } = config;
@@ -166,8 +170,7 @@ module.exports = function createNoUnsafeRule(config) {
       type: 'problem',
       docs: {
         description: `Enforce use of ${safeFn}() instead of ${unsafeFn}()`,
-        category: 'Best Practices',
-        recommended: true,
+        ...docs,
       },
       fixable: 'code',
       schema: [EXEMPT_AND_SAFE_MODULE_SCHEMA],

package/eslint/rules/exempt-path-matcher.cjs

@@ -23,7 +23,7 @@
  * - `isTestFile` — "is this a test file?" (a category, anchored on the basename's
  *   extension rather than on a path segment)
  *
- * `eslint-rule-factory.cjs`, `path-function-rule-factory.cjs`,
+ * `eslint-rule-factory.cjs`, `no-raw-node-path.cjs`,
  * `no-command-direct-factory.cjs` and `no-unix-shell-commands.cjs` all use these.
  * Do not re-implement any of them: the sibling-factory copy is how the bug
  * shipped four times in the first place.
@@ -36,6 +36,7 @@
 
 /** Forward-slash a path and drop any leading `./` or `/` noise used for anchoring. */
 function normalizeForMatch(value) {
+  // eslint-disable-next-line local/no-manual-path-normalize -- the rule pack is standalone CommonJS and cannot import the ESM helper; config paths and linted filenames are matched separator-agnostically on purpose.
   return String(value).replaceAll('\\', '/').replace(/^(?:\.\/)+/, '');
 }
 

package/eslint/rules/explicit-zod-strictness.cjs

@@ -0,0 +1,120 @@
+/**
+ * ESLint rule: explicit-zod-strictness
+ *
+ * Every `z.object({...})` must say, in the same method chain, what it does
+ * with a key it does not declare: `.strict()` (refuse), `.passthrough()` /
+ * `.loose()` (keep), or `.strip()` (drop — said out loud, for the write-side
+ * whitelist whose whole point is dropping). Zod's DEFAULT is that third answer
+ * left unsaid, and that is the one this repo cannot afford: CLAUDE.md retired
+ * every hand-bumped version integer on the promise that a strict schema is
+ * what refuses stale stored data, and a default-strip schema keeps none of that
+ * promise. It also hides the adopter-config trap the other way round: a key
+ * the schema strips on the way in is a key the adopter thinks is honoured.
+ *
+ * `z.strictObject()` and `z.looseObject()` are explicit by construction and
+ * pass. The marker may sit anywhere later in the chain (`.describe('…')
+ * .strict()`, `.strict().optional()`), and `.extend()` / `.partial()` /
+ * `.pick()` inherit the policy of what they were called on, so a chain that
+ * reaches a marker through them is explicit too.
+ *
+ * Option `allowDefaultStripIn: string[]` — repo-relative paths of files whose
+ * `z.object` calls may keep the default. This is a ratchet list, not a scope:
+ * name files, not directories, so a new default-strip schema cannot arrive
+ * unannounced under an allowed prefix.
+ *
+ * @example
+ * // BAD — an unknown key vanishes without a word
+ * const S = z.object({ version: z.string() });
+ *
+ * // GOOD — the policy is written where the shape is
+ * const S = z.object({ version: z.string() }).strict();
+ */
+
+'use strict';
+
+const { createExemptPathMatcher } = require('./exempt-path-matcher.cjs');
+
+/** Chain methods that decide the unknown-key policy. */
+const EXPLICIT_METHODS = new Set(['strict', 'passthrough', 'loose', 'strip']);
+
+/** Whether `node` is a `z.object(...)` call. */
+function isZodObjectCall(node) {
+  const { callee } = node;
+  return (
+    callee.type === 'MemberExpression' &&
+    !callee.computed &&
+    callee.object.type === 'Identifier' &&
+    callee.object.name === 'z' &&
+    callee.property.type === 'Identifier' &&
+    callee.property.name === 'object'
+  );
+}
+
+/**
+ * Whether the method chain that starts at `call` reaches an explicit
+ * unknown-key method. Follows `<call>.<method>(...)` links only: the moment
+ * the value is stored, passed, or returned the chain has ended and no later
+ * `.strict()` on some other expression counts for this object.
+ */
+function chainDeclaresPolicy(call) {
+  let current = call;
+  for (;;) {
+    const member = current.parent;
+    if (member?.type !== 'MemberExpression' || member.object !== current || member.computed) {
+      return false;
+    }
+    const outer = member.parent;
+    if (outer?.type !== 'CallExpression' || outer.callee !== member) {
+      return false;
+    }
+    if (member.property.type === 'Identifier' && EXPLICIT_METHODS.has(member.property.name)) {
+      return true;
+    }
+    current = outer;
+  }
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require every z.object({...}) to declare its unknown-key policy in the same chain — ' +
+        '.strict(), .passthrough(), .loose() or an explicit .strip() — because the default silently strips keys',
+      recommended: false,
+      recommendedSeverity: 'warn',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allowDefaultStripIn: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      defaultStrip:
+        'This z.object() keeps Zod\'s default of silently DROPPING unknown keys. Say what you mean: ' +
+        '.strict() refuses them (the default for anything VAT stores or reads back), ' +
+        '.passthrough() keeps them (only for a document some other party owns — say who, beside it), ' +
+        '.strip() drops them on purpose (a write-side whitelist — say why, beside it).',
+    },
+  },
+
+  create(context) {
+    const allowed = context.options?.[0]?.allowDefaultStripIn ?? [];
+    const filename = context.filename ?? context.getFilename();
+    if (createExemptPathMatcher(allowed)(filename)) {
+      return {};
+    }
+
+    return {
+      CallExpression(node) {
+        if (isZodObjectCall(node) && !chainDeclaresPolicy(node)) {
+          context.report({ node, messageId: 'defaultStrip' });
+        }
+      },
+    };
+  },
+};

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

@@ -114,8 +114,12 @@ module.exports = {
     docs: {
       description:
         'Disallow dynamic `import()` of a filesystem path; wrap with `pathToFileURL(p).href`.',
-      category: 'Cross-platform compatibility',
+      category: 'URLs and dynamic imports',
+      bans: '`await import(absolutePath)`',
+      useInstead: '`dynamicImportPath()` / `pathToFileURL(p).href`',
+      subpath: '/fs',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     messages: {
       useFileUrl:

package/eslint/rules/no-bare-executable-spawn.cjs

@@ -0,0 +1,70 @@
+/**
+ * ESLint rule: no-bare-executable-spawn
+ *
+ * Flags `spawn`, `spawnSync`, `execFile`, `execFileSync` or `execSync` whose
+ * first argument is the string literal `'git'` or `'node'` — bare or through
+ * a namespace (`cp.spawnSync('git', …)`).
+ *
+ * A bare name asks the OS to search `PATH` at spawn time, so a writable
+ * directory on `PATH` is a place to plant a binary (SonarCloud S4036), and
+ * `node` by name may not be the node running the caller. Resolve once and
+ * spawn the absolute path: `process.execPath` for node in source;
+ * `NODE_EXECUTABLE` / `gitExecutable()` from `@vibe-agent-toolkit/utils/testing`
+ * in tests. Sonar sees new code only and named 13 of 84 sites; this rule sees
+ * every file, so the class cannot regrow one PR at a time.
+ *
+ * @example
+ * // BAD
+ * spawnSync('git', ['status'], { cwd });
+ *
+ * // GOOD
+ * spawnSync(gitExecutable(), ['status'], { cwd });
+ */
+
+'use strict';
+
+const { calleeName } = require('./callee-name.cjs');
+
+const SPAWN_CALLS = new Set(['spawn', 'spawnSync', 'execFile', 'execFileSync', 'execSync']);
+const BARE_NAMES = new Set(['git', 'node']);
+
+/** The spawn-family callee name of a call, bare or namespaced, or null. */
+function spawnCallName(call) {
+  const name = calleeName(call);
+  return name !== null && SPAWN_CALLS.has(name) ? name : null;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        "Disallow spawning 'git' or 'node' by bare name — resolve the executable once " +
+        '(process.execPath; NODE_EXECUTABLE / gitExecutable() in tests) and spawn the absolute path',
+      category: 'Filesystem and process',
+      recommended: true,
+      recommendedSeverity: 'error',
+    },
+    schema: [],
+    messages: {
+      bareName:
+        "{{call}}('{{name}}', …) searches PATH at spawn time. Spawn an absolute path: " +
+        "process.execPath for node; NODE_EXECUTABLE / gitExecutable() from '@vibe-agent-toolkit/utils/testing' in tests.",
+    },
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        const call = spawnCallName(node);
+        if (call === null) {
+          return;
+        }
+        const first = node.arguments[0];
+        if (first?.type === 'Literal' && typeof first.value === 'string' && BARE_NAMES.has(first.value)) {
+          context.report({ node: first, messageId: 'bareName', data: { call, name: first.value } });
+        }
+      },
+    };
+  },
+};