nestjs-docfy 0.2.8 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/README.md +261 -0
  2. package/dist/attach-tag-groups.d.ts +14 -0
  3. package/dist/attach-tag-groups.js +24 -0
  4. package/dist/attach-tag-groups.js.map +1 -0
  5. package/dist/cli/build-openapi-patch.d.ts +45 -0
  6. package/dist/cli/build-openapi-patch.js +151 -0
  7. package/dist/cli/build-openapi-patch.js.map +1 -0
  8. package/dist/cli/coverage.d.ts +15 -0
  9. package/dist/cli/coverage.js +34 -0
  10. package/dist/cli/coverage.js.map +1 -0
  11. package/dist/cli/eval-decorator-args.d.ts +39 -0
  12. package/dist/cli/eval-decorator-args.js +115 -0
  13. package/dist/cli/eval-decorator-args.js.map +1 -0
  14. package/dist/cli/extract-docs-config.d.ts +19 -0
  15. package/dist/cli/extract-docs-config.js +89 -0
  16. package/dist/cli/extract-docs-config.js.map +1 -0
  17. package/dist/cli/index.js +287 -0
  18. package/dist/cli/index.js.map +1 -1
  19. package/dist/cli/lint.d.ts +33 -0
  20. package/dist/cli/lint.js +211 -0
  21. package/dist/cli/lint.js.map +1 -0
  22. package/dist/cli/merge-spec-patch.d.ts +57 -0
  23. package/dist/cli/merge-spec-patch.js +115 -0
  24. package/dist/cli/merge-spec-patch.js.map +1 -0
  25. package/dist/cli/patch-spec.d.ts +31 -0
  26. package/dist/cli/patch-spec.js +82 -0
  27. package/dist/cli/patch-spec.js.map +1 -0
  28. package/dist/docfy-ui.module.d.ts +48 -0
  29. package/dist/docfy-ui.module.js +72 -0
  30. package/dist/docfy-ui.module.js.map +1 -0
  31. package/dist/docfy.module.js +9 -5
  32. package/dist/docfy.module.js.map +1 -1
  33. package/dist/docs.d.ts +13 -0
  34. package/dist/docs.js +4 -0
  35. package/dist/docs.js.map +1 -1
  36. package/dist/index.d.ts +3 -0
  37. package/dist/index.js +5 -1
  38. package/dist/index.js.map +1 -1
  39. package/dist/registry.d.ts +2 -1
  40. package/dist/registry.js +11 -1
  41. package/dist/registry.js.map +1 -1
  42. package/dist/require-ts.d.ts +32 -0
  43. package/dist/require-ts.js +122 -0
  44. package/dist/require-ts.js.map +1 -0
  45. package/dist/resolve-docs-path.d.ts +10 -1
  46. package/dist/resolve-docs-path.js +31 -3
  47. package/dist/resolve-docs-path.js.map +1 -1
  48. package/dist/resolve-source-from-stack.d.ts +35 -0
  49. package/dist/resolve-source-from-stack.js +153 -0
  50. package/dist/resolve-source-from-stack.js.map +1 -0
  51. package/dist/tag-group-registry.d.ts +9 -0
  52. package/dist/tag-group-registry.js +32 -0
  53. package/dist/tag-group-registry.js.map +1 -0
  54. package/dist/testing.js +2 -0
  55. package/dist/testing.js.map +1 -1
  56. package/dist/with-docs.decorator.js +7 -1
  57. package/dist/with-docs.decorator.js.map +1 -1
  58. package/package.json +5 -1
package/README.md CHANGED
@@ -28,13 +28,19 @@ Keep your NestJS controllers clean. Swagger documentation lives in a dedicated c
28
28
  - [Project types](#project-types)
29
29
  - [Idempotency and --force](#idempotency-and---force)
30
30
  - [CLI — check](#cli--check)
31
+ - [CLI — coverage](#cli--coverage)
32
+ - [CLI — lint](#cli--lint)
33
+ - [CLI — patch-spec](#cli--patch-spec)
31
34
  - [API reference](#api-reference)
32
35
  - [DocfyModule.forRoot()](#docfymoduleforrootoptions)
33
36
  - [@WithDocs()](#withdocs)
34
37
  - [docs()](#docscontrollerclass-config)
38
+ - [attachTagGroups()](#attachtaggroupsdocument)
39
+ - [DocfyUiModule.setup()](#docfyuimodulesetupmountpath-app-options)
35
40
  - [Interface-typed DTOs](#interface-typed-dtos)
36
41
  - [class-validator inference](#class-validator-inference)
37
42
  - [@HttpCode() support](#httpcode-support)
43
+ - [Tag groups (x-tagGroups)](#tag-groups-x-taggroups)
38
44
  - [File naming convention](#file-naming-convention)
39
45
  - [Testing](#testing)
40
46
  - [How it works](#how-it-works)
@@ -304,6 +310,155 @@ Or as an npm script:
304
310
  }
305
311
  ```
306
312
 
313
+ ## CLI — coverage
314
+
315
+ Measure what percentage of your endpoints are documented. Useful as an objective quality metric and as a CI gate.
316
+
317
+ ```bash
318
+ npx nestjs-docfy coverage [options]
319
+ ```
320
+
321
+ | Option | Default | Description |
322
+ | ------------------- | -------------------- | ------------------------------------------------------ |
323
+ | `--root <path>` | `.` | Project root directory |
324
+ | `--tsconfig <path>` | auto-detected | Path to `tsconfig.json` |
325
+ | `--pattern <glob>` | `**/*.controller.ts` | Glob pattern to find controllers |
326
+ | `--format <format>` | `ts` | Docs file format to look for: `ts` or `js` |
327
+ | `--min <percent>` | none | Minimum coverage required (0-100) — exits `1` if below |
328
+ | `--quiet` | `false` | Suppress all output except errors |
329
+
330
+ **Example output:**
331
+
332
+ ```text
333
+ Controllers: 42
334
+ Endpoints: 187
335
+
336
+ Documented: 174
337
+ Missing docs: 13
338
+
339
+ Coverage: 93.0%
340
+ ```
341
+
342
+ **Enforcing a minimum in CI:**
343
+
344
+ ```bash
345
+ npx nestjs-docfy coverage --min 95
346
+ ```
347
+
348
+ When coverage falls below `--min`, the command exits with code `1`, failing the build.
349
+
350
+ ```yaml
351
+ # GitHub Actions example
352
+ - name: Enforce documentation coverage
353
+ run: npx nestjs-docfy coverage --min 95
354
+ ```
355
+
356
+ Or as an npm script:
357
+
358
+ ```json
359
+ {
360
+ "scripts": {
361
+ "docs:coverage": "nestjs-docfy coverage --min 95"
362
+ }
363
+ }
364
+ ```
365
+
366
+ ## CLI — lint
367
+
368
+ Checks documentation **quality**, not just presence — catches incomplete `ApiOperation`, `ApiResponse`, and `ApiBody` decorators that `check` and `coverage` wouldn't flag (the method is documented, just incompletely).
369
+
370
+ ```bash
371
+ npx nestjs-docfy lint [options]
372
+ ```
373
+
374
+ | Option | Default | Description |
375
+ | ------------------- | -------------------- | ------------------------------------------ |
376
+ | `--root <path>` | `.` | Project root directory |
377
+ | `--tsconfig <path>` | auto-detected | Path to `tsconfig.json` |
378
+ | `--pattern <glob>` | `**/*.controller.ts` | Glob pattern to find controllers |
379
+ | `--format <format>` | `ts` | Docs file format to look for: `ts` or `js` |
380
+ | `--quiet` | `false` | Suppress all output except errors |
381
+
382
+ **What it checks**, for every method already present in a docs file:
383
+
384
+ - `ApiOperation` missing a `summary`
385
+ - Endpoints with a `@Body()` parameter missing a `400` `ApiResponse`
386
+ - Endpoints with a `@Body()` parameter missing an `ApiBody` `description`
387
+
388
+ Controllers without a companion docs file, or methods not yet documented at all, are left to `check` — `lint` only judges the quality of what's already there.
389
+
390
+ **Example output:**
391
+
392
+ ```text
393
+ ✖ POST /users
394
+ Missing 400 response
395
+
396
+ ✖ GET /users
397
+ Missing operation summary
398
+
399
+ ✖ PATCH /users/:id
400
+ Missing request body description
401
+
402
+ ✖ 3 issue(s) found.
403
+ ```
404
+
405
+ Exits with code `1` if any issue is found — designed for CI pipelines, same as `check`.
406
+
407
+ ```yaml
408
+ # GitHub Actions example
409
+ - name: Lint documentation quality
410
+ run: npx nestjs-docfy lint
411
+ ```
412
+
413
+ Or as an npm script:
414
+
415
+ ```json
416
+ {
417
+ "scripts": {
418
+ "docs:lint": "nestjs-docfy lint"
419
+ }
420
+ }
421
+ ```
422
+
423
+ ## CLI — patch-spec
424
+
425
+ Patches an **already-built** OpenAPI document with every controller's companion docs file, entirely via static analysis (`ts-morph`) — no `require()` of any docs file, no decorators applied to any class, no dependency on a live class reference matching the one the running app actually uses.
426
+
427
+ This is the workaround for the one thing `DocfyModule`'s runtime pipeline structurally cannot do: work under NestJS CLI's `webpack: true` build mode (see "Not supported" under [File naming convention](#file-naming-convention) for why). `patch-spec` sidesteps that entirely by matching on **path + HTTP method**, computed the same way `check`/`coverage`/`lint` already do, instead of needing the live controller class.
428
+
429
+ ```bash
430
+ npx nestjs-docfy patch-spec --spec <path-or-url> [options]
431
+ ```
432
+
433
+ | Option | Default | Description |
434
+ | --- | --- | --- |
435
+ | `--spec <path\|url>` | *(required)* | A local `openapi.json`, or a URL (e.g. a running app's `/api-json`) |
436
+ | `--out <path>` | stdout | Where to write the patched document |
437
+ | `--root <path>` | `.` | Project root directory |
438
+ | `--tsconfig <path>` | auto-detected | Path to `tsconfig.json` |
439
+ | `--pattern <glob>` | `**/*.controller.ts` | Glob pattern to find controllers |
440
+ | `--format <format>` | `ts` | Docs file format to look for: `ts` or `js` |
441
+ | `--quiet` | `false` | Suppress all output except errors |
442
+
443
+ ```bash
444
+ # Patch a running app's served document
445
+ npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.json
446
+
447
+ # Patch a file already written to disk
448
+ npx nestjs-docfy patch-spec --spec dist/openapi.json --out dist/openapi.json
449
+ ```
450
+
451
+ **What gets merged**, matched by `path` + HTTP method against the base document:
452
+
453
+ - `ApiTags` → unioned into `tags` (never drops tags the base document already had)
454
+ - `ApiOperation({ summary, description, deprecated })` → overwrites those fields
455
+ - `ApiResponse({ status, description, schema })` → merged per status code (other status codes untouched); when no `schema`/`type` is given, falls back to the method's own resolved return type — same DTO/class-validator/interface inference `generate` already does
456
+ - `ApiBody({ schema })` → sets `requestBody`, with the same return-type-style fallback to the `@Body()` parameter's resolved type
457
+ - `ApiBearerAuth()` → appended to `security`
458
+ - `ApiParam` / `ApiQuery` / `ApiHeader` → appended to `parameters`, deduplicated by name + location
459
+
460
+ **What this does *not* do** (yet — this command is intentionally scoped, not a full reimplementation of `@nestjs/swagger`'s decorator semantics): enums, `oneOf`/`anyOf`, examples, links, callbacks, and any decorator argument that isn't a literal (a variable, a function call, a spread) are left alone rather than guessed at — better to leave a field as the base document already had it than patch in something wrong. Routes a docs file documents that don't exist in `--spec` are reported as warnings, not silently dropped or errored on.
461
+
307
462
  ## API reference
308
463
 
309
464
  ### `DocfyModule.forRoot(options?)`
@@ -352,8 +507,57 @@ docs(UsersController, {
352
507
 
353
508
  **`config.methods`** — `Partial<Record<keyof T, MethodDecorator[]>>` — decorator arrays per method name, applied in order.
354
509
 
510
+ **`config.group`** — `string` — logical group name for ReDoc's `x-tagGroups` extension. See [Tag groups](#tag-groups-x-taggroups).
511
+
512
+ **`config.tags`** — `string[]` — tag names associated with `group`. Should match what you pass to `ApiTags()`.
513
+
355
514
  If a method key does not exist on the controller at runtime, a warning is logged and that entry is skipped — the rest of the docs file still applies.
356
515
 
516
+ ### `attachTagGroups(document)`
517
+
518
+ Adds the `x-tagGroups` extension to a Swagger document, built from groups registered via `docs({ group, tags })`. Call after `SwaggerModule.createDocument()` and before `SwaggerModule.setup()`. Returns the document unchanged if no groups were registered. See [Tag groups](#tag-groups-x-taggroups) for a full example.
519
+
520
+ ### `DocfyUiModule.setup(mountPath, app, options?)`
521
+
522
+ Serves [`docfy-ui`](https://www.npmjs.com/package/docfy-ui) — the AI-first documentation UI companion to this package — at `mountPath`, the same role `SwaggerModule.setup()` + `swagger-ui-express` play for raw Swagger UI. Built on Express's static-file middleware directly, so it expects an Express-based Nest app (the default `@nestjs/platform-express` adapter) — Fastify isn't supported yet.
523
+
524
+ ```ts
525
+ import { NestFactory } from '@nestjs/core';
526
+ import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
527
+ import { DocfyUiModule } from 'nestjs-docfy';
528
+
529
+ const app = await NestFactory.create(AppModule);
530
+
531
+ DocfyUiModule.setup('/docs', app); // before SwaggerModule.setup — see staticSpecPath below
532
+
533
+ const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
534
+ SwaggerModule.setup('api', app, document); // exposes /api-json, which docfy-ui fetches by default
535
+
536
+ await app.listen(3000);
537
+ ```
538
+
539
+ Visit `/docs` — no further configuration needed, since `docfy-ui` fetches `/api-json` same-origin by default.
540
+
541
+ | Option | Type | Default | Description |
542
+ | --- | --- | --- | --- |
543
+ | `staticSpecPath` | `string` | — | Path to a pre-built OpenAPI JSON file, served at `/api-json` *instead of* the app's live one. |
544
+
545
+ **`staticSpecPath` — required if your app builds with `"webpack": true`.** `DocfyModule`'s runtime metadata pipeline cannot apply docs files there (see [Not supported: webpack: true](#not-supported-nestjs-clis-webpack-true-build-mode)), so the live `/api-json` will be missing everything docs files would otherwise add. Generate a patched document ahead of time —
546
+
547
+ ```bash
548
+ npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json
549
+ ```
550
+
551
+ — and serve that instead:
552
+
553
+ ```ts
554
+ DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });
555
+ ```
556
+
557
+ Call this **before** `SwaggerModule.setup()`: Express resolves routes in registration order, so the static, patched document takes precedence over the live one for any request to `/api-json`.
558
+
559
+ > **Caveat**: `docfy-ui` renders with React Router's `BrowserRouter` and no configurable `basename` yet, so deep client-side routes (e.g. reloading an endpoint's detail page directly) only resolve correctly when `mountPath` is `/` — the application's root. Mounting elsewhere (e.g. `/docs`) still serves the UI and its initial load works fine; in-app navigation to a specific endpoint and then reloading that URL does not yet work at a non-root mount path.
560
+
357
561
  ## Interface-typed DTOs
358
562
 
359
563
  When a response or body type is a TypeScript `interface` (not a class), Swagger cannot use it as a `type:` value because interfaces are erased at runtime. `nestjs-docfy` detects this automatically and generates an inline `schema:` object instead — **no changes to your code required**.
@@ -449,6 +653,53 @@ logout: [
449
653
 
450
654
  Without `@HttpCode()`, the default codes apply: `201` for `@Post`, `200` for all other HTTP verbs.
451
655
 
656
+ ## Tag groups (x-tagGroups)
657
+
658
+ Pass `group` and `tags` to `docs()` to organize controllers under logical sections in tools that support the `x-tagGroups` OpenAPI extension — most notably [ReDoc](https://github.com/Redocly/redoc).
659
+
660
+ ```ts
661
+ // users.controller.docs.ts
662
+ docs(UsersController, {
663
+ classDecorators: [ApiTags('users')],
664
+ group: 'Administration',
665
+ tags: ['users'],
666
+ });
667
+
668
+ // roles.controller.docs.ts
669
+ docs(RolesController, {
670
+ classDecorators: [ApiTags('roles')],
671
+ group: 'Administration',
672
+ tags: ['roles'],
673
+ });
674
+ ```
675
+
676
+ `tags` should match what you already pass to `ApiTags()` — `nestjs-docfy` does not call `ApiTags` for you, it only builds the `x-tagGroups` mapping from what you declare.
677
+
678
+ To actually attach the groups to the generated document, call `attachTagGroups()` after `SwaggerModule.createDocument()`:
679
+
680
+ ```ts
681
+ // main.ts
682
+ import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
683
+ import { attachTagGroups } from 'nestjs-docfy';
684
+
685
+ const config = new DocumentBuilder().setTitle('My API').build();
686
+ const document = SwaggerModule.createDocument(app, config);
687
+
688
+ SwaggerModule.setup('api', app, attachTagGroups(document));
689
+ ```
690
+
691
+ Generated extension:
692
+
693
+ ```yaml
694
+ x-tagGroups:
695
+ - name: Administration
696
+ tags:
697
+ - users
698
+ - roles
699
+ ```
700
+
701
+ Multiple `docs()` calls can contribute to the same group — tags are merged and deduplicated. `attachTagGroups()` is a no-op (returns the document unchanged) when no controller declares a `group`.
702
+
452
703
  ## File naming convention
453
704
 
454
705
  Discovery is automatic. `DocfyModule` locates each controller's source file via Node's module cache and resolves the companion path — this works identically in `ts-node` (development) and compiled `dist/` (production).
@@ -460,6 +711,16 @@ Discovery is automatic. `DocfyModule` locates each controller's source file via
460
711
 
461
712
  > **Barrel re-exports**: if your controller is also exported from an `index.ts` barrel, make sure the class is exported directly from its own module file. `nestjs-docfy` prefers `.controller.ts` over barrel files.
462
713
 
714
+ ### Not supported: NestJS CLI's `webpack: true` build mode
715
+
716
+ If your `nest-cli.json` has `"webpack": true` under `compilerOptions` — the documented default for monorepos with multiple apps — `nestjs-docfy` **will not work**, and there is no configuration that makes it work. This is architectural, not a bug to be patched around:
717
+
718
+ - Webpack inlines every module into one bundle file and never populates Node's `require.cache` with an entry per original source file, which is what the discovery mechanism above depends on. You'll see `Could not locate source file for X` for every `@WithDocs()` controller.
719
+ - Even if that lookup is worked around (e.g. by recovering the original path from the bundle's source map, sidestepping `require.cache` entirely), there's a second, unavoidable wall: a docs file required from outside the bundle creates a structurally different class object than the one the running app actually uses internally. Decorating that fresh copy has no effect on the document `SwaggerModule.createDocument()` actually serves — silently, with no error. This path-recovery layer was built and tested before discovering this; it isn't shipped, because "looks like it loaded, does nothing" is worse than the current loud, accurate warning.
720
+ - The only way around this would be for the controller's own file to import its `.docs.ts` companion (forcing webpack to bundle them together) — which defeats the entire point of the convention: zero coupling between a controller and its documentation.
721
+
722
+ **If you need `nestjs-docfy`, disable webpack bundling**: remove `"webpack": true` (or set it to `false`) in `nest-cli.json`. Under `nest build`'s default `tsc`-based compilation, every source file — including each `*.controller.docs.ts` — gets compiled to its own `.js` file in `dist/`, so `require.cache` naturally has one entry per file and discovery works exactly as documented above, no special configuration needed.
723
+
463
724
  ## Testing
464
725
 
465
726
  Reset the controller registry between test suites to avoid cross-contamination:
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Adds the `x-tagGroups` extension (read by ReDoc to group tags in its
3
+ * sidebar) to a Swagger document, built from groups registered via
4
+ * `docs({ group, tags })`.
5
+ *
6
+ * Call after `SwaggerModule.createDocument()` and before `SwaggerModule.setup()`:
7
+ *
8
+ * @example
9
+ * const document = SwaggerModule.createDocument(app, config);
10
+ * SwaggerModule.setup('api', app, attachTagGroups(document));
11
+ *
12
+ * Returns the document unchanged (same reference) if no groups were registered.
13
+ */
14
+ export declare function attachTagGroups<T extends object>(document: T): T;
@@ -0,0 +1,24 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.attachTagGroups = attachTagGroups;
4
+ const tag_group_registry_1 = require("./tag-group-registry");
5
+ /**
6
+ * Adds the `x-tagGroups` extension (read by ReDoc to group tags in its
7
+ * sidebar) to a Swagger document, built from groups registered via
8
+ * `docs({ group, tags })`.
9
+ *
10
+ * Call after `SwaggerModule.createDocument()` and before `SwaggerModule.setup()`:
11
+ *
12
+ * @example
13
+ * const document = SwaggerModule.createDocument(app, config);
14
+ * SwaggerModule.setup('api', app, attachTagGroups(document));
15
+ *
16
+ * Returns the document unchanged (same reference) if no groups were registered.
17
+ */
18
+ function attachTagGroups(document) {
19
+ const groups = tag_group_registry_1.TagGroupRegistry.getAll();
20
+ if (groups.length === 0)
21
+ return document;
22
+ return Object.assign({}, document, { 'x-tagGroups': groups });
23
+ }
24
+ //# sourceMappingURL=attach-tag-groups.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"attach-tag-groups.js","sourceRoot":"","sources":["../src/attach-tag-groups.ts"],"names":[],"mappings":";;AAeA,0CAIC;AAnBD,6DAAwD;AAExD;;;;;;;;;;;;GAYG;AACH,SAAgB,eAAe,CAAmB,QAAW;IAC3D,MAAM,MAAM,GAAG,qCAAgB,CAAC,MAAM,EAAE,CAAC;IACzC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACzC,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,CAAM,CAAC;AACrE,CAAC"}
@@ -0,0 +1,45 @@
1
+ import type { ControllerInfo } from './extract-methods';
2
+ import type { ExtractedDocsConfig } from './extract-docs-config';
3
+ export type OpenApiSchema = Record<string, unknown>;
4
+ export interface OperationPatch {
5
+ tags?: string[];
6
+ summary?: string;
7
+ description?: string;
8
+ deprecated?: boolean;
9
+ security?: Array<Record<string, string[]>>;
10
+ parameters?: Array<{
11
+ name: string;
12
+ in: string;
13
+ required?: boolean;
14
+ schema: OpenApiSchema;
15
+ }>;
16
+ requestBody?: {
17
+ required?: boolean;
18
+ content: Record<string, {
19
+ schema: OpenApiSchema;
20
+ }>;
21
+ };
22
+ responses?: Record<string, {
23
+ description?: string;
24
+ content?: Record<string, {
25
+ schema: OpenApiSchema;
26
+ }>;
27
+ }>;
28
+ }
29
+ /** path -> httpMethod (lowercase) -> patch */
30
+ export type SpecPatch = Record<string, Record<string, OperationPatch>>;
31
+ /**
32
+ * Computes the OpenAPI fragment a controller's `.docs.ts` file represents,
33
+ * purely from statically-extracted data — no decorators are applied to any
34
+ * class, no Reflect metadata is touched, nothing is required() at runtime.
35
+ *
36
+ * This intentionally does not aim for full parity with what `@nestjs/swagger`
37
+ * decorators would produce when actually applied (that's a much larger
38
+ * surface — enums, oneOf/anyOf, examples, links, callbacks, etc.). It covers
39
+ * the common path: tags, operation summary/description, responses with a
40
+ * status + description + schema, request bodies, and bearer auth — enough
41
+ * to validate that statically-computed patches can stand in for runtime
42
+ * decoration where the latter is structurally impossible (see the README's
43
+ * "Not supported: webpack: true" section).
44
+ */
45
+ export declare function buildOpenApiPatch(ctrl: ControllerInfo, config: ExtractedDocsConfig): SpecPatch;
@@ -0,0 +1,151 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.buildOpenApiPatch = buildOpenApiPatch;
4
+ const eval_decorator_args_1 = require("./eval-decorator-args");
5
+ const HTTP_METHODS_OPENAPI = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options']);
6
+ function joinPaths(controllerPath, methodPath) {
7
+ const a = (controllerPath ?? '').replace(/^\/+|\/+$/g, '');
8
+ const b = (methodPath ?? '').replace(/^\/+|\/+$/g, '');
9
+ const joined = [a, b].filter(Boolean).join('/');
10
+ return `/${joined}`;
11
+ }
12
+ function schemaFromResponseType(info) {
13
+ if (!info)
14
+ return undefined;
15
+ const inline = info.classSchema ?? info.inlineSchema;
16
+ const base = inline
17
+ ? { type: 'object', properties: inline.properties, ...(inline.required.length ? { required: inline.required } : {}) }
18
+ : { $ref: `#/components/schemas/${info.name}` };
19
+ return info.isArray ? { type: 'array', items: base } : base;
20
+ }
21
+ function findBodyResponseType(method) {
22
+ const bodyParam = method.params.find((p) => p.nestDecorator === '@Body' && p.bodyType);
23
+ return bodyParam?.bodyType ?? null;
24
+ }
25
+ /** Resolves a schema for an ApiBody/ApiResponse `type`/`schema` argument value. */
26
+ function resolveSchemaArg(value, fallback) {
27
+ if (value === undefined)
28
+ return schemaFromResponseType(fallback);
29
+ if ((0, eval_decorator_args_1.isUnresolved)(value))
30
+ return schemaFromResponseType(fallback);
31
+ if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
32
+ return value;
33
+ }
34
+ return schemaFromResponseType(fallback);
35
+ }
36
+ function asRecord(value) {
37
+ if (value && typeof value === 'object' && !Array.isArray(value) && !(0, eval_decorator_args_1.isUnresolved)(value)) {
38
+ return value;
39
+ }
40
+ return {};
41
+ }
42
+ function plain(value) {
43
+ if (value === undefined || (0, eval_decorator_args_1.isUnresolved)(value) || value === null || typeof value === 'object')
44
+ return undefined;
45
+ return value;
46
+ }
47
+ /**
48
+ * Computes the OpenAPI fragment a controller's `.docs.ts` file represents,
49
+ * purely from statically-extracted data — no decorators are applied to any
50
+ * class, no Reflect metadata is touched, nothing is required() at runtime.
51
+ *
52
+ * This intentionally does not aim for full parity with what `@nestjs/swagger`
53
+ * decorators would produce when actually applied (that's a much larger
54
+ * surface — enums, oneOf/anyOf, examples, links, callbacks, etc.). It covers
55
+ * the common path: tags, operation summary/description, responses with a
56
+ * status + description + schema, request bodies, and bearer auth — enough
57
+ * to validate that statically-computed patches can stand in for runtime
58
+ * decoration where the latter is structurally impossible (see the README's
59
+ * "Not supported: webpack: true" section).
60
+ */
61
+ function buildOpenApiPatch(ctrl, config) {
62
+ const patch = {};
63
+ const classTags = config.classDecorators
64
+ .filter((d) => d.name === 'ApiTags')
65
+ .flatMap((d) => d.args.filter((a) => typeof a === 'string'));
66
+ for (const method of ctrl.methods) {
67
+ if (!method.httpDecorator)
68
+ continue;
69
+ const httpMethod = method.httpDecorator.toLowerCase();
70
+ if (!HTTP_METHODS_OPENAPI.has(httpMethod))
71
+ continue;
72
+ const route = joinPaths(ctrl.controllerPath, method.httpPath);
73
+ const calls = config.methods[method.name] ?? [];
74
+ const op = {};
75
+ if (classTags.length > 0)
76
+ op.tags = classTags;
77
+ for (const call of calls) {
78
+ switch (call.name) {
79
+ case 'ApiOperation': {
80
+ const arg = asRecord(call.args[0]);
81
+ const summary = plain(arg.summary);
82
+ const description = plain(arg.description);
83
+ const deprecated = plain(arg.deprecated);
84
+ if (typeof summary === 'string')
85
+ op.summary = summary;
86
+ if (typeof description === 'string')
87
+ op.description = description;
88
+ if (typeof deprecated === 'boolean')
89
+ op.deprecated = deprecated;
90
+ break;
91
+ }
92
+ case 'ApiResponse': {
93
+ const arg = asRecord(call.args[0]);
94
+ const status = plain(arg.status);
95
+ const statusKey = typeof status === 'number' ? String(status) : 'default';
96
+ const description = plain(arg.description);
97
+ const schema = resolveSchemaArg(arg.schema ?? arg.type, method.responseType);
98
+ op.responses ?? (op.responses = {});
99
+ op.responses[statusKey] = {
100
+ ...(typeof description === 'string' ? { description } : {}),
101
+ ...(schema ? { content: { 'application/json': { schema } } } : {}),
102
+ };
103
+ break;
104
+ }
105
+ case 'ApiBody': {
106
+ const arg = asRecord(call.args[0]);
107
+ const fallback = findBodyResponseType(method);
108
+ const schema = resolveSchemaArg(arg.schema ?? arg.type, fallback);
109
+ if (schema) {
110
+ op.requestBody = {
111
+ required: true,
112
+ content: { 'application/json': { schema } },
113
+ };
114
+ }
115
+ break;
116
+ }
117
+ case 'ApiBearerAuth': {
118
+ op.security = [...(op.security ?? []), { bearer: [] }];
119
+ break;
120
+ }
121
+ case 'ApiParam':
122
+ case 'ApiQuery':
123
+ case 'ApiHeader': {
124
+ const arg = asRecord(call.args[0]);
125
+ const name = plain(arg.name);
126
+ if (typeof name !== 'string')
127
+ break;
128
+ const paramIn = call.name === 'ApiParam' ? 'path' : call.name === 'ApiQuery' ? 'query' : 'header';
129
+ const required = plain(arg.required);
130
+ op.parameters = [
131
+ ...(op.parameters ?? []),
132
+ {
133
+ name,
134
+ in: paramIn,
135
+ ...(typeof required === 'boolean' ? { required } : {}),
136
+ schema: { type: 'string' },
137
+ },
138
+ ];
139
+ break;
140
+ }
141
+ default:
142
+ // Unrecognized decorator (custom, or not yet handled) — ignored, not an error.
143
+ break;
144
+ }
145
+ }
146
+ patch[route] ?? (patch[route] = {});
147
+ patch[route][httpMethod] = op;
148
+ }
149
+ return patch;
150
+ }
151
+ //# sourceMappingURL=build-openapi-patch.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"build-openapi-patch.js","sourceRoot":"","sources":["../../src/cli/build-openapi-patch.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,15 @@
1
+ import type { ControllerInfo } from './extract-methods';
2
+ export interface CoverageReport {
3
+ totalControllers: number;
4
+ /** HTTP-mapped methods across all controllers */
5
+ totalEndpoints: number;
6
+ documentedEndpoints: number;
7
+ missingEndpoints: number;
8
+ /** Percentage 0–100, one decimal place. NaN when totalEndpoints === 0. */
9
+ coveragePercent: number;
10
+ }
11
+ /**
12
+ * Computes documentation coverage across all scanned controllers.
13
+ * Only HTTP-mapped methods (those with an httpDecorator) are counted.
14
+ */
15
+ export declare function computeCoverage(controllers: ControllerInfo[], format: 'ts' | 'js'): CoverageReport;
@@ -0,0 +1,34 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.computeCoverage = computeCoverage;
4
+ const scan_controllers_1 = require("./scan-controllers");
5
+ const check_1 = require("./check");
6
+ /**
7
+ * Computes documentation coverage across all scanned controllers.
8
+ * Only HTTP-mapped methods (those with an httpDecorator) are counted.
9
+ */
10
+ function computeCoverage(controllers, format) {
11
+ let totalEndpoints = 0;
12
+ let documentedEndpoints = 0;
13
+ for (const ctrl of controllers) {
14
+ const httpMethods = ctrl.methods.filter((m) => m.httpDecorator !== null);
15
+ totalEndpoints += httpMethods.length;
16
+ if (ctrl.hasDocsFile) {
17
+ const docsFile = (0, scan_controllers_1.deriveDocsFilePath)(ctrl.filePath, format);
18
+ const documented = (0, check_1.getDocumentedMethods)(docsFile);
19
+ documentedEndpoints += httpMethods.filter((m) => documented.has(m.name)).length;
20
+ }
21
+ }
22
+ const missingEndpoints = totalEndpoints - documentedEndpoints;
23
+ const coveragePercent = totalEndpoints === 0
24
+ ? NaN
25
+ : Math.round((documentedEndpoints / totalEndpoints) * 1000) / 10;
26
+ return {
27
+ totalControllers: controllers.length,
28
+ totalEndpoints,
29
+ documentedEndpoints,
30
+ missingEndpoints,
31
+ coveragePercent,
32
+ };
33
+ }
34
+ //# sourceMappingURL=coverage.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../src/cli/coverage.ts"],"names":[],"mappings":";;AAkBA,0CA+BC;AAjDD,yDAAwD;AACxD,mCAA+C;AAa/C;;;GAGG;AACH,SAAgB,eAAe,CAC7B,WAA6B,EAC7B,MAAmB;IAEnB,IAAI,cAAc,GAAG,CAAC,CAAC;IACvB,IAAI,mBAAmB,GAAG,CAAC,CAAC;IAE5B,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC;QACzE,cAAc,IAAI,WAAW,CAAC,MAAM,CAAC;QAErC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,QAAQ,GAAG,IAAA,qCAAkB,EAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC3D,MAAM,UAAU,GAAG,IAAA,4BAAoB,EAAC,QAAQ,CAAC,CAAC;YAClD,mBAAmB,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;QAClF,CAAC;IACH,CAAC;IAED,MAAM,gBAAgB,GAAG,cAAc,GAAG,mBAAmB,CAAC;IAC9D,MAAM,eAAe,GACnB,cAAc,KAAK,CAAC;QAClB,CAAC,CAAC,GAAG;QACL,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,mBAAmB,GAAG,cAAc,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAErE,OAAO;QACL,gBAAgB,EAAE,WAAW,CAAC,MAAM;QACpC,cAAc;QACd,mBAAmB;QACnB,gBAAgB;QAChB,eAAe;KAChB,CAAC;AACJ,CAAC"}
@@ -0,0 +1,39 @@
1
+ import { Node } from 'ts-morph';
2
+ /**
3
+ * Marker for an expression this evaluator couldn't statically resolve to a
4
+ * plain value — e.g. a variable reference, a function call, a spread. The
5
+ * raw source text is kept so callers can decide whether to ignore it,
6
+ * surface a warning, or (for known patterns like `HttpStatus.CREATED`)
7
+ * recognize it themselves.
8
+ */
9
+ export interface Unresolved {
10
+ __unresolved: true;
11
+ text: string;
12
+ }
13
+ export type EvaluatedValue = string | number | boolean | null | EvaluatedValue[] | {
14
+ [key: string]: EvaluatedValue;
15
+ } | Unresolved;
16
+ export declare function isUnresolved(value: EvaluatedValue): value is Unresolved;
17
+ /**
18
+ * Statically evaluates a ts-morph expression node into a plain JS value,
19
+ * without executing any code. Handles the literal shapes that actually
20
+ * appear in `.docs.ts` files written by hand or generated by this tool:
21
+ * string/number/boolean/null literals, array and object literals, and
22
+ * `HttpStatus.X` member access. Anything else (variable references,
23
+ * function calls, spreads, computed keys) becomes an `Unresolved` marker
24
+ * rather than throwing — callers decide what to do with it.
25
+ */
26
+ export declare function evaluateExpression(node: Node): EvaluatedValue;
27
+ export interface DecoratorCall {
28
+ /** Decorator factory name, e.g. "ApiOperation". */
29
+ name: string;
30
+ /** Each call argument, statically evaluated. */
31
+ args: EvaluatedValue[];
32
+ }
33
+ /**
34
+ * Evaluates a decorator factory call expression — e.g. the `ApiOperation({
35
+ * summary: 'X' })` inside an array literal `[ApiOperation({...}), ApiBearerAuth()]`
36
+ * — into a `{ name, args }` pair. Returns null if the expression isn't a
37
+ * recognizable `Identifier(...)` or `Identifier.member(...)` call.
38
+ */
39
+ export declare function evaluateDecoratorCall(node: Node): DecoratorCall | null;