codetrail-cli 1.4.1__py3-none-any.whl

codetrail/metrics/inventory.py

@@ -0,0 +1,63 @@
+"""Facts by kind, and the dependencies that arrived and left, from the validity ranges (design section 19.1).
+
+Codetrail's history of a repository starts with its first snapshot: packages present then were there from the start,
+not arrivals.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from codetrail.facts import EntityKind, Snapshot
+from codetrail.facts.store import FactStore
+
+
+@dataclass(frozen=True)
+class KindCount:
+    kind: str
+    count: int
+    change: int | None  # since the previous snapshot
+    trend: list[int]  # over the last snapshots, oldest first
+
+
+@dataclass(frozen=True)
+class Change:
+    package: str
+    snapshot: Snapshot  # the snapshot that first saw it, or first no longer saw it
+
+
+@dataclass(frozen=True)
+class Inventory:
+    since: Snapshot | None  # the first snapshot: where Codetrail's history of the repository starts
+    kinds: list[KindCount]  # the most facts first
+    arrived: list[Change]  # newest first
+    left: list[Change]  # newest first
+
+
+def measure_inventory(store: FactStore, trend_updates: int) -> Inventory:
+    snapshots = store.snapshots()
+    if not snapshots:
+        return Inventory(None, [], [], [])
+    recent = snapshots[-trend_updates:]
+    counts = store.entity_counts([snapshot.id for snapshot in recent])
+    latest = counts[recent[-1].id]
+    previous = counts[recent[-2].id] if len(recent) > 1 else None
+    kinds = [
+        KindCount(kind, count, None if previous is None else count - previous.get(kind, 0),
+                  [counts[snapshot.id].get(kind, 0) for snapshot in recent])
+        for kind, count in sorted(latest.items(), key=lambda item: (-item[1], item[0]))
+    ]  # fmt: skip
+    by_id = {snapshot.id: snapshot for snapshot in snapshots}
+    arrived, left = [], []
+    for package, first, last in store.entity_spans(EntityKind.PACKAGE):
+        if first > snapshots[0].id:
+            arrived.append(Change(package, by_id[first]))
+        if last is not None:
+            after = next((snapshot for snapshot in snapshots if snapshot.id > last), None)
+            if after is not None:
+                left.append(Change(package, after))
+    return Inventory(snapshots[0], kinds, sorted(arrived, key=_newest_first), sorted(left, key=_newest_first))
+
+
+def _newest_first(change: Change) -> tuple[int, str]:
+    return -change.snapshot.id, change.package

codetrail/metrics/rationale.py

@@ -0,0 +1,74 @@
+"""The documented share of the guide's rationale, by source type and by page (design section 18.1).
+
+Only area and concept pages count: digests accumulate and are mostly about commits, and saved answers follow the
+reader's questions rather than the repository.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from pathspec import GitIgnoreSpec
+
+from codetrail.generate.validate import parse_rationale
+from codetrail.guide import Page
+
+GUIDE_KINDS = ("area", "concept")
+SOURCE_KINDS = ("adr", "docs", "code", "commit")
+
+
+@dataclass(frozen=True)
+class InferredBlock:
+    page: Page
+    first_line: str
+
+
+@dataclass(frozen=True)
+class PageRationale:
+    page: Page
+    documented: int
+    inferred: int
+
+
+@dataclass(frozen=True)
+class RationaleMetric:
+    documented: int
+    inferred: int
+    by_source: dict[str, int]
+    pages: list[PageRationale]  # most inferred first, then by title
+    inferred_blocks: list[InferredBlock]
+
+
+def guide_pages(pages: Iterable[Page]) -> list[Page]:
+    return [page for page in pages if page.kind in GUIDE_KINDS]
+
+
+def citation_source(citation: str, adr: GitIgnoreSpec, documents: GitIgnoreSpec) -> str:
+    """Where a documented block's quote comes from: a commit, an ADR, another document, or code (a comment)."""
+    if citation.startswith("commit:"):
+        return "commit"
+    path = citation.split("#", 1)[0]
+    if adr.match_file(path):
+        return "adr"
+    return "docs" if documents.match_file(path) else "code"
+
+
+def measure_rationale(pages: Iterable[Page], adr: GitIgnoreSpec, documents: GitIgnoreSpec) -> RationaleMetric:
+    by_source = dict.fromkeys(SOURCE_KINDS, 0)
+    rows: list[PageRationale] = []
+    inferred_blocks: list[InferredBlock] = []
+    for page in guide_pages(pages):
+        documented = inferred = 0
+        for block in parse_rationale(page.body):
+            if block.kind == "documented":
+                documented += 1
+                by_source[citation_source(block.citation or "", adr, documents)] += 1
+            else:
+                inferred += 1
+                inferred_blocks.append(InferredBlock(page, next(iter(block.text.splitlines()), "")))
+        rows.append(PageRationale(page, documented, inferred))
+    rows.sort(key=lambda row: (-row.inferred, row.page.title.casefold(), row.page.id))
+    inferred_blocks.sort(key=lambda block: block.page.id)  # stable: a page's blocks stay in order
+    return RationaleMetric(sum(row.documented for row in rows), sum(row.inferred for row in rows), by_source, rows,
+                           inferred_blocks)  # fmt: skip

codetrail/metrics/releases.py

@@ -0,0 +1,26 @@
+"""Releases: the target's tags that point into the branch's history (design section 19.1)."""
+
+from __future__ import annotations
+
+import statistics
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from itertools import pairwise
+
+from codetrail.repo.history import Tag
+
+DAY_SECONDS = 86_400
+
+
+@dataclass(frozen=True)
+class Releases:
+    tags: list[Tag] = field(default_factory=list)  # newest first
+    since_latest: int | None = None  # commits after the latest release
+    median_days: int | None = None  # between consecutive releases
+
+
+def measure_releases(tags: Sequence[Tag], since_latest: int | None) -> Releases:
+    newest_first = sorted(tags, key=lambda tag: (tag.date, tag.name), reverse=True)
+    gaps = [newer.date - older.date for newer, older in pairwise(newest_first)]
+    median = round(statistics.median(gaps) / DAY_SECONDS) if gaps else None
+    return Releases(newest_first, since_latest, median)

codetrail/metrics/report.py

@@ -0,0 +1,111 @@
+"""The documentation metrics' report: every metric, read from the target's data (design section 18.2).
+
+Documents are read from `source/` through the allowed-files reader, so excluded and secret files are never read; commits
+come from the filtered history, with flagged messages withheld. If the history can't be read, the commit metric is
+missing and the rest of the report stands.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import date
+from enum import StrEnum
+
+from pathspec import GitIgnoreSpec
+
+from codetrail.config import GlobalConfig, Paths, load_target
+from codetrail.errors import CodetrailError
+from codetrail.facts import EntityKind
+from codetrail.facts.store import FactStore
+from codetrail.guide import GuideRepository
+from codetrail.metrics.commits import CommitMetric, measure_commits
+from codetrail.metrics.coverage import ExplainedMetric, MentionMetric, measure_explained, measure_mentions
+from codetrail.metrics.decisions import DecisionMetric, measure_decisions
+from codetrail.metrics.rationale import RationaleMetric, measure_rationale
+from codetrail.repo.history import latest_commits
+from codetrail.repo.secrets import SecretScanner
+from codetrail.repo.source import SourceManifest, allowed_reader
+
+logger = logging.getLogger(__name__)
+
+
+class Metric(StrEnum):
+    DOCUMENTED_SHARE = "documented_share"
+    COMMIT_WHY_SHARE = "commit_why_share"
+    ADR_ATTENTION = "adr_attention"
+    MENTIONED_SHARE = "mentioned_share"
+    EXPLAINED_SHARE = "explained_share"
+    # The repository statistics recorded for their trend (design section 19.4)
+    COMMITS = "commits"
+    CODE_LINES = "code_lines"
+    SOURCE_FILES = "source_files"
+    TEST_SHARE = "test_share"
+
+
+@dataclass(frozen=True)
+class Value:
+    numerator: int
+    denominator: int | None  # None for a count
+
+    @property
+    def share(self) -> float | None:
+        """The share, or None for a count or when there was nothing to measure."""
+        return self.numerator / self.denominator if self.denominator else None
+
+
+@dataclass(frozen=True)
+class MetricsReport:
+    rationale: RationaleMetric
+    commits: CommitMetric | None  # None when the history couldn't be read
+    decisions: DecisionMetric
+    mentions: MentionMetric
+    explained: ExplainedMetric
+
+    def values(self) -> dict[Metric, Value]:
+        rationale, mentions = self.rationale, self.mentions
+        values = {
+            Metric.DOCUMENTED_SHARE: Value(rationale.documented, rationale.documented + rationale.inferred),
+            Metric.ADR_ATTENTION: Value(self.decisions.attention, None),
+            Metric.MENTIONED_SHARE: Value(len(mentions.mentioned), len(mentions.mentioned) + len(mentions.unmentioned)),
+            Metric.EXPLAINED_SHARE: Value(self.explained.explained, self.explained.total),
+        }
+        if self.commits is not None:
+            values[Metric.COMMIT_WHY_SHARE] = Value(self.commits.explains_why, self.commits.measured)
+        return {metric: values[metric] for metric in Metric if metric in values}
+
+
+def build_report(paths: Paths, name: str, settings: GlobalConfig, store: FactStore, today: date) -> MetricsReport:
+    target = load_target(paths, name)
+    data = paths.target_data(name)
+    guide = GuideRepository(data / "guide")
+    pages = guide.pages() if guide.root.exists() else []
+    manifest = SourceManifest.load(data / "source.json")
+    files = manifest.files if manifest else {}
+    document_globs = GitIgnoreSpec.from_lines(target.metrics.document_globs)
+    read = allowed_reader(data / "source", files, settings.extract.max_file_bytes)
+    documents = {}
+    for path in files:
+        if document_globs.match_file(path):
+            content = read(path)
+            # An image under docs/ matches the globs but isn't text: its bytes would cost time and fake mentions.
+            # A NUL byte marks it binary, as the code size counts it (metrics/size.py).
+            if content is not None and b"\0" not in content:
+                documents[path] = content.decode("utf-8", "replace")
+    commits = None
+    if manifest is not None:
+        try:
+            found = latest_commits(data / "mirror.git", manifest.commit, settings.metrics.commit_window,
+                                   SecretScanner(settings.tools))  # fmt: skip
+            commits = measure_commits(found, target.metrics.why, settings.metrics.max_message_chars)
+        except (CodetrailError, OSError) as error:
+            logger.warning("The commit metric isn't available: %s", error)
+    entities = store.entities()
+    decisions = [entity for entity in entities if entity.kind == EntityKind.DECISION]
+    return MetricsReport(
+        measure_rationale(pages, GitIgnoreSpec.from_lines(target.adr.paths), document_globs),
+        commits,
+        measure_decisions(decisions, pages, today, settings.metrics.proposed_adr_days),
+        measure_mentions(entities, documents),
+        measure_explained(entities, pages),
+    )

codetrail/metrics/repository.py

@@ -0,0 +1,128 @@
+"""The repository statistics' report: history, releases, code size and facts, read from the target's data (19.3).
+
+Files are read from `source/` through the allowed-files reader, so excluded and secret files are never read; commit
+subjects and tags pass gitleaks first. If the history or the tags can't be read, those parts are missing and the rest of
+the report stands.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, replace
+from datetime import UTC, date, datetime, timedelta
+from pathlib import Path
+
+from pathspec import GitIgnoreSpec
+
+from codetrail.config import GlobalConfig, Paths, load_target
+from codetrail.errors import CodetrailError
+from codetrail.facts.store import FactStore
+from codetrail.guide import GuideRepository, Page
+from codetrail.metrics.activity import Activity, CommitTypes, measure_activity, measure_types
+from codetrail.metrics.churn import Churn, measure_churn
+from codetrail.metrics.coverage import page_scope
+from codetrail.metrics.inventory import Inventory, measure_inventory
+from codetrail.metrics.rationale import measure_rationale
+from codetrail.metrics.releases import Releases, measure_releases
+from codetrail.metrics.report import Metric, Value
+from codetrail.metrics.size import CodeSize, measure_size
+from codetrail.repo.history import (
+    changed_files,
+    commit_count,
+    commit_times,
+    commit_totals,
+    files_changed_since,
+    first_commit_time,
+    latest_commits,
+    read_tags,
+)
+from codetrail.repo.secrets import SecretScanner
+from codetrail.repo.source import SourceManifest, allowed_reader
+
+logger = logging.getLogger(__name__)
+# A part that fails these ways is unavailable and the rest of the report stands. ValueError and OverflowError come
+# from a date past the year 9999, which a commit or tag can claim and Python's dates can't hold.
+UNREADABLE = (CodetrailError, OSError, ValueError, OverflowError)
+
+
+@dataclass(frozen=True)
+class RepositoryReport:
+    activity: Activity | None  # None when the history couldn't be read
+    types: CommitTypes | None  # None, with the releases, when the commits or tags couldn't be read
+    releases: Releases | None
+    size: CodeSize
+    inventory: Inventory
+    churn: Churn | None = None  # None when the history couldn't be read
+
+    def values(self) -> dict[Metric, Value]:
+        """The statistics recorded per update for their trend (design section 19.4)."""
+        size = self.size
+        values = {
+            Metric.CODE_LINES: Value(size.code_lines, None),
+            Metric.SOURCE_FILES: Value(size.files, None),
+            Metric.TEST_SHARE: Value(size.test_lines, size.code_lines),
+        }
+        if self.activity is not None:
+            values[Metric.COMMITS] = Value(self.activity.commits, None)
+        return {metric: values[metric] for metric in Metric if metric in values}
+
+
+def build_repository_report(
+    paths: Paths, name: str, settings: GlobalConfig, store: FactStore, today: date
+) -> RepositoryReport:
+    target = load_target(paths, name)
+    data = paths.target_data(name)
+    manifest = SourceManifest.load(data / "source.json")
+    files = manifest.files if manifest else {}
+    read = allowed_reader(data / "source", files, settings.extract.max_file_bytes)
+    documents = GitIgnoreSpec.from_lines(target.metrics.document_globs)
+    tests = GitIgnoreSpec.from_lines(target.metrics.test_globs)
+    size = measure_size(files, read, settings.metrics.languages, documents, tests)
+    activity = types = releases = churn = None
+    if manifest is not None:
+        mirror, end = data / "mirror.git", manifest.commit
+        try:
+            commits, merges = commit_totals(mirror, end)
+            times = commit_times(mirror, end, settings.metrics.history_limit)
+            activity = measure_activity(times, commits, merges, today, settings.metrics.activity_months)
+            first = first_commit_time(mirror, end) if activity.cut else None
+            if first is not None:  # the times read stop short of the first commit
+                activity = replace(activity, first=datetime.fromtimestamp(first, UTC).date())
+        except UNREADABLE as error:
+            logger.warning("The history isn't available: %s", error)
+        try:
+            scanner = SecretScanner(settings.tools)
+            latest = latest_commits(mirror, end, settings.metrics.commit_window, scanner)
+            types = measure_types(latest, target.metrics.types, settings.metrics.max_message_chars)
+            tags = read_tags(mirror, end, scanner)
+            newest = max(tags, key=lambda tag: (tag.date, tag.name), default=None)
+            releases = measure_releases(tags, commit_count(mirror, newest.commit, end) if newest else None)
+        except UNREADABLE as error:
+            types = None
+            logger.warning("The commit types and releases aren't available: %s", error)
+        try:
+            changes = changed_files(mirror, end, settings.metrics.churn_window)
+            recent = files_changed_since(mirror, end, today - timedelta(days=settings.metrics.quiet_days))
+            code_lines = {file.path: file.lines for file in size.largest}
+            areas = _areas(data / "guide", target.adr.paths, target.metrics.document_globs)
+            metrics = settings.metrics
+            churn = measure_churn(changes, files, code_lines, recent, areas, today, metrics.folder_depth,
+                                  metrics.heatmap_tiles, metrics.churn_window)  # fmt: skip
+        except UNREADABLE as error:
+            logger.warning("Where change happens isn't available: %s", error)
+    inventory = measure_inventory(store, settings.metrics.trend_updates)
+    return RepositoryReport(activity, types, releases, size, inventory, churn)
+
+
+def _areas(guide_root: Path, adr_paths: list[str], document_globs: list[str]) -> list[tuple[Page, list[str], int, int]]:
+    """Each area page with a usable scope, with its documented and inferred rationale blocks."""
+    guide = GuideRepository(guide_root)
+    pages = guide.pages() if guide.root.exists() else []
+    rationale = measure_rationale(pages, GitIgnoreSpec.from_lines(adr_paths), GitIgnoreSpec.from_lines(document_globs))
+    counts = {row.page.id: (row.documented, row.inferred) for row in rationale.pages}
+    areas = []
+    for page in pages:
+        entry = page_scope(page) if page.kind == "area" else None
+        if entry is not None:
+            areas.append((page, entry.scope_paths, *counts.get(page.id, (0, 0))))
+    return areas

codetrail/metrics/size.py

@@ -0,0 +1,95 @@
+"""Code size: files and lines by language, documents and tests (design section 19.1).
+
+A file's language is looked up by its name, then its suffix, in the configured map: a dictionary lookup, never a
+pattern a repository could control.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from pathspec import GitIgnoreSpec
+
+
+@dataclass(frozen=True)
+class LanguageSize:
+    language: str
+    files: int
+    lines: int
+
+
+@dataclass(frozen=True)
+class FileSize:
+    path: str
+    language: str
+    lines: int
+
+
+@dataclass(frozen=True)
+class CodeSize:
+    files: int  # every allowed file
+    languages: list[LanguageSize]  # the most lines first
+    documents: LanguageSize
+    other_files: int  # in no language
+    binary_files: int
+    too_large_files: int  # over extract.max_file_bytes, or unreadable
+    code_lines: int  # lines in files with a language, tests included
+    test_lines: int
+    largest: list[FileSize]  # files with a language, the most lines first
+
+
+def count_lines(content: bytes) -> int:
+    """The newline bytes, plus one for a last line without one."""
+    return content.count(b"\n") + (1 if content and not content.endswith(b"\n") else 0)
+
+
+def language_of(path: str, languages: Mapping[str, str]) -> str | None:
+    name = PurePosixPath(path).name.lower()
+    if not name.startswith(".") and name in languages:
+        return languages[name]
+    suffix = PurePosixPath(name).suffix
+    return languages.get(suffix) if suffix else None
+
+
+def measure_size(
+    paths: Iterable[str],
+    read: Callable[[str], bytes | None],
+    languages: Mapping[str, str],
+    documents: GitIgnoreSpec,
+    tests: GitIgnoreSpec,
+) -> CodeSize:
+    """Reads each allowed file once and sorts it: too large, binary, a document, a language or other."""
+    files = other = binary = too_large = document_files = document_lines = test_lines = 0
+    by_language: dict[str, list[int]] = {}
+    largest = []
+    for path in paths:
+        files += 1
+        content = read(path)
+        if content is None:
+            too_large += 1
+            continue
+        if b"\0" in content:
+            binary += 1
+            continue
+        lines = count_lines(content)
+        if documents.match_file(path):
+            document_files += 1
+            document_lines += lines
+            continue
+        language = language_of(path, languages)
+        if language is None:
+            other += 1
+            continue
+        counts = by_language.setdefault(language, [0, 0])
+        counts[0] += 1
+        counts[1] += lines
+        largest.append(FileSize(path, language, lines))
+        if tests.match_file(path):
+            test_lines += lines
+    sizes = [LanguageSize(language, counts[0], counts[1]) for language, counts in by_language.items()]
+    sizes.sort(key=lambda size: (-size.lines, -size.files, size.language))
+    largest.sort(key=lambda file: (-file.lines, file.path))
+    return CodeSize(files, sizes, LanguageSize("Documents", document_files, document_lines), other, binary,
+                    too_large, sum(size.lines for size in sizes), test_lines, largest)  # fmt: skip

codetrail/remove.py

@@ -0,0 +1,50 @@
+"""Removing a target: everything Codetrail keeps for it, never the repository it teaches (AGENTS.md, Never do, 6)."""
+
+from __future__ import annotations
+
+import shutil
+import tomllib
+from collections.abc import Callable
+from pathlib import Path
+
+from codetrail.config import Paths, check_containment, validate_target_name
+from codetrail.errors import CodetrailError
+from codetrail.lock import existing_target_lock, target_removal
+
+
+def remove_target(paths: Paths, name: str, confirm: Callable[[list[Path]], bool]) -> bool:
+    """Shows `confirm` the target's existing locations and deletes them if it agrees; returns whether it did.
+
+    The settings file goes last, and its lock is held until then: a removal that fails part way leaves a target
+    that can be removed again, and no command can start using the target meanwhile."""
+    settings = paths.target_file(validate_target_name(name))
+    if not settings.exists():
+        raise CodetrailError(f"No target named {name!r}.")
+    repository = _repository(settings)
+    if repository is not None:  # the XDG variables may have moved Codetrail's folders since the target was added
+        check_containment(paths, repository)
+    data = paths.target_data(name)
+    locations = [data, paths.target_state(name), paths.ignore_file(name), settings]
+    if not confirm([location for location in locations if _exists(location)]):
+        return False
+    # Refused while serve, update or files uses the target, or an update runs.
+    with target_removal(paths, name), existing_target_lock(paths, name):
+        for location in locations:
+            if location.is_dir() and not location.is_symlink():
+                shutil.rmtree(location)  # never follows a symlink inside the folder
+            elif _exists(location):
+                location.unlink()  # a file, or a symlink: the link goes, never what it points to
+    return True
+
+
+def _exists(location: Path) -> bool:
+    return location.is_symlink() or location.exists()
+
+
+def _repository(settings: Path) -> Path | None:
+    """The target's repository, if its settings still say; a broken file mustn't stop the target being removed."""
+    try:
+        repository = tomllib.loads(settings.read_text(encoding="utf-8")).get("repository")
+    except OSError, UnicodeDecodeError, tomllib.TOMLDecodeError:
+        return None
+    return Path(repository) if isinstance(repository, str) else None

codetrail/repo/__init__.py

@@ -0,0 +1,4 @@
+"""Everything that reads a target repository: the mirror, the exclusion rules, the sources and their history.
+
+Every other module reads a target only through this package (design section 2.2).
+"""

codetrail/repo/git.py

@@ -0,0 +1,56 @@
+"""Runs git for Codetrail: argument lists only, never a shell, never a prompt."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from collections.abc import Sequence
+from contextlib import suppress
+from pathlib import Path
+
+from codetrail.errors import CodetrailError
+
+# How long a git stopped early gets to remove its lock files before it's killed; it needs only a moment.
+STOP_WAIT_SECONDS = 5
+
+
+def run_git(
+    arguments: Sequence[str],
+    *,
+    git_dir: Path | None = None,
+    work_tree: Path | None = None,
+    input: bytes | None = None,
+    allowed_exit_codes: Sequence[int] = (0,),
+) -> bytes:
+    """Runs git and returns its standard output; any other exit code raises a CodetrailError with git's message."""
+    command = ["git"]
+    if git_dir is not None:
+        command.append(f"--git-dir={git_dir}")
+    if work_tree is not None:
+        command.append(f"--work-tree={work_tree}")
+    command.extend(arguments)
+    environment = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
+    environment["GIT_TERMINAL_PROMPT"] = "0"
+    # Run from the file system's root and stop repository discovery there: git never finds a repository (a
+    # target's, or another user's in a shared temporary folder) from where it runs.
+    environment["GIT_CEILING_DIRECTORIES"] = "/"
+    with subprocess.Popen(  # noqa: S603
+        command, stdin=subprocess.PIPE if input is not None else None, stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE, env=environment, cwd="/",
+    ) as process:  # fmt: skip
+        try:
+            stdout, stderr = process.communicate(input)
+        except BaseException:
+            # Stopped early (Ctrl-C, a hangup or terminate signal): SIGTERM lets git remove its lock files, which
+            # SIGKILL would leave behind to fail every later command in that repository.
+            try:
+                process.terminate()
+                with suppress(subprocess.TimeoutExpired):
+                    process.wait(STOP_WAIT_SECONDS)
+            finally:
+                process.kill()  # does nothing once git has exited
+            raise
+    if process.returncode not in allowed_exit_codes:
+        message = stderr.decode("utf-8", "replace").strip() or f"exit code {process.returncode}"
+        raise CodetrailError(f"git {arguments[0]} failed: {message}")
+    return stdout

codetrail/repo/gitleaks.toml

@@ -0,0 +1,6 @@
+# Codetrail's gitleaks configuration (ADR 0002). It is always passed with --config, so a target's own .gitleaks.toml,
+# a GITLEAKS_CONFIG setting or a .gitleaksignore can't change what is found.
+title = "codetrail"
+
+[extend]
+useDefault = true