sourcecode 2.5.3__py3-none-any.whl → 2.5.4__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.5.3"
+__version__ = "2.5.4"

sourcecode/architecture_analyzer.py

@@ -31,7 +31,14 @@ _TOOLING_PREFIXES = (
     "dist/",
     "build/",
 )
-_SRC_TRANSPARENT = {"src", "lib", "app", "pkg"}
+# Structural wrappers to walk THROUGH when looking for a module: they are build
+# layout, never a module name. "main" and the language dirs come from the Maven /
+# Gradle source-set convention (src/main/java/...) — without them a Maven repo with
+# no other signal offers "main" as one of its modules (P1-D, spring-petclinic).
+_SRC_TRANSPARENT = {
+    "src", "lib", "app", "pkg",
+    "main", "java", "kotlin", "scala", "groovy",
+}
 _CODE_EXTENSIONS = {
     ".py", ".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs",
     ".go", ".java", ".kt", ".rs", ".rb",
@@ -56,7 +63,13 @@ _BENCHMARK_DIRS: frozenset[str] = frozenset({
     "sandbox",
 })
 _DOCS_DIRS: frozenset[str] = frozenset({"docs", "doc", "documentation", "wiki"})
-_TOOLING_DIRS: frozenset[str] = frozenset({"scripts", "script", "tools", "tool", "ci"})
+# Tooling/CI config, never runtime architecture. The dot-dirs are conventional: a
+# leading dot marks tooling config across ecosystems, and without them `.github`
+# was offered as a neo4j "module" alongside community/ and packaging/ (P1-D).
+_TOOLING_DIRS: frozenset[str] = frozenset({
+    "scripts", "script", "tools", "tool", "ci",
+    ".github", ".circleci", ".mvn", ".idea", ".vscode",
+})
 # All dirs that are not part of the runtime source architecture
 _NON_SOURCE_DIRS: frozenset[str] = _TEST_DIRS | _BENCHMARK_DIRS | _DOCS_DIRS | _TOOLING_DIRS | _ASSET_DIRS
 
@@ -137,11 +150,25 @@ LAYER_PATTERNS: dict[str, dict[str, list[str]]] = {
         "model":      ["model", "models", "entity", "entities", "domain"],
         "view":       ["views", "templates", "pages", "components"],
     },
+    # P1-D: a keyword may only name a layer it actually ATTESTS. The dropped
+    # synonyms below are naming conventions that say nothing about a layer role,
+    # and they were the engine of the fabricated claims — mass alone cannot filter
+    # them out, because in the repos they mislabel they are large:
+    #   * "api" — a Java `foo/api/` package is a public API surface (interfaces),
+    #     not an HTTP controller layer. It manufactured neo4j's controller layer
+    #     (925 files, 16.5%, and neo4j has no controller dir at all) and openmrs's
+    #     (821 files, 94.8% — that is `org/openmrs/api/`, the service API).
+    #   * "store"/"storage" — a storage ENGINE is not a repository/DAO layer
+    #     (neo4j's `store` is exactly that).
+    #   * "db"/"database" — a database package is not an infrastructure layer.
+    # Kept are the names that state their role: controller/handlers/routes/endpoints,
+    # repository/repo/dao, infra/infrastructure/persistence. Broadleaf keeps all four
+    # of its layers on those alone.
     "layered": {
-        "controller":     ["controller", "controllers", "api", "routes", "handlers", "endpoints"],
+        "controller":     ["controller", "controllers", "routes", "handlers", "endpoints"],
         "service":        ["service", "services", "usecase", "usecases", "application"],
-        "repository":     ["repository", "repositories", "repo", "repos", "store", "storage", "dao"],
-        "infrastructure": ["infra", "infrastructure", "persistence", "db", "database"],
+        "repository":     ["repository", "repositories", "repo", "repos", "dao"],
+        "infrastructure": ["infra", "infrastructure", "persistence"],
     },
     "hexagonal": {
         "port":    ["port", "ports", "interface", "interfaces"],
@@ -154,7 +181,11 @@ LAYER_PATTERNS: dict[str, dict[str, list[str]]] = {
     },
     "fullstack": {
         "frontend": ["frontend", "client", "web", "ui", "pages", "components", "app"],
-        "backend":  ["backend", "server", "api", "services"],
+        # P1-D: "api" dropped — a `foo/api/` package is a public API surface, not
+        # evidence of a backend TIER. With it, openmrs (94.8% `org/openmrs/api/`)
+        # and jobrunr fell straight from a fabricated "layered" into a fabricated
+        # "fullstack" instead. Same conflation, same fix.
+        "backend":  ["backend", "server", "services"],
     },
 }
 
@@ -167,6 +198,28 @@ _PATTERN_REQUIRED_KEYS: dict[str, frozenset[str]] = {
     "mvc": frozenset({"view"}),
 }
 
+# Minimum share of source files a matched layer must hold to count as a LAYER
+# (P1-D, neo4j field test). Matching was pure name PRESENCE over the set of every
+# directory name in the repo, so one incidental dir minted a whole layer: neo4j — a
+# graph engine with no controller, repository or infrastructure directory anywhere —
+# reported "Layered Architecture with controller, service, repository, infrastructure
+# layers", synthesized from `api`, `service` (7 files), `store`/`storage` and
+# `database`. Presence does not scale: the bigger the repo, the likelier some
+# directory somewhere matches a keyword, so large systems were the most confidently
+# mislabelled.
+#
+# A layer is a place where a real share of the code lives. Same reasoning the
+# archetype engine already applies to the same question ("a 0.3% `api/` dir does not
+# manufacture a controller layer", _architectural_style).
+#
+# Calibrated against the field-test repos rather than copied from archetype's 5%,
+# which scores a web+service+repository triplet and is too coarse to erase a single
+# layer with: Broadleaf's controller layer is a real 4.68% (it has a literal
+# `controller/` dir) and 5% deleted it. The phantoms all sit an order of magnitude
+# lower — jenkins 0.72% (`handlers`, and it has no HTTP controllers at all), ofbiz
+# 0.19%, neo4j's service layer 7 files at 0.12% — so 1% separates them cleanly.
+_LAYER_MIN_SHARE = 0.01
+
 # Higher value = wins when score ties
 _PATTERN_PRIORITY: dict[str, int] = {
     "cqrs":               8,
@@ -555,24 +608,44 @@ class ArchitectureAnalyzer:
         if not source_paths:
             return "unknown", []
 
-        dir_names: set[str] = set()
-        for p in source_paths:
-            parts = p.replace("\\", "/").split("/")
-            for part in parts[:-1]:
-                dir_names.add(part.lower())
+        # Index each directory NAME to the source files under it, so a matched layer
+        # can be weighed by the code it actually holds instead of counted as present
+        # (P1-D). Built once; every pattern below reads it.
+        dir_files: dict[str, set[int]] = {}
+        for i, p in enumerate(source_paths):
+            for part in p.replace("\\", "/").split("/")[:-1]:
+                dir_files.setdefault(part.lower(), set()).add(i)
+        dir_names: set[str] = set(dir_files)
+        total_files = len(source_paths)
+
+        def _layer_files(matched_dirs: list[str]) -> set[int]:
+            files: set[int] = set()
+            for d in matched_dirs:
+                files |= dir_files.get(d, set())
+            return files
 
         # 1. Classical keyword-based pattern matching
         best_pattern = ""
         best_score = 0
         best_priority = -1
         best_matched: dict[str, list[str]] = {}
+        best_layer_files: dict[str, set[int]] = {}
 
         for pattern_name, layer_keys in LAYER_PATTERNS.items():
             matched: dict[str, list[str]] = {}
+            layer_files: dict[str, set[int]] = {}
             for layer_key, keywords in layer_keys.items():
                 matched_dirs = [d for d in dir_names if d in keywords]
-                if matched_dirs:
-                    matched[layer_key] = matched_dirs
+                if not matched_dirs:
+                    continue
+                # P1-D: a layer is where a real share of the code lives. An incidental
+                # directory that merely matches a keyword is not one — neo4j's 7-file
+                # `service/` dir (0.12%) never made it a service layer.
+                files = _layer_files(matched_dirs)
+                if total_files and len(files) / total_files < _LAYER_MIN_SHARE:
+                    continue
+                matched[layer_key] = matched_dirs
+                layer_files[layer_key] = files
             # A pattern with unmet required keys cannot qualify (e.g. mvc needs a view).
             required = _PATTERN_REQUIRED_KEYS.get(pattern_name)
             if required and not required.issubset(matched.keys()):
@@ -584,18 +657,13 @@ class ArchitectureAnalyzer:
                 best_priority = priority
                 best_pattern = pattern_name
                 best_matched = matched
+                best_layer_files = layer_files
 
         if best_score >= 2:
             layer_confidence: Literal["high", "medium", "low"] = "medium" if best_score >= 3 else "low"
             layers: list[ArchitectureLayer] = []
             for layer_key, matched_dirs in best_matched.items():
-                matched_files = [
-                    p for p in source_paths
-                    if any(
-                        seg.lower() in matched_dirs
-                        for seg in p.replace("\\", "/").split("/")[:-1]
-                    )
-                ]
+                matched_files = [source_paths[i] for i in sorted(best_layer_files[layer_key])]
                 layers.append(ArchitectureLayer(
                     name=layer_key,
                     pattern=best_pattern,
@@ -716,6 +784,14 @@ class ArchitectureAnalyzer:
         - orchestration: cli.py, main.py, *_handler.py, *_controller.py
         - processing:    *_analyzer.py, *_processor.py, *_parser.py, *_detector.py, *_scanner.py
         - data:          schema.py, model.py, *_repository.py, *_serializer.py, config.py, …
+
+        P1-D: weighed by share, like the directory-name patterns. Matching on file
+        stems alone let a handful of incidentally-named files mint logical layers:
+        neo4j's "orchestration, processing, data" rested on ~6 files out of 5616
+        (0.05% each) — one `Main.java`, a `Config.java`, a `Serializer.java`, and two
+        `Server.java` that are model classes under `topology/model/`, "orchestration"
+        only because of their stem. Three layers named off 0.1% of a codebase is a
+        description of nothing.
         """
         layer_files: dict[str, list[str]] = {"orchestration": [], "processing": [], "data": []}
         for p in paths:
@@ -728,7 +804,11 @@ class ArchitectureAnalyzer:
                     layer_files[layer].append(p)
                     break
 
-        non_empty = {k: v for k, v in layer_files.items() if v}
+        total = len(paths)
+        non_empty = {
+            k: v for k, v in layer_files.items()
+            if v and (not total or len(v) / total >= _LAYER_MIN_SHARE)
+        }
         if len(non_empty) >= 2:
             return "layered", [
                 ArchitectureLayer(name=k, pattern="layered", files=v, confidence="low")

sourcecode/classifier.py

@@ -25,7 +25,9 @@ _API_FRAMEWORKS = {
     "Micronaut",
     "Vert.x",
     "Quarkus",
-    "Jakarta EE",   # JAX-RS / Jakarta REST — pure JAX-RS projects must not fall to "unknown"
+    "JAX-RS",       # Jakarta REST — pure JAX-RS projects must not fall to "unknown"
+    "Jakarta EE",   # platform umbrella artifact (jakartaee-api); implies a web profile
+    "Java EE",      # javax.* umbrella artifact (javaee-api)
     "Laravel",
     "Symfony",
     "Ktor",
@@ -42,7 +44,7 @@ _API_STACKS = {"python", "go", "java", "php", "ruby", "dotnet", "kotlin", "scala
 # 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
+#   * a source-annotation "JAX-RS" 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

sourcecode/detectors/java.py

@@ -185,17 +185,22 @@ class JavaDetector(AbstractDetector):
         # build.gradle files are not scanned at all — yet it ships 18 @Path resource
         # classes. Without this the headline read "Java library / package" while the
         # endpoints command listed a full JAX-RS API. When the annotation scan found
-        # JAX-RS entry points and no Jakarta-EE framework was inferred from the
+        # JAX-RS entry points and no JAX-RS framework was inferred from the
         # manifest, surface it so the stack (and project_type) reflect the REST API
         # the endpoints already prove. Structural (VAI): reasons from the JAX-RS
         # entry points found in source, not from a vendor dependency-name allowlist.
         # detected_via carries no path form, so it is treated as repo-wide evidence
         # (never localized to an adapter submodule).
-        if not any(f.name == "Jakarta EE" for f in frameworks) and any(
+        # P1-C: @Path/@GET resources prove JAX-RS — the one spec they belong to —
+        # and nothing about the rest of the Jakarta EE platform. Eureka (Jersey 1.x
+        # + Guice, no EE container) read "Java rest api using Jakarta EE" on this
+        # path alone. The API framing this exists to deliver is unchanged; only the
+        # claim narrows to what the annotations attest.
+        if not any(f.name == "JAX-RS" for f in frameworks) and any(
             ep.kind in ("jax_rs_controller", "jax_rs_provider") for ep in entry_points
         ):
             frameworks.append(FrameworkDetection(
-                name="Jakarta EE", source="annotation", detected_via=["jax_rs_endpoints"],
+                name="JAX-RS", source="annotation", detected_via=["jax_rs_endpoints"],
             ))
 
         transactional_classes = self._collect_transactional_classes(context, all_paths)
@@ -436,15 +441,27 @@ class JavaDetector(AbstractDetector):
             frameworks.append(FrameworkDetection(name="Micronaut", source=source))
         if "io.vertx" in text or "vertx" in text:
             frameworks.append(FrameworkDetection(name="Vert.x", source=source))
+        # P1-C: name the spec that is actually evidenced, not the platform that
+        # contains it. "Jakarta EE" is a platform of ~40 specs; a JAX-RS coordinate
+        # attests ONE of them. Claiming the platform from it told neo4j (a graph
+        # engine with an HTTP API) and jobrunr (a job library with RESTEasy on the
+        # test path) that they were Jakarta EE applications.
+        #
+        # Only an aggregate platform artifact — the coordinate that IS the platform
+        # umbrella — attests the platform itself. Counting distinct jakarta.* specs
+        # instead would misfire: Spring Boot 3 pulls jakarta.servlet, .validation and
+        # .persistence transitively (Broadleaf ships the first two), so any threshold
+        # low enough to catch a real EE app relabels every Boot 3 app.
+        if "javaee-api" in text:            # javax.* umbrella (pre-EE 9)
+            frameworks.append(FrameworkDetection(name="Java EE", source=source))
+        if "jakartaee-api" in text or "jakarta.platform" in text or "jakarta.ee" in text:
+            frameworks.append(FrameworkDetection(name="Jakarta EE", source=source))
         if (
-            "jakarta.ee" in text
-            or "javax.ws.rs-api" in text   # JAX-RS 2.x spec; excludes jsr311-api (1.x API-only jar)
-            or "jakarta.ws.rs" in text      # Jakarta namespace (EE 9+)
-            or "javaee-api" in text         # full Java EE platform
-            or "jakartaee-api" in text      # full Jakarta EE platform
-            or "resteasy" in text           # RESTEasy (JBoss JAX-RS impl)
+            "javax.ws.rs-api" in text   # JAX-RS 2.x spec; excludes jsr311-api (1.x API-only jar)
+            or "jakarta.ws.rs" in text  # Jakarta namespace (EE 9+)
+            or "resteasy" in text       # RESTEasy — a JAX-RS implementation
         ):
-            frameworks.append(FrameworkDetection(name="Jakarta EE", source=source))
+            frameworks.append(FrameworkDetection(name="JAX-RS", source=source))
         if "mybatis" in text:
             frameworks.append(FrameworkDetection(name="MyBatis", source=source))
         if "thymeleaf" in text:

sourcecode/reconciliation.py

@@ -0,0 +1,201 @@
+"""reconciliation.py — Evidence Reconciliation Layer (F-1).
+
+Cross-validates independent evidence views BEFORE a result is narrated:
+
+    evidence views  →  consistency rules  →  positively-detected contradictions
+
+Each analyzer (call graph, endpoint index, …) is treated as an evidence
+provider whose view may be incomplete. A reconciliation rule fires only on a
+*provable* self-contradiction between two views — never on absence alone —
+and its output downgrades confidence and names the gap instead of letting the
+narrative assert an answer the evidence does not support.
+
+Rules are pure functions over frozensets of symbols: no I/O, no parsing, no
+framework-name branching (annotation tables come from the open-standard
+declarative sets in repository_ir — VAI-safe). New rules append to the
+registry of the relevant query surface; consumers surface each finding as a
+blind spot + warning.
+
+Rule registry (impact queries):
+    endpoint_coverage — a class in the call chain declares HTTP handler
+        methods (Spring MVC / JAX-RS verb annotations) but the endpoint index
+        modeled NO route for it. The call graph and the endpoint index are
+        contradicting each other; `endpoints_affected` under-reports real HTTP
+        exposure (e.g. JAX-RS sub-resource locator chains the route extractor
+        cannot compose). First shipped instance of F-1 (SIM-2, keycloak
+        simulacro 2026-07-16).
+
+Rule registry (extraction):
+    parse_coverage — a scanned Java file provably declares a type (masked
+        source matches a type-declaration keyword) but symbol extraction
+        produced NOTHING for it. The file inventory and the symbol index are
+        contradicting each other; every symbol in that file is silently
+        invisible to the graph, callers and endpoints (P1-E: legal-Java
+        declarations the regex extractor cannot bind, e.g. `public class\n
+        Name` split across lines, Unicode type identifiers).
+
+Never raises. Empty evidence → no findings.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ReconciliationFinding:
+    """One positively-detected contradiction between two evidence views."""
+    rule: str                 # stable rule id, e.g. "endpoint_coverage"
+    symbols: tuple[str, ...]  # symbols the contradiction is anchored to
+    detail: str               # one-sentence human/agent-readable statement
+
+    def to_dict(self) -> dict:
+        return {
+            "rule": self.rule,
+            "symbols": list(self.symbols),
+            "detail": self.detail,
+        }
+
+
+def http_handler_classes(cir) -> frozenset[str]:
+    """Classes with at least one method carrying an HTTP handler annotation.
+
+    Independent evidence of "this class serves HTTP" derived straight from the
+    per-symbol annotation facts — deliberately NOT derived from the endpoint
+    index, so the two views can be reconciled against each other.
+    """
+    from sourcecode.repository_ir import _ENDPOINT_ANNOTATIONS
+
+    raw = getattr(cir, "_raw_ir", None) or {}
+    nodes = (raw.get("graph") or {}).get("nodes") or []
+    out: set[str] = set()
+    for node in nodes:
+        if not isinstance(node, dict):
+            continue
+        fqn = node.get("fqn") or ""
+        if "#" not in fqn:
+            continue
+        anns = node.get("annotations") or []
+        if any(a in _ENDPOINT_ANNOTATIONS for a in anns):
+            out.add(fqn.split("#", 1)[0])
+    return frozenset(out)
+
+
+def _rule_endpoint_coverage(
+    chain_classes: frozenset[str],
+    handler_classes: frozenset[str],
+    modeled_classes: frozenset[str],
+) -> list[ReconciliationFinding]:
+    """Chain class declares HTTP handlers but the endpoint index has no route for it.
+
+    Fires only on total absence from the index (extractor could not model ANY
+    route for a class that provably declares handlers). A class that IS in the
+    index but contributes only a subset of its endpoints to a query is the
+    intentional method-precision rule, not a contradiction — never flagged.
+    """
+    unmapped = sorted((chain_classes & handler_classes) - modeled_classes)
+    if not unmapped:
+        return []
+    return [
+        ReconciliationFinding(
+            rule="endpoint_coverage",
+            symbols=tuple(unmapped),
+            detail=(
+                f"{len(unmapped)} class(es) in the call chain declare HTTP handler "
+                "methods but the endpoint index modeled no route for them — "
+                "endpoints_affected under-reports real HTTP exposure."
+            ),
+        )
+    ]
+
+
+def reconcile_impact_evidence(
+    *,
+    chain_classes: frozenset[str],
+    handler_classes: frozenset[str],
+    modeled_classes: frozenset[str],
+) -> list[ReconciliationFinding]:
+    """Run all impact-query reconciliation rules. Never raises.
+
+    Args:
+        chain_classes:   classes of every seed + caller in the resolved chain.
+        handler_classes: classes with HTTP-handler annotation evidence
+                         (from http_handler_classes(cir)).
+        modeled_classes: classes the endpoint index has ≥1 route for
+                         (endpoint_index.controller_fqns).
+    """
+    findings: list[ReconciliationFinding] = []
+    try:
+        findings.extend(
+            _rule_endpoint_coverage(chain_classes, handler_classes, modeled_classes)
+        )
+    except Exception:
+        pass
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Extraction-time reconciliation (file inventory × symbol index)
+# ---------------------------------------------------------------------------
+
+# A type-declaration keyword followed by the start of an identifier. Applied to
+# COMMENT/STRING-MASKED source only, so `/* class Ghost */` and "class" inside
+# a string literal never match. `record` is a contextual keyword; requiring a
+# following identifier keeps `record = ...` assignments out, and the rule is
+# only ever consulted for files that yielded zero symbols — where a stray
+# match would still be pointing at real, unmodeled Java.
+_TYPE_DECL_RE = re.compile(r"\b(?:class|interface|enum|record)\s+\w")
+
+
+def declares_java_type(masked_source: str) -> bool:
+    """True if comment/string-masked Java source declares a type.
+
+    The caller masks (repository_ir._mask_java) so this stays a pure text
+    predicate with no parsing dependency.
+    """
+    return bool(_TYPE_DECL_RE.search(masked_source))
+
+
+def _rule_parse_coverage(
+    type_decl_files: frozenset[str],
+    extracted_files: frozenset[str],
+) -> list[ReconciliationFinding]:
+    """File declares a type but symbol extraction produced nothing for it.
+
+    Fires only on total extraction absence for the file — a file that yielded
+    at least one symbol is never flagged (partial member loss is a different,
+    weaker signal this rule does not claim to detect).
+    """
+    lost = sorted(type_decl_files - extracted_files)
+    if not lost:
+        return []
+    return [
+        ReconciliationFinding(
+            rule="parse_coverage",
+            symbols=tuple(lost),
+            detail=(
+                f"{len(lost)} Java file(s) declare a type but produced no symbols — "
+                "their classes and methods are invisible to the graph, callers and "
+                "endpoints."
+            ),
+        )
+    ]
+
+
+def reconcile_extraction_evidence(
+    *,
+    type_decl_files: frozenset[str],
+    extracted_files: frozenset[str],
+) -> list[ReconciliationFinding]:
+    """Run extraction-time reconciliation rules. Never raises.
+
+    Args:
+        type_decl_files: files whose masked source declares a Java type.
+        extracted_files: files symbol extraction produced ≥1 symbol for.
+    """
+    findings: list[ReconciliationFinding] = []
+    try:
+        findings.extend(_rule_parse_coverage(type_decl_files, extracted_files))
+    except Exception:
+        pass
+    return findings