# ishowta/firebase-rules-linter architecture

> Architecture diagram of the GitHub repository ishowta/firebase-rules-linter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ishowta/firebase-rules-linter
- Repository: https://github.com/ishowta/firebase-rules-linter

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% I/O Inputs
    RulesFile[/"Rules File (.rules)"/]:::io
    ConfigFile[/"Config File (.ruleslintrc.json)"/]:::io

    %% CLI Frontend
    CLI["CLI Frontend\n(main.rs)"]:::internal
    click CLI "https://github.com/ishowta/firebase-rules-linter/blob/main/src/main.rs"

    %% Configuration Loader
    ConfigLoader["Configuration Loader\n(config.rs)"]:::internal
    click ConfigLoader "https://github.com/ishowta/firebase-rules-linter/blob/main/src/config.rs"

    %% Parser Layer
    ParserTop["Parser Layer\n(parser.rs)"]:::parse
    click ParserTop "https://github.com/ishowta/firebase-rules-linter/blob/main/src/parser.rs"
    ParserInternal["Internal Query Parser\n(src/analyser/parser.rs)"]:::parse
    click ParserInternal "https://github.com/ishowta/firebase-rules-linter/blob/main/src/analyser/parser.rs"

    %% AST
    AST["AST Representation\n(ast.rs)"]:::internal
    click AST "https://github.com/ishowta/firebase-rules-linter/blob/main/src/ast.rs"

    %% Name Binder
    Binder["Name Binder\n(binder.rs)"]:::parse
    click Binder "https://github.com/ishowta/firebase-rules-linter/blob/main/src/binder.rs"
    Symbol["Symbol Table & Built-ins\n(symbol.rs)"]:::parse
    click Symbol "https://github.com/ishowta/firebase-rules-linter/blob/main/src/symbol.rs"
    Globals["Global Constants\n(globals.rs)"]:::parse
    click Globals "https://github.com/ishowta/firebase-rules-linter/blob/main/src/globals.rs"

    %% Type System
    TypeCore["Type System Core\n(ty.rs)"]:::type
    click TypeCore "https://github.com/ishowta/firebase-rules-linter/blob/main/src/ty.rs"
    TypeInterfaces["Type Interfaces\n(interfaces.rs)"]:::type
    click TypeInterfaces "https://github.com/ishowta/firebase-rules-linter/blob/main/src/interfaces.rs"

    %% Static Analyzer / Linter
    subgraph "Static Analyzer / Linter" 
        direction TB
        StaticAnalyzer["Analyzer Entry Point\n(checker.rs)"]:::type
        click StaticAnalyzer "https://github.com/ishowta/firebase-rules-linter/blob/main/src/checker.rs"
        AnalyserMod["Analyser Module\n(analyser.rs)"]:::type
        click AnalyserMod "https://github.com/ishowta/firebase-rules-linter/blob/main/src/analyser.rs"
        RuleExpr["Expr Checks\n(check_expression.rs)"]:::type
        click RuleExpr "https://github.com/ishowta/firebase-rules-linter/blob/main/src/analyser/check_expression.rs"
        RuleFunc["Function Checks\n(check_function.rs)"]:::type
        click RuleFunc "https://github.com/ishowta/firebase-rules-linter/blob/main/src/analyser/check_function.rs"
        RuleGlobalFunc["Global Function Checks\n(check_global_function.rs)"]:::type
        click RuleGlobalFunc "https://github.com/ishowta/firebase-rules-linter/blob/main/src/analyser/check_global_function.rs"
        RuleDestruct["Destruct/Sort Checks\n(destruct_sort.rs)"]:::type
        click RuleDestruct "https://github.com/ishowta/firebase-rules-linter/blob/main/src/analyser/destruct_sort.rs"
    end

    %% SMT Solver Integration
    subgraph "SMT Solver Integration" 
        direction TB
        SolverBuilder["Constraint Builder\n(solver.rs)"]:::smt
        click SolverBuilder "https://github.com/ishowta/firebase-rules-linter/blob/main/src/analyser/solver.rs"
        Z3Wrapper["Z3 API Wrapper\n(z3.rs)"]:::smt
        click Z3Wrapper "https://github.com/ishowta/firebase-rules-linter/blob/main/src/analyser/z3.rs"
        Libraries["SMT Libraries\n(lib.smt2, lib-lite.smt2)"]:::smt
        click Libraries "https://github.com/ishowta/firebase-rules-linter/blob/main/src/analyser/lib.smt2"
        click Libraries "https://github.com/ishowta/firebase-rules-linter/blob/main/src/analyser/lib-lite.smt2"
        Z3Service[(Z3 Theorem Prover)]:::external
    end

    %% Reporter
    Reporter["Result Reporter\n(via checker.rs)"]:::io
    click Reporter "https://github.com/ishowta/firebase-rules-linter/blob/main/src/checker.rs"

    %% Output
    Output[/"Lint Report\n(stdout/stderr)"/]:::io

    %% Flow
    RulesFile -->|"input file"| CLI
    ConfigFile -->|"config path"| CLI
    CLI -->|"args"| ConfigLoader
    ConfigLoader -->|"Config struct"| CLI
    CLI -->|"invoke parser"| ParserTop
    ParserTop -->|"raw AST"| AST
    AST --> Binder
    Binder -->|"scoped AST"| AST
    AST --> TypeCore
    TypeCore --> TypeInterfaces
    TypeInterfaces -->|"typed AST"| StaticAnalyzer
    StaticAnalyzer --> AnalyserMod
    AnalyserMod --> RuleExpr
    AnalyserMod --> RuleFunc
    AnalyserMod --> RuleGlobalFunc
    AnalyserMod --> RuleDestruct
    RuleExpr -->|"patterns"| SolverBuilder
    RuleFunc --> SolverBuilder
    RuleGlobalFunc --> SolverBuilder
    RuleDestruct --> SolverBuilder
    SolverBuilder -->|"SMT constraints"| Z3Wrapper
    Libraries --> Z3Wrapper
    Z3Wrapper -->|"sat/unsat"| SolverBuilder
    SolverBuilder -->|"solver results"| StaticAnalyzer
    StaticAnalyzer --> Reporter
    Reporter --> Output

    %% Legend
    classDef io fill:#dddddd,stroke:#333,stroke-width:1px;
    classDef parse fill:#cce5ff,stroke:#0066cc,stroke-width:1px;
    classDef type fill:#d4edda,stroke:#28a745,stroke-width:1px;
    classDef smt fill:#ffe5b4,stroke:#ff8800,stroke-width:1px;
    classDef internal fill:#f2f2f2,stroke:#888,stroke-width:1px;
    classDef external fill:#fff0f0,stroke:#dd0000,stroke-width:2px;
```
