"""Read-only project icon discovery from retained bare mirrors. A repository's own favicon or logo makes it recognisable in the catalog. The icon is resolved from the existing mirror at an exact revision, never from a worktree and never by fetching: the scanned repository and the mirror are not modified. Candidates are ranked deterministically, size-bounded and content-checked before they are served. """ from __future__ import annotations import re import subprocess from collections import OrderedDict from dataclasses import dataclass from pathlib import Path from threading import Lock from .processes import git_environment, run_bounded SAFE_REVISION = re.compile(r"^[0-9a-fA-F]{7,64}$") SAFE_OBJECT = re.compile(r"^[0-9a-f]{40,64}$") MAX_ICON_BYTES = 128 * 1024 MAX_TREE_ENTRIES = 200_000 MIN_RASTER_BYTES = 3 * 1024 _ICON_NAME = re.compile(r"^(favicon|icon|app-icon|logo|logo-mark|apple-touch-icon)([._-][a-z0-9-]*)?\.(svg|png|webp|ico)$", re.IGNORECASE) _EXCLUDED_SEGMENT = re.compile( r"^(node_modules|vendor|third_party|\.git|dist|build-cache|coverage|tests?|__tests__|fixtures?|examples?|screens|screenshots|mockups?|templates?)$", re.IGNORECASE, ) _PREFERRED_DIRECTORY = {"public": 0, "static": 1, "app": 1, "assets": 2, "icons": 2, "images": 3, "wwwroot": 1, "media": 3, "build": 4, "resources": 4, "build-resources": 4} _NAME_RANK = {"favicon": 0, "icon": 1, "app-icon": 1, "logo-mark": 2, "logo": 3, "apple-touch-icon": 4} _FORMAT_RANK = {"svg": 0, "png": 1, "webp": 2, "ico": 3} MEDIA_TYPES = {"svg": "image/svg+xml", "png": "image/png", "webp": "image/webp", "ico": "image/x-icon"} @dataclass(frozen=True) class ProjectIcon: path: str media_type: str content: bytes def _rank(path: str, size: int) -> tuple[int, int, int, int, int, int, str] | None: parts = path.split("/") name = parts[-1] match = _ICON_NAME.fullmatch(name) if not match or size <= 0 or size > MAX_ICON_BYTES: return None directories = parts[:-1] if any(_EXCLUDED_SEGMENT.fullmatch(segment) for segment in directories): return None if len(directories) > 6: return None directory_rank = min((_PREFERRED_DIRECTORY.get(segment.casefold(), 6) for segment in directories), default=5) extension = match.group(3).casefold() sized_variant = 1 if match.group(2) and re.search(r"\d", match.group(2)) else 0 # Tiny raster favicons (16/32 px) look blurry at avatar size; prefer a larger raster. low_resolution = 1 if extension != "svg" and size < MIN_RASTER_BYTES else 0 return ( _FORMAT_RANK[extension], low_resolution, _NAME_RANK[match.group(1).casefold()], directory_rank + sized_variant, len(directories), size, path, ) def _looks_like(content: bytes, extension: str) -> bool: if extension == "png": return content.startswith(b"\x89PNG\r\n\x1a\n") if extension == "ico": return content[:4] == b"\x00\x00\x01\x00" if extension == "webp": return content[:4] == b"RIFF" and content[8:12] == b"WEBP" head = content[:2048].lstrip().lower() return head.startswith((b" None: self.mirrors_root = mirrors_root self.timeout = timeout self.cache_size = cache_size self._cache: OrderedDict[tuple[str, str], ProjectIcon | None] = OrderedDict() self._lock = Lock() def _git(self, mirror: Path, args: list[str]) -> bytes: result = run_bounded(["git", "--git-dir", str(mirror), *args], timeout=self.timeout, env=git_environment()) return result.stdout def resolve(self, mirror: Path, revision: str) -> ProjectIcon | None: if not SAFE_REVISION.fullmatch(revision): return None try: mirror.resolve().relative_to(self.mirrors_root.resolve()) except (OSError, RuntimeError, ValueError): return None key = (str(mirror), revision.casefold()) with self._lock: if key in self._cache: self._cache.move_to_end(key) return self._cache[key] icon = self._discover(mirror, revision) if mirror.is_dir() else None with self._lock: self._cache[key] = icon self._cache.move_to_end(key) while len(self._cache) > self.cache_size: self._cache.popitem(last=False) return icon def _discover(self, mirror: Path, revision: str) -> ProjectIcon | None: try: listing = self._git(mirror, ["ls-tree", "-r", "-l", "--full-tree", "-z", f"{revision}^{{tree}}"]) except (OSError, subprocess.SubprocessError): return None candidates: list[tuple[tuple[int, int, int, int, int, int, str], str, str]] = [] for index, entry in enumerate(listing.split(b"\x00")): if index >= MAX_TREE_ENTRIES or not entry: continue try: meta, raw_path = entry.split(b"\t", 1) _mode, kind, obj, size = meta.split() path = raw_path.decode("utf-8") except ValueError: continue if kind != b"blob" or not size.isdigit(): continue obj_id = obj.decode("ascii", errors="ignore") rank = _rank(path, int(size)) if rank is not None and SAFE_OBJECT.fullmatch(obj_id): candidates.append((rank, obj_id, path)) for _rank_key, obj_id, path in sorted(candidates)[:8]: try: content = self._git(mirror, ["cat-file", "blob", obj_id]) except (OSError, subprocess.SubprocessError): continue extension = path.rsplit(".", 1)[-1].casefold() if len(content) <= MAX_ICON_BYTES and _looks_like(content, extension): return ProjectIcon(path=path, media_type=MEDIA_TYPES[extension], content=content) return None