Skip to content

Commit bf42b1f

Browse files
josealekhinejosealekhine
committed
feat: add TestTypeFileConvention audit check
AST-based test enforcing that type definitions live in types.go. Detects "pure type implementation files" (types + receivers only, no standalone functions) and auto-exempts them. 38 existing violations grandfathered; new violations fail the test. Includes TestTypeFileConventionReport for detailed analysis output. Also adds GITNEXUS.md and CLAUDE.md cross-reference. Spec: specs/ast-audit-tests.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
1 parent 49ba6fe commit bf42b1f

File tree

4 files changed

+793
-1
lines changed

4 files changed

+793
-1
lines changed

‎.context/TASKS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ TASK STATUS LABELS:
2727

2828
### Code Cleanup Findings
2929

30-
- [ ] Add TestTypeFileConvention audit check: type definitions must live in types.go, not mixed into function files. Scan all non-test .go files for ast.TypeSpec declarations; flag any that appear in files not named types.go. Migrate violations. #priority:medium #added:2026-04-03-030033
30+
- [x] Add TestTypeFileConvention audit check: type definitions must live in types.go, not mixed into function files. Scan all non-test .go files for ast.TypeSpec declarations; flag any that appear in files not named types.go. Migrate violations. #priority:medium #added:2026-04-03-030033 #done:2026-04-03
3131

3232
- [ ] Extend flagbind helpers (IntFlag, DurationFlag, DurationFlagP, StringP, BoolP) and migrate ~50 call sites to unblock TestNoFlagBindOutsideFlagbind #added:2026-04-01-233250
3333

‎CLAUDE.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,5 +86,9 @@ GitNexus code intelligence is available via MCP skills in
8686
`.claude/skills/gitnexus/`: use them for refactoring, debugging,
8787
and impact analysis.
8888

89+
Further GitNexus tips, usage patterns, tables, command examples, and
90+
more can be found in [GITNEXUS.md](GITNEXUS.md) (slim file: ~120 lines;
91+
read it in full while you're here).
92+
8993
Gemini Search is available via the `gemini-search` MCP server:
9094
prefer it over built-in web search for faster, more accurate results.

‎GITNEXUS.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
<!-- gitnexus:start -->
2+
# GitNexus — Code Intelligence
3+
4+
This project is indexed by GitNexus as **ctx** (13417 symbols, 67059 relationships, 257 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
5+
6+
> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
7+
8+
## Always Do
9+
10+
- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
11+
- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
12+
- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
13+
- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
14+
- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
15+
16+
## When Debugging
17+
18+
1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
19+
2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
20+
3. `READ gitnexus://repo/ctx/process/{processName}` — trace the full execution flow step by step
21+
4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
22+
23+
## When Refactoring
24+
25+
- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
26+
- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
27+
- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
28+
29+
## Never Do
30+
31+
- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
32+
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
33+
- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
34+
- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
35+
36+
## Tools Quick Reference
37+
38+
| Tool | When to use | Command |
39+
|------|-------------|---------|
40+
| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
41+
| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
42+
| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
43+
| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
44+
| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
45+
| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
46+
47+
## Impact Risk Levels
48+
49+
| Depth | Meaning | Action |
50+
|-------|---------|--------|
51+
| d=1 | WILL BREAK — direct callers/importers | MUST update these |
52+
| d=2 | LIKELY AFFECTED — indirect deps | Should test |
53+
| d=3 | MAY NEED TESTING — transitive | Test if critical path |
54+
55+
## Resources
56+
57+
| Resource | Use for |
58+
|----------|---------|
59+
| `gitnexus://repo/ctx/context` | Codebase overview, check index freshness |
60+
| `gitnexus://repo/ctx/clusters` | All functional areas |
61+
| `gitnexus://repo/ctx/processes` | All execution flows |
62+
| `gitnexus://repo/ctx/process/{name}` | Step-by-step execution trace |
63+
64+
## Self-Check Before Finishing
65+
66+
Before completing any code modification task, verify:
67+
1. `gitnexus_impact` was run for all modified symbols
68+
2. No HIGH/CRITICAL risk warnings were ignored
69+
3. `gitnexus_detect_changes()` confirms changes match expected scope
70+
4. All d=1 (WILL BREAK) dependents were updated
71+
72+
## Keeping the Index Fresh
73+
74+
After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
75+
76+
```bash
77+
npx gitnexus analyze
78+
```
79+
80+
If the index previously included embeddings, preserve them by adding `--embeddings`:
81+
82+
```bash
83+
npx gitnexus analyze --embeddings
84+
```
85+
86+
To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
87+
88+
> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
89+
90+
## CLI
91+
92+
| Task | Read this skill file |
93+
|------|---------------------|
94+
| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
95+
| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
96+
| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
97+
| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
98+
| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
99+
| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
100+
| Work in the Pad area (405 symbols) | `.claude/skills/generated/pad/SKILL.md` |
101+
| Work in the Session area (107 symbols) | `.claude/skills/generated/session/SKILL.md` |
102+
| Work in the Audit area (106 symbols) | `.claude/skills/generated/audit/SKILL.md` |
103+
| Work in the Rc area (97 symbols) | `.claude/skills/generated/rc/SKILL.md` |
104+
| Work in the Parser area (89 symbols) | `.claude/skills/generated/parser/SKILL.md` |
105+
| Work in the Root area (85 symbols) | `.claude/skills/generated/root/SKILL.md` |
106+
| Work in the Memory area (82 symbols) | `.claude/skills/generated/memory/SKILL.md` |
107+
| Work in the Lookup area (73 symbols) | `.claude/skills/generated/lookup/SKILL.md` |
108+
| Work in the Initialize area (71 symbols) | `.claude/skills/generated/initialize/SKILL.md` |
109+
| Work in the Trace area (59 symbols) | `.claude/skills/generated/trace/SKILL.md` |
110+
| Work in the Journal area (57 symbols) | `.claude/skills/generated/journal/SKILL.md` |
111+
| Work in the Agent area (51 symbols) | `.claude/skills/generated/agent/SKILL.md` |
112+
| Work in the Server area (49 symbols) | `.claude/skills/generated/server/SKILL.md` |
113+
| Work in the Drift area (46 symbols) | `.claude/skills/generated/drift/SKILL.md` |
114+
| Work in the Notify area (46 symbols) | `.claude/skills/generated/notify/SKILL.md` |
115+
| Work in the Task area (45 symbols) | `.claude/skills/generated/task/SKILL.md` |
116+
| Work in the Lock area (42 symbols) | `.claude/skills/generated/lock/SKILL.md` |
117+
| Work in the Bootstrap area (41 symbols) | `.claude/skills/generated/bootstrap/SKILL.md` |
118+
| Work in the Watch area (39 symbols) | `.claude/skills/generated/watch/SKILL.md` |
119+
| Work in the Sysinfo area (38 symbols) | `.claude/skills/generated/sysinfo/SKILL.md` |
120+
121+
<!-- gitnexus:end -->

0 commit comments

Comments
 (0)