Initial Commit
This commit is contained in:
236
openspec/changes/enterprise-api-docs/proposal.md
Normal file
236
openspec/changes/enterprise-api-docs/proposal.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# OpenSpec Change: enterprise-api-docs
|
||||
|
||||
- **Change ID**: enterprise-api-docs
|
||||
- **Package**: `@suaveplan/api-docs`
|
||||
- **Category**: universal/docs
|
||||
- **Target path**: `universal/docs/api-docs`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-docs.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/api-docs` on the genesis branch from scratch at enterprise quality. The package provides an API documentation generator: parse TypeDoc-annotated TypeScript source, extract public API surfaces (functions, classes, interfaces, type aliases, enumerations), generate structured documentation as JSON/Markdown/HTML, and emit OpenAPI 3.1 schemas from function signatures. Genesis adds structured errors via `@suaveplan/error`, Zod schemas for all doc types, OTel instrumentation on generation operations, `AbortSignal` on async generation, injectable `Clock` for build timestamps, and a plugin interface for custom output formatters.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
The package does not exist on genesis yet — this is a fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | Base class for `ApiDocsError`; stable error codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock` injectable interfaces |
|
||||
| `@suaveplan/logger` (`workspace:^`) | Structured logging with OTel trace correlation |
|
||||
| `@suaveplan/serialize` (`workspace:^`) | Structured serialization for doc export |
|
||||
| `zod` (`catalog:forms`) | Zod schemas for all public doc types |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters on doc generation |
|
||||
| `tslib` (`catalog:build`) | Runtime helpers |
|
||||
|
||||
Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check` (all `catalog:testing`).
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
### Core
|
||||
|
||||
```ts
|
||||
function createDocGenerator(options?: DocGeneratorOptions): DocGenerator
|
||||
|
||||
interface DocGenerator {
|
||||
generate(input: DocInput, signal?: AbortSignal): Promise<DocOutput>
|
||||
use(formatter: DocFormatter): this
|
||||
}
|
||||
```
|
||||
|
||||
### Input/output types
|
||||
|
||||
```ts
|
||||
interface DocInput {
|
||||
source: string | string[] // file paths or glob patterns
|
||||
entryPoints?: string[]
|
||||
tsconfig?: string
|
||||
includePrivate?: boolean
|
||||
includeInternal?: boolean
|
||||
}
|
||||
|
||||
interface DocOutput {
|
||||
readonly packages: ReadonlyArray<PackageDoc>
|
||||
readonly generatedAt: number
|
||||
toJSON(): string
|
||||
toMarkdown(): string
|
||||
toOpenApi(): OpenApiSchema
|
||||
}
|
||||
|
||||
interface PackageDoc {
|
||||
readonly name: string
|
||||
readonly version?: string
|
||||
readonly description?: string
|
||||
readonly symbols: ReadonlyArray<SymbolDoc>
|
||||
}
|
||||
|
||||
type SymbolDoc =
|
||||
| FunctionDoc
|
||||
| ClassDoc
|
||||
| InterfaceDoc
|
||||
| TypeAliasDoc
|
||||
| EnumDoc
|
||||
| VariableDoc
|
||||
|
||||
interface BaseSymbol {
|
||||
name: string
|
||||
kind: SymbolKind
|
||||
description?: string
|
||||
remarks?: string
|
||||
examples?: string[]
|
||||
deprecated?: string
|
||||
since?: string
|
||||
tags?: Record<string, string>
|
||||
sourceFile?: string
|
||||
sourceLine?: number
|
||||
}
|
||||
|
||||
type SymbolKind = 'function' | 'class' | 'interface' | 'typeAlias' | 'enum' | 'variable'
|
||||
|
||||
interface FunctionDoc extends BaseSymbol {
|
||||
kind: 'function'
|
||||
signatures: ReadonlyArray<FunctionSignature>
|
||||
}
|
||||
|
||||
interface FunctionSignature {
|
||||
parameters: ReadonlyArray<ParameterDoc>
|
||||
returnType: string
|
||||
typeParameters?: ReadonlyArray<TypeParameterDoc>
|
||||
overload?: number
|
||||
}
|
||||
|
||||
interface ClassDoc extends BaseSymbol {
|
||||
kind: 'class'
|
||||
constructors: ReadonlyArray<FunctionSignature>
|
||||
properties: ReadonlyArray<PropertyDoc>
|
||||
methods: ReadonlyArray<FunctionDoc>
|
||||
extends?: string
|
||||
implements?: string[]
|
||||
}
|
||||
|
||||
interface InterfaceDoc extends BaseSymbol {
|
||||
kind: 'interface'
|
||||
properties: ReadonlyArray<PropertyDoc>
|
||||
methods: ReadonlyArray<FunctionDoc>
|
||||
extends?: string[]
|
||||
}
|
||||
```
|
||||
|
||||
### Plugin interface
|
||||
|
||||
```ts
|
||||
interface DocFormatter {
|
||||
readonly name: string
|
||||
readonly format: 'json' | 'markdown' | 'html' | 'openapi' | string
|
||||
format(output: DocOutput): string | Promise<string>
|
||||
}
|
||||
|
||||
function defineFormatter(formatter: DocFormatter): DocFormatter
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```ts
|
||||
interface DocGeneratorOptions {
|
||||
logger?: LoggerLike
|
||||
clock?: Clock
|
||||
outputFormat?: 'json' | 'markdown' | 'html' | 'openapi'
|
||||
excludePatterns?: string[]
|
||||
includePatterns?: string[]
|
||||
}
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type ApiDocsErrorCode =
|
||||
| 'API_DOCS_SOURCE_NOT_FOUND'
|
||||
| 'API_DOCS_PARSE_FAILED'
|
||||
| 'API_DOCS_GENERATE_FAILED'
|
||||
| 'API_DOCS_FORMATTER_NOT_FOUND'
|
||||
| 'API_DOCS_INVALID_INPUT'
|
||||
|
||||
function registerApiDocsErrorCodes(): void
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Genesis additions
|
||||
|
||||
1. **Structured `ApiDocsError`** extending `SuaveplanError` with stable `API_DOCS.*` codes
|
||||
2. **Zod schemas** for `DocInput`, `DocGeneratorOptions`, `PackageDoc`
|
||||
3. **Plugin formatter interface** — `use()` on `DocGenerator`; JSON, Markdown, and OpenAPI formatters built-in
|
||||
4. **`AbortSignal` on `generate()`**
|
||||
5. **Injectable `Clock`** for `generatedAt` timestamps
|
||||
6. **OTel instrumentation** — span `api_docs.generate`, histogram `api_docs.generation_duration_ms`, counter `api_docs.symbols_parsed_total`
|
||||
7. **OpenAPI 3.1 emission** from function signatures
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
universal/docs/api-docs/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
common.ts
|
||||
common.md
|
||||
core/
|
||||
generator/
|
||||
generator.ts
|
||||
generator.md
|
||||
generator.types.ts
|
||||
generator.test.ts
|
||||
index.ts
|
||||
parser/
|
||||
parser.ts
|
||||
parser.md
|
||||
parser.test.ts
|
||||
index.ts
|
||||
formatters/
|
||||
json-formatter/
|
||||
json-formatter.ts
|
||||
json-formatter.md
|
||||
json-formatter.test.ts
|
||||
index.ts
|
||||
markdown-formatter/
|
||||
markdown-formatter.ts
|
||||
markdown-formatter.md
|
||||
markdown-formatter.test.ts
|
||||
index.ts
|
||||
openapi-formatter/
|
||||
openapi-formatter.ts
|
||||
openapi-formatter.md
|
||||
openapi-formatter.test.ts
|
||||
index.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream packages**: `@suaveplan/docs` may depend on this for documentation site generation.
|
||||
|
||||
**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/logger`, `@suaveplan/serialize` must be published.
|
||||
103
openspec/changes/enterprise-api-docs/tasks.md
Normal file
103
openspec/changes/enterprise-api-docs/tasks.md
Normal file
@@ -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/`.
|
||||
Reference in New Issue
Block a user