@breadstone-infrastructure/nx-tasks 0.0.256 → 0.0.258

package/src/executors/icon-collection-downloader/executor.task.ts

@@ -0,0 +1,409 @@
+// #region Imports
+
+import { bold, ConsoleLogger, Directory, File, gray, type IFileCache, type IFileCacheOptions, type ILogger, logSeparator, magenta, Path, red, TextFileWriter, yellow } from '@breadstone-infrastructure/utilities';
+import https from 'https';
+import { withCaching } from '../../utils/withCaching';
+
+// #endregion
+
+/**
+ * Task for downloading icon collections from various providers.
+ *
+ * @public
+ */
+export namespace IconCollectionDownloaderTask {
+
+    interface IGitHubTreeResponse {
+        tree: Array<{
+            path: string;
+            type: string;
+        }>;
+    }
+
+    interface IProviderConfig {
+        name: string;
+        apiUrl: string;
+        rawContentUrl: string;
+        pathPrefix: string;
+        filter?: string;
+        preferredVariant?: number;
+        fallbackVariants?: number[];
+    }
+
+    export interface IIconCollectionDownloaderTaskOptions {
+        cwd: string;
+        outDir: string;
+        providers: Record<string, IProviderConfig>;
+        parallel?: boolean;
+        cache?: IFileCacheOptions;
+    }
+
+    interface ITreeItem {
+        path: string;
+        type: string;
+    }
+
+    interface ISelectedFile {
+        item: ITreeItem;
+        selectionKey: string;
+        selectedVariant: number | undefined;
+        isPreferred: boolean;
+        availableVariants: number[];
+    }
+
+    interface ISelectionStatistics {
+        totalSvgsFound: number;
+        uniqueIcons: number;
+        variantDistribution: Map<number, number>;
+        selectedDistribution: Map<number, number>;
+        notInPreferred: number;
+    }
+
+    interface ISelectionResult {
+        files: ISelectedFile[];
+        statistics: ISelectionStatistics;
+    }
+
+    function getOrderedVariants(providerConfig: IProviderConfig): number[] {
+        const preferred = providerConfig.preferredVariant;
+        const allVariants = [...new Set([
+            ...(typeof preferred === 'number' ? [preferred] : []),
+            ...(providerConfig.fallbackVariants ?? [])
+        ])];
+
+        if (typeof preferred !== 'number') {
+            return allVariants;
+        }
+
+        return allVariants.sort((a, b) => {
+            const distanceA = Math.abs(a - preferred);
+            const distanceB = Math.abs(b - preferred);
+
+            if (distanceA !== distanceB) {
+                return distanceA - distanceB;
+            }
+
+            return a - b;
+        });
+    }
+
+    function getVariantSelectionKey(filePath: string): string {
+        const fileName = filePath.split('/').pop() ?? filePath;
+        return fileName.replace(/_\d+(?=_[^_]+\.svg$)/i, '');
+    }
+
+    function getVariantFromPath(filePath: string): number | undefined {
+        const fileName = filePath.split('/').pop() ?? filePath;
+        const match = fileName.match(/_(\d+)(?=_[^_]+\.svg$)/i);
+        return match ? Number(match[1]) : undefined;
+    }
+
+    function selectProviderFiles(tree: ITreeItem[], providerConfig: IProviderConfig): ISelectionResult {
+        const providerEntries = tree.filter((item) => {
+            const matchesPrefix = item.path.startsWith(providerConfig.pathPrefix);
+            const isBlob = item.type === 'blob';
+            const isSvg = item.path.endsWith('.svg');
+
+            return matchesPrefix && isBlob && isSvg;
+        });
+
+        const orderedVariants = getOrderedVariants(providerConfig);
+        const hasVariantConfig = orderedVariants.length > 0;
+
+        if (!hasVariantConfig) {
+            const filtered = providerEntries.filter((item) => !providerConfig.filter || item.path.includes(providerConfig.filter));
+
+            return {
+                files: filtered.map((item) => ({
+                    item,
+                    selectionKey: item.path.split('/').pop() ?? item.path,
+                    selectedVariant: undefined,
+                    isPreferred: true,
+                    availableVariants: []
+                })),
+                statistics: {
+                    totalSvgsFound: providerEntries.length,
+                    uniqueIcons: filtered.length,
+                    variantDistribution: new Map(),
+                    selectedDistribution: new Map(),
+                    notInPreferred: 0
+                }
+            };
+        }
+
+        const groupedEntries = new Map<string, Map<number, ITreeItem>>();
+        const variantDistribution = new Map<number, number>();
+
+        for (const item of providerEntries) {
+            const variant = getVariantFromPath(item.path);
+
+            if (typeof variant !== 'number') {
+                continue;
+            }
+
+            variantDistribution.set(variant, (variantDistribution.get(variant) ?? 0) + 1);
+
+            if (!orderedVariants.includes(variant)) {
+                continue;
+            }
+
+            const selectionKey = getVariantSelectionKey(item.path);
+            const existingGroup = groupedEntries.get(selectionKey) ?? new Map<number, ITreeItem>();
+            existingGroup.set(variant, item);
+            groupedEntries.set(selectionKey, existingGroup);
+        }
+
+        const selectedFiles: ISelectedFile[] = [];
+        const selectedDistribution = new Map<number, number>();
+        let notInPreferred = 0;
+
+        for (const [selectionKey, entriesByVariant] of groupedEntries) {
+            const availableVariants = [...entriesByVariant.keys()].sort((a, b) => a - b);
+
+            const selectedEntry = orderedVariants
+                .map((variant) => ({ variant, entry: entriesByVariant.get(variant) }))
+                .find((result): result is { variant: number; entry: ITreeItem } => Boolean(result.entry));
+
+            if (selectedEntry) {
+                const isPreferred = selectedEntry.variant === providerConfig.preferredVariant;
+
+                if (!isPreferred) {
+                    notInPreferred++;
+                }
+
+                selectedDistribution.set(selectedEntry.variant, (selectedDistribution.get(selectedEntry.variant) ?? 0) + 1);
+
+                selectedFiles.push({
+                    item: selectedEntry.entry,
+                    selectionKey,
+                    selectedVariant: selectedEntry.variant,
+                    isPreferred,
+                    availableVariants
+                });
+            }
+        }
+
+        return {
+            files: selectedFiles,
+            statistics: {
+                totalSvgsFound: providerEntries.length,
+                uniqueIcons: groupedEntries.size,
+                variantDistribution,
+                selectedDistribution,
+                notInPreferred
+            }
+        };
+    }
+
+    export async function run(options: IIconCollectionDownloaderTaskOptions): Promise<void> {
+        const logger = new ConsoleLogger();
+
+        logSeparator(logger, 'Download icons');
+
+        const fileCache = withCaching(options.cache);
+        const outputPath = Path.combine(options.cwd, options.outDir);
+        const isParallel = options.parallel ?? false;
+
+        if (!Directory.exists(outputPath)) {
+            Directory.create(outputPath);
+        }
+
+        logger.log(`  Execution mode: ${isParallel ? 'Parallel' : 'Sequential'}`);
+
+        const providers = Object.entries(options.providers);
+
+        if (isParallel) {
+            const results = await Promise.allSettled(providers.map(([providerKey, providerConfig]) => processProvider(providerKey, providerConfig, outputPath, fileCache, logger)));
+
+            const successfulResults = results
+                .filter((result): result is PromiseFulfilledResult<IProviderResult> => result.status === 'fulfilled')
+                .map((result) => result.value);
+
+            const totalDownloaded = successfulResults.reduce((sum, result) => sum + result.downloaded, 0);
+            const totalCached = successfulResults.reduce((sum, result) => sum + result.cached, 0);
+
+            logger.log('  All icon downloads completed.');
+            logger.log('  Total Summary:');
+            logger.log(`  - ${totalDownloaded} icons downloaded.`);
+            logger.log(`  - ${totalCached} icons cached.`);
+        } else {
+            let totalDownloaded = 0;
+            let totalCached = 0;
+
+            for (const [providerKey, providerConfig] of providers) {
+                // eslint-disable-next-line no-await-in-loop
+                const result = await processProvider(providerKey, providerConfig, outputPath, fileCache, logger);
+                totalDownloaded += result.downloaded;
+                totalCached += result.cached;
+            }
+
+            logger.log('  All icon downloads completed.');
+            logger.log('  Total Summary:');
+            logger.log(`  - ${totalDownloaded} icons downloaded.`);
+            logger.log(`  - ${totalCached} icons cached.`);
+        }
+
+        logSeparator(logger);
+
+        return Promise.resolve();
+    }
+
+    interface IProviderResult {
+        downloaded: number;
+        cached: number;
+    }
+
+    function formatVariantDistribution(distribution: Map<number, number>): string {
+        return [...distribution.entries()]
+            .sort(([a], [b]) => a - b)
+            .map(([variant, count]) => `${variant}: ${count}`)
+            .join(' | ');
+    }
+
+    async function processProvider(
+        providerKey: string,
+        providerConfig: IProviderConfig,
+        outputPath: string,
+        fileCache: IFileCache,
+        logger: ILogger
+    ): Promise<IProviderResult> {
+        try {
+            logger.log(magenta(`  Fetching icon collection from ${providerConfig.name}...`));
+
+            const data = await fetchJson(providerConfig.apiUrl);
+            const selectionResult = selectProviderFiles(data.tree, providerConfig);
+            const { files, statistics } = selectionResult;
+
+            if (files.length === 0) {
+                logger.log(yellow(`  No SVG files found for ${providerConfig.name}.`));
+                return {
+                    downloaded: 0,
+                    cached: 0
+                };
+            }
+
+            logger.log(`  Found ${statistics.totalSvgsFound} SVG files for ${providerConfig.name}.`);
+            logger.log(`  Unique icons: ${statistics.uniqueIcons}`);
+
+            if (statistics.variantDistribution.size > 0) {
+                logger.log(`  Available variants:  ${formatVariantDistribution(statistics.variantDistribution)}`);
+                logger.log(`  Selected variants:   ${formatVariantDistribution(statistics.selectedDistribution)}`);
+
+                if (statistics.notInPreferred > 0) {
+                    logger.log(yellow(`  [!] ${statistics.notInPreferred} icons not available in preferred variant (${providerConfig.preferredVariant}).`));
+                }
+            }
+
+            const providerOutputPath = Path.combine(outputPath, providerKey);
+            if (!Directory.exists(providerOutputPath)) {
+                Directory.create(providerOutputPath);
+            }
+
+            let count = 0;
+            let downloadedCount = 0;
+            let cachedCount = 0;
+            const totalCount = files.length;
+
+            for (const selectedFile of files) {
+                const fileUrl = `${providerConfig.rawContentUrl}${selectedFile.item.path}`;
+                const fileName = selectedFile.item.path.split('/').pop() ?? selectedFile.item.path;
+                const destPath = Path.combine(providerOutputPath, fileName);
+
+                // eslint-disable-next-line no-await-in-loop
+                const cached = await downloadFile(fileUrl, destPath, fileCache, logger);
+
+                count++;
+
+                const prefix = selectedFile.isPreferred ? '' : `${bold(yellow('[!]'))} `;
+
+                if (cached) {
+                    cachedCount++;
+                    logger.log(`  ${prefix}${bold(gray(`[${count}/${totalCount}]`))} ${bold(gray('[cached]'))} ${bold(fileName)}`);
+                } else {
+                    downloadedCount++;
+                    logger.log(`  ${prefix}${bold(magenta(`[${count}/${totalCount}]`))} ${bold(fileName)}`);
+                }
+            }
+
+            logger.log(`  ${providerConfig.name} completed: ${downloadedCount} downloaded, ${cachedCount} cached.`);
+            return {
+                downloaded: downloadedCount,
+                cached: cachedCount
+            };
+        } catch (error) {
+            logger.error(`  ${red('[ERROR]')} Error downloading icons from ${providerConfig.name}: ${error}`);
+            return {
+                downloaded: 0,
+                cached: 0
+            };
+        }
+    }
+
+    function fetchJson(url: string): Promise<IGitHubTreeResponse> {
+        return new Promise((resolve, reject) => {
+            https.get(url, {
+                headers: {
+                    'User-Agent': 'Node.js'
+                }
+            }, (res) => {
+                let data = '';
+
+                res.on('data', (chunk) => {
+                    data += chunk;
+                });
+
+                res.on('end', () => {
+                    if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                        try {
+                            resolve(JSON.parse(data));
+                        } catch (error) {
+                            reject(new Error(`Error parsing JSON from ${url}: ${error}`));
+                        }
+                    } else {
+                        reject(new Error(`Request failed with status ${res.statusCode} for ${url}`));
+                    }
+                });
+            }).on('error', (error) => {
+                reject(error);
+            });
+        });
+    }
+
+    async function downloadFile(url: string, destPath: string, fileCache: IFileCache, logger: ILogger): Promise<boolean> {
+        let isFileCached = false;
+        try {
+            isFileCached = await fileCache.isFileCached(destPath);
+        } catch (error) {
+            isFileCached = false;
+            logger.error(`[ERROR] Error checking cache for ${destPath}: ${error}`);
+        }
+
+        if (!isFileCached) {
+            await new Promise<void>((resolve, reject) => {
+                const writer = new TextFileWriter(destPath);
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                const stream = writer.getWritableStream()!;
+
+                https.get(url, (res) => {
+                    if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                        res.pipe(stream);
+
+                        stream.on('finish', () => {
+                            writer.dispose();
+                            resolve();
+                        });
+                    } else {
+                        writer.dispose();
+                        File.delete(destPath);
+                        reject(new Error(`Download failed with status ${res.statusCode} for ${url}`));
+                    }
+                }).on('error', (error) => {
+                    File.delete(destPath);
+                    reject(error);
+                });
+            });
+        }
+
+        return Promise.resolve(isFileCached);
+    }
+}

package/src/executors/icon-collection-downloader/executor.ts

@@ -0,0 +1,47 @@
+// #region Imports
+
+import { Path } from '@breadstone-infrastructure/utilities';
+import type { ExecutorContext } from '@nx/devkit';
+import { getProjectRoot } from '../../utils/getProjectRoot';
+import type { IconCollectionDownloaderExecutorOptions } from './executor.options';
+
+// #endregion
+
+/**
+ * @public
+ */
+export default async function runExecutor(options: IconCollectionDownloaderExecutorOptions, context: ExecutorContext): Promise<{ success: boolean }> {
+    try {
+        const task = (await import('./executor.task')).IconCollectionDownloaderTask;
+
+        await task.run({
+            cwd: getProjectRoot(context),
+            outDir: options.outDir,
+            providers: {
+                fluent: {
+                    name: 'Fluent UI System Icons',
+                    apiUrl: 'https://api.github.com/repos/microsoft/fluentui-system-icons/git/trees/main?recursive=1',
+                    rawContentUrl: 'https://raw.githubusercontent.com/microsoft/fluentui-system-icons/main/',
+                    pathPrefix: 'assets/',
+                    preferredVariant: 24,
+                    fallbackVariants: [16, 20, 24, 28, 32, 48]
+                },
+                lucide: {
+                    name: 'Lucide Icons',
+                    apiUrl: 'https://api.github.com/repos/lucide-icons/lucide/git/trees/main?recursive=1',
+                    rawContentUrl: 'https://raw.githubusercontent.com/lucide-icons/lucide/main/',
+                    pathPrefix: 'icons/'
+                }
+            },
+            parallel: options.parallel ?? false,
+            cache: {
+                enabled: options.cache?.enabled ?? context.target?.cache ?? false,
+                dirPath: Path.combine(getProjectRoot(context), '.cache')
+            }
+        });
+        return { success: true };
+    } catch (error) {
+        console.error(error);
+        return { success: false };
+    }
+}

package/src/executors/icon-collection-downloader/schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "cli": "nx",
+  "title": "Icon Collection Downloader",
+  "description": "Downloads icon collections from all configured providers (Fluent UI, Lucide, etc.)",
+  "type": "object",
+  "properties": {
+    "outDir": {
+      "type": "string",
+      "description": "Output directory for downloaded icons (relative to project root). Each provider will create a subdirectory.",
+      "default": "src/icons"
+    },
+    "parallel": {
+      "type": "boolean",
+      "description": "Execute provider downloads in parallel. Significantly faster but may hit rate limits.",
+      "default": false
+    },
+    "cache": {
+      "type": "object",
+      "description": "Cache configuration",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable caching to avoid re-downloading icons",
+          "default": false
+        }
+      }
+    }
+  },
+  "required": [
+    "outDir"
+  ]
+}