declapract-typescript-ehmpathy 0.49.10 → 0.49.12

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

@@ -0,0 +1,136 @@
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import {
+  getAllPathsUnderDir,
+  PRACTICE_TREE_SKIP_DIRS,
+} from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = a structural ratchet over every `package.json.declapract.ts` declaration: each one that
+ *         reads a consumer `package.json` off the `contents` arg must parse it through
+ *         `asPackageJSON`, not a raw `JSON.parse(contents)`. the ratchet holds the CURRENT
+ *         unconverted set to an allowlist, so the count only ever falls — a new declaration cannot
+ *         add a raw parse OF `contents` off the allowlist, and a converted one must drop from the
+ *         allowlist (D50 / #571).
+ * .bound = the ledger's teeth are keyed to the `contents` parameter name and to self-consistency
+ *          within ONE run. two gaps follow, both benign at today's instances and named here so the
+ *          claim above is not read wider than it holds: (1) a declaration that parses the consumer
+ *          `package.json` off a differently-named var is not matched — the ratchet reads the
+ *          `contents` arg, the canonical name for that arg in a `FileCheckFunction`/`FileFixFunction`
+ *          signature, so an off-name parse of the SAME input evades it (a `FileContentsFunction` that
+ *          parses config or its own template package.json, as `tests-service` does, is NOT this debt
+ *          — it never reads the consumer's package.json). (2) the compare is intra-run only: a diff
+ *          that adds a raw parse AND its allowlist row together passes, since there is no baseline
+ *          diff against `origin/main`. to widen either is a value-emitter change gated behind a
+ *          same-store/same-input discriminant (a differently-named parse of an unrelated input must
+ *          not false-positive) — a follow-on, not a claim this ledger makes today.
+ * .why  = a raw `JSON.parse(contents)` throws a context-free engine `SyntaxError` that names no
+ *         practice, no dependency, no file, and no remedy (see `asPackageJSON`). the verbal note
+ *         "route every parse through the util" decayed across three review rounds as a memory rather
+ *         than a test; a memory does not redden when a 27th declaration adds a raw parse. this turns
+ *         the note into a gate: the allowlist is the debt ledger, and it can only shrink.
+ * .note = this is an INTEGRATION test by the same rule its kin walks cite (`errors`, `domain`,
+ *         `actionPins`): it reads the filesystem — `readdirSync` over the practice tree,
+ *         `readFileSync` on every declaration — and `rule.forbid.unit.remote-boundaries` puts any
+ *         test that crosses that boundary in the integration suite. no credential, no network; the
+ *         boundary alone classifies it.
+ * .teeth = the "no NEW unconverted" case is the sharp one: it reddens the moment a fresh
+ *          `package.json.declapract.ts` raw-parses `contents` off the allowlist. the "no STALE
+ *          allowlist" case forces the ledger down — convert a declaration and its allowlist row must
+ *          go, or the test reddens.
+ */
+
+const PRACTICES_DIR = `${__dirname}/practices`;
+
+/**
+ * .what = the allowlist of `package.json.declapract.ts` declarations that still raw-parse `contents`
+ *         (paths relative to `src/practices`). this is the debt ledger; each row is a declaration
+ *         yet to route through `asPackageJSON`, and the ratchet forbids the ledger to grow.
+ */
+const ALLOWED_UNCONVERTED = [
+  'bottleneck/bad-practices/bottleneck/package.json.declapract.ts',
+  'config/bad-practices/old-config-with-paramstore-dep/package.json.declapract.ts',
+  'conventional-commits/bad-practices/commitlint/package.json.declapract.ts',
+  'dates-and-times/bad-practices/uni-time/package.json.declapract.ts',
+  'domain/bad-practices/simple-type-guards/package.json.declapract.ts',
+  'environments/bad-practices/old-dev-scripts/package.json.declapract.ts',
+  'errors/bad-practices/error-fns/package.json.declapract.ts',
+  'format/bad-practices/format-script/package.json.declapract.ts',
+  'format/bad-practices/prettier/package.json.declapract.ts',
+  'husky/bad-practices/postinstall/package.json.declapract.ts',
+  'lint/bad-practices/eslint/package.json.declapract.ts',
+  'lint/bad-practices/tslint/package.json.declapract.ts',
+  'logs/bad-practices/simple-log-methods/package.json.declapract.ts',
+  'node-service/bad-practices/license/package.json.declapract.ts',
+  'node-service/bad-practices/simple-lambda-client/package.json.declapract.ts',
+  'node-service/bad-practices/simple-lambda-handlers/package.json.declapract.ts',
+  'node/bad-practices/self-deps-not-link/package.json.declapract.ts',
+  'package-json-order/best-practice/package.json.declapract.ts',
+  'persist-with-rds/bad-practices/old-packagejson-script-names/package.json.declapract.ts',
+  'pnpm/bad-practices/npm-overrides/package.json.declapract.ts',
+  'runtime-schemas/bad-practices/joi/package.json.declapract.ts',
+  'serverless/bad-practices/old-sls-plugins/package.json.declapract.ts',
+  'tests-expo/bad-practices/inline-jest-config/package.json.declapract.ts',
+  'tests-node/bad-practices/deprecated-test-deps/package.json.declapract.ts',
+  'uuid/bad-practices/deps-file/package.json.declapract.ts',
+  'uuid/bad-practices/npm-uuidv4/package.json.declapract.ts',
+].sort();
+
+/**
+ * .what = whether a declaration's source text raw-parses `contents` WITHOUT a route through
+ *         `asPackageJSON` — i.e. it is unconverted debt on the ledger.
+ * .why  = a pure transformer leaf, named so the walk composer below reads intent rather than an
+ *         inline regex a reader must simulate to know what "unconverted" means. the `JSON.parse`
+ *         pattern matches `contents` ANYWHERE in the call args, not just as the exact first token —
+ *         so a trimmed or coalesced form (`JSON.parse(contents.trim())`, `JSON.parse(contents ??
+ *         '{}')`) cannot evade the ledger via a wrapped arg. the `asPackageJSON` guard is what
+ *         lets a converted declaration drop off the ledger.
+ */
+const isRawParseOfPackageJSON = (input: { source: string }): boolean =>
+  /JSON\.parse\([^)]*contents/.test(input.source) &&
+  !input.source.includes('asPackageJSON');
+
+/**
+ * .what = every `package.json.declapract.ts` declaration path under the practice tree, relative to
+ *         `src/practices`, that raw-parses `contents` without a route through `asPackageJSON`.
+ */
+const getUnconvertedRelPaths = (): string[] =>
+  getAllPathsUnderDir({ dir: PRACTICES_DIR, skip: PRACTICE_TREE_SKIP_DIRS })
+    .filter((path) => path.endsWith('package.json.declapract.ts'))
+    .filter((path) =>
+      isRawParseOfPackageJSON({ source: readFileSync(path, 'utf8') }),
+    )
+    .map((path) => relative(PRACTICES_DIR, path))
+    .sort();
+
+describe('asPackageJSON adoption — the raw-parse ratchet (D50 clamp)', () => {
+  given('[case1] the current unconverted declarations vs the allowlist', () => {
+    const scene = useBeforeAll(() => ({
+      unconverted: getUnconvertedRelPaths(),
+    }));
+
+    when('[t0] the unconverted set is compared to the ledger', () => {
+      then('no NEW declaration raw-parses off the allowlist', () => {
+        // teeth: add a 27th `package.json.declapract.ts` with a raw `JSON.parse(contents)` and its
+        // path lands here, off the allowlist, reddening this assertion.
+        const newUnconverted = scene.unconverted.filter(
+          (path) => !ALLOWED_UNCONVERTED.includes(path),
+        );
+        expect(newUnconverted).toEqual([]);
+      });
+
+      then('no allowlist row is stale — every entry still raw-parses', () => {
+        // teeth: route one allowlisted declaration through `asPackageJSON` and its allowlist row
+        // must go, or it surfaces here as a stale entry and reddens this assertion. the ledger can
+        // only shrink.
+        const staleAllowlist = ALLOWED_UNCONVERTED.filter(
+          (path) => !scene.unconverted.includes(path),
+        );
+        expect(staleAllowlist).toEqual([]);
+      });
+    });
+  });
+});

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

@@ -0,0 +1,75 @@
+import { join, relative } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = clamps that NO test artifact which declapract's compile would SHIP sits under a
+ *         `best-practice/` directory. compile strips `*.declapract.test.ts` (+ its `.snap`) before
+ *         it publishes a practice — so a UNIT clamp and its snapshot may collocate inside
+ *         `best-practice/`. it does NOT strip `*.declapract.integration.test.ts` (+ its `.snap`),
+ *         nor any other `__snapshots__/` file — those would ship, so they must live at the practice
+ *         ROOT (or another non-`best-practice/` home).
+ * .why  = declapract's emission classifier (getProjectCheckDeclaration) treats every file under
+ *         `best-practice/` that is not `.declapract.`-prefixed as a TEMPLATE to copy into the
+ *         consumer repo, and compile only removes the two `.declapract.test.ts` shapes. a shipped
+ *         `*.declapract.integration.test.ts` materializes at the consumer root as an EQUALS template
+ *         — it `import`s `declapract`/`test-fns` and reads fixtures that exist ONLY in this library,
+ *         so it fails jest load (ENOENT, or absent dev deps). found live on the app-protools-native
+ *         upgrade (#583). the compile-strip asymmetry is `ehmpathy/declapract#109`.
+ * .teeth = move a `*.declapract.integration.test.ts`, its `.snap`, or any other `__snapshots__/`
+ *          file under `best-practice/` and this clamp reddens, with the offender in the diff.
+ * .note = this lives at `src/` (not under any practice's `best-practice/`), so declapract never
+ *         walks it for emission — the same safe home as `src/actionPins.declapract.integration.test.ts`.
+ */
+
+// anchored on `__dirname` (this file sits at `src/`) rather than cwd, so the walk holds wherever
+// jest is invoked from — a nested-scope run or a CI checkout dir cannot silently scan the wrong
+// tree and assert on zero files (a vacuous green). same safe home as
+// `src/actionPins.declapract.integration.test.ts`.
+const repoRoot = join(__dirname, '..');
+const practicesDir = join(repoRoot, 'src/practices');
+
+const isTestArtifact = (path: string): boolean =>
+  path.endsWith('.declapract.test.ts') ||
+  path.endsWith('.declapract.integration.test.ts') ||
+  path.includes('/__snapshots__/');
+
+// compile strips ONLY these two shapes before it publishes a practice, so they never reach a
+// consumer even when they sit under `best-practice/` (a UNIT clamp + its snapshot).
+const isStrippedByCompile = (path: string): boolean =>
+  path.endsWith('.declapract.test.ts') ||
+  path.endsWith('.declapract.test.ts.snap');
+
+const isShippedTestArtifact = (path: string): boolean =>
+  isTestArtifact(path) && !isStrippedByCompile(path);
+
+const isUnderBestPractice = (path: string): boolean =>
+  path.includes('/best-practice/');
+
+describe('practice test files never sit under best-practice/ (#583)', () => {
+  const offenders = getAllPathsUnderDir({ dir: practicesDir, skip: null })
+    .filter(isUnderBestPractice)
+    .filter(isShippedTestArtifact)
+    .map((path) => relative(repoRoot, path))
+    .sort();
+
+  given('[case1] the src/practices tree', () => {
+    when('[t0] every path under a best-practice/ dir is scanned', () => {
+      then('no *.declapract.integration.test.ts ships into a template dir', () => {
+        const integrationTests = offenders.filter((path) =>
+          path.endsWith('.declapract.integration.test.ts'),
+        );
+        expect(integrationTests).toEqual([]);
+      });
+
+      then('no un-stripped __snapshots__/ file ships into a template dir', () => {
+        const snapshots = offenders.filter((path) =>
+          path.includes('/__snapshots__/'),
+        );
+        expect(snapshots).toEqual([]);
+      });
+    });
+  });
+});

package/dist/practices/cache/.declapract.integration.test.ts

@@ -20,7 +20,7 @@ describe('cache practice with ifInstalled', () => {
       slug: 'cache-not-installed',
       clone: './src/practices/cache/.test/assets/repo-without-cache-package',
       symlink: [
-        { at: 'declarations', to: './test/assets/cache/declarations' },
+        { at: 'declarations', to: './src/.test/assets/cache/declarations' },
         { at: 'node_modules', to: 'node_modules' },
       ],
     });
@@ -53,7 +53,7 @@ describe('cache practice with ifInstalled', () => {
       slug: 'cache-outdated',
       clone: './src/practices/cache/.test/assets/repo-with-old-cache-package',
       symlink: [
-        { at: 'declarations', to: './test/assets/cache/declarations' },
+        { at: 'declarations', to: './src/.test/assets/cache/declarations' },
         { at: 'node_modules', to: 'node_modules' },
       ],
     });
@@ -71,8 +71,8 @@ describe('cache practice with ifInstalled', () => {
         const packageJson = JSON.parse(
           await fs.readFile(path.join(tempDir, 'package.json'), 'utf-8'),
         );
-        // should have upgraded from 0.3.0 to 0.4.3
-        expect(packageJson.dependencies['simple-in-memory-cache']).toBe('0.4.3');
+        // should have upgraded from 0.3.0 to the 0.5.1 floor
+        expect(packageJson.dependencies['simple-in-memory-cache']).toBe('0.5.1');
       });
     });
   });
@@ -82,7 +82,7 @@ describe('cache practice with ifInstalled', () => {
       slug: 'cache-valid',
       clone: './src/practices/cache/.test/assets/repo-with-valid-cache-package',
       symlink: [
-        { at: 'declarations', to: './test/assets/cache/declarations' },
+        { at: 'declarations', to: './src/.test/assets/cache/declarations' },
         { at: 'node_modules', to: 'node_modules' },
       ],
     });
@@ -100,8 +100,8 @@ describe('cache practice with ifInstalled', () => {
         const packageJson = JSON.parse(
           await fs.readFile(path.join(tempDir, 'package.json'), 'utf-8'),
         );
-        // should still be 0.4.3 (unchanged, already valid)
-        expect(packageJson.dependencies['simple-in-memory-cache']).toBe('0.4.3');
+        // should still be 0.5.1 (unchanged, already at the floor)
+        expect(packageJson.dependencies['simple-in-memory-cache']).toBe('0.5.1');
       });
     });
   });

package/dist/practices/cache/.test/assets/repo-with-valid-cache-package/package.json

@@ -2,6 +2,6 @@
   "name": "test-project-valid-cache",
   "version": "1.0.0",
   "dependencies": {
-    "simple-in-memory-cache": "0.4.3"
+    "simple-in-memory-cache": "0.5.1"
   }
 }

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

@@ -1,7 +1,7 @@
 {
   "dependencies": {
-    "simple-in-memory-cache": "@declapract{check.minVersion('0.4.3').ifInstalled()}",
-    "simple-on-disk-cache": "@declapract{check.minVersion('1.7.11').ifInstalled()}",
-    "with-simple-cache": "@declapract{check.minVersion('0.16.2').ifInstalled()}"
+    "simple-in-memory-cache": "@declapract{check.minVersion('0.5.1').ifInstalled()}",
+    "simple-on-disk-cache": "@declapract{check.minVersion('1.8.1').ifInstalled()}",
+    "with-simple-cache": "@declapract{check.minVersion('0.17.3').ifInstalled()}"
   }
 }