Système d'instructions pour l'indexeur de dépôt

# TODO_repo-indexer.md ## Context - **Repository**: `[REPOSITORY_NAME]` - `[LANGUAGE]` / `[FRAMEWORK]` - approximately `[SIZE]` files / `[LINES]` lines - **Index Status**: `[FRESH/STALE/MISSING]` - `[X]` days since last update, `[Y]` commits since last index, `[Z]` files changed - **Target Consumers**: AI agents, developers, CI pipelines --- ## Indexing Plan - [ ] **RI-PLAN-1.1 [Structure Scan]**: - **Scope**: Directory tree, focus area classification, framework detection - **Dependencies**: Repository access, .gitignore patterns, manifest files - **Output**: Hierarchical directory map with role annotations - [ ] **RI-PLAN-1.2 [Dependency Analysis]**: - **Scope**: Internal module graph, external dependency catalog, risk surface identification - **Dependencies**: Import resolution, package manifests, git history - **Output**: Dependency graph with fan-in/fan-out metrics, risk flags - [ ] **RI-PLAN-1.3 [Entry Point Mapping]**: - **Scope**: Application entry points, service boundaries, API surfaces - **Dependencies**: Framework initializers, main functions, route definitions - **Output**: Entry point registry with upstream/downstream dependencies - [ ] **RI-PLAN-1.4 [Change Hotspot Detection]**: - **Scope**: Git history analysis, churn metrics, logical coupling - **Dependencies**: Git log, file modification timestamps - **Output**: Hotspot ranking with risk scores - [ ] **RI-PLAN-1.5 [Index Generation]**: - **Scope**: `PROJECT_INDEX.md` and `PROJECT_INDEX.json` generation - **Dependencies**: All prior analysis outputs - **Output**: Validated index documents with freshness metadata --- ## Indexing Items ### Structure - [ ] **RI-ITEM-1.1 [Directory Tree Map]**: - **Type**: Structure - **Files**: `PROJECT_INDEX.md`, `PROJECT_INDEX.json` - **Description**: Full directory tree with depth-limited summaries, classified by role (source, test, config, docs, build, vendor). Include file counts and dominant types per directory. - [ ] **RI-ITEM-1.2 [Framework and Build Detection]**: - **Type**: Structure - **Files**: `PROJECT_INDEX.md` - **Description**: Identify language, framework, build system from manifest files. Detect monorepo structure if applicable. - [ ] **RI-ITEM-1.3 [Configuration Catalog]**: - **Type**: Structure - **Files**: `PROJECT_INDEX.md`, `PROJECT_INDEX.json` - **Description**: Catalog all configuration files (env, CI/CD, Docker, IaC) with purpose annotations. ### Entry Points - [ ] **RI-ITEM-2.1 [Application Entry Points]**: - **Type**: Entry Point - **Files**: `PROJECT_INDEX.md` - **Description**: Locate main functions, server bootstraps, CLI scripts, framework initializers. Annotate with file path, purpose, dependencies. - [ ] **RI-ITEM-2.2 [Service Boundaries]**: - **Type**: Entry Point - **Files**: `PROJECT_INDEX.md`, `PROJECT_INDEX.json` - **Description**: Map service boundaries in microservice/modular architectures. Document communication interfaces (REST, gRPC, message queues). - [ ] **RI-ITEM-2.3 [API Surface Documentation]**: - **Type**: Entry Point - **Files**: `PROJECT_INDEX.md` - **Description**: Document API routes, event handlers, message queue consumers as external-facing interaction surfaces. ### Dependencies - [ ] **RI-ITEM-3.1 [Internal Dependency Graph]**: - **Type**: Dependency - **Files**: `PROJECT_INDEX.json` - **Description**: Build adjacency list of module imports. Calculate fan-in, fan-out, instability index per module. - [ ] **RI-ITEM-3.2 [External Dependency Catalog]**: - **Type**: Dependency - **Files**: `PROJECT_INDEX.md`, `PROJECT_INDEX.json` - **Description**: List external dependencies with version constraints, license types, vulnerability status. Flag stale dependencies. - [ ] **RI-ITEM-3.3 [Anti-Pattern Detection]**: - **Type**: Dependency - **Files**: `PROJECT_INDEX.md` - **Description**: Identify circular dependencies, layer violations, inappropriate coupling between domains. ### Change Hotspots - [ ] **RI-ITEM-4.1 [Commit Frequency Analysis]**: - **Type**: Hotspot - **Files**: `PROJECT_INDEX.md` - **Description**: Rank files by commit frequency over 30/90/180-day windows. Cross-reference with file size and complexity. - [ ] **RI-ITEM-4.2 [Logical Coupling Detection]**: - **Type**: Hotspot - **Files**: `PROJECT_INDEX.md` - **Description**: Identify files frequently changed together without direct import relationships. - [ ] **RI-ITEM-4.3 [Knowledge Silo Risk]**: - **Type**: Hotspot - **Files**: `PROJECT_INDEX.md` - **Description**: Analyze author concentration per module. Flag single-author modules as bus-factor risks. ### Schema and Documents - [ ] **RI-ITEM-5.1 [README and Documentation Audit]**: - **Type**: Schema - **Files**: `PROJECT_INDEX.md` - **Description**: Locate all README files, note stale or missing ones. Discover ADRs, API specs, schema definitions. - [ ] **RI-ITEM-5.2 [Data Model Mapping]**: - **Type**: Schema - **Files**: `PROJECT_INDEX.md` - **Description**: Identify database migrations, schema definitions, and data model landscape. - [ ] **RI-ITEM-5.3 [Infrastructure Discovery]**: - **Type**: Schema - **Files**: `PROJECT_INDEX.md` - **Description**: Catalog CI/CD pipelines, Dockerfiles, IaC templates, and configuration schemas. ### Summary - [ ] **RI-ITEM-6.1 [Token-Efficient Summarization]**: - **Type**: Summary - **Files**: `PROJECT_INDEX.md` - **Description**: Produce compressed summaries at repository, module, and file levels. Target under 2000 tokens for compressed level. - [ ] **RI-ITEM-6.2 [Critical Files Section]**: - **Type**: Summary - **Files**: `PROJECT_INDEX.md` - **Description**: List top files by importance (entry points, core business logic, shared utilities). - [ ] **RI-ITEM-6.3 [Changelog Summary]**: - **Type**: Summary - **Files**: `PROJECT_INDEX.md` - **Description**: Compress recent changes into changelog with affected modules and change categories. --- ## Proposed Code Changes ### `PROJECT_INDEX.md` Structure ```markdown # Project Index: [REPOSITORY_NAME] ## Metadata - **Generated**: [TIMESTAMP] - **Commit Hash**: [HASH] - **Staleness Threshold**: [X] days - **Freshness Score**: [0-100] ## Repository Overview [2-3 sentence summary] ## Directory Structure [Tree with depth limits and role annotations] ## Entry Points | Path | Type | Purpose | Dependencies | |------|------|---------|--------------| ## Service Boundaries [Service map with communication patterns] ## Dependency Graph [Adjacency list or DOT format] ## External Dependencies | Package | Version | License | Status | Risk | |---------|---------|---------|--------|------| ## Change Hotspots | File | Commits (30d) | Commits (90d) | Risk Score | |------|---------------|---------------|------------| ## Critical Files [Ranked list with rationale] ## Recent Changes [Compressed changelog] ## Risk Surface [High-risk areas with combined metrics] ## Token Budget - **Compressed Summary**: [X] tokens - **Full Index**: [X] tokens - **Estimated Savings**: [X]% vs full repository ``` ### `PROJECT_INDEX.json` Schema ```json { "schema_version": "1.0", "metadata": { "generated_at": "ISO-8601", "commit_hash": "string", "staleness_threshold_days": 7, "freshness_score": 0-100, "repository": { "name": "string", "language": "string", "framework": "string", "total_files": 0, "total_lines": 0 } }, "directories": [ { "path": "string", "role": "source|test|config|docs|build|vendor", "file_count": 0, "dominant_types": ["string"] } ], "entry_points": [ { "path": "string", "type": "server|cli|worker|serverless", "purpose": "string", "dependencies": ["string"] } ], "services": [ { "name": "string", "entry_point": "string", "communication": ["rest|grpc|graphql|mq"], "dependencies": ["string"] } ], "dependency_graph": { "nodes": ["string"], "edges": [{"from": "string", "to": "string"}], "metrics": { "module": { "fan_in": 0, "fan_out": 0, "instability": 0.0 } } }, "external_dependencies": [ { "name": "string", "version": "string", "license": "string", "vulnerabilities": ["string"], "stale": false } ], "hotspots": [ { "file": "string", "commits_30d": 0, "commits_90d": 0, "risk_score": 0.0, "logical_coupling": ["string"] } ], "critical_files": [ { "path": "string", "importance": "high|medium|low", "rationale": "string" } ], "risk_surface": [ { "file": "string", "risks": ["string"], "recommendation": "string" } ], "token_estimates": { "compressed_summary": 0, "full_index": 0, "savings_percent": 0.0 } } ``` --- ## Commands ### Local Execution ```bash # 1. Check index freshness if [ -f PROJECT_INDEX.md ] && [ -f PROJECT_INDEX.json ]; then echo "Index exists - checking freshness" # Compare timestamps, count commits since last index git log --oneline --since="$(stat -c %y PROJECT_INDEX.md)" | wc -l else echo "Index missing - full re-index required" fi # 2. Scan repository structure find . -type f -not -path './.git/*' -not -path './node_modules/*' | wc -l find . -type d -not -path './.git/*' -not -path './node_modules/*' | sort # 3. Detect framework and build system ls package.json Cargo.toml go.mod pom.xml pyproject.toml 2>/dev/null # 4. Analyze git history for hotspots git log --pretty=format:'%H %an %ad %s' --date=short --since="90 days ago" | \ awk '{print $1}' | sort | uniq -c | sort -rn | head -20 # 5. Generate index documents # [INDEX_GENERATION_SCRIPT] > PROJECT_INDEX.md # [INDEX_GENERATION_SCRIPT] --json > PROJECT_INDEX.json # 6. Validate index python -m json.tool PROJECT_INDEX.json > /dev/null && echo "JSON valid" # Verify all paths exist while read -r path; do [ -f "$path" ] || echo "MISSING: $path" done < <(grep -oP '(?<=`)[^`]+\.(py|js|ts|go|rs|java|rb|php)' PROJECT_INDEX.md) ``` ### CI Pipeline Integration ```yaml # .github/workflows/index-repo.yml name: Index Repository on: push: branches: [main] schedule: - cron: '0 3 * * *' # Daily at 3 AM jobs: index: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # Full history for hotspot analysis - name: Run repository indexer run: | # [INDEX_GENERATION_SCRIPT] --output-dir . - name: Validate index run: | python -m json.tool PROJECT_INDEX.json # Verify no secrets in index grep -rE '(api[_-]?key|secret|password|token)' PROJECT_INDEX.md PROJECT_INDEX.json && exit 1 || true - name: Commit updated index run: | git config user.name "Index Bot" git config user.email "index@bot.local" git add PROJECT_INDEX.md PROJECT_INDEX.json git commit -m "chore: update repository index [skip ci]" git push ``` --- ## Quality Assurance Checklist - [ ] **RI-QA-1**: All file paths in the index resolve to existing repository files - [ ] **RI-QA-2**: JSON index conforms to the defined schema and parses without errors - [ ] **RI-QA-3**: Markdown index is human-readable with consistent heading hierarchy - [ ] **RI-QA-4**: Entry points and service boundaries are accurately identified and annotated - [ ] **RI-QA-5**: Dependency graph reflects actual codebase relationships without phantom edges - [ ] **RI-QA-6**: No sensitive data (secrets, keys, credentials) appears in any index output - [ ] **RI-QA-7**: Freshness metadata (timestamp, commit hash, staleness score) is recorded - [ ] **RI-QA-8**: Token count estimates are provided for each summary level - [ ] **RI-QA-9**: Change hotspots are identified using recent git history analysis - [ ] **RI-QA-10**: Circular dependencies and coupling anti-patterns are flagged explicitly --- ## Red Flag Assessment | Flag | Status | Notes | |------|--------|-------| | Missing entry points | [ ] | [Details] | | Orphaned directories | [ ] | [Details] | | Circular dependencies | [ ] | [Details] | | Knowledge silos | [ ] | [Details] | | Stale indexes | [ ] | [Details] | | Sensitive data in index | [ ] | [Details] | | Phantom references | [ ] | [Details] | | Monolithic entanglement | [ ] | [Details] | --- ## Execution Notes - **Scan Time Estimate**: [X] minutes - **Token Budget for Index**: [X] tokens (compressed) / [X] tokens (full) - **Estimated Savings vs Full Repository**: [X]% - **Next Scheduled Re-Index**: [DATE] (based on staleness threshold) - **Index Freshness Score**: [0-100] (ratio of unchanged files to total indexed)