feat: add modusgraphgen code generator by mlwelles · Pull Request #10 · matthewmcneely/modusGraph

mlwelles · 2026-02-27T19:12:04Z

Summary

Adds cmd/modusgraphgen/, a code generation tool that reads Go structs with json/dgraph tags and produces typed CRUD clients, query builders, auto-paging iterators, functional options, and a Kong CLI
Zero new dependencies -- the generator uses only the Go standard library (go/ast, go/parser, text/template, embed)
Code organized under cmd/modusgraphgen/internal/ with model, parser, and generator packages
Self-contained test fixtures in testdata/ with golden file regression tests
Adds "Code Generation" section to README
Adds .osgrep, .opencode, .claude to .gitignore

Usage

//go:generate go run github.com/matthewmcneely/modusgraph/cmd/modusgraphgen

Or install directly:

go install github.com/matthewmcneely/modusgraph/cmd/modusgraphgen@latest

What Gets Generated

Output	Scope
`client_gen.go`	Typed `Client` with sub-clients per entity
`page_options_gen.go`	`First(n)` and `Offset(n)` pagination
`iter_gen.go`	Auto-paging `SearchIter` and `ListIter` iterators
`<entity>_gen.go`	Per entity CRUD: `Get`, `Add`, `Update`, `Delete`, `Search`, `List`
`<entity>_options_gen.go`	Functional options for each scalar field
`<entity>_query_gen.go`	Fluent query builder with filters, ordering, pagination
`cmd/<pkg>/main.go`	Kong CLI with subcommands per entity

Testing

All parser and generator tests pass. Existing modusGraph tests unaffected.

Summary by cubic

Adds modusgraph-gen, a standard-library code generator that reads Go structs with json/dgraph tags and generates a typed client, CRUD APIs, fluent query builders, auto-paging iterators, functional options, and an optional Kong CLI with a raw DQL query command. Also updates .gitignore and removes stray binaries/IDE files; README and golden tests updated; no new dependencies.

New Features
- New generator under cmd/modusgraph-gen with internal model, parser, and generator packages.
- Generates client_gen.go, page_options_gen.go, iter_gen.go, and per-entity CRUD, options, and query files.
- Adds Client.QueryRaw and a generated CLI with global --addr/--dir flags and a "query" subcommand; standalone cmd/query marked deprecated.
- Embeds templates and writes formatted *_gen.go output; updated README and docs.
Migration
- Add: //go:generate go run github.com/matthewmcneely/modusgraph/cmd/modusgraph-gen
- Run: go generate ./...
- Optional: configure CLI output with -cli-dir and -cli-name; use the generated CLI's "query" subcommand instead of cmd/query.

^{Written for commit d6f4145. Summary will update on new commits.}

Merge the standalone modusGraphGen code generator into the modusGraph repository as cmd/modusgraphgen/. The tool parses Go structs with json/dgraph tags and generates typed CRUD clients, query builders, auto-paging iterators, functional options, and a Kong CLI. Code is organized under cmd/modusgraphgen/internal/ with model, parser, and generator packages. Test fixtures are self-contained in testdata/. The generated code imports github.com/matthewmcneely/modusgraph and requires no additional dependencies beyond the Go standard library.

cubic-dev-ai

4 issues found across 59 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/modusgraphgen/internal/generator/templates/options.go.tmpl">

<violation number="1" location="cmd/modusgraphgen/internal/generator/templates/options.go.tmpl:6">
P2: time import detection only checks types starting with `time.`, so pointer/slice/map time types (e.g., `*time.Time`, `[]time.Time`) won't trigger the import and will generate code that references `time` without importing it.</violation>
</file>

<file name="cmd/modusgraphgen/internal/generator/templates/cli.go.tmpl">

<violation number="1" location="cmd/modusgraphgen/internal/generator/templates/cli.go.tmpl:68">
P2: Non-string scalar CLI inputs are ignored because only string-typed fields are copied into the entity in the generated Add command.</violation>
</file>

<file name="cmd/modusgraphgen/internal/parser/parser.go">

<violation number="1" location="cmd/modusgraphgen/internal/parser/parser.go:1">
P2: Parser iteration over Go maps (`pkgs` and `pkgAST.Files`) is unsorted, making package selection and entity ordering nondeterministic across runs. This can yield unstable or incorrect generated output when multiple packages or files are present.</violation>
</file>

<file name="cmd/modusgraphgen/internal/generator/templates/iter.go.tmpl">

<violation number="1" location="cmd/modusgraphgen/internal/generator/templates/iter.go.tmpl:3">
P2: iter.go.tmpl always emits context/iter imports even when .Entities is empty, producing an iter_gen.go with unused imports and no declarations. This can break builds for empty schemas.</violation>
</file>

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

cubic-dev-ai · 2026-02-27T19:16:55Z

cmd/modusgraph-gen/internal/generator/templates/options.go.tmpl

+{{$name := .Entity.Name}}
+{{$fields := scalarFields .Entity.Fields}}
+{{- $needsTime := false}}
+{{- range $fields}}{{if hasPrefix .GoType "time."}}{{$needsTime = true}}{{end}}{{end}}


P2: time import detection only checks types starting with time., so pointer/slice/map time types (e.g., *time.Time, []time.Time) won't trigger the import and will generate code that references time without importing it.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At cmd/modusgraphgen/internal/generator/templates/options.go.tmpl, line 6: <comment>time import detection only checks types starting with `time.`, so pointer/slice/map time types (e.g., `*time.Time`, `[]time.Time`) won't trigger the import and will generate code that references `time` without importing it.</comment> <file context> @@ -0,0 +1,34 @@ +{{$name := .Entity.Name}} +{{$fields := scalarFields .Entity.Fields}} +{{- $needsTime := false}} +{{- range $fields}}{{if hasPrefix .GoType "time."}}{{$needsTime = true}}{{end}}{{end}} +{{- $extImports := externalImports $fields .Imports}} +{{if or $needsTime (gt (len $extImports) 0)}} </file context>

cubic-dev-ai · 2026-02-27T19:16:55Z

cmd/modusgraph-gen/internal/generator/templates/cli.go.tmpl

+
+func (c *{{.Name}}AddCmd) Run(client *{{$.Name}}.Client) error {
+	v := &{{$.Name}}.{{.Name}}{
+{{- range scalarFields .Fields}}{{if and (not .IsUID) (not .IsDType) (eq .GoType "string")}}


P2: Non-string scalar CLI inputs are ignored because only string-typed fields are copied into the entity in the generated Add command.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At cmd/modusgraphgen/internal/generator/templates/cli.go.tmpl, line 68: <comment>Non-string scalar CLI inputs are ignored because only string-typed fields are copied into the entity in the generated Add command.</comment> <file context> @@ -0,0 +1,129 @@ + +func (c *{{.Name}}AddCmd) Run(client *{{$.Name}}.Client) error { + v := &{{$.Name}}.{{.Name}}{ +{{- range scalarFields .Fields}}{{if and (not .IsUID) (not .IsDType) (eq .GoType "string")}} + {{.Name}}: c.{{.Name}}, +{{- end}}{{end}} </file context>

cubic-dev-ai · 2026-02-27T19:16:55Z

cmd/modusgraph-gen/internal/parser/parser.go

@@ -0,0 +1,354 @@
+// Package parser extracts entity and field metadata from Go source files by


P2: Parser iteration over Go maps (pkgs and pkgAST.Files) is unsorted, making package selection and entity ordering nondeterministic across runs. This can yield unstable or incorrect generated output when multiple packages or files are present.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At cmd/modusgraphgen/internal/parser/parser.go: <comment>Parser iteration over Go maps (`pkgs` and `pkgAST.Files`) is unsorted, making package selection and entity ordering nondeterministic across runs. This can yield unstable or incorrect generated output when multiple packages or files are present.</comment> <file context> @@ -0,0 +1,354 @@ +// Package parser extracts entity and field metadata from Go source files by +// inspecting struct declarations and their struct tags. It uses go/ast and +// go/parser to walk the AST, then builds a model.Package for the generator. +package parser + +import ( + "fmt" + "go/ast" + "go/parser" </file context>

cubic-dev-ai · 2026-02-27T19:16:55Z

cmd/modusgraph-gen/internal/generator/templates/iter.go.tmpl

@@ -0,0 +1,63 @@
+package {{.Name}}
+
+import (


P2: iter.go.tmpl always emits context/iter imports even when .Entities is empty, producing an iter_gen.go with unused imports and no declarations. This can break builds for empty schemas.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At cmd/modusgraphgen/internal/generator/templates/iter.go.tmpl, line 3: <comment>iter.go.tmpl always emits context/iter imports even when .Entities is empty, producing an iter_gen.go with unused imports and no declarations. This can break builds for empty schemas.</comment> <file context> @@ -0,0 +1,63 @@ +package {{.Name}} + +import ( + "context" + "iter" </file context>

cubic-dev-ai

1 issue found across 63 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=".gitignore">

<violation number="1" location=".gitignore:27">
P2: Unscoped `.gitignore` pattern `query` will ignore untracked files under existing `cmd/query`, making future additions easy to miss. Scope the ignore to the repo root if that's the intent.</violation>
</file>

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

cubic-dev-ai · 2026-02-27T21:09:40Z

.gitignore

+.osgrep
+.opencode
+.claude
+query


P2: Unscoped .gitignore pattern query will ignore untracked files under existing cmd/query, making future additions easy to miss. Scope the ignore to the repo root if that's the intent.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .gitignore, line 27: <comment>Unscoped `.gitignore` pattern `query` will ignore untracked files under existing `cmd/query`, making future additions easy to miss. Scope the ignore to the repo root if that's the intent.</comment> <file context> @@ -24,3 +24,4 @@ cpu_profile.prof .osgrep .opencode .claude +query </file context>

Suggested change

query

/query

Remove .idea/.gitignore, modusgraphgen binary, and benchmark JSON files that were accidentally committed. Update .gitignore to prevent recurrence.

matthewmcneely · 2026-02-28T01:06:29Z

@mlwelles Can you create a README in the cmd/modusgraph-gen folder that provides an overview of when/how to use this? For instance, how does it improve upon one simply creating a

type TestEntity struct {
	Name        string    `json:"name,omitempty" dgraph:"index=exact"`
	Description string    `json:"description,omitempty" dgraph:"index=term"`
	CreatedAt   time.Time `json:"createdAt,omitempty"`

	UID string `json:"uid,omitempty"`
	DType []string `json:"dgraph.type,omitempty"`
}

and then client.Insert()-ing a TestEntity?

mlwelles requested a review from matthewmcneely as a code owner February 27, 2026 19:12

mlwelles mentioned this pull request Feb 27, 2026

feat: add modusgraphgen code generator mlwelles/modusGraph#1

Merged

cubic-dev-ai bot reviewed Feb 27, 2026

View reviewed changes

mlwelles added 8 commits February 27, 2026 15:35

docs: add design for merging query into generated CLI

1a8553e

docs: add implementation plan for merging query into generated CLI

942f92f

refactor: rename cmd/modusgraphgen to cmd/modusgraph-gen

98c2afb

chore: add deprecation notice to standalone cmd/query

0404fa3

feat: add QueryRaw method to generated client template

7df5b9e

feat: add query subcommand and --dir/--addr flags to generated CLI

6660a26

test: add query subcommand tests and update golden files

3ab0726

chore: remove stray query binary and update gitignore

ec7efd6

cubic-dev-ai bot reviewed Feb 27, 2026

View reviewed changes

chore: remove untracked files swept up by git add -A

d6f4145

Remove .idea/.gitignore, modusgraphgen binary, and benchmark JSON files that were accidentally committed. Update .gitignore to prevent recurrence.

mlwelles marked this pull request as draft February 27, 2026 23:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add modusgraphgen code generator#10

feat: add modusgraphgen code generator#10
mlwelles wants to merge 10 commits intomatthewmcneely:mainfrom
mlwelles:feature/add-modusgraphgen

mlwelles commented Feb 27, 2026 •

edited by cubic-dev-ai bot

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

cubic-dev-ai bot Feb 27, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai bot Feb 27, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai bot Feb 27, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai bot Feb 27, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

cubic-dev-ai bot Feb 27, 2026 •

edited

Loading

Uh oh!

matthewmcneely commented Feb 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,354 @@
		// Package parser extracts entity and field metadata from Go source files by

Conversation

mlwelles commented Feb 27, 2026 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Usage

What Gets Generated

Testing

Summary by cubic

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewmcneely commented Feb 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mlwelles commented Feb 27, 2026 •

edited by cubic-dev-ai bot

Loading

cubic-dev-ai bot Feb 27, 2026 •

edited

Loading

cubic-dev-ai bot Feb 27, 2026 •

edited

Loading

cubic-dev-ai bot Feb 27, 2026 •

edited

Loading

cubic-dev-ai bot Feb 27, 2026 •

edited

Loading

cubic-dev-ai bot Feb 27, 2026 •

edited

Loading