feat(cli): describe sub-command #2650

ss2165 · 2025-10-29T11:52:40Z

Closes #2603

See base PR for more context: #2639

The describe CLI command loads the package with a description and:

If successful prints the description as tables to output
If error prints partial description to output and error to stderror
If --json flag is passed outputs as json instead, for use with other tools

Help

Summary

JSON (nushell render)

codecov · 2025-10-29T11:59:48Z

Codecov Report

❌ Patch coverage is 85.00000% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.40%. Comparing base (349dd61) to head (e555db5).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
hugr-cli/src/describe.rs	84.87%	5 Missing and 13 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2650      +/-   ##
==========================================
+ Coverage   83.36%   83.40%   +0.04%     
==========================================
  Files         261      262       +1     
  Lines       51015    51135     +120     
  Branches    46576    46696     +120     
==========================================
+ Hits        42527    42648     +121     
+ Misses       6120     6109      -11     
- Partials     2368     2378      +10

Flag	Coverage Δ
python	`91.46% <ø> (ø)`
rust	`82.63% <85.00%> (+0.04%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull Request Overview

This PR adds a new describe sub-command to the CLI that loads and displays information about HUGR packages. The command outputs package metadata either as formatted tables (default) or JSON (with --json flag), with various options to control the level of detail shown.

Key changes:

Adds a new describe subcommand with support for table and JSON output formats
Implements filtering options for module extensions, public symbols, and packaged extensions
Handles partial descriptions when package loading fails, outputting available information to stdout and errors to stderr

Reviewed Changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
hugr-cli/src/describe.rs	New module implementing the describe command with table/JSON formatting and filtering logic
hugr-cli/src/lib.rs	Adds the Describe variant to CliCommand enum and imports the describe module
hugr-cli/src/main.rs	Adds command dispatch for the describe subcommand
hugr-cli/Cargo.toml	Adds dependencies for tabled (table formatting) and serde (JSON serialization)
hugr-cli/tests/describe.rs	Comprehensive test suite covering basic usage, JSON output, filtering options, and error cases

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

hugr-cli/src/describe.rs

cqc-alec · 2025-10-29T12:47:57Z

hugr-cli/src/main.rs


    if let Err(err) = result {
        error!("{:?}", err);
+        // TODO include description if verbosity is high enough


Do you want to do this here or leave it for later?

leftover, don't think this is necessary anymore - again related to orthogonal functionality, if something goes wrong the user should be able to use describe

hugr-cli/src/describe.rs

cqc-alec · 2025-10-29T13:09:25Z

hugr-cli/src/describe.rs

+    /// Output in json format
+    pub json: bool,
+
+    /// Output file. Use '-' for stdout.


Weirdly I don't see the final "." when I build and run hugr describe --help. Is there some magic behind this?

Might be a clio bug? seems to strip the final .

hugr-cli/src/describe.rs

cqc-alec · 2025-10-29T13:23:37Z

hugr-cli/src/describe.rs

+            }
+            self.output_json(desc, &res)?;
+        } else {
+            self.print_description(desc)?;


If there is a decoding error, we still print "Package contains 0 module(s) and 0 extension(s)". Is this desired behaviour?

yes, partial descriptions on error are intended - will add to the help docs

cqc-alec · 2025-10-29T13:25:05Z

hugr-cli/src/describe.rs

+        let header = desc.header();
+        writeln!(
+            self.output,
+            "{header}\nPackage contains {} module(s) and {} extension(s)",


As an enhancement we could special-case the value 1 and use singular in that case and plural in others. But not a big deal.

cqc-alec · 2025-10-29T13:33:33Z

hugr-cli/src/describe.rs

Do you think we should also validate the hugr after loading -- either always or just when a suitable option is given on the CLI? Currently there is no indication if a hugr fails validation.

the usage pattern i was imagining was hugr validate and if it fails hugr describe to try and figure out what happened. Trying to keep the sub-commands orthogonal.

hugr-cli/src/lib.rs

codspeed-hq · 2025-10-31T13:53:32Z

CodSpeed Performance Report

Merging #2650 will not alter performance

_{Comparing ss/push-ppqolononmxt (e555db5) with main (349dd61)}

Summary

✅ 25 untouched

# Goals - Track descriptions during package loading such that partial descriptions can be provided even if an error is returned - Provide a `describe` cli subcommand for high-level descriptions of a package, primarily for debug purposes #2650. Since we want a description even if some loading stage fails (e.g. extension resolution), tracking partial descriptions is a requirement. ## Secondary goals - Unify loading approaches across json/model, centralise more validation logic - Reduce burden on EnvelopeError - more local errors - Replace existing debug extraction (generator, used extensions, envelopeconfig) with single description # Approach In order to make this PR non-breaking I have deprecated existing reading functions, and introduced new functions that return a full description on successful read, and a partial when error. The deprecated functions are most of the missing test coverage. Reading naturally falls in to two stages: header and payload. If the header fails no description is valid, so that error does not come with a description. Payload errors can come with descriptions. In order to build descriptions while loading I introduce the `Reader` struct to track data across the reading stages. This is handed off to the model `Context` when that stage takes over. ## Partial descriptions Descriptions are defined in description.rs. They are intended to be small amounts of simple data, so all fields are pub. All fields except the envelope header are optional, a value of None indicates the field has not been set yet. ## Appendix: JSON Since the JSON format is effectively legacy I did not focus much on incremental description tracking, it is more difficult since serde likes to read all at once. I found a surprise performance regression in JSON loading. In commit [af01043](af01043) I attempted to address this by removing an unnecessary two stage serde deser, which has swung things in the other direction, improving performance from prior. ## Appendix: EnvelopeError EnvelopeError is used as a catch all for all reading and writing errors. This PR goes some way to introducing new more specific errors for reaeding. EnvelopeError should really in future have the reading errors be taken out of it and renamed to `WriteError` or similar, then all the conversions from the reading errors can be removed. Removing the deprecated read functions is a pre-requisite for this. The merging of this PR should be accompanied by issues for these follow ups.

Co-authored-by: Alec Edgington <[email protected]>

## 🤖 New release * `hugr-model`: 0.24.0 -> 0.24.1 (✓ API compatible changes) * `hugr-core`: 0.24.0 -> 0.24.1 (✓ API compatible changes) * `hugr-llvm`: 0.24.0 -> 0.24.1 (✓ API compatible changes) * `hugr-passes`: 0.24.0 -> 0.24.1 (✓ API compatible changes) * `hugr-persistent`: 0.3.1 -> 0.3.2 (✓ API compatible changes) * `hugr`: 0.24.0 -> 0.24.1 (✓ API compatible changes) * `hugr-cli`: 0.24.0 -> 0.24.1 (✓ API compatible changes) <details><summary>Changelog</summary> ## `hugr-model` <blockquote> ## [0.24.1](hugr-model-v0.24.0...hugr-model-v0.24.1) - 2025-11-03 ### Bug Fixes - Correct conversion of `table::Term::Tuple` to `ast::Term` ([#2653](#2653)) </blockquote> ## `hugr-core` <blockquote> ## [0.24.1](hugr-core-v0.24.0...hugr-core-v0.24.1) - 2025-11-03 ### Bug Fixes - validation outside entrypoint, normalize_cfgs w/ nonlocal edges ([#2633](#2633)) - SiblingSubgraph::try_from_nodes for non-entrypoint region ([#2655](#2655)) - Correct conversion of `table::Term::Tuple` to `ast::Term` ([#2653](#2653)) ### New Features - track package descriptions when loading ([#2639](#2639)) - *(cli)* describe sub-command ([#2650](#2650)) </blockquote> ## `hugr-llvm` <blockquote> ## [0.24.0](hugr-llvm-v0.23.0...hugr-llvm-v0.24.0) - 2025-10-13 ### New Features - LLVM lowering for borrow arrays using bitmasks ([#2574](#2574)) - *(py, core, llvm)* add `is_borrowed` op for BorrowArray ([#2610](#2610)) ### Refactor - [**breaking**] consistent inout order in borrow array ([#2621](#2621)) </blockquote> ## `hugr-passes` <blockquote> ## [0.24.1](hugr-passes-v0.24.0...hugr-passes-v0.24.1) - 2025-11-03 ### Bug Fixes - validation outside entrypoint, normalize_cfgs w/ nonlocal edges ([#2633](#2633)) </blockquote> ## `hugr-persistent` <blockquote> ## [0.3.2](hugr-persistent-v0.3.1...hugr-persistent-v0.3.2) - 2025-11-03 ### New Features - *(persistent)* More efficient HugrView iterators for PersistentHugr ([#2595](#2595)) </blockquote> ## `hugr` <blockquote> ## [0.24.1](hugr-v0.24.0...hugr-v0.24.1) - 2025-11-03 ### Bug Fixes - validation outside entrypoint, normalize_cfgs w/ nonlocal edges ([#2633](#2633)) - SiblingSubgraph::try_from_nodes for non-entrypoint region ([#2655](#2655)) - Correct conversion of `table::Term::Tuple` to `ast::Term` ([#2653](#2653)) ### New Features - track package descriptions when loading ([#2639](#2639)) - *(cli)* describe sub-command ([#2650](#2650)) </blockquote> ## `hugr-cli` <blockquote> ## [0.24.1](hugr-cli-v0.24.0...hugr-cli-v0.24.1) - 2025-11-03 ### New Features - track package descriptions when loading ([#2639](#2639)) - *(cli)* describe sub-command ([#2650](#2650)) </blockquote> </details> --- This PR was generated with [release-plz](https://github.com/release-plz/release-plz/).

## 🤖 New release * `hugr-model`: 0.24.1 -> 0.24.2 * `hugr-core`: 0.24.1 -> 0.24.2 * `hugr-llvm`: 0.24.1 -> 0.24.2 * `hugr-passes`: 0.24.1 -> 0.24.2 (✓ API compatible changes) * `hugr`: 0.24.1 -> 0.24.2 (✓ API compatible changes) * `hugr-cli`: 0.24.1 -> 0.24.2 (✓ API compatible changes) * `hugr-persistent`: 0.3.2 -> 0.3.3 <details><summary>Changelog</summary> ## `hugr-model` <blockquote> ## [0.24.1](hugr-model-v0.24.0...hugr-model-v0.24.1) - 2025-11-03 ### Bug Fixes - Correct conversion of `table::Term::Tuple` to `ast::Term` ([#2653](#2653)) </blockquote> ## `hugr-core` <blockquote> ## [0.24.1](hugr-core-v0.24.0...hugr-core-v0.24.1) - 2025-11-03 ### Bug Fixes - validation outside entrypoint, normalize_cfgs w/ nonlocal edges ([#2633](#2633)) - SiblingSubgraph::try_from_nodes for non-entrypoint region ([#2655](#2655)) - Correct conversion of `table::Term::Tuple` to `ast::Term` ([#2653](#2653)) ### New Features - track package descriptions when loading ([#2639](#2639)) - *(cli)* describe sub-command ([#2650](#2650)) </blockquote> ## `hugr-llvm` <blockquote> ## [0.24.0](hugr-llvm-v0.23.0...hugr-llvm-v0.24.0) - 2025-10-13 ### New Features - LLVM lowering for borrow arrays using bitmasks ([#2574](#2574)) - *(py, core, llvm)* add `is_borrowed` op for BorrowArray ([#2610](#2610)) ### Refactor - [**breaking**] consistent inout order in borrow array ([#2621](#2621)) </blockquote> ## `hugr-passes` <blockquote> ## [0.24.2](hugr-passes-v0.24.1...hugr-passes-v0.24.2) - 2025-11-03 ### Bug Fixes - ReplaceTypes: operate on whole Hugr, with set_regions ([#2662](#2662)) </blockquote> ## `hugr` <blockquote> ## [0.24.2](hugr-v0.24.1...hugr-v0.24.2) - 2025-11-03 ### Bug Fixes - ReplaceTypes: operate on whole Hugr, with set_regions ([#2662](#2662)) </blockquote> ## `hugr-cli` <blockquote> ## [0.24.1](hugr-cli-v0.24.0...hugr-cli-v0.24.1) - 2025-11-03 ### New Features - track package descriptions when loading ([#2639](#2639)) - *(cli)* describe sub-command ([#2650](#2650)) </blockquote> ## `hugr-persistent` <blockquote> ## [0.3.2](hugr-persistent-v0.3.1...hugr-persistent-v0.3.2) - 2025-11-03 ### New Features - *(persistent)* More efficient HugrView iterators for PersistentHugr ([#2595](#2595)) </blockquote> </details> --- This PR was generated with [release-plz](https://github.com/release-plz/release-plz/).

## 🤖 New release * `hugr-model`: 0.24.2 -> 0.24.3 (✓ API compatible changes) * `hugr-core`: 0.24.2 -> 0.24.3 * `hugr-llvm`: 0.24.2 -> 0.24.3 (✓ API compatible changes) * `hugr-passes`: 0.24.2 -> 0.24.3 (✓ API compatible changes) * `hugr`: 0.24.2 -> 0.24.3 (✓ API compatible changes) * `hugr-cli`: 0.24.2 -> 0.24.3 (✓ API compatible changes) * `hugr-persistent`: 0.3.3 -> 0.3.4 <details><summary>Changelog</summary> ## `hugr-model` <blockquote> ## [0.24.1](hugr-model-v0.24.0...hugr-model-v0.24.1) - 2025-11-03 ### Bug Fixes - Correct conversion of `table::Term::Tuple` to `ast::Term` ([#2653](#2653)) </blockquote> ## `hugr-core` <blockquote> ## [0.24.1](hugr-core-v0.24.0...hugr-core-v0.24.1) - 2025-11-03 ### Bug Fixes - validation outside entrypoint, normalize_cfgs w/ nonlocal edges ([#2633](#2633)) - SiblingSubgraph::try_from_nodes for non-entrypoint region ([#2655](#2655)) - Correct conversion of `table::Term::Tuple` to `ast::Term` ([#2653](#2653)) ### New Features - track package descriptions when loading ([#2639](#2639)) - *(cli)* describe sub-command ([#2650](#2650)) </blockquote> ## `hugr-llvm` <blockquote> ## [0.24.3](hugr-llvm-v0.24.2...hugr-llvm-v0.24.3) - 2025-11-06 ### Bug Fixes - BorrowArray discard handler allows elements to be borrowed ([#2666](#2666)) </blockquote> ## `hugr-passes` <blockquote> ## [0.24.3](hugr-passes-v0.24.2...hugr-passes-v0.24.3) - 2025-11-06 ### Bug Fixes - BorrowArray discard handler allows elements to be borrowed ([#2666](#2666)) </blockquote> ## `hugr` <blockquote> ## [0.24.3](hugr-v0.24.2...hugr-v0.24.3) - 2025-11-06 ### Bug Fixes - BorrowArray discard handler allows elements to be borrowed ([#2666](#2666)) </blockquote> ## `hugr-cli` <blockquote> ## [0.24.1](hugr-cli-v0.24.0...hugr-cli-v0.24.1) - 2025-11-03 ### New Features - track package descriptions when loading ([#2639](#2639)) - *(cli)* describe sub-command ([#2650](#2650)) </blockquote> ## `hugr-persistent` <blockquote> ## [0.3.2](hugr-persistent-v0.3.1...hugr-persistent-v0.3.2) - 2025-11-03 ### New Features - *(persistent)* More efficient HugrView iterators for PersistentHugr ([#2595](#2595)) </blockquote> </details> --- This PR was generated with [release-plz](https://github.com/release-plz/release-plz/).

ss2165 requested a review from a team as a code owner October 29, 2025 11:52

ss2165 requested review from mark-koch and removed request for a team October 29, 2025 11:52

ss2165 mentioned this pull request Oct 29, 2025

feat: track package descriptions when loading #2639

Merged

ss2165 force-pushed the ss/push-ppqolononmxt branch from fe316f2 to 8b72ff7 Compare October 29, 2025 12:32

ss2165 force-pushed the ss/push-stplquvkmuwx branch from d83cebc to 35bf8fa Compare October 29, 2025 12:32

ss2165 requested review from cqc-alec and removed request for mark-koch October 29, 2025 12:36

ss2165 force-pushed the ss/push-stplquvkmuwx branch from 35bf8fa to 5b2ae6c Compare October 29, 2025 12:49

ss2165 force-pushed the ss/push-ppqolononmxt branch from 8b72ff7 to 435f9d8 Compare October 29, 2025 12:49

ss2165 requested a review from Copilot October 29, 2025 12:49

Copilot AI reviewed Oct 29, 2025

View reviewed changes

hugr-cli/src/describe.rs Outdated Show resolved Hide resolved

hugr-cli/src/describe.rs Outdated Show resolved Hide resolved

hugr-cli/src/describe.rs Outdated Show resolved Hide resolved

cqc-alec reviewed Oct 29, 2025

View reviewed changes

ss2165 requested a review from cqc-alec October 29, 2025 15:04

cqc-alec approved these changes Oct 29, 2025

View reviewed changes

hugr-cli/src/lib.rs Outdated Show resolved Hide resolved

ss2165 force-pushed the ss/push-ppqolononmxt branch from 306b3a5 to 87aaf2d Compare October 30, 2025 13:03

ss2165 force-pushed the ss/push-stplquvkmuwx branch from d6350c9 to f32406d Compare October 30, 2025 13:26

ss2165 force-pushed the ss/push-ppqolononmxt branch 2 times, most recently from 6f72629 to 0bf7bbd Compare October 30, 2025 13:56

ss2165 force-pushed the ss/push-stplquvkmuwx branch 2 times, most recently from f51da3c to fe20cc4 Compare October 31, 2025 13:46

ss2165 force-pushed the ss/push-ppqolononmxt branch from 0bf7bbd to 0ca7e5a Compare October 31, 2025 13:46

ss2165 force-pushed the ss/push-ppqolononmxt branch from 16fdb8a to 63a992a Compare October 31, 2025 14:55

ss2165 force-pushed the ss/push-stplquvkmuwx branch from fe20cc4 to 334e96b Compare November 3, 2025 10:21

Base automatically changed from ss/push-stplquvkmuwx to main November 3, 2025 10:33

ss2165 added 2 commits November 3, 2025 10:33

feat(cli): describe sub-command

7482397

review suggestions

660fdb6

ss2165 and others added 4 commits November 3, 2025 10:33

help headings

366ff2c

detect singular

514e9d2

Update hugr-cli/src/lib.rs

f2332d6

Co-authored-by: Alec Edgington <[email protected]>

add schema output

e555db5

ss2165 force-pushed the ss/push-ppqolononmxt branch from 63a992a to e555db5 Compare November 3, 2025 10:35

ss2165 enabled auto-merge November 3, 2025 10:35

ss2165 added this pull request to the merge queue Nov 3, 2025

Merged via the queue into main with commit 96a294f Nov 3, 2025
31 checks passed

ss2165 deleted the ss/push-ppqolononmxt branch November 3, 2025 10:51

hugrbot mentioned this pull request Nov 3, 2025

chore: release #2625

Merged

hugrbot mentioned this pull request Nov 3, 2025

chore: release #2661

Merged

This was referenced Nov 5, 2025

chore: release #2667

Closed

chore: release #2669

Merged

hugrbot mentioned this pull request Nov 10, 2025

chore: release #2674

Draft

feat(cli): describe sub-command #2650

feat(cli): describe sub-command #2650

Uh oh!

Conversation

ss2165 commented Oct 29, 2025

Help

Summary

JSON (nushell render)

Uh oh!

codecov bot commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codspeed-hq bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging #2650 will not alter performance

Summary

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Oct 29, 2025 •

edited

Loading

codspeed-hq bot commented Oct 31, 2025 •

edited

Loading