// API-REST-GENERATOR — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

api-rest-generator is a REST backend code generator. Input is a raw CREATE TABLE dump in any of four SQL dialects (MySQL, PostgreSQL, SQLite, MSSQL). Output is a complete REST surface — entities, controllers, DAOs / repositories, migrations, and module wiring — targeting one of four backends (Spring Boot in Java, Kotlin, or Groovy; or Loco in Rust with Axum + SeaORM). Two binaries ship from one crate: api-rest-generator (full multi-target dispatch) and loco-gen (focused Rust-only flag surface, same engine).

Status: mid-transition. The repo currently carries two implementations of the same generator — the original Kotlin/Gradle pipeline (9,094 LOC) and the Rust/Cargo port (3,956 LOC). Both compile and produce output independently. The Rust port is being grown module-for-module against the Kotlin reference, with a parity test (tests/parity_smoke.rs) that runs both pipelines over shared sample DDLs and diffs the output. When parity holds across the full sample corpus + every dialect × target combination, the Kotlin path retires; until then both ship.

~DIALECT × TARGET MATRIX

Every input dialect feeds every output target. The crate ships sample DDLs covering all four dialect families; the test suite parameterises across (dialect × target) so a regression in any one cell fails CI for both pipelines.

$SAMPLE DDL CORPUS

Real-world reference schemas covering every supported dialect, used as parity-test fixtures and as demo inputs. All four live in samples/.

Table counts are the README-reported figures for each schema; tests/sample_ddls.rs pins the parse with conservative lower bounds (Sakila ≥15, Chinook ≥11, Pagila ≥15, Northwind ≥10) plus invariants — every table gets a PK (synthetic where needed) and no quote/bracket/tab leaks into the parsed identifiers. The Loco toolchain is not required to run this test, so parser/normalizer regressions are caught in CI without installing loco.

%INTERFACE SURFACE

Two entry points with two operating models. api-rest-generator is config-driven (no CLI flags — it reads src/main/resources/config.properties at a hard-coded relative path); loco-gen is flag-driven with new / generate subcommands.

// config.properties (api-rest-generator + Kotlin pipeline)

// loco-gen subcommands + flags (Rust/Loco)

loco-gen new shells out to loco new -n <name> --db <loco-db> --bg none --assets none, then writes entities / controllers / migrations into the scaffold. --wire rewrites an idempotent // BEGIN loco-gen routes block in src/app.rs (one .add_route(crate::controllers::<table>::routes()) per entity), preserving scaffold-shipped modules like controllers::home.

&KOTLIN → RUST PORT STATUS

The Rust port mirrors the Kotlin layout module-for-module to keep the diff readable. Each Kotlin source file has (or will have) a matching .rs port; the table below pins which ones are live.

Rust source totals 3,956 LOC across 11 files; the Kotlin codebase totals 9,094 LOC across 36 .kt files (8 main + 28 test). The 2.3× line-count ratio reflects Kotlin's reliance on Spring / JPA / Lombok annotations (which expand into JVM bytecode the Rust port doesn't need an annotation framework to produce) and Java-style class boilerplate the Rust port collapses into structs + free functions.

@DIALECT NORMALISATION

Each non-MySQL dialect runs a dedicated pre-parse normalizer (src/normalize.rs) so the shared parse_words cascade sees a clean token stream. MySQL needs none — its CREATE TABLE grammar parses directly.

^RUST/LOCO COLTYPE MAPPING

The Loco emitter (src/loco.rs) maps SQL tokens to SeaORM Rust types and the matching Loco ColType for the create_table migration.

Reserved Rust keywords (a column named type / match / move) are emitted as raw identifiers (r#type) so the structs compile without losing the original column name in JSON. tests/loco_keyword_escape.rs pins this; tests/loco_collision_pins.rs pins snake-table collisions, duplicate emission, FK-clobber, and silent-drop edge cases in write_loco_project.

!TEST COVERAGE

Both pipelines carry their own test suite; the Rust suite is grown alongside the port to lock in parity as each module lands.

// RUST INTEGRATION TESTS

// KOTLIN TEST CATEGORIES

Full per-class breakdown lives in README “RUNNING TESTS”. Three tiers:

• Unit — MainTest, UtilTest, KotlinUtilTest, GroovyUtilTest, ColumnToFieldTest, EntityTest, EntityToRESTConstantsTest, EdgeCaseParsingTest, ConfigurationTest, KotlinConfigurationTest, GroovyConfigurationTest: pinpoint per-fn coverage of parsers, type mappers, name transforms.
• Template — TemplatesTest, KotlinTemplatesTest, GroovyTemplatesTest, KotlinEntityFieldDefaultsTest, GroovyEntityFieldsTest, RestRepositoryTemplateTest: pin per-target template emission shape.
• Integration — FullPipelineTest, PostgresqlPipelineTest, SqlitePipelineTest, MssqlPipelineTest, KotlinPipelineTest, GroovyPipelineTest, CustomSqlParsingTest, EmptyEntityListTest, KotlinContentValidationTest, GroovyContentValidationTest, CrossDatabaseLanguageTest: end-to-end pipelines across the dialect × language matrix.

#CI POSTURE

api-rest-generator is in the meta-repo's polish-gates allowlist with all four gates opt-out for the Rust path: fmt, clippy, doc, test. The allowlist entry reads “mid-transition from Kotlin to Rust — Rust code is still the secondary path. Treat as opt-out until the transition completes.” The Kotlin path stays the source of truth; Rust ports land continuously without blocking on Rust-side polish until parity is established.

/PROJECT METADATA