Prune backend deps, gate Swagger, wire minor-units, drop dead modules

[Amnesty-jr]

Prune backend deps, gate Swagger, wire minor-units, drop dead modules

This closes #1949, #1950, #1951 and #1952.

Closes #1949
Closes #1950
Closes #1951
Closes #1952

Summary of changes

#1949 — Remove or wire up the unused in-memory helper modules

Removed the modules that were imported by nothing but their own spec, and added a CI gate so they cannot come back.

Deleted (all verified to have zero non-test importers, so no wiring was needed):

• auth/jwks-cache.util.ts, auth/login-rate-limiter.util.ts, auth/password-reset-token.store.ts
• credits/credit-adjustment-audit.util.ts, credits/credit-balance-cache.util.ts, credits/payment-credit-dedupe.util.ts, credits/dto/usage-date-range.dto.ts
• credits/interfaces/index.ts (unused barrel — its three importers now target interfaces/external-payout-rail.interface directly)
• payments/ledger-append-only.guard.ts, payments/metered-usage-timestamp.util.ts, payments/payment-creation-throttle.util.ts, payments/payment-orchestrator.ts, payments/refund-amount-guard.util.ts, payments/revenue-split-validator.util.ts, payments/settlement-backoff.util.ts, payments/errors/rail-not-registered.error.ts (and the now-empty payments/errors/)

CI check. The issue suggested ts-prune, but ts-prune reports unused exports (including symbols exported purely for in-module use), which is a much broader concern than "a module that exists but is never wired into the running application." Instead scripts/check-dead-modules.js resolves the real import graph from the actual entrypoints (main.ts, database/data-source.ts, database/migrations/**, **/testing/**) and fails the job on any non-test module reachable only from a spec. It runs as the blocking Dead module check step.

#1950 — Currency arithmetic helpers are unused by the money paths

payments/utils/minor-units.ts is now the single home for minor-unit arithmetic and allocation.

• Added assertPositiveMinorUnits, addMinorUnits, subtractMinorUnits, sumMinorUnits alongside the existing assertMinorUnits / multiplyMinorUnits / apportionByBasisPoints.
• Refunds (refunds.service.ts): the amount check goes through assertPositiveMinorUnits; remaining uses subtractMinorUnits and the refunded-total check uses addMinorUnits.
• Ledger (ledger.service.ts): leg validation uses assertPositiveMinorUnits and sideTotal uses sumMinorUnits.
• Splits (split-allocation.ts): the largest-remainder pass is delegated to apportionByBasisPoints, so there is one rounding implementation to audit. The recipients are pre-sorted by sortOrder (then input position) to preserve the module's documented tie-break, then mapped back to the caller's order.

Property test (acceptance criterion): minor-units.spec.ts gains a "money conservation" suite that seeds 2,000 random partial-refund sequences and 2,000 random basis-point splits and asserts the pieces always reconcile back to the exact input — no unit is created and none is lost.

Also fixed a bug in the existing spec: the "assigns a single minor unit" case used shares summing to 4000, not 10000, so it threw MinorUnitsError instead of testing the intended behaviour.

Non-integer or unsafe amounts are already rejected with a 400 at the API boundary by the @MinorUnits DTO decorator (issue #1966); the service-level guards now share the same helpers so the two cannot drift.

#1951 — Swagger UI and the OpenAPI document are served in production

New src/common/swagger.ts exposes setupSwagger(app, env) and isSwaggerEnabled(env), called from main.ts.

• Swagger is off in production unless SWAGGER_ENABLED=true (the explicit, auditable opt-in). GET /api/docs is a 404 in production by default.
• Optionally protected with HTTP basic auth when SWAGGER_USER / SWAGGER_PASSWORD are set (constant-time credential comparison).
• The auth controller issues a cookie, so the document now advertises it via addCookieAuth('accessToken') in addition to the bearer token.

The unit test covers both settings: disabled (404) and enabled (200), plus the production SWAGGER_ENABLED=true override and the basic-auth path.

#1952 — Prune unused and misplaced backend dependencies

• Removed the 19 unused packages the issue lists: @sendgrid/mail, moment, mjml, nodemailer-mjml, otplib, pdfkit, qrcode, sharp, passport, passport-jwt, passport-local, @nestjs/passport, @nestjs/axios, axios, date-fns, json2csv, multer, cache-manager-ioredis, nestjs-command. Also removed the unused swagger-ui-express (@nestjs/swagger serves the UI from swagger-ui-dist), plus the orphaned @types/json2csv / @types/multer / @types/passport-* / @types/pdfkit / @types/qrcode / @types/swagger-ui-express.
• Moved @nestjs/cli, @types/cookie-parser and @types/handlebars to devDependencies so they no longer ship in production installs, and declared the missing dotenv dependency.
• Aligned express to ^4 to match @nestjs/platform-express@^10 (which bundles Express 4) and lowered @types/express accordingly.
• Added a depcheck script + blocking Dependency hygiene (depcheck) CI step. The script ignores only the tooling packages that are required by the build but never imported (@nestjs/schematics, @types/jest, source-map-support, ts-loader, tsconfig-paths).

Verification

• npm run build — passes.
• npm run dead-modules — clean.
• npm run depcheck — "No depcheck issue".
• npm ci and npm ci --omit=dev — both succeed; the production install carries no app-declared @types/* and no CLI tooling.
• npm test — 6 failed suites / 3 failed tests, all pre-existing seeded-bug failures on main (credits-admin.controller.spec, credits.controller.spec, payments.service.spec, lazy-initialization.spec, testnet-integration.spec, with-timeout.spec). This is an improvement over the baseline on main (7 failed suites / 4 failed tests), because the minor-units.spec seed bug is fixed here.

[vercel]

Someone is attempting to deploy a commit to the naijabuz's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Amnesty-jr Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits