49 lines
3.2 KiB
Markdown
49 lines
3.2 KiB
Markdown
# Tasks — add-api-openapi
|
|
|
|
## 1. Scaffold
|
|
|
|
- [ ] 1.1 Create `packages/api/api-openapi/` with `src/{registry,route-factory,schema-registry,merger,plugin-integration,error-codes,types}/` + `tests/setup/`
|
|
- [ ] 1.2 `package.json` v0.1.0. Deps: `@suaveplan/error` `@suaveplan/api-plugin` `@suaveplan/api-schemas` `@suaveplan/types` `tslib`, `hono` `@hono/zod-openapi` (`catalog:server`), `zod` (`catalog:forms`), `@opentelemetry/api`. Dev: standard testing. ~8 subpath exports.
|
|
- [ ] 1.3 tsconfigs + vite + vitest (100/100/100/100) + polyfills
|
|
|
|
## 2. Implementation
|
|
|
|
- [ ] 2.1 `src/error-codes.ts` + `.md` + test — 3 OPENAPI.* codes + `OpenAPIError`
|
|
- [ ] 2.2 `src/types/openapi.{ts,md,index.ts}` — `OpenAPIDocument`, `PathItem`, `Operation`, `OpenAPIInfo`, `OpenAPIServer`, `SecurityScheme`, `RegisteredRoute`
|
|
- [ ] 2.3 `src/registry/registry.{ts,test.ts,md,index.ts}` — `OpenAPIRegistry` + `buildDocument()` + `applyTo(app)`
|
|
- [ ] 2.4 `src/route-factory/route-factory.{ts,test.ts,md,index.ts}` — `RouteBuilder<TParams,TQuery,TBody,TResponse>` + `route/GET/POST/PUT/PATCH/DELETE` + `StandardResponses` (widened) + `ErrorResponseSchema` (+ `successResponse/paginatedResponse/errorResponse`)
|
|
- [ ] 2.5 `src/route-factory/route-factory.spec-conformance.test.ts` — `expectTypeOf` end-to-end inference
|
|
- [ ] 2.6 `src/schema-registry/schema-registry.{ts,test.ts,md,index.ts}` — instance-based, no global; extend/partial/pick/omit on ZodObject
|
|
- [ ] 2.7 `src/schema-registry/common-schemas.{ts,md}` — `CommonSchemas` (uuid/email/url/datetime/positiveInt/nonNegativeInt/page/limit/sortOrder)
|
|
- [ ] 2.8 `src/merger/merger.{ts,test.ts,md,index.ts}` — `mergeOpenAPIDocuments`, `prefixPaths`, `filterPathsByTag`, `removeInternalRoutes`
|
|
- [ ] 2.9 `src/plugin-integration/plugin-integration.{ts,test.ts,md,index.ts}` — `definePluginRoutes(routes, {app, registry, pluginName})`
|
|
- [ ] 2.10 `src/index.ts` — named re-exports (incl. `BearerAuthScheme`, `ApiKeyScheme`)
|
|
|
|
## 3. Tests
|
|
|
|
- [ ] 3.1 Co-located `*.test.ts` per spec scenario
|
|
- [ ] 3.2 `src/api-openapi.spec-conformance.test.ts` — every OPENAPI.* thrown; no global singleton; `expectTypeOf` on RouteBuilder end-to-end
|
|
- [ ] 3.3 `tests/integration/full-doc-roundtrip.test.ts` — real OpenAPIHono + real registry + 3 plugins registering routes → assert merged doc shape
|
|
- [ ] 3.4 `tests/property.test.ts` — fast-check `mergeOpenAPIDocuments` associativity (`merge(a, b, c) === merge(merge(a, b), c)`) for arbitrary path sets
|
|
- [ ] 3.5 `tests/dep-graph.test.ts`
|
|
- [ ] 3.6 Runner imports + timeouts conventions
|
|
|
|
## 4. Documentation
|
|
|
|
- [ ] 4.1 Sibling `.md` per impl
|
|
- [ ] 4.2 `README.md` — RouteBuilder examples (basic + with auth + paginated), SchemaRegistry derivation patterns, mergeOpenAPIDocuments use cases, `definePluginRoutes` plugin pattern
|
|
|
|
## 5. Gates
|
|
|
|
- [ ] 5.1 `bunx turbo lint typecheck test --filter=@suaveplan/api-openapi --force`
|
|
- [ ] 5.2 Coverage 100/100/100/100
|
|
- [ ] 5.3 `bun scripts/openspec-conformance.ts @suaveplan/api-openapi` exit 0
|
|
- [ ] 5.4 Build green
|
|
- [ ] 5.5 Banned-pattern + no `export *` + no direct runner imports
|
|
|
|
## 6. Archive
|
|
|
|
- [ ] 6.1 Fold spec → `openspec/specs/api-openapi/spec.md`
|
|
- [ ] 6.2 mv change → archive
|
|
- [ ] 6.3 MANIFEST + STATUS refresh
|