# chuyeow/facon architecture

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

- Interactive diagram: https://gitdiagram.com/chuyeow/facon
- Repository: https://github.com/chuyeow/facon

## Overview

##### Project type and purpose
- This is an open-source Ruby library (a gem) that provides mocking and expectation functionality for Bacon and MacBacon test suites.
- It is not a web app or service; it’s a code library meant to be included in test code to generate mock objects, set expectations on method calls, and verify invocation counts.

##### File structure
- Top-level files:
- Gemfile, facon.gemspec – define gem dependencies and metadata
- Rakefile – build and test automation
- README.md, Changelog.txt – documentation
- lib/facon – contains the source code modules:
- core_ext (monkey-patch to Object)
- baconize (integration with Bacon)
- error_generator (building error messages)
- expectation (defining expectation objects)
- mock, mockable, proxy (creating and managing mock objects)
- spec – unit tests for each module (baconize_spec, expectation_spec, mock_spec, etc.)

##### Extract insights from the README
- Facon hooks into Bacon’s lifecycle to install its mocking behavior.
- It uses Ruby metaprogramming (method_missing, proxies) to intercept calls.
- Users write `mock('name', :attr => val)`, call `should.receive`, then invoke code under test; Facon verifies expectations.

##### Main components
a. Facon Library Modules
- CoreExt Module (opens Object to add `mock` method)
- Mockable Module (mix-in for classes/objects)
- Proxy Class (wraps real object or stub data)
- Expectation Class (records method, args, call count rules)
- ErrorGenerator (formats assertion failures)
- Baconize Adapter (registers Facon hooks with Bacon runner)
b. External Interfaces
- Test Code (user’s specs)
- Bacon / MacBacon Framework
- Ruby Runtime
c. Relationships / Data Flow
1. Test code calls `mock(…)` (via CoreExt).
2. CoreExt creates a Proxy instance, including Mockable.
3. Test code sets expectations on Proxy (calls Expectation APIs).
4. When code under test invokes a mocked method, Proxy delegates to Expectation to record/check calls, possibly returning stubbed values.
5. At the end of each spec, Baconize adapter triggers verification of all expectations.
6. On failure, ErrorGenerator builds descriptive error message and signals Bacon test failure.
d. Architectural patterns and design principles
- Proxy pattern – intercept calls to target objects
- Mixin/monkey-patch – extend Object dynamically
- Separation of concerns – expectation logic, error formatting, Bacon integration each in its own class/module
- Convention over configuration – simple API, default behaviors

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    TestCode["Test Code"]:::test
    BaconFramework["Bacon/MacBacon Framework"]:::external
    RubyRuntime["Ruby Runtime"]:::external

    %% Facon Library Core
    subgraph "Facon Library Core"
        CoreExt["CoreExt Module"]:::core
        Mockable["Mockable Module"]:::core
        Proxy["Proxy Class"]:::core
        Expectation["Expectation Class"]:::core
        ErrorGen["ErrorGenerator"]:::core
        FaconEntry["Facon Module (Entry Point)"]:::core
        Version["Version Metadata"]:::core
    end

    %% Adapter
    subgraph "Integration Adapter"
        Baconize["Baconize Adapter"]:::adapter
    end

    %% Relationships
    TestCode -->|"calls mock(...) via CoreExt"| CoreExt
    CoreExt -->|"creates Proxy instance"| Proxy
    Proxy -->|"includes Mockable mix-in"| Mockable
    TestCode -->|"calls should.receive on Proxy"| Expectation
    Proxy -->|"delegates method_missing to"| Expectation
    Expectation -->|"returns stubbed values to"| Proxy
    BaconFramework -->|"triggers verification"| Baconize
    Baconize -->|"calls verify on"| Expectation
    Expectation -->|"on failure invokes"| ErrorGen
    ErrorGen -->|"signals test failure to"| BaconFramework

    %% Ruby Runtime relation
    RubyRuntime -.supports.-> CoreExt
    RubyRuntime -.supports.-> Mockable
    RubyRuntime -.supports.-> Proxy
    RubyRuntime -.supports.-> Expectation
    RubyRuntime -.supports.-> ErrorGen
    RubyRuntime -.supports.-> Baconize

    %% Click Events
    click CoreExt "https://github.com/chuyeow/facon/blob/master/lib/facon/core_ext/object.rb"
    click Mockable "https://github.com/chuyeow/facon/blob/master/lib/facon/mockable.rb"
    click Proxy "https://github.com/chuyeow/facon/blob/master/lib/facon/proxy.rb"
    click Expectation "https://github.com/chuyeow/facon/blob/master/lib/facon/expectation.rb"
    click ErrorGen "https://github.com/chuyeow/facon/blob/master/lib/facon/error_generator.rb"
    click Baconize "https://github.com/chuyeow/facon/blob/master/lib/facon/baconize.rb"
    click FaconEntry "https://github.com/chuyeow/facon/blob/master/lib/facon.rb"
    click Version "https://github.com/chuyeow/facon/blob/master/lib/facon/version.rb"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef adapter fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px
    classDef test fill:#eceff1,stroke:#607d8b,stroke-width:1px
```
