Flight Compiler

@flighthq/tool-compiler is being built as the shared TypeScript compiler for mechanical ports of the Flight SDK.

The package's intended ownership is the complete source-compilation path:

• Flight workspace, package, export-lane, and symbol analysis
• normalized declaration fingerprints and source provenance
• a target-neutral intermediate representation
• deterministic, identity-based semantic patches and patch audits
• coverage and API inventory models
• compiler orchestration and target-backend infrastructure
• concrete C++, Haxe, and Rust lowering and source emission

flight-hx and flight-rs remain integration targets, and the flight-cpp runtime was incubated here before moving to its own repository. Target repositories retain their ecosystem, project layout, examples, and integration tests; compiler-owned target rules and emitters stay here so every port uses one versioned toolchain.

Development follows Flight's package-per-domain architecture. Private @flighthq/compiler-* workspaces isolate contracts, analysis, provenance, completion, patches, structural semantics, emission, target backends, and orchestration; the public packages/tool-compiler workspace assembles them into one self-contained artifact. The repository root is a private development workspace. Source trees are flat, contracts are centralized in compiler-types, and implementations use functions and plain data instead of classes.

The architecture and health foundation are in place, but the current compiler is not yet a drop-in replacement for the generators in flight-hx or flight-rs. Work proceeds from the dependency floor described in Compiler foundations; the compiler migration roadmap tracks the later parity and extraction sequence.

Install

npm install @flighthq/tool-compiler

The package is not published yet. During extraction, target repositories can install a packed local build after each target reaches its parity gate.

Usage

import { analyzeFlightWorkspace } from '@flighthq/tool-compiler';

const inventory = analyzeFlightWorkspace({
  upstreamDirectory: '/path/to/flight',
});

The upstream directory must be an initialized Flight Git checkout. Analysis is read-only and deterministic for a fixed checkout and compiler version.

Development

npm install
npm run fix
npm run check
npm run test

npm run check runs the static correctness gates, while npm run test runs the unit suite without coverage instrumentation. npm run verify is the explicit full sweep for CI and releases: it adds isolated-package tests, coverage ratchets, emitted-source compilation, behavioral oracles, and package assembly. See AGENTS.md for architecture and contribution rules.

Releases follow an SDK release: the release bridge is the contract that turns a Flight release into a compiler release, including how it is recovered when a dispatch is lost.

License

MIT