declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/.test/assets/expo-toolchain/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/expo-toolchain/declarations/practices/tests-any/livedb-wake-branches.declapract.integration.test.ts

@@ -0,0 +1,315 @@
+import { readFileSync } from 'node:fs';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+import { getModuleExportsFromTsSource } from '../../utils/getModuleExportsFromTsSource';
+
+/**
+ * .what = executes the REAL shipped `useWakeOfLivedb` template through its deterministic
+ *         decide-gate branches, with every boundary (fs, child_process, env) injected — so
+ *         the wake's actual logic runs, not a source-text pin of it.
+ * .why  = `livedb-wake-globalsetup.declapract.integration.test.ts` pins the wake by SOURCE TEXT
+ *         (it `.toContain`s `process.env.CI`, `=== 'prod'`, `.database?.tunnel`, …). a logic
+ *         bug that keeps those tokens — an inverted gate, a swallowed timeout, a classifier that
+ *         rethrows every failure — sails through every pin green. the decide-steps are pure
+ *         state decisions (ci-skip, prod-skip, tunnel present/absent, parse-failure throw) and
+ *         the failure classifier is a pure allowlist, so they run for real here with no live
+ *         infra — the repo's own `runTargetSlug`/`probeTestDb` pattern.
+ * .the-invariant = each gate lets the wake through ONLY when it should: not-ci ∧ not-prod ∧
+ *         reaches-cluster. a config the consumer authored but the setup cannot parse throws
+ *         (never a silent false). a wake-command failure is tolerated loud; a non-child-process
+ *         error is rethrown.
+ * .teeth = invert any gate in the template (drop the ci return, the prod return, the tunnel
+ *          gate) and the matched case reddens — a caller reaches the cluster it must not, or
+ *          skips one it must. drop the parse-failure throw and the malformed-config case
+ *          reddens. widen the classifier to rethrow-none and the non-child-process case reddens.
+ * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it reads the shipped template off
+ *         the filesystem. no network, no real subprocess — the child_process boundary is stubbed,
+ *         so the deployed cluster is never touched. it sits at the PRACTICE ROOT (not under
+ *         `best-practice/`), because declapract's compile strips `.declapract.test.ts` (+ `.snap`)
+ *         but NOT `.declapract.integration.test.ts` — so an integration clamp collocated inside
+ *         `best-practice/` would SHIP to a consumer and apply as an EQUALS template until
+ *         ehmpathy/declapract#109 lands. the practice-root home keeps it out of the emission set
+ *         while it still clamps the shipped template by path (`rule.require.declapract-integration-tests`).
+ */
+
+const SOURCE_PATH = `${__dirname}/best-practice/src/.test/useWakeOfLivedb.ts`;
+
+/**
+ * .what = transpile the template to CommonJS + execute its sole export with every boundary
+ *         stubbed, then report what crossed each boundary (the exec calls, the stderr warns).
+ * .why  = the template imports `node:fs`, `node:child_process`, `node:path`, `helpful-errors`;
+ *         a require-stub feeds each a controlled fake so the real decide-logic runs against
+ *         inputs this test dictates, and the boundary effects are observed rather than performed.
+ */
+const runUseWakeOfLivedb = async (input: {
+  env: 'test' | 'prep' | 'prod' | null;
+  reaches?: 'via-tunnel' | 'via-gateway'; // the node prepares pass via-tunnel; default to it here
+  ci: boolean;
+  configText: string | null; // null = the config file is absent
+  wakeThrows?: unknown; // when set, the stubbed execSync throws this
+}): Promise<{ execCalls: string[]; stderr: string[] }> => {
+  const execCalls: string[] = [];
+  const stderr: string[] = [];
+
+  class FakeConstraintError extends Error {
+    public readonly cause: unknown;
+    constructor(message: string, meta?: { cause?: unknown }) {
+      super(message);
+      this.name = 'ConstraintError';
+      this.cause = meta?.cause;
+    }
+  }
+
+  const requireStub = (id: string): unknown => {
+    if (id === 'node:child_process')
+      return {
+        execSync: (cmd: string): void => {
+          execCalls.push(cmd);
+          if (input.wakeThrows !== undefined) throw input.wakeThrows;
+        },
+      };
+    if (id === 'node:fs')
+      return {
+        existsSync: (): boolean => input.configText !== null,
+        readFileSync: (): string => input.configText ?? '',
+      };
+    if (id === 'node:path')
+      return { join: (...parts: string[]): string => parts.join('/') };
+    if (id === 'helpful-errors') return { ConstraintError: FakeConstraintError };
+    return {};
+  };
+
+  // control the two process globals the template reads, and capture its stderr warns
+  const priorCi = process.env.CI;
+  if (input.ci) process.env.CI = '1';
+  else delete process.env.CI;
+  const priorWrite = process.stderr.write.bind(process.stderr);
+  (process.stderr as unknown as { write: (s: string) => boolean }).write = (
+    s: string,
+  ): boolean => {
+    stderr.push(s);
+    return true;
+  };
+
+  try {
+    const { useWakeOfLivedb } = getModuleExportsFromTsSource<{
+      useWakeOfLivedb: (i: {
+        env: 'test' | 'prep' | 'prod' | null;
+        reaches: 'via-tunnel' | 'via-gateway';
+      }) => Promise<void>;
+    }>({ source: readFileSync(SOURCE_PATH, 'utf8'), requireStub });
+    await useWakeOfLivedb!({
+      env: input.env,
+      reaches: input.reaches ?? 'via-tunnel',
+    });
+  } finally {
+    (process.stderr as unknown as { write: (s: string) => boolean }).write =
+      priorWrite as never;
+    if (priorCi === undefined) delete process.env.CI;
+    else process.env.CI = priorCi;
+  }
+
+  return { execCalls, stderr };
+};
+
+const TUNNEL_CONFIG = '{"database":{"tunnel":{"lambda":{"host":"x"}}}}';
+
+describe('the useWakeOfLivedb decide-gate runs its real branches (executed, no live infra)', () => {
+  given('a service that reaches the shared cluster (config declares a db tunnel)', () => {
+    when('the caller is not in ci and targets prep', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prep', ci: false, configText: TUNNEL_CONFIG }),
+      );
+      then('it wakes the cluster via the rhx skill for that access', () => {
+        expect(state.execCalls).toEqual(['rhx use.rds.capacity --env prep']);
+      });
+    });
+
+    when('the target access is null (defaults to prep)', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: null, ci: false, configText: TUNNEL_CONFIG }),
+      );
+      then('it wakes the prep cluster by default', () => {
+        expect(state.execCalls).toEqual(['rhx use.rds.capacity --env prep']);
+      });
+    });
+
+    when('the run is in ci', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prep', ci: true, configText: TUNNEL_CONFIG }),
+      );
+      then('it does NOT wake (ci wakes via the dedicated workflow step)', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+
+    when('the target access is prod', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prod', ci: false, configText: TUNNEL_CONFIG }),
+      );
+      then('it does NOT wake (prod never scales to 0)', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+  });
+
+  given('a service that reaches no shared cluster', () => {
+    when('its config is absent', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prep', ci: false, configText: null }),
+      );
+      then('it does NOT wake (no known cluster)', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+
+    when('its config declares no db tunnel', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prep', ci: false, configText: '{"database":{}}' }),
+      );
+      then('it does NOT wake (no reaches-cluster signal)', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+  });
+
+  given('a config the consumer authored but the setup cannot parse', () => {
+    when('the wake gate reads it', () => {
+      then('it throws a ConstraintError that names the parse failure (never a silent false)', async () => {
+        const error = await runUseWakeOfLivedb({
+          env: 'prep',
+          ci: false,
+          configText: '{ not: valid json',
+        }).catch((caught: unknown) => caught);
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).name).toBe('ConstraintError');
+        expect((error as Error).message).toContain('could not parse');
+      });
+    });
+  });
+
+  given('the wake command fails', () => {
+    when('it fails with a child-process shape (a non-zero exit)', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({
+          env: 'prep',
+          ci: false,
+          configText: TUNNEL_CONFIG,
+          wakeThrows: { status: 1 },
+        }),
+      );
+      then('it tolerates the failure (non-fatal) and warns loud to stderr', () => {
+        expect(state.stderr.length).toBe(1);
+      });
+      then('the wake-failure warn matches snapshot', () => {
+        expect(state.stderr[0]).toMatchSnapshot('useWakeOfLivedb wake-failure warn');
+      });
+    });
+
+    when('it fails with a NON-child-process shape (a code malfunction)', () => {
+      then('it rethrows, never warns it away (rule.forbid.failhide)', async () => {
+        const error = await runUseWakeOfLivedb({
+          env: 'prep',
+          ci: false,
+          configText: TUNNEL_CONFIG,
+          wakeThrows: new Error('a real bug in this module'),
+        }).catch((caught: unknown) => caught);
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).message).toBe('a real bug in this module');
+      });
+    });
+  });
+
+  given('a caller that reaches the cluster via its gateway, with no config/ dir (an expo app, #621)', () => {
+    when('the run targets prep, outside ci', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({
+          env: 'prep',
+          reaches: 'via-gateway',
+          ci: false,
+          configText: null,
+        }),
+      );
+      then('it wakes the prep cluster, with no tunnel config to gate on', () => {
+        expect(state.execCalls).toEqual(['rhx use.rds.capacity --env prep']);
+      });
+    });
+
+    when('the run targets prod', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({
+          env: 'prod',
+          reaches: 'via-gateway',
+          ci: false,
+          configText: null,
+        }),
+      );
+      then('it refuses to wake prod, rather than write capacity against production', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+
+    when('the run targets test access', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({
+          env: 'test',
+          reaches: 'via-gateway',
+          ci: false,
+          configText: null,
+        }),
+      );
+      then('it wakes the prep cluster, since test access reaches prep peers', () => {
+        expect(state.execCalls).toEqual(['rhx use.rds.capacity --env prep']);
+      });
+    });
+  });
+});
+
+/**
+ * .what = clamps the pure wake decision the expo port asked for (#621): prod is refused, an
+ *         undeclared access falls to prep (never prod), and ci is skipped.
+ * .teeth = flip the prod arm to `{ wake: true }` and [case1] reddens; default an absent access to
+ *          prod and [case2] reddens.
+ */
+describe('getWakeDecision', () => {
+  const loadGetWakeDecision = (): ((input: {
+    access: 'test' | 'prep' | 'prod' | null;
+    ci: string | null;
+  }) => { wake: boolean; access: 'test' | 'prep' | 'prod' }) => {
+    const { getWakeDecision } = getModuleExportsFromTsSource<{
+      getWakeDecision: (input: {
+        access: 'test' | 'prep' | 'prod' | null;
+        ci: string | null;
+      }) => { wake: boolean; access: 'test' | 'prep' | 'prod' };
+    }>({ source: readFileSync(SOURCE_PATH, 'utf8'), requireStub: () => ({}) });
+    return getWakeDecision!;
+  };
+
+  given('[case1] prod access', () => {
+    then('it refuses to wake prod, rather than write capacity against production', () => {
+      expect(loadGetWakeDecision()({ access: 'prod', ci: null }).wake).toEqual(false);
+    });
+  });
+
+  given('[case2] no declared access', () => {
+    then('an undeclared access falls to prep, never to prod', () => {
+      const decision = loadGetWakeDecision()({ access: null, ci: null });
+      expect(decision).toEqual({ wake: true, access: 'prep' });
+    });
+  });
+
+  given('[case3] test access', () => {
+    then('it wakes the prep cluster its peers query', () => {
+      expect(loadGetWakeDecision()({ access: 'test', ci: null })).toEqual({
+        wake: true,
+        access: 'prep',
+      });
+    });
+  });
+
+  given('[case4] a ci runner', () => {
+    then('it does not wake (ci wakes via its own workflow step)', () => {
+      expect(loadGetWakeDecision()({ access: 'prep', ci: 'true' }).wake).toEqual(false);
+    });
+  });
+});

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/old-acceptance-test-utils.declapract.integration.test.ts

@@ -0,0 +1,122 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { given, then, useThen, when } from 'test-fns';
+
+import { isOnRetiredLambdaTestLib } from '../../utils/asSourceOnRunLambdaEndpoint';
+import { genTempRepoWithDeclarationsOutside } from '../../utils/genTempRepoWithDeclarationsOutside';
+
+// one file-scoped executeApply evaluates the tests-any practice; grant a wide bound
+jest.setTimeout(240_000);
+
+/**
+ * .what = end-to-end proof of the three old-acceptance-test-utils bad-practices (`-`, `-2`, `-3`):
+ *         each moves a `blackbox/lambdas/*.ts` acceptance test off its old util import and, in the
+ *         same apply, off the retired lambda test lib onto runLambdaEndpoint (#650).
+ * .why  = the unit tests prove each fix in isolation; only the real pipeline proves the glob matches
+ *         the consumer file, `getProjectVariables` reads the consumer's declapract.use.yml, and a
+ *         second apply over the output converges (rule.require.declapract-integration-tests).
+ * .note = the declarations mirror holds the tests-any practice alone (the tests-any-only usecase),
+ *         mounted OUTSIDE the temp repo, so the apply evaluates one practice and walks no link back
+ *         into this repo's source. each apply is scoped with `file` too.
+ *         this file sits at the practice ROOT: a test directly under `bad-practices/` has no
+ *         bad-practice name to extract, and declapract throws.
+ */
+const RETIRED_LIB = 'simple-lambda-testing-methods';
+const CASES = [
+  {
+    slug: 'old-acceptance-test-utils',
+    fixture: 'repo-old-acceptance-utils',
+    file: 'blackbox/lambdas/consumeSESEmailEventFromSNS.acceptance.test.ts',
+    oldImport: "import { invokeLambda } from '../_utils/invokeLambda';",
+    whichExpected:
+      "which: { service: 'svc-notifications', function: 'consumeSESEmailEventFromSNS' }",
+  },
+  {
+    slug: 'old-acceptance-test-utils-2',
+    fixture: 'repo-old-acceptance-utils-2',
+    file: 'blackbox/lambdas/addDecoratedImage.acceptance.test.ts',
+    oldImport: "import { locally } from '../__test_utils__/environment';",
+    whichExpected:
+      "which: { service: 'svc-images', function: 'addDecoratedImage' }",
+  },
+  {
+    slug: 'old-acceptance-test-utils-3',
+    fixture: 'repo-old-acceptance-utils-3',
+    file: 'blackbox/lambdas/addDecoratedImage.acceptance.test.ts',
+    oldImport: "import { locally } from '../_utils/environment';",
+    whichExpected:
+      "which: { service: 'svc-images', function: 'addDecoratedImage' }",
+  },
+];
+
+describe('tests-any old-acceptance-test-utils', () => {
+  CASES.forEach((thisCase, index) =>
+    given(`[case${index + 1}] a repo on the ${thisCase.slug} shape`, () => {
+      const tempDir = genTempRepoWithDeclarationsOutside({
+        slug: `declapract-${thisCase.slug}`,
+        clone: `./src/practices/tests-any/.test/assets/${thisCase.fixture}`,
+        declarations: './src/.test/assets/tests-any-only/declarations',
+        symlink: [{ at: 'node_modules', to: 'node_modules' }],
+      });
+      const read = () =>
+        fs.readFile(path.join(tempDir, thisCase.file), 'utf-8');
+      const applyOne = () =>
+        executeApply({
+          config: path.join(tempDir, 'declapract.use.yml'),
+          practice: 'tests-any',
+          file: thisCase.file,
+        });
+
+      when('[t0] the input (before any fix)', () => {
+        then('the file holds the old import, and matches snapshot', async () => {
+          const before = await read();
+          expect(before).toContain(thisCase.oldImport);
+          expect(before).toMatchSnapshot(`${thisCase.slug} — before`);
+        });
+      });
+
+      when('[t1] the fix is applied', () => {
+        const after = useThen('apply succeeds', async () => {
+          await applyOne();
+          return { contents: await read() };
+        });
+
+        then('the old import is gone, and the environment import points at ../environment', () => {
+          expect(after.contents).not.toContain(thisCase.oldImport);
+          expect(after.contents).toContain(
+            "import { locally } from '../environment';",
+          );
+        });
+
+        then('the file is off the retired lib, onto runLambdaEndpoint (#650)', () => {
+          expect(after.contents).not.toContain(RETIRED_LIB);
+          expect(isOnRetiredLambdaTestLib({ contents: after.contents })).toBe(
+            false,
+          );
+          expect(after.contents).toContain('runLambdaEndpoint.onSerialized');
+          expect(after.contents).toContain(thisCase.whichExpected);
+          expect(after.contents).toContain("at: locally ? 'local' : 'cloud'");
+        });
+
+        then('no template token leaks, and the file matches snapshot', () => {
+          expect(after.contents).not.toContain('@declapract{');
+          expect(after.contents).toMatchSnapshot(`${thisCase.slug} — after`);
+        });
+      });
+
+      when('[t2] the fix is applied a second time (idempotency)', () => {
+        const passes = useThen('a second apply over its own output', async () => {
+          const before = await read();
+          await applyOne();
+          return { before, after: await read() };
+        });
+
+        then('the second apply is a no-op', () => {
+          expect(passes.after).toEqual(passes.before);
+        });
+      });
+    }),
+  );
+});

package/dist/.test/assets/expo-toolchain/declarations/practices/tests-any/test-kind-seam.declapract.integration.test.ts

@@ -0,0 +1,87 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { FileCheckContext, FileCheckFunction } from 'declapract';
+import { genTempDir, getError, given, then } from 'test-fns';
+
+import { check as checkServiceAcceptance } from '../tests-service/best-practice/blackbox/**/*.acceptance.test.ts.declapract';
+import { check as checkServiceLambdaAcceptance } from '../tests-service/best-practice/blackbox/lambdas/*.acceptance.test.ts.declapract';
+import { check as checkServiceIntegration } from '../tests-service/best-practice/src/**/*.integration.test.ts.declapract';
+import { check as checkAnyIntegration } from './best-practice/src/**/*.integration.test.ts.declapract';
+
+/**
+ * .what = clamps #679 on every name-keyed test-presence declaration: a repo whose tests carry only
+ *         the `._.` kind seam (`._.intg`, `._.acpt`) passes, as one with the old suffix does; a repo
+ *         with neither form still fails.
+ * .why  = the jest configs match both suffix forms; a declaration that still demanded the old
+ *         suffix would flag a repo that runs that suite just fine.
+ * .teeth = revert any declaration to `FileCheckType.EXISTS` (or to a throw on absent contents) and
+ *          its seam case reddens (an enum is no function; a bare throw rejects the seam repo).
+ * .note = sits at the practice root, so declapract never reads it as a declaration.
+ */
+
+// the single documented cast: these checks read only getProjectRootDirectory() + relativeFilePath.
+const genContextForRoot = (root: string): FileCheckContext =>
+  ({
+    getProjectRootDirectory: () => root,
+    relativeFilePath: 'absent',
+  }) as unknown as FileCheckContext;
+
+const DECLARATIONS: Array<{
+  name: string;
+  check: unknown;
+  dir: string;
+  seamFile: string;
+}> = [
+  {
+    name: 'tests-any integration',
+    check: checkAnyIntegration,
+    dir: 'src',
+    seamFile: 'a._.intg.test.ts',
+  },
+  {
+    name: 'tests-service integration',
+    check: checkServiceIntegration,
+    dir: 'src',
+    seamFile: 'a._.intg.test.ts',
+  },
+  {
+    name: 'tests-service blackbox acceptance',
+    check: checkServiceAcceptance,
+    dir: 'blackbox',
+    seamFile: 'a._.acpt.test.ts',
+  },
+  {
+    name: 'tests-service lambda acceptance',
+    check: checkServiceLambdaAcceptance,
+    dir: 'blackbox/lambdas',
+    seamFile: 'getWidget._.acpt.test.ts',
+  },
+];
+
+describe('#679 test-kind presence accepts the `._.` seam', () => {
+  for (const declaration of DECLARATIONS) {
+    given(`[case] the ${declaration.name} declaration, on a repo with only ${declaration.seamFile}`, () => {
+      then('the check is a function that passes', async () => {
+        expect(typeof declaration.check).toEqual('function');
+        const root = genTempDir({ slug: `seam-${declaration.name.replaceAll(' ', '-')}` });
+        mkdirSync(join(root, declaration.dir), { recursive: true });
+        writeFileSync(join(root, declaration.dir, declaration.seamFile), '// test');
+        await (declaration.check as FileCheckFunction)(null, genContextForRoot(root));
+      });
+    });
+
+    given(`[case] the ${declaration.name} declaration, on a repo with no test of either form`, () => {
+      then('the check still fails', async () => {
+        const root = genTempDir({ slug: `seamless-${declaration.name.replaceAll(' ', '-')}` });
+        mkdirSync(join(root, declaration.dir), { recursive: true });
+        const error = await getError(
+          async () =>
+            (declaration.check as FileCheckFunction)(null, genContextForRoot(root)),
+        );
+        expect(error.message).toContain(declaration.dir);
+        expect(error.message).toMatchSnapshot();
+      });
+    });
+  }
+});