How ishowta/firebase-rules-linter works
Project Type and Purpose
• This is a Rust-based command-line static analysis tool (an open-source linter) for Firebase security rules.
• It reads a .rules file (and optional JSON config), parses it into an AST, performs name binding, type checking, rule‐by‐rule analysis (lint checks), and leverages the Z3 theorem prover to discharge certain conditions.
• The output is a set of lint errors or confirmations that the ruleset passes all enabled checks.
High-Level Architectural Components
• CLI Frontend (main.rs)
• Parses command-line arguments (input rules file path + optional config).
• Loads configuration (config.rs) and hands off to the core pipeline.
• Configuration Loader (config.rs)
• Deserializes .ruleslintrc.json into an internal Config struct.
• Sets timeouts, enabled/disabled rules, and choice of SMT library.
• Parser Layer (parser.rs & src/analyser/parser.rs)
• parser.rs (top-level) implements the Firebase Rules grammar → produces a raw AST (ast.rs).
• May delegate to sub-parsers in src/analyser/parser.rs for internal query expressions.
• AST (ast.rs)
• Represents rules, functions, match blocks, expressions, identifiers, literals.
• Name Binder (binder.rs & symbol.rs & globals.rs)
• Resolves identifiers, scope nesting, path‐capture variables.
• Builds symbol tables for functions, built-in identifiers, global constants.
• Type System (ty.rs & interfaces.rs)
• Implements Firebase types (string, number, map, list, etc.) and coercion rules.
• Checks each expression and function signature, errors on mismatches.
• **Static Analyzer / Linter (checker.rs & src/analyser/\*.rs)**
• A suite of rule checkers (no-unused-vars, no-shadow, no-untyped-field, etc.).
• Each rule is a separate module under src/analyser/.
• Produces lint warnings/errors based on AST patterns and type information.
• SMT Solver Integration (z3.rs & solver.rs & lib.smt2 files)
• Builds SMT constraints for certain data‐validation checks (e.g., path‐capture patterns, size limits).
• Invokes Z3 via its API or command-line interface, reads unsat/sat responses.
• Two libraries lib.smt2 and lib-lite.smt2 are passed to Z3 depending on config.
• Result Reporter
• Aggregates errors from parser, binder, type checker, linter, and solver.
• Prints human-readable reports to stdout/stderr with file locations and suggestions.
Interactions and Data Flow
1. User invokes firebase-rules-linter <rules-file> [--config config.json].
2. CLI Frontend reads arguments → loads Config.
3. Parser processes the .rules text → produces AST.
4. Binder walks AST → resolves symbols → attaches scope/meta info.
5. Type Checker annotates AST nodes with types; errors out on mismatches.
6. Static Analyzer runs each lint rule module over the typed AST.
7. For rules requiring theorem proving, SMT Builder (solver.rs) emits SMT constraints + loads an SMT lib file → invokes Z3 → returns satisfiability results.
8. Reporter collects all errors/warnings → displays to the user.
Architectural Patterns and Design Principles
• Pipeline / Staged Processing: clear separation of parsing, binding, typing, analysis, and reporting.
• Modular Rule Engines: each lint rule is pluggable under src/analyser.
• External Solver Integration: isolation of solver logic in z3.rs and solver.rs keeps Z3 calls encapsulated.
• Configuration-Driven Behavior: feature flags in Config drive which rules run and which SMT library to use.