flareguard 0.1.0

package/src/bindings/cli.rs

@@ -0,0 +1,49 @@
+use clap::{Parser, ValueEnum};
+use std::path::PathBuf;
+
+#[derive(Debug, Clone, Copy, ValueEnum)]
+pub enum CliFormat {
+    Text,
+    Json,
+    Sarif,
+}
+
+#[derive(Parser, Debug)]
+#[command(
+    name = "cf-binding-validator",
+    about = "⚡ Validate Cloudflare Worker/Pages bindings against Wrangler configuration",
+    version
+)]
+pub struct CliArgs {
+    /// Target files or directories to scan (defaults to current directory)
+    #[arg(default_value = ".")]
+    pub paths: Vec<PathBuf>,
+
+    /// Path to wrangler configuration (wrangler.jsonc, wrangler.json, or wrangler.toml)
+    #[arg(short = 'c', long = "config")]
+    pub config: Option<PathBuf>,
+
+    /// Wrangler environment to validate against (e.g. 'production', 'staging')
+    #[arg(short = 'e', long = "env")]
+    pub environment: Option<String>,
+
+    /// Check mode for CI/CD: exits with non-zero code if undeclared bindings exist
+    #[arg(long = "check")]
+    pub check: bool,
+
+    /// Strict mode: also fail CI if unused/ghost bindings exist
+    #[arg(long = "strict")]
+    pub strict: bool,
+
+    /// Output report format
+    #[arg(short = 'f', long = "format", value_enum, default_value_t = CliFormat::Text)]
+    pub format: CliFormat,
+
+    /// Comma-separated binding names to ignore if unused
+    #[arg(long = "ignore-unused", value_delimiter = ',')]
+    pub ignore_unused: Vec<String>,
+
+    /// Comma-separated binding names to ignore if undeclared
+    #[arg(long = "ignore-undeclared", value_delimiter = ',')]
+    pub ignore_undeclared: Vec<String>,
+}

package/src/bindings/jsonc.rs

@@ -0,0 +1,166 @@
+use std::error::Error;
+
+/// Strips JavaScript-style comments (`//` and `/* ... */`) and trailing commas from JSONC text,
+/// producing valid standard JSON.
+pub fn clean_jsonc(input: &str) -> String {
+    let chars: Vec<char> = input.chars().collect();
+    let len = chars.len();
+    let mut output = String::with_capacity(len);
+    let mut i = 0;
+    let mut in_string = false;
+    let mut is_escaped = false;
+
+    // Step 1: Strip comments while respecting strings
+    let mut no_comments = String::with_capacity(len);
+    while i < len {
+        let ch = chars[i];
+
+        if in_string {
+            no_comments.push(ch);
+            if is_escaped {
+                is_escaped = false;
+            } else if ch == '\\' {
+                is_escaped = true;
+            } else if ch == '"' {
+                in_string = false;
+            }
+            i += 1;
+            continue;
+        }
+
+        if ch == '"' {
+            in_string = true;
+            is_escaped = false;
+            no_comments.push(ch);
+            i += 1;
+            continue;
+        }
+
+        // Check for line comment //
+        if ch == '/' && i + 1 < len && chars[i + 1] == '/' {
+            i += 2;
+            while i < len && chars[i] != '\n' {
+                i += 1;
+            }
+            if i < len {
+                no_comments.push('\n');
+                i += 1;
+            }
+            continue;
+        }
+
+        // Check for block comment /* ... */
+        if ch == '/' && i + 1 < len && chars[i + 1] == '*' {
+            i += 2;
+            while i + 1 < len && !(chars[i] == '*' && chars[i + 1] == '/') {
+                if chars[i] == '\n' {
+                    no_comments.push('\n'); // Preserve line breaks for line numbering
+                }
+                i += 1;
+            }
+            i += 2; // skip */
+            continue;
+        }
+
+        no_comments.push(ch);
+        i += 1;
+    }
+
+    // Step 2: Strip trailing commas in objects and arrays
+    let nc_chars: Vec<char> = no_comments.chars().collect();
+    let nc_len = nc_chars.len();
+    let mut j = 0;
+    let mut in_str = false;
+    let mut esc = false;
+
+    while j < nc_len {
+        let ch = nc_chars[j];
+
+        if in_str {
+            output.push(ch);
+            if esc {
+                esc = false;
+            } else if ch == '\\' {
+                esc = true;
+            } else if ch == '"' {
+                in_str = false;
+            }
+            j += 1;
+            continue;
+        }
+
+        if ch == '"' {
+            in_str = true;
+            esc = false;
+            output.push(ch);
+            j += 1;
+            continue;
+        }
+
+        if ch == ',' {
+            // Peek ahead to see if the next non-whitespace character is `}` or `]`
+            let mut k = j + 1;
+            while k < nc_len && nc_chars[k].is_whitespace() {
+                k += 1;
+            }
+            if k < nc_len && (nc_chars[k] == '}' || nc_chars[k] == ']') {
+                // Skip the trailing comma
+                j += 1;
+                continue;
+            }
+        }
+
+        output.push(ch);
+        j += 1;
+    }
+
+    output
+}
+
+/// Parses JSONC or JSON text into a `serde_json::Value`.
+pub fn parse_jsonc(input: &str) -> Result<serde_json::Value, Box<dyn Error + Send + Sync>> {
+    let cleaned = clean_jsonc(input);
+    let val: serde_json::Value = serde_json::from_str(&cleaned)?;
+    Ok(val)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_clean_jsonc_basic() {
+        let jsonc = r#"
+        {
+            // This is a line comment
+            "name": "my-worker", /* inline comment */
+            "vars": {
+                "API_KEY": "https://api.example.com//test", // URL with slashes
+                "DEBUG": true,
+            },
+            "kv_namespaces": [
+                {
+                    "binding": "MY_KV",
+                    "id": "12345",
+                },
+            ],
+        }
+        "#;
+        let cleaned = clean_jsonc(jsonc);
+        let parsed: serde_json::Value =
+            serde_json::from_str(&cleaned).expect("Failed to parse cleaned JSON");
+        assert_eq!(parsed["name"], "my-worker");
+        assert_eq!(parsed["vars"]["API_KEY"], "https://api.example.com//test");
+        assert_eq!(parsed["vars"]["DEBUG"], true);
+        assert_eq!(parsed["kv_namespaces"][0]["binding"], "MY_KV");
+    }
+
+    #[test]
+    fn test_clean_jsonc_nested_trailing_commas() {
+        let jsonc = r#"{"a": [1, 2, [3, 4,],], "b": {"c": 1,},}"#;
+        let cleaned = clean_jsonc(jsonc);
+        let parsed: serde_json::Value = serde_json::from_str(&cleaned).unwrap();
+        assert_eq!(parsed["a"][2][0], 3);
+        assert_eq!(parsed["b"]["c"], 1);
+    }
+}

package/src/bindings/mod.rs

@@ -0,0 +1,7 @@
+pub mod ast_scanner;
+pub mod cli;
+pub mod jsonc;
+pub mod reporter;
+pub mod types;
+pub mod validator;
+pub mod wrangler;

package/src/bindings/reporter.rs

@@ -0,0 +1,328 @@
+use crate::bindings::types::{OutputFormat, ValidationReport};
+use colored::Colorize;
+use serde_json::json;
+use std::io::{self, Write};
+
+/// Render validation report according to requested OutputFormat.
+pub fn render_report(report: &ValidationReport, format: OutputFormat) -> io::Result<()> {
+    match format {
+        OutputFormat::Text => render_text_report(report),
+        OutputFormat::Json => render_json_report(report),
+        OutputFormat::Sarif => render_sarif_report(report),
+    }
+}
+
+/// Render rich human-readable terminal text output.
+pub fn render_text_report(report: &ValidationReport) -> io::Result<()> {
+    let mut stdout = io::stdout().lock();
+
+    writeln!(
+        stdout,
+        "{}",
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━".dimmed()
+    )?;
+    writeln!(
+        stdout,
+        "{}",
+        "  ⚡ Cloudflare Worker / Pages Binding Validator"
+            .bold()
+            .cyan()
+    )?;
+    writeln!(
+        stdout,
+        "{}",
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━".dimmed()
+    )?;
+
+    if let Some(cfg) = &report.config_file {
+        writeln!(stdout, "  {} {}", "Config:".bold(), cfg.white())?;
+    } else {
+        writeln!(
+            stdout,
+            "  {} {}",
+            "Config:".bold(),
+            "None found (all bindings treated as undeclared)".yellow()
+        )?;
+    }
+    writeln!(
+        stdout,
+        "  {} {}",
+        "Environment:".bold(),
+        report.environment.magenta()
+    )?;
+    writeln!(
+        stdout,
+        "  {} {}",
+        "Files Scanned:".bold(),
+        report.total_files_scanned.to_string().white()
+    )?;
+    writeln!(stdout)?;
+
+    // 1. Undeclared Bindings (Errors)
+    if !report.undeclared_accesses.is_empty() {
+        writeln!(
+            stdout,
+            "{}",
+            format!(
+                "  CRITICAL / ERROR: Undeclared Bindings ({} found)",
+                report.undeclared_accesses.len()
+            )
+            .bold()
+            .red()
+        )?;
+        writeln!(
+            stdout,
+            "  {}",
+            "These bindings are accessed in code but NOT declared in Wrangler config."
+                .red()
+                .italic()
+        )?;
+        writeln!(
+            stdout,
+            "  {}",
+            "Risk: Runtime TypeError / crash when accessing undefined property at runtime."
+                .red()
+                .italic()
+        )?;
+        writeln!(stdout)?;
+
+        for access in &report.undeclared_accesses {
+            let loc = format!("{}:{}:{}", access.file_path, access.line, access.column);
+            writeln!(
+                stdout,
+                "    {} {} in {}",
+                "✖".bold().red(),
+                access.name.bold().bright_red(),
+                loc.underline().dimmed()
+            )?;
+            writeln!(
+                stdout,
+                "      {} `{}`",
+                "Expression:".dimmed(),
+                access.raw_expression.bright_yellow()
+            )?;
+            writeln!(
+                stdout,
+                "      {} Declare `{}` in your wrangler configuration (e.g. `vars`, `kv_namespaces`, `d1_databases`)",
+                "Fix Hint:".bold().cyan(),
+                access.name.bright_white()
+            )?;
+            writeln!(stdout)?;
+        }
+    }
+
+    // 2. Ghost / Unused Bindings (Warnings)
+    if !report.ghost_bindings.is_empty() {
+        writeln!(
+            stdout,
+            "{}",
+            format!(
+                "  WARNING: Ghost / Unused Bindings ({} found)",
+                report.ghost_bindings.len()
+            )
+            .bold()
+            .yellow()
+        )?;
+        writeln!(
+            stdout,
+            "  {}",
+            "These bindings are declared in Wrangler config but never referenced in code."
+                .yellow()
+                .italic()
+        )?;
+        writeln!(
+            stdout,
+            "  {}",
+            "Recommendation: Remove unused bindings to keep infrastructure lean.".dimmed()
+        )?;
+        writeln!(stdout)?;
+
+        for ghost in &report.ghost_bindings {
+            let details_str = ghost
+                .details
+                .as_deref()
+                .map(|d| format!(" ({})", d))
+                .unwrap_or_default();
+            writeln!(
+                stdout,
+                "    {} {} [{}{}] in {}",
+                "▲".bold().yellow(),
+                ghost.name.bold().bright_yellow(),
+                ghost.binding_type,
+                details_str.dimmed(),
+                ghost.file.dimmed()
+            )?;
+        }
+        writeln!(stdout)?;
+    }
+
+    // 3. Valid / Active Bindings Summary
+    if !report.valid_bindings.is_empty() {
+        writeln!(
+            stdout,
+            "{}",
+            format!(
+                "  SYNCHRONIZED BINDINGS ({} active)",
+                report.valid_bindings.len()
+            )
+            .bold()
+            .green()
+        )?;
+        for valid in &report.valid_bindings {
+            writeln!(
+                stdout,
+                "    {} {} [{}] ({} reference{})",
+                "✔".bold().green(),
+                valid.binding.name.bold().bright_white(),
+                valid.binding.binding_type.to_string().dimmed(),
+                valid.access_count,
+                if valid.access_count == 1 { "" } else { "s" }
+            )?;
+        }
+        writeln!(stdout)?;
+    }
+
+    // Summary Box
+    writeln!(
+        stdout,
+        "{}",
+        "─────────────────────────────────────────────────────────────────────".dimmed()
+    )?;
+    let status_str = if report.is_success {
+        "✓ VALIDATION PASSED".bold().bright_green()
+    } else {
+        "✗ VALIDATION FAILED".bold().bright_red()
+    };
+
+    let errors_str = if report.undeclared_accesses.is_empty() {
+        report.undeclared_accesses.len().to_string().green()
+    } else {
+        report.undeclared_accesses.len().to_string().red().bold()
+    };
+
+    let warnings_str = if report.ghost_bindings.is_empty() {
+        report.ghost_bindings.len().to_string().green()
+    } else {
+        report.ghost_bindings.len().to_string().yellow().bold()
+    };
+
+    writeln!(
+        stdout,
+        "  Status: {}  |  Declared: {}  |  Scanned Accesses: {}  |  Errors: {}  |  Warnings: {}",
+        status_str,
+        report.total_declared.to_string().white(),
+        report.total_accesses.to_string().white(),
+        errors_str,
+        warnings_str,
+    )?;
+    writeln!(
+        stdout,
+        "{}",
+        "─────────────────────────────────────────────────────────────────────".dimmed()
+    )?;
+
+    Ok(())
+}
+
+/// Render JSON format.
+pub fn render_json_report(report: &ValidationReport) -> io::Result<()> {
+    let json_str = serde_json::to_string_pretty(report)
+        .map_err(|e| io::Error::other(e.to_string()))?;
+    println!("{}", json_str);
+    Ok(())
+}
+
+/// Render SARIF format (v2.1.0 standard for GitHub Actions / Code Scanning).
+pub fn render_sarif_report(report: &ValidationReport) -> io::Result<()> {
+    let mut results = Vec::new();
+
+    // Undeclared binding errors
+    for access in &report.undeclared_accesses {
+        results.push(json!({
+            "ruleId": "cf001-undeclared-binding",
+            "level": "error",
+            "message": {
+                "text": format!("Binding '{}' accessed in code via `{}` is not declared in Wrangler config.", access.name, access.raw_expression)
+            },
+            "locations": [{
+                "physicalLocation": {
+                    "artifactLocation": {
+                        "uri": access.file_path.replace("\\", "/")
+                    },
+                    "region": {
+                        "startLine": access.line,
+                        "startColumn": access.column
+                    }
+                }
+            }]
+        }));
+    }
+
+    // Ghost binding warnings
+    for ghost in &report.ghost_bindings {
+        results.push(json!({
+            "ruleId": "cf002-ghost-binding",
+            "level": "warning",
+            "message": {
+                "text": format!("Binding '{}' [{}] declared in '{}' is never referenced in source code.", ghost.name, ghost.binding_type, ghost.file)
+            },
+            "locations": [{
+                "physicalLocation": {
+                    "artifactLocation": {
+                        "uri": ghost.file.replace("\\", "/")
+                    },
+                    "region": {
+                        "startLine": 1,
+                        "startColumn": 1
+                    }
+                }
+            }]
+        }));
+    }
+
+    let sarif = json!({
+        "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [{
+            "tool": {
+                "driver": {
+                    "name": "cf-binding-validator",
+                    "informationUri": "https://github.com/cloudflare/wrangler",
+                    "version": env!("CARGO_PKG_VERSION"),
+                    "rules": [
+                        {
+                            "id": "cf001-undeclared-binding",
+                            "name": "UndeclaredBindingAccess",
+                            "shortDescription": {
+                                "text": "Binding is accessed in code without being declared in Wrangler config"
+                            },
+                            "fullDescription": {
+                                "text": "Accessing undefined environment bindings at runtime causes TypeErrors and Worker crashes."
+                            },
+                            "defaultConfiguration": {
+                                "level": "error"
+                            }
+                        },
+                        {
+                            "id": "cf002-ghost-binding",
+                            "name": "GhostBindingDeclared",
+                            "shortDescription": {
+                                "text": "Binding is declared in Wrangler configuration but never referenced in code"
+                            },
+                            "fullDescription": {
+                                "text": "Unused bindings add maintenance overhead and clutter configuration."
+                            },
+                            "defaultConfiguration": {
+                                "level": "warning"
+                            }
+                        }
+                    ]
+                }
+            },
+            "results": results
+        }]
+    });
+
+    println!("{}", serde_json::to_string_pretty(&sarif).unwrap());
+    Ok(())
+}

package/src/bindings/types.rs

@@ -0,0 +1,129 @@
+use serde::{Deserialize, Serialize};
+use std::fmt;
+
+/// The type of Cloudflare Worker/Pages binding declared in Wrangler configuration.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum BindingType {
+    KvNamespace,
+    D1Database,
+    R2Bucket,
+    QueueProducer,
+    QueueConsumer,
+    Vectorize,
+    Hyperdrive,
+    Ai,
+    Service,
+    AnalyticsEngine,
+    DurableObject,
+    Workflow,
+    Browser,
+    SendEmail,
+    MtlsCertificate,
+    Pipeline,
+    Assets,
+    Var,
+    Secret,
+    Unknown(String),
+}
+
+impl fmt::Display for BindingType {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            BindingType::KvNamespace => write!(f, "KV Namespace"),
+            BindingType::D1Database => write!(f, "D1 Database"),
+            BindingType::R2Bucket => write!(f, "R2 Bucket"),
+            BindingType::QueueProducer => write!(f, "Queue Producer"),
+            BindingType::QueueConsumer => write!(f, "Queue Consumer"),
+            BindingType::Vectorize => write!(f, "Vectorize Index"),
+            BindingType::Hyperdrive => write!(f, "Hyperdrive"),
+            BindingType::Ai => write!(f, "Workers AI"),
+            BindingType::Service => write!(f, "Service Binding"),
+            BindingType::AnalyticsEngine => write!(f, "Analytics Engine Dataset"),
+            BindingType::DurableObject => write!(f, "Durable Object"),
+            BindingType::Workflow => write!(f, "Workflow"),
+            BindingType::Browser => write!(f, "Browser Rendering"),
+            BindingType::SendEmail => write!(f, "Send Email"),
+            BindingType::MtlsCertificate => write!(f, "mTLS Certificate"),
+            BindingType::Pipeline => write!(f, "Pipeline"),
+            BindingType::Assets => write!(f, "Static Assets"),
+            BindingType::Var => write!(f, "Environment Variable (var)"),
+            BindingType::Secret => write!(f, "Secret"),
+            BindingType::Unknown(name) => write!(f, "Custom ({})", name),
+        }
+    }
+}
+
+/// A binding declared in `wrangler.jsonc`, `wrangler.json`, or `wrangler.toml`.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DeclaredBinding {
+    pub name: String,
+    pub binding_type: BindingType,
+    pub file: String,
+    pub environment: String,
+    pub details: Option<String>,
+}
+
+/// How a binding was accessed in source code.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AccessKind {
+    DirectMember,
+    Destructured,
+    ParamDestructured,
+    HelperCall,
+    ProcessEnv,
+}
+
+impl fmt::Display for AccessKind {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            AccessKind::DirectMember => write!(f, "property access"),
+            AccessKind::Destructured => write!(f, "destructuring"),
+            AccessKind::ParamDestructured => write!(f, "parameter destructuring"),
+            AccessKind::HelperCall => write!(f, "helper call"),
+            AccessKind::ProcessEnv => write!(f, "process.env access"),
+        }
+    }
+}
+
+/// An instance in source code where a binding was accessed.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BindingAccess {
+    pub name: String,
+    pub file_path: String,
+    pub line: usize,
+    pub column: usize,
+    pub raw_expression: String,
+    pub access_kind: AccessKind,
+}
+
+/// Information about a binding that was successfully matched between config and code.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ValidBindingInfo {
+    pub binding: DeclaredBinding,
+    pub access_count: usize,
+    pub accesses: Vec<BindingAccess>,
+}
+
+/// Complete report of the validation process.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ValidationReport {
+    pub config_file: Option<String>,
+    pub environment: String,
+    pub total_files_scanned: usize,
+    pub total_declared: usize,
+    pub total_accesses: usize,
+    pub undeclared_accesses: Vec<BindingAccess>,
+    pub ghost_bindings: Vec<DeclaredBinding>,
+    pub valid_bindings: Vec<ValidBindingInfo>,
+    pub is_success: bool,
+}
+
+/// Output formats supported by the CLI.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OutputFormat {
+    Text,
+    Json,
+    Sarif,
+}