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

code_retrieval/engine.py

@@ -0,0 +1,722 @@
+from __future__ import annotations
+
+import math
+import re
+import time
+from collections import Counter
+from dataclasses import dataclass
+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 .structure import containing_section, sections_for
+
+
+SYMBOL_RE = re.compile(r"\b[A-Z][A-Za-z0-9_$]{3,}\b")
+
+
+@dataclass(slots=True)
+class _FileCandidate:
+    source: SourceFile
+    terms: Counter[str]
+    score: float
+    matches: list[str]
+
+
+class RetrievalEngine:
+    """Build a small, explainable evidence bundle for an engineering task."""
+
+    def __init__(self, repository: str | Path, ref: str | None = None):
+        self.reader = RepositoryReader(repository, ref)
+        self.index = PersistentIndex(self.reader)
+        self._index_refresh: IndexRefresh | None = None
+        self._files: list[SourceFile] | None = None
+        self._document_terms: dict[str, Counter[str]] = {}
+        self._path_terms: dict[str, Counter[str]] = {}
+        self._sections: dict[str, list[Section]] = {}
+        self._section_terms: dict[tuple[str, int, int], Counter[str]] = {}
+
+    def retrieve(
+        self,
+        task: str,
+        max_evidence: int = 16,
+    ) -> RetrievalResult:
+        if not task.strip():
+            raise ValueError("task must not be empty")
+        started = time.perf_counter()
+        weighted, original = query_terms(task)
+        files = self._load_files()
+        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._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))
+        evidence = self._pack(section_candidates, max_evidence)
+        elapsed = time.perf_counter() - started
+        used = sum(item.estimated_tokens for item in evidence)
+        return RetrievalResult(
+            task=task,
+            repository=str(self.reader.root),
+            ref=self.reader.ref,
+            used_tokens=used,
+            query_terms=original,
+            evidence=evidence,
+            stats={
+                "source_files": len(files),
+                "candidate_files": len(candidates),
+                "elapsed_ms": round(elapsed * 1000, 2),
+                "strategy": "weighted-lexical+structure+references+causal-contrast",
+                "index": self._index_refresh.to_dict() if self._index_refresh else None,
+            },
+        )
+
+    def prepare(self) -> dict[str, float | int]:
+        """Build the reusable in-process lexical and structural index."""
+        started = time.perf_counter()
+        files = self._load_files()
+        section_count = 0
+        for source in files:
+            self._terms_for_source(source)
+            self._terms_for_path(source.path)
+            sections = self._sections_for(source)
+            section_count += len(sections)
+            for section in sections:
+                self._terms_for_section(section)
+        return {
+            "source_files": len(files),
+            "sections": section_count,
+            "elapsed_ms": round((time.perf_counter() - started) * 1000, 2),
+        }
+
+    def expand(
+        self,
+        path: str,
+        *,
+        line: int | None = None,
+        symbol: str | None = None,
+        relation: str = "enclosing",
+    ) -> list[Evidence]:
+        if relation not in {"enclosing", "siblings", "references"}:
+            raise ValueError("relation must be enclosing, siblings, or references")
+        source = self.reader.read_file(path)
+        sections = sections_for(source)
+        anchor = containing_section(source, line, sections) if line else _section_named(sections, symbol)
+        if relation == "enclosing":
+            selected = [anchor]
+            reason = "enclosing structural unit"
+        elif relation == "references":
+            name = symbol or anchor.name
+            selected = []
+            for candidate in self._load_files():
+                if candidate.path != path and re.search(rf"\b{re.escape(name)}\b", candidate.content):
+                    selected.append(
+                        containing_section(candidate, _first_line(candidate.content, name), self._sections_for(candidate))
+                    )
+            reason = f"references `{name}`"
+        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]
+        return self._pack(items, 20)
+
+    def _load_files(self) -> list[SourceFile]:
+        if self._files is None:
+            self._index_refresh = self.index.refresh()
+            snapshot = self.index.load()
+            self._files = snapshot.files
+            self._document_terms.update(snapshot.document_terms)
+            self._sections.update(snapshot.sections)
+        return self._files
+
+    def _rank_files(
+        self,
+        task: str,
+        files: list[SourceFile],
+        weighted: dict[str, float],
+        original: list[str],
+    ) -> list[_FileCandidate]:
+        task_lower = task.lower()
+        candidates = []
+        for source in files:
+            terms = self._terms_for_source(source)
+            path_terms = self._terms_for_path(source.path)
+            score = 0.0
+            matches = []
+            for term, weight in weighted.items():
+                content_count = terms.get(term, 0)
+                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))
+            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))
+            if original and original_hits == len(original):
+                score += 8
+            elif original_hits >= 2:
+                score += original_hits
+            if score > 0:
+                candidates.append(_FileCandidate(source, terms, score, matches))
+        return sorted(candidates, key=lambda item: (-item.score, item.source.path))
+
+    def _rank_sections(
+        self,
+        candidates: list[_FileCandidate],
+        weighted: dict[str, float],
+        original: list[str],
+    ) -> list[Evidence]:
+        result = []
+        for file_rank, candidate in enumerate(candidates, 1):
+            ranked = []
+            for section in self._sections_for(candidate.source):
+                terms = self._terms_for_section(section)
+                hits = [(term, terms[term], weight) for term, weight in weighted.items() if terms.get(term)]
+                if not hits:
+                    continue
+                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)
+                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):
+                    window_reasons = reasons if len(focused) == 1 else reasons + [f"focused window {window_rank + 1}"]
+                    ranked.append(_evidence(window, score - window_rank * 0.5, window_reasons))
+            ranked.sort(key=lambda item: (-item.score, item.start_line))
+            representatives = []
+            represented = set()
+            for item in ranked:
+                key = item.path, item.name
+                if key in represented:
+                    continue
+                representatives.append(item)
+                represented.add(key)
+                if len(representatives) == 4:
+                    break
+            result.extend(representatives)
+            if representatives:
+                primary = representatives[0]
+                second_window = next(
+                    (
+                        item for item in ranked
+                        if item.path == primary.path
+                        and item.name == primary.name
+                        and item.key() != primary.key()
+                    ),
+                    None,
+                )
+                if second_window:
+                    result.append(second_window)
+        return result
+
+    def _reference_expansion(
+        self,
+        task: str,
+        files: list[_FileCandidate],
+        sections: list[Evidence],
+        weighted: dict[str, float],
+        original: list[str],
+    ) -> list[Evidence]:
+        query_symbols = set(SYMBOL_RE.findall(task))
+        for item in sections[:8]:
+            query_symbols.update(SYMBOL_RE.findall(item.content))
+        # Prefer task symbols and class names of strong anchors; cap fan-out aggressively.
+        anchor_names = {Path(item.path).stem for item in sections[:8]}
+        symbols = sorted(query_symbols & anchor_names | set(SYMBOL_RE.findall(task)))[:8]
+        if not symbols:
+            return []
+        expanded: list[Evidence] = []
+        seen_paths = {item.path for item in sections[:4]}
+        for symbol in symbols:
+            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):
+                    continue
+                line = _first_line(candidate.source.content, symbol)
+                section = containing_section(candidate.source, line, self._sections_for(candidate.source))
+                terms = document_terms(section.content)
+                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}`"])
+                )
+            references.sort(key=lambda item: (-item.score, item.path))
+            expanded.extend(references[:5])
+        return expanded
+
+    def _structural_expansion(self, task: str, files: list[_FileCandidate]) -> list[Evidence]:
+        intent = set(split_identifier(task))
+        non_schedule_intent = intent - {
+            "scheduled", "schedule", "scheduler", "cron", "trigger",
+            "resolve", "fix", "failure", "error", "exception", "null", "pointer",
+            "nullpointerexception", "npe", "in", "the",
+        }
+        patterns: list[tuple[str, re.Pattern[str]]] = []
+        if intent & {"dependency", "injection", "order", "startup", "initialization"}:
+            patterns.extend(
+                [
+                    ("dependency ordering annotation", re.compile(r"@DependsOn\b")),
+                    ("startup lifecycle hook", re.compile(r"@PostConstruct\b|\bafterPropertiesSet\s*\(")),
+                ]
+            )
+        if intent & {"callback", "event", "events", "listener", "subscriber"}:
+            patterns.extend(
+                [
+                    ("event registration", re.compile(r"\bregister(?:Subscriber|Listener|ToPublisher)\s*\(")),
+                    ("event publication", re.compile(r"\bpublishEvent\s*\(")),
+                ]
+            )
+        if intent & {"scheduled", "schedule", "scheduler", "cron", "trigger"}:
+            patterns.append(
+                (
+                    "scheduled execution entry",
+                    re.compile(
+                        r"@Scheduled\b|\bconfigureTasks\s*\(|\baddTriggerTask\s*\(|"
+                        r"\bscheduleAtFixedRate\s*\("
+                    ),
+                )
+            )
+        if not patterns:
+            return []
+        expanded = []
+        for candidate in files:
+            matches = [(label, pattern.search(candidate.source.content)) for label, pattern in patterns]
+            matches = [(label, match) for label, match in matches if match]
+            if matches and all(label == "scheduled execution entry" for label, _ in matches):
+                if not non_schedule_intent.intersection(candidate.matches):
+                    continue
+            if not matches:
+                continue
+            label, match = matches[0]
+            assert match is not None
+            line = candidate.source.content.count("\n", 0, match.start()) + 1
+            section = containing_section(candidate.source, line, self._sections_for(candidate.source))
+            score = candidate.score * 0.35 + 36 + 8 * len(matches)
+            labels = [matched_label for matched_label, _ in matches]
+            expanded.append(
+                _evidence(
+                    _focused_section(section, {}, line),
+                    score,
+                    labels + [f"obligation: {matched_label}" for matched_label in labels]
+                    + ["task-specific structural pattern"],
+                )
+            )
+        expanded.sort(key=lambda item: (-item.score, item.path))
+        return expanded[:16]
+
+    def _call_expansion(
+        self,
+        files: list[_FileCandidate],
+        evidence: list[Evidence],
+        weighted: dict[str, float],
+    ) -> list[Evidence]:
+        by_path = {candidate.source.path: candidate.source for candidate in files}
+        expanded: list[Evidence] = []
+        anchors = sorted(evidence, key=lambda item: -item.score)[:20]
+        for anchor in anchors:
+            source = by_path.get(anchor.path)
+            if source is None:
+                continue
+            definitions = {section.name: section for section in self._sections_for(source)}
+            calls = re.findall(r"\b([A-Za-z_$][\w$]*)\s*\(", anchor.content)
+            for name in list(dict.fromkeys(calls)):
+                target = definitions.get(name)
+                if target is None or target.start_line == anchor.start_line:
+                    continue
+                terms = document_terms(target.content + " " + target.name)
+                task_signal = sum(weight for term, weight in weighted.items() if terms.get(term))
+                if task_signal <= 0:
+                    continue
+                score = anchor.score * 0.85 + task_signal
+                expanded.append(
+                    _evidence(
+                        _focused_section(target, weighted),
+                        score,
+                        [f"called by `{anchor.name}`", "definition expansion"],
+                    )
+                )
+        expanded.sort(key=lambda item: (-item.score, item.path, item.start_line))
+        return expanded[:20]
+
+    def _sibling_contrast_expansion(
+        self,
+        task: str,
+        files: list[_FileCandidate],
+        weighted: dict[str, float],
+        original: list[str],
+    ) -> list[Evidence]:
+        intent = set(split_identifier(task))
+        if not intent.intersection({"callback", "callbacks"}):
+            return []
+        identity_terms = {
+            term: weighted[term]
+            for term in original
+            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):
+                    continue
+                target_name_terms = set(split_identifier(target.name))
+                target_relevance = _term_signal(target, identity_terms)
+                if target_relevance <= 0:
+                    continue
+                comparisons = []
+                for sibling in sections:
+                    if sibling is target or not publication.search(sibling.content):
+                        continue
+                    sibling_name_terms = set(split_identifier(sibling.name))
+                    common = target_name_terms & sibling_name_terms
+                    if len(common) < 2:
+                        continue
+                    similarity = len(common) / max(1, min(len(target_name_terms), len(sibling_name_terms)))
+                    if similarity < 0.6 or target_relevance <= _term_signal(sibling, identity_terms):
+                        continue
+                    comparisons.append((similarity, sibling))
+                if not comparisons:
+                    continue
+                _, sibling = max(comparisons, key=lambda item: (item[0], -item[1].start_line))
+                base = candidate.score * 0.35 + target_relevance
+                expanded.extend(
+                    [
+                        _evidence(
+                            _focused_section(target, weighted),
+                            base + 72,
+                            [
+                                f"sibling contrast: `{sibling.name}` publishes an event",
+                                "callback path lacks the sibling's event publication",
+                                "obligation: callback completion",
+                            ],
+                        ),
+                        _evidence(
+                            _focused_section(sibling, weighted),
+                            base + 64,
+                            [
+                                f"comparison sibling for `{target.name}`",
+                                "contains event publication",
+                            ],
+                        ),
+                    ]
+                )
+        expanded.sort(key=lambda item: (-item.score, item.path, item.start_line))
+        return expanded[:8]
+
+    def _initialization_order_expansion(
+        self,
+        task: str,
+        files: list[_FileCandidate],
+        weighted: dict[str, float],
+    ) -> list[Evidence]:
+        intent = set(split_identifier(task))
+        if not intent.intersection({"startup", "initialization", "dependency", "order"}):
+            return []
+        if not intent.intersection({"event", "events", "listener", "subscriber", "missed", "missing"}):
+            return []
+
+        task_lower = task.lower()
+        subscribers: dict[str, list[tuple[_FileCandidate, Section]]] = {}
+        for candidate in files:
+            content = candidate.source.content
+            if "registerSubscriber" not in content:
+                continue
+            event_types = re.findall(r"return\s+([A-Z][A-Za-z0-9_$]*)\.class\s*;", content)
+            if not event_types:
+                continue
+            static_registration = next(
+                (
+                    match for match in re.finditer(r"\bregisterSubscriber\s*\(", content)
+                    if _inside_static_initializer(content, match.start())
+                ),
+                None,
+            )
+            if static_registration is None:
+                continue
+            line = content.count("\n", 0, static_registration.start()) + 1
+            section = containing_section(candidate.source, line, self._sections_for(candidate.source))
+            for event_type in event_types:
+                subscribers.setdefault(event_type, []).append((candidate, section))
+
+        expanded: list[Evidence] = []
+        for publisher in files:
+            publisher_name = Path(publisher.source.path).stem
+            if publisher_name.lower() not in task_lower:
+                continue
+            published_events = list(dict.fromkeys(re.findall(
+                r"\bpublishEvent\s*\(\s*new\s+([A-Z][A-Za-z0-9_$]*)\b",
+                publisher.source.content,
+            )))
+            if not published_events:
+                continue
+            constructor = next(
+                (section for section in self._sections_for(publisher.source) if section.name == publisher_name),
+                None,
+            )
+            if constructor is None:
+                continue
+            for event_type in published_events:
+                for subscriber, registration in subscribers.get(event_type, []):
+                    subscriber_name = Path(subscriber.source.path).stem
+                    if subscriber.source.path == publisher.source.path or subscriber_name in constructor.content:
+                        continue
+                    base = publisher.score * 0.35 + _term_signal(constructor, weighted)
+                    expanded.extend(
+                        [
+                            _evidence(
+                                _focused_section(constructor, weighted),
+                                base + 84,
+                                [
+                                    f"publishes `{event_type}` before `{subscriber_name}` is guaranteed initialized",
+                                    f"missing initialization edge to `{subscriber_name}`",
+                                    f"required repair site: initialize `{subscriber_name}` from this component",
+                                    "obligation: initialization responsibility",
+                                ],
+                            ),
+                            _evidence(
+                                _focused_section(registration, weighted),
+                                base + 76,
+                                [
+                                    f"registers the subscriber for `{event_type}`",
+                                    f"initialization counterpart for `{publisher_name}`",
+                                ],
+                            ),
+                        ]
+                    )
+        expanded.sort(key=lambda item: (-item.score, item.path, item.start_line))
+        return expanded[:8]
+
+    def _dependency_order_expansion(
+        self,
+        task: str,
+        files: list[_FileCandidate],
+        weighted: dict[str, float],
+    ) -> list[Evidence]:
+        intent = set(split_identifier(task))
+        if not intent.intersection({"startup", "initialization", "dependency", "order"}):
+            return []
+        task_components = [
+            symbol for symbol in SYMBOL_RE.findall(task)
+            if symbol.endswith(("Notifier", "Listener", "Initializer", "Manager", "Service"))
+        ]
+        if not task_components:
+            return []
+
+        expanded: list[Evidence] = []
+        for candidate in files:
+            content = candidate.source.content
+            annotation = re.search(r"@DependsOn\s*\(([^)]*)\)", content, re.DOTALL)
+            if annotation is None or not re.search(r"@PostConstruct\b|\bafterPropertiesSet\s*\(", content):
+                continue
+            declared = annotation.group(1)
+            for component in task_components:
+                bean_name = component[0].lower() + component[1:]
+                if component in content or bean_name in declared:
+                    continue
+                line = content.count("\n", 0, annotation.start()) + 1
+                section = containing_section(candidate.source, line, self._sections_for(candidate.source))
+                base = candidate.score * 0.35 + _term_signal(section, weighted)
+                expanded.append(
+                    _evidence(
+                        _focused_section(section, weighted, line),
+                        base + 96,
+                        [
+                            f"startup lifecycle has `@DependsOn` but omits `{bean_name}`",
+                            f"missing dependency edge to task component `{component}`",
+                            f"required repair site: add `{bean_name}` to this dependency declaration",
+                            "joint responsibility: order startup work after notifier initialization",
+                            "obligation: startup dependency owner",
+                        ],
+                    )
+                )
+        expanded.sort(key=lambda item: (-item.score, item.path, item.start_line))
+        return expanded[:4]
+
+    def _sections_for(self, source: SourceFile) -> list[Section]:
+        cached = self._sections.get(source.path)
+        if cached is None:
+            cached = sections_for(source)
+            self._sections[source.path] = cached
+        return cached
+
+    def _terms_for_source(self, source: SourceFile) -> Counter[str]:
+        cached = self._document_terms.get(source.path)
+        if cached is None:
+            cached = document_terms(source.content)
+            self._document_terms[source.path] = cached
+        return cached
+
+    def _terms_for_path(self, path: str) -> Counter[str]:
+        cached = self._path_terms.get(path)
+        if cached is None:
+            cached = document_terms(path)
+            self._path_terms[path] = cached
+        return cached
+
+    def _terms_for_section(self, section: Section) -> Counter[str]:
+        key = section.path, section.start_line, section.end_line
+        cached = self._section_terms.get(key)
+        if cached is None:
+            cached = document_terms(section.content + " " + section.name)
+            self._section_terms[key] = cached
+        return cached
+
+    def _pack(self, candidates: list[Evidence], limit: int) -> list[Evidence]:
+        unique: dict[tuple[str, int, int], Evidence] = {}
+        for item in candidates:
+            existing = unique.get(item.key())
+            if existing is None or item.score > existing.score:
+                unique[item.key()] = item
+        ranked = sorted(unique.values(), key=lambda item: (-_packing_score(item), item.path, item.start_line))
+        selected: list[Evidence] = []
+        # Preserve one strong, preferably production, example for every structural
+        # obligation inferred from the task before adding similar hits.
+        obligations: dict[str, list[Evidence]] = {}
+        for item in ranked:
+            for reason in item.reasons:
+                if reason.startswith("obligation: "):
+                    obligations.setdefault(reason, []).append(item)
+        for reason in sorted(obligations):
+            if len(selected) >= limit:
+                break
+            options = sorted(obligations[reason], key=lambda item: (-_packing_score(item), item.path))
+            for item in options:
+                if item not in selected:
+                    selected.append(item)
+                    break
+
+        # Prefer multiple candidate files before adding more results from the same file.
+        diversity_limit = min(4, limit)
+        representatives: dict[str, Evidence] = {}
+        for item in ranked:
+            representatives.setdefault(item.path, item)
+        diverse = sorted(
+            representatives.values(),
+            key=lambda item: (-_packing_score(item), item.path),
+        )
+        for item in diverse:
+            if len(selected) >= diversity_limit:
+                break
+            if item in selected:
+                continue
+            selected.append(item)
+        for item in ranked:
+            if len(selected) >= limit or item in selected:
+                continue
+            selected.append(item)
+        return selected
+
+
+def _packing_score(item: Evidence) -> float:
+    test_penalty = 12 if "/test/" in item.path or item.path.startswith("test/") else 0
+    return item.score - min(item.estimated_tokens, 2000) / 200 - test_penalty
+
+
+def _term_signal(section: Section, weighted: dict[str, float]) -> float:
+    terms = document_terms(section.content + " " + section.name)
+    return sum(weight for term, weight in weighted.items() if terms.get(term))
+
+
+def _inside_static_initializer(content: str, offset: int) -> bool:
+    for match in reversed(list(re.finditer(r"\bstatic\s*\{", content[:offset]))):
+        depth = 0
+        for index in range(match.end() - 1, len(content)):
+            if content[index] == "{":
+                depth += 1
+            elif content[index] == "}":
+                depth -= 1
+                if depth == 0:
+                    return offset < index
+        return True
+    return False
+
+
+def _focused_section(
+    section: Section,
+    weighted: dict[str, float],
+    focus_line: int | None = None,
+    size: int = 48,
+) -> Section:
+    return _focused_sections(section, weighted, focus_line, size, limit=1)[0]
+
+
+def _focused_sections(
+    section: Section,
+    weighted: dict[str, float],
+    focus_line: int | None = None,
+    size: int = 48,
+    limit: int = 2,
+) -> list[Section]:
+    lines = section.content.splitlines()
+    if len(lines) <= size:
+        return [section]
+    if focus_line is not None:
+        focus = max(0, min(len(lines) - 1, focus_line - section.start_line))
+        starts = [max(0, min(focus - size // 2, len(lines) - size))]
+    else:
+        lowered = [line.lower() for line in lines]
+        candidates = list(range(0, len(lines) - size + 1, size // 2))
+        candidates.append(len(lines) - size)
+        scored = []
+        for candidate in dict.fromkeys(candidates):
+            text = "\n".join(lowered[candidate : candidate + size])
+            score = sum(weight * text.count(term) for term, weight in weighted.items())
+            scored.append((score, candidate))
+        starts = []
+        for _, candidate in sorted(scored, key=lambda item: (-item[0], item[1])):
+            if all(abs(candidate - selected) >= size // 2 for selected in starts):
+                starts.append(candidate)
+            if len(starts) == limit:
+                break
+    return [
+        Section(
+            section.path,
+            section.name,
+            f"{section.kind}-window",
+            section.start_line + start,
+            section.start_line + start + size - 1,
+            "\n".join(lines[start : start + size]),
+        )
+        for start in starts
+    ]
+
+
+def _evidence(section: Section, score: float, reasons: list[str]) -> Evidence:
+    return Evidence(
+        path=section.path,
+        start_line=section.start_line,
+        end_line=section.end_line,
+        kind=section.kind,
+        name=section.name,
+        score=round(score, 4),
+        reasons=reasons,
+        content=section.content,
+        estimated_tokens=max(1, (len(section.content) + 3) // 4),
+    )
+
+
+def _section_named(sections: list[Section], symbol: str | None) -> Section:
+    if not sections:
+        raise ValueError("file contains no retrievable sections")
+    if symbol:
+        for section in sections:
+            if section.name == symbol or re.search(rf"\b{re.escape(symbol)}\b", section.content):
+                return section
+        raise ValueError(f"symbol not found: {symbol}")
+    return sections[0]
+
+
+def _first_line(content: str, value: str) -> int:
+    for index, line in enumerate(content.splitlines(), 1):
+        if value in line:
+            return index
+    return 1