@breadstone-infrastructure/nx-tasks 0.0.258 → 0.0.260

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

@@ -1,353 +0,0 @@
-/* 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

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