code-search-cli 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

code_retrieval/cli.py

@@ -5,30 +5,44 @@ import json
 import sqlite3
 import subprocess
 import sys
+from importlib.metadata import PackageNotFoundError, version
 
 from .engine import RetrievalEngine
 from .index_store import PersistentIndex
-from .installer import install_codex_skill, uninstall_codex_skill
+from .installer import (
+    AGENT_SELECTORS,
+    AgentName,
+    agent_display_name,
+    install_skills,
+    uninstall_skills,
+)
 from .models import Evidence
-from .repository import RepositoryReader
+from .repository import RETRIEVAL_SCOPES, RepositoryReader
 
 
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="code-search", description="Task-aware local code retrieval")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {_package_version()}")
     subparsers = parser.add_subparsers(dest="command", required=True)
 
     retrieve = subparsers.add_parser("retrieve", help="build an evidence bundle for a task")
     _repository_args(retrieve)
     retrieve.add_argument("--task", required=True, help="engineering task or failure description")
-    retrieve.add_argument("--max-evidence", type=int, default=16)
+    retrieve.add_argument("--max-evidence", type=_positive_int, default=16)
+    retrieve.add_argument(
+        "--scope",
+        choices=RETRIEVAL_SCOPES,
+        default="all",
+        help="limit retrieval to code, tests, or configuration files",
+    )
     retrieve.add_argument("--format", choices=("markdown", "json"), default="markdown")
 
     expand = subparsers.add_parser("expand", help="expand a known source anchor")
     _repository_args(expand)
     expand.add_argument("--path", required=True, help="repository-relative source path")
-    anchor = expand.add_mutually_exclusive_group()
-    anchor.add_argument("--line", type=int)
-    anchor.add_argument("--symbol")
+    anchor = expand.add_mutually_exclusive_group(required=True)
+    anchor.add_argument("--line", type=_positive_int)
+    anchor.add_argument("--symbol", type=_non_empty)
     expand.add_argument("--relation", choices=("enclosing", "siblings", "references"), default="enclosing")
     expand.add_argument("--format", choices=("markdown", "json"), default="markdown")
 
@@ -43,11 +57,25 @@ def build_parser() -> argparse.ArgumentParser:
     clean = subparsers.add_parser("clean", help="remove the persistent index for a repository")
     _repository_args(clean)
 
-    install = subparsers.add_parser("install", help="install the bundled Codex skill")
+    install = subparsers.add_parser("install", help="install the bundled skill for a coding agent")
+    install.add_argument(
+        "--target",
+        choices=AGENT_SELECTORS,
+        default="codex",
+        help="agent destination; 'detected' uses best-effort local signals (default: codex)",
+    )
     install.add_argument("--force", action="store_true", help="replace a locally modified installed skill")
-
-    uninstall = subparsers.add_parser("uninstall", help="remove the bundled Codex skill")
+    install.add_argument("--dry-run", action="store_true", help="preview changes without writing files")
+
+    uninstall = subparsers.add_parser("uninstall", help="remove the bundled skill for a coding agent")
+    uninstall.add_argument(
+        "--target",
+        choices=AGENT_SELECTORS,
+        default="codex",
+        help="agent destination; 'detected' uses best-effort local signals (default: codex)",
+    )
     uninstall.add_argument("--force", action="store_true", help="remove a locally modified installed skill")
+    uninstall.add_argument("--dry-run", action="store_true", help="preview changes without removing files")
     return parser
 
 
@@ -55,11 +83,14 @@ def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
     try:
         if args.command in {"install", "uninstall"}:
-            operation = install_codex_skill if args.command == "install" else uninstall_codex_skill
-            path, action = operation(force=args.force)
-            print(f"Codex skill {action}: {path}")
-            if args.command == "install":
-                print("Restart Codex to load the skill.")
+            operation = install_skills if args.command == "install" else uninstall_skills
+            results = operation(target=args.target, force=args.force, dry_run=args.dry_run)
+            for result in results:
+                action = f"would be {result.action}" if args.dry_run else result.action
+                print(f"{agent_display_name(result.agent)} skill {action}: {result.path}")
+            if args.command == "install" and not args.dry_run:
+                for result in results:
+                    print(_skill_reload_hint(result.agent))
             return 0
 
         if args.command in {"index", "status", "clean"}:
@@ -78,7 +109,7 @@ def main(argv: list[str] | None = None) -> int:
 
         engine = RetrievalEngine(args.repo, args.ref)
         if args.command == "retrieve":
-            result = engine.retrieve(args.task, args.max_evidence)
+            result = engine.retrieve(args.task, args.max_evidence, scope=args.scope)
             output = json.dumps(result.to_dict(), ensure_ascii=False, indent=2) if args.format == "json" else result.to_markdown()
         else:
             evidence = engine.expand(
@@ -100,6 +131,36 @@ def _repository_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--ref", help="optional Git commit, tag, or branch; does not modify the working tree")
 
 
+def _package_version() -> str:
+    try:
+        return version("code-search-cli")
+    except PackageNotFoundError:
+        return "0+unknown"
+
+
+def _positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed < 1:
+        raise argparse.ArgumentTypeError("must be at least 1")
+    return parsed
+
+
+def _non_empty(value: str) -> str:
+    if not value.strip():
+        raise argparse.ArgumentTypeError("must not be empty")
+    return value
+
+
+def _skill_reload_hint(agent: AgentName) -> str:
+    if agent == "codex":
+        return "Restart Codex if the skill does not appear automatically."
+    if agent == "gemini":
+        return "Run /skills reload in Gemini CLI if the skill does not appear automatically."
+    if agent == "kiro":
+        return "Kiro loads Agent Skills automatically; reopen the session if it is not listed."
+    return f"Restart {agent_display_name(agent)} if the skill does not appear automatically."
+
+
 def _evidence_json(evidence: list[Evidence]) -> str:
     from dataclasses import asdict
 
@@ -113,6 +174,8 @@ def _evidence_markdown(evidence: list[Evidence]) -> str:
             [
                 f"## `{item.path}:{item.start_line}-{item.end_line}`",
                 "",
+                f"Role `{item.role}`; {item.confidence} confidence from `{item.provenance}`",
+                "",
                 "; ".join(item.reasons),
                 "",
                 "```",

code_retrieval/engine.py

@@ -9,12 +9,23 @@ from pathlib import Path
 
 from .index_store import IndexRefresh, PersistentIndex
 from .models import Evidence, RetrievalResult, Section, SourceFile
-from .query import document_terms, query_terms, split_identifier
-from .repository import RepositoryReader
+from .query import document_terms, query_terms, split_identifier, stem
+from .repository import RETRIEVAL_SCOPES, RepositoryReader, source_scope
 from .structure import containing_section, sections_for
 
-
 SYMBOL_RE = re.compile(r"\b[A-Z][A-Za-z0-9_$]{3,}\b")
+EXACT_SYMBOL_QUERY_RE = re.compile(
+    r"[A-Za-z_$][A-Za-z0-9_$]*(?:(?:::|[.#\\])[A-Za-z_$][A-Za-z0-9_$]*)*"
+)
+DECLARATION_KEYWORDS = (
+    r"actor|class|def|enum|fn|func|function|interface|module|namespace|"
+    r"object|protocol|record|struct|trait|type|typealias|union|using"
+)
+IDENTIFIER_CHAR_CLASS = r"A-Za-z0-9_$"
+USING_ALIAS_SUFFIX_RE = re.compile(r"\s*=")
+EVENT_EMISSION_RE = re.compile(
+    r"\b(?:dispatchEvent|dispatch_event|emit|emitEvent|emit_event|publishEvent|publish_event)\s*\("
+)
 
 
 @dataclass(slots=True)
@@ -42,20 +53,31 @@ class RetrievalEngine:
         self,
         task: str,
         max_evidence: int = 16,
+        *,
+        scope: str = "all",
     ) -> RetrievalResult:
         if not task.strip():
             raise ValueError("task must not be empty")
+        if scope not in RETRIEVAL_SCOPES:
+            raise ValueError(f"scope must be one of: {', '.join(RETRIEVAL_SCOPES)}")
         started = time.perf_counter()
         weighted, original = query_terms(task)
-        files = self._load_files()
+        indexed_files = self._load_files()
+        files = [
+            source
+            for source in indexed_files
+            if scope == "all" or source_scope(source.path) == scope
+        ]
         candidates = self._rank_files(task, files, weighted, original)
         section_candidates = self._rank_sections(candidates[:40], weighted, original)
         section_candidates.extend(self._reference_expansion(task, candidates, section_candidates, weighted, original))
+        section_candidates.extend(self._collaborator_expansion(candidates, section_candidates, weighted))
         section_candidates.extend(self._structural_expansion(task, candidates))
         section_candidates.extend(self._call_expansion(candidates, section_candidates, weighted))
         section_candidates.extend(self._sibling_contrast_expansion(task, candidates, weighted, original))
         section_candidates.extend(self._initialization_order_expansion(task, candidates, weighted))
         section_candidates.extend(self._dependency_order_expansion(task, candidates, weighted))
+        section_candidates.extend(self._exact_symbol_expansion(task, candidates))
         evidence = self._pack(section_candidates, max_evidence)
         elapsed = time.perf_counter() - started
         used = sum(item.estimated_tokens for item in evidence)
@@ -67,14 +89,84 @@ class RetrievalEngine:
             query_terms=original,
             evidence=evidence,
             stats={
-                "source_files": len(files),
+                "source_files": len(indexed_files),
+                "searched_files": len(files),
                 "candidate_files": len(candidates),
                 "elapsed_ms": round(elapsed * 1000, 2),
-                "strategy": "weighted-lexical+structure+references+causal-contrast",
+                "strategy": "weighted-lexical+structure+exact-symbol+references+causal-contrast",
+                "scope": scope,
                 "index": self._index_refresh.to_dict() if self._index_refresh else None,
             },
         )
 
+    def _exact_symbol_expansion(
+        self,
+        task: str,
+        files: list[_FileCandidate],
+    ) -> list[Evidence]:
+        symbol = _exact_symbol_query(task)
+        if symbol is None:
+            return []
+        raw_query = task.strip()
+        declaration_pattern = _direct_declaration_pattern(raw_query)
+        symbol_pattern = _exact_occurrence_pattern(symbol)
+        expanded: list[Evidence] = []
+        for file_rank, candidate in enumerate(files[:12], 1):
+            lines = candidate.source.content.splitlines()
+            occurrences: list[int] = []
+            for line_number, line in enumerate(lines, 1):
+                for match in declaration_pattern.finditer(line):
+                    if (
+                        match.group("keyword") != "using"
+                        or USING_ALIAS_SUFFIX_RE.match(line, match.end())
+                    ):
+                        occurrences.append(line_number)
+                        break
+            if not occurrences:
+                continue
+            windows = []
+            for line_number in occurrences:
+                start = max(1, min(line_number - 6, max(1, len(lines) - 19)))
+                end = min(len(lines), start + 19)
+                content = "\n".join(lines[start - 1 : end])
+                density = len(symbol_pattern.findall(content))
+                windows.append(
+                    (
+                        density,
+                        -line_number,
+                        Section(
+                            candidate.source.path,
+                            symbol,
+                            "symbol-window",
+                            start,
+                            end,
+                            content,
+                        ),
+                    )
+                )
+            _, _, section = max(
+                windows,
+                key=lambda item: item[:-1],
+            )
+            reasons = [
+                f"file rank {file_rank}",
+                f"exact symbol occurrence `{raw_query}`",
+                "line text places the symbol directly after a declaration keyword",
+            ]
+            expanded.append(
+                _evidence(
+                    section,
+                    candidate.score,
+                    reasons,
+                    role="anchor",
+                    provenance="exact-symbol",
+                    confidence="medium",
+                )
+            )
+            if len(expanded) == 2:
+                break
+        return expanded
+
     def prepare(self) -> dict[str, float | int]:
         """Build the reusable in-process lexical and structural index."""
         started = time.perf_counter()
@@ -109,6 +201,7 @@ class RetrievalEngine:
         if relation == "enclosing":
             selected = [anchor]
             reason = "enclosing structural unit"
+            role, provenance, confidence = "anchor", "structure", "high"
         elif relation == "references":
             name = symbol or anchor.name
             selected = []
@@ -118,10 +211,22 @@ class RetrievalEngine:
                         containing_section(candidate, _first_line(candidate.content, name), self._sections_for(candidate))
                     )
             reason = f"references `{name}`"
+            role, provenance, confidence = "reference", "exact-symbol", "high"
         else:
             selected = [item for item in sections if item.name != anchor.name]
             reason = f"sibling of `{anchor.name}`"
-        items = [_evidence(item, 1.0, [reason]) for item in selected]
+            role, provenance, confidence = "sibling", "structure", "high"
+        items = [
+            _evidence(
+                item,
+                1.0,
+                [reason],
+                role=role,
+                provenance=provenance,
+                confidence=confidence,
+            )
+            for item in selected
+        ]
         return self._pack(items, 20)
 
     def _load_files(self) -> list[SourceFile]:
@@ -141,10 +246,32 @@ class RetrievalEngine:
         original: list[str],
     ) -> list[_FileCandidate]:
         task_lower = task.lower()
+        query_stems = {stem(term) for term in weighted}
+        wants_tests = bool(
+            set(split_identifier(task))
+            & {"test", "tests", "testing", "tested", "spec", "specs", "regression", "coverage"}
+        )
         candidates = []
+        # Long natural-language tasks (issue reports) match everything in huge
+        # files; pivoted length normalization makes those files earn their
+        # term frequencies. Short tasks keep raw scoring.
+        normalize_length = len(original) >= 12
+        lengths = {}
+        average_length = 1.0
+        if normalize_length:
+            lengths = {source.path: sum(self._terms_for_source(source).values()) for source in files}
+            average_length = (sum(lengths.values()) / len(lengths)) if lengths else 1.0
         for source in files:
             terms = self._terms_for_source(source)
             path_terms = self._terms_for_path(source.path)
+            length_norm = 1.0
+            if normalize_length and average_length:
+                relative_length = lengths[source.path] / average_length
+                length_norm = max(0.4, min(1.0, 1.0 / (0.5 + 0.5 * relative_length)))
+                if _basename_stems(source.path) & query_stems:
+                    # A file named after a query concept must not be buried
+                    # for its size; soften the penalty.
+                    length_norm = max(length_norm, 0.85)
             score = 0.0
             matches = []
             for term, weight in weighted.items():
@@ -152,16 +279,29 @@ class RetrievalEngine:
                 path_count = path_terms.get(term, 0)
                 if content_count or path_count:
                     matches.append(term)
-                    score += weight * (math.log2(1 + min(content_count, 16)) + 5 * min(path_count, 1))
+                    score += weight * (
+                        length_norm * math.log2(1 + min(content_count, 16))
+                        + 5 * min(path_count, 1)
+                    )
             lowered = source.content.lower()
             if task_lower in lowered:
                 score += 20
                 matches.append("exact task phrase")
-            original_hits = sum(1 for term in original if terms.get(term) or path_terms.get(term))
+            original_hits = sum(
+                1
+                for term in original
+                if terms.get(term) or path_terms.get(term) or terms.get(stem(term))
+            )
             if original and original_hits == len(original):
                 score += 8
             elif original_hits >= 2:
                 score += original_hits
+            name_stems = _basename_stems(source.path)
+            if len(name_stems) >= 2 and name_stems <= query_stems:
+                score += 14.0 * len(name_stems)
+                matches.append("file name matches task")
+            if score > 0 and not wants_tests and source_scope(source.path) == "tests":
+                score *= 0.45
             if score > 0:
                 candidates.append(_FileCandidate(source, terms, score, matches))
         return sorted(candidates, key=lambda item: (-item.score, item.source.path))
@@ -174,6 +314,7 @@ class RetrievalEngine:
     ) -> list[Evidence]:
         result = []
         for file_rank, candidate in enumerate(candidates, 1):
+            name_bonus = 25.0 if "file name matches task" in candidate.matches else 0.0
             ranked = []
             for section in self._sections_for(candidate.source):
                 terms = self._terms_for_section(section)
@@ -183,7 +324,7 @@ class RetrievalEngine:
                 local = sum(weight * math.log2(1 + min(count, 12)) for term, count, weight in hits)
                 original_hits = sum(1 for term in original if terms.get(term))
                 local += 2 * original_hits
-                score = local + candidate.score * 0.35 - math.log2(file_rank + 1)
+                score = local + name_bonus + candidate.score * 0.35 - math.log2(file_rank + 1)
                 reasons = [f"file rank {file_rank}", "matched " + ", ".join(term for term, _, _ in hits[:6])]
                 focused = _focused_sections(section, weighted)
                 for window_rank, window in enumerate(focused):
@@ -235,22 +376,94 @@ class RetrievalEngine:
         expanded: list[Evidence] = []
         seen_paths = {item.path for item in sections[:4]}
         for symbol in symbols:
+            symbol_terms = frozenset(split_identifier(symbol))
+            symbol_pattern = rf"\b{re.escape(symbol)}\b"
             references = []
             for candidate in files:
-                if candidate.source.path in seen_paths or not re.search(rf"\b{re.escape(symbol)}\b", candidate.source.content):
+                if candidate.source.path in seen_paths:
+                    continue
+                if symbol_terms and not symbol_terms.issubset(candidate.terms):
+                    continue
+                if (
+                    symbol not in candidate.source.content
+                    or not re.search(symbol_pattern, candidate.source.content)
+                ):
                     continue
                 line = _first_line(candidate.source.content, symbol)
                 section = containing_section(candidate.source, line, self._sections_for(candidate.source))
-                terms = document_terms(section.content)
+                terms = self._terms_for_section(section)
                 task_hits = sum(weight for term, weight in weighted.items() if terms.get(term))
                 score = candidate.score * 0.15 + task_hits + 2
                 references.append(
-                    _evidence(_focused_section(section, weighted, line), score, [f"references anchor `{symbol}`"])
+                    _evidence(
+                        _focused_section(section, weighted, line),
+                        score,
+                        [f"references anchor `{symbol}`"],
+                        role="reference",
+                        provenance="exact-symbol",
+                        confidence="high",
+                    )
                 )
             references.sort(key=lambda item: (-item.score, item.path))
             expanded.extend(references[:5])
         return expanded
 
+    def _collaborator_expansion(
+        self,
+        candidates: list[_FileCandidate],
+        sections: list[Evidence],
+        weighted: dict[str, float],
+    ) -> list[Evidence]:
+        if not sections:
+            return []
+        primary_path = sections[0].path
+        primary = next(
+            (candidate for candidate in candidates if candidate.source.path == primary_path),
+            None,
+        )
+        if primary is None:
+            return []
+        by_name = {}
+        for candidate in candidates[1:60]:
+            name = Path(candidate.source.path).stem
+            if candidate.source.path != primary_path and name not in by_name:
+                by_name[name] = candidate
+        counts = Counter(SYMBOL_RE.findall(primary.source.content))
+        referenced = sorted(
+            (
+                (counts[name], candidate)
+                for name, candidate in by_name.items()
+                if counts.get(name, 0) >= 3
+            ),
+            key=lambda item: (-item[0], item[1].source.path),
+        )
+        covered = {item.path for item in sections[:6]}
+        expanded = []
+        primary_name = Path(primary_path).stem
+        for count, candidate in referenced[:2]:
+            if candidate.source.path in covered:
+                continue
+            best = None
+            best_signal = 0.0
+            for section in self._sections_for(candidate.source):
+                terms = self._terms_for_section(section)
+                signal = sum(weight for term, weight in weighted.items() if terms.get(term))
+                if signal > best_signal:
+                    best, best_signal = section, signal
+            if best is None:
+                continue
+            expanded.append(
+                _evidence(
+                    _focused_section(best, weighted, best.start_line),
+                    candidate.score * 0.3 + best_signal + 4,
+                    [f"collaborates with `{primary_name}` ({count} references)"],
+                    role="reference",
+                    provenance="structure",
+                    confidence="medium",
+                )
+            )
+        return expanded
+
     def _structural_expansion(self, task: str, files: list[_FileCandidate]) -> list[Evidence]:
         intent = set(split_identifier(task))
         non_schedule_intent = intent - {
@@ -306,6 +519,9 @@ class RetrievalEngine:
                     score,
                     labels + [f"obligation: {matched_label}" for matched_label in labels]
                     + ["task-specific structural pattern"],
+                    role="structural-obligation",
+                    provenance="syntax-pattern",
+                    confidence="medium",
                 )
             )
         expanded.sort(key=lambda item: (-item.score, item.path))
@@ -340,6 +556,9 @@ class RetrievalEngine:
                         _focused_section(target, weighted),
                         score,
                         [f"called by `{anchor.name}`", "definition expansion"],
+                        role="definition",
+                        provenance="same-file-call",
+                        confidence="medium",
                     )
                 )
         expanded.sort(key=lambda item: (-item.score, item.path, item.start_line))
@@ -361,12 +580,11 @@ class RetrievalEngine:
             if term not in {"callback", "callbacks", "event", "events", "listener", "subscriber"}
         }
         identity_terms = identity_terms or weighted
-        publication = re.compile(r"\bpublishEvent\s*\(")
         expanded: list[Evidence] = []
         for candidate in files[:30]:
             sections = [item for item in self._sections_for(candidate.source) if item.kind in {"method", "function"}]
             for target in sections:
-                if publication.search(target.content):
+                if EVENT_EMISSION_RE.search(target.content):
                     continue
                 target_name_terms = set(split_identifier(target.name))
                 target_relevance = _term_signal(target, identity_terms)
@@ -374,7 +592,7 @@ class RetrievalEngine:
                     continue
                 comparisons = []
                 for sibling in sections:
-                    if sibling is target or not publication.search(sibling.content):
+                    if sibling is target or not EVENT_EMISSION_RE.search(sibling.content):
                         continue
                     sibling_name_terms = set(split_identifier(sibling.name))
                     common = target_name_terms & sibling_name_terms
@@ -398,6 +616,9 @@ class RetrievalEngine:
                                 "callback path lacks the sibling's event publication",
                                 "obligation: callback completion",
                             ],
+                            role="missing-behavior",
+                            provenance="sibling-contrast",
+                            confidence="medium",
                         ),
                         _evidence(
                             _focused_section(sibling, weighted),
@@ -406,6 +627,9 @@ class RetrievalEngine:
                                 f"comparison sibling for `{target.name}`",
                                 "contains event publication",
                             ],
+                            role="comparison",
+                            provenance="sibling-contrast",
+                            confidence="medium",
                         ),
                     ]
                 )
@@ -481,6 +705,9 @@ class RetrievalEngine:
                                     f"required repair site: initialize `{subscriber_name}` from this component",
                                     "obligation: initialization responsibility",
                                 ],
+                                role="repair-site",
+                                provenance="lifecycle-inference",
+                                confidence="medium",
                             ),
                             _evidence(
                                 _focused_section(registration, weighted),
@@ -489,6 +716,9 @@ class RetrievalEngine:
                                     f"registers the subscriber for `{event_type}`",
                                     f"initialization counterpart for `{publisher_name}`",
                                 ],
+                                role="registration",
+                                provenance="syntax-pattern",
+                                confidence="medium",
                             ),
                         ]
                     )
@@ -536,6 +766,9 @@ class RetrievalEngine:
                             "joint responsibility: order startup work after notifier initialization",
                             "obligation: startup dependency owner",
                         ],
+                        role="repair-site",
+                        provenance="lifecycle-inference",
+                        confidence="medium",
                     )
                 )
         expanded.sort(key=lambda item: (-item.score, item.path, item.start_line))
@@ -594,8 +827,9 @@ class RetrievalEngine:
                     selected.append(item)
                     break
 
-        # Prefer multiple candidate files before adding more results from the same file.
-        diversity_limit = min(4, limit)
+        # Prefer covering distinct files across the whole budget before adding
+        # more results from the same file.
+        diversity_limit = limit
         representatives: dict[str, Evidence] = {}
         for item in ranked:
             representatives.setdefault(item.path, item)
@@ -690,7 +924,25 @@ def _focused_sections(
     ]
 
 
-def _evidence(section: Section, score: float, reasons: list[str]) -> Evidence:
+def _basename_stems(path: str) -> frozenset[str]:
+    name = Path(path).stem
+    joined = name.lower().replace("_", "")
+    return frozenset(
+        stem(part)
+        for part in split_identifier(name)
+        if len(part) > 1 and part != joined
+    )
+
+
+def _evidence(
+    section: Section,
+    score: float,
+    reasons: list[str],
+    *,
+    role: str = "candidate",
+    provenance: str = "lexical",
+    confidence: str = "medium",
+) -> Evidence:
     return Evidence(
         path=section.path,
         start_line=section.start_line,
@@ -699,6 +951,9 @@ def _evidence(section: Section, score: float, reasons: list[str]) -> Evidence:
         name=section.name,
         score=round(score, 4),
         reasons=reasons,
+        role=role,
+        provenance=provenance,
+        confidence=confidence,
         content=section.content,
         estimated_tokens=max(1, (len(section.content) + 3) // 4),
     )
@@ -720,3 +975,25 @@ def _first_line(content: str, value: str) -> int:
         if value in line:
             return index
     return 1
+
+
+def _exact_symbol_query(task: str) -> str | None:
+    stripped = task.strip()
+    if not EXACT_SYMBOL_QUERY_RE.fullmatch(stripped):
+        return None
+    symbol = re.split(r"::|[.#\\]", stripped)[-1]
+    return symbol if len(symbol) >= 2 else None
+
+
+def _exact_occurrence_pattern(value: str) -> re.Pattern[str]:
+    return re.compile(
+        rf"(?<![{IDENTIFIER_CHAR_CLASS}]){re.escape(value)}"
+        rf"(?![{IDENTIFIER_CHAR_CLASS}])"
+    )
+
+
+def _direct_declaration_pattern(value: str) -> re.Pattern[str]:
+    return re.compile(
+        rf"\b(?P<keyword>{DECLARATION_KEYWORDS})\s+{re.escape(value)}"
+        rf"(?![{IDENTIFIER_CHAR_CLASS}])"
+    )