declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/practices/typescript-node/bad-practices/node-lts-strictest/package.json.declapract.ts

@@ -0,0 +1,90 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { asPackageJSON } from '../../../../utils/asPackageJSON';
+
+const PRACTICE = 'typescript-node/node-lts-strictest';
+
+const RETIRED_TSCONFIG = '@tsconfig/node-lts-strictest';
+
+/**
+ * .what = whether any root tsconfig*.json still extends the retired tsconfig base.
+ * .why  = the package must stay while a tsconfig extends it, or tsc cannot load the config (F42).
+ */
+const isRetiredTsconfigExtended = (input: {
+  projectRoot: string | null;
+}): boolean => {
+  const root = input.projectRoot;
+  if (!root || !existsSync(root)) return false;
+  return readdirSync(root)
+    .filter((name) => /^tsconfig.*\.json$/.test(name))
+    .some((name) =>
+      readFileSync(path.join(root, name), 'utf-8').includes(RETIRED_TSCONFIG),
+    );
+};
+
+/**
+ * .what = whether a package.json declares the retired tsconfig base, in either section.
+ */
+const isRetiredTsconfigDeclared = (input: {
+  contents: string | null;
+}): boolean => {
+  const pkg = asPackageJSON(
+    { contents: input.contents ?? '{}' },
+    { practice: PRACTICE },
+  );
+  return !!(
+    pkg.dependencies?.[RETIRED_TSCONFIG] ??
+    pkg.devDependencies?.[RETIRED_TSCONFIG]
+  );
+};
+
+/**
+ * .what = flags `@tsconfig/node-lts-strictest` once no tsconfig extends it.
+ * .why  = the typescript-node practice swapped it for `@tsconfig/strictest` + `@tsconfig/node20`
+ *         and left the old package in devDependencies, which depcheck then flags (#660).
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  if (
+    isRetiredTsconfigDeclared({ contents }) &&
+    !isRetiredTsconfigExtended({
+      projectRoot: context?.getProjectRootDirectory?.() ?? null,
+    })
+  )
+    return; // bad practice detected
+  throw new Error(
+    `does not match bad practice: ${RETIRED_TSCONFIG} absent, or a tsconfig still extends it`,
+  );
+};
+
+/**
+ * .what = removes the retired tsconfig base from both dep sections.
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  if (
+    !contents ||
+    isRetiredTsconfigExtended({
+      projectRoot: context?.getProjectRootDirectory?.() ?? null,
+    })
+  )
+    return { contents };
+  const pkg = asPackageJSON({ contents }, { practice: PRACTICE });
+  const without = (deps: Record<string, string> | undefined) =>
+    deps
+      ? Object.fromEntries(
+          Object.entries(deps).filter(([name]) => name !== RETIRED_TSCONFIG),
+        )
+      : undefined;
+  return {
+    contents: JSON.stringify(
+      {
+        ...pkg,
+        dependencies: without(pkg.dependencies),
+        devDependencies: without(pkg.devDependencies),
+      },
+      null,
+      2,
+    ),
+  };
+};

package/dist/practices/typescript-node/best-practice/tsconfig.build.json

@@ -13,6 +13,6 @@
     "**/*.test.js",
     "**/.test/**/*",
     "**/.scratch/**/*",
-    "**/__test*__/**/*" // todo: deprecate this pattern in favor of .test
+    "**/__test*__/**/*" // legacy dunder test dirs; new test assets live under .test
   ]
 }

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

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+import yaml from 'yaml';
+
+import { getAllPracticesForUsecase } from './utils/getAllPracticesForUsecase';
+
+/**
+ * .what = clamps #608 across every usecase: where a usecase holds `provision-github`, some
+ *         practice in that usecase declares `.github/workflows/provision.yml`, and its `github`
+ *         job points `wish-path` at the declastruct wish `provision/github.repo/resources.ts`.
+ * .why  = provision-github ships the declastruct wish; with no caller job a repo never applies it,
+ *         and a caller on the retired `provision/github/` terraform path applies naught. the expo
+ *         usecase once held provision-github with no caller at all — this holds the class.
+ * .teeth = drop the expo `provision.yml` template, or point any `github` job's wish-path elsewhere,
+ *          and case1 reddens with the usecase named.
+ */
+
+const repoRoot = join(__dirname, '..');
+const practicesDir = join(repoRoot, 'src/practices');
+const usecasesYmlPath = join(repoRoot, 'src/useCases.yml');
+const WISH_PATH_EXPECTED = 'provision/github.repo/resources.ts';
+
+/**
+ * .what = the github job's wish-path of each provision.yml template the usecase's practices declare
+ */
+const getAllGithubWishPaths = (input: {
+  practices: string[];
+}): { practice: string; wishPath: string | null }[] =>
+  input.practices
+    .map((practice) => ({
+      practice,
+      path: join(
+        practicesDir,
+        practice,
+        'best-practice/.github/workflows/provision.yml',
+      ),
+    }))
+    .filter(({ path }) => existsSync(path))
+    .map(({ practice, path }) => {
+      const workflow = yaml.parse(readFileSync(path, 'utf8'));
+      return {
+        practice,
+        wishPath: workflow?.jobs?.github?.with?.['wish-path'] ?? null,
+      };
+    });
+
+describe('provisionGithubWishPath', () => {
+  const usecases = Object.keys(
+    yaml.parse(readFileSync(usecasesYmlPath, 'utf8'))['use-cases'],
+  );
+  const usecasesWithProvisionGithub = usecases.filter((usecase) =>
+    getAllPracticesForUsecase({ usecasesYmlPath, usecase }).includes(
+      'provision-github',
+    ),
+  );
+
+  given('[case0] the usecases that hold provision-github', () => {
+    then('at least the node service, package, and expo usecases', () => {
+      expect(usecasesWithProvisionGithub.length).toBeGreaterThanOrEqual(3);
+    });
+  });
+
+  given('[case1] each usecase that holds provision-github', () => {
+    when('[t0] its provision.yml templates are read', () => {
+      then(
+        'some practice declares one, and every github job calls the declastruct wish',
+        () => {
+          const offenses = usecasesWithProvisionGithub.flatMap((usecase) => {
+            const found = getAllGithubWishPaths({
+              practices: getAllPracticesForUsecase({ usecasesYmlPath, usecase }),
+            });
+            if (!found.length)
+              return [`${usecase}: no practice declares provision.yml`];
+            if (!found.some(({ wishPath }) => wishPath !== null))
+              return [`${usecase}: no provision.yml declares a github job`];
+            return found
+              .filter(
+                ({ wishPath }) =>
+                  wishPath !== null && wishPath !== WISH_PATH_EXPECTED,
+              )
+              .map(
+                ({ practice, wishPath }) =>
+                  `${usecase}: ${practice} github job wish-path is ${wishPath}`,
+              );
+          });
+          expect(offenses).toEqual([]);
+        },
+      );
+    });
+  });
+});

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

@@ -0,0 +1,34 @@
+import { readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = clamps the host-path class: no committed jest snapshot holds this checkout's absolute root
+ * .why  = a snapshot that pins `/home/<who>/<worktree>/…` passes only on the checkout that wrote it,
+ *         and goes red in ci and on every other clone. a subprocess that echoes `$0` is the usual
+ *         source; its test must mask the path before it snapshots the output.
+ * .teeth = drop the `<check-engine-skew.sh>` mask in persist-with-rds's engine-upgrade test and
+ *          resnap; case1 reddens with that .snap named.
+ */
+describe('snapshotsHostPathFree', () => {
+  const repoRoot = join(__dirname, '..');
+
+  given('[case1] every committed jest snapshot under src/', () => {
+    when('[t0] each is read', () => {
+      then('none holds the absolute root of this checkout', () => {
+        const snapshots = getAllPathsUnderDir({
+          dir: join(repoRoot, 'src'),
+          skip: ['node_modules', '.test'],
+        }).filter((file) => file.endsWith('.snap'));
+        expect(snapshots.length).toBeGreaterThan(10);
+        const offenses = snapshots
+          .filter((file) => readFileSync(file, 'utf8').includes(repoRoot))
+          .map((file) => relative(repoRoot, file));
+        expect(offenses).toEqual([]);
+      });
+    });
+  });
+});

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

@@ -1,19 +1,18 @@
 import { readFileSync } from 'node:fs';
 
+import { MalfunctionError } from 'helpful-errors';
 import { given, then, useBeforeAll, when } from 'test-fns';
-import ts from 'typescript';
+import { getModuleExportsFromTsSource } from './utils/getModuleExportsFromTsSource';
 
 /**
  * .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).
+ *         — that below prod `stage=dev ⟺ access=prep`, and at prod both axes read `prod` — in TWO
+ *         unlinked places: the serverless `accessByStage` map (the deploy-side bridge) and the
+ *         `sdkAwsLambdaEnvAccessAncient` helper (the call-side slug). this asserts they agree per
+ *         deployed access, so a drift in one without the other reddens (#571).
+ * .note = the ssm param names carry no `dev` cast: they take the config slug sdk-config derives
+ *         (`/{org}/{project}/{config}/…`, #637), so the [t3] leg asserts the namespace source holds
+ *         no prep→dev cast at all.
  * .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,
@@ -21,10 +20,10 @@ import ts from 'typescript';
  *         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
+ * .teeth = drift the map's `dev:` target, or the helper's ancient branch, and the per-access
  *          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).
+ *          preserved a pinned text fragment can no longer sail through green.
  */
 
 const ACCESS_BY_STAGE_SRC = `${__dirname}/practices/serverless/best-practice/serverless.yml.declapract.ts`;
@@ -53,46 +52,24 @@ const parseAccessByStage = (src: string): Record<string, string> => {
  * .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
+ *         return value per access — 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).
+ *         this reuses the environments practice's executed-helper pattern.
  */
 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;
+  const { sdkAwsLambdaEnvAccessAncient } = getModuleExportsFromTsSource<{
+    sdkAwsLambdaEnvAccessAncient: (input: { access: null }) => string;
+  }>({ source: input.src, requireStub });
+  const targetOp =
+    sdkAwsLambdaEnvAccessAncient ??
+    MalfunctionError.throw('the ancient helper template no longer exports its op', {
+      name: 'sdkAwsLambdaEnvAccessAncient',
+    });
+  return targetOp({ access: null });
 };
 
 describe('stage↔access bridge — the two unlinked sources agree (round-trip clamp)', () => {
@@ -113,7 +90,7 @@ describe('stage↔access bridge — the two unlinked sources agree (round-trip c
       });
     });
 
-    when('[t1] the ancient helper is transpiled + executed per tier', () => {
+    when('[t1] the ancient helper is transpiled + executed per access', () => {
       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');
@@ -124,7 +101,7 @@ describe('stage↔access bridge — the two unlinked sources agree (round-trip c
       });
     });
 
-    when('[t2] the round-trip is composed per deployed tier', () => {
+    when('[t2] the round-trip is composed per deployed access', () => {
       // 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', () => {
@@ -138,25 +115,12 @@ describe('stage↔access bridge — the two unlinked sources agree (round-trip c
       });
     });
 
-    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');
+    when('[t3] the ssm-namespace source is read', () => {
+      then('it holds no prep→dev cast (the names take the config slug, #637)', () => {
+        // teeth: re-add an `accessSlug` ternary or any `'dev'` literal and this reddens
+        expect(scene.namespaceSrc).not.toContain('accessSlug');
+        expect(scene.namespaceSrc).not.toContain("'dev'");
+        expect(scene.namespaceSrc).toContain('input.choice ?? config');
       });
     });
   });

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

@@ -0,0 +1,124 @@
+import { readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+import {
+  getAllPathsUnderDir,
+  PRACTICE_TREE_SKIP_DIRS,
+} from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = clamps that the terraform pin `terraform-common` ships in `.terraform-version`
+ *         satisfies every `required_version` constraint a best-practice `.tf` template declares.
+ * .why  = the pin and the constraints ship from different practices into one adopter repo. a pin
+ *         below a constraint is a self-contradiction: tfenv installs the pinned binary, and that
+ *         binary refuses every root that declares the constraint (#600 — `0.14.11` against
+ *         `>= 1.7`). a wrong number here goes red in this repo, never in an adopter.
+ * .teeth = set `.terraform-version` back to `0.14.11` and case1 goes red with each offender.
+ * .note = scope is `best-practice/` only; a bad-practice `.tf` is a pattern to detect, not a
+ *         template that ships.
+ */
+
+const repoRoot = join(__dirname, '..');
+const practicesDir = join(repoRoot, 'src/practices');
+const pinPath = join(
+  practicesDir,
+  'terraform-common/best-practice/.terraform-version',
+);
+
+type VersionTuple = [number, number, number];
+
+/**
+ * .what = a dotted version string as a three-number tuple; absent parts read as zero
+ */
+const asVersionTuple = (input: { version: string }): VersionTuple => {
+  const [major = 0, minor = 0, patch = 0] = input.version
+    .trim()
+    .split('.')
+    .map((part) => Number.parseInt(part, 10));
+  return [major, minor, patch];
+};
+
+/**
+ * .what = the sign of (a - b) across a version tuple, leftmost part first
+ */
+const compareVersions = (a: VersionTuple, b: VersionTuple): number =>
+  a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+
+/**
+ * .what = whether one version satisfies one terraform comparator (`>= 1.7`, `~> 1.9.0`, `1.9.8`)
+ * .note = `~>` follows terraform: the rightmost declared part may increase, the rest must hold
+ */
+const isVersionInComparator = (input: {
+  version: VersionTuple;
+  comparator: string;
+}): boolean => {
+  const match = input.comparator.trim().match(/^(>=|<=|!=|~>|>|<|=)?\s*(.+)$/);
+  if (!match) throw new Error(`unparsable comparator: ${input.comparator}`);
+  const operator = match[1] ?? '=';
+  const bound = asVersionTuple({ version: match[2] ?? '' });
+  const diff = compareVersions(input.version, bound);
+  if (operator === '>=') return diff >= 0;
+  if (operator === '<=') return diff <= 0;
+  if (operator === '>') return diff > 0;
+  if (operator === '<') return diff < 0;
+  if (operator === '!=') return diff !== 0;
+  if (operator === '=') return diff === 0;
+  const declaredParts = (match[2] ?? '').trim().split('.').length;
+  const fixedParts = Math.max(declaredParts - 1, 1);
+  const prefixHolds = input.version
+    .slice(0, fixedParts)
+    .every((part, index) => part === bound[index]);
+  return prefixHolds && diff >= 0;
+};
+
+/**
+ * .what = every `required_version = "..."` constraint inside one `.tf` source
+ */
+const getAllRequiredVersions = (input: { source: string }): string[] =>
+  [...input.source.matchAll(/required_version\s*=\s*"([^"]+)"/g)].map(
+    (match) => match[1] ?? '',
+  );
+
+describe('the terraform pin satisfies every required_version (#600)', () => {
+  const pin = readFileSync(pinPath, 'utf8').trim();
+  const constraints = getAllPathsUnderDir({
+    dir: practicesDir,
+    skip: PRACTICE_TREE_SKIP_DIRS,
+  })
+    .filter((path) => path.endsWith('.tf') && path.includes('/best-practice/'))
+    .sort()
+    .flatMap((path) =>
+      getAllRequiredVersions({ source: readFileSync(path, 'utf8') }).map(
+        (constraint) => ({ path: relative(repoRoot, path), constraint }),
+      ),
+    );
+
+  given('[case0] the best-practice terraform templates', () => {
+    when('[t0] their required_version constraints are collected', () => {
+      then('at least one constraint is found, so the clamp is not vacuous', () => {
+        expect(constraints.length).toBeGreaterThan(0);
+      });
+    });
+  });
+
+  given('[case1] the .terraform-version pin', () => {
+    when('[t0] it is checked against each constraint', () => {
+      then('no constraint rejects the pin', () => {
+        const version = asVersionTuple({ version: pin });
+        const offenders = constraints
+          .filter(
+            ({ constraint }) =>
+              !constraint
+                .split(',')
+                .every((comparator) =>
+                  isVersionInComparator({ version, comparator }),
+                ),
+          )
+          .map(({ path, constraint }) => `${path}: "${constraint}" rejects ${pin}`);
+        expect(offenders).toEqual([]);
+      });
+    });
+  });
+});