@playcanvas/attribute-parser 1.10.2 → 1.11.0

package/package.json

@@ -1,68 +1,71 @@
 {
-  "name": "@playcanvas/attribute-parser",
-  "version": "1.10.2",
-  "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": "dist/index.js",
-  "types": "types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./types/index.d.ts",
-      "import": "./dist/index.js"
+    "name": "@playcanvas/attribute-parser",
+    "version": "1.11.0",
+    "description": "The PlayCanvas Attribute Parser",
+    "keywords": [
+        "playcanvas",
+        "attribute",
+        "parser"
+    ],
+    "homepage": "https://github.com/playcanvas/attribute-parser#readme",
+    "bugs": {
+        "url": "https://github.com/playcanvas/attribute-parser/issues"
     },
-    "./libs": "./dist/libs.d.ts"
-  },
-  "bugs": {
-    "url": "https://github.com/playcanvas/attribute-parser/issues"
-  },
-  "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"
-  ],
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "28.0.6",
-    "@rollup/plugin-node-resolve": "16.0.1",
-    "@rollup/plugin-swc": "0.4.0",
-    "@swc/core": "1.13.3",
-    "chai": "5.2.1",
-    "globals": "16.3.0",
-    "mocha": "11.7.1",
-    "playcanvas": "^2.12.3",
-    "publint": "0.3.12",
-    "rollup": "4.46.2"
-  },
-  "dependencies": {
-    "@playcanvas/eslint-config": "^2.0.0",
-    "@typescript/vfs": "^1.6.0",
-    "eslint": "^9.0.0",
-    "typescript": "^5.5.3"
-  },
-  "scripts": {
-    "build": "rollup -c && npm run build:types",
-    "build:types": "tsc -p tsconfig.build.json",
-    "lint": "eslint src rollup.config.mjs eslint.config.mjs",
-    "lint:fix": "eslint src rollup.config.mjs eslint.config.mjs --fix",
-    "publint": "publint",
-    "test": "mocha test/**/*.test.js --timeout 10000",
-    "type:check": "tsc --noEmit",
-    "watch": "rollup -c -w"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/playcanvas/attribute-parser.git"
+    },
+    "license": "MIT",
+    "author": "PlayCanvas <support@playcanvas.com>",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./types/index.d.ts",
+            "node": "./dist/index.node.mjs",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./libs": "./dist/libs.d.ts"
+    },
+    "main": "dist/index.js",
+    "types": "types/index.d.ts",
+    "files": [
+        "dist/index.node.mjs",
+        "dist/libs.d.ts",
+        "types"
+    ],
+    "scripts": {
+        "build": "rollup -c && npm run build:types",
+        "build:types": "tsc -p tsconfig.build.json",
+        "fmt": "prettier --check .",
+        "fmt:fix": "prettier --write .",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "publint": "publint",
+        "test": "mocha",
+        "typecheck": "tsc --noEmit",
+        "watch": "rollup -c -w"
+    },
+    "dependencies": {
+        "@playcanvas/eslint-config": "3.0.0-beta.8",
+        "@typescript/vfs": "^1.6.0",
+        "eslint": "^9.0.0",
+        "typescript": "^5.5.3"
+    },
+    "devDependencies": {
+        "@rollup/plugin-commonjs": "28.0.9",
+        "@rollup/plugin-node-resolve": "16.0.3",
+        "@rollup/plugin-swc": "0.4.1",
+        "@swc/core": "1.15.43",
+        "@types/node": "26.1.0",
+        "chai": "5.3.3",
+        "mocha": "11.7.6",
+        "playcanvas": "2.12.3",
+        "prettier": "3.9.4",
+        "publint": "0.3.21",
+        "rollup": "4.62.2"
+    },
+    "engines": {
+        "node": ">=22.0.0"
+    }
 }

package/types/index.d.ts

@@ -1,57 +1,74 @@
-export class JSDocParser {
-    /**
-     * @type {import('@typescript/vfs').VirtualTypeScriptEnvironment}
-     * @private
-     */
+import * as ts from 'typescript';
+import type { AttributeData } from './parsers/attribute-parser.ts';
+import { ParsingError } from './parsers/parsing-error.ts';
+import { ScriptParser } from './parsers/script-parser.ts';
+import type { ValidationError } from './parsers/script-parser.ts';
+type ScriptResults = {
+    /** The extracted attributes, keyed by attribute name */
+    attributes: Record<string, AttributeData>;
+    /** The parsing errors for this script */
+    errors: ParsingError[];
+};
+type MemberInfo = {
+    /** The name of the member */
+    name: string;
+    /** Whether the member is a script attribute */
+    isAttribute: boolean;
+    /** The type of the member, with an array suffix when applicable */
+    type: string;
+    /** The start of the member, including any JSDoc block */
+    start: {
+        line: number;
+        column: number;
+    };
+    /** The end of the member */
+    end: {
+        line: number;
+        column: number;
+    };
+};
+export declare class JSDocParser {
     private _env;
     /**
      * An internal array of program errors
-     * @private
      */
     private _errors;
+    parser: ScriptParser;
+    program: ts.Program;
     /**
      * 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
+     * @param libPath - A path to a directory of library types, or a path to the '.d.ts' file itself
+     * @returns The initialized JSDocParser
      */
-    init(libPath: string): Promise<JSDocParser>;
+    init(libPath?: string): Promise<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
+     * @param newFiles - An array of [path, content] tuples which represent the files in the program
+     * @param removedFiles - An array of file paths that should be removed from the program
+     * @returns The program errors
      */
-    updateProgram(newFiles?: [string, string][], removedFiles?: string[]): {
-        parser: ScriptParser;
-        program: ts.Program;
-        errors: import("./parsers/script-parser.js").ValidationError[];
-    };
-    parser: ScriptParser;
-    program: ts.Program;
+    updateProgram(newFiles?: [string, string][], removedFiles?: string[]): ValidationError[];
     /**
      * Returns all the valid ESM Scripts within a file
-     * @param {string} fileName - The file name in the program to check
-     * @param {ParsingError[]} errors - An array to store any parsing errors
-     * @returns {Map<string, import('typescript').Node>} - A map of valid ESM Script <names, nodes> within the file
+     * @param fileName - The file name in the program to check
+     * @param errors - An array to store any parsing errors
+     * @returns A map of valid ESM Script <names, nodes> within the file
      */
-    getAllEsmScripts(fileName: string, errors?: ParsingError[]): Map<string, import("typescript").Node>;
+    getAllEsmScripts(fileName: string, errors?: (ParsingError | ValidationError)[]): Map<string, ts.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
+     * @param fileName - The name of the file in the program to run
+     * @returns The extracted attributes and errors
      */
-    parseAttributes(fileName: string): [results: object, errors: import("./parsers/script-parser.js").ValidationError[]];
+    parseAttributes(fileName: string): [Record<string, ScriptResults>, (ParsingError | 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
+     * @param fileName - The name of the file to run
+     * @returns The extracted attributes and errors
      */
-    getAttributes(fileName: string): [results: object, errors: import("./parsers/script-parser.js").ValidationError[]];
+    getAttributes(fileName: string): [Record<string, MemberInfo[]>, (ParsingError | ValidationError)[]];
 }
-import { ScriptParser } from './parsers/script-parser.js';
-import * as ts from 'typescript';
-import { ParsingError } from './parsers/parsing-error.js';
+export {};

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

@@ -1,78 +1,97 @@
+import type { VirtualTypeScriptEnvironment } from '@typescript/vfs';
+import * as ts from 'typescript';
+import type { LiteralValue } from '../utils/ts-utils.ts';
+import { ParsingError } from './parsing-error.ts';
+export type TagDefinition = {
+    /** The type of the tag */
+    type: string;
+    /** A function to generate a support message for the tag */
+    supportMessage?: () => string;
+    /** A string to fix the tag */
+    fix?: string;
+};
+export type TypeSerializer = (node: ts.Node, typeChecker?: ts.TypeChecker) => LiteralValue;
 /**
- * @typedef {Object} TagDefinition
- * @property {string} type - The type of the tag
- * @property {() => string} supportMessage - A function to generate a support message for the tag
- * @property {string} fix - A function to fix the tag
+ * The internal representation of a parsed attribute. Known fields are set while parsing;
+ * custom block tags (e.g. @placeholder, @size) land on the index signature.
  */
+export type AttributeData = {
+    /** The resolved type, replaced with its lowercased type name on output */
+    type: ts.Type | string;
+    /** The name of the attribute */
+    name: string;
+    /** The type name, removed on output */
+    typeName?: string;
+    /** Whether the attribute is an array type */
+    array: boolean;
+    /** The serialized value, moved to default on output */
+    value?: LiteralValue;
+    /** The enum members, removed on output when empty */
+    enum?: Record<string, LiteralValue>[];
+    description?: string;
+    range?: number[];
+    min?: number;
+    max?: number;
+    attributes?: Record<string, AttributeData>;
+    schema?: AttributeData[];
+    resource?: string;
+    assetType?: string;
+    default?: LiteralValue;
+    enabledif?: string;
+    visibleif?: string;
+    [key: string]: unknown;
+};
 /**
  * A class to parse JSDoc comments and extract attribute metadata.
  */
-export class AttributeParser {
+export declare class AttributeParser {
+    env: VirtualTypeScriptEnvironment;
+    tagTypeAnnotations: Map<string, TagDefinition>;
+    typeSerializerMap: Map<string, TypeSerializer>;
+    program: ts.Program;
+    typeChecker: ts.TypeChecker;
     /**
      * Creates a new instance of the ScriptParser class.
      *
-     * @param {Map<string, TagDefinition>} 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
+     * @param tags - An set of tag definitions and their validators to add to the parser
+     * @param env - The TypeScript environment to use
+     * @param typeSerializerMap - A map of custom serializers
      */
-    constructor(tags: Map<string, TagDefinition>, env: object, typeSerializerMap: Map<string, Function>);
-    env: any;
-    tagTypeAnnotations: Map<string, TagDefinition>;
-    typeSerializerMap: Map<string, Function>;
-    program: any;
-    typeChecker: any;
+    constructor(tags: Map<string, TagDefinition>, env: VirtualTypeScriptEnvironment, typeSerializerMap: Map<string, TypeSerializer>);
     /**
      * 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
-     * @param {string} scriptName - The name of the script this node belongs to
-     * @param {string} attributeName - The name of the attribute this node belongs to
-     * @returns {*} - The extracted metadata or null if no metadata was found
+     * @param node - The node to parse
+     * @param errors - An array to store any parsing errors
+     * @param requiresAttributeTag - Whether the comment must have an attribute tag
+     * @param scriptName - The name of the script this node belongs to
+     * @param attributeName - The name of the attribute this node belongs to
+     * @returns The extracted metadata or undefined if no metadata was found
      */
-    parseAttributeComment(node: ts.Node, errors: ParsingError[], requiresAttributeTag: boolean, scriptName: string, attributeName: string): any;
+    parseAttributeComment(node: ts.Node, errors?: ParsingError[], requiresAttributeTag?: boolean, scriptName?: string, attributeName?: string): AttributeData;
     /**
      * 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
-     * @param {string} [scriptName] - The name of the script this node belongs to
-     * @returns {*} - The extracted members
+     * @param node - The node to parse
+     * @param errors - An array to store any parsing errors
+     * @param scriptName - The name of the script this node belongs to
+     * @returns The extracted members
      */
-    getNodeAsAttribute(node: ts.Node, errors?: ParsingError[], scriptName?: string): any;
+    getNodeAsAttribute(node: ts.Node, errors?: ParsingError[], scriptName?: string): AttributeData;
     /**
      * 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
+     * @param node - The TypeScript node to analyze
+     * @param _errors - An array to store any parsing errors
+     * @returns An array of enum members
      */
-    getEnumMembers(node: import("typescript").Node, errors: ParsingError[]): {
-        [x: string]: any;
-    }[];
+    getEnumMembers(node: ts.Node, _errors: ParsingError[]): Record<string, LiteralValue>[];
     /**
      * Extract the public members and their values from a TypeScript node.
      *
-     * @param {ts.Node} node - The node to parse
-     * @returns {any[]} - The extracted members
+     * @param node - The node to parse
+     * @returns The extracted members
      */
-    getMembers(node: ts.Node): any[];
+    getMembers(node: ts.Node): Record<string, LiteralValue>[];
 }
-export type TagDefinition = {
-    /**
-     * - The type of the tag
-     */
-    type: string;
-    /**
-     * - A function to generate a support message for the tag
-     */
-    supportMessage: () => string;
-    /**
-     * - A function to fix the tag
-     */
-    fix: string;
-};
-import * as ts from 'typescript';
-import { ParsingError } from './parsing-error.js';

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

@@ -1,40 +1,10 @@
-/**
- * @typedef {Object} Fix
- * @property {string} text - The text to insert at the fix location
- * @property {string} title - The title of the fix
- * @property {{ startLineNumber: number, startColumn: number, endLineNumber: number, endColumn: number }} range - The range of the fix
- */
-/**
- * A class representing a parsing error.
- * @param {import('typescript').Node} node - The AST node which caused the error
- * @param {string} type - The type of the error
- * @param {string} message - The description of the error
- * @param {Fix} [fix] - The fix for the error
- * @param {string} [scriptName] - The name of the script this error belongs to (required)
- * @param {string} [attributeName] - The name of the attribute this error belongs to (optional)
- */
-export class ParsingError {
-    constructor(node: any, type: any, message: any, fix: any, scriptName: any, attributeName: any);
-    node: any;
-    type: any;
-    message: any;
-    fix: any;
-    scriptName: any;
-    attributeName: any;
-    toString(): string;
-}
+import type { Node } from 'typescript';
 export type Fix = {
-    /**
-     * - The text to insert at the fix location
-     */
+    /** The text to insert at the fix location */
     text: string;
-    /**
-     * - The title of the fix
-     */
+    /** The title of the fix */
     title: string;
-    /**
-     * - The range of the fix
-     */
+    /** The range of the fix */
     range: {
         startLineNumber: number;
         startColumn: number;
@@ -42,3 +12,22 @@ export type Fix = {
         endColumn: number;
     };
 };
+/**
+ * A class representing a parsing error.
+ */
+export declare class ParsingError {
+    /** The AST node which caused the error */
+    node: Node;
+    /** The type of the error */
+    type: string;
+    /** The description of the error */
+    message: string;
+    /** The fix for the error */
+    fix?: Fix;
+    /** The name of the script this error belongs to */
+    scriptName?: string;
+    /** The name of the attribute this error belongs to */
+    attributeName?: string;
+    constructor(node: Node, type: string, message: string, fix?: Fix, scriptName?: string, attributeName?: string);
+    toString(): string;
+}

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

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