flyleaf 0.5.0__py3-none-any.whl

flyleaf/report.py

@@ -0,0 +1,393 @@
+# Copyright 2026 Krishna Dahale
+# SPDX-License-Identifier: Apache-2.0
+"""Render inventories, briefs, and citation entries."""
+
+import json
+
+from flyleaf import DISCLAIMER, __version__, attribution
+from flyleaf.citations import CHANGELOG, CITATIONS, PACK_VERSION, citation_payload
+from flyleaf.severity import SEVERITY_NOTE
+
+FORMATS = ("json", "markdown", "sarif")
+HOMEPAGE = "https://github.com/krishyaid-coder/flyleaf"
+_SARIF_LEVEL = {"high": "error", "medium": "warning", "low": "note"}
+
+
+def render(document: dict, output_format: str) -> str:
+    if output_format == "sarif":
+        if document.get("kind") != "brief":
+            raise ValueError("sarif is available for brief only")
+        return json.dumps(_sarif(document), indent=2) + "\n"
+    if output_format == "json":
+        return json.dumps(document, indent=2) + "\n"
+    if output_format != "markdown":
+        raise ValueError(f"unknown format: {output_format}")
+    if document.get("kind") == "brief":
+        return _brief_markdown(document)
+    return _inventory_markdown(document)
+
+
+def render_citations(citation_id: str | None, changelog: bool, output_format: str) -> str:
+    if changelog:
+        document = {"citation_pack": {"version": PACK_VERSION}, "changelog": list(CHANGELOG)}
+    elif citation_id is None:
+        document = {
+            "citation_pack": {"version": PACK_VERSION},
+            "citations": {item_id: citation_payload(item_id) for item_id in sorted(CITATIONS)},
+        }
+    else:
+        if citation_id not in CITATIONS:
+            raise KeyError(citation_id)
+        document = {
+            "citation_pack": {"version": PACK_VERSION},
+            "citations": {citation_id: citation_payload(citation_id)},
+        }
+    if output_format == "json":
+        return json.dumps(document, indent=2) + "\n"
+    if output_format != "markdown":
+        raise ValueError(f"unknown format: {output_format}")
+    return _citations_markdown(document, changelog)
+
+
+def _inventory_markdown(inventory: dict) -> str:
+    components = inventory["components"]
+    pack = inventory["citation_pack"]["version"]
+    lines = [
+        "# flyleaf inventory",
+        "",
+        DISCLAIMER,
+        "",
+        f"Citation pack: {pack}",
+        "",
+        f"Components: {len(components)}",
+        "",
+    ]
+    if not components:
+        lines.append("No AI libraries detected.")
+        lines.append("")
+    lines.extend(_systems_lines(inventory))
+    for component in components:
+        lines.extend(_component_lines(component, inventory["citations"], pack))
+    warnings = inventory["warnings"]
+    if warnings:
+        lines.append("## Warnings")
+        lines.append("")
+        for warning in warnings:
+            lines.append(f"- `{warning['path']}`: {warning['message']}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _systems_lines(inventory: dict) -> list[str]:
+    systems = inventory.get("systems") or []
+    components = inventory["components"]
+    if not systems:
+        return []
+    unassigned = [item["id"] for item in components if not item["system"]]
+    lines = ["## Systems", "", "Declared in `.flyleaf/systems.toml`. flyleaf does not infer them.", ""]
+    for system in systems:
+        card = system["model_card_path"] or system["model_card_status"]
+        lines.append(f"### {system['name']}")
+        lines.append("")
+        lines.append(f"- Owner: {system['owner'] or 'not stated'}")
+        lines.append(f"- Model card: {card}")
+        lines.append(f"- Frameworks: {', '.join(system['frameworks']) or 'none detected'}")
+        lines.append(f"- Components: {len(system['component_ids'])}")
+        for component_id in system["component_ids"]:
+            lines.append(f"  - `{component_id}`")
+        lines.append("")
+    lines.append(f"Components in no declared system: {len(unassigned)}")
+    lines.append("")
+    for component_id in unassigned:
+        lines.append(f"- `{component_id}`")
+    if unassigned:
+        lines.append("")
+    return lines
+
+
+def _component_lines(component: dict, citations: dict, pack: str) -> list[str]:
+    card = component["model_card_status"]
+    if component["model_card_path"]:
+        card = f"{card} (`{component['model_card_path']}`)"
+    lines = [
+        f"## {component['path']} ({component['framework']})",
+        "",
+        f"- Category: {component['category']}",
+        f"- Role hint: {component['role_hint']}",
+        f"- System: {component['system'] or 'none declared'}",
+        f"- Model card: {card}",
+        "- Evidence:",
+    ]
+    for item in component["evidence"]:
+        lines.append(f"  - line {item['line']}: `{item['text']}` ({item['kind']})")
+    lines.append("- Areas to review:")
+    for hint in component["review_hints"]:
+        lines.append(f"  - {hint['text']}")
+        lines.extend(_citation_lines(hint["citation_ids"], citations, pack))
+    lines.append("- Documentation:")
+    lines.append(f"  - status {component['model_card_status']}")
+    lines.extend(_citation_lines(component["documentation_citation_ids"], citations, pack))
+    lines.append("")
+    return lines
+
+
+def _brief_markdown(brief: dict) -> str:
+    findings = brief["findings"]
+    waived = brief["waived"]
+    pack = brief["citation_pack"]["version"]
+    head = brief["head"]
+    head_line = head["ref"]
+    if head.get("dirty"):
+        head_line = f"{head_line} (uncommitted changes)"
+    base = brief["base"]
+    base_line = base["ref"] or "HEAD"
+    if base.get("recorded_at"):
+        base_line = f"{base_line} (recorded {base['recorded_at']})"
+    elif base.get("rev"):
+        base_line = f"{base_line} ({base['rev']})"
+
+    lines = [
+        "# flyleaf brief",
+        "",
+        DISCLAIMER,
+        "",
+        SEVERITY_NOTE,
+        "",
+        f"Citation pack: {pack}",
+        "",
+        f"Base: {base_line}",
+        f"Head: {head_line}",
+        "",
+        f"Findings: {len(findings)} ({_severity_tally(findings)})",
+        f"Waived: {len(waived)}",
+        "",
+    ]
+    if not findings:
+        lines.append("No compliance-relevant change.")
+        lines.append("")
+    lines.extend(_reviewer_lines(findings))
+    for finding in findings:
+        lines.extend(_finding_lines(finding, brief["citations"], pack))
+    if waived:
+        lines.append("## Waived")
+        lines.append("")
+        for finding in waived:
+            waiver = finding["waiver"]
+            lines.append(
+                f"- {_subject(finding)}, {finding['change']}, severity {finding['severity']}"
+            )
+            lines.append(
+                f"  waived by {waiver['approved_by']} until {waiver['expires']} "
+                f"({waiver['days_left']} day(s) left): {waiver['reason']}"
+            )
+        lines.append("")
+    if brief["warnings"]:
+        lines.append("## Warnings")
+        lines.append("")
+        for warning in brief["warnings"]:
+            lines.append(f"- {warning}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def reviewer_of(finding: dict) -> str:
+    """Who should look at this finding.
+
+    The person who made the change is asked first, because they have the
+    context. The declared owner stands behind it either way.
+    """
+    author = finding.get("author")
+    if author and not author["uncommitted"] and not author["is_bot"]:
+        return author["email"] or author["name"] or "unassigned"
+    owner = finding.get("owner")
+    if owner:
+        return owner
+    if author:
+        return attribution.label(author)
+    return "unassigned"
+
+
+def _reviewer_lines(findings: list[dict]) -> list[str]:
+    if not findings:
+        return []
+    buckets: dict[str, list[dict]] = {}
+    for finding in findings:
+        buckets.setdefault(reviewer_of(finding), []).append(finding)
+    lines = ["## Who should look at this", ""]
+    for reviewer, owned in sorted(buckets.items(), key=lambda item: (-len(item[1]), item[0])):
+        subjects = ", ".join(dict.fromkeys(_subject(item) for item in owned))
+        lines.append(f"- {reviewer}: {len(owned)} ({_severity_tally(owned)}). {subjects}.")
+    lines.append("")
+    lines.append(
+        "Names come from the declared system owner and from git blame on the line "
+        "that changed. Blame names a line, not a fault."
+    )
+    lines.append("")
+    return lines
+
+
+def _subject(finding: dict) -> str:
+    if finding.get("kind") == "system":
+        return f"system {finding['system']} ({finding['framework']})"
+    return f"{finding['path']} ({finding['framework']})"
+
+
+def _finding_lines(finding: dict, citations: dict, pack: str) -> list[str]:
+    lines = [
+        f"## [{finding['severity']}] {_subject(finding)}",
+        "",
+        f"- Change: {finding['change']}",
+        f"- Impact: {finding['impact']}",
+        f"- Status: {finding['status']}",
+        f"- Model card: {finding['model_card_status']}",
+        f"- Owner: {finding.get('owner') or 'none declared'}",
+        f"- Last changed by: {attribution.label(finding.get('author'))}",
+        f"- {finding['summary']}",
+    ]
+    if finding.get("waiver_state") == "expired":
+        lines.append("- Waiver: expired")
+    members = finding.get("members")
+    if members:
+        lines.append(f"- Components ({len(members)}):")
+        for member in members:
+            lines.append(
+                f"  - `{member['path']}` line {member['line']} ({member['framework']}), "
+                f"{member['change']}, severity {member['severity']}, "
+                f"last changed by {attribution.label(member.get('author'))}"
+            )
+    lines.append("- Read:")
+    lines.extend(_citation_lines(finding["citation_ids"], citations, pack))
+    lines.append("")
+    return lines
+
+
+def _severity_tally(findings: list[dict]) -> str:
+    counts = {"high": 0, "medium": 0, "low": 0}
+    for finding in findings:
+        counts[finding["severity"]] = counts.get(finding["severity"], 0) + 1
+    return ", ".join(f"{level} {counts[level]}" for level in ("high", "medium", "low"))
+
+
+def _sarif(brief: dict) -> dict:
+    rules: dict[str, dict] = {}
+    results: list[dict] = []
+    for finding in brief["findings"]:
+        rule_id = f"flyleaf/{finding['change']}"
+        rules.setdefault(
+            rule_id,
+            {
+                "id": rule_id,
+                "name": finding["change"],
+                "shortDescription": {"text": _rule_text(finding["change"])},
+                "fullDescription": {"text": SEVERITY_NOTE},
+                "helpUri": HOMEPAGE,
+                "properties": {"impact": finding["impact"]},
+            },
+        )
+        citations = ", ".join(
+            brief["citations"][citation_id]["pinpoint"] for citation_id in finding["citation_ids"]
+        )
+        results.append(
+            {
+                "ruleId": rule_id,
+                "level": _SARIF_LEVEL.get(finding["severity"], "warning"),
+                "message": {"text": f"{finding['summary']} Read: {citations}."},
+                "locations": _sarif_locations(finding),
+                "properties": {
+                    "severity": finding["severity"],
+                    "impact": finding["impact"],
+                    "status": finding["status"],
+                    "component": finding["component_id"],
+                    "system": finding.get("system"),
+                    "owner": finding.get("owner"),
+                    "author": attribution.label(finding.get("author")),
+                },
+            }
+        )
+    return {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "flyleaf",
+                        "version": __version__,
+                        "informationUri": HOMEPAGE,
+                        "rules": list(rules.values()),
+                    }
+                },
+                "results": results,
+            }
+        ],
+    }
+
+
+def _sarif_locations(finding: dict) -> list[dict]:
+    """The lead location comes first, because GitHub annotates the first one."""
+    places = [(finding["path"], finding["line"])]
+    for member in finding.get("members") or []:
+        place = (member["path"], member["line"])
+        if place not in places:
+            places.append(place)
+    return [
+        {
+            "physicalLocation": {
+                "artifactLocation": {"uri": path},
+                "region": {"startLine": max(1, line)},
+            }
+        }
+        for path, line in places
+    ]
+
+
+def _rule_text(change: str) -> str:
+    return {
+        "added": "A new AI component appeared.",
+        "removed": "A detected AI component is gone.",
+        "evidence_changed": "The detected AI code changed.",
+        "card_stale": "The AI code changed and the model card did not.",
+        "card_removed": "A model card was removed.",
+        "card_added": "A model card appeared.",
+        "card_changed": "A model card changed.",
+        "evidence_and_card_changed": "The AI code and the model card both changed.",
+    }.get(change, change)
+
+
+def _citations_markdown(document: dict, changelog: bool) -> str:
+    pack = document["citation_pack"]["version"]
+    lines = ["# flyleaf citation pack", "", f"Version: {pack}", ""]
+    if changelog:
+        for entry in document["changelog"]:
+            lines.append(f"## {entry['version']}")
+            lines.append("")
+            lines.append(entry["summary"])
+            lines.append("")
+        return "\n".join(lines)
+    for citation in document["citations"].values():
+        lines.extend(
+            [
+                f"## {citation['id']}",
+                "",
+                f"{citation['pinpoint']}",
+                "",
+                f"{citation['instrument']} ({citation['celex']}), status {citation['status']}.",
+                "",
+                f"> {citation['quote']}",
+                "",
+                citation["note"],
+                "",
+                citation["source_url"],
+                "",
+            ]
+        )
+    return "\n".join(lines)
+
+
+def _citation_lines(citation_ids: list[str], citations: dict, pack: str) -> list[str]:
+    lines: list[str] = []
+    for citation_id in citation_ids:
+        citation = citations[citation_id]
+        lines.append(f"    - {citation['pinpoint']} ({citation['celex']}, pack {pack})")
+        lines.append(f"      {citation['source_url']}")
+    return lines

flyleaf/rules.py

@@ -0,0 +1,258 @@
+# Copyright 2026 Krishna Dahale
+# SPDX-License-Identifier: Apache-2.0
+"""Detection rules.
+
+A rule matches a library, not a legal outcome. Role hints and review hints
+are prompts for a person. They are not a risk tier.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ReviewHint:
+    id: str
+    text: str
+    citation_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Rule:
+    framework: str
+    category: str
+    role_hint: str
+    packages: frozenset[str]
+    import_roots: frozenset[str]
+    review_hints: tuple[ReviewHint, ...]
+
+
+_API_HINTS = (
+    ReviewHint(
+        id="role",
+        text=(
+            "This looks like a client of a hosted model. "
+            "Confirm whether you provide the model or deploy someone else's. "
+            "Those roles carry different duties."
+        ),
+        citation_ids=("art-3-provider", "art-3-deployer", "art-53-gpai"),
+    ),
+    ReviewHint(
+        id="transparency",
+        text=(
+            "If people receive generated text, audio, or images, "
+            "Article 50 transparency is an area to review."
+        ),
+        citation_ids=("art-50-interaction",),
+    ),
+)
+
+_ORCHESTRATION_HINTS = (
+    ReviewHint(
+        id="role",
+        text=(
+            "Orchestration code composes model calls. "
+            "Review the system those calls sit inside. "
+            "The import does not identify the use case."
+        ),
+        citation_ids=("art-3-provider", "art-3-deployer"),
+    ),
+)
+
+_ML_HINTS = (
+    ReviewHint(
+        id="use_case",
+        text=(
+            "A machine-learning library does not say whether a use case is high-risk. "
+            "Annex III depends on purpose. Fill that in yourself."
+        ),
+        citation_ids=("art-6-annex-iii",),
+    ),
+)
+
+
+def _rule(
+    framework: str,
+    category: str,
+    role_hint: str,
+    packages: tuple[str, ...],
+    import_roots: tuple[str, ...],
+    review_hints: tuple[ReviewHint, ...],
+) -> Rule:
+    return Rule(
+        framework=framework,
+        category=category,
+        role_hint=role_hint,
+        packages=frozenset(packages),
+        import_roots=frozenset(import_roots),
+        review_hints=review_hints,
+    )
+
+
+RULES: tuple[Rule, ...] = (
+    _rule(
+        "openai",
+        "llm_api",
+        "api_client",
+        ("openai",),
+        ("openai",),
+        _API_HINTS,
+    ),
+    _rule(
+        "anthropic",
+        "llm_api",
+        "api_client",
+        ("anthropic", "@anthropic-ai/sdk"),
+        ("anthropic",),
+        _API_HINTS,
+    ),
+    _rule(
+        "google-genai",
+        "llm_api",
+        "api_client",
+        (
+            "google-generativeai",
+            "google-genai",
+            "@google/generative-ai",
+            "@google/genai",
+        ),
+        ("google.generativeai", "google.genai"),
+        _API_HINTS,
+    ),
+    _rule(
+        "mistralai",
+        "llm_api",
+        "api_client",
+        ("mistralai", "@mistralai/mistralai"),
+        ("mistralai",),
+        _API_HINTS,
+    ),
+    _rule(
+        "cohere",
+        "llm_api",
+        "api_client",
+        ("cohere", "cohere-ai"),
+        ("cohere",),
+        _API_HINTS,
+    ),
+    _rule(
+        "langchain",
+        "orchestration",
+        "orchestration",
+        (
+            "langchain",
+            "langchain-core",
+            "langchain-openai",
+            "langchain-community",
+            "langchain-anthropic",
+            "langchain-google-genai",
+            "@langchain/core",
+            "@langchain/openai",
+            "@langchain/community",
+            "@langchain/anthropic",
+            "@langchain/google-genai",
+        ),
+        (
+            "langchain",
+            "langchain_core",
+            "langchain_openai",
+            "langchain_community",
+            "langchain_anthropic",
+            "langchain_google_genai",
+        ),
+        _ORCHESTRATION_HINTS,
+    ),
+    _rule(
+        "llama-index",
+        "orchestration",
+        "orchestration",
+        ("llama-index", "llama-index-core", "llamaindex"),
+        ("llama_index",),
+        _ORCHESTRATION_HINTS,
+    ),
+    _rule(
+        "langgraph",
+        "orchestration",
+        "orchestration",
+        ("langgraph", "@langchain/langgraph"),
+        ("langgraph",),
+        _ORCHESTRATION_HINTS,
+    ),
+    _rule(
+        "torch",
+        "ml_framework",
+        "local_ml",
+        ("torch", "torchvision", "torchaudio"),
+        ("torch", "torchvision", "torchaudio"),
+        _ML_HINTS,
+    ),
+    _rule(
+        "tensorflow",
+        "ml_framework",
+        "local_ml",
+        ("tensorflow", "tensorflow-cpu", "tensorflow-macos"),
+        ("tensorflow",),
+        _ML_HINTS,
+    ),
+    _rule(
+        "scikit-learn",
+        "ml_framework",
+        "local_ml",
+        ("scikit-learn", "sklearn"),
+        ("sklearn",),
+        _ML_HINTS,
+    ),
+    _rule(
+        "transformers",
+        "ml_framework",
+        "local_ml",
+        ("transformers",),
+        ("transformers",),
+        _ML_HINTS,
+    ),
+    _rule(
+        "xgboost",
+        "ml_framework",
+        "local_ml",
+        ("xgboost",),
+        ("xgboost",),
+        _ML_HINTS,
+    ),
+)
+
+
+def match_import(module: str) -> Rule | None:
+    """Return the rule with the longest import root that covers `module`."""
+    best: Rule | None = None
+    best_len = -1
+    for rule in RULES:
+        for root in rule.import_roots:
+            covers = module == root or module.startswith(root + ".")
+            if covers and len(root) > best_len:
+                best = rule
+                best_len = len(root)
+    return best
+
+
+_PACKAGES: dict[str, Rule] = {}
+for _rule_item in RULES:
+    for _package in _rule_item.packages:
+        if _package in _PACKAGES:
+            raise RuntimeError(f"package {_package} is claimed by two rules")
+        _PACKAGES[_package] = _rule_item
+
+
+def match_package(name: str) -> Rule | None:
+    return _PACKAGES.get(name)
+
+
+def _validate_citation_ids() -> None:
+    from flyleaf.citations import CITATIONS
+
+    for rule in RULES:
+        for hint in rule.review_hints:
+            missing = [citation_id for citation_id in hint.citation_ids if citation_id not in CITATIONS]
+            if missing:
+                raise RuntimeError(f"{rule.framework} hint {hint.id} cites unknown ids: {missing}")
+
+
+_validate_citation_ids()