mandrel 2.57.0 → 2.59.0

package/.agents/scripts/lib/escomplex-ast-compat.js

@@ -4,8 +4,8 @@
  *
  * ## The upstream defect
  *
- * `typhonjs-escomplex` parses with `@typhonjs/babel-parser`, so every AST it
- * analyses is a **Babel** AST. But `typhonjs-escomplex-commons`'
+ * The kernel parses with `@babel/parser`, so every AST it analyses is a
+ * **Babel** AST. But `typhonjs-escomplex-commons`'
  * `utils/ast/astSyntax.js` — the code generator that `ASTGenerator` drives —
  * was written against **ESTree**. The two disagree on node names
  * (`OptionalMemberExpression` vs a `MemberExpression` with `optional: true`)
@@ -62,6 +62,21 @@ import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
 
+/**
+ * The package whose resolution anchors every `typhonjs-escomplex-commons` deep
+ * import in this module.
+ *
+ * `escomplex-plugin-syntax-babylon` is the package that actually reads the
+ * `astSyntax` table during a metric traversal, so its copy of `commons` is the
+ * only one worth patching.
+ *
+ * Module-local on purpose. A test proves the binding by resolving from this
+ * package's own root itself — which is the assertion worth making, since our
+ * copy and the plugin's coincide under a hoisting installer and an
+ * "ours === theirs" check would pass vacuously.
+ */
+const ANCHOR_PACKAGE = 'escomplex-plugin-syntax-babylon';
+
 /** Marker set on every function this module installs, for idempotency. */
 const PATCH_MARKER = Symbol.for('mandrel.escomplexAstCompat');
 
@@ -77,25 +92,32 @@ let installResult = null;
  * back to today's behaviour (unscorable files, now reported explicitly by
  * the engine rather than silently scored 0).
  *
- * The patch must land on the *same* `typhonjs-escomplex-commons` instance the
- * kernel loads, so `commons` is resolved **through `typhonjs-escomplex`'s own
- * resolution** rather than from here. Resolving it directly would be a coin
- * flip: under a hoisting installer it usually finds the same copy, but under
- * pnpm's isolated layout — or as soon as anything declares `commons` directly —
- * it can find a *different* physical copy, and the patch then lands on a table
- * nobody reads while `install()` cheerfully reports success. Anchoring makes
- * that failure mode unreachable.
+ * The patch must land on the *same* `astSyntax` table the metric traversal
+ * reads, and that table is resolved by **`escomplex-plugin-syntax-babylon`**,
+ * from its own location — `PluginSyntaxBabylon` requires
+ * `typhonjs-escomplex-commons/dist/utils/ast/ASTGenerator` and `ASTState` binds
+ * the table it finds. So `commons` is anchored through the syntax plugin's
+ * resolution, not through this module's and not through the kernel's.
+ *
+ * Resolving it from here, or from the kernel, would be a coin flip: under a
+ * hoisting installer every copy usually coincides, but under pnpm's isolated
+ * layout — or as soon as anything declares `commons` at a different version —
+ * the plugin can read a *different* physical copy, and the patch then lands on
+ * a table nobody reads while `install()` cheerfully reports success. Anchoring
+ * on the reader makes that unreachable. Note this is why a test asserting
+ * "our copy === the patched copy" proves nothing: under hoisting it passes
+ * vacuously — a test must resolve from the plugin's own root instead.
  *
  * `requireFn` is the test seam: a cross-checkout verification harness passes
- * its own `createRequire` so the anchor starts from that checkout's escomplex.
+ * its own `createRequire` so the anchor starts from that checkout's plugin.
  *
  * @param {NodeJS.Require} [requireFn]
  * @returns {Record<string, Function>|null}
  */
 function resolveSyntaxTable(requireFn = require) {
   try {
-    const fromKernel = createRequire(requireFn.resolve('typhonjs-escomplex'));
-    const mod = fromKernel(
+    const fromReader = createRequire(requireFn.resolve(ANCHOR_PACKAGE));
+    const mod = fromReader(
       'typhonjs-escomplex-commons/dist/utils/ast/astSyntax.js',
     );
     const table = mod?.default ?? mod;
@@ -337,8 +359,8 @@ export function install(options = {}) {
 /**
  * `ASTUtil` is only needed by the `OptionalCallExpression` handler, and only at
  * call time — resolving it lazily keeps `install()` free of a second deep
- * import that could fail at module load. Anchored through the kernel for the
- * same reason as {@link resolveSyntaxTable}.
+ * import that could fail at module load. Anchored through the syntax plugin
+ * for the same reason as {@link resolveSyntaxTable}.
  *
  * `formatSequence` is a pure helper that takes the traveler and state as
  * arguments, so which copy answers is immaterial — but resolving it the same
@@ -347,8 +369,8 @@ export function install(options = {}) {
  * @returns {{ formatSequence: Function }}
  */
 function ASTUtil() {
-  const fromKernel = createRequire(require.resolve('typhonjs-escomplex'));
-  const mod = fromKernel(
+  const fromReader = createRequire(require.resolve(ANCHOR_PACKAGE));
+  const mod = fromReader(
     'typhonjs-escomplex-commons/dist/utils/ast/ASTUtil.js',
   );
   return mod?.default ?? mod;

package/.agents/scripts/lib/escomplex-kernel.js

@@ -0,0 +1,298 @@
+/**
+ * escomplex-kernel.js — the complexity kernel's parse and dispatch layers,
+ * in-repo.
+ *
+ * ## Why this file exists
+ *
+ * `typhonjs-escomplex` was a thin shell around four packages that do all the
+ * actual work. The shell contributed two things: a parser front-end
+ * (`@typhonjs/babel-parser`, a ~100-LOC shim over `@babel/parser`) and a
+ * generic plugin bus (`typhonjs-plugin-manager`, used as a hardcoded
+ * two-plugin synchronous dispatcher). Nine packages of plumbing hang off
+ * those two, and none of it computes anything.
+ *
+ * What this does **not** do is remove `core-js@2`. Four of the retained
+ * metric-core packages `require('babel-runtime/core-js/*')` themselves, so it
+ * is load-bearing for the code that stays; a change that claimed otherwise
+ * would be unshippable. What it buys instead is an honest closure —
+ * `babel-runtime` is required by those packages and declared by none of them,
+ * so today it resolves only because the removed plumbing hoists it. Declaring
+ * it turns an accident into a contract.
+ *
+ * This module reimplements exactly those two layers over the retained metric
+ * core — `typhonjs-escomplex-commons`, `escomplex-plugin-metrics-module`,
+ * `escomplex-plugin-syntax-babylon`, `typhonjs-ast-walker` — which compute
+ * every score. Nothing here computes a metric; the scores come from the same
+ * packages as before, which is why they do not move.
+ *
+ * ## The equivalence contract
+ *
+ * Reproducing the displaced shell's *behaviour* means reproducing three
+ * details it never documented:
+ *
+ * 1. **The parser's fixed plugin list**, verbatim and in order, with
+ *    `sourceType: 'unambiguous'` — see `PARSER_PLUGINS` below. The list is
+ *    what makes a `.ts` file, a decorator or a pipeline operator parse at
+ *    all, and `unambiguous` is what lets a CommonJS script and an ES module
+ *    both score.
+ * 2. **Both plugin instances, in registration order** — syntax first, then
+ *    metrics. The metrics plugin reads trait tables the syntax plugin put on
+ *    the event.
+ * 3. **One mutable event object per dispatch**, threaded through every plugin
+ *    in turn, with the caller reading the mutations back off it. The displaced
+ *    bus also stamped `$$plugin_invoke_count` / `$$plugin_invoke_names` onto
+ *    every event's data; no plugin and no report reads them, so they are not
+ *    reproduced.
+ *
+ * Equivalence is not asserted by reasoning: `tests/lib/escomplex-kernel.test.js`
+ * replays a corpus captured under the displaced kernel *before* it left the
+ * tree (`tests/fixtures/escomplex-kernel-parity/`), because afterwards there is
+ * nothing left to compare against.
+ *
+ * ## The one uncontrolled input
+ *
+ * `.agents/` materializes into a consumer's repository root, so `@babel/parser`
+ * resolves from **their** `node_modules`. The preflight guard checks presence,
+ * not range, and `@babel/parser@8` is GA and rejects several names in the
+ * fixed plugin list. A manifest range documents the requirement; it does not
+ * enforce it. So the resolved major is asserted here, at load, with an error
+ * that names the problem — rather than surfacing as an opaque plugin-list
+ * syntax error partway through a scan.
+ */
+
+// Every metric-core package is reached by a STATIC import specifier with an
+// explicit `.js` extension. That is not style: `tests/scripts/
+// runtime-deps-drift.test.js` scans for literal `import`/`require` callees, so
+// a package reached through an aliased `createRequire` would be a runtime
+// dependency that is neither declared nor preflighted. The extensions are
+// mandatory because `typhonjs-escomplex-commons` ships an empty
+// `package.json` — no `main`, no `exports` — so a deep path is the only door.
+import { parse as babelParse } from '@babel/parser';
+import PluginMetricsModule from 'escomplex-plugin-metrics-module/dist/PluginMetricsModule.js';
+import PluginSyntaxBabylon from 'escomplex-plugin-syntax-babylon/dist/PluginSyntaxBabylon.js';
+import ASTWalker from 'typhonjs-ast-walker/dist/ASTWalker.js';
+import ModuleScopeControl from 'typhonjs-escomplex-commons/dist/module/report/control/ModuleScopeControl.js';
+import ModuleReport from 'typhonjs-escomplex-commons/dist/module/report/ModuleReport.js';
+import { install as installAstCompat } from './escomplex-ast-compat.js';
+import { describeParserMajorError } from './runtime-deps/parser-major.js';
+
+/**
+ * The displaced parser shim's plugin list, verbatim and in order.
+ *
+ * Order is preserved because it is cheap to preserve, not because a
+ * reordering is known to matter. The two entries with options
+ * (`decorators`, `pipelineOperator`) carry the shim's exact settings —
+ * `decoratorsBeforeExport: false` and the `minimal` pipeline proposal — which
+ * decide whether decorated classes and `|>` parse. Re-cloned per parse so a
+ * parser that mutated its options could not poison a later call.
+ */
+const PARSER_PLUGINS = [
+  'asyncGenerators',
+  'bigInt',
+  'classProperties',
+  'classPrivateProperties',
+  'classPrivateMethods',
+  ['decorators', { decoratorsBeforeExport: false }],
+  'doExpressions',
+  'dynamicImport',
+  'exportDefaultFrom',
+  'exportNamespaceFrom',
+  'functionBind',
+  'functionSent',
+  'importMeta',
+  'jsx',
+  'logicalAssignment',
+  'nullishCoalescingOperator',
+  'numericSeparator',
+  'objectRestSpread',
+  'optionalCatchBinding',
+  'optionalChaining',
+  ['pipelineOperator', { proposal: 'minimal' }],
+  'throwExpressions',
+  'typescript',
+];
+
+/**
+ * The two plugins, in registration order: syntax populates the trait tables
+ * the metrics plugin then reads. Neither defines `onPluginLoad`, and the
+ * displaced bus was constructed without an eventbus, so there is no plugin
+ * lifecycle or eventbus coupling to reproduce — only this list.
+ */
+const PLUGINS = [
+  ['escomplex-plugin-syntax-babylon', new PluginSyntaxBabylon()],
+  ['escomplex-plugin-metrics-module', new PluginMetricsModule()],
+];
+
+// The kernel's code generator predates the Babel AST its own parser emits, so
+// ordinary modern syntax aborts a WHOLE module — see `escomplex-ast-compat.js`
+// for the defect and the upstream status. Installing at the kernel rather than
+// at each caller makes the next scoring entrypoint correct by construction.
+installAstCompat();
+
+const parserProblem = describeParserMajorError();
+if (parserProblem !== null) {
+  throw new Error(`[escomplex-kernel] ${parserProblem}`);
+}
+
+/**
+ * Run one synchronous plugin dispatch.
+ *
+ * Reproduces the displaced bus's `invokeSyncEvents` for the degenerate shape
+ * this kernel uses: no `copyProps` (the shell passed `void 0` at every call
+ * site, so the merge base was always `{}`), no eventbus, and the caller
+ * reading its results back off the same mutated `data` object every plugin
+ * saw.
+ *
+ * @param {string} method Plugin method name, e.g. `onEnterNode`.
+ * @param {object} passthru Properties placed on the event's `data`.
+ * @returns {object} The event `data`, after every plugin has mutated it.
+ */
+function dispatch(method, passthru) {
+  const event = {
+    data: { ...passthru },
+    extra: undefined,
+    eventbus: undefined,
+    pluginName: undefined,
+    pluginOptions: undefined,
+  };
+  for (const [name, instance] of PLUGINS) {
+    if (typeof instance[method] !== 'function') continue;
+    event.pluginName = name;
+    instance[method](event);
+  }
+  return event.data;
+}
+
+/**
+ * The `ignoreKeys` a syntax trait wants withheld from the walker, if any.
+ *
+ * @param {object|undefined} syntax The trait entry for this node type.
+ * @param {object} node
+ * @param {object} parent
+ * @returns {string[]}
+ */
+function traitIgnoreKeys(syntax, node, parent) {
+  return typeof syntax === 'object' && syntax?.ignoreKeys
+    ? syntax.ignoreKeys.valueOf(node, parent)
+    : [];
+}
+
+/**
+ * The new scope a syntax trait opens at this node, if any.
+ *
+ * @param {object|undefined} syntax The trait entry for this node type.
+ * @param {object} node
+ * @param {object} parent
+ * @returns {object|null}
+ */
+function traitNewScope(syntax, node, parent) {
+  if (typeof syntax !== 'object' || !syntax?.newScope) return null;
+  return syntax.newScope.valueOf(node, parent) ?? null;
+}
+
+/**
+ * Build the walker visitor for one module traversal.
+ *
+ * Split out of {@link analyzeModule} so the enter/exit symmetry is readable
+ * side by side: each resolves the trait's scope, brackets the `scopeControl`
+ * mutation with a pre/post dispatch, and straddles it with the node dispatch
+ * in opposite order on the way in and out.
+ *
+ * The two event shapes are not interchangeable, and the difference is the
+ * displaced shell's, not a simplification available here: node events carry
+ * `syntaxes` and scope events do not, and a scope event names its scope
+ * `newScope` on the way in but `scope` on the way out.
+ *
+ * @param {{
+ *   moduleReport: object,
+ *   scopeControl: object,
+ *   syntaxes: Record<string, object>,
+ *   settings: object,
+ * }} context
+ * @returns {{enterNode: Function, exitNode: Function}}
+ */
+function buildVisitor({ moduleReport, scopeControl, syntaxes, settings }) {
+  const nodeBase = { moduleReport, scopeControl, syntaxes, settings };
+  const scopeBase = { moduleReport, scopeControl, settings };
+  return {
+    enterNode(node, parent) {
+      const syntax = syntaxes[node.type];
+      const event = dispatch('onEnterNode', {
+        ...nodeBase,
+        ignoreKeys: traitIgnoreKeys(syntax, node, parent),
+        node,
+        parent,
+      });
+      const ignoreKeys = event !== null ? event.ignoreKeys : [];
+      const newScope = traitNewScope(syntax, node, parent);
+      if (newScope) {
+        const scoped = { ...scopeBase, newScope, node, parent };
+        dispatch('onModulePreScopeCreated', scoped);
+        scopeControl.createScope(newScope);
+        dispatch('onModulePostScopeCreated', scoped);
+      }
+      return ignoreKeys;
+    },
+    exitNode(node, parent) {
+      const syntax = syntaxes[node.type];
+      const newScope = traitNewScope(syntax, node, parent);
+      if (newScope) {
+        const scoped = { ...scopeBase, scope: newScope, node, parent };
+        dispatch('onModulePreScopePopped', scoped);
+        scopeControl.popScope(newScope);
+        dispatch('onModulePostScopePopped', scoped);
+      }
+      dispatch('onExitNode', { ...nodeBase, node, parent });
+    },
+  };
+}
+
+/**
+ * Parse and score one module.
+ *
+ * Drop-in replacement for the displaced `escomplex.analyzeModule(source)`:
+ * same report object, same `finalize()` shape, same thrown errors for source
+ * the kernel cannot handle.
+ *
+ * @param {string} source JavaScript (or TypeScript) source text.
+ * @param {object} [options] Passed to the plugins' `onConfigure`, as before.
+ * @returns {object} The finalized module report.
+ * @throws {SyntaxError} Propagated from the parser, as before.
+ */
+export function analyzeModule(source, options = {}) {
+  const ast = babelParse(source, {
+    plugins: structuredClone(PARSER_PLUGINS),
+    sourceType: 'unambiguous',
+  });
+
+  const settings = dispatch('onConfigure', { options, settings: {} }).settings;
+  Object.freeze(settings);
+  const syntaxes = dispatch('onLoadSyntax', {
+    settings,
+    syntaxes: {},
+  }).syntaxes;
+
+  const moduleReport = new ModuleReport(
+    ast.loc.start.line,
+    ast.loc.end.line,
+    settings,
+  );
+  dispatch('onModuleStart', { ast, moduleReport, syntaxes, settings });
+
+  const scopeControl = new ModuleScopeControl(moduleReport);
+  new ASTWalker().traverse(
+    ast,
+    buildVisitor({ moduleReport, scopeControl, syntaxes, settings }),
+  );
+
+  for (const phase of [
+    'onModuleCalculate',
+    'onModuleAverage',
+    'onModulePostAverage',
+    'onModuleEnd',
+  ]) {
+    dispatch(phase, { moduleReport, syntaxes, settings });
+  }
+
+  return moduleReport.finalize();
+}

package/.agents/scripts/lib/maintainability-engine.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
-import escomplex from 'typhonjs-escomplex';
 import { install as installAstCompat } from './escomplex-ast-compat.js';
+import { analyzeModule } from './escomplex-kernel.js';
 import { transpileIfNeeded } from './transpile.js';
 
 /**
@@ -45,7 +45,7 @@ const UNSCORABLE = 0;
  */
 export function scoreSource(sourceCode) {
   try {
-    const score = escomplex.analyzeModule(sourceCode)?.maintainability;
+    const score = analyzeModule(sourceCode)?.maintainability;
     return Number.isFinite(score)
       ? { score, unscorable: false, reason: null }
       : unscorable(`kernel returned a non-finite index (${String(score)})`);
@@ -141,7 +141,7 @@ export function scoreFile(filePath) {
  */
 export function calculateReport(sourceCode) {
   try {
-    const result = escomplex.analyzeModule(sourceCode);
+    const result = analyzeModule(sourceCode);
     const methods = (result.methods ?? []).map((m) => ({
       name: m.name,
       maintainability:

package/.agents/scripts/lib/orchestration/code-review.js

@@ -42,6 +42,7 @@
 import { hasSurvivingCritical } from '../audit-suite/findings.js';
 import { resolveConfig } from '../config-resolver.js';
 import { computeChangeSet } from './change-set.js';
+import { remoteBaseRef } from './review-base-ref.js';
 import { deriveChangeLevel, resolveDepth } from './review-depth.js';
 import {
   collectProviderDegradations,
@@ -70,11 +71,14 @@ import { upsertStructuredComment } from './ticketing.js';
  */
 
 /**
- * Resolve the project base branch fallback used when a caller omits
- * `baseRef`.
+ * Resolve the base ref used when a caller omits `baseRef`. Remote-qualified,
+ * never the bare branch name — a caller that does not name a base must not
+ * silently inherit the local ref's drift (Story #5325). An unfetched remote
+ * then yields an unenumerable diff, which every downstream consumer already
+ * fails safe on, instead of a confidently-wrong wide one.
  */
 function resolveConfigBase(config) {
-  return config?.project?.baseBranch ?? 'main';
+  return remoteBaseRef(config?.project?.baseBranch ?? 'main');
 }
 
 /** Positive-integer override, else the supplied default. */

package/.agents/scripts/lib/orchestration/pinned-identifier-lint.js

@@ -0,0 +1,137 @@
+/**
+ * pinned-identifier-lint.js — the `pinned-identifier` advisory lint over a
+ * draft Story's `acceptance[]` (Story #5323).
+ *
+ * `acceptance[]` is the Story's **binding** contract and `changes[]` only an
+ * advisory sketch the deliverer may revise, so an acceptance item naming an
+ * internal symbol pins something the executor is free to rename out from
+ * under it. The story-author prompt has always said so; nothing surfaced a
+ * violation, which left the rule enforced only by the authoring model
+ * remembering it.
+ *
+ * The classifier lives in its own module because its vocabulary is its own:
+ * four token grammars and a call-suffix strip that the sibling prose lint in
+ * `plan-text-hygiene.js` shares nothing with.
+ *
+ * Advisory by contract: findings are deterministic text for the persist
+ * dry-run's warning list. They never gate persist and spawn nothing.
+ *
+ * Pure, synchronous, no I/O.
+ *
+ * @module lib/orchestration/pinned-identifier-lint
+ */
+
+/**
+ * An inline code span carrying one of these is naming something other than a
+ * source identifier, and is never a pinned identifier:
+ *
+ *   - `/` — a file path or a glob (`src/app.js`, `tests/x/*.spec.ts`);
+ *   - `.` — a dotted path, a filename, or a config key
+ *     (`delivery.routing.closeAndLand`, `story-body.js`);
+ *   - `:` — a label (`agent::ready`, `type::story`);
+ *   - `-` — a kebab token: a `data-testid` value, a slug, a package name, or
+ *     a CLI flag (`--dry-run`);
+ *   - whitespace — an argv shape, so a command (`npm run lint`);
+ *   - `[` / `]` — a field reference (`acceptance[]`).
+ */
+const NON_IDENTIFIER_MARKERS = /[/.:\-\s[\]]/;
+
+/** A bare source identifier, with an optional call suffix stripped. */
+const BARE_IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * An UPPER_SNAKE token. Exempt by contract: an environment variable and an
+ * internal constant are the same shape, and warning on every `DATABASE_URL`
+ * to catch the occasional pinned constant trades a real class of false
+ * positives for a marginal gain.
+ */
+const UPPER_SNAKE_RE = /^[A-Z0-9_$]+$/;
+
+/**
+ * A case transition (`staffCan`, `MyCalendarBoard`, `TimeGrid`) — the
+ * signature that separates a source identifier from a prose word a criterion
+ * legitimately quotes (`landed`, `pending`, `main`).
+ */
+const CASE_TRANSITION_RE = /[a-z][A-Z]/;
+
+/** The remedy, either side of the identifiers a finding names. */
+const MESSAGE_HEAD = 'Acceptance item pins the internal identifier(s) ';
+const MESSAGE_TAIL =
+  '; `changes[]` is an advisory sketch the deliverer may reshape, so assert ' +
+  'the observable behaviour instead of the symbol that implements it.';
+
+/**
+ * Collect the inline code spans of one acceptance item.
+ *
+ * @param {string} item
+ * @returns {string[]}
+ */
+function codeSpans(item) {
+  return [...String(item ?? '').matchAll(/`([^`\n]+)`/g)].map((m) => m[1]);
+}
+
+/**
+ * Decide whether one code span pins a source identifier: a bare token
+ * carrying a case transition, with no separator that would make it a path, a
+ * label, a kebab token, a flag or a command, and not an UPPER_SNAKE name.
+ *
+ * Deliberately conservative in one direction only: a false positive costs a
+ * warning line the author dismisses, while a false negative on a path, a
+ * testid or a command would train the author to ignore the lint.
+ *
+ * @param {string} span
+ * @returns {boolean}
+ */
+function isPinnedIdentifier(span) {
+  const token = span.trim().replace(/\(\s*\)$/, '');
+  return (
+    !NON_IDENTIFIER_MARKERS.test(token) &&
+    BARE_IDENTIFIER_RE.test(token) &&
+    !UPPER_SNAKE_RE.test(token) &&
+    CASE_TRANSITION_RE.test(token)
+  );
+}
+
+/**
+ * The authored `acceptance[]` of one draft Story.
+ *
+ * It is authored at the ticket's top level — the machine contract the
+ * validators read — and synced into the body only at assembly, so the top
+ * level wins; the parsed body covers a draft that carries it inline.
+ *
+ * @param {object} story The raw draft ticket.
+ * @param {object} body Its parsed body.
+ * @returns {string[]}
+ */
+function resolveAcceptance(story, body) {
+  if (Array.isArray(story?.acceptance)) return story.acceptance;
+  return Array.isArray(body?.acceptance) ? body.acceptance : [];
+}
+
+/**
+ * Evaluate the lint over one draft Story — one finding per offending
+ * acceptance item, naming every identifier it pinned.
+ *
+ * @param {object} story The raw draft ticket.
+ * @param {object} body Its parsed body.
+ * @param {string} slug
+ * @param {(text: string) => string} excerpt Evidence truncator, shared with
+ *   the sibling lints so every finding excerpts alike.
+ * @returns {Array<{ kind: 'pinned-identifier', slug: string, evidence: string, message: string }>}
+ */
+export function findPinnedIdentifiers(story, body, slug, excerpt) {
+  const acceptance = resolveAcceptance(story, body);
+  const findings = [];
+  for (const item of acceptance) {
+    const pinned = codeSpans(item).filter(isPinnedIdentifier);
+    if (pinned.length === 0) continue;
+    const named = pinned.map((name) => `\`${name}\``).join(', ');
+    findings.push({
+      kind: 'pinned-identifier',
+      slug,
+      evidence: excerpt(String(item ?? '')),
+      message: `${MESSAGE_HEAD}${named}${MESSAGE_TAIL}`,
+    });
+  }
+  return findings;
+}