whykit 0.3.1__py3-none-any.whl

whykit/context.py

@@ -0,0 +1,204 @@
+"""Build bounded, evidence-aware context packs for people and AI agents."""
+from __future__ import annotations
+
+from .io import consistent_read
+
+import argparse
+import json
+import re
+from dataclasses import asdict
+from pathlib import Path
+
+from .contract import emit_error, vault_not_found
+from .impact import analyze_impact
+from .lint import (
+    Note,
+    path_cache,
+    DECISION_ID_RE,
+    EVIDENCE_ID_RE,
+    evidence_register,
+    find_vault_root,
+    is_vault_root,
+    lint,
+    rel,
+)
+from .vault_index import VaultIndex
+from .console import emit_machine
+
+
+def _resolve_note(root: Path, target: str, vault: VaultIndex):
+    if DECISION_ID_RE.fullmatch(target):
+        matches = [
+            note for note in vault.notes
+            if str(note.front.get("decision_id") or "").strip() == target
+        ]
+        return (matches[0], False) if len(matches) == 1 else (None, len(matches) > 1)
+    path, ambiguous = vault.resolve_link(target)
+    if path is None:
+        return None, ambiguous
+    return vault.note_for(path), ambiguous
+
+
+def _evidence_details(root: Path, ids: list[str]) -> list[dict]:
+    active, retired, _ = evidence_register(root)
+    out = []
+    for evidence_id in sorted(set(ids)):
+        row = active.get(evidence_id) or retired.get(evidence_id)
+        out.append({
+            "id": evidence_id,
+            "state": "active" if evidence_id in active else "retired" if evidence_id in retired else "missing",
+            "record": row,
+        })
+    return out
+
+
+FRONT_MATTER_RE = re.compile(r"\A\ufeff?---[ \t]*\r?\n.*?^---[ \t]*\r?$\n?", re.S | re.M)
+SUMMARY_KEYS = ("summary", "description")
+
+
+def _budgeted(note: Note, max_chars: int) -> tuple[str, bool]:
+    """The most useful *max_chars* of a note that does not fit whole.
+
+    Front matter goes first, because the pack already carries it as
+    structured fields (``record``): a 200-character budget spent on
+    ``aliases:`` and ``tags:`` would say nothing about the note. What is left
+    is the ``summary`` (or ``description``) front-matter value when the note
+    has one, then the body from its first line.
+    """
+    match = FRONT_MATTER_RE.match(note.text)
+    if not match:
+        return note.text[:max_chars], False
+    body = note.text[match.end():].lstrip("\r\n")
+    summary = next(
+        (str(note.front.get(key)).strip() for key in SUMMARY_KEYS if str(note.front.get(key) or "").strip()),
+        "",
+    )
+    if summary and summary not in body:
+        body = f"{summary}\n\n{body}"
+    return body[:max_chars], True
+
+
+@consistent_read
+@path_cache()
+def build_context(
+    root: Path,
+    target: str,
+    *,
+    max_chars: int = 20_000,
+    include_body: bool = True,
+    vault: VaultIndex | None = None,
+) -> dict:
+    if max_chars < 0:
+        raise ValueError("max_chars must be >= 0")
+    vault_index = vault or VaultIndex.load(root)
+    impact = analyze_impact(root, target, vault=vault_index)
+    if not impact.get("exists"):
+        return {
+            "contract_version": 1,
+            "target": target,
+            "exists": False,
+            "ambiguous": bool(impact.get("ambiguous")),
+            "kind": impact.get("kind"),
+        }
+
+    if EVIDENCE_ID_RE.fullmatch(target):
+        return {
+            "contract_version": 1,
+            "target": target,
+            "exists": True,
+            "kind": "evidence",
+            "evidence": _evidence_details(root, [target])[0],
+            "references": impact.get("references", []),
+            "replacement": impact.get("replacement"),
+        }
+
+    note, ambiguous = _resolve_note(root, target, vault_index)
+    if note is None:
+        return {
+            "contract_version": 1,
+            "target": target,
+            "exists": False,
+            "ambiguous": ambiguous,
+            "kind": impact.get("kind", "document"),
+        }
+
+    content = note.text
+    truncated = False
+    front_matter_omitted = False
+    if include_body and len(content) > max_chars:
+        content, front_matter_omitted = _budgeted(note, max_chars)
+        truncated = True
+    if not include_body:
+        content = ""
+
+    source_ids = list(note.cited_evidence)
+    note_path = rel(root, note.path)
+    _, scoped_findings = lint(root, [note_path], orphans=False, secrets=False, vault=vault_index)
+    scoped_findings = [item for item in scoped_findings if item.path == note_path]
+    return {
+        "contract_version": 1,
+        "target": target,
+        "exists": True,
+        "kind": impact.get("kind", "document"),
+        "record": impact.get("record"),
+        "content": content,
+        "content_truncated": truncated,
+        **({"front_matter_omitted": True} if front_matter_omitted else {}),
+        "content_chars": len(note.text),
+        "evidence": _evidence_details(root, source_ids),
+        "incoming": impact.get("incoming", []),
+        "outgoing": impact.get("outgoing", []),
+        "supersedes": impact.get("supersedes"),
+        "superseded_by": impact.get("superseded_by", []),
+        "findings": [asdict(item) for item in scoped_findings],
+    }
+
+
+def _human(report: dict) -> None:
+    if not report.get("exists"):
+        print(f"{report['target']}: {'ambiguous' if report.get('ambiguous') else 'not found'}")
+        return
+    print(f"Context for {report['target']} [{report['kind']}]")
+    if report["kind"] == "evidence":
+        evidence = report["evidence"]
+        print(f"  state        {evidence['state']}")
+        print(f"  references   {len(report.get('references', []))}")
+        if evidence.get("record"):
+            row = evidence["record"]
+            print(f"  source       {row.get('source') or '—'}")
+            print(f"  location     {row.get('location') or '—'}")
+        return
+    record = report.get("record") or {}
+    print(f"  document     {record.get('path', '—')}")
+    print(f"  owner        {record.get('owner') or '—'}")
+    print(f"  status       {record.get('status') or '—'}")
+    print(f"  evidence     {len(report.get('evidence', []))}")
+    print(f"  backlinks    {len(report.get('incoming', []))}")
+    print(f"  outgoing     {len(report.get('outgoing', []))}")
+    print(f"  findings     {len(report.get('findings', []))}")
+    if report.get("content"):
+        print("\n--- document ---")
+        print(report["content"])
+        if report.get("content_truncated"):
+            print("\n[content truncated]")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="whykit context", description="Build a bounded evidence-aware context pack for one WhyKit target.")
+    parser.add_argument("target", help="E-NNN, D-NNN, path, stem or alias")
+    parser.add_argument("--root", help="vault root (default: nearest vault)")
+    parser.add_argument("--max-chars", type=int, default=20_000)
+    parser.add_argument("--no-body", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    if args.max_chars < 0:
+        return emit_error("invalid_argument", "--max-chars must be >= 0", json_mode=args.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)
+    report = build_context(root, args.target, max_chars=args.max_chars, include_body=not args.no_body)
+    if args.json:
+        emit_machine(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        _human(report)
+    return 0 if report.get("exists") else 1

whykit/contract.py

@@ -0,0 +1,210 @@
+"""The machine contract shared by every command that writes JSON to stdout.
+
+Success payloads carry ``contract_version``. Failures that stop a command from
+producing its report are written as one error object instead::
+
+    {"contract_version": 1, "error": {"code": "...", "message": "...", "hint": "..."}}
+
+``code`` is stable and listed in :data:`ERROR_CODES`; ``message`` and ``hint``
+are for people and may be reworded. Exit codes do not change: the error object
+is an additional channel, and the same human-readable text still goes to
+stderr, so scripts that already read stderr keep working.
+
+See ``docs/automation.md`` for the full policy and ``schemas/`` for the shapes.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+from .console import emit_machine
+from .messages import no_vault
+
+CONTRACT_VERSION = 1
+
+# Stable error codes. Adding a code is a compatible change; renaming or removing
+# one is a breaking change and needs a CHANGELOG entry, exactly like a lint rule
+# code. Keep this table, schemas/error.schema.json and docs/automation.md in
+# step; tests/test_machine_contract.py enforces it.
+ERROR_CODES: dict[str, str] = {
+    "usage": "The command line could not be parsed, or options conflict.",
+    "invalid_argument": "An option or argument value is malformed or out of range (a date, a number, an ID, a snapshot file).",
+    "invalid_target": "The named source or destination exists but cannot be used by this command.",
+    "vault_not_found": "No WhyKit vault at --root, or at or above the working directory.",
+    "invalid_config": "whykit.toml could not be read or failed validation.",
+    "not_found": "The vault record named as the command's target does not exist.",
+    "unsafe_path": "A path was refused because it escapes the vault or passes through a symlink.",
+    "target_exists": "The command refused to overwrite existing content.",
+    "operation_rejected": "The vault refused the requested change, e.g. an already retired ID or a reference to an unknown record.",
+    "missing_dependency": "A required external tool or bundled file is missing (git, the vault template).",
+    "git_error": "Git could not answer, e.g. an unknown ref or a directory that is not a repository.",
+    "vault_invalid": "The vault is broken in a way that blocks this command: lint errors, or a missing register or log.",
+    "io_error": "The filesystem refused a read or write.",
+    "interrupted": "The command was interrupted.",
+    "internal_error": "WhyKit itself failed: an unexpected exception, which is a bug to report.",
+}
+
+# Where the internal_error hint sends people. Kept here so the CLI and the docs
+# test agree on one address.
+ISSUES_URL = "https://github.com/CometWeb-io/whykit/issues"
+
+# Each code has exactly one exit code. 1 means the command ran and the answer is
+# a problem with the vault (a missing target, a broken vault); 2 means it could
+# not run as asked; 70 means WhyKit crashed. Everything not listed here exits 2.
+ERROR_EXIT_CODES: dict[str, int] = {code: 2 for code in ERROR_CODES} | {
+    "not_found": 1,
+    "vault_invalid": 1,
+    "interrupted": 130,
+    # EX_SOFTWARE from sysexits.h: distinct from 1 and 2, so a CI job can tell
+    # "WhyKit broke" from "the vault is wrong" and "the job is misconfigured".
+    "internal_error": 70,
+}
+
+
+class TargetNotFound(ValueError):
+    """The record a command was asked to act on does not exist.
+
+    A ``ValueError`` so callers that already catch ``ValueError`` keep working;
+    the CLI reports it as ``not_found`` with exit code 1, matching read commands
+    that report a missing target as ``"exists": false`` with exit code 1.
+    """
+
+
+# The JSON Schema in ``schemas/`` that each command's JSON stdout follows.
+# Every command that accepts ``--json`` (or always writes JSON) is listed; a
+# test walks the argument parser to keep this table complete.
+OUTPUT_SCHEMAS: dict[str, str] = {
+    "init": "init-result.schema.json",
+    "recover": "recovery-result.schema.json",
+    "lint": "lint-report.schema.json",
+    "new decision": "record-create.schema.json",
+    "new evidence": "record-create.schema.json",
+    "new note": "record-create.schema.json",
+    "status": "status-report.schema.json",
+    "graph": "graph.schema.json",
+    "backlinks": "backlinks-report.schema.json",
+    "impact": "impact-report.schema.json",
+    "trace": "trace-report.schema.json",
+    "query": "query-result.schema.json",
+    "context": "context-pack.schema.json",
+    "pack": "context-bundle.schema.json",
+    "review list": "review-queue.schema.json",
+    "review record": "review-record-result.schema.json",
+    "review approve": "decision-approval-result.schema.json",
+    "snapshot": "snapshot.schema.json",
+    "verify-snapshot": "snapshot-verify.schema.json",
+    "check": "check-report.schema.json",
+    "policy": "policy.schema.json",
+    "evidence list": "evidence-list.schema.json",
+    "evidence retire": "evidence-retire-result.schema.json",
+    "adopt": "adopt-report.schema.json",
+    "history": "history-report.schema.json",
+    "diff": "diff-report.schema.json",
+    "rules": "rule-catalog.schema.json",
+    "rules <code>": "rule-detail.schema.json",
+    "doctor": "doctor-report.schema.json",
+    "explorer-index": "explorer-index.schema.json",
+    "explorer-index --publication-preview": "publication-preview.schema.json",
+}
+ERROR_SCHEMA = "error.schema.json"
+
+# Non-default machine formats that are not the JSON contract itself (so they
+# carry no top-level ``contract_version``) but still have a published schema.
+# ``--format github`` is GitHub's workflow-command text and has none.
+FORMAT_SCHEMAS: dict[str, str] = {
+    "lint --format sarif": "lint-sarif.schema.json",
+}
+
+_HINT_PREFIX = "hint: "
+
+
+def _split_hint(text: str) -> tuple[str, str | None]:
+    """Separate trailing ``hint: ...`` lines from a human error message."""
+    lines = text.rstrip("\n").split("\n")
+    hints: list[str] = []
+    while lines and lines[-1].startswith(_HINT_PREFIX):
+        hints.insert(0, lines.pop()[len(_HINT_PREFIX):])
+    message = "\n".join(lines).strip()
+    return message, ("\n".join(hints) if hints else None)
+
+
+def error_payload(code: str, message: str, hint: str | None = None) -> dict[str, Any]:
+    """Build the error object. ``code`` must be one of :data:`ERROR_CODES`."""
+    if code not in ERROR_CODES:
+        raise ValueError(f"unregistered error code: {code}")
+    return {
+        "contract_version": CONTRACT_VERSION,
+        "error": {"code": code, "message": message, "hint": hint},
+    }
+
+
+def emit_error(
+    code: str,
+    text: str,
+    *,
+    json_mode: bool,
+    hint: str | None = None,
+    json_hint: str | None = None,
+    stdout: TextIO | None = None,
+    stderr: TextIO | None = None,
+) -> int:
+    """Report a failure and return its exit code (see :data:`ERROR_EXIT_CODES`).
+
+    ``text`` is printed to stderr exactly as before, so human output does not
+    change. ``hint``, when given, is printed verbatim on the next line; when it
+    is omitted, trailing ``hint: ...`` lines of ``text`` become the JSON hint.
+    ``json_hint`` sets the JSON hint without adding a line to the human output.
+    With ``json_mode`` the error object is also written to stdout.
+    """
+    if code not in ERROR_CODES:
+        raise ValueError(f"unregistered error code: {code}")
+    out = stdout or sys.stdout
+    err = stderr or sys.stderr
+    print(text, file=err)
+    if hint is not None:
+        print(hint, file=err)
+    if json_mode:
+        message, embedded_hint = _split_hint(text)
+        if json_hint is None and hint is not None:
+            json_hint = hint[len(_HINT_PREFIX):] if hint.startswith(_HINT_PREFIX) else hint
+        if json_hint is None:
+            json_hint = embedded_hint
+        # Same UTF-8-safe path as every success payload (cp1252 consoles included).
+        emit_machine(json.dumps(error_payload(code, message, json_hint), ensure_ascii=False, indent=2), file=out)
+    return ERROR_EXIT_CODES[code]
+
+
+def describe_os_error(exc: OSError) -> str:
+    """One readable line for a filesystem refusal (no ``[Errno 13]`` prefix)."""
+    reason = exc.strerror or exc.__class__.__name__
+    if exc.filename is not None and exc.filename2 is not None:
+        return f"{reason}: {exc.filename} -> {exc.filename2}"
+    if exc.filename is not None:
+        return f"{reason}: {exc.filename}"
+    return str(exc) or reason
+
+
+def vault_not_found(explicit: str | None, *, json_mode: bool) -> int:
+    """The shared "no vault here" failure."""
+    return emit_error("vault_not_found", no_vault(explicit), json_mode=json_mode)
+
+
+def argv_wants_json(argv: list[str]) -> bool:
+    """Best-effort: did this command line ask for JSON on stdout?
+
+    Used only where the parsed namespace is not available yet, i.e. when the
+    command line itself cannot be parsed. ``--json`` may be abbreviated, as
+    argparse allows.
+    """
+    tokens = list(argv)
+    for index, token in enumerate(tokens):
+        if token == "--":
+            break
+        if len(token) >= 3 and token.startswith("--j") and "--json".startswith(token):
+            return True
+        if token == "--format=json":
+            return True
+        if token == "--format" and index + 1 < len(tokens) and tokens[index + 1] == "json":
+            return True
+    return "explorer-index" in tokens[:1]

whykit/contract_schemas/backlinks-report.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cometweb.io/schemas/whykit/backlinks-report.schema.json",
+  "title": "WhyKit backlinks report",
+  "description": "Output of `whykit backlinks --json`. A target that does not exist is a report with `exists: false` (exit 1), not an error object.",
+  "type": "object",
+  "required": [
+    "contract_version",
+    "target",
+    "id",
+    "kind",
+    "exists",
+    "backlinks",
+    "count"
+  ],
+  "properties": {
+    "contract_version": {
+      "const": 1
+    },
+    "target": {
+      "type": "string"
+    },
+    "id": {
+      "type": "string"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "exists": {
+      "type": "boolean"
+    },
+    "backlinks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "from",
+          "type",
+          "to"
+        ],
+        "properties": {
+          "from": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "to": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "count": {
+      "type": "integer",
+      "minimum": 0
+    }
+  },
+  "additionalProperties": true
+}

whykit/contract_schemas/context-bundle.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cometweb.io/schemas/whykit/context-bundle.schema.json",
+  "title": "WhyKit multi-record context bundle",
+  "type": "object",
+  "required": ["format", "contract_version", "resolved", "missing", "contexts", "evidence", "budget"],
+  "properties": {
+    "format": {"const": "whykit.context-bundle/v1"},
+    "contract_version": {"const": 1},
+    "query": {"type": ["string", "null"]},
+    "canonical_only": {"type": "boolean"},
+    "agent": {"enum": ["generic", "cursor", "claude", "codex"]},
+    "preamble": {"type": "string"},
+    "content_trust": {"const": "untrusted_data"},
+    "requested_targets": {"type": "array", "items": {"type": "string"}},
+    "selected": {"type": "array", "items": {"type": "string"}},
+    "resolved": {"type": "integer", "minimum": 0},
+    "missing": {"type": "array", "items": {"type": "object"}},
+    "contexts": {"type": "array", "items": {"type": "object"}},
+    "evidence": {"type": "array", "items": {"type": "object"}},
+    "budget": {
+      "type": "object",
+      "required": ["max_docs", "max_chars", "used_chars", "remaining_chars", "exhausted"]
+    }
+  },
+  "additionalProperties": false
+}

whykit/contract_schemas/context-pack.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cometweb.io/schemas/whykit/context-pack.schema.json",
+  "title": "WhyKit bounded context pack",
+  "type": "object",
+  "required": ["contract_version", "target", "exists"],
+  "properties": {
+    "contract_version": {"const": 1},
+    "target": {"type": "string"},
+    "exists": {"type": "boolean"},
+    "kind": {"type": "string"},
+    "path": {"type": ["string", "null"]},
+    "content": {"type": "string"},
+    "content_truncated": {"type": "boolean"},
+    "front_matter_omitted": {
+      "const": true,
+      "description": "Present when the body did not fit max_chars: the front matter was left out first (its fields are in `record`), so the content starts with the summary or the body."
+    },
+    "evidence": {
+      "description": "Evidence rows cited by a document or decision; for an E-NNN target, that entry's own register row.",
+      "anyOf": [{"type": "array", "items": {"type": "object"}}, {"type": "object"}]
+    },
+    "incoming": {"type": "array", "items": {"type": "object"}},
+    "outgoing": {"type": "array", "items": {"type": "object"}},
+    "supersession": {"type": "object"},
+    "findings": {"type": "array", "items": {"type": "object"}}
+  },
+  "additionalProperties": true
+}

whykit/contract_schemas/impact-report.schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cometweb.io/schemas/whykit/impact-report.schema.json",
+  "title": "WhyKit impact report",
+  "description": "Output of `whykit impact --json`. The fields after `exists` depend on `kind`; a missing target is a report with `exists: false`.",
+  "type": "object",
+  "required": [
+    "contract_version",
+    "target",
+    "kind",
+    "exists",
+    "reference_count"
+  ],
+  "properties": {
+    "contract_version": {
+      "const": 1
+    },
+    "target": {
+      "type": "string"
+    },
+    "kind": {
+      "enum": [
+        "evidence",
+        "decision",
+        "document"
+      ]
+    },
+    "exists": {
+      "type": "boolean"
+    },
+    "state": {
+      "enum": [
+        "active",
+        "retired",
+        "missing"
+      ]
+    },
+    "ambiguous": {
+      "type": "boolean"
+    },
+    "record": {
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "replacement": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "references": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "path"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string"
+          },
+          "owner": {
+            "type": "string"
+          },
+          "sensitivity": {
+            "type": "string"
+          },
+          "source_of_truth": {
+            "type": "boolean"
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "incoming": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "outgoing": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "supersedes": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "superseded_by": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "reference_count": {
+      "type": "integer",
+      "minimum": 0
+    }
+  },
+  "additionalProperties": true
+}