reconcilekit 0.1.0__tar.gz

reconcilekit-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+dist/
+public/

reconcilekit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugo Haas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reconcilekit-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: reconcilekit
+Version: 0.1.0
+Summary: A tiny stateless fetch-diff-apply reconciliation kernel for fleet-wide config tools
+Project-URL: Homepage, https://github.com/hugoh/gh-workflows/tree/main/reconcilekit
+Project-URL: Issues, https://github.com/hugoh/gh-workflows/issues
+Project-URL: Repository, https://github.com/hugoh/gh-workflows
+Author: Hugo Haas
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: rich>=13
+Description-Content-Type: text/markdown
+
+# reconcilekit
+
+A tiny, stateless fetch-diff-apply reconciliation kernel — the pattern a
+fleet-wide config tool repeats for every resource it manages, with none of the
+domain specifics.
+
+There is no state file, no backend, no daemon. Each run reads live state,
+compares it to what you want, and either reports the plan or applies it.
+
+## The pattern
+
+1. **Enumerate targets** — anything with a `name`.
+2. **Fetch** each target's current state.
+3. **Compare** to the desired state: already there? partly blocked?
+4. **Dry-run** → report the plan, or **apply** → mutate and report the outcome.
+5. **Classify** into `Status` (`OK`, `UNCHANGED`, `LIMITED`, `LIMITED_UNCHANGED`,
+   `FAILED`).
+6. **Run the fleet in bounded parallel**, isolating per-target failures and
+   raising them together at the end.
+
+## API
+
+Full API reference, generated from the docstrings:
+[hugoh.github.io/gh-workflows/reconcilekit](https://hugoh.github.io/gh-workflows/reconcilekit/)
+(rebuilt on every push that touches this package -- see
+`.github/workflows/docs.yml`).
+
+## Example
+
+```python
+import asyncio
+from dataclasses import dataclass
+
+from reconcilekit import (
+    Result,
+    Status,
+    classify_status,
+    result_line,
+    run_parallel,
+    run_reconcile,
+)
+
+
+@dataclass
+class File:
+    name: str
+    path: str
+    want: str
+
+
+def make_worker(dry_run: bool):
+    async def worker(f: File) -> Result[File]:
+        async def fetch() -> str:
+            return f.path_text()  # read current contents
+
+        def plan(current: str) -> Result[File]:
+            status = classify_status(
+                at_target=current == f.want, changed=current != f.want
+            )
+            return Result(
+                f,
+                result_line(
+                    f.name, "would rewrite" if current != f.want else "ok", status
+                ),
+                status,
+            )
+
+        async def apply(current: str) -> Result[File]:
+            if current != f.want:
+                f.write(f.want)
+            status = classify_status(at_target=True, changed=current != f.want)
+            return Result(
+                f,
+                result_line(f.name, "written" if current != f.want else "ok", status),
+                status,
+            )
+
+        return await run_reconcile(
+            dry_run=dry_run, fetch=fetch, plan_result=plan, apply_result=apply
+        )
+
+    return worker
+
+
+asyncio.run(run_parallel(files, make_worker(dry_run=True)))
+```
+
+## Consumers
+
+`repo-admin/` (in this repo) uses it for every account-wide GitHub `sync`
+command, consumed as a uv workspace member there.

reconcilekit-0.1.0/README.md

@@ -0,0 +1,91 @@
+# reconcilekit
+
+A tiny, stateless fetch-diff-apply reconciliation kernel — the pattern a
+fleet-wide config tool repeats for every resource it manages, with none of the
+domain specifics.
+
+There is no state file, no backend, no daemon. Each run reads live state,
+compares it to what you want, and either reports the plan or applies it.
+
+## The pattern
+
+1. **Enumerate targets** — anything with a `name`.
+2. **Fetch** each target's current state.
+3. **Compare** to the desired state: already there? partly blocked?
+4. **Dry-run** → report the plan, or **apply** → mutate and report the outcome.
+5. **Classify** into `Status` (`OK`, `UNCHANGED`, `LIMITED`, `LIMITED_UNCHANGED`,
+   `FAILED`).
+6. **Run the fleet in bounded parallel**, isolating per-target failures and
+   raising them together at the end.
+
+## API
+
+Full API reference, generated from the docstrings:
+[hugoh.github.io/gh-workflows/reconcilekit](https://hugoh.github.io/gh-workflows/reconcilekit/)
+(rebuilt on every push that touches this package -- see
+`.github/workflows/docs.yml`).
+
+## Example
+
+```python
+import asyncio
+from dataclasses import dataclass
+
+from reconcilekit import (
+    Result,
+    Status,
+    classify_status,
+    result_line,
+    run_parallel,
+    run_reconcile,
+)
+
+
+@dataclass
+class File:
+    name: str
+    path: str
+    want: str
+
+
+def make_worker(dry_run: bool):
+    async def worker(f: File) -> Result[File]:
+        async def fetch() -> str:
+            return f.path_text()  # read current contents
+
+        def plan(current: str) -> Result[File]:
+            status = classify_status(
+                at_target=current == f.want, changed=current != f.want
+            )
+            return Result(
+                f,
+                result_line(
+                    f.name, "would rewrite" if current != f.want else "ok", status
+                ),
+                status,
+            )
+
+        async def apply(current: str) -> Result[File]:
+            if current != f.want:
+                f.write(f.want)
+            status = classify_status(at_target=True, changed=current != f.want)
+            return Result(
+                f,
+                result_line(f.name, "written" if current != f.want else "ok", status),
+                status,
+            )
+
+        return await run_reconcile(
+            dry_run=dry_run, fetch=fetch, plan_result=plan, apply_result=apply
+        )
+
+    return worker
+
+
+asyncio.run(run_parallel(files, make_worker(dry_run=True)))
+```
+
+## Consumers
+
+`repo-admin/` (in this repo) uses it for every account-wide GitHub `sync`
+command, consumed as a uv workspace member there.

reconcilekit-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "reconcilekit"
+version = "0.1.0"
+description = "A tiny stateless fetch-diff-apply reconciliation kernel for fleet-wide config tools"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Hugo Haas" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+dependencies = ["rich>=13"]
+
+[project.urls]
+Homepage = "https://github.com/hugoh/gh-workflows/tree/main/reconcilekit"
+Issues = "https://github.com/hugoh/gh-workflows/issues"
+Repository = "https://github.com/hugoh/gh-workflows"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/reconcilekit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

reconcilekit-0.1.0/src/reconcilekit/__init__.py

@@ -0,0 +1,43 @@
+"""reconcilekit -- a tiny stateless fetch-diff-apply reconciliation kernel.
+
+The pattern every fleet-wide config tool repeats: enumerate targets, fetch each
+one's current state, compare to the desired state, either report the plan
+(dry run) or apply it, classify the outcome into a small fixed vocabulary, and
+run the whole thing in bounded parallel with per-target failure isolation.
+"""
+
+from __future__ import annotations
+
+from .kernel import (
+    DEFAULT_JOBS,
+    HasName,
+    ReconcileError,
+    Result,
+    run_parallel,
+    run_reconcile,
+)
+from .render import print_status, progress_bar, result_line
+from .status import (
+    Status,
+    classify_status,
+    partition_fields,
+    summary_status,
+    unavailable_suffix,
+)
+
+__all__ = [
+    "DEFAULT_JOBS",
+    "HasName",
+    "ReconcileError",
+    "Result",
+    "Status",
+    "classify_status",
+    "partition_fields",
+    "print_status",
+    "progress_bar",
+    "result_line",
+    "run_parallel",
+    "run_reconcile",
+    "summary_status",
+    "unavailable_suffix",
+]

reconcilekit-0.1.0/src/reconcilekit/kernel.py

@@ -0,0 +1,133 @@
+"""The reconciliation kernel: a fetch-then-branch skeleton for one target, and
+a bounded-parallel runner over a fleet of them with per-target failure
+isolation. Nothing here knows what a target is beyond its name.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import Generic, Protocol, TypeVar
+
+from .render import QUIET_STATUSES, console, print_status, progress_bar
+from .status import Status
+
+DEFAULT_JOBS = 6
+
+
+class ReconcileError(RuntimeError):
+    """A target's worker failed, or a run finished with failures.
+
+    Callers that need a domain-specific exception type (so `pytest.raises` and
+    `except` clauses can stay narrow) pass it as `run_parallel(..., error_cls=)`.
+    """
+
+
+class HasName(Protocol):
+    @property
+    def name(self) -> str: ...
+
+
+class ResultLike(Protocol):
+    status: Status
+    line: str
+
+
+Target = TypeVar("Target", bound=HasName)
+State = TypeVar("State")
+R = TypeVar("R", bound=ResultLike)
+
+
+@dataclass
+class Result(Generic[Target]):
+    target: Target
+    line: str
+    status: Status = Status.OK
+    tag: str | None = None
+
+
+async def run_reconcile(
+    *,
+    dry_run: bool,
+    fetch: Callable[[], Awaitable[State]],
+    plan_result: Callable[[State], R],
+    apply_result: Callable[[State], Awaitable[R]],
+) -> R:
+    """Read the target's current state once, then either report the plan (dry
+    run) or apply the change and report the outcome. Each worker keeps its own
+    planning, side effects, and result formatting in the three callables.
+    """
+    state = await fetch()
+    if dry_run:
+        return plan_result(state)
+    return await apply_result(state)
+
+
+async def run_parallel(
+    targets: Sequence[Target],
+    worker: Callable[[Target], Awaitable[R]],
+    jobs: int = DEFAULT_JOBS,
+    verbose: bool = False,
+    *,
+    error_cls: type[Exception] = ReconcileError,
+) -> list[R]:
+    """Runs worker(target) for each target concurrently (bounded by a semaphore
+    -- these are I/O-bound calls, not CPU-bound work), printing each result's
+    line as soon as it's ready (completion order, not submission order) above a
+    live progress bar, and returning every result.
+
+    A worker exception is caught inside call() itself -- not left to propagate
+    through the TaskGroup -- so one target failing doesn't cancel the others
+    (TaskGroup cancels every sibling task the moment any task raises). Instead
+    it's printed as a failure line and collected; once every target has been
+    attempted, any failures are raised together as a single `error_cls` so the
+    run still ends with a nonzero exit.
+
+    Unless verbose=True, a target already at its target state (UNCHANGED /
+    LIMITED_UNCHANGED) isn't printed live -- on a large fleet the handful of
+    lines that represent an actual change would otherwise be lost in a wall of
+    "unchanged: ..." lines. Suppressed lines are counted and reported as a
+    single dim summary line instead.
+    """
+    results: list[R] = []
+    failed_names: list[str] = []
+    unchanged_count = 0
+    sem = asyncio.Semaphore(jobs)
+
+    with progress_bar() as progress:
+        task = progress.add_task("Processing...", total=len(targets))
+
+        async def call(target: Target) -> None:
+            nonlocal unchanged_count
+            async with sem:
+                try:
+                    result = await worker(target)
+                except Exception as exc:  # noqa: BLE001 -- collected below, not swallowed
+                    failed_names.append(target.name)
+                    print_status(Status.FAILED, f"{target.name}: {exc}")
+                else:
+                    if not verbose and result.status in QUIET_STATUSES:
+                        unchanged_count += 1
+                    else:
+                        print_status(result.status, result.line)
+                    results.append(result)
+                finally:
+                    progress.advance(task)
+
+        async with asyncio.TaskGroup() as tg:
+            for target in targets:
+                tg.create_task(call(target))
+
+    if unchanged_count:
+        console.print(
+            f"  {unchanged_count} unchanged (rerun with --verbose to see them)",
+            style="dim",
+        )
+
+    if failed_names:
+        raise error_cls(
+            f"{len(failed_names)} target(s) failed: {', '.join(sorted(failed_names))}"
+        )
+
+    return results

reconcilekit-0.1.0/src/reconcilekit/render.py

@@ -0,0 +1,54 @@
+"""Default terminal renderer for reconcile runs: a status symbol per line above
+a live progress bar, silenced when stdout isn't a terminal.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.progress import Progress
+
+from .status import Status
+
+console = Console()
+
+_STATUS_DISPLAY: dict[Status, tuple[str, str]] = {
+    Status.OK: ("✓", "green"),
+    Status.UNCHANGED: ("•", "green"),
+    Status.LIMITED: ("○", "yellow"),
+    Status.LIMITED_UNCHANGED: ("•", "yellow"),
+    Status.FAILED: ("✗", "red"),
+}
+
+QUIET_STATUSES = (Status.UNCHANGED, Status.LIMITED_UNCHANGED)
+
+
+def progress_bar(*, console: Console = console, **kwargs: Any) -> Progress:
+    """A Progress bound to `console` (module-level `console` by default),
+    silenced when its console isn't a terminal -- e.g. `cmd > file` or piping
+    into another command -- so its status text (which Progress still renders as
+    plain lines even without a tty) doesn't end up mixed into redirected output.
+    """
+    return Progress(console=console, disable=not console.is_terminal, **kwargs)
+
+
+def result_line(name: str, detail: str, status: Status) -> str:
+    prefix = (
+        "unchanged: " if status in (Status.UNCHANGED, Status.LIMITED_UNCHANGED) else ""
+    )
+    return f"{name:<30} {prefix}{detail}"
+
+
+def print_status(status: Status, line: str) -> None:
+    # Always goes through the single Console that Progress/Live owns
+    # (run_parallel passes it to Progress(console=...)): a second Console
+    # writing to a separate stream isn't coordinated by rich's Live redraw
+    # bookkeeping and can visually corrupt output on a real terminal.
+    symbol, color = _STATUS_DISPLAY[status]
+    # markup=False: `line` can contain target/error text with literal "[" (dict
+    # reprs, error messages) that would otherwise be parsed as rich markup.
+    # highlight=False: rich's default ReprHighlighter recolors numbers, paths,
+    # etc. within the line (e.g. a target named "foo-410"), fighting with the
+    # single status color we want for the whole line.
+    console.print(f"{symbol} {line}", style=color, markup=False, highlight=False)

reconcilekit-0.1.0/src/reconcilekit/status.py

@@ -0,0 +1,55 @@
+"""The status vocabulary every reconcile result is classified into, plus the
+"enable a set of toggles, some of which are gated" summarising helpers.
+"""
+
+from __future__ import annotations
+
+import enum
+
+
+class Status(enum.Enum):
+    """How a target's result relates to the desired end state -- distinct from
+    a Result's tag, which is per-command bookkeeping for end-of-run summaries.
+    """
+
+    OK = "ok"  # full target reached, changed this run
+    UNCHANGED = "unchanged"  # full target reached, already was
+    LIMITED = "limited"  # best-effort (capped by plan/data) reached, changed this run
+    LIMITED_UNCHANGED = "limited_unchanged"  # best-effort reached, already was
+    FAILED = "failed"  # worker raised
+
+
+def classify_status(at_target: bool, changed: bool) -> Status:
+    if at_target:
+        return Status.OK if changed else Status.UNCHANGED
+    return Status.LIMITED if changed else Status.LIMITED_UNCHANGED
+
+
+def partition_fields(fields: dict[str, tuple[bool, bool]]) -> dict[str, list[str]]:
+    """Splits a `name -> (currently_enabled, available_here)` mapping into the
+    two lists every "enable a set of toggles" command reports: `would_enable`
+    (available but off) and `unavailable` (gated).
+    """
+    return {
+        "would_enable": [
+            name
+            for name, (enabled, available) in fields.items()
+            if available and not enabled
+        ],
+        "unavailable": [
+            name for name, (_enabled, available) in fields.items() if not available
+        ],
+    }
+
+
+def summary_status(summary: dict[str, list[str]]) -> Status:
+    """Status for a partition_fields() summary: at target once nothing is
+    gated, changed when there's anything left to enable.
+    """
+    return classify_status(
+        at_target=not summary["unavailable"], changed=bool(summary["would_enable"])
+    )
+
+
+def unavailable_suffix(unavailable: list[str]) -> str:
+    return f" (unavailable: {', '.join(unavailable)})" if unavailable else ""

reconcilekit-0.1.0/tests/test_kernel.py

@@ -0,0 +1,186 @@
+import asyncio
+from dataclasses import dataclass
+
+import pytest
+
+from reconcilekit import (
+    ReconcileError,
+    Result,
+    Status,
+    run_parallel,
+    run_reconcile,
+)
+
+
+@dataclass
+class Fake:
+    name: str
+
+
+def _targets(n: int) -> list[Fake]:
+    return [Fake(name=f"t{i}") for i in range(n)]
+
+
+def test_result_defaults_to_ok_status():
+    assert Result(Fake("t"), "line").status == Status.OK
+
+
+async def test_run_reconcile_dry_run_reports_plan_without_applying():
+    applied = False
+
+    async def fetch():
+        return "state"
+
+    def plan_result(state):
+        assert state == "state"
+        return "planned"
+
+    async def apply_result(state):
+        nonlocal applied
+        applied = True
+        return "applied"
+
+    result = await run_reconcile(
+        dry_run=True, fetch=fetch, plan_result=plan_result, apply_result=apply_result
+    )
+    assert result == "planned"
+    assert not applied
+
+
+async def test_run_reconcile_applies_with_fetched_state():
+    fetch_calls = 0
+
+    async def fetch():
+        nonlocal fetch_calls
+        fetch_calls += 1
+        return "before"
+
+    def plan_result(state):
+        raise AssertionError("plan_result should not run when not dry_run")
+
+    async def apply_result(state):
+        assert state == "before"
+        return "applied"
+
+    result = await run_reconcile(
+        dry_run=False, fetch=fetch, plan_result=plan_result, apply_result=apply_result
+    )
+    assert result == "applied"
+    assert fetch_calls == 1
+
+
+async def test_run_parallel_returns_worker_results_for_every_target():
+    targets = _targets(5)
+
+    async def worker(target):
+        return Result(target, f"{target.name} done")
+
+    results = await run_parallel(targets, worker, jobs=3)
+    assert sorted(r.target.name for r in results) == sorted(t.name for t in targets)
+
+
+async def test_run_parallel_prints_each_worker_result_line(capsys):
+    async def worker(target):
+        return Result(target, f"{target.name} line")
+
+    await run_parallel([Fake("t-a")], worker, jobs=1)
+    assert "t-a line" in capsys.readouterr().out
+
+
+async def test_run_parallel_runs_workers_concurrently():
+    targets = _targets(4)
+    barrier = asyncio.Barrier(4)
+
+    async def worker(target):
+        await barrier.wait()
+        return Result(target, target.name)
+
+    # If run_parallel executed workers serially, the barrier would never
+    # release with only 1 worker present at a time and this would time out.
+    await asyncio.wait_for(run_parallel(targets, worker, jobs=4), timeout=2)
+
+
+async def test_run_parallel_one_failure_does_not_block_others():
+    targets = _targets(3)
+    completed = []
+
+    async def worker(target):
+        if target.name == "t1":
+            raise RuntimeError("boom")
+        await asyncio.sleep(0.05)
+        completed.append(target.name)
+        return Result(target, target.name)
+
+    with pytest.raises(ReconcileError):
+        await run_parallel(targets, worker, jobs=3)
+
+    assert sorted(completed) == ["t0", "t2"]
+
+
+async def test_run_parallel_reports_failed_target_names_in_error(capsys):
+    async def worker(target):
+        raise RuntimeError("network error")
+
+    with pytest.raises(ReconcileError, match="bad-target"):
+        await run_parallel([Fake("bad-target")], worker, jobs=1)
+    assert "bad-target" in capsys.readouterr().out
+
+
+async def test_run_parallel_raises_the_given_error_class():
+    class MyError(RuntimeError):
+        pass
+
+    async def worker(target):
+        raise RuntimeError("boom")
+
+    with pytest.raises(MyError):
+        await run_parallel([Fake("t")], worker, jobs=1, error_cls=MyError)
+
+
+async def test_run_parallel_hides_unchanged_lines_by_default(capsys):
+    async def worker(target):
+        return Result(target, f"{target.name} line", status=Status.UNCHANGED)
+
+    await run_parallel([Fake("t-a")], worker, jobs=1)
+    out = capsys.readouterr().out
+    assert "t-a line" not in out
+    assert "1 unchanged" in out
+
+
+async def test_run_parallel_verbose_shows_unchanged_lines_without_summary(capsys):
+    async def worker(target):
+        return Result(target, f"{target.name} line", status=Status.UNCHANGED)
+
+    await run_parallel([Fake("t-a")], worker, jobs=1, verbose=True)
+    out = capsys.readouterr().out
+    assert "t-a line" in out
+    assert "unchanged" not in out.replace("t-a line", "")
+
+
+@pytest.mark.parametrize("status", [Status.OK, Status.FAILED, Status.LIMITED])
+async def test_run_parallel_always_shows_non_unchanged_lines(capsys, status):
+    async def worker(target):
+        if status is Status.FAILED:
+            raise RuntimeError("boom")
+        return Result(target, f"{target.name} line", status=status)
+
+    if status is Status.FAILED:
+        with pytest.raises(ReconcileError):
+            await run_parallel([Fake("t-a")], worker, jobs=1)
+        out = capsys.readouterr().out
+        assert "t-a" in out
+    else:
+        await run_parallel([Fake("t-a")], worker, jobs=1)
+        out = capsys.readouterr().out
+        assert "t-a line" in out
+    assert "unchanged" not in out
+
+
+async def test_run_parallel_hides_limited_unchanged_lines_by_default(capsys):
+    async def worker(target):
+        return Result(target, f"{target.name} line", status=Status.LIMITED_UNCHANGED)
+
+    await run_parallel([Fake("t-a")], worker, jobs=1)
+    out = capsys.readouterr().out
+    assert "t-a line" not in out
+    assert "1 unchanged" in out

reconcilekit-0.1.0/tests/test_render.py

@@ -0,0 +1,62 @@
+import io
+
+import pytest
+from reconcilekit.render import _STATUS_DISPLAY
+from rich.console import Console
+
+from reconcilekit import Status, print_status, progress_bar, result_line
+
+
+def test_result_line_prefixes_unchanged_status():
+    assert result_line("t", "up to date detail", Status.UNCHANGED) == (
+        f"{'t':<30} unchanged: up to date detail"
+    )
+
+
+def test_result_line_prefixes_limited_unchanged_status():
+    assert result_line("t", "capped detail", Status.LIMITED_UNCHANGED) == (
+        f"{'t':<30} unchanged: capped detail"
+    )
+
+
+@pytest.mark.parametrize("status", [Status.OK, Status.LIMITED, Status.FAILED])
+def test_result_line_does_not_prefix_changed_statuses(status):
+    assert result_line("t", "detail", status) == f"{'t':<30} detail"
+
+
+def test_print_status_prints_line_to_stdout(capsys):
+    print_status(Status.OK, "target-a done")
+    assert "target-a done" in capsys.readouterr().out
+
+
+def test_print_status_does_not_interpret_brackets_in_line_as_markup(capsys):
+    print_status(Status.OK, "t {'allow_auto_merge': True} -> [oops]")
+    assert "{'allow_auto_merge': True} -> [oops]" in capsys.readouterr().out
+
+
+def test_status_display_pairs_are_unique_per_status():
+    # (symbol, color) pairs -- not symbols alone, since e.g. UNCHANGED and
+    # LIMITED_UNCHANGED intentionally share the "•" symbol and differ only by
+    # color.
+    pairs = list(_STATUS_DISPLAY.values())
+    assert len(pairs) == len(set(pairs)) == len(list(Status))
+
+
+def test_progress_bar_disabled_when_console_is_not_a_terminal():
+    non_tty_console = Console(file=io.StringIO())
+    assert progress_bar(console=non_tty_console).disable is True
+
+
+def test_progress_bar_enabled_when_console_is_a_terminal():
+    tty_console = Console(file=io.StringIO(), force_terminal=True)
+    assert progress_bar(console=tty_console).disable is False
+
+
+def test_progress_bar_prints_nothing_when_disabled():
+    output = io.StringIO()
+    non_tty_console = Console(file=output)
+    with progress_bar(console=non_tty_console) as bar:
+        task = bar.add_task("working", total=2)
+        bar.advance(task)
+        bar.advance(task)
+    assert output.getvalue() == ""

reconcilekit-0.1.0/tests/test_status.py

@@ -0,0 +1,73 @@
+import pytest
+
+from reconcilekit import (
+    Status,
+    classify_status,
+    partition_fields,
+    summary_status,
+    unavailable_suffix,
+)
+
+
+def test_classify_status_at_target_and_changed_is_ok():
+    assert classify_status(at_target=True, changed=True) == Status.OK
+
+
+def test_classify_status_at_target_and_unchanged_is_unchanged():
+    assert classify_status(at_target=True, changed=False) == Status.UNCHANGED
+
+
+def test_classify_status_not_at_target_and_changed_is_limited():
+    assert classify_status(at_target=False, changed=True) == Status.LIMITED
+
+
+def test_classify_status_not_at_target_and_unchanged_is_limited_unchanged():
+    assert classify_status(at_target=False, changed=False) == Status.LIMITED_UNCHANGED
+
+
+def test_partition_fields_splits_would_enable_and_unavailable():
+    summary = partition_fields(
+        {"a": (False, True), "b": (True, True), "c": (False, False)}
+    )
+    assert summary == {"would_enable": ["a"], "unavailable": ["c"]}
+
+
+def test_partition_fields_preserves_field_order():
+    summary = partition_fields(
+        {"z": (False, True), "a": (False, True), "m": (False, True)}
+    )
+    assert summary["would_enable"] == ["z", "a", "m"]
+
+
+def test_summary_status_ok_when_would_enable_and_nothing_gated():
+    assert summary_status({"would_enable": ["a"], "unavailable": []}) == Status.OK
+
+
+def test_summary_status_limited_when_gated_and_would_enable():
+    assert (
+        summary_status({"would_enable": ["a"], "unavailable": ["b"]}) == Status.LIMITED
+    )
+
+
+def test_summary_status_limited_unchanged_when_only_gated():
+    assert (
+        summary_status({"would_enable": [], "unavailable": ["b"]})
+        == Status.LIMITED_UNCHANGED
+    )
+
+
+def test_summary_status_unchanged_when_nothing_to_do():
+    assert summary_status({"would_enable": [], "unavailable": []}) == Status.UNCHANGED
+
+
+def test_unavailable_suffix_empty_when_nothing_gated():
+    assert unavailable_suffix([]) == ""
+
+
+def test_unavailable_suffix_lists_names():
+    assert unavailable_suffix(["a", "b"]) == " (unavailable: a, b)"
+
+
+@pytest.mark.parametrize("status", [Status.OK, Status.LIMITED, Status.FAILED])
+def test_status_is_hashable_and_distinct(status):
+    assert status in set(Status)