declapract-typescript-ehmpathy 0.49.10 → 0.49.12

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\`;
+"
+`;

package/dist/practices/environments/bad-practices/old-stage-enum/src/<star><star>/<star>.ts.declapract.ts

@@ -1,37 +1,304 @@
 import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import * as ts from 'typescript';
+
+// `Stage.DEVELOPMENT` (value `'dev'`) was overloaded across two axes: the access
+// (→ 'prep') and the deploy-stage slug (→ 'dev'). a rewrite cannot know which axis a given
+// occurrence sits on. so the fix NEVER guesses it: `Stage.PRODUCTION` and `Stage.TEST` are
+// unambiguous and migrate to `'prod'` / `'test'`, but `Stage.DEVELOPMENT` is LEFT IN PLACE.
+// because it is left, `check` still detects it, so `declapract plan` stays RED until a
+// human decides the axis by hand — the loud, plan-visible "leave the file in violation"
+// signal guard #3 demands, never a green plan that hides a possibly-wrong `'prep'` guess.
+//
+// a red plan alone does not say WHERE the unsettled reference sits or WHAT the human must
+// do, so the fix also inserts a `// @declapract:review:` COMMENT directly above each
+// `Stage.DEVELOPMENT` line. the comment names the file location (it rides the very line) and
+// the choice to make (an access, or the deploy-stage slug). it is a COMMENT, not a value
+// splice — the real `Stage.DEVELOPMENT` property access is untouched — so it neither guesses a
+// value NOR clears the check (a comment is not a property-access node, so the parser still
+// detects the real reference and `plan` stays red). idempotent: a line that already holds the
+// marker is skipped, so a second `fix` pass adds no second marker.
+//
+// this pairs with, and is deliberately UNLIKE, an earlier shape that rewrote
+// `Stage.DEVELOPMENT` → `'prep' /* marker */`. that VALUE-SPLICE shape (a) still GUESSED
+// `'prep'` (a deploy-stage occurrence, whose correct value is `'dev'`, was silently
+// mis-migrated), and (b) once it rewrote the reference, the check no longer matched, so `plan`
+// read CLEAN with a possibly-wrong value — the exact silent-break class this wish exists to
+// retire. the COMMENT marker forecloses both: no value is emitted (no guess), and the
+// still-red plan cannot hide the unsettled axis — it now carries the pointer + the hint.
+
+/**
+ * .what = find every `Stage.<member>` reference in real code, via the typescript parser. three
+ *         node shapes carry it: a value-position PROPERTY ACCESS (`Stage.PRODUCTION`), a
+ *         type-position QUALIFIED NAME (`x: Stage.PRODUCTION`), and a bracket ELEMENT ACCESS with a
+ *         string-literal key (`Stage['PRODUCTION']`). all three name the same enum member and must
+ *         migrate together.
+ * .why  = the parser classifies every token exactly, so a `Stage.PRODUCTION` that sits inside a
+ *         comment, a string literal, a template literal's static text, or a REGEX literal is that
+ *         token's own text — never one of these three nodes — and is therefore invisible to this
+ *         walk BY CONSTRUCTION. a live `${Stage.X}` interpolation, by contrast, IS a property
+ *         access and is found. this forecloses the whole "a value spliced into a non-code span"
+ *         corruption class that a hand-rolled character mask could only chase one token position
+ *         at a time — a `/` after `}`/`)`/`]`, a regex nested in a `${...}`, a brace inside an
+ *         interpolated string — each a fresh hole. the parser has none. and the type + bracket
+ *         positions close the mirror hole: a `Stage.DEVELOPMENT` in a type annotation or a
+ *         `Stage['DEVELOPMENT']` bracket lookup is just as axis-ambiguous as the value form, so it
+ *         too must keep `check` red until a human settles it.
+ * .note = a `Stage.X` is matched wherever the top-level identifier `Stage` is accessed. a consumer
+ *         that shadows the enum with its own object literally named `Stage` is an accepted,
+ *         disclosed residual — the org-standard enum name is not re-used locally in practice.
+ */
+type StageAccess = { member: string; start: number; end: number };
+
+const getStageAccesses = (contents: string): StageAccess[] => {
+  const source = ts.createSourceFile(
+    'stage-scan.ts',
+    contents,
+    ts.ScriptTarget.Latest,
+    true, // setParentNodes — so getStart(source) reads real offsets
+    ts.ScriptKind.TS,
+  );
+  const accesses: StageAccess[] = [];
+  const visit = (node: ts.Node): void => {
+    // value position: `Stage.PRODUCTION`
+    if (
+      ts.isPropertyAccessExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === 'Stage'
+    )
+      accesses.push({
+        member: node.name.text,
+        start: node.getStart(source),
+        end: node.getEnd(),
+      });
+
+    // type position: `x: Stage.PRODUCTION` (a QualifiedName, `left.right`)
+    if (
+      ts.isQualifiedName(node) &&
+      ts.isIdentifier(node.left) &&
+      node.left.text === 'Stage'
+    )
+      accesses.push({
+        member: node.right.text,
+        start: node.getStart(source),
+        end: node.getEnd(),
+      });
+
+    // bracket position: `Stage['PRODUCTION']` (an ElementAccess with a string-literal key)
+    if (
+      ts.isElementAccessExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === 'Stage' &&
+      ts.isStringLiteral(node.argumentExpression)
+    )
+      accesses.push({
+        member: node.argumentExpression.text,
+        start: node.getStart(source),
+        end: node.getEnd(),
+      });
+
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return accesses;
+};
+
+// only PRODUCTION + TEST are unambiguous (prod → 'prod', test → 'test'). DEVELOPMENT is
+// axis-ambiguous and is deliberately NOT mapped here — it is never rewritten.
+const replacementFor = (member: string): string =>
+  member === 'PRODUCTION' ? "'prod'" : "'test'";
+
+/**
+ * .what = replace every unambiguous `Stage.PRODUCTION`/`Stage.TEST` PROPERTY ACCESS with its
+ *         string literal, spliced into the ORIGINAL at the parser's node offsets — so a comment,
+ *         string, template-static, or regex mention is preserved byte-for-byte (it is not a
+ *         property-access node, so it is never in the splice set). `Stage.DEVELOPMENT` is never in
+ *         the set, so it is left in place (never guessed).
+ * .why  = keeps `fix` a what-not-how read; the splice + offset math lives in this one op.
+ */
+const withUnambiguousStageRefsReplaced = (input: {
+  contents: string;
+}): string => {
+  const accesses = getStageAccesses(input.contents)
+    .filter(
+      (access) => access.member === 'PRODUCTION' || access.member === 'TEST',
+    )
+    .sort((a, b) => a.start - b.start);
+  // a pure fold over the sorted accesses — carries { spliced, last } with no mutable accumulator
+  // (rule.forbid.maintenance-hazards). each step appends the gap since the prior splice plus this
+  // member's literal, then advances the cursor past the property access.
+  const { spliced, last } = accesses.reduce(
+    (acc, access) => ({
+      spliced:
+        acc.spliced +
+        input.contents.slice(acc.last, access.start) +
+        replacementFor(access.member),
+      last: access.end,
+    }),
+    { spliced: '', last: 0 },
+  );
+  return spliced + input.contents.slice(last);
+};
+
+/**
+ * .what = drop the now-unused `Stage` named-import specifier — ONLY when no real-code `Stage.`
+ *         reference remains. done via the parser, so the `Stage` specifier is dropped wherever it
+ *         sits in the named-bindings list — first (`{ Stage, A }`), last (`{ A, Stage }`), or MIDDLE
+ *         (`{ A, Stage, B }`) — and the surviving specifiers are preserved verbatim. when `Stage`
+ *         is the sole specifier, the whole import statement (and its trailing newline) is removed.
+ * .why  = a leftover `Stage.DEVELOPMENT` still needs the import to compile, so the import is kept
+ *         while any real reference survives; keeps `fix` a what-not-how read. the parser finds the
+ *         specifier by its position in the list, so a mid-list `Stage` — which a first/last-only
+ *         regex silently skips, leaving a dead import that fails the lint — is dropped like any
+ *         other. a comment/string mention of `Stage` is not an import specifier, so it is untouched.
+ */
+const withUnusedStageImportRemoved = (input: { contents: string }): string => {
+  if (getStageAccesses(input.contents).length > 0) return input.contents;
+
+  const source = ts.createSourceFile(
+    'stage-import-scan.ts',
+    input.contents,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+
+  // find the `Stage` named-import specifier + the NamedImports list it sits in, via the parser
+  const found = source.statements.reduce<{
+    named: ts.NamedImports;
+    decl: ts.ImportDeclaration;
+  } | null>((hit, statement) => {
+    if (hit) return hit;
+    if (!ts.isImportDeclaration(statement)) return null;
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) return null;
+    const hasStage = bindings.elements.some(
+      (specifier) => specifier.name.text === 'Stage',
+    );
+    return hasStage ? { named: bindings, decl: statement } : null;
+  }, null);
+
+  // no `Stage` specifier to drop → leave the file byte-for-byte
+  if (!found) return input.contents;
+
+  // the survivors — every specifier that is not `Stage`, kept verbatim by their source text
+  const survivors = found.named.elements.filter(
+    (specifier) => specifier.name.text !== 'Stage',
+  );
+
+  // sole specifier → remove the whole import statement, including its trailing newline
+  if (survivors.length === 0) {
+    const declStart = found.decl.getStart(source);
+    const declEnd = found.decl.getEnd();
+    const withTrailingNewline =
+      input.contents[declEnd] === '\n' ? declEnd + 1 : declEnd;
+    return (
+      input.contents.slice(0, declStart) +
+      input.contents.slice(withTrailingNewline)
+    );
+  }
+
+  // otherwise, rebuild the named-bindings list from the survivors + splice it over the original
+  const rebuilt = `{ ${survivors
+    .map((specifier) => specifier.getText(source))
+    .join(', ')} }`;
+  return (
+    input.contents.slice(0, found.named.getStart(source)) +
+    rebuilt +
+    input.contents.slice(found.named.getEnd())
+  );
+};
+
+// the review pointer inserted above each axis-ambiguous `Stage.DEVELOPMENT` line. it names WHERE
+// (it rides the reference's line) and WHAT (pick an access, or the deploy-stage slug). the
+// literal `Stage.DEVELOPMENT` text here sits in a `//` comment, so the parser never reads it as a
+// property access — it never keeps the check red on its own, and it never adds a second real ref.
+const REVIEW_MARKER =
+  "// @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";
+
+/**
+ * .what = insert a `// @declapract:review:` comment above each `Stage.DEVELOPMENT` line, once.
+ * .why  = the fix leaves `Stage.DEVELOPMENT` in place so `plan` stays red (guard #3), but a bare
+ *         red plan names neither the file/line nor the axis to pick. the comment supplies both,
+ *         without a value guess and without a cleared check (a comment is not a property access).
+ *         each line is marked at most once (idempotent), so a re-apply is a no-op.
+ */
+const withDevelopmentAxisReviewMarker = (input: {
+  contents: string;
+}): string => {
+  // the start offset of every line that holds a real `Stage.DEVELOPMENT` property access
+  const lineStarts = Array.from(
+    new Set(
+      getStageAccesses(input.contents)
+        .filter((access) => access.member === 'DEVELOPMENT')
+        .map(
+          (access) => input.contents.lastIndexOf('\n', access.start - 1) + 1,
+        ),
+    ),
+  ).sort((a, b) => b - a); // splice bottom-up so lower offsets stay valid
+
+  // a pure fold over the bottom-up line starts — carries the text-so-far with no mutable
+  // accumulator (rule.forbid.maintenance-hazards). each step splices the marker above its line, or
+  // returns the text unchanged when the contiguous comment block just above already holds the
+  // marker (idempotent).
+  return lineStarts.reduce((out, lineStart) => {
+    const indent = out.slice(lineStart).match(/^[ \t]*/)?.[0] ?? '';
+
+    // idempotent guard: walk up the CONTIGUOUS `//` comment block directly above this line and skip
+    // if any of its lines already holds the marker. a single-line check above would miss a marker
+    // that a reformat pushed one line up (e.g. a blank-less comment now sits between it and the
+    // reference), so it would double-insert. the block scan sees the whole comment run.
+    const priorBlockHoldsMarker = (() => {
+      const walk = (cursor: number): boolean => {
+        if (cursor === 0) return false;
+        const priorStart = out.lastIndexOf('\n', cursor - 2) + 1;
+        const priorLine = out.slice(priorStart, cursor - 1);
+        if (priorLine.includes('@declapract:review')) return true;
+        // stop at the first non-comment line — the comment block ends there
+        if (!priorLine.trimStart().startsWith('//')) return false;
+        return walk(priorStart);
+      };
+      return walk(lineStart);
+    })();
+    if (priorBlockHoldsMarker) return out;
+
+    return (
+      out.slice(0, lineStart) +
+      indent +
+      REVIEW_MARKER +
+      '\n' +
+      out.slice(lineStart)
+    );
+  }, input.contents);
+};
 
 export const check: FileCheckFunction = (contents) => {
-  if (!contents) throw new Error('does not match bad practice');
+  if (!contents)
+    throw new Error(
+      'does not match bad practice: file has no contents to scan for a Stage.* enum reference',
+    );
 
-  // check for Stage enum usage
-  if (
-    contents.includes('Stage.PRODUCTION') ||
-    contents.includes('Stage.DEVELOPMENT') ||
-    contents.includes('Stage.TEST')
-  )
-    return; // bad practice detected
+  // detect a `Stage.<member>` PROPERTY ACCESS in real code, via the parser. a comment/string/
+  // regex/template-static mention is not a property-access node, so it never keeps the check red
+  // after the fix (it would never clear). the check detects ALL three members — a DEVELOPMENT
+  // reference must keep the check red so `plan` stays visibly unsettled.
+  const accesses = getStageAccesses(contents);
+  if (accesses.length > 0) return; // bad practice detected
 
-  throw new Error('does not match bad practice');
+  throw new Error(
+    'does not match bad practice: no Stage.PRODUCTION|DEVELOPMENT|TEST property access found in real code (a comment/string/regex/template-static mention is ignored)',
+  );
 };
 
 export const fix: FileFixFunction = (contents) => {
   if (!contents) return { contents };
 
-  const fixed = contents
-    // replace enum values with string literals
-    .replace(/Stage\.PRODUCTION/g, "'prod'")
-    .replace(/Stage\.DEVELOPMENT/g, "'prep'")
-    .replace(/Stage\.TEST/g, "'test'")
-    // remove Stage import if no longer used
-    .replace(/import\s*\{\s*Stage\s*\}\s*from\s*['"][^'"]+['"];\n?/g, '')
-    .replace(
-      /import\s*\{\s*([^}]*),\s*Stage\s*\}\s*from/g,
-      'import { $1 } from',
-    )
-    .replace(
-      /import\s*\{\s*Stage\s*,\s*([^}]*)\}\s*from/g,
-      'import { $1 } from',
-    );
+  // migrate the unambiguous members, mark each axis-ambiguous `Stage.DEVELOPMENT` with a review
+  // pointer, then drop the Stage import when no reference remains. `Stage.DEVELOPMENT` is left in
+  // place (never guessed), so `check` still detects it and `plan` stays red until a human decides
+  // the axis — now with a `// @declapract:review:` line naming where + what.
+  const spliced = withUnambiguousStageRefsReplaced({ contents });
+  const marked = withDevelopmentAxisReviewMarker({ contents: spliced });
+  const fixed = withUnusedStageImportRemoved({ contents: marked });
 
   return { contents: fixed };
 };

package/dist/practices/environments/best-practice/.declapract.readme.md

@@ -1,22 +1,20 @@
 # environments
 
-a critical part of an application's environment is which stage it is running in
+a critical part of an application's environment is its `access` — which deployment's resources
+the runtime may reach, and with what weight.
 
-ehmpathy recognizes three standard stages in which applications run throughout their development cycle
-- `prod` stage - a deployed production stack in which application that the business depends on run, affecting real customers
-- `prep` stage - a deployed pre-production stack in which applications can run and interact with each other for testing
-- `test` stage - an ephemeral, primarily local, developer-only stack in which developers run local code against for testing
+ehmpathy recognizes three standard tiers in which applications run throughout their development cycle
+- `prod` — a deployed production stack the business depends on, which serves real customers
+- `prep` — a deployed pre-production stack where applications interact for cross-service tests
+- `test` — an ephemeral, primarily local, developer-only tier for local code
 
-this information is expected to be defined in the runtime environment through the following environmental variables
-- `STAGE` env var - explicitly defines the stage
-- `NODE_ENV` env var - implicitly defines the stage if `STAGE` was not explicitly defined
+`access` is the one canonical axis (`test | prep | prod`). the runtime reads it via
+`getEnvironment.static().access` (sdk-environment), which derives it from the `ACCESS` env var, then
+the aws account, then `NODE_ENV`.
 
 # vocab
 
 definitions
-- `stage`
-  - > A stage is a stack that you deploy for a specific purpose.
-
 - `stack`
   - > A stack is your application plus everything that it requires to run. This can include (but is not limited to) networks, servers, storage folders, Docker containers, build pipelines, etc.
 
@@ -26,3 +24,38 @@ definitions
 
 ref
 - https://www.tinystacks.com/blog-post/what-are-stacks-stages-and-environments/
+
+# the access axis, and how a caller reaches a peer lambda
+
+one fact — which deployment a runtime reaches — is named by `access` (`test | prep | prod`).
+below prod the deployed resource names carry a legacy `dev` label, so an `access=prep` runtime must
+reach resources named `-dev-`. that mismatch (`access=prep` ⟺ deployed name `dev`) is a
+compiler-invisible fault: both are `string`, so a wrong reference is green at build and red only at
+runtime, against a deployed resource.
+
+`src/access/sdks/` holds the transitional bridge that lets a caller reach a peer lambda by the slug
+the peer actually publishes at, per callee — one procedure per file (`rule.require.single-responsibility`):
+
+- `sdkAwsLambdaEnvAccessAncient.ts` → `sdkAwsLambdaEnvAccessAncient()` — emits the legacy `dev` slug
+  below prod. for a peer still published under `-dev-` only. carries the shared `LambdaEnvSlug` type.
+- `sdkAwsLambdaEnvAccessContemp.ts` → `sdkAwsLambdaEnvAccessContemp()` — emits the access direct.
+  for a `-prep-` peer, or self.
+
+## the migration ledger
+
+the helper choice IS the ledger: `grep AccessAncient` across a repo lists every peer still on the
+ancient (`-dev-` only) slug. a per-peer migration is a one-line `Ancient → Contemp` flip. once the
+org's last `Ancient` import is gone, the ancient branch, the `-dev-` publish, and the divergent
+`dev` slug retire together — the helper is scaffold built to be torn down.
+
+`ancient`/`contemp` is `sdk-aws-lambda`'s own vocabulary (it names the payload-format axis there);
+the `EnvAccess` qualifier disambiguates this slug-axis sense from that homograph.
+
+## the helper is a shared primitive
+
+the helper is a pure, shared target-resolution primitive that a consumer wires when it migrates a
+peer, so a fresh consumer holds it with no call site yet. the caller-side wire-up and the helper's
+retirement both land at the north-star endpoint.
+
+the full transition design (dual-publish, the ledger, the deletion endpoint) is the north-star of
+the fix-lambdas wish — see `.behavior/v2026_08_31.fix-lambdas-3/1.vision.yield.md` in this repo.

package/dist/practices/environments/best-practice/src/access/sdks/sdkAwsLambdaEnvAccessAncient.ts

@@ -0,0 +1,32 @@
+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';
+};

package/dist/practices/environments/best-practice/src/access/sdks/sdkAwsLambdaEnvAccessContemp.ts

@@ -0,0 +1,14 @@
+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;