@variantlab/core 0.1.4 → 0.1.6

package/docs/features/codegen.md

@@ -0,0 +1,351 @@
+# Codegen
+
+Turn `experiments.json` into type-safe TypeScript. This document describes how the CLI generates types, what it generates, and how users consume them.
+
+## Table of contents
+
+- [The problem codegen solves](#the-problem-codegen-solves)
+- [What gets generated](#what-gets-generated)
+- [CLI command](#cli-command)
+- [Output file shape](#output-file-shape)
+- [Hook overloads](#hook-overloads)
+- [Watch mode](#watch-mode)
+- [Integration with bundlers](#integration-with-bundlers)
+- [Configuration](#configuration)
+
+---
+
+## The problem codegen solves
+
+Without codegen:
+
+```ts
+const variant = useVariant("news-card-layot"); // typo!
+// variant type: string
+// runtime behavior: falls back to default, silently wrong
+```
+
+With codegen:
+
+```ts
+const variant = useVariant("news-card-layot");
+// ❌ Type error: Argument of type '"news-card-layot"' is not assignable
+//    to parameter of type ExperimentId
+```
+
+Codegen turns stringly-typed experiments into a compile-time contract. Typos become build errors. Refactors are catchable. IDE autocomplete shows every valid ID.
+
+---
+
+## What gets generated
+
+For this config:
+
+```json
+{
+  "version": 1,
+  "experiments": [
+    {
+      "id": "news-card-layout",
+      "type": "render",
+      "default": "responsive",
+      "variants": [
+        { "id": "responsive" },
+        { "id": "scale-to-fit" },
+        { "id": "pip-thumbnail" }
+      ]
+    },
+    {
+      "id": "cta-copy",
+      "type": "value",
+      "default": "buy-now",
+      "variants": [
+        { "id": "buy-now", "value": "Buy now" },
+        { "id": "get-started", "value": "Get started" }
+      ]
+    }
+  ]
+}
+```
+
+The CLI emits:
+
+```ts
+// variantlab.generated.ts
+// AUTO-GENERATED — DO NOT EDIT BY HAND
+// Regenerate with: variantlab generate
+
+export interface VariantLabExperiments {
+  "news-card-layout": {
+    type: "render";
+    variants: "responsive" | "scale-to-fit" | "pip-thumbnail";
+    default: "responsive";
+  };
+  "cta-copy": {
+    type: "value";
+    variants: "buy-now" | "get-started";
+    default: "buy-now";
+    value: "Buy now" | "Get started";
+  };
+}
+
+declare module "@variantlab/core" {
+  interface VariantLabRegistry extends VariantLabExperiments {}
+}
+
+export type ExperimentId = keyof VariantLabExperiments;
+```
+
+The magic is the `declare module` augmentation: it extends `@variantlab/core`'s registry type, which in turn makes all hooks aware of the experiments.
+
+---
+
+## CLI command
+
+```bash
+# One-shot generate
+variantlab generate
+
+# Custom input/output
+variantlab generate --config ./config/experiments.json --out ./src/variantlab.generated.ts
+
+# Watch mode
+variantlab generate --watch
+
+# Verbose
+variantlab generate --verbose
+```
+
+### Exit codes
+
+- `0` — success
+- `1` — config not found
+- `2` — config invalid (schema violation)
+- `3` — output path unwritable
+
+### CI integration
+
+In CI, codegen should run as a validation step:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Validate experiments
+  run: npx variantlab validate experiments.json
+
+- name: Generate types
+  run: npx variantlab generate
+
+- name: Check for uncommitted changes
+  run: git diff --exit-code src/variantlab.generated.ts
+```
+
+This ensures the generated file is checked in and matches the config.
+
+---
+
+## Output file shape
+
+The output is a `.ts` file (not `.d.ts`) because it uses `declare module` which must be in a non-ambient context.
+
+### Header
+
+```ts
+// variantlab.generated.ts
+// AUTO-GENERATED by variantlab v0.1.0 at 2026-04-10T12:00:00Z
+// DO NOT EDIT BY HAND
+// Regenerate with: variantlab generate
+// Source: ./experiments.json
+```
+
+### Interfaces
+
+One interface per experiment, composed into `VariantLabExperiments`.
+
+### Module augmentation
+
+The augmentation hooks into `@variantlab/core`'s `VariantLabRegistry` interface. This is how the hooks become type-aware without the user needing to pass generics.
+
+### Exported helpers
+
+```ts
+export type ExperimentId = keyof VariantLabExperiments;
+
+export type VariantId<T extends ExperimentId> =
+  VariantLabExperiments[T]["variants"];
+
+export type VariantValue<T extends ExperimentId> =
+  VariantLabExperiments[T] extends { value: infer V } ? V : never;
+```
+
+Users can use these directly for typing props, state, etc.
+
+---
+
+## Hook overloads
+
+The core package defines hooks with overloads that look up the registry:
+
+```ts
+// In @variantlab/core (before codegen)
+export interface VariantLabRegistry {}
+
+export function useVariant<K extends keyof VariantLabRegistry>(
+  id: K,
+): VariantLabRegistry[K]["variants"];
+
+export function useVariant(id: string): string; // fallback when no codegen
+```
+
+After codegen, `VariantLabRegistry` has entries, so the first overload wins. TypeScript narrows the return to the exact variant union.
+
+### For render experiments
+
+```ts
+const variant = useVariant("news-card-layout");
+// variant: "responsive" | "scale-to-fit" | "pip-thumbnail"
+```
+
+### For value experiments
+
+```ts
+const value = useVariantValue("cta-copy");
+// value: "Buy now" | "Get started"
+```
+
+### For the `<Variant>` component
+
+```tsx
+<Variant experimentId="news-card-layout">
+  {{
+    responsive: <ResponsiveCard />,
+    "scale-to-fit": <ScaleToFitCard />,
+    // ❌ Type error: Property "pip-thumbnail" is missing
+  }}
+</Variant>
+```
+
+The component's prop is `Record<VariantId<T>, ReactNode>`, so TypeScript enforces exhaustive handling.
+
+---
+
+## Watch mode
+
+`variantlab generate --watch` uses a minimal file watcher (native `fs.watch`) to regenerate on config changes.
+
+- Debounced 100 ms to avoid thrashing on rapid edits
+- Prints a timestamped log line on each regeneration
+- Validates the config before writing; invalid configs do not overwrite the previous output
+- Prints errors clearly with line/column references
+
+### IDE workflow
+
+With watch mode running, the developer edits `experiments.json` and the `.ts` file updates immediately. TypeScript picks up the new types on the next save.
+
+---
+
+## Integration with bundlers
+
+### Next.js
+
+Add a `postinstall` script to regenerate after `npm install`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "variantlab generate",
+    "predev": "variantlab generate",
+    "prebuild": "variantlab generate"
+  }
+}
+```
+
+### Vite
+
+Use a custom plugin wrapper (we ship one):
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import variantlab from "@variantlab/vite-plugin";
+
+export default defineConfig({
+  plugins: [variantlab({ config: "./experiments.json" })],
+});
+```
+
+The plugin:
+
+1. Regenerates the file on dev server start
+2. Watches the config in dev
+3. Fails the build if the config is invalid
+
+### Webpack / Rollup / esbuild / tsup
+
+No special plugin needed — use the npm scripts approach.
+
+---
+
+## Configuration
+
+A project config file (`variantlab.config.ts` or `variantlab.config.json`) controls codegen:
+
+```ts
+// variantlab.config.ts
+import { defineConfig } from "@variantlab/cli";
+
+export default defineConfig({
+  config: "./experiments.json",
+  output: "./src/variantlab.generated.ts",
+  watch: {
+    debounce: 100,
+    ignore: ["**/.git/**", "**/node_modules/**"],
+  },
+  validate: {
+    strict: true, // fail on warnings too
+  },
+});
+```
+
+All options have sensible defaults. The config file is only needed for non-default setups.
+
+---
+
+## Security considerations
+
+- The CLI reads a user-provided JSON file. We validate it against the schema before processing.
+- The output is a plain TypeScript file with no runtime code — no injection vectors.
+- We escape IDs and values before interpolating into the output (no arbitrary code via crafted config values).
+- Path traversal in `--out` is blocked.
+- The CLI rejects configs > 1 MB.
+
+---
+
+## Without codegen
+
+Codegen is **optional**. Users who don't want it can still use all the hooks, with explicit generics:
+
+```ts
+const variant = useVariant<"responsive" | "scale-to-fit">("news-card-layout");
+```
+
+Or just use strings and accept the lack of safety:
+
+```ts
+const variant = useVariant("news-card-layout"); // type: string
+```
+
+Codegen is a DX win, not a requirement.
+
+---
+
+## Bundle size impact
+
+Zero. Codegen emits types only. No runtime code is added. The `.generated.ts` file is erased by the TypeScript compiler.
+
+---
+
+## See also
+
+- [`API.md`](../../API.md) — hook type definitions
+- [`config-format.md`](../design/config-format.md) — the input format
+- [`api-philosophy.md`](../design/api-philosophy.md) — why generics over overloads