# deepsourcecorp/globstar architecture

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

- Interactive diagram: https://gitdiagram.com/deepsourcecorp/globstar
- Repository: https://github.com/deepsourcecorp/globstar

## Overview

##### Project type and purpose
- Globstar is an open-source, CLI-driven static analysis toolkit (written in Go) that bundles a set of built-in and user-defined checkers (YAML or Go) to run AST-based code inspections via tree-sitter.

##### Main components
a. CLI Layer
- `pkg/cli` – parses commands (`globstar check`), handles flags, version, and invokes the test runner.
- `cmd/*` – entry points for helper binaries (e.g., `genregistry`, `globstar` alias).
b. Configuration & Registry
- `pkg/config` – loads global and repository-level settings (`.globstar` directory).
- `cmd/genregistry` & `pkg/analysis/pattern_rule.go` – discover and register built-in Go and YAML checkers.
c. Core Analysis Engine
- `pkg/analysis` + `analysis/` folder – tree-sitter integration, AST walker, multi-file scope resolution, matcher engine.
- Language modules – per‐language hooks (e.g., `analysis/ts_scope.go`, `checkers/javascript/js_dataflow.go`, etc.).
d. Checker Definitions
- YAML checkers (in `checkers/*/*.yml`) – simple S-expression queries.
- Go checkers (in `checkers/*/*.go`) – advanced logic using the analysis API.
e. Test Runner & Output
- `pkg/cli/test_runner.go` & `analysis/testrunner.go` – feed file list into the engine, aggregate results, format output (console, JSON).
f. External & Packaging
- Tree-sitter parsers (third-party library) – for AST generation.
- Single-binary packaging via Go modules, goreleaser for distribution.

##### Relationships & Data Flow
- User runs `globstar check` → CLI parses flags → Config loader finds `.globstar` + built-in checkers → Registry builder aggregates checker metadata → Test runner walks the file system → Core engine uses tree-sitter to parse each source file → Applies each checker (YAML pattern or Go function) → Collects and formats findings → Outputs to stdout/CI.

##### Architectural Patterns & Design Principles
- Plugin/registry pattern for checkers (discovering via file conventions).
- Layered architecture: CLI → Config → Registry → Analysis Engine → Checkers → Output.
- Dependency injection of AST and scope into checker implementations.
- Single-binary design to simplify CI integration.

##### Final Checklist
- [ ] Rectangles for each major component with package/file labels.
- [ ] Clear distinction between built-in and user-provided checkers.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: User & CLI
    subgraph "User & CLI Layer"
        direction TB
        User["User"]:::external
        CLI["pkg/cli"]:::cli
        CMD1["cmd/globstar"]:::cli
        CMD2["cmd/genregistry"]:::cli
    end

    %% Layer 2: Config & Registry
    subgraph "Config & Registry Layer"
        direction TB
        Config["pkg/config"]:::config
        Pattern["pkg/analysis/pattern_rule.go"]:::registry
        GenReg["cmd/genregistry/main.go"]:::registry
    end

    %% Layer 3: Core Analysis Engine
    subgraph "Core Analysis Engine Layer"
        direction TB
        EnginePublic["pkg/analysis"]:::engine
        EngineCore["analysis"]:::engine
        TreeSitter["Tree-sitter Parsers"]:::external
    end

    %% Layer 4: Checkers Plugins
    subgraph "Checkers Plugins Layer"
        direction TB
        Discover["checkers/discover"]:::checkers
        YAML["YAML Checkers"]:::checkers
        GoChk["Go Checkers"]:::checkers
    end

    %% Layer 5: Test Runner & Output
    subgraph "Test Runner & Output Layer"
        direction TB
        TestRunnerCLI["pkg/cli/test_runner.go"]:::output
        TestRunnerCore["analysis/testrunner.go"]:::output
        Output["Results (Console/JSON)"]:::output
    end

    %% External & Packaging
    subgraph "External & Packaging"
        direction TB
        GoMod["go.mod/go.sum"]:::external
        Goreleaser["goreleaser.yaml"]:::external
    end

    %% Connections & Data Flow
    User -->|"runs `globstar check`"| CLI
    CLI -->|"invokes"| CMD1
    CLI -->|"invokes"| TestRunnerCLI
    CLI -->|"loads flags"| Config
    Config -->|"loads `.globstar`"| Discover
    CMD2 -->|"generates registry"| Pattern
    Pattern -->|"registers built-ins"| Discover
    Discover -->|"checker list"| EngineCore
    TestRunnerCLI -->|"file list"| EngineCore
    EngineCore -->|"AST"| EnginePublic
    TreeSitter -->|"parses code"| EngineCore
    EnginePublic -->|"injects scope"| GoChk
    EnginePublic -->|"injects scope"| YAML
    GoChk -->|"reports findings"| TestRunnerCore
    YAML -->|"reports findings"| TestRunnerCore
    TestRunnerCore -->|"aggregates results"| Output
    Output -->|"outputs"| User

    %% Click Events
    click CLI "https://github.com/deepsourcecorp/globstar/tree/master/pkg/cli"
    click CMD1 "https://github.com/deepsourcecorp/globstar/blob/master/cmd/globstar/main.go"
    click CMD2 "https://github.com/deepsourcecorp/globstar/blob/master/cmd/genregistry/main.go"
    click Config "https://github.com/deepsourcecorp/globstar/blob/master/pkg/config/config.go"
    click Pattern "https://github.com/deepsourcecorp/globstar/blob/master/pkg/analysis/pattern_rule.go"
    click EnginePublic "https://github.com/deepsourcecorp/globstar/tree/master/pkg/analysis"
    click EngineCore "https://github.com/deepsourcecorp/globstar/tree/master/analysis"
    click Discover "https://github.com/deepsourcecorp/globstar/tree/master/checkers/discover"
    click TestRunnerCLI "https://github.com/deepsourcecorp/globstar/blob/master/pkg/cli/test_runner.go"
    click TestRunnerCore "https://github.com/deepsourcecorp/globstar/blob/master/analysis/testrunner.go"
    click GoMod "https://github.com/deepsourcecorp/globstar/blob/master/go.mod"
    click Goreleaser "https://github.com/deepsourcecorp/globstar/blob/master/goreleaser.yaml"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef config fill:#AFEEEE,stroke:#333,stroke-width:1px
    classDef registry fill:#98FB98,stroke:#333,stroke-width:1px
    classDef engine fill:#90EE90,stroke:#333,stroke-width:1px
    classDef checkers fill:#FFA500,stroke:#333,stroke-width:1px
    classDef output fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
