agent-wiki-cli 0.3.28__py3-none-any.whl

llm_wiki_cli/commands/migrate_cmd.py

@@ -0,0 +1,892 @@
+"""Legacy wiki migration command.
+
+`llm-wiki migrate` reconciles pages generated by older llm-wiki versions with
+the current collision-aware naming rules.  Active canonical pages are
+regenerated from source, old active pages are archived, and previous page
+content is preserved under a Legacy Notes section.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .bootstrap_cmd import (
+    _build_relationships,
+    _generate_docker_md,
+    _generate_entity_md,
+    _generate_index_md,
+    _generate_module_md,
+    build_entity_page_map,
+    build_module_page_map,
+)
+from .extract_cmd import get_docker_inventory, get_inventory_result, print_inventory_failures
+from .sync_cmd import MANIFEST_FILENAME, MANIFEST_VERSION, SyncManifest
+from ..config import DEFAULT_WIKI_DIR, validate_path
+from ..services.io import read_md, write_md
+from ..services.paths import normalize_source_path
+
+LEGACY_MARKER = "<!-- llm-wiki-migrate:legacy-notes -->"
+_MANAGED_DIRS = ("entities", "modules", "infrastructure")
+_LINK_RE = re.compile(r"(\[[^\]]+\]\()([^)]+)(\))")
+_HEADING_RE = re.compile(r"^#\s+(.+?)\s*$", re.MULTILINE)
+_LOCATION_RE = re.compile(r"^\*\*Location:\*\*\s*`?(.+?)`?\s*$", re.MULTILINE)
+_PATH_RE = re.compile(r"^\*\*Path:\*\*\s*`?(.+?)`?\s*$", re.MULTILINE)
+
+
+@dataclass(frozen=True)
+class ExistingPage:
+    """A currently active wiki page before migration."""
+
+    kind: str
+    path: Path
+    rel: str
+    stem: str
+    content: str
+    heading: str | None = None
+    location_path: str | None = None
+    location_line: int | None = None
+    source_path: str | None = None
+    archived: bool = False
+
+
+@dataclass(frozen=True)
+class TargetPage:
+    """A canonical page generated from the current source inventory."""
+
+    kind: str
+    stem: str
+    rel: str
+    content: str
+    source_path: str | None = None
+    entity_name: str | None = None
+    line: int | None = None
+
+
+@dataclass
+class MigrationPlan:
+    """Computed migration operations, shared by apply and dry-run paths."""
+
+    archive_name: str
+    targets: list[TargetPage]
+    matches: dict[str, list[ExistingPage]] = field(default_factory=dict)
+    unmatched: list[ExistingPage] = field(default_factory=list)
+    link_map: dict[str, str] = field(default_factory=dict)
+    index_content: str = ""
+    manifest: SyncManifest | None = None
+
+
+@dataclass(frozen=True)
+class MigrationChunk:
+    """A bounded subset of currently pending migration work."""
+
+    number: int
+    total: int
+    targets: list[TargetPage]
+    unmatched: list[ExistingPage]
+    include_finalizers: bool = False
+
+    @property
+    def page_operations(self) -> int:
+        return len(self.targets) + len(self.unmatched)
+
+
+def _normalize_source_path(value: str | None, src_dir: str) -> str | None:
+    """Normalize extracted markdown source paths to inventory-relative paths."""
+    return normalize_source_path(value, src_dir)
+
+
+def _page_rel(path: Path, wiki_dir: Path) -> str:
+    try:
+        return path.relative_to(wiki_dir).as_posix()
+    except ValueError:
+        return path.resolve().relative_to(wiki_dir.resolve()).as_posix()
+
+
+def _legacy_gitignore_pattern(wiki_dir: Path) -> str:
+    """Return the project-root-relative gitignore pattern for legacy archives."""
+    cwd = Path.cwd().resolve()
+    try:
+        rel = wiki_dir.resolve().relative_to(cwd).as_posix()
+    except ValueError:
+        rel = wiki_dir.as_posix()
+    rel = rel.strip("/")
+    return f"{rel}/legacy/" if rel else "legacy/"
+
+
+def _gitignore_has_pattern(content: str, pattern: str) -> bool:
+    wanted = pattern.strip().lstrip("/").rstrip("/")
+    for raw_line in content.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.lstrip("/").rstrip("/") == wanted:
+            return True
+    return False
+
+
+def _legacy_gitignore_needs_write(wiki_dir: Path) -> bool:
+    gitignore = Path(".gitignore")
+    if not gitignore.exists():
+        return True
+    return not _gitignore_has_pattern(read_md(gitignore), _legacy_gitignore_pattern(wiki_dir))
+
+
+def _ensure_legacy_gitignore(wiki_dir: Path, dry_run: bool) -> bool:
+    """Ensure migration archives are ignored by git.
+
+    Returns True when a write was needed, including dry-run previews.
+    """
+    pattern = _legacy_gitignore_pattern(wiki_dir)
+    gitignore = Path(".gitignore")
+    content = read_md(gitignore) if gitignore.exists() else ""
+    if _gitignore_has_pattern(content, pattern):
+        return False
+
+    print(f"  GITIGNORE add {pattern}")
+    if dry_run:
+        return True
+
+    addition = f"# LLM Wiki migration archives\n{pattern}\n"
+    if content.strip():
+        updated = content.rstrip("\n") + "\n\n" + addition
+    else:
+        updated = addition
+    write_md(gitignore, updated)
+    return True
+
+
+def _split_location(value: str) -> tuple[str, int | None]:
+    """Split a legacy Location value into path and optional line number."""
+    location = value.strip()
+    path_part, sep, line_part = location.rpartition(":")
+    if sep and line_part.isdigit():
+        return path_part, int(line_part)
+    return location, None
+
+
+def _read_existing_page(
+    path: Path,
+    wiki_dir: Path,
+    src_dir: str,
+    *,
+    archived: bool = False,
+) -> ExistingPage:
+    content = read_md(path)
+    rel = _page_rel(path, wiki_dir)
+    kind = path.parent.name
+
+    heading_match = _HEADING_RE.search(content)
+    location_match = _LOCATION_RE.search(content)
+    path_match = _PATH_RE.search(content)
+
+    location_path: str | None = None
+    location_line: int | None = None
+    if location_match:
+        raw_location_path, location_line = _split_location(location_match.group(1))
+        location_path = _normalize_source_path(raw_location_path, src_dir)
+
+    source_path = _normalize_source_path(path_match.group(1), src_dir) if path_match else None
+
+    return ExistingPage(
+        kind=kind,
+        path=path,
+        rel=rel,
+        stem=path.stem,
+        content=content,
+        heading=heading_match.group(1).strip() if heading_match else None,
+        location_path=location_path,
+        location_line=location_line,
+        source_path=source_path,
+        archived=archived,
+    )
+
+
+def _active_managed_pages(wiki_dir: Path, src_dir: str) -> list[ExistingPage]:
+    pages: list[ExistingPage] = []
+    for dirname in _MANAGED_DIRS:
+        directory = wiki_dir / dirname
+        if not directory.exists():
+            continue
+        for path in sorted(directory.glob("*.md")):
+            if path.is_file():
+                pages.append(_read_existing_page(path, wiki_dir, src_dir))
+    return pages
+
+
+def _legacy_archive_roots(wiki_dir: Path) -> list[Path]:
+    legacy_dir = wiki_dir / "legacy"
+    if not legacy_dir.exists():
+        return []
+    return sorted(
+        (path for path in legacy_dir.glob("migrate-*") if path.is_dir()),
+        key=lambda path: path.name,
+        reverse=True,
+    )
+
+
+def _archived_managed_pages(wiki_dir: Path, src_dir: str) -> list[ExistingPage]:
+    pages: list[ExistingPage] = []
+    for archive_root in _legacy_archive_roots(wiki_dir):
+        for dirname in _MANAGED_DIRS:
+            directory = archive_root / dirname
+            if not directory.exists():
+                continue
+            for path in sorted(directory.glob("*.md")):
+                if path.is_file():
+                    pages.append(
+                        _read_existing_page(path, archive_root, src_dir, archived=True)
+                    )
+    return pages
+
+
+def _additional_doc_entries(wiki_dir: Path) -> list[str]:
+    ignored_top_level = set(_MANAGED_DIRS) | {"workflows", "legacy"}
+    docs: list[str] = []
+    if not wiki_dir.exists():
+        return docs
+
+    for path in sorted(wiki_dir.rglob("*.md")):
+        if not path.is_file() or _is_legacy_path(path, wiki_dir):
+            continue
+        rel = _page_rel(path, wiki_dir)
+        parts = Path(rel).parts
+        if path.name in {"index.md", "log.md"}:
+            continue
+        if parts and parts[0] in ignored_top_level:
+            continue
+        docs.append(rel)
+    return docs
+
+
+def _append_additional_docs_index(index_content: str, wiki_dir: Path) -> str:
+    docs = _additional_doc_entries(wiki_dir)
+    if not docs:
+        return index_content
+
+    lines = [index_content.rstrip(), "", "## Additional Docs", ""]
+    for rel in docs:
+        label = str(Path(rel).with_suffix("")).replace("\\", "/")
+        lines.append(f"- [{label}]({rel})")
+    return "\n".join(lines)
+
+
+def _build_targets(
+    wiki_dir: Path,
+    src_dir: str,
+    inventory: dict,
+    docker_inventory: dict,
+) -> tuple[list[TargetPage], str, SyncManifest]:
+    module_page_map = build_module_page_map(inventory)
+    entity_page_map = build_entity_page_map(inventory)
+    relationships = _build_relationships(inventory, module_page_map)
+
+    targets: list[TargetPage] = []
+    entity_names: list[str] = []
+    module_entries: list[dict] = []
+    infra_entries: list[dict] = []
+
+    for filepath, file_data in inventory.items():
+        module_page = module_page_map[filepath]
+        file_entity_map = {
+            cls["name"]: entity_page_map[(cls["name"], filepath)]
+            for cls in file_data.get("classes", [])
+        }
+
+        module_entries.append({
+            "name": module_page,
+            "path": filepath,
+            "docstring": file_data.get("module_docstring", ""),
+        })
+        targets.append(TargetPage(
+            kind="modules",
+            stem=module_page,
+            rel=f"modules/{module_page}.md",
+            content=_generate_module_md(filepath, file_data, file_entity_map),
+            source_path=filepath,
+        ))
+
+        for cls in file_data.get("classes", []):
+            entity_page = entity_page_map[(cls["name"], filepath)]
+            entity_names.append(entity_page)
+            targets.append(TargetPage(
+                kind="entities",
+                stem=entity_page,
+                rel=f"entities/{entity_page}.md",
+                content=_generate_entity_md(cls, filepath, relationships, module_page),
+                source_path=filepath,
+                entity_name=cls["name"],
+                line=cls.get("line"),
+            ))
+
+    for docker_file, docker_info in docker_inventory.items():
+        page_name = docker_file.replace("\\", "/").replace("/", "_").replace(".", "_")
+        infra_entries.append({"name": page_name, "type": docker_info.get("type", "")})
+        targets.append(TargetPage(
+            kind="infrastructure",
+            stem=page_name,
+            rel=f"infrastructure/{page_name}.md",
+            content=_generate_docker_md(docker_file, docker_info, module_page_map),
+            source_path=docker_file,
+        ))
+
+    workflow_entries = _list_workflows(wiki_dir)
+    index_content = _generate_index_md(
+        entity_names,
+        module_entries,
+        workflow_entries or None,
+        infra_entries or None,
+    )
+    manifest = SyncManifest.build_from_inventory(
+        inventory,
+        src_dir,
+        entity_page_map,
+        module_page_map,
+    )
+    return targets, _append_additional_docs_index(index_content, wiki_dir), manifest
+
+
+def _list_workflows(wiki_dir: Path) -> list[dict]:
+    workflow_dir = wiki_dir / "workflows"
+    if not workflow_dir.exists():
+        return []
+    return [{"name": path.stem, "entry": ""} for path in sorted(workflow_dir.glob("*.md"))]
+
+
+def _unique(values: list[TargetPage]) -> TargetPage | None:
+    return values[0] if len(values) == 1 else None
+
+
+def _build_match_lookups(targets: list[TargetPage]) -> dict[str, dict]:
+    lookups: dict[str, dict] = {
+        "by_rel": {target.rel: target for target in targets},
+        "entities_by_path_name": {},
+        "entities_by_name": {},
+        "modules_by_source": {},
+        "modules_by_source_stem": {},
+        "modules_by_page_stem": {},
+        "infra_by_source": {},
+        "infra_by_page_stem": {},
+    }
+
+    for target in targets:
+        if target.kind == "entities" and target.entity_name:
+            lookups["entities_by_path_name"].setdefault(
+                (target.source_path, target.entity_name), []
+            ).append(target)
+            lookups["entities_by_name"].setdefault(target.entity_name, []).append(target)
+        elif target.kind == "modules":
+            lookups["modules_by_source"][target.source_path] = target
+            lookups["modules_by_source_stem"].setdefault(
+                Path(target.source_path or "").stem, []
+            ).append(target)
+            lookups["modules_by_page_stem"].setdefault(target.stem, []).append(target)
+        elif target.kind == "infrastructure":
+            lookups["infra_by_source"][target.source_path] = target
+            lookups["infra_by_page_stem"].setdefault(target.stem, []).append(target)
+    return lookups
+
+
+def _match_existing_page(page: ExistingPage, lookups: dict[str, dict]) -> TargetPage | None:
+    if page.rel in lookups["by_rel"]:
+        return lookups["by_rel"][page.rel]
+
+    if page.kind == "entities":
+        name = page.heading or page.stem.rsplit("_", 1)[-1]
+        if page.location_path:
+            exact = _unique(
+                lookups["entities_by_path_name"].get((page.location_path, name), [])
+            )
+            if exact:
+                return exact
+        return _unique(lookups["entities_by_name"].get(name, []))
+
+    if page.kind == "modules":
+        if page.source_path and page.source_path in lookups["modules_by_source"]:
+            return lookups["modules_by_source"][page.source_path]
+        canonical = _unique(lookups["modules_by_page_stem"].get(page.stem, []))
+        if canonical:
+            return canonical
+        return _unique(lookups["modules_by_source_stem"].get(page.stem, []))
+
+    if page.kind == "infrastructure":
+        if page.source_path and page.source_path in lookups["infra_by_source"]:
+            return lookups["infra_by_source"][page.source_path]
+        return _unique(lookups["infra_by_page_stem"].get(page.stem, []))
+
+    return None
+
+
+def _build_migration_plan(wiki_dir: Path, src_dir: str) -> MigrationPlan:
+    inventory_result = get_inventory_result(src_dir, deep=True)
+    if inventory_result.failed:
+        print_inventory_failures(inventory_result)
+        sys.exit(1)
+    inventory = inventory_result.inventory
+    docker_inventory = get_docker_inventory(src_dir)
+    targets, index_content, manifest = _build_targets(
+        wiki_dir,
+        src_dir,
+        inventory,
+        docker_inventory,
+    )
+    lookups = _build_match_lookups(targets)
+    target_rels = {target.rel for target in targets}
+    plan = MigrationPlan(
+        archive_name=f"migrate-{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S')}",
+        targets=targets,
+        index_content=index_content,
+        manifest=manifest,
+    )
+
+    active_pages = _active_managed_pages(wiki_dir, src_dir)
+    active_rels = {page.rel for page in active_pages}
+
+    for page in active_pages:
+        target = _match_existing_page(page, lookups)
+        if target:
+            plan.matches.setdefault(target.rel, []).append(page)
+            if page.rel != target.rel:
+                plan.link_map[page.rel] = target.rel
+        elif page.rel not in target_rels:
+            plan.unmatched.append(page)
+            plan.link_map.setdefault(page.rel, f"legacy/{plan.archive_name}/{page.rel}")
+
+    for page in _archived_managed_pages(wiki_dir, src_dir):
+        if page.rel in active_rels:
+            continue
+        target = _match_existing_page(page, lookups)
+        if target:
+            plan.matches.setdefault(target.rel, []).append(page)
+            if page.rel != target.rel:
+                plan.link_map.setdefault(page.rel, target.rel)
+        else:
+            archive_rel = _page_rel(page.path, wiki_dir)
+            plan.link_map.setdefault(page.rel, archive_rel)
+
+    return plan
+
+
+def _existing_legacy_payload(page: ExistingPage, generated_content: str) -> str:
+    content = page.content.strip()
+    if not content or content == generated_content.strip():
+        return ""
+    if LEGACY_MARKER in page.content:
+        return page.content.split(LEGACY_MARKER, 1)[1].strip()
+    return content
+
+
+def _split_legacy_sections(payload: str) -> list[str]:
+    payload = payload.strip()
+    if not payload:
+        return []
+    if not payload.startswith("### From "):
+        return [payload]
+    return [
+        section.strip()
+        for section in re.split(r"(?=^### From )", payload, flags=re.MULTILINE)
+        if section.strip()
+    ]
+
+
+def _merge_legacy_notes(target: TargetPage, pages: list[ExistingPage]) -> str:
+    sections: list[str] = []
+    seen_sections: set[str] = set()
+    for page in pages:
+        payload = _existing_legacy_payload(page, target.content)
+        if not payload:
+            continue
+        if payload.startswith("### From "):
+            candidates = _split_legacy_sections(payload)
+        else:
+            candidates = [f"### From `{page.rel}`\n\n{payload}"]
+        for section in candidates:
+            normalized = section.strip()
+            if normalized in seen_sections:
+                continue
+            seen_sections.add(normalized)
+            sections.append(normalized)
+
+    if not sections:
+        return target.content
+
+    return (
+        target.content.rstrip()
+        + "\n\n## Legacy Notes\n\n"
+        + LEGACY_MARKER
+        + "\n\n"
+        + "\n\n".join(sections).rstrip()
+        + "\n"
+    )
+
+
+def _archive_page(page: ExistingPage, wiki_dir: Path, archive_root: Path, dry_run: bool) -> None:
+    dest = archive_root / page.rel
+    print(f"  ARCHIVE {page.rel} -> {_page_rel(dest, wiki_dir)}")
+    if dry_run:
+        return
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    write_md(dest, page.content)
+
+
+def _remove_old_page(page: ExistingPage, dry_run: bool) -> None:
+    if dry_run:
+        return
+    page.path.unlink(missing_ok=True)
+
+
+def _write_page(wiki_dir: Path, rel: str, content: str, dry_run: bool) -> None:
+    path = wiki_dir / rel
+    if path.exists() and read_md(path) == content:
+        print(f"  SKIP unchanged {rel}")
+        return
+
+    print(f"  WRITE {rel}")
+    if dry_run:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_md(path, content)
+
+
+def _is_legacy_path(path: Path, wiki_dir: Path) -> bool:
+    try:
+        return path.relative_to(wiki_dir).parts[:1] == ("legacy",)
+    except ValueError:
+        try:
+            return path.resolve().relative_to(wiki_dir.resolve()).parts[:1] == ("legacy",)
+        except ValueError:
+            return False
+
+
+def _active_markdown_pages(wiki_dir: Path) -> list[Path]:
+    if not wiki_dir.exists():
+        return []
+    return [
+        path for path in sorted(wiki_dir.rglob("*.md"))
+        if path.is_file() and not _is_legacy_path(path, wiki_dir)
+    ]
+
+
+def _rewrite_links_in_content(content: str, page: Path, wiki_dir: Path, link_map: dict[str, str]) -> str:
+    if not link_map:
+        return content
+    wiki_root = wiki_dir.resolve()
+
+    def replace(match: re.Match[str]) -> str:
+        prefix, url, suffix = match.groups()
+        if url.startswith(("http://", "https://", "mailto:", "#")):
+            return match.group(0)
+
+        base_url, sep, anchor = url.partition("#")
+        if not base_url:
+            return match.group(0)
+
+        try:
+            target = (page.parent / base_url).resolve()
+            old_rel = target.relative_to(wiki_root).as_posix()
+        except ValueError:
+            return match.group(0)
+
+        new_rel = link_map.get(old_rel)
+        if not new_rel:
+            return match.group(0)
+
+        try:
+            relative = os.path.relpath(wiki_dir / new_rel, start=page.parent).replace(os.sep, "/")
+        except ValueError:
+            return match.group(0)
+        if sep:
+            relative += f"#{anchor}"
+        return f"{prefix}{relative}{suffix}"
+
+    return _LINK_RE.sub(replace, content)
+
+
+def _rewrite_active_links(wiki_dir: Path, link_map: dict[str, str], dry_run: bool) -> int:
+    rewritten = 0
+    for page in _active_markdown_pages(wiki_dir):
+        content = read_md(page)
+        updated = _rewrite_links_in_content(content, page, wiki_dir, link_map)
+        if updated != content:
+            rewritten += 1
+            print(f"  REWRITE links: {_page_rel(page, wiki_dir)}")
+            if not dry_run:
+                write_md(page, updated)
+    return rewritten
+
+
+def _should_archive_matched_page(page: ExistingPage, target: TargetPage) -> bool:
+    if page.archived:
+        return False
+    if page.rel != target.rel:
+        return True
+    if LEGACY_MARKER in page.content:
+        return False
+    return bool(_existing_legacy_payload(page, target.content))
+
+
+def _matched_archive_count(plan: MigrationPlan) -> int:
+    count = 0
+    targets_by_rel = {target.rel: target for target in plan.targets}
+    for target_rel, pages in plan.matches.items():
+        target = targets_by_rel[target_rel]
+        count += sum(1 for page in pages if _should_archive_matched_page(page, target))
+    return count
+
+
+def _target_needs_apply(wiki_dir: Path, target: TargetPage, matched_pages: list[ExistingPage]) -> bool:
+    if any(_should_archive_matched_page(page, target) for page in matched_pages):
+        return True
+    if any(not page.archived and page.rel != target.rel and page.path.exists() for page in matched_pages):
+        return True
+
+    path = wiki_dir / target.rel
+    content = _merge_legacy_notes(target, matched_pages)
+    return not path.exists() or read_md(path) != content
+
+
+def _manifest_payload(manifest: SyncManifest) -> str:
+    return json.dumps(
+        {"version": MANIFEST_VERSION, "sources": manifest.sources},
+        indent=2,
+        sort_keys=True,
+    )
+
+
+def _manifest_needs_write(wiki_dir: Path, manifest: SyncManifest | None) -> bool:
+    if manifest is None:
+        return False
+    path = wiki_dir / MANIFEST_FILENAME
+    return not path.exists() or path.read_text(encoding="utf-8") != _manifest_payload(manifest)
+
+
+def _pending_link_rewrite_count(wiki_dir: Path, link_map: dict[str, str]) -> int:
+    if not link_map:
+        return 0
+    count = 0
+    for page in _active_markdown_pages(wiki_dir):
+        content = read_md(page)
+        if _rewrite_links_in_content(content, page, wiki_dir, link_map) != content:
+            count += 1
+    return count
+
+
+def _finalizers_pending(wiki_dir: Path, plan: MigrationPlan) -> bool:
+    index_path = wiki_dir / "index.md"
+    index_pending = not index_path.exists() or read_md(index_path) != plan.index_content
+    return (
+        index_pending
+        or _manifest_needs_write(wiki_dir, plan.manifest)
+        or _pending_link_rewrite_count(wiki_dir, plan.link_map) > 0
+        or (_legacy_archive_ignore_applicable(wiki_dir, plan) and _legacy_gitignore_needs_write(wiki_dir))
+    )
+
+
+def _pending_targets(wiki_dir: Path, plan: MigrationPlan) -> list[TargetPage]:
+    return [
+        target
+        for target in plan.targets
+        if _target_needs_apply(wiki_dir, target, plan.matches.get(target.rel, []))
+    ]
+
+
+def _build_chunks(wiki_dir: Path, plan: MigrationPlan, chunk_size: int) -> list[MigrationChunk]:
+    if chunk_size < 1:
+        raise ValueError("--chunk-size must be greater than zero")
+
+    units: list[tuple[str, TargetPage | ExistingPage]] = [
+        ("target", target) for target in _pending_targets(wiki_dir, plan)
+    ]
+    units.extend(("unmatched", page) for page in plan.unmatched if page.path.exists())
+
+    finalizers_pending = _finalizers_pending(wiki_dir, plan)
+    if not units:
+        if not finalizers_pending:
+            return []
+        return [MigrationChunk(1, 1, [], [], include_finalizers=True)]
+
+    total = (len(units) + chunk_size - 1) // chunk_size
+    chunks: list[MigrationChunk] = []
+    for index in range(total):
+        page_units = units[index * chunk_size:(index + 1) * chunk_size]
+        targets = [unit for kind, unit in page_units if kind == "target"]
+        unmatched = [unit for kind, unit in page_units if kind == "unmatched"]
+        chunks.append(MigrationChunk(
+            number=index + 1,
+            total=total,
+            targets=targets,
+            unmatched=unmatched,
+            include_finalizers=finalizers_pending and index == total - 1,
+        ))
+    return chunks
+
+
+def _chunk_link_map(plan: MigrationPlan, chunk: MigrationChunk) -> dict[str, str]:
+    if chunk.include_finalizers:
+        return plan.link_map
+
+    rels: set[str] = {page.rel for page in chunk.unmatched}
+    for target in chunk.targets:
+        rels.update(page.rel for page in plan.matches.get(target.rel, []))
+    return {
+        old_rel: new_rel
+        for old_rel, new_rel in plan.link_map.items()
+        if old_rel in rels
+    }
+
+
+def _planned_archive_count(plan: MigrationPlan) -> int:
+    return _matched_archive_count(plan) + len(plan.unmatched)
+
+
+def _legacy_archive_ignore_applicable(wiki_dir: Path, plan: MigrationPlan) -> bool:
+    return bool(_legacy_archive_roots(wiki_dir)) or _planned_archive_count(plan) > 0
+
+
+def _chunk_has_archive_work(plan: MigrationPlan, chunk: MigrationChunk) -> bool:
+    if chunk.unmatched:
+        return True
+    for target in chunk.targets:
+        if any(
+            _should_archive_matched_page(page, target)
+            for page in plan.matches.get(target.rel, [])
+        ):
+            return True
+    return False
+
+
+def _print_chunk_plan(chunks: list[MigrationChunk], chunk_size: int) -> None:
+    print(f"\nMigration chunk plan (max {chunk_size} pending page operation(s) per chunk):")
+    if not chunks:
+        print("  No pending migration changes.")
+        return
+
+    for chunk in chunks:
+        finalizers = " + final index/link/manifest refresh" if chunk.include_finalizers else ""
+        print(
+            f"  {chunk.number}/{chunk.total}: "
+            f"{len(chunk.targets)} canonical page(s), "
+            f"{len(chunk.unmatched)} unmatched archive(s)"
+            f"{finalizers}"
+        )
+
+
+def _apply_chunk(wiki_dir: Path, plan: MigrationPlan, chunk: MigrationChunk, dry_run: bool) -> None:
+    archive_root = wiki_dir / "legacy" / plan.archive_name
+    if _chunk_has_archive_work(plan, chunk) or (
+        chunk.include_finalizers and _legacy_archive_ignore_applicable(wiki_dir, plan)
+    ):
+        _ensure_legacy_gitignore(wiki_dir, dry_run)
+
+    for target in chunk.targets:
+        matched_pages = plan.matches.get(target.rel, [])
+        for page in matched_pages:
+            if not _should_archive_matched_page(page, target):
+                continue
+            _archive_page(page, wiki_dir, archive_root, dry_run)
+            if page.rel != target.rel:
+                _remove_old_page(page, dry_run)
+        _write_page(wiki_dir, target.rel, _merge_legacy_notes(target, matched_pages), dry_run)
+
+    for page in chunk.unmatched:
+        _archive_page(page, wiki_dir, archive_root, dry_run)
+        _remove_old_page(page, dry_run)
+        print(f"  UNMATCHED archived: {page.rel}")
+
+    if chunk.include_finalizers:
+        _write_page(wiki_dir, "index.md", plan.index_content, dry_run)
+    else:
+        print("  DEFER index/manifest refresh until the final chunk")
+
+    link_map = _chunk_link_map(plan, chunk)
+    rewritten = _rewrite_active_links(wiki_dir, link_map, dry_run)
+    if link_map:
+        print(f"  Link mappings: {len(link_map)} path(s); pages rewritten: {rewritten}")
+
+    if chunk.include_finalizers and not dry_run and plan.manifest is not None:
+        plan.manifest.save(wiki_dir)
+        print(f"  WRITE {wiki_dir / '.llm-wiki-manifest.json'}")
+    elif chunk.include_finalizers and dry_run:
+        print("  DRY-RUN: manifest refresh skipped")
+
+
+def _apply_plan(wiki_dir: Path, plan: MigrationPlan, dry_run: bool) -> None:
+    chunk = MigrationChunk(
+        number=1,
+        total=1,
+        targets=plan.targets,
+        unmatched=plan.unmatched,
+        include_finalizers=True,
+    )
+    _apply_chunk(wiki_dir, plan, chunk, dry_run)
+
+
+def run(args) -> None:
+    src_dir = getattr(args, "src_dir", ".")
+    wiki_dir = Path(getattr(args, "wiki_dir", DEFAULT_WIKI_DIR))
+    dry_run = getattr(args, "dry_run", False)
+    chunk_size = getattr(args, "chunk_size", None)
+    chunk_number = getattr(args, "chunk", None)
+    plan_chunks = getattr(args, "plan_chunks", False)
+    validate_path(src_dir, "--src-dir")
+    validate_path(str(wiki_dir), "--wiki-dir")
+
+    if chunk_size is None and (chunk_number is not None or plan_chunks):
+        print("Error: --chunk and --plan-chunks require --chunk-size.", file=sys.stderr)
+        sys.exit(1)
+
+    if not wiki_dir.exists():
+        print(f"Error: Directory {wiki_dir} does not exist.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"{'Planning' if dry_run else 'Migrating'} wiki at: {wiki_dir}")
+    print(f"Source directory: {src_dir}")
+
+    plan = _build_migration_plan(wiki_dir, src_dir)
+    if dry_run:
+        print("DRY-RUN: no files will be modified.")
+
+    if chunk_size is not None:
+        chunks = _build_chunks(wiki_dir, plan, chunk_size)
+        _print_chunk_plan(chunks, chunk_size)
+
+        if plan_chunks or (dry_run and chunk_number is None):
+            print("PLAN: no files modified.")
+            return
+
+        if not chunks:
+            print("\nNo pending migration changes.")
+            return
+
+        selected_number = chunk_number or 1
+        if selected_number < 1 or selected_number > len(chunks):
+            print(
+                f"Error: --chunk must be between 1 and {len(chunks)} for the current plan.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        chunk = chunks[selected_number - 1]
+        print(f"\nApplying migration chunk {chunk.number}/{chunk.total}:")
+        _apply_chunk(wiki_dir, plan, chunk, dry_run)
+        print(
+            "\nMigration chunk complete: "
+            f"{chunk.page_operations} page operation(s)."
+        )
+        if not chunk.include_finalizers:
+            print("Run chunked migrate again after reviewing or committing this chunk.")
+        return
+
+    _apply_plan(wiki_dir, plan, dry_run)
+
+    print(
+        "\nMigration complete: "
+        f"{len(plan.targets)} canonical page(s), "
+        f"{_matched_archive_count(plan)} archived source page(s), "
+        f"{len(plan.unmatched)} unmatched archived page(s)."
+    )