@zigrivers/scaffold 3.7.0 → 3.9.0

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.

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

@@ -0,0 +1,229 @@
+---
+name: library-conventions
+description: Public API naming, deprecation patterns, changelog conventions, and export patterns for published libraries
+topics: [library, conventions, naming, deprecation, changelog, exports, api-design]
+---
+
+Library conventions are the agreements that make a library predictable, navigable, and trustworthy across versions. They cover how public APIs are named, how deprecated APIs are marked and eventually removed, how changes are communicated through changelogs, and how exports are structured. Inconsistent conventions are a tax on every consumer — they create confusion about what is stable, what is safe to use, and what changed between versions.
+
+## Summary
+
+Establish and document conventions before publishing v1. Key areas: consistent naming patterns (verbs for functions, nouns for types/classes, `is`/`has` for predicates), deprecation lifecycle with JSDoc markers and migration guidance, changelog format (Keep a Changelog or Conventional Commits), and export structure that makes tree-shaking possible. Internal exports must be clearly separated from public exports to avoid accidental API surface expansion.
+
+Core conventions:
+- Functions: verb-noun (`parseConfig`, `validateSchema`, `createClient`)
+- Types/interfaces: PascalCase nouns (`ParseOptions`, `ClientConfig`, `ValidationError`)
+- Predicates: `is` prefix (`isError`, `isValidConfig`)
+- Constants: SCREAMING_SNAKE for module-level, camelCase for config object keys
+- Deprecation: JSDoc `@deprecated` + replacement reference + removal version
+- Changelog: per-version sections with Added / Changed / Deprecated / Removed / Fixed / Security
+
+## Deep Guidance
+
+### Public API Naming
+
+Naming is the most visible part of the API contract. Inconsistency in naming signals immaturity and creates cognitive load for consumers.
+
+**Functions — verb-noun pattern:**
+```typescript
+// Good: verb-noun, action is clear
+parseConfig(input: string): Config
+validateSchema(schema: Schema): ValidationResult
+createClient(options: ClientOptions): Client
+formatError(error: unknown): string
+resolveModulePath(specifier: string): string
+
+// Bad: ambiguous, no verb, or inverted
+config(input: string): Config        // what does it do?
+schemaValidator(schema: Schema): ... // -or suffix is not a function verb
+client(options: ClientOptions): ...  // noun-only looks like a constructor
+```
+
+**Types and interfaces — PascalCase nouns:**
+```typescript
+// Good
+interface ParseOptions { ... }
+type ValidationResult = { valid: boolean; errors: ValidationError[] }
+class ConfigClient { ... }
+type ErrorCode = 'NOT_FOUND' | 'INVALID' | 'TIMEOUT'
+
+// Bad
+interface parseOptions { ... }    // lowercase
+type validation_result = ...      // snake_case
+type ErrCode = ...                // abbreviation
+```
+
+**Predicates — `is` prefix:**
+```typescript
+function isError(value: unknown): value is Error
+function isValidConfig(config: unknown): config is Config
+function hasRequiredFields(obj: unknown): boolean  // 'has' for possession checks
+```
+
+**Boolean options — avoid double negatives:**
+```typescript
+// Good
+interface Options {
+  strict: boolean        // enable strict mode
+  cache: boolean         // enable caching
+}
+
+// Bad
+interface Options {
+  noStrict: boolean      // double negative when true disables
+  disableCache: boolean  // confusing when combined: disableCache: false
+}
+```
+
+**Error types — descriptive, namespace-prefixed:**
+```typescript
+// Good: namespaced, descriptive
+class ParseError extends Error {
+  constructor(message: string, public readonly line: number, public readonly col: number) {
+    super(message)
+    this.name = 'ParseError'
+  }
+}
+
+// Available as named export:
+export { ParseError, ValidationError, NetworkError, TimeoutError }
+```
+
+### Deprecation Lifecycle
+
+Deprecation is a promise to consumers: "this still works today, but plan to migrate." It must be communicated at multiple levels.
+
+**Step 1: Add `@deprecated` JSDoc in a MINOR release:**
+```typescript
+/**
+ * Parse a configuration string.
+ * @deprecated Use `parseConfig()` instead. Will be removed in v3.0.
+ * @see parseConfig
+ */
+export function parse(input: string): Config {
+  return parseConfig(input)
+}
+```
+
+The `@deprecated` tag causes TypeScript to show strikethrough in IDEs and emit warnings. Always include:
+- What to use instead
+- When it will be removed (target major version)
+
+**Step 2: Log a runtime warning (optional, for JS users without TypeScript):**
+```typescript
+export function parse(input: string): Config {
+  if (process.env.NODE_ENV !== 'production') {
+    console.warn(
+      '[my-library] parse() is deprecated. Use parseConfig() instead. ' +
+      'Will be removed in v3.0. See migration guide: https://example.com/v3-migration'
+    )
+  }
+  return parseConfig(input)
+}
+```
+
+Only add runtime warnings if the library has significant JS (non-TypeScript) consumers. Don't pollute production logs.
+
+**Step 3: Remove in the next major version:**
+- Remove the export entirely
+- Add a clear CHANGELOG entry with migration instructions
+- Include migration guide link in the changelog entry
+
+**Deprecation period policy:**
+The minimum deprecation period before removal should be one full major version. If you deprecate in v2.3, the earliest removal is v3.0. Communicate the removal version at deprecation time.
+
+### Changelog Conventions
+
+Follow the [Keep a Changelog](https://keepachangelog.com) format. Every release must have a changelog entry before publishing.
+
+**Format:**
+```markdown
+# Changelog
+
+## [Unreleased]
+
+## [2.1.0] - 2024-03-15
+
+### Added
+- `parseConfig()` function as the new primary parsing API
+- `ParseOptions.strict` flag for strict mode validation
+
+### Changed
+- `createClient()` now accepts `ClientOptions.timeout` in milliseconds (previously seconds)
+
+### Deprecated
+- `parse()` — use `parseConfig()` instead. Will be removed in v3.0.
+
+### Fixed
+- `validateSchema()` no longer throws on empty input; returns `{ valid: false, errors: [] }`
+
+## [2.0.0] - 2024-01-10
+
+### Breaking Changes
+- Removed `connect()` (deprecated since v1.5.0). Use `createClient()`.
+- `Config.timeout` is now in milliseconds (was seconds in v1.x). Multiply existing values by 1000.
+
+### Migration from v1.x
+See: https://example.com/v2-migration
+```
+
+Rules:
+- Every entry in "Breaking Changes" must have a migration instruction or link
+- "Added" entries must reference the new API by name
+- "Fixed" entries must describe the incorrect behavior and the correct behavior
+- Never put vague entries like "Various bug fixes" — enumerate them
+
+### Export Patterns
+
+How you structure exports determines your tree-shaking story and your public API surface.
+
+**Root index.ts — explicit, intentional exports only:**
+```typescript
+// src/index.ts
+// Public API — these are the semver-protected exports
+
+// Core functions
+export { parseConfig } from './parser'
+export { validateSchema } from './validator'
+export { createClient } from './client'
+
+// Types
+export type { ParseOptions, ParseResult } from './parser'
+export type { ValidationResult, ValidationError } from './validator'
+export type { ClientOptions, Client } from './client'
+
+// Error types
+export { ParseError, ValidationError as LibValidationError } from './errors'
+
+// DO NOT export internal utilities
+// DO NOT re-export everything with `export * from './...'`
+```
+
+**Avoid `export *` at the root:** It makes the API surface opaque and causes accidental exports of internal symbols.
+
+**Subpath exports for optional features:**
+```typescript
+// package.json exports map (see library-bundling.md for full config)
+{
+  "exports": {
+    ".": "./dist/index.js",
+    "./plugins": "./dist/plugins/index.js",
+    "./testing": "./dist/testing/index.js"
+  }
+}
+```
+
+Consumers who don't use plugins pay zero bundle cost. Testing utilities stay separate from production code.
+
+**Barrel files — use sparingly:**
+Barrel files (files that re-export from many modules) can defeat tree-shaking in some bundlers. Prefer deep imports in internal code; use the root barrel only for the public API.
+
+### Convention Documentation
+
+Every library must have a `CONTRIBUTING.md` or `docs/conventions.md` documenting:
+1. Naming conventions for new API additions
+2. Deprecation lifecycle steps (checklist format)
+3. Changelog update requirement (must update before PR merges)
+4. Export checklist for new public APIs
+
+Without documented conventions, contributors add APIs inconsistently, and the library accumulates naming debt that is expensive to fix without breaking changes.

package/content/knowledge/library/library-dev-environment.md

@@ -0,0 +1,220 @@
+---
+name: library-dev-environment
+description: Monorepo setup, npm link workflow, build watch mode, and local consumer testing for library development
+topics: [library, dev-environment, monorepo, npm-link, build-watch, local-testing]
+---
+
+Library development environment setup is distinct from application development: you are building code that will be consumed by other projects, which means your dev workflow must include a way to test the library as a consumer would — before publishing to npm. The feedback loop between changing library source and seeing the effect in a consumer application is the central challenge. Get this wrong, and you spend hours debugging issues that only surface after publish.
+
+## Summary
+
+Use build watch mode (TypeScript `--watch` or a bundler watcher) for fast feedback during development. For testing in a real consumer project, use `npm link` or workspace-relative `file:` references. In monorepos, use npm/pnpm/yarn workspaces to co-locate the library and consumer apps. Never develop library code exclusively through unit tests — always validate through a real consumer context. Set up scripts for the full dev loop: `build:watch` in one terminal, consumer app in another.
+
+Core workflow tools:
+- `tsc --watch` for TypeScript compilation feedback
+- `npm link` / `pnpm link` for local cross-project testing
+- Workspace `file:` references for monorepo consumers
+- `npm pack` + install for pre-publish verification
+
+## Deep Guidance
+
+### Build Watch Mode
+
+The development feedback loop starts with build watch mode. TypeScript's `--watch` mode recompiles on every save:
+
+```bash
+# Terminal 1: watch the library build
+npm run build:watch
+
+# package.json script:
+"build:watch": "tsc -p tsconfig.json --watch --preserveWatchOutput"
+```
+
+For more complex builds (bundling, multiple outputs), use a bundler watcher:
+
+```bash
+# With tsup (recommended for dual ESM/CJS builds)
+"build:watch": "tsup --watch"
+
+# tsup.config.ts
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  watch: process.env.WATCH === 'true'
+})
+```
+
+TypeScript `--watch` alone is sufficient for type-only changes. If you're bundling (minifying, inlining), use the bundler's watch mode.
+
+### npm link Workflow
+
+`npm link` creates a symlink from your global npm prefix to the library, then links that into the consuming project:
+
+```bash
+# In the library directory:
+cd my-library
+npm link
+# Creates: ~/.nvm/versions/node/vX/lib/node_modules/my-library -> /path/to/my-library
+
+# In the consuming project:
+cd my-app
+npm link my-library
+# Creates: my-app/node_modules/my-library -> ~/.nvm/.../my-library
+
+# The consumer now uses the live dist/ from the library
+```
+
+**Caveats with npm link:**
+- The consumer uses the `dist/` directory, so the library must be built first and kept rebuilt via watch mode
+- React and other singleton libraries can cause issues because the library and consumer may each resolve their own copy: use `npm link my-app/node_modules/react` inside the library to force shared resolution
+- `npm install` in the consumer will break the link — you must re-run `npm link my-library`
+
+**Preferred alternative: `file:` reference in consumer:**
+```json
+// my-app/package.json
+{
+  "dependencies": {
+    "my-library": "file:../my-library"
+  }
+}
+```
+
+Run `npm install` in `my-app`. This creates a symlink into `my-library/` respecting the `exports` map. Survives `npm install` (unlike `npm link`). Requires the library to have its `dist/` built.
+
+### pnpm Workspace Setup (Recommended for Monorepos)
+
+pnpm workspaces handle library + consumer in the same repository without symlink complexity:
+
+```yaml
+# pnpm-workspace.yaml (at monorepo root)
+packages:
+  - 'packages/*'
+  - 'apps/*'
+  - 'examples/*'
+```
+
+```
+monorepo/
+├── packages/
+│   └── my-library/
+│       ├── src/
+│       ├── dist/
+│       └── package.json  # name: "my-library"
+├── apps/
+│   └── my-app/
+│       └── package.json  # depends on "my-library": "workspace:*"
+└── pnpm-workspace.yaml
+```
+
+```json
+// apps/my-app/package.json
+{
+  "dependencies": {
+    "my-library": "workspace:*"
+  }
+}
+```
+
+With `workspace:*`, pnpm links to the local package automatically. The `dist/` directory is used (respecting `exports` map), so the library still needs to be built.
+
+**Monorepo dev script:**
+```bash
+# Run both library watch and app dev server in parallel
+"dev": "concurrently \"npm run build:watch -w packages/my-library\" \"npm run dev -w apps/my-app\""
+```
+
+### Pre-publish Verification with npm pack
+
+Before publishing, verify the actual package contents:
+
+```bash
+# Pack the library without publishing
+npm pack --dry-run
+
+# This shows exactly what files will be included in the published package
+# Look for:
+# - dist/ files present (ESM, CJS, .d.ts)
+# - No src/ files (source not published)
+# - No test files
+# - README.md and CHANGELOG.md present
+# - No .env or secrets
+
+# Pack to a tarball and install it in a test project
+npm pack
+# Creates: my-library-1.0.0.tgz
+
+# In a fresh test project:
+npm install ../my-library/my-library-1.0.0.tgz
+```
+
+Installing the tarball is the most faithful pre-publish test. It reproduces exactly what consumers get from `npm install my-library`.
+
+### Dev Dependencies vs. Build Dependencies
+
+Keep the dev environment fast by understanding what belongs where:
+
+**devDependencies** (not published):
+```json
+{
+  "devDependencies": {
+    "typescript": "^5.4.0",       // Build tool
+    "tsup": "^8.0.0",             // Bundler
+    "vitest": "^1.4.0",           // Test runner
+    "tsd": "^0.31.0",             // Type testing
+    "typedoc": "^0.25.0",         // Doc generation
+    "eslint": "^8.57.0",          // Linter
+    "prettier": "^3.2.0",         // Formatter
+    "concurrently": "^8.2.0",     // Parallel scripts
+    "rimraf": "^5.0.0"            // Cross-platform rm -rf
+  }
+}
+```
+
+**dependencies** (installed by consumers):
+Only runtime dependencies that the library code imports at runtime. Keep this list minimal. Every dependency you add becomes a consumer's dependency. Prefer zero runtime dependencies for utility libraries.
+
+**peerDependencies**:
+Framework dependencies the consumer is expected to provide (React, Vue, etc.).
+
+### Environment Variables for Dev
+
+Libraries should not read environment variables at runtime (that's the consumer's responsibility). But the build process may need them:
+
+```bash
+# .env.local (gitignored) — only for build/test scripts
+NPM_REGISTRY=https://registry.npmjs.org
+TYPEDOC_TOKEN=...  # for doc deployment
+```
+
+Document any required environment variables in `docs/dev-setup.md`. Never hardcode registry URLs or tokens.
+
+### Recommended package.json Dev Scripts
+
+```json
+{
+  "scripts": {
+    "build": "rimraf dist && tsup",
+    "build:watch": "tsup --watch",
+    "dev": "npm run build:watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:types": "tsd",
+    "test:coverage": "vitest run --coverage",
+    "test:examples": "node examples/basic-usage/index.js",
+    "lint": "eslint src/ tests/",
+    "format": "prettier --write src/ tests/",
+    "typecheck": "tsc --noEmit -p tsconfig.dev.json",
+    "docs": "typedoc",
+    "pack:dry": "npm pack --dry-run",
+    "prepublishOnly": "npm run build && npm run test && npm run test:types",
+    "clean": "rimraf dist"
+  }
+}
+```
+
+The `prepublishOnly` script is a safety net — it runs automatically before `npm publish` and blocks publishing if tests fail.