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.

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":

# 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

Created: April 7, 2026 • Last Modified: April 7, 2026

Docs Login