cli: _LAZY_COMMANDS duplicates the tool.yaml registry, and 14/18 descriptions already disagree
- Dominant language
- Python
- Stars
- 1
- Forks
- 0
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 40
Description
Found during the adversarial review of #303. Not fixed there because the obvious fix is wrong (see below) — this needs a design decision.
## The duplication
`_LAZY_COMMANDS` in `hvantk/hvantk.py` stores, for each of the 18 top-level commands, a `(module, function, short help)` triple. The repo already stores exactly that: 21 `hvantk/tools/**/*.tool.yaml` manifests, each with `name`, `cli.module`, `cli.function`, `description` — read by `hvantk/core/tool/loader.py` **without importing any CLI module**.
## They have already diverged
Measured on the branch:
```
module + function agree: 18/18
description DIFFERS: 14/18
```
So `hvantk --help` and `hvantk tools list` describe the same command differently today. Examples:
| command | `hvantk --help` | `hvantk tools list` |
| --- | --- | --- |
| `ancestry-inference` | Infer genetic ancestry using PCA and Random Forest classification. | Infer ancestry labels for a query cohort from a labeled reference MT. |
| `psroc` | PSROC: Prediction Score ROC Analysis | Per-gene-set ROC evaluation of dbNSFP predictors against ClinVar. |
| `ptm` | Post-translational modification variant classification commands. | Post-translational modification variant classification pipeline. |
`test_lazy_command_registry_matches_real_commands` (added in #303) compares the dict against the click docstring, **not** against the manifest, so all 14 divergences pass CI.
## Why the obvious fix is wrong
Routing `--help` through `ToolRegistry.get_registry()` costs ~0.13 s of `import yaml, jsonschema` plus 21 YAML parses and schema validations. Startup is currently ~0.10 s, so that would eat most of what #303 bought.
## Options
1. **Generate `_LAZY_COMMANDS` from the manifests at build time** — single source of truth, zero runtime cost, adds a codegen step.
2. **Assert equality in the test suite** — cheapest; import cost is free in tests. Extend `test_tool_smoke.py` (it already holds the registry) to assert `(spec.cli_module, spec.cli_callable, spec.description)` matches the dict entry. Does not remove the duplication but makes divergence impossible to merge.
3. **Make the manifest description authoritative** and drop it from the dict, keeping only `(module, function)` — halves the duplication and fixes the user-facing inconsistency directly.
Option 2 is the smallest step that stops the bleeding; 1 or 3 actually removes the duplication.
Whatever is chosen, the 14 existing description divergences should be reconciled — right now the two surfaces disagree and neither is obviously canonical.
Contributor guide
Research direction
Start with _LAZY_COMMANDS in hvantk/hvantk.py, then read hvantk/core/tool/loader.py and the existing test_lazy_command_registry_matches_real_commands in test_tool_smoke.py. Compare the registry entries with the tool.yaml manifests and evaluate the three listed options. Done means a decided source-of-truth approach, reconciled descriptions, and coverage preventing future divergence.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, tooling
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100