proxmox/docs/scripts/organize_files.py

#!/usr/bin/env python3
"""
Script to categorize and organize standalone documentation files
"""
import os
import shutil
from pathlib import Path
from collections import defaultdict

DOCS_DIR = Path("/home/intlc/projects/proxmox/docs")
ARCHIVE_DIR = DOCS_DIR / "archive"

# Category patterns
CATEGORIES = {
    "status": [
        "STATUS", "PROGRESS", "MIGRATION_STATUS", "CONNECTION_STATUS",
        "DEPLOYMENT_STATUS", "VERIFICATION_STATUS", "SERVICE_STATUS",
        "CONFIG_STATUS", "SETUP_STATUS", "NEXT_STEPS_STATUS"
    ],
    "completion": [
        "COMPLETE", "COMPLETED", "COMPLETION", "SUCCESS", "FINAL",
        "ALL_TASKS_COMPLETE", "ALL_STEPS_COMPLETE", "ALL_TODOS_COMPLETE",
        "FIX_COMPLETE", "SETUP_COMPLETE", "DEPLOYMENT_COMPLETE",
        "IMPLEMENTATION_COMPLETE", "REVIEW_COMPLETE", "VERIFICATION_COMPLETE"
    ],
    "fixes": [
        "FIX", "FIXED", "FIXES", "RESOLUTION", "RESOLVED", "CORRECTED",
        "QUICK_FIX", "FIX_SUMMARY", "FIX_COMPLETE", "FIX_APPLIED"
    ],
    "tests": [
        "TEST", "TESTING", "VERIFICATION", "VALIDATION", "CHECKLIST",
        "QUICKSTART_RESULTS", "FUNCTIONALITY_TEST", "INTEGRATION_TEST"
    ],
    "configuration": [
        "CONFIGURATION", "CONFIG", "SETUP", "INSTALLATION", "GUIDE",
        "INSTRUCTIONS", "QUICK_START", "QUICKSTART", "TROUBLESHOOTING"
    ],
    "historical": [
        "SUMMARY", "REPORT", "ANALYSIS", "REVIEW", "INVESTIGATION",
        "FINDINGS", "RESULTS", "PLAN", "REFERENCE", "INVENTORY"
    ]
}

# Files to keep in root (active documentation)
KEEP_IN_ROOT = {
    "README.md", "MASTER_INDEX.md", "DOCUMENTATION_REVIEW.md",
    "CLEANUP_SUMMARY.md", "DOCUMENTATION_UPGRADE_SUMMARY.md"
}

# Files that should move to numbered directories
MOVE_TO_DIRS = {
    "BLOCKSCOUT_CONFIGURATION_GUIDE.md": "08-monitoring",
    "BLOCKSCOUT_START_INSTRUCTIONS.md": "08-monitoring",
    "BLOCKSCOUT_VERIFICATION_GUIDE.md": "08-monitoring",
    "TROUBLESHOOTING_GUIDE.md": "09-troubleshooting",
    "DEPLOYMENT_RUNBOOK.md": "03-deployment",
    "DEPLOYMENT_READINESS_CHECKLIST.md": "03-deployment",
    "PRE_START_CHECKLIST.md": "03-deployment",
    "PRE_START_AUDIT_PLAN.md": "03-deployment",
    "API_DOCUMENTATION.md": "11-references",
    "CONTRACT_ADDRESSES_REFERENCE.md": "11-references",
    "TOKEN_LIST_AUTHORING_GUIDE.md": "11-references",
    "METAMASK_CONFIGURATION.md": "04-configuration",
    "METAMASK_TROUBLESHOOTING_GUIDE.md": "09-troubleshooting",
    "METAMASK_QUICK_START_GUIDE.md": "01-getting-started",
    "CLOUDFLARE_TUNNEL_CONFIGURATION_GUIDE.md": "04-configuration",
    "CLOUDFLARE_TUNNEL_INSTALLATION.md": "04-configuration",
    "CLOUDFLARE_TUNNEL_ROUTING_ARCHITECTURE.md": "05-network",
    "CLOUDFLARE_EXPLORER_CONFIG.md": "04-configuration",
    "CLOUDFLARE_EXPLORER_QUICK_SETUP.md": "04-configuration",
    "RPC_PUBLIC_ENDPOINT_ROUTING.md": "05-network",
    "CENTRAL_NGINX_ROUTING_SETUP.md": "05-network",
    "NGINX_SETUP_FINAL_SUMMARY.md": "05-network",
    "CHAIN138_QUICK_START.md": "01-getting-started",
    "CHAIN138_BESU_CONFIGURATION.md": "06-besu",
    "CHAIN138_AUTOMATION_SCRIPTS.md": "03-deployment",
    "CHAIN138_JWT_AUTH_REQUIREMENTS.md": "04-configuration",
    "CCIP_SECURITY_DOCUMENTATION.md": "07-ccip",
    "CCIP_SENDER_CONTRACT_REFERENCE.md": "07-ccip",
    "BRIDGE_TESTING_GUIDE.md": "07-ccip",
    "COMPREHENSIVE_INFRASTRUCTURE_REVIEW.md": "02-architecture",
    "COMPREHENSIVE_RECOMMENDATIONS.md": "10-best-practices",
    "PROXMOX_COMPLETE_RECOMMENDATIONS.md": "10-best-practices",
    "PROXMOX_COMPREHENSIVE_REVIEW.md": "02-architecture",
    "PROXMOX_FINAL_RECOMMENDATIONS.md": "10-best-practices",
    "ENABLE_ROOT_SSH_CONTAINER.md": "04-configuration",
    "LVM_THIN_PVE_ENABLED.md": "03-deployment",
    "STORAGE_MIGRATION_ISSUE.md": "09-troubleshooting",
    "MISSING_CONTAINERS_LIST.md": "03-deployment",
}

def categorize_file(filename):
    """Categorize a file based on its name"""
    filename_upper = filename.upper()
    
    # Check if should move to numbered directory
    if filename in MOVE_TO_DIRS:
        return ("move_to_dir", MOVE_TO_DIRS[filename])
    
    # Check category patterns
    for category, patterns in CATEGORIES.items():
        for pattern in patterns:
            if pattern in filename_upper:
                return ("archive", category)
    
    # Default to historical
    return ("archive", "historical")

def organize_files():
    """Main organization function"""
    moved = defaultdict(list)
    errors = []
    
    # Get all markdown files in docs root
    for file_path in DOCS_DIR.glob("*.md"):
        filename = file_path.name
        
        # Skip files to keep in root
        if filename in KEEP_IN_ROOT:
            continue
        
        try:
            category, dest = categorize_file(filename)
            
            if category == "move_to_dir":
                dest_path = DOCS_DIR / dest
                dest_path.mkdir(exist_ok=True)
                shutil.move(str(file_path), str(dest_path / filename))
                moved[f"moved_to_{dest}"].append(filename)
            elif category == "archive":
                dest_path = ARCHIVE_DIR / dest
                dest_path.mkdir(exist_ok=True)
                shutil.move(str(file_path), str(dest_path / filename))
                moved[f"archived_to_{dest}"].append(filename)
        except Exception as e:
            errors.append(f"{filename}: {str(e)}")
    
    # Print summary
    print("=" * 60)
    print("FILE ORGANIZATION SUMMARY")
    print("=" * 60)
    for category, files in moved.items():
        print(f"\n{category}: {len(files)} files")
        if len(files) <= 10:
            for f in files:
                print(f"  - {f}")
        else:
            for f in files[:5]:
                print(f"  - {f}")
            print(f"  ... and {len(files) - 5} more")
    
    if errors:
        print(f"\nERRORS ({len(errors)}):")
        for error in errors:
            print(f"  - {error}")
    
    print(f"\nTotal files organized: {sum(len(files) for files in moved.values())}")
    return moved, errors

if __name__ == "__main__":
    print("Starting file organization...")
    moved, errors = organize_files()
    print("\nOrganization complete!")