import { readFileSync, existsSync } from 'fs'; import { join, resolve as resolvePath } from 'path'; import type { Schema } from 'nx/src/utils/params'; export type PluginSchemaWithExamples = Schema & { examplesFile?: string; }; export function getPropertyType(property: any): string { if (property.type) { if (Array.isArray(property.type)) { return property.type.join(' | '); } return property.type; } if (property.oneOf) { return 'string'; } return 'any'; } export function getPropertyDefault(property: any): string { if (property.default !== undefined) { return `\`${JSON.stringify(property.default)}\``; } if (property.$default) { if ( property.$default.$source === 'argv' && property.$default.index !== undefined ) { return 'From command line'; } } return ''; } export type PluginItem = { config: Record; schema: PluginSchemaWithExamples; schemaPath: string; }; // schema.json files are hand-authored sources copied verbatim into dist at build // time. When a plugin's dist isn't built during docs generation (e.g. @nx/gradle, // whose dist requires a Gradle/JVM assemble step) the built path is missing, so // fall back to the source path by stripping the leading "dist/" segment. function resolveSchemaPath(pluginPath: string, schemaRef: string): string { const builtPath = join(pluginPath, schemaRef); if (existsSync(builtPath)) { return builtPath; } const sourcePath = join(pluginPath, schemaRef.replace(/^(\.\/)?dist\//, '')); return existsSync(sourcePath) ? sourcePath : builtPath; } export function parseGenerators( pluginPath: string ): Map | null { const generatorsJsonPath = join(pluginPath, 'generators.json'); if (!existsSync(generatorsJsonPath)) { return null; // Plugin might not have generators } const generatorsJson = JSON.parse(readFileSync(generatorsJsonPath, 'utf-8')); const generators = new Map(); for (const [name, config] of Object.entries( generatorsJson.generators || {} ) as [string, any][]) { // Skip hidden generators if (config.hidden) { continue; } const schemaPath = resolveSchemaPath(pluginPath, config.schema); const schema = JSON.parse(readFileSync(schemaPath, 'utf-8')); generators.set(name, { config, schema, schemaPath }); } return generators; } export function parseExecutors( pluginPath: string ): Map | null { const executorsJsonPath = join(pluginPath, 'executors.json'); if (!existsSync(executorsJsonPath)) { return null; // Plugin might not have executors } const executorsJson = JSON.parse(readFileSync(executorsJsonPath, 'utf-8')); const executors = new Map(); for (const [name, config] of Object.entries( executorsJson.executors || {} ) as [string, any][]) { // Skip hidden executors if (config.hidden) { continue; } const schemaPath = resolveSchemaPath(pluginPath, config.schema); const schema = JSON.parse(readFileSync(schemaPath, 'utf-8')); executors.set(name, { config, schema, schemaPath }); } return executors; } export type PluginMigrationItem = { config: Record; type: 'packageJsonUpdate' | 'generator'; }; export function parseMigrations(pluginPath: string): Map | null { const migrationsJsonPath = join(pluginPath, 'migrations.json'); if (!existsSync(migrationsJsonPath)) { return null; // Plugin might not have migrations } const migrationsJson = JSON.parse(readFileSync(migrationsJsonPath, 'utf-8')); const migrations = new Map(); // Parse generators (migrations) for (const [name, config] of Object.entries( migrationsJson.generators || {} ) as [string, any][]) { if (config.documentation) { config['documentationPath'] = resolvePath( pluginPath, config.documentation ); } migrations.set(name, { config, type: 'generator' }); } // Parse packageJsonUpdates for (const [version, config] of Object.entries( migrationsJson.packageJsonUpdates || {} ) as [string, any][]) { migrations.set(`${version}-package-updates`, { config: { ...config, name: version }, type: 'packageJsonUpdate', }); } return migrations; }