feat: initial implementation

.github/workflows/ci.yml

@@ -39,3 +39,18 @@ jobs:
 
       - name: Run tests
         run: make test
+
+  examples:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Regenerate and test examples
+        run: make test-examples
+
+      - name: Verify generated code is up to date
+        run: git diff --exit-code

.golangci.yaml

@@ -59,6 +59,8 @@ linters:
     - wsl              # Excessive whitespace enforcement often degrades code density and readability
     - wsl_v5           # Same as wsl; v5 variant also enforces excessive whitespace rules
   exclusions:
+    paths:
+      - internal/generator/fixtures # Test fixture packages exist to be parsed by the generator, not to be exemplary code
     rules:
       - path: _test\.go
         linters:

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tetsuro Mikami
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -1,11 +1,14 @@
-.PHONY: test lint
+.PHONY: test test-examples lint
 
 test:
 	go test ./...
 
+test-examples:
+	cd examples && go generate ./... && go test ./...
+
 lint:
 	@command -v golangci-lint >/dev/null 2>&1 || { \
-		@echo "golangci-lint is not installed"; \
+		echo "golangci-lint is not installed"; \
 		exit 1; \
 	}
 	golangci-lint run

README.md

@@ -0,0 +1,139 @@
+# mapgen
+
+Type-safe struct mapping code generator for Go, driven by registered converters and `go generate`.
+
+mapgen generates the boring mapping functions between your domain models and wire types (protobuf messages, DTOs) that you would otherwise write by hand. There is no reflection at runtime: the generated code calls your converter functions directly and compiles like hand-written code.
+
+```go
+// What you write: a converter package registered once.
+func init() {
+	mapper.Register(ToDate)      // time.Time -> *date.Date
+	mapper.Register(UUIDToString)
+	mapper.Register(ToTime)      // *date.Date -> time.Time
+	mapper.RegisterE(uuid.Parse) // string -> uuid.UUID, can fail
+}
+```
+
+```go
+// What you add: one directive in the package that should hold the mappers.
+//go:generate go tool mapgen -types=model.Employee:*employeev1.Employee -converter-pkg=./lib/converters
+```
+
+```go
+// What you get: readable, compile-checked mapping functions.
+func EmployeeToEmployeev1(src model.Employee) *employeev1.Employee {
+	return &employeev1.Employee{
+		Id:      converters.UUIDToString(src.ID),
+		Name:    src.Name,
+		HiredAt: converters.ToDate(src.HiredAt),
+	}
+}
+
+func EmployeeFromEmployeev1(src *employeev1.Employee) (model.Employee, error) {
+	if src == nil {
+		return model.Employee{}, nil
+	}
+	v1, err0 := uuid.Parse(src.GetId())
+	if err0 != nil {
+		return model.Employee{}, fmt.Errorf("map model.Employee.ID: %w", err0)
+	}
+	// ...
+}
+```
+
+See [examples](./examples) for a complete, runnable module.
+
+## Installation
+
+Requires Go 1.25+.
+
+```sh
+go get -tool github.com/mickamy/mapgen@latest
+```
+
+## How it works
+
+`mapper.Register` calls are never executed by the generator. Instead, mapgen statically analyzes the converter package, extracts the registered `(Src, Dst)` type pairs and function references, and wires those functions directly into the generated code. The `runtime/mapper` package is a declaration DSL first; the registry also works at runtime through `mapper.Convert` if you need dynamic lookup.
+
+Package selectors in `-types` (`model`, `employeev1`) are resolved from the imports of the package containing the directive, with the directive file's imports taking priority. If the package already imports the types for real use, the directive is a single line. Otherwise keep a minimal directive file:
+
+```go
+//go:generate go tool mapgen -types=model.Employee:*employeev1.Employee -converter-pkg=./lib/converters
+package handler
+
+import (
+	_ "github.com/acme/app/gen/employee/v1"
+	_ "github.com/acme/app/internal/model"
+)
+```
+
+Full import paths are also accepted: `-types=github.com/acme/app/internal/model.Employee:*github.com/acme/app/gen/employee/v1.Employee`.
+
+## Flags
+
+| Flag                        | Description                                                                                         |
+|-----------------------------|-----------------------------------------------------------------------------------------------------|
+| `-types=SRC:DST[,...]`      | Type pairs to map. Optional `*` prefix for pointer types. Repeatable.                               |
+| `-converter-pkg=PATH`       | Package containing `mapper.Register` calls (directory or import path). Repeatable.                  |
+| `-output=PATH`              | Output directory (file name derives from `$GOFILE`), or a `.go` file path. Default `.`.             |
+| `-direction=both\|to\|from` | Which functions to generate. Default `both`.                                                        |
+| `-ignore=TYPE.FIELD[,...]`  | Skip destination fields on types you cannot tag (e.g., `employeev1.Employee.Internal`). Repeatable. |
+| `-package=NAME`             | Output package name when `$GOPACKAGE` is not available.                                             |
+| `-check`                    | Verify generated files are up to date instead of writing (for CI).                                  |
+
+One pair `A:B` generates both `AToB` and `AFromB` style functions, named from the A side (`EmployeeToEmployeev1` / `EmployeeFromEmployeev1`). A function returns `(T, error)` only when it uses a fallible converter registered with `RegisterE`.
+
+## Field matching
+
+For each destination field, mapgen picks the source in this order:
+
+1. `map` tag on either side (see below)
+2. exact name match
+3. case-insensitive match (`ID` ↔ `Id`)
+4. promoted (embedded) fields, exact match only
+
+Reading prefers nil-safe getters (`GetName()`) when present, which handles protobuf pointers and proto3 optional fields naturally. Unexported fields are always skipped, so protobuf bookkeeping fields (`state`, `sizeCache`, `unknownFields`) never get in the way.
+
+Every remaining destination field must resolve, or generation fails with the field's position and a copy-pasteable suggestion:
+
+```
+internal/model/employee.go:12:2: cannot map model.Employee.ID (uuid.UUID) to employeev1.Employee.Id (string)
+	register a converter: mapper.Register(func(uuid.UUID) string { ... })
+	or declare the pair in -types, or exclude the field with map:"-" or -ignore
+```
+
+### The `map` struct tag
+
+```go
+type Employee struct {
+	ID        uuid.UUID `map:"Id"` // maps to the counterpart field named Id
+	CreatedAt time.Time `map:"-"`  // invisible to mapgen
+}
+```
+
+`map:"Name"` names the counterpart field and works in both directions. `map:"-"` removes the field from mapping entirely. Tags naming nonexistent counterparts are errors, so typos surface at generation time. For types you cannot tag (generated protobuf code), use `-ignore`.
+
+## Conversion rules
+
+For a source value of type S and a destination field of type D, mapgen resolves in order:
+
+1. identical types: direct assignment
+2. registered converter `(S, D)`: direct call
+3. declared pair in `-types`: call to the generated mapper (errors propagate)
+4. `*S`: dereference, leaving the destination zero when nil (nil pointers map to nil pointers, never to a pointer to a zero value)
+5. `*D`: take the address of the converted value
+6. slices: element-wise conversion; nil stays nil
+7. safe Go conversions only: loss-free numeric widening (`int32` → `int64`, `uint8` → `int16`, `float32` → `float64`, exactly representable integers → float), named ↔ underlying (e.g., proto enum ↔ int32), string ↔ []byte
+
+Lossy or surprising conversions are deliberately rejected: numeric ↔ string (`string(rune(42))` is never what you want), float → integer, and narrowing or sign-changing integer conversions (`int64` → `int32`, `int` → `uint`) all require an explicit converter.
+
+## Limitations (v1)
+
+- map-typed fields, protobuf `oneof`, the protobuf opaque API, and generic types are not supported; errors name them explicitly and `-ignore` is the escape hatch
+- converters must be named functions callable from the generated code (no closures, no methods)
+- proto3 optional: an unset field and a zero value collapse to the same thing on a roundtrip through a getter
+- pointer fields assigned directly (identical types) share the pointee; converters and declared pairs produce copies
+
+## License
+
+[MIT](./LICENSE)

examples/gen/employeev1/employee.go

@@ -0,0 +1,71 @@
+// Package employeev1 mimics protoc-generated wire types (open API
+// style: exported fields plus nil-safe getters).
+package employeev1
+
+import "google.golang.org/genproto/googleapis/type/date"
+
+// Employee is the wire-side representation of model.Employee.
+type Employee struct {
+	state     int
+	Id        string
+	Name      string
+	HiredAt   *date.Date
+	Address   *Address
+	Nicknames []string
+}
+
+func (x *Employee) GetId() string {
+	if x != nil {
+		return x.Id
+	}
+	return ""
+}
+
+func (x *Employee) GetName() string {
+	if x != nil {
+		return x.Name
+	}
+	return ""
+}
+
+func (x *Employee) GetHiredAt() *date.Date {
+	if x != nil {
+		return x.HiredAt
+	}
+	return nil
+}
+
+func (x *Employee) GetAddress() *Address {
+	if x != nil {
+		return x.Address
+	}
+	return nil
+}
+
+func (x *Employee) GetNicknames() []string {
+	if x != nil {
+		return x.Nicknames
+	}
+	return nil
+}
+
+// Address is the wire-side representation of model.Address.
+type Address struct {
+	state  int
+	City   string
+	Street string
+}
+
+func (x *Address) GetCity() string {
+	if x != nil {
+		return x.City
+	}
+	return ""
+}
+
+func (x *Address) GetStreet() string {
+	if x != nil {
+		return x.Street
+	}
+	return ""
+}

examples/go.mod

@@ -0,0 +1,20 @@
+module github.com/mickamy/mapgen/examples
+
+go 1.25.0
+
+tool github.com/mickamy/mapgen
+
+require (
+	github.com/google/uuid v1.6.0
+	github.com/mickamy/mapgen v0.0.0
+	google.golang.org/genproto v0.0.0-20240213162025-012b6fc9bca9
+)
+
+require (
+	golang.org/x/mod v0.38.0 // indirect
+	golang.org/x/sync v0.22.0 // indirect
+	golang.org/x/tools v0.48.0 // indirect
+	google.golang.org/protobuf v1.32.0 // indirect
+)
+
+replace github.com/mickamy/mapgen => ../

examples/go.sum

@@ -0,0 +1,14 @@
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
+golang.org/x/mod v0.38.0/go.mod h1:V6Xz0pq8TQ3dGqVQ1FVHuelZpAL0uNhSkk9ogYP3c40=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/tools v0.48.0 h1:3+hClM1aLL5mjMKm5ovokw9epgRXPuu2tILgismM6RE=
+golang.org/x/tools v0.48.0/go.mod h1:08xX0orndb/F7jJxGDicx061tyd5pcMto75YMAXr6lk=
+google.golang.org/genproto v0.0.0-20240213162025-012b6fc9bca9 h1:9+tzLLstTlPTRyJTh+ah5wIMsBW5c4tQwGTN3thOW9Y=
+google.golang.org/genproto v0.0.0-20240213162025-012b6fc9bca9/go.mod h1:mqHbVIp48Muh7Ywss/AD6I5kNVKZMmAa/QEW58Gxp2s=
+google.golang.org/protobuf v1.32.0 h1:pPC6BG5ex8PDFnkbrGU3EixyhKcQ2aDuBS36lqK/C7I=
+google.golang.org/protobuf v1.32.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=

examples/handler/handler.go

@@ -0,0 +1,10 @@
+// Package handler demonstrates mapgen: one go:generate directive, blank
+// imports to make the type selectors resolvable, nothing else.
+//
+//go:generate go tool mapgen -types=model.Employee:*employeev1.Employee,model.Address:*employeev1.Address -converter-pkg=../lib/converters
+package handler
+
+import (
+	_ "github.com/mickamy/mapgen/examples/gen/employeev1"
+	_ "github.com/mickamy/mapgen/examples/model"
+)