rolldown-plugin-dts 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![Unit Test](https://github.com/sxzz/rolldown-plugin-dts/actions/workflows/unit-test.yml/badge.svg)](https://github.com/sxzz/rolldown-plugin-dts/actions/workflows/unit-test.yml)
 
-A Rolldown plugin to bundle dts files.
+A Rolldown plugin to generate and bundle dts files.
 
 ## Install
 
@@ -18,24 +18,59 @@ Add the plugin to your `rolldown.config.js`:
 // rolldown.config.js
 import { dts } from 'rolldown-plugin-dts'
 
-const config = [
-  {
-    input: './index.d.ts',
-    plugins: [dts()],
-    output: [
-      {
-        file: 'dist/index.d.ts',
-        format: 'es',
-      },
-    ],
-  },
-]
-
-export default config
+export default {
+  input: './src/index.ts',
+  plugins: [dts()],
+  output: [{ dir: 'dist', format: 'es' }],
+}
 ```
 
-> [!NOTE]
-> Namespaces are not supported yet.
+You can find a real demo in [here](./rolldown.config.ts).
+
+## Options
+
+````ts
+interface Options {
+  /**
+   * When entries are `.d.ts` files (instead of `.ts` files), this option should be set to `true`.
+   *
+   * If enabled, the plugin will skip generating a `.d.ts` file for the entry point.
+   */
+  dtsInput?: boolean
+
+  isolatedDeclaration?: Omit<IsolatedDeclarationsOptions, 'sourcemap'>
+
+  /**
+   * dts file name alias `{ [filename]: path }`
+   *
+   * @example
+   * ```ts
+   * inputAlias: {
+   *   'foo.d.ts': 'foo/index.d.ts',
+   * }
+   */
+  inputAlias?: Record<string, string>
+
+  /**
+   * Determines whether the module imported by `.d.ts` files should be treated as external or not.
+   */
+  external?: (
+    id: string,
+    importer: string,
+    extraOptions: ResolveIdExtraOptions,
+  ) => boolean | void
+}
+````
+
+## Caveats
+
+- The plugin uses Oxc's `isolatedDeclarations` to generate `.d.ts` files,
+  which means you need to set `isolatedDeclarations: true` in your `tsconfig.json` and ensure there are no errors.
+
+- Namespaces are not supported yet.
+  - `export * as ns from './ns'`
+  - `import * as ns from './ns'` and then `export { ns }`
+  - `type ns = import('./ns')`
 
 ## Credits
 

package/dist/index.d.ts

@@ -1,7 +1,40 @@
-import { Plugin } from "rolldown";
+import { IsolatedDeclarationsOptions } from "oxc-transform";
+import { FunctionPluginHooks, Plugin } from "rolldown";
 
-//#region dist/.tsdown-types-es/index.d.ts
-declare function dts(): Plugin;
+//#region src/fake-js.d.ts
+declare function createFakeJsPlugin({ dtsInput }: Pick<Options, "dtsInput">): Plugin;
 
 //#endregion
-export { dts };
+//#region src/generate.d.ts
+declare function createGeneratePlugin({ isolatedDeclaration, inputAlias, external }: Pick<Options, "external" | "isolatedDeclaration" | "inputAlias">): Plugin;
+
+//#endregion
+//#region src/index.d.ts
+type ResolveIdExtraOptions = Parameters<FunctionPluginHooks["resolveId"]>[2];
+interface Options {
+	/**
+	* When entries are `.d.ts` files (instead of `.ts` files), this option should be set to `true`.
+	*
+	* If enabled, the plugin will skip generating a `.d.ts` file for the entry point.
+	*/
+	dtsInput?: boolean;
+	isolatedDeclaration?: Omit<IsolatedDeclarationsOptions, "sourcemap">;
+	/**
+	* dts file name alias `{ [filename]: path }`
+	*
+	* @example
+	* ```ts
+	* inputAlias: {
+	*   'foo.d.ts': 'foo/index.d.ts',
+	* }
+	*/
+	inputAlias?: Record<string, string>;
+	/**
+	* Determines whether the module imported by `.d.ts` files should be treated as external or not.
+	*/
+	external?: (id: string, importer: string, extraOptions: ResolveIdExtraOptions) => boolean | void;
+}
+declare function dts(options?: Options): Plugin[];
+
+//#endregion
+export { Options, createFakeJsPlugin, createGeneratePlugin, dts };

package/dist/index.js

@@ -1,6 +1,7 @@
-import path from "node:path";
 import { MagicStringAST } from "magic-string-ast";
 import { parseAsync } from "oxc-parser";
+import path, { basename } from "node:path";
+import { isolatedDeclaration } from "oxc-transform";
 
 //#region node_modules/.pnpm/estree-walker@3.0.3/node_modules/estree-walker/src/walker.js
 var WalkerBase = class {
@@ -110,10 +111,10 @@ var SyncWalker = class extends WalkerBase {
 				if (value && typeof value === "object") {
 					if (Array.isArray(value)) {
 						const nodes = value;
-						for (let i$1 = 0; i$1 < nodes.length; i$1 += 1) {
-							const item = nodes[i$1];
+						for (let i = 0; i < nodes.length; i += 1) {
+							const item = nodes[i];
 							if (isNode(item)) {
-								if (!this.visit(item, node, key, i$1)) i$1--;
+								if (!this.visit(item, node, key, i)) i--;
 							}
 						}
 					} else if (isNode(value)) this.visit(value, node, key, null);
@@ -163,25 +164,49 @@ function getIdentifierRange(node, offset = 0) {
 	return [node.start + offset, node.end + offset];
 }
 
+//#endregion
+//#region src/utils/filename.ts
+const RE_JS = /\.([cm]?)js$/;
+const RE_TS = /\.([cm]?)ts$/;
+const RE_DTS = /\.d\.([cm]?)ts$/;
+const RE_NODE_MODULES = /node_modules/;
+function filename_js_to_dts(id) {
+	return id.replace(RE_JS, ".d.$1ts");
+}
+function filename_ts_to_dts(id) {
+	return id.replace(RE_TS, ".d.$1ts");
+}
+function filename_dts_to(id, ext) {
+	return id.replace(RE_DTS, `.$1${ext}`);
+}
+function isRelative(id) {
+	return path.isAbsolute(id) || id[0] === ".";
+}
+
 //#endregion
 //#region src/utils/magic-string.ts
-function overwriteOrAppend(s, range, replacement) {
+function overwriteOrAppend(s, range, replacement, suffix) {
 	if (range[0] === range[1]) {
 		s.appendLeft(range[0], ` ${replacement}`);
 		return;
 	}
-	s.overwrite(range[0], range[1], replacement);
+	const original = s.slice(range[0], range[1]);
+	if (original !== replacement) s.overwrite(range[0], range[1], replacement + (suffix || ""));
 }
 
 //#endregion
-//#region src/index.ts
+//#region src/fake-js.ts
 const RE_TYPE = /\btype\b/;
-function dts() {
-	let i$1 = 0;
+function createFakeJsPlugin({ dtsInput }) {
+	let symbolIdx = 0;
+	let identifierIdx = 0;
 	const symbolMap = new Map();
-	const commentMap = new Map();
+	const preserveMap = new Map();
+	function getIdentifierIndex() {
+		return identifierIdx++;
+	}
 	function register(info) {
-		const symbolId = i$1++;
+		const symbolId = symbolIdx++;
 		symbolMap.set(symbolId, info);
 		return symbolId;
 	}
@@ -189,8 +214,8 @@ function dts() {
 		return symbolMap.get(symbolId);
 	}
 	return {
-		name: "rolldown-plugin-dts",
-		options({ onLog,...options }) {
+		name: "rolldown-plugin-dts:fake-js",
+		options: dtsInput ? (options) => {
 			return {
 				...options,
 				resolve: {
@@ -205,85 +230,87 @@ function dts() {
 						".cjs": [".d.cts"]
 					},
 					...options.resolve
-				},
-				onLog(level, log, defaultHandler) {
-					if (level === "warn" && log.code === "CIRCULAR_DEPENDENCY") return;
-					if (onLog) onLog(level, log, defaultHandler);
-					else defaultHandler(level, log);
-				},
-				treeshake: {
-					moduleSideEffects: "no-external",
-					unknownGlobalSideEffects: false
 				}
 			};
-		},
+		} : void 0,
 		outputOptions(options) {
 			return {
-				chunkFileNames: "[name]-[hash].d.ts",
-				entryFileNames: "[name].ts",
-				format: "es",
-				exports: "named",
-				...options
-			};
-		},
-		resolveId(id, importer) {
-			if (importer && !path.isAbsolute(id) && id[0] !== ".") return {
-				id,
-				external: true
+				...options,
+				entryFileNames: options.entryFileNames ?? (dtsInput ? "[name].ts" : void 0),
+				chunkFileNames(chunk) {
+					const original = (typeof options.chunkFileNames === "function" ? options.chunkFileNames(chunk) : options.chunkFileNames) || "[name]-[hash].js";
+					if (chunk.name.endsWith(".d")) return filename_js_to_dts(original);
+					return original;
+				}
 			};
 		},
-		async transform(code, id) {
-			const { program, comments } = await parseAsync(id, code);
-			const preserveComments = collectReferenceDirectives(comments);
-			commentMap.set(id, preserveComments);
-			const s = new MagicStringAST(code);
-			for (let node of program.body) {
-				if (rewriteImportExport(s, node)) continue;
-				const stmt = node;
-				const isDefaultExport = node.type === "ExportDefaultDeclaration";
-				if ((node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration") && node.declaration) node = node.declaration;
-				if (node.type === "VariableDeclaration" && node.declarations.length !== 1) throw new Error("Only one declaration is supported");
-				if (node.type === "TSDeclareFunction" || node.type.endsWith("Declaration")) {
-					const binding = node.type === "VariableDeclaration" ? node.declarations[0].id : node.id;
-					const code$1 = s.sliceNode(node);
-					const jsdoc = comments.find((c) => c.type === "Block" && c.value[0] === "*" && stmt.start - c.end <= 1);
-					const offset = node.start;
-					let bindingRange;
-					if (binding) bindingRange = getIdentifierRange(binding, -offset);
-					else if (isDefaultExport) {
-						const idx = s.sliceNode(node).indexOf("function") + 8;
-						bindingRange = [idx, idx];
-					} else continue;
-					const deps = collectDependencies(s, node);
-					const depsString = stringifyDependencies(s, deps);
-					const depsRanges = deps.map((dep) => [dep.start - offset, dep.end - offset]);
-					const needDeclare = (node.type === "TSEnumDeclaration" || node.type === "ClassDeclaration" || node.type === "FunctionDeclaration" || node.type === "TSDeclareFunction" || node.type === "TSModuleDeclaration" || node.type === "VariableDeclaration") && !node.declare;
-					const symbolId = register({
-						code: code$1,
-						binding: bindingRange,
-						deps: depsRanges,
-						needDeclare,
-						jsdoc: jsdoc ? s.sliceNode(jsdoc) : void 0
-					});
-					const runtime = `[${symbolId}, ${depsString}]`;
-					const bindingName = binding ? s.sliceNode(binding) : "export_default";
-					if (isDefaultExport) s.overwriteNode(stmt, `var ${bindingName} = ${runtime};export { ${bindingName} as default }`);
-					else s.overwriteNode(node, `var ${bindingName} = [${symbolId}, ${depsString}]`);
+		transform: {
+			filter: { id: {
+				include: [RE_DTS],
+				exclude: [RE_NODE_MODULES]
+			} },
+			async handler(code, id) {
+				const { program, comments } = await parseAsync(id, code);
+				const preserved = collectReferenceDirectives(comments);
+				preserveMap.set(id, preserved);
+				const s = new MagicStringAST(code);
+				for (let node of program.body) {
+					if (node.type === "ExportAllDeclaration" && node.exported && isRelative(node.source.value)) throw new Error("`export * as foo from './...'` is not supported");
+					if (rewriteImportExport(s, node)) continue;
+					const sideEffect = node.type === "TSModuleDeclaration" && node.kind !== "namespace";
+					const stmt = node;
+					const isDefaultExport = node.type === "ExportDefaultDeclaration";
+					if ((node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration") && node.declaration) node = node.declaration;
+					if (node.type === "VariableDeclaration" && node.declarations.length !== 1) throw new Error("Only one declaration is supported");
+					if (node.type === "TSDeclareFunction" || node.type.endsWith("Declaration")) {
+						const binding = node.type === "VariableDeclaration" ? node.declarations[0].id : node.id;
+						const code$1 = s.sliceNode(node);
+						const jsdoc = comments.find((c) => c.type === "Block" && c.value[0] === "*" && c.start < node.start && stmt.start - c.end <= 1);
+						const offset = node.start;
+						let bindingRange;
+						if (sideEffect) bindingRange = [0, 0];
+						else if (binding) bindingRange = getIdentifierRange(binding, -offset);
+						else if (isDefaultExport) {
+							const idx = s.sliceNode(node).indexOf("function") + 8;
+							bindingRange = [idx, idx];
+						} else continue;
+						const depsNodes = collectDependencies(s, node, getIdentifierIndex);
+						const depsString = stringifyDependencies(s, depsNodes);
+						const depsSymbols = depsNodes.map((dep) => [
+							dep.start - offset,
+							dep.end - offset,
+							dep._suffix
+						]);
+						const needDeclare = (node.type === "TSEnumDeclaration" || node.type === "ClassDeclaration" || node.type === "FunctionDeclaration" || node.type === "TSDeclareFunction" || node.type === "TSModuleDeclaration" || node.type === "VariableDeclaration") && !node.declare;
+						const symbolId = register({
+							code: code$1,
+							binding: bindingRange,
+							deps: depsSymbols,
+							needDeclare,
+							jsdoc: jsdoc ? s.sliceNode(jsdoc) : void 0,
+							preserveName: sideEffect
+						});
+						const runtime = `[${symbolId}, ${depsString}${depsString && sideEffect ? ", " : ""}${sideEffect ? "sideEffect()" : ""}]`;
+						const bindingName = sideEffect ? `_${identifierIdx++}` : binding ? s.sliceNode(binding) : "export_default";
+						if (isDefaultExport) s.overwriteNode(stmt, `var ${bindingName} = ${runtime};export { ${bindingName} as default }`);
+						else s.overwriteNode(node, `var ${bindingName} = ${runtime};`);
+					}
 				}
+				if (!s.hasChanged()) return;
+				const str = s.toString();
+				return str;
 			}
-			if (!s.hasChanged()) return;
-			const str = s.toString();
-			return str;
 		},
 		async renderChunk(code, chunk) {
+			if (!RE_DTS.test(chunk.fileName)) return;
 			const { program } = await parseAsync(chunk.fileName, code);
 			const s = new MagicStringAST(code);
 			const comments = new Set();
 			for (const id of chunk.moduleIds) {
-				const preserveComments = commentMap.get(id);
+				const preserveComments = preserveMap.get(id);
 				if (preserveComments) {
 					preserveComments.forEach((c) => comments.add(c));
-					commentMap.delete(id);
+					preserveMap.delete(id);
 				}
 			}
 			if (comments.size) s.prepend(`${[...comments].join("\n")}\n`);
@@ -301,14 +328,14 @@ function dts() {
 					continue;
 				}
 				const symbolId = symbolIdNode.value;
-				const { code: code$1, binding, deps, needDeclare, jsdoc } = retrieve(symbolId);
-				const depsRaw = depsNodes.map((dep) => {
-					if (dep.type !== "ArrowFunctionExpression") throw new Error("Expected ArrowFunctionExpression");
-					return s.sliceNode(dep.body);
-				});
+				const { code: code$1, binding, deps, needDeclare, jsdoc, preserveName } = retrieve(symbolId);
+				const depsRaw = depsNodes.filter((node$1) => node$1?.type === "ArrowFunctionExpression").map((dep) => s.sliceNode(dep.body));
 				const ss = new MagicStringAST(code$1);
-				overwriteOrAppend(ss, binding, s.sliceNode(decl.id));
-				for (const dep of deps) overwriteOrAppend(ss, dep, depsRaw.shift());
+				if (!preserveName) overwriteOrAppend(ss, binding, s.sliceNode(decl.id));
+				for (const dep of deps) {
+					const [start, end, suffix] = dep;
+					overwriteOrAppend(ss, [start, end], depsRaw.shift(), suffix);
+				}
 				if (needDeclare) ss.prepend("declare ");
 				if (jsdoc) ss.prepend(`${jsdoc}\n`);
 				s.overwriteNode(node, ss.toString());
@@ -323,10 +350,19 @@ const REFERENCE_RE = /\/\s*<reference\s+(?:path|types)=/;
 function collectReferenceDirectives(comment) {
 	return comment.filter((c) => REFERENCE_RE.test(c.value)).map((c) => `//${c.value}`);
 }
-function collectDependencies(s, node) {
+function collectDependencies(s, node, getIdentifierIndex) {
 	const deps = new Set();
 	walk(node, { leave(node$1) {
-		if (node$1.type === "TSInterfaceDeclaration" && node$1.extends) for (const heritage of node$1.extends || []) addDependency(heritage.expression);
+		if (node$1.type === "ExportNamedDeclaration") {
+			for (const specifier of node$1.specifiers) if (specifier.type === "ExportSpecifier") {
+				let _suffix;
+				if (specifier.local.start === specifier.exported.start && specifier.local.end === specifier.exported.end) _suffix = ` as ${s.sliceNode(specifier.local)}`;
+				addDependency({
+					...specifier.local,
+					_suffix
+				});
+			}
+		} else if (node$1.type === "TSInterfaceDeclaration" && node$1.extends) for (const heritage of node$1.extends || []) addDependency(heritage.expression);
 		else if (node$1.type === "ClassDeclaration") {
 			if (node$1.superClass) addDependency(node$1.superClass);
 			if (node$1.implements) for (const implement of node$1.implements) addDependency(implement.expression);
@@ -340,7 +376,7 @@ function collectDependencies(s, node) {
 			if (!node$1.qualifier) throw new Error("Import namespace is not supported");
 			const source = node$1.argument.literal.value;
 			const imported = s.sliceNode(node$1.qualifier);
-			const local = importNamespace(s, source, imported);
+			const local = importNamespace(s, source, imported, getIdentifierIndex);
 			addDependency({
 				type: "Identifier",
 				name: local,
@@ -365,10 +401,9 @@ function patchVariableDeclarator(s, node, decl) {
 	if (decl.init && !decl.id.typeAnnotation) s.overwriteNode(node, `type ${s.sliceNode(decl.id)} = ${s.sliceNode(decl.init)}`);
 	else if (!node.declare) s.prependLeft(node.start, "declare ");
 }
-const RE_D_TS = /\.d\.([cm]?)ts$/;
 function patchImportSource(s, node) {
-	if ((node.type === "ImportDeclaration" || node.type === "ExportAllDeclaration" || node.type === "ExportNamedDeclaration") && node.source?.value && RE_D_TS.test(node.source.value)) {
-		s.overwriteNode(node.source, JSON.stringify(node.source.value.replace(RE_D_TS, ".$1js")));
+	if ((node.type === "ImportDeclaration" || node.type === "ExportAllDeclaration" || node.type === "ExportNamedDeclaration") && node.source?.value && RE_DTS.test(node.source.value)) {
+		s.overwriteNode(node.source, JSON.stringify(filename_dts_to(node.source.value, "js")));
 		return true;
 	}
 }
@@ -393,12 +428,89 @@ function rewriteImportExport(s, node) {
 		return true;
 	}
 }
-let i = 0;
-function importNamespace(s, source, imported) {
-	const local = `_${i++}`;
+function importNamespace(s, source, imported, getIdentifierIndex) {
+	const local = `_${getIdentifierIndex()}`;
 	s.prepend(`import { ${imported} as ${local} } from ${JSON.stringify(source)};\n`);
 	return local;
 }
 
 //#endregion
-export { dts };
+//#region src/generate.ts
+function createGeneratePlugin({ isolatedDeclaration: isolatedDeclaration$1, inputAlias, external }) {
+	const dtsMap = new Map();
+	return {
+		name: "rolldown-plugin-dts:generate",
+		transform: {
+			order: "pre",
+			filter: { id: {
+				include: [RE_TS],
+				exclude: [RE_DTS, RE_NODE_MODULES]
+			} },
+			handler(code, id) {
+				const { code: dtsCode, errors } = isolatedDeclaration(id, code, isolatedDeclaration$1);
+				if (errors.length) return this.error(errors[0]);
+				const dtsId = filename_ts_to_dts(id);
+				dtsMap.set(dtsId, dtsCode);
+				const mod = this.getModuleInfo(id);
+				if (mod?.isEntry) {
+					let fileName = basename(dtsId);
+					if (inputAlias?.[fileName]) fileName = inputAlias[fileName];
+					this.emitFile({
+						type: "chunk",
+						id: dtsId,
+						fileName
+					});
+				}
+			}
+		},
+		async resolveId(id, importer, extraOptions) {
+			if (dtsMap.has(id)) return {
+				id,
+				meta: { dtsFile: true }
+			};
+			const importerMod = importer ? this.getModuleInfo(importer) : null;
+			if (importerMod?.meta.dtsFile) {
+				if (!isRelative(id) || external?.(id, importer, extraOptions) === true) return {
+					id,
+					external: true
+				};
+				const resolution = await this.resolve(id, filename_dts_to(importer, "ts"));
+				if (!resolution || resolution.external) return;
+				const dtsId = filename_ts_to_dts(resolution.id);
+				if (dtsMap.has(dtsId)) return {
+					id: dtsId,
+					meta: { dtsFile: true }
+				};
+				await this.load(resolution);
+				if (dtsMap.has(dtsId)) return {
+					id: dtsId,
+					meta: { dtsFile: true }
+				};
+			}
+		},
+		load: {
+			filter: { id: {
+				include: [RE_DTS],
+				exclude: [RE_NODE_MODULES]
+			} },
+			handler(id) {
+				if (dtsMap.has(id)) return {
+					code: dtsMap.get(id),
+					moduleSideEffects: false
+				};
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/index.ts
+function dts(options = {}) {
+	const plugins = [];
+	if (!options.dtsInput) plugins.push(createGeneratePlugin(options));
+	plugins.push(createFakeJsPlugin(options));
+	return plugins;
+}
+
+//#endregion
+export { createFakeJsPlugin, createGeneratePlugin, dts };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rolldown-plugin-dts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A Rolldown plugin to bundle dts files",
   "type": "module",
   "license": "MIT",
@@ -29,24 +29,25 @@
   },
   "dependencies": {
     "magic-string-ast": "^0.9.1",
-    "oxc-parser": "^0.62.0"
+    "oxc-parser": "^0.62.0",
+    "oxc-transform": "^0.62.0"
   },
   "devDependencies": {
     "@sxzz/eslint-config": "^6.1.1",
     "@sxzz/prettier-config": "^2.2.1",
     "@sxzz/test-utils": "^0.5.4",
     "@types/diff": "^7.0.2",
-    "@types/node": "^22.13.17",
+    "@types/node": "^22.14.0",
     "bumpp": "^10.1.0",
     "diff": "^7.0.0",
-    "eslint": "^9.23.0",
+    "eslint": "^9.24.0",
     "estree-walker": "^3.0.3",
     "prettier": "^3.5.3",
     "rolldown": "1.0.0-beta.7",
     "rollup-plugin-dts": "^6.2.1",
-    "tsdown": "^0.7.3",
+    "tsdown": "^0.8.0-beta.1",
     "tsx": "^4.19.3",
-    "typescript": "^5.8.2",
+    "typescript": "^5.8.3",
     "vitest": "^3.1.1"
   },
   "engines": {