efesto-migrate

Codemod deterministico Express → Bun/Elysia per i BaseApiService. Pensato per essere brainless per l'utente: un comando fa tutto il meccanico e segnala — senza indovinare in silenzio — i pochi punti che richiedono giudizio umano.

Uso

# dry-run: report senza scrivere
bunx efesto-migrate ./src/routes --dry

# applica le trasformazioni in-place
bunx efesto-migrate ./src/routes

Lavora in-place: esegui su un repo pulito (git) così rivedi il diff.

Sviluppo nel repo (senza pubblicare): bun packages/migrate/index.ts <dir>. Il pacchetto pubblicato è compilato in packages/migrate/dist/index.js (npm run build).

Principio (perché ci si può fidare)

Asimmetria, non percentuale: può emettere codice che NON gira (errore di compilazione, // EFESTO-TODO), ma mai codice che gira e significa qualcosa di diverso dall'originale. Whitelist di trasformazioni provabilmente equivalenti → automatiche; tutto il resto → marker, codice intatto.

Cosa fa in automatico (AUTO)

• import "efesto" → "efesto/elysia";
• firma handler (req,res,next) → destructuring { body, params, query, headers } dei soli campi usati, solo se req è usato esclusivamente come req.{body,params,query,headers}, res solo dentro return res.json(x), e next mai usato;
• req.<campo> → <campo>, return res.json(x) → return x;
• rimuove i riferimenti ai tipi generati (*Types.*) dalla firma.

Cosa segnala e lascia a te (MARKER // EFESTO-TODO)

• handler non standard (res.status/res.send/res.redirect/next, req.file, accessi non banali a req) → conversione manuale a (ctx) => return value;
• _<verb>Validation in forma express-validator (array) → TypeBox ({ body/query/params }; con multer includi files);
• swaggerModel sul service → spostalo in efesto({ models });
• cache key/purgeKey con identificatori fuori dallo scope Elysia ({ctx,params,query,body,headers,store}), es. allParams, req.*;
• import da express / express-validator da rimuovere.

Dopo il codemod (a mano, una-tantum nel server)

1. risolvi i // EFESTO-TODO;
2. centralizza gli swaggerModel in efesto({ models }) e aggiungi un onError che mappa err.status (vedi example/elysia-project/lib/server.ts);
3. tsc --noEmit, poi avvia e verifica a runtime (cache, upload, errori).

Riferimento completo del mapping: docs/migration-express-to-elysia.md.

Limiti noti (v1)

• il typecheck NON è il gate (Bun non typecheck-a): usa tsc --noEmit;
• l'import di tipi non esportati da efesto/elysia (SwaggerModel) resta danglante → errore tsc loud, adiacente al marker swaggerModel;
• l'auto-rewrite degli handler copre solo la forma standard a metodo; arrow function e firme insolite → marker.