declapract-typescript-ehmpathy 0.49.13 → 0.49.15

package/dist/typecheckBestPracticeTemplates.declapract.integration.test.ts

@@ -0,0 +1,584 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { executeApply, executePlan } from 'declapract';
+import { ConstraintError, MalfunctionError } from 'helpful-errors';
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+
+import { asPackageJSON } from './utils/asPackageJSON';
+
+/**
+ * .what = the pnpm this repo pins in its own `packageManager`, run via npx
+ * .why  = a ci test job restores node_modules from cache and puts no pnpm on its PATH, so a bare
+ *         `pnpm` spawn fails ENOENT. npx fetches the pinned version, so the run needs no host pnpm
+ * .note = `--loglevel=error` sits before the package spec, so it quiets npx's own npm and reaches
+ *         neither pnpm nor tsc: npx reads the emitted `.npmrc`, and a newer host npm warns on each
+ *         pnpm-only key in it (`node-linker`, `public-hoist-pattern`), which says naught of the
+ *         templates and would vary each snapshot with the host's npm
+ */
+const PNPM_VIA_NPX = (() => {
+  const packageManager: string = asPackageJSON(
+    {
+      contents: readFileSync(
+        path.join(__dirname, '..', 'package.json'),
+        'utf-8',
+      ),
+    },
+    { practice: 'typecheck-best-practice-templates' },
+  ).packageManager;
+  return {
+    command: 'npx',
+    argsBefore: ['--yes', '--loglevel=error', packageManager],
+  };
+})();
+
+/**
+ * .what = clamps that every `.ts` template a usecase ships type-checks, as an adopter compiles it:
+ *         apply the whole usecase into a bare repo, install the emitted deps, then `tsc --noEmit`
+ *         with the emitted tsconfig.
+ * .why  = this repo's own tsconfig includes only `src/**\/*.declapract.ts`, so the templates under
+ *         `best-practice/` are never type-checked here. a template that fails the strictest
+ *         tsconfig the practices themselves ship reaches every adopter at once (#632 `cause: error`
+ *         on an `unknown` catch var, #633 a doc example that does not compile) — found by adopters,
+ *         never by this repo. only an APPLIED usecase is the tree an adopter compiles: templates
+ *         import peer practices' files, and each usecase pins its own dep floors (F88).
+ * .teeth = restore `cause: error` (an `unknown` catch var) into
+ *          `tests-node/best-practice/src/.test/useKeyrack.ts` — every node usecase reddens with
+ *          the TS2322 diagnostic in its failure message and snapshot.
+ * .note = `typescript-project-core` is excluded: it is a base that every consumer extends, and it
+ *         emits no tsconfig of its own (typescript-node / typescript-expo own the tsconfig), so a
+ *         lone core apply has no compile shape to check. every consumer below covers its files.
+ * .note = the temp repo lives at /tmp (genTempDir isolates it from this repo's node_modules), so
+ *         the install and the compile see only the deps the usecase emits. the pnpm store is
+ *         global, so the usecases share cached tarballs (`--prefer-offline`).
+ * .note = a whole-usecase apply costs minutes, so every usecase is prepared in parallel inside one
+ *         `useBeforeAll`; each `given` then reads its own result.
+ * .what = also clamps that a usecase converges: after a second apply, a plan flags no file for an
+ *         automatic fix, and flags no file the apply itself wrote. a practice whose check rejects a
+ *         peer's shipped template (a lockfile hook two practices fight over, an `s3://` uri read as
+ *         the retired `s3:` key, an import that must leave src/, a null config leaf) flags every
+ *         adopter forever, with no fix a human could make.
+ * .teeth = restore `/\bs3\s*:/` as the s3 key pattern in `cache/bad-practices/cache-directory-options`
+ *          — the config template `src/utils/config/getOneCacheDirectory.ts` is flagged in each
+ *          usecase that ships it.
+ * .what = also runs each usecase's emitted cycle check (`test:lint:cycles`) on the installed tree,
+ *         and clamps that no cycle runs through pg-pool. dpdm walks node_modules (`exclude: []`),
+ *         so a cycle in a shipped prod dep reddens every adopter's lint gate at once. every other
+ *         cycle it finds is held in a snapshot, so a new one shows in review.
+ * .teeth = drop the `pg-pool` key from `persist-with-rds/best-practice/package.json`
+ *          `pnpm.patchedDependencies` — `lambda-service-with-rds` reports `pg -> pg-pool`.
+ * .note = the test lives at `src/` (not under `src/.test/`): jest skips dot dirs, so a test there
+ *         would never run.
+ */
+
+const USECASES = [
+  'typescript-project',
+  'npm-package',
+  'rhachet-roles-package',
+  'lambda-service',
+  'lambda-service-with-rds',
+  'lambda-service-with-dynamodb',
+  'app-react-native-expo',
+] as const;
+type Usecase = (typeof USECASES)[number];
+
+// the usecases whose install holds pg-pool; `[t3]` checks this set against each real install, so
+// a usecase that gains pg reddens until it joins, and its pg-pool verdict is never vacuous
+const USECASES_WITH_PG_POOL: readonly Usecase[] = ['lambda-service-with-rds'];
+
+// every `@declapract{variable.*}` any practice in any usecase references
+const VARIABLES_YML = `
+variables:
+  projectName: typecheck-demo
+  organizationName: test-org
+  infrastructureNamespaceId: testns
+  databaseName: testdb
+  databaseUserName:
+    cicdUser: testdb_cicd
+    serviceUser: testdb_service
+  databaseTunnelHost:
+    prep: tunnel.prep.test.dev
+    prod: tunnel.prod.test.dev
+  databaseClusterHost:
+    prep: cluster.prep.test.dev
+    prod: cluster.prod.test.dev
+  slackWebhookUrl: 'https://hooks.slack.test/webhook'
+  awsAccountId:
+    prep: '111111111111'
+    prod: '222222222222'
+  app:
+    web:
+      domain:
+        prep: demo.prep.test.dev
+        prod: demo.test.dev
+      port:
+        hot: 3547
+        cold: 3549
+`;
+
+/**
+ * .what = runs a command in the temp repo and captures its exit code + combined output
+ * .why  = the install and compile are real processes; their output is the diagnosis.
+ *         async, so the usecases install and compile in parallel
+ */
+const runInRepo = (input: {
+  cwd: string;
+  command: string;
+  args: string[];
+}): Promise<{ status: number | null; output: string }> =>
+  new Promise((done, fail) => {
+    const child = spawn(input.command, input.args, {
+      cwd: input.cwd,
+      env: { ...process.env, CI: 'true', FORCE_COLOR: '0' },
+      // a stalled registry kills the child (status null) instead of a silent park of the run
+      timeout: 900_000,
+    });
+    const chunks: string[] = [];
+    child.stdout.on('data', (chunk) => chunks.push(String(chunk)));
+    child.stderr.on('data', (chunk) => chunks.push(String(chunk)));
+    child.on('error', fail);
+    child.on('close', (status) =>
+      done({ status, output: chunks.join('').trim() }),
+    );
+  });
+
+/**
+ * .what = pins each `@declapract{check.minVersion('x')}` dep in an emitted package.json to its floor `x`
+ * .why  = a dep absent from the repo is emitted with the check expression verbatim; an adopter
+ *         would install the floor version, so the compile runs against the floor the practice pins
+ */
+const asPackageJsonAtFloorVersions = (input: { contents: string }): string =>
+  input.contents.replace(
+    /@declapract\{check\.minVersion\('([^']+)'\)\}/g,
+    (_match, version: string) => version,
+  );
+
+/**
+ * .what = masks the temp dir paths out of an output, so a snapshot is stable across runs
+ */
+const asMaskedOutput = (input: { output: string; dirs: string[] }): string =>
+  input.dirs.reduce(
+    (masked, dir) => masked.split(dir).join('<tempdir>'),
+    input.output,
+  );
+
+/**
+ * .what = the package each segment of one dpdm cycle line sits in, joined in cycle order
+ * .why  = a raw cycle line names pnpm store dirs whose suffix hashes shift with every peer set;
+ *         the packages alone are the stable fact a snapshot can hold
+ */
+const asCyclePackages = (input: { line: string }): string =>
+  input.line
+    .split(' -> ')
+    .map((segment) => {
+      const afterStore = segment.trim().split('node_modules/').pop() ?? '';
+      const match = afterStore.match(/^((?:@[^/]+\/)?[^/]+)/);
+      return match?.[1] ?? segment.trim();
+    })
+    .join(' -> ');
+
+/**
+ * .what = the verdict of one `test:lint:cycles` run: whether dpdm analyzed a tree, and each
+ *         cycle it found, as package chains
+ * .why  = a bare repo of a usecase that emits no `src/**\/*.ts` gives dpdm no entry file, which it
+ *         reports as a failure; that is not a cycle, so the summary keeps the two apart
+ */
+const asCycleSummary = (input: {
+  output: string;
+}): { analyzed: boolean; cycles: string[] } => ({
+  analyzed: input.output.includes('Analyze done!'),
+  cycles: input.output
+    .split('\n')
+    .map((line) => line.match(/^\s*\d+\)\s+(.+)$/)?.[1])
+    .filter((line): line is string => line !== undefined)
+    .map((line) => asCyclePackages({ line }))
+    .sort(), // dpdm reports cycles in traversal order, which shifts between runs
+});
+
+/**
+ * .what = applies one usecase into its temp repo, installs the emitted deps, and compiles
+ * .why  = the three steps an adopter takes before their first `tsc`
+ */
+const genTypecheckResult = async (input: {
+  usecase: Usecase;
+  tempDir: string;
+  declarationsDir: string;
+}): Promise<{
+  config: string;
+  tsconfigFound: boolean;
+  holdsPgPool: boolean;
+  srcImportsPg: boolean;
+  install: { status: number | null; output: string };
+  compile: { status: number | null; output: string };
+  cycles: { status: number | null; output: string };
+}> => {
+  // declare the usecase this repo adopts, from declarations that live outside the repo
+  // .note = declapract joins `declarations` onto the config's dir, so the path is relative, and both
+  //         ends are physical paths (genTempDir hands back a link into /tmp)
+  const repoDir = realpathSync(input.tempDir);
+  const config = path.join(repoDir, 'declapract.use.yml');
+  const declarationsPath = path.relative(
+    repoDir,
+    path.join(realpathSync(input.declarationsDir), 'declapract.declare.yml'),
+  );
+  await fs.writeFile(
+    config,
+    [
+      `declarations: '${declarationsPath}'`,
+      `useCase: ${input.usecase}`,
+      VARIABLES_YML,
+    ].join('\n'),
+  );
+
+  // apply the whole usecase; the repo holds no link into src/, so no fix can write through one
+  const startedAt = Date.now();
+  await executeApply({ config });
+  const appliedAt = Date.now();
+
+  // pin each emitted dep to the floor version its practice declares
+  const cwd = realpathSync(input.tempDir);
+  const packageJsonPath = path.join(cwd, 'package.json');
+  await fs.writeFile(
+    packageJsonPath,
+    asPackageJsonAtFloorVersions({
+      contents: await fs.readFile(packageJsonPath, 'utf-8'),
+    }),
+  );
+
+  // apply again, as an adopter's next upgrade would; the plan after it must show convergence
+  await executeApply({ config });
+
+  // install the emitted deps, at the physical path (outside this repo's tree)
+  const install = await runInRepo({
+    cwd,
+    command: PNPM_VIA_NPX.command,
+    args: [
+      ...PNPM_VIA_NPX.argsBefore,
+      'install',
+      '--no-frozen-lockfile',
+      '--ignore-scripts',
+      '--prefer-offline',
+    ],
+  });
+  const installedAt = Date.now();
+
+  // compile with the emitted tsconfig
+  const tsconfigFound = existsSync(path.join(cwd, 'tsconfig.json'));
+  const compile = await runInRepo({
+    cwd,
+    command: PNPM_VIA_NPX.command,
+    args: [
+      ...PNPM_VIA_NPX.argsBefore,
+      'exec',
+      'tsc',
+      '--noEmit',
+      '--pretty',
+      'false',
+      '-p',
+      'tsconfig.json',
+    ],
+  });
+
+  const compiledAt = Date.now();
+
+  // run the emitted cycle check, as the adopter's `npm run test:lint` does
+  const cycles = await runInRepo({
+    cwd,
+    command: PNPM_VIA_NPX.command,
+    args: [...PNPM_VIA_NPX.argsBefore, 'run', 'test:lint:cycles'],
+  });
+
+  // report the per-phase cost, so a slow usecase is visible in the run log
+  console.log(`typecheck-templates ${input.usecase} phase cost`, {
+    applyMs: appliedAt - startedAt,
+    installMs: installedAt - appliedAt,
+    compileMs: compiledAt - installedAt,
+    cyclesMs: Date.now() - compiledAt,
+  });
+
+  // whether the install holds pg-pool at all; pnpm keeps a transitive dep only in its store
+  const pnpmStore = path.join(cwd, 'node_modules', '.pnpm');
+  const holdsPgPool =
+    existsSync(pnpmStore) &&
+    (await fs.readdir(pnpmStore)).some((name) => name.startsWith('pg-pool@'));
+
+  // whether any emitted src file imports pg; without one, dpdm never reaches pg-pool
+  const srcDir = path.join(cwd, 'src');
+  const srcFiles = existsSync(srcDir)
+    ? (await fs.readdir(srcDir, { recursive: true }))
+        .map(String)
+        .filter((file) => file.endsWith('.ts'))
+    : [];
+  const srcImportsPg = (
+    await Promise.all(
+      srcFiles.map((file) => fs.readFile(path.join(srcDir, file), 'utf-8')),
+    )
+  ).some((contents) => /from 'pg'/.test(contents));
+
+  const dirs = [cwd, input.tempDir];
+  return {
+    config,
+    tsconfigFound,
+    holdsPgPool,
+    srcImportsPg,
+    install: {
+      status: install.status,
+      output: asMaskedOutput({ output: install.output, dirs }),
+    },
+    compile: {
+      status: compile.status,
+      output: asMaskedOutput({ output: compile.output, dirs }),
+    },
+    cycles: {
+      status: cycles.status,
+      output: asMaskedOutput({ output: cycles.output, dirs }),
+    },
+  };
+};
+
+/**
+ * .what = plans one applied repo, and returns each file the plan still flags, by fix kind
+ * .why  = `executePlan` prints its result and returns naught, so the printed plan is the contract.
+ *         the spy passes each line through to the real console, so the run log keeps the plan
+ * .note = plans run one at a time: the spy reads the one shared console
+ */
+const getPlanFlags = async (input: {
+  config: string;
+}): Promise<{ automatic: string[]; manual: string[] }> => {
+  const lines: string[] = [];
+  const logOriginal = console.log;
+  const spy = jest.spyOn(console, 'log').mockImplementation((...args) => {
+    lines.push(args.map(String).join(' '));
+    logOriginal(...args);
+  });
+  try {
+    await executePlan({ config: input.config });
+  } finally {
+    spy.mockRestore();
+  }
+  const flags = lines
+    .join('\n')
+    .replace(/\x1b\[[0-9;]*m/g, '') // eslint-disable-line no-control-regex
+    .split('\n')
+    .map((line) => line.match(/^\s*\* \[(FIX_AUTOMATIC|FIX_MANUAL)\] (.+?)\s*$/))
+    .filter((match): match is RegExpMatchArray => match !== null);
+  return {
+    automatic: flags.filter((m) => m[1] === 'FIX_AUTOMATIC').map((m) => m[2]!),
+    manual: flags.filter((m) => m[1] === 'FIX_MANUAL').map((m) => m[2]!),
+  };
+};
+
+// apply + install + compile per usecase runs minutes, not seconds; useBeforeAll takes no timeout
+jest.setTimeout(3_600_000);
+
+describe('typecheck best-practice templates', () => {
+  // one temp repo per usecase, plus one declarations dir per usecase that mounts the real practices
+  // + usecases. the declarations dir is a SEPARATE temp dir: the repo holds no link into src/, so
+  // the whole-usecase apply cannot write through one into this repo's own source
+  const tempDirs = Object.fromEntries(
+    USECASES.map((usecase) => [
+      usecase,
+      {
+        repo: genTempDir({
+          slug: `typecheck-templates-${usecase}`,
+          clone: './src/.test/assets/typecheck-templates/repo-bare',
+        }),
+        declarations: genTempDir({
+          slug: `typecheck-templates-${usecase}-declarations`,
+          clone: './src/.test/assets/typecheck-templates/declarations',
+          symlink: [
+            { at: 'practices', to: 'src/practices' },
+            { at: 'useCases.yml', to: 'src/useCases.yml' },
+          ],
+        }),
+      },
+    ]),
+  ) as Record<Usecase, { repo: string; declarations: string }>;
+
+  // prepare every usecase in parallel; settle each alone, so one usecase's failure stays its own
+  const settled = useBeforeAll(async () => {
+    const results = await Promise.allSettled(
+      USECASES.map((usecase) =>
+        genTypecheckResult({
+          usecase,
+          tempDir: tempDirs[usecase].repo,
+          declarationsDir: tempDirs[usecase].declarations,
+        }),
+      ),
+    );
+    return Object.fromEntries(
+      USECASES.map((usecase, index) => [usecase, results[index]!]),
+    ) as Record<
+      Usecase,
+      PromiseSettledResult<Awaited<ReturnType<typeof genTypecheckResult>>>
+    >;
+  });
+
+  // read one usecase's result; a usecase whose preparation threw fails each of its thens loud
+  const getScene = (input: { usecase: Usecase }) => {
+    const result = settled[input.usecase];
+    if (result.status === 'rejected') throw result.reason;
+    return result.value;
+  };
+
+  // plan each prepared usecase, one at a time (see getPlanFlags); a plan that throws stays its own
+  const plans = useBeforeAll(async () => {
+    const results: Partial<
+      Record<
+        Usecase,
+        PromiseSettledResult<Awaited<ReturnType<typeof getPlanFlags>>>
+      >
+    > = {};
+    for (const usecase of USECASES) {
+      const prepared = settled[usecase];
+      if (prepared.status === 'rejected') {
+        results[usecase] = prepared;
+        continue;
+      }
+      const [planned] = await Promise.allSettled([
+        getPlanFlags({ config: prepared.value.config }),
+      ]);
+      results[usecase] = planned!;
+    }
+    return results as Record<
+      Usecase,
+      PromiseSettledResult<Awaited<ReturnType<typeof getPlanFlags>>>
+    >;
+  });
+
+  // read one usecase's plan flags; a plan that threw fails each of its thens loud
+  const getPlan = (input: { usecase: Usecase }) => {
+    const result = plans[input.usecase];
+    if (result.status === 'rejected') throw result.reason;
+    return result.value;
+  };
+
+  USECASES.forEach((usecase) => {
+    given(`[usecase] ${usecase} applied to a bare repo`, () => {
+      when('[t0] the emitted deps are installed', () => {
+        then('the install exits 0', () => {
+          const scene = getScene({ usecase });
+          if (scene.install.status !== 0)
+            throw new MalfunctionError(`pnpm install failed for ${usecase}`, {
+              status: scene.install.status,
+              output: scene.install.output,
+              hint: 'read the install output above; a registry or cache fault is the usual cause',
+            });
+          expect(scene.install.status).toEqual(0);
+        });
+      });
+
+      when('[t1] the emitted tree is compiled with the emitted tsconfig', () => {
+        then('the usecase emits a tsconfig.json', () => {
+          expect(getScene({ usecase }).tsconfigFound).toEqual(true);
+        });
+
+        then('the tsc diagnostics match snapshot', () => {
+          expect(getScene({ usecase }).compile.output).toMatchSnapshot(
+            `${usecase} — tsc --noEmit diagnostics`,
+          );
+        });
+
+        then('tsc --noEmit exits 0', () => {
+          const scene = getScene({ usecase });
+          if (scene.compile.status !== 0)
+            throw new ConstraintError(`tsc --noEmit failed for ${usecase}`, {
+              status: scene.compile.status,
+              output: scene.compile.output,
+              hint: 'a template the usecase ships does not compile; the diagnostics name it',
+            });
+          expect(scene.compile.status).toEqual(0);
+        });
+      });
+
+      when('[t2] the twice-applied repo is planned again', () => {
+        then('no file is flagged for an automatic fix (the apply converges)', () => {
+          expect(getPlan({ usecase }).automatic).toEqual([]);
+        });
+
+        then('no file the apply wrote is flagged by its own usecase', () => {
+          const cwd = realpathSync(tempDirs[usecase].repo);
+          const flaggedWritten = getPlan({ usecase }).manual.filter((file) =>
+            existsSync(path.join(cwd, file)),
+          );
+          expect(flaggedWritten).toEqual([]);
+        });
+
+        then('the files left for a human to author match snapshot', () => {
+          expect(getPlan({ usecase }).manual).toMatchSnapshot(
+            `${usecase} — files flagged for a human`,
+          );
+        });
+      });
+
+      when('[t3] the emitted cycle check runs, as `npm run test:lint` does', () => {
+        then('the install holds pg-pool exactly where the usecase is declared to', () => {
+          const scene = getScene({ usecase });
+          const declared = USECASES_WITH_PG_POOL.includes(usecase);
+          if (scene.holdsPgPool !== declared)
+            throw new ConstraintError(`pg-pool presence drifted for ${usecase}`, {
+              holdsPgPool: scene.holdsPgPool,
+              declared,
+              hint: 'update USECASES_WITH_PG_POOL to match the install, so the pg-pool verdict below stays real',
+            });
+          expect(scene.holdsPgPool).toEqual(declared);
+        });
+
+        then('it reports no cycle through pg-pool', () => {
+          const { cycles } = asCycleSummary({
+            output: getScene({ usecase }).cycles.output,
+          });
+          const cyclesThroughPgPool = cycles.filter((cycle) =>
+            cycle.includes('pg-pool'),
+          );
+          if (cyclesThroughPgPool.length > 0)
+            throw new ConstraintError(`pg-pool cycle found for ${usecase}`, {
+              cyclesThroughPgPool,
+              hint: 'the shipped patches/pg-pool.patch did not apply; check its key in persist-with-rds package.json, and whether pg-pool moved the line (pnpm warns by name)',
+            });
+          expect(cyclesThroughPgPool).toEqual([]);
+        });
+
+        if (USECASES_WITH_PG_POOL.includes(usecase))
+          then('it analyzes the tree, so the pg-pool verdict is real', () => {
+            expect(
+              asCycleSummary({ output: getScene({ usecase }).cycles.output })
+                .analyzed,
+            ).toEqual(true);
+          });
+
+        if (USECASES_WITH_PG_POOL.includes(usecase))
+          then('its emitted src imports pg, so dpdm can reach pg-pool', () => {
+            expect(getScene({ usecase }).srcImportsPg).toEqual(true);
+          });
+
+        // a drift in dpdm's cycle line format would parse to zero cycles and pass the pg-pool verdict blind
+        then('the parsed cycles agree with the verdict dpdm prints', () => {
+          const { output } = getScene({ usecase }).cycles;
+          const summary = asCycleSummary({ output });
+          if (!summary.analyzed) return expect(summary.cycles).toEqual([]);
+          const noneFound = output.includes('no circular dependency was found');
+          if (noneFound !== (summary.cycles.length === 0))
+            throw new MalfunctionError(`cycle parse drifted for ${usecase}`, {
+              noneFound,
+              cyclesParsed: summary.cycles.length,
+              hint: 'dpdm changed its cycle line format; update the line pattern in asCycleSummary',
+            });
+          expect(noneFound).toEqual(summary.cycles.length === 0);
+        });
+
+        // .note = the exit status rides in the snapshot, so a pass/fail flip shows in review. it is not
+        //         asserted 0: a bare repo with no src entry, and cycles at floor versions outside pg-pool,
+        //         each exit the check 1 for causes this clamp does not own
+        then('the exit status and the cycles it finds match snapshot', () => {
+          expect({
+            status: getScene({ usecase }).cycles.status,
+            ...asCycleSummary({ output: getScene({ usecase }).cycles.output }),
+          }).toMatchSnapshot(`${usecase} — test:lint:cycles summary`);
+        });
+      });
+    });
+  });
+});

package/dist/useCases.rhachet-roles-package.declapract.integration.test.ts

@@ -0,0 +1,43 @@
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+import { getAllPracticesForUsecase } from './utils/getAllPracticesForUsecase';
+
+/**
+ * .what = clamps the `rhachet-roles-package` usecase (#558)
+ * .why  = a role repo is an npm package first, so its resolved practice set must hold every
+ *         practice npm-package resolves to (extends is non-transitive; a lost core extend would
+ *         drop the baseline in silence), plus the rhachet practice that carries the #520 build order
+ * .note = reads src/useCases.yml from disk, hence the integration grain
+ */
+describe('useCases.yml — rhachet-roles-package', () => {
+  const usecasesYmlPath = join(__dirname, 'useCases.yml');
+
+  given('[case1] the declared usecases', () => {
+    when('[t0] rhachet-roles-package is resolved', () => {
+      const rolesPackage = getAllPracticesForUsecase({
+        usecasesYmlPath,
+        usecase: 'rhachet-roles-package',
+      });
+      const npmPackage = getAllPracticesForUsecase({
+        usecasesYmlPath,
+        usecase: 'npm-package',
+      });
+
+      then('it holds every practice npm-package resolves to', () => {
+        expect(rolesPackage).toEqual(expect.arrayContaining(npmPackage));
+      });
+
+      then('it holds the rhachet practice', () => {
+        expect(rolesPackage).toContain('rhachet');
+      });
+
+      then('its resolved set matches snapshot', () => {
+        expect([...rolesPackage].sort()).toMatchSnapshot(
+          'rhachet-roles-package practices',
+        );
+      });
+    });
+  });
+});

package/dist/useCases.yml

@@ -47,6 +47,17 @@ use-cases:
       - cicd-package
       - node-package
       - provision-github
+  # a rhachet roles package (rhachet-roles-*): publishes roles (briefs, skills, boot.yml,
+  # keyrack.yml) to npm, so it IS an npm package first (#558). the role-repo delta rides on
+  # the rhachet practice: a repo that self-links its roles via `link:.` builds `dist/` before
+  # `rhachet init` (#520), since the linked roles load their hooks from the build.
+  rhachet-roles-package:
+    extends:
+      - typescript-project-core # non-transitive: must extend core directly (declapract#17)
+      - typescript-project
+      - npm-package
+    practices:
+      - rhachet # restated: the practice that carries the role-repo delta (deduped by name)
   lambda-service:
     extends:
       - typescript-project-core # non-transitive: must extend core directly (declapract#17)

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

@@ -0,0 +1,15 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`genUnmigratedParamPathsDeclaration (#544) given: [case1] a repo whose prep.json holds an explicit param path when: [t1] the fix runs, then runs again then: the marker is stamped once, the explicit path kept, and the check passes 1`] = `
+"{
+  "@declapract:review": "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)",
+  "database": {
+    "role": {
+      "crud": {
+        "password": "$.at(aws::param/test-org/test-project/prep/crud)"
+      }
+    }
+  }
+}
+"
+`;