docs: add doctests to repos.py and localgit.py helpers (#80)

collector/jq_collector/localgit.py

@@ -139,6 +139,9 @@ def _fingerprint(head_sha: str, branch_sha: str, dirty: int, untracked: int, tag
     guards each depend on one of them: the line counts on the working copy
     (head, dirty, untracked), the commit counts on the default branch, the
     release counter on the tags.
+
+    >>> _fingerprint("abc", "def", 2, 0, 1767225600.25)
+    'abc:def:2:0:1767225600.250000'
     """
     # Sub-second precision on the mtime is not fussiness: cutting a release and
     # the scan that follows it land in the same second often enough, and a
@@ -164,6 +167,15 @@ def _fingerprint(head_sha: str, branch_sha: str, dirty: int, untracked: int, tag
 
 
 def _is_test(rel: str) -> bool:
+    """Whether a tracked path counts toward the test half of the line split.
+
+    >>> _is_test("tests/unit/helpers.py"), _is_test("src/pkg/test_io.py")
+    (True, True)
+    >>> _is_test("cmd/server_test.go"), _is_test("web/app.test.ts")
+    (True, True)
+    >>> _is_test("src/pkg/contest.py"), _is_test("src/testing_utils.py")
+    (False, False)
+    """
     *parents, base = rel.split("/")
     if any(part in _TEST_DIRS for part in parents):
         return True

collector/jq_collector/repos.py

@@ -54,6 +54,15 @@ def resolve_path(raw: str, host_root: str) -> str:
     against. An absolute path is tried as written first - it is right when the
     collector runs natively - and only then under the mount, which is what a
     whole-root mount (``-v /:/host:ro``) makes work.
+
+    >>> resolve_path("~/repos/rhiza", "/host")
+    '/host/repos/rhiza'
+    >>> resolve_path("repos/rhiza", "/host")
+    '/host/repos/rhiza'
+    >>> resolve_path("~", "/host")
+    '/host'
+    >>> resolve_path("/no/such/checkout", "/host")
+    '/host/no/such/checkout'
     """
     raw = raw.strip()
     if not host_root:
@@ -83,6 +92,15 @@ def _declared_forge(item: dict[str, Any], index: int) -> str | None:
     An unknown value is refused rather than defaulted. Silently reading
     ``forge: gitbucket`` as GitHub would put a repo on the board with every
     remote panel wrong and nothing saying why.
+
+    >>> _declared_forge({"forge": " GitLab "}, 0)
+    'gitlab'
+    >>> _declared_forge({"repo": "o/r"}, 0) is None
+    True
+    >>> _declared_forge({"forge": "gitbucket"}, 3)
+    Traceback (most recent call last):
+    ...
+    jq_collector.repos.FleetError: entry 3: forge 'gitbucket' is not one of github, gitlab
     """
     declared = str(item.get("forge") or "").strip().lower()
     if not declared: