@zigrivers/scaffold 3.6.0 → 3.8.0

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

@@ -0,0 +1,319 @@
+---
+name: library-testing
+description: Unit tests, consumer integration tests, example app tests, snapshot testing, and type testing for published libraries
+topics: [library, testing, unit-tests, integration-tests, type-testing, tsd, snapshot-testing, consumer-testing]
+---
+
+Library testing has a different threat model than application testing. You are not just testing that your code works internally — you are testing that the public API works correctly from a consumer's perspective, across different environments and module systems, and that type definitions accurately reflect runtime behavior. A library with excellent unit tests but untested consumer integration can still fail spectacularly when installed in a real project. Every public API export needs test coverage that exercises it as a consumer would.
+
+## Summary
+
+Library testing requires four layers: unit tests for internal logic (fast, isolated), consumer-perspective integration tests (exercise the public API as an external consumer would), example application tests (run the examples from the docs to catch regressions), and type tests (verify TypeScript types are accurate and don't regress). Use vitest for unit and integration tests. Use `tsd` or vitest's `expectTypeOf` for type tests. Run example apps in CI. Aim for 100% coverage of public API exports.
+
+Testing layers:
+- Unit tests: pure functions, internal logic, error conditions
+- Integration tests: public API called without any internal access
+- Type tests: `tsd` or `expect-type` assertions on all public exports
+- Example tests: run examples/ as standalone scripts in CI
+- Cross-environment tests: Node ESM, Node CJS, and bundler environments
+
+## Deep Guidance
+
+### Unit Tests
+
+Unit tests cover individual functions and classes in isolation. Use vitest for its TypeScript support and fast execution:
+
+```typescript
+// tests/unit/parser.test.ts
+import { describe, it, expect } from 'vitest'
+import { parseConfig } from '../../src/parser'
+import { ParseError } from '../../src/errors'
+
+describe('parseConfig', () => {
+  it('parses a valid TOML string', () => {
+    const result = parseConfig('[server]\nhost = "localhost"\nport = 3000')
+    expect(result.server.host).toBe('localhost')
+    expect(result.server.port).toBe(3000)
+  })
+
+  it('throws ParseError on invalid TOML', () => {
+    expect(() => parseConfig('invalid = {toml')).toThrow(ParseError)
+  })
+
+  it('includes line number in ParseError', () => {
+    try {
+      parseConfig('line1 = "ok"\nline2 = {invalid')
+    } catch (err) {
+      expect(err).toBeInstanceOf(ParseError)
+      expect((err as ParseError).line).toBe(2)
+    }
+  })
+
+  it('returns empty config for empty input', () => {
+    const result = parseConfig('')
+    expect(result).toEqual({})
+  })
+
+  it('handles special characters in string values', () => {
+    const result = parseConfig('key = "hello\\nworld"')
+    expect(result.key).toBe('hello\nworld')
+  })
+})
+```
+
+**Unit test coverage targets:**
+- Every exported function: 100% coverage
+- Every error case: tested explicitly
+- Edge cases: empty inputs, null/undefined, very large inputs, special characters
+- Option combinations: test that each option modifies behavior correctly
+
+### Consumer-Perspective Integration Tests
+
+These tests exercise the public API exactly as a consumer would — importing from the package root, never accessing internal modules:
+
+```typescript
+// tests/integration/consumer-api.test.ts
+// Import from the package root, not from src/
+// This tests the actual public API surface
+import { parseConfig, createClient, ParseError, ValidationError } from 'my-library'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+
+// If running in Node, import the dist/ version not the source
+// Configure vitest to resolve 'my-library' to './dist/index.js'
+
+describe('Consumer API', () => {
+  describe('parseConfig()', () => {
+    it('is callable with a single string argument', () => {
+      expect(() => parseConfig('[test]\nvalue = 1')).not.toThrow()
+    })
+
+    it('returns an object with the parsed structure', () => {
+      const config = parseConfig('[db]\nhost = "localhost"')
+      expect(config).toMatchObject({ db: { host: 'localhost' } })
+    })
+
+    it('throws ParseError (a named export) on syntax errors', () => {
+      expect(() => parseConfig('invalid')).toThrow(ParseError)
+    })
+  })
+
+  describe('createClient()', () => {
+    let client: ReturnType<typeof createClient>
+
+    beforeEach(() => {
+      const config = parseConfig('[server]\nhost = "localhost"\nport = 3000')
+      client = createClient({ config })
+    })
+
+    afterEach(async () => {
+      await client.close()
+    })
+
+    it('creates a client with a query method', () => {
+      expect(client.query).toBeTypeOf('function')
+    })
+  })
+})
+```
+
+**Configure vitest to test against dist/ for integration tests:**
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest'
+
+export default defineConfig({
+  test: {
+    // Unit tests use src/ directly
+    // Integration tests use the built dist/
+    include: ['tests/unit/**/*.test.ts'],
+  }
+})
+
+// vitest.integration.config.ts
+export default defineConfig({
+  resolve: {
+    alias: {
+      'my-library': new URL('./dist/index.js', import.meta.url).pathname
+    }
+  },
+  test: {
+    include: ['tests/integration/**/*.test.ts'],
+  }
+})
+```
+
+### Type Tests with tsd
+
+Type tests verify that TypeScript types are accurate and don't regress:
+
+```typescript
+// tests/types/index.test-d.ts
+import { expectType, expectError, expectAssignable, expectNotType } from 'tsd'
+import type { Config, ParseOptions, ParseError as PE } from 'my-library'
+import { parseConfig, createClient, ParseError } from 'my-library'
+
+// Return type tests
+expectType<Config>(parseConfig('[test]\nvalue = 1'))
+
+// Overload resolution
+expectType<Config>(parseConfig('input', { async: false }))
+expectType<Promise<Config>>(parseConfig('input', { async: true }))
+
+// Input type constraints
+expectError(parseConfig(42))
+expectError(parseConfig(null))
+expectError(parseConfig(undefined))
+expectError(parseConfig([]))
+
+// Options shape
+const validOptions: ParseOptions = { strict: true, encoding: 'utf-8' }
+expectAssignable<ParseOptions>(validOptions)
+expectAssignable<ParseOptions>({})  // All options are optional
+
+// Error type hierarchy
+const err = new ParseError('msg', 1, 1)
+expectAssignable<Error>(err)
+expectType<number>(err.line)
+expectType<number>(err.column)
+
+// Discriminated union types
+type ParseResult = ReturnType<typeof parseConfig>
+expectNotType<undefined>(null as ParseResult)  // Result is never null
+```
+
+```json
+// package.json — configure tsd
+{
+  "tsd": {
+    "directory": "tests/types"
+  },
+  "scripts": {
+    "test:types": "tsd"
+  }
+}
+```
+
+### Snapshot Testing for Serialized Output
+
+Snapshot tests catch unintentional changes to formatted output:
+
+```typescript
+// tests/unit/formatter.test.ts
+import { describe, it, expect } from 'vitest'
+import { formatConfig } from '../../src/formatter'
+
+describe('formatConfig', () => {
+  it('formats a config object to TOML', () => {
+    const config = { server: { host: 'localhost', port: 3000 } }
+    expect(formatConfig(config)).toMatchSnapshot()
+  })
+
+  it('formats an array value', () => {
+    const config = { allowed: ['read', 'write'] }
+    expect(formatConfig(config)).toMatchSnapshot()
+  })
+})
+```
+
+Snapshot files are committed to the repository. When intentional output changes are made, update snapshots with `vitest --update-snapshots`. In CI, fail on unexpected snapshot changes.
+
+**When to use snapshots vs. explicit assertions:**
+- Use snapshots for complex serialized output (HTML, TOML, JSON with many fields)
+- Use explicit assertions for simple return values — snapshots hide intent
+- Never snapshot non-deterministic output (timestamps, random IDs)
+
+### Cross-Environment Testing
+
+Libraries must work in both Node ESM and CJS environments:
+
+```typescript
+// tests/env/esm.test.mjs — ES module import test
+import { parseConfig } from 'my-library'
+console.assert(typeof parseConfig === 'function', 'ESM import works')
+console.log('ESM: OK')
+
+// tests/env/cjs.test.cjs — CommonJS require test
+const { parseConfig } = require('my-library')
+console.assert(typeof parseConfig === 'function', 'CJS require works')
+console.log('CJS: OK')
+```
+
+```yaml
+# .github/workflows/ci.yml
+- name: Test CJS compatibility
+  run: node tests/env/cjs.test.cjs
+
+- name: Test ESM compatibility
+  run: node tests/env/esm.test.mjs
+
+- name: Test with latest Node
+  run: npm test
+  env:
+    NODE_VERSION: 22
+
+- name: Test with minimum Node
+  run: npm test
+  env:
+    NODE_VERSION: 18
+```
+
+### Example Application Tests
+
+Run examples in CI to catch regressions in the documented usage:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Build library
+  run: npm run build
+
+- name: Test basic-usage example
+  run: |
+    cd examples/basic-usage
+    npm install
+    node index.js
+  # Fails if the example throws an error or exits non-zero
+
+- name: Test advanced example
+  run: |
+    cd examples/advanced-plugin
+    npm install
+    node index.js
+```
+
+Each example's `package.json` references `"my-library": "file:../../"` so it uses the locally built dist/, not a published version:
+
+```json
+{
+  "dependencies": {
+    "my-library": "file:../../"
+  }
+}
+```
+
+If an example breaks, the public API has regressed. Fix the library, not the example.
+
+### Test Coverage Configuration
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest'
+
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: 'v8',
+      include: ['src/**/*.ts'],
+      exclude: ['src/internal/**', 'src/**/*.test.ts'],
+      thresholds: {
+        functions: 100,    // Every exported function must be tested
+        branches: 90,      // 90% branch coverage
+        lines: 95,
+        statements: 95
+      },
+      reporter: ['text', 'lcov', 'html']
+    }
+  }
+})
+```
+
+A 100% function coverage target is achievable for libraries and enforces that every public export has at least one test. Combined with type tests (which test every function's type signature), this gives comprehensive coverage of the public API contract.

package/content/knowledge/library/library-type-definitions.md

@@ -0,0 +1,284 @@
+---
+name: library-type-definitions
+description: Declaration files (.d.ts), type testing with tsd/expect-type, conditional types, and API surface documentation via types
+topics: [library, typescript, type-definitions, declarations, tsd, expect-type, conditional-types, dts]
+---
+
+Type definitions are a first-class deliverable for TypeScript libraries. They are part of the public API contract, not an afterthought. Declaration files (`.d.ts`) must be accurate, complete, and expressive — they determine whether consumers can use the library with type safety, whether IDEs provide useful completions, and whether type errors are caught at compile time rather than runtime. Inaccurate types are worse than no types because they create false confidence.
+
+## Summary
+
+Emit declaration files alongside compiled JavaScript using TypeScript's `declaration: true` compiler option or a bundler like tsup. Test types with `tsd` or `expect-type` to catch type regressions. Use conditional types to express relationships between input and output types. Export all types that appear in public API signatures — unexported types force consumers to use `any` or `ReturnType<typeof fn>` workarounds. Document type parameters with JSDoc. Include declaration maps (`declarationMap: true`) so Go-to-Definition works across the source.
+
+Core type definition practices:
+- Enable `declaration` and `declarationMap` in tsconfig build config
+- Export every type that appears in any public API signature
+- Write type tests with `tsd` or `expect-type` as part of the test suite
+- Use conditional types to narrow return types based on input types
+- Avoid `any` in public signatures — use `unknown` for unvalidated input
+
+## Deep Guidance
+
+### TypeScript Configuration for Declaration Emission
+
+The build tsconfig must enable declaration emission:
+
+```json
+{
+  "compilerOptions": {
+    "declaration": true,      // Emit .d.ts files
+    "declarationMap": true,   // Emit .d.ts.map for Go-to-Definition
+    "declarationDir": "./dist/types",  // Put declarations in dist/types/
+    "emitDeclarationOnly": false,      // Emit JS too (or use separate tsc runs)
+    "stripInternal": true,    // Remove @internal JSDoc items from declarations
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+With tsup:
+```typescript
+export default defineConfig({
+  entry: ['src/index.ts'],
+  dts: true,  // tsup generates declarations using tsc under the hood
+})
+```
+
+### What to Export
+
+Every type that appears in a public API signature must be exported:
+
+```typescript
+// src/index.ts — export all types consumers will need
+
+// Types used in function signatures
+export type { ParseOptions, ParseResult } from './parser'
+export type { ValidationResult, ValidationError, ValidationRule } from './validator'
+export type { ClientOptions, Client, RequestOptions, Response } from './client'
+
+// Error classes (constructors are values AND types)
+export { ParseError, ValidationError, NetworkError } from './errors'
+
+// Enums or const objects used as parameter values
+export { LogLevel, OutputFormat } from './constants'
+
+// Utility types consumers may want to use
+export type { DeepPartial, Awaited } from './utils'
+```
+
+**What NOT to export:**
+- Internal implementation types (`InternalCacheEntry`, `HttpClientConfig`)
+- Types used only within the library's own internals
+- Types from `src/internal/` modules
+
+Mark internal types with `@internal` JSDoc to exclude them from declaration files when `stripInternal: true` is set:
+
+```typescript
+/** @internal */
+export interface InternalCacheEntry {
+  value: unknown
+  expiresAt: number
+}
+```
+
+### Type Testing with tsd
+
+`tsd` lets you write assertions about types as test files. These catch type regressions — when a refactor accidentally changes the type of a public API:
+
+```typescript
+// tests/types/index.test-d.ts
+import { expectType, expectError, expectAssignable } from 'tsd'
+import { parseConfig, ParseOptions, ParseError, Config } from 'my-library'
+
+// Assert parseConfig returns Config
+expectType<Config>(parseConfig('input'))
+
+// Assert ParseOptions is accepted
+const options: ParseOptions = { strict: true }
+expectAssignable<ParseOptions>(options)
+
+// Assert ParseError has the right shape
+const err = new ParseError('message', 1, 1)
+expectType<number>(err.line)
+expectType<number>(err.column)
+
+// Assert that invalid input types cause a type error
+expectError(parseConfig(42))
+expectError(parseConfig(null))
+
+// Assert overload resolution
+expectType<Config>(parseConfig('input'))
+expectType<Promise<Config>>(parseConfig('input', { async: true }))
+```
+
+Run type tests as part of CI:
+```bash
+# package.json
+"test:types": "tsd"
+"test": "vitest run && tsd"
+```
+
+`tsd` will fail the test suite if any `expectType` assertion fails (wrong type) or any `expectError` assertion fails (expected error didn't occur).
+
+### Using expect-type (Alternative to tsd)
+
+`expect-type` works inline with your test runner (vitest, jest):
+
+```typescript
+// tests/types/parser.test.ts
+import { expectTypeOf } from 'vitest'
+import { parseConfig } from 'my-library'
+
+test('parseConfig return type', () => {
+  expectTypeOf(parseConfig).toBeFunction()
+  expectTypeOf(parseConfig).parameter(0).toBeString()
+  expectTypeOf(parseConfig).returns.toEqualTypeOf<Config>()
+})
+
+test('ParseOptions is a valid options object', () => {
+  expectTypeOf<ParseOptions>().toHaveProperty('strict')
+  expectTypeOf<ParseOptions['strict']>().toEqualTypeOf<boolean | undefined>()
+})
+```
+
+The advantage of `expect-type` within vitest: type tests live alongside runtime tests and run in the same test command. The advantage of `tsd`: it's a dedicated type testing tool with more ergonomic syntax for complex assertions.
+
+### Conditional Types for Precise Return Types
+
+Conditional types allow the return type to depend on the input type:
+
+```typescript
+// Return type narrows based on whether async option is set
+function parseConfig(input: string, options?: { async?: false }): Config
+function parseConfig(input: string, options: { async: true }): Promise<Config>
+function parseConfig(input: string, options?: { async?: boolean }): Config | Promise<Config>
+
+// Generic conditional type
+type ParseResult<T extends ParseOptions> =
+  T extends { async: true } ? Promise<Config> : Config
+
+// Deep conditional: extract value type from Result
+type Unwrap<T> = T extends Promise<infer U> ? U : T
+```
+
+**Practical conditional type patterns:**
+
+```typescript
+// Input determines output type
+function transform<T extends string | Buffer>(
+  input: T
+): T extends string ? string : Buffer
+
+// Stricter types in strict mode
+interface ParseOptions {
+  strict?: boolean
+}
+
+type ParseReturn<T extends ParseOptions> =
+  T extends { strict: true } ? StrictConfig : Config
+
+// Utility: make deeply optional
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K]
+}
+```
+
+Use conditional types when the return type genuinely depends on the input. Don't overuse them — complex conditional types are hard to debug and can produce confusing error messages.
+
+### Declaration Maps
+
+Declaration maps (`.d.ts.map`) enable Go-to-Definition in IDEs to jump to the TypeScript source rather than the compiled declaration file. This dramatically improves the experience of debugging library code:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "declarationMap": true  // Emits .d.ts.map alongside .d.ts
+  }
+}
+```
+
+Include the source maps in the published package:
+```json
+// package.json
+{
+  "files": [
+    "dist/",   // includes .d.ts.map files
+    "src/",    // include source for source map resolution
+    "README.md"
+  ]
+}
+```
+
+Including `src/` in the published package allows IDEs to resolve the original TypeScript source through the declaration map.
+
+### Template Literal Types for String APIs
+
+When a library accepts string patterns, template literal types provide exact-match checking:
+
+```typescript
+// HTTP method type
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'
+
+// Route parameter extraction
+type ExtractParams<Route extends string> =
+  Route extends `${string}:${infer Param}/${infer Rest}`
+    ? Param | ExtractParams<`/${Rest}`>
+    : Route extends `${string}:${infer Param}`
+      ? Param
+      : never
+
+// Usage:
+type Params = ExtractParams<'/users/:userId/posts/:postId'>
+// Type: "userId" | "postId"
+
+function route<R extends string>(
+  path: R,
+  handler: (params: Record<ExtractParams<R>, string>) => void
+): void
+```
+
+Template literal types are powerful for configuration DSLs and string-based APIs. Use them when the consumer's strings have a predictable structure that TypeScript can validate.
+
+### JSDoc for Type Documentation
+
+TypeDoc and IDE hover text both read JSDoc comments from type declarations:
+
+```typescript
+/**
+ * Options for controlling the parsing behavior.
+ *
+ * @example
+ * ```typescript
+ * const config = parseConfig(input, {
+ *   strict: true,
+ *   encoding: 'utf-8'
+ * })
+ * ```
+ */
+export interface ParseOptions {
+  /**
+   * Enable strict mode validation.
+   * In strict mode, unknown fields cause a ValidationError.
+   * @default false
+   */
+  strict?: boolean
+
+  /**
+   * File encoding for file-based parsing.
+   * @default 'utf-8'
+   */
+  encoding?: BufferEncoding
+
+  /**
+   * Maximum input size in bytes.
+   * Inputs larger than this limit throw a ParseError.
+   * @default 1_048_576 (1 MB)
+   */
+  maxSize?: number
+}
+```
+
+JSDoc on interfaces and their properties generates rich documentation and appears in IDE hover. Always document: the purpose, any constraints, and the default value.