@breadstone-infrastructure/nx-tasks 0.0.258 → 0.0.259

package/src/executors/generate-package-docs/executor.task.ts

@@ -1,381 +0,0 @@
-// #region Imports
-
-import { ConsoleLogger, logSeparator } from '@breadstone-infrastructure/utilities';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-
-import {
-    countMarkdownFiles,
-    escapeAngleBrackets,
-    normalizeFrontmatter,
-    resolveInlineLinks,
-    rewriteLinks,
-    stripPackageBackLink,
-} from '../../utils/markdown-processing';
-
-// #endregion
-
-/**
- * @description Task to generate API documentation for a library package using TypeDoc.
- * @public
- */
-export namespace GeneratePackageDocsTask {
-
-    /**
-     * Post-processing options for generated Markdown files.
-     *
-     * @public
-     */
-    export interface IPostProcessingOptions {
-        /** Remove the auto-generated README.md from output. */
-        removeReadme?: boolean;
-        /** Rename globals.md to index.md for static site generators. */
-        renameGlobalsToIndex?: boolean;
-        /** Rewrite `.md` extension links for clean URL compatibility. */
-        rewriteLinks?: boolean;
-        /** Escape angle brackets in type generics for Vue/VitePress. */
-        escapeAngleBrackets?: boolean;
-        /** Add or normalize YAML frontmatter with a title. */
-        normalizeFrontmatter?: boolean;
-        /** Mark generated files with `generated: true` in frontmatter. */
-        markAsGenerated?: boolean;
-        /** Strip TypeDoc-generated package back-links at the top of pages. */
-        stripPackageBackLink?: boolean;
-        /** Resolve unresolved `{@link}` TSDoc references to plain text. */
-        resolveInlineLinks?: boolean;
-    }
-
-    /**
-     * Options for the generate-package-docs task.
-     *
-     * @public
-     */
-    export interface IGeneratePackageDocsTaskOptions {
-        /** Absolute path to the project root. */
-        cwd: string;
-        /** Absolute path to the workspace root. */
-        workspaceRoot: string;
-        /** Nx project name. */
-        projectName: string;
-
-        /** Entry point file relative to `cwd`. */
-        entryPoint?: string;
-        /** Additional entry point paths (absolute or relative to workspace root). */
-        additionalEntryPoints?: string[];
-        /** TypeScript config file relative to `cwd`. */
-        tsConfig?: string;
-        /** Output directory (absolute or relative to workspace root). */
-        outputDir?: string;
-        /** Display name for the package in generated docs. Auto-detected from package.json if omitted. */
-        packageDisplayName?: string;
-
-        /** TypeDoc output file strategy. */
-        outputFileStrategy?: string;
-        /** Flatten output files into a single directory. */
-        flattenOutputFiles?: boolean;
-        /** Hide page headers in generated Markdown. */
-        hidePageHeader?: boolean;
-        /** Hide page titles in generated Markdown. */
-        hidePageTitle?: boolean;
-        /** Hide breadcrumb navigation in generated Markdown. */
-        hideBreadcrumbs?: boolean;
-        /** Wrap code examples in fenced code blocks. */
-        useCodeBlocks?: boolean;
-        /** Expand object types inline. */
-        expandObjects?: boolean;
-        /** Format for function parameters. */
-        parametersFormat?: string;
-        /** Format for enum members. */
-        enumMembersFormat?: string;
-        /** Format for type declarations. */
-        typeDeclarationFormat?: string;
-        /** Format for index/listing pages. */
-        indexFormat?: string;
-        /** TypeDoc member kinds that get their own file. */
-        membersWithOwnFile?: string[];
-
-        /** Exclude private members from docs. */
-        excludePrivate?: boolean;
-        /** Exclude protected members from docs. */
-        excludeProtected?: boolean;
-        /** Exclude `@internal` members from docs. */
-        excludeInternal?: boolean;
-        /** Exclude external/third-party symbols from docs. */
-        excludeExternals?: boolean;
-
-        /** Category display order in index pages. */
-        categoryOrder?: string[];
-        /** Sort order for members. */
-        sort?: string[];
-        /** Kind sort order for members. */
-        kindSortOrder?: string[];
-
-        /** Git revision used for source links. */
-        gitRevision?: string;
-        /** TypeDoc log level. */
-        logLevel?: string;
-
-        /** Post-processing options for generated Markdown. */
-        postProcessing?: IPostProcessingOptions;
-
-        /** Enable verbose logging. */
-        verbose?: boolean;
-    }
-
-    // #region Fields
-
-    const DEFAULT_POST_PROCESSING: Required<IPostProcessingOptions> = {
-        removeReadme: true,
-        renameGlobalsToIndex: true,
-        rewriteLinks: true,
-        escapeAngleBrackets: true,
-        normalizeFrontmatter: true,
-        markAsGenerated: true,
-        stripPackageBackLink: true,
-        resolveInlineLinks: true,
-    };
-
-    const DEFAULT_OPTIONS = {
-        entryPoint: 'src/Index.ts',
-        tsConfig: 'tsconfig.json',
-        outputFileStrategy: 'members',
-        flattenOutputFiles: true,
-        hidePageHeader: false,
-        hidePageTitle: false,
-        hideBreadcrumbs: true,
-        useCodeBlocks: true,
-        expandObjects: true,
-        parametersFormat: 'table',
-        enumMembersFormat: 'table',
-        typeDeclarationFormat: 'table',
-        indexFormat: 'table',
-        membersWithOwnFile: ['Class', 'Interface', 'TypeAlias', 'Enum', 'Function', 'Variable'],
-        excludePrivate: true,
-        excludeProtected: false,
-        excludeInternal: true,
-        excludeExternals: true,
-        categoryOrder: ['Classes', 'Interfaces', 'Type Aliases', 'Functions', 'Enumerations', 'Variables'],
-        sort: ['alphabetical'],
-        kindSortOrder: ['Class', 'Interface', 'TypeAlias', 'Function', 'Enum', 'Variable'],
-        gitRevision: 'main',
-        logLevel: 'Warn',
-    };
-
-    // #endregion
-
-    // #region Methods
-
-    /**
-     * Runs the generate-package-docs task.
-     *
-     * @public
-     */
-    export async function run(options: IGeneratePackageDocsTaskOptions): Promise<void> {
-        const logger = new ConsoleLogger();
-
-        logSeparator(logger, 'Generate Package Docs');
-
-        const projectRoot = options.cwd;
-        const workspaceRoot = options.workspaceRoot;
-        const projectName = options.projectName;
-
-        const entryPointRelative = options.entryPoint ?? DEFAULT_OPTIONS.entryPoint;
-        const entryPoint = path.resolve(projectRoot, entryPointRelative);
-
-        if (!fs.existsSync(entryPoint)) {
-            throw new Error(`Entry point not found: ${entryPoint}`);
-        }
-
-        const tsConfigRelative = options.tsConfig ?? DEFAULT_OPTIONS.tsConfig;
-        const tsConfig = path.resolve(projectRoot, tsConfigRelative);
-        const fallbackTsConfig = path.join(workspaceRoot, 'tsconfig.base.json');
-
-        const outputDir = options.outputDir
-            ? path.resolve(workspaceRoot, options.outputDir)
-            : path.join(workspaceRoot, '.docs', 'packages', projectName, 'api');
-
-        let packageDisplayName = options.packageDisplayName ?? projectName;
-        const packageJsonPath = path.join(projectRoot, 'package.json');
-
-        if (!options.packageDisplayName && fs.existsSync(packageJsonPath)) {
-            try {
-                const pkgJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-                if (pkgJson.name) {
-                    packageDisplayName = pkgJson.name;
-                }
-            } catch {
-                // Falls back to project name
-            }
-        }
-
-        const additionalEntryPoints = resolveAdditionalEntryPoints(
-            options.additionalEntryPoints,
-            workspaceRoot,
-            options.verbose ? logger : undefined,
-        );
-
-        if (options.verbose) {
-            logger.log(`  📦 Project: ${projectName}`);
-            logger.log(`  📂 Entry: ${entryPoint}`);
-            if (additionalEntryPoints.length > 0) {
-                logger.log(`  📂 Additional entries: ${additionalEntryPoints.length}`);
-            }
-            logger.log(`  📁 Output: ${outputDir}`);
-        }
-
-        logger.log(`  📦 Generating docs for ${projectName}...`);
-
-        if (fs.existsSync(outputDir)) {
-            fs.rmSync(outputDir, { recursive: true });
-        }
-
-        let typedocEntry = entryPoint;
-        let tempEntryFile: string | null = null;
-
-        if (additionalEntryPoints.length > 0) {
-            logger.log(`  📂 Entry points: main + ${additionalEntryPoints.length} subpath(s)`);
-            const libSrc = path.join(projectRoot, 'src');
-            tempEntryFile = path.join(libSrc, '_typedoc-entry.ts');
-
-            const lines = ["export * from './index';"];
-            for (const ep of additionalEntryPoints) {
-                const rel = path.relative(libSrc, ep).replace(/\.ts$/, '').replace(/\\/g, '/');
-                lines.push(`export * from './${rel}';`);
-            }
-            fs.writeFileSync(tempEntryFile, lines.join('\n') + '\n', 'utf-8');
-            typedocEntry = tempEntryFile;
-        }
-
-        try {
-            const { Application } = await import('typedoc');
-
-            const typedocOptions = {
-                entryPoints: [typedocEntry],
-                entryPointStrategy: 'resolve' as const,
-                tsconfig: fs.existsSync(tsConfig) ? tsConfig : fallbackTsConfig,
-                skipErrorChecking: true,
-                out: outputDir,
-                plugin: ['typedoc-plugin-markdown'],
-
-                outputFileStrategy: options.outputFileStrategy ?? DEFAULT_OPTIONS.outputFileStrategy,
-                flattenOutputFiles: options.flattenOutputFiles ?? DEFAULT_OPTIONS.flattenOutputFiles,
-                hidePageHeader: options.hidePageHeader ?? DEFAULT_OPTIONS.hidePageHeader,
-                hidePageTitle: options.hidePageTitle ?? DEFAULT_OPTIONS.hidePageTitle,
-                hideBreadcrumbs: options.hideBreadcrumbs ?? DEFAULT_OPTIONS.hideBreadcrumbs,
-                useCodeBlocks: options.useCodeBlocks ?? DEFAULT_OPTIONS.useCodeBlocks,
-                expandObjects: options.expandObjects ?? DEFAULT_OPTIONS.expandObjects,
-                parametersFormat: options.parametersFormat ?? DEFAULT_OPTIONS.parametersFormat,
-                enumMembersFormat: options.enumMembersFormat ?? DEFAULT_OPTIONS.enumMembersFormat,
-                typeDeclarationFormat: options.typeDeclarationFormat ?? DEFAULT_OPTIONS.typeDeclarationFormat,
-                indexFormat: options.indexFormat ?? DEFAULT_OPTIONS.indexFormat,
-                membersWithOwnFile: options.membersWithOwnFile ?? DEFAULT_OPTIONS.membersWithOwnFile,
-
-                projectDocuments: [],
-
-                excludePrivate: options.excludePrivate ?? DEFAULT_OPTIONS.excludePrivate,
-                excludeProtected: options.excludeProtected ?? DEFAULT_OPTIONS.excludeProtected,
-                excludeInternal: options.excludeInternal ?? DEFAULT_OPTIONS.excludeInternal,
-                excludeExternals: options.excludeExternals ?? DEFAULT_OPTIONS.excludeExternals,
-
-                categoryOrder: options.categoryOrder ?? DEFAULT_OPTIONS.categoryOrder,
-                sort: options.sort ?? DEFAULT_OPTIONS.sort,
-                kindSortOrder: options.kindSortOrder ?? DEFAULT_OPTIONS.kindSortOrder,
-
-                gitRevision: options.gitRevision ?? DEFAULT_OPTIONS.gitRevision,
-                logLevel: options.logLevel ?? DEFAULT_OPTIONS.logLevel,
-                name: packageDisplayName,
-            };
-
-            const app = await Application.bootstrapWithPlugins(typedocOptions as Record<string, unknown>);
-            const project = await app.convert();
-
-            if (!project) {
-                throw new Error(`TypeDoc conversion failed for ${projectName}`);
-            }
-
-            await app.generateOutputs(project);
-
-            const postProcessing = { ...DEFAULT_POST_PROCESSING, ...options.postProcessing };
-
-            if (postProcessing.removeReadme) {
-                const readmePath = path.join(outputDir, 'README.md');
-                if (fs.existsSync(readmePath)) {
-                    fs.unlinkSync(readmePath);
-                }
-            }
-
-            if (postProcessing.renameGlobalsToIndex) {
-                const globalsPath = path.join(outputDir, 'globals.md');
-                const indexPath = path.join(outputDir, 'index.md');
-                if (fs.existsSync(globalsPath) && !fs.existsSync(indexPath)) {
-                    fs.renameSync(globalsPath, indexPath);
-                }
-            }
-
-            processGeneratedMarkdown(outputDir, postProcessing);
-
-            const count = countMarkdownFiles(outputDir);
-            logger.log(`  ✅ ${projectName}: ${count} API doc files`);
-        } finally {
-            if (tempEntryFile && fs.existsSync(tempEntryFile)) {
-                fs.unlinkSync(tempEntryFile);
-            }
-
-            logSeparator(logger);
-        }
-    }
-
-    // #endregion
-
-    // #region Private
-
-    function resolveAdditionalEntryPoints(
-        entryPoints: string[] | undefined,
-        workspaceRoot: string,
-        logger?: ConsoleLogger,
-    ): string[] {
-        if (!entryPoints) {
-            return [];
-        }
-
-        const resolved: string[] = [];
-        for (const ep of entryPoints) {
-            const abs = path.isAbsolute(ep) ? ep : path.resolve(workspaceRoot, ep);
-            if (fs.existsSync(abs)) {
-                resolved.push(abs);
-            } else {
-                logger?.warn(`  ⚠ Additional entry point not found: ${ep}`);
-            }
-        }
-
-        return resolved;
-    }
-
-    function processGeneratedMarkdown(dir: string, options: Required<IPostProcessingOptions>): void {
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const fullPath = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                processGeneratedMarkdown(fullPath, options);
-            } else if (entry.name.endsWith('.md')) {
-                if (options.normalizeFrontmatter) {
-                    normalizeFrontmatter(fullPath, { generated: options.markAsGenerated });
-                }
-                if (options.rewriteLinks) {
-                    rewriteLinks(fullPath);
-                }
-                if (options.stripPackageBackLink) {
-                    stripPackageBackLink(fullPath);
-                }
-                if (options.resolveInlineLinks) {
-                    resolveInlineLinks(fullPath);
-                }
-                if (options.escapeAngleBrackets) {
-                    escapeAngleBrackets(fullPath);
-                }
-            }
-        }
-    }
-
-    // #endregion
-
-}

package/src/executors/generate-package-docs/executor.ts

@@ -1,47 +0,0 @@
-// #region Imports
-
-import type { ExecutorContext } from '@nx/devkit';
-import { getProjectRoot } from '../../utils/getProjectRoot';
-import { isVerbose } from '../../utils/isVerbose';
-import type { GeneratePackageDocsExecutorOptions } from './executor.options';
-
-// #endregion
-
-export default async function runExecutor(
-    options: GeneratePackageDocsExecutorOptions,
-    context: ExecutorContext,
-): Promise<{ success: boolean }> {
-    try {
-        const projectName = context.projectName;
-
-        if (!projectName) {
-            throw new Error('No project name available in executor context.');
-        }
-
-        // Auto-discover additional entry points from the build target when not explicitly provided
-        let additionalEntryPoints = options.additionalEntryPoints;
-        if (!additionalEntryPoints) {
-            const projectNode = context.projectGraph?.nodes[projectName];
-            const buildTarget = projectNode?.data.targets?.['build'];
-            if (Array.isArray(buildTarget?.options?.additionalEntryPoints)) {
-                additionalEntryPoints = buildTarget.options.additionalEntryPoints as string[];
-            }
-        }
-
-        const task = (await import('./executor.task')).GeneratePackageDocsTask;
-        await task.run({
-            ...options,
-            cwd: getProjectRoot(context),
-            workspaceRoot: context.root,
-            projectName,
-            additionalEntryPoints,
-            verbose: isVerbose(context, options),
-        });
-
-        return { success: true };
-    } catch (error) {
-        console.error(error);
-
-        return { success: false };
-    }
-}

package/src/executors/generate-package-docs/schema.json

@@ -1,258 +0,0 @@
-{
-  "$schema": "https://json-schema.org/schema",
-  "title": "Generate Package Docs",
-  "description": "Generates API documentation for a library package using TypeDoc with Markdown output and configurable post-processing.",
-  "type": "object",
-  "properties": {
-    "entryPoint": {
-      "type": "string",
-      "description": "Entry point file relative to the project root.",
-      "default": "src/Index.ts"
-    },
-    "additionalEntryPoints": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Additional entry point paths (absolute or relative to workspace root). Auto-discovered from the build target's `additionalEntryPoints` when omitted."
-    },
-    "tsConfig": {
-      "type": "string",
-      "description": "TypeScript config file relative to the project root.",
-      "default": "tsconfig.json"
-    },
-    "outputDir": {
-      "type": "string",
-      "description": "Output directory (absolute or relative to workspace root). Defaults to `.docs/packages/{projectName}/api`."
-    },
-    "packageDisplayName": {
-      "type": "string",
-      "description": "Display name for the package in generated docs. Auto-detected from package.json when omitted."
-    },
-    "outputFileStrategy": {
-      "type": "string",
-      "enum": [
-        "members",
-        "modules"
-      ],
-      "description": "TypeDoc output file strategy.",
-      "default": "members"
-    },
-    "flattenOutputFiles": {
-      "type": "boolean",
-      "description": "Flatten output files into a single directory.",
-      "default": true
-    },
-    "hidePageHeader": {
-      "type": "boolean",
-      "description": "Hide page headers in generated Markdown.",
-      "default": false
-    },
-    "hidePageTitle": {
-      "type": "boolean",
-      "description": "Hide page titles in generated Markdown.",
-      "default": false
-    },
-    "hideBreadcrumbs": {
-      "type": "boolean",
-      "description": "Hide breadcrumb navigation in generated Markdown.",
-      "default": true
-    },
-    "useCodeBlocks": {
-      "type": "boolean",
-      "description": "Wrap code examples in fenced code blocks.",
-      "default": true
-    },
-    "expandObjects": {
-      "type": "boolean",
-      "description": "Expand object types inline.",
-      "default": true
-    },
-    "parametersFormat": {
-      "type": "string",
-      "enum": [
-        "table",
-        "list",
-        "htmlTable"
-      ],
-      "description": "Format for function parameters.",
-      "default": "table"
-    },
-    "enumMembersFormat": {
-      "type": "string",
-      "enum": [
-        "table",
-        "list",
-        "htmlTable"
-      ],
-      "description": "Format for enum members.",
-      "default": "table"
-    },
-    "typeDeclarationFormat": {
-      "type": "string",
-      "enum": [
-        "table",
-        "list",
-        "htmlTable"
-      ],
-      "description": "Format for type declarations.",
-      "default": "table"
-    },
-    "indexFormat": {
-      "type": "string",
-      "enum": [
-        "table",
-        "list",
-        "htmlTable"
-      ],
-      "description": "Format for index/listing pages.",
-      "default": "table"
-    },
-    "membersWithOwnFile": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "TypeDoc member kinds that get their own file.",
-      "default": [
-        "Class",
-        "Interface",
-        "TypeAlias",
-        "Enum",
-        "Function",
-        "Variable"
-      ]
-    },
-    "excludePrivate": {
-      "type": "boolean",
-      "description": "Exclude private members from docs.",
-      "default": true
-    },
-    "excludeProtected": {
-      "type": "boolean",
-      "description": "Exclude protected members from docs.",
-      "default": false
-    },
-    "excludeInternal": {
-      "type": "boolean",
-      "description": "Exclude @internal members from docs.",
-      "default": true
-    },
-    "excludeExternals": {
-      "type": "boolean",
-      "description": "Exclude external/third-party symbols from docs.",
-      "default": true
-    },
-    "categoryOrder": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Category display order in index pages.",
-      "default": [
-        "Classes",
-        "Interfaces",
-        "Type Aliases",
-        "Functions",
-        "Enumerations",
-        "Variables"
-      ]
-    },
-    "sort": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Sort order for members.",
-      "default": [
-        "alphabetical"
-      ]
-    },
-    "kindSortOrder": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Kind sort order for members.",
-      "default": [
-        "Class",
-        "Interface",
-        "TypeAlias",
-        "Function",
-        "Enum",
-        "Variable"
-      ]
-    },
-    "gitRevision": {
-      "type": "string",
-      "description": "Git revision used for source links.",
-      "default": "main"
-    },
-    "logLevel": {
-      "type": "string",
-      "enum": [
-        "Verbose",
-        "Info",
-        "Warn",
-        "Error",
-        "None"
-      ],
-      "description": "TypeDoc log level.",
-      "default": "Warn"
-    },
-    "postProcessing": {
-      "type": "object",
-      "description": "Post-processing options for generated Markdown files. All default to true.",
-      "properties": {
-        "removeReadme": {
-          "type": "boolean",
-          "description": "Remove the auto-generated README.md from output.",
-          "default": true
-        },
-        "renameGlobalsToIndex": {
-          "type": "boolean",
-          "description": "Rename globals.md to index.md for static site generators.",
-          "default": true
-        },
-        "rewriteLinks": {
-          "type": "boolean",
-          "description": "Rewrite .md extension links for clean URL compatibility.",
-          "default": true
-        },
-        "escapeAngleBrackets": {
-          "type": "boolean",
-          "description": "Escape angle brackets in type generics for Vue/VitePress.",
-          "default": true
-        },
-        "normalizeFrontmatter": {
-          "type": "boolean",
-          "description": "Add or normalize YAML frontmatter with a title.",
-          "default": true
-        },
-        "markAsGenerated": {
-          "type": "boolean",
-          "description": "Mark generated files with generated: true in frontmatter.",
-          "default": true
-        },
-        "stripPackageBackLink": {
-          "type": "boolean",
-          "description": "Strip TypeDoc-generated package back-links at the top of pages.",
-          "default": true
-        },
-        "resolveInlineLinks": {
-          "type": "boolean",
-          "description": "Resolve unresolved {@link} TSDoc references to plain text.",
-          "default": true
-        }
-      },
-      "additionalProperties": false
-    },
-    "verbose": {
-      "type": "boolean",
-      "description": "Enable verbose logging.",
-      "default": false
-    }
-  },
-  "required": [],
-  "additionalProperties": false
-}

package/src/executors/icon-collection-builder/executor.options.ts

@@ -1,10 +0,0 @@
-// #region Imports
-
-import type { IconCollectionBuilderTask } from './executor.task';
-
-// #endregion
-
-/**
- * @private
- */
-export type IconCollectionBuilderExecutorOptions = Omit<IconCollectionBuilderTask.IIconCollectionBuilderTaskOptions, 'cwd' | 'packageJson' | 'tsConfigJson'>;