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

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

@@ -0,0 +1,213 @@
+/**
+ * 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: 'Filesystem and process',
+      bans: 'unguarded `fs.symlinkSync()` / `fs.promises.symlink()`',
+      useInstead: 'in tests: `createSymlink(cap, …)` / `createSymlinkAsync(cap, …)`; in shipped code: a win32 junction, or a `catch` naming the privilege',
+      subpath: '/testing',
+      // Not in `recommended`: half its advice is unreachable without a helper the
+      // consumer may not have. In a test file it points at `createSymlink()` /
+      // `createSymlinkAsync()` on THIS package's `./testing` subpath, routed through
+      // a probed capability token and the vitest-specific `skip()` idiom; an adopter
+      // on a different runner should not silently inherit that. Its shipped-code
+      // half (`unguardedSymlink`) is portable advice on its own — the two share one
+      // rule id and cannot be enabled separately, and the test half is what keeps
+      // the pair out. VAT enables the whole rule explicitly.
+      recommended: false,
+      recommendedSeverity: 'error',
+    },
+    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-blind-catch.cjs

@@ -0,0 +1,171 @@
+/**
+ * ESLint rule: no-blind-catch
+ *
+ * Flags a `catch` clause that never LOOKS at its error and never THROWS. Such
+ * a clause answers every failure the same way — a sentinel `return null`, a
+ * `continue`, an empty body, a fallback assignment — so the case it was
+ * written for (a file that is not there) becomes indistinguishable from the
+ * cases it was not (a permission refusal, a corrupt artifact, a `TypeError`
+ * from a bug two frames down). The result is a tool that is quietest exactly
+ * when it is most wrong: a directory the OS refused to list reports as empty,
+ * and a build that examined nothing exits 0.
+ *
+ * This is the class behind the worst finding in seven consecutive adversarial
+ * review rounds on one branch. A crawler learned to REFUSE an unreadable
+ * directory instead of skipping it; one caller's `catch { return null }`
+ * absorbed the refusal, and `vat audit` silently ran with no population. The
+ * fix was type-forcing the seam so `tsc` enumerated the callers — but a blind
+ * `catch` is the one seam `tsc` cannot see, because it compiles for every
+ * callee that ever learns to throw.
+ *
+ * ## What counts as handling
+ *
+ * The rule is a FLOOR, deliberately syntactic: the clause is fine if either
+ *
+ * 1. the error binding is REFERENCED anywhere in the body — narrowing on it
+ *    (`isFilesystemAccessError(e)`, `e instanceof X`, `e.code === 'ENOENT'`),
+ *    carrying it into a report (`errors.push(String(e))`, `{ ok: false, error }`),
+ *    or logging it — or
+ * 2. the body THROWS (a rethrow, or a translation into a louder error), at the
+ *    clause's own level — a `throw` inside a nested function is a promise to
+ *    fail later, not a rethrow from this catch.
+ *
+ * A reference is a reference: the rule cannot tell `narrow(e)` from `log(e)`,
+ * and does not try. What it guarantees is the weaker, enforceable property —
+ * *the error was looked at before being discarded* — which is the property
+ * every one of the shipped defects lacked.
+ *
+ * ## What this rule does NOT catch
+ *
+ * - `catch (e) { void e; return null; }` — a reference written to dodge the
+ *   rule. Code review's job.
+ * - A narrowing that is wrong: `if (e instanceof Error) return null` looks at
+ *   the error and still absorbs everything. The rule sees a reference.
+ * - A catch whose body references the binding only to build a message it
+ *   then throws away.
+ *
+ * There is deliberately NO annotation escape hatch. Every site this rule
+ * flags has a legitimate rewrite — narrow and rethrow, or carry the error into
+ * the result — and an `eslint-disable` with a reason is already the escape
+ * hatch ESLint provides, visible in the diff and countable with
+ * `rg 'eslint-disable.*no-blind-catch'`.
+ *
+ * @example
+ * // BAD — "not there" and "refused" and "bug" all become null
+ * try { return statSync(p); } catch { return null; }
+ *
+ * // GOOD — narrowed to the case the sentinel means, everything else stays loud
+ * try { return statSync(p); } catch (e) {
+ *   if (isPathAbsentError(e)) return null;
+ *   throw e;
+ * }
+ *
+ * // GOOD — the error reaches the report instead of vanishing
+ * try { return parse(text); } catch (e) {
+ *   return { ok: false, reason: String(e) };
+ * }
+ */
+
+'use strict';
+
+/** Function-boundary node types: a `throw` inside one is not this clause's throw. */
+const FUNCTION_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+]);
+
+/** Keys on an ESTree node that point somewhere other than a child. */
+const NON_CHILD_KEYS = new Set(['parent', 'loc', 'range']);
+
+/** Whether `value` is an ESTree node (as opposed to a token, a literal, or null). */
+function isNode(value) {
+  return value !== null && typeof value === 'object' && typeof value.type === 'string';
+}
+
+/** Every child node of `node`, in no particular order. */
+function childNodes(node) {
+  const children = [];
+  for (const key of Object.keys(node)) {
+    if (NON_CHILD_KEYS.has(key)) {
+      continue;
+    }
+    const value = node[key];
+    const values = Array.isArray(value) ? value : [value];
+    children.push(...values.filter((child) => isNode(child)));
+  }
+  return children;
+}
+
+/**
+ * Whether `body` contains a `ThrowStatement` reachable without crossing a
+ * function boundary. Iterative so a deeply nested body cannot blow the stack.
+ */
+function throwsAtOwnLevel(body) {
+  const stack = [body];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (node.type === 'ThrowStatement') {
+      return true;
+    }
+    if (!FUNCTION_TYPES.has(node.type)) {
+      stack.push(...childNodes(node));
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether any binding the clause declares (`catch (e)`, `catch ({ code })`) is
+ * read in the body. A clause with no param declares nothing and reads nothing.
+ */
+function readsErrorBinding(sourceCode, node) {
+  if (node.param === null) {
+    return false;
+  }
+  const declared = sourceCode.getDeclaredVariables(node);
+  return declared.some((variable) => variable.references.length > 0);
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow a catch clause that neither reads its error nor throws — it absorbs a bug, a ' +
+        'permission refusal, or a corrupt artifact into the same answer as the case it was written for',
+      category: 'Error handling',
+      bans: 'a `catch` that neither reads its error nor throws',
+      useInstead: 'narrow on the error and rethrow the rest, or carry it into the result',
+      // `warn`, not `error`: the same migration-volume criterion as
+      // `no-raw-node-path`, without the autofix. A blind `catch` has no
+      // mechanical rewrite — each site is a decision about WHICH failure the
+      // sentinel stands for — and the first run on an existing tree is a long
+      // list (202 sites on this repo's own ~200k lines). `warn` makes that a
+      // backlog to burn down rather than a wall; the hazard is real at every one.
+      recommended: true,
+      recommendedSeverity: 'warn',
+    },
+    schema: [],
+    messages: {
+      blindCatch:
+        'This catch discards the error without looking at it, so a bug, a permission refusal, or a ' +
+        'corrupt artifact is absorbed into the same result as the case it was written for. Narrow it ' +
+        "to that case and rethrow the rest — `if (isPathAbsentError(e)) return null; throw e;` — or " +
+        'carry the error into the result so the report can show it.',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    return {
+      CatchClause(node) {
+        if (readsErrorBinding(sourceCode, node) || throwsAtOwnLevel(node.body)) {
+          return;
+        }
+        context.report({ node, messageId: 'blindCatch' });
+      },
+    };
+  },
+};

package/eslint/rules/no-child-process-execSync.cjs

@@ -20,4 +20,12 @@ module.exports = factory({
   message: 'Use safeExecSync() from {{safeModule}} instead of child_process.execSync() to prevent command injection (security + cross-platform)',
   // No baked-in exemption: the file that implements safeExecSync() is
   // repo-specific. Consumers declare it as { exemptFiles: [...] }.
+  docs: {
+    category: 'Filesystem and process',
+    bans: '`child_process.execSync()`',
+    useInstead: '`safeExecSync()`',
+    subpath: '/process',
+    recommended: true,
+    recommendedSeverity: 'error',
+  },
 });

package/eslint/rules/no-decaying-referent.cjs

@@ -0,0 +1,217 @@
+/**
+ * ESLint rule: no-decaying-referent
+ *
+ * Flags, in comments under `src/`, three kinds of referent that rot in place:
+ *
+ * - an issue or PR number (`#145`) — the issue closes, the PR merges, and the
+ *   comment keeps pointing at a discussion nobody reopens;
+ * - an ISO date (`2026-08-22`, `2026-08`) — "re-derived on" is a claim about
+ *   freshness that is false the day after it is written;
+ * - a named person (`Jeff`, configurable) — a ruling attributed to someone is a
+ *   ruling nobody else feels entitled to revisit.
+ *
+ * None of these is the RULE the comment exists to state. The rule stays; the
+ * history goes where history is kept — the commit message, the CHANGELOG, or
+ * `docs/contributing/` — and `git log -L` holds the rest without decaying.
+ *
+ * Scope: files with a `/src/` segment that are not test files. Tests and
+ * scripts are not linted here; Markdown never reaches ESLint. One report per
+ * comment block, on the FIRST referent found, whichever kind it is — the fix is
+ * to rewrite the comment, not to hunt tokens one at a time.
+ *
+ * Options:
+ * - `names: string[]` — whole-word, case-sensitive names to treat as referents
+ *   (default `['Jeff']`). Pass `[]` to disable the class.
+ * - `allowDates: boolean` — leave dates alone (default `false`).
+ *
+ * One line shape is exempt without an option: `@vendor-claim reviewed=<date>
+ * verify=<how>`. That date is READ by a freshness gate that fails the build when
+ * it ages past its budget — a date with a mechanism behind it is the opposite of
+ * a decaying one. The exemption covers only the line carrying the tag.
+ *
+ * @example
+ * // BAD — the reader must open #145 to learn what the code does
+ * // Fixed in #145 (Jeff, 2026-08-22): skip the second crawl.
+ *
+ * // GOOD — the rule, stated; the history is in `git log -L`
+ * // The second crawl is skipped: the first already answered from git.
+ */
+
+'use strict';
+
+const { isTestFile } = require('./exempt-path-matcher.cjs');
+
+/** `#12` … `#1234`, not preceded by a word/URL/entity character and not part of a longer number. */
+const ISSUE_REF = /(?<![\w/&#])#\d{2,4}(?!\d)/u;
+
+/**
+ * `20YY-MM` or `20YY-MM-DD`, standing alone. Glued to a word, a hyphen or a
+ * path separator it names a thing (`sweep-2026-09-12/`, a JSON Schema dialect's
+ * `draft/2020-12/schema`), not a day something was true.
+ */
+const ISO_DATE = /(?<![\w/-])20\d\d-\d\d(?:-\d\d)?(?![\w-])/u;
+
+/** A character that continues a word, for the whole-word check on names. */
+const WORD_CHAR = /\w/u;
+
+/** The one annotation whose date is machine-checked rather than left to rot. */
+const VENDOR_CLAIM_TAG = '@vendor-claim';
+
+/**
+ * `text` with every line carrying {@link VENDOR_CLAIM_TAG} blanked to spaces
+ * of the same length, so match indices still map onto the original comment.
+ */
+function blankVendorClaimLines(text) {
+  if (!text.includes(VENDOR_CLAIM_TAG)) {
+    return text;
+  }
+  return text
+    .split('\n')
+    .map((line) => (line.includes(VENDOR_CLAIM_TAG) ? ' '.repeat(line.length) : line))
+    .join('\n');
+}
+
+/**
+ * The first whole-word, case-sensitive occurrence of any of `names` in `text`,
+ * as a `{ index, match }` pair, or null. A hand search rather than a built
+ * RegExp so a configured name needs no escaping and the rule stays free of a
+ * non-literal RegExp constructor.
+ */
+function findWholeWordName(text, names) {
+  let best = null;
+  for (const name of names) {
+    let from = 0;
+    for (;;) {
+      const index = text.indexOf(name, from);
+      if (index === -1 || (best !== null && index >= best.index)) {
+        break;
+      }
+      const boundedBefore = index === 0 || !WORD_CHAR.test(text[index - 1]);
+      const boundedAfter = !WORD_CHAR.test(text[index + name.length] ?? '');
+      if (boundedBefore && boundedAfter) {
+        best = { index, match: name };
+        break;
+      }
+      from = index + 1;
+    }
+  }
+  return best;
+}
+
+/** Whether a linted filename is a non-test file under a `src/` directory. */
+function isSourceFile(filename) {
+  if (!filename) {
+    return false;
+  }
+  // eslint-disable-next-line local/no-manual-path-normalize -- the rule pack is standalone CommonJS and cannot import the ESM helper; config paths and linted filenames are matched separator-agnostically on purpose.
+  const normalized = String(filename).replaceAll('\\', '/');
+  return normalized.includes('/src/') && !isTestFile(normalized);
+}
+
+/**
+ * The earliest referent in `text` across the enabled classes, or null.
+ * Each class contributes at most its first match; the earliest of those wins.
+ */
+function firstReferent(text, matchers) {
+  let best = null;
+  for (const { kind, find } of matchers) {
+    const found = find(text);
+    if (found !== null && (best === null || found.index < best.index)) {
+      best = { kind, referent: found.match, index: found.index };
+    }
+  }
+  return best;
+}
+
+/** A matcher backed by a RegExp literal. */
+function regexMatcher(kind, pattern) {
+  return {
+    kind,
+    find(text) {
+      const match = pattern.exec(text);
+      return match === null ? null : { index: match.index, match: match[0] };
+    },
+  };
+}
+
+/**
+ * The source location of `index` within a comment's value, accounting for the
+ * two-character opener (`//`, `/*`, `#!`) and any newlines before the match.
+ */
+function locationInComment(comment, index) {
+  const before = comment.value.slice(0, index);
+  const lastNewline = before.lastIndexOf('\n');
+  const newlines = before.match(/\n/gu)?.length ?? 0;
+  const line = comment.loc.start.line + newlines;
+  const column = lastNewline === -1 ? comment.loc.start.column + 2 + index : index - lastNewline - 1;
+  return { line, column };
+}
+
+/** Build the enabled matcher table from the rule options. */
+function buildMatchers(options) {
+  const matchers = [regexMatcher('an issue or PR number', ISSUE_REF)];
+  if (options.allowDates !== true) {
+    matchers.push(regexMatcher('a date', ISO_DATE));
+  }
+  const names = (options.names ?? ['Jeff']).filter((name) => name.length > 0);
+  if (names.length > 0) {
+    matchers.push({ kind: 'a person', find: (text) => findWholeWordName(text, names) });
+  }
+  return matchers;
+}
+
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Disallow issue/PR numbers, ISO dates and named people in src comments — they decay in ' +
+        'place; the rule belongs in the comment and the history in the commit, CHANGELOG or docs',
+      recommended: false,
+      recommendedSeverity: 'warn',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          names: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+          allowDates: { type: 'boolean' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      decayingReferent:
+        'This comment cites {{kind}} ({{referent}}), which decays in place: nobody rewrites the ' +
+        'comment when the issue closes, the date passes, or the person moves on. Keep the rule the ' +
+        'comment states and move the history to the commit message, the CHANGELOG, or ' +
+        'docs/contributing/ — `git log -L` keeps the rest.',
+    },
+  },
+
+  create(context) {
+    const filename = context.filename ?? context.getFilename();
+    if (!isSourceFile(filename)) {
+      return {};
+    }
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const matchers = buildMatchers(context.options?.[0] ?? {});
+
+    return {
+      Program() {
+        for (const comment of sourceCode.getAllComments()) {
+          const found = firstReferent(blankVendorClaimLines(comment.value), matchers);
+          if (found === null) {
+            continue;
+          }
+          const start = locationInComment(comment, found.index);
+          context.report({
+            loc: { start, end: { line: start.line, column: start.column + found.referent.length } },
+            messageId: 'decayingReferent',
+            data: { kind: found.kind, referent: found.referent },
+          });
+        }
+      },
+    };
+  },
+};