Documentation Generation, Coverage Scanning, and Reference Sync Tooling
Overview
This tooling group keeps the repository’s documentation set synchronized with the codebase and with the generated OpenAPI artifacts. It covers the full docs maintenance loop: generate the repo analysis page, refresh endpoint reference pages from OpenAPI, scan for missing documentation coverage, validate that endpoint pages still point at real OpenAPI operations, and enforce the workspace memory rule used by the repo’s long-lived documentation process.
For local development, the scripts are designed to be run together through a single orchestration entry point. The generated outputs live under docs/repo/, docs/api-reference/endpoint/, and docs/docs.json, while the workspace memory check reads the small set of long-lived files in workspace/ that the repo treats as durable project memory.
Architecture Overview
flowchart TB
subgraph DocsOrchestration [Docs Generation and Validation]
DocsGenerate[docs-generate.mjs]
RepoAnalysis[generate-repo-analysis-docs.mjs]
Coverage[scan-repo-doc-coverage.mjs]
SyncRefs[sync-api-reference-pages.mjs]
ValidateRefs[validate-docs-openapi-links.mjs]
WorkspaceCheck[check-workspace-memory.mjs]
end
subgraph Inputs [Repository Inputs]
Readme[README.md]
GitFiles[Tracked files]
DocsJson[docs docs.json]
OpenapiUs[docs api-reference openapi.json]
OpenapiJp[docs api-reference jp-openapi.json]
WorkspaceFiles[workspace memory files]
PrismaSchema[packages db prisma schema.prisma]
end
subgraph Outputs [Generated Outputs]
RepoAnalysisPage[docs repo auto-generated-analysis.mdx]
CoveragePage[docs repo documentation-coverage.mdx]
EndpointPages[docs api-reference endpoint pages]
UpdatedDocsJson[docs docs.json]
end
DocsGenerate --> RepoAnalysis
DocsGenerate --> Coverage
DocsGenerate --> SyncRefs
DocsGenerate --> ValidateRefs
DocsGenerate --> WorkspaceCheck
Readme --> RepoAnalysis
GitFiles --> RepoAnalysis
PrismaSchema --> RepoAnalysis
GitFiles --> Coverage
DocsJson --> SyncRefs
OpenapiUs --> ValidateRefs
OpenapiJp --> ValidateRefs
WorkspaceFiles --> WorkspaceCheck
RepoAnalysis --> RepoAnalysisPage
Coverage --> CoveragePage
SyncRefs --> EndpointPages
SyncRefs --> UpdatedDocsJson
Generated Artifacts
| Artifact | Produced By | Purpose |
|---|---|---|
docs/repo/auto-generated-analysis.mdx |
scripts/generate-repo-analysis-docs.mjs |
Auto-generated repo analysis, ownership, topology, and architecture summary. |
docs/repo/documentation-coverage.mdx |
scripts/scan-repo-doc-coverage.mjs |
Coverage report for tracked files that should have explicit docs references. |
docs/api-reference/endpoint/*.mdx |
scripts/sync-api-reference-pages.mjs |
Human-readable endpoint pages generated from OpenAPI operations. |
docs/docs.json |
scripts/sync-api-reference-pages.mjs |
Navigation updates for generated API reference pages. |
docs/api-reference/openapi.json |
openapi:generate step |
US OpenAPI artifact consumed by docs validation. |
docs/api-reference/jp-openapi.json |
openapi:generate step |
JP OpenAPI artifact consumed by docs validation and sync. |
Docs Generation Pipeline
scripts/docs-generate.mjs
scripts/docs-generate.mjs
This is the top-level orchestration script for local docs generation. It runs the documentation and schema tasks in a fixed sequence and stops immediately if any step fails.
Steps
| Step | Command | Purpose |
|---|---|---|
| Generate repository analysis page | pnpm docs:generate-analysis |
Builds docs/repo/auto-generated-analysis.mdx. |
| Generate Prisma client | pnpm db:generate |
Refreshes generated database client code before docs tasks that rely on schema metadata. |
| Generate OpenAPI JSON artifacts | pnpm openapi:generate |
Produces the OpenAPI files consumed by reference sync and validation. |
| Sync API reference pages from OpenAPI | pnpm docs:sync-api-reference-pages |
Creates missing endpoint docs and updates docs navigation. |
| Scan whole-repo documentation coverage | pnpm docs:scan-repo-coverage |
Writes the documentation coverage report. |
| Validate endpoint OpenAPI references | pnpm docs:validate-openapi-links |
Confirms endpoint pages still point at operations present in generated specs. |
Execution behavior
- Uses
spawnSyncfor each step. - Prints step progress in order as
[index/total]. - Inherits stdio so each command’s output is visible directly in the terminal.
- Uses the current environment unchanged.
- Stops on the first non-zero exit code and reports the failing step.
Flow
sequenceDiagram
participant Dev as Developer
participant Orchestrator as docs-generate.mjs
participant Analysis as generate-repo-analysis-docs.mjs
participant Prisma as db generate
participant OpenAPI as openapi generate
participant Sync as sync-api-reference-pages.mjs
participant Coverage as scan-repo-doc-coverage.mjs
participant Validate as validate-docs-openapi-links.mjs
Dev->>Orchestrator: Run docs generation
Orchestrator->>Analysis: Generate repo analysis page
Analysis-->>Orchestrator: auto-generated-analysis.mdx
Orchestrator->>Prisma: Generate Prisma client
Prisma-->>Orchestrator: Generated client
Orchestrator->>OpenAPI: Generate OpenAPI artifacts
OpenAPI-->>Orchestrator: openapi.json and jp-openapi.json
Orchestrator->>Sync: Sync endpoint reference pages
Sync-->>Orchestrator: Endpoint pages and docs.json updates
Orchestrator->>Coverage: Scan documentation coverage
Coverage-->>Orchestrator: documentation-coverage.mdx
Orchestrator->>Validate: Validate OpenAPI links
Validate-->>Orchestrator: Pass or fail
Orchestrator-->>Dev: Success or first failure
Repository Analysis Page Generation
scripts/generate-repo-analysis-docs.mjs
scripts/generate-repo-analysis-docs.mjs
This script writes docs/repo/auto-generated-analysis.mdx. It walks tracked repository files, workspace package manifests, README.md, and the Prisma schema to produce a structured analysis page.
Inputs and derived data
| Input or Heuristic | Purpose |
|---|---|
workspaceDirs = ["apps", "packages"] |
Restricts workspace discovery to the application and package roots. |
workspacePkgs |
Collects package metadata from each child package.json found under apps/ and packages/. |
trackedFiles from git ls-files |
Provides the file list used for graph and heuristic discovery. |
readmePath |
Supplies the repository summary line used in the generated page. |
prismaSchemaPath |
Supplies model names extracted from packages/db/prisma/schema.prisma. |
componentHints |
Maps known file patterns to responsibility text for the key components table. |
integrationHints |
Collects integration-related files by filename pattern. |
queueEventFiles |
Collects queue, event, webhook, cron, and worker files by filename pattern. |
authFiles |
Collects auth, token, permission, scope, and RBAC files by filename pattern. |
deployFiles |
Collects deployment and infrastructure files by filename pattern. |
Helper functions
| Function | Role |
|---|---|
exists |
Checks whether a file or directory is present using stat. |
readJson |
Parses a JSON file from disk. |
findByPattern |
Returns up to 12 tracked files matching a regex. |
nodeId |
Normalizes a name into a Mermaid-safe node identifier. |
fileChip |
Renders a file path as a compact HTML chip in the generated MDX. |
Generated page sections
The generated page includes these sections:
- What the repo is responsible for
- Entry points
- External dependencies
- Key Components Reference
- Internal module graph
- System topology and service boundaries
- Request lifecycle / execution flow
- Data model / schema interactions
- Queues, events, cron jobs, background workers
- Third-party integrations
- Auth / permissions model
- Failure points
- Deployment architecture
- How this repo talks to the other repos
- Per-service docs
Heuristic outputs
| Heuristic Output | Source |
|---|---|
| Entry points | src/index.ts, src/index.tsx, src/main.ts, src/server.ts, src/app.ts, package.json main, or src/generate.ts when a generate script exists. |
| Internal graph edges | Workspace dependencies declared with workspace: in dependencies, devDependencies, or peerDependencies. |
| External dependency list | Non-workspace dependencies plus repo-level non-workspace dev dependencies. |
| Prisma model names | model declarations in packages/db/prisma/schema.prisma. |
Key component hints
| File Pattern | Responsibility |
|---|---|
apps/api/src/index.ts |
Composes the public API service and bootstraps route and plugin wiring. |
apps/api/src/server.ts |
Bootstraps the Fastify runtime, middleware, and lifecycle hooks. |
apps/api/src/routes/us/index.ts |
Implements US consent, token, data, and scoring request handlers. |
apps/api/src/routes/jp/index.ts |
Implements JP consent, token, data, and scoring request handlers. |
apps/worker/src/index.ts |
Runs background and async jobs for webhook and compliance processing. |
packages/db/prisma/schema.prisma |
Defines relational data models and persistence schema contracts. |
packages/openapi/src/generate.ts |
Generates OpenAPI JSON artifacts consumed by Mintlify API docs. |
docs/api-reference/openapi.json |
US API schema source for interactive request and response docs. |
docs/api-reference/jp-openapi.json |
JP API schema source for interactive request and response docs. |
Repo analysis flow
flowchart TB
Root[Repository files] --> GitTracked[Tracked files]
Root --> Readme[README md]
Root --> Prisma[Prisma schema]
GitTracked --> Heuristics[File heuristics]
Readme --> Summary[Repository summary]
Prisma --> Models[Prisma models]
Heuristics --> Graph[Internal module graph]
Heuristics --> Topology[System topology]
Heuristics --> Components[Key components]
Summary --> Page[auto generated analysis mdx]
Models --> Page
Graph --> Page
Topology --> Page
Components --> Page
Documentation Coverage Scanning
scripts/scan-repo-doc-coverage.mjs
scripts/scan-repo-doc-coverage.mjs
This script generates docs/repo/documentation-coverage.mdx. It scans tracked files that match a docs-relevant pattern, then checks whether each path string appears anywhere in the tracked docs/*.mdx corpus.
Core variables and helpers
| Variable or Helper | Role |
|---|---|
candidatePattern |
Regex used to select files worth checking for explicit documentation references. |
tracked |
All tracked files from git ls-files. |
docFiles |
All tracked .mdx files under docs/. |
docsCorpus |
Concatenated contents of every tracked docs MDX file. |
isDocumented |
Returns true when the file path string appears in docsCorpus. |
missing |
Candidate files not found in the docs corpus. |
documented |
Candidate files found in the docs corpus. |
byArea |
Counts missing files grouped by their first two path segments. |
coverage |
Percentage of documented candidates, rounded to the nearest integer. |
outPath |
Target file path for the generated report. |
Candidate file scope
The scanner considers these tracked file families:
apps/**/*.ts,apps/**/*.tsx,apps/**/*.js,apps/**/*.mjs,apps/**/*.cjs,apps/**/*.py,apps/**/*.gopackages/**/*.ts,packages/**/*.tsx,packages/**/*.js,packages/**/*.mjs,packages/**/*.cjspackages/db/prisma/schema.prismadocuments/**/*.md,documents/**/*.yaml,documents/**/*.yml.github/workflows/*.ymland.github/workflows/*.yaml
Coverage report layout
The generated page includes:
- Coverage summary
- Pie chart for documented vs missing files
- Missing docs by area
- Missing files, top 250 entries
- Suggested documentation text for each missing file
Suggestion rules for missing files
| Area Prefix | Suggested Documentation |
|---|---|
apps/ |
Document runtime responsibilities and request or worker flow. |
packages/ |
Document module contracts, consumers, and data boundaries. |
documents/ |
Document contract ownership, versioning, and regeneration workflow. |
| Other areas | Document CI, deployment behavior, and failure handling. |
Coverage calculation
coverage = 100when no candidates exist.- Otherwise:
Math.round((documented.length / candidates.length) * 100).
API Reference Page Synchronization
scripts/sync-api-reference-pages.mjs
scripts/sync-api-reference-pages.mjs
This script reads docs/docs.json, inspects generated OpenAPI specs, and creates missing endpoint reference pages under docs/api-reference/endpoint/. It also updates the docs navigation so the new pages appear under the API Reference tab.
Core variables and helpers
| Variable or Helper | Role |
|---|---|
docsJsonPath |
Path to docs/docs.json. |
usSpecPath |
Path to docs/api-reference/openapi.json. |
jpSpecPath |
Path to docs/api-reference/jp-openapi.json. |
endpointDir |
Directory containing endpoint reference pages. |
existingFiles |
Current .mdx files already present in docs/api-reference/endpoint/. |
existingRefs |
Set of openapi frontmatter values already referenced by existing pages. |
specs |
Region/spec list used by the sync pass. |
created |
Tracks pages created during the current run. |
exists |
Checks whether a spec file is present. |
toSlug |
Converts region, method, and path into a page slug. |
findOrCreateGroup |
Locates or adds a docs navigation group entry. |
Generated page template
For each missing operation, the script writes a page with:
- Frontmatter
title - Frontmatter
openapi: '<METHOD> <PATH>' - An endpoint heading
- A literal endpoint display line with
https://api.joinlita.com - A short “What to expect” note
- An example
curlrequest block
Sync behavior
- Reads the API Reference tab from
docs/docs.json. - Creates missing pages only when their
METHOD /pathoperation is absent from existing endpoint docs. - Uses only the standard methods
GET,POST,PUT,PATCH, andDELETE. - Appends created page paths to the docs navigation group.
- Writes the updated
docs/docs.jsonback to disk.
Page creation flow
sequenceDiagram
participant Sync as sync api reference pages
participant DocsJson as docs json
participant Spec as OpenAPI spec
participant Pages as endpoint docs directory
Sync->>DocsJson: Read navigation
Sync->>Pages: Read existing endpoint pages
Sync->>Spec: Read operations
Spec-->>Sync: paths and methods
Sync->>Pages: Write missing pages
Sync->>DocsJson: Update API Reference group
Sync-->>DocsJson: Persist navigation
Slug generation rules
[!NOTE] The visible
specsarray contains onlyjpSpecPath, so the shown sync pass generates endpoint pages from the JP OpenAPI artifact only. The validation script checks both regional specs.
toSlug builds file names by:
- prefixing the region
- lowercasing the HTTP method
- stripping leading slashes
- removing braces
- converting non-alphanumeric characters to hyphens
- collapsing repeated hyphens
- trimming leading and trailing hyphens
OpenAPI Link Validation
scripts/validate-docs-openapi-links.mjs
scripts/validate-docs-openapi-links.mjs
This script checks that endpoint docs under docs/api-reference/endpoint/ point at operations that exist in the generated US or JP OpenAPI specs.
Core variables
| Variable | Role |
|---|---|
root |
Repository root from process.cwd(). |
endpointDir |
Directory containing endpoint MDX pages. |
usSpecPath |
US OpenAPI artifact path. |
jpSpecPath |
JP OpenAPI artifact path. |
files |
All .mdx endpoint docs in endpointDir. |
missing |
Accumulates endpoint pages whose openapi reference is missing from both specs. |
Validation logic
- Reads every
.mdxfile in the endpoint docs directory. - Matches a frontmatter line of the form
openapi: '<METHOD> <PATH>'. - Splits the value into HTTP method and path.
- Checks the path and method against both OpenAPI specs.
- Records the page as missing when the operation is absent from both specs.
- Exits with code
1and prints the missing references. - Exits successfully after validating all files when nothing is missing.
Validation behavior
Pages without an openapi frontmatter entry are skipped by this script. The check is focused on generated or maintained endpoint reference pages that declare an OpenAPI binding.
Validation flow
sequenceDiagram
participant Validator as validate docs openapi links
participant Pages as endpoint docs directory
participant UsSpec as US OpenAPI
participant JpSpec as JP OpenAPI
Validator->>Pages: Read endpoint pages
Pages-->>Validator: MDX frontmatter
Validator->>UsSpec: Check method and path
Validator->>JpSpec: Check method and path
alt missing in both specs
Validator-->>Validator: Record missing reference
else found in at least one spec
Validator-->>Validator: Accept page
end
Workspace Memory Enforcement
scripts/check-workspace-memory.mjs
scripts/check-workspace-memory.mjs
This script supports the repository’s workspace memory rule described in workspace/README.md. It builds the changed-file set from git history and defines the explicit list of workspace memory files that should be treated as durable project memory.
Visible inputs and state
| Variable or Helper | Role |
|---|---|
memoryFiles |
Set of workspace files that belong to repo memory: workspace/SOUL.md, workspace/MEMORIES.md, workspace/DECISIONS.md, workspace/TASKS.md, and workspace/README.md. |
lines |
Normalizes command output into trimmed, non-empty file paths. |
changed |
Accumulates file paths changed in the current commit or local working tree. |
Changed-file discovery
The script builds changed in this order:
git diff --name-only HEADgit ls-files --others --exclude-standard- If still empty,
git diff-tree --no-commit-id --name-only -r HEAD
The second step explicitly includes untracked files for local development mode.
Workspace memory files
| File | Role |
|---|---|
workspace/SOUL.md |
Mission and principles. |
workspace/MEMORIES.md |
Dated observations that should influence future edits. |
workspace/DECISIONS.md |
Durable architecture and product decisions. |
workspace/TASKS.md |
Follow-up work. |
workspace/README.md |
Repository guidance for the memory folder itself. |
Workspace memory flow
flowchart TB
GitDiff[git diff HEAD] --> Changed[Changed files]
GitUntracked[git ls files others] --> Changed
GitFallback[git diff tree] --> Changed
MemoryFiles[Workspace memory files] --> Check[Workspace memory check]
Changed --> Check
Check --> Result[Memory enforcement result]
Error Handling and Failure Modes
| Script | Failure Behavior |
|---|---|
docs-generate.mjs |
Stops the pipeline on the first non-zero step result and reports the failing step label. |
sync-api-reference-pages.mjs |
Throws when the API Reference tab cannot be found in docs/docs.json. |
validate-docs-openapi-links.mjs |
Prints missing endpoint references and exits with code 1 when an openapi page reference is absent from both specs. |
scan-repo-doc-coverage.mjs |
Produces a report that surfaces the missing files and grouped counts; the visible logic is report generation only. |
check-workspace-memory.mjs |
Builds the changed-file set from git and untracked files before the memory check that follows. |
Integration Points
pnpmworkspace scriptsgitcommand line inspection for tracked and changed filesREADME.mdfor repository summary textpackages/db/prisma/schema.prismafor model discoverydocs/docs.jsonfor docs navigation updatesdocs/api-reference/openapi.jsonanddocs/api-reference/jp-openapi.jsonfor endpoint validation and syncdocs/api-reference/endpoint/for generated endpoint reference pagesworkspace/README.mdand the workspace memory files for durable repo memory
Testing Considerations
| Scenario | Expected Outcome |
|---|---|
Run pnpm docs:generate with all steps healthy |
The pipeline completes and prints the success message. |
| Break one step in the docs generation pipeline | The orchestrator stops at that step and exits with the step’s status. |
Add a tracked file in apps/ or packages/ without a docs reference |
It appears in docs/repo/documentation-coverage.mdx as missing. |
| Add a new OpenAPI operation without a matching endpoint page | validate-docs-openapi-links.mjs reports the missing openapi reference. |
Add a missing endpoint page with valid openapi frontmatter |
The validation pass accepts it if the operation exists in either spec. |
| Add a new operation to OpenAPI | sync-api-reference-pages.mjs creates a corresponding endpoint page when no existing page references that operation. |
| Update a workspace memory file in a meaningful docs change | The workspace memory check has the updated file available in its tracked memory set. |
Key Classes Reference
| Class | Responsibility |
|---|---|
docs-generate.mjs |
Orchestrates the docs generation pipeline and stops on first failure. |
generate-repo-analysis-docs.mjs |
Builds the auto-generated repository analysis page from tracked files, README text, and Prisma schema metadata. |
scan-repo-doc-coverage.mjs |
Scans tracked repository files for documentation coverage and writes the coverage report. |
sync-api-reference-pages.mjs |
Generates missing endpoint reference pages from OpenAPI and updates docs navigation. |
validate-docs-openapi-links.mjs |
Confirms generated endpoint pages still reference operations present in the OpenAPI specs. |
check-workspace-memory.mjs |
Collects changed paths and workspace memory files for the repo’s memory enforcement check. |