@appthreat/atom-parsetools 1.2.1 → 1.3.0

package/README.md

@@ -7,6 +7,10 @@ This package hosts a collection of parsing tools that complement the `@appthreat
 - rbastgen - Generates AST for Ruby projects using the AppThreat's `ruby_ast_gen` gem
 - scalasem - Generates a custom semantics slice for Scala Projects by utilising scalac command.
 
+## Runtime support
+
+These tools run on both [Node.js](https://nodejs.org) (>= 22, required by `@babel/parser` 8) and [Bun](https://bun.sh). All commands and the accompanying regression test-suite are exercised under both runtimes in CI, so the commands below can be invoked with either `node` or `bun` interchangeably (for example `bun astgen.js -i .`).
+
 ## Command usages
 
 ### astgen
@@ -25,6 +29,16 @@ Options:
   -h             Show help                                             [boolean]
 ```
 
+#### Environment variables
+
+| Variable                    | Default   | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ASTGEN_TYPE_WORKERS`       | `1` (off) | Number of worker threads for the TypeScript type-generation phase, or `auto` to derive it from the available CPUs. The TypeScript checker is single-threaded, so parallelism comes from sharding files across workers, each building its own program. **Opt-in:** sharding changes TypeScript's internal type-id ordering, which reorders the members of a small number of inferred union types (e.g. `A \| B` → `B \| A`; semantically identical). Leave unset for byte-identical output; set it (e.g. `auto` or `8`) to trade that cosmetic reordering for a large speedup on big projects. |
+| `ASTGEN_INCLUDE_TEST_FILES` | `false`   | When `true`, do not exclude test files (`*.poku.js`, `*.test.*`, `*.spec.*`, `*.e2e.*`, `__tests__/`, `__mocks__/`) from AST and type generation. They are excluded by default because they are typically the heaviest, lowest-value inputs for type generation.                                                                                                                                                                                                                                                                                                                              |
+| `ASTGEN_CONCURRENCY`        | `10`      | Chunk size for the in-thread file loop (bounds peak memory between `gc()` passes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `ASTGEN_INCLUDE_NODE_MODULES_BUNDLES` | `false` | When `true`, also parse bundled entrypoints inside `node_modules` (files matching `*.(bundle\|dist\|index\|min\|app).(js\|cjs\|mjs)`). Off by default; `node_modules` is otherwise skipped entirely.                                                                                                                                                                                                                                                       |
+| `ASTGEN_IGNORE_DIRS`        | unset     | Comma/space-separated list of directories to ignore. As a side effect, when it is set and does **not** contain `node_modules`, the `node_modules` bundle entrypoints above are included (equivalent to `ASTGEN_INCLUDE_NODE_MODULES_BUNDLES=true`).                                                                                                                                                                                                        |
+
 ### phpastgen
 
 ```text

package/astgen.js

@@ -1,21 +1,35 @@
 #!/usr/bin/env node
 
-import { join, dirname, relative, resolve } from "path";
+import { join, dirname, relative, resolve, basename } from "path";
 import { fileURLToPath } from "url";
 import { parse } from "@babel/parser";
 import { parse as parseHermes } from "hermes-parser";
-import tsc from "typescript";
+// TypeScript 7.0 (the native Go port) ships without a programmatic compiler
+// API, which astgen relies on heavily (createProgram, getTypeChecker,
+// forEachChild, SyntaxKind, TypeFormatFlags, ...). The officially supported
+// bridge until the API returns in TS 7.1 is the @typescript/typescript6
+// package, which is the same TS 6 engine and therefore keeps AST shapes and
+// type-inference accuracy identical.
+import tsc from "@typescript/typescript6";
+import { tmpdir, cpus, availableParallelism } from "os";
+import { Worker, isMainThread, parentPort, workerData } from "worker_threads";
 import {
   readFileSync,
   mkdirSync,
   writeFileSync,
   accessSync,
   constants,
-  existsSync
+  existsSync,
+  mkdtempSync,
+  rmSync
 } from "fs";
 import { getAllFiles } from "@appthreat/atom-common";
 
-const ASTGEN_VERSION = "4.0.0";
+// Printed by `astgen --version`. Downstream frontends (e.g. chen's jssrc2cpg)
+// fold this into their parse-cache fingerprint, so it MUST be bumped whenever
+// the emitted AST/type shape changes — otherwise stale cached parses from an
+// older astgen are silently reused. Bumped for the Babel 8 AST-shape change.
+const ASTGEN_VERSION = "4.1.0";
 
 const HELP_TEXT = `Options:
   -i, --src      Source directory                                 [default: "."]
@@ -294,7 +308,10 @@ const makeBabelOptions = (
   baseOptions,
   file,
   extraPlugins = [],
-  { enableJsxSyntax = shouldEnableJsxSyntax(file), disallowAmbiguousJSXLike } = {}
+  {
+    enableJsxSyntax = shouldEnableJsxSyntax(file),
+    disallowAmbiguousJSXLike
+  } = {}
 ) => ({
   ...baseOptions,
   plugins: mergeBabelPlugins(
@@ -375,6 +392,25 @@ const babelSafeFlowParserOptions = {
   ]
 };
 
+// Test files (e.g. *.poku.js, *.test.ts, *.spec.js, __tests__/*) are
+// test-runner artifacts that are typically the heaviest, lowest-value inputs
+// for type generation (each is often a full twin of a source module wrapped in
+// test scaffolding). They are excluded by default to keep the type-generation
+// phase scalable. Set ASTGEN_INCLUDE_TEST_FILES=true to restore them (e.g. when
+// a downstream consumer wants test files analysed).
+const shouldIncludeTestFiles =
+  process.env?.ASTGEN_INCLUDE_TEST_FILES === "true";
+
+const TEST_FILE_EXT = "(?:js|jsx|cjs|mjs|ts|tsx|mts|cts)";
+const TEST_FILE_PATTERN = new RegExp(
+  `(?:\\.(?:poku|test|spec|e2e|integration|it)\\.${TEST_FILE_EXT}$` +
+    `|[\\\\/]__(?:tests|mocks)__[\\\\/])`,
+  "i"
+);
+
+const isExcludedTestFile = (file) =>
+  !shouldIncludeTestFiles && TEST_FILE_PATTERN.test(file);
+
 const shouldIncludeNodeModulesBundles =
   process.env?.ASTGEN_INCLUDE_NODE_MODULES_BUNDLES === "true" ||
   (process.env?.ASTGEN_IGNORE_DIRS &&
@@ -420,16 +456,18 @@ const getAllSrcJSAndTSFiles = (src) => {
   // Step 2: Combine both lists
   return Promise.all([allFilesPromise, bundledFilesPromise]).then(
     ([allFiles, bundledFiles]) =>
-      [...new Set([...allFiles, ...bundledFiles])].sort()
+      [...new Set([...allFiles, ...bundledFiles])]
+        .filter((file) => !isExcludedTestFile(file))
+        .sort()
   );
 };
 
 /**
  * Convert a single JS/TS file to AST
  */
-const fileToJsAst = (file, projectType) => {
+const fileToJsAst = (file, projectType, tsInstance) => {
   if (file.endsWith(".vue") || file.endsWith(".svelte")) {
-    return toVueAst(file);
+    return toVueAst(file, tsInstance);
   }
   if (file.endsWith(".ejs")) {
     return toEjsAst(file);
@@ -509,12 +547,209 @@ const codeToJsAst = (file, code, projectType) => {
   }
 };
 
+const vueScriptTagOnlyRegex = /<\/?script[^>]*>/gi;
+const vueScriptBlockRegex = /<script\b[^>]*>[\s\S]*?<\/script>/gi;
+const vueStyleBlockRegex = /<style\b[^>]*>[\s\S]*?<\/style>/gi;
+const vueBrTagRegex = /<\/?br>/gi;
 const vueCleaningRegex = /<\/*script.*>|<style[\s\S]*style>|<\/*br>/gi;
 const vueTemplateRegex = /(<template.*>)([\s\S]*)(<\/template>)/gi;
 const vueCommentRegex = /<!--[\s\S]*?-->/gi;
 const vueBindRegex = /(:\[)([\s\S]*?)(\])/gi;
 const vuePropRegex = /\s([.:@])([a-zA-Z]*?=)/gi;
 const vueOpenImgTag = /(<img)((?!>)[\s\S]+?)( [^/]>)/gi;
+const vueScriptTagRegex = /<script\b[^>]*>([\s\S]*?)<\/script>/gi;
+
+const VUE_COMPILER_MACRO_SHIMS = `
+declare function defineProps<T = any>(): T;
+declare function defineEmits<T = any>(): T;
+declare function defineExpose<T = any>(value?: T): void;
+declare function defineSlots<T = any>(): T;
+declare function defineModel<T = any>(
+  options?: { required?: boolean; default?: T }
+): import("vue").Ref<T>;
+declare function defineModel<T = any>(
+  name: string,
+  options?: { required?: boolean; default?: T }
+): import("vue").Ref<T>;
+declare function withDefaults<T, D>(props: T, defaults: D): T & D;
+
+declare module "vue" {
+  export type Ref<T = any> = { value: T };
+  export type ComputedRef<T = any> = { readonly value: T };
+  export type InjectionKey<T> = symbol & { __type?: T };
+  export function ref<T>(value: T): Ref<T>;
+  export function ref<T = any>(): Ref<T | undefined>;
+  export function shallowRef<T>(value: T): Ref<T>;
+  export function computed<T>(getter: () => T): ComputedRef<T>;
+  export function inject<T>(key: any, defaultValue?: T): T;
+  export function provide<T>(key: any, value: T): void;
+  export function watch(...args: any[]): void;
+  export function watchEffect(effect: () => void): void;
+  export function onMounted(cb: () => void): void;
+  export function onUnmounted(cb: () => void): void;
+}
+`;
+
+const maskNonNewlineChars = (value) => value.replace(/[^\r\n]/g, " ");
+
+const cleanVueCodeForParsing = (code, { includeScripts = true } = {}) => {
+  let cleanedCode = code
+    .replace(vueCommentRegex, (match) => maskNonNewlineChars(match))
+    .replace(vueStyleBlockRegex, (match) => maskNonNewlineChars(match));
+
+  if (includeScripts) {
+    cleanedCode = cleanedCode.replace(vueScriptTagOnlyRegex, (match) => {
+      const masked = maskNonNewlineChars(match);
+      return masked.length > 0 ? `${masked.slice(1)};` : masked;
+    });
+  } else {
+    cleanedCode = cleanedCode.replace(vueScriptBlockRegex, (match) =>
+      maskNonNewlineChars(match)
+    );
+  }
+
+  return cleanedCode
+    .replace(vueBrTagRegex, (match) => {
+      const masked = maskNonNewlineChars(match);
+      return masked.length > 0 ? `${masked.slice(1)};` : masked;
+    })
+    .replace(vueBindRegex, (match, grA, grB, grC) => {
+      return maskNonNewlineChars(grA) + grB + maskNonNewlineChars(grC);
+    })
+    .replace(vuePropRegex, (match, grA, grB) => {
+      return " " + grA.replace(/[.:@]/g, " ") + grB.replaceAll(".", "-");
+    })
+    .replace(vueOpenImgTag, (match, grA, grB, grC) => {
+      return grA + grB + grC.replace(" >", "/>");
+    })
+    .replace(vueTemplateRegex, (match, grA, grB, grC) => {
+      return grA + grB.replaceAll("{{", "{ ").replaceAll("}}", " }") + grC;
+    });
+};
+
+const extractVueScriptContent = (code) => {
+  const scriptChunks = [];
+  let scriptMatch;
+  vueScriptBlockRegex.lastIndex = 0;
+  while ((scriptMatch = vueScriptBlockRegex.exec(code)) !== null) {
+    const fullMatch = scriptMatch[0] || "";
+    const content = fullMatch
+      .replace(/^<script\b[^>]*>/i, "")
+      .replace(/<\/script>$/i, "");
+    if (content.trim().length > 0) {
+      scriptChunks.push(content);
+    }
+  }
+  return scriptChunks.join("\n");
+};
+
+const buildVueParseCandidates = (code) => {
+  const fullCandidate = cleanVueCodeForParsing(code, { includeScripts: true });
+  const templateOnlyCandidate = cleanVueCodeForParsing(code, {
+    includeScripts: false
+  });
+  const scriptOnlyCandidate = extractVueScriptContent(code);
+  const combinedCandidate = scriptOnlyCandidate
+    ? `${scriptOnlyCandidate}\n${templateOnlyCandidate}`
+    : templateOnlyCandidate;
+
+  const candidates = [
+    { name: "full", code: fullCandidate },
+    { name: "combined", code: combinedCandidate },
+    { name: "template-only", code: templateOnlyCandidate },
+    { name: "script-only", code: scriptOnlyCandidate }
+  ];
+
+  const seenCandidateCode = new Set();
+  return candidates.filter((candidate) => {
+    if (!candidate.code || !candidate.code.trim()) {
+      return false;
+    }
+    if (seenCandidateCode.has(candidate.code)) {
+      return false;
+    }
+    seenCandidateCode.add(candidate.code);
+    return true;
+  });
+};
+
+const parseVueAstWithFallback = (file, code) => {
+  const candidates = buildVueParseCandidates(code);
+  let lastError;
+  for (const candidate of candidates) {
+    try {
+      return codeToJsAst(file, candidate.code, "ts");
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  throw lastError || new Error(`Unable to parse Vue file: ${file}`);
+};
+
+const createVueVirtualTypeSource = (code) => {
+  const output = maskNonNewlineChars(code).split("");
+  let hasScriptContent = false;
+  let scriptMatch;
+  vueScriptTagRegex.lastIndex = 0;
+  while ((scriptMatch = vueScriptTagRegex.exec(code)) !== null) {
+    const fullMatch = scriptMatch[0];
+    const scriptContent = scriptMatch[1] || "";
+    const contentStart = scriptMatch.index + fullMatch.indexOf(scriptContent);
+    if (scriptContent.trim().length > 0) {
+      hasScriptContent = true;
+    }
+    for (let index = 0; index < scriptContent.length; index++) {
+      output[contentStart + index] = scriptContent[index];
+    }
+  }
+  return {
+    source: output.join(""),
+    hasScriptContent
+  };
+};
+
+const collectVueTypesWithVirtualProgram = (file, virtualSource) => {
+  const tempDir = mkdtempSync(join(tmpdir(), "atom-parsetools-vue-"));
+  const virtualFile = join(tempDir, `${basename(file)}.ts`);
+  const shimFile = join(tempDir, "vue-shims.d.ts");
+  try {
+    writeFileSync(virtualFile, virtualSource, "utf8");
+    writeFileSync(shimFile, VUE_COMPILER_MACRO_SHIMS, "utf8");
+    const virtualTs = createTsc([virtualFile, shimFile], tempDir);
+    const sourceFile = virtualTs?.program?.getSourceFile(virtualFile);
+    if (!virtualTs || !sourceFile) {
+      return new Map();
+    }
+    return virtualTs.collectTypes(sourceFile);
+  } catch {
+    return new Map();
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+};
+
+const collectVueSeenTypes = (file, code, tsInstance) => {
+  let seenTypes;
+  if (tsInstance?.program) {
+    try {
+      const tsSrc = tsInstance.program.getSourceFile(file);
+      if (tsSrc) {
+        seenTypes = tsInstance.collectTypes(tsSrc);
+      }
+    } catch {
+      // Ignore and continue with virtual source fallback below.
+    }
+  }
+
+  if (!seenTypes || seenTypes.size === 0) {
+    const virtualSource = createVueVirtualTypeSource(code);
+    if (virtualSource.hasScriptContent) {
+      seenTypes = collectVueTypesWithVirtualProgram(file, virtualSource.source);
+    }
+  }
+
+  return seenTypes;
+};
 
 const TSC_FLAGS =
   tsc.TypeFormatFlags.NoTruncation |
@@ -526,30 +761,43 @@ const TSC_FLAGS =
   tsc.TypeFormatFlags.NoTypeReduction;
 
 /**
- * Convert a single vue file to AST
+ * Convert a single vue file to AST.
+ * When `tsInstance` is present also collect type inference from TSC and return both AST & types.
  */
-const toVueAst = (file) => {
+const toVueAst = (file, tsInstance) => {
   const code = readFileSync(file, "utf-8");
-  const cleanedCode = code
-    .replace(vueCommentRegex, function (match) {
-      return match.replaceAll(/\S/g, " ");
-    })
-    .replace(vueCleaningRegex, function (match) {
-      return match.replaceAll(/\S/g, " ").substring(1) + ";";
-    })
-    .replace(vueBindRegex, function (match, grA, grB, grC) {
-      return grA.replaceAll(/\S/g, " ") + grB + grC.replaceAll(/\S/g, " ");
-    })
-    .replace(vuePropRegex, function (match, grA, grB) {
-      return " " + grA.replace(/[.:@]/g, " ") + grB.replaceAll(".", "-");
-    })
-    .replace(vueOpenImgTag, function (match, grA, grB, grC) {
-      return grA + grB + grC.replace(" >", "/>");
-    })
-    .replace(vueTemplateRegex, function (match, grA, grB, grC) {
-      return grA + grB.replaceAll("{{", "{ ").replaceAll("}}", " }") + grC;
-    });
-  return codeToJsAst(file, cleanedCode, "ts");
+  return parseVueAstWithFallback(file, code);
+};
+
+const collectSeenTypesForFile = (file, ts, options) => {
+  if (!options?.tsTypes) {
+    return undefined;
+  }
+
+  if (file.endsWith(".vue")) {
+    return collectVueSeenTypes(file, readFileSync(file, "utf-8"), ts);
+  }
+
+  if (!ts?.program) {
+    return undefined;
+  }
+
+  try {
+    const tsAst = ts.program.getSourceFile(file);
+    if (!tsAst) {
+      return undefined;
+    }
+    return ts.collectTypes
+      ? ts.collectTypes(tsAst)
+      : (() => {
+          tsc.forEachChild(tsAst, ts.addType);
+          const collectedTypes = new Map(ts.seenTypes);
+          ts.seenTypes.clear();
+          return collectedTypes;
+        })();
+  } catch {
+    return undefined;
+  }
 };
 
 /**
@@ -707,7 +955,7 @@ const DEFAULT_TSC_OPTIONS = {
 
 const readJsonFileIfExists = (file) => {
   try {
-    if (!existsSync(file)) {
+    if (!file || !existsSync(file)) {
       return undefined;
     }
     return JSON.parse(readFileSync(file, "utf8"));
@@ -732,7 +980,10 @@ const findNearestPackageJson = (src) => {
 };
 
 const detectDefaultTscOptions = (srcFiles, src) => {
-  const packageJson = readJsonFileIfExists(findNearestPackageJson(src));
+  const nearPackageJson = findNearestPackageJson(src);
+  const packageJson = nearPackageJson
+    ? readJsonFileIfExists(nearPackageJson)
+    : undefined;
   const usesNodeNextModuleResolution =
     packageJson?.type === "module" ||
     Boolean(packageJson?.exports) ||
@@ -868,6 +1119,33 @@ function createTsc(srcFiles, src) {
     const typeChecker = program.getTypeChecker();
     const seenTypes = new Map();
 
+    // Return-type inference below can re-walk the body of the *same* function
+    // declaration once per referencing call site / initializer (e.g. a helper
+    // called 50 times triggers 50 identical body walks). Since the checker
+    // state is fixed for the lifetime of this program, the inferred string for
+    // a given node is deterministic, so we memoize by node to remove the
+    // redundant re-walks without changing any output. A sentinel distinguishes
+    // "computed and produced undefined" from "not yet computed".
+    const RETURN_TYPE_NOT_COMPUTED = Symbol("returnTypeNotComputed");
+    const memoizeByNode = (fn) => {
+      const cache = new WeakMap();
+      return (node, ...rest) => {
+        if (!node || typeof node !== "object" || rest.length > 0) {
+          return fn(node, ...rest);
+        }
+        const cached = cache.get(node);
+        if (cached !== undefined) {
+          return cached === RETURN_TYPE_NOT_COMPUTED ? undefined : cached;
+        }
+        const result = fn(node);
+        cache.set(
+          node,
+          result === undefined ? RETURN_TYPE_NOT_COMPUTED : result
+        );
+        return result;
+      };
+    };
+
     const safeTypeToString = (type, context) => {
       try {
         return normalizeTypeString(
@@ -895,7 +1173,10 @@ function createTsc(srcFiles, src) {
         return undefined;
       }
       try {
-        return safeTypeToString(typeChecker.getTypeFromTypeNode(typeNode), typeNode);
+        return safeTypeToString(
+          typeChecker.getTypeFromTypeNode(typeNode),
+          typeNode
+        );
       } catch {
         return undefined;
       }
@@ -984,7 +1265,6 @@ function createTsc(srcFiles, src) {
         return collectedTypes;
       }
       if (
-        node !== undefined &&
         !tsc.isFunctionDeclaration(node) &&
         !tsc.isFunctionExpression(node) &&
         !tsc.isArrowFunction(node) &&
@@ -997,7 +1277,7 @@ function createTsc(srcFiles, src) {
       return collectedTypes;
     };
 
-    const inferAsyncReturnTypeFromBody = (node) => {
+    const inferAsyncReturnTypeFromBodyImpl = (node) => {
       if (!node.body) {
         return undefined;
       }
@@ -1019,6 +1299,9 @@ function createTsc(srcFiles, src) {
         ? unionType
         : `Promise<${unionType}>`;
     };
+    const inferAsyncReturnTypeFromBody = memoizeByNode(
+      inferAsyncReturnTypeFromBodyImpl
+    );
 
     const buildFunctionSignatureType = (node, returnTypeStr) => {
       if (!node.parameters) {
@@ -1074,7 +1357,7 @@ function createTsc(srcFiles, src) {
       return undefined;
     };
 
-    const inferFunctionDeclarationReturnType = (declaration) => {
+    const inferFunctionDeclarationReturnTypeImpl = (declaration) => {
       const signature = typeChecker.getSignatureFromDeclaration(declaration);
       if (!signature) {
         return undefined;
@@ -1096,8 +1379,11 @@ function createTsc(srcFiles, src) {
       }
       return inferredType;
     };
+    const inferFunctionDeclarationReturnType = memoizeByNode(
+      inferFunctionDeclarationReturnTypeImpl
+    );
 
-    const inferAsyncReturnTypeFromSyntaxBody = (node) => {
+    const inferAsyncReturnTypeFromSyntaxBodyImpl = (node) => {
       if (!node?.body) {
         return undefined;
       }
@@ -1140,6 +1426,9 @@ function createTsc(srcFiles, src) {
         ? unionType
         : `Promise<${unionType}>`;
     };
+    const inferAsyncReturnTypeFromSyntaxBody = memoizeByNode(
+      inferAsyncReturnTypeFromSyntaxBodyImpl
+    );
 
     const addType = (node, currentSeenTypes = seenTypes) => {
       // STRUCTURAL/CONTAINER NODES
@@ -1256,10 +1545,13 @@ function createTsc(srcFiles, src) {
           node.kind === tsc.SyntaxKind.VariableDeclaration &&
           node.name
         ) {
-          const explicitDeclaredType = getExplicitTypeAnnotationString(node.type);
+          const explicitDeclaredType = getExplicitTypeAnnotationString(
+            node.type
+          );
           const varType = typeChecker.getTypeAtLocation(node.name);
           typeStr =
-            explicitDeclaredType && !isUnresolvedTypeString(explicitDeclaredType)
+            explicitDeclaredType &&
+            !isUnresolvedTypeString(explicitDeclaredType)
               ? explicitDeclaredType
               : safeTypeWithContextToString(varType, node.name);
           if (node.initializer && !explicitDeclaredType) {
@@ -1537,64 +1829,209 @@ function createTsc(srcFiles, src) {
   }
 }
 
+/**
+ * Expand the set of output files to include the source files that tsconfig
+ * pulls in (that live under the source root), mirroring the program root names.
+ * Computed from the parsed tsconfig alone so no TypeScript program has to be
+ * built on the main thread.
+ */
+const expandSrcFilesWithRootNames = (srcFiles, rootNames, src) => {
+  if (!rootNames) {
+    return srcFiles;
+  }
+  const srcRoot = resolve(src);
+  const srcFileByResolvedPath = new Map(
+    srcFiles.map((file) => [resolve(file), file])
+  );
+  for (const file of rootNames) {
+    const resolvedFile = resolve(file);
+    if (
+      resolvedFile.startsWith(srcRoot) &&
+      /\.(?:js|jsx|cjs|mjs|ts|tsx|mts|cts)$/.test(file) &&
+      !isExcludedTestFile(file) &&
+      !srcFileByResolvedPath.has(resolvedFile)
+    ) {
+      srcFileByResolvedPath.set(
+        resolvedFile,
+        join(src, relative(srcRoot, resolvedFile))
+      );
+    }
+  }
+  return [...srcFileByResolvedPath.values()].sort();
+};
+
+const runGc = () => {
+  if (typeof globalThis.gc === "function") {
+    try {
+      globalThis.gc();
+    } catch (e) {
+      // ignore
+    }
+  } else if (typeof Bun !== "undefined" && typeof Bun.gc === "function") {
+    try {
+      Bun.gc(true);
+    } catch (e) {
+      // ignore
+    }
+  }
+};
+
+/**
+ * Process a list of files (AST + optional type generation) on the current
+ * thread, in memory-bounded chunks. `ts` is the shared TypeScript program
+ * instance (or undefined when type generation is disabled).
+ */
+const processFilesInline = async (srcFiles, options, ts) => {
+  const CONCURRENCY_LIMIT = Math.max(
+    1,
+    Number.parseInt(process.env.ASTGEN_CONCURRENCY || "10", 10) || 10
+  );
+  for (let i = 0; i < srcFiles.length; i += CONCURRENCY_LIMIT) {
+    const chunk = srcFiles.slice(i, i + CONCURRENCY_LIMIT);
+    await Promise.all(chunk.map((file) => processFile(file, options, ts)));
+    runGc();
+  }
+};
+
+/**
+ * Decide how many worker threads to use for the type-generation phase.
+ * The TypeScript checker is single-threaded and CPU-bound, so real speedups
+ * only come from running independent programs on separate threads. Each worker
+ * builds its own full program (needed for cross-file type resolution).
+ *
+ * IMPORTANT: parallelism is OPT-IN. When files are sharded across workers,
+ * TypeScript's per-program type-id assignment order changes, which reorders the
+ * members of a small number of inferred union types (e.g. `A | B` -> `B | A`;
+ * semantically identical, textually different). To keep the default output
+ * byte-identical for downstream consumers, workers are only used when
+ * ASTGEN_TYPE_WORKERS is set explicitly. Set it to the desired worker count
+ * (e.g. number of cores) to trade that cosmetic reordering for speed; "auto"
+ * derives the count from the available CPUs. Unset or 1 => single-threaded.
+ */
+const resolveTypeWorkerCount = (fileCount) => {
+  const envValue = process.env.ASTGEN_TYPE_WORKERS;
+  if (envValue === undefined || envValue === "") {
+    return 1;
+  }
+  if (envValue.toLowerCase() === "auto") {
+    let cores = 1;
+    try {
+      cores =
+        typeof availableParallelism === "function"
+          ? availableParallelism()
+          : cpus().length;
+    } catch (e) {
+      cores = 1;
+    }
+    const autoCount = Math.max(cores - 1, 1);
+    return Math.min(autoCount, Math.max(1, fileCount));
+  }
+  const requested = Number.parseInt(envValue, 10);
+  if (!Number.isFinite(requested) || requested < 1) {
+    return 1;
+  }
+  return Math.min(requested, Math.max(1, fileCount));
+};
+
+/**
+ * Run the type-generation phase across worker threads. Files are sharded
+ * round-robin so heavy files spread across workers. Each worker builds its own
+ * program over `projectFiles`; the per-file AST and type set are identical to
+ * the single-threaded path, except that a small number of inferred union types
+ * may have their members printed in a different order (see resolveTypeWorkerCount).
+ * Returns true only if every worker completed cleanly; on any failure the
+ * caller falls back to inline processing (writes are idempotent, so
+ * re-processing is safe).
+ */
+const runTypeGenerationInWorkers = (
+  srcFiles,
+  projectFiles,
+  options,
+  workerCount
+) => {
+  const shards = Array.from({ length: workerCount }, () => []);
+  srcFiles.forEach((file, index) => shards[index % workerCount].push(file));
+  const workerEntry = fileURLToPath(import.meta.url);
+  return Promise.all(
+    shards.map((shard, index) => {
+      if (shard.length === 0) {
+        return Promise.resolve(true);
+      }
+      return new Promise((resolvePromise) => {
+        let settled = false;
+        const settle = (value) => {
+          if (!settled) {
+            settled = true;
+            resolvePromise(value);
+          }
+        };
+        try {
+          const worker = new Worker(workerEntry, {
+            workerData: {
+              kind: "astgen-typegen",
+              shard,
+              projectFiles,
+              options,
+              index
+            }
+          });
+          worker.on("error", (err) => {
+            console.error("astgen type worker failed:", err?.message || err);
+            settle(false);
+          });
+          worker.on("exit", (code) => settle(code === 0));
+        } catch (err) {
+          console.error("Unable to start astgen type worker:", err?.message);
+          settle(false);
+        }
+      });
+    })
+  ).then((results) => results.every(Boolean));
+};
+
 /**
  * Generate AST for JavaScript or TypeScript
  */
 const createJSAst = async (options) => {
   try {
-    const promiseMap = await getAllSrcJSAndTSFiles(options.src);
-    let srcFiles = promiseMap.flatMap((d) => d).sort();
-    let ts;
-    if (options.tsTypes) {
-      const projectFiles = !shouldIncludeNodeModulesBundles
-        ? srcFiles.filter((file) => !file.includes("node_modules"))
-        : srcFiles;
-      ts = createTsc(projectFiles, options.src);
-      if (ts?.rootNames) {
-        const srcRoot = resolve(options.src);
-        const srcFileByResolvedPath = new Map(
-          srcFiles.map((file) => [resolve(file), file])
-        );
-        for (const file of ts.rootNames) {
-          const resolvedFile = resolve(file);
-          if (
-            resolvedFile.startsWith(srcRoot) &&
-            /\.(?:js|jsx|cjs|mjs|ts|tsx|mts|cts)$/.test(file) &&
-            !srcFileByResolvedPath.has(resolvedFile)
-          ) {
-            srcFileByResolvedPath.set(
-              resolvedFile,
-              join(options.src, relative(srcRoot, resolvedFile))
-            );
-          }
-        }
-        srcFiles = [...srcFileByResolvedPath.values()].sort();
-      }
+    const discovered = await getAllSrcJSAndTSFiles(options.src);
+    let srcFiles = [...discovered].sort();
+
+    if (!options.tsTypes) {
+      await processFilesInline(srcFiles, options, undefined);
+      return;
     }
-    const CONCURRENCY_LIMIT = Math.max(
-      1,
-      Number.parseInt(process.env.ASTGEN_CONCURRENCY || "10", 10) || 10
+
+    const projectFiles = !shouldIncludeNodeModulesBundles
+      ? srcFiles.filter((file) => !file.includes("node_modules"))
+      : srcFiles;
+    // Compute the program root names from the parsed tsconfig without building
+    // a program on the main thread, then expand the output file set to match.
+    const tscConfig = createTscProgramConfig(projectFiles, options.src);
+    srcFiles = expandSrcFilesWithRootNames(
+      srcFiles,
+      tscConfig?.rootNames,
+      options.src
     );
-    const chunks = [];
-    for (let i = 0; i < srcFiles.length; i += CONCURRENCY_LIMIT) {
-      chunks.push(srcFiles.slice(i, i + CONCURRENCY_LIMIT));
-    }
-    for (const chunk of chunks) {
-      await Promise.all(chunk.map((file) => processFile(file, options, ts)));
-      if (typeof globalThis.gc === "function") {
-        try {
-          globalThis.gc();
-        } catch (e) {
-          // ignore
-        }
-      } else if (typeof Bun !== "undefined" && typeof Bun.gc === "function") {
-        try {
-          Bun.gc(true);
-        } catch (e) {
-          // ignore
-        }
+
+    const workerCount = resolveTypeWorkerCount(srcFiles.length);
+    if (workerCount > 1) {
+      const ranInParallel = await runTypeGenerationInWorkers(
+        srcFiles,
+        projectFiles,
+        options,
+        workerCount
+      );
+      if (ranInParallel) {
+        return;
       }
+      console.error(
+        "Falling back to single-threaded type generation after worker failure."
+      );
     }
+
+    const ts = createTsc(projectFiles, options.src);
+    await processFilesInline(srcFiles, options, ts);
   } catch (err) {
     console.error(err);
   }
@@ -1602,25 +2039,12 @@ const createJSAst = async (options) => {
 
 const processFile = (file, options, ts) => {
   try {
-    const ast = fileToJsAst(file, options.type);
+    const ast = fileToJsAst(file, options.type, ts);
     writeAstFile(file, ast, options);
-    if (ts) {
-      try {
-        const tsAst = ts.program.getSourceFile(file);
-        if (tsAst) {
-          const seenTypes = ts.collectTypes
-            ? ts.collectTypes(tsAst)
-            : (() => {
-                tsc.forEachChild(tsAst, ts.addType);
-                const collectedTypes = new Map(ts.seenTypes);
-                ts.seenTypes.clear();
-                return collectedTypes;
-              })();
-          writeTypesFile(file, seenTypes, options);
-        }
-      } catch (err) {
-        console.warn("Process file", file, ":", err.message);
-      }
+
+    const seenTypes = collectSeenTypesForFile(file, ts, options);
+    if (seenTypes && seenTypes.size > 0) {
+      writeTypesFile(file, seenTypes, options);
     }
   } catch (err) {
     console.error("Failure:", file, err?.message);
@@ -1650,6 +2074,12 @@ const createVueAst = async (options) => {
 const getCircularReplacer = () => {
   const seen = new WeakSet();
   return (key, value) => {
+    // Babel 8 emits BigIntLiteral/`extra.value` as a native bigint, which
+    // JSON.stringify cannot serialize. Emit it as a string, which also matches
+    // the Babel 7 shape (BigIntLiteral.value was already a string there).
+    if (typeof value === "bigint") {
+      return value.toString();
+    }
     if (typeof value === "object" && value !== null) {
       if (seen.has(value)) {
         return;
@@ -1758,4 +2188,25 @@ async function main(argvs) {
   }
 }
 
-main(process.argv);
+/**
+ * Type-generation worker entry point. Runs in a worker thread spawned by
+ * runTypeGenerationInWorkers: builds its own TypeScript program over the full
+ * project file set and processes only its assigned shard, so cross-file type
+ * resolution is identical to the single-threaded path.
+ */
+const runTypeGenWorker = async ({ shard, projectFiles, options }) => {
+  try {
+    const ts = createTsc(projectFiles, options.src);
+    await processFilesInline(shard, options, ts);
+    parentPort?.postMessage({ done: true });
+  } catch (err) {
+    console.error(err);
+    process.exit(1);
+  }
+};
+
+if (isMainThread) {
+  main(process.argv);
+} else if (workerData?.kind === "astgen-typegen") {
+  runTypeGenWorker(workerData);
+}

package/package.json

@@ -1,21 +1,24 @@
 {
   "name": "@appthreat/atom-parsetools",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Parsing tools that complement the @appthreat/atom project.",
   "main": "./index.js",
   "type": "module",
   "scripts": {
     "pretty": "prettier --write *.js --trailing-comma=none",
-    "test": "node test-fixtures/astgen-type-regression.js && node test-fixtures/astgen-json-regression.js && node test-fixtures/evaluate-astgen.js",
+    "test": "node test-fixtures/astgen-type-regression.js && node test-fixtures/astgen-json-regression.js && node test-fixtures/astgen-vue-regression.js && node test-fixtures/astgen-shape-snapshot.js && node test-fixtures/evaluate-astgen.js",
     "test:evaluate": "node test-fixtures/evaluate-astgen.js",
+    "test:shape": "node test-fixtures/astgen-shape-snapshot.js",
+    "test:shape:update": "UPDATE_SHAPE_SNAPSHOT=1 node test-fixtures/astgen-shape-snapshot.js",
     "test:json": "node test-fixtures/astgen-json-regression.js",
-    "test:fixtures": "node test-fixtures/test-suite.js"
+    "test:fixtures": "node test-fixtures/test-suite.js",
+    "test:vue": "node test-fixtures/astgen-vue-regression.js"
   },
   "dependencies": {
     "@appthreat/atom-common": "^1.1.0",
-    "@babel/parser": "^7.29.3",
-    "hermes-parser": "^0.36.1",
-    "typescript": "^6.0.3"
+    "@babel/parser": "^8.0.4",
+    "@typescript/typescript6": "^6.0.2",
+    "hermes-parser": "^0.37.0"
   },
   "bin": {
     "astgen": "astgen.js",
@@ -24,7 +27,7 @@
     "scalasem": "scalasem.js"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=22.0.0"
   },
   "repository": {
     "type": "git",

package/plugins/composer/installed.php

@@ -1,9 +1,9 @@
 <?php return array(
     'root' => array(
         'name' => '__root__',
-        'pretty_version' => 'v1.2.1',
-        'version' => '1.2.1.0',
-        'reference' => 'afc68f061af5b27948f4408573df918fdbda4162',
+        'pretty_version' => 'v1.3.0',
+        'version' => '1.3.0.0',
+        'reference' => '65d96106e47fe9607cec2ba1be69da7c9c4d574c',
         'type' => 'library',
         'install_path' => __DIR__ . '/../../',
         'aliases' => array(),
@@ -11,9 +11,9 @@
     ),
     'versions' => array(
         '__root__' => array(
-            'pretty_version' => 'v1.2.1',
-            'version' => '1.2.1.0',
-            'reference' => 'afc68f061af5b27948f4408573df918fdbda4162',
+            'pretty_version' => 'v1.3.0',
+            'version' => '1.3.0.0',
+            'reference' => '65d96106e47fe9607cec2ba1be69da7c9c4d574c',
             'type' => 'library',
             'install_path' => __DIR__ . '/../../',
             'aliases' => array(),

package/plugins/rubyastgen/bundle/ruby/4.0.0/extensions/x86_64-linux/4.0.0/prism-1.9.0/gem_make.out

@@ -6,10 +6,10 @@ checking for whether -fvisibility=hidden is accepted as CFLAGS... yes
 creating Makefile
 
 current directory: /home/runner/work/atom-parsetools/atom-parsetools/plugins/rubyastgen/bundle/ruby/4.0.0/gems/prism-1.9.0/ext/prism
-make -j5 DESTDIR\= sitearchdir\=./.gem.20260527-2573-bep84q sitelibdir\=./.gem.20260527-2573-bep84q clean
+make -j5 DESTDIR\= sitearchdir\=./.gem.20260807-2447-y3xzkz sitelibdir\=./.gem.20260807-2447-y3xzkz clean
 
 current directory: /home/runner/work/atom-parsetools/atom-parsetools/plugins/rubyastgen/bundle/ruby/4.0.0/gems/prism-1.9.0/ext/prism
-make -j5 DESTDIR\= sitearchdir\=./.gem.20260527-2573-bep84q sitelibdir\=./.gem.20260527-2573-bep84q
+make -j5 DESTDIR\= sitearchdir\=./.gem.20260807-2447-y3xzkz sitelibdir\=./.gem.20260807-2447-y3xzkz
 compiling api_node.c
 compiling api_pack.c
 compiling extension.c
@@ -37,8 +37,8 @@ compiling ./../../src/util/pm_strpbrk.c
 linking shared-object prism/prism.so
 
 current directory: /home/runner/work/atom-parsetools/atom-parsetools/plugins/rubyastgen/bundle/ruby/4.0.0/gems/prism-1.9.0/ext/prism
-make -j5 DESTDIR\= sitearchdir\=./.gem.20260527-2573-bep84q sitelibdir\=./.gem.20260527-2573-bep84q install
-/usr/bin/install -c -m 0755 prism.so ./.gem.20260527-2573-bep84q/prism
+make -j5 DESTDIR\= sitearchdir\=./.gem.20260807-2447-y3xzkz sitelibdir\=./.gem.20260807-2447-y3xzkz install
+/usr/bin/install -c -m 0755 prism.so ./.gem.20260807-2447-y3xzkz/prism
 
 current directory: /home/runner/work/atom-parsetools/atom-parsetools/plugins/rubyastgen/bundle/ruby/4.0.0/gems/prism-1.9.0/ext/prism
-make DESTDIR\= sitearchdir\=./.gem.20260527-2573-bep84q sitelibdir\=./.gem.20260527-2573-bep84q clean
+make DESTDIR\= sitearchdir\=./.gem.20260807-2447-y3xzkz sitelibdir\=./.gem.20260807-2447-y3xzkz clean

package/plugins/rubyastgen/bundle/ruby/4.0.0/extensions/x86_64-linux/4.0.0/racc-1.8.1/gem_make.out

@@ -3,16 +3,16 @@ current directory: /home/runner/work/atom-parsetools/atom-parsetools/plugins/rub
 creating Makefile
 
 current directory: /home/runner/work/atom-parsetools/atom-parsetools/plugins/rubyastgen/bundle/ruby/4.0.0/gems/racc-1.8.1/ext/racc/cparse
-make -j5 DESTDIR\= sitearchdir\=./.gem.20260527-2573-dcu8v1 sitelibdir\=./.gem.20260527-2573-dcu8v1 clean
+make -j5 DESTDIR\= sitearchdir\=./.gem.20260807-2447-krkev6 sitelibdir\=./.gem.20260807-2447-krkev6 clean
 
 current directory: /home/runner/work/atom-parsetools/atom-parsetools/plugins/rubyastgen/bundle/ruby/4.0.0/gems/racc-1.8.1/ext/racc/cparse
-make -j5 DESTDIR\= sitearchdir\=./.gem.20260527-2573-dcu8v1 sitelibdir\=./.gem.20260527-2573-dcu8v1
+make -j5 DESTDIR\= sitearchdir\=./.gem.20260807-2447-krkev6 sitelibdir\=./.gem.20260807-2447-krkev6
 compiling cparse.c
 linking shared-object racc/cparse.so
 
 current directory: /home/runner/work/atom-parsetools/atom-parsetools/plugins/rubyastgen/bundle/ruby/4.0.0/gems/racc-1.8.1/ext/racc/cparse
-make -j5 DESTDIR\= sitearchdir\=./.gem.20260527-2573-dcu8v1 sitelibdir\=./.gem.20260527-2573-dcu8v1 install
-/usr/bin/install -c -m 0755 cparse.so ./.gem.20260527-2573-dcu8v1/racc
+make -j5 DESTDIR\= sitearchdir\=./.gem.20260807-2447-krkev6 sitelibdir\=./.gem.20260807-2447-krkev6 install
+/usr/bin/install -c -m 0755 cparse.so ./.gem.20260807-2447-krkev6/racc
 
 current directory: /home/runner/work/atom-parsetools/atom-parsetools/plugins/rubyastgen/bundle/ruby/4.0.0/gems/racc-1.8.1/ext/racc/cparse
-make DESTDIR\= sitearchdir\=./.gem.20260527-2573-dcu8v1 sitelibdir\=./.gem.20260527-2573-dcu8v1 clean
+make DESTDIR\= sitearchdir\=./.gem.20260807-2447-krkev6 sitelibdir\=./.gem.20260807-2447-krkev6 clean