Typebridge

Typebridge is a small, dependency-free checker for mixed Python and TypeScript repositories. It inventories function parameters, return values, variables, class attributes, and TypeScript interface properties; measures annotation coverage; and compares same-named items across languages after normalizing common type spellings.

Install and run

Python 3.10 or newer is required.

python -m pip install typebridge-check
typebridge /path/to/repository

The distribution is named typebridge-check; the installed command is typebridge. Generate a starting configuration in a repository with:

typebridge . --init-config
typebridge . --init-config --force  # replace an existing typebridge.yml

It also runs directly from a source checkout:

PYTHONPATH=src python -m typebridge .
PYTHONPATH=src python -m typebridge . --json
PYTHONPATH=src python -m typebridge . --show-items

Useful command checks:

typebridge --version
typebridge --help

To analyze only Python code reachable from a Django view, API handler, or other callable, pass its import path:

typebridge . --entry myapp.views:get_user
typebridge . --entry myapp.views:UserView.get --json

Entry mode reads pyproject.toml dependencies, locates their installed source without importing them, and follows calls into a dependency only when a reachable function calls that dependency. Calls made by reached dependency functions are followed transitively up to traversal.max_depth and traversal.max_files in typebridge.yml. Uncalled functions—even functions in an already reached file—are not scored. Repository TypeScript remains included so its declarations can be compared with the reachable Python contract.

For each statically resolvable call, Typebridge also compares annotated arguments and literal argument types with the called function's parameter annotations. These call-contract checks contribute to consistency and identify reachable dependency mismatches directly.

Local package roots default to . and src and can be changed with traversal.source_roots. Set traversal.include_installed_dependencies to false to confine traversal to the repository.

Scoring

• Coverage is the percentage of discovered items with an explicit type.
• Consistency is the percentage of cross-language matches whose normalized types agree. It is reported as n/a when there are no matches instead of awarding an artificial perfect score.
• Overall combines those values using the weights in typebridge.yml (40% coverage and 60% consistency by default).

Names are compared after converting camel case to snake case, so getUser.userId matches get_user.user_id. Built-in aliases make types such as Python str/int agree with TypeScript string/number. Add project-specific equivalents under type_aliases in typebridge.yml.

Set scoring.minimum_score to make the command exit with status 1 when the score is too low, which is useful in CI. Parse/configuration failures exit with status 2. JSON output contains every cross-language match and its source location.

This intentionally uses lightweight static parsing rather than invoking mypy or tsc: it measures annotation presence and repository agreement, while those compilers remain responsible for proving language-specific correctness.

Call traversal is also static. Direct calls, imported functions, module attributes, class methods through self, and relative imports are supported. Runtime-generated calls, reflection, monkey-patching, and dependency modules distributed only as compiled extensions cannot be followed safely and are skipped.

Test

PYTHONPATH=src python -m unittest discover -s tests -v

Build a release

python -m pip install -e '.[dev]'
python -m build
python -m twine check dist/*

Upload first to TestPyPI when preparing a release. Publishing requires a PyPI account and API token and is intentionally not performed by the package itself.