@zigrivers/scaffold 3.6.0 → 3.8.0

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.