feat(info): World Almanac — repo metadata in the Info tab (#60)

api/models/manifest.py

@@ -114,20 +114,107 @@ class BusynessThresholds(BaseModel):
 # not optional. camelCase matches the frontend DateRanges + the fullPath
 # precedent.
 class DateRanges(BaseModel):
-    createdMin: Optional[str] = Field(
+    minCreated: Optional[str] = Field(
         description="Earliest resolved create date (ISO), or null for an empty tree"
     )
-    createdMax: Optional[str] = Field(
+    maxCreated: Optional[str] = Field(
         description="Latest resolved create date (ISO), or null for an empty tree"
     )
-    modifiedMin: Optional[str] = Field(
+    minModified: Optional[str] = Field(
         description="Earliest resolved modify date (ISO), or null for an empty tree"
     )
-    modifiedMax: Optional[str] = Field(
+    maxModified: Optional[str] = Field(
         description="Latest resolved modify date (ISO), or null for an empty tree"
     )
 
 
+class RangeStat(BaseModel):
+    min: int
+    max: int
+
+
+class FileLeader(BaseModel):
+    path: str
+    lines: int
+    bytes: int
+    created: str
+    modified: str
+    # Optional-but-non-nullable (absent for non-media leaders, a pixel count
+    # otherwise — never null); see OptionalInt above.
+    media_width: OptionalInt = None
+    media_height: OptionalInt = None
+
+    @model_validator(mode="after")
+    def _media_both_or_neither(self) -> "FileLeader":
+        if (self.media_width is None) != (self.media_height is None):
+            raise ValueError(
+                "media_width and media_height must both be set or both absent"
+            )
+        return self
+
+
+class DirLeader(BaseModel):
+    path: str
+    depth: int
+    children: int
+    descendants: int
+
+
+class CommitLeader(BaseModel):
+    sha: str
+    files: int
+
+
+# Both fields required-nullable: the scanner always emits them (null for a repo
+# with no commits), so they're present-but-nullable on the wire, not optional.
+class CommitDateRange(BaseModel):
+    oldest: Optional[str] = Field(
+        description="Oldest commit date (YYYY-MM-DD), or null when the repo has no commits"
+    )
+    newest: Optional[str] = Field(
+        description="Newest commit date (YYYY-MM-DD), or null when the repo has no commits"
+    )
+
+
+class DayLeader(BaseModel):
+    date: str
+    count: int
+
+
+class AuthorStat(BaseModel):
+    name: str
+    commits: int
+
+
+class RepoStats(BaseModel):
+    lineCountRange: RangeStat
+    byteSizeRange: RangeStat
+    oldestCreatedFile: Optional[FileLeader]
+    newestCreatedFile: Optional[FileLeader]
+    newestModifiedFile: Optional[FileLeader]
+    oldestModifiedFile: Optional[FileLeader]
+    maxLinesFile: Optional[FileLeader]
+    minLinesFile: Optional[FileLeader]
+    maxBytesFile: Optional[FileLeader]
+    minBytesFile: Optional[FileLeader]
+    maxMediaBytesFile: Optional[FileLeader]
+    minMediaBytesFile: Optional[FileLeader]
+    maxMediaPixelsFile: Optional[FileLeader]
+    minMediaPixelsFile: Optional[FileLeader]
+    mediaCount: int
+    totalLines: int
+    codeBytes: int
+    maxDepthDir: Optional[DirLeader]
+    maxChildrenDir: Optional[DirLeader]
+    minChildrenDir: Optional[DirLeader]
+    maxFilesPerCommit: Optional[CommitLeader]
+    minFilesPerCommit: Optional[CommitLeader]
+    commitDates: CommitDateRange
+    maxCommitsPerDay: Optional[DayLeader]
+    maxCommitStreakDays: int
+    authors: list[AuthorStat]
+
+
 class Manifest(BaseModel):
     root: str
     scanned_at: str
@@ -138,6 +225,7 @@ class Manifest(BaseModel):
     commits: list[CommitEntry]
     busyness: BusynessThresholds
     dateRanges: DateRanges
+    stats: RepoStats
     # Optional-but-non-nullable (absent for local sources, a label string for
     # git sources — never null); see OptionalStr above.
     display_root: OptionalStr = None

api/models/responses.py

@@ -15,6 +15,14 @@ class FileTooLargeResponse(BaseModel):
     limit: int
 
 
+class FileBatchEntry(BaseModel):
+    """One image in a POST /api/files batch response: its content-type and
+    base64-encoded bytes, keyed by request path in the response map."""
+
+    mime: str
+    b64: str
+
+
 class HealthResponse(BaseModel):
     ok: bool
 

api/routers/file.py

@@ -1,20 +1,37 @@
-"""GET /api/file — serve a file from disk, restricted to scanned roots."""
+"""GET /api/file — serve a file from disk, restricted to scanned roots.
+
+POST /api/files is the batch sibling used by the scene's media-texture loader:
+one round trip for many small images instead of one request per billboard.
+"""
 
 from __future__ import annotations
 
+import base64
 import mimetypes
 from pathlib import Path
 
 from fastapi import APIRouter, HTTPException, Query, Response
 from fastapi.responses import JSONResponse
+from pydantic import BaseModel
 
 from api.config import MAX_FILE_BYTES
-from api.models.responses import FileTooLargeResponse
+from api.models.responses import FileBatchEntry, FileTooLargeResponse
 from api.security import NoRootsRegisteredError, OutsideRootError, TRUST
 from api.services.media import is_media
 
 router = APIRouter(prefix="/api", tags=["file"])
 
+# Caps for POST /api/files. The client chunks its requests, but a server-side
+# bound keeps any single response from ballooning: at most this many paths, and
+# only images up to this size are base64-inlined — anything larger or non-image
+# is omitted so the client falls back to the streaming GET /api/file path.
+_MAX_BATCH_PATHS = 64
+_MAX_BATCH_FILE_BYTES = 8 * 1024 * 1024
+
+
+class FileBatchRequest(BaseModel):
+    paths: list[str]
+
 
 @router.get("/file")
 def get_file(
@@ -58,3 +75,32 @@ def get_file(
     # Non-media (code, configs, extensionless) → text/plain so the preview
     # renders the bytes as code; GZipMiddleware compresses it (text gzips well).
     return Response(content=body, media_type="text/plain; charset=utf-8")
+
+
+@router.post("/files")
+def get_files(req: FileBatchRequest) -> dict[str, FileBatchEntry]:
+    """Batch image fetch — return {path: {mime, b64}} for many small images in
+    one round trip. The scene loads one billboard texture per media file; firing
+    a separate GET per file exhausts the browser's HTTP/1.1 connection pool on
+    media-heavy repos, so the loader coalesces image paths into POST batches.
+
+    Each path is trust-checked exactly like GET /api/file. Paths that are out of
+    root, missing, non-image, or larger than _MAX_BATCH_FILE_BYTES are silently
+    omitted; the client falls back to the streaming GET for those. Videos are
+    never batched (they stream their poster frame), so this is images only.
+    """
+    out: dict[str, FileBatchEntry] = {}
+    for path in req.paths[:_MAX_BATCH_PATHS]:
+        try:
+            target = TRUST.assert_inside(Path(path))
+        except (NoRootsRegisteredError, OutsideRootError, OSError, RuntimeError):
+            continue
+        if not target.is_file() or target.stat().st_size > _MAX_BATCH_FILE_BYTES:
+            continue
+        guessed, _ = mimetypes.guess_type(str(target))
+        if not guessed or not guessed.startswith("image/"):
+            continue
+        out[path] = FileBatchEntry(
+            mime=guessed, b64=base64.b64encode(target.read_bytes()).decode()
+        )
+    return out

api/services/cache.py

@@ -65,7 +65,9 @@ class FileEntry(TypedDict):
 # treated as a miss and re-scanned. (Per-bump rationale lives in git history.)
 _FILE_CACHE_VERSION = 1
 _GIT_HISTORY_CACHE_VERSION = 12  # v12: dates UTC-normalized (file maps + commit days)
-_MANIFEST_SCHEMA_VERSION = 7  # v7: FileNode.mediaKind added
+_MANIFEST_SCHEMA_VERSION = (
+    11  # v11: dir leaders by direct children (max/minChildrenDir) + totals
+)
 # Composite: invalidates when EITHER the manifest schema OR the git-history
 # shape changes. Stored as a string in the cache file's `version` field.
 _MANIFEST_CACHE_VERSION: str = (

api/services/manifest_types.py

@@ -159,10 +159,109 @@ class DateRanges(TypedDict):
     gradients read one consistent range instead of re-walking the tree.
     All four are None for a tree with zero files."""
 
-    createdMin: str | None
-    createdMax: str | None
-    modifiedMin: str | None
-    modifiedMax: str | None
+    minCreated: str | None
+    maxCreated: str | None
+    minModified: str | None
+    maxModified: str | None
+
+
+class RangeStat(TypedDict):
+    """Inclusive min/max of an integer metric (lines, bytes)."""
+
+    min: int
+    max: int
+
+
+class FileLeader(TypedDict):
+    """The file that wins a per-repo superlative, with the values the Overview renders (path + lines/bytes/dates, optional media dims)."""
+
+    path: str
+    lines: int
+    bytes: int
+    created: str
+    modified: str
+    media_width: NotRequired[int]
+    media_height: NotRequired[int]
+
+
+class DirLeader(TypedDict):
+    """The directory that wins a street superlative. `children` = direct
+    children (files + sub-dirs on that street); `descendants` = everything below
+    it; `depth` = nesting level."""
+
+    path: str
+    depth: int
+    children: int
+    descendants: int
+
+
+class CommitLeader(TypedDict):
+    """The commit that wins a superlative (most / fewest files changed)."""
+
+    sha: str
+    files: int
+
+
+class CommitDateRange(TypedDict):
+    """Oldest/newest commit date (YYYY-MM-DD) across the lookback window — the
+    scene's tree-age normalization range, computed once so the trees + firefly
+    orbits read it instead of re-scanning commits. Both None for a repo with
+    zero commits."""
+
+    oldest: str | None
+    newest: str | None
+
+
+class DayLeader(TypedDict):
+    """A calendar date with a commit count (the busiest day)."""
+
+    date: str
+    count: int
+
+
+class AuthorStat(TypedDict):
+    """One author and their total commit count."""
+
+    name: str
+    commits: int
+
+
+class RepoStats(TypedDict):
+    """Per-repo derived stats computed once at manifest-wrap
+    (api/services/stats.py): the Overview almanac superlatives + min/max
+    ranges. The web app reads these instead of re-walking the tree."""
+
+    # Building-size NORMALIZATION ranges (non-zero), NOT honest min/max file
+    # size. Over all files with non-zero lines/size — 0-length files are
+    # excluded because they have no meaningful building height/width (and the
+    # frontend log/sqrt can't take 0). The honest "smallest file" lives in the
+    # minBytesFile / minLinesFile leaders. {0,0} when no non-zero files exist.
+    lineCountRange: RangeStat
+    byteSizeRange: RangeStat
+    oldestCreatedFile: FileLeader | None
+    newestCreatedFile: FileLeader | None
+    newestModifiedFile: FileLeader | None
+    oldestModifiedFile: FileLeader | None
+    maxLinesFile: FileLeader | None
+    minLinesFile: FileLeader | None
+    maxBytesFile: FileLeader | None
+    minBytesFile: FileLeader | None
+    maxMediaBytesFile: FileLeader | None
+    minMediaBytesFile: FileLeader | None
+    maxMediaPixelsFile: FileLeader | None
+    minMediaPixelsFile: FileLeader | None
+    mediaCount: int
+    totalLines: int
+    codeBytes: int
+    maxDepthDir: DirLeader | None
+    maxChildrenDir: DirLeader | None
+    minChildrenDir: DirLeader | None
+    maxFilesPerCommit: CommitLeader | None
+    minFilesPerCommit: CommitLeader | None
+    commitDates: CommitDateRange
+    maxCommitsPerDay: DayLeader | None
+    maxCommitStreakDays: int
+    authors: list[AuthorStat]
 
 
 class Manifest(TypedDict):
@@ -178,6 +277,7 @@ class Manifest(TypedDict):
     commits: list[CommitEntry]
     busyness: BusynessThresholds
     dateRanges: DateRanges
+    stats: RepoStats
     display_root: NotRequired[str]
 
 

api/services/scan.py

@@ -35,6 +35,7 @@
     cache_save_git_history,
 )
 from .media import media_kind, probe_media_dims
+from .stats import compute_repo_stats
 from .manifest_types import (
     BusynessThresholds,
     CommitEntry,
@@ -1188,10 +1189,10 @@ def _compute_date_ranges(tree: DirNode) -> DateRanges:
         mmin = m if mmin is None or m < mmin else mmin
         mmax = m if mmax is None or m > mmax else mmax
     return {
-        "createdMin": cmin,
-        "createdMax": cmax,
-        "modifiedMin": mmin,
-        "modifiedMax": mmax,
+        "minCreated": cmin,
+        "maxCreated": cmax,
+        "minModified": mmin,
+        "maxModified": mmax,
     }
 
 
@@ -1220,6 +1221,7 @@ def _wrap_manifest(
         "commits": commits,
         "busyness": _compute_busyness(commits),
         "dateRanges": _compute_date_ranges(tree),
+        "stats": compute_repo_stats(tree, commits),
     }