Skip to content

docs: add library usage documentation and architecture guide [8 of 8] #280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
whizzzkid wants to merge 1 commit into
base: feat/refactor-library-part_7
Choose a base branch
from
Open

docs: add library usage documentation and architecture guide [8 of 8] #280

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,38 @@ Review the [latest release](https://github.com/oscope-dev/scope/releases/latest)
**Cargo**

```shell
cargo install dev-scope
cargo install dx-scope
```

**Manually**

To install manually, download the correct archive for your platform from [github release](https://github.com/oscope-dev/scope/releases/latest), extract it, and place the binaries on the `PATH`.

## Library Usage

`scope` can be used as a Rust library for programmatic access to the analyze and doctor functionality:

```toml
[dependencies]
dx-scope = "2026.1"
tokio = { version = "1", features = ["full"] }
```

```rust
use dx_scope::{AnalyzeOptions, AutoApprove, DoctorRunOptions};

// Use AutoApprove for CI/automated environments
// Use DenyAll for dry-run mode
let interaction = AutoApprove;

// Configure doctor options programmatically
let options = DoctorRunOptions::with_fixes();
```

For detailed library documentation, see:
- [Library Usage Guide](docs/library-usage.md)
- [API Documentation](https://docs.rs/dx-scope)

## Commands

### `scope doctor`
Expand Down
177 changes: 177 additions & 0 deletions docs/docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
# Architecture

This document describes the architecture of the `dx-scope` library and how it separates library functionality from CLI concerns.

## Module Structure

```mermaid
graph TD
subgraph "Library API (dx-scope crate)"
LIB[lib.rs<br/>Public Exports]

subgraph "Core Modules"
DOCTOR[doctor/<br/>Health Checks]
ANALYZE[analyze/<br/>Error Detection]
REPORT[report/<br/>Bug Reports]
LINT[lint/<br/>Config Validation]
end

subgraph "Abstractions"
INTERNAL[internal/<br/>UserInteraction<br/>ProgressReporter]
end

subgraph "Shared Utilities"
SHARED[shared/<br/>Config Loading<br/>Output Capture]
MODELS[models/<br/>Data Schemas]
end
end

subgraph "Binary Layer"
BIN[bin/scope.rs<br/>Thin CLI Wrapper]
BINCLI[bin/cli/<br/>Command Routing]
end

LIB --> DOCTOR
LIB --> ANALYZE
LIB --> INTERNAL
LIB --> SHARED

BIN --> BINCLI
BINCLI --> LIB
```

## Library API Flow

```mermaid
flowchart TB
subgraph Consumer["External Consumer"]
APP[Your Rust Application]
end

subgraph Library["dx-scope Library"]
API[Library API<br/>doctor::run<br/>analyze::process_input]
OPTIONS[Options Types<br/>DoctorRunOptions<br/>AnalyzeOptions]
TRAITS[Trait Abstractions<br/>UserInteraction<br/>ProgressReporter]
end

subgraph Implementations["Interaction Implementations"]
AUTO[AutoApprove<br/>CI Mode]
DENY[DenyAll<br/>Dry-Run]
INQ[InquireInteraction<br/>Interactive CLI]
CUSTOM[Your Custom Impl]
end

APP --> OPTIONS
APP --> API
API --> TRAITS
TRAITS --> AUTO
TRAITS --> DENY
TRAITS --> INQ
TRAITS --> CUSTOM
```

## Data Flow: Doctor Run

```mermaid
sequenceDiagram
participant App as Application
participant Lib as doctor::run()
participant UI as UserInteraction
participant Exec as ExecutionProvider

App->>Lib: run(config, options)
Lib->>Exec: Execute check command
Exec-->>Lib: Check result

alt Check Failed & Fix Available
Lib->>UI: confirm("Apply fix?")
UI-->>Lib: true/false
opt User Approved
Lib->>Exec: Execute fix command
Exec-->>Lib: Fix result
end
end

Lib-->>App: PathRunResult
```

## Key Design Principles

### Library-First Design

The codebase follows a library-first approach where:

1. **Core functionality lives in the library** - All health check logic, error detection, and configuration handling is in the `dx-scope` crate
2. **CLI is a thin wrapper** - The binary (`bin/scope.rs`) is approximately 100 lines and delegates to the library
3. **No console output in library code** - The library uses tracing for logging; CLI-specific output functions live in `bin/cli/`

### Trait Abstractions

The library uses traits to abstract user interaction and progress reporting:

| Trait | Purpose | Implementations |
|-------|---------|-----------------|
| `UserInteraction` | Prompt user for confirmations | `AutoApprove`, `DenyAll`, `InquireInteraction` |
| `ProgressReporter` | Report progress updates | `NoOpProgress` |
| `ExecutionProvider` | Execute shell commands | `DefaultExecutionProvider`, `MockExecutionProvider` |

### Options Types

Each major operation has a dedicated options type that is independent of CLI argument parsing:

| Options Type | Module | Purpose |
|--------------|--------|---------|
| `DoctorRunOptions` | `doctor` | Configure health check runs |
| `AnalyzeOptions` | `analyze` | Configure error detection |
| `ConfigLoadOptions` | `shared::config` | Configure configuration loading |

## Module Responsibilities

### `doctor/`

Health check system that:
- Runs checks defined in configuration
- Applies fixes when checks fail (with user confirmation)
- Reports results via `PathRunResult`

Key types:
- `DoctorRunOptions` - Run configuration
- `PathRunResult` - Execution results

### `analyze/`

Error detection system that:
- Scans text/files for known error patterns
- Matches against configured `KnownError` definitions
- Reports matches via `AnalyzeStatus`

Key types:
- `AnalyzeOptions` - Analysis configuration
- `AnalyzeInput` - Input source specification
- `AnalyzeStatus` - Analysis outcome

### `internal/`

Abstraction traits for:
- User interaction (prompts, confirmations)
- Progress reporting

### `shared/`

Shared utilities including:
- Configuration loading
- Command execution
- Output capture
- Report building

### `models/`

Data model definitions including:
- `DoctorGroup` - Health check group definition
- `KnownError` - Error pattern definition
- `ReportLocation` - Report upload configuration

## See Also

- [Library Usage Guide](./library-usage.md) - How to use dx-scope as a library
- [API Documentation](https://docs.rs/dx-scope) - Generated API documentation
Loading