declapract-typescript-ehmpathy 0.49.11 → 0.49.13

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

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

package/dist/utils/asPackageJSON.ts

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

package/dist/utils/asPrepConfigPath.ts

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

package/dist/utils/getAllPathsUnderDir.ts

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

package/dist/utils/getAllPracticesForUsecase.ts

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

package/dist/utils/migrateDevConfigToPrep.ts

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

package/dist/utils/readFile.ts

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