tsz-org TSZ Tracing
Use tracing before adding debug prints. It is for conformance failures, inference/narrowing/assignability surprises, and runtime path discovery.
Commands
TSZ_LOG=debug TSZ_LOG_FORMAT=tree cargo run -p tsz-cli -- file.ts
TSZ_LOG=debug TSZ_LOG_FORMAT=json cargo run -p tsz-cli -- file.ts
TSZ_LOG="tsz_solver=trace,tsz_checker=debug" TSZ_LOG_FORMAT=tree cargo run -p tsz-cli -- file.ts
TSZ_LOG="tsz_solver::narrowing=trace" TSZ_LOG_FORMAT=tree cargo run -p tsz-cli -- file.ts
Use RUST_LOG only as fallback. TSZ_LOG_FORMAT values: tree, json,
text.
Workflow
- Reduce to the smallest
.tswitness. - Compare expected behavior with
npx tsc --noEmit file.ts. - Start broad (
debug, tree), then narrow by module. - Capture large traces with
2> trace.log,head,tail,rg, orgrep "type_id=<id>". - Use structured trace fields and spans; never add ad-hoc stdout/stderr debugging.
Useful Filters
- Narrowing:
TSZ_LOG="tsz_solver::narrowing=trace". - Relations/inference:
TSZ_LOG="tsz_solver=debug". - Checker lookup/cache:
TSZ_LOG="tsz_checker=debug". - Query events:
TSZ_LOG=tsz::query_json=trace TSZ_LOG_FORMAT=json.
Read Output
Tree output nests spans, shows elapsed ms, level, module path, event, and fields. Look for the first structural divergence: wrong narrowed member, unexpected relation result, missing lazy ref resolution, cache hit/miss, or diagnostic source-span decision.
Tracing goes to stderr and is initialized only when TSZ_LOG/RUST_LOG is set.
For trace examples and quick reminders, read QUICKREF.md.