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.
- package/README.md +261 -0
- package/dist/attach-tag-groups.d.ts +14 -0
- package/dist/attach-tag-groups.js +24 -0
- package/dist/attach-tag-groups.js.map +1 -0
- package/dist/cli/build-openapi-patch.d.ts +45 -0
- package/dist/cli/build-openapi-patch.js +151 -0
- package/dist/cli/build-openapi-patch.js.map +1 -0
- package/dist/cli/coverage.d.ts +15 -0
- package/dist/cli/coverage.js +34 -0
- package/dist/cli/coverage.js.map +1 -0
- package/dist/cli/eval-decorator-args.d.ts +39 -0
- package/dist/cli/eval-decorator-args.js +115 -0
- package/dist/cli/eval-decorator-args.js.map +1 -0
- package/dist/cli/extract-docs-config.d.ts +19 -0
- package/dist/cli/extract-docs-config.js +89 -0
- package/dist/cli/extract-docs-config.js.map +1 -0
- package/dist/cli/index.js +287 -0
- package/dist/cli/index.js.map +1 -1
- package/dist/cli/lint.d.ts +33 -0
- package/dist/cli/lint.js +211 -0
- package/dist/cli/lint.js.map +1 -0
- package/dist/cli/merge-spec-patch.d.ts +57 -0
- package/dist/cli/merge-spec-patch.js +115 -0
- package/dist/cli/merge-spec-patch.js.map +1 -0
- package/dist/cli/patch-spec.d.ts +31 -0
- package/dist/cli/patch-spec.js +82 -0
- package/dist/cli/patch-spec.js.map +1 -0
- package/dist/docfy-ui.module.d.ts +48 -0
- package/dist/docfy-ui.module.js +72 -0
- package/dist/docfy-ui.module.js.map +1 -0
- package/dist/docfy.module.js +9 -5
- package/dist/docfy.module.js.map +1 -1
- package/dist/docs.d.ts +13 -0
- package/dist/docs.js +4 -0
- package/dist/docs.js.map +1 -1
- package/dist/index.d.ts +3 -0
- package/dist/index.js +5 -1
- package/dist/index.js.map +1 -1
- package/dist/registry.d.ts +2 -1
- package/dist/registry.js +11 -1
- package/dist/registry.js.map +1 -1
- package/dist/require-ts.d.ts +32 -0
- package/dist/require-ts.js +122 -0
- package/dist/require-ts.js.map +1 -0
- package/dist/resolve-docs-path.d.ts +10 -1
- package/dist/resolve-docs-path.js +31 -3
- package/dist/resolve-docs-path.js.map +1 -1
- package/dist/resolve-source-from-stack.d.ts +35 -0
- package/dist/resolve-source-from-stack.js +153 -0
- package/dist/resolve-source-from-stack.js.map +1 -0
- package/dist/tag-group-registry.d.ts +9 -0
- package/dist/tag-group-registry.js +32 -0
- package/dist/tag-group-registry.js.map +1 -0
- package/dist/testing.js +2 -0
- package/dist/testing.js.map +1 -1
- package/dist/with-docs.decorator.js +7 -1
- package/dist/with-docs.decorator.js.map +1 -1
- package/package.json +5 -1
package/dist/docfy.module.js
CHANGED
|
@@ -32,7 +32,8 @@ let DocfyModule = DocfyModule_1 = class DocfyModule {
|
|
|
32
32
|
static _loadAllDocs(options = {}, requireFn = require, cacheReader) {
|
|
33
33
|
const { strict = false } = options;
|
|
34
34
|
for (const controllerClass of registry_1.DocfyRegistry.getAll()) {
|
|
35
|
-
const
|
|
35
|
+
const callSiteStack = registry_1.DocfyRegistry.getCallSite(controllerClass);
|
|
36
|
+
const docsPath = (0, resolve_docs_path_1.resolveDocsPath)(controllerClass, cacheReader, callSiteStack);
|
|
36
37
|
if (!docsPath) {
|
|
37
38
|
const message = `Could not locate source file for ${controllerClass.name}. ` +
|
|
38
39
|
`Make sure the class is exported directly from its own module file ` +
|
|
@@ -77,9 +78,12 @@ function isMissingDocsFile(err, docsPath) {
|
|
|
77
78
|
return false;
|
|
78
79
|
if (!('code' in err) || err.code !== 'MODULE_NOT_FOUND')
|
|
79
80
|
return false;
|
|
80
|
-
// Node's
|
|
81
|
-
//
|
|
82
|
-
//
|
|
83
|
-
|
|
81
|
+
// Node's MODULE_NOT_FOUND message is "Cannot find module 'X'\nRequire stack:\n- ...".
|
|
82
|
+
// Only the first line names the actual missing module — docsPath legitimately
|
|
83
|
+
// also appears further down in the "Require stack" list whenever a *dependency*
|
|
84
|
+
// inside an existing docs file is missing (docsPath required it, so it's in the
|
|
85
|
+
// chain), which would otherwise false-positive as "the docs file doesn't exist".
|
|
86
|
+
const firstLine = err.message.split('\n', 1)[0];
|
|
87
|
+
return firstLine.includes(docsPath);
|
|
84
88
|
}
|
|
85
89
|
//# sourceMappingURL=docfy.module.js.map
|
package/dist/docfy.module.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"docfy.module.js","sourceRoot":"","sources":["../src/docfy.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAA+D;AAC/D,yCAA2C;AAC3C,2DAAsD;AAYtD;;;;;;;;;GASG;AAEI,IAAM,WAAW,mBAAjB,MAAM,WAAW;IAGtB,MAAM,CAAC,OAAO,CAAC,UAA8B,EAAE;QAC7C,aAAW,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAClC,OAAO,EAAE,MAAM,EAAE,aAAW,EAAE,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY,CACjB,UAA8B,EAAE,EAChC,YAAoC,OAAO,EAC3C,WAAoF;QAEpF,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;QAEnC,KAAK,MAAM,eAAe,IAAI,wBAAa,CAAC,MAAM,EAAE,EAAE,CAAC;YACrD,MAAM,QAAQ,GAAG,IAAA,mCAAe,EAAC,eAAe,EAAE,WAAW,CAAC,CAAC;
|
|
1
|
+
{"version":3,"file":"docfy.module.js","sourceRoot":"","sources":["../src/docfy.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAA+D;AAC/D,yCAA2C;AAC3C,2DAAsD;AAYtD;;;;;;;;;GASG;AAEI,IAAM,WAAW,mBAAjB,MAAM,WAAW;IAGtB,MAAM,CAAC,OAAO,CAAC,UAA8B,EAAE;QAC7C,aAAW,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAClC,OAAO,EAAE,MAAM,EAAE,aAAW,EAAE,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY,CACjB,UAA8B,EAAE,EAChC,YAAoC,OAAO,EAC3C,WAAoF;QAEpF,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;QAEnC,KAAK,MAAM,eAAe,IAAI,wBAAa,CAAC,MAAM,EAAE,EAAE,CAAC;YACrD,MAAM,aAAa,GAAG,wBAAa,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;YACjE,MAAM,QAAQ,GAAG,IAAA,mCAAe,EAAC,eAAe,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;YAE9E,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,OAAO,GACX,oCAAoC,eAAe,CAAC,IAAI,IAAI;oBAC5D,oEAAoE;oBACpE,mCAAmC,CAAC;gBACtC,IAAI,MAAM;oBAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAC;gBACzD,aAAW,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACjC,SAAS;YACX,CAAC;YAED,IAAI,CAAC;gBACH,SAAS,CAAC,QAAQ,CAAC,CAAC;gBACpB,aAAW,CAAC,MAAM,CAAC,GAAG,CAAC,mBAAmB,eAAe,CAAC,IAAI,SAAS,QAAQ,EAAE,CAAC,CAAC;YACrF,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,IAAI,iBAAiB,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,CAAC;oBACrC,kEAAkE;oBAClE,MAAM,OAAO,GACX,0BAA0B,eAAe,CAAC,IAAI,eAAe,QAAQ,EAAE,CAAC;oBAC1E,IAAI,MAAM;wBAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAC;oBACzD,aAAW,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACnC,CAAC;qBAAM,CAAC;oBACN,iFAAiF;oBACjF,aAAW,CAAC,MAAM,CAAC,KAAK,CACtB,gCAAgC,eAAe,CAAC,IAAI,KAAK,QAAQ,EAAE,EACnE,GAAG,CACJ,CAAC;oBACF,MAAM,GAAG,CAAC;gBACZ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;;AApDU,kCAAW;AACE,kBAAM,GAAG,IAAI,eAAM,CAAC,aAAW,CAAC,IAAI,CAAC,AAA/B,CAAgC;sBADnD,WAAW;IADvB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,WAAW,CAqDvB;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,GAAY,EAAE,QAAgB;IACvD,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,IAAI,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,IAAK,GAA6B,CAAC,IAAI,KAAK,kBAAkB;QAAE,OAAO,KAAK,CAAC;IACjG,sFAAsF;IACtF,8EAA8E;IAC9E,gFAAgF;IAChF,gFAAgF;IAChF,iFAAiF;IACjF,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,OAAO,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACtC,CAAC"}
|
package/dist/docs.d.ts
CHANGED
|
@@ -4,6 +4,19 @@ export interface DocsConfig<T = any> {
|
|
|
4
4
|
classDecorators?: ClassDecorator[];
|
|
5
5
|
/** Method-level decorators keyed by method name. */
|
|
6
6
|
methods?: Partial<Record<keyof T, MethodDecorator[]>>;
|
|
7
|
+
/**
|
|
8
|
+
* Logical group name for ReDoc's `x-tagGroups` extension. Purely
|
|
9
|
+
* organizational — has no effect on per-operation Swagger tags.
|
|
10
|
+
* Combine with `tags`, and call `attachTagGroups()` on the document
|
|
11
|
+
* returned by `SwaggerModule.createDocument()`.
|
|
12
|
+
*/
|
|
13
|
+
group?: string;
|
|
14
|
+
/**
|
|
15
|
+
* Tag names to associate with `group`. These should match the tags you
|
|
16
|
+
* already apply via `ApiTags()` in `classDecorators` — nestjs-docfy does
|
|
17
|
+
* not call `ApiTags` for you, it only builds the `x-tagGroups` mapping.
|
|
18
|
+
*/
|
|
19
|
+
tags?: string[];
|
|
7
20
|
}
|
|
8
21
|
/**
|
|
9
22
|
* Applies Swagger decorators to a controller class from outside the class file.
|
package/dist/docs.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.docs = docs;
|
|
4
|
+
const tag_group_registry_1 = require("./tag-group-registry");
|
|
4
5
|
/**
|
|
5
6
|
* Applies Swagger decorators to a controller class from outside the class file.
|
|
6
7
|
* Mirrors exactly what TypeScript decorator syntax does: each decorator factory
|
|
@@ -23,6 +24,9 @@ function docs(controllerClass, config) {
|
|
|
23
24
|
decorator(controllerClass);
|
|
24
25
|
}
|
|
25
26
|
}
|
|
27
|
+
if (config.group) {
|
|
28
|
+
tag_group_registry_1.TagGroupRegistry.register(config.group, config.tags ?? []);
|
|
29
|
+
}
|
|
26
30
|
if (!config.methods)
|
|
27
31
|
return;
|
|
28
32
|
for (const [methodName, decorators] of Object.entries(config.methods)) {
|
package/dist/docs.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"docs.js","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":";;
|
|
1
|
+
{"version":3,"file":"docs.js","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":";;AAwCA,oBA+BC;AAvED,6DAAwD;AAwBxD;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,IAAI,CAAI,eAA+B,EAAE,MAAqB;IAC5E,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;QAC3B,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;YAC/C,SAAS,CAAC,eAAe,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,qCAAgB,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO;IAE5B,KAAK,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAkC,EAAE,CAAC;QACvG,MAAM,UAAU,GAAG,MAAM,CAAC,wBAAwB,CAChD,eAAe,CAAC,SAAS,EACzB,UAAU,CACX,CAAC;QAEF,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,CAAC,IAAI,CACV,0BAA0B,UAAU,kBAAkB,eAAe,CAAC,IAAI,IAAI;gBAC5E,uCAAuC,CAC1C,CAAC;YACF,SAAS;QACX,CAAC;QAED,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,SAAS,CAAC,eAAe,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;AACH,CAAC"}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,6 @@
|
|
|
1
1
|
export { WithDocs, DOCFY_MARKER } from './with-docs.decorator';
|
|
2
2
|
export { docs, DocsConfig } from './docs';
|
|
3
3
|
export { DocfyModule, DocfyModuleOptions } from './docfy.module';
|
|
4
|
+
export { attachTagGroups } from './attach-tag-groups';
|
|
5
|
+
export { TagGroup } from './tag-group-registry';
|
|
6
|
+
export { DocfyUiModule, DocfyUiSetupTarget, DocfyUiSetupOptions } from './docfy-ui.module';
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.DocfyModule = exports.docs = exports.DOCFY_MARKER = exports.WithDocs = void 0;
|
|
3
|
+
exports.DocfyUiModule = exports.attachTagGroups = exports.DocfyModule = exports.docs = exports.DOCFY_MARKER = exports.WithDocs = void 0;
|
|
4
4
|
var with_docs_decorator_1 = require("./with-docs.decorator");
|
|
5
5
|
Object.defineProperty(exports, "WithDocs", { enumerable: true, get: function () { return with_docs_decorator_1.WithDocs; } });
|
|
6
6
|
Object.defineProperty(exports, "DOCFY_MARKER", { enumerable: true, get: function () { return with_docs_decorator_1.DOCFY_MARKER; } });
|
|
@@ -8,4 +8,8 @@ var docs_1 = require("./docs");
|
|
|
8
8
|
Object.defineProperty(exports, "docs", { enumerable: true, get: function () { return docs_1.docs; } });
|
|
9
9
|
var docfy_module_1 = require("./docfy.module");
|
|
10
10
|
Object.defineProperty(exports, "DocfyModule", { enumerable: true, get: function () { return docfy_module_1.DocfyModule; } });
|
|
11
|
+
var attach_tag_groups_1 = require("./attach-tag-groups");
|
|
12
|
+
Object.defineProperty(exports, "attachTagGroups", { enumerable: true, get: function () { return attach_tag_groups_1.attachTagGroups; } });
|
|
13
|
+
var docfy_ui_module_1 = require("./docfy-ui.module");
|
|
14
|
+
Object.defineProperty(exports, "DocfyUiModule", { enumerable: true, get: function () { return docfy_ui_module_1.DocfyUiModule; } });
|
|
11
15
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAA+D;AAAtD,+GAAA,QAAQ,OAAA;AAAE,mHAAA,YAAY,OAAA;AAC/B,+BAA0C;AAAjC,4FAAA,IAAI,OAAA;AACb,+CAAiE;AAAxD,2GAAA,WAAW,OAAA"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAA+D;AAAtD,+GAAA,QAAQ,OAAA;AAAE,mHAAA,YAAY,OAAA;AAC/B,+BAA0C;AAAjC,4FAAA,IAAI,OAAA;AACb,+CAAiE;AAAxD,2GAAA,WAAW,OAAA;AACpB,yDAAsD;AAA7C,oHAAA,eAAe,OAAA;AAExB,qDAA2F;AAAlF,gHAAA,aAAa,OAAA"}
|
package/dist/registry.d.ts
CHANGED
package/dist/registry.js
CHANGED
|
@@ -4,13 +4,23 @@ exports.DocfyRegistry = void 0;
|
|
|
4
4
|
// Global registry of classes decorated with @WithDocs().
|
|
5
5
|
// Populated at class-definition time; consumed by DocfyModule.forRoot().
|
|
6
6
|
const registry = new Set();
|
|
7
|
+
// Raw `Error().stack` captured at the exact line `@WithDocs()` was applied,
|
|
8
|
+
// keyed by class. Used as a fallback to locate the controller's source file
|
|
9
|
+
// when require.cache has no entry for it (e.g. the app is bundled — see
|
|
10
|
+
// resolve-source-from-stack.ts for why that happens and how this is used).
|
|
11
|
+
const callSites = new WeakMap();
|
|
7
12
|
exports.DocfyRegistry = {
|
|
8
|
-
add(target) {
|
|
13
|
+
add(target, callSiteStack) {
|
|
9
14
|
registry.add(target);
|
|
15
|
+
if (callSiteStack)
|
|
16
|
+
callSites.set(target, callSiteStack);
|
|
10
17
|
},
|
|
11
18
|
getAll() {
|
|
12
19
|
return registry;
|
|
13
20
|
},
|
|
21
|
+
getCallSite(target) {
|
|
22
|
+
return callSites.get(target);
|
|
23
|
+
},
|
|
14
24
|
// For testing only — resets the registry between test runs.
|
|
15
25
|
_reset() {
|
|
16
26
|
registry.clear();
|
package/dist/registry.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":";;;AAAA,yDAAyD;AACzD,yEAAyE;AACzE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":";;;AAAA,yDAAyD;AACzD,yEAAyE;AACzE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAY,CAAC;AAErC,4EAA4E;AAC5E,4EAA4E;AAC5E,wEAAwE;AACxE,2EAA2E;AAC3E,MAAM,SAAS,GAAG,IAAI,OAAO,EAAoB,CAAC;AAErC,QAAA,aAAa,GAAG;IAC3B,GAAG,CAAC,MAAgB,EAAE,aAAsB;QAC1C,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrB,IAAI,aAAa;YAAE,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM;QACJ,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,WAAW,CAAC,MAAgB;QAC1B,OAAO,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,4DAA4D;IAC5D,MAAM;QACJ,QAAQ,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;CACF,CAAC"}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Loads a .ts companion docs file at runtime without relying on a
|
|
3
|
+
* pre-registered TypeScript loader (ts-node, tsx, etc.).
|
|
4
|
+
*
|
|
5
|
+
* Why this is needed: docs files are intentionally never imported by
|
|
6
|
+
* application code (that's the whole point of the *.controller.docs.ts
|
|
7
|
+
* convention — they attach metadata from outside the controller). Under
|
|
8
|
+
* NestJS CLI's `webpack: true` build mode, that means they're never part
|
|
9
|
+
* of the bundle's reachable module graph, so they never get compiled to
|
|
10
|
+
* .js even when the rest of the app is — there's nothing for a plain
|
|
11
|
+
* `require()` to load. resolveDocsPath can correctly locate the original
|
|
12
|
+
* .ts file (see resolve-source-from-stack.ts), but loading it still needs
|
|
13
|
+
* this.
|
|
14
|
+
*
|
|
15
|
+
* Registers `require.extensions['.ts']` — exactly the mechanism ts-node's
|
|
16
|
+
* own `register()` uses — rather than manually constructing a `Module`
|
|
17
|
+
* instance and calling `_compile()` directly. That distinction matters for
|
|
18
|
+
* correctness, not just style: Node's module *resolution* (not just
|
|
19
|
+
* compilation) only tries an extension if it's a registered key of
|
|
20
|
+
* `require.extensions`. A docs file importing a sibling relative path
|
|
21
|
+
* (`import { UsersController } from './users.controller'`) needs Node to
|
|
22
|
+
* try `./users.controller.ts` while resolving — manually compiling just
|
|
23
|
+
* the entry file doesn't make Node try `.ts` for anything *it* requires
|
|
24
|
+
* in turn, so any relative import inside the docs file would still throw
|
|
25
|
+
* "Cannot find module" one level down.
|
|
26
|
+
*
|
|
27
|
+
* Transpiles with esbuild — type-stripping only, since docs files call
|
|
28
|
+
* decorator factories as plain functions (`docs(Controller, { classDecorators:
|
|
29
|
+
* [ApiTags('x')] })`) rather than using TypeScript decorator syntax
|
|
30
|
+
* themselves, so no decorator-metadata emulation is needed.
|
|
31
|
+
*/
|
|
32
|
+
export declare function requireTypeScriptFile(absPath: string): unknown;
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.requireTypeScriptFile = requireTypeScriptFile;
|
|
37
|
+
const fs = __importStar(require("fs"));
|
|
38
|
+
/**
|
|
39
|
+
* Loads a .ts companion docs file at runtime without relying on a
|
|
40
|
+
* pre-registered TypeScript loader (ts-node, tsx, etc.).
|
|
41
|
+
*
|
|
42
|
+
* Why this is needed: docs files are intentionally never imported by
|
|
43
|
+
* application code (that's the whole point of the *.controller.docs.ts
|
|
44
|
+
* convention — they attach metadata from outside the controller). Under
|
|
45
|
+
* NestJS CLI's `webpack: true` build mode, that means they're never part
|
|
46
|
+
* of the bundle's reachable module graph, so they never get compiled to
|
|
47
|
+
* .js even when the rest of the app is — there's nothing for a plain
|
|
48
|
+
* `require()` to load. resolveDocsPath can correctly locate the original
|
|
49
|
+
* .ts file (see resolve-source-from-stack.ts), but loading it still needs
|
|
50
|
+
* this.
|
|
51
|
+
*
|
|
52
|
+
* Registers `require.extensions['.ts']` — exactly the mechanism ts-node's
|
|
53
|
+
* own `register()` uses — rather than manually constructing a `Module`
|
|
54
|
+
* instance and calling `_compile()` directly. That distinction matters for
|
|
55
|
+
* correctness, not just style: Node's module *resolution* (not just
|
|
56
|
+
* compilation) only tries an extension if it's a registered key of
|
|
57
|
+
* `require.extensions`. A docs file importing a sibling relative path
|
|
58
|
+
* (`import { UsersController } from './users.controller'`) needs Node to
|
|
59
|
+
* try `./users.controller.ts` while resolving — manually compiling just
|
|
60
|
+
* the entry file doesn't make Node try `.ts` for anything *it* requires
|
|
61
|
+
* in turn, so any relative import inside the docs file would still throw
|
|
62
|
+
* "Cannot find module" one level down.
|
|
63
|
+
*
|
|
64
|
+
* Transpiles with esbuild — type-stripping only, since docs files call
|
|
65
|
+
* decorator factories as plain functions (`docs(Controller, { classDecorators:
|
|
66
|
+
* [ApiTags('x')] })`) rather than using TypeScript decorator syntax
|
|
67
|
+
* themselves, so no decorator-metadata emulation is needed.
|
|
68
|
+
*/
|
|
69
|
+
function requireTypeScriptFile(absPath) {
|
|
70
|
+
console.error('[DEBUG requireTypeScriptFile]', JSON.stringify(absPath), 'exists=', fs.existsSync(absPath));
|
|
71
|
+
if (!fs.existsSync(absPath)) {
|
|
72
|
+
// Matches the shape of Node's own require() MODULE_NOT_FOUND error, so
|
|
73
|
+
// callers that distinguish "file doesn't exist" from "file threw while
|
|
74
|
+
// loading" (DocfyModule's isMissingDocsFile) work the same regardless
|
|
75
|
+
// of which loader actually handled the path.
|
|
76
|
+
throw Object.assign(new Error(`Cannot find module '${absPath}'`), {
|
|
77
|
+
code: 'MODULE_NOT_FOUND',
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
registerTsExtension();
|
|
81
|
+
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
82
|
+
return require(absPath);
|
|
83
|
+
}
|
|
84
|
+
let registered = false;
|
|
85
|
+
function registerTsExtension() {
|
|
86
|
+
if (registered || require.extensions['.ts'])
|
|
87
|
+
return;
|
|
88
|
+
const esbuild = loadEsbuild();
|
|
89
|
+
if (!esbuild) {
|
|
90
|
+
throw new Error(`[nestjs-docfy] Cannot load a .ts docs file: no TypeScript loader is registered ` +
|
|
91
|
+
`(e.g. ts-node) and the "esbuild" dependency isn't available. Install esbuild ` +
|
|
92
|
+
`(it's a direct dependency of nestjs-docfy and should already be present — ` +
|
|
93
|
+
`check your install), or disable webpack bundling ("webpack": false in ` +
|
|
94
|
+
`nest-cli.json) so docs files get compiled to .js like everything else.`);
|
|
95
|
+
}
|
|
96
|
+
require.extensions['.ts'] = (mod, filename) => {
|
|
97
|
+
const source = fs.readFileSync(filename, 'utf8');
|
|
98
|
+
const { code } = esbuild.transformSync(source, {
|
|
99
|
+
loader: 'ts',
|
|
100
|
+
format: 'cjs',
|
|
101
|
+
target: 'es2019',
|
|
102
|
+
sourcefile: filename,
|
|
103
|
+
// A docs file's own relative imports can pull in real application
|
|
104
|
+
// source (e.g. the controller it documents), which legitimately uses
|
|
105
|
+
// NestJS's decorator syntax — without this, esbuild rejects parameter
|
|
106
|
+
// decorators like `@Body()` outright.
|
|
107
|
+
tsconfigRaw: { compilerOptions: { experimentalDecorators: true, emitDecoratorMetadata: true } },
|
|
108
|
+
});
|
|
109
|
+
mod._compile(code, filename);
|
|
110
|
+
};
|
|
111
|
+
registered = true;
|
|
112
|
+
}
|
|
113
|
+
function loadEsbuild() {
|
|
114
|
+
try {
|
|
115
|
+
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
116
|
+
return require('esbuild');
|
|
117
|
+
}
|
|
118
|
+
catch {
|
|
119
|
+
return null;
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
//# sourceMappingURL=require-ts.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"require-ts.js","sourceRoot":"","sources":["../src/require-ts.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,sDAeC;AAtDD,uCAAyB;AAQzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,SAAgB,qBAAqB,CAAC,OAAe;IACnD,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3G,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,uEAAuE;QACvE,uEAAuE;QACvE,sEAAsE;QACtE,6CAA6C;QAC7C,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,uBAAuB,OAAO,GAAG,CAAC,EAAE;YAChE,IAAI,EAAE,kBAAkB;SACzB,CAAC,CAAC;IACL,CAAC;IAED,mBAAmB,EAAE,CAAC;IACtB,iEAAiE;IACjE,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC;AAED,IAAI,UAAU,GAAG,KAAK,CAAC;AAEvB,SAAS,mBAAmB;IAC1B,IAAI,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO;IACpD,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;IAC9B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,iFAAiF;YAC/E,+EAA+E;YAC/E,4EAA4E;YAC5E,wEAAwE;YACxE,wEAAwE,CAC3E,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE;QAC5C,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACjD,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,EAAE;YAC7C,MAAM,EAAE,IAAI;YACZ,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,QAAQ;YAChB,UAAU,EAAE,QAAQ;YACpB,kEAAkE;YAClE,qEAAqE;YACrE,sEAAsE;YACtE,sCAAsC;YACtC,WAAW,EAAE,EAAE,eAAe,EAAE,EAAE,sBAAsB,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,EAAE;SAChG,CAAC,CAAC;QACF,GAAqC,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAClE,CAAC,CAAC;IACF,UAAU,GAAG,IAAI,CAAC;AACpB,CAAC;AAED,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,iEAAiE;QACjE,OAAO,OAAO,CAAC,SAAS,CAAkB,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
|
|
@@ -13,6 +13,15 @@ type CacheSnapshot = Record<string, {
|
|
|
13
13
|
* - the class is only found via a barrel re-export (index.ts) rather than its own file
|
|
14
14
|
*
|
|
15
15
|
* @param readCache Injected for testing; defaults to () => require.cache.
|
|
16
|
+
* @param callSiteStack The `Error().stack` captured by `@WithDocs()` at the
|
|
17
|
+
* controller's own decoration site. Used as a fallback when the controller's
|
|
18
|
+
* file has no require.cache entry — which is always true when the app is
|
|
19
|
+
* bundled (NestJS CLI's `webpack: true` build mode, the documented default
|
|
20
|
+
* for monorepos): bundlers inline every module into one file and never
|
|
21
|
+
* populate require.cache per original source file, so the cache-based
|
|
22
|
+
* lookup below can never find anything to return. In that case we resolve
|
|
23
|
+
* the bundle position from the stack trace back to the original file via
|
|
24
|
+
* that bundle's source map (emitted by default by the webpack build).
|
|
16
25
|
*/
|
|
17
|
-
export declare function resolveDocsPath(controllerClass: Function, readCache?: () => CacheSnapshot): string | null;
|
|
26
|
+
export declare function resolveDocsPath(controllerClass: Function, readCache?: () => CacheSnapshot, callSiteStack?: string): string | null;
|
|
18
27
|
export {};
|
|
@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.resolveDocsPath = resolveDocsPath;
|
|
37
37
|
const path = __importStar(require("path"));
|
|
38
|
+
const resolve_source_from_stack_1 = require("./resolve-source-from-stack");
|
|
38
39
|
/**
|
|
39
40
|
* Given a controller class, finds its own source file in require.cache and derives
|
|
40
41
|
* the companion docs file path by replacing the suffix:
|
|
@@ -47,9 +48,18 @@ const path = __importStar(require("path"));
|
|
|
47
48
|
* - the class is only found via a barrel re-export (index.ts) rather than its own file
|
|
48
49
|
*
|
|
49
50
|
* @param readCache Injected for testing; defaults to () => require.cache.
|
|
51
|
+
* @param callSiteStack The `Error().stack` captured by `@WithDocs()` at the
|
|
52
|
+
* controller's own decoration site. Used as a fallback when the controller's
|
|
53
|
+
* file has no require.cache entry — which is always true when the app is
|
|
54
|
+
* bundled (NestJS CLI's `webpack: true` build mode, the documented default
|
|
55
|
+
* for monorepos): bundlers inline every module into one file and never
|
|
56
|
+
* populate require.cache per original source file, so the cache-based
|
|
57
|
+
* lookup below can never find anything to return. In that case we resolve
|
|
58
|
+
* the bundle position from the stack trace back to the original file via
|
|
59
|
+
* that bundle's source map (emitted by default by the webpack build).
|
|
50
60
|
*/
|
|
51
|
-
function resolveDocsPath(controllerClass, readCache = () => require.cache) {
|
|
52
|
-
const controllerFile = findFileInCache(controllerClass, readCache());
|
|
61
|
+
function resolveDocsPath(controllerClass, readCache = () => require.cache, callSiteStack) {
|
|
62
|
+
const controllerFile = findFileInCache(controllerClass, readCache()) ?? resolveFromCallSite(callSiteStack);
|
|
53
63
|
if (!controllerFile)
|
|
54
64
|
return null;
|
|
55
65
|
const ext = path.extname(controllerFile); // .ts or .js
|
|
@@ -59,6 +69,12 @@ function resolveDocsPath(controllerClass, readCache = () => require.cache) {
|
|
|
59
69
|
return null;
|
|
60
70
|
return `${base}.docs${ext}`;
|
|
61
71
|
}
|
|
72
|
+
function resolveFromCallSite(callSiteStack) {
|
|
73
|
+
const loc = (0, resolve_source_from_stack_1.parseCallSite)(callSiteStack);
|
|
74
|
+
if (!loc)
|
|
75
|
+
return null;
|
|
76
|
+
return (0, resolve_source_from_stack_1.resolveOriginalPath)(loc);
|
|
77
|
+
}
|
|
62
78
|
/**
|
|
63
79
|
* Searches require.cache for the file that directly owns the class.
|
|
64
80
|
*
|
|
@@ -72,7 +88,19 @@ function findFileInCache(target, cache) {
|
|
|
72
88
|
if (!mod?.exports)
|
|
73
89
|
continue;
|
|
74
90
|
for (const key of Object.keys(mod.exports)) {
|
|
75
|
-
|
|
91
|
+
// Some third-party modules (e.g. express's `request.js`) export an
|
|
92
|
+
// object with enumerable getters that throw outside their expected
|
|
93
|
+
// context (`req.query` reads `this.app`, undefined here). Reading
|
|
94
|
+
// those would crash this require.cache scan, so any getter that
|
|
95
|
+
// throws is treated as a non-match instead of propagating.
|
|
96
|
+
let value;
|
|
97
|
+
try {
|
|
98
|
+
value = mod.exports[key];
|
|
99
|
+
}
|
|
100
|
+
catch {
|
|
101
|
+
continue;
|
|
102
|
+
}
|
|
103
|
+
if (value === target) {
|
|
76
104
|
candidates.push(filename);
|
|
77
105
|
break;
|
|
78
106
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"resolve-docs-path.js","sourceRoot":"","sources":["../src/resolve-docs-path.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
|
|
1
|
+
{"version":3,"file":"resolve-docs-path.js","sourceRoot":"","sources":["../src/resolve-docs-path.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,0CAgBC;AA3CD,2CAA6B;AAC7B,2EAAiF;AAIjF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,eAAe,CAC7B,eAAyB,EACzB,YAAiC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAiC,EAChF,aAAsB;IAEtB,MAAM,cAAc,GAClB,eAAe,CAAC,eAAe,EAAE,SAAS,EAAE,CAAC,IAAI,mBAAmB,CAAC,aAAa,CAAC,CAAC;IACtF,IAAI,CAAC,cAAc;QAAE,OAAO,IAAI,CAAC;IAEjC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,aAAa;IACvD,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAElD,kFAAkF;IAClF,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC;QAAE,OAAO,IAAI,CAAC;IAE/C,OAAO,GAAG,IAAI,QAAQ,GAAG,EAAE,CAAC;AAC9B,CAAC;AAED,SAAS,mBAAmB,CAAC,aAAiC;IAC5D,MAAM,GAAG,GAAG,IAAA,yCAAa,EAAC,aAAa,CAAC,CAAC;IACzC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,OAAO,IAAA,+CAAmB,EAAC,GAAG,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,MAAgB,EAAE,KAAoB;IAC7D,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,KAAK,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACpD,IAAI,CAAC,GAAG,EAAE,OAAO;YAAE,SAAS;QAC5B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3C,mEAAmE;YACnE,mEAAmE;YACnE,kEAAkE;YAClE,gEAAgE;YAChE,2DAA2D;YAC3D,IAAI,KAAc,CAAC;YACnB,IAAI,CAAC;gBACH,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;YACD,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;gBACrB,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAC1B,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC;IAElD,4DAA4D;IAC5D,kEAAkE;IAClE,qEAAqE;IACrE,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;IAEH,OAAO,UAAU,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC"}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
export interface StackLocation {
|
|
2
|
+
file: string;
|
|
3
|
+
line: number;
|
|
4
|
+
column: number;
|
|
5
|
+
}
|
|
6
|
+
/**
|
|
7
|
+
* Parses a V8 stack trace string (as captured by `new Error().stack`) and
|
|
8
|
+
* returns the call site of whatever invoked the function that captured it.
|
|
9
|
+
*
|
|
10
|
+
* The first frame (right after the "Error" header line) is always the
|
|
11
|
+
* capturing function's own location — that's a property of how
|
|
12
|
+
* `Error().stack` works, unaffected by bundling — so it's always skipped
|
|
13
|
+
* unconditionally rather than identified by file path: after bundling,
|
|
14
|
+
* both that frame and the real caller's frame report the *same* bundle
|
|
15
|
+
* file (just different line/column), so a filename-based skip can't tell
|
|
16
|
+
* them apart, but a positional one always can.
|
|
17
|
+
*
|
|
18
|
+
* Used as a fallback when `resolveDocsPath`'s require.cache lookup fails —
|
|
19
|
+
* which happens whenever the app is bundled (e.g. NestJS CLI's `webpack:
|
|
20
|
+
* true` build mode, the documented default for monorepos), since bundlers
|
|
21
|
+
* inline every module into one file and never populate Node's require.cache
|
|
22
|
+
* with one entry per original source file.
|
|
23
|
+
*/
|
|
24
|
+
export declare function parseCallSite(stack: string | undefined): StackLocation | null;
|
|
25
|
+
/**
|
|
26
|
+
* Given a location inside a (possibly bundled) compiled file, resolves it
|
|
27
|
+
* back to the original source file path using that file's source map, if
|
|
28
|
+
* one is available (sidecar `.map` file or an inlined `sourceMappingURL`
|
|
29
|
+
* data URI — both of which NestJS CLI's webpack build emits by default).
|
|
30
|
+
*
|
|
31
|
+
* Returns the input location's file unchanged if no source map is found or
|
|
32
|
+
* it fails to resolve a source for that position — the caller falls back
|
|
33
|
+
* to its existing behavior in that case.
|
|
34
|
+
*/
|
|
35
|
+
export declare function resolveOriginalPath(loc: StackLocation): string;
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.parseCallSite = parseCallSite;
|
|
37
|
+
exports.resolveOriginalPath = resolveOriginalPath;
|
|
38
|
+
const fs = __importStar(require("fs"));
|
|
39
|
+
const path = __importStar(require("path"));
|
|
40
|
+
const source_map_1 = require("source-map");
|
|
41
|
+
const STACK_FRAME_RE = /\(?([^()\s]+):(\d+):(\d+)\)?\s*$/;
|
|
42
|
+
/**
|
|
43
|
+
* Parses a V8 stack trace string (as captured by `new Error().stack`) and
|
|
44
|
+
* returns the call site of whatever invoked the function that captured it.
|
|
45
|
+
*
|
|
46
|
+
* The first frame (right after the "Error" header line) is always the
|
|
47
|
+
* capturing function's own location — that's a property of how
|
|
48
|
+
* `Error().stack` works, unaffected by bundling — so it's always skipped
|
|
49
|
+
* unconditionally rather than identified by file path: after bundling,
|
|
50
|
+
* both that frame and the real caller's frame report the *same* bundle
|
|
51
|
+
* file (just different line/column), so a filename-based skip can't tell
|
|
52
|
+
* them apart, but a positional one always can.
|
|
53
|
+
*
|
|
54
|
+
* Used as a fallback when `resolveDocsPath`'s require.cache lookup fails —
|
|
55
|
+
* which happens whenever the app is bundled (e.g. NestJS CLI's `webpack:
|
|
56
|
+
* true` build mode, the documented default for monorepos), since bundlers
|
|
57
|
+
* inline every module into one file and never populate Node's require.cache
|
|
58
|
+
* with one entry per original source file.
|
|
59
|
+
*/
|
|
60
|
+
function parseCallSite(stack) {
|
|
61
|
+
if (!stack)
|
|
62
|
+
return null;
|
|
63
|
+
const lines = stack.split('\n').slice(2); // drop "Error" header + the capturing function's own frame
|
|
64
|
+
for (const rawLine of lines) {
|
|
65
|
+
const match = STACK_FRAME_RE.exec(rawLine.trim());
|
|
66
|
+
if (!match)
|
|
67
|
+
continue;
|
|
68
|
+
const [, file, lineStr, colStr] = match;
|
|
69
|
+
if (!file)
|
|
70
|
+
continue;
|
|
71
|
+
if (file.includes(`${path.sep}node_modules${path.sep}`))
|
|
72
|
+
continue;
|
|
73
|
+
return { file, line: Number(lineStr), column: Number(colStr) };
|
|
74
|
+
}
|
|
75
|
+
return null;
|
|
76
|
+
}
|
|
77
|
+
function loadSourceMap(bundleFile) {
|
|
78
|
+
const sidecarPath = `${bundleFile}.map`;
|
|
79
|
+
if (fs.existsSync(sidecarPath)) {
|
|
80
|
+
try {
|
|
81
|
+
return JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
|
|
82
|
+
}
|
|
83
|
+
catch {
|
|
84
|
+
return null;
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
try {
|
|
88
|
+
const contents = fs.readFileSync(bundleFile, 'utf8');
|
|
89
|
+
const match = /\/\/[#@]\s*sourceMappingURL=data:application\/json;(?:charset=[^;]+;)?base64,([a-zA-Z0-9+/=]+)\s*$/m.exec(contents);
|
|
90
|
+
if (!match)
|
|
91
|
+
return null;
|
|
92
|
+
const decoded = Buffer.from(match[1], 'base64').toString('utf8');
|
|
93
|
+
return JSON.parse(decoded);
|
|
94
|
+
}
|
|
95
|
+
catch {
|
|
96
|
+
return null;
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Given a location inside a (possibly bundled) compiled file, resolves it
|
|
101
|
+
* back to the original source file path using that file's source map, if
|
|
102
|
+
* one is available (sidecar `.map` file or an inlined `sourceMappingURL`
|
|
103
|
+
* data URI — both of which NestJS CLI's webpack build emits by default).
|
|
104
|
+
*
|
|
105
|
+
* Returns the input location's file unchanged if no source map is found or
|
|
106
|
+
* it fails to resolve a source for that position — the caller falls back
|
|
107
|
+
* to its existing behavior in that case.
|
|
108
|
+
*/
|
|
109
|
+
function resolveOriginalPath(loc) {
|
|
110
|
+
// If something in the process already registered automatic stack
|
|
111
|
+
// source-mapping (e.g. ts-node, or webpack/Node's own source-map
|
|
112
|
+
// support), `loc.file` may already be a `webpack://<namespace>/<path>`
|
|
113
|
+
// URI rather than a real bundle file path — Node's resolved it for us,
|
|
114
|
+
// it just left the result in webpack's own URI form. There's no real
|
|
115
|
+
// file to read a `.map` sidecar from in that case (the bundle path is
|
|
116
|
+
// gone), so resolve this directly instead of going through
|
|
117
|
+
// loadSourceMap/SourceMapConsumer below.
|
|
118
|
+
const directWebpackSource = stripWebpackProtocol(loc.file);
|
|
119
|
+
if (directWebpackSource)
|
|
120
|
+
return path.resolve(process.cwd(), directWebpackSource);
|
|
121
|
+
const map = loadSourceMap(loc.file);
|
|
122
|
+
if (!map)
|
|
123
|
+
return loc.file;
|
|
124
|
+
try {
|
|
125
|
+
const consumer = new source_map_1.SourceMapConsumer(map);
|
|
126
|
+
const original = consumer.originalPositionFor({ line: loc.line, column: loc.column });
|
|
127
|
+
if (!original.source)
|
|
128
|
+
return loc.file;
|
|
129
|
+
const webpackSource = stripWebpackProtocol(original.source);
|
|
130
|
+
if (webpackSource) {
|
|
131
|
+
// webpack's own sourceRoot/source values are namespace URIs, not real
|
|
132
|
+
// paths — e.g. "webpack://api-gateway/./apps/api-gateway/src/x.ts" —
|
|
133
|
+
// so for these we resolve relative to the process's cwd (the project
|
|
134
|
+
// root in standard `nest start`/`nest build` usage) instead of mapDir.
|
|
135
|
+
return path.resolve(process.cwd(), webpackSource);
|
|
136
|
+
}
|
|
137
|
+
const mapDir = path.dirname(loc.file);
|
|
138
|
+
const sourceRoot = map.sourceRoot ?? '';
|
|
139
|
+
return path.resolve(mapDir, sourceRoot, original.source);
|
|
140
|
+
}
|
|
141
|
+
catch {
|
|
142
|
+
return loc.file;
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* Strips a `webpack://<namespace>/` prefix from a source-map `source` entry,
|
|
147
|
+
* returning the remaining relative path, or null if it isn't a webpack URI.
|
|
148
|
+
*/
|
|
149
|
+
function stripWebpackProtocol(source) {
|
|
150
|
+
const match = /^webpack:\/\/[^/]*\/(.*)$/.exec(source);
|
|
151
|
+
return match ? match[1] : null;
|
|
152
|
+
}
|
|
153
|
+
//# sourceMappingURL=resolve-source-from-stack.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"resolve-source-from-stack.js","sourceRoot":"","sources":["../src/resolve-source-from-stack.ts"],"names":[],"mappings":"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"}
|