# stnuessl/rf architecture

> Architecture diagram of the GitHub repository stnuessl/rf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stnuessl/rf
- Repository: https://github.com/stnuessl/rf

## Overview

##### Project Type and Purpose
- This is an open-source, command-line refactoring tool for C and C++ (“rf”).
- It parses, analyzes, and rewrites source code using Clang/LLVM libraries to perform safe, batchable renames of tags, functions, variables, macros, includes, namespaces, etc.

##### High-Level Architecture
At a glance, rf’s pipeline consists of:
· CLI Frontend
· Configuration & Database Loader
· Clang Tooling Integration
· Preprocessor Callback Dispatcher
· AST Consumer / Visitor
· Refactoring Action Factory → Refactorers
· Replacement Engine & File Writer
· Utilities & Tests

##### Major Components
A. CLI Frontend (src/main.cpp)
– Parses command-line flags (util/commandline.cpp/.hpp).
– Reads batch files or individual refactor commands.
B. Compilation Database Loader (util/CompilationDatabase.cpp/.hpp)
– Loads compile_commands.json for project compilation context.
C. Clang Tooling (libclang, llvm)
– Invokes ClangTool with file list and compiler arguments.
D. Preprocessor Callback Dispatcher (PPCallbackDispatcher.cpp/.hpp)
– Hooks into Clang’s preprocessor to track include directives and macros.
E. AST Processing
1. RefactoringASTConsumer (src/RefactoringASTConsumer.cpp/.hpp)
2. RefactoringASTVisitor (src/RefactoringASTVisitor.cpp/.hpp)
– Traverses AST nodes.
F. RefactoringActionFactory (src/RefactoringActionFactory.cpp/.hpp)
– Determines which specific Refactorer to apply based on CLI flags.
G. Refactorers (src/Refactorers/)
– Base classes (Refactorer.hpp) + specialized modules:
- NameRefactorer, FunctionRefactorer, MacroRefactorer, VariableRefactorer, EnumConstantRefactorer, IncludeRefactorer, NamespaceRefactorer, TagRefactorer
– Each encapsulates logic for finding and emitting replacements for its entity type.
H. Replacement Engine & Writer (inside Refactorers + Clang tooling)
– Collects clang::tooling::Replacements, applies them to the file system.
I. Utilities (src/util/)
– memory management, string utilities, YAML parsing (for batching), command-line helpers.
J. Testing Harness (test/)
– Sample code, YAML recipes, shell scripts to validate replacements.
K. Bash-Completion (bash-completion/rf)
– Auto-completion integration for the rf binary.
L. Project Scripts (utils/)
– fix-jcdb.py and make-jcdb.py to massage compile_commands.json for compatibility.

##### Component Relationships & Data Flow
1. User runs “rf” → main.cpp (CLI)
2. CLI invokes util/commandline → constructs RefactorOptions
3. CompilationDatabase reads compile_commands.json → supplies file list + flags
4. ClangTool is created with file list + flags
5. PPCallbackDispatcher registered → intercepts preprocessor events
6. RefactoringASTConsumer + RefactoringASTVisitor traverse each AST → emit callbacks
7. RefactoringActionFactory chooses and instantiates specific Refactorer(s)
8. Each Refactorer examines AST nodes, generates clang::tooling::Replacement
9. Collected replacements are applied and written back to disk
10. Optional: YAML util writes/reads batch definitions
11. Tests invoke rf against sample code and compare expected outputs

##### Architectural Patterns & Principles
- Visitor Pattern: ASTVisitor for decoupled traversal.
- Factory Pattern: RefactoringActionFactory to select Refactorer modules.
- Single-Responsibility: each Refactorer only handles one kind of renaming.
- Extensibility: new Refactorer modules can be added under src/Refactorers.
- Separation of Concerns: clear layers—CLI, config loader, Clang integration, AST processing, refactoring logic, utilities.

##### Technologies, Frameworks, Libraries
- C++11/14, STL
- LLVM / Clang Tooling & libclang
- YAML parser (custom in util/yaml.cpp)
- GNU Make (Makefile)
- Bash (completion script)
- Python (utils/fix-jcdb.py, utils/make-jcdb.py) for CI/setup support

##### Detail Level
- Every directory as a sub-component.
- How util/yaml plugs into batching feature.
- Test/ as a separate validation workflow.
- Do not over-abstract—display each Refactorer submodule if desired.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        CLI["CLI Frontend"]:::frontend
        CLIP["Command-Line Parser"]:::frontend
    end

    %% Data Store
    compileDBData["compile_commands.json"]:::db

    %% Core Engine Layer
    subgraph "Core Engine"
        ClangTool["ClangTool (Clang/LLVM)"]:::core
        PPDispatcher["Preprocessor Callback Dispatcher"]:::core
        ASTConsumer["RefactoringASTConsumer"]:::core
        ASTVisitor["RefactoringASTVisitor"]:::core
        ActionFactory["RefactoringActionFactory"]:::core
    end

    %% Extensions Layer
    subgraph "Refactorers (Extensions)"
        subgraph "Base Refactorers"
            BaseR["Base Refactorer"]:::ext
            NameR["Name Refactorer"]:::ext
        end
        FunctionR["Function Refactorer"]:::ext
        MacroR["Macro Refactorer"]:::ext
        VariableR["Variable Refactorer"]:::ext
        EnumR["Enum Constant Refactorer"]:::ext
        IncludeR["Include Refactorer"]:::ext
        NamespaceR["Namespace Refactorer"]:::ext
        TagR["Tag Refactorer"]:::ext
    end

    %% Replacement & File System
    ReplacementEngine["Replacement Engine & Writer"]:::core
    FileSystem["File System"]:::db

    %% Utilities & Tests
    subgraph "Utilities & Support"
        subgraph "Utilities"
            MemUtil["Memory Utilities"]:::util
            StrUtil["String Utilities"]:::util
            YAMLUtil["YAML Batching Parser"]:::util
        end
        subgraph "Support Scripts"
            BashComp["Bash-Completion Script"]:::util
            FixJCDB["fix-jcdb.py"]:::util
            MakeJCDB["make-jcdb.py"]:::util
        end
        TestHarness["Testing Harness"]:::util
    end

    %% Connections
    CLI -->|"invokes"| CLIP
    CLIP -->|"Options"| CompilationDB
    CompilationDB["CompilationDB Loader"]:::frontend -->|"FileList+Flags"| ClangTool
    compileDBData -->|"reads"| CompilationDB
    ClangTool -->|"registers"| PPDispatcher
    PPDispatcher -->|"PreprocessorEvents"| ASTConsumer
    ASTConsumer -->|"ASTNodes"| ASTVisitor
    ASTVisitor -->|"visits"| ActionFactory
    ActionFactory -->|"selects"| BaseR
    ActionFactory --> NameR
    ActionFactory --> FunctionR
    ActionFactory --> MacroR
    ActionFactory --> VariableR
    ActionFactory --> EnumR
    ActionFactory --> IncludeR
    ActionFactory --> NamespaceR
    ActionFactory --> TagR
    BaseR & NameR & FunctionR & MacroR & VariableR & EnumR & IncludeR & NamespaceR & TagR -->|"generate Replacements"| ReplacementEngine
    ReplacementEngine -->|"apply"| FileSystem
    CLI -->|"batch YAML"| YAMLUtil
    MemUtil & StrUtil & YAMLUtil -->|"support"| CLI
    FixJCDB & MakeJCDB -->|"generate"| compileDBData
    BashComp -->|"provides"| CLI
    TestHarness -->|"validates against"| FileSystem

    %% Click Events
    click CLI "https://github.com/stnuessl/rf/blob/master/src/main.cpp"
    click CLIP "https://github.com/stnuessl/rf/blob/master/src/util/commandline.cpp"
    click CLIP "https://github.com/stnuessl/rf/blob/master/src/util/commandline.hpp"
    click CompilationDB "https://github.com/stnuessl/rf/blob/master/src/util/CompilationDatabase.cpp"
    click CompilationDB "https://github.com/stnuessl/rf/blob/master/src/util/CompilationDatabase.hpp"
    click ClangTool "https://github.com/stnuessl/rf/blob/master/src/ToolThread.cpp"
    click ClangTool "https://github.com/stnuessl/rf/blob/master/src/ToolThread.hpp"
    click PPDispatcher "https://github.com/stnuessl/rf/blob/master/src/PPCallbackDispatcher.cpp"
    click PPDispatcher "https://github.com/stnuessl/rf/blob/master/src/PPCallbackDispatcher.hpp"
    click ASTConsumer "https://github.com/stnuessl/rf/blob/master/src/RefactoringASTConsumer.cpp"
    click ASTConsumer "https://github.com/stnuessl/rf/blob/master/src/RefactoringASTConsumer.hpp"
    click ASTVisitor "https://github.com/stnuessl/rf/blob/master/src/RefactoringASTVisitor.cpp"
    click ASTVisitor "https://github.com/stnuessl/rf/blob/master/src/RefactoringASTVisitor.hpp"
    click ActionFactory "https://github.com/stnuessl/rf/blob/master/src/RefactoringActionFactory.cpp"
    click ActionFactory "https://github.com/stnuessl/rf/blob/master/src/RefactoringActionFactory.hpp"
    click BaseR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/Base/Refactorer.cpp"
    click BaseR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/Base/Refactorer.hpp"
    click NameR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/Base/NameRefactorer.cpp"
    click NameR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/Base/NameRefactorer.hpp"
    click FunctionR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/FunctionRefactorer.cpp"
    click FunctionR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/FunctionRefactorer.hpp"
    click MacroR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/MacroRefactorer.cpp"
    click MacroR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/MacroRefactorer.hpp"
    click VariableR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/VariableRefactorer.cpp"
    click VariableR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/VariableRefactorer.hpp"
    click EnumR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/EnumConstantRefactorer.cpp"
    click EnumR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/EnumConstantRefactorer.hpp"
    click IncludeR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/IncludeRefactorer.cpp"
    click IncludeR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/IncludeRefactorer.hpp"
    click NamespaceR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/NamespaceRefactorer.cpp"
    click NamespaceR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/NamespaceRefactorer.hpp"
    click TagR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/TagRefactorer.cpp"
    click TagR "https://github.com/stnuessl/rf/blob/master/src/Refactorers/TagRefactorer.hpp"
    click MemUtil "https://github.com/stnuessl/rf/blob/master/src/util/memory.cpp"
    click MemUtil "https://github.com/stnuessl/rf/blob/master/src/util/memory.hpp"
    click StrUtil "https://github.com/stnuessl/rf/blob/master/src/util/string.cpp"
    click StrUtil "https://github.com/stnuessl/rf/blob/master/src/util/string.hpp"
    click YAMLUtil "https://github.com/stnuessl/rf/blob/master/src/util/yaml.cpp"
    click YAMLUtil "https://github.com/stnuessl/rf/blob/master/src/util/yaml.hpp"
    click TestHarness "https://github.com/stnuessl/rf/tree/master/test/"
    click BashComp "https://github.com/stnuessl/rf/tree/master/bash-completion/rf"
    click FixJCDB "https://github.com/stnuessl/rf/blob/master/utils/fix-jcdb.py"
    click MakeJCDB "https://github.com/stnuessl/rf/blob/master/utils/make-jcdb.py"

    %% Styles
    classDef frontend fill:#D4EFDF,stroke:#27AE60;
    classDef core fill:#AED6F1,stroke:#3498DB;
    classDef ext fill:#F9E79F,stroke:#D4AC0D;
    classDef util fill:#D5DBDB,stroke:#7B7D7D;
    classDef db fill:#ABEBC6,stroke:#229954,shape:db;
```
