File tree diff

readthedocs/filetreediff/__init__.py

@@ -0,0 +1,84 @@
+import json
+from dataclasses import dataclass
+
+from readthedocs.builds.constants import BUILD_STATE_FINISHED
+from readthedocs.builds.models import Version
+from readthedocs.projects.constants import MEDIA_TYPE_METADATA
+from readthedocs.storage import build_media_storage
+
+
+@dataclass
+class FileTreeDiff:
+    added: list[str]
+    removed: list[str]
+    modified: list[str]
+
+
+def get_diff(version_a: Version, version_b: Version) -> FileTreeDiff | None:
+    version_a_manifest = get_manifest(version_a)
+    version_b_manifest = get_manifest(version_b)
+
+    if not version_a_manifest or not version_b_manifest:
+        return None
+
+    files_a = set(version_a_manifest.get("files", {}).keys())
+    files_b = set(version_b_manifest.get("files", {}).keys())
+
+    files_added = list(files_a - files_b)
+    files_removed = list(files_b - files_a)
+    files_modified = []
+    for file_path in files_a & files_b:
+        file_a = version_a_manifest["files"][file_path]
+        file_b = version_b_manifest["files"][file_path]
+
+        if file_a["hash"] != file_b["hash"]:
+            files_modified.append(file_path)
+
+    return FileTreeDiff(
+        added=files_added,
+        removed=files_removed,
+        modified=files_modified,
+    )
+
+
+def get_manifest(version: Version):
+    storage_path = version.project.get_storage_path(
+        type_=MEDIA_TYPE_METADATA,
+        version_slug=version.slug,
+        include_file=False,
+        version_type=version.type,
+    )
+    manifest_path = build_media_storage.join(storage_path, "manifest.json")
+    try:
+        with build_media_storage.open(manifest_path) as manifest_file:
+            manifest = json.load(manifest_file)
+    except FileNotFoundError:
+        return None
+
+    latest_successful_build = version.builds.filter(
+        state=BUILD_STATE_FINISHED,
+        success=True,
+    ).first()
+    if not latest_successful_build:
+        return None
+
+    build_id_from_manifest = manifest.get("build", {}).get("id")
+    if latest_successful_build.id != build_id_from_manifest:
+        # The manifest is outdated,
+        # do we want to still use it? do we care?
+        # Should the caller be responsible to handle this?
+        return None
+
+    return manifest
+
+
+def write_manifest(version: Version, manifest: dict):
+    storage_path = version.project.get_storage_path(
+        type_=MEDIA_TYPE_METADATA,
+        version_slug=version.slug,
+        include_file=False,
+        version_type=version.type,
+    )
+    manifest_path = build_media_storage.join(storage_path, "manifest.json")
+    with build_media_storage.open(manifest_path, "w") as f:
+        json.dump(manifest, f)

readthedocs/projects/constants.py

@@ -34,6 +34,7 @@
 MEDIA_TYPE_EPUB = "epub"
 MEDIA_TYPE_HTMLZIP = "htmlzip"
 MEDIA_TYPE_JSON = "json"
+MEDIA_TYPE_METADATA = "metadata"
 DOWNLOADABLE_MEDIA_TYPES = (
     MEDIA_TYPE_PDF,
     MEDIA_TYPE_EPUB,
@@ -45,6 +46,7 @@
     MEDIA_TYPE_EPUB,
     MEDIA_TYPE_HTMLZIP,
     MEDIA_TYPE_JSON,
+    MEDIA_TYPE_METADATA,
 )
 
 BUILD_COMMANDS_OUTPUT_PATH = "_readthedocs/"

readthedocs/projects/models.py

@@ -1887,6 +1887,7 @@ def add_features(sender, **kwargs):
     RESOLVE_PROJECT_FROM_HEADER = "resolve_project_from_header"
     USE_PROXIED_APIS_WITH_PREFIX = "use_proxied_apis_with_prefix"
     ALLOW_VERSION_WARNING_BANNER = "allow_version_warning_banner"
+    GENERATE_MANIFEST_FOR_FILE_TREE_DIFF = "generate_manifest_for_file_tree_diff"
 
     # Versions sync related features
     SKIP_SYNC_TAGS = "skip_sync_tags"
@@ -1947,6 +1948,10 @@ def add_features(sender, **kwargs):
             ALLOW_VERSION_WARNING_BANNER,
             _("Dashboard: Allow project to use the version warning banner."),
         ),
+        (
+            GENERATE_MANIFEST_FOR_FILE_TREE_DIFF,
+            _("Build: Generate a file manifest for file tree diff."),
+        ),
         # Versions sync related features
         (
             SKIP_SYNC_BRANCHES,