codetrail-cli 1.4.1__py3-none-any.whl

codetrail/lock.py

@@ -0,0 +1,114 @@
+"""One update at a time per target (design section 10), and no removal while a command uses the target.
+
+The OS releases the locks if the process dies."""
+
+from __future__ import annotations
+
+import fcntl
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from codetrail.config import Paths, validate_target_name
+from codetrail.errors import CodetrailError
+
+
+class TargetBusy(CodetrailError):
+    """Another command holds the target's lock."""
+
+
+@contextmanager
+def target_lock(paths: Paths, name: str) -> Iterator[None]:
+    folder = paths.target_data(name)
+    folder.mkdir(parents=True, exist_ok=True)
+    with (folder / "update.lock").open("a") as handle:
+        try:
+            fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as error:
+            raise TargetBusy(_already_updating(name)) from error
+        try:
+            yield
+        finally:
+            fcntl.flock(handle, fcntl.LOCK_UN)
+
+
+@contextmanager
+def existing_target_lock(paths: Paths, name: str) -> Iterator[None]:
+    """Holds the update lock if the data folder has one, creating nothing and following no symlink.
+
+    For removal: an update holds it even when an editor has replaced the settings file its in-use lock is on."""
+    folder = paths.target_data(name)
+    descriptor = None
+    if folder.is_dir() and not folder.is_symlink():
+        try:
+            descriptor = os.open(folder / "update.lock", os.O_RDONLY | os.O_NOFOLLOW)
+        except FileNotFoundError:
+            pass
+        except OSError as error:
+            raise CodetrailError(f"Can't lock target {name!r} ({folder / 'update.lock'}): {error.strerror}.") from error
+    if descriptor is None:
+        yield
+        return
+    try:
+        try:
+            fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as error:
+            raise TargetBusy(_already_updating(name)) from error
+        yield
+    finally:
+        os.close(descriptor)  # closing releases the lock
+
+
+def _already_updating(name: str) -> str:
+    return f"Target {name!r} is already updating; try again when that finishes."
+
+
+@contextmanager
+def target_in_use(paths: Paths, name: str) -> Iterator[None]:
+    """Held, shared, by `serve`, `update` and `files` while they use the target, so it isn't removed under them."""
+    with _settings_lock(paths, name, fcntl.LOCK_SH, f"Target {name!r} is being removed."):
+        yield
+
+
+@contextmanager
+def target_removal(paths: Paths, name: str) -> Iterator[None]:
+    """Held alone by `codetrail target remove` until the target's settings file is gone."""
+    busy = f"Target {name!r} is in use: stop `codetrail serve` for it, or wait for its update to finish."
+    with _settings_lock(paths, name, fcntl.LOCK_EX, busy):
+        yield
+
+
+@contextmanager
+def _settings_lock(paths: Paths, name: str, operation: int, busy: str) -> Iterator[None]:
+    """Locks the target's settings file, which removal deletes last; opening it creates no folder."""
+    settings = paths.target_file(validate_target_name(name))
+    missing = f"No target named {name!r}. Add it with: codetrail target add {name} <path>"
+    try:
+        handle = settings.open("rb")
+    except FileNotFoundError as error:
+        raise CodetrailError(missing) from error
+    except OSError as error:
+        raise CodetrailError(f"Can't lock target {name!r} ({settings}): {error.strerror}.") from error
+    with handle:
+        try:
+            fcntl.flock(handle, operation | fcntl.LOCK_NB)
+        except BlockingIOError as error:
+            raise TargetBusy(busy) from error
+        except OSError as error:  # a filesystem without locks, for one
+            raise CodetrailError(f"Can't lock target {name!r} ({settings}): {error.strerror}.") from error
+        try:
+            if not _is_current(handle.fileno(), settings):  # a removal finished between opening and locking
+                raise CodetrailError(missing)
+            yield
+        finally:
+            fcntl.flock(handle, fcntl.LOCK_UN)
+
+
+def _is_current(descriptor: int, settings: Path) -> bool:
+    try:
+        current = settings.stat()
+    except FileNotFoundError:
+        return False
+    opened = os.fstat(descriptor)
+    return (opened.st_dev, opened.st_ino) == (current.st_dev, current.st_ino)

codetrail/metrics/__init__.py

@@ -0,0 +1,6 @@
+"""Documentation metrics: how well a repository explains itself, from the guide, the facts and the history (design
+section 18).
+
+Each metric is a pure function over data already read; `report.build_report` reads it, and `history` keeps each
+metric's value per update. Nothing here calls an assistant.
+"""

codetrail/metrics/activity.py

@@ -0,0 +1,96 @@
+"""The branch's history and its commit types (design section 19.1): dates and counts only, never people."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, date, datetime, timedelta
+from itertools import pairwise
+
+from codetrail.repo.history import WITHHELD_MESSAGE, Commit
+
+
+@dataclass(frozen=True)
+class Activity:
+    commits: int
+    merges: int
+    first: date | None
+    latest: date | None
+    months: list[tuple[str, int]]  # "YYYY-MM" and its commits, the last few months up to today, oldest first
+    years: list[tuple[int, int]]  # each year from the first commit's to the latest's, oldest first
+    active_weeks: int
+    weeks: int  # weeks from the first commit's to the latest's, both counted
+    longest_gap: tuple[date, date] | None  # the two commit days furthest apart with none between
+    cut: bool  # the history holds more commits than were read
+    days: list[int] = field(default_factory=list)  # commits per UTC day, from days_start to today
+    days_start: date | None = None
+
+
+def _monday(day: date) -> date:
+    return day - timedelta(days=day.weekday())
+
+
+def measure_activity(times: Sequence[int], commits: int, merges: int, today: date, months: int) -> Activity:
+    """Activity from author times in UTC; `commits` and `merges` count the whole history, even past the times read."""
+    days = sorted(datetime.fromtimestamp(time, UTC).date() for time in times)
+    by_month = Counter(day.strftime("%Y-%m") for day in days)
+    shown, year, month = [], today.year, today.month
+    for _ in range(months):
+        shown.append(f"{year:04d}-{month:02d}")
+        year, month = (year, month - 1) if month > 1 else (year - 1, 12)
+    month_counts = [(key, by_month.get(key, 0)) for key in reversed(shown)]
+    cut = len(times) < commits
+    if not days:
+        return Activity(commits, merges, None, None, month_counts, [], 0, 0, None, cut)
+    first, latest = days[0], days[-1]
+    by_year = Counter(day.year for day in days)
+    years = [(year, by_year.get(year, 0)) for year in range(first.year, latest.year + 1)]
+    active_weeks = len({_monday(day) for day in days})
+    weeks = (_monday(latest) - _monday(first)).days // 7 + 1
+    widest = max(pairwise(days), key=lambda pair: pair[1] - pair[0], default=None)
+    gap = widest if widest and widest[1] > widest[0] else None
+    # Commits per day end at today: a commit can claim any date, and a far-future one would make the series huge.
+    by_day = Counter(days)
+    per_day = [by_day.get(first + timedelta(days=offset), 0) for offset in range((today - first).days + 1)]
+    days_start = first if per_day else None
+    return Activity(commits, merges, first, latest, month_counts, years, active_weeks, weeks, gap, cut, per_day,
+                    days_start)  # fmt: skip
+
+
+@dataclass(frozen=True)
+class CommitTypes:
+    matched: int
+    measured: int  # subjects read: withheld ones are left out
+    types: list[tuple[str, int]]  # the most used first
+    scopes: list[tuple[str, int]]
+
+    @property
+    def used(self) -> bool:
+        """Whether the repository appears to use such subjects: at least half of them match."""
+        return self.measured > 0 and self.matched * 2 >= self.measured
+
+
+def _most_first(counts: Counter[str]) -> list[tuple[str, int]]:
+    return sorted(counts.items(), key=lambda item: (-item[1], item[0]))
+
+
+def measure_types(commits: Iterable[Commit], pattern: re.Pattern[str], max_chars: int) -> CommitTypes:
+    """Counts the subjects that match the target's commit type pattern; only the start of a subject is matched."""
+    matched = measured = 0
+    types: Counter[str] = Counter()
+    scopes: Counter[str] = Counter()
+    for commit in commits:
+        if commit.subject == WITHHELD_MESSAGE:
+            continue
+        measured += 1
+        found = pattern.match(commit.subject[:max_chars])
+        if found is None:
+            continue
+        matched += 1
+        types[found["type"].lower()] += 1
+        scope = found.groupdict().get("scope")
+        if scope:
+            scopes[scope] += 1
+    return CommitTypes(matched, measured, _most_first(types), _most_first(scopes))

codetrail/metrics/churn.py

@@ -0,0 +1,156 @@
+"""Where change happens: hot spots, the heat map's tiles, the area-by-month grid, quiet code and commit size.
+
+Design sections 19.1 and 20.1. Only allowed files are ever named: a commit's other files count toward its size, never
+toward a hot spot or a tile.
+"""
+
+from __future__ import annotations
+
+import statistics
+from collections import Counter
+from collections.abc import Collection, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, date, datetime
+
+from codetrail.generate.outline import in_scope
+from codetrail.guide import Page
+
+MONTHS_SHOWN = 12
+SIZE_BUCKETS = (1, 2, 3, 5, 10, 20)  # upper bounds of 1, 2, 3, 4-5, 6-10, 11-20; anything larger is 21+
+
+
+@dataclass(frozen=True)
+class HotSpot:
+    name: str  # a file, or a folder ("." for the repository's root)
+    count: int  # commits that changed it, or for quiet code, its quiet files
+
+
+@dataclass(frozen=True)
+class AreaSpot:
+    page: Page
+    commits: int
+    documented: int
+    inferred: int
+    lines: int = 0  # lines of code in the area's scope
+    scope: tuple[str, ...] = field(default=(), compare=False)  # the area's scope paths
+
+
+@dataclass(frozen=True)
+class HeatTile:
+    name: str
+    path: str
+    lines: int
+    commits: int
+
+
+@dataclass(frozen=True)
+class Churn:
+    commits: int  # read: the latest non-merge commits, up to the window
+    files: list[HotSpot]  # the most changed first
+    folders: list[HotSpot]
+    areas: list[AreaSpot]
+    quiet: list[HotSpot]  # code files no recent commit changed, counted by folder
+    quiet_files: int
+    median_files: float | None  # files a commit changes
+    p90_files: float | None
+    folder_tiles: list[HeatTile] = field(default_factory=list)  # the largest by lines, at most the cap
+    file_tiles: list[HeatTile] = field(default_factory=list)
+    left_out: dict[str, int] = field(default_factory=dict)  # tiles past the cap, per level
+    months: list[str] = field(default_factory=list)  # "YYYY-MM", the last twelve, oldest first
+    area_months: list[tuple[str, list[int | None]]] = field(default_factory=list)  # None: a month not read
+    size_histogram: list[int] = field(default_factory=list)  # commits per bucket of files changed
+    folder_depth: int = 2  # how deep the folder tiles group files
+    tile_cap: int = 60  # tiles a heat map level draws at most
+
+
+def folder_of(path: str, depth: int) -> str:
+    """The file's folder, at most `depth` levels deep; "." for a file at the root."""
+    return "/".join(path.split("/")[:-1][:depth]) or "."
+
+
+def _most_first(counts: Counter[str]) -> list[HotSpot]:
+    return [HotSpot(name, count) for name, count in sorted(counts.items(), key=lambda item: (-item[1], item[0]))]
+
+
+def _month(time: int) -> str:
+    return datetime.fromtimestamp(time, UTC).strftime("%Y-%m")
+
+
+def _last_months(today: date) -> list[str]:
+    year, month, months = today.year, today.month, []
+    for _ in range(MONTHS_SHOWN):
+        months.append(f"{year:04d}-{month:02d}")
+        year, month = (year, month - 1) if month > 1 else (year - 1, 12)
+    return months[::-1]
+
+
+def _bucket(size: int) -> int:
+    return next((index for index, bound in enumerate(SIZE_BUCKETS) if size <= bound), len(SIZE_BUCKETS))
+
+
+def _capped(tiles: list[HeatTile], cap: int) -> list[HeatTile]:
+    return sorted(tiles, key=lambda tile: (-tile.lines, tile.path))[:cap]
+
+
+def measure_churn(
+    changes: Sequence[tuple[int, Sequence[str]]],
+    allowed: Collection[str],
+    code_lines: Mapping[str, int],
+    recently_changed: Collection[str],
+    areas: Sequence[tuple[Page, list[str], int, int]],
+    today: date,
+    folder_depth: int,
+    tile_cap: int,
+    window: int,
+) -> Churn:
+    """`changes` holds each commit's time and paths, newest first; `areas` each area page with its scope and rationale.
+
+    `window` is how many commits were asked for: when that many came back, the history goes further back than was
+    read, and the grid's months before the oldest commit read are unread rather than quiet.
+    """
+    files: Counter[str] = Counter()
+    folders: Counter[str] = Counter()
+    by_area: Counter[str] = Counter()
+    by_area_month: Counter[tuple[str, str]] = Counter()
+    for time, paths in changes:
+        visible = {path for path in paths if path in allowed}
+        files.update(visible)
+        folders.update({folder_of(path, folder_depth) for path in visible})
+        for page, scope_paths, _documented, _inferred in areas:
+            if any(in_scope(path, scope_paths) for path in visible):
+                by_area[page.id] += 1
+                by_area_month[page.id, _month(time)] += 1
+    spots = [
+        AreaSpot(page, by_area[page.id], documented, inferred,
+                 sum(lines for path, lines in code_lines.items() if in_scope(path, scope_paths)), tuple(scope_paths))
+        for page, scope_paths, documented, inferred in areas
+    ]  # fmt: skip
+    spots.sort(key=lambda spot: (-spot.commits, spot.page.title))
+    folder_lines: Counter[str] = Counter()
+    for path, lines in code_lines.items():
+        folder_lines[folder_of(path, folder_depth)] += lines
+    folder_tiles = [HeatTile(name, name, lines, folders[name]) for name, lines in folder_lines.items()]
+    file_tiles = [HeatTile(path.rsplit("/", 1)[-1], path, lines, files[path]) for path, lines in code_lines.items()]
+    months = _last_months(today)
+    oldest = _month(changes[-1][0]) if changes and len(changes) >= window else None
+    area_months = [
+        (page.id, [None if oldest and month < oldest else by_area_month[page.id, month] for month in months])
+        for page, _scope, _documented, _inferred in areas
+    ]
+    quiet = [path for path in code_lines if path not in recently_changed]
+    sizes = [len(paths) for _time, paths in changes]
+    histogram = [0] * (len(SIZE_BUCKETS) + 1)
+    for size in sizes:
+        if size:
+            histogram[_bucket(size)] += 1
+    median = statistics.median(sizes) if sizes else None
+    # Inclusive: the default method extrapolates past the largest commit when there are few.
+    p90 = statistics.quantiles(sizes, n=10, method="inclusive")[8] if len(sizes) > 1 else median
+    left_out = {"areas": max(0, len(spots) - tile_cap), "folders": max(0, len(folder_tiles) - tile_cap),
+                "files": max(0, len(file_tiles) - tile_cap)}  # fmt: skip
+    return Churn(
+        len(changes), _most_first(files), _most_first(folders), spots,
+        _most_first(Counter(folder_of(path, folder_depth) for path in quiet)), len(quiet), median, p90,
+        _capped(folder_tiles, tile_cap), _capped(file_tiles, tile_cap), left_out, months, area_months, histogram,
+        folder_depth, tile_cap,
+    )  # fmt: skip

codetrail/metrics/commits.py

@@ -0,0 +1,45 @@
+"""Commits that explain why (design section 18.1).
+
+A commit explains why when its body matches the target's `commit_why_pattern`; otherwise it has a body without a why,
+or only a subject. A message gitleaks withheld is counted apart and left out of the share.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from codetrail.repo.history import WITHHELD_MESSAGE, Commit
+
+
+@dataclass(frozen=True)
+class CommitMetric:
+    explains_why: int
+    body_only: int
+    subject_only: int
+    withheld: int
+    without_why: list[Commit]  # in the order given: newest first
+
+    @property
+    def measured(self) -> int:
+        """The share's denominator: every commit but the withheld ones."""
+        return self.explains_why + self.body_only + self.subject_only
+
+
+def measure_commits(commits: Iterable[Commit], why: re.Pattern[str], max_chars: int = 20_000) -> CommitMetric:
+    """Sorts each commit into one level; only the start of a body is matched, so no message can make it slow."""
+    explains_why = body_only = subject_only = withheld = 0
+    without_why = []
+    for commit in commits:
+        if commit.subject == WITHHELD_MESSAGE:
+            withheld += 1
+        elif why.search(commit.body[:max_chars]):
+            explains_why += 1
+        else:
+            without_why.append(commit)
+            if commit.body:
+                body_only += 1
+            else:
+                subject_only += 1
+    return CommitMetric(explains_why, body_only, subject_only, withheld, without_why)

codetrail/metrics/coverage.py

@@ -0,0 +1,114 @@
+"""Facts a document mentions, and facts the guide explains (design section 18.1).
+
+A mention isn't a reason: this only shows which dependencies, projects and resources some document names. Names are
+looked up in the set of a document's words, so no regular expression is ever built from a name a repository controls.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from codetrail.facts import Entity, EntityKind
+from codetrail.generate.outline import OutlineEntry
+from codetrail.generate.scope import entities_in_scope
+from codetrail.guide import Page
+from codetrail.metrics.rationale import guide_pages
+
+MENTIONABLE = (EntityKind.PACKAGE, EntityKind.PROJECT, EntityKind.RESOURCE)
+WORD = re.compile(r"[A-Za-z0-9@/._-]+")
+SEPARATORS = re.compile(r"[-_.]+")
+
+
+def normalise(word: str) -> str:
+    """Lower-cased, with each run of `-`, `_` and `.` made one `-`, as Python distribution names are compared."""
+    return SEPARATORS.sub("-", word.lower()).strip("-/")
+
+
+def words_of(text: str) -> set[str]:
+    """Every word of the text, and each part of a word with slashes, normalised."""
+    words = set()
+    for token in WORD.findall(text):
+        words.add(normalise(token))
+        words.update(normalise(part) for part in token.split("/"))
+    words.discard("")
+    return words
+
+
+def mention_name(entity: Entity) -> str:
+    """What a document names: a package's name, a project's folder, a resource's address."""
+    key = entity.id.split(":", 1)[1]
+    if entity.kind == EntityKind.PACKAGE:
+        return normalise(key.split("/", 1)[-1])  # after the ecosystem: pypi/, npm/, swift/
+    if entity.kind == EntityKind.RESOURCE:
+        return normalise(key.rsplit("/", 1)[-1])
+    return normalise(key)
+
+
+def _folder(path: str) -> str:
+    parent = str(PurePosixPath(path).parent)
+    return "" if parent == "." else parent
+
+
+@dataclass(frozen=True)
+class MentionMetric:
+    mentioned: list[Entity]
+    unmentioned: list[Entity]
+
+
+def measure_mentions(entities: Iterable[Entity], documents: Mapping[str, str]) -> MentionMetric:
+    words: set[str] = set()
+    for text in documents.values():
+        words |= words_of(text)
+    readme_folders = {_folder(path) for path in documents if PurePosixPath(path).name.lower().startswith("readme")}
+    mentioned: list[Entity] = []
+    unmentioned: list[Entity] = []
+    for entity in sorted(entities, key=lambda found: found.id):
+        if entity.kind not in MENTIONABLE:
+            continue
+        if entity.kind == EntityKind.PROJECT:
+            folder = entity.id.split(":", 1)[1]
+            found = (("" if folder == "." else folder) in readme_folders) or (folder != "." and
+                                                                             mention_name(entity) in words)  # fmt: skip
+        else:
+            found = mention_name(entity) in words
+        (mentioned if found else unmentioned).append(entity)
+    return MentionMetric(mentioned, unmentioned)
+
+
+def _strings(value: object) -> list[str] | None:
+    if isinstance(value, list) and all(isinstance(item, str) for item in value):
+        return value
+    return None
+
+
+def page_scope(page: Page) -> OutlineEntry | None:
+    """The scope a written page records (design section 4.3), or None when its front matter isn't usable."""
+    scope = page.meta.get("scope", {})
+    facts = page.meta.get("facts", [])
+    if not isinstance(scope, dict) or not isinstance(facts, list):
+        return None
+    paths, kinds = _strings(scope.get("paths", [])), _strings(scope.get("kinds", []))
+    if paths is None or kinds is None or not all(isinstance(fact, dict) and isinstance(fact.get("id"), str)
+                                                 for fact in facts):  # fmt: skip
+        return None
+    return OutlineEntry(page.id, page.kind, page.title, paths, kinds, [fact["id"] for fact in facts])
+
+
+@dataclass(frozen=True)
+class ExplainedMetric:
+    explained: int
+    total: int
+    unexplained: list[Entity]
+
+
+def measure_explained(entities: list[Entity], pages: Iterable[Page]) -> ExplainedMetric:
+    explained: set[str] = set()
+    for page in guide_pages(pages):
+        entry = page_scope(page)
+        if entry is not None:
+            explained.update(entity.id for entity in entities_in_scope(entities, entry))
+    unexplained = sorted((entity for entity in entities if entity.id not in explained), key=lambda found: found.id)
+    return ExplainedMetric(len(entities) - len(unexplained), len(entities), unexplained)

codetrail/metrics/decisions.py

@@ -0,0 +1,77 @@
+"""ADR health: statuses, proposed ADRs waiting too long, and which ADRs the guide cites (design section 18.1).
+
+A page cites an ADR with a documented block quoting its file, a `[[decision:…]]` link, or the ADR in its front
+matter's `facts`. Only area and concept pages count, as for the documented share.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import date
+
+from codetrail.facts import Entity
+from codetrail.generate.validate import FACT_LINK, parse_rationale
+from codetrail.guide import Page
+from codetrail.metrics.rationale import guide_pages
+
+RETIRED = ("superseded", "deprecated")
+
+
+@dataclass(frozen=True)
+class DecisionMetric:
+    by_status: dict[str, list[Entity]]  # "none" when an ADR states no status
+    overdue: list[Entity]
+    undated: list[Entity]  # proposed, with no usable date
+    superseded_cited: list[Entity]  # superseded or deprecated, still cited
+    uncited: list[Entity]  # accepted, cited by no page
+
+    @property
+    def attention(self) -> int:
+        return len(self.overdue) + len(self.superseded_cited)
+
+
+def cited_decisions(pages: Iterable[Page], decisions: Iterable[Entity]) -> set[str]:
+    by_path = {str(decision.attributes.get("path", "")): decision.id for decision in decisions}
+    cited: set[str] = set()
+    for page in guide_pages(pages):
+        cited.update(FACT_LINK.findall(page.body))
+        for block in parse_rationale(page.body):
+            if block.kind == "documented" and block.citation:
+                cited.add(by_path.get(block.citation.split("#", 1)[0], ""))
+        facts = page.meta.get("facts")
+        for fact in facts if isinstance(facts, list) else []:
+            if isinstance(fact, dict):
+                cited.add(str(fact.get("id", "")))
+    return cited
+
+
+def written_on(decision: Entity) -> date | None:
+    """The ADR's `Date:`, or None when it gives none Python can read."""
+    try:
+        return date.fromisoformat(str(decision.attributes.get("date", "")))
+    except ValueError:
+        return None
+
+
+def measure_decisions(
+    decisions: Iterable[Entity], pages: Iterable[Page], today: date, proposed_days: int
+) -> DecisionMetric:
+    found = sorted(decisions, key=lambda decision: decision.id)
+    cited = cited_decisions(pages, found)
+    by_status: dict[str, list[Entity]] = {}
+    overdue, undated, superseded_cited, uncited = [], [], [], []
+    for decision in found:
+        status = str(decision.attributes.get("status") or "none")
+        by_status.setdefault(status, []).append(decision)
+        if status == "proposed":
+            written = written_on(decision)
+            if written is None:
+                undated.append(decision)
+            elif (today - written).days > proposed_days:
+                overdue.append(decision)
+        elif status in RETIRED and decision.id in cited:
+            superseded_cited.append(decision)
+        elif status == "accepted" and decision.id not in cited:
+            uncited.append(decision)
+    return DecisionMetric(by_status, overdue, undated, superseded_cited, uncited)

codetrail/metrics/history.py

@@ -0,0 +1,47 @@
+"""Each metric's value per update, in the `metric_values` table, for the trend (design section 18.3)."""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Mapping
+
+from codetrail.metrics.report import Metric, Value
+
+KNOWN = {str(metric) for metric in Metric}
+
+
+def record_values(connection: sqlite3.Connection, snapshot_id: int, values: Mapping[Metric, Value]) -> None:
+    """Replaces the snapshot's values with these, in one transaction."""
+    connection.execute("BEGIN")
+    try:
+        connection.execute("DELETE FROM metric_values WHERE snapshot = ?", (snapshot_id,))
+        connection.executemany(
+            "INSERT INTO metric_values (snapshot, metric, numerator, denominator) VALUES (?, ?, ?, ?)",
+            [(snapshot_id, str(metric), value.numerator, value.denominator) for metric, value in values.items()],
+        )
+        connection.execute("COMMIT")
+    except BaseException:
+        if connection.in_transaction:  # SQLite ends it itself after some errors
+            connection.execute("ROLLBACK")
+        raise
+
+
+def recent_values(connection: sqlite3.Connection, metric: Metric, limit: int) -> list[tuple[int, Value]]:
+    """The metric's last `limit` values with their snapshots, oldest first."""
+    rows = connection.execute(
+        "SELECT snapshot, numerator, denominator FROM metric_values WHERE metric = ? ORDER BY snapshot DESC LIMIT ?",
+        (str(metric), limit),
+    ).fetchall()
+    return [(row["snapshot"], Value(row["numerator"], row["denominator"])) for row in reversed(rows)]
+
+
+def values_before(connection: sqlite3.Connection, snapshot_id: int) -> dict[Metric, Value]:
+    """The values of the latest update before the snapshot that recorded any."""
+    rows = connection.execute(
+        "SELECT metric, numerator, denominator FROM metric_values"
+        " WHERE snapshot = (SELECT MAX(snapshot) FROM metric_values WHERE snapshot < ?)",
+        (snapshot_id,),
+    )
+    return {
+        Metric(row["metric"]): Value(row["numerator"], row["denominator"]) for row in rows if row["metric"] in KNOWN
+    }