@savvy-web/bundler 0.2.1 → 0.3.0

package/README.md

@@ -87,7 +87,16 @@ With no `targets` map the build falls back to the single-`npm` group above.
 
 ## API Extractor meta
 
-Set the optional `meta` field on `defineBuild` to generate an [API Extractor](https://api-extractor.com/) api-model from a package's type declarations:
+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 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 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.
 
 ```ts
 const config = defineBuild({
@@ -101,14 +110,10 @@ const config = defineBuild({
     },
   },
 });
-```
 
-With `meta` set, two behaviors come online:
-
-- `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/`.
-
-`meta` is optional; omit it and neither behavior runs. `--target meta` errors if the config has no `meta` field.
+// Or opt out of api-model generation altogether:
+// const config = defineBuild({ meta: false });
+```
 
 ## Executable binaries
 
@@ -222,6 +227,28 @@ const config = defineBuild({
 });
 ```
 
+## Build-time constants
+
+The build injects `process.env.__PACKAGE_VERSION__` as a compile-time constant set to the package's version, so source can read its own version without importing `package.json` at runtime:
+
+```ts
+// somewhere in src/
+const version = process.env.__PACKAGE_VERSION__;
+// the reference is replaced at build time with the package's version as a string literal
+```
+
+Add your own compile-time replacements with the `define` field. Values are inserted verbatim, so string literals must be pre-quoted:
+
+```ts
+const config = defineBuild({
+  define: {
+    "process.env.FLAG": JSON.stringify("on"),
+  },
+});
+```
+
+`define` merges with the auto-injected version constant; a key of `process.env.__PACKAGE_VERSION__` in your own `define` wins.
+
 ## 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.
@@ -237,6 +264,7 @@ const config = defineBuild({
 - **Per-entry overrides** — `overrides` pins a subset of export entries to their own format and bundling, so one entry can ship dual-format CJS in an otherwise ESM-only package without changing the rest.
 - **Readable prod output** — prod output is unminified by default to keep stack traces legible and pass security scanners; `minify` opts back in.
 - **Default manifest stripping** — the published `package.json` drops build- and dev-only fields automatically; a custom `transform` replaces the default and can re-apply it via `defaultManifestTransform`.
+- **Build-time constants** — the package version is injected as `process.env.__PACKAGE_VERSION__`, and the `define` field adds your own verbatim compile-time replacements.
 - **Fast-fail config validation** — `runBuild` validates the config (`publishConfig.targets`, `exe`, `meta`) before any build work, raising a typed `ConfigValidationError` on the first violation.
 - **One devDependency** — `tsdown` is a regular dependency, pinned and tested transitively, so you never carry it or its plugin peers in your own tree.
 - **Injectable orchestration** — `runBuild` takes its IO dependencies as options, so the build is testable without spawning a real bundle.
@@ -244,7 +272,7 @@ const config = defineBuild({
 
 ## API
 
-- `defineBuild(input)` — normalizes a build config (`externals`, `bundle`, `bundleNodeModules`, `bundledPackages`, `dtsExternals`, `minify`, `devManifest`, `transform`, `output`, `meta`, `jsx`, `exe`, `format`, `overrides`), applying defaults. The `format` field controls the output module formats forwarded to tsdown (esm-only by default; add `"cjs"` for a dual-format esm+cjs build). `minify` defaults to false, `transform` defaults to a manifest stripper, and `overrides` pins a subset of entries to their own format and bundling. Pure; it does not run the build.
+- `defineBuild(input)` — normalizes a build config (`externals`, `bundle`, `bundleNodeModules`, `bundledPackages`, `dtsExternals`, `minify`, `devManifest`, `transform`, `output`, `meta`, `jsx`, `exe`, `format`, `overrides`, `define`), applying defaults. The `format` field controls the output module formats forwarded to tsdown (esm-only by default; add `"cjs"` for a dual-format esm+cjs build). `minify` defaults to false, `transform` defaults to a manifest stripper, and `overrides` pins a subset of entries to their own format and bundling. Pure; it does not run the build.
 - `runBuild(config, options)` — the orchestrator. Parses `--target`/`--watch` from `options.argv`, reads `package.json` at `options.cwd`, derives entries, drives the build for the selected target and renders a report. Every IO dependency on `options` is injectable for tests.
 - `parseArgs(argv)` — the argument parser behind `runBuild`, exported for embedding.
 

package/config.js

@@ -18,7 +18,8 @@ function defineBuild(input = {}) {
 		jsx: input.jsx,
 		exe: input.exe,
 		format: input.format,
-		overrides: input.overrides
+		overrides: input.overrides,
+		define: input.define
 	};
 }
 function parseArgs(argv) {

package/index.d.ts

@@ -75,7 +75,13 @@ interface BuildConfigInput {
     targetGroup: TargetGroupRef;
   }) => Json;
   readonly output?: OutputConfig;
-  readonly meta?: MetaOptions;
+  /**
+   * 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.
+   */
+  readonly meta?: MetaOptions | false;
   readonly jsx?: JsxConfig | undefined;
   readonly exe?: ExeConfig | ReadonlyArray<ExeConfig> | undefined;
   /**
@@ -90,6 +96,13 @@ interface BuildConfigInput {
    * an otherwise ESM-only package (e.g. silk's `./changesets/markdownlint`).
    */
   readonly overrides?: ReadonlyArray<BuildEntryOverride> | undefined;
+  /**
+   * Compile-time global replacements forwarded to the tsdown/rolldown build `define`.
+   * Values are inserted VERBATIM, so string literals must be quoted:
+   * `{ "process.env.FLAG": JSON.stringify("on") }`. Merged with the auto-injected
+   * `process.env.__PACKAGE_VERSION__` define; a user key of the same name wins.
+   */
+  readonly define?: Record<string, string> | undefined;
 }
 interface BuildConfig {
   readonly formats: ReadonlyArray<"esm">;
@@ -126,12 +139,14 @@ interface BuildConfig {
     targetGroup: TargetGroupRef;
   }) => Json) | undefined;
   readonly output?: OutputConfig | undefined;
-  readonly meta?: MetaOptions | undefined;
+  readonly meta?: MetaOptions | false | undefined;
   readonly jsx?: JsxConfig | undefined;
   readonly exe?: ExeConfig | ReadonlyArray<ExeConfig> | undefined;
   /** Output module formats forwarded to the tsdown build (esm-only by default; add "cjs" for dual-format). */
   readonly format?: ReadonlyArray<BuildFormat> | undefined;
   readonly overrides?: ReadonlyArray<BuildEntryOverride> | undefined;
+  /** 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). */
 declare function defineBuild(input?: BuildConfigInput): BuildConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/bundler",
-	"version": "0.2.1",
+	"version": "0.3.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",
@@ -24,10 +24,11 @@
 			"types": "./index.d.ts",
 			"import": "./index.js"
 		},
-		"./ecma.json": "./public/ecma.json"
+		"./ecma.json": "./public/ecma.json",
+		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@savvy-web/tsdown-plugins": "0.2.1",
+		"@savvy-web/tsdown-plugins": "0.3.0",
 		"@tsdown/exe": "^0.22.1",
 		"tsdown": "^0.22.2"
 	},

package/run.js

@@ -73,11 +73,18 @@ async function runBuild(config, options) {
 		...publishTargets !== void 0 ? { targets: publishTargets } : {},
 		...config.exe !== void 0 ? { exe: config.exe } : {},
 		osCpu: osCpuForValidate,
-		...config.meta !== void 0 ? { meta: config.meta } : {}
+		...config.meta !== void 0 && config.meta !== false ? { meta: config.meta } : {}
 	})).pipe(Effect.provide(ConfigValidatorLive)));
 	if (target === "meta") {
-		if (config.meta === void 0) throw new Error("`savvy build --target meta` requires a `meta` option in the build config");
-		const norm = normalizeMetaOptions(config.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;
 		await runGenerateMeta({
@@ -177,13 +184,14 @@ async function runBuild(config, options) {
 		...config.transform !== void 0 ? { transform: config.transform } : {},
 		...jsx !== void 0 ? { jsx } : {},
 		...config.format !== void 0 ? { format: config.format } : {},
+		...config.define !== void 0 ? { define: config.define } : {},
 		...overridePartitions.length > 0 ? { overrides: overridePartitions } : {},
 		...dualExports !== void 0 ? { dualExports } : {}
 	});
 	if (target === "prod" && resolution !== void 0) writeBinding(cwd, resolution);
-	if (target === "prod" && config.meta !== void 0) {
+	if (target === "prod" && config.meta !== false) {
 		const metaGroupId = (groups.find((g) => g.name === packageName) ?? groups[0])?.id ?? "npm";
-		const norm = normalizeMetaOptions(config.meta);
+		const norm = normalizeMetaOptions(config.meta ?? {});
 		const dtsBasenames = {};
 		for (const name of Object.keys(entries)) dtsBasenames[name] = name;
 		await runGenerateMeta({