bashrs 6.66.0

//! # Rash - Rust to Shell Transpiler
// Allow uppercase TASK_IDs in test function names (EXTREME TDD naming convention)
#![cfg_attr(test, allow(non_snake_case))]
// Allow unwrap in test code - tests should panic on unexpected conditions
#![cfg_attr(test, allow(clippy::unwrap_used))]
// Allow indexing in test code - tests should panic on out-of-bounds
#![cfg_attr(test, allow(clippy::indexing_slicing))]
// Allow absurd extreme comparisons (defensive test assertions like usize >= 0)
// TODO(v2.1.0): Clean up these assertions - Issue #TBD
#![allow(clippy::absurd_extreme_comparisons)]
// Rust 1.93: doc comments before dead-code-eliminated items trigger unused_doc_comments
#![allow(unused_doc_comments)]
// Allow multiple crate versions - transitive dependencies from different crates
#![allow(clippy::multiple_crate_versions)]
//!
//! Rash is a Rust-to-POSIX shell script transpiler that generates safe, deterministic,
//! and verifiable shell scripts from a restricted Rust subset.
//!
//! ## Features
//!
//! - **POSIX Compliance**: Generated scripts work on sh, dash, bash, and ash
//! - **Safety**: Injection attack prevention, proper quoting, verified output
//! - **Determinism**: Same input always produces identical output
//! - **ShellCheck Integration**: All output passes shellcheck validation
//!
//! ## Quick Start
//!
//! ```rust
//! use bashrs::{transpile, Config};
//!
//! let rust_code = r#"
//!     fn main() {
//!         let greeting = "Hello, World!";
//!         echo(greeting);
//!     }
//!
//!     fn echo(msg: &str) {}
//! "#;
//!
//! let shell_script = transpile(rust_code, &Config::default()).unwrap();
//! assert!(shell_script.contains("#!/bin/sh"));
//! ```
//!
//! ## Main Functions
//!
//! - [`transpile`]: Convert Rust code to shell script
//! - [`check`]: Validate Rust code without generating output
//!
//! ## Configuration
//!
//! ```rust
//! use bashrs::{Config, transpile};
//! use bashrs::models::{ShellDialect, VerificationLevel};
//!
//! let config = Config {
//!     target: ShellDialect::Posix,
//!     verify: VerificationLevel::Strict,
//!     optimize: true,
//!     ..Config::default()
//! };
//!
//! let rust_code = "fn main() { let x = 42; }";
//! let result = transpile(rust_code, &config);
//! assert!(result.is_ok());
//! ```

// Contract assertions from YAML (pv codegen)
#[macro_use]
#[allow(unused_macros)]
mod generated_contracts;

/// Abstract syntax tree types and validation
pub mod ast;
/// Bash script parsing and AST generation
pub mod bash_parser;
/// Bash quality tools (test generation, coverage, formatting, scoring)
#[cfg(not(target_arch = "wasm32"))]
pub mod bash_quality;
/// Bash script transpilation and purification
pub mod bash_transpiler;
/// build.rs integration with auto-discovery
#[cfg(not(target_arch = "wasm32"))]
pub mod build_rs;
/// Command-line interface for bashrs
#[cfg(all(not(target_arch = "wasm32"), feature = "clap"))]
pub mod cli;
/// Rust compiler integration for transpilation
#[cfg(all(not(target_arch = "wasm32"), feature = "compile"))]
pub mod compiler;
/// Shell artifact compliance system (SPEC-COMPLY-2026-001)
#[cfg(not(target_arch = "wasm32"))]
pub mod comply;
/// Shell configuration file management and analysis
pub mod config;
/// Container and sandbox support
#[cfg(all(not(target_arch = "wasm32"), feature = "compile"))]
pub mod container;
/// Corpus-driven transpilation quality measurement (Popperian falsification)
#[cfg(not(target_arch = "wasm32"))]
pub mod corpus;
/// Shell script code emission
pub mod emitter;
/// Formal verification and proof generation
#[cfg(not(target_arch = "wasm32"))]
pub mod formal;
/// Shell script formatting
pub mod formatter;
/// Quality gate configuration and enforcement
#[cfg(not(target_arch = "wasm32"))]
pub mod gates;
/// TDD-first installer framework
#[cfg(not(target_arch = "wasm32"))]
pub mod installer;
/// Intermediate representation for transpilation
pub mod ir;
/// Shell script linting with ShellCheck-equivalent rules
pub mod linter;
/// Makefile parsing and purification
pub mod make_parser;
/// Configuration types and error handling
pub mod models;
/// Quality gates with rich reporting and fault localization (ML-001 to ML-012)
#[cfg(not(target_arch = "wasm32"))]
pub mod quality;
/// Interactive REPL with integrated debugger
#[cfg(all(not(target_arch = "wasm32"), feature = "rustyline"))]
pub mod repl;
/// Parser and compiler services
pub mod services;
/// Standard library function mappings
pub mod stdlib;
/// Stdlib function metadata (extracted for file-size discipline)
pub mod stdlib_metadata;
/// Test case generation from shell scripts
#[cfg(not(target_arch = "wasm32"))]
pub mod test_generator;
/// Tracing infrastructure for diagnostics and debugging
pub mod tracing;
/// Builder API for programmatic transpilation
pub mod transpiler;
/// Type system with taint tracking for injection safety
pub mod types;
/// AST and output validation
pub mod validation;
/// Output verification and shellcheck integration
#[cfg(not(target_arch = "wasm32"))]
pub mod verifier;

/// Terminal User Interface (TUI) with ratatui
#[cfg(feature = "tui")]
pub mod tui;

#[cfg(test)]
pub mod testing;

#[cfg(test)]
#[path = "coverage_integration_tests.rs"]
mod coverage_integration_tests;

// WebAssembly support removed - use probar/simular/jugar instead

pub use emitter::{DecisionTrace, TranspilerDecision};
pub use models::{Config, Error, Result};
pub use transpiler::Transpiler;

/// Transpile Rust source code to POSIX shell script.
///
/// This is the main entry point for the Rash transpiler. It takes Rust source code
/// and converts it to a POSIX-compliant shell script with full validation.
///
/// # Arguments
///
/// * `input` - Rust source code as a string
/// * `config` - Configuration options for transpilation
///
/// # Returns
///
/// * `Ok(String)` - Generated shell script
/// * `Err(Error)` - Transpilation error (parse, validation, emission)
///
/// # Examples
///
/// ## Basic Usage
///
/// ```rust
/// use bashrs::{transpile, Config};
///
/// let rust_code = r#"
///     fn main() {
///         let message = "Hello from Rash";
///         echo(message);
///     }
///     fn echo(msg: &str) {}
/// "#;
///
/// let shell_script = transpile(rust_code, &Config::default()).unwrap();
/// assert!(shell_script.contains("#!/bin/sh"));
/// assert!(shell_script.contains("message="));
/// ```
///
/// ## With Custom Configuration
///
/// ```rust
/// use bashrs::{transpile, Config};
/// use bashrs::models::{ShellDialect, VerificationLevel};
///
/// let config = Config {
///     target: ShellDialect::Bash,
///     verify: VerificationLevel::Paranoid,
///     optimize: true,
///     ..Config::default()
/// };
///
/// let rust_code = "fn main() { let x = 1 + 2; }";
/// let result = transpile(rust_code, &config);
/// assert!(result.is_ok());
/// ```
///
/// ## Variable Assignment
///
/// ```rust
/// use bashrs::{transpile, Config};
///
/// let rust_code = r#"
///     fn main() {
///         let name = "Alice";
///         let age = 30;
///         let active = true;
///     }
/// "#;
///
/// let shell_script = transpile(rust_code, &Config::default()).unwrap();
/// assert!(shell_script.contains("name="));
/// assert!(shell_script.contains("age="));
/// ```
///
/// ## Function Calls
///
/// ```rust
/// use bashrs::{transpile, Config};
///
/// let rust_code = r#"
///     fn main() {
///         greet("World");
///     }
///     fn greet(name: &str) {}
/// "#;
///
/// let shell_script = transpile(rust_code, &Config::default()).unwrap();
/// assert!(shell_script.contains("greet"));
/// ```
///
/// # Errors
///
/// Returns `Err` if:
/// - Input cannot be parsed as valid Rust
/// - AST validation fails (unsupported features)
/// - IR generation fails
/// - Shell code emission fails
/// - Output validation fails (shellcheck, safety checks)
pub fn transpile(input: &str, config: &Config) -> Result<String> {
    let validation_pipeline = validation::pipeline::ValidationPipeline::new(config);

    let ast = services::parser::parse(input)?;
    ast::validate(&ast)?;
    validation_pipeline.validate_ast(&ast)?;

    let ir = ir::from_ast(&ast)?;
    validation_pipeline.validate_ir(&ir)?;

    let optimized = ir::optimize(ir, config)?;
    let shell_code = emitter::emit(&optimized)?;

    validation_pipeline.validate_output(&shell_code)?;

    Ok(shell_code)
}

/// Transpile Rust source code to POSIX shell script with decision tracing.
///
/// Same pipeline as [`transpile`], but collects a trace of emitter decisions
/// for fault localization via the SBFL module.
///
/// # Returns
///
/// * `Ok((String, DecisionTrace))` - Generated shell script and decision trace
/// * `Err(Error)` - Transpilation error
pub fn transpile_with_trace(input: &str, config: &Config) -> Result<(String, DecisionTrace)> {
    let validation_pipeline = validation::pipeline::ValidationPipeline::new(config);

    let ast = services::parser::parse(input)?;
    ast::validate(&ast)?;
    validation_pipeline.validate_ast(&ast)?;

    let ir = ir::from_ast(&ast)?;
    validation_pipeline.validate_ir(&ir)?;

    let optimized = ir::optimize(ir, config)?;
    let (shell_code, trace) = emitter::emit_with_trace(&optimized)?;

    validation_pipeline.validate_output(&shell_code)?;

    Ok((shell_code, trace))
}

/// Transpile Rust source code to POSIX shell script with lint validation.
///
/// Like [`transpile`], but additionally runs the built-in linter on the generated
/// shell output. Returns both the shell script and any lint diagnostics found.
///
/// # Arguments
///
/// * `input` - Rust source code as a string
/// * `config` - Configuration options for transpilation
///
/// # Returns
///
/// * `Ok((String, LintResult))` - Generated shell script and lint results
/// * `Err(Error)` - Transpilation error
pub fn transpile_with_lint(input: &str, config: &Config) -> Result<(String, linter::LintResult)> {
    let shell_code = transpile(input, config)?;
    let lint_result = linter::rules::lint_shell(&shell_code);
    Ok((shell_code, lint_result))
}

/// Transpile Rust source code to a Makefile.
///
/// Converts a Rust DSL into a valid Makefile using conventions:
/// - `let` bindings -> Makefile variables (`CC := gcc`)
/// - `target("name", &["deps"], &["recipes"])` -> Make targets
/// - `phony_target("name", ...)` -> `.PHONY` targets
///
/// # Arguments
///
/// * `input` - Rust source code using the Makefile DSL
/// * `config` - Configuration options
///
/// # Returns
///
/// * `Ok(String)` - Generated Makefile content
/// * `Err(Error)` - Transpilation error
pub fn transpile_makefile(input: &str, config: &Config) -> Result<String> {
    let _validation_pipeline = validation::pipeline::ValidationPipeline::new(config);

    let ast = services::parser::parse(input)?;
    ast::validate(&ast)?;

    emitter::makefile::emit_makefile(&ast)
}

/// Transpile Rust source code to a Dockerfile.
///
/// Converts a Rust DSL into a valid Dockerfile using conventions:
/// - `from_image("rust", "1.75-alpine")` -> `FROM rust:1.75-alpine`
/// - `run(&["cmd1", "cmd2"])` -> `RUN cmd1 && cmd2`
/// - `copy("src", "dst")` -> `COPY src dst`
/// - `workdir("/app")` -> `WORKDIR /app`
/// - `user("65534")` -> `USER 65534`
/// - `entrypoint(&["/app"])` -> `ENTRYPOINT ["/app"]`
///
/// # Arguments
///
/// * `input` - Rust source code using the Dockerfile DSL
/// * `config` - Configuration options
///
/// # Returns
///
/// * `Ok(String)` - Generated Dockerfile content
/// * `Err(Error)` - Transpilation error
pub fn transpile_dockerfile(input: &str, config: &Config) -> Result<String> {
    let _validation_pipeline = validation::pipeline::ValidationPipeline::new(config);

    let ast = services::parser::parse(input)?;
    ast::validate(&ast)?;

    emitter::dockerfile::emit_dockerfile(&ast)
}

/// Check if the given Rust code is valid for transpilation without generating output.
///
/// This function parses and validates the input Rust code but does not generate
/// shell script output. Useful for quick validation or IDE integration.
///
/// # Arguments
///
/// * `input` - Rust source code as a string
///
/// # Returns
///
/// * `Ok(())` - Code is valid and can be transpiled
/// * `Err(Error)` - Code has syntax or validation errors
///
/// # Examples
///
/// ## Valid Code
///
/// ```rust
/// use bashrs::check;
///
/// let valid_code = r#"
///     fn main() {
///         let x = 42;
///         let y = "hello";
///     }
/// "#;
///
/// assert!(check(valid_code).is_ok());
/// ```
///
/// ## Invalid Syntax
///
/// ```rust
/// use bashrs::check;
///
/// let invalid_code = "fn main( { }"; // Missing closing paren
/// assert!(check(invalid_code).is_err());
/// ```
///
/// ## Unsupported Features
///
/// ```rust
/// use bashrs::check;
///
/// let unsupported = r#"
///     fn main() {
///         let v = vec![1, 2, 3]; // Vec not supported in v1.0
///     }
/// "#;
///
/// // This may fail validation depending on the restricted subset
/// let result = check(unsupported);
/// ```
///
/// # Use Cases
///
/// - **IDE Integration**: Fast syntax checking without full transpilation
/// - **CI/CD Validation**: Verify Rash code before transpilation
/// - **Development**: Quick feedback loop for code validity
pub fn check(input: &str) -> Result<()> {
    let ast = services::parser::parse(input)?;
    ast::validate(&ast)?;
    Ok(())
}