@breadstone-infrastructure/nx-tasks 0.0.257 → 0.0.258

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

@@ -0,0 +1,381 @@
+// #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

@@ -0,0 +1,47 @@
+// #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

@@ -0,0 +1,258 @@
+{
+  "$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

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