sourcecode 1.67.0__tar.gz → 1.69.0__tar.gz

{sourcecode-1.67.0 → sourcecode-1.69.0}/CHANGELOG.md

@@ -1,5 +1,110 @@
 # Changelog
 
+## [1.69.0] — 2026-06-30
+
+### Fixed — framing & symbol-graph fidelity on a non-framework Java library (JobRunr field test)
+
+A full architectural audit of **JobRunr** (Gradle multi-module, 707 classes, a
+background-job-processing **library** that is framework-agnostic at its core and
+integrates with Quarkus/Micronaut/Spring only through small optional adapter
+modules) surfaced four reproducible defects. Each fix targets the **root cause** so
+it generalizes to any equivalent repo, with new regression coverage across five
+suites.
+
+- **`migrate-check` MIG-011 — false positive on JDK-exported packages (BUG #1).**
+  The rule flagged *any* `sun.*` / `com.sun.*` import as a strongly-encapsulated
+  JDK internal on a pure prefix heuristic. On JobRunr this turned 14 benign
+  `com.sun.net.httpserver.*` imports into 14 `high`/`manual_migration` findings —
+  **100% of an inflated `blocking_count: 14`** on a healthy repo (the GO/NO-GO
+  metric). `com.sun.net.httpserver` is exported **unconditionally** by the
+  `jdk.httpserver` module (public since Java 6, basis of JEP 408) and needs no
+  `--add-exports`/`--add-opens`. MIG-011 now consults an allowlist of
+  unconditionally-exported JDK packages **generated from the running JDK** by
+  `scripts/generate_jdk_exports.py` (`src/sourcecode/jdk_exports.py`), never
+  hand-maintained. Genuinely-internal packages (`sun.misc.Unsafe`,
+  `com.sun.tools.*`, `com.sun.jdi.*`, `com.sun.source.*`) stay `high`.
+  `blocking_count` and `estimated_effort_days` recompute accordingly. JobRunr
+  `blocking_count` 14 → 0.
+- **Phantom symbols extracted from prose (BUG #2).** `modernize`'s
+  `statically_unreferenced` / `framework_dispatched` lists (and the shared symbol
+  graph behind `repo-ir` / `impact` / `export --c4`) contained FQNs that match no
+  real type — e.g. `org.jobrunr.configuration.provides` (from the Javadoc "This
+  class **provides** the entry point") and `…details.instead` (from an exception
+  string "…**instead** of an actual implementation"). The non-annotated fast-path
+  symbol scan ran `(?:class|interface|enum)\s+(\w+)` over **raw source**, tokenizing
+  words inside comments and string literals. It now strips comments + string
+  literals first and requires a capitalized type name, matching the precision of the
+  annotated-file extractor. Fixing the shared parser fixes every downstream command.
+- **`endpoints` — total false negative on imperative router DSLs (BUG #3).** JobRunr
+  exposes 12 live dashboard REST routes via `get("/jobs", handler)` /
+  `post(...)` / `delete(...)` calls; the annotation-only extractor returned **0
+  endpoints** (silently disabling `validation` downstream). A shape-based detector
+  now recognizes router-DSL registrations — an HTTP-verb method whose first argument
+  is a path literal **and** that has a second argument (the trailing comma
+  distinguishes a route from a 1-arg `Map.get`). Reported at `confidence: medium`
+  with `source: router_dsl`. Handles bare (Spark/static-import) and `app.get(...)`
+  (Javalin) forms. JobRunr `endpoints` 0 → 12.
+- **Stack/architecture classification biased to the most-recognizable framework (BUG #4).**
+  JobRunr (19 modules, framework only in 3 small adapters, `core` ≈ 85% of code) was
+  reported as `project_type: "api"` / `frameworks: ["Quarkus"]`. Two root causes:
+  (a) the Gradle detector substring-matched `"quarkus"` inside an **exclusion filter**
+  (`configure(subprojects.findAll { !it.name.contains('quarkus') })`) — framework
+  tokens are now matched only inside genuine dependency/plugin lines; and (b)
+  presence-based typing — a framework confined to a minority adapter module (its
+  dominant source module uses no framework) no longer drives the project type, and a
+  multi-module JVM repo with no defining web/API framework classifies as `library`,
+  never `unknown`. A monolithic framework app is unaffected. `explain` no longer
+  emits the misleading "No stereotype detected — may be a plain class or utility" for
+  a structurally central non-annotated class: it infers a low-confidence stereotype
+  from in-degree, lifecycle methods, and naming (e.g. `BackgroundJobServer` →
+  "Likely server/orchestrator … lifecycle methods detected (start/stop)"). JobRunr
+  `project_type` "api" → "library", `frameworks` `["Quarkus"]` → `[]`.
+
+## [1.68.0] — 2026-06-30
+
+### Fixed — narrative/structured-data parity on non-Spring DI repos (Netflix Eureka field test)
+
+A real audit of **Netflix Eureka** (Gradle multi-module, JAX-RS/Jersey 1.x + Google
+Guice, **no Spring, no Hibernate, no persistence layer**) surfaced six reliability
+defects that share one root cause: **prose that assumed a Spring/Hibernate/persistence
+context even though the same JSON's own structured fields already knew it did not
+apply.** A consumer trusting the narrative over the structured fields would have read
+false conclusions. Guiding principle applied throughout: **a narrative term (Spring,
+Guice, persistence, …) may only appear when the corresponding structured signal
+confirms it.** New regression coverage across four suites.
+
+- **SMTP false positive on a log string (BUG #1).** `export --integrations` reported
+  `kind=smtp` for `logger.warn("Transport initialization failure", e)` — the bare word
+  "Transport" in a log literal. The detector now (a) skips any token matched inside a
+  string literal and (b) gates the JavaMail tokens (`Transport`, `MimeMessage`) on a
+  `javax.mail`/`jakarta.mail`/`org.springframework.mail` import. Eureka SMTP hits 3 → 0.
+- **JNDI DNS mislabeled as LDAP (BUG #2).** `javax.naming.directory.{Dir,Initial}Context`
+  is protocol-agnostic; it is now classified by its `INITIAL_CONTEXT_FACTORY` —
+  `DnsContextFactory` → `kind=dns` (`client=jndi-dns`), `LdapCtxFactory` → `ldap`, and an
+  unresolvable factory → `kind=naming-directory-unknown` with `confidence=low`, never an
+  assumed LDAP. Eureka `DnsResolver` now reports `dns`.
+- **"Spring Boot 3" narrative on a non-Spring repo (BUG #3).** When `spring_present` is
+  `False`, every `migrate-check` finding's `explanation` is rewritten from Spring-Boot
+  framing into framework-neutral Jakarta-EE / servlet-container framing (the javax→jakarta
+  finding itself is unchanged). Guarantee: no explanation contains "Spring Boot" unless
+  the report confirms runtime Spring.
+- **Inconsistent DI-framework label (BUG #4).** `impact` emitted "Spring/CDI DI pattern"
+  in the short `explanation` but "Spring/CDI/Guice" in `via_interface_note` of the *same*
+  JSON, while `direct_callers` proved the framework was Guice. Both strings now derive
+  from one label computed from caller evidence — a `*.guice.*` caller yields "Guice".
+- **"persistence paths" for non-persistence mappers (BUG #5).** Eureka's `AzToRegionMapper`
+  classes (AWS topology, no data layer) were counted as "4 persistence paths". Each
+  `mappers_affected` entry now carries `mapper_kind` (`persistence` only for a confirmed
+  `@Repository` role or MyBatis `mapper_interface`; otherwise `name_heuristic`). The
+  explanation says "persistence path" only for confirmed entries and neutral
+  "data-mapping class" otherwise — the word "persistence" never appears for a repo with no
+  confirmed persistence signal.
+- **Ambiguous `member_count` unit in `modernize` (BUG #6).** `subsystem_summary.member_count`
+  counts all graph members (classes + methods + fields), ~5× the class count and not
+  comparable to repo-level `total_classes`. Each entry now also carries an unambiguous
+  `class_count` (class/interface declarations only, comparable to `total_classes`), with a
+  `subsystem_summary_note` documenting both units.
+
 ## [1.67.0] — 2026-06-30
 
 ### Fixed — framing accuracy on non-Spring repos (Apache OFBiz field test)

{sourcecode-1.67.0 → sourcecode-1.69.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.67.0
+Version: 1.69.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

{sourcecode-1.67.0 → sourcecode-1.69.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.67.0"
+version = "1.69.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

sourcecode-1.69.0/scripts/generate_jdk_exports.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Generate the JDK unconditional-export allowlist used by migrate-check MIG-011.
+
+MIG-011 flags `sun.*` / `com.sun.*` imports as strongly-encapsulated JDK-internal
+APIs. That heuristic is *prefix-based* and produces false positives on packages
+that merely share the prefix but are in fact exported **unconditionally** by a
+JDK module (no `to` clause) and therefore require NO `--add-exports` /
+`--add-opens` on any classpath or module-path scenario. The canonical example is
+`com.sun.net.httpserver.*` (module `jdk.httpserver`) — public and documented
+since Java 6, the basis of JEP 408.
+
+This script derives the allowlist directly from the running JDK by parsing
+`java --describe-module` for every module, so the data tracks the real platform
+instead of a hand-maintained list that silently rots across releases.
+
+Two filters are applied:
+
+  1. Only `exports <pkg>` lines WITHOUT a `to <module>` qualifier are kept
+     (qualified exports still need `--add-exports` for arbitrary code).
+
+  2. Modules whose whole purpose is internal / tooling / deprecated access are
+     DENYLISTED — their `sun.*` / `com.sun.*` exports are genuine migration
+     concerns and must keep MIG-011's `high` severity:
+        - jdk.unsupported  → sun.misc.Unsafe, sun.reflect (deprecated for removal)
+        - jdk.compiler     → com.sun.source.*, com.sun.tools.javac (compiler internals)
+        - jdk.attach       → com.sun.tools.attach.* (tooling)
+        - jdk.jdi          → com.sun.jdi.* (debugger internals)
+        - jdk.jconsole / jdk.jdeps / jdk.javadoc / jdk.jshell → com.sun.tools.*
+
+Run with the OLDEST supported target JDK to stay conservative (a package
+exported in JDK 21 but not JDK 17 must not be allowlisted for a JDK 17 target).
+Re-run after a JDK bump and commit the regenerated module.
+
+Usage:
+    python scripts/generate_jdk_exports.py > src/sourcecode/jdk_exports.py
+"""
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+
+# Modules whose sun.*/com.sun.* exports are genuinely internal/tooling/deprecated.
+# Their packages must NOT be allowlisted — MIG-011 keeps firing `high` for them.
+_DENYLIST_MODULES: frozenset[str] = frozenset(
+    {
+        "jdk.unsupported",
+        "jdk.compiler",
+        "jdk.attach",
+        "jdk.jdi",
+        "jdk.jconsole",
+        "jdk.jdeps",
+        "jdk.javadoc",
+        "jdk.jshell",
+        "jdk.internal.ed",
+        "jdk.internal.le",
+        "jdk.internal.opt",
+        "jdk.internal.vm.ci",
+        "jdk.internal.vm.compiler",
+    }
+)
+
+_EXPORT_RE = re.compile(r"^exports\s+(\S+?)(?:\s+to\s+.*)?$")
+
+
+def _list_modules() -> list[str]:
+    out = subprocess.run(
+        ["java", "--list-modules"], capture_output=True, text=True, check=True
+    ).stdout
+    return [line.split("@", 1)[0].strip() for line in out.splitlines() if line.strip()]
+
+
+def _module_exports(module: str) -> list[tuple[str, bool]]:
+    """Return (package, is_unconditional) for each `exports` line of a module."""
+    out = subprocess.run(
+        ["java", "--describe-module", module],
+        capture_output=True,
+        text=True,
+    ).stdout
+    results: list[tuple[str, bool]] = []
+    for line in out.splitlines():
+        line = line.strip()
+        m = _EXPORT_RE.match(line)
+        if not m:
+            continue
+        pkg = m.group(1)
+        unconditional = " to " not in line
+        results.append((pkg, unconditional))
+    return results
+
+
+def main() -> int:
+    java_version = subprocess.run(
+        ["java", "-version"], capture_output=True, text=True
+    ).stderr.splitlines()[0]
+
+    allowlist: set[str] = set()
+    for module in _list_modules():
+        if module in _DENYLIST_MODULES:
+            continue
+        for pkg, unconditional in _module_exports(module):
+            if not unconditional:
+                continue
+            if pkg.startswith("sun.") or pkg.startswith("com.sun."):
+                allowlist.add(pkg)
+
+    packages = sorted(allowlist)
+
+    print('"""GENERATED FILE — do not edit by hand.')
+    print()
+    print("Allowlist of sun.* / com.sun.* packages exported UNCONDITIONALLY by the")
+    print("JDK (no `--add-exports` / `--add-opens` required on classpath or module")
+    print("path). Consumed by migrate-check MIG-011 to suppress false positives.")
+    print()
+    print(f"Regenerate with:  python scripts/generate_jdk_exports.py > "
+          "src/sourcecode/jdk_exports.py")
+    print(f"Generated from:   {java_version}")
+    print('"""')
+    print("from __future__ import annotations")
+    print()
+    print()
+    print("JDK_UNCONDITIONAL_EXPORTS: frozenset[str] = frozenset(")
+    print("    {")
+    for pkg in packages:
+        print(f'        "{pkg}",')
+    print("    }")
+    print(")")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{sourcecode-1.67.0 → sourcecode-1.69.0}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.67.0"
+__version__ = "1.69.0"

{sourcecode-1.67.0 → sourcecode-1.69.0}/src/sourcecode/classifier.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import re
 from collections.abc import Iterable, Sequence
 from dataclasses import replace
 from typing import Any, Literal
@@ -104,6 +105,21 @@ class TypeClassifier:
         stack_names = {stack.stack for stack in stacks}
         framework_names = {framework.name for stack in stacks for framework in stack.frameworks}
 
+        # BUG #4 (JobRunr field test): a framework present only in a small optional
+        # integration/adapter submodule must NOT label the whole repo as that
+        # framework's app type. JobRunr is a framework-agnostic background-job
+        # LIBRARY whose `core` module holds ~85% of the code; Quarkus/Micronaut/Spring
+        # appear only in tiny per-framework adapter modules — yet presence-based
+        # classification returned project_type="api"+Quarkus. We weight by code
+        # locality: if the DOMINANT source module (the one with the most source files)
+        # contains no evidence of the app-defining framework, the framework is an
+        # optional adapter and the repo is a library. A monolithic Spring app is
+        # unaffected — its dominant module *does* use the framework. Drop such
+        # localized frameworks from the set that drives the app-type decision below.
+        _app_frameworks = framework_names & (_WEB_FRAMEWORKS | _API_FRAMEWORKS)
+        _localized = self._localized_adapter_frameworks(file_tree, stacks, _app_frameworks)
+        framework_names = framework_names - _localized
+
         if len(stack_names) >= 2 and self._is_fullstack(stacks):
             return "fullstack"
 
@@ -129,9 +145,16 @@ class TypeClassifier:
         if framework_names & _API_FRAMEWORKS:
             return "api"
 
+        # All app-defining frameworks were localized to optional adapter submodules
+        # (multi-module library with per-framework integrations) — report library,
+        # never "unknown", when there is clearly source code present.
+        if _localized and not (framework_names & (_WEB_FRAMEWORKS | _API_FRAMEWORKS)):
+            return "library"
+
+        # Strong CLI signals: a CLI framework or an explicit cli entry point.
         if framework_names & _CLI_FRAMEWORKS or any(
             entry.kind == "cli" for entry in entry_points
-        ) or any(path.startswith("bin/") for path in flat_paths):
+        ):
             return "cli"
 
         if stack_names:
@@ -141,8 +164,105 @@ class TypeClassifier:
             if single in {"cpp", "dotnet"} and any(entry.kind == "cli" for entry in entry_points):
                 return "cli"
 
+        # BUG #4 (JobRunr field test): a multi-module JVM repo with no app-defining
+        # web/API framework is a library/toolkit, not an "unknown" — never let the
+        # first command of an audit emit a vacuous classification for a clearly
+        # structured codebase (e.g. JobRunr: core + per-framework adapter modules).
+        # This is checked BEFORE the weak `bin/`-directory CLI heuristic so a build
+        # output / wrapper `bin/` dir does not mislabel a library as a CLI.
+        if stack_names & {"java", "kotlin", "scala"} and self._is_multi_module(file_tree):
+            return "library"
+
+        # Weak CLI heuristic: a top-level bin/ directory (only when nothing stronger).
+        if any(path.startswith("bin/") for path in flat_paths):
+            return "cli"
+
         return "unknown" if stacks else None
 
+    def _is_multi_module(self, file_tree: dict[str, Any]) -> bool:
+        """True when the repo has >1 source module (distinct `*/src/...` roots)."""
+        _CODE_EXTS = (".java", ".kt", ".kts", ".scala", ".groovy")
+        modules = {
+            self._module_of(p)
+            for p in flatten_file_tree(file_tree)
+            if p.endswith(_CODE_EXTS)
+        }
+        modules.discard("")
+        return len(modules) >= 2
+
+    @staticmethod
+    def _module_of(path: str) -> str:
+        """Group a source path into its module root.
+
+        For Maven/Gradle layouts the module is everything before `/src/`
+        (e.g. `framework-support/jobrunr-quarkus/src/main/java/...` →
+        `framework-support/jobrunr-quarkus`). Otherwise the top-level directory.
+        """
+        norm = path.replace("\\", "/")
+        idx = norm.find("/src/")
+        if idx > 0:
+            return norm[:idx]
+        head, _, tail = norm.partition("/")
+        return head if tail else ""
+
+    _EVIDENCE_PATH_RE = re.compile(r"\(([^()]+)\)\s*$")
+
+    def _localized_adapter_frameworks(
+        self,
+        file_tree: dict[str, Any],
+        stacks: Sequence[StackDetection],
+        candidate_frameworks: set[str],
+    ) -> set[str]:
+        """Frameworks confined to a minority module while a framework-agnostic
+        module dominates the codebase (library + per-framework adapters).
+
+        Returns the subset of ``candidate_frameworks`` that should NOT drive the
+        project-type decision. A framework qualifies only when (a) the repo is
+        multi-module, (b) the framework's evidence files are all outside the
+        dominant source module, and (c) the framework has located evidence files
+        (a manifest-only/root detection applies repo-wide and never localizes).
+        """
+        if not candidate_frameworks:
+            return set()
+
+        _CODE_EXTS = (".java", ".kt", ".kts", ".scala", ".groovy")
+        module_file_counts: dict[str, int] = {}
+        for p in flatten_file_tree(file_tree):
+            if not p.endswith(_CODE_EXTS):
+                continue
+            mod = self._module_of(p)
+            module_file_counts[mod] = module_file_counts.get(mod, 0) + 1
+
+        # Need a genuine multi-module repo to reason about locality.
+        if len(module_file_counts) < 2:
+            return set()
+        dominant_module = max(module_file_counts, key=lambda m: module_file_counts[m])
+
+        # Collect evidence file paths per framework from detected_via.
+        evidence: dict[str, set[str]] = {}
+        for stack in stacks:
+            for fw in stack.frameworks:
+                if fw.name not in candidate_frameworks:
+                    continue
+                paths = evidence.setdefault(fw.name, set())
+                for ev in fw.detected_via:
+                    if ev.startswith("manifest:"):
+                        continue
+                    m = self._EVIDENCE_PATH_RE.search(ev)
+                    if m:
+                        paths.add(m.group(1).strip())
+
+        localized: set[str] = set()
+        for fw_name in candidate_frameworks:
+            files = evidence.get(fw_name) or set()
+            if not files:
+                # No locatable evidence (manifest-only) → applies repo-wide.
+                continue
+            modules = {self._module_of(f) for f in files}
+            if dominant_module not in modules:
+                localized.add(fw_name)
+        return localized
+
     def _is_fullstack(self, stacks: Sequence[StackDetection]) -> bool:
         has_web = False
         has_api = False

{sourcecode-1.67.0 → sourcecode-1.69.0}/src/sourcecode/cli.py

@@ -5777,14 +5777,32 @@ def modernize_cmd(
         "statically_unreferenced": len(dead_zones),
         "framework_dispatched": len(framework_dispatched),
     }
+    # BUG #6 (v1.68.0): `member_count` counts ALL graph members in the subsystem —
+    # classes, methods AND fields — so it runs ~5x higher than the class count and
+    # is not comparable to the repo-level `total_classes` (which counts only
+    # class/interface nodes). Surface an unambiguous `class_count` alongside it,
+    # computed against the same class/interface node set as total_classes, so a
+    # reader does not have to reverse-engineer the unit. `member_count` is retained
+    # for backward compatibility but is now documented as the graph-member tally.
+    _class_fqns = {n["fqn"] for n in graph_nodes if n.get("type") in ("class", "interface")}
+
+    def _class_count(members: list) -> int:
+        return sum(1 for m in members if m in _class_fqns)
+
     _subsystem_summary = [
         {
             "label": s.get("label") or s.get("name") or "",
             "package_prefix": s.get("package_prefix") or s.get("pkg") or "",
+            "class_count": _class_count(s.get("members") or []),
             "member_count": len(s.get("members") or []),
         }
         for s in subsystems[:15]
     ]
+    _subsystem_summary_note = (
+        "class_count = class/interface declarations only (comparable to "
+        "summary.total_classes). member_count = all graph members in the subsystem "
+        "including methods and fields, so it is larger and not a class tally."
+    )
 
     if (not _mod_is_pro) and _mod_large(str(root)):
         # Large monolith, free tier: structural discovery preview only — no dead
@@ -5801,6 +5819,7 @@ def modernize_cmd(
             ),
             "summary": _summary,
             "subsystem_summary": _subsystem_summary,
+            "subsystem_summary_note": _subsystem_summary_note,
             "hotspot_candidates": hotspots[:3],
             "high_coupling_nodes": [
                 {"fqn": n["fqn"], "in_degree": n.get("in_degree", 0), "role": n.get("role", "other")}
@@ -5833,9 +5852,11 @@ def modernize_cmd(
                 for n in framework_dispatched
             ],
             "subsystem_summary": _subsystem_summary,
+            "subsystem_summary_note": _subsystem_summary_note,
             "cross_module_tangles": [
                 {
                     "label": s.get("label") or s.get("name") or "",
+                    "class_count": _class_count(s.get("members") or []),
                     "member_count": len(s.get("members") or []),
                 }
                 for s in tangle_modules

{sourcecode-1.67.0 → sourcecode-1.69.0}/src/sourcecode/detectors/java.py

@@ -90,6 +90,19 @@ _GRADLE_JAVA_VERSION_RE = re.compile(
 _GRADLE_JAVA_ENUM_RE = re.compile(
     r"""(?:sourceCompatibility|targetCompatibility)\s*=\s*JavaVersion\.VERSION_(\d+)"""
 )
+# BUG #4: a gradle line that genuinely declares a dependency or plugin. Matches a
+# quoted Maven coordinate (group:artifact, requires the colon), a plugins-block
+# `id '...'`, an `apply plugin:`, or a `classpath`/`platform(`/`enforcedPlatform(`
+# declaration. Deliberately does NOT match `it.name.contains('quarkus')`-style
+# subproject filters (a bare quoted name with no colon and no plugin/dep keyword).
+_GRADLE_DEP_LINE_RE = re.compile(
+    r"""['"][\w.\-]+:[\w.\-]+"""          # maven coordinate "group:artifact..."
+    r"""|\bclasspath\b"""
+    r"""|\b(?:enforced)?platform\s*\("""
+    r"""|\bapply\s+plugin\s*:"""
+    r"""|\bid\s*[('"]""",
+    re.IGNORECASE,
+)
 
 
 class JavaDetector(AbstractDetector):
@@ -279,7 +292,29 @@ class JavaDetector(AbstractDetector):
         original = "\n".join(read_text_lines(path))
         content = original.lower()
         sb_version = self._extract_gradle_sb_version(original)
-        return self._detect_jvm_frameworks(content, "build.gradle", sb_version=sb_version)
+        # BUG #4 (JobRunr field test): framework tokens must be matched only inside
+        # genuine dependency / plugin declarations, never anywhere in the file. A
+        # multi-module root build.gradle that EXCLUDES a subproject by name —
+        # `configure(subprojects.findAll { !it.name.contains('quarkus') })` — must
+        # not be read as "this project uses Quarkus". Restrict the scan to lines
+        # carrying a Maven coordinate / plugin id; the exclusion filter has neither.
+        dep_text = self._gradle_dependency_text(content)
+        return self._detect_jvm_frameworks(dep_text, "build.gradle", sb_version=sb_version)
+
+    @staticmethod
+    def _gradle_dependency_text(content: str) -> str:
+        """Keep only gradle lines that declare a dependency or plugin.
+
+        A real dependency carries a Maven coordinate (`group:artifact`...) and a
+        plugin carries an `id`/`plugin`/`classpath` token. Subproject-name filters
+        and arbitrary prose are dropped, so a framework substring there cannot
+        manufacture a phantom framework detection.
+        """
+        kept: list[str] = []
+        for line in content.splitlines():
+            if _GRADLE_DEP_LINE_RE.search(line):
+                kept.append(line)
+        return "\n".join(kept)
 
     def _extract_gradle_sb_version(self, content: str) -> str | None:
         m = _GRADLE_SB_PLUGIN_RE.search(content)

{sourcecode-1.67.0 → sourcecode-1.69.0}/src/sourcecode/explain.py

@@ -223,7 +223,89 @@ def _build_purpose(
         if role_anns:
             desc = f"{role_anns[0]} bean"
 
-    return desc or "No stereotype detected — may be a plain class or utility."
+    if desc:
+        return desc
+
+    # BUG #4 (JobRunr field test): with no recognized framework annotation, the old
+    # fallback returned "No stereotype detected — may be a plain class or utility",
+    # which is actively misleading for a central domain class. Libraries and clean/
+    # hexagonal architectures model rich roles WITHOUT DI annotations. Infer a
+    # low-confidence structural role from signals the tool already computes:
+    # in-degree (coupling), lifecycle methods, and naming convention.
+    structural = _structural_purpose(class_fqn, raw_nodes, cir)
+    if structural:
+        return structural
+    return "No stereotype detected — may be a plain class or utility."
+
+
+# Lifecycle method names that signal an orchestrator/component managing state.
+_LIFECYCLE_METHODS = frozenset({
+    "start", "stop", "init", "initialize", "shutdown", "close",
+    "pause", "resume", "run", "destroy", "open", "restart",
+})
+
+# Class-name suffix → inferred role (no annotation required).
+_NAME_ROLE_SUFFIXES: tuple[tuple[str, str], ...] = (
+    ("Server", "server/orchestrator"),
+    ("Manager", "manager/coordinator"),
+    ("Controller", "controller"),
+    ("Service", "service"),
+    ("Repository", "repository/data access"),
+    ("Factory", "factory"),
+    ("Builder", "builder"),
+    ("Handler", "handler"),
+    ("Listener", "listener"),
+    ("Provider", "provider"),
+    ("Registry", "registry"),
+    ("Scheduler", "scheduler"),
+    ("Dispatcher", "dispatcher"),
+    ("Processor", "processor"),
+    ("Filter", "filter"),
+    ("Interceptor", "interceptor"),
+)
+
+
+def _structural_purpose(
+    class_fqn: str,
+    raw_nodes: list[dict],
+    cir: "CanonicalRepositoryIR",
+) -> str:
+    """Infer a low-confidence stereotype from structural signals (no annotations)."""
+    try:
+        in_degree = len(_build_callers(class_fqn, cir))
+    except Exception:
+        in_degree = 0
+
+    try:
+        method_names = {m.split("(")[0].lower() for m in _build_public_methods(class_fqn, raw_nodes)}
+    except Exception:
+        method_names = set()
+    lifecycle = sorted(method_names & _LIFECYCLE_METHODS)
+
+    simple = _simple(class_fqn)
+    role = ""
+    for suffix, label in _NAME_ROLE_SUFFIXES:
+        if simple.endswith(suffix):
+            role = label
+            break
+    if not role and lifecycle:
+        role = "orchestrator/lifecycle component"
+
+    # Require at least one real signal — otherwise stay honestly silent.
+    if not role and in_degree < 3:
+        return ""
+
+    head = f"Likely {role} (no DI annotations found)" if role else \
+        "Likely a structurally significant class (no DI annotations found)"
+    signals: list[str] = []
+    if in_degree >= 3:
+        signals.append(f"high in-degree ({in_degree})")
+    elif in_degree:
+        signals.append(f"in-degree {in_degree}")
+    if lifecycle:
+        signals.append(f"lifecycle methods detected ({'/'.join(lifecycle)})")
+    suffix = f" — {', '.join(signals)}" if signals else ""
+    return f"{head}{suffix} — inferred from structure, not annotations (low confidence)."
 
 
 def _build_public_methods(class_fqn: str, raw_nodes: list[dict]) -> list[str]: