feat(cli-helpers): add async PHP file parsing method

change/@rightcapital-php-parser-cd87dc5c-d5d4-4cfb-8d82-92d609348145.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat(cli-helpers): add async PHP file parsing method and refactor path resolution",
+  "packageName": "@rightcapital/php-parser",
+  "email": "yilunsun11@yeah.net",
+  "dependentChangeType": "patch"
+}

src/php-parser/helpers/cli-helpers.ts

@@ -1,12 +1,12 @@
-import { execSync } from 'node:child_process';
+import { execFile, execSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import { tmpdir } from 'node:os';
-import { resolve } from 'node:path';
+import * as path from 'node:path';
 
 import { PROJECT_ROOT } from '../../constants';
 import type { NodeTypeInheritingFromNodeAbstract } from '../types/types';
 
-const defaultPhpParserBinaryPath = resolve(
+const defaultPhpParserBinaryPath = path.resolve(
   PROJECT_ROOT,
   'vendor',
   'bin',
@@ -42,6 +42,46 @@ export class CliHelpers {
     ) as NodeTypeInheritingFromNodeAbstract[];
   }
 
+  /**
+   * Using PHP version php phaser to Parse PHP File to AST (Async version)
+   *
+   * @param phpFilePath The PHP file path to parse
+   * @returns Promise resolving to an AST in JSON format from php parser
+   */
+  public static async parsePhpFileToAstAsync(
+    phpFilePath: string,
+  ): Promise<NodeTypeInheritingFromNodeAbstract[]> {
+    return new Promise((resolve, reject) => {
+      execFile(
+        PHP_PARSER_BINARY,
+        [phpFilePath, '-j'],
+        {
+          encoding: 'utf8',
+          maxBuffer: MAX_BUFFER_SIZE_FOR_PHP_BINARY_OUTPUT,
+        },
+        (error, stdout) => {
+          if (error) {
+            reject(new Error(`Failed to parse PHP file: ${error.message}`));
+            return;
+          }
+
+          try {
+            const result = JSON.parse(
+              stdout,
+            ) as NodeTypeInheritingFromNodeAbstract[];
+            resolve(result);
+          } catch (parseError) {
+            reject(
+              new Error(
+                `Failed to parse JSON output: ${parseError instanceof Error ? parseError.message : String(parseError)}`,
+              ),
+            );
+          }
+        },
+      );
+    });
+  }
+
   /**
    * Parse a PHP Code string to AST in JSON format
    * Because we are invoking PHP parser to parse the string
@@ -56,7 +96,7 @@ export class CliHelpers {
     /**
      * Temp file like "php-parser-{current time}.tmp" +
      */
-    const temporaryFilename = resolve(
+    const temporaryFilename = path.resolve(
       tmpdir(),
       `${currentDate.getTime()}.${currentDate.getMilliseconds()}.tmp`,
     );

src/php-parser/helpers/type-generation-helpers.ts

@@ -32,14 +32,39 @@ export class TypeGenerationHelpers {
 
     const combinationTypesPart = Object.entries(allNodes)
       .map(([name, nodeItem]) => {
+        const validSubNodeTypes = nodeItem.subNodeNames
+          .filter((subNodeName) => {
+            const subNode = allNodes[subNodeName];
+            const hasNodeType =
+              subNode &&
+              subNode.nodeType !== undefined &&
+              subNode.nodeType !== '';
+            const isUnionType =
+              subNode &&
+              subNode.subNodeNames &&
+              subNode.subNodeNames.length > 0;
+
+            return hasNodeType || isUnionType;
+          })
+          .map((subNodeName) =>
+            TypeGenerationHelpers.getGroupedTypeNameForNode(subNodeName),
+          );
+
+        const shouldIncludeSelf =
+          nodeItem.nodeType !== undefined && nodeItem.nodeType !== '';
+
+        const typeComponents = [
+          ...(shouldIncludeSelf ? [name] : []),
+          ...validSubNodeTypes,
+        ];
+
+        if (typeComponents.length === 0) {
+          typeComponents.push(name);
+        }
+
         return `export type ${TypeGenerationHelpers.getGroupedTypeNameForNode(
           name,
-        )} = ${[
-          name,
-          ...nodeItem.subNodeNames.map((subNodeName) =>
-            TypeGenerationHelpers.getGroupedTypeNameForNode(subNodeName),
-          ),
-        ].join(' | ')};`;
+        )} = ${typeComponents.join(' | ')};`;
       })
       .join('\n');