@savvy-web/bundler 0.8.0 → 0.9.0

package/README.md

@@ -89,6 +89,8 @@ With no `targets` map the build falls back to the single-`npm` group above.
 
 `savvy build --target prod` generates an [API Extractor](https://api-extractor.com/) api-model from each prod group's resolved `.d.ts`. For every group it writes the bundle (`<unscoped>.api.json`, `tsdoc-metadata.json` and a resolved `tsconfig.json`) into `dist/prod/<group>/meta` as a release asset alongside `pkg/`, and copies the canonical group's bundle into any `localPaths` directories. Because it reads the prod build, the meta `package.json` carries concrete dependency versions rather than `catalog:`/`workspace:` specifiers.
 
+API Extractor's analyzer messages — forgotten exports, missing release tags and TSDoc issues — surface in the build log rather than being dropped. A forgotten export (a type reachable from your public API but not itself exported) fails the build under CI (`CI` or `GITHUB_ACTIONS` set); locally it stays a warning so an incremental build is not blocked. Listing the message in `tsdoc.suppressWarnings` suppresses both the local warning and the CI failure, and the build log accounts for what it suppressed.
+
 The `meta` field on `defineBuild` is tri-state:
 
 - **Omitted** (or `undefined`) — generation runs with default options. This is the default; you do not need a `meta` field for `--target prod` to emit the api-model.

package/config.js

@@ -1,7 +1,11 @@
 import { defaultManifestTransform } from "@savvy-web/tsdown-plugins";
 
 //#region src/config.ts
-/** Normalize + validate a defineBuild config. Pure when imported; self-runs when entry (see run.ts). */
+/**
+* Normalize + validate a defineBuild config. Pure when imported; self-runs when entry (see run.ts).
+*
+* @public
+*/
 function defineBuild(input = {}) {
 	return {
 		formats: input.formats ?? ["esm"],
@@ -23,6 +27,7 @@ function defineBuild(input = {}) {
 		define: input.define
 	};
 }
+/** Parse the build CLI argv into the normalized target/flags shape. @public */
 function parseArgs(argv) {
 	let target = "dev";
 	let watch = false;

package/index.d.ts

@@ -1,6 +1,7 @@
-import { BuildFormat, BuildPlatform, BuildTargetGroupsOptions, CssOptions, ExeConfig, GenerateMetaOptions, Json, JsxConfig, LooseFiles, MetaOptions, MetaResult, NextVersions, PublishTargets, RenderedOutput, RunExeBuildOptions, TargetGroupRef, TargetResolution, TsconfigJsx, defaultManifestTransform } from "@savvy-web/tsdown-plugins";
+import { BuildFormat, BuildPlatform, BuildReport, BuildTargetGroupsOptions, CssOptions, ExeConfig, GenerateMetaOptions, Json, JsxConfig, LooseFiles, MetaOptions, MetaResult, NextVersions, PublishTargets, RenderedOutput, RunExeBuildOptions, TargetGroupRef, TargetResolution, TsconfigJsx, defaultManifestTransform } from "@savvy-web/tsdown-plugins";
 
 //#region src/config.d.ts
+/** @public */
 interface BuildEntryOverride {
   /** Export paths to pin to this partition, e.g. "./changesets/markdownlint" (or "." for root). */
   readonly entries: ReadonlyArray<string>;
@@ -21,6 +22,7 @@ interface BuildEntryOverride {
    */
   readonly outSubdir?: string | undefined;
 }
+/** @public */
 interface OutputConfig {
   readonly console?: {
     readonly human?: boolean;
@@ -29,6 +31,7 @@ interface OutputConfig {
   };
   readonly format?: "terminal" | "json" | "markdown" | "ci-annotations" | "silent";
 }
+/** @public */
 interface BuildConfigInput {
   readonly formats?: ReadonlyArray<"esm">;
   readonly externals?: ReadonlyArray<string>;
@@ -50,8 +53,8 @@ interface BuildConfigInput {
   /**
    * Force-bundle node_modules (and workspace) JS dependencies that are not
    * externalized into the package output, restoring the self-contained bundle
-   * the rslib builder produced. Threads tsdown `deps.skipNodeModulesBundle:
-   * false` into BOTH the JS output and the bundled declarations: the dts posture
+   * the rslib builder produced. Threads tsdown `deps.skipNodeModulesBundle: false`
+   * into BOTH the JS output and the bundled declarations: the dts posture
    * tracks the JS posture, so node_modules types are inlined into the `.d.ts`
    * and the published package needs no extra declared deps for them. Defaults to false.
    */
@@ -75,7 +78,7 @@ interface BuildConfigInput {
   readonly devManifest?: "preserve" | "resolve";
   /**
    * Final mutation of the emitted package.json, run after the declarative
-   * `publishConfig.targets` rename. Defaults to {@link defaultManifestTransform},
+   * `publishConfig.targets` rename. Defaults to `defaultManifestTransform`,
    * which strips build/dev-only fields (devDependencies, scripts, publishConfig,
    * etc.). Supplying your own REPLACES that default — import and call
    * `defaultManifestTransform` from it if you still want the stripping.
@@ -123,6 +126,7 @@ interface BuildConfigInput {
    */
   readonly define?: Record<string, string> | undefined;
 }
+/** @public */
 interface BuildConfig {
   readonly formats: ReadonlyArray<"esm">;
   readonly externals: ReadonlyArray<string>;
@@ -169,8 +173,13 @@ interface BuildConfig {
   /** Compile-time global replacements forwarded to the build `define` (merged with the auto-version). */
   readonly define?: Record<string, string> | undefined;
 }
-/** Normalize + validate a defineBuild config. Pure when imported; self-runs when entry (see run.ts). */
+/**
+ * Normalize + validate a defineBuild config. Pure when imported; self-runs when entry (see run.ts).
+ *
+ * @public
+ */
 declare function defineBuild(input?: BuildConfigInput): BuildConfig;
+/** @public */
 interface ParsedArgs {
   readonly target: "dev" | "prod" | "meta" | "exe";
   readonly watch: boolean;
@@ -178,9 +187,11 @@ interface ParsedArgs {
   readonly noExe: boolean;
   readonly verbose: boolean;
 }
+/** Parse the build CLI argv into the normalized target/flags shape. @public */
 declare function parseArgs(argv: ReadonlyArray<string>): ParsedArgs;
 //#endregion
 //#region src/run.d.ts
+/** @public */
 interface RunOptions {
   readonly cwd: string;
   readonly argv: ReadonlyArray<string>;
@@ -213,8 +224,15 @@ interface RunOptions {
   }) | undefined;
   /** Injectable for tests: resolves next release versions for the optimistic meta rewrite. */
   readonly resolveNextVersions?: ((cwd: string) => Promise<NextVersions>) | undefined;
+  /** Injectable issues-artifact writer (defaults to writeIssuesArtifact). */
+  readonly writeIssues?: (opts: {
+    cwd: string;
+    target: "dev" | "prod";
+    reports: ReadonlyArray<BuildReport>;
+    now?: () => Date;
+  }) => string | undefined;
 }
-/** Run a build from a normalized config. Pure orchestration; all IO injectable. */
+/** Run a build from a normalized config. Pure orchestration; all IO injectable. @public */
 declare function runBuild(config: BuildConfig, options: RunOptions): Promise<void>;
 //#endregion
 export { type BuildConfig, type BuildConfigInput, type BuildEntryOverride, type OutputConfig, type ParsedArgs, type RunOptions, defaultManifestTransform, defineBuild, parseArgs, runBuild };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/bundler",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"private": false,
 	"description": "Zero-config tsdown-based bundler for Silk Suite TypeScript packages",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/bundler",
@@ -29,16 +29,16 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@savvy-web/tsdown-plugins": "0.8.0",
+		"@savvy-web/tsdown-plugins": "0.9.0",
 		"@tsdown/exe": "^0.22.1",
-		"effect": "^3.21.3",
+		"effect": "^3.21.4",
 		"tsdown": "^0.22.3"
 	},
 	"peerDependencies": {
-		"@types/node": "^25.9.0",
+		"@types/node": "^26.0.0",
 		"@types/react": "^19.2.0",
 		"@types/react-dom": "^19.2.0",
-		"@typescript/native-preview": "^7.0.0-dev.20260513.1",
+		"@typescript/native-preview": "^7.0.0-dev.20260612.1",
 		"react": "^19.2.0",
 		"react-dom": "^19.2.0",
 		"typescript": "^6.0.0"

package/run.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "./config.js";
-import { BuildCollector, ConfigValidator, ConfigValidatorLive, ReportPipelineLive, buildEmittedManifest, buildTargetGroups, computeExeFileName, createEntryName, generateMeta, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReport, resolveJsxConfig, resolveNextVersions, resolveTargets, rewriteMetaVersions, runExeBuild, writeResolvedTsconfig, writeTargetsBinding } from "@savvy-web/tsdown-plugins";
+import { BuildCollector, ConfigValidator, ConfigValidatorLive, ReportPipelineLive, buildEmittedManifest, buildTargetGroups, computeExeFileName, createEntryName, deriveExportPaths, normalizeExeOptions, normalizeLooseFiles, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReport, resolveJsxConfig, resolveTargets, runExeBuild, runMetaPass, writeIssuesArtifact, writeResolvedTsconfig, writeTargetsBinding } from "@savvy-web/tsdown-plugins";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { Effect } from "effect";
@@ -27,22 +27,14 @@ function deriveProdGroups(targets, baseName) {
 		resolution
 	};
 }
-/** Map entry names to export paths using the package exports map. index maps to ".". */
-function deriveExportPaths(entries, exportsMap) {
-	const out = {};
-	const sourceToKey = /* @__PURE__ */ new Map();
-	if (exportsMap) for (const [key, src] of Object.entries(exportsMap)) sourceToKey.set(src, key);
-	for (const [entryName, src] of Object.entries(entries)) out[entryName] = sourceToKey.get(src) ?? (entryName === "index" ? "." : `./${entryName}`);
-	return out;
-}
 /**
 * Fast-fail validation for `outSubdir` overrides, run on EVERY target path. The dev/prod override-partition
 * loop already validates these (and all other overrides) before building, but `--target meta` returns early
-* (before that loop) and remaps meta dts basenames via `applySubdirMetaEntries` — which assumes validated
-* input. Without this guard, a malformed `outSubdir` override (more than one entry, a non-canonical export
-* path, or an export path that is not a real build entry) would silently remap a wrong/nonexistent key on the
-* meta path. Mirrors the override loop's conditions and messages verbatim so every target path fast-fails
-* identically. No-op when there are no overrides or none set `outSubdir`.
+* (before that loop) and remaps meta dts basenames (logic now in @savvy-web/tsdown-plugins) — which assumes
+* validated input. Without this guard, a malformed `outSubdir` override (more than one entry, a non-canonical
+* export path, or an export path that is not a real build entry) would silently remap a wrong/nonexistent key
+* on the meta path. Mirrors the override loop's conditions and messages verbatim so every target path
+* fast-fails identically. No-op when there are no overrides or none set `outSubdir`.
 */
 function validateSubdirOverrides(overrides, entries, packageName) {
 	if (overrides === void 0) return;
@@ -55,24 +47,7 @@ function validateSubdirOverrides(overrides, entries, packageName) {
 		if (entries[flatName] === void 0) throw new Error(`overrides: export path "${exportPath}" (entry "${flatName}") is not a build entry of ${packageName}`);
 	}
 }
-/**
-* For each `outSubdir` override, point its meta entry at the isolated sub-package barrel: the dts lives
-* at `<subdir>/index.d.ts` (not `<flatName>.d.ts`). Keyed by the stable flattened entry name so it
-* overwrites the default `dtsBasenames[flatName] = flatName` set from the full entry map. No-op when no
-* override sets `outSubdir`.
-*/
-function applySubdirMetaEntries(overrides, dtsBasenames, exportPaths) {
-	if (overrides === void 0) return;
-	for (const ov of overrides) {
-		if (ov.outSubdir === void 0) continue;
-		const exportPath = ov.entries[0];
-		if (exportPath === void 0) continue;
-		const flatName = createEntryName(exportPath, false);
-		dtsBasenames[flatName] = `${ov.outSubdir}/index`;
-		exportPaths[flatName] = exportPath;
-	}
-}
-/** Run a build from a normalized config. Pure orchestration; all IO injectable. */
+/** Run a build from a normalized config. Pure orchestration; all IO injectable. @public */
 async function runBuild(config, options) {
 	const { target, noExe, verbose } = parseArgs(options.argv);
 	const build = options.buildTargetGroups ?? buildTargetGroups;
@@ -91,7 +66,6 @@ async function runBuild(config, options) {
 		...jsx?.runtime === "classic" ? { jsx: "react" } : {}
 	})))(cwd);
 	const exportsMap = options.readExports ? options.readExports() : pkg.exports;
-	const runGenerateMeta = options.generateMeta ?? generateMeta;
 	const publishTargets = (options.readPublishTargets ?? (() => {
 		const declared = pkg.publishConfig?.targets;
 		return declared !== void 0 && !Array.isArray(declared) && typeof declared === "object" ? declared : void 0;
@@ -218,6 +192,16 @@ async function runBuild(config, options) {
 		}).pipe(Effect.provide(ReportPipelineLive)));
 		for (const output of rendered) writeOutput(output);
 	};
+	const writeIssuesBestEffort = () => {
+		if (target !== "dev" && target !== "prod") return;
+		try {
+			(options.writeIssues ?? writeIssuesArtifact)({
+				cwd,
+				target,
+				reports: collector.snapshot(packageName)
+			});
+		} catch {}
+	};
 	try {
 		if (hasJsEntries || config.exe === void 0) await build({
 			cwd,
@@ -246,30 +230,20 @@ async function runBuild(config, options) {
 		});
 		if (target === "prod" && resolution !== void 0) writeBinding(cwd, resolution);
 		if (target === "prod" && config.meta !== false && (config.exe === void 0 || hasJsEntries)) {
-			const norm = normalizeMetaOptions(config.meta ?? {});
-			const canonicalId = (groups.find((g) => g.name === packageName) ?? groups[0])?.id ?? "npm";
-			const dtsBasenames = {};
-			for (const name of Object.keys(entries)) if (!name.startsWith("bin/")) dtsBasenames[name] = name;
-			const exportPaths = deriveExportPaths(entries, exportsMap);
-			applySubdirMetaEntries(config.overrides, dtsBasenames, exportPaths);
-			const resolveNext = options.resolveNextVersions ?? resolveNextVersions;
-			const nextVersions = norm.optimistic ? await resolveNext(cwd) : void 0;
-			const manifestTransform = nextVersions ? (m) => rewriteMetaVersions(m, nextVersions.versions, packageName) : void 0;
-			for (const g of groups) await runGenerateMeta({
+			const ci = process.env.CI === "true" || process.env.GITHUB_ACTIONS === "true";
+			await runMetaPass({
 				cwd,
 				packageName,
 				tsconfigPath,
-				dtsDir: join(cwd, "dist", "prod", g.id, "pkg"),
-				entries: dtsBasenames,
-				exportPaths,
-				outMetaDir: join(cwd, "dist", "prod", g.id, "meta"),
-				localPaths: g.id === canonicalId ? norm.localPaths : [],
-				tsdoc: norm.tsdoc,
-				...manifestTransform !== void 0 ? { manifestTransform } : {},
-				onMessage: (e) => {
-					if (e.level === "error") collector.recordError(g.id, e);
-					else collector.recordWarning(g.id, e);
-				}
+				groups,
+				entries,
+				exportsMap,
+				overrides: config.overrides,
+				meta: config.meta ?? {},
+				collector,
+				ci,
+				...options.generateMeta !== void 0 ? { generateMeta: options.generateMeta } : {},
+				...options.resolveNextVersions !== void 0 ? { resolveNextVersions: options.resolveNextVersions } : {}
 			});
 		}
 		if (target === "prod") for (const g of groups) removeDeclarationMaps(join(cwd, "dist", "prod", g.id, "pkg"));
@@ -312,9 +286,11 @@ async function runBuild(config, options) {
 		}
 	} catch (err) {
 		await renderAndWrite();
+		writeIssuesBestEffort();
 		throw err;
 	}
 	await renderAndWrite();
+	writeIssuesBestEffort();
 }
 
 //#endregion

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}