flyleaf 0.5.0__py3-none-any.whl

flyleaf/__init__.py

@@ -0,0 +1,11 @@
+# Copyright 2026 Krishna Dahale
+# SPDX-License-Identifier: Apache-2.0
+"""Inventory AI components in a repository and list areas to review."""
+
+__version__ = "0.5.0"
+
+DISCLAIMER = (
+    "flyleaf lists AI components and areas to review. "
+    "Legal classification under the EU AI Act depends on the use case, "
+    "which code cannot determine. This output is not legal advice."
+)

flyleaf/attribution.py

@@ -0,0 +1,96 @@
+# Copyright 2026 Krishna Dahale
+# SPDX-License-Identifier: Apache-2.0
+"""Who should look at a finding.
+
+Two different names, deliberately kept apart. The owner is declared in
+`.flyleaf/systems.toml` and is accountable for the system. The author is read
+from git blame and is whoever last touched the evidence line. The author is
+the person who can answer the question now. The owner is the person who is
+answerable for it either way.
+
+Blame names a line, not a responsibility. A reformat, a rename, or a bot
+bumping a version will make the wrong person the author, so the report says
+where the name came from and never calls it fault.
+"""
+
+import re
+import subprocess
+from pathlib import Path
+
+BOT_PATTERN = re.compile(r"(?i)\[bot\]|^(dependabot|renovate|github-actions)\b")
+_EMPTY_SHA = "0" * 40
+
+
+def last_author(repo: Path, rev: str | None, path: str, line: int) -> dict | None:
+    """Return who last changed `line` of `path`, or None when git cannot say.
+
+    `rev` blames at a revision. None blames the working tree, where an
+    uncommitted edit has no author yet.
+    """
+    args = ["blame", "--porcelain", "-L", f"{max(1, line)},{max(1, line)}"]
+    if rev:
+        args.append(rev)
+    args.extend(["--", path])
+    try:
+        completed = subprocess.run(
+            ["git", "-C", str(repo), *args],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except (OSError, subprocess.CalledProcessError):
+        return None
+    return _parse(completed.stdout)
+
+
+def _parse(output: str) -> dict | None:
+    lines = output.splitlines()
+    if not lines:
+        return None
+    commit = lines[0].split(" ", 1)[0]
+    fields: dict[str, str] = {}
+    for raw in lines[1:]:
+        if raw.startswith("\t"):
+            break
+        key, _, value = raw.partition(" ")
+        fields.setdefault(key, value)
+
+    name = fields.get("author", "").strip()
+    email = fields.get("author-mail", "").strip().strip("<>")
+    uncommitted = commit == _EMPTY_SHA
+    if uncommitted:
+        return {
+            "name": None,
+            "email": None,
+            "commit": None,
+            "summary": None,
+            "uncommitted": True,
+            "is_bot": False,
+            "source": "git blame",
+        }
+    if not name and not email:
+        return None
+    return {
+        "name": name or None,
+        "email": email or None,
+        "commit": commit[:12],
+        "summary": fields.get("summary") or None,
+        "uncommitted": False,
+        "is_bot": _is_bot(name, email),
+        "source": "git blame",
+    }
+
+
+def _is_bot(name: str, email: str) -> bool:
+    return bool(BOT_PATTERN.search(name or "") or BOT_PATTERN.search(email or ""))
+
+
+def label(author: dict | None) -> str:
+    """A short human label for a report line."""
+    if author is None:
+        return "unknown"
+    if author["uncommitted"]:
+        return "uncommitted change"
+    who = author["email"] or author["name"] or "unknown"
+    suffix = " (bot)" if author["is_bot"] else ""
+    return f"{who}{suffix}"

flyleaf/baseline.py

@@ -0,0 +1,66 @@
+# Copyright 2026 Krishna Dahale
+# SPDX-License-Identifier: Apache-2.0
+"""A baseline is the inventory as it stood at the last sign-off."""
+
+import json
+from datetime import UTC, date, datetime
+from pathlib import Path
+
+from flyleaf import __version__
+from flyleaf.scan import scan_path
+
+BASELINE_FILE = Path(".flyleaf") / "baseline.json"
+
+
+class BaselineError(Exception):
+    """The baseline could not be read."""
+
+
+def baseline_path(repo: Path) -> Path:
+    return repo / BASELINE_FILE
+
+
+def write_baseline(repo: Path, rev: str | None, approved_by: str | None) -> Path:
+    """Record the current tree as the approved state."""
+    inventory = scan_path(repo)
+    document = {
+        "kind": "baseline",
+        "tool": {"name": "flyleaf", "version": __version__},
+        "recorded_at": datetime.now(UTC).date().isoformat(),
+        "rev": rev,
+        "approved_by": approved_by,
+        "inventory": inventory,
+    }
+    destination = baseline_path(repo)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+    return destination
+
+
+def read_baseline(repo: Path) -> dict:
+    path = baseline_path(repo)
+    if not path.is_file():
+        raise BaselineError(
+            f"No baseline at {BASELINE_FILE.as_posix()}. Run 'flyleaf baseline' to record one."
+        )
+    try:
+        document = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise BaselineError(f"Could not read {BASELINE_FILE.as_posix()}: {exc}") from exc
+    inventory = document.get("inventory")
+    if not isinstance(inventory, dict) or "components" not in inventory:
+        raise BaselineError(f"{BASELINE_FILE.as_posix()} does not contain an inventory.")
+    return document
+
+
+def describe(document: dict) -> dict:
+    return {
+        "ref": "baseline",
+        "rev": document.get("rev"),
+        "recorded_at": document.get("recorded_at"),
+        "approved_by": document.get("approved_by"),
+    }
+
+
+def today() -> date:
+    return datetime.now(UTC).date()

flyleaf/brief.py

@@ -0,0 +1,427 @@
+# Copyright 2026 Krishna Dahale
+# SPDX-License-Identifier: Apache-2.0
+"""Compare two inventories and list documentation changes with citations."""
+
+import io
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+from datetime import date
+from pathlib import Path
+
+from flyleaf import DISCLAIMER, __version__, attribution
+from flyleaf import baseline as baseline_store
+from flyleaf import severity as severity_grades
+from flyleaf import waivers as waiver_store
+from flyleaf.citations import pack_meta, payloads_for
+from flyleaf.scan import SCHEMA_VERSION, scan_path
+
+
+class GitError(Exception):
+    """The repository could not be read with git."""
+
+
+def build_brief(
+    start: Path,
+    base: str | None,
+    head: str | None,
+    use_baseline: bool = False,
+    today: date | None = None,
+    blame: bool = True,
+) -> dict:
+    """Diff a base state against a head state.
+
+    The base is a git ref, or the recorded baseline when `use_baseline` is set.
+    The head is a git ref, or the working tree when `head` is omitted.
+    """
+    if not start.exists():
+        raise FileNotFoundError(start)
+    repo = _git_root(start)
+    now = today or baseline_store.today()
+
+    if use_baseline:
+        document = baseline_store.read_baseline(repo)
+        base_inventory = document["inventory"]
+        base_meta = baseline_store.describe(document)
+    else:
+        base_rev = _rev_parse(repo, base or "HEAD")
+        base_inventory = _scan_ref(repo, base_rev)
+        base_meta = {"ref": base, "rev": base_rev}
+
+    if head is None:
+        head_meta = {
+            "ref": "working tree",
+            "rev": _rev_parse(repo, "HEAD"),
+            "dirty": bool(_git(repo, "status", "--porcelain")),
+        }
+        head_inventory = scan_path(repo)
+    else:
+        head_rev = _rev_parse(repo, head)
+        head_meta = {"ref": head, "rev": head_rev, "dirty": False}
+        head_inventory = _scan_ref(repo, head_rev)
+
+    found = _diff(base_inventory, head_inventory)
+    _attribute(repo, found, head_inventory, head_meta, base_meta, blame)
+
+    loaded, warnings = waiver_store.load_waivers(repo)
+    findings, waived = _partition(found, loaded, now)
+    findings, system_waived = _partition(_rollup(findings), loaded, now)
+    waived.extend(system_waived)
+    warnings.extend(_expiry_warnings(waived, now))
+
+    citation_ids: set[str] = set()
+    for finding in findings + waived:
+        citation_ids.update(finding["citation_ids"])
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "kind": "brief",
+        "tool": {"name": "flyleaf", "version": __version__},
+        "disclaimer": DISCLAIMER,
+        "severity_note": severity_grades.SEVERITY_NOTE,
+        "citation_pack": pack_meta(),
+        "citations": payloads_for(citation_ids),
+        "repository": str(repo),
+        "as_of": now.isoformat(),
+        "base": base_meta,
+        "head": head_meta,
+        "systems": head_inventory.get("systems", []),
+        "findings": findings,
+        "waived": waived,
+        "warnings": warnings,
+    }
+
+
+def _attribute(
+    repo: Path,
+    findings: list[dict],
+    head_inventory: dict,
+    head_meta: dict,
+    base_meta: dict,
+    blame: bool,
+) -> None:
+    """Put a name on every finding, from the declared owner and from git blame."""
+    owners = {
+        system["name"]: system.get("owner")
+        for system in head_inventory.get("systems") or []
+    }
+    head_rev = None if head_meta["ref"] == "working tree" else head_meta["rev"]
+    for finding in findings:
+        finding["owner"] = owners.get(finding.get("system") or "")
+        if not blame:
+            finding["author"] = None
+            continue
+        # A removed component is not in the head tree, so blame the base.
+        rev = base_meta.get("rev") if finding["change"] == "removed" else head_rev
+        finding["author"] = attribution.last_author(repo, rev, finding["path"], finding["line"])
+
+
+def highest_severity(brief: dict) -> str | None:
+    """The worst severity among active findings, or None when the brief is quiet."""
+    worst: str | None = None
+    for finding in brief["findings"]:
+        if worst is None or severity_grades.at_least(finding["severity"], worst):
+            worst = finding["severity"]
+    return worst
+
+
+def _partition(
+    findings: list[dict],
+    waivers: list[waiver_store.Waiver],
+    today: date,
+) -> tuple[list[dict], list[dict]]:
+    """Split findings into active and waived.
+
+    An expired waiver does not suppress. The finding returns for review and
+    says which waiver lapsed.
+    """
+    active: list[dict] = []
+    waived: list[dict] = []
+    for finding in findings:
+        waiver = waiver_store.match(waivers, finding["component_id"], finding["change"])
+        if waiver is None:
+            active.append(finding)
+            continue
+        payload = waiver.payload(today)
+        if waiver.days_left(today) < 0:
+            finding["waiver"] = payload
+            finding["waiver_state"] = "expired"
+            finding["summary"] = (
+                f"{finding['summary']} A waiver by {waiver.approved_by} expired on "
+                f"{waiver.expires.isoformat()}, so this is open again."
+            )
+            active.append(finding)
+        else:
+            finding["waiver"] = payload
+            finding["waiver_state"] = "active"
+            waived.append(finding)
+    return active, waived
+
+
+def _expiry_warnings(waived: list[dict], today: date) -> list[str]:
+    warnings: list[str] = []
+    for finding in waived:
+        waiver = finding["waiver"]
+        days = waiver["days_left"]
+        if days <= waiver_store.EXPIRY_WARNING_DAYS:
+            warnings.append(
+                f"Waiver for {finding['component_id']} expires on {waiver['expires']} "
+                f"in {days} day(s). Renew it or close the finding."
+            )
+    return warnings
+
+
+def _diff(base_inventory: dict, head_inventory: dict) -> list[dict]:
+    base_map = {component["id"]: component for component in base_inventory["components"]}
+    head_map = {component["id"]: component for component in head_inventory["components"]}
+    findings: list[dict] = []
+    for component_id in sorted(set(base_map) | set(head_map)):
+        before = base_map.get(component_id)
+        after = head_map.get(component_id)
+        if before is None and after is not None:
+            findings.append(_added(after))
+        elif after is None and before is not None:
+            findings.append(_removed(before))
+        elif before is not None and after is not None:
+            findings.extend(_changed(before, after))
+    return _sorted(findings)
+
+
+def _sorted(findings: list[dict]) -> list[dict]:
+    return sorted(
+        findings,
+        key=lambda item: (-severity_grades.rank(item["severity"]), item["path"], item["framework"]),
+    )
+
+
+def _rollup(findings: list[dict]) -> list[dict]:
+    """Collapse the findings of a declared system into one.
+
+    Components are the evidence. A system is what a person documents, so when
+    the repository declares one, the system is what the brief reports.
+    """
+    grouped: dict[str, list[dict]] = {}
+    standalone: list[dict] = []
+    for finding in findings:
+        name = finding.get("system")
+        if name:
+            grouped.setdefault(name, []).append(finding)
+        else:
+            standalone.append(finding)
+    rolled = [_system_finding(name, members) for name, members in grouped.items()]
+    return _sorted(standalone + rolled)
+
+
+def _system_finding(name: str, members: list[dict]) -> dict:
+    lead = max(members, key=lambda item: severity_grades.rank(item["severity"]))
+    citation_ids: list[str] = []
+    for member in members:
+        for citation_id in member["citation_ids"]:
+            if citation_id not in citation_ids:
+                citation_ids.append(citation_id)
+    frameworks = sorted({member["framework"] for member in members})
+    changes = sorted({member["change"] for member in members})
+    authors: list[dict] = []
+    for member in members:
+        author = member.get("author")
+        if author and author not in authors:
+            authors.append(author)
+    missing = any(member["model_card_status"] == "missing" for member in members)
+    if len(members) == 1:
+        summary = f"System '{name}': {lead['summary']}"
+    else:
+        summary = (
+            f"System '{name}': {len(members)} components changed "
+            f"({', '.join(changes)}). {lead['summary']}"
+        )
+    return {
+        "kind": "system",
+        "component_id": f"system:{name}",
+        "system": name,
+        "path": lead["path"],
+        "line": lead["line"],
+        "framework": ", ".join(frameworks),
+        "frameworks": frameworks,
+        "change": lead["change"],
+        "changes": changes,
+        "impact": "runtime"
+        if any(member["impact"] == "runtime" for member in members)
+        else "documentation",
+        "severity": lead["severity"],
+        "status": "missing" if missing else "needs_review",
+        "summary": summary,
+        "model_card_status": "missing" if missing else "present",
+        "citation_ids": citation_ids,
+        "owner": lead.get("owner"),
+        "author": lead.get("author"),
+        "authors": authors,
+        "members": [_member(member) for member in members],
+        "waiver": None,
+        "waiver_state": "none",
+    }
+
+
+def _member(finding: dict) -> dict:
+    return {
+        "component_id": finding["component_id"],
+        "path": finding["path"],
+        "line": finding["line"],
+        "framework": finding["framework"],
+        "change": finding["change"],
+        "impact": finding["impact"],
+        "severity": finding["severity"],
+        "author": finding.get("author"),
+    }
+
+
+def _added(component: dict) -> dict:
+    missing = component["model_card_status"] == "missing"
+    summary = (
+        "New component, and no model card was found."
+        if missing
+        else "New component. A model card is present. Confirm that the card describes this component."
+    )
+    return _finding(
+        component,
+        change="added",
+        status="missing" if missing else "needs_review",
+        summary=summary,
+    )
+
+
+def _removed(component: dict) -> dict:
+    return _finding(
+        component,
+        change="removed",
+        status="needs_review",
+        summary=(
+            "This component was in the base state and is absent from the head state. "
+            "Check whether a model card still describes it."
+        ),
+    )
+
+
+def _changed(before: dict, after: dict) -> list[dict]:
+    evidence_changed = _evidence_key(before) != _evidence_key(after)
+    card_changed = before.get("model_card_sha256") != after.get("model_card_sha256")
+    missing = after["model_card_status"] == "missing"
+    if not evidence_changed and not card_changed:
+        return []
+
+    if missing and before["model_card_status"] == "present":
+        change = "card_removed"
+        summary = "The model card that was present in the base state is gone."
+        status = "missing"
+    elif before["model_card_status"] == "missing" and not missing:
+        change = "card_added"
+        summary = (
+            "A model card appeared for this component. "
+            "Confirm that it describes this component and not only its neighbours."
+        )
+        status = "needs_review"
+    elif evidence_changed and missing:
+        change = "evidence_changed"
+        summary = "The detected evidence changed, and there is still no model card."
+        status = "missing"
+    elif evidence_changed and not card_changed:
+        change = "card_stale"
+        summary = (
+            "The detected evidence changed and the model card content did not. "
+            "Article 11 asks that technical documentation of a high-risk system be kept up to date. "
+            "Confirm whether that article applies, and whether this card still matches the code."
+        )
+        status = "needs_review"
+    elif evidence_changed and card_changed:
+        change = "evidence_and_card_changed"
+        summary = "The detected evidence and the model card both changed. Read them together."
+        status = "needs_review"
+    else:
+        change = "card_changed"
+        summary = "The model card changed and the detected evidence did not."
+        status = "needs_review"
+    return [_finding(after, change=change, status=status, summary=summary)]
+
+
+def _finding(component: dict, change: str, status: str, summary: str) -> dict:
+    citation_ids: list[str] = []
+    for hint in component["review_hints"]:
+        for citation_id in hint["citation_ids"]:
+            if citation_id not in citation_ids:
+                citation_ids.append(citation_id)
+    for citation_id in component["documentation_citation_ids"]:
+        if citation_id not in citation_ids:
+            citation_ids.append(citation_id)
+    documented = component["model_card_status"] == "present"
+    impact, level = severity_grades.grade(change, documented)
+    evidence = component["evidence"]
+    return {
+        "kind": "component",
+        "component_id": component["id"],
+        "path": component["path"],
+        "line": evidence[0]["line"] if evidence else 1,
+        "framework": component["framework"],
+        "system": component.get("system"),
+        "change": change,
+        "impact": impact,
+        "severity": level,
+        "status": status,
+        "summary": summary,
+        "model_card_status": component["model_card_status"],
+        "citation_ids": citation_ids,
+        "owner": None,
+        "author": None,
+        "waiver": None,
+        "waiver_state": "none",
+    }
+
+
+def _evidence_key(component: dict) -> tuple[tuple[str, str], ...]:
+    return tuple((item["kind"], item["text"]) for item in component["evidence"])
+
+
+def _scan_ref(repo: Path, rev: str) -> dict:
+    raw = _git_bytes(repo, "archive", rev)
+    temp = Path(tempfile.mkdtemp(prefix="flyleaf-"))
+    try:
+        with tarfile.open(fileobj=io.BytesIO(raw), mode="r:") as archive:
+            kwargs = {"filter": "data"} if sys.version_info >= (3, 12) else {}
+            archive.extractall(temp, **kwargs)
+        return scan_path(temp)
+    finally:
+        shutil.rmtree(temp, ignore_errors=True)
+
+
+def _git_root(start: Path) -> Path:
+    return Path(_git(start, "rev-parse", "--show-toplevel"))
+
+
+def _rev_parse(repo: Path, ref: str) -> str:
+    return _git(repo, "rev-parse", "--verify", ref)
+
+
+def _git(repo: Path, *args: str) -> str:
+    return _run(repo, args, text=True).strip()
+
+
+def _git_bytes(repo: Path, *args: str) -> bytes:
+    return _run(repo, args, text=False)
+
+
+def _run(repo: Path, args: tuple[str, ...], text: bool):
+    try:
+        completed = subprocess.run(
+            ["git", "-C", str(repo), *args],
+            check=True,
+            capture_output=True,
+            text=text,
+        )
+    except FileNotFoundError as exc:
+        raise GitError("git is not installed.") from exc
+    except subprocess.CalledProcessError as exc:
+        message = exc.stderr or exc.stdout or "git failed"
+        if isinstance(message, bytes):
+            message = message.decode(errors="replace")
+        raise GitError(str(message).strip()) from exc
+    return completed.stdout