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

package/eslint/rules/require-justified-skip.cjs

@@ -0,0 +1,348 @@
+/* eslint-disable sonarjs/todo-tag -- This rule governs disabled tests, so its
+   documentation and its own test-runner member list necessarily quote the
+   `todo` token that sonarjs/todo-tag bans. The ban is why the annotation
+   grammar below is SKIP(#N) and not TODO(#N). */
+
+/* STILL BLIND (syntax-only rule): a skip reached through an imported/re-exported binding or an alias of an
+   alias; `it.only`; `expect(A).toBe(A)` on named constants; `assert.ok(true)`; a non-empty body with no assertion. */
+
+/**
+ * ESLint rule: require-justified-skip
+ *
+ * Flags test code that claims coverage it does not provide:
+ *
+ * 1. **Unconditional skips** — `it.skip`, `test.skip`, `describe.skip`, `suite.skip`,
+ *    `it.todo`, `test.todo`, and the `xit`/`xdescribe`/`xtest` aliases. The suite
+ *    still lists the case, so a reader (and a coverage report) sees a test that
+ *    never runs. Also the spellings that dodge a naive `object.property` check:
+ *    deeper chains (`test.concurrent.skip`), computed access (`it['skip']`), and
+ *    alias assignment (`const gate = describe.skip`).
+ * 2. **Tautological assertions** — `expect(<literal>)` (or `expect.soft(...)`)
+ *    whose matcher argument is also a literal (or absent): `expect(true).toBe(true)`,
+ *    `expect(1 === 1).toBe(true)`, `expect([]).toEqual([])`, `assert(true)`. These
+ *    are *worse* than a skip, because they report as PASSING.
+ * 3. **Empty test bodies** — `it('x', () => {})`. Same failure mode as (2): a
+ *    listed, green case that asserts nothing. `describe` is exempt; an empty
+ *    suite claims no case of its own.
+ *
+ * ## What this rule does NOT catch — read this before trusting it
+ *
+ * The coherence audit that motivated this rule found **9** instances of tests
+ * that asserted something other than what their name claimed. This rule catches
+ * **3 of the 9**. The other 6 were live, green, PASSING tests that asserted the
+ * wrong thing — a linter cannot see those, because nothing about their syntax is
+ * wrong. No amount of tightening this rule will reach them.
+ *
+ * The real control for that class is a convention, not a lint rule: **every
+ * assertion of absence sits beside a positive control on the same fixture.** If
+ * a test asserts "no issue was reported", a sibling assertion on the same
+ * fixture must prove the detector fires at all — otherwise a detector that never
+ * runs is indistinguishable from a detector that correctly found nothing.
+ *
+ * Worked shape: a suppression test asserts the issue list is empty, and its
+ * sibling asserts the *same* fixture produces the issue when suppression is
+ * turned off. The pair is what makes the empty result meaningful; either half
+ * alone proves nothing.
+ *
+ * Treat this rule as the cheap 3/9, not as coverage of the problem.
+ *
+ * ## Escape hatch — the annotation grammar
+ *
+ * A flagged call is exempt when a comment on the same line, or on the line
+ * immediately above, matches exactly one shape:
+ *
+ *     /\bSKIP\(#\d+\):\s*\S/
+ *
+ * i.e. `SKIP(#163): references[] not populated by the extractor yet`. Three
+ * parts are all required: the uppercase keyword `SKIP`, a `#`-prefixed GitHub
+ * issue number, and a non-empty reason after the colon. A bare
+ * `// fix this later` does not qualify — an escape hatch that accepts any
+ * comment is not an escape hatch, it is an off switch.
+ *
+ * Why `SKIP(` and not the more natural `TODO(`: this repo runs
+ * `sonarjs/todo-tag` at error level, which bans the `TODO` token in comments
+ * outright. A grammar built on `TODO(#N)` would be unusable — every
+ * annotation would trip a second rule. One keyword, and it is `SKIP`.
+ *
+ * Grep the whole tree for outstanding debt with: `rg 'SKIP\(#'`
+ *
+ * @example
+ * // BAD — silently claims a case the suite never runs
+ * it.skip('validates broken links', () => { ... });
+ *
+ * // BAD — reports as PASSING while asserting nothing
+ * expect(true).toBe(true);
+ *
+ * // GOOD — a condition, not a claim of coverage
+ * it.skipIf(process.platform === 'win32')('uses POSIX permissions', () => { ... });
+ *
+ * // GOOD — annotated with a tracking issue and a reason
+ * // SKIP(#163): references[] not populated by the extractor yet
+ * it.skip('REFERENCE_TARGET_MISSING', () => { ... });
+ */
+
+/** Test-runner globals whose `.skip` / `.todo` members disable a case. */
+const TEST_ROOTS = new Set(['it', 'test', 'describe', 'suite']);
+
+/** Roots whose empty-bodied call is a case that asserts nothing. `describe` is not one. */
+const EMPTY_BODY_ROOTS = new Set(['it', 'test']);
+
+/** Members that disable a case unconditionally. `skipIf` / `runIf` are NOT here. */
+const DISABLING_MEMBERS = new Set(['skip', 'todo']);
+
+/** Bare-identifier aliases for the same thing. */
+const DISABLING_ALIASES = new Set(['xit', 'xdescribe', 'xtest', 'xspecify']);
+
+/** Identifiers that are literal values rather than references. */
+const LITERAL_IDENTIFIERS = new Set(['undefined', 'NaN', 'Infinity']);
+
+/**
+ * Annotation grammar. Deliberately narrow: keyword + `#`-issue + non-empty reason.
+ * See the module doc comment.
+ */
+const JUSTIFICATION_PATTERN = /\bSKIP\(#\d+\):\s*\S/;
+
+/**
+ * True when `node` is a value that is fully known at parse time, so comparing it
+ * against another such value tells you nothing about the code under test.
+ */
+function isLiteralValue(node) {
+  if (!node) {
+    return false;
+  }
+  if (node.type === 'Literal') {
+    return true;
+  }
+  if (node.type === 'TemplateLiteral') {
+    return node.expressions.length === 0;
+  }
+  if (node.type === 'Identifier') {
+    return LITERAL_IDENTIFIERS.has(node.name);
+  }
+  if (node.type === 'UnaryExpression') {
+    return isLiteralValue(node.argument);
+  }
+  // `1 === 1`, `2 > 1` — both operands known, so the comparison is decided at parse time.
+  if (node.type === 'BinaryExpression') {
+    return isLiteralValue(node.left) && isLiteralValue(node.right);
+  }
+  // `[]`, `[1, 2]`, `{}` — a collection built entirely from known values.
+  if (node.type === 'ArrayExpression') {
+    return node.elements.every((element) => element === null || isLiteralValue(element));
+  }
+  if (node.type === 'ObjectExpression') {
+    return node.properties.every(
+      (property) => property.type === 'Property' && !property.computed && isLiteralValue(property.value),
+    );
+  }
+  return false;
+}
+
+/**
+ * Property name of a member access, whether dotted (`it.skip`) or computed with a
+ * string key (`it['skip']`). Null when the key is not knowable statically.
+ */
+function memberName(node) {
+  if (!node.computed) {
+    return node.property.type === 'Identifier' ? node.property.name : null;
+  }
+  return node.property.type === 'Literal' && typeof node.property.value === 'string'
+    ? node.property.value
+    : null;
+}
+
+/**
+ * True when a member chain bottoms out at a test-runner global, so
+ * `test.concurrent.skip` and `test.sequential.skip` count but `myLib.test.skip`
+ * does not.
+ */
+function isTestRootChain(node) {
+  let current = node;
+  while (current.type === 'MemberExpression') {
+    current = current.object;
+  }
+  return current.type === 'Identifier' && TEST_ROOTS.has(current.name);
+}
+
+/** `expect(...)` or `expect.soft(...)` — the soft variant is still an assertion. */
+function isExpectCallee(callee) {
+  if (callee.type === 'Identifier') {
+    return callee.name === 'expect';
+  }
+  return (
+    callee.type === 'MemberExpression' &&
+    callee.object.type === 'Identifier' &&
+    callee.object.name === 'expect' &&
+    memberName(callee) === 'soft'
+  );
+}
+
+/**
+ * True when a non-invoked `it.skip` is being stored under another name
+ * (`const gate = describe.skip`), which reaches every later `gate(...)` call.
+ * A ternary branch (`cond ? describe : describe.skip`) is excluded: its parent is
+ * the ConditionalExpression, not the declarator, so it stays a runtime gate.
+ */
+function isAliasAssignment(node) {
+  const { parent } = node;
+  if (!parent) {
+    return false;
+  }
+  return (
+    (parent.type === 'VariableDeclarator' && parent.init === node) ||
+    (parent.type === 'AssignmentExpression' && parent.right === node)
+  );
+}
+
+/** True when a test callback is present but its block body is empty. */
+function hasEmptyBody(callback) {
+  return (
+    Boolean(callback) &&
+    (callback.type === 'ArrowFunctionExpression' || callback.type === 'FunctionExpression') &&
+    callback.body.type === 'BlockStatement' &&
+    callback.body.body.length === 0
+  );
+}
+
+/**
+ * Walk up from `node` through any member chain hanging off it and return the
+ * CallExpression that ultimately invokes it, or null when `node` is not being
+ * called at all.
+ *
+ * Used for both halves of this rule:
+ *  - `it.skip(...)` and `it.skip.each([...])(...)` resolve to their call, so
+ *    they are reported; `(NET ? describe : describe.skip)(...)` and
+ *    `const d = cond ? describe : describe.skip` resolve to null, because the
+ *    member expression is a ternary branch rather than a callee. That ternary
+ *    is a runtime gate — the same thing skipIf() expresses — so it must not be
+ *    flagged. (Both shapes exist in this repo; the first draft of this rule
+ *    flagged them and was wrong.)
+ *  - `expect(x)` resolves through `.not` / `.resolves` / `.toBe` to the
+ *    matcher call.
+ */
+function resolveInvocation(node) {
+  let current = node;
+  let parent = current.parent;
+  while (parent?.type === 'MemberExpression' && parent.object === current) {
+    current = parent;
+    parent = current.parent;
+  }
+  if (parent?.type === 'CallExpression' && parent.callee === current) {
+    return parent;
+  }
+  return null;
+}
+
+/** Collect every source line covered by a justification comment. */
+function collectJustifiedLines(sourceCode) {
+  const lines = new Set();
+  for (const comment of sourceCode.getAllComments()) {
+    if (!JUSTIFICATION_PATTERN.test(comment.value)) {
+      continue;
+    }
+    for (let line = comment.loc.start.line; line <= comment.loc.end.line; line++) {
+      lines.add(line);
+    }
+  }
+  return lines;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require a tracking-issue justification for skipped tests, and ban tautological assertions',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    schema: [],
+    messages: {
+      unconditionalSkip:
+        'This test is disabled unconditionally, so the suite lists a case it never runs. ' +
+        "Fix it, delete it, or annotate it with a tracking issue: '// SKIP(#123): reason' " +
+        'on the line above. A platform or environment gate should use skipIf()/runIf() ' +
+        'instead — a condition is not a skip.',
+      tautologicalAssertion:
+        'This assertion compares literals, so it passes no matter what the code does — ' +
+        'worse than a skip, because it reports as PASSING. Assert on a value produced by ' +
+        'the code under test, or delete the assertion. If the literal really is the subject, ' +
+        "annotate it: '// SKIP(#123): reason'.",
+      emptyTestBody:
+        'This test has an empty body, so it asserts nothing while reporting as PASSING. ' +
+        'Give it an assertion, delete it, or — if the case is real but not written yet — ' +
+        "make the gap visible with it.todo() plus '// SKIP(#123): reason'.",
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    let justifiedLines = null;
+
+    /** A finding is exempt when annotated on its own line or the line above. */
+    function isJustified(node) {
+      justifiedLines ??= collectJustifiedLines(sourceCode);
+      const line = node.loc.start.line;
+      return justifiedLines.has(line) || justifiedLines.has(line - 1);
+    }
+
+    function report(node, messageId) {
+      if (!isJustified(node)) {
+        context.report({ node, messageId });
+      }
+    }
+
+    return {
+      // `it.skip`, `describe.todo`, and the `it.skip.each(...)` chain (whose
+      // inner member expression is `it.skip`).
+      MemberExpression(node) {
+        if (!DISABLING_MEMBERS.has(memberName(node)) || !isTestRootChain(node.object)) {
+          return;
+        }
+        // Only an invoked skip disables a case, or an alias that will be invoked
+        // later. A ternary branch is a gate.
+        if (!resolveInvocation(node) && !isAliasAssignment(node)) {
+          return;
+        }
+        report(node, 'unconditionalSkip');
+      },
+
+      CallExpression(node) {
+        // `xit(...)` / `xdescribe(...)` aliases.
+        if (node.callee.type === 'Identifier' && DISABLING_ALIASES.has(node.callee.name)) {
+          report(node, 'unconditionalSkip');
+          return;
+        }
+
+        // `it('x', () => {})` — a listed case whose body asserts nothing, yet PASSES.
+        if (node.callee.type === 'Identifier' && EMPTY_BODY_ROOTS.has(node.callee.name)) {
+          if (hasEmptyBody(node.arguments[1])) {
+            report(node, 'emptyTestBody');
+          }
+          return;
+        }
+
+        // `assert(true)` — never fails. `assert(false, 'unreachable')` is a real
+        // guard, so only the always-true spelling is reported.
+        if (node.callee.type === 'Identifier' && node.callee.name === 'assert') {
+          if (node.arguments[0]?.type === 'Literal' && node.arguments[0].value === true) {
+            report(node, 'tautologicalAssertion');
+          }
+          return;
+        }
+
+        // `expect(<literal>).<matcher>(<literal>?)`
+        if (!isExpectCallee(node.callee)) {
+          return;
+        }
+        if (node.arguments.length !== 1 || !isLiteralValue(node.arguments[0])) {
+          return;
+        }
+        const matcherCall = resolveInvocation(node);
+        if (matcherCall?.arguments.every((argument) => isLiteralValue(argument))) {
+          report(matcherCall, 'tautologicalAssertion');
+        }
+      },
+    };
+  },
+};

package/eslint/rules/safe-import.cjs

@@ -0,0 +1,141 @@
+/**
+ * Where each safe replacement lives, and whether it is already in scope.
+ *
+ * ## Why the autofix targets a SUBPATH and not the barrel
+ *
+ * `@vibe-agent-toolkit/utils` publishes fifteen entry points. `safePath` and
+ * `toForwardSlash` are reachable from `./path`, which pulls in nothing but
+ * `node:path`; the barrel drags five third-party dependencies behind it. Every
+ * rule in this pack used to autofix to the barrel while the README table shipped
+ * beside it named the narrow subpath — so a release whose entire purpose was
+ * narrow subpaths shipped lint rules that mechanically rewrote code AWAY from
+ * them, one autofix at a time. An adopter running the pack over 4,670 files hit
+ * 4,719 such sites.
+ *
+ * Naming the modules once, here, is what keeps the fixer, the error message and
+ * the README from drifting apart again: a rule that hardcodes its own copy of
+ * the string is how the first divergence happened.
+ *
+ * ## Why `isNameAlreadyBound` exists
+ *
+ * A fixer that adds `import { safePath } from '<target>'` to a file that already
+ * imports `safePath` from somewhere else does not produce a redundant import —
+ * it produces `SyntaxError: Identifier 'safePath' has already been declared`.
+ *
+ * That was latent while the target WAS the barrel (the fixer's own "do I already
+ * import from the target?" check happened to cover the only module anyone
+ * imported from). Pointing the fixer at `./path` makes it live for exactly the
+ * population being migrated: every file that already reaches the helpers through
+ * the barrel. So the check has to be "is this NAME bound?", not "did I see an
+ * import from MY module?".
+ *
+ * Scope analysis rather than import scanning, because a top-level
+ * `const safePath = ...` collides just as fatally as an import does.
+ */
+
+const { EXEMPT_FILES_SCHEMA } = require('./exempt-path-matcher.cjs');
+
+const PACKAGE_NAME = '@vibe-agent-toolkit/utils';
+
+/** `safePath`, `toForwardSlash`. */
+const SAFE_PATH_MODULE = `${PACKAGE_NAME}/path`;
+/** `normalizePath`, `normalizedTmpdir`, `mkdirSyncReal`, `resolveFromImportMeta`, `dynamicImportPath`. */
+const SAFE_FS_MODULE = `${PACKAGE_NAME}/fs`;
+/** `safeExecSync`. */
+const SAFE_PROCESS_MODULE = `${PACKAGE_NAME}/process`;
+
+/**
+ * Is `name` already bound at the top level of the linted file?
+ *
+ * Checks the module scope (or the global scope for `sourceType: 'script'`), which
+ * is where an added `import` declaration would land. A binding of the same name
+ * inside a nested function is deliberately NOT a conflict — an import at the top
+ * of the file is still legal, it is merely shadowed there.
+ *
+ * @param {object} sourceCode - ESLint `SourceCode` for the file being linted.
+ * @param {string} name - The identifier the fixer wants to import.
+ * @returns {boolean} True when adding an import of `name` would redeclare it.
+ */
+function isNameAlreadyBound(sourceCode, name) {
+  const globalScope = sourceCode.getScope(sourceCode.ast);
+  // `getScope(Program)` hands back the GLOBAL scope, not the module scope —
+  // and every `import` binding lives in the module scope, which is its child.
+  // Reading `globalScope.variables` alone finds nothing and the check silently
+  // answers "not bound" for every ES module, i.e. exactly the files it exists
+  // to protect. (RuleTester caught this: the fix emitted a duplicate binding.)
+  const moduleScope = globalScope.childScopes.find((child) => child.type === 'module');
+  const scope = moduleScope ?? globalScope;
+  return scope.variables.some((variable) => variable.name === name);
+}
+
+/**
+ * The `safeModule` rule option: point the fixer at YOUR re-export seam.
+ *
+ * The narrow-subpath defaults above are right for a consumer importing this
+ * package directly, and wrong for one that re-exports the helpers through its
+ * own module. An adopter measured the difference: of the 61 packages in their
+ * workspace that would receive a new import, **52 (620 files) do not declare
+ * `@vibe-agent-toolkit/utils` at all**. Under pnpm's isolated `node_modules` an
+ * undeclared import does not degrade — it fails to resolve. Across their top 25
+ * affected packages our default resolved in 0; their own seam resolved in 24.
+ * So the autofix is only as useful as its ability to name a specifier that
+ * resolves where the fix lands, and only the consuming repo knows what that is.
+ *
+ * PER-RULE rather than one shared `settings` key, because a seam does not have
+ * to split its symbols the way this package does. The same adopter's narrow
+ * entry carries `normalizedTmpdir`/`mkdirSyncReal` but NOT `safePath`, so their
+ * `no-os-tmpdir` and `no-path-join` need different targets — the exact "path
+ * rules here, fs rules there" case a single key cannot express.
+ */
+const SAFE_MODULE_PROPERTY = Object.freeze({
+  type: 'string',
+  minLength: 1,
+});
+
+/**
+ * Add the `safeModule` property to a rule's options schema.
+ *
+ * `additionalProperties: false` is preserved deliberately: a typo'd `safeModules`
+ * must be a loud config error, not a silently ignored override that leaves the
+ * fixer writing the default specifier into every file.
+ *
+ * @param {object} [schema] - Existing options-object schema to extend.
+ * @returns {object} Frozen schema accepting `safeModule` alongside `schema`'s own keys.
+ */
+function withSafeModuleOption(schema) {
+  return Object.freeze({
+    type: 'object',
+    properties: { ...schema?.properties, safeModule: SAFE_MODULE_PROPERTY },
+    additionalProperties: false,
+  });
+}
+
+/** Options schema for rules that take BOTH `exemptFiles` and `safeModule`. */
+const EXEMPT_AND_SAFE_MODULE_SCHEMA = withSafeModuleOption(EXEMPT_FILES_SCHEMA);
+
+/** Options schema for rules that only name a module in their advice text. */
+const SAFE_MODULE_ONLY_SCHEMA = withSafeModuleOption();
+
+/**
+ * The module this rule should name, for this rule invocation.
+ *
+ * @param {object} context - ESLint rule context.
+ * @param {string} fallbackModule - The rule's narrow-subpath default.
+ * @returns {string} The configured `safeModule`, or the default.
+ */
+function resolveSafeModule(context, fallbackModule) {
+  const configured = context.options?.[0]?.safeModule;
+  return typeof configured === 'string' && configured.length > 0 ? configured : fallbackModule;
+}
+
+module.exports = {
+  EXEMPT_AND_SAFE_MODULE_SCHEMA,
+  PACKAGE_NAME,
+  SAFE_FS_MODULE,
+  SAFE_MODULE_ONLY_SCHEMA,
+  SAFE_PATH_MODULE,
+  SAFE_PROCESS_MODULE,
+  isNameAlreadyBound,
+  resolveSafeModule,
+  withSafeModuleOption,
+};

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "@vibe-agent-toolkit/utils",
-  "version": "0.1.41",
+  "version": "0.1.42-rc.1",
   "type": "module",
   "description": "Core utility functions shared across the vibe-agent-toolkit packages",
   "sideEffects": false,
   "keywords": [
     "typescript",
     "utilities",
-    "toolkit"
+    "toolkit",
+    "cross-platform",
+    "windows",
+    "eslint"
   ],
   "author": "Jeff Dutton",
   "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -18,17 +24,63 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./process": {
-      "types": "./dist/process.d.ts",
-      "import": "./dist/process.js"
+    "./path": {
+      "types": "./dist/path.d.ts",
+      "import": "./dist/path.js"
     },
     "./fs": {
       "types": "./dist/fs.d.ts",
       "import": "./dist/fs.js"
-    }
+    },
+    "./process": {
+      "types": "./dist/process.d.ts",
+      "import": "./dist/process.js"
+    },
+    "./git": {
+      "types": "./dist/git.d.ts",
+      "import": "./dist/git.js"
+    },
+    "./glob": {
+      "types": "./dist/glob.d.ts",
+      "import": "./dist/glob.js"
+    },
+    "./zod": {
+      "types": "./dist/zod.d.ts",
+      "import": "./dist/zod.js"
+    },
+    "./template": {
+      "types": "./dist/template-entry.d.ts",
+      "import": "./dist/template-entry.js"
+    },
+    "./yaml": {
+      "types": "./dist/yaml.d.ts",
+      "import": "./dist/yaml.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./asset": {
+      "types": "./dist/asset.d.ts",
+      "import": "./dist/asset.js"
+    },
+    "./crawl": {
+      "types": "./dist/crawl.d.ts",
+      "import": "./dist/crawl.js"
+    },
+    "./project": {
+      "types": "./dist/project.d.ts",
+      "import": "./dist/project.js"
+    },
+    "./eslint": {
+      "types": "./eslint/index.d.cts",
+      "default": "./eslint/index.cjs"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "eslint",
     "README.md"
   ],
   "scripts": {
@@ -48,11 +100,17 @@
     "yaml": "^2.6.1"
   },
   "peerDependencies": {
-    "zod": "^3.25.0 || ^4.0.0"
+    "eslint": ">=9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/picomatch": "^4.0.2",
     "@types/which": "^3.0.4",
+    "eslint": "^9.39.5",
     "rimraf": "^6.0.1",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",