PathRegistry Module

Version: 2.0.0 Status: ✅ MIGRATED Location: 03_INFRA/03_00_development_environment/03_00_08_profile_management/PathRegistry/

---

📖 Overview

PathRegistry is a PowerShell module that provides centralized path management for the entire AudioLab project. It eliminates hardcoded paths and provides a single source of truth for all project directories.

Key Benefits

• ✅ Single Source of Truth - All paths defined in one place
• ✅ Auto-Detection - Automatically finds repository root
• ✅ Cross-Script Consistency - All scripts use the same paths
• ✅ Environment Flexibility - Supports local overrides for different machines
• ✅ Safe Path Operations - Optional directory creation with -Ensure flag

---

🚀 Quick Start

Load the Module

# Import PathRegistry
Import-Module .\PathRegistry.psm1

# Or with full path
Import-Module "C:\AudioDev\audio-lab\03_INFRA\03_00_development_environment\03_00_08_profile_management\PathRegistry\PathRegistry.psm1"

Basic Usage

# Get repository root
$root = Get-RepoRoot
# Returns: C:\AudioDev\audio-lab

# Get a registered path
$buildPath = Get-Path "BUILD"
# Returns: C:\AudioDev\audio-lab\_ARTIFACTS\build

# Get a path and ensure directory exists
$logsPath = Get-Path "ARTIFACTS" -Ensure
# Returns path and creates directory if needed

# Resolve a relative path under a base
$logFile = Resolve-Under "ARTIFACTS" "logs\build.log"
# Returns: C:\AudioDev\audio-lab\_ARTIFACTS\logs\build.log

# List all registered paths
Get-AllPaths | Format-Table

# Validate all paths exist
Test-AllPaths -Verbose

---

📋 Available Path IDs

Core Paths

ID	Description	Example Value
REPO	Repository root	C:\AudioDev\audio-lab
WORKING	Active work directory	C:\AudioDev\audio-lab\_WORKING
ARTIFACTS	Build artifacts	C:\AudioDev\audio-lab\_ARTIFACTS
BUILD	CMake build directory	C:\AudioDev\audio-lab\_ARTIFACTS\build

Infrastructure Paths

ID	Description	Example Value
INFRA	Infrastructure root	03_INFRA
PIPELINE	CI/CD pipeline	00_PIPELINE
BUILD_SYSTEM	Build infrastructure	03_INFRA\03_02_build_infrastructure
DEV_ENV	Development environment	03_INFRA\03_00_development_environment
TESTING	Testing framework	03_INFRA\03_04_testing_framework

Module & Component Paths

ID	Description	Example Value
CORE	Core libraries	04_CORE
MODULES	Audio modules	05_MODULES
PLUGINS	Plugin projects	08_PLUGINS
GRAPHICS	Graphics assets	06_GRAPHICS
ASSETS	General assets	07_ASSETS

Documentation Paths

ID	Description	Example Value
DOCS	Documentation root	10_DOCUMENTATION
DOCS_PLATFORM	MkDocs platform	03_INFRA\03_11_documentation_platform

System Paths

ID	Description	Example Value
VST3_USER	User VST3 directory	%APPDATA%\Common Files\VST3
VST3_SYSTEM	System VST3 directory	C:\Program Files\Common Files\VST3
TEMP	System temp directory	%TEMP%

---

🔧 Function Reference

Get-RepoRoot

Finds the repository root directory.

# Auto-detect from current location
$root = Get-RepoRoot

# Start searching from specific path
$root = Get-RepoRoot -StartPath "C:\AudioDev\audio-lab\05_MODULES"

Returns: String - Absolute path to repository root

Detection Methods: 1. Tries git rev-parse --show-toplevel (fastest) 2. Looks for .audiolab-root marker file 3. Looks for .git directory

---

Initialize-PathMap

Initializes the path registry (called automatically).

# Auto-detect repo root
Initialize-PathMap

# Specify repo root
Initialize-PathMap -RepoRoot "C:\AudioDev\audio-lab"

Returns: Hashtable - Complete path registry

Features: - Loads default paths for current structure - Applies local overrides from paths.local.json if present - Caches result in module-level variable

---

Get-Path

Gets a registered path by ID.

# Get path (throws error if not found)
$path = Get-Path "BUILD"

# Get path and create directory if it doesn't exist
$path = Get-Path "BUILD" -Ensure

# Use in scripts
$corePath = Get-Path "CORE"
Push-Location $corePath
# ... do work ...
Pop-Location

Parameters: - Id (required) - Path identifier - Ensure (optional) - Create directory if it doesn't exist

Returns: String - Absolute path

Throws: If path ID doesn't exist (shows available IDs)

---

Resolve-Under

Combines a base path with a relative subpath.

# Resolve without ensuring parent exists
$logFile = Resolve-Under "ARTIFACTS" "logs\build.log"

# Resolve and ensure parent directory exists
$outputFile = Resolve-Under "BUILD" "Debug\MyPlugin.vst3" -Ensure

Parameters: - BaseId (required) - Base path identifier - Relative (required) - Relative path to append - Ensure (optional) - Create parent directory if needed

Returns: String - Combined absolute path

---

Get-AllPaths

Lists all registered paths.

# Get as hashtable
$paths = Get-AllPaths

# Display as table
Get-AllPaths | Format-Table

# Access specific path
$paths = Get-AllPaths
Write-Host "Build: $($paths['BUILD'])"

Returns: Hashtable - All path mappings

---

Test-AllPaths

Validates that all registered paths exist.

# Basic validation
$allValid = Test-AllPaths

# Verbose output (shows each path check)
Test-AllPaths -Verbose

Returns: Boolean - $true if all paths exist, $false otherwise

Useful For: - Setup verification - Diagnostics - CI/CD validation

---

⚙️ Configuration

Default Configuration

Default paths are defined in paths.default.json but are primarily used for documentation. The actual defaults are in the module code.

Local Overrides

Create paths.local.json (git-ignored) to override paths for your machine:

{
  "BUILD": "D:\\MyCustomBuild",
  "ARTIFACTS": "E:\\FastDrive\\artifacts",
  "VST3_USER": "C:\\MyVST3Plugins"
}

Features: - {REPO} placeholder is replaced with actual repo root - Overrides are merged with defaults - File is git-ignored for machine-specific settings

---

🧪 Testing

Manual Tests

# Load module
Import-Module .\PathRegistry.psm1 -Force

# Test 1: Get repository root
Write-Host "Repository root: $(Get-RepoRoot)"

# Test 2: Initialize and list paths
Initialize-PathMap
Get-AllPaths | Format-Table

# Test 3: Get specific paths
Write-Host "BUILD: $(Get-Path 'BUILD')"
Write-Host "CORE: $(Get-Path 'CORE')"
Write-Host "MODULES: $(Get-Path 'MODULES')"

# Test 4: Resolve relative paths
$logFile = Resolve-Under "ARTIFACTS" "logs\test.log"
Write-Host "Log file: $logFile"

# Test 5: Ensure directory creation
$testPath = Get-Path "ARTIFACTS" -Ensure
Test-Path $testPath

# Test 6: Validate all paths
Test-AllPaths -Verbose

# Test 7: Error handling (invalid path ID)
try {
    Get-Path "INVALID_PATH"
} catch {
    Write-Host "Expected error: $_"
}

Automated Test Script

# Test script location: PathRegistry\Test-PathRegistry.ps1
Import-Module .\PathRegistry.psm1 -Force

Write-Host "`n=== PathRegistry Module Tests ===" -ForegroundColor Cyan

$tests = @(
    @{ Name = "Get-RepoRoot"; Test = { Get-RepoRoot | Should -Not -BeNullOrEmpty } },
    @{ Name = "Initialize-PathMap"; Test = { $map = Initialize-PathMap; $map.Count | Should -BeGreaterThan 10 } },
    @{ Name = "Get-Path BUILD"; Test = { Get-Path "BUILD" | Should -Match "build" } },
    @{ Name = "Resolve-Under"; Test = { Resolve-Under "BUILD" "test" | Should -Match "test" } },
    @{ Name = "Get-AllPaths"; Test = { $paths = Get-AllPaths; $paths.REPO | Should -Not -BeNullOrEmpty } }
)

$passed = 0
foreach ($test in $tests) {
    try {
        & $test.Test
        Write-Host "✓ $($test.Name)" -ForegroundColor Green
        $passed++
    } catch {
        Write-Host "✗ $($test.Name): $_" -ForegroundColor Red
    }
}

Write-Host "`nTests passed: $passed / $($tests.Count)" -ForegroundColor Cyan

---

📚 Usage Examples

In Build Scripts

Import-Module (Join-Path (Get-RepoRoot) "03_INFRA\03_00_development_environment\03_00_08_profile_management\PathRegistry\PathRegistry.psm1")

# Get paths for build
$buildDir = Get-Path "BUILD" -Ensure
$artifactsDir = Get-Path "ARTIFACTS" -Ensure

# Configure CMake
cmake -S (Get-Path "REPO") -B $buildDir
cmake --build $buildDir

# Copy output
$outputPath = Resolve-Under "ARTIFACTS" "plugins\MyPlugin.vst3"
Copy-Item "$buildDir\MyPlugin.vst3" $outputPath

In Generator Scripts

Import-Module PathRegistry

# Get template directory
$templatesDir = Resolve-Under "INFRA" "templates\plugin"

# Get output directory
$outputDir = Resolve-Under "PLUGINS" "MyNewPlugin" -Ensure

# Generate plugin
Copy-Item "$templatesDir\*" $outputDir -Recurse

In Test Scripts

Import-Module PathRegistry

# Get test data directory
$testDataDir = Resolve-Under "TESTING" "data\audio_samples"

# Get test output directory
$testOutputDir = Resolve-Under "ARTIFACTS" "test_results" -Ensure

# Run tests
ctest --test-dir (Get-Path "BUILD") --output-dir $testOutputDir

---

🔄 Migration Notes

Changes from Legacy Version

Location Changed: - OLD: __LEGAZY/06_BRAIN/00_system/1_modules/PathRegistry.psm1 - NEW: 03_INFRA/03_00_development_environment/03_00_08_profile_management/PathRegistry/PathRegistry.psm1

Path Structure Updated: - Removed references to 06_BRAIN (legacy) - Added support for current folder structure (00-20 folders) - Added 00_PIPELINE, _WORKING, _ARTIFACTS paths - Updated infrastructure paths to match 03_INFRA organization

Improvements: - Better error messages with available path IDs - Enhanced documentation and examples - Improved .audiolab-root marker support - More robust path validation - Added Get-AllPaths and Test-AllPaths functions

---

🐛 Troubleshooting

Module Won't Load

# Check file exists
Test-Path ".\PathRegistry.psm1"

# Import with verbose output
Import-Module .\PathRegistry.psm1 -Verbose -Force

# Check for syntax errors
Get-Content .\PathRegistry.psm1 | Out-Null

Repository Root Not Found

# Check for .audiolab-root marker
Test-Path ".audiolab-root"

# Check git is available
git --version

# Manually specify root
$env:AUDIOLAB_ROOT = "C:\AudioDev\audio-lab"

Path Not Found Error

# List all available path IDs
Get-AllPaths | Format-Table

# Check spelling
Get-Path "BIULD"  # Typo! Should be "BUILD"

# Validate all paths
Test-AllPaths -Verbose

---

📞 Support

Documentation: This README Source: PathRegistry.psm1 Issues: Report in project tracking system Project: LEGAZY-RESCUE-2025 (TASK-001)

---

📝 Changelog

Version 2.0.0 (2025-10-17)

• ✅ Migrated from 06_BRAIN to 03_INFRA
• ✅ Updated for current project structure
• ✅ Added comprehensive documentation
• ✅ Added Get-AllPaths and Test-AllPaths functions
• ✅ Improved error handling
• ✅ Added support for .audiolab-root marker
• ✅ Created paths.default.json configuration
• ✅ Added local override support via paths.local.json

Version 1.0.0 (Legacy)

• Initial implementation in 06_BRAIN
• Basic path registry functionality

---

Module Status: ✅ PRODUCTION READY Last Updated: 2025-10-17 Maintainer: AudioLab Development Team