@playcanvas/attribute-parser 1.3.2 → 1.4.0

package/package.json

@@ -5,9 +5,8 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "version": "1.3.2",
+  "version": "1.4.0",
   "dependencies": {
-    "@microsoft/tsdoc": "^0.15.0",
     "@playcanvas/eslint-config": "^1.7.4 || ^2.0.0",
     "@typescript/vfs": "^1.6.0",
     "eslint": "^8.56.0 || ^9.0.0",

package/rollup.config.js

@@ -0,0 +1,33 @@
+import commonjs from '@rollup/plugin-commonjs';
+import resolve from '@rollup/plugin-node-resolve';
+import swc from '@rollup/plugin-swc';
+
+export default {
+    input: 'src/index.js',
+    treeshake: { moduleSideEffects: false },
+    // Mark 'typescript' as external, so it won’t get bundled
+    // external: ['typescript'],
+    output: {
+        dir: 'dist',
+        format: 'esm'
+    },
+    plugins: [
+        commonjs({
+            include: /node_modules/,
+            ignoreGlobal: true,
+            sourceMap: false
+        }),
+        resolve({
+            browser: true, // This instructs the plugin to resolve for the browser
+            preferBuiltins: false // Prefer the local versions of built-ins instead of Node.js versions
+        }),
+        swc({ swc: {
+            minify: true,
+            jsc: {
+                minify: {
+                    compress: true
+                }
+            }
+        } })
+    ]
+};

package/src/parsers/attribute-parser.js

@@ -1,10 +1,9 @@
-import { TSDocConfiguration, TSDocTagDefinition, TSDocTagSyntaxKind, TextRange, TSDocParser } from '@microsoft/tsdoc';
 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 { extractTextFromDocNode, getLeadingBlockCommentRanges, getLiteralValue, getType } from '../utils/ts-utils.js';
+import { getLiteralValue, getType } from '../utils/ts-utils.js';
 
 /**
  * A class to parse JSDoc comments and extract attribute metadata.
@@ -25,44 +24,18 @@ export class AttributeParser {
         this.program = env.languageService.getProgram();
         this.typeChecker = this.program.getTypeChecker();
 
-        this.attributeTag = new TSDocTagDefinition({
-            tagName: '@attribute', syntaxKind: TSDocTagSyntaxKind.ModifierTag
-        });
-
-        this.typeTag = new TSDocTagDefinition({
-            tagName: '@type', syntaxKind: TSDocTagSyntaxKind.BlockTag
-        });
-
-        const conf = new TSDocConfiguration();
-        conf.validation.reportUnsupportedTags = false;
-
-        conf.addTagDefinition(this.attributeTag);
-
-        tags.forEach((_, tag) => {
-            const tagDefinition = new TSDocTagDefinition({
-                tagName: `@${tag}`, syntaxKind: TSDocTagSyntaxKind.BlockTag, allowMultiple: false
-            });
-            conf.addTagDefinition(tagDefinition);
-        });
-
-        this.parser = new TSDocParser(conf);
     }
 
     /**
      * 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 {TextRange} comment - The comment to parse
      * @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(comment, node, errors = [], requiresAttributeTag = true) {
-
-        const parserContext = this.parser.parseRange(comment);
-        const docComment = parserContext.docComment;
-        const file = node.getSourceFile();
+    parseAttributeComment(node, errors = [], requiresAttributeTag = true) {
 
         // Check if the comment has an attribute tag
         if (!requiresAttributeTag || hasTag('attribute', node)) {
@@ -73,7 +46,7 @@ export class AttributeParser {
             if (!attribute) return;
 
             // Extract the description from the summary section
-            const description = extractTextFromDocNode(docComment.summarySection);
+            const description = node.jsDoc[0].comment;
             if (description) {
                 attribute.description = description.split('.')[0];
             }
@@ -96,6 +69,7 @@ export class AttributeParser {
                         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);
@@ -107,51 +81,6 @@ export class AttributeParser {
         }
     }
 
-    /**
-     * Returns the leading block comments for an typescript AST node.
-     *
-     * @param {import('typescript').Node} node - The node to parse
-     * @param {string[]} errors - An array to store any parsing errors
-     * @returns {import('@microsoft/tsdoc').DocComment} - The extracted doc comment;
-     */
-    getCommentsForNode(node, errors = []) {
-        const fullText = node.getSourceFile().getFullText();
-        const comments = getLeadingBlockCommentRanges(node, fullText);
-
-        if (comments.length === 0) return null;
-
-        const lastComment = comments[0];
-        const textRange = TextRange.fromStringRange(fullText, lastComment.pos, lastComment.end);
-
-        const parserContext = this.parser.parseRange(textRange);
-        const docComment = parserContext.docComment;
-
-        // Check for comment parsing errors and flag them
-        this.populateErrors(node, parserContext, errors);
-
-        return docComment;
-    }
-
-    /**
-     * Populates the errors array with any parsing errors found in the parser context.
-     *
-     * @param {import('typescript').Node} node - The node to parse
-     * @param {import('@microsoft/tsdoc').ParserContext} parserContext - The parser context to check for errors
-     * @param {string[]} errors - An array to store any parsing errors
-     */
-    populateErrors(node, parserContext, errors) {
-        if (parserContext.log.messages.length > 0) {
-            const sourceFile = node.getSourceFile();
-
-            const formattedErrors = parserContext.log.messages.map((message) => {
-                const location = sourceFile.getLineAndCharacterOfPosition(message.textRange.pos);
-                return `${sourceFile.fileName}(${location.line + 1},${location.character + 1}): [TSDoc] ${message}`;
-            });
-
-            errors.push(...formattedErrors);
-        }
-    }
-
     /**
      * Extract the public members and their values from a TypeScript node.
      *

package/src/parsers/script-parser.js

@@ -1,11 +1,10 @@
-import { TextRange } from '@microsoft/tsdoc';
 import * as ts from 'typescript';
 
 import { AttributeParser } from './attribute-parser.js';
 import { ParsingError } from './parsing-error.js';
 import { hasTag } from '../utils/attribute-utils.js';
 import { zipArrays } from '../utils/generic-utils.js';
-import { flatMapAnyNodes, getJSDocCommentRanges, getLiteralValue, parseArrayLiteral, parseFloatNode } from '../utils/ts-utils.js';
+import { flatMapAnyNodes, getJSDocTags, getLiteralValue, parseArrayLiteral, parseFloatNode } from '../utils/ts-utils.js';
 
 /**
  * @typedef {object} Attribute
@@ -148,7 +147,9 @@ const SUPPORTED_BLOCK_TAGS = new Map([
     ['size', 'number'],
     ['step', 'number'],
     ['title', 'string'],
-    ['default', 'any']
+    ['default', 'any'],
+    ['enabledif', 'any'],
+    ['visibleif', 'any']
 ]);
 
 /**
@@ -203,6 +204,16 @@ const mapAttributesToOutput = (attribute) => {
         delete attribute.default;
     }
 
+    // enabledif is in a {}, so strip it out
+    if (attribute.enabledif?.startsWith('{') && attribute.enabledif?.endsWith('}')) {
+        attribute.enabledif = attribute.enabledif.slice(1, -1);
+    }
+
+    // enabledif is in a {}, so strip it out
+    if (attribute.visibleif?.startsWith('{') && attribute.visibleif?.endsWith('}')) {
+        attribute.visibleif = attribute.visibleif.slice(1, -1);
+    }
+
     // remove typeName from the output
     delete attribute.typeName;
     delete attribute.value;
@@ -322,17 +333,14 @@ export class ScriptParser {
         }
 
         // Find "/** */" style comments associated with this node.
-        const comments = getJSDocCommentRanges(node, this.typeChecker);
+        const members = getJSDocTags(node, this.typeChecker);
 
         // Parse the comments for attribute metadata
-        for (const comment of comments) {
-
-            const memberFileText = comment.member.getSourceFile().getFullText();
+        for (const { member, memberName } of members) {
 
             // Parse the comment for attribute metadata
             const attributeMetadata = this.attributeParser.parseAttributeComment(
-                TextRange.fromStringRange(memberFileText, comment.range.pos, comment.range.end),
-                comment.member,
+                member,
                 errors,
                 requiresAttributeTag
             );
@@ -341,11 +349,11 @@ export class ScriptParser {
             if (attributeMetadata) {
 
                 const { type, typeName } = attributeMetadata;
-                const initializer = comment.member?.initializer;
+                const initializer = member?.initializer;
 
                 if (typeName === 'any') {
 
-                    const error = new ParsingError(comment.member, `The attribute "${comment.memberName}" is not initialized and does not have a @type tag.`);
+                    const error = new ParsingError(member, `The attribute "${memberName}" is not initialized and does not have a @type tag.`);
                     errors.push(error);
                     continue;
 
@@ -369,7 +377,7 @@ export class ScriptParser {
 
                     // Check if the type is a valid interface
                     if (!isInitialized && !typeIsInterface && !typeIsJSDocTypeDef && !isJSDocTypeLiteral) {
-                        const error = new ParsingError(comment.member, `Attribute "${comment.memberName}" is an invalid type.`);
+                        const error = new ParsingError(member, `Attribute "${memberName}" is an invalid type.`);
                         errors.push(error);
                         continue;
                     }
@@ -408,7 +416,7 @@ export class ScriptParser {
                 }
 
                 // Add the attribute to the list of found attributes
-                attributes[comment.memberName] = mapAttributesToOutput(attributeMetadata);
+                attributes[memberName] = mapAttributesToOutput(attributeMetadata);
 
             }
         }

package/src/utils/attribute-utils.js

@@ -4,10 +4,10 @@
 
 
 /**
- * Returns a tsdoc tag from a JSDoc comment.
+ * Returns a jsdoc tag from a JSDoc comment.
  * @param {string} tag - The tag to search for
  * @param {import('typescript').Node} doc - The JSDoc comment node
- * @returns {import('@microsoft/tsdoc').DocNode | null} - The tag node
+ * @returns {import('typescript').Node} | null} - The tag node
  */
 export const getTagFromJsdoc = (tag, doc) => {
     return doc?.tags?.find(doc => doc.tagName.text === tag);
@@ -42,29 +42,3 @@ export const hasTag = (tag, node) => {
 export const isInterface = (node) => {
     return hasTag('interface', node);
 };
-
-// /**
-//  * Parses a type tag in the format "{type}".
-//  * @param {import('@microsoft/tsdoc').DocSection} content - The content of the tag.
-//  * @param {object} metadata - An object to store the extracted metadata.
-//  * @param {{ node: import('typescript').Node, env: tsdoc.Environment, errors: string[] }} opts - Additional parser options
-//  * @returns {{ type: import('typescript').Type | null, array: boolean | null }} - The extracted type and array flag.
-//  */
-// export function parseTypeTag(content, metadata, { node, env, errors }) {
-
-//     // Extract the full source text of the original file
-//     const originalSourceText = node.getSourceFile().getFullText();
-//     const typeString = extractTextFromDocNode(content);
-//     const sourceText = `${originalSourceText}\nlet a: ${typeString};`;
-
-//     env.createFile("/virtual.ts", sourceText);
-
-//     const updatedProgram = env.languageService.getProgram();
-//     const newTypeChecker = updatedProgram.getTypeChecker();
-
-//     const sourceFile = updatedProgram.getSourceFile('/virtual.ts');
-
-//     const variableStatement = sourceFile.statements[sourceFile.statements.length - 1];
-//     const variableDeclaration = variableStatement.declarationList.declarations[0];
-//     return getType(variableDeclaration, newTypeChecker);
-// }

package/src/utils/ts-utils.js

@@ -1,4 +1,3 @@
-import { DocNodeKind } from '@microsoft/tsdoc';
 import { knownLibFilesForCompilerOptions } from '@typescript/vfs';
 import * as ts from 'typescript';
 
@@ -205,10 +204,10 @@ function getSuperClasses(node, typeChecker) {
  * @param {import('typescript').Node} node - The TypeScript node to analyze
  * @param {string} text - The full text content of the source file
  * @param {import('typescript').TypeChecker} typeChecker - The TypeScript type checker
- * @returns {{ memberName: string, member: ts.Node, range: import('typescript').CommentRange}[]} - An array of comment ranges
+ * @returns {{ memberName: string, member: Node, range: import('typescript').CommentRange}[]} - An array of comment ranges
  */
-export function getJSDocCommentRanges(node, typeChecker) {
-    const commentRanges = [];
+export function getJSDocTags(node, typeChecker) {
+    const tags = [];
 
     if (ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node)) {
         // get an array of the class an all parent classed
@@ -221,12 +220,11 @@ export function getJSDocCommentRanges(node, typeChecker) {
             classNode.members.forEach((member) => {
                 if (ts.isPropertyDeclaration(member) || ts.isSetAccessor(member) || ts.isPropertySignature(member)) {
                     const memberName = member.name && ts.isIdentifier(member.name) ? member.name.text : 'unnamed';
-                    const ranges = getLeadingBlockCommentRanges(member, member.getSourceFile().getFullText());
-                    if (ranges.length > 0) {
-                        commentRanges.push({
+                    const hasJsDoc = member.jsDoc?.length > 0;
+                    if (hasJsDoc) {
+                        tags.push({
                             memberName,
-                            member,
-                            range: ranges[0]
+                            member
                         });
                     }
                 }
@@ -234,62 +232,7 @@ export function getJSDocCommentRanges(node, typeChecker) {
         });
     }
 
-    return commentRanges;
-}
-
-const ASTERISK = 42;
-const SLASH = 47;
-
-/**
- * Retrieves the JSDoc-style comments blocks associated with a specific AST node.
- * @param {import('typescript').Node} node - The TypeScript node to analyze
- * @param {string} text - The full text content of the source file
- * @returns {import('typescript').CommentRange[]} - An array of comment ranges
- */
-export function getLeadingBlockCommentRanges(node, text) {
-    const ranges = ts.getLeadingCommentRanges(text, node.getFullStart()) ?? [];
-    return ranges.filter(({ pos }) => {
-        return (
-            text.charCodeAt(pos + 1) === ASTERISK &&
-            text.charCodeAt(pos + 2) === ASTERISK &&
-            text.charCodeAt(pos + 3) !== SLASH
-        );
-    });
-}
-
-/**
- * Recursively extract text content from a DocNode.
- * @param {tsdoc.DocNode} node - The DocNode from which to extract text.
- * @returns {string} - The concatenated string of all text content.
- */
-export function extractTextFromDocNode(node) {
-    // Check if the current node is a PlainText node
-    if (node.kind === DocNodeKind.PlainText) {
-        return node.text.trim(); // Cast and return as we found a PlainText node
-    }
-
-    // If not, recursively search its children
-    for (const child of node.getChildNodes()) {
-        const result = extractTextFromDocNode(child);
-        if (result !== null) {
-            return result; // Return the first PlainText node found in the subtree
-        }
-    }
-
-    return null;
-}
-
-/**
- * Extracts all imports from a TypeScript source file.
- * @param {ts.Node} node - The TypeScript node to analyze
- * @returns {string[]} - An array of import statements
- */
-export function getLeadingComments(node) {
-    const fullText = node.getFullText();
-    const commentRanges = ts.getLeadingCommentRanges(fullText, 0);
-
-    if (!commentRanges) return [];
-    return commentRanges.map(range => fullText.slice(range.pos, range.end));
+    return tags;
 }
 
 /**
@@ -343,7 +286,7 @@ export function getPrimitiveEnumType(type, typeChecker) {
  *
  * @param {ts.Node} node - The TypeScript node to analyze
  * @param {ts.TypeChecker} typeChecker - The TypeScript type checker
- * @returns {{ array: boolean, name: string | undefined, type: ts.Type | null }} - The inferred type of the node
+ * @returns {{ array: boolean, name: string | undefined, type: Type | null }} - The inferred type of the node
  */
 export function getType(node, typeChecker) {
     if (node?.name?.kind === ts.SyntaxKind.Identifier) {
@@ -565,11 +508,11 @@ const evaluatePrefixUnaryExpression = (node, typeChecker) => {
 function handleObjectLiteral(node, typeChecker) {
     const obj = {};
     node.properties.forEach((prop) => {
-        if (ts.isPropertyAssignment(prop)) {
+        if  (ts.isPropertyAssignment(prop)) {
             const key = prop.name.getText();
             const value = getLiteralValue(prop.initializer, typeChecker);
             obj[key] = value;
-        } else if (ts.isShorthandPropertyAssignment(prop)) {
+        } else if  (ts.isShorthandPropertyAssignment(prop)) {
             const key = prop.name.getText();
             const value = resolveIdentifier(prop.name, typeChecker);
             obj[key] = value;
@@ -632,7 +575,7 @@ export function getLiteralValue(node, typeChecker) {
  */
 export const parseStringNode = (node) => {
     if (node.kind !== ts.SyntaxKind.StringLiteral) {
-        if (ts.isPropertyAssignment(node.parent) || ts.isPropertyDeclaration(node.parent)) {
+        if  (ts.isPropertyAssignment(node.parent) || ts.isPropertyDeclaration(node.parent)) {
             throw new ParsingError(node, `"${node.parent.getText()}" must be defined with a string literal.`);
         }
         return '';
@@ -642,7 +585,7 @@ export const parseStringNode = (node) => {
 
 export const parseArrayLiteralNode = (node, isArgument = false) => {
     if (node.kind !== ts.SyntaxKind.ArrayLiteralExpression) {
-        if (ts.isPropertyAssignment(node.parent) || ts.isPropertyDeclaration(node.parent) || isArgument) {
+        if  (ts.isPropertyAssignment(node.parent) || ts.isPropertyDeclaration(node.parent) || isArgument) {
             throw new ParsingError(node, `"${node.parent.getText()}" must be defined with an array literal.`);
         }
         return [];

package/test/fixtures/conditional.valid.js

@@ -0,0 +1,22 @@
+import { Script } from 'playcanvas';
+
+class Example extends Script {
+    /**
+     * @attribute
+     * @visibleif {b === 2}
+     */
+    a = 1;
+
+    /**
+     * @attribute
+     * @enabledif {a === 3}
+     */
+    b = 1;
+
+    /**
+     * @attribute
+     */
+    c = 1;
+}
+
+export { Example };

package/test/tests/valid/conditional.test.js

@@ -0,0 +1,45 @@
+import { expect } from 'chai';
+import { describe, it, before } from 'mocha';
+
+import { parseAttributes } from '../../utils.js';
+
+describe('VALID: Conditional Tags', function () {
+    let data;
+    before(async function () {
+        data = await parseAttributes('./conditional.valid.js');
+    });
+
+    it('only results should exist', function () {
+        expect(data).to.exist;
+        expect(data[0]).to.not.be.empty;
+        expect(data[1]).to.be.empty;
+    });
+
+    it('Example: should exist without errors', function () {
+        expect(data[0]?.example).to.exist;
+        expect(data[0].example.attributes).to.not.be.empty;
+        expect(data[0].example.errors).to.be.empty;
+    });
+
+    it('a: should conditional `@visibleif` tag', function () {
+        expect(data[0].example.attributes.a).exist;
+        expect(data[0].example.attributes.a.name).to.equal('a');
+        expect(data[0].example.attributes.a.type).to.equal('number');
+        expect(data[0].example.attributes.a.visibleif).to.equal('b === 2');
+    });
+
+    it('b: should conditional `@enabledif` tag', function () {
+        expect(data[0].example.attributes.b).exist;
+        expect(data[0].example.attributes.b.name).to.equal('b');
+        expect(data[0].example.attributes.b.type).to.equal('number');
+        expect(data[0].example.attributes.b.enabledif).to.equal('a === 3');
+    });
+
+    it('c: should not include `@enabledif` or `@visibleif` tag if none is declared', function () {
+        expect(data[0].example.attributes.c).exist;
+        expect(data[0].example.attributes.c.name).to.equal('c');
+        expect(data[0].example.attributes.c.type).to.equal('number');
+        expect(data[0].example.attributes.c.enabledif).to.not.exist;
+        expect(data[0].example.attributes.c.visibleif).to.not.exist;
+    });
+});