@zigrivers/scaffold 3.6.0 → 3.8.0

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

@@ -0,0 +1,300 @@
+---
+name: library-documentation
+description: TypeDoc/JSDoc setup, README structure, example code, migration guides, and API reference for published libraries
+topics: [library, documentation, typedoc, jsdoc, readme, examples, migration-guides, api-reference]
+---
+
+Library documentation is the primary onboarding surface for new consumers and the support surface for existing ones. Poor documentation causes consumers to misuse the API, open avoidable issues, and ultimately abandon the library for better-documented alternatives. Good documentation reduces support burden, increases adoption, and communicates the library's quality and professionalism. Documentation must be treated as a first-class deliverable, not an afterthought after code is complete.
+
+## Summary
+
+Every library needs four documentation layers: a README for discovery and quick start, API reference generated from JSDoc (TypeDoc), example code that is runnable and tested, and migration guides for each major version. The README structure follows a standard pattern: badges, one-line description, install, quick start, core concepts, API overview with links to full reference, and contributing. JSDoc comments are the source of truth for the API reference — they must be maintained alongside code.
+
+Documentation layers:
+- README.md: discovery, install, quick start (< 5 minutes to first working code)
+- JSDoc inline: function descriptions, parameter docs, examples, throws
+- TypeDoc site: full API reference with types, overloads, inheritance
+- examples/: runnable, tested example projects per major use case
+- Migration guides: step-by-step for every major version bump
+
+## Deep Guidance
+
+### README Structure
+
+The README must answer four questions in order: What is it? How do I install it? How do I use it? Where do I learn more?
+
+```markdown
+# my-library
+
+[![npm](https://img.shields.io/npm/v/my-library)](https://npmjs.com/package/my-library)
+[![CI](https://github.com/org/my-library/actions/workflows/ci.yml/badge.svg)](...)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+One-sentence description of what the library does and the problem it solves.
+
+## Install
+
+\`\`\`bash
+npm install my-library
+\`\`\`
+
+Requires Node.js 18+. TypeScript 5.0+ recommended.
+
+## Quick Start
+
+\`\`\`typescript
+import { parseConfig, createClient } from 'my-library'
+
+const config = parseConfig(`
+  [server]
+  host = "localhost"
+  port = 3000
+`)
+
+const client = createClient({ config })
+const result = await client.query('SELECT 1')
+\`\`\`
+
+## Core Concepts
+
+Brief explanation of the 2-3 key concepts consumers need to understand before using the API:
+- **Config**: The parsed configuration object. Passed to all client methods.
+- **Client**: Stateful connection to a service. Create once per application.
+- **Query**: An operation executed against the client.
+
+## API Reference
+
+Full API documentation: [https://my-library.dev/api](https://my-library.dev/api)
+
+Key exports:
+| Export | Description |
+|--------|-------------|
+| `parseConfig(input)` | Parse a TOML string into a Config object |
+| `createClient(options)` | Create a connected Client instance |
+| `ParseError` | Thrown when input is not valid TOML |
+
+## Examples
+
+See [examples/](examples/) for runnable examples:
+- [Basic usage](examples/basic-usage/) — Parse a config and run a query
+- [Custom transport](examples/custom-transport/) — Inject a custom HTTP transport
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT
+```
+
+**README anti-patterns to avoid:**
+- Feature lists without usage examples
+- Installation section that assumes npm — show the command explicitly
+- API "documentation" that only lists function names without signatures
+- No error handling in examples (shows only the happy path)
+- Out-of-date examples (the most common and damaging README failure)
+
+### JSDoc Standards
+
+JSDoc comments are compiled into the generated API reference. Write them for the consumer who has never read the source:
+
+```typescript
+/**
+ * Parse a TOML-formatted configuration string.
+ *
+ * Parses `input` as TOML and validates the result against the expected Config
+ * schema. Returns a fully typed Config object on success.
+ *
+ * @param input - TOML-formatted string. Must be valid TOML 1.0.
+ * @param options - Optional parsing configuration.
+ * @param options.strict - When true, unknown fields cause a ValidationError.
+ *   Defaults to false (unknown fields are ignored).
+ * @param options.encoding - Character encoding. Defaults to 'utf-8'.
+ *
+ * @returns Parsed Config object with all fields typed.
+ *
+ * @throws {ParseError} If `input` is not valid TOML. The error includes
+ *   `line` and `column` properties indicating the error location.
+ * @throws {ValidationError} If `options.strict` is true and the parsed config
+ *   contains unknown fields.
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const config = parseConfig('[server]\nhost = "localhost"')
+ * console.log(config.server.host) // "localhost"
+ * ```
+ *
+ * @example
+ * With strict mode:
+ * ```typescript
+ * try {
+ *   const config = parseConfig(input, { strict: true })
+ * } catch (err) {
+ *   if (err instanceof ValidationError) {
+ *     console.error('Unknown fields:', err.unknownFields)
+ *   }
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function parseConfig(input: string, options?: ParseOptions): Config
+```
+
+**Minimum JSDoc for every public export:**
+- One-sentence description (what it does, not how)
+- `@param` for each parameter with type context and constraints
+- `@returns` describing the return value
+- `@throws` for every error type that can be thrown
+- At least one `@example` showing realistic usage
+- `@since` for when the export was added (helps with migration)
+- `@deprecated` with replacement and removal version when applicable
+
+### TypeDoc Setup
+
+TypeDoc generates HTML API reference from JSDoc comments:
+
+```bash
+npm install --save-dev typedoc typedoc-plugin-markdown
+```
+
+```json
+// typedoc.json
+{
+  "entryPoints": ["src/index.ts"],
+  "out": "docs/api",
+  "plugin": ["typedoc-plugin-markdown"],
+  "readme": "none",
+  "excludePrivate": true,
+  "excludeInternal": true,
+  "categorizeByGroup": true,
+  "categoryOrder": ["Core", "Types", "Errors", "*"],
+  "gitRemote": "origin",
+  "githubPages": true
+}
+```
+
+```bash
+# Generate docs
+npm run docs
+# Or: npx typedoc
+
+# Deploy to GitHub Pages (in CI)
+# Add to your GitHub Actions workflow:
+- uses: actions/upload-pages-artifact@v3
+  with:
+    path: docs/api
+```
+
+Run TypeDoc in CI to catch documentation failures (missing exports, broken references) before they reach consumers.
+
+### Example Code Standards
+
+Examples are documentation that can be run and tested. They must:
+
+1. **Be complete and runnable:**
+```typescript
+// examples/basic-usage/index.ts
+// This file runs standalone: `node index.js`
+import { parseConfig, createClient } from 'my-library'
+
+const raw = `
+[server]
+host = "localhost"
+port = 3000
+`
+
+const config = parseConfig(raw)
+const client = createClient({ config })
+
+async function main() {
+  const result = await client.query('SELECT 1')
+  console.log('Connected:', result)
+  await client.close()
+}
+
+main().catch((err) => {
+  console.error('Example failed:', err)
+  process.exit(1)
+})
+```
+
+2. **Show error handling:**
+```typescript
+// Don't just show the happy path
+try {
+  const config = parseConfig(invalidInput)
+} catch (err) {
+  if (err instanceof ParseError) {
+    console.error(`Syntax error at line ${err.line}, column ${err.column}`)
+    console.error(err.message)
+  }
+}
+```
+
+3. **Be tested in CI:**
+```yaml
+# .github/workflows/ci.yml
+- name: Test examples
+  run: |
+    cd examples/basic-usage && npm install && node index.js
+    cd examples/custom-transport && npm install && node index.js
+```
+
+### Migration Guides
+
+Every major version must have a migration guide. The guide must be findable from the CHANGELOG and README:
+
+```markdown
+<!-- docs/guides/migration-v2-to-v3.md -->
+# Migrating from v2 to v3
+
+## Breaking Changes
+
+### `parse()` removed
+`parse()` was deprecated in v2.3. Replace with `parseConfig()`:
+
+**Before (v2):**
+\`\`\`typescript
+import { parse } from 'my-library'
+const config = parse(input)
+\`\`\`
+
+**After (v3):**
+\`\`\`typescript
+import { parseConfig } from 'my-library'
+const config = parseConfig(input)
+\`\`\`
+
+### `Config.timeout` is now milliseconds
+The `timeout` field was previously in seconds. Multiply by 1000:
+
+**Before (v2):**
+\`\`\`typescript
+const config = parseConfig(input)
+// config.timeout === 30 (seconds)
+\`\`\`
+
+**After (v3):**
+\`\`\`typescript
+const config = parseConfig(input)
+// config.timeout === 30000 (milliseconds)
+// Adjust your code: config.timeout * 1000 is no longer needed
+\`\`\`
+
+## Automated Migration
+
+A codemod is available to automate common patterns:
+\`\`\`bash
+npx @my-library/codemod v2-to-v3 ./src
+\`\`\`
+```
+
+**Migration guide checklist:**
+- Every breaking change has a before/after code example
+- Every renamed export has an explicit replacement
+- Behavior changes are explained, not just listed
+- A codemod is provided for mechanical changes (optional but appreciated)
+- Link to the migration guide from the CHANGELOG entry

package/content/knowledge/library/library-project-structure.md

@@ -0,0 +1,237 @@
+---
+name: library-project-structure
+description: Directory layout, package.json exports map, tsconfig for declarations, and examples/ structure for published libraries
+topics: [library, project-structure, package-json, tsconfig, exports, declarations]
+---
+
+Library project structure must serve two audiences simultaneously: contributors who need to navigate and modify the source, and consumers who install the package and expect predictable module resolution. The structure of the source directory, the `dist/` output, the `package.json` exports map, and the TypeScript configuration all interlock. Getting any one of them wrong produces libraries that fail to tree-shake, ship broken types, or cause dual-package hazards.
+
+## Summary
+
+A well-structured library has `src/` for source, `dist/` for built output (gitignored), `examples/` for runnable consumer examples, and `docs/` for API reference. The `package.json` exports map is the definitive module resolution contract. The TypeScript configuration must emit declaration files alongside compiled output. Internal implementation details live under `src/internal/` and are never exported from the root index.
+
+Standard layout:
+- `src/index.ts` — public API barrel (explicit named exports only)
+- `src/internal/` — implementation details, never publicly exported
+- `src/types.ts` — shared type definitions
+- `examples/` — standalone runnable examples (one per major use case)
+- `dist/` — build output (gitignored, published to npm)
+- `docs/` — generated API reference and hand-written guides
+
+## Deep Guidance
+
+### Source Directory Layout
+
+```
+my-library/
+├── src/
+│   ├── index.ts              # Public API — only named exports here
+│   ├── types.ts              # Shared types/interfaces used across modules
+│   ├── errors.ts             # All custom error classes
+│   ├── parser.ts             # Feature module
+│   ├── validator.ts          # Feature module
+│   ├── client.ts             # Feature module
+│   └── internal/             # Implementation details — NEVER export from root
+│       ├── utils.ts
+│       ├── cache.ts
+│       └── http.ts
+├── examples/
+│   ├── basic-usage/
+│   │   ├── index.ts          # Standalone example, uses installed package
+│   │   └── package.json      # Depends on "my-library": "file:../../"
+│   └── advanced-plugin/
+│       ├── index.ts
+│       └── package.json
+├── tests/
+│   ├── unit/                 # Unit tests mirroring src/ structure
+│   ├── integration/          # Consumer-perspective integration tests
+│   └── types/                # Type-level tests (tsd or expect-type)
+├── docs/
+│   ├── api/                  # Generated by TypeDoc
+│   └── guides/               # Hand-written usage guides
+├── dist/                     # Build output (gitignored)
+├── package.json
+├── tsconfig.json             # Build config (emits to dist/)
+├── tsconfig.dev.json         # Dev/test config (no emit)
+├── CHANGELOG.md
+└── README.md
+```
+
+### package.json Structure
+
+The full `package.json` for a dual ESM/CJS library:
+
+```json
+{
+  "name": "my-library",
+  "version": "1.0.0",
+  "description": "One-line description",
+  "license": "MIT",
+  "author": "Name <email>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/org/my-library.git"
+  },
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    },
+    "./plugins": {
+      "import": {
+        "types": "./dist/types/plugins/index.d.ts",
+        "default": "./dist/esm/plugins/index.js"
+      },
+      "require": {
+        "types": "./dist/types/plugins/index.d.cts",
+        "default": "./dist/cjs/plugins/index.cjs"
+      }
+    },
+    "./testing": {
+      "import": {
+        "types": "./dist/types/testing/index.d.ts",
+        "default": "./dist/esm/testing/index.js"
+      },
+      "require": {
+        "types": "./dist/types/testing/index.d.cts",
+        "default": "./dist/cjs/testing/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json",
+    "build:watch": "tsc -p tsconfig.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:types": "tsd",
+    "lint": "eslint src/ tests/",
+    "typecheck": "tsc --noEmit",
+    "docs": "typedoc src/index.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.4.0",
+    "tsd": "^0.31.0",
+    "typedoc": "^0.25.0",
+    "eslint": "^8.57.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false
+}
+```
+
+The `"sideEffects": false` field tells bundlers this library is fully tree-shakeable. Only set this if true — if the library registers globals or patches prototypes on import, this must be `true` or an array of files with side effects.
+
+### TypeScript Configuration
+
+Two tsconfig files: one for building (emit), one for development (no emit, strict checking).
+
+**tsconfig.json (build — ESM output):**
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2020"],
+    "outDir": "./dist/esm",
+    "declarationDir": "./dist/types",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "esModuleInterop": false,
+    "skipLibCheck": false
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts", "tests/", "examples/", "dist/"]
+}
+```
+
+**tsconfig.cjs.json (CJS output — extends build config):**
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "outDir": "./dist/cjs",
+    "declaration": false
+  }
+}
+```
+
+**tsconfig.dev.json (development — no emit):**
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "moduleResolution": "Bundler"
+  },
+  "include": ["src", "tests", "examples"]
+}
+```
+
+### Examples Directory
+
+Each example must be a standalone project that installs the library as a dependency:
+
+```json
+// examples/basic-usage/package.json
+{
+  "name": "basic-usage-example",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "my-library": "file:../../"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "build": "tsc"
+  }
+}
+```
+
+This ensures examples test the actual published API surface, not the source. If an example breaks, the public API is broken. Run examples in CI.
+
+### .npmignore and `files` Field
+
+Use the `files` field in `package.json` to allowlist what gets published. This is safer than `.npmignore` (which is a denylist and can accidentally publish source, tests, or secrets):
+
+```json
+"files": [
+  "dist/",
+  "README.md",
+  "CHANGELOG.md",
+  "LICENSE"
+]
+```
+
+Explicitly excluded from publish: `src/`, `tests/`, `examples/`, `docs/`, `.github/`, `tsconfig*.json`, `*.config.*`. Consumers never need source files — they use the compiled dist output and type declarations.