@savvy-web/tsdown-plugins 0.8.0 → 0.9.1

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

@@ -23,6 +23,7 @@ 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;

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"];

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

@@ -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

@@ -6,7 +6,11 @@ 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) {

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" : ""}`;