@breadstone-infrastructure/nx-tasks 0.0.258 → 0.0.260

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

@@ -1,571 +0,0 @@
-// #region Imports
-
-import { File } from '@breadstone-infrastructure/utilities';
-import type { IJSDocCheckerResult } from './JSDocChecker';
-
-// #endregion
-
-/**
- * Represents the location and text of a component documentation comment block.
- *
- * @public
- */
-export interface IComponentDocMatch {
-    readonly start: number;
-    readonly end: number;
-    readonly docText: string;
-}
-
-/**
- * Represents a single parsed tag occurrence from a documentation block.
- *
- * @public
- */
-export interface IDocTag {
-    readonly tag: string;
-    readonly lines: ReadonlyArray<string>;
-}
-
-/**
- * Represents a fully parsed documentation comment block, split into
- * preamble text and individual tag sections.
- *
- * @public
- */
-export interface IParsedDocBlock {
-    readonly preambleLines: ReadonlyArray<string>;
-    readonly tagSections: ReadonlyArray<IDocTag>;
-}
-
-/**
- * Reconciles component documentation comment blocks with the actual code.
- * Removes stale tags, adds missing tags, and reorders all tags according to
- * the canonical tag order.
- *
- * @public
- */
-export class ComponentDocFixer {
-
-    // #region Fields
-
-    /**
-     * The canonical order of custom element documentation tags.
-     *
-     * @private
-     */
-    private static readonly _TAG_ORDER: ReadonlyArray<string> = [
-        'description', 'name', 'element', 'category',
-        'slot', 'csspart', 'cssprop', 'fires', 'dependency',
-        'example', 'public'
-    ];
-
-    /**
-     * Defines which tags belong to the same visual group in the output.
-     * Tags within a group are consecutive; groups are separated by blank lines.
-     *
-     * @private
-     */
-    private static readonly _TAG_GROUPS: ReadonlyArray<ReadonlyArray<string>> = [
-        ['description'],
-        ['name', 'element', 'category'],
-        ['slot'],
-        ['csspart'],
-        ['cssprop'],
-        ['fires'],
-        ['dependency'],
-        ['example'],
-        ['public'],
-    ];
-
-    /**
-     * Tags that can contain multiple continuation lines (free-form content).
-     *
-     * @private
-     */
-    private static readonly _MULTILINE_TAGS: ReadonlySet<string> = new Set(['description', 'example']);
-
-    // #endregion
-
-    // #region Methods
-
-    /**
-     * Reconciles component documentation tags in a file with the actual code.
-     * Removes stale tags, adds missing tags, and reorders all tags to match
-     * the canonical tag order.
-     *
-     * @param filePath - The absolute path to the component file to fix.
-     * @param result - The validation result containing the class name and missing details.
-     * @param slots - The full list of expected slot names from the template.
-     * @param parts - The full list of expected csspart names from the template.
-     * @param cssVars - The full list of expected CSS custom property names.
-     * @param dependencies - The full list of expected dependency class names.
-     * @param cssVarTypes - Optional map from CSS variable name to token type (e.g. `color`, `time`).
-     * @returns `true` if the file was modified, or a failure reason string.
-     * @public
-     */
-    public static fix(
-        filePath: string,
-        result: IJSDocCheckerResult,
-        slots: Array<string>,
-        parts: Array<string>,
-        cssVars: Array<string>,
-        dependencies: Array<string>,
-        cssVarTypes: Map<string, string> = new Map()
-    ): true | string {
-        const content = File.readAllText(filePath, 'utf8');
-
-        const docMatch = this.findClassDoc(content, result.className);
-        if (!docMatch) {
-            return `Could not locate a documentation comment block (/** ... */) before class '${result.className}'. ` +
-                `The file may use a complex @Component() decorator that the regex cannot parse.`;
-        }
-
-        const { start, end, docText } = docMatch;
-        const parsed = this.parseDocBlock(docText);
-        const reconciled = this.reconcile(parsed, slots, parts, cssVars, dependencies, cssVarTypes);
-        const rebuilt = this.rebuildDocBlock(parsed.preambleLines, reconciled);
-
-        if (rebuilt === docText) {
-            return `Documentation comment for class '${result.className}' is already correct after reconciliation.`;
-        }
-
-        const updatedContent = content.substring(0, start) + rebuilt + content.substring(end);
-        File.writeAllText(filePath, updatedContent, 'utf8');
-
-        return true;
-    }
-
-    /**
-     * Finds the documentation comment block immediately preceding a class declaration.
-     * Searches backwards from the class keyword to find the nearest doc block,
-     * ensuring it does not accidentally match a doc block for a different declaration.
-     *
-     * @param content - The full file content.
-     * @param className - The class name to find the documentation for.
-     * @returns The doc match or `null` if not found.
-     * @private
-     */
-    private static findClassDoc(content: string, className: string): IComponentDocMatch | null {
-        // Find the class declaration position
-        const classPattern = new RegExp(
-            `export\\s+(?:abstract\\s+)?class\\s+${className}\\b`
-        );
-        const classMatch = classPattern.exec(content);
-
-        if (!classMatch) {
-            return null;
-        }
-
-        // Search backwards from the class declaration for the nearest /** ... */ block.
-        // Only consider the content before the class keyword.
-        const contentBeforeClass = content.substring(0, classMatch.index);
-        const docBlockPattern = /\/\*\*[\s\S]*?\*\//g;
-        let lastDocMatch: RegExpExecArray | null = null;
-        let currentMatch: RegExpExecArray | null;
-
-        while ((currentMatch = docBlockPattern.exec(contentBeforeClass)) !== null) {
-            lastDocMatch = currentMatch;
-        }
-
-        if (!lastDocMatch) {
-            return null;
-        }
-
-        // Verify there are no other declarations (interface, class, type, enum, function)
-        // between the doc block end and the class declaration.
-        const betweenContent = contentBeforeClass.substring(lastDocMatch.index + lastDocMatch[0].length);
-        const declarationPattern = /\b(?:export\s+)?(?:interface|class|type|enum|function)\s+\w+/;
-
-        if (declarationPattern.test(betweenContent)) {
-            return null;
-        }
-
-        const docText = lastDocMatch[0];
-        const start = lastDocMatch.index;
-        const end = start + docText.length;
-
-        return { start, end, docText };
-    }
-
-    /**
-     * Parses a raw documentation comment block into structured preamble and tag sections.
-     *
-     * @param docText - The raw documentation comment text including opening and closing markers.
-     * @returns The parsed representation with preamble lines and tag sections.
-     * @private
-     */
-    private static parseDocBlock(docText: string): IParsedDocBlock {
-        const lines = docText.split('\n');
-        const preambleLines: Array<string> = [];
-        const tagSections: Array<IDocTag> = [];
-
-        let currentTag: string | null = null;
-        let currentLines: Array<string> = [];
-        let inPreamble = true;
-
-        const tagPattern = /^\s*\*\s*@(\w+)/;
-
-        const saveCurrentTag = (): void => {
-            if (currentTag !== null && currentLines.length > 0) {
-                // Strip trailing blank comment lines
-                while (currentLines.length > 0 && currentLines[currentLines.length - 1].trim() === '*') {
-                    currentLines.pop();
-                }
-
-                if (currentLines.length > 0) {
-                    tagSections.push({ tag: currentTag, lines: [...currentLines] });
-                }
-            }
-
-            currentLines = [];
-        };
-
-        for (const line of lines) {
-            const trimmed = line.trim();
-
-            if (trimmed === '/**' || trimmed === '*/') {
-                continue;
-            }
-
-            const tagMatch = tagPattern.exec(line);
-
-            if (tagMatch) {
-                saveCurrentTag();
-                inPreamble = false;
-                currentTag = tagMatch[1];
-                currentLines = [line];
-            } else if (inPreamble) {
-                preambleLines.push(line);
-            } else if (currentTag !== null) {
-                const isBlank = trimmed === '*' || trimmed === '';
-
-                if (!isBlank || ComponentDocFixer._MULTILINE_TAGS.has(currentTag)) {
-                    currentLines.push(line);
-                }
-            }
-        }
-
-        saveCurrentTag();
-
-        // Strip trailing blank lines from preamble
-        while (preambleLines.length > 0 && preambleLines[preambleLines.length - 1].trim() === '*') {
-            preambleLines.pop();
-        }
-
-        return { preambleLines, tagSections };
-    }
-
-    /**
-     * Reconciles parsed tag sections with the expected values from the actual code.
-     * Removes stale tags, adds missing tags, and orders everything canonically.
-     *
-     * @param parsed - The parsed documentation block.
-     * @param slots - The expected slot names.
-     * @param parts - The expected csspart names.
-     * @param cssVars - The expected CSS custom property names.
-     * @param dependencies - The expected dependency class names.
-     * @param cssVarTypes - Map from CSS variable name to token type.
-     * @returns The reconciled and ordered tag list.
-     * @private
-     */
-    private static reconcile(
-        parsed: IParsedDocBlock,
-        slots: Array<string>,
-        parts: Array<string>,
-        cssVars: Array<string>,
-        dependencies: Array<string>,
-        cssVarTypes: Map<string, string> = new Map()
-    ): Array<IDocTag> {
-        // Group existing tags by type
-        const tagsByType = new Map<string, Array<IDocTag>>();
-
-        for (const section of parsed.tagSections) {
-            const group = tagsByType.get(section.tag);
-
-            if (group) {
-                group.push(section);
-            } else {
-                tagsByType.set(section.tag, [section]);
-            }
-        }
-
-        const result: Array<IDocTag> = [];
-
-        // Emit tags in canonical order
-        for (const tag of ComponentDocFixer._TAG_ORDER) {
-            const existing = tagsByType.get(tag) ?? [];
-
-            switch (tag) {
-                case 'slot':
-                    result.push(...this.reconcileTagGroup(
-                        'slot', existing, slots,
-                        (value) => ` * @slot ${value} - The ${value || 'default'} slot.`
-                    ));
-                    break;
-                case 'csspart':
-                    result.push(...this.reconcileTagGroup(
-                        'csspart', existing, parts,
-                        (value) => ` * @csspart ${value} - The ${value} part.`
-                    ));
-                    break;
-                case 'cssprop':
-                    result.push(...this.reconcileTagGroup(
-                        'cssprop', existing, cssVars,
-                        (value) => ` * @cssprop {${this.tokenTypeToCsspropType(cssVarTypes.get(value))}} ${value} - The ${this.cssVarToDescription(value)} CSS custom property.`
-                    ));
-                    break;
-                case 'dependency':
-                    result.push(...this.reconcileTagGroup(
-                        'dependency', existing, dependencies,
-                        (value) => ` * @dependency ${value} - The ${this.tagNameToDescription(value)} element.`
-                    ));
-                    break;
-                default:
-                    // Non-reconcilable tags (description, name, element, category, fires, example, public): keep as-is
-                    result.push(...existing);
-                    break;
-            }
-        }
-
-        // Preserve unknown tags not in _TAG_ORDER
-        for (const [tag, sections] of tagsByType.entries()) {
-            if (!ComponentDocFixer._TAG_ORDER.includes(tag)) {
-                result.push(...sections);
-            }
-        }
-
-        return result;
-    }
-
-    /**
-     * Reconciles a single tag group against the expected values.
-     * Keeps existing tags that match an expected value, removes stale ones,
-     * and adds new tags for uncovered values.
-     *
-     * @param tagName - The tag type being reconciled.
-     * @param existing - The existing tags of this type from the doc block.
-     * @param expectedValues - The expected values from the actual code.
-     * @param generateLine - A factory to produce new tag lines for missing values.
-     * @returns The reconciled tags: preserved originals first, then newly generated ones.
-     * @private
-     */
-    private static reconcileTagGroup(
-        tagName: string,
-        existing: Array<IDocTag>,
-        expectedValues: Array<string>,
-        generateLine: (value: string) => string
-    ): Array<IDocTag> {
-        const result: Array<IDocTag> = [];
-        const covered = new Set<string>();
-        const tagToValue = new Map<IDocTag, string>();
-
-        // Keep existing tags that match an expected value
-        for (const tag of existing) {
-            const tagText = tag.lines.join(' ');
-            let matched = false;
-
-            for (const value of expectedValues) {
-                if (!covered.has(value) && this.tagContainsValue(tagText, value, tagName)) {
-                    covered.add(value);
-                    matched = true;
-                    tagToValue.set(tag, value);
-                    break;
-                }
-            }
-
-            if (matched) {
-                result.push(tag);
-            }
-        }
-
-        // Add new tags for uncovered expected values
-        for (const value of expectedValues) {
-            if (!covered.has(value)) {
-                const tag: IDocTag = { tag: tagName, lines: [generateLine(value)] };
-                tagToValue.set(tag, value);
-                result.push(tag);
-            }
-        }
-
-        // Sort alphabetically; empty string (default slot) always first
-        result.sort((a, b) => {
-            const valueA = tagToValue.get(a) ?? '';
-            const valueB = tagToValue.get(b) ?? '';
-
-            if (valueA === '' && valueB !== '') {
-                return -1;
-            }
-
-            if (valueA !== '' && valueB === '') {
-                return 1;
-            }
-
-            return valueA.localeCompare(valueB);
-        });
-
-        return result;
-    }
-
-    /**
-     * Checks whether a tag text contains a specific expected value using
-     * precise matching to avoid substring false positives.
-     *
-     * @param tagText - The concatenated text of the tag lines.
-     * @param value - The expected value to look for.
-     * @param tagName - The tag type for context-aware matching.
-     * @returns `true` if the tag documents the given value.
-     * @private
-     */
-    private static tagContainsValue(tagText: string, value: string, tagName: string): boolean {
-        if (value === '') {
-            // Default/unnamed slot: matches @slot - description (no name before the dash)
-            if (tagName === 'slot') {
-                return /\*\s*@slot\s+-\s/.test(tagText) || /\*\s*@slot\s*$/.test(tagText);
-            }
-
-            return true;
-        }
-
-        const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-        // CSS variables: exact match with non-word-hyphen lookahead
-        if (value.startsWith('--')) {
-            return new RegExp(`${escaped}(?![\\w-])`).test(tagText);
-        }
-
-        // Identifiers: exact match with word-boundary-like checks
-        return new RegExp(`(?<![\\w-])${escaped}(?![\\w-])`).test(tagText);
-    }
-
-    /**
-     * Rebuilds a documentation comment block from preamble and ordered tag sections.
-     * Groups tags visually according to the tag group definitions and separates
-     * groups with blank comment lines.
-     *
-     * @param preambleLines - The preamble text lines.
-     * @param tags - The ordered tag sections.
-     * @returns The complete documentation comment string.
-     * @private
-     */
-    private static rebuildDocBlock(
-        preambleLines: ReadonlyArray<string>,
-        tags: ReadonlyArray<IDocTag>
-    ): string {
-        const sections: Array<Array<string>> = [];
-
-        // Section 0: preamble
-        if (preambleLines.length > 0) {
-            sections.push([...preambleLines]);
-        }
-
-        // Group tags by their visual group
-        let currentGroupIndex = -1;
-        let currentGroupLines: Array<string> = [];
-        let lastTag: string | null = null;
-
-        for (const tag of tags) {
-            const groupIndex = this.getTagGroupIndex(tag.tag);
-
-            if (groupIndex !== currentGroupIndex && currentGroupLines.length > 0) {
-                sections.push(currentGroupLines);
-                currentGroupLines = [];
-            }
-
-            // Separate consecutive multiline tags (e.g. @example) with a blank line
-            if (tag.tag === lastTag && ComponentDocFixer._MULTILINE_TAGS.has(tag.tag)) {
-                currentGroupLines.push(' *');
-            }
-
-            currentGroupLines.push(...tag.lines);
-            currentGroupIndex = groupIndex;
-            lastTag = tag.tag;
-        }
-
-        if (currentGroupLines.length > 0) {
-            sections.push(currentGroupLines);
-        }
-
-        // Join sections with ' *' separators
-        const output: Array<string> = ['/**'];
-
-        for (let i = 0; i < sections.length; i++) {
-            if (i > 0) {
-                output.push(' *');
-            }
-
-            output.push(...sections[i]);
-        }
-
-        output.push(' */');
-
-        return output.join('\n');
-    }
-
-    /**
-     * Gets the visual group index for a tag type.
-     *
-     * @param tag - The tag type.
-     * @returns The group index, or `-1` for unknown tags.
-     * @private
-     */
-    private static getTagGroupIndex(tag: string): number {
-        return ComponentDocFixer._TAG_GROUPS.findIndex((group) => group.includes(tag));
-    }
-
-    /**
-     * Generates a human-readable description from a CSS variable name.
-     *
-     * @param cssVar - The CSS variable name (e.g. `--button-font-family`).
-     * @returns A human-readable description.
-     * @private
-     */
-    private static cssVarToDescription(cssVar: string): string {
-        const segments = cssVar.replace(/^--/, '').split('-');
-
-        if (segments.length <= 1) {
-            return cssVar;
-        }
-
-        return segments.slice(1).join(' ');
-    }
-
-    /**
-     * Converts a `mosaik-*` tag name to a human-readable description.
-     *
-     * @param tagName - The tag name (e.g. `mosaik-fab`).
-     * @returns A human-readable description (e.g. `Fab`).
-     * @private
-     */
-    private static tagNameToDescription(tagName: string): string {
-        return tagName
-            .replace(/^mosaik-/, '')
-            .split('-')
-            .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
-            .join(' ');
-    }
-
-    /**
-     * Maps a token type from the JSON definition to the PascalCase type
-     * used in `@cssprop` annotations.
-     *
-     * @param tokenType - The token type from the JSON (e.g. `color`, `time`).
-     * @returns The PascalCase type for the `@cssprop` tag (e.g. `Color`, `String`).
-     * @private
-     */
-    private static tokenTypeToCsspropType(tokenType: string | undefined): string {
-        switch (tokenType) {
-            case 'color':
-                return 'Color';
-            case 'number':
-                return 'Number';
-            case 'array':
-                return 'Array';
-            default:
-                return 'String';
-        }
-    }
-
-    // #endregion
-
-}
-