@savvy-web/bundler 0.6.0 → 0.7.0

package/README.md

@@ -49,7 +49,7 @@ npm run build:prod
 # writes dist/prod/npm/pkg — the tarball root, with a resolved manifest and built code
 ```
 
-`--target dev` writes `dist/dev/pkg`, the local-link target with `catalog:`/`workspace:` specifiers preserved. `--target prod` writes `dist/prod/npm/pkg` with those specifiers resolved to concrete ranges, ready to publish. Two further targets, `--target meta` and `--target exe`, are covered below.
+`--target dev` writes `dist/dev/pkg`, the local-link target with `catalog:`/`workspace:` specifiers preserved. `--target prod` writes `dist/prod/npm/pkg` with those specifiers resolved to concrete ranges, ready to publish — and emits the API Extractor api-model alongside it. A third target, `--target exe`, compiles SEA binaries and is covered below.
 
 Every build emits per-module JavaScript alongside a single rolled-up, self-contained `.d.ts` per public entry. Each entry's declaration file pulls in every re-exported type, so a consumer that infers a type from your public API never has to reach into a deep sibling module that no export subpath addresses.
 
@@ -87,22 +87,19 @@ With no `targets` map the build falls back to the single-`npm` group above.
 
 ## API Extractor meta
 
-The bundler generates an [API Extractor](https://api-extractor.com/) api-model from a package's type declarations. Two behaviors come online:
+`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.
 
-- `savvy build --target meta` runs API Extractor over the dev build's `.d.ts` — no tsdown build, so it depends only on a prior `--target dev`. It writes the api-model (`<unscoped>.api.json`, `tsdoc-metadata.json` and a resolved `tsconfig.json`) into each `localPaths` directory.
-- `savvy build --target prod` additionally emits the same bundle into `dist/prod/npm/meta` as a release asset alongside `pkg/`.
+The `meta` field on `defineBuild` is tri-state:
 
-The `meta` field on `defineBuild` is tri-state and controls these:
-
-- **Omitted** (or `undefined`) — generation runs with default options. `--target meta` works with no configuration and `--target prod` emits the meta asset. This is the default; you do not need a `meta` field to use `--target meta`.
-- **An object** — override the defaults: `localPaths` (directories the api-model is copied into on `--target meta`) and `tsdoc` (warning suppression and custom tags).
-- **`false`** — opt out entirely; both `--target meta` and the prod meta asset become no-ops.
+- **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.
+- **An object** — override the defaults: `localPaths` (directories the canonical api-model is copied into), `tsdoc` (warning suppression and custom tags) and `optimistic` (see below).
+- **`false`** — opt out entirely; the prod meta asset becomes a no-op.
 
 ```ts
 const config = defineBuild({
   format: ["esm"],
   meta: {
-    // directories the generated api-model is copied into on `--target meta`
+    // directories the generated api-model is copied into
     localPaths: ["../mcp/models/@savvy-web/bundler"],
     tsdoc: {
       suppressWarnings: [{ messageId: "ae-undocumented" }],
@@ -115,6 +112,16 @@ const config = defineBuild({
 // const config = defineBuild({ meta: false });
 ```
 
+`optimistic` (`"auto"`, the default, or a boolean) forward-looks the meta bundle's own `version` and its workspace-sibling dependency versions to their next release version from pending changesets. `"auto"` is off under CI (`CI` or `GITHUB_ACTIONS` set) and on locally, so a locally generated bundle matches what the CI release build would emit. Set it to `true` or `false` to pin the behavior:
+
+```ts
+const config = defineBuild({
+  meta: { optimistic: false }, // always use the current package.json versions
+});
+```
+
+`--target meta` is deprecated: it warns and no-ops. Generate the api-model with `--target prod` instead.
+
 ## Executable binaries
 
 Set the optional `exe` field to compile a single-executable application (SEA) from a bin entry, via [`@tsdown/exe`](https://www.npmjs.com/package/@tsdown/exe):
@@ -268,7 +275,7 @@ const config = defineBuild({
 ## Features
 
 - **One self-executing config** — `savvy.build.ts` exports a `defineBuild` object for tooling to introspect and runs the build when invoked directly. No factory-notation config file.
-- **Four build targets** — `dev` for local linking, `npm` for a resolved publishable manifest, `meta` for an API Extractor api-model and `exe` for SEA binaries, on disjoint `dist/dev` and `dist/prod` output paths for clean caching.
+- **Build targets** — `dev` for local linking, `prod` for a resolved publishable manifest (which also emits an API Extractor api-model) and `exe` for SEA binaries, on disjoint `dist/dev` and `dist/prod` output paths for clean caching.
 - **Bundled declarations** — per-module JavaScript with a single rolled-up `.d.ts` per public entry, so re-exported types stay reachable through your published export subpaths.
 - **Shared tsconfig base** — extend `@savvy-web/bundler/ecma.json` for the ESNext/NodeNext/strict settings the build expects.
 - **Manifest resolution** — `catalog:` and `workspace:` specifiers are resolved against the workspace for the published target, and preserved for the linked dev target.
@@ -295,7 +302,7 @@ const config = defineBuild({
 
 ## Turbo tasks
 
-`pnpm turbo run build:meta` regenerates api-models into the `localPaths` configured in each package's `savvy.build.ts`, reading the dev build's `dist/dev/pkg` dts; it depends on `build:dev` and is intentionally uncached because it writes outside the package's own cache scope.
+`pnpm turbo run build:prod` produces the publishable output and the api-model bundle in one pass, writing the canonical group's api-model into the `localPaths` configured in each package's `savvy.build.ts`. The standalone `build:meta` task is deprecated — its `--target meta` now warns and no-ops.
 
 ## License
 

package/index.d.ts

@@ -1,4 +1,4 @@
-import { BuildFormat, BuildPlatform, BuildTargetGroupsOptions, CssOptions, ExeConfig, GenerateMetaOptions, Json, JsxConfig, LooseFiles, MetaOptions, MetaResult, PublishTargets, RenderedOutput, RunExeBuildOptions, TargetGroupRef, TargetResolution, TsconfigJsx, defaultManifestTransform } from "@savvy-web/tsdown-plugins";
+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";
 
 //#region src/config.d.ts
 interface BuildEntryOverride {
@@ -86,10 +86,11 @@ interface BuildConfigInput {
   }) => Json;
   readonly output?: OutputConfig;
   /**
-   * API-model (meta) generation. Tri-state: omit it (or `undefined`) to generate with
-   * DEFAULT options — `savvy build --target meta` always works and `--target prod` emits the
-   * meta release asset. Pass an object to override the defaults (`localPaths`, `tsdoc`). Pass
-   * `false` to opt OUT entirely — both `--target meta` and the prod meta asset become no-ops.
+   * API-model (meta) generation. Tri-state: omit it (or `undefined`) to generate with DEFAULT
+   * options; `--target prod` emits the meta release asset for every prod group and copies the
+   * canonical group's bundle into `localPaths`. Pass an object to override defaults (`localPaths`,
+   * `tsdoc`, `optimistic`). Pass `false` to opt OUT (the prod meta asset becomes a no-op).
+   * NOTE: `--target meta` is deprecated and now a no-op; meta is a function of `--target prod`.
    */
   readonly meta?: MetaOptions | false;
   readonly jsx?: JsxConfig | undefined;
@@ -209,6 +210,8 @@ interface RunOptions {
     os: ReadonlyArray<string>;
     cpu: ReadonlyArray<string>;
   }) | undefined;
+  /** Injectable for tests: resolves next release versions for the optimistic meta rewrite. */
+  readonly resolveNextVersions?: ((cwd: string) => Promise<NextVersions>) | undefined;
 }
 /** Run a build from a normalized config. Pure orchestration; all IO injectable. */
 declare function runBuild(config: BuildConfig, options: RunOptions): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/bundler",
-	"version": "0.6.0",
+	"version": "0.7.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,9 +29,9 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@savvy-web/tsdown-plugins": "0.6.0",
+		"@savvy-web/tsdown-plugins": "0.7.0",
 		"@tsdown/exe": "^0.22.1",
-		"tsdown": "^0.22.2"
+		"tsdown": "^0.22.3"
 	},
 	"peerDependencies": {
 		"effect": ">=3.21.0"

package/run.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "./config.js";
-import { ConfigValidator, ConfigValidatorLive, ReportPipelineLive, buildEmittedManifest, buildTargetGroups, computeExeFileName, createEntryName, generateMeta, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReport, resolveJsxConfig, resolveTargets, runExeBuild, writeResolvedTsconfig, writeTargetsBinding } from "@savvy-web/tsdown-plugins";
+import { 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 { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { Effect } from "effect";
@@ -128,34 +128,10 @@ async function runBuild(config, options) {
 	const hasJsEntries = Object.keys(entries).length > 0;
 	validateSubdirOverrides(config.overrides, entries, packageName);
 	if (target === "meta") {
-		if (config.meta === false) {
-			(options.writeOutput ?? ((o) => process.stdout.write(`${o.content}\n`)))({
-				target: "stdout",
-				contentType: "text/plain",
-				content: `meta: generation disabled (meta: false) for ${packageName}`
-			});
-			return;
-		}
-		const norm = normalizeMetaOptions(config.meta ?? {});
-		const dtsBasenames = {};
-		for (const name of Object.keys(entries)) dtsBasenames[name] = name;
-		const exportPaths = deriveExportPaths(entries, exportsMap);
-		applySubdirMetaEntries(config.overrides, dtsBasenames, exportPaths);
-		await runGenerateMeta({
-			cwd,
-			packageName,
-			tsconfigPath,
-			dtsDir: join(cwd, "dist", "dev", "pkg"),
-			entries: dtsBasenames,
-			exportPaths,
-			outMetaDir: join(cwd, "dist", "dev", "meta"),
-			localPaths: norm.localPaths,
-			tsdoc: norm.tsdoc
-		});
 		(options.writeOutput ?? ((o) => process.stdout.write(`${o.content}\n`)))({
 			target: "stdout",
 			contentType: "text/plain",
-			content: `meta: wrote api-model for ${packageName} to ${norm.localPaths.length} localPath(s)`
+			content: `meta: --target meta is deprecated and now a no-op; meta is emitted by --target prod (${packageName}).`
 		});
 		return;
 	}
@@ -254,22 +230,26 @@ 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 metaGroupId = (groups.find((g) => g.name === packageName) ?? groups[0])?.id ?? "npm";
 		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)) dtsBasenames[name] = name;
 		const exportPaths = deriveExportPaths(entries, exportsMap);
 		applySubdirMetaEntries(config.overrides, dtsBasenames, exportPaths);
-		await runGenerateMeta({
+		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({
 			cwd,
 			packageName,
 			tsconfigPath,
-			dtsDir: join(cwd, "dist", "prod", metaGroupId, "pkg"),
+			dtsDir: join(cwd, "dist", "prod", g.id, "pkg"),
 			entries: dtsBasenames,
 			exportPaths,
-			outMetaDir: join(cwd, "dist", "prod", metaGroupId, "meta"),
-			localPaths: [],
-			tsdoc: norm.tsdoc
+			outMetaDir: join(cwd, "dist", "prod", g.id, "meta"),
+			localPaths: g.id === canonicalId ? norm.localPaths : [],
+			tsdoc: norm.tsdoc,
+			...manifestTransform !== void 0 ? { manifestTransform } : {}
 		});
 	}
 	if (target === "prod") for (const g of groups) removeDeclarationMaps(join(cwd, "dist", "prod", g.id, "pkg"));