SourceIndex 0.1.2__tar.gz → 0.1.4__tar.gz

{sourceindex-0.1.2 → sourceindex-0.1.4}/GETTING_STARTED.md

@@ -10,8 +10,8 @@ weird" — would be hugely helpful to hear. No feedback is too small.
 ## What it is
 
 When you ask a coding agent to fix or build something, it has to find the
-relevant code first. By default Claude Code and opencode do that live, in
-your session. SourceIndex does it ahead of time so the agent jumps straight
+relevant code first. By default Claude Code, opencode, and Codex do that
+live, in your session. SourceIndex does it ahead of time so the agent jumps straight
 to the right files.
 
 **Best on an existing repo you didn't fully write yourself.** Not very useful
@@ -22,8 +22,8 @@ on a brand-new empty project.
 You'll need Python 3.10+ and a SourceIndex API key (starts with `sk-si-`).
 Apply for access at https://sourceindex.dev/access.
 
-**Easiest path:** open this file in Claude Code or opencode and tell it "set
-sourceindex up in this repo." It can run the steps for you.
+**Easiest path:** open this file in Claude Code, opencode, or Codex and tell
+it "set sourceindex up in this repo." It can run the steps for you.
 
 If you'd rather do it by hand:
 
@@ -33,16 +33,18 @@ cd /path/to/your/repo
 sourceindex init             # auto-detects your agent(s)
 sourceindex init claude      # set up Claude Code only
 sourceindex init opencode    # set up opencode only
+sourceindex init codex       # set up Codex only
 ```
 
 It'll prompt for the key, set up some git hooks plus a subagent for the
 coding agent your repo already uses (a `CLAUDE.md` or `.claude/` means
-Claude Code; an `AGENTS.md` or `.opencode/` means opencode; neither means
-Claude Code), and scan your repo. A few minutes, once per repo. You can
-also name both at once (`sourceindex init claude opencode`), and it's safe
-to re-run init later to add the other agent.
-If you don't have a `CLAUDE.md` (Claude Code) or `AGENTS.md` (opencode)
-yet, run `/init` in your agent first.
+Claude Code; a `.opencode/` means opencode; a `.codex/` means Codex; an
+`AGENTS.md` alone means both opencode and Codex; none of those means Claude
+Code), and scan your repo. A few minutes, once per repo. You can also name
+several at once (`sourceindex init claude opencode codex`), and it's safe
+to re-run init later to add another agent.
+If you don't have a `CLAUDE.md` (Claude Code) or `AGENTS.md` (opencode,
+Codex) yet, run `/init` in your agent first.
 
 To replace a rotated or expired key later:
 
@@ -68,8 +70,8 @@ global default.
 
 ## Day-to-day
 
-Nothing. Open the repo in Claude Code or opencode as usual — it'll use
-SourceIndex on its own.
+Nothing. Open the repo in Claude Code, opencode, or Codex as usual — it'll
+use SourceIndex on its own.
 
 ## Feedback I'd love
 

sourceindex-0.1.4/LICENSE

@@ -0,0 +1,115 @@
+SourceIndex — Software License Agreement
+
+Copyright (c) 2026 MANTEON PTE. LTD. (Singapore). All rights reserved.
+
+SourceIndex is commercial software. It is licensed, not sold. By installing,
+copying, or using it you agree to this Agreement. If you do not agree, do not
+install or use it.
+
+1. DEFINITIONS
+
+   "Licensor" means MANTEON PTE. LTD., a company incorporated in the Republic
+   of Singapore. "Software" means the SourceIndex program distributed by the
+   Licensor, in source or object form, together with its documentation.
+   "You" means the individual or entity exercising rights under this
+   Agreement.
+
+2. GRANT OF LICENSE
+
+   Subject to Your compliance with this Agreement, the Licensor grants You a
+   limited, non-exclusive, non-transferable, non-sublicensable, revocable
+   licence to install and use unmodified copies of the Software for Your own
+   internal purposes.
+
+   No other rights are granted. All rights not expressly granted are reserved
+   by the Licensor.
+
+3. RESTRICTIONS
+
+   Except to the extent that this restriction is prohibited by applicable law,
+   or expressly permitted by the Licensor in writing, You may not:
+
+   (a) distribute, publish, sublicense, sell, rent, lease, lend, or otherwise
+       make the Software available to any third party;
+   (b) modify the Software or create derivative works from it;
+   (c) reverse engineer, decompile, or disassemble the Software, or otherwise
+       attempt to derive its source code, methods, or prompts, save to the
+       extent applicable law confers a non-excludable right to do so for
+       interoperability purposes;
+   (d) use the Software, or any information derived from it, to develop,
+       train, or improve a product or service that competes with it;
+   (e) remove, obscure, or alter any copyright, trademark, or other
+       proprietary notice; or
+   (f) circumvent or disable any licensing, metering, or security mechanism.
+
+   The Software is distributed in a human-readable form because it is written
+   in an interpreted language. That fact does not grant any right beyond
+   Clause 2, and does not make the Software open source.
+
+4. OWNERSHIP
+
+   The Software is protected by copyright and other intellectual property
+   laws. The Licensor and its licensors retain all right, title, and interest
+   in and to the Software, including all prompts, templates, indexes, models
+   of operation, and other content contained in it.
+
+5. THIRD-PARTY COMPONENTS
+
+   The Software depends on third-party components distributed under their own
+   licences. Those components are licensed to You by their respective owners
+   under those licences, not under this Agreement, and nothing here limits
+   Your rights under them.
+
+6. HOSTED SERVICES
+
+   The Software may communicate with services operated by the Licensor. Use of
+   those services is governed by separate terms and may require a valid
+   subscription or API credential. The Licensor may modify, suspend, or
+   discontinue those services at any time.
+
+7. NO WARRANTY
+
+   THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF
+   ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED
+   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+   SATISFACTORY QUALITY, AND NON-INFRINGEMENT. THE LICENSOR DOES NOT WARRANT
+   THAT THE SOFTWARE WILL BE UNINTERRUPTED, ERROR-FREE, OR THAT ITS OUTPUT
+   WILL BE ACCURATE OR COMPLETE.
+
+8. LIMITATION OF LIABILITY
+
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR SHALL NOT BE LIABLE
+   FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR EXEMPLARY
+   DAMAGES, OR FOR ANY LOSS OF PROFITS, REVENUE, DATA, OR GOODWILL, ARISING
+   OUT OF OR IN CONNECTION WITH THE SOFTWARE, EVEN IF ADVISED OF THE
+   POSSIBILITY OF SUCH DAMAGES.
+
+   THE LICENSOR'S TOTAL AGGREGATE LIABILITY ARISING OUT OF OR IN CONNECTION
+   WITH THIS AGREEMENT SHALL NOT EXCEED THE GREATER OF (a) THE AMOUNTS PAID BY
+   YOU TO THE LICENSOR FOR THE SOFTWARE IN THE TWELVE MONTHS PRECEDING THE
+   CLAIM, OR (b) ONE HUNDRED SINGAPORE DOLLARS (SGD 100).
+
+   Nothing in this Agreement excludes or limits liability that cannot lawfully
+   be excluded or limited, including liability for death or personal injury
+   caused by negligence, or for fraud or fraudulent misrepresentation.
+
+9. TERMINATION
+
+   This licence terminates automatically if You breach any term of it. On
+   termination You must cease all use of the Software and destroy all copies
+   in Your possession. Clauses 4, 7, 8, and 10 survive termination.
+
+10. GOVERNING LAW AND JURISDICTION
+
+    This Agreement is governed by the laws of the Republic of Singapore,
+    without regard to its conflict of laws rules. The courts of Singapore
+    have exclusive jurisdiction over any dispute arising out of or in
+    connection with it.
+
+11. ENTIRE AGREEMENT
+
+    This Agreement is the entire agreement between You and the Licensor
+    regarding the Software, and supersedes any prior understanding. If any
+    provision is held unenforceable, the remainder stays in effect.
+
+For licensing enquiries, contact MANTEON PTE. LTD.

{sourceindex-0.1.2 → sourceindex-0.1.4}/PKG-INFO

@@ -1,7 +1,14 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: SourceIndex
-Version: 0.1.2
+Version: 0.1.4
 Summary: Codebase index for agentic coding
+Author: MANTEON PTE. LTD.
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.10
 Requires-Dist: cryptography>=42
 Requires-Dist: keyring>=24
@@ -16,6 +23,9 @@ Requires-Dist: tree-sitter-ruby>=0.23
 Requires-Dist: tree-sitter-rust>=0.23
 Requires-Dist: tree-sitter-typescript>=0.23
 Requires-Dist: tree-sitter>=0.23
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: tomli; (python_version < '3.11') and extra == 'test'
 Description-Content-Type: text/markdown
 
 # Getting Started with SourceIndex
@@ -30,8 +40,8 @@ weird" — would be hugely helpful to hear. No feedback is too small.
 ## What it is
 
 When you ask a coding agent to fix or build something, it has to find the
-relevant code first. By default Claude Code and opencode do that live, in
-your session. SourceIndex does it ahead of time so the agent jumps straight
+relevant code first. By default Claude Code, opencode, and Codex do that
+live, in your session. SourceIndex does it ahead of time so the agent jumps straight
 to the right files.
 
 **Best on an existing repo you didn't fully write yourself.** Not very useful
@@ -42,8 +52,8 @@ on a brand-new empty project.
 You'll need Python 3.10+ and a SourceIndex API key (starts with `sk-si-`).
 Apply for access at https://sourceindex.dev/access.
 
-**Easiest path:** open this file in Claude Code or opencode and tell it "set
-sourceindex up in this repo." It can run the steps for you.
+**Easiest path:** open this file in Claude Code, opencode, or Codex and tell
+it "set sourceindex up in this repo." It can run the steps for you.
 
 If you'd rather do it by hand:
 
@@ -53,16 +63,18 @@ cd /path/to/your/repo
 sourceindex init             # auto-detects your agent(s)
 sourceindex init claude      # set up Claude Code only
 sourceindex init opencode    # set up opencode only
+sourceindex init codex       # set up Codex only
 ```
 
 It'll prompt for the key, set up some git hooks plus a subagent for the
 coding agent your repo already uses (a `CLAUDE.md` or `.claude/` means
-Claude Code; an `AGENTS.md` or `.opencode/` means opencode; neither means
-Claude Code), and scan your repo. A few minutes, once per repo. You can
-also name both at once (`sourceindex init claude opencode`), and it's safe
-to re-run init later to add the other agent.
-If you don't have a `CLAUDE.md` (Claude Code) or `AGENTS.md` (opencode)
-yet, run `/init` in your agent first.
+Claude Code; a `.opencode/` means opencode; a `.codex/` means Codex; an
+`AGENTS.md` alone means both opencode and Codex; none of those means Claude
+Code), and scan your repo. A few minutes, once per repo. You can also name
+several at once (`sourceindex init claude opencode codex`), and it's safe
+to re-run init later to add another agent.
+If you don't have a `CLAUDE.md` (Claude Code) or `AGENTS.md` (opencode,
+Codex) yet, run `/init` in your agent first.
 
 To replace a rotated or expired key later:
 
@@ -88,8 +100,8 @@ global default.
 
 ## Day-to-day
 
-Nothing. Open the repo in Claude Code or opencode as usual — it'll use
-SourceIndex on its own.
+Nothing. Open the repo in Claude Code, opencode, or Codex as usual — it'll
+use SourceIndex on its own.
 
 ## Feedback I'd love
 

{sourceindex-0.1.2 → sourceindex-0.1.4}/pyproject.toml

@@ -4,10 +4,25 @@ build-backend = "hatchling.build"
 
 [project]
 name = "SourceIndex"
-version = "0.1.2"
+version = "0.1.4"
 description = "Codebase index for agentic coding"
 readme = "GETTING_STARTED.md"
 requires-python = ">=3.10"
+authors = [{ name = "MANTEON PTE. LTD." }]
+# Proprietary: the published wheel ships readable .py because Python is
+# interpreted, not because the source is licensed for reuse. LicenseRef-* is
+# how PEP 639 spells a licence with no SPDX identifier.
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+# No "License ::" classifier: PEP 639 deprecates them, and pairing one with
+# License-Expression is the case where tools are permitted to reject the
+# upload. The expression above is the authoritative declaration.
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
 dependencies = [
     "litellm>=1.50",
     "tree-sitter>=0.23",
@@ -32,6 +47,13 @@ dependencies = [
     "tree-sitter-typescript>=0.23",
 ]
 
+[project.optional-dependencies]
+test = [
+    "pytest",
+    # tomllib backport for the TOML-validity tests on the 3.10 floor.
+    "tomli; python_version < '3.11'",
+]
+
 [project.scripts]
 sourceindex = "sourceindex.cli:main"
 
@@ -46,4 +68,5 @@ include = [
     "sourceindex/",
     "pyproject.toml",
     "GETTING_STARTED.md",
+    "LICENSE",
 ]

{sourceindex-0.1.2 → sourceindex-0.1.4}/sourceindex/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 
 # Surfaced at the top level so the CLI's argparse setup can use it for
 # --workers help/default without importing the build pipeline (which

sourceindex-0.1.4/sourceindex/build/linerange/anchor.py

@@ -0,0 +1,220 @@
+"""Anchor tier-2 entries to parser truth, name-first.
+
+Shared by the python-ast and tree-sitter fixers. This is a PERMANENT
+build-pipeline stage (every ``init`` runs it right after the LLM responds),
+not a repair utility — LLM-emitted line numbers are unreliable for every
+builder model, and this stage is the deterministic guarantee that cached
+ranges are parser truth whenever the symbol exists. On perfect LLM output
+it is a no-op.
+
+The original fixers were format-first: a strict regex had to recognize the
+whole entry line (canonical ``name (Lstart-Lend): desc``) before any range
+correction happened. Models that drift off-format — Gemma emits ``(23:18)``
+colon ranges ~6% of the time and Go receiver names like ``(b *Backend).foo``
+— silently bypassed the fixer, which is how thousands of reversed/truncated
+ranges survived into built caches.
+
+This module inverts the order into two parts:
+
+1. The language backend supplies parser truth: ``{qualified_name: [(s, e), …]}``
+   (lists, because the same name can legitimately define several ranges).
+2. Each entry line is matched by NAME, and its range is converged to truth:
+   - any recognizable range token (dash, colon, en-dash, missing ``L``,
+     reversed, single-line) is REPLACED with the truth range;
+   - a matched name with no range token at all gets the truth range INSERTED;
+   - a name absent from truth whose range is clearly broken (reversed,
+     ``L1-L1`` placeholder, or missing) is SNAPPED to its innermost existing
+     container's range (e.g. a @dataclass-generated ``__init__`` → the class);
+   - otherwise the line is left untouched — never dropped, so a well-formed
+     range for something the parser can't see (module constants, generated
+     members) keeps the LLM's answer.
+
+Multiple definitions sharing a name: qualified keys are preferred over bare
+ones by ``_lookup``; among remaining candidates we pick the one whose start is
+closest to the LLM's reported start, falling back to the first definition in
+file order when the entry carried no usable range.
+"""
+from __future__ import annotations
+
+import re
+from typing import Callable, Dict, List, Optional, Tuple
+
+Range = Tuple[int, int]
+Truth = Dict[str, List[Range]]
+Resolver = Callable[[str, Optional[int], bool], Optional[Range]]
+
+# Any parenthesized line token: (L12-L40) (12-40) (23:18) (L12:L40) (L12) (12)
+# plus en/em-dash and tilde separators seen in off-format LLM output.
+_RANGE_TOKEN = re.compile(
+    r"\(\s*L?(?P<s>\d+)\s*(?:(?P<sep>[-:–—~])\s*L?(?P<e>\d+))?\s*\)"
+)
+
+_BARE_ID = re.compile(r"^[A-Za-z_$~][\w$]*$")
+
+# Leading tokens the LLM sometimes folds into the name ("func Foo", "pub fn bar").
+_NAME_KEYWORDS = {
+    "func", "fn", "def", "function", "method", "class", "interface", "type",
+    "struct", "enum", "trait", "impl", "pub", "static", "async", "export",
+    "const", "var", "let", "val", "public", "private", "protected", "abstract",
+    "override", "suspend", "inline", "internal", "final", "new", "get", "set",
+}
+
+_TRAILING_SUFFIXES = (
+    ".get", ".set", ".<init>", ".init", ".constructor", ".ctor",
+    ".closure", ".lambda", ".function_",
+)
+
+_RECEIVER_RE = re.compile(r"^\([^)]*\)\s*\.")  # Go receiver: (b *Backend).foo
+
+
+def normalize_name(qn: str) -> str:
+    """Normalize separators to ``.``, drop receiver parens / keyword prefixes /
+    accessor suffixes, so lookup keys converge across LLM naming styles."""
+    qn = qn.strip()
+    qn = _RECEIVER_RE.sub("", qn)  # "(b *Backend).foo" -> "foo"
+    qn = qn.replace("::", ".").replace("#", ".")
+    if " " in qn:
+        qn = qn.split()[-1]
+    while qn.endswith(_TRAILING_SUFFIXES):
+        for suf in _TRAILING_SUFFIXES:
+            if qn.endswith(suf):
+                qn = qn[: -len(suf)]
+                break
+    while ".." in qn:
+        qn = qn.replace("..", ".")
+    return qn.strip(".")
+
+
+def _bare_tail(name: str) -> str:
+    tail = normalize_name(name).rsplit(".", 1)[-1]
+    return re.sub(r"<.*>$", "", tail)  # strip generics: Foo<T> -> Foo
+
+
+def _plausible_name(name: str) -> bool:
+    """Loose gate for heads that sit directly in front of a range token."""
+    name = name.strip()
+    if not name or len(name) > 160 or "/" in name or "`" in name:
+        return False
+    if " " in name and not _RECEIVER_RE.match(name):
+        toks = name.split()
+        if not all(t.lower() in _NAME_KEYWORDS for t in toks[:-1]):
+            return False
+    return bool(_BARE_ID.match(_bare_tail(name)))
+
+
+def _strict_name(name: str) -> bool:
+    """Tight gate for the no-range insertion path (highest prose risk)."""
+    name = name.strip()
+    if not name or " " in name and not _RECEIVER_RE.match(name):
+        return False
+    if name[0] in "#-*>|":
+        return False
+    return _plausible_name(name)
+
+
+def _lookup(truth: Truth, qn: str) -> List[Range]:
+    """Qualified match first; peel leading segments; finally bare name."""
+    norm = normalize_name(qn)
+    if not norm:
+        return []
+    if norm in truth:
+        return truth[norm]
+    parts = norm.split(".")
+    # Peel LLM-invented leading prefixes (mypkg.Foo.bar -> Foo.bar), but only
+    # accept still-qualified suffixes here — the bare tail is gated below.
+    for i in range(1, len(parts)):
+        suffix = ".".join(parts[i:])
+        if "." in suffix and suffix in truth:
+            return truth[suffix]
+    # Bare-name fallback — but NOT when the entry's own container exists in
+    # truth: then this member genuinely isn't defined there (generated or
+    # hallucinated), and borrowing a same-named member of another container
+    # would mis-anchor it (Dataclass.__init__ -> SomeOtherClass.__init__).
+    for i in range(len(parts) - 1):
+        container = ".".join(parts[i:-1])
+        if container and container in truth:
+            return []
+    return truth.get(_bare_tail(qn), [])
+
+
+def make_resolver(truth: Truth) -> Resolver:
+    """Build a ``resolve(name, reported_start, allow_container)`` over truth.
+
+    ``allow_container=True`` additionally tries the name's enclosing scopes
+    (``A.B.c`` → ``A.B`` → ``A``) — used only when the entry's own range is
+    already known to be broken, so a fabricated member at least points the
+    agent at the right class body.
+    """
+
+    def resolve(name: str, reported_start: Optional[int] = None,
+                allow_container: bool = False) -> Optional[Range]:
+        cands = _lookup(truth, name)
+        if not cands and allow_container:
+            parent = normalize_name(name)
+            while "." in parent and not cands:
+                parent = parent.rsplit(".", 1)[0]
+                cands = truth.get(parent, [])
+        if not cands:
+            return None
+        if len(cands) > 1 and reported_start is not None:
+            return min(cands, key=lambda c: abs(c[0] - reported_start))
+        return cands[0]
+
+    return resolve
+
+
+def _is_broken(s: int, e: Optional[int]) -> bool:
+    if e is None:          # single-line token: not broken, but improvable
+        return False
+    return e < s or (s == 1 and e == 1)
+
+
+def anchor_entries(functions_text: str, resolve: Resolver) -> str:
+    """Apply the name-first convergence rules line by line (never drops a line)."""
+    out: List[str] = []
+    for line in functions_text.splitlines():
+        out.append(_anchor_line(line, resolve))
+    joined = "\n".join(out)
+    if functions_text.endswith("\n") and not joined.endswith("\n"):
+        joined += "\n"
+    return joined
+
+
+def _anchor_line(line: str, resolve: Resolver) -> str:
+    m = _RANGE_TOKEN.search(line)
+    if m:
+        head = line[: m.start()].rstrip()
+        after = line[m.end():]
+        # Real entries read "name (range): desc" — require the colon.
+        if head and re.match(r"\s*:", after) and _plausible_name(head.strip()):
+            s = int(m.group("s"))
+            e = int(m.group("e")) if m.group("e") else None
+            best = resolve(head.strip(), s, False)
+            if best is None:
+                # Name unknown to the parser: snap to the enclosing container
+                # when the range is clearly broken OR points outside it.
+                cont = resolve(head.strip(), s, True)
+                if cont is not None and (
+                    _is_broken(s, e) or not (cont[0] <= s <= cont[1])
+                ):
+                    best = cont
+            if best is None:
+                # No truth to converge to — still canonicalize the token so
+                # downstream dash-only parsers (search pass, compliance) see it.
+                lo, hi = (s, e if e is not None else s)
+                if hi < lo:
+                    lo, hi = hi, lo
+                best = (lo, hi)
+            return f"{head} (L{best[0]}-L{best[1]}){after}"
+        # fall through: token may live in the description of a range-less entry
+
+    head, sep, rest = line.partition(":")
+    if not sep:
+        return line
+    name = head.strip()
+    if not _strict_name(name):
+        return line
+    best = resolve(name, None, False) or resolve(name, None, True)
+    if best is None:
+        return line
+    return f"{head.rstrip()} (L{best[0]}-L{best[1]}):{rest}"

{sourceindex-0.1.2 → sourceindex-0.1.4}/sourceindex/build/linerange/python_ast.py

@@ -8,28 +8,38 @@ whenever the qualified name matches. Description quality is unchanged.
 import ast
 import re
 
+from .anchor import Truth, make_resolver, anchor_entries
+
 
 _LINE_RANGE_RE = re.compile(r"\(L?\d+\s*-\s*L?\d+\)")
 _ENTRY_RE = re.compile(r"^([\w.:_<>]+)\s+\(L?\d+\s*-\s*L?\d+\)\s*:?")
 
 
-def _python_ast_truth(source: str) -> dict[str, tuple[int, int]]:
-    """{qualified_name: (start_lineno, end_lineno)} for every def in source.
+def _python_ast_truth(source: str) -> Truth:
+    """{qualified_name: [(start_lineno, end_lineno), …]} for every def in source.
 
     Methods qualified as Class.method, nested funcs as Outer.inner AND
-    Outer.<locals>.inner so either naming convention matches."""
+    Outer.<locals>.inner so either naming convention matches. A bare-name
+    fallback key (last segment) is also populated so entries that drop the
+    class prefix still resolve; the resolver prefers qualified keys."""
     try:
         tree = ast.parse(source)
     except (SyntaxError, ValueError):
         return {}
 
-    out: dict[str, tuple[int, int]] = {}
+    out: Truth = {}
+
+    def add(key: str, rng: tuple[int, int]) -> None:
+        out.setdefault(key, []).append(rng)
 
     def walk(node, prefix: str = ""):
         for child in ast.iter_child_nodes(node):
             if isinstance(child, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
                 qname = f"{prefix}{child.name}" if prefix else child.name
-                out[qname] = (child.lineno, child.end_lineno or child.lineno)
+                rng = (child.lineno, child.end_lineno or child.lineno)
+                add(qname, rng)
+                if "." in qname:
+                    add(child.name, rng)
                 walk(child, prefix=f"{qname}.")
                 if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
                     walk(child, prefix=f"{qname}.<locals>.")
@@ -39,38 +49,16 @@ def _python_ast_truth(source: str) -> dict[str, tuple[int, int]]:
 
 
 def fix_python_line_ranges(source: str, functions_text: str) -> str:
-    """Replace LLM-emitted line ranges with AST ground truth for Python files.
+    """Converge LLM-emitted line ranges to AST ground truth for Python files.
 
-    Lines whose qualified name matches an AST def get their (Lstart-Lend)
-    rewritten to the real range. Unmatched names (likely hallucinations or
-    deeply nested helpers AST didn't enumerate) are left untouched — kept
-    so a downstream judge can flag them, not silently dropped."""
+    Name-first (see ``anchor``): entries are matched by qualified name and
+    their range replaced/inserted/snapped regardless of the LLM's range
+    formatting. Names AST can't see with a well-formed range are left
+    untouched — kept, never dropped."""
     truth = _python_ast_truth(source)
     if not truth:
         return functions_text
-
-    out_lines: list[str] = []
-    for line in functions_text.splitlines():
-        m = _ENTRY_RE.match(line.strip())
-        if not m:
-            out_lines.append(line)
-            continue
-        qname = m.group(1).rstrip(".")
-        match_key = qname if qname in truth else None
-        if match_key is None:
-            for k in truth:
-                if k.endswith(qname) or qname.endswith(k):
-                    match_key = k
-                    break
-        if match_key is None:
-            out_lines.append(line)
-            continue
-        ls, le = truth[match_key]
-        new_line = _LINE_RANGE_RE.sub(f"(L{ls}-L{le})", line, count=1)
-        if match_key != qname:
-            new_line = new_line.replace(qname, match_key, 1)
-        out_lines.append(new_line)
-    return "\n".join(out_lines)
+    return anchor_entries(functions_text, make_resolver(truth))
 
 
 def fill_missing_python_classes(source: str, functions_text: str) -> str: