# twostraws/sitrep architecture

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

- Interactive diagram: https://gitdiagram.com/twostraws/sitrep
- Repository: https://github.com/twostraws/sitrep

## Overview

This project is a Swift command line tool and library called “Sitrep” that analyzes Swift codebases. Its primary purpose is to scan a given Swift project, gathering statistics such as counts of classes, structs, methods, and other code metrics, and then reporting these findings in a user-friendly format. It functions both as a stand-alone CLI tool (via the “Sitrep” executable) and as an importable library (SitrepCore) for integration in other Swift projects.

##### Main Components
- Command Line Interface (CLI) Frontend:
- Represented by the files in Sources/Sitrep (e.g., Command.swift and main.swift).
- It handles parsing the command line flags (-c, -f, -p, -i, etc.), reading configurations (.sitrep.yml), and invoking the analysis.
- Core Analysis Engine (Library):
- Corresponds to the SitrepCore module in Sources/SitrepCore.
- This module contains the logic for parsing Swift code (via SwiftSyntax), scanning files (FileVisitor.swift), and computing various metrics (e.g., Report.swift, Scan.swift, Function.swift, Comment.swift, etc.).
- Test Suite:
- Located in the Tests directory. Even though tests are not part of runtime architecture, you may note the existence of comprehensive tests (e.g., SitrepCoreTests and SitrepTests) that ensure accuracy.
- External Dependencies:
- SwiftSyntax is a crucial dependency for parsing Swift code.
- Other auxiliary tools or scripts (like makefile and configuration files) that assist with builds and deployments.
- Configuration Management:
- The .sitrep.yml file (when provided) configures exclusions and scan behavior.
- This should be depicted as an input to the CLI, which then passes the configuration to SitrepCore.

##### Relationships and Data Flow
- The CLI component reads user input (command line flags) and configuration files.
- The SitrepCore module recursively scans the provided directory, reading files and parsing code using SwiftSyntax.
- The analysis results are then encapsulated into structures (e.g., Report, Results) and formatted as either text or JSON before being output to the terminal.
- Data/input flows (command line arguments, configuration file path) feeding into the CLI.
- A control flow from the CLI to the library (SitrepCore) for scanning.
- Return paths from the library back to the CLI for reporting the analysis.

##### Architectural Patterns & Design Principles
- Separation of Concerns:
- The clear division between the CLI (user interface) and the analysis engine (business logic) is central. This separation allows Sitrep to be both a standalone tool and an importable library.
- Modular Design:
- By having a distinct SitrepCore module, the project allows for easy unit testing and reuse within other applications.
- Configurability:
- The use of the .sitrep.yml file demonstrates an emphasis on customization and external configuration.
- Extensibility:
- The design anticipates future expansion of data reporting (such as additional metrics like cyclomatic complexity).

- “CLI Frontend” (Sources/Sitrep: main.swift, Command.swift).
- “Processing Engine” or “Analysis Core” (Sources/SitrepCore).
- “File System Scanner & Visitor” (e.g., FileVisitor.swift, Scan.swift).
- “Reporting” (e.g., Report.swift, Results.swift).
- “Configuration Parser” (Configuration.swift and the .sitrep.yml file).
- “External Library: SwiftSyntax” for code parsing.
- How user inputs and configurations flow into CLI.
- How the CLI calls into the core analysis engine.
- Use another for processing logic (SitrepCore).
- Data flow:

## Diagram (Mermaid)

```mermaid
flowchart TB

    %% CLI Frontend
    subgraph "CLI Frontend"
        CLI_Command["Command.swift"]:::cli
        CLI_Main["main.swift"]:::cli
    end

    %% SitrepCore Library
    subgraph "SitrepCore Library"
        SC_FileVisitor["FileVisitor.swift"]:::core
        SC_Scan["Scan.swift"]:::core
        SC_Report["Report.swift"]:::core
        SC_Function["Function.swift"]:::core
        SC_Comment["Comment.swift"]:::core
        SC_Results["Results.swift"]:::core
    end

    %% Configuration Management
    subgraph "Configuration Management"
        Config_YML[".sitrep.yml"]:::config
        Config_Parser["Configuration.swift"]:::config
    end

    %% Test Suite
    subgraph "Test Suite"
        Test_Core["SitrepCoreTests"]:::test
        Test_Sitrep["SitrepTests"]:::test
    end

    %% Build/Deployment Scripts
    subgraph "Build/Deployment"
        Makefile["makefile"]:::build
    end

    %% External Dependencies
    subgraph "External Dependencies"
        SwiftSyntax["SwiftSyntax"]:::external
    end

    %% Relationships
    %% Configuration flows into CLI Frontend
    Config_YML -->|"reads config"| CLI_Command
    Config_Parser -->|"parses config"| CLI_Main

    %% CLI Frontend invokes analysis in SitrepCore Library
    CLI_Main -->|"invokesAnalysis"| SC_FileVisitor

    %% Core scanning process flow (internal interactions)
    SC_FileVisitor -->|"traversesFiles"| SC_Scan
    SC_Scan -->|"computesMetrics"| SC_Report
    SC_Report -->|"generatesReport"| CLI_Main
    SC_Report -->|"includesData"| SC_Function
    SC_Report -->|"includesData"| SC_Comment
    SC_Report -->|"includesData"| SC_Results

    %% External dependency used by core engine for parsing
    SwiftSyntax -->|"parsesCode"| SC_FileVisitor

    %% Build process triggering CLI executable build
    Makefile -->|"buildsTool"| CLI_Main

    %% Test Suite verifying components
    Test_Core ---|"verifies"| SC_Report
    Test_Sitrep ---|"verifies"| CLI_Command

    %% Click Events for CLI Frontend
    click CLI_Command "https://github.com/twostraws/sitrep/blob/main/Sources/Sitrep/Command.swift"
    click CLI_Main "https://github.com/twostraws/sitrep/blob/main/Sources/Sitrep/main.swift"

    %% Click Events for SitrepCore Library
    click SC_FileVisitor "https://github.com/twostraws/sitrep/blob/main/Sources/SitrepCore/FileVisitor.swift"
    click SC_Scan "https://github.com/twostraws/sitrep/blob/main/Sources/SitrepCore/Scan.swift"
    click SC_Report "https://github.com/twostraws/sitrep/blob/main/Sources/SitrepCore/Report.swift"
    click SC_Function "https://github.com/twostraws/sitrep/blob/main/Sources/SitrepCore/Function.swift"
    click SC_Comment "https://github.com/twostraws/sitrep/blob/main/Sources/SitrepCore/Comment.swift"
    click SC_Results "https://github.com/twostraws/sitrep/blob/main/Sources/SitrepCore/Results.swift"

    %% Click Events for Configuration Management
    click Config_YML "https://github.com/twostraws/sitrep/blob/main/.sitrep.yml"
    click Config_Parser "https://github.com/twostraws/sitrep/blob/main/Sources/SitrepCore/Configuration.swift"

    %% Click Events for Test Suite
    click Test_Core "https://github.com/twostraws/sitrep/tree/main/Tests/SitrepCoreTests"
    click Test_Sitrep "https://github.com/twostraws/sitrep/tree/main/Tests/SitrepTests"

    %% Click Event for Build/Deployment Scripts
    click Makefile "https://github.com/twostraws/sitrep/tree/main/makefile"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef test fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef build fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
