nestjs-openapi-parser 0.0.1

package/dist/config/types.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineConfig = defineConfig;
+/** Helper for `nestparser.config.ts` so users get full type-checking. */
+function defineConfig(config) {
+    return config;
+}
+//# sourceMappingURL=types.js.map

package/dist/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":";;AA8JA,oCAEC;AAHD,yEAAyE;AACzE,SAAgB,YAAY,CAAC,MAAwB;IACnD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/lib.d.ts

@@ -0,0 +1,12 @@
+export { parseNestProject } from './parser';
+export type { ParseNestProjectOptions } from './parser';
+export { AstIndex, PathBuilder, SchemaBuilder } from './parser';
+export { defineConfig } from './config/types';
+export type { NestParserConfig, NestParserHooks, OpenApiConfig, ProjectConfig, ConventionsConfig, ResponseSchemaContext, SecurityContext, EndpointSummaryContext, ModelConstructor, } from './config/types';
+export { loadConfig } from './config/loader';
+export type { LoadConfigOptions, LoadedConfig } from './config/loader';
+export { validateDocument } from './validate';
+export type { ValidationResult } from './validate';
+export { filterScopedComments, getScopes, getTags, isVisible, parseScopeList } from './parser/tags';
+export type { TagBag } from './parser/tags';
+export type { OpenApiDocument, OpenApiInfo, OpenApiServer, OpenApiSchema, OpenApiSecurityScheme, OpenApiSecurityRequirement, } from './types/openapi';

package/dist/lib.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseScopeList = exports.isVisible = exports.getTags = exports.getScopes = exports.filterScopedComments = exports.validateDocument = exports.loadConfig = exports.defineConfig = exports.SchemaBuilder = exports.PathBuilder = exports.AstIndex = exports.parseNestProject = void 0;
+var parser_1 = require("./parser");
+Object.defineProperty(exports, "parseNestProject", { enumerable: true, get: function () { return parser_1.parseNestProject; } });
+var parser_2 = require("./parser");
+Object.defineProperty(exports, "AstIndex", { enumerable: true, get: function () { return parser_2.AstIndex; } });
+Object.defineProperty(exports, "PathBuilder", { enumerable: true, get: function () { return parser_2.PathBuilder; } });
+Object.defineProperty(exports, "SchemaBuilder", { enumerable: true, get: function () { return parser_2.SchemaBuilder; } });
+var types_1 = require("./config/types");
+Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return types_1.defineConfig; } });
+var loader_1 = require("./config/loader");
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return loader_1.loadConfig; } });
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "validateDocument", { enumerable: true, get: function () { return validate_1.validateDocument; } });
+var tags_1 = require("./parser/tags");
+Object.defineProperty(exports, "filterScopedComments", { enumerable: true, get: function () { return tags_1.filterScopedComments; } });
+Object.defineProperty(exports, "getScopes", { enumerable: true, get: function () { return tags_1.getScopes; } });
+Object.defineProperty(exports, "getTags", { enumerable: true, get: function () { return tags_1.getTags; } });
+Object.defineProperty(exports, "isVisible", { enumerable: true, get: function () { return tags_1.isVisible; } });
+Object.defineProperty(exports, "parseScopeList", { enumerable: true, get: function () { return tags_1.parseScopeList; } });
+//# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":";;;AAAA,mCAA4C;AAAnC,0GAAA,gBAAgB,OAAA;AAEzB,mCAAgE;AAAvD,kGAAA,QAAQ,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,uGAAA,aAAa,OAAA;AAE7C,wCAA8C;AAArC,qGAAA,YAAY,OAAA;AAarB,0CAA6C;AAApC,oGAAA,UAAU,OAAA;AAGnB,uCAA8C;AAArC,4GAAA,gBAAgB,OAAA;AAGzB,sCAAoG;AAA3F,4GAAA,oBAAoB,OAAA;AAAE,iGAAA,SAAS,OAAA;AAAE,+FAAA,OAAO,OAAA;AAAE,iGAAA,SAAS,OAAA;AAAE,sGAAA,cAAc,OAAA"}

package/dist/parser/ast-index.d.ts

@@ -0,0 +1,38 @@
+import { ClassDeclaration, ClassInstancePropertyTypes, Project, Type } from 'ts-morph';
+import type { ConventionsConfig, ProjectConfig } from '../config/types';
+export interface AstIndexOptions {
+    projectRoot: string;
+    project?: ProjectConfig;
+    conventions?: ConventionsConfig;
+}
+/**
+ * Builds and indexes the TypeScript AST of the user's source tree with ts-morph
+ * so the OpenAPI generator can resolve classes (entities/DTOs), enums and
+ * controllers purely from source code.
+ */
+export declare class AstIndex {
+    readonly project: Project;
+    private readonly classesMap;
+    private readonly enumsMap;
+    private readonly conventions;
+    constructor(options: AstIndexOptions);
+    private generateMaps;
+    getClass(name: string): ClassDeclaration | undefined;
+    hasClass(name: string): boolean;
+    hasEnum(name: string): boolean;
+    /** All classes decorated with `@Controller(...)`. */
+    getControllers(): ClassDeclaration[];
+    /**
+     * Every distinct `@Scope` value declared anywhere in the indexed source
+     * (classes, methods, properties). This is the scope *vocabulary* — used to
+     * tell genuine `<scope>…</scope>` description fragments apart from ordinary
+     * angle-bracket prose like `Array<string>` or `<id>`.
+     */
+    getDeclaredScopes(): Set<string>;
+    /** Resolve the named enum's member values (string or numeric), or undefined if unknown. */
+    getEnumValues(name: string): (string | number)[] | undefined;
+    /** Symbol name of a type (e.g. `Date`, `App`, `ProductType`), if any. */
+    static symbolName(type: Type): string | undefined;
+    isOptionalProperty(prop: ClassInstancePropertyTypes): boolean;
+    get excludeDecorator(): string;
+}

package/dist/parser/ast-index.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AstIndex = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const ts_morph_1 = require("ts-morph");
+const defaults_1 = require("../config/defaults");
+const tags_1 = require("./tags");
+/**
+ * Builds and indexes the TypeScript AST of the user's source tree with ts-morph
+ * so the OpenAPI generator can resolve classes (entities/DTOs), enums and
+ * controllers purely from source code.
+ */
+class AstIndex {
+    project;
+    classesMap = new Map();
+    enumsMap = new Map();
+    conventions;
+    constructor(options) {
+        const projectCfg = { ...defaults_1.DEFAULT_PROJECT, ...options.project };
+        this.conventions = { ...defaults_1.DEFAULT_CONVENTIONS, ...options.conventions };
+        const tsConfigFilePath = node_path_1.default.isAbsolute(projectCfg.tsConfigFilePath)
+            ? projectCfg.tsConfigFilePath
+            : node_path_1.default.resolve(options.projectRoot, projectCfg.tsConfigFilePath);
+        this.project = new ts_morph_1.Project({ tsConfigFilePath });
+        const rootDir = node_path_1.default.isAbsolute(projectCfg.rootDir)
+            ? projectCfg.rootDir
+            : node_path_1.default.resolve(options.projectRoot, projectCfg.rootDir);
+        this.generateMaps(rootDir, projectCfg.excludeSuffixes);
+    }
+    generateMaps(folder, excludeSuffixes) {
+        if (!node_fs_1.default.existsSync(folder))
+            return;
+        // Sort entries by name so the traversal order — and therefore the order of
+        // paths, schemas and tags in the output — is identical across filesystems
+        // and platforms. `fs.readdirSync` order is not guaranteed (arbitrary on
+        // ext4/xfs), and `localeCompare` would reintroduce locale-dependent
+        // ordering, so compare raw strings by UTF-16 code unit.
+        const entries = node_fs_1.default
+            .readdirSync(folder, { withFileTypes: true })
+            .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const full = node_path_1.default.join(folder, entry.name);
+            if (entry.isDirectory()) {
+                this.generateMaps(full, excludeSuffixes);
+                continue;
+            }
+            if (!entry.name.endsWith('.ts'))
+                continue;
+            if (excludeSuffixes.some((suffix) => entry.name.endsWith(suffix)))
+                continue;
+            const sourceFile = this.project.getSourceFile(full);
+            if (!sourceFile)
+                continue;
+            for (const clazz of sourceFile.getClasses()) {
+                const name = clazz.getName();
+                if (name)
+                    this.classesMap.set(name, clazz);
+            }
+            for (const e of sourceFile.getEnums()) {
+                this.enumsMap.set(e.getName(), e);
+            }
+        }
+    }
+    getClass(name) {
+        return this.classesMap.get(name);
+    }
+    hasClass(name) {
+        return this.classesMap.has(name);
+    }
+    hasEnum(name) {
+        return this.enumsMap.has(name);
+    }
+    /** All classes decorated with `@Controller(...)`. */
+    getControllers() {
+        return [...this.classesMap.values()].filter((c) => !!c.getDecorator('Controller'));
+    }
+    /**
+     * Every distinct `@Scope` value declared anywhere in the indexed source
+     * (classes, methods, properties). This is the scope *vocabulary* — used to
+     * tell genuine `<scope>…</scope>` description fragments apart from ordinary
+     * angle-bracket prose like `Array<string>` or `<id>`.
+     */
+    getDeclaredScopes() {
+        const scopes = new Set();
+        for (const clazz of this.classesMap.values()) {
+            for (const s of (0, tags_1.getScopes)((0, tags_1.getTags)(clazz)))
+                scopes.add(s);
+            for (const method of clazz.getInstanceMethods()) {
+                for (const s of (0, tags_1.getScopes)((0, tags_1.getTags)(method)))
+                    scopes.add(s);
+            }
+            for (const prop of clazz.getInstanceProperties()) {
+                for (const s of (0, tags_1.getScopes)((0, tags_1.getTags)(prop)))
+                    scopes.add(s);
+            }
+        }
+        return scopes;
+    }
+    /** Resolve the named enum's member values (string or numeric), or undefined if unknown. */
+    getEnumValues(name) {
+        const e = this.enumsMap.get(name);
+        if (!e)
+            return undefined;
+        return e.getMembers().map((m) => m.getValue());
+    }
+    /** Symbol name of a type (e.g. `Date`, `App`, `ProductType`), if any. */
+    static symbolName(type) {
+        return type.getSymbol()?.getName() ?? type.getAliasSymbol()?.getName();
+    }
+    isOptionalProperty(prop) {
+        if (!ts_morph_1.Node.isPropertyDeclaration(prop))
+            return false;
+        return prop.hasQuestionToken() || !!prop.getDecorator(this.conventions.optionalDecorator);
+    }
+    get excludeDecorator() {
+        return this.conventions.excludeDecorator;
+    }
+}
+exports.AstIndex = AstIndex;
+//# sourceMappingURL=ast-index.js.map

package/dist/parser/ast-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-index.js","sourceRoot":"","sources":["../../src/parser/ast-index.ts"],"names":[],"mappings":"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"}

package/dist/parser/index.d.ts

@@ -0,0 +1,20 @@
+import type { NestParserConfig } from '../config/types';
+import type { OpenApiDocument } from '../types/openapi';
+import { AstIndex } from './ast-index';
+import { PathBuilder } from './path-builder';
+import { SchemaBuilder } from './schema-builder';
+export { AstIndex, PathBuilder, SchemaBuilder };
+export interface ParseNestProjectOptions {
+    projectRoot: string;
+    config: NestParserConfig;
+}
+/**
+ * Build an OpenAPI 3.0.3 document from a NestJS project's TypeScript source.
+ * Pure static analysis — no app boot, no decorator reflection.
+ *
+ * The produced document is validated against the OpenAPI 3.x schema before it is
+ * returned; an invalid document throws (it indicates a parser/config bug rather
+ * than something the caller should silently ship). This is why the function is
+ * async — schema validation runs through `@seriousme/openapi-schema-validator`.
+ */
+export declare function parseNestProject(options: ParseNestProjectOptions): Promise<OpenApiDocument>;

package/dist/parser/index.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaBuilder = exports.PathBuilder = exports.AstIndex = void 0;
+exports.parseNestProject = parseNestProject;
+const validate_1 = require("../validate");
+const ast_index_1 = require("./ast-index");
+Object.defineProperty(exports, "AstIndex", { enumerable: true, get: function () { return ast_index_1.AstIndex; } });
+const path_builder_1 = require("./path-builder");
+Object.defineProperty(exports, "PathBuilder", { enumerable: true, get: function () { return path_builder_1.PathBuilder; } });
+const schema_builder_1 = require("./schema-builder");
+Object.defineProperty(exports, "SchemaBuilder", { enumerable: true, get: function () { return schema_builder_1.SchemaBuilder; } });
+const tags_1 = require("./tags");
+/**
+ * Build an OpenAPI 3.0.3 document from a NestJS project's TypeScript source.
+ * Pure static analysis — no app boot, no decorator reflection.
+ *
+ * The produced document is validated against the OpenAPI 3.x schema before it is
+ * returned; an invalid document throws (it indicates a parser/config bug rather
+ * than something the caller should silently ship). This is why the function is
+ * async — schema validation runs through `@seriousme/openapi-schema-validator`.
+ */
+async function parseNestProject(options) {
+    const { projectRoot, config } = options;
+    const index = new ast_index_1.AstIndex({
+        projectRoot,
+        project: config.project,
+        conventions: config.conventions,
+    });
+    const activeScopes = new Set(config.scopes ?? []);
+    // Scope vocabulary: every `@Scope` declared in the source plus the active
+    // scopes. Only these names are treated as `<scope>…</scope>` description
+    // fragments — ordinary angle-bracket prose passes through untouched.
+    const knownScopes = new Set([...index.getDeclaredScopes(), ...activeScopes]);
+    const schemaBuilder = new schema_builder_1.SchemaBuilder(index, { activeScopes, knownScopes });
+    for (const klass of config.additionalModels ?? []) {
+        const name = klass.name;
+        const astClass = index.getClass(name);
+        if (!astClass) {
+            throw new Error(`additionalModels: class "${name}" was not found in the project source tree. ` +
+                `Make sure it is defined in a .ts file under the configured rootDir.`);
+        }
+        const classScopes = (0, tags_1.getScopes)((0, tags_1.getTags)(astClass));
+        if (!(0, tags_1.isVisible)(classScopes, activeScopes)) {
+            throw new Error(`additionalModels: class "${name}" has @Scope ${formatScopes(classScopes)} ` +
+                `which doesn't match the active scopes ${formatScopes(activeScopes)}. ` +
+                `Remove it from additionalModels or add a matching scope.`);
+        }
+        schemaBuilder.registerRef(name);
+    }
+    const registeredSchemes = Object.keys(config.openapi.securitySchemes ?? {});
+    const pathBuilder = new path_builder_1.PathBuilder(index, schemaBuilder, {
+        globalPrefix: config.project?.globalPrefix,
+        hooks: config.hooks,
+        registeredSchemes,
+        activeScopes,
+        knownScopes,
+    });
+    const paths = pathBuilder.build();
+    const tags = pathBuilder.getTags();
+    // Flush the schema worklist — paths may have registered extra refs.
+    schemaBuilder.build();
+    const document = {
+        openapi: '3.0.3',
+        info: {
+            title: config.openapi.title,
+            version: config.openapi.version,
+            ...(config.openapi.description ? { description: config.openapi.description } : {}),
+            ...config.openapi.info,
+        },
+        paths,
+        components: {
+            schemas: schemaBuilder.getSchemas(),
+            ...(config.openapi.securitySchemes
+                ? { securitySchemes: config.openapi.securitySchemes }
+                : {}),
+        },
+    };
+    if (config.openapi.servers && config.openapi.servers.length > 0) {
+        document.servers = config.openapi.servers;
+    }
+    if (tags.length > 0) {
+        document.tags = tags;
+    }
+    const { valid, errors } = await (0, validate_1.validateDocument)(document);
+    if (!valid) {
+        throw new Error(`Generated OpenAPI document failed schema validation:\n${errors
+            .map((e) => `  - ${e}`)
+            .join('\n')}`);
+    }
+    return document;
+}
+function formatScopes(scopes) {
+    return scopes.size === 0 ? '{}' : `{${[...scopes].join(', ')}}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/parser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/parser/index.ts"],"names":[],"mappings":"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"}

package/dist/parser/path-builder.d.ts

@@ -0,0 +1,87 @@
+import type { NestParserHooks } from '../config/types';
+import { AstIndex } from './ast-index';
+import { SchemaBuilder } from './schema-builder';
+export interface PathBuilderOptions {
+    globalPrefix?: string;
+    hooks?: NestParserHooks;
+    registeredSchemes?: string[];
+    activeScopes?: Set<string>;
+    /** Scope vocabulary used to recognize `<scope>…</scope>` description fragments. */
+    knownScopes?: Set<string>;
+}
+/**
+ * Converts NestJS controllers into the OpenAPI `paths` object by static analysis:
+ * `@Controller` + HTTP route decorators, `@Param/@Query/@Body/@Headers`, method
+ * return types, and pluggable hooks for response envelope and security.
+ */
+export declare class PathBuilder {
+    private readonly index;
+    private readonly schemaBuilder;
+    private readonly paths;
+    private readonly usedOperationIds;
+    private readonly tags;
+    /** Distinct method-level `@Tag` names seen, declared in root after controllers. */
+    private readonly methodTagNames;
+    private readonly globalPrefix;
+    private readonly hooks;
+    private readonly registeredSchemes;
+    private readonly activeScopes;
+    private readonly knownScopes;
+    constructor(index: AstIndex, schemaBuilder: SchemaBuilder, options?: PathBuilderOptions);
+    build(): Record<string, Record<string, unknown>>;
+    /**
+     * Root `tags[]` entries: one per distinct tag name in play. Controller tags
+     * (name from `@Tag`/the default-tag hook, description from the class JSDoc;
+     * first controller wins on a shared name) come first, then any method-level
+     * `@Tag` name a controller didn't already declare — description-less, since a
+     * method's JSDoc is its operation description, not a tag description.
+     */
+    getTags(): {
+        name: string;
+        description?: string;
+    }[];
+    private processController;
+    private buildOperation;
+    /**
+     * The operation `summary`: a method-level `@Name` JSDoc tag (highest priority),
+     * else the `endpointSummary` hook when it returns a value, else the default —
+     * the method name humanized.
+     */
+    private resolveSummary;
+    private buildQueryParameters;
+    private buildRequestBody;
+    private buildResponses;
+    /**
+     * The success status code for an operation: an explicit `@HttpCode(...)` when
+     * present — either a numeric literal (`@HttpCode(204)`) or an `HttpStatus`
+     * member (`@HttpCode(HttpStatus.NO_CONTENT)`) — otherwise NestJS's default:
+     * 201 for POST, 200 for every other verb.
+     */
+    private responseStatus;
+    private computeResponseSchema;
+    private buildSecurity;
+    private paramSchema;
+    private stringArg;
+    /**
+     * Read a decorator argument that may be a string literal or an array of string
+     * literals (`@Get('a')` or `@Get(['a', 'b'])`), returning the distinct values.
+     * Non-string and dynamic entries are skipped; the result is empty when absent.
+     */
+    private stringArgs;
+    private defaultTag;
+    private uniqueOperationId;
+    private joinPath;
+    /**
+     * Turn a raw NestJS route (with `:params`) into the OpenAPI path(s) it maps to.
+     *
+     *  - An optional param (`:id?`) expands into the with/without pair, because
+     *    OpenAPI path params are always required (`a/:id?` → `/a` and `/a/{id}`).
+     *  - Constructs OpenAPI can't represent — inline regex (`:id(\d+)`), wildcards
+     *    (`*`, `:splat*`), `+`/`*` modifiers, and more than one optional param —
+     *    cause the route to be skipped with a warning.
+     */
+    private expandRoutePaths;
+    private toOpenApiPath;
+    /** Names of the `{param}` placeholders in an OpenAPI path, in order, deduped. */
+    private pathParamNames;
+}