declapract-typescript-ehmpathy 0.49.9 → 0.49.11

package/dist/practices/pnpm/bad-practices/package-lock-json/package-lock.json.declapract.ts

@@ -1,3 +1,41 @@
-import { FileCheckType } from 'declapract';
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
 
-export const check = FileCheckType.EXISTS;
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * .what = detects a `package-lock.json` (the npm lockfile) that is SAFE to remove — i.e. only
+ *         once a `pnpm-lock.yaml` sits beside it.
+ * .why  = the npm→pnpm migration must be FORGET-NOT-DESTROY: `package-lock.json` is removed ONLY
+ *         after `pnpm-lock.yaml` exists, so a fix interrupted midway never leaves the repo
+ *         lockfile-less (the wish's stated safety bar). a bare `FileCheckType.EXISTS` would let
+ *         declapract's default fix delete the npm lockfile UNCONDITIONALLY — even on a repo that
+ *         has not yet run `pnpm install` — which is exactly the destructive strip this gate
+ *         forecloses. so the delete is gated on the pnpm lockfile's presence, read from the
+ *         project root via `context.getProjectRootDirectory()`.
+ */
+const hasPnpmLock = (context: {
+  getProjectRootDirectory: () => string;
+}): boolean =>
+  existsSync(path.join(context.getProjectRootDirectory(), 'pnpm-lock.yaml'));
+
+export const check: FileCheckFunction = (contents, context) => {
+  // no package-lock.json → no npm lockfile to remove, skip
+  if (contents === null) throw new Error('does not match bad practice');
+
+  // forget-not-destroy: without a pnpm-lock.yaml beside it, removal would leave the repo
+  // lockfile-less — so this is NOT yet a safe-to-remove npm lockfile, skip
+  if (!hasPnpmLock(context)) throw new Error('does not match bad practice');
+
+  // package-lock.json present AND pnpm-lock.yaml present → safe to remove, detected
+  return;
+};
+
+export const fix: FileFixFunction = (contents, context) => {
+  // gate the delete on the pnpm lockfile's presence (forget-not-destroy) — a fix that ran
+  // where the check would not detect leaves the file untouched, never lockfile-less
+  if (!hasPnpmLock(context)) return { contents };
+
+  // pnpm-lock.yaml exists → remove the redundant npm lockfile
+  return { contents: null };
+};

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

@@ -0,0 +1,22 @@
+# pnpm best-practice — what this practice owns, and what it does NOT
+
+this practice owns the pnpm **adoption** signal: the `packageManager` exact pin
+(`pnpm@10.31.7`, an intentional org-convergence requirement — see the `.declapract.ts` note).
+
+## where the hoisted-linker `.npmrc` lives — NOT here
+
+the pnpm-only `.npmrc` directives an expo repo needs (`node-linker=hoisted`,
+`public-hoist-pattern[]=*expo*`, …) are declared by the **`node`** practice, not this one. the
+`node` practice owns the whole `.npmrc` (it is the package-manager-config file), and its declaration
+is usecase-aware: it findserts the hoist block only when the `cicd-app-react-native-expo` usecase is
+present.
+
+so an auditor of all that pnpm needs should also read:
+
+- `src/practices/node/best-practice/.npmrc.declapract.ts` — the usecase-aware `.npmrc` declaration
+- `src/utils/defineExpectedNpmrcContents.ts` — the shared base + expo-hoist line source
+- `.agent/repo=.this/role=any/briefs/howto.pnpm-expo-hoisted-linker.md` — why the flat linker is
+  required for metro/expo, and the transitive-skew gotcha it exposes
+
+the split is deliberate: the `.npmrc` is one file with one owner (`node`), so a repo gets a single
+coherent `.npmrc` rather than two practices that fight over it.

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

@@ -1,3 +1,3 @@
 {
-  "packageManager": "pnpm@10.24.0"
+  "packageManager": "pnpm@10.31.7"
 }

package/dist/practices/pnpm/best-practice/package.json.declapract.ts

@@ -1,3 +1,15 @@
 import { FileCheckType } from 'declapract';
 
+/**
+ * .what = pins `packageManager` to an EXACT pnpm version (`pnpm@10.31.7`), not a minVersion.
+ * .why  = this is an intentional org-standardization REQUIREMENT, not an oversight. every pnpm
+ *         consumer runs ONE blessed pnpm version, so `corepack` / `pnpm/action-setup@v4` load the
+ *         identical toolchain across CI, local, and every repo — reproducible installs, no per-repo
+ *         drift. an exact pin is also the ONLY correct shape here: the `packageManager` field is a
+ *         corepack spec that requires the `pnpm@<version>` prefix, which declapract's bare-semver
+ *         `check.minVersion(..)` cannot emit.
+ * .note = a consumer ahead of the pin (e.g. on 10.32.1) is pinned BACK to the blessed version on
+ *         `declapract fix` — that convergence-to-one-version is the intent, not a regression. when
+ *         the org bumps the blessed version, this pin bumps and every consumer follows.
+ */
 export const check = FileCheckType.CONTAINS;

package/dist/practices/tests-any/bad-practices/javascript-config-files/.declapract.readme.md

@@ -0,0 +1 @@
+we've migrated to using `.ts` config files for jest config, rather than `.js`

package/dist/practices/tests-any/bad-practices/javascript-config-files/jest.<star>.js.declapract.ts

@@ -0,0 +1,17 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+/**
+ * .what = deletes a stale `.js` jest config file
+ * .why  = the go-forward jest config is `.ts` (see .declapract.readme.md). a leftover
+ *         `.js` jest config (e.g. a jsdom `jest.config.js` or a `jest.unit.config.js`)
+ *         is redundant and fights the shipped `.ts` config — the dual-source hazard the
+ *         app-protools-native migration must reconcile. drop the redundant `.js`; the
+ *         best-practice supplies the canonical `.ts` config in the same pass.
+ * .note  = `{ contents: null }` removes the file. idempotent: once gone, the EXISTS
+ *          check no longer detects it, so a re-run is a no-op.
+ */
+export const fix: FileFixFunction = () => {
+  return { contents: null };
+};

package/dist/practices/tests-any/bad-practices/mocks/.declapract.readme.md

@@ -0,0 +1,8 @@
+should not have any `__mock__` directories
+
+these are hard to track down and are too "magical" and affect _all_ tests (i.e., inter test dependency)
+
+just explicitly mocks manually in each test OR root level in setup env with:
+```ts
+jest.mock("...");
+```

package/dist/practices/tests-any/bad-practices/mocks/<star><star>/__mock__/<star>.js

@@ -0,0 +1,3 @@
+/**
+ * bad practice: file exists
+ */

package/dist/practices/tests-any/bad-practices/mocks/<star><star>/__mock__/<star>.ts

@@ -0,0 +1,3 @@
+/**
+ * bad practice: file exists
+ */

package/dist/practices/tests-any/bad-practices/old-acceptance-dir-location/.declapract.integration.test.ts

@@ -0,0 +1,63 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = integration test for old-acceptance-dir-location bad practice
+ * .why = reproduces bug where files with non-ts extensions are silently dropped
+ */
+describe('old-acceptance-dir-location', () => {
+  given('[case1] accept.blackbox/ with various file types', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-old-acceptance-dir',
+      clone: './src/practices/tests-any/bad-practices/old-acceptance-dir-location/.test/assets/demo-repo-with-accept-blackbox-dir',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    when('[t0] before fix', () => {
+      then('accept.blackbox/ contains files', async () => {
+        const rhachetFile = path.join(
+          tempDir,
+          'accept.blackbox/.test/assets/.rhachet/manifest.json',
+        );
+        const stats = await fs.stat(rhachetFile);
+        expect(stats.isFile()).toBe(true);
+      });
+    });
+
+    when('[t1] declapract fix is applied', () => {
+      useThen('fix is applied', async () => {
+        await executeApply({
+          config: path.join(tempDir, 'declapract.use.yml'),
+          practice: 'tests-any',
+        });
+      });
+
+      then('somefile.ts is moved to blackbox/', async () => {
+        const newPath = path.join(tempDir, 'blackbox/somefile.ts');
+        const stats = await fs.stat(newPath).catch(() => null);
+        expect(stats?.isFile()).toBe(true);
+      });
+
+      then('.rhachet/manifest.json is moved to blackbox/', async () => {
+        const newPath = path.join(
+          tempDir,
+          'blackbox/.test/assets/.rhachet/manifest.json',
+        );
+        const stats = await fs.stat(newPath).catch(() => null);
+        expect(stats?.isFile()).toBe(true);
+      });
+
+      then('.agent/config.yml is moved to blackbox/', async () => {
+        const newPath = path.join(
+          tempDir,
+          'blackbox/.test/assets/.agent/config.yml',
+        );
+        const stats = await fs.stat(newPath).catch(() => null);
+        expect(stats?.isFile()).toBe(true);
+      });
+    });
+  });
+});

package/dist/practices/tests-any/bad-practices/old-acceptance-dir-location/.declapract.readme.md

@@ -0,0 +1,22 @@
+# old-acceptance-dir-location
+
+## .what
+
+detects test files located in `acceptance/` or `accept.blackbox/` directories and migrates them to `blackbox/`.
+
+## .why
+
+the term "blackbox" makes the testing philosophy explicit:
+- blackbox tests interact only through public contracts (APIs, CLIs, SDKs)
+- no access to internal implementation details
+- tests validate behavior from the caller's perspective
+
+the rename from `acceptance/` or `accept.blackbox/` to `blackbox/` clarifies this intent and simplifies the naming.
+
+## .fix
+
+moves all files from `acceptance/` or `accept.blackbox/` to `blackbox/` while preserving the directory structure.
+
+## .note
+
+the `.acceptance.test.ts` file extension is preserved — it communicates the test type while the directory name communicates the testing philosophy.

package/dist/practices/tests-any/bad-practices/old-acceptance-dir-location/.test/assets/demo-repo-with-accept-blackbox-dir/accept.blackbox/.test/assets/.agent/config.yml

@@ -0,0 +1 @@
+key: value

package/dist/practices/tests-any/bad-practices/old-acceptance-dir-location/.test/assets/demo-repo-with-accept-blackbox-dir/accept.blackbox/.test/assets/.rhachet/manifest.json

@@ -0,0 +1 @@
+{}

package/dist/practices/tests-any/bad-practices/old-acceptance-dir-location/.test/assets/demo-repo-with-accept-blackbox-dir/accept.blackbox/somefile.ts

@@ -0,0 +1 @@
+export const x = 1;

package/dist/practices/tests-any/bad-practices/old-acceptance-dir-location/.test/assets/demo-repo-with-accept-blackbox-dir/declapract.declare.yml

@@ -0,0 +1,4 @@
+declare:
+  examples: src/examples
+  practices: src/practices
+  use-cases: src/useCases.yml

package/dist/practices/tests-any/bad-practices/old-acceptance-dir-location/.test/assets/demo-repo-with-accept-blackbox-dir/declapract.use.yml

@@ -0,0 +1,5 @@
+declarations: './'
+useCase: typescript-project
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'

package/dist/practices/tests-any/bad-practices/old-acceptance-dir-location/.test/assets/demo-repo-with-accept-blackbox-dir/package.json

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

package/dist/practices/tests-any/bad-practices/old-acceptance-dir-location/accept.blackbox/<star><star>/<star>.declapract.ts

@@ -0,0 +1,19 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if any files exist in accept.blackbox/, flag as bad practice
+
+/**
+ * .what = moves any file from accept.blackbox/ to blackbox/
+ * .why = ensures all files are moved, not just .ts files — prevents silent data loss for hidden paths
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  // move from accept.blackbox/ to blackbox/
+  const newPath = context.relativeFilePath.replace(
+    /^accept\.blackbox\//,
+    'blackbox/',
+  );
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/practices/tests-any/bad-practices/old-acceptance-dir-location/acceptance/<star><star>/<star>.declapract.ts

@@ -0,0 +1,19 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if any files exist in acceptance/, flag as bad practice
+
+/**
+ * .what = moves any file from acceptance/ to blackbox/
+ * .why = ensures all files are moved, not just .ts files — prevents silent data loss for hidden paths
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  // move from acceptance/ to blackbox/
+  const newPath = context.relativeFilePath.replace(
+    /^acceptance\//,
+    'blackbox/',
+  );
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/practices/tests-any/bad-practices/old-acceptance-import-paths/.declapract.readme.md

@@ -0,0 +1,31 @@
+# old-acceptance-import-paths
+
+## .what
+
+detects import statements that reference the old `acceptance/` directory path.
+
+## .why
+
+the `acceptance/` directory has been renamed to `blackbox/` to make the testing philosophy explicit:
+- blackbox tests interact only through public contracts
+- no access to internal implementation details
+
+import paths must be updated to reference `blackbox/` instead of `acceptance/`.
+
+## .fix
+
+replaces all occurrences of `acceptance/` with `blackbox/` in import paths.
+
+## .examples
+
+before:
+```typescript
+import { locally } from '../acceptance/environment';
+import { stage } from '../../acceptance/utils/environment';
+```
+
+after:
+```typescript
+import { locally } from '../blackbox/environment';
+import { stage } from '../../blackbox/utils/environment';
+```

package/dist/practices/tests-any/bad-practices/old-acceptance-import-paths/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,25 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects imports that reference acceptance/ directory
+ * .why = acceptance/ has been renamed to blackbox/
+ */
+export const check: FileCheckFunction = (contents) => {
+  // match imports that reference acceptance/ directory
+  if (contents?.match(/from ['"]\.\.?\/.*acceptance\//)) return; // matches bad practice
+  if (contents?.match(/from ['"]acceptance\//)) return; // matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * .what = replaces acceptance/ with blackbox/ in import paths
+ * .why = blackbox/ naming makes the testing philosophy explicit
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+  return {
+    contents: contents
+      .replace(/(['"])(.*)\/acceptance\//g, '$1$2/blackbox/')
+      .replace(/(['"])acceptance\//g, '$1blackbox/'),
+  };
+};

package/dist/practices/tests-any/bad-practices/old-acceptance-test-utils/blackbox/_utils/getDataFromLastOpenBracketAtStartOfLine.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS;

package/dist/practices/tests-any/bad-practices/old-acceptance-test-utils/blackbox/_utils/invokeLambda.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS;

package/dist/practices/tests-any/bad-practices/old-acceptance-test-utils/blackbox/lambdas/<star>.ts.declapract.ts

@@ -0,0 +1,44 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { getProjectVariables } from '../../../../../../getVariables';
+
+export const check: FileCheckFunction = (contents) => {
+  if (
+    contents?.includes(`import { invokeLambda } from '../_utils/invokeLambda';`)
+  )
+    return; // then it matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = async (contents, context) => {
+  if (!contents) return {}; // do nothing if no contents. really, this shouldn't have been called
+  const { projectName } = await getProjectVariables(context);
+  return {
+    contents: contents
+      .replace(
+        // replace the bad import
+        `import { invokeLambda } from '../_utils/invokeLambda';`,
+        [
+          `import { invokeLambdaForTesting } from 'simple-lambda-testing-methods';`,
+          `import { stage } from '../../src/utils/environment';`,
+          `import { locally } from '../environment';`,
+        ].join('\n'),
+      )
+      .replace(
+        // replace calls to the fn
+        /invokeLambda\(\{/g,
+        'invokeLambdaForTesting({',
+      )
+      .replace(
+        // replace the inputs
+        /name: '(\w+)',/g,
+        [
+          `service: '${projectName}',`,
+          `function: '$1',`,
+          `stage,`,
+          `locally,`,
+        ].join('\n'),
+      )
+      .replace(/data: /g, 'event: '),
+  };
+};

package/dist/practices/tests-any/bad-practices/old-acceptance-test-utils-2/blackbox/lambdas/<star>.ts.declapract.ts

@@ -0,0 +1,22 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (
+    contents?.includes(
+      `import { locally } from '../__test_utils__/environment';`,
+    )
+  )
+    return; // then it matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = async (contents) => {
+  if (!contents) return {}; // do nothing if no contents. really, this shouldn't have been called
+  return {
+    contents: contents.replace(
+      // replace the bad import
+      `import { locally } from '../__test_utils__/environment';`,
+      `import { locally } from '../environment';`,
+    ),
+  };
+};

package/dist/practices/tests-any/bad-practices/old-acceptance-test-utils-3/blackbox/_utils/environment.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS;

package/dist/practices/tests-any/bad-practices/old-acceptance-test-utils-3/blackbox/lambdas/<star>.ts.declapract.ts

@@ -0,0 +1,18 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes(`import { locally } from '../_utils/environment';`))
+    return; // then it matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = async (contents) => {
+  if (!contents) return {}; // do nothing if no contents. really, this shouldn't have been called
+  return {
+    contents: contents.replace(
+      // replace the bad import
+      `import { locally } from '../_utils/environment';`,
+      `import { locally } from '../environment';`,
+    ),
+  };
+};

package/dist/practices/tests-any/bad-practices/old-extension-pattern/.declapract.readme.md

@@ -0,0 +1,3 @@
+a previous, now deprecated, best practice was to have the extension of `*.test.integration.ts` or `*.test.acceptance.ts` on test files
+
+we've since moved over to `*.integration.test.ts` and `*.acceptance.test.ts` (it having the `.test.ts` extension still makes tools that dont expect different test types work with these test files out of the box, which is a nice to have)

package/dist/practices/tests-any/bad-practices/old-extension-pattern/<star><star>/<star>.test.acceptance.ts.declapract.ts

@@ -0,0 +1,11 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if files matching this pattern exist, bad practice
+
+export const fix: FileFixFunction = (contents, context) => ({
+  relativeFilePath: context.relativeFilePath.replace(
+    /\.test\.acceptance\.ts$/,
+    '.acceptance.test.ts',
+  ),
+  contents,
+});

package/dist/practices/tests-any/bad-practices/old-extension-pattern/<star><star>/<star>.test.integration.ts.declapract.ts

@@ -0,0 +1,11 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if files matching this pattern exist, bad practice
+
+export const fix: FileFixFunction = (contents, context) => ({
+  relativeFilePath: context.relativeFilePath.replace(
+    /\.test\.integration\.ts$/,
+    '.integration.test.ts',
+  ),
+  contents,
+});

package/dist/practices/tests-any/bad-practices/old-test-utils-and-assets-location/.declapract.readme.md

@@ -0,0 +1,8 @@
+test utilities and assets should be located in `.test.utils/` or `.test.assets/` instead of `__test_utils__` or `__test_assets__`
+
+the `.test.utils/` directory replaces `__test_utils__` and `.test.assets/` replaces `__test_assets__` in the same relative location.
+
+examples:
+- `src/domain/__test_utils__/exampleUser.ts` → `src/domain/.test.utils/exampleUser.ts`
+- `src/logic/__test_assets__/fixtures.json` → `src/logic/.test.assets/fixtures.json`
+- `blackbox/__test_utils__/environment.ts` → `blackbox/.test.utils/environment.ts`

package/dist/practices/tests-any/bad-practices/old-test-utils-and-assets-location/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,27 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * check if file has imports from __test_utils__ or __test_assets__ directories
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes('__test_utils__')) return; // matches bad practice
+  if (contents?.includes('__test_assets__')) return; // matches bad practice
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * replace __test_utils__ and __test_assets__ with .test.utils and .test.assets in import paths
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+
+  // simple string replacement - the relative path stays the same, only the directory name changes
+  // e.g., from '../__test_utils__/foo' to '../.test.utils/foo'
+  const fixedContents = contents
+    .replace(/__test_utils__\//g, '.test.utils/')
+    .replace(/__test_assets__\//g, '.test.assets/');
+
+  return {
+    contents: fixedContents,
+  };
+};

package/dist/practices/tests-any/bad-practices/old-test-utils-and-assets-location/<star><star>/__test_assets__/<star><star>/<star>.declapract.ts

@@ -0,0 +1,17 @@
+import type { FileFixFunction } from 'declapract';
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if files exist in __test_assets__ directories, it's bad practice
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move from any/**/__test_assets__/**/* to .test.assets/**/*
+  const newPath = context.relativeFilePath.replace(
+    /__test_assets__\//g,
+    '.test.assets/',
+  );
+
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/practices/tests-any/bad-practices/old-test-utils-and-assets-location/<star><star>/__test_utils__/<star><star>/<star>.declapract.ts

@@ -0,0 +1,17 @@
+import type { FileFixFunction } from 'declapract';
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if files exist in __test_utils__ directories, it's bad practice
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move from any/**/__test_utils__/**/* to .test.utils/**/*
+  const newPath = context.relativeFilePath.replace(
+    /__test_utils__\//g,
+    '.test.utils/',
+  );
+
+  return {
+    contents: contents ?? null,
+    relativeFilePath: newPath,
+  };
+};

package/dist/practices/tests-any/best-practice/.declapract.readme.md

@@ -0,0 +1,45 @@
+# best practices for testing
+
+## purpose of testing:
+- think use cases, edge cases, and play with the business logic / model you've defined
+- define use cases, edge cases, and previous failure points explicitly for future reference
+- automate checking that:
+  - code complies with spec (i.e., all use cases and requirements are satisfied)
+  - regressions will not occur
+  - predicted error cases are covered
+
+## three test types:
+- unit tests
+  - test precisely scoped business logic, mocking out all dependencies
+  - purpose is to test that the unit/function of logic that you're defining does the logic in it correctly
+- integration tests
+  - test end to end logic OR test boundaries between calling a dependent service
+  - for example:
+    - test boundaries with a dependent api
+      - test that we are communicating w/ database correctly
+      - test that we are
+    - test end to end logic
+      - test that a handler acts correctly in different cases
+      - test that a highly composed business logic function produces the correct results in all cases
+- acceptance tests
+  - test that the deployed product works
+  - ideally: test an end to end pipeline of each use case it needs to support
+    - note: typically its sufficient to trust that integration tests have already tested the use cases and then all we need to test is that the lambda can be hit
+
+// todo: add examples to the above
+// todo: finesse the above definitions now that we're formally defining them
+
+## pattern
+
+- each test type gets its own file extension
+  - unit -> `.test.ts` (the default extension)
+  - integration -> `.integration.test.ts`
+  - acceptance -> `.acceptance.test.ts`
+- each test type gets its own config (e.g., specify what extension to use)
+  - `jest.unit.config`
+  - `jest.integration.config`
+  - `jest.acceptance.config`
+- each test type gets its own environment setup file (e.g., global mocks, or checks, etc)
+  - `jest.unit.env`
+  - `jest.integration.env`
+  - `jest.acceptance.env`

package/dist/practices/tests-any/best-practice/.declapract.todo.md

@@ -0,0 +1,3 @@
+cutover to vitest
+
+its faster and has native esm + ts support

package/dist/practices/tests-any/best-practice/package.json

@@ -0,0 +1,17 @@
+{
+  "devDependencies": {
+    "@jest/globals": "@declapract{check.minVersion('30.2.0')}",
+    "@types/jest": "@declapract{check.minVersion('30.0.0')}",
+    "jest": "@declapract{check.minVersion('30.2.0')}",
+    "esbuild-register": "@declapract{check.minVersion('3.6.0')}",
+    "test-fns": "@declapract{check.minVersion('1.15.8')}",
+    "tsx": "@declapract{check.minVersion('4.20.6')}"
+  },
+  "scripts": {
+    "test:unit": "set -eu && jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${THOROUGH:-}\" != \"true\" ] && echo '--changedSince=main') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
+    "test:integration": "set -eu && jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${THOROUGH:-}\" != \"true\" ] && echo '--changedSince=main') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
+    "test:acceptance:locally": "set -eu && npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
+    "test": "set -eu && npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
+    "test:acceptance": "set -eu && npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')"
+  }
+}

package/dist/practices/tests-any/best-practice/package.json.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;