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

package/dist/text.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @vibe-agent-toolkit/utils/text
+ *
+ * **The one way bytes become text.** Encoding detection from a byte-order mark,
+ * BOM stripping, and a stated default when there is no BOM — see
+ * `text-content.ts` for what is a fact, what is an assumption, and the two
+ * limitations that are deliberately not guessed around.
+ *
+ * Pure: this entry reaches no `node:*` builtin and no third-party package, so
+ * bytes from a git blob, an HTTP response or a zip entry decode through exactly
+ * the same function as bytes from disk. For the read-a-file case, import
+ * `readTextContent` from `@vibe-agent-toolkit/utils/fs`, which is this plus a
+ * `readFile`.
+ */
+export { decodeTextContent, type DecodedText, type EncodingSource, type TextEncoding, type TextProvenance, } from './text-content.js';
+//# sourceMappingURL=text.d.ts.map

package/dist/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAC"}

package/dist/text.js

@@ -0,0 +1,16 @@
+/**
+ * @vibe-agent-toolkit/utils/text
+ *
+ * **The one way bytes become text.** Encoding detection from a byte-order mark,
+ * BOM stripping, and a stated default when there is no BOM — see
+ * `text-content.ts` for what is a fact, what is an assumption, and the two
+ * limitations that are deliberately not guessed around.
+ *
+ * Pure: this entry reaches no `node:*` builtin and no third-party package, so
+ * bytes from a git blob, an HTTP response or a zip entry decode through exactly
+ * the same function as bytes from disk. For the read-a-file case, import
+ * `readTextContent` from `@vibe-agent-toolkit/utils/fs`, which is this plus a
+ * `readFile`.
+ */
+export { decodeTextContent, } from './text-content.js';
+//# sourceMappingURL=text.js.map

package/dist/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,iBAAiB,GAKlB,MAAM,mBAAmB,CAAC"}

package/dist/timing-dump.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The on-disk plumbing every VAT timing seam shares.
+ *
+ * Two seams write per-process JSON dumps to an operator-named directory:
+ * `@vibe-agent-toolkit/resources`' `parse-timing.ts` (which pass inside a parser
+ * owns the time) and this package's `crawl-timing.ts` (which contributor or
+ * crawler owns the time). They sit in different packages because `crawl-timing`
+ * has to bracket `GitTracker`, which is here — so this module lives at the lower
+ * of the two and is exported for the higher one. What they
+ * MEASURE could not be less alike — one axis is a closed enum of parser passes,
+ * the other is an open set of contributor ids — but every property that makes
+ * the *file* trustworthy is identical between them, and the lab's
+ * `harness/dumps.ts` already says so from the reading end:
+ *
+ * 1. A directory that cannot be created is reported the moment the seam turns
+ *    on, while there is still a run to abandon — never at exit, where a failure
+ *    costs the whole measurement.
+ * 2. A dump failure is written to **stderr and never thrown**. These run from
+ *    an `exit` listener, where a throw changes the process's exit behaviour, and
+ *    they must never touch stdout, which carries vat's report.
+ * 3. A pid can file more than one dump. `vat validate` spawns the vat binary
+ *    once per phase and pids are reused, so `<stem>-<pid>.json` genuinely
+ *    collides; the name gains a counter rather than overwriting.
+ * 4. The process's own wall and CPU time is read ONCE, at dump time. It is a
+ *    lifetime figure for the process and never a duration of the measured work;
+ *    its value is the RATIO, which tells a reader whether the wall-timed
+ *    brackets above it were competing with a loaded machine.
+ *
+ *    ⚠️ **A reader must never SUM these across dumps.** Point 3 means one
+ *    command routinely files several, and a vat command's phase processes
+ *    overlap in time — so summing their lifetimes counts the same wall clock
+ *    more than once and produces a "total" longer than the command took. The
+ *    figure is per process, and the only honest aggregate over several is the
+ *    per-process ratio read one dump at a time. The `crawl` facet keeps one
+ *    record per dump and publishes no total for exactly this reason; `parse`
+ *    still sums, which is review finding F2 (2026-08-14) and is annotated at
+ *    `facets/parse/dump.ts`. This list is where both seams learn what makes a
+ *    dump trustworthy, so the hazard belongs here rather than only beside the
+ *    consumer that already fixed it.
+ *
+ * Writing that twice would give two seams two chances to diverge on the one
+ * thing a reader has to be able to trust identically. What each seam keeps for
+ * itself is its accumulator shape, its dump body and the noun it is called by.
+ */
+/**
+ * Process-level wall and CPU time, read ONCE when a dump is written.
+ *
+ * All three are lifetime figures for the whole process, not for the measured
+ * work: the point of carrying them is the *ratio*. CPU well below wall means the
+ * process was waiting rather than computing, and every wall-timed bracket in the
+ * dump carries that waiting inside it. CPU above wall is normal and not an
+ * error — `process.cpuUsage()` sums every thread, including libuv's pool.
+ */
+export interface TimingProcess {
+    /** Wall clock since this process started. */
+    wallMs: number;
+    /** User CPU consumed by the process, across all its threads. */
+    cpuUserMs: number;
+    /** System CPU consumed by the process, across all its threads. */
+    cpuSystemMs: number;
+}
+/**
+ * Reduce a raw env value to a directory or `null`.
+ *
+ * An empty-string value counts as absent: `VAT_PARSE_TIMING=` in a shell profile
+ * is a variable somebody meant to unset, not a request to dump into the process's
+ * working directory.
+ *
+ * @param raw - The env var's value, if set
+ * @returns The dump directory, or `null` when the seam is off
+ */
+export declare function normalizeTimingDirectory(raw: string | undefined): string | null;
+/**
+ * Report a dump problem on stderr.
+ *
+ * Never throws and never touches stdout: vat's stdout carries a YAML report, and
+ * an exit handler that threw would change the process's exit behaviour.
+ *
+ * @param noun - What the seam is called, so a reader knows which instrument failed
+ * @param target - Path the failure concerns
+ * @param error - Whatever was caught
+ */
+export declare function reportTimingDumpFailure(noun: string, target: string, error: unknown): void;
+/**
+ * Create the dump directory, swallowing failure.
+ *
+ * Done once when the seam turns on rather than at exit, so a bad path is
+ * reported while there is still a run to abandon — and so the exit handler does
+ * the minimum possible work.
+ *
+ * @param noun - What the seam is called, for the failure line
+ * @param directory - Directory dumps will be written to
+ */
+export declare function ensureTimingDirectory(noun: string, directory: string): void;
+/**
+ * Read this process's lifetime wall and CPU time.
+ *
+ * Called ONCE per dump — two syscalls for a whole run, which is why the process
+ * level can afford a CPU reading that a per-bracket level cannot. Deliberately
+ * not an accumulator and deliberately not reset: it describes the process, not
+ * the measurement window.
+ *
+ * @returns Wall clock and CPU since process start, in milliseconds
+ */
+export declare function readTimingProcess(): TimingProcess;
+/**
+ * Write one seam's dump, if the seam is on.
+ *
+ * The body is built lazily, inside this call, so a disabled seam never pays to
+ * snapshot accumulators nobody will read.
+ *
+ * @param noun - What the seam is called, for any failure line
+ * @param directory - Where to write, or `null` when the seam is off
+ * @param basename - Basename stem for the file
+ * @param build - Produces the dump body
+ * @returns The path written, or `null` when the seam is off or the write failed
+ */
+export declare function writeTimingDump(noun: string, directory: string | null, basename: string, build: () => unknown): string | null;
+//# sourceMappingURL=timing-dump.d.ts.map

package/dist/timing-dump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing-dump.d.ts","sourceRoot":"","sources":["../src/timing-dump.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAOH;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;CACrB;AAeD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAE/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAG1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAM3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,aAAa,CAOjD;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,OAAO,GACnB,MAAM,GAAG,IAAI,CAYf"}

package/dist/timing-dump.js

@@ -0,0 +1,164 @@
+/**
+ * The on-disk plumbing every VAT timing seam shares.
+ *
+ * Two seams write per-process JSON dumps to an operator-named directory:
+ * `@vibe-agent-toolkit/resources`' `parse-timing.ts` (which pass inside a parser
+ * owns the time) and this package's `crawl-timing.ts` (which contributor or
+ * crawler owns the time). They sit in different packages because `crawl-timing`
+ * has to bracket `GitTracker`, which is here — so this module lives at the lower
+ * of the two and is exported for the higher one. What they
+ * MEASURE could not be less alike — one axis is a closed enum of parser passes,
+ * the other is an open set of contributor ids — but every property that makes
+ * the *file* trustworthy is identical between them, and the lab's
+ * `harness/dumps.ts` already says so from the reading end:
+ *
+ * 1. A directory that cannot be created is reported the moment the seam turns
+ *    on, while there is still a run to abandon — never at exit, where a failure
+ *    costs the whole measurement.
+ * 2. A dump failure is written to **stderr and never thrown**. These run from
+ *    an `exit` listener, where a throw changes the process's exit behaviour, and
+ *    they must never touch stdout, which carries vat's report.
+ * 3. A pid can file more than one dump. `vat validate` spawns the vat binary
+ *    once per phase and pids are reused, so `<stem>-<pid>.json` genuinely
+ *    collides; the name gains a counter rather than overwriting.
+ * 4. The process's own wall and CPU time is read ONCE, at dump time. It is a
+ *    lifetime figure for the process and never a duration of the measured work;
+ *    its value is the RATIO, which tells a reader whether the wall-timed
+ *    brackets above it were competing with a loaded machine.
+ *
+ *    ⚠️ **A reader must never SUM these across dumps.** Point 3 means one
+ *    command routinely files several, and a vat command's phase processes
+ *    overlap in time — so summing their lifetimes counts the same wall clock
+ *    more than once and produces a "total" longer than the command took. The
+ *    figure is per process, and the only honest aggregate over several is the
+ *    per-process ratio read one dump at a time. The `crawl` facet keeps one
+ *    record per dump and publishes no total for exactly this reason; `parse`
+ *    still sums, which is review finding F2 (2026-08-14) and is annotated at
+ *    `facets/parse/dump.ts`. This list is where both seams learn what makes a
+ *    dump trustworthy, so the hazard belongs here rather than only beside the
+ *    consumer that already fixed it.
+ *
+ * Writing that twice would give two seams two chances to diverge on the one
+ * thing a reader has to be able to trust identically. What each seam keeps for
+ * itself is its accumulator shape, its dump body and the noun it is called by.
+ */
+import { existsSync, writeFileSync } from 'node:fs';
+import { safePath } from './path-core.js';
+import { mkdirSyncReal } from './path-utils.js';
+/** `process.cpuUsage()` reports microseconds; a dump reports milliseconds. */
+const MICROSECONDS_PER_MS = 1000;
+/** `process.uptime()` reports seconds; a dump reports milliseconds. */
+const MS_PER_SECOND = 1000;
+/**
+ * Ceiling on the pid-collision search. A directory holding this many dumps for
+ * one pid is a runaway, not a collision; overwriting the last slot is a better
+ * outcome than spinning.
+ */
+const MAX_DUMP_COLLISIONS = 1000;
+/**
+ * Reduce a raw env value to a directory or `null`.
+ *
+ * An empty-string value counts as absent: `VAT_PARSE_TIMING=` in a shell profile
+ * is a variable somebody meant to unset, not a request to dump into the process's
+ * working directory.
+ *
+ * @param raw - The env var's value, if set
+ * @returns The dump directory, or `null` when the seam is off
+ */
+export function normalizeTimingDirectory(raw) {
+    return raw === undefined || raw === '' ? null : raw;
+}
+/**
+ * Report a dump problem on stderr.
+ *
+ * Never throws and never touches stdout: vat's stdout carries a YAML report, and
+ * an exit handler that threw would change the process's exit behaviour.
+ *
+ * @param noun - What the seam is called, so a reader knows which instrument failed
+ * @param target - Path the failure concerns
+ * @param error - Whatever was caught
+ */
+export function reportTimingDumpFailure(noun, target, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`vat: ${noun} dump failed for ${target}: ${detail}\n`);
+}
+/**
+ * Create the dump directory, swallowing failure.
+ *
+ * Done once when the seam turns on rather than at exit, so a bad path is
+ * reported while there is still a run to abandon — and so the exit handler does
+ * the minimum possible work.
+ *
+ * @param noun - What the seam is called, for the failure line
+ * @param directory - Directory dumps will be written to
+ */
+export function ensureTimingDirectory(noun, directory) {
+    try {
+        mkdirSyncReal(directory, { recursive: true });
+    }
+    catch (error) {
+        reportTimingDumpFailure(noun, directory, error);
+    }
+}
+/**
+ * Read this process's lifetime wall and CPU time.
+ *
+ * Called ONCE per dump — two syscalls for a whole run, which is why the process
+ * level can afford a CPU reading that a per-bracket level cannot. Deliberately
+ * not an accumulator and deliberately not reset: it describes the process, not
+ * the measurement window.
+ *
+ * @returns Wall clock and CPU since process start, in milliseconds
+ */
+export function readTimingProcess() {
+    const cpu = process.cpuUsage();
+    return {
+        wallMs: process.uptime() * MS_PER_SECOND,
+        cpuUserMs: cpu.user / MICROSECONDS_PER_MS,
+        cpuSystemMs: cpu.system / MICROSECONDS_PER_MS,
+    };
+}
+/**
+ * Pick a dump path that does not already exist.
+ *
+ * @param directory - Directory dumps are written to
+ * @param basename - Basename stem; the pid and any collision counter follow
+ * @returns An unused path, or the last candidate tried
+ */
+function nextTimingDumpPath(directory, basename) {
+    const stem = `${basename}-${String(process.pid)}`;
+    let candidate = safePath.join(directory, `${stem}.json`);
+    for (let collision = 1; 
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- operator-supplied diagnostic directory from a VAT_*_TIMING variable
+    collision <= MAX_DUMP_COLLISIONS && existsSync(candidate); collision += 1) {
+        candidate = safePath.join(directory, `${stem}-${String(collision)}.json`);
+    }
+    return candidate;
+}
+/**
+ * Write one seam's dump, if the seam is on.
+ *
+ * The body is built lazily, inside this call, so a disabled seam never pays to
+ * snapshot accumulators nobody will read.
+ *
+ * @param noun - What the seam is called, for any failure line
+ * @param directory - Where to write, or `null` when the seam is off
+ * @param basename - Basename stem for the file
+ * @param build - Produces the dump body
+ * @returns The path written, or `null` when the seam is off or the write failed
+ */
+export function writeTimingDump(noun, directory, basename, build) {
+    if (directory === null)
+        return null;
+    const target = nextTimingDumpPath(directory, basename);
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- operator-supplied diagnostic directory from a VAT_*_TIMING variable
+        writeFileSync(target, `${JSON.stringify(build(), null, 2)}\n`, 'utf-8');
+    }
+    catch (error) {
+        reportTimingDumpFailure(noun, target, error);
+        return null;
+    }
+    return target;
+}
+//# sourceMappingURL=timing-dump.js.map

package/dist/timing-dump.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing-dump.js","sourceRoot":"","sources":["../src/timing-dump.ts"],"names":[],"mappings":"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"}

package/eslint/README.md

@@ -25,7 +25,7 @@ export default [
 ];
 ```
 
-`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`.
+`configs.recommended` registers the plugin under the `@vibe-agent-toolkit` namespace and enables the **cross-platform safety core** — 18 of the 22 rules, most at `error` and three at `warn` (see [Severities](#severities)). The other four 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:
 
@@ -111,6 +111,21 @@ Two ways your target can be wrong, which surface differently: `ERR_MODULE_NOT_FO
 | `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` |
+| `no-bare-symlink-in-tests` | unguarded `fs.symlinkSync()` / `fs.promises.symlink()` | in tests: `createSymlink(cap, …)` / `createSymlinkAsync(cap, …)`; in shipped code: a win32 junction, or a `catch` naming the privilege | `/testing` | | — |
+
+**`no-bare-symlink-in-tests` reports two different remedies, and the name is narrower than the rule.**
+Creating a symlink on Windows requires `SeCreateSymbolicLinkPrivilege` — Developer Mode or an
+elevated shell — which most user machines and CI agents lack. In a **test file** the fix is to probe
+with `symlinkCapability()` and pass the resulting token to `createSymlink()`, so a host without the
+privilege produces a visible `skip()` rather than a failure or a silently-swallowed one. In **shipped
+code** there is deliberately no wrapper to route through: `createSymlink()` lives on the `/testing`
+subpath, and pointing production code at a test helper would be worse advice than the bare call.
+There the guidance is a junction for a directory link on win32 (no elevation required), or catching
+the failure and naming the missing privilege. Declaring a platform out of scope is legitimate —
+say so in an `eslint-disable` justification, which is what `vat agent install --dev` does.
+
+`exemptFiles` matters here: the implementation file holding the sanctioned `symlinkSync` is not a
+test file, so it needs an explicit exemption once the rule covers shipped code.
 
 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.
 
@@ -122,6 +137,63 @@ The member-call rules here check the **receiver**, not just the method name, so
 | `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` |
 
+### Content decoding
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `no-raw-text-decode` | `buf.toString('utf-8')`, `new TextDecoder(…)`, `readFile(p, 'utf-8')` | one project-owned decoding seam | — | | — |
+
+`buf.toString('utf-8')` ignores every byte-order mark and cannot express UTF-16BE at all — Node's `Buffer` has no such encoding. A UTF-16 document therefore decodes to NUL-interleaved mojibake, and whatever sniffs for binary content downstream believes it. PowerShell 5.1's `Out-File` and `>` write UTF-16LE by default, so this is a Windows-authored file, not an exotic one.
+
+This rule has no wrapper to point at, because the seam is yours: write one decoder, name it with `safeModule`, and exempt its own file with `exemptFiles`. Put the decoder at the **bottom** of your dependency arrow — a seam in a leaf package cannot be imported by the primitive packages the rule also lints, and those files would then have no legal way to comply.
+
+**Not every `'utf-8'` read is a content read**, and this is the distinction that decides whether the rule survives. Three categories:
+
+1. **A document you did not write** — an adopter's markdown, config, schema, `.gitignore`, `package.json`. The encoding must be **discovered**. This is the rule's target.
+2. **An artifact your project wrote** — its own cache entry, its own published asset. The encoding was **chosen at the write**; reading it back the same way is a closed loop.
+3. **Bytes that were never a file** — subprocess stdout, an HTTP body, a Buffer you built. The **producer's contract** decides.
+
+Static analysis cannot tell them apart, so the rule reports all three and you settle 2 and 3 at the call site with a one-line `eslint-disable-next-line` that **names the writer or the producer**:
+
+```js
+// eslint-disable-next-line @vibe-agent-toolkit/no-raw-text-decode -- subprocess stdout; producer is the credential helper spawned above
+const out = result.stdout.toString('utf8');
+```
+
+That gives a reviewer a falsifiable test: a justification that cannot name who wrote the bytes is a category-1 call wearing a disable comment. Do not settle these by adding paths to `exemptFiles` — that list is for the seam's own implementation file.
+
+```js
+{
+  files: ['src/corpus/**/*.ts'],
+  rules: {
+    '@vibe-agent-toolkit/no-raw-text-decode': ['error', {
+      safeModule: '@my-org/resources',
+      exemptFiles: ['src/corpus/text-content.ts'],
+    }],
+  },
+}
+```
+
+Only a string **literal** encoding triggers it. `buf.toString(enc)` is deliberately not reported: without type information it is indistinguishable from `n.toString(radix)`, and `readFile(p, cb)` from `readFile(p, encoding)`.
+
+### Build correctness
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `no-self-package-import` | importing the enclosing package by its own name | a relative path to the defining module | — | | — (needs `packageName`) |
+
+A file inside `packages/foo` that writes `import … from '@scope/foo'` resolves out through `node_modules` to its own `package.json`, whose `types` point at `./dist/index.d.ts` — a file the compiler is in the middle of producing. It works only by a TypeScript courtesy: while `dist` **is** the running project's output path, that declaration is recognised as the project's own output and the import is redirected back to `src`, so it resolves with no `dist/` on disk.
+
+Change `outDir` — to a staging directory that makes emit atomic, say — and 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.
+```
+
+The knock-on `TS2339`s land wherever a local type extended one of the now-unresolved imports, which is what makes it read as a type bug in code nobody touched.
+
+It is latent by construction, and worse, **it is invisible to any tree that has built before**: a stale `dist/` satisfies the literal lookup, so the build passes by typechecking against the *previous* build's declarations. In a monorepo whose worktrees live inside the main checkout, resolution walks up past the worktree and satisfies it from the *parent checkout's* `dist/`. Both are green locally and red in CI, which is the only genuinely pristine tree. Lint is the only stage that sees it on the author's machine.
+
 ### Code and test hygiene
 
 | Rule | Bans | Use instead | Subpath | Fix | `recommended` |
@@ -132,7 +204,7 @@ The member-call rules here check the **receiver**, not just the method name, so
 
 ### What `recommended` deliberately leaves out
 
-Three rules ship without riding in `recommended`, for two different reasons.
+Six rules ship without riding in `recommended`, for five 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.
 
@@ -147,7 +219,27 @@ safePath.join(base, userInput)              // SILENT — the shape it exists to
 
 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:
+**No wrapper to point at** — `no-raw-text-decode`. Every other rule in this pack names a replacement this package publishes; this one names a decoding seam that only exists once *you* write it. Shipped in `recommended`, its every message would read "use `decodeTextContent()` from your content-decoding module", which is advice nobody can follow. Turn it on with `safeModule` and `exemptFiles` set, as shown above.
+
+**Needs an option, and only in the directories you compile** — `no-self-package-import`. The import it bans is a genuine build-breaker with no style opinion in it, but the rule cannot discover on its own which package a file is in: reading `package.json` would mean `require('node:fs')`, and every module on this subpath is plain data that requires *nothing* — not `eslint`, not a third-party package, not even a Node builtin. That is what keeps `eslint` an optional peer dependency and lets these rules ship as a subpath of a runtime package rather than as one of their own. So the caller names the package. The caller is a config file, which already runs in full Node and can read every manifest it likes:
+
+```js
+import { readFileSync, readdirSync } from 'node:fs';
+
+export default readdirSync('packages').flatMap((dir) => {
+  const { name } = JSON.parse(readFileSync(`packages/${dir}/package.json`, 'utf8'));
+  return [{
+    files: [`packages/${dir}/src/**/*.ts`],
+    rules: { '@vibe-agent-toolkit/no-self-package-import': ['error', { packageName: name }] },
+  }];
+});
+```
+
+Scope it to the sources you **compile**. Test and example trees — normally excluded from the build — import their own package by name **on purpose**, to exercise the public entry point exactly as a consumer does. This repo has ~10 such imports, every one of them correct.
+
+**Half its advice is unreachable without a helper you may not have** — `no-bare-symlink-in-tests`. In a test file it points at `createSymlink()` / `createSymlinkAsync()`, which live on *this* package's `./testing` subpath and route through a probed capability token; an adopter on a different test runner, or with no symlink-heavy tests, should not silently inherit that opinion — nor the vitest-specific `skip()` idiom the message names. Its **shipped-code** half (`unguardedSymlink`) carries neither dependency and is portable advice on its own, so this is the one exclusion that is half arbitrary; it stays out because the two halves cannot be enabled separately. This repo turns it on explicitly, scoped to its own test-file convention.
+
+Enable any of the six by naming it:
 
 ```js
 import vat from '@vibe-agent-toolkit/utils/eslint';
@@ -160,6 +252,16 @@ export default [
       '@vibe-agent-toolkit/require-justified-skip': 'error',
     },
   },
+  {
+    // Scope it to the code that reads files whose encoding you do not choose.
+    files: ['src/corpus/**/*.ts'],
+    rules: {
+      '@vibe-agent-toolkit/no-raw-text-decode': ['error', {
+        safeModule: '@my-org/resources',
+        exemptFiles: ['src/corpus/text-content.ts'],
+      }],
+    },
+  },
   {
     // Scope it to where an escape is a security boundary, not repo-wide.
     files: ['src/staging/**/*.ts'],

package/eslint/index.cjs

@@ -50,7 +50,10 @@ const rules = {
   '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'),
+  'no-raw-text-decode': require('./rules/no-raw-text-decode.cjs'),
+  'no-self-package-import': require('./rules/no-self-package-import.cjs'),
   'require-justified-skip': require('./rules/require-justified-skip.cjs'),
+  'no-bare-symlink-in-tests': require('./rules/no-bare-symlink-in-tests.cjs'),
 };
 
 /**
@@ -95,6 +98,44 @@ const RECOMMENDED_EXCLUDE = new Set([
   // 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',
+  // Excluded because it names a seam that does not exist until a consumer builds
+  // one. `decodeTextContent()` is VAT's module, in VAT's repo; an adopter who
+  // installed this package for `safePath.join()` has no content-decoding seam to
+  // be pointed at, so `recommended` would hand them a rule whose every message
+  // advises importing from `your content-decoding module`. It ships in `rules`
+  // and is enabled — with `safeModule` naming the real seam and `exemptFiles`
+  // naming the file that implements it — by whoever has one. VAT itself does
+  // exactly that, scoped to the directories that read corpus documents.
+  'no-raw-text-decode',
+  // Excluded for two reasons, either of which would be enough. It REQUIRES a
+  // `packageName` option — it will not read a `package.json` to find out, because
+  // that would mean `require('node:fs')` and break the empty-external-set property
+  // this whole subpath rests on — and a rule with a required option cannot ride in
+  // a config that supplies none. And the directories it must not fire in are a
+  // property of the adopter's `tsconfig`, not of this package: a self-import only
+  // breaks the build in files the package actually COMPILES, while test and
+  // example trees import their own package by name on purpose, to exercise the
+  // public entry point the way a consumer does. This repo has ~10 such imports
+  // across `utils`, `agent-skills`, `claude-marketplace` and
+  // `vat-example-cat-agents`, every one of them correct. It ships in `rules`, and
+  // `eslint.config.js` generates one scoped block per workspace package.
+  'no-self-package-import',
+  // Excluded for its TEST half only, which is the honest way to say it. That
+  // half names a vitest-specific idiom (`skip()` from the per-test context) and
+  // a replacement — `createSymlink()` / `createSymlinkAsync()` /
+  // `symlinkCapability()` — living on THIS package's own `./testing` subpath
+  // rather than on a seam every consumer already has. An adopter using a
+  // different test runner, or no symlink-heavy tests at all, should not
+  // silently inherit an opinion about vitest control flow.
+  //
+  // ⚠️ The rule now covers SHIPPED code too, and that half (`unguardedSymlink`)
+  // has neither dependency: it names the Windows privilege and a junction, both
+  // portable facts. So this exclusion is weaker than it reads — the two halves
+  // share one rule id and cannot be enabled separately, and the test half is
+  // what keeps the pair out. Splitting the rule would let the production half
+  // ride in `recommended`; that is a public-API change and has not been made.
+  // VAT enables the whole rule explicitly, scoped to its own conventions.
+  'no-bare-symlink-in-tests',
 ]);
 
 /**

package/eslint/index.d.cts

@@ -47,10 +47,13 @@ declare namespace plugin {
     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.
+       * The cross-platform safety core: 18 of the 22 rules, 15 `error` / 3 `warn`.
+       * Four are excluded, for three reasons: `no-test-scoped-functions` and
+       * `require-justified-skip` are positions on test style rather than
+       * portability facts; `no-unsafe-root-join` keys on naming rather than taint;
+       * and `no-raw-text-decode` names a decoding seam that only exists in the
+       * consuming repo. All four still ship in `rules` and are enabled by naming
+       * them.
        */
       recommended: FlatConfig;
     };