@breadstone-infrastructure/nx-tasks 0.0.257 → 0.0.258

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

@@ -0,0 +1,353 @@
+/* eslint-disable complexity */
+// #region Imports
+
+import { File } from '@breadstone-infrastructure/utilities';
+import * as ts from 'typescript';
+
+// #endregion
+
+/**
+ * Interface representing the result of a JSDoc check.
+ */
+export interface IJSDocCheckerResult {
+    className: string;
+    missingTags: Array<'description' | 'name' | 'element' | 'category' | 'example' | 'public' | 'slot' | 'csspart' | 'fires' | 'cssprop' | 'dependency'>;
+    missingDetails: {
+        slot?: Array<string>;
+        csspart?: Array<string>;
+        fires?: Array<string>;
+        cssprop?: Array<string>;
+        dependency?: Array<string>;
+    };
+    orderDetails: {
+        currentOrder: Array<string>;
+        correctOrder: Array<string>;
+        missingTags: Array<string>;
+    };
+}
+
+/**
+ * JSDocChecker is responsible for verifying the completeness of JSDoc comments
+ * on TypeScript classes decorated with @Component.
+ */
+export class JSDocChecker {
+
+    private readonly _correctOrder: Array<string>;
+    private readonly _filePath: string;
+
+    /**
+     * Initializes a new instance of the JSDocChecker class.
+     * @param filePath The path to the TypeScript file to be checked.
+     */
+    public constructor(filePath: string) {
+        this._correctOrder = ['description', 'name', 'element', 'category', 'slot', 'csspart', 'cssprop', 'fires', 'dependency', 'example', 'public'];
+        this._filePath = filePath;
+    }
+
+    /**
+     * Validates the JSDoc comments in the TypeScript file against the specified schema.
+     * Ensures that all required tags are present and optional tags are checked if relevant arrays are provided.
+     * @param slots Optional array of slot names to check for.
+     * @param parts Optional array of part names to check for.
+     * @param events Optional array of event names to check for.
+     * @param props Optional array of CSS properties to check for.
+     * @param dependencies Optional array of dependencies to check for.
+     * @returns An array of IJSDocCheckerResult containing class names and missing JSDoc tags.
+     */
+    public validate(
+        slots?: Array<string>,
+        parts?: Array<string>,
+        events?: Array<string>,
+        props?: Array<string>,
+        dependencies?: Array<string>
+    ): Array<IJSDocCheckerResult> {
+        const fileContent = File.readAllText(this._filePath, 'utf8');
+        const sourceFile = ts.createSourceFile(
+            this._filePath,
+            fileContent,
+            ts.ScriptTarget.Latest,
+            true
+        );
+
+        const results: Array<IJSDocCheckerResult> = [];
+
+        const visit = (node: ts.Node) => {
+            if (ts.isClassDeclaration(node)) {
+                const className = node.name?.getText() ?? 'UnnamedClass';
+                const jsDocTags = this.extractJSDocTags(node);
+                const tagKeys = jsDocTags.map((tag) => tag.key);
+
+                // Required tags to check
+                const requiredTags = ['description', 'name', 'element', 'category', 'example', 'public'];
+                const missingRequiredTags = requiredTags.filter((tag) => !tagKeys.includes(tag));
+
+                // Optional tags
+                const missingSlots = slots?.filter((slot) => !jsDocTags.some((tag) => tag.key === 'slot' && tag.value.includes(slot))) ?? [];
+                const missingParts = parts?.filter((part) => !jsDocTags.some((tag) => tag.key === 'csspart' && tag.value.includes(part))) ?? [];
+                const missingEvents = events?.filter((event) => !jsDocTags.some((tag) => tag.key === 'fires' && tag.value.includes(event))) ?? [];
+                const missingProps = props?.filter((prop) => !jsDocTags.some((tag) => tag.key === 'cssprop' && tag.value.includes(prop))) ?? [];
+                const missingDependencies = dependencies?.filter((dep) => !jsDocTags.some((tag) => tag.key === 'dependency' && tag.value.includes(dep))) ?? [];
+
+                const missingTags = [
+                    ...missingRequiredTags,
+                    ...missingSlots.length > 0 ? ['slot'] : [],
+                    ...missingParts.length > 0 ? ['csspart'] : [],
+                    ...missingEvents.length > 0 ? ['fires'] : [],
+                    ...missingProps.length > 0 ? ['cssprop'] : [],
+                    ...missingDependencies.length > 0 ? ['dependency'] : []
+                ] as IJSDocCheckerResult['missingTags'];
+
+                const missingDetails = {
+                    slot: missingSlots.length > 0 ? missingSlots : undefined,
+                    csspart: missingParts.length > 0 ? missingParts : undefined,
+                    fires: missingEvents.length > 0 ? missingEvents : undefined,
+                    cssprop: missingProps.length > 0 ? missingProps : undefined,
+                    dependency: missingDependencies.length > 0 ? missingDependencies : undefined
+                };
+
+                // Check the order of tags
+                const currentOrder = tagKeys;
+                const expectedOrder = this._correctOrder.filter((tag) => currentOrder.includes(tag));
+
+                const orderDetails = {
+                    currentOrder: Array.from(new Set(currentOrder)),
+                    correctOrder: this._correctOrder,
+                    missingTags: new Array<string>()
+                };
+
+                // Check if the order of tags is correct
+                if (expectedOrder.length > 1) {
+                    for (let i = 0; i < expectedOrder.length - 1; i++) {
+                        const currentTag = expectedOrder[i];
+                        const nextTag = expectedOrder[i + 1];
+                        if (currentOrder.indexOf(currentTag) > currentOrder.indexOf(nextTag)) {
+                            orderDetails.missingTags = expectedOrder;
+                            break;
+                        }
+                    }
+                }
+
+                if (missingTags.length > 0 || orderDetails.missingTags.length > 0) {
+                    results.push({
+                        className,
+                        missingTags,
+                        missingDetails,
+                        orderDetails
+                    });
+                }
+            }
+
+            ts.forEachChild(node, visit);
+        };
+
+        visit(sourceFile);
+        return results;
+    }
+
+    /**
+     * Fixes the JSDoc comment of a class declaration node to match the specified schema.
+     *
+     * @param name - The name to use in the JSDoc.
+     * @param element - The element name to use in the JSDoc.
+     * @param category - The category to use in the JSDoc.
+     * @param dependencies - An array of dependencies with their descriptions to be included in the JSDoc.
+     * @param description - The description to use in the JSDoc.
+     * @param slots - An array of slots with their descriptions to be included in the JSDoc.
+     * @param cssparts - An array of cssparts with their descriptions to be included in the JSDoc.
+     * @param cssprops - An array of cssprops with their descriptions to be included in the JSDoc.
+     * @param events - An array of events with their descriptions to be included in the JSDoc.
+     */
+    public fix(
+        name: string,
+        element: string,
+        category: string,
+        dependencies: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }> = [],
+        description: string = 'TBD',
+        slots: Array<{
+            name: string;
+            description: string;
+        }> = [],
+        cssparts: Array<{
+            name: string;
+            description: string;
+        }> = [],
+        cssprops: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }> = [],
+        events: Array<{
+            name: string;
+            description: string;
+        }> = []
+    ): void {
+        const fileContent = File.readAllText(this._filePath, 'utf8');
+        const sourceFile = ts.createSourceFile(
+            this._filePath,
+            fileContent,
+            ts.ScriptTarget.Latest,
+            true
+        );
+
+        const updatedContent: Array<string> = [];
+        const originalContentLines = fileContent.split('\n');
+
+        const visit = (node: ts.Node) => {
+            if (ts.isClassDeclaration(node)) {
+                const correctJSDoc = this.generateCorrectJSDoc(
+                    name,
+                    element,
+                    category,
+                    dependencies,
+                    description,
+                    slots,
+                    cssparts,
+                    cssprops,
+                    events
+                );
+
+                const className = node.name?.getText() ?? 'UnnamedClass';
+                console.log(`Updating JSDoc for class: ${className}`);
+
+                // Insert JSDoc comment right before the class declaration
+                const start = node.getStart(sourceFile);
+                const preClassContent = originalContentLines.slice(0, start).join('\n');
+                const postClassContent = originalContentLines.slice(start).join('\n');
+
+                // Construct updated content
+                updatedContent.push(preClassContent, correctJSDoc, postClassContent);
+            }
+
+            ts.forEachChild(node, visit);
+        };
+
+        visit(sourceFile);
+
+        // This writes the updated content back to the file
+        File.writeAllText(this._filePath, updatedContent.join('\n'), 'utf8');
+    }
+
+    /**
+     * Validates if the tag comment matches a specific format using a regex pattern.
+     *
+     * @param comment - The tag comment to validate.
+     * @param pattern - The regex pattern to match against.
+     * @returns True if the comment matches the pattern, false otherwise.
+     */
+    private validateTagWithSpecificFormat(comment: string | undefined, pattern: RegExp): boolean {
+        if (!comment) {
+            return false;
+        }
+        return pattern.test(comment);
+    }
+
+    /**
+     * Extracts JSDoc tags from the class declaration node.
+     * @param node The class declaration node.
+     * @returns An array of JSDoc tags found in the node.
+     */
+    private extractJSDocTags(node: ts.ClassDeclaration): Array<{
+        key: string;
+        value: string;
+    }> {
+        const jsDocTags: Array<{
+            key: string;
+            value: string;
+        }> = [];
+
+        const jsDocs = (node as any).jsDoc as Array<ts.JSDoc> | undefined;
+        jsDocs?.forEach((jsDoc) => {
+            jsDoc.tags?.forEach((tag) => {
+                jsDocTags.push({
+                    key: tag.tagName.text,
+                    value: tag.comment?.toString() ?? ''
+                });
+            });
+        });
+
+        return jsDocTags;
+    }
+
+    /**
+     * Generates a correct JSDoc comment with the right order of attributes, including dynamic parts.
+     *
+     * @param name - The name to use in the JSDoc.
+     * @param element - The element name to use in the JSDoc.
+     * @param category - The category to use in the JSDoc.
+     * @param dependencies - An array of dependencies with their descriptions to be included in the JSDoc.
+     * @param description - The description to use in the JSDoc. Defaults to "TBD" if not provided.
+     * @param slots - An array of slots with their descriptions to be included in the JSDoc.
+     * @param cssparts - An array of cssparts with their descriptions to be included in the JSDoc.
+     * @param cssprops - An array of cssprops with their descriptions to be included in the JSDoc.
+     * @param events - An array of events with their descriptions to be included in the JSDoc.
+     * @returns A string containing the formatted JSDoc comment.
+     */
+    private generateCorrectJSDoc(
+        name: string,
+        element: string,
+        category: string,
+        dependencies: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }> = [],
+        description: string = 'TBD',
+        slots: Array<{
+            name: string;
+            description: string;
+        }> = [],
+        cssparts: Array<{
+            name: string;
+            description: string;
+        }> = [],
+        cssprops: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }> = [],
+        events: Array<{
+            name: string;
+            description: string;
+        }> = []
+    ): string {
+        // Generate the dynamic parts for slots, cssparts, cssprops, events, and dependencies
+        const slotsSection = slots.map((slot) => ` * @slot ${slot.name} - ${slot.description}`).join('\n');
+        const csspartsSection = cssparts.map((part) => ` * @csspart ${part.name} - ${part.description}`).join('\n');
+        const csspropsSection = cssprops.map((prop) => ` * @cssprop {${prop.type}} ${prop.name} - ${prop.description}`).join('\n');
+        const eventsSection = events.map((event) => ` * @fires ${event.name} - ${event.description}`).join('\n');
+        const dependenciesSection = dependencies.map((dep) => ` * @dependency {${dep.type}} ${dep.name} - ${dep.description}`).join('\n');
+
+        return `
+/**
+ * ${name} - An interactive UI element typically used to trigger actions or user interactions.
+ *
+ * @description
+ * ${description}
+ *
+ * @name ${name}
+ * @element ${element}
+ * @category ${category}
+ *
+${slotsSection}
+ *
+${csspartsSection}
+ *
+${csspropsSection}
+ *
+${eventsSection}
+ *
+${dependenciesSection}
+ *
+ * @example
+ * <${element} label="Button"></${element}>
+ *
+ * @public
+ */
+`.trim();
+    }
+
+}

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

@@ -0,0 +1,10 @@
+// #region Imports
+
+import type { LitDocsTask } from './executor.task';
+
+// #endregion
+
+/**
+ * @public
+ */
+export type LitDocsExecutorOptions = Omit<LitDocsTask.ILitDocsTaskOptions, 'cwd' | 'tsConfigJson' | 'packageJson'>;