flarelint 0.1.0

Unified, nanosecond-fast Rust AST static analysis and edge compatibility linter for Cloudflare Workers & Astro applications
Documentation
use serde::{Deserialize, Serialize};
use std::collections::HashSet;
use std::path::Path;

use crate::diagnostics::{Diagnostic, SourceLocation};

const MAX_PAGES_ROUTES_LIMIT: usize = 100;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RoutesConfig {
    pub version: u32,
    #[serde(default)]
    pub include: Vec<String>,
    #[serde(default)]
    pub exclude: Vec<String>,
}

pub struct RoutesLinter<'a> {
    pub file_path: &'a Path,
    pub full_source: &'a str,
    pub diagnostics: Vec<Diagnostic>,
}

impl<'a> RoutesLinter<'a> {
    pub fn new(file_path: &'a Path, full_source: &'a str) -> Self {
        Self {
            file_path,
            full_source,
            diagnostics: Vec::new(),
        }
    }

    pub fn lint(&mut self) {
        let parsed: Result<RoutesConfig, _> = serde_json::from_str(self.full_source);
        let config = match parsed {
            Ok(c) => c,
            Err(e) => {
                let diag = Diagnostic::error(
                    "routes/invalid-json",
                    format!("Malformed _routes.json: {}", e),
                    self.file_path,
                )
                .with_location(SourceLocation::new(1, 1, 0, 0));
                self.diagnostics.push(diag);
                return;
            }
        };

        if config.version != 1 {
            let loc = self.find_line_offset("\"version\"");
            let diag = Diagnostic::error(
                "routes/invalid-version",
                format!(
                    "Invalid version {}. Cloudflare Pages requires version: 1",
                    config.version
                ),
                self.file_path,
            )
            .with_location(loc)
            .with_suggestion("Set \"version\": 1", Some("\"version\": 1".to_string()));
            self.diagnostics.push(diag);
        }

        let total_rules = config.include.len() + config.exclude.len();
        if total_rules > MAX_PAGES_ROUTES_LIMIT {
            let diag = Diagnostic::error(
                "routes/exceeds-limit",
                format!(
                    "Total route count ({}) exceeds Cloudflare Pages limit of {} rules (include: {}, exclude: {}).",
                    total_rules, MAX_PAGES_ROUTES_LIMIT, config.include.len(), config.exclude.len()
                ),
                self.file_path,
            )
            .with_location(SourceLocation::new(1, 1, 0, 0))
            .with_suggestion(
                format!("Reduce rules to <= {} by consolidating paths with wildcards (e.g. '/api/*').", MAX_PAGES_ROUTES_LIMIT),
                None,
            );
            self.diagnostics.push(diag);
        } else if total_rules >= 90 {
            let diag = Diagnostic::warning(
                "routes/approaching-limit",
                format!(
                    "Total route count ({}) is approaching the Cloudflare Pages limit of {} rules.",
                    total_rules, MAX_PAGES_ROUTES_LIMIT
                ),
                self.file_path,
            )
            .with_location(SourceLocation::new(1, 1, 0, 0));
            self.diagnostics.push(diag);
        }

        if config.include.is_empty() {
            let diag = Diagnostic::error(
                "routes/missing-include",
                "Cloudflare Pages _routes.json requires at least 1 'include' rule (e.g. '/*').",
                self.file_path,
            )
            .with_location(SourceLocation::new(1, 1, 0, 0))
            .with_suggestion(
                "Add '\"include\": [\"/*\"]'",
                Some("\"include\": [\"/*\"]".to_string()),
            );
            self.diagnostics.push(diag);
        }

        let mut seen_includes = HashSet::new();
        for rule in &config.include {
            self.validate_pattern(rule);
            if !seen_includes.insert(rule) {
                let loc = self.find_line_offset(rule);
                let diag = Diagnostic::warning(
                    "routes/duplicate-rule",
                    format!("Duplicate include rule '{}'", rule),
                    self.file_path,
                )
                .with_location(loc)
                .with_suggestion(format!("Remove duplicate rule '{}'", rule), None);
                self.diagnostics.push(diag);
            }
        }

        let mut seen_excludes = HashSet::new();
        for rule in &config.exclude {
            self.validate_pattern(rule);
            if !seen_excludes.insert(rule) {
                let loc = self.find_line_offset(rule);
                let diag = Diagnostic::warning(
                    "routes/duplicate-rule",
                    format!("Duplicate exclude rule '{}'", rule),
                    self.file_path,
                )
                .with_location(loc)
                .with_suggestion(format!("Remove duplicate rule '{}'", rule), None);
                self.diagnostics.push(diag);
            }
        }

        for (i, r1) in config.include.iter().enumerate() {
            for (j, r2) in config.include.iter().enumerate() {
                if i != j && self.pattern_shadows(r1, r2) {
                    let loc = self.find_line_offset(r2);
                    let diag = Diagnostic::warning(
                        "routes/shadowed-rule",
                        format!(
                            "Include rule '{}' is redundant because it is already matched by '{}'.",
                            r2, r1
                        ),
                        self.file_path,
                    )
                    .with_location(loc)
                    .with_suggestion(format!("Remove shadowed rule '{}'", r2), None);
                    self.diagnostics.push(diag);
                }
            }
        }

        for exc in &config.exclude {
            let matched_by_any = config
                .include
                .iter()
                .any(|inc| self.pattern_matches_or_overlaps(inc, exc));
            if !matched_by_any && !config.include.is_empty() {
                let loc = self.find_line_offset(exc);
                let diag = Diagnostic::warning(
                    "routes/unmatched-exclude",
                    format!("Exclude rule '{}' is unnecessary because no include rule matches its path prefix.", exc),
                    self.file_path,
                )
                .with_location(loc)
                .with_suggestion(format!("Remove unneeded exclude rule '{}' to save quota", exc), None);
                self.diagnostics.push(diag);
            }
        }
    }

    fn validate_pattern(&mut self, pattern: &str) {
        let loc = self.find_line_offset(pattern);

        if !pattern.starts_with('/') {
            let diag = Diagnostic::error(
                "routes/invalid-path",
                format!("Route pattern '{}' must start with '/'", pattern),
                self.file_path,
            )
            .with_location(loc)
            .with_suggestion(
                format!("Prepend '/' to '/{}'", pattern.trim_start_matches('/')),
                Some(format!("/{}", pattern)),
            );
            self.diagnostics.push(diag);
            return;
        }

        if let Some(star_pos) = pattern.find('*')
            && star_pos != pattern.len() - 1
        {
            let diag = Diagnostic::error(
                    "routes/invalid-glob",
                    format!(
                        "Cloudflare Pages wildcards ('*') can only appear at the end of a route pattern (e.g. '/api/*'). In '{}', wildcard is at position {}.",
                        pattern, star_pos
                    ),
                    self.file_path,
                )
                .with_location(loc)
                .with_suggestion(
                    "Move wildcard to the end of the prefix or use exact matching.",
                    None,
                );
            self.diagnostics.push(diag);
        }

        if pattern.contains("//") {
            let diag = Diagnostic::warning(
                "routes/double-slash",
                format!(
                    "Route pattern '{}' contains consecutive slashes '//'",
                    pattern
                ),
                self.file_path,
            )
            .with_location(loc);
            self.diagnostics.push(diag);
        }
    }

    fn pattern_shadows(&self, broader: &str, narrower: &str) -> bool {
        if broader == "/*" && narrower != "/*" {
            return true;
        }
        if let Some(prefix) = broader.strip_suffix("/*")
            && narrower.starts_with(prefix)
            && narrower != broader
        {
            return true;
        }
        false
    }

    fn pattern_matches_or_overlaps(&self, include: &str, exclude: &str) -> bool {
        if include == "/*" {
            return true;
        }
        if let Some(prefix) = include.strip_suffix("/*")
            && exclude.starts_with(prefix)
        {
            return true;
        }
        if include == exclude {
            return true;
        }
        false
    }

    fn find_line_offset(&self, query: &str) -> SourceLocation {
        let mut offset = 0;

        for (line_num, line) in (1..).zip(self.full_source.lines()) {
            if let Some(col) = line.find(query) {
                return SourceLocation::new(line_num, col + 1, offset + col, query.len());
            }
            offset += line.len() + 1;
        }

        SourceLocation::new(1, 1, 0, query.len())
    }
}