Skip to content
Typhon

Workspace Layout

tyc/
├── Cargo.toml                  (workspace root)
├── crates/
│   ├── tyc-syntax/             Typhon lexer/parser
│   ├── tyc-db/                 Salsa database
│   ├── tyc-resolve/            Name resolution, scopes, let/mut
│   ├── tyc-types/              Nominal/structural type checker
│   ├── tyc-analyse/            Purity, async, comptime
│   ├── tyc-desugar/            Typhon AST → Python AST
│   ├── tyc-emit/               Python codegen + .py.map
│   ├── tyc-format/             ruff format wrapper
│   ├── tyc-diagnostics/        miette-based renderer
│   ├── tyc-lsp/                LSP backend
│   ├── tyc-vm/                 in-process tree-walking interpreter (tyc run default)
│   └── tyc/                    CLI binary
└── vendor/                     Typhon's fork of Ruff
    ├── ruff_text_size/
    ├── ruff_source_file/
    ├── ruff_python_trivia/
    ├── ruff_python_ast/        + Mutability extension
    └── ruff_python_parser/     + let/mut soft keywords

Dependency direction

The arrows in the pipeline are the dependency arrows:

tyc-syntax → tyc-resolve → tyc-types → tyc-analyse → tyc-desugar → tyc-emit → tyc-format
                              ↓
                         tyc-diagnostics (everyone)
                              ↓
                          tyc-db (everyone needing incremental cache)
                              ↓
                          tyc-lsp (everyone above)
                              ↓
                            tyc (everyone)

tyc-diagnostics and tyc-db are shared infrastructure; everyone else is on the pipeline.

Per-crate notes

tyc-syntax

Re-exports the vendored ruff_python_ast and ruff_python_parser. Public surface: parse_module(&str) -> Result<Mod, ParseError>. Adds the Mutability enum and the assignment-node extension.

tyc-db

Salsa database root. Exposes input queries (set_source(file, text)), tracked queries (preprocessed_text, module_decl_names, resolved_module), and the cancellation primitives. Every other crate that needs caching goes through this.

tyc-resolve

Walks Mod to build a ResolvedModule. Independent of types — purely scopes and binding kinds.

tyc-types

The biggest crate. Implements the type checker: assignment compatibility, narrowing, generic inference, structural conformance, sealed-union exhaustiveness, ? validity.

tyc-analyse

Purity, async correctness, comptime evaluation, auto-gather candidates. Each is a Salsa-tracked function.

tyc-desugar

Typhon AST → Python AST. Owns the lowering tables for gather:, go, lazy, comptime, extend, Result?.

tyc-emit

Hand-written pretty-printer. Records per-statement (out_line → ty_line) for .py.map v2.

tyc-format

Composes an in-process whitespace pass with an optional ruff format wrap (when on PATH and the post-pass buffer contains no Typhon-only tokens). One function, one concern.

tyc-diagnostics

Every diagnostic code is registered here. Search tyc::CODE_NAME to find every emission site. Each variant carries a url(https://github.com/CodeHalwell/Typhon/blob/main/docs/diagnostics/<code>.md) clause for miette’s deep-link rendering.

tyc-lsp

tower-lsp-server backend. Reuses the same Salsa DB as the CLI.

tyc-vm

In-process tree-walking interpreter for .ty source. Default execution mode for tyc run — no build/ directory, no CPython spawn. Reuses the preprocess + parse pipeline from tyc-syntax and walks the AST with a Rust environment. Native support covers core language, Result[T, E], dunder dispatch / rich comparisons on user instances (v0.10.0), finite generators via eager materialisation (v0.10.0), type(x) as a real type object (v0.10.0), Value::Complex + dict-view (v0.11.0), __call__ / __post_init__ / multi-level MRO field accumulation (v0.11.0), bare super() rewritten to two-arg form in tyc-desugar so @dataclass(slots=True) works (v0.11.0), ~50 builtins, math / os / sys / json / time / random shims, native enum / datetime / pathlib / collections.defaultdict shims (v0.11.0), and str / list / dict / set / bytes methods. Value semantics align with CPython since v0.11.0 (dataclass eq / repr / hash is value-based with class-identity keying, set equality is order-independent, float repr matches CPython’s shortest round-tripping form). Unsupported features (async, lazy / unbounded generators, tz-aware datetime, full CPython stdlib) raise NotImplementedError at runtime with a pointer to --compile.

tyc

The clap-based CLI. Wires everything together.

Where to start if you’re contributing

  • Bug in type inference? tyc-types.
  • Bug in lowering? tyc-desugar.
  • Bug in emitted Python format? tyc-emit.
  • Bug in diagnostic wording? tyc-diagnostics plus the call site.
  • tyc run produces wrong result without --compile? tyc-vm.
  • tyc fmt produces wrong whitespace? tyc-format.
  • New CLI flag? tyc/crates/tyc.
  • Salsa cache invalidation? tyc-db.

Where next