Metadata-Version: 2.4
Name: typebridge-check
Version: 0.0.1
Summary: Score Python and TypeScript typing consistency in mixed repositories
Author: Typebridge contributors
License-Expression: MIT
Keywords: typing,typescript,python,django,static-analysis,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: build>=1.5.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# 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.

```bash
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:

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

It also runs directly from a source checkout:

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

Useful command checks:

```bash
typebridge --version
typebridge --help
```

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

```bash
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

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

## Build a release

```bash
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.
