nestjs-docfy 0.1.3 → 0.2.0

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 (40) hide show
  1. package/README.md +112 -32
  2. package/dist/cli/detect-project.d.ts +13 -0
  3. package/dist/cli/detect-project.js +318 -0
  4. package/dist/cli/detect-project.js.map +1 -0
  5. package/dist/cli/errors.d.ts +15 -0
  6. package/dist/cli/errors.js +26 -0
  7. package/dist/cli/errors.js.map +1 -0
  8. package/dist/cli/extract-methods.d.ts +34 -0
  9. package/dist/cli/extract-methods.js +171 -0
  10. package/dist/cli/extract-methods.js.map +1 -0
  11. package/dist/cli/generate-file.d.ts +11 -0
  12. package/dist/cli/generate-file.js +127 -0
  13. package/dist/cli/generate-file.js.map +1 -0
  14. package/dist/cli/index.d.ts +2 -0
  15. package/dist/cli/index.js +130 -0
  16. package/dist/cli/index.js.map +1 -0
  17. package/dist/cli/logger.d.ts +5 -0
  18. package/dist/cli/logger.js +48 -0
  19. package/dist/cli/logger.js.map +1 -0
  20. package/dist/cli/merge-docs.d.ts +19 -0
  21. package/dist/cli/merge-docs.js +87 -0
  22. package/dist/cli/merge-docs.js.map +1 -0
  23. package/dist/cli/parse-args.d.ts +42 -0
  24. package/dist/cli/parse-args.js +85 -0
  25. package/dist/cli/parse-args.js.map +1 -0
  26. package/dist/cli/project-types.d.ts +18 -0
  27. package/dist/cli/project-types.js +3 -0
  28. package/dist/cli/project-types.js.map +1 -0
  29. package/dist/cli/resolve-tsconfig.d.ts +5 -0
  30. package/dist/cli/resolve-tsconfig.js +39 -0
  31. package/dist/cli/resolve-tsconfig.js.map +1 -0
  32. package/dist/cli/scan-controllers.d.ts +24 -0
  33. package/dist/cli/scan-controllers.js +157 -0
  34. package/dist/cli/scan-controllers.js.map +1 -0
  35. package/dist/cli/writer.d.ts +25 -0
  36. package/dist/cli/writer.js +115 -0
  37. package/dist/cli/writer.js.map +1 -0
  38. package/dist/docs.d.ts +4 -4
  39. package/dist/docs.js.map +1 -1
  40. package/package.json +11 -2
@@ -0,0 +1,171 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.extractMethods = extractMethods;
4
+ exports.extractControllerPath = extractControllerPath;
5
+ const ts_morph_1 = require("ts-morph");
6
+ const HTTP_DECORATORS = new Set([
7
+ 'Get', 'Post', 'Put', 'Patch', 'Delete', 'Head', 'Options', 'All',
8
+ ]);
9
+ const NEST_PARAM_DECORATORS = new Set([
10
+ 'Param', 'Body', 'Query', 'Headers', 'Req', 'Res', 'Request',
11
+ 'Response', 'Session', 'UploadedFile', 'UploadedFiles', 'Ip', 'HostParam',
12
+ ]);
13
+ function getDecoratorName(dec) {
14
+ try {
15
+ return dec.getName() ?? null;
16
+ }
17
+ catch {
18
+ return null;
19
+ }
20
+ }
21
+ function getDecoratorFirstStringArg(method, decoratorName) {
22
+ try {
23
+ const dec = method.getDecorator(decoratorName);
24
+ if (!dec)
25
+ return null;
26
+ const args = dec.getArguments();
27
+ if (args.length === 0)
28
+ return '';
29
+ const first = args[0];
30
+ if (first.getKind() === ts_morph_1.SyntaxKind.StringLiteral) {
31
+ return first.getText().replace(/^['"`]|['"`]$/g, '');
32
+ }
33
+ return null;
34
+ }
35
+ catch {
36
+ return null;
37
+ }
38
+ }
39
+ function extractParams(method) {
40
+ try {
41
+ return method.getParameters().map((p) => {
42
+ let nestDecorator = null;
43
+ for (const dec of p.getDecorators()) {
44
+ const name = getDecoratorName(dec);
45
+ if (name && NEST_PARAM_DECORATORS.has(name)) {
46
+ nestDecorator = `@${name}`;
47
+ break;
48
+ }
49
+ }
50
+ const typeNode = p.getTypeNode();
51
+ return {
52
+ name: p.getName(),
53
+ type: typeNode ? typeNode.getText() : 'unknown',
54
+ nestDecorator,
55
+ };
56
+ });
57
+ }
58
+ catch {
59
+ return [];
60
+ }
61
+ }
62
+ /**
63
+ * Extracts public, non-static methods from a controller class declaration.
64
+ * Marks inherited methods (from base classes) but still includes them.
65
+ * Private and protected methods are ignored.
66
+ */
67
+ function extractMethods(cls) {
68
+ const results = [];
69
+ const ownMethodNames = new Set(cls.getMethods().map((m) => m.getName()));
70
+ // Own methods
71
+ for (const method of cls.getMethods()) {
72
+ if (method.hasModifier(ts_morph_1.SyntaxKind.PrivateKeyword))
73
+ continue;
74
+ if (method.hasModifier(ts_morph_1.SyntaxKind.ProtectedKeyword))
75
+ continue;
76
+ if (method.isStatic())
77
+ continue;
78
+ let httpDecorator = null;
79
+ let httpPath = null;
80
+ for (const dec of method.getDecorators()) {
81
+ const name = getDecoratorName(dec);
82
+ if (name && HTTP_DECORATORS.has(name)) {
83
+ httpDecorator = name;
84
+ httpPath = getDecoratorFirstStringArg(method, name);
85
+ break;
86
+ }
87
+ }
88
+ let returnType = 'unknown';
89
+ try {
90
+ const returnTypeNode = method.getReturnTypeNode();
91
+ returnType = returnTypeNode
92
+ ? returnTypeNode.getText()
93
+ : method.getReturnType().getText();
94
+ }
95
+ catch {
96
+ // ts-morph can fail to infer complex types — keep 'unknown'
97
+ }
98
+ results.push({
99
+ name: method.getName(),
100
+ httpDecorator,
101
+ httpPath,
102
+ params: extractParams(method),
103
+ returnType,
104
+ isAsync: method.isAsync(),
105
+ isInherited: false,
106
+ inheritedFrom: null,
107
+ });
108
+ }
109
+ // Inherited methods from base class(es)
110
+ try {
111
+ const baseClass = cls.getBaseClass();
112
+ if (baseClass) {
113
+ const baseClassName = baseClass.getName() ?? 'unknown';
114
+ for (const method of baseClass.getMethods()) {
115
+ if (method.hasModifier(ts_morph_1.SyntaxKind.PrivateKeyword))
116
+ continue;
117
+ if (method.hasModifier(ts_morph_1.SyntaxKind.ProtectedKeyword))
118
+ continue;
119
+ if (method.isStatic())
120
+ continue;
121
+ if (ownMethodNames.has(method.getName()))
122
+ continue; // overridden
123
+ let httpDecorator = null;
124
+ for (const dec of method.getDecorators()) {
125
+ const name = getDecoratorName(dec);
126
+ if (name && HTTP_DECORATORS.has(name)) {
127
+ httpDecorator = name;
128
+ break;
129
+ }
130
+ }
131
+ results.push({
132
+ name: method.getName(),
133
+ httpDecorator,
134
+ httpPath: null,
135
+ params: extractParams(method),
136
+ returnType: 'unknown',
137
+ isAsync: method.isAsync(),
138
+ isInherited: true,
139
+ inheritedFrom: baseClassName,
140
+ });
141
+ }
142
+ }
143
+ }
144
+ catch {
145
+ // base class resolution is best-effort
146
+ }
147
+ return results;
148
+ }
149
+ /**
150
+ * Extracts the path argument from @Controller('path').
151
+ * Returns null if the decorator is absent or has no string argument.
152
+ */
153
+ function extractControllerPath(cls) {
154
+ try {
155
+ const dec = cls.getDecorator('Controller');
156
+ if (!dec)
157
+ return null;
158
+ const args = dec.getArguments();
159
+ if (args.length === 0)
160
+ return '';
161
+ const first = args[0];
162
+ if (first.getKind() === ts_morph_1.SyntaxKind.StringLiteral) {
163
+ return first.getText().replace(/^['"`]|['"`]$/g, '');
164
+ }
165
+ return null;
166
+ }
167
+ catch {
168
+ return null;
169
+ }
170
+ }
171
+ //# sourceMappingURL=extract-methods.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"extract-methods.js","sourceRoot":"","sources":["../../src/cli/extract-methods.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,11 @@
1
+ import type { ControllerInfo } from './extract-methods';
2
+ /**
3
+ * Computes the relative import path from the generated docs file to the
4
+ * controller file, stripping the .ts extension (CommonJS/ESM convention).
5
+ */
6
+ export declare function relativeImport(docsFilePath: string, controllerFilePath: string): string;
7
+ /**
8
+ * Renders a complete .controller.docs.ts file for the given controller.
9
+ * All user-sourced values are sanitised before interpolation.
10
+ */
11
+ export declare function renderDocsFile(ctrl: ControllerInfo, docsFilePath: string, format: 'ts' | 'js'): string;
@@ -0,0 +1,127 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.relativeImport = relativeImport;
7
+ exports.renderDocsFile = renderDocsFile;
8
+ const path_1 = __importDefault(require("path"));
9
+ // ---------------------------------------------------------------------------
10
+ // Sanitisation helpers — values from AST go through these before any
11
+ // string interpolation so they can never inject executable code.
12
+ // ---------------------------------------------------------------------------
13
+ /** Whitelist for JS identifiers: letters, digits, $ and _. */
14
+ const IDENTIFIER_RE = /^[$_a-zA-Z][$_a-zA-Z0-9]*$/;
15
+ function sanitizeIdentifier(value, fallback) {
16
+ return IDENTIFIER_RE.test(value) ? value : fallback;
17
+ }
18
+ /** Strips characters that could close a JS string or inject code into a comment. */
19
+ function sanitizeComment(value) {
20
+ return value.replace(/[`'"\\*]/g, '').slice(0, 200);
21
+ }
22
+ /** Escapes a URL path for safe use inside a line comment. */
23
+ function sanitizeHttpPath(value) {
24
+ if (!value)
25
+ return '';
26
+ return '/' + value.replace(/[^a-zA-Z0-9/_:.-]/g, '');
27
+ }
28
+ // ---------------------------------------------------------------------------
29
+ // Import path resolution
30
+ // ---------------------------------------------------------------------------
31
+ /**
32
+ * Computes the relative import path from the generated docs file to the
33
+ * controller file, stripping the .ts extension (CommonJS/ESM convention).
34
+ */
35
+ function relativeImport(docsFilePath, controllerFilePath) {
36
+ const rel = path_1.default.relative(path_1.default.dirname(docsFilePath), controllerFilePath);
37
+ const withoutExt = rel.replace(/\.ts$/, '');
38
+ // Ensure it starts with ./ for Node module resolution
39
+ return withoutExt.startsWith('.') ? withoutExt : `./${withoutExt}`;
40
+ }
41
+ // ---------------------------------------------------------------------------
42
+ // Method signature comment
43
+ // ---------------------------------------------------------------------------
44
+ function methodSignatureComment(m) {
45
+ const verb = m.httpDecorator ? `${m.httpDecorator.toUpperCase()} ` : '';
46
+ const httpPath = m.httpPath !== null ? sanitizeHttpPath(m.httpPath) : '';
47
+ const route = verb || httpPath ? `${verb}${httpPath} → ` : '';
48
+ const paramList = m.params
49
+ .map((p) => `${sanitizeIdentifier(p.name, '_')}: ${sanitizeComment(p.type)}`)
50
+ .join(', ');
51
+ const returnType = sanitizeComment(m.returnType);
52
+ const asyncPrefix = m.isAsync ? 'async ' : '';
53
+ const methodName = sanitizeIdentifier(m.name, '_');
54
+ const inherited = m.isInherited && m.inheritedFrom
55
+ ? ` [inherited from ${sanitizeComment(m.inheritedFrom)}]`
56
+ : '';
57
+ return `${route}${asyncPrefix}${methodName}(${paramList}): ${returnType}${inherited}`;
58
+ }
59
+ // ---------------------------------------------------------------------------
60
+ // Template
61
+ // ---------------------------------------------------------------------------
62
+ function renderMethod(m, indent) {
63
+ const name = sanitizeIdentifier(m.name, '_method');
64
+ const sig = methodSignatureComment(m);
65
+ const lines = [];
66
+ lines.push(`${indent}// ${sig}`);
67
+ lines.push(`${indent}${name}: [`);
68
+ lines.push(`${indent} // ApiOperation({ summary: '' }),`);
69
+ lines.push(`${indent} // ApiResponse({ status: 200 }),`);
70
+ lines.push(`${indent}],`);
71
+ return lines.join('\n');
72
+ }
73
+ /**
74
+ * Renders a complete .controller.docs.ts file for the given controller.
75
+ * All user-sourced values are sanitised before interpolation.
76
+ */
77
+ function renderDocsFile(ctrl, docsFilePath, format) {
78
+ const importPath = relativeImport(docsFilePath, ctrl.filePath);
79
+ const className = sanitizeIdentifier(ctrl.className, 'Controller');
80
+ const controllerRoute = ctrl.controllerPath !== null
81
+ ? ` (route: "${sanitizeHttpPath(ctrl.controllerPath)}")`
82
+ : '';
83
+ const timestamp = new Date().toISOString();
84
+ const methodsBlock = ctrl.methods.length === 0
85
+ ? ' // No public HTTP methods found.'
86
+ : ctrl.methods.map((m) => renderMethod(m, ' ')).join('\n\n');
87
+ if (format === 'js') {
88
+ return [
89
+ `// Auto-generated by nestjs-docfy — fill in the decorator arrays.`,
90
+ `// Generated: ${timestamp}`,
91
+ ``,
92
+ `const { docs } = require('nestjs-docfy');`,
93
+ `const { ${className} } = require('${importPath}');`,
94
+ ``,
95
+ `docs(${className}, {`,
96
+ ` classDecorators: [`,
97
+ ` // ApiTags('${sanitizeComment(ctrl.controllerPath ?? className.replace(/Controller$/, '').toLowerCase())}'),`,
98
+ ` ],`,
99
+ ` methods: {`,
100
+ methodsBlock.split('\n').map((l) => (l ? ` ${l}` : l)).join('\n'),
101
+ ` },`,
102
+ `});`,
103
+ ``,
104
+ ].join('\n');
105
+ }
106
+ return [
107
+ `/**`,
108
+ ` * Auto-generated by nestjs-docfy — fill in the decorator arrays.`,
109
+ ` * Controller: ${className}${controllerRoute}`,
110
+ ` * Generated: ${timestamp}`,
111
+ ` */`,
112
+ `import { docs } from 'nestjs-docfy';`,
113
+ `import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';`,
114
+ `import { ${className} } from '${importPath}';`,
115
+ ``,
116
+ `docs(${className}, {`,
117
+ ` classDecorators: [`,
118
+ ` // ApiTags('${sanitizeComment(ctrl.controllerPath ?? className.replace(/Controller$/, '').toLowerCase())}'),`,
119
+ ` ],`,
120
+ ` methods: {`,
121
+ methodsBlock,
122
+ ` },`,
123
+ `});`,
124
+ ``,
125
+ ].join('\n');
126
+ }
127
+ //# sourceMappingURL=generate-file.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"generate-file.js","sourceRoot":"","sources":["../../src/cli/generate-file.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
@@ -0,0 +1,130 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+ var __importDefault = (this && this.__importDefault) || function (mod) {
4
+ return (mod && mod.__esModule) ? mod : { "default": mod };
5
+ };
6
+ Object.defineProperty(exports, "__esModule", { value: true });
7
+ const commander_1 = require("commander");
8
+ const picocolors_1 = __importDefault(require("picocolors"));
9
+ const parse_args_1 = require("./parse-args");
10
+ const logger_1 = require("./logger");
11
+ const errors_1 = require("./errors");
12
+ const detect_project_1 = require("./detect-project");
13
+ const scan_controllers_1 = require("./scan-controllers");
14
+ const writer_1 = require("./writer");
15
+ const program = new commander_1.Command();
16
+ program
17
+ .name('nestjs-docfy')
18
+ .description('Generate companion docs files for NestJS controllers')
19
+ .version(
20
+ // eslint-disable-next-line @typescript-eslint/no-var-requires
21
+ require('../../package.json').version, '-v, --version');
22
+ program
23
+ .command('generate')
24
+ .description('Scan controllers and generate *.controller.docs.ts files')
25
+ .option('--root <path>', 'Project root directory', '.')
26
+ .option('--tsconfig <path>', 'Path to tsconfig.json (auto-detected if omitted)')
27
+ .option('--pattern <glob>', 'Glob pattern to find controllers', '**/*.controller.ts')
28
+ .option('--out <path>', 'Output directory for generated files (default: alongside each controller)')
29
+ .option('--force', 'Overwrite existing docs files (merges new methods, preserves existing)', false)
30
+ .option('--dry-run', 'Print what would be generated without writing files', false)
31
+ .option('--quiet', 'Suppress all output except errors', false)
32
+ .option('--format <format>', 'Output format: ts or js', 'ts')
33
+ .action(async (rawOpts) => {
34
+ try {
35
+ const options = (0, parse_args_1.parseAndValidateOptions)(rawOpts);
36
+ (0, logger_1.setQuiet)(options.quiet);
37
+ if (options.dryRun) {
38
+ (0, logger_1.header)(`${picocolors_1.default.cyan('[DRY RUN]')} nestjs-docfy generate`);
39
+ }
40
+ else {
41
+ (0, logger_1.header)('nestjs-docfy generate');
42
+ }
43
+ (0, logger_1.log)('info', `Root: ${options.root}`);
44
+ (0, logger_1.log)('info', `Pattern: ${options.pattern}`);
45
+ (0, logger_1.log)('info', `Format: ${options.format}`);
46
+ if (options.tsconfig)
47
+ (0, logger_1.log)('info', `Tsconfig: ${options.tsconfig}`);
48
+ if (options.force)
49
+ (0, logger_1.log)('warn', 'Force mode — new methods merged, existing decorators preserved.');
50
+ if (options.dryRun)
51
+ (0, logger_1.log)('dry', 'Dry-run mode — no files will be written.');
52
+ // ── Detect project ──────────────────────────────────────────────────
53
+ const context = (0, detect_project_1.detectProject)(options.root, options.tsconfig);
54
+ const kindLabel = {
55
+ 'simple': 'Simple project',
56
+ 'nx': 'NX Monorepo',
57
+ 'nest-cli-monorepo': 'Nest CLI Monorepo',
58
+ 'generic-monorepo': 'Generic Monorepo',
59
+ };
60
+ (0, logger_1.log)('success', `Project type detected: ${kindLabel[context.kind]} (${context.apps.length} app${context.apps.length !== 1 ? 's' : ''})`);
61
+ for (const app of context.apps) {
62
+ (0, logger_1.log)('info', ` App "${app.name}" → ${app.tsconfig}`);
63
+ }
64
+ // ── Scan controllers ────────────────────────────────────────────────
65
+ (0, logger_1.header)('Scanning controllers...');
66
+ const scanResult = (0, scan_controllers_1.scanAllApps)(context.apps, context.root, options.pattern !== '**/*.controller.ts' ? options.pattern : undefined, options.format);
67
+ for (const err of scanResult.errors) {
68
+ (0, logger_1.log)('error', `${err.file}: ${err.message}`);
69
+ }
70
+ if (scanResult.controllers.length === 0 && scanResult.errors.length === 0) {
71
+ (0, logger_1.log)('warn', 'No controllers found matching the pattern.');
72
+ (0, logger_1.summary)(0, 0, 0);
73
+ process.exit(0 /* CliExitCode.Ok */);
74
+ }
75
+ // ── Generate / dry-run ──────────────────────────────────────────────
76
+ (0, logger_1.header)(options.dryRun ? 'Preview (dry-run):' : 'Generating docs files...');
77
+ const writeResults = (0, writer_1.writeAllDocs)(scanResult.controllers, {
78
+ projectRoot: context.root,
79
+ outDir: options.out,
80
+ force: options.force,
81
+ dryRun: options.dryRun,
82
+ format: options.format,
83
+ });
84
+ let created = 0, skipped = 0, errors = scanResult.errors.length;
85
+ for (const r of writeResults) {
86
+ switch (r.outcome) {
87
+ case 'created':
88
+ (0, logger_1.log)('success', `${r.controllerClass} → ${r.docsFilePath} ${picocolors_1.default.green('[created]')}`);
89
+ created++;
90
+ break;
91
+ case 'merged':
92
+ (0, logger_1.log)('success', `${r.controllerClass} → ${r.docsFilePath} ${picocolors_1.default.cyan('[merged]')}${r.addedMethods?.length ? ` (+${r.addedMethods.join(', ')})` : ''}`);
93
+ created++;
94
+ break;
95
+ case 'skipped':
96
+ (0, logger_1.log)('skip', `${r.controllerClass} → ${r.docsFilePath} ${picocolors_1.default.gray('[skipped — already exists]')}`);
97
+ skipped++;
98
+ break;
99
+ case 'dry':
100
+ // output already written inline by writer
101
+ break;
102
+ case 'error':
103
+ (0, logger_1.log)('error', `${r.controllerClass}: ${r.error}`);
104
+ errors++;
105
+ break;
106
+ }
107
+ }
108
+ if (!options.dryRun) {
109
+ (0, logger_1.summary)(created, skipped, errors);
110
+ }
111
+ process.exit(errors > 0 ? 1 /* CliExitCode.PartialError */ : 0 /* CliExitCode.Ok */);
112
+ }
113
+ catch (err) {
114
+ if (err instanceof errors_1.CliError) {
115
+ process.stderr.write(`\n${picocolors_1.default.red('✖ Error:')} ${err.message}\n\n`);
116
+ process.exit(err.exitCode);
117
+ }
118
+ if (err instanceof Error) {
119
+ process.stderr.write(`\n${picocolors_1.default.red('✖ Error:')} ${err.message}\n\n`);
120
+ }
121
+ else {
122
+ process.stderr.write(`\n${picocolors_1.default.red('✖ Unknown error')}\n\n`);
123
+ }
124
+ process.exit(2 /* CliExitCode.Fatal */);
125
+ }
126
+ });
127
+ program.parseAsync(process.argv).catch(() => {
128
+ process.exit(2 /* CliExitCode.Fatal */);
129
+ });
130
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,5 @@
1
+ export type LogLevel = 'info' | 'warn' | 'error' | 'success' | 'skip' | 'dry';
2
+ export declare function setQuiet(value: boolean): void;
3
+ export declare function log(level: LogLevel, message: string): void;
4
+ export declare function header(message: string): void;
5
+ export declare function summary(created: number, skipped: number, errors: number): void;
@@ -0,0 +1,48 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.setQuiet = setQuiet;
7
+ exports.log = log;
8
+ exports.header = header;
9
+ exports.summary = summary;
10
+ const picocolors_1 = __importDefault(require("picocolors"));
11
+ let quiet = false;
12
+ function setQuiet(value) {
13
+ quiet = value;
14
+ }
15
+ function prefix(level) {
16
+ switch (level) {
17
+ case 'success': return picocolors_1.default.green('✔');
18
+ case 'warn': return picocolors_1.default.yellow('⚠');
19
+ case 'error': return picocolors_1.default.red('✖');
20
+ case 'skip': return picocolors_1.default.gray('–');
21
+ case 'dry': return picocolors_1.default.cyan('~');
22
+ case 'info': return picocolors_1.default.blue('ℹ');
23
+ }
24
+ }
25
+ function log(level, message) {
26
+ if (quiet && level !== 'error')
27
+ return;
28
+ const out = level === 'error' ? process.stderr : process.stdout;
29
+ out.write(` ${prefix(level)} ${message}\n`);
30
+ }
31
+ function header(message) {
32
+ if (quiet)
33
+ return;
34
+ process.stdout.write(`\n${picocolors_1.default.bold(message)}\n`);
35
+ }
36
+ function summary(created, skipped, errors) {
37
+ if (quiet)
38
+ return;
39
+ const parts = [];
40
+ if (created > 0)
41
+ parts.push(picocolors_1.default.green(`${created} created`));
42
+ if (skipped > 0)
43
+ parts.push(picocolors_1.default.gray(`${skipped} skipped`));
44
+ if (errors > 0)
45
+ parts.push(picocolors_1.default.red(`${errors} error${errors > 1 ? 's' : ''}`));
46
+ process.stdout.write(`\n${picocolors_1.default.bold('Done.')} ${parts.join(' · ')}\n\n`);
47
+ }
48
+ //# sourceMappingURL=logger.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/cli/logger.ts"],"names":[],"mappings":";;;;;AAMA,4BAEC;AAaD,kBAIC;AAED,wBAGC;AAED,0BAOC;AAvCD,4DAA4B;AAI5B,IAAI,KAAK,GAAG,KAAK,CAAC;AAElB,SAAgB,QAAQ,CAAC,KAAc;IACrC,KAAK,GAAG,KAAK,CAAC;AAChB,CAAC;AAED,SAAS,MAAM,CAAC,KAAe;IAC7B,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,SAAS,CAAC,CAAC,OAAO,oBAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrC,KAAK,MAAM,CAAC,CAAI,OAAO,oBAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACtC,KAAK,OAAO,CAAC,CAAG,OAAO,oBAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,KAAK,MAAM,CAAC,CAAI,OAAO,oBAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpC,KAAK,KAAK,CAAC,CAAK,OAAO,oBAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpC,KAAK,MAAM,CAAC,CAAI,OAAO,oBAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC;AACH,CAAC;AAED,SAAgB,GAAG,CAAC,KAAe,EAAE,OAAe;IAClD,IAAI,KAAK,IAAI,KAAK,KAAK,OAAO;QAAE,OAAO;IACvC,MAAM,GAAG,GAAG,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IAChE,GAAG,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,IAAI,OAAO,IAAI,CAAC,CAAC;AAC/C,CAAC;AAED,SAAgB,MAAM,CAAC,OAAe;IACpC,IAAI,KAAK;QAAE,OAAO;IAClB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,oBAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,SAAgB,OAAO,CAAC,OAAe,EAAE,OAAe,EAAE,MAAc;IACtE,IAAI,KAAK;QAAE,OAAO;IAClB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,GAAG,CAAC;QAAG,KAAK,CAAC,IAAI,CAAC,oBAAE,CAAC,KAAK,CAAC,GAAG,OAAO,UAAU,CAAC,CAAC,CAAC;IAC7D,IAAI,OAAO,GAAG,CAAC;QAAG,KAAK,CAAC,IAAI,CAAC,oBAAE,CAAC,IAAI,CAAC,GAAG,OAAO,UAAU,CAAC,CAAC,CAAC;IAC5D,IAAI,MAAM,GAAG,CAAC;QAAI,KAAK,CAAC,IAAI,CAAC,oBAAE,CAAC,GAAG,CAAC,GAAG,MAAM,SAAS,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAChF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,oBAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACzE,CAAC"}
@@ -0,0 +1,19 @@
1
+ import type { ControllerInfo } from './extract-methods';
2
+ export interface MergeResult {
3
+ content: string;
4
+ addedMethods: string[];
5
+ }
6
+ /**
7
+ * Merges newly discovered controller methods into an existing docs file.
8
+ *
9
+ * Strategy:
10
+ * - Parse the existing file via ts-morph (AST, no execution).
11
+ * - Find the `docs(ControllerName, { methods: { ... } })` call.
12
+ * - Add entries for methods that are present in `ctrl.methods` but
13
+ * absent as keys in the existing `methods` object.
14
+ * - Leave everything else untouched — user-edited decorators are preserved.
15
+ *
16
+ * If the existing file cannot be parsed or the `docs()` call cannot be
17
+ * located, returns null so the caller can fall back to overwrite.
18
+ */
19
+ export declare function mergeDocsFile(existingContent: string, ctrl: ControllerInfo): MergeResult | null;
@@ -0,0 +1,87 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.mergeDocsFile = mergeDocsFile;
4
+ const ts_morph_1 = require("ts-morph");
5
+ /**
6
+ * Merges newly discovered controller methods into an existing docs file.
7
+ *
8
+ * Strategy:
9
+ * - Parse the existing file via ts-morph (AST, no execution).
10
+ * - Find the `docs(ControllerName, { methods: { ... } })` call.
11
+ * - Add entries for methods that are present in `ctrl.methods` but
12
+ * absent as keys in the existing `methods` object.
13
+ * - Leave everything else untouched — user-edited decorators are preserved.
14
+ *
15
+ * If the existing file cannot be parsed or the `docs()` call cannot be
16
+ * located, returns null so the caller can fall back to overwrite.
17
+ */
18
+ function mergeDocsFile(existingContent, ctrl) {
19
+ let project;
20
+ try {
21
+ project = new ts_morph_1.Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
22
+ }
23
+ catch {
24
+ return null;
25
+ }
26
+ const sf = project.createSourceFile('existing.docs.ts', existingContent);
27
+ const addedMethods = [];
28
+ // Find: docs(ClassName, { ... })
29
+ const docsCall = sf.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression).find((call) => {
30
+ try {
31
+ const expr = call.getExpression();
32
+ return expr.getText() === 'docs';
33
+ }
34
+ catch {
35
+ return false;
36
+ }
37
+ });
38
+ if (!docsCall)
39
+ return null;
40
+ const args = docsCall.getArguments();
41
+ if (args.length < 2)
42
+ return null;
43
+ const configArg = args[1];
44
+ if (configArg.getKind() !== ts_morph_1.SyntaxKind.ObjectLiteralExpression)
45
+ return null;
46
+ const configObj = configArg;
47
+ // Find or create the `methods` property
48
+ let methodsProp = configObj.getProperty('methods');
49
+ if (!methodsProp) {
50
+ // Add methods: {} if not present
51
+ configObj.addPropertyAssignment({ name: 'methods', initializer: '{}' });
52
+ methodsProp = configObj.getProperty('methods');
53
+ if (!methodsProp)
54
+ return null;
55
+ }
56
+ // Get the methods object literal
57
+ const methodsValue = methodsProp.getChildrenOfKind(ts_morph_1.SyntaxKind.ObjectLiteralExpression)[0];
58
+ if (!methodsValue)
59
+ return null;
60
+ // Collect existing method keys (already documented)
61
+ const existingKeys = new Set(methodsValue.getProperties().map((p) => {
62
+ try {
63
+ return p.getFirstChildByKind(ts_morph_1.SyntaxKind.Identifier)?.getText() ?? '';
64
+ }
65
+ catch {
66
+ return '';
67
+ }
68
+ }));
69
+ // Add missing methods
70
+ for (const method of ctrl.methods) {
71
+ // Validate identifier before touching the AST
72
+ if (!/^[$_a-zA-Z][$_a-zA-Z0-9]*$/.test(method.name))
73
+ continue;
74
+ if (existingKeys.has(method.name))
75
+ continue;
76
+ methodsValue.addPropertyAssignment({
77
+ name: method.name,
78
+ initializer: `[\n // ApiOperation({ summary: '' }),\n // ApiResponse({ status: 200 }),\n ]`,
79
+ });
80
+ addedMethods.push(method.name);
81
+ }
82
+ return {
83
+ content: sf.getFullText(),
84
+ addedMethods,
85
+ };
86
+ }
87
+ //# sourceMappingURL=merge-docs.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"merge-docs.js","sourceRoot":"","sources":["../../src/cli/merge-docs.ts"],"names":[],"mappings":";;AAqBA,sCAgFC;AArGD,uCAAgG;AAQhG;;;;;;;;;;;;GAYG;AACH,SAAgB,aAAa,CAC3B,eAAuB,EACvB,IAAoB;IAEpB,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,kBAAO,CAAC,EAAE,qBAAqB,EAAE,IAAI,EAAE,4BAA4B,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,eAAe,CAAC,CAAC;IACzE,MAAM,YAAY,GAAa,EAAE,CAAC;IAElC,iCAAiC;IACjC,MAAM,QAAQ,GAAG,EAAE,CAAC,oBAAoB,CAAC,qBAAU,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;QAChF,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC,OAAO,EAAE,KAAK,MAAM,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE3B,MAAM,IAAI,GAAG,QAAQ,CAAC,YAAY,EAAE,CAAC;IACrC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEjC,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,SAAS,CAAC,OAAO,EAAE,KAAK,qBAAU,CAAC,uBAAuB;QAAE,OAAO,IAAI,CAAC;IAE5E,MAAM,SAAS,GAAG,SAAoC,CAAC;IAEvD,wCAAwC;IACxC,IAAI,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAEnD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,iCAAiC;QACjC,SAAS,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QACxE,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;IAChC,CAAC;IAED,iCAAiC;IACjC,MAAM,YAAY,GAAG,WAAW,CAAC,iBAAiB,CAAC,qBAAU,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAE3E,CAAC;IAEd,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IAE/B,oDAAoD;IACpD,MAAM,YAAY,GAAG,IAAI,GAAG,CAC1B,YAAY,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACrC,IAAI,CAAC;YACH,OAAO,CAAC,CAAC,mBAAmB,CAAC,qBAAU,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACvE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CACH,CAAC;IAEF,sBAAsB;IACtB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClC,8CAA8C;QAC9C,IAAI,CAAC,4BAA4B,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,SAAS;QAC9D,IAAI,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,SAAS;QAE5C,YAAY,CAAC,qBAAqB,CAAC;YACjC,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,WAAW,EAAE,qFAAqF;SACnG,CAAC,CAAC;QAEH,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,OAAO;QACL,OAAO,EAAE,EAAE,CAAC,WAAW,EAAE;QACzB,YAAY;KACb,CAAC;AACJ,CAAC"}