113 lines
4.2 KiB
Markdown
113 lines
4.2 KiB
Markdown
|
# 🔎 Analyze Guide
|
|||
|
|
|
|||
|
|
The `analyze` command performs a deep investigation of a codebase and produces a clean, educational Markdown report. It is designed as a **didactic training tool** for learning developers, hobbyists, and anyone onboarding to a new project.
|
|||
|
|
|
|||
|
|
### Why use Analyze?
|
|||
|
|
|
|||
|
|
- **Educational Focus**: Explains not just *what* the code does, but *how* each function/method works and *why* it was included.
|
|||
|
|
- **Polyglot Support**: Works for Go, Python, Java, C90, Rexx, Perl, JavaScript/TypeScript, and more via custom prompts.
|
|||
|
|
- **Project-Aware**: Includes tech stack, module relationships, object ↔ data flow, and suggested learning paths.
|
|||
|
|
- **Transactional**: Always shows a preview and requires explicit confirmation before writing (unless `--yes`).
|
|||
|
|
|
|||
|
|
### Usage
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Analyze current directory (preview + confirmation)
|
|||
|
|
grokkit analyze
|
|||
|
|
|
|||
|
|
# Analyze a specific directory
|
|||
|
|
grokkit analyze --dir ./legacy-c90-project
|
|||
|
|
|
|||
|
|
# Write to custom file or stdout
|
|||
|
|
grokkit analyze --output my-analysis.md
|
|||
|
|
grokkit analyze --output - # stdout only
|
|||
|
|
|
|||
|
|
# Skip confirmation (useful in scripts/CI)
|
|||
|
|
grokkit analyze --yes
|
|||
|
|
|
|||
|
|
# Use a different model
|
|||
|
|
grokkit analyze --model grok-4
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
|
|||
|
|
### Options
|
|||
|
|
|
|||
|
|
| Flag | Short | Description | Default |
|
|||
|
|
|----------|-------|----------------------------|-------------------|
|
|||
|
|
| --dir | | Repository root to analyze | Current directory |
|
|||
|
|
| --output | -o | Output file (- for stdout) | analyze.md |
|
|||
|
|
| --yes | -y | Skip confirmation prompt | false |
|
|||
|
|
| --model | -m | Override model | from config |
|
|||
|
|
|
|||
|
|
|
|||
|
|
### Prompt Discovery (Automatic & Developer-First)
|
|||
|
|
|
|||
|
|
Grokkit automatically locates a language-specific system prompt using this exact order:
|
|||
|
|
|
|||
|
|
1. `{PROJECT_ROOT}/.grokkit/prompts/{language}.md` ← preferred (project-specific)
|
|||
|
|
2. `~/.config/grokkit/prompts/{language}.md` ← global fallback
|
|||
|
|
|
|||
|
|
Language is detected automatically via `internal/linter`.
|
|||
|
|
|
|||
|
|
If no prompt is found for the detected language, Grokkit prints a clear, actionable error message with exact paths where to create the file and exits without running analysis.
|
|||
|
|
|
|||
|
|
Supported languages (out of the box via the linter): `go`, `python`, `javascript`, `typescript`, `java`, `c`, `cpp`, `rust`, `ruby`, `perl`, `shell`, and others.
|
|||
|
|
|
|||
|
|
### Adding Support for New Languages (C90, Rexx, Perl, etc.)
|
|||
|
|
|
|||
|
|
1. Create a new prompt file in .grokkit/prompts/ (or globally in ~/.config/grokkit/prompts/).
|
|||
|
|
2. Name it after the language: `c90.md`, `rexx.md`, `perl.md`, etc.
|
|||
|
|
3. Make it educational and specific to the language’s idioms.
|
|||
|
|
|
|||
|
|
Example starter for c90.md:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
You are an expert C90 educator helping a hobbyist or learning developer understand legacy C code.
|
|||
|
|
|
|||
|
|
Generate a single, clean, educational Markdown report with these exact sections:
|
|||
|
|
|
|||
|
|
# Project Analysis: [Inferred Project Name]
|
|||
|
|
|
|||
|
|
## Tech Stack & Layout
|
|||
|
|
...
|
|||
|
|
|
|||
|
|
## Function & Method Reference
|
|||
|
|
For every function:
|
|||
|
|
- What it does
|
|||
|
|
- How it works (memory management, K&R vs ANSI style, etc.)
|
|||
|
|
- Why it exists
|
|||
|
|
|
|||
|
|
## Learning Path & Gotchas
|
|||
|
|
...
|
|||
|
|
Be precise, encouraging, and focus on C90 constraints and common pitfalls.
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Safety Features
|
|||
|
|
|
|||
|
|
* Preview: Shows the first ~60 lines of the generated report before writing.
|
|||
|
|
* Confirmation: Requires explicit y/N unless --yes is used.
|
|||
|
|
* No Auto-Write: Nothing is saved to disk without user approval.
|
|||
|
|
* Git-Friendly: The generated analyze.md can be reviewed with git diff, reverted with git restore, or committed as documentation.
|
|||
|
|
|
|||
|
|
### Best Practices
|
|||
|
|
|
|||
|
|
* Run grokkit analyze early when exploring a new codebase.
|
|||
|
|
* Customize the prompt in `.grokkit/prompts/` for your specific learning goals (e.g., focus on security for C, concurrency for Go, or monadic patterns for Rexx/Perl).
|
|||
|
|
* Combine with other commands: use `analyze` for high-level understanding, then `review` for deeper logic critique, or `lint` for style issues.
|
|||
|
|
* Commit the generated report if it helps team onboarding or personal reference.
|
|||
|
|
* For very large projects, consider running with a faster model (--model grok-4-mini) or limiting scope with a project-specific prompt.
|
|||
|
|
|
|||
|
|
### Example Workflow
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
# 1. Analyze the project
|
|||
|
|
grokkit analyze
|
|||
|
|
|
|||
|
|
# 2. Review the generated report
|
|||
|
|
less analyze.md
|
|||
|
|
|
|||
|
|
# 3. Commit as documentation (optional)
|
|||
|
|
git add analyze.md
|
|||
|
|
grokkit commit
|
|||
|
|
```
|