@vibe-agent-toolkit/utils 0.1.41 → 0.1.42

package/eslint/README.md

@@ -0,0 +1,217 @@
+# `@vibe-agent-toolkit/utils/eslint`
+
+ESLint rules that enforce the cross-platform and agentic-code safety helpers in the rest of [`@vibe-agent-toolkit/utils`](https://www.npmjs.com/package/@vibe-agent-toolkit/utils).
+
+Twenty-one rules, all of them derived from a bug that actually shipped: `os.tmpdir()` returning an 8.3 short path on a Windows CI runner, `path.join()` producing backslashes that then failed a string comparison, `await import(absolutePath)` throwing on Windows without a `file://` URL, `execSync()` interpolating a caller-controlled string into a shell. Most auto-fix.
+
+## Installation
+
+```bash
+bun add @vibe-agent-toolkit/utils
+```
+
+There is no separate plugin package: the rules are a subpath of the package whose helpers they enforce, so the two can never drift to different versions. Requires ESLint 9+ (flat config) and Node >= 22.
+
+`eslint` is an **optional** peer dependency, and this subpath adds no dependency to the others. An ESLint plugin is data, not code that runs — every rule module here exports a plain object and none of them `require('eslint')` — so installing `utils` for `safePath.join()` alone pulls in nothing extra and warns about nothing.
+
+## Usage
+
+```js
+// eslint.config.js
+import vat from '@vibe-agent-toolkit/utils/eslint';
+
+export default [
+  vat.configs.recommended,
+];
+```
+
+`configs.recommended` registers the plugin under the `@vibe-agent-toolkit` namespace and enables the **cross-platform safety core** — 18 of the 21 rules, most at `error` and three at `warn` (see [Severities](#severities)). The other three are opt-in; the [rule tables](#rules) mark each rule's `recommended` severity, and `—` means not in `recommended`.
+
+To pick rules yourself, register the plugin and name them:
+
+```js
+import vat from '@vibe-agent-toolkit/utils/eslint';
+
+export default [
+  {
+    files: ['**/*.{ts,tsx,js,cjs,mjs}'],
+    plugins: { '@vibe-agent-toolkit': vat },
+    rules: {
+      '@vibe-agent-toolkit/no-path-join': 'error',
+      '@vibe-agent-toolkit/no-os-tmpdir': 'error',
+    },
+  },
+];
+```
+
+### Exempting the file that implements the wrapper
+
+A rule that bans `os.tmpdir()` has to let *something* call it — the file that implements your `normalizedTmpdir()`. That file's path is a fact about your repo, so the plugin ships **no** built-in exemptions; you declare them:
+
+```js
+'@vibe-agent-toolkit/no-os-tmpdir': ['error', { exemptFiles: ['src/paths.ts'] }],
+'@vibe-agent-toolkit/no-path-join': ['error', { exemptFiles: [
+  'src/paths.ts',
+  'test/paths.test.ts',   // asserts the platform-native behavior the wrapper hides
+] }],
+```
+
+Paths are repo-relative and matched at a **path-segment boundary**, never as a substring: declaring `src/paths.ts` does not exempt `tools/hooks/paths.ts`, `src/my-paths.ts`, or `src/paths.ts.bak`. (It used to be a substring check. A private `tools/hooks/path-utils.ts` full of raw `tmpdir()` calls linted clean for months.) Matching is separator-agnostic, so the same list works on Windows.
+
+The match is anchored at the **end** of the path, so a declaration is a suffix: `src/paths.ts` also exempts `packages/anything/src/paths.ts`. Name enough leading segments to be unambiguous in your tree (this repo declares `packages/utils/src/path-utils.ts`, not `path-utils.ts`).
+
+Taken to its limit, a **bare filename with no `/` exempts that filename everywhere in the repo** — including files added later by someone who never read the config. The rules report that as `unanchoredExemptFile` rather than letting it pass, because it is the same repo-wide hole the segment-boundary matching exists to close. `./paths.ts` is the same hole with a slash in it, so the check runs on the normalized entry, not the raw string.
+
+The option **replaces** any default rather than merging with it, and unknown option keys are a config error — a typo'd `exemptFile` must fail loudly rather than quietly exempt nothing.
+
+The rules taking `exemptFiles` are `no-path-join`, `no-path-resolve`, `no-path-relative`, `no-os-tmpdir`, `no-fs-mkdirSync`, `no-fs-realpathSync`, `no-child-process-execSync`, and `no-fs-promises-cp`.
+
+## Rules
+
+The "use instead" column names the `@vibe-agent-toolkit/utils` subpath the replacement lives on; ✓ marks an auto-fix. The **`recommended`** column is the severity `configs.recommended` assigns — `—` means the rule is **not** in `recommended` and must be enabled explicitly.
+
+**The auto-fix writes the import to the subpath in that column**, not to the barrel — `--fix` on a raw `path.join()` inserts `import { safePath } from '@vibe-agent-toolkit/utils/path'`. A file that already reaches the helper through the barrel keeps its existing import and only has the call rewritten: adding a second binding of the same name is a `SyntaxError`, not a redundant import.
+
+### Pointing the fix at your own re-export seam — `safeModule`
+
+If your repo re-exports these helpers through its own module, the defaults above are wrong for you, and not merely stylistically: in a workspace with isolated `node_modules` (pnpm, Yarn PnP), an import of a package the receiving package does not declare **fails to resolve**. One adopter measured 620 files across 52 such packages. Point the rule at the module that resolves where the fix lands:
+
+```js
+'@vibe-agent-toolkit/no-path-join':  ['warn',  { safeModule: '@acme/dev-tools/paths' }],
+'@vibe-agent-toolkit/no-os-tmpdir':  ['error', { safeModule: '@acme/dev-tools/fs' }],
+```
+
+It is **per-rule**, not one shared `settings` key, because a seam need not split its symbols the way this package does — an adopter whose narrow entry carried `normalizedTmpdir()` but not `safePath` needed the two rules pointed at different modules, which a single key cannot express. Note the two lines above therefore name *different* modules. It composes with `exemptFiles`, and it changes the error message as well as the fix, so the advice never names a module you don't use. Every rule that names a module accepts it, including the ones that only advise and never fix.
+
+> **Point each rule at a module that exports the symbol *that rule writes*, not merely one that resolves.** This is the failure mode worth spending a minute on, because it is the quiet one. A `safeModule` that doesn't resolve fails loudly and immediately. A `safeModule` that resolves but lacks the symbol passes every resolution check — including an explicit `import()` probe — and then throws `Cannot read properties of undefined` at each call site, once per fixed file. Aim `no-path-join` at an entry without `safePath` and you get a green `--fix`, a green install, and thousands of latent `TypeError`s. The rules cannot check this for you: verifying it would mean resolving and importing your module from inside the linter, which is neither its job nor reliable from wherever ESLint happens to be running.
+
+Two ways your target can be wrong, which surface differently: `ERR_MODULE_NOT_FOUND` means the receiving package doesn't declare it at all, while `ERR_PACKAGE_PATH_NOT_EXPORTED` means it does — but the version resolved *at that location* doesn't export the subpath. In a monorepo mid-upgrade those differ, so the question is never "does the package declare it" but "does the resolved version there export it."
+
+### Path handling
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `no-path-join` | `path.join()` | `safePath.join()` | `/path` | ✓ | `warn` |
+| `no-path-resolve` | `path.resolve()` | `safePath.resolve()` | `/path` | ✓ | `warn` |
+| `no-path-relative` | `path.relative()` | `safePath.relative()` | `/path` | ✓ | `warn` |
+| `no-path-startswith` | `path.startsWith()` on a raw path | `toForwardSlash()` first | `/path` | | `error` |
+| `no-hardcoded-path-split` | `split('/')` / `split('\\')` on a path | `path.basename()`, or `toForwardSlash()` first | `/path` | | `error` |
+| `no-path-sep-in-strings` | `path.sep` embedded in a string literal | `toForwardSlash()` | `/path` | | `error` |
+| `no-manual-path-normalize` | hand-rolled `.replace(/\\/g, '/')` | `toForwardSlash()` | `/path` | ✓ | `error` |
+| `no-path-operations-in-comparisons` | raw `path.*()` results in string comparisons | wrap in `toForwardSlash()` | `/path` | | `error` |
+| `no-unsafe-root-join` | `safePath.join(someRoot, x)` where `x` can escape | `safePath.joinUnderRoot()` | `/path` | | — |
+
+### Filesystem and process
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `no-os-tmpdir` | `os.tmpdir()` (8.3 short names on Windows) | `normalizedTmpdir()` | `/fs` | ✓ | `error` |
+| `no-fs-realpathSync` | `fs.realpathSync()` | `normalizePath()` | `/fs` | ✓ | `error` |
+| `no-fs-mkdirSync` | `fs.mkdirSync()` | `mkdirSyncReal()` | `/fs` | ✓ | `error` |
+| `no-fs-promises-cp` | `cp()` from `node:fs/promises` (drops nested files on Node 22) | `cpSync()` from `node:fs` | — | ✓ | `error` |
+| `no-child-process-execSync` | `child_process.execSync()` | `safeExecSync()` | `/process` | ✓ | `error` |
+| `no-unix-shell-commands` | `tar`, `grep`, `rm`, `echo`, … spawned directly | Node APIs, or a portable script fixture | — | | `error` |
+
+The member-call rules here check the **receiver**, not just the method name, so `env.tmpdir()` on some unrelated object is not a finding — and the namespace they check for can be bound by a static `import * as os`, by `const os = require('node:os')`, or by `const os = await import('node:os')`. The fix replaces the whole callee (`os.tmpdir()` → `normalizedTmpdir()`), which is correct however the binding was made. Matching the method name alone was the earlier behaviour and it produced `os.normalizedTmpdir()` — a method that does not exist, compiles, and throws.
+
+### URLs and dynamic imports
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `no-url-pathname-for-fs` | `new URL(x, import.meta.url).pathname` as a filesystem path | `resolveFromImportMeta()` / `fileURLToPath()` | `/fs` | | `error` |
+| `no-bare-dynamic-import-path` | `await import(absolutePath)` | `dynamicImportPath()` / `pathToFileURL(p).href` | `/fs` | | `error` |
+| `no-file-url-string-concat` | `` `file://${p}` `` | `pathToFileURL(p).href` | — | | `error` |
+
+### Code and test hygiene
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `prefer-startswith-over-regex` | `/^foo/.test(s)`, `` /^\*glob/.test(s) ``, `const RE = /^foo/; RE.test(s)` | `s.startsWith('foo')` | — | | `error` |
+| `no-test-scoped-functions` | helper functions declared inside `describe`/`it` | module scope | — | | — |
+| `require-justified-skip` | unannotated `it.skip`/`it.todo`, tautological assertions, empty test bodies | a `SKIP(#123): reason` annotation, or a real assertion | — | | — |
+
+### What `recommended` deliberately leaves out
+
+Three rules ship without riding in `recommended`, for two different reasons.
+
+**Test-style opinions** — `no-test-scoped-functions` (where a helper may be declared) and `require-justified-skip` (the annotation grammar for a disabled test). Neither is a portability or correctness fact, and installing this package for `safePath.join()` should not also import someone else's test conventions. Both are worth turning on deliberately.
+
+**Unsound, pending a rewrite** — `no-unsafe-root-join`. It keys on whether an identifier's *name* ends in `root` rather than on whether any segment is caller-controlled, which makes it noisy and blind at the same time. Measured against 4,670 files of real adopter source: 108 findings, none autofixable. Verified behaviour:
+
+```js
+safePath.join(repoRoot, 'docs', 'product')  // FIRES — all literals, nothing can escape
+safePath.resolve(packageRoot, '..', '..')   // FIRES — escaping is the intent; the fix breaks it
+safePath.join(repoRoot)                     // FIRES — one argument, no segment at all
+safePath.join(base, userInput)              // SILENT — the shape it exists to catch
+```
+
+A rule that misses its own target does not belong in a config named `recommended` at any severity: a safety core that cries wolf teaches people to ignore it, and that costs you the true positives too. It still ships, and it still earns `error` when scoped to directories where a path escape is a security boundary — which is how this repo uses it, on its skill-test staging code. It will return to `recommended` when it keys on taint rather than on naming.
+
+Enable any of the three by naming it:
+
+```js
+import vat from '@vibe-agent-toolkit/utils/eslint';
+
+export default [
+  vat.configs.recommended,
+  {
+    rules: {
+      '@vibe-agent-toolkit/no-test-scoped-functions': 'error',
+      '@vibe-agent-toolkit/require-justified-skip': 'error',
+    },
+  },
+  {
+    // Scope it to where an escape is a security boundary, not repo-wide.
+    files: ['src/staging/**/*.ts'],
+    rules: { '@vibe-agent-toolkit/no-unsafe-root-join': 'error' },
+  },
+];
+```
+
+### Severities
+
+Within `recommended`, `error` is the default; three rules are `warn`:
+
+- **`no-path-join`, `no-path-resolve`, `no-path-relative`** — by far the highest-churn rules; they fire on every raw `node:path` call in an existing codebase. Measured on a 4,670-file adopter tree: 3,963 + 372 + 1 findings, **every one of them autofixable**. `warn` lets a project run `--fix` and burn the list down incrementally instead of blocking CI on day one.
+
+Raise all three to `error` once the backlog is clear. That is what this repo does.
+
+The criterion for `warn` is **migration volume**, not how real the finding is — a rule whose findings we doubted would be out of `recommended` entirely, not demoted. Everything at `error` either prevents a bug or moves a static-analysis finding left of a merge.
+
+### Running `--fix` over a large backlog
+
+Every rule that rewrites a call *and* edits imports fixes **all** of a file's call sites in a single pass, and `packages/utils/test/eslint/rules.test.ts` holds each of them to that: it runs `--fix` to its fixpoint and then asks `no-undef` whether the result still binds every identifier.
+
+That test exists because the answer used to be no. ESLint merges the fixes one `fix()` yields into a **single range spanning `min..max`**, and applies only non-overlapping ranges per pass — so a fix touching both the import and its own call site spanned everything in between, N call sites produced N nested ranges, and ESLint kept one. The rule then went quiet, because the import specifier its detection keyed on was what had just been removed. `--fix` reached a stable fixpoint over source that no longer compiles and exited clean; you found out at `tsc`. An adopter measured **146 files left with a dangling reference** across one ~4,900-site sweep, worst single file 75 unrewritten calls.
+
+`eslint-disable` interacts with this in a way worth knowing about, because it is not obvious and it took an adversarial run to find. ESLint invokes a rule's `fix()` **before** the disable filter discards the problem, so a suppressed report still consumes any once-per-file edit its rule was holding. Where that edit is an import *insert*, the rules either re-emit it from every report or carry a repair leg that recognises the orphaned call and supplies the missing import on the next pass — so a disabled call site costs an extra pass, not a broken file. Where it is an import *removal*, the removal is latched and simply goes away with the discarded report, leaving an unused import for `no-unused-vars` to point at rather than a call with nothing behind it. `exemptFiles` remains the supported way to opt a whole file out.
+
+Two more things a fixer here will not do: delete a `type`-only, aliased, or re-exported specifier (removing a re-exported one produced output that did not parse), and insert an import *between* a leading `eslint-disable-next-line` and the statement it protects, which would silently revoke the suppression.
+
+#### The binding left behind
+
+`path.join(a, b)` becomes `safePath.join(a, b)`, and when that was the file's last `path.*` reference the `import path from 'node:path'` is left bound to nothing. That is not a dangling reference, so the `no-undef` fixpoint check above is blind to it — and the same adopter measured **536 errors surviving a converged `--fix` across 232 files** (289 `no-unused-vars`, 247 `sonarjs/unused-import`), every one of them this. In a repo gating at `--max-warnings=0`, `--fix` output that does not lint clean is not a finished migration.
+
+So the rules now report it themselves, as a separate `deadUnsafeImport` finding on the import line with its own fix. Being its own finding is the point: it shows up in lint output and you can `eslint-disable` it, rather than a call rewrite quietly taking a declaration with it.
+
+Deliberately narrow:
+
+- **A closed list of modules** — `node:path`, `node:os`, `node:fs`, `node:fs/promises`, `node:child_process` and their bare spellings. All Node builtins, all side-effect-free with certainty decided when the rule was written. This is *not* a general unused-import rule and will not become one; for blanket cleanup, `eslint-plugin-unused-imports` already exists and already autofixes.
+- **Only in a file these rules migrated** — the safe symbol must already be bound. A dead import in a file this pack never touched is somebody else's business.
+- **Only whole declarations, only with zero references left** — evaluated against the source as it stands on that pass, so the removal always lands *after* the rewrite that consumed the last reference, never speculatively beside it. A partially-dead declaration (`import path, { sep }` with `sep` still live) is left alone, as are bare `import 'node:path'` side-effect imports and anything carrying a `type` specifier.
+
+This cannot be delegated: `@typescript-eslint/no-unused-vars` declares `meta.fixable: 'code'` but emits only a **suggestion** for an unused import, and `--fix` never applies suggestions; `sonarjs/unused-import` declares no fixer at all. Verified with both enabled alongside these rules in one `verifyAndFix` — the import survived. Those rules abstain for a good reason, since removing an import can change behaviour; a rule that *created* the orphan knows it just consumed the last reference and knows the module, so it can act where a generic rule cannot.
+
+## Why custom rules
+
+A cross-platform safety helper is only as good as its enforcement. `safePath.join()` prevents a class of Windows bug precisely once — the moment someone writes `path.join()` instead, the helper's existence has bought nothing. Publishing the API without the lint rule ships half a product: the fix is available, and nothing directs anyone to it.
+
+What these rules buy is *when* you find out. Without them, a raw `os.tmpdir()` is found by a Windows CI job — a different machine, twenty minutes later, on someone else's push, with a failure message about a path that doesn't obviously relate to the line that caused it. With them, it is a red squiggle under the call, on the author's machine, with the replacement named in the message and usually applied by `--fix`. The bug never leaves the editor. That is the whole argument, and it is why the rules are written to name the replacement rather than merely to forbid the primitive.
+
+The second reason is agentic. When most code in a repo is written by an LLM, a convention that lives only in a style guide or a CLAUDE.md gets re-violated constantly — the model is confident, `path.join` is what it saw a million times in training, and the guidance was three thousand tokens back. A lint rule is feedback the model receives at the moment it is wrong, which is the only moment it can act on. Treat rules as the durable form of any convention you'd otherwise repeat in a prompt.
+
+Most projects will want rules the ones here don't cover, for invariants only that project has: a deprecated internal API, a logging call that must carry a request ID, a module boundary nothing may import across. These rules are readable, small, and built on two shared factories plus a segment-anchored path matcher — copy the shape. `eslint-rule-factory.cjs` handles "ban function X from module Y, suggest Z, fix the import"; `exempt-path-matcher.cjs` handles the exemption question every such rule eventually asks, and is worth reading before you write `filename.includes(...)`.
+
+## License
+
+MIT

package/eslint/index.cjs

@@ -0,0 +1,161 @@
+/**
+ * `@vibe-agent-toolkit/utils/eslint` — cross-platform and agentic-code safety rules.
+ *
+ * These rules enforce the safe helpers published by the rest of this package
+ * (`safePath.*` on `/path`, `normalizedTmpdir()`, `mkdirSyncReal()`,
+ * `normalizePath()` on `/fs`, `safeExecSync()` on `/process`). The helpers exist
+ * because the raw primitives they wrap have platform potholes; the rules exist so
+ * a call to the raw primitive fails at lint time on the author's machine rather
+ * than in CI on a different OS.
+ *
+ * They ship as a SUBPATH rather than a separate package because an ESLint plugin
+ * is data, not code that runs: every module below exports a plain rule object and
+ * none of them `require('eslint')`. So this entry resolves — and the other twelve
+ * subpaths keep resolving — whether or not ESLint is installed, which is why
+ * `eslint` is declared as an OPTIONAL peer dependency. One install, one version,
+ * no way for the rules to drift from the helpers they name.
+ *
+ * CommonJS on purpose, in an ESM package: the rule modules are `.cjs`, Node keys
+ * module format off the extension regardless of the package's `"type"`, and a CJS
+ * entry point can be both `require()`d from an `eslint.config.cjs` and `import`ed
+ * from an `eslint.config.js`/`.mjs`.
+ *
+ * Rules whose exemptions name a file (the ONE implementation file allowed to call
+ * the primitive) take an `exemptFiles` option — see README.md. The shipped
+ * defaults are EMPTY: an exemption is a claim about a specific repo's layout, and
+ * inheriting another repo's claim is how a same-named file silently opts itself
+ * out of a rule.
+ */
+
+'use strict';
+
+const rules = {
+  'no-child-process-execSync': require('./rules/no-child-process-execSync.cjs'),
+  'no-hardcoded-path-split': require('./rules/no-hardcoded-path-split.cjs'),
+  'no-path-startswith': require('./rules/no-path-startswith.cjs'),
+  'no-unix-shell-commands': require('./rules/no-unix-shell-commands.cjs'),
+  'no-os-tmpdir': require('./rules/no-os-tmpdir.cjs'),
+  'no-fs-mkdirSync': require('./rules/no-fs-mkdirSync.cjs'),
+  'no-fs-realpathSync': require('./rules/no-fs-realpathSync.cjs'),
+  'no-manual-path-normalize': require('./rules/no-manual-path-normalize.cjs'),
+  'no-path-sep-in-strings': require('./rules/no-path-sep-in-strings.cjs'),
+  'no-path-operations-in-comparisons': require('./rules/no-path-operations-in-comparisons.cjs'),
+  'no-path-join': require('./rules/no-path-join.cjs'),
+  'no-path-resolve': require('./rules/no-path-resolve.cjs'),
+  'no-path-relative': require('./rules/no-path-relative.cjs'),
+  'no-test-scoped-functions': require('./rules/no-test-scoped-functions.cjs'),
+  'no-fs-promises-cp': require('./rules/no-fs-promises-cp.cjs'),
+  'no-url-pathname-for-fs': require('./rules/no-url-pathname-for-fs.cjs'),
+  'no-bare-dynamic-import-path': require('./rules/no-bare-dynamic-import-path.cjs'),
+  'no-file-url-string-concat': require('./rules/no-file-url-string-concat.cjs'),
+  'prefer-startswith-over-regex': require('./rules/prefer-startswith-over-regex.cjs'),
+  'no-unsafe-root-join': require('./rules/no-unsafe-root-join.cjs'),
+  'require-justified-skip': require('./rules/require-justified-skip.cjs'),
+};
+
+/**
+ * Rules deliberately LEFT OUT of `configs.recommended`.
+ *
+ * `recommended` is the cross-platform-safety core: every rule in it flags a call
+ * that is wrong (or unportable) regardless of how the adopting project likes to
+ * write tests. The two below are neither — they encode a position on TEST STYLE:
+ *
+ * - `require-justified-skip` — a specific annotation grammar (`SKIP(#123): reason`)
+ *   for a disabled test, plus a view on what counts as a tautological assertion.
+ * - `no-test-scoped-functions` — a view on WHERE a test helper may be declared
+ *   (module scope, never inside `describe`/`it`).
+ *
+ * Someone installing this package for `safePath.join()` should not silently
+ * inherit either. Both ship in `rules` and stay enabled explicitly:
+ *
+ *   '@vibe-agent-toolkit/require-justified-skip': 'error',
+ *
+ * That is exactly what VAT's own `eslint.config.js` does — it does not consume
+ * `configs.recommended` at all, so this exclusion changes nothing about how this
+ * repo lints itself.
+ */
+const RECOMMENDED_EXCLUDE = new Set([
+  'require-justified-skip',
+  'no-test-scoped-functions',
+  // Excluded for a DIFFERENT reason than the two above: not a style opinion, but
+  // an unsound heuristic. It keys on whether an identifier's name ends in `root`
+  // rather than on whether any segment is caller-controlled, which makes it
+  // simultaneously noisy and blind. Measured on a 4,670-file adopter tree: 108
+  // findings, 0 autofixable, and every one of these verified by execution here:
+  //
+  //   FIRES   safePath.join(repoRoot, 'docs', 'product')  <- all literals, cannot escape
+  //   FIRES   safePath.resolve(packageRoot, '..', '..')   <- escaping IS the intent; the fix breaks it
+  //   FIRES   safePath.join(repoRoot)                     <- one argument, no segment at all
+  //   silent  safePath.join(base, userInput)              <- THE dangerous shape, missed
+  //
+  // A rule that misses the case it exists to catch must not ride in a config
+  // named `recommended` at any severity — a safety core that cries wolf teaches
+  // people to ignore it, which costs the true positives too. It still ships, and
+  // it still earns `error` where scoped to directories in which a path escape is
+  // a security boundary (this repo scopes it to the skill-test staging code).
+  // Re-include it when it keys on taint rather than on naming.
+  'no-unsafe-root-join',
+]);
+
+/**
+ * Default severities for `configs.recommended`.
+ *
+ * `error` is the default: every rule below flags a call whose replacement is a
+ * one-line swap, and a wrong answer is a real bug on some platform.
+ *
+ * `warn` is reserved for the case where a fresh adopter's first run would
+ * otherwise be a wall of blocking errors they cannot triage in one sitting:
+ * `no-path-join` / `no-path-resolve` / `no-path-relative`, the highest-churn
+ * rules by far (they fire on every raw `node:path` call in the codebase).
+ * Measured on a 4,670-file adopter tree: 3,963 + 372 + 1 findings, **all
+ * autofixable**. All three auto-fix, so `warn` lets a project run `--fix` and
+ * burn the list down incrementally instead of blocking CI on day one.
+ *
+ * Raise them to `error` once the backlog is clear — that is what VAT itself does.
+ *
+ * The criterion for `warn` is MIGRATION VOLUME, not how real the finding is. Every
+ * rule in this pack either prevents a bug or shifts a static-analysis finding left of
+ * a merge, and both are worth blocking on; what `warn` buys is a first run that reads
+ * as a backlog to `--fix` rather than a wall. `prefer-startswith-over-regex` was
+ * briefly graded on a different axis ("style, not a defect") and demoted — that was
+ * wrong twice over: avoiding a SonarQube S6557 at lint time instead of at merge time
+ * is a real saving, and the rule's matcher rejects any regex containing a
+ * metacharacter, so it only fires on true literal prefixes and has near-zero churn.
+ * It is `error`.
+ */
+const RECOMMENDED_WARN = new Set([
+  'no-path-join',
+  'no-path-resolve',
+  'no-path-relative',
+]);
+
+/**
+ * Plugin namespace an adopter gets from `configs.recommended`, and therefore the
+ * prefix on every rule id (`@vibe-agent-toolkit/no-path-join`).
+ *
+ * Deliberately the SCOPE, not the full subpath specifier: rule ids are the surface
+ * adopters type into `rules`, `eslint-disable` comments and CI baselines, and they
+ * should not have to change if the pack ever moves house again. (This repo's own
+ * config registers the same object under `local` for exactly that reason.)
+ */
+const NAMESPACE = '@vibe-agent-toolkit';
+
+const plugin = {
+  meta: {
+    name: '@vibe-agent-toolkit/utils/eslint',
+  },
+  rules,
+  configs: {},
+};
+
+plugin.configs.recommended = {
+  name: '@vibe-agent-toolkit/utils/eslint/recommended',
+  plugins: { [NAMESPACE]: plugin },
+  rules: Object.fromEntries(
+    Object.keys(rules)
+      .filter((name) => !RECOMMENDED_EXCLUDE.has(name))
+      .map((name) => [`${NAMESPACE}/${name}`, RECOMMENDED_WARN.has(name) ? 'warn' : 'error']),
+  ),
+};
+
+module.exports = plugin;

package/eslint/index.d.cts

@@ -0,0 +1,60 @@
+/**
+ * Types for `@vibe-agent-toolkit/utils/eslint`.
+ *
+ * Hand-written, and deliberately structural rather than `import type { ESLint }
+ * from 'eslint'`: `eslint` is an OPTIONAL peer dependency, so a consumer who took
+ * this package for `safePath.join()` has no `eslint` types installed, and a
+ * reference to them here would turn this entry into a type error for exactly the
+ * people the optional peer exists to spare. The shapes below are the subset flat
+ * config consumes, and are structurally assignable to `ESLint.Plugin`.
+ *
+ * `export =`, not `export default`: the implementation ends in
+ * `module.exports = plugin`, and `export =` is the only declaration form that says
+ * so. Consumers with `esModuleInterop` (the default for this repo's base config)
+ * still write `import vat from '@vibe-agent-toolkit/utils/eslint'`.
+ *
+ * `.d.cts`, not `.d.ts`: under `moduleResolution: node16`/`nodenext` TypeScript
+ * matches the declaration's extension to the module format of the file it
+ * describes, and `index.cjs` is CommonJS inside a `"type": "module"` package.
+ *
+ * This file exists because `eslint.config.ts` is supported from ESLint 9.18.
+ * Without it, an adopter writing one gets TS7016 on the import. It is NOT covered
+ * by `bun run typecheck` (utils' tsconfig includes only `src/**‍/*.ts`), so the
+ * packaged-artifact integration test compiles a consumer fixture against it
+ * instead — see `test/integration/eslint-recommended-config.integration.test.ts`.
+ */
+
+declare const plugin: plugin.Plugin;
+
+declare namespace plugin {
+  /** A rule module, opaque here — adopters hand these to ESLint, never call them. */
+  interface RuleModule {
+    meta?: Record<string, unknown>;
+    create: (context: unknown) => Record<string, unknown>;
+  }
+
+  /** A flat-config object, as returned by `configs.recommended`. */
+  interface FlatConfig {
+    name: string;
+    plugins: Record<string, Plugin>;
+    /** Rule id → severity. Keys are namespaced: `@vibe-agent-toolkit/no-path-join`. */
+    rules: Record<string, 'error' | 'warn' | 'off'>;
+  }
+
+  interface Plugin {
+    meta: { name: string };
+    /** Rule name WITHOUT the namespace prefix, e.g. `no-path-join`. */
+    rules: Record<string, RuleModule>;
+    configs: {
+      /**
+       * The cross-platform safety core: 18 of the 21 rules, 15 `error` / 3 `warn`.
+       * `no-test-scoped-functions` and `require-justified-skip` are excluded — they
+       * are positions on test style, not portability facts. Both still ship in
+       * `rules` and are enabled by naming them.
+       */
+      recommended: FlatConfig;
+    };
+  }
+}
+
+export = plugin;

package/eslint/rules/dead-import.cjs

@@ -0,0 +1,201 @@
+/**
+ * Removing the import binding THIS PACK's own fixers just orphaned.
+ *
+ * ## The gap this closes
+ *
+ * `path.join(a, b)` rewrites to `safePath.join(a, b)`, and when that was the
+ * file's last `path.*` reference the `import path from 'node:path'` is left
+ * bound to nothing. An adopter measured the consequence over ~5,100 sites:
+ * `--fix` converged, and **536 errors survived across 232 files** — 289
+ * `no-unused-vars` plus 247 `sonarjs/unused-import`, every one of them this same
+ * class. Their repo gates at `--max-warnings=0`, so the fixed output did not
+ * lint clean and the migration was not actually complete.
+ *
+ * The `no-undef` fixpoint check the rest of this pack leans on is structurally
+ * blind to it: a dead import leaves nothing DANGLING, it leaves something SPARE.
+ *
+ * ## Why this cannot be delegated to the ecosystem
+ *
+ * `@typescript-eslint/no-unused-vars` declares `meta.fixable: 'code'` — and for
+ * an unused import it emits only a SUGGESTION, which `--fix` never applies.
+ * `eslint-plugin-sonarjs/unused-import` declares no fixer at all. Measured on
+ * `@typescript-eslint/eslint-plugin@8.65.0`, with both rules enabled alongside
+ * ours in a single `verifyAndFix`: the import survived. `meta.fixable` is a
+ * capability flag about the RULE, not a promise about any given report.
+ *
+ * Those rules abstain for a real reason — removing an import can change
+ * behaviour (`import './polyfill'`, modules with top-level effects), and a
+ * generic rule cannot prove otherwise. A rule that CREATED the orphan is in a
+ * strictly better position: it knows it just consumed the binding's last
+ * reference, and it knows the module, because its own config named it.
+ *
+ * ## Why the module list is closed, and hardcoded
+ *
+ * Every entry is a Node builtin that this pack already targets, and every one is
+ * side-effect-free with certainty decided here, at authoring time. The only
+ * general signal available instead would be package.json `sideEffects` — author
+ * declared, unverified, absent by default (and absence means "assume side
+ * effects"), sometimes a glob array rather than a boolean, requiring filesystem
+ * resolution per import inside a linter expected to be pure and fast, and it
+ * **does not apply to `node:` builtins at all**, which is the only case here.
+ * So: no `sideEffects` lookup, no I/O, no new dependency, and deliberately NOT
+ * a general `unused-import-no-side-effects` rule. For blanket cleanup outside
+ * this list, `eslint-plugin-unused-imports` already exists and already autofixes.
+ *
+ * Bare aliases (`path`, `os`, …) are listed beside their `node:`-prefixed
+ * spellings because the rules themselves treat the two as one module. Detecting
+ * `path.join()` from `import path from 'path'` and then declining to clean up
+ * after it would leave exactly the adopter's blocker in place for whichever
+ * spelling a file happened to use.
+ */
+
+const REMOVABLE_MODULES = new Set([
+  'node:path',
+  'path',
+  'node:os',
+  'os',
+  'node:fs',
+  'fs',
+  'node:fs/promises',
+  'fs/promises',
+  'node:child_process',
+  'child_process',
+]);
+
+const DEAD_UNSAFE_IMPORT = 'deadUnsafeImport';
+const DEAD_UNSAFE_IMPORT_MESSAGE =
+  "'{{local}}' is no longer used — this rule's autofix rewrote the last call that " +
+  "referenced it. Remove the '{{module}}' import.";
+
+/**
+ * Does this declaration bring in anything the type checker alone can see?
+ *
+ * A `type` binding has zero references by construction — scope analysis does not
+ * record type positions as references — so "nothing uses it" is not evidence of
+ * anything. Deleting one silently breaks every `typeof join` and every
+ * annotation that named it, and NEITHER `no-undef` nor `no-unused-vars` can see
+ * the damage, because the reference it broke was a type reference. Round 2 of
+ * this work learned that by shipping the deletion first.
+ */
+function hasTypeOnlyBinding(node) {
+  return (
+    node.importKind === 'type' || node.specifiers.some((spec) => spec.importKind === 'type')
+  );
+}
+
+/**
+ * Is every binding this declaration introduces now unreferenced?
+ *
+ * Whole declarations only. A partially-dead declaration (`import path, { sep }`
+ * with `sep` still live) needs comma surgery, which is where removal bugs live,
+ * and it is not the shape the adopter measured — so it is left alone and stays a
+ * visible `no-unused-vars` finding rather than a risky edit.
+ *
+ * Re-exports need no special guard: `export { path }` and `export default path`
+ * both register as references under espree AND `@typescript-eslint/parser`
+ * (measured, both parsers), so such a declaration is never dead here. Round 2
+ * added an explicit `isReExported` check for the SPECIFIER-removal path, where
+ * the reference count is not consulted at all; this path reads the count, so a
+ * second check would be a guard that can never fire.
+ */
+function isDeadRemovableImport(sourceCode, node) {
+  if (!REMOVABLE_MODULES.has(node.source.value)) {
+    return false;
+  }
+  // A bare `import 'node:path';` declares no bindings, which would make "every
+  // binding is dead" vacuously true. Whether the module has side effects is
+  // beside the point — the author wrote a statement whose only possible purpose
+  // is its effect, and deleting it is an edit nobody asked for.
+  if (node.specifiers.length === 0 || hasTypeOnlyBinding(node)) {
+    return false;
+  }
+  // `every` over a non-empty list: the `specifiers.length === 0` bail above is
+  // what makes that safe, and it is the ONLY thing that does. A second
+  // `declared.length > 0` here would look like belt-and-braces and would in fact
+  // be a guard that can never fire — which mutation testing reports as an
+  // unguarded line, correctly, because deleting the real check leaves it green.
+  return sourceCode
+    .getDeclaredVariables(node)
+    .every((variable) => variable.references.length === 0);
+}
+
+/**
+ * Report — and remove — every import declaration this pass emptied out.
+ *
+ * Runs at `Program:exit`, over the SOURCE as it stands this pass. That ordering
+ * is the safety property, not an implementation detail: while a live reference
+ * survives in the text being linted, the binding is not dead and nothing is
+ * reported. The removal therefore lands on a later pass, after the rewrite that
+ * consumed the last reference — never speculatively alongside it.
+ *
+ * `migrated` gates the whole leg on the safe symbol being bound in the file, and
+ * is what keeps this a REPAIR leg rather than a general unused-import rule. It
+ * must be read from the SOURCE and never from a flag a `fix()` can flip: ESLint
+ * runs `fix()` for a suppressed problem before the `eslint-disable` filter
+ * discards it, so any mutable "did I add the import?" flag is already spent and
+ * lying by the time this runs.
+ *
+ * Its own report, with its own `fix`, deliberately — so the deletion appears in
+ * lint output and can be suppressed at the import line, rather than a rewrite
+ * quietly taking a declaration with it.
+ *
+ * Several rules in this pack can reach the same dead declaration in the same
+ * pass (a file using only `path.join` and `path.resolve` finishes owing nothing
+ * to `path`). They emit identical removals over an identical range, so ESLint
+ * applies one and drops the rest as overlapping. Measured with the three
+ * `safePath` rules enabled together over a file using all three: one
+ * `verifyAndFix`, output clean under `no-undef` and `no-unused-vars`, nothing
+ * left to report.
+ *
+ * In a check-only run that same file yields N identical messages, one per
+ * enabled rule. **Do not "fix" that by latching across rules.** These rule
+ * instances do share a module scope here, so a `WeakMap` keyed on `SourceCode`
+ * would dedupe them — and would reintroduce the exact trap round 2 was spent
+ * escaping. ESLint runs `fix()` for a suppressed problem BEFORE the
+ * `eslint-disable` filter discards it, so an `eslint-disable-next-line` naming
+ * whichever rule happened to win the latch would consume the file's only
+ * removal and then throw it away, leaving the import permanently undeletable and
+ * unreported. Duplicate messages on a file that is about to be fixed are the
+ * cheap failure; a silently stranded file is not.
+ *
+ * @param {object} context - ESLint rule context.
+ * @param {object} sourceCode - ESLint `SourceCode` for the file being linted.
+ * @param {object[]} importNodes - Unsafe-module `ImportDeclaration`s seen this pass.
+ * @param {boolean} migrated - Was the safe symbol already bound in the SOURCE?
+ */
+function reportDeadUnsafeImports(context, sourceCode, importNodes, migrated) {
+  if (!migrated) {
+    return;
+  }
+  for (const node of importNodes) {
+    if (!isDeadRemovableImport(sourceCode, node)) {
+      continue;
+    }
+    context.report({
+      node,
+      messageId: DEAD_UNSAFE_IMPORT,
+      data: {
+        local: sourceCode
+          .getDeclaredVariables(node)
+          .map((variable) => variable.name)
+          .join("', '"),
+        module: node.source.value,
+      },
+      // `fixer.remove(node)` takes the declaration and leaves its newline, so a
+      // blank line remains where the import was. That is exactly what the
+      // specifier-removal leg in `path-function-rule-factory.cjs` has always
+      // done — its fixtures pin the leading `\n` — and matching it keeps one
+      // behaviour rather than two. Extending the range through a trailing
+      // whitespace-only remainder would tidy both, and should be done to both at
+      // once, once an adopter has measured whether their formatter cares.
+      fix: (fixer) => fixer.remove(node),
+    });
+  }
+}
+
+module.exports = {
+  DEAD_UNSAFE_IMPORT,
+  DEAD_UNSAFE_IMPORT_MESSAGE,
+  REMOVABLE_MODULES,
+  reportDeadUnsafeImports,
+};