migration: close candidate maintenance audit

app/tools/build_preservation_manifest.py

@@ -1,14 +1,13 @@
 from __future__ import annotations
 
+import argparse
 import hashlib
 import json
 from datetime import datetime
 from pathlib import Path
 
 
-ROOT = Path(__file__).resolve().parents[1]
-TARGET = ROOT / "app"
-OUTPUT = ROOT / "docs" / "migration" / "原版资产清单.json"
+REPOSITORY_ROOT = Path(__file__).resolve().parents[2]
 
 DIRECTORIES = (
     "backend",
@@ -69,33 +68,57 @@ def digest(path: Path) -> str:
     return checksum.hexdigest()
 
 
-def source_files() -> list[Path]:
-    files = [ROOT / name for name in ROOT_FILES]
+def display_path(path: Path, base: Path) -> str:
+    try:
+        return path.relative_to(base).as_posix() or "."
+    except ValueError:
+        return path.as_posix()
+
+
+def source_files(source_root: Path) -> list[Path]:
+    files = [source_root / name for name in ROOT_FILES]
     for directory in DIRECTORIES:
+        root = source_root / directory
+        if not root.is_dir():
+            continue
         files.extend(
             path
-            for path in (ROOT / directory).rglob("*")
+            for path in root.rglob("*")
             if path.is_file() and "__pycache__" not in path.parts
         )
-    return sorted(set(files), key=lambda path: path.relative_to(ROOT).as_posix())
+    return sorted(
+        set(files), key=lambda path: path.relative_to(source_root).as_posix()
+    )
 
 
-def build_manifest() -> dict[str, object]:
+def build_manifest(
+    source_root: Path,
+    target_root: Path,
+    source_commit: str,
+) -> dict[str, object]:
     assets = []
     mismatches = []
-    for source in source_files():
-        relative = source.relative_to(ROOT)
-        target = TARGET / relative
-        source_hash = digest(source)
+    for source in source_files(source_root):
+        relative = source.relative_to(source_root)
+        target = target_root / relative
+        source_exists = source.is_file()
+        source_hash = digest(source) if source_exists else ""
         target_hash = digest(target) if target.is_file() else ""
-        status = "identical" if source_hash == target_hash else "mismatch"
+        if not source_exists:
+            status = "missing_source"
+        elif not target.is_file():
+            status = "missing_target"
+        elif source_hash == target_hash:
+            status = "identical"
+        else:
+            status = "mismatch"
         if status != "identical":
             mismatches.append(relative.as_posix())
         assets.append(
             {
                 "source": relative.as_posix(),
-                "target": f"app/{relative.as_posix()}",
-                "bytes": source.stat().st_size,
+                "target": display_path(target, REPOSITORY_ROOT),
+                "bytes": source.stat().st_size if source_exists else 0,
                 "sha256": source_hash,
                 "disposition": "original_copy_pending_move",
                 "status": status,
@@ -104,9 +127,9 @@ def build_manifest() -> dict[str, object]:
     return {
         "schema_version": 1,
         "generated_at": datetime.now().astimezone().isoformat(timespec="seconds"),
-        "source_commit": "41329943c4878fc09ed82ec376eb93ab151e4092",
-        "source_root": ".",
-        "target_root": "app",
+        "source_commit": source_commit,
+        "source_root": display_path(source_root, REPOSITORY_ROOT),
+        "target_root": display_path(target_root, REPOSITORY_ROOT),
         "excluded": [
             "next/",
             "data/review.db and SQLite sidecars",
@@ -123,14 +146,34 @@ def build_manifest() -> dict[str, object]:
 
 
 def main() -> int:
-    manifest = build_manifest()
-    OUTPUT.write_text(
+    parser = argparse.ArgumentParser(
+        description=(
+            "Build an exact-copy manifest for a preservation migration stage. "
+            "This is a migration-only tool; it does not describe the final moved layout."
+        )
+    )
+    parser.add_argument("--source-root", type=Path, default=REPOSITORY_ROOT)
+    parser.add_argument("--target-root", type=Path, default=REPOSITORY_ROOT / "app")
+    parser.add_argument("--source-commit", default="")
+    parser.add_argument(
+        "--output",
+        type=Path,
+        required=True,
+        help="write to a new audit path; do not overwrite committed slice evidence",
+    )
+    args = parser.parse_args()
+    source_root = args.source_root.resolve()
+    target_root = args.target_root.resolve()
+    output = args.output.resolve()
+    manifest = build_manifest(source_root, target_root, args.source_commit)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(
         json.dumps(manifest, ensure_ascii=False, indent=2) + "\n",
         encoding="utf-8",
     )
     print(
         f"assets={manifest['asset_count']} mismatches={manifest['mismatch_count']} "
-        f"output={OUTPUT}"
+        f"output={output}"
     )
     return 1 if manifest["mismatch_count"] else 0