Repo Docs Framework (Tree-sitter → Repo Map → Sys Design)

This is a repo-agnostic framework that generates Copilot-friendly documentation for any codebase:

Codebase
  ↓
Tree-sitter AST (optional, for symbols)
  ↓
Symbol extraction
  ↓
Repo Map (repo-map.md)
  ↓
System Design (sys-design.md = repo-map + architecture + api-flow + detected stack/languages)

It’s intentionally dependency-light:

• Uses Node.js only (no npm install required to run the generators)
• Uses Tree-sitter CLI globally (not installed in the target repo)

What it generates

Inside a chosen output folder (default: docs/):

• repo-map.md (auto-generated)
• sys-design.md (auto-generated)
• architecture.md (optional template, if missing)
• api-flow.md (optional template, if missing)

Quick start (any repo)

From the repo root you want to document:

node /path/to/repo-docs-framework/bin/repo-docs.mjs --root . --out docs

Re-run any time things change.

Tree-sitter global install (recommended)

The framework can generate a repo map without Tree-sitter, but symbol extraction requires it.

Install Tree-sitter CLI globally

Pick one:

# npm global install
npm i -g tree-sitter-cli

# or cargo install
cargo install tree-sitter-cli

Verify:

tree-sitter --version

Install grammars (multi-language)

Tree-sitter discovers grammars via a global config.

1. Create config:

tree-sitter init-config

2. Add grammar directory in ~/.config/tree-sitter/config.json (Linux):

{
  "parser-directories": [
    "$HOME/.tree-sitter-parsers"
  ]
}

3. Clone grammars into that directory (names must start with tree-sitter-):

mkdir -p "$HOME/.tree-sitter-parsers"
cd "$HOME/.tree-sitter-parsers"

# Common starters
git clone https://github.com/tree-sitter/tree-sitter-typescript
git clone https://github.com/tree-sitter/tree-sitter-javascript
git clone https://github.com/tree-sitter/tree-sitter-python
git clone https://github.com/tree-sitter/tree-sitter-go
git clone https://github.com/tree-sitter/tree-sitter-java
git clone https://github.com/tree-sitter/tree-sitter-rust
git clone https://github.com/tree-sitter/tree-sitter-json
git clone https://github.com/tree-sitter/tree-sitter-yaml
git clone https://github.com/tree-sitter/tree-sitter-bash

Confirm:

tree-sitter dump-languages

How it decides “stack” and “languages”

• Languages: file extension counts across the target --root, excluding configured ignore dirs.
• Stack: heuristic detection from:
  • package manifests (package.json, pyproject.toml, go.mod, etc.)
  • well-known config files (docker-compose.yml, k8s/, terraform, etc.)
  • common folder patterns (src/, apps/, services/, etc.)

You can customize ignores and behavior via --config (see config/default.json).

Suggested automation (optional)

• Pre-commit hook to regenerate docs
• CI job to ensure generated docs are up to date (fail on diff)