@breadstone-infrastructure/nx-tasks 0.0.231 → 0.0.233

package/executors/lit-docs/ComponentDocFixer.js

@@ -0,0 +1,424 @@
+"use strict";
+// #region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComponentDocFixer = void 0;
+const utilities_1 = require("@breadstone-infrastructure/utilities");
+/**
+ * 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
+ */
+class ComponentDocFixer {
+    // #region Fields
+    /**
+     * The canonical order of custom element documentation tags.
+     *
+     * @private
+     */
+    static _TAG_ORDER = [
+        '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
+     */
+    static _TAG_GROUPS = [
+        ['description'],
+        ['name', 'element', 'category'],
+        ['slot'],
+        ['csspart'],
+        ['cssprop'],
+        ['fires'],
+        ['dependency'],
+        ['example'],
+        ['public'],
+    ];
+    /**
+     * Tags that can contain multiple continuation lines (free-form content).
+     *
+     * @private
+     */
+    static _MULTILINE_TAGS = 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
+     */
+    static fix(filePath, result, slots, parts, cssVars, dependencies, cssVarTypes = new Map()) {
+        const content = utilities_1.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);
+        utilities_1.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
+     */
+    static findClassDoc(content, className) {
+        // 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 = null;
+        let currentMatch;
+        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
+     */
+    static parseDocBlock(docText) {
+        const lines = docText.split('\n');
+        const preambleLines = [];
+        const tagSections = [];
+        let currentTag = null;
+        let currentLines = [];
+        let inPreamble = true;
+        const tagPattern = /^\s*\*\s*@(\w+)/;
+        const saveCurrentTag = () => {
+            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
+     */
+    static reconcile(parsed, slots, parts, cssVars, dependencies, cssVarTypes = new Map()) {
+        // Group existing tags by type
+        const tagsByType = new Map();
+        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 = [];
+        // 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
+     */
+    static reconcileTagGroup(tagName, existing, expectedValues, generateLine) {
+        const result = [];
+        const covered = new Set();
+        const tagToValue = new Map();
+        // 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 = { 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
+     */
+    static tagContainsValue(tagText, value, tagName) {
+        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
+     */
+    static rebuildDocBlock(preambleLines, tags) {
+        const sections = [];
+        // Section 0: preamble
+        if (preambleLines.length > 0) {
+            sections.push([...preambleLines]);
+        }
+        // Group tags by their visual group
+        let currentGroupIndex = -1;
+        let currentGroupLines = [];
+        let lastTag = 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 = ['/**'];
+        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
+     */
+    static getTagGroupIndex(tag) {
+        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
+     */
+    static cssVarToDescription(cssVar) {
+        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
+     */
+    static tagNameToDescription(tagName) {
+        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
+     */
+    static tokenTypeToCsspropType(tokenType) {
+        switch (tokenType) {
+            case 'color':
+                return 'Color';
+            case 'number':
+                return 'Number';
+            case 'array':
+                return 'Array';
+            default:
+                return 'String';
+        }
+    }
+}
+exports.ComponentDocFixer = ComponentDocFixer;
+//# sourceMappingURL=ComponentDocFixer.js.map

package/executors/lit-docs/ComponentDocFixer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ComponentDocFixer.js","sourceRoot":"","sources":["../../../src/executors/lit-docs/ComponentDocFixer.ts"],"names":[],"mappings":"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"}

package/executors/lit-docs/JSDocFixer.d.ts

@@ -0,0 +1,97 @@
+import type { IJSDocCheckerResult } from './JSDocChecker';
+/**
+ * Represents the location and text of a JSDoc comment block.
+ *
+ * @public
+ */
+export interface IJSDocMatch {
+    readonly start: number;
+    readonly end: number;
+    readonly jsDocText: string;
+}
+/**
+ * Surgically fixes missing JSDoc tags in component files by inserting
+ * only the missing tags at their correct positions, preserving all existing content.
+ *
+ * @public
+ */
+export declare class JSDocFixer {
+    /**
+     * The canonical order of JSDoc tags for component documentation.
+     *
+     * @private
+     */
+    private static readonly _TAG_ORDER;
+    /**
+     * Fixes missing JSDoc tags in a component file based on validation results.
+     *
+     * @param filePath - The absolute path to the component file to fix.
+     * @param result - The validation result containing missing tags.
+     * @param slots - The full list of expected slots.
+     * @param parts - The full list of expected cssparts.
+     * @param cssVars - The full list of expected CSS custom properties.
+     * @param dependencies - The full list of expected dependencies.
+     * @returns `true` if the file was modified, `false` otherwise.
+     * @public
+     */
+    static fix(filePath: string, result: IJSDocCheckerResult, slots: Array<string>, parts: Array<string>, cssVars: Array<string>, dependencies: Array<string>): boolean;
+    /**
+     * Finds the JSDoc comment block immediately preceding a class declaration.
+     *
+     * @param content - The full file content.
+     * @param className - The class name to find the JSDoc for.
+     * @returns The JSDoc match or `null` if not found.
+     * @private
+     */
+    private static findClassJSDoc;
+    /**
+     * Inserts missing tag lines into the existing JSDoc at correct positions.
+     *
+     * @param lines - The existing JSDoc lines.
+     * @param missingSlots - Lines to insert for missing slots.
+     * @param missingParts - Lines to insert for missing cssparts.
+     * @param missingProps - Lines to insert for missing cssprops.
+     * @param missingEvents - Lines to insert for missing events.
+     * @param missingDeps - Lines to insert for missing dependencies.
+     * @returns The updated lines or `null` if nothing was missing.
+     * @private
+     */
+    private static insertMissingTags;
+    /**
+     * Inserts a group of missing tag lines after existing tags of the same type,
+     * or at the correct position based on tag ordering rules.
+     *
+     * @param lines - The JSDoc lines to mutate.
+     * @param tagName - The tag type to insert (e.g. `slot`, `cssprop`).
+     * @param newLines - The new tag lines to insert.
+     * @private
+     */
+    private static insertTagGroup;
+    /**
+     * Finds the last line index containing a specific JSDoc tag.
+     *
+     * @param lines - The JSDoc lines to search.
+     * @param tagName - The tag name to search for.
+     * @returns The line index or `-1` if not found.
+     * @private
+     */
+    private static findLastTagIndex;
+    /**
+     * Finds the first line index containing a specific JSDoc tag.
+     *
+     * @param lines - The JSDoc lines to search.
+     * @param tagName - The tag name to search for.
+     * @returns The line index or `-1` if not found.
+     * @private
+     */
+    private static findFirstTagIndex;
+    /**
+     * 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;
+}
+//# sourceMappingURL=JSDocFixer.d.ts.map

package/executors/lit-docs/JSDocFixer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JSDocFixer.d.ts","sourceRoot":"","sources":["../../../src/executors/lit-docs/JSDocFixer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAI1D;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IAInB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAIhC;IAMF;;;;;;;;;;;OAWG;WACW,GAAG,CACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EACpB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EACpB,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,EACtB,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,GAC5B,OAAO;IAmDV;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAiB7B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IA8BhC;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IA4C7B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAY/B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAYhC;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;CAYrC"}