declapract-typescript-ehmpathy 0.49.11 → 0.49.13

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

@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps that the ssm-off-terraform wish declares the two cicd credentials as SLASH paths
+ *         with NO tier segment, while the crud credential keeps its dotted tier-scoped name.
+ * .why  = the prod plan role pins its ONE `kms:Decrypt` exception to a slash arn
+ *         (`parameter/*​/svc-*​/database/role/cicd/for-plan/*`) that needs literal `/` separators
+ *         and omits a tier (the aws ACCOUNT separates prep from prod, never the name). a dotted
+ *         name cannot match that arn, so the plan role gets ciphertext or a denial, forever, and
+ *         a repo does not find out until prod (#591). the shipped `ahbode/svc-home-services` proved
+ *         the slash form; this clamp ports it into the practice so no consumer inherits the dotted
+ *         cicd name again. crud is pinned by NO policy, so it keeps its dotted name and this clamp
+ *         leaves it alone.
+ * .teeth = revert either cicd entry to the dotted `${namespace}.database.role.cicd.for-plan.password`
+ *          form and the slash-present case reddens; the no-dotted-cicd case reddens too.
+ * .note = `.declapract.test.ts` = this repo's UNIT-test marker; at the practice ROOT (not under
+ *         best-practice/), so it is neither loaded as a declaration nor copied to a consumer.
+ */
+
+// anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different cwd.
+// from this file (src/practices/persist-with-rds/) the best-practice tree is one segment down.
+const paramsPath = join(
+  __dirname,
+  'best-practice/provision/aws/resources.parameters.ts',
+);
+
+describe('persist-with-rds ssm cicd param names are slash-path, tierless', () => {
+  const source = readFileSync(paramsPath, 'utf8');
+
+  given('[case1] the two cicd credentials', () => {
+    when('[t0] resources.parameters.ts is read', () => {
+      then('for-plan is a slash path, byte-identical to the iam pin', () => {
+        expect(source).toContain('/database/role/cicd/for-plan/password');
+      });
+
+      then('for-apply is a slash path', () => {
+        expect(source).toContain('/database/role/cicd/for-apply/password');
+      });
+
+      then('neither cicd name is dotted (a dotted name cannot match the arn pin)', () => {
+        expect(source).not.toContain('.database.role.cicd.for-plan');
+        expect(source).not.toContain('.database.role.cicd.for-apply');
+      });
+
+      then('the cicd slash path carries no tier segment (project joins /database directly)', () => {
+        // /{org}/{project}/database/... — a tier segment would split project from database
+        expect(source).toContain('projectName}/database/role/cicd/for-plan/password');
+        expect(source).not.toContain('${slug}/database/role/cicd');
+      });
+
+      // the emitted param-name lines are the caller-faced contract: snapshot them so a reword that
+      // keeps the slash tokens green (a re-templated prefix, a moved tier segment) reddens a vibecheck.
+      then('the emitted cicd + crud param-name lines match snapshot', () => {
+        const nameLines = source
+          .split('\n')
+          .filter((line) => line.includes('database/role/cicd') || line.includes('database.role.'))
+          .map((line) => line.trim());
+        expect(nameLines).toMatchSnapshot('ssm cicd + crud param names');
+      });
+    });
+  });
+
+  given('[case2] the crud credential', () => {
+    when('[t0] resources.parameters.ts is read', () => {
+      then('crud keeps its dotted tier-scoped name (no policy pins it)', () => {
+        expect(source).toContain('${namespace}.database.role.crud.password');
+      });
+    });
+  });
+});

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/testdb-preflight-failloud.declapract.integration.test.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps the testdb preflight probe (#589) to fail LOUD, not hide
+ * .why  = the prior probe swallowed psql stderr (`> /dev/null 2>&1`), printed one
+ *         hardcoded diagnosis regardless of the true cause, and passed the secret
+ *         inline in the connection string (which leaks it to `ps`). so a bad
+ *         password, a port conflict, and an image build failure all read the same,
+ *         and the real cause never surfaced on timeout.
+ * .teeth = revert the fix (restore `> /dev/null 2>&1` + the inline password + the
+ *          single hardcoded line) and each `then` below goes red.
+ * .note  = a `.declapract.test.ts` at the practice ROOT is a UNIT-test marker — it is
+ *          not loaded as a declaration nor copied to a consumer. it anchors on
+ *          __dirname (not process.cwd()) so it reads the shipped template directly.
+ */
+
+const source = readFileSync(
+  join(
+    __dirname,
+    'best-practice/provision/docker/testdb/wait-for-postgres.sh',
+  ),
+  'utf8',
+);
+
+describe('testdb preflight fails loud (#589)', () => {
+  given('the shipped wait-for-postgres preflight probe', () => {
+    when('[t0] it runs the psql probe', () => {
+      then('it does not swallow the probe stderr to /dev/null', () => {
+        expect(source).not.toContain('/dev/null');
+      });
+
+      then('it captures the probe stderr for surfacing on timeout', () => {
+        expect(source).toContain('lasterr=$(psql');
+        expect(source).toContain('2>&1');
+      });
+    });
+
+    when('[t1] the probe fails past the timeout', () => {
+      then('it echoes the captured last error to stderr', () => {
+        expect(source).toContain('>&2 echo "$lasterr"');
+      });
+
+      then('it no longer prints only the one hardcoded diagnosis', () => {
+        expect(source).not.toContain('postgres too long');
+      });
+    });
+
+    when('[t2] it authenticates to postgres', () => {
+      then('it passes the secret via PGPASSWORD, not inline in the connstring', () => {
+        // the secret rides PGPASSWORD (never the connstring, which leaks to `ps`), and
+        // the env read uses the safe-default form per rule.require.safe-shell-vars
+        expect(source).toContain('export PGPASSWORD="${POSTGRES_PASSWORD:-}"');
+        expect(source).not.toContain('password=$POSTGRES_PASSWORD');
+      });
+    });
+
+    when('[t3] a consumer shell runs it under nounset', () => {
+      then('it opens with set -eu so an unset env fails loud, not silent', () => {
+        expect(source).toContain('set -eu');
+      });
+
+      then('it reads every optional env var with the ${VAR:-} default form', () => {
+        // no bare "$VAR" env read survives: under set -u a bare read is an unbound-variable
+        // crash; the :- default keeps a loud, correct connect attempt instead
+        expect(source).not.toContain('"$POSTGRES_PASSWORD"');
+        expect(source).not.toContain('dbname=$POSTGRES_DB ');
+        expect(source).toContain('${POSTGRES_DB:-}');
+      });
+    });
+
+    when('[t4] the shipped probe is vibechecked as a whole', () => {
+      then('the emitted wait-for-postgres.sh matches snapshot', () => {
+        // snapshot the whole shipped probe so a reword that keeps the pinned tokens green
+        // (a reshaped psql invocation, a rephrased echo, a moved PGPASSWORD export) reddens a
+        // vibecheck in review — the tokens above prove presence, this proves the exact text
+        // (rule.require.contract-snapshot-exhaustiveness)
+        expect(source).toMatchSnapshot('wait-for-postgres.sh preflight probe');
+      });
+    });
+  });
+});

package/dist/.test/assets/cicd-service/declarations/useCases.yml

@@ -0,0 +1,13 @@
+# minimal use cases for the cicd-service provision.yml (D28) pipeline test.
+# .why = the provision.yml `contents` branch fires on
+#        `context.projectPractices.includes('persist-with-rds')`. these two lean use cases carry the
+#        one signal the branch reads (rds present vs absent) while each evaluates only 1-2 practices —
+#        not the ~40 of the real declarations tree, which blows the jest hook timeout.
+use-cases:
+  service-without-rds:
+    practices:
+      - cicd-service
+  service-with-rds:
+    practices:
+      - cicd-service
+      - persist-with-rds

package/dist/.test/assets/environments/declarations/declapract.declare.yml

@@ -0,0 +1,4 @@
+# minimal declarations for the environments practice integration test
+declare:
+  practices: practices
+  use-cases: useCases.yml

package/dist/.test/assets/environments/declarations/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/.test/assets/environments/declarations/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/.test/assets/environments/declarations/practices/environments/bad-practices/old-dev-scripts/package.json.declapract.ts

@@ -0,0 +1,59 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects package.json scripts with `:dev` as a segment
+ * .why = standardizing on `prep` over `dev` for pre-production environment naming
+ *
+ * matches both `:dev` at end (deploy:dev) and `:dev:` in middle (build:dev:ios)
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (!contents) throw new Error('fine, does not match bad practice');
+  const parsedContents = JSON.parse(contents);
+  const scripts = parsedContents.scripts ?? {};
+
+  // check if any script name contains :dev as a segment (either :dev at end or :dev: in middle)
+  const devScripts = Object.keys(scripts).filter(
+    (key) => key.endsWith(':dev') || key.includes(':dev:'),
+  );
+  if (devScripts.length > 0) return; // matches bad practice
+
+  throw new Error('fine, no scripts with :dev segment');
+};
+
+/**
+ * .what = renames scripts from `:dev` segment to `:prep` segment
+ * .why = standardizing on `prep` over `dev` for pre-production environment naming
+ *
+ * handles both `:dev` at end (deploy:dev) and `:dev:` in middle (build:dev:ios)
+ *
+ * .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 {};
+  const parsedContents = JSON.parse(contents);
+  const scripts = parsedContents.scripts ?? {};
+
+  // find scripts with :dev segment and create renamed versions
+  const updatedScripts = { ...scripts };
+  for (const [key, value] of Object.entries(scripts)) {
+    if (key.endsWith(':dev') || key.includes(':dev:')) {
+      // replace :dev: in middle and :dev at end with :prep
+      const newKey = key.replace(/:dev:/g, ':prep:').replace(/:dev$/, ':prep');
+      updatedScripts[newKey] = value; // add :prep version
+      updatedScripts[key] = undefined; // remove :dev version
+    }
+  }
+
+  return {
+    contents: JSON.stringify(
+      { ...parsedContents, scripts: updatedScripts },
+      null,
+      2,
+    ),
+  };
+};

package/dist/.test/assets/environments/declarations/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/.test/assets/environments/declarations/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/.test/assets/environments/declarations/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/.test/assets/environments/declarations/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/.test/assets/environments/declarations/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\`;
+"
+`;