commitguardian 0.1.0__py3-none-any.whl

commitguard/cli/render.py

@@ -0,0 +1,367 @@
+"""Rendering of :class:`ScanReport` objects as text or JSON.
+
+* ``scan`` text: detailed, human-oriented explanation of every finding.
+* ``check`` text: one tab-separated line per finding plus a ``result=`` line.
+* JSON: the full report model, ASCII-only (all non-ASCII and control
+  characters escaped, so it is terminal-safe), schema_version 1.
+"""
+
+import json
+
+from commitguard.cli.output import supports_unicode
+from commitguard.core.decision import Action
+from commitguard.core.result import Evidence, MatchReason
+from commitguard.security.sanitization import sanitize_for_terminal
+from commitguard.services.reports import CommitReport, EvaluatedFinding, ScanReport
+
+
+def _s(text: str, limit: int = 300) -> str:
+    return sanitize_for_terminal(text, max_length=limit)
+
+
+def render_json(report: ScanReport) -> str:
+    return json.dumps(report.model_dump(mode="json"), indent=2, ensure_ascii=True, sort_keys=False)
+
+
+def _symbols() -> tuple[str, str, str]:
+    return ("✓", "✗", "!") if supports_unicode() else ("OK", "X", "!")
+
+
+def _reason(reason: MatchReason) -> str:
+    return f'{reason.kind.value} "{_s(reason.value, 120)}" ({_s(reason.rule, 120)})'
+
+
+def _evidence_lines(evidence: Evidence) -> list[str]:
+    source = evidence.source.label
+    if evidence.line_number is not None:
+        source += f", line {evidence.line_number}"
+    lines = [f"  Evidence:    {_s(evidence.value)}", f"  Source:      {source}"]
+    for index, reason in enumerate(evidence.matched):
+        lines.append(f"  {'Matched:' if index == 0 else '':<12} {_reason(reason)}")
+    if evidence.notes:
+        lines.append(f"  Notes:       {_s('; '.join(evidence.notes))}")
+    return lines
+
+
+def _finding_block(item: EvaluatedFinding, commit: CommitReport) -> list[str]:
+    finding = item.finding
+    policy = f" (policy {item.policy_id})" if item.policy_id else ""
+    lines = [
+        _s(finding.title, 120),
+        f"  Commit:      {commit.short_sha}",
+        f"  Detector:    {finding.detector}",
+        f"  Rule:        {finding.rule_id}",
+        f"  Severity:    {finding.severity.value}",
+        f"  Confidence:  {finding.confidence.value}",
+        f"  Action:      {item.action.value}{policy}",
+        f"  Message:     {_s(finding.message)}",
+    ]
+    for evidence in finding.evidence:
+        lines.extend(_evidence_lines(evidence))
+    lines.append(f"  Remediation: {_s(finding.remediation)}")
+    return lines
+
+
+def render_scan_text(report: ScanReport) -> str:
+    ok, cross, bang = _symbols()
+    lines = ["CommitGuard"]
+    if report.repository:
+        lines.append(f"Repository: {_s(report.repository)}")
+    count = len(report.commits)
+    lines.append(
+        f"Target:     {_s(report.target, 120)} ({count} commit{'s' if count != 1 else ''})"
+    )
+    lines.append("Config:     " + " < ".join(_s(source, 200) for source in report.config_sources))
+    lines.append("")
+
+    ordered = [(item, commit) for commit in report.commits for item in commit.findings]
+    ordered.sort(key=lambda pair: -pair[0].action.rank)  # stable: commit order kept per action
+    failures = [(failure, commit) for commit in report.commits for failure in commit.failures]
+
+    if not ordered and not failures:
+        lines.append(f"{ok} Repository scanned")
+        lines.append(f"{ok} No policy violations detected")
+    else:
+        headline = {
+            Action.BLOCK: f"{cross} BLOCKED: policy violation detected",
+            Action.WARN: f"{bang} WARNING: policy warnings detected",
+            Action.ALLOW: f"{ok} Findings present, all allowed by policy",
+        }[report.action]
+        lines.append(headline)
+        for failure, commit in failures:
+            lines.append("")
+            lines.append(f"{cross} Detector failure (scan incomplete)")
+            lines.append(f"  Commit:      {commit.short_sha}")
+            lines.append(f"  Detector:    {failure.failure.detector}")
+            lines.append(
+                f"  Error:       {_s(failure.failure.error_type)}: {_s(failure.failure.message)}"
+            )
+            lines.append(f"  Action:      {failure.action.value} ({_s(failure.reason)})")
+        for item, commit in ordered:
+            lines.append("")
+            lines.extend(_finding_block(item, commit))
+
+    summary = report.summary
+    lines.append("")
+    lines.append(
+        f"Summary: {summary['commits']} commit(s), {summary['block']} blocking, "
+        f"{summary['warn']} warning(s), {summary['allow']} allowed finding(s)"
+    )
+    lines.append(f"Result: {report.action.value.upper()}")
+    return "\n".join(lines)
+
+
+def render_check_text(report: ScanReport) -> str:
+    """Stable, grep/cut-friendly output: ``ACTION<TAB>sha<TAB>detector<TAB>rule<TAB>evidence``."""
+    lines = []
+    for commit in report.commits:
+        for failure in commit.failures:
+            lines.append(
+                "\t".join(
+                    [
+                        failure.action.value.upper(),
+                        commit.short_sha,
+                        failure.failure.detector,
+                        "detector_failure",
+                        _s(failure.failure.message, 200),
+                    ]
+                )
+            )
+        for item in commit.findings:
+            evidence = item.finding.evidence[0].value
+            lines.append(
+                "\t".join(
+                    [
+                        item.action.value.upper(),
+                        commit.short_sha,
+                        item.finding.detector,
+                        item.finding.rule_id,
+                        _s(evidence, 200),
+                    ]
+                )
+            )
+    summary = report.summary
+    lines.append(
+        f"result={report.action.value.upper()} commits={summary['commits']} "
+        f"block={summary['block']} warn={summary['warn']} allow={summary['allow']}"
+    )
+    return "\n".join(lines)
+
+
+# --------------------------------------------------------------------------- #
+# Hook output (written to stderr by the hook commands)
+# --------------------------------------------------------------------------- #
+_PUSH_REMEDIATION = [
+    "How to fix:",
+    "  CommitGuard never modifies commits. Rewrite the blocked commits so they no",
+    "  longer carry the attribution, then push again:",
+    "  - latest commit only:  git commit --amend",
+    "      (replaces that one local commit with an edited copy)",
+    "  - older commits:       git rebase -i <commit>^   and mark them 'reword'",
+    "      (recreates the selected commits and every commit after them)",
+    "  Only rewrite commits that have not already been shared with others.",
+]
+
+
+def _short_finding_lines(item: EvaluatedFinding) -> list[str]:
+    finding = item.finding
+    evidence = finding.evidence[0]
+    where = evidence.source.label + (
+        f", line {evidence.line_number}" if evidence.line_number is not None else ""
+    )
+    return [
+        f"    {_s(finding.title, 120)} [{finding.rule_id}, {finding.severity.value}]",
+        f"    Evidence: {_s(evidence.value, 160)} ({where})",
+    ]
+
+
+def _commit_marker(action: Action) -> str:
+    ok, cross, bang = _symbols()
+    return {Action.BLOCK: cross, Action.WARN: bang, Action.ALLOW: ok}[action]
+
+
+def render_push_text(report: ScanReport, *, remote: str | None, verbose: bool) -> str:
+    ok, cross, bang = _symbols()
+    commits = report.commits
+    counts = {action: sum(1 for c in commits if c.action is action) for action in Action}
+    lines = ["CommitGuard"]
+    if not commits:
+        lines.append(f"{ok} No new commits to check for this push.")
+        return "\n".join(lines)
+
+    if report.action is Action.ALLOW and not any(c.findings or c.failures for c in commits):
+        count = len(commits)
+        return (
+            f"CommitGuard: {ok} {count} outgoing commit{'s' if count != 1 else ''} checked, "
+            "no policy violations"
+        )
+    if report.action is Action.BLOCK:
+        lines.append(f"{cross} PUSH BLOCKED")
+    elif report.action is Action.WARN:
+        lines.append(f"{bang} PUSH ALLOWED WITH WARNINGS")
+    else:
+        lines.append(f"{ok} Push allowed: no policy violations")
+    lines += [
+        f"Remote: {_s(remote or '?', 200)}",
+        f"Commits checked: {len(commits)}",
+        f"Violations: {counts[Action.BLOCK]}",
+        f"Warnings: {counts[Action.WARN]}",
+        f"Allowed: {counts[Action.ALLOW]}",
+    ]
+
+    flagged = [c for c in commits if c.findings or c.failures]
+    for commit in sorted(flagged, key=lambda c: -c.action.rank):
+        lines.append("")
+        lines.append(
+            f"{_commit_marker(commit.action)} {commit.short_sha}  {_s(commit.subject, 72)}"
+        )
+        for failure in commit.failures:
+            lines.append(
+                f"    Detector failure: {failure.failure.detector} "
+                f"({_s(failure.failure.message, 160)}); analysis incomplete"
+            )
+        for item in commit.findings:
+            if verbose:
+                lines.extend("  " + line for line in _finding_block(item, commit))
+            else:
+                lines.extend(_short_finding_lines(item))
+                if item.action is not Action.BLOCK:
+                    lines.append(f"    Action: {item.action.value}")
+
+    if report.action is Action.BLOCK:
+        lines += ["", *_PUSH_REMEDIATION, "", "No changes were pushed to the remote repository."]
+        if not verbose:
+            lines.append("Full evidence: commitguard scan <sha>   (for each blocked commit)")
+    return "\n".join(lines)
+
+
+def render_commit_hook_text(report: ScanReport, *, stage: str, verbose: bool) -> str:
+    ok, cross, bang = _symbols()
+    (commit,) = report.commits
+    if not commit.findings and not commit.failures:
+        return ""
+    lines = ["CommitGuard"]
+    if report.action is Action.BLOCK:
+        lines.append(f"{cross} COMMIT BLOCKED ({stage})")
+    elif report.action is Action.WARN:
+        lines.append(f"{bang} Commit allowed with warnings ({stage})")
+    else:
+        lines.append(f"{ok} Findings allowed by policy ({stage})")
+    for failure in commit.failures:
+        lines.append(
+            f"  Detector failure: {failure.failure.detector} ({_s(failure.failure.message, 160)})"
+        )
+    for item in commit.findings:
+        lines.append("")
+        if verbose:
+            lines.extend(_finding_block(item, commit))
+        else:
+            lines.extend(line[2:] for line in _short_finding_lines(item))
+            lines.append(f"  Action: {item.action.value}")
+    if report.action is Action.BLOCK:
+        lines.append("")
+        lines.append("Nothing was committed. Your staged changes are unchanged.")
+        if stage == "commit-msg":
+            lines.append("Remove the attribution from the message and commit again.")
+            lines.append(
+                "Your message is still in .git/COMMIT_EDITMSG; to reuse it: "
+                "git commit -e -F .git/COMMIT_EDITMSG"
+            )
+        else:
+            lines.append(
+                "Commit under the responsible human contributor's identity "
+                "(git config user.name / user.email, or --author)."
+            )
+    return "\n".join(lines)
+
+
+# --------------------------------------------------------------------------- #
+# CI output
+# --------------------------------------------------------------------------- #
+MAX_CI_FINDINGS = 50
+_CI_REMEDIATION = (
+    "Please update the listed commits so that they comply with the repository's "
+    "contribution policy, then push the updated branch. CommitGuard does not "
+    "automatically rewrite Git history."
+)
+
+
+def render_ci_text(report: ScanReport, *, failed: bool) -> str:
+    ok, cross, bang = _symbols()
+    rule = "━" * 40 if supports_unicode() else "-" * 40
+    ci = report.ci
+    commits = report.commits
+    counts = {action: sum(1 for c in commits if c.action is action) for action in Action}
+    lines = ["CommitGuard", rule]
+    if ci is not None:
+        if ci.repository:
+            lines.append(f"Repository: {_s(ci.repository, 200)}")
+        event = _s(ci.event, 60)
+        if ci.pull_request_number:
+            event += f" (PR #{ci.pull_request_number}{', from a fork' if ci.from_fork else ''})"
+        lines.append(f"Event: {event}")
+        if ci.head_sha:
+            base = ci.base_sha[:12] if ci.base_sha else "(none)"
+            lines.append(f"Range: {base}..{ci.head_sha[:12]}")
+        lines.append(f"Policy: {_s(ci.policy_source, 200)}")
+    lines += [
+        f"{ok} policy loaded",
+        f"{ok} commits scanned: {len(commits)}",
+        f"{ok if not any(c.failures for c in commits) else cross} detection completed",
+    ]
+    by_rule: dict[str, int] = {}
+    for commit in commits:
+        for item in commit.findings:
+            by_rule[item.finding.rule_id] = by_rule.get(item.finding.rule_id, 0) + 1
+    if by_rule:
+        lines.append("Findings:")
+        lines.extend(f"  {rule_id}: {count}" for rule_id, count in sorted(by_rule.items()))
+    else:
+        lines.append("Findings: 0")
+    lines += [
+        f"Violations: {counts[Action.BLOCK]}",
+        f"Warnings: {counts[Action.WARN]}",
+        f"Allowed: {counts[Action.ALLOW]}",
+    ]
+    if ci is not None:
+        for notice in ci.notices:
+            lines.append(f"{bang} {_s(notice, 400)}")
+
+    shown = 0
+    omitted = 0
+    for commit in sorted(commits, key=lambda c: -c.action.rank):
+        for failure in commit.failures:
+            lines += [
+                "",
+                f"{cross} Detector failure (analysis incomplete)",
+                f"  Commit:   {commit.short_sha}",
+                f"  Detector: {failure.failure.detector}",
+                f"  Error:    {_s(failure.failure.message, 200)}",
+            ]
+        for item in commit.findings:
+            if shown >= MAX_CI_FINDINGS:
+                omitted += 1
+                continue
+            shown += 1
+            finding = item.finding
+            evidence = finding.evidence[0]
+            lines += [
+                "",
+                f"{_commit_marker(item.action)} {_s(finding.title, 120)}",
+                f"  Commit:   {commit.short_sha}  {_s(commit.subject, 72)}",
+                f"  Evidence: {_s(evidence.value, 200)} ({evidence.source.label})",
+                f"  Rule:     {finding.rule_id}",
+                f"  Severity: {finding.severity.value}",
+                f"  Action:   {item.action.value}",
+            ]
+    if omitted:
+        lines.append(f"\n... {omitted} more finding(s) omitted; use --format json for all")
+
+    if failed:
+        result = "BLOCK" if report.action is Action.BLOCK else "FAILED (fail-on: warn)"
+    else:
+        result = "PASS (with warnings)" if report.action is Action.WARN else "PASS"
+    lines += ["", f"Result: {result}"]
+    if report.action is Action.BLOCK:
+        lines += ["", f"Remediation: {_CI_REMEDIATION}"]
+    return "\n".join(lines)

commitguard/config/__init__.py

@@ -0,0 +1,6 @@
+"""Repository configuration (``.commitguard.yaml``).
+
+Configuration is security-relevant, so it is validated strictly: unknown keys,
+unknown policy IDs, wrong types, duplicate YAML keys and YAML tags that
+construct Python objects are all rejected rather than ignored.
+"""

commitguard/config/defaults.py

@@ -0,0 +1,53 @@
+"""Configuration file locations, limits and the ``commitguard init`` template."""
+
+CONFIG_FILENAMES: tuple[str, ...] = (".commitguard.yaml", ".commitguard.yml")
+DEFAULT_CONFIG_FILENAME = CONFIG_FILENAMES[0]
+GLOBAL_CONFIG_DIRNAME = "commitguard"
+GLOBAL_CONFIG_FILENAME = "config.yaml"
+CURRENT_CONFIG_VERSION = 1
+
+#: Refuse to parse configuration files larger than this (defence against
+#: resource exhaustion via YAML alias expansion or huge files).
+MAX_CONFIG_BYTES = 64 * 1024
+
+DEFAULT_CONFIG_TEMPLATE = """\
+# CommitGuard repository configuration.
+# Docs: docs/configuration.md
+#
+# Policies not listed here keep their built-in secure defaults.
+# Valid actions: allow | warn | block
+
+version: 1
+
+policies:
+  ai_coauthor:
+    enabled: true
+    action: block
+  ai_identity:
+    enabled: true
+    action: block
+  ai_trailer:
+    enabled: true
+    action: block
+  malformed_trailer:
+    enabled: true
+    action: warn
+  bot_identity:
+    enabled: true
+    action: warn
+
+# Which Git hooks enforce the policies above (after `commitguard install`).
+# Disabling a hook is visible in `commitguard doctor`.
+enforcement:
+  pre_commit: true
+  commit_msg: true
+  pre_push: true
+
+# What to do about a violation. By default CommitGuard blocks and leaves the
+# message to you. Set auto_remove: true and the commit-msg hook deletes the
+# offending lines instead, reports what it removed, and lets the commit through.
+# Attribution in the author or committer identity still blocks: no edit to the
+# message can fix that. `commitguard doctor` shows when this is on.
+# remediation:
+#   auto_remove: true
+"""

commitguard/config/enforcement.py

@@ -0,0 +1,53 @@
+"""Effective hook enforcement and remediation settings, merged across layers."""
+
+from pydantic import BaseModel, ConfigDict
+
+from commitguard.config.schema import CommitGuardConfig
+
+DEFAULT_MAX_PUSH_COMMITS = 10_000
+
+
+class Enforcement(BaseModel):
+    """Resolved enforcement settings. Secure default: every hook enforces."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    pre_commit: bool = True
+    commit_msg: bool = True
+    pre_push: bool = True
+    max_push_commits: int = DEFAULT_MAX_PUSH_COMMITS
+
+    def enabled(self, hook: str) -> bool:
+        return bool(getattr(self, hook.replace("-", "_")))
+
+    @property
+    def complete(self) -> bool:
+        return self.pre_commit and self.commit_msg and self.pre_push
+
+
+def build_enforcement(*configs: CommitGuardConfig) -> Enforcement:
+    """Merge enforcement settings from configuration layers (lowest first)."""
+    effective = Enforcement()
+    for config in configs:
+        updates = config.enforcement.model_dump(exclude_unset=True)
+        if updates:
+            effective = effective.model_copy(update=updates)
+    return effective
+
+
+class Remediation(BaseModel):
+    """Resolved remediation settings. Secure default: change nothing, just block."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    auto_remove: bool = False
+
+
+def build_remediation(*configs: CommitGuardConfig) -> Remediation:
+    """Merge remediation settings from configuration layers (lowest first)."""
+    effective = Remediation()
+    for config in configs:
+        updates = config.remediation.model_dump(exclude_unset=True)
+        if updates:
+            effective = effective.model_copy(update=updates)
+    return effective

commitguard/config/loader.py

@@ -0,0 +1,174 @@
+"""Locate, parse, validate and layer configuration files.
+
+Precedence (later layers override earlier ones, field by field)::
+
+    1. built-in defaults           commitguard.policies.defaults
+    2. global configuration        $XDG_CONFIG_HOME/commitguard/config.yaml
+                                   (default ~/.config/commitguard/config.yaml)
+    3. repository configuration    <repo root>/.commitguard.yaml (or .yml)
+    4. explicit configuration      --config PATH
+
+A layer only overrides the policy fields it sets; omitted policies and fields
+keep the value from the layer below, ultimately the secure built-in default.
+
+Security properties:
+
+* strict safe YAML (no object construction, no duplicate keys, no aliases);
+* files are size-limited and must be regular files;
+* repository configuration is read only from the repository root - never from
+  parent directories, which may be controlled by someone else.
+"""
+
+import os
+from enum import StrEnum
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from commitguard.config.defaults import (
+    CONFIG_FILENAMES,
+    GLOBAL_CONFIG_DIRNAME,
+    GLOBAL_CONFIG_FILENAME,
+    MAX_CONFIG_BYTES,
+)
+from commitguard.config.schema import CommitGuardConfig
+from commitguard.exceptions.base import UnsafeInputError
+from commitguard.exceptions.configuration import ConfigurationError
+from commitguard.security.safe_yaml import load_yaml
+from commitguard.utils.filesystem import read_text_limited
+
+
+class ConfigLayer(StrEnum):
+    BUILTIN = "builtin"
+    GLOBAL = "global"
+    REPOSITORY = "repository"
+    EXPLICIT = "explicit"
+
+
+class ConfigSource(BaseModel):
+    """Where one configuration layer came from."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    layer: ConfigLayer
+    path: Path | None = None
+    revision: str | None = None  # set when the file was read from a commit, not the work tree
+
+    def __str__(self) -> str:
+        if self.path is None:
+            return self.layer.value
+        if self.revision is not None:
+            return f"{self.layer.value}: {self.path.as_posix()} @ {self.revision[:12]}"
+        return f"{self.layer.value}: {self.path}"
+
+
+class LoadedConfig(BaseModel):
+    """All configuration layers in precedence order (lowest first)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    layers: tuple[tuple[ConfigSource, CommitGuardConfig], ...]
+
+    @property
+    def configs(self) -> tuple[CommitGuardConfig, ...]:
+        return tuple(config for _, config in self.layers)
+
+    @property
+    def sources(self) -> tuple[ConfigSource, ...]:
+        return tuple(source for source, _ in self.layers)
+
+
+def find_config(repository_root: Path) -> Path | None:
+    """Return the configuration file at ``repository_root``, if any.
+
+    Having both ``.commitguard.yaml`` and ``.commitguard.yml`` is ambiguous and
+    rejected.
+    """
+    candidates = [repository_root / name for name in CONFIG_FILENAMES]
+    present = [path for path in candidates if path.exists() or path.is_symlink()]
+    if len(present) > 1:
+        raise ConfigurationError(
+            "multiple configuration files found: " + ", ".join(p.name for p in present)
+        )
+    return present[0] if present else None
+
+
+def global_config_path() -> Path:
+    """Path of the per-user global configuration file (may not exist)."""
+    base = os.environ.get("XDG_CONFIG_HOME")
+    root = Path(base) if base and Path(base).is_absolute() else Path.home() / ".config"
+    return root / GLOBAL_CONFIG_DIRNAME / GLOBAL_CONFIG_FILENAME
+
+
+def parse_config(text: str, *, path: Path | None = None) -> CommitGuardConfig:
+    """Parse and validate configuration from YAML text."""
+    try:
+        document = load_yaml(text)
+    except yaml.YAMLError as exc:
+        raise ConfigurationError(f"invalid YAML: {exc}", path=path) from exc
+
+    if not isinstance(document, dict):
+        raise ConfigurationError("configuration must be a YAML mapping", path=path)
+
+    try:
+        return CommitGuardConfig.model_validate(document)
+    except ValidationError as exc:
+        raise ConfigurationError(_format_validation_error(exc), path=path) from exc
+
+
+def load_config(path: Path) -> CommitGuardConfig:
+    """Read, parse and validate a configuration file."""
+    try:
+        text = read_text_limited(path, max_bytes=MAX_CONFIG_BYTES)
+    except FileNotFoundError as exc:
+        raise ConfigurationError("configuration file not found", path=path) from exc
+    except (OSError, UnsafeInputError) as exc:
+        raise ConfigurationError(str(exc), path=path) from exc
+    return parse_config(text, path=path)
+
+
+def load_repository_config(repository_root: Path) -> tuple[CommitGuardConfig, Path | None]:
+    """Load only the repository layer, or an empty config if it has none."""
+    path = find_config(repository_root)
+    if path is None:
+        return CommitGuardConfig(version=1), None
+    return load_config(path), path
+
+
+def load_effective_config(
+    repository_root: Path | None,
+    *,
+    explicit_path: Path | None = None,
+    include_global: bool = True,
+) -> LoadedConfig:
+    """Load every applicable configuration layer in precedence order."""
+    layers: list[tuple[ConfigSource, CommitGuardConfig]] = [
+        (ConfigSource(layer=ConfigLayer.BUILTIN), CommitGuardConfig(version=1))
+    ]
+    if include_global:
+        path = global_config_path()
+        if path.exists() or path.is_symlink():
+            layers.append((ConfigSource(layer=ConfigLayer.GLOBAL, path=path), load_config(path)))
+    if repository_root is not None:
+        repo_path = find_config(repository_root)
+        if repo_path is not None:
+            layers.append(
+                (ConfigSource(layer=ConfigLayer.REPOSITORY, path=repo_path), load_config(repo_path))
+            )
+    if explicit_path is not None:
+        layers.append(
+            (
+                ConfigSource(layer=ConfigLayer.EXPLICIT, path=explicit_path),
+                load_config(explicit_path),
+            )
+        )
+    return LoadedConfig(layers=tuple(layers))
+
+
+def _format_validation_error(exc: ValidationError) -> str:
+    lines = ["invalid configuration:"]
+    for error in exc.errors(include_url=False, include_input=False):
+        location = ".".join(str(part) for part in error["loc"]) or "<root>"
+        lines.append(f"  - {location}: {error['msg']}")
+    return "\n".join(lines)