whykit 0.3.1__py3-none-any.whl

whykit/backlinks.py

@@ -0,0 +1,106 @@
+"""Inbound link discovery for documents, decisions and evidence."""
+from __future__ import annotations
+
+from .io import consistent_read
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .contract import vault_not_found
+from .graph import build_graph
+from .lint import (
+    _within,
+    path_is_file,
+    path_cache,
+    strip_markdown_suffix,
+    DECISION_ID_RE,
+    EVIDENCE_ID_RE,
+    find_vault_root,
+    is_vault_root,
+)
+from .vault_index import VaultIndex
+from .console import emit_machine
+
+
+def _normalize_target(root: Path, target: str, vault: VaultIndex) -> tuple[str, str]:
+    """Return (kind, graph_id) for a CLI target.
+
+    Documents resolve exactly as wikilinks do, so a bare stem or an alias finds
+    the note wherever it lives instead of being looked up as a root-level path.
+    """
+    raw = target.strip()
+    if EVIDENCE_ID_RE.fullmatch(raw):
+        return "evidence", f"evidence:{raw}"
+    if DECISION_ID_RE.fullmatch(raw):
+        for note in vault.notes:
+            if str(note.front.get("decision_id") or "").strip() == raw:
+                return "decision", strip_markdown_suffix(vault.relative(note.path))
+        return "decision", raw
+    try:
+        path = Path(raw).expanduser()
+    except RuntimeError:  # `~name` for a user that does not exist
+        path = Path(raw)
+    if path.is_absolute():
+        # Containment before any file system call: another drive or a UNC share
+        # is answered from the strings alone.
+        if path.suffix.lower() == ".md" and _within(root, path) and path_is_file(path) and vault.note_for(path) is not None:
+            return "document", strip_markdown_suffix(vault.relative(path))
+        return "document", strip_markdown_suffix(raw)
+    resolved, ambiguous = vault.resolve_link(raw)
+    if resolved is not None and not ambiguous:
+        return "document", strip_markdown_suffix(vault.relative(resolved))
+    return "document", strip_markdown_suffix(raw)
+
+
+@consistent_read
+@path_cache()
+def build_backlinks(root: Path, target: str, *, vault: VaultIndex | None = None) -> dict:
+    root = root.resolve()
+    vault = vault or VaultIndex.load(root)
+    kind, node_id = _normalize_target(root, target, vault)
+    graph = build_graph(root, vault=vault)
+    known = {node["id"] for node in graph["nodes"]}
+    exists = node_id in known
+    inbound = [
+        {
+            "from": edge["from"],
+            "type": edge["type"],
+            "to": edge["to"],
+        }
+        for edge in graph["edges"]
+        if edge["to"] == node_id
+    ]
+    inbound.sort(key=lambda item: (item["type"], item["from"]))
+    return {
+        "contract_version": 1,
+        "target": target,
+        "id": node_id,
+        "kind": kind,
+        "exists": exists,
+        "backlinks": inbound,
+        "count": len(inbound),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="whykit backlinks", description="List inbound links to a note, decision or evidence ID.")
+    parser.add_argument("target", help="path, stem, D-NNN or E-NNN")
+    parser.add_argument("--root", help="vault root (default: nearest vault)")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    root = Path(args.root).expanduser().resolve() if args.root else find_vault_root()
+    if root is None or not is_vault_root(root):
+        return vault_not_found(args.root, json_mode=args.json)
+    report = build_backlinks(root, args.target)
+    if args.json:
+        emit_machine(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        if not report["exists"]:
+            print(f"target not found in graph: {report['id']}", file=sys.stderr)
+            return 1
+        print(f"backlinks for {report['id']} ({report['count']})")
+        for item in report["backlinks"]:
+            print(f"  {item['type']:<10} {item['from']}")
+    return 0 if report["exists"] else 1

whykit/check.py

@@ -0,0 +1,320 @@
+"""Policy-profile quality gates for local work, CI and releases."""
+from __future__ import annotations
+
+from .io import consistent_read
+
+import argparse
+import datetime as dt
+import json
+import shutil
+import subprocess
+from dataclasses import asdict
+from pathlib import Path
+
+from .contract import emit_error, vault_not_found
+from .config import CONFIG_FILE, ConfigError, configuration_readiness, get_profile, load_config, parse_config
+from .immutability import _git_prefix, _require_revisions, changed_records, git
+from .lint import _parse_date, find_vault_root, is_vault_root, lint, rel, path_cache
+from .console import emit_machine, one_line
+from .rule_policy import Override, describe_override, secret_scan_skipped
+
+
+def _git_repo(root: Path) -> bool:
+    if not shutil.which("git"):
+        return False
+    result = subprocess.run(["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"], capture_output=True, text=True, encoding="utf-8", errors="replace")
+    return result.returncode == 0 and result.stdout.strip() == "true"
+
+
+def _git_clean(root: Path) -> bool:
+    result = subprocess.run(["git", "-C", str(root), "status", "--porcelain"], capture_output=True, text=True, encoding="utf-8", errors="replace")
+    return result.returncode == 0 and not result.stdout.strip()
+
+
+def _run_profile(
+    root: Path,
+    config: dict,
+    config_path: Path | None,
+    *,
+    profile_name: str,
+    base: str | None = None,
+    head: str = "HEAD",
+    today: dt.date | None = None,
+) -> dict:
+    profile = get_profile(config, profile_name)
+    applied: list[Override] = []
+    files, findings = lint(
+        root,
+        orphans=bool(profile["orphans"]),
+        secrets=bool(profile["secrets"]),
+        hub_links=bool(profile.get("require_hub_links", False)),
+        today=today,
+        overrides=applied,
+        config=config,
+    )
+    if not profile["secrets"]:
+        applied.append(secret_scan_skipped(f"profile {profile_name} (secrets = false)"))
+    errors = [item for item in findings if item.level == "error"]
+    warnings = [item for item in findings if item.level == "warning"]
+    checks: list[dict] = []
+
+    lint_passed = not errors and not (profile["strict"] and warnings)
+    checks.append({
+        "name": "lint",
+        "passed": lint_passed,
+        "detail": f"{len(files)} files, {len(errors)} errors, {len(warnings)} warnings",
+    })
+
+    git_repo = _git_repo(root)
+    if profile["require_git"]:
+        checks.append({"name": "git_repository", "passed": git_repo, "detail": "git work tree required"})
+    else:
+        checks.append({"name": "git_repository", "passed": True, "detail": "not required" if not git_repo else "detected"})
+
+    if profile["require_clean_tree"]:
+        clean = git_repo and _git_clean(root)
+        checks.append({"name": "clean_tree", "passed": clean, "detail": "working tree must be clean"})
+    else:
+        checks.append({"name": "clean_tree", "passed": True, "detail": "not required"})
+
+    if profile["require_configured"]:
+        ready, reasons = configuration_readiness(config, config_path)
+        checks.append({
+            "name": "policy_configuration",
+            "passed": ready,
+            "detail": "repository policy is configured" if ready else "; ".join(reasons),
+        })
+    else:
+        checks.append({"name": "policy_configuration", "passed": True, "detail": "not required"})
+
+    history_checked = False
+    history_mode = profile["history"]
+    if history_mode == "off":
+        checks.append({"name": "history", "passed": True, "detail": "disabled by profile"})
+    elif base:
+        if not git_repo:
+            checks.append({"name": "history", "passed": False, "detail": "--base supplied but vault is not in a git work tree"})
+        else:
+            try:
+                history_reasons: dict[str, str] = {}
+                blocked = changed_records(base, head, str(root), reasons=history_reasons)
+            except subprocess.CalledProcessError as exc:
+                checks.append({"name": "history", "passed": False, "detail": (exc.stderr or str(exc)).strip()})
+            else:
+                history_checked = True
+                checks.append({
+                    "name": "history",
+                    "passed": not blocked,
+                    "detail": "immutable reasoning unchanged" if not blocked else f"{len(blocked)} immutable decision change(s)",
+                    "blocked": [{"status": status, "path": path, **({"reason": history_reasons[path]} if path in history_reasons else {})} for status, path in blocked],
+                })
+    elif history_mode == "required":
+        checks.append({"name": "history", "passed": False, "detail": "profile requires --base <git-ref>"})
+    else:
+        checks.append({"name": "history", "passed": True, "detail": "optional; pass --base to enforce"})
+
+    checks[-1]["checked"] = history_checked
+    passed = all(item["passed"] for item in checks)
+    lint_report: dict = {
+        "files": len(files),
+        "errors": len(errors),
+        "warnings": len(warnings),
+        "findings": [asdict(item) for item in findings],
+    }
+    if applied:
+        lint_report["overrides"] = [entry.report() for entry in applied]
+    return {
+        "contract_version": 1,
+        "profile": profile_name,
+        "profile_config": profile,
+        "config_source": rel(root, config_path) if config_path else "built-in defaults",
+        "as_of": (today or dt.date.today()).isoformat(),
+        "passed": passed,
+        "history_checked": history_checked,
+        "checks": checks,
+        "lint": lint_report,
+    }
+
+
+@consistent_read
+@path_cache()
+def run_check(
+    root: Path,
+    *,
+    profile_name: str,
+    base: str | None = None,
+    head: str = "HEAD",
+    today: dt.date | None = None,
+) -> dict:
+    """Check the working vault against both head and protected base policies."""
+    config, path = load_config(root)
+    report = _run_profile(root, config, path, profile_name=profile_name, base=base, head=head, today=today)
+    if base is None:
+        return report
+    try:
+        _require_revisions(str(root), base)
+        policy_path = _git_prefix(str(root)) + CONFIG_FILE
+        entry = git("ls-tree", "-z", "--full-tree", base, "--", policy_path, root=str(root))
+        if entry:
+            if entry.split(" ", 1)[0] not in {"100644", "100755"}:
+                raise ConfigError("baseline policy must be a regular file")
+            baseline_config = parse_config(git("show", f"{base}:{policy_path}", root=str(root)))
+        else:
+            baseline_config = parse_config("")
+        baseline = _run_profile(
+            root, baseline_config, root / CONFIG_FILE if entry else None,
+            profile_name=profile_name, base=base, head=head, today=today,
+        )
+        baseline["config_source"] = f"{base}:{policy_path}" if entry else f"{base}:built-in defaults"
+    except (ConfigError, subprocess.CalledProcessError) as exc:
+        report["checks"].append({
+            "name": "baseline_policy", "passed": False,
+            "detail": f"cannot validate policy at {base}: " + (getattr(exc, "stderr", None) or str(exc)).strip(),
+        })
+    else:
+        report["baseline"] = {"ref": base, **baseline}
+        report["history_checked"] = report["history_checked"] or baseline["history_checked"]
+        failed = "; ".join(f"{check['name']}: {check['detail']}" for check in baseline["checks"] if not check["passed"])
+        report["checks"].append({
+            "name": "baseline_policy", "passed": baseline["passed"],
+            "detail": f"policy at {base}: " + (failed or "all checks passed"),
+        })
+    report["passed"] = all(check["passed"] for check in report["checks"])
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="whykit check", description="Run a versioned local/CI/release WhyKit policy profile.")
+    parser.add_argument("--root", help="vault root (default: nearest vault)")
+    parser.add_argument("--profile", default="ci", help="policy profile from whykit.toml (default: ci)")
+    parser.add_argument("--base", help="base git ref for immutable-history verification")
+    parser.add_argument("--head", default="HEAD")
+    parser.add_argument("--today", help="evaluate review dates as of this ISO date")
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--format", choices=("text", "json", "github"), default=None, help="output format (default: text)")
+    args = parser.parse_args(argv)
+    if args.json and args.format not in (None, "json"):
+        return emit_error(
+            "usage",
+            f"--json conflicts with --format {args.format}\nhint: pass one of them to `whykit check`",
+            json_mode=True,
+        )
+    fmt = "json" if args.json else (args.format or "text")
+    args.json = fmt == "json"
+    root = Path(args.root).expanduser().resolve() if args.root else find_vault_root()
+    if root is None or not is_vault_root(root):
+        return vault_not_found(args.root, json_mode=args.json)
+    today = None
+    if args.today:
+        # Same YYYY-MM-DD contract as `whykit lint --today`; fromisoformat alone
+        # would also accept forms such as 20260917 or 2026-W38-4.
+        today = _parse_date(args.today)
+        if today is None:
+            return emit_error("invalid_argument", f"--today is not a real ISO date: {args.today}", json_mode=args.json)
+    try:
+        report = run_check(root, profile_name=args.profile, base=args.base, head=args.head, today=today)
+    except ConfigError as exc:
+        return emit_error("invalid_config", str(exc), json_mode=args.json)
+    if args.json:
+        emit_machine(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        if fmt == "github":
+            annotations = gate_annotations(report, root)
+            if annotations:
+                emit_machine("\n".join(annotations))
+        state = "PASS" if report["passed"] else "FAIL"
+        print(f"WhyKit {report['profile']} gate — {state}")
+        print(f"  config  {one_line(report['config_source'])}")
+        width = max(len(check["name"]) for check in report["checks"])
+        for check in report["checks"]:
+            marker = "SKIP" if check.get("checked") is False and check["passed"] else ("OK" if check["passed"] else "FAIL")
+            print(f"  {marker:<4} {check['name']:<{width}}  {one_line(check['detail'])}")
+            for item in check.get("blocked", []):
+                print(f"         {item['status']}  {one_line(item['path'])}")
+        if report["lint"]["errors"] or report["lint"]["warnings"]:
+            print(f"  lint findings  {report['lint']['errors']} error(s), {report['lint']['warnings']} warning(s)")
+        _print_gate_findings(report)
+        if report.get("baseline", {}).get("lint", {}).get("findings"):
+            print("  findings under the baseline policy:")
+            _print_gate_findings(report["baseline"])
+        for entry in report["lint"].get("overrides", []):
+            if entry["security"]:
+                print(f"  policy  {one_line(describe_override(entry))}")
+    return 0 if report["passed"] else 1
+
+
+MAX_GATE_FINDINGS = 20
+
+
+def gate_annotations(report: dict, root: Path) -> list[str]:
+    """GitHub workflow commands for a gate report.
+
+    Every lint finding is annotated at its level, so a reviewer sees warnings
+    inline even when the profile does not fail on them. Rewritten decision
+    history is an error on the record; any other failed check is an error
+    without a file.
+    """
+    from .ci_formats import github_annotations, source_root, workflow_command
+
+    lines = github_annotations(report["lint"]["findings"], root)
+    for entry in report["lint"].get("overrides", []):
+        if entry["security"]:
+            text = describe_override(entry)
+            lines.append(workflow_command(
+                "notice", text if entry.get("skipped_by") else f"whykit.toml policy: {text}", title="WhyKit policy",
+            ))
+    _, prefix = source_root(root)
+    for check in report["checks"]:
+        if check["passed"] or check["name"] == "lint":
+            continue
+        blocked = check.get("blocked") or []
+        for item in blocked:
+            path = item["path"].split(" -> ")[0]
+            reason = item.get("reason")
+            message = (
+                f"{reason}: include a newly appended matching review event with this record."
+                if reason else
+                f"Accepted decision reasoning is append-only ({item['status']}); supersede it with a new record instead of rewriting it."
+            )
+            lines.append(workflow_command(
+                "error",
+                message,
+                file=f"{prefix}{path}",
+                title="WhyKit history",
+            ))
+        if not blocked:
+            lines.append(workflow_command("error", f"{check['name']}: {check['detail']}", title=f"WhyKit {report['profile']} gate"))
+    lint_check = next((c for c in report["checks"] if c["name"] == "lint"), None)
+    if lint_check is not None and not lint_check["passed"] and not report["lint"]["errors"]:
+        lines.append(workflow_command(
+            "error",
+            f"profile {report['profile']} is strict: {report['lint']['warnings']} warning(s) fail this gate",
+            title=f"WhyKit {report['profile']} gate",
+        ))
+    return lines
+
+
+def _print_gate_findings(report: dict) -> None:
+    """Show the findings that failed the lint check.
+
+    A CI log is often all a reviewer sees; a bare "5 warnings" sends them off
+    to rerun the linter locally just to learn what broke the gate.
+    """
+    lint_check = next((c for c in report["checks"] if c["name"] == "lint"), None)
+    if lint_check is None or lint_check["passed"]:
+        return
+    strict = bool(report["profile_config"].get("strict"))
+    failing = [
+        item for item in report["lint"]["findings"]
+        if item["level"] == "error" or (strict and item["level"] == "warning")
+    ]
+    failing.sort(key=lambda item: (item["level"] != "error", item["path"], item["line"] or 0))
+    print("")
+    print("  findings that fail this gate:")
+    for item in failing[:MAX_GATE_FINDINGS]:
+        location = f"{item['path']}:{item['line']}" if item["line"] else item["path"]
+        print(f"    {item['level']:<7} {one_line(location)}  [{item['code']}] {one_line(item['message'])}")
+    if len(failing) > MAX_GATE_FINDINGS:
+        print(f"    ... {len(failing) - MAX_GATE_FINDINGS} more; run `whykit lint` for the full list")
+    if strict and any(item["level"] == "warning" for item in failing):
+        print("  this profile is strict: warnings fail it (see `whykit policy`)")