Merge pull request #7 from Codeturion/feature/line-numbers

Add line numbers to all records for targeted source reads

Author: Codeturion

README.md

@@ -42,25 +42,24 @@ Restart your AI tool and ask: *"What methods does MyService have?"*
 
 Add this to your project's `CLAUDE.md` (or equivalent instructions file). **This step is important.** Without it, the AI has the tools but won't know when to reach for them.
 
-```markdown
+````markdown
 ## Codebase API Lookup (codesurface MCP)
 
-When you need to find a class, method, property, or field — use the codesurface MCP tools BEFORE Grep, Glob, or Read. They return compact, ranked results and save tokens.
-
-| When | Tool | Example |
-|------|------|---------|
-| Searching for an API by keyword | `search` | `search("MergeService")` |
-| Need exact method signature | `get_signature` | `get_signature("TryMerge")` |
-| Want all members on a class | `get_class` | `get_class("BlastBoardModel")` |
-| Overview of indexed codebase | `get_stats` | `get_stats()` |
-| Force refresh after bulk file changes | `reindex` | `reindex()` (auto-refreshes on query misses) |
-
-**Rules:**
-- Before looking up a class or method, use `search` or `get_signature` instead of Grep/Glob/Read
-- Use `get_class` to see all members on a class instead of reading the source file
-- The index auto-refreshes on query misses — no need to manually reindex after editing files
-- Only fall back to Grep/Read when you need implementation details (method bodies, control flow) that the API index doesn't cover
-```
+Use codesurface MCP tools BEFORE Grep, Glob, Read, or Task (subagents) for any class/method/field lookup. This applies to you AND any subagents you spawn.
+
+| Tool | Use when | Example |
+|------|----------|---------|
+| `search` | Find APIs by keyword | `search("MergeService")` |
+| `get_signature` | Need exact signature | `get_signature("TryMerge")` |
+| `get_class` | See all members on a class | `get_class("BlastBoardModel")` |
+| `get_stats` | Codebase overview | `get_stats()` |
+
+Every result includes file path + line numbers. Use them for targeted reads:
+- `File: Service.cs:32` → `Read("Service.cs", offset=32, limit=15)`
+- `File: Converter.java:504-506` → `Read("Converter.java", offset=504, limit=10)`
+
+Never read a full file when you have a line number. Only fall back to Grep/Read for implementation details (method bodies, control flow).
+````
 
 ## Tools
 
@@ -92,6 +91,30 @@ When you need to find a class, method, property, or field — use the codesurfac
 | [gin](https://github.com/gin-gonic/gin) | Go | 41 | 574 | <0.1s |
 | Unity game (private) | C# | 129 | 1,018 | 0.1s |
 
+## Line Numbers for Targeted Reads
+
+Every record includes `line_start` and `line_end` (1-indexed). Multi-line declarations span the full signature:
+
+```
+[METHOD] com.google.common.base.Converter.from
+  Signature: static Converter<A, B> from(Function<...> forward, Function<...> backward)
+  File: Converter.java:504-506          ← multi-line signature
+
+[METHOD] server.AlbumController.createAlbum
+  Signature: createAlbum(@Auth() auth: AuthDto, @Body() dto: CreateAlbumDto)
+  File: album.controller.ts:46          ← single-line
+```
+
+This lets AI agents do **targeted reads** instead of reading full files:
+
+```python
+# Instead of reading the entire 600-line file:
+Read("Converter.java")                     # 600 lines, ~12k tokens
+
+# Read just the method + context:
+Read("Converter.java", offset=504, limit=10)  # 10 lines, ~200 tokens
+```
+
 ## Benchmarks
 
 Measured against a real Unity game project (129 files, 1,018 API records) across a 10-step cross-cutting research workflow.

src/codesurface/db.py

@@ -58,6 +58,8 @@ def _build_search_text(record: dict) -> str:
     params_json TEXT NOT NULL DEFAULT '[]',
     returns_text TEXT NOT NULL DEFAULT '',
     file_path TEXT NOT NULL DEFAULT '',
+    line_start INTEGER NOT NULL DEFAULT 0,
+    line_end INTEGER NOT NULL DEFAULT 0,
     search_text TEXT NOT NULL DEFAULT ''
 );
 
@@ -99,8 +101,9 @@ def insert_records(conn: sqlite3.Connection, records: list[dict]) -> int:
     sql = """
         INSERT OR REPLACE INTO api_records
         (fqn, namespace, class_name, member_name, member_type,
-         signature, summary, params_json, returns_text, file_path, search_text)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         signature, summary, params_json, returns_text, file_path,
+         line_start, line_end, search_text)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     """
     rows = [
         (
@@ -114,6 +117,8 @@ def insert_records(conn: sqlite3.Connection, records: list[dict]) -> int:
             json.dumps(r.get("params_json", [])),
             r.get("returns_text", ""),
             r.get("file_path", ""),
+            r.get("line_start", 0),
+            r.get("line_end", 0),
             _build_search_text(r),
         )
         for r in records

src/codesurface/parsers/csharp.py

@@ -200,6 +200,8 @@ def _parse_cs_file(path: Path, base_dir: Path) -> list[dict]:
                     params_json=doc.get("params", []),
                     returns_text="",
                     file_path=rel_path,
+                    line_start=i + 1,
+                    line_end=i + 1,
                 ))
 
                 # For enums, extract members
@@ -248,6 +250,8 @@ def _parse_cs_file(path: Path, base_dir: Path) -> list[dict]:
                             params_json=[],
                             returns_text="",
                             file_path=rel_path,
+                            line_start=i + 1,
+                            line_end=i + 1,
                         ))
                     brace_depth = new_depth
                     i += 1
@@ -258,7 +262,7 @@ def _parse_cs_file(path: Path, base_dir: Path) -> list[dict]:
                 # Try constructor first
                 ctor_match = _CTOR_RE.match(line)
                 if ctor_match and ctor_match.group(1) == current_class:
-                    params_str = _collect_params(lines, i, ctor_match.group(2))
+                    params_str, end_i = _collect_params(lines, i, ctor_match.group(2))
                     doc = _look_back_for_doc(lines, i)
                     sig = f"{current_class}({params_str})"
                     records.append(_build_record(
@@ -272,6 +276,8 @@ def _parse_cs_file(path: Path, base_dir: Path) -> list[dict]:
                         params_json=doc.get("params", []),
                         returns_text="",
                         file_path=rel_path,
+                        line_start=i + 1,
+                        line_end=end_i + 1,
                     ))
                     brace_depth = new_depth
                     i += 1
@@ -281,7 +287,7 @@ def _parse_cs_file(path: Path, base_dir: Path) -> list[dict]:
                 if method_match:
                     ret_type = method_match.group(1).strip()
                     meth_name = method_match.group(2)
-                    params_str = _collect_params(lines, i, method_match.group(3))
+                    params_str, end_i = _collect_params(lines, i, method_match.group(3))
                     if meth_name not in _SKIP_NAMES:
                         doc = _look_back_for_doc(lines, i)
                         sig = f"{ret_type} {meth_name}({params_str})"
@@ -296,6 +302,8 @@ def _parse_cs_file(path: Path, base_dir: Path) -> list[dict]:
                             params_json=doc.get("params", []),
                             returns_text=doc.get("returns", ""),
                             file_path=rel_path,
+                            line_start=i + 1,
+                            line_end=end_i + 1,
                         ))
                     brace_depth = new_depth
                     i += 1
@@ -323,6 +331,8 @@ def _parse_cs_file(path: Path, base_dir: Path) -> list[dict]:
                             params_json=[],
                             returns_text="",
                             file_path=rel_path,
+                            line_start=i + 1,
+                            line_end=i + 1,
                         ))
                     brace_depth = new_depth
                     i += 1
@@ -351,6 +361,8 @@ def _parse_cs_file(path: Path, base_dir: Path) -> list[dict]:
                             params_json=[],
                             returns_text="",
                             file_path=rel_path,
+                            line_start=i + 1,
+                            line_end=i + 1,
                         ))
                     brace_depth = new_depth
                     i += 1
@@ -402,6 +414,8 @@ def _try_parse_interface_member(
                 params_json=doc.get("params", []),
                 returns_text=doc.get("returns", ""),
                 file_path=file_path,
+                line_start=idx + 1,
+                line_end=idx + 1,
             )
 
     # Interface property
@@ -424,6 +438,8 @@ def _try_parse_interface_member(
                 params_json=[],
                 returns_text="",
                 file_path=file_path,
+                line_start=idx + 1,
+                line_end=idx + 1,
             )
 
     return None
@@ -467,6 +483,8 @@ def _parse_enum_members(
                         params_json=[],
                         returns_text="",
                         file_path=file_path,
+                        line_start=i + 1,
+                        line_end=i + 1,
                     ))
     return records
 
@@ -518,23 +536,29 @@ def _look_back_for_doc(lines: list[str], decl_idx: int) -> dict:
     return result
 
 
-def _collect_params(lines: list[str], line_idx: int, initial: str) -> str:
-    """Collect parameters that may span multiple lines."""
+def _collect_params(lines: list[str], line_idx: int, initial: str) -> tuple[str, int]:
+    """Collect parameters that may span multiple lines.
+
+    Returns (params_str, end_line_idx) where end_line_idx is the 0-based
+    index of the last line consumed by the parameter list.
+    """
     params = initial.strip()
     if ")" in lines[line_idx]:
-        return params
+        return re.sub(r"\s+", " ", params).strip(), line_idx
 
     # Multi-line params -- collect until closing paren
+    end = line_idx
     for j in range(line_idx + 1, min(line_idx + 50, len(lines))):
         part = lines[j].strip()
         params += " " + part
+        end = j
         if ")" in part:
             # Trim at closing paren
             paren_idx = params.index(")")
             params = params[:paren_idx]
             break
 
-    return re.sub(r"\s+", " ", params).strip()
+    return re.sub(r"\s+", " ", params).strip(), end
 
 
 def _extract_accessors(line: str) -> str:

src/codesurface/parsers/go.py

@@ -429,7 +429,7 @@ def _parse_go_file(path: Path, base_dir: Path) -> list[dict]:
             method_name = method_m.group(3)
 
             if _is_exported(method_name) and _is_exported(receiver_type):
-                full_sig, _ = _collect_signature(lines, i)
+                full_sig, end_i = _collect_signature(lines, i)
                 params_str, returns_str = _extract_func_parts(full_sig, method_name)
                 doc = _look_back_for_doc_comment(lines, i)
 
@@ -446,6 +446,8 @@ def _parse_go_file(path: Path, base_dir: Path) -> list[dict]:
                     signature=sig,
                     summary=doc,
                     file_path=rel_path,
+                    line_start=i + 1,
+                    line_end=end_i + 1,
                 ))
 
             brace_depth = new_depth
@@ -458,7 +460,7 @@ def _parse_go_file(path: Path, base_dir: Path) -> list[dict]:
             func_name = func_m.group(1)
 
             if _is_exported(func_name):
-                full_sig, _ = _collect_signature(lines, i)
+                full_sig, end_i = _collect_signature(lines, i)
                 params_str, returns_str = _extract_func_parts(full_sig, func_name)
                 doc = _look_back_for_doc_comment(lines, i)
 
@@ -475,6 +477,8 @@ def _parse_go_file(path: Path, base_dir: Path) -> list[dict]:
                     signature=sig,
                     summary=doc,
                     file_path=rel_path,
+                    line_start=i + 1,
+                    line_end=end_i + 1,
                 ))
 
             brace_depth = new_depth
@@ -500,6 +504,8 @@ def _parse_go_file(path: Path, base_dir: Path) -> list[dict]:
                     signature=sig,
                     summary=doc,
                     file_path=rel_path,
+                    line_start=i + 1,
+                    line_end=i + 1,
                 ))
 
             brace_depth = new_depth
@@ -527,6 +533,8 @@ def _parse_go_file(path: Path, base_dir: Path) -> list[dict]:
                         signature=sig,
                         summary=doc,
                         file_path=rel_path,
+                        line_start=i + 1,
+                        line_end=i + 1,
                     ))
                     if "{" in line:
                         current_type = type_name
@@ -545,6 +553,8 @@ def _parse_go_file(path: Path, base_dir: Path) -> list[dict]:
                         signature=sig,
                         summary=doc,
                         file_path=rel_path,
+                        line_start=i + 1,
+                        line_end=i + 1,
                     ))
                     if "{" in line:
                         current_type = type_name
@@ -565,6 +575,8 @@ def _parse_go_file(path: Path, base_dir: Path) -> list[dict]:
                         signature=sig,
                         summary=doc,
                         file_path=rel_path,
+                        line_start=i + 1,
+                        line_end=i + 1,
                     ))
 
             brace_depth = new_depth
@@ -590,6 +602,8 @@ def _parse_go_file(path: Path, base_dir: Path) -> list[dict]:
                     signature=sig,
                     summary=doc,
                     file_path=rel_path,
+                    line_start=i + 1,
+                    line_end=i + 1,
                 ))
 
             brace_depth = new_depth
@@ -622,6 +636,8 @@ def _parse_go_file(path: Path, base_dir: Path) -> list[dict]:
                     signature=sig,
                     summary=doc,
                     file_path=rel_path,
+                    line_start=i + 1,
+                    line_end=i + 1,
                 ))
 
             brace_depth = new_depth
@@ -692,6 +708,8 @@ def _try_parse_struct_field(
         signature=sig,
         summary=doc,
         file_path=file_path,
+        line_start=idx + 1,
+        line_end=idx + 1,
     ))
 
 
@@ -721,7 +739,7 @@ def _try_parse_interface_method(
     if not _is_exported(method_name):
         return
 
-    full_sig, _ = _collect_signature(lines, idx)
+    full_sig, end_i = _collect_signature(lines, idx)
     params_str, returns_str = _extract_iface_method_parts(full_sig, method_name)
     doc = _look_back_for_doc_comment(lines, idx)
 
@@ -738,6 +756,8 @@ def _try_parse_interface_method(
         signature=sig,
         summary=doc,
         file_path=file_path,
+        line_start=idx + 1,
+        line_end=end_i + 1,
     ))
 
 
@@ -771,6 +791,8 @@ def _parse_group_type_entry(
                 signature=sig,
                 summary=doc,
                 file_path=file_path,
+                line_start=idx + 1,
+                line_end=idx + 1,
             ))
         return
 
@@ -799,6 +821,8 @@ def _parse_group_type_entry(
             signature=sig,
             summary=doc,
             file_path=file_path,
+            line_start=idx + 1,
+            line_end=idx + 1,
         ))
     elif rest.startswith("interface"):
         sig = f"type {name} interface"
@@ -812,6 +836,8 @@ def _parse_group_type_entry(
             signature=sig,
             summary=doc,
             file_path=file_path,
+            line_start=idx + 1,
+            line_end=idx + 1,
         ))
     else:
         underlying = rest.rstrip("{").strip()
@@ -826,6 +852,8 @@ def _parse_group_type_entry(
             signature=sig,
             summary=doc,
             file_path=file_path,
+            line_start=idx + 1,
+            line_end=idx + 1,
         ))
 
 
@@ -884,6 +912,8 @@ def _parse_group_var_const_entry(
         signature=sig,
         summary=doc,
         file_path=file_path,
+        line_start=idx + 1,
+        line_end=idx + 1,
     ))