Build a GitHub-native system that ensures documentation is always aligned with code by automatically detecting changes and generating updates after PR merges.

We do not generate docs from scratch. We ensure docs never become incorrect.

• Documentation becomes outdated quickly
• Developers do not update docs during PRs
• Broken examples reduce trust in codebases
• No automated system enforces documentation correctness

• Accuracy > Intelligence
• Automation without friction
• Human-in-the-loop (via PR review)
• Diff-based, not full-repo processing

PR Merged
   ↓
GitHub Webhook (App)
   ↓
Backend Server (TS)
   ↓
Diff Analyzer (AST)
   ↓
Doc Matcher
   ↓
Drift Detection
   ↓
Fix Generator (AI optional)
   ↓
Create Docs PR

• Handles authentication (JWT + installation tokens)
• Receives webhook events
• Triggers backend processing

• Webhook receiver

• Orchestrator

• Responsible for:

  • diff extraction
  • processing pipeline
  • PR creation

• Diff analysis
• AST parsing
• Drift detection
• Fix generation

• Used for:

  • natural language fixes
  • example regeneration

• Supports:

  • built-in provider
  • BYO API keys

• PR creation
• Comments
• Commit patches

• GitHub App installation per repo/org

• Webhook support:

  • pull_request.closed

• Detect merged PRs

• Analyze only changed files

• Extract:

  • modified functions
  • renamed symbols
  • changed parameters

• Use tree-sitter

• Extract:

  • function names
  • parameters
  • return values

• Identify docs:

  • README.md
  • /docs/**
  • inline examples

Detect mismatches:

• function signatures
• parameter changes
• removed APIs
• outdated examples

• Deterministic updates:

  • signature replacement
  • param updates

• AI-assisted updates (optional)

• Create PR:

  • docs: update after #<PR_NUMBER>

• Include:

  • updated files
  • summary

Example:

Changes:
- Updated createUser(email, name) → createUser(email)
- Fixed example in README
- Removed deprecated parameter

File: docs-integrity.config.json

{
  "docsPaths": ["README.md", "docs/"],
  "ignore": ["internal/"],
  "ai": {
    "enabled": true,
    "provider": "openai"
  },
  "autoPR": true
}

• User provides API keys

• Supported providers:

  • OpenAI
  • Anthropic

• Each fix includes:

  • confidence %
  • reasoning

• Aggregate multiple changes
• Reduce PR spam

• File/path-based exclusions

Commands:

docs-integrity check
docs-integrity fix

• Run code blocks from docs
• Detect failures

• Compare actual vs documented responses

• Track doc health over time

• Org-level insights

• VSCode extension
• real-time feedback

• Language: TypeScript
• Runtime: Node.js
• Framework: Hono (preferred)

• Octokit SDK
• GitHub App (webhooks + auth)

• tree-sitter

• Language support:

  • Phase 1: TypeScript
  • Phase 2: Python

• TypeScript

• Bundler:

  • tsup / esbuild

• OpenAI / Anthropic APIs
• Abstract provider interface

• Railway (primary)
• Render (alternative)

• MVP: none

• Future:

  • PostgreSQL
  • Redis (queue)

/apps
  /backend
  /cli

/packages
  /core-engine
  /parser
  /matcher
  /fixer
  /github

/config
  default-config.json

• Uses tree-sitter
• Extracts AST
• Outputs structured data

• Compares:

  • old vs new AST

• Outputs change set

• Maps code → docs
• Heuristic-based

• Identifies inconsistencies

• Deterministic fixes
• AI fallback

• PR creation
• comments
• file updates

• Write deterministic logic first
• AI is optional, never core dependency
• Prefer clarity over cleverness

• Strict mode enabled
• No any
• Use interfaces over types where possible
• Prefer small pure functions

• No silent failures

• All errors must:

  • be logged
  • include context

• Structured logs

• Include:

  • repo
  • PR number
  • operation stage

• Unit tests for:

  • parser
  • diff analyzer
  • matcher

• Snapshot tests for:

  • doc updates

• Use ESLint + Prettier

• Consistent naming:

  • camelCase (variables)
  • PascalCase (classes)

• Validate webhook signatures
• Use short-lived tokens

• Never store plaintext keys
• Use environment variables

• Sanitize all external inputs

• Always use diff-based processing
• Avoid full repo scans
• Cache AST where possible
• Limit AI calls

• No full doc generation
• No heavy UI in early stages
• No multi-language support initially
• No self-hosted LLM

• CLI + GitHub Action

• GitHub App + Backend

• Queue system
• Analytics

• Hybrid engine (TS + Rust/Go)

If wrong even 10% of time → product fails

• No blocking PRs
• No forced workflows

• deterministic → AI enhancement

A GitHub-native system that automatically detects documentation drift after code changes and generates accurate, reviewable updates via pull requests.

• Works on real repos
• Produces correct updates >90% of time
• Requires minimal user setup
• Integrates seamlessly into GitHub workflow

END OF SPEC