ckdn 1.0.0__py3-none-any.whl

ckdn/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Den Rozhnovskiy <rozhnovskiydenis@gmail.com>
+# SPDX-License-Identifier: MIT
+"""ckdn: deterministic check runner and log digester for AI-assisted development."""
+
+__version__ = "1.0.0"
+
+#: Digest document schema identifier. Bump the trailing integer on any
+#: backward-incompatible change to the digest.json structure.
+DIGEST_SCHEMA = "ckdn.digest/2"
+
+#: Meta document schema identifier.
+META_SCHEMA = "ckdn.meta/1"
+
+#: Alias aggregate document schema identifier. Bump the trailing integer on any
+#: backward-incompatible change to the aggregate structure.
+AGGREGATE_SCHEMA = "ckdn.aggregate/1"

ckdn/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Den Rozhnovskiy <rozhnovskiydenis@gmail.com>
+# SPDX-License-Identifier: MIT
+"""Allow `python -m ckdn`."""
+
+from ckdn.cli import main
+
+raise SystemExit(main())

ckdn/app/__init__.py

@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Den Rozhnovskiy <rozhnovskiydenis@gmail.com>
+# SPDX-License-Identifier: MIT
+"""Stdlib application facade shared by CLI and MCP transports."""
+
+from __future__ import annotations
+
+from ckdn.app.errors import (
+    AliasExtraArgsError,
+    AppError,
+    ArtifactError,
+    ConfigLoadError,
+    DigestError,
+    NotAliasError,
+    NotAtomicError,
+    RunNotFoundError,
+    UnknownCheckError,
+    UnknownParserError,
+)
+from ckdn.app.queries import (
+    DEFAULT_EVIDENCE_LIMIT,
+    MAX_EVIDENCE_LIMIT,
+    get_digest,
+    get_evidence,
+    list_checks,
+    list_runs,
+)
+from ckdn.app.run import exit_from_outcome, run_alias, run_check, run_one
+from ckdn.app.types import AliasRunResult, AtomicRunResult
+
+__all__ = [
+    "DEFAULT_EVIDENCE_LIMIT",
+    "MAX_EVIDENCE_LIMIT",
+    "AliasExtraArgsError",
+    "AliasRunResult",
+    "AppError",
+    "ArtifactError",
+    "AtomicRunResult",
+    "ConfigLoadError",
+    "DigestError",
+    "NotAliasError",
+    "NotAtomicError",
+    "RunNotFoundError",
+    "UnknownCheckError",
+    "UnknownParserError",
+    "exit_from_outcome",
+    "get_digest",
+    "get_evidence",
+    "list_checks",
+    "list_runs",
+    "run_alias",
+    "run_check",
+    "run_one",
+]

ckdn/app/errors.py

@@ -0,0 +1,45 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Den Rozhnovskiy <rozhnovskiydenis@gmail.com>
+# SPDX-License-Identifier: MIT
+"""Application-layer errors (transports map these to exit codes / isError)."""
+
+from __future__ import annotations
+
+
+class AppError(Exception):
+    """Base error for ckdn application operations."""
+
+
+class ConfigLoadError(AppError):
+    """ckdn.toml missing or invalid."""
+
+
+class UnknownCheckError(AppError):
+    """Requested check name is not in the config."""
+
+
+class NotAtomicError(AppError):
+    """Operation requires an atomic check."""
+
+
+class NotAliasError(AppError):
+    """Operation requires an alias check."""
+
+
+class UnknownParserError(AppError):
+    """Configured parser name is not registered."""
+
+
+class AliasExtraArgsError(AppError):
+    """Aliases do not accept extra command arguments."""
+
+
+class RunNotFoundError(AppError):
+    """No matching run directory."""
+
+
+class DigestError(AppError):
+    """Digest missing or corrupt."""
+
+
+class ArtifactError(AppError):
+    """Artifact path invalid, missing, or outside the run directory."""

ckdn/app/queries.py

@@ -0,0 +1,270 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Den Rozhnovskiy <rozhnovskiydenis@gmail.com>
+# SPDX-License-Identifier: MIT
+"""Read-side application queries over config and run artifacts."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ckdn.app.errors import ArtifactError, DigestError, RunNotFoundError
+from ckdn.config import Config
+from ckdn.digest import DIGEST_NAME, META_NAME, list_artifacts
+from ckdn.runner import LOG_NAME, list_run_dirs, resolve_run_dir
+
+DEFAULT_EVIDENCE_LIMIT = 200
+MAX_EVIDENCE_LIMIT = 2000
+MAX_LIST_RUNS_LIMIT = 500
+
+# Streaming artifact reads: never hold the whole file in memory. Scan in fixed
+# chunks and cap the bytes retained per returned line so a single pathological
+# (e.g. newline-free) artifact cannot exhaust memory via get_evidence.
+_EVIDENCE_READ_CHUNK = 1 << 16  # 64 KiB
+_MAX_EVIDENCE_LINE_BYTES = 64 << 10  # 64 KiB per returned line
+
+
+def _no_run_error(ref: str | None) -> RunNotFoundError:
+    """Distinguish an unresolved/invalid ref from an empty runs directory.
+
+    A truthy ``ref`` that resolves to nothing is either unknown or not a valid
+    run id inside the runs dir (absolute/``..``/multi-segment/symlink refs are
+    refused by ``resolve_run_dir``); say so rather than implying nothing has run.
+    """
+    if ref:
+        return RunNotFoundError(
+            f"no run matching {ref!r} (unknown, or not a valid run id "
+            "inside the runs directory)"
+        )
+    return RunNotFoundError("no matching run found (nothing has been run yet?)")
+
+
+_DIGEST_EVIDENCE_KEYS = (
+    "findings",
+    "findings_total",
+    "findings_truncated",
+    "gate_failures",
+    "notes",
+    "log_tail",
+    "summary",
+    "status_reason",
+    "artifacts",
+)
+
+
+def list_checks(cfg: Config) -> list[dict[str, Any]]:
+    """Return sorted check metadata for agents / MCP."""
+    out: list[dict[str, Any]] = []
+    for name in sorted(cfg.checks):
+        check = cfg.checks[name]
+        if check.is_alias:
+            out.append(
+                {
+                    "name": name,
+                    "kind": "alias",
+                    "members": list(check.members or ()),
+                    "fail_fast": check.fail_fast,
+                }
+            )
+        else:
+            item: dict[str, Any] = {
+                "name": name,
+                "kind": "atomic",
+                "parser": check.parser,
+                "command": check.command,
+            }
+            if check.timeout is not None:
+                item["timeout"] = check.timeout
+            if check.options:
+                item["options"] = dict(check.options)
+            out.append(item)
+    return out
+
+
+def _load_digest(run_dir: Path) -> dict[str, Any]:
+    """Load and validate ``digest.json`` from an already-resolved run dir.
+
+    Reading is anchored to ``run_dir`` itself -- never re-resolved by basename
+    -- so a run's digest can never be paired with another run's artifacts.
+    """
+    digest_path = run_dir / DIGEST_NAME
+    if not digest_path.exists():
+        raise DigestError(f"run {run_dir.name} has no {DIGEST_NAME}")
+    try:
+        doc = json.loads(digest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise DigestError(f"run {run_dir.name} has corrupt {DIGEST_NAME}") from exc
+    if not isinstance(doc, dict):
+        raise DigestError(f"run {run_dir.name} digest root is not an object")
+    return doc
+
+
+def get_digest(cfg: Config, ref: str | None = None) -> dict[str, Any]:
+    """Load ``digest.json`` for ``ref`` or the latest run."""
+    run_dir = resolve_run_dir(cfg.runs_dir, ref)
+    if run_dir is None:
+        raise _no_run_error(ref)
+    return _load_digest(run_dir)
+
+
+def list_runs(cfg: Config, *, limit: int = 10) -> list[dict[str, Any]]:
+    """Return recent run summaries (oldest→newest within the window)."""
+    n = min(max(0, limit), MAX_LIST_RUNS_LIMIT)
+    dirs = list_run_dirs(cfg.runs_dir)[-n:] if n else []
+    rows: list[dict[str, Any]] = []
+    for run_dir in dirs:
+        row: dict[str, Any] = {"run_id": run_dir.name, "check": "?", "status": "?"}
+        digest_path = run_dir / DIGEST_NAME
+        if digest_path.exists():
+            try:
+                doc = json.loads(digest_path.read_text(encoding="utf-8"))
+                if isinstance(doc, dict):
+                    row["check"] = str(doc.get("check", "?"))
+                    row["status"] = str(doc.get("status", "?"))
+                    if "rc" in doc:
+                        row["rc"] = doc["rc"]
+                    if "run_dir" in doc:
+                        row["run_dir"] = doc["run_dir"]
+            except json.JSONDecodeError:
+                row["status"] = "corrupt"
+        rows.append(row)
+    return rows
+
+
+def _safe_artifact_path(run_dir: Path, artifact: str) -> Path:
+    if not artifact or artifact.strip() != artifact:
+        raise ArtifactError(f"invalid artifact name: {artifact!r}")
+    if Path(artifact).is_absolute() or ".." in Path(artifact).parts:
+        raise ArtifactError(f"artifact path escapes run directory: {artifact!r}")
+    allowed = set(list_artifacts(run_dir))
+    # full.log is always an evidence candidate even if list_artifacts filters
+    allowed.add(LOG_NAME)
+    allowed.add(DIGEST_NAME)
+    allowed.add(META_NAME)
+    if artifact not in allowed:
+        raise ArtifactError(
+            f"artifact '{artifact}' not found in run {run_dir.name}; "
+            f"available: {', '.join(sorted(allowed))}"
+        )
+    target = (run_dir / artifact).resolve()
+    root = run_dir.resolve()
+    try:
+        target.relative_to(root)
+    except ValueError as exc:
+        raise ArtifactError(
+            f"artifact path escapes run directory: {artifact!r}"
+        ) from exc
+    if not target.is_file():
+        raise ArtifactError(
+            f"artifact '{artifact}' is not a file in run {run_dir.name}"
+        )
+    return target
+
+
+def get_evidence(
+    cfg: Config,
+    *,
+    ref: str | None = None,
+    artifact: str | None = None,
+    offset: int = 0,
+    limit: int = DEFAULT_EVIDENCE_LIMIT,
+    include_meta: bool = False,
+) -> dict[str, Any]:
+    """Return bounded digest evidence and/or a sliced artifact body.
+
+    When ``artifact`` is omitted, returns digest evidence fields and the
+    artifact index — never the full log body.
+    """
+    run_dir = resolve_run_dir(cfg.runs_dir, ref)
+    if run_dir is None:
+        raise _no_run_error(ref)
+
+    digest = _load_digest(run_dir)
+    payload: dict[str, Any] = {
+        "run_id": run_dir.name,
+        "check": digest.get("check"),
+        "status": digest.get("status"),
+        "rc": digest.get("rc"),
+        "run_dir": digest.get("run_dir"),
+        "artifacts": list_artifacts(run_dir),
+    }
+    for key in _DIGEST_EVIDENCE_KEYS:
+        if key in digest and key != "artifacts":
+            payload[key] = digest[key]
+
+    if include_meta:
+        meta_path = run_dir / META_NAME
+        if meta_path.is_file():
+            try:
+                meta = json.loads(meta_path.read_text(encoding="utf-8"))
+                if isinstance(meta, dict):
+                    payload["meta"] = meta
+            except json.JSONDecodeError:
+                payload["meta_error"] = f"corrupt {META_NAME}"
+
+    if artifact is None:
+        return payload
+
+    line_offset = max(0, offset)
+    line_limit = min(max(1, limit), MAX_EVIDENCE_LIMIT)
+    path = _safe_artifact_path(run_dir, artifact)
+    sliced, total_lines = _slice_artifact_lines(path, line_offset, line_limit)
+    payload["artifact"] = {
+        "name": artifact,
+        "offset": line_offset,
+        "limit": line_limit,
+        "total_lines": total_lines,
+        "truncated": line_offset + line_limit < total_lines,
+        "lines": sliced,
+    }
+    return payload
+
+
+def _slice_artifact_lines(path: Path, offset: int, limit: int) -> tuple[list[str], int]:
+    """Stream ``path`` and return ``(window, total_lines)``.
+
+    Only the ``[offset, offset + limit)`` window is retained, and each retained
+    line is capped at ``_MAX_EVIDENCE_LINE_BYTES``, so neither a huge file nor a
+    single unbounded line can be pulled into memory in full. Line splitting
+    matches ``str.splitlines`` for ``\\n`` (and trims a trailing ``\\r`` so CRLF
+    logs read cleanly).
+    """
+    end = offset + limit
+    window: list[bytes] = []
+    total = 0
+    idx = 0
+    cur = bytearray()
+    line_nonempty = False
+    keeping = offset <= idx < end
+
+    with path.open("rb") as fh:
+        while chunk := fh.read(_EVIDENCE_READ_CHUNK):
+            pos = 0
+            size = len(chunk)
+            while pos < size:
+                nl = chunk.find(b"\n", pos)
+                seg_end = size if nl == -1 else nl
+                if seg_end > pos:
+                    line_nonempty = True
+                    if keeping and len(cur) < _MAX_EVIDENCE_LINE_BYTES:
+                        room = _MAX_EVIDENCE_LINE_BYTES - len(cur)
+                        cur += chunk[pos : min(seg_end, pos + room)]
+                if nl == -1:
+                    break
+                total += 1
+                if keeping:
+                    window.append(bytes(cur))
+                idx += 1
+                cur = bytearray()
+                line_nonempty = False
+                keeping = offset <= idx < end
+                pos = nl + 1
+
+    # A trailing segment with no terminating newline is a final line.
+    if line_nonempty:
+        total += 1
+        if keeping:
+            window.append(bytes(cur))
+
+    decoded = [b.decode("utf-8", errors="replace").removesuffix("\r") for b in window]
+    return decoded, total

ckdn/app/run.py

@@ -0,0 +1,177 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Den Rozhnovskiy <rozhnovskiydenis@gmail.com>
+# SPDX-License-Identifier: MIT
+"""Run atomic checks and aliases (shared by CLI and MCP)."""
+
+from __future__ import annotations
+
+from ckdn.app.errors import (
+    AliasExtraArgsError,
+    NotAliasError,
+    NotAtomicError,
+    UnknownCheckError,
+    UnknownParserError,
+)
+from ckdn.app.types import AliasRunResult, AtomicRunResult
+from ckdn.config import CheckConfig, Config
+from ckdn.digest import (
+    META_NAME,
+    build_alias_aggregate,
+    build_digest,
+    build_meta,
+    dump_json,
+    list_artifacts,
+    write_documents,
+)
+from ckdn.parsers import available_parsers, get_parser
+from ckdn.parsers.base import ParseContext, ParseResult
+from ckdn.reconcile import reconcile
+from ckdn.runner import (
+    build_tokens,
+    create_run_dir,
+    execute,
+    prune,
+    update_latest,
+)
+
+
+def exit_from_outcome(rc: int, status: str) -> int:
+    if rc != 0:
+        return rc if 0 < rc <= 255 else 1
+    return 0 if status == "pass" else 1
+
+
+def run_one(
+    cfg: Config,
+    check: CheckConfig,
+    *,
+    extra: list[str] | None = None,
+) -> AtomicRunResult:
+    """Run one atomic check and persist digest/meta under the run directory."""
+    if check.is_alias or check.command is None or check.parser is None:
+        raise NotAtomicError(f"[check.{check.name}] is not an atomic check")
+
+    parser = get_parser(check.parser)
+    if parser is None:
+        raise UnknownParserError(
+            f"[check.{check.name}] uses unknown parser '{check.parser}'; "
+            "available: " + ", ".join(available_parsers())
+        )
+
+    run_dir = create_run_dir(cfg.runs_dir, check.name)
+    tokens = build_tokens(check.command, run_dir, list(extra or ()))
+    outcome = execute(tokens, cwd=cfg.root, run_dir=run_dir, timeout=check.timeout)
+
+    try:
+        result = parser.parse(
+            ParseContext(
+                run_dir=run_dir,
+                log_text=outcome.log_text,
+                rc=outcome.rc,
+                options=check.options,
+                top=int(check.options.get("top", cfg.run.top)),
+                max_snippet_lines=cfg.run.max_snippet_lines,
+            )
+        )
+    except Exception as exc:  # a parser bug must never hide a result
+        result = ParseResult(
+            parser_ok=False,
+            notes=[f"parser '{check.parser}' crashed: {exc!r}"],
+        )
+    if outcome.exec_note:
+        result.notes.insert(0, outcome.exec_note)
+
+    status, reason, include_tail = reconcile(outcome.rc, result)
+
+    meta = build_meta(check=check.name, parser=check.parser, outcome=outcome)
+    (run_dir / META_NAME).write_text(dump_json(meta), encoding="utf-8")
+    try:
+        run_dir_rel = str(run_dir.relative_to(cfg.root))
+    except ValueError:
+        run_dir_rel = str(run_dir)
+    digest = build_digest(
+        check=check.name,
+        status=status,
+        reason=reason,
+        outcome=outcome,
+        result=result,
+        run_dir_rel=run_dir_rel,
+        top=int(check.options.get("top", cfg.run.top)),
+        include_tail=include_tail,
+        tail_lines=cfg.run.log_tail_lines,
+        artifacts=list_artifacts(run_dir),
+    )
+    write_documents(run_dir, digest, meta)
+    update_latest(cfg.runs_dir, run_dir)
+    prune(cfg.runs_dir, cfg.run.keep)
+
+    return AtomicRunResult(
+        check=check.name,
+        status=status,
+        rc=outcome.rc,
+        run_dir=run_dir,
+        digest=digest,
+        exit_code=exit_from_outcome(outcome.rc, status),
+    )
+
+
+def _alias_aggregate_exit(results: list[AtomicRunResult]) -> int:
+    for item in results:
+        if item.rc != 0:
+            return item.rc if 0 < item.rc <= 255 else 1
+    if any(item.status != "pass" for item in results):
+        return 1
+    return 0
+
+
+def run_alias(cfg: Config, alias: CheckConfig) -> AliasRunResult:
+    """Run an alias's members in order; return aggregate + member results."""
+    if not alias.is_alias or alias.members is None:
+        raise NotAliasError(f"[check.{alias.name}] is not an alias")
+
+    results: list[AtomicRunResult] = []
+    for member_name in alias.members:
+        member = cfg.checks[member_name]
+        outcome = run_one(cfg, member, extra=[])
+        results.append(outcome)
+        if alias.fail_fast and outcome.exit_code != 0:
+            break
+
+    exit_code = _alias_aggregate_exit(results)
+    status = "pass" if exit_code == 0 else "fail"
+    aggregate = build_alias_aggregate(
+        alias=alias.name,
+        results=[(r.check, r.status, r.rc, r.run_dir) for r in results],
+        status=status,
+        rc=exit_code,
+    )
+    return AliasRunResult(
+        alias=alias.name,
+        status=status,
+        aggregate=aggregate,
+        members=tuple(results),
+        exit_code=exit_code,
+    )
+
+
+def run_check(
+    cfg: Config,
+    name: str,
+    *,
+    extra: list[str] | None = None,
+) -> AtomicRunResult | AliasRunResult:
+    """Dispatch by check kind. Aliases reject ``extra``."""
+    check = cfg.checks.get(name)
+    if check is None:
+        raise UnknownCheckError(
+            f"unknown check '{name}'; configured: " + ", ".join(sorted(cfg.checks))
+        )
+    extra_args = list(extra or ())
+    if check.is_alias:
+        if extra_args:
+            raise AliasExtraArgsError(
+                f"alias '{check.name}' does not accept extra arguments; "
+                "run an atomic member check instead "
+                f"(members: {', '.join(check.members or ())})"
+            )
+        return run_alias(cfg, check)
+    return run_one(cfg, check, extra=extra_args)

ckdn/app/types.py

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 Den Rozhnovskiy <rozhnovskiydenis@gmail.com>
+# SPDX-License-Identifier: MIT
+"""Shared result types for the application layer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AtomicRunResult:
+    check: str
+    status: str
+    rc: int
+    run_dir: Path
+    digest: dict[str, Any]
+    exit_code: int
+
+
+@dataclass(frozen=True)
+class AliasRunResult:
+    alias: str
+    status: str
+    aggregate: dict[str, Any]
+    members: tuple[AtomicRunResult, ...]
+    exit_code: int