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

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"

sourcecode/archetype.py

@@ -0,0 +1,605 @@
+"""Evidence-based architectural archetype classifier (ADDITIVE / EXPERIMENTAL).
+
+Runs in PARALLEL with the legacy `ArchitectureAnalyzer` pattern. It does NOT feed
+the report wording yet — it exists so the new model can be validated against the
+legacy one across many repos before any cutover.
+
+Design goals (vs the legacy directory-name matcher):
+  * describe WHAT a system is, not which technologies it contains;
+  * accumulate weighted evidence from many signals — never a single dominant rule;
+  * weight every signal by CODE MASS (fraction of the codebase it represents), so a
+    directory named `api/` in a 5,600-file engine contributes ~0.003, not 1.0;
+  * report per-candidate score + evidence + confidence + a human explanation.
+
+Four ORTHOGONAL dimensions (a system is a point in each, not one enum):
+  * software_archetype : engine | platform | framework | library | application | compiler | sdk
+  * architectural_style: layered | hexagonal | clean | mvc | event-driven | plugin-based | microkernel
+  * deployment_shape   : monolith | multi-module | distributed | embedded
+  * primary_interface  : api-first | cli | worker | daemon | library | embedded
+
+Signals consumed today (all cheap / already computed by a normal scan):
+  module masses (file_tree), package-concept masses (path segments), entry-point
+  kinds, HTTP endpoint share, packaging, detected frameworks, and — when present on
+  the SourceMap — module_graph_summary (hubs/cycles). Richer signals (repo-ir
+  subsystem masses, Semantic-IR SPI fan-in, protocol handlers) are declared in
+  `signals_missing` when unavailable so the confidence reflects it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from sourcecode.graph_evidence import GraphEvidence, GraphEvidenceProvider, GraphEvidenceResult
+from sourcecode.schema import SourceMap
+from sourcecode.tree_utils import flatten_file_tree
+
+_JVM_EXTS = (".java", ".kt", ".kts", ".scala", ".groovy")
+_CODE_EXTS = _JVM_EXTS + (".py", ".go", ".rs", ".cs", ".ts", ".js", ".rb", ".php")
+_NON_SOURCE = frozenset({
+    "test", "tests", "src-test", "it", "benchmark", "benchmarks", "bench",
+    "example", "examples", "demo", "docs", "doc", "fixture", "fixtures",
+    "node_modules", "target", "build", "generated", "resources",
+})
+
+# Concept banks: path-segment keywords → a named concept. Mass of a concept =
+# fraction of source files whose path contains any of its segments. These are
+# DOMAIN concepts, not framework names; membership is deliberately broad.
+_CONCEPTS: dict[str, frozenset[str]] = {
+    "storage":     frozenset({"storage", "store", "pagecache", "pagecache", "recordstorage",
+                              "record", "btree", "gbptree", "wal", "log", "tx", "transaction",
+                              "commit", "checkpoint", "index", "lucene", "kvstore", "heap"}),
+    "kernel":      frozenset({"kernel", "engine", "executor", "runtime", "core", "internal"}),
+    "compiler":    frozenset({"parser", "lexer", "ast", "grammar", "antlr", "codegen",
+                              "compiler", "ir", "bytecode", "semantic", "typecheck", "rewriter",
+                              "planner", "optimizer", "expression"}),
+    "protocol":    frozenset({"protocol", "bolt", "netty", "transport", "wire", "packstream",
+                              "rpc", "grpc", "http", "connector", "connection"}),
+    "distributed": frozenset({"cluster", "raft", "discovery", "gossip", "consensus",
+                              "replication", "coordination", "membership", "fabric", "routing"}),
+    "web":         frozenset({"controller", "controllers", "rest", "mvc", "servlet",
+                              "endpoint", "endpoints", "resource", "webapp", "jaxrs"}),
+    "service":     frozenset({"service", "services", "usecase", "usecases", "application"}),
+    "repository":  frozenset({"repository", "repositories", "repo", "dao", "persistence"}),
+    "event":       frozenset({"event", "events", "listener", "listeners", "publisher",
+                              "subscriber", "bus", "dispatcher", "reactor"}),
+    "plugin":      frozenset({"plugin", "plugins", "extension", "extensions", "spi",
+                              "provider", "providers", "addon", "module"}),
+    "api_pkg":     frozenset({"api", "apis", "spi", "contract", "interfaces"}),
+    "cli":         frozenset({"cli", "command", "commands", "commandline", "shell", "console"}),
+    "hexagonal":   frozenset({"adapter", "adapters", "port", "ports"}),
+    "clean":       frozenset({"domain", "domains", "usecase", "usecases", "infrastructure", "infra"}),
+    "cqrs":        frozenset({"command", "commands", "query", "queries"}),
+    "sdk_client":  frozenset({"client", "clients", "sdk"}),
+}
+
+_CONF_ORDER = {"high": 3, "medium": 2, "low": 1}
+# A dimension whose best candidate scores below this is reported as undetermined
+# (primary=None) rather than asserting a label on noise.
+_MIN_PRIMARY_SCORE = 0.05
+# A winner must clear this absolute score (not just the top-2 margin) to earn
+# medium/high confidence — a near-floor lone candidate stays "low".
+_MIN_CONFIDENT_SCORE = 0.5
+
+
+@dataclass
+class Evidence:
+    signal: str          # machine name, e.g. "storage_mass"
+    detail: str          # human-readable
+    weight: float        # base importance of the signal
+    strength: float      # 0..1 — how strongly the signal is present
+    mass: float          # 0..1 — fraction of the codebase it represents (1.0 if N/A)
+    contribution: float  # weight * strength * mass (what actually adds to the score)
+
+
+@dataclass
+class ArchetypeCandidate:
+    label: str
+    score: float
+    evidence: list[Evidence] = field(default_factory=list)
+
+
+@dataclass
+class DimensionResult:
+    dimension: str
+    primary: Optional[str]
+    confidence: str                       # high | medium | low
+    candidates: list[ArchetypeCandidate]  # sorted score desc
+    explanation: str
+
+
+@dataclass
+class ArchetypeAnalysis:
+    dimensions: dict[str, DimensionResult]
+    signals_used: list[str]
+    signals_missing: list[str]
+    generated_from: str
+    graph_metrics: dict[str, float] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": "0.1-experimental",
+            "note": "Parallel/experimental model. Legacy architecture pattern is unchanged.",
+            "dimensions": {
+                dim: {
+                    "primary": r.primary,
+                    "confidence": r.confidence,
+                    "explanation": r.explanation,
+                    "candidates": [
+                        {
+                            "label": c.label,
+                            "score": round(c.score, 4),
+                            "evidence": [
+                                {
+                                    "signal": e.signal, "detail": e.detail,
+                                    "weight": e.weight, "strength": round(e.strength, 3),
+                                    "mass": round(e.mass, 4),
+                                    "contribution": round(e.contribution, 4),
+                                }
+                                for e in c.evidence
+                            ],
+                        }
+                        for c in r.candidates
+                    ],
+                }
+                for dim, r in self.dimensions.items()
+            },
+            "signals_used": self.signals_used,
+            "signals_missing": self.signals_missing,
+            "generated_from": self.generated_from,
+            "graph_metrics": {k: round(v, 4) for k, v in self.graph_metrics.items()},
+        }
+
+
+@dataclass
+class _Features:
+    total_files: int
+    module_counts: dict[str, int]
+    dominant_module: Optional[str]
+    dominant_share: float
+    module_count: int
+    concept_mass: dict[str, float]        # concept → fraction of source files
+    entry_kinds: dict[str, int]
+    endpoint_total: int
+    endpoint_share: float                 # endpoints per source file
+    packaging: Optional[str]
+    frameworks: set[str]
+    graph_hubs: list[str]
+    graph_cycles: int
+    graph_available: bool
+    graph_evidence: list[GraphEvidence]
+    graph_metrics: dict[str, float]
+    signals_used: list[str]
+    signals_missing: list[str]
+
+
+# Which archetype each topological metric supports, and how. Each entry is
+# (dimension, label, weight, polarity, lo, hi): the metric's raw value is ramped
+# to a strength via (value-lo)/(hi-lo) clamped to [0,1]; polarity +1 supports the
+# label, -1 refutes it (negative contribution). This is the ONLY place that knows
+# both graphs and archetypes — the provider stays archetype-agnostic, the scorer
+# stays graph-agnostic, and the coupling lives here as declarative data.
+_GRAPH_MAP: dict[str, list[tuple[str, str, float, int, float, float]]] = {
+    "scc_mass": [
+        ("software_archetype", "engine",      2.5, +1, 0.10, 0.50),
+        ("architectural_style", "layered",    1.5, -1, 0.10, 0.50),
+    ],
+    "cyclic_density": [
+        ("software_archetype", "engine",      2.0, +1, 0.05, 0.40),
+        ("architectural_style", "layered",    2.0, -1, 0.05, 0.40),
+        ("architectural_style", "hexagonal",  1.5, -1, 0.05, 0.40),
+        ("architectural_style", "microkernel", 1.5, -1, 0.05, 0.40),
+    ],
+    "hub_concentration": [
+        ("software_archetype", "engine",      1.5, +1, 0.10, 0.40),
+        ("architectural_style", "microkernel", 1.5, +1, 0.10, 0.40),
+    ],
+    "module_centralization": [
+        ("architectural_style", "microkernel", 2.0, +1, 0.30, 0.80),
+        ("architectural_style", "hexagonal",  1.5, -1, 0.30, 0.80),  # a single hub is not a distributed domain core
+        ("software_archetype", "platform",    0.8, +1, 0.30, 0.80),
+    ],
+    "downward_edge_ratio": [
+        ("architectural_style", "layered",    2.5, +1, 0.55, 0.90),
+        ("architectural_style", "hexagonal",  1.0, +1, 0.55, 0.90),
+    ],
+    "dependency_inversion_ratio": [
+        ("architectural_style", "hexagonal",  2.5, +1, 0.50, 0.80),
+        ("architectural_style", "clean",      1.5, +1, 0.50, 0.80),
+    ],
+    "fan_in_gini": [
+        ("software_archetype", "engine",      1.5, +1, 0.40, 0.75),
+    ],
+}
+
+
+class ArchetypeClassifier:
+    """Consumes a SourceMap; emits an ArchetypeAnalysis. Pure (no filesystem writes)."""
+
+    def analyze(
+        self,
+        sm: SourceMap,
+        root: Optional[Path] = None,
+        module_graph: object = None,
+    ) -> ArchetypeAnalysis:
+        f = self._extract_features(sm, root, module_graph)
+        dims = {
+            "software_archetype": self._software_archetype(f),
+            "architectural_style": self._architectural_style(f),
+            "deployment_shape": self._deployment_shape(f),
+            "primary_interface": self._primary_interface(f),
+        }
+        return ArchetypeAnalysis(
+            dimensions=dims,
+            signals_used=f.signals_used,
+            signals_missing=f.signals_missing,
+            generated_from=(
+                f"{f.total_files} source files, {f.module_count} modules, "
+                f"{f.endpoint_total} endpoints"
+            ),
+            graph_metrics=f.graph_metrics,
+        )
+
+    # ── feature extraction ────────────────────────────────────────────────────
+    def _extract_features(
+        self, sm: SourceMap, root: Optional[Path], module_graph: object = None,
+    ) -> _Features:
+        used: list[str] = []
+        missing: list[str] = []
+        paths = [p.replace("\\", "/") for p in (sm.file_paths or flatten_file_tree(sm.file_tree))]
+        src = [
+            p for p in paths
+            if p.endswith(_CODE_EXTS)
+            and not any(seg.lower() in _NON_SOURCE for seg in p.split("/")[:-1])
+        ]
+        total = len(src)
+
+        module_counts: dict[str, int] = {}
+        for p in src:
+            module_counts[self._module_of(p)] = module_counts.get(self._module_of(p), 0) + 1
+        module_counts.pop("", None)
+        dominant = max(module_counts, key=lambda m: module_counts[m], default=None)
+        dominant_share = (module_counts[dominant] / total) if (dominant and total) else 0.0
+        if module_counts:
+            used.append("module_masses")
+
+        # concept masses (share of source files whose path touches the concept)
+        concept_mass: dict[str, float] = {}
+        for concept, kws in _CONCEPTS.items():
+            hits = sum(
+                1 for p in src
+                if any(seg.lower() in kws for seg in p.split("/")[:-1])
+            )
+            concept_mass[concept] = (hits / total) if total else 0.0
+        if total:
+            used.append("concept_masses")
+
+        entry_kinds: dict[str, int] = {}
+        for ep in sm.entry_points or []:
+            k = getattr(ep, "kind", None) or "unknown"
+            entry_kinds[k] = entry_kinds.get(k, 0) + 1
+        if sm.entry_points:
+            used.append("entry_points")
+        else:
+            missing.append("entry_points")
+
+        endpoint_total = self._endpoint_count(root)
+        endpoint_share = (endpoint_total / total) if total else 0.0
+        if root is not None:
+            used.append("endpoints")
+        else:
+            missing.append("endpoints")
+
+        frameworks = {fw.name for s in (sm.stacks or []) for fw in s.frameworks}
+        if frameworks:
+            used.append("frameworks")
+
+        hubs: list[str] = []
+        cycles = 0
+        mgs = sm.module_graph_summary
+        if mgs is not None:
+            hubs = list(getattr(mgs, "hubs", []) or [])
+            cycles = int(getattr(mgs, "cycle_count", 0) or 0)
+            used.append("module_graph_summary")
+
+        # Module graph as a first-class Evidence Provider (ADR-0003 step 2).
+        # A ModuleGraph (nodes+edges) yields topological evidence the scorer can
+        # consume WITHOUT ever walking the graph. Absent/too-small graphs degrade
+        # to today's name-mass-only behaviour and are declared missing.
+        graph = module_graph if module_graph is not None else sm.module_graph
+        graph_result: GraphEvidenceResult = (
+            GraphEvidenceProvider().analyze(graph) if graph is not None
+            else GraphEvidenceResult(node_count=0, edge_count=0)
+        )
+        if graph_result.available:
+            used.append("module_graph")
+            if not cycles and graph_result.metric("cyclic_density") > 0:
+                cycles = 1  # topology confirms a cyclic core even without a summary
+        else:
+            missing.append("module_graph")
+        # Richer signals not wired yet — declare them so confidence reflects it.
+        missing.append("repo_ir_subsystem_masses")
+        missing.append("semantic_ir_spi_fanin")
+
+        return _Features(
+            total_files=total,
+            module_counts=module_counts,
+            dominant_module=dominant,
+            dominant_share=dominant_share,
+            module_count=len(module_counts),
+            concept_mass=concept_mass,
+            entry_kinds=entry_kinds,
+            endpoint_total=endpoint_total,
+            endpoint_share=endpoint_share,
+            packaging=sm.packaging,
+            frameworks=frameworks,
+            graph_hubs=hubs,
+            graph_cycles=cycles,
+            graph_available=graph_result.available,
+            graph_evidence=graph_result.evidence,
+            graph_metrics=graph_result.metrics,
+            signals_used=used,
+            signals_missing=missing,
+        )
+
+    # ── dimension scorers ─────────────────────────────────────────────────────
+    def _software_archetype(self, f: _Features) -> DimensionResult:
+        cm = f.concept_mass
+        cands: dict[str, list[Evidence]] = {a: [] for a in
+                                            ("engine", "compiler", "framework", "library",
+                                             "application", "platform", "sdk")}
+
+        def add(label: str, signal: str, detail: str, weight: float, strength: float, mass: float):
+            cands[label].append(Evidence(signal, detail, weight, strength,
+                                         mass, weight * strength * mass))
+
+        # engine: storage/kernel mass is the core of the codebase
+        eng_mass = min(1.0, cm["storage"] + cm["kernel"])
+        add("engine", "storage_kernel_mass",
+            f"storage+kernel packages ≈ {eng_mass:.0%} of source", 3.0, 1.0, eng_mass)
+        if f.graph_cycles > 0:
+            add("engine", "cyclic_core",
+                f"{f.graph_cycles} import cycle(s) — tightly-woven engine core", 1.0, 1.0, 0.5)
+        # compiler: parser/ast/ir/codegen pipeline mass
+        add("compiler", "compiler_pipeline_mass",
+            f"parser/ast/ir/codegen packages ≈ {cm['compiler']:.0%}", 3.0, 1.0, cm["compiler"])
+        # framework: plugin/SPI extension surface + jar packaging + not app-entry
+        fw_strength = 1.0 if f.packaging == "jar" else 0.6
+        add("framework", "extension_surface_mass",
+            f"plugin/SPI/provider packages ≈ {cm['plugin']:.0%}", 2.5, fw_strength, cm["plugin"])
+        # library/SDK: public API surface, no server/cli bootstrap
+        has_server = any(k in f.entry_kinds for k in ("server", "jax_rs_controller"))
+        has_bootstrap = "bootstrap" in f.entry_kinds or "application" in f.entry_kinds
+        lib_strength = 0.4 if (has_server or has_bootstrap) else 1.0
+        add("library", "public_api_no_runtime",
+            f"api/contract packages ≈ {cm['api_pkg']:.0%}; "
+            f"{'no' if lib_strength == 1.0 else 'has'} server/bootstrap entry",
+            2.0, lib_strength, max(cm["api_pkg"], 0.15))
+        if cm["sdk_client"] > 0.1:
+            add("sdk", "client_packages",
+                f"client/sdk packages ≈ {cm['sdk_client']:.0%}", 2.0, 1.0, cm["sdk_client"])
+        # application: has bootstrap/server + business (service) mass
+        if has_bootstrap or has_server:
+            add("application", "runtime_entry_plus_services",
+                f"bootstrap/server entry + service mass ≈ {cm['service']:.0%}",
+                2.0, 1.0, max(cm["service"], 0.2))
+        # platform: many modules + multiple concept clusters + distribution
+        multi = 1.0 if f.module_count >= 8 else f.module_count / 8
+        add("platform", "many_modules_multi_concern",
+            f"{f.module_count} modules; distributed mass ≈ {cm['distributed']:.0%}",
+            1.5, multi, max(cm["distributed"], 0.1))
+        self._apply_graph_evidence("software_archetype", cands, f)
+        return self._resolve("software_archetype", cands, f)
+
+    def _architectural_style(self, f: _Features) -> DimensionResult:
+        cm = f.concept_mass
+        cands: dict[str, list[Evidence]] = {a: [] for a in
+                                            ("layered", "hexagonal", "clean", "mvc",
+                                             "event-driven", "plugin-based", "microkernel")}
+
+        def add(label, signal, detail, weight, strength, mass):
+            cands[label].append(Evidence(signal, detail, weight, strength,
+                                         mass, weight * strength * mass))
+
+        # layered: needs BOTH web/controller AND service AND repository mass — and each
+        # must be non-trivial. Legacy asserted this from mere name presence; we weight
+        # by mass so a 0.3% `api/` dir does not manufacture a "controller layer".
+        layered_present = sum(1 for c in ("web", "service", "repository") if cm[c] >= 0.05)
+        layered_mass = min(1.0, cm["web"] + cm["service"] + cm["repository"])
+        add("layered", "layered_triplet_mass",
+            f"controller/service/repository mass ≈ {layered_mass:.0%} "
+            f"({layered_present}/3 layers above 5%)",
+            2.0, layered_present / 3, layered_mass)
+        # mvc requires a view/web surface with real mass
+        add("mvc", "web_view_mass", f"web/controller mass ≈ {cm['web']:.0%}",
+            2.0, 1.0 if cm["web"] >= 0.05 else 0.0, cm["web"])
+        # hexagonal / clean
+        add("hexagonal", "ports_adapters_mass", f"ports/adapters mass ≈ {cm['hexagonal']:.0%}",
+            2.5, 1.0, cm["hexagonal"])
+        add("clean", "domain_usecase_infra_mass", f"domain/usecase/infra mass ≈ {cm['clean']:.0%}",
+            2.5, 1.0, cm["clean"])
+        # event-driven
+        add("event-driven", "event_mass", f"event/listener/bus mass ≈ {cm['event']:.0%}",
+            2.0, 1.0, cm["event"])
+        # plugin-based / microkernel: plugin mass + small dominant core
+        add("plugin-based", "plugin_mass", f"plugin/extension mass ≈ {cm['plugin']:.0%}",
+            2.0, 1.0, cm["plugin"])
+        micro_strength = 1.0 if (cm["plugin"] > 0.05 and f.dominant_share < 0.4) else 0.0
+        add("microkernel", "small_core_many_plugins",
+            f"plugin mass ≈ {cm['plugin']:.0%}, dominant module {f.dominant_share:.0%}",
+            1.5, micro_strength, max(cm["plugin"], 0.1))
+        self._apply_graph_evidence("architectural_style", cands, f)
+        return self._resolve("architectural_style", cands, f)
+
+    def _deployment_shape(self, f: _Features) -> DimensionResult:
+        cm = f.concept_mass
+        cands: dict[str, list[Evidence]] = {a: [] for a in
+                                            ("monolith", "multi-module", "distributed", "embedded")}
+
+        def add(label, signal, detail, weight, strength, mass):
+            cands[label].append(Evidence(signal, detail, weight, strength,
+                                         mass, weight * strength * mass))
+
+        multi = 1.0 if f.module_count >= 3 else f.module_count / 3
+        add("multi-module", "module_count", f"{f.module_count} source modules", 2.0, multi, 1.0)
+        # monolith: modules but a single deployable (one war, or a single dominant module)
+        mono_strength = 1.0 if (f.packaging == "war" or f.dominant_share >= 0.5) else 0.3
+        add("monolith", "single_deployable",
+            f"packaging={f.packaging}, dominant module {f.dominant_share:.0%}",
+            1.5, mono_strength, 1.0)
+        add("distributed", "cluster_mass", f"cluster/raft/discovery mass ≈ {cm['distributed']:.0%}",
+            2.5, 1.0, cm["distributed"])
+        # embedded: library packaging + embeddable API, no server bootstrap
+        emb_strength = 1.0 if (f.packaging == "jar" and "server" not in f.entry_kinds) else 0.3
+        add("embedded", "library_packaging_no_server",
+            f"packaging={f.packaging}, {'no' if 'server' not in f.entry_kinds else 'has'} server entry",
+            1.5, emb_strength, 0.5)
+        return self._resolve("deployment_shape", cands, f)
+
+    def _primary_interface(self, f: _Features) -> DimensionResult:
+        cm = f.concept_mass
+        cands: dict[str, list[Evidence]] = {a: [] for a in
+                                            ("api-first", "cli", "worker", "daemon",
+                                             "library", "embedded")}
+
+        def add(label, signal, detail, weight, strength, mass):
+            cands[label].append(Evidence(signal, detail, weight, strength,
+                                         mass, weight * strength * mass))
+
+        # api-first: HTTP surface must be significant relative to size. Ramp so a
+        # rounding-error surface cannot win: 0 below 0.5 endpoints/100 files, linear
+        # to full strength at >=2/100 files. (neo4j: 18/5600 = 0.32/100 -> 0.)
+        density = f.endpoint_share * 100
+        api_strength = max(0.0, min(1.0, (density - 0.5) / 1.5)) if f.endpoint_total else 0.0
+        add("api-first", "endpoint_density",
+            f"{f.endpoint_total} endpoints over {f.total_files} files "
+            f"({density:.2f}/100 files)",
+            3.0, api_strength, 1.0)
+        cli_entries = f.entry_kinds.get("cli", 0)
+        add("cli", "cli_entry_points", f"{cli_entries} CLI entry point(s); cli mass ≈ {cm['cli']:.0%}",
+            2.5, 1.0 if cli_entries else (1.0 if cm["cli"] > 0.05 else 0.0), max(cm["cli"], 0.2))
+        add("daemon", "server_bootstrap",
+            f"server/bootstrap entries: {f.entry_kinds.get('server',0)+f.entry_kinds.get('bootstrap',0)}",
+            2.0, 1.0 if ("server" in f.entry_kinds or "bootstrap" in f.entry_kinds) else 0.0, 0.5)
+        add("worker", "event_no_http",
+            f"event mass ≈ {cm['event']:.0%}, endpoints={f.endpoint_total}",
+            1.5, 1.0 if (cm["event"] > 0.05 and f.endpoint_total == 0) else 0.0, max(cm["event"], 0.1))
+        lib_strength = 1.0 if (f.packaging == "jar" and not f.entry_kinds) else 0.3
+        add("library", "consumed_as_dependency",
+            f"packaging={f.packaging}, entry kinds={list(f.entry_kinds) or 'none'}",
+            1.5, lib_strength, 0.4)
+        add("embedded", "embeddable_api", f"api mass ≈ {cm['api_pkg']:.0%}, packaging={f.packaging}",
+            1.2, 1.0 if (f.packaging == "jar" and cm["api_pkg"] > 0.03) else 0.0, 0.4)
+        return self._resolve("primary_interface", cands, f)
+
+    # ── graph evidence bridge ──────────────────────────────────────────────────
+    def _apply_graph_evidence(
+        self, dimension: str, cands: dict[str, list[Evidence]], f: _Features,
+    ) -> None:
+        """Translate topological GraphEvidence into archetype Evidence for this
+        dimension, via the declarative `_GRAPH_MAP`. The scorer consumes evidence
+        objects here; it never inspects nodes or edges. A metric with polarity -1
+        contributes NEGATIVELY (e.g. a dense cyclic core refutes 'layered')."""
+        if not f.graph_available:
+            return
+        ev_by_kind = {e.kind: e for e in f.graph_evidence}
+        for kind, mappings in _GRAPH_MAP.items():
+            ge = ev_by_kind.get(kind)
+            if ge is None:
+                continue
+            for dim, label, weight, polarity, lo, hi in mappings:
+                if dim != dimension or label not in cands:
+                    continue
+                span = (hi - lo) or 1.0
+                strength = max(0.0, min(1.0, (ge.value - lo) / span))
+                if strength <= 0.0:
+                    continue
+                contribution = weight * strength * ge.mass * polarity
+                sign = "" if polarity > 0 else "_refutes"
+                cands[label].append(Evidence(
+                    signal=f"graph_{kind}{sign}",
+                    detail=ge.detail,
+                    weight=weight, strength=strength, mass=ge.mass,
+                    contribution=contribution,
+                ))
+
+    # ── conflict resolution + confidence ──────────────────────────────────────
+    def _resolve(self, dimension: str, raw: dict[str, list[Evidence]], f: _Features) -> DimensionResult:
+        candidates = [
+            ArchetypeCandidate(label=lbl, score=sum(e.contribution for e in evs), evidence=evs)
+            for lbl, evs in raw.items()
+        ]
+        candidates.sort(key=lambda c: c.score, reverse=True)
+        top = candidates[0] if candidates else None
+        runner = candidates[1] if len(candidates) > 1 else None
+        # Floor: do not declare a winner on negligible evidence (e.g. a 0.3% plugin
+        # dir "winning" architectural_style). Below it, the dimension is undetermined.
+        primary = top.label if top and top.score >= _MIN_PRIMARY_SCORE else None
+
+        # Confidence from margin between top-2 + whether mass/graph evidence backs it
+        # (vs name-only), plus penalties for missing richer signals.
+        confidence = "low"
+        if top and top.score > 0:
+            margin = top.score - (runner.score if runner else 0.0)
+            rel_margin = margin / top.score if top.score else 0.0
+            mass_backed = any(e.mass < 1.0 and e.contribution > 0 for e in top.evidence)
+            # Graph-backed = the WINNING conclusion is supported by real topology,
+            # not merely that a graph exists. Ties "high" confidence to structural
+            # evidence for THIS label (ADR-0003 acceptance criterion).
+            graph_backed = any(
+                e.signal.startswith("graph_") and e.contribution > 0 for e in top.evidence
+            )
+            # Elevated confidence also requires a non-marginal absolute score: a
+            # winner barely above the evidence floor is "undetermined-ish" and must
+            # not read as high/medium however lonely it is.
+            confident_enough = top.score >= _MIN_CONFIDENT_SCORE
+            if confident_enough and rel_margin >= 0.4 and mass_backed and graph_backed:
+                confidence = "high"
+            elif confident_enough and rel_margin >= 0.25 and mass_backed:
+                confidence = "medium"
+            else:
+                confidence = "low"
+
+        if primary is None:
+            explanation = (
+                f"No dominant {dimension.replace('_', ' ')}: best candidate "
+                f"'{top.label}' ({top.score:.3f}) is below the evidence floor "
+                f"({_MIN_PRIMARY_SCORE}) — undetermined."
+            ) if top else f"No evidence for {dimension.replace('_', ' ')}."
+            confidence = "low" if not top or top.score == 0 else confidence
+        else:
+            explanation = self._explain(dimension, top, runner)
+        return DimensionResult(dimension, primary, confidence, candidates, explanation)
+
+    def _explain(self, dimension: str, top: Optional[ArchetypeCandidate],
+                 runner: Optional[ArchetypeCandidate]) -> str:
+        if top is None or top.score <= 0:
+            return f"No archetype evidence for {dimension}."
+        parts = [f"{e.signal}(+{e.contribution:.3f})"
+                 for e in sorted(top.evidence, key=lambda e: e.contribution, reverse=True)
+                 if e.contribution > 0][:3]
+        base = f"'{top.label}' wins ({top.score:.3f}) on {', '.join(parts) or 'weak signals'}"
+        if runner and runner.score > 0:
+            base += f"; over '{runner.label}' ({runner.score:.3f})"
+        return base + "."
+
+    # ── helpers ───────────────────────────────────────────────────────────────
+    @staticmethod
+    def _module_of(path: str) -> str:
+        norm = path.replace("\\", "/")
+        idx = norm.find("/src/")
+        if idx > 0:
+            return norm[:idx]
+        head, _, tail = norm.partition("/")
+        return head if tail else ""
+
+    @staticmethod
+    def _endpoint_count(root: Optional[Path]) -> int:
+        if root is None:
+            return 0
+        try:
+            from sourcecode.repository_ir import extract_java_endpoints
+            data = extract_java_endpoints(root)
+            return int(data.get("total", len(data.get("endpoints", []))))
+        except Exception:
+            return 0

sourcecode/architecture_summary.py

@@ -31,6 +31,18 @@ _CORE_DETECTION_MODULES = {"scanner", "detectors", "classifier", "workspace"}
 # headline to a qualified, consistent phrasing instead of overclaiming.
 _MIN_REST_ENDPOINTS_FOR_LABEL = 5
 
+# BUG (neo4j field test): endpoint COUNT alone cannot separate "an API server"
+# from "a large engine/platform that also exposes a few HTTP endpoints". A graph
+# database with ~14 JAX-RS endpoints across 5,600+ source files is not a "REST
+# API" — yet it clears the count threshold above and gets mis-headlined, the exact
+# thing a reader sees in the first line. Add a proportionality guard: on a large
+# JVM codebase, only keep the "REST API" headline when the HTTP surface is
+# architecturally significant relative to code size (at least one endpoint per
+# _API_DOMINANCE_FILES_PER_ENDPOINT source files). Below that density the web
+# layer is a minor component, not the architecture.
+_LARGE_JVM_SOURCE_FILES = 400
+_API_DOMINANCE_FILES_PER_ENDPOINT = 100
+
 _OPTIONAL_LABEL_MAP: dict[str, str] = {
     "DependencyAnalyzer": "dependencias",
     "GraphAnalyzer": "grafo de módulos",
@@ -207,6 +219,21 @@ class ArchitectureSummarizer:
                         f"(HTTP framework present; only {total} endpoint{plural} "
                         f"detected — see `endpoints`)."
                     )
+                # Proportionality guard: a large JVM codebase whose HTTP surface is
+                # a rounding error is an engine/platform exposing an API, not an
+                # "API" project. Endpoint count already cleared the threshold above,
+                # so lead with what the system IS instead of overclaiming "REST API".
+                n_src = self._jvm_source_file_count(sm)
+                if (
+                    n_src >= _LARGE_JVM_SOURCE_FILES
+                    and total * _API_DOMINANCE_FILES_PER_ENDPOINT < n_src
+                ):
+                    plural = "s" if total != 1 else ""
+                    return (
+                        f"{stack_label} multi-module codebase{fw_str} — large "
+                        f"system ({n_src} source files) with a minor HTTP surface "
+                        f"({total} endpoint{plural}); not API-first. See `endpoints`."
+                    )
             return f"{stack_label} {runtime.lower()}{fw_str}."
         return f"{stack_label} project{fw_str}."
 
@@ -228,6 +255,20 @@ class ArchitectureSummarizer:
         self._endpoint_support_cache = (total, high)
         return self._endpoint_support_cache
 
+    def _jvm_source_file_count(self, sm: SourceMap) -> int:
+        """Count JVM source files in the scanned tree (excludes tooling paths).
+        Used by the proportionality guard to tell a large engine/platform apart
+        from an API-first project. A truncated tree only undercounts, which makes
+        the guard more conservative (less likely to degrade a real API)."""
+        exts = (".java", ".kt", ".kts", ".scala")
+        try:
+            return sum(
+                1 for p in flatten_file_tree(sm.file_tree)
+                if p.endswith(exts) and not self._is_tooling_path(p)
+            )
+        except Exception:
+            return 0
+
     def _qualify_web_pattern(self, arch: Any, arch_line: str, sm: SourceMap) -> str:
         """BUG #1 (Jenkins field test): the "mvc" pattern is a directory-name
         heuristic (dirs matching controller/model/view keywords). On a Java/Kotlin

sourcecode/classifier.py

@@ -34,6 +34,30 @@ _API_FRAMEWORKS = {
 _WEB_FRAMEWORKS = {"Next.js", "React", "Vue", "Svelte", "Vite", "Flutter", "Phoenix", "Angular"}
 _CLI_FRAMEWORKS = {"Typer", "Cobra", "Clap"}
 _API_STACKS = {"python", "go", "java", "php", "ruby", "dotnet", "kotlin", "scala"}
+
+# Center-of-gravity gate for the "api" decision (neo4j field test).
+# The historical rule was pure PRESENCE: any API framework on the classpath →
+# project_type="api". That mislabels a large engine/platform that merely exposes a
+# small HTTP surface. Two evidence paths defeat the existing adapter-localization
+# guard because they are repo-wide (no locatable minority module):
+#   * a jakarta.ws.rs / javax.ws.rs-api coordinate pinned in a BOM/parent pom's
+#     <dependencyManagement> (a version pin, not usage), and
+#   * a source-annotation "Jakarta EE" marker synthesized from @Path resources
+#     (detected_via carries no file path).
+# So on a repo large enough to HAVE a distinct center of gravity, require the API
+# surface to occupy a real share of the code (or the dominant module) before we
+# headline the whole system as an API. Small/single-module repos keep presence-based
+# behavior (a real API framework there defines the project — e.g. the Eureka field
+# test). JVM-only: this is where the false positive lives; other stacks are untouched.
+_JVM_STACKS = {"java", "kotlin", "scala", "groovy"}
+_JVM_CODE_EXTS = (".java", ".kt", ".kts", ".scala", ".groovy")
+_API_DOMINANCE_MIN_FILES = 300
+_API_PRIMARY_SHARE = 0.15
+_API_SURFACE_ENTRY_KINDS = frozenset({
+    "jax_rs_controller", "jax_rs_provider",
+    "rest_controller", "mvc_controller", "controller", "web", "server",
+})
+
 ConfidenceLevel = Literal["high", "medium", "low"]
 
 
@@ -143,7 +167,18 @@ class TypeClassifier:
             return "web_mvc"
 
         if framework_names & _API_FRAMEWORKS:
-            return "api"
+            if not (stack_names & _JVM_STACKS) or self._api_is_center_of_gravity(
+                file_tree, stacks, entry_points
+            ):
+                return "api"
+            # A JVM API framework is present but is NOT the repo's center of gravity.
+            # It survived adapter-localization only because its evidence is repo-wide
+            # (a BOM/parent-pom version pin, or a source-annotation marker with no
+            # locatable minority module). Do not headline the whole system as an API —
+            # the framework stays in stacks[].frameworks as a secondary capability and
+            # the primary type falls back to the structural center of gravity.
+            if self._is_multi_module(file_tree):
+                return "library"
 
         # All app-defining frameworks were localized to optional adapter submodules
         # (multi-module library with per-framework integrations) — report library,
@@ -263,6 +298,64 @@ class TypeClassifier:
                 localized.add(fw_name)
         return localized
 
+    def _api_is_center_of_gravity(
+        self,
+        file_tree: dict[str, Any],
+        stacks: Sequence[StackDetection],
+        entry_points: Sequence[EntryPoint],
+    ) -> bool:
+        """True when an API/web framework reflects the repo's center of gravity, not
+        merely its presence. Small or single-module JVM repos: a present API framework
+        defines the project (keeps the historical behavior). Large multi-module repos:
+        the HTTP surface must live in the dominant module or occupy at least
+        ``_API_PRIMARY_SHARE`` of the JVM source — otherwise it is a minor capability
+        of an engine/platform/library, not the primary type."""
+        counts: dict[str, int] = {}
+        for p in flatten_file_tree(file_tree):
+            if p.endswith(_JVM_CODE_EXTS):
+                mod = self._module_of(p)
+                counts[mod] = counts.get(mod, 0) + 1
+        counts.pop("", None)
+        total = sum(counts.values())
+        # Too small, or a single module, to reason about a center of gravity.
+        if total < _API_DOMINANCE_MIN_FILES or len(counts) < 2:
+            return True
+        dominant = max(counts, key=lambda m: counts[m])
+        api_modules = self._api_surface_modules(stacks, entry_points)
+        if not api_modules:
+            # API framework known only repo-wide (BOM version pin / annotation marker)
+            # with no source-located HTTP surface in a large multi-module system.
+            return False
+        if dominant in api_modules:
+            return True
+        api_files = sum(counts.get(m, 0) for m in api_modules)
+        return (api_files / total) >= _API_PRIMARY_SHARE
+
+    def _api_surface_modules(
+        self,
+        stacks: Sequence[StackDetection],
+        entry_points: Sequence[EntryPoint],
+    ) -> set[str]:
+        """Modules that actually host an HTTP/REST surface: derived from API entry
+        points (controllers / JAX-RS resources) and from API-framework file evidence.
+        Repo-wide manifest evidence (no path) contributes no module, by design."""
+        modules: set[str] = set()
+        for ep in entry_points:
+            if getattr(ep, "kind", None) in _API_SURFACE_ENTRY_KINDS and ep.path:
+                modules.add(self._module_of(ep.path))
+        for stack in stacks:
+            for fw in stack.frameworks:
+                if fw.name not in _API_FRAMEWORKS:
+                    continue
+                for ev in fw.detected_via:
+                    if ev.startswith("manifest:"):
+                        continue
+                    m = self._EVIDENCE_PATH_RE.search(ev)
+                    if m:
+                        modules.add(self._module_of(m.group(1).strip()))
+        modules.discard("")
+        return modules
+
     def _is_fullstack(self, stacks: Sequence[StackDetection]) -> bool:
         has_web = False
         has_api = False

sourcecode/cli.py

@@ -246,6 +246,8 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "rename-class",
         # Large file semantic chunking (BLOCKER-B)
         "chunk-file",
+        # Experimental evidence-based archetype (parallel to legacy)
+        "archetype",
     }
 )
 
@@ -6422,6 +6424,77 @@ def config_cmd() -> None:
 
 # ── cold-start (RIS bootstrap for external MCP and agents) ───────────────────
 
+@app.command("archetype")
+def archetype_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write output to a file instead of stdout."
+    ),
+) -> None:
+    """[EXPERIMENTAL] Evidence-based architectural archetype (parallel to legacy).
+
+    Emits a 4-dimension archetype analysis — software_archetype, architectural_style,
+    deployment_shape, primary_interface — each with scored candidates, the evidence
+    (weighted by code mass), a confidence level, and a human explanation.
+
+    This runs ALONGSIDE the legacy architecture pattern and does NOT change any
+    report wording. It exists to validate the new model against the old one across
+    many repositories before any cutover.
+    """
+    import json as _json
+    from sourcecode.adaptive_scanner import AdaptiveScanner
+    from sourcecode.repo_classifier import RepoClassifier
+    from sourcecode.detectors import ProjectDetector, build_default_detectors
+    from sourcecode.schema import SourceMap
+    from sourcecode.tree_utils import flatten_file_tree
+    from sourcecode.archetype import ArchetypeClassifier
+
+    target = Path(path).resolve()
+    topology = RepoClassifier().classify(target)
+    scanner = AdaptiveScanner(target, topology=topology, base_depth=12)
+    file_tree = scanner.scan_tree()
+    manifests = scanner.find_manifests()
+
+    detector = ProjectDetector(build_default_detectors())
+    stacks, entry_points, _ = detector.detect(target, file_tree, manifests)
+    stacks, project_type = detector.classify_results(file_tree, stacks, entry_points)
+
+    sm = SourceMap(
+        file_tree=file_tree, stacks=stacks,
+        project_type=project_type, entry_points=entry_points,
+    )
+    sm.file_paths = [p.replace("\\", "/") for p in flatten_file_tree(file_tree)]
+    _java = next((s for s in stacks if s.stack == "java"), None)
+    if _java is not None:
+        sm.packaging = getattr(_java, "packaging", None)
+
+    # Module graph as a first-class Evidence Provider (ADR-0003 step 2). Built
+    # here so archetype can consume topological evidence. Bounded + best-effort:
+    # on very large trees or any failure it degrades to None (name-mass-only),
+    # which is exactly the pre-provider behaviour — no regression.
+    module_graph = None
+    try:
+        from sourcecode.graph_analyzer import GraphAnalyzer
+        module_graph = GraphAnalyzer(max_nodes=1200, max_edges=4000).analyze(
+            target, file_tree, detail="full", entry_points=entry_points,
+        )
+        if module_graph is not None:
+            sm.module_graph = module_graph
+            sm.module_graph_summary = module_graph.summary
+    except Exception:
+        module_graph = None
+
+    analysis = ArchetypeClassifier().analyze(sm, root=target, module_graph=module_graph)
+    result = analysis.to_dict()
+    result["legacy_project_type"] = project_type  # side-by-side with legacy for validation
+    out = _json.dumps(result, indent=2, ensure_ascii=False)
+    if output_path:
+        _safe_write_file(output_path, out)
+        typer.echo(f"Archetype analysis written to {output_path}")
+    else:
+        typer.echo(out)
+
+
 @app.command("cold-start")
 def cold_start_cmd(
     path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),

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.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.2.0
+Version: 2.3.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.3.0.dist-info}/RECORD

@@ -1,15 +1,16 @@
-sourcecode/__init__.py,sha256=QOkIfC7KA2tM2ix9_wUgS6fHiERh2v_TTNhjw8RBb1o,308
+sourcecode/__init__.py,sha256=_9_i7ziVcM1wLhG9oULnIMnZhX9H1T1qmnmsiNwXBmg,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=rK4umQmgajbQwuwmhhm6q898X-xaniHuRpXbUnW1WUk,296904
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/confidence_analyzer.py,sha256=_jckZSxksV-OU38vbkxfVNBnWCtlCq8Vwfg23x1uspA,19054
 sourcecode/context_graph.py,sha256=8MVDu06bPhvRDTgUqWEvRME2fOw34bFLf4OUILZd13I,43527
@@ -34,6 +35,7 @@ sourcecode/format_contract.py,sha256=1cTNqwP8geA2hbQoBHUPgX3_vSh3l8guJT_jmgEnFF8
 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 +117,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.3.0.dist-info/METADATA,sha256=sOmWl4PHteHOjBgUxeKpVh6H6Hc2Yo-Zyrk3c62z1CE,10837
+sourcecode-2.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-2.3.0.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
+sourcecode-2.3.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-2.3.0.dist-info/RECORD,,