# jonlundberg/loadwhat architecture

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

- Interactive diagram: https://gitdiagram.com/jonlundberg/loadwhat
- Repository: https://github.com/jonlundberg/loadwhat

## Overview

This is a **single-binary Rust CLI tool for Windows x64** that diagnoses **DLL loading failures** by:
- **Running a target EXE under Win32 debugging APIs** (live diagnosis), optionally enabling **loader-snaps** to infer handled `LoadLibrary*` failures from debug strings.
- **Parsing PE imports offline** (static analysis) and doing a **recursive missing-dependency walk** (transitive missing detection).

##### File tree reading: map directories/files to architectural components
Top-level signals:
- `src/` = core product code (Rust CLI).
- `tests/fixtures/msvc/` = C++/MSVC-built executables/DLLs used to reproduce loader scenarios.
- `tests/harness/` = custom Rust harness to run the CLI against fixtures and assert token output.
- `xtask/` = dev tooling (build/test orchestration tasks).

- `src/main.rs` — entrypoint wiring
- `src/cli.rs` — argument parsing, subcommands (`run`, `imports`), flags (`--trace`, `--loader-snaps`, etc.)
- `src/debug_run.rs` — live “run under debugger” logic; phase/timeline tokens
- `src/win.rs` — Win32 API bindings/wrappers + OS/version/build detection utilities
- `src/loader_snaps.rs` — loader-snaps enabling + heuristics to infer dynamic load failures from debug strings
- `src/pe.rs` — PE parsing for imports (static analysis)
- `src/search.rs` — DLL search-order/path tracing and related tokens (`SEARCH_ORDER`, `SEARCH_PATH`)
- `src/emit.rs` — tokenized line emitter (`TOKEN key=value ...`) for summary/trace/verbose modes

##### README-derived architecture/behavior you must capture
From the README/spec:
- Two primary commands:
- `loadwhat run <exe>`: live run with debugging; emits summary or trace; **Phase B** does direct import diagnosis and a **recursive missing walk** (always on).
- `loadwhat imports <exe_or_dll>`: offline scan; includes recursive missing-dependency walk.
- Loader-snaps:
- Best-effort enabling via `PEB->NtGlobalFlag` with x64 offset chosen based on OS build detection.
- Heuristic selection rules when multiple candidates appear.

##### User/Inputs
- User invokes `loadwhat` with args
- Inputs: target EXE/DLL path, optional `--cwd`, `--timeout-ms`, flags (`--trace`, `-v`, `--loader-snaps`), target args after `--`

##### CLI/Orchestration Layer
- `main.rs` (entry)
- `cli.rs` (subcommand routing + option normalization, e.g., `--verbose` implies `--trace`)

##### Diagnosis Engines (core)
- **Live Debug Runner** (`debug_run.rs`)
- interacts with **Win32 Debug APIs** (`win.rs`)
- optionally uses **Loader-snaps Inference** (`loader_snaps.rs`)
- produces events: module load, debug strings, first break, exit status
- **PE Import Scanner** (`pe.rs`)
- reads PE structures/import tables from disk
- feeds into missing-dependency recursion

**Search Analysis** (`search.rs`) as a supporting component used by both engines to:
- “how the loader searched” (search order, expanded paths)
- enrich missing diagnosis with context

##### Output/Contract Layer
- **Token Emitter** (`emit.rs`)
- formats and prints `TOKEN key=value ...`
- supports modes: summary vs trace vs verbose
- emits families: `STATIC_*`, `DYNAMIC_MISSING`, `SEARCH_*`, `RUN_*`, `SUMMARY`, etc.

##### “Windows OS subsystems” explicitly as external dependencies
- Windows Loader (LoadLibrary behavior, search order)
- Win32 Debugging APIs (DebugActiveProcess / WaitForDebugEvent / output debug strings / module load notifications)
- PEB/NtGlobalFlag (for loader-snaps enabling)
- Filesystem (reading EXE/DLLs, current working directory)
This is a major accuracy driver: the “system” is essentially “loadwhat + Windows internals”.

##### `cli.rs` → `debug_run.rs` (RunConfig: exe path, cwd, timeout, mode flags)
3. `debug_run.rs` ↔ `win.rs` (debug session + OS build detection; process creation/attach; event loop)
4. (optional) `debug_run.rs` → `loader_snaps.rs` → `win.rs` (enable loader-snaps via PEB flag)
5. `win.rs` → `debug_run.rs` (events: module load, debug strings, exceptions/first break, exit)
6. `debug_run.rs` → `pe.rs` (Phase B: direct import diagnosis for main module and/or observed modules)
##### `emit.rs` → stdout (greppable lines)

- If `--loader-snaps` enabled: parse debug strings → infer candidates → apply selection rules → emit `DYNAMIC_MISSING`
- If mode is summary: emit one-line diagnosis (`STATIC_MISSING`/`STATIC_BAD_IMAGE`/`DYNAMIC_MISSING`/`SUCCESS`)
- If trace/verbose: emit expanded tokens (SEARCH_*, RUN_*, counters in SUMMARY)

##### `pe.rs` ↔ filesystem (read PE)
4. `pe.rs` → `search.rs` (resolve candidates, emit `SEARCH_ORDER/PATH` if in trace-like mode—if supported)
5. `pe.rs` → recursion walker (likely in `pe.rs` or a helper) → emits `STATIC_MISSING` with `via=... depth=...`

##### Architectural patterns to explicitly label
- **Pipeline / staged diagnosis**:
- Stage A: runtime debug event capture
- Stage B: static import + recursive missing walk (always on for `run`)
- **Separation of concerns**:
- OS bindings (`win.rs`)
- domain heuristics (`loader_snaps.rs`, `search.rs`)
- parsing (`pe.rs`)
- presentation/contract (`emit.rs`)
- **Contract-first output**: tokens are the interface; tests assert them.

##### Tech/framework/library callouts (only the significant ones)
- Rust CLI binary (Cargo)
- Windows x64 only
- Win32 Debug APIs + PEB/NtGlobalFlag manipulation
- PE (Portable Executable) parsing

##### Diagramming conventions to use (make it unambiguous)
Include:
- **Clear labels**: use module names (e.g., `debug_run.rs`) and responsibility (e.g., “Debug event loop”)
- Rectangles for internal modules

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Layer 1: User / Inputs
  %% =========================
  subgraph "User / Inputs"
    U["User / Scripts"]:::external
    IN_ARGS["CLI args\nrun|imports + flags\n(--trace, -v, --loader-snaps,\n--cwd, --timeout-ms, target args after --)"]:::external
    TARGET["Target EXE/DLL path"]:::external
  end

  %% =========================
  %% Layer 2: CLI / Orchestration
  %% =========================
  subgraph "CLI / Orchestration (loadwhat.exe)"
    MAIN["main.rs\nEntrypoint wiring"]:::core
    CLI["cli.rs\nArg parsing + subcommand routing\nFlag normalization (e.g., verbose⇒trace)"]:::core

    DEC_CMD{"Command?"}:::decision
    CMD_RUN["run\nLive diagnosis pipeline"]:::core
    CMD_IMPORTS["imports\nOffline static scan"]:::core
  end

  %% =========================
  %% Layer 3: Diagnosis Engines
  %% =========================
  subgraph "Diagnosis Engines (Core)"
    DR["debug_run.rs\nLive debug runner\nStage A: Debug event capture\nStage B: Static imports + recursive missing walk (always)"]:::engine
    WIN["win.rs\nWin32 API wrappers\nOS/version/build detection"]:::osglue
    LS["loader_snaps.rs\nOptional: enable loader-snaps\nInfer handled LoadLibrary* failures\nfrom debug strings + selection rules"]:::engine
    PE["pe.rs\nPE import scanner\nRecursive missing-dependency walk"]:::engine
    SEARCH["search.rs\nDLL search-order/path reasoning\nEmits SEARCH_ORDER / SEARCH_PATH context"]:::engine

    DEC_LS{"--loader-snaps?"}:::decision
    DEC_MODE{"Output mode?"}:::decision
    MODE_SUM["Summary"]:::core
    MODE_TRACE["Trace / Verbose"]:::core
  end

  %% =========================
  %% Layer 4: Output / Contract
  %% =========================
  subgraph "Output / Contract Layer"
    EMIT["emit.rs\nTokenized emitter\nPrints: TOKEN key=value ...\n(summary|trace|verbose)"]:::output
    STDOUT["stdout\nGreppable token lines"]:::external

    SPEC["docs/*.md\nBehavior/contract:\nToken semantics + selection rules"]:::spec
  end

  %% =========================
  %% External: Windows subsystems
  %% =========================
  subgraph "Windows OS Subsystems (External Dependencies)"
    FS["Filesystem\nRead EXE/DLLs, cwd, path resolution"]:::external
    DBG["Win32 Debug APIs\n(Create/Attach, WaitForDebugEvent,\nmodule load events, debug strings)"]:::external
    LOADER["Windows Loader\nDLL search order + LoadLibrary behavior"]:::external
    PEB["PEB / NtGlobalFlag\n(loader-snaps flag)"]:::external
  end

  %% =========================
  %% Testing / CI (optional view)
  %% =========================
  subgraph "Test / Engineering System"
    XTASK["xtask/\nDev task orchestration\n(build fixtures, run tests)"]:::dev
    HARNESS["tests/harness/\nCustom runner + assertions\n(exec CLI, parse tokens)"]:::test
    INTEG["tests/integration/\nContract/scenario coverage"]:::test
    FIX["tests/fixtures/msvc/\nMSVC-built EXEs/DLLs\nReal loader failure scenarios"]:::test
    CI[".github/workflows/ci.yml\nWindows CI runner automation"]:::dev
  end

  %% =========================
  %% Primary flows
  %% =========================
  U --> IN_ARGS --> MAIN --> CLI --> DEC_CMD
  TARGET --> CLI

  DEC_CMD -->|"run"| CMD_RUN --> DR
  DEC_CMD -->|"imports"| CMD_IMPORTS --> PE

  %% run pipeline (Stage A)
  DR <-->|"debugsession+events"| WIN
  WIN -->|"calls"| DBG
  DBG -->|"moduleload+dbgstrings+breaks+exit"| WIN --> DR

  %% optional loader-snaps
  DR --> DEC_LS
  DEC_LS -->|"yes"| LS
  LS -.->|"besteffortenable"| WIN
  WIN -.->|"writeflag"| PEB
  LS -->|"heuristics:parse dbg strings\nselect candidates"| DR

  %% Stage B always for run: static imports + recursive missing walk
  DR -->|"StageB:imports+missingwalk"| PE
  PE -->|"searchreasoning"| SEARCH

  %% offline imports flow
  PE <-->|"read PE on disk"| FS
  PE -->|"context"| SEARCH

  %% search interacts with OS semantics + filesystem
  SEARCH -->|"models"| LOADER
  SEARCH -->|"probespaths"| FS

  %% outputs (contract-first)
  DR -->|"tokens:RUN_*,SUMMARY,DYNAMIC_MISSING"| EMIT
  LS -->|"tokens:DYNAMIC_MISSING (inferred)"| EMIT
  PE -->|"tokens:STATIC_* (missing/badimage)\nvia/depth recursion"| EMIT
  SEARCH -->|"tokens:SEARCH_ORDER,SEARCH_PATH"| EMIT
  EMIT --> STDOUT

  %% mode decision influences verbosity
  CLI --> DEC_MODE
  DEC_MODE -->|"summary"| MODE_SUM --> EMIT
  DEC_MODE -->|"trace/verbose"| MODE_TRACE --> EMIT

  %% spec informs behavior
  SPEC -.->|"defines token semantics\nselection rules"| CLI
  SPEC -.->|"defines stage outputs"| DR
  SPEC -.->|"defines selection rules"| LS
  SPEC -.->|"defines static walk tokens"| PE
  SPEC -.->|"defines output contract"| EMIT

  %% =========================
  %% Testing / CI connections
  %% =========================
  INTEG -->|"uses"| HARNESS
  HARNESS -->|"executes"| MAIN
  HARNESS -->|"runs against"| FIX
  XTASK -->|"orchestrates"| FIX
  XTASK -->|"runs"| INTEG
  CI -->|"runs on Windows"| INTEG
  CI -->|"runs"| XTASK

  %% =========================
  %% Click events (component mapping)
  %% =========================
  click MAIN "https://github.com/jonlundberg/loadwhat/blob/main/src/main.rs"
  click CLI "https://github.com/jonlundberg/loadwhat/blob/main/src/cli.rs"
  click DR "https://github.com/jonlundberg/loadwhat/blob/main/src/debug_run.rs"
  click WIN "https://github.com/jonlundberg/loadwhat/blob/main/src/win.rs"
  click LS "https://github.com/jonlundberg/loadwhat/blob/main/src/loader_snaps.rs"
  click PE "https://github.com/jonlundberg/loadwhat/blob/main/src/pe.rs"
  click SEARCH "https://github.com/jonlundberg/loadwhat/blob/main/src/search.rs"
  click EMIT "https://github.com/jonlundberg/loadwhat/blob/main/src/emit.rs"

  click SPEC "https://github.com/jonlundberg/loadwhat/blob/main/docs/loadwhat_spec_v1.md"

  click HARNESS "https://github.com/jonlundberg/loadwhat/tree/main/tests/harness/"
  click INTEG "https://github.com/jonlundberg/loadwhat/tree/main/tests/integration/"
  click FIX "https://github.com/jonlundberg/loadwhat/tree/main/tests/fixtures/msvc/"
  click XTASK "https://github.com/jonlundberg/loadwhat/tree/main/xtask/"
  click CI "https://github.com/jonlundberg/loadwhat/blob/main/.github/workflows/ci.yml"

  %% additional docs (mapped)
  click SPEC "https://github.com/jonlundberg/loadwhat/blob/main/docs/loadwhat_spec_v1.md"
  click SPEC "https://github.com/jonlundberg/loadwhat/blob/main/docs/loadwhat_ai_agent_spec.md"
  click SPEC "https://github.com/jonlundberg/loadwhat/blob/main/docs/loadwhat_specs_for_codex_current.md"
  click SPEC "https://github.com/jonlundberg/loadwhat/blob/main/docs/loadwhat_specs_for_codex_reconciliation.md"

  %% harness files (mapped)
  click HARNESS "https://github.com/jonlundberg/loadwhat/blob/main/tests/harness/mod.rs"
  click HARNESS "https://github.com/jonlundberg/loadwhat/blob/main/tests/harness/run_loadwhat.rs"
  click HARNESS "https://github.com/jonlundberg/loadwhat/blob/main/tests/harness/assert.rs"
  click HARNESS "https://github.com/jonlundberg/loadwhat/blob/main/tests/harness/case.rs"
  click HARNESS "https://github.com/jonlundberg/loadwhat/blob/main/tests/harness/fixture.rs"
  click HARNESS "https://github.com/jonlundberg/loadwhat/blob/main/tests/harness/paths.rs"
  click HARNESS "https://github.com/jonlundberg/loadwhat/blob/main/tests/harness/win_path.rs"

  %% integration entry + examples (mapped)
  click INTEG "https://github.com/jonlundberg/loadwhat/blob/main/tests/integration.rs"
  click INTEG "https://github.com/jonlundberg/loadwhat/blob/main/tests/integration/dynamic_loader_snaps_contract.rs"
  click INTEG "https://github.com/jonlundberg/loadwhat/blob/main/tests/integration/static_missing_transitive.rs"

  %% fixtures sln (mapped)
  click FIX "https://github.com/jonlundberg/loadwhat/blob/main/tests/fixtures/msvc/LoadWhatFixtures.sln"

  %% xtask files (mapped)
  click XTASK "https://github.com/jonlundberg/loadwhat/blob/main/xtask/src/main.rs"
  click XTASK "https://github.com/jonlundberg/loadwhat/blob/main/xtask/Cargo.toml"

  %% =========================
  %% Styles
  %% =========================
  classDef core fill:#1f3a5f,stroke:#0b1f33,stroke-width:1.5px,color:#ffffff
  classDef engine fill:#2b6e3f,stroke:#13351f,stroke-width:1.5px,color:#ffffff
  classDef osglue fill:#3d4b7a,stroke:#1b2140,stroke-width:1.5px,color:#ffffff
  classDef output fill:#7a3d6a,stroke:#3a1b33,stroke-width:1.5px,color:#ffffff
  classDef external fill:#f2f2f2,stroke:#6b6b6b,stroke-width:1.2px,color:#111111
  classDef decision fill:#ffefc2,stroke:#8a6d00,stroke-width:1.5px,color:#111111
  classDef spec fill:#fff4f4,stroke:#b54b4b,stroke-width:1.4px,color:#111111
  classDef test fill:#e6f4ff,stroke:#2c6aa3,stroke-width:1.4px,color:#111111
  classDef dev fill:#efe6ff,stroke:#5b3aa3,stroke-width:1.4px,color:#111111
```
