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

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