NestJS Module PR Check
Use this skill conditionally during PR review. It targets the failure mode where TypeScript and unit tests pass but Nest cannot construct the application because a provider is missing from the runtime module graph.
Trigger
Apply when the PR diff contains any of the following:
apps/ai/src/**/*.module.tsapps/sync/src/**/*.module.tspackages/api/core/src/**/*.module.tsapp.module.tsor module barrel exports in those services/packages@Module({ ... })metadata:imports,providers,controllers, orexports@Injectable()constructor parameters,@Inject(...)tokens, factoryinjectarrays,useExisting,useFactory,@Global(), or dynamic-module registration- A provider, controller, consumer, guard, filter, interceptor, pipe, or repository moved between modules
Determine this from the PR diff against its actual base branch, not from the current working tree alone:
git diff <base>...HEAD --name-only
git diff <base>...HEAD -- 'apps/ai/**/*.ts' 'apps/sync/**/*.ts' 'packages/api/core/**/*.ts'
If none of the trigger conditions match, record N/A — no NestJS module or DI surface changed and stop.
Review checklist
1. Build the module graph
For every changed module, record a small table of:
| Module | Imports | Providers | Exports | Controllers |
|---|
Read the complete @Module metadata, including dynamic registrations such as BullModule.registerQueue(...), ConfigModule.forRoot(...), and CacheModule.register(...). Follow imported module definitions far enough to verify exported tokens; do not treat an import as automatically exposing all of its providers.
2. Verify every injected token
For each changed or newly reachable class, inspect:
- constructor-injected classes and
@Inject(TOKEN)parameters; - factory provider
injectarrays; useExistingaliases and exported injection tokens;- queue names consumed by
@Processor/WorkerHostproviders.
Every token must be visible from the declaring module through one of these paths:
- declared in that module's
providers; - exported by an imported module;
- provided by a deliberately global module; or
- registered by the relevant dynamic module.
A provider being imported as a TypeScript symbol is not sufficient. A unit test that manually lists providers is not proof that the production module graph resolves them.
3. Validate module metadata
- Every item in
exportsis declared locally or is re-exported from an imported module. - Export only the public API needed by consuming modules; do not export implementation-only services.
- Providers moved to another module have their consumers updated and the owning module is imported where needed.
- Factory providers list all runtime dependencies in
injectand use the correct token, not merely a matching TypeScript type. @Global()is used only for genuinely application-wide infrastructure; prefer explicit imports for feature dependencies. The AI session layer is a feature dependency, not infrastructure — do not mark it@Global().- Shared session access uses the ordinary DI path: import
AiUserSessionModulefrom@kit/api-core/sessionand constructor-injectAiUserSessionManager(asRepoSyncService,MeasuresService, and the GitLab credential resolver do). Do not invent a dynamic-module session token (Module.register({ sessionManager }),useExistingalias, or a package-local session interface) to hand the manager across a module boundary — a static module import shares one instance and needs no token. - Dynamic module configuration is present in the application path that instantiates the feature.
- BullMQ queue registration names match the consumer/producer constants exactly.
4. Reject circular-DI workarounds
Treat new or expanded forwardRef(...) usage as a Blocker. Fix the module boundary instead: extract shared infrastructure, move the provider to its owning feature, use an injection token, or decouple through an event/queue. Also inspect the module import graph for cycles that do not use forwardRef; they are still a design and startup risk.
5. Check test quality
For changed module wiring, require a focused Nest testing module or application smoke test that exercises the real metadata. The test should:
- import the production module(s), rather than reproducing them by manually listing providers;
- stub only external infrastructure such as Redis, Supabase, Vault, or provider HTTP clients;
- call
.compile()and, where lifecycle hooks matter,.init(); - assert the newly exposed provider/token can be resolved.
Do not accept a test that only checks a class in isolation when the change is in imports, exports, or provider registration.
6. Run proportional validation
Run the package checks for each affected NestJS service:
pnpm --filter hamster-ai typecheck
pnpm --filter sync typecheck
Run the focused module tests first, then the affected package test suite. Build the affected service when module metadata or path aliases changed:
pnpm --filter hamster-ai test -- <focused-spec>
pnpm --filter sync test -- <focused-spec>
pnpm --filter hamster-ai build
pnpm --filter sync build
When local environment files are available, perform the runtime check through the normal development command. Do not substitute start:prod for this check:
pnpm dev:full-stack
Confirm in the development logs that the affected Nest application reaches Nest application successfully started and that the changed module/provider is initialized. For Sync, verify the proxied endpoint http://localhost:8080/sync/health; for AI, use the proxied API path under http://localhost:8080/ai/. Access services through the Cloudflare dev proxy, not their direct ports.
If dev:full-stack is stopped by an unrelated sibling process (for example, an API worker heap failure), report the Sync/AI startup evidence separately and mark full-stack validation partial. Never call the PR fully validated solely because a different worktree's process is already listening on the service port.
Findings and severity
- Blocker: unresolved production DI token; invalid
exports; missing imported module/export; broken dynamic registration; newforwardRefworkaround; changed application module cannot boot. - Should-fix: unnecessary export or
@Global; duplicated stateful provider; missing real-module wiring test; module cycle without an immediate boot failure. - Nit: ordering or naming that does not affect resolution.
Required review output
Report:
- which trigger matched and which modules were inspected;
- unresolved tokens, invalid exports, cycles, or unnecessary exports;
- focused tests and typechecks/builds run;
- development startup and health evidence, including any unrelated sibling-process failure;
- a final
PASS,PASS WITH PARTIAL RUNTIME VALIDATION, orNEEDS FIXESverdict.
Do not call the PR ready when a Blocker remains.