@rsdk/cli.cmd.autodoc 6.0.0-next.7 → 6.0.0-next.8

package/src/base/app.loader.ts

@@ -0,0 +1,39 @@
+import { Assert } from '@rsdk/common';
+import { Path } from '@rsdk/common.node';
+import { PlatformApp } from '@rsdk/core';
+import type { ILogger } from '@rsdk/logging';
+
+export class AppLoader {
+  constructor(private readonly logger: ILogger) {}
+
+  async loadApp(
+    fullpath: string,
+    required: boolean,
+  ): Promise<PlatformApp | undefined> {
+    let app: PlatformApp | undefined;
+
+    try {
+      const [absolute] = Path.absolutize(fullpath);
+      const loaded = await import(absolute);
+
+      app = loaded.app as PlatformApp;
+    } catch (error) {
+      Assert.isError(error);
+      this.logger.warn(`module by path ${fullpath} not found`);
+
+      if (!required) {
+        this.logger.info(`found --if-present, finished with exit code 0`);
+        return undefined;
+      }
+
+      this.logger.error(`Error on import ${fullpath}`, error);
+      throw error;
+    }
+
+    if (app instanceof PlatformApp) {
+      return app;
+    }
+
+    throw new Error('app is not instance of PlatformApp');
+  }
+}

package/src/base/document.file.ts

@@ -0,0 +1,33 @@
+import type { ILogger } from '@rsdk/logging';
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * TODO: Может быть удобная абстракция для работы с файлами.
+ * Ещё в старых загашниках надо NetworkFile поискать
+ */
+export type DocumentFile = {
+  name: string;
+  content: string;
+};
+
+export class DocumentWriter {
+  constructor(
+    private readonly logger: ILogger,
+    private readonly basepath: string,
+  ) {}
+
+  async write(file: DocumentFile): Promise<string> {
+    const exists = existsSync(this.basepath);
+    if (!exists) {
+      await mkdir(this.basepath, { recursive: true });
+    }
+    const fullpath = path.join(this.basepath, file.name);
+
+    this.logger.info(`writing file ${file.name}...`);
+    await writeFile(fullpath, file.content);
+    this.logger.info(`file ${file.name} created!`);
+    return fullpath;
+  }
+}

package/src/base/index.ts

@@ -0,0 +1,2 @@
+export * from './app.loader';
+export * from './document.file';

package/src/commands/autodoc.cmd.ts

@@ -0,0 +1,93 @@
+import { Command, IRunnable, Option, ValueOption } from '@rsdk/cli.common';
+import { FsPathParser, Path } from '@rsdk/common.node';
+import { ILogger, LoggerFactory } from '@rsdk/logging';
+import { API_ZONE_INTERNAL } from '@rsdk/zones';
+
+import { type DocumentFile, DocumentWriter } from '../base';
+import { AppLoader } from '../base';
+import {
+  MarkdownDocsGenerator,
+  OpenApiFileGenerator,
+  RsdkFileGenerator,
+} from '../generators';
+
+import { OpenApiCommand } from './openapi.variation';
+
+@Command('autodoc', {
+  description: 'autodoc your app',
+  variations: [OpenApiCommand],
+})
+export class AutodocCommand implements IRunnable {
+  private readonly logger: ILogger;
+  private readonly loader: AppLoader;
+
+  constructor() {
+    this.logger = LoggerFactory.create(AutodocCommand);
+    this.loader = new AppLoader(this.logger);
+  }
+
+  async run(
+    @Option('verbose', { description: 'Verbose output' })
+    verbose: boolean,
+
+    @Option('if-present', { description: 'Not fail if not provided app file' })
+    ifPresent: boolean,
+
+    @Option('open-api', {
+      description: 'generate open api (internal routes are excluded)',
+    })
+    openApi: boolean,
+
+    @ValueOption('out', new FsPathParser('dir', { check: 'dirname' }), {
+      description: 'output directory',
+      defaultValue: 'autodoc',
+      alias: 'o',
+    })
+    outPath: string,
+
+    @ValueOption('app', new FsPathParser('file'), {
+      description: 'path to app.js file',
+      defaultValue: './dist/app.js',
+      alias: 'a',
+    })
+    appPath: string,
+  ): Promise<void> {
+    if (verbose) {
+      this.logger.info(`app path: ${appPath}`);
+      this.logger.info(`output directory path: ${outPath}`);
+      this.logger.info(`--if-present: ${ifPresent}`);
+    }
+
+    const app = await this.loader.loadApp(appPath, !ifPresent);
+    if (!app) {
+      return;
+    }
+
+    const documents: DocumentFile[] = [
+      await new RsdkFileGenerator(app).createFile('rsdk.json'),
+      await new MarkdownDocsGenerator(app).createFile('autodoc.md'),
+    ];
+
+    if (openApi) {
+      const generator = new OpenApiFileGenerator(app, {
+        excludeZones: [API_ZONE_INTERNAL],
+      });
+
+      const openApiDocument = await generator.createFile('openapi.json');
+
+      if (openApiDocument) {
+        documents.push(openApiDocument);
+      }
+    }
+
+    const [absolutePath] = Path.absolutize(outPath);
+
+    const writer = new DocumentWriter(this.logger, absolutePath);
+
+    await Promise.all(
+      documents.map(async (doc) => {
+        await writer.write(doc);
+      }),
+    );
+  }
+}

package/src/commands/openapi.variation.ts

@@ -0,0 +1,172 @@
+import {
+  CommandVariation,
+  IRunnable,
+  Option,
+  ValueOption,
+} from '@rsdk/cli.common';
+import { ArrayParser, StringParser, text } from '@rsdk/common';
+import { FsPathParser, Path, readObj } from '@rsdk/common.node';
+import { ILogger, LoggerFactory } from '@rsdk/logging';
+import { Value } from '@sinclair/typebox/value';
+
+import { AppLoader } from '../base/app.loader';
+import { DocumentWriter } from '../base/document.file';
+import {
+  OpenApiConfigSchema,
+  OpenApiFileGenerator,
+  OpenApiGeneratorOptions,
+} from '../generators';
+
+interface OpenApiConfig extends Partial<OpenApiGeneratorOptions> {
+  out?: string;
+  app?: string;
+}
+
+@CommandVariation('autodoc:openapi', {
+  description: 'generate open api',
+})
+export class OpenApiCommand implements IRunnable {
+  private readonly logger: ILogger;
+  private readonly loader: AppLoader;
+
+  constructor() {
+    this.logger = LoggerFactory.create(OpenApiCommand);
+    this.loader = new AppLoader(this.logger);
+  }
+
+  async run(
+    @Option('verbose', { description: 'Verbose output', defaultValue: false })
+    verbose: boolean,
+
+    @Option('if-present', {
+      description: 'Not fail if not provided app file',
+      defaultValue: false,
+    })
+    ifPresent: boolean,
+
+    @ValueOption('out', new FsPathParser('file', { check: 'dirname' }), {
+      description: 'output file',
+      alias: 'o',
+    })
+    outPath?: string,
+
+    @ValueOption('app', new FsPathParser('file'), {
+      description: 'path to app.js file',
+      alias: 'a',
+    })
+    appPath?: string,
+
+    @ValueOption('conf', new FsPathParser('file'), {
+      description: text`
+        Path to configuration file (YAML or JSON) containing any of the command options.
+        Command line options take precedence over config file values.
+      `,
+    })
+    configPath?: string,
+
+    @ValueOption('include-zones', new ArrayParser(new StringParser()), {
+      description: text`
+        API zones to include. Only controllers with these zones will be included in the output.
+        Zones are specified as a comma-separated list.
+      `,
+    })
+    includeZones?: string[],
+
+    @ValueOption('exclude-zones', new ArrayParser(new StringParser()), {
+      description: text`
+        API zones to exclude. Only controllers without these zones will be included in the output.
+        Zones are specified as a comma-separated list.
+      `,
+    })
+    excludeZones?: string[],
+
+    @ValueOption('title', new StringParser(), {
+      description: text`
+        The title of OpenAPI document. Takes precedence over config file and app metadata.
+      `,
+    })
+    title?: string,
+
+    @ValueOption('version', new StringParser(), {
+      description: text`
+        The version of OpenAPI document. Takes precedence over config file and app metadata.
+      `,
+    })
+    version?: string,
+
+    @ValueOption('description', new StringParser(), {
+      description: text`
+        The description of OpenAPI document. Takes precedence over config file and app metadata.
+      `,
+    })
+    description?: string,
+  ): Promise<void> {
+    if (verbose) {
+      this.logger.info(`app path: ${appPath}`);
+      this.logger.info(`output file: ${outPath}`);
+      this.logger.info(`--if-present: ${ifPresent}`);
+    }
+
+    const config = await this.readConfig(configPath);
+
+    // Command line options take precedence over config file
+    const effectiveOutPath = outPath ?? config.out ?? 'openapi.json';
+    const effectiveAppPath = appPath ?? config.app ?? './dist/app.js';
+
+    if (verbose) {
+      this.logger.info(`effective out path: ${effectiveOutPath}`);
+      this.logger.info(`effective app path: ${effectiveAppPath}`);
+    }
+
+    const app = await this.loader.loadApp(effectiveAppPath, !ifPresent);
+    if (!app) {
+      return;
+    }
+
+    const [absolutePath] = Path.absolutize(effectiveOutPath);
+    const [dirname, filename] = Path.split(absolutePath);
+
+    const options: Partial<OpenApiGeneratorOptions> = {
+      ...config,
+      ...(includeZones && { includeZones }),
+      ...(excludeZones && { excludeZones }),
+      ...(title && { title }),
+      ...(description && { description }),
+      ...(version && { version }),
+    };
+
+    if (verbose) {
+      this.logger.info('override options', options);
+    }
+
+    const generator = new OpenApiFileGenerator(app, options);
+    const writer = new DocumentWriter(this.logger, dirname);
+
+    const document = await generator.createFile(filename);
+
+    await writer.write(document);
+  }
+
+  private async readConfig(
+    configPath: string | undefined,
+  ): Promise<Partial<OpenApiConfig>> {
+    if (!configPath) {
+      return {};
+    }
+
+    this.logger.info(`reading config file: ${configPath}`);
+
+    const [absolutePath] = Path.absolutize(configPath);
+    const config = await readObj(absolutePath);
+
+    if (!Value.Check(OpenApiConfigSchema, config)) {
+      const errors = [...Value.Errors(OpenApiConfigSchema, config)];
+
+      throw new Error(
+        `Invalid config file: ${configPath}\n${JSON.stringify(errors, null, 2)}`,
+      );
+    }
+
+    return config;
+  }
+}

package/src/generators/autodoc-md/autodoc-md.generator.ts

@@ -0,0 +1,56 @@
+import type { DocumentNode } from '@rsdk/autodoc.protocol';
+import { Composite } from '@rsdk/autodoc.protocol';
+import type { PlatformApp } from '@rsdk/core';
+import { LoggerFactory } from '@rsdk/logging';
+
+import { FileGenerator } from '../file-generator.interface';
+
+import type { DocumentFragment } from './fragments';
+import {
+  AdditionalSourcesFragment,
+  AppMetadataFragment,
+  AutodocMetadataFragment,
+  ConfigSectionFragment,
+  HeaderFragment,
+  PluginFragment,
+  TransportsFragment,
+} from './fragments';
+
+export class MarkdownDocsGenerator extends FileGenerator {
+  constructor(private readonly app: PlatformApp) {
+    super(LoggerFactory.create(MarkdownDocsGenerator));
+  }
+
+  protected async getContent(): Promise<string> {
+    this.logger.info('Start generating documentation');
+
+    const structure = await this.getStructure();
+
+    const nodes = await Promise.all(
+      structure.map((item) => item.getDocumentNode()),
+    );
+
+    const metadata = await this.app.getMetadata();
+    const content = await new Composite(
+      nodes.filter((node): node is DocumentNode => node !== null),
+      'Application: ' + metadata.name,
+    ).toString();
+
+    this.logger.info('Generating documentation finished');
+    return content;
+  }
+
+  private async getStructure(): Promise<DocumentFragment[]> {
+    const metadata = await this.app.getMetadata();
+
+    return [
+      new HeaderFragment(this.app),
+      new AppMetadataFragment(this.app),
+      new PluginFragment(this.app.platformAppOptions.plugins),
+      new TransportsFragment(this.app.platformAppOptions.transports),
+      new AdditionalSourcesFragment(metadata.config.sources),
+      new ConfigSectionFragment(metadata),
+      new AutodocMetadataFragment(this.app),
+    ];
+  }
+}

package/src/generators/autodoc-md/formatters.ts

@@ -0,0 +1,9 @@
+export class MdFormatter {
+  static italic(str: string): string {
+    return `*${str}*`;
+  }
+
+  static bold(str: string): string {
+    return `**${str}**`;
+  }
+}

package/src/generators/autodoc-md/fragments/document-fragment.abstract.ts

@@ -0,0 +1,6 @@
+import type { DocumentNode } from '@rsdk/autodoc.protocol';
+import type { Promisable } from 'type-fest';
+
+export abstract class DocumentFragment {
+  abstract getDocumentNode(): Promisable<DocumentNode[] | DocumentNode | null>;
+}

package/src/generators/autodoc-md/fragments/extractor/document.extractor.ts

@@ -0,0 +1,73 @@
+import type {
+  Abstract,
+  ClassProvider,
+  DynamicModule,
+  ExistingProvider,
+  FactoryProvider,
+  Type,
+  ValueProvider,
+} from '@nestjs/common';
+import type { DocumentResolver } from '@rsdk/autodoc.protocol';
+import { AutodocMetadata } from '@rsdk/autodoc.protocol';
+import { NestAssert, RsdkMetadataProvider } from '@rsdk/metadata';
+import { NestDefinitionIterator } from '@rsdk/nest-tools';
+import type { Promisable } from 'type-fest';
+
+type DocumentResolverMap = Map<string, DocumentResolver>;
+
+export class DocumentExtractor {
+  constructor(readonly module: Promisable<DynamicModule | Type>) {}
+
+  async getDocumentResolverMap(): Promise<DocumentResolverMap> {
+    return this.recursiveFillDocumentMap();
+  }
+
+  /**
+   * Рекурсивно проходит по дереву объявлений неста и добавляет все AutodocResolver в `map`
+   */
+  private async recursiveFillDocumentMap(
+    autodocResolverMap: DocumentResolverMap = new Map(),
+  ): Promise<DocumentResolverMap> {
+    const nestDefinitionIterator = new NestDefinitionIterator(this.module);
+
+    for await (const nestDef of nestDefinitionIterator.iterate()) {
+      if (!NestAssert.isObjectOrCtor(nestDef)) {
+        continue;
+      }
+      for (const value of RsdkMetadataProvider.getMetadataSource(nestDef)) {
+        if (!NestAssert.isObjectOrCtor(value)) {
+          continue;
+        }
+        this.fillDocumentMap(value, autodocResolverMap);
+      }
+    }
+
+    return autodocResolverMap;
+  }
+
+  /**
+   * Извлекает autodoc-метаданные из definition и добавляет их в map
+   */
+  private fillDocumentMap(
+    definition:
+      | DynamicModule
+      | Type<any>
+      | ClassProvider<any>
+      | ValueProvider<any>
+      | FactoryProvider<any>
+      | ExistingProvider<any>
+      | Abstract<any>
+      // eslint-disable-next-line @typescript-eslint/ban-types
+      | Function,
+    extractorMap: DocumentResolverMap,
+  ): void {
+    const resolvers = AutodocMetadata.getResolvers(definition);
+
+    if (!resolvers) {
+      return;
+    }
+    for (const resolver of resolvers) {
+      extractorMap.set(resolver.scope, resolver.resolver);
+    }
+  }
+}

package/src/generators/autodoc-md/fragments/implementations/additional-sources.fragment.ts

@@ -0,0 +1,41 @@
+import { Composite } from '@rsdk/autodoc.protocol';
+import type { SourceMetadata } from '@rsdk/core';
+
+import { DocumentFragment } from '../document-fragment.abstract';
+
+export class AdditionalSourcesFragment extends DocumentFragment {
+  constructor(private sources?: SourceMetadata[]) {
+    super();
+  }
+
+  getContent(): string {
+    if (!this.sources?.length) {
+      return '';
+    }
+    const fragments: string[] = [];
+
+    fragments.push('## Additional Sources', '\n');
+
+    for (const metadata of this.sources) {
+      fragments.push(
+        `### ${metadata.name}`,
+        `${metadata.name} ${metadata.description}`,
+      );
+    }
+    return fragments.join('\n');
+  }
+
+  getDocumentNode(): Composite | null {
+    if (!this.sources) {
+      return null;
+    }
+    const sourceNodes = this.sources.map((metadata) => {
+      return new Composite(
+        [`${metadata.name} ${metadata.description}`],
+        metadata.name,
+      );
+    });
+
+    return new Composite(sourceNodes, 'AdditionalSources');
+  }
+}

package/src/generators/autodoc-md/fragments/implementations/app-metadata.fragment.ts

@@ -0,0 +1,18 @@
+import type { DocumentNode } from '@rsdk/autodoc.protocol';
+import { Composite } from '@rsdk/autodoc.protocol';
+import type { PlatformApp } from '@rsdk/core';
+
+import type { DocumentFragment } from '../document-fragment.abstract';
+
+export class AppMetadataFragment implements DocumentFragment {
+  constructor(private readonly app: PlatformApp) {}
+
+  async getDocumentNode(): Promise<DocumentNode[] | DocumentNode | null> {
+    const metadata = await this.app.getMetadata();
+
+    if (!metadata.description) {
+      return null;
+    }
+    return new Composite(metadata.description, 'Description');
+  }
+}

package/src/generators/autodoc-md/fragments/implementations/autodoc.fragment.ts

@@ -0,0 +1,30 @@
+import type { DocumentNode } from '@rsdk/autodoc.protocol';
+import { Composite } from '@rsdk/autodoc.protocol';
+import type { PlatformApp } from '@rsdk/core';
+
+import type { DocumentFragment } from '../document-fragment.abstract';
+import { DocumentExtractor } from '../extractor/document.extractor';
+
+export class AutodocMetadataFragment implements DocumentFragment {
+  constructor(readonly app: PlatformApp) {}
+
+  async getDocumentNode(): Promise<DocumentNode> {
+    const root = this.app.context.getRoot();
+    const resolvers = await new DocumentExtractor(
+      root,
+    ).getDocumentResolverMap();
+
+    const nodes: DocumentNode[] = [];
+
+    const rsdkMetadataProvider =
+      await this.app.context.getRsdkMetadataProvider();
+
+    for (const resolver of resolvers.values()) {
+      const node = await resolver.getNode(rsdkMetadataProvider);
+
+      node && nodes.push(node);
+    }
+
+    return new Composite(nodes);
+  }
+}