dtsroll 1.5.0 → 1.7.0

package/README.md

@@ -1,152 +1,160 @@
 <p align="center">
-    <img width="150" src="./.github/logo.webp">
+  <img width="200" src="./.github/logo.webp">
 </p>
+<h2 align="center">dtsroll</h2>
 
-<h2 align="center">
-dtsroll
-</h2>
+Are you publishing a TypeScript project where consumers encounter type-checking errors like:
 
-_dtsroll_ is a CLI tool for bundling TypeScript declaration (`.d.ts`) files.
+```
+Cannot find module 'some-package' or its corresponding type declarations.
+```
 
-### Why bundle `.d.ts` files?
+When you compile with `tsc`, the emitted declaration files (`.d.ts` files) preserve imports exactly as written. So if your published types import from a `devDependency` or a private package (e.g. an internal monorepo package), those imports cannot be resolved by the consumer.
 
-- **Smaller distribution**
+```ts
+// dist/index.d.ts (generated by tsc)
+import type { SomeType } from 'my-private-dependency' // ❌ consumers can't resolve this
 
-	Tree-shaking removes unused code, keeping only what's needed and reducing the output size.
+export declare function myUtility(): SomeType
+```
 
-- **Bundle in private dependencies**
+If you can't move the dependency to `dependencies`, or you just want its types pulled directly into your published declarations, _dtsroll_ is for you.
 
-	Inline types from private dependencies (e.g., monorepo packages) that aren't accessible to consumers.
+## What is dtsroll?
 
-- **Improve TS performance**
+_dtsroll_ is a TypeScript declaration (`.d.ts`) file bundler. It's zero-config and reads your `package.json` to determine how your types should be bundled.
 
-	Flattens multiple files into one, reducing TypeScript's file resolution for type checking.
+### What dtsroll does
 
-<p align="center">
-    <img width="600" src="./.github/screenshot.webp">
-</p>
+_dtsroll_ runs *after your build when `.d.ts` files have been emitted*, and works in-place to bundle them to their entry points.
 
+Since packages declared in `devDependencies` are not installed for the consumer, _dtsroll_ assumes any imports referencing them should be bundled, as they would otherwise be unresolvable.
 
-## Install
-```
-npm install --save-dev dtsroll
-```
+The result is a single, clean `.d.ts` output that works for consumers without extra installs.
 
-## Quick start
+```ts
+// dist/index.d.ts (after dtsroll)
+type SomeType = {
+    value: string
+}
 
-1. Compile your TypeScript code with declaration (`.d.ts`) files
-	- If using the TypeScript compiler (`tsc`), enable [`declaration`](https://www.typescriptlang.org/tsconfig/#declaration)
-	- If using Vite, use a plugin like [vite-plugin-dts](https://www.npmjs.com/package/vite-plugin-dts)
+export declare function myUtility(): SomeType
+```
 
-2. Pass in the entry declaration file to _dtsroll_
+### Features
 
-	```sh
-	dtsroll --dry-run dist/index.d.ts
-	```
+- **Zero config** — Automatically finds entry points from `package.json`.
+- **Fixes missing-type errors** — Inlines types from `devDependencies` so consumers don't need them installed.
+- **Tree-shaken output** — Unused types are removed to keep files small.
+- **In-place** — Designed to run directly on your `dist` folder after compilation.
 
-> [!CAUTION]
-> _dtsroll_ is designed to run on compiled output so it modifies files in-place.
-> - It will modify files you pass in, and files they import.
-> - Only pass in backed up or generated files
-> - Start with `--dry-run`
+<p align="center">
+  <img width="600" src="./.github/screenshot.webp">
+</p>
+
+## Install
 
-3. If the changes look good, remove the `--dry-run` flag:
+```bash
+npm install --save-dev dtsroll
+```
 
-	```sh
-	dtsroll dist/index.d.ts
-	```
+## Quick start
 
-### Recommended setup
+### 1. Configure `package.json`
+
+Point your `types` or `exports` to the final `.d.ts` file you want to publish.
+
+```jsonc
+{
+	"name": "my-package",
+	"exports": {
+		"types": "./dist/index.d.ts", // dtsroll targets this
+		"default": "./dist/index.js",
+	},
+	"scripts": {
+		"build": "tsc && dtsroll",
+	},
+}
+```
 
-Running `dtsroll` without specifying input files will auto-detect them from `package.json`.
+### 2. Build
 
-Update your `package.json` to reference `.d.ts` files and include `dtsroll` in the build step:  
-```diff
- {
-     "name": "my-package",
-     "exports": {
-+        "types": "./dist/index.d.ts",
-         "default": "./dist/index.js"
-     },
-     "scripts": {
-+        "build": "tsc && dtsroll"
-     }
- }
+```bash
+npm run build
 ```
 
-### Externalization
+That's it.
 
-By default, _dtsroll_ decides which dependencies to bundle or keep external by analyzing the `package.json` file. Packages in `devDependencies` are bundled, and packages in other dependency types are externalized.
+> [!WARNING]
+> _dtsroll_ modifies files in-place—bundled source files are removed and entry files are overwritten with bundled output.
+> Use `--dry-run` first to see what it would change:
+>
+> ```bash
+> dtsroll --dry-run
+> ```
 
-When there is no `package.json` file, you can specify packages to externalize with the `--external` flag.
+## Behavior
 
-#### Handling `@types` packages
+### Automatic configuration
 
-Some packages need separate `@types/*` packages for type definitions. In this setup, typically:
+By default, _dtsroll_ reads your `package.json` to determine which imports should be bundled and which should remain external. The recommended setup is to run _dtsroll_ without any configuration and let it infer the correct behavior based on your dependency declarations.
 
-- The main package is in `dependencies`.
-- The corresponding `@types/*` package is in `devDependencies`.
+| Dependency type        | Action      | Reason                        |
+| ---------------------- | ----------- | ----------------------------- |
+| `devDependencies`      | Bundle      | Consumers don't install these |
+| `dependencies`         | Externalize | Consumers already have them   |
+| `optionalDependencies` | Externalize | Consumers already have them   |
+| `peerDependencies`     | Externalize | Provided by the consumer      |
 
-Because the main package is in `dependencies`,  _dtsroll_ externalizes it. However, consumers of your package won’t get the type definitions for it because the `@types/*` package is only in `devDependencies`.
+If you have a `@types/*` package in `devDependencies` but the corresponding runtime package in `dependencies`, _dtsroll_ will recommend moving the types package to `dependencies`, as this can otherwise result in missing types for consumers.
 
-To fix this, _dtsroll_ will display a warning suggesting you move the `@types/*` package out of `devDependencies`.
+### Manual configuration
 
-## CLI
+If your project doesn't have a `package.json` file, you can still manually specify the input files (which entry files to collapse the `imports` into), and which packages to externalize.
 
-### Usage
-```sh
-dtsroll [-flags] [...entry dts files]
-```
+### Subpath imports
 
-The default usage is to run `dtsroll` without any flags/arguments in a directory containing a `package.json` file. This allows the configuration to be inferred automatically.
+> [!WARNING]
+> Currently, _dtsroll_ mistakenly resolves and bundles [subpath imports](https://nodejs.org/api/packages.html#subpath-imports). Subpath imports are intended to be dynamic aliases controlled by the consumer. In a future breaking release, _dtsroll_ will likely externalize them to preserve this behavior.
 
-### --help, -h
-Display usage instructions.
+## Usage
 
-### --dry-run, -d
-Simulate the bundling process without modifying the disk and logs what would happen.
+_dtsroll_ can be used in several ways.
 
-### --external, -e
-If there is no `package.json` file, you can specify package names to exclude from the bundle.
+### CLI usage
 
-> [!NOTE]
-> This flag can only be used when there is no `package.json`. It's better to define dependencies appropriately in `package.json` instead of using this flag.
+```bash
+dtsroll [flags] [...entry .d.ts files]
+```
 
-### --conditions, -C
-Provide resolution conditions to target specific entry points in dependencies, similar to Node’s [`--conditions`](https://nodejs.org/api/cli.html#-c-condition---conditionscondition).
+If no entry files are provided, _dtsroll_ reads `package.json` to determine them.
 
-## Node.js API
-```ts
-import { dtsroll } from 'dtsroll'
+#### Flags
 
-await dtsroll(options as {
+| Flag           | Alias | Description                                       |
+| -------------- | ----- | ------------------------------------------------- |
+| `--dry-run`    | `-d`  | Show what would be bundled without writing files  |
+| `--sourcemap`  | `-s`  | Generate source maps (`.d.ts.map` files)          |
+| `--conditions` | `-C`  | Resolution conditions for [subpath exports](https://nodejs.org/api/packages.html#subpath-exports) (e.g. `production`)         |
+| `--external`   | `-e`  | *(Only when no `package.json`)* Packages to externalize |
 
-    /**
-     * CWD to find the package.json in
-     * @default process.cwd()
-     */
-    cwd?: string
+#### Why use `--sourcemap`?
 
-    /**
-     * Defaults to auto-detecting d.ts files from package.json
-     */
-    inputs?: string[]
+Without source maps, "Go to Definition" in VS Code lands you in bundled `.d.ts` files—often a flattened wall of generated types that's hard to navigate.
 
-    /**
-     * Only used if there's no package.json
-     * Defaults to auto-detecting dependencies from package.json
-     */
-    external?: string[]
+With `--sourcemap`, _dtsroll_ generates `.d.ts.map` files that map positions in the bundled output back to your original source files. This lets VS Code jump directly to the actual TypeScript implementation instead of the generated declarations.
 
-    conditions?: string[]
+This is especially useful for:
+- **Monorepos** — Navigate seamlessly across packages to real source
+- **Library authors** — Give consumers a better DX when exploring your types
+- **Anyone debugging types** — Understand types at their origin, not the emitted output
 
-    dryRun?: boolean
-})
-```
+> [!NOTE]
+> For source navigation to work, the original `.ts` source files must be available (either shipped with your package or present locally). If they're not, VS Code falls back to the `.d.ts` file.
 
-## Vite plugin
+### Vite plugin
 
-Use it in conjunction with a plugin that generates the initial declaration files like `vite-plugin-dts`.
+If you use `vite-plugin-dts`, _dtsroll_ will automatically bundle the emitted types immediately after generation:
 
 ```ts
 import { defineConfig } from 'vitest/config'
@@ -154,16 +162,25 @@ import dts from 'vite-plugin-dts'
 import { dtsroll } from 'dtsroll/vite'
 
 export default defineConfig({
-    // ...
     plugins: [
-        // ...
         dts(),
         dtsroll()
     ]
 })
 ```
 
+### Node API
+
+```ts
+import { dtsroll } from 'dtsroll'
+
+await dtsroll({
+    cwd: process.cwd(),
+    dryRun: false,
+    sourcemap: true // generates .d.ts.map files
+})
+```
+
 ## Related
 
-### pkgroll
-For package bundling (along with dts bundling), check out [pkgroll](https://github.com/privatenumber/pkgroll).
+- [pkgroll](https://github.com/privatenumber/pkgroll) — Zero-config JS + DTS bundler

package/dist/cli.mjs

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 import { cli } from 'cleye';
-import { b as bgYellow, a as black, d as dtsroll, l as logOutput } from './index-DfxmCmBK.mjs';
+import { b as bgYellow, a as black, d as dtsroll, l as logOutput, D as DtsrollBuildError } from './index-r9RZgCg7.mjs';
 import 'node:path';
 import 'node:fs/promises';
 import 'rollup';
 import 'rollup-plugin-dts';
 import '@rollup/plugin-node-resolve';
 import 'node:fs';
+import 'convert-source-map';
 import 'empathic/find';
 import 'resolve-pkg-maps';
 import 'byte-size';
 
 var name = "dtsroll";
-var version = "1.5.0";
+var version = "1.7.0";
 var description = "Bundle dts files";
 
 const argv = cli({
@@ -21,6 +22,7 @@ const argv = cli({
   help: {
     description
   },
+  strictFlags: true,
   parameters: ["[input files...]"],
   flags: {
     conditions: {
@@ -37,32 +39,46 @@ const argv = cli({
       type: [String],
       alias: "e",
       description: "Dependency to externalize"
+    },
+    sourcemap: {
+      type: Boolean,
+      alias: "s",
+      description: "Generate sourcemaps"
     }
-    // sourcemap: {
-    //	 type: Boolean,
-    //	 description: 'Generate sourcemaps',
-    // },
   }
 });
 const { flags } = argv;
-const dryMode = flags.dryRun;
-if (dryMode) {
+if (flags.dryRun) {
   console.log(bgYellow(black(" Dry run - No files will be written ")));
 }
 dtsroll({
   inputs: argv._.inputFiles,
   external: flags.external,
   conditions: flags.conditions,
-  dryRun: flags.dryRun
+  dryRun: flags.dryRun,
+  sourcemap: flags.sourcemap
 }).then(
   (output) => {
     if ("error" in output) {
       process.exitCode = 1;
     }
     logOutput(output);
-  },
+  }
+).catch(
   (error) => {
-    console.error("\nFailed to build:", error.message);
+    let errorMessage = "\nFailed to build";
+    if (error instanceof DtsrollBuildError) {
+      errorMessage += `
+  File: ${error.id}`;
+      if (error.importChain.length > 1) {
+        errorMessage += "\n\n  Import chain:\n    ";
+        errorMessage += error.importChain.join("\n    \u2192 ");
+      }
+    }
+    errorMessage += `
+
+${error instanceof Error ? error.message : String(error)}`;
+    console.error(errorMessage);
     process.exitCode = 1;
   }
 );

package/dist/{index-DfxmCmBK.mjs → index-r9RZgCg7.mjs}

@@ -4,6 +4,7 @@ import { rollup } from 'rollup';
 import { dts } from 'rollup-plugin-dts';
 import nodeResolve from '@rollup/plugin-node-resolve';
 import fs$1 from 'node:fs';
+import convert from 'convert-source-map';
 import { up } from 'empathic/find';
 import { resolveImports } from 'resolve-pkg-maps';
 import byteSize from 'byte-size';
@@ -72,7 +73,13 @@ const bgYellow = kolorist(43, 49);
 const cwd = process.cwd();
 
 const isPath = (filePath) => filePath[0] === "." || path.isAbsolute(filePath);
-const normalizePath = (filepath) => filepath.replaceAll("\\", "/");
+const normalizePath$1 = (filepath) => filepath.replaceAll("\\", "/");
+const getDisplayPath = (fullPath) => {
+  const relativePath = path.relative(cwd, fullPath);
+  return normalizePath$1(
+    relativePath.length < fullPath.length ? relativePath : fullPath
+  );
+};
 
 const warningSignUnicode = "\u26A0";
 const warningPrefix = yellow("Warning:");
@@ -84,10 +91,7 @@ const logOutput = (dtsOutput) => {
 \u{1F4E5} Entry points${isCliInput ? "" : " in package.json"}`));
   console.log(
     inputs.map(([inputFile, inputSource, error]) => {
-      const relativeInputFile = path.relative(cwd, inputFile);
-      const logPath2 = normalizePath(
-        relativeInputFile.length < inputFile.length ? relativeInputFile : inputFile
-      );
+      const logPath2 = getDisplayPath(inputFile);
       if (error) {
         return ` ${lightYellow(`${warningSignUnicode} ${logPath2} ${dim(error)}`)}`;
       }
@@ -107,10 +111,7 @@ const logOutput = (dtsOutput) => {
     size,
     externals
   } = dtsOutput;
-  const outputDirectoryRelative = path.relative(cwd, outputDirectory);
-  const logPath = `${normalizePath(
-    outputDirectoryRelative.length < outputDirectory.length ? outputDirectoryRelative : outputDirectory
-  )}/`;
+  const logPath = `${getDisplayPath(outputDirectory)}/`;
   const logChunk = ({
     file,
     indent,
@@ -124,10 +125,7 @@ const logOutput = (dtsOutput) => {
 ${moduleIds.sort().map((moduleId, index) => {
       const isLast = index === moduleIds.length - 1;
       const prefix = `${indent}   ${isLast ? "\u2514\u2500 " : "\u251C\u2500 "}`;
-      const relativeModuleId = path.relative(cwd, moduleId);
-      const logModuleId = normalizePath(
-        relativeModuleId.length < moduleId.length ? relativeModuleId : moduleId
-      );
+      const logModuleId = getDisplayPath(moduleId);
       const bareSpecifier = moduleToPackage[moduleId];
       if (bareSpecifier) {
         return `${prefix}${dim(`${magenta(bareSpecifier)} (${logModuleId})`)}`;
@@ -177,6 +175,17 @@ ${moduleIds.sort().map((moduleId, index) => {
   }
 };
 
+class DtsrollBuildError extends Error {
+  id;
+  importChain;
+  constructor(message, id, importChain) {
+    super(message);
+    this.name = "DtsrollBuildError";
+    this.id = id;
+    this.importChain = importChain;
+  }
+}
+
 const dtsExtensions = [".d.ts", ".d.cts", ".d.mts"];
 const isDts = (fileName) => dtsExtensions.some((extension) => fileName.endsWith(extension));
 
@@ -269,6 +278,7 @@ const getPackageName = (id) => {
   return id.slice(0, indexOfSlash);
 };
 
+const normalizePath = (filePath) => filePath.replaceAll("\\", "/");
 const getAllFiles = async (directoryPath, dontShortenPath) => {
   const directoryFiles = await fs.readdir(directoryPath, { withFileTypes: true });
   const fileTree = await Promise.all(
@@ -276,9 +286,9 @@ const getAllFiles = async (directoryPath, dontShortenPath) => {
       const filePath = path.join(directoryPath, entry.name);
       if (entry.isDirectory()) {
         const files = await getAllFiles(filePath, true);
-        return dontShortenPath ? files : files.map((file) => `./${path.relative(directoryPath, file)}`);
+        return dontShortenPath ? files : files.map((file) => `./${normalizePath(path.relative(directoryPath, file))}`);
       }
-      return dontShortenPath ? filePath : `./${path.relative(directoryPath, filePath)}`;
+      return dontShortenPath ? filePath : `./${normalizePath(path.relative(directoryPath, filePath))}`;
     })
   );
   return fileTree.flat();
@@ -473,6 +483,129 @@ const createExternalizePlugin = (configuredExternals) => {
   };
 };
 
+const createImportChainPlugin = () => {
+  const importerMap = /* @__PURE__ */ new Map();
+  const plugin = {
+    name: "import-chain-tracker",
+    buildStart: () => {
+      importerMap.clear();
+    },
+    async resolveId(source, importer) {
+      if (!importer) {
+        return null;
+      }
+      const resolved = await this.resolve(source, importer, { skipSelf: true });
+      if (resolved && !resolved.external && !importerMap.has(resolved.id)) {
+        importerMap.set(resolved.id, importer);
+      }
+      return null;
+    }
+  };
+  const getImportChain = (errorFileId) => {
+    const chain = [];
+    let current = errorFileId;
+    while (current) {
+      chain.unshift(current);
+      current = importerMap.get(current);
+    }
+    return chain;
+  };
+  return {
+    plugin,
+    getImportChain
+  };
+};
+
+const tryReadFile = async (filePath) => {
+  try {
+    return await fs$1.promises.readFile(filePath, "utf8");
+  } catch {
+    return null;
+  }
+};
+const loadSourceMap = async (codePath, code) => {
+  const adjacentMapPath = `${codePath}.map`;
+  const adjacentMapContent = await tryReadFile(adjacentMapPath);
+  if (adjacentMapContent) {
+    try {
+      const converter = convert.fromJSON(adjacentMapContent);
+      return {
+        map: converter.toObject(),
+        mapPath: adjacentMapPath
+      };
+    } catch {
+    }
+  }
+  try {
+    const inlineConverter = convert.fromSource(code);
+    if (inlineConverter) {
+      return {
+        map: inlineConverter.toObject(),
+        mapPath: codePath
+      };
+    }
+  } catch {
+  }
+  try {
+    const regex = new RegExp(convert.mapFileCommentRegex.source);
+    const commentMatch = regex.exec(code);
+    const referencedPath = commentMatch?.[1] ?? commentMatch?.[2];
+    if (!referencedPath) {
+      return;
+    }
+    const mapFilePath = path.join(path.dirname(codePath), referencedPath);
+    const mapContent = await tryReadFile(mapFilePath);
+    if (!mapContent) {
+      return;
+    }
+    const converter = convert.fromJSON(mapContent);
+    return {
+      map: converter.toObject(),
+      mapPath: mapFilePath
+    };
+  } catch {
+  }
+};
+const loadInputSourcemapsPlugin = () => ({
+  name: "load-input-sourcemaps",
+  async load(id) {
+    const isDts = dtsExtensions.some((extension) => id.endsWith(extension));
+    if (!isDts) {
+      return null;
+    }
+    const code = await tryReadFile(id);
+    if (!code) {
+      return null;
+    }
+    const result = await loadSourceMap(id, code);
+    if (!result) {
+      return { code };
+    }
+    const { map: inputMap, mapPath } = result;
+    const sourceRoot = path.resolve(path.dirname(mapPath), inputMap.sourceRoot ?? ".");
+    const sources = inputMap.sources.map(
+      (source) => path.isAbsolute(source) ? source : path.resolve(sourceRoot, source)
+    );
+    const sourcesContentRaw = await Promise.all(
+      sources.map(async (source, index) => inputMap.sourcesContent?.[index] ?? tryReadFile(source))
+    );
+    const sourcesContent = sourcesContentRaw.filter(
+      (content) => content !== null
+    );
+    return {
+      code,
+      map: {
+        version: inputMap.version,
+        names: inputMap.names,
+        sources,
+        mappings: inputMap.mappings,
+        ...sourcesContent.length > 0 ? { sourcesContent } : {},
+        ...inputMap.file ? { file: inputMap.file } : {}
+      }
+    };
+  }
+});
+
 const nodeModules = `${path.sep}node_modules${path.sep}`;
 const removeBundledModulesPlugin = (outputDirectory, sizeRef) => {
   let deleteFiles = [];
@@ -490,14 +623,17 @@ const removeBundledModulesPlugin = (outputDirectory, sizeRef) => {
     async generateBundle(options, bundle) {
       const modules = Object.values(bundle);
       const bundledFiles = Array.from(new Set(modules.flatMap(({ moduleIds }) => moduleIds)));
-      const fileSizes = bundledFiles.map((moduleId) => this.getModuleInfo(moduleId).meta);
-      const totalSize = fileSizes.reduce((total, { size }) => total + size, 0);
+      let totalSize = 0;
+      for (const moduleId of bundledFiles) {
+        const moduleInfo = this.getModuleInfo(moduleId);
+        const size = moduleInfo?.meta?.size;
+        if (typeof size === "number") {
+          totalSize += size;
+        }
+      }
       sizeRef.value = totalSize;
       const outputFiles = new Set(modules.map(({ fileName }) => path.join(options.dir, fileName)));
-      deleteFiles = bundledFiles.filter((moduleId) => (
-        // To avoid deleting files from symlinked dependencies
-        moduleId.startsWith(outputDirectory) && !moduleId.includes(nodeModules) && !outputFiles.has(moduleId)
-      ));
+      deleteFiles = bundledFiles.filter((moduleId) => moduleId && moduleId.startsWith(outputDirectory) && !moduleId.includes(nodeModules) && !outputFiles.has(moduleId));
     },
     writeBundle: async () => {
       await Promise.all(
@@ -508,7 +644,7 @@ const removeBundledModulesPlugin = (outputDirectory, sizeRef) => {
 };
 
 const packageJsonCache = /* @__PURE__ */ new Map();
-const findPackageJsonUp = (cwd) => {
+const findPackageJsonUp = async (cwd) => {
   const packageJsonPath = up("package.json", { cwd });
   if (!packageJsonPath) {
     return void 0;
@@ -517,7 +653,7 @@ const findPackageJsonUp = (cwd) => {
   let packageJson = packageJsonCache.get(packageRoot);
   if (!packageJson) {
     try {
-      const content = fs$1.readFileSync(packageJsonPath, "utf8");
+      const content = await fs.readFile(packageJsonPath, "utf8");
       packageJson = JSON.parse(content);
       packageJsonCache.set(packageRoot, packageJson);
     } catch {
@@ -537,7 +673,7 @@ const resolveSubpathImportsPlugin = () => ({
     if (id[0] !== "#" || !importer) {
       return null;
     }
-    const result = findPackageJsonUp(path.dirname(importer));
+    const result = await findPackageJsonUp(path.dirname(importer));
     if (!result) {
       return null;
     }
@@ -565,25 +701,29 @@ const createInputMap = (input, outputDirectory) => Object.fromEntries(
     inputFile
   ])
 );
-const build = async (input, outputDirectory, externals, mode, conditions) => {
+const build = async (input, outputDirectory, externals, mode, conditions, sourcemap) => {
   const {
     externalizePlugin,
     externalized,
     getPackageEntryPoint
   } = createExternalizePlugin(externals);
+  const { plugin: importChainPlugin, getImportChain } = createImportChainPlugin();
   const sizeRef = {};
   const rollupConfig = {
     input: createInputMap(input, outputDirectory),
     output: {
-      // sourcemap: true,
+      sourcemap,
       dir: outputDirectory,
       entryFileNames: "[name]",
       chunkFileNames: "_dtsroll-chunks/[hash]-[name].ts"
     },
     plugins: [
+      importChainPlugin,
       externalizePlugin,
       removeBundledModulesPlugin(outputDirectory, sizeRef),
       resolveSubpathImportsPlugin(),
+      // Load existing .d.ts.map files to chain sourcemaps back to original .ts sources
+      sourcemap && loadInputSourcemapsPlugin(),
       nodeResolve({
         extensions: [".ts", ...dtsExtensions],
         exportConditions: conditions
@@ -600,15 +740,26 @@ const build = async (input, outputDirectory, externals, mode, conditions) => {
       })
     ]
   };
-  const rollupBuild = await rollup(rollupConfig);
-  const built = await rollupBuild[mode](rollupConfig.output);
-  await rollupBuild.close();
-  return {
-    built,
-    externalized,
-    getPackageEntryPoint,
-    sourceSize: sizeRef.value
-  };
+  try {
+    const rollupBuild = await rollup(rollupConfig);
+    const built = await rollupBuild[mode](rollupConfig.output);
+    await rollupBuild.close();
+    return {
+      built,
+      externalized,
+      getPackageEntryPoint,
+      sourceSize: sizeRef.value ?? 0
+    };
+  } catch (error) {
+    if (error instanceof Error && "id" in error && typeof error.id === "string") {
+      throw new DtsrollBuildError(
+        error.message,
+        error.id,
+        getImportChain(error.id)
+      );
+    }
+    throw error;
+  }
 };
 
 const dtsroll = async ({
@@ -616,7 +767,8 @@ const dtsroll = async ({
   inputs,
   external,
   conditions,
-  dryRun
+  dryRun,
+  sourcemap
 } = {}) => {
   const pkgJson = await getPackageJson(cwd);
   const externals = pkgJson ? pkgJson.getExternals() : /* @__PURE__ */ new Map();
@@ -651,13 +803,15 @@ const dtsroll = async ({
     outputDirectory,
     externals,
     dryRun ? "generate" : "write",
-    conditions
+    conditions,
+    sourcemap
   );
   let outputSize = 0;
   const outputEntries = [];
   const outputChunks = [];
   const moduleImports = /* @__PURE__ */ new Set();
-  for (const file of built.output) {
+  const chunks = built.output.filter((file) => file.type === "chunk");
+  for (const file of chunks) {
     const size = Buffer.byteLength(file.code);
     outputSize += size;
     const moduleToPackage = Object.fromEntries(
@@ -702,4 +856,4 @@ const dtsroll = async ({
   };
 };
 
-export { black as a, bgYellow as b, dtsroll as d, logOutput as l };
+export { DtsrollBuildError as D, black as a, bgYellow as b, dtsroll as d, logOutput as l };

package/dist/index.d.ts

@@ -1,19 +1,36 @@
 import { OutputChunk } from 'rollup';
 
+/**
+ * Extended output chunk with additional metadata.
+ */
 type Output = OutputChunk & {
+    /** Size of the output file in bytes. */
     size: number;
+    /** Map of module IDs to their package names. */
     moduleToPackage: Record<string, string | undefined>;
 };
+/**
+ * List of externalized packages with metadata.
+ * Each entry is [packageName, reason, warning?].
+ */
 type Externals = [
     packageName: string,
     reason?: string,
     warning?: string
 ][];
+/**
+ * Validated input file with source info and optional error.
+ * Tuple format: [inputPath, inputSource, error?].
+ */
 type ValidatedInput = [
     inputPath: string,
     inputSource: string | undefined,
     error?: string
 ];
+/**
+ * Output from the dtsroll build process.
+ * Returns either an error state or successful build results.
+ */
 type DtsrollOutput = {
     inputs: ValidatedInput[];
     error: string;
@@ -31,14 +48,30 @@ type DtsrollOutput = {
     externals: Externals;
 };
 
+/**
+ * Configuration options for dtsroll.
+ */
 type Options = {
+    /** Working directory. Defaults to process.cwd(). */
     cwd?: string;
+    /** Input .d.ts files to bundle. If not provided, auto-detects from package.json. */
     inputs?: string[];
+    /** Packages to externalize (only used when no package.json is present). */
     external?: string[];
+    /** Export conditions for module resolution. */
     conditions?: string[];
+    /** If true, generates output without writing files. */
     dryRun?: boolean;
+    /** If true, generates source maps (.d.ts.map files). */
+    sourcemap?: boolean;
 };
-declare const dtsroll: ({ cwd, inputs, external, conditions, dryRun, }?: Options) => Promise<DtsrollOutput>;
+/**
+ * Bundle TypeScript declaration files using Rollup.
+ *
+ * @param options - Configuration options
+ * @returns Build output including bundled files, sizes, and externalized packages
+ */
+declare const dtsroll: ({ cwd, inputs, external, conditions, dryRun, sourcemap, }?: Options) => Promise<DtsrollOutput>;
 
 export { dtsroll };
 export type { DtsrollOutput, Options };

package/dist/index.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import 'node:path';
-export { d as dtsroll } from './index-DfxmCmBK.mjs';
+export { d as dtsroll } from './index-r9RZgCg7.mjs';
 import 'node:fs/promises';
 import 'rollup';
 import 'rollup-plugin-dts';
 import '@rollup/plugin-node-resolve';
 import 'node:fs';
+import 'convert-source-map';
 import 'empathic/find';
 import 'resolve-pkg-maps';
 import 'byte-size';

package/dist/vite.d.ts

@@ -2,6 +2,13 @@ import { Plugin } from 'vite';
 import { Options } from './index.js';
 import 'rollup';
 
+/**
+ * Vite plugin for bundling TypeScript declaration files.
+ * Runs after vite-plugin-dts in the writeBundle hook.
+ *
+ * @param options - Configuration options (same as dtsroll function)
+ * @returns Vite plugin instance
+ */
 declare const dtsrollPlugin: (options?: Options) => Plugin;
 
 export { dtsrollPlugin as dtsroll };

package/dist/vite.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
-import { d as dtsroll, l as logOutput } from './index-DfxmCmBK.mjs';
+import { d as dtsroll, l as logOutput } from './index-r9RZgCg7.mjs';
 import 'node:path';
 import 'node:fs/promises';
 import 'rollup';
 import 'rollup-plugin-dts';
 import '@rollup/plugin-node-resolve';
 import 'node:fs';
+import 'convert-source-map';
 import 'empathic/find';
 import 'resolve-pkg-maps';
 import 'byte-size';
@@ -29,14 +30,22 @@ const dtsrollPlugin = (options) => {
         if (built) {
           return;
         }
-        const output = await dtsroll({
-          cwd,
-          ...options
-        });
-        built = true;
-        if (!noLog) {
-          logOutput(output);
-          console.log();
+        try {
+          const output = await dtsroll({
+            cwd,
+            ...options
+          });
+          built = true;
+          if (!noLog) {
+            logOutput(output);
+            console.log();
+          }
+        } catch (error) {
+          built = true;
+          throw new Error(
+            `dtsroll failed: ${error instanceof Error ? error.message : String(error)}`,
+            { cause: error }
+          );
         }
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dtsroll",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Bundle dts files",
   "keywords": [
     "bundle",
@@ -40,6 +40,7 @@
     "@rollup/plugin-node-resolve": "^16.0.3",
     "byte-size": "^9.0.1",
     "cleye": "^2.2.1",
+    "convert-source-map": "^2.0.0",
     "empathic": "^2.0.0",
     "resolve-pkg-maps": "^1.0.0",
     "rollup": "^4.55.1",