sourcecode 0.37.0__py3-none-any.whl → 0.38.0__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/adaptive_scanner.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+"""Adaptive file tree scanner with topology-aware depth budgets.
+
+Replaces pure depth filtering with relevance-oriented traversal:
+- Source roots (packages/*/src, apps/*/src) get deep scan budgets.
+- Low-signal directories (docs/, benchmarks/) are limited to 2 levels.
+- Generated/excluded directories (dist/, node_modules/) are skipped.
+- Unclassified directories fall back to the base depth limit.
+
+Drop-in replacement for FileScanner: same scan_tree() and find_manifests()
+interface, same output format (None = file, dict = directory).
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Optional, cast
+
+from pathspec import GitIgnoreSpec
+
+from sourcecode.repo_classifier import RepoTopology
+from sourcecode.scanner import DEFAULT_EXCLUDES, MANIFEST_NAMES
+
+
+class AdaptiveScanner:
+    """File tree scanner driven by repository topology.
+
+    When *topology* is provided, traversal depth is controlled per-directory:
+    directories inside source roots receive a deep budget; low-signal dirs
+    are restricted; generated dirs are excluded entirely.
+
+    When *topology* is None, falls back to the base depth limit — identical
+    behaviour to FileScanner.
+    """
+
+    def __init__(
+        self,
+        root: Path,
+        topology: Optional[RepoTopology] = None,
+        base_depth: int = 4,
+        extra_excludes: Optional[frozenset[str]] = None,
+    ) -> None:
+        self.root = root.resolve()
+        self.topology = topology
+        self.base_depth = base_depth
+        self._excludes = DEFAULT_EXCLUDES | (extra_excludes or frozenset())
+        self._gitignore_spec: Optional[GitIgnoreSpec] = None
+
+        # Pre-compute lookup tables from topology for O(1) classification
+        # during traversal.
+        #
+        # Each entry is (path_parts_tuple, max_absolute_depth):
+        #   source prefix → (src_parts, len(src_parts) + source_depth)
+        #   low-signal prefix → (ls_parts, len(ls_parts) + low_signal_depth)
+        #
+        # "max_absolute_depth" is depth measured from the repo root, not from
+        # the classified directory. At depth D, files are visible; at depth
+        # >= max we clear dirnames and skip files.
+        self._source_prefixes: list[tuple[tuple[str, ...], int]] = []
+        self._low_signal_prefixes: list[tuple[tuple[str, ...], int]] = []
+        self._extra_exclude_names: frozenset[str] = frozenset()
+
+        if topology is not None:
+            budget = topology.scan_budget
+            for sr in topology.source_roots:
+                parts = tuple(p for p in sr.path.split("/") if p)
+                if parts:
+                    max_d = len(parts) + budget.source_depth
+                    self._source_prefixes.append((parts, max_d))
+
+            for lr in topology.low_signal_roots:
+                parts = tuple(p for p in lr.path.split("/") if p)
+                if parts:
+                    max_d = len(parts) + budget.low_signal_depth
+                    self._low_signal_prefixes.append((parts, max_d))
+
+            # Generated roots at depth 1 → add to excludes so os.walk never enters
+            top_generated = {
+                gr.path.split("/")[0]
+                for gr in topology.generated_roots
+                if "/" not in gr.path
+            }
+            self._extra_exclude_names = frozenset(top_generated)
+
+    # ------------------------------------------------------------------
+    # Gitignore
+    # ------------------------------------------------------------------
+
+    def _load_gitignore_spec(self) -> GitIgnoreSpec:
+        if self._gitignore_spec is None:
+            gitignore = self.root / ".gitignore"
+            lines: list[str] = []
+            if gitignore.exists():
+                try:
+                    lines = gitignore.read_text(encoding="utf-8", errors="replace").splitlines()
+                except OSError:
+                    pass
+            self._gitignore_spec = GitIgnoreSpec.from_lines(lines)
+        return self._gitignore_spec
+
+    def _is_excluded_by_gitignore(self, rel_path: str, is_dir: bool) -> bool:
+        spec = self._load_gitignore_spec()
+        path_to_match = rel_path + "/" if is_dir else rel_path
+        return spec.match_file(path_to_match)
+
+    # ------------------------------------------------------------------
+    # Depth budget computation — the core of adaptive traversal
+    # ------------------------------------------------------------------
+
+    def _compute_max_depth(self, rel_parts: tuple[str, ...]) -> int:
+        """Return the maximum absolute depth allowed at *rel_parts*.
+
+        Depth is the number of path components from the repo root.  Files
+        at depth D are included; the scan stops (dirnames cleared) when
+        depth >= returned value.
+
+        Priority order:
+        1. Inside a source root → deep budget (source_depth extra levels)
+        2. Ancestor of a source root → must allow traversal to reach it
+        3. Inside a low-signal root → restricted budget (low_signal_depth)
+        4. Default → base_depth
+        """
+        if not self._source_prefixes and not self._low_signal_prefixes:
+            return self.base_depth
+
+        current_depth = len(rel_parts)
+
+        # Track the best depth found via ancestor matching (may have multiple
+        # source roots; return the maximum so all are reachable).
+        ancestor_best = self.base_depth
+        found_ancestor = False
+
+        for src_parts, src_max in self._source_prefixes:
+            n = len(src_parts)
+            if current_depth >= n:
+                # At or inside the source root
+                if rel_parts[:n] == src_parts:
+                    return src_max  # definite source territory — early exit
+            else:
+                # Ancestor check: src_parts starts with rel_parts?
+                if src_parts[:current_depth] == rel_parts:
+                    found_ancestor = True
+                    if src_max > ancestor_best:
+                        ancestor_best = src_max
+
+        if found_ancestor:
+            return ancestor_best
+
+        # Low-signal roots (only if not already committed to a source path)
+        for ls_parts, ls_max in self._low_signal_prefixes:
+            n = len(ls_parts)
+            if current_depth >= n and rel_parts[:n] == ls_parts:
+                return ls_max
+
+        return self.base_depth
+
+    # ------------------------------------------------------------------
+    # Main traversal
+    # ------------------------------------------------------------------
+
+    def scan_tree(self) -> dict[str, Any]:
+        """Build the nested file tree dictionary.
+
+        Returns dict where None = file (D-02) and dict = directory (D-01).
+        Depth limits are applied per-directory using topology-derived budgets.
+        """
+        self._load_gitignore_spec()
+        root_tree: dict[str, Any] = {}
+        all_excludes = self._excludes | self._extra_exclude_names
+
+        for dirpath, dirnames, filenames in os.walk(self.root, followlinks=False):
+            current = Path(dirpath)
+            try:
+                rel = current.relative_to(self.root)
+            except ValueError:
+                continue
+
+            rel_parts = rel.parts
+            depth = len(rel_parts)
+
+            effective_max_depth = self._compute_max_depth(rel_parts)
+
+            if depth >= effective_max_depth:
+                dirnames.clear()
+                continue
+
+            # Filter dirnames in-place (critical: slice assignment)
+            dirnames[:] = [
+                d for d in dirnames
+                if d not in all_excludes
+                and not (current / d).is_symlink()
+                and not self._is_excluded_by_gitignore(
+                    str(rel / d) if rel_parts else d,
+                    is_dir=True,
+                )
+            ]
+
+            node = self._get_or_create_node(root_tree, rel_parts)
+
+            for fname in filenames:
+                # Skip flag-shaped names (shell redirect artifacts)
+                if fname.startswith("-"):
+                    continue
+                fpath = current / fname
+                if fpath.is_symlink():
+                    continue
+                rel_file = str(rel / fname) if rel_parts else fname
+                if self._is_excluded_by_gitignore(rel_file, is_dir=False):
+                    continue
+                node[fname] = None  # D-02: None = file
+
+            # Ensure accepted subdirs exist as dict nodes
+            for d in dirnames:
+                if d not in node:
+                    node[d] = {}
+
+        return root_tree
+
+    def _get_or_create_node(
+        self, tree: dict[str, Any], parts: tuple[str, ...]
+    ) -> dict[str, Any]:
+        node = tree
+        for part in parts:
+            if part not in node or node[part] is None:
+                node[part] = {}
+            node = cast(dict[str, Any], node[part])
+        return node
+
+    # ------------------------------------------------------------------
+    # Manifest discovery — same interface as FileScanner
+    # ------------------------------------------------------------------
+
+    def find_manifests(self) -> list[str]:
+        """Find manifest files at depth 0-1.
+
+        Identical logic to FileScanner.find_manifests() — depth-0 root
+        manifests plus depth-1 sub-package manifests, hidden dirs excluded.
+        """
+        manifests: list[str] = []
+        for name in MANIFEST_NAMES:
+            candidate = self.root / name
+            if candidate.exists() and not candidate.is_symlink():
+                manifests.append(str(candidate))
+        try:
+            for child in self.root.iterdir():
+                if (
+                    child.is_dir()
+                    and not child.is_symlink()
+                    and child.name not in self._excludes
+                    and not child.name.startswith(".")
+                ):
+                    for name in MANIFEST_NAMES:
+                        candidate = child / name
+                        if candidate.exists() and not candidate.is_symlink():
+                            manifests.append(str(candidate))
+        except PermissionError:
+            pass
+        return manifests

sourcecode/cli.py

@@ -714,6 +714,13 @@ def main(
     # 1. Scan directory (SCAN-01 to SCAN-05)
     redactor = SecretRedactor(enabled=not no_redact)
 
+    # Classify repository topology before scanning.  This is a shallow
+    # filesystem read (depth 0-1 only) and completes in milliseconds.
+    # The topology drives per-directory depth budgets in AdaptiveScanner.
+    from sourcecode.adaptive_scanner import AdaptiveScanner
+    from sourcecode.repo_classifier import RepoClassifier
+    _topology = RepoClassifier().classify(target)
+
     # Detect manifests before scan to adjust depth.
     # find_manifests() only looks at depth 0-1, does not need the full tree.
     _pre_scanner = FileScanner(target, max_depth=1)
@@ -735,7 +742,7 @@ def main(
         no_tree = True  # agents never need the raw file tree
         typer.echo("[agent] dependencies env-map code-notes (no-tree)", err=True)
 
-    scanner = FileScanner(target, max_depth=effective_depth)
+    scanner = AdaptiveScanner(target, topology=_topology, base_depth=effective_depth)
     raw_tree = scanner.scan_tree()
 
     # 2. Filter .env and *.secret entries from file tree (SEC-02, all levels)
@@ -775,16 +782,14 @@ def main(
     detector = ProjectDetector(build_default_detectors())
     workspace_analysis = WorkspaceAnalyzer().analyze(target, manifests)
 
-    # Warn when scanning a monorepo at default depth — typical package sources
-    # (packages/*/src/) live at depth 5+, so default depth=4 silently misses them.
-    # Only emit to TTY to avoid contaminating piped/CI output; agents read analysis_gaps.
+    # Adaptive traversal handles monorepo source root discovery automatically.
+    # Emit a diagnostic when topology confidence is low so users know why.
     import sys as _sys
-    if workspace_analysis.is_monorepo and depth <= 4 and effective_depth <= 4:
+    if _topology.workspace_type == "monorepo" and _topology.confidence < 0.5:
         if _sys.stderr.isatty():
             typer.echo(
-                f"[warning] monorepo detected with --depth {depth}. "
-                "Source files in packages/*/src/ (depth 5+) may be invisible. "
-                "Use --depth 6 or higher for full coverage.",
+                "[traversal] monorepo detected but source root confidence is low "
+                f"({_topology.confidence:.0%}). Use --depth 8 or higher if files are missing.",
                 err=True,
             )
 
@@ -896,7 +901,8 @@ def main(
         workspace_root = target / workspace.path
         if not workspace_root.exists() or not workspace_root.is_dir():
             continue
-        workspace_scanner = FileScanner(workspace_root, max_depth=depth)
+        _ws_topology = RepoClassifier().classify(workspace_root)
+        workspace_scanner = AdaptiveScanner(workspace_root, topology=_ws_topology, base_depth=depth)
         workspace_tree = filter_sensitive_files(workspace_scanner.scan_tree())
         workspace_manifests = workspace_scanner.find_manifests()
         workspace_stacks, workspace_entry_points, _ = detector.detect(
@@ -1008,6 +1014,7 @@ def main(
     metadata = AnalysisMetadata(
         analyzed_path=str(target),
         analyzer_fingerprints=_fingerprints,
+        traversal_topology=_topology.as_dict(),
     )
     sm = SourceMap(
         metadata=metadata,
@@ -1037,7 +1044,7 @@ def main(
                     target / ws.path,
                     (
                         filter_sensitive_files(
-                            FileScanner(target / ws.path, max_depth=depth).scan_tree()
+                            AdaptiveScanner(target / ws.path, base_depth=depth).scan_tree()
                         )
                     ),
                     workspace=ws.path,

sourcecode/repo_classifier.py

@@ -0,0 +1,570 @@
+from __future__ import annotations
+
+"""Repository topology classifier for adaptive traversal.
+
+Detects monorepo vs single-package structure, identifies source roots,
+low-signal directories, and generated content. Feeds AdaptiveScanner
+with per-path depth budgets so traversal is relevance-oriented, not
+purely structural.
+"""
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+# ---------------------------------------------------------------------------
+# Signal tables
+# ---------------------------------------------------------------------------
+
+# Top-level dirs that almost always contain actual source code
+_SOURCE_DIRS: frozenset[str] = frozenset({
+    "src", "lib", "source", "sources", "core",
+    "app", "server", "client", "backend", "frontend",
+    "cmd", "pkg",          # Go conventions
+    "main",                # Java src/main
+    "kotlin", "java", "scala",  # JVM source dirs
+})
+
+# First-level dirs that act as workspace containers in monorepos
+_WORKSPACE_CONTAINERS: frozenset[str] = frozenset({
+    "packages", "apps", "libs", "services", "internal",
+    "plugins", "modules", "components", "crates",
+    "workspaces", "projects",
+})
+
+# Directories with low signal value for AI code understanding
+_LOW_SIGNAL_DIRS: frozenset[str] = frozenset({
+    "docs", "doc", "documentation", "docsrc", "website", "site",
+    "benchmark", "benchmarks", "bench", "perf", "perfs",
+    "examples", "example", "demo", "demos", "sample", "samples",
+    "fixtures", "fixture", "__fixtures__",
+    "scripts", "script", "tools", "tool",
+    "ci", ".ci",
+    "storybook", "stories", "__stories__",
+    "sandbox", "playground", "playgrounds",
+    "migrations", "migration",
+    ".github", ".vscode", ".claude", ".cursor", ".idea",
+    "themes", "theme",
+    "static", "public", "assets",
+})
+
+# Directories to skip entirely — generated content and dependency stores
+_GENERATED_DIRS: frozenset[str] = frozenset({
+    "dist", "build", "out", "output", "release", "releases",
+    "target", "coverage", ".next", ".nuxt", ".svelte-kit",
+    ".turbo", "node_modules", "__pycache__",
+    ".venv", "venv", "env",
+    ".mypy_cache", ".pytest_cache", ".ruff_cache",
+    ".nyc_output", ".tox",
+    "generated", ".generated", "gen", "_gen",
+    ".cache", "cache",
+    "vendor",
+    ".git",
+})
+
+# Manifest file names that mark a directory as a source package
+_PACKAGE_MANIFESTS: frozenset[str] = frozenset({
+    "package.json", "pyproject.toml", "setup.py", "setup.cfg",
+    "go.mod", "Cargo.toml", "pom.xml", "build.gradle",
+    "build.gradle.kts", "composer.json", "Gemfile", "pubspec.yaml",
+})
+
+# Source file extensions — presence signals a directory has real code
+_SOURCE_EXTENSIONS: frozenset[str] = frozenset({
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+    ".py", ".go", ".rs", ".java", ".kt", ".rb",
+    ".cs", ".swift", ".scala", ".cpp", ".c", ".h",
+})
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SourceRoot:
+    """A classified directory with traversal priority and depth budget."""
+    path: str       # repo-relative path, forward slashes
+    signal: str     # "high" | "medium" | "low" | "excluded"
+    reason: str     # human-readable explanation
+    priority: float  # 0.0–1.0 traversal priority
+
+
+@dataclass
+class ScanBudget:
+    """Per-topology traversal budget constraints."""
+    max_files: int = 2000
+    base_depth: int = 4      # depth cap for unclassified paths
+    source_depth: int = 8    # additional levels allowed inside source roots
+    low_signal_depth: int = 2  # additional levels allowed inside low-signal roots
+
+
+@dataclass
+class RepoTopology:
+    """Classified repository topology for adaptive traversal.
+
+    Produced by RepoClassifier.classify() and consumed by AdaptiveScanner.
+    The three root lists partition the repository's first-level directories
+    into source code, low-value content, and generated/excluded content.
+    """
+    workspace_type: str = "unknown"  # "monorepo" | "single-package" | "unknown"
+    source_roots: list[SourceRoot] = field(default_factory=list)
+    low_signal_roots: list[SourceRoot] = field(default_factory=list)
+    generated_roots: list[SourceRoot] = field(default_factory=list)
+    package_manager: str = "unknown"
+    confidence: float = 0.0
+    scan_budget: ScanBudget = field(default_factory=ScanBudget)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "workspace_type": self.workspace_type,
+            "source_roots": [
+                {"path": r.path, "reason": r.reason, "priority": round(r.priority, 2)}
+                for r in self.source_roots
+            ],
+            "low_signal_roots": [r.path for r in self.low_signal_roots],
+            "generated_roots": [r.path for r in self.generated_roots],
+            "package_manager": self.package_manager,
+            "confidence": round(self.confidence, 2),
+            "scan_budget": {
+                "base_depth": self.scan_budget.base_depth,
+                "source_depth": self.scan_budget.source_depth,
+                "low_signal_depth": self.scan_budget.low_signal_depth,
+            },
+        }
+
+
+# ---------------------------------------------------------------------------
+# RepoClassifier
+# ---------------------------------------------------------------------------
+
+class RepoClassifier:
+    """Detects repository topology and classifies directories for adaptive traversal.
+
+    Reads workspace config files (pnpm-workspace.yaml, package.json workspaces,
+    turbo.json, nx.json, lerna.json, go.work, Cargo.toml), resolves package
+    glob patterns, and identifies which directories contain real source code
+    vs. docs, benchmarks, or generated content.
+
+    Classification is fast: only depth-0 and depth-1 filesystem reads.
+    """
+
+    def classify(self, root: Path) -> RepoTopology:
+        """Classify the repository at *root* and return its topology."""
+        topology = RepoTopology()
+        topology.package_manager = self._detect_package_manager(root)
+
+        markers = self._detect_markers(root)
+        workspace_patterns = self._read_workspace_patterns(root, markers)
+
+        try:
+            root_children = [
+                d for d in sorted(root.iterdir())
+                if d.is_dir() and not d.is_symlink()
+            ]
+        except PermissionError:
+            root_children = []
+
+        source_roots = self._find_source_roots(
+            root, root_children, workspace_patterns, bool(markers) or bool(workspace_patterns)
+        )
+        low_signal_roots = self._find_low_signal_roots(root, root_children, source_roots)
+        generated_roots = self._find_generated_roots(root, root_children)
+
+        # Monorepo heuristic: explicit markers OR multiple packages found via
+        # workspace containers (packages/*, apps/*, etc.) without top-level src/
+        container_sourced = [
+            r for r in source_roots
+            if "container:" in r.reason or "workspace:" in r.reason
+        ]
+        has_top_level_src = any(
+            r.reason == "top_level_source" for r in source_roots
+        )
+        is_monorepo = (
+            bool(markers)
+            or bool(workspace_patterns)
+            or (len(container_sourced) >= 2 and not has_top_level_src)
+        )
+        topology.workspace_type = "monorepo" if is_monorepo else "single-package"
+
+        topology.source_roots = sorted(source_roots, key=lambda r: -r.priority)
+        topology.low_signal_roots = low_signal_roots
+        topology.generated_roots = generated_roots
+        topology.confidence = self._compute_confidence(topology, is_monorepo)
+        topology.scan_budget = self._compute_budget(topology)
+
+        return topology
+
+    # ------------------------------------------------------------------
+    # Package manager detection
+    # ------------------------------------------------------------------
+
+    def _detect_package_manager(self, root: Path) -> str:
+        if (root / "pnpm-lock.yaml").exists() or (root / "pnpm-workspace.yaml").exists():
+            return "pnpm"
+        if (root / "yarn.lock").exists():
+            return "yarn"
+        if (root / "bun.lockb").exists() or (root / "bun.lock").exists():
+            return "bun"
+        if (root / "package-lock.json").exists():
+            return "npm"
+        if (root / "go.work").exists():
+            return "go-workspace"
+        if (root / "go.mod").exists():
+            return "go-modules"
+        if (root / "Cargo.toml").exists():
+            return "cargo"
+        if (root / "uv.lock").exists():
+            return "uv"
+        if (root / "Pipfile").exists():
+            return "pipenv"
+        if (root / "pyproject.toml").exists() or (root / "setup.py").exists():
+            return "python"
+        return "unknown"
+
+    # ------------------------------------------------------------------
+    # Workspace marker detection
+    # ------------------------------------------------------------------
+
+    def _detect_markers(self, root: Path) -> list[str]:
+        """Return list of workspace marker file names present at root."""
+        markers: list[str] = []
+        for name in ("pnpm-workspace.yaml", "go.work", "turbo.json", "lerna.json", "nx.json"):
+            if (root / name).exists():
+                markers.append(name)
+
+        cargo = root / "Cargo.toml"
+        if cargo.exists():
+            try:
+                content = cargo.read_text(encoding="utf-8", errors="replace")
+                if "[workspace]" in content:
+                    markers.append("Cargo.toml[workspace]")
+            except OSError:
+                pass
+
+        pkg = root / "package.json"
+        if pkg.exists():
+            try:
+                data = json.loads(pkg.read_text(encoding="utf-8", errors="replace"))
+                if "workspaces" in data:
+                    markers.append("package.json[workspaces]")
+            except (json.JSONDecodeError, OSError, ValueError):
+                pass
+
+        return markers
+
+    # ------------------------------------------------------------------
+    # Workspace pattern extraction from config files
+    # ------------------------------------------------------------------
+
+    def _read_workspace_patterns(self, root: Path, markers: list[str]) -> list[str]:
+        """Extract glob patterns from workspace config files."""
+        patterns: list[str] = []
+
+        if "pnpm-workspace.yaml" in markers:
+            patterns.extend(self._patterns_from_pnpm(root))
+
+        if "package.json[workspaces]" in markers:
+            patterns.extend(self._patterns_from_npm_workspaces(root))
+
+        if "nx.json" in markers:
+            patterns.extend(self._patterns_from_nx(root))
+
+        if "lerna.json" in markers:
+            patterns.extend(self._patterns_from_lerna(root))
+
+        if "Cargo.toml[workspace]" in markers:
+            patterns.extend(self._patterns_from_cargo_workspace(root))
+
+        if "go.work" in markers:
+            patterns.extend(self._patterns_from_go_work(root))
+
+        return list(dict.fromkeys(patterns))  # deduplicate, preserve order
+
+    def _patterns_from_pnpm(self, root: Path) -> list[str]:
+        try:
+            content = (root / "pnpm-workspace.yaml").read_text(encoding="utf-8", errors="replace")
+            result = []
+            for line in content.splitlines():
+                stripped = line.strip().lstrip("- ").strip("'\"")
+                if stripped and not stripped.startswith("#"):
+                    result.append(stripped)
+            return result
+        except OSError:
+            return []
+
+    def _patterns_from_npm_workspaces(self, root: Path) -> list[str]:
+        try:
+            data = json.loads((root / "package.json").read_text(encoding="utf-8", errors="replace"))
+            ws = data.get("workspaces", [])
+            if isinstance(ws, list):
+                return [str(p) for p in ws]
+            if isinstance(ws, dict):
+                return [str(p) for p in ws.get("packages", [])]
+        except (json.JSONDecodeError, OSError, ValueError):
+            pass
+        return []
+
+    def _patterns_from_nx(self, root: Path) -> list[str]:
+        try:
+            data = json.loads((root / "nx.json").read_text(encoding="utf-8", errors="replace"))
+            patterns = []
+            wl = data.get("workspaceLayout", {})
+            if "appsDir" in wl:
+                patterns.append(f"{wl['appsDir']}/*")
+            if "libsDir" in wl:
+                patterns.append(f"{wl['libsDir']}/*")
+            return patterns
+        except (json.JSONDecodeError, OSError, ValueError):
+            return []
+
+    def _patterns_from_lerna(self, root: Path) -> list[str]:
+        try:
+            data = json.loads((root / "lerna.json").read_text(encoding="utf-8", errors="replace"))
+            pkgs = data.get("packages", ["packages/*"])
+            return [str(p) for p in pkgs] if isinstance(pkgs, list) else []
+        except (json.JSONDecodeError, OSError, ValueError):
+            return []
+
+    def _patterns_from_cargo_workspace(self, root: Path) -> list[str]:
+        try:
+            content = (root / "Cargo.toml").read_text(encoding="utf-8", errors="replace")
+            in_members = False
+            patterns = []
+            for line in content.splitlines():
+                stripped = line.strip()
+                if "members" in stripped and "=" in stripped:
+                    in_members = True
+                if in_members:
+                    for quote in ('"', "'"):
+                        if quote in stripped:
+                            for segment in stripped.split(quote):
+                                segment = segment.strip(" [],")
+                                if segment and "/" in segment:
+                                    patterns.append(segment)
+                    if "]" in stripped:
+                        in_members = False
+            return patterns
+        except OSError:
+            return []
+
+    def _patterns_from_go_work(self, root: Path) -> list[str]:
+        try:
+            content = (root / "go.work").read_text(encoding="utf-8", errors="replace")
+            patterns = []
+            for line in content.splitlines():
+                stripped = line.strip()
+                if stripped.startswith("use "):
+                    target = stripped[4:].strip().strip("()")
+                    if target and target != ".":
+                        patterns.append(target.removeprefix("./").rstrip("/"))
+                elif stripped.startswith("./") and not stripped.startswith("//"):
+                    patterns.append(stripped.removeprefix("./").rstrip())
+            return patterns
+        except OSError:
+            return []
+
+    # ------------------------------------------------------------------
+    # Source root discovery
+    # ------------------------------------------------------------------
+
+    def _find_source_roots(
+        self,
+        root: Path,
+        root_children: list[Path],
+        workspace_patterns: list[str],
+        is_monorepo: bool,
+    ) -> list[SourceRoot]:
+        """Identify directories that contain actual source code."""
+        result: list[SourceRoot] = []
+        seen: set[str] = set()
+
+        def _add(path_str: str, reason: str, priority: float) -> None:
+            if path_str not in seen:
+                seen.add(path_str)
+                result.append(SourceRoot(
+                    path=path_str, signal="high", reason=reason, priority=priority
+                ))
+
+        # 1. Resolve workspace glob patterns → packages → src/
+        for pattern in workspace_patterns:
+            try:
+                for pkg_dir in sorted(root.glob(pattern)):
+                    if not pkg_dir.is_dir() or pkg_dir.is_symlink():
+                        continue
+                    try:
+                        rel = pkg_dir.relative_to(root)
+                    except ValueError:
+                        continue
+                    rel_str = str(rel).replace("\\", "/")
+                    if not self._is_allowed_path(rel_str):
+                        continue
+
+                    found_src = False
+                    for src_name in ("src", "lib", "source"):
+                        src_dir = pkg_dir / src_name
+                        if src_dir.is_dir() and not src_dir.is_symlink():
+                            _add(f"{rel_str}/{src_name}", f"workspace:{pattern}", 0.92)
+                            found_src = True
+
+                    if not found_src and self._has_source_signal(pkg_dir):
+                        _add(rel_str, f"workspace_flat:{pattern}", 0.72)
+            except Exception:
+                continue
+
+        # 2. Check known workspace container dirs even without explicit patterns
+        for child in root_children:
+            name = child.name
+            if name not in _WORKSPACE_CONTAINERS:
+                continue
+            try:
+                for pkg_dir in sorted(child.iterdir()):
+                    if not pkg_dir.is_dir() or pkg_dir.is_symlink():
+                        continue
+                    try:
+                        rel = pkg_dir.relative_to(root)
+                    except ValueError:
+                        continue
+                    rel_str = str(rel).replace("\\", "/")
+                    if not self._is_allowed_path(rel_str):
+                        continue
+
+                    found_src = False
+                    for src_name in ("src", "lib", "source"):
+                        src_dir = pkg_dir / src_name
+                        if src_dir.is_dir() and not src_dir.is_symlink():
+                            _add(f"{rel_str}/{src_name}", f"container:{name}", 0.88)
+                            found_src = True
+
+                    if not found_src and self._has_source_signal(pkg_dir):
+                        _add(rel_str, f"container_flat:{name}", 0.68)
+            except PermissionError:
+                continue
+
+        # 3. Top-level source dirs (single-package repos or workspace containers)
+        for child in root_children:
+            name = child.name
+            if name in _SOURCE_DIRS and name not in _GENERATED_DIRS:
+                try:
+                    rel_str = str(child.relative_to(root)).replace("\\", "/")
+                    _add(rel_str, "top_level_source", 0.95)
+                except ValueError:
+                    pass
+
+        # 4. Workspace containers themselves if they contain source files at root
+        for child in root_children:
+            name = child.name
+            if name in _WORKSPACE_CONTAINERS and name not in _GENERATED_DIRS:
+                try:
+                    rel_str = str(child.relative_to(root)).replace("\\", "/")
+                except ValueError:
+                    continue
+                if rel_str not in seen and self._has_source_signal(child):
+                    _add(rel_str, f"workspace_container_source:{name}", 0.55)
+
+        return result
+
+    def _has_source_signal(self, directory: Path) -> bool:
+        """Return True if directory has a manifest or source files."""
+        for name in _PACKAGE_MANIFESTS:
+            if (directory / name).exists():
+                return True
+        try:
+            for entry in directory.iterdir():
+                if entry.is_file() and entry.suffix.lower() in _SOURCE_EXTENSIONS:
+                    return True
+                if entry.name in _PACKAGE_MANIFESTS:
+                    return True
+        except PermissionError:
+            pass
+        return False
+
+    def _is_allowed_path(self, rel_str: str) -> bool:
+        parts = rel_str.split("/")
+        return all(p not in _GENERATED_DIRS for p in parts)
+
+    # ------------------------------------------------------------------
+    # Low-signal root discovery
+    # ------------------------------------------------------------------
+
+    def _find_low_signal_roots(
+        self,
+        root: Path,
+        root_children: list[Path],
+        source_roots: list[SourceRoot],
+    ) -> list[SourceRoot]:
+        """Identify root-level directories with low signal value."""
+        top_source_names = {sr.path.split("/")[0] for sr in source_roots}
+        low_signal: list[SourceRoot] = []
+
+        for child in root_children:
+            name = child.name
+            if name in top_source_names or name in _GENERATED_DIRS:
+                continue
+            try:
+                rel_str = str(child.relative_to(root)).replace("\\", "/")
+            except ValueError:
+                continue
+
+            if name in _LOW_SIGNAL_DIRS:
+                low_signal.append(SourceRoot(
+                    path=rel_str, signal="low",
+                    reason=f"low_signal:{name}", priority=0.15,
+                ))
+            elif name.startswith("."):
+                low_signal.append(SourceRoot(
+                    path=rel_str, signal="low",
+                    reason="hidden_dir", priority=0.05,
+                ))
+
+        return low_signal
+
+    # ------------------------------------------------------------------
+    # Generated root discovery
+    # ------------------------------------------------------------------
+
+    def _find_generated_roots(
+        self,
+        root: Path,
+        root_children: list[Path],
+    ) -> list[SourceRoot]:
+        """Identify root-level generated/excluded directories."""
+        generated: list[SourceRoot] = []
+        for child in root_children:
+            name = child.name
+            if name in _GENERATED_DIRS:
+                generated.append(SourceRoot(
+                    path=name, signal="excluded",
+                    reason=f"generated:{name}", priority=0.0,
+                ))
+        return generated
+
+    # ------------------------------------------------------------------
+    # Budget and confidence
+    # ------------------------------------------------------------------
+
+    def _compute_confidence(self, topology: RepoTopology, is_monorepo: bool) -> float:
+        sc = len(topology.source_roots)
+        if sc >= 5:
+            return 0.95
+        if sc >= 2:
+            return 0.85
+        if sc >= 1:
+            return 0.75 if is_monorepo else 0.80
+        return 0.30
+
+    def _compute_budget(self, topology: RepoTopology) -> ScanBudget:
+        if topology.workspace_type == "monorepo":
+            return ScanBudget(
+                max_files=2000,
+                base_depth=4,
+                source_depth=8,
+                low_signal_depth=2,
+            )
+        return ScanBudget(
+            max_files=2000,
+            base_depth=6,
+            source_depth=8,
+            low_signal_depth=2,
+        )

sourcecode/schema.py

@@ -34,6 +34,7 @@ class AnalysisMetadata:
     sourcecode_version: str = field(default_factory=_sourcecode_version)
     analyzed_path: str = ""
     analyzer_fingerprints: dict[str, str] = field(default_factory=dict)
+    traversal_topology: Optional[dict[str, Any]] = None
 
 
 @dataclass

sourcecode/serializer.py

@@ -927,6 +927,9 @@ def _contract_view_minimal(
         "project": project,
     }
 
+    if sm.metadata.traversal_topology:
+        result["traversal"] = sm.metadata.traversal_topology
+
     # Per-file contracts
     if contracts:
         serialized: list[dict[str, Any]] = []
@@ -1170,6 +1173,8 @@ def _contract_view_standard(
         ],
         "entry_points": ep_groups["production"],
     }
+    if sm.metadata.traversal_topology:
+        result["traversal"] = sm.metadata.traversal_topology
     if ep_groups["development"]:
         result["development_entry_points"] = ep_groups["development"]
 

{sourcecode-0.37.0.dist-info → sourcecode-0.38.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 0.37.0
+Version: 0.38.0
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004

{sourcecode-0.37.0.dist-info → sourcecode-0.38.0.dist-info}/RECORD

@@ -1,9 +1,10 @@
-sourcecode/__init__.py,sha256=Xha8jq1XWD5Ze_B5mEne-d5fOfBVVwnX-Ieg7spvalk,103
+sourcecode/__init__.py,sha256=RjrfBH06OIJiq-xk4Hadj8Zl3Soer5r1Ct1ogF0xqaU,103
+sourcecode/adaptive_scanner.py,sha256=6dh34C2qZXyRbw-8xBhbEwDdXanM6CRFRWayVoYITnA,10190
 sourcecode/architecture_analyzer.py,sha256=H6noGgVArUJ25z1qC0fFA0KvJJeHZYyhKvKSkOyWHUk,23096
 sourcecode/architecture_summary.py,sha256=rSY5MRiaz4N1YdG0pqDTDuFjSN7PO_Zplx-dtNzv2Yo,19985
 sourcecode/ast_extractor.py,sha256=0OHQwTUBBc9lmqPLryVeB1z8dGIC6NhLlar800CD9oI,41129
 sourcecode/classifier.py,sha256=GKTMN8qKZX7ponSwDJfN08RrasI4CVpq1_gFBgEopps,7093
-sourcecode/cli.py,sha256=LSGytpRlyMFdmHugrP3USDhPb0hiigHn0PL9Ppac3R4,64852
+sourcecode/cli.py,sha256=dJ0kkwC0pQ4LJyhjlbtHKSpD-TvRQQyhdhvjRCHPA8o,65280
 sourcecode/code_notes_analyzer.py,sha256=rRd8bFYV0krjlxxQV0wenwE9K7pVpUQSR7KvSvUQKw4,9226
 sourcecode/confidence_analyzer.py,sha256=HxJMPLI5ulqtkncnv98W4iVO6yMbpQo87VuxiuNbDmY,12167
 sourcecode/context_summarizer.py,sha256=CiQrfBEzun949bWvmLabWoj2HhPn6Lw62ofqnsy0FlQ,6503
@@ -21,11 +22,12 @@ sourcecode/metrics_analyzer.py,sha256=e2cFwB9XubFq_dIVsP2PLjpr4wX0N6ulb3ol3sGDUe
 sourcecode/prepare_context.py,sha256=vxEzr8czS3MFbdTx4hBJQlJLrl9cuvbHdL3ZokxFkvo,31384
 sourcecode/redactor.py,sha256=xuGcadGEHaPw4qZXlMDvzMCsr4VOkdp3oBQptHyJk8c,2884
 sourcecode/relevance_scorer.py,sha256=ea7_7AHVgahVEWK3ebKOpG67agzG_pGICu5f2KgzrIA,8133
+sourcecode/repo_classifier.py,sha256=FG1vaWKdWXsWdl-S8hjVMiTqcwgaRXkDyvK4rPcOGtQ,22681
 sourcecode/runtime_classifier.py,sha256=zWX3r3HCKHc-qtIobErOa8aKMmaoPYREtJKvPcBGPjQ,14792
 sourcecode/scanner.py,sha256=aM3h9-DCQ3xKpeHpHYdo2vX6T5P95HA_YwZbkAVNwmo,8288
-sourcecode/schema.py,sha256=AShu_bcP30TYaw4Dl1nYy8aFnBCKxrUli3LhU3MZTjs,20739
+sourcecode/schema.py,sha256=dVA-3EbHBakHLkgeZF-LfjKClEFRgPZkzblXpDTshFA,20796
 sourcecode/semantic_analyzer.py,sha256=asQfJf-EhzYaOTA-iMuZsrVXtbW7SV2WEKCxgsxa88Y,79413
-sourcecode/serializer.py,sha256=uQGcytdaaM3qzxXcZ2NMjXYvzdvT9PP45960t-Thgqk,51128
+sourcecode/serializer.py,sha256=qJRJV_z-T_wU615KMA1ez5IIeV3wcexh29lY4-fcgjs,51329
 sourcecode/summarizer.py,sha256=ZuzIdm3t8A-d5MuQL0TSNLrd-L0IQIuguIxeNXMNJf8,16070
 sourcecode/tree_utils.py,sha256=Fj9OIuUksBvgibNd3feog0sMDjVypJzPexp5lvMoYWI,1424
 sourcecode/workspace.py,sha256=fQlVoNx8S-fSHpKoJ0JBvEHCFkxszH0KZVJed1i3TRk,6845
@@ -56,8 +58,8 @@ sourcecode/telemetry/consent.py,sha256=wLMvGNJeSSyZoNkQXpoUioY6mMv4Qdvuw7S9jAEWn
 sourcecode/telemetry/events.py,sha256=oEvvulfsv5GIDWG2174gSS6tNB95w38AIYiYeifGKlE,2294
 sourcecode/telemetry/filters.py,sha256=Asa71oRl7q3Wt_FMwuufIZJFzSYdgRNKS8LHCIyFeYE,4805
 sourcecode/telemetry/transport.py,sha256=KJeIPCPWMdmbCP3ySGs2iUlia34U6vWne2dZsUezesw,1560
-sourcecode-0.37.0.dist-info/METADATA,sha256=75XE0yybH_O7U8rxcP6ZY2MdvibRaxALg4io5V9RsU4,25209
-sourcecode-0.37.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-0.37.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-0.37.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-0.37.0.dist-info/RECORD,,
+sourcecode-0.38.0.dist-info/METADATA,sha256=-RJ8bdDTHeuGmWN-iNo4eYkjPTuSnfriYYD1O59Gmwc,25209
+sourcecode-0.38.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-0.38.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-0.38.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-0.38.0.dist-info/RECORD,,