feat: experimental typechecker

.gitignore

@@ -44,6 +44,8 @@ node_modules
 !/benches/js/results/report.conformance.bun.md
 !/benches/js/results/report.json
 !/benches/js/results/report.md
+!/benches/js/results/report.tsc-conformance.json
+!/benches/js/results/report.tsc-conformance.md
 
 # Env
 .env*

CLAUDE.md

@@ -151,7 +151,7 @@ cargo run -p tsv_cli format --content '<div>x</div>' --parser svelte     # forma
 
 ```bash
 deno task check          # full committed-tree gate: fmt, audits, typecheck, tests, clippy (benches/js/CLAUDE.md §Gate map)
-deno task doctor         # one-pass setup check: runtimes, canonical pins + checkout alignment, node_modules freshness, oracle checkouts, corpus entries, build artifacts. Exit 1 only on MISLEADING state (pin drift, skew, stale deps); absences are warnings (--strict promotes warnings to failures)
+deno task doctor         # one-pass setup check: runtimes, canonical pins + checkout alignment, node_modules freshness, oracle checkouts, corpus entries, build artifacts. Exit 1 only on MISLEADING state (pin drift, skew, stale deps); absences are warnings (--strict promotes warnings to failures) — except in the explicitly optional experimental-typechecker tier, whose absences are informational at any strictness (a BROKEN checkout there still warns)
 deno task typecheck      # cargo check
 deno task test           # cargo test
 deno task lint           # cargo clippy
@@ -331,11 +331,11 @@ deno task conformance:ts-repo          # tsv's TS parser vs the tsc corpus (../t
 
 # The three gates above accept: -v, --json, <subtree>.
 
-deno task conformance                  # the pre-release aggregate: the three gates above + corpus:compare:parse
-# --all + corpus:compare:format --all, in ONE process (benches/js/conformance.ts; oracle modules load
-# once, fail-fast, corpus FFI built once), then render:audit over the version-pinned checkouts (a
-# subprocess — it drives its own sidecar). The external-oracle correctness gates that can't live in
-# `deno task check`. The format leg's prettier calls ride a content-addressed cache
+deno task conformance                  # the pre-release aggregate: the three gates above +
+# corpus:compare:parse --all + corpus:compare:format --all, in ONE process (benches/js/conformance.ts;
+# oracle modules load once, fail-fast, corpus FFI built once), then render:audit over the version-pinned
+# checkouts (a subprocess — it drives its own sidecar). The external-oracle correctness gates that
+# can't live in `deno task check`. The format leg's prettier calls ride a content-addressed cache
 # (benches/js/lib/prettier_cache.ts; TSV_PRETTIER_CACHE=0 disables).
 
 deno task conformance:test262          # tsv's JS parser vs test262 POSITIVES (pure Rust, `test262 --gate`);
@@ -514,6 +514,7 @@ tsv/
 │   ├── tsv_css/     # CSS: parse(), format(), convert_ast_json_bytes()
 │   ├── tsv_svelte/  # Svelte: parse(), format(), convert_ast_json_bytes()
 │   ├── tsv_svelte_compile/ # Svelte→JS compiler (Svelte's compile() oracle) + JS canonicalizer (intent-erased reprint); consumed by tsv_debug — no shipped artifact links it
+│   ├── tsv_check/   # EXPERIMENTAL TypeScript binder + checker — may never ship (tsgo-conformance target; consumed only by tsv_debug — no shipped artifact links it)
 │   ├── tsv_cli/     # Production CLI (binary: tsv) - pure Rust
 │   ├── tsv_debug/   # Dev utilities (binary: tsv_debug) - uses Deno
 │   ├── tsv_ffi/     # C FFI bindings (Deno's native path)
@@ -867,10 +868,28 @@ cargo run -p tsv_debug test262 language/expressions  # filter by path pattern
 
 See ./docs/conformance_test262.md (command interface; §Differential for the tsv-vs-oxc comparison).
 
+**Typechecker conformance (`tsc_conformance`) — EXPERIMENTAL, may never ship.**
+`tsv_check` is a from-scratch TypeScript binder + checker in development; no shipped
+artifact links it (`cargo tree -i tsv_check` → only `tsv_debug`), and the parser and
+formatter are never modified in service of it. `tsv_debug tsc_conformance` grades it
+against tsgo's committed `.errors.txt` baselines (`../typescript-go`, pin `168e7015`),
+surfaced as **on-demand** tasks:
+
+```bash
+deno task conformance:tsc-roundtrip     # baseline parse → re-render → byte-compare (zero checker code)
+deno task conformance:tsc-check         # the tsv_check conformance sweep + committed report
+deno task conformance:tsc-check:update  # re-pin the run's snapshot counts after deliberate drift
+```
+
+None is in `deno task check`, in `deno task conformance`, or release-gating, and
+`../typescript-go` is not a release-required oracle — until the typechecker ships, no
+ordinary dev or release flow pays for it. Full reference: ./docs/typechecker.md.
+
 **Performance Profiling Commands** (all pure Rust, no Deno — full reference: ./docs/performance.md):
 
 ```bash
 cargo run -p tsv_debug profile ~/dev/zzz/src/lib                    # parse vs format phase timing (--iterations, --json)
+cargo run -p tsv_debug profile --bind ~/dev/zzz/src                 # parse vs lower+bind timing (TS-only) + peak RSS (§1)
 cargo run --release -p tsv_debug -- json_profile ~/dev/zzz/src/lib  # FFI parse path: parse vs the wire-JSON write (§2)
 cargo run -p tsv_debug buffer_sizes ~/dev/zzz/src ~/dev/gro/src     # printer SmallVec sizing histograms (§8)
 cargo run -p tsv_debug arena_stats ~/dev/zzz/src/lib                # DocArena node-population + memory audit (§7; --reuse, --list-errors)
@@ -1059,13 +1078,13 @@ cases; prettier, oxfmt and biome all get the JSDoc-cast paren binding wrong —
 ### Rust Crates (minimal deps)
 
 - `serde_json` — wire-JSON emission: the writer's exact string-escape / `f64` formatting, and reparsing bytes to a `Value` (CLI `--pretty`, tests). The language crates no longer depend on `serde` directly (only transitively, without its `derive`); `serde`'s derive is dev-tooling only (`tsv_debug` / `tsv_cli`)
-- `smallvec` — Stack-allocated vectors
+- `smallvec` — Stack-allocated vectors (printers + `tsv_check`)
 - `thiserror` — Error type derivation
 - `phf` — Compile-time perfect hash maps (keywords, entities)
 - `unicode-ident` — Unicode XID_Start/XID_Continue for identifiers
 - `unicode-segmentation` — Grapheme clustering for visual width measurement
 - `unicode-width` — Character display width (CJK, zero-width)
-- `bumpalo` — Bump arena for the internal AST (and, via the `tsv_arena` crate, the bindings' per-thread `reset()` reuse — `tsv_ffi`/`tsv_napi`/`tsv_wasm`)
+- `bumpalo` — Bump arena for the internal AST (and, via the `tsv_arena` crate, the bindings' per-thread `reset()` reuse — `tsv_ffi`/`tsv_napi`/`tsv_wasm`; `tsv_check`'s caller-owned check arenas follow the same contract)
 - `talc` — WASM global allocator (`tsv_wasm` only, wasm32-only target dep): pure-Rust `no_std` allocator replacing std's default dlmalloc; the `WasmGrowAndExtend` source keeps the warm instance's linear-memory high-water at dlmalloc parity. Pulls `lock_api` + `allocator-api2` (+ `scopeguard`) into the wasm32 graph only; native builds unaffected
 - `napi` / `napi-derive` / `napi-build` — N-API bindings for `tsv_napi` (Node/Bun native addon; tsv-scoped carve-out)
 
@@ -1111,6 +1130,7 @@ formatting behavior. Key files: `src/language-js/print/assignment.js` (assignmen
 - ./docs/comments.md - the detached comment model: ownership, the three axes, hazards, emitters
 - ./docs/compile_tooling.md - the sidecar-dependent compiler harnesses: corpus compare, compile fuzz, erase census
 - ./docs/compile_validation_ratchet.md - the validation-suite ratchet: snapshot, kinds, verdict, triage
+- ./docs/typechecker.md - the experimental `tsv_check` typechecker (may never ship) + its on-demand tsgo-conformance harness
 - ./docs/performance.md - profiling methodology, tooling, and results tracking
 - ./docs/workflow_corpus.md - corpus-driven formatting conformance workflow
 - ./docs/workflow_test262.md - test262 conformance workflow

Cargo.toml

@@ -10,6 +10,7 @@ members = [
     "crates/tsv_css",
     "crates/tsv_svelte",
     "crates/tsv_svelte_compile",
+    "crates/tsv_check",
     "crates/tsv_cli",
     "crates/tsv_debug",
     "crates/tsv_wasm",
@@ -49,6 +50,11 @@ tsv_svelte = { path = "crates/tsv_svelte", default-features = false }
 # no shipped artifact links it yet.
 tsv_svelte_compile = { path = "crates/tsv_svelte_compile" }
 
+# Experimental TypeScript type-checking. A consumer crate of tsv_ts's concrete
+# types; referenced only by the tsv_debug harness so it never touches the
+# shipped format/parse artifacts (a crate-boundary zero-cost exclusion).
+tsv_check = { path = "crates/tsv_check" }
+
 # External dependencies
 argh = "0.1"
 # N-API (Node.js/Bun) bindings — the native path for the `tsv_napi` crate, the

README.md

@@ -76,6 +76,7 @@ Future features (unknown order):
     - svelte-check replacement
     - LSP
     - linter - type aware, initially focused on serializable data-only plugins for extensibility
+    - includes an experimental first-party typechecker `tsv_check` (which may never ship)
   - bundling is probably out of scope 
   - [discussion](https://github.com/fuzdev/tsv/discussions) welcome
 
@@ -260,6 +261,7 @@ tsv/
 │   ├── tsv_ts/        # TypeScript parser/formatter (standalone)
 │   ├── tsv_css/       # CSS parser/formatter (standalone)
 │   ├── tsv_svelte/    # Svelte parser/formatter (uses tsv_ts + tsv_css)
+│   ├── tsv_check/     # experimental TypeScript binder/checker (may never ship; not in any shipped artifact)
 │   ├── tsv_cli/       # unified CLI (binary: `tsv`)
 │   ├── tsv_debug/     # dev utilities (binary: `tsv_debug`, uses Deno)
 │   ├── tsv_ffi/       # C FFI bindings

benches/js/CLAUDE.md

@@ -454,23 +454,27 @@ green-skipping (the baselines are the oracle; publish Step 3b's probe is the
 tolerance point). Full-corpus runs freshness-check `KNOWN_GAPS` (stale entries fail).
 
 **Pre-release aggregate — `deno task conformance` (+ `conformance:test262` = `conformance:all`).** The three parse-conformance
-gates (svelte-fixtures, ts-fixtures, ts-repo), plus
-`corpus:compare:parse --all` and `corpus:compare:format --all`, are the
-release-cadence correctness gates that run against external JS oracles (and so can't
-live in `deno task check`). `deno task conformance:all` runs the pure-Rust **test262
+gates (svelte-fixtures, ts-fixtures, ts-repo), plus `corpus:compare:parse --all`
+and `corpus:compare:format --all`, are the release-cadence correctness gates that
+run against external oracles (and so can't live in `deno task check`). The
+typechecker's `tsc_conformance` tasks are deliberately NOT legs here — `tsv_check`
+is experimental and may never ship, so its gates stay on-demand (see
+../../docs/typechecker.md). `deno task conformance:all` runs the pure-Rust **test262
 positive gate** FIRST (`conformance:test262` — `tsv_debug test262 --gate`, gating the
 exact positive-pass count; the ~2.5k negatives are the deferred early-error frontier,
 reported not gated), THEN the aggregate — fail-fast, so a positive-parse regression
 trips the ~1-min gate before the multi-minute FFI legs run. That superset is what
 publish Step 3b runs. `deno task conformance` builds the corpus FFI once and
-runs all five legs in **ONE process** (`conformance.ts`, the driver): the canonical
+runs all six legs in **ONE process** (`conformance.ts`, the driver): the canonical
 oracle modules (prettier, the svelte plugin, svelte/compiler, acorn, acorn-ts) load
-once via the module cache instead of once per leg, each leg gets a timing line, and
-failure semantics match a `&&` chain exactly (every leg exits the process on a
-finding — fail-fast). The driver takes no arguments; the per-leg tasks remain the
-scoped/triage entries. `conformance:all` is wired into `scripts/publish.ts` **Step 3b**
-(skipped by `--no-check`). Step 3b preflights the oracles (`../svelte`,
-`../acorn-typescript`, `../typescript`, `../test262`, this dir's `node_modules`): a missing one
+once via the module cache instead of once per leg (`render:audit`, the lone non-JS
+leg, is a `cargo` subprocess — which is why the task carries `--allow-run=cargo`),
+each leg gets a timing line, and failure semantics match a `&&` chain exactly
+(every leg exits the process on a finding — fail-fast). The driver takes no
+arguments; the per-leg tasks remain the scoped/triage entries. `conformance:all`
+is wired into `scripts/publish.ts` **Step 3b** (skipped by `--no-check`). Step 3b
+preflights the oracles (`../svelte`, `../acorn-typescript`, `../typescript`,
+`../test262`, this dir's `node_modules`): a missing one
 **FAILS a `--wetrun`** (only the explicit `--no-check` releases without gates),
 warn-and-skips a dry-run, and any skip is re-warned in the run's final summary.
 The gates themselves fail closed on a missing checkout (0 scanned = FAIL), so a
@@ -510,6 +514,17 @@ every real move in a number is a deliberate, visible edit.
   test262 (discovered + graded-manifest), `fixtures_validate` (total fixtures —
   protects the primary gate against a discovery collapse), and `swallow_audit`
   (formatted files — closes its vacuous-pass).
+- `tsc_conformance` (the largest set) splits its pins by what they mean, and
+  gates the ON-DEMAND experimental-typechecker tasks, not a release leg. The
+  drifting tsv-side counts (denominators, parse-divergence census, family
+  partitions, carve-outs) live in the machine-regenerated snapshot
+  `crates/tsv_debug/src/cli/commands/tsc_conformance_pins.txt`, rewritten by
+  `deno task conformance:tsc-check:update`. The oracle-side pins
+  (baseline/roundtrip/pretty + the `INDEX_*` denominators) and the
+  semantically-zero invariant gates stay hand-edited consts in
+  `cli/commands/tsc_conformance/pins.rs`; the crash-exclusion count sits beside its
+  ledger in `tsc_conformance/runner/grade.rs`. Re-pin ritual:
+  ../../docs/typechecker.md.
 
 **Semantics — three pin categories, chosen per surface:**
 
@@ -793,9 +808,9 @@ deno task bench:deno:run -- --compare-baseline  # Compare against saved baseline
 
 # Wipe local-only bench state (gitignored): baseline.json, timestamped
 # results pairs, and the harvest caches (benches/js/.cache). Preserves the
-# committed `report.<runtime>.{json,md}` / `report.conformance.node.*`
-# because the glob is anchored on a leading digit (timestamped files start
-# with a year).
+# committed `report.<runtime>.{json,md}` / `report.conformance.node.*` /
+# `report.tsc-conformance.{json,md}` because the glob is anchored on a
+# leading digit (timestamped files start with a year).
 deno task bench:clean
 
 # Environment variables (apply to any runtime's :run)
@@ -1232,7 +1247,7 @@ benches/js/
 ├── install_deps.ts        # `bench:install`: npm install + force-fetch the oxc wasi binding
 ├── harvest_test262.ts     # `bench:harvest:test262`: graded positives → .cache/test262_files.json (Deno-only)
 ├── bench.ts               # Benchmark entry point (runtime-neutral — runs under Deno AND Node)
-├── conformance.ts         # Single-process pre-release aggregate driver (deno task conformance): all five legs, one module cache
+├── conformance.ts         # Single-process pre-release aggregate driver (deno task conformance): all six legs, one module cache
 ├── smoke.ts               # Smoke test for formatters and parsers (runtime-neutral: smoke / smoke:node / smoke:bun)
 ├── compose_reports.ts     # Fold report.{deno,node,bun}.json → combined report.{json,md} (bench:compose)
 ├── idempotency_sweep.ts   # F1 sweep over the `perf` corpus view — format(format(x)) == format(x) on real code (deno task idempotency:sweep; drives tsv_debug `fuzz --iterations 0`)