@breadstone-infrastructure/nx-tasks 0.0.257 → 0.0.258

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

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