adl-toolkit 0.0.0-stage → 0.1.1

package/adl_drift/lang/java/config.py

@@ -0,0 +1,707 @@
+"""Bounded Maven/Gradle project and framework detection (P4.7)."""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from defusedxml import ElementTree as DefusedET
+from defusedxml.common import DefusedXmlException
+
+from adl_drift.utils.config import find_project_root
+
+
+FRAMEWORK_MARKERS = {
+    "spring_boot": ("org.springframework.boot", "spring-boot"),
+    "spring_mvc": ("spring-webmvc", "spring-boot-starter-web"),
+    "spring_data": ("spring-data", "spring-boot-starter-data"),
+    "jpa": ("jakarta.persistence", "javax.persistence", "data-jpa"),
+    "hibernate": ("org.hibernate", "hibernate-core"),
+    "junit": ("junit",),
+    "testng": ("testng",),
+    "lombok": ("lombok",),
+    "jackson": ("com.fasterxml.jackson", "jackson-"),
+    "mybatis": ("mybatis",),
+}
+
+_GRADLE_DEPENDENCY = re.compile(
+    r"^\s*(?:[\w.]*(?:implementation|api|compileOnly|runtimeOnly|"
+    r"annotationProcessor|kapt|classpath))\s*(?:\(\s*)?(?:platform\(\s*)?"
+    r"[\"']([^\"']+:[^\"']+(?::[^\"']+)*)[\"']",
+    re.MULTILINE | re.IGNORECASE,
+)
+_GRADLE_CONSTRAINTS_BLOCK = re.compile(r"\bconstraints\s*\{")
+# ponytail: common static Gradle forms only; use the Tooling API if dynamic DSL
+# projects become a measured source of misses.
+_GRADLE_PLUGIN = re.compile(r"\bid\s*(?:\(\s*)?[\"']([^\"']+)[\"']")
+_GRADLE_GROUP = re.compile(r"(?m)^\s*group\s*=\s*[\"']([^\"']+)[\"']")
+_GRADLE_ROOT_NAME = re.compile(
+    r"(?m)^\s*rootProject\.name\s*=\s*[\"']([^\"']+)[\"']"
+)
+_GRADLE_INCLUDE = re.compile(r"(?m)^\s*include\b\s*(?:\(([^\n]*)\)|([^\n]*))")
+_GRADLE_SOURCE_LINE = re.compile(
+    r"(?m)^.*(?:srcDir|srcDirs|setSrcDirs)\s*(?:=|\()?([^\n]*)$"
+)
+_QUOTED = re.compile(r"[\"']([^\"']+)[\"']")
+# A Windows drive-letter (`C:\...`/`C:/...`) or POSIX (`/...`) absolute path,
+# as opposed to Gradle's own `:`-delimited project-path notation
+# (`:app:sub`) — the two must not be conflated (see `_read_gradle` below).
+_ABS_PATH = re.compile(r"^(?:[A-Za-z]:[\\/]|[\\/])")
+DEFAULT_MAX_BUILD_FILE_BYTES = 1024 * 1024
+DEFAULT_MAX_BUILD_TOTAL_BYTES = 16 * 1024 * 1024
+_MAX_MAVEN_POMS = 128
+
+
+def _blank_gradle_token(token: str) -> str:
+    return "".join(ch if ch == "\n" else " " for ch in token)
+
+
+def _mask_gradle_tokens(text: str, *, mask_strings: bool) -> str:
+    """Blank Gradle comments, and optionally strings, in one linear pass."""
+    out: list[str] = []
+    i = 0
+    length = len(text)
+    while i < length:
+        ch = text[i]
+        next_ch = text[i + 1] if i + 1 < length else ""
+        if ch == "/" and next_ch == "/":
+            start = i
+            i += 2
+            while i < length and text[i] != "\n":
+                i += 1
+            out.append(_blank_gradle_token(text[start:i]))
+            continue
+        if ch == "/" and next_ch == "*":
+            start = i
+            i += 2
+            while i + 1 < length and not (text[i] == "*" and text[i + 1] == "/"):
+                i += 1
+            i = i + 2 if i + 1 < length else length
+            out.append(_blank_gradle_token(text[start:i]))
+            continue
+        if ch in "\"'":
+            quote = ch
+            triple = text.startswith(quote * 3, i)
+            start = i
+            i += 3 if triple else 1
+            if triple:
+                while i + 2 < length and not text.startswith(quote * 3, i):
+                    i += 1
+                i = i + 3 if i + 2 < length else length
+            else:
+                escaped = False
+                while i < length:
+                    current = text[i]
+                    i += 1
+                    if escaped:
+                        escaped = False
+                    elif current == "\\":
+                        escaped = True
+                    elif current == quote:
+                        break
+            token = text[start:i]
+            out.append(_blank_gradle_token(token) if mask_strings else token)
+            continue
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+
+def _mask_gradle_noise(text: str) -> str:
+    """Blank out comments and string literals, preserving length and newlines.
+
+    Brace-depth counting must only see structural Groovy/Kotlin syntax —
+    otherwise a stray ``constraints {`` (or an unmatched brace) inside a
+    comment or string literal desyncs the depth counter and swallows real
+    code that follows it.
+    """
+    return _mask_gradle_tokens(text, mask_strings=True)
+
+
+def _mask_gradle_comments(text: str) -> str:
+    """Blank out ``//``/``/* */`` comments only, keeping string content intact.
+
+    Every non-brace-counting extraction (dependency/plugin/group/source-root
+    regexes) must run on this, not raw source: those regexes have no notion
+    of "inside a comment", so a commented-out ``implementation '...'`` line
+    (very common when a dependency is disabled) or even a same-line ``//
+    id '...'`` reads as a real declaration otherwise. Reuses the combined
+    comment-or-string tokenizer so a ``//`` embedded in a string (e.g. a URL
+    coordinate) is correctly kept as string content, not treated as a
+    comment start.
+    """
+    return _mask_gradle_tokens(text, mask_strings=False)
+
+
+def _strip_gradle_constraints(text: str) -> tuple[str, bool]:
+    """Drop ``constraints { ... }`` bodies before dependency extraction.
+
+    A `constraints` block only pins versions for the Gradle version-alignment
+    engine (Gradle's equivalent of Maven `dependencyManagement`) — it does not
+    declare an actual dependency. Without this, a `dependencies { constraints
+    { implementation(...) } }` block would be indistinguishable from a real
+    `dependencies { implementation(...) }` declaration.
+
+    Returns the cleaned text and whether an unbalanced ``constraints {`` was
+    found. On an unbalanced match, text up to the unmatched brace is kept
+    (real dependencies declared earlier in the file are not discarded) but
+    nothing from the unmatched ``constraints {`` onward is: falling back to
+    the raw remainder there would treat pinned-only (managed, not actually
+    used) coordinates as real dependencies — a false positive that can also
+    leak into framework detection. Losing any real declaration that happens
+    to follow a malformed block is the safer trade-off; the caller surfaces
+    this as a truncation error so downstream consumers know the metadata is
+    partial.
+    """
+    masked = _mask_gradle_noise(text)
+    out = []
+    pos = 0
+    unbalanced = False
+    for match in _GRADLE_CONSTRAINTS_BLOCK.finditer(masked):
+        if match.start() < pos:
+            continue
+        depth = 1
+        i = match.end()
+        while i < len(masked) and depth > 0:
+            if masked[i] == "{":
+                depth += 1
+            elif masked[i] == "}":
+                depth -= 1
+            i += 1
+        out.append(text[pos:match.start()])
+        if depth > 0:
+            unbalanced = True
+            pos = len(text)
+            break
+        pos = i
+    if not unbalanced:
+        out.append(text[pos:])
+    return "".join(out), unbalanced
+
+
+def _local_name(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1]
+
+
+def _child_text(element: ET.Element, name: str) -> Optional[str]:
+    for child in element:
+        if _local_name(child.tag) == name and child.text:
+            return child.text.strip()
+    return None
+
+
+def _direct_child(element: ET.Element, name: str) -> Optional[ET.Element]:
+    return next((child for child in element if _local_name(child.tag) == name), None)
+
+
+def _coordinate(element: ET.Element) -> Optional[str]:
+    group = _child_text(element, "groupId")
+    artifact = _child_text(element, "artifactId")
+    version = _child_text(element, "version")
+    if not group or not artifact:
+        return None
+    return ":".join(part for part in (group, artifact, version) if part)
+
+
+def _maven_module_parents(project: ET.Element) -> list[ET.Element]:
+    """Return reactor ``<modules>`` blocks, including profile reactors.
+
+    Static analysis takes the union of Maven profiles: unlike a build invocation,
+    it has no activation environment, and excluding inactive-profile modules makes
+    source discovery disagree with a repository-wide oracle.
+    """
+    parents = []
+    direct = _direct_child(project, "modules")
+    if direct is not None:
+        parents.append(direct)
+    profiles = _direct_child(project, "profiles")
+    if profiles is not None:
+        for profile in profiles:
+            if _local_name(profile.tag) != "profile":
+                continue
+            modules = _direct_child(profile, "modules")
+            if modules is not None:
+                parents.append(modules)
+    return parents
+
+
+def _resolve_path(base: Path, value: str) -> Optional[Path]:
+    value = value.strip().replace("${project.basedir}", str(base)).replace(
+        "${basedir}", str(base)
+    )
+    if not value or "${" in value or "$" in value:
+        return None
+    path = Path(value)
+    return path if path.is_absolute() else base / path
+
+
+@dataclass
+class JavaProjectConfig:
+    """Shared ProjectConfig shape populated from Maven or bounded Gradle syntax."""
+
+    project_path: Path
+    max_build_file_bytes: int = DEFAULT_MAX_BUILD_FILE_BYTES
+    max_build_total_bytes: int = DEFAULT_MAX_BUILD_TOTAL_BYTES
+    frameworks: list[str] = field(init=False, default_factory=list)
+    source_roots: list[Path] = field(init=False, default_factory=list)
+    dependencies: list[str] = field(init=False, default_factory=list)
+    modules: list[str] = field(init=False, default_factory=list)
+    plugins: list[str] = field(init=False, default_factory=list)
+    group_id: Optional[str] = field(init=False, default=None)
+    artifact_id: Optional[str] = field(init=False, default=None)
+    build_system: Optional[str] = field(init=False, default=None)
+    errors: list[str] = field(init=False, default_factory=list)
+    error_details: list[dict[str, Any]] = field(init=False, default_factory=list)
+    truncated: bool = field(init=False, default=False)
+    build_files_processed: int = field(init=False, default=0)
+    build_files_remaining: int = field(init=False, default=0)
+    build_bytes_read: int = field(init=False, default=0)
+    _budget_exhausted: bool = field(init=False, default=False, repr=False)
+    _resolved_root: Optional[Path] = field(init=False, default=None, repr=False)
+    # Every build file this config read, with its (st_mtime_ns, st_size) at
+    # read time: a long-lived process re-validates a cached discovery by
+    # re-stat()ing these (scanner.discovery.CachedDiscovery).
+    build_file_stats: dict[str, tuple[int, int]] = field(
+        init=False, default_factory=dict, repr=False,
+    )
+
+    def __post_init__(self) -> None:
+        if self.max_build_file_bytes < 1 or self.max_build_total_bytes < 1:
+            raise ValueError("build-file byte limits must be positive")
+        supplied = Path(self.project_path)
+        if supplied.is_file():
+            supplied = supplied.parent
+        self.project_path = find_project_root(supplied) or supplied
+        self._detect()
+
+    @property
+    def metadata(self) -> dict[str, Any]:
+        """JSON-safe project metadata for scanner/MCP consumers in later P4 work."""
+        return {
+            "project_path": str(self.project_path),
+            "build_system": self.build_system,
+            "group_id": self.group_id,
+            "artifact_id": self.artifact_id,
+            "frameworks": self.frameworks,
+            "dependencies": self.dependencies,
+            "modules": self.modules,
+            "plugins": self.plugins,
+            "source_roots": [str(path) for path in self.source_roots],
+            "truncated": self.truncated,
+            "build_files": {
+                "processed": self.build_files_processed,
+                "remaining": self.build_files_remaining,
+                "bytes_read": self.build_bytes_read,
+            },
+            "limits": {
+                "max_file_bytes": self.max_build_file_bytes,
+                "max_total_bytes": self.max_build_total_bytes,
+                "max_maven_poms": _MAX_MAVEN_POMS,
+            },
+            "errors": self.errors,
+            "error_details": self.error_details,
+        }
+
+    def has_framework(self, name: str) -> bool:
+        return name.lower() in self.frameworks
+
+    def _project_path(self, candidate: Path, label: str) -> Optional[Path]:
+        """Resolve ``candidate`` only when it remains inside the project root."""
+        try:
+            # Resolve the root once per config: this runs for every module /
+            # source directory of a reactor and Path.resolve() lstat()s each
+            # path component (MCP_GRAPH_CACHE_PLAN.md Lớp 2).
+            if self._resolved_root is None:
+                self._resolved_root = self.project_path.resolve()
+            root = self._resolved_root
+            resolved = candidate.resolve()
+            resolved.relative_to(root)
+        except (OSError, RuntimeError, ValueError):
+            self.errors.append(f"{label} escapes project root: {candidate}")
+            return None
+        return resolved
+
+    def _resource_error(self, code: str, message: str, **details: Any) -> None:
+        self.truncated = True
+        self.errors.append(message)
+        self.error_details.append({"code": code, "message": message, **details})
+
+    def _read_build_file(self, path: Path) -> Optional[bytes]:
+        """Read one build file without exceeding per-file or reactor byte limits."""
+        try:
+            stat = path.stat()
+        except OSError as exc:
+            self.errors.append(f"{path}: {exc}")
+            return None
+        size = stat.st_size
+        self.build_file_stats[str(path)] = (stat.st_mtime_ns, size)
+
+        if size > self.max_build_file_bytes:
+            self.build_files_remaining += 1
+            self._resource_error(
+                "build_file_too_large",
+                f"{path}: build file exceeds {self.max_build_file_bytes} byte limit",
+                path=str(path),
+                actual_bytes=size,
+                limit_bytes=self.max_build_file_bytes,
+            )
+            return None
+
+        remaining = self.max_build_total_bytes - self.build_bytes_read
+        if size > remaining:
+            self.build_files_remaining += 1
+            self._budget_exhausted = True
+            self._resource_error(
+                "build_total_too_large",
+                f"{path}: build files exceed {self.max_build_total_bytes} byte total limit",
+                path=str(path),
+                actual_bytes=size,
+                remaining_bytes=max(remaining, 0),
+                limit_bytes=self.max_build_total_bytes,
+            )
+            return None
+
+        try:
+            with path.open("rb") as stream:
+                data = stream.read(size)
+        except OSError as exc:
+            self.errors.append(f"{path}: {exc}")
+            return None
+
+        self.build_files_processed += 1
+        self.build_bytes_read += len(data)
+        return data
+
+    def _parse_pom(self, pom: Path, data: bytes) -> Optional[ET.Element]:
+        try:
+            return DefusedET.fromstring(
+                data, forbid_dtd=True, forbid_entities=True, forbid_external=True
+            )
+        except DefusedXmlException as exc:
+            self._resource_error(
+                "unsafe_xml",
+                f"{pom}: unsafe XML is not allowed: {exc}",
+                path=str(pom),
+            )
+            return None
+        except ET.ParseError as exc:
+            self.errors.append(f"{pom}: {exc}")
+            return None
+
+    def _detect(self) -> None:
+        dependencies: set[str] = set()
+        plugins: set[str] = set()
+        modules: set[str] = set()
+        roots: set[Path] = set()
+        hints: set[str] = set()
+
+        pom = self.project_path / "pom.xml"
+        gradle_files = [
+            self.project_path / name
+            for name in (
+                "build.gradle",
+                "build.gradle.kts",
+                "settings.gradle",
+                "settings.gradle.kts",
+            )
+            if (self.project_path / name).is_file()
+        ]
+
+        if pom.is_file():
+            self.build_system = "maven"
+            self._read_maven(pom, dependencies, plugins, modules, roots, hints)
+        elif gradle_files:
+            self.build_system = "gradle"
+            self._read_gradle(gradle_files, dependencies, plugins, modules, roots, hints)
+
+        self._add_conventional_roots(self.project_path, roots)
+        for module in modules:
+            self._add_conventional_roots(self.project_path / module, roots)
+
+        marker_text = "\n".join((*dependencies, *plugins, *hints)).lower()
+        self.frameworks = sorted(
+            framework
+            for framework, markers in FRAMEWORK_MARKERS.items()
+            if any(marker in marker_text for marker in markers)
+        )
+        self.dependencies = sorted(dependencies)
+        self.plugins = sorted(plugins)
+        self.modules = sorted(modules)
+        self.source_roots = sorted(roots, key=str)
+
+    def _read_maven(
+        self,
+        root_pom: Path,
+        dependencies: set[str],
+        plugins: set[str],
+        modules: set[str],
+        roots: set[Path],
+        hints: set[str],
+    ) -> None:
+        pending = [root_pom]
+        seen: set[Path] = set()
+        # Same module can legally appear in more than one `<modules>` block
+        # (default + a profile, or two different profiles) — union-of-profiles
+        # reactor discovery must not enqueue it twice, or a cap/budget stop
+        # mid-queue overcounts `build_files_remaining` with a POM that was
+        # already fully processed, falsely reporting the reactor as truncated.
+        queued: set[Path] = {root_pom}
+        resolved_root_pom = root_pom.resolve()
+        # ponytail: fixed file/count budgets bound untrusted reactors; make them
+        # configurable only if real repositories need different limits.
+        while pending and len(seen) < _MAX_MAVEN_POMS and not self._budget_exhausted:
+            pom = self._project_path(pending.pop(), "Maven POM")
+            if pom is None:
+                continue
+            if pom in seen or not pom.is_file():
+                continue
+            seen.add(pom)
+            data = self._read_build_file(pom)
+            if data is None:
+                continue
+            project = self._parse_pom(pom, data)
+            if project is None:
+                continue
+            base = pom.parent
+
+            if pom == resolved_root_pom:
+                parent = _direct_child(project, "parent")
+                self.group_id = _child_text(project, "groupId") or (
+                    _child_text(parent, "groupId") if parent is not None else None
+                )
+                self.artifact_id = _child_text(project, "artifactId")
+
+            parent = _direct_child(project, "parent")
+            if parent is not None and (coordinate := _coordinate(parent)):
+                hints.add(coordinate)
+
+            dependency_parent = _direct_child(project, "dependencies")
+            if dependency_parent is not None:
+                for dependency in dependency_parent:
+                    if (
+                        _local_name(dependency.tag) == "dependency"
+                        and (coordinate := _coordinate(dependency))
+                    ):
+                        dependencies.add(coordinate)
+
+            build = _direct_child(project, "build")
+            plugin_parent = _direct_child(build, "plugins") if build is not None else None
+            if plugin_parent is not None:
+                for plugin in plugin_parent:
+                    if (
+                        _local_name(plugin.tag) == "plugin"
+                        and (coordinate := _coordinate(plugin))
+                    ):
+                        plugins.add(coordinate)
+
+            for element in project.iter():
+                kind = _local_name(element.tag)
+                if kind in {"sourceDirectory", "testSourceDirectory"} and element.text:
+                    source_root = _resolve_path(base, element.text)
+                    if source_root is not None:
+                        source_root = self._project_path(source_root, f"Maven {kind}")
+                    if source_root is not None:
+                        roots.add(source_root)
+                elif kind == "sources":
+                    for source in element:
+                        if _local_name(source.tag) == "source" and source.text:
+                            source_root = _resolve_path(base, source.text)
+                            if source_root is not None:
+                                source_root = self._project_path(
+                                    source_root, "Maven configured source root"
+                                )
+                            if source_root is not None:
+                                roots.add(source_root)
+
+            for module_parent in _maven_module_parents(project):
+                for module in module_parent:
+                    if _local_name(module.tag) != "module" or not module.text:
+                        continue
+                    module_name = module.text.strip().replace("\\", "/")
+                    if not module_name or "${" in module_name:
+                        continue
+                    module_path = self._project_path(
+                        base / module_name, f"Maven module {module_name!r}"
+                    )
+                    if module_path is None:
+                        continue
+                    relative = module_path.relative_to(
+                        self.project_path.resolve()
+                    ).as_posix()
+                    modules.add(relative)
+                    child_pom = module_path / "pom.xml"
+                    if child_pom not in queued:
+                        queued.add(child_pom)
+                        pending.append(child_pom)
+
+        if pending:
+            self.build_files_remaining += len(pending)
+            if len(seen) >= _MAX_MAVEN_POMS:
+                self._resource_error(
+                    "maven_reactor_limit",
+                    f"Maven reactor stopped after {_MAX_MAVEN_POMS} POMs; "
+                    f"{len(pending)} remain",
+                    processed=len(seen),
+                    remaining=len(pending),
+                    limit=_MAX_MAVEN_POMS,
+                )
+
+    def _read_gradle(
+        self,
+        root_files: list[Path],
+        dependencies: set[str],
+        plugins: set[str],
+        modules: set[str],
+        roots: set[Path],
+        hints: set[str],
+    ) -> None:
+        texts: dict[Path, str] = {}
+        ordered_root_files = sorted(
+            root_files, key=lambda path: not path.name.startswith("settings.gradle")
+        )
+        for index, candidate in enumerate(ordered_root_files):
+            if self._budget_exhausted:
+                self.build_files_remaining += len(ordered_root_files) - index
+                break
+            path = self._project_path(candidate, f"Gradle build file {candidate.name}")
+            if path is None:
+                continue
+            data = self._read_build_file(path)
+            if data is not None:
+                texts[path] = _mask_gradle_comments(data.decode("utf-8", errors="replace"))
+
+        settings_text = "\n".join(
+            text for path, text in texts.items() if path.name.startswith("settings.gradle")
+        )
+        if match := _GRADLE_ROOT_NAME.search(settings_text):
+            self.artifact_id = match.group(1)
+        for match in _GRADLE_INCLUDE.finditer(settings_text):
+            for value in _QUOTED.findall(match.group(1) or match.group(2) or ""):
+                # Gradle's own module-path notation (`:app:sub`) uses `:` as
+                # its separator, so it's normally safe to fold into `/` — but
+                # an `include(...)` argument that's actually an absolute
+                # filesystem path (this can be produced by dynamic/scripted
+                # settings.gradle, and matters most on Windows) carries a
+                # drive-letter `:` that is NOT a Gradle separator. Folding it
+                # anyway used to strip the drive letter's colon (`C:\x` ->
+                # `C\x`), turning an absolute path into what pathlib treats
+                # as a *relative* one when joined below — silently pulling a
+                # module that escapes the project root back "inside" it and
+                # defeating the `_project_path` escape check entirely.
+                module = value if _ABS_PATH.match(value) else value.strip(":").replace(":", "/")
+                if not module:
+                    continue
+                module_path = self._project_path(
+                    self.project_path / module, f"Gradle module {value!r}"
+                )
+                if module_path is not None:
+                    modules.add(
+                        module_path.relative_to(self.project_path.resolve()).as_posix()
+                    )
+
+        build_files = {
+            path for path in texts if path.name in {"build.gradle", "build.gradle.kts"}
+        }
+        for module in modules:
+            for name in ("build.gradle", "build.gradle.kts"):
+                candidate = self.project_path / module / name
+                path = self._project_path(candidate, f"Gradle build file {candidate}")
+                if path is not None and path.is_file():
+                    build_files.add(path)
+
+        unread = sorted(build_files - texts.keys(), key=str)
+        for index, path in enumerate(unread):
+            if self._budget_exhausted:
+                self.build_files_remaining += len(unread) - index
+                break
+            data = self._read_build_file(path)
+            if data is not None:
+                texts[path] = _mask_gradle_comments(data.decode("utf-8", errors="replace"))
+
+        for path in sorted(build_files & texts.keys(), key=str):
+            text = texts[path]
+            cleaned, unbalanced = _strip_gradle_constraints(text)
+            if unbalanced:
+                self._resource_error(
+                    "unbalanced_gradle_constraints",
+                    f"{path}: unbalanced 'constraints {{' block (possibly "
+                    "inside a comment/string); dependency extraction "
+                    "stopped before the unmatched block",
+                    path=str(path),
+                )
+            dependencies.update(_GRADLE_DEPENDENCY.findall(cleaned))
+            plugins.update(_GRADLE_PLUGIN.findall(text))
+            if self.group_id is None and (match := _GRADLE_GROUP.search(text)):
+                self.group_id = match.group(1)
+            for match in _GRADLE_SOURCE_LINE.finditer(text):
+                for value in _QUOTED.findall(match.group(1)):
+                    source_root = _resolve_path(path.parent, value)
+                    if source_root is not None:
+                        source_root = self._project_path(
+                            source_root, "Gradle configured source root"
+                        )
+                    if source_root is not None:
+                        roots.add(source_root)
+
+        hints.update(plugins)
+
+    @staticmethod
+    def _add_conventional_roots(project: Path, roots: set[Path]) -> None:
+        for relative in ("src/main/java", "src/test/java"):
+            path = project / relative
+            if path.is_dir():
+                roots.add(path)
+
+    def excluded_source_files(self) -> list[dict[str, Any]]:
+        """Diagnostic only — every ``.java`` file physically present under
+        the project root that ``source_roots`` does not cover, each with a
+        best-effort reason. Not called from ``_detect()``: it walks the
+        whole tree once (``rglob``), which is fine for an opt-in diagnostic
+        (``scan --format json``) but would be wasted work on every
+        ``graph``/``scan`` build, where callers only need ``source_roots``
+        itself.
+
+        A benchmark comparing Drift's file counts against a plain recursive
+        ``.java`` count found Drift "silently" analyzing fewer files than
+        exist on disk, with no way to tell a correct exclusion (a Maven
+        module commented out of its parent's ``<modules>`` list; a
+        ``.java``-suffixed file sitting in a ``resources`` directory, never
+        a compiled source root) from an actual bug. This surfaces that gap.
+        """
+        if self.build_system != "maven":
+            return []
+        root = self._resolved_root or self.project_path.resolve()
+        covered_roots = [r.resolve() for r in self.source_roots]
+
+        def _is_covered(path: Path) -> bool:
+            return any(path == cr or cr in path.parents for cr in covered_roots)
+
+        resolved_modules = {(root / m).resolve() for m in self.modules}
+        module_dirs = {p.parent.resolve() for p in root.rglob("pom.xml")}
+        module_dirs.add(root)
+
+        excluded: list[dict[str, Any]] = []
+        for java_file in sorted(root.rglob("*.java")):
+            if _is_covered(java_file):
+                continue
+            rel = java_file.relative_to(root).as_posix()
+            reason = "unknown"
+            detail: Optional[str] = None
+            if f"/{rel}".startswith("/") and (
+                "/src/main/resources/" in f"/{rel}" or "/src/test/resources/" in f"/{rel}"
+            ):
+                reason = "not_a_compiled_source_root"
+                detail = "under a Maven resources directory, not src/main|test/java"
+            else:
+                for ancestor in java_file.parents:
+                    if ancestor == root:
+                        break
+                    if ancestor in module_dirs and ancestor not in resolved_modules:
+                        reason = "module_not_in_active_reactor"
+                        detail = ancestor.relative_to(root).as_posix()
+                        break
+            excluded.append({"path": rel, "reason": reason, "detail": detail})
+        return excluded