@savvy-web/tsdown-plugins 0.7.0 → 0.9.0

package/README.md

@@ -50,8 +50,9 @@ export default defineConfig({
 - **Per-target build loop** — `deriveTargetGroupOptions` and `buildTargetGroups` map a target to its `tsdown` options and run the build once per target, exposed as a helper so the escape hatch gets multi-target builds too. A `format` of `["esm", "cjs"]` (the `BuildFormat` type) derives a dual-format build — a require-able CJS output with default-export interop and `.d.cts` declarations alongside the ESM one. The `bundleNodeModules`, `bundledPackages` and `dtsExternals` options thread the dependency-bundling posture into both the JS and declaration passes. A per-entry override partition can also set `platform` (the JS-pass target, `"browser"` for a client bundle), `css` (forwarded to tsdown's `css` option for `@tsdown/css`) and `outSubdir` (build the partition into an isolated `<group>/pkg/<subdir>/` sub-package). The `define` option forwards compile-time global replacements to both passes, merged with an auto-injected `process.env.__PACKAGE_VERSION__` constant.
 - **Loose files** — `normalizeLooseFiles` resolves a `LooseFiles` map of literal output filenames to `NormalizedLooseFile` descriptors, inferring the module format from each `.mjs`/`.cjs` key and raising `ConfigValidationError` on a path separator, an unsupported extension or an ambiguous `.js`. `buildTargetGroups` takes the normalized form as its `looseFiles` option and emits one extra single-entry, bundled, declaration-free and manifest-free pass per file per target group, inheriting the group's bundling posture so each file is self-contained.
 - **Bundled declarations** — each target runs two `tsdown` passes: a JavaScript pass that preserves per-module output, then a declaration-only pass that rolls every re-exported type into a single `.d.ts` per public entry (`deriveDtsPassOptions`). Per-module JavaScript stays intact while consumers keep reaching re-exported types through your published subpaths.
-- **API Extractor meta** — `generateMeta` runs [API Extractor](https://api-extractor.com/) over a package's emitted `.d.ts` to write an api-model bundle (`.api.json`, `tsdoc-metadata.json`, resolved `tsconfig.json`); `normalizeMetaOptions` fills the `MetaOptions` defaults that drive it.
+- **API Extractor meta** — `runMetaPass` is the single meta-generation orchestrator the bundler front door and both self-hosting escape hatches share: it derives the export paths, applies the optimistic next-version forward-look and drives API Extractor over a package's emitted `.d.ts` to write an api-model bundle (`.api.json`, `tsdoc-metadata.json`, resolved `tsconfig.json`). `generateMeta` is the lower-level pass it wraps, and `normalizeMetaOptions` fills the `MetaOptions` defaults that drive it.
 - **Output reporter** — `renderReport` plus the `BuildReport` schema and a set of formatters (terminal, JSON, markdown, CI annotations, silent) render a build report for humans, agents or CI.
+- **Issues artifact** — `writeIssuesArtifact` (with the pure `flattenIssues` and `serializeIssues` behind it) writes a deduplicated `dist/<target>/issues.json` on every build, collecting the build's warnings, errors and suppressed diagnostics in a stable JSON shape (`BuildIssues`/`PlainDiagnostic`) so an agent or CI script reads the diagnostics straight from disk instead of parsing terminal output.
 
 ## Effect
 

package/build/build-target-groups.js

@@ -1,4 +1,7 @@
 import { emitManifest } from "../manifest/emit-manifest.js";
+import { buildMetricsPlugin } from "../report/metrics-plugin.js";
+import { createTimer } from "../report/timer.js";
+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";
@@ -20,11 +23,28 @@ import { dirname, join } from "node:path";
 * build (JS and the dts plugin share it), so a single pass cannot give per-module JS + bundled
 * dts. Per-module dts breaks type portability (TS2883); bundling the JS re-bundles workspace
 * consumers. The split keeps per-module JS AND rolled-up, self-contained declarations.
+* @public
 */
 async function buildTargetGroups(options) {
 	const build = options.build ?? (await import("tsdown")).build;
 	const publicDir = join(options.cwd, "public");
+	const collector = options.collector;
+	const verbose = options.verbose ?? false;
+	const instrument = (groupId) => collector === void 0 ? {} : {
+		logLevel: "silent",
+		customLogger: createTsdownLogger(collector, groupId)
+	};
+	const metricsPlugins = (groupId, pass) => collector === void 0 ? [] : [buildMetricsPlugin(collector, groupId, pass, verbose)];
+	const timed = async (groupId, pass, run) => {
+		const timer = createTimer();
+		try {
+			await run();
+		} finally {
+			if (collector !== void 0) collector.recordPassTiming(groupId, pass, timer.elapsed());
+		}
+	};
 	for (const group of options.groups) {
+		if (collector !== void 0) collector.registerGroup(group.id, Object.keys(options.entry));
 		const partitions = [{
 			entry: options.entry,
 			...options.format !== void 0 ? { format: options.format } : {},
@@ -81,7 +101,7 @@ async function buildTargetGroups(options) {
 				...options.subdirExports !== void 0 ? { subdirExports: options.subdirExports } : {},
 				...options.exeRewrite !== void 0 ? { exeRewrite: options.exeRewrite } : {}
 			}) : void 0;
-			await build({
+			await timed(group.id, "js", () => build({
 				config: false,
 				cwd: options.cwd,
 				entry: jsEntry,
@@ -95,6 +115,7 @@ async function buildTargetGroups(options) {
 				fixedExtension: js.fixedExtension,
 				dts: js.dts,
 				define: js.define,
+				...instrument(group.id),
 				...part.css !== void 0 ? { css: part.css } : {},
 				...partExternals?.length || partBundleNodeModules || partBundle?.length ? { deps: {
 					...partExternals?.length ? { neverBundle: partExternals } : {},
@@ -106,12 +127,14 @@ async function buildTargetGroups(options) {
 				plugins: [
 					...manifestPlugin ? [manifestPlugin] : [],
 					...js.format.includes("cjs") ? [nodeBuiltinDefaultInterop(), cjsDefaultInterop()] : [],
-					...options.extraPlugins ?? []
+					...options.extraPlugins ?? [],
+					...metricsPlugins(group.id, "js")
 				]
-			});
+			}));
 			if (isBase) syncPublicDir(publicDir, join(js.outDir, "public"));
 			const dtsNeverBundle = [...partExternals ?? [], ...partDtsExternals ?? []];
-			await build({
+			if (Object.keys(dts.entry).length === 0) continue;
+			await timed(group.id, "dts", () => build({
 				config: false,
 				cwd: options.cwd,
 				entry: dts.entry,
@@ -124,6 +147,7 @@ async function buildTargetGroups(options) {
 				fixedExtension: dts.fixedExtension,
 				dts: dts.dts,
 				define: dts.define,
+				...instrument(group.id),
 				...dtsNeverBundle.length > 0 || partBundleNodeModules || dts.bundledPackages ? { deps: {
 					...dtsNeverBundle.length > 0 ? { neverBundle: dtsNeverBundle } : {},
 					...partBundleNodeModules ? {
@@ -135,8 +159,12 @@ async function buildTargetGroups(options) {
 					} : {}
 				} } : {},
 				...dts.jsx !== void 0 ? { inputOptions: { jsx: dts.jsx } } : {},
-				plugins: [...dts.format.includes("cjs") ? [nodeBuiltinDefaultInterop(), cjsDefaultInterop()] : [], ...options.extraPlugins ?? []]
-			});
+				plugins: [
+					...dts.format.includes("cjs") ? [nodeBuiltinDefaultInterop(), cjsDefaultInterop()] : [],
+					...options.extraPlugins ?? [],
+					...metricsPlugins(group.id, "dts")
+				]
+			}));
 		}
 		const looseOutDir = outDirFor(options.cwd, group.id);
 		const isProdGroup = group.id !== "dev";
@@ -147,7 +175,7 @@ async function buildTargetGroups(options) {
 		};
 		for (const lf of options.looseFiles ?? []) {
 			const hasCjs = lf.format === "cjs";
-			await build({
+			await timed(group.id, "loose", () => build({
 				config: false,
 				cwd: options.cwd,
 				entry: { [lf.entryName]: lf.source },
@@ -164,10 +192,15 @@ async function buildTargetGroups(options) {
 					"process.env.__PACKAGE_VERSION__": JSON.stringify(options.version),
 					...options.define
 				},
+				...instrument(group.id),
 				...Object.keys(looseDeps).length > 0 ? { deps: looseDeps } : {},
 				...hasCjs ? { cjsDefault: true } : {},
-				plugins: [...hasCjs ? [nodeBuiltinDefaultInterop(), cjsDefaultInterop()] : [], ...options.extraPlugins ?? []]
-			});
+				plugins: [
+					...hasCjs ? [nodeBuiltinDefaultInterop(), cjsDefaultInterop()] : [],
+					...options.extraPlugins ?? [],
+					...metricsPlugins(group.id, "loose")
+				]
+			}));
 		}
 	}
 }

package/build/cjs-default-interop.js

@@ -75,6 +75,7 @@ const INTEROP_FOOTER = [
 *
 * The emitted footer is also self-guarded (`module.exports.default !== void 0`), so it is a
 * runtime no-op whenever the static gate is ever too generous.
+* @public
 */
 function cjsDefaultInterop() {
 	return {

package/build/loose-files.js

@@ -13,6 +13,7 @@ const EXT_FORMAT = {
 * a missing `source` is surfaced later by tsdown's entry resolution. Throws
 * {@link ConfigValidationError} on any structural problem so the bundler's ConfigValidator
 * surfaces it as a typed, fast-fail config error.
+* @public
 */
 function normalizeLooseFiles(files) {
 	const out = [];

package/build/node-builtin-default-interop.js

@@ -18,13 +18,15 @@ function isNodeBuiltin(spec) {
 * Why this exists — a rolldown 1.1.0 codegen defect (verified against the latest
 * published rolldown 1.1.0 / tsdown 0.22.2, with no newer release to upgrade to):
 *
-*   // SOURCE (e.g. vfile's lib/minproc.js)
-*   export {default as minproc} from 'node:process'
-*   // ...consumed as minproc.cwd()
+* ```ts
+* // SOURCE (e.g. vfile's lib/minproc.js)
+* export {default as minproc} from 'node:process'
+* // ...consumed as minproc.cwd()
 *
-*   // rolldown CJS OUTPUT (BROKEN)
-*   let node_process = require("node:process");
-*   node_process.default.cwd()           // <- require("node:process").default is undefined
+* // rolldown CJS OUTPUT (BROKEN)
+* let node_process = require("node:process");
+* node_process.default.cwd()           // <- require("node:process").default is undefined
+* ```
 *
 * For a default import of an EXTERNAL Node builtin, rolldown emits a bare
 * `require("node:x")` WITHOUT its `__toESM` interop wrapper, yet still accesses
@@ -41,14 +43,18 @@ function isNodeBuiltin(spec) {
 * layer, which is why the correction happens here on the source.
 *
 * Rewrites (the two static forms that occur in practice, anchored to statement start):
-*  - `import NAME from "node:x"`            -> `import * as NAME from "node:x"`
-*  - `export { default as NAME } from "node:x"` -> `export * as NAME from "node:x"`
-*  - `import NAME, { a, b } from "node:x"`  -> `import * as NAME from "node:x"; import { a, b } from "node:x"`
+*
+* ```ts
+* import NAME from "node:x"            -> import * as NAME from "node:x"
+* export { default as NAME } from "node:x" -> export * as NAME from "node:x"
+* import NAME, { a, b } from "node:x"  -> import * as NAME from "node:x"; import { a, b } from "node:x"
+* ```
 *
 * The namespace binding NAME carries the builtin's named exports (`NAME.cwd`,
 * `NAME.join`, ...), which is exactly how a default import of a builtin is consumed
 * in practice. ESM output is unaffected at runtime (a namespace import of a builtin
 * resolves to the same members), so the plugin is safe to attach to dual builds.
+* @public
 */
 function nodeBuiltinDefaultInterop() {
 	const DEFAULT_REEXPORT = /(^|\n)([ \t]*)export\s*\{\s*default\s+as\s+([A-Za-z_$][\w$]*)\s*\}\s*from\s*(["'])([^"']+)\4/g;

package/build/strip-maps.js

@@ -15,6 +15,7 @@ import { readdirSync, rmSync } from "node:fs";
 *
 * Recurses, but skips `node_modules` so it does not traverse a self-contained bundle's
 * vendored tree — only the package's own emitted declarations carry maps worth stripping.
+* @public
 */
 function removeDeclarationMaps(pkgDir) {
 	const removed = [];

package/build/sync-public.js

@@ -42,6 +42,7 @@ function pruneEmptyDirs(dir) {
 *
 * The byte-diff keeps unchanged files (and their timestamps) untouched, so a large copied asset
 * tree — e.g. the mcp markdown corpus — is not rewritten on every build.
+* @public
 */
 function syncPublicDir(sourceDir, targetDir) {
 	if (!existsSync(sourceDir)) return;

package/build/target-groups.js

@@ -3,7 +3,11 @@ import { join } from "node:path";
 //#region src/build/target-groups.ts
 /** 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");
-/** Derive the JS-pass tsdown options for one TargetGroup (per-module JS, no dts). */
+/**
+* Derive the JS-pass tsdown options for one TargetGroup (per-module JS, no dts).
+*
+* @public
+*/
 function deriveTargetGroupOptions(options) {
 	const isProd = options.group !== "dev";
 	const format = options.format ?? ["esm"];
@@ -32,6 +36,7 @@ function deriveTargetGroupOptions(options) {
 function deriveDtsPassOptions(options) {
 	const isProd = options.group !== "dev";
 	const format = options.format ?? ["esm"];
+	const entry = Object.fromEntries(Object.entries(options.entry).filter(([name]) => !name.startsWith("bin/")));
 	return {
 		outDir: outDirFor(options.cwd, options.group),
 		sourcemap: false,
@@ -40,7 +45,7 @@ function deriveDtsPassOptions(options) {
 		clean: false,
 		platform: "node",
 		fixedExtension: false,
-		entry: options.entry,
+		entry,
 		dts: {
 			tsconfig: options.tsconfigPath,
 			emitDtsOnly: true

package/catalog/resolve-catalogs.js

@@ -12,6 +12,7 @@ import { Effect } from "effect";
 *
 * Rejects with `CatalogResolutionError` on an unresolvable reference, or
 * `CatalogAssemblyError` if the workspace catalog set cannot be assembled.
+* @public
 */
 function resolveManifest(pkg) {
 	const program = Effect.gen(function* () {

package/changesets/next-versions.js

@@ -9,6 +9,7 @@ import { getPackages } from "@manypkg/get-packages";
 * each package's CURRENT version, then overlays `newVersion` for changeset-affected packages
 * via `@changesets/get-release-plan`. Never rejects: any failure (not a workspace, missing
 * `.changeset/config.json`, parse error) degrades to current versions (or an empty map).
+* @public
 */
 async function resolveNextVersions(cwd) {
 	try {

package/config-validation/ConfigValidator.js

@@ -1,7 +1,11 @@
 import { Context } from "effect";
 
 //#region src/config-validation/ConfigValidator.ts
-/** Fast-fail config validator; runs first in the bundler over the resolved config. */
+/**
+* Fast-fail config validator; runs first in the bundler over the resolved config.
+*
+* @public
+*/
 var ConfigValidator = class extends Context.Tag("@savvy-web/tsdown-plugins/ConfigValidator")() {};
 
 //#endregion

package/config-validation/ConfigValidatorLive.js

@@ -7,7 +7,7 @@ import { Effect, Layer } from "effect";
 import { existsSync, statSync } from "node:fs";
 
 //#region src/config-validation/ConfigValidatorLive.ts
-const VALID_SYNTAX_KINDS = new Set([
+const VALID_SYNTAX_KINDS = /* @__PURE__ */ new Set([
 	"block",
 	"inline",
 	"modifier"
@@ -50,7 +50,11 @@ function check(input) {
 	}
 	if (input.looseFiles !== void 0) normalizeLooseFiles(input.looseFiles);
 }
-/** Live ConfigValidator: wraps the synchronous rule set, surfacing ConfigValidationError as a typed Effect failure. */
+/**
+* Live ConfigValidator: wraps the synchronous rule set, surfacing ConfigValidationError as a typed Effect failure.
+*
+* @public
+*/
 const ConfigValidatorLive = Layer.succeed(ConfigValidator, { validate: (input) => Effect.try({
 	try: () => check(input),
 	catch: (e) => e instanceof ConfigValidationError ? e : new ConfigValidationError({

package/dts/resolved-tsconfig.js

@@ -3,7 +3,11 @@ import { writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 
 //#region src/dts/resolved-tsconfig.ts
-/** Build the portable absolute-path tsconfig object (ported from rslib writeBundleTempConfig). */
+/**
+* Build the portable absolute-path tsconfig object (ported from rslib writeBundleTempConfig).
+*
+* @public
+*/
 function buildResolvedTsconfig(options) {
 	const cwd = options.cwd;
 	return {
@@ -32,7 +36,11 @@ function buildResolvedTsconfig(options) {
 		exclude: [join(cwd, "node_modules"), join(cwd, "dist/**/*")]
 	};
 }
-/** Write the resolved tsconfig to a temp file and return its absolute path. */
+/**
+* Write the resolved tsconfig to a temp file and return its absolute path.
+*
+* @public
+*/
 function writeResolvedTsconfig(options) {
 	const cfg = buildResolvedTsconfig(options);
 	const path = join(tmpdir(), `tsconfig-bundle-${process.pid}-${options.cwd.replace(/[^\w]/g, "_")}.json`);

package/entry/extract.js

@@ -26,6 +26,7 @@ const createEntryName = (exportKey, exportsAsIndexes) => {
 	const withoutPrefix = exportKey.replace(/^\.\//, "");
 	return exportsAsIndexes ? `${withoutPrefix}/index` : withoutPrefix.replace(/\//g, "-");
 };
+/** @public */
 function extractEntries(pkg, options = {}) {
 	const entries = {};
 	const exportPaths = {};

package/entry/package-json-entries.js

@@ -3,7 +3,11 @@ import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
 
 //#region src/entry/package-json-entries.ts
-/** Derive a tsdown `entry` record (name to source path) from a package.json. */
+/**
+* Derive a tsdown `entry` record (name to source path) from a package.json.
+*
+* @public
+*/
 function packageJsonEntries(options = {}) {
 	return extractEntries(options.pkg ?? JSON.parse(readFileSync(resolve(options.cwd ?? process.cwd(), "package.json"), "utf-8")), {
 		exportsAsIndexes: options.exportsAsIndexes,

package/errors.js

@@ -19,13 +19,21 @@ var BuildFailed = class extends Data.TaggedError("BuildFailed") {
 		return `Build failed for TargetGroup "${this.targetGroup}": ${this.reason}`;
 	}
 };
-/** API Extractor meta generation failed for an entry. */
+/**
+* API Extractor meta generation failed for an entry.
+*
+* @public
+*/
 var MetaGenerationError = class extends Data.TaggedError("MetaGenerationError") {
 	get message() {
 		return `Meta generation failed for entry "${this.entry}": ${this.reason}`;
 	}
 };
-/** A savvy.build.ts or publishConfig.targets config is structurally invalid; raised before any build work. */
+/**
+* A savvy.build.ts or publishConfig.targets config is structurally invalid; raised before any build work.
+*
+* @public
+*/
 var ConfigValidationError = class extends Data.TaggedError("ConfigValidationError") {
 	get message() {
 		return `Config validation failed at "${this.path}": ${this.reason}`;

package/exe/build.js

@@ -1,13 +1,28 @@
+import { buildMetricsPlugin } from "../report/metrics-plugin.js";
+import { createTimer } from "../report/timer.js";
+import { createTsdownLogger } from "../report/tsdown-logger.js";
 import { join } from "node:path";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 
 //#region src/exe/build.ts
-/** Compile each SEA binary via tsdown's exe mode. One tsdown build per spec. */
+/**
+* Compile each SEA binary via tsdown's exe mode. One tsdown build per spec.
+*
+* @public
+*/
 async function runExeBuild(options) {
 	const build = options.build ?? (await import("tsdown")).build;
 	for (const spec of options.specs) {
 		const scratch = mkdtempSync(join(tmpdir(), "savvy-exe-"));
+		const collector = options.collector;
+		const groupId = options.groupId;
+		const instrument = collector !== void 0 && groupId !== void 0 ? {
+			logLevel: "silent",
+			customLogger: createTsdownLogger(collector, groupId)
+		} : {};
+		const plugins = collector !== void 0 && groupId !== void 0 ? [buildMetricsPlugin(collector, groupId, "exe", options.verbose ?? false)] : [];
+		const timer = createTimer();
 		try {
 			await build({
 				cwd: options.cwd,
@@ -23,9 +38,12 @@ async function runExeBuild(options) {
 					outDir: options.outDir,
 					seaConfig: spec.seaConfig,
 					targets: spec.targets
-				}
+				},
+				...instrument,
+				...plugins.length > 0 ? { plugins } : {}
 			});
 		} finally {
+			if (collector !== void 0 && groupId !== void 0) collector.recordPassTiming(groupId, "exe", timer.elapsed());
 			rmSync(scratch, {
 				recursive: true,
 				force: true

package/exe/config.js

@@ -1,5 +1,9 @@
 //#region src/exe/config.ts
-/** Default Node runtime embedded in the SEA (parity with the vitest-agent reference). */
+/**
+* Default Node runtime embedded in the SEA (parity with the vitest-agent reference).
+*
+* @public
+*/
 const DEFAULT_EXE_NODE_VERSION = "25.9.0";
 /** Map a package.json os value to the tsdown exe platform token. */
 function platformToken(os) {
@@ -24,6 +28,7 @@ function inferTargets(pkg) {
 *
 * Pure function; structural validation (missing fileName, empty targets) lives in the
 * config-validation layer.
+* @public
 */
 function normalizeExeOptions(exe, pkg) {
 	return (Array.isArray(exe) ? exe : [exe]).map((c) => {

package/exe/filename.js

@@ -3,6 +3,7 @@
 * The exact filename `@tsdown/exe` emits for a SEA target, mirroring tsdown's
 * `resolveOutputFileName`: base fileName + `-<platform>-<arch>` + `.exe` on win.
 * Single source of truth so the manifest value never drifts from the on-disk file.
+* @public
 */
 function computeExeFileName(fileName, target) {
 	return `${fileName}${`-${target.platform}-${target.arch}`}${target.platform === "win" ? ".exe" : ""}`;