36 lines
2.0 KiB
Markdown
36 lines
2.0 KiB
Markdown
|
# Feature: grokkit analyze — Deep project investigation & didactic report
|
||
|
|
|
||
|
|
**Description**
|
||
|
|
New command `grokkit analyze` that takes a repository root (default: `.`), performs a full static + semantic analysis, and outputs a single, readable Markdown report.
|
||
|
|
|
||
|
|
The report is educational: it explains the tech stack, how every public function/method works, why it exists, module inter-relationships, and (when relevant) object ↔ DB schema mappings.
|
||
|
|
|
||
|
|
**Acceptance Criteria**
|
||
|
|
- [ ] Cobra command `analyze` in `cmd/analyze.go`
|
||
|
|
- [ ] Supports `--dir`, `--output` (stdout / file), `--model`, `--yes` (skip confirmation)
|
||
|
|
- [ ] Uses existing `internal/linter` for language detection + file discovery
|
||
|
|
- [ ] Uses `internal/grok` (StreamSilent + structured prompt) for the heavy lifting
|
||
|
|
- [ ] Transactional: always shows preview of the generated report + `y/N` confirmation before writing to disk (unless `--yes`)
|
||
|
|
- [ ] Full user-guide doc: `docs/user-guide/analyze.md` (usage, safety, best practices, example output)
|
||
|
|
- [ ] Updates to `docs/user-guide/index.md`, main README, and `docs/index.md`
|
||
|
|
- [ ] Unit tests + integration test that runs on a temp test repo
|
||
|
|
- [ ] Follows architecture: thin cmd layer, structured logging, Git safety, no new heavy deps
|
||
|
|
- [ ] Report sections (enforced by system prompt):
|
||
|
|
- Tech Stack & Project Layout
|
||
|
|
- Module / Package Overview + inter-relationships
|
||
|
|
- Function/Method Reference (how it works + why it was included)
|
||
|
|
- Object ↔ DB Schema Mappings (if applicable)
|
||
|
|
- Suggested Learning Path / Gotchas
|
||
|
|
|
||
|
|
**Implementation Plan**
|
||
|
|
1. Add command skeleton + flags (model after `review.go` + `pr-describe.go`)
|
||
|
|
2. File discovery + language batching (reuse `internal/linter`)
|
||
|
|
3. Build rich context prompt (project tree + key files + git metadata)
|
||
|
|
4. Single Grok call (or smart multi-call if project is huge) → clean Markdown
|
||
|
|
5. Diff-style preview + confirmation (even for stdout, show first ~50 lines)
|
||
|
|
6. Write / print report
|
||
|
|
7. Docs + tests
|
||
|
|
|
||
|
|
**Priority**
|
||
|
|
High — this is the exact “didactic training tool” the project has been missing.
|