@savvy-web/tsdown-plugins 0.9.2 → 0.11.0

package/build/build-target-groups.js

@@ -5,7 +5,7 @@ import { createTsdownLogger } from "../report/tsdown-logger.js";
 import { cjsDefaultInterop } from "./cjs-default-interop.js";
 import { nodeBuiltinDefaultInterop } from "./node-builtin-default-interop.js";
 import { syncPublicDir } from "./sync-public.js";
-import { deriveDtsPassOptions, deriveTargetGroupOptions, outDirFor } from "./target-groups.js";
+import { deriveDeclarationsPassOptions, deriveDtsPassOptions, deriveTargetGroupOptions, outDirFor } from "./target-groups.js";
 import { dirname, join } from "node:path";
 
 //#region src/build/build-target-groups.ts
@@ -80,6 +80,7 @@ async function buildTargetGroups(options) {
 			};
 			const js = deriveTargetGroupOptions(deriveInput);
 			const dts = deriveDtsPassOptions(deriveInput);
+			const decl = deriveDeclarationsPassOptions(deriveInput);
 			const partOutDir = part.outSubdir !== void 0 ? join(js.outDir, part.outSubdir) : js.outDir;
 			const targetGroup = {
 				id: group.id,
@@ -165,6 +166,44 @@ async function buildTargetGroups(options) {
 					...metricsPlugins(group.id, "dts")
 				]
 			}));
+			if (js.isProd && options.emitDeclarations === true && Object.keys(decl.entry).length > 0) {
+				const partDeclDir = part.outSubdir !== void 0 ? join(decl.outDir, part.outSubdir) : decl.outDir;
+				try {
+					await build({
+						config: false,
+						cwd: options.cwd,
+						entry: decl.entry,
+						outDir: partDeclDir,
+						format: decl.format,
+						platform: decl.platform,
+						sourcemap: decl.sourcemap,
+						unbundle: decl.unbundle,
+						clean: isBase,
+						fixedExtension: decl.fixedExtension,
+						dts: decl.dts,
+						define: decl.define,
+						logLevel: "silent",
+						...dtsNeverBundle.length > 0 || partBundleNodeModules || decl.bundledPackages ? { deps: {
+							...dtsNeverBundle.length > 0 ? { neverBundle: dtsNeverBundle } : {},
+							...partBundleNodeModules ? {
+								skipNodeModulesBundle: false,
+								...decl.bundledPackages ? { dts: { alwaysBundle: decl.bundledPackages } } : {}
+							} : decl.bundledPackages ? {
+								skipNodeModulesBundle: true,
+								dts: { alwaysBundle: decl.bundledPackages }
+							} : {}
+						} } : {},
+						...decl.jsx !== void 0 ? { inputOptions: { jsx: decl.jsx } } : {},
+						...options.extraPlugins !== void 0 ? { plugins: [...options.extraPlugins] } : {}
+					});
+				} catch (err) {
+					collector?.recordWarning(group.id, {
+						source: "tsdown",
+						level: "warn",
+						text: `Could not emit per-module declarations for API Extractor diagnostics: ${String(err)}`
+					});
+				}
+			}
 		}
 		const looseOutDir = outDirFor(options.cwd, group.id);
 		const isProdGroup = group.id !== "dev";

package/build/target-groups.js

@@ -4,6 +4,12 @@ import { join } from "node:path";
 /** The output dir for a group: dev -> dist/dev/pkg, prod -> dist/prod/<group>/pkg. */
 const outDirFor = (cwd, group) => group === "dev" ? join(cwd, "dist/dev/pkg") : join(cwd, "dist/prod", group, "pkg");
 /**
+* Per-module declarations dir for a prod group: a sibling of `pkg/`, NOT published, used only as
+* API Extractor's diagnostics-run input so locations resolve to per-file source. Kept (not stripped)
+* as a cacheable, inspectable build artifact (issue #162).
+*/
+const declarationsDirFor = (cwd, group) => join(cwd, "dist/prod", group, "declarations");
+/**
 * Derive the JS-pass tsdown options for one TargetGroup (per-module JS, no dts).
 *
 * @public
@@ -59,6 +65,35 @@ function deriveDtsPassOptions(options) {
 		...options.bundledPackages !== void 0 ? { bundledPackages: options.bundledPackages } : {}
 	};
 }
+/**
+* Derive the per-module declarations pass (API Extractor diagnostics input). Mirrors
+* {@link deriveDtsPassOptions} but `unbundle: true` (preserveModules → 1:1 source positions),
+* esm-only (AE reads the `.d.ts` entry only), into the `declarations/` sibling dir. Bin entries
+* are dropped (no exports).
+* @internal
+*/
+function deriveDeclarationsPassOptions(options) {
+	const entry = Object.fromEntries(Object.entries(options.entry).filter(([name]) => !name.startsWith("bin/")));
+	return {
+		outDir: declarationsDirFor(options.cwd, options.group),
+		sourcemap: false,
+		format: ["esm"],
+		unbundle: true,
+		platform: "node",
+		fixedExtension: false,
+		entry,
+		dts: {
+			tsconfig: options.tsconfigPath,
+			emitDtsOnly: true
+		},
+		define: {
+			"process.env.__PACKAGE_VERSION__": JSON.stringify(options.version),
+			...options.define
+		},
+		...options.bundledPackages !== void 0 ? { bundledPackages: options.bundledPackages } : {},
+		...options.jsx !== void 0 ? { jsx: options.jsx } : {}
+	};
+}
 
 //#endregion
-export { deriveDtsPassOptions, deriveTargetGroupOptions, outDirFor };
+export { declarationsDirFor, deriveDeclarationsPassOptions, deriveDtsPassOptions, deriveTargetGroupOptions, outDirFor };

package/index.d.ts

@@ -689,6 +689,13 @@ interface BuildTargetGroupsOptions {
   readonly collector?: BuildCollector | undefined;
   /** Compute gzip sizes for emitted files (verbose render). Forwarded to the metrics plugin. */
   readonly verbose?: boolean | undefined;
+  /**
+   * Emit a per-module (`unbundle: true`) declaration tree into `dist/prod/<id>/declarations/` per
+   * group, in addition to the bundled dts in `pkg/`. API Extractor's diagnostics-run input for the
+   * meta pass. Prod-only; the bundler sets it for `--target prod`. Absent → no third pass
+   * (byte-identical to the two-pass default). Not captured by the collector.
+   */
+  readonly emitDeclarations?: boolean | undefined;
 }
 /**
  * Run tsdown.build() per TargetGroup. Composable so the escape hatch gets multi-group too.
@@ -1273,6 +1280,13 @@ interface GenerateMetaOptions {
   readonly tsconfigPath: string;
   /** Directory holding the tsdown-emitted per-file .d.ts (e.g. dist/dev/pkg). */
   readonly dtsDir: string;
+  /**
+   * Per-module declarations dir used ONLY for a second, diagnostics-only API Extractor run that
+   * resolves accurate per-file source locations. The shipped api-model is still produced from
+   * `dtsDir` (the bundled dts), so it is unchanged. When omitted or equal to `dtsDir`, a single
+   * run over `dtsDir` produces both model and diagnostics (legacy behavior).
+   */
+  readonly aeInputDir?: string | undefined;
   /** Map of entry name to the .d.ts basename (without extension) inside dtsDir. */
   readonly entries: Record<string, string>;
   /** Map of entry name to its export path (".", "./sub"). */

package/meta/api-extractor.js

@@ -12,12 +12,9 @@ const CI_FATAL_MESSAGE_IDS = /* @__PURE__ */ new Set(["ae-forgotten-export"]);
 /**
 * Map an API Extractor message to a collector DiagnosticInput, or undefined if not warn/error.
 *
-* The location (`file`/`line`/`column`) is deliberately dropped. API Extractor analyzes the
-* bundled `.d.ts` and maps positions back through its `.d.ts.map` source map, which anchors
-* every message to the start of an adjacent declaration rather than the symbol's true source
-* position — wrong for release-tag codes, unresolved links, and the rest alike. A misleading
-* `file:line` is worse than none, so it is omitted; the authoritative locator is the symbol
-* name quoted in `text`. See systems#154.
+* Location (`file`/`line`/`column`) is preserved: diagnostics now come from a per-module declaration
+* run (see generateMeta's two-input split), where each `.d.ts.map` references only its own source, so
+* positions resolve to the true source declaration. Reverts the systems#154 mitigation. See systems#162.
 */
 function mapExtractorMessage(message) {
 	const isError = message.logLevel === ExtractorLogLevel.Error;
@@ -27,7 +24,10 @@ function mapExtractorMessage(message) {
 		source: "api-extractor",
 		level: isError ? "error" : "warn",
 		text: message.text,
-		...message.messageId !== void 0 ? { code: message.messageId } : {}
+		...message.messageId !== void 0 ? { code: message.messageId } : {},
+		...message.sourceFilePath !== void 0 ? { file: message.sourceFilePath } : {},
+		...message.sourceFileLine !== void 0 ? { line: message.sourceFileLine } : {},
+		...message.sourceFileColumn !== void 0 ? { column: message.sourceFileColumn } : {}
 	};
 }
 /** Run API Extractor over a single entry's .d.ts, writing the .api.json (and optionally tsdoc-metadata.json). Throws on failure. */
@@ -41,7 +41,7 @@ function runApiExtractor(options) {
 			mainEntryPointFilePath: options.entryDtsPath,
 			enumMemberOrder: "preserve",
 			compiler: { tsconfigFilePath: options.tsconfigPath },
-			docModel: {
+			docModel: options.emitDocModel === false ? { enabled: false } : {
 				enabled: true,
 				apiJsonFilePath: options.apiJsonPath
 			},

package/meta/generate.js

@@ -20,6 +20,8 @@ function unscopedName(name) {
 */
 async function generateMeta(options) {
 	const { cwd, packageName, tsconfigPath, dtsDir, entries, exportPaths, outMetaDir, localPaths, tsdoc, manifestTransform, onMessage, ci, onSuppressed } = options;
+	const aeInputDir = options.aeInputDir ?? dtsDir;
+	const splitDiagnostics = aeInputDir !== dtsDir;
 	const tsdocConfigPath = writeTsdocConfig(cwd, tsdoc);
 	const packageJsonPath = join(cwd, "package.json");
 	mkdirSync(outMetaDir, { recursive: true });
@@ -29,24 +31,72 @@ async function generateMeta(options) {
 	const perEntryModels = /* @__PURE__ */ new Map();
 	const intermediateApiJsons = [];
 	let mainEntryDidTsdocMetadata = false;
+	const diagnosticKey = (e) => `${e.code ?? ""}\0${e.text}`;
+	const stripLocation = (e) => ({
+		source: e.source,
+		level: e.level,
+		text: e.text,
+		...e.code !== void 0 ? { code: e.code } : {},
+		...e.ciFatal !== void 0 ? { ciFatal: e.ciFatal } : {}
+	});
 	for (const entryName of entryNames) {
-		const entryDtsPath = join(dtsDir, `${entries[entryName]}.d.ts`);
+		const modelEntryDts = join(dtsDir, `${entries[entryName]}.d.ts`);
 		const perEntryApiJson = join(outMetaDir, `${entryName.replace(/[\\/]/g, "__")}.entry.api.json`);
 		intermediateApiJsons.push(perEntryApiJson);
 		const isMain = (exportPaths[entryName] ?? (entryName === "index" ? "." : `./${entryName}`)) === ".";
+		const captureRollupOnlyFatal = splitDiagnostics && onMessage !== void 0 && ci !== true;
+		const rollupFatal = [];
+		const runBReported = /* @__PURE__ */ new Set();
+		const runAOnMessage = captureRollupOnlyFatal ? (entry) => {
+			if (entry.ciFatal === true) rollupFatal.push(entry);
+		} : ci === true && onMessage !== void 0 ? (entry) => {
+			if (entry.level === "error") onMessage(stripLocation(entry));
+		} : () => {};
 		runApiExtractor({
 			cwd,
 			packageJsonPath,
-			entryDtsPath,
+			entryDtsPath: modelEntryDts,
 			tsconfigPath,
 			tsdocConfigPath,
 			apiJsonPath: perEntryApiJson,
 			...isMain && !mainEntryDidTsdocMetadata ? { tsdocMetadataPath } : {},
 			suppressWarnings: tsdoc.suppressWarnings,
 			...ci !== void 0 ? { ci } : {},
-			...onMessage !== void 0 ? { onMessage } : {},
-			...onSuppressed !== void 0 ? { onSuppressed } : {}
+			...splitDiagnostics ? { onMessage: runAOnMessage } : {
+				...onMessage !== void 0 ? { onMessage } : {},
+				...onSuppressed !== void 0 ? { onSuppressed } : {}
+			}
 		});
+		if (splitDiagnostics) {
+			const runBOnMessage = captureRollupOnlyFatal && onMessage !== void 0 ? (entry) => {
+				if (entry.ciFatal === true) runBReported.add(diagnosticKey(entry));
+				onMessage(entry);
+			} : onMessage;
+			try {
+				runApiExtractor({
+					cwd,
+					packageJsonPath,
+					entryDtsPath: join(aeInputDir, `${entries[entryName]}.d.ts`),
+					tsconfigPath,
+					tsdocConfigPath,
+					apiJsonPath: perEntryApiJson,
+					emitDocModel: false,
+					suppressWarnings: tsdoc.suppressWarnings,
+					...runBOnMessage !== void 0 ? { onMessage: runBOnMessage } : {},
+					...onSuppressed !== void 0 ? { onSuppressed } : {}
+				});
+			} catch (err) {
+				if (onMessage !== void 0) onMessage({
+					source: "api-extractor",
+					level: "warn",
+					text: `Could not harvest per-module source locations for "${entryName}": ${String(err)}`
+				});
+			}
+			if (captureRollupOnlyFatal && onMessage !== void 0) for (const entry of rollupFatal) {
+				if (runBReported.has(diagnosticKey(entry))) continue;
+				onMessage(stripLocation(entry));
+			}
+		}
 		if (isMain) mainEntryDidTsdocMetadata = true;
 		perEntryModels.set(entryName, JSON.parse(readFileSync(perEntryApiJson, "utf-8")));
 	}

package/meta/run-pass.js

@@ -1,4 +1,5 @@
 import { createEntryName } from "../entry/extract.js";
+import { declarationsDirFor } from "../build/target-groups.js";
 import { resolveNextVersions } from "../changesets/next-versions.js";
 import { normalizeMetaOptions } from "./config.js";
 import { generateMeta } from "./generate.js";
@@ -31,6 +32,7 @@ async function runMetaPass(o) {
 		packageName: o.packageName,
 		tsconfigPath: o.tsconfigPath,
 		dtsDir: join(o.cwd, "dist", "prod", g.id, "pkg"),
+		aeInputDir: declarationsDirFor(o.cwd, g.id),
 		entries: dtsBasenames,
 		exportPaths,
 		outMetaDir: join(o.cwd, "dist", "prod", g.id, "meta"),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/tsdown-plugins",
-	"version": "0.9.2",
+	"version": "0.11.0",
 	"private": false,
 	"description": "Interface-only tsdown/rolldown plugin pack powering @savvy-web/bundler",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/tsdown-plugins",