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

package/eslint/rules/no-bare-symlink-in-tests.cjs

@@ -0,0 +1,200 @@
+/**
+ * ESLint rule: no-bare-symlink-in-tests
+ *
+ * Bans unguarded `fs.symlinkSync()` / `fs.promises.symlink()`, with a different
+ * remedy on each side of the test boundary:
+ *
+ * - **test files** → route through `createSymlink()` / `createSymlinkAsync()`
+ *   from `@vibe-agent-toolkit/utils`, which require a probed capability token.
+ * - **shipped code** → there is no wrapper to route through, and there must not
+ *   be: `createSymlink()` lives on the `utils/testing` subpath, so pointing
+ *   production code at it would be worse advice than the bare call. Prefer a
+ *   junction for a directory link on win32, or catch the failure and name the
+ *   missing privilege. An `eslint-disable` justification is the sanctioned way
+ *   to say "this platform is deliberately out of scope" — see
+ *   `cli/src/commands/agent/install.ts`, where `--dev` is knowingly unavailable
+ *   on an unprivileged Windows and fails saying exactly that.
+ *
+ * ⚠️ **The name is now narrower than the rule.** It covers shipped code too;
+ * renaming it is a public-API change to `@vibe-agent-toolkit/utils/eslint` and
+ * has not been done.
+ *
+ * Why: creating a symlink on Windows needs Developer Mode or
+ * `SeCreateSymbolicLinkPrivilege`, which most dev boxes and CI agents lack. A
+ * bare `symlinkSync()` call throws `EPERM` there with no visible skip — the
+ * test just fails, or (worse) the failure is masked by a `try`/`catch` that
+ * swallows it silently. `createSymlink()`/`createSymlinkAsync()` require a
+ * `SymlinkCapability` token as their first argument, and the only way to mint
+ * one is `symlinkCapability()`, which performs the real probe. That token
+ * requirement is what this rule enforces structurally: a test cannot reach the
+ * real syscall without first proving — or explicitly declining via vitest's
+ * `skip()` — that the host supports it.
+ *
+ * No auto-fix: unlike a straight rename, the replacement needs a capability
+ * token threaded from a probe call, which is a judgment call about where that
+ * probe belongs in the surrounding test (per-test via `{ skip }`, or hoisted
+ * to a shared `beforeAll`) that a mechanical fixer cannot make safely.
+ */
+
+const {
+  EXEMPT_FILES_SCHEMA,
+  UNANCHORED_EXEMPT_FILE,
+  UNANCHORED_EXEMPT_MESSAGE,
+  createConfigurableExemptPathMatcher,
+  isTestFile,
+  reportUnanchoredExemptEntries,
+} = require('./exempt-path-matcher.cjs');
+
+/** `node:fs` names carrying the sync primitive. */
+const SYNC_MODULES = new Set(['node:fs', 'fs']);
+/** `node:fs/promises` names carrying the async primitive. */
+const ASYNC_MODULES = new Set(['node:fs/promises', 'fs/promises']);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Ban unguarded fs.symlinkSync()/fs.symlink() — route tests through createSymlink()/createSymlinkAsync(), and guard shipped code against the Windows privilege requirement',
+      category: 'Cross-Platform',
+      recommended: true,
+    },
+    fixable: null,
+    schema: [EXEMPT_FILES_SCHEMA],
+    messages: {
+      noBareSymlink:
+        'Bare {{fn}}() in a test file can throw EPERM on Windows without Developer Mode. ' +
+        'Probe with symlinkCapability() and call {{safeFn}}(cap, ...) from @vibe-agent-toolkit/utils, ' +
+        "routing a missing capability through vitest's skip() rather than a silent return.",
+      // Deliberately a different remedy, not a reworded version of the same one.
+      // Production code cannot `skip()`, and `createSymlink()` lives on the
+      // `@vibe-agent-toolkit/utils/testing` subpath — telling shipped code to
+      // import a test helper would be worse advice than the bare call.
+      unguardedSymlink:
+        'Unguarded {{fn}}() will throw EPERM on Windows unless the process holds ' +
+        'SeCreateSymbolicLinkPrivilege (Developer Mode or an elevated shell) — most user machines ' +
+        'and CI agents do not. For a DIRECTORY link prefer a junction on win32 ' +
+        "(`process.platform === 'win32' ? 'junction' : 'dir'`, absolute target), which needs no " +
+        'elevation; otherwise catch the failure and say what privilege is missing, or degrade to a copy. ' +
+        'If this platform is deliberately out of scope, say so in an eslint-disable justification.',
+      [UNANCHORED_EXEMPT_FILE]: UNANCHORED_EXEMPT_MESSAGE,
+    },
+  },
+
+  create(context) {
+    const filename = context.getFilename();
+
+    const exemptMatcherFor = createConfigurableExemptPathMatcher([]);
+    if (exemptMatcherFor(context)(filename)) {
+      // Still surface a malformed exemption list: the file we are standing in
+      // may be exempt only BECAUSE the entry is unanchored.
+      return {
+        Program(node) {
+          reportUnanchoredExemptEntries(context, node);
+        },
+      };
+    }
+
+    // Test files and shipped code are both covered, with different remedies.
+    //
+    // The rule was test-only for one revision, and that left two blind spots
+    // that mattered: VAT's own `src/` fixture builders (`trap-corpus.ts` had to
+    // be migrated by hand precisely because no rule could see it), and — since
+    // this rule ships publicly on `@vibe-agent-toolkit/utils/eslint` — every
+    // adopter's production code, which faces the identical Windows hazard with
+    // none of the test lane's ability to skip.
+    //
+    // ⚠️ Extending it is what MAKES `exemptFiles` load-bearing:
+    // `packages/utils/src/test-helpers.ts` holds the one sanctioned
+    // `symlinkSync` call and is not a test file, so it was previously excluded
+    // for free. It now needs a real exemption entry in eslint.config.js.
+    const messageId = isTestFile(filename) ? 'noBareSymlink' : 'unguardedSymlink';
+
+    // Local names bound to each module's default/namespace import, e.g.
+    // `import fs from 'node:fs/promises'` binds `fs` to ASYNC_MODULES.
+    const syncNamespaceNames = new Set();
+    const asyncNamespaceNames = new Set();
+    // Whether `symlinkSync` / `symlink` were pulled in as bare named imports.
+    let syncNamedImported = false;
+    let asyncNamedImported = false;
+
+    function namespaceLocalName(importNode) {
+      const spec = importNode.specifiers.find(
+        (candidate) => candidate.type === 'ImportDefaultSpecifier' || candidate.type === 'ImportNamespaceSpecifier',
+      );
+      return spec ? spec.local.name : null;
+    }
+
+    function importsNamed(importNode, name) {
+      return importNode.specifiers.some(
+        (spec) => spec.type === 'ImportSpecifier' && spec.imported.name === name,
+      );
+    }
+
+    return {
+      Program(node) {
+        reportUnanchoredExemptEntries(context, node);
+      },
+
+      ImportDeclaration(node) {
+        const source = node.source.value;
+        if (SYNC_MODULES.has(source)) {
+          const local = namespaceLocalName(node);
+          if (local) syncNamespaceNames.add(local);
+          syncNamedImported = syncNamedImported || importsNamed(node, 'symlinkSync');
+        }
+        if (ASYNC_MODULES.has(source)) {
+          const local = namespaceLocalName(node);
+          if (local) asyncNamespaceNames.add(local);
+          asyncNamedImported = asyncNamedImported || importsNamed(node, 'symlink');
+        }
+      },
+
+      CallExpression(node) {
+        const { callee } = node;
+
+        // Bare `symlinkSync(...)` from a named import.
+        if (syncNamedImported && callee.type === 'Identifier' && callee.name === 'symlinkSync') {
+          context.report({ node, messageId, data: { fn: 'symlinkSync', safeFn: 'createSymlink' } });
+          return;
+        }
+
+        // Bare `symlink(...)` from a named `node:fs/promises` import.
+        if (asyncNamedImported && callee.type === 'Identifier' && callee.name === 'symlink') {
+          context.report({ node, messageId, data: { fn: 'symlink', safeFn: 'createSymlinkAsync' } });
+          return;
+        }
+
+        // `fs.promises.symlink(...)` — the two-hop shape reached via a tracked
+        // sync namespace import (`import fs from 'node:fs'`).
+        if (
+          callee.type === 'MemberExpression' &&
+          callee.property.name === 'symlink' &&
+          callee.object.type === 'MemberExpression' &&
+          callee.object.property.name === 'promises' &&
+          callee.object.object.type === 'Identifier' &&
+          syncNamespaceNames.has(callee.object.object.name)
+        ) {
+          context.report({ node, messageId, data: { fn: 'symlink', safeFn: 'createSymlinkAsync' } });
+          return;
+        }
+
+        if (callee.type !== 'MemberExpression' || callee.object.type !== 'Identifier') {
+          return;
+        }
+        const receiver = callee.object.name;
+
+        // `fs.symlinkSync(...)` / `nodeFs.symlinkSync(...)` on a tracked sync namespace.
+        if (syncNamespaceNames.has(receiver) && callee.property.name === 'symlinkSync') {
+          context.report({ node, messageId, data: { fn: 'symlinkSync', safeFn: 'createSymlink' } });
+          return;
+        }
+
+        // `fs.symlink(...)` on a tracked async namespace (the common
+        // `import fs from 'node:fs/promises'` shape).
+        if (asyncNamespaceNames.has(receiver) && callee.property.name === 'symlink') {
+          context.report({ node, messageId, data: { fn: 'symlink', safeFn: 'createSymlinkAsync' } });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-raw-text-decode.cjs

@@ -0,0 +1,296 @@
+/**
+ * ESLint rule: no-raw-text-decode
+ *
+ * **One seam turns file bytes into text; every other route is an error.**
+ *
+ * ## What it is for
+ *
+ * `bytes.toString('utf-8')` is a guess dressed as a conversion. It ignores every
+ * byte-order mark, cannot express UTF-16BE at all (Node's `Buffer` has no such
+ * encoding), and turns a perfectly ordinary UTF-16 document into NUL-interleaved
+ * mojibake — which downstream code then classifies as *binary*. Measured in VAT:
+ * a `working-tree-encoding=UTF-16` checkout of a markdown file yielding one
+ * heading and one link produced **no blob row, no section and no reference**,
+ * because the read decoded it wrong and the binary sniff believed the result.
+ * PowerShell 5.1's `Out-File` and `>` write UTF-16LE by default, so this is a
+ * Windows-authored document, not an exotic one.
+ *
+ * The fix is a single decoding seam that reads the encoding off the BOM and says
+ * so. This rule is what keeps a second, private decoder from growing beside it.
+ *
+ * ## The three shapes it catches
+ *
+ * | shape | example |
+ * |---|---|
+ * | `toString(<encoding>)` on any value | `buf.toString('utf-8')` |
+ * | constructing a decoder | `new TextDecoder('utf-16le')` |
+ * | letting `fs` decode | `readFile(p, 'utf-8')`, `readFileSync(p, { encoding: 'latin1' })` |
+ *
+ * ## The line this rule is drawing: whose choice was the encoding?
+ *
+ * **Not every `'utf-8'` read is a content read**, and the distinction is the
+ * whole difference between a rule that survives and one that gets widened until
+ * it means nothing. Three categories, and every call site is in exactly one:
+ *
+ * 1. **A document from the corpus** — an adopter's markdown, HTML, `SKILL.md`,
+ *    config file, JSON schema or `package.json`. Nobody in this codebase chose
+ *    the encoding; it has to be **discovered** from the bytes. *This is the
+ *    rule's target*, and the seam is the only correct reader.
+ * 2. **An artifact this project wrote** — its own cache entry, its own emitted
+ *    manifest, an asset it publishes beside its own code. The encoding was
+ *    **chosen at the write**, so reading it back the same way is a closed loop,
+ *    not a decode.
+ * 3. **Bytes that were never a file** — a subprocess's stdout, an HTTP response
+ *    body, a Buffer this process built. There is no file encoding to discover;
+ *    the **producer's contract** decides.
+ *
+ * Static analysis cannot tell the three apart — `buf.toString('utf8')` looks
+ * identical whether the Buffer came from `readFile` or from `spawn`. So the rule
+ * reports all three, and 2 and 3 are settled at the call site with a one-line
+ * `eslint-disable-next-line` that **names the writer or the producer**.
+ *
+ * That gives a reviewer a falsifiable test, which is the point: *a justification
+ * that cannot name who wrote the bytes is a category-1 call wearing a disable
+ * comment.* "It's always UTF-8 in practice" names nobody and does not qualify.
+ * Do not settle these by adding paths to `exemptFiles` until lint goes quiet —
+ * `exemptFiles` is for the seam's own implementation file, nothing else.
+ *
+ * ## Why the encoding test is an EXCLUSION and not an inclusion list
+ *
+ * An inclusion list of character encodings would have to enumerate every legal
+ * spelling — `utf8`, `utf-8`, `utf16le`, `ucs2`, `ucs-2`, `latin1`, `binary`,
+ * `ascii`, the `iso-8859-*` family, the `windows-125*` family, and every
+ * `TextDecoder` label alias beyond those — and a spelling it missed would pass
+ * silently. That is a rule that fails OPEN, in the one direction that matters.
+ *
+ * Node's `Buffer` encodings are a CLOSED set, and exactly three of them are
+ * binary-to-text codecs rather than character encodings: `base64`, `base64url`
+ * and `hex`. So "a string argument that is not one of those three" is both
+ * exhaustive over `Buffer` and correct for `TextDecoder` (whose labels are all
+ * character encodings). Excluding three known-safe values fails CLOSED: an
+ * encoding nobody anticipated still fires.
+ *
+ * ## What it does NOT catch, stated so the coverage is not overclaimed
+ *
+ * - **A computed encoding** — `buf.toString(enc)`, `readFile(p, enc)`. Firing on
+ *   a non-literal second argument is untenable without type information:
+ *   `n.toString(radix)` with a variable radix is ordinary code, and
+ *   `readFile(p, callback)` in callback style has the same shape as
+ *   `readFile(p, encoding)`. A rule that fires on both teaches people to disable
+ *   it, which costs its true positives too — this repo has already demoted one
+ *   rule (`no-unsafe-root-join`) for precisely that. So the trigger is a string
+ *   LITERAL, and a variable holding `'utf-8'` is a bypass a reviewer can see and
+ *   a linter cannot.
+ * - `createReadStream(path, 'utf-8')` and other streaming decodes. No VAT code
+ *   does this; it is a real hole, not a decision that it is safe.
+ * - A subprocess's stdout decoded with `.toString('utf8')` IS caught, and that
+ *   is usually a false positive — process output is not file content and its
+ *   encoding is the child's business. Nothing here can tell the two apart
+ *   statically, which is why the rule is registered against the directories that
+ *   read corpus documents rather than repo-wide. See the consuming config.
+ * - `require()`/`import()` of a JSON or data file, which decode below the public
+ *   `fs` surface entirely.
+ *
+ * @example
+ * ```javascript
+ * // ❌ BAD
+ * const text = (await readFile(p)).toString('utf-8');
+ * const text = await readFile(p, 'utf-8');
+ * const text = new TextDecoder().decode(bytes);
+ *
+ * // ✅ GOOD — category 1, the corpus document
+ * const { text } = await readTextContent(p);
+ * const { text } = decodeTextContent(bytes);
+ *
+ * // ✅ GOOD — category 3, and the justification names the producer
+ * // eslint-disable-next-line local/no-raw-text-decode -- subprocess stdout; producer is the credential helper spawned above
+ * const out = result.stdout.toString('utf8');
+ * ```
+ */
+
+'use strict';
+
+const {
+  EXEMPT_FILES_SCHEMA,
+  UNANCHORED_EXEMPT_FILE,
+  UNANCHORED_EXEMPT_MESSAGE,
+  createConfigurableExemptPathMatcher,
+  reportUnanchoredExemptEntries,
+} = require('./exempt-path-matcher.cjs');
+const { resolveSafeModule, withSafeModuleOption } = require('./safe-import.cjs');
+
+/**
+ * The default module named in the advice text.
+ *
+ * A placeholder, and deliberately not this package: the seam lives in the
+ * consuming repo, so `safeModule` is the option every real config sets. Named
+ * rather than left blank so the message is still a sentence when it is not.
+ */
+const DEFAULT_SEAM_MODULE = 'your content-decoding module';
+
+/**
+ * The three `Buffer` encodings that are binary-to-text codecs, not character
+ * encodings. Everything else is a decode. See the module docstring for why the
+ * test is shaped this way round.
+ */
+const BINARY_TO_TEXT_CODECS = new Set(['base64', 'base64url', 'hex']);
+
+/** The `fs` readers that will decode for you if handed an encoding. */
+const DECODING_READERS = new Set(['readFile', 'readFileSync']);
+
+/**
+ * Is this node a string literal (or a template with no substitutions)?
+ *
+ * @param {object} node - AST node
+ * @returns {string | null} Its value, or `null` when it is not a plain string
+ */
+function stringValueOf(node) {
+  if (node?.type === 'Literal' && typeof node.value === 'string') return node.value;
+  if (node?.type === 'TemplateLiteral' && node.expressions.length === 0) {
+    return node.quasis[0]?.value?.cooked ?? null;
+  }
+  return null;
+}
+
+/**
+ * Does this argument spell out a character encoding?
+ *
+ * Only a string LITERAL counts — see the module docstring for why a computed
+ * encoding is deliberately out of reach. A numeric radix (`n.toString(16)`) is
+ * not a string and so is never a decode.
+ *
+ * @param {object} node - The argument node
+ * @returns {boolean} True when the argument names a character encoding
+ */
+function isCharacterEncodingArgument(node) {
+  const literal = stringValueOf(node);
+  if (literal === null) return false;
+  return !BINARY_TO_TEXT_CODECS.has(literal.toLowerCase());
+}
+
+/**
+ * The `{ encoding: '...' }` option object's encoding argument, if it selects a
+ * character encoding.
+ *
+ * @param {object} node - The argument node
+ * @returns {boolean} True when the options object asks `fs` to decode
+ */
+function optionsObjectDecodes(node) {
+  if (node?.type !== 'ObjectExpression') return false;
+  for (const property of node.properties) {
+    if (property.type !== 'Property') continue;
+    const key = property.key?.type === 'Identifier'
+      ? property.key.name
+      : stringValueOf(property.key);
+    if (key !== 'encoding') continue;
+    // An explicit `encoding: null` / `encoding: undefined` asks for a Buffer.
+    if (property.value?.type === 'Literal' && property.value.value === null) return false;
+    return isCharacterEncodingArgument(property.value);
+  }
+  return false;
+}
+
+/** The called function's name, whether it is bare or a member call. */
+function calleeName(node) {
+  if (node.callee?.type === 'Identifier') return node.callee.name;
+  if (node.callee?.type === 'MemberExpression' && node.callee.property?.type === 'Identifier') {
+    return node.callee.property.name;
+  }
+  return null;
+}
+
+const exemptMatcherFor = createConfigurableExemptPathMatcher([]);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow decoding bytes to text outside the one content-decoding seam; '
+        + 'raw `toString(encoding)` / `TextDecoder` / `readFile(path, encoding)` '
+        + 'ignore byte-order marks and cannot express UTF-16BE at all.',
+      category: 'Correctness',
+      recommended: false,
+    },
+    schema: [withSafeModuleOption(EXEMPT_FILES_SCHEMA)],
+    messages: {
+      bufferTextDecode:
+        'Do not decode bytes with `.toString({{encoding}})` — it ignores any byte-order mark and '
+        + 'cannot express UTF-16BE. Use `decodeTextContent()` from {{safeModule}}.',
+      textDecoderConstruct:
+        'Do not construct a `TextDecoder` here — the encoding has to be decided from the bytes, '
+        + 'in one place. Use `decodeTextContent()` from {{safeModule}}.',
+      fsReadTextEncoding:
+        'Do not let `{{reader}}` decode — it applies the encoding you name with no BOM handling. '
+        + 'Read bytes and use `readTextContent()` / `decodeTextContent()` from {{safeModule}}.',
+      [UNANCHORED_EXEMPT_FILE]: UNANCHORED_EXEMPT_MESSAGE,
+    },
+  },
+
+  create(context) {
+    const seamModule = resolveSafeModule(context, DEFAULT_SEAM_MODULE);
+
+    // The seam itself must be able to call the primitives it wraps.
+    if (exemptMatcherFor(context)(context.getFilename())) {
+      // Still surface a malformed exemption list: the file we are standing in
+      // may be exempt only BECAUSE the entry is unanchored.
+      return {
+        Program(node) {
+          reportUnanchoredExemptEntries(context, node);
+        },
+      };
+    }
+
+    return {
+      Program(node) {
+        reportUnanchoredExemptEntries(context, node);
+      },
+
+      NewExpression(node) {
+        if (node.callee?.type !== 'Identifier' || node.callee.name !== 'TextDecoder') return;
+        context.report({
+          node,
+          messageId: 'textDecoderConstruct',
+          data: { safeModule: seamModule },
+        });
+      },
+
+      CallExpression(node) {
+        const name = calleeName(node);
+        if (name === null) return;
+
+        if (
+          name === 'toString'
+          && node.callee.type === 'MemberExpression'
+          && node.arguments.length > 0
+          && isCharacterEncodingArgument(node.arguments[0])
+        ) {
+          context.report({
+            node,
+            messageId: 'bufferTextDecode',
+            data: {
+              safeModule: seamModule,
+              encoding: context.getSourceCode().getText(node.arguments[0]),
+            },
+          });
+          return;
+        }
+
+        if (!DECODING_READERS.has(name) || node.arguments.length < 2) return;
+        const second = node.arguments[1];
+        // Object form first: `{ encoding: 'hex' }` is an ObjectExpression, and
+        // asking the positional test about it would answer the wrong question.
+        const decodes = second?.type === 'ObjectExpression'
+          ? optionsObjectDecodes(second)
+          : isCharacterEncodingArgument(second);
+        if (decodes) {
+          context.report({
+            node,
+            messageId: 'fsReadTextEncoding',
+            data: { reader: name, safeModule: seamModule },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-self-package-import.cjs

@@ -0,0 +1,157 @@
+/**
+ * ESLint rule: no-self-package-import
+ *
+ * Disallow a file importing the package it already lives in **by that package's
+ * own name**. Inside `packages/foo/src`, write `./types.js`, never
+ * `@scope/foo`.
+ *
+ * @example
+ * // ❌ BAD — packages/agent-runtime/src/session/file-session-store.ts
+ * import type { SessionStore } from '@vibe-agent-toolkit/agent-runtime';
+ *
+ * // ✅ GOOD
+ * import type { SessionStore } from './types.js';
+ *
+ * ## Why this is a build-breaker and not a style preference
+ *
+ * A self-import resolves out through `node_modules` to the package's OWN
+ * `package.json`, whose `types`/`exports` point at `./dist/index.d.ts` — a file
+ * the compiler is in the middle of producing. It appears to work only because of
+ * a TypeScript courtesy: while `dist` IS the running project's output path,
+ * `dist/index.d.ts` is recognised as this project's own declaration output and
+ * the import is redirected back to `src`, so it resolves with no `dist/` on disk
+ * at all.
+ *
+ * That courtesy is conditional, and every condition is one a build script may
+ * legitimately change. Compile the package with `--outDir` pointed anywhere else
+ * — a staging directory used to make emit atomic, for instance — and `dist` is
+ * no longer this program's output, the redirect is gone, tsc looks for a literal
+ * `dist/index.d.ts`, and a tree that has never been built has none:
+ *
+ *   error TS2307: Cannot find module '@scope/foo' or its corresponding type
+ *                 declarations.
+ *
+ * Knock-on `TS2339`s follow wherever a local type extended one of the now
+ * unresolved imports, which is what makes the failure read as a type bug in
+ * code nobody touched.
+ *
+ * ## Why the compiler cannot be trusted to find these
+ *
+ * The failure is invisible on any machine that has built the package before:
+ * a stale `dist/` satisfies the literal lookup, so the build passes — by
+ * typechecking the package against its PREVIOUS build's declarations. Worse, in
+ * a monorepo whose worktrees live inside the main checkout, module resolution
+ * walks up past the worktree into the parent checkout's `node_modules` and
+ * resolves against a DIFFERENT checkout's `dist/`. Both are green locally and
+ * red in CI, which is the only place the tree is genuinely pristine.
+ *
+ * So a self-import is latent by construction: it costs nothing until the day a
+ * build script changes `outDir`, and then it fails somewhere nobody can
+ * reproduce. Lint is the only stage that sees it on the author's machine.
+ *
+ * ## `packageName` is required, and the rule reads no files to get it
+ *
+ * The obvious implementation walks up from the linted file to the nearest
+ * `package.json` and reads its `name`. This rule deliberately does NOT: every
+ * module on the `./eslint` subpath is plain data that requires nothing — not
+ * `eslint`, not a third-party package, not even a Node builtin — which is what
+ * lets the pack ship as a subpath of a runtime package, keeps `eslint` an
+ * OPTIONAL peer dependency, and keeps the other subpaths resolving in a tree with
+ * no ESLint installed. `test/eslint/subpath-purity.test.ts` enforces that as an
+ * empty-set assertion. One `require('node:fs')` here would be the first crack in
+ * it, for a convenience the config layer can supply for free.
+ *
+ * So the caller names the package, and the caller is a config file that already
+ * runs in full Node and can read every manifest it likes. See the generated
+ * per-package blocks in this repo's `eslint.config.js`.
+ *
+ * Scoping is the caller's job for the same reason: only files a package actually
+ * COMPILES can break the build, and test and example trees commonly import their
+ * own package by name ON PURPOSE, to exercise the public entry point exactly as a
+ * consumer would.
+ */
+
+'use strict';
+
+/**
+ * Whether `specifier` names `packageName` itself or one of its subpaths.
+ *
+ * The subpath check is anchored on `/` so `@scope/foo-bar` is not read as a
+ * subpath of `@scope/foo`.
+ *
+ * @param {string} specifier - The import specifier as written.
+ * @param {string} packageName - The enclosing package's name.
+ * @returns {boolean}
+ */
+function isSelfReference(specifier, packageName) {
+  return specifier === packageName || specifier.startsWith(`${packageName}/`);
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        "Disallow importing the enclosing package by its own name; use a relative path so the import does not depend on the package's built `dist/`.",
+      category: 'Build correctness',
+      recommended: true,
+    },
+    messages: {
+      useRelativeImport:
+        "Do not import '{{specifier}}' — this file is already inside '{{packageName}}'. That resolves through the package's own `dist/`, which only works while `dist` is the running compiler's output path; change `outDir` (or build a tree that has never been built) and it fails with TS2307. Import the defining module by relative path instead.",
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          packageName: { type: 'string', minLength: 1 },
+        },
+        required: ['packageName'],
+        additionalProperties: false,
+      },
+    ],
+  },
+
+  create(context) {
+    const { packageName } = context.options[0];
+
+    /**
+     * @param {{ type: string, value?: unknown } | null | undefined} source - A node in source position.
+     */
+    const check = (source) => {
+      if (!source || source.type !== 'Literal') return;
+      const specifier = source.value;
+      if (typeof specifier !== 'string') return;
+      if (!isSelfReference(specifier, packageName)) return;
+      context.report({
+        node: source,
+        messageId: 'useRelativeImport',
+        data: { specifier, packageName },
+      });
+    };
+
+    return {
+      // `import … from 'x'` and `import type … from 'x'`
+      ImportDeclaration: (node) => check(node.source),
+      // `export … from 'x'` and `export * from 'x'` — a barrel re-exporting
+      // through its own package name is the same resolution, one step removed.
+      ExportNamedDeclaration: (node) => check(node.source),
+      ExportAllDeclaration: (node) => check(node.source),
+      // `await import('x')`
+      ImportExpression: (node) => check(node.source),
+      // `import('x')` in TYPE position, which no other visitor above reaches.
+      // The specifier hangs off `source`; typescript-eslint has called this
+      // property `parameter` and `argument` in earlier majors, and reading the
+      // wrong one costs nothing at lint time — the visitor simply never fires.
+      // The `import() in TYPE position` case in `rules.test.ts` is what turns
+      // that silence into a red test if a future parser renames it again.
+      TSImportType: (node) => check(node.source),
+      // `require('x')` in the `.cts`/`.cjs` files this pack also lints.
+      CallExpression: (node) => {
+        if (node.callee.type !== 'Identifier' || node.callee.name !== 'require') return;
+        if (node.arguments.length !== 1) return;
+        check(node.arguments[0]);
+      },
+    };
+  },
+};

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@vibe-agent-toolkit/utils",
-  "version": "0.2.0-rc.1",
+  "version": "0.2.0-rc.3",
   "type": "module",
   "description": "Core utility functions shared across the vibe-agent-toolkit packages",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/crawl-timing.js"
+  ],
   "keywords": [
     "typescript",
     "utilities",
@@ -32,6 +34,10 @@
       "types": "./dist/fs.d.ts",
       "import": "./dist/fs.js"
     },
+    "./text": {
+      "types": "./dist/text.d.ts",
+      "import": "./dist/text.js"
+    },
     "./process": {
       "types": "./dist/process.d.ts",
       "import": "./dist/process.js"
@@ -93,6 +99,7 @@
     "clean": "rimraf dist *.tsbuildinfo"
   },
   "dependencies": {
+    "@vibe-validate/git": "0.20.1",
     "handlebars": "^4.7.8",
     "ignore": "^7.0.5",
     "picomatch": "^4.0.3",