sourcecode 2.5.3__py3-none-any.whl → 2.5.5__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.5"

sourcecode/architecture_analyzer.py

@@ -4,6 +4,8 @@ import re
 from pathlib import Path
 from typing import Literal, Optional
 
+from sourcecode.reconciliation import incoherent_layers
+
 from sourcecode.schema import (
     ArchitectureAnalysis,
     ArchitectureDomain,
@@ -31,7 +33,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 +65,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
 
@@ -126,8 +141,14 @@ LAYER_PATTERNS: dict[str, dict[str, list[str]]] = {
         "application":    ["application", "usecases", "usecase"],
         "infrastructure": ["infrastructure", "infra", "adapters", "persistence"],
     },
+    # P1-D residue (found by measurement, 2026-07-16): "core" belongs with
+    # "api"/"store"/"db" — it names a module's importance ("the main module"),
+    # never an onion/hexagonal DOMAIN layer, and nearly every large JVM repo has
+    # one. With it, keycloak's `core/` (623 Java files) + a
+    # `representations/adapters/config` package read "Onion Architecture with
+    # domain, adapters layers". Kept are the names that state their role.
     "onion": {
-        "domain":      ["domain", "core"],
+        "domain":      ["domain"],
         "application": ["application", "usecases"],
         "ports":       ["ports", "interfaces"],
         "adapters":    ["adapters", "secondary"],
@@ -137,16 +158,30 @@ 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"],
         "adapter": ["adapter", "adapters"],
-        "domain":  ["domain", "core", "model", "models"],
+        "domain":  ["domain", "model", "models"],  # "core" dropped — see onion
     },
     "monorepo": {
         "apps":     ["apps", "applications"],
@@ -154,7 +189,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"],
     },
 }
 
@@ -165,8 +204,37 @@ LAYER_PATTERNS: dict[str, dict[str, list[str]]] = {
 # it; without it the pattern falls through to layered / a weaker match.
 _PATTERN_REQUIRED_KEYS: dict[str, frozenset[str]] = {
     "mvc": frozenset({"view"}),
+    # Same principle as MVC/view — a pattern must show its DEFINING trait, not
+    # just any two of its layers. Hexagonal is literally "Ports and Adapters":
+    # a `models/` package next to an `adapters/` package is not one, and that
+    # pair alone was enough to label keycloak "Hexagonal Architecture". Onion's
+    # defining trait is the domain at the centre.
+    "hexagonal": frozenset({"port", "adapter"}),
+    "onion": frozenset({"domain"}),
 }
 
+# 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 +623,62 @@ 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
+
+            # SIM-3: a layer must belong to the same PROGRAM as the rest of the
+            # claim. Directory names are language-blind, so on a polyglot
+            # monorepo one pattern was assembled across two subsystems: keycloak
+            # read "MVC with controller, model, view layers" where `view` was a
+            # React SPA (87 .tsx, zero Java) sitting beside a 1088-file Java
+            # `model`. Mass cannot catch this — the SPA has genuine mass. The
+            # reconciliation rule drops layers owned by a different runtime;
+            # template/asset-only layers are untouched, so a real Spring-MVC
+            # `templates/` view survives.
+            for _bad in incoherent_layers(
+                pattern_name,
+                {k: [source_paths[i] for i in v] for k, v in layer_files.items()},
+                source_paths,
+            ):
+                matched.pop(_bad, None)
+                layer_files.pop(_bad, None)
+
             # 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 +690,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 +817,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 +837,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: