Type Checking

The typecheck command performs Hindley-Milner type inference on Python code and reports type errors.

Usage

beacon typecheck [OPTIONS] [PATHS]...

Accepts:

Single file: beacon typecheck file.py
Multiple files: beacon typecheck file1.py file2.py file3.py
Directory: beacon typecheck src/ (recursively finds all .py files)
Stdin: beacon typecheck (reads from stdin)

Options

-f, --format <FORMAT> - Output format (human, json, compact) [default: human]

Output Formats

Human (Default)

Human-readable output with context and visual pointers:

$ beacon typecheck example.py
Found 1 type error(s):

Error 1: Cannot unify types: Int ~ Str (line 3, col 5)
  --> example.py:3:5
   |
 3 | z = x + y
   |     ^

JSON

Machine-readable JSON format for tooling integration:

$ beacon typecheck --format json example.py
{
  "diagnostics": [
    {
      "code": "HM001",
      "file": "example.py",
      "message": "Type mismatch: cannot unify str with int.",
      "severity": "error",
      "span": {
        "end": {
          "col": 17,
          "line": 3
        },
        "start": {
          "col": 5,
          "line": 3
        }
      },
      "tags": []
    }
  ],
  "failures": [],
  "schema_version": 1
}

Compact

Single-line format compatible with editor quickfix lists:

$ beacon typecheck --format compact example.py
example.py:3:5: Cannot unify types: Int ~ Str

Examples

Check a single file

beacon typecheck src/main.py

Check multiple files

beacon typecheck src/main.py src/utils.py tests/test_main.py

Check all files in a directory

beacon typecheck src/

Check with JSON output for CI

beacon typecheck --format json src/ > type-errors.json

Check from stdin

cat src/main.py | beacon typecheck

Exit Codes

0 - No type errors found
1 - Type errors found or analysis failed

Directory Traversal

When a directory is provided, the command:

Recursively discovers all .py files
Respects .gitignore rules
Excludes common patterns: __pycache__/, *.pyc, .pytest_cache/, .mypy_cache/, .ruff_cache/, venv/, .venv/, env/, .env/

Beacon.rs