# voxpupuli/onceover architecture

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

- Interactive diagram: https://gitdiagram.com/voxpupuli/onceover
- Repository: https://github.com/voxpupuli/onceover

## Overview

##### MAIN COMPONENTS
- CLI Interface – Represented by the files inside the “bin” folder (e.g., bin/onceover) and the CLI-related Ruby modules in lib/onceover/cli (e.g., init.rb, run.rb, show.rb, update.rb). This component is the entry point for users invoking onceover commands.
- Core Engine / Control Repository Manager – This is implemented in files such as lib/onceover/controlrepo.rb and related classes in lib/onceover (like testconfig.rb, group.rb, and runner.rb). It reads configuration (onceover.yaml), parses the Puppet control repository structure, and determines what tests to generate.
- Factset Processor – Notice the “factsets” directory containing many JSON files of various operating systems. This module converts factset files into the data needed for compiling catalogs and for generating RSpec tests.
- Test Generation & Runner – The system auto-generates rspec-puppet tests and integrates with Beaker for acceptance testing. Components that support these tests reside in lib/onceover/rspec, features (with Cucumber tests), and the spec directory.
- R10k and Puppetfile Integration – The system uses r10k to clone modules referenced in the Puppetfile. This is indirectly triggered via the control repo and via specific rake tasks (generate_fixtures, generate_vendor_cache) and files like Puppetfile and environment.conf.
- Plugin System – Onceover auto-activates plugins (gems starting with “onceover-”), so include a plugin manager piece that loads these external components.
- Configuration Layer – There is extensive configuration via onceover.yaml (and other manifest/config files) and also support for hiera configuration (hiera.yaml and data directories). This defines which nodes, classes, and groups get tested.

- The CLI interface (user entry point) accepts commands (init, run, show, update) and passes them to the Control Repo Manager.
- The Control Repo Manager parses the onceover.yaml and Puppetfile, gathers factsets from the “factsets” directory, and discovers additional test specifications (from directories “features”, “spec”, “templates” and “pre_conditions”).
- During test execution, there is communication with the underlying Puppet compilation engine (via rspec-puppet), and optionally, modules may be auto-vendored using r10k integration.
- Plugins extend or modify the behavior of various stages (from test generation, to post-test analysis by tools like onceover-codequality or onceover-octocatalog-diff).

##### Architectural Patterns & Design Principles
- Modular design: Each directory (lib/onceover/cli, lib/onceover/controlrepo, lib/onceover/test, etc.) encapsulates a distinct responsibility.
- Separation of concerns: The CLI layer, the configuration parser, factset management, test generation, and external module management (via r10k) are kept in separate, well-defined modules.
- Extensibility via plugin architecture: The system automatically loads any gem starting with “onceover-“ which enables extension of the core functionalities without modifying the main codebase.

##### Relevant Technologies, Frameworks, & Libraries
- Ruby (Gemfile, Rakefile, .gemspec)
- rspec-puppet & Beaker – for testing Puppet code
- r10k – for managing and cloning Puppet modules from the Puppetfile
- Cucumber – seen in the “features” directory for acceptance testing scenarios
- YAML & JSON processing – for configuration (onceover.yaml) and factset files
- GitHub Actions and other CI/CD workflows (under .github/workflows) indicate continuous integration support

##### Additional Details
- That the “spec” and “features” folders represent the test suites – one for traditional unit tests and one for acceptance tests.
- That the “templates” folder feeds into the dynamic generation of configuration and helper files inside a temporary directory (e.g., .onceover)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Nodes - User Interaction
    U("User"):::user
    CLIExec("CLI Executable"):::cli
    CLIMod("CLI Modules"):::cli

    %% Nodes - Core Engine and Supporting Classes
    CRM("Control Repo Manager"):::engine
    TC("Test Configuration"):::engine
    GM("Group Manager"):::engine
    RUN("Runner"):::engine

    %% Nodes - Supporting Modules
    Config("Configuration Handler"):::config
    Fact("Factset Processor"):::processor
    Test("Test Generation & Runner"):::tester
    RSpec("RSpec Support"):::tester
    Accept("Acceptance Tests"):::tester
    Spec("Spec Tests"):::tester
    Module("Module Fetcher (r10k Integration)"):::integration
    Plugin("Plugin Loader"):::plugin
    Rake("Rake Tasks"):::automation

    %% Relationships - User to CLI
    U -->|"invokes"| CLIExec
    U -->|"invokes"| CLIMod

    %% Relationships - CLI to Core Engine
    CLIExec -->|"triggers"| CRM
    CLIMod -->|"triggers"| CRM

    %% Internal Core Engine breakdown
    CRM -->|"uses"| TC
    CRM -->|"uses"| GM
    CRM -->|"uses"| RUN

    %% Core Engine to Supporting Modules
    CRM -->|"parses_config"| Config
    CRM -->|"loads_factsets"| Fact
    CRM -->|"generates_tests"| Test
    CRM -->|"fetches_modules"| Module

    %% Test Generation breakdown
    Test -->|"supports"| RSpec
    Test -->|"includes"| Accept
    Test -->|"includes"| Spec

    %% Plugin integration
    Plugin -->|"modifies_workflow"| CRM
    Plugin -->|"extends_tests"| Test

    %% Rake tasks automation
    Rake -.->|"automates"| Module
    Rake -.->|"updates_fixtures"| Config

    %% Click Events
    click CLIExec "https://github.com/voxpupuli/onceover/tree/master/bin/onceover"
    click CLIMod "https://github.com/voxpupuli/onceover/tree/master/lib/onceover/cli"
    click CRM "https://github.com/voxpupuli/onceover/blob/master/lib/onceover/controlrepo.rb"
    click TC "https://github.com/voxpupuli/onceover/blob/master/lib/onceover/testconfig.rb"
    click GM "https://github.com/voxpupuli/onceover/blob/master/lib/onceover/group.rb"
    click RUN "https://github.com/voxpupuli/onceover/blob/master/lib/onceover/runner.rb"
    click Fact "https://github.com/voxpupuli/onceover/tree/master/factsets"
    click RSpec "https://github.com/voxpupuli/onceover/tree/master/lib/onceover/rspec"
    click Accept "https://github.com/voxpupuli/onceover/tree/master/features"
    click Spec "https://github.com/voxpupuli/onceover/tree/master/spec"
    click Module "https://github.com/voxpupuli/onceover/blob/master/lib/onceover/vendored_modules.rb"
    click Plugin "https://github.com/voxpupuli/onceover/blob/master/lib/onceover/cli/plugins.rb"
    click Config "https://github.com/voxpupuli/onceover/tree/master/templates"
    click Rake "https://github.com/voxpupuli/onceover/tree/master/Rakefile"

    %% Style Classes
    classDef user fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef cli fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef engine fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef config fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef processor fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef tester fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef integration fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef plugin fill:#D6EAF8,stroke:#5DADE2,stroke-width:2px;
    classDef automation fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
```
