Unify apply-back path into disassembler_path

Merge commit()/regenerate()'s ida_path and ghidra_path into a single
disassembler_path, dispatched via the Disassembler backend recorded in
the .quokka file. Rename the quokka-apply --ghidra-path option to
--disassembler-path accordingly. Addresses PR #120 review feedback.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: DarkaMaul

bindings/python/quokka/__main__.py

@@ -389,10 +389,11 @@ def main(
     help="IDA .i64 database or Ghidra .gpr/project directory to modify",
 )
 @click.option(
-    "--ghidra-path",
+    "--disassembler-path",
     type=click.Path(exists=True),
     default=None,
-    help="Ghidra installation directory (overrides GHIDRA_INSTALL_DIR)",
+    help="Disassembler installation path (IDA install dir or Ghidra "
+    "install dir, depending on the backend recorded in the .quokka file)",
 )
 @click.option("--overwrite", is_flag=True, default=False, help="Allow overwriting an existing disassembler database")
 @click.option("-v", "--verbose", count=True, help="Increase logging verbosity")
@@ -401,7 +402,7 @@ def main(
 def apply_changes(
     action: str,
     database_file: str | None,
-    ghidra_path: str | None,
+    disassembler_path: str | None,
     overwrite: bool,
     verbose: int,
     quokka_file: str,
@@ -429,7 +430,7 @@ def apply_changes(
         try:
             errors = program.commit(
                 database_file=database_file,
-                ghidra_path=ghidra_path,
+                disassembler_path=disassembler_path,
                 overwrite=overwrite,
             )
         except FileExistsError as e:
@@ -444,7 +445,7 @@ def apply_changes(
         try:
             new_program = program.regenerate(
                 database_file=database_file,
-                ghidra_path=ghidra_path,
+                disassembler_path=disassembler_path,
                 overwrite=overwrite,
             )
             logging.info(f"Regenerated: {new_program.export_file}")

bindings/python/quokka/program.py

@@ -1353,19 +1353,23 @@ def _commit_edits_ghidra(
     def commit(
         self,
         database_file: "Path|str|None" = None,
-        ida_path: "Path|str|None" = None,
-        ghidra_path: "Path|str|None" = None,
+        disassembler_path: "Path|str|None" = None,
         overwrite: bool = True,
         timeout: int = 600,
     ) -> int:
         """Write the .quokka and apply edits to the disassembler database.
 
+        The target disassembler is determined by the backend recorded in the
+        ``.quokka`` file (``self.disassembler``): edits are always applied with
+        the same disassembler that produced the export.
+
         Arguments:
             database_file: Path to the disassembler database.  For IDA this is
                 an ``.i64`` database.  For Ghidra this is either a ``.gpr`` file
                 or a directory that contains/should contain a Ghidra project.
-            ida_path: Optional IDA installation path (IDA only).
-            ghidra_path: Optional Ghidra installation path (Ghidra only).
+            disassembler_path: Optional installation path for the disassembler
+                selected by ``self.disassembler`` (the IDA install dir for an
+                IDA export, the Ghidra install dir for a Ghidra export).
             overwrite: Allow modifying an existing database.
             timeout: Disassembler timeout in seconds.
 
@@ -1383,14 +1387,14 @@ def commit(
                     database_file = str(self.executable.exec_file) + ".i64"
                 return self._commit_edits_ida(
                     database_file,
-                    ida_path=ida_path,
+                    ida_path=disassembler_path,
                     overwrite=overwrite,
                     timeout=timeout,
                 )
             case Disassembler.GHIDRA:
                 return self._commit_edits_ghidra(
                     database_file,
-                    ghidra_path=ghidra_path,
+                    ghidra_path=disassembler_path,
                     overwrite=overwrite,
                     timeout=timeout,
                 )
@@ -1403,8 +1407,7 @@ def commit(
     def regenerate(
         self,
         database_file: "Path|str|None" = None,
-        ida_path: "Path|str|None" = None,
-        ghidra_path: "Path|str|None" = None,
+        disassembler_path: "Path|str|None" = None,
         overwrite: bool = True,
         timeout: int = 600,
     ) -> 'Program':
@@ -1415,8 +1418,8 @@ def regenerate(
 
         Arguments:
             database_file: Path to the disassembler database/project.
-            ida_path: Optional IDA installation path.
-            ghidra_path: Optional Ghidra installation path.
+            disassembler_path: Optional installation path for the disassembler
+                selected by ``self.disassembler``.
             overwrite: Allow modifying an existing database.
             timeout: IDA timeout in seconds.
 
@@ -1428,8 +1431,7 @@ def regenerate(
         """
         errors = self.commit(
             database_file=database_file,
-            ida_path=ida_path,
-            ghidra_path=ghidra_path,
+            disassembler_path=disassembler_path,
             overwrite=overwrite,
             timeout=timeout,
         )

docs/write_feature.md

@@ -92,8 +92,7 @@ errors = prog.commit(database_file="binary_ghidra/binary.gpr", overwrite=True)
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `database_file` | `Path\|str\|None` | backend default | IDA `.i64` database, Ghidra `.gpr` file, or Ghidra project directory |
-| `ida_path` | `Path\|str\|None` | `None` | IDA installation directory (auto-detected if omitted) |
-| `ghidra_path` | `Path\|str\|None` | `None` | Ghidra installation directory (or `GHIDRA_INSTALL_DIR`) |
+| `disassembler_path` | `Path\|str\|None` | `None` | Installation directory of the disassembler recorded in the `.quokka` file (IDA install dir, or Ghidra install dir / `GHIDRA_INSTALL_DIR`) |
 | `overwrite` | `bool` | `True` | Allow modifying an existing database/project. Raises `FileExistsError` when `False` and it exists. Logs a warning when `True`. |
 | `timeout` | `int` | `600` | Maximum seconds to wait for the disassembler |
 
@@ -144,15 +143,15 @@ disassembler database/project without writing Python code:
 ```commandline
 $ quokka-apply binary.quokka binary --overwrite
 $ quokka-apply binary.quokka binary --regenerate --overwrite
-$ quokka-apply binary.quokka binary --database-file binary_ghidra/binary.gpr --ghidra-path "$GHIDRA_INSTALL_DIR" --overwrite
+$ quokka-apply binary.quokka binary --database-file binary_ghidra/binary.gpr --disassembler-path "$GHIDRA_INSTALL_DIR" --overwrite
 ```
 
 | Option | Description |
 |--------|-------------|
 | `--commit` | Write `.quokka` and apply edits to the disassembler (default) |
 | `--regenerate` | Commit then re-export a fresh `.quokka` from the disassembler |
 | `--database-file` | IDA `.i64` database or Ghidra `.gpr`/project directory |
-| `--ghidra-path` | Ghidra installation directory |
+| `--disassembler-path` | Disassembler installation directory (IDA or Ghidra, per the backend recorded in the `.quokka`) |
 | `--overwrite` | Allow overwriting an existing disassembler database |
 | `-v`, `--verbose` | Increase logging verbosity |
 

tests/python/tests/offline/test_commit_regenerate.py

@@ -190,7 +190,7 @@ def test_commit_ghidra_calls_apply_back(self):
 
         assert prog.commit(
             database_file="/tmp/proj.gpr",
-            ghidra_path="/opt/ghidra",
+            disassembler_path="/opt/ghidra",
             overwrite=True,
             timeout=42,
         ) == 0