@rsdk/cli.cmd.autodoc 6.0.0-next.2 → 6.0.0-next.20

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);
+  }
+}

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

@@ -0,0 +1,148 @@
+import type { DocumentNode } from '@rsdk/autodoc.protocol';
+import { Composite, Table } from '@rsdk/autodoc.protocol';
+import type {
+  PlatformAppMetadata,
+  SerializablePropertyMetadata,
+  SerializableSectionMetadata,
+} from '@rsdk/core';
+import { get, set } from 'lodash';
+
+import { MdFormatter } from '../../formatters';
+import { DocumentFragment } from '../document-fragment.abstract';
+
+/*
+ * Этот тип представляет собой древовидную структуру, где каждый ключ может
+ * быть либо массивом SerializableSectionMetadata,
+ * либо другим GroupedSectionTree, что позволяет создавать вложенные секции в конфигурации.
+ */
+type GroupedSectionTree = {
+  [key in string]: SerializableSectionMetadata[] | GroupedSectionTree;
+};
+
+export const APPLICATION_SECTION_NAME = 'Application';
+
+export class ConfigSectionFragment extends DocumentFragment {
+  constructor(private metadata: PlatformAppMetadata) {
+    super();
+  }
+
+  private static getSectionNode(
+    section: SerializableSectionMetadata,
+  ): Composite {
+    const content: (DocumentNode | string)[] = [];
+
+    if (section.description) {
+      content.push(section.description);
+    }
+
+    content.push(
+      new Table(
+        section.properties.map((property) => ({
+          Name: property.expectedInEnv
+            ? MdFormatter.bold(property.key)
+            : property.key,
+          Type: property.parser.type,
+          'Default value': `${property.defaultValue}`,
+          Description: property.description,
+        })),
+      ),
+    );
+
+    const nodeTitle = section.name
+      ? `${section.name} (${MdFormatter.italic(section.constructorName)})`
+      : section.constructorName;
+
+    return new Composite(content, nodeTitle);
+  }
+
+  private static getSectionNodeTree(
+    groupedSectionTree: GroupedSectionTree,
+  ): Composite[] {
+    const sectionNodes: Composite[] = [];
+
+    for (const [key, value] of Object.entries(groupedSectionTree)) {
+      if (Array.isArray(value)) {
+        sectionNodes.push(
+          new Composite(
+            value.map((section) =>
+              ConfigSectionFragment.getSectionNode(section),
+            ),
+            key,
+          ),
+        );
+        continue;
+      }
+      sectionNodes.push(new Composite(this.getSectionNodeTree(value), key));
+    }
+    return sectionNodes;
+  }
+
+  getDocumentNode(): Composite | null {
+    const {
+      config: { properties },
+    } = this.metadata;
+
+    const title = 'Configuration properties';
+
+    const printProperty = (meta: SerializablePropertyMetadata): Composite => {
+      const { key, defaultValue, description, parser, expectedInEnv } = meta;
+      const fragments: string[] = [];
+
+      fragments.push(
+        `- ${key} ${description}`,
+        `> Parser: **${parser.type}** ${parser.description}`,
+      );
+
+      if ('defaultValue' in meta) {
+        fragments.push(`> Default value: ${defaultValue}`);
+      }
+
+      if (expectedInEnv) {
+        fragments.push(`> Should be in environment!`);
+      }
+      fragments.push('');
+      return new Composite(fragments.join('\n'));
+    };
+
+    const sectionsNode = this.getSectionsNode();
+
+    const content = [sectionsNode];
+
+    if (properties.length > 0) {
+      const title = `Unbound properties`;
+      const propertyNodeContent: DocumentNode[] = [];
+      const propertiesNode = new Composite(propertyNodeContent, title);
+
+      for (const propMeta of properties) {
+        const propertyNode = printProperty(propMeta);
+
+        propertyNodeContent.push(propertyNode);
+      }
+      content.push(propertiesNode);
+    }
+    return new Composite(content, title);
+  }
+
+  private getSectionsNode(): Composite {
+    const groupByTags: { [key in string]: SerializableSectionMetadata[] } = {};
+
+    for (const section of this.metadata.config.sections) {
+      if (section.tags?.length) {
+        const existed = get(groupByTags, section.tags.join('.'), [section]);
+
+        set(groupByTags, section.tags.join('.'), existed);
+      } else {
+        groupByTags[APPLICATION_SECTION_NAME] ??= <
+          SerializableSectionMetadata[]
+        >[];
+
+        groupByTags[APPLICATION_SECTION_NAME].push(section);
+      }
+    }
+
+    const content: DocumentNode[] =
+      ConfigSectionFragment.getSectionNodeTree(groupByTags);
+
+    return new Composite(content, 'Sections');
+  }
+}

package/src/generators/autodoc-md/fragments/implementations/header.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 HeaderFragment implements DocumentFragment {
+  constructor(readonly app: PlatformApp) {}
+
+  async getDocumentNode(): Promise<DocumentNode[] | DocumentNode | null> {
+    const metadata = await this.app.getMetadata();
+    const appVersion = metadata.version;
+
+    const headerFragments = [`version: ${appVersion}`];
+
+    return new Composite(headerFragments);
+  }
+}

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

@@ -0,0 +1,21 @@
+import type { DocumentNode } from '@rsdk/autodoc.protocol';
+import { Composite, List } from '@rsdk/autodoc.protocol';
+import type { PlatformAppPlugin } from '@rsdk/core';
+
+import { DocumentFragment } from '../document-fragment.abstract';
+
+export class PluginFragment extends DocumentFragment {
+  constructor(private plugins?: PlatformAppPlugin[]) {
+    super();
+  }
+
+  getDocumentNode(): DocumentNode | null {
+    if (!this.plugins?.length) {
+      return null;
+    }
+    return new Composite(
+      new List(this.plugins?.map((plugin) => plugin.constructor.name)),
+      'Plugins',
+    );
+  }
+}

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

@@ -0,0 +1,36 @@
+import { Composite, List } from '@rsdk/autodoc.protocol';
+import type { ITransport } from '@rsdk/core';
+
+import { DocumentFragment } from '../document-fragment.abstract';
+
+export class TransportsFragment extends DocumentFragment {
+  constructor(private transports?: ITransport[]) {
+    super();
+  }
+
+  getContent(): string {
+    if (!this.transports?.length) {
+      return '';
+    }
+    const fragments: string[] = [];
+
+    fragments.push('## Transports', '\n');
+    for (const transport of this.transports) {
+      fragments.push('- ' + transport.getProtocol());
+    }
+    return fragments.join('\n');
+  }
+
+  getDocumentNode(): Composite | null {
+    if (!this.transports?.length) {
+      return null;
+    }
+
+    const transportNode = new Composite(
+      new List(this.transports.map((tr) => tr.getProtocol())),
+      'Transports',
+    );
+
+    return transportNode;
+  }
+}

package/src/generators/autodoc-md/fragments/index.ts

@@ -0,0 +1,9 @@
+export * from './implementations/config-section.fragment';
+export * from './implementations/app-metadata.fragment';
+export * from './implementations/config-section.fragment';
+export * from './implementations/transports.fragment';
+export * from './implementations/autodoc.fragment';
+export * from './implementations/plugin.fragment';
+export * from './implementations/additional-sources.fragment';
+export * from './implementations/header.fragment';
+export * from './document-fragment.abstract';

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

@@ -0,0 +1 @@
+export * from './autodoc-md.generator';

package/src/generators/file-generator.interface.ts

@@ -0,0 +1,22 @@
+import type { ILogger } from '@rsdk/logging';
+
+import type { DocumentFile } from '../base';
+
+export abstract class FileGenerator {
+  constructor(protected readonly logger: ILogger) {}
+
+  /**
+   * Принимает имя файла и возвращает абстракцию файла
+   * @param filename - Имя файла
+   * @returns {DocumentFile} Объект файла
+   */
+  async createFile(filename: string): Promise<DocumentFile> {
+    this.logger.info(`started generating ${filename}`);
+    const content = await this.getContent();
+
+    this.logger.info(`finished generating ${filename}`);
+    return { name: filename, content };
+  }
+
+  protected abstract getContent(): Promise<string>;
+}

package/src/generators/index.ts

@@ -0,0 +1,4 @@
+export * from './file-generator.interface';
+export * from './autodoc-md';
+export * from './openapi-json';
+export * from './rsdk-json';