refutescan 0.1.0__tar.gz

refutescan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinay Vobbilichetty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

refutescan-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: refutescan
+Version: 0.1.0
+Summary: A two-LLM, refute-first agentic source-code vulnerability scanner — wide-net navigate, skeptical refute, jailed in docker. Bring your own LLM.
+Author-email: Vinay Vobbilichetty <vinayvobbilichetty11@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/vinayvobbili/refutescan
+Project-URL: Repository, https://github.com/vinayvobbili/refutescan
+Project-URL: Issues, https://github.com/vinayvobbili/refutescan/issues
+Keywords: security,sast,vulnerability-scanner,appsec,code-security,agentic,llm,ai-security,static-analysis,secure-code-review,false-positive-reduction,supply-chain,sandbox
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2
+Requires-Dist: langchain-core>=0.3
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=0.1; extra == "openai"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# refutescan
+
+**A two-LLM, refute-first agentic source-code vulnerability scanner.**
+
+Most LLM code scanners have the same problem: they hallucinate. Point a model at
+a repo and it will confidently report SQL injection in a parameterized query and
+SSRF behind an allowlist. The noise buries the real bugs.
+
+refutescan splits the job across two models:
+
+1. **Navigate (wide net).** A fast tool-calling model explores the repo with
+   read-only tools (`list_dir` / `read_file` / `grep`), traces untrusted input
+   toward dangerous sinks, and records *candidate* findings. It's cheap and it
+   over-reports on purpose.
+2. **Refute (skeptic).** A stronger model re-reads the actual code slice around
+   each candidate from disk — ground truth, not the navigator's paraphrase — and
+   is prompted to **refute** it. Sanitized? Parameterized? Gated by auth? Not
+   reachable? It's culled, with the reason kept. Only what survives is reported.
+
+You get the recall of an agentic scanner without the false-positive flood.
+
+Every scan runs **jailed in an ephemeral docker sandbox** by default: git URLs
+are cloned *inside a container* (no host mounts), then audited in a second
+container with **no network, read-only, no capabilities, non-root**, and only
+the repo mounted. A hostile repo (malicious submodule, hook, symlink) touches
+neither your filesystem nor the network.
+
+## Install
+
+```
+pip install refutescan            # core kernel
+pip install 'refutescan[openai]'  # + the OpenAI adapter for the CLI
+```
+
+For sandboxed scans (recommended), build the jail image once:
+
+```
+refutescan-build-sandbox
+```
+
+(Requires Docker. Without it, refutescan falls back to a guarded in-process scan.)
+
+## CLI
+
+```
+export OPENAI_API_KEY=sk-...
+refutescan https://github.com/owner/repo
+refutescan ./path/to/local/repo --judge-model gpt-4o --json
+```
+
+Exit code is non-zero when confirmed findings exist, so it drops straight into CI.
+
+## Library
+
+```python
+from refutescan import scan, ScanConfig
+from refutescan.adapters import openai_navigator_factory, openai_judge_factory
+
+result = scan(
+    "https://github.com/owner/repo",
+    navigator_factory=openai_navigator_factory("gpt-4o-mini"),
+    judge_factory=openai_judge_factory("gpt-4o"),
+    config=ScanConfig(sandbox="docker"),       # auto | docker | inprocess
+    progress=lambda phase: print(phase),
+)
+
+for f in result.findings:
+    print(f["severity"], f["title"], f"{f['file']}:{f['line']}")
+    print("  ", f["reasoning"])
+    print("  fix:", f["recommendation"])
+```
+
+`result.culled` holds the refuted candidates with the reason each was rejected —
+useful for tuning and for trusting the tool.
+
+## Bring your own model
+
+refutescan never imports a provider SDK in its core. Pass any LangChain-style
+chat model through two factories:
+
+- `navigator_factory() -> chat_model` — supports `.bind_tools(...)` + `.invoke(...)`
+- `judge_factory() -> judge(prompt, schema) -> instance` — one structured-output call
+
+So a local model (vLLM/Ollama via the OpenAI shim, `--base-url`), Anthropic,
+Azure OpenAI, or a corporate gateway all work — wire the factory and go. See
+`refutescan/providers.py`.
+
+## What it is and isn't
+
+- **Is:** an agentic, read-only, false-positive-resistant first-pass auditor for
+  the common web-app vuln classes (injection, authz/IDOR, SSRF, path traversal,
+  unsafe deserialization, hardcoded secrets, weak crypto, XSS, auth flaws).
+- **Isn't:** a replacement for a full SAST suite, a proof of exploitability, or a
+  patch generator. It finds and explains; a human confirms and fixes.
+
+## License
+
+MIT.

refutescan-0.1.0/README.md

@@ -0,0 +1,98 @@
+# refutescan
+
+**A two-LLM, refute-first agentic source-code vulnerability scanner.**
+
+Most LLM code scanners have the same problem: they hallucinate. Point a model at
+a repo and it will confidently report SQL injection in a parameterized query and
+SSRF behind an allowlist. The noise buries the real bugs.
+
+refutescan splits the job across two models:
+
+1. **Navigate (wide net).** A fast tool-calling model explores the repo with
+   read-only tools (`list_dir` / `read_file` / `grep`), traces untrusted input
+   toward dangerous sinks, and records *candidate* findings. It's cheap and it
+   over-reports on purpose.
+2. **Refute (skeptic).** A stronger model re-reads the actual code slice around
+   each candidate from disk — ground truth, not the navigator's paraphrase — and
+   is prompted to **refute** it. Sanitized? Parameterized? Gated by auth? Not
+   reachable? It's culled, with the reason kept. Only what survives is reported.
+
+You get the recall of an agentic scanner without the false-positive flood.
+
+Every scan runs **jailed in an ephemeral docker sandbox** by default: git URLs
+are cloned *inside a container* (no host mounts), then audited in a second
+container with **no network, read-only, no capabilities, non-root**, and only
+the repo mounted. A hostile repo (malicious submodule, hook, symlink) touches
+neither your filesystem nor the network.
+
+## Install
+
+```
+pip install refutescan            # core kernel
+pip install 'refutescan[openai]'  # + the OpenAI adapter for the CLI
+```
+
+For sandboxed scans (recommended), build the jail image once:
+
+```
+refutescan-build-sandbox
+```
+
+(Requires Docker. Without it, refutescan falls back to a guarded in-process scan.)
+
+## CLI
+
+```
+export OPENAI_API_KEY=sk-...
+refutescan https://github.com/owner/repo
+refutescan ./path/to/local/repo --judge-model gpt-4o --json
+```
+
+Exit code is non-zero when confirmed findings exist, so it drops straight into CI.
+
+## Library
+
+```python
+from refutescan import scan, ScanConfig
+from refutescan.adapters import openai_navigator_factory, openai_judge_factory
+
+result = scan(
+    "https://github.com/owner/repo",
+    navigator_factory=openai_navigator_factory("gpt-4o-mini"),
+    judge_factory=openai_judge_factory("gpt-4o"),
+    config=ScanConfig(sandbox="docker"),       # auto | docker | inprocess
+    progress=lambda phase: print(phase),
+)
+
+for f in result.findings:
+    print(f["severity"], f["title"], f"{f['file']}:{f['line']}")
+    print("  ", f["reasoning"])
+    print("  fix:", f["recommendation"])
+```
+
+`result.culled` holds the refuted candidates with the reason each was rejected —
+useful for tuning and for trusting the tool.
+
+## Bring your own model
+
+refutescan never imports a provider SDK in its core. Pass any LangChain-style
+chat model through two factories:
+
+- `navigator_factory() -> chat_model` — supports `.bind_tools(...)` + `.invoke(...)`
+- `judge_factory() -> judge(prompt, schema) -> instance` — one structured-output call
+
+So a local model (vLLM/Ollama via the OpenAI shim, `--base-url`), Anthropic,
+Azure OpenAI, or a corporate gateway all work — wire the factory and go. See
+`refutescan/providers.py`.
+
+## What it is and isn't
+
+- **Is:** an agentic, read-only, false-positive-resistant first-pass auditor for
+  the common web-app vuln classes (injection, authz/IDOR, SSRF, path traversal,
+  unsafe deserialization, hardcoded secrets, weak crypto, XSS, auth flaws).
+- **Isn't:** a replacement for a full SAST suite, a proof of exploitability, or a
+  patch generator. It finds and explains; a human confirms and fixes.
+
+## License
+
+MIT.

refutescan-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "refutescan"
+version = "0.1.0"
+description = "A two-LLM, refute-first agentic source-code vulnerability scanner — wide-net navigate, skeptical refute, jailed in docker. Bring your own LLM."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Vinay Vobbilichetty", email = "vinayvobbilichetty11@gmail.com" }]
+keywords = [
+    "security", "sast", "vulnerability-scanner", "appsec", "code-security",
+    "agentic", "llm", "ai-security", "static-analysis", "secure-code-review",
+    "false-positive-reduction", "supply-chain", "sandbox",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Quality Assurance",
+]
+# Core: the kernel + the LangChain interface the navigator/judge speak. Provider
+# SDKs are opt-in extras — bring your own model.
+dependencies = [
+    "pydantic>=2",
+    "langchain-core>=0.3",
+]
+
+[project.optional-dependencies]
+openai = ["langchain-openai>=0.1"]
+dev = [
+    "pytest>=7",
+    "ruff>=0.4",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.scripts]
+refutescan = "refutescan.cli:main"
+refutescan-build-sandbox = "refutescan.cli:build_sandbox"
+
+[project.urls]
+Homepage = "https://github.com/vinayvobbili/refutescan"
+Repository = "https://github.com/vinayvobbili/refutescan"
+Issues = "https://github.com/vinayvobbili/refutescan/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# The sandbox image source ships with the package so `refutescan-build-sandbox`
+# can build it from the installed location.
+"refutescan.sandbox" = ["Dockerfile", "build.sh", "toolrunner.py"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

refutescan-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

refutescan-0.1.0/src/refutescan/__init__.py

@@ -0,0 +1,38 @@
+"""refutescan — a two-LLM, refute-first agentic source-code vulnerability scanner.
+
+A fast model NAVIGATES the repo with read-only tools and casts a wide net of
+candidate findings; a stronger model then REFUTES each one against the real code
+slice before it surfaces — so you get the recall of an agentic scanner without
+the false-positive flood. Scans run jailed in an ephemeral docker sandbox
+(clone-in-container, no network, read-only, non-root) by default. Bring your own
+LLMs.
+
+    from refutescan import scan
+    from refutescan.adapters import openai_navigator_factory, openai_judge_factory
+
+    result = scan(
+        "https://github.com/owner/repo",
+        navigator_factory=openai_navigator_factory(),
+        judge_factory=openai_judge_factory(),
+    )
+    for f in result.findings:
+        print(f["severity"], f["title"], f["file"], f["line"])
+"""
+
+from .models import ScanConfig, ScanResult, Verdict
+from .scanner import derive_title, looks_like_git_url, scan
+from .vulns import SEVERITIES, VULN_CLASSES
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "scan",
+    "ScanConfig",
+    "ScanResult",
+    "Verdict",
+    "VULN_CLASSES",
+    "SEVERITIES",
+    "looks_like_git_url",
+    "derive_title",
+    "__version__",
+]

refutescan-0.1.0/src/refutescan/adapters/__init__.py

@@ -0,0 +1,11 @@
+"""Ready-made model factories for common providers.
+
+These are thin conveniences over LangChain chat models so you don't have to wire
+the injection seam yourself. Import the one you want; each needs its provider
+extra installed (e.g. ``pip install refutescan[openai]``). Bring your own by
+passing any LangChain-style chat model — see ``refutescan.providers``.
+"""
+
+from .openai_chat import openai_judge_factory, openai_navigator_factory
+
+__all__ = ["openai_navigator_factory", "openai_judge_factory"]

refutescan-0.1.0/src/refutescan/adapters/openai_chat.py

@@ -0,0 +1,51 @@
+"""OpenAI (or any OpenAI-compatible endpoint) model factories.
+
+Requires ``langchain-openai`` (the ``openai`` extra). Set ``OPENAI_API_KEY``, or
+pass ``base_url`` to point at a compatible gateway (vLLM, Ollama's OpenAI shim,
+Azure OpenAI, a local proxy, …).
+
+    from refutescan import scan
+    from refutescan.adapters import openai_navigator_factory, openai_judge_factory
+
+    result = scan(
+        "https://github.com/owner/repo",
+        navigator_factory=openai_navigator_factory("gpt-4o-mini"),
+        judge_factory=openai_judge_factory("gpt-4o"),
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..providers import JudgeFactory, NavigatorFactory
+
+
+def _chat(model: str, **kwargs: Any):
+    try:
+        from langchain_openai import ChatOpenAI
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            "refutescan's OpenAI adapter needs langchain-openai. "
+            "Install it with: pip install 'refutescan[openai]'"
+        ) from e
+    return ChatOpenAI(model=model, temperature=0, **kwargs)
+
+
+def openai_navigator_factory(model: str = "gpt-4o-mini", **kwargs: Any) -> NavigatorFactory:
+    """A navigator factory using a fast OpenAI tool-calling model (the wide-net pass)."""
+    def factory():
+        return _chat(model, **kwargs)
+    return factory
+
+
+def openai_judge_factory(model: str = "gpt-4o", **kwargs: Any) -> JudgeFactory:
+    """A judge factory using a stronger OpenAI model with structured output (refute pass)."""
+    def factory():
+        llm = _chat(model, **kwargs)
+
+        def judge(prompt: str, schema: type):
+            return llm.with_structured_output(schema).invoke(prompt)
+
+        return judge
+    return factory

refutescan-0.1.0/src/refutescan/cli.py

@@ -0,0 +1,116 @@
+"""Command-line entry points.
+
+  refutescan <path-or-git-url> [options]   — run a scan, print findings
+  refutescan-build-sandbox                 — build the docker jail image
+
+The scan CLI uses the OpenAI adapter by default (needs the ``openai`` extra and
+OPENAI_API_KEY, or --base-url for a compatible gateway). For other providers,
+call ``refutescan.scan`` directly with your own factories.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+
+from . import __version__
+from .models import ScanConfig
+
+
+def _sev_marker(sev: str) -> str:
+    return {"critical": "[CRIT]", "high": "[HIGH]", "medium": "[MED ]",
+            "low": "[LOW ]", "info": "[INFO]"}.get(sev, "[????]")
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="refutescan",
+        description="Two-LLM, refute-first agentic source-code vulnerability scanner.")
+    ap.add_argument("source", help="a local directory path or a git URL to clone")
+    ap.add_argument("--branch", default="", help="git branch to clone (git sources only)")
+    ap.add_argument("--sandbox", default="auto", choices=["auto", "docker", "inprocess"],
+                    help="isolation backend (default: auto)")
+    ap.add_argument("--navigator-model", default="gpt-4o-mini",
+                    help="navigator (wide-net) model (default: gpt-4o-mini)")
+    ap.add_argument("--judge-model", default="gpt-4o",
+                    help="judge (refute) model (default: gpt-4o)")
+    ap.add_argument("--base-url", default=None,
+                    help="OpenAI-compatible base URL (vLLM, Azure, local proxy, …)")
+    ap.add_argument("--json", action="store_true", help="emit the full result as JSON")
+    ap.add_argument("--version", action="version", version=f"refutescan {__version__}")
+    args = ap.parse_args(argv)
+
+    try:
+        from .adapters import openai_judge_factory, openai_navigator_factory
+    except Exception as e:  # pragma: no cover
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    kw = {"base_url": args.base_url} if args.base_url else {}
+    from . import scan
+
+    def _progress(phase: str) -> None:
+        if not args.json:
+            print(f"  … {phase}", file=sys.stderr)
+
+    try:
+        result = scan(
+            args.source,
+            navigator_factory=openai_navigator_factory(args.navigator_model, **kw),
+            judge_factory=openai_judge_factory(args.judge_model, **kw),
+            branch=args.branch,
+            config=ScanConfig(sandbox=args.sandbox),
+            progress=_progress,
+        )
+    except Exception as e:
+        print(f"scan failed: {type(e).__name__}: {e}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(result.model_dump_json(indent=2))
+        return 0 if not result.findings else 1
+
+    s = result.summary
+    print(f"\nScanned {s.get('files_scanned')} files / {s.get('total_loc')} LOC"
+          f"  ·  {'sandboxed' if result.sandboxed else 'in-process'}")
+    print(f"{result.candidate_count} candidate(s) → {len(result.findings)} confirmed, "
+          f"{len(result.culled)} culled\n")
+    if not result.findings:
+        print("No confirmed findings.")
+        return 0
+    for f in result.findings:
+        conf = f.get("confidence")
+        conf_s = f" (conf {conf:.2f})" if isinstance(conf, (int, float)) else ""
+        print(f"{_sev_marker(f.get('severity', ''))} {f.get('title')}{conf_s}")
+        print(f"        {f.get('file')}:{f.get('line')}  [{f.get('vuln_class')}]")
+        if f.get("reasoning"):
+            print(f"        {f['reasoning']}")
+        print()
+    return 1  # non-zero exit when findings exist (CI-friendly)
+
+
+def build_sandbox(argv=None) -> int:
+    """Build the docker jail image (refutescan-build-sandbox)."""
+    from .sandbox.docker import sandbox_dir
+    ap = argparse.ArgumentParser(
+        prog="refutescan-build-sandbox",
+        description="Build the refutescan docker sandbox image.")
+    ap.add_argument("--image", default="refutescan-sandbox:current", help="image tag to build")
+    args = ap.parse_args(argv)
+    d = sandbox_dir()
+    print(f"Building {args.image} from {d} ...")
+    try:
+        subprocess.run(["docker", "build", "-t", args.image, str(d)], check=True)
+    except FileNotFoundError:
+        print("error: docker not found on PATH", file=sys.stderr)
+        return 2
+    except subprocess.CalledProcessError as e:
+        print(f"docker build failed ({e.returncode})", file=sys.stderr)
+        return e.returncode
+    print(f"Done. Image: {args.image}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

refutescan-0.1.0/src/refutescan/codemap.py

@@ -0,0 +1,84 @@
+"""Deterministic, LLM-free repository map.
+
+A single os.walk that classifies files (source / manifest / entrypoint), counts
+LOC, and returns the relative source-file list the navigator will reach. Cheap,
+reproducible, and the same logic that runs inside the sandbox toolrunner.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+# Source file extensions worth scanning. Anything else (assets, lockfiles,
+# binaries, minified bundles) is counted as context, not handed to the LLM.
+SOURCE_EXTS = {
+    ".py", ".js", ".jsx", ".ts", ".tsx", ".java", ".go", ".rb", ".php", ".cs",
+    ".c", ".cc", ".cpp", ".h", ".hpp", ".rs", ".kt", ".scala", ".swift", ".sh",
+    ".bash", ".pl", ".pm", ".sql", ".html", ".vue", ".lua", ".groovy", ".tf",
+}
+# Directories never worth walking — vendored / generated / VCS metadata.
+SKIP_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", "vendor", "venv", ".venv", "env",
+    "__pycache__", ".mypy_cache", ".pytest_cache", "dist", "build", ".next",
+    "site-packages", "target", ".idea", ".vscode", ".gradle", "bin", "obj",
+    "coverage", ".tox", ".cache", "bower_components",
+}
+# Dependency manifests we surface in the map (signal for what the app is).
+MANIFESTS = {
+    "requirements.txt", "pyproject.toml", "setup.py", "Pipfile", "package.json",
+    "go.mod", "pom.xml", "build.gradle", "Gemfile", "composer.json", "Cargo.toml",
+    "csproj",
+}
+# Entry-point filename hints (heuristic — where untrusted input often lands).
+ENTRY_HINTS = {
+    "app.py", "main.py", "manage.py", "wsgi.py", "asgi.py", "server.py",
+    "index.js", "server.js", "app.js", "main.go", "main.rs", "index.php",
+    "application.java",
+}
+
+
+def build_map(root: Path, max_map_files: int = 400,
+              max_file_bytes: int = 200_000) -> Tuple[Dict[str, Any], List[str]]:
+    """Walk the tree once. Returns (map_dict, relative_source_file_paths)."""
+    root = root.resolve()
+    langs: Dict[str, int] = {}
+    manifests: List[str] = []
+    entrypoints: List[str] = []
+    source_files: List[str] = []
+    total_files = 0
+    total_loc = 0
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")]
+        for fn in filenames:
+            total_files += 1
+            ext = os.path.splitext(fn)[1].lower()
+            full = Path(dirpath) / fn
+            rel = str(full.relative_to(root))
+            if fn in MANIFESTS or fn.endswith(".csproj"):
+                manifests.append(rel)
+            if fn in ENTRY_HINTS:
+                entrypoints.append(rel)
+            if ext in SOURCE_EXTS and len(source_files) < max_map_files:
+                source_files.append(rel)
+                langs[ext] = langs.get(ext, 0) + 1
+                try:
+                    if full.stat().st_size <= max_file_bytes:
+                        with open(full, "r", errors="ignore") as fh:
+                            total_loc += sum(1 for _ in fh)
+                except Exception:
+                    pass
+
+    code_map = {
+        "root_name": root.name,
+        "total_files": total_files,
+        "source_files_scanned": len(source_files),
+        "truncated": len(source_files) >= max_map_files,
+        "total_loc": total_loc,
+        "languages": dict(sorted(langs.items(), key=lambda kv: -kv[1])),
+        "manifests": manifests[:30],
+        "entrypoints": entrypoints[:30],
+    }
+    return code_map, source_files