first commit

docs/devtools/tooling/test-vite/src/vite-library-config/vite-library-config.md

@@ -0,0 +1,63 @@
+# vite-library-config
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`createViteLibraryConfig` builds an opinionated Vite `UserConfig` suitable for any `@suaveplan/*` library package. It encodes the suaveplan conventions for tree-shake-friendly output, type-declaration emission via `vite-plugin-dts`, and the `external` baseline (`/^@suaveplan\//`, `/^node:/`, `'tslib'`). Every package in the project can drop a one-line `vite.config.ts` and inherit the contract: ESM-first output with `preserveModules`, named exports, and sourcemaps.
+
+## Features
+
+- `preserveModules: true` with `preserveModulesRoot` mirroring the source root.
+- `vite-plugin-dts` plugin pre-pended ahead of caller-supplied plugins.
+- `external` automatically merged with the suaveplan baseline.
+- Zod-validated option boundary; bad input throws `TestViteError(TEST_VITE.INVALID_OPTIONS)`.
+- OTel counter `test_vite_config_built_total{kind="vite_library"}` incremented per invocation.
+
+## Usage: Basic
+
+```ts
+// vite.config.ts
+import { createViteLibraryConfig } from "@suaveplan/test-vite/vite-library-config";
+
+export default createViteLibraryConfig({
+  entries: { index: "src/index.ts" },
+  tsconfigPath: "./tsconfig.lib.json",
+});
+```
+
+## Usage: Advanced
+
+Multi-entry build with extra externals and caller plugins:
+
+```ts
+import path from "node:path";
+import { createViteLibraryConfig } from "@suaveplan/test-vite/vite-library-config";
+
+export default createViteLibraryConfig({
+  root: __dirname,
+  entries: {
+    index: "src/index.ts",
+    "submodule/index": "src/submodule/index.ts",
+  },
+  entryRoot: "src",
+  outDir: "dist",
+  tsconfigPath: "./tsconfig.lib.json",
+  external: ["zod", /^@opentelemetry\//],
+  plugins: [],
+  sourcemap: true,
+  emptyOutDir: true,
+});
+```
+
+## API Reference
+
+- `createViteLibraryConfig(opts: ViteLibraryConfigOptions): UserConfig`.
+- `ViteLibraryConfigOptions` — `{ root?, entries, tsconfigPath?, entryRoot?, outDir?, external?, sourcemap?, emptyOutDir?, plugins? }`.
+- Throws `TestViteError` with code `TEST_VITE.INVALID_OPTIONS` on Zod failure.
+
+## Implementation Notes
+
+The factory mutates nothing on the input; the returned config is freshly constructed. Rollup `output.entryFileNames` is set to `[name].js` so the emitted directory mirrors the source tree. The dts plugin is added with `insertTypesEntry: true` so a single `index.d.ts` shim is emitted for the package root regardless of how many entries are configured. The `external` baseline is intentionally merged via simple concatenation rather than de-duplication so caller-supplied entries always take precedence in Rollup's match order.