vovk-cli 0.0.1-beta.0

package/src/server/ensureMetadataFiles.ts

@@ -0,0 +1,92 @@
+import fs from 'fs/promises';
+import path from 'path';
+import debounce from 'lodash/debounce';
+import writeOneMetadataFile, { ROOT_SEGMENT_SCHEMA_NAME } from './writeOneMetadataFile';
+import { ProjectInfo } from '../getProjectInfo';
+
+export default async function ensureMetadataFiles(
+  metadataOutFullPath: string,
+  segmentNames: string[],
+  projectInfo: ProjectInfo | null
+): Promise<void> {
+  const now = Date.now();
+  let hasChanged = false;
+  // Create index.js file
+  const indexContent = segmentNames
+    .map((segmentName) => {
+      return `module.exports['${segmentName}'] = require('./${segmentName || ROOT_SEGMENT_SCHEMA_NAME}.json');`;
+    })
+    .join('\n');
+
+  const dTsContent = `import type { VovkMetadata } from 'vovk';
+declare const segmentMetadata: Record<string, VovkMetadata>;
+export default segmentMetadata;`;
+
+  await fs.mkdir(metadataOutFullPath, { recursive: true });
+  await fs.writeFile(path.join(metadataOutFullPath, 'index.js'), indexContent);
+  await fs.writeFile(path.join(metadataOutFullPath, 'index.d.ts'), dTsContent);
+
+  // Create JSON files (if not exist) with name [segmentName].json (where segmentName can include /, which means the folder structure can be nested) : {} (empty object)
+  await Promise.all(
+    segmentNames.map(async (segmentName) => {
+      const { isCreated } = await writeOneMetadataFile({
+        metadataOutFullPath,
+        metadata: {
+          emitMetadata: false,
+          segmentName,
+          controllers: {},
+          workers: {},
+        },
+        skipIfExists: true,
+      });
+
+      if (isCreated) {
+        projectInfo?.log.debug(`Created empty metadata file for segment "${segmentName}"`);
+        hasChanged = true;
+      }
+    })
+  );
+
+  // Recursive function to delete unnecessary JSON files and folders
+  async function deleteUnnecessaryJsonFiles(dirPath: string): Promise<void> {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+    await Promise.all(
+      entries.map(async (entry) => {
+        const fullPath = path.join(dirPath, entry.name);
+
+        if (entry.isDirectory()) {
+          // Recursively delete unnecessary files and folders within nested directories
+          await deleteUnnecessaryJsonFiles(fullPath);
+
+          // Check if the directory is empty after deletion and remove it if so
+          const remainingEntries = await fs.readdir(fullPath);
+          if (remainingEntries.length === 0) {
+            await fs.rmdir(fullPath);
+            projectInfo?.log.debug(`Deleted unnecessary metadata directory "${fullPath}"`);
+            hasChanged = true;
+          }
+        } else if (entry.isFile() && entry.name.endsWith('.json')) {
+          const relativePath = path.relative(metadataOutFullPath, fullPath);
+          const segmentName = relativePath.replace(/\\/g, '/').slice(0, -5); // Remove '.json' extension
+
+          if (
+            !segmentNames.includes(segmentName) &&
+            !segmentNames.includes(segmentName.replace(ROOT_SEGMENT_SCHEMA_NAME, ''))
+          ) {
+            await fs.unlink(fullPath);
+            projectInfo?.log.debug(`Deleted unnecessary metadata file for segment "${segmentName}"`);
+            hasChanged = true;
+          }
+        }
+      })
+    );
+  }
+
+  // Start the recursive deletion from the root directory
+  await deleteUnnecessaryJsonFiles(metadataOutFullPath);
+
+  if (hasChanged) projectInfo?.log.info(`Metadata files updated in ${Date.now() - now}ms`);
+}
+
+export const debouncedEnsureMetadataFiles = debounce(ensureMetadataFiles, 1000);

package/src/server/generateClient.ts

@@ -0,0 +1,108 @@
+import path from 'path';
+import fs from 'fs/promises';
+import type { ProjectInfo } from '../getProjectInfo';
+import type { Segment } from '../locateSegments';
+import { VovkMetadata } from 'vovk';
+
+export default async function generateClient(
+  projectInfo: ProjectInfo,
+  segments: Segment[],
+  segmentsMetadata: Record<string, VovkMetadata>
+) {
+  const now = Date.now();
+  const outDir = projectInfo.clientOutFullPath;
+  const validatePath = projectInfo.config.validateOnClient?.startsWith('.')
+    ? path.join(projectInfo.cwd, projectInfo.config.validateOnClient)
+    : projectInfo.config.validateOnClient;
+  let dts = `// auto-generated
+/* eslint-disable */
+import type { clientizeController } from 'vovk/client';
+import type { promisifyWorker } from 'vovk/worker';
+import type { VovkClientFetcher } from 'vovk/client';
+import type fetcher from '${projectInfo.fetcherClientImportPath}';
+
+`;
+  let js = `// auto-generated
+/* eslint-disable */
+const { clientizeController } = require('vovk/client');
+const { promisifyWorker } = require('vovk/worker');
+const { default: fetcher } = require('${projectInfo.fetcherClientImportPath}');
+const metadata = require('${projectInfo.metadataOutImportPath}');
+`;
+  let ts = `// auto-generated
+/* eslint-disable */
+import { clientizeController } from 'vovk/client';
+import { promisifyWorker } from 'vovk/worker';
+import type { VovkClientFetcher } from 'vovk/client';
+import fetcher from '${projectInfo.fetcherClientImportPath}';
+import metadata from '${projectInfo.metadataOutImportPath}';
+
+`;
+  for (let i = 0; i < segments.length; i++) {
+    const { routeFilePath, segmentName } = segments[i];
+    const metadata = segmentsMetadata[segmentName];
+    if (!metadata) {
+      throw new Error(`Unable to generate client. No metadata found for segment ${segmentName}`);
+    }
+    if (!metadata.emitMetadata) continue;
+    const importRouteFilePath = path.relative(projectInfo.config.clientOutDir, routeFilePath);
+
+    dts += `import type { Controllers as Controllers${i}, Workers as Workers${i} } from "${importRouteFilePath}";\n`;
+    ts += `import type { Controllers as Controllers${i}, Workers as Workers${i} } from "${importRouteFilePath}";\n`;
+  }
+
+  dts += `
+type Options = typeof fetcher extends VovkClientFetcher<infer U> ? U : never;
+  `;
+  ts += `
+${validatePath ? `import validateOnClient from '${validatePath}';\n` : '\nconst validateOnClient = undefined;'}
+type Options = typeof fetcher extends VovkClientFetcher<infer U> ? U : never;
+const prefix = '${projectInfo.apiPrefix}';
+  `;
+  js += `
+const { default: validateOnClient = null } = ${validatePath ? `require('${validatePath}')` : '{}'};
+const prefix = '${projectInfo.apiPrefix}';
+`;
+
+  for (let i = 0; i < segments.length; i++) {
+    const { segmentName } = segments[i];
+    const metadata = segmentsMetadata[segmentName];
+    if (!metadata) {
+      throw new Error(`Unable to generate client. No metadata found for segment ${segmentName}`);
+    }
+    if (!metadata.emitMetadata) continue;
+
+    for (const key of Object.keys(metadata.controllers)) {
+      dts += `export const ${key}: ReturnType<typeof clientizeController<Controllers${i}["${key}"], Options>>;\n`;
+      js += `exports.${key} = clientizeController(metadata['${segmentName}'].controllers.${key}, '${segmentName}', { fetcher, validateOnClient, defaultOptions: { prefix } });\n`;
+      ts += `export const ${key} = clientizeController<Controllers${i}["${key}"], Options>(metadata['${segmentName}'].controllers.${key}, '${segmentName}', { fetcher, validateOnClient, defaultOptions: { prefix } });\n`;
+    }
+
+    for (const key of Object.keys(metadata.workers)) {
+      dts += `export const ${key}: ReturnType<typeof promisifyWorker<Workers${i}["${key}"]>>;\n`;
+      js += `exports.${key} = promisifyWorker(null, metadata['${segmentName}'].workers.${key});\n`;
+      ts += `export const ${key} = promisifyWorker<Workers${i}["${key}"]>(null, metadata['${segmentName}'].workers.${key});\n`;
+    }
+  }
+
+  const localJsPath = path.join(outDir, 'client.js');
+  const localDtsPath = path.join(outDir, 'client.d.ts');
+  const localTsPath = path.join(outDir, 'index.ts');
+  const existingJs = await fs.readFile(localJsPath, 'utf-8').catch(() => '');
+  const existingDts = await fs.readFile(localDtsPath, 'utf-8').catch(() => '');
+  const existingTs = await fs.readFile(localTsPath, 'utf-8').catch(() => '');
+
+  if (existingJs === js && existingDts === dts && existingTs === ts) {
+    projectInfo.log.info(`Client is up to date and doesn't need to be regenerated (${Date.now() - now}ms).`);
+    return { written: false, path: outDir };
+  }
+
+  await fs.mkdir(outDir, { recursive: true });
+  await fs.writeFile(localJsPath, js);
+  await fs.writeFile(localDtsPath, dts);
+  await fs.writeFile(localTsPath, ts);
+
+  projectInfo.log.info(`Client generated in ${Date.now() - now}ms`);
+
+  return { written: true, path: outDir };
+}

package/src/server/index.ts

@@ -0,0 +1,306 @@
+import * as chokidar from 'chokidar';
+import * as http from 'http';
+import fs from 'fs/promises';
+import getProjectInfo, { ProjectInfo } from '../getProjectInfo';
+import path from 'path';
+import { debouncedEnsureMetadataFiles } from './ensureMetadataFiles';
+import createMetadataServer from './createMetadataServer';
+import writeOneMetadataFile from './writeOneMetadataFile';
+import logDiffResult from './logDiffResult';
+import generateClient from './generateClient';
+import locateSegments, { type Segment } from '../locateSegments';
+import debounceWithArgs from '../utils/debounceWithArgs';
+import { debounce, isEmpty } from 'lodash';
+import { VovkEnv } from '../types';
+import { VovkMetadata } from 'vovk';
+
+export class VovkCLIServer {
+  #projectInfo: ProjectInfo;
+
+  #segments: Segment[] = [];
+
+  #metadata: Record<string, VovkMetadata> = {};
+
+  #isWatching = false;
+
+  #modulesWatcher: chokidar.FSWatcher | null = null;
+
+  #segmentWatcher: chokidar.FSWatcher | null = null;
+
+  #watchSegments = () => {
+    const segmentReg = /\/?\[\[\.\.\.[a-zA-Z-_]+\]\]\/route.ts$/;
+    const { apiDir, log, metadataOutFullPath } = this.#projectInfo;
+    const getSegmentName = (filePath: string) => path.relative(apiDir, filePath).replace(segmentReg, '');
+    log.debug(`Watching segments in ${apiDir}`);
+    this.#segmentWatcher = chokidar
+      .watch(apiDir, {
+        persistent: true,
+        ignoreInitial: true,
+      })
+      .on('add', (filePath) => {
+        log.debug(`File ${filePath} has been added to segments folder`);
+        if (segmentReg.test(filePath)) {
+          const segmentName = getSegmentName(filePath);
+
+          this.#segments = this.#segments.find((s) => s.segmentName === segmentName)
+            ? this.#segments
+            : [...this.#segments, { routeFilePath: filePath, segmentName }];
+          log.info(`Segment "${segmentName}" has been added`);
+          log.debug(`Full list of segments: ${this.#segments.map((s) => s.segmentName).join(', ')}`);
+
+          void debouncedEnsureMetadataFiles(
+            metadataOutFullPath,
+            this.#segments.map((s) => s.segmentName),
+            this.#projectInfo // TODO refactor
+          );
+        }
+      })
+      .on('change', (filePath) => {
+        log.debug(`File ${filePath} has been changed at segments folder`);
+        if (segmentReg.test(filePath)) {
+          void this.#ping(getSegmentName(filePath));
+        }
+      })
+      // eslint-disable-next-line @typescript-eslint/no-misused-promises
+      .on('addDir', async (dirPath) => {
+        log.debug(`Directory ${dirPath} has been added to segments folder`);
+        this.#segments = await locateSegments(this.#projectInfo.apiDir);
+        for (const { segmentName } of this.#segments) {
+          void this.#ping(segmentName);
+        }
+      })
+      // eslint-disable-next-line @typescript-eslint/no-misused-promises
+      .on('unlinkDir', async (dirPath) => {
+        log.debug(`Directory ${dirPath} has been removed from segments folder`);
+        this.#segments = await locateSegments(this.#projectInfo.apiDir);
+        for (const { segmentName } of this.#segments) {
+          void this.#ping(segmentName);
+        }
+      })
+      .on('unlink', (filePath) => {
+        log.debug(`File ${filePath} has been removed from segments folder`);
+        if (segmentReg.test(filePath)) {
+          const segmentName = getSegmentName(filePath);
+          this.#segments = this.#segments.filter((s) => s.segmentName !== segmentName);
+          log.info(`Segment "${segmentName}" has been removed`);
+          log.debug(`Full list of segments: ${this.#segments.map((s) => s.segmentName).join(', ')}`);
+
+          void debouncedEnsureMetadataFiles(
+            metadataOutFullPath,
+            this.#segments.map((s) => s.segmentName),
+            this.#projectInfo // TODO refactor
+          );
+        }
+      })
+      .on('ready', () => {
+        log.debug('Segments watcher is ready');
+      })
+      .on('error', (error) => {
+        log.error(`Error watching segments folder: ${error.message}`);
+      });
+  };
+
+  #watchModules = () => {
+    const { config, log } = this.#projectInfo;
+    log.debug(`Watching modules in ${config.modulesDir}`);
+    this.#modulesWatcher = chokidar
+      .watch(config.modulesDir, {
+        persistent: true,
+        ignoreInitial: true,
+      })
+      .on('add', (filePath) => {
+        log.debug(`File ${filePath} has been added to modules folder`);
+        void this.#processControllerChange(filePath);
+      })
+      .on('change', (filePath) => {
+        log.debug(`File ${filePath} has been changed at modules folder`);
+        void this.#processControllerChange(filePath);
+      })
+      .on('unlink', (filePath) => {
+        log.debug(`File ${filePath} has been removed from modules folder`);
+      })
+      .on('addDir', () => {
+        for (const { segmentName } of this.#segments) {
+          void this.#ping(segmentName);
+        }
+      })
+      .on('unlinkDir', () => {
+        for (const { segmentName } of this.#segments) {
+          void this.#ping(segmentName);
+        }
+      })
+      .on('ready', () => {
+        log.debug('Modules watcher is ready');
+      })
+      .on('error', (error) => {
+        log.error(`Error watching modules folder: ${error.message}`);
+      });
+  };
+
+  #watchConfig = () => {
+    const { log } = this.#projectInfo;
+    log.debug(`Watching config files`);
+    let isInitial = true;
+    const handle = debounce(async () => {
+      this.#projectInfo = await getProjectInfo();
+      if (!isInitial) {
+        log.info('Config file has been updated');
+
+        isInitial = false;
+      }
+      await this.#modulesWatcher?.close();
+      await this.#segmentWatcher?.close();
+      this.#watchModules();
+      this.#watchSegments();
+    }, 1000);
+
+    chokidar
+      .watch('vovk.config.{js,mjs,cjs}', {
+        persistent: true,
+        cwd: process.cwd(),
+        ignoreInitial: false,
+        depth: 0,
+      })
+      .on('add', () => void handle())
+      .on('change', () => void handle())
+      .on('unlink', () => void handle())
+      .on('ready', () => {
+        log.debug('Config files watcher is ready');
+      })
+      .on('error', (error) => {
+        log.error(`Error watching config files: ${error.message}`);
+      });
+  };
+
+  #watch() {
+    if (this.#isWatching) throw new Error('Already watching');
+    const { apiDir, log, config } = this.#projectInfo;
+
+    log.info(
+      `Watching segments in ${apiDir} and modules in ${config.modulesDir}. Detected initial segments: ${JSON.stringify(this.#segments.map((s) => s.segmentName))}.`
+    );
+
+    this.#watchSegments();
+    this.#watchModules();
+    this.#watchConfig();
+  }
+
+  #processControllerChange = async (filePath: string) => {
+    const { log } = this.#projectInfo;
+    const code = await fs.readFile(filePath, 'utf-8').catch(() => null);
+    if (typeof code !== 'string') return;
+    const nameOfClasReg = /\bclass\s+([A-Za-z_]\w*)(?:\s*<[^>]*>)?\s*\{/g;
+    const namesOfClasses = [...code.matchAll(nameOfClasReg)].map((match) => match[1]);
+
+    const importRegex =
+      /import\s*{[^}]*\b(initVovk|get|post|put|del|head|options|worker)\b[^}]*}\s*from\s*['"]vovk['"]/;
+    if (importRegex.test(code) && namesOfClasses.length) {
+      const affectedSegments = this.#segments.filter((s) => {
+        const metadata = this.#metadata[s.segmentName];
+        if (!metadata) return false;
+        return namesOfClasses.some((name) => metadata.controllers[name] || metadata.workers[name]);
+      });
+
+      if (affectedSegments.length) {
+        log.debug(
+          `A file with controller or worker ${namesOfClasses.join(', ')} have been modified at path "${filePath}". Segment(s) affected: ${affectedSegments.map((s) => s.segmentName).join(', ')}`
+        );
+
+        for (const segment of affectedSegments) {
+          await this.#ping(segment.segmentName);
+        }
+      }
+    }
+  };
+
+  #ping = debounceWithArgs((segmentName: string) => {
+    const { apiEntryPoint, log } = this.#projectInfo;
+    const endpoint = `${apiEntryPoint}/${segmentName ? `${segmentName}/` : ''}_vovk-ping_`;
+
+    log.debug(`Pinging segment "${segmentName}" at ${endpoint}`);
+    const req = http.get(endpoint, (resp) => {
+      if (resp.statusCode !== 200) {
+        log.warn(`Ping to segment "${segmentName}" failed with status code ${resp.statusCode}. Expected 200.`);
+      }
+    });
+
+    req.on('error', (err) => {
+      log.error(`Error during HTTP request made to ${endpoint}: ${err.message}`);
+    });
+  }, 500);
+
+  #createMetadataServer() {
+    const { metadataOutFullPath, log } = this.#projectInfo;
+    return createMetadataServer(
+      async ({ metadata }) => {
+        const segment = this.#segments.find((s) => s.segmentName === metadata.segmentName);
+
+        if (!segment) {
+          log.debug(`Segment "${metadata.segmentName}" not found`);
+          return;
+        }
+
+        this.#metadata[metadata.segmentName] = metadata;
+        if (metadata.emitMetadata) {
+          const now = Date.now();
+          const { diffResult } = await writeOneMetadataFile({
+            metadataOutFullPath,
+            metadata,
+            skipIfExists: false,
+          });
+
+          const timeTook = Date.now() - now;
+
+          if (diffResult) {
+            logDiffResult(segment.segmentName, diffResult, this.#projectInfo);
+            log.info(`Metadata for segment "${metadata.segmentName}" has been updated in ${timeTook}ms`);
+          }
+        } else if (metadata && (!isEmpty(metadata.controllers) || !isEmpty(metadata.workers))) {
+          log.error(`Non-empty metadata provided for segment "${metadata.segmentName}" but emitMetadata is false`);
+        }
+
+        if (this.#segments.every((s) => this.#metadata[s.segmentName])) {
+          log.debug(`All segments with emitMetadata=true have metadata.`);
+          await generateClient(this.#projectInfo, this.#segments, this.#metadata);
+        }
+      },
+      (error) => {
+        log.error(String(error));
+      }
+    );
+  }
+
+  async startServer({ clientOutDir }: { clientOutDir?: string } = {}) {
+    this.#projectInfo = await getProjectInfo({ clientOutDir });
+    this.#segments = await locateSegments(this.#projectInfo.apiDir);
+    const { vovkPort, log, metadataOutFullPath } = this.#projectInfo;
+    const server = this.#createMetadataServer();
+
+    if (!vovkPort) {
+      log.error('No port provided for Vovk Server. Exiting...');
+      return;
+    }
+
+    await debouncedEnsureMetadataFiles(
+      metadataOutFullPath,
+      this.#segments.map((s) => s.segmentName),
+      this.#projectInfo
+    );
+
+    server.listen(vovkPort, () => {
+      log.info(`Vovk Metadata Server is running on port ${vovkPort}. Happy coding!`);
+    });
+
+    // Ping every segment in 3 seconds in order to update metadata and start watching
+    setTimeout(() => {
+      for (const { segmentName } of this.#segments) {
+        void this.#ping(segmentName);
+      }
+      this.#watch();
+    }, 3000);
+  }
+}
+const env = process.env as VovkEnv;
+if (env.__VOVK_START_SERVER_IN_STANDALONE_MODE__ === 'true') {
+  void new VovkCLIServer().startServer();
+}

package/src/server/isMetadataEmpty.ts

@@ -0,0 +1,6 @@
+import { isEmpty } from 'lodash';
+import type { VovkMetadata } from 'vovk';
+
+export default function isMetadataEmpty(metadata: VovkMetadata): boolean {
+  return isEmpty(metadata.controllers) && isEmpty(metadata.workers);
+}

package/src/server/logDiffResult.ts

@@ -0,0 +1,114 @@
+import chalk from 'chalk';
+import { ProjectInfo } from '../getProjectInfo';
+import { DiffResult } from './diffMetadata';
+
+export default function logDiffResult(segmentName: string, diffResult: DiffResult, projectInfo: ProjectInfo) {
+  const diffNormalized: {
+    what: 'worker' | 'controller' | 'workerHandler' | 'controllerHandler';
+    type: 'added' | 'removed' | 'changed';
+    name: string;
+  }[] = [];
+
+  diffResult.workers.added.forEach((name) => {
+    diffNormalized.push({ what: 'worker', type: 'added', name });
+  });
+
+  diffResult.workers.removed.forEach((name) => {
+    diffNormalized.push({ what: 'worker', type: 'removed', name });
+  });
+
+  diffResult.controllers.added.forEach((name) => {
+    diffNormalized.push({ what: 'controller', type: 'added', name });
+  });
+
+  diffResult.controllers.removed.forEach((name) => {
+    diffNormalized.push({ what: 'controller', type: 'removed', name });
+  });
+
+  diffResult.controllers.handlers.forEach((handler) => {
+    handler.added.forEach((name) => {
+      diffNormalized.push({ what: 'controllerHandler', type: 'added', name: `${handler.nameOfClass}.${name}` });
+    });
+
+    handler.removed.forEach((name) => {
+      diffNormalized.push({ what: 'controllerHandler', type: 'removed', name: `${handler.nameOfClass}.${name}` });
+    });
+
+    handler.changed.forEach((name) => {
+      diffNormalized.push({ what: 'controllerHandler', type: 'changed', name: `${handler.nameOfClass}.${name}` });
+    });
+  });
+
+  const LIMIT = 5;
+
+  for (const diffNormalizedItem of diffNormalized.slice(0, LIMIT)) {
+    switch (diffNormalizedItem.what) {
+      case 'worker':
+        switch (diffNormalizedItem.type) {
+          case 'added':
+            projectInfo.log.info(
+              `New worker ${chalk.white.bold(diffNormalizedItem.name)} has been added to segment "${chalk.white.bold(segmentName)}"`
+            );
+            break;
+          case 'removed':
+            projectInfo.log.info(
+              `Worker ${chalk.white.bold(diffNormalizedItem.name)} has been removed from segment "${chalk.white.bold(segmentName)}"`
+            );
+            break;
+        }
+        break;
+      case 'controller':
+        switch (diffNormalizedItem.type) {
+          case 'added':
+            projectInfo.log.info(
+              `New controller ${chalk.white.bold(diffNormalizedItem.name)} has been added to segment "${chalk.white.bold(segmentName)}"`
+            );
+            break;
+          case 'removed':
+            projectInfo.log.info(
+              `Controller ${chalk.white.bold(diffNormalizedItem.name)} has been removed from segment "${chalk.white.bold(segmentName)}"`
+            );
+            break;
+        }
+        break;
+      case 'workerHandler':
+        switch (diffNormalizedItem.type) {
+          case 'added':
+            projectInfo.log.info(
+              `New worker method ${chalk.white.bold(diffNormalizedItem.name)} has been added in segment "${chalk.white.bold(segmentName)}"`
+            );
+            break;
+          case 'removed':
+            projectInfo.log.info(
+              `Worker method ${chalk.white.bold(diffNormalizedItem.name)} has been removed in segment "${chalk.white.bold(segmentName)}"`
+            );
+            break;
+        }
+        break;
+
+      case 'controllerHandler':
+        switch (diffNormalizedItem.type) {
+          case 'added':
+            projectInfo.log.info(
+              `New controller method ${chalk.white.bold(diffNormalizedItem.name)} has been added in segment "${chalk.white.bold(segmentName)}"`
+            );
+            break;
+          case 'removed':
+            projectInfo.log.info(
+              `Controller method ${chalk.white.bold(diffNormalizedItem.name)} has been removed in segment "${chalk.white.bold(segmentName)}"`
+            );
+            break;
+          case 'changed':
+            projectInfo.log.info(
+              `Controller method ${chalk.white.bold(diffNormalizedItem.name)} has been changed in segment "${chalk.white.bold(segmentName)}"`
+            );
+            break;
+        }
+        break;
+    }
+  }
+
+  if (diffNormalized.length > LIMIT) {
+    projectInfo.log.info(`...and ${diffNormalized.length - LIMIT} more changes`);
+  }
+}

package/src/server/writeOneMetadataFile.ts

@@ -0,0 +1,44 @@
+import path from 'path';
+import fs from 'fs/promises';
+import { VovkMetadata } from 'vovk';
+import diffMetadata, { DiffResult } from './diffMetadata';
+
+export const ROOT_SEGMENT_SCHEMA_NAME = '_root';
+
+export default async function writeOneMetadataFile({
+  metadataOutFullPath,
+  metadata,
+  skipIfExists = false,
+}: {
+  metadataOutFullPath: string;
+  metadata: VovkMetadata;
+  skipIfExists?: boolean;
+}): Promise<{
+  isCreated: boolean;
+  diffResult: DiffResult | null;
+}> {
+  const segmentPath = path.join(metadataOutFullPath, `${metadata.segmentName || ROOT_SEGMENT_SCHEMA_NAME}.json`);
+
+  if (skipIfExists) {
+    try {
+      await fs.stat(segmentPath);
+      return { isCreated: false, diffResult: null };
+    } catch {
+      // File doesn't exist
+    }
+  }
+
+  await fs.mkdir(path.dirname(segmentPath), { recursive: true });
+  const metadataStr = JSON.stringify(metadata, null, 2);
+  const existing = await fs.readFile(segmentPath, 'utf-8').catch(() => null);
+  if (existing === metadataStr) {
+    return { isCreated: false, diffResult: null };
+  }
+  await fs.writeFile(segmentPath, metadataStr);
+
+  if (existing) {
+    return { isCreated: false, diffResult: diffMetadata(JSON.parse(existing), metadata) };
+  }
+
+  return { isCreated: true, diffResult: null };
+}