# workiva/dart_dev architecture

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

- Interactive diagram: https://gitdiagram.com/workiva/dart_dev
- Repository: https://github.com/workiva/dart_dev

## Overview

##### Project Type and Purpose
- This is a Dart‐based CLI library/toolkit (“dart_dev”) that provides a consistent, configurable interface for common Dart developer tasks (analyze, format, test, serve, etc.).
- It’s both a library (consumed by projects via a dev dependency) and an executable front‐end (bin/dart_dev.dart) that delegates to underlying Dart tools and any custom extensions.

##### File Structure Analysis
- **bin/dart_dev.dart** – entry point for the CLI.
- **lib/** – public API surface and core logic:
- lib/dart_dev.dart – exports and entry hooks
- lib/src/… – runner, tool abstractions, coreConfig, event definitions, utility modules, individual DevTool implementations under src/tools.
- **tool/dart_dev/config.dart** – project-level override/extension point for customizing or adding tools.
- **test/** – unit and functional tests organized by tool, utils, and end-to-end fixtures.
- **doc/** – design docs, tool guides, upgrade notes.
- **.github/**, CI/workflows – CI, publishing, dependency configuration.

##### README Insights
- Describes a `coreConfig` (built‐in Map<String,DevTool>) that defines default tasks.
- Projects can spread coreConfig and override or add targets via tool/dart_dev/config.dart.
- Each tool implements the same DevTool interface/abstract base.
- Internally, TestTool inspects pubspec.yaml, FormatTool invokes dart format or dart_style, AnalyzeTool invokes dart analyze, etc.

##### Main Components
a. **CLI Front-End**
- bin/dart_dev.dart → parses args, bootstraps DartDevRunner
b. **DartDevRunner (core)**
- Loads sharedConfig (coreConfig)
- Loads projectConfig (tool/dart_dev/config.dart) if present, merges overrides
- Matches the requested command to a DevTool instance
c. **DevTool Interface**
- Defines `run()` contract, shared lifecycle and event hooks
d. **Tool Implementations**
- AnalyzeTool, FormatTool, TestTool, WebdevServeTool, CompoundTool, ProcessTool, etc.
- Each encapsulates specific builder or process args
e. **Process Executor / Event Bus**
- Utility modules in lib/src/utils handle spawning subprocesses (dart, pub, build_runner), logging, exit handling
- Event streams (lib/events.dart) propagate status and results
f. **External Tools / Subprocesses**
- dart analyze, dart format/dart_style, dart test or build_runner test, webdev serve, custom ProcessTool commands
g. **Project Configuration**
- tool/dart_dev/config.dart defines overrides; pubspec.yaml used by some tools to detect dependencies (e.g., build_test)
h. **Tests**
- Functional: fixture-driven tests spin up the dart_dev CLI against sample projects
- Unit: isolated tests of tools and utils

##### Relationships and Data Flow
- **User** invokes `dart run dart_dev <command> [args]`
→ CLI Front-End calls DartDevRunner
→ Runner reads configs (core + project)
→ Runner selects a DevTool instance from the merged config Map
→ DevTool.run() publishes “start” event → ProcessExecutor spawns the underlying tool → publishes status/events → DevTool processes output → publishes “complete” event → Runner exits with code
- Tools can compose other tools (CompoundTool) or wrap external commands (ProcessTool).
- Configuration flows from project config → overrides coreConfig entries.

##### Architectural Patterns & Design Principles
- **Strategy/Plugin Pattern**: DevTool interface with interchangeable implementations
- **Composition over Inheritance**: Tools are composed via maps and spread operators, and CompoundTool can group multiple DevTools
- **Separation of Concerns**:
- CLI and argument parsing
- Tool selection & configuration
- Process execution & event dispatch
- Individual tool logic (analyze, format, test)
- **Convention over Configuration**: sensible defaults via coreConfig, overridden at project level only when needed

##### Detail Level
- Every tool as a sub-component under “DevTool Implementations.”
- Test suite as a separate module invoking the CLI for functional verification.
- Role of `pubspec.yaml` in TestTool logic (build_test detection).
- Extensibility point at tool/dart_dev/config.dart.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User invokes CLI
    User["User"]:::external
    User -->|"dart run dart_dev <command>"| CLI

    %% CLI Front-End
    CLI["CLI Front-End\nbin/dart_dev.dart"]:::internal
    click CLI "https://github.com/workiva/dart_dev/blob/master/bin/dart_dev.dart"

    %% Runner and Config
    CLI --> Runner
    Runner["DartDevRunner\nlib/src/dart_dev_runner.dart"]:::internal
    click Runner "https://github.com/workiva/dart_dev/blob/master/lib/src/dart_dev_runner.dart"

    subgraph "Configuration Merge"
        direction TB
        CoreConfig["coreConfig\nlib/src/core_config.dart"]:::internal
        click CoreConfig "https://github.com/workiva/dart_dev/blob/master/lib/src/core_config.dart"
        ProjectConfig["projectConfig\ntool/dart_dev/config.dart"]:::config
        click ProjectConfig "https://github.com/workiva/dart_dev/blob/master/tool/dart_dev/config.dart"
        MergedConfig["Merged Config\nMap<String,DevTool>"]:::plugin
    end

    Runner -->|"loads"| CoreConfig
    Runner -->|"loads if present"| ProjectConfig
    CoreConfig --> MergedConfig
    ProjectConfig --> MergedConfig
    Runner -->|"uses"| MergedConfig

    %% DevTool Interface and Executable Helpers
    DevToolIntf["DevTool Interface\nlib/src/dart_dev_tool.dart"]:::plugin
    click DevToolIntf "https://github.com/workiva/dart_dev/blob/master/lib/src/dart_dev_tool.dart"
    ExecHelpers["Executable Entry/Helpers\nlib/src/executable.dart"]:::internal
    click ExecHelpers "https://github.com/workiva/dart_dev/blob/master/lib/src/executable.dart"

    Runner --> DevToolIntf
    Runner --> ExecHelpers
    MergedConfig --> DevToolIntf

    %% Tool Implementations
    subgraph "DevTool Implementations" 
        direction TB
        Analyze["AnalyzeTool\nlib/src/tools/analyze_tool.dart"]:::plugin
        click Analyze "https://github.com/workiva/dart_dev/blob/master/lib/src/tools/analyze_tool.dart"
        Format["FormatTool\nlib/src/tools/format_tool.dart"]:::plugin
        click Format "https://github.com/workiva/dart_dev/blob/master/lib/src/tools/format_tool.dart"
        Test["TestTool\nlib/src/tools/test_tool.dart"]:::plugin
        click Test "https://github.com/workiva/dart_dev/blob/master/lib/src/tools/test_tool.dart"
        WebServe["WebdevServeTool\nlib/src/tools/webdev_serve_tool.dart"]:::plugin
        click WebServe "https://github.com/workiva/dart_dev/blob/master/lib/src/tools/webdev_serve_tool.dart"
        Compound["CompoundTool\nlib/src/tools/compound_tool.dart"]:::plugin
        click Compound "https://github.com/workiva/dart_dev/blob/master/lib/src/tools/compound_tool.dart"
        ProcessT["ProcessTool\nlib/src/tools/process_tool.dart"]:::plugin
        click ProcessT "https://github.com/workiva/dart_dev/blob/master/lib/src/tools/process_tool.dart"
        Clean["CleanTool\nlib/src/tools/clean_tool.dart"]:::plugin
        click Clean "https://github.com/workiva/dart_dev/blob/master/lib/src/tools/clean_tool.dart"
        FunctionT["FunctionTool\nlib/src/tools/function_tool.dart"]:::plugin
        click FunctionT "https://github.com/workiva/dart_dev/blob/master/lib/src/tools/function_tool.dart"
        Tuneup["TuneupCheckTool\nlib/src/tools/tuneup_check_tool.dart"]:::plugin
        click Tuneup "https://github.com/workiva/dart_dev/blob/master/lib/src/tools/tuneup_check_tool.dart"
        OverReact["OverReactFormatTool\nlib/src/tools/over_react_format_tool.dart"]:::plugin
        click OverReact "https://github.com/workiva/dart_dev/blob/master/lib/src/tools/over_react_format_tool.dart"
    end

    MergedConfig -->|"selects instance"| Analyze
    MergedConfig --> Format
    MergedConfig --> Test
    MergedConfig --> WebServe
    MergedConfig --> Compound
    MergedConfig --> ProcessT
    MergedConfig --> Clean
    MergedConfig --> FunctionT
    MergedConfig --> Tuneup
    MergedConfig --> OverReact

    %% Utilities & Event Bus
    subgraph "Utils & Event Bus"
        direction TB
        EventsPub["Public Events API\nlib/events.dart"]:::plugin
        click EventsPub "https://github.com/workiva/dart_dev/blob/master/lib/events.dart"
        EventsInt["Internal Event Streams\nlib/src/events.dart"]:::internal
        click EventsInt "https://github.com/workiva/dart_dev/blob/master/lib/src/events.dart"
        subgraph "Process Executor Utils"
            direction TB
            RP["run_process_and_ensure_exit\nlib/src/utils/run_process_and_ensure_exit.dart"]:::internal
            click RP "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/run_process_and_ensure_exit.dart"
            SP["start_process_and_ensure_exit\nlib/src/utils/start_process_and_ensure_exit.dart"]:::internal
            click SP "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/start_process_and_ensure_exit.dart"
            EP["ensure_process_exit\nlib/src/utils/ensure_process_exit.dart"]:::internal
            click EP "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/ensure_process_exit.dart"
            PD["process_declaration\nlib/src/utils/process_declaration.dart"]:::internal
            click PD "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/process_declaration.dart"
            EXE["executables\nlib/src/utils/executables.dart"]:::internal
            click EXE "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/executables.dart"
        end
        subgraph "Logging & Signals"
            LOG["logging\nlib/src/utils/logging.dart"]:::internal
            click LOG "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/logging.dart"
            SIG["exit_process_signals\nlib/src/utils/exit_process_signals.dart"]:::internal
            click SIG "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/exit_process_signals.dart"
        end
        subgraph "Arg Parsing Utils"
            ARGU["arg_results_utils\nlib/src/utils/arg_results_utils.dart"]:::internal
            click ARGU "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/arg_results_utils.dart"
            PARS["parse_flag_from_args\nlib/src/utils/parse_flag_from_args.dart"]:::internal
            click PARS "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/parse_flag_from_args.dart"
        end
        subgraph "Pubspec Utils"
            CACHED["cached_pubspec\nlib/src/utils/cached_pubspec.dart"]:::internal
            click CACHED "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/cached_pubspec.dart"
            LOCK["pubspec_lock\nlib/src/utils/pubspec_lock.dart"]:::internal
            click LOCK "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/pubspec_lock.dart"
            DEP["package_is_immediate_dependency\nlib/src/utils/package_is_immediate_dependency.dart"]:::internal
            click DEP "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/package_is_immediate_dependency.dart"
        end
        subgraph "Other Utils"
            SEMV["dart_semver_version\nlib/src/utils/dart_semver_version.dart"]:::internal
            click SEMV "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/dart_semver_version.dart"
            VER["version\nlib/src/utils/version.dart"]:::internal
            click VER "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/version.dart"
            PATHS["dart_dev_paths\nlib/src/utils/dart_dev_paths.dart"]:::internal
            click PATHS "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/dart_dev_paths.dart"
            CACHE["dart_tool_cache\nlib/src/utils/dart_tool_cache.dart"]:::internal
            click CACHE "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/dart_tool_cache.dart"
            GPA["global_package_is_active_and_compatible\nlib/src/utils/global_package_is_active_and_compatible.dart"]:::internal
            click GPA "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/global_package_is_active_and_compatible.dart"
            COMMENT["get_dart_version_comment\nlib/src/utils/get_dart_version_comment.dart"]:::internal
            click COMMENT "https://github.com/workiva/dart_dev/blob/master/lib/src/utils/get_dart_version_comment.dart"
        end
    end

    DevToolIntf --> EventsPub
    DevToolIntf --> EventsInt
    DevToolIntf --> RP
    DevToolIntf --> SP
    DevToolIntf --> PD

    subgraph "External Tools/Subprocesses"
        direction TB
        DartAnalyze["dart analyze"]:::external
        DartFormat["dart format / dart_style"]:::external
        DartTest["dart test / build_runner test"]:::external
        WebDevServe["webdev serve"]:::external
        CustomProc["custom ProcessTool commands"]:::external
    end

    Analyze -->|"spawns"| DartAnalyze
    Format -->|"spawns"| DartFormat
    Test -->|"spawns"| DartTest
    WebServe -->|"spawns"| WebDevServe
    ProcessT --> CustomProc

    %% pubspec.yaml
    Pubspec["pubspec.yaml"]:::config
    Test -->|"reads"| Pubspec
    CACHED --> Pubspec
    LOCK --> Pubspec
    DEP --> Pubspec

    %% Public API Surface
    subgraph "Public API Surface"
        LibExport["Library Exports & Hooks\nlib/dart_dev.dart"]:::internal
        click LibExport "https://github.com/workiva/dart_dev/blob/master/lib/dart_dev.dart"
        UtilsExp["Convenience Exports\nlib/utils.dart"]:::internal
        click UtilsExp "https://github.com/workiva/dart_dev/blob/master/lib/utils.dart"
    end
    LibExport --> DevToolIntf
    LibExport --> ExecHelpers

    %% Tests
    subgraph "Tests"
        direction TB
        Unit["Unit Tests\ntest/tools/*.dart"]:::external
        Func["Functional CLI Tests\ntest/functional"]:::external
        UtilsT["Utils Module Tests\ntest/utils/**/*.dart"]:::external
    end
    Unit --> Analyze
    Unit --> Format
    Unit --> Test
    Func --> CLI
    UtilsT --> RP
    UtilsT --> LOG

    classDef internal fill:#D0E8FF,stroke:#000
    classDef plugin fill:#D0FFD0,stroke:#000
    classDef external fill:#FFE0B2,stroke:#000
    classDef config fill:#E0E0E0,stroke:#000
```
