Detect unused code and dependencies with knip

.github/workflows/checks.yml

@@ -77,6 +77,8 @@ jobs:
           node-version: 24.x
       - name: Code linting
         run: npm run lint:ci
+      - name: Find unused files, exports and dependencies
+        run: npm run knip
 
   compile:
     if: ${{ needs.detect-modules.outputs.modules_count != '0' }}

AGENTS.md

@@ -24,6 +24,7 @@ It captures practical rules that prevent avoidable CI and PR churn.
 
 - If a public API changes, update the relevant docs in the same PR.
 - If new types are made part of the public API, export them from the package's `index.ts` in the same PR.
+- Only what a package's `index.ts` exports is public API. `npm run knip` fails on any other export that no other file uses: drop the `export` keyword, or export it from `index.ts` if consumers need it.
 - If new learnings or misunderstandings are discovered, propose an `AGENTS.md` update in the same PR.
 - In docs Markdown, keep `<!--codeinclude-->` blocks tight with no blank lines between the markers and the include line, or the rendered snippet will contain blank lines between code lines.
 - Codeinclude `inside_block:<name>` selects the block after the first line that contains `<name>` anywhere, so a marker whose name also appears earlier in the file (for example inside another marker's name) silently includes the wrong block. The `Docs` workflow runs `mkdocs build --strict`, which fails when a marker or included file is missing but cannot catch this.
@@ -96,7 +97,7 @@ reviewers can follow the reasoning.
 1. Start from `main`.
 2. Create a branch prefixed with `<agent-name>/` (for example `claude/fix-exec-output-truncation`). The PR title must not carry such prefixes (see step 9).
 3. Implement scoped changes only.
-4. Run required checks: `npm run format`, `npm run lint`, `npm run check-compiles` when touching `packages/testcontainers` APIs consumed by modules, and targeted tests.
+4. Run required checks: `npm run format`, `npm run lint`, `npm run knip`, `npm run check-compiles` when touching `packages/testcontainers` APIs consumed by modules, and targeted tests.
    - When working in a fresh git worktree, dependencies are not installed (`node_modules` is absent), so verification commands (tests, `lint`, `format`, `check-compiles`) will fail with "Cannot find module" errors. Run `npm ci` once before verifying. `npm ci` only populates `node_modules` and must not modify `package-lock.json`; if it does, treat that as drift to investigate.
 5. Verify git diff only contains intended files.
 6. Never commit, push, or post on GitHub (issues, PRs, or comments) without first sharing the proposed diff/message and getting explicit user approval.

knip.jsonc

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://unpkg.com/knip@6/schema-jsonc.json",
+  "workspaces": {
+    ".": {
+      // Loaded by a <script> tag in docs/site/theme/main.html, not imported by any module.
+      "entry": ["docs/site/js/tc-header.js"]
+    },
+    "packages/testcontainers": {
+      // Run by Jest in the Checks workflow via `--testMatch`, which knip can't trace back to a file.
+      "entry": ["smoke-test.jest.js"],
+      // Docker build contexts that tests copy into images, never imported.
+      "ignoreFiles": ["fixtures/**"]
+    },
+    "packages/modules/gcloud": {
+      // firebase-admin/firestore requires it at runtime, but firebase-admin only lists it as optional.
+      "ignoreDependencies": ["@google-cloud/firestore"]
+    }
+  }
+}