How fandango-fuzzer/fandango works
Project Type & Purpose
FANDANGO is an open-source, Python-based language-driven fuzzer and test-input generator. It provides:
– A CLI (and Python API) for users to specify grammars and semantic constraints
– A core “framework” implementing a genetic/evolutionary search over grammar-derived input populations
– An optional Language Server Protocol endpoint for editor integration
High-Level Directory & Component Breakdown
• src/fandango/cli → Command-line entry points, progress UI, suggestion store
• src/fandango/framework.py → The “application layer” glue for orchestrating grammar loading, search, constraint checking
• src/fandango/language → Grammar‐processing layer, including ANTLR parser files, convert/parse/grammar AST, symbol & tree modules
• src/fandango/constraints → Constraint‐checking layer (fitness functions, predicate definitions)
• src/fandango/evolution → Evolutionary search layer (population management, mutation, crossover, adaptation, evaluation)
• src/fandango/language/server → LSP server implementation
• utils & demo & docs & evaluation → External resources (conversion scripts, notebook demos, documentation, experimental harnesses)
Key Architectural Patterns
– Layered architecture: Presentation (CLI/API/LSP) → Orchestration (framework) → Domain services (grammar, constraints, evolution)
– Pipeline/feedback loop: Grammar → Candidate generation → Constraint evaluation → Selection & evolution → Repeat
– Plugin-style extensibility: Users can drop in new grammars (.fan), constraints (Python code), or even custom mutation/evolution strategies
Main Components & Their Interactions
[A] User Interfaces
• CLI: fando commands (src/fandango/cli)
• Python API: import framework.py in user scripts
• LSP Server: language_server.py for editor feedback
[B] Orchestration Layer
• Framework: loads grammar definitions, constraints, instantiates Evolution engine
[C] Core Domain Services
• Grammar Processor (language/*): uses ANTLR-generated parsers (FandangoLexer.g4, FandangoParser.g4) to build ASTs
• Constraint Checker (constraints/*): evaluates semantic constraints on generated inputs
• Evolution Engine (evolution/*): manages population, applies mutation, crossover, adaptation, selects next generation
[D] Outputs & Integrations
• Generated test inputs (console, files)
• Experiment harnesses (evaluation/*)
• Documentation site & Docker/PyPI packaging
Putting It All Together
– Start with the user actor on the left (Tester, Editor)
– Show the Presentation layer (CLI/API/LSP) → Orchestration (framework) → Core Domain (grammar, constraints, evolution)
– Branch off from Core Domain to “Generated Inputs” and “Evaluation Harness”
– Finally, link to External Services (PyPI, Docker Hub, CI) to illustrate packaging/deployment