codetrail-cli 1.4.1__py3-none-any.whl

codetrail/web/diagrams.py

@@ -0,0 +1,414 @@
+"""Diagrams drawn from facts only, as D2 text (design section 4.4, ADR 0016).
+
+Every node and edge is a fact, so a diagram can't show a connection the code doesn't have. Node ids are generated and
+labels are written as D2 double-quoted strings, so a name from the target can't inject D2's syntax. D2 keys are only
+ever generated ids: D2's dagre layout writes them into JavaScript it evaluates, escaping too little for a name. Above
+the node limit, modules roll up to their folders, one level at a time, with the number of imports on each edge.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import PurePosixPath
+from urllib.parse import quote
+
+from codetrail.facts import Entity, EntityKind, RelationKind
+from codetrail.facts.store import FactStore
+
+
+def d2_label(text: str, fallback: str = "?") -> str:
+    """A label D2 reads as plain text inside double quotes: only a quote, a backslash or a `${}` substitution could
+    end or change it, so each is escaped, and a line break, which would end the string, is dropped. An empty label
+    becomes the fallback."""
+    return _flattened(text, fallback).replace("\\", "\\\\").replace('"', '\\"').replace("$", "\\$")
+
+
+def _flattened(text: str, fallback: str) -> str:
+    """One line of printable text; an empty one becomes the fallback."""
+    return " ".join(_printable(text).split()) or " ".join(_printable(fallback).split()) or "?"
+
+
+def _printable(text: str) -> str:
+    """Without control, format and surrogate characters or noncharacters (U+FDD0-U+FDEF, U+xFFFE and U+xFFFF): none is
+    text a reader can see, and a line break would end D2's quoted string."""
+    return "".join(
+        character
+        for character in text
+        if unicodedata.category(character) not in ("Cc", "Cf", "Cs")
+        and ord(character) & 0xFFFE != 0xFFFE
+        and not 0xFDD0 <= ord(character) <= 0xFDEF
+    )
+
+
+def _node(node_id: str, label: str, key: str) -> str:
+    return f'{node_id}: "{d2_label(label, fallback=key)}"'
+
+
+def _edge(source: str, target: str, label: str) -> str:
+    """An arrow, labelled only when there's a label."""
+    text = " ".join(label.split())
+    return f'{source} -> {target}: "{d2_label(text)}"' if text else f"{source} -> {target}"
+
+
+@dataclass(frozen=True)
+class DiagramNode:
+    id: str
+    label: str
+    link: str
+
+
+@dataclass(frozen=True)
+class DiagramArrow:
+    """One connection in the system diagram and why it's there: its source file and line, or the rule's two names."""
+
+    source: str
+    kind: str
+    target: str
+    evidence: str
+    link: str | None
+    names: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class Diagram:
+    d2: str
+    nodes: list[DiagramNode] = field(default_factory=list)
+    rolled_up: bool = False
+    arrows: list[DiagramArrow] = field(default_factory=list)
+
+
+def imports_diagram(store: FactStore, scope: str, max_nodes: int) -> Diagram:
+    """The imports between modules under the folder `scope`, rolled up to folders above `max_nodes`."""
+    prefix = scope.rstrip("/") + "/"
+    modules = {
+        entity.id: entity
+        for kind in (EntityKind.MODULE, EntityKind.SWIFT_TARGET)
+        for entity in store.entities(kind)
+        if _location(entity.id).startswith(prefix)
+    }
+    edges = [
+        (relation.source_id, relation.target_id)
+        for kind in (RelationKind.IMPORTS, RelationKind.DEPENDS_ON)
+        for relation in store.relations(kind)
+        if relation.source_id in modules and relation.target_id in modules
+    ]
+    if len(modules) <= max_nodes:
+        group = {module_id: module_id for module_id in modules}
+        labels = {module_id: str(entity.attributes.get("name", module_id)) for module_id, entity in modules.items()}
+        links = {module_id: f"/facts/{quote(module_id, safe='')}" for module_id in modules}
+        return _render(group, labels, links, Counter(edges), rolled_up=False, counted=False)
+    paths = {module_id: PurePosixPath(_location(module_id)).parent for module_id in modules}
+    depth = max(len(path.parts) for path in paths.values())
+    while depth > 1 and len({_truncate(path, depth) for path in paths.values()}) > max_nodes:
+        depth -= 1
+    group = {module_id: str(_truncate(path, depth)) for module_id, path in paths.items()}
+    labels = {folder: f"{folder}/" for folder in group.values()}
+    links = {folder: f"/areas/{quote(folder)}" for folder in group.values()}
+    folder_edges = Counter((group[source], group[target]) for source, target in edges if group[source] != group[target])
+    return _render(group, labels, links, folder_edges, rolled_up=True, counted=True)
+
+
+def dependencies_diagram(store: FactStore, project_id: str) -> Diagram:
+    """A project and the packages it depends on, each edge labelled with its dependency group."""
+    project = store.entity(project_id)
+    if project is None:
+        return Diagram("direction: right\n")
+    relations = [r for r in store.relations(RelationKind.DEPENDS_ON) if r.source_id == project_id]
+    labels = {project_id: str(project.attributes.get("name", project_id))}
+    for relation in relations:
+        labels[relation.target_id] = _package_name(relation.target_id)
+    ids = {key: f"n{index}" for index, key in enumerate(sorted(labels), start=1)}
+    lines = ["direction: right"]
+    lines += [_node(ids[key], label, key) for key, label in sorted(labels.items())]
+    for relation in relations:
+        lines.append(_edge(ids[project_id], ids[relation.target_id], str(relation.attributes.get("group") or "")))
+    nodes = [DiagramNode(ids[key], label, f"/facts/{quote(key, safe='')}") for key, label in sorted(labels.items())]
+    return Diagram("\n".join(lines) + "\n", nodes)
+
+
+def resources_diagram(store: FactStore, scope: str, max_nodes: int) -> Diagram:
+    """Terraform modules under the folder `scope`, the modules they call and, when they fit, their resources."""
+    prefix = scope.rstrip("/") + "/"
+    modules = {
+        entity.id: entity for entity in store.entities(EntityKind.TERRAFORM_MODULE)
+        if (_location(entity.id) + "/").startswith(prefix) or prefix.startswith(_location(entity.id) + "/")
+    }  # fmt: skip
+    resources = {
+        entity.id: entity for entity in store.entities(EntityKind.RESOURCE)
+        if f"terraform_module:{entity.attributes.get('module')}" in modules
+    }  # fmt: skip
+    nodes = dict(modules) if len(modules) + len(resources) > max_nodes else {**modules, **resources}
+    labels = {key: (f"{_location(key)}/" if key in modules else _location(key).rsplit("/", 1)[-1]) for key in nodes}
+    edges: Counter[tuple[str, str]] = Counter()
+    for relation in store.relations(RelationKind.REFERENCES) + store.relations(RelationKind.CONTAINS):
+        if relation.source_id in nodes and relation.target_id in nodes:
+            edges[(relation.source_id, relation.target_id)] += 1
+    return _render({key: key for key in nodes}, labels, {key: f"/facts/{quote(key, safe='')}" for key in nodes}, edges,
+                   rolled_up=len(nodes) < len(modules) + len(resources), counted=False)  # fmt: skip
+
+
+# Each kind of part has its own shape: D2's syntax, after the quoted label.
+SHAPES = {
+    "service": " {style.border-radius: 8}",
+    "app": " {style.border-radius: 8}",
+    "library": "",
+    "contract": " {shape: page}",
+    "infrastructure": " {style.double-border: true}",
+    "platform": " {style.border-radius: 999}",  # a stadium
+}
+SYSTEM_RELATIONS = (RelationKind.DEPENDS_ON, RelationKind.IMPLEMENTS, RelationKind.CALLS_VIA, RelationKind.DEPLOYED_ON)
+ARROW_LABELS = {RelationKind.IMPLEMENTS: "implements", RelationKind.CALLS_VIA: "calls via",
+                RelationKind.DEPLOYED_ON: "deployed on"}  # fmt: skip
+
+
+def system_diagram(store: FactStore, focus: str | None, max_nodes: int) -> Diagram:
+    """How the repository's parts connect (design 17.4), or, with `focus`, the parts in a folder and their neighbours.
+
+    A client that calls through a contract that one service implements gets an arrow to that service, labelled
+    with the contract. Matched connections are dashed. Above `max_nodes`, libraries roll up into their parent
+    folders, then every part but the platforms into its top-level folder, then the smallest groups into one.
+    """
+    parts = {entity.id: entity for entity in store.entities(EntityKind.PART)}
+    relations = [
+        relation for kind in SYSTEM_RELATIONS for relation in store.relations(kind)
+        if relation.source_id in parts and relation.target_id in parts
+    ]  # fmt: skip
+    implementers: dict[str, list[str]] = {}
+    for relation in relations:
+        if relation.kind is RelationKind.IMPLEMENTS:
+            implementers.setdefault(relation.target_id, []).append(relation.source_id)
+    edges: dict[tuple[str, str], tuple[str, bool]] = {}  # (source, target) -> (label, matched)
+    for relation in relations:
+        matched = relation.attributes.get("evidence") == "matched"
+        if relation.kind is RelationKind.CALLS_VIA and len(implementers.get(relation.target_id, [])) == 1:
+            # One service behind the contract: the call is drawn to it. With several, it stays on the contract, so
+            # arrows never grow as callers times services.
+            contract = str(parts[relation.target_id].attributes.get("name", ""))
+            edges.setdefault((relation.source_id, implementers[relation.target_id][0]), (contract, matched))
+            continue
+        label = "matched by name" if matched else ARROW_LABELS.get(relation.kind, "")
+        edges.setdefault((relation.source_id, relation.target_id), (label, matched))
+    shown = set(parts)
+    if focus is not None:
+        inside = {key for key, entity in parts.items() if _within(_part_folder(entity), focus.strip("/"))
+                  and entity.attributes.get("kind") != "platform"}  # fmt: skip
+        pairs = [*edges, *((relation.source_id, relation.target_id) for relation in relations)]
+        shown = inside | {other for pair in pairs if set(pair) & inside for other in pair}
+    edges = {pair: value for pair, value in edges.items() if set(pair) <= shown}
+    relations = [relation for relation in relations if {relation.source_id, relation.target_id} <= shown]
+    group = {key: key for key in shown}
+    labels = {key: str(parts[key].attributes.get("name") or "") for key in shown}
+    kinds = {key: str(parts[key].attributes.get("kind", "library")) for key in shown}
+    links = {key: f"/facts/{quote(key, safe='')}" for key in shown}
+    rolled_up = False
+    for level in ("libraries", "parts"):
+        if len(set(group.values())) <= max_nodes:
+            break
+        rolled_up = True
+        members: dict[str, list[str]] = {}
+        for key in shown:
+            if level == "libraries" and kinds[key] == "library":
+                folder = str(PurePosixPath(_part_folder(parts[key])).parent)
+            elif level == "parts" and kinds[key] != "platform":
+                folder = _part_folder(parts[key]).split("/", 1)[0] or "."
+            else:
+                continue
+            members.setdefault(f"group:{folder}", []).append(key)
+        for folder_key, keys in members.items():
+            folder = folder_key.removeprefix("group:")
+            noun = "libraries" if level == "libraries" else "parts"
+            labels[folder_key] = f"{folder}/ ({len(keys)} {noun})"
+            kinds[folder_key] = "library"
+            links[folder_key] = f"/areas/{quote(folder)}"
+            for key in keys:
+                group[key] = folder_key
+    sizes = Counter(group.values())
+    if len(sizes) > max_nodes:  # still too many: the largest groups stay, the rest fold into one node
+        kept = {key for key, _ in sizes.most_common(max_nodes - 1)}
+        folded = [key for key in shown if group[key] not in kept]
+        labels["group:other"] = f"other parts ({len(folded)})"
+        kinds["group:other"] = "library"
+        links["group:other"] = "/system"
+        for key in folded:
+            group[key] = "group:other"
+    counted: Counter[tuple[str, str]] = Counter()
+    merged: dict[tuple[str, str], tuple[str, bool]] = {}
+    for (source, target), (label, matched) in edges.items():
+        pair = (group[source], group[target])
+        if pair[0] == pair[1]:
+            continue
+        counted[pair] += 1
+        before = merged.get(pair)
+        if before is not None:  # merged arrows keep a label they share, and are dashed only if all were matched
+            label, matched = (label if before[0] == label else ""), before[1] and matched
+        merged[pair] = (label, matched)
+    keys = sorted(set(group.values()))
+    ids = {key: f"n{index}" for index, key in enumerate(keys, start=1)}
+    lines = ["direction: right"]
+    for key in keys:
+        lines.append(_node(ids[key], labels[key], key) + SHAPES.get(kinds[key], ""))
+    for (source, target), (label, matched) in sorted(merged.items()):
+        text = str(counted[(source, target)]) if counted[(source, target)] > 1 else label
+        arrow = _edge(ids[source], ids[target], text)
+        if matched:  # dashed
+            arrow += " {style.stroke-dash: 3}" if text.strip() else ": {style.stroke-dash: 3}"
+        lines.append(arrow)
+    nodes = [DiagramNode(ids[key], labels[key] or key, links[key]) for key in keys]
+    arrows = [
+        DiagramArrow(
+            labels[relation.source_id] or relation.source_id, str(relation.kind),
+            labels[relation.target_id] or relation.target_id, str(relation.attributes.get("evidence", "explicit")),
+            _source_link(str(relation.attributes.get("source", ""))),
+            tuple(str(name) for name in relation.attributes.get("names") or ()),
+        )
+        for relation in relations
+    ]  # fmt: skip
+    return Diagram("\n".join(lines) + "\n", nodes, rolled_up, arrows)
+
+
+PART_KINDS = ("service", "app", "library", "contract", "infrastructure", "platform")
+
+
+@dataclass(frozen=True)
+class SystemPart:
+    """A part as the system page lists it, with the names of the parts it connects to."""
+
+    id: str
+    name: str
+    folder: str
+    depends_on: list[str]
+    called_by: list[str]
+    runs_on: list[str]
+
+
+def system_parts(store: FactStore) -> list[tuple[str, list[SystemPart]]]:
+    """Every part, grouped by kind in PART_KINDS order: what it depends on, what calls it and where it runs.
+
+    A part that calls through a contract counts as calling the contract, and the service behind it when there's one.
+    """
+    parts = {entity.id: entity for entity in store.entities(EntityKind.PART)}
+    names = {key: str(entity.attributes.get("name") or key) for key, entity in parts.items()}
+    relations = [
+        relation for kind in SYSTEM_RELATIONS for relation in store.relations(kind)
+        if relation.source_id in parts and relation.target_id in parts
+    ]  # fmt: skip
+    implementers: dict[str, set[str]] = {}
+    for relation in relations:
+        if relation.kind is RelationKind.IMPLEMENTS:
+            implementers.setdefault(relation.target_id, set()).add(relation.source_id)
+    depends_on: dict[str, set[str]] = {}
+    called_by: dict[str, set[str]] = {}
+    runs_on: dict[str, set[str]] = {}
+    for relation in relations:
+        source, target = relation.source_id, relation.target_id
+        if relation.kind is RelationKind.DEPENDS_ON:
+            depends_on.setdefault(source, set()).add(names[target])
+        elif relation.kind is RelationKind.CALLS_VIA:  # a lone implementer is called too; several stay on the contract
+            services = implementers.get(target, set())
+            for called in {target, *services} if len(services) == 1 else {target}:
+                called_by.setdefault(called, set()).add(names[source])
+        elif relation.kind is RelationKind.DEPLOYED_ON:
+            runs_on.setdefault(source, set()).add(names[target])
+    grouped: dict[str, list[SystemPart]] = {}
+    for key, entity in sorted(parts.items(), key=lambda item: names[item[0]].lower()):
+        kind = str(entity.attributes.get("kind"))
+        grouped.setdefault(kind if kind in PART_KINDS else "library", []).append(
+            SystemPart(key, names[key], _part_folder(entity), sorted(depends_on.get(key, set())),
+                       sorted(called_by.get(key, set())), sorted(runs_on.get(key, set())))
+        )  # fmt: skip
+    return [(kind, grouped[kind]) for kind in PART_KINDS if kind in grouped]
+
+
+def _within(folder: str, scope: str) -> bool:
+    return folder == scope or folder.startswith(scope + "/")
+
+
+def _part_folder(entity: Entity) -> str:
+    return str(entity.attributes.get("folder") or "")
+
+
+def _source_link(cited: str) -> str | None:
+    path, _, line = cited.partition("#L")
+    if not path or not LISTABLE.fullmatch(path):
+        return None
+    return f"/source/{path}#L{line}" if line.isdigit() else f"/source/{path}"
+
+
+MAX_AVAILABLE = 15  # of each kind, so the list stays a short part of a question's prompt
+# A folder or project id listed for an answer: plain path characters only, so no repository name can carry
+# whitespace, braces or instructions into the prompt (a name with spaces couldn't be drawn anyway).
+LISTABLE = re.compile(r"[A-Za-z0-9._@+/:-]+")
+
+
+def available_diagrams(store: FactStore) -> list[str]:
+    """The diagram placeholders that would draw something from these facts, for an answer to use (design 7.3).
+
+    The system first, when there are parts; imports for every top-level folder, project folder and folder of
+    projects that holds at least two modules or Swift targets; dependencies for every project that has any;
+    resources for every top-level Terraform folder.
+    """
+    located = [_location(entity.id) for kind in (EntityKind.MODULE, EntityKind.SWIFT_TARGET)
+               for entity in store.entities(kind)]  # fmt: skip
+    projects = [entity.id for entity in store.entities(EntityKind.PROJECT)]
+    folders = {path.split("/", 1)[0] for path in located if "/" in path}
+    for project in projects:
+        folder = _location(project)
+        if folder not in ("", "."):
+            folders |= {folder, str(PurePosixPath(folder).parent)}
+    scopes = sorted(
+        folder
+        for folder in folders
+        if folder not in ("", ".") and sum(p.startswith(folder + "/") for p in located) >= 2
+    )
+    depending = {relation.source_id for relation in store.relations(RelationKind.DEPENDS_ON)}
+    terraform = sorted(
+        {_location(entity.id).split("/", 1)[0] for entity in store.entities(EntityKind.TERRAFORM_MODULE)}
+    )
+    scopes = [scope for scope in scopes if LISTABLE.fullmatch(scope)]
+    depending = {project for project in depending if LISTABLE.fullmatch(project)}
+    terraform = [scope for scope in terraform if LISTABLE.fullmatch(scope)]
+    system = ["{{diagram system}}"] if store.entities(EntityKind.PART) else []
+    return (
+        system
+        + [f"{{{{diagram imports scope={scope}}}}}" for scope in scopes[:MAX_AVAILABLE]]
+        + [f"{{{{diagram dependencies project={project}}}}}" for project in sorted(depending & set(projects))][
+            :MAX_AVAILABLE
+        ]
+        + [f"{{{{diagram resources scope={scope}}}}}" for scope in terraform[:MAX_AVAILABLE]]
+    )
+
+
+def _package_name(package_id: str) -> str:
+    """package:<ecosystem>/<name> -> <name>, for every ecosystem (pypi, swift, ...)."""
+    return package_id.split(":", 1)[-1].split("/", 1)[-1]
+
+
+def _location(fact_id: str) -> str:
+    """A path-based fact id's path: module:<path>, swift_target:<folder>/<name>, terraform_module:<folder>..."""
+    return fact_id.split(":", 1)[1]
+
+
+def _truncate(path: PurePosixPath, depth: int) -> PurePosixPath:
+    return PurePosixPath(*path.parts[:depth]) if path.parts else path
+
+
+def _render(
+    group: dict[str, str],
+    labels: dict[str, str],
+    links: dict[str, str],
+    edges: Counter[tuple[str, str]],
+    *,
+    rolled_up: bool,
+    counted: bool,
+) -> Diagram:
+    keys = sorted(set(group.values()))
+    ids = {key: f"n{index}" for index, key in enumerate(keys, start=1)}
+    lines = ["direction: right"]
+    lines += [_node(ids[key], labels[key], key) for key in keys]
+    for (source, target), count in sorted(edges.items()):
+        lines.append(_edge(ids[source], ids[target], str(count) if counted else ""))
+    nodes = [DiagramNode(ids[key], labels[key], links[key]) for key in keys]
+    return Diagram("\n".join(lines) + "\n", nodes, rolled_up)

codetrail/web/documentation.py

@@ -0,0 +1,146 @@
+"""The Documentation page's tiles, its sections' helpers, and the report kept in memory between updates.
+
+Design sections 18.4 and 21.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import Counter
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import date
+
+from codetrail.facts import Entity
+from codetrail.metrics.decisions import written_on
+from codetrail.metrics.report import Metric, Value
+from codetrail.repo.history import Commit
+from codetrail.web.trend import trend_points
+
+COUNTS = {Metric.ADR_ATTENTION, Metric.COMMITS, Metric.CODE_LINES, Metric.SOURCE_FILES}
+# The sections a share can open, in their order on the page (design section 21.1).
+SECTIONS = (
+    ("rationale", Metric.DOCUMENTED_SHARE),
+    ("commits", Metric.COMMIT_WHY_SHARE),
+    ("coverage", Metric.MENTIONED_SHARE),
+)
+
+
+def section_to_open(values: Mapping[Metric, Value]) -> str | None:
+    """The decisions when an ADR needs attention; else the lowest measured share below 1, the first on a tie."""
+    attention = values.get(Metric.ADR_ATTENTION)
+    if attention is not None and attention.numerator:
+        return "decisions"
+    shares = []
+    for order, (section, metric) in enumerate(SECTIONS):
+        value = values.get(metric)
+        if value is not None and value.share is not None and value.share < 1:
+            shares.append((value.share, order, section))
+    return min(shares)[2] if shares else None
+
+
+def commit_kind(commit: Commit) -> str:
+    """A commit without a why: it has a body that doesn't say why, or only a subject."""
+    return "body-only" if commit.body else "subject-only"
+
+
+@dataclass(frozen=True)
+class Filter:
+    kinds: list[str]  # each item's kind, in the list's order
+    totals: dict[str, int]  # items per kind, "all" first
+    folded: dict[str, int]  # items past the first `listed`, per kind, "all" first
+
+
+def filtered(kinds: Sequence[str], listed: int) -> Filter:
+    """What a list's filter chips need: each item's kind, and the items of each kind in all and in the folded rest."""
+    rest = Counter(kinds[listed:])
+    totals = {"all": len(kinds), **Counter(kinds)}
+    folded = {kind: len(kinds[listed:]) if kind == "all" else rest.get(kind, 0) for kind in totals}
+    return Filter(list(kinds), totals, folded)
+
+
+def segments(parts: Sequence[tuple[str, int, str]], width: int = 1000) -> list[tuple[str, float, float]]:
+    """A stacked bar's parts as tone, x and width; a part with no tone takes its room and isn't drawn."""
+    total = sum(count for _, count, _ in parts)
+    drawn, x = [], 0.0
+    for tone, count, _ in parts:
+        if count <= 0 or not total:
+            continue
+        span = count / total * width
+        if tone:
+            drawn.append((tone, round(x, 1), round(span, 1)))
+        x += span
+    return drawn
+
+
+def days_proposed(decision: Entity, today: date) -> int | None:
+    written = written_on(decision)
+    return (today - written).days if written is not None else None
+
+
+@dataclass(frozen=True)
+class Tile:
+    metric: Metric
+    value: Value | None  # None when it couldn't be measured
+    percent: int | None  # a share's rounded percent
+    change: int | None  # since the previous update: percentage points for a share, the difference for a count
+    trend_text: str  # each recorded value, oldest first, as the page writes it
+    points: str  # the trend line's SVG points
+
+
+def percent_of(value: Value) -> int | None:
+    """A share's percent, rounded, but 100 only when it is all and 0 only when it is none."""
+    if value.share is None:
+        return None
+    percent = round(value.share * 100)
+    if value.numerator < (value.denominator or 0):
+        percent = min(percent, 99)
+    return max(percent, 1) if value.numerator > 0 else percent
+
+
+def age(first: date, today: date) -> tuple[int, int]:
+    """Whole months from `first` to `today`, as years and months; a day of the month not yet reached doesn't count."""
+    months = (today.year - first.year) * 12 + today.month - first.month - (1 if today.day < first.day else 0)
+    return divmod(max(months, 0), 12)
+
+
+def _number(metric: Metric, value: Value) -> float | None:
+    if metric in COUNTS:
+        return value.numerator
+    return None if value.share is None else value.share * 100
+
+
+def build_tiles(
+    values: Mapping[Metric, Value], before: Mapping[Metric, Value], history: Mapping[Metric, Sequence[Value]]
+) -> dict[Metric, Tile]:
+    tiles = {}
+    for metric in Metric:
+        value, earlier = values.get(metric), before.get(metric)
+        now = _number(metric, value) if value else None
+        then = _number(metric, earlier) if earlier else None
+        change = round(now - then) if now is not None and then is not None else None
+        past = [recorded for recorded in history.get(metric, []) if _number(metric, recorded) is not None]
+        trend = [number for number in (_number(metric, recorded) for recorded in past) if number is not None]
+        if metric in COUNTS:
+            text = ", ".join(str(recorded.numerator) for recorded in past)
+        else:
+            text = ", ".join(f"{percent_of(recorded)}%" for recorded in past)
+        percent = None if value is None or metric in COUNTS else percent_of(value)
+        tiles[metric] = Tile(metric, value, percent, change, text, trend_points(trend))
+    return tiles
+
+
+class ReportCache[T]:
+    """One report, rebuilt only when its key changes: the latest snapshot, the guide's state and the date."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._key: object = None
+        self._report: T | None = None
+
+    def get(self, key: object, build: Callable[[], T]) -> T:
+        with self._lock:
+            if self._report is None or self._key != key:
+                self._report = build()
+                self._key = key
+            return self._report

codetrail/web/i18n.py

@@ -0,0 +1,44 @@
+"""Interface languages: one gettext catalog per language, English first and as the fallback (design section 7.2).
+
+A catalog names itself and its writing direction by translating two messages with a context: "English" in the
+context "language name", and "ltr" in the context "text direction" (as `ltr` or `rtl`). The installed languages are
+English plus every compiled catalog found.
+"""
+
+from __future__ import annotations
+
+import gettext
+import re
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+
+LANGUAGE_CODE = re.compile(r"[a-z]{2,3}(_[A-Z]{2})?")
+DOMAIN = "codetrail"
+
+
+@dataclass(frozen=True)
+class Language:
+    code: str
+    name: str
+    direction: str
+    translations: gettext.NullTranslations
+
+
+def default_locales() -> Path:
+    return Path(str(files("codetrail").joinpath("locales")))
+
+
+def installed_languages(locales: Path | None = None) -> dict[str, Language]:
+    languages = {"en": Language("en", "English", "ltr", gettext.NullTranslations())}
+    folder = locales or default_locales()
+    for catalog in sorted(folder.glob(f"*/LC_MESSAGES/{DOMAIN}.mo")):
+        code = catalog.parent.parent.name
+        if not LANGUAGE_CODE.fullmatch(code) or code == "en":
+            continue
+        with catalog.open("rb") as handle:
+            translations = gettext.GNUTranslations(handle)
+        direction = translations.pgettext("text direction", "ltr")
+        name = translations.pgettext("language name", "English")
+        languages[code] = Language(code, name, direction if direction in ("ltr", "rtl") else "ltr", translations)
+    return languages