feat: add modusgraph-gen code generator with private field support and accessor name overrides

[mlwelles]

Summary

Adds modusgraph-gen, a code generation tool that reads Go structs with json/dgraph tags and produces typed CRUD clients, query builders, iterators, and a CLI — with full private field support and customizable accessor names.

Core Generator

Output	Purpose
client_gen.go	Typed Client with per-entity sub-clients
page_options_gen.go	First(n) / Offset(n) pagination helpers
iter_gen.go	Auto-paging SearchIter / ListIter (Go 1.23+ iter.Seq2)
<entity>_gen.go	Per-entity CRUD: Get, Add, Update, Delete, Search, List
<entity>_options_gen.go	Functional options per scalar field
<entity>_query_gen.go	Fluent query builder with filters, ordering, pagination
<entity>_accessors_gen.go	Getters, setters, slice/edge helpers (private fields only)
<entity>_marshal_gen.go	DgraphMap(), UnmarshalJSON(), ValidateWith() (private fields only)
cmd/<pkg>/main.go	Kong CLI with per-entity subcommands and raw DQL query

Private Field Support

Entities with unexported fields get:

• Getters/setters with Go-idiomatic names (name → Name() / SetName())
• Singular edge accessors for *Entity, bare Entity, or validate:"max=1" fields → *Type signatures
• Multi-edge helpers: Append (variadic), Remove (by UID), RemoveFunc (predicate)
• Primitive slice helpers: Append, Remove (by value), RemoveFunc
• DgraphMap() for write-path serialization (bypasses dgman's reflect limitation on unexported fields)
• UnmarshalJSON() for read-path deserialization
• ValidateWith(ctx, validator) for struct validation via a mirror struct with exported fields
• Field opt-out: no json tag → skip; dgraph:"-" → explicit skip

Accessor Name Overrides (New)

Initialism-aware naming: toCamelCase now recognizes the canonical Go lint initialisms (38 entries from golang.org/x/lint). Fields like id produce ID() / SetID() automatically.

Per-field overrides via accessor struct tag:

type Widget struct {
    id   string `json:"id,omitempty" accessor:"ID"`
    url  string `json:"url,omitempty"`           // auto: URL() / SetURL()
    name string `json:"name,omitempty"`           // auto: Name() / SetName()
}

The override applies everywhere: getters, setters, Append*, Remove*, With*Option, UnmarshalJSON alias, ValidateWith mirror, and CLI struct fields.

Engine Changes

• DgraphMapper interface: Insert/Update detect entities with private fields and route through map-based mutation
• InsertRaw for raw struct insertion
• Validator support via WithValidator(...) and SelfValidator interface

Edge Type Coverage

All edge variants are supported and tested:

• []Entity, []*Entity — multi-edge (getter, setter, append, remove, removeFunc)
• *Entity — singular edge (getter, setter)
• Entity (bare value) — singular edge (getter returns *Entity, setter accepts *Entity)
• []Entity / []*Entity + validate:"max=1" or validate:"len=1" — singular edge

Zero New Dependencies

The generator uses only the Go standard library (go/ast, go/parser, text/template, embed).

Usage

//go:generate go run github.com/matthewmcneely/modusgraph/cmd/modusgraph-gen

Testing

• Unit tests: toCamelCase with 33 initialism/compound/edge cases, accessorName with override and fallback, accessor tag parsing
• Golden file tests: all entity types including Studio (private field test fixture with all edge variants)
• Parser tests: parseValidateTag, dgraph:"-", private field detection, singular edge detection, accessor tag
• Generator tests: accessor output, marshal output, CLI output, validator output, edge variants, external imports
• All existing modusGraph tests pass unchanged
• go vet / go build clean

[cubic-dev-ai]

11 issues found across 74 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="cmd/modusgraph-gen/internal/generator/templates/cli.go.tmpl">

<violation number="1" location="cmd/modusgraph-gen/internal/generator/templates/cli.go.tmpl:131">
P2: Add command only applies string-typed scalar fields; non-string scalar flags are accepted but never copied into the entity, so user input is ignored and zero values are inserted.</violation>
</file>

<file name="cmd/modusgraph-gen/internal/parser/parser.go">

<violation number="1" location="cmd/modusgraph-gen/internal/parser/parser.go:130">
P2: parseStruct only processes the first name in a multi-name field declaration (f.Names[0]). In Go, `A, B string` is valid; this implementation silently drops `B`, so metadata for additional names is never generated.</violation>
</file>

<file name="cmd/modusgraph-gen/internal/parser/parser_test.go">

<violation number="1" location="cmd/modusgraph-gen/internal/parser/parser_test.go:525">
P2: Test uses a hardcoded absolute `/tmp` path, making the expectation host-dependent and potentially flaky.</violation>
</file>

<file name="README.md">

<violation number="1" location="README.md:628">
P2: README documents the generator at `cmd/modusgraphgen`, but the actual package is `cmd/modusgraph-gen`, causing install/generate commands to fail.</violation>

<violation number="2" location="README.md:676">
P2: Entity detection documentation is inaccurate: parser includes private/unexported fields with json tags, but README claims only exported fields are parsed.</violation>
</file>

<file name="docs/plans/2026-02-27-merge-query-into-generated-cli-design.md">

<violation number="1" location="docs/plans/2026-02-27-merge-query-into-generated-cli-design.md:94">
P2: Mutual-exclusion logic is tied to a duplicated default address literal, creating a brittle regression point if defaults drift.</violation>
</file>

<file name="cmd/modusgraph-gen/internal/generator/templates/options.go.tmpl">

<violation number="1" location="cmd/modusgraph-gen/internal/generator/templates/options.go.tmpl:6">
P2: Time import detection only matches GoType prefix "time.", missing pointer/slice/map time types (e.g., *time.Time, []time.Time), which can lead to generated code referencing time without importing it.</violation>

<violation number="2" location="cmd/modusgraph-gen/internal/generator/templates/options.go.tmpl:24">
P2: Option function names can collide between private and exported fields that differ only by case, leading to duplicate generated functions and a compile-time error.</violation>
</file>

<file name="mutate.go">

<violation number="1" location="mutate.go:265">
P1: `toDgraphMap` can panic by calling `Interface()` on invalid reflection values after `Elem()` on nil pointers (single object and slice element paths).</violation>
</file>

<file name="docs/plans/2026-02-27-merge-modusgraphgen-plan.md">

<violation number="1" location="docs/plans/2026-02-27-merge-modusgraphgen-plan.md:293">
P2: The "full test suite" command only runs tests in the current package. Use `./...` to include subpackages so the plan actually checks all regressions.</violation>
</file>

<file name="cmd/modusgraph-gen/internal/generator/templates/accessors.go.tmpl">

<violation number="1" location="cmd/modusgraph-gen/internal/generator/templates/accessors.go.tmpl:11">
P2: Accessors for private slice fields can reference external types, but the import list is built only from private scalar fields. This can omit required imports (e.g., time or uuid) when an entity has only private slice fields, causing generated code to fail to compile.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

2 issues found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="VALIDATOR.md">

<violation number="1" location="VALIDATOR.md:176">
P2: Documentation claims runtime cardinality enforcement unconditionally, but validation is optional, so enforcement is not guaranteed in all setups.</violation>
</file>

<file name="README.md">

<violation number="1" location="README.md:682">
P2: README examples still show `[]*Entity` relationships, but the generator only detects edges for `[]Entity` and `*Entity`. This documentation inconsistency can mislead users into modeling pointer-slice edges that won’t be recognized by the parser.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}