declapract-typescript-ehmpathy 0.49.13 → 0.49.15

package/dist/practices/persist-with-rds/provision-testdb-access.declapract.integration.test.ts

@@ -10,7 +10,7 @@ import { given, then, when } from 'test-fns';
  * .why  = each schema call invokes sql-schema-control → getConfig() → getEnvironment.static(); with
  *         no ACCESS in a local shell (no aws account alias / NODE_ENV that fits), every access parser
  *         fails and it throws `could not derive access`. the local testdb always provisions the
- *         `test` tier, so ACCESS=test is a constant here, not the cicd `${{ inputs.access }}`
+ *         `test` access, so ACCESS=test is a constant here, not the cicd `${{ inputs.access }}`
  *         interpolation the live-db path uses.
  * .teeth = drop an `ACCESS=test` from any inner schema call in best-practice/package.json and the
  *          "no bare schema call" assertion reddens (a bare `&& npm run provision:schema:` reappears).

package/dist/practices/persist-with-rds/ssm-param-names.declapract.integration.test.ts

@@ -0,0 +1,154 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+import { getModuleExportsFromTsSource } from '../../utils/getModuleExportsFromTsSource';
+
+/**
+ * .what = clamps that the provision wish declares each db credential at the exact ssm name that
+ *         config's bare `$.at(aws::param)` placeholder derives: `/{org}/{project}/{config}/{keyPath}`.
+ * .why  = sdk-config >= 0.3.0 derives a bare placeholder's ssm name as
+ *         `/${org}/${repo}/${choice}/${keyPath}`, where `choice` is the CONFIG slug. config/*.json
+ *         ships the bare form for all three passwords, so the wish must declare those same three
+ *         names, or the provision manages params the app never reads while the app reads params no
+ *         wish declares (#637). this supersedes the #591 clamp, which pinned the slash cicd form
+ *         with no config segment; the plan role's iam pin now allows the derived form (seed S4).
+ * .teeth = restore any dotted, config-segment-free, or access-keyed name in resources.parameters.ts,
+ *          or drop a bare placeholder from config/prep.json, and the names-equal-config case reddens.
+ *          read the config segment from `access` in place of `config` and the ACCESS=prep
+ *          CONFIG=prod case reddens.
+ * .note = INTEGRATION by rule.forbid.unit.remote-boundaries: it reads template files off disk. the
+ *         template imports declastruct-aws + sdk-environment, which this repo does not install, so
+ *         it is transpiled and run against a require stub — the clamp reads what the real source
+ *         returns, never a text fragment.
+ */
+
+const paramsPath = join(
+  __dirname,
+  'best-practice/provision/aws/resources.parameters.ts',
+);
+const configPath = (env: string) =>
+  join(__dirname, `best-practice/config/${env}.json`);
+
+const ORG = '@declapract{variable.organizationName}';
+const PROJECT = '@declapract{variable.projectName}';
+
+/**
+ * .what = transpile resources.parameters.ts and run getAllParameters under a stubbed environment
+ * .why  = the wish reads `getEnvironment.static()` at module load; a stub per (access, config) pair
+ *         proves which axis names the config segment and which tags it
+ */
+const runGetAllParameters = (input: {
+  src: string;
+  access: string;
+  config: string;
+}): { name: string; tags: Record<string, string> }[] => {
+  const requireStub = (id: string): unknown => {
+    if (id === 'declastruct-aws')
+      return { DeclaredAwsSsmParameterSecure: { as: (x: unknown) => x } };
+    if (id === 'sdk-environment')
+      return {
+        getEnvironment: {
+          static: () => ({ access: input.access, config: input.config }),
+        },
+      };
+    throw new Error(`unexpected require in template: ${id}`);
+  };
+  const { getAllParameters } = getModuleExportsFromTsSource<{
+    getAllParameters: (input: {
+      choice: string | null;
+    }) => { name: string; tags: Record<string, string> }[];
+  }>({ source: input.src, requireStub });
+  return getAllParameters!({ choice: null });
+};
+
+/**
+ * .what = list the dotted key paths whose value is the bare `$.at(aws::param)` placeholder
+ * .why  = each such leaf is a param sdk-config derives a name for, so the wish owes a declaration
+ */
+const getAllBareParamKeyPaths = (input: {
+  value: unknown;
+  prefix: string[];
+}): string[] => {
+  if (input.value === '$.at(aws::param)') return [input.prefix.join('.')];
+  if (!input.value || typeof input.value !== 'object') return [];
+  return Object.entries(input.value as Record<string, unknown>).flatMap(
+    ([key, child]) =>
+      getAllBareParamKeyPaths({ value: child, prefix: [...input.prefix, key] }),
+  );
+};
+
+describe('persist-with-rds ssm param names are the sdk-config derived names (#637)', () => {
+  const scene = useBeforeAll(() => ({
+    src: readFileSync(paramsPath, 'utf8'),
+    prep: JSON.parse(readFileSync(configPath('prep'), 'utf8')),
+    prod: JSON.parse(readFileSync(configPath('prod'), 'utf8')),
+  }));
+
+  given('[case1] the wish run with ACCESS=prep CONFIG=prep', () => {
+    when('[t0] getAllParameters is called with no choice override', () => {
+      const run = useBeforeAll(() => ({
+        params: runGetAllParameters({ src: scene.src, access: 'prep', config: 'prep' }),
+      }));
+
+      then('it declares the three derived names under /{org}/{project}/prep/', () => {
+        expect(run.params.map((p) => p.name)).toEqual([
+          `/${ORG}/${PROJECT}/prep/database.role.crud.password`,
+          `/${ORG}/${PROJECT}/prep/database.role.cicd.for-plan.password`,
+          `/${ORG}/${PROJECT}/prep/database.role.cicd.for-apply.password`,
+        ]);
+      });
+
+      then('the declared names equal the names config/prep.json derives', () => {
+        const derived = getAllBareParamKeyPaths({ value: scene.prep, prefix: [] })
+          .map((keyPath) => `/${ORG}/${PROJECT}/prep/${keyPath}`)
+          .sort();
+        expect(run.params.map((p) => p.name).sort()).toEqual(derived);
+      });
+
+      then('no name carries the legacy `dev` slug or a dotted org.project namespace', () => {
+        for (const { name } of run.params) {
+          expect(name).not.toContain('/dev/');
+          expect(name).not.toContain(`${ORG}.${PROJECT}`);
+        }
+      });
+
+      then('the declared names match snapshot', () => {
+        expect(run.params.map((p) => p.name)).toMatchSnapshot();
+      });
+    });
+  });
+
+  given('[case2] the wish run with ACCESS=prod CONFIG=prod', () => {
+    when('[t0] getAllParameters is called', () => {
+      then('the declared names equal the names config/prod.json derives', () => {
+        const params = runGetAllParameters({
+          src: scene.src,
+          access: 'prod',
+          config: 'prod',
+        });
+        const derived = getAllBareParamKeyPaths({ value: scene.prod, prefix: [] })
+          .map((keyPath) => `/${ORG}/${PROJECT}/prod/${keyPath}`)
+          .sort();
+        expect(params.map((p) => p.name).sort()).toEqual(derived);
+      });
+    });
+  });
+
+  given('[case3] the wish run with ACCESS=prep CONFIG=prod (a legal pair)', () => {
+    when('[t0] getAllParameters is called', () => {
+      const run = useBeforeAll(() => ({
+        params: runGetAllParameters({ src: scene.src, access: 'prep', config: 'prod' }),
+      }));
+
+      then('the config slug names the config segment, so the names read prod', () => {
+        expect(run.params).toHaveLength(3);
+        for (const { name } of run.params) expect(name).toContain(`/${PROJECT}/prod/`);
+      });
+
+      then('the access tags each param', () => {
+        for (const { tags } of run.params) expect(tags.environment).toEqual('prep');
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/testdb-per-worktree.declapract.integration.test.ts

@@ -0,0 +1,332 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import {
+  chmodSync,
+  copyFileSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+import { genTempDir, given, then, useBeforeAll } from 'test-fns';
+
+import { getTestdbIdentity } from './best-practice/src/.test/assets/database/getTestdbIdentity';
+import { getTestdbPort } from './best-practice/src/.test/assets/database/getTestdbPort';
+
+/**
+ * .what = proves each worktree of a repo gets a testdb of its own (#674): its own compose
+ *         project, container, and host port, while ci and a main checkout keep port 7821
+ * .why = two worktrees that share one testdb read and clobber each other's rows, and a
+ *        `start:testdb` in one stops the other's db mid-run
+ * .teeth = drop the worktree branch from getTestdbIdentity and case2 reddens; route a compose
+ *          command around compose.sh, or pin the compose port, and case5 reddens; read the port
+ *          straight off the config in a reader, or import a testdb test asset from a prod path,
+ *          and case5 reddens
+ * .note = getTestdbIdentity and getTestdbPort are test assets (`src/.test/assets/database/`): the
+ *         app never imports them, it reads the TESTDB_PORT the test harness declares
+ * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it runs git and bash in temp repos
+ */
+
+jest.setTimeout(5 * 60 * 1000);
+
+const BEST_PRACTICE_DIR = join(__dirname, 'best-practice');
+const REPO_NODE_MODULES = join(__dirname, '../../../node_modules');
+const PORT_DECLARED = 7821;
+const ENV_LOCAL = { ...process.env, CI: '' };
+
+/**
+ * .what = run git in a dir, with an author so a commit needs no global config
+ */
+const runGit = (input: { cwd: string; args: string[] }): string =>
+  execFileSync(
+    'git',
+    [
+      '-c',
+      'user.name=surfer',
+      '-c',
+      'user.email=surfer@example.com',
+      ...input.args,
+    ],
+    { cwd: input.cwd, encoding: 'utf8' },
+  );
+
+/**
+ * .what = a temp repo with one commit, plus two linked worktrees of it
+ */
+const genRepoWithWorktrees = (input: {
+  slug: string;
+  files: Record<string, string>;
+}): { main: string; worktreeA: string; worktreeB: string } => {
+  const root = genTempDir({ slug: input.slug });
+  const main = join(root, 'main');
+  mkdirSync(main, { recursive: true });
+  Object.entries(input.files).forEach(([path, source]) => {
+    mkdirSync(join(main, path, '..'), { recursive: true });
+    writeFileSync(join(main, path), source);
+  });
+  runGit({ cwd: main, args: ['init', '-q', '-b', 'main'] });
+  runGit({ cwd: main, args: ['add', '-A'] });
+  runGit({ cwd: main, args: ['commit', '-q', '--allow-empty', '-m', 'init'] });
+  const worktreeA = join(root, 'worktree-a');
+  const worktreeB = join(root, 'worktree-b');
+  runGit({ cwd: main, args: ['worktree', 'add', '-q', '-b', 'a', worktreeA] });
+  runGit({ cwd: main, args: ['worktree', 'add', '-q', '-b', 'b', worktreeB] });
+  return { main, worktreeA, worktreeB };
+};
+
+describe('persist-with-rds testdb per worktree (#674)', () => {
+  given('[case1] a main checkout', () => {
+    const repo = useBeforeAll(async () =>
+      genRepoWithWorktrees({ slug: 'testdb-per-worktree-main', files: {} }),
+    );
+
+    then('it keeps the declared port and no suffix, as before', () => {
+      expect(
+        getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.main, env: ENV_LOCAL },
+        ),
+      ).toEqual({ suffix: '', port: PORT_DECLARED });
+    });
+  });
+
+  given('[case2] two linked worktrees of one repo', () => {
+    const scene = useBeforeAll(async () => {
+      const repo = genRepoWithWorktrees({
+        slug: 'testdb-per-worktree-linked',
+        files: {},
+      });
+      return {
+        a: getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.worktreeA, env: ENV_LOCAL },
+        ),
+        aAgain: getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.worktreeA, env: ENV_LOCAL },
+        ),
+        b: getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.worktreeB, env: ENV_LOCAL },
+        ),
+      };
+    });
+
+    then('each derives a suffix of its own', () => {
+      expect(scene.a.suffix).toMatch(/^-[0-9a-f]{6}$/);
+      expect(scene.b.suffix).toMatch(/^-[0-9a-f]{6}$/);
+      expect(scene.a.suffix).not.toEqual(scene.b.suffix);
+    });
+
+    then('each binds a port of its own, never the declared one', () => {
+      [scene.a.port, scene.b.port].forEach((port) => {
+        expect(port).toBeGreaterThan(PORT_DECLARED);
+        expect(port).toBeLessThan(PORT_DECLARED + 1000);
+      });
+      expect(scene.a.port).not.toEqual(scene.b.port);
+    });
+
+    then('a worktree lands on the same identity every time', () => {
+      expect(scene.aAgain).toEqual(scene.a);
+    });
+  });
+
+  given('[case3] a linked worktree in ci', () => {
+    const repo = useBeforeAll(async () =>
+      genRepoWithWorktrees({ slug: 'testdb-per-worktree-ci', files: {} }),
+    );
+
+    then('it keeps the declared port, so ci behaves as before', () => {
+      expect(
+        getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.worktreeA, env: { ...process.env, CI: 'true' } },
+        ),
+      ).toEqual({ suffix: '', port: PORT_DECLARED });
+    });
+  });
+
+  given('[case4] a reader asks for its port', () => {
+    then('an access other than test keeps its declared port', () => {
+      expect(getTestdbPort({ access: 'prep', portDeclared: 5432 })).toEqual(
+        5432,
+      );
+    });
+
+    then('test access dials the identity this checkout derives', () => {
+      expect(
+        getTestdbPort({ access: 'test', portDeclared: PORT_DECLARED }),
+      ).toEqual(getTestdbIdentity({ portDeclared: PORT_DECLARED }).port);
+    });
+  });
+
+  given('[case5] the shipped templates', () => {
+    const read = (path: string) =>
+      readFileSync(join(BEST_PRACTICE_DIR, path), 'utf8');
+
+    then('the compose project, container, and port take the derived values', () => {
+      const compose = read('provision/docker/testdb/docker-compose.yml');
+      expect(compose).toContain(
+        'name: @declapract{variable.databaseName}${TESTDB_SUFFIX:-}',
+      );
+      expect(compose).toContain(
+        'container_name: @declapract{variable.databaseName}${TESTDB_SUFFIX:-}',
+      );
+      expect(compose).toContain('- ${TESTDB_PORT:-7821}:5432');
+      expect(compose).not.toContain('- 7821:5432');
+    });
+
+    then('every compose command goes through compose.sh', () => {
+      const commands: string[] = Object.values(
+        JSON.parse(read('package.json')).scripts,
+      );
+      expect(
+        commands.filter((command) => command.includes('docker compose')),
+      ).toEqual([]);
+      expect(
+        commands.filter((command) =>
+          command.includes('bash provision/docker/testdb/compose.sh'),
+        ).length,
+      ).toBeGreaterThanOrEqual(4);
+    });
+
+    then('the app dials the TESTDB_PORT override, never the test asset', () => {
+      const factory = read('src/utils/database/getOneDatabaseConnection.ts');
+      expect(factory).toContain('getOneDatabasePort({');
+      expect(factory).not.toContain('getTestdbPort');
+      expect(factory).not.toContain('.test/');
+    });
+
+    then('the schema provisioner dials getTestdbPort, from the test assets', () => {
+      const config = read('provision/schema/connection.config.js');
+      expect(config).toContain('getTestdbPort({');
+      expect(config).toContain(
+        "require('../../src/.test/assets/database/getTestdbPort')",
+      );
+    });
+
+    then('no prod path under src/ imports a testdb test asset', () => {
+      const prodImporters = readdirSync(join(BEST_PRACTICE_DIR, 'src/utils'), {
+        recursive: true,
+      })
+        .map((entry) => entry.toString())
+        .filter((path) => path.endsWith('.ts') && !path.endsWith('.test.ts'))
+        .filter((path) =>
+          /getTestdb(Port|Identity)|\.test\/assets/.test(
+            read(join('src/utils', path)),
+          ),
+        );
+      expect(prodImporters).toEqual([]);
+    });
+  });
+
+  given('[case6] compose.sh, run in a linked worktree', () => {
+    const scene = useBeforeAll(async () => {
+      const repo = genRepoWithWorktrees({
+        slug: 'testdb-per-worktree-compose',
+        files: {
+          'src/.test/assets/database/getTestdbIdentity.ts': readFileSync(
+            join(BEST_PRACTICE_DIR, 'src/.test/assets/database/getTestdbIdentity.ts'),
+            'utf8',
+          ),
+          'config/test.json': JSON.stringify({
+            database: { tunnel: { local: { host: 'localhost', port: 7821 } } },
+          }),
+          'provision/docker/testdb/docker-compose.yml': 'services: {}\n',
+        },
+      });
+      copyFileSync(
+        join(BEST_PRACTICE_DIR, 'provision/docker/testdb/compose.sh'),
+        join(repo.worktreeA, 'provision/docker/testdb/compose.sh'),
+      );
+      symlinkSync(REPO_NODE_MODULES, join(repo.worktreeA, 'node_modules'));
+
+      // a docker stand-in that reports what compose would have received
+      const bin = join(repo.worktreeA, '.bin');
+      mkdirSync(bin);
+      writeFileSync(
+        join(bin, 'docker'),
+        '#!/usr/bin/env bash\necho "suffix=$TESTDB_SUFFIX port=$TESTDB_PORT args=$*"\n',
+      );
+      chmodSync(join(bin, 'docker'), 0o755);
+
+      const result = spawnSync(
+        'bash',
+        ['provision/docker/testdb/compose.sh', 'up', '-d'],
+        {
+          cwd: repo.worktreeA,
+          encoding: 'utf8',
+          env: { ...ENV_LOCAL, PATH: `${bin}:${process.env.PATH}` },
+        },
+      );
+      const identity = getTestdbIdentity(
+        { portDeclared: PORT_DECLARED },
+        { cwd: repo.worktreeA, env: ENV_LOCAL },
+      );
+      return { result, identity, worktree: realpathSync(repo.worktreeA) };
+    });
+
+    then('it exits 0', () => {
+      expect(scene.result.stderr).toEqual('');
+      expect(scene.result.status).toEqual(0);
+    });
+
+    then('docker compose receives the worktree identity and the args', () => {
+      expect(scene.result.stdout.trim()).toEqual(
+        `suffix=${scene.identity.suffix} port=${scene.identity.port} args=compose -f ${scene.worktree}/provision/docker/testdb/docker-compose.yml up -d`,
+      );
+    });
+  });
+
+  given('[case7] compose.sh, where the identity util yields a malformed port', () => {
+    const scene = useBeforeAll(async () => {
+      const repo = genRepoWithWorktrees({
+        slug: 'testdb-per-worktree-compose-malformed',
+        files: {
+          'src/.test/assets/database/getTestdbIdentity.ts':
+            "export const getTestdbIdentity = (_input: { portDeclared: number }) => ({ suffix: '-abc123', port: Number.NaN });\n",
+          'config/test.json': JSON.stringify({
+            database: { tunnel: { local: { host: 'localhost', port: 7821 } } },
+          }),
+          'provision/docker/testdb/docker-compose.yml': 'services: {}\n',
+        },
+      });
+      copyFileSync(
+        join(BEST_PRACTICE_DIR, 'provision/docker/testdb/compose.sh'),
+        join(repo.worktreeA, 'provision/docker/testdb/compose.sh'),
+      );
+      symlinkSync(REPO_NODE_MODULES, join(repo.worktreeA, 'node_modules'));
+
+      // a docker stand-in that reports any call it receives
+      const bin = join(repo.worktreeA, '.bin');
+      mkdirSync(bin);
+      writeFileSync(join(bin, 'docker'), '#!/usr/bin/env bash\necho "docker called"\n');
+      chmodSync(join(bin, 'docker'), 0o755);
+
+      const result = spawnSync(
+        'bash',
+        ['provision/docker/testdb/compose.sh', 'up', '-d'],
+        {
+          cwd: repo.worktreeA,
+          encoding: 'utf8',
+          env: { ...ENV_LOCAL, PATH: `${bin}:${process.env.PATH}` },
+        },
+      );
+      return { result };
+    });
+
+    then('it halts with exit 1 and names the malformed identity', () => {
+      expect(scene.result.status).toEqual(1);
+      expect(scene.result.stderr).toContain(
+        "💥 MalfunctionError: getTestdbIdentity yielded '-abc123 NaN'",
+      );
+    });
+
+    then('docker compose is never called', () => {
+      expect(scene.result.stdout).not.toContain('docker called');
+    });
+  });
+});

package/dist/practices/persist-with-rds/with-connection-in-input.declapract.integration.test.ts

@@ -0,0 +1,97 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+// executeApply is slow (full practice evaluation), so grant a generous limit
+jest.setTimeout(180_000);
+
+/**
+ * .what = end-to-end proof of the with-connection-in-input fix on a real repo (#626).
+ * .why  = the prior declaration was an EXISTS check with no fix, so an apply could not repair it and
+ *   named no replacement. the src declaration now stamps the input→context review line above each
+ *   import and definition of withDatabaseConnection, and never deletes the wrapper its callers need.
+ * .note = the declarations isolate this one bad-practice (a persist-with-rds practice that holds only
+ *   it), so the test owes none of the practice's variables.
+ */
+describe('persist-with-rds with-connection-in-input', () => {
+  given('[case1] a repo whose op imports withDatabaseConnection', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-rds-connection-in-input',
+      clone:
+        './src/practices/persist-with-rds/bad-practices/with-connection-in-input/.test/assets/demo-repo-with-connection-in-input',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/persist-with-rds-connection-in-input/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const opPath = 'src/domain.operations/findSurferById.ts';
+    const wrapperPath = 'src/utils/database/withDatabaseConnection.ts';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyOne = (input: { file: string }) =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'persist-with-rds',
+        file: input.file,
+      });
+    const applyFix = async () => {
+      await applyOne({ file: opPath });
+      await applyOne({ file: wrapperPath });
+    };
+
+    when('[t0] the input (before any fix)', () => {
+      then('both src files match snapshot', async () => {
+        expect(await read(opPath)).toMatchSnapshot('op — before');
+        expect(await read(wrapperPath)).toMatchSnapshot('wrapper — before');
+      });
+    });
+
+    when('[t1] the fix is applied', () => {
+      const after = useThen('apply', async () => {
+        const before = { op: await read(opPath), wrapper: await read(wrapperPath) };
+        await applyFix();
+        return { before, op: await read(opPath), wrapper: await read(wrapperPath) };
+      });
+
+      then('the op gains one review line above its import, which names withDatabaseContext', () => {
+        const markers = after.op
+          .split('\n')
+          .filter((line) => line.includes('@declapract:review:'));
+        expect(markers).toHaveLength(1);
+        expect(markers[0]).toContain('withDatabaseContext');
+        expect(markers[0]).toContain('(input, context)');
+        expect(after.op.replace(/^.*@declapract:review.*\n/m, '')).toEqual(
+          after.before.op,
+        );
+        expect(after.op).toMatchSnapshot('op — after');
+      });
+
+      then('the wrapper stays in place, marked, so the tree still builds', () => {
+        expect(after.wrapper).toContain('export const withDatabaseConnection');
+        expect(after.wrapper.replace(/^.*@declapract:review.*\n/m, '')).toEqual(
+          after.before.wrapper,
+        );
+        expect(after.wrapper).toMatchSnapshot('wrapper — after');
+      });
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      const passes = useThen('a second apply over its own output', async () => {
+        const before = { op: await read(opPath), wrapper: await read(wrapperPath) };
+        await applyFix();
+        const after = { op: await read(opPath), wrapper: await read(wrapperPath) };
+        return { before, after };
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/practices/pnpm/.test/assets/repo-stale-patch/declapract.use.yml

@@ -0,0 +1,4 @@
+# .note = declarations dir is symlinked by the test to src/.test/assets/pnpm/declarations
+# .why  = a repo with one patch the lockfile moved past and one it still resolves (#680)
+declarations: 'declarations/declapract.declare.yml'
+useCase: pnpm-repo

package/dist/practices/pnpm/.test/assets/repo-stale-patch/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "repo-stale-patch",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.34.5",
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "rhachet-roles-ehmpathy@1.39.1": "patches/rhachet-roles-ehmpathy@1.39.1.patch",
+      "type-fns@1.21.3": "patches/type-fns@1.21.3.patch"
+    }
+  }
+}

package/dist/practices/pnpm/.test/assets/repo-stale-patch/patches/rhachet-roles-ehmpathy@1.39.1.patch

@@ -0,0 +1,6 @@
+diff --git a/dist/index.js b/dist/index.js
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -1 +1 @@
+-module.exports = {};
++module.exports = { patched: true };

package/dist/practices/pnpm/.test/assets/repo-stale-patch/patches/type-fns@1.21.3.patch

@@ -0,0 +1,6 @@
+diff --git a/dist/index.js b/dist/index.js
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -1 +1 @@
+-module.exports = {};
++module.exports = { patched: true };

package/dist/practices/pnpm/.test/assets/repo-stale-patch/pnpm-lock.yaml

@@ -0,0 +1,19 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+packages:
+
+  rhachet-roles-ehmpathy@1.40.0:
+    resolution: {integrity: sha512-a}
+
+  type-fns@1.21.3:
+    resolution: {integrity: sha512-b}
+
+snapshots:
+
+  rhachet-roles-ehmpathy@1.40.0: {}
+
+  type-fns@1.21.3: {}

package/dist/practices/pnpm/.test/assets/repo-stale-patch-beside-bare/declapract.use.yml

@@ -0,0 +1,4 @@
+# .note = declarations dir is symlinked by the test to src/.test/assets/pnpm/declarations
+# .why  = a repo with one patch the lockfile moved past and one it still resolves (#680)
+declarations: 'declarations/declapract.declare.yml'
+useCase: pnpm-repo

package/dist/practices/pnpm/.test/assets/repo-stale-patch-beside-bare/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "repo-stale-patch-beside-bare",
+  "version": "1.0.0",
+  "packageManager": "pnpm@10.34.5",
+  "pnpm": {
+    "overrides": {
+      "react-refresh": "0.14.2"
+    },
+    "patchedDependencies": {
+      "rhachet-roles-ehmpathy": "patches/rhachet-roles-ehmpathy.patch",
+      "rhachet-roles-ehmpathy@1.39.1": "patches/rhachet-roles-ehmpathy@1.39.1.patch",
+      "type-fns@1.21.3": "patches/type-fns@1.21.3.patch"
+    }
+  }
+}

package/dist/practices/pnpm/.test/assets/repo-stale-patch-beside-bare/patches/rhachet-roles-ehmpathy.patch

@@ -0,0 +1,6 @@
+diff --git a/dist/index.js b/dist/index.js
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -1 +1 @@
+-module.exports = {};
++module.exports = { patched: true };