# Modularization Proposal: Verify Bridge Path

Based on the recent complexity audit (Complexity: **Very High / 87 points**), the `verify-bridge-path.ps1` script has grown into a "God Script" that handles everything from API communication to detailed filesystem heuristics. 

Modularizing this script will reduce the line count from ~600 to under 100 in the main loop, drastically improving readability and allowing shared logic (like API helpers) to be used across the entire toolset.

## 🏗️ Proposed Directory Structure

Original monolith file as its already backed up `(tools/backups/evals/verify-bridge-path-20260407-1028.ps1)` using `tools/eval-ps.ps1` which also generated eval reports at `tools/telemetry/verify-bridge-path-20260407-1028.json` and `/tools/telemetry/verify-bridge-path-20260407-1028.md` which helped create the diagnostics, variables, and functions used in the monolith file.

We generated a modularization sandbox for the target script as `verify-bridge-path/` directly inside `tools/modularization` using `tools/modularization/scaffold-modularization-files.ps1`.

Allow `verify-bridge-path_modularized.ps1` to become the new main orchestrator. It serves as the primary entry point, dot-sourcing the specialized functions from the `lib/` directory. Once the contents are moved to the root `tools/` folder and the file is renamed, it replaces the monolith.

> **Note on Orchestration:** The `verify-bridge-path_modularized.ps1` file manages environment initialization and coordinates the audit suite, but delegates all categorical logic (API, Discovery, Audits, Reporting) to the libraries in its associated `lib` folder.

No changes are needed to the original monolith file. Only use it for reference if needed. 

```text
tools/
├── verify-bridge-path.ps1          (Main Orchestrator [to be replaced, no changes needed])
├── modularization/
│   └── verify-bridge-path/
│       ├── verify-bridge-path_modularized.ps1          (Main Orchestrator Modularized)
│       └── lib/
│           ├── bridge-api.ps1              (Shared API Wrappers)
│           ├── bridge-discovery.ps1        (Account & Partition Logic)
│           ├── bridge-audits.ps1           (Health, Security, & Baseline Checks)
│           └── bridge-reporting.ps1        (Telemetry & JSON Output)

```

## 🧩 Categorical Module Breakdown

### 1. `lib/bridge-api.ps1` (Shared Client)
**Responsibility:** Communication and Error Handling.
- Move `Invoke-Cpanel-API2` and `Invoke-UAPI`.
- Add `Test-CpanelApiResult` (currently found in `test-symlink.ps1`) to provide unified error parsing for all tools.

### 2. `lib/bridge-discovery.ps1` (Pathfinding)
**Responsibility:** Identifying the target location.
- Logic for `listaccts` (Home/Partition resolution).
- The `PathsToExplore` loop that detects Atomic vs. Legacy structures.
- Returns a standardized "Bridge Context" object.

### 3. `lib/bridge-audits.ps1` (Check Suite)
**Responsibility:** Domain-specific validation logic.
- **Structural Audit**: Mapping `releases`, `current`, and `backups`.
- **Asset Matrix**: Comparing file existence across scopes.
- **Security Audit**: `.htaccess` parsing and permission checks.
- **Maintenance Audits**: Cleanup (artifacts), Legacy Presence, and Baseline Health.

### 4. `lib/bridge-reporting.ps1` (Data Output)
**Responsibility:** Console feedback and persistence.
- Logic for the Cyan/Green console output headers.
- Construction of the `StringBuilder` for the Markdown report.
- Final assembly of the `bridge_path.json` telemetry object.

## 🔄 Refactored Main Orchestrator (Example)

By moving the "How" into modules, the main `verify-bridge-path.ps1` focus shifts to "What":

```powershell
# 1. Load Modules
. "$PSScriptRoot\tools\lib\bridge-api.ps1"
. "$PSScriptRoot\tools\lib\bridge-discovery.ps1"
. "$PSScriptRoot\tools\lib\bridge-audits.ps1"
. "$PSScriptRoot\tools\lib\bridge-reporting.ps1"

# 2. Environment Initialization
$Context = Get-BridgeAccountContext -TargetUser "ab6506"
$Discovery = Resolve-BridgeRoot -Context $Context

# 3. Audit Suite
$Map = Get-BridgeStructuralMap -Context $Context -Discovery $Discovery
$Security = Invoke-BridgeSecurityAudit -Context $Context -Discovery $Discovery
$Readiness = Get-MigrationReadiness -Map $Map -SecurityAudit $Security

# 4. Persistence
Save-BridgeReports -JsonData $JsonData -MarkdownText $ReportText
```

## 📈 Complexity Comparison & Refactoring Audit

| Component | Lines | Complexity Points | Rating |
| :--- | :--- | :--- | :--- |
| **Original Monolith** | 585 | **87** | **Very High** |
| **verify-bridge-path_modularized.ps1** | 91 | **4** | **Low** |
| `lib/bridge-audits.ps1` | 280 | 31 | Moderate High |
| `lib/bridge-reporting.ps1` | 130 | 26 | Moderate High |
| `lib/bridge-discovery.ps1` | 64 | 8 | Low |
| `lib/bridge-api.ps1` | 52 | 7 | Low |

**Audit Summary:** The migration successfully decentralized logic. The "Peak Cognitive Load" (the difficulty of reading the most complex file) dropped from **87 to 31**, a 64% improvement in maintainability.

### 🚀 Future Growth & Potentials
- **Orchestrator Lean-ness**: The orchestrator is now a "Thin Controller". Any new high-level deployment phases can be added as single-line function calls without bloating the main script.
- **Categorical Reporting**: `bridge-reporting.ps1` (26 points) currently uses a single large `StringBuilder` loop. As more audits are added, we should move to a section-based builder (e.g., `Build-SecuritySection`, `Build-StorageSection`) to keep complexity low.
- **Asset Matrix Extraction**: `bridge-audits.ps1` (31 points) is currently the "heaviest" logic file. If heuristics for "Atomic vs Legacy" grow, the `Get-BridgeAssetMatrix` logic could be moved into its own specialized library.
- **API Generalization**: `bridge-api.ps1` provides a solid foundation to become a shared WHM/cPanel SDK for other deployment tools in the `wp-poster` ecosystem.

## STATUS OF MODULARIZATION
Complete