declapract-typescript-ehmpathy 0.49.14 → 0.50.0

package/dist/.test/assets/git/declarations/practices/persist-with-rds/database-wrappers-typecheck.declapract.integration.test.ts

@@ -0,0 +1,225 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+import ts from 'typescript';
+
+/**
+ * .what = type-checks the SHIPPED `withDatabaseTransaction` + `withDatabaseContext` templates, and
+ *         the callers an adopter writes over them, under the strictest options the typescript
+ *         practice emits — the verdict for #627 and #633.
+ * .why  = a template the practice emits must compile where it lands. #627: the transaction wrapper
+ *         declared `Promise<Awaited<R>>`, which its own body cannot reach for an unconstrained `R`
+ *         (`await` of a bare generic types as `R`), so tsc failed inside the practice-owned file on
+ *         every adopter. #633: the context wrapper's jsdoc example showed a call that does not
+ *         compile. both defects live in bytes no adopter may edit (the next apply re-emits them),
+ *         so the only place to catch them is here, before they ship.
+ * .teeth = put `Promise<Awaited<R>>` back on the transaction wrapper and the "zero diagnostics"
+ *          assertion reddens with TS2322 inside withDatabaseTransaction.ts (both bodies). put the
+ *          one-arg `findById({ id: 821 })` back into the jsdoc example and the example fixture
+ *          reddens (TS2554 + TS2322).
+ * .note = the fixture holds BOTH transaction bodies — the practice's (context passed through) and
+ *         the one #627 quotes (a fresh context spread into `logic`) — and three callers: an async
+ *         op, a sync op, and a generic op. `getOneDatabaseConnection` is stubbed so no `pg` types
+ *         are needed. INTEGRATION by `rule.forbid.unit.remote-boundaries`: it reads the shipped
+ *         templates off the filesystem. it sits at the practice ROOT, so declapract never emits it.
+ */
+
+const TEMPLATE_DIR = join(__dirname, 'best-practice/src/utils/database');
+const FIXTURE_DIR = '/fixture/src/utils/database';
+
+// the strictest options the typescript-node practice emits (@tsconfig/strictest + its overrides)
+const COMPILER_OPTIONS: ts.CompilerOptions = {
+  strict: true,
+  noUncheckedIndexedAccess: true,
+  noImplicitReturns: true,
+  noFallthroughCasesInSwitch: true,
+  allowUnusedLabels: false,
+  allowUnreachableCode: false,
+  noPropertyAccessFromIndexSignature: false,
+  exactOptionalPropertyTypes: false,
+  noUnusedLocals: false,
+  noUnusedParameters: false,
+  target: ts.ScriptTarget.ES2020,
+  lib: ['lib.es2020.d.ts'],
+  module: ts.ModuleKind.CommonJS,
+  moduleResolution: ts.ModuleResolutionKind.Node10,
+  types: [],
+  noEmit: true,
+};
+
+/**
+ * .what = the stub that stands in for the pg-backed connection factory
+ * .why = the wrappers import only the `DatabaseConnection` type and the factory fn; a stub keeps
+ *        the fixture free of `pg` while the shape the wrappers see stays the real one
+ */
+const STUB_CONNECTION = `
+export interface DatabaseConnection {
+  query: <Row>(args: { sql: string; values?: unknown[] }) => Promise<{ rows: Row[] }>;
+  end: () => Promise<void>;
+}
+export const getOneDatabaseConnection = async (): Promise<DatabaseConnection> => {
+  throw new Error('stub: no database in a type-check fixture');
+};
+`;
+
+/**
+ * .what = the callers an adopter writes over the transaction wrapper: async, sync, and generic
+ * .why = each pins what the wrapper must return; a wrong declared return reddens here or in the
+ *        wrapper itself
+ */
+const asTransactionCallers = (input: { wrapperModule: string }): string => `
+import type { DatabaseConnection } from './getOneDatabaseConnection';
+import { withDatabaseTransaction } from './${input.wrapperModule}';
+
+declare const context: { dbConnection: DatabaseConnection };
+
+// an async op: the wrapper hands back a promise of the resolved value
+const setSurfLesson = withDatabaseTransaction(
+  async (input: { uuid: string }, context: { dbConnection: DatabaseConnection }) => {
+    await context.dbConnection.query({ sql: 'select 1' });
+    return { uuid: input.uuid };
+  },
+);
+export const lessonSet: Promise<{ uuid: string }> = setSurfLesson({ uuid: 'x' }, context);
+
+// a sync op: the wrapper is always async, so the caller sees a promise back
+const getWaveCount = withDatabaseTransaction(
+  (input: { waves: string[] }, _context: { dbConnection: DatabaseConnection }) => input.waves.length,
+);
+export const waveCount: Promise<number> = getWaveCount({ waves: [] }, context);
+
+// a generic op: the wrapper keeps the caller's type parameter
+export const getEcho = async <T>(input: { value: T }): Promise<T> =>
+  withDatabaseTransaction(
+    async (inner: { value: T }, _context: { dbConnection: DatabaseConnection }) => inner.value,
+  )(input, context);
+`;
+
+/**
+ * .what = the example code block inside a template's jsdoc, unwrapped from its ` * ` gutter
+ * .why = the example is a claim about the template's own contract; it must compile like any caller
+ */
+const asJsdocExample = (input: { source: string }): string => {
+  const block = input.source.match(/```\n([\s\S]*?)\n\s*\*\s*```/)?.[1];
+  if (!block) throw new Error('no ``` example block found in the jsdoc');
+  return block
+    .split('\n')
+    .map((line) => line.replace(/^\s*\* ?/, ''))
+    .join('\n');
+};
+
+/**
+ * .what = type-check a set of in-memory fixture files and return each diagnostic as one line
+ * .why = an in-memory host overlays the fixture on the real lib files, so the check needs no disk
+ *        writes and no tsconfig of its own
+ */
+const getDiagnostics = (input: { files: Record<string, string> }): string[] => {
+  const host = ts.createCompilerHost(COMPILER_OPTIONS);
+  const readFileBase = host.readFile.bind(host);
+  const getSourceFileBase = host.getSourceFile.bind(host);
+  const fileExistsBase = host.fileExists.bind(host);
+  host.fileExists = (fileName) =>
+    fileName in input.files || fileExistsBase(fileName);
+  host.directoryExists = (directoryName) =>
+    FIXTURE_DIR.startsWith(directoryName) ||
+    ts.sys.directoryExists(directoryName);
+  host.readFile = (fileName) => input.files[fileName] ?? readFileBase(fileName);
+  host.getSourceFile = (fileName, languageVersion, ...rest) => {
+    const fixture = input.files[fileName];
+    if (fixture !== undefined)
+      return ts.createSourceFile(fileName, fixture, languageVersion, true);
+    return getSourceFileBase(fileName, languageVersion, ...rest);
+  };
+  const program = ts.createProgram({
+    rootNames: Object.keys(input.files),
+    options: COMPILER_OPTIONS,
+    host,
+  });
+  return ts.getPreEmitDiagnostics(program).map((diagnostic) => {
+    const where = diagnostic.file
+      ? `${diagnostic.file.fileName.replace(`${FIXTURE_DIR}/`, '')}:${
+          diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start ?? 0)
+            .line + 1
+        }`
+      : '(global)';
+    return `${where} TS${diagnostic.code}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ')}`;
+  });
+};
+
+describe('persist-with-rds database wrappers type-check where they land (#627, #633)', () => {
+  const transactionTemplate = readFileSync(
+    join(TEMPLATE_DIR, 'withDatabaseTransaction.ts'),
+    'utf8',
+  );
+  const contextTemplate = readFileSync(
+    join(TEMPLATE_DIR, 'withDatabaseContext.ts'),
+    'utf8',
+  );
+
+  // the body #627 quotes: a fresh context spread into `logic`, under the shipped declaration
+  const transactionIssueBody = transactionTemplate.replace(
+    'await logic(input, context)',
+    'await logic(input, { ...context, dbConnection: context.dbConnection })',
+  );
+
+  given('[case1] an adopter with an async, a sync, and a generic op wrapped in withDatabaseTransaction', () => {
+    when('[t0] tsc runs over the practice body and the body #627 quotes', () => {
+      const diagnostics = useBeforeAll(async () => ({
+        lines: getDiagnostics({
+          files: {
+            [`${FIXTURE_DIR}/getOneDatabaseConnection.ts`]: STUB_CONNECTION,
+            [`${FIXTURE_DIR}/withDatabaseTransaction.ts`]: transactionTemplate,
+            [`${FIXTURE_DIR}/withDatabaseTransactionIssueBody.ts`]:
+              transactionIssueBody,
+            [`${FIXTURE_DIR}/callersOfPracticeBody.ts`]: asTransactionCallers({
+              wrapperModule: 'withDatabaseTransaction',
+            }),
+            [`${FIXTURE_DIR}/callersOfIssueBody.ts`]: asTransactionCallers({
+              wrapperModule: 'withDatabaseTransactionIssueBody',
+            }),
+          },
+        }),
+      }));
+
+      then('the issue body differs from the practice body (both bodies are under test)', () => {
+        expect(transactionIssueBody).not.toEqual(transactionTemplate);
+      });
+
+      then('no diagnostic points into the wrapper or its callers', () => {
+        expect(diagnostics.lines).toEqual([]);
+      });
+    });
+  });
+
+  given('[case2] the jsdoc example that withDatabaseContext ships', () => {
+    when('[t0] tsc runs over the example, as an adopter would paste it', () => {
+      const example = asJsdocExample({ source: contextTemplate });
+      const diagnostics = useBeforeAll(async () => ({
+        lines: getDiagnostics({
+          files: {
+            [`${FIXTURE_DIR}/getOneDatabaseConnection.ts`]: STUB_CONNECTION,
+            [`${FIXTURE_DIR}/withDatabaseContext.ts`]: contextTemplate,
+            [`${FIXTURE_DIR}/example.ts`]: [
+              "import type { DatabaseConnection } from './getOneDatabaseConnection';",
+              "import { withDatabaseContext } from './withDatabaseContext';",
+              '// the connection the example reuses, as an adopter inside a transaction holds it',
+              'declare const dbConnection: DatabaseConnection;',
+              'export const run = async (): Promise<void> => {',
+              example,
+              '};',
+            ].join('\n'),
+          },
+        }),
+      }));
+
+      then('the example compiles', () => {
+        expect(diagnostics.lines).toEqual([]);
+      });
+
+      then('the example matches snapshot', () => {
+        expect(example).toMatchSnapshot('withDatabaseContext jsdoc example');
+      });
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/deploy-database-gerunds.declapract.integration.test.ts

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #549: the shipped provision/schema/deploy.database.sh carries no gerund
+ *         (-ing) progress-string, comment, or error — imperative/plain verbs only, per
+ *         rule.forbid.gerunds.
+ * .why  = this template is emitted verbatim to every persist-with-rds consumer, and each
+ *         consumer runs the mechanic gerund hook on the emitted file. a gerund in the
+ *         template trips that hook downstream, so each repo re-fixes it and re-diverges from
+ *         the template — the fix must live upstream, here, once.
+ * .teeth = revert any progress-string to its gerund form (e.g. "create the database" ->
+ *          "creating the database") in best-practice/provision/schema/deploy.database.sh and
+ *          the paired "no gerund" assertion reddens.
+ * .note = the subject is the shipped TEMPLATE, read from __dirname. this file sits at the
+ *         practice ROOT, so declapract never emits it (per the #583 relocation convention).
+ */
+describe('persist-with-rds deploy.database.sh gerund-free', () => {
+  given('the shipped deploy.database.sh', () => {
+    const source = readFileSync(
+      join(__dirname, 'best-practice/provision/schema/deploy.database.sh'),
+      'utf8',
+    );
+
+    // the exact gerund forms #549 removed; none may reappear in the template
+    const forbidden = [
+      'creating',
+      'installing',
+      'granting',
+      'before running this',
+    ];
+
+    when('the template body is read', () => {
+      forbidden.forEach((word) =>
+        then(`it carries no gerund form: "${word}"`, () => {
+          expect(source.includes(word)).toEqual(false);
+        }),
+      );
+
+      then('it keeps the imperative progress strings', () => {
+        expect(source).toContain('🔨 create the database...');
+        expect(source).toContain('🔨 install the extensions...');
+        expect(source).toContain('🔨 create the schema...');
+        expect(source).toContain('🔨 create the cicd user...');
+      });
+
+      then('the emitted deploy.database.sh matches snapshot', () => {
+        // snapshot the whole shipped file so a reworded progress string that stays
+        // gerund-free still reddens a vibecheck in review — the token asserts prove the
+        // gerund class is absent, this proves the exact text (rule.require.contract-snapshot-exhaustiveness)
+        expect(source).toMatchSnapshot('deploy.database.sh');
+      });
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/empty-template-declares-zero-clusters.declapract.integration.test.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps the empty-template invariant the case=7 (stateful-store-alias-not-copy) safety
+ *         rests on: the persist-with-rds declastruct wish declares ZERO rds clusters — `getResources`
+ *         returns only ssm params, and the provision tree imports no cluster/rds/aurora/database
+ *         resource-declaration type.
+ * .why  = case=7's fail-safe is "a lambda under two names is two copies of code; a database under two
+ *         names must be one store with two pointers" — and its load-bearer is that the template holds
+ *         NO cluster for a `fix` to duplicate. a second cluster is the operator's to hand-author,
+ *         against the runbook, never a state the template produces. this is the demoed critipath's
+ *         real test (per `rule.require.experience-catalog-evolution`, a demoed critipath owes a test
+ *         by verification): if a future edit ever declares a cluster in the go-forward wish, the
+ *         "zero clusters to duplicate" premise silently breaks, and this reddens.
+ * .teeth = a cluster resource cannot enter `getResources` without an import of a `DeclaredAws*Cluster`
+ *          / `*Rds` / `*Aurora` / `*Database` type plus its addition to the returned array — so the
+ *          "declares only ssm params" + "imports no cluster type" cases redden the moment one lands.
+ * .note = `.integration.test.ts` because it reads the filesystem (a remote boundary); at the practice
+ *         ROOT (not under best-practice/), so it is neither loaded as a declaration nor copied to a
+ *         consumer. peer of the param-name clamp in `ssm-param-names.declapract.integration.test.ts`.
+ */
+
+// anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different cwd.
+const resourcesPath = join(__dirname, 'best-practice/provision/aws/resources.ts');
+const paramsPath = join(
+  __dirname,
+  'best-practice/provision/aws/resources.parameters.ts',
+);
+
+// any declastruct-aws resource-declaration type that would name an rds/aurora cluster or database.
+// a cluster resource cannot be declared without one of these, so the negation is the teeth.
+const CLUSTER_TYPE_PATTERN = /Declared\w*(Rds|Cluster|Aurora|Database)/;
+
+describe('persist-with-rds wish declares zero rds clusters (empty-template invariant)', () => {
+  const resources = readFileSync(resourcesPath, 'utf8');
+  const params = readFileSync(paramsPath, 'utf8');
+
+  given('[case1] the wish entrypoint resources.ts', () => {
+    when('[t0] resources.ts is read', () => {
+      then('getResources yields only the ssm parameters', () => {
+        expect(resources).toContain('getAllParameters({ choice: null })');
+      });
+
+      then('the wish imports no cluster/rds/aurora/database resource type', () => {
+        expect(resources).not.toMatch(CLUSTER_TYPE_PATTERN);
+      });
+
+      then('the sole declared aws resource declaration is the ssm parameter secure', () => {
+        // the one resource-declaration import from declastruct-aws is DeclaredAwsSsmParameterSecure
+        // (via resources.parameters.ts). resources.ts itself declares no resource type directly.
+        expect(resources).not.toContain('DeclaredAwsRds');
+        expect(resources).not.toContain('DeclaredAwsAurora');
+      });
+    });
+  });
+
+  given('[case2] the resource set resources.parameters.ts', () => {
+    when('[t0] resources.parameters.ts is read', () => {
+      then('getAllParameters yields a DeclaredAwsSsmParameterSecure array (ssm params only)', () => {
+        expect(params).toContain('DeclaredAwsSsmParameterSecure[]');
+      });
+
+      then('the resource set declares no cluster/rds/aurora/database type', () => {
+        expect(params).not.toMatch(CLUSTER_TYPE_PATTERN);
+      });
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/engine-upgrade.declapract.integration.test.ts

@@ -0,0 +1,243 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+import { check as checkDockerfile } from './best-practice/provision/docker/testdb/build-image.dockerfile.declapract';
+
+/**
+ * .what = proves the persist-with-rds surface a postgres major upgrade leans on (#664): a current
+ *         `dialect`, a healthcheck that probes the repo's own db, a testdb pin each repo owns, and a
+ *         skew check that halts a testdb which leads its livedb
+ * .note = the post-upgrade ops (`ALTER EXTENSION … UPDATE`, `ANALYZE`) belong to the repo that
+ *         owns the cutover, so this practice declares none of them
+ * .why = each lives in bytes the practice declares, so every adopter inherited each defect; and
+ *        each new declaration with logic is proven here through the real apply pipeline
+ * .teeth = drop the dao fix and [case1] stays on 10.7; compare the dockerfile exactly and [case1]
+ *          moves the repo pin to the template's; let the skew check pass a lead and [case3] reddens
+ * .note = every touched file is snapshotted in full, before AND after, per
+ *         rule.require.declapract-integration-tests
+ */
+jest.setTimeout(10 * 60 * 1000);
+
+const BEST_PRACTICE_DIR = path.join(__dirname, 'best-practice');
+const FILES = [
+  'codegen.sql.dao.yml',
+  'provision/docker/testdb/build-image.dockerfile',
+];
+
+describe('persist-with-rds engine upgrade surface (#664)', () => {
+  given('[case1] a repo on dialect 10.7 with its own testdb pin', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-persist-with-rds-engine-upgrade',
+      clone:
+        './src/practices/persist-with-rds/.test/assets/demo-repo-on-a-prior-major',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+    const read = (relativePath: string) =>
+      fs
+        .readFile(path.join(tempDir, relativePath), 'utf-8')
+        .catch((error: NodeJS.ErrnoException) => {
+          if (error.code === 'ENOENT') return null; // absent is a valid end-state to assert on
+          throw error; // any other read failure is a malfunction, never "absent"
+        });
+    const applyAll = async () => {
+      for (const file of FILES)
+        await executeApply({
+          config: path.join(tempDir, 'declapract.use.yml'),
+          practice: 'persist-with-rds',
+          file,
+        });
+    };
+
+    when('[t0] the input, before any fix', () => {
+      then('each file matches snapshot', async () => {
+        for (const file of FILES)
+          expect(await read(file)).toMatchSnapshot(`${file} — before`);
+      });
+    });
+
+    when('[t1] apply runs', () => {
+      useThen('apply the declarations', async () => applyAll());
+
+      then('the dao config moves to dialect 17, and keeps its own exclusions', async () => {
+        const after = await read(FILES[0]!);
+        expect(after).toContain('dialect: 17\n');
+        expect(after).not.toContain('dialect: 10.7');
+        expect(after).toContain("- 'SurfReportDraft'");
+        expect(after).toMatchSnapshot(`${FILES[0]} — after`);
+      });
+
+      then('the testdb keeps the pin the repo chose, and the check passes on it', async () => {
+        const after = await read(FILES[1]!);
+        expect(after).toContain('FROM postgres:17.9\n');
+        expect(() =>
+          checkDockerfile(after, {
+            declaredFileContents: readFileSync(
+              path.join(BEST_PRACTICE_DIR, FILES[1]!),
+              'utf-8',
+            ),
+          } as Parameters<typeof checkDockerfile>[1]), // .note = the check reads only declaredFileContents
+        ).not.toThrow();
+        expect(after).toMatchSnapshot(`${FILES[1]} — after`);
+      });
+    });
+
+    when('[t2] apply runs a second time', () => {
+      const scene = useThen('apply again', async () => {
+        const before = await Promise.all(FILES.map((file) => read(file)));
+        await applyAll();
+        const after = await Promise.all(FILES.map((file) => read(file)));
+        return { before, after };
+      });
+
+      then('every file is a fixed point', () => {
+        expect(scene.after).toEqual(scene.before);
+      });
+    });
+  });
+
+  given('[case2] the shipped templates', () => {
+    const read = (relativePath: string) =>
+      readFileSync(path.join(BEST_PRACTICE_DIR, relativePath), 'utf-8');
+
+    then('every sql-schema tool config declares dialect 17', () => {
+      [
+        'provision/schema/control.yml',
+        'codegen.sql.schema.yml',
+        'codegen.sql.types.yml',
+        'codegen.sql.dao.yml',
+      ].forEach((file) => expect(read(file)).toContain('\ndialect: 17\n'));
+    });
+
+    then('the healthcheck probes the repo own database, not a peer repo name', () => {
+      const compose = read('provision/docker/testdb/docker-compose.yml');
+      expect(compose).toContain(
+        "pg_isready -U postgres -d @declapract{variable.databaseName}'",
+      );
+      expect(compose).not.toContain('homeservicesdb');
+    });
+
+    then('the dockerfile check flags a drift outside the pin line', () => {
+      expect(() =>
+        checkDockerfile('FROM postgres:17.9\n', {
+          declaredFileContents: read(
+            'provision/docker/testdb/build-image.dockerfile',
+          ),
+        } as Parameters<typeof checkDockerfile>[1]),
+      ).toThrow('build-image.dockerfile must match the template');
+    });
+  });
+
+  given('[case3] check-engine-skew.sh', () => {
+    const runSkewCheck = (input: { args: string[]; testdbPin: string | null }) => {
+      const dir = genTempDir({ slug: 'check-engine-skew' });
+      const dockerfile = path.join(dir, 'build-image.dockerfile');
+      if (input.testdbPin !== null)
+        writeFileSync(dockerfile, `${input.testdbPin}\n`);
+      const skewCheckPath = path.join(
+        BEST_PRACTICE_DIR,
+        'provision/docker/testdb/check-engine-skew.sh',
+      );
+      const result = spawnSync(
+        'bash',
+        [skewCheckPath, '--dockerfile', dockerfile, ...input.args],
+        {
+          encoding: 'utf-8',
+          env: { ...process.env, AWS_PROFILE: 'check-engine-skew-absent-profile' },
+        },
+      );
+      // mask both host paths, so the snapshot holds on any checkout
+      const asMasked = (text: string) =>
+        text
+          .replaceAll(dockerfile, '<dockerfile>')
+          .replaceAll(skewCheckPath, '<check-engine-skew.sh>');
+      return {
+        status: result.status,
+        stdout: asMasked(result.stdout),
+        stderr: asMasked(result.stderr),
+      };
+    };
+
+    [
+      {
+        name: 'the testdb leads the livedb',
+        testdbPin: 'FROM postgres:17.11',
+        args: ['--livedb-version', '13.23'],
+        status: 2,
+        expected: 'pin the testdb to postgres 13',
+      },
+      {
+        name: 'the testdb leads a livedb below its declared target',
+        testdbPin: 'FROM postgres:17.11',
+        args: ['--livedb-version', '13.23', '--declared-version', '17.11'],
+        status: 2,
+        expected: 'the livedb sits below its declared target 17',
+      },
+      {
+        name: 'the testdb trails the livedb',
+        testdbPin: 'FROM postgres:13.20',
+        args: ['--livedb-version', '17.11'],
+        status: 0,
+        expected: '::warning title=engine skew::',
+      },
+      {
+        name: 'the majors match',
+        testdbPin: 'FROM postgres:17.11',
+        args: ['--livedb-version', '17.7'],
+        status: 0,
+        expected: 'majors match',
+      },
+      {
+        name: 'the dockerfile has no postgres pin',
+        testdbPin: 'FROM alpine:3',
+        args: ['--livedb-version', '17.11'],
+        status: 1,
+        expected: "💥 MalfunctionError: no 'FROM postgres:<major>' pin found",
+      },
+      {
+        name: 'a flag with no value',
+        testdbPin: 'FROM postgres:17.11',
+        args: ['--livedb-version'],
+        status: 2,
+        expected: '✋ ConstraintError: --livedb-version needs a value',
+      },
+      {
+        name: 'the livedb read fails',
+        testdbPin: 'FROM postgres:17.11',
+        args: [
+          '--config',
+          path.join(BEST_PRACTICE_DIR, 'config/test.json'),
+        ],
+        status: 1,
+        expected: 'rds:DescribeDBClusters',
+      },
+    ].forEach((thisCase, index) =>
+      when(`[t${index}] ${thisCase.name}`, () => {
+        const result = useThen('the check runs', async () =>
+          runSkewCheck({ args: thisCase.args, testdbPin: thisCase.testdbPin }),
+        );
+
+        then(`it exits ${thisCase.status} and says so`, () => {
+          expect(result.status).toEqual(thisCase.status);
+          expect(`${result.stdout}${result.stderr}`).toContain(thisCase.expected);
+        });
+
+        then('the check lines match the snapshot', () => {
+          expect({
+            status: result.status,
+            stdout: result.stdout,
+            stderr: result.stderr
+              .split('\n')
+              .filter((line) => /^(✋|💥| {3})/.test(line))
+              .join('\n'),
+          }).toMatchSnapshot();
+        });
+      }),
+    );
+  });
+});