declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/practices/domain/.declapract.integration.test.ts

@@ -0,0 +1,115 @@
+import { relative } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from '../../utils/getAllPathsUnderDir';
+
+/**
+ * .what = holds the `domain` best-practice to the go-forward `src/domain.objects/` layout, so it
+ *         can never again require a file that its kin `directory-structure-src`'s `domain-dir`
+ *         bad-practice forbids (D51 / #574).
+ * .why  = both practices sit in `typescript-project-core`, so every service repo carries both.
+ *         `domain-dir` forbids EVERY file under `src/**​/domain/**` and its fix RELOCATES them to
+ *         `src/domain.objects/`. while `domain` required `src/domain/objects/index.ts`, a repo that
+ *         satisfied `domain` VIOLATED `domain-dir`, and `domain-dir`'s fix moved the required file
+ *         AWAY — a terminal, unrepairable state. keyed on `domain.objects`, the two agree:
+ *         `domain-dir`'s fix produces exactly what `domain` requires.
+ * .note = this is an INTEGRATION test by the same rule the sibling `actionPins` walk cites — it
+ *         reads the filesystem (`readdirSync` over the `domain` best-practice tree), and
+ *         `rule.forbid.unit.remote-boundaries` puts any filesystem-crossing test in the integration
+ *         suite. it needs no credential and no network; the boundary alone classifies it.
+ * .note = this is the FOCUSED clamp for the one collision D51 named. the wish's broader durable
+ *         guard — "no best-practice path is matched by a bad-practice glob in the SAME usecase,
+ *         across every practice" — is owed as a follow-on; it must land with a full collision audit,
+ *         since a repo-wide lint may surface other overlaps already present that each need a verdict.
+ */
+
+const BEST_PRACTICE_DIR = `${__dirname}/best-practice`;
+
+// the `schematic-joi-model` bad-practice DETECTS joi models by content and rewrites them to
+// domain-objects. its subject glob scopes WHERE it looks; keyed at the deprecated `src/domain/`
+// path it is inert on any migrated repo (D51 / #574, ask 2) — the go-forward path is
+// `src/domain.objects/`, exactly where `directory-structure-src`'s `domain-dir` relocates files.
+const JOI_DETECTOR_DIR = `${__dirname}/bad-practices/schematic-joi-model`;
+
+/**
+ * .what = the CONSUMER target path a declaration governs, relative to a practice-half base dir.
+ *         a `*.declapract.ts` declaration governs its filename minus that suffix; any other file is
+ *         a template that governs itself.
+ */
+const asConsumerTargetPath = (input: { absPath: string; baseDir: string }): string => {
+  const rel = relative(input.baseDir, input.absPath);
+  return rel.replace(/\.declapract\.ts$/, '');
+};
+
+/**
+ * .what = does a consumer target path sit under a bare `domain/` path segment?
+ * .why = that is precisely the set `domain-dir`'s `src/**​/domain/**` glob forbids. a
+ *        `domain.objects` segment is NOT a `domain` segment (the `.objects` makes it a distinct
+ *        directory name), so the go-forward layout reads false here.
+ */
+const isUnderBareDomainSegment = (input: { targetPath: string }): boolean =>
+  input.targetPath.split('/').includes('domain');
+
+/**
+ * .what = every declared CONSUMER target path under a practice-half dir — the walk minus the files
+ *         that are not governed consumer paths (readmes, todos, `.test.ts`, `__snapshots__`).
+ * .why  = both scenes below gather the same set from different base dirs; one named transformer
+ *         holds the exclusion list in one place rather than an inline `.filter` chain a reader
+ *         must simulate twice (rule.require.named-transformers).
+ */
+const getConsumerTargetPaths = (input: { dir: string }): string[] =>
+  getAllPathsUnderDir({ dir: input.dir, skip: null })
+    .filter((path) => !/\.declapract\.readme\.md$/.test(path))
+    .filter((path) => !/\.declapract\.todo\.md$/.test(path))
+    // a test file is not a governed consumer path — exclude it so the walk holds
+    // only real declarations to the layout, not `.test.ts` / `__snapshots__`
+    .filter((path) => !/\.test\.ts$/.test(path))
+    .filter((path) => !/\/__snapshots__\//.test(path))
+    .map((absPath) => asConsumerTargetPath({ absPath, baseDir: input.dir }));
+
+describe('domain practice — go-forward layout (D51 clamp)', () => {
+  given('[case1] the `domain` best-practice tree', () => {
+    const scene = useBeforeAll(() => ({
+      targetPaths: getConsumerTargetPaths({ dir: BEST_PRACTICE_DIR }),
+    }));
+
+    when('[t0] its declared consumer target paths are gathered', () => {
+      then('none sits under a bare `domain/` segment that `domain-dir` forbids', () => {
+        // teeth: the pre-fix declaration at `src/domain/objects/index.ts.declapract.ts` targets
+        // `src/domain/objects/index.ts`, whose `domain` segment is exactly what `domain-dir`
+        // relocates — so a revert of the move to the deprecated path reddens this assertion.
+        const offenders = scene.targetPaths.filter((targetPath) =>
+          isUnderBareDomainSegment({ targetPath }),
+        );
+        expect(offenders).toEqual([]);
+      });
+
+      then('the objects index is declared at the `src/domain.objects/` path', () => {
+        expect(scene.targetPaths).toContain('src/domain.objects/index.ts');
+      });
+    });
+  });
+
+  given('[case2] the `schematic-joi-model` bad-practice tree', () => {
+    const scene = useBeforeAll(() => ({
+      targetPaths: getConsumerTargetPaths({ dir: JOI_DETECTOR_DIR }),
+    }));
+
+    when('[t0] its declared subject glob paths are gathered', () => {
+      then('none sits under a bare `domain/` segment (else the detector is inert post-migration)', () => {
+        // teeth: revert the glob to `src/domain/**/*.ts.declapract.ts` and its subject path
+        // `src/domain/**/*.ts` carries a bare `domain` segment — the deprecated location a
+        // migrated repo no longer holds — so this assertion reddens.
+        const offenders = scene.targetPaths.filter((targetPath) =>
+          isUnderBareDomainSegment({ targetPath }),
+        );
+        expect(offenders).toEqual([]);
+      });
+
+      then('the joi detector targets the go-forward `src/domain.objects/` path', () => {
+        expect(scene.targetPaths).toContain('src/domain.objects/**/*.ts');
+      });
+    });
+  });
+});

package/dist/{.test/assets/expo-migration/declarations/practices/domain/bad-practices/schematic-joi-model/src/domain → practices/domain/bad-practices/schematic-joi-model/src/domain.objects}/<star><star>/<star>.ts.declapract.ts

@@ -3,7 +3,10 @@ import type { FileCheckFunction, FileFixFunction } from 'declapract';
 export const check: FileCheckFunction = (contents) => {
   if (contents?.includes('SchematicJoiModel')) return; // if it includes that, then this file matches a bad practice
   if (contents?.includes('schematic-joi-model')) return; // if it includes that, then this file matches a bad practice
-  throw new Error('passes'); // otherwise, does not match the bad practice
+  // otherwise, does not match the bad practice: no SchematicJoiModel import or schematic-joi-model reference found
+  throw new Error(
+    'does not match bad practice: no SchematicJoiModel or schematic-joi-model reference found',
+  );
 };
 export const fix: FileFixFunction = (contents) => {
   if (!contents) return {}; // shouldnt be called if file does not exist, but handle it in case anyway

package/dist/practices/domain/best-practice/package.json

@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "domain-objects": "@declapract{check.minVersion('0.31.13')}",
-    "type-fns": "@declapract{check.minVersion('1.21.3')}"
+    "domain-objects": "@declapract{check.minVersion('0.34.0')}",
+    "type-fns": "@declapract{check.minVersion('1.21.4')}"
   }
 }

package/dist/practices/domain/best-practice/src/domain.objects/index.ts.declapract.ts

@@ -0,0 +1,12 @@
+import { FileCheckType } from 'declapract';
+
+// a project should declare domain objects — otherwise, what does the service operate on?
+//
+// this requires the `src/domain.objects/` layout that `directory-structure-src`'s `domain-dir`
+// bad-practice enforces. it deliberately does NOT require the deprecated `src/domain/objects/`
+// path: `domain-dir` forbids every file under `src/**/domain/**` and its fix relocates them to
+// `src/domain.objects/`, so a check that required `src/domain/objects/index.ts` (D51) contradicted
+// its own kin — `domain-dir`'s fix moved the required file away, so a repo reached a terminal,
+// unrepairable state. keyed on the go-forward layout, the two practices agree: `domain-dir`'s fix
+// produces exactly this path.
+export const check = FileCheckType.EXISTS;

package/dist/practices/environments/.declapract.integration.test.ts

@@ -0,0 +1,136 @@
+import { readFileSync } from 'node:fs';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+import ts from 'typescript';
+
+/**
+ * .what = holds the `sdkAwsLambdaEnvAccess{Ancient,Contemp}` helper templates — the
+ *         north-star's first named primitive — to their exports, their honest return type,
+ *         AND their actual runtime behavior.
+ * .why  = each helper is a plain `.ts` template (no `.declapract.ts` companion), so it sits
+ *         OUTSIDE this repo's own tsconfig (`include: src/**​/*.declapract.ts`) and is never
+ *         type-checked here — by design, since its imports (`@src/utils/environment`) look up
+ *         in the CONSUMER's tree, not this repo's. so a text pin alone cannot prove behavior:
+ *         a logic bug that preserves the pinned text would sail through green. this test
+ *         transpiles each template + executes its function with a stubbed `envStatic`, so it
+ *         proves the RETURN VALUE per access, not merely the source shape.
+ * .note = INTEGRATION by rule.forbid.unit.remote-boundaries: it reads the filesystem (the
+ *         template files). no credential, no network — the boundary alone classifies it.
+ *         the pair lives in two files per rule.require.single-responsibility (one exported
+ *         procedure per file); the ancient file also carries the shared `LambdaEnvSlug` type.
+ * .teeth = the behavioral assertions are the sharp ones: the ancient target MUST return `dev`
+ *          below prod (the only slug a `-dev-`-only peer publishes), never `prep`. a rewrite of
+ *          the ancient branch to `access` reddens `runHelperFile(...Ancient, 'prep')`. the
+ *          honest-type pin (`LambdaEnvSlug`, no `as`-cast) reddens if the type-lie returns.
+ */
+
+const SDK_DIR = `${__dirname}/best-practice/src/access/sdks`;
+const ANCIENT_PATH = `${SDK_DIR}/sdkAwsLambdaEnvAccessAncient.ts`;
+const CONTEMP_PATH = `${SDK_DIR}/sdkAwsLambdaEnvAccessContemp.ts`;
+
+/**
+ * .what = transpile one helper template + execute its sole export with a stubbed
+ *         `envStatic.access`, returning the named function.
+ * .why  = the template's `@src/utils/environment` import looks up in the consumer's tree, so
+ *         this repo cannot import it directly; transpile-to-CommonJS + a require-stub lets the
+ *         real source run here, so the assertions prove behavior rather than source text.
+ */
+const runHelperFile = (input: {
+  path: string;
+  name: string;
+  access: 'test' | 'prep' | 'prod';
+}): (() => string) => {
+  const source = readFileSync(input.path, 'utf8');
+  const transpiled = ts.transpileModule(source, {
+    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[input.name];
+};
+
+describe('environments practice — the EnvAccess helper primitive (north-star clamp)', () => {
+  given('[case1] the shipped helper templates — their source shape', () => {
+    // readFileSync throws if a template is absent — that throw IS the presence proof
+    const scene = useBeforeAll(() => ({
+      ancient: readFileSync(ANCIENT_PATH, 'utf8'),
+      contemp: readFileSync(CONTEMP_PATH, 'utf8'),
+    }));
+
+    when('[t0] the contents are read', () => {
+      then('the ancient file exports exactly the ancient target function', () => {
+        expect(scene.ancient).toContain(
+          'export const sdkAwsLambdaEnvAccessAncient',
+        );
+        expect(scene.ancient).not.toContain(
+          'export const sdkAwsLambdaEnvAccessContemp',
+        );
+      });
+
+      then('the contemp file exports exactly the contemp target function', () => {
+        expect(scene.contemp).toContain(
+          'export const sdkAwsLambdaEnvAccessContemp',
+        );
+        expect(scene.contemp).not.toContain(
+          'export const sdkAwsLambdaEnvAccessAncient',
+        );
+      });
+
+      then('the ancient target has the honest LambdaEnvSlug return type, not an as-cast', () => {
+        expect(scene.ancient).toContain('LambdaEnvSlug');
+        expect(scene.ancient).not.toContain('as EnvironmentAccessTier');
+      });
+
+      then('the ancient file source matches snapshot (a structural edit vibechecks in a review)', () => {
+        // the toContain asserts above catch a named regression; the full-source snapshot catches an
+        // UNnamed one — an added param, a changed import, a dropped comment — that trips no assert
+        // yet a reviewer must eyeball (rule.require.snapshots)
+        expect(scene.ancient).toMatchSnapshot(
+          'sdkAwsLambdaEnvAccessAncient.ts source',
+        );
+      });
+
+      then('the contemp file source matches snapshot', () => {
+        expect(scene.contemp).toMatchSnapshot(
+          'sdkAwsLambdaEnvAccessContemp.ts source',
+        );
+      });
+    });
+  });
+
+  given('[case2] the transpiled + executed helper templates — their runtime behavior', () => {
+    when('[t0] the ancient target runs under each access', () => {
+      then('it returns the dev slug below prod, prod at prod (the D27 avoidance)', () => {
+        const run = (access: 'test' | 'prep' | 'prod') =>
+          runHelperFile({
+            path: ANCIENT_PATH,
+            name: 'sdkAwsLambdaEnvAccessAncient',
+            access,
+          })();
+        expect(run('prod')).toBe('prod');
+        expect(run('prep')).toBe('dev');
+        expect(run('test')).toBe('dev');
+      });
+    });
+
+    when('[t1] the contemp target runs under each access', () => {
+      then('it returns the access direct', () => {
+        const run = (access: 'test' | 'prep' | 'prod') =>
+          runHelperFile({
+            path: CONTEMP_PATH,
+            name: 'sdkAwsLambdaEnvAccessContemp',
+            access,
+          })();
+        expect(run('prod')).toBe('prod');
+        expect(run('prep')).toBe('prep');
+        expect(run('test')).toBe('test');
+      });
+    });
+  });
+});

package/dist/practices/environments/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,55 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`environments practice — the EnvAccess helper primitive (north-star clamp) given: [case1] the shipped helper templates — their source shape when: [t0] the contents are read then: the ancient file source matches snapshot (a structural edit vibechecks in a review): sdkAwsLambdaEnvAccessAncient.ts source 1`] = `
+"import type { EnvironmentAccessTier } from 'sdk-environment';
+
+import { envStatic } from '@src/utils/environment';
+
+/**
+ * .what = the fleet slug a caller addresses a peer lambda by.
+ * .why  = it is an access (\`test | prep | prod\`) OR the legacy \`dev\` slug an
+ *         ancient peer still publishes under. a first-class \`dev\` member keeps the slug
+ *         compiler-tracked — never an \`as\`-cast that lies a \`dev\` value through a type
+ *         that forbids it (the exact silent fault this transition exists to kill).
+ */
+export type LambdaEnvSlug = EnvironmentAccessTier | 'dev';
+
+/**
+ * .what = address an **ancient** peer — one that publishes \`-dev-\` only.
+ * .why  = \`askLambdaEndpoint\` builds its target as \`\${service}-\${access}-\${function}\`.
+ *         an ancient peer publishes under a legacy \`dev\` slug that disagrees with
+ *         **access** (\`test | prep | prod\`) below prod (\`access=prep\` ⟺ deployed name
+ *         \`dev\`). so a caller emits the legacy \`dev\` slug below prod, because that is the
+ *         only name the peer publishes. \`prod\` maps to \`prod\` on both.
+ * .note = the helper choice IS the migration ledger: \`grep AccessAncient\` lists every
+ *         peer still published under \`-dev-\` only. once zero remain, this ancient branch
+ *         — and the divergent \`dev\` slug — retire together, alongside its contemp
+ *         counterpart \`sdkAwsLambdaEnvAccessContemp\`. the return type is \`LambdaEnvSlug\`,
+ *         so the \`dev\` slug flows with a compiler-tracked type — no cast, no lie.
+ */
+export const sdkAwsLambdaEnvAccessAncient = (
+  input?: { access: EnvironmentAccessTier | null },
+): LambdaEnvSlug => {
+  const access = input?.access ?? envStatic.access;
+  return access === 'prod' ? 'prod' : 'dev';
+};
+"
+`;
+
+exports[`environments practice — the EnvAccess helper primitive (north-star clamp) given: [case1] the shipped helper templates — their source shape when: [t0] the contents are read then: the contemp file source matches snapshot: sdkAwsLambdaEnvAccessContemp.ts source 1`] = `
+"import type { EnvironmentAccessTier } from 'sdk-environment';
+
+import { envStatic } from '@src/utils/environment';
+
+/**
+ * .what = address a **contemp** peer, or **self** — one that publishes \`-prep-\`.
+ * .why  = emit the access direct; no bridge is needed once the callee is
+ *         published under the access slug. the contemp counterpart of
+ *         \`sdkAwsLambdaEnvAccessAncient\`: as peers migrate, a caller flips
+ *         \`Ancient → Contemp\` per peer, and \`grep AccessAncient\` at zero is the exit.
+ */
+export const sdkAwsLambdaEnvAccessContemp = (
+  input?: { access: EnvironmentAccessTier | null },
+): EnvironmentAccessTier => input?.access ?? envStatic.access;
+"
+`;

package/dist/practices/environments/bad-practices/old-dev-scripts/package.json.declapract.ts

@@ -26,10 +26,12 @@ export const check: FileCheckFunction = (contents) => {
  *
  * handles both `:dev` at end (deploy:dev) and `:dev:` in middle (build:dev:ios)
  *
- * .note = only renames script NAMES, not VALUES. script values may still reference
- *         `--stage dev` for infrastructure naming (cloudformation stacks stay named
- *         `$service-dev`). the serverless package.json handles this via SLS_STAGE
- *         mapping. see brief: define.infrastructure-dev-vs-application-prep.md
+ * .note = renames script NAMES only; script VALUES pass through untouched. this practice
+ *         does not own the deploy-slug axis: a serverless deploy command must derive its
+ *         slug from ACCESS (`--stage "${SLS_STAGE:-}"`, where SLS_STAGE = ACCESS with a
+ *         prep→dev bridge for the ancient fleet), never a hardcoded divergent `--stage dev`.
+ *         that value-axis migration is the serverless practice's STAGE→ACCESS rewrite. see
+ *         rule.forbid.stage-term.md + define.infrastructure-dev-vs-application-prep.md
  */
 export const fix: FileFixFunction = (contents) => {
   if (!contents) return {};

package/dist/practices/environments/bad-practices/old-stage-enum/.declapract.integration.test.ts

@@ -0,0 +1,133 @@
+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 ceiling
+jest.setTimeout(180_000);
+
+/**
+ * .what = end-to-end proof of the old-stage-enum migration, run through the REAL declapract apply
+ *   pipeline against a genTempDir clone of a consumer repo. per
+ *   rule.require.declapract-integration-tests, a fix that TRANSFORMS a file (parser-driven splice)
+ *   owes a pipeline test — a unit test of the exported `fix` never exercises the glob -> file match.
+ * .why = the fix migrates the two UNAMBIGUOUS members (`Stage.PRODUCTION` -> `'prod'`,
+ *   `Stage.TEST` -> `'test'`) and LEAVES `Stage.DEVELOPMENT` in place (axis-ambiguous, never
+ *   guessed), so the check stays red until a human decides the axis. it uses the typescript PARSER,
+ *   not a hand-rolled lexer, so an enum mention inside a regex literal or a template-literal's static
+ *   text is that token's own text — never a property access — and is preserved byte-for-byte.
+ * .note = the target file is snapshotted in full (before AND after), so a reviewer can eyeball the
+ *   exact end-state, per rule.require.declapract-integration-tests.
+ * .teeth = the input holds `Stage.PRODUCTION` + `Stage.TEST` (migrated), `Stage.DEVELOPMENT` (left
+ *   in place), a regex literal `/Stage\.PRODUCTION/` and a template-static `Stage.TEST` (both
+ *   preserved). the after-state proves all of these — and that NO `/s'prod'/`-class corruption ever
+ *   lands in the emitted file (the whole reason the lexer was retired for the parser).
+ */
+describe('old-stage-enum migration', () => {
+  given('[case1] a repo with Stage.* enum references in a src file', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-old-stage-enum',
+      clone: './src/practices/environments/bad-practices/old-stage-enum/.test/assets/demo-repo-with-stage-enum',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/environments/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const targetPath = 'src/logic/getDeployTarget.ts';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyMigrate = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'environments',
+        file: targetPath,
+      });
+
+    when('[t0] the migration input (before any fix)', () => {
+      then('the src file holds the raw Stage.* references + matches snapshot', async () => {
+        const before = await read(targetPath);
+        expect(before).toContain('Stage.PRODUCTION');
+        expect(before).toContain('Stage.TEST');
+        expect(before).toContain('Stage.DEVELOPMENT');
+        expect(before).toMatchSnapshot('getDeployTarget.ts — before');
+      });
+    });
+
+    when('[t1] the old-stage-enum fix is applied', () => {
+      useThen('migrate the unambiguous Stage members', async () => applyMigrate());
+
+      then(
+        'the unambiguous members migrate, DEVELOPMENT + non-code mentions survive, and it matches snapshot',
+        async () => {
+          const after = await read(targetPath);
+
+          // the two unambiguous PROPERTY ACCESSES migrate to their string literals
+          expect(after).toContain("export const prodStage = 'prod';");
+          expect(after).toContain("export const testStage = 'test';");
+
+          // the axis-ambiguous member is LEFT in place, never guessed
+          expect(after).toContain('Stage.DEVELOPMENT');
+
+          // the import stays, because a live Stage.DEVELOPMENT reference still needs it
+          expect(after).toContain("import { Stage } from 'sdk-environment';");
+
+          // the regex literal + template-static mentions are NOT property accesses, so the parser
+          // never splices them — they survive byte-for-byte (a splice into the regex would corrupt
+          // this exact text span, so its survival IS the pipeline-grain corruption-safety proof;
+          // the hard-position corruption cases are clamped in the unit suite)
+          expect(after).toContain('/Stage\\.PRODUCTION/');
+          expect(after).toContain('deploy target: Stage.TEST');
+          // the migrated VALUE-SPLICES appear exactly where the property accesses were, and nowhere
+          // else. count the `= '<slug>'` splice form (not a bare `'<slug>'`), because the review
+          // marker's option-list carries `'test'|'prep'|'prod'` as prose — those have no `= ` prefix,
+          // so this count clamps the splices alone and stays 1 despite the marker (r9.b2).
+          expect((after.match(/= 'prod'/g) || []).length).toBe(1);
+          expect((after.match(/= 'test'/g) || []).length).toBe(1);
+
+          // r9.b2: the fix marks the axis-ambiguous line with a `// @declapract:review:` comment on
+          // the line DIRECTLY ABOVE the reference, so a red plan names WHERE + WHAT to pick by hand.
+          // find the CODE line (the real property access), not the marker — the marker's own text
+          // also holds `Stage.DEVELOPMENT`, so filter it out by the `@declapract:review` tag.
+          const lines = after.split('\n');
+          const devCodeLineIndex = lines.findIndex(
+            (line) =>
+              line.includes('Stage.DEVELOPMENT') &&
+              !line.includes('@declapract:review'),
+          );
+          expect(devCodeLineIndex).toBeGreaterThan(0);
+          expect(lines[devCodeLineIndex - 1]).toContain('@declapract:review');
+          expect(lines[devCodeLineIndex - 1]).toContain(
+            "access ('test'|'prep'|'prod')",
+          );
+
+          // full content, for the reviewer's eye
+          expect(after).toMatchSnapshot('getDeployTarget.ts — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // Stage.DEVELOPMENT remains a live property access, so the check still detects it and the fix
+      // still runs — but no unambiguous member is left to migrate and the import stays, so the
+      // second apply changes zero bytes (per rule.require.idempotent-fixes).
+      const passes = useThen(
+        'a second apply over its own output',
+        async () => {
+          const before = await read(targetPath); // post-first-migrate
+          await applyMigrate(); // second apply
+          const after = await read(targetPath);
+          return { before, after };
+        },
+      );
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/practices/environments/bad-practices/old-stage-enum/.test/assets/demo-repo-with-stage-enum/declapract.use.yml

@@ -0,0 +1,8 @@
+# .note = the declarations dir is symlinked by the test (holds declapract.declare.yml + a
+#         practices/environments symlink to the real practice), so the consumer's own src/ tree
+#         stays free to hold the target .ts file the src/**/*.ts glob matches.
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'

package/dist/practices/environments/bad-practices/old-stage-enum/.test/assets/demo-repo-with-stage-enum/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

package/dist/practices/environments/bad-practices/old-stage-enum/.test/assets/demo-repo-with-stage-enum/src/logic/getDeployTarget.ts

@@ -0,0 +1,15 @@
+import { Stage } from 'sdk-environment';
+
+// unambiguous property accesses — migrated to their string literals
+export const prodStage = Stage.PRODUCTION;
+export const testStage = Stage.TEST;
+
+// axis-ambiguous — LEFT in place, never guessed (a human decides the axis)
+export const devStage = Stage.DEVELOPMENT;
+
+// a regex literal that MENTIONS the enum text — the parser classifies it as a
+// RegularExpressionLiteral, never a property access, so it must survive byte-for-byte
+export const stageMatcher = /Stage\.PRODUCTION/;
+
+// a template literal whose STATIC text mentions the enum — also never spliced
+export const label = `deploy target: Stage.TEST`;

package/dist/practices/environments/bad-practices/old-stage-enum/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,40 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`old-stage-enum migration given: [case1] a repo with Stage.* enum references in a src file when: [t0] the migration input (before any fix) then: the src file holds the raw Stage.* references + matches snapshot: getDeployTarget.ts — before 1`] = `
+"import { Stage } from 'sdk-environment';
+
+// unambiguous property accesses — migrated to their string literals
+export const prodStage = Stage.PRODUCTION;
+export const testStage = Stage.TEST;
+
+// axis-ambiguous — LEFT in place, never guessed (a human decides the axis)
+export const devStage = Stage.DEVELOPMENT;
+
+// a regex literal that MENTIONS the enum text — the parser classifies it as a
+// RegularExpressionLiteral, never a property access, so it must survive byte-for-byte
+export const stageMatcher = /Stage\\.PRODUCTION/;
+
+// a template literal whose STATIC text mentions the enum — also never spliced
+export const label = \`deploy target: Stage.TEST\`;
+"
+`;
+
+exports[`old-stage-enum migration given: [case1] a repo with Stage.* enum references in a src file when: [t1] the old-stage-enum fix is applied then: the unambiguous members migrate, DEVELOPMENT + non-code mentions survive, and it matches snapshot: getDeployTarget.ts — after 1`] = `
+"import { Stage } from 'sdk-environment';
+
+// unambiguous property accesses — migrated to their string literals
+export const prodStage = 'prod';
+export const testStage = 'test';
+
+// axis-ambiguous — LEFT in place, never guessed (a human decides the axis)
+// @declapract:review: Stage.DEVELOPMENT is axis-ambiguous — pick by hand: an access ('test'|'prep'|'prod') or the deploy-stage slug ('dev'), then delete this marker
+export const devStage = Stage.DEVELOPMENT;
+
+// a regex literal that MENTIONS the enum text — the parser classifies it as a
+// RegularExpressionLiteral, never a property access, so it must survive byte-for-byte
+export const stageMatcher = /Stage\\.PRODUCTION/;
+
+// a template literal whose STATIC text mentions the enum — also never spliced
+export const label = \`deploy target: Stage.TEST\`;
+"
+`;