llm-sca-tooling 0.1.0__py3-none-any.whl

llm_sca_tooling/__init__.py

@@ -0,0 +1,5 @@
+"""LLM-SCA tooling package."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__", "schemas"]

llm_sca_tooling/blast_radius/__init__.py

@@ -0,0 +1,42 @@
+"""Phase 15 blast-radius service — cross-language and cross-repository impact analysis."""
+
+from __future__ import annotations
+
+from llm_sca_tooling.blast_radius.change_type import ChangeType, classify_change_type
+from llm_sca_tooling.blast_radius.models import (
+    ABIChangeType,
+    ABIImpactNote,
+    AmbiguousLinkRecord,
+    BlastRadiusConfig,
+    BlastRadiusReport,
+    CrossRepoImpactRecord,
+    GeneratedStubImpactNote,
+    GeneratedStubImpactType,
+    ImpactGroup,
+    ImpactRecord,
+    MatchMethod,
+)
+from llm_sca_tooling.blast_radius.service import BlastRadiusService
+from llm_sca_tooling.blast_radius.traversal_policy import (
+    TraversalPolicy,
+    default_policy_for,
+)
+
+__all__ = [
+    "ABIChangeType",
+    "ABIImpactNote",
+    "AmbiguousLinkRecord",
+    "BlastRadiusConfig",
+    "BlastRadiusReport",
+    "BlastRadiusService",
+    "ChangeType",
+    "CrossRepoImpactRecord",
+    "GeneratedStubImpactNote",
+    "GeneratedStubImpactType",
+    "ImpactGroup",
+    "ImpactRecord",
+    "MatchMethod",
+    "TraversalPolicy",
+    "classify_change_type",
+    "default_policy_for",
+]

llm_sca_tooling/blast_radius/abi_impact.py

@@ -0,0 +1,74 @@
+"""Phase 15 C/C++ ABI impact detection (with fallback when backend absent)."""
+
+from __future__ import annotations
+
+import logging
+
+from llm_sca_tooling.blast_radius.models import ABIChangeType, ABIImpactNote
+from llm_sca_tooling.patch_review.models import ChangedSymbolRecord
+
+logger = logging.getLogger(__name__)
+
+_CPP_EXTENSIONS = {".cpp", ".cc", ".cxx", ".c", ".h", ".hpp", ".hxx"}
+
+
+def _is_cpp_file(file_path: str) -> bool:
+    lower = file_path.lower()
+    return any(lower.endswith(ext) for ext in _CPP_EXTENSIONS)
+
+
+def build_abi_impact_notes(
+    changed_records: list[ChangedSymbolRecord],
+    *,
+    clangd_available: bool = False,
+) -> list[ABIImpactNote]:
+    """Produce ABIImpactNotes for C/C++ symbol changes.
+
+    When clangd/libclang backend is unavailable, always produce a note with
+    abi_change_type=UNKNOWN and an explanatory diagnostic — never silently skip.
+    """
+    notes: list[ABIImpactNote] = []
+
+    for rec in changed_records:
+        if not _is_cpp_file(rec.file_path):
+            continue
+
+        if not clangd_available:
+            notes.append(
+                ABIImpactNote(
+                    symbol_node_id=rec.graph_node_id or rec.symbol_path,
+                    symbol_path=rec.symbol_path,
+                    abi_change_type=ABIChangeType.UNKNOWN,
+                    diagnostics=[
+                        "libclang/clangd backend unavailable; ABI analysis skipped. "
+                        "Manual ABI review required for this C/C++ change."
+                    ],
+                )
+            )
+            logger.warning(
+                "ABI analysis unavailable for %s (clangd not present)", rec.file_path
+            )
+            continue
+
+        # When clangd is available, determine ABI change type from record metadata
+        from llm_sca_tooling.patch_review.models import ChangeKind  # noqa: PLC0415
+
+        if rec.change_kind == ChangeKind.MODIFIED_SIGNATURE:
+            abi_type = ABIChangeType.SIGNATURE_CHANGED
+        else:
+            abi_type = ABIChangeType.NO_ABI_IMPACT
+
+        notes.append(
+            ABIImpactNote(
+                symbol_node_id=rec.graph_node_id or rec.symbol_path,
+                symbol_path=rec.symbol_path,
+                abi_change_type=abi_type,
+                confidence=0.75,
+                diagnostics=[],
+            )
+        )
+
+    return notes
+
+
+__all__ = ["build_abi_impact_notes"]

llm_sca_tooling/blast_radius/ambiguous_links.py

@@ -0,0 +1,46 @@
+"""Phase 15 ambiguous-link bucket helpers."""
+
+from __future__ import annotations
+
+from llm_sca_tooling.blast_radius.models import AmbiguousLinkRecord, MatchMethod
+
+
+def make_unresolved_cross_repo_link(
+    source_node_id: str,
+    target_node_id: str,
+    edge_type: str,
+    confidence: float,
+    reason: str = "",
+) -> AmbiguousLinkRecord:
+    return AmbiguousLinkRecord(
+        source_node_id=source_node_id,
+        target_node_id=target_node_id,
+        edge_type=edge_type,
+        confidence=confidence,
+        match_method=MatchMethod.CROSS_REPO_UNRESOLVED,
+        reason_ambiguous=reason or "Cross-repo target unresolved.",
+        recommended_followup="Register target repo and re-index.",
+    )
+
+
+def make_candidate_link(
+    source_node_id: str,
+    target_node_id: str,
+    edge_type: str,
+    confidence: float,
+    analyser_threshold: float,
+) -> AmbiguousLinkRecord:
+    return AmbiguousLinkRecord(
+        source_node_id=source_node_id,
+        target_node_id=target_node_id,
+        edge_type=edge_type,
+        confidence=confidence,
+        match_method=MatchMethod.CANDIDATE_EDGE,
+        reason_ambiguous=(
+            f"Edge confidence {confidence:.2f} below analyser threshold {analyser_threshold:.2f}."
+        ),
+        recommended_followup="Run analyser-level pass to confirm or reject.",
+    )
+
+
+__all__ = ["make_candidate_link", "make_unresolved_cross_repo_link"]

llm_sca_tooling/blast_radius/change_type.py

@@ -0,0 +1,99 @@
+"""Phase 15 change-type classification."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from llm_sca_tooling.patch_review.models import ChangedSymbolRecord
+
+
+class ChangeType(StrEnum):
+    INTERNAL_IMPLEMENTATION = "internal_implementation"
+    PUBLIC_API_CHANGE = "public_api_change"
+    IDL_SCHEMA_CONTRACT_CHANGE = "idl_schema_contract_change"
+    SECURITY_SENSITIVE_CHANGE = "security_sensitive_change"
+    GENERATED_FILE_CHANGE = "generated_file_change"
+    MIXED = "mixed"
+    UNKNOWN = "unknown"
+
+
+_IDL_PATTERNS = (
+    ".proto",
+    ".thrift",
+    ".idl",
+    ".wsdl",
+    ".avsc",
+    ".avro",
+    "openapi",
+    "swagger",
+)
+
+_SECURITY_KEYWORDS = (
+    "auth",
+    "crypt",
+    "perm",
+    "secret",
+    "token",
+    "password",
+    "passwd",
+    "credential",
+    "cwe",
+    "sanitize",
+    "escape",
+    "jwt",
+    "oauth",
+    "acl",
+    "rbac",
+)
+
+
+def _is_idl_path(file_path: str) -> bool:
+    lower = file_path.lower()
+    return any(pat in lower for pat in _IDL_PATTERNS)
+
+
+def _is_security_sensitive(record: ChangedSymbolRecord) -> bool:
+    lower = record.file_path.lower() + " " + record.symbol_path.lower()
+    return any(kw in lower for kw in _SECURITY_KEYWORDS)
+
+
+def classify_change_type(
+    records: list[ChangedSymbolRecord],
+    *,
+    security_node_ids: set[str] | None = None,
+) -> tuple[ChangeType, list[ChangeType]]:
+    """Classify the change type from a list of ChangedSymbolRecord.
+
+    Returns a tuple of (primary_type, applicable_types).
+    If multiple change types apply, primary_type is MIXED.
+    """
+    if not records:
+        return ChangeType.UNKNOWN, []
+
+    applicable: set[ChangeType] = set()
+
+    for rec in records:
+        if rec.is_generated:
+            applicable.add(ChangeType.GENERATED_FILE_CHANGE)
+        if rec.is_public_api:
+            applicable.add(ChangeType.PUBLIC_API_CHANGE)
+        if _is_idl_path(rec.file_path):
+            applicable.add(ChangeType.IDL_SCHEMA_CONTRACT_CHANGE)
+        if _is_security_sensitive(rec) or (
+            security_node_ids
+            and rec.graph_node_id
+            and rec.graph_node_id in security_node_ids
+        ):
+            applicable.add(ChangeType.SECURITY_SENSITIVE_CHANGE)
+
+    if not applicable:
+        return ChangeType.INTERNAL_IMPLEMENTATION, [ChangeType.INTERNAL_IMPLEMENTATION]
+
+    if len(applicable) > 1:
+        return ChangeType.MIXED, sorted(applicable)
+
+    only = next(iter(applicable))
+    return only, [only]
+
+
+__all__ = ["ChangeType", "classify_change_type"]

llm_sca_tooling/blast_radius/cross_repo.py

@@ -0,0 +1,117 @@
+"""Phase 15 cross-repository traversal with is_partial fallback."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from llm_sca_tooling.blast_radius.models import (
+    AmbiguousLinkRecord,
+    CrossRepoImpactRecord,
+    MatchMethod,
+)
+from llm_sca_tooling.schemas.enums import GraphEdgeType
+
+if TYPE_CHECKING:
+    from llm_sca_tooling.storage.graph_store import GraphStore
+
+logger = logging.getLogger(__name__)
+
+_CROSS_REPO_EDGE_TYPES = {
+    GraphEdgeType.CONSUMES.value,
+    GraphEdgeType.EXPOSES.value,
+    GraphEdgeType.FFI.value,
+}
+
+
+def traverse_cross_repo(
+    changed_node_ids: list[str],
+    graph_store: GraphStore,
+    *,
+    registered_repo_ids: list[str] | None = None,
+    max_hops: int = 2,
+    analyser_threshold: float = 0.75,
+) -> tuple[list[CrossRepoImpactRecord], list[AmbiguousLinkRecord]]:
+    """Traverse cross-repo graph overlay to find consuming repos.
+
+    When the overlay is unavailable or incomplete, returns CrossRepoImpactRecord
+    with is_partial=True — never silently skips.
+
+    Returns (cross_repo_records, ambiguous_link_records).
+    """
+    if not registered_repo_ids:
+        logger.info("No registered repos provided; cross-repo traversal skipped.")
+        ambiguous = [
+            AmbiguousLinkRecord(
+                source_node_id=nid,
+                target_node_id="<unknown>",
+                edge_type=GraphEdgeType.CONSUMES.value,
+                confidence=0.0,
+                match_method=MatchMethod.CROSS_REPO_UNRESOLVED,
+                reason_ambiguous="No registered repos available for cross-repo traversal.",
+                recommended_followup="Register consuming repos and re-run blast radius.",
+            )
+            for nid in changed_node_ids
+        ]
+        return [], ambiguous
+
+    edge_types = [GraphEdgeType(et) for et in _CROSS_REPO_EDGE_TYPES]
+    cross_records: list[CrossRepoImpactRecord] = []
+    cross_ambiguous: list[AmbiguousLinkRecord] = []
+
+    try:
+        slice_ = graph_store.fetch_ego_graph(
+            changed_node_ids,
+            depth=max_hops,
+            edge_types=edge_types,
+        )
+
+        # Group consuming nodes by repo_id
+        repo_consumers: dict[str, list[str]] = {}
+        for node in slice_.nodes:
+            if node.node_id in set(changed_node_ids):
+                continue
+            repo_id = node.repo.repo_id
+            if repo_id not in registered_repo_ids:
+                cross_ambiguous.append(
+                    AmbiguousLinkRecord(
+                        source_node_id=changed_node_ids[0] if changed_node_ids else "?",
+                        target_node_id=node.node_id,
+                        edge_type=GraphEdgeType.CONSUMES.value,
+                        confidence=0.0,
+                        match_method=MatchMethod.CROSS_REPO_UNRESOLVED,
+                        reason_ambiguous=f"Repo {repo_id!r} not in registered repo list.",
+                        recommended_followup="Register this repo to enable full cross-repo impact.",
+                    )
+                )
+                continue
+            repo_consumers.setdefault(repo_id, []).append(node.node_id)
+
+        for repo_id, consumers in repo_consumers.items():
+            cross_records.append(
+                CrossRepoImpactRecord(
+                    repo_id=repo_id,
+                    consuming_node_ids=consumers,
+                    hop_distance=1,
+                    is_partial=False,
+                    confidence=analyser_threshold,
+                )
+            )
+
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Cross-repo traversal failed: %s", exc)
+        cross_records.append(
+            CrossRepoImpactRecord(
+                repo_id="<unknown>",
+                consuming_node_ids=[],
+                hop_distance=0,
+                is_partial=True,
+                partial_reason=f"Graph overlay traversal failed: {exc}",
+                confidence=0.0,
+            )
+        )
+
+    return cross_records, cross_ambiguous
+
+
+__all__ = ["traverse_cross_repo"]

llm_sca_tooling/blast_radius/doc_spec_impact.py

@@ -0,0 +1,70 @@
+"""Phase 15 linked docs/specs impact — flag stale design clauses."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from llm_sca_tooling.schemas.enums import GraphEdgeType, GraphNodeType
+
+if TYPE_CHECKING:
+    from llm_sca_tooling.storage.graph_store import GraphStore
+
+logger = logging.getLogger(__name__)
+
+_DOC_NODE_TYPES = {
+    GraphNodeType.DOCUMENT,
+    GraphNodeType.DESIGN_CLAUSE,
+    GraphNodeType.INTENT_NODE,
+}
+
+_DOC_EDGE_TYPES = [
+    GraphEdgeType.SATISFIES,
+    GraphEdgeType.VIOLATES,
+    GraphEdgeType.DOCUMENTS,
+    GraphEdgeType.DECOMPOSES_TO,
+]
+
+
+def collect_linked_docs(
+    changed_node_ids: list[str],
+    graph_store: GraphStore,
+    *,
+    max_hops: int = 3,
+) -> tuple[list[dict[str, object]], str]:
+    """Collect design_clause / intent_node / document nodes linked to changed symbols.
+
+    Returns (doc_node_dicts, summary_string).
+    """
+    docs: list[dict[str, object]] = []
+
+    try:
+        slice_ = graph_store.fetch_ego_graph(
+            changed_node_ids,
+            depth=max_hops,
+            edge_types=_DOC_EDGE_TYPES,
+        )
+        for node in slice_.nodes:
+            if node.node_id in set(changed_node_ids):
+                continue
+            if node.node_type in _DOC_NODE_TYPES:
+                docs.append(
+                    {
+                        "node_id": node.node_id,
+                        "node_type": node.node_type.value,
+                        "label": node.label,
+                        "potentially_stale": True,
+                    }
+                )
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Linked docs collection failed: %s", exc)
+
+    summary = (
+        f"{len(docs)} linked doc/spec node(s) may be stale after this change."
+        if docs
+        else "No linked docs/specs affected."
+    )
+    return docs, summary
+
+
+__all__ = ["collect_linked_docs"]

llm_sca_tooling/blast_radius/generated_stub.py

@@ -0,0 +1,60 @@
+"""Phase 15 generated-stub impact detection and reporting."""
+
+from __future__ import annotations
+
+import logging
+
+from llm_sca_tooling.blast_radius.models import (
+    GeneratedStubImpactNote,
+    GeneratedStubImpactType,
+)
+from llm_sca_tooling.patch_review.models import ChangedSymbolRecord
+
+logger = logging.getLogger(__name__)
+
+
+def build_generated_stub_notes(
+    diff_id: str,
+    changed_records: list[ChangedSymbolRecord],
+    *,
+    generated_file_allowlist: set[str] | None = None,
+) -> list[GeneratedStubImpactNote]:
+    """Produce GeneratedStubImpactNotes for generated files touched by this diff.
+
+    Rules:
+    - Every generated file produces a note.
+    - Direct edits to generated files set manual_edit_policy_flag=True unless in allowlist.
+    """
+    allowlist = generated_file_allowlist or set()
+    notes: list[GeneratedStubImpactNote] = []
+
+    for rec in changed_records:
+        if not rec.is_generated:
+            continue
+        is_manual_violation = rec.file_path not in allowlist
+        notes.append(
+            GeneratedStubImpactNote(
+                diff_id=diff_id,
+                generated_file_path=rec.file_path,
+                generator_source="",
+                source_contract_node_id=rec.graph_node_id,
+                impact_type=GeneratedStubImpactType.GENERATED_FILE_DIRECTLY_CHANGED,
+                manual_edit_policy_flag=is_manual_violation,
+                recommended_action=(
+                    "Check policy allowlist before merging."
+                    if is_manual_violation
+                    else "Verify regeneration is idempotent."
+                ),
+            )
+        )
+        if is_manual_violation:
+            logger.warning(
+                "Manual edit detected on generated file %s (diff=%s)",
+                rec.file_path,
+                diff_id,
+            )
+
+    return notes
+
+
+__all__ = ["build_generated_stub_notes"]