Debian Codegraph @

.claude/skills/codegen/SKILL.md

raw
1 # Code Generation
2
3 How the testify code and documentation generator works.
4
5 ## Running
6
7 ```bash
8 # Generate everything (code + docs) from internal/assertions/
9 go generate ./...
10
11 # Or run the generator directly
12 cd codegen && go run . -output-packages assert,require -include-doc
13
14 # Code only (skip docs)
15 cd codegen && go run . -output-packages assert,require -include-doc=false
16 ```
17
18 ## Generator pipeline
19
20 1. **Scanner** (`codegen/internal/scanner/`) parses `internal/assertions/` using
21 `go/packages` and `go/types`. Extracts function signatures, doc comments,
22 domain tags, examples, and metadata.
23 - `comments/` -- doc comment extraction
24 - `comments-parser/` -- domain tags, examples, metadata parsing
25 - `signature/` -- function signature analysis
26
27 2. **Model** (`codegen/internal/model/`) holds the intermediate representation:
28 functions, type params, tests, documentation, metrics.
29
30 3. **Generator** (`codegen/internal/generator/`) renders templates:
31 - **Code templates** produce `assert/` and `require/` packages with all variants
32 - **Doc templates** produce Hugo markdown in `docs/doc-site/api/`
33 - **Metrics** produces `metrics.yaml` for Hugo site params
34
35 ## Key templates
36
37 Located in `codegen/internal/generator/templates/`:
38
39 | Template | Produces |
40 |----------|----------|
41 | `assertion_assertions.gotmpl` | `assert` package-level functions |
42 | `assertion_format.gotmpl` | `assert` formatted variants (`*f`) |
43 | `assertion_forward.gotmpl` | `assert` forward methods |
44 | `requirement_*.gotmpl` | `require` equivalents (calls `FailNow`) |
45 | `doc_index.md.gotmpl` | API index page (`_index.md`) |
46 | `doc_page.md.gotmpl` | Per-domain doc pages |
47 | `doc_metrics.md.gotmpl` | Quick index & metrics page |
48
49 ## Template functions
50
51 Custom template functions in `codegen/internal/generator/funcmaps/`:
52 - `Slugize(name)` -- converts function name to markdown anchor
53 - `Titleize(s)` -- title-cases a string
54 - `hopen` / `hclose` -- Hugo shortcode delimiters (`{{% ... %}}`)
55
56 ## Domain organization
57
58 Functions are grouped by `// Domain: <name>` tags inside the function body.
59 Domain descriptions live in `internal/assertions/doc.go` as special comments.
60 The generator reorganizes package-based docs into domain-based pages
61 (19 domains currently).
62
63 ## Generated output
64
65 **Never edit generated files directly.** They carry a `DO NOT EDIT` header.
66
67 | Output | Location |
68 |--------|----------|
69 | `assert/` package | Generated functions + tests |
70 | `require/` package | Generated functions + tests |
71 | `docs/doc-site/api/*.md` | Domain-organized Hugo pages |
72 | `docs/doc-site/api/metrics.md` | Quick index + API metrics |
73 | `hack/doc-site/hugo/metrics.yaml` | Hugo site params (counts) |
74
75 Exceptions (not generated): `assert/doc.go`, `require/doc.go`, ad-hoc testable examples.
76
77 ## Adding support for a new construct
78
79 If the generator needs to support a new Go construct (e.g., new type param
80 pattern), the work is in:
81 1. `codegen/internal/scanner/` -- teach the scanner to extract it
82 2. `codegen/internal/model/` -- add fields to the model
83 3. `codegen/internal/generator/templates/` -- update templates to render it
84
85 The scanner and generator have comprehensive tests (~1,400+ lines across test files).