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

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.