Initial Commit

openspec/changes/enterprise-api-docs/tasks.md

@@ -0,0 +1,103 @@
+# Tasks: enterprise-api-docs
+
+**Change ID**: enterprise-api-docs
+**Package**: `@suaveplan/api-docs`
+**Target path**: `universal/docs/api-docs`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/logger`, `@suaveplan/serialize`
+
+---
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Scaffold
+
+- [ ] Create `universal/docs/api-docs/` with `src/`, `tests/`, and all feature subdirectories per the layout in `proposal.md`.
+- [ ] Write `package.json` at version `0.1.0`:
+  - `"type": "module"`, `"sideEffects": false`
+  - `exports` map: `"."` barrel + one subpath per feature module
+  - `dependencies`: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/logger workspace:^`, `@suaveplan/serialize workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`
+  - `devDependencies`: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `fast-check catalog:testing`, `@suaveplan/testing workspace:^`
+- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
+- [ ] Write `vitest.config.ts` using `createTestConfig()`.
+- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
+
+---
+
+## 2. Types and error codes
+
+- [ ] Define all public types in `src/types/common.ts`: `DocInput`, `DocOutput`, `PackageDoc`, `SymbolDoc`, `SymbolKind`, `FunctionDoc`, `FunctionSignature`, `ClassDoc`, `InterfaceDoc`, `TypeAliasDoc`, `EnumDoc`, `VariableDoc`, `ParameterDoc`, `PropertyDoc`, `TypeParameterDoc`, `DocGeneratorOptions`, `DocFormatter`.
+- [ ] Write `src/types/common.md` (≥200 words, simple + advanced examples).
+- [ ] Define error codes in `src/error-codes.ts`: `ApiDocsErrorCode` union, metadata, `registerApiDocsErrorCodes()`.
+- [ ] Write Zod schemas in `src/types/schemas.ts` + `src/types/schemas.md`.
+
+---
+
+## 3. Parser (`src/core/parser/`)
+
+- [ ] Implement `parseSource(input: DocInput, signal?: AbortSignal): Promise<PackageDoc[]>`:
+  - Use TypeScript compiler API (`ts.createProgram`) to parse source files.
+  - Extract exported symbols with JSDoc comments.
+  - Map to `SymbolDoc` union based on symbol kind.
+  - Filter by `includePrivate` and `includeInternal` flags.
+  - Guard all `ts.*` imports behind a lazy dynamic import so the package remains tree-shakeable when the compiler API is not needed.
+- [ ] Write `parser.test.ts` (≤500 lines): function parse, class parse, interface parse, type alias, enum, exclude private, exclude `@internal`.
+- [ ] Write `parser.md` (≥200 words).
+
+---
+
+## 4. Formatters (`src/formatters/`)
+
+### 4a. JSON formatter
+
+- [ ] Implement `createJsonFormatter()` — serialises `DocOutput` to indented JSON via `@suaveplan/serialize`.
+- [ ] Write `json-formatter.test.ts` + `json-formatter.md`.
+
+### 4b. Markdown formatter
+
+- [ ] Implement `createMarkdownFormatter()` — generates Markdown with function signatures as code blocks, parameter tables, return type, and description.
+- [ ] Write `markdown-formatter.test.ts` (verify key Markdown patterns in output) + `markdown-formatter.md`.
+
+### 4c. OpenAPI formatter
+
+- [ ] Implement `createOpenApiFormatter()` — generates OpenAPI 3.1 `paths` and `components` objects from exported function signatures with HTTP method JSDoc tags (`@get`, `@post`, `@put`, `@delete`, `@patch`).
+- [ ] Write `openapi-formatter.test.ts` + `openapi-formatter.md`.
+
+---
+
+## 5. Generator (`src/core/generator/`)
+
+- [ ] Implement `createDocGenerator(options?)`:
+  - Validates options with Zod.
+  - Registers built-in formatters (json, markdown, openapi).
+  - Stores custom formatters registered via `use(formatter)`.
+- [ ] Implement `generator.generate(input, signal?)`:
+  - Calls `parseSource(input, signal)`.
+  - Constructs `DocOutput` with `toJSON()`, `toMarkdown()`, `toOpenApi()` delegating to registered formatters.
+  - OTel span `api_docs.generate`, histogram `api_docs.generation_duration_ms`, counter `api_docs.symbols_parsed_total`.
+- [ ] Implement `generator.use(formatter)` — registers custom formatter; returns `this`.
+- [ ] Write `generator.test.ts` (≤500 lines): happy path, custom formatter, abort signal, parse error.
+- [ ] Write `generator.md` (≥200 words).
+
+---
+
+## 6. Docs
+
+- [ ] All per-file `.md` files per layout in `proposal.md`.
+- [ ] `universal/docs/api-docs/README.md`.
+
+---
+
+## 7. Verify and publish
+
+- [ ] `bunx turbo lint --filter=@suaveplan/api-docs` — zero errors.
+- [ ] `bunx turbo typecheck --filter=@suaveplan/api-docs` — zero errors.
+- [ ] `bunx turbo test --filter=@suaveplan/api-docs` — all tests pass.
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/api-docs` — 100% on all touched modules.
+- [ ] `bun run docs:check --filter=@suaveplan/api-docs` — zero errors.
+- [ ] `bun scripts/publish.ts --package @suaveplan/api-docs`.
+- [ ] Update `CLAUDE.md` package listing.
+- [ ] Archive: move `openspec/changes/enterprise-api-docs/` to `openspec/archive/2026-04-24-enterprise-api-docs/`.