improve error message (#135)

Improve error messages when QIR generation fails

Drive-by: don't run snapshot checks on cibuildwheel (they tend to fail
for unimportant reasons)
Drive-by2: track pre-commit config

---------

Co-authored-by: Travis Thompson <[email protected]>
Co-authored-by: Travis Thompson <[email protected]>

Author: cqc-melf

.gitignore

@@ -5,8 +5,6 @@ devenv.local.nix
 # direnv
 .direnv
 
-# pre-commit
-.pre-commit-config.yaml
 /.envrc
 
 

.pre-commit-config.yaml

@@ -0,0 +1,98 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0 # Use the ref you want to point at
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-vcs-permalinks
+      - id: check-yaml
+      - id: detect-private-key
+      - id: end-of-file-fixer
+        exclude: |
+          (?x)^(
+            specification/schema/.*|
+            .*\.snap|
+            .*\.snap\.new|
+            .*\.ambr|
+            .release-please-manifest.json|
+            .*/snapshots/.*
+          )$
+      - id: trailing-whitespace
+        exclude: |
+          (?x)^(
+            specification/schema/.*|
+            .*\.snap|
+            .*\.ambr|
+            .*\.snap\.new|
+            .*/snapshots/.*
+          )$
+      - id: fix-byte-order-marker
+      - id: mixed-line-ending
+      # Python-specific
+      - id: check-ast
+      - id: check-docstring-first
+      - id: debug-statements
+
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        description: Format python code with `ruff`.
+        entry: uv run ruff format
+        language: system
+        files: \.py$
+        pass_filenames: false
+      - id: ruff-check
+        name: ruff
+        description: Check python code with `ruff`.
+        entry: uv run ruff check --fix --exit-non-zero-on-fix
+        language: system
+        files: \.py$
+        pass_filenames: false
+      - id: mypy-check
+        name: mypy
+        description: Check python code with `mypy`.
+        entry: uv run mypy .
+        language: system
+        files: \.py$
+        pass_filenames: false
+      - id: cargo-fmt
+        name: cargo format
+        description: Format rust code with `cargo fmt`.
+        entry: cargo fmt --all -- --check
+        language: system
+        files: \.rs$
+        pass_filenames: false
+      - id: cargo-check
+        name: cargo check
+        description: Check rust code with `cargo check`.
+        entry: cargo check --all --all-features --workspace
+        language: system
+        files: \.rs$
+        pass_filenames: false
+      - id: cargo-test
+        name: cargo test
+        description:
+          Run tests with `cargo test`.
+          # guppy tests require python/guppylang so use uv to run cargo test
+        entry: uv run cargo test
+        language: system
+        files: \.rs$
+        pass_filenames: false
+      - id: cargo-clippy
+        name: cargo clippy
+        description: Run clippy lints with `cargo clippy`.
+        entry: cargo clippy --all-targets --all-features --workspace -- -D warnings
+        language: system
+        files: \.rs$
+        pass_filenames: false
+      - id: cargo-doc
+        name: cargo doc
+        description: Generate documentation with `cargo doc`.
+        entry: sh -c "RUSTDOCFLAGS=-Dwarnings cargo doc --no-deps --all-features --workspace"
+        language: system
+        files: \.rs$
+        pass_filenames: false

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "hugr-qir"
-version = "0.0.15"
+version = "0.0.16"
 edition = "2024"
 rust-version = "1.85"
 

Cargo.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hugr-qir"
-version = "0.0.15"
+version = "0.0.16"
 description = "Quantinuum's tool for converting HUGR to QIR"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -52,7 +52,7 @@ skip = "*-win32 *-manylinux_i686 *-musllinux*"
 manylinux-x86_64-image = "manylinux_2_34"
 test-groups = ["dev"]
 test-sources = ["python/tests", "guppy_examples"]
-test-command = "pytest python/tests -k test_guppy_files"
+test-command = "pytest python/tests"
 
 [tool.cibuildwheel.linux.environment]
 PATH = '$HOME/.cargo/bin:/tmp/llvm/bin:$PATH'

pyproject.toml

@@ -121,14 +121,28 @@ def hugr_qir_impl(  # noqa: PLR0913
         tmp_outfile_name = f"{tmp_dir}/tmp.ll"  # noqa: S108
         tmp_outfile_path = Path(tmp_outfile_name)
         tmp_options = [*options, "-o", tmp_outfile_name]
-        cli(str(hugr_file), *tmp_options)
-        with Path.open(tmp_outfile_path) as output:
-            qir = output.read()
+        failedqirmsg = "QIR generation failed. This may be the result of a bug \
+         but can also happen when trying to convert a feature in HUGR/Guppylang \
+         which is not supported in QIR."
+        try:
+            cli(str(hugr_file), *tmp_options)
+        except RuntimeError as e:
+            msg = f"{failedqirmsg} Error details: {e}"
+            raise ValueError(msg) from e
+        try:
+            with Path.open(tmp_outfile_path) as output:
+                qir = output.read()
+        except FileNotFoundError as e:
+            msg = f"{failedqirmsg} Error details: {e}"
+            raise ValueError(msg) from e
     if validate_qir:
         try:
             qircheck(qir)
         except ValidationError as e:
-            msg = f"Found a problem in the generated QIR: {e}"
+            msg = f"{failedqirmsg} The failure occurred in the validity check of the \
+            generated QIR. This check can be disabled by setting `--no-validate-qir`\
+            on the cli or passing `validate_qir=False` for library calls. Error \
+            details: {e}"
             raise ValueError(msg) from e
 
     llvm_write_mode = get_write_mode(output_format)

python/hugr_qir/cli.py

@@ -1,16 +1,33 @@
+import os
 import subprocess
 import sys
 import tempfile
 from pathlib import Path
 from typing import IO
 
+import pytest
 from click.testing import CliRunner
 from hugr_qir.cli import hugr_qir
 
 GUPPY_EXAMPLES_DIR_GENERAL = Path(__file__).parent / "../../guppy_examples/general"
 GUPPY_EXAMPLES_DIR_QHO = (
     Path(__file__).parent / "../../guppy_examples/quantinuum-hardware-only"
 )
+# Within the cibuildwheels environments, ssa variable names tend to be slightly
+# different, so verbatim snapshot tests do not pass. So we just test
+# that generation works for the wheel builds
+skip_snapshot_checks = os.getenv("CIBUILDWHEEL") == "1"
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    if skip_snapshot_checks:
+        config.issue_config_time_warning(
+            UserWarning(
+                "Detected tests running on cibuildwheel,"
+                " so skipping all snapshot checks"
+            ),
+            stacklevel=2,
+        )
 
 
 def guppy_to_hugr_file(guppy_file: Path, outfd: IO) -> None:

python/tests/conftest.py

@@ -9,6 +9,7 @@
     GUPPY_EXAMPLES_DIR_GENERAL,
     cli_on_guppy,
     guppy_files,
+    skip_snapshot_checks,
 )
 
 SNAPSHOT_DIR = Path(__file__).parent / "snapshots"
@@ -49,7 +50,8 @@ def test_guppy_file_snapshots(
     )
     with Path.open(out_file) as f:
         qir = f.read()
-    snapshot.assert_match(qir, str(Path(guppy_file.stem).with_suffix(".ll")))
+    if not skip_snapshot_checks:
+        snapshot.assert_match(qir, str(Path(guppy_file.stem).with_suffix(".ll")))
 
 
 @pytest.mark.parametrize(
@@ -76,7 +78,7 @@ def test_guppy_files_options(
     with Path.open(out_file, mode=file_read_mode) as f:
         qir = f.read()
     # don't test snapshots for 'native' since output is machine-dependent
-    if target != "native":
+    if target != "native" and not skip_snapshot_checks:
         snapshot_filename = guppy_file.stem + "_" + target + "_" + opt_level
         snapshot.assert_match(
             qir, str(Path(snapshot_filename).with_suffix(file_suffix))

python/tests/test_guppy_examples.py

@@ -17,6 +17,7 @@
     GUPPY_EXAMPLES_DIR_GENERAL,
     guppy_files,
     guppy_to_hugr_binary,
+    skip_snapshot_checks,
 )
 
 SNAPSHOT_DIR = Path(__file__).parent / "snapshots"
@@ -61,7 +62,8 @@ def test_guppy_file_snapshots(guppy_file: Path, snapshot: Snapshot) -> None:
     snapshot.snapshot_dir = SNAPSHOT_DIR
     hugr = guppy_to_hugr_binary(guppy_file)
     qir = hugr_to_qir(hugr, validate_qir=False, output_format=OutputFormat.LLVM_IR)
-    snapshot.assert_match(qir, str(Path(guppy_file.stem).with_suffix(".ll")))
+    if not skip_snapshot_checks:
+        snapshot.assert_match(qir, str(Path(guppy_file.stem).with_suffix(".ll")))
 
 
 @pytest.mark.parametrize(
@@ -110,7 +112,7 @@ def test_guppy_files_options(
         output_format=OutputFormat(out_format),
     )
     # don't test snapshots for 'native' since output is machine-dependent
-    if target != "native":
+    if target != "native" and not skip_snapshot_checks:
         file_suffix = expected_file_extension(out_format)
         snapshot_filename = guppy_file.stem + "_" + target + "_" + opt_level
         snapshot.assert_match(