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

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-process-exit-in-phase.cjs

@@ -0,0 +1,117 @@
+/**
+ * ESLint Rule: no-process-exit-in-phase
+ *
+ * Forbid `process.exit()` inside a phase entry point — a function whose name
+ * ends in `Phase`.
+ *
+ * ## Why this rule exists
+ *
+ * `vat validate`, `vat verify` and `vat build` used to run each phase as a
+ * SEPARATE CHILD PROCESS. A `process.exit()` inside a phase was then perfectly
+ * safe: it ended that child, the parent read the exit code, and the run carried
+ * on to the next phase. Nothing about the code said so — the safety came
+ * entirely from the process boundary.
+ *
+ * That boundary is gone. Phases now run in the orchestrator's own process, so a
+ * surviving `process.exit()` ends THE WHOLE RUN: every later phase is silently
+ * skipped, the parent's aggregation never happens, and the process exits 0-or-1
+ * having done half the work with nothing in the document to say so. It is the
+ * worst shape of failure this codebase has — a confident, well-formed, wrong
+ * answer — and it cannot be caught by a type, because `process.exit()`
+ * typechecks anywhere.
+ *
+ * A phase must RETURN `{ document, exitCode }` and let its caller decide whether
+ * to print and exit (a command-line run) or to fold the result into the run (an
+ * orchestrated one).
+ *
+ * ## Why the name is the marker
+ *
+ * The `…Phase` suffix is the convention every phase entry point already follows
+ * (`runResourcesValidatePhase`, `runSkillsBuildPhase`, …). Keying the rule to it
+ * means a new phase is protected the moment it is named like one, with no list
+ * to keep in sync — a list is the thing that goes stale silently, which is the
+ * defect class this rule exists to prevent in the first place.
+ *
+ * The thin Commander wrappers that CALL these functions keep their
+ * `process.exit()`: deciding how the process ends is exactly their job, and they
+ * are not named `…Phase`.
+ */
+
+/** Does this call expression read as `process.exit(...)`? */
+function isProcessExitCall(node) {
+  const { callee } = node;
+  return (
+    callee.type === 'MemberExpression' &&
+    !callee.computed &&
+    callee.object.type === 'Identifier' &&
+    callee.object.name === 'process' &&
+    callee.property.type === 'Identifier' &&
+    callee.property.name === 'exit'
+  );
+}
+
+/**
+ * The declared name of a function-ish node, however it was declared.
+ *
+ * Covers the three spellings a phase entry point can legitimately take: a
+ * function declaration, a `const x = function () {}`, and a `const x = () => {}`.
+ * A rule that only understood declarations would be silently inert against an
+ * arrow const — the same blind spot `no-test-scoped-functions` documents.
+ */
+function functionName(node) {
+  if (node.id && node.id.type === 'Identifier') return node.id.name;
+
+  const { parent } = node;
+  if (parent && parent.type === 'VariableDeclarator' && parent.id.type === 'Identifier') {
+    return parent.id.name;
+  }
+  if (parent && parent.type === 'Property' && parent.key.type === 'Identifier') {
+    return parent.key.name;
+  }
+  return undefined;
+}
+
+const FUNCTION_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+]);
+
+/** The nearest enclosing function named like a phase entry point, if any. */
+function enclosingPhaseName(node) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (!FUNCTION_TYPES.has(current.type)) continue;
+    const name = functionName(current);
+    if (name !== undefined && name.endsWith('Phase')) return name;
+  }
+  return undefined;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Forbid process.exit() inside a phase entry point, where it would end the whole orchestrated run',
+      category: 'Agentic Code Safety',
+      recommended: true,
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      exitInPhase:
+        "'{{name}}' is a phase entry point, so process.exit() here ends the ENTIRE run — every later phase is skipped and the orchestrator never aggregates. Return { document, exitCode } instead and let the caller decide how the process ends.",
+    },
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!isProcessExitCall(node)) return;
+        const name = enclosingPhaseName(node);
+        if (name === undefined) return;
+        context.report({ node, messageId: 'exitInPhase', data: { name } });
+      },
+    };
+  },
+};

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 },
+          });
+        }
+      },
+    };
+  },
+};