@playcanvas/attribute-parser 1.3.0 → 1.3.1

package/.github/workflows/ci.yml

@@ -7,25 +7,43 @@ on:
     branches: [ main ]
 
 jobs:
+  lint:
+    name: Lint Code
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js 18.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm clean-install --progress=false --no-fund
+
+      - name: Run ESLint
+        run: npm run lint
+
   unit-test-node:
     name: Unit Test
     runs-on: ubuntu-latest
     timeout-minutes: 10
+    needs: lint # Ensure linting completes successfully first
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-
-    - name: Setup Node.js 18.x
-      uses: actions/setup-node@v4
-      with:
-        node-version: 18.x
-        cache: 'npm'
+      - name: Checkout code
+        uses: actions/checkout@v4
 
-    - name: Install dependencies
-      run: npm clean-install --progress=false --no-fund
+      - name: Setup Node.js 18.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+          cache: 'npm'
 
-    - name: Run ESLint
-      run: npm run lint
+      - name: Install dependencies
+        run: npm clean-install --progress=false --no-fund
 
-    - name: Run unit tests
-      run: npm test
+      - name: Run unit tests
+        run: npm test

package/eslint.config.mjs

@@ -0,0 +1,35 @@
+import playcanvasConfig from '@playcanvas/eslint-config';
+import globals from 'globals';
+
+export default [
+    ...playcanvasConfig,
+    {
+        ignores: ['**/program.invalid.js'] // Exclude specific files
+    },
+    {
+        languageOptions: {
+            ecmaVersion: 2022,
+            sourceType: 'module',
+            globals: {
+                ...globals.browser,
+                ...globals.mocha,
+                ...globals.node
+            }
+        }
+    },
+    {
+        rules: {
+            'no-unused-expressions': 'off',
+            'jsdoc/check-tag-names': 'off',
+            'import/no-unresolved': 'off'
+        }
+    },
+    {
+        // Configuration specific to test files
+        files: ['**/*.test.js'], // Match test files
+
+        rules: {
+            'prefer-arrow-callback': 'off' // Allow function expressions in test files
+        }
+    }
+];

package/package.json

@@ -5,18 +5,18 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "version": "1.3.0",
+  "version": "1.3.1",
   "dependencies": {
     "@microsoft/tsdoc": "^0.15.0",
-    "@playcanvas/eslint-config": "^1.7.4",
+    "@playcanvas/eslint-config": "^1.7.4 || ^2.0.0",
     "@typescript/vfs": "^1.6.0",
-    "eslint": "^8.56.0",
+    "eslint": "^8.56.0 || ^9.0.0",
     "typescript": "^5.5.3"
   },
   "devDependencies": {
-    "chai": "^5.1.1",
-    "globals": "^15.9.0",
-    "mocha": "^10.6.0"
+    "chai": "5.1.2",
+    "globals": "15.14.0",
+    "mocha": "11.1.0"
   },
   "scripts": {
     "test": "mocha test/**/*.test.js --timeout 10000",

package/renovate.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended"
+  ],
+  "packageRules": [
+    {
+      "matchManagers": [
+        "npm"
+      ],
+      "groupName": "all npm dependencies",
+      "schedule": [
+        "on monday at 10:00am"
+      ]
+    },
+    {
+      "matchDepTypes": ["devDependencies"],
+      "rangeStrategy": "pin"
+    },
+    {
+      "matchDepTypes": ["dependencies"],
+      "rangeStrategy": "widen"
+    }
+  ],
+}

package/src/index.js

@@ -110,7 +110,7 @@ export class JSDocParser {
     /**
      * Returns all the valid ESM Scripts within a file
      * @param {string} fileName - The file name in the program to check
-     * @returns {import('typescript').Node[]} - An array of any exported ESM Script nodes within the file
+     * @returns {Map<string, import('typescript').Node>} - A map of valid ESM Script <names, nodes> within the file
      */
     getAllEsmScripts(fileName) {
 
@@ -135,9 +135,15 @@ export class JSDocParser {
 
         const esmScriptClass = pcTypes.statements.find(node => node.kind === ts.SyntaxKind.ClassDeclaration && node.name.text === 'Script')?.symbol;
 
+        const esmScripts = new Map();
         // Check if the file exports a class that inherits from `Script`
-        return Array.from(nodes).filter(node => isAliasedClassDeclaration(node, typeChecker) && inheritsFrom(node, typeChecker, esmScriptClass));
+        nodes.forEach((node, name) => {
+            if (isAliasedClassDeclaration(node, typeChecker) && inheritsFrom(node, typeChecker, esmScriptClass)) {
+                esmScripts.set(name, node);
+            }
+        });
 
+        return esmScripts;
     }
 
     /**
@@ -158,9 +164,8 @@ export class JSDocParser {
         const nodes = this.getAllEsmScripts(fileName);
 
         // Extract attributes from each script
-        nodes.forEach((node) => {
-            const name = toLowerCamelCase(node.name.text);
-            const opts = results[name] = { attributes: {}, errors: [] };
+        nodes.forEach((node, name) => {
+            const opts = results[toLowerCamelCase(name)] = { attributes: {}, errors: [] };
             this.parser.extractAttributes(node, opts);
         });
 

package/src/parsers/script-parser.js

@@ -321,17 +321,17 @@ export class ScriptParser {
             return attributes;
         }
 
-        const buffer = node.getSourceFile().getFullText();
-
         // Find "/** */" style comments associated with this node.
-        const comments = getJSDocCommentRanges(node, buffer, this.typeChecker);
+        const comments = getJSDocCommentRanges(node, this.typeChecker);
 
         // Parse the comments for attribute metadata
         for (const comment of comments) {
 
+            const memberFileText = comment.member.getSourceFile().getFullText();
+
             // Parse the comment for attribute metadata
             const attributeMetadata = this.attributeParser.parseAttributeComment(
-                TextRange.fromStringRange(buffer, comment.range.pos, comment.range.end),
+                TextRange.fromStringRange(memberFileText, comment.range.pos, comment.range.end),
                 comment.member,
                 errors,
                 requiresAttributeTag

package/src/utils/tag-utils.js

@@ -24,12 +24,12 @@ export function parseTag(input = '') {
     try {
         const arr = parseStringToNumericalArray(input);
         if (Array.isArray(arr)) return arr;
-    } catch { /* eslint-disable-next-line no-empty */ }
+    } catch { }
 
     try {
         const arr = JSON.parse(input);
         if (Array.isArray(arr)) return arr;
-    } catch { /* eslint-disable-next-line no-empty */ }
+    } catch { }
 
     // If none of the above, return the string
     return input;

package/src/utils/ts-utils.js

@@ -5,8 +5,8 @@ import * as ts from 'typescript';
 import { ParsingError } from '../parsers/parsing-error.js';
 
 export function createDefaultMapFromCDN(options, prefix, ts) {
-    var fsMap = new Map();
-    var files = knownLibFilesForCompilerOptions(options, ts);
+    const fsMap = new Map();
+    const files = knownLibFilesForCompilerOptions(options, ts);
 
     async function uncached() {
         const contentPromises = files.map((lib) => {
@@ -45,7 +45,7 @@ function resolveAliasedSymbol(typeChecker, symbol) {
  * Returns an array of exported nodes from a TypeScript source file.
  * @param {import('typescript').Program} program - The TypeScript program
  * @param {import('typescript').SourceFile} sourceFile - The TypeScript source file
- * @returns {Set<import('typescript').Node>} - A Set of exported nodes
+ * @returns {let map: Map<string, Set<import('typescript').Node>>} - A Map of exported nodes
  */
 export function getExportedNodes(program, sourceFile) {
     if (!program || !sourceFile) {
@@ -62,16 +62,18 @@ export function getExportedNodes(program, sourceFile) {
     const exportedSymbols = typeChecker.getExportsOfModule(moduleSymbol);
 
     // Find the actual declaration nodes for each exported symbol
-    const exportedNodes = [];
+    const exportedNodes = new Map();
 
     exportedSymbols.forEach((symbol) => {
         const resolvedSymbol = resolveAliasedSymbol(typeChecker, symbol);
         if (resolvedSymbol.declarations) {
-            exportedNodes.push(...resolvedSymbol.declarations);
+            const node = resolvedSymbol.declarations[0];
+            const name = symbol.name === 'default' ? node.name.getText() : symbol.name;
+            exportedNodes.set(name, node);
         }
     });
 
-    return new Set(exportedNodes);
+    return exportedNodes;
 }
 
 /**
@@ -205,12 +207,13 @@ function getSuperClasses(node, typeChecker) {
  * @param {import('typescript').TypeChecker} typeChecker - The TypeScript type checker
  * @returns {{ memberName: string, member: ts.Node, range: import('typescript').CommentRange}[]} - An array of comment ranges
  */
-export function getJSDocCommentRanges(node, text, typeChecker) {
+export function getJSDocCommentRanges(node, typeChecker) {
     const commentRanges = [];
 
     if (ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node)) {
         // get an array of the class an all parent classed
-        const heritageChain = getSuperClasses(node, typeChecker);
+        const heritageChain = getSuperClasses(node, typeChecker)
+        .filter(classNode => !classNode.getSourceFile().isDeclarationFile);
 
         // iterate over the heritance chain
         heritageChain.forEach((classNode) => {
@@ -218,7 +221,7 @@ export function getJSDocCommentRanges(node, text, 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, text);
+                    const ranges = getLeadingBlockCommentRanges(member, member.getSourceFile().getFullText());
                     if (ranges.length > 0) {
                         commentRanges.push({
                             memberName,

package/test/fixtures/example.dep.js

@@ -0,0 +1,9 @@
+import { Script } from 'playcanvas';
+
+export class Example extends Script {
+    /**
+     * @attribute
+     * @type {boolean}
+     */
+    a;
+}

package/test/fixtures/export.import.js

@@ -1,3 +1,8 @@
 import { Script } from 'playcanvas';
 
-export class ExampleImport extends Script {}
+export class ExampleImport extends Script {
+    /**
+     * @attribute
+     */
+    prop = 10;
+}

package/test/fixtures/export.valid.js

@@ -4,9 +4,12 @@ import { ExampleImport } from './export.import.js';
 
 class ExampleImportExtend extends ExampleImport {}
 
-export { ExampleImport as ExampleImportExportAs } from './export.import.js';
+export { ExampleImport as ExampleImportAsExport } from './export.import.js';
 
-class Example extends Script {}
+class Example extends Script {
+    /** @attribute */
+    num = 10;
+}
 
 export default class ExampleDefault extends Script {}
 

package/test/fixtures/inherit.valid.js

@@ -1,12 +1,6 @@
 import { Script } from 'playcanvas';
 
-class Example extends Script {
-    /**
-     * @attribute
-     * @type {boolean}
-     */
-    a;
-}
+import { Example } from './example.dep.js';
 
 class ExampleExtended extends Example {
     /**

package/test/tests/valid/export.test.js

@@ -15,9 +15,9 @@ describe('VALID: Export Script', function () {
         expect(data[1]).to.be.empty;
     });
 
-    it('Example: should exist without attributes or errors', function () {
+    it('Example: should exist with attributes', function () {
         expect(data[0]?.example).to.exist;
-        expect(data[0].example.attributes).to.be.empty;
+        expect(data[0].example.attributes).to.not.be.empty;
         expect(data[0].example.errors).to.be.empty;
     });
 
@@ -33,19 +33,31 @@ describe('VALID: Export Script', function () {
         expect(data[0].exampleDefault.errors).to.be.empty;
     });
 
+    it('ExampleImportAsExport: should not exist', function () {
+        expect(data[0]?.exampleImportAsExport).to.exist;
+        expect(data[0].exampleImportAsExport.attributes).to.not.be.empty;
+        expect(data[0].exampleImportAsExport.errors).to.be.empty;
+    });
+
     it('ExampleExportAs: should not exist', function () {
-        expect(data[0]?.exampleExportAs).to.not.exist;
+        expect(data[0]?.exampleExportAs).to.exist;
+        expect(data[0].exampleExportAs.attributes).to.not.be.empty;
+        expect(data[0].exampleExportAs.errors).to.be.empty;
     });
 
-    it('ExampleImport: should exist without attributes or errors', function () {
+    it('ExampleImport: should exist with attributes', function () {
         expect(data[0]?.exampleImport).to.exist;
-        expect(data[0].exampleImport.attributes).to.be.empty;
+        expect(data[0].exampleImport.attributes).to.not.be.empty;
+        expect(data[0].exampleImport.attributes.prop.type).to.equal('number');
+        expect(data[0].exampleImport.attributes.prop.default).to.equal(10);
         expect(data[0].exampleImport.errors).to.be.empty;
     });
 
-    it('ExampleImportExtend: should exist without attributes or errors', function () {
+    it('ExampleImportExtend: should exist with attributes', function () {
         expect(data[0]?.exampleImportExtend).to.exist;
-        expect(data[0].exampleImportExtend.attributes).to.be.empty;
+        expect(data[0].exampleImportExtend.attributes).to.not.be.empty;
+        expect(data[0].exampleImportExtend.attributes.prop.type).to.equal('number');
+        expect(data[0].exampleImportExtend.attributes.prop.default).to.equal(10);
         expect(data[0].exampleImportExtend.errors).to.be.empty;
     });
 

package/test/tests/valid/inherit.test.js

@@ -6,7 +6,7 @@ import { parseAttributes } from '../../utils.js';
 describe('VALID: Script inheritance attributes', function () {
     let data;
     before(async function () {
-        data = await parseAttributes('./inherit.valid.js');
+        data = await parseAttributes('./inherit.valid.js', './example.dep.js');
     });
 
     it('only results should exist', function () {
@@ -24,6 +24,14 @@ describe('VALID: Script inheritance attributes', function () {
     it('ExampleExtended: should exist without errors', function () {
         expect(data[0]?.exampleExtended).to.exist;
         expect(data[0].exampleExtended.attributes).to.not.be.empty;
+        expect(data[0].exampleExtended.attributes.a).to.exist;
+        expect(data[0].exampleExtended.attributes.a.type).to.equal('boolean');
+        expect(data[0].exampleExtended.attributes.a.array).to.equal(false);
+        expect(data[0].exampleExtended.attributes.a.default).to.equal(false);
+        expect(data[0].exampleExtended.attributes.b).to.be.exists;
+        expect(data[0].exampleExtended.attributes.b.type).to.equal('number');
+        expect(data[0].exampleExtended.attributes.b.array).to.equal(false);
+        expect(data[0].exampleExtended.attributes.b.default).to.equal(0);
         expect(data[0].exampleExtended.errors).to.be.empty;
     });
 

package/.eslintignore

@@ -1 +0,0 @@
-/**/program.invalid.js

package/.eslintrc

@@ -1,19 +0,0 @@
-{
-    "extends": [
-      "@playcanvas/eslint-config"
-    ],
-    "rules": {
-      "no-unused-expressions": "off",
-      "jsdoc/check-tag-names": "off",
-      "import/no-unresolved": "off"
-    },
-    "overrides": [
-        {
-            "files": ["./**/*.test.js"],
-            "rules": {
-              "prefer-arrow-callback": "off",
-          }
-        }
-      ]
-  }
-