Add a function and cli command to find symbol definition by query

* bdx/binary.py (Definition): New class.
(find_symbol_definition): New function.
* bdx/cli.py (find_definition): New function.
* tests/test_cli.py (test_cli_find_definition): New test.

Author: mkcms

bdx/binary.py

@@ -476,6 +476,55 @@ def is_readable_elf_file(path: Path) -> bool:
         return False
 
 
+@dataclass(frozen=True)
+class Definition:
+    """Contains the location where a Symbol is defined."""
+
+    source: Path
+    line: int
+
+
+def find_symbol_definition(symbol: Symbol) -> Optional[Definition]:
+    """Attempt to find the definition of `symbol`.
+
+    This uses the addr2line program to find it.
+    """
+    try:
+        out = subprocess.check_output(
+            [
+                "addr2line",
+                "-i",
+                "-f",
+                "-j",
+                symbol.section,
+                "-e",
+                symbol.path,
+                hex(symbol.address),
+            ]
+        ).decode()
+    except Exception as e:
+        debug("Failed to run addr2line program on {}:", symbol.name, str(e))
+        return None
+
+    lines = out.splitlines()
+    try:
+        pos = lines.index(symbol.name)
+    except ValueError:
+        trace("Symbol not found in addr2line output: {}", symbol)
+        return None
+
+    value = lines[pos + 1]
+
+    match = re.match("(.*):([0-9]+)(.*discriminator.*)?$", value)
+    if not match:
+        debug("Unexpected output of addr2line detected")
+        return None
+
+    file, line, _ = match.groups()
+
+    return Definition(Path(file), int(line))
+
+
 @dataclass(frozen=True)
 class Exclusion:
     """Represents a glob pattern for excluding files to index."""

bdx/cli.py

@@ -16,7 +16,12 @@
 
 import bdx
 from bdx import debug, error, info, log, make_progress_bar, trace
-from bdx.binary import BinaryDirectory, Exclusion, find_compilation_database
+from bdx.binary import (
+    BinaryDirectory,
+    Exclusion,
+    find_compilation_database,
+    find_symbol_definition,
+)
 from bdx.index import (
     IndexingOptions,
     PathField,
@@ -652,6 +657,54 @@ def disass(
         subprocess.check_call(cmd, shell=True)
 
 
+@cli.command()
+@_common_options(index_must_exist=True)
+@click.argument(
+    "query",
+    nargs=-1,
+    shell_complete=_complete_query,
+)
+@click.option(
+    "-n",
+    "--num",
+    help="Limit the number of results",
+    type=click.IntRange(1),
+    metavar="LIMIT",
+    default=None,
+)
+def find_definition(_directory, index_path, query, num):
+    """Find definition of symbols matching some query."""
+    fmt = "{file}:{line}: {name}"
+
+    results = search_index(
+        index_path=index_path, query=" ".join(query), limit=num
+    )
+
+    while True:
+        try:
+            res = next(results)
+        except QueryParser.Error as e:
+            error(f"Invalid query: {str(e)}")
+            exit(1)
+        except StopIteration:
+            break
+
+        if res.symbol_outdated:
+            error("Information outdated, re-index needed")
+
+        defn = find_symbol_definition(res.symbol)
+        debug("Found definition: {}", defn)
+
+        if defn:
+            click.echo(
+                fmt.format(
+                    file=defn.source,
+                    line=defn.line,
+                    name=res.symbol.name,
+                )
+            )
+
+
 @cli.command()
 @_common_options(index_must_exist=True)
 def files(_directory, index_path):

tests/test_cli.py

@@ -214,6 +214,21 @@ def mock_check_call(*args, **kwargs):
     assert re.search("push[ ]+%rbp", output)
 
 
+def test_cli_find_definition(monkeypatch, fixture_path, index_path):
+    runner = CliRunner()
+    result = index_directory(runner, fixture_path, index_path)
+    assert result.exit_code == 0
+
+    result = runner.invoke(
+        cli,
+        ["find-definition", "--index-path", str(index_path), "fullname:main"],
+    )
+
+    assert result.exit_code == 0
+
+    assert result.stdout.strip() == f"/src/tests/fixture/toplev.c:7: main"
+
+
 def test_cli_file_list(fixture_path, index_path):
     runner = CliRunner()
     result = index_directory(runner, fixture_path, index_path)