104 lines
5.5 KiB
Markdown
104 lines
5.5 KiB
Markdown
# 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/`.
|