@playcanvas/attribute-parser 1.6.1 → 1.7.1

package/src/index.js

@@ -1,273 +0,0 @@
-import { createSystem, createDefaultMapFromNodeModules, createVirtualTypeScriptEnvironment } from '@typescript/vfs';
-import * as ts from 'typescript';
-
-import { ScriptParser } from './parsers/script-parser.js';
-import { isInterface, isStaticMember } from './utils/attribute-utils.js';
-import { createDefaultMapFromCDN, flatMapAnyNodes, getExportedNodes, getType, inheritsFrom, isAliasedClassDeclaration } from './utils/ts-utils.js';
-
-const toLowerCamelCase = str => str[0].toLowerCase() + str.substring(1);
-
-const COMPILER_OPTIONS = {
-    noLib: true,
-    strict: false,
-    skipLibCheck: true, // Skip type checking of declaration files
-    target: ts.ScriptTarget.ES2023, // If this version changes, the types must be updated in the /rollup.config.mjs
-    module: ts.ModuleKind.CommonJS,
-    checkJs: true, // Enable JSDoc parsing
-    allowJs: true,
-    baseUrl: './',
-    paths: {
-        'playcanvas': ['/playcanvas.js']
-    }
-};
-
-export class JSDocParser {
-    /**
-     * @type {import('@typescript/vfs').VirtualTypeScriptEnvironment}
-     * @private
-     */
-    _env;
-
-    /**
-     * An internal array of program errors
-     * @private
-     */
-    _errors = [];
-
-    /**
-     * Initializes the JSDocParser with the standard library files
-     *
-     * @param {string} libPath - A path to a directory of library types, or a path to the '.d.ts' file itself
-     * @returns {Promise<JSDocParser>} - The initialized JSDocParser
-     */
-    async init(libPath) {
-        if (this._env) {
-            return this;
-        }
-
-        let fsMap;
-        if (!libPath) {
-
-            // This is a node only option. If no lib path is passed, attempt to resolve ES types from node_modules.
-            fsMap = await createDefaultMapFromNodeModules(COMPILER_OPTIONS, ts);
-
-        } else if (libPath.endsWith('.d.ts')) {
-
-            // If the libPath is a '.d.ts' file then load it and add it
-            const types = await fetch(libPath).then(r => r.text());
-            fsMap = new Map([['/lib.d.ts', types]]);
-
-        } else {
-
-            // A libPath was supplied, but not to a '.d.ts', so assume this is a path to types
-            fsMap = await createDefaultMapFromCDN(COMPILER_OPTIONS, libPath, ts);
-        }
-
-        // Set up the virtual file system and environment
-        const system = createSystem(fsMap);
-        this._env = createVirtualTypeScriptEnvironment(system, Array.from(fsMap.keys()), ts, COMPILER_OPTIONS);
-
-        return this;
-    }
-
-    /**
-     * Creates program from fileName and scriptsContents
-     *
-     * @param {[string, string][]} newFiles - An array of {[path]: [content]} which represent the files in the program
-     * @param {string[]} removedFiles - An array of file paths that should be removed from the program
-     * @returns {{ parser: ScriptParser, program: ts.Program,
-     * errors: import('./parsers/script-parser.js').ValidationError[]}} - The extracted attributes
-     */
-    updateProgram(newFiles = [], removedFiles = []) {
-        const errors = [];
-
-        // Add custom files to the map
-        newFiles.forEach(([filePath, fileContent]) => {
-            if (this._env.getSourceFile(filePath)) {
-                this._env.updateFile(filePath, fileContent);
-            } else {
-                this._env.createFile(filePath, fileContent);
-            }
-        });
-
-        // Remove deleted Files
-        removedFiles.forEach((filePath) => {
-            this._env.deleteFile(filePath);
-        });
-
-
-        this.parser = new ScriptParser(this._env);
-        this.program = this._env.languageService.getProgram();
-
-        // Check for compiler errors
-        this.parser.validateProgram(errors);
-
-        this._errors = errors;
-
-        return errors;
-    }
-
-    /**
-     * Returns all the valid ESM Scripts within a file
-     * @param {string} fileName - The file name in the program to check
-     * @returns {Map<string, import('typescript').Node>} - A map of valid ESM Script <names, nodes> within the file
-     */
-    getAllEsmScripts(fileName) {
-
-        const typeChecker = this.program.getTypeChecker();
-
-        // Find the Script class in the PlayCanvas namespace
-        const pcTypes = this.program.getSourceFile('/playcanvas.d.ts');
-
-        if (!pcTypes) {
-            throw new Error('PlayCanvas Types must be supplied');
-        }
-
-        const esmScripts = new Map();
-
-        // Parse the source file and pc types
-        const sourceFile = this.program.getSourceFile(fileName);
-
-        // In a special edge case where the files contents are empty, the sourcefile will be undefined
-        // So we should early out
-        if (sourceFile === undefined) {
-            return esmScripts;
-        }
-
-        if (sourceFile === null) {
-            throw new Error(`Source file ${fileName} not found`);
-        }
-
-        // Extract all exported nodes
-        const nodes = getExportedNodes(this.program, sourceFile);
-
-        const esmScriptClass = pcTypes.statements.find(node => node.kind === ts.SyntaxKind.ClassDeclaration && node.name.text === 'Script')?.symbol;
-
-        const isScriptNameMember = member => (
-            ts.isPropertyDeclaration(member) && // Is a property declaration
-            ts.isIdentifier(member.name) &&
-            member.name.text === 'scriptName' &&
-            isStaticMember(member) &&
-            ts.isStringLiteral(member.initializer)
-        );
-
-        // Check if the file exports a class that inherits from `Script`
-        nodes.forEach((node, name) => {
-            if (isAliasedClassDeclaration(node, typeChecker) && inheritsFrom(node, typeChecker, esmScriptClass)) {
-
-                // Check for a static scriptName property and use that as the name if it exists
-                const scriptNameMember = node.members.find(isScriptNameMember);
-
-                // If the scriptName property exists, use that as the name
-                if (scriptNameMember) {
-                    name = scriptNameMember.initializer.text;
-                }
-
-                esmScripts.set(name, node);
-            }
-        });
-
-        return esmScripts;
-    }
-
-    /**
-     * Analyzes the specified TypeScript file and extracts metadata from JSDoc comments.
-     *
-     * @param {string} fileName - The name of the file in the program to run
-     * @returns {[results: object, errors: import('./parsers/script-parser.js').ValidationError[]]} - The extracted attributes
-     */
-    parseAttributes(fileName) {
-        const results = {};
-        const errors = [...this._errors];
-
-        if (errors.length > 0) {
-            return [results, errors];
-        }
-
-        // Extract all exported nodes
-        const nodes = this.getAllEsmScripts(fileName);
-
-        // Extract attributes from each script
-        nodes.forEach((node, name) => {
-            const opts = results[toLowerCamelCase(name)] = { attributes: {}, errors: [] };
-            this.parser.extractAttributes(node, opts);
-        });
-
-        return [results, errors];
-    }
-
-    /**
-     * Analyzes the specified TypeScript file and extracts metadata from JSDoc comments.
-     * @param {string} fileName - The name of the file to run
-     * @returns {[results: object, errors: import('./parsers/script-parser.js').ValidationError[]]} - The extracted attributes
-     */
-    getAttributes(fileName) {
-        const results = {};
-        const errors = [...this._errors];
-
-        if (errors.length > 0) {
-            return [results, errors];
-        }
-
-        const typeChecker = this.program.getTypeChecker();
-
-        // Find the Script class in the PlayCanvas namespace
-        const pcTypes = this.program.getSourceFile('/playcanvas.d.ts');
-        const esmScriptClass = pcTypes.statements.find(node => node.kind === ts.SyntaxKind.ClassDeclaration && node.name.text === 'Script')?.symbol;
-
-        // Parse the source file and pc types
-        const sourceFile = this.program.getSourceFile(fileName);
-
-        if (!sourceFile) {
-            throw new Error(`Source file ${fileName} not found`);
-        }
-
-        const nodes = flatMapAnyNodes(sourceFile, (node) => {
-            if (!ts.isClassDeclaration(node)) {
-                return false;
-            }
-
-            return inheritsFrom(node, typeChecker, esmScriptClass) || isInterface(node);
-        });
-
-        for (const node of nodes) {
-            const name = toLowerCamelCase(node.name.text);
-            const members = [];
-
-            for (const member of node.members) {
-                if (member.kind !== ts.SyntaxKind.PropertyDeclaration || isStaticMember(member)) {
-                    continue;
-                }
-
-                // Extract JSDoc tags
-                const tags = member.jsDoc ? member.jsDoc.map(jsdoc => jsdoc.tags?.map(tag => tag.tagName.getText()) ?? []).flat() : [];
-
-                const name = member.name.getText();
-                const type = getType(member, typeChecker);
-                if (!type) {
-                    continue;
-                }
-
-                const namePos = ts.getLineAndCharacterOfPosition(member.getSourceFile(), member.name.getStart());
-
-                const jsdocNode = member.jsDoc && member.jsDoc[member.jsDoc.length - 1];
-                const jsdocPos = jsdocNode ? ts.getLineAndCharacterOfPosition(member.getSourceFile(), jsdocNode.getStart()) : null;
-
-                const data = {
-                    name,
-                    type: type.name + (type.array ? '[]' : ''),
-                    isAttribute: tags.includes('attribute'),
-                    start: jsdocNode ? { line: jsdocPos.line + 1, column: jsdocPos.character + 1 } :
-                        { line: namePos.line + 1, column: namePos.character + 1 },
-                    end: { line: namePos.line + 1, column: namePos.character + name.length + 1 }
-                };
-
-                members.push(data);
-            }
-
-            results[name] = members;
-        }
-
-        return [results, errors];
-    }
-}

package/src/parsers/attribute-parser.js

@@ -1,197 +0,0 @@
-import * as ts from 'typescript';
-
-import { ParsingError } from './parsing-error.js';
-import { hasTag } from '../utils/attribute-utils.js';
-import { parseTag, validateTag } from '../utils/tag-utils.js';
-import { getLiteralValue, getType } from '../utils/ts-utils.js';
-
-/**
- * A class to parse JSDoc comments and extract attribute metadata.
- */
-export class AttributeParser {
-    /**
-     * Creates a new instance of the ScriptParser class.
-     *
-     * @param {Map<string, string>} tags - An set of tag definitions and their validators to add to the parser
-     * @param {object} env - The TypeScript environment to use
-     * @param {Map<string, Function>} typeSerializerMap - A map of custom serializers
-     */
-    constructor(tags = new Map(), env, typeSerializerMap) {
-
-        this.env = env;
-        this.tagTypeAnnotations = tags;
-        this.typeSerializerMap = typeSerializerMap;
-        this.program = env.languageService.getProgram();
-        this.typeChecker = this.program.getTypeChecker();
-
-    }
-
-    /**
-     * Parses a JSdoc comment and extracts any associated metadata if the `@attribute`
-     * modifier is used. Returns null if this is not an attribute comment.
-     *
-     * @param {ts.Node} node - The node to parse
-     * @param {ParsingError[]} errors - An array to store any parsing errors
-     * @param {boolean} requiresAttributeTag - Whether the comment must have an attribute tag
-     * @returns {*} - The extracted metadata or null if no metadata was found
-     */
-    parseAttributeComment(node, errors = [], requiresAttributeTag = true) {
-
-        // Check if the comment has an attribute tag
-        if (!requiresAttributeTag || hasTag('attribute', node)) {
-
-            // Fetch the primary attribute metadata
-            const attribute = this.getNodeAsAttribute(node, errors);
-
-            if (!attribute) return;
-
-            // Extract the description from the summary section
-            attribute.description = node.jsDoc?.[0]?.comment || '';
-
-            // Extract metadata from custom tags
-            const jsDocTags = node.jsDoc?.[0]?.tags ?? [];
-            jsDocTags.forEach((tag) => {
-                let commentText = tag.comment;
-
-                // Check if the tag is a supported tag
-                if (this.tagTypeAnnotations.has(tag.tagName.text)) {
-                    try {
-                        const value = parseTag(commentText);
-                        const tagTypeAnnotation = this.tagTypeAnnotations.get(tag.tagName.text);
-
-                        // Tags like @resource with string values do not need quotations, so we need to manually add them
-                        if (typeof value === 'string') commentText = `"${commentText}"`;
-
-                        validateTag(commentText, tagTypeAnnotation, this.env);
-                        attribute[tag.tagName.text] = value;
-
-                    } catch (error) {
-                        const file = node.getSourceFile();
-                        const { line, character } = file.getLineAndCharacterOfPosition(tag.getStart());
-                        const parseError = new ParsingError(tag, `Error (${line}, ${character}): Parsing Tag '@${tag.tagName.text} ${commentText}' - ${error.message}`);
-                        errors.push(parseError);
-                    }
-                }
-            });
-
-            return attribute;
-        }
-    }
-
-    /**
-     * Extract the public members and their values from a TypeScript node.
-     *
-     * @param {ts.Node} node - The node to parse
-     * @param {ParsingError[]} errors - An array to store any parsing errors
-     * @returns {*} - The extracted members
-     */
-    getNodeAsAttribute(node, errors = []) {
-
-        const name = node.name && ts.isIdentifier(node.name) && node.name.text;
-        const { type, name: typeName, array } = getType(node, this.typeChecker);
-        const enums = this.getEnumMembers(node, errors);
-        let value = null;
-
-        // we don't need to serialize the value for arrays
-        const serializer = !array && this.typeSerializerMap.get(typeName);
-        if (serializer) {
-            try {
-                value = serializer(node.initializer ?? node, this.typeChecker);
-            } catch (error) {
-                errors.push(error);
-                return;
-            }
-        }
-
-        return { type, name, typeName, array, value, enum: enums };
-    }
-
-    /**
-     * Extracts the members of an enum from a TypeScript node.
-     *
-     * @param {import('typescript').Node} node - The TypeScript node to analyze
-     * @param {ParsingError[]} errors - An array to store any parsing errors
-     * @returns {Object<string, *>[]} - An array of enum members
-     */
-    getEnumMembers(node, errors) {
-        let typeNode = null;
-        let members = [];
-
-        // Check if there's a type annotation directly on the variable declaration
-        if (node.type) {
-            typeNode = node;
-        } else {
-            // Check for JSDoc annotations
-            const jsDocs = ts.getJSDocTags(node);
-            const typeTag = jsDocs.find(doc => doc.tagName.text === 'type');
-            if (typeTag && ts.isJSDocTypeTag(typeTag)) {
-                typeNode = typeTag.typeExpression;
-            }
-        }
-
-        // Also consider the elementType
-        const type = typeNode && (typeNode.type.elementType ?? typeNode.type);
-
-        if (typeNode && ts.isTypeReferenceNode(type)) {
-
-            // resolve the symbol of the type
-            let symbol = this.typeChecker.getSymbolAtLocation(type.typeName);
-
-            // Resolve aliases, which are common with imports
-            if (symbol && symbol.flags & ts.SymbolFlags.Alias) {
-                symbol = this.typeChecker.getAliasedSymbol(symbol);
-            }
-
-            if (symbol) {
-                const declarations = symbol.getDeclarations();
-
-                if (declarations && declarations.length > 0) {
-
-                    declarations.forEach((declaration) => {
-
-                        // Check if the declaration is a TypeScript enum
-                        if (ts.isEnumDeclaration(declaration)) {
-                            members = declaration.members.map(member => ({ [member.name.text]: member.initializer.text }));
-                        }
-
-                        // Additionally check for JSDoc enum tag
-                        const jsDocs = ts.getJSDocTags(declaration);
-                        const enumTag = jsDocs.find(doc => doc.tagName.text === 'enum');
-                        if (enumTag && ts.isJSDocEnumTag(enumTag)) {
-                            // This assumes enum members are correctly annotated in JSDoc comments
-                            // Example: @enum {type} EnumName { Member1, Member2 }
-                            members = members.concat(this.getMembers(declaration.initializer, errors)); // declaration.initializer.properties.map(member => member.name.getText());
-                        }
-                    });
-                }
-            }
-        }
-
-        return members;
-    }
-
-    /**
-     * Extract the public members and their values from a TypeScript node.
-     *
-     * @param {ts.Node} node - The node to parse
-     * @returns {any[]} - The extracted members
-     */
-    getMembers(node) {
-
-        const members = [];
-
-        if (ts.isObjectLiteralExpression(node)) {
-            node.properties.forEach((property) => {
-
-                if (ts.isPropertyAssignment(property)) {
-                    const isValidName = ts.isIdentifier(property.name) || ts.isStringLiteral(property.name);
-                    const name = isValidName && property.name.text;
-                    const value = getLiteralValue(property.initializer, this.typeChecker);
-                    members.push({ [name]: value });
-                }
-            });
-        }
-
-        return members;
-    }
-}

package/src/parsers/parsing-error.js

@@ -1,14 +0,0 @@
-export class ParsingError {
-    constructor(node, message) {
-        this.node = node;        // AST node which caused the error
-        this.message = message;  // Description of the error
-    }
-
-    toString() {
-        // Ensure node.location exists and has the necessary properties
-        const file = this.node.getSourceFile();
-        const fileName = file.fileName;
-        const start = this.node.getSourceFile().getLineAndCharacterOfPosition(this.node.getStart());
-        return `ParsingError: ${this.message} at ${fileName}:${start.line + 1}:${start.character}`;
-    }
-}