fayalite 0.2.0

// SPDX-License-Identifier: LGPL-3.0-or-later
// See Notices.txt for copyright information
use crate::{
    bundle::{Bundle, BundleType},
    firrtl::{self, ExportOptions},
    intern::Interned,
    module::Module,
    util::{job_server::AcquiredJob, streaming_read_utf8::streaming_read_utf8},
};
use clap::{
    builder::{OsStringValueParser, TypedValueParser},
    Parser, Subcommand, ValueEnum, ValueHint,
};
use eyre::{eyre, Report};
use serde::{Deserialize, Serialize};
use std::{
    error,
    ffi::OsString,
    fmt::{self, Write},
    fs, io, mem,
    path::{Path, PathBuf},
    process,
};
use tempfile::TempDir;

pub type Result<T = (), E = CliError> = std::result::Result<T, E>;

pub struct CliError(Report);

impl fmt::Debug for CliError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

impl fmt::Display for CliError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

impl error::Error for CliError {}

impl From<io::Error> for CliError {
    fn from(value: io::Error) -> Self {
        CliError(Report::new(value))
    }
}

pub trait RunPhase<Arg> {
    type Output;
    fn run(&self, arg: Arg) -> Result<Self::Output> {
        self.run_with_job(arg, &mut AcquiredJob::acquire())
    }
    fn run_with_job(&self, arg: Arg, acquired_job: &mut AcquiredJob) -> Result<Self::Output>;
}

#[derive(Parser, Debug, Clone)]
#[non_exhaustive]
pub struct BaseArgs {
    /// the directory to put the generated main output file and associated files in
    #[arg(short, long, value_hint = ValueHint::DirPath, required = true)]
    pub output: Option<PathBuf>,
    /// the stem of the generated main output file, e.g. to get foo.v, pass --file-stem=foo
    #[arg(long)]
    pub file_stem: Option<String>,
    #[arg(long, env = "FAYALITE_KEEP_TEMP_DIR")]
    pub keep_temp_dir: bool,
    #[arg(skip = false)]
    pub redirect_output_for_rust_test: bool,
}

impl BaseArgs {
    fn make_firrtl_file_backend(&self) -> Result<(firrtl::FileBackend, Option<TempDir>)> {
        let (dir_path, temp_dir) = match &self.output {
            Some(output) => (output.clone(), None),
            None => {
                let temp_dir = TempDir::new()?;
                if self.keep_temp_dir {
                    let temp_dir = temp_dir.into_path();
                    println!("created temporary directory: {}", temp_dir.display());
                    (temp_dir, None)
                } else {
                    (temp_dir.path().to_path_buf(), Some(temp_dir))
                }
            }
        };
        Ok((
            firrtl::FileBackend {
                dir_path,
                top_fir_file_stem: self.file_stem.clone(),
                circuit_name: None,
            },
            temp_dir,
        ))
    }
    /// handles possibly redirecting the command's output for Rust tests
    pub fn run_external_command(
        &self,
        _acquired_job: &mut AcquiredJob,
        mut command: process::Command,
        mut captured_output: Option<&mut String>,
    ) -> io::Result<process::ExitStatus> {
        if self.redirect_output_for_rust_test || captured_output.is_some() {
            let (reader, writer) = os_pipe::pipe()?;
            let mut reader = io::BufReader::new(reader);
            command.stderr(writer.try_clone()?);
            command.stdout(writer); // must not leave writer around after spawning child
            command.stdin(process::Stdio::null());
            let mut child = command.spawn()?;
            drop(command); // close writers
            Ok(loop {
                let status = child.try_wait()?;
                streaming_read_utf8(&mut reader, |s| {
                    if let Some(captured_output) = captured_output.as_deref_mut() {
                        captured_output.push_str(s);
                    }
                    // use print! so output goes to Rust test output capture
                    print!("{s}");
                    io::Result::Ok(())
                })?;
                if let Some(status) = status {
                    break status;
                }
            })
        } else {
            command.status()
        }
    }
}

#[derive(Parser, Debug, Clone)]
#[non_exhaustive]
pub struct FirrtlArgs {
    #[command(flatten)]
    pub base: BaseArgs,
    #[command(flatten)]
    pub export_options: ExportOptions,
}

#[derive(Debug)]
#[non_exhaustive]
pub struct FirrtlOutput {
    pub file_stem: String,
    pub top_module: String,
    pub output_dir: PathBuf,
    pub temp_dir: Option<TempDir>,
}

impl FirrtlOutput {
    pub fn file_with_ext(&self, ext: &str) -> PathBuf {
        let mut retval = self.output_dir.join(&self.file_stem);
        retval.set_extension(ext);
        retval
    }
    pub fn firrtl_file(&self) -> PathBuf {
        self.file_with_ext("fir")
    }
}

impl FirrtlArgs {
    fn run_impl(
        &self,
        top_module: Module<Bundle>,
        _acquired_job: &mut AcquiredJob,
    ) -> Result<FirrtlOutput> {
        let (file_backend, temp_dir) = self.base.make_firrtl_file_backend()?;
        let firrtl::FileBackend {
            top_fir_file_stem,
            circuit_name,
            dir_path,
        } = firrtl::export(file_backend, &top_module, self.export_options)?;
        Ok(FirrtlOutput {
            file_stem: top_fir_file_stem.expect(
                "export is known to set the file stem from the circuit name if not provided",
            ),
            top_module: circuit_name.expect("export is known to set the circuit name"),
            output_dir: dir_path,
            temp_dir,
        })
    }
}

impl<T: BundleType> RunPhase<Module<T>> for FirrtlArgs {
    type Output = FirrtlOutput;
    fn run_with_job(
        &self,
        top_module: Module<T>,
        acquired_job: &mut AcquiredJob,
    ) -> Result<Self::Output> {
        self.run_impl(top_module.canonical(), acquired_job)
    }
}

impl<T: BundleType> RunPhase<Interned<Module<T>>> for FirrtlArgs {
    type Output = FirrtlOutput;
    fn run_with_job(
        &self,
        top_module: Interned<Module<T>>,
        acquired_job: &mut AcquiredJob,
    ) -> Result<Self::Output> {
        self.run_with_job(*top_module, acquired_job)
    }
}

/// based on [LLVM Circt's recommended lowering options
/// ](https://circt.llvm.org/docs/VerilogGeneration/#recommended-loweringoptions-by-target)
#[derive(ValueEnum, Copy, Clone, Debug, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum VerilogDialect {
    Questa,
    Spyglass,
    Verilator,
    Vivado,
    Yosys,
}

impl fmt::Display for VerilogDialect {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

impl VerilogDialect {
    pub fn as_str(self) -> &'static str {
        match self {
            VerilogDialect::Questa => "questa",
            VerilogDialect::Spyglass => "spyglass",
            VerilogDialect::Verilator => "verilator",
            VerilogDialect::Vivado => "vivado",
            VerilogDialect::Yosys => "yosys",
        }
    }
    pub fn firtool_extra_args(self) -> &'static [&'static str] {
        match self {
            VerilogDialect::Questa => &["--lowering-options=emitWireInPorts"],
            VerilogDialect::Spyglass => {
                &["--lowering-options=explicitBitcast,disallowExpressionInliningInPorts"]
            }
            VerilogDialect::Verilator => &[
                "--lowering-options=locationInfoStyle=wrapInAtSquareBracket,disallowLocalVariables",
            ],
            VerilogDialect::Vivado => &["--lowering-options=mitigateVivadoArrayIndexConstPropBug"],
            VerilogDialect::Yosys => {
                &["--lowering-options=disallowLocalVariables,disallowPackedArrays"]
            }
        }
    }
}

#[derive(Parser, Debug, Clone)]
#[non_exhaustive]
pub struct VerilogArgs {
    #[command(flatten)]
    pub firrtl: FirrtlArgs,
    #[arg(
        long,
        default_value = "firtool",
        env = "FIRTOOL",
        value_hint = ValueHint::CommandName,
        value_parser = OsStringValueParser::new().try_map(which::which)
    )]
    pub firtool: PathBuf,
    #[arg(long)]
    pub firtool_extra_args: Vec<OsString>,
    /// adapt the generated Verilog for a particular toolchain
    #[arg(long)]
    pub verilog_dialect: Option<VerilogDialect>,
    #[arg(long, short = 'g')]
    pub debug: bool,
}

#[derive(Debug)]
#[non_exhaustive]
pub struct VerilogOutput {
    pub firrtl: FirrtlOutput,
    pub verilog_files: Vec<PathBuf>,
    pub contents_hash: Option<blake3::Hash>,
}

impl VerilogOutput {
    pub fn main_verilog_file(&self) -> PathBuf {
        self.firrtl.file_with_ext("v")
    }
    fn unadjusted_verilog_file(&self) -> PathBuf {
        self.firrtl.file_with_ext("unadjusted.v")
    }
}

impl VerilogArgs {
    fn process_unadjusted_verilog_file(&self, mut output: VerilogOutput) -> Result<VerilogOutput> {
        let input = fs::read_to_string(output.unadjusted_verilog_file())?;
        let file_separator_prefix = "\n// ----- 8< ----- FILE \"";
        let file_separator_suffix = "\" ----- 8< -----\n\n";
        let mut input = &*input;
        output.contents_hash = Some(blake3::hash(input.as_bytes()));
        let main_verilog_file = output.main_verilog_file();
        let mut file_name: Option<&Path> = Some(&main_verilog_file);
        loop {
            let (chunk, next_file_name) = if let Some((chunk, rest)) =
                input.split_once(file_separator_prefix)
            {
                let Some((next_file_name, rest)) = rest.split_once(file_separator_suffix) else {
                    return Err(CliError(eyre!("parsing firtool's output failed: found {file_separator_prefix:?} but no {file_separator_suffix:?}")));
                };
                input = rest;
                (chunk, Some(next_file_name.as_ref()))
            } else {
                (mem::take(&mut input), None)
            };
            let Some(file_name) = mem::replace(&mut file_name, next_file_name) else {
                break;
            };
            let file_name = output.firrtl.output_dir.join(file_name);
            fs::write(&file_name, chunk)?;
            if let Some(extension) = file_name.extension() {
                if extension == "v" || extension == "sv" {
                    output.verilog_files.push(file_name);
                }
            }
        }
        Ok(output)
    }
    fn run_impl(
        &self,
        firrtl_output: FirrtlOutput,
        acquired_job: &mut AcquiredJob,
    ) -> Result<VerilogOutput> {
        let Self {
            firrtl,
            firtool,
            firtool_extra_args,
            verilog_dialect,
            debug,
        } = self;
        let output = VerilogOutput {
            firrtl: firrtl_output,
            verilog_files: vec![],
            contents_hash: None,
        };
        let mut cmd = process::Command::new(firtool);
        cmd.arg(output.firrtl.firrtl_file());
        cmd.arg("-o");
        cmd.arg(output.unadjusted_verilog_file());
        if *debug {
            cmd.arg("-g");
            cmd.arg("--preserve-values=all");
        }
        if let Some(dialect) = verilog_dialect {
            cmd.args(dialect.firtool_extra_args());
        }
        cmd.args(firtool_extra_args);
        cmd.current_dir(&output.firrtl.output_dir);
        let status = firrtl.base.run_external_command(acquired_job, cmd, None)?;
        if status.success() {
            self.process_unadjusted_verilog_file(output)
        } else {
            Err(CliError(eyre!(
                "running {} failed: {status}",
                self.firtool.display()
            )))
        }
    }
}

impl<Arg> RunPhase<Arg> for VerilogArgs
where
    FirrtlArgs: RunPhase<Arg, Output = FirrtlOutput>,
{
    type Output = VerilogOutput;
    fn run_with_job(&self, arg: Arg, acquired_job: &mut AcquiredJob) -> Result<Self::Output> {
        let firrtl_output = self.firrtl.run_with_job(arg, acquired_job)?;
        self.run_impl(firrtl_output, acquired_job)
    }
}

#[derive(ValueEnum, Copy, Clone, Debug, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum FormalMode {
    #[default]
    BMC,
    Prove,
    Live,
    Cover,
}

impl FormalMode {
    pub fn as_str(self) -> &'static str {
        match self {
            FormalMode::BMC => "bmc",
            FormalMode::Prove => "prove",
            FormalMode::Live => "live",
            FormalMode::Cover => "cover",
        }
    }
}

impl fmt::Display for FormalMode {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

#[derive(Clone)]
struct FormalAdjustArgs;

impl clap::FromArgMatches for FormalAdjustArgs {
    fn from_arg_matches(_matches: &clap::ArgMatches) -> Result<Self, clap::Error> {
        Ok(Self)
    }

    fn update_from_arg_matches(&mut self, _matches: &clap::ArgMatches) -> Result<(), clap::Error> {
        Ok(())
    }
}

impl clap::Args for FormalAdjustArgs {
    fn augment_args(cmd: clap::Command) -> clap::Command {
        cmd.mut_arg("output", |arg| arg.required(false))
            .mut_arg("verilog_dialect", |arg| {
                arg.default_value(VerilogDialect::Yosys.to_string())
                    .hide(true)
            })
    }

    fn augment_args_for_update(cmd: clap::Command) -> clap::Command {
        Self::augment_args(cmd)
    }
}

#[derive(Parser, Clone)]
#[non_exhaustive]
pub struct FormalArgs {
    #[command(flatten)]
    pub verilog: VerilogArgs,
    #[arg(
        long,
        default_value = "sby",
        env = "SBY",
        value_hint = ValueHint::CommandName,
        value_parser = OsStringValueParser::new().try_map(which::which)
    )]
    pub sby: PathBuf,
    #[arg(long)]
    pub sby_extra_args: Vec<String>,
    #[arg(long, default_value_t)]
    pub mode: FormalMode,
    #[arg(long, default_value_t = Self::DEFAULT_DEPTH)]
    pub depth: u64,
    #[arg(long, default_value = "z3")]
    pub solver: String,
    #[arg(long)]
    pub smtbmc_extra_args: Vec<String>,
    #[arg(long, default_value_t = true, env = "FAYALITE_CACHE_RESULTS")]
    pub cache_results: bool,
    #[command(flatten)]
    _formal_adjust_args: FormalAdjustArgs,
}

impl fmt::Debug for FormalArgs {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let Self {
            verilog,
            sby,
            sby_extra_args,
            mode,
            depth,
            solver,
            smtbmc_extra_args,
            cache_results,
            _formal_adjust_args: _,
        } = self;
        f.debug_struct("FormalArgs")
            .field("verilog", verilog)
            .field("sby", sby)
            .field("sby_extra_args", sby_extra_args)
            .field("mode", mode)
            .field("depth", depth)
            .field("solver", solver)
            .field("smtbmc_extra_args", smtbmc_extra_args)
            .field("cache_results", cache_results)
            .finish_non_exhaustive()
    }
}

impl FormalArgs {
    pub const DEFAULT_DEPTH: u64 = 20;
}

#[derive(Debug)]
#[non_exhaustive]
pub struct FormalOutput {
    pub verilog: VerilogOutput,
}

impl FormalOutput {
    pub fn sby_file(&self) -> PathBuf {
        self.verilog.firrtl.file_with_ext("sby")
    }
    pub fn cache_file(&self) -> PathBuf {
        self.verilog.firrtl.file_with_ext("cache.json")
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[non_exhaustive]
pub struct FormalCacheOutput {}

#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[non_exhaustive]
pub enum FormalCacheVersion {
    V1,
}

impl FormalCacheVersion {
    pub const CURRENT: Self = Self::V1;
}

#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[non_exhaustive]
pub struct FormalCache {
    pub version: FormalCacheVersion,
    pub contents_hash: blake3::Hash,
    pub stdout_stderr: String,
    pub result: Result<FormalCacheOutput, String>,
}

impl FormalCache {
    pub fn new(
        version: FormalCacheVersion,
        contents_hash: blake3::Hash,
        stdout_stderr: String,
        result: Result<FormalCacheOutput, String>,
    ) -> Self {
        Self {
            version,
            contents_hash,
            stdout_stderr,
            result,
        }
    }
}

impl FormalArgs {
    fn sby_contents(&self, output: &FormalOutput) -> Result<String> {
        let Self {
            verilog: _,
            sby: _,
            sby_extra_args: _,
            mode,
            depth,
            smtbmc_extra_args,
            solver,
            cache_results: _,
            _formal_adjust_args: _,
        } = self;
        let smtbmc_options = smtbmc_extra_args.join(" ");
        let top_module = &output.verilog.firrtl.top_module;
        let mut retval = format!(
            "[options]\n\
            mode {mode}\n\
            depth {depth}\n\
            wait on\n\
            \n\
            [engines]\n\
            smtbmc {solver} -- -- {smtbmc_options}\n\
            \n\
            [script]\n"
        );
        for verilog_file in &output.verilog.verilog_files {
            let verilog_file = verilog_file
                .to_str()
                .ok_or_else(|| CliError(eyre!("verilog file path is not UTF-8")))?;
            if verilog_file.contains(|ch: char| {
                (ch != ' ' && ch != '\t' && ch.is_ascii_whitespace()) || ch == '"'
            }) {
                return Err(CliError(eyre!(
                    "verilog file path contains characters that aren't permitted"
                )));
            }
            writeln!(retval, "read_verilog -sv -formal \"{verilog_file}\"").unwrap();
        }
        // workaround for wires disappearing -- set `keep` on all wires
        writeln!(retval, "hierarchy -top {top_module}").unwrap();
        writeln!(retval, "proc").unwrap();
        writeln!(retval, "setattr -set keep 1 w:\\*").unwrap();
        writeln!(retval, "prep").unwrap();
        Ok(retval)
    }
    fn run_impl(
        &self,
        verilog_output: VerilogOutput,
        acquired_job: &mut AcquiredJob,
    ) -> Result<FormalOutput> {
        let output = FormalOutput {
            verilog: verilog_output,
        };
        let sby_file = output.sby_file();
        let sby_contents = self.sby_contents(&output)?;
        let contents_hash = output.verilog.contents_hash.map(|verilog_hash| {
            let mut hasher = blake3::Hasher::new();
            hasher.update(verilog_hash.as_bytes());
            hasher.update(sby_contents.as_bytes());
            hasher.update(&(self.sby_extra_args.len() as u64).to_le_bytes());
            for sby_extra_arg in self.sby_extra_args.iter() {
                hasher.update(&(sby_extra_arg.len() as u64).to_le_bytes());
                hasher.update(sby_extra_arg.as_bytes());
            }
            hasher.finalize()
        });
        std::fs::write(&sby_file, sby_contents)?;
        let mut cmd = process::Command::new(&self.sby);
        cmd.arg("-j1"); // sby seems not to respect job count in parallel mode
        cmd.arg("-f");
        cmd.arg(sby_file.file_name().unwrap());
        cmd.args(&self.sby_extra_args);
        cmd.current_dir(&output.verilog.firrtl.output_dir);
        let mut captured_output = String::new();
        let cache_file = output.cache_file();
        let do_cache = if let Some(contents_hash) = contents_hash.filter(|_| self.cache_results) {
            if let Some(FormalCache {
                version: FormalCacheVersion::CURRENT,
                contents_hash: cache_contents_hash,
                stdout_stderr,
                result,
            }) = fs::read(&cache_file)
                .ok()
                .and_then(|v| serde_json::from_slice(&v).ok())
            {
                if cache_contents_hash == contents_hash {
                    println!("Using cached formal result:\n{stdout_stderr}");
                    return match result {
                        Ok(FormalCacheOutput {}) => Ok(output),
                        Err(error) => Err(CliError(eyre::Report::msg(error))),
                    };
                }
            }
            true
        } else {
            false
        };
        let _ = fs::remove_file(&cache_file);
        let status = self.verilog.firrtl.base.run_external_command(
            acquired_job,
            cmd,
            do_cache.then_some(&mut captured_output),
        )?;
        let result = if status.success() {
            Ok(output)
        } else {
            Err(CliError(eyre!(
                "running {} failed: {status}",
                self.sby.display()
            )))
        };
        if do_cache {
            fs::write(
                cache_file,
                serde_json::to_string_pretty(&FormalCache {
                    version: FormalCacheVersion::CURRENT,
                    contents_hash: contents_hash.unwrap(),
                    stdout_stderr: captured_output,
                    result: match &result {
                        Ok(FormalOutput { verilog: _ }) => Ok(FormalCacheOutput {}),
                        Err(error) => Err(error.to_string()),
                    },
                })
                .expect("serialization shouldn't ever fail"),
            )?;
        }
        result
    }
}

impl<Arg> RunPhase<Arg> for FormalArgs
where
    VerilogArgs: RunPhase<Arg, Output = VerilogOutput>,
{
    type Output = FormalOutput;
    fn run_with_job(&self, arg: Arg, acquired_job: &mut AcquiredJob) -> Result<Self::Output> {
        let verilog_output = self.verilog.run_with_job(arg, acquired_job)?;
        self.run_impl(verilog_output, acquired_job)
    }
}

#[derive(Subcommand, Debug)]
enum CliCommand {
    /// Generate FIRRTL
    Firrtl(FirrtlArgs),
    /// Generate Verilog
    Verilog(VerilogArgs),
    /// Run a formal proof
    Formal(FormalArgs),
}

/// a simple CLI
///
/// Use like:
///
/// ```no_run
/// # use fayalite::prelude::*;
/// # #[hdl_module]
/// # fn my_module() {}
/// use fayalite::cli;
///
/// fn main() -> cli::Result {
///     cli::Cli::parse().run(my_module())
/// }
/// ```
///
/// You can also use it with a larger [`clap`]-based CLI like so:
///
/// ```no_run
/// # use fayalite::prelude::*;
/// # #[hdl_module]
/// # fn my_module() {}
/// use clap::{Subcommand, Parser};
/// use fayalite::cli;
///
/// #[derive(Subcommand)]
/// pub enum Cmd {
///     #[command(flatten)]
///     Fayalite(cli::Cli),
///     MySpecialCommand {
///         #[arg(long)]
///         foo: bool,
///     },
/// }
///
/// #[derive(Parser)]
/// pub struct Cli {
///     #[command(subcommand)]
///     cmd: Cmd, // or just use cli::Cli directly if you don't need more subcommands
/// }
///
/// fn main() -> cli::Result {
///     match Cli::parse().cmd {
///         Cmd::Fayalite(v) => v.run(my_module())?,
///         Cmd::MySpecialCommand { foo } => println!("special: foo={foo}"),
///     }
///     Ok(())
/// }
/// ```
#[derive(Parser, Debug)]
// clear things that would be crate-specific
#[command(name = "Fayalite Simple CLI", about = None, long_about = None)]
pub struct Cli {
    #[command(subcommand)]
    subcommand: CliCommand,
}

impl clap::Subcommand for Cli {
    fn augment_subcommands(cmd: clap::Command) -> clap::Command {
        CliCommand::augment_subcommands(cmd)
    }

    fn augment_subcommands_for_update(cmd: clap::Command) -> clap::Command {
        CliCommand::augment_subcommands_for_update(cmd)
    }

    fn has_subcommand(name: &str) -> bool {
        CliCommand::has_subcommand(name)
    }
}

impl<T> RunPhase<T> for Cli
where
    FirrtlArgs: RunPhase<T, Output = FirrtlOutput>,
{
    type Output = ();
    fn run_with_job(&self, arg: T, acquired_job: &mut AcquiredJob) -> Result<Self::Output> {
        match &self.subcommand {
            CliCommand::Firrtl(c) => {
                c.run_with_job(arg, acquired_job)?;
            }
            CliCommand::Verilog(c) => {
                c.run_with_job(arg, acquired_job)?;
            }
            CliCommand::Formal(c) => {
                c.run_with_job(arg, acquired_job)?;
            }
        }
        Ok(())
    }
}

impl Cli {
    /// forwards to [`clap::Parser::parse()`] so you don't have to import [`clap::Parser`]
    pub fn parse() -> Self {
        clap::Parser::parse()
    }
    /// forwards to [`RunPhase::run()`] so you don't have to import [`RunPhase`]
    pub fn run<T>(&self, top_module: T) -> Result<()>
    where
        Self: RunPhase<T, Output = ()>,
    {
        RunPhase::run(self, top_module)
    }
}