CLI Flag debug

--debug <level>

Status: ✅ Implemented (#54)

Prints the tool's internal logs on stderr, up to the requested level.

Usage

transf-orm --debug <level> <command> ...
transf-orm --debug debug convert schema.prisma > pivot.json
transf-orm convert schema.prisma --debug trace   # global flag: also accepted after the command

<level> is one of error, warn, info, debug, trace (case-insensitive: --debug TRACE works). Any other value prints the list of valid levels and exits with status 2.

Behavior

• Logs go to stderr only: stdout (e.g. the JSON pivot) is unchanged.
• Without the flag, no logger is installed and nothing extra is printed.
• Each level shows its own events and every event of a more severe level:

Level	What you see
error, warn	Nothing yet (no event at these levels)
info	One-line import summary (tables / views / enums) and server startup
debug	+ ORM detection / lookup, file path and size, datasource, number of parsed blocks
trace	+ one line per parsed model, view, enum and type alias

• Lines have no timestamp. Colours are only used when stderr is a terminal: no ANSI codes when it is redirected to a file or piped.
• Can be combined with --verbose.

$ transf-orm --debug debug convert schema.prisma > pivot.json
DEBUG transf_orm_core::registry: detected ORM from extension path="schema.prisma" ext="prisma" orm="prisma"
DEBUG transf_orm_cli: read schema file path=schema.prisma bytes=9645
DEBUG transf_orm_core::importer::prisma: parsed datasource database=PostgreSql
DEBUG transf_orm_core::importer::prisma: parsed Prisma blocks models=11 views=1 enums=3 type_aliases=1
 INFO transf_orm_core::importer::prisma: imported Prisma schema tables=11 views=1 enums=3

Implementation

Logs use the tracing crate:

• Library crates only emit events (tracing::info!, debug!, trace!, ...) and never configure output:
  • crates/core/src/registry.rs — detect and find_by_name;
  • crates/core/src/importer/prisma/mod.rs — parse_schema;
  • crates/cli/src/lib.rs — run_convert;
  • crates/server/src/lib.rs — run.
• The binary installs the subscriber — init_logging in crates/transf-orm/src/main.rs, called by dispatch only when --debug is given. It uses tracing-subscriber's fmt layer writing to stderr, without timestamps, with ANSI enabled only if std::io::stderr().is_terminal().
• DebugLevel (crates/core/src/config.rs) is parsed by FromStr (so core does not depend on clap) and converts into tracing::level_filters::LevelFilter, used as the subscriber's max level.
• Tests: debug_level_maps_to_tracing_filter (unit) and, in crates/transf-orm/tests/dispatch.rs, debug_enables_internal_logs, debug_trace_shows_every_block, debug_error_hides_lower_levels, invalid_debug_level_exits_with_2.

Adding logs

Use structured fields rather than formatted strings, and pick the level by audience:

tracing::info!(tables = schema.tables.len(), "imported Prisma schema"); // summary
tracing::debug!(path, ext, "detected ORM from extension");                // internal step
tracing::trace!(model = %model.name, "parsed model");                    // per item

Never use println! / eprintln! for diagnostics: use tracing for internal details and the --verbose step helper for user-facing progress.

---

← CLI