migrate_group.py

#!/usr/bin/env python3
"""
Umbrella script for migrating an Xcode PBXGroup to a
PBXFileSystemSynchronizedRootGroup (folder reference).

Author: Deszip
Usage:
  python migrate_group.py <group_path>
  python migrate_group.py --verbose <group_path>
  python migrate_group.py --dry-run <group_path>

Example:
  python migrate_group.py "Classes/Intents"
  python migrate_group.py --verbose "Classes/Intents"

Steps:
  1. Extract target memberships from the old PBXGroup
  2. Move files on disk to match group hierarchy (git mv)
  3. Remove old PBXGroup entries from pbxproj
  4. Add PBXFileSystemSynchronizedRootGroup + exception sets
"""

import json
import os
import subprocess
import sys
import time
from collections import defaultdict


PBXPROJ_PATH = "ReaddleDocs2.xcodeproj/project.pbxproj"

ALL_TARGETS = [
    'Documents', 'DocumentsDemo',
    'PDFExpert', 'PDFExpert Demo',
]


def find_suspicious_items(target_base, files_dict):
    """Scan target folder for files/dirs not in the group.

    files_dict: the 'files' dict from JSON with keys being
    expected relative paths and values having 'disk_path'.
    """
    if not os.path.isdir(target_base):
        return []

    expected = set(files_dict.keys())

    # Current disk paths relative to target_base
    known_current = set()
    abs_base = os.path.abspath(target_base)
    for fdata in files_dict.values():
        abs_disk = os.path.abspath(fdata['disk_path'])
        if abs_disk.startswith(abs_base + '/'):
            rel = os.path.relpath(abs_disk, abs_base)
            known_current.add(rel)

    known_files = expected | known_current

    known_dirs = set()
    for f in known_files:
        parts = f.split('/')
        for i in range(1, len(parts)):
            known_dirs.add('/'.join(parts[:i]))

    opaque_exts = {
        '.xcassets', '.xcdatamodeld',
        '.xcmappingmodel', '.bundle',
        '.playground',
    }

    suspicious = []
    for dirpath, dirnames, filenames in os.walk(target_base):
        rel_dir = os.path.relpath(dirpath, target_base)
        if rel_dir == '.':
            rel_dir = ''

        # Don't recurse into opaque bundles
        bundles = [
            d for d in dirnames
            if os.path.splitext(d)[1] in opaque_exts
        ]
        for b in bundles:
            dirnames.remove(b)
            rel_path = (
                f"{rel_dir}/{b}" if rel_dir else b
            )
            if rel_path not in known_files:
                suspicious.append(rel_path)

        # Don't recurse into dirs that are known files
        # (folder references like Lottie animation dirs)
        folder_refs = [
            d for d in dirnames
            if (
                f"{rel_dir}/{d}" if rel_dir else d
            ) in known_files
        ]
        for fr in folder_refs:
            dirnames.remove(fr)

        for fname in filenames:
            if fname == '.DS_Store':
                continue
            rel_path = (
                f"{rel_dir}/{fname}" if rel_dir else fname
            )
            if rel_path not in known_files:
                suspicious.append(rel_path)

        for dname in dirnames:
            rel_path = (
                f"{rel_dir}/{dname}" if rel_dir else dname
            )
            if rel_path not in known_dirs:
                suspicious.append(f"{rel_path}/")

    return sorted(suspicious)


def report_suspicious(target_base, suspicious):
    """Print a warning about untracked items in the folder."""
    if not suspicious:
        return
    print()
    print("!" * 60)
    print("  SUSPICIOUS: Items on disk not in Xcode group")
    print("!" * 60)
    print()
    print(
        f"  The following items exist in '{target_base}' "
        f"but are not part"
    )
    print(
        "  of the migrated group. They were left untouched."
    )
    print()
    for item in suspicious:
        tag = "dir " if item.endswith('/') else "file"
        print(f"  [{tag}] {item}")
    print()


def resolve_folder_name(parent_path, group_name):
    """Check if folder already exists on disk and pick a
    non-conflicting name if needed."""
    target = os.path.join(parent_path, group_name)
    if not os.path.exists(target):
        return group_name

    for i in range(2, 100):
        candidate = f"{group_name}{i}"
        if not os.path.exists(
            os.path.join(parent_path, candidate)
        ):
            print(
                f"  WARNING: Folder '{target}' already "
                f"exists on disk."
            )
            print(
                f"  Will use '{candidate}' as folder name "
                f"instead."
            )
            return candidate

    print(
        f"Error: Could not find unused folder name "
        f"for {target}"
    )
    sys.exit(1)


def parse_group_path(group_path):
    """Parse 'Classes/Intents' into parent_path and
    group_name."""
    parts = group_path.rstrip('/').split('/')
    if len(parts) < 2:
        print(
            f"Error: group_path must be in parent/group "
            f"format, e.g. 'Classes/Intents'. "
            f"Got: '{group_path}'"
        )
        sys.exit(1)

    parent_path = parts[0]
    group_name = parts[-1]
    return parent_path, group_name


def run_step(description, cmd, verbose=False):
    """Run a migration step as a subprocess.

    Quiet mode: one compact line per step.
    Verbose mode: full banner, command, and output.
    """
    if verbose:
        print()
        print("=" * 60)
        print(f"  {description}")
        print("=" * 60)
        print(f"  Command: {' '.join(cmd)}")
        print()
        result = subprocess.run(
            cmd, capture_output=False,
        )
        if result.returncode != 0:
            print()
            print(f"  FAILED: {description}")
            print(f"  Exit code: {result.returncode}")
        return result.returncode == 0

    # Quiet mode
    sys.stdout.write(f"  {description}...")
    sys.stdout.flush()

    start = time.time()
    result = subprocess.run(
        cmd, capture_output=True, text=True, timeout=300,
    )
    elapsed = time.time() - start

    if result.returncode == 0:
        print(f" OK ({elapsed:.1f}s)")
    else:
        print(f" FAILED ({elapsed:.1f}s)")
        err = result.stderr or result.stdout or ''
        for line in err.strip().split('\n')[:3]:
            if line.strip():
                print(f"    {line.strip()}")

    return result.returncode == 0


def dry_run(
    group_path, parent_path, group_name, json_path,
    script_dir, group_id=None, new_folder=False,
):
    """Run extract only and print a report."""
    print()
    print("=" * 60)
    print("  DRY RUN - no files or project will be modified")
    print("=" * 60)
    print()

    extract_cmd = [
        sys.executable,
        os.path.join(
            script_dir, "extract_target_memberships.py",
        ),
        group_name,
        PBXPROJ_PATH,
        "--parent-path", parent_path,
    ]
    if group_id:
        extract_cmd += ["--group-id", group_id]
    if not run_step(
        "Extract target memberships (read-only)",
        extract_cmd, verbose=True,
    ):
        sys.exit(1)

    if not os.path.exists(json_path):
        print(f"Error: Expected JSON not found: {json_path}")
        sys.exit(1)

    with open(json_path, 'r', encoding='utf-8') as f:
        data = json.load(f)

    files = data['files']

    if new_folder:
        folder_name = resolve_folder_name(
            parent_path, group_name,
        )
    else:
        folder_name = group_name
    target_base = os.path.join(parent_path, folder_name)

    print()
    print("=" * 60)
    print("  DRY RUN REPORT")
    print("=" * 60)
    print()
    print(f"  Group:       {group_name}")
    if folder_name != group_name:
        print(f"  Folder:      {folder_name} (new folder)")
    print(f"  Group UUID:  {data['group_uuid']}")
    print(
        f"  Subgroups:   {len(data['group_uuids']) - 1}"
    )
    print(f"  Total files: {len(files)}")
    print()

    # File moves
    print("-" * 60)
    print("  FILE MOVES (git mv)")
    print("-" * 60)
    print()
    moves = 0
    skips = 0
    missing = 0
    for relative_path, fdata in files.items():
        src = fdata['disk_path']
        dst = os.path.join(target_base, relative_path)
        if os.path.abspath(src) == os.path.abspath(dst):
            skips += 1
            continue
        exists = os.path.exists(src)
        if not exists:
            tag = " [MISSING]"
            missing += 1
        else:
            tag = ""
            moves += 1
        print(f"  {src}{tag}")
        print(f"    -> {dst}")
        print()

    print(f"  Will move:    {moves} files")
    if skips:
        print(f"  Already there: {skips} files")
    if missing:
        print(f"  MISSING:       {missing} files")
    print()

    # Target membership
    print("-" * 60)
    print("  TARGET MEMBERSHIP")
    print("-" * 60)
    print()

    target_set_groups = defaultdict(list)
    for relative_path, fdata in files.items():
        key = (
            tuple(sorted(fdata['targets']))
            if fdata['targets'] else ()
        )
        target_set_groups[key].append(relative_path)

    for target_set, fpaths in sorted(
        target_set_groups.items(),
        key=lambda x: (-len(x[1]), x[0]),
    ):
        if target_set:
            label = ", ".join(target_set)
        else:
            label = "(no targets - header only)"
        print(f"  [{label}]")
        for fp in sorted(fpaths):
            print(f"    {fp}")
        print()

    # Exceptions
    print("-" * 60)
    print("  EXCEPTIONS (files excluded per target)")
    print("-" * 60)
    print()

    for target_name in ALL_TARGETS:
        excluded = []
        for relative_path, fdata in files.items():
            if target_name not in fdata['targets']:
                excluded.append(relative_path)
        if excluded:
            print(
                f"  {target_name}: "
                f"{len(excluded)} exclusions"
            )
            for fp in sorted(excluded):
                print(f"    - {fp}")
            print()
        else:
            print(
                f"  {target_name}: no exclusions "
                f"(all files included)"
            )
            print()

    # pbxproj changes
    print("-" * 60)
    print("  PBXPROJ CHANGES")
    print("-" * 60)
    print()

    bf_count = sum(
        len(fdata.get('build_files', {}))
        for fdata in files.values()
    )
    print(f"  Will remove:")
    print(f"    {bf_count} PBXBuildFile entries")
    print(f"    {bf_count} build phase references")
    print(f"    {len(files)} PBXFileReference entries")
    print(
        f"    {len(data['group_uuids'])} PBXGroup entries"
    )
    print()
    print(f"  Will add:")
    exc_count = sum(
        1 for t in ALL_TARGETS
        if any(
            t not in fdata['targets']
            for fdata in files.values()
        )
    )
    print(f"    1 PBXFileSystemSynchronizedRootGroup")
    print(
        f"    {exc_count} "
        f"PBXFileSystemSynchronizedBuildFileExceptionSet"
    )
    print()

    nested_synced = data.get('nested_synced_groups', [])
    if nested_synced:
        print("-" * 60)
        print(
            "  NESTED SYNCED FOLDERS "
            "(will be absorbed)"
        )
        print("-" * 60)
        print()
        for sg in nested_synced:
            targets_str = ', '.join(sg['targets'])
            print(
                f"  {sg['name']} ({sg['uuid']})"
            )
            print(f"    Targets: {targets_str}")
        print()

    if os.path.isdir(target_base):
        suspicious = find_suspicious_items(
            target_base, files,
        )
        report_suspicious(target_base, suspicious)


def execute(
    group_path, parent_path, group_name, json_path,
    script_dir, group_id=None, new_folder=False,
    verbose=False,
):
    """Run the full migration."""

    # Step 1: Extract target memberships
    extract_cmd = [
        sys.executable,
        os.path.join(
            script_dir, "extract_target_memberships.py",
        ),
        group_name,
        PBXPROJ_PATH,
        "--parent-path", parent_path,
    ]
    if group_id:
        extract_cmd += ["--group-id", group_id]
    if not run_step(
        "Extract memberships", extract_cmd, verbose,
    ):
        sys.exit(1)

    if not os.path.exists(json_path):
        print(f"Error: Expected JSON not found: {json_path}")
        sys.exit(1)

    if new_folder:
        folder_name = resolve_folder_name(
            parent_path, group_name,
        )
    else:
        folder_name = group_name

    # Step 2: Move files on disk
    move_cmd = [
        sys.executable,
        os.path.join(
            script_dir, "move_files_to_group_structure.py",
        ),
        json_path,
    ]
    if folder_name != group_name:
        move_cmd += ["--folder-name", folder_name]
    if not run_step("Move files", move_cmd, verbose):
        sys.exit(1)

    # Step 3: Remove old group from pbxproj
    remove_cmd = [
        sys.executable,
        os.path.join(script_dir, "remove_old_group.py"),
        json_path,
        PBXPROJ_PATH,
    ]
    if not run_step(
        "Remove group from project", remove_cmd, verbose,
    ):
        sys.exit(1)

    # Step 4: Add filesystem synchronized group
    restore_cmd = [
        sys.executable,
        os.path.join(
            script_dir, "restore_target_memberships.py",
        ),
        json_path,
        PBXPROJ_PATH,
        group_name,
    ]
    if folder_name != group_name:
        restore_cmd += ["--folder-path", folder_name]
    if not run_step(
        "Add folder to project", restore_cmd, verbose,
    ):
        sys.exit(1)

    # Step 5: Validate and fix target memberships
    validate_cmd = [
        sys.executable,
        os.path.join(
            script_dir, "validate_memberships.py",
        ),
        "--fix", json_path,
        PBXPROJ_PATH,
    ]
    if not run_step(
        "Validate memberships", validate_cmd, verbose,
    ):
        sys.exit(1)

    if verbose:
        print()
        print("=" * 60)
        print("  MIGRATION COMPLETE")
        print("=" * 60)
        if folder_name != group_name:
            print(
                f"  Group '{group_name}' migrated to "
                f"folder '{folder_name}'."
            )
        else:
            print(
                f"  Group '{group_name}' migrated to "
                f"folder reference."
            )
        print()
        print("  Next steps:")
        print(
            "  1. Open Xcode and verify the folder "
            "appears correctly"
        )
        print(
            "  2. Build all targets to verify "
            "no files are missing"
        )
        print("  3. Commit with: git add -A && git commit")
        print()
    else:
        print(f"  Migration complete: {group_name}")


def restore_membership(
    folder_name, membership_path, verbose=False,
):
    """Restore target memberships for an existing synced
    folder using a membership file."""
    from restore_target_memberships import (
        restore_membership_for_folder,
    )

    if verbose:
        print()
        print("=" * 60)
        print("  Restore Target Memberships")
        print("=" * 60)
        print(f"  Folder:      {folder_name}")
        print(f"  Membership:  {membership_path}")
        print(f"  Project:     {PBXPROJ_PATH}")
        print()

    if not os.path.exists(membership_path):
        print(f"Error: File not found: {membership_path}")
        sys.exit(1)

    if not verbose:
        sys.stdout.write("  Restore memberships...")
        sys.stdout.flush()

    start = time.time()
    success = restore_membership_for_folder(
        membership_path, PBXPROJ_PATH, folder_name,
    )
    elapsed = time.time() - start

    if success:
        if verbose:
            print("=" * 60)
            print("  MEMBERSHIP RESTORE COMPLETE")
            print("=" * 60)
            print()
            print("  Next steps:")
            print(
                "  1. Open Xcode and verify "
                "target memberships"
            )
            print(
                "  2. Build all targets to verify "
                "no files are missing"
            )
            print()
        else:
            print(f" OK ({elapsed:.1f}s)")
    else:
        if verbose:
            print("Error: Failed to restore memberships")
        else:
            print(f" FAILED ({elapsed:.1f}s)")
        sys.exit(1)


def main():
    args = sys.argv[1:]
    is_dry_run = False
    verbose = False
    group_id = None
    new_folder = False
    membership_file = None

    if '--dry-run' in args:
        is_dry_run = True
        args.remove('--dry-run')

    if '--verbose' in args:
        verbose = True
        args.remove('--verbose')

    if '--new-folder' in args:
        new_folder = True
        args.remove('--new-folder')

    if '--group-id' in args:
        idx = args.index('--group-id')
        if idx + 1 >= len(args):
            print("Error: --group-id requires a value")
            sys.exit(1)
        group_id = args[idx + 1]
        args = args[:idx] + args[idx + 2:]

    if '--restore-membership' in args:
        idx = args.index('--restore-membership')
        if idx + 1 >= len(args):
            print(
                "Error: --restore-membership "
                "requires a file path"
            )
            sys.exit(1)
        membership_file = args[idx + 1]
        args = args[:idx] + args[idx + 2:]

    if membership_file:
        if len(args) != 1:
            print(
                "Usage: python migrate_group.py "
                "--restore-membership "
                "<membership.json> <folder_name>"
            )
            print()
            print(
                "  folder_name:  Name of the synced "
                "folder in Xcode project"
            )
            print(
                "  membership:   JSON file mapping "
                "file -> [targets]"
            )
            print()
            print("Example:")
            print(
                "  python migrate_group.py "
                "--restore-membership \\\n"
                "    /tmp/xcode_membership_Statistics"
                ".json Statistics"
            )
            sys.exit(1)
        restore_membership(
            args[0], membership_file, verbose,
        )
        return

    if len(args) != 1:
        print(
            "Usage: python migrate_group.py [options] "
            "<group_path>"
        )
        print()
        print("Options:")
        print(
            "  --verbose      Show full output "
            "from each step"
        )
        print(
            "  --dry-run      Extract and print report "
            "only,"
        )
        print(
            "                 do not modify files or "
            "project"
        )
        print(
            "  --group-id ID  Group UUID (to disambiguate "
            "groups with same name)"
        )
        print(
            "  --new-folder   Create a new folder if one "
            "with the same name"
        )
        print(
            "                 already exists (appends a "
            "number suffix)"
        )
        print(
            "  --restore-membership <file>"
        )
        print(
            "                 Restore target memberships "
            "for an existing"
        )
        print(
            "                 synced folder using a "
            "membership file"
        )
        print()
        print("Examples:")
        print(
            "  python migrate_group.py "
            "\"Classes/Intents\""
        )
        print(
            "  python migrate_group.py --verbose "
            "\"Classes/Intents\""
        )
        print(
            "  python migrate_group.py --dry-run "
            "\"Classes/Intents\""
        )
        print(
            "  python migrate_group.py "
            "--group-id ABC123DEF456... "
            "\"Classes/iCloud\""
        )
        print(
            "  python migrate_group.py "
            "--restore-membership \\\n"
            "    /tmp/xcode_membership_Stats.json "
            "Statistics"
        )
        sys.exit(1)

    group_path = args[0]
    parent_path, group_name = parse_group_path(group_path)

    safe_name = (
        group_name.replace('/', '_').replace(' ', '_')
    )
    json_path = (
        f"/tmp/xcode_target_memberships_{safe_name}.json"
    )

    script_dir = os.path.dirname(os.path.abspath(__file__))

    if verbose or is_dry_run:
        print()
        print("=" * 60)
        mode = (
            "DRY RUN" if is_dry_run
            else "Xcode Group Migration"
        )
        print(f"  {mode}")
        print("=" * 60)
        print(f"  Group path:   {group_path}")
        print(f"  Parent:       {parent_path}")
        print(f"  Group name:   {group_name}")
        if group_id:
            print(f"  Group ID:     {group_id}")
        if new_folder:
            print(f"  New folder:   yes")
        print(f"  Project:      {PBXPROJ_PATH}")
        print(f"  JSON output:  {json_path}")
        print()
    else:
        print(f"Migrating: {group_name}")

    if is_dry_run:
        dry_run(
            group_path, parent_path, group_name,
            json_path, script_dir, group_id, new_folder,
        )
    else:
        execute(
            group_path, parent_path, group_name,
            json_path, script_dir, group_id, new_folder,
            verbose,
        )


if __name__ == '__main__':
    main()