declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/.test/assets/tests-service/declarations/practices/tests-service/best-practice/package.json.declapract.ts

@@ -0,0 +1,101 @@
+import { FileCheckType, type FileContentsFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+
+import { existsSync } from 'node:fs';
+import { readFile } from '../../../utils/readFile';
+
+/**
+ * .what = declare the tests-service package.json, with the `start:livedb:prep` wake command
+ *         included only when this service REACHES the shared aurora-serverless cluster —
+ *         signalled by a `database.tunnel` block in its own `config/prep.json`.
+ * .why  = the cicd-common test workflow already runs `npm run start:livedb:prep --if-present`
+ *         in both the integration + acceptance shards, but the command lived ONLY in
+ *         persist-with-rds — so a gateway/fan-out service (owns no db, but invokes peers that
+ *         query the shared cluster) never got it, the `--if-present` step no-op'd, and the
+ *         min-capacity-0 prep cluster was never woken in ci (#598). tests-service covers the
+ *         whole lambda-service set (gateways AND rds services), so it is the common-denominator
+ *         home for the wake. but a lambda-service that reaches NO cluster (no tunnel) must NOT
+ *         get it — else its `--if-present` step would fire `rhx use.rds.capacity` against a
+ *         cluster it does not use and could FAIL the job (the step has no swallow). so the emit
+ *         is self-gated on the tunnel: the same signal `useWakeOfLivedb` uses locally.
+ * .note = the discriminant is the CONSUMER's `config/prep.json`, not `context.projectPractices` —
+ *         a gateway declares its tunnel in config, not via a db-ownership practice. so this reads
+ *         the neighbor file via `getProjectRootDirectory()`, the check-context escape hatch.
+ * .note = persist-with-rds ALSO declares this command; both emit the IDENTICAL line, so an rds
+ *         service converges on one entry (the multi-declarer convergence pattern, as with the
+ *         repo-root .gitignore). additive by design — this does not touch persist-with-rds.
+ */
+
+/**
+ * .what = read whether the consumer declares a db tunnel in its config/<env>.json.
+ * .why  = the tunnel is the signal a service reaches the shared cluster (owns the db, or invokes
+ *         peers that query it). names the neighbor-read as one intent rather than an inline
+ *         positional decode (rule.forbid.inline-decode-friction).
+ * .note = an ABSENT config is benign — a service that declares no config/<env>.json reaches no
+ *         known cluster, so it returns false and gets no wake command (a false-negative just omits
+ *         a latency nicety, never breaks a suite; contrast the RUNTIME useWakeOfLivedb, likewise soft
+ *         on absence). but a PRESENT-yet-unparseable config is NOT benign: it means the consumer
+ *         authored a config the build cannot read, so a silent `return false` would conflate a
+ *         broken config with an absent tunnel (`rule.forbid.failhide`). so absence returns false
+ *         and a parse failure rethrows with context, naming the file to repair.
+ */
+const readReachesSharedCluster = async (input: {
+  projectRoot: string;
+  env: 'prep';
+}): Promise<boolean> => {
+  const configPath = `${input.projectRoot}/config/${input.env}.json`;
+  if (!existsSync(configPath)) return false; // no config = no known cluster (benign)
+  const raw = await readFile({ filePath: configPath });
+  try {
+    return !!JSON.parse(raw)?.database?.tunnel;
+  } catch (cause) {
+    // a non-Error throw is unexpected here; rethrow it verbatim rather than reclassify it
+    if (!(cause instanceof Error)) throw cause;
+    // a config the consumer authored but the build cannot parse is a real defect, not "no
+    // cluster" — a caller-must-fix condition, so throw a ConstraintError (exit 2) that NAMES the
+    // file, to match asPackageJSON's own class for the identical malformed-JSON case, so a
+    // consumer can machine-distinguish "my config is broken" from a server malfunction (never a
+    // silent false — `rule.forbid.failhide` / `rule.require.exit-code-semantics`)
+    throw new ConstraintError(
+      `tests-service: could not parse ${configPath} as JSON — fix the malformed config so the wake-command gate can read its database.tunnel signal`,
+      { cause },
+    );
+  }
+};
+
+/**
+ * .what = return the package.json without the `start:livedb:prep` wake command; a `scripts` block
+ *         the strip leaves empty is removed too.
+ * .why  = names the tunnel-gated strip as one intent, so `contents` reads what-not-how rather than
+ *         an inline mutate-then-count-then-delete sequence a reader must simulate
+ *         (`rule.forbid.inline-decode-friction`). pure over a fresh clone of `pkg`, so the caller's
+ *         object is untouched and the leaf is independently testable.
+ */
+const withoutWakeCommand = (input: {
+  pkg: Record<string, any>;
+}): Record<string, any> => {
+  const pkg = { ...input.pkg, scripts: { ...input.pkg.scripts } };
+  delete pkg.scripts['start:livedb:prep'];
+  if (Object.keys(pkg.scripts).length === 0) delete pkg.scripts;
+  return pkg;
+};
+
+export const contents: FileContentsFunction = async (context) => {
+  // the superset: the package.json with the wake command included
+  const superset = JSON.parse(
+    await readFile({ filePath: `${__dirname}/package.json` }),
+  );
+
+  // keep the wake command when this service reaches the shared cluster; strip it otherwise
+  const reachesSharedCluster = await readReachesSharedCluster({
+    projectRoot: context.getProjectRootDirectory(),
+    env: 'prep',
+  });
+  const emitted = reachesSharedCluster
+    ? superset
+    : withoutWakeCommand({ pkg: superset });
+
+  return `${JSON.stringify(emitted, null, 2)}\n`;
+};
+
+export const check = FileCheckType.CONTAINS;

package/dist/.test/assets/tests-service/declarations/practices/tests-service/best-practice/src/<star><star>/<star>.integration.test.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // there should prolly be atleast one unit test per project

package/dist/.test/assets/tests-service/declarations/practices/tests-service/best-practice/src/<star><star>/<star>.test.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // there should prolly be atleast one unit test per project

package/dist/.test/assets/tests-service/declarations/practices/tests-service/package.json.declapract.integration.test.ts

@@ -0,0 +1,204 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, getError, given, then, useBeforeAll, when } from 'test-fns';
+
+// executeApply is slow (full usecase evaluation), so widen the jest budget
+jest.setTimeout(180_000); // 3 minutes
+
+/**
+ * .what = end-to-end proof of the #598 wake-command gate, run through the REAL declapract apply
+ *   pipeline against a genTempDir consumer. per `rule.require.declapract-integration-tests`, a
+ *   `contents` fn that READS A NEIGHBOR FILE (here, the consumer's config/prep.json) is REQUIRED to
+ *   carry a pipeline test — a unit test of the exported `contents` never exercises the glob→file
+ *   match, the `getProjectRootDirectory()` resolution against the real consumer root, nor the
+ *   emitted package.json a consumer actually receives.
+ * .why = the declaration emits `start:livedb:prep` only when the consumer declares a db tunnel in
+ *   its own config/prep.json (the signal it REACHES the shared aurora-serverless cluster — owns the
+ *   db, or invokes peers that query it). only a real apply proves declapract (1) matches the
+ *   declaration to `package.json`, (2) reads the neighbor config via `getProjectRootDirectory()`,
+ *   (3) EMITS the wake command for a tunnel consumer, and (4) STRIPS it for a no-tunnel one — so a
+ *   pure-compute lambda's cicd `start:livedb:prep --if-present` step stays a no-op rather than fires
+ *   `rhx use.rds.capacity` against a cluster it does not use (which, with no swallow in the step,
+ *   could fail the job). that is the exact #598 end-state the gate delivers.
+ * .note = the apply is scoped by `file` ONLY, never by `practice` — a file-only apply keeps every
+ *   usecase practice in `projectPractices` while it applies just the package.json plan (per the
+ *   cicd-service provision.yml exemplar). the fixture symlinks a lean `declarations/` MIRROR that
+ *   carries only tests-service, so a file-only apply compiles 1 practice, not the real tree's ~40.
+ * .note = the CONSUMER config/prep.json is WRITTEN into the tempDir per case (not a fixture file),
+ *   so the same base fixture drives both branches — the test owns the discriminant the gate reads.
+ * .note = the emitted package.json is snapshotted in full (both branches), per the rule.
+ */
+
+const FIXTURE = './src/practices/tests-service/.test/assets/demo-repo-service';
+const DECLARATIONS_MIRROR = './src/.test/assets/tests-service/declarations';
+const WAKE_COMMAND = 'rhx use.rds.capacity --env prep';
+
+const TUNNEL_CONFIG = {
+  environment: { access: 'prep' },
+  database: {
+    tunnel: {
+      bastion: 'vpc-main-bastion',
+      lambda: { host: 'cluster.prep.example.com', port: 5432 },
+    },
+  },
+};
+const NO_TUNNEL_CONFIG = {
+  environment: { access: 'prep' },
+};
+
+describe('tests-service package.json — the #598 wake-command gate, end to end', () => {
+  given('[case1] a consumer that reaches the shared cluster (tunnel declared)', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-tests-service-wake-tunnel',
+      clone: FIXTURE,
+      symlink: [
+        { at: 'declarations', to: DECLARATIONS_MIRROR },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const read = (rel: string) => fs.readFile(path.join(tempDir, rel), 'utf-8');
+    const applyPackageJson = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: 'package.json',
+      });
+
+    const state = useBeforeAll(async () => {
+      // the consumer declares a db tunnel — the signal it reaches the shared cluster
+      await fs.mkdir(path.join(tempDir, 'config'), { recursive: true });
+      await fs.writeFile(
+        path.join(tempDir, 'config', 'prep.json'),
+        `${JSON.stringify(TUNNEL_CONFIG, null, 2)}\n`,
+      );
+      await applyPackageJson();
+      const after1 = await read('package.json');
+      await applyPackageJson(); // second apply — prove a fixed point
+      const after2 = await read('package.json');
+      return { after1, after2 };
+    }, 170_000);
+
+    when('[t0] the tests-service package.json declaration is applied', () => {
+      then('the emitted package.json holds the wake command', () => {
+        const pkg = JSON.parse(state.after1);
+        expect(pkg.scripts?.['start:livedb:prep']).toEqual(WAKE_COMMAND);
+      });
+
+      then('the emitted package.json matches snapshot', () => {
+        expect(state.after1).toMatchSnapshot(
+          'package.json — tunnel consumer (wake command emitted)',
+        );
+      });
+    });
+
+    when('[t1] the declaration is applied a second time', () => {
+      // idempotency is scoped to THIS fix's output — the scripts block. the devDependency's
+      // `@declapract{check.minVersion(...)}` token resolves to a concrete version across the two
+      // applies (a declapract minVersion-on-absent-dep behavior shared by every package.json
+      // practice, not introduced by #598), so a whole-file equality would assert a property
+      // declapract does not provide. the wake command this fix emits IS a fixed point.
+      then('the emitted scripts block is a fixed point (idempotent)', () => {
+        expect(JSON.parse(state.after2).scripts).toEqual(
+          JSON.parse(state.after1).scripts,
+        );
+      });
+    });
+  });
+
+  given('[case2] a consumer that reaches NO cluster (no tunnel declared)', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-tests-service-wake-notunnel',
+      clone: FIXTURE,
+      symlink: [
+        { at: 'declarations', to: DECLARATIONS_MIRROR },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const read = (rel: string) => fs.readFile(path.join(tempDir, rel), 'utf-8');
+    const applyPackageJson = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: 'package.json',
+      });
+
+    const state = useBeforeAll(async () => {
+      // the consumer declares NO db tunnel — a pure-compute lambda that reaches no cluster
+      await fs.mkdir(path.join(tempDir, 'config'), { recursive: true });
+      await fs.writeFile(
+        path.join(tempDir, 'config', 'prep.json'),
+        `${JSON.stringify(NO_TUNNEL_CONFIG, null, 2)}\n`,
+      );
+      await applyPackageJson();
+      const after1 = await read('package.json');
+      await applyPackageJson(); // second apply — prove a fixed point
+      const after2 = await read('package.json');
+      return { after1, after2 };
+    }, 170_000);
+
+    when('[t0] the tests-service package.json declaration is applied', () => {
+      then('the emitted package.json STRIPS the wake command', () => {
+        const pkg = JSON.parse(state.after1);
+        expect(pkg.scripts?.['start:livedb:prep']).toBeUndefined();
+      });
+
+      then('the emitted package.json matches snapshot (the stripped shape)', () => {
+        expect(state.after1).toMatchSnapshot(
+          'package.json — no-tunnel consumer (wake command stripped)',
+        );
+      });
+    });
+
+    when('[t1] the declaration is applied a second time', () => {
+      // scoped to this fix's output (see [case1] [t1] note); the strip is a fixed point — the
+      // wake command stays absent across applies.
+      then('the emitted scripts block stays absent (idempotent)', () => {
+        expect(JSON.parse(state.after2).scripts).toEqual(
+          JSON.parse(state.after1).scripts,
+        );
+      });
+    });
+  });
+
+  given('[case3] a consumer whose config/prep.json is present but unparseable', () => {
+    // the failhide clamp (r6 n2): a PRESENT-yet-broken config must FAIL LOUD, never be conflated
+    // with a no-tunnel consumer. teeth: with the old `catch { return false }`, this apply RESOLVED
+    // and stripped the wake command (a malformed config read as "no cluster"); with the rethrow,
+    // the apply REJECTS and names the file. revert the try/catch to a silent false and this reddens.
+    const tempDir = genTempDir({
+      slug: 'declapract-tests-service-wake-broken',
+      clone: FIXTURE,
+      symlink: [
+        { at: 'declarations', to: DECLARATIONS_MIRROR },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const applyPackageJson = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: 'package.json',
+      });
+
+    const state = useBeforeAll(async () => {
+      // the consumer wrote a config the build cannot parse (a real defect, not "no cluster")
+      await fs.mkdir(path.join(tempDir, 'config'), { recursive: true });
+      await fs.writeFile(
+        path.join(tempDir, 'config', 'prep.json'),
+        '{ "database": { "tunnel": ', // truncated JSON — a real author defect
+      );
+      const error = await getError(applyPackageJson());
+      return { error };
+    }, 170_000);
+
+    when('[t0] the tests-service package.json declaration is applied', () => {
+      then('the apply FAILS LOUD, and names the malformed config to fix', () => {
+        expect(state.error).toBeDefined();
+        expect(state.error.message).toContain('could not parse');
+        expect(state.error.message).toContain('config/prep.json');
+      });
+    });
+  });
+});

package/dist/.test/assets/tests-service/declarations/useCases.yml

@@ -0,0 +1,9 @@
+# minimal use case for the tests-service package.json (#598) pipeline test.
+# .why = the wake-command emit branches on the CONSUMER's config/prep.json tunnel (the test writes
+#        it per case), NOT on projectPractices — so one lean usecase with just tests-service carries
+#        every signal the branch reads, while it evaluates only 1 practice (not the ~40 of the real
+#        declarations tree, which blows the jest hook timeout).
+use-cases:
+  service-tests:
+    practices:
+      - tests-service

package/dist/__snapshots__/ancientTargetPublished.declapract.integration.test.ts.snap

@@ -0,0 +1,42 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`the EnvAccess target op emits only slugs the dual-publish scaffold publishes (case=2 no-404) given: the ancient/contemp target ops and the serverless accessByStage scaffold when: the per-tier emitted slugs are derived for both target ops then: the target-slug shape matches snapshot: per-tier target slug vs published stages 1`] = `
+{
+  "perTier": [
+    {
+      "access": "prep",
+      "ancient": "dev",
+      "contemp": "prep",
+    },
+    {
+      "access": "prod",
+      "ancient": "prod",
+      "contemp": "prod",
+    },
+  ],
+  "publishedStages": [
+    "dev",
+    "prep",
+    "prod",
+  ],
+}
+`;
+
+exports[`the EnvAccess target op emits only slugs the dual-publish scaffold publishes (case=2 no-404) given: the ancient/contemp target ops and the serverless accessByStage scaffold when: the scaffold is read then: the derived scaffold shape matches snapshot: dual-publish scaffold shape 1`] = `
+{
+  "accessByStage": {
+    "dev": "prep",
+    "prep": "prep",
+    "prod": "prod",
+  },
+  "deployedTiers": [
+    "prep",
+    "prod",
+  ],
+  "publishedStages": [
+    "dev",
+    "prep",
+    "prod",
+  ],
+}
+`;