@breadstone-infrastructure/nx-tasks 0.0.258 → 0.0.259

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

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

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

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

package/src/executors/docs/ApiDocumenter.ts

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

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

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

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

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

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

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

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