coderay 1.0.4__tar.gz → 1.0.6__tar.gz

{coderay-1.0.4/src/coderay.egg-info → coderay-1.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderay
-Version: 1.0.4
+Version: 1.0.6
 Summary: X-ray your codebase — semantic search, code graphs, file skeletons, and MCP server
 Author-email: Bogdan Copocean <bogdancopocean@gmail.com>
 License-Expression: MIT
@@ -64,6 +64,15 @@ AI coding assistants and a standalone CLI.
 
 ## Install
 
+Create a virtual environment (recommended):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Then install:
+
 ```bash
 pip install coderay
 ```
@@ -79,6 +88,7 @@ For development:
 ```bash
 git clone https://github.com/bogdan-copocean/coderay.git
 cd coderay
+python -m venv .venv && source .venv/bin/activate
 pip install -e ".[all]"
 ```
 
@@ -86,15 +96,22 @@ pip install -e ".[all]"
 
 ```bash
 cd /path/to/your/project
-coderay build --repo .
+coderay watch --repo .   # keeps index fresh while you work (recommended)
 coderay search "how does authentication work"
-coderay watch --repo .
 coderay graph --kind calls
 coderay skeleton src/app/main.py
 ```
 
+> **Use `watch`, not `build`.** `coderay build` is a one-off; while you work, the index will get stale. `coderay watch` re-indexes on file changes and is the go-to for active development.
+
 ## MCP server (Claude Code / Cursor)
 
+Find the MCP executable path:
+
+```bash
+which coderay-mcp
+```
+
 Add to `~/.claude/claude_code_config.json` or Cursor MCP settings:
 
 ```json
@@ -108,13 +125,14 @@ Add to `~/.claude/claude_code_config.json` or Cursor MCP settings:
 }
 ```
 
+Replace `/path/to/your/.venv/bin/coderay-mcp` with the output of `which coderay-mcp`.
+
 ## CLI reference
 
 | Command | Description |
 |---|---|
-| `coderay build [--full] --repo .` | Build index (incremental or full rebuild) |
-| `coderay update --repo .` | Incremental update (changed files only) |
-| `coderay watch --repo . [--debounce N]` | Watch for file changes, re-index automatically |
+| `coderay watch --repo . [--debounce N]` | **Recommended.** Watch for file changes, re-index automatically |
+| `coderay build [--full] --repo .` | Build or incremental update. Use `--full` for full rebuild |
 | `coderay search "query" [--top-k N]` | Semantic search |
 | `coderay list [--by-file]` | List indexed chunks |
 | `coderay status` | Index state, branch, commit, chunk count |
@@ -124,39 +142,37 @@ Add to `~/.claude/claude_code_config.json` or Cursor MCP settings:
 
 ## Configuration
 
-Optional `config.yaml` in the index directory:
+File discovery and ignoring are based on `.git` and `.gitignore`. The `.git` directory is excluded; files matching `.gitignore` are not indexed. Config `exclude_patterns` add extra exclusions on top of that.
+
+Optional `config.yaml` in the index directory (default: `.index/config.yaml`):
 
 ```yaml
 embedder:
-  provider: local
-  model: all-MiniLM-L6-v2
+  model: sentence-transformers/all-MiniLM-L6-v2
   dimensions: 384
 
-search:
-  boost_rules:
-    "tests/": 0.5
-    "src/core/": 1.2
-
-graph:
-  exclude_callees:
-    - "our_sdk_helper"
-  include_callees:
-    - "isinstance"
-
-watch:
-  debounce_seconds: 2
-  branch_switch_threshold: 50
-  exclude_patterns:
+index:
+  exclude_patterns:  # besides .gitignore
     - "*.log"
-```
 
-## Development
+semantic_search:
+  boosting:
+    penalties:
+      - pattern: "(^|/)tests?/"
+        factor: 0.5
+      - pattern: "(^|/)test_[^/]+\\.py$"
+        factor: 0.5
+    bonuses:
+      - pattern: "(^|/)src/"
+        factor: 1.1
+  metric: cosine
+
+watcher:
+  debounce: 2
+  exclude_patterns:  # besides .gitignore
+    - "*.log"
 
-```bash
-pip install -e ".[dev]"
-make test
-make lint
-make format
+graph:
+  exclude_modules: []   # module names to exclude from CALLS/IMPORTS edges
+  include_modules: []  # force-include (override excludes)
 ```
-
-Requires Python >= 3.10 and Git.

{coderay-1.0.4 → coderay-1.0.6}/README.md

@@ -15,6 +15,15 @@ AI coding assistants and a standalone CLI.
 
 ## Install
 
+Create a virtual environment (recommended):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Then install:
+
 ```bash
 pip install coderay
 ```
@@ -30,6 +39,7 @@ For development:
 ```bash
 git clone https://github.com/bogdan-copocean/coderay.git
 cd coderay
+python -m venv .venv && source .venv/bin/activate
 pip install -e ".[all]"
 ```
 
@@ -37,15 +47,22 @@ pip install -e ".[all]"
 
 ```bash
 cd /path/to/your/project
-coderay build --repo .
+coderay watch --repo .   # keeps index fresh while you work (recommended)
 coderay search "how does authentication work"
-coderay watch --repo .
 coderay graph --kind calls
 coderay skeleton src/app/main.py
 ```
 
+> **Use `watch`, not `build`.** `coderay build` is a one-off; while you work, the index will get stale. `coderay watch` re-indexes on file changes and is the go-to for active development.
+
 ## MCP server (Claude Code / Cursor)
 
+Find the MCP executable path:
+
+```bash
+which coderay-mcp
+```
+
 Add to `~/.claude/claude_code_config.json` or Cursor MCP settings:
 
 ```json
@@ -59,13 +76,14 @@ Add to `~/.claude/claude_code_config.json` or Cursor MCP settings:
 }
 ```
 
+Replace `/path/to/your/.venv/bin/coderay-mcp` with the output of `which coderay-mcp`.
+
 ## CLI reference
 
 | Command | Description |
 |---|---|
-| `coderay build [--full] --repo .` | Build index (incremental or full rebuild) |
-| `coderay update --repo .` | Incremental update (changed files only) |
-| `coderay watch --repo . [--debounce N]` | Watch for file changes, re-index automatically |
+| `coderay watch --repo . [--debounce N]` | **Recommended.** Watch for file changes, re-index automatically |
+| `coderay build [--full] --repo .` | Build or incremental update. Use `--full` for full rebuild |
 | `coderay search "query" [--top-k N]` | Semantic search |
 | `coderay list [--by-file]` | List indexed chunks |
 | `coderay status` | Index state, branch, commit, chunk count |
@@ -75,39 +93,37 @@ Add to `~/.claude/claude_code_config.json` or Cursor MCP settings:
 
 ## Configuration
 
-Optional `config.yaml` in the index directory:
+File discovery and ignoring are based on `.git` and `.gitignore`. The `.git` directory is excluded; files matching `.gitignore` are not indexed. Config `exclude_patterns` add extra exclusions on top of that.
+
+Optional `config.yaml` in the index directory (default: `.index/config.yaml`):
 
 ```yaml
 embedder:
-  provider: local
-  model: all-MiniLM-L6-v2
+  model: sentence-transformers/all-MiniLM-L6-v2
   dimensions: 384
 
-search:
-  boost_rules:
-    "tests/": 0.5
-    "src/core/": 1.2
-
-graph:
-  exclude_callees:
-    - "our_sdk_helper"
-  include_callees:
-    - "isinstance"
-
-watch:
-  debounce_seconds: 2
-  branch_switch_threshold: 50
-  exclude_patterns:
+index:
+  exclude_patterns:  # besides .gitignore
     - "*.log"
-```
 
-## Development
+semantic_search:
+  boosting:
+    penalties:
+      - pattern: "(^|/)tests?/"
+        factor: 0.5
+      - pattern: "(^|/)test_[^/]+\\.py$"
+        factor: 0.5
+    bonuses:
+      - pattern: "(^|/)src/"
+        factor: 1.1
+  metric: cosine
+
+watcher:
+  debounce: 2
+  exclude_patterns:  # besides .gitignore
+    - "*.log"
 
-```bash
-pip install -e ".[dev]"
-make test
-make lint
-make format
+graph:
+  exclude_modules: []   # module names to exclude from CALLS/IMPORTS edges
+  include_modules: []  # force-include (override excludes)
 ```
-
-Requires Python >= 3.10 and Git.

{coderay-1.0.4 → coderay-1.0.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "coderay"
-version = "1.0.4"
+version = "1.0.6"
 description = "X-ray your codebase — semantic search, code graphs, file skeletons, and MCP server"
 readme = "README.md"
 license = "MIT"

{coderay-1.0.4 → coderay-1.0.6}/src/coderay/cli/commands.py

@@ -9,6 +9,7 @@ import click
 from dotenv import load_dotenv
 
 from coderay.core.lock import acquire_indexer_lock
+from coderay.core.timing import timed_phase
 from coderay.pipeline.indexer import Indexer
 from coderay.retrieval.search import Retrieval
 from coderay.state.machine import StateMachine
@@ -45,6 +46,7 @@ def _setup_logging(verbose: bool = False) -> None:
 
 
 @click.group()
+@click.version_option(package_name="coderay", prog_name="coderay")
 @click.option("-v", "--verbose", is_flag=True, default=False, help="Verbose logging")
 @click.pass_context
 def cli(ctx: click.Context, verbose: bool) -> None:
@@ -74,61 +76,20 @@ def build(ctx: click.Context, full: bool, repo: Path) -> None:
     index_dir = Path(config.index.path)
     index_dir.mkdir(parents=True, exist_ok=True)
     indexer = Indexer(repo)
-    t0 = time.time()
     try:
-        with acquire_indexer_lock(index_dir):
-            if full or not indexer.index_exists():
-                click.echo(_color("Building full index...", CYAN))
-                result = indexer.build_full()
-                click.echo(
-                    _color(
-                        f"{result} in {time.time() - t0:.2f}s",
-                        GREEN,
-                    )
-                )
-            else:
-                click.echo(_color("Updating index (incremental)...", CYAN))
-                result = indexer.update_incremental()
-                click.echo(
-                    _color(
-                        f"{result} in {time.time() - t0:.2f}s",
-                        GREEN,
-                    )
-                )
-            indexer.maintain()
-    except Exception as e:
-        indexer.error(str(e))
-        click.echo(_color(f"Error: {e}", RED))
-        raise
-
-
-@cli.command()
-@click.option(
-    "--repo",
-    default=".",
-    type=click.Path(exists=True, path_type=Path),
-    help="Repo root",
-)
-@click.pass_context
-def update(ctx: click.Context, repo: Path) -> None:
-    """Incremental update (only changed files). Uses file lock."""
-    from coderay.core.config import get_config
-
-    config = get_config()
-    index_dir = Path(config.index.path)
-    indexer = Indexer(repo)
-    t0 = time.time()
-
-    if not indexer.index_exists():
-        click.echo(_color("No index found. Run 'coderay build' first.", YELLOW))
-        ctx.exit(1)
-
-    try:
-        with acquire_indexer_lock(index_dir):
-            click.echo(_color("Updating index...", CYAN))
-            result = indexer.update_incremental()
-            click.echo(_color(f"{result} in {time.time() - t0:.2f}s", GREEN))
+        with timed_phase("build", log=False) as tp:
+            with acquire_indexer_lock(index_dir):
+                if full:
+                    click.echo(_color("Building full index...", CYAN))
+                    result = indexer.build_full()
+                else:
+                    if not indexer.index_exists():
+                        click.echo(_color("Building full index...", CYAN))
+                    else:
+                        click.echo(_color("Updating index (incremental)...", CYAN))
+                    result = indexer.ensure_index()
             indexer.maintain()
+        click.echo(_color(f"{result} in {tp.elapsed:.2f}s", GREEN))
     except Exception as e:
         indexer.error(str(e))
         click.echo(_color(f"Error: {e}", RED))
@@ -163,16 +124,15 @@ def search_cmd(
 
     retrieval = Retrieval()
     click.echo(_color(f"Searching: {query_text!r}", CYAN))
-    t0 = time.perf_counter()
 
-    results = retrieval.search(
-        query=query_text,
-        current_state=current_state,
-        top_k=top_k,
-        path_prefix=path_prefix,
-    )
-    elapsed = time.perf_counter() - t0
-    click.echo(_color(f"Query took {elapsed:.2f}s", BOLD))
+    with timed_phase("search", log=False) as tp:
+        results = retrieval.search(
+            query=query_text,
+            current_state=current_state,
+            top_k=top_k,
+            path_prefix=path_prefix,
+        )
+    click.echo(_color(f"Query took {tp.elapsed:.2f}s", BOLD))
 
     if not results:
         click.echo(_color("No results.", YELLOW))
@@ -367,7 +327,7 @@ def graph_cmd(
     if not edges:
         click.echo(
             _color(
-                "No graph data. Run 'coderay build' or 'coderay update' to build it.",
+                "No graph data. Run 'coderay build' to build it.",
                 YELLOW,
             )
         )
@@ -412,20 +372,26 @@ def watch(
 
     config = get_config()
     index_dir = Path(config.index.path)
-    if not index_exists(index_dir):
-        click.echo(
-            _color(
-                "No index found. Run 'coderay build' first.",
-                YELLOW,
-            )
-        )
-        ctx.exit(1)
+    index_dir.mkdir(parents=True, exist_ok=True)
 
     if quiet:
         logging.getLogger("coderay.pipeline.watcher").setLevel(logging.WARNING)
 
-    watcher = FileWatcher(repo, index_dir)
+    indexer = Indexer(repo)
+    try:
+        with timed_phase("watch_startup", log=False) as tp:
+            with acquire_indexer_lock(index_dir):
+                if not indexer.index_exists():
+                    click.echo(_color("No index found. Building full index...", CYAN))
+                result = indexer.ensure_index()
+            indexer.maintain()
+        click.echo(_color(f"{result} in {tp.elapsed:.2f}s", GREEN))
+    except Exception as e:
+        indexer.error(str(e))
+        click.echo(_color(f"Error: {e}", RED))
+        raise
 
+    watcher = FileWatcher(repo, index_dir)
     click.echo(
         _color(
             f"Watching {repo.resolve()} "
@@ -433,9 +399,6 @@ def watch(
             CYAN,
         )
     )
-    index_dir.mkdir(parents=True, exist_ok=True)
-    indexer = Indexer(repo)
-    indexer.update_incremental()
 
     watcher.start()
     try:

{coderay-1.0.4 → coderay-1.0.6}/src/coderay/core/config.py

@@ -85,7 +85,18 @@ class SemanticSearchConfig:
 class WatcherConfig:
     debounce: Annotated[int, "in seconds"] = 2
     exclude_patterns: Annotated[str, "besides .gitignore"] | None = None
-    branch_switch_threshold: int = 50
+
+
+@dataclass(frozen=True)
+class GraphConfig:
+    """Module filtering for the code graph (CALLS, IMPORTS edges)."""
+
+    exclude_modules: Annotated[
+        list[str], "module names/prefixes to exclude from graph edges"
+    ] = field(default_factory=list)
+    include_modules: Annotated[
+        list[str], "module names to force-include (override excludes)"
+    ] = field(default_factory=list)
 
 
 @dataclass(frozen=True)
@@ -94,6 +105,7 @@ class Config:
     index: IndexConfig = field(default_factory=IndexConfig)
     semantic_search: SemanticSearchConfig = field(default_factory=SemanticSearchConfig)
     watcher: WatcherConfig = field(default_factory=WatcherConfig)
+    graph: GraphConfig = field(default_factory=GraphConfig)
 
 
 def _parse_boosting(data: dict[str, Any]) -> BoostingConfig:
@@ -204,6 +216,7 @@ def _load_config_impl() -> Config:
             default_data.get("semantic_search", {}) or {}
         ),
         watcher=WatcherConfig(**default_data.get("watcher", {})),
+        graph=GraphConfig(**default_data.get("graph", {})),
     )
 
 
@@ -288,4 +301,5 @@ def _deep_merge(overrides: dict, *, index_dir: Path) -> Config:
         index=IndexConfig(**merged.get("index", {})),
         semantic_search=_parse_semantic_search(merged.get("semantic_search", {}) or {}),
         watcher=WatcherConfig(**merged.get("watcher", {})),
+        graph=GraphConfig(**merged.get("graph", {})),
     )

{coderay-1.0.4 → coderay-1.0.6}/src/coderay/core/timing.py

@@ -29,17 +29,23 @@ def timed(phase: str) -> Callable[[F], F]:
     return decorator
 
 
-class timed_phase:
-    """Context manager that logs block execution time at INFO level."""
+class TimedPhase:
+    """Context manager that measures block execution time and optionally logs it."""
 
-    def __init__(self, phase: str) -> None:
+    def __init__(self, phase: str, *, log: bool = True) -> None:
         self.phase = phase
+        self.log = log
         self.t0: float = 0.0
+        self.elapsed: float = 0.0
 
-    def __enter__(self) -> timed_phase:
+    def __enter__(self) -> TimedPhase:
         self.t0 = time.perf_counter()
         return self
 
     def __exit__(self, *args: object) -> None:
-        elapsed = time.perf_counter() - self.t0
-        logger.info("%s: %.3fs", self.phase, elapsed)
+        self.elapsed = time.perf_counter() - self.t0
+        if self.log:
+            logger.info("%s: %.3fs", self.phase, self.elapsed)
+
+
+timed_phase = TimedPhase  # Convenience alias for context manager usage

{coderay-1.0.4 → coderay-1.0.6}/src/coderay/graph/builder.py

@@ -33,11 +33,13 @@ def build_graph(
         except Exception as exc:
             logger.warning("Graph extraction failed for %s: %s", file_path, exc)
     resolved = graph.resolve_edges()
+    pruned = graph.prune_phantom_edges()
     logger.info(
-        "Graph built: %d nodes, %d edges (%d call edges resolved)",
+        "Graph built: %d nodes, %d edges (%d resolved, %d phantoms pruned)",
         graph.node_count,
         graph.edge_count,
         resolved,
+        pruned,
     )
     return graph
 
@@ -140,6 +142,7 @@ def build_and_save_graph(
             except Exception as exc:
                 logger.warning("Graph extraction failed for %s: %s", fp, exc)
         existing_graph.resolve_edges()
+        existing_graph.prune_phantom_edges()
         graph = existing_graph
         logger.info(
             "Graph incremental update: re-parsed %d files",

{coderay-1.0.4 → coderay-1.0.6}/src/coderay/graph/code_graph.py

@@ -74,6 +74,10 @@ class CodeGraph:
         # (e.g. two files both define a function called "helper").
         self._symbol_index: dict[str, set[str]] = defaultdict(set)
 
+        # qualified_name -> {full node IDs} — enables resolving dotted names
+        # like "ClassName.method" to "src/a.py::ClassName.method".
+        self._qualified_index: dict[str, set[str]] = defaultdict(set)
+
         # dotted module name -> node ID — maps Python-style import paths
         # (e.g. "core.models") to the MODULE node they refer to.
         self._module_index: dict[str, str] = {}
@@ -85,6 +89,8 @@ class CodeGraph:
     def _index_node(self, node: GraphNode) -> None:
         """Register a node in all secondary indexes."""
         self._symbol_index[node.name].add(node.id)
+        if node.qualified_name != node.name:
+            self._qualified_index[node.qualified_name].add(node.id)
         self._file_index[node.file_path].add(node.id)
         if node.kind == NodeKind.MODULE:
             # Register all suffix variants so that "import models" and
@@ -98,6 +104,10 @@ class CodeGraph:
         sym_entries = self._symbol_index.get(node.name)
         if sym_entries is not None:
             sym_entries.discard(node.id)
+        if node.qualified_name != node.name:
+            qual_entries = self._qualified_index.get(node.qualified_name)
+            if qual_entries is not None:
+                qual_entries.discard(node.id)
         file_entries = self._file_index.get(node.file_path)
         if file_entries is not None:
             file_entries.discard(node.id)
@@ -140,17 +150,27 @@ class CodeGraph:
         return len(to_remove)
 
     def resolve_symbol(self, name: str, caller_file: str | None = None) -> str | None:
-        """Resolve a short/bare name to a fully-qualified node ID.
+        """Resolve a short, qualified, or dotted name to a fully-qualified node ID.
+
+        Lookup order:
+            1. Exact node ID match (fast path).
+            2. Bare name via ``_symbol_index`` (unique match only).
+            3. Qualified name via ``_qualified_index`` (e.g. "ClassName.method").
 
         Returns:
             Full node ID, or None if the name cannot be uniquely resolved.
         """
-        # Already a full node ID (e.g. "src/a.py::foo") — fast path
         if name in self._g and self._g.nodes[name].get("data") is not None:
             return name
+
         candidates = self._symbol_index.get(name, set())
         if len(candidates) == 1:
             return next(iter(candidates))
+
+        qual_candidates = self._qualified_index.get(name, set())
+        if len(qual_candidates) == 1:
+            return next(iter(qual_candidates))
+
         return None
 
     def resolve_edges(self) -> int:
@@ -194,6 +214,46 @@ class CodeGraph:
             logger.info("Resolved %d edges via symbol/module index", len(to_add))
         return len(to_add)
 
+    def prune_phantom_edges(self) -> int:
+        """Remove CALLS edges whose target is a phantom with no resolution candidates.
+
+        These are typically stdlib/third-party methods (``append``, ``get``,
+        ``join``, etc.) that will never resolve to a project node.  Removing
+        them reduces noise and improves ``get_impact_radius`` traversal.
+
+        Returns:
+            Number of edges pruned.
+        """
+        to_remove: list[tuple[str, str]] = []
+        for u, v, data in self._g.edges(data=True):
+            if data.get("kind") != EdgeKind.CALLS:
+                continue
+            node_data = self._g.nodes.get(v, {})
+            if node_data and node_data.get("data") is not None:
+                continue
+            if (
+                not self._symbol_index.get(v)
+                and not self._qualified_index.get(v)
+            ):
+                to_remove.append((u, v))
+
+        for u, v in to_remove:
+            if self._g.has_edge(u, v):
+                self._g.remove_edge(u, v)
+
+        # Clean up orphan phantom nodes (no remaining edges)
+        phantom_nodes = [
+            n for n in list(self._g.nodes)
+            if self._g.nodes[n].get("data") is None
+            and self._g.degree(n) == 0
+        ]
+        for n in phantom_nodes:
+            self._g.remove_node(n)
+
+        if to_remove:
+            logger.info("Pruned %d phantom CALLS edges", len(to_remove))
+        return len(to_remove)
+
     def _resolve_path_target(self, target: str) -> str | None:
         """Try to match a path-style target to an existing MODULE node."""
         if "/" not in target:

{coderay-1.0.4 → coderay-1.0.6}/src/coderay/graph/extractor.py

@@ -86,11 +86,8 @@ def build_module_filter() -> frozenset[str]:
         from CALLS and IMPORTS edges.
     """
     config = get_config()
-    graph_cfg = getattr(config, "graph", None) or {}
-    if not isinstance(graph_cfg, dict):
-        graph_cfg = {}
-    extra_excludes = set(graph_cfg.get("exclude_modules") or [])
-    force_includes = set(graph_cfg.get("include_modules") or [])
+    extra_excludes = set(config.graph.exclude_modules or [])
+    force_includes = set(config.graph.include_modules or [])
     return frozenset((_DEFAULT_EXCLUDED_MODULES | extra_excludes) - force_includes)
 
 
@@ -391,12 +388,13 @@ class GraphTreeSitterParser(BaseTreeSitterParser):
             )
         )
 
-        # Top-level functions are registered in FileContext so calls
-        # like ``my_func()`` resolve to the fully qualified node_id.
-        # TODO: register class methods too (e.g. ClassName.method) so that
-        #  static/classmethod calls at module level can resolve
+        # Register in FileContext so calls resolve to the full node_id.
+        # Top-level: ``my_func()`` → node_id
+        # Class methods: ``ClassName.method()`` → node_id (via qualified name)
         if not scope_stack:
             self._file_ctx.register_definition(name, node_id)
+        else:
+            self._file_ctx.register_definition(qualified, node_id)
 
         # Recurse into the function body under a new scope
         new_scope = [*scope_stack, name]

{coderay-1.0.4 → coderay-1.0.6}/src/coderay/pipeline/indexer.py

@@ -80,18 +80,12 @@ class Indexer:
         """Full rebuild: discover, chunk, embed, and store all source files."""
 
         current = self._state.current_state
-        last_branch = current.branch if current is not None else None
-        branch_switched = self._git.is_branch_switched(last_branch=last_branch)
-        if branch_switched:
-            return self.update_incremental()
-
         current_run = current.current_run if current else None
         saved_paths = current_run.paths_to_process if current_run else []
         processed_count = current_run.processed_count if current_run else 0
 
         can_resume = (
-            not branch_switched
-            and self._state.is_in_progress
+            self._state.is_in_progress
             and self._state.has_partial_progress
         )
 
@@ -150,17 +144,6 @@ class Indexer:
         self._state.set_incomplete()
 
         current = self._state.current_state
-        state_branch = current.branch if current else None
-        active_branch = self._git.get_current_branch()
-
-        if self._git.is_branch_switched(last_branch=state_branch):
-            logger.info(
-                "Branch switched %s -> %s; syncing index",
-                state_branch,
-                active_branch,
-            )
-            return self._sync_after_branch_switch()
-
         to_add, to_remove = self._git.get_files_to_index(
             last_commit=current.last_commit if current else None
         )
@@ -193,55 +176,6 @@ class Indexer:
             file_hashes=file_hashes,
         )
 
-    def _sync_after_branch_switch(self) -> IndexResult:
-        """Sync index to current branch after a switch. Returns IndexResult."""
-        file_hashes = self._state.file_hashes.copy()
-        py_files = self._git.discover_files()
-
-        # All .py files were deleted from git
-        to_remove: list[str] = []
-        if not py_files:
-            to_remove = list(file_hashes)
-
-        if to_remove:
-            self._store.delete_by_paths(to_remove)
-            index_result = IndexResult(removed=len(file_hashes))
-            file_hashes.clear()
-
-            self._state.file_hashes = file_hashes
-            self._state.finish(
-                last_commit=self._git.get_head_commit(),
-                branch=self._git.get_current_branch(),
-            )
-            self._refresh_graph()
-            return index_result
-
-        rel_paths_current = {str(p.relative_to(self._repo_root)) for p in py_files}
-        # Deleted files on current branch
-        to_remove = [p for p in file_hashes if p not in rel_paths_current]
-        if to_remove:
-            self._store.delete_by_paths(to_remove)
-            for p in to_remove:
-                file_hashes.pop(p, None)
-
-        changed_files = files_with_changed_content(
-            repo=self._repo_root, paths=py_files, file_hashes=file_hashes
-        )
-
-        if not changed_files and not to_remove:
-            self._state.finish(
-                last_commit=self._git.get_head_commit(),
-                branch=self._git.get_current_branch(),
-            )
-            self._refresh_graph()
-            logger.info("Branch switch: index already in sync (no changes)")
-            return IndexResult(cached=len(self._state.file_hashes))
-
-        return self._update(
-            paths_to_add=changed_files,
-            file_hashes=file_hashes,
-        )
-
     def _run_batch_loop(
         self,
         rel_paths: list[str],
@@ -423,6 +357,12 @@ class Indexer:
         """Return True if the index exists at index_dir."""
         return index_exists(self._index_dir)
 
+    def ensure_index(self) -> IndexResult:
+        """Build full index if missing, else incremental update."""
+        if not self.index_exists():
+            return self.build_full()
+        return self.update_incremental()
+
     def error(self, exc: str) -> None:
         """Mark the current run as errored with the given exception message."""
         self._state.set_errored(exc=exc)

{coderay-1.0.4 → coderay-1.0.6}/src/coderay/pipeline/watcher.py

@@ -19,6 +19,7 @@ from watchdog.events import (
 from watchdog.observers import Observer
 from watchdog.observers.polling import PollingObserver
 
+from coderay.core.timing import timed_phase
 from coderay.parsing.languages import get_supported_extensions
 from coderay.vcs.git import load_gitignore
 
@@ -35,7 +36,6 @@ class _DebouncedHandler:
         gitignore_spec: pathspec.PathSpec,
         supported_extensions: set[str],
         debounce_seconds: float,
-        branch_switch_threshold: int,
         extra_exclude: list[str],
         on_batch: Callable[[set[str], set[str]], None],
     ) -> None:
@@ -45,7 +45,6 @@ class _DebouncedHandler:
         self._gitignore = gitignore_spec
         self._extensions = supported_extensions
         self._debounce = debounce_seconds
-        self._threshold = branch_switch_threshold
         self._on_batch = on_batch
 
         extra_spec = pathspec.PathSpec.from_lines("gitignore", extra_exclude)
@@ -160,13 +159,6 @@ class _DebouncedHandler:
         if not changed and not removed:
             return
 
-        total = len(changed) + len(removed)
-        if total >= self._threshold:
-            logger.info(
-                "Branch switch detected (%d files); delegating to full sync",
-                total,
-            )
-
         try:
             self._on_batch(changed, removed)
         except Exception:
@@ -195,7 +187,6 @@ class FileWatcher:
 
         watch_cfg = self._config.watcher
         self._debounce = float(watch_cfg.debounce)
-        self._threshold = int(watch_cfg.branch_switch_threshold)
         self._extra_exclude = list(watch_cfg.exclude_patterns or [])
 
         self._observer: Observer | PollingObserver | None = None
@@ -219,7 +210,6 @@ class FileWatcher:
             gitignore_spec=gitignore_spec,
             supported_extensions=extensions,
             debounce_seconds=self._debounce,
-            branch_switch_threshold=self._threshold,
             extra_exclude=self._extra_exclude,
             on_batch=batch_fn,
         )
@@ -265,30 +255,21 @@ class FileWatcher:
             self._observer.join(timeout=timeout)
 
     def _default_batch(self, changed: set[str], removed: set[str]) -> None:
-        """Default callback: acquire lock and run Indexer.update_paths."""
+        """Default callback: acquire lock and run Indexer.update_incremental."""
         from coderay.core.lock import acquire_indexer_lock
         from coderay.pipeline.indexer import Indexer
 
-        total = len(changed) + len(removed)
-        t0 = time.time()
-
         try:
-            with acquire_indexer_lock(self._index_dir, timeout=30):
-                indexer = Indexer(self._repo_root)
-                if total >= self._threshold:
+            with timed_phase("update", log=False) as tp:
+                with acquire_indexer_lock(self._index_dir, timeout=30):
+                    indexer = Indexer(self._repo_root)
                     result = indexer.update_incremental()
-                else:
-                    result = indexer.update_paths(
-                        changed=sorted(changed),
-                        removed=sorted(removed),
-                    )
-            elapsed = time.time() - t0
             self._update_count += 1
             logger.info(
                 "Update #%d: %s (%.2fs) [%d changed, %d removed]",
                 self._update_count,
                 result,
-                elapsed,
+                tp.elapsed,
                 len(changed),
                 len(removed),
             )

{coderay-1.0.4 → coderay-1.0.6}/src/coderay/retrieval/search.py

@@ -1,11 +1,11 @@
 from __future__ import annotations
 
 import logging
-import time
 from pathlib import Path
 from typing import Any
 
 from coderay.core.config import Config, get_config
+from coderay.core.timing import timed_phase
 from coderay.embedding.base import Embedder, load_embedder_from_config
 from coderay.graph.builder import load_graph
 from coderay.retrieval.boosting import StructuralBooster
@@ -65,20 +65,18 @@ class Retrieval:
 
         store = self._get_store()
 
-        t0 = time.perf_counter()
-        query_vectors = self._embedder.embed([query])
-        logger.info("Query embed took %.3fs", time.perf_counter() - t0)
+        with timed_phase("embed"):
+            query_vectors = self._embedder.embed([query])
 
         if not query_vectors:
             return []
-        t1 = time.perf_counter()
-        results = store.search(
-            query_embedding=query_vectors[0],
-            top_k=top_k,
-            path_prefix=path_prefix,
-            query_text=query,
-        )
-        logger.info("Vector search took %.3fs", time.perf_counter() - t1)
+        with timed_phase("vector_search"):
+            results = store.search(
+                query_embedding=query_vectors[0],
+                top_k=top_k,
+                path_prefix=path_prefix,
+                query_text=query,
+            )
 
         return self._booster.boost(results)
 

{coderay-1.0.4 → coderay-1.0.6/src/coderay.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderay
-Version: 1.0.4
+Version: 1.0.6
 Summary: X-ray your codebase — semantic search, code graphs, file skeletons, and MCP server
 Author-email: Bogdan Copocean <bogdancopocean@gmail.com>
 License-Expression: MIT
@@ -64,6 +64,15 @@ AI coding assistants and a standalone CLI.
 
 ## Install
 
+Create a virtual environment (recommended):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Then install:
+
 ```bash
 pip install coderay
 ```
@@ -79,6 +88,7 @@ For development:
 ```bash
 git clone https://github.com/bogdan-copocean/coderay.git
 cd coderay
+python -m venv .venv && source .venv/bin/activate
 pip install -e ".[all]"
 ```
 
@@ -86,15 +96,22 @@ pip install -e ".[all]"
 
 ```bash
 cd /path/to/your/project
-coderay build --repo .
+coderay watch --repo .   # keeps index fresh while you work (recommended)
 coderay search "how does authentication work"
-coderay watch --repo .
 coderay graph --kind calls
 coderay skeleton src/app/main.py
 ```
 
+> **Use `watch`, not `build`.** `coderay build` is a one-off; while you work, the index will get stale. `coderay watch` re-indexes on file changes and is the go-to for active development.
+
 ## MCP server (Claude Code / Cursor)
 
+Find the MCP executable path:
+
+```bash
+which coderay-mcp
+```
+
 Add to `~/.claude/claude_code_config.json` or Cursor MCP settings:
 
 ```json
@@ -108,13 +125,14 @@ Add to `~/.claude/claude_code_config.json` or Cursor MCP settings:
 }
 ```
 
+Replace `/path/to/your/.venv/bin/coderay-mcp` with the output of `which coderay-mcp`.
+
 ## CLI reference
 
 | Command | Description |
 |---|---|
-| `coderay build [--full] --repo .` | Build index (incremental or full rebuild) |
-| `coderay update --repo .` | Incremental update (changed files only) |
-| `coderay watch --repo . [--debounce N]` | Watch for file changes, re-index automatically |
+| `coderay watch --repo . [--debounce N]` | **Recommended.** Watch for file changes, re-index automatically |
+| `coderay build [--full] --repo .` | Build or incremental update. Use `--full` for full rebuild |
 | `coderay search "query" [--top-k N]` | Semantic search |
 | `coderay list [--by-file]` | List indexed chunks |
 | `coderay status` | Index state, branch, commit, chunk count |
@@ -124,39 +142,37 @@ Add to `~/.claude/claude_code_config.json` or Cursor MCP settings:
 
 ## Configuration
 
-Optional `config.yaml` in the index directory:
+File discovery and ignoring are based on `.git` and `.gitignore`. The `.git` directory is excluded; files matching `.gitignore` are not indexed. Config `exclude_patterns` add extra exclusions on top of that.
+
+Optional `config.yaml` in the index directory (default: `.index/config.yaml`):
 
 ```yaml
 embedder:
-  provider: local
-  model: all-MiniLM-L6-v2
+  model: sentence-transformers/all-MiniLM-L6-v2
   dimensions: 384
 
-search:
-  boost_rules:
-    "tests/": 0.5
-    "src/core/": 1.2
-
-graph:
-  exclude_callees:
-    - "our_sdk_helper"
-  include_callees:
-    - "isinstance"
-
-watch:
-  debounce_seconds: 2
-  branch_switch_threshold: 50
-  exclude_patterns:
+index:
+  exclude_patterns:  # besides .gitignore
     - "*.log"
-```
 
-## Development
+semantic_search:
+  boosting:
+    penalties:
+      - pattern: "(^|/)tests?/"
+        factor: 0.5
+      - pattern: "(^|/)test_[^/]+\\.py$"
+        factor: 0.5
+    bonuses:
+      - pattern: "(^|/)src/"
+        factor: 1.1
+  metric: cosine
+
+watcher:
+  debounce: 2
+  exclude_patterns:  # besides .gitignore
+    - "*.log"
 
-```bash
-pip install -e ".[dev]"
-make test
-make lint
-make format
+graph:
+  exclude_modules: []   # module names to exclude from CALLS/IMPORTS edges
+  include_modules: []  # force-include (override excludes)
 ```
-
-Requires Python >= 3.10 and Git.