declapract-typescript-ehmpathy 0.49.14 → 0.50.0

package/dist/.test/assets/git/declarations/practices/tests-any/best-practice/src/.test/useWakeOfLivedb.ts

@@ -0,0 +1,209 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * .what = wake the shared aurora-serverless cluster before a suite runs, when this
+ *         service reaches it — whether it OWNS the db or only invokes peers that do.
+ * .why =
+ *   - the non-prod cluster is aurora-serverless-v2 at min-capacity 0, so it auto-pauses
+ *     when idle; the first downstream query after a pause cold-starts past the 90s test
+ *     timeout and flakes the suite (svc-gateway hit this on mAddCrewMember + the quote suites)
+ *   - a gateway/fan-out service owns NO db of its own, so a db-ownership signal misses it.
+ *     the signal that it REACHES the shared cluster is a tunnel declared in its config —
+ *     `config/prep.json`'s `database.tunnel`. that is the self-gate: a tunnel means a query
+ *     lands on the cluster (direct or via a peer), so wake it; no tunnel means no-op.
+ *   - `rhx use.rds.capacity` opens an ssm tunnel to the cluster and waits for it to accept
+ *     connections, which resumes it for every consumer (incl. deployed lambdas), not just
+ *     the local caller
+ *   - best-effort: a warm db, absent tunnel alias, or absent skill must NEVER break the
+ *     suite, so a wake failure is surfaced loud to stderr (not swallowed) and the suite
+ *     proceeds — a wake is a latency nicety, not a correctness gate; the suite's own
+ *     assertions are the gate
+ *   - ci is skipped: creds arrive via oidc and the local ssm-tunnel path is unavailable there,
+ *     so ci wakes via the dedicated `start:livedb:prep` workflow step instead
+ * .note = this is the LIVEDB half of a suite's db needs — the shared prep cluster its peers query.
+ *         it RESUMES a paused cluster. its pair, `useWakeOfTestdb`, is the LOCAL own-db half: it
+ *         only PREFLIGHTS the local testdb (it cannot start it, so it fails loud with a `start:testdb`
+ *         fix). the two form a symmetric pair; the name reads "wake" for symmetry, the act differs.
+ *         the wake fires for prep OR test access: both reach the deployed prep peers.
+ * .note = `reaches` names HOW the caller reaches the cluster, so the gate reads a signal the caller
+ *         actually has:
+ *         - `via-tunnel` = a node service; gate on `config/prep.json`'s `database.tunnel`
+ *         - `via-gateway` = an expo app, which owns no `config/` dir and reaches the cluster through
+ *           its gateway's peers; its acceptance + integration suites reach a deployment by
+ *           construction, so the test kind itself is the signal and no config gate applies
+ */
+export const useWakeOfLivedb = async (input: {
+  env: 'test' | 'prep' | 'prod' | null;
+  reaches: 'via-tunnel' | 'via-gateway';
+}): Promise<void> => {
+  // decide whether to wake, and which cluster: ci and prod never wake; test + prep wake prep
+  const decision = getWakeDecision({
+    access: input.env,
+    ci: process.env.CI ?? null,
+  });
+  if (!decision.wake) return;
+  const env = decision.access;
+
+  // gate a node service on a declared db tunnel: it is the signal this service reaches the shared
+  // cluster, whether it owns the db (persist-with-rds) or only invokes peers that query it (a gateway).
+  // absent config = no cluster to wake; a malformed config fails loud (names the file), never silent.
+  if (input.reaches === 'via-tunnel' && !asReachesSharedClusterFromConfig({ env }))
+    return;
+
+  // the wake blocks suite start on a local run, so its budget is consumer-bounded: a generous
+  // default (a cold aurora-serverless-v2 resume can exceed 60s), overridable DOWN via
+  // LIVEDB_WAKE_TIMEOUT_MS so a consumer can fail fast on a hung tunnel rather than wait the full cap
+  const timeoutMs = Number(process.env.LIVEDB_WAKE_TIMEOUT_MS) || 180000;
+
+  // best-effort wake: a wake-command failure (a non-zero exit, a timeout kill, an absent binary) is
+  // non-fatal — a warm db or absent skill must not break the suite. but an error that bears no
+  // child-process shape is a malfunction in this module's own logic, so rethrow it (rule.forbid.failhide):
+  // the catch tolerates only the allowlisted wake failures and surfaces the rest.
+  try {
+    wakeSharedCluster({ env, timeoutMs });
+  } catch (error) {
+    if (!isWakeCommandFailure({ error })) throw error;
+    // a non-Error failure shape (e.g. a child-process `{ status, signal }` object) must read
+    // legibly on stderr: `String({...})` yields the useless `[object Object]`, so serialize it.
+    const message =
+      error instanceof Error ? error.message : JSON.stringify(error);
+    warnWakeFailed({ env, message });
+  }
+};
+
+/**
+ * .what = decide whether a run wakes the shared cluster, and which cluster it wakes.
+ * .why  = a pure transformer leaf: the prod refusal and the prep default are the two arms a wrong
+ *         edit turns into a capacity write against production, so they live in one named, clamped
+ *         decision rather than inline in the orchestrator.
+ *         - ci → no wake (ci wakes via its own workflow step; the local ssm path is absent there)
+ *         - prod → no wake (prod never scales to 0; a wake there is an unprompted prod write)
+ *         - test, prep, or undeclared → wake prep, the cluster both test and prep access reach
+ *           (both query the deployed prep peers); an undeclared access never falls to prod
+ */
+export const getWakeDecision = (input: {
+  access: 'test' | 'prep' | 'prod' | null;
+  ci: string | null;
+}): { wake: boolean; access: 'test' | 'prep' | 'prod' } => {
+  if (input.access === 'prod') return { wake: false, access: 'prod' };
+  if (input.ci) return { wake: false, access: 'prep' };
+  return { wake: true, access: 'prep' };
+};
+
+/**
+ * .what = read the raw text of this service's `config/<env>.json`, or null when absent.
+ * .why  = a communicator leaf: the sole filesystem i/o of the wake gate, named so the
+ *         orchestrator composes it rather than embeds an inline `existsSync`/`readFileSync`.
+ * .note = an absent config is benign (a service that declares none reaches no known cluster),
+ *         so absence returns null and the pure decide-step below folds it to false. this leaf
+ *         performs i/o only; it never parses or decides.
+ */
+const readConfigText = (input: {
+  env: 'test' | 'prep' | 'prod';
+}): string | null => {
+  const configPath = join(process.cwd(), 'config', `${input.env}.json`);
+  if (!existsSync(configPath)) return null;
+  return readFileSync(configPath, 'utf8');
+};
+
+/**
+ * .what = decide, from raw config text, whether this service reaches the shared cluster.
+ * .why  = a pure transformer leaf: no i/o, deterministic. a `database.tunnel` in the config =
+ *         a query lands on the cluster (direct or via a peer), so the service reaches it.
+ *         the one fact — does this service reach the cluster — has one shape here, read off
+ *         the same `database.tunnel` signal everywhere, so two readers cannot drift.
+ */
+const asReachesSharedClusterFromConfigText = (input: {
+  text: string;
+}): boolean => {
+  return !!JSON.parse(input.text)?.database?.tunnel;
+};
+
+/**
+ * .what = compose the config read + tunnel decision into a single what-not-how signal.
+ * .why  = the composer of the two leaves above, so `useWakeOfLivedb` reads one intent rather than
+ *         an inline read-parse-decode a reader must simulate.
+ * .note = an absent config folds to false (no known cluster → no wake). but a present-yet-
+ *         unparseable config is NOT benign: it means the consumer authored a config the setup
+ *         cannot read, so a silent `false` would conflate a broken config with an absent tunnel.
+ *         so a parse failure throws a ConstraintError (caller-must-fix, exit 2) that names the
+ *         file + the fix, rather than a raw engine SyntaxError with no file and no remediation.
+ */
+const asReachesSharedClusterFromConfig = (input: {
+  env: 'test' | 'prep' | 'prod';
+}): boolean => {
+  const text = readConfigText({ env: input.env });
+  if (text === null) return false; // no config = no known cluster (benign)
+  try {
+    return asReachesSharedClusterFromConfigText({ text });
+  } catch (cause) {
+    // allowlist the ONLY error the parse-decide leaf can throw — a SyntaxError on malformed json.
+    // an error of any other shape is a malfunction in this module's own logic, not a config the
+    // consumer mis-authored, so surface it unwrapped rather than relabel it a parse failure
+    // (rule.forbid.failhide: a catch allowlists its expected errors and rethrows the rest).
+    if (!(cause instanceof SyntaxError)) throw cause;
+    // a config the consumer authored but the setup cannot parse is a real defect, not "no cluster" —
+    // throw with the path so a malformed config names the file to repair (never a silent false)
+    const configPath = join(process.cwd(), 'config', `${input.env}.json`);
+    throw new ConstraintError(
+      `useWakeOfLivedb: could not parse ${configPath} as JSON — fix the malformed config so the wake gate can read its database.tunnel signal`,
+      { cause },
+    );
+  }
+};
+
+/**
+ * .what = wake the shared cluster by an ssm tunnel that resumes it for every consumer.
+ * .why  = a communicator leaf: the sole subprocess i/o of the wake, named so the orchestrator
+ *         composes it rather than embeds an inline `execSync`. `rhx use.rds.capacity` opens the
+ *         tunnel and waits for the cluster to accept connections, which resumes it (incl. for
+ *         deployed lambdas), not just the local caller.
+ */
+const wakeSharedCluster = (input: {
+  env: 'test' | 'prep' | 'prod';
+  timeoutMs: number;
+}): void => {
+  execSync(`rhx use.rds.capacity --env ${input.env}`, {
+    stdio: 'inherit',
+    timeout: input.timeoutMs,
+  });
+};
+
+/**
+ * .what = surface a wake failure loud to stderr, non-fatal.
+ * .why  = a communicator leaf: the failure sink of the wake, named so the orchestrator composes
+ *         it rather than embeds an inline `process.stderr.write`. a real wake failure — a
+ *         miswired command, an absent skill, a broken rhx binary — must be visible, never hidden;
+ *         the suite proceeds and a downstream cold-start timeout flake is the likely symptom.
+ */
+const warnWakeFailed = (input: {
+  env: 'test' | 'prep' | 'prod';
+  message: string;
+}): void => {
+  process.stderr.write(
+    `useWakeOfLivedb: 'rhx use.rds.capacity --env ${input.env}' failed (non-fatal): ${input.message}\n`,
+  );
+};
+
+/**
+ * .what = decide whether an error is a wake-command failure (safe to tolerate) vs a code malfunction.
+ * .why  = a pure transformer leaf: the allowlist `rule.forbid.failhide` demands. an execSync failure
+ *         bears a child-process shape — a numeric `status` (a non-zero exit), a string `signal` (a
+ *         timeout kill), or a `code` of `ENOENT` (an absent binary) or `ETIMEDOUT` (the cap).
+ *         those are the wake failures the suite intends to tolerate. an error with none of that shape
+ *         is a genuine malfunction in this module's own logic, so the catch rethrows it, never warns
+ *         it away — a best-effort op still distinguishes the failures it ignores from the ones it must not.
+ */
+const isWakeCommandFailure = (input: { error: unknown }): boolean => {
+  const error = input.error;
+  if (!error || typeof error !== 'object') return false;
+  const shape = error as { status?: unknown; signal?: unknown; code?: unknown };
+  if (typeof shape.status === 'number') return true; // child exited non-zero
+  if (typeof shape.signal === 'string') return true; // child killed by a signal (a timeout)
+  if (shape.code === 'ENOENT' || shape.code === 'ETIMEDOUT') return true; // absent binary, cap hit
+  return false; // any other `code` (EACCES, EMFILE, …) is not a wake failure, so it rethrows
+};

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

@@ -0,0 +1,8 @@
+import { asTestKindPresenceCheck } from '../../../../../utils/asTestKindPresenceCheck';
+
+// there should prolly be atleast one integration test per project, in either suffix form (#679)
+export const check = asTestKindPresenceCheck({
+  dir: 'src',
+  suffixOld: '.integration.test.ts',
+  suffixSeam: '._.intg.test.ts',
+});

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

@@ -0,0 +1,7 @@
+import { asPresenceCheck } from '../../../../../utils/asPresenceCheck';
+
+// there should prolly be atleast one unit test per project
+export const check = asPresenceCheck({
+  expected: 'at least one test file under src/ named *.test.ts',
+  hint: 'add a unit test beside the code it covers (e.g. *._.unit.test.ts)',
+});

package/dist/.test/assets/git/declarations/practices/tests-any/build-ifstale.declapract.integration.test.ts

@@ -0,0 +1,124 @@
+import { execSync } from 'child_process';
+import { mkdirSync, readFileSync, utimesSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = proves the `build:ifstale` command the tests-any practice ships (#622): it builds when
+ *         dist holds no stamp, skips when no src/config file is newer than the stamp, rebuilds
+ *         when one is, and ignores a newer test file. `test:acceptance:locally` calls it; ci's
+ *         `test:acceptance` keeps the full build.
+ * .why  = a local acceptance run rebuilt dist on every call, even when dist was fresh. the stamp
+ *         is written only after a green build, so a failed build never reads as fresh.
+ * .why integration = drives a real `bash -c` against a temp repo — a process + fs boundary.
+ */
+const PACKAGE_JSON = JSON.parse(
+  readFileSync(join(__dirname, 'best-practice/package.json'), 'utf-8'),
+);
+const COMMANDS: Record<string, string> = PACKAGE_JSON['scripts'];
+const COMMAND_IFSTALE = COMMANDS['build:ifstale']!;
+
+/**
+ * .what = run the shipped command in a dir with `npm` stood in by a function that records a build
+ * .why  = the build itself is out of scope; the skip-or-build choice is the subject
+ * .note = returns an object, since useThen proxies its result and a bare string cannot be proxied
+ */
+const runCommand = (input: { cwd: string; buildExit: number }): { text: string } => ({
+  text: execSync(
+    `bash -c 'npm() { echo BUILT; mkdir -p dist; return ${input.buildExit}; }; ${COMMAND_IFSTALE.replace(/'/g, `'\\''`)}' || echo EXIT_NONZERO`,
+    { cwd: input.cwd, encoding: 'utf-8', timeout: 10_000 },
+  ),
+});
+
+/**
+ * .what = set a file's mtime to a fixed offset from now, in seconds
+ * .why  = `find -newer` compares mtimes; fixed offsets make the order explicit
+ */
+const setMtime = (input: { path: string; offsetSec: number }): void => {
+  const at = new Date(Date.now() + input.offsetSec * 1000);
+  utimesSync(input.path, at, at);
+};
+
+describe('build:ifstale', () => {
+  given('[case0] the shipped package.json', () => {
+    then('test:acceptance:locally calls build:ifstale, and ci keeps the full build', () => {
+      expect(COMMAND_IFSTALE).toBeDefined();
+      expect(COMMANDS['test:acceptance:locally']).toContain('npm run build:ifstale &&');
+      expect(COMMANDS['test:acceptance']).toContain('npm run build &&');
+      expect(COMMANDS['test:acceptance']).not.toContain('build:ifstale');
+    });
+  });
+
+  given('[case1] a repo with src and no stamp', () => {
+    const dir = genTempDir({ slug: 'build-ifstale' });
+
+    when('[t0] the command runs with no stamp', () => {
+      const output = useThen('it runs', async () => {
+        mkdirSync(join(dir, 'src'), { recursive: true });
+        writeFileSync(join(dir, 'src/index.ts'), 'export {};');
+        writeFileSync(join(dir, 'package.json'), '{}');
+        return runCommand({ cwd: dir, buildExit: 0 });
+      });
+
+      then('it builds and writes the stamp', () => {
+        expect(output.text).toContain('BUILT');
+        expect(readFileSync(join(dir, 'dist/.build.stamp'), 'utf-8')).toEqual('');
+      });
+    });
+
+    when('[t1] the command runs again with no src change', () => {
+      const output = useThen('it runs', async () => {
+        setMtime({ path: join(dir, 'src/index.ts'), offsetSec: -120 });
+        setMtime({ path: join(dir, 'package.json'), offsetSec: -120 });
+        setMtime({ path: join(dir, 'dist/.build.stamp'), offsetSec: -60 });
+        return runCommand({ cwd: dir, buildExit: 0 });
+      });
+
+      then('it skips the build (idempotent rerun)', () => {
+        expect(output.text).not.toContain('BUILT');
+        expect(output.text).toContain('dist is fresh, build skipped');
+      });
+    });
+
+    when('[t2] only a test file is newer than the stamp', () => {
+      const output = useThen('it runs', async () => {
+        writeFileSync(join(dir, 'src/index.test.ts'), 'test.todo("x");');
+        writeFileSync(join(dir, 'src/index.acceptance.test.ts'), 'test.todo("x");');
+        return runCommand({ cwd: dir, buildExit: 0 });
+      });
+
+      then('it still skips the build', () => {
+        expect(output.text).not.toContain('BUILT');
+      });
+    });
+
+    when('[t3] a src file is newer than the stamp', () => {
+      const output = useThen('it runs', async () => {
+        writeFileSync(join(dir, 'src/index.ts'), 'export const x = 1;');
+        return runCommand({ cwd: dir, buildExit: 0 });
+      });
+
+      then('it rebuilds', () => {
+        expect(output.text).toContain('BUILT');
+      });
+    });
+  });
+
+  given('[case2] a repo whose build fails', () => {
+    const dir = genTempDir({ slug: 'build-ifstale-fail' });
+
+    when('[t0] the command runs and the build exits nonzero', () => {
+      const output = useThen('it runs', async () => {
+        mkdirSync(join(dir, 'src'), { recursive: true });
+        writeFileSync(join(dir, 'src/index.ts'), 'export {};');
+        return runCommand({ cwd: dir, buildExit: 1 });
+      });
+
+      then('it fails and writes no stamp, so the next run builds again', () => {
+        expect(output.text).toContain('EXIT_NONZERO');
+        expect(() => readFileSync(join(dir, 'dist/.build.stamp'))).toThrow();
+      });
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/tests-any/changedsince-origin-main.declapract.integration.test.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #531: the shipped `test:unit` + `test:integration` commands scope changed-file
+ *         detection against `origin/main`, NEVER bare `main`.
+ * .why  = a local `main` drifts behind the real trunk the moment a teammate merges without a local
+ *         pull, so `--changedSince=main` drags unrelated already-merged suites into scope — the
+ *         exact stale-ref defect #531 names. `origin/main` is the true fork point, so the scope
+ *         holds only this branch's own change.
+ * .teeth = revert either command to `--changedSince=main` in best-practice/package.json and the
+ *          "no bare main" assertion reddens (the emitted `echo '--changedSince=main'` carries the
+ *          `--changedSince=main'` token; the origin form carries `--changedSince=origin/main'`,
+ *          which does NOT contain it).
+ * .note = the subject is the shipped TEMPLATE, read once from __dirname (a single static-file read,
+ *         as the kin `dpdmrc-exclude-policy` / `commitlint-body-max-line` clamps do). this file
+ *         sits at the practice ROOT, so declapract never emits it (per the #583 relocation convention).
+ */
+describe('tests-any changedSince=origin/main policy', () => {
+  given('the shipped best-practice/package.json', () => {
+    const parsed = JSON.parse(
+      readFileSync(join(__dirname, 'best-practice/package.json'), 'utf8'),
+    );
+    const scripts: Record<string, string> = parsed?.scripts ?? {};
+
+    when('the changed-file test commands are read', () => {
+      then('test:unit scopes against origin/main', () => {
+        expect(scripts['test:unit']).toContain('--changedSince=origin/main');
+      });
+
+      then('test:integration scopes against origin/main', () => {
+        expect(scripts['test:integration']).toContain(
+          '--changedSince=origin/main',
+        );
+      });
+
+      then('neither command scopes against a bare local main', () => {
+        // the emitted flag is quoted: `echo '--changedSince=origin/main'`. a bare-main revert
+        // emits `echo '--changedSince=main'`, whose `--changedSince=main'` token the origin form
+        // never carries — so this token is the precise teeth for the drift #531 forbids.
+        const bareMainToken = "--changedSince=main'";
+        expect(scripts['test:unit']).not.toContain(bareMainToken);
+        expect(scripts['test:integration']).not.toContain(bareMainToken);
+      });
+
+      // the emitted commands are the caller-faced contract: snapshot both so a reword that keeps
+      // the origin token green (a re-ordered flag, a reshaped command) reddens a vibecheck.
+      then('the emitted changed-file commands match snapshot', () => {
+        expect({
+          'test:unit': scripts['test:unit'],
+          'test:integration': scripts['test:integration'],
+        }).toMatchSnapshot('tests-any changed-file commands');
+      });
+    });
+  });
+});