95 lines
3.6 KiB
Markdown
95 lines
3.6 KiB
Markdown
# Tasks: enterprise-docs
|
||
|
||
**Change ID**: enterprise-docs
|
||
**Package**: `@suaveplan/docs`
|
||
**Target path**: `packages/devtools/docs/docs`
|
||
|
||
## 1. Scaffold
|
||
|
||
- [ ] Create `packages/devtools/docs/docs/` per design layout.
|
||
- [ ] Add `markdown` catalog key to root `package.json` carrying `glob`,
|
||
`gray-matter`, `remark-parse`, `remark-gfm`, `unified`,
|
||
`unist-util-visit`, `@types/mdast`.
|
||
- [ ] Write `package.json` at version `0.1.0` with subpath exports per feature.
|
||
- [ ] Write `tsconfig.lib.json`, `vite.config.ts`, `vitest.config.ts`,
|
||
`README.md`.
|
||
|
||
## 2. Errors
|
||
|
||
- [ ] Implement `src/errors/errors.ts` with `DOCS_CODES` registry (eight
|
||
codes) and `DocsError extends SuaveplanError<DocsErrorCode>`.
|
||
- [ ] Write `src/errors/errors.test.ts` covering registry shape, every code,
|
||
and round-trip through cause chain.
|
||
|
||
## 3. Observability
|
||
|
||
- [ ] Implement `src/observability/observability.ts` and
|
||
`observability.types.ts` exposing `createDocsObservability`.
|
||
- [ ] Test against `@opentelemetry/api` no-op providers.
|
||
|
||
## 4. Types
|
||
|
||
- [ ] Implement `src/types/docs.types.ts` carrying `DocFile`, `DocLink`,
|
||
`DocCategory` (eighteen-category union), `DocGraph`, `DocNode`,
|
||
`DiscoverOptions`, `SearchResult`, `DiscoverOptionsSchema`.
|
||
|
||
## 5. Parser
|
||
|
||
- [ ] Implement `src/parser/parse.ts` using typed mdast traversal, no `as any`,
|
||
timing instrumented via observability.
|
||
- [ ] Write `src/parser/parse.test.ts` covering title extraction, frontmatter,
|
||
link extraction, GFM tables, ID stability, category derivation across
|
||
all eighteen genesis categories, root tier, and PARSE_FAILED branch.
|
||
|
||
## 6. Discovery
|
||
|
||
- [ ] Implement `src/discovery/discover.ts`: Zod-validate options,
|
||
`AbortSignal` propagation, per-file IO error counter, glob error wrap.
|
||
- [ ] Write `src/discovery/discover.test.ts` covering happy path, includeApps,
|
||
ignore, sorting, abort, invalid options, IO error surfacing.
|
||
|
||
## 7. Graph
|
||
|
||
- [ ] Implement `src/graph/build-graph.ts` and `src/graph/find-orphans.ts`.
|
||
- [ ] Write tests covering link resolution, anchor + external link rejection,
|
||
fragment handling, fuzzy basename match, self-link skip, orphan
|
||
detection, and findOrphans suggestedParent.
|
||
|
||
## 8. Hierarchy
|
||
|
||
- [ ] Implement `src/hierarchy/build-hierarchy.ts` with configurable
|
||
`maxDepth`.
|
||
- [ ] Write tests covering nesting, category grouping, circular safety, sort
|
||
order, and `HIERARCHY_CYCLE_LIMIT` (when maxDepth=0).
|
||
|
||
## 9. Search
|
||
|
||
- [ ] Implement `src/search/search.ts` with timing + counter instrumentation
|
||
and `DOCS.SEARCH_INVALID_QUERY` on non-string input.
|
||
- [ ] Write tests covering scoring, snippets, limit, sort, case insensitivity.
|
||
|
||
## 10. Barrel + subpath exports
|
||
|
||
- [ ] Author `src/index.ts` with explicit named re-exports — never `export *`.
|
||
- [ ] Confirm `package.json` `exports` map has one subpath per feature.
|
||
|
||
## 11. Docs
|
||
|
||
- [ ] Sibling `.md` for every `.ts` (excl. `index.ts`, `.test.ts`,
|
||
`.types.ts`). Each ≥200 words across six required sections.
|
||
- [ ] `README.md` with Purpose, Install, Quick Start, Modules.
|
||
|
||
## 12. Gate
|
||
|
||
- [ ] `bunx turbo lint typecheck test build --filter=@suaveplan/docs` green.
|
||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/docs` at 100/100/100/100.
|
||
- [ ] Banned-pattern scan clean.
|
||
- [ ] Test-runner import scan clean.
|
||
- [ ] MANIFEST refreshed via `bun scripts/folder-reorg/generate-manifest.ts`.
|
||
|
||
## 13. Archive
|
||
|
||
- [ ] Fold `specs/docs/spec.md` into `openspec/specs/docs/spec.md`.
|
||
- [ ] Move change folder to `openspec/archive/2026-05-25-enterprise-docs/`.
|
||
- [ ] Flip STATUS.md row `–` → `✅` with one-line summary; bump counts.
|