bigbio / bigbio/hvantk

cli: _LAZY_COMMANDS duplicates the tool.yaml registry, and 14/18 descriptions already disagree

Open
#304 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.