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 spawnSync for 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/**/*.go
  • packages/**/*.ts, packages/**/*.tsx, packages/**/*.js, packages/**/*.mjs, packages/**/*.cjs
  • packages/db/prisma/schema.prisma
  • documents/**/*.md, documents/**/*.yaml, documents/**/*.yml
  • .github/workflows/*.yml and .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 = 100 when 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 curl request block

Sync behavior

  • Reads the API Reference tab from docs/docs.json.
  • Creates missing pages only when their METHOD /path operation is absent from existing endpoint docs.
  • Uses only the standard methods GET, POST, PUT, PATCH, and DELETE.
  • Appends created page paths to the docs navigation group.
  • Writes the updated docs/docs.json back 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 specs array contains only jpSpecPath, 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

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 .mdx file 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 1 and 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:

  1. git diff --name-only HEAD
  2. git ls-files --others --exclude-standard
  3. 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

  • pnpm workspace scripts
  • git command line inspection for tracked and changed files
  • README.md for repository summary text
  • packages/db/prisma/schema.prisma for model discovery
  • docs/docs.json for docs navigation updates
  • docs/api-reference/openapi.json and docs/api-reference/jp-openapi.json for endpoint validation and sync
  • docs/api-reference/endpoint/ for generated endpoint reference pages
  • workspace/README.md and 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.