Add repomap workflow automation

jeremyeder · claude · jeremyeder · commit fab1d8f7d69d · 2026-01-15T22:46:28.000-05:00
- Add scripts/update-repomap.sh for automated repomap management
- Add pre-commit hook to auto-update repomap on code changes
- Add CI validation to ensure repomap stays current
- Update documentation (README.md, CLAUDE.md, docs/patterns/repomap.md)
- Add scripts/README.md documenting all automation scripts

The repomap now automatically updates when committing code changes
and CI validates it's current on every push/PR.

Co-Authored-By: Claude Sonnet 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -21,3 +21,24 @@ jobs:
           test -f docs/README.md || { echo "Error: docs/README.md missing"; exit 1; }
           test -d docs/adr || { echo "Error: docs/adr/ missing"; exit 1; }
           echo "All required documentation files present"
+
+  repomap-validation:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install repomap dependencies
+        run: |
+          pip install tree-sitter tree-sitter-python tree-sitter-javascript \
+                      tree-sitter-typescript tree-sitter-go tree-sitter-bash
+
+      - name: Validate repomap is current
+        run: |
+          chmod +x scripts/update-repomap.sh
+          ./scripts/update-repomap.sh --check
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,6 +1,14 @@
 repos:
   - repo: local
     hooks:
+      - id: repomap-update
+        name: Update repository map
+        entry: scripts/update-repomap.sh
+        language: system
+        pass_filenames: false
+        files: '\.(py|js|ts|tsx|go|sh|bash)$'
+        description: Regenerate .repomap.txt when code structure changes
+
       - id: mkdocs-build
         name: mkdocs build --strict
         entry: .venv/bin/mkdocs build --strict
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -135,12 +135,26 @@ cat .repomap.txt
 - Major refactoring is completed
 - Before creating PRs (ensure map is current)
 
+**Automated regeneration**:
+
+The repository includes automation for repomap management:
+
 ```bash
-# Regenerate after changes
+# Manual regeneration (recommended method)
+./scripts/update-repomap.sh
+
+# Check if repomap is current
+./scripts/update-repomap.sh --check
+
+# Legacy manual method (still works)
 python repomap.py . > .repomap.txt
 git add .repomap.txt  # Include in commits
 ```
 
+**Pre-commit hook**: The repomap is automatically regenerated when you commit changes to code files (`.py`, `.js`, `.ts`, `.tsx`, `.go`, `.sh`, `.bash`) via the pre-commit hook.
+
+**CI validation**: The CI workflow validates that the repomap is current on every push/PR.
+
 #### Integration with Development Workflow
 
 **Include repomap in commit tracking**:
@@ -369,6 +383,7 @@ Focus on "why" rather than "what".
 3. **`.github/workflows/ci.yml`** (General CI)
    - Code example linting (if any)
    - Documentation build test
+   - Repomap validation (ensures .repomap.txt is current)
    - Triggers: on push, PR
 
 4. **`.github/workflows/deploy-docs.yml`** (Documentation Deployment)
@@ -408,9 +423,15 @@ Teams can extend with:
 git clone https://github.com/yourusername/reference.git
 cd reference
 
+# Install repomap dependencies
+uv pip install -r requirements.txt
+
 # Install doc tooling
 uv pip install -r requirements-dev.txt
 
+# Install pre-commit hooks
+pre-commit install
+
 # Load repomap (session start)
 cat .repomap.txt
 
diff --git a/README.md b/README.md
@@ -25,8 +25,12 @@ See [Quickstart](docs/README.md) for pattern overview and adoption guidance.
 ```bash
 git clone https://github.com/ambient-code/reference.git
 cd reference
-./scripts/setup.sh
-source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt      # Repomap dependencies
+pip install -r requirements-dev.txt  # Doc tooling
+
+# Install pre-commit hooks (includes repomap auto-update)
 pre-commit install
 ```
 
diff --git a/docs/patterns/repomap.md b/docs/patterns/repomap.md
@@ -8,20 +8,24 @@ Generate clean, token-optimized code structure maps using tree-sitter for AI-ass
 
 ## Quick Start
 
+This repository includes **complete automation** for repomap management. The repomap is automatically updated via pre-commit hooks and validated in CI.
+
 ```bash
-# Install dependencies
+# Install dependencies (includes tree-sitter packages)
 pip install -r requirements.txt
 
-# Generate map of current directory
-python repomap.py .
+# Install pre-commit hooks (includes repomap auto-update)
+pre-commit install
 
-# Save to file
-python repomap.py . > repomap.txt
+# Manual update (if needed)
+./scripts/update-repomap.sh
 
-# Map specific directory with verbose output
-python repomap.py /path/to/repo --verbose
+# Validate repomap is current
+./scripts/update-repomap.sh --check
 ```
 
+**That's it!** The repomap will auto-update when you commit code changes.
+
 ## Installation
 
 ### Requirements
@@ -192,7 +196,78 @@ generate_repomap:
       - repomap.txt
 ```
 
-### 3. Pre-commit Hook
+### 3. Automated Workflow (This Repository)
+
+This reference repository includes **complete repomap automation**:
+
+#### Pre-commit Hook
+
+The pre-commit hook automatically regenerates `.repomap.txt` when you commit changes to code files:
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: repomap-update
+        name: Update repository map
+        entry: scripts/update-repomap.sh
+        language: system
+        pass_filenames: false
+        files: '\.(py|js|ts|tsx|go|sh|bash)$'
+```
+
+**Triggers on**: `.py`, `.js`, `.ts`, `.tsx`, `.go`, `.sh`, `.bash` file changes
+
+**What it does**: Runs `./scripts/update-repomap.sh` to regenerate `.repomap.txt` before commit
+
+#### CI Validation
+
+GitHub Actions workflow validates repomap is current on every push/PR:
+
+```yaml
+# .github/workflows/ci.yml
+repomap-validation:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    - name: Install repomap dependencies
+      run: |
+        pip install tree-sitter tree-sitter-python tree-sitter-javascript \
+                    tree-sitter-typescript tree-sitter-go tree-sitter-bash
+    - name: Validate repomap is current
+      run: ./scripts/update-repomap.sh --check
+```
+
+**What it does**: Blocks merge if `.repomap.txt` is outdated
+
+#### Automation Script
+
+The `scripts/update-repomap.sh` script provides:
+
+```bash
+# Regenerate repomap
+./scripts/update-repomap.sh
+
+# Validate repomap is current (CI usage)
+./scripts/update-repomap.sh --check
+
+# Show help
+./scripts/update-repomap.sh --help
+```
+
+**Features**:
+- Clear error messages with dependency installation hints
+- Validates repomap currency for CI/CD
+- Used by pre-commit hook for auto-updates
+
+#### Manual Pre-commit Hook (Alternative)
+
+If you prefer a simpler manual hook in other repositories:
 
 ```bash
 # .git/hooks/pre-commit
@@ -320,6 +395,14 @@ See LICENSE file in repository root.
 
 **Quickstart**:
 
-1. Install: `pip install -r requirements.txt`
-2. Run: `python repomap.py .`
-3. Save: `python repomap.py . > repomap.txt`
+1. Install dependencies: `pip install -r requirements.txt`
+2. Install pre-commit hooks: `pre-commit install`
+3. The repomap auto-updates on commits!
+
+**Manual usage** (if needed):
+
+```bash
+./scripts/update-repomap.sh          # Regenerate
+./scripts/update-repomap.sh --check  # Validate
+python repomap.py .                  # Direct generation
+```
diff --git a/scripts/README.md b/scripts/README.md
@@ -0,0 +1,149 @@
+# Scripts Directory
+
+Automation scripts for the Ambient Code reference repository.
+
+## Repomap Management
+
+### `update-repomap.sh`
+
+Updates or validates the repository map (`.repomap.txt`) - an AI-friendly code structure map that optimizes context window usage.
+
+**Usage:**
+
+```bash
+# Regenerate repomap
+./scripts/update-repomap.sh
+
+# Validate repomap is current (CI usage)
+./scripts/update-repomap.sh --check
+
+# Show help
+./scripts/update-repomap.sh --help
+```
+
+**Features:**
+
+- Automatically regenerates `.repomap.txt` using `repomap.py`
+- Validates that repomap is current (useful for CI)
+- Clear error messages with dependency installation hints
+- Used by pre-commit hook to auto-update on code changes
+
+**When to use:**
+
+- After adding/removing files or functions
+- Before creating pull requests
+- When structural changes occur
+- Automatically triggered by pre-commit hook
+
+**Dependencies:** Installed via `requirements.txt`:
+
+```bash
+uv pip install -r requirements.txt
+```
+
+## Documentation Validation
+
+### `validate-mermaid.sh`
+
+Validates all Mermaid diagrams in the documentation.
+
+**Usage:**
+
+```bash
+./scripts/validate-mermaid.sh
+```
+
+**Purpose:** Ensures Mermaid diagrams are syntactically correct before committing, preventing broken diagrams in documentation.
+
+## Development Setup
+
+### `setup.sh`
+
+Initial repository setup script.
+
+**Usage:**
+
+```bash
+./scripts/setup.sh
+```
+
+**What it does:**
+
+- Installs dependencies
+- Sets up pre-commit hooks
+- Initializes development environment
+
+## Demo Recording
+
+### `record-demo.sh`
+
+Records demonstration videos/screenshots for documentation.
+
+**Usage:**
+
+```bash
+./scripts/record-demo.sh
+```
+
+## Autonomous Review
+
+Scripts for automated code review workflows.
+
+### `autonomous-review/review-reference.sh`
+
+Performs automated review of reference documentation.
+
+**Usage:**
+
+```bash
+./scripts/autonomous-review/review-reference.sh
+```
+
+## Validation
+
+Scripts for continuous validation and testing.
+
+### `validation/autonomous-fix-loop-template.sh`
+
+Template for autonomous validation and fix loops.
+
+### `validation/tests/`
+
+Test scripts for validation workflows:
+
+- `run-all.sh` - Run all validation tests
+- `test-autonomous-fix-loop.sh` - Test autonomous fix loop
+
+## Quick Reference
+
+**Common workflows:**
+
+```bash
+# Setup new development environment
+./scripts/setup.sh
+
+# Update repomap after code changes
+./scripts/update-repomap.sh
+
+# Validate documentation
+./scripts/validate-mermaid.sh
+markdownlint docs/**/*.md --fix
+
+# Run all validation tests
+./scripts/validation/tests/run-all.sh
+```
+
+## CI Integration
+
+These scripts are integrated into GitHub Actions workflows:
+
+- **`update-repomap.sh --check`** - CI job validates repomap is current
+- **`validate-mermaid.sh`** - CI job validates diagrams before merge
+- **Pre-commit hook** - Auto-runs `update-repomap.sh` on code changes
+
+## Development Notes
+
+- All scripts use `#!/usr/bin/env bash` for portability
+- Scripts include error handling (`set -euo pipefail`)
+- Scripts provide helpful error messages with actionable suggestions
+- Scripts follow the "fail fast" principle
diff --git a/scripts/update-repomap.sh b/scripts/update-repomap.sh
