contextl 1.0.1

package/python/import_parser.py

@@ -0,0 +1,271 @@
+"""
+Repository Intelligence Engine
+Step 2: Import Parser
+
+Reads each scanned file and extracts import relationships.
+Handles:
+  - Relative imports:  import X from "./foo"  or  "../../lib/bar"
+  - Alias imports:     import X from "@/components/Button"
+  - Type imports:      import type { X } from "@/types"
+  - Named imports:     import { X, Y } from "./utils"
+
+Returns only imports that resolve to other files in the repository.
+External packages (react, next, etc.) are ignored.
+"""
+
+import re
+from pathlib import Path
+from dataclasses import dataclass, field
+
+from scanner import ScannedFile, ScanResult
+
+
+# Matches any ES6 import statement and captures the module path
+IMPORT_PATTERN = re.compile(
+    r"""import\s+(?:type\s+)?          # import or import type
+        (?:
+            \{[^}]*\}                  # named imports: { Foo, Bar }
+            |[\w*]+                    # default or namespace: Foo or *
+            |[\w*]+\s*,\s*\{[^}]*\}   # mixed: Foo, { Bar }
+        )?
+        \s*(?:from\s+)?                # optional "from"
+        ['"](.*?)['"]                  # the module path in quotes
+    """,
+    re.VERBOSE,
+)
+
+# Also catch: import("./foo")  — dynamic imports
+DYNAMIC_IMPORT_PATTERN = re.compile(r"""import\s*\(\s*['"](.*?)['"]\s*\)""")
+
+
+@dataclass
+class ImportRelationship:
+    """A resolved import from one file to another."""
+    source: str       # Relative path of the file doing the importing
+    target: str       # Relative path of the file being imported
+    raw_import: str   # The original import string (e.g. "@/components/Button")
+
+
+@dataclass
+class ParseResult:
+    """All import relationships discovered across the repository."""
+    relationships: list[ImportRelationship] = field(default_factory=list)
+    unresolved: list[tuple[str, str]] = field(default_factory=list)
+    # unresolved = [(source_file, raw_import), ...] — external packages or not found
+
+    def summary(self) -> str:
+        lines = [
+            f"Import relationships found: {len(self.relationships)}",
+            f"Unresolved (external/missing): {len(self.unresolved)}",
+            "",
+            "Resolved imports:",
+        ]
+        for rel in self.relationships:
+            lines.append(f"  {rel.source}")
+            lines.append(f"    → {rel.target}  (from '{rel.raw_import}')")
+        return "\n".join(lines)
+
+
+def _extract_raw_imports(source_code: str) -> list[str]:
+    """Pull all import paths out of a TypeScript/JSX file."""
+    paths = []
+    for match in IMPORT_PATTERN.finditer(source_code):
+        paths.append(match.group(1))
+    for match in DYNAMIC_IMPORT_PATTERN.finditer(source_code):
+        paths.append(match.group(1))
+    return paths
+
+
+def _is_external(import_path: str) -> bool:
+    """Return True if this is an npm package rather than a local file."""
+    # Local files start with . (relative) or @ followed by / (alias like @/)
+    # but NOT @scope/package style from npm — those don't contain our alias prefix
+    if import_path.startswith("./") or import_path.startswith("../"):
+        return False
+    if import_path.startswith("@/"):
+        return False
+    return True  # Everything else is an external package
+
+
+def _resolve_alias(import_path: str, alias_map: dict[str, str]) -> str | None:
+    """
+    Convert an aliased import path to a repo-relative path.
+    Example: "@/components/Button" → "frontend/components/Button"
+    """
+    for alias, real_prefix in alias_map.items():
+        if import_path.startswith(alias):
+            suffix = import_path[len(alias):].lstrip("/")
+            prefix = real_prefix.rstrip("/")
+            if prefix:
+                return prefix + "/" + suffix
+            else:
+                # alias maps directly to the repo root — no leading slash
+                return suffix
+    return None
+
+
+def _resolve_relative(import_path: str, source_file: str) -> str:
+    """
+    Resolve a relative import path against the source file's directory.
+    Example: source="frontend/app/page.tsx", import="../lib/api" → "frontend/lib/api"
+    """
+    source_dir = Path(source_file).parent
+    resolved = (source_dir / import_path).resolve()
+    # Make it relative again (we'll strip the absolute prefix below)
+    return str(resolved)
+
+
+def _find_file_in_repo(
+    candidate: str,
+    file_index: dict[str, str],
+    root: str,
+) -> str | None:
+    """
+    Given a candidate path (without extension), find the matching file
+    in the repository. Tries adding common extensions if missing.
+    
+    file_index maps absolute_path → relative_path.
+    """
+    root_path = Path(root)
+    candidate_path = Path(candidate)
+
+    # If candidate is absolute, make it relative to root
+    if candidate_path.is_absolute():
+        try:
+            candidate_path = candidate_path.relative_to(root_path)
+        except ValueError:
+            return None
+
+    candidate_str = str(candidate_path)
+
+    # Try exact match first (already has extension)
+    if candidate_str in file_index:
+        return candidate_str
+
+    # Try adding each supported extension
+    for ext in [".tsx", ".ts", ".jsx", ".js"]:
+        with_ext = candidate_str + ext
+        if with_ext in file_index:
+            return with_ext
+
+    # Try as a directory index file (e.g. components/Button/index.tsx)
+    for ext in [".tsx", ".ts", ".jsx", ".js"]:
+        index_path = candidate_str + "/index" + ext
+        if index_path in file_index:
+            return index_path
+
+    return None
+
+
+def _detect_alias_map(scan_result: ScanResult) -> dict[str, str]:
+    """
+    Auto-detect the @/ alias by finding tsconfig.json or next.config files
+    and inferring the project root. Falls back to a heuristic.
+    
+    Returns a map like {"@/": "frontend/"} or {"@/": ""}
+    """
+    root = Path(scan_result.root)
+
+    # Look for tsconfig.json to find paths config
+    for tsconfig in root.rglob("tsconfig.json"):
+        try:
+            import json
+            data = json.loads(tsconfig.read_text())
+            paths = data.get("compilerOptions", {}).get("paths", {})
+            base_url = data.get("compilerOptions", {}).get("baseUrl", ".")
+
+            alias_map = {}
+            for alias, targets in paths.items():
+                if not targets:
+                    continue
+                # "@/*": ["./src/*"] → strip trailing /* from both
+                clean_alias = alias.rstrip("/*").rstrip("*")
+                clean_target = targets[0].rstrip("/*").rstrip("*").lstrip("./")
+
+                tsconfig_dir = tsconfig.parent.relative_to(root)
+                prefix = str(tsconfig_dir / clean_target).lstrip("./")
+                alias_map[clean_alias + "/"] = prefix + "/" if prefix else ""
+
+            if alias_map:
+                return alias_map
+        except Exception:
+            continue
+
+    # Heuristic fallback: if all files share a common top-level dir, use that
+    top_dirs = {Path(f.path).parts[0] for f in scan_result.files if Path(f.path).parts}
+    if len(top_dirs) == 1:
+        top = list(top_dirs)[0]
+        return {"@/": top + "/"}
+
+    return {"@/": ""}
+
+
+def parse_imports(scan_result: ScanResult) -> ParseResult:
+    """
+    Parse all import statements from scanned files and resolve them
+    to concrete file paths within the repository.
+
+    Args:
+        scan_result: Output from scan_repo().
+
+    Returns:
+        ParseResult containing all resolved ImportRelationships.
+    """
+    result = ParseResult()
+
+    # Build lookup: relative_path → ScannedFile
+    file_index: dict[str, ScannedFile] = {f.path: f for f in scan_result.files}
+
+    # Auto-detect alias map (e.g. @/ → frontend/)
+    alias_map = _detect_alias_map(scan_result)
+
+    for scanned_file in scan_result.files:
+        try:
+            source_code = Path(scanned_file.absolute_path).read_text(encoding="utf-8")
+        except Exception:
+            continue
+
+        raw_imports = _extract_raw_imports(source_code)
+
+        for raw in raw_imports:
+            if _is_external(raw):
+                result.unresolved.append((scanned_file.path, raw))
+                continue
+
+            # Resolve to a candidate path string
+            if raw.startswith("@/"):
+                resolved_alias = _resolve_alias(raw, alias_map)
+                if resolved_alias is None:
+                    result.unresolved.append((scanned_file.path, raw))
+                    continue
+                candidate = resolved_alias
+            else:
+                # Relative import
+                candidate = _resolve_relative(raw, scanned_file.path)
+
+            # Find the actual file in the repo
+            matched = _find_file_in_repo(candidate, file_index, scan_result.root)
+
+            if matched:
+                result.relationships.append(
+                    ImportRelationship(
+                        source=scanned_file.path,
+                        target=matched,
+                        raw_import=raw,
+                    )
+                )
+            else:
+                result.unresolved.append((scanned_file.path, raw))
+
+    return result
+
+
+if __name__ == "__main__":
+    import sys
+    from scanner import scan_repo
+
+    target = sys.argv[1] if len(sys.argv) > 1 else "."
+    scan = scan_repo(target)
+    parse = parse_imports(scan)
+
+    print(parse.summary())

package/python/main.py

@@ -0,0 +1,237 @@
+"""
+Repository Intelligence Engine
+CLI Entry Point
+
+Usage:
+    python main.py <repo_path> "<query>" [--top N] [--json]
+
+Examples:
+    python main.py ./my-next-app "change the download button"
+    python main.py ./my-next-app "fix file upload" --top 10
+    python main.py ./my-next-app "update footer text" --json
+"""
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+from scanner import scan_repo
+from import_parser import parse_imports
+from graph_builder import build_graph
+from query_engine import query, RankedFile
+
+
+# ---------------------------------------------------------------------------
+# Confidence thresholds
+# ---------------------------------------------------------------------------
+def _confidence(score: float) -> str:
+    """Derive a confidence label from the total relevance score."""
+    if score > 0.7:
+        return "high"
+    elif score >= 0.4:
+        return "medium"
+    else:
+        return "low"
+
+
+# ---------------------------------------------------------------------------
+# Reasoning generator
+# ---------------------------------------------------------------------------
+def _reasoning(ranked: RankedFile, repo_graph) -> str:
+    """
+    Produce a one-line human-readable explanation of why this file ranked here.
+    Uses the score breakdown from RankedFile plus graph context.
+    """
+    parts = []
+
+    # Filename / path signal
+    if ranked.keyword_score >= 0.8:
+        parts.append("Filename strongly matches query terms")
+    elif ranked.keyword_score >= 0.4:
+        parts.append("Filename partially matches query terms")
+
+    # Content signal
+    if ranked.content_score >= 0.8:
+        parts.append("file contents heavily reference query terms")
+    elif ranked.content_score >= 0.4:
+        parts.append("file contents mention query terms")
+
+    # Graph context
+    if ranked.neighbor_bonus > 0.05:
+        try:
+            dependents = repo_graph.get_dependents(ranked.path)
+            if dependents:
+                short_names = [Path(d).name for d in dependents[:2]]
+                parts.append(f"imported by {', '.join(short_names)}")
+        except Exception:
+            pass
+
+    # Centrality signal
+    if ranked.centrality > 0.05:
+        parts.append("highly connected file in the dependency graph")
+
+    # Terms matched
+    if ranked.matched_terms:
+        term_str = ", ".join(f'"{t}"' for t in sorted(ranked.matched_terms)[:4])
+        parts.append(f"matched terms: {term_str}")
+
+    if not parts:
+        return "Low-signal match based on graph proximity"
+
+    return "; ".join(parts).capitalize() + "."
+
+
+# ---------------------------------------------------------------------------
+# Output formatters
+# ---------------------------------------------------------------------------
+def _format_json(query_str: str, repo_path: str, results: list[RankedFile], repo_graph) -> str:
+    """Render results as a clean JSON string."""
+    output = {
+        "query": query_str,
+        "repo": str(Path(repo_path).resolve()),
+        "results": [
+            {
+                "rank": i + 1,
+                "path": r.path,
+                "score": round(r.total_score, 4),
+                "confidence": _confidence(r.total_score),
+                "matched_terms": sorted(r.matched_terms),
+                "reasoning": _reasoning(r, repo_graph),
+            }
+            for i, r in enumerate(results)
+        ],
+    }
+    return json.dumps(output, indent=2)
+
+
+def _format_human(query_str: str, repo_path: str, results: list[RankedFile], repo_graph, elapsed: float) -> str:
+    """Render results as styled, human-readable console output."""
+    BOLD  = "\033[1m"
+    DIM   = "\033[2m"
+    GREEN = "\033[32m"
+    YELLOW= "\033[33m"
+    RED   = "\033[31m"
+    CYAN  = "\033[36m"
+    RESET = "\033[0m"
+
+    CONF_COLOR = {"high": GREEN, "medium": YELLOW, "low": RED}
+
+    lines = [
+        "",
+        f"{BOLD}Repository Intelligence Engine{RESET}",
+        f"{DIM}{'─' * 60}{RESET}",
+        f"  Query : {BOLD}{query_str}{RESET}",
+        f"  Repo  : {repo_path}",
+        f"  Found : {len(results)} result(s)  {DIM}({elapsed:.2f}s){RESET}",
+        f"{DIM}{'─' * 60}{RESET}",
+        "",
+    ]
+
+    for i, r in enumerate(results, 1):
+        conf = _confidence(r.total_score)
+        color = CONF_COLOR.get(conf, RESET)
+        badge = f"{color}[{conf.upper()}]{RESET}"
+
+        terms = ", ".join(sorted(r.matched_terms)) if r.matched_terms else "—"
+        reason = _reasoning(r, repo_graph)
+
+        lines += [
+            f"  {BOLD}#{i}{RESET}  {CYAN}{r.path}{RESET}  {badge}",
+            f"      Score    : {r.total_score:.4f}  "
+            f"(kw={r.keyword_score:.3f} "
+            f"content={r.content_score:.3f} "
+            f"neighbor={r.neighbor_bonus:.3f} "
+            f"pr={r.centrality:.4f})",
+            f"      Terms    : {terms}",
+            f"      Reason   : {DIM}{reason}{RESET}",
+            "",
+        ]
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Main pipeline
+# ---------------------------------------------------------------------------
+def run_engine(repo_path: str, query_str: str, top_n: int):
+    """
+    Execute the full pipeline and return (results, repo_graph, elapsed_seconds).
+    Raises SystemExit on unrecoverable errors.
+    """
+    t0 = time.perf_counter()
+
+    try:
+        scan = scan_repo(repo_path)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if scan.total_files == 0:
+        print("Warning: No source files found in the repository.", file=sys.stderr)
+
+    parse = parse_imports(scan)
+    repo_graph = build_graph(scan, parse)
+    results = query(query_str, repo_graph, top_n=top_n)
+
+    elapsed = time.perf_counter() - t0
+    return results, repo_graph, elapsed
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="prune",
+        description=(
+            "Repository Intelligence Engine — find the most relevant files "
+            "for a given change request without LLMs or embeddings."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    parser.add_argument("repo_path", help="Path to the repository root")
+    parser.add_argument("query", help="Natural-language query (e.g. 'fix the upload error handler')")
+    parser.add_argument(
+        "--top", "-n",
+        type=int,
+        default=5,
+        metavar="N",
+        help="Number of results to return (default: 5)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        default=False,
+        help="Output clean JSON instead of human-readable text",
+    )
+    return parser
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+
+    results, repo_graph, elapsed = run_engine(args.repo_path, args.query, args.top)
+
+    if not results:
+        if args.json:
+            print(json.dumps({
+                "query": args.query,
+                "repo": str(Path(args.repo_path).resolve()),
+                "results": [],
+            }, indent=2))
+        else:
+            print(f"\nNo relevant files found for: '{args.query}'")
+        sys.exit(0)
+
+    if args.json:
+        print(_format_json(args.query, args.repo_path, results, repo_graph))
+    else:
+        print(_format_human(args.query, args.repo_path, results, repo_graph, elapsed))
+
+
+if __name__ == "__main__":
+    main()