declapract-typescript-ehmpathy 0.49.10 → 0.49.12

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

@@ -0,0 +1,163 @@
+import { readFileSync } from 'node:fs';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+import ts from 'typescript';
+
+/**
+ * .what = a cross-file round-trip clamp on the stage↔access bridge. the transition encodes ONE fact
+ *         — that below prod `stage=dev ⟺ access=prep`, and at prod both axes read `prod` — in THREE
+ *         unlinked places: the serverless `accessByStage` map (the deploy-side bridge), the
+ *         `sdkAwsLambdaEnvAccessAncient` helper (the call-side slug), and the `resources.parameters.ts`
+ *         `accessSlug` ternary (the SSM-namespace cast). this asserts they agree per deployed tier, so
+ *         a drift in one without the others reddens (r11 nitpick, #571 north star).
+ * .note = the third restatement is a DELIBERATELY narrower cast: it casts a literal legacy SSM param
+ *         string, so `prep → dev` and `prod → prod` (agrees with the other two), but `test → test`
+ *         (the fleet-slug helper collapses test → dev). the leg asserts accessSlug's OWN documented
+ *         cast + cross-checks the map/helper only on the tiers all three share (prep, prod).
+ * .why  = two sources for one fact is the exact ambiguity the north star exists to kill. if the map
+ *         says `dev: prep` but the helper emits some other slug for `access=prep`, an outbound call
+ *         addresses a fleet the deploy never published — the compiler-invisible 404 (D31) returns,
+ *         now from a bridge half-edited rather than a two-axis split. one clamp over both files makes
+ *         a half-edit red.
+ * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it reads two template/declaration
+ *         files off the filesystem. no credential, no network.
+ * .teeth = drift the map's `dev:` target, or the helper's ancient branch, and the per-tier
+ *          round-trip assertion reddens — because the round-trip now EXECUTES the real helper source,
+ *          not a hand-modeled ternary, so a semantically-live rewrite (ternary→if, operand swap) that
+ *          preserved a pinned text fragment can no longer sail through green (r008 nitpick.1).
+ */
+
+const ACCESS_BY_STAGE_SRC = `${__dirname}/practices/serverless/best-practice/serverless.yml.declapract.ts`;
+const HELPER_SRC = `${__dirname}/practices/environments/best-practice/src/access/sdks/sdkAwsLambdaEnvAccessAncient.ts`;
+const NAMESPACE_SRC = `${__dirname}/practices/persist-with-rds/best-practice/provision/aws/resources.parameters.ts`;
+
+/**
+ * .what = parse the `accessByStage` yaml map out of the serverless declaration source.
+ * .why  = the map is a private const in the declaration, not exported, so the value is read from the
+ *         file text — the same boundary the ratchet kin cross.
+ */
+const parseAccessByStage = (src: string): Record<string, string> => {
+  const block = src.match(/accessByStage:\n([\s\S]*?)\n\n/)?.[1] ?? '';
+  const map: Record<string, string> = {};
+  for (const line of block.split('\n')) {
+    // named captures so the composer reads `key`/`value`, not positional `hit[1]`/`hit[2]`
+    const hit = line.match(/^\s+(?<key>\w+):\s+(?<value>\w+)/);
+    if (hit?.groups) map[hit.groups.key!] = hit.groups.value!;
+  }
+  return map;
+};
+
+/**
+ * .what = transpile the ancient helper template + execute it with a stubbed `envStatic.access`, and
+ *         return the slug it actually emits for that access.
+ * .why  = the helper is a plain `.ts` template whose `@src/utils/environment` import looks up in the
+ *         CONSUMER's tree, so this repo cannot import it directly. transpile-to-CommonJS + a
+ *         require-stub runs the real source here, so the round-trip asserts the helper's ACTUAL
+ *         return value per tier — not a re-derived model tied to source only by a text pin (which a
+ *         semantically-neutral reformat would break cosmetically while a logic bug sailed through).
+ *         this reuses the environments practice's executed-helper pattern (r008 nitpick.1).
+ */
+const runAncientSlug = (
+  input: { src: string; access: 'test' | 'prep' | 'prod' },
+): string => {
+  const transpiled = ts.transpileModule(input.src, {
+    compilerOptions: {
+      module: ts.ModuleKind.CommonJS,
+      target: ts.ScriptTarget.ES2020,
+    },
+  }).outputText;
+  const moduleExports: Record<string, () => string> = {};
+  const requireStub = (id: string): unknown =>
+    id.includes('environment') ? { envStatic: { access: input.access } } : {};
+  // eslint-disable-next-line no-new-func
+  new Function('exports', 'require', transpiled)(moduleExports, requireStub);
+  return (
+    moduleExports as {
+      sdkAwsLambdaEnvAccessAncient: (input: { access: null }) => string;
+    }
+  ).sdkAwsLambdaEnvAccessAncient({ access: null });
+};
+
+/**
+ * .what = extract the `accessSlug` ternary from the ssm-namespace declaration source + evaluate it for
+ *         one access, so the assertion reads the ACTUAL slug the third restatement yields.
+ * .why  = `accessSlug` is a private module const (`access === 'prep' ? 'dev' : access`), not exported,
+ *         so this repo cannot import it. an eval of the extracted expression executes the real logic
+ *         per tier — an operand swap (`'dev'` → `'stg'`) or a logic inversion reddens, where a pinned
+ *         text fragment would not. reuses the executed-source spirit of `runAncientSlug` (r011 B.1).
+ */
+const runAccessSlug = (input: {
+  src: string;
+  access: 'test' | 'prep' | 'prod';
+}): string => {
+  const rhs = input.src.match(/const accessSlug = ([^;]+);/)?.[1] ?? '';
+  // eslint-disable-next-line no-new-func
+  return new Function('access', `return (${rhs});`)(input.access) as string;
+};
+
+describe('stage↔access bridge — the two unlinked sources agree (round-trip clamp)', () => {
+  const scene = useBeforeAll(() => ({
+    accessByStage: parseAccessByStage(readFileSync(ACCESS_BY_STAGE_SRC, 'utf8')),
+    helperSrc: readFileSync(HELPER_SRC, 'utf8'),
+    namespaceSrc: readFileSync(NAMESPACE_SRC, 'utf8'),
+  }));
+
+  given('[case1] the deploy-side map and the call-side helper', () => {
+    when('[t0] the serverless accessByStage map is parsed', () => {
+      then('it bridges the ancient stage `dev` to access `prep`', () => {
+        expect(scene.accessByStage.dev).toEqual('prep');
+      });
+
+      then('it holds `prod` on both axes', () => {
+        expect(scene.accessByStage.prod).toEqual('prod');
+      });
+    });
+
+    when('[t1] the ancient helper is transpiled + executed per tier', () => {
+      then('it emits `dev` below prod (the only slug a `-dev-`-only peer publishes)', () => {
+        expect(runAncientSlug({ src: scene.helperSrc, access: 'prep' })).toEqual('dev');
+        expect(runAncientSlug({ src: scene.helperSrc, access: 'test' })).toEqual('dev');
+      });
+
+      then('it emits `prod` at prod (both axes converge)', () => {
+        expect(runAncientSlug({ src: scene.helperSrc, access: 'prod' })).toEqual('prod');
+      });
+    });
+
+    when('[t2] the round-trip is composed per deployed tier', () => {
+      // teeth: for each deployed access, the ancient slug the REAL helper emits must map BACK
+      // to that same access through accessByStage. a drift in either file breaks the identity.
+      then('access=prep round-trips through the ancient slug back to prep', () => {
+        const slug = runAncientSlug({ src: scene.helperSrc, access: 'prep' });
+        expect(scene.accessByStage[slug]).toEqual('prep');
+      });
+
+      then('access=prod round-trips through the ancient slug back to prod', () => {
+        const slug = runAncientSlug({ src: scene.helperSrc, access: 'prod' });
+        expect(scene.accessByStage[slug]).toEqual('prod');
+      });
+    });
+
+    when('[t3] the ssm-namespace ternary is evaluated per tier (the third restatement)', () => {
+      then('it holds its own documented cast: prep→dev, test→test, prod→prod', () => {
+        // the narrower cast: prep+prod agree with the map/helper, test keeps its own name (the
+        // fleet-slug helper collapses test→dev; this literal-string cast does not). the test→test
+        // leg guards a "tidy-up" that would force it to match the helper.
+        expect(runAccessSlug({ src: scene.namespaceSrc, access: 'prep' })).toEqual('dev');
+        expect(runAccessSlug({ src: scene.namespaceSrc, access: 'test' })).toEqual('test');
+        expect(runAccessSlug({ src: scene.namespaceSrc, access: 'prod' })).toEqual('prod');
+      });
+
+      then('it agrees with the deploy-side map + call-side helper on the shared tiers (prep, prod)', () => {
+        // prep: map bridges dev→prep, the ancient helper emits dev, and the namespace casts prep→dev
+        const prepSlug = runAccessSlug({ src: scene.namespaceSrc, access: 'prep' });
+        expect(prepSlug).toEqual(runAncientSlug({ src: scene.helperSrc, access: 'prep' }));
+        expect(scene.accessByStage[prepSlug]).toEqual('prep');
+        // prod: all three converge on the single slug
+        const prodSlug = runAccessSlug({ src: scene.namespaceSrc, access: 'prod' });
+        expect(prodSlug).toEqual(runAncientSlug({ src: scene.helperSrc, access: 'prod' }));
+        expect(scene.accessByStage[prodSlug]).toEqual('prod');
+      });
+    });
+  });
+});

package/dist/useCases.yml

@@ -1,6 +1,18 @@
 # define the different types of combinations of the best practices that we support
 use-cases:
-  typescript-project:
+  # the runtime-agnostic platform baseline: every practice shared by a node project and an
+  # expo app alike (agent tools, package manager, domain organization, lint/format, git).
+  # extracted so `typescript-project` and `app-react-native-expo` COMPOSE it via `extends`
+  # rather than hand-copy it — a practice added HERE reaches both consumers, so neither can
+  # silently drift from the baseline (the exact bug the fix-expo wish exists to fix).
+  #
+  # .note = declapract's `extends` is NON-TRANSITIVE (it pulls a usecase's OWN base
+  #         `.practices`, never its resolved-with-extends set — see declapract#17). so a
+  #         consumer that wants this core must extend `typescript-project-core` DIRECTLY; it
+  #         cannot inherit it through a usecase that itself extends core. every consumer below
+  #         does. the `getAllPracticesForUsecase` characterization test pins every usecase's
+  #         resolved set, so this extraction is proven to change zero practice for any repo.
+  typescript-project-core:
     practices:
       - cache
       - cicd-common
@@ -16,12 +28,20 @@ use-cases:
       - nonpublished-modules
       - package-json-order
       - rhachet
-      - tests
-      - typescript
+      - tests-any
+      - typescript-any
       - pnpm
+  typescript-project:
+    extends:
+      - typescript-project-core
+    practices:
+      # the node runtime delta atop the shared core: the tsc build + node jest + rate-limit lib
+      - tests-node
+      - typescript-node
       - bottleneck
   npm-package:
     extends:
+      - typescript-project-core # non-transitive: must extend core directly (declapract#17)
       - typescript-project
     practices:
       - cicd-package
@@ -29,6 +49,7 @@ use-cases:
       - provision-github
   lambda-service:
     extends:
+      - typescript-project-core # non-transitive: must extend core directly (declapract#17)
       - typescript-project
     practices:
       - artifact
@@ -49,29 +70,28 @@ use-cases:
       - uuid
   lambda-service-with-rds:
     extends:
-      - typescript-project # https://github.com/ehmpathy/declapract/issues/17
+      - typescript-project-core # https://github.com/ehmpathy/declapract/issues/17
+      - typescript-project
       - lambda-service
     practices:
       - persist-with-rds
-  lambda-service-with-dynamodb: # note that projects can still use both by specifying the `declapract.use-case: [lambda-service-with-dynamodb, lambda-service-with-rds]` since we allow use-cases to add together. `use-cases` just enable us to enforce a "minimum" set of practices
+  lambda-service-with-dynamodb: # projects can use both at once via `declapract.use-case: [lambda-service-with-dynamodb, lambda-service-with-rds]` since use-cases add together. a use-case just enforces a "minimum" set of practices
     extends:
-      - typescript-project # https://github.com/ehmpathy/declapract/issues/17
+      - typescript-project-core # https://github.com/ehmpathy/declapract/issues/17
+      - typescript-project
       - lambda-service
     practices:
       - persist-with-dynamodb
   app-react-native-expo:
+    extends:
+      - typescript-project-core # composes the shared platform baseline; only the expo delta is listed below
     practices:
-      - cicd-common
+      # the expo runtime delta atop the shared core: the expo cicd, the metro/expo lint,
+      # and the expo cuts of the typescript/tests triads. NO terraform-common — an expo app
+      # owns no terraform-managed infra (declastruct is the go-forward; see define.declastruct-goforward.md).
       - cicd-app-react-native-expo
-      - conventional-commits
-      - husky
-      - format
-      - git
-      - node
-      - nonpublished-modules
-      - package-json-order
-      - terraform-common
       - provision-github
-      - lint
       - lint-react
       - lint-react-native
+      - tests-expo
+      - typescript-expo

package/dist/utils/asPackageJSON.ts

@@ -0,0 +1,57 @@
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * .what = parse a consumer `package.json`, or throw a context-rich error on malformed json.
+ * .why  = a raw `JSON.parse(contents)` throws a context-free engine `SyntaxError`
+ *         (`Unexpected token ... in JSON at position N`) that names no practice, no
+ *         dependency, no file, and no remediation. a declapract consumer mid-edit — or
+ *         a declaration ever handed non-json contents — gets zero signal about which
+ *         declaration failed or how to recover. this wraps the parse and rethrows with
+ *         the practice + a concrete fix hint, so a leaked failure is self-explanatory.
+ *         ONE source for every declaration that reads a `package.json`, so the
+ *         diagnostic cannot drift between them (mirrors `defineExpectedGitignoreContents`
+ *         / `isDeferredToDeprecatedDirMove`).
+ */
+export const asPackageJSON = (
+  input: { contents: string },
+  context: { practice: string },
+): Record<string, any> => {
+  // parse in its own scope, so the catch wraps ONLY the parse — a ConstraintError from the
+  // shape guard below must not be caught and re-labelled as a parse failure.
+  const parsed = (() => {
+    try {
+      return JSON.parse(input.contents);
+    } catch (error) {
+      // allowlist the ONLY error JSON.parse can throw — a SyntaxError on malformed json. any other
+      // error is not a parse failure, so rethrow it unwrapped rather than relabel it a parse failure
+      // (rule.forbid.failhide: a catch allowlists its expected errors and surfaces the rest).
+      if (!(error instanceof SyntaxError)) throw error;
+      const reason = error.message;
+      // a malformed consumer package.json is CALLER-must-fix (exit 2), not a server malfunction —
+      // ConstraintError carries that semantic + the practice/reason context (rule.require.failloud).
+      throw new ConstraintError(
+        `[${context.practice}] could not parse package.json: ${reason}. ` +
+          `fix: ensure the package.json holds valid json (a stray comma or character is the usual cause).`,
+        { practice: context.practice, reason },
+      );
+    }
+  })();
+
+  // valid json, but a top-level scalar / array / null is not a package.json OBJECT. the callers
+  // deref `.dependencies` / `.devDependencies` on it, which would throw a context-free
+  // `TypeError: Cannot read properties of null` — the exact context-free failure this util exists
+  // to replace. so guard the SHAPE too, and throw the same caller-must-fix ConstraintError.
+  const shape = Array.isArray(parsed)
+    ? 'an array'
+    : parsed === null
+      ? 'null'
+      : typeof parsed;
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+    throw new ConstraintError(
+      `[${context.practice}] package.json is not a json object (got ${shape}). ` +
+        `fix: ensure the package.json holds a top-level json object (a {...}, not a scalar or array).`,
+      { practice: context.practice, shape },
+    );
+
+  return parsed;
+};

package/dist/utils/asPrepConfigPath.ts

@@ -0,0 +1,12 @@
+/**
+ * .what = relocate a `config/dev.json` relativeFilePath to `config/prep.json`.
+ * .why  = ONE source for the relocate half of the two `old-dev-config-location` declarers
+ *         (config + persist-with-rds), paired with `migrateDevConfigToPrep` (the content half).
+ *         the relocate regex was duplicated verbatim in both declarers' fix bodies; a future
+ *         edit to the target filename (e.g. `config/prep/`) must touch one place now, never
+ *         two that drift. mirrors `defineExpectedGitignoreContents` / `migrateDevConfigToPrep`.
+ */
+export const asPrepConfigPath = (input: {
+  relativeFilePath: string;
+}): string =>
+  input.relativeFilePath.replace(/^config\/dev\.json$/, 'config/prep.json');

package/dist/utils/defineExpectedNpmrcContents.ts

@@ -0,0 +1,103 @@
+/**
+ * .what = the base `.npmrc` lines every node repo carries, order-inert
+ * .why  = one source for both `check` and `fix`, so the gate and the repair can
+ *         never disagree about what the file should hold. inlined here rather than
+ *         read from a sibling template so there is a single source (mirrors
+ *         `defineExpectedGitignoreContents`, whose declaration carries no template
+ *         file either).
+ */
+export const npmrcBaseLines: readonly string[] = [
+  'engine-strict=true',
+  'save-exact=true',
+  'message=%s 🎉',
+];
+
+/**
+ * .what = the hoisted-linker lines an expo repo layers atop the base `.npmrc`
+ * .why  = `node-linker=hoisted` flattens node_modules — create-expo-app's OWN
+ *         default for pnpm, and the documented fallback when isolated installs
+ *         break metro/react-native native-module lookup. SDK 54+ supports pnpm's
+ *         isolated default for most packages, so the forced-vs-opt-in POLICY is a
+ *         wisher-deferred fulcrum (see `howto.pnpm-expo-hoisted-linker.md`); the
+ *         findsert delivers create-expo-app's default shape append-only until the
+ *         wisher rules. these are findserted PER-LINE (append each absent line),
+ *         like `npmrcBaseLines` and `defineExpectedGitignoreContents` — so a line
+ *         ADDED here later (e.g. a new `public-hoist-pattern[]`) still reaches an
+ *         already-hoisted consumer on the next `declapract fix`, rather than a skip
+ *         because a block-level sentinel was already present. no line's ORDER
+ *         carries load (unlike `.gitignore`'s negations), so a per-line union is
+ *         safe and removes the asymmetry with the base-line findsert below.
+ */
+export const npmrcExpoHoistLines: readonly string[] = [
+  '# hoisted linker flattens node_modules — create-expo-app default for pnpm,',
+  '# the documented fallback when isolated installs break metro native lookup',
+  'node-linker=hoisted',
+  'public-hoist-pattern[]=*expo*',
+  'public-hoist-pattern[]=*react-native*',
+  'public-hoist-pattern[]=@react-native/*',
+  'public-hoist-pattern[]=metro*',
+  'public-hoist-pattern[]=*metro-*',
+];
+
+/**
+ * .what = emits the `.npmrc` the node practice declares, given the repo's extant one
+ * .why  = a FINDSERT by construction — the file's own lines are preserved and only
+ *         MISSING declared lines are appended, so no line is ever dropped. this is
+ *         what forecloses the narrow-scope strip: under `declapract fix --practice
+ *         node` the expo signal goes dark (`projectPractices === ['node']`), so the
+ *         declared set is just the base lines — but because the fix only APPENDS
+ *         what is absent (never overwrites), a correctly-hoisted `.npmrc` is left
+ *         intact rather than reverted to base. the whole hazard class is gone, not
+ *         merely characterized.
+ * .why  = mirrors `defineExpectedGitignoreContents` (union-not-clobber). a repo's
+ *         own custom `.npmrc` lines survive for the same reason a repo's custom
+ *         `.gitignore` ignores do.
+ * .note = a fixed point: `fix(fix(x)) === fix(x)`, and `check` passes on its own
+ *         output — without both, `declapract fix` would rewrite this file forever.
+ */
+export const defineExpectedNpmrcContents = (input: {
+  contents: string | null;
+  projectPractices: string[];
+}): string => {
+  const isExpo = input.projectPractices.includes('cicd-app-react-native-expo');
+
+  // the repo's extant lines, trailing blank(s) dropped (one trailing newline re-added below)
+  const extant = (input.contents ?? '').replace(/\n+$/, '');
+  const lines = extant === '' ? [] : extant.split('\n');
+
+  // findsert each base line (append if absent — never remove, never reorder)
+  const withBase = npmrcBaseLines.reduce<string[]>(
+    (acc, line) => (acc.includes(line) ? acc : [...acc, line]),
+    lines,
+  );
+
+  // a consumer who explicitly set a NON-hoisted linker (e.g. `node-linker=isolated`,
+  // pnpm's SDK-54 default) has OPTED OUT — respect it. do NOT append `node-linker=hoisted`
+  // (which would leave two rival `node-linker=` directives), and skip the whole hoist block:
+  // the hoist is create-expo-app's default, OFFERED not imposed over an explicit choice.
+  const hasOptedOutLinker = withBase.some(
+    (line) => line.startsWith('node-linker=') && line !== 'node-linker=hoisted',
+  );
+  const wantsHoist = isExpo && !hasOptedOutLinker;
+
+  // findsert each expo hoist line PER-LINE when wanted (append if absent). a blank
+  // separator precedes the block ONLY on a fresh insert — i.e. when NONE of the
+  // hoist lines are present yet — so an already-hoisted file gains a newly-added
+  // hoist line at the tail without a second separator, and a bare file gets the
+  // block set off from the base lines exactly once.
+  const anyHoistPresent = npmrcExpoHoistLines.some((line) =>
+    withBase.includes(line),
+  );
+  const withSeparator =
+    wantsHoist && !anyHoistPresent && withBase.length > 0
+      ? [...withBase, '']
+      : withBase;
+  const withHoist = wantsHoist
+    ? npmrcExpoHoistLines.reduce<string[]>(
+        (acc, line) => (acc.includes(line) ? acc : [...acc, line]),
+        withSeparator,
+      )
+    : withSeparator;
+
+  return `${withHoist.join('\n')}\n`;
+};

package/dist/utils/getAllPathsUnderDir.ts

@@ -0,0 +1,45 @@
+import { readdirSync } from 'node:fs';
+
+/**
+ * .what = every file path under a directory, walked recursively with node's own readdir.
+ * .why  = ONE source for the practice-tree walks the declaration clamps share — the `domain`
+ *         layout clamp (D51) and the `errors` catch-all-glob clamp (D48) each recursed the
+ *         same way in their own copy, which is the "one source, no drift" convention this repo
+ *         holds elsewhere (`defineExpectedGitignoreContents` / `isDeferredToDeprecatedDirMove`).
+ *         each caller applies its OWN filter over the returned paths — the walk is shared, the
+ *         per-clamp policy (all files vs declarations-only) stays local, where it legitimately
+ *         differs.
+ * .note = `skip` names directories NOT to descend into (a TRAVERSAL decision, not a selection).
+ *         it is required and nullable per rule.forbid.undefined-inputs — a caller that wants the
+ *         whole tree passes `skip: null`, never an omitted arg. the actionPins pin clamp passes
+ *         its fixture dirs here so the walk itself never enters them — one util, one contract,
+ *         no same-name/different-shape twin.
+ */
+export const getAllPathsUnderDir = (input: {
+  dir: string;
+  skip: string[] | null;
+}): string[] =>
+  readdirSync(input.dir, { withFileTypes: true }).flatMap((entry) => {
+    const path = `${input.dir}/${entry.name}`;
+    if (!entry.isDirectory()) return [path];
+    return (input.skip ?? []).includes(entry.name)
+      ? []
+      : getAllPathsUnderDir({ dir: path, skip: input.skip });
+  });
+
+/**
+ * .what = the canonical dirs a practice-tree walk (`src/practices/**`) never descends into.
+ * .why  = three root-level clamps each walk the practice tree and each must skip the same
+ *         non-template dirs: a fixture (`.test`) or a jest snapshot (`__snapshots__`) is an INPUT
+ *         to a test, not a template a consumer receives, so a walk that reached one would red on a
+ *         non-defect; `node_modules` a symlinked test tree can expose. named ONCE here — the same
+ *         "one source, no drift" convention the walker itself embodies — so the three callers
+ *         cannot drift into inconsistent shapes (they held two: `['.test','__snapshots__','node_modules']`
+ *         vs `['__snapshots__','.test']`).
+ * .note = this is NOT `actionPins`'s `FIXTURE_DIRS`. that names the fixture-dir CLASS a pin clamp
+ *         must exclude AND assert holds at least one unpinned ref — a distinct domain concept with
+ *         its own glossary cluster. to merge the two would conflate a traversal-skip set with a
+ *         fixture-dir class (rule.forbid.domain-term-ambiguity); the walk-skip set legitimately
+ *         also carries `node_modules`, which the fixture-dir class does not.
+ */
+export const PRACTICE_TREE_SKIP_DIRS = ['.test', '__snapshots__', 'node_modules'];

package/dist/utils/getAllPracticesForUsecase.ts

@@ -0,0 +1,79 @@
+import { readFileSync } from 'fs';
+import { ConstraintError } from 'helpful-errors';
+import yaml from 'yaml';
+
+/**
+ * .what = expands a usecase's FULL practice set, per `extends`, exactly as declapract's
+ *         `readUseCaseDeclarations` does.
+ * .why  = both the platform-baseline drift guard and the extends-refactor characterization
+ *         test must reason about a usecase's RESOLVED practices, not its raw `.practices`
+ *         list. declapract's `extends` is a NON-TRANSITIVE union: a usecase that extends X
+ *         pulls X's OWN base `.practices` (never X's own resolved-with-extends set), then
+ *         dedupes by name (readUseCaseDeclarations.js: `hydratedPractices.push(...extendedUseCase.practices)`
+ *         + `uniqBy(..., name)`). this util is a HAND-MIRROR of that one algorithm — a
+ *         duplicate, not an import, so it CAN drift if declapract changes its expansion.
+ *         it is pinned to the installed declapract release (see `declapract` in package.json);
+ *         re-check it against `readUseCaseDeclarations.js` on any declapract bump.
+ * .note = non-transitive is the subtlety that carries the load: if A extends B and B extends
+ *         C, then A does NOT inherit C through B — A must extend C directly. this is why
+ *         `lambda-service-with-rds` carries a `# declapract#17` double-extends today.
+ */
+
+interface UsecaseDefinition {
+  extends?: string[];
+  practices: string[];
+}
+
+/**
+ * .what = the deduped set of practice names, order preserved (first occurrence wins).
+ * .why  = a named transformer so the orchestrator reads as narrative ("dedupe the names")
+ *         rather than an inline `[...new Set(...)]` a reader must mentally simulate
+ *         (rule.forbid.inline-decode-friction). mirrors declapract's own `uniqBy(..., name)`.
+ */
+const asDedupedPractices = (input: { names: string[] }): string[] => [
+  ...new Set(input.names),
+];
+
+const readUsecases = (input: {
+  usecasesYmlPath: string;
+}): Record<string, UsecaseDefinition> =>
+  yaml.parse(readFileSync(input.usecasesYmlPath, 'utf-8'))['use-cases'];
+
+/**
+ * .what = the resolved, deduped practice-name set for one usecase (extends applied)
+ */
+export const getAllPracticesForUsecase = (input: {
+  usecasesYmlPath: string;
+  usecase: string;
+}): string[] => {
+  const usecases = readUsecases({ usecasesYmlPath: input.usecasesYmlPath });
+  const definition = usecases[input.usecase];
+  if (!definition)
+    throw new ConstraintError(`no usecase named '${input.usecase}'`, {
+      usecase: input.usecase,
+      usecasesYmlPath: input.usecasesYmlPath,
+      available: Object.keys(usecases),
+    });
+
+  // each extended usecase contributes its OWN base practices (non-transitive), exactly
+  // as declapract does — flatMap keeps this immutable (no push onto a const array)
+  const extendedPractices = (definition.extends ?? []).flatMap((extendedName) => {
+    const extended = usecases[extendedName];
+    if (!extended)
+      throw new ConstraintError(
+        `usecase '${input.usecase}' extends a usecase that is absent: '${extendedName}'`,
+        {
+          usecase: input.usecase,
+          extendedName,
+          available: Object.keys(usecases),
+        },
+      );
+    return extended.practices;
+  });
+
+  // the usecase's own base practices come first, then the extended ones; dedupe by name
+  // (order-independent — callers compare as sorted sets)
+  return asDedupedPractices({
+    names: [...definition.practices, ...extendedPractices],
+  });
+};

package/dist/utils/isDeferredToDeprecatedDirMove.ts

@@ -0,0 +1,37 @@
+/**
+ * .what = the deprecated source dirs whose files a peer dir-move bad-practice
+ *         RELOCATES (logic-dir, data-dir, domain-dir, model-dir, services-dir,
+ *         nonpublished-modules-dir).
+ * .why  = a file still under one of these gets MOVED this pass; any in-place
+ *         rewrite of that same file (import-path rewrite) must DEFER to the next
+ *         pass, when the file sits at its new location. otherwise declapract
+ *         applies a relocate AND an in-place rewrite to one file in one apply —
+ *         the move unlinks the source, then the rewrite throws ENOENT against it.
+ *         one source for both declarers that must defer (mirrors
+ *         `defineExpectedGitignoreContents` / `defineExpectedNpmrcContents`), so
+ *         the guard cannot drift between them.
+ */
+export const DEPRECATED_SRC_DIR_PATTERNS: readonly RegExp[] = [
+  /\/logic\//,
+  /\/data\//,
+  /\/domain\//,
+  /\/model\//,
+  /\/services\//,
+  /\/__nonpublished_modules__\//,
+];
+
+/**
+ * .what = true when a file still sits under a deprecated src dir, so an in-place
+ *         rewrite of it must DEFER to the peer dir-move's next pass.
+ * .why  = the shared predicate both `old-import-paths` (directory-structure-src)
+ *         and `relative-imports` (typescript-any) gate their in-place import
+ *         rewrite on — so neither rewrites a file the same apply relocates.
+ */
+export const isDeferredToDeprecatedDirMove = (input: {
+  relativeFilePath: string | undefined;
+}): boolean => {
+  const relativeFilePath = input.relativeFilePath ?? '';
+  return DEPRECATED_SRC_DIR_PATTERNS.some((pattern) =>
+    pattern.test(relativeFilePath),
+  );
+};

package/dist/utils/migrateDevConfigToPrep.ts

@@ -0,0 +1,47 @@
+/**
+ * .what = migrate a `config/dev.json`'s ONE unambiguous tier token from `dev` to `prep`: the
+ *         `"access": "dev"` key. every HOST value is preserved verbatim.
+ * .why  = ONE source for the two `old-dev-config-location` declarers (config +
+ *         persist-with-rds), so the tier-migration cannot drift between them —
+ *         mirrors `defineExpectedGitignoreContents` / `isDeferredToDeprecatedDirMove`.
+ *         both declarers relocate `config/dev.json` → `config/prep.json` and migrate
+ *         the access; this holds the shared byte-identical core so a future edit
+ *         touches one place, never two that drift.
+ *
+ *         ONLY the `access` key migrates. the `access` KEY names the axis, so its value is
+ *         known: `"access": "dev"` → `"access": "prep"`. no guess.
+ *
+ *         a HOST is NEVER rewritten — this util runs on a CONSUMER's real `config/dev.json`,
+ *         whose host values are the consumer's own. a `.dev` label is axis-ambiguous WHEREVER
+ *         it sits: `auth.myapp.dev` may be a public `.dev` gTLD or an internal tier host, and
+ *         `api.dev.paypal.com` carries a mid-dotted `dev` that is a FOREIGN host's own label,
+ *         not a tier segment. the migration cannot tell a tier host from a foreign host by
+ *         structure, so per the wish's guard #3 (a rewrite that cannot verify its output must
+ *         NOT guess) it rewrites NO host at all — the earlier mid-dotted rewrite guessed one
+ *         position over from the terminal case, and silently corrupted a foreign public host
+ *         (`api.dev.paypal.com` → `api.prep.paypal.com`) whose only signal was a human reading
+ *         the apply diff. dropping it applies guard #3 uniformly.
+ *
+ *         the residual: a consumer whose OWN tier host is a bare `.dev` (`mydb.dev`) keeps it
+ *         after the migrate, so it must set the prep host by hand. that is correct by guard #3
+ *         — the util cannot know the consumer's prep host (the real template keys it as a
+ *         `@declapract{variable.databaseClusterHost.prep}`, a per-consumer value), so host
+ *         migration is out of this util's scope. a stranded tier host fails LOUD at connect
+ *         time (a connection error, never silent wrong data), and the apply diff shows the
+ *         access flip so the host review is visible.
+ *
+ *         why no review marker: an earlier shape appended a `@declapract:review` marker INTO
+ *         the host value. that corrupted the value (a broken host string), and both declarers
+ *         gate on `FileCheckType.EXISTS`, which never reads content — so a `declapract fix`
+ *         left the file with a corrupt value while `declapract plan` read CLEAN, the exact
+ *         silent-break class this whole wish exists to retire. the config file is JSON, which
+ *         admits no comment, so a plan-visible marker is impossible here; the migration instead
+ *         does only what it can verify (the `access` key) and rewrites no value it cannot.
+ */
+export const migrateDevConfigToPrep = (input: { contents: string }): string =>
+  // the access itself — the ONE unambiguous key/value (the `access` key names the axis).
+  // GLOBAL: a config with more than one `"access": "dev"` (a per-section or per-environment
+  // override) migrates EVERY occurrence, not just the first — a non-global replace left the rest
+  // silently `dev` and could not converge (a re-run's first-only match no-ops on the already-`prep`
+  // key). idempotent: once rewritten, a re-run finds no `"access": "dev"` to match. no host is touched.
+  input.contents.replace(/"access":\s*"dev"/g, '"access": "prep"');

package/dist/utils/readFile.ts

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
 import util from 'node:util';
 
-export const readFile = async (filePath: string): Promise<string> =>
-  util.promisify(fs.readFile)(filePath, 'utf-8');
+export const readFile = async (input: { filePath: string }): Promise<string> =>
+  util.promisify(fs.readFile)(input.filePath, 'utf-8');