@playcanvas/attribute-parser 1.5.1 → 1.6.0

package/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup Node.js 18.x
         uses: actions/setup-node@v4
         with:
-          node-version: 18.x
+          node-version: 22.x
           cache: 'npm'
 
       - name: Install dependencies
@@ -39,7 +39,7 @@ jobs:
       - name: Setup Node.js 18.x
         uses: actions/setup-node@v4
         with:
-          node-version: 18.x
+          node-version: 22.x
           cache: 'npm'
 
       - name: Install dependencies

package/README.md

@@ -1,59 +1,55 @@
 # PlayCanvas Attribute Parser
 
-This the official JSDoc attribute parser used in the PlayCanvas editor. 
+This is the official JSDoc attribute parser used in the PlayCanvas Editor.
 
-It's used in the PlayCanvas Editor to collect metadata from jsdoc annotated users scripts. This allows special `@attribute` members which can surface contextual data about class members.
+It collects metadata from user scripts by parsing `@attribute` JSDoc annotations. These attributes enable the PlayCanvas Editor to expose UI controls and contextual information for your script properties.
 
-## A quick examples
+Example
 
-It takes a script like this...
+Given a script like this:
 
 ```javascript
 class Rotator extends ScriptType {
   /**
    * @attribute
-   * Speed determines how fast to rotate things"
+   * Speed determines how fast to rotate things
    */
-   speed = new Vec3()
-
-   /**
-    * @attribute
-    *  An array of Entities to rotate
-    * 
-    * @type {Entity[]}
-    */
-   thingsToRotate
+  speed = new Vec3();
+
+  /**
+   * @attribute
+   * An array of Entities to rotate
+   *
+   * @type {Entity[]}
+   */
+  thingsToRotate;
 }
 ```
 
-and turns it into the following data ...
+The parser outputs:
 
 
 ```json
 {
-    "rotator": {
-        "attributes": {
-            "speed": {
-                "type": "vec3",
-                "name": "speed",
-                "array": false,
-                "description": "Speed determines how fast to rotate things\"",
-                "default": [
-                    0,
-                    0,
-                    0
-                ]
-            },
-            "thingsToRotate": {
-                "type": "entity",
-                "name": "thingsToRotate",
-                "array": true,
-                "description": "An array of Entities to rotate",
-                "default": null
-            }
-        },
-        "errors": []
-    }
+  "rotator": {
+    "attributes": {
+      "speed": {
+        "type": "vec3",
+        "name": "speed",
+        "array": false,
+        "description": "Speed determines how fast to rotate things",
+        "default": [0, 0, 0]
+      },
+      "thingsToRotate": {
+        "type": "entity",
+        "name": "thingsToRotate",
+        "array": true,
+        "description": "An array of Entities to rotate",
+        "default": null
+      }
+    },
+    "errors": []
+  }
 }
 ```
 
@@ -63,26 +59,26 @@ JSDocs tags are parsed and values and outputs the metadata in a serializable for
 
 ```javascript
 // Initialise the parser
+// Initialize the parser
 const parser = new JSDocParser();
 await parser.init();
 
-// fetch your program source {[filename: string, contents: string][]}
+// Load your source files: {[filename: string]: string}[]
 const scripts = await fetchScripts([...paths, './playcanvas.d.ts']);
 
-// update the progam
-parser.updateProgram(scripts)
+// Update the parser program
+parser.updateProgram(scripts);
 
-// Parse the program, starting from the first path
-const [attribute, errors] parser.parseAttributes("./index.js");
+// Parse attributes from the entry point
+const [attributes, errors] = parser.parseAttributes("./index.js");
 ```
 
 ### Attribute structure
 
-You can learn more about the special tags [available here ](https://github.com/playcanvas/attribute-parser/tree/main/test/fixtures)
-
+See the [test fixtures](https://github.com/playcanvas/attribute-parser/tree/main/test/fixtures) for examples of supported JSDoc tags and output formats.
 
 ### Tests
 
-We provide good coverage
+This project includes good test coverage for all supported tag formats and edge cases.
 
 

package/package.json

@@ -5,7 +5,7 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "version": "1.5.1",
+  "version": "1.6.0",
   "dependencies": {
     "@playcanvas/eslint-config": "^1.7.4 || ^2.0.0",
     "@typescript/vfs": "^1.6.0",

package/src/index.js

@@ -143,9 +143,26 @@ export class JSDocParser {
 
         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' &&
+            (ts.getCombinedModifierFlags(member) & ts.ModifierFlags.Static) !== 0 &&
+            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);
             }
         });

package/src/parsers/attribute-parser.js

@@ -46,10 +46,7 @@ export class AttributeParser {
             if (!attribute) return;
 
             // Extract the description from the summary section
-            const description = node.jsDoc[0].comment;
-            if (description) {
-                attribute.description = description.split('.')[0];
-            }
+            attribute.description = node.jsDoc?.[0]?.comment || '';
 
             // Extract metadata from custom tags
             const jsDocTags = node.jsDoc?.[0]?.tags ?? [];

package/src/parsers/script-parser.js

@@ -186,6 +186,12 @@ const mapAttributesToOutput = (attribute) => {
         attribute.type = 'rgba';
     }
 
+    // 'resource' type needs to be mapped to 'assetType'
+    if (attribute.resource) {
+        attribute.assetType = attribute.resource;
+        delete attribute.resource;
+    }
+
     // remove enum if it's empty
     if (attribute.enum.length === 0) delete attribute.enum;
 
@@ -388,9 +394,9 @@ export class ScriptParser {
                         Array.from(type.symbol.members).map(arr => arr[1].declarations[0]) ??  // a typedefs property declarations
                         [];
 
-                    // If the type is an interface, we need to parse the attribute comments, if not, just the intitialized object
+                    // If the type is an interface or an initialized object, we need to parse the attribute comments, if not, just the intitialized object
                     let commentAttributes;
-                    if (typeIsInterface) {
+                    if (typeIsInterface || isInitialized) {
                         commentAttributes = this.extractAttributes(typeNode, { errors, requiresAttributeTag: false, depth: depth + 1 });
                     }
 

package/src/utils/ts-utils.js

@@ -209,6 +209,7 @@ function getSuperClasses(node, typeChecker) {
 export function getJSDocTags(node, typeChecker) {
     const tags = [];
 
+    // check if class interface of initialized object
     if (ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node)) {
         // get an array of the class an all parent classed
         const heritageChain = getSuperClasses(node, typeChecker)
@@ -240,6 +241,23 @@ export function getJSDocTags(node, typeChecker) {
                 }
             });
         });
+    } else if (ts.isObjectLiteralExpression(node)) {
+        // Handle object literals
+        node.properties.forEach((property) => {
+            if (ts.isPropertyAssignment(property)) {
+                const memberName = property.name &&
+                    (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ?
+                    property.name.text :
+                    'unnamed';
+
+                if (property.jsDoc?.length > 0) {
+                    tags.push({
+                        memberName,
+                        member: property
+                    });
+                }
+            }
+        });
     }
 
     return tags;

package/test/fixtures/json.valid.js

@@ -6,6 +6,7 @@ import { Script, Vec3 } from 'playcanvas';
 // eslint-disable-next-line
 class Folder {
     /**
+     * This is some description of the attribute.
      * @attribute
      * @type {boolean}
      */
@@ -13,6 +14,7 @@ class Folder {
 
     /**
      * @attribute
+     * @range [10, 20]
      */
     b = 10;
 
@@ -64,7 +66,14 @@ class Example extends Script {
     /**
      * @attribute
      */
-    i = { a: true, b: 10, c: 'hello', d: [new Vec3(1, 2, 3)] };
+    i = {
+        /** description of a */
+        a: true,
+        /** @range [10, 20] */
+        b: 10,
+        c: 'hello',
+        d: [new Vec3(1, 2, 3)]
+    };
 
     /**
      * @typedef {object} TypeDefFolder

package/test/fixtures/json.valid.ts

@@ -2,6 +2,7 @@ import { Script, Vec3 } from 'playcanvas';
 
 interface Folder {
     /**
+     * This is some description of the attribute.
      * @attribute
      */
     a: boolean;
@@ -9,6 +10,7 @@ interface Folder {
     /**
      * @attribute
      * @default 10
+     * @range [10, 20]
      */
     b: number;
 
@@ -54,7 +56,14 @@ class Example extends Script {
     /**
      * @attribute
      */
-    i = { a: true, b: 10, c: 'hello', d: [new Vec3(1, 2, 3)] };
+    i = {
+        /** description of a */
+        a: true,
+        /** @range [10, 20] */
+        b: 10,
+        c: 'hello',
+        d: [new Vec3(1, 2, 3)]
+    };
 
     /**
      * @attribute

package/test/fixtures/misc.valid.js

@@ -2,7 +2,9 @@ import { Script } from 'playcanvas';
 
 class Example extends Script {
     /**
-     * This is a description of the attribute.
+     * This is a description of the attribute. It can be multi-sentence.
+     *
+     * And multi-line too
      *
      * @attribute
      * @type {number}

package/test/fixtures/program.valid.js

@@ -6,6 +6,8 @@ import { Script } from 'playcanvas';
 export const MyEnum = { value: 0 };
 
 class Example extends Script {
+    static scriptName = 'customExample';
+
     /**
      * @attribute
      * @precision 1

package/test/tests/invalid/asset.test.js

@@ -26,7 +26,7 @@ describe('INVALID: Asset attribute', function () {
         expect(data[0].example.attributes.a.name).to.equal('a');
         expect(data[0].example.attributes.a.type).to.equal('asset');
         expect(data[0].example.attributes.a.default).to.not.exist;
-        expect(data[0].example.attributes.a.resource).to.not.exist;
+        expect(data[0].example.attributes.a.assetType).to.not.exist;
     });
 
     it('b: should fallback to an asset attribute without resource', function () {
@@ -34,7 +34,7 @@ describe('INVALID: Asset attribute', function () {
         expect(data[0].example.attributes.b.name).to.equal('b');
         expect(data[0].example.attributes.b.type).to.equal('asset');
         expect(data[0].example.attributes.b.default).to.not.exist;
-        expect(data[0].example.attributes.b.resource).to.not.exist;
+        expect(data[0].example.attributes.b.assetType).to.not.exist;
     });
 
     it('c: should fallback to an asset attribute without resource', function () {
@@ -42,6 +42,6 @@ describe('INVALID: Asset attribute', function () {
         expect(data[0].example.attributes.c.name).to.equal('c');
         expect(data[0].example.attributes.c.type).to.equal('asset');
         expect(data[0].example.attributes.c.default).to.not.exist;
-        expect(data[0].example.attributes.c.resource).to.not.exist;
+        expect(data[0].example.attributes.c.assetType).to.not.exist;
     });
 });

package/test/tests/valid/asset.test.js

@@ -40,7 +40,7 @@ function runTests(fileName) {
             expect(data[0].example.attributes.b.type).to.equal('asset');
             expect(data[0].example.attributes.b.array).to.equal(false);
             expect(data[0].example.attributes.b.default).to.equal(null);
-            expect(data[0].example.attributes.b.resource).to.equal('texture');
+            expect(data[0].example.attributes.b.assetType).to.equal('texture');
         });
 
         it('c: should be a asset attribute array with a container resource', function () {
@@ -49,7 +49,7 @@ function runTests(fileName) {
             expect(data[0].example.attributes.c.type).to.equal('asset');
             expect(data[0].example.attributes.c.array).to.equal(true);
             expect(data[0].example.attributes.c.default).to.equal(null);
-            expect(data[0].example.attributes.c.resource).to.equal('container');
+            expect(data[0].example.attributes.c.assetType).to.equal('container');
         });
 
     });

package/test/tests/valid/json.test.js

@@ -37,12 +37,15 @@ describe('JS: VALID: Asset attribute', function () {
         expect(data[0].example.attributes.f.schema[0].type).to.equal('boolean');
         expect(data[0].example.attributes.f.schema[0].array).to.equal(false);
         expect(data[0].example.attributes.f.schema[0].default).to.equal(false);
+        expect(data[0].example.attributes.f.schema[0].description).to.equal('This is some description of the attribute.');
     });
 
     it('f[b]: should be a numeric attribute', function () {
         expect(data[0].example.attributes.f.schema[1].name).to.equal('b');
         expect(data[0].example.attributes.f.schema[1].type).to.equal('number');
         expect(data[0].example.attributes.f.schema[1].array).to.equal(false);
+        expect(data[0].example.attributes.f.schema[1].min).to.equal(10);
+        expect(data[0].example.attributes.f.schema[1].max).to.equal(20);
         expect(data[0].example.attributes.f.schema[1].default).to.equal(10);
     });
 
@@ -100,6 +103,22 @@ describe('JS: VALID: Asset attribute', function () {
         expect(data[0].example.attributes.i.schema).to.exist;
     });
 
+    it('i[a]: should be a boolean attribute', function () {
+        expect(data[0].example.attributes.i.schema[0].name).to.equal('a');
+        expect(data[0].example.attributes.i.schema[0].type).to.equal('boolean');
+        expect(data[0].example.attributes.i.schema[0].array).to.equal(false);
+        expect(data[0].example.attributes.i.schema[0].default).to.equal(true);
+        expect(data[0].example.attributes.i.schema[0].description).to.equal('description of a');
+    });
+
+    it('i[b]: should be a numeric attribute', function () {
+        expect(data[0].example.attributes.i.schema[1].name).to.equal('b');
+        expect(data[0].example.attributes.i.schema[1].type).to.equal('number');
+        expect(data[0].example.attributes.i.schema[1].array).to.equal(false);
+        expect(data[0].example.attributes.i.schema[1].min).to.equal(10);
+        expect(data[0].example.attributes.i.schema[1].max).to.equal(20);
+    });
+
     it('j: should be a typedef json attribute', function () {
         expect(data[0].example.attributes.j).to.exist;
         expect(data[0].example.attributes.j.name).to.equal('j');
@@ -184,6 +203,7 @@ describe('TS: VALID: Asset attribute', function () {
         expect(data[0].example.attributes.f.schema[0].type).to.equal('boolean');
         expect(data[0].example.attributes.f.schema[0].array).to.equal(false);
         expect(data[0].example.attributes.f.schema[0].default).to.equal(false);
+        expect(data[0].example.attributes.f.schema[0].description).to.equal('This is some description of the attribute.');
     });
 
     it('f[b]: should be a numeric attribute', function () {
@@ -191,6 +211,8 @@ describe('TS: VALID: Asset attribute', function () {
         expect(data[0].example.attributes.f.schema[1].type).to.equal('number');
         expect(data[0].example.attributes.f.schema[1].array).to.equal(false);
         expect(data[0].example.attributes.f.schema[1].default).to.equal(10);
+        expect(data[0].example.attributes.f.schema[1].min).to.equal(10);
+        expect(data[0].example.attributes.f.schema[1].max).to.equal(20);
     });
 
     it('f[c]: should be a string attribute', function () {
@@ -247,6 +269,22 @@ describe('TS: VALID: Asset attribute', function () {
         expect(data[0].example.attributes.i.schema).to.exist;
     });
 
+    it('i[a]: should be a boolean attribute', function () {
+        expect(data[0].example.attributes.i.schema[0].name).to.equal('a');
+        expect(data[0].example.attributes.i.schema[0].type).to.equal('boolean');
+        expect(data[0].example.attributes.i.schema[0].array).to.equal(false);
+        expect(data[0].example.attributes.i.schema[0].default).to.equal(true);
+        expect(data[0].example.attributes.i.schema[0].description).to.equal('description of a');
+    });
+
+    it('i[b]: should be a numeric attribute', function () {
+        expect(data[0].example.attributes.i.schema[1].name).to.equal('b');
+        expect(data[0].example.attributes.i.schema[1].type).to.equal('number');
+        expect(data[0].example.attributes.i.schema[1].array).to.equal(false);
+        expect(data[0].example.attributes.i.schema[1].min).to.equal(10);
+        expect(data[0].example.attributes.i.schema[1].max).to.equal(20);
+    });
+
     it('l: should be an inline type json attribute', function () {
         expect(data[0].example.attributes.l).to.exist;
         expect(data[0].example.attributes.l.name).to.equal('l');

package/test/tests/valid/misc.test.js

@@ -28,7 +28,7 @@ describe('VALID: Misc attribute types', function () {
         expect(data[0].example.attributes.a.array).to.equal(false);
         expect(data[0].example.attributes.a.default).to.equal(0);
         expect(data[0].example.attributes.a.title).to.equal('A number');
-        expect(data[0].example.attributes.a.description).to.equal('This is a description of the attribute');
+        expect(data[0].example.attributes.a.description).to.equal('This is a description of the attribute. It can be multi-sentence.\n\nAnd multi-line too');
     });
 
     it('b: should be a numeric attribute with a getter and setter', function () {

package/test/tests/valid/program.test.js

@@ -9,10 +9,15 @@ describe('VALID: Program ', function () {
         data = await parseAttributes('./program.valid.js');
     });
 
+    it('should have a customExample script', function () {
+        expect(data[0].customExample).to.exist;
+        expect(data[0].customExample.errors).to.be.empty;
+    });
+
     it('only results should exist', function () {
         expect(data).to.exist;
         expect(data[0]).to.not.be.empty;
         expect(data[1]).to.be.empty;
-        expect(data[0].example.errors).to.be.empty;
+        expect(data[0].customExample.errors).to.be.empty;
     });
 });