@breadstone-infrastructure/nx-tasks 0.0.257 → 0.0.258

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

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

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

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