sourcecode 2.2.0__py3-none-any.whl → 2.4.0__py3-none-any.whl

sourcecode/graph_evidence.py

@@ -0,0 +1,352 @@
+"""Graph Evidence Provider — turns the structural module graph into reusable
+topological evidence (ADR-0003, migration step 2).
+
+Responsibility boundary (deliberately narrow):
+
+    ModuleGraph  ->  [ this module ]  ->  topological metrics  ->  GraphEvidence
+
+This component knows GRAPHS, not ARCHETYPES. It does not classify, does not
+emit prose verdicts, and never imports the archetype scorer. It computes a
+small, robust set of topological metrics and packages each as a language- and
+domain-agnostic ``GraphEvidence`` object. The archetype scorer consumes those
+evidence objects; it never traverses the graph itself.
+
+The metrics are chosen so that architectural style can emerge from STRUCTURE
+rather than from directory names:
+
+  * scc_mass                  — fraction of nodes that sit inside a NON-TRIVIAL
+                                strongly-connected component (an import cycle).
+                                Range [0,1]. 0 for a clean DAG (layered/
+                                hexagonal); high for a woven engine core.
+                                Cost O(V+E) (iterative Tarjan).
+  * cyclic_density            — fraction of edges that live INSIDE a non-trivial
+                                SCC (true back-edges). Range [0,1]. Low for
+                                layered; high for engine. Cost O(V+E).
+  * hub_concentration         — share of all edges pointing at the single
+                                highest fan-in node. Range [0,1]. High for
+                                engine/microkernel cores. Cost O(V+E).
+  * module_centralization     — Freeman centralization of the in-degree
+                                distribution. Range [0,1]. ~1 for a star
+                                (microkernel), ~0 for a uniform mesh. Cost O(V).
+  * downward_edge_ratio       — fraction of edges flowing from a LESS stable to
+                                a MORE stable node (Martin instability
+                                I = out/(in+out)). Range [0,1]. High for
+                                layered/hexagonal directed flow. Cost O(V+E).
+  * dependency_inversion_ratio— fraction of edges whose TARGET sits in the most
+                                stable quartile (a stable, depended-upon core).
+                                Range [0,1]. High for hexagonal/clean. O(V+E).
+  * fan_in_gini               — Gini inequality of the in-degree distribution.
+                                Range [0,1]. High when a few modules absorb most
+                                dependencies (engine). Cost O(V log V).
+
+All metrics are name-free: they are functions of the directed topology only.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable, Optional
+
+# Structural edge kinds that represent a real dependency between modules.
+_STRUCTURAL_EDGE_KINDS = frozenset({"imports", "calls"})
+
+# Graph-size thresholds for how much a metric can be trusted / how much mass it
+# is allowed to contribute. A three-node toy graph must not speak with the same
+# authority as a sixty-module one.
+_MIN_NODES_FOR_METRICS = 4
+_MIN_EDGES_FOR_METRICS = 3
+_HIGH_CONF_NODES = 12
+_MASS_SATURATION_NODES = 10.0
+
+
+@dataclass(frozen=True)
+class GraphEvidence:
+    """One topological fact, ready to be consumed by any scorer.
+
+    Archetype-agnostic: it says *what the graph looks like*, never *what the
+    system is*. ``value`` is the raw metric in [0,1]; the scorer decides which
+    archetype (if any) that value supports and with what weight."""
+
+    provider: str          # always "module_graph"
+    kind: str              # metric name, e.g. "scc_mass"
+    value: float           # raw metric, 0..1
+    mass: float            # 0..1 — topological coverage (graph size proxy)
+    confidence: str        # low | medium | high — from graph size
+    detail: str            # human-readable one-liner
+
+    def to_dict(self) -> dict:
+        return {
+            "provider": self.provider,
+            "kind": self.kind,
+            "value": round(self.value, 4),
+            "mass": round(self.mass, 4),
+            "confidence": self.confidence,
+            "detail": self.detail,
+        }
+
+
+@dataclass
+class GraphEvidenceResult:
+    """Metrics + evidence produced from a single module graph."""
+
+    node_count: int
+    edge_count: int
+    metrics: dict[str, float] = field(default_factory=dict)
+    evidence: list[GraphEvidence] = field(default_factory=list)
+    available: bool = False       # False when the graph is too small to trust
+    confidence: str = "low"       # overall provider confidence
+
+    def metric(self, kind: str, default: float = 0.0) -> float:
+        return self.metrics.get(kind, default)
+
+    def to_dict(self) -> dict:
+        return {
+            "node_count": self.node_count,
+            "edge_count": self.edge_count,
+            "available": self.available,
+            "confidence": self.confidence,
+            "metrics": {k: round(v, 4) for k, v in self.metrics.items()},
+            "evidence": [e.to_dict() for e in self.evidence],
+        }
+
+
+class GraphEvidenceProvider:
+    """Transforms a module graph (nodes + directed edges) into GraphEvidence.
+
+    Stateless. Accepts anything exposing ``nodes`` and ``edges`` (a
+    ``schema.ModuleGraph`` does), so tests can hand it synthetic graphs without
+    building a repository."""
+
+    def analyze(
+        self,
+        graph: object,
+        *,
+        edge_kinds: Optional[Iterable[str]] = None,
+    ) -> GraphEvidenceResult:
+        nodes, adjacency = self._project(graph, edge_kinds)
+        n = len(nodes)
+        edges = [(u, v) for u, outs in adjacency.items() for v in outs]
+        e = len(edges)
+
+        result = GraphEvidenceResult(node_count=n, edge_count=e)
+        if n < _MIN_NODES_FOR_METRICS or e < _MIN_EDGES_FOR_METRICS:
+            # Too small to say anything structural. Report nothing rather than
+            # asserting metrics on noise.
+            return result
+
+        result.available = True
+        result.confidence = "high" if n >= _HIGH_CONF_NODES else "medium"
+        topo_mass = min(1.0, n / _MASS_SATURATION_NODES)
+
+        in_deg, out_deg = self._degrees(nodes, edges)
+        scc_of, scc_sizes = self._tarjan_scc(nodes, adjacency)
+        instability = self._instability(nodes, in_deg, out_deg)
+
+        m: dict[str, float] = {}
+        # Only NON-TRIVIAL SCCs (size > 1) count: a pure DAG has none, a woven
+        # engine core has many. A single-node "component" is not a cycle.
+        cyclic_nodes = sum(sz for sz in scc_sizes.values() if sz > 1)
+        m["scc_mass"] = (cyclic_nodes / n) if n else 0.0
+        m["cyclic_density"] = self._cyclic_density(edges, scc_of, scc_sizes, e)
+        m["hub_concentration"] = (max(in_deg.values(), default=0) / e) if e else 0.0
+        m["module_centralization"] = self._centralization(in_deg, n)
+        m["downward_edge_ratio"] = self._downward_ratio(edges, instability)
+        m["dependency_inversion_ratio"] = self._inversion_ratio(edges, instability)
+        m["fan_in_gini"] = self._gini([in_deg[x] for x in nodes])
+        result.metrics = m
+
+        # One evidence object per metric.
+        details = {
+            "scc_mass": f"{m['scc_mass']:.0%} of modules sit inside an import cycle",
+            "cyclic_density": f"{m['cyclic_density']:.0%} of edges are back-edges inside a cycle",
+            "hub_concentration": f"top module absorbs {m['hub_concentration']:.0%} of all dependencies",
+            "module_centralization": f"in-degree centralization {m['module_centralization']:.2f} (1=star, 0=mesh)",
+            "downward_edge_ratio": f"{m['downward_edge_ratio']:.0%} of edges flow toward more-stable modules",
+            "dependency_inversion_ratio": f"{m['dependency_inversion_ratio']:.0%} of edges point into the stable core",
+            "fan_in_gini": f"in-degree inequality (Gini) {m['fan_in_gini']:.2f}",
+        }
+        result.evidence = [
+            GraphEvidence(
+                provider="module_graph", kind=k, value=m[k], mass=topo_mass,
+                confidence=result.confidence, detail=details[k],
+            )
+            for k in details
+        ]
+        return result
+
+    # ── graph projection ───────────────────────────────────────────────────────
+    @staticmethod
+    def _project(
+        graph: object, edge_kinds: Optional[Iterable[str]]
+    ) -> "tuple[list[str], dict[str, set[str]]]":
+        """Reduce the graph to a deduped directed adjacency over the relevant
+        vertices. Prefers module-granularity nodes; falls back to all nodes."""
+        raw_nodes = list(getattr(graph, "nodes", []) or [])
+        raw_edges = list(getattr(graph, "edges", []) or [])
+        kinds = frozenset(edge_kinds) if edge_kinds is not None else _STRUCTURAL_EDGE_KINDS
+
+        module_ids = {getattr(nd, "id") for nd in raw_nodes if getattr(nd, "kind", None) == "module"}
+        # If the graph carries module nodes, restrict to them; otherwise use every
+        # node (synthetic test graphs, symbol-only graphs).
+        if module_ids:
+            allowed = module_ids
+        else:
+            allowed = {getattr(nd, "id") for nd in raw_nodes}
+
+        adjacency: dict[str, set[str]] = {nid: set() for nid in allowed}
+        for ed in raw_edges:
+            if getattr(ed, "kind", None) not in kinds:
+                continue
+            u = getattr(ed, "source", None)
+            v = getattr(ed, "target", None)
+            if u is None or v is None or u == v:
+                continue
+            if u not in allowed or v not in allowed:
+                continue
+            adjacency.setdefault(u, set()).add(v)
+            adjacency.setdefault(v, set())
+        nodes = sorted(adjacency.keys())
+        return nodes, adjacency
+
+    # ── metric primitives ──────────────────────────────────────────────────────
+    @staticmethod
+    def _degrees(
+        nodes: list[str], edges: list[tuple[str, str]]
+    ) -> "tuple[dict[str, int], dict[str, int]]":
+        in_deg = {x: 0 for x in nodes}
+        out_deg = {x: 0 for x in nodes}
+        for u, v in edges:
+            out_deg[u] += 1
+            in_deg[v] += 1
+        return in_deg, out_deg
+
+    @staticmethod
+    def _tarjan_scc(
+        nodes: list[str], adjacency: dict[str, set[str]]
+    ) -> "tuple[dict[str, int], dict[int, int]]":
+        """Iterative Tarjan. Returns (node -> scc_id, scc_id -> size)."""
+        index_of: dict[str, int] = {}
+        low: dict[str, int] = {}
+        on_stack: set[str] = set()
+        stack: list[str] = []
+        scc_of: dict[str, int] = {}
+        sizes: dict[int, int] = {}
+        counter = 0
+        scc_id = 0
+
+        for root in nodes:
+            if root in index_of:
+                continue
+            # work stack of (node, iterator-position)
+            work: list[tuple[str, int]] = [(root, 0)]
+            while work:
+                v, pi = work[-1]
+                if pi == 0:
+                    index_of[v] = low[v] = counter
+                    counter += 1
+                    stack.append(v)
+                    on_stack.add(v)
+                succ = sorted(adjacency.get(v, ()))
+                if pi < len(succ):
+                    work[-1] = (v, pi + 1)
+                    w = succ[pi]
+                    if w not in index_of:
+                        work.append((w, 0))
+                    elif w in on_stack:
+                        low[v] = min(low[v], index_of[w])
+                    continue
+                # done with v
+                if low[v] == index_of[v]:
+                    size = 0
+                    while True:
+                        w = stack.pop()
+                        on_stack.discard(w)
+                        scc_of[w] = scc_id
+                        size += 1
+                        if w == v:
+                            break
+                    sizes[scc_id] = size
+                    scc_id += 1
+                work.pop()
+                if work:
+                    parent = work[-1][0]
+                    low[parent] = min(low[parent], low[v])
+        return scc_of, sizes
+
+    @staticmethod
+    def _cyclic_density(
+        edges: list[tuple[str, str]], scc_of: dict[str, int],
+        scc_sizes: dict[int, int], e: int,
+    ) -> float:
+        if not e:
+            return 0.0
+        intra = 0
+        for u, v in edges:
+            su = scc_of.get(u)
+            if su is not None and su == scc_of.get(v) and scc_sizes.get(su, 1) > 1:
+                intra += 1
+        return intra / e
+
+    @staticmethod
+    def _centralization(in_deg: dict[str, int], n: int) -> float:
+        """Freeman in-degree centralization, normalized to [0,1]."""
+        if n < 2:
+            return 0.0
+        mx = max(in_deg.values(), default=0)
+        total_diff = sum(mx - d for d in in_deg.values())
+        denom = (n - 1) * (n - 1)  # theoretical max for a directed star
+        return min(1.0, total_diff / denom) if denom else 0.0
+
+    @staticmethod
+    def _instability(
+        nodes: list[str], in_deg: dict[str, int], out_deg: dict[str, int]
+    ) -> dict[str, float]:
+        """Martin instability I = out / (in + out). Isolated nodes -> None-like
+        (excluded via absence)."""
+        inst: dict[str, float] = {}
+        for x in nodes:
+            total = in_deg[x] + out_deg[x]
+            if total > 0:
+                inst[x] = out_deg[x] / total
+        return inst
+
+    @staticmethod
+    def _downward_ratio(
+        edges: list[tuple[str, str]], instability: dict[str, float]
+    ) -> float:
+        considered = 0
+        downward = 0
+        for u, v in edges:
+            if u in instability and v in instability:
+                considered += 1
+                # edge from less-stable (higher I) to more-stable (lower I)
+                if instability[u] >= instability[v]:
+                    downward += 1
+        return (downward / considered) if considered else 0.0
+
+    @staticmethod
+    def _inversion_ratio(
+        edges: list[tuple[str, str]], instability: dict[str, float]
+    ) -> float:
+        """Fraction of edges whose target sits in the most-stable quartile."""
+        vals = sorted(instability.values())
+        if not vals or not edges:
+            return 0.0
+        q1 = vals[max(0, len(vals) // 4 - 1)]
+        into_core = sum(
+            1 for _u, v in edges
+            if v in instability and instability[v] <= q1
+        )
+        return into_core / len(edges)
+
+    @staticmethod
+    def _gini(values: list[int]) -> float:
+        vals = sorted(float(v) for v in values)
+        n = len(vals)
+        s = sum(vals)
+        if n == 0 or s == 0:
+            return 0.0
+        cum = 0.0
+        for i, v in enumerate(vals, start=1):
+            cum += i * v
+        # Gini = (2*sum(i*x_i) / (n*sum)) - (n+1)/n
+        return max(0.0, min(1.0, (2 * cum) / (n * s) - (n + 1) / n))

{sourcecode-2.2.0.dist-info → sourcecode-2.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.2.0
+Version: 2.4.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-2.2.0-blue)
+![Version](https://img.shields.io/badge/version-2.3.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -84,7 +84,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 2.2.0
+ask version                    # ask 2.3.0
 ```
 
 > **Package vs. command.** The install package is named `sourcecode` this release

{sourcecode-2.2.0.dist-info → sourcecode-2.4.0.dist-info}/RECORD

@@ -1,17 +1,19 @@
-sourcecode/__init__.py,sha256=QOkIfC7KA2tM2ix9_wUgS6fHiERh2v_TTNhjw8RBb1o,308
+sourcecode/__init__.py,sha256=1iN-frOfJr05mYoED0IYnoxSY-4xnA-sHP9MRe_9Qn4,308
 sourcecode/adaptive_scanner.py,sha256=XffluXKzJUXrMtjEiAOnSNPZnztdIcts17T9ouHeID0,10521
+sourcecode/archetype.py,sha256=ezeyCR4E0VeZUUBPwmsWUUPAhIlqwwkc8qDieUx2JWA,31087
 sourcecode/architecture_analyzer.py,sha256=6_wC4TYuBYxaqckZS0I1vBSMRPeH2vzlDB48gXwOOd4,46627
-sourcecode/architecture_summary.py,sha256=UaxmUU77oTlWxttMU3c6PxHrU-Q6q5N31TeU_NWWTdU,24297
+sourcecode/architecture_summary.py,sha256=pkl6lIOnSy-poa9EzW43U0MkXhx2FDfAFh8pDXLpcTo,26630
 sourcecode/ast_extractor.py,sha256=FEsYTsMCXbJfSYQZRk1k-I-PjUNGnKqO1IxMftsgA5U,51351
 sourcecode/cache.py,sha256=1V3vsaODAa2UBJAC0xpvxpmRdriCezQx5Q8JCcfgziE,31892
 sourcecode/call_surface.py,sha256=fiqYfHooxN1fX9oQoysq1LS3LoZcobhyUNjAGEZKpwk,4148
 sourcecode/caller_metrics.py,sha256=HG8RCOkpzzsEGdnMRob6byrwjoj5__t0TEsBj4yR7ks,2574
 sourcecode/canonical_ir.py,sha256=U69m8Vkr0p407xF1q5y1KguHXWEAubYw8NFHR9hDNJk,29178
 sourcecode/cir_graphs.py,sha256=9G0HHj1kw2325IDyzo2OpX73BNswEckecf4MZUXB4JM,12078
-sourcecode/classifier.py,sha256=YTTCoRdcLEFRVcql9Ow1dE7eYQj0jq2rgx32bRDnb1k,13852
-sourcecode/cli.py,sha256=CKy6zdBfecnT6reYb749pLY4NqH1_Qy7c8DHnBWamrU,293593
+sourcecode/classifier.py,sha256=RhLMDR031FAiUcT3bsf2EL3KrFwl7KsWh_wXXR_Bumo,18729
+sourcecode/cli.py,sha256=xYrKelvgspWuus8LM4DcRroXGydbU47CAr-KV-8oysU,299977
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/confidence_analyzer.py,sha256=_jckZSxksV-OU38vbkxfVNBnWCtlCq8Vwfg23x1uspA,19054
+sourcecode/context_cache.py,sha256=maws79rLKDwyZ7c9Q2LwlIxqZHRFlaKzErtO3mglWoA,25036
 sourcecode/context_graph.py,sha256=8MVDu06bPhvRDTgUqWEvRME2fOw34bFLf4OUILZd13I,43527
 sourcecode/context_scorer.py,sha256=QpChSpsmaAYz91rXA4Ue5xzQmNz_ZboZN09YOHScq1U,14679
 sourcecode/context_summarizer.py,sha256=cI2TZMvEhl0BEma12VtPaX6z03ZVBAetVzuK5GaCOvg,6852
@@ -27,13 +29,14 @@ sourcecode/entrypoint_classifier.py,sha256=jhTYlyqDJH2AtdEcLVaRU3lYRTJuF8DkxVzl4
 sourcecode/env_analyzer.py,sha256=aNTyYgQk5noJDfJU6FmasmESOHfiomyJw5EvZqjy6qc,22213
 sourcecode/error_schema.py,sha256=uwosfNaSujtYm11_732Hu92z5ITV040fQDaIyefSvR4,1683
 sourcecode/evidence_provider.py,sha256=GSSL44JEaouO5AHks2sB3d1YvC9xIKIld1yBYxZpXxo,4277
-sourcecode/explain.py,sha256=bo4sy8qkEstIF3sIefECKRYJBK97C6cMjyzRa8USCdI,21189
+sourcecode/explain.py,sha256=HnHWVTNNf9fzeR3FP-A-eXKeKZvBcUEuODgIO3rJQkQ,22312
 sourcecode/file_chunker.py,sha256=3vkM3mDQ5eE_yTPvUgjyjpGFBIjkW6_mrBmIbrylnA8,16444
 sourcecode/file_classifier.py,sha256=A0fEABqtfVu1MfoaxnPAvGpZgneGgVXlJDhT74NYXxE,15314
 sourcecode/format_contract.py,sha256=1cTNqwP8geA2hbQoBHUPgX3_vSh3l8guJT_jmgEnFF8,3466
 sourcecode/fqn_utils.py,sha256=XLU7zDkNBXz_RZkIUNfpPmp1nekWtqP-fxV92tDV1vg,2158
 sourcecode/git_analyzer.py,sha256=JStxTQXNjBWi_wLdwhsZs9mT-v50cSJIz4Agzn6Kh9I,13362
 sourcecode/graph_analyzer.py,sha256=lp0eB1PWC20BYF-GpPhAyegRpKrUKgOmXZIcZSIX_Ks,65777
+sourcecode/graph_evidence.py,sha256=rENNsYRZeNstX_ExNCLlbHJAruFQwxo5d00x6wO3xwI,15030
 sourcecode/hibernate_strat.py,sha256=h0leIhlWvSjYq3F99LxvLIDLrJ-xPYxWAREG4LkqZ-4,61190
 sourcecode/jdk_exports.py,sha256=fCrlwNAXUT9gge_joq6kMnY3zJxYB2pxqy-0w3o3MJI,874
 sourcecode/license.py,sha256=keFuwNxdAtvK2Ds91Wl79GMYxuxWYnN5Wbw1qBpaoUI,24896
@@ -115,8 +118,8 @@ sourcecode/telemetry/consent.py,sha256=LIAO9ohJZF8OuZwM4u1VWtALlYfTCCKq4wV3Vwc7i
 sourcecode/telemetry/events.py,sha256=LtzYfaX9Ilckj5PTvAcTpDa9mLqDsYPDUiDkRa58piY,2580
 sourcecode/telemetry/filters.py,sha256=NHa5T-6DaZduQPFuC34jOqHWQgSizM-Ygq8aZ4j19ng,5834
 sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
-sourcecode-2.2.0.dist-info/METADATA,sha256=GWUjIL4RNPYx8cMKSRHxzELL49K0anIx6qH8aHAsB3I,10837
-sourcecode-2.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-2.2.0.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
-sourcecode-2.2.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-2.2.0.dist-info/RECORD,,
+sourcecode-2.4.0.dist-info/METADATA,sha256=fairNRCqgRAaSicMGWcWQcPral9_3NeVBIDTrv2rHaI,10837
+sourcecode-2.4.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-2.4.0.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
+sourcecode-2.4.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-2.4.0.dist-info/RECORD,,