@zigrivers/scaffold 3.6.0 → 3.8.0

package/content/knowledge/library/library-architecture.md

@@ -0,0 +1,247 @@
+---
+name: library-architecture
+description: Module design, dependency minimization, tree-shaking enablement, and plugin patterns for published libraries
+topics: [library, architecture, modules, tree-shaking, plugins, dependencies, design]
+---
+
+Library architecture is constrained by two forces that do not apply to applications: the consumer's bundle size budget and the consumer's dependency graph. Every architectural decision must account for what the library adds to consumers who import it — not just the feature complexity it solves. A well-architected library is modular by default, has minimal or zero runtime dependencies, enables tree-shaking so consumers pay only for what they use, and provides extension points that don't require forking the library.
+
+## Summary
+
+Design libraries as collections of composable, independently tree-shakeable units. The root module is a barrel export; each feature module is independently importable. Minimize runtime dependencies to zero where possible — every dependency you add becomes a transitive dependency for every consumer. Enable tree-shaking by using ES modules, avoiding side effects, and ensuring the `"sideEffects": false` field is accurate. Plugin patterns allow extension without coupling; prefer dependency injection and factory functions over class hierarchies.
+
+Core architectural decisions:
+- Module boundary: each exported function/class is its own module file, barrel at root
+- Dependency strategy: zero runtime deps preferred; peer deps for framework integration
+- Side effects: none at module load time; `"sideEffects": false` in package.json
+- Extension pattern: plugin factory or dependency injection, not subclassing
+- Error strategy: typed error classes, not string codes; never swallow errors
+
+## Deep Guidance
+
+### Module Boundary Design
+
+Each public export should have a clear, single responsibility. The module structure mirrors the API surface:
+
+```
+src/
+├── index.ts           # Barrel: re-exports all public APIs
+├── parser.ts          # parseConfig, ParseOptions, ParseError
+├── validator.ts       # validateSchema, ValidationResult, ValidationError
+├── client.ts          # createClient, ClientOptions, Client interface
+├── types.ts           # Shared types used by multiple modules
+├── errors.ts          # Base error classes
+└── internal/
+    ├── cache.ts       # Internal LRU cache (not exported)
+    ├── http.ts        # Internal HTTP utilities
+    └── utils.ts       # Internal pure utilities
+```
+
+**The key constraint:** modules in `internal/` must never be imported by consumers. Enforce this with an ESLint rule:
+
+```json
+// .eslintrc.json
+{
+  "rules": {
+    "no-restricted-imports": ["error", {
+      "patterns": ["*/internal/*"]
+    }]
+  }
+}
+```
+
+This rule is for consumer code, not for library internals. The library's own modules can freely import from `internal/`.
+
+### Dependency Minimization
+
+Every runtime dependency you add has costs:
+1. Adds to install size for all consumers
+2. Creates a version conflict risk (consumer uses different version of same dep)
+3. Introduces a supply chain attack surface
+4. Creates license compliance requirements for consumers
+
+**Target: zero runtime dependencies for utility libraries.** If the library's value is transforming data, parsing strings, or providing utilities, it should have no runtime dependencies.
+
+**When dependencies are justified:**
+- The dependency solves a genuinely hard problem with no reasonable alternative (cryptography, date parsing)
+- The dependency is a peer dependency the consumer already has (React, Vue, Node.js built-ins)
+- The functionality would require thousands of lines of well-tested code to replicate
+
+**Inlining vs. depending:**
+For small, stable utilities (10-50 lines), consider inlining instead of depending:
+```typescript
+// Instead of: import { clamp } from 'lodash-es'
+// Inline it:
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max)
+}
+```
+
+For large, complex utilities (crypto, parsing), depend on the established library.
+
+### Tree-Shaking Enablement
+
+Tree-shaking requires the bundler to statically analyze which exports are used. Three requirements:
+
+**1. ES module syntax throughout:**
+```typescript
+// Good — static, analyzable
+export function parseConfig(input: string): Config { ... }
+export { validateSchema } from './validator'
+
+// Bad — dynamic, blocks tree-shaking
+module.exports = { parseConfig }  // CommonJS
+exports[functionName] = fn         // Dynamic export key
+```
+
+**2. No side effects at module load time:**
+```typescript
+// BAD: side effect on import — breaks tree-shaking
+const cache = new Map()
+globalThis.__myLibCache = cache  // Pollutes global on import
+console.log('my-library loaded') // Log on import
+
+// GOOD: factory function — no side effect until called
+export function createCache(): Map<string, unknown> {
+  return new Map()
+}
+```
+
+**3. Accurate `sideEffects` field:**
+```json
+// package.json — only if genuinely no side effects
+{ "sideEffects": false }
+
+// If CSS imports or polyfills have side effects:
+{ "sideEffects": ["*.css", "src/polyfills.js"] }
+```
+
+**Verify tree-shaking works:**
+```bash
+# Use bundle-buddy, rollup-plugin-visualizer, or bundlephobia to verify
+npx bundlephobia my-library@1.0.0
+
+# Or build a minimal consumer and check the output bundle size
+# A consumer that only imports parseConfig should not include validateSchema code
+```
+
+### Plugin Architecture Patterns
+
+Plugins allow consumers to extend the library without modifying it. Three patterns in increasing flexibility order:
+
+**Pattern 1: Factory function with options (simplest):**
+```typescript
+export interface ClientOptions {
+  transport?: Transport  // Consumer provides custom transport
+  serializer?: Serializer
+  logger?: Logger
+}
+
+export function createClient(options: ClientOptions = {}): Client {
+  const transport = options.transport ?? defaultHttpTransport()
+  const serializer = options.serializer ?? jsonSerializer()
+  const logger = options.logger ?? noopLogger()
+  return new ClientImpl(transport, serializer, logger)
+}
+
+// Consumer can inject their own transport:
+const client = createClient({
+  transport: myCustomTransport,
+  logger: pinoLogger
+})
+```
+
+This is dependency injection — the simplest, most testable plugin pattern.
+
+**Pattern 2: Plugin registry (for named, composable extensions):**
+```typescript
+export interface Plugin {
+  name: string
+  setup(context: PluginContext): void | Promise<void>
+}
+
+export interface PluginContext {
+  registerTransform(name: string, fn: TransformFn): void
+  registerValidator(name: string, fn: ValidatorFn): void
+  onParse(hook: ParseHook): void
+}
+
+export function createClient(options: { plugins?: Plugin[] } = {}): Client {
+  const context = createPluginContext()
+  for (const plugin of (options.plugins ?? [])) {
+    plugin.setup(context)
+  }
+  return new ClientImpl(context)
+}
+
+// Consumer uses plugins:
+import { myPlugin } from 'my-library-plugin-example'
+const client = createClient({ plugins: [myPlugin()] })
+```
+
+**Pattern 3: Middleware chain (for transform pipelines):**
+```typescript
+export type Middleware<T> = (value: T, next: (value: T) => T) => T
+
+export function createPipeline<T>(middlewares: Middleware<T>[]): (value: T) => T {
+  return (initial: T) => {
+    const chain = middlewares.reduceRight<(value: T) => T>(
+      (next, middleware) => (value) => middleware(value, next),
+      (value) => value
+    )
+    return chain(initial)
+  }
+}
+```
+
+**What to avoid:**
+- Class inheritance as extension mechanism (consumers must subclass to customize — creates tight coupling)
+- Singleton registries (one global registry makes testing and isolation difficult)
+- Monkey-patching as extension (fragile, hidden coupling)
+
+### Error Architecture
+
+Typed errors are part of the public API contract:
+
+```typescript
+// errors.ts — exported as part of public API
+export class LibraryError extends Error {
+  constructor(message: string, public readonly code: ErrorCode) {
+    super(message)
+    this.name = 'LibraryError'
+    // Maintain proper prototype chain in transpiled environments
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
+export class ParseError extends LibraryError {
+  constructor(
+    message: string,
+    public readonly line: number,
+    public readonly column: number,
+    public readonly source?: string
+  ) {
+    super(message, 'PARSE_ERROR')
+    this.name = 'ParseError'
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
+export type ErrorCode = 'PARSE_ERROR' | 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT'
+```
+
+Never throw raw `Error` objects from library code — consumers cannot distinguish library errors from their own errors. Always throw typed errors with enough context to diagnose the problem.
+
+### Avoiding Circular Dependencies
+
+Circular dependencies in libraries cause subtle initialization order bugs. Enforce absence with ESLint:
+
+```json
+{
+  "rules": {
+    "import/no-cycle": ["error", { "maxDepth": 10 }]
+  }
+}
+```
+
+When you detect a circular dependency, the usual fix is extracting shared types to `types.ts` (which has no imports) rather than rearranging imports.

package/content/knowledge/library/library-bundling.md

@@ -0,0 +1,244 @@
+---
+name: library-bundling
+description: ESM/CJS dual publishing, package.json exports map, bundler configuration, and tree-shaking verification for libraries
+topics: [library, bundling, esm, cjs, dual-publishing, exports-map, tree-shaking, tsup, rollup]
+---
+
+Library bundling solves the problem of serving multiple module systems from one codebase. The JavaScript ecosystem is mid-transition from CommonJS to ES modules, and libraries must serve both until the transition completes. Getting bundling wrong produces libraries that fail to import in certain environments, cause dual-package hazards (two instances of the same library loaded simultaneously), or defeat tree-shaking and inflate consumer bundle sizes.
+
+## Summary
+
+Use a bundler (tsup or rollup) rather than raw TypeScript compilation for libraries that need dual ESM/CJS output. The `package.json` exports map is the canonical module resolution contract — define it precisely with condition precedence (types before default, import before require). Set `"sideEffects": false` when true to enable aggressive tree-shaking. Test module resolution in real consumer environments, not just in your build output. ESM-only is acceptable if your minimum supported environment supports it; document this clearly.
+
+Key bundling decisions:
+- Output formats: ESM + CJS for maximum compatibility; ESM-only for modern toolchains
+- File extensions: `.js`/`.cjs` to signal format explicitly
+- Declaration files: emitted alongside each output, not separately
+- Exports map: precise condition ordering (types, import, require, default)
+- Tree-shaking: `sideEffects: false` + ES module output + no barrel-file anti-patterns
+
+## Deep Guidance
+
+### Choosing a Bundler
+
+**tsup (recommended for most libraries):**
+tsup is a TypeScript-first bundler built on esbuild. Fast, opinionated, handles dual ESM/CJS output with declaration files:
+
+```typescript
+// tsup.config.ts
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,               // Emit .d.ts declaration files
+  sourcemap: true,
+  clean: true,             // Clean dist/ before each build
+  splitting: false,        // Keep single output file per format
+  treeshake: true,
+  outExtension({ format }) {
+    return {
+      js: format === 'cjs' ? '.cjs' : '.js'
+    }
+  }
+})
+```
+
+Output:
+```
+dist/
+├── index.js       # ESM
+├── index.cjs      # CJS
+├── index.d.ts     # TypeScript declarations
+└── index.d.cts    # CJS declarations (tsup generates automatically)
+```
+
+**rollup (when you need fine-grained control):**
+```javascript
+// rollup.config.mjs
+import typescript from '@rollup/plugin-typescript'
+import { nodeResolve } from '@rollup/plugin-node-resolve'
+
+export default [
+  {
+    input: 'src/index.ts',
+    output: { file: 'dist/index.js', format: 'es', sourcemap: true },
+    plugins: [nodeResolve(), typescript({ declaration: false })]
+  },
+  {
+    input: 'src/index.ts',
+    output: { file: 'dist/index.cjs', format: 'cjs', sourcemap: true, exports: 'named' },
+    plugins: [nodeResolve(), typescript({ declaration: false })]
+  }
+]
+```
+
+**tsc only (when bundling is unnecessary):**
+If the library has no dependencies to bundle, raw `tsc` with separate CJS and ESM configs works. Use this for pure type libraries or libraries where consumers handle bundling:
+
+```bash
+# ESM
+tsc -p tsconfig.json
+
+# CJS (separate tsconfig)
+tsc -p tsconfig.cjs.json
+```
+
+### Exports Map Configuration
+
+The `exports` field in `package.json` is the definitive module resolution spec for Node.js 12+ and modern bundlers. Define it precisely:
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./plugins": {
+      "import": {
+        "types": "./dist/plugins/index.d.ts",
+        "default": "./dist/plugins/index.js"
+      },
+      "require": {
+        "types": "./dist/plugins/index.d.cts",
+        "default": "./dist/plugins/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  }
+}
+```
+
+**Condition ordering matters:**
+- `types` must come before `default` so TypeScript resolves declarations correctly
+- `import` before `require` (ESM preferred when both are available)
+- `default` as the final fallback
+
+**Legacy fields for older tooling:**
+Keep `"main"` and `"module"` for older bundlers and Node versions that don't support `exports`:
+```json
+{
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}
+```
+
+Bundlers like webpack 4 and older rollup configurations use `"module"` for ESM. Modern tooling uses `exports`.
+
+### Dual Package Hazard
+
+The dual package hazard occurs when both ESM and CJS versions of the same library are loaded in the same process, creating two instances of what should be a singleton. Symptoms: `instanceof` checks fail, shared state doesn't sync, plugin registrations disappear.
+
+**Prevention strategies:**
+
+1. **State in the ESM version only:**
+```javascript
+// dist/index.cjs — CJS wrapper that re-exports the ESM version
+// This ensures only one module instance regardless of import style
+const mod = await import('./index.js')
+module.exports = mod
+```
+
+2. **Stateless library design (best):**
+Design the library with no module-level state. Factory functions create instances; there is no singleton. With no shared state, dual loading is harmless:
+```typescript
+// NO module-level state — safe for dual loading
+export function createCache(): Cache { return new Map() }
+export function parseConfig(input: string): Config { /* pure function */ }
+```
+
+3. **Wrapper CJS file:**
+```javascript
+// dist/index.cjs — thin CJS wrapper
+'use strict'
+const mod = require('./index.js') // This won't work if index.js is ESM
+// Use a proper wrapper instead:
+Object.assign(exports, require('./index-cjs-impl.cjs'))
+```
+
+For complex libraries with state, use approach 1 or design as approach 2.
+
+### Tree-Shaking Verification
+
+After building, verify that tree-shaking actually works:
+
+```bash
+# Install a fresh consumer project and import one function
+mkdir /tmp/tree-shake-test && cd /tmp/tree-shake-test
+npm init -y
+npm install my-library@file:/path/to/library
+
+cat > index.js << 'EOF'
+import { parseConfig } from 'my-library'
+const config = parseConfig('[server]\nhost = "localhost"')
+console.log(config)
+EOF
+
+# Bundle with rollup and check output size
+npx rollup index.js --format iife --bundle > bundle.js
+wc -c bundle.js
+
+# If the bundle is larger than just parseConfig + its dependencies,
+# tree-shaking is not working — investigate the sideEffects field
+# and ES module output
+```
+
+**Common tree-shaking failures:**
+- CommonJS output used (bundler can't statically analyze)
+- `sideEffects: true` in package.json (prevents dead code elimination)
+- Barrel files that import everything (forces all code into bundle)
+- `export * from './large-module'` at root when consumers only use one export
+
+**Subpath exports enable opt-in tree-shaking at the feature level:**
+```typescript
+// Consumer only needs the validator — zero parser code in bundle
+import { validateSchema } from 'my-library/validators'
+```
+
+### Bundle Size Budgets
+
+Define a bundle size budget for browser-targeted libraries:
+
+```json
+// package.json
+{
+  "size-limit": [
+    {
+      "path": "./dist/index.js",
+      "limit": "10 kB"
+    },
+    {
+      "path": "./dist/plugins/index.js",
+      "limit": "5 kB"
+    }
+  ]
+}
+```
+
+```bash
+# Check with size-limit
+npx size-limit
+```
+
+Enforce in CI: if a PR increases bundle size beyond the budget, fail the check. This prevents gradual size bloat.
+
+### Source Maps
+
+Always emit source maps. They enable consumers to debug into the library source when troubleshooting:
+
+```typescript
+// tsup.config.ts
+export default defineConfig({
+  sourcemap: true,  // Emits .js.map alongside .js
+})
+```
+
+Source maps should be included in the published package (`dist/*.map`). They don't significantly affect install size but dramatically improve debugging.