@breadstone-infrastructure/nx-tasks 0.0.258 → 0.0.260

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

@@ -1,372 +0,0 @@
-// #region Imports
-
-import { type IResolvedToken, TokenResolver } from '@breadstone-infrastructure/token-linter';
-import { bold, ConsoleLogger, File, gray, green, logSeparator, logSummary, Path, red, StringExtensions } from '@breadstone-infrastructure/utilities';
-import { diffWords } from 'diff';
-import { ComponentDocFixer } from './ComponentDocFixer';
-import { type IJSDocCheckerResult, JSDocChecker } from './JSDocChecker';
-
-// #endregion
-
-export namespace LitDocsTask {
-
-    export interface ILitDocsTaskOptions {
-        cwd: string;
-        files: string | Array<string>;
-        ignore?: Array<string>;
-        verbose?: boolean;
-        validateOrder?: boolean;
-        validateTags?: boolean;
-        fix?: boolean;
-    }
-
-    export async function run(options: ILitDocsTaskOptions): Promise<void> {
-        const logger = new ConsoleLogger();
-
-        logSeparator(logger, 'Analyzing component documentation (Lit)');
-
-        const elementPath = Array.isArray(options.files)
-            ? options.files.map((file) => Path.combine(options.cwd, file))
-            : Path.combine(options.cwd, options.files);
-
-        if (options.verbose) {
-            [...elementPath].forEach((p) => {
-                logger.log(gray(`    Search elements in ${p}`));
-            });
-        }
-
-        return new Promise<void>((resolve) => {
-            const allResults = new Array<{
-                file: string;
-                results: Array<IJSDocCheckerResult>;
-            }>();
-
-            const files = File.glob(elementPath);
-            files.forEach((file) => {
-                if (options.ignore?.includes(Path.getFileNameWithoutExtension(file))) {
-                    return;
-                }
-
-                if (options.verbose) {
-                    logger.log(gray(`    Analyzing ${Path.getFileName(file)}`));
-                }
-
-                const elementFile = file;
-                const templateFile = Path.combine(Path.getDirectoryName(elementFile), Path.getFileNameWithoutExtension(elementFile).concat('Template.ts'));
-                const styleFile = Path.combine(Path.getDirectoryName(elementFile), Path.getFileNameWithoutExtension(elementFile).concat('Style.ts'));
-
-                const tokenFileName = `_${Path.getFileNameWithoutExtension(elementFile)}`
-                    .replace('Element', '')
-                    .concat('.Tokens.scss');
-                const styleTokensFile = Path.combine(options.cwd, '../mosaik-themes/src/Themes/Joy/_Components', tokenFileName);
-
-                // Resolve tokens from the JSON source of truth
-                const componentName = Path.getFileNameWithoutExtension(elementFile).replace('Element', '');
-                const tokenJsonName = StringExtensions.firstCharToLowerCase(componentName) + '.json';
-                const tokenJsonPath = Path.combine(options.cwd, '../mosaik-themes/tokens/themes/joy/components', tokenJsonName);
-                const baseTokensPath = Path.combine(options.cwd, '../mosaik-themes/tokens/themes/components.json');
-                const mixinsDir = Path.combine(options.cwd, '../mosaik-themes/tokens/mixins');
-
-                let resolvedTokens: Array<IResolvedToken> = [];
-                if (File.exists(tokenJsonPath)) {
-                    try {
-                        resolvedTokens = TokenResolver.resolve({ componentFilePath: tokenJsonPath, baseTokensPath, mixinsDir });
-                    } catch (error: unknown) {
-                        const message = error instanceof Error ? error.message : String(error);
-                        logger.log(red(`    [ERROR] Token resolution failed for ${Path.getFileName(file)} (${tokenJsonPath}): ${message}`));
-                        throw error;
-                    }
-                }
-
-                const componentKebab = StringExtensions.toKebabCase(componentName);
-                const cssVarTypes = new Map<string, string>();
-                const resolvedCssVars = resolvedTokens.map((token: IResolvedToken) => {
-                    const varName = `--${componentKebab}-${StringExtensions.toKebabCase(token.key.replace(/\./g, '-'))}`;
-                    if (token.type) {
-                        cssVarTypes.set(varName, token.type);
-                    }
-
-                    return varName;
-                });
-
-                const parts = File.exists(templateFile)
-                    ? TemplateExtractor.extractParts(templateFile).filter((part) => !part.startsWith('_'))
-                    : [];
-                const slots = File.exists(templateFile)
-                    ? TemplateExtractor.extractSlots(templateFile).filter((slot) => !slot.startsWith('_'))
-                    : [];
-                const scssVars = TemplateExtractor.extractCSSVars([styleFile, styleTokensFile])
-                    .filter((cssVar) => !cssVar.startsWith('--_')); // we want to ignore internal CSS variables;
-
-                // Merge SCSS-extracted vars with token-resolved vars, deduplicating
-                const cssVarSet = new Set([...scssVars, ...resolvedCssVars]);
-                const cssVars = Array.from(cssVarSet).filter((cssVar) => !cssVar.startsWith('--_'));
-                const dependencies = File.exists(templateFile)
-                    ? TemplateExtractor.extractDependencies(templateFile)
-                    : [];
-
-                // Usage example
-                const jsDocChecker = new JSDocChecker(elementFile);
-                const results = jsDocChecker.validate(slots, parts, undefined, cssVars, dependencies);
-
-                if (results.length > 0) {
-                    results.forEach((result) => {
-                        if (options.fix) {
-                            const fixResult = ComponentDocFixer.fix(elementFile, result, slots, parts, cssVars, dependencies, cssVarTypes);
-                            if (fixResult === true) {
-                                logger.log(`    ${green('[FIXED]')}: ${bold(Path.getFileName(file))} - documentation reconciled (stale removed, missing added, order fixed).`);
-                            } else {
-                                logger.warn(`    ${red('[SKIP]')}: ${bold(Path.getFileName(file))} - ${fixResult}`);
-                            }
-
-                            return;
-                        }
-
-                        logger.error(`    ${red('[ERROR]')}: ${bold(Path.getFileName(file))} has missing doc tags:`);
-
-                        result.missingTags.forEach((tag) => {
-                            logger.warn(`      - ${bold(`@${tag}`)}`);
-                            switch (tag) {
-                                case 'slot':
-                                    logger.log('        To fix this issue, add the following slots to the class:');
-                                    logger.log(green(`        * ${bold('@slot')} ${result.missingDetails.slot?.join('\n        * @slot ')}`));
-                                    break;
-                                case 'csspart':
-                                    logger.log('        To fix this issue, add the following parts to the class:');
-                                    logger.log(green(`        * ${bold('@csspart')} ${result.missingDetails.csspart?.join('\n        * @csspart ')}`));
-                                    break;
-                                case 'fires':
-                                    logger.log('        To fix this issue, add the following events to the class:');
-                                    logger.log(green(`        * ${bold('@fires')} ${result.missingDetails.fires?.join('\n        * @fires ')}`));
-                                    break;
-                                case 'cssprop':
-                                    logger.log('        To fix this issue, add the following CSS properties to the class:');
-                                    logger.log(green(`        * ${bold('@cssprop')} {unknown} ${result.missingDetails.cssprop?.join('\n        * @cssprop {unknown} ')}`));
-                                    break;
-                                case 'dependency':
-                                    const formattedDependencies = dependencies
-                                        .map((dep) => `${bold('@dependency')} {${dep}} - The ${StringExtensions.humanize(dep.replace('Element', ''))} element.`)
-                                        .join('\n        * ');
-
-                                    logger.log('        To fix this issue, add the following dependencies to the class:');
-                                    logger.log(green(`        * ${formattedDependencies}`));
-                                    break;
-                                case 'description':
-                                case 'name':
-                                case 'element':
-                                case 'category':
-                                case 'example':
-                                case 'public':
-                                default:
-                                    break;
-                            }
-                        });
-
-                        logger.log('    There are some differences between the correct order and the your current order');
-                        logger.log('    Correct order:', result.orderDetails.correctOrder.join(' | '));
-
-                        const diff = diffWords(result.orderDetails.correctOrder.join(' '), result.orderDetails.currentOrder.join(' '));
-                        const output = diff.map((part) => {
-                            const color = part.added ? '\x1b[32m' : part.removed ? '\x1b[31m' : '\x1b[0m';
-                            return `${color + part.value}\x1b[0m`;
-                        }).join(' | ');
-
-                        console.log('    Current order:', output);
-
-                        // logger.log(green('    Correct order:'), result.orderDetails.correctOrder.join(', '));
-                        // logger.log(red('    Current order:'), result.orderDetails.currentOrder.join(', '));
-                        // logger.log('Missing tags:', result.orderDetails.missingTags.join(', '));
-
-                        // Logger.instance().logWarning(`      - ${result.missingTags.join(' | ')}`);
-                        // if (result.missingTags.includes('slot') || result.missingTags.includes('csspart') || result.missingTags.includes('fires') || result.missingTags.includes('cssprop')) {
-
-                        //     Logger.instance().logWarning(`        - details: ${result.missingDetails?.slot?.join(', ')}`);
-
-                        // }
-
-                        logger.log('');
-                    });
-
-                    allResults.push({
-                        file: elementFile,
-                        results: results
-                    });
-                } else {
-
-                    // Logger.instance().logInfo(`    Class ${Path.getFileName(file)} is okay.`, { color: 'green' });
-
-                }
-            });
-
-            // count all errors
-            const count = allResults.reduce((total, x) => {
-                // For each x.results, we reduce to sum up the lengths of missingTags
-                const missingTagsCount = x.results.reduce((sum, y) => sum + y.missingTags.length, 0);
-                return total + missingTagsCount;
-            }, 0);
-
-            logSummary(logger, {
-                error: [`\tFound ${count} errors in ${allResults.length}/${files.length} files.`, count > 0 && !options.fix],
-                success: [`\t${files.length - allResults.length} files are okay.`, true],
-                waring: [`\tFixed ${allResults.length} files with ${count} missing tags.`, options.fix === true && count > 0]
-            });
-
-            resolve();
-        }).catch((error: unknown) => {
-            logger.error('Error during analysis:', error);
-            throw error;
-        })
-            .finally(() => {
-                logSeparator(logger);
-            });
-    }
-}
-
-/**
- * TemplateExtractor is responsible for extracting slot elements or `part` attributes from Lit HTML templates.
- */
-namespace TemplateExtractor {
-
-    /**
-     * Reads the file and processes its contents to extract `part` attributes.
-     */
-    export function extractParts(filePath: string): Array<string> {
-        const fileContent = File.readAllText(filePath, 'utf8');
-        return _extractParts(fileContent);
-    }
-
-    /**
-     * Reads the file and processes its contents to extract slot elements.
-     */
-    export function extractSlots(filePath: string): Array<string> {
-        const fileContent = File.readAllText(filePath, 'utf8');
-        return _extractSlots(fileContent);
-    }
-
-    /**
-     * Reads the file and processes its contents to extract CSS variables.
-     */
-    export function extractCSSVars(filePath: Array<string>): Array<string> {
-        return filePath.flatMap((path) => {
-            if (!File.exists(path)) {
-                return [];
-            }
-
-            const fileContent = File.readAllText(path, 'utf8');
-            return _extractCSSVars(fileContent);
-        });
-    }
-
-    /**
-     * Extracts `mosaik-*` element tag names used in a template file.
-     * These represent the component's dependencies.
-     *
-     * @param filePath - The path to the template file.
-     * @returns An array of unique `mosaik-*` tag names found in the template.
-     */
-    export function extractDependencies(filePath: string): Array<string> {
-        const fileContent = File.readAllText(filePath, 'utf8');
-        return _extractDependencies(fileContent);
-    }
-
-    /**
-     * Extracts `part` attributes from the provided content.
-     * @param content The content of the TypeScript file to be processed.
-     * @returns An array of extracted part names.
-     */
-    function _extractParts(content: string): Array<string> {
-        const partRegex = /part="([^"]+)"/g;
-        const parts = new Set<string>();
-        let match: RegExpExecArray | null = null;
-
-        while ((match = partRegex.exec(content)) !== null) {
-            parts.add(match[1]);
-        }
-
-        return Array.from(parts);
-    }
-
-    /**
-     * Extracts slot elements from the provided content.
-     * @param content The content of the TypeScript file to be processed.
-     * @returns An array of extracted slot names.
-     */
-    function _extractSlots(content: string): Array<string> {
-        const slotRegex = /<slot\b([^>]*)>/g;
-        const nameRegex = /\bname="([^"]+)"/;
-        const slots = new Set<string>();
-        let match: RegExpExecArray | null = null;
-
-        while ((match = slotRegex.exec(content)) !== null) {
-            const nameMatch = nameRegex.exec(match[1]);
-            const slotName = nameMatch ? nameMatch[1] : '';
-            slots.add(slotName);
-        }
-
-        return Array.from(slots);
-    }
-
-    /**
-     * Extracts CSS variables and SCSS map-derived variables like --button-font-family
-     * from given content.
-     *
-     * @param content - The SCSS or TypeScript string to analyze.
-     * @returns An array of variable names in CSS custom property format.
-     */
-    function _extractCSSVars(content: string): Array<string> {
-        const result = new Set<string>();
-
-        // 1. Extract plain CSS custom properties: --foo-bar:
-        const cssVarRegex = /--[\w-]+(?=\s*:)/g;
-        for (const match of content.matchAll(cssVarRegex)) {
-            result.add(match[0]);
-        }
-
-        // 2. Extract SCSS $*-props map blocks and generate --<component>-<key>
-        const propsMapRegex = /\$([\w-]+)-props\s*:\s*\(/g;
-        let match: RegExpExecArray | null = null;
-
-        while ((match = propsMapRegex.exec(content)) !== null) {
-            const component = match[1]; // e.g. "button"
-            const startIdx = match.index + match[0].length;
-            let depth = 1;
-            let endIdx = startIdx;
-
-            // Bracket matching to extract the full map body
-            while (endIdx < content.length && depth > 0) {
-                if (content[endIdx] === '(') { depth++; } else if (content[endIdx] === ')') { depth--; }
-                endIdx++;
-            }
-
-            const mapBody = content.slice(startIdx, endIdx - 1); // exclude final ')'
-
-            // Match entries like: 'font-size': var(--...)
-            const entryRegex = /['"]([\w-]+)['"]\s*:\s*var\(/g;
-            for (const entry of mapBody.matchAll(entryRegex)) {
-                const key = entry[1];
-                result.add(`--${component}-${key}`);
-            }
-        }
-
-        return Array.from(result);
-    }
-
-    /**
-     * Extracts `mosaik-*` element tag names from the provided template content.
-     *
-     * @param content - The content of the template file to be processed.
-     * @returns An array of unique `mosaik-*` tag names.
-     */
-    function _extractDependencies(content: string): Array<string> {
-        const tagRegex = /<(mosaik-[\w-]+)/g;
-        const dependencies = new Set<string>();
-        let match: RegExpExecArray | null = null;
-
-        while ((match = tagRegex.exec(content)) !== null) {
-            dependencies.add(match[1]);
-        }
-
-        return Array.from(dependencies);
-    }
-
-}

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

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

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

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