Skip to content
Typhon

tyc check

tyc check [PATHS]... [--stubs] [--with-ty]

Runs everything up to the analyser — lex, parse, resolve, type-check, purity check, async check, comptime evaluation — without emitting any .py. Exits non-zero if any error-severity diagnostic fires.

Examples

Terminal window
tyc check                 # check the whole project (default: src/)
tyc check src/users.ty    # check a single file
tyc check src/ tests/     # multiple paths
tyc check --stubs         # also diff .dty stubs against their sibling implementation modules
tyc check --with-ty       # also run Astral's `ty` over a throwaway build

What it does

Per file:

  1. Lex + parse through the vendored Ruff parser.
  2. Resolve names; classify let/mut; build scope tree.
  3. Type-check signatures, assignments, narrowing, exhaustiveness, ? validity, etc.
  4. Analyse purity, async correctness, comptime evaluation, auto-gather candidates.

If everything is clean, exits 0 with a one-line checked N file(s) summary. Otherwise, emits miette-formatted diagnostics and exits 1.

--stubs

Additionally parses and type-checks every .dty stub under the checked paths, then diffs each stub’s surface against the sibling implementation module with the same stem — a .ty is preferred over a .py; a stub with no sibling stands alone and is not diffed. Findings surface as tyc::stub_mismatch (missing-in-implementation / missing-in-stub / signature-mismatch) at the severity set by [strictness] stub-check (default "error"). The runtime-introspection counterpart is tyc stubtest.

Terminal window
tyc check --stubs

Useful as a CI gate when you ship .dty stubs.

Flags

FlagEffect
--stubsAlso diff every .dty stub against its sibling .ty / .py implementation.
--with-tyBuild to a temporary directory and run Astral’s ty over the emitted Python as a typeshed-backed second-stage check — the same behaviour as [checker] external = "ty", for one invocation. Requires ty on PATH.

tyc check walks up from the first checked path looking for typhon.toml. To target a different project, pass an explicit path: tyc check path/to/project.

A directory that holds several projects is checked one project at a time. Every subdirectory with its own typhon.toml is checked with that config and its own module set, exactly as tyc check <that directory> would check it, so tyc check examples/ over a folder of independent apps never resolves one app’s from models import Position against another app’s models. Files that belong to no nested project are checked together under the config found for the path you passed.

Exit codes

CodeMeaning
0No errors.
1At least one error-severity diagnostic, or invalid input: a missing path, or a path with nothing to check (no .ty files — an empty directory, a .py-only tree), so a mistyped CI path cannot pass.
2Malformed command line (rejected by the argument parser).

Warning-severity diagnostics do not change the exit code. To gate CI on warnings as well, raise [strictness] levels in typhon.toml.

jobs:
  typhon:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install tyc
        run: |
          cd tyc && cargo build --release
          echo "$PWD/target/release" >> $GITHUB_PATH
      - name: Type-check
        run: tyc check src/
      - name: Stub drift
        run: tyc check --stubs    # if you ship stubs

Where next