@bymax-one/nest-core 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -11,6 +11,76 @@ heading here.
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-08-08
+
+Both entries change what a caller receives, which is why this is a minor rather than a patch: an
+application wiring `@bymax-one/nest-auth` starts seeing that library's own error codes where it
+previously saw one collapsed `BYMAX_BAD_REQUEST`, and a deployment with a feature disabled starts
+answering `404` where it answered `500`.
+
+### Fixed
+
+- **A feature disabled on the `forRootAsync` path answers `404` instead of `500`.** Route metadata
+  is fixed before the async options resolve, so the health and metrics controllers register
+  regardless and guard at request time. That guard threw a plain `Error`, which the envelope
+  renders as `BYMAX_INTERNAL_ERROR` — so every consumer registering asynchronously with
+  `metrics: { enabled: false }`, which is the ordinary configuration and the one that keeps the
+  optional `prom-client` peer unloaded, served an unauthenticated `/metrics` that answered a
+  server error to anyone who asked. It counted as a real failure in alerting, in error budgets and
+  in any uptime check pointed at the service, describing a state nothing was wrong with.
+
+  The route now reads as absent, which is what the caller would have seen had the framework been
+  able to skip the registration. Only the feature's _absence_ is normalised: a resolved path that
+  disagrees with the route the controller was registered at is a genuine misconfiguration and
+  still throws.
+
+- **A domain error's `details` reach the caller, and a nested `{ error: { … } }` body is read as
+  readily as a flat one.** The filter passed an explicit `code` through but dropped the structured
+  context beside it, and recognised the fields only when they sat directly on the response.
+
+  `@bymax-one/nest-auth` builds `{ error: { code, message, details } }`, so a backend wiring both
+  libraries rendered every distinct auth failure identically — a duplicate e-mail, a password below
+  the policy floor, a missing field all arrived as `BYMAX_BAD_REQUEST` / `"Auth Exception"` with no
+  details. A client could not branch on the failure, and neither could whoever was debugging it.
+
+  A nested object is followed only when it carries a string `code`, since `error` is an ordinary
+  word for a response body to use; a flat code still wins over a nested one; and a `details` value
+  that is neither an array nor an object — including the `null` `AuthException` writes to mean
+  "none" — is omitted rather than reshaped, so the field stays present only when context exists.
+
+## [1.1.1] - 2026-08-07
+
+**Documentation and tooling.** `dist/` differs from `1.1.0` only in the text of the comments
+described below; no runtime code changed.
+
+### Changed
+
+- **Equivalent mutants are documented in the source instead of only in the report.** The nine
+  now carry `// Stryker disable next-line <Mutator>: <reason>` on the line they apply to,
+  which is the convention now shared across the `@bymax-one/nest-*` libraries. The measured
+  score moves from **98.76%** to **100%** — no test and no production logic changed; Stryker
+  excludes an ignored mutant from the denominator instead of counting it as one the suite
+  failed to kill.
+
+  Two needed the block `disable`/`restore` form, because `next-line` binds to the following
+  statement and those mutants do not sit on one: the cursor-parse catch body, and
+  `setExtras({ isGlobal: true }, …)` inside the builder chain. The second was already known —
+  the note above that call said a directive does not attach there and left the mutant counted.
+  That prose is now the directive's reason, and the block brackets the builder statement alone
+  so nothing else in the file loses its `ObjectLiteral` mutants. Both were confirmed by
+  running them: the pass reports zero survivors where it reported nine.
+
+- The README claimed **Zero suppressions** as a rule. It states what is true now: every
+  suppression carries its reason, in the grammar Stryker parses.
+
+### Added
+
+- `check:mutants` gate (`scripts/check-mutation-directives.mjs`) — validates every
+  `// Stryker` comment against the parser's own regular expression, rejecting a reason
+  written after `--` instead of a colon, a reason wrapped onto a second comment line, a stray
+  comma in the mutator list, and a mutator name Stryker does not know, which matches nothing
+  and so silences nothing. Wired into CI and `prepublishOnly`.
+
 ## [1.1.0] - 2026-08-05
 
 Four optional integrations, each off by default and each loading nothing until it
@@ -230,4 +300,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.1.0]: https://github.com/bymaxone/nest-core/compare/v1.0.1...v1.1.0
 [1.0.1]: https://github.com/bymaxone/nest-core/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/bymaxone/nest-core/releases/tag/v1.0.0
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.1.0...HEAD
+[1.1.1]: https://github.com/bymaxone/nest-core/compare/v1.1.0...v1.1.1
+[1.2.0]: https://github.com/bymaxone/nest-core/compare/v1.1.1...v1.2.0
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.2.0...HEAD

package/README.md

@@ -14,7 +14,7 @@
   <a href="https://www.npmjs.com/package/@bymax-one/nest-core"><img src="https://img.shields.io/npm/dm/@bymax-one/nest-core?style=flat-square&colorA=000000&colorB=000000" alt="npm downloads" /></a>
   <a href="https://github.com/bymaxone/nest-core/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bymaxone/nest-core/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI" alt="CI status" /></a>
   <a href="https://github.com/bymaxone/nest-core/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000" alt="coverage" /></a>
-  <a href="https://github.com/bymaxone/nest-core/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-98.76%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
+  <a href="https://github.com/bymaxone/nest-core/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-100%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/bymaxone/nest-core"><img src="https://api.scorecard.dev/projects/github.com/bymaxone/nest-core/badge?style=flat-square" alt="OpenSSF Scorecard" /></a>
   <a href="https://github.com/bymaxone/nest-core/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bymaxone/nest-core?style=flat-square&colorA=000000&colorB=000000" alt="license" /></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
@@ -917,17 +917,20 @@ This library sits in the path of every request and every failure of every servic
 installs it, so the suite is held to a bar beyond "the tests pass".
 
 - ✅ **100% line coverage** — statements, branches, functions and lines, enforced as a gate
-- ✅ **98.76% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
+- ✅ **100% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
   `break: 95`; every killable survivor was killed by a strengthened test, with no production
-  change, and the nine that remain are documented equivalents rather than suppressions
-  ([report](./docs/mutation_testing_results.md))
+  change, and the nine equivalents that no test can kill each carry their reason on the line
+  they apply to ([report](./docs/mutation_testing_results.md))
 - ✅ **End-to-end against a real application** — the filter, the interceptor, the health and
   metrics routes, the served OpenAPI document, discovered indicators, contributed metrics and
   trace correlation are all exercised through a booted Nest app, not against mocks of it
 - ✅ **Published-artifact gates** — `check:exports` resolves the types the way each module
   system does, `check:runtime` loads every subpath from the packed tarball in ESM and
   CommonJS, and `check:published` compiles this README's snippets against `dist/`
-- ✅ **Zero suppressions** — no coverage or mutation directives in the production source
+- ✅ **Every suppression carries its reason** — no coverage directives anywhere; each
+  `// Stryker disable` in the production source names, after the `:` Stryker reads it from,
+  why the mutant it silences is behaviour-preserving, and `check:mutants` proves those reasons
+  parse so they reach the mutation report rather than the `Ignored using a comment` fallback
 
 ```bash
 pnpm test          # unit suite

package/dist/index.cjs

@@ -287,12 +287,28 @@ function buildErrorEnvelope(input) {
 var INTERNAL_ERROR_STATUS = 500;
 var INTERNAL_ERROR_MESSAGE = "Internal server error";
 var VALIDATION_FAILED_MESSAGE = "Validation failed";
-function extractExplicitCode(response) {
-  if (typeof response !== "object" || response === null || !("code" in response)) {
+function resolveErrorCarrier(response) {
+  if (typeof response !== "object" || response === null) {
     return void 0;
   }
-  const code = response.code;
-  return typeof code === "string" ? code : void 0;
+  if (hasStringCode(response)) {
+    return response;
+  }
+  const nested = response.error;
+  if (typeof nested === "object" && nested !== null && hasStringCode(nested)) {
+    return nested;
+  }
+  return void 0;
+}
+function hasStringCode(value) {
+  return "code" in value && typeof value.code === "string";
+}
+function extractExplicitCode(carrier) {
+  return carrier.code;
+}
+function extractExplicitDetails(carrier) {
+  const details = carrier.details;
+  return typeof details === "object" && details !== null ? details : void 0;
 }
 function isValidationResponse(response) {
   return typeof response === "object" && response !== null && "message" in response && Array.isArray(response.message);
@@ -302,12 +318,13 @@ function toValidationDetails(violations) {
     (violation) => typeof violation === "string" ? { issue: violation } : violation
   );
 }
-function extractHttpMessage(response, exception) {
+function extractHttpMessage(response, exception, carrier) {
   if (typeof response === "string") {
     return response;
   }
-  if (typeof response === "object" && response !== null && "message" in response) {
-    const message = response.message;
+  const source = carrier ?? response;
+  if (typeof source === "object" && source !== null && "message" in source) {
+    const message = source.message;
     if (typeof message === "string") {
       return message;
     }
@@ -414,9 +431,10 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
     return this.mapUnknown(exception, context);
   }
   /**
-   * Map an `HttpException` to the envelope. Explicit domain codes pass through;
-   * the validation shape becomes `BYMAX_VALIDATION_FAILED` with structured
-   * details; everything else derives its code from the status.
+   * Map an `HttpException` to the envelope. A domain error passes its own code,
+   * message and details through, whether it wrote them flat on the response or
+   * nested under `error`; the validation shape becomes `BYMAX_VALIDATION_FAILED`
+   * with structured details; everything else derives its code from the status.
    *
    * @param exception - The HTTP exception to format.
    * @param context - The neutral request context.
@@ -425,9 +443,15 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
   mapHttpException(exception, context) {
     const status = exception.getStatus();
     const response = exception.getResponse();
-    const explicitCode = extractExplicitCode(response);
-    if (explicitCode !== void 0) {
-      return this.toEnvelope(status, explicitCode, extractHttpMessage(response, exception), context);
+    const carrier = resolveErrorCarrier(response);
+    if (carrier !== void 0) {
+      return this.toEnvelope(
+        status,
+        extractExplicitCode(carrier),
+        extractHttpMessage(response, exception, carrier),
+        context,
+        extractExplicitDetails(carrier)
+      );
     }
     if (isValidationResponse(response)) {
       return this.toEnvelope(
@@ -483,10 +507,12 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
       path: context.path,
       now: this.now,
       ...details !== void 0 ? { details } : {},
+      // Stryker disable next-line ConditionalExpression: equivalent — the always-spread form hands the builder `correlationId: undefined`, and `buildErrorEnvelope` re-guards `input.correlationId !== undefined` and omits an undefined value, so the emitted envelope is byte-for-byte identical whether or not a correlation id is present.
       ...context.correlationId !== void 0 ? { correlationId: context.correlationId } : {},
       // Gated separately from the context above: the trace id reaches the
       // observability seam either way, and the response body only when the
       // operator opted into publishing it.
+      // Stryker disable next-line ConditionalExpression: equivalent — same as the correlation id above. The always-spread form hands the builder `traceId: undefined`, which `buildErrorEnvelope` re-guards and omits. The call-site guard exists because `exactOptionalPropertyTypes` rejects an explicit `undefined` for an optional field, not because it changes the output.
       ...this.options.telemetry.exposeTraceId && context.traceId !== void 0 ? { traceId: context.traceId } : {}
     });
   }
@@ -680,8 +706,8 @@ var PassThroughInterceptor = class {
 };
 function assertAsyncFeatureEnabled(feature, enabled) {
   if (!enabled) {
-    throw new Error(
-      `[BymaxCoreModule] The "${feature}" controller was reached while the feature is disabled. On the forRootAsync path this controller is always registered because options resolve after the module is defined; enable "${feature}" in the resolved options, or do not expose this controller while the feature is disabled.`
+    throw new common.NotFoundException(
+      `[BymaxCoreModule] The "${feature}" feature is disabled, so this route does not exist.`
     );
   }
 }

package/dist/index.d.cts

@@ -464,9 +464,10 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
      */
     private buildEnvelope;
     /**
-     * Map an `HttpException` to the envelope. Explicit domain codes pass through;
-     * the validation shape becomes `BYMAX_VALIDATION_FAILED` with structured
-     * details; everything else derives its code from the status.
+     * Map an `HttpException` to the envelope. A domain error passes its own code,
+     * message and details through, whether it wrote them flat on the response or
+     * nested under `error`; the validation shape becomes `BYMAX_VALIDATION_FAILED`
+     * with structured details; everything else derives its code from the status.
      *
      * @param exception - The HTTP exception to format.
      * @param context - The neutral request context.

package/dist/index.d.ts

@@ -464,9 +464,10 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
      */
     private buildEnvelope;
     /**
-     * Map an `HttpException` to the envelope. Explicit domain codes pass through;
-     * the validation shape becomes `BYMAX_VALIDATION_FAILED` with structured
-     * details; everything else derives its code from the status.
+     * Map an `HttpException` to the envelope. A domain error passes its own code,
+     * message and details through, whether it wrote them flat on the response or
+     * nested under `error`; the validation shape becomes `BYMAX_VALIDATION_FAILED`
+     * with structured details; everything else derives its code from the status.
      *
      * @param exception - The HTTP exception to format.
      * @param context - The neutral request context.

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { Catch, Inject, Optional, Injectable, ConfigurableModuleBuilder, Module, HttpException, Logger, Get, Res, Controller, HttpStatus } from '@nestjs/common';
+import { Catch, Inject, Optional, Injectable, ConfigurableModuleBuilder, Module, HttpException, Logger, Get, Res, Controller, HttpStatus, NotFoundException } from '@nestjs/common';
 import { HttpAdapterHost, DiscoveryService, Reflector, BaseExceptionFilter, APP_FILTER, APP_INTERCEPTOR, DiscoveryModule } from '@nestjs/core';
 import { tap, catchError, throwError } from 'rxjs';
 
@@ -285,12 +285,28 @@ function buildErrorEnvelope(input) {
 var INTERNAL_ERROR_STATUS = 500;
 var INTERNAL_ERROR_MESSAGE = "Internal server error";
 var VALIDATION_FAILED_MESSAGE = "Validation failed";
-function extractExplicitCode(response) {
-  if (typeof response !== "object" || response === null || !("code" in response)) {
+function resolveErrorCarrier(response) {
+  if (typeof response !== "object" || response === null) {
     return void 0;
   }
-  const code = response.code;
-  return typeof code === "string" ? code : void 0;
+  if (hasStringCode(response)) {
+    return response;
+  }
+  const nested = response.error;
+  if (typeof nested === "object" && nested !== null && hasStringCode(nested)) {
+    return nested;
+  }
+  return void 0;
+}
+function hasStringCode(value) {
+  return "code" in value && typeof value.code === "string";
+}
+function extractExplicitCode(carrier) {
+  return carrier.code;
+}
+function extractExplicitDetails(carrier) {
+  const details = carrier.details;
+  return typeof details === "object" && details !== null ? details : void 0;
 }
 function isValidationResponse(response) {
   return typeof response === "object" && response !== null && "message" in response && Array.isArray(response.message);
@@ -300,12 +316,13 @@ function toValidationDetails(violations) {
     (violation) => typeof violation === "string" ? { issue: violation } : violation
   );
 }
-function extractHttpMessage(response, exception) {
+function extractHttpMessage(response, exception, carrier) {
   if (typeof response === "string") {
     return response;
   }
-  if (typeof response === "object" && response !== null && "message" in response) {
-    const message = response.message;
+  const source = carrier ?? response;
+  if (typeof source === "object" && source !== null && "message" in source) {
+    const message = source.message;
     if (typeof message === "string") {
       return message;
     }
@@ -412,9 +429,10 @@ var BymaxExceptionFilter = class {
     return this.mapUnknown(exception, context);
   }
   /**
-   * Map an `HttpException` to the envelope. Explicit domain codes pass through;
-   * the validation shape becomes `BYMAX_VALIDATION_FAILED` with structured
-   * details; everything else derives its code from the status.
+   * Map an `HttpException` to the envelope. A domain error passes its own code,
+   * message and details through, whether it wrote them flat on the response or
+   * nested under `error`; the validation shape becomes `BYMAX_VALIDATION_FAILED`
+   * with structured details; everything else derives its code from the status.
    *
    * @param exception - The HTTP exception to format.
    * @param context - The neutral request context.
@@ -423,9 +441,15 @@ var BymaxExceptionFilter = class {
   mapHttpException(exception, context) {
     const status = exception.getStatus();
     const response = exception.getResponse();
-    const explicitCode = extractExplicitCode(response);
-    if (explicitCode !== void 0) {
-      return this.toEnvelope(status, explicitCode, extractHttpMessage(response, exception), context);
+    const carrier = resolveErrorCarrier(response);
+    if (carrier !== void 0) {
+      return this.toEnvelope(
+        status,
+        extractExplicitCode(carrier),
+        extractHttpMessage(response, exception, carrier),
+        context,
+        extractExplicitDetails(carrier)
+      );
     }
     if (isValidationResponse(response)) {
       return this.toEnvelope(
@@ -481,10 +505,12 @@ var BymaxExceptionFilter = class {
       path: context.path,
       now: this.now,
       ...details !== void 0 ? { details } : {},
+      // Stryker disable next-line ConditionalExpression: equivalent — the always-spread form hands the builder `correlationId: undefined`, and `buildErrorEnvelope` re-guards `input.correlationId !== undefined` and omits an undefined value, so the emitted envelope is byte-for-byte identical whether or not a correlation id is present.
       ...context.correlationId !== void 0 ? { correlationId: context.correlationId } : {},
       // Gated separately from the context above: the trace id reaches the
       // observability seam either way, and the response body only when the
       // operator opted into publishing it.
+      // Stryker disable next-line ConditionalExpression: equivalent — same as the correlation id above. The always-spread form hands the builder `traceId: undefined`, which `buildErrorEnvelope` re-guards and omits. The call-site guard exists because `exactOptionalPropertyTypes` rejects an explicit `undefined` for an optional field, not because it changes the output.
       ...this.options.telemetry.exposeTraceId && context.traceId !== void 0 ? { traceId: context.traceId } : {}
     });
   }
@@ -678,8 +704,8 @@ var PassThroughInterceptor = class {
 };
 function assertAsyncFeatureEnabled(feature, enabled) {
   if (!enabled) {
-    throw new Error(
-      `[BymaxCoreModule] The "${feature}" controller was reached while the feature is disabled. On the forRootAsync path this controller is always registered because options resolve after the module is defined; enable "${feature}" in the resolved options, or do not expose this controller while the feature is disabled.`
+    throw new NotFoundException(
+      `[BymaxCoreModule] The "${feature}" feature is disabled, so this route does not exist.`
     );
   }
 }

package/dist/pagination/index.cjs

@@ -57,6 +57,7 @@ function isOrderingKeyRecord(value) {
     return false;
   }
   return Object.values(value).every(
+    // Stryker disable next-line ConditionalExpression: equivalent — replacing the `typeof entry === 'number'` guard with `true` leaves `Number.isFinite(entry)`, which never coerces and so already returns `false` for every non-number. The guard is redundant and the predicate is unchanged for every value.
     (entry) => typeof entry === "string" || typeof entry === "number" && Number.isFinite(entry)
   );
 }

package/dist/pagination/index.mjs

@@ -55,6 +55,7 @@ function isOrderingKeyRecord(value) {
     return false;
   }
   return Object.values(value).every(
+    // Stryker disable next-line ConditionalExpression: equivalent — replacing the `typeof entry === 'number'` guard with `true` leaves `Number.isFinite(entry)`, which never coerces and so already returns `false` for every non-number. The guard is redundant and the predicate is unchanged for every value.
     (entry) => typeof entry === "string" || typeof entry === "number" && Number.isFinite(entry)
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints with indicator discovery, an optional Prometheus metrics endpoint with a contribution contract, OpenAPI documents in development, and OpenTelemetry trace correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -78,6 +78,7 @@
   "scripts": {
     "build": "pnpm clean && tsup",
     "check:exports": "attw --pack . --profile strict",
+    "check:mutants": "node scripts/check-mutation-directives.mjs",
     "check:published": "node scripts/check-published-surface.mjs",
     "check:runtime": "node scripts/check-consumer-runtime.mjs",
     "clean": "node -e \"const fs=require('node:fs');for(const d of ['dist','coverage'])fs.rmSync(d,{recursive:true,force:true})\"",
@@ -85,10 +86,10 @@
     "lint": "eslint --no-error-on-unmatched-pattern src scripts test",
     "lint:fix": "eslint --no-error-on-unmatched-pattern src scripts test --fix",
     "mutation": "stryker run",
+    "mutation:full": "node -e \"require('node:fs').rmSync('reports/stryker-incremental.json',{force:true,recursive:true})\" && stryker run",
     "mutation:dry-run": "stryker run --dryRunOnly",
-    "mutation:incremental": "stryker run --incremental",
     "prepare": "husky",
-    "prepublishOnly": "pnpm clean && pnpm typecheck && pnpm lint && pnpm test:cov:all && pnpm build && pnpm size && pnpm check:published",
+    "prepublishOnly": "pnpm clean && pnpm typecheck && pnpm lint && pnpm check:mutants && pnpm test:cov:all && pnpm build && pnpm size && pnpm check:published",
     "release": "npm publish --provenance --access public",
     "size": "node scripts/check-size.mjs",
     "test": "jest",