Initial Commit

openspec/archive/2026-05-25-enterprise-docs/tasks.md

@@ -0,0 +1,94 @@
+# 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.