Skip to content

Code Organization

Jump to bottom
Calvindd2f edited this page Jan 14, 2026 · 1 revision

Code Organization

Relevant source files

The following files were used as context for generating this wiki page:

This document describes the repository structure and file organization of the OfficeScrubC2R codebase. It explains where different types of files are located, how they are organized into directories, and the relationships between components.

For information about building the project from source, see Building from Source. For coding standards and conventions, see Development Guidelines.

Repository Structure Overview

The repository follows a flat structure at the root level for PowerShell modules, with subdirectories for documentation, testing, and CI/CD infrastructure.

graph TB
    Root["/ (Repository Root)"]
    
    Root --> PSM["OfficeScrubC2R.psm1<br/>Main PowerShell Module"]
    Root --> PSD["OfficeScrubC2R.psd1<br/>Module Manifest"]
    Root --> UTIL["OfficeScrubC2R-Utilities.psm1<br/>Nested Utilities Module"]
    Root --> CS["OfficeScrubC2R-Native.cs<br/>C# Source Code"]
    Root --> DLL["OfficeScrubNative.dll<br/>Pre-compiled Native Library"]
    Root --> BUILD["build.ps1<br/>Build Script"]
    
    Root --> Docs["docs/<br/>Documentation"]
    Root --> GitHub[".github/<br/>CI/CD Infrastructure"]
    Root --> Tests["tests/<br/>Test Suite"]
    Root --> EnUS["en-US/<br/>Help Files"]
    Root --> Release["release/<br/>Build Artifacts"]
    
    Docs --> MemBank["memory-bank/<br/>Design Docs"]
    Docs --> Source["source/<br/>Original VBS"]
    
    GitHub --> Workflows["workflows/<br/>CI Pipelines"]
    GitHub --> Scripts["scripts/<br/>Validation Scripts"]
    
    Workflows --> CI["ci.yml"]
    Scripts --> Validate["Validate-Module.ps1"]
    Scripts --> Utils["utils.ps1"]
    
    Tests --> TestScript["Test-OfficeScrubC2R.ps1"]
    Tests --> Verify["Verify-NativeBuild.ps1"]
    
    EnUS --> Help["about_OfficeScrubC2R.help.txt"]
    
    style Root fill:#f9f9f9
    style PSM fill:#e1f5ff
    style CS fill:#ffe1e1
    style DLL fill:#ffe1e1
Loading

Sources:

Core Source Files

The root directory contains all PowerShell module files and the native C# library components. These files are organized to follow PowerShell Gallery module conventions.

PowerShell Module Files

File Purpose Key Components
OfficeScrubC2R.psd1 Module manifest with metadata, dependencies, and exports ModuleVersion, GUID, RootModule, NestedModules, FunctionsToExport
OfficeScrubC2R.psm1 Main module with exported functions Import-OfficeScrubNative, New-OfficeScrubOrchestrator, Test-OfficeC2RPath, Test-OfficeProductScope
OfficeScrubC2R-Utilities.psm1 Nested utilities module with helper functions Initialize-Environment, Initialize-Log, Write-Log, Get-InstalledProducts

Native C# Library Files

File Purpose Build Target
OfficeScrubC2R-Native.cs C# source code (14,000+ lines) Compilation input
OfficeScrubNative.dll Pre-compiled native library .NET Framework 4.5+
build.ps1 Build automation script Compiles .cs to .dll

The native library contains these key classes: OfficeScrubOrchestrator, RegistryHelper, FileHelper, ProcessHelper, WindowsInstallerHelper, TypeLibHelper, LicenseHelper, ServiceHelper, ShellHelper, GuidHelper.

Sources:

Documentation Structure

Documentation is organized in the docs/ directory with two main subdirectories: memory-bank/ for design documentation and source/ for reference materials.

graph TB
    DocsRoot["docs/"]
    
    DocsRoot --> MB["memory-bank/<br/>Design Documentation"]
    DocsRoot --> Src["source/<br/>Original Source"]
    DocsRoot --> BuildDoc["BUILD.md"]
    DocsRoot --> Changelog["CHANGELOG.md"]
    DocsRoot --> Checklist["CHECKLIST.md"]
    DocsRoot --> Contributing["CONTRIBUTING.md"]
    DocsRoot --> RepoStruct["REPOSITORY_STRUCTURE.md"]
    DocsRoot --> Setup["SETUP_COMPLETE.md"]
    
    MB --> StructMD["structure.md<br/>Project Structure"]
    MB --> TechMD["tech.md<br/>Technical Details"]
    MB --> ProductMD["product.md<br/>Product Info"]
    MB --> GuidelinesMD["guidelines.md<br/>Development Guidelines"]
    
    Src --> VBS["OfficeScrubC2R.vbs<br/>Original Microsoft Script"]
    Src --> SrcReadme["README<br/>Original Documentation"]
    
    style DocsRoot fill:#f9f9f9
    style MB fill:#e1f5ff
    style Src fill:#ffe1e1
Loading

Documentation Categories

Category Files Purpose
Design Docs memory-bank/*.md Architecture, technical decisions, development patterns
Build Guides BUILD.md Compilation instructions and requirements
Change History CHANGELOG.md Version history following Keep a Changelog format
Contribution CONTRIBUTING.md, CHECKLIST.md Developer guidelines and processes
Reference source/OfficeScrubC2R.vbs, source/README Original Microsoft implementation

Sources:

Build and CI Infrastructure

Build and continuous integration configuration is located in .github/ for GitHub Actions and the root-level build.ps1 script.

Build Configuration

The build.ps1 script build.ps1:1-end orchestrates native library compilation:

  1. Locates csc.exe (C# compiler) from .NET Framework installation
  2. Compiles OfficeScrubC2R-Native.cs with references to:
    • System.Management.dll (WMI operations)
    • Microsoft.CSharp.dll (dynamic operations)
  3. Outputs OfficeScrubNative.dll to the module root directory

CI/CD Pipeline Structure

graph LR
    GHRoot[".github/"]
    
    GHRoot --> WF["workflows/"]
    GHRoot --> SCR["scripts/"]
    
    WF --> CI["ci.yml<br/>GitHub Actions Pipeline"]
    
    SCR --> Val["Validate-Module.ps1<br/>Gallery Compatibility Checks"]
    SCR --> Util["utils.ps1<br/>Build Helper Functions"]
    
    CI --> TestJob["Test Job:<br/>Build + Import + Test"]
    CI --> ValJob["Validate Job:<br/>Gallery Compatibility"]
    
    TestJob --> BuildStep["Build Native DLL"]
    TestJob --> ImportStep["Import Module"]
    TestJob --> TestStep["Run Tests"]
    
    ValJob --> ManifestCheck["Check Manifest"]
    ValJob --> FilesCheck["Check Required Files"]
    ValJob --> ZoneCheck["Check Zone Identifiers"]
    
    style CI fill:#e1f5ff
    style TestJob fill:#fff4e1
    style ValJob fill:#ffe1e1
Loading

The CI pipeline .github/workflows/ci.yml:1-end runs two parallel jobs on pull requests and pushes to main branch:

  • Test Job: Validates build process and module import on Windows Server 2022
  • Validate Job: Ensures PowerShell Gallery publication requirements are met

Sources:

Testing Structure

Test files are organized in the tests/ directory, with additional verification scripts in .github/scripts/.

Test Organization

File Purpose Type
tests/Test-OfficeScrubC2R.ps1 Main test suite Functional tests
tests/Verify-NativeBuild.ps1 Build verification Build validation
.github/scripts/Validate-Module.ps1 PowerShell Gallery checks Compliance validation

The test structure supports both manual testing via Pester and automated CI/CD validation.

Sources:

Configuration Files

Repository-level configuration files control version control behavior, code analysis, and build exclusions.

File Purpose Key Configuration
.gitignore Git exclusion rules Excludes *.dll (except OfficeScrubNative.dll), *.log, *.pdb, release/, artifacts/
.gitattributes Git file handling Line ending normalization
PSScriptAnalyzerSettings.psd1 PowerShell linting Code quality rules and exclusions
LICENSE MIT license Distribution terms

The .gitignore file .gitignore:1-59 explicitly includes the pre-compiled OfficeScrubNative.dll using the exception rule !OfficeScrubNative.dll .gitignore:54.

Sources:

Component File Relationships

The following diagram illustrates how source files depend on each other and the load order during module initialization.

graph TB
    subgraph "Module Entry Point"
        PSD1["OfficeScrubC2R.psd1<br/>Module Manifest"]
    end
    
    subgraph "PowerShell Layer"
        PSM1["OfficeScrubC2R.psm1<br/>Main Module"]
        UTIL["OfficeScrubC2R-Utilities.psm1<br/>Nested Module"]
    end
    
    subgraph "Native Layer"
        DLL["OfficeScrubNative.dll<br/>Pre-compiled Binary"]
        CS["OfficeScrubC2R-Native.cs<br/>Source Code"]
        BuildScript["build.ps1<br/>Compilation"]
    end
    
    subgraph "Native Library Classes"
        ORCH["OfficeScrubOrchestrator"]
        REG["RegistryHelper"]
        FILE["FileHelper"]
        PROC["ProcessHelper"]
        MSI["WindowsInstallerHelper"]
        TLB["TypeLibHelper"]
        LIC["LicenseHelper"]
        SVC["ServiceHelper"]
        SHELL["ShellHelper"]
        GUID["GuidHelper"]
    end
    
    PSD1 -->|"RootModule ="| PSM1
    PSD1 -->|"NestedModules ="| UTIL
    
    PSM1 -->|"Import-Module"| UTIL
    PSM1 -->|"Import-OfficeScrubNative()"| DLL
    PSM1 -->|"Fallback Compile"| BuildScript
    
    BuildScript -->|"Compiles"| CS
    CS -->|"Produces"| DLL
    
    DLL --> ORCH
    DLL --> REG
    DLL --> FILE
    DLL --> PROC
    DLL --> MSI
    DLL --> TLB
    DLL --> LIC
    DLL --> SVC
    DLL --> SHELL
    DLL --> GUID
    
    ORCH -->|"Uses"| REG
    ORCH -->|"Uses"| FILE
    ORCH -->|"Uses"| PROC
    ORCH -->|"Uses"| MSI
    ORCH -->|"Uses"| TLB
    ORCH -->|"Uses"| LIC
    ORCH -->|"Uses"| SVC
    ORCH -->|"Uses"| SHELL
    ORCH -->|"Uses"| GUID
    
    style PSD1 fill:#e1f5ff
    style PSM1 fill:#e1f5ff
    style UTIL fill:#e1f5ff
    style DLL fill:#ffe1e1
    style ORCH fill:#fff4e1
Loading

Module Load Sequence

  1. Module Import: PowerShell reads OfficeScrubC2R.psd1 manifest
  2. Root Module Load: Loads OfficeScrubC2R.psm1 as RootModule
  3. Nested Module Import: Imports OfficeScrubC2R-Utilities.psm1 defined in NestedModules
  4. Native DLL Load: Import-OfficeScrubNative function attempts to load OfficeScrubNative.dll
  5. Fallback Compilation: If DLL load fails, executes build.ps1 to compile from OfficeScrubC2R-Native.cs
  6. Orchestrator Creation: New-OfficeScrubOrchestrator instantiates the orchestrator with all helper classes

Sources:

File Dependencies and Import Requirements

The module has specific dependency requirements for different components.

PowerShell Module Dependencies

The manifest OfficeScrubC2R.psd1 declares:

  • PowerShellVersion: Minimum 5.1
  • DotNetFrameworkVersion: Minimum 4.5
  • NestedModules: @('OfficeScrubC2R-Utilities.psm1')
  • RequiredAssemblies: @('OfficeScrubNative.dll')

Native Library Dependencies

The C# source OfficeScrubC2R-Native.cs requires compilation references:

  • System.dll - Base .NET types
  • System.Management.dll - WMI operations for services and licensing
  • Microsoft.CSharp.dll - Dynamic operations and runtime binding

Build System Dependencies

The build.ps1 script requires:

  • C# Compiler: csc.exe from .NET Framework 4.5+ installation
  • Alternative: dotnet build for .NET Core 7+ compilation
  • Environment Variables: ProgramFiles(x86) or ProgramFiles for locating compiler

Sources:

Output and Artifact Locations

Build outputs and artifacts are organized into excluded directories to keep the repository clean.

Excluded Directories

Directory Purpose Tracking
release/ Release artifacts and packages .gitignore excluded
artifacts/ CI/CD verification artifacts .gitignore excluded
temp/, tmp/ Temporary build files .gitignore excluded
TestResults/ Test execution results .gitignore excluded

Included Artifacts

File Tracking Reason
OfficeScrubNative.dll Committed to repository Pre-compiled for immediate use without build requirements

The pre-compiled DLL OfficeScrubNative.dll is explicitly tracked .gitignore:54 to allow users to import the module without requiring the .NET Framework compiler or build tools.

Sources:

Help and Localization Structure

PowerShell help files are organized using standard PowerShell localization directory conventions.

en-US/
└── about_OfficeScrubC2R.help.txt  # PowerShell help documentation

The en-US/ directory follows PowerShell's culture-specific help file structure, allowing for potential future localization into other languages using additional culture directories (e.g., de-DE/, fr-FR/).

Sources:

Clone this wiki locally