81 lines
2.6 KiB
Markdown
81 lines
2.6 KiB
Markdown
# Codebase Genome Pipeline
|
|
|
|
Issue: `timmy-home#665`
|
|
|
|
This pipeline gives Timmy a repeatable way to generate a deterministic `GENOME.md` for any repository and rotate through the org nightly.
|
|
|
|
## What landed
|
|
|
|
- `pipelines/codebase_genome.py` — static analyzer that writes `GENOME.md`
|
|
- `pipelines/codebase-genome.py` — thin CLI wrapper matching the expected pipeline-style entrypoint
|
|
- `scripts/codebase_genome_nightly.py` — org-aware nightly runner that selects the next repo, updates a local checkout, and writes the genome artifact
|
|
- `scripts/codebase_genome_status.py` — rollup/status reporter for artifact coverage, duplicate paths, and next uncovered repo
|
|
- `GENOME.md` — generated analysis for `timmy-home` itself
|
|
|
|
## Genome output
|
|
|
|
Each generated `GENOME.md` includes:
|
|
|
|
- project overview and repository size metrics
|
|
- Mermaid architecture diagram
|
|
- entry points and API surface
|
|
- data flow summary
|
|
- key abstractions from Python source
|
|
- test coverage gaps
|
|
- security audit findings
|
|
- dead code candidates
|
|
- performance bottleneck analysis
|
|
|
|
## Single-repo usage
|
|
|
|
```bash
|
|
python3 pipelines/codebase_genome.py \
|
|
--repo-root /path/to/repo \
|
|
--repo-name Timmy_Foundation/some-repo \
|
|
--output /path/to/repo/GENOME.md
|
|
```
|
|
|
|
The hyphenated wrapper also works:
|
|
|
|
```bash
|
|
python3 pipelines/codebase-genome.py --repo-root /path/to/repo --repo Timmy_Foundation/some-repo
|
|
```
|
|
|
|
## Nightly org rotation
|
|
|
|
Dry-run the next selection:
|
|
|
|
```bash
|
|
python3 scripts/codebase_genome_nightly.py --dry-run
|
|
```
|
|
|
|
Run one real pass:
|
|
|
|
```bash
|
|
python3 scripts/codebase_genome_nightly.py \
|
|
--org Timmy_Foundation \
|
|
--workspace-root ~/timmy-foundation-repos \
|
|
--output-root ~/.timmy/codebase-genomes \
|
|
--state-path ~/.timmy/codebase_genome_state.json
|
|
```
|
|
|
|
Behavior:
|
|
|
|
1. fetches the current repo list from Gitea
|
|
2. selects the next repo after the last recorded run
|
|
3. clones or fast-forwards the local checkout
|
|
4. writes `GENOME.md` into the configured output tree
|
|
5. updates the rotation state file
|
|
|
|
## Example cron entry
|
|
|
|
```cron
|
|
30 2 * * * cd ~/timmy-home && /usr/bin/env python3 scripts/codebase_genome_nightly.py --org Timmy_Foundation --workspace-root ~/timmy-foundation-repos --output-root ~/.timmy/codebase-genomes --state-path ~/.timmy/codebase_genome_state.json >> ~/.timmy/logs/codebase_genome_nightly.log 2>&1
|
|
```
|
|
|
|
## Limits and follow-ons
|
|
|
|
- the generator is deterministic and static; it does not hallucinate architecture, but it also does not replace a full human review pass
|
|
- nightly rotation handles genome generation; auto-generated test expansion remains a separate follow-on lane
|
|
- large repos may still need a second-pass human edit after the initial genome artifact lands
|