feat: Introduce analyze Command for Deep Educational Codebase Analysis #6

Merged

gmgauthier merged 9 commits from feature/analyze_cmd into master 2026-03-28 16:11:39 +00:00

Conversation 0 Commits 9 Files Changed 9 +486

gmgauthier commented 2026-03-28 14:16:55 +00:00

Owner

Copy Link

Introduce analyze Command for Codebase Analysis

Description

This PR adds a new analyze command to Grokkit, enabling users to generate clean, educational Markdown reports that deeply analyze a codebase. The feature is designed as a didactic tool for learning developers, hobbyists, and teams onboarding to projects. It supports polyglot codebases through customizable, language-specific prompts (e.g., for Go, Python, C90, Rexx, Perl, etc.), automatically detecting the primary language and loading prompts from project-local or global locations.

Key highlights:

• Educational Focus: Reports include tech stack, module relationships, function references (with "what," "how," and "why"), data flows, and learning paths with gotchas.
• User Safety: Includes a preview of the generated report and requires confirmation before writing to disk (skippable with --yes).
• Extensibility: Prompts are developer-first, preferring project-local files for customization.
• Integration: Ties into existing internals like grok, git, linter, and logger, with minimal changes to core files.

This enhances Grokkit's value as a learning and exploration tool, complementing commands like review and lint.

Closes # [if applicable, link to any related issues].

Changes

• Added .grokkit/prompts/go.md:

  • A sample Go-specific prompt for generating structured Markdown reports. This serves as a template for other languages and can be customized per-project.

• Added cmd/analyze.go:

  • Implements the analyze Cobra command.
  • Handles flag parsing (e.g., --dir, --output, --yes, --model).
  • Discovers source files, detects primary language, loads prompts, builds project context, calls the Grok API, previews the report, and writes output transactionally.
  • Includes helper functions like discoverSourceFiles, previewLines, and buildProjectContext for file walking, previewing, and context building.

• Modified cmd/root.go:

  • Added analyzeCmd to the root command for CLI integration.

• Added docs/user-guide/analyze.md:

  • Comprehensive user documentation, including usage examples, options, prompt discovery, adding new language support, safety features, best practices, and an example workflow.

• Modified docs/user-guide/index.md:

  • Added a link to the new analyze.md in the command list.

• Added internal/linter/language.go:

  • New functions DetectPrimaryLanguage (counts languages across files and picks the dominant one, with Go bias) and SupportedLanguages (lists known languages for future use).

• Added internal/prompts/analyze.go:

  • LoadAnalysisPrompt function to search for and load language-specific prompts, preferring project-local over global paths. Returns an error if none found for clear user feedback.

No breaking changes; this is a pure addition. Code follows existing style (e.g., using package-level logger, Cobra patterns, and error handling).

Motivation

Grokkit already excels at targeted tasks like linting and reviews, but users often need a high-level, educational overview of an entire project—especially when learning a new codebase, language, or legacy system (e.g., C90 or Rexx). This command fills that gap by:

• Providing structured, beginner-friendly reports that explain design rationale and pitfalls.
• Supporting multiple languages via extensible prompts, making Grokkit more versatile for polyglot repos.
• Encouraging best practices like transactional outputs (preview + confirm) to avoid unwanted file writes.
• Leveraging Grok's AI for insightful analysis without requiring users to craft queries manually.

This aligns with Grokkit's goal of being a helpful, developer-focused CLI, and the prompt system empowers users to tailor it (e.g., focusing on security for C or concurrency for Go).

Testing Notes

Prerequisites

• Ensure Grokkit is built/installed (e.g., go build or go install).
• Have a Grok API key configured (via ~/.config/grokkit/config.yaml or env vars).
• Test in a Git repo for full metadata; non-Git dirs will show a warning but still work.

Manual Testing Steps

1. Basic Run:

   • In a Go project directory: grokkit analyze
   • Verify: Detects "go" language, loads prompt (from .grokkit/prompts/go.md if present), generates report preview, prompts for confirmation, and writes to analyze.md.
   • Check report contents: Matches the exact sections (e.g., # Project Analysis, ## Tech Stack & Layout).

2. Custom Directory and Output:

   • grokkit analyze --dir ./path/to/project --output custom-report.md --yes
   • Verify: Analyzes the specified dir, skips confirmation, writes to custom file. Use cat custom-report.md to inspect.

3. Stdout Output:

   • grokkit analyze --output -
   • Verify: Prints report to console without writing to disk.

4. Language Detection:

   • In a mixed repo (e.g., Go + Python files): Run grokkit analyze.
   • Verify: Picks dominant language (biases toward Go if present). If no prompt, shows actionable error with paths to create one.
   • Test new language: Create ~/.config/grokkit/prompts/python.md with sample content, run in a Python project, confirm it loads.

5. Edge Cases:

   • Empty dir: grokkit analyze --dir /empty → Exits with "No supported source files found".
   • No prompt: Remove prompts → Shows error with creation instructions.
   • Non-Git dir: Warns about limited Git metadata but proceeds.
   • Large report: Use --model grok-4-mini for speed; verify streaming works without live output (uses StreamSilent).

6. Documentation:

   • Build and view docs (if using a doc viewer): Ensure analyze.md renders correctly and links work in index.md.

Automated Tests (if added in future)

• This PR doesn't include new tests, but suggest adding unit tests for:
  • DetectPrimaryLanguage (e.g., mock file lists returning "go", "python", "unknown").
  • LoadAnalysisPrompt (mock fs for local/global paths, error on missing).
  • Integration: Mock Grok API responses to test full command flow.

# Introduce `analyze` Command for Codebase Analysis ## Description This PR adds a new `analyze` command to Grokkit, enabling users to generate clean, educational Markdown reports that deeply analyze a codebase. The feature is designed as a didactic tool for learning developers, hobbyists, and teams onboarding to projects. It supports polyglot codebases through customizable, language-specific prompts (e.g., for Go, Python, C90, Rexx, Perl, etc.), automatically detecting the primary language and loading prompts from project-local or global locations. Key highlights: - **Educational Focus**: Reports include tech stack, module relationships, function references (with "what," "how," and "why"), data flows, and learning paths with gotchas. - **User Safety**: Includes a preview of the generated report and requires confirmation before writing to disk (skippable with `--yes`). - **Extensibility**: Prompts are developer-first, preferring project-local files for customization. - **Integration**: Ties into existing internals like `grok`, `git`, `linter`, and `logger`, with minimal changes to core files. This enhances Grokkit's value as a learning and exploration tool, complementing commands like `review` and `lint`. Closes # [if applicable, link to any related issues]. ## Changes - **Added `.grokkit/prompts/go.md`**: - A sample Go-specific prompt for generating structured Markdown reports. This serves as a template for other languages and can be customized per-project. - **Added `cmd/analyze.go`**: - Implements the `analyze` Cobra command. - Handles flag parsing (e.g., `--dir`, `--output`, `--yes`, `--model`). - Discovers source files, detects primary language, loads prompts, builds project context, calls the Grok API, previews the report, and writes output transactionally. - Includes helper functions like `discoverSourceFiles`, `previewLines`, and `buildProjectContext` for file walking, previewing, and context building. - **Modified `cmd/root.go`**: - Added `analyzeCmd` to the root command for CLI integration. - **Added `docs/user-guide/analyze.md`**: - Comprehensive user documentation, including usage examples, options, prompt discovery, adding new language support, safety features, best practices, and an example workflow. - **Modified `docs/user-guide/index.md`**: - Added a link to the new `analyze.md` in the command list. - **Added `internal/linter/language.go`**: - New functions `DetectPrimaryLanguage` (counts languages across files and picks the dominant one, with Go bias) and `SupportedLanguages` (lists known languages for future use). - **Added `internal/prompts/analyze.go`**: - `LoadAnalysisPrompt` function to search for and load language-specific prompts, preferring project-local over global paths. Returns an error if none found for clear user feedback. No breaking changes; this is a pure addition. Code follows existing style (e.g., using package-level logger, Cobra patterns, and error handling). ## Motivation Grokkit already excels at targeted tasks like linting and reviews, but users often need a high-level, educational overview of an entire project—especially when learning a new codebase, language, or legacy system (e.g., C90 or Rexx). This command fills that gap by: - Providing structured, beginner-friendly reports that explain design rationale and pitfalls. - Supporting multiple languages via extensible prompts, making Grokkit more versatile for polyglot repos. - Encouraging best practices like transactional outputs (preview + confirm) to avoid unwanted file writes. - Leveraging Grok's AI for insightful analysis without requiring users to craft queries manually. This aligns with Grokkit's goal of being a helpful, developer-focused CLI, and the prompt system empowers users to tailor it (e.g., focusing on security for C or concurrency for Go). ## Testing Notes ### Prerequisites - Ensure Grokkit is built/installed (e.g., `go build` or `go install`). - Have a Grok API key configured (via `~/.config/grokkit/config.yaml` or env vars). - Test in a Git repo for full metadata; non-Git dirs will show a warning but still work. ### Manual Testing Steps 1. **Basic Run**: - In a Go project directory: `grokkit analyze` - Verify: Detects "go" language, loads prompt (from `.grokkit/prompts/go.md` if present), generates report preview, prompts for confirmation, and writes to `analyze.md`. - Check report contents: Matches the exact sections (e.g., # Project Analysis, ## Tech Stack & Layout). 2. **Custom Directory and Output**: - `grokkit analyze --dir ./path/to/project --output custom-report.md --yes` - Verify: Analyzes the specified dir, skips confirmation, writes to custom file. Use `cat custom-report.md` to inspect. 3. **Stdout Output**: - `grokkit analyze --output -` - Verify: Prints report to console without writing to disk. 4. **Language Detection**: - In a mixed repo (e.g., Go + Python files): Run `grokkit analyze`. - Verify: Picks dominant language (biases toward Go if present). If no prompt, shows actionable error with paths to create one. - Test new language: Create `~/.config/grokkit/prompts/python.md` with sample content, run in a Python project, confirm it loads. 5. **Edge Cases**: - Empty dir: `grokkit analyze --dir /empty` → Exits with "No supported source files found". - No prompt: Remove prompts → Shows error with creation instructions. - Non-Git dir: Warns about limited Git metadata but proceeds. - Large report: Use `--model grok-4-mini` for speed; verify streaming works without live output (uses `StreamSilent`). 6. **Documentation**: - Build and view docs (if using a doc viewer): Ensure `analyze.md` renders correctly and links work in `index.md`. ### Automated Tests (if added in future) - This PR doesn't include new tests, but suggest adding unit tests for: - `DetectPrimaryLanguage` (e.g., mock file lists returning "go", "python", "unknown"). - `LoadAnalysisPrompt` (mock fs for local/global paths, error on missing). - Integration: Mock Grok API responses to test full command flow.

gmgauthier added 8 commits 2026-03-28 14:16:55 +00:00

feat(cmd): add analyze command for project analysis ... 78379aa557

Introduces a new Cobra command `analyze` that performs deep project analysis,
discovers files, builds context, streams to Grok for report generation, and
handles output with confirmation.

feat(analyze): implement educational project analysis with language prompts ... b24b86723b

- Add Go-specific analysis prompt in .grokkit/prompts/go.md
- Expand cmd/analyze.go to discover files, detect language, load prompts, build context, generate report via Grok, and handle output with preview/confirmation
- Integrate analyzeCmd into root command
- Introduce internal/linter/language.go for primary language detection
- Add internal/prompts/analyze.go for loading analysis prompts from project or global locations

refactor(analysis): refine prompts, language detection, and context building ... 09119ded37

- Updated Go analysis prompt for clarity, structure, and educational focus.
- Improved buildProjectContext to include shallow key files and cleaner Git remote handling.
- Implemented DetectPrimaryLanguage with counting logic and Go bias; added SupportedLanguages.
- Enhanced LoadAnalysisPrompt with better language handling, fallbacks, and error clarity.

fix(analyze): correct config, logger, and git usage in analyze command ... fd033b03c7

- Fix config.GetModel to use command name and flag
- Switch to package-level logger functions
- Update git.IsRepo to take no arguments
- Simplify linter language detection comments
- Adjust Grok client creation to NewClient().StreamSilent
- Add error handling for confirmation input
- Remove unnecessary imports and refine comments in linter

refactor(analyze): improve file discovery and project context in analyze command ... 4084315dc1

- Enhance discoverSourceFiles to skip additional noise directories like "build" and "dist" while descending into source directories.
- Update safety check to use package-level logger without .Get().
- Refine buildProjectContext with better labeling and consistent git remote handling.
- Minor comment and string adjustments for clarity.

feat(analyze): add project name inference for Go analysis prompts ... 4549ab5589

- Modify Go prompt to include instruction for inferring project name from directory or go.mod.
- Update analyze command to infer project name from directory base and replace placeholder in prompt content.
- Enhance prompt formatting with bold text and rephrased sections for clarity.

docs(user-guide): add guide for analyze command ... db184bb931

Introduced a new documentation page `analyze.md` detailing the `analyze` command, including usage, options, prompt discovery, language support, safety features, best practices, and an example workflow. Updated `index.md` to include a link to the new guide.

chore(todo): mark analyze-command as completed ... ba11717476

Moves the task file from queued to completed directory.

gmgauthier added 1 commit 2026-03-28 14:32:55 +00:00

docs(analyze): add project analysis Markdown report and refine AI prompt ... 7e5cb7c4d7

- Introduce analyze.md with comprehensive breakdown of Grokkit project, including tech stack, structure, APIs, data flow, and learning path.
- Update cmd/analyze.go to include detected language in user prompt for more targeted AI analysis.

gmgauthier merged commit 5cb84f44bb into master 2026-03-28 16:11:39 +00:00

gmgauthier referenced this issue from a commit 2026-03-28 16:11:40 +00:00

Merge pull request 'feat: Introduce `analyze` Command for Deep Educational Codebase Analysis' (#6) from feature/analyze_cmd into master

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No Label

Milestone

Clear milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

No Assignees

1 Participants

Notifications

Subscribe

Due Date

The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: gmgauthier/grokkit#6

No description provided.