# goctl compatibility matrix
Milestone 5 defines rs-zero's goctl compatibility as input semantics and workflow compatibility, not byte-for-byte Go output compatibility. The reference source for the reviewed behavior is the local go-zero `tools/goctl` tree. The committed fixtures are reduced examples that keep only the syntax needed for repeatable tests.
## Summary
| API parser | Partial | `syntax`, `import`, `type`, field tags, `@server`, `@handler`, route request/response | Only one service per parsed root file is validated today. |
| API formatter | Partial | Stable `.api` output preserving imports, docs, server options, handlers and field tags | Formatting is stable for rs-zero; it does not promise gofmt/goctl byte identity. |
| API OpenAPI/doc | Partial | OpenAPI paths, prefix, group tags, route summaries, request parameters and response schemas | goctl doc templates and Swagger output layout are not copied. |
| Model SQL parser | Partial | MySQL `CREATE TABLE` subset plus explicit PostgreSQL subset, comments, defaults, `ON UPDATE`, charset/collation, primary/unique/normal indexes | Full MySQL/PostgreSQL grammar, migrations and database introspection are out of scope. |
| Model generation | Partial | Rust entity, repository trait, cache key skeletons, SQLite/MySQL/PostgreSQL SQLx pool markers | Output is Rust-first and does not match goctl Go model files. |
| RPC parser | Partial | proto3 package/options/import/message/service/rpc subset, local imports, well-known type references | It does not replace `protoc`; it only builds enough AST for skeleton generation. |
| RPC generation | Partial | tonic-oriented Rust skeleton and file list | Real prost build wiring is left to application integration. |
| CLI | Partial | `api validate`, `api format`, `api openapi`, `api gen`, `model gen`, `rpc gen`, `goctl compat matrix` | goctl plugin, gateway, docker, kube and language-specific generators are not implemented. |
## Golden fixtures
Fixtures live under `tests/fixtures/goctl/`:
- `api/parser_test.api` covers syntax docs, import, field tag options, `@server` group/prefix/middleware, handler docs and route response.
- `model/user.sql` covers `AUTO_INCREMENT`, charset/collation, multiline comments, `ON UPDATE`, composite unique index, normal index and explicit MySQL SQLx backend generation.
- `tests/fixtures/postgres/model/user.sql` covers explicit PostgreSQL model generation, including quoted identifiers, identity, PostgreSQL types, `CREATE INDEX` and `COMMENT ON`.
- `rpc/*.proto` covers basic services, sibling imports, subdirectory imports, transitive imports, multiple services and well-known types.
Tests assert AST fields, normalized formatting, generated file lists and key content. They intentionally avoid fragile full-file snapshots.
## Not supported
- Go output byte-for-byte compatibility.
- Running or requiring the `goctl` binary in default tests.
- Java, Dart, TypeScript, Kotlin, Mongo, gateway, plugin and upgrade commands.
- External services, databases or registries in compatibility tests.
- Full protobuf, MySQL grammar or PostgreSQL grammar support.
## Verification
Default verification must pass without Go toolchain, goctl binary or external services:
```bash
cargo metadata --format-version 1 --no-deps
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```