Auto,

Always,

Never,

Bytecode,

RuntimeBytecode,

Ir,

Abi,

Metadata,

static VERSION: OnceLock<String> = OnceLock::new();

VERSION

.get_or_init(|| match option_env!("FE_GIT_HASH") {

Some(hash) if !hash.is_empty() => format!("{} ({hash})", env!("CARGO_PKG_VERSION")),

_ => env!("CARGO_PKG_VERSION").to_string(),

})

.as_str()

/// Control colored output (auto, always, never).

#[arg(long, global = true, value_enum, default_value = "auto")]

pub color: ColorChoice,

#[command(subcommand)]

pub command: Command,

/// Optimization level.

///

/// 0 = none

/// 1 = fast compilation, usually close to `2` gas and bytecode size with Sonatina

/// 2 = optimizes heavily for runtime gas

/// s = size-oriented (currently similar to `2`)

///

/// Defaults to `1`

///

#[arg(

optimize: Option<String>,

fn as_deref(&self) -> Option<&str> {

self.optimize.as_deref()

}

/// Compile Fe code to EVM bytecode.

Build {

/// Path to an ingot/workspace directory (containing fe.toml), a workspace member name, or a .fe file.

#[arg(default_value_t = default_project_path())]

path: Utf8PathBuf,

/// Build artifacts for a single workspace ingot by member name.

///

/// This requires targeting a workspace root path.

#[arg(short = 'i', long = "ingot", value_name = "INGOT")]

ingot: Option<String>,

/// Treat a `.fe` file target as standalone, even if it is inside an ingot.

#[arg(long)]

standalone: bool,

/// Rebuild from a `<Contract>.metadata.json` recompilation input produced by

/// `--emit metadata` (`-` reads the JSON from stdin).

///

/// The recorded project is materialized into a temporary directory and built with

/// the settings captured in the metadata. Artifacts default to `./out`.

#[arg(

from_metadata: Option<Utf8PathBuf>,

/// Build a specific contract by name (defaults to all contracts in the target).

#[arg(long)]

contract: Option<String>,

#[command(flatten)]

optimize: OptimizeArgs,

/// Output directory for artifacts.

#[arg(long)]

out_dir: Option<Utf8PathBuf>,

/// Compilation profile to use when resolving profile-aware config.

#[arg(long, default_value = "release", value_name = "PROFILE")]

profile: String,

/// Comma-delimited artifacts to emit.

#[arg(

emit: Vec<BuildEmit>,

/// Write a debugging report as a `.tar.gz` file (includes sources, IR, backend output, and bytecode artifacts).

#[arg(long)]

report: bool,

/// Output path for `--report` (must end with `.tar.gz`).

#[arg(

report_out: Utf8PathBuf,

/// Only write the report if `fe build` fails.

#[arg(long, requires = "report")]

report_failed_only: bool,

/// Use recovery mode when parsing.

#[arg(long, default_value = "false")]

recovery_mode: bool,

},

Check {

#[arg(default_value_t = default_project_path())]

path: Utf8PathBuf,

/// Check a single workspace ingot by member name.

///

/// This requires targeting a workspace root path.

#[arg(short = 'i', long = "ingot", value_name = "INGOT")]

ingot: Option<String>,

/// Treat a `.fe` file target as standalone, even if it is inside an ingot.

#[arg(long)]

standalone: bool,

/// Compilation profile to use when resolving profile-aware config.

#[arg(long, default_value = "dev", value_name = "PROFILE")]

profile: String,

#[arg(long)]

dump_mir: bool,

/// Write a debugging report as a `.tar.gz` file (includes sources and diagnostics).

#[arg(long)]

report: bool,

/// Output path for `--report` (must end with `.tar.gz`).

#[arg(

report_out: Utf8PathBuf,

/// Only write the report if `fe check` fails.

#[arg(long, requires = "report")]

report_failed_only: bool,

/// Use recovery mode when parsing.

#[arg(long, default_value = "false")]

recovery_mode: bool,

},

/// Generate documentation for a Fe project

Doc {

/// Path to a .fe file or ingot directory

#[arg(default_value_t = default_project_path())]

path: Utf8PathBuf,

/// Output directory for generated docs

#[arg(short, long)]

output: Option<Utf8PathBuf>,

/// Include builtin ingots (core, std) in generated docs

#[arg(long)]

builtins: bool,

/// Load core/std from a directory on disk instead of the embedded version.

/// The directory should contain `core/` and `std/` subdirectories.

#[arg(long)]

stdlib_path: Option<Utf8PathBuf>,

/// Include `#[test]` functions in generated docs.

///

/// Off by default to keep sidebars focused on the public API surface;

/// turn on for a test-centric overview of an ingot.

#[arg(long)]

include_tests: bool,

#[command(subcommand)]

action: Option<DocAction>,

},

#[cfg(not(target_arch = "wasm32"))]

Tree {

#[arg(default_value_t = default_project_path())]

path: Utf8PathBuf,

},

/// Format Fe source code.

Fmt {

/// Path to a Fe source file or directory. If omitted, formats all .fe files in the current project.

path: Option<Utf8PathBuf>,

/// Check if files are formatted, but do not write changes.

#[arg(long)]

check: bool,

},

/// Run Fe tests in a file or directory.

Test {

/// Path(s) to .fe files or directories containing ingots with tests.

///

/// Supports glob patterns (e.g. `crates/fe/tests/fixtures/fe_test/*.fe`).

///

/// When omitted, defaults to the current project root (like `cargo test`).

#[arg(value_name = "PATH", num_args = 0..)]

paths: Vec<Utf8PathBuf>,

/// Run tests for a single workspace ingot by member name

///

/// This requires targeting a workspace root path.

#[arg(short = 'i', long = "ingot", value_name = "INGOT")]

ingot: Option<String>,

/// Optional filter pattern for test names.

#[arg(short, long)]

filter: Option<String>,

/// Number of suites to run in parallel (0 = auto).

#[arg(long, default_value_t = 8, value_name = "N")]

jobs: usize,

/// Run suites as grouped jobs instead of splitting into per-test jobs.

#[arg(long)]

grouped: bool,

/// Show event logs from test execution.

#[arg(long)]

show_logs: bool,

/// Write test-module IR artifacts (`ir`, `rmir`) to the suite `out/` directory.

#[arg(long, value_enum, value_delimiter = ',')]

emit: Vec<TestEmit>,

/// Compilation profile to use when resolving profile-aware config.

#[arg(long, default_value = "test", value_name = "PROFILE")]

profile: String,

#[command(flatten)]

optimize: OptimizeArgs,

/// Trace executed EVM opcodes while running tests.

#[arg(long)]

trace_evm: bool,

/// How many EVM steps to keep in the trace ring buffer.

#[arg(long, default_value_t = 200)]

trace_evm_keep: usize,

/// How many stack items to print per EVM step in traces.

#[arg(long, default_value_t = 16)]

trace_evm_stack_n: usize,

/// Directory to write debug outputs (traces) into.

#[arg(long)]

debug_dir: Option<Utf8PathBuf>,

/// Write a debugging report as a `.tar.gz` file (includes sources, IR, bytecode, traces).

#[arg(long)]

report: bool,

/// Output path for `--report` (must end with `.tar.gz`).

#[arg(

report_out: Utf8PathBuf,

/// Write one `.tar.gz` report per input suite into this directory.

///

/// Useful when running a glob over many fixtures: each failing suite can be shared as a

/// standalone artifact.

#[arg(long, value_name = "DIR", conflicts_with = "report")]

report_dir: Option<Utf8PathBuf>,

/// When used with `--report-dir`, only write reports for suites that failed.

#[arg(long, requires = "report_dir")]

report_failed_only: bool,

/// Print a normalized call trace for each test.

#[arg(long)]

call_trace: bool,

/// Use recovery mode when parsing.

#[arg(long, default_value = "false")]

recovery_mode: bool,

},

/// Run gas benchmarks comparing Fe (Sonatina) against Solidity.

Bench {

/// Path to benchmark fixtures directory.

#[arg(value_name = "PATH", default_value = "bench_fixtures")]

path: Utf8PathBuf,

/// Filter benchmarks by name.

#[arg(short, long)]

filter: Option<String>,

/// solc binary to use (overrides FE_SOLC_PATH).

#[arg(long)]

solc: Option<String>,

/// Output directory for CSV reports.

#[arg(long, short)]

output: Option<Utf8PathBuf>,

},

/// Create a new ingot or workspace.

New {

/// Path to create the ingot or workspace in.

path: Utf8PathBuf,

/// Create a workspace instead of a single ingot.

#[arg(long)]

workspace: bool,

/// Override the default inferred name.

#[arg(long)]

name: Option<String>,

/// Override the default version (default: 0.1.0).

#[arg(long)]

version: Option<String>,

},

/// Generate shell completion scripts.

Completion {

/// Shell to generate completions for

#[arg(value_name = "shell")]

shell: clap_complete::Shell,

},

/// Generate LSIF index for code navigation.

Lsif {

/// Path to the ingot directory.

#[arg(default_value_t = default_project_path())]

path: Utf8PathBuf,

/// Output file (defaults to stdout).

#[arg(short, long)]

output: Option<Utf8PathBuf>,

},

/// Find the workspace or ingot root for a given path.

///

/// Walks up from the given path (or cwd) looking for fe.toml files.

/// Prints the workspace root if found, otherwise the nearest ingot root.

/// Useful for editor integrations that need to determine the project root.

Root {

/// Path to start searching from (default: current directory).

path: Option<Utf8PathBuf>,

},

/// Start the Fe language server (LSP).

#[cfg(feature = "lsp")]

Lsp {

/// Set the workspace root directory.

///

/// Used as the server's working directory. When the LSP client doesn't

/// send workspace folders, this directory is used as the fallback root

/// for ingot/workspace discovery.

#[arg(long)]

root: Option<Utf8PathBuf>,

/// Port for the combined doc+LSP server (default: auto-pick).

#[arg(long)]

port: Option<u16>,

/// Communication mode (default: stdio).

#[command(subcommand)]

mode: Option<LspMode>,

},

/// Generate SCIP index for code navigation.

Scip {

/// Path to the ingot directory.

#[arg(default_value_t = default_project_path())]

path: Utf8PathBuf,

/// Output file (defaults to index.scip).

#[arg(short, long, default_value = "index.scip")]

output: Utf8PathBuf,

},

/// Generate a documentation site (separate files by default).

///

/// Default output: docs.json, index.html, fe-web.js, fe-highlight.css.

/// Use --self-contained for a single index.html with everything inlined.

Static {

/// Output a single self-contained index.html instead of separate files

#[arg(long)]

self_contained: bool,

},

/// Produce docs.json (DocIndex + SCIP data) for web components.

///

/// The JSON can be consumed by <fe-code-block src="docs.json">,

/// <fe-doc-item src="docs.json">, and <fe-doc-viewer src="docs.json">.

Json {

/// Merge into an existing docs.json (deduplicates items, symbols, and files)

#[arg(long)]

merge: Option<Utf8PathBuf>,

},

/// Write the fe-web.js component bundle and fe-highlight.css.

///

/// Does not require compiling a project — just outputs the reusable assets.

Bundle {

/// Also write fe-highlight.css alongside the bundle

#[arg(long)]

with_css: bool,

},

/// Generate Starlight-compatible markdown pages

Pages {

/// Base URL prefix for generated links

#[arg(long, default_value = "/api")]

base_url: String,

},

/// Start a live documentation server with hot reload

Serve {

/// Port for HTTP server

#[arg(long, default_value = "8080")]

port: u16,

},

/// Start with TCP transport instead of stdio.

Tcp {

/// Port to listen on.

#[arg(short, long, default_value_t = 4242)]

port: u16,

/// Timeout in seconds to shut down if no clients are connected.

#[arg(short, long, default_value_t = 10)]

timeout: u64,

},

let preference = match opts.color {

ColorChoice::Auto => common::color::ColorPreference::Auto,

ColorChoice::Always => common::color::ColorPreference::Always,

ColorChoice::Never => common::color::ColorPreference::Never,

};

common::color::set_color_preference(preference);

match preference {

common::color::ColorPreference::Auto => colored::control::unset_override(),

common::color::ColorPreference::Always => colored::control::set_override(true),

common::color::ColorPreference::Never => colored::control::set_override(false),

}

match &opts.command {

Command::Build {

path,

ingot,

standalone,

from_metadata,

contract,

optimize,

out_dir,

profile,

emit,

report,

report_out,

report_failed_only,

recovery_mode,

} => {

if let Some(metadata_path) = from_metadata {

build::build_from_metadata(

metadata_path,

contract.as_deref(),

optimize.as_deref(),

emit,

out_dir.as_ref(),

profile,

*recovery_mode,

);

return;

}

let opt_level = match effective_opt_level(optimize.as_deref()) {

Ok(level) => level,

Err(err) => {

eprintln!("Error: {err}");

std::process::exit(1);

}

};

build(

path,

ingot.as_deref(),

*standalone,

contract.as_deref(),

opt_level,

emit,

out_dir.as_ref(),

profile,

(*report).then_some(report_out),

*report_failed_only,

*recovery_mode,

)

}

Command::Check {

path,

ingot,

standalone,

profile,

dump_mir,

report,

report_out,

report_failed_only,

recovery_mode,

} => {

match check(

path,

ingot.as_deref(),

*standalone,

profile,

*dump_mir,

(*report).then_some(report_out),

*report_failed_only,

*recovery_mode,

) {

Ok(has_errors) => {

if has_errors {

std::process::exit(1);

}

}

Err(err) => {

eprintln!("Error: {err}");

std::process::exit(1);

}

}

}

Command::Doc {

path,

output,

builtins,

stdlib_path,

include_tests,

action,

} => {

if let Some(DocAction::Bundle { with_css }) = action {

let output_dir = output.clone().unwrap_or_else(|| Utf8PathBuf::from("."));

doc::write_bundle(&output_dir.join("fe-web.js"));

if *with_css {

doc::write_highlight_css(&output_dir.join("fe-highlight.css"));

doc::write_styles_css(&output_dir.join("styles.css"));

}

} else {

doc::generate_docs(

path,

output.as_ref(),

*builtins,

stdlib_path.as_ref(),

*include_tests,

action.as_ref(),

);

}

}

#[cfg(not(target_arch = "wasm32"))]

Command::Tree { path } => {

if tree::print_tree(path) {

std::process::exit(1);

}

}

Command::Fmt { path, check } => {

run_fmt(path.as_ref(), *check);

}

Command::Test {

paths,

ingot,

filter,

jobs,

grouped,

show_logs,

emit,

profile,

optimize,

trace_evm,

trace_evm_keep,

trace_evm_stack_n,

debug_dir,

report,

report_out,

report_dir,

report_failed_only,

call_trace,

recovery_mode,

} => {

let opt_level = match effective_opt_level(optimize.as_deref()) {

Ok(level) => level,

Err(err) => {

eprintln!("Error: {err}");

std::process::exit(1);

}

};

let debug = TestDebugOptions {

trace_evm: *trace_evm,

trace_evm_keep: *trace_evm_keep,

trace_evm_stack_n: *trace_evm_stack_n,

debug_dir: debug_dir.clone(),

};

let paths = if paths.is_empty() {

vec![default_project_path()]

} else {

paths.clone()

};

match test::run_tests(

&paths,

ingot.as_deref(),

filter.as_deref(),

*jobs,

*grouped,

*show_logs,

profile,

opt_level,

emit,

&debug,

(*report).then_some(report_out),

report_dir.as_ref(),

*report_failed_only,

*call_trace,

*recovery_mode,

) {

Ok(has_failures) => {

if has_failures {

std::process::exit(1);

}

}

Err(err) => {

eprintln!("Error: {err}");

std::process::exit(1);

}

}

}

Command::Bench {

path,

filter,

solc,

output,

} => match fe::bench::run_benchmarks(

path.as_path(),

filter.as_deref(),

solc.as_deref(),

output.as_ref().map(|p| p.as_path()),

) {

Ok(()) => {}

Err(err) => {

eprintln!("Error: {err}");

std::process::exit(1);

}

},

Command::New {

path,

workspace,

name,

version,

} => {

if let Err(err) = cli::new::run(path, *workspace, name.as_deref(), version.as_deref()) {

eprintln!("Error: {err}");

std::process::exit(1);

}

}

Command::Completion { shell } => {

clap_complete::generate(

*shell,

&mut Options::command(),

"fe",

&mut std::io::stdout(),

);

}

Command::Root { path } => {

run_root(path.as_ref());

}

#[cfg(feature = "lsp")]

Command::Lsp { root, port, mode } => {

// If --root is explicit, use it. Otherwise, auto-discover from cwd.

let resolved_root = match root {

Some(r) => Some(r.canonicalize_utf8().unwrap_or_else(|e| {

eprintln!("Error: invalid --root path {r}: {e}");

std::process::exit(1);

})),

None => driver::files::find_project_root(),

};

if let Some(root) = &resolved_root {

std::env::set_current_dir(root.as_std_path()).unwrap_or_else(|e| {

eprintln!("Error: cannot chdir to {root}: {e}");

std::process::exit(1);

});

}

let rt = tokio::runtime::Runtime::new().unwrap_or_else(|e| {

eprintln!("Error creating async runtime: {e}");

std::process::exit(1);

});

rt.block_on(async {

unsafe {

std::env::set_var("RUST_BACKTRACE", "full");

}

language_server::setup_panic_hook();

match mode {

Some(LspMode::Tcp { port, timeout }) => {

language_server::run_tcp_server(

*port,

std::time::Duration::from_secs(*timeout),

)

.await;

}

None => {

run_lsp_with_combined_server(resolved_root, *port).await;

}

}

});

}

Command::Lsif { path, output } => {

run_lsif(path, output.as_ref());

}

Command::Scip { path, output } => {

run_scip(path, output);

}

}

use tokio::net::TcpListener;

// Bind the combined server listener

let addr = format!("127.0.0.1:{}", port.unwrap_or(0));

let listener = match TcpListener::bind(&addr).await {

Ok(l) => l,

Err(e) => {

eprintln!("Warning: could not bind combined server: {e}");

language_server::run_stdio_server(None).await;

return;

}

};

let actual_port = listener.local_addr().unwrap().port();

// Generate doc HTML for the workspace (best-effort)

let doc_html = generate_lsp_doc_html(resolved_root.as_ref());

eprintln!("Documentation: http://127.0.0.1:{actual_port}");

// Write .fe-lsp.json for discovery

let workspace_root_path = resolved_root

.as_ref()

.map(|r| r.as_std_path().to_path_buf())

.unwrap_or_else(|| std::env::current_dir().unwrap());

// Inspect any existing .fe-lsp.json. This is purely diagnostic: we

// always proceed with writing our own, since the file is a discovery

// pointer, not a lock. The outcome is still important for triage:

// stale files mean a previous crash, sibling-live means Zed respawned

// us without shutting the old instance down, and a root-mismatch

// means we're fighting with another instance over workspace root

// detection.

//

// These diagnostics are emitted via `eprintln!` rather than `tracing`

// because the tracing subscriber isn't installed until later, inside

// `language_server::run_stdio_server` -> `setup_default_subscriber`.

// Zed captures stderr for its LSP log panel, so users still see the

// messages in the same place they'd see a `tracing::warn!`.

let workspace_root_display = workspace_root_path.display();

let our_pid = std::process::id();

match doc::ExistingInstanceCheck::inspect(&workspace_root_path) {

doc::ExistingInstanceCheck::None => {

// Nothing to report in the common case; keep startup quiet.

}

doc::ExistingInstanceCheck::StaleFound {

stale_pid,

recorded_workspace_root,

} => {

eprintln!(

"fe-language-server: removing stale .fe-lsp.json at {workspace_root_display} \

);

doc::LspServerInfo::remove_from_workspace(&workspace_root_path);

}

doc::ExistingInstanceCheck::SiblingLive {

sibling_pid,

sibling_docs_url,

} => {

eprintln!(

"fe-language-server: another fe lsp instance (pid {sibling_pid}) is already \

);

}

doc::ExistingInstanceCheck::RootMismatch {

other_pid,

other_workspace_root,

our_workspace_root,

} => {

eprintln!(

"fe-language-server: ROOT MISMATCH: existing .fe-lsp.json (pid {other_pid}) refers \

);

}

doc::ExistingInstanceCheck::Malformed => {

eprintln!(

"fe-language-server: removing malformed .fe-lsp.json at {workspace_root_display} \

);

doc::LspServerInfo::remove_from_workspace(&workspace_root_path);

}

}

let server_info = doc::LspServerInfo {

pid: our_pid,

port: Some(actual_port),

workspace_root: Some(workspace_root_path.display().to_string()),

docs_url: Some(format!("http://127.0.0.1:{actual_port}")),

};

if let Err(e) = server_info.write_to_workspace(&workspace_root_path) {

eprintln!(

"fe-language-server: could not write .fe-lsp.json at {workspace_root_display}: {e}"

);

}

let config = language_server::CombinedServerConfig {

listener,

doc_html,

docs_url: Some(format!("http://127.0.0.1:{actual_port}")),

};

language_server::run_stdio_server(Some(config)).await;

// Cleanup on exit

doc::LspServerInfo::remove_from_workspace(&workspace_root_path);

db: &mut driver::DriverDataBase,

workspace_root: &camino::Utf8Path,

) -> (String, Option<String>) {

let root_path = workspace_root

.canonicalize_utf8()

.unwrap_or_else(|_| workspace_root.to_owned());

if let Ok(root_url) = url::Url::from_directory_path(&root_path) {

let _discovered = driver::discover_and_init(db, &root_url);

semantic_indexing::doc::regenerate(db)

} else {

let json = serde_json::to_string(&fe_web::model::DocIndex::new()).unwrap();

(json, None)

}

let root_path = resolved_root

.cloned()

.unwrap_or_else(|| Utf8PathBuf::from("."));

let mut db = driver::DriverDataBase::default();

let (json, scip_json) = regenerate_doc_data(&mut db, &root_path);

// Parse back the index to get the title

let index: fe_web::model::DocIndex =

serde_json::from_str(&json).unwrap_or_else(|_| fe_web::model::DocIndex::new());

let title = if let Some(root) = index.modules.first() {

format!("{} — Fe Documentation", root.name)

} else {

"Fe Documentation".to_string()

};

let mut html = fe_web::assets::html_shell_full(&title, &json, scip_json.as_deref(), None);

// Append auto-connect script

let connect_script =

r#"<script>window.FE_LSP = connectLsp(`${location.protocol==='https:'?'wss:':'ws:'}://${location.host}/lsp`);</script>"#.to_string();

if let Some(pos) = html.rfind("</body>") {

html.insert_str(pos, &connect_script);

}

html

use driver::DriverDataBase;

let mut db = DriverDataBase::default();

let canonical_path = match path.canonicalize_utf8() {

Ok(p) => p,

Err(_) => {

eprintln!("Error: Invalid or non-existent directory path: {path}");

std::process::exit(1);

}

};

let ingot_url = match url::Url::from_directory_path(canonical_path.as_str()) {

Ok(url) => url,

Err(_) => {

eprintln!("Error: Invalid directory path: {path}");

std::process::exit(1);

}

};

let had_init_diagnostics = driver::init_ingot(&mut db, &ingot_url);

if had_init_diagnostics {

eprintln!("Warning: ingot had initialization diagnostics");

}

let result = if let Some(output_path) = output {

let file = match std::fs::File::create(output_path.as_std_path()) {

Ok(f) => f,

Err(e) => {

eprintln!("Error creating output file: {e}");

std::process::exit(1);

}

};

let writer = std::io::BufWriter::new(file);

semantic_indexing::lsif::generate_lsif(&db, &ingot_url, writer)

} else {

let stdout = std::io::stdout().lock();

let writer = std::io::BufWriter::new(stdout);

semantic_indexing::lsif::generate_lsif(&db, &ingot_url, writer)

};

if let Err(e) = result {

eprintln!("Error generating LSIF: {e}");

std::process::exit(1);

}

use driver::DriverDataBase;

let mut db = DriverDataBase::default();

let canonical_path = match path.canonicalize_utf8() {

Ok(p) => p,

Err(_) => {

eprintln!("Error: Invalid or non-existent directory path: {path}");

std::process::exit(1);

}

};

let ingot_url = match url::Url::from_directory_path(canonical_path.as_str()) {

Ok(url) => url,

Err(_) => {

eprintln!("Error: Invalid directory path: {path}");

std::process::exit(1);

}

};

let had_init_diagnostics = driver::init_ingot(&mut db, &ingot_url);

if had_init_diagnostics {

eprintln!("Warning: ingot had initialization diagnostics");

}

let result =

semantic_indexing::scip_batch::generate_scip(&db, &ingot_url).unwrap_or_else(|e| {