From fab1d8f7d69d9c84089dfb4ab124ab7b54896c28 Mon Sep 17 00:00:00 2001 From: Jeremy Eder Date: Thu, 15 Jan 2026 22:46:28 -0500 Subject: [PATCH 1/2] Add repomap workflow automation - 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 --- .github/workflows/ci.yml | 21 +++++ .pre-commit-config.yaml | 8 ++ CLAUDE.md | 23 +++++- README.md | 8 +- docs/patterns/repomap.md | 105 ++++++++++++++++++++++--- scripts/README.md | 149 ++++++++++++++++++++++++++++++++++++ scripts/update-repomap.sh | 157 ++++++++++++++++++++++++++++++++++++++ 7 files changed, 457 insertions(+), 14 deletions(-) create mode 100644 scripts/README.md create mode 100755 scripts/update-repomap.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d4c6dee..2598ba4 100644 --- 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 index 7cc43d9..6a31047 100644 --- 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 index afb97ac..2996431 100644 --- 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 index c971c13..3b0a349 100644 --- 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 index a1f6031..c7e018b 100644 --- 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 new file mode 100644 index 0000000..26efe5f --- /dev/null +++ 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 new file mode 100755 index 0000000..847bb95 --- /dev/null +++ b/scripts/update-repomap.sh @@ -0,0 +1,157 @@ +#!/usr/bin/env bash +# +# Update repository map (.repomap.txt) +# +# This script regenerates the .repomap.txt file using repomap.py. +# The repomap provides AI-friendly context about code structure, +# reducing token usage while maintaining code understanding. +# +# Usage: +# ./scripts/update-repomap.sh # Update repomap +# ./scripts/update-repomap.sh --check # Validate repomap is current +# ./scripts/update-repomap.sh --help # Show help + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +REPOMAP_FILE="$REPO_ROOT/.repomap.txt" +REPOMAP_PY="$REPO_ROOT/repomap.py" + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +usage() { + cat < .repomap.txt +EOF +} + +check_dependencies() { + if [[ ! -f "$REPOMAP_PY" ]]; then + echo -e "${RED}Error: repomap.py not found at $REPOMAP_PY${NC}" >&2 + exit 1 + fi + + if ! command -v python3 &>/dev/null; then + echo -e "${RED}Error: python3 not found. Install Python 3.11+${NC}" >&2 + exit 1 + fi +} + +generate_repomap() { + echo -e "${YELLOW}Generating repository map...${NC}" + + cd "$REPO_ROOT" + + # Generate new repomap + local error_output + if error_output=$(python3 "$REPOMAP_PY" . 2>&1 > "${REPOMAP_FILE}.new"); then + mv "${REPOMAP_FILE}.new" "$REPOMAP_FILE" + echo -e "${GREEN}✓ Repository map updated: $REPOMAP_FILE${NC}" + return 0 + else + echo -e "${RED}✗ Failed to generate repository map${NC}" >&2 + echo -e "${YELLOW}$error_output${NC}" >&2 + if echo "$error_output" | grep -q "tree-sitter packages not installed"; then + echo -e "${YELLOW}Install dependencies: pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash${NC}" >&2 + fi + rm -f "${REPOMAP_FILE}.new" + return 1 + fi +} + +check_repomap_current() { + echo -e "${YELLOW}Checking if repomap is current...${NC}" + + if [[ ! -f "$REPOMAP_FILE" ]]; then + echo -e "${RED}✗ Repomap file not found: $REPOMAP_FILE${NC}" >&2 + echo -e "${YELLOW}Run: ./scripts/update-repomap.sh${NC}" >&2 + return 1 + fi + + cd "$REPO_ROOT" + + # Generate temp repomap + local error_output + if ! error_output=$(python3 "$REPOMAP_PY" . 2>&1 > "${REPOMAP_FILE}.check"); then + echo -e "${RED}✗ Failed to generate repomap for comparison${NC}" >&2 + echo -e "${YELLOW}$error_output${NC}" >&2 + if echo "$error_output" | grep -q "tree-sitter packages not installed"; then + echo -e "${YELLOW}Install dependencies: pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash${NC}" >&2 + fi + rm -f "${REPOMAP_FILE}.check" + return 1 + fi + + # Compare with existing + if diff -q "$REPOMAP_FILE" "${REPOMAP_FILE}.check" >/dev/null 2>&1; then + echo -e "${GREEN}✓ Repomap is current${NC}" + rm -f "${REPOMAP_FILE}.check" + return 0 + else + echo -e "${RED}✗ Repomap is outdated${NC}" >&2 + echo -e "${YELLOW}Run: ./scripts/update-repomap.sh${NC}" >&2 + + # Show diff if verbose + if [[ "${VERBOSE:-0}" == "1" ]]; then + echo -e "\n${YELLOW}Differences:${NC}" + diff "$REPOMAP_FILE" "${REPOMAP_FILE}.check" || true + fi + + rm -f "${REPOMAP_FILE}.check" + return 1 + fi +} + +main() { + local check_mode=false + + # Parse arguments + while [[ $# -gt 0 ]]; do + case $1 in + --check) + check_mode=true + shift + ;; + --help) + usage + exit 0 + ;; + *) + echo -e "${RED}Error: Unknown option: $1${NC}" >&2 + usage + exit 1 + ;; + esac + done + + check_dependencies + + if [[ "$check_mode" == true ]]; then + check_repomap_current + else + generate_repomap + fi +} + +main "$@" From 465df936dab8ca426c176084a470c707b30e554c Mon Sep 17 00:00:00 2001 From: Jeremy Eder Date: Thu, 15 Jan 2026 23:05:39 -0500 Subject: [PATCH 2/2] Replace pip with uv throughout documentation - Update all package installation commands to use uv - Update CI workflow to install and use uv - Update error messages in scripts to recommend uv - Keep pip only for bootstrapping uv in CI environments Per project standards: always prefer uv over pip for package management. Co-Authored-By: Claude Sonnet 4.5 --- .github/workflows/ci.yml | 5 +++-- README.md | 4 ++-- docs/patterns/repomap.md | 26 +++++++++++++++----------- scripts/update-repomap.sh | 4 ++-- 4 files changed, 22 insertions(+), 17 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2598ba4..c02b1f3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -35,8 +35,9 @@ jobs: - name: Install repomap dependencies run: | - pip install tree-sitter tree-sitter-python tree-sitter-javascript \ - tree-sitter-typescript tree-sitter-go tree-sitter-bash + pip install uv + uv 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: | diff --git a/README.md b/README.md index 3b0a349..00dba0a 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,8 @@ git clone https://github.com/ambient-code/reference.git cd reference # Install dependencies -pip install -r requirements.txt # Repomap dependencies -pip install -r requirements-dev.txt # Doc tooling +uv pip install -r requirements.txt # Repomap dependencies +uv 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 index c7e018b..6c8cea9 100644 --- a/docs/patterns/repomap.md +++ b/docs/patterns/repomap.md @@ -12,7 +12,7 @@ This repository includes **complete automation** for repomap management. The rep ```bash # Install dependencies (includes tree-sitter packages) -pip install -r requirements.txt +uv pip install -r requirements.txt # Install pre-commit hooks (includes repomap auto-update) pre-commit install @@ -36,11 +36,11 @@ pre-commit install ### Install Dependencies ```bash -# Using pip -pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash - -# Using uv (recommended) +# Recommended method uv pip install -r requirements.txt + +# Or install individually with uv +uv pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash ``` ## Usage @@ -169,7 +169,9 @@ jobs: python-version: '3.11' - name: Install dependencies - run: pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash + run: | + pip install uv + uv pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash - name: Generate repomap run: python repomap.py . > repomap.txt @@ -189,7 +191,8 @@ generate_repomap: stage: build image: python:3.11 script: - - pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash + - pip install uv + - uv pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash - python repomap.py . > repomap.txt artifacts: paths: @@ -237,8 +240,9 @@ repomap-validation: 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 + pip install uv + uv 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 ``` @@ -342,7 +346,7 @@ Potential improvements for future versions: **Solution**: Install dependencies ```bash -pip install -r requirements.txt +uv pip install -r requirements.txt ``` ### Parse Errors @@ -395,7 +399,7 @@ See LICENSE file in repository root. **Quickstart**: -1. Install dependencies: `pip install -r requirements.txt` +1. Install dependencies: `uv pip install -r requirements.txt` 2. Install pre-commit hooks: `pre-commit install` 3. The repomap auto-updates on commits! diff --git a/scripts/update-repomap.sh b/scripts/update-repomap.sh index 847bb95..e9df504 100755 --- a/scripts/update-repomap.sh +++ b/scripts/update-repomap.sh @@ -73,7 +73,7 @@ generate_repomap() { echo -e "${RED}✗ Failed to generate repository map${NC}" >&2 echo -e "${YELLOW}$error_output${NC}" >&2 if echo "$error_output" | grep -q "tree-sitter packages not installed"; then - echo -e "${YELLOW}Install dependencies: pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash${NC}" >&2 + echo -e "${YELLOW}Install dependencies: uv pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash${NC}" >&2 fi rm -f "${REPOMAP_FILE}.new" return 1 @@ -97,7 +97,7 @@ check_repomap_current() { echo -e "${RED}✗ Failed to generate repomap for comparison${NC}" >&2 echo -e "${YELLOW}$error_output${NC}" >&2 if echo "$error_output" | grep -q "tree-sitter packages not installed"; then - echo -e "${YELLOW}Install dependencies: pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash${NC}" >&2 + echo -e "${YELLOW}Install dependencies: uv pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-bash${NC}" >&2 fi rm -f "${REPOMAP_FILE}.check" return 1