How flowr-analysis/flowr works
Below are detailed guidelines tailored to flowR’s architecture:
Main Components
• Command Line & REPL Interface: This is the entry point for users. It is represented by components in the “src/cli” directory (including both the REPL and various CLI apps such as “benchmark-app”, “slicer-app”, or “statistics-app”). This layer handles user commands, input file selection, and dispatching operations.
• Abstract Interpretation and Parsing Modules: These are responsible for interpreting the input R code. Key pieces are found in “src/abstract-interpretation”, “src/core/steps”, and in the parser sections of “src/r-bridge/lang-4.x/ast”. They process the source code into an intermediate representation (AST, normalized AST), and then apply both static analysis and dataflow extraction.
• Dataflow Analysis Engine: Distributed throughout “src/dataflow”, this module builds and maintains dataflow graphs, handles environments, links and graph resolution. It is critical for both the slicing and query operations.
• Query & Slicing Engine: Under “src/queries” and “src/slicing”, these components implement the domain-specific queries (e.g., dependencies, lineage, static slicing queries) and perform the slicing operation to extract the relevant portions of the code.
• R Bridge & Integration: Found extensively in “src/r-bridge”, this component provides support for language-specific constructs, interfacing with R’s parsing mechanisms (even including WebAssembly modules for tree-sitter support) to connect R’s semantics to flowR’s analysis.
• Benchmarking & Statistics: These modules (in “src/benchmark” and “src/statistics”) handle performance measurements and statistical analyses of processed data, which may feed back into both quality assurance and optimization efforts.
• Utilities & Documentation: The “src/util” provides helper functions (for logging, file operations, ANSI formatting, etc.) while “src/documentation” and the “wiki” folder serve external documentation and usage examples, but can be abstracted as supporting components in the overall architecture.
Relationships and Interactions
• The CLI layer collects user input (possibly via Docker, npm, or direct command-line calls) and passes the R source files onto the Core Pipeline Executor.
• The Pipeline Executor coordinates various processing stages: it sends source code to the Parser/Abstract Interpretation modules, which build an internal representation (AST and normalized AST).
• Next, the Dataflow Analysis Engine processes the intermediate representations to generate data/control flow graphs and compute dependencies.
• The Query Engine (including slicing queries) operates on these representations, providing targeted outputs such as slices or dependency graphs.
• The R Bridge acts as an intermediary layer that deals specifically with nuances of the R language—processing its syntax and semantics using dedicated parsers and tree-sitter executables.
• Supporting modules for performance benchmarking and statistical analysis are integrated within the pipeline to provide feedback on efficiency and to quantify aspects of the analysis.
Architectural Patterns & Design Principles
• Modular Architecture: The project follows a clear separation of concerns, with distinct modules for CLI, core processing, language parsing, dataflow analysis, queries, and utilities.
• Pipeline/Step-Execution Pattern: The “pipeline” design, seen in “src/core/steps” and “src/core/pipeline”, supports sequential stages in program analysis.
• Abstraction & Extensibility: The design encourages modularity (e.g., separate “built-in” handling under dataflow processes, abstract interpretation modules, and query catalogs) to allow for easy extended analyses.