# 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

| Area | Status | Covered in rs-zero | Main differences |
| --- | --- | --- | --- |
| 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
```
