declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/utils/genTempRepoWithDeclarationsOutside.ts

@@ -0,0 +1,53 @@
+import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { genTempDir } from 'test-fns';
+
+/**
+ * .what = a temp repo for a whole-usecase apply, whose declarations mirror is mounted in a SEPARATE
+ *         temp dir, and whose `declapract.use.yml` points there. returns the repo's physical path.
+ * .why  = an apply walks every path of the repo it applies to — `**` globs, dot dirs, and links
+ *         included. a declarations mirror mounted INSIDE the repo links back to this repo's real
+ *         practice trees, fixtures and all, so an unscoped apply writes a `**` fix through the link
+ *         into this repo's own source (tests-any's `__test_utils__/` → `.test.utils/` rewrite did,
+ *         into a tests-any fixture). mounted outside, the walk never reaches it.
+ * .note = declapract joins `declarations` onto the config's dir as a string, so the path written is
+ *         relative between the two PHYSICAL dirs, and callers must name the config by the returned
+ *         physical path (genTempDir hands back a link into /tmp).
+ */
+export const genTempRepoWithDeclarationsOutside = (input: {
+  slug: string;
+  clone: string;
+  declarations: string;
+  symlink: { at: string; to: string }[];
+}): string => {
+  // the repo to apply into, with no link into src/ for the declarations
+  const repo = realpathSync(
+    genTempDir({ slug: input.slug, clone: input.clone, symlink: input.symlink }),
+  );
+
+  // the declarations mirror, mounted beside the repo, never within it
+  const mount = realpathSync(
+    genTempDir({
+      slug: `${input.slug}-declarations`,
+      symlink: [{ at: 'declarations', to: input.declarations }],
+    }),
+  );
+
+  // point the repo's use.yml at the outside mount
+  const configPath = path.join(repo, 'declapract.use.yml');
+  const configBefore = readFileSync(configPath, 'utf-8');
+  if (!/^declarations:.*$/m.test(configBefore))
+    throw new Error(
+      `genTempRepoWithDeclarationsOutside: ${input.clone}/declapract.use.yml has no declarations line to repoint`,
+    );
+  const declarePath = path.relative(
+    repo,
+    path.join(mount, 'declarations', 'declapract.declare.yml'),
+  );
+  writeFileSync(
+    configPath,
+    configBefore.replace(/^declarations:.*$/m, `declarations: '${declarePath}'`),
+  );
+  return repo;
+};

package/dist/utils/genUnmigratedParamPathsDeclaration.declapract.integration.test.ts

@@ -0,0 +1,95 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import type { FileCheckContext } from 'declapract';
+import { genTempDir, getError, given, then, useBeforeAll, when } from 'test-fns';
+
+import {
+  genUnmigratedParamPathsDeclaration,
+  UNMIGRATED_PARAM_PATHS_MARKER,
+  UNMIGRATED_PARAM_PATHS_MARKER_KEY,
+} from './genUnmigratedParamPathsDeclaration';
+
+/**
+ * .what = proves the unmigrated-param-paths check flags each config of a repo whose configs hold
+ *         an explicit `$.at(aws::param/…)` path, and that its fix stamps the marker once (#544)
+ * .note = INTEGRATION by rule.forbid.unit.remote-boundaries: the check reads the peer configs off disk
+ */
+
+const { check, fix } = genUnmigratedParamPathsDeclaration();
+
+const EXPLICIT = JSON.stringify(
+  {
+    database: {
+      role: {
+        crud: { password: '$.at(aws::param/test-org/test-project/prep/crud)' },
+      },
+    },
+  },
+  null,
+  2,
+);
+const BARE = JSON.stringify(
+  { database: { role: { crud: { password: '$.at(aws::param)' } } } },
+  null,
+  2,
+);
+
+// each `as FileCheckContext` below is a documented cast: the context carries many fields this
+// declaration never reads; it reads only getProjectRootDirectory(). removal path: a declapract
+// partial-context builder.
+describe('genUnmigratedParamPathsDeclaration (#544)', () => {
+  given('[case1] a repo whose prep.json holds an explicit param path', () => {
+    const tempDir = genTempDir({ slug: 'unmigrated-param-paths-explicit' });
+    const context = useBeforeAll(async () => {
+      await fs.mkdir(path.join(tempDir, 'config'), { recursive: true });
+      await fs.writeFile(path.join(tempDir, 'config/prep.json'), EXPLICIT);
+      await fs.writeFile(path.join(tempDir, 'config/test.json'), BARE);
+      return {
+        value: { getProjectRootDirectory: () => tempDir } as FileCheckContext,
+      };
+    });
+
+    when('[t0] the check runs on prep and on test', () => {
+      then('both are flagged, so all three carry the marker together', async () => {
+        await check(EXPLICIT, context.value);
+        await check(BARE, context.value);
+      });
+    });
+
+    when('[t1] the fix runs, then runs again', () => {
+      then('the marker is stamped once, the explicit path kept, and the check passes', async () => {
+        const once = await fix(EXPLICIT, context.value);
+        const twice = await fix(once.contents!, context.value);
+        expect(twice.contents).toEqual(once.contents);
+        expect(JSON.parse(once.contents!)[UNMIGRATED_PARAM_PATHS_MARKER_KEY]).toEqual(
+          UNMIGRATED_PARAM_PATHS_MARKER,
+        );
+        expect(once.contents).toContain(
+          '$.at(aws::param/test-org/test-project/prep/crud)',
+        );
+        const error = await getError(() => check(once.contents!, context.value));
+        expect(error.message).toContain('already marked');
+        expect(once.contents).toMatchSnapshot();
+      });
+    });
+  });
+
+  given('[case2] a repo whose configs hold only bare placeholders', () => {
+    const tempDir = genTempDir({ slug: 'unmigrated-param-paths-bare' });
+    const context = useBeforeAll(async () => {
+      await fs.mkdir(path.join(tempDir, 'config'), { recursive: true });
+      await fs.writeFile(path.join(tempDir, 'config/prep.json'), BARE);
+      return {
+        value: { getProjectRootDirectory: () => tempDir } as FileCheckContext,
+      };
+    });
+
+    when('[t0] the check runs', () => {
+      then('the file is not flagged', async () => {
+        const error = await getError(() => check(BARE, context.value));
+        expect(error.message).toContain('no explicit param path');
+      });
+    });
+  });
+});

package/dist/utils/genUnmigratedParamPathsDeclaration.ts

@@ -0,0 +1,70 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { isJsonObject } from './asJsonMergedDeep';
+import { readFile } from './readFile';
+
+const EXPLICIT_PARAM_PREFIX = '$.at(aws::param/';
+export const UNMIGRATED_PARAM_PATHS_MARKER_KEY = '@declapract:review';
+export const UNMIGRATED_PARAM_PATHS_MARKER =
+  'explicit aws::param paths: copy each value to the derived name /{org}/{project}/{config}/{keyPath}, then swap the explicit path for the bare placeholder (declapract-typescript-ehmpathy#544, see provision/aws/readme.md)';
+
+const CONFIG_FILES = ['config/test.json', 'config/prep.json', 'config/prod.json'];
+
+/**
+ * .what = whether any of the repo's config/{test,prep,prod}.json holds an explicit param path
+ * .why  = all three carry the marker together, so config's divergent-config-shapes check never
+ *         sees one file with a key the others lack
+ */
+const isExplicitParamPathFoundInAnyConfig = async (input: {
+  root: string;
+}): Promise<boolean> => {
+  const found = await Promise.all(
+    CONFIG_FILES.map((file) =>
+      readFile({ filePath: `${input.root}/${file}` }).catch(
+        (error: NodeJS.ErrnoException) => {
+          if (error.code === 'ENOENT') return ''; // an absent config holds no path
+          throw error;
+        },
+      ),
+    ),
+  );
+  return found.some((contents) => contents.includes(EXPLICIT_PARAM_PREFIX));
+};
+
+/**
+ * .what = the declaration (check, fix) of the `unmigrated-param-paths` bad-practice, for one
+ *         config/{env}.json
+ * .why  = an explicit `$.at(aws::param/…)` path cannot auto-flip to the bare placeholder: the bare
+ *         form derives a param name that holds no value until someone copies it there. so the fix
+ *         stamps a top-level review key that names the copy step, and leaves every path as is.
+ *         zod's object schema strips the unknown key on parse, so getConfig is unaffected.
+ */
+export const genUnmigratedParamPathsDeclaration = (): {
+  check: FileCheckFunction;
+  fix: FileFixFunction;
+} => {
+  const check: FileCheckFunction = async (contents, context) => {
+    if (!contents) throw new Error('config file is absent');
+    const parsed: unknown = JSON.parse(contents);
+    if (isJsonObject(parsed) && UNMIGRATED_PARAM_PATHS_MARKER_KEY in parsed)
+      throw new Error('already marked');
+    const isFound = await isExplicitParamPathFoundInAnyConfig({
+      root: context.getProjectRootDirectory(),
+    });
+    if (isFound) return; // an explicit param path, unmarked → bad practice
+    throw new Error('no explicit param path');
+  };
+
+  const fix: FileFixFunction = (contents) => {
+    if (!contents) return {};
+    const parsed: unknown = JSON.parse(contents);
+    if (!isJsonObject(parsed)) return { contents };
+    const marked = {
+      [UNMIGRATED_PARAM_PATHS_MARKER_KEY]: UNMIGRATED_PARAM_PATHS_MARKER,
+      ...parsed,
+    };
+    return { contents: `${JSON.stringify(marked, null, 2)}\n` };
+  };
+
+  return { check, fix };
+};

package/dist/utils/getAllJsonDriftPaths.ts

@@ -0,0 +1,42 @@
+import { isJsonObject, type JsonLeafKeepRule } from './asJsonMergedDeep';
+
+/**
+ * .what = list the dotted paths where found json does not contain the declared json
+ * .why  = a check that names each drifted leaf tells the human what apply will change; an empty
+ *         list means the found json already holds every declared value. the same keep rule as
+ *         asJsonMergedDeep, so the check passes on exactly what the merge produces.
+ */
+export const getAllJsonDriftPaths = (input: {
+  declared: unknown;
+  found: unknown;
+  path: string[];
+  isLeafKept: JsonLeafKeepRule;
+}): string[] => {
+  // a declared object owes each of its keys, recursively
+  if (isJsonObject(input.declared)) {
+    if (!isJsonObject(input.found)) return [input.path.join('.')];
+    const declared = input.declared;
+    const found = input.found;
+    return Object.keys(declared).flatMap((key) =>
+      getAllJsonDriftPaths({
+        declared: declared[key],
+        found: found[key],
+        path: [...input.path, key],
+        isLeafKept: input.isLeafKept,
+      }),
+    );
+  }
+
+  // a leaf: equal, or kept by the rule
+  const isEqual =
+    JSON.stringify(input.declared) === JSON.stringify(input.found);
+  if (isEqual) return [];
+  const isKept =
+    input.found !== undefined &&
+    input.isLeafKept({
+      path: input.path,
+      declared: input.declared,
+      found: input.found,
+    });
+  return isKept ? [] : [input.path.join('.')];
+};

package/dist/utils/getAllStalePatchKeys.ts

@@ -0,0 +1,45 @@
+import { getAllVersionsByPackageFromLockfile } from './getAllVersionsByPackageFromLockfile';
+
+/**
+ * .what = cast a `pnpm.patchedDependencies` key (or a patch file name) into its package + version
+ * .why  = a key reads `name@version` (scoped: `@scope/name@version`); a patch file name encodes the
+ *         scope slash as `__` (`@scope__name@version.patch`). a bare `name` key patches every
+ *         version, so it has no pinned version
+ */
+export const asPatchTarget = (input: {
+  key: string;
+}): { name: string; version: string | null } => {
+  const at = input.key.lastIndexOf('@');
+  if (at <= 0) return { name: input.key, version: null };
+  return { name: input.key.slice(0, at), version: input.key.slice(at + 1) };
+};
+
+/**
+ * .what = whether a patch version is an exact semver (not a range)
+ * .why  = only an exact pin can go stale against the lockfile; a range patch keeps its own match
+ */
+const isExactVersion = (version: string): boolean =>
+  /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(version);
+
+/**
+ * .what = the `pnpm.patchedDependencies` keys whose pinned version no longer resolves (#680)
+ * .why  = a patch pins one exact version; once the lockfile resolves the package to another
+ *         version (or drops it), the patch applies to no install. such a patch is dead weight
+ *         that pnpm warns on (or, without `allowUnusedPatches`, refuses the install over)
+ * .note = no lockfile → no verdict (an empty list): the resolved graph is unknown, so no patch is
+ *         judged stale. a range key or a bare name key is never judged stale
+ */
+export const getAllStalePatchKeys = (input: {
+  patchedDependencies: Record<string, string>;
+  lockfile: string | null;
+}): string[] => {
+  if (input.lockfile === null) return [];
+  const versionsByName = getAllVersionsByPackageFromLockfile({
+    lockfile: input.lockfile,
+  });
+  return Object.keys(input.patchedDependencies).filter((key) => {
+    const target = asPatchTarget({ key });
+    if (target.version === null || !isExactVersion(target.version)) return false;
+    return !(versionsByName.get(target.name) ?? []).includes(target.version);
+  });
+};

package/dist/utils/getAllVersionsByPackageFromLockfile.ts

@@ -0,0 +1,71 @@
+/**
+ * .what = every resolved version of every package in a pnpm lockfile's graph
+ * .why  = one parse of the `packages:` keys serves two readers: the hoist flip notice (#610)
+ *         lists the names with two or more versions; the stale-patch bad practice (#680) asks
+ *         whether a patch's pinned version still resolves
+ * .note = pure: reads only the `packages:` keys. supports lockfile v9 (`name@ver:`),
+ *         v6 (`/name@ver(peer):`), and v5 (`/name/ver_peer:`)
+ */
+export const getAllVersionsByPackageFromLockfile = (input: {
+  lockfile: string;
+}): Map<string, string[]> => {
+  // collect the keys of the top-level `packages:` section
+  const lines = input.lockfile.split(/\r?\n/);
+  const start = lines.findIndex((line) => line === 'packages:');
+  if (start === -1) return new Map();
+  const after = lines.slice(start + 1);
+  const end = after.findIndex((line) => /^[^\s#]/.test(line));
+  const section = end === -1 ? after : after.slice(0, end);
+  const keys = section
+    .filter((line) => /^ {2}[^\s]/.test(line))
+    .map((line) => line.trim().replace(/:(\s.*)?$/, ''));
+
+  // map each key to its name + version
+  const pairs = keys
+    .map((key) => asLockfilePackageNameAndVersion({ key }))
+    .filter((pair): pair is { name: string; version: string } => pair !== null);
+
+  // group versions by name, sorted, deduped
+  const versionsByName = pairs.reduce<Map<string, Set<string>>>(
+    (acc, pair) =>
+      new Map(acc).set(
+        pair.name,
+        new Set([...(acc.get(pair.name) ?? []), pair.version]),
+      ),
+    new Map(),
+  );
+  return new Map(
+    [...versionsByName.entries()].map(([name, versions]) => [
+      name,
+      [...versions].sort((a, b) => a.localeCompare(b, 'en', { numeric: true })),
+    ]),
+  );
+};
+
+/**
+ * .what = cast one lockfile `packages:` key into its package name + version
+ * .why  = the key shape differs per lockfile version; one cast keeps the reader flat
+ */
+const asLockfilePackageNameAndVersion = (input: {
+  key: string;
+}): { name: string; version: string } | null => {
+  // strip quotes, the v5/v6 lead slash, and any peer suffix
+  const bare = input.key
+    .replace(/^['"]|['"]$/g, '')
+    .replace(/^\//, '')
+    .replace(/\(.*$/, '');
+
+  // v6 / v9: name@version (a scoped name starts with @, so look past index 0)
+  const at = bare.lastIndexOf('@');
+  if (at > 0) return { name: bare.slice(0, at), version: bare.slice(at + 1) };
+
+  // v5: name/version_peer
+  const slash = bare.lastIndexOf('/');
+  if (slash > 0)
+    return {
+      name: bare.slice(0, slash),
+      version: bare.slice(slash + 1).replace(/_.*$/, ''),
+    };
+
+  return null;
+};

package/dist/utils/getAllWorkflowJobDrifts.ts

@@ -0,0 +1,97 @@
+import { isDeepStrictEqual } from 'node:util';
+
+import { asWorkflowParts, isPlainMap, isTriggerHeld } from './asWorkflowParts';
+
+/**
+ * .what = every way the found `on` triggers depart from the declared ones
+ * .why  = `on` merges per trigger, so each declared trigger is read alone, and an undeclared
+ *         trigger is the repo's own
+ */
+const getTriggerDrift = (input: {
+  triggersFound: unknown;
+  triggersDeclared: unknown;
+}): string[] => {
+  // a declared `on` that is not a map is compared whole, with the other top-level keys
+  const triggersDeclared = input.triggersDeclared;
+  if (!isPlainMap(triggersDeclared)) return [];
+
+  // a found `on` that is not a map (e.g. `on: push`) cannot hold a declared trigger map
+  const triggersFound = input.triggersFound;
+  if (!isPlainMap(triggersFound))
+    return ["top-level key 'on' is not a map of triggers"];
+
+  // each declared trigger must be held
+  return Object.entries(triggersDeclared)
+    .filter(
+      ([name, value]) =>
+        !isTriggerHeld({ triggersFound, name, declared: value }),
+    )
+    .map(([name]) =>
+      name in triggersFound
+        ? `trigger '${name}' differs from its declared shape`
+        : `trigger '${name}' is absent`,
+    );
+};
+
+/**
+ * .what = every way a found workflow departs from a declared one, under the merge-by-job contract
+ * .why  = one source for both `check` and `fix`, so the gate and the repair cannot disagree.
+ *         the contract:
+ *         - each declared trigger under `on` must be held (see `isTriggerHeld`); a repo's own
+ *           triggers (a `schedule`, a dispatch with inputs) are never drift
+ *         - each other declared top-level key (other than `jobs`) must equal its declared value
+ *         - each declared job must exist and equal its declared shape
+ *         - an undeclared job is the repo's own, and is never drift — unless `dropJobWhen`
+ *           marks it obsolete (e.g. a job that still points at a dir a migration deleted)
+ * .note = equality is semantic (parsed data), so a comment or a quote style never counts as drift
+ */
+export const getAllWorkflowJobDrifts = (input: {
+  found: string;
+  declared: string;
+  dropJobWhen: ((input: { job: unknown }) => boolean) | null;
+}): string[] => {
+  const found = asWorkflowParts({ contents: input.found });
+  const declared = asWorkflowParts({ contents: input.declared });
+
+  // each declared top-level key must hold its declared value; `on` is read per trigger below
+  const triggersDeclared = declared.topLevel.on;
+  const isOnPerTrigger = isPlainMap(triggersDeclared);
+  const driftTopLevel = Object.keys(declared.topLevel)
+    .filter((key) => key !== 'jobs')
+    .filter((key) => !(key === 'on' && isOnPerTrigger))
+    .filter(
+      (key) => !isDeepStrictEqual(found.topLevel[key], declared.topLevel[key]),
+    )
+    .map((key) => `top-level key '${key}' differs from its declared value`);
+
+  // each declared trigger must be held; an undeclared trigger is the repo's own, never drift
+  const driftTriggers = getTriggerDrift({
+    triggersFound: found.topLevel.on,
+    triggersDeclared,
+  });
+
+  // each declared job must exist with its declared shape
+  const driftJobsDeclared = Object.keys(declared.jobs)
+    .filter((name) => !isDeepStrictEqual(found.jobs[name], declared.jobs[name]))
+    .map((name) =>
+      name in found.jobs
+        ? `job '${name}' differs from its declared shape`
+        : `job '${name}' is absent`,
+    );
+
+  // an undeclared job is kept, unless the declaration marks it obsolete
+  const dropJobWhen = input.dropJobWhen;
+  const driftJobsObsolete = dropJobWhen
+    ? Object.keys(found.jobs)
+        .filter((name) => !(name in declared.jobs))
+        .filter((name) => dropJobWhen({ job: found.jobs[name] }))
+        .map((name) => `job '${name}' is obsolete and must be dropped`)
+    : [];
+
+  return [
+    ...driftTopLevel,
+    ...driftTriggers,
+    ...driftJobsDeclared,
+    ...driftJobsObsolete,
+  ];
+};

package/dist/utils/getFileTextOrNull.integration.test.ts

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { genTempDir, given, then } from 'test-fns';
+
+import { getFileTextOrNull } from './getFileTextOrNull';
+
+describe('getFileTextOrNull', () => {
+  given('[case1] a root that holds the file', () => {
+    const root = genTempDir({ slug: 'get-file-text-or-null-found' });
+    fs.writeFileSync(path.join(root, 'pnpm-lock.yaml'), 'lockfileVersion: 9.0\n');
+
+    then('it returns the text of the file', () => {
+      expect(
+        getFileTextOrNull({ root, relativePath: 'pnpm-lock.yaml' }),
+      ).toEqual('lockfileVersion: 9.0\n');
+    });
+  });
+
+  given('[case2] a root that lacks the file', () => {
+    const root = genTempDir({ slug: 'get-file-text-or-null-absent' });
+
+    then('it returns null', () => {
+      expect(
+        getFileTextOrNull({ root, relativePath: 'pnpm-lock.yaml' }),
+      ).toBeNull();
+    });
+  });
+});

package/dist/utils/getFileTextOrNull.ts

@@ -0,0 +1,15 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * .what = the text of a file under a root, or null where the file is absent
+ * .why = several declarations read an optional neighbor file (the lockfile, the repo's own
+ *        package.json); one named read keeps that i/o boundary in one place
+ */
+export const getFileTextOrNull = (input: {
+  root: string;
+  relativePath: string;
+}): string | null => {
+  const filePath = path.join(input.root, input.relativePath);
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : null;
+};

package/dist/utils/getModuleExportsFromTsSource.ts

@@ -0,0 +1,34 @@
+import ts from 'typescript';
+
+/**
+ * .what = transpile a typescript source to commonjs and run it, with each require answered by a stub
+ * .why  = a test proves an emitted template's real branches by execution, with no install of the
+ *         template's own deps — the stub names exactly which modules the template may reach
+ * .note = test-only: it evaluates source via `new Function`, so it is never called on untrusted input
+ * .note = the caller's `requireStub` answers every require the module body makes. a stub that returns
+ *         `{}` for an id it does not know lets a member read off it fail at eval as a bare TypeError;
+ *         to name the gap instead, a stub throws on any id it does not answer
+ */
+export const getModuleExportsFromTsSource = <
+  TExports extends Record<string, unknown> = Record<string, unknown>,
+>(input: {
+  source: string;
+  requireStub: (id: string) => unknown;
+}): Partial<TExports> => {
+  // transpile to commonjs, so `exports` and `require` are the two seams the stub fills
+  const transpiled = ts.transpileModule(input.source, {
+    compilerOptions: {
+      module: ts.ModuleKind.CommonJS,
+      target: ts.ScriptTarget.ES2020,
+    },
+  }).outputText;
+
+  // run the module body against a fresh exports record
+  const moduleExports: Record<string, unknown> = {};
+  // eslint-disable-next-line no-new-func
+  new Function('exports', 'require', transpiled)(moduleExports, input.requireStub);
+
+  // a module evaluated at runtime carries no static types; the caller names the shape it expects,
+  // and every export is Partial so an absent one reads as undefined, never as present
+  return moduleExports as Partial<TExports>;
+};

package/dist/utils/getOneContentionSetFromLockfile.ts

@@ -0,0 +1,16 @@
+import { getAllVersionsByPackageFromLockfile } from './getAllVersionsByPackageFromLockfile';
+
+/**
+ * .what = the packages with more than one version in a pnpm lockfile's graph
+ * .why  = under `node-linker=hoisted` one copy of each package wins the root slot, so a
+ *         package with two versions becomes decisive rather than latent (#610). this set
+ *         names the candidates before the first red check, where the runtime symptom
+ *         (a crashed hook, a blank page) names none of them
+ */
+export const getOneContentionSetFromLockfile = (input: {
+  lockfile: string;
+}): { name: string; versions: string[] }[] =>
+  [...getAllVersionsByPackageFromLockfile(input).entries()]
+    .filter(([, versions]) => versions.length > 1)
+    .map(([name, versions]) => ({ name, versions }))
+    .sort((a, b) => a.name.localeCompare(b.name, 'en'));

package/dist/utils/getOneSourceScanEnd.ts

@@ -0,0 +1,100 @@
+/**
+ * .what = the index where a scan of typescript source stops, with strings and comments skipped:
+ *         - `close` mode: `from` sits on an opener (`(`, `[`, `{`); the index of its match
+ *         - `expression` mode: the index of the first `,` or `;` at depth 0, or of the closer
+ *           that would drop below depth 0 (the end of the outer list), else the source end
+ * .why  = a codemod that restructures a call or renames an identifier inside an arrow body must
+ *         know where that call or body ends. a regex cannot count brackets, and a bracket inside
+ *         a string or a comment must not count either.
+ * .note = deliberate mutation: a char-by-char scanner holds its cursor + depth as local state.
+ *         a functional fold was declined: a per-char recursion would overflow the stack on a large
+ *         file, and a reduce cannot jump the cursor past a string or comment it skips.
+ *         a template literal is skipped whole, `${…}` holes included (their brackets balance).
+ */
+export const getOneSourceScanEnd = (input: {
+  contents: string;
+  from: number;
+  mode: 'close' | 'expression';
+}): number => {
+  const { contents } = input;
+  let depth = 0;
+  let index = input.from;
+  while (index < contents.length) {
+    const char = contents[index]!;
+    const next = contents[index + 1];
+
+    // skip a line comment
+    if (char === '/' && next === '/') {
+      const newline = contents.indexOf('\n', index);
+      index = newline === -1 ? contents.length : newline;
+      continue;
+    }
+
+    // skip a block comment
+    if (char === '/' && next === '*') {
+      const close = contents.indexOf('*/', index + 2);
+      index = close === -1 ? contents.length : close + 2;
+      continue;
+    }
+
+    // skip a string literal, escapes honored
+    if (char === "'" || char === '"' || char === '`') {
+      index = getOneStringEnd({ contents, from: index }) + 1;
+      continue;
+    }
+
+    // descend into a bracket
+    if (char === '(' || char === '[' || char === '{') {
+      depth += 1;
+      index += 1;
+      continue;
+    }
+
+    // ascend out of a bracket
+    if (char === ')' || char === ']' || char === '}') {
+      depth -= 1;
+      if (input.mode === 'close' && depth === 0) return index;
+      if (input.mode === 'expression' && depth < 0) return index;
+      index += 1;
+      continue;
+    }
+
+    // a list separator at depth 0 ends an expression
+    if (
+      input.mode === 'expression' &&
+      depth === 0 &&
+      (char === ',' || char === ';')
+    )
+      return index;
+
+    index += 1;
+  }
+  return contents.length;
+};
+
+/**
+ * .what = the index of the quote that closes the string literal opened at `from`
+ * .why  = names the string skip, so the scanner above reads as one walk. a template literal's
+ *         `${…}` hole may itself hold a string or a backtick, so the hole is scanned in `close`
+ *         mode rather than searched for the next `}`.
+ */
+const getOneStringEnd = (input: { contents: string; from: number }): number => {
+  const { contents } = input;
+  const quote = contents[input.from]!;
+  let index = input.from + 1;
+  while (index < contents.length) {
+    const char = contents[index]!;
+    if (char === '\\') {
+      index += 2;
+      continue;
+    }
+    if (char === quote) return index;
+    if (quote === '`' && char === '$' && contents[index + 1] === '{') {
+      index =
+        getOneSourceScanEnd({ contents, from: index + 1, mode: 'close' }) + 1;
+      continue;
+    }
+    index += 1;
+  }
+  return contents.length;
+};