jsaw-core

jsaw-core is a compiler framework for ECMAScript (JavaScript) that provides multiple intermediate representations (IR) for optimization and code generation. It transforms JavaScript/ECMAScript code through several lowering stages, from high-level syntax to optimized intermediate forms suitable for various compilation targets.

Overview

jsaw-core provides a multi-stage compilation pipeline for JavaScript:

1. Source Parsing: Using SWC (Speedy Web Compiler) to parse JavaScript/TypeScript
2. Control Flow Graph (CFG): Converts parsed AST into control flow graphs
3. Three-Address Code (TAC): Lowers CFG to three-address code representation
4. Static Single Assignment (SSA): Transforms TAC into SSA form for optimization
5. Optimizations: Performs various optimizations on SSA form
6. Code Generation: Targets various backends (WebAssembly, native code, etc.)

Architecture

The project is organized as a Cargo workspace with several crates, each handling a specific compilation stage:

Core Crates

• portal-jsc-common: Common types and utilities used across all stages

  • Native function definitions
  • Semantic configuration
  • Syntax helpers

• swc-cfg: Control Flow Graph representation

  • Converts JavaScript AST to CFG
  • Basic block structure
  • Control flow analysis

• swc-tac: Three-Address Code intermediate representation

  • Converts CFG to TAC
  • Single-assignment form (not SSA yet)
  • Statement-based IR with explicit control flow

• swc-ssa: Static Single Assignment form

  • Converts TAC to SSA
  • Φ-functions for merging values
  • Block parameters for SSA invariants

• swc-opt-ssa: SSA-level optimizations

  • Constant propagation
  • Dead code elimination
  • Other optimization passes

Utility Crates

• swc-util: Shared utilities for SWC-based transformations

  • Type utilities
  • Import mapping
  • Semantic analysis helpers

• swc-ll-common: Low-level common utilities

  • Shared types for lower-level IRs
  • Fetching and resolution helpers

• simpl-js: Legacy Simpl dialect AST package

  • Legacy AST implementation for the "Simpl" JavaScript subset
  • Provides dialect-specific AST types and transformations

Applications

• portal-jsc-generator: Native bindings generator
  • Generates TypeScript/JavaScript bindings for native functions
  • Creates intrinsics based on definitions in portal-jsc-common/src/natives.rs
  • Does not depend on or use most of the compilation pipeline

Building

# Build all crates
cargo build

# Build in release mode
cargo build --release

# Run tests
cargo test

Usage

The typical compilation flow:

1. Parse JavaScript source using SWC
2. Convert to CFG using swc-cfg
3. Lower to TAC using swc-tac
4. Transform to SSA using swc-ssa
5. Optimize using swc-opt-ssa (optional - can be skipped for different optimization strategies)
6. Generate target code

Note on swc-opt-ssa: This stage can be skipped if different optimizations are needed. Most generic optimizations are already implemented in swc-tac and swc-ssa. Pipelines targeting JavaScript output may benefit from skipping swc-opt-ssa as it can currently increase code size.

Example using the generator:

cargo run --bin portal-jsc-generator -- [options] <input.js>

Intermediate Representations

TAC (Three-Address Code)

TAC represents computations as a sequence of simple statements, each with at most one operator:

• TFunc: Function representation with entry block and parameters
• TCfg: Control flow graph with basic blocks
• TBlock: Basic block containing statements
• TStmt: Individual statement (assignment, call, etc.)
• TTerm: Block terminator (return, jump, conditional, etc.)

SSA (Static Single Assignment)

SSA form ensures each variable is assigned exactly once:

• SFunc: Function in SSA form
• SCfg: SSA control flow graph
• SBlock: SSA basic block with block parameters
• SValue: SSA values (parameters, operations, loads, stores)
• STerm: SSA block terminators with target blocks and arguments

Key Features

• Multiple IR Levels: Gradual lowering from high-level to low-level representations
• Type Preservation: Optional TypeScript type annotations preserved through pipeline (work-in-progress)
• Optimization Infrastructure: Framework for implementing analyses and transformations
• Extensible: Designed to support multiple compilation targets
• No Unsafe: Safe Rust throughout (as per project requirements)

License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0). See the workspace Cargo.toml for details.

Contributing

This is part of the Portal Compiler Organization projects. Contributions should maintain:

• Safe Rust (no unsafe blocks)
• Minimal API changes
• Comprehensive documentation
• Clear commit history

Related Projects

• SWC (Speedy Web Compiler): The underlying JavaScript/TypeScript parser
• codegen-utils: Shared utilities for SSA and CFG traits

Status

Version 0.8.0-pre.9 - Pre-release development version. APIs may change between pre-release versions.

Goals

• Provide a multi-stage compilation pipeline for ECMAScript
• Support SWC-based parsing and IR lowering

Progress

• Core compiler crates implemented (swc-cfg, swc-ssa, swc-tac)
• Documentation for architecture and usage provided

AI assisted

lib.rs:

Utilities for working with SWC (Speedy Web Compiler) ASTs.

This crate provides helper functions and traits for working with SWC's JavaScript AST, including semantic analysis, native function resolution, and import mapping.

Key Features

• Semantic configuration for controlling compilation behavior
• Native function recognition and resolution
• Import mapping for module resolution
• Constant evaluation for SES (Secure ECMAScript) methods

Main Types

• SemanticCfg: Configuration for semantic analysis
• ResolveNatives: Trait for resolving native/intrinsic functions
• ImportMapper: Trait for custom import resolution