create-stitchkit 0.4.0 → 0.4.2

package/template/scripts/acceptance-local.ts

@@ -0,0 +1,144 @@
+/**
+ * The runtime gates, against a deployment this script owns.
+ *
+ * `runtime:smoke` and `e2e` check a RUNNING deployment, so a gate list has to
+ * bring one up. The wrong way to do that — and the way this replaced — is
+ * `pm2:prod`: it applies the declared migrations and reloads the developer's
+ * own PM2 daemon, so "run these before handing work off" quietly meant "deploy".
+ * A gate may not mutate a deployment; it may only create and destroy its own.
+ *
+ * So everything here is this run's and nothing else's: its own `PM2_HOME`, its
+ * own ephemeral ports, its own public-host allowlist, its own database, and a
+ * stop that names the roles the declaration declares rather than deleting
+ * whatever the daemon happened to hold.
+ *
+ * The database is the last thing this owned. It used to inherit `DATABASE_URL`,
+ * which made a GATE a writer: the repository example's smoke posts a refresh,
+ * and that upserts. It now runs against `ACCEPTANCE_DATABASE_URL` and refuses to
+ * start when that is unset or names the deployment's own database — and the
+ * deployment's URL is not in the child environment at all, so no role here can
+ * reach it even by asking.
+ */
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { appDeclaration } from '../packages/config/src/declaration';
+import { resolveAcceptanceDatabase } from './acceptance-database';
+import { awaitRolesAnswering, declaredRoleReadiness } from './readiness';
+import { assertBuildArtifacts, runDeclaredReleaseSteps } from './release-steps';
+import { deploymentEnvironment } from './tooling-env';
+
+const root = resolve(import.meta.dir, '..');
+
+function freePort(): number {
+  const listener = Bun.listen({
+    hostname: '127.0.0.1',
+    port: 0,
+    socket: { data: () => undefined },
+  });
+  const port = listener.port;
+  listener.stop(true);
+  return port;
+}
+
+async function run(command: string[], env: Record<string, string>): Promise<void> {
+  const child = Bun.spawn(command, {
+    cwd: root,
+    env,
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  const exitCode = await child.exited;
+  if (exitCode !== 0) throw new Error(`${command.join(' ')} failed with exit code ${exitCode}`);
+}
+
+if (!Bun.which('pm2')) {
+  throw new Error(
+    'pm2 is required to run the local acceptance gate. Install it with `bun add --global pm2`, then rerun.',
+  );
+}
+
+assertBuildArtifacts();
+
+const home = await mkdtemp(join(tmpdir(), 'acceptance-local-'));
+const apiPort = freePort();
+const webPort = freePort();
+const apiOrigin = `http://127.0.0.1:${apiPort}`;
+const webOrigin = `http://127.0.0.1:${webPort}`;
+const base = deploymentEnvironment(root);
+// Before anything starts, and before the deployment's own URL is copied into
+// the child environment: a refusal here costs a message, a missing one costs
+// rows in someone's database.
+const acceptanceDatabaseUrl = resolveAcceptanceDatabase(base);
+const environment: Record<string, string> = {};
+for (const [name, value] of Object.entries(base)) {
+  if (value !== undefined) environment[name] = value;
+}
+delete environment.ACCEPTANCE_DATABASE_URL;
+Object.assign(environment, {
+  NODE_ENV: 'production',
+  // The one address every role, every migration and every gate here will see.
+  DATABASE_URL: acceptanceDatabaseUrl,
+  PM2_HOME: home,
+  API_PORT: String(apiPort),
+  WEB_PORT: String(webPort),
+  INTERNAL_API_URL: apiOrigin,
+  SMOKE_API_ORIGIN: apiOrigin,
+  SMOKE_WEB_ORIGIN: webOrigin,
+  PLAYWRIGHT_BASE_URL: webOrigin,
+  // The portability proof asks this deployment to answer as addresses other
+  // than the one it is dialled on. Those addresses belong to the CHECK, so
+  // they are supplied here rather than written into the project's own
+  // `.env.example`, where they would be policy a deployment carries for real.
+  PUBLIC_WEB_HOSTS: `127.0.0.1:${webPort},alpha.example,beta.example:8443`,
+});
+
+// Boxed, so a thrown `undefined` is still recorded as a failure.
+let failure: { error: unknown } | undefined;
+try {
+  // The declared migrations, against the acceptance database. A deployment is
+  // brought to its source before its roles start — that is a property of this
+  // deployment too, and skipping it here would mean the gates run against
+  // whatever schema the throwaway database happened to have.
+  await runDeclaredReleaseSteps(environment);
+  await run(['pm2', 'start', 'ecosystem.config.cjs', '--update-env'], environment);
+  await awaitRolesAnswering(declaredRoleReadiness(appDeclaration, environment));
+  await run(['bun', 'run', 'runtime:smoke'], environment);
+  await run(['bun', 'run', 'e2e'], environment);
+  console.log(
+    `Local acceptance passed: ${appDeclaration.roles.map((role) => role.name).join(' and ')} answered on ephemeral ports, and both runtime gates are green`,
+  );
+} catch (error) {
+  failure = { error };
+}
+
+// Only what this run started, named from the declaration. `pm2 delete all`
+// would delete every application in the daemon it is pointed at — and pointing
+// it at the wrong home is one forgotten variable away.
+const cleanupFailures: unknown[] = [];
+for (const step of [
+  () =>
+    run(
+      [
+        'pm2',
+        'delete',
+        ...appDeclaration.roles.map((role) => `${appDeclaration.identity.slug}-${role.name}`),
+      ],
+      environment,
+    ),
+  () => run(['pm2', 'kill'], environment),
+  () => rm(home, { recursive: true, force: true }),
+]) {
+  try {
+    await step();
+  } catch (error) {
+    cleanupFailures.push(error);
+  }
+}
+
+const failures = [...(failure ? [failure.error] : []), ...cleanupFailures];
+if (failures.length === 1) throw failures[0];
+if (failures.length > 1) {
+  throw new AggregateError(failures, 'Local acceptance failed, and so did its cleanup');
+}

package/template/scripts/build-inputs.test.ts

@@ -3,8 +3,8 @@ import { createHash } from 'node:crypto';
 import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import type { ProjectDeclaration } from 'stitchkit/declaration';
 import { appDeclaration } from '../packages/config/src/declaration';
-import type { ProjectDeclaration } from '../packages/config/src/project-declaration.generated';
 import { assertDeclaredBuildInputs } from './build-inputs';
 
 function digestOf(text: string): string {

package/template/scripts/build-inputs.ts

@@ -1,8 +1,8 @@
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import type { ProjectDeclaration } from 'stitchkit/declaration';
 import { appDeclaration } from '../packages/config/src/declaration';
-import type { ProjectDeclaration } from '../packages/config/src/project-declaration.generated';
 
 const root = resolve(import.meta.dir, '..');
 
@@ -20,8 +20,9 @@ const root = resolve(import.meta.dir, '..');
  * runtime (the default, and what this template does), read a frozen export
  * whose digest is declared here, or generate the bytes as a release step. This
  * file owns the second one. It is deliberately a no-op for a project that
- * declares no inputs — absent means "this build reads no data", which is an
- * answer, not a gap.
+ * declares no inputs — absent means "this build reads no DECLARED data", which
+ * is an answer rather than a gap. It is the author's statement, not a traced
+ * fact: nothing here sandboxes the build to see what it really opened.
  */
 export function assertDeclaredBuildInputs(
   declaration: ProjectDeclaration = appDeclaration,

package/template/scripts/build-stamp.test.ts

@@ -0,0 +1,151 @@
+import { afterAll, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { appDeclaration } from '../packages/config/src/declaration';
+import {
+  assertArtifactMatchesSource,
+  BUILD_STAMP_PATH,
+  sourceDigest,
+  writeBuildStamp,
+} from './build-stamp';
+
+const created: string[] = [];
+afterAll(async () => {
+  for (const path of created) await rm(path, { recursive: true, force: true });
+});
+
+async function tree(files: Record<string, string>): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'build-stamp-'));
+  created.push(root);
+  for (const [relative, contents] of Object.entries(files)) {
+    const path = join(root, relative);
+    await mkdir(join(path, '..'), { recursive: true });
+    await writeFile(path, contents);
+  }
+  return root;
+}
+
+describe('a release starts this source, not a previous one', () => {
+  test('a stamped tree passes its own check', async () => {
+    const root = await tree({ 'src/index.ts': 'export const a = 1;\n' });
+    writeBuildStamp(root, []);
+    expect(() => assertArtifactMatchesSource(root, [])).not.toThrow();
+  });
+
+  test('an edited source file makes the artifact refuse to start', async () => {
+    // The failure this exists for: `pm2:prod` without a build applies THIS
+    // source's migrations and starts the previous source's `dist`. The schema
+    // moves ahead of the code, and rolling the code back does not undo it.
+    const root = await tree({ 'src/index.ts': 'export const a = 1;\n' });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, 'src/index.ts'), 'export const a = 2;\n');
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(/not this source's/);
+  });
+
+  test('a new source file counts, without anyone listing it', async () => {
+    const root = await tree({ 'src/index.ts': 'export const a = 1;\n' });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, 'src/added.ts'), 'export const b = 2;\n');
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(/not this source's/);
+  });
+
+  test('a moved file changes the digest even with every byte unchanged', async () => {
+    const root = await tree({ 'src/index.ts': 'export const a = 1;\n' });
+    const before = sourceDigest(root, []);
+    await rm(join(root, 'src/index.ts'));
+    await writeFile(join(root, 'src/moved.ts'), 'export const a = 1;\n');
+    expect(sourceDigest(root, [])).not.toBe(before);
+  });
+
+  test('a binding is not an input — editing `.env` does not refuse the artifact', async () => {
+    // Deliberate, and the one exclusion that is a JUDGEMENT rather than a fact
+    // about outputs. This project forbids build-time environment reads —
+    // `check-authored` refuses direct environment access outside its declared
+    // boundaries, and the packed lane builds against a database that accepts
+    // nothing — so hashing
+    // `.env` would refuse a correct artifact every time a deployment edited its
+    // own environment.
+    const root = await tree({ 'src/index.ts': 'export const a = 1;\n', '.env': 'PORT=1\n' });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, '.env'), 'PORT=2\n');
+    expect(() => assertArtifactMatchesSource(root, [])).not.toThrow();
+  });
+
+  test('a Markdown file counts, because a project may import one', async () => {
+    // The digest used to skip every `.md`, every test file and every directory
+    // called `generated`. All three are true of THIS project today and none is
+    // true by construction: MDX is an import, and a checked-in directory may be
+    // called anything. A digest that answers "fresh" about a stale build is the
+    // failure the stamp exists to prevent.
+    const root = await tree({
+      'src/index.ts': 'export const a = 1;\n',
+      'content/post.md': 'before\n',
+    });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, 'content/post.md'), 'after\n');
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(/not this source's/);
+  });
+
+  test('a directory merely NAMED generated is source', async () => {
+    const root = await tree({
+      'src/index.ts': 'export const a = 1;\n',
+      'src/generated/checked-in.ts': 'export const kept = 1;\n',
+    });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, 'src/generated/checked-in.ts'), 'export const kept = 2;\n');
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(/not this source's/);
+  });
+
+  test('a test file counts too', async () => {
+    const root = await tree({
+      'src/index.ts': 'export const a = 1;\n',
+      'src/index.test.ts': 'test("x", () => {});\n',
+    });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, 'src/index.test.ts'), 'test("y", () => {});\n');
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(/not this source's/);
+  });
+
+  test('what the DECLARATION calls output is skipped, by path and not by name', async () => {
+    // The one list a deployment tool already reads. `packages/db/src/generated`
+    // is skipped because `build.artifacts` says it is produced, not because of
+    // the word in it.
+    const artifacts = ['packages/db/src/generated', 'packages/frontend/.next'];
+    const root = await tree({
+      'src/index.ts': 'export const a = 1;\n',
+      'node_modules/pkg/index.js': 'module.exports = 1;\n',
+      'packages/db/src/generated/client.ts': 'export const generated = 1;\n',
+      'packages/frontend/.next/build-manifest.json': '{}\n',
+    });
+    writeBuildStamp(root, artifacts);
+    await writeFile(join(root, 'node_modules/pkg/index.js'), 'module.exports = 2;\n');
+    await writeFile(
+      join(root, 'packages/db/src/generated/client.ts'),
+      'export const generated = 2;\n',
+    );
+    await writeFile(join(root, 'packages/frontend/.next/build-manifest.json'), '{"c":1}\n');
+    expect(() => assertArtifactMatchesSource(root, artifacts)).not.toThrow();
+  });
+
+  test('an undeclared build output is NOT skipped', async () => {
+    // Falsification for the test above: without it, a helper that skipped every
+    // `.next` anywhere would pass it just as well.
+    const root = await tree({
+      'src/index.ts': 'export const a = 1;\n',
+      'packages/frontend/.next/build-manifest.json': '{}\n',
+    });
+    writeBuildStamp(root, []);
+    await writeFile(join(root, 'packages/frontend/.next/build-manifest.json'), '{"c":1}\n');
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(/not this source's/);
+  });
+
+  test('this project declares its outputs, so the default skips them', async () => {
+    expect(appDeclaration.build?.artifacts).toContain('packages/db/src/generated');
+  });
+
+  test('no stamp at all is refused, not assumed fresh', async () => {
+    const root = await tree({ 'src/index.ts': 'export const a = 1;\n' });
+    expect(() => assertArtifactMatchesSource(root, [])).toThrow(new RegExp(BUILD_STAMP_PATH));
+  });
+});

package/template/scripts/build-stamp.ts

@@ -0,0 +1,169 @@
+/**
+ * What the artifact was built FROM, so a release can tell whether it still is.
+ *
+ * `assertBuildArtifacts()` checked that the declared paths exist. Existence is
+ * not freshness: `pm2:prod` run without a build applies the migrations this
+ * source declares and then starts the `dist` and `.next` of an earlier one. The
+ * schema moves ahead of the code, which is the worst direction — rolling the
+ * code back does not roll the schema back with it.
+ *
+ * So the build leaves a stamp: one digest over the source it read. The release
+ * recomputes it and compares. A digest, not a timestamp, because a checkout
+ * rewrites every mtime and a formatter rewrites some for no change at all —
+ * both would make the gate cry wolf, and a gate nobody believes is worse than
+ * none.
+ *
+ * **Everything is source until something says otherwise, and the something is
+ * named.** The first version of this listed what to skip by *kind* — every
+ * `.md`, every test file, every directory called `generated` — which reads as
+ * "these cannot affect a build" and is only true of the project as it stands
+ * today. A project that imports MDX, or keeps checked-in source in a directory
+ * it happened to call `generated`, would change its content, keep its digest,
+ * and be told its old artifact was current. A digest that answers "fresh" about
+ * a stale build is worse than no digest.
+ *
+ * So the exclusions are now exactly three kinds, each named rather than guessed:
+ *
+ * - **The build's own OUTPUTS**, read from `build.artifacts` in the project
+ *   declaration. One source of truth: a project that adds an artifact is
+ *   covered by declaring it, and `packages/db/src/generated` is skipped because
+ *   the declaration calls it output — not because of its name.
+ * - **Not this project's source at all**: `node_modules`, `.git`. (`bun.lock`
+ *   is source and is hashed.)
+ * - **Runtime state**: `.env*`, logs, and the directories a test run writes.
+ *   `.env` is deliberate and not an oversight — a binding is not an input to
+ *   this build, which is the whole point of forbidding `NEXT_PUBLIC_*` env
+ *   reads and of building the packed lane against a database that accepts
+ *   nothing. Hashing it would refuse a correct artifact every time a deployment
+ *   edited its own environment: the same gate, crying wolf in the other
+ *   direction.
+ *
+ * The cost is that editing a README or a test now asks for a rebuild before a
+ * release. That is the safe direction: the gate can be wrong about "stale", and
+ * must never be wrong about "fresh".
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { z } from 'zod';
+import { appDeclaration } from '../packages/config/src/declaration';
+
+const root = resolve(import.meta.dir, '..');
+
+export const BUILD_STAMP_PATH = '.build-stamp.json';
+
+/** Not this project's source, and state a test run leaves behind. */
+const IGNORED_DIRECTORIES = new Set([
+  'node_modules',
+  '.git',
+  'coverage',
+  'test-results',
+  'playwright-report',
+]);
+
+function isIgnoredFile(name: string): boolean {
+  return (
+    name === BUILD_STAMP_PATH ||
+    // Written by `next typegen`, which `bun run check` runs — a generated file
+    // sitting at a package root rather than inside a declared artifact, and one
+    // that exists or not depending on whether anyone has run `check` yet.
+    name === 'next-env.d.ts' ||
+    // A binding, not an input. See the note above.
+    name.startsWith('.env') ||
+    name.endsWith('.log')
+  );
+}
+
+/** The declared outputs, as normalised relative paths. */
+function outputPaths(artifacts: readonly string[]): string[] {
+  return artifacts.map((artifact) => artifact.replaceAll('\\', '/').replace(/\/+$/, ''));
+}
+
+function sourceFiles(
+  from: string,
+  outputs: readonly string[],
+  directory: string = from,
+  found: string[] = [],
+): string[] {
+  for (const entry of readdirSync(directory).sort()) {
+    const path = join(directory, entry);
+    const relativePath = relative(from, path).replaceAll('\\', '/');
+    if (outputs.includes(relativePath)) continue;
+    if (statSync(path).isDirectory()) {
+      if (IGNORED_DIRECTORIES.has(entry)) continue;
+      sourceFiles(from, outputs, path, found);
+    } else if (!isIgnoredFile(entry)) {
+      found.push(path);
+    }
+  }
+  return found;
+}
+
+/**
+ * One digest over every file a build of this project reads.
+ *
+ * `artifacts` defaults to what the declaration says the build produces, so the
+ * one list a deployment tool reads is the one this skips.
+ */
+export function sourceDigest(
+  from: string = root,
+  artifacts: readonly string[] = appDeclaration.build?.artifacts ?? [],
+): string {
+  const digest = createHash('sha256');
+  for (const path of sourceFiles(from, outputPaths(artifacts))) {
+    // The PATH goes in too: moving a file changes the build without changing
+    // any byte inside it.
+    digest.update(relative(from, path));
+    digest.update('\0');
+    digest.update(readFileSync(path));
+    digest.update('\0');
+  }
+  return `sha256:${digest.digest('hex')}`;
+}
+
+const BuildStampSchema = z.object({
+  schemaVersion: z.literal(1),
+  source: z.string().startsWith('sha256:'),
+});
+
+export function writeBuildStamp(
+  from: string = root,
+  artifacts: readonly string[] = appDeclaration.build?.artifacts ?? [],
+): string {
+  const source = sourceDigest(from, artifacts);
+  writeFileSync(
+    join(from, BUILD_STAMP_PATH),
+    `${JSON.stringify({ schemaVersion: 1, source }, null, 2)}\n`,
+  );
+  return source;
+}
+
+/**
+ * Refuse an artifact that is not this source's.
+ *
+ * A missing stamp is refused too, and deliberately: it means the artifact was
+ * produced by something other than this build, and "we cannot tell" is not a
+ * reason to start it.
+ */
+export function assertArtifactMatchesSource(
+  from: string = root,
+  artifacts: readonly string[] = appDeclaration.build?.artifacts ?? [],
+): void {
+  const path = join(from, BUILD_STAMP_PATH);
+  if (!existsSync(path)) {
+    throw new Error(
+      `No build stamp beside the artifacts (${BUILD_STAMP_PATH}). Run \`bun run build\` — a release will not start an artifact it cannot tie to this source.`,
+    );
+  }
+  const stamp = BuildStampSchema.parse(JSON.parse(readFileSync(path, 'utf8')));
+  const current = sourceDigest(from, artifacts);
+  if (stamp.source !== current) {
+    throw new Error(
+      `The built artifacts are not this source's: the stamp says ${stamp.source.slice(0, 19)}…, the tree hashes to ${current.slice(0, 19)}…. Run \`bun run build\` before releasing — otherwise the declared migrations of this source are applied to a deployment running the previous one.`,
+    );
+  }
+}
+
+if (import.meta.main) {
+  console.log(`Build stamped: ${writeBuildStamp()}`);
+}

package/template/scripts/client-boundary.test.ts

@@ -0,0 +1,117 @@
+import { afterAll, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import {
+  type ClientBoundaryScan,
+  clientEntries,
+  findDeclarationLeaks,
+  specifiers,
+} from './client-boundary';
+
+const root = resolve(import.meta.dir, '..');
+const project: ClientBoundaryScan = {
+  root,
+  frontendSrc: join(root, 'packages/frontend/src'),
+  declaration: join(root, 'packages/config/src/declaration.ts'),
+};
+
+describe('the declaration stays out of the browser', () => {
+  test('the fixture actually has client components to walk', () => {
+    expect(clientEntries(project).length).toBeGreaterThan(0);
+  });
+
+  test('no client graph reaches the project declaration', () => {
+    expect(
+      findDeclarationLeaks(project).map((chain) =>
+        chain.map((file) => relative(root, file)).join(' → '),
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe('the scanner fails however the import is written', () => {
+  // A check that only recognises the one spelling the leak had the first time
+  // is a check that passes while the leak is back. These fixtures write it the
+  // two other ways it can come back.
+  const created: string[] = [];
+  afterAll(() => {
+    for (const path of created) rmSync(path, { recursive: true, force: true });
+  });
+
+  function fixture(files: Record<string, string>): ClientBoundaryScan {
+    const base = mkdtempSync(join(tmpdir(), 'client-boundary-'));
+    created.push(base);
+    const write = (relativePath: string, content: string): void => {
+      const path = join(base, relativePath);
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, content);
+    };
+    write(
+      'packages/config/package.json',
+      JSON.stringify({
+        name: '@app/config',
+        exports: { './declaration': './src/declaration.ts' },
+      }),
+    );
+    write('packages/config/src/declaration.ts', 'export const appDeclaration = {};\n');
+    for (const [path, content] of Object.entries(files)) write(path, content);
+    return {
+      root: base,
+      frontendSrc: join(base, 'packages/frontend/src'),
+      declaration: join(base, 'packages/config/src/declaration.ts'),
+    };
+  }
+
+  test('a barrel that re-exports the declaration is a leak', () => {
+    const scan = fixture({
+      'packages/frontend/src/page.tsx':
+        "'use client';\nimport { appDeclaration } from './lib';\nexport const value = appDeclaration;\n",
+      'packages/frontend/src/lib/index.ts': "export * from '@app/config/declaration';\n",
+    });
+    expect(findDeclarationLeaks(scan)).toHaveLength(1);
+  });
+
+  test('a relative path into the config package is a leak', () => {
+    // No `@app/` prefix anywhere in the file, so a check on the specifier
+    // string sees nothing at all.
+    const scan = fixture({
+      'packages/frontend/src/page.tsx':
+        "'use client';\nimport { appDeclaration } from '../../config/src/declaration';\nexport const value = appDeclaration;\n",
+    });
+    expect(findDeclarationLeaks(scan)).toHaveLength(1);
+  });
+
+  test('a double-quoted import is a leak too', () => {
+    const scan = fixture({
+      'packages/frontend/src/page.tsx':
+        '\'use client\';\nimport { appDeclaration } from "@app/config/declaration";\nexport const value = appDeclaration;\n',
+    });
+    expect(findDeclarationLeaks(scan)).toHaveLength(1);
+  });
+
+  test('a client graph that reaches nothing forbidden is clean', () => {
+    // The control: without it every assertion above would also pass with a
+    // scanner that reports a leak for anything.
+    const scan = fixture({
+      'packages/frontend/src/page.tsx':
+        "'use client';\nimport { name } from './lib';\nexport const value = name;\n",
+      'packages/frontend/src/lib/index.ts': "export const name = 'x';\n",
+    });
+    expect(findDeclarationLeaks(scan)).toEqual([]);
+  });
+
+  test('both quote styles and side-effect imports are read', () => {
+    expect(
+      specifiers(
+        [
+          "import a from 'single';",
+          'import b from "double";',
+          "import 'side-effect';",
+          'const c = await import("dynamic");',
+          "export { d } from 'reexport';",
+        ].join('\n'),
+      ),
+    ).toEqual(['single', 'double', 'reexport', 'side-effect', 'dynamic']);
+  });
+});