# mgrafl/shellspec-ext-invocation architecture

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

- Interactive diagram: https://gitdiagram.com/mgrafl/shellspec-ext-invocation
- Repository: https://github.com/mgrafl/shellspec-ext-invocation

## Overview

##### Project type and purpose
- This is an open‐source ShellSpec extension, implemented in Bash, that provides a “capture_invocation” feature for mocking and verifying command/function invocations in ShellSpec test suites.
- It is not a full‐stack application but a plugin/library for ShellSpec with both unit tests and integration tests (including a Docker‐based test harness).

##### File structure
- lib/extension/invocation/… : the core extension code (capture_invocation function, helper scripts, matcher definitions).
- shellspec-ext-invocation : wrapper CLI script that sets up ShellSpec with the extension.
- spec/… and integration/spec/… : Bash test cases (unit and integration).
- Dockerfile & GitHub workflows: build/test pipelines and Docker images.
- CONFIG & CI files (.shellspec, Dockerfile, .github/workflows) : define test runners and Docker image publication.

##### README for architecture insights
- The extension consists of:
- capture_invocation function (stores command name + args)
- ShellSpec subjects (“number of mocks”, “mock”/“invocation”)
- ShellSpec matcher (“have received arguments”)
- Usage sections show how the extension is loaded into the ShellSpec CLI, and how tests invoke it under Docker.

##### Main components
A. ShellSpec CLI (the test runner core)
B. Extension Loader (shellspec-ext-invocation wrapper or --load-path flag)
C. capture_invocation module (Bash functions under lib/extension/invocation)
D. invocation helper scripts (capture_invocation_helper.sh, have_received_arguments.sh, etc.)
E. Test Suites
- Unit tests (spec/)
- Integration tests (integration/spec/)
F. Docker Image
- mgrafl/shellspec-ext-invocation (standard + “docker” variant with Docker-in-Docker)
G. CI/CD Pipeline (GitHub Actions workflows)

##### Relationships and data flows
1. Developer writes tests in spec/ or integration/spec/ that call ShellSpec with the extension loaded.
2. shellspec-ext-invocation (or shellspec CLI with --load-path) loads the capture_invocation scripts.
3. When tests run, `capture_invocation` intercepts mocked commands/functions and logs their names + args into an internal array/state.
4. Test matchers (`number of mocks`, `have received arguments`) query that stored state to pass/fail assertions.
5. Docker image provides a reproducible environment: it bundles shellspec core + extension code + helper scripts.
6. GitHub Actions orchestrates building the Docker image, running unit tests, and publishing the Docker image.

##### Architectural patterns and design principles
- Plugin architecture: the extension attaches to ShellSpec via a load path, registering new subjects and matchers.
- Separation of concerns:
- Core extension logic (capture_invocation functions)
- Test definitions (spec files)
- Packaging and CI/CD (Dockerfile, workflows)
- Unix philosophy: small shell scripts each doing one thing, composed via load paths and standard ShellSpec hooks.

b. Inside it, nest a “Load Extension” element that imports lib/extension/invocation/*.sh.
c. Capture_invocation functions writing to an “Invocation Store” (in-memory Bash array).
d. Matcher functions reading from the “Invocation Store.”
f. Below, place “Docker Image” as the runtime container that houses ShellSpec + extension.
g. Above, show “CI/CD (GitHub Actions)” orchestrating the Docker build and test runs.

##### Essential elements
- Clear component labels (CLI, Extension, Tests, Docker, CI/CD)
- Annotations of key scripts or file groups

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CI/CD (GitHub Actions)"
        CI_Test["Test Workflow"]:::cicd
        CI_DockerPub["Docker Publish Workflow"]:::cicd
    end

    subgraph "Test Suites" 
        UnitTests["Unit Tests\n(spec/capture_invocation_spec.sh\nspec/capture_invocation_spec-failing-examples.sh)"]:::tests
        IntegrationTests["Integration Tests\n(integration/spec/integration_docker_spec.sh)"]:::tests
    end

    subgraph "ShellSpec Test Runner" 
        ShellSpecCLI["ShellSpec CLI\n(shellspec-ext-invocation)"]:::core
        ExtensionLoader["Extension Loader\n(shellspec-ext-invocation)"]:::ext
        CaptureInvocation["capture_invocation Module"]:::ext
        InvocationStore["Invocation State Store"]:::store
        MatcherArgs["have_received_arguments Matcher"]:::matcher
        MatcherCount["invocations_count Matcher"]:::matcher

        ShellSpecCLI -->|"load extension"| ExtensionLoader
        ExtensionLoader -->|"loads scripts"| CaptureInvocation
        CaptureInvocation -->|"record invocation"| InvocationStore
        MatcherArgs -->|"read store"| InvocationStore
        MatcherCount -->|"read store"| InvocationStore
    end

    subgraph "Docker Environment"
        DockerImage["Docker Image\n(Dockerfile)"]:::infra
    end

    CI_Test -->|"orchestrates build & tests"| DockerImage
    CI_DockerPub -->|"publish image"| DockerImage
    DockerImage -->|"runs tests"| ShellSpecCLI
    UnitTests -->|"invoke tests"| ShellSpecCLI
    IntegrationTests -->|"invoke tests"| ShellSpecCLI

    click ShellSpecCLI "https://github.com/mgrafl/shellspec-ext-invocation/tree/main/shellspec-ext-invocation"
    click ExtensionLoader "https://github.com/mgrafl/shellspec-ext-invocation/tree/main/shellspec-ext-invocation"
    click CaptureInvocation "https://github.com/mgrafl/shellspec-ext-invocation/blob/main/lib/extension/invocation/capture_invocation_helper.sh"
    click InvocationStore "https://github.com/mgrafl/shellspec-ext-invocation/blob/main/lib/extension/invocation/support/invocation.sh"
    click MatcherArgs "https://github.com/mgrafl/shellspec-ext-invocation/blob/main/lib/extension/invocation/support/have_received_arguments.sh"
    click MatcherCount "https://github.com/mgrafl/shellspec-ext-invocation/blob/main/lib/extension/invocation/support/invocations_count.sh"
    click UnitTests "https://github.com/mgrafl/shellspec-ext-invocation/blob/main/spec/capture_invocation_spec.sh"
    click IntegrationTests "https://github.com/mgrafl/shellspec-ext-invocation/blob/main/integration/spec/integration_docker_spec.sh"
    click DockerImage "https://github.com/mgrafl/shellspec-ext-invocation/tree/main/Dockerfile"
    click CI_Test "https://github.com/mgrafl/shellspec-ext-invocation/blob/main/.github/workflows/test.yml"
    click CI_DockerPub "https://github.com/mgrafl/shellspec-ext-invocation/blob/main/.github/workflows/docker-publish.yml"

    classDef core fill:#aaccff,stroke:#000,stroke-width:1px
    classDef ext fill:#aaffaa,stroke:#000,stroke-width:1px
    classDef tests fill:#ffd599,stroke:#000,stroke-width:1px
    classDef infra fill:#cccccc,stroke:#000,stroke-width:1px
    classDef cicd fill:#e0bbff,stroke:#000,stroke-width:1px
    classDef store fill:#ccffcc,stroke:#000,stroke-width:1px
    classDef matcher fill:#ffffaa,stroke:#000,stroke-width:1px
```
