fix: Add estree.Program type to rollup.d.ts (#5323)

* Includes Program type from estree

* Add @types/estree as a dependency

* Remove annotation type from the official type file

* Fix JSDoc types for internal scripts

* Change ProgramAst to ProgramNode

ProgramAst is a tautology as a Program IS the AST.
In the future, we may need names for other AST nodes,
so a naming scheme XXXNode should work well.

---------

Co-authored-by: Lukas Taegert-Atkinson <lukas.taegert-atkinson@tngtech.com>

browser/package.json

@@ -19,6 +19,9 @@
     "url": "https://github.com/rollup/rollup/issues"
   },
   "homepage": "https://rollupjs.org/",
+  "dependencies": {
+    "@types/estree": "1.0.5"
+  },
   "files": [
     "dist/**/*.wasm",
     "dist/**/*.js",

package.json

@@ -102,6 +102,9 @@
   "optionalDependencies": {
     "fsevents": "~2.3.2"
   },
+  "dependencies": {
+    "@types/estree": "1.0.5"
+  },
   "devDependenciesComments": {
     "@rollup/plugin-typescript": "It appears that 11.1.3 breaks sourcemaps"
   },
@@ -124,7 +127,6 @@
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "11.1.5",
     "@rollup/pluginutils": "^5.1.0",
-    "@types/estree": "1.0.5",
     "@types/inquirer": "^9.0.7",
     "@types/mocha": "^10.0.6",
     "@types/node": "18.0.0",

scripts/perf.js

@@ -106,7 +106,7 @@ function getAverage(accumulatedMeasurements, runs, discarded) {
 }
 
 /**
- * @param {import('rollup').MergedRollupOptions} config
+ * @param {import('../dist/rollup.js').MergedRollupOptions} config
  * @param {PersistedTimings} existingTimings
  * @return {Promise<void>}
  */
@@ -148,8 +148,8 @@ async function calculatePrintAndPersistTimings(config, existingTimings) {
 }
 
 /**
- * @param {import('rollup').MergedRollupOptions} config
- * @return {Promise<import('rollup').SerializedTimings>}
+ * @param {import('../dist/rollup.js').MergedRollupOptions} config
+ * @return {Promise<import('../dist/rollup.js').SerializedTimings>}
  */
 async function buildAndGetTimings(config) {
 	config.perf = true;

src/Graph.ts

@@ -5,10 +5,10 @@ import { ModuleLoader, type UnresolvedModule } from './ModuleLoader';
 import GlobalScope from './ast/scopes/GlobalScope';
 import { PathTracker } from './ast/utils/PathTracker';
 import type {
-	AstNode,
 	ModuleInfo,
 	ModuleJSON,
 	NormalizedInputOptions,
+	ProgramNode,
 	RollupCache,
 	RollupWatcher,
 	SerializablePluginCache,
@@ -52,7 +52,7 @@ function normalizeEntryModules(
 }
 
 export default class Graph {
-	readonly astLru = flru<AstNode>(5);
+	readonly astLru = flru<ProgramNode>(5);
 	readonly cachedModules = new Map<string, ModuleJSON>();
 	readonly deoptimizationTracker = new PathTracker();
 	entryModules: Module[] = [];

src/Module.ts

@@ -47,7 +47,6 @@ import type {
 } from './rollup/types';
 import { EMPTY_OBJECT } from './utils/blank';
 import { BuildPhase } from './utils/buildPhase';
-import type { ProgramAst } from './utils/convert-ast';
 import { decodedSourcemap, resetSourcemapCache } from './utils/decodedSourcemap';
 import { getId } from './utils/getId';
 import { getNewSet, getOrCreate } from './utils/getOrCreate';
@@ -1347,17 +1346,17 @@ export default class Module {
 		this.exports.set(name, MISSING_EXPORT_SHIM_DESCRIPTION);
 	}
 
-	private tryParse(): ProgramAst {
+	private tryParse() {
 		try {
-			return parseAst(this.info.code!) as ProgramAst;
+			return parseAst(this.info.code!);
 		} catch (error_: any) {
 			return this.error(logModuleParseError(error_, this.id), error_.pos);
 		}
 	}
 
-	private async tryParseAsync(): Promise<ProgramAst> {
+	private async tryParseAsync() {
 		try {
-			return (await parseAstAsync(this.info.code!)) as ProgramAst;
+			return await parseAstAsync(this.info.code!);
 		} catch (error_: any) {
 			return this.error(logModuleParseError(error_, this.id), error_.pos);
 		}

src/rollup/types.d.ts

@@ -1,3 +1,5 @@
+import type { Program } from 'estree';
+
 export const VERSION: string;
 
 // utils
@@ -98,13 +100,13 @@ interface ModuleOptions {
 }
 
 export interface SourceDescription extends Partial<PartialNull<ModuleOptions>> {
-	ast?: AstNode;
+	ast?: ProgramNode;
 	code: string;
 	map?: SourceMapInput;
 }
 
 export interface TransformModuleJSON {
-	ast?: AstNode;
+	ast?: ProgramNode;
 	code: string;
 	// note if plugins use new this.cache to opt-out auto transform cache
 	customTransformCache: boolean;
@@ -115,7 +117,7 @@ export interface TransformModuleJSON {
 }
 
 export interface ModuleJSON extends TransformModuleJSON, ModuleOptions {
-	ast: AstNode;
+	ast: ProgramNode;
 	dependencies: string[];
 	id: string;
 	resolvedIds: ResolvedIdMap;
@@ -171,7 +173,7 @@ export type EmittedFile = EmittedAsset | EmittedChunk | EmittedPrebuiltChunk;
 export type EmitFile = (emittedFile: EmittedFile) => string;
 
 interface ModuleInfo extends ModuleOptions {
-	ast: AstNode | null;
+	ast: ProgramNode | null;
 	code: string | null;
 	dynamicImporters: readonly string[];
 	dynamicallyImportedIdResolutions: readonly ResolvedId[];
@@ -204,7 +206,7 @@ type LoggingFunctionWithPosition = (
 export type ParseAst = (
 	input: string,
 	options?: { allowReturnOutsideFunction?: boolean }
-) => AstNode;
+) => ProgramNode;
 
 // declare AbortSignal here for environments without DOM lib or @types/node
 declare global {
@@ -214,7 +216,7 @@ declare global {
 export type ParseAstAsync = (
 	input: string,
 	options?: { allowReturnOutsideFunction?: boolean; signal?: AbortSignal }
-) => Promise<AstNode>;
+) => Promise<ProgramNode>;
 
 export interface PluginContext extends MinimalPluginContext {
 	addWatchFile: (id: string) => void;
@@ -280,7 +282,7 @@ export type ResolveIdHook = (
 export type ShouldTransformCachedModuleHook = (
 	this: PluginContext,
 	options: {
-		ast: AstNode;
+		ast: ProgramNode;
 		code: string;
 		id: string;
 		meta: CustomPluginOptions;
@@ -977,6 +979,8 @@ interface AstNode {
 	type: string;
 }
 
+type ProgramNode = Program & AstNode;
+
 export function defineConfig(options: RollupOptions): RollupOptions;
 export function defineConfig(options: RollupOptions[]): RollupOptions[];
 export function defineConfig(optionsFunction: RollupOptionsFunction): RollupOptionsFunction;

src/utils/convert-ast.ts

@@ -1,11 +1,11 @@
 import type * as estree from 'estree';
-import type { AstNode } from '../rollup/types';
+import type { AstNode, ProgramNode } from '../rollup/types';
 import { FIXED_STRINGS } from './convert-ast-strings';
 import { error, logParseError } from './logs';
 
 type ReadString = (start: number, length: number) => string;
 
-export const convertProgram = (buffer: ArrayBuffer, readString: ReadString): ProgramAst =>
+export const convertProgram = (buffer: ArrayBuffer, readString: ReadString): InternalProgramNode =>
 	convertNode(0, new Uint32Array(buffer), readString);
 
 const convertNode = (position: number, buffer: Uint32Array, readString: ReadString): any => {
@@ -826,7 +826,7 @@ const nodeConverters: ((position: number, buffer: Uint32Array, readString: ReadS
 		};
 	},
 	// index:53; Program
-	(position, buffer, readString): ProgramAst => {
+	(position, buffer, readString): InternalProgramNode => {
 		const start = buffer[position++];
 		const end = buffer[position++];
 		const annotations = convertAnnotationList(buffer[position++], buffer);
@@ -1259,7 +1259,6 @@ interface ArrowFunctionExpression extends estree.ArrowFunctionExpression {
 	[ANNOTATION_KEY]?: RollupAnnotation[];
 }
 
-export type ProgramAst = estree.Program &
-	AstNode & {
-		[INVALID_ANNOTATION_KEY]?: RollupAnnotation[];
-	};
+type InternalProgramNode = ProgramNode & {
+	[INVALID_ANNOTATION_KEY]?: RollupAnnotation[];
+};