@breadstone-infrastructure/nx-tasks 0.0.257 → 0.0.258

package/src/executors/copy2/executor.task.ts

@@ -0,0 +1,115 @@
+// #region Imports
+
+import { ArrayExtensions, ConsoleLogger, Directory, File, gray, logSeparator, logSummary, Path, StringExtensions } from '@breadstone-infrastructure/utilities';
+
+// #endregion
+
+/**
+ * A task to make a simple copy of a file or directory.
+ *
+ * @public
+ */
+export namespace Copy2Task {
+
+    /**
+     * Describes a single copy operation.
+     */
+    export interface CopyEntry {
+
+        /**
+         * The source path to copy from.
+         * It is also possible to provide an array of paths or a glob pattern.
+         */
+        from: string | Array<string>;
+
+        /**
+         * The destination path.
+         */
+        to: string;
+
+        /**
+         * A flag to indicate if the copy should be clean.
+         */
+        cleanCopy?: boolean;
+    }
+
+    export interface ICopy2TaskOptions {
+
+        /**
+         * The current working directory.
+         */
+        cwd: string;
+
+        /**
+         * A flag to indicate if the copy should be dry.
+         */
+        dryRun?: boolean;
+
+        /**
+         * A flag to indicate if the copy should be verbose.
+         */
+        verbose?: boolean;
+
+        /**
+         * One or multiple copy operations to perform.
+         */
+        copies: CopyEntry | Array<CopyEntry>;
+    }
+
+    export async function run(options: ICopy2TaskOptions): Promise<void> {
+        const logger = new ConsoleLogger();
+
+        logSeparator(logger, 'Copy');
+
+        return new Promise((resolve, _reject) => {
+            const copyEntries = ArrayExtensions.arrayify(options.copies);
+            let totalCopied = 0;
+
+            copyEntries.forEach((copy) => {
+                const to = Path.combine(options.cwd, copy.to);
+                const from = ArrayExtensions.arrayify(copy.from).map((path) => Path.combine(options.cwd, path));
+                const fromFiles = File.glob(from);
+
+                if (copy.cleanCopy) {
+                    if (Directory.exists(to)) {
+                        logger.log(`  > Deleting ${copy.to}`);
+
+                        if (!options.dryRun) {
+                            Directory.delete(to);
+                        }
+                    }
+
+                    if (File.exists(to)) {
+                        logger.log(`  > Deleting ${copy.to}`);
+
+                        if (!options.dryRun) {
+                            File.delete(to);
+                        }
+                    }
+                }
+
+                fromFiles.forEach((path) => {
+                    const toFile = Path.combine(to, Path.getFileName(path));
+
+                    if (options.verbose) {
+                        logger.log(gray(`  Copying ${path}${StringExtensions.newLine}    to ${toFile}`));
+                    }
+
+                    if (!options.dryRun) {
+                        File.copy(path, toFile);
+                    }
+                });
+
+                totalCopied += fromFiles.length;
+            });
+
+            logSummary(logger, {
+                success: [`${totalCopied} files copied`, true]
+            });
+
+            logSeparator(logger);
+
+            resolve();
+        });
+    }
+}

package/src/executors/copy2/executor.ts

@@ -0,0 +1,28 @@
+// #region Imports
+
+import type { ExecutorContext } from '@nx/devkit';
+import { getProjectRoot } from '../../utils/getProjectRoot';
+import { isVerbose } from '../../utils/isVerbose';
+import type { Copy2ExecutorOptions } from './executor.options';
+
+// #endregion
+
+/**
+ * @public
+ */
+export default async function runExecutor(options: Copy2ExecutorOptions, context: ExecutorContext): Promise<{ success: boolean }> {
+    try {
+        const task = (await import('./executor.task')).Copy2Task;
+
+        await task.run({
+            cwd: getProjectRoot(context),
+            copies: options.copies,
+            dryRun: options.dryRun,
+            verbose: isVerbose(context, options),
+        });
+        return { success: true };
+    } catch (error) {
+        console.error(error);
+        return { success: false };
+    }
+}

package/src/executors/copy2/schema.json

@@ -0,0 +1 @@
+{}

package/src/executors/docs/ApiDocumenter.ts

@@ -0,0 +1,50 @@
+// import { MarkdownDocumenter } from '@microsoft/api-documenter/lib/documenters/MarkdownDocumenter';
+// import { type ApiModel, ApiClass } from '@microsoft/api-extractor-model';
+
+// export class MyMarkdownDocumenter extends MarkdownDocumenter {
+
+//     public constructor(apiModel: ApiModel, outputFolder: string) {
+//         super(apiModel, outputFolder);
+//     }
+
+//     // Überschreibe die Methode, die Tabellen rendert
+//     protected _renderTable(rows: Array<Array<string>>): string {
+//         // Schreibe hier eigenen Markdown-Tabellen-Renderer
+//         // rows: Array von Tabellenzeilen, jeweils Array von Strings (Zellen)
+//         // Beispiel für einfache Markdown-Tabelle
+//         const [header, ...body] = rows;
+//         let md = `| ${header.join(' | ')} |\n`;
+//         md += `| ${header.map(() => '---').join(' | ')} |\n`;
+//         for (const row of body) {
+//             md += `| ${row.join(' | ')} |\n`;
+//         }
+//         return md;
+//     }
+
+//     // Überschreibe, wie/wo Dateien erzeugt werden
+//     protected onGenerateFiles(): void {
+//         for (const apiItem of this.apiModel.members) {
+//             if (apiItem instanceof ApiClass) {
+//                 // Sammle alle Member der Klasse
+//                 const classFilename = this.getFilenameForApiItem(apiItem);
+//                 const classContent = this.renderClass(apiItem); // Eigene Methode, die alles rendert
+//                 this.writeMarkdownFile(classFilename, classContent);
+//             }
+//             // ...andere Typen behandeln, falls nötig
+//         }
+//     }
+
+//     // Beispiel: Methode, die eine Klasse plus Methoden rendert
+//     private renderClass(apiClass: ApiClass): string {
+//         // Hier alles zusammenbauen, inkl. Methoden, Properties etc.
+//         let md = `# ${apiClass.displayName}\n\n`;
+//         // ...Beschreibung, Methoden, Properties etc.
+//         for (const member of apiClass.members) {
+//             // z.B. Methoden ausgeben
+//             md += `## ${member.displayName}\n\n`;
+//             // ...
+//         }
+//         return md;
+//     }
+
+// }

package/src/executors/docs/DocusaurusMarkdownFeature.ts

@@ -0,0 +1,129 @@
+// #region Imports
+
+import { FileSystem } from '@breadstone-infrastructure/utilities';
+import type { ApiItem } from '@microsoft/api-extractor-model';
+import { type IApiDocumenterPluginManifest, MarkdownDocumenterFeature, type IMarkdownDocumenterFeatureOnBeforeWritePageArgs, type IMarkdownDocumenterFeatureOnFinishedArgs } from '@microsoft/api-documenter';
+import path from 'path';
+
+// #endregion
+
+interface INavigationNode {
+    type: string;
+    label: string;
+    id?: string;
+    items?: Array<INavigationNode>;
+}
+
+export class DocusaurusMarkdownFeature extends MarkdownDocumenterFeature {
+
+    private readonly _apiItemsWithPages: Set<ApiItem> = new Set<ApiItem>();
+    private readonly _fileSystem: FileSystem = new FileSystem();
+
+    public override onInitialized(): void {
+        console.log('RushStackFeature: onInitialized()');
+    }
+
+    public override onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs): void {
+        // Add the Docusaurus frontmatter
+        const header: string = [
+            '---',
+            // Generated API docs have a built-in title header below the breadcrumbs
+            // `title: ${JSON.stringify(eventArgs.apiItem.displayName)}`,
+            'hide_title: true',
+            // Suppress the default Edit button and Next/Prev links for API docs
+            'custom_edit_url: null',
+            'pagination_prev: null',
+            'pagination_next: null',
+            '---',
+            ''
+        ].join('\n');
+        eventArgs.pageContent = header + eventArgs.pageContent;
+
+        // API Documenter generates "<!-- -->" comments to prevent emitted Markdown from
+        // being misinterpreted in certain contexts that are handed ambiguously by different
+        // Markdown engines.  See these test cases for some examples:
+        //
+        // https://github.com/microsoft/rushstack/blob/484a7be546784783f5a7b4d387cbb48b0cebde27/apps/api-documenter/src/markdown/test/__snapshots__/CustomMarkdownEmitter.test.ts.snap#L25
+        // https://github.com/microsoft/rushstack/blob/484a7be546784783f5a7b4d387cbb48b0cebde27/apps/api-documenter/src/markdown/MarkdownEmitter.ts#L248
+        //
+        // HTML comments don't work with Docusaurus, because it uses MDX instead of Markdown.
+        // However empty React fragments have an equivalent effect:
+        eventArgs.pageContent = eventArgs.pageContent.replace(/<!-- -->/g, '<></>');
+
+        this._apiItemsWithPages.add(eventArgs.apiItem);
+    }
+
+    public override onFinished(_: IMarkdownDocumenterFeatureOnFinishedArgs): void {
+        const navigationFile: INavigationNode = {
+            type: 'category',
+            label: 'API Reference',
+            items: [
+                {
+                    type: 'doc',
+                    label: '(members)',
+                    id: 'pages/index'
+                }
+            ]
+        };
+
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        this._buildNavigation(navigationFile.items!, this.context.apiModel);
+
+        const navFilePath: string = this._fileSystem.pathCombine(this.context.outputFolder, '..', 'api_nav.json');
+        const navFileContent: string = JSON.stringify(navigationFile, undefined, 2);
+
+        this._fileSystem.fileWriteAllText(navFilePath, navFileContent);
+    }
+
+    private _buildNavigation(parentNodes: Array<INavigationNode>, parentApiItem: ApiItem): void {
+        for (const apiItem of parentApiItem.members) {
+            if (this._apiItemsWithPages.has(apiItem)) {
+                const label = apiItem.displayName;
+                const id = path.posix
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                    .join('pages/', this.context.documenter.getLinkForApiItem(apiItem)!)
+                    .replace(/\.md$/, '')
+                    .replace(/\/$/, '/index');
+                const children: Array<INavigationNode> = [];
+                this._buildNavigation(children, apiItem);
+
+                if (children.length > 0) {
+                    const newNode: INavigationNode = {
+                        type: 'category',
+                        label,
+                        items: [
+                            {
+                                type: 'doc',
+                                label: '(members)',
+                                id
+                            },
+                            ...children
+                        ]
+                    };
+                    parentNodes.push(newNode);
+                } else {
+                    const newNode: INavigationNode = {
+                        type: 'doc',
+                        label,
+                        id
+                    };
+                    parentNodes.push(newNode);
+                }
+            } else {
+                this._buildNavigation(parentNodes, apiItem);
+            }
+        }
+    }
+
+}
+
+export const apiDocumenterPluginManifest: IApiDocumenterPluginManifest = {
+    manifestVersion: 1000,
+    features: [
+        {
+            featureName: 'docusaurus-markdown-documenter',
+            kind: 'MarkdownDocumenterFeature',
+            subclass: DocusaurusMarkdownFeature
+        }
+    ]
+};

package/src/executors/docs/executor.options.ts

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

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

@@ -0,0 +1,116 @@
+// #region Imports
+
+import { ConsoleLogger, File, gray, logSeparator, magenta, Path, StringExtensions, Template } from '@breadstone-infrastructure/utilities';
+import { Extractor, ExtractorConfig } from '@microsoft/api-extractor';
+// import type { IApiDocumenterPluginManifest } from '@microsoft/api-documenter';
+import type { PackageJson, TsConfigJson } from 'type-fest';
+
+// #endregion
+
+/**
+ * @description Task to generate entry markdown documentation file.
+ * @public
+ */
+export namespace DocsTask {
+
+    export interface IDocsTaskOptions {
+        cwd: string;
+        indexFile: string;
+        templatePath: string;
+        tsConfigJson: TsConfigJson;
+        packageJson: PackageJson;
+        verbose?: boolean;
+        extractor?: {
+            configPath: string;
+        };
+        documenter?: {
+            outputFolder: string;
+        };
+    }
+
+    export async function run(options: IDocsTaskOptions): Promise<void> {
+        const logger = new ConsoleLogger();
+
+        logSeparator(logger, 'Docs');
+
+        logger.log(magenta('    > Generating documentation...'));
+
+        const newImpl = false;
+
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (newImpl) {
+            return new Promise<void>((resolve, reject) => {
+                const apiExtractorJsonPath = Path.combine(options.cwd, options.extractor?.configPath ?? '');
+
+                logger.log(gray(`    config: ${apiExtractorJsonPath}`));
+
+                const extractorConfig = ExtractorConfig.loadFileAndPrepare(apiExtractorJsonPath);
+                const extractorResult = Extractor.invoke(extractorConfig, {
+                    localBuild: true, // Equivalent to the "--local" command-line parameter
+                    showVerboseMessages: false // Equivalent to the "--verbose" command-line parameter
+                });
+
+                if (extractorResult.succeeded) {
+                    console.log('API Extractor completed successfully');
+                    process.exitCode = 0;
+                } else {
+                    console.error(
+                        `API Extractor completed with ${extractorResult.errorCount} errors` +
+                        ` and ${extractorResult.warningCount} warnings`
+                    );
+                    process.exitCode = 1;
+
+                    reject();
+                }
+
+                // TODO: maybe this help:https://github.com/microsoft/rushstack-websites/blob/main/tools/api-documenter-docusaurus-plugin/src/DocusaurusMarkdownFeature.ts
+                // new ApiModel().loadPackage()
+
+                resolve();
+            });
+        }
+
+        return new Promise<void>((resolve, reject) => {
+            const docName = StringExtensions.replace((options.packageJson.name ?? '').split('/')[1], '-', '.');
+            const tplPath = Path.combine(options.cwd, options.templatePath);
+            const docPath = Path.combine(options.cwd, StringExtensions.format(options.indexFile, docName));
+            const templateContent = File.readAllText(tplPath);
+            const imports = options.tsConfigJson.compilerOptions?.rootDirs ?? ''
+                ? options.tsConfigJson.compilerOptions?.rootDirs ?? ''
+                : [options.tsConfigJson.compilerOptions?.rootDir ?? ''].map((x) => x.replace('./src', options.packageJson.name ?? ''));
+            const data = {
+                name: options.packageJson.name ?? '',
+                description: options.packageJson.description,
+                imports: imports
+            };
+
+            try {
+                logger.log(`Generating documentation for ${docName}...`);
+                logger.log(`Writing to ${docPath}...`);
+
+                const fileContent = Template.create(data, { unescapeContent: true })
+                    .apply(templateContent)
+                    .toString();
+                File.writeAllText(docPath, fileContent);
+
+                resolve();
+            } catch (error) {
+                reject(error);
+            } finally {
+                logSeparator(logger);
+            }
+        });
+    }
+
+}
+
+// export const apiDocumenterPluginManifest: IApiDocumenterPluginManifest = {
+//     manifestVersion: 1000,
+//     features: [
+//         {
+//             featureName: 'docusaurus-markdown-documenter',
+//             kind: 'MarkdownDocumenterFeature',
+//             // subclass: DocusaurusMarkdownFeature
+//         }
+//     ]
+// };

package/src/executors/docs/executor.ts

@@ -0,0 +1,33 @@
+// #region Imports
+
+import type { ExecutorContext } from '@nx/devkit';
+import { getProjectPackageJson } from '../../utils/getProjectPackageJson';
+import { getProjectRoot } from '../../utils/getProjectRoot';
+import { getProjectTsConfigJson } from '../../utils/getProjectTsConfigJson';
+import type { DocsExecutorOptions } from './executor.options';
+
+// #endregion
+
+/**
+ * @public
+ */
+export default async function runExecutor(options: DocsExecutorOptions, context: ExecutorContext): Promise<{ success: boolean }> {
+    try {
+        const task = (await import('./executor.task')).DocsTask;
+
+        await task.run({
+            cwd: getProjectRoot(context),
+            tsConfigJson: getProjectTsConfigJson(context),
+            packageJson: getProjectPackageJson(context),
+            indexFile: options.indexFile,
+            templatePath: options.templatePath,
+            extractor: options.extractor,
+            documenter: options.documenter,
+            verbose: context.isVerbose || options.verbose
+        });
+        return { success: true };
+    } catch (error) {
+        console.error(error);
+        return { success: false };
+    }
+}

package/src/executors/docs/schema.json

@@ -0,0 +1 @@
+{}

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

@@ -0,0 +1,10 @@
+// #region Imports
+
+import type { GeneratePackageDocsTask } from './executor.task';
+
+// #endregion
+
+/**
+ * @public
+ */
+export type GeneratePackageDocsExecutorOptions = Omit<GeneratePackageDocsTask.IGeneratePackageDocsTaskOptions, 'cwd' | 'workspaceRoot' | 'projectName'>;