Свой плагин

Плагин — это класс, который наследуется от BasePlugin и возвращает массив предложенных файлов. Самостоятельно писать файлы на диск плагину не нужно: это делает FileGenerator, чтобы все артефакты проходили через общий headerTemplate, format, логирование, cleanup и каскадные итерации.

generate

Метод для рекомендации генератору создать или изменить файлы.

import path from 'node:path';

import { 
  BasePlugin, 
  type TypeGeneratedFiles, 
  type TypePluginGenerateArgs 
} from '@arfa-tools/generator';

export class PluginBuildInfo extends BasePlugin {
  name = 'build-info';

  async generate({ 
    rootDir, 
    pluginLog 
  }: TypePluginGenerateArgs): Promise<TypeGeneratedFiles> {
    pluginLog({ plugin: this.name, message: 'Generating build info' });

    return [
      {
        plugin: this.name,
        filePath: path.resolve(rootDir, 'buildInfo.generated.ts'),
        rawContent: "export const generatorName = '@arfa-tools/generator';\n",
      },
    ];
  }
}

rootDir: string	Корневая директория, переданная в FileGenerator
changedFiles?: Array<{ event: 'add' | 'change' | 'unlink'; origin: 'watch' | 'cascade'; filePath: string; eventTimeMs: number; relativePath: string; }>	Список изменившихся файлов в watch-режиме или каскадной итерации. На первой итерации generator.runFullCycle() приходит undefined
pluginLog: (log: { message: string; plugin: string; }) => void	Функция для регистрации информационных сообщений
pluginError: (log: { message: string; plugin: string; error: unknown; }) => void	Функция для регистрации ошибок

При неизменных входных данных возвращайте одинаковое содержимое. Date.now(), случайные значения или другие изменяющиеся данные внутри generate могут вызвать каскад (до лимита в 10 итераций).

TypeGeneratedFiles

plugin: string	Имя плагина для логов
filePath: string	Абсолютный путь целевого файла
rawContent: string	Содержимое до headerTemplate и format
skipHeader?: boolean	Отключает общий header для конкретного файла. Полезен для JSON, ассетов, документации и т.п.

cleanup

Метод для рекомендации генератору удалить файлы.

import path from 'node:path';

import {
  BasePlugin,
  type TypeCleanupFiles,
  type TypeGeneratedFiles,
  type TypePluginCleanupArgs,
  type TypePluginGenerateArgs,
} from '@arfa-tools/generator';

export class PluginBuildInfo extends BasePlugin {
  name = 'build-info';

  async generate({ rootDir }: TypePluginGenerateArgs): Promise<TypeGeneratedFiles> {
    return [{
      plugin: this.name,
      filePath: path.resolve(rootDir, 'generated/buildInfo/index.generated.ts'),
      rawContent: "export const generatorName = '@arfa-tools/generator';\n",
    }];
  }

  cleanup({ rootDir, generatedFiles, changedFiles }: TypePluginCleanupArgs): TypeCleanupFiles {
    // Cleanup only during runFullCycle()
    if (changedFiles) return [];

    const expectedPaths = new Set(
      generatedFiles
        .filter(({ plugin }) => plugin === this.name)
        .map(({ filePath }) => filePath)
    );

    return this.globToPaths({
      rootDir,
      entries: ['generated/buildInfo/*.generated.ts'],
      kind: 'file',
    })
      .filter((filePath) => !expectedPaths.has(filePath))
      .map((filePath) => ({ plugin: this.name, filePath }));
  }
}

rootDir: string	Корневая директория, переданная в FileGenerator
changedFiles?: Array<{ event: 'add' | 'change' | 'unlink'; origin: 'watch' | 'cascade'; filePath: string; eventTimeMs: number; relativePath: string; }>	Список изменившихся файлов в watch-режиме или каскадной итерации. На первой итерации generator.runFullCycle() приходит undefined
generatedFiles: TypeGeneratedFiles	Результаты успешно завершившихся вызовов generate всех плагинов за текущую итерацию, включая не записанные на диск из-за совпадения контента

Cleanup вызывается после записи и получает результаты успешно завершившихся вызовов generate за текущую итерацию. Если generate плагина выбросил исключение, его cleanup не выполняется, сохраняя ранее созданные артефакты.

TypeCleanupFiles

plugin: string	Имя плагина для логов
filePath: string	Абсолютный путь файла, который генератор должен удалить

Встроенные helpers

BasePlugin содержит два helper-метода, которые возвращают отсортированные абсолютные пути:

globToPaths(params: { rootDir: string; entries: Array<string>; kind: 'file' | 'dir'; exclude?: RegExp; }): Array<string>	Находит файлы или директории по glob-паттернам относительно rootDir
getDirectChildren(params: { folderPath: string; filter?: (filePath: string) => boolean; exclude?: RegExp; }): Array<string>	Возвращает прямые дочерние файлы папки с опциональной фильтрацией

entries задаются относительно rootDir без абсолютных путей, а сегменты .. не допускаются.

exclude проверяет имя файла или папки.