@savvy-web/tsdown-plugins 0.3.0 → 0.4.1

package/README.md

@@ -48,6 +48,7 @@ export default defineConfig({
 - **Config validation** — the `ConfigValidator` Effect service (with `ConfigValidatorLive`) fast-fails on a bad `publishConfig.targets`, `exe` or `meta` config, raising the typed `ConfigValidationError`.
 - **dts tsconfig port** — `buildResolvedTsconfig` and `writeResolvedTsconfig` write a temp tsconfig with absolute paths so type declarations emit cleanly under pnpm symlinks.
 - **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. 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.
 - **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.

package/build/build-target-groups.js

@@ -2,7 +2,7 @@ import { emitManifest } from "../manifest/emit-manifest.js";
 import { cjsDefaultInterop } from "./cjs-default-interop.js";
 import { nodeBuiltinDefaultInterop } from "./node-builtin-default-interop.js";
 import { syncPublicDir } from "./sync-public.js";
-import { deriveDtsPassOptions, deriveTargetGroupOptions } from "./target-groups.js";
+import { deriveDtsPassOptions, deriveTargetGroupOptions, outDirFor } from "./target-groups.js";
 import { join } from "node:path";
 
 //#region src/build/build-target-groups.ts
@@ -127,6 +127,37 @@ async function buildTargetGroups(options) {
 				plugins: [...dts.format.includes("cjs") ? [nodeBuiltinDefaultInterop(), cjsDefaultInterop()] : [], ...options.extraPlugins ?? []]
 			});
 		}
+		const looseOutDir = outDirFor(options.cwd, group.id);
+		const isProdGroup = group.id !== "dev";
+		const looseDeps = {
+			...options.externals?.length ? { neverBundle: options.externals } : {},
+			...options.bundle?.length ? { alwaysBundle: options.bundle } : {},
+			...options.bundleNodeModules ? { skipNodeModulesBundle: false } : {}
+		};
+		for (const lf of options.looseFiles ?? []) {
+			const hasCjs = lf.format === "cjs";
+			await build({
+				config: false,
+				cwd: options.cwd,
+				entry: { [lf.entryName]: lf.source },
+				outDir: looseOutDir,
+				format: [lf.format],
+				platform: "node",
+				sourcemap: !isProdGroup,
+				minify: isProdGroup && (options.minify ?? false),
+				unbundle: false,
+				clean: false,
+				fixedExtension: lf.fixedExtension,
+				dts: false,
+				define: {
+					"process.env.__PACKAGE_VERSION__": JSON.stringify(options.version),
+					...options.define
+				},
+				...Object.keys(looseDeps).length > 0 ? { deps: looseDeps } : {},
+				...hasCjs ? { cjsDefault: true } : {},
+				plugins: [...hasCjs ? [nodeBuiltinDefaultInterop(), cjsDefaultInterop()] : [], ...options.extraPlugins ?? []]
+			});
+		}
 	}
 }
 

package/build/loose-files.js

@@ -0,0 +1,57 @@
+import { ConfigValidationError } from "../errors.js";
+import { basename, extname } from "node:path";
+
+//#region src/build/loose-files.ts
+/** Extension to its implied format; `.js` is ambiguous (undefined). */
+const EXT_FORMAT = {
+	".mjs": "esm",
+	".cjs": "cjs",
+	".js": void 0
+};
+/**
+* Resolve a `looseFiles` map into normalized build descriptors. Pure (no filesystem):
+* 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.
+*/
+function normalizeLooseFiles(files) {
+	const out = [];
+	for (const [outFile, raw] of Object.entries(files)) {
+		if (basename(outFile) !== outFile) throw new ConfigValidationError({
+			path: `looseFiles."${outFile}"`,
+			reason: "a loose file must be a root-level filename with no path separator"
+		});
+		const ext = extname(outFile);
+		if (!(ext in EXT_FORMAT)) throw new ConfigValidationError({
+			path: `looseFiles."${outFile}"`,
+			reason: `unsupported output extension "${ext}" — use .mjs, .cjs, or .js`
+		});
+		const source = typeof raw === "string" ? raw : raw.source;
+		const explicit = typeof raw === "string" ? void 0 : raw.format;
+		const inferred = EXT_FORMAT[ext];
+		if (inferred !== void 0 && explicit !== void 0 && explicit !== inferred) throw new ConfigValidationError({
+			path: `looseFiles."${outFile}".format`,
+			reason: `format "${explicit}" contradicts the "${ext}" extension (which implies "${inferred}")`
+		});
+		if (inferred === void 0 && explicit === void 0) throw new ConfigValidationError({
+			path: `looseFiles."${outFile}".format`,
+			reason: "a \".js\" output is format-ambiguous — set format: \"esm\""
+		});
+		const format = inferred ?? explicit;
+		if (ext === ".js" && format === "cjs") throw new ConfigValidationError({
+			path: `looseFiles."${outFile}"`,
+			reason: "a CJS file named \".js\" is not supported yet — name it \".cjs\""
+		});
+		out.push({
+			outFile,
+			entryName: basename(outFile, ext),
+			source,
+			format,
+			fixedExtension: ext !== ".js"
+		});
+	}
+	return out;
+}
+
+//#endregion
+export { normalizeLooseFiles };

package/build/target-groups.js

@@ -1,6 +1,7 @@
 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). */
 function deriveTargetGroupOptions(options) {
@@ -55,4 +56,4 @@ function deriveDtsPassOptions(options) {
 }
 
 //#endregion
-export { deriveDtsPassOptions, deriveTargetGroupOptions };
+export { deriveDtsPassOptions, deriveTargetGroupOptions, outDirFor };

package/config-validation/ConfigValidatorLive.js

@@ -1,5 +1,6 @@
-import { ConfigValidator } from "./ConfigValidator.js";
 import { ConfigValidationError } from "../errors.js";
+import { normalizeLooseFiles } from "../build/loose-files.js";
+import { ConfigValidator } from "./ConfigValidator.js";
 import { normalizeExeOptions } from "../exe/config.js";
 import { resolveTargets } from "../targets/resolve-targets.js";
 import { Effect, Layer } from "effect";
@@ -47,6 +48,7 @@ function check(input) {
 			reason: `"${p}" exists but is not a directory`
 		});
 	}
+	if (input.looseFiles !== void 0) normalizeLooseFiles(input.looseFiles);
 }
 /** Live ConfigValidator: wraps the synchronous rule set, surfacing ConfigValidationError as a typed Effect failure. */
 const ConfigValidatorLive = Layer.succeed(ConfigValidator, { validate: (input) => Effect.try({

package/index.d.ts

@@ -233,6 +233,40 @@ interface DerivedTsdownOptions {
 /** Derive the JS-pass tsdown options for one TargetGroup (per-module JS, no dts). */
 declare function deriveTargetGroupOptions(options: DeriveOptions): DerivedTsdownOptions;
 //#endregion
+//#region src/build/loose-files.d.ts
+/** One standalone bundled output file, declared by its literal output filename. */
+interface LooseFileSpec {
+  /** Source module to bundle into the file. */
+  readonly source: string;
+  /** Module format. Required only for an ambiguous `.js` key; inferred from `.mjs`/`.cjs`. */
+  readonly format?: BuildFormat | undefined;
+}
+/** Map of literal output filename to its source (bare string) or a `{ source, format }` spec. */
+type LooseFiles = Record<string, string | LooseFileSpec>;
+/** A loose file resolved to a concrete build descriptor. */
+interface NormalizedLooseFile {
+  /** Literal output filename written into the package dir, e.g. `pnpmfile.mjs`. */
+  readonly outFile: string;
+  /** tsdown entry name (outFile without its extension), e.g. `pnpmfile`. */
+  readonly entryName: string;
+  /** Source module to bundle. */
+  readonly source: string;
+  /** Resolved module format. */
+  readonly format: BuildFormat;
+  /**
+   * Whether tsdown should use fixed extensions. `.mjs`/`.cjs` need `true` (tsdown derives
+   * `.mjs` for esm and `.cjs` for cjs); a `.js` + esm output needs `false` (tsdown derives `.js`).
+   */
+  readonly fixedExtension: boolean;
+}
+/**
+ * Resolve a `looseFiles` map into normalized build descriptors. Pure (no filesystem):
+ * 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.
+ */
+declare function normalizeLooseFiles(files: LooseFiles): ReadonlyArray<NormalizedLooseFile>;
+//#endregion
 //#region src/build/build-target-groups.d.ts
 /** Signature compatible with tsdown's `build(inlineConfig)`. */
 type TsdownBuild = (config: Record<string, unknown>) => Promise<unknown>;
@@ -327,6 +361,14 @@ interface BuildTargetGroupsOptions {
    * otherwise ESM-only package). The base `entry` must already EXCLUDE these entries.
    */
   readonly overrides?: ReadonlyArray<EntryOverride> | undefined;
+  /**
+   * Standalone bundled output files emitted at literal paths into each group's pkg/ dir,
+   * outside the exports/dts/meta graph (e.g. pnpm config-dependency pnpmfiles). Each runs as
+   * one extra single-entry, bundled (unbundle:false), no-dts, no-manifest pass per group,
+   * inheriting the group's bundleNodeModules/bundle/externals posture so the file is
+   * self-contained. Caller passes the normalized form (see normalizeLooseFiles).
+   */
+  readonly looseFiles?: ReadonlyArray<NormalizedLooseFile> | undefined;
   /**
    * Which export keys get a CJS `require` condition in the emitted manifest. Pass a Set
    * when overrides give different entries different formats; omit for the uniform
@@ -630,6 +672,8 @@ interface ValidationInput {
     readonly cpu: ReadonlyArray<string>;
   } | undefined;
   readonly meta?: MetaOptions | undefined;
+  /** Standalone bundled output files; validated structurally (extension/format) before any build. */
+  readonly looseFiles?: LooseFiles | undefined;
 }
 declare const ConfigValidator_base: Context.TagClass<ConfigValidator, "@savvy-web/tsdown-plugins/ConfigValidator", {
   readonly validate: (input: ValidationInput) => Effect.Effect<void, ConfigValidationError>;
@@ -1465,5 +1509,5 @@ declare function resolveTargets(options: {
   baseName: string;
 }): TargetResolution;
 //#endregion
-export { type BuildEmittedManifestOptions, type BuildFormat, type BuildGroupSpec, type BuildReport, BuildReport as BuildReportSchema, type BuildTargetGroupsOptions, CatalogAssemblyError, CatalogResolutionError, CiAnnotationsFormatter, ConfigValidationError, ConfigValidator, ConfigValidatorLive, DEFAULT_EXE_NODE_VERSION, type DeriveOptions, type DerivedTsdownOptions, type DualExports, type EmitManifestOptions, type EntryOverride, type Environment, EnvironmentDetector, EnvironmentDetectorLive, type ExeBuild, type ExeConfig, type ExeSeaConfig, type ExeTarget, type ExeTargetInput, type Executor, ExecutorResolver, ExecutorResolverLive, type ExtractOptions, type ExtractResult, FormatSelector, FormatSelectorLive, type Formatter, type FormatterContext, type GenerateMetaOptions, type Json, JsonFormatter, type JsxConfig, type ManifestLike, MarkdownFormatter, MetaGenerationError, type MetaOptions, type MetaResult, type NormalizedExe, type NormalizedMeta, type OutputFormat, OutputRenderer, OutputRendererLive, type PackageJsonEntriesOptions, type PackageJsonLike, type PkgOsCpu, type PortableTsconfig, type PublishTargetObject, type PublishTargetValue, type PublishTargets, type RenderReportOptions, type RenderedOutput, ReportPipelineLive, ReportTimings, type ResolvedCompilerOptions, type ResolvedGroup, type ResolvedTarget, type ResolvedTsconfig, type ResolvedTsconfigOptions, type RunExeBuildOptions, SilentFormatter, type TargetGroupId, type TargetGroupRef, type TargetGroupReport, TargetGroupReport as TargetGroupReportSchema, type TargetResolution, TerminalFormatter, type Timer, type TransformManifestOptions, type TsconfigJsx, TsconfigResolver, type TsdocOptions, type TsdocTagDefinition, type TsdownBuild, type ValidationInput, type WarningSuppressionRule, buildEmittedManifest, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, createEntryName, createTimer, defaultManifestTransform, deriveTargetGroupOptions, emitManifest, extractEntries, formatTime, generateBuildReportSchema, generateMeta, isTargetObject, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReport, resolveJsxConfig, resolveManifest, resolvePortableTsconfig, resolveTargets, runExeBuild, syncPublicDir, transformBin, transformExports, transformManifest, writeResolvedTsconfig, writeTargetsBinding };
+export { type BuildEmittedManifestOptions, type BuildFormat, type BuildGroupSpec, type BuildReport, BuildReport as BuildReportSchema, type BuildTargetGroupsOptions, CatalogAssemblyError, CatalogResolutionError, CiAnnotationsFormatter, ConfigValidationError, ConfigValidator, ConfigValidatorLive, DEFAULT_EXE_NODE_VERSION, type DeriveOptions, type DerivedTsdownOptions, type DualExports, type EmitManifestOptions, type EntryOverride, type Environment, EnvironmentDetector, EnvironmentDetectorLive, type ExeBuild, type ExeConfig, type ExeSeaConfig, type ExeTarget, type ExeTargetInput, type Executor, ExecutorResolver, ExecutorResolverLive, type ExtractOptions, type ExtractResult, FormatSelector, FormatSelectorLive, type Formatter, type FormatterContext, type GenerateMetaOptions, type Json, JsonFormatter, type JsxConfig, type LooseFileSpec, type LooseFiles, type ManifestLike, MarkdownFormatter, MetaGenerationError, type MetaOptions, type MetaResult, type NormalizedExe, type NormalizedLooseFile, type NormalizedMeta, type OutputFormat, OutputRenderer, OutputRendererLive, type PackageJsonEntriesOptions, type PackageJsonLike, type PkgOsCpu, type PortableTsconfig, type PublishTargetObject, type PublishTargetValue, type PublishTargets, type RenderReportOptions, type RenderedOutput, ReportPipelineLive, ReportTimings, type ResolvedCompilerOptions, type ResolvedGroup, type ResolvedTarget, type ResolvedTsconfig, type ResolvedTsconfigOptions, type RunExeBuildOptions, SilentFormatter, type TargetGroupId, type TargetGroupRef, type TargetGroupReport, TargetGroupReport as TargetGroupReportSchema, type TargetResolution, TerminalFormatter, type Timer, type TransformManifestOptions, type TsconfigJsx, TsconfigResolver, type TsdocOptions, type TsdocTagDefinition, type TsdownBuild, type ValidationInput, type WarningSuppressionRule, buildEmittedManifest, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, createEntryName, createTimer, defaultManifestTransform, deriveTargetGroupOptions, emitManifest, extractEntries, formatTime, generateBuildReportSchema, generateMeta, isTargetObject, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReport, resolveJsxConfig, resolveManifest, resolvePortableTsconfig, resolveTargets, runExeBuild, syncPublicDir, transformBin, transformExports, transformManifest, writeResolvedTsconfig, writeTargetsBinding };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -7,9 +7,10 @@ import { nodeBuiltinDefaultInterop } from "./build/node-builtin-default-interop.
 import { syncPublicDir } from "./build/sync-public.js";
 import { deriveTargetGroupOptions } from "./build/target-groups.js";
 import { buildTargetGroups } from "./build/build-target-groups.js";
+import { ConfigValidationError, MetaGenerationError } from "./errors.js";
+import { normalizeLooseFiles } from "./build/loose-files.js";
 import { removeDeclarationMaps } from "./build/strip-maps.js";
 import { ConfigValidator } from "./config-validation/ConfigValidator.js";
-import { ConfigValidationError, MetaGenerationError } from "./errors.js";
 import { DEFAULT_EXE_NODE_VERSION, normalizeExeOptions } from "./exe/config.js";
 import { isTargetObject } from "./targets/config.js";
 import { resolveTargets } from "./targets/resolve-targets.js";
@@ -41,4 +42,4 @@ import { generateBuildReportSchema } from "./report/schema-export.js";
 import { writeTargetsBinding } from "./targets/binding.js";
 import { CatalogAssemblyError, CatalogResolutionError } from "workspaces-effect";
 
-export { BuildReport as BuildReportSchema, CatalogAssemblyError, CatalogResolutionError, CiAnnotationsFormatter, ConfigValidationError, ConfigValidator, ConfigValidatorLive, DEFAULT_EXE_NODE_VERSION, EnvironmentDetector, EnvironmentDetectorLive, ExecutorResolver, ExecutorResolverLive, FormatSelector, FormatSelectorLive, JsonFormatter, MarkdownFormatter, MetaGenerationError, OutputRenderer, OutputRendererLive, ReportPipelineLive, ReportTimings, SilentFormatter, TargetGroupReport as TargetGroupReportSchema, TerminalFormatter, TsconfigResolver, buildEmittedManifest, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, createEntryName, createTimer, defaultManifestTransform, deriveTargetGroupOptions, emitManifest, extractEntries, formatTime, generateBuildReportSchema, generateMeta, isTargetObject, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReport, resolveJsxConfig, resolveManifest, resolvePortableTsconfig, resolveTargets, runExeBuild, syncPublicDir, transformBin, transformExports, transformManifest, writeResolvedTsconfig, writeTargetsBinding };
+export { BuildReport as BuildReportSchema, CatalogAssemblyError, CatalogResolutionError, CiAnnotationsFormatter, ConfigValidationError, ConfigValidator, ConfigValidatorLive, DEFAULT_EXE_NODE_VERSION, EnvironmentDetector, EnvironmentDetectorLive, ExecutorResolver, ExecutorResolverLive, FormatSelector, FormatSelectorLive, JsonFormatter, MarkdownFormatter, MetaGenerationError, OutputRenderer, OutputRendererLive, ReportPipelineLive, ReportTimings, SilentFormatter, TargetGroupReport as TargetGroupReportSchema, TerminalFormatter, TsconfigResolver, buildEmittedManifest, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, createEntryName, createTimer, defaultManifestTransform, deriveTargetGroupOptions, emitManifest, extractEntries, formatTime, generateBuildReportSchema, generateMeta, isTargetObject, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReport, resolveJsxConfig, resolveManifest, resolvePortableTsconfig, resolveTargets, runExeBuild, syncPublicDir, transformBin, transformExports, transformManifest, writeResolvedTsconfig, writeTargetsBinding };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/tsdown-plugins",
-	"version": "0.3.0",
+	"version": "0.4.1",
 	"private": false,
 	"description": "Interface-only tsdown/rolldown plugin pack powering @savvy-web/bundler",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/tsdown-plugins",
@@ -28,12 +28,12 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effect/platform-node": "^0.106.0",
-		"@microsoft/api-extractor": "^7.58.7",
+		"@effect/platform-node": "^0.107.0",
+		"@microsoft/api-extractor": "^7.58.8",
 		"@microsoft/tsdoc": "^0.16.0",
 		"@microsoft/tsdoc-config": "^0.18.1",
 		"deep-equal": "^2.2.3",
-		"json-schema-effect": "^0.2.1",
+		"json-schema-effect": "^0.2.2",
 		"picocolors": "^1.1.1",
 		"sort-package-json": "^4.0.0",
 		"std-env": "^4.1.0",