docs: add WOMM certification badge and developer guides
- Add WOMM bronze certification SVG and text certificate - Add CLAUDE.md for AI coding guidance - Update README.md with certification badge - Add TEST-COVERAGE.md in docs/developer-guide
This commit is contained in:
parent
071568b37b
commit
c49f6d84ef
76
.womm/bronze.svg
Normal file
76
.womm/bronze.svg
Normal file
@ -0,0 +1,76 @@
|
|||||||
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" width="400" height="400">
|
||||||
|
<defs>
|
||||||
|
<style>
|
||||||
|
.seal-text { font-family: 'Georgia', 'EB Garamond', serif; font-weight: 700; }
|
||||||
|
</style>
|
||||||
|
</defs>
|
||||||
|
|
||||||
|
<!-- Outer ring -->
|
||||||
|
<circle cx="200" cy="200" r="190" fill="none" stroke="#B87333" stroke-width="6"/>
|
||||||
|
<circle cx="200" cy="200" r="180" fill="none" stroke="#B87333" stroke-width="2"/>
|
||||||
|
|
||||||
|
<!-- Decorative dots -->
|
||||||
|
<g fill="#B87333">
|
||||||
|
<circle cx="200" cy="14" r="4"/>
|
||||||
|
<circle cx="200" cy="386" r="4"/>
|
||||||
|
<circle cx="14" cy="200" r="4"/>
|
||||||
|
<circle cx="386" cy="200" r="4"/>
|
||||||
|
<circle cx="68" cy="68" r="3"/>
|
||||||
|
<circle cx="332" cy="68" r="3"/>
|
||||||
|
<circle cx="68" cy="332" r="3"/>
|
||||||
|
<circle cx="332" cy="332" r="3"/>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<!-- Inner ring -->
|
||||||
|
<circle cx="200" cy="200" r="150" fill="none" stroke="#B87333" stroke-width="2"/>
|
||||||
|
<circle cx="200" cy="200" r="140" fill="none" stroke="#B87333" stroke-width="1"/>
|
||||||
|
|
||||||
|
<!-- Stars between rings -->
|
||||||
|
<g fill="#B87333" class="seal-text" text-anchor="middle" font-size="16">
|
||||||
|
<text x="200" y="42">★</text>
|
||||||
|
<text x="200" y="370">★</text>
|
||||||
|
<text x="38" y="206">★</text>
|
||||||
|
<text x="362" y="206">★</text>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<!-- Circular text - top: "WORKS ON MY MACHINE" -->
|
||||||
|
<path id="topArc" d="M 80,200 a 120,120 0 0,1 240,0" fill="none"/>
|
||||||
|
<text class="seal-text" font-size="18" fill="#B87333" letter-spacing="3">
|
||||||
|
<textPath href="#topArc" startOffset="50%" text-anchor="middle">WORKS ON MY MACHINE</textPath>
|
||||||
|
</text>
|
||||||
|
|
||||||
|
<!-- Circular text - bottom: "CERTIFIED" -->
|
||||||
|
<path id="bottomArc" d="M 320,200 a 120,120 0 0,1 -240,0" fill="none"/>
|
||||||
|
<text class="seal-text" font-size="18" fill="#B87333" letter-spacing="5">
|
||||||
|
<textPath href="#bottomArc" startOffset="50%" text-anchor="middle">CERTIFIED</textPath>
|
||||||
|
</text>
|
||||||
|
|
||||||
|
<!-- Laptop + checkmark icon -->
|
||||||
|
<g transform="translate(200,165)" fill="none" stroke="#B87333" stroke-width="3"
|
||||||
|
stroke-linecap="round" stroke-linejoin="round">
|
||||||
|
<rect x="-35" y="-30" width="70" height="48" rx="4"/>
|
||||||
|
<polyline points="-12,0 -2,10 16,-10" stroke-width="4" stroke="#8B5E3C"/>
|
||||||
|
<path d="M-45,18 L-50,28 L50,28 L45,18"/>
|
||||||
|
</g>
|
||||||
|
|
||||||
|
<!-- WOMM -->
|
||||||
|
<text x="200" y="228" class="seal-text" font-size="42" fill="#B87333"
|
||||||
|
text-anchor="middle" letter-spacing="6">WOMM</text>
|
||||||
|
|
||||||
|
<!-- Divider -->
|
||||||
|
<line x1="120" y1="240" x2="280" y2="240" stroke="#B87333" stroke-width="1.5"/>
|
||||||
|
|
||||||
|
<!-- Level label -->
|
||||||
|
<text x="200" y="260" class="seal-text" font-size="16" fill="#B87333"
|
||||||
|
text-anchor="middle" letter-spacing="3">BRONZE</text>
|
||||||
|
|
||||||
|
<!-- Date -->
|
||||||
|
<text x="200" y="285" class="seal-text" font-size="13" fill="#B87333"
|
||||||
|
text-anchor="middle" letter-spacing="1">2026-04-02</text>
|
||||||
|
|
||||||
|
<!-- Dot decorations -->
|
||||||
|
<g fill="#B87333">
|
||||||
|
<circle cx="148" cy="282" r="2"/>
|
||||||
|
<circle cx="252" cy="282" r="2"/>
|
||||||
|
</g>
|
||||||
|
</svg>
|
||||||
|
After Width: | Height: | Size: 2.8 KiB |
110
.womm/womm-certificate.txt
Normal file
110
.womm/womm-certificate.txt
Normal file
@ -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.
|
||||||
|
================================================================
|
||||||
|
|
||||||
87
CLAUDE.md
Normal file
87
CLAUDE.md
Normal file
@ -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.
|
||||||
@ -256,4 +256,6 @@ Error: Request failed: context deadline exceeded
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Made with ❤️ using Grok AI**
|
**Made with ❤️ using Grok AI**
|
||||||
|
|
||||||
|
THIS PROJECT IS [WOMM CERTIFIED](.womm/womm-certificate.txt) 
|
||||||
81
docs/developer-guide/TEST-COVERAGE.md
Normal file
81
docs/developer-guide/TEST-COVERAGE.md
Normal file
@ -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.
|
||||||
Loading…
Reference in New Issue
Block a user