@playcanvas/attribute-parser 1.6.1 → 1.7.1

package/package.json

@@ -1,27 +1,67 @@
 {
   "name": "@playcanvas/attribute-parser",
+  "version": "1.7.1",
+  "author": "PlayCanvas <support@playcanvas.com>",
+  "homepage": "https://github.com/playcanvas/attribute-parser#readme",
+  "description": "The PlayCanvas Attribute Parser",
+  "keywords": [
+    "playcanvas",
+    "attribute",
+    "parser"
+  ],
+  "license": "MIT",
   "type": "module",
-  "main": "src/index.js",
-  "engines": {
-    "node": ">=18.0.0"
+  "main": "dist/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./libs": "./dist/libs.d.ts"
+  },
+  "bugs": {
+    "url": "https://github.com/playcanvas/attribute-parser/issues"
   },
-  "version": "1.6.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/playcanvas/attribute-parser.git"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/libs.d.ts",
+    "types",
+    "README.md",
+    "LICENSE.md"
+  ],
   "dependencies": {
-    "@playcanvas/eslint-config": "^1.7.4 || ^2.0.0",
+    "@playcanvas/eslint-config": "^2.0.0",
     "@typescript/vfs": "^1.6.0",
-    "eslint": "^8.56.0 || ^9.0.0",
+    "eslint": "^9.0.0",
     "typescript": "^5.5.3"
   },
   "devDependencies": {
+    "@rollup/plugin-commonjs": "28.0.1",
+    "@rollup/plugin-node-resolve": "15.3.0",
+    "@rollup/plugin-swc": "0.4.0",
+    "@swc/core": "1.9.2",
     "chai": "5.1.2",
     "globals": "15.14.0",
-    "mocha": "11.1.0"
+    "mocha": "11.1.0",
+    "rollup": "4.25.0",
+    "publint": "^0.3.2"
   },
   "scripts": {
     "test": "mocha test/**/*.test.js --timeout 10000",
-    "lint": "eslint ."
+    "build": "rollup -c",
+    "build:types": "tsc -p tsconfig.build.json",
+    "watch": "rollup -c -w",
+    "lint": "eslint src rollup.config.mjs",
+    "lint:fix": "eslint src rollup.config.mjs --fix",
+    "type:check": "tsc --noEmit",
+    "publint": "publint"
   },
-  "publishConfig": {
-    "access": "public"
+  "engines": {
+    "node": ">=18.0.0"
   }
 }

package/types/index.d.ts

@@ -0,0 +1,55 @@
+export class JSDocParser {
+    /**
+     * @type {import('@typescript/vfs').VirtualTypeScriptEnvironment}
+     * @private
+     */
+    private _env;
+    /**
+     * An internal array of program errors
+     * @private
+     */
+    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
+     */
+    init(libPath: string): Promise<JSDocParser>;
+    /**
+     * 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?: [string, string][], removedFiles?: string[]): {
+        parser: ScriptParser;
+        program: ts.Program;
+        errors: import("./parsers/script-parser.js").ValidationError[];
+    };
+    parser: ScriptParser;
+    program: ts.Program;
+    /**
+     * 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: string): Map<string, import("typescript").Node>;
+    /**
+     * 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: string): [results: object, errors: import("./parsers/script-parser.js").ValidationError[]];
+    /**
+     * 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: string): [results: object, errors: import("./parsers/script-parser.js").ValidationError[]];
+}
+import { ScriptParser } from './parsers/script-parser.js';
+import * as ts from 'typescript';

package/types/parsers/attribute-parser.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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: Map<string, string>, env: object, typeSerializerMap: Map<string, Function>);
+    env: any;
+    tagTypeAnnotations: Map<string, string>;
+    typeSerializerMap: Map<string, Function>;
+    program: any;
+    typeChecker: any;
+    /**
+     * 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: ts.Node, errors?: ParsingError[], requiresAttributeTag?: boolean): any;
+    /**
+     * 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: ts.Node, errors?: ParsingError[]): any;
+    /**
+     * 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: import("typescript").Node, errors: ParsingError[]): {
+        [x: string]: any;
+    }[];
+    /**
+     * 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: ts.Node): any[];
+}
+import * as ts from 'typescript';
+import { ParsingError } from './parsing-error.js';

package/types/parsers/parsing-error.d.ts

@@ -0,0 +1,6 @@
+export class ParsingError {
+    constructor(node: any, message: any);
+    node: any;
+    message: any;
+    toString(): string;
+}

package/types/parsers/script-parser.d.ts

@@ -0,0 +1,124 @@
+/**
+ * A class to parse ESM Scripts and extract attribute metadata from JSDoc comments.
+ * This class uses the TypeScript compiler API to parse the script and extract the metadata.
+ */
+export class ScriptParser {
+    /**
+     * @param {import('@typescript/vfs').VirtualTypeScriptEnvironment} env - The TypeScript virtual environment
+     * @param {number} [maxDepth] - The maximum recursion depth
+     */
+    constructor(env: import("@typescript/vfs").VirtualTypeScriptEnvironment, maxDepth?: number);
+    env: import("@typescript/vfs").VirtualTypeScriptEnvironment;
+    program: ts.Program;
+    typeChecker: ts.TypeChecker;
+    maxDepth: number;
+    typeSerializerMap: Map<any, any>;
+    allSupportedTypesSet: Set<ts.Type>;
+    attributeParser: AttributeParser;
+    /**
+     * Checks a program for compile errors and returns a list of formatted error messages.
+     * @param {ValidationError[]} errors - The array to store error messages
+     * @returns {boolean} - True if the program has no errors, false otherwise
+     */
+    validateProgram(errors?: ValidationError[]): boolean;
+    /**
+     * @typedef {Object} ParserOptions
+     * @property {object} [attributes] - The attributes object to add to
+     * @property {ParsingError[]} [errors] - The array to store parsing errors
+     * @property {boolean} [requiresAttributeTag] - Whether the attribute requires an @attribute tag
+     * @property {number} [depth] - The current recursion depth
+     */
+    /**
+     * Extracts Script Attributes from JSDoc style tag from a AST node
+     *
+     * @param {import('typescript').Node} node - The TypeScript node to analyze
+     * @param {ParserOptions} [opts] - The input options
+     * @returns {Attribute[]} - The extracted attributes;
+     */
+    extractAttributes(node: import("typescript").Node, opts?: {
+        /**
+         * - The attributes object to add to
+         */
+        attributes?: object;
+        /**
+         * - The array to store parsing errors
+         */
+        errors?: ParsingError[];
+        /**
+         * - Whether the attribute requires an
+         */
+        requiresAttributeTag?: boolean;
+    }): Attribute[];
+}
+export type Attribute = {
+    /**
+     * - The type of the attribute
+     */
+    type: string;
+    /**
+     * - Whether the attribute is an array type of not
+     */
+    array: boolean;
+    /**
+     * - The description of the attribute
+     */
+    description?: string;
+    /**
+     * - Placeholder for Editor's for field UI.
+     */
+    placeholder?: string;
+    /**
+     * - The default value of the attribute
+     */
+    defaultValue?: any;
+    /**
+     * - An array of possible values for the attribute
+     */
+    enum?: {
+        [x: string]: number | boolean | string;
+    }[];
+    /**
+     * - Numerical constraints for the attribute
+     */
+    range?: {
+        min: number;
+        max: number;
+    };
+    /**
+     * - Numerical constraints for the attribute
+     */
+    precision?: number;
+    /**
+     * - Numerical constraints for the attribute
+     */
+    step?: number;
+    /**
+     * - Name of asset type to be used in 'asset' type attribute
+     */
+    resource?: string;
+};
+export type ValidationError = {
+    /**
+     * - The error message
+     */
+    message: string;
+    /**
+     * - The file the error occurred in
+     */
+    file?: string;
+    /**
+     * - The line the error occurred on
+     */
+    line?: number;
+    /**
+     * - The column the error occurred on
+     */
+    column?: number;
+    /**
+     * - The length of the error
+     */
+    length?: number;
+};
+import * as ts from 'typescript';
+import { AttributeParser } from './attribute-parser.js';
+import { ParsingError } from './parsing-error.js';

package/types/utils/attribute-utils.d.ts

@@ -0,0 +1,5 @@
+export function getTagFromJsdoc(tag: string, doc: import("typescript").Node): import("typescript").Node;
+export function getTag(tag: string, node: import("typescript").Node): import("typescript").Node;
+export function hasTag(tag: string, node: import("typescript").Node): boolean;
+export function isInterface(node: import("typescript").Node): boolean;
+export function isStaticMember(member: import("typescript").Node): boolean;

package/{src/utils/generic-utils.js → types/utils/generic-utils.d.ts}

@@ -6,13 +6,4 @@
  * @param {array} b - The second array
  * @returns {array} - The merged array
  */
-export function zipArrays(a, b) {
-    const length = Math.max(a.length, b.length);
-    const result = new Array(length);
-
-    for (let i = 0; i < length; i++) {
-        result[i] = i < a.length ? a[i] : b[i];
-    }
-
-    return result;
-}
+export function zipArrays(a: any[], b: any[]): any[];

package/types/utils/tag-utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Parses a tag value into a boolean, number, array or string
+ * @param {string} input - The tag value to parse
+ * @returns {boolean|number|string|Array<any>} - The parsed value
+ */
+export function parseTag(input?: string): boolean | number | string | Array<any>;
+/**
+ * Validates that a tag value matches the expected type
+ *
+ * @param {String} value - The value to be validated.
+ * @param {String} typeAnnotation - The TypeScript type annotation as a string.
+ * @param {import('@typescript/vfs').VirtualTypeScriptEnvironment} env - The environment containing the language service and file creation utilities.
+ * @throws Will throw an error if the value does not conform to the typeAnnotation.
+ * @returns {true} if validation passes without type errors.
+ */
+export function validateTag(value: string, typeAnnotation: string, env: import("@typescript/vfs").VirtualTypeScriptEnvironment): true;

package/types/utils/ts-utils.d.ts

@@ -0,0 +1,103 @@
+export function createDefaultMapFromCDN(options: any, prefix: any, ts: any): Promise<Map<any, any>>;
+/**
+ * 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 {let map: Map<string, Set<import('typescript').Node>>} - A Map of exported nodes
+ */
+export function getExportedNodes(program: import("typescript").Program, sourceFile: import("typescript").SourceFile): let;
+/**
+ * Checks if the node or its aliased symbol is a class declaration.
+ *
+ * @param {import('typescript').Node} node - The TypeScript node
+ * @param {import('typescript').TypeChecker} typeChecker - The TypeScript type checker
+ * @returns {boolean} - True if the node or its original declaration is a class declaration, false otherwise
+ */
+export function isAliasedClassDeclaration(node: import("typescript").Node, typeChecker: import("typescript").TypeChecker): boolean;
+/**
+ * Determines if a TypeScript node inherits from a specific base class.
+ * @param {ts.ClassDeclaration} node - The TypeScript node to analyze
+ * @param {ts.TypeChecker} typeChecker - The TypeScript type checker
+ * @param {ts.Symbol} baseClassSymbol - The base class symbol to check inheritance against
+ * @returns {boolean} - True if the node inherits from the base class
+ */
+export function inheritsFrom(node: ts.ClassDeclaration, typeChecker: ts.TypeChecker, baseClassSymbol: ts.Symbol): boolean;
+/**
+ * Recursively gathers and flat maps and nodes that meet a specific filter.
+ * @param {import('typescript').Node} node - The TypeScript node to analyze
+ * @param {function} filter - A function to filter the nodes
+ * @returns {import('typescript').Node[]} - An array of exported class declarations
+ */
+export function flatMapAnyNodes(node: import("typescript").Node, filter?: Function): import("typescript").Node[];
+/**
+ * Retrieves the JSDoc-style comments 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
+ * @param {import('typescript').TypeChecker} typeChecker - The TypeScript type checker
+ * @returns {{ memberName: string, member: Node, range: import('typescript').CommentRange}[]} - An array of comment ranges
+ */
+export function getJSDocTags(node: import("typescript").Node, typeChecker: import("typescript").TypeChecker): {
+    memberName: string;
+    member: Node;
+    range: import("typescript").CommentRange;
+}[];
+/**
+ * Determines if a TypeScript node is an enum.
+ * @param {import('typescript').Node} node - The TypeScript node to analyze
+ * @returns {boolean} - True if the node is an enum
+ */
+export function isEnum(node: import("typescript").Node): boolean;
+/**
+ * Determines the primitive type for enums, or falls back to the actual type name.
+ *
+ * @param {ts.Type} type - The type to inspect.
+ * @param {ts.TypeChecker} typeChecker - The TypeScript type checker.
+ * @returns {'string' | 'boolean' | 'number' | null} - The primitive type of the enum or the type's name.
+ */
+export function getPrimitiveEnumType(type: ts.Type, typeChecker: ts.TypeChecker): "string" | "boolean" | "number" | null;
+/**
+ * Gets the inferred type of a TypeScript node.
+ *
+ * @param {ts.Node} node - The TypeScript node to analyze
+ * @param {ts.TypeChecker} typeChecker - The TypeScript type checker
+ * @returns {{ array: boolean, name: string | undefined, type: Type | null }} - The inferred type of the node
+ */
+export function getType(node: ts.Node, typeChecker: ts.TypeChecker): {
+    array: boolean;
+    name: string | undefined;
+    type: Type | null;
+};
+/**
+ * Parses a numerical string into a number. Handles hexadecimal, binary,
+ * octal, exponential notation and underscore notation
+ *
+ * @param {string} input - The string to parse
+ * @returns {number} The parsed number, or NaN if the input is not a number
+ */
+export function parseNumber(input: string): number;
+/**
+ * Parses a string representation of a numerical array into an array of numbers.
+ *
+ * @param {string} input - The string to parse
+ * @returns {number[]} - The parsed array of numbers
+ * @throws {Error} - If the input contains invalid characters or is not a valid array
+ */
+export function parseStringToNumericalArray(input: string): number[];
+/**
+ * Attempts to extract a literal value from a TypeScript node. This function
+ * supports various types of literals and expressions, including object literals,
+ * array literals, identifiers, and unary expressions.
+ *
+ * @param {import('typescript').Node} node - The AST node to evaluate
+ * @param {import('typescript').TypeChecker} typeChecker - The TypeScript type checker
+ * @returns {any} - The extracted literal value
+ */
+export function getLiteralValue(node: import("typescript").Node, typeChecker: import("typescript").TypeChecker): any;
+export function isNumericLiteral(node: import("typescript").Node): boolean;
+export function parseFloatNode(node: import("typescript").Node, isArgument?: boolean): number;
+export function parseBooleanNode(node: import("typescript").Node): boolean;
+export function parseStringNode(node: import("typescript").Node): string;
+export function parseArrayLiteralNode(node: any, isArgument?: boolean): any;
+export function parseArrayLiteral(args: ts.Node[]): number[];
+import * as ts from 'typescript';

package/.github/workflows/ci.yml

@@ -1,49 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    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: 22.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: 22.x
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm clean-install --progress=false --no-fund
-
-      - name: Run unit tests
-        run: npm test

package/eslint.config.mjs

@@ -1,35 +0,0 @@
-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/renovate.json

@@ -1,25 +0,0 @@
-{
-  "$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"
-    }
-  ],
-}