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

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';

package/src/generators/openapi-json/config.schema.spec.ts

@@ -0,0 +1,265 @@
+import { TypeBoxValidator } from '@rsdk/common';
+import { parse } from 'yaml';
+
+import { OpenApiConfigSchema } from './config.schema';
+
+describe('OpenAPI Config Schema', () => {
+  const validator = new TypeBoxValidator(OpenApiConfigSchema);
+
+  it('should validate minimal config', () => {
+    const config = parse(`
+      out: openapi.json
+      title: Test API
+      version: 1.0.0
+      description: Test API Description
+    `);
+
+    const { isValid, errors } = validator.check(config);
+
+    expect(isValid).toBe(true);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate minimal config', () => {
+    const config = parse(`
+      out: openapi.json
+      title: Test API
+      version: '1.0.0'
+      description: Test API Description
+    `);
+
+    const { isValid, errors } = validator.check(config);
+
+    expect(isValid).toBe(true);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate config with zones', () => {
+    const config = parse(`
+      out: openapi.json
+      title: Test API
+      version: '1.0.0'
+      description: Test API Description
+      includeZones:
+        - public
+        - api:web
+      excludeZones:
+        - __internal
+    `);
+
+    const { isValid, errors } = validator.check(config);
+
+    expect(isValid).toBe(true);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate config without optional fields', () => {
+    const config = parse(`
+      out: openapi.json
+      version: '1.0.0'
+    `);
+
+    const { isValid, errors } = validator.check(config);
+
+    expect(isValid).toBe(true);
+    expect(errors).toHaveLength(0);
+  });
+
+  describe('Security Schemes', () => {
+    it('should validate API Key auth', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          ApiKeyAuth:
+            type: apiKey
+            in: header
+            name: x-api-key
+            description: API Key Authentication
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate Bearer auth', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          BearerAuth:
+            type: http
+            scheme: bearer
+            bearerFormat: JWT
+            description: JWT Bearer Authentication
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate Basic auth', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          BasicAuth:
+            type: http
+            scheme: basic
+            description: Basic Authentication
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate OAuth2 auth', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          OAuth2Auth:
+            type: oauth2
+            flows:
+              implicit:
+                authorizationUrl: https://auth.example.com/oauth/authorize
+                scopes:
+                  read: Read access
+                  write: Write access
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      for (const error of errors) {
+        console.log(error);
+      }
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate multiple security schemes', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: '1.0.0'
+        description: Test API Description
+        security:
+          BearerAuth:
+            type: http
+            scheme: bearer
+            bearerFormat: JWT
+            description: JWT Bearer Authentication
+          
+          ApiKeyAuth:
+            type: apiKey
+            in: header
+            name: x-api-key
+            description: API Key Authentication
+          
+          OAuth2Auth:
+            type: oauth2
+            description: OAuth2 Authentication
+            flows:
+              implicit:
+                authorizationUrl: https://auth.example.com/oauth/authorize
+                scopes:
+                  read: Read access
+                  write: Write access
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should validate cookie-based auth', () => {
+      const config = parse(`
+        out: openapi/openapi.web.json
+        includeZones:
+          - api:web
+        title: Web API
+        version: '1.3'
+        description: Web API methods
+        security:
+          SessionCookie:
+            type: apiKey
+            in: cookie
+            name: sessionId
+            description: Cookie-based authentication
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+  });
+
+  describe('Validation Errors', () => {
+    it('should fail on invalid security type', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: 1.0.0
+        description: Test API Description
+        security:
+          InvalidAuth:
+            type: invalid
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(false);
+      expect(errors).toHaveLength(2);
+    });
+
+    it('should fail on missing required fields', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        description: Test API Description
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(true);
+      expect(errors).toHaveLength(0);
+    });
+
+    it('should fail on invalid OAuth2 flow configuration', () => {
+      const config = parse(`
+        out: openapi.json
+        title: Test API
+        version: 1.0.0
+        description: Test API Description
+        security:
+          - type: oauth2
+            schemaName: OAuth2Auth
+            flows:
+              implicit:
+                scopes: invalid
+      `);
+
+      const { isValid, errors } = validator.check(config);
+
+      expect(isValid).toBe(false);
+      expect(errors.length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/generators/openapi-json/config.schema.ts

@@ -0,0 +1,37 @@
+import { OpenApiOptions } from '@rsdk/http.openapi';
+import type { Static } from '@sinclair/typebox';
+import { Type } from '@sinclair/typebox';
+
+/**
+ * Configuration schema for OpenAPI document generation.
+ * @example
+ * {
+ *   "out": "openapi.json",
+ *   "app": "./dist/app.js",
+ *   "title": "My API",
+ *   "version": "1.0.0",
+ *   "description": "API Description",
+ *   "includeZones": ["public"],
+ *   "excludeZones": ["internal"],
+ *   "security": {
+ *     "jwt": {
+ *       "type": "http",
+ *       "scheme": "bearer",
+ *       "bearerFormat": "JWT",
+ *       "name": "JWT Auth"
+ *     }
+ *   }
+ * }
+ */
+export const OpenApiConfigSchema = Type.Intersect([
+  Type.Partial(OpenApiOptions),
+  Type.Object({
+    /** Output file path for the generated OpenAPI document */
+    out: Type.Optional(Type.String()),
+
+    /** Path to the application file (usually `dist/app.js`) */
+    app: Type.Optional(Type.String()),
+  }),
+]);
+
+export type OpenApiConfigSchema = Static<typeof OpenApiConfigSchema>;

package/src/generators/openapi-json/index.ts

@@ -0,0 +1,2 @@
+export * from './openapi-json.generator';
+export * from './config.schema';

package/src/generators/openapi-json/openapi-json.generator.ts

@@ -0,0 +1,53 @@
+import type { PlatformApp, PlatformContext } from '@rsdk/core';
+import { OpenApiGenerator } from '@rsdk/http.openapi';
+import { LoggerFactory } from '@rsdk/logging';
+
+import { FileGenerator } from '../file-generator.interface';
+
+import type { OpenApiConfigSchema } from './config.schema';
+
+/**
+ * Here we don't need `out` and `app`,
+ * but `title`, `version` and `description` are required.
+ */
+export type OpenApiGeneratorOptions = Omit<OpenApiConfigSchema, 'out' | 'app'> &
+  Required<Pick<OpenApiConfigSchema, 'title' | 'version' | 'description'>>;
+
+export class OpenApiFileGenerator extends FileGenerator {
+  private readonly context: PlatformContext;
+  private readonly options: Partial<OpenApiGeneratorOptions>;
+
+  constructor(
+    app: PlatformApp,
+    options: Partial<OpenApiGeneratorOptions> = {},
+  ) {
+    super(LoggerFactory.create(OpenApiFileGenerator));
+    this.context = app.context;
+    this.options = options;
+  }
+
+  protected async getContent(): Promise<string> {
+    this.logger.info('Generate openapi starting');
+
+    const options = await this.resolveOptions(this.context, this.options);
+    const generator = new OpenApiGenerator(this.context, options);
+    const document = await generator.generate();
+
+    this.logger.info('Generate openapi finished');
+    return JSON.stringify(document, null, 2);
+  }
+
+  private async resolveOptions(
+    context: PlatformContext,
+    passed: Partial<OpenApiGeneratorOptions>,
+  ): Promise<OpenApiGeneratorOptions> {
+    const appMetadata = await context.getMetadata();
+    const defaults: OpenApiGeneratorOptions = {
+      title: appMetadata.name,
+      version: appMetadata.version,
+      description: appMetadata.description,
+    };
+
+    return { ...defaults, ...passed };
+  }
+}