Skip to main content
The parity audit measures how closely the Python port mirrors the structure and inventory of the original TypeScript source. It checks root-level file coverage, top-level subsystem names, and command/tool entry counts — giving a concrete view of where the port stands.

​
What it checks

Root file surface

Compares the 18 expected root-level Python files against what is actually present in src/. Each .ts → .py mapping is defined in ARCHIVE_ROOT_FILES.

Top-level subsystems

Checks that the 30 expected top-level directory/module names listed in ARCHIVE_DIR_MAPPINGS exist in src/.

Command inventory

Counts entries in reference_data/commands_snapshot.json and compares against reference_data/archive_surface_snapshot.json’s command_entry_count.

Tool inventory

Counts entries in reference_data/tools_snapshot.json and compares against archive_surface_snapshot.json’s tool_entry_count.
The audit also counts total Python files in src/ and compares that against the archived TypeScript-like file count stored in archive_surface_snapshot.json.

​
Running the audit

python3 -m src.main parity-audit
Output is a Markdown report. Example when the archive is present: 
# Parity Audit

Root file coverage: **16/18**
Directory coverage: **28/30**
Total Python files vs archived TS-like files: **54/312**
Command entry coverage: **87/87**
Tool entry coverage: **42/42**

Missing root targets:
- dialogLaunchers.py
- replLauncher.py

Missing directory targets:
- native_ts
- voice

​
When the archive is absent

The TypeScript archive (archive/claude_code_ts_snapshot/) is locally ignored and not tracked in the repository. If the directory does not exist, the audit reports this and exits cleanly without error: 
# Parity Audit
Local archive unavailable; parity audit cannot compare against the original snapshot.
The archive_present field in ParityAuditResult controls which output branch is taken. All coverage metrics still derive from the committed reference data files (reference_data/*.json), so command and tool ratios are always available even without the live archive tree.

​
How port_manifest.py drives the analysis

build_port_manifest() walks src/ and builds a PortManifest that enumerates every Python file and groups them into top-level modules. The parity audit uses CURRENT_ROOT (the src/ directory) directly rather than the manifest, but both share the same source of truth. The three reference data files consumed by the audit are:
FileContents
src/reference_data/archive_surface_snapshot.jsonTop-level counts: total_ts_like_files, command_entry_count, tool_entry_count
src/reference_data/commands_snapshot.jsonArray of mirrored command entries
src/reference_data/tools_snapshot.jsonArray of mirrored tool entries
These files are committed to the repository and version-controlled independently of the live archive, so parity ratios are reproducible on any checkout.

​
Interpreting the output

The audit maps each TypeScript root file to its expected Python equivalent (e.g. QueryEngine.ts → QueryEngine.py). A hit means the file exists anywhere in src/; it does not validate the file’s contents or completeness.Current checkpoint: The Python port mirrors the full root-entry file surface. Missing entries appear in the Missing root targets section.
Top-level TypeScript subdirectories (e.g. assistant/, bootstrap/, cli/) are mapped to their Python equivalents. Some map to a single .py file rather than a directory (e.g. commands/ → commands.py).Current checkpoint: Top-level subsystem names are mirrored. Gaps appear in Missing directory targets.
Command and tool coverage compares snapshot entry counts. A ratio of 87/87 means every command entry from the TypeScript snapshot has a corresponding Python entry.Current checkpoint: Command and tool inventories are at parity with the archived snapshot.
This is the broadest gap metric. The Python port has far fewer total files than the archived TypeScript source because the port has not yet replicated every runtime execution slice.Current checkpoint: The port has fewer executable runtime slices than the archived source. This ratio is expected to improve as more subsystems are ported.

​
ParityAuditResult dataclass

@dataclass(frozen=True)
class ParityAuditResult:
    archive_present: bool
    root_file_coverage: tuple[int, int]      # (hits, total)
    directory_coverage: tuple[int, int]      # (hits, total)
    total_file_ratio: tuple[int, int]        # (python_files, ts_like_files)
    command_entry_ratio: tuple[int, int]     # (python_entries, ts_entries)
    tool_entry_ratio: tuple[int, int]        # (python_entries, ts_entries)
    missing_root_targets: tuple[str, ...]
    missing_directory_targets: tuple[str, ...]
Call result.to_markdown() to get the formatted report string.

Build docs developers (and LLMs) love

Get started for freeTalk to us