# 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/`.