diff --git a/.womm/bronze.svg b/.womm/bronze.svg new file mode 100644 index 0000000..63284c1 --- /dev/null +++ b/.womm/bronze.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + ★ + ★ + ★ + ★ + + + + + + WORKS ON MY MACHINE + + + + + + CERTIFIED + + + + + + + + + + + WOMM + + + + + + BRONZE + + + 2026-04-02 + + + + + + + diff --git a/.womm/womm-certificate.txt b/.womm/womm-certificate.txt new file mode 100644 index 0000000..d091b1a --- /dev/null +++ b/.womm/womm-certificate.txt @@ -0,0 +1,110 @@ + ================================================================ + WOMM CERTIFICATE OF COMPLIANCE + WOMM-STD-001:2026 + ================================================================ + + Certificate Number: WOMM-20260402172447-2462 + Date of Issuance: 2026-04-02 17:24:47 + Standard: WOMM-STD-001:2026, First Edition + + ---------------------------------------------------------------- + PROJECT INFORMATION + ---------------------------------------------------------------- + + Project Name: grokkit + Project Path: /data/Projects/grokkit + Certification Level: BRONZE (It Compiles) + + ---------------------------------------------------------------- + CERTIFICATION AUTHORITY + ---------------------------------------------------------------- + + Certifying Machine: plato + Certifying User: gmgauthier + Operating System: Linux 6.17.0-111019-tuxedo + Python Version: 3.12.3 + + This certification was performed on the above machine and is + valid exclusively for this machine in its current configuration, + including all running processes, environment variables, and the + certifier's current emotional state. + + ---------------------------------------------------------------- + AUDIT TRAIL + ---------------------------------------------------------------- + + | Check | Result | Detail | + |------------------------------------------|--------|--------| + | Project directory exists | PASS | Project directory +located. We're off to a strong start. | +| Contains source code | PASS | Source files detected. +This is, in fact, a software project. | +| Python syntax check | PASS | No Python files to check. +Blissful ignorance achieved. | +| Test suite exists | FAIL | No test suite found. Bold +strategy. | +| Tests pass | FAIL | Tests failed. +/usr/bin/python: No module named pytest | +| README exists | PASS | README found. +Documentation: the thought that counts. | +| No TODO/FIXME/HACK comments | FAIL | Found markers in: +testgen_test.go:20, testgen.go:216, testgen.go:218, testgen.go:223, +testgen.go:225. The guilt is documented. | +| CI configuration exists | FAIL | No CI configuration found. +You are the CI. | +| Git working tree is clean | FAIL | Uncommitted changes +detected. Living dangerously. | + + ---------------------------------------------------------------- + DECLARATION + ---------------------------------------------------------------- + + I, gmgauthier@plato, do hereby certify that the software + project "grokkit" has been evaluated in accordance + with WOMM-STD-001:2026 and has achieved: + + *** WOMM BRONZE CERTIFICATION *** + + This certification is granted under the following conditions: + + 1. The software was observed to work on my machine. + 2. No guarantee is made regarding any other machine. + 3. This certificate is void if anyone asks "are you sure?" + 4. Validity expires upon the next git pull, dependency update, + or passage of more than 24 hours. + + ---------------------------------------------------------------- + SIGNATURES + ---------------------------------------------------------------- + + Certified by: + + ___________________________ + gmgauthier + plato + 2026-04-02 + + Witnessed by: + + ___________________________ + /dev/null + (The Void) + + + Approved by the WOMM Standards Committee: + + ___________________________ + The Committee + (Quorum: 1) + + + ================================================================ + This document was generated in compliance with WOMM-STD-001:2026 + "Works On My Machine" Certification Standard + First Edition, 2026-04-02 + + Copyright 2026 The WOMM Standards Committee. + All rights reserved, except the right to guarantee + it works on your machine. + ================================================================ + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..93b1f5e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,87 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Grokkit is a Go CLI that integrates the xAI Grok API with git workflows. It provides AI-assisted chat, file editing, commit message generation, multi-language linting, test generation, documentation, and automated todo workflows. The core philosophy is "The Developer Is The Agent" — the LLM enhances rather than replaces developer judgment. + +## Commands + +```bash +make build # Build optimized binary to build/grokkit (with ldflags: version, commit, builddate) +make install # Build + install to ~/.local/bin +make test # Run all tests with -v -race +make test-cover # Generate HTML coverage report at build/coverage.html +make test-agent # Run only agent tests +make lint # Run golangci-lint (matches CI) +make clean # Remove build/ directory +``` + +To run a single test: +```bash +go test -run TestFunctionName ./cmd/... +go test -run TestFunctionName ./internal/grok/... +``` + +Required env var: `XAI_API_KEY=sk-...` + +## Architecture + +``` +main.go → cmd.Execute() +cmd/ Cobra subcommands (~40 files). Each command: parse flags → load config → call internal packages → stream output +config/ Viper config from ~/.config/grokkit/config.toml; resolves model aliases; CLI flags > env > file > defaults +internal/ + grok/ HTTP client with SSE streaming; AIClient interface for testability + git/ os/exec wrapper around git commands; GitRunner interface + linter/ Detects language by extension, runs available linters, supports 9 languages + errors/ Domain-specific error types (GitError, APIError, etc.) + prompts/ AI prompt construction + recipe/ Loads and executes transactional markdown workflow recipes + todo/ Task tracking + workon/ Automated branch+plan+execute workflow + logger/ slog facade; JSON to ~/.config/grokkit/grokkit.log +``` + +Key interfaces in `internal/grok/interface.go` (`AIClient`) and `internal/git/interface.go` (`GitRunner`) enable dependency injection for tests. + +The typical command flow: CLI flags parsed → `config.Load()` → build prompt → `grok.Client.Stream()` (SSE) → display streamed output. + +## Code Conventions + +- Go 1.24.2 +- Use `errors.Is`/`errors.Join`, `slices`, `maps` packages (modern Go) +- Table-driven tests with `t.Parallel()` and `t.Run()` +- Interface-based design for external dependencies (API, git) +- Structured logging via `internal/logger` (not fmt.Println for errors) +- Coverage target: >70% for internal packages + +## Testing Notes + +These are not unit-tested (require integration or E2E): +- Cobra command execution paths +- Terminal input (Scanln) +- API SSE streaming (would need mock HTTP server) +- `os.Exit()` paths + +## Configuration + +`~/.config/grokkit/config.toml`: +```toml +default_model = "grok-4" +temperature = 0.7 +timeout = 60 + +[aliases] +fast = "grok-4-1-fast-non-reasoning" + +[commands.lint.model] +"model" = "grok-4-1-fast-non-reasoning" +``` + +Model resolution: `--model` flag → config alias expansion → literal model name. + +## CI + +Gitea CI (`.gitea/workflows/ci.yml`): test → lint → build. golangci-lint v2.1.6. Release workflow builds multi-platform binaries with SHA256 checksums. diff --git a/README.md b/README.md index c9677f6..577196a 100644 --- a/README.md +++ b/README.md @@ -256,4 +256,6 @@ Error: Request failed: context deadline exceeded --- -**Made with ❤️ using Grok AI** \ No newline at end of file +**Made with ❤️ using Grok AI** + +THIS PROJECT IS [WOMM CERTIFIED](.womm/womm-certificate.txt) ![BRONZE-BADGE](.womm/bronze.svg) \ No newline at end of file diff --git a/docs/developer-guide/TEST-COVERAGE.md b/docs/developer-guide/TEST-COVERAGE.md new file mode 100644 index 0000000..2fd912e --- /dev/null +++ b/docs/developer-guide/TEST-COVERAGE.md @@ -0,0 +1,81 @@ +# Test Coverage Assessment + +**Date:** 2026-04-02 +**Scope:** All packages in `cmd/`, `internal/`, and `config/` +**Test files reviewed:** 32 across 12 packages + +--- + +## Overall: ~60% unit / ~20% integration + +The pattern is consistent: **pure helper functions are well-tested; the actual command execution paths are mostly not**. + +--- + +## Per-Package Breakdown + +| Package | Est. Coverage | Notes | +|---|---|---| +| `internal/logger/` | ~85% | Comprehensive public API coverage | +| `internal/prompts/` | ~85% | All load paths + fallback covered | +| `internal/errors/` | ~80% | Error types + unwrapping covered | +| `internal/todo/` | ~80% | Bootstrap idempotency solid | +| `internal/linter/` | ~75% | Language detection strong; output parsing weak | +| `config/` | ~75% | Config getters good; file-load errors not tested | +| `internal/workon/` | ~70% | State transitions good; `Run()` itself untested | +| `internal/git/` | ~70% | Real git integration, good core coverage | +| `internal/grok/` | ~60% | Streaming + SSE parsing tested; error paths absent | +| `internal/version/` | ~50% | Just variable presence check | +| `internal/recipe/` | ~50% | Loading tested; execution engine (`Run()`, `refactorFiles()`, `handleApplyStep()`) entirely untested | +| `cmd/` | ~25–35% | Message builders tested; nearly all `run*()` functions untested | + +--- + +## What's Systematically Untested + +**Command execution** — Most `run*()` functions in `cmd/` have zero direct tests: +- `runAgent()`, `runChat()`, `runQuery()`, `runRecipe()`, `runTestgen()`, `runWorkon()`, `runChangelogCommand()`, `runDocs()` + +**API error scenarios** — The grok client has no tests for: HTTP errors, rate limits, auth failures, malformed SSE chunks, timeouts, or stream cancellation. + +**Recipe execution** — `internal/recipe/` tests only YAML loading. The entire execution side (`Run`, `refactorFiles`, `handleApplyStep`, `executeReadOnlyShell`) is untouched. + +**User interaction** — All interactive confirmation/prompt flows are untested. No mock stdin anywhere. + +**File system errors** — Read-only paths, permission failures, disk full — none tested. + +--- + +## Highest-Impact Gaps + +1. `internal/recipe/` — execution engine is production code with zero test coverage +2. `internal/grok/` — error path coverage missing entirely for a network client +3. `cmd/agent.go`, `cmd/chat.go`, `cmd/query.go` — core UX features without tests +4. `config/` — file parsing errors and env var overrides not tested + +--- + +## Strengths + +- Good use of `t.TempDir()` for isolation +- Real git integration in `internal/git/` tests (not mocked) +- Mock injection via function variables (git runner, API client) makes testing feasible +- `t.Parallel()` used consistently where appropriate +- Error type chain verification (`errors.Is`) is present + +## Weaknesses + +- The "Live" test pattern (`TestScaffoldCmd_Live`) uses `testing.Short()` logic inconsistently — it's gated but the semantics are inverted from convention +- No benchmark tests anywhere +- No CI separation between unit and integration tests — "live" tests quietly depend on environment +- Mocking strategy is inconsistent across packages (some use testify mocks, some manual function variables) + +--- + +## Priority Recommendations + +**High:** Add tests for `internal/recipe/` execution, grok client error scenarios, and `runAgent()`/`runChat()`/`runQuery()`. + +**Medium:** Test `config/` file-load failure paths, git error scenarios (uninitialized repo), and file permission errors. + +**Low:** Standardize the Live test pattern, add benchmarks for SSE streaming, add concurrent operation tests.