feat: Documentation and error hints #2523

zrho · 2025-08-18T08:51:01Z

This PR adds doc comments and error hints to explain model import better.

codecov · 2025-08-18T08:55:47Z

Codecov Report

❌ Patch coverage is 3.94737% with 73 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.85%. Comparing base (ef06013) to head (8485482).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
hugr-core/src/import.rs	3.94%	71 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2523      +/-   ##
==========================================
- Coverage   82.94%   82.85%   -0.09%     
==========================================
  Files         254      254              
  Lines       47590    47644      +54     
  Branches    43101    43155      +54     
==========================================
+ Hits        39475    39477       +2     
- Misses       6052     6104      +52     
  Partials     2063     2063

Flag	Coverage Δ
python	`91.42% <ø> (ø)`
rust	`81.96% <3.94%> (-0.10%)`	⬇️

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.

aborgna-q · 2025-08-27T14:16:51Z

hugr-core/src/import.rs

 }

+const UNSUPPORTED_HINT: &str = concat!(
+    "Hint: The import process encountered a `hugr-model` feature",


Don't forget to add whitespace at the end of the concatenated lines.

doug-q

This is great, thank you.

I think you did not intend to commit hugr.dylib and tree-sitter-hugr.wasm.

Request changes:

Add whitespace to all the string contants as Agustin says. A test showing this would be nice but not strictly required
Remove the committed binary files, or explain why they are necessary

doug-q · 2025-08-28T08:17:00Z

hugr-model/src/v0/mod.rs

-//! - `hugr-model` allows to declare term constructors that serve as blueprints for constructing
-//!   runtime values. This allows constants to have potentially multiple representations,
-//!   which can be essential in case of very large constants that require efficient encodings.
-//!   `hugr-core` is more restricted, requiring a canonical representation for constant values.


I liked this explict calling out of the need for multiple representations for large constants that require efficient encodings. Can we have it back?

aborgna-q · 2025-09-16T09:22:02Z

hugr-model/src/v0/mod.rs

+//! - Some terms can not yet be represented in `hugr-core` although they should be.
+//!   Importing such terms will result in an error that declares these terms as currently
+//!   unsupported.
+//! - In particular `hugr-core` currently only allows to define custom runtime types but


This will get outdated, so it'd be nice to pin a version

Suggested change

//! - In particular `hugr-core` currently only allows to define custom runtime types but

//! - In particular `hugr-core` (as of `v0.22.3`) only allows to define custom runtime types but

aborgna-q · 2025-09-16T09:37:28Z

hugr-model/src/v0/mod.rs

+//! - `hugr-core` only allows to define type aliases, but not aliases for other terms. The
+//!   alias system is under-developed in both `hugr-core` and `hugr-model` and will need some
+//!   considerable design and implementation work (or to be removed if deemed unnecessary).


Is there an Issue to link here?

Now there is: #2558

aborgna-q · 2025-09-16T09:42:20Z

hugr-core/src/import.rs

+                    // TODO: Allow calling functions that are passed as variables.
+                    //
+                    // This would be necessary to allow functions which take
+                    // other functions as static parameters and then call them.


Open an issue and link it here, so we can keep track of it

aborgna-q · 2025-09-16T09:42:32Z

hugr-core/src/import.rs

+                    // TODO: Allow importing and calling anonoymous functions.
+                    //
+                    // This could be implemented in `hugr-core` by lifting the anonymous function
+                    // into a function to be added into the containing module and then calling that
+                    // function.


Same here, open an issue and link it here.

More error messages.

Agustín approved, Doug busy in the US visit.

This PR adds doc comments and error hints to explain model import better.

## 🤖 New release * `hugr-model`: 0.22.4 -> 0.23.0 (✓ API compatible changes) * `hugr-core`: 0.22.4 -> 0.23.0 (⚠ API breaking changes) * `hugr-llvm`: 0.22.4 -> 0.23.0 (✓ API compatible changes) * `hugr-passes`: 0.22.4 -> 0.23.0 (⚠ API breaking changes) * `hugr-persistent`: 0.2.3 -> 0.3.0 (✓ API compatible changes) * `hugr`: 0.22.4 -> 0.23.0 (✓ API compatible changes) * `hugr-cli`: 0.22.4 -> 0.23.0 (✓ API compatible changes) ### ⚠ `hugr-core` breaking changes ```text --- failure enum_variant_missing: pub enum variant removed or renamed --- Description: A publicly-visible enum has at least one variant that is no longer available under its prior name. It may have been renamed or removed entirely. ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.43.0/src/lints/enum_variant_missing.ron Failed in: variant PackageEncodingError::ExtensionVersion, previously in file /tmp/.tmp8eoQo1/hugr-core/src/envelope/package_json.rs:89 --- failure function_parameter_count_changed: pub fn parameter count changed --- Description: A publicly-visible function now takes a different number of parameters. ref: https://doc.rust-lang.org/cargo/reference/semver.html#fn-change-arity impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.43.0/src/lints/function_parameter_count_changed.ron Failed in: hugr_core::import::import_package now takes 3 parameters instead of 2, in /tmp/.tmpBTXSed/hugr/hugr-core/src/import.rs:187 --- failure struct_missing: pub struct removed or renamed --- Description: A publicly-visible struct cannot be imported by its prior path. A `pub use` may have been removed, or the struct itself may have been renamed or removed entirely. ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.43.0/src/lints/struct_missing.ron Failed in: struct hugr_core::extension::prelude::PRELUDE_REGISTRY, previously in file /tmp/.tmp8eoQo1/hugr-core/src/extension/prelude.rs:43 struct hugr_core::extension::PRELUDE_REGISTRY, previously in file /tmp/.tmp8eoQo1/hugr-core/src/extension/prelude.rs:43 struct hugr_core::std_extensions::logic::EXTENSION, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/logic.rs:134 struct hugr_core::extension::prelude::PRELUDE, previously in file /tmp/.tmp8eoQo1/hugr-core/src/extension/prelude.rs:43 struct hugr_core::extension::PRELUDE, previously in file /tmp/.tmp8eoQo1/hugr-core/src/extension/prelude.rs:43 struct hugr_core::std_extensions::ptr::EXTENSION, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/ptr.rs:112 struct hugr_core::std_extensions::arithmetic::int_types::EXTENSION, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/arithmetic/int_types.rs:209 struct hugr_core::std_extensions::arithmetic::conversions::EXTENSION, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/arithmetic/conversions.rs:174 struct hugr_core::std_extensions::collections::array::EXTENSION, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/collections/array.rs:93 struct hugr_core::std_extensions::arithmetic::int_types::INT_TYPES, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/arithmetic/int_types.rs:49 struct hugr_core::std_extensions::arithmetic::float_types::EXTENSION, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/arithmetic/float_types.rs:104 struct hugr_core::std_extensions::collections::static_array::EXTENSION, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/collections/static_array.rs:142 struct hugr_core::std_extensions::collections::list::EXTENSION, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/collections/list.rs:289 struct hugr_core::std_extensions::STD_REG, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions.rs:35 struct hugr_core::std_extensions::collections::value_array::EXTENSION, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/collections/value_array.rs:99 struct hugr_core::std_extensions::collections::borrow_array::EXTENSION, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/collections/borrow_array.rs:290 struct hugr_core::std_extensions::arithmetic::float_ops::EXTENSION, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/arithmetic/float_ops.rs:115 struct hugr_core::std_extensions::arithmetic::int_ops::EXTENSION, previously in file /tmp/.tmp8eoQo1/hugr-core/src/std_extensions/arithmetic/int_ops.rs:254 ``` ### ⚠ `hugr-passes` breaking changes ```text --- failure enum_missing: pub enum removed or renamed --- Description: A publicly-visible enum cannot be imported by its prior path. A `pub use` may have been removed, or the enum itself may have been renamed or removed entirely. ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.43.0/src/lints/enum_missing.ron Failed in: enum hugr_passes::non_local::NonLocalEdgesError, previously in file /tmp/.tmp8eoQo1/hugr-passes/src/non_local.rs:57 ``` <details><summary>Changelog</summary> ## `hugr-model` <blockquote> ## [0.23.0](hugr-model-v0.22.4...hugr-model-v0.23.0) - 2025-09-30 ### Bug Fixes - [**breaking**] Appease `cargo-audit` by replacing unmaintained dependencies ([#2572](#2572)) ### New Features - Documentation and error hints ([#2523](#2523)) </blockquote> ## `hugr-core` <blockquote> ## [0.23.0](hugr-core-v0.22.4...hugr-core-v0.23.0) - 2025-09-30 ### Bug Fixes - [**breaking**] Appease `cargo-audit` by replacing unmaintained dependencies ([#2572](#2572)) - *(core)* check extension versions on model import ([#2580](#2580)) - [**breaking**] test extension version compatibility on ModelWithExts ([#2587](#2587)) - *(core)* check used extension versions against resolved extensions ([#2588](#2588)) - [**breaking**] model import loads Package extensions ([#2590](#2590)) ### Miscellaneous Tasks - [**breaking**] Cleanup deprecated definitions ([#2594](#2594)) ### New Features - add trait+funcs for linking Hugrs explicitly by Node ([#2521](#2521)) - Documentation and error hints ([#2523](#2523)) - Allow creating DFG builders from existing hugrs ([#2562](#2562)) - add_input/output for arbitrary DFGBuilders ([#2564](#2564)) - [**breaking**] Return error instead of panicking in DFGWrapper::add_{in,out}put ([#2571](#2571)) - *(core)* inner acccesors for WithGenerator error ([#2583](#2583)) - Normalize CFGs ([#2591](#2591)) ### Refactor - [**breaking**] Replace lazy_static with std::sync::LazyLock ([#2567](#2567)) </blockquote> ## `hugr-llvm` <blockquote> ## [0.23.0](hugr-llvm-v0.22.4...hugr-llvm-v0.23.0) - 2025-09-30 ### Miscellaneous Tasks - [**breaking**] Cleanup deprecated definitions ([#2594](#2594)) ### Refactor - [**breaking**] Replace lazy_static with std::sync::LazyLock ([#2567](#2567)) ### Testing - Add framework for LLVM execution tests involving panics ([#2568](#2568)) </blockquote> ## `hugr-passes` <blockquote> ## [0.23.0](hugr-passes-v0.22.4...hugr-passes-v0.23.0) - 2025-09-30 ### Bug Fixes - DeadCodeElim keeps consumers of linear outputs ([#2560](#2560)) - [**breaking**] Appease `cargo-audit` by replacing unmaintained dependencies ([#2572](#2572)) ### Miscellaneous Tasks - [**breaking**] Cleanup deprecated definitions ([#2594](#2594)) ### New Features - [**breaking**] DeadCodeElimPass reports error on non-existent entry_points ([#2566](#2566)) - Normalize CFGs ([#2591](#2591)) ### Refactor - [**breaking**] Replace lazy_static with std::sync::LazyLock ([#2567](#2567)) </blockquote> ## `hugr-persistent` <blockquote> ## [0.3.0](hugr-persistent-v0.2.3...hugr-persistent-v0.3.0) - 2025-09-30 ### Miscellaneous Tasks - [**breaking**] Cleanup deprecated definitions ([#2594](#2594)) ### Refactor - [**breaking**] Replace lazy_static with std::sync::LazyLock ([#2567](#2567)) </blockquote> ## `hugr` <blockquote> ## [0.23.0](hugr-v0.22.4...hugr-v0.23.0) - 2025-09-30 ### Bug Fixes - DeadCodeElim keeps consumers of linear outputs ([#2560](#2560)) - [**breaking**] Appease `cargo-audit` by replacing unmaintained dependencies ([#2572](#2572)) - *(core)* check extension versions on model import ([#2580](#2580)) - [**breaking**] test extension version compatibility on ModelWithExts ([#2587](#2587)) - *(core)* check used extension versions against resolved extensions ([#2588](#2588)) - [**breaking**] model import loads Package extensions ([#2590](#2590)) ### Miscellaneous Tasks - [**breaking**] Cleanup deprecated definitions ([#2594](#2594)) ### New Features - [**breaking**] DeadCodeElimPass reports error on non-existent entry_points ([#2566](#2566)) - add trait+funcs for linking Hugrs explicitly by Node ([#2521](#2521)) - Documentation and error hints ([#2523](#2523)) - Allow creating DFG builders from existing hugrs ([#2562](#2562)) - add_input/output for arbitrary DFGBuilders ([#2564](#2564)) - [**breaking**] Return error instead of panicking in DFGWrapper::add_{in,out}put ([#2571](#2571)) - *(core)* inner acccesors for WithGenerator error ([#2583](#2583)) - Normalize CFGs ([#2591](#2591)) ### Refactor - [**breaking**] Replace lazy_static with std::sync::LazyLock ([#2567](#2567)) </blockquote> ## `hugr-cli` <blockquote> ## [0.22.3](hugr-cli-v0.22.2...hugr-cli-v0.22.3) - 2025-09-11 ### New Features - *(hugr-cli)* CliError::validate helper ([#2507](#2507)) </blockquote> </details> --- This PR was generated with [release-plz](https://github.com/release-plz/release-plz/).

## 🤖 New release * `hugr-model`: 0.23.0 -> 0.24.0 * `hugr-core`: 0.23.0 -> 0.24.0 (✓ API compatible changes) * `hugr-llvm`: 0.23.0 -> 0.24.0 (✓ API compatible changes) * `hugr-passes`: 0.23.0 -> 0.24.0 (✓ API compatible changes) * `hugr-persistent`: 0.3.0 -> 0.3.1 (✓ API compatible changes) * `hugr`: 0.23.0 -> 0.24.0 (✓ API compatible changes) * `hugr-cli`: 0.23.0 -> 0.24.0 (✓ API compatible changes) <details><summary>Changelog</summary> ## `hugr-model` <blockquote> ## [0.23.0](hugr-model-v0.22.4...hugr-model-v0.23.0) - 2025-09-30 ### Bug Fixes - [**breaking**] Appease `cargo-audit` by replacing unmaintained dependencies ([#2572](#2572)) ### New Features - Documentation and error hints ([#2523](#2523)) </blockquote> ## `hugr-core` <blockquote> ## [0.24.0](hugr-core-v0.23.0...hugr-core-v0.24.0) - 2025-10-13 ### Bug Fixes - Preserve offset for CFG edges when serializing to JSON ([#2606](#2606)) ### 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-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.0](hugr-passes-v0.23.0...hugr-passes-v0.24.0) - 2025-10-13 ### New Features - Add handler for copying / discarding borrow arrays to default lineariser ([#2602](#2602)) </blockquote> ## `hugr-persistent` <blockquote> ## [0.3.1](hugr-persistent-v0.3.0...hugr-persistent-v0.3.1) - 2025-10-13 ### Bug Fixes - *(test)* No extension serialisation in persistent-hugr testing ([#2612](#2612)) ### New Features - *(persistent)* Redesign CommitStateSpace, bound Commit lifetime ([#2534](#2534)) </blockquote> ## `hugr` <blockquote> ## [0.24.0](hugr-v0.23.0...hugr-v0.24.0) - 2025-10-13 ### Bug Fixes - Preserve offset for CFG edges when serializing to JSON ([#2606](#2606)) ### New Features - Add handler for copying / discarding borrow arrays to default lineariser ([#2602](#2602)) - 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-cli` <blockquote> ## [0.24.0](hugr-cli-v0.23.0...hugr-cli-v0.24.0) - 2025-10-13 ### Documentation - update cli readme ([#2601](#2601)) </blockquote> </details> --- This PR was generated with [release-plz](https://github.com/release-plz/release-plz/).

zrho changed the title ~~Documentation and error hints~~ feat: Documentation and error hints Aug 18, 2025

zrho force-pushed the zrho/push-kyxlsurvlqsq branch 3 times, most recently from db21887 to 22ece1d Compare August 27, 2025 11:19

zrho marked this pull request as ready for review August 27, 2025 11:25

zrho requested a review from a team as a code owner August 27, 2025 11:25

zrho requested a review from doug-q August 27, 2025 11:25

aborgna-q reviewed Aug 27, 2025

View reviewed changes

doug-q previously requested changes Aug 28, 2025

View reviewed changes

zrho requested a review from doug-q September 8, 2025 08:44

zrho requested a review from aborgna-q September 16, 2025 08:55

aborgna-q approved these changes Sep 16, 2025

View reviewed changes

zrho force-pushed the zrho/push-kyxlsurvlqsq branch 2 times, most recently from aec958a to e4a624d Compare September 16, 2025 14:56

zrho added 5 commits September 16, 2025 16:09

Documentation.

bf2992d

Error hints in import.

dae5d63

More error messages.

Spaces in concatenated error messages.

4019a13

Remove accidentally committed tree-sitter files.

2bde82d

More comments on constants.

8485482

zrho force-pushed the zrho/push-kyxlsurvlqsq branch from e4a624d to 8485482 Compare September 16, 2025 15:09

zrho enabled auto-merge September 16, 2025 15:16

zrho added this pull request to the merge queue Sep 17, 2025

Merged via the queue into main with commit bb37b07 Sep 17, 2025
25 of 26 checks passed

zrho deleted the zrho/push-kyxlsurvlqsq branch September 17, 2025 10:06

hugrbot mentioned this pull request Sep 17, 2025

chore: release #2554

Merged

ss2165 pushed a commit that referenced this pull request Sep 24, 2025

feat: Documentation and error hints (#2523)

592f961

This PR adds doc comments and error hints to explain model import better.

hugrbot mentioned this pull request Oct 1, 2025

chore: release #2605

Merged

hugrbot mentioned this pull request Oct 14, 2025

chore: release #2625

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Documentation and error hints #2523

feat: Documentation and error hints #2523

Uh oh!

zrho commented Aug 18, 2025

Uh oh!

codecov bot commented Aug 18, 2025 •

edited

Loading

Uh oh!

aborgna-q Aug 27, 2025

Uh oh!

doug-q left a comment

Uh oh!

doug-q Aug 28, 2025

Uh oh!

aborgna-q Sep 16, 2025

Uh oh!

aborgna-q Sep 16, 2025

Uh oh!

zrho Sep 16, 2025

Uh oh!

aborgna-q Sep 16, 2025

Uh oh!

aborgna-q Sep 16, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	//! - In particular `hugr-core` currently only allows to define custom runtime types but
	//! - In particular `hugr-core` (as of `v0.22.3`) only allows to define custom runtime types but

feat: Documentation and error hints #2523

feat: Documentation and error hints #2523

Uh oh!

Conversation

zrho commented Aug 18, 2025

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

aborgna-q Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

doug-q left a comment

Choose a reason for hiding this comment

Uh oh!

doug-q Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

aborgna-q Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

aborgna-q Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

zrho Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

aborgna-q Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

aborgna-q Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov bot commented Aug 18, 2025 •

edited

Loading