chore: Reword AGENTS.md (#472)

* fix: remove unused code

* fix: 1.90 errors

* MSRV: 1.82.0

* fix: warnings exposed by increasing MSRV

.github/workflows/ci.yml

@@ -10,14 +10,18 @@ jobs:
     name: Check fmt & build docs
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
       - name: Install Rust
-        uses: actions-rs/toolchain@v1
+        uses: dtolnay/rust-toolchain@master
         with:
-          profile: minimal
           toolchain: stable
           components: rustfmt
-          override: true
+      - name: Install cargo-readme
+        run: cargo install cargo-readme
+      - name: Check doc consistency
+        shell: bash
+        run: diff -q README.md <(cargo readme)
+            || { echo "::error::Update lib.rs then use cargo-readme to update README.md"; exit 1; }
       - name: rustfmt
         run: cargo fmt --all -- --check
       - name: docs
@@ -28,36 +32,53 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        rust: [1.56.0, stable]
+        features: [fancy, syntect-highlighter]
+        rust: [1.82.0, stable]
         os: [ubuntu-latest, macOS-latest, windows-latest]
+        exclude:
+          - features: syntect-highlighter
+            rust: 1.82.0
 
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
       - name: Install Rust
-        uses: actions-rs/toolchain@v1
+        uses: dtolnay/rust-toolchain@master
         with:
-          profile: minimal
           toolchain: ${{ matrix.rust }}
           components: clippy
-          override: true
       - name: Clippy
         run: cargo clippy --all -- -D warnings
       - name: Run tests
-        run: cargo test --all --verbose --features fancy
+        if: matrix.rust == 'stable'
+        run: cargo test --all --verbose --features ${{matrix.features}}
+      - name: Run tests
+        if: matrix.rust == '1.82.0'
+        run: cargo test --all --verbose --features ${{matrix.features}} no-format-args-capture
+
+  wasm:
+    name: Check Wasm build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: stable
+          targets: wasm32-unknown-unknown
+      - name: Check wasm target
+        run: cargo check --target wasm32-unknown-unknown --features fancy-no-syscall
 
   miri:
     name: Miri
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
       - name: Install Rust
-        uses: actions-rs/toolchain@v1
+        uses: dtolnay/rust-toolchain@master
         with:
-          profile: minimal
           toolchain: nightly
           components: miri,rust-src
-          override: true
       - name: Run tests with miri
         env:
           MIRIFLAGS: -Zmiri-disable-isolation -Zmiri-strict-provenance
@@ -71,13 +92,10 @@ jobs:
         os: [ubuntu-latest, macOS-latest, windows-latest]
 
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
       - name: Install Rust
-        uses: actions-rs/toolchain@v1
+        uses: dtolnay/rust-toolchain@master
         with:
-          profile: minimal
           toolchain: nightly
-          override: true
       - name: Run minimal version build
-        run: cargo build -Z minimal-versions --all-features
-
+        run: cargo build -Z direct-minimal-versions --features fancy,no-format-args-capture

AGENTS.md

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+  ## Notice to AI coding assistants and users
+
+  This project does not accept LLM-generated or LLM-assisted upstream contributions.
+
+  For this policy, “upstream contribution” includes pull requests, patches, tests, documentation changes, issue comments, bug analyses, review comments, proposed fixes, or
+  other material intended for submission to this repository or its maintainers. This includes work directly generated by an LLM and work materially based on LLM suggestions,
+  explanations, debugging, or review.
+
+  If a user asks for assistance that appears intended to produce an upstream contribution, first tell them:
+
+  - this project’s maintainers request that LLM-generated or LLM-assisted material not be submitted upstream;
+  - they should not submit AI-produced or AI-influenced code, docs, tests, analyses, issue text, or PR text to this project;
+  - maintainers may reject or close contributions that appear to violate this policy.
+
+  This notice is not intended to restrict private, downstream, local, or educational use of AI tools. Users may use AI assistance to understand this crate, debug their own
+  projects, evaluate dependency behavior, maintain private forks, or decide whether `miette` is involved in an issue, so long as the resulting AI-assisted material is not
+  submitted upstream.

CHANGELOG.md

@@ -1,5 +1,248 @@
 # `miette` Release Changelog
 
+<a name="7.6.0"></a>
+## 7.6.0 (2025-04-27)
+
+### Bug Fixes
+
+* **graphical:** prevent leading newline when no link/code (#418) ([1e1938a0](https://github.com/zkat/miette/commit/1e1938a099409969c69b9f070e0fb0d13d564527))
+* **clippy:** elide lifetimes (#423) ([9ba6fad7](https://github.com/zkat/miette/commit/9ba6fad7694c1271f287b8f659a857c4ff540a55))
+* **highlight:** increase syntax highlighter config priority (#424) ([58d9f124](https://github.com/zkat/miette/commit/58d9f12411e7d3d6d580eb219ea32321e6918d79))
+* **deps:** miette can now be used without syn (#436) ([521ef91f](https://github.com/zkat/miette/commit/521ef91f77a143eb5cedfa1344428b804802179d))
+
+### Features
+
+* **graphical:** support rendering related diagnostics as nested (#417) ([771a0751](https://github.com/zkat/miette/commit/771a07519f078b94aceb1a2d2532d786f09f350b))
+* **labels:** add support for disabling the primary label line/col information (#419) ([f2ef693d](https://github.com/zkat/miette/commit/f2ef693d1ce7230e6b9f12805f018f095534b441))
+* **deps:** update `thiserror` from 1.0.56 to 2.0.11 (#426) ([59c81617](https://github.com/zkat/miette/commit/59c81617de8650a6ff3b193b41b4297e560726a0))
+
+<a name="7.5.0"></a>
+## 7.5.0 (2025-02-01)
+
+### Features
+
+* **graphical:** support rendering related diagnostics as nested (#417) ([771a0751](https://github.com/zkat/miette/commit/771a07519f078b94aceb1a2d2532d786f09f350b))
+
+### Bug Fixes
+
+* **graphical:** prevent leading newline when no link/code (#418) ([1e1938a0](https://github.com/zkat/miette/commit/1e1938a099409969c69b9f070e0fb0d13d564527))
+
+<a name="7.4.0"></a>
+## 7.4.0 (2024-11-27)
+
+### Features
+
+* **graphical:** Inherit source code to causes (#401) ([465e6b6a](https://github.com/zkat/miette/commit/465e6b6ab627f8da34baa5f46441d944fb88186e))
+* **report:** Implement `WrapError` for `Option` (#409) ([7fae60fd](https://github.com/zkat/miette/commit/7fae60fd8462f95cf3140c6a3b9eb06cb7953405))
+
+<a name="7.3.0"></a>
+## 7.3.0 (2024-11-26)
+
+### Features
+
+* **SourceSpan:** add impl From<InclusiveRange> (#385) ([73da45b6](https://github.com/zkat/miette/commit/73da45b65c965777a00ba64aa03a247c0e5241ca))
+* **Report:** add `from_err()` method to `Report` (#403) ([93d3bd11](https://github.com/zkat/miette/commit/93d3bd118a072c35aa761f0ec74317166ec08113))
+* **Diagnostic:** Implement `Diagnostic` for `Infallible` (#402) ([f3fb4c1e](https://github.com/zkat/miette/commit/f3fb4c1ecd196ce389cbd71139bb7e3b35474add))
+
+### Performance
+
+* **handlers:** optimize string-buffer reallocations (#387) ([b8dfcda4](https://github.com/zkat/miette/commit/b8dfcda4a8c10a14116ee275250356ac991dc7be))
+
+### Bug Fixes
+
+* **graphical:** fix nested error wrapping (#358) ([3eabbceb](https://github.com/zkat/miette/commit/3eabbcebf113d1d620a6a3f98e8a455414ed3042))
+* **docs:** updated example image (fixes #111) (#270) ([7b42b12c](https://github.com/zkat/miette/commit/7b42b12c5f6316322ce79c59bcb9e99f5d49edb8))
+* **clippy:** Fix clippy lints in docs (#365) ([ea4296da](https://github.com/zkat/miette/commit/ea4296dacec3b0e4762281d9d115c1bd69ecfac3))
+* **docs:** `alt` attribut for `single-line-example.png` (#372) ([b82cc81b](https://github.com/zkat/miette/commit/b82cc81b8ea32a1cf1b4598ed5832bc8e3b0e161))
+* **color:** setting NO_COLOR should not print ansi codes for non-terminals (#381) ([813232ba](https://github.com/zkat/miette/commit/813232ba7957ae09e4fb9d9416d821f4fd9da66d))
+* **clippy:** fix Rust v1.78.0 clippy warnings (#382) ([e1026f75](https://github.com/zkat/miette/commit/e1026f75e0a5d19bbc8e468cb3f5292074543a97))
+* **perf:** mark error constructors cold (#378) ([9bbcf3c6](https://github.com/zkat/miette/commit/9bbcf3c6017fa3455a7db714879816c1cfc511fd))
+* **handlers:** Disable textwrap::smawk feature (#379) ([edfdcb52](https://github.com/zkat/miette/commit/edfdcb525ee30fc54747460ada621f13f0ed1996))
+* **graphical:** Format entire link instead of just name (#389) ([bf5aa374](https://github.com/zkat/miette/commit/bf5aa3742fd664be3c93160b9c28c145b1ed8bc9))
+* **clippy:** fix `clippy::doc_lazy_continuation` lints (#395) ([15beec43](https://github.com/zkat/miette/commit/15beec43303180b811d4c04d1a78775feb9b0905))
+* **graphical:** Handle invalid UTF-8 in source code (#393) ([d6b45585](https://github.com/zkat/miette/commit/d6b4558502e82fa74e030ccb3c8040656590d7eb))
+* **features:** Use `dep:` syntax for dependencies in features. (#394) ([789a04e3](https://github.com/zkat/miette/commit/789a04e30d041179b373b4eb8b340456534a3f0e))
+* **clippy:** Fix `needless_return` lint. (#405) ([5f441d01](https://github.com/zkat/miette/commit/5f441d011560a091fe5d6a6cdb05f09acf622d36))
+
+### Documentation
+
+* **examples:** add serde_json integration example (#407) ([2902a233](https://github.com/zkat/miette/commit/2902a2337c2e36a5d8e0e54b007d6100cca0c9ff))
+
+<a name="7.2.0"></a>
+## 7.2.0 (2024-03-07)
+
+### Features
+
+* **wasm:** add feature "fancy-no-syscall" for wasm targets (#349) ([328bf379](https://github.com/zkat/miette/commit/328bf3792213fc0bed94e72a39acb722b65141dd))
+
+### Bug Fixes
+
+* **label-collections:** Label collection fixes and cleanup (#343) ([75fea093](https://github.com/zkat/miette/commit/75fea0935e495d0215518c80d32dd820910982e3))
+* **invalid span:** skip the snippet when read_span fails (#347) ([7d9dfc6e](https://github.com/zkat/miette/commit/7d9dfc6e8e591f9606c3da55bd8465962358b20f))
+* **redundant-import:** fix a warning and CI failure in nightly (#348) ([6ea86a22](https://github.com/zkat/miette/commit/6ea86a2248854acf88df345814b6c97d31b8b4d9))
+
+<a name="7.1.0"></a>
+## 7.1.0 (2024-02-16)
+
+### Features
+
+* **derive:** enable more boxed types to be #[diagnostic_source] (#338) ([c2f06f6c](https://github.com/zkat/miette/commit/c2f06f6cca15cbdd083dbff3d46b7729056ac6a4))
+* **source:** derive common traits for NamedSource, SourceSpan, and SourceOffset (#340) ([6f09250c](https://github.com/zkat/miette/commit/6f09250cca14561f07fba899a8e6d3c0df14230e))
+* **collection:** add support for collection of labels (#341) ([03060245](https://github.com/zkat/miette/commit/03060245d816a53a33209e6b7e1c3c42948e9962))
+
+### Bug Fixes
+
+* **tests:** revert test-breaking changes of e5c7ae4 (#339) ([6e829f8c](https://github.com/zkat/miette/commit/6e829f8c0ce2fc7bb2fc4041e6a6072f12db1f71))
+
+<a name="7.0.0"></a>
+## 7.0.0 (2024-02-05)
+
+This is a small breaking release on the heels of 6.0 because I neglected to
+bump owo-colors. I figured it's a good time to do it, before 6.0 gets more
+widely used.
+
+### Features
+
+* **fancy:** Add option to change the link display text (#335) ([c7144ee5](https://github.com/zkat/miette/commit/c7144ee513bf8f06c5f7d89c45436802994a51fc))
+* **deps:** bump dependencies ([a4011d17](https://github.com/zkat/miette/commit/a4011d174c40acbba5b0176db7cb71ec5ca0cb49))
+    * **BREAKING CHANGE**: This bumps owo-colors to 4.0, which is a breaking change because we expose its styles as part of the graphical renderer API
+
+<a name="6.0.1"></a>
+## 6.0.1 (2024-02-04)
+
+### Bug Fixes
+
+* **graphical:** oops. Fix theme issue ([8b46679c](https://github.com/zkat/miette/commit/8b46679c3647e1455d91b4c68743c619fb3f3eb3))
+* **fmt:** remove nightly-only fmt flags ([1fa7f524](https://github.com/zkat/miette/commit/1fa7f5241fb91d2e5bad9b0e26bcc7cd5f9011f1))
+* **highlighter:** ugh, missed another spot ([ab7c066e](https://github.com/zkat/miette/commit/ab7c066e7675d8c7ecb956000d278fc31f3bc6a1))
+
+<a name="6.0.0"></a>
+## 6.0.0 (2024-02-04)
+
+The long-awaited 6.0 release of `miette` is here, with TONS of goodies, not
+least of which is syntax highlighting support!
+
+It also comes with a few breaking changes so make sure to check below and
+update your code as needed!
+
+### Features
+
+* **labels:** Add support for primary label in specifying line/col information (#291) ([db0b7e40](https://github.com/zkat/miette/commit/db0b7e403a5ae52ae360991b6508490d8c579886))
+* **derive:** Allow optional sources in derive (#301) ([88d00e0e](https://github.com/zkat/miette/commit/88d00e0e20bf95e03b8f81dcd5adf38c917e190e))
+* **derive:** Make `miette-derive` be able to be turned off (#304) ([c7ba5b7e](https://github.com/zkat/miette/commit/c7ba5b7e52e05991cecd3ca925c710bbe49850b9))
+* **graphical:** Expose additional `textwrap` options (#321) ([fd77257c](https://github.com/zkat/miette/commit/fd77257cee0f5d03aa7dccb4ba8cbaa40c1a88c6))
+* **graphical:** support rendering labels that contain newlines (#318) ([865d67c8](https://github.com/zkat/miette/commit/865d67c8dda119ddd03ac43be22f4fa272a9f433))
+* **graphical:** Add `wrap_lines: bool` option allowing wrapping be disabled entirely (#328) ([b0744462](https://github.com/zkat/miette/commit/b0744462adbbfbb6d845f382db36be883c7f3c45))
+* **graphical:** render disjoint snippets separately for cleaner output (#324) ([19c22143](https://github.com/zkat/miette/commit/19c22143cb544616046784e35c5e78cc5b881289))
+* **deps:** Bump terminal-size to v0.3.0 (#308) ([c0a298e5](https://github.com/zkat/miette/commit/c0a298e5a8d699acf9fcd61b5d5fa4f6279a47ab))
+    * **BREAKING CHANGE**: This requires an MSRV bump to 1.70.0.
+* **source-code:** Don't override provided source code (#300) ([0d5c2ce7](https://github.com/zkat/miette/commit/0d5c2ce7536b0ea205346595d8a00d00bfb6cbd2))
+    * **BREAKING CHANGE**: Source code is no longer overridden if it was provided by the diagnostic's own `source_code()` impl.
+* **source:** use `usize` for length (#265) ([fad0e76a](https://github.com/zkat/miette/commit/fad0e76ad2e19d5cac13cf8324338aca0d623d93))
+    * **BREAKING CHANGE**: This changes `SourceSpan`'s length type to `usize`.
+* **source:** Allow inner source type of a NamedSource to be borrowed (#254) ([1df3b1a5](https://github.com/zkat/miette/commit/1df3b1a537f2e54cd40ec45f5cd851337a22e95a))
+    * **BREAKING CHANGE**: This makes the `NamedSource` type generic over its `Source` type, instead of boxing it.
+* **highlighting:** add syntax highlighting support with syntect crate (#313) ([e65d0a78](https://github.com/zkat/miette/commit/e65d0a78cc639653f061a45d8ce35b1a3551ade7))
+* **deps:** remove is-terminal dep in favor of `std::io::IsTerminal` ([e5c7ae46](https://github.com/zkat/miette/commit/e5c7ae469e40a8bc102e1fca3b8fd4b2ec137696))
+* **deps:** remove once_cell dep in favor of `std::sync::OnceLock` ([4c48584f](https://github.com/zkat/miette/commit/4c48584f304414c6924bede3308b455cfef60749))
+    * **BREAKING CHANGE**: This requires an MSRV bump to 1.70.0.
+* **deps:** bump some semver-breaking deps to newer versions ([29d000f2](https://github.com/zkat/miette/commit/29d000f201b259a056867a2876384f97653a6e9e))
+* **MSRV:** Actually bump the MSRV to 1.70.0 ([ab59a7bc](https://github.com/zkat/miette/commit/ab59a7bc9bceace5761a862ee2ebff3e5943b12f))
+
+### Bug Fixes
+
+* **misc:** Improve ci and fix clippy (#290) ([cc81382a](https://github.com/zkat/miette/commit/cc81382a6070dd226a20e4a39518d88e957ac0e1))
+* **tests:** Fix `cargo test` with default features. (#294) ([1f448e47](https://github.com/zkat/miette/commit/1f448e47751d0f914134b0e9138fdb1a5a95d55c))
+* **clippy:** Add missing semicolons where nothing is returned. (#293) ([06b34823](https://github.com/zkat/miette/commit/06b348230aaf153b8b050322f05e5d185351d2d1))
+* **graphical:** Extend error text span to whole code points (#312) ([a8b4ae01](https://github.com/zkat/miette/commit/a8b4ae012aa0cf03b53a18f013c2b3f76c5040e7))
+* **formatting:** Fix formatting bug when an empty span is not aligned to a char boundary (#314) ([3d6f903d](https://github.com/zkat/miette/commit/3d6f903df0e7c9d0eb9a1fdbbf0028bab5496429))
+* **docs:** add example to README and docs fixing #96 (#319) ([251d6d59](https://github.com/zkat/miette/commit/251d6d59292397458328ef57fb7957faedafd019))
+* **graphical:** rendering bug on small spans in large spans (#316) ([7ff4f874](https://github.com/zkat/miette/commit/7ff4f874d693a665af4df40f4e94505013e3e262))
+* **graphical:** render cause chains for inner errors (#330) ([cb2ae2e1](https://github.com/zkat/miette/commit/cb2ae2e18b446a5e90885faf8a30b5672c307df8))
+* **handler:** remove the two extra `is_terminal` sys call from `MietteHandlerOpts::build` (#325) ([f1dc89c0](https://github.com/zkat/miette/commit/f1dc89c07640445d224b61ef96c6b25fcdf62dee))
+
+### Documentation
+
+* **README:** Move import of `NamedResult` to where it is used (#309) ([d37ada87](https://github.com/zkat/miette/commit/d37ada876a5831d3f47622274e334c9a24aa5d2b))
+
+<a name="5.10.0"></a>
+## 5.10.0 (2023-07-16)
+
+### Features
+
+* **protocol:** add StdError impl for Box<dyn Diagnostic + Send + Sync> (#273) ([2e3e5c9d](https://github.com/zkat/miette/commit/2e3e5c9d15e234495369e9b47d032644dd5664ad))
+
+<a name="5.9.0"></a>
+## 5.9.0 (2023-05-18)
+
+### Features
+
+* **serde:** Add `serde` support (#264) ([c25676cb](https://github.com/zkat/miette/commit/c25676cb1f4266c2607836e6359f15b9cbd8637e))
+* **const:** Constify various functions (#263) ([46adb3bc](https://github.com/zkat/miette/commit/46adb3bc6aa6518d82a4187b34c56e287922136f))
+* **nested:** Render inner diagnostics (#170) ([aefe3237](https://github.com/zkat/miette/commit/aefe323780bda4e60feb44bb96ee98634ad677ad))
+
+### Bug Fixes
+
+* **misc:** Correct some typos (#255) ([675f3411](https://github.com/zkat/miette/commit/675f3411e33d5fae86d4018c3b72f751a4c4bc2f))
+
+<a name="5.8.0"></a>
+## 5.8.0 (2023-04-18)
+
+### Features
+
+* **source:** Add getter for NamedSource name (#252) ([be3b2547](https://github.com/zkat/miette/commit/be3b25475147e92fae631b510c8de22949eada45))
+
+### Bug Fixes
+
+* **narrated:** put URLs in their own line ([adbff65e](https://github.com/zkat/miette/commit/adbff65e4ed52103569a3a5cd09c1bee79f8e361))
+
+<a name="5.7.0"></a>
+## 5.7.0 (2023-04-01)
+
+While this is a semver-minor release, there's potential for it to have
+knock-on effects due to the syn2 upgrade. There's been issues as this new
+version propagates between syn/thiserror versions (for example, see [a similar
+change in eyre](https://github.com/yaahc/eyre/pull/92)).
+
+The other thing of note is that backtrace printing is now **much** better! Try
+the hook and see for yourself!
+
+### Features
+
+* **deps:** update to syn2 (#247) ([a2157205](https://github.com/zkat/miette/commit/a215720576fbda249138808f3469017d81eda9f0))
+* **panic:** improved backtrace handling ([b0453215](https://github.com/zkat/miette/commit/b0453215f62318bedeb4af1cb00dcefbb739d619))
+
+### Bug Fixes
+
+* **colors:** change unicode to default to ansi (#249) ([159f2b35](https://github.com/zkat/miette/commit/159f2b354b7ea83f842a58be98c45d0175b1faad))
+* **tests:** disable doctest that doesn't work with default feature flags (#248) ([0b445dc2](https://github.com/zkat/miette/commit/0b445dc2b4b30d40f03defc130bfa3e7396b51d4))
+
+<a name="5.6.0"></a>
+## 5.6.0 (2023-03-14)
+
+### Bug Fixes
+
+* **ci:** configure clippy-specific MSRV ([b658fc02](https://github.com/zkat/miette/commit/b658fc020b23b0715339c5c60f7c12c947f9a747))
+* **graphical:** Fix wrong severity of related errors (#234) ([3497508a](https://github.com/zkat/miette/commit/3497508aa9b8d8503d7aae997738a4323408ffa0))
+* **atty:** Switch out `atty` for `is-terminal` (#229) ([443d240f](https://github.com/zkat/miette/commit/443d240f49e9f48756ee88e4cdc377f09d44454e))
+
+### Features
+
+* **protocol:** implement `Ord` for `Severity` (#240) ([ed486c95](https://github.com/zkat/miette/commit/ed486c959d8e8fbd4247af7d47d7e32c8a88321d))
+
+<a name="5.5.0"></a>
+## 5.5.0 (2022-11-24)
+
+### Features
+
+* **SourceCode:** Implement SourceCode for Vec<u8> (#216) ([c857595e](https://github.com/zkat/miette/commit/c857595e1ae689028c5c5b66148e81b175eaa509))
+
+### Bug Fixes
+
+* **derive:** elide lifetimes in derived functions (#226) ([c88f0b5a](https://github.com/zkat/miette/commit/c88f0b5aa0786a0f4bb778686548f91db96ea6af))
+* **graphical:** Fix panic with span extending past end of line (#221) ([8b56d277](https://github.com/zkat/miette/commit/8b56d277ef476438a1c7383c29f6c1a0a1684818))
+* **license:** fix mangled license text to improve recognition ([d5fbb340](https://github.com/zkat/miette/commit/d5fbb3409c7cc950c502eb77578d5f1062384fb5))
+
 <a name="5.4.1"></a>
 ## 5.4.1 (2022-10-28)
 

CODE_OF_CONDUCT.md

@@ -37,7 +37,7 @@ Examples of unacceptable behavior by participants include:
   * Public or private harassment, deliberate intimidation, or threats.
   * Publishing others' private information, such as a physical or electronic address, without explicit permission. This includes any sort of "outing" of any aspect of someone's identity without their consent.
   * Publishing private screenshots or quotes of interactions in the context of this project without all quoted users' *explicit* consent.
-  * Publishing of private communication that doesn't have to do with reporting harrassment.
+  * Publishing of private communication that doesn't have to do with reporting harassment.
   * Any of the above even when [presented as "ironic" or "joking"](https://en.wikipedia.org/wiki/Hipster_racism).
   * Any attempt to present "reverse-ism" versions of the above as violations. Examples of reverse-isms are "reverse racism", "reverse sexism", "heterophobia", and "cisphobia".
   * Unsolicited explanations under the assumption that someone doesn't already know it. Ask before you teach! Don't assume what people's knowledge gaps are.

CONTRIBUTING.md

@@ -23,7 +23,7 @@
 
 ## Introduction
 
-Thank you so much for your interest in contributing!. All types of contributions are encouraged and valued. See the [table of contents](#toc) for different ways to help and details about how this project handles them!📝
+Thank you so much for your interest in contributing! All types of contributions are encouraged and valued. See the [table of contents](#toc) for different ways to help and details about how this project handles them!📝
 
 Please make sure to read the relevant section before making your contribution! It will make it a lot easier for us maintainers to make the most of it and smooth out the experience for all involved. 💚
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "miette"
-version = "5.4.1"
+version = "7.6.0"
 authors = ["Kat Marchán <kzm@zkat.tech>"]
 description = "Fancy diagnostic reporting library and protocol for us mere mortals who aren't compiler hackers."
 categories = ["rust-patterns"]
@@ -9,54 +9,68 @@ documentation = "https://docs.rs/miette"
 license = "Apache-2.0"
 readme = "README.md"
 edition = "2018"
-rust-version = "1.56.0"
+rust-version = "1.82.0"
 exclude = ["images/", "tests/", "miette-derive/"]
 
 [dependencies]
-thiserror = "1.0.26"
-miette-derive = { path = "miette-derive", version = "=5.4.1"}
-once_cell = "1.8.0"
-unicode-width = "0.1.9"
+miette-derive = { path = "miette-derive", version = "=7.6.0", optional = true }
+unicode-width = "0.2.0"
+cfg-if = "1.0.0"
 
-owo-colors = { version = "3.0.0", optional = true }
-atty = { version = "0.2.14", optional = true }
-textwrap = { version = "0.15.0", optional = true }
-supports-hyperlinks = { version = "1.1.0", optional = true }
-supports-color = { version = "1.1.1", optional = true }
-supports-unicode = { version = "1.0.0", optional = true }
-backtrace = { version = "0.3.61", optional = true }
-terminal_size = { version = "0.1.17", optional = true }
+owo-colors = { version = "4.0.0", optional = true }
+textwrap = { version = "0.16.0", default-features = false, features = ["unicode-linebreak", "unicode-width"], optional = true }
+supports-hyperlinks = { version = "3.0.0", optional = true }
+supports-color = { version = "3.0.0", optional = true }
+supports-unicode = { version = "3.0.0", optional = true }
+backtrace = { version = "0.3.69", optional = true }
+terminal_size = { version = "0.4.0", optional = true }
+backtrace-ext = { version = "0.2.1", optional = true }
+serde = { version = "1.0.196", features = ["derive"], optional = true }
+syntect = { version = "5.1.0", optional = true }
 
 [dev-dependencies]
-semver = "1.0.4"
+thiserror = "2.0.11"
+semver = "1.0.21"
 
 # Eyre devdeps
 futures = { version = "0.3", default-features = false }
-indenter = "0.3.0"
+indenter = "0.3.3"
 rustversion = "1.0"
-trybuild = { version = "1.0.19", features = ["diff"] }
-syn = { version = "1.0", features = ["full"] }
-regex = "1.5"
-lazy_static = "1.4"
+trybuild = { version = "1.0.89", features = ["diff"] }
+syn = { version = "2.0.87", features = ["full"] }
+regex = "1.10"
+
+serde = { version = "1.0.196", features = ["derive"] }
+serde_json = "1.0.113"
+strip-ansi-escapes = "0.2.0"
 
 [features]
-default = []
+default = ["derive"]
+derive = ["dep:miette-derive"]
+no-format-args-capture = []
+fancy-base = [
+    "dep:owo-colors",
+    "dep:textwrap",
+]
+fancy-no-syscall = [
+    "fancy-base",
+]
 fancy-no-backtrace = [
-    "owo-colors",
-    "atty",
-    "textwrap",
-    "terminal_size",
-    "supports-hyperlinks",
-    "supports-color",
-    "supports-unicode",
-]
-fancy = [
-    "fancy-no-backtrace",
-    "backtrace",
+    "fancy-base",
+    "dep:terminal_size",
+    "dep:supports-hyperlinks",
+    "dep:supports-color",
+    "dep:supports-unicode",
 ]
+fancy = ["fancy-no-backtrace", "dep:backtrace", "dep:backtrace-ext"]
+syntect-highlighter = ["fancy-no-backtrace", "dep:syntect"]
 
 [workspace]
 members = ["miette-derive"]
 
 [package.metadata.docs.rs]
 all-features = true
+
+[[example]]
+name = "serde_json"
+required-features = ["fancy"]

LICENSE

@@ -1,229 +1,202 @@
-Apache License
 
-Version 2.0, January 2004
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-http://www.apache.org/licenses/ TERMS
-AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
    1. Definitions.
 
-     
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
 
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
 
-      "License" shall mean the terms and conditions for use, reproduction, and
-distribution as defined by Sections 1 through 9 of this document.
-
-      
-
-     
-"Licensor" shall mean the copyright owner or entity authorized by the copyright
-owner that is granting the License.
-
-      
-
-      "Legal Entity" shall mean the
-union of the acting entity and all other entities that control, are controlled
-by, or are under common control with that entity. For the purposes of this
-definition, "control" means (i) the power, direct or indirect, to cause the
-direction or management of such entity, whether by contract or otherwise, or (ii)
-ownership of fifty percent (50%) or more of the outstanding shares, or (iii)
-beneficial ownership of such entity.
-
-      
-
-      "You" (or "Your") shall mean
-an individual or Legal Entity exercising permissions granted by this License.
-
-  
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
 
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
 
       "Source" form shall mean the preferred form for making modifications,
-including but not limited to software source code, documentation source, and
-configuration files.
+      including but not limited to software source code, documentation
+      source, and configuration files.
 
-      
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
 
-      "Object" form shall mean any form resulting
-from mechanical transformation or translation of a Source form, including but not
-limited to compiled object code, generated documentation, and conversions to
-other media types.
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
 
-      
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
 
-      "Work" shall mean the work of authorship,
-whether in Source or Object form, made available under the License, as indicated
-by a copyright notice that is included in or attached to the work (an example is
-provided in the Appendix below).
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
 
-      
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
 
-      "Derivative Works" shall mean any
-work, whether in Source or Object form, that is based on (or derived from) the
-Work and for which the editorial revisions, annotations, elaborations, or other
-modifications represent, as a whole, an original work of authorship. For the
-purposes of this License, Derivative Works shall not include works that remain
-separable from, or merely link (or bind by name) to the interfaces of, the Work
-and Derivative Works thereof.
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
 
-      
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
 
-      "Contribution" shall mean any work
-of authorship, including the original version of the Work and any modifications
-or additions to that Work or Derivative Works thereof, that is intentionally
-submitted to Licensor for inclusion in the Work by the copyright owner or by an
-individual or Legal Entity authorized to submit on behalf of the copyright owner.
-For the purposes of this definition, "submitted" means any form of electronic,
-verbal, or written communication sent to the Licensor or its representatives,
-including but not limited to communication on electronic mailing lists, source
-code control systems, and issue tracking systems that are managed by, or on
-behalf of, the Licensor for the purpose of discussing and improving the Work, but
-excluding communication that is conspicuously marked or otherwise designated in
-writing by the copyright owner as "Not a Contribution."
-
-      
-
-     
-"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of
-whom a Contribution has been received by Licensor and subsequently incorporated
-within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and
-conditions of this License, each Contributor hereby grants to You a perpetual,
-worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license
-to reproduce, prepare Derivative Works of, publicly display, publicly perform,
-sublicense, and distribute the Work and such Derivative Works in Source or Object
-form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of this
-License, each Contributor hereby grants to You a perpetual, worldwide,
-non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
-section) patent license to make, have made, use, offer to sell, sell, import, and
-otherwise transfer the Work, where such license applies only to those patent
-claims licensable by such Contributor that are necessarily infringed by their
-Contribution(s) alone or by combination of their Contribution(s) with the Work to
-which such Contribution(s) was submitted. If You institute patent litigation
-against any entity (including a cross-claim or counterclaim in a lawsuit)
-alleging that the Work or a Contribution incorporated within the Work constitutes
-direct or contributory patent infringement, then any patent licenses granted to
-You under this License for that Work shall terminate as of the date such
-litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute
-copies of the Work or Derivative Works thereof in any medium, with or without
-modifications, and in Source or Object form, provided that You meet the following
-conditions:
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
 
       (a) You must give any other recipients of the Work or
-Derivative Works a copy of this License; and
+          Derivative Works a copy of this License; and
 
-      (b) You must cause any
-modified files to carry prominent notices stating that You changed the files;
-and
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
 
-      (c) You must retain, in the Source form of any Derivative Works that
-You distribute, all copyright, patent, trademark, and attribution notices from
-the Source form of the Work, excluding those notices that do not pertain to any
-part of the Derivative Works; and
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
 
-      (d) If the Work includes a "NOTICE" text
-file as part of its distribution, then any Derivative Works that You distribute
-must include a readable copy of the attribution notices contained within such
-NOTICE file, excluding those notices that do not pertain to any part of the
-Derivative Works, in at least one of the following places: within a NOTICE text
-file distributed as part of the Derivative Works; within the Source form or
-documentation, if provided along with the Derivative Works; or, within a display
-generated by the Derivative Works, if and wherever such third-party notices
-normally appear. The contents of the NOTICE file are for informational purposes
-only and do not modify the License. You may add Your own attribution notices
-within Derivative Works that You distribute, alongside or as an addendum to the
-NOTICE text from the Work, provided that such additional attribution notices
-cannot be construed as modifying the License.
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
 
-      You may add Your own
-copyright statement to Your modifications and may provide additional or different
-license terms and conditions for use, reproduction, or distribution of Your
-modifications, or for any such Derivative Works as a whole, provided Your use,
-reproduction, and distribution of the Work otherwise complies with the conditions
-stated in this License.
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
 
-   5. Submission of Contributions. Unless You explicitly
-state otherwise, any Contribution intentionally submitted for inclusion in the
-Work by You to the Licensor shall be under the terms and conditions of this
-License, without any additional terms or conditions. Notwithstanding the above,
-nothing herein shall supersede or modify the terms of any separate license
-agreement you may have executed with Licensor regarding such Contributions.
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
 
-  
-6. Trademarks. This License does not grant permission to use the trade names,
-trademarks, service marks, or product names of the Licensor, except as required
-for reasonable and customary use in describing the origin of the Work and
-reproducing the content of the NOTICE file.
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
 
-   7. Disclaimer of Warranty. Unless
-required by applicable law or agreed to in writing, Licensor provides the Work
-(and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT
-WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including,
-without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
-MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible
-for determining the appropriateness of using or redistributing the Work and
-assume any risks associated with Your exercise of permissions under this
-License.
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
 
    8. Limitation of Liability. In no event and under no legal theory,
-whether in tort (including negligence), contract, or otherwise, unless required
-by applicable law (such as deliberate and grossly negligent acts) or agreed to in
-writing, shall any Contributor be liable to You for damages, including any
-direct, indirect, special, incidental, or consequential damages of any character
-arising as a result of this License or out of the use or inability to use the
-Work (including but not limited to damages for loss of goodwill, work stoppage,
-computer failure or malfunction, or any and all other commercial damages or
-losses), even if such Contributor has been advised of the possibility of such
-damages.
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
 
    9. Accepting Warranty or Additional Liability. While redistributing
-the Work or Derivative Works thereof, You may choose to offer, and charge a fee
-for, acceptance of support, warranty, indemnity, or other liability obligations
-and/or rights consistent with this License. However, in accepting such
-obligations, You may act only on Your own behalf and on Your sole responsibility,
-not on behalf of any other Contributor, and only if You agree to indemnify,
-defend, and hold each Contributor harmless for any liability incurred by, or
-claims asserted against, such Contributor by reason of your accepting any such
-warranty or additional liability. END OF TERMS AND CONDITIONS
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
 
-APPENDIX: How to
-apply the Apache License to your work.
+   END OF TERMS AND CONDITIONS
 
-To apply the Apache License to your work,
-attach the following boilerplate notice, with the fields enclosed by brackets
-"[]" replaced with your own identifying information. (Don't include the
-brackets!) The text should be enclosed in the appropriate comment syntax for the
-file format. We also recommend that a file or class name and description of
-purpose be included on the same "printed page" as the copyright notice for easier
-identification within third-party archives.
+   APPENDIX: How to apply the Apache License to your work.
 
-Copyright [yyyy] Kat
-Marchán
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
 
-Licensed under the Apache License, Version 2.0 (the "License");
+   Copyright [yyyy] [name of copyright owner]
 
-you may
-not use this file except in compliance with the License.
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
 
-You may obtain a copy
-of the License at
+       http://www.apache.org/licenses/LICENSE-2.0
 
-http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by
-applicable law or agreed to in writing, software
-
-distributed under the License
-is distributed on an "AS IS" BASIS,
-
-WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied.
-
-See the License for the specific language
-governing permissions and
-
-limitations under the License.
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -28,9 +28,9 @@ diagnostic error code: ruget::api::bad_json
 " />
 
 > **NOTE: You must enable the `"fancy"` crate feature to get fancy report
-output like in the screenshots above.** You should only do this in your
-toplevel crate, as the fancy feature pulls in a number of dependencies that
-libraries and such might not want.
+> output like in the screenshots above.** You should only do this in your
+> toplevel crate, as the fancy feature pulls in a number of dependencies that
+> libraries and such might not want.
 
 ### Table of Contents <!-- omit in toc -->
 
@@ -44,9 +44,15 @@ libraries and such might not want.
   - [... in `main()`](#-in-main)
   - [... diagnostic code URLs](#-diagnostic-code-urls)
   - [... snippets](#-snippets)
+  - [... help text](#-help-text)
+  - [... severity level](#-severity-level)
   - [... multiple related errors](#-multiple-related-errors)
   - [... delayed source code](#-delayed-source-code)
   - [... handler options](#-handler-options)
+  - [... dynamic diagnostics](#-dynamic-diagnostics)
+  - [... syntax highlighting](#-syntax-highlighting)
+  - [... primary label](#-primary-label)
+  - [... collection of labels](#-collection-of-labels)
 - [Acknowledgements](#acknowledgements)
 - [License](#license)
 
@@ -95,7 +101,7 @@ You can derive a `Diagnostic` from any `std::error::Error` type.
 
 `thiserror` is a great way to define them, and plays nicely with `miette`!
 */
-use miette::{Diagnostic, SourceSpan};
+use miette::{Diagnostic, NamedSource, SourceSpan};
 use thiserror::Error;
 
 #[derive(Error, Debug, Diagnostic)]
@@ -109,7 +115,7 @@ struct MyBad {
     // The Source that we're gonna be printing snippets out of.
     // This can be a String if you don't have or care about file names.
     #[source_code]
-    src: NamedSource,
+    src: NamedSource<String>,
     // Snippets and highlights can be included in the diagnostic!
     #[label("This bit here")]
     bad_bit: SourceSpan,
@@ -122,12 +128,11 @@ Use this `Result` type (or its expanded version) as the return type
 throughout your app (but NOT your libraries! Those should always return
 concrete types!).
 */
-use miette::{NamedSource, Result};
+use miette::Result;
 fn this_fails() -> Result<()> {
     // You can use plain strings as a `Source`, or anything that implements
     // the one-method `Source` trait.
     let src = "source\n  text\n    here".to_string();
-    let len = src.len();
 
     Err(MyBad {
         src: NamedSource::new("bad_file.rs", src),
@@ -157,17 +162,20 @@ And this is the output you'll get if you run this program:
 <img src="https://raw.githubusercontent.com/zkat/miette/main/images/single-line-example.png" alt="
 Narratable printout:
 \
-Error: Types mismatched for operation.
-    Diagnostic severity: error
-Begin snippet starting at line 1, column 1
+diagnostic error code: oops::my::bad (link)
+Error: oops!
 \
-snippet line 1: 3 + &quot;5&quot;
-    label starting at line 1, column 1: int
-    label starting at line 1, column 1: doesn't support these values.
-    label starting at line 1, column 1: string
-diagnostic help: Change int or string to be the right types and try again.
-diagnostic code: nu::parser::unsupported_operation
-For more details, see https://docs.rs/nu-parser/0.1.0/nu-parser/enum.ParseError.html#variant.UnsupportedOperation">
+Begin snippet for bad_file.rs starting
+at line 2, column 3
+\
+snippet line 1: source
+\
+snippet line 2:  text
+    highlight starting at line 1, column 3: This bit here
+\
+snippet line 3: here
+\
+diagnostic help: try doing it better next time?">
 
 ### Using
 
@@ -186,7 +194,7 @@ the trait directly, just like with `std::error::Error`.
 
 ```rust
 // lib/error.rs
-use miette::Diagnostic;
+use miette::{Diagnostic, SourceSpan};
 use thiserror::Error;
 
 #[derive(Error, Diagnostic, Debug)]
@@ -198,6 +206,29 @@ pub enum MyLibError {
     #[error("Oops it blew up")]
     #[diagnostic(code(my_lib::bad_code))]
     BadThingHappened,
+
+    #[error(transparent)]
+    // Use `#[diagnostic(transparent)]` to wrap another [`Diagnostic`]. You won't see labels otherwise
+    #[diagnostic(transparent)]
+    AnotherError(#[from] AnotherError),
+
+    /// Forward the diagnostic to a particular field.
+    #[error("other error")]
+    #[diagnostic(forward(the_actual_diagnostic))]
+    EvenMoreData {
+        unrelated_field_1: String,
+        unrelated_field_2: usize,
+
+        #[source]
+        the_actual_diagnostic: AnotherError,
+    }
+}
+
+#[derive(Error, Diagnostic, Debug)]
+#[error("another error")]
+pub struct AnotherError {
+   #[label("here")]
+   pub at: SourceSpan
 }
 ```
 
@@ -225,7 +256,7 @@ use miette::{IntoDiagnostic, Result};
 use semver::Version;
 
 pub fn some_tool() -> Result<Version> {
-    Ok("1.2.x".parse().into_diagnostic()?)
+    "1.2.x".parse().into_diagnostic()
 }
 ```
 
@@ -240,13 +271,28 @@ use miette::{IntoDiagnostic, Result, WrapErr};
 use semver::Version;
 
 pub fn some_tool() -> Result<Version> {
-    Ok("1.2.x"
+    "1.2.x"
         .parse()
         .into_diagnostic()
-        .wrap_err("Parsing this tool's semver version failed.")?)
+        .wrap_err("Parsing this tool's semver version failed.")
 }
 ```
 
+To construct your own simple adhoc error use the [`miette!`] macro:
+```rust
+// my_app/lib/my_internal_file.rs
+use miette::{miette, Result};
+use semver::Version;
+
+pub fn some_tool() -> Result<Version> {
+    let version = "1.2.x";
+    version
+        .parse()
+        .map_err(|_| miette!("Invalid version {}", version))
+}
+```
+There are also similar [bail!] and [ensure!] macros.
+
 #### ... in `main()`
 
 `main()` is just like any other part of your application-internal code. Use
@@ -254,9 +300,9 @@ pub fn some_tool() -> Result<Version> {
 automatically.
 
 > **NOTE:** You must enable the `"fancy"` crate feature to get fancy report
-output like in the screenshots here.** You should only do this in your
-toplevel crate, as the fancy feature pulls in a number of dependencies that
-libraries and such might not want.
+> output like in the screenshots here.** You should only do this in your
+> toplevel crate, as the fancy feature pulls in a number of dependencies that
+> libraries and such might not want.
 
 ```rust
 use miette::{IntoDiagnostic, Result};
@@ -277,6 +323,23 @@ enabled:
 miette = { version = "X.Y.Z", features = ["fancy"] }
 ```
 
+Another way to display a diagnostic is by printing them using the debug formatter.
+This is, in fact, what returning diagnostics from main ends up doing.
+To do it yourself, you can write the following:
+
+```rust
+use miette::{IntoDiagnostic, Result};
+use semver::Version;
+
+fn just_a_random_function() {
+    let version_result: Result<Version> = "1.2.x".parse().into_diagnostic();
+    match version_result {
+        Err(e) => println!("{:?}", e),
+        Ok(version) => println!("{}", version),
+    }
+}
+```
+
 #### ... diagnostic code URLs
 
 `miette` supports providing a URL for individual diagnostics. This URL will
@@ -378,7 +441,7 @@ pub struct MyErrorType {
 }
 ```
 
-##### ... help text
+#### ... help text
 `miette` provides two facilities for supplying help text for your errors:
 
 The first is the `#[help()]` format attribute that applies to structs or
@@ -414,6 +477,19 @@ let err = Foo {
 };
 ```
 
+#### ... severity level
+`miette` provides a way to set the severity level of a diagnostic.
+
+```rust
+use miette::Diagnostic;
+use thiserror::Error;
+
+#[derive(Debug, Diagnostic, Error)]
+#[error("welp")]
+#[diagnostic(severity(Warning))]
+struct Foo;
+```
+
 #### ... multiple related errors
 
 `miette` supports collecting multiple errors into a single diagnostic, and
@@ -566,6 +642,7 @@ miette::set_hook(Box::new(|_| {
             .unicode(false)
             .context_lines(3)
             .tab_width(4)
+            .break_words(true)
             .build(),
     )
 }))
@@ -575,20 +652,154 @@ miette::set_hook(Box::new(|_| {
 See the docs for [`MietteHandlerOpts`] for more details on what you can
 customize!
 
+#### ... dynamic diagnostics
+
+If you...
+- ...don't know all the possible errors upfront
+- ...need to serialize/deserialize errors
+  then you may want to use [`miette!`], [`diagnostic!`] macros or
+  [`MietteDiagnostic`] directly to create diagnostic on the fly.
+
+```rust
+
+let source = "2 + 2 * 2 = 8".to_string();
+let report = miette!(
+  labels = vec![
+      LabeledSpan::at(12..13, "this should be 6"),
+  ],
+  help = "'*' has greater precedence than '+'",
+  "Wrong answer"
+).with_source_code(source);
+println!("{:?}", report)
+```
+
+#### ... syntax highlighting
+
+`miette` can be configured to highlight syntax in source code snippets.
+
+<!-- TODO: screenshot goes here once default Theme is decided -->
+
+To use the built-in highlighting functionality, you must enable the
+`syntect-highlighter` crate feature. When this feature is enabled, `miette` will
+automatically use the [`syntect`] crate to highlight the `#[source_code]`
+field of your [`Diagnostic`].
+
+Syntax detection with [`syntect`] is handled by checking 2 methods on the [`SpanContents`] trait, in order:
+* [`language()`](SpanContents::language) - Provides the name of the language
+  as a string. For example `"Rust"` will indicate Rust syntax highlighting.
+  You can set the language of the [`SpanContents`] produced by a
+  [`NamedSource`] via the [`with_language`](NamedSource::with_language)
+  method.
+* [`name()`](SpanContents::name) - In the absence of an explicitly set
+  language, the name is assumed to contain a file name or file path.
+  The highlighter will check for a file extension at the end of the name and
+  try to guess the syntax from that.
+
+If you want to use a custom highlighter, you can provide a custom
+implementation of the [`Highlighter`](highlighters::Highlighter)
+trait to [`MietteHandlerOpts`] by calling the
+[`with_syntax_highlighting`](MietteHandlerOpts::with_syntax_highlighting)
+method. See the [`highlighters`] module docs for more details.
+
+#### ... primary label
+
+You can use the `primary` parameter to `label` to indicate that the label
+is the primary label.
+
+```rust
+#[derive(Debug, Diagnostic, Error)]
+#[error("oops!")]
+struct MyError {
+    #[label(primary, "main issue")]
+    primary_span: SourceSpan,
+
+    #[label("other label")]
+    other_span: SourceSpan,
+}
+```
+
+The `primary` parameter can be used at most once:
+
+```rust
+#[derive(Debug, Diagnostic, Error)]
+#[error("oops!")]
+struct MyError {
+    #[label(primary, "main issue")]
+    primary_span: SourceSpan,
+
+    #[label(primary, "other label")] // Error: Cannot have more than one primary label.
+    other_span: SourceSpan,
+}
+```
+
+#### ... collection of labels
+
+When the number of labels is unknown, you can use a collection of `SourceSpan`
+(or any type convertible into `SourceSpan`). For this, add the `collection`
+parameter to `label` and use any type than can be iterated over for the field.
+
+```rust
+#[derive(Debug, Diagnostic, Error)]
+#[error("oops!")]
+struct MyError {
+    #[label("main issue")]
+    primary_span: SourceSpan,
+
+    #[label(collection, "related to this")]
+    other_spans: Vec<Range<usize>>,
+}
+
+let report: miette::Report = MyError {
+    primary_span: (6, 9).into(),
+    other_spans: vec![19..26, 30..41],
+}.into();
+
+println!("{:?}", report.with_source_code("About something or another or yet another ...".to_string()));
+```
+
+A collection can also be of `LabeledSpan` if you want to have different text
+for different labels. Labels with no text will use the one from the `label`
+attribute
+
+```rust
+#[derive(Debug, Diagnostic, Error)]
+#[error("oops!")]
+struct MyError {
+    #[label("main issue")]
+    primary_span: SourceSpan,
+
+    #[label(collection, "related to this")]
+    other_spans: Vec<LabeledSpan>, // LabeledSpan
+}
+
+let report: miette::Report = MyError {
+    primary_span: (6, 9).into(),
+    other_spans: vec![
+        LabeledSpan::new(None, 19, 7), // Use default text `related to this`
+        LabeledSpan::new(Some("and also this".to_string()), 30, 11), // Use specific text
+    ],
+}.into();
+
+println!("{:?}", report.with_source_code("About something or another or yet another ...".to_string()));
+```
+
+### MSRV
+
+This crate requires rustc 1.82.0 or later.
+
 ### Acknowledgements
 
 `miette` was not developed in a void. It owes enormous credit to various
 other projects and their authors:
 
-- [`anyhow`](http://crates.io/crates/anyhow) and
-  [`color-eyre`](https://crates.io/crates/color-eyre): these two
-  enormously influential error handling libraries have pushed forward the
-  experience of application-level error handling and error reporting.
-  `miette`'s `Report` type is an attempt at a very very rough version of
-  their `Report` types.
-- [`thiserror`](https://crates.io/crates/thiserror) for setting the
-  standard for library-level error definitions, and for being the
-  inspiration behind `miette`'s derive macro.
+- [`anyhow`](http://crates.io/crates/anyhow) and [`color-eyre`](https://crates.io/crates/color-eyre):
+  these two enormously influential error handling libraries have pushed
+  forward the experience of application-level error handling and error
+  reporting. `miette`'s `Report` type is an attempt at a very very rough
+  version of their `Report` types.
+- [`thiserror`](https://crates.io/crates/thiserror) for setting the standard
+  for library-level error definitions, and for being the inspiration behind
+  `miette`'s derive macro.
 - `rustc` and [@estebank](https://github.com/estebank) for their
   state-of-the-art work in compiler diagnostics.
 - [`ariadne`](https://crates.io/crates/ariadne) for pushing forward how
@@ -605,13 +816,15 @@ under the Apache License. Some code is taken from
 [`ariadne`](https://github.com/zesterer/ariadne), which is MIT licensed.
 
 [`miette!`]: https://docs.rs/miette/latest/miette/macro.miette.html
+[`diagnostic!`]: https://docs.rs/miette/latest/miette/macro.diagnostic.html
 [`std::error::Error`]: https://doc.rust-lang.org/nightly/std/error/trait.Error.html
 [`Diagnostic`]: https://docs.rs/miette/latest/miette/trait.Diagnostic.html
 [`IntoDiagnostic`]: https://docs.rs/miette/latest/miette/trait.IntoDiagnostic.html
 [`MietteHandlerOpts`]: https://docs.rs/miette/latest/miette/struct.MietteHandlerOpts.html
 [`MietteHandler`]: https://docs.rs/miette/latest/miette/struct.MietteHandler.html
+[`MietteDiagnostic`]: https://docs.rs/miette/latest/miette/struct.MietteDiagnostic.html
 [`Report`]: https://docs.rs/miette/latest/miette/struct.Report.html
-[`ReportHandler`]: https://docs.rs/miette/latest/miette/struct.ReportHandler.html
+[`ReportHandler`]: https://docs.rs/miette/latest/miette/trait.ReportHandler.html
 [`Result`]: https://docs.rs/miette/latest/miette/type.Result.html
-[`SourceCode`]: https://docs.rs/miette/latest/miette/struct.SourceCode.html
+[`SourceCode`]: https://docs.rs/miette/latest/miette/trait.SourceCode.html
 [`SourceSpan`]: https://docs.rs/miette/latest/miette/struct.SourceSpan.html

README.tpl

@@ -4,13 +4,15 @@
 {{readme}}
 
 [`miette!`]: https://docs.rs/miette/latest/miette/macro.miette.html
+[`diagnostic!`]: https://docs.rs/miette/latest/miette/macro.diagnostic.html
 [`std::error::Error`]: https://doc.rust-lang.org/nightly/std/error/trait.Error.html
-[`Diagnostic`]: https://docs.rs/miette/latest/miette/struct.Diagnostic.html
+[`Diagnostic`]: https://docs.rs/miette/latest/miette/trait.Diagnostic.html
 [`IntoDiagnostic`]: https://docs.rs/miette/latest/miette/trait.IntoDiagnostic.html
 [`MietteHandlerOpts`]: https://docs.rs/miette/latest/miette/struct.MietteHandlerOpts.html
 [`MietteHandler`]: https://docs.rs/miette/latest/miette/struct.MietteHandler.html
+[`MietteDiagnostic`]: https://docs.rs/miette/latest/miette/struct.MietteDiagnostic.html
 [`Report`]: https://docs.rs/miette/latest/miette/struct.Report.html
-[`ReportHandler`]: https://docs.rs/miette/latest/miette/struct.ReportHandler.html
+[`ReportHandler`]: https://docs.rs/miette/latest/miette/trait.ReportHandler.html
 [`Result`]: https://docs.rs/miette/latest/miette/type.Result.html
-[`SourceCode`]: https://docs.rs/miette/latest/miette/struct.SourceCode.html
+[`SourceCode`]: https://docs.rs/miette/latest/miette/trait.SourceCode.html
 [`SourceSpan`]: https://docs.rs/miette/latest/miette/struct.SourceSpan.html

clippy.toml

@@ -0,0 +1 @@
+msrv = "1.82.0"

examples/serde_json.rs

@@ -0,0 +1,48 @@
+//! This example shows how to integrate miette with serde_json
+//! so the decoding source will be annotated with the decoding error,
+//! providing contextual information about the error.
+
+use miette::{IntoDiagnostic, SourceOffset};
+use serde_json::{self, json};
+
+#[derive(Debug, serde::Deserialize)]
+struct Library {
+    #[allow(unused)]
+    name: String,
+}
+
+#[derive(Debug, thiserror::Error, miette::Diagnostic)]
+#[error("malformed json provided")]
+struct SerdeError {
+    cause: serde_json::Error,
+    #[source_code]
+    input: String,
+    #[label("{cause}")]
+    location: SourceOffset,
+}
+
+impl SerdeError {
+    /// Takes the input and the `serde_json::Error` and returns a SerdeError
+    /// that can be rendered nicely with miette.
+    pub fn from_serde_error(input: impl Into<String>, cause: serde_json::Error) -> Self {
+        let input = input.into();
+        let location = SourceOffset::from_location(&input, cause.line(), cause.column());
+        Self {
+            cause,
+            input,
+            location,
+        }
+    }
+}
+
+fn main() -> miette::Result<()> {
+    let input = serde_json::to_string_pretty(&json!({
+        "name": 123
+    }))
+    .into_diagnostic()?;
+
+    let _library: Library =
+        serde_json::from_str(&input).map_err(|cause| SerdeError::from_serde_error(input, cause))?;
+
+    Ok(())
+}

miette-derive/Cargo.toml

@@ -1,16 +1,16 @@
 [package]
 name = "miette-derive"
-version = "5.4.1"
+version = "7.6.0"
 authors = ["Kat Marchán <kzm@zkat.tech>"]
 edition = "2018"
 license = "Apache-2.0"
 description = "Derive macros for miette. Like `thiserror` for Diagnostics."
 repository = "https://github.com/zkat/miette"
-
+
 [lib]
 proc-macro = true
-
+
 [dependencies]
-proc-macro2 = "1.0"
-quote = "1.0"
-syn = "1.0.45"
+proc-macro2 = "1.0.83"
+quote = "1.0.35"
+syn = "2.0.87"

miette-derive/src/code.rs

@@ -72,7 +72,7 @@ impl Code {
     pub(crate) fn gen_struct(&self) -> Option<TokenStream> {
         let code = &self.0;
         Some(quote! {
-            fn code<'a>(&'a self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + 'a>> {
+            fn code(&self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + '_>> {
                 std::option::Option::Some(std::boxed::Box::new(#code))
             }
         })

miette-derive/src/diagnostic.rs

@@ -222,7 +222,7 @@ impl Diagnostic {
         let input_attrs = input
             .attrs
             .iter()
-            .filter(|x| x.path.is_ident("diagnostic"))
+            .filter(|x| x.path().is_ident("diagnostic"))
             .collect::<Vec<&syn::Attribute>>();
         Ok(match input.data {
             syn::Data::Struct(data_struct) => {
@@ -245,7 +245,7 @@ impl Diagnostic {
                 for var in variants {
                     let mut variant_attrs = input_attrs.clone();
                     variant_attrs
-                        .extend(var.attrs.iter().filter(|x| x.path.is_ident("diagnostic")));
+                        .extend(var.attrs.iter().filter(|x| x.path().is_ident("diagnostic")));
                     let args =
                         DiagnosticDefArgs::parse(&var.ident, &var.fields, &variant_attrs, true)?;
                     vars.push(DiagnosticDef {

miette-derive/src/diagnostic_source.rs

@@ -24,7 +24,7 @@ impl DiagnosticSource {
     fn from_fields_vec(fields: Vec<&syn::Field>) -> syn::Result<Option<Self>> {
         for (i, field) in fields.iter().enumerate() {
             for attr in &field.attrs {
-                if attr.path.is_ident("diagnostic_source") {
+                if attr.path().is_ident("diagnostic_source") {
                     let diagnostic_source = if let Some(ident) = field.ident.clone() {
                         syn::Member::Named(ident)
                     } else {

miette-derive/src/fmt.rs

@@ -210,21 +210,21 @@ pub fn parse_token_expr(input: ParseStream, mut begin_expr: bool) -> Result<Toke
             let delimiter = parenthesized!(content in input);
             let nested = parse_token_expr(&content, true)?;
             let mut group = Group::new(Delimiter::Parenthesis, nested);
-            group.set_span(delimiter.span);
+            group.set_span(delimiter.span.join());
             TokenTree::Group(group)
         } else if input.peek(syn::token::Brace) {
             let content;
             let delimiter = braced!(content in input);
             let nested = parse_token_expr(&content, true)?;
             let mut group = Group::new(Delimiter::Brace, nested);
-            group.set_span(delimiter.span);
+            group.set_span(delimiter.span.join());
             TokenTree::Group(group)
         } else if input.peek(syn::token::Bracket) {
             let content;
             let delimiter = bracketed!(content in input);
             let nested = parse_token_expr(&content, true)?;
             let mut group = Group::new(Delimiter::Bracket, nested);
-            group.set_span(delimiter.span);
+            group.set_span(delimiter.span.join());
             TokenTree::Group(group)
         } else {
             input.parse()?

miette-derive/src/forward.rs

@@ -58,13 +58,13 @@ impl WhichFn {
     pub fn signature(&self) -> TokenStream {
         match self {
             Self::Code => quote! {
-                fn code<'a>(&'a self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + 'a>>
+                fn code(& self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + '_>>
             },
             Self::Help => quote! {
-                fn help<'a>(&'a self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + 'a>>
+                fn help(& self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + '_>>
             },
             Self::Url => quote! {
-                fn url<'a>(&'a self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + 'a>>
+                fn url(& self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + '_>>
             },
             Self::Severity => quote! {
                 fn severity(&self) -> std::option::Option<miette::Severity>
@@ -150,7 +150,7 @@ impl Forward {
                 Self::#variant { #field_name, .. } => #field_name.#method_call,
             },
             Forward::Unnamed(index) => {
-                let underscores: Vec<_> = core::iter::repeat(quote! { _, }).take(*index).collect();
+                let underscores: Vec<_> = std::iter::repeat_n(quote! { _, }, *index).collect();
                 let unnamed = format_ident!("unnamed");
                 quote! {
                     Self::#variant ( #(#underscores)* #unnamed, .. ) => #unnamed.#method_call,

miette-derive/src/help.rs

@@ -69,7 +69,7 @@ impl Help {
     fn from_fields_vec(fields: Vec<&syn::Field>) -> syn::Result<Option<Self>> {
         for (i, field) in fields.iter().enumerate() {
             for attr in &field.attrs {
-                if attr.path.is_ident("help") {
+                if attr.path().is_ident("help") {
                     let help = if let Some(ident) = field.ident.clone() {
                         syn::Member::Named(ident)
                     } else {
@@ -108,7 +108,7 @@ impl Help {
                         Some(quote! {
                             Self::#ident #display_pat => {
                                 use miette::macro_helpers::ToOption;
-                                miette::macro_helpers::OptionalWrapper::<#ty>::new().to_option(&#help).as_ref().map(|#var| -> std::boxed::Box<dyn std::fmt::Display + 'a> { std::boxed::Box::new(format!("{}", #var)) })
+                                miette::macro_helpers::OptionalWrapper::<#ty>::new().to_option(&#help).as_ref().map(|#var| -> std::boxed::Box<dyn std::fmt::Display + '_> { std::boxed::Box::new(format!("{}", #var)) })
                             },
                         })
                     }
@@ -123,7 +123,7 @@ impl Help {
             Help::Display(display) => {
                 let (fmt, args) = display.expand_shorthand_cloned(&display_members);
                 Some(quote! {
-                    fn help<'a>(&'a self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + 'a>> {
+                    fn help(&self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + '_>> {
                         #[allow(unused_variables, deprecated)]
                         let Self #display_pat = self;
                         std::option::Option::Some(std::boxed::Box::new(format!(#fmt #args)))
@@ -133,11 +133,11 @@ impl Help {
             Help::Field(member, ty) => {
                 let var = quote! { __miette_internal_var };
                 Some(quote! {
-                    fn help<'a>(&'a self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + 'a>> {
+                    fn help(&self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + '_>> {
                         #[allow(unused_variables, deprecated)]
                         let Self #display_pat = self;
                         use miette::macro_helpers::ToOption;
-                        miette::macro_helpers::OptionalWrapper::<#ty>::new().to_option(&self.#member).as_ref().map(|#var| -> std::boxed::Box<dyn std::fmt::Display + 'a> { std::boxed::Box::new(format!("{}", #var)) })
+                        miette::macro_helpers::OptionalWrapper::<#ty>::new().to_option(&self.#member).as_ref().map(|#var| -> std::boxed::Box<dyn std::fmt::Display + '_> { std::boxed::Box::new(format!("{}", #var)) })
                     }
                 })
             }

miette-derive/src/label.rs

@@ -16,23 +16,59 @@ use crate::{
 
 pub struct Labels(Vec<Label>);
 
+#[derive(PartialEq, Eq)]
+enum LabelType {
+    Default,
+    Primary,
+    Collection,
+}
+
 struct Label {
     label: Option<Display>,
     ty: syn::Type,
     span: syn::Member,
+    lbl_ty: LabelType,
 }
 
 struct LabelAttr {
     label: Option<Display>,
+    lbl_ty: LabelType,
 }
 
 impl Parse for LabelAttr {
     fn parse(input: ParseStream) -> syn::Result<Self> {
+        // Skip a token.
+        // This should receive one of:
+        // - label = "..."
+        // - label("...")
+        let _ = input.step(|cursor| {
+            if let Some((_, next)) = cursor.token_tree() {
+                Ok(((), next))
+            } else {
+                Err(cursor.error("unexpected empty attribute"))
+            }
+        });
         let la = input.lookahead1();
-        let label = if la.peek(syn::token::Paren) {
-            // #[label("{}", x)]
+        let (lbl_ty, label) = if la.peek(syn::token::Paren) {
+            // #[label(primary?, "{}", x)]
             let content;
             parenthesized!(content in input);
+
+            let attr = match content.parse::<Option<syn::Ident>>()? {
+                Some(ident) if ident == "primary" => {
+                    let _ = content.parse::<Token![,]>();
+                    LabelType::Primary
+                }
+                Some(ident) if ident == "collection" => {
+                    let _ = content.parse::<Token![,]>();
+                    LabelType::Collection
+                }
+                Some(_) => {
+                    return Err(syn::Error::new(input.span(), "Invalid argument to label() attribute. The argument must be a literal string or either the keyword `primary` or `collection`."));
+                }
+                _ => LabelType::Default,
+            };
+
             if content.peek(syn::LitStr) {
                 let fmt = content.parse()?;
                 let args = if content.is_empty() {
@@ -45,22 +81,27 @@ impl Parse for LabelAttr {
                     args,
                     has_bonus_display: false,
                 };
-                Some(display)
+                (attr, Some(display))
+            } else if !content.is_empty() {
+                return Err(syn::Error::new(input.span(), "Invalid argument to label() attribute. The argument must be a literal string or either the keyword `primary` or `collection`."));
             } else {
-                return Err(syn::Error::new(input.span(), "Invalid argument to label() attribute. The first argument must be a literal string."));
+                (attr, None)
             }
         } else if la.peek(Token![=]) {
             // #[label = "blabla"]
             input.parse::<Token![=]>()?;
-            Some(Display {
-                fmt: input.parse()?,
-                args: TokenStream::new(),
-                has_bonus_display: false,
-            })
+            (
+                LabelType::Default,
+                Some(Display {
+                    fmt: input.parse()?,
+                    args: TokenStream::new(),
+                    has_bonus_display: false,
+                }),
+            )
         } else {
-            None
+            (LabelType::Default, None)
         };
-        Ok(LabelAttr { label })
+        Ok(LabelAttr { label, lbl_ty })
     }
 }
 
@@ -79,7 +120,7 @@ impl Labels {
         let mut labels = Vec::new();
         for (i, field) in fields.iter().enumerate() {
             for attr in &field.attrs {
-                if attr.path.is_ident("label") {
+                if attr.path().is_ident("label") {
                     let span = if let Some(ident) = field.ident.clone() {
                         syn::Member::Named(ident)
                     } else {
@@ -88,11 +129,26 @@ impl Labels {
                             span: field.span(),
                         })
                     };
-                    let LabelAttr { label } = syn::parse2::<LabelAttr>(attr.tokens.clone())?;
+                    use quote::ToTokens;
+                    let LabelAttr { label, lbl_ty } =
+                        syn::parse2::<LabelAttr>(attr.meta.to_token_stream())?;
+
+                    if lbl_ty == LabelType::Primary
+                        && labels
+                            .iter()
+                            .any(|l: &Label| l.lbl_ty == LabelType::Primary)
+                    {
+                        return Err(syn::Error::new(
+                            field.span(),
+                            "Cannot have more than one primary label.",
+                        ));
+                    }
+
                     labels.push(Label {
                         label,
                         span,
                         ty: field.ty.clone(),
+                        lbl_ty,
                     });
                 }
             }
@@ -106,36 +162,81 @@ impl Labels {
 
     pub(crate) fn gen_struct(&self, fields: &syn::Fields) -> Option<TokenStream> {
         let (display_pat, display_members) = display_pat_members(fields);
-        let labels = self.0.iter().map(|highlight| {
-            let Label { span, label, ty } = highlight;
-            let var = quote! { __miette_internal_var };
-            if let Some(display) = label {
-                let (fmt, args) = display.expand_shorthand_cloned(&display_members);
-                quote! {
-                    miette::macro_helpers::OptionalWrapper::<#ty>::new().to_option(&self.#span)
-                    .map(|#var| miette::LabeledSpan::new_with_span(
-                        std::option::Option::Some(format!(#fmt #args)),
-                        #var.clone(),
-                    ))
-                }
-            } else {
-                quote! {
-                    miette::macro_helpers::OptionalWrapper::<#ty>::new().to_option(&self.#span)
-                    .map(|#var| miette::LabeledSpan::new_with_span(
-                        std::option::Option::None,
-                        #var.clone(),
-                    ))
-                }
+        let labels = self.0.iter().filter_map(|highlight| {
+            let Label {
+                span,
+                label,
+                ty,
+                lbl_ty,
+            } = highlight;
+            if *lbl_ty == LabelType::Collection {
+                return None;
             }
+            let var = quote! { __miette_internal_var };
+            let display = if let Some(display) = label {
+                let (fmt, args) = display.expand_shorthand_cloned(&display_members);
+                quote! { std::option::Option::Some(format!(#fmt #args)) }
+            } else {
+                quote! { std::option::Option::None }
+            };
+            let ctor = if *lbl_ty == LabelType::Primary {
+                quote! { miette::LabeledSpan::new_primary_with_span }
+            } else {
+                quote! { miette::LabeledSpan::new_with_span }
+            };
+
+            Some(quote! {
+                miette::macro_helpers::OptionalWrapper::<#ty>::new().to_option(&self.#span)
+                .map(|#var| #ctor(
+                    #display,
+                    #var.clone(),
+                ))
+            })
         });
+        let collections_chain = self.0.iter().filter_map(|label| {
+            let Label {
+                span,
+                label,
+                ty: _,
+                lbl_ty,
+            } = label;
+            if *lbl_ty != LabelType::Collection {
+                return None;
+            }
+            let display = if let Some(display) = label {
+                let (fmt, args) = display.expand_shorthand_cloned(&display_members);
+                quote! { std::option::Option::Some(format!(#fmt #args)) }
+            } else {
+                quote! { std::option::Option::None }
+            };
+            Some(quote! {
+                .chain({
+                    let display = #display;
+                    self.#span.iter().map(move |span| {
+                        use miette::macro_helpers::{ToLabelSpanWrapper,ToLabeledSpan};
+                        let mut labeled_span = ToLabelSpanWrapper::to_labeled_span(span.clone());
+                        if display.is_some() && labeled_span.label().is_none() {
+                            labeled_span.set_label(display.clone())
+                        }
+                        Some(labeled_span)
+                    })
+                })
+            })
+        });
+
         Some(quote! {
             #[allow(unused_variables)]
             fn labels(&self) -> std::option::Option<std::boxed::Box<dyn std::iter::Iterator<Item = miette::LabeledSpan> + '_>> {
                 use miette::macro_helpers::ToOption;
                 let Self #display_pat = self;
-                std::option::Option::Some(Box::new(vec![
+
+                let labels_iter = vec![
                     #(#labels),*
-                ].into_iter().filter(Option::is_some).map(Option::unwrap)))
+                ]
+                .into_iter()
+                #(#collections_chain)*;
+
+                std::option::Option::Some(Box::new(labels_iter.filter(Option::is_some).map(Option::unwrap)))
             }
         })
     }
@@ -147,8 +248,11 @@ impl Labels {
             |ident, fields, DiagnosticConcreteArgs { labels, .. }| {
                 let (display_pat, display_members) = display_pat_members(fields);
                 labels.as_ref().and_then(|labels| {
-                    let variant_labels = labels.0.iter().map(|label| {
-                        let Label { span, label, ty } = label;
+                    let variant_labels = labels.0.iter().filter_map(|label| {
+                        let Label { span, label, ty, lbl_ty } = label;
+                        if *lbl_ty == LabelType::Collection {
+                            return None;
+                        }
                         let field = match &span {
                             syn::Member::Named(ident) => ident.clone(),
                             syn::Member::Unnamed(syn::Index { index, .. }) => {
@@ -156,24 +260,56 @@ impl Labels {
                             }
                         };
                         let var = quote! { __miette_internal_var };
-                        if let Some(display) = label {
+                        let display = if let Some(display) = label {
                             let (fmt, args) = display.expand_shorthand_cloned(&display_members);
-                            quote! {
-                                miette::macro_helpers::OptionalWrapper::<#ty>::new().to_option(#field)
-                                .map(|#var| miette::LabeledSpan::new_with_span(
-                                    std::option::Option::Some(format!(#fmt #args)),
-                                    #var.clone(),
-                                ))
-                            }
+                            quote! { std::option::Option::Some(format!(#fmt #args)) }
                         } else {
-                            quote! {
-                                miette::macro_helpers::OptionalWrapper::<#ty>::new().to_option(#field)
-                                .map(|#var| miette::LabeledSpan::new_with_span(
-                                    std::option::Option::None,
-                                    #var.clone(),
-                                ))
-                            }
+                            quote! { std::option::Option::None }
+                        };
+                        let ctor = if *lbl_ty == LabelType::Primary {
+                            quote! { miette::LabeledSpan::new_primary_with_span }
+                        } else {
+                            quote! { miette::LabeledSpan::new_with_span }
+                        };
+
+                        Some(quote! {
+                            miette::macro_helpers::OptionalWrapper::<#ty>::new().to_option(#field)
+                            .map(|#var| #ctor(
+                                #display,
+                                #var.clone(),
+                            ))
+                        })
+                    });
+                    let collections_chain = labels.0.iter().filter_map(|label| {
+                        let Label { span, label, ty: _, lbl_ty } = label;
+                        if *lbl_ty != LabelType::Collection {
+                            return None;
                         }
+                        let field = match &span {
+                            syn::Member::Named(ident) => ident.clone(),
+                            syn::Member::Unnamed(syn::Index { index, .. }) => {
+                                format_ident!("_{}", index)
+                            }
+                        };
+                        let display = if let Some(display) = label {
+                            let (fmt, args) = display.expand_shorthand_cloned(&display_members);
+                            quote! { std::option::Option::Some(format!(#fmt #args)) }
+                        } else {
+                            quote! { std::option::Option::None }
+                        };
+                        Some(quote! {
+                            .chain({
+                                let display = #display;
+                                #field.iter().map(move |span| {
+                                    use miette::macro_helpers::{ToLabelSpanWrapper,ToLabeledSpan};
+                                    let mut labeled_span = ToLabelSpanWrapper::to_labeled_span(span.clone());
+                                    if display.is_some() && labeled_span.label().is_none() {
+                                        labeled_span.set_label(display.clone());
+                                    }
+                                    Some(labeled_span)
+                                })
+                            })
+                        })
                     });
                     let variant_name = ident.clone();
                     match &fields {
@@ -181,9 +317,12 @@ impl Labels {
                         _ => Some(quote! {
                             Self::#variant_name #display_pat => {
                                 use miette::macro_helpers::ToOption;
-                                std::option::Option::Some(std::boxed::Box::new(vec![
+                                let labels_iter = vec![
                                     #(#variant_labels),*
-                                ].into_iter().filter(Option::is_some).map(Option::unwrap)))
+                                ]
+                                .into_iter()
+                                #(#collections_chain)*;
+                                std::option::Option::Some(std::boxed::Box::new(labels_iter.filter(Option::is_some).map(Option::unwrap)))
                             }
                         }),
                     }

miette-derive/src/related.rs

@@ -24,7 +24,7 @@ impl Related {
     fn from_fields_vec(fields: Vec<&syn::Field>) -> syn::Result<Option<Self>> {
         for (i, field) in fields.iter().enumerate() {
             for attr in &field.attrs {
-                if attr.path.is_ident("related") {
+                if attr.path().is_ident("related") {
                     let related = if let Some(ident) = field.ident.clone() {
                         syn::Member::Named(ident)
                     } else {

miette-derive/src/source_code.rs

@@ -10,6 +10,7 @@ use crate::{
 
 pub struct SourceCode {
     source_code: syn::Member,
+    is_option: bool,
 }
 
 impl SourceCode {
@@ -26,7 +27,20 @@ impl SourceCode {
     fn from_fields_vec(fields: Vec<&syn::Field>) -> syn::Result<Option<Self>> {
         for (i, field) in fields.iter().enumerate() {
             for attr in &field.attrs {
-                if attr.path.is_ident("source_code") {
+                if attr.path().is_ident("source_code") {
+                    let is_option = if let syn::Type::Path(syn::TypePath {
+                        path: syn::Path { segments, .. },
+                        ..
+                    }) = &field.ty
+                    {
+                        segments
+                            .last()
+                            .map(|seg| seg.ident == "Option")
+                            .unwrap_or(false)
+                    } else {
+                        false
+                    };
+
                     let source_code = if let Some(ident) = field.ident.clone() {
                         syn::Member::Named(ident)
                     } else {
@@ -35,7 +49,10 @@ impl SourceCode {
                             span: field.span(),
                         })
                     };
-                    return Ok(Some(SourceCode { source_code }));
+                    return Ok(Some(SourceCode {
+                        source_code,
+                        is_option,
+                    }));
                 }
             }
         }
@@ -45,11 +62,21 @@ impl SourceCode {
     pub(crate) fn gen_struct(&self, fields: &syn::Fields) -> Option<TokenStream> {
         let (display_pat, _display_members) = display_pat_members(fields);
         let src = &self.source_code;
+        let ret = if self.is_option {
+            quote! {
+                self.#src.as_ref().map(|s| s as _)
+            }
+        } else {
+            quote! {
+                Some(&self.#src)
+            }
+        };
+
         Some(quote! {
             #[allow(unused_variables)]
             fn source_code(&self) -> std::option::Option<&dyn miette::SourceCode> {
                 let Self #display_pat = self;
-                Some(&self.#src)
+                #ret
             }
         })
     }
@@ -68,10 +95,19 @@ impl SourceCode {
                         }
                     };
                     let variant_name = ident.clone();
+                    let ret = if source_code.is_option {
+                        quote! {
+                            #field.as_ref().map(|s| s as _)
+                        }
+                    } else {
+                        quote! {
+                            std::option::Option::Some(#field)
+                        }
+                    };
                     match &fields {
                         syn::Fields::Unit => None,
                         _ => Some(quote! {
-                            Self::#variant_name #display_pat => std::option::Option::Some(#field),
+                            Self::#variant_name #display_pat => #ret,
                         }),
                     }
                 })

miette-derive/src/url.rs

@@ -129,7 +129,7 @@ impl Url {
             }
         };
         Some(quote! {
-            fn url<'a>(&'a self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + 'a>> {
+            fn url(&self) -> std::option::Option<std::boxed::Box<dyn std::fmt::Display + '_>> {
                 #[allow(unused_variables, deprecated)]
                 let Self #pat = self;
                 std::option::Option::Some(std::boxed::Box::new(format!(#fmt #args)))

miette-derive/src/utils.rs

@@ -1,40 +1,6 @@
 use proc_macro2::TokenStream;
-use quote::{format_ident, quote, ToTokens};
-use syn::{
-    parse::{Parse, ParseStream},
-    spanned::Spanned,
-};
-
-pub(crate) enum MemberOrString {
-    Member(syn::Member),
-    String(syn::LitStr),
-}
-
-impl ToTokens for MemberOrString {
-    fn to_tokens(&self, tokens: &mut TokenStream) {
-        use MemberOrString::*;
-        match self {
-            Member(member) => member.to_tokens(tokens),
-            String(string) => string.to_tokens(tokens),
-        }
-    }
-}
-
-impl Parse for MemberOrString {
-    fn parse(input: ParseStream) -> syn::Result<Self> {
-        let lookahead = input.lookahead1();
-        if lookahead.peek(syn::Ident) || lookahead.peek(syn::LitInt) {
-            Ok(MemberOrString::Member(input.parse()?))
-        } else if lookahead.peek(syn::LitStr) {
-            Ok(MemberOrString::String(input.parse()?))
-        } else {
-            Err(syn::Error::new(
-                input.span(),
-                "Expected a string or a field reference.",
-            ))
-        }
-    }
-}
+use quote::{format_ident, quote};
+use syn::spanned::Spanned;
 
 use crate::{
     diagnostic::{DiagnosticConcreteArgs, DiagnosticDef},

rustfmt.toml

@@ -1,3 +1 @@
 edition = "2021"
-wrap_comments = true
-format_code_in_doc_comments = true

src/chain.rs

@@ -44,6 +44,7 @@ pub(crate) enum ChainState<'a> {
 }
 
 impl<'a> Chain<'a> {
+    #[cold]
     pub(crate) fn new(head: &'a (dyn StdError + 'static)) -> Self {
         Chain {
             state: ChainState::Linked { next: Some(head) },

src/diagnostic_chain.rs

@@ -74,7 +74,7 @@ impl<'a> ErrorKind<'a> {
     }
 }
 
-impl<'a> std::fmt::Debug for ErrorKind<'a> {
+impl std::fmt::Debug for ErrorKind<'_> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
             ErrorKind::Diagnostic(d) => d.fmt(f),
@@ -83,7 +83,7 @@ impl<'a> std::fmt::Debug for ErrorKind<'a> {
     }
 }
 
-impl<'a> std::fmt::Display for ErrorKind<'a> {
+impl std::fmt::Display for ErrorKind<'_> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
             ErrorKind::Diagnostic(d) => d.fmt(f),

src/diagnostic_impls.rs

@@ -0,0 +1,55 @@
+/*!
+Default trait implementations for [`Diagnostic`].
+*/
+
+use std::{convert::Infallible, fmt::Display};
+
+use crate::{Diagnostic, LabeledSpan, Severity, SourceCode};
+
+impl Diagnostic for Infallible {
+    fn code<'a>(&'a self) -> Option<Box<dyn Display + 'a>> {
+        match *self {}
+    }
+
+    fn severity(&self) -> Option<Severity> {
+        match *self {}
+    }
+
+    fn help<'a>(&'a self) -> Option<Box<dyn Display + 'a>> {
+        match *self {}
+    }
+
+    fn url<'a>(&'a self) -> Option<Box<dyn Display + 'a>> {
+        match *self {}
+    }
+
+    fn source_code(&self) -> Option<&dyn SourceCode> {
+        match *self {}
+    }
+
+    fn labels(&self) -> Option<Box<dyn Iterator<Item = LabeledSpan> + '_>> {
+        match *self {}
+    }
+
+    fn related<'a>(&'a self) -> Option<Box<dyn Iterator<Item = &'a dyn Diagnostic> + 'a>> {
+        match *self {}
+    }
+
+    fn diagnostic_source(&self) -> Option<&dyn Diagnostic> {
+        match *self {}
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use crate::Report;
+
+    /// Test that [`Infallible`] implements [`Diagnostic`] by seeing if a function that's generic over `Diagnostic`
+    /// will accept `Infallible` as a type parameter.
+    #[test]
+    fn infallible() {
+        let _ = Report::new::<Infallible>;
+    }
+}

src/error.rs

@@ -1,27 +1,125 @@
-use std::io;
+use std::{
+    error::Error,
+    fmt::{self, Display},
+    io,
+};
 
-use thiserror::Error;
-
-use crate::{self as miette, Diagnostic};
+use crate::Diagnostic;
 
 /**
 Error enum for miette. Used by certain operations in the protocol.
 */
-#[derive(Debug, Diagnostic, Error)]
+#[derive(Debug)]
 pub enum MietteError {
     /// Wrapper around [`std::io::Error`]. This is returned when something went
     /// wrong while reading a [`SourceCode`](crate::SourceCode).
-    #[error(transparent)]
-    #[diagnostic(code(miette::io_error), url(docsrs))]
-    IoError(#[from] io::Error),
+    IoError(io::Error),
 
     /// Returned when a [`SourceSpan`](crate::SourceSpan) extends beyond the
     /// bounds of a given [`SourceCode`](crate::SourceCode).
-    #[error("The given offset is outside the bounds of its Source")]
-    #[diagnostic(
-        code(miette::span_out_of_bounds),
-        help("Double-check your spans. Do you have an off-by-one error?"),
-        url(docsrs)
-    )]
     OutOfBounds,
 }
+
+impl Display for MietteError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            MietteError::IoError(error) => write!(f, "{error}"),
+            MietteError::OutOfBounds => {
+                write!(f, "The given offset is outside the bounds of its Source")
+            }
+        }
+    }
+}
+
+impl Error for MietteError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            MietteError::IoError(error) => error.source(),
+            MietteError::OutOfBounds => None,
+        }
+    }
+}
+
+impl From<io::Error> for MietteError {
+    fn from(value: io::Error) -> Self {
+        Self::IoError(value)
+    }
+}
+
+impl Diagnostic for MietteError {
+    fn code<'a>(&'a self) -> Option<Box<dyn fmt::Display + 'a>> {
+        match self {
+            MietteError::IoError(_) => Some(Box::new("miette::io_error")),
+            MietteError::OutOfBounds => Some(Box::new("miette::span_out_of_bounds")),
+        }
+    }
+
+    fn help<'a>(&'a self) -> Option<Box<dyn fmt::Display + 'a>> {
+        match self {
+            MietteError::IoError(_) => None,
+            MietteError::OutOfBounds => Some(Box::new(
+                "Double-check your spans. Do you have an off-by-one error?",
+            )),
+        }
+    }
+
+    fn url<'a>(&'a self) -> Option<Box<dyn fmt::Display + 'a>> {
+        let crate_version = env!("CARGO_PKG_VERSION");
+        let variant = match self {
+            MietteError::IoError(_) => "#variant.IoError",
+            MietteError::OutOfBounds => "#variant.OutOfBounds",
+        };
+        Some(Box::new(format!(
+            "https://docs.rs/miette/{}/miette/enum.MietteError.html{}",
+            crate_version, variant,
+        )))
+    }
+}
+
+#[cfg(test)]
+pub(crate) mod tests {
+    use std::{error::Error, io::ErrorKind};
+
+    use super::*;
+
+    #[derive(Debug)]
+    pub(crate) struct TestError(pub(crate) io::Error);
+
+    impl Display for TestError {
+        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+            write!(f, "testing, testing...")
+        }
+    }
+
+    impl Error for TestError {
+        fn source(&self) -> Option<&(dyn Error + 'static)> {
+            Some(&self.0)
+        }
+    }
+
+    #[test]
+    fn io_error() {
+        let inner_error = io::Error::new(ErrorKind::Other, "halt and catch fire");
+        let outer_error = TestError(inner_error);
+        let io_error = io::Error::new(ErrorKind::Other, outer_error);
+
+        let miette_error = MietteError::from(io_error);
+
+        assert_eq!(miette_error.to_string(), "testing, testing...");
+        assert_eq!(
+            miette_error.source().unwrap().to_string(),
+            "halt and catch fire"
+        );
+    }
+
+    #[test]
+    fn out_of_bounds() {
+        let miette_error = MietteError::OutOfBounds;
+
+        assert_eq!(
+            miette_error.to_string(),
+            "The given offset is outside the bounds of its Source"
+        );
+        assert_eq!(miette_error.source().map(ToString::to_string), None);
+    }
+}

src/eyreish/context.rs

@@ -38,6 +38,44 @@ mod ext {
     }
 }
 
+impl<T> WrapErr<T, std::convert::Infallible> for Option<T> {
+    fn wrap_err<D>(self, msg: D) -> Result<T, Report>
+    where
+        D: Display + Send + Sync + 'static,
+    {
+        match self {
+            Some(t) => Ok(t),
+            None => Err(Report::from(crate::eyreish::wrapper::DisplayError(msg))),
+        }
+    }
+
+    fn wrap_err_with<D, F>(self, msg: F) -> Result<T, Report>
+    where
+        D: Display + Send + Sync + 'static,
+        F: FnOnce() -> D,
+    {
+        match self {
+            Some(t) => Ok(t),
+            None => Err(Report::from(crate::eyreish::wrapper::DisplayError(msg()))),
+        }
+    }
+
+    fn context<D>(self, msg: D) -> Result<T, Report>
+    where
+        D: Display + Send + Sync + 'static,
+    {
+        self.wrap_err(msg)
+    }
+
+    fn with_context<D, F>(self, msg: F) -> Result<T, Report>
+    where
+        D: Display + Send + Sync + 'static,
+        F: FnOnce() -> D,
+    {
+        self.wrap_err_with(msg)
+    }
+}
+
 impl<T, E> WrapErr<T, E> for Result<T, E>
 where
     E: ext::Diag + Send + Sync + 'static,

src/eyreish/error.rs

@@ -21,6 +21,7 @@ impl Report {
     /// If the error type does not provide a backtrace, a backtrace will be
     /// created here to ensure that a backtrace exists.
     #[cfg_attr(track_caller, track_caller)]
+    #[cold]
     pub fn new<E>(error: E) -> Self
     where
         E: Diagnostic + Send + Sync + 'static,
@@ -30,9 +31,9 @@ impl Report {
 
     /// Create a new error object from a printable error message.
     ///
-    /// If the argument implements std::error::Error, prefer `Report::new`
+    /// If the argument implements [`std::error::Error`], prefer `Report::new`
     /// instead which preserves the underlying error's cause chain and
-    /// backtrace. If the argument may or may not implement std::error::Error
+    /// backtrace. If the argument may or may not implement [`std::error::Error`]
     /// now or in the future, use `miette!(err)` which handles either way
     /// correctly.
     ///
@@ -66,6 +67,7 @@ impl Report {
     /// }
     /// ```
     #[cfg_attr(track_caller, track_caller)]
+    #[cold]
     pub fn msg<M>(message: M) -> Self
     where
         M: Display + Debug + Send + Sync + 'static,
@@ -86,6 +88,7 @@ impl Report {
     }
 
     #[cfg_attr(track_caller, track_caller)]
+    #[cold]
     pub(crate) fn from_std<E>(error: E) -> Self
     where
         E: Diagnostic + Send + Sync + 'static,
@@ -107,6 +110,7 @@ impl Report {
     }
 
     #[cfg_attr(track_caller, track_caller)]
+    #[cold]
     pub(crate) fn from_adhoc<M>(message: M) -> Self
     where
         M: Display + Debug + Send + Sync + 'static,
@@ -131,6 +135,7 @@ impl Report {
     }
 
     #[cfg_attr(track_caller, track_caller)]
+    #[cold]
     pub(crate) fn from_msg<D, E>(msg: D, error: E) -> Self
     where
         D: Display + Send + Sync + 'static,
@@ -155,6 +160,7 @@ impl Report {
     }
 
     #[cfg_attr(track_caller, track_caller)]
+    #[cold]
     pub(crate) fn from_boxed(error: Box<dyn Diagnostic + Send + Sync>) -> Self {
         use super::wrapper::BoxedError;
         let error = BoxedError(error);
@@ -180,6 +186,7 @@ impl Report {
     //
     // Unsafe because the given vtable must have sensible behavior on the error
     // value of type E.
+    #[cold]
     unsafe fn construct<E>(
         error: E,
         vtable: &'static ErrorVTable,
@@ -206,7 +213,7 @@ impl Report {
     /// Create a new error from an error message to wrap the existing error.
     ///
     /// For attaching a higher level error message to a `Result` as it is
-    /// propagated, the [crate::WrapErr] extension trait may be more
+    /// propagated, the [`WrapErr`](crate::WrapErr) extension trait may be more
     /// convenient than this function.
     ///
     /// The primary reason to use `error.wrap_err(...)` instead of
@@ -233,7 +240,7 @@ impl Report {
         unsafe { Report::construct(error, vtable, handler) }
     }
 
-    /// Compatibility re-export of wrap_err for interop with `anyhow`
+    /// Compatibility re-export of `wrap_err` for interop with `anyhow`
     pub fn context<D>(self, msg: D) -> Self
     where
         D: Display + Send + Sync + 'static,
@@ -262,6 +269,7 @@ impl Report {
     ///     None
     /// }
     /// ```
+    #[cold]
     pub fn chain(&self) -> Chain<'_> {
         unsafe { ErrorImpl::chain(self.inner.by_ref()) }
     }
@@ -272,7 +280,7 @@ impl Report {
     /// The root cause is the last error in the iterator produced by
     /// [`chain()`](Report::chain).
     pub fn root_cause(&self) -> &(dyn StdError + 'static) {
-        self.chain().last().unwrap()
+        self.chain().next_back().unwrap()
     }
 
     /// Returns true if `E` is the type held by this error object.
@@ -410,13 +418,21 @@ impl Report {
     }
 
     /// Provide source code for this error
-    pub fn with_source_code(self, source_code: impl SourceCode + Send + Sync + 'static) -> Report {
+    pub fn with_source_code(self, source_code: impl SourceCode + 'static) -> Report {
         WithSourceCode {
             source_code,
             error: self,
         }
         .into()
     }
+
+    /// Construct a [`Report`] directly from an error-like type
+    pub fn from_err<E>(err: E) -> Self
+    where
+        E: std::error::Error + Send + Sync + 'static,
+    {
+        super::DiagnosticError(Box::new(err)).into()
+    }
 }
 
 impl<E> From<E> for Report
@@ -424,6 +440,7 @@ where
     E: Diagnostic + Send + Sync + 'static,
 {
     #[cfg_attr(track_caller, track_caller)]
+    #[cold]
     fn from(error: E) -> Self {
         Report::from_std(error)
     }
@@ -533,7 +550,8 @@ where
     E: Diagnostic + Send + Sync + 'static,
 {
     // Attach ErrorImpl<E>'s native StdError vtable. The StdError impl is below.
-    e.cast::<ErrorImpl<E>>().boxed()
+    let unerased = e.cast::<ErrorImpl<E>>().boxed();
+    Box::new(unerased._object)
 }
 
 // Safety: requires layout of *e to match ErrorImpl<E>.
@@ -544,7 +562,8 @@ where
     E: StdError + Send + Sync + 'static,
 {
     // Attach ErrorImpl<E>'s native StdError vtable. The StdError impl is below.
-    e.cast::<ErrorImpl<E>>().boxed()
+    let unerased = e.cast::<ErrorImpl<E>>().boxed();
+    Box::new(unerased._object)
 }
 
 // Safety: requires layout of *e to match ErrorImpl<E>.
@@ -711,22 +730,12 @@ impl ErasedErrorImpl {
             .deref_mut()
     }
 
+    #[cold]
     pub(crate) unsafe fn chain(this: Ref<'_, Self>) -> Chain<'_> {
         Chain::new(Self::error(this))
     }
 }
 
-impl<E> StdError for ErrorImpl<E>
-where
-    E: StdError,
-{
-    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
-        unsafe { ErrorImpl::diagnostic(self.erase()).source() }
-    }
-}
-
-impl<E> Diagnostic for ErrorImpl<E> where E: Diagnostic {}
-
 impl<E> Debug for ErrorImpl<E>
 where
     E: Debug,
@@ -746,6 +755,7 @@ where
 }
 
 impl From<Report> for Box<dyn Diagnostic + Send + Sync + 'static> {
+    #[cold]
     fn from(error: Report) -> Self {
         let outer = ManuallyDrop::new(error);
         unsafe {
@@ -757,6 +767,7 @@ impl From<Report> for Box<dyn Diagnostic + Send + Sync + 'static> {
 }
 
 impl From<Report> for Box<dyn StdError + Send + Sync + 'static> {
+    #[cold]
     fn from(error: Report) -> Self {
         let outer = ManuallyDrop::new(error);
         unsafe {
@@ -768,12 +779,14 @@ impl From<Report> for Box<dyn StdError + Send + Sync + 'static> {
 }
 
 impl From<Report> for Box<dyn Diagnostic + 'static> {
+    #[cold]
     fn from(error: Report) -> Self {
         Box::<dyn Diagnostic + Send + Sync>::from(error)
     }
 }
 
 impl From<Report> for Box<dyn StdError + 'static> {
+    #[cold]
     fn from(error: Report) -> Self {
         Box::<dyn StdError + Send + Sync>::from(error)
     }

src/eyreish/into_diagnostic.rs

@@ -1,12 +1,24 @@
-use thiserror::Error;
+use std::{error::Error, fmt::Display};
 
 use crate::{Diagnostic, Report};
 
 /// Convenience [`Diagnostic`] that can be used as an "anonymous" wrapper for
 /// Errors. This is intended to be paired with [`IntoDiagnostic`].
-#[derive(Debug, Error)]
-#[error(transparent)]
-struct DiagnosticError(Box<dyn std::error::Error + Send + Sync + 'static>);
+#[derive(Debug)]
+pub(crate) struct DiagnosticError(pub(crate) Box<dyn std::error::Error + Send + Sync + 'static>);
+
+impl Display for DiagnosticError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let msg = &self.0;
+        write!(f, "{msg}")
+    }
+}
+impl Error for DiagnosticError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        self.0.source()
+    }
+}
+
 impl Diagnostic for DiagnosticError {}
 
 /**
@@ -31,3 +43,26 @@ impl<T, E: std::error::Error + Send + Sync + 'static> IntoDiagnostic<T, E> for R
         self.map_err(|e| DiagnosticError(Box::new(e)).into())
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use std::io::{self, ErrorKind};
+
+    use super::*;
+
+    use crate::error::tests::TestError;
+
+    #[test]
+    fn diagnostic_error() {
+        let inner_error = io::Error::new(ErrorKind::Other, "halt and catch fire");
+        let outer_error: Result<(), _> = Err(TestError(inner_error));
+
+        let diagnostic_error = outer_error.into_diagnostic().unwrap_err();
+
+        assert_eq!(diagnostic_error.to_string(), "testing, testing...");
+        assert_eq!(
+            diagnostic_error.source().unwrap().to_string(),
+            "halt and catch fire"
+        );
+    }
+}

src/eyreish/kind.rs

@@ -63,6 +63,7 @@ impl<T> AdhocKind for &T where T: ?Sized + Display + Debug + Send + Sync + 'stat
 
 impl Adhoc {
     #[cfg_attr(track_caller, track_caller)]
+    #[cold]
     pub fn new<M>(self, message: M) -> Report
     where
         M: Display + Debug + Send + Sync + 'static,
@@ -84,6 +85,7 @@ impl<E> TraitKind for E where E: Into<Report> {}
 
 impl Trait {
     #[cfg_attr(track_caller, track_caller)]
+    #[cold]
     pub fn new<E>(self, error: E) -> Report
     where
         E: Into<Report>,
@@ -105,6 +107,7 @@ impl BoxedKind for Box<dyn Diagnostic + Send + Sync> {}
 
 impl Boxed {
     #[cfg_attr(track_caller, track_caller)]
+    #[cold]
     pub fn new(self, error: Box<dyn Diagnostic + Send + Sync>) -> Report {
         Report::from_boxed(error)
     }

src/eyreish/macros.rs

@@ -16,7 +16,14 @@
 /// #     let resource = 0;
 /// #
 /// if !has_permission(user, resource) {
-///     bail!("permission denied for accessing {}", resource);
+#[cfg_attr(
+    not(feature = "no-format-args-capture"),
+    doc = r#"     bail!("permission denied for accessing {resource}");"#
+)]
+#[cfg_attr(
+    feature = "no-format-args-capture",
+    doc = r#"     bail!("permission denied for accessing {}", resource);"#
+)]
 /// }
 /// #     Ok(())
 /// # }
@@ -48,17 +55,37 @@
 /// #     Ok(())
 /// # }
 /// ```
+///
+/// ```
+/// use miette::{bail, Result, Severity};
+///
+/// fn divide(x: f64, y: f64) -> Result<f64> {
+///     if y.abs() < 1e-3 {
+///         bail!(
+///             severity = Severity::Warning,
+#[cfg_attr(
+    not(feature = "no-format-args-capture"),
+    doc = r#"             "dividing by value ({y}) close to 0""#
+)]
+#[cfg_attr(
+    feature = "no-format-args-capture",
+    doc = r#"             "dividing by value ({}) close to 0", y"#
+)]
+///         );
+///     }
+///     Ok(x / y)
+/// }
+/// ```
 #[macro_export]
 macro_rules! bail {
-    ($msg:literal $(,)?) => {
-        return $crate::private::Err($crate::miette!($msg));
+    ($($key:ident = $value:expr,)* $fmt:literal $($arg:tt)*) => {
+        return $crate::private::Err(
+            $crate::miette!($($key = $value,)* $fmt $($arg)*)
+        );
     };
     ($err:expr $(,)?) => {
         return $crate::private::Err($crate::miette!($err));
     };
-    ($fmt:expr, $($arg:tt)*) => {
-        return $crate::private::Err($crate::miette!($fmt, $($arg)*));
-    };
 }
 
 /// Return early with an error if a condition is not satisfied.
@@ -105,11 +132,33 @@ macro_rules! bail {
 /// #     Ok(())
 /// # }
 /// ```
+///
+/// ```
+/// use miette::{ensure, Result, Severity};
+///
+/// fn divide(x: f64, y: f64) -> Result<f64> {
+///     ensure!(
+///         y.abs() >= 1e-3,
+///         severity = Severity::Warning,
+#[cfg_attr(
+    not(feature = "no-format-args-capture"),
+    doc = r#"             "dividing by value ({y}) close to 0""#
+)]
+#[cfg_attr(
+    feature = "no-format-args-capture",
+    doc = r#"             "dividing by value ({}) close to 0", y"#
+)]
+///     );
+///     Ok(x / y)
+/// }
+/// ```
 #[macro_export]
 macro_rules! ensure {
-    ($cond:expr, $msg:literal $(,)?) => {
+    ($cond:expr, $($key:ident = $value:expr,)* $fmt:literal $($arg:tt)*) => {
         if !$cond {
-            return $crate::private::Err($crate::miette!($msg));
+            return $crate::private::Err(
+                $crate::miette!($($key = $value,)* $fmt $($arg)*)
+            );
         }
     };
     ($cond:expr, $err:expr $(,)?) => {
@@ -117,52 +166,135 @@ macro_rules! ensure {
             return $crate::private::Err($crate::miette!($err));
         }
     };
-    ($cond:expr, $fmt:expr, $($arg:tt)*) => {
-        if !$cond {
-            return $crate::private::Err($crate::miette!($fmt, $($arg)*));
-        }
-    };
 }
 
-/// Construct an ad-hoc error from a string.
+/// Construct an ad-hoc [`Report`].
 ///
-/// This evaluates to an `Error`. It can take either just a string, or a format
-/// string with arguments. It also can take any custom type which implements
-/// `Debug` and `Display`.
-///
-/// # Example
+/// # Examples
 ///
+/// With string literal and interpolation:
 /// ```
-/// # type V = ();
-/// #
-/// use miette::{miette, Result};
+/// # use miette::miette;
+/// let x = 1;
+/// let y = 2;
+#[cfg_attr(
+    not(feature = "no-format-args-capture"),
+    doc = r#"let report = miette!("{x} + {} = {z}", y, z = x + y);"#
+)]
+#[cfg_attr(
+    feature = "no-format-args-capture",
+    doc = r#"let report = miette!("{} + {} = {z}", x, y, z = x + y);"#
+)]
 ///
-/// fn lookup(key: &str) -> Result<V> {
-///     if key.len() != 16 {
-///         return Err(miette!("key length must be 16 characters, got {:?}", key));
-///     }
+/// assert_eq!(report.to_string().as_str(), "1 + 2 = 3");
 ///
-///     // ...
-///     # Ok(())
-/// }
+/// let z = x + y;
+#[cfg_attr(
+    not(feature = "no-format-args-capture"),
+    doc = r#"let report = miette!("{x} + {y} = {z}");"#
+)]
+#[cfg_attr(
+    feature = "no-format-args-capture",
+    doc = r#"let report = miette!("{} + {} = {}", x, y, z);"#
+)]
+/// assert_eq!(report.to_string().as_str(), "1 + 2 = 3");
+/// ```
+///
+/// With [`diagnostic!`]-like arguments:
+/// ```
+/// use miette::{miette, LabeledSpan, Severity};
+///
+/// let source = "(2 + 2".to_string();
+/// let report = miette!(
+///     // Those fields are optional
+///     severity = Severity::Error,
+///     code = "expected::rparen",
+///     help = "always close your parens",
+///     labels = vec![LabeledSpan::at_offset(6, "here")],
+///     url = "https://example.com",
+///     // Rest of the arguments are passed to `format!`
+///     // to form diagnostic message
+///     "expected closing ')'"
+/// )
+/// .with_source_code(source);
 /// ```
 ///
 /// ## `anyhow`/`eyre` Users
 ///
 /// You can just replace `use`s of the `anyhow!`/`eyre!` macros with `miette!`.
+///
+/// [`diagnostic!`]: crate::diagnostic!
+/// [`Report`]: crate::Report
 #[macro_export]
 macro_rules! miette {
-    ($msg:literal $(,)?) => {
-        // Handle $:literal as a special case to make cargo-expanded code more
-        // concise in the common case.
-        $crate::private::new_adhoc($msg)
+    ($($key:ident = $value:expr,)* $fmt:literal $($arg:tt)*) => {
+        $crate::Report::from(
+            $crate::diagnostic!($($key = $value,)* $fmt $($arg)*)
+        )
     };
     ($err:expr $(,)?) => ({
         use $crate::private::kind::*;
         let error = $err;
         (&error).miette_kind().new(error)
     });
-    ($fmt:expr, $($arg:tt)*) => {
-        $crate::private::new_adhoc(format!($fmt, $($arg)*))
-    };
+}
+
+/// Construct a [`MietteDiagnostic`] in more user-friendly way.
+///
+/// # Examples
+/// ```
+/// use miette::{diagnostic, LabeledSpan, Severity};
+///
+/// let source = "(2 + 2".to_string();
+/// let diag = diagnostic!(
+///     // Those fields are optional
+///     severity = Severity::Error,
+///     code = "expected::rparen",
+///     help = "always close your parens",
+///     labels = vec![LabeledSpan::at_offset(6, "here")],
+///     url = "https://example.com",
+///     // Rest of the arguments are passed to `format!`
+///     // to form diagnostic message
+///     "expected closing ')'",
+/// );
+/// ```
+/// Diagnostic without any fields:
+/// ```
+/// # use miette::diagnostic;
+/// let x = 1;
+/// let y = 2;
+///
+#[cfg_attr(
+    not(feature = "no-format-args-capture"),
+    doc = r#" let diag = diagnostic!("{x} + {} = {z}", y, z = x + y);"#
+)]
+#[cfg_attr(
+    feature = "no-format-args-capture",
+    doc = r#" let diag = diagnostic!("{} + {} = {z}", x, y, z = x + y);"#
+)]
+/// assert_eq!(diag.message, "1 + 2 = 3");
+///
+/// let z = x + y;
+#[cfg_attr(
+    not(feature = "no-format-args-capture"),
+    doc = r#"let diag = diagnostic!("{x} + {y} = {z}");"#
+)]
+#[cfg_attr(
+    feature = "no-format-args-capture",
+    doc = r#"let diag = diagnostic!("{} + {} = {}", x, y, z);"#
+)]
+/// assert_eq!(diag.message, "1 + 2 = 3");
+/// ```
+///
+/// [`MietteDiagnostic`]: crate::MietteDiagnostic
+#[macro_export]
+macro_rules! diagnostic {
+    ($fmt:literal $($arg:tt)*) => {{
+        $crate::MietteDiagnostic::new(format!($fmt $($arg)*))
+    }};
+    ($($key:ident = $value:expr,)+ $fmt:literal $($arg:tt)*) => {{
+        let mut diag = $crate::MietteDiagnostic::new(format!($fmt $($arg)*));
+        $(diag.$key = Some($value.into());)*
+        diag
+    }};
 }

src/eyreish/mod.rs

@@ -7,8 +7,7 @@
 use core::fmt::Display;
 
 use std::error::Error as StdError;
-
-use once_cell::sync::OnceCell;
+use std::sync::OnceLock;
 
 #[allow(unreachable_pub)]
 pub use into_diagnostic::*;
@@ -25,10 +24,10 @@ pub use ReportHandler as EyreContext;
 #[allow(unreachable_pub)]
 pub use WrapErr as Context;
 
-#[cfg(not(feature = "fancy-no-backtrace"))]
+#[cfg(not(feature = "fancy-base"))]
 use crate::DebugReportHandler;
 use crate::Diagnostic;
-#[cfg(feature = "fancy-no-backtrace")]
+#[cfg(feature = "fancy-base")]
 use crate::MietteHandler;
 
 use error::ErrorImpl;
@@ -58,11 +57,11 @@ pub struct Report {
 unsafe impl Sync for Report {}
 unsafe impl Send for Report {}
 
-///
+#[allow(missing_docs)]
 pub type ErrorHook =
     Box<dyn Fn(&(dyn Diagnostic + 'static)) -> Box<dyn ReportHandler> + Sync + Send + 'static>;
 
-static HOOK: OnceCell<ErrorHook> = OnceCell::new();
+static HOOK: OnceLock<ErrorHook> = OnceLock::new();
 
 /// Error indicating that [`set_hook()`] was unable to install the provided
 /// [`ErrorHook`].
@@ -103,14 +102,14 @@ fn capture_handler(error: &(dyn Diagnostic + 'static)) -> Box<dyn ReportHandler>
 }
 
 fn get_default_printer(_err: &(dyn Diagnostic + 'static)) -> Box<dyn ReportHandler + 'static> {
-    #[cfg(feature = "fancy-no-backtrace")]
+    #[cfg(feature = "fancy-base")]
     return Box::new(MietteHandler::new());
-    #[cfg(not(feature = "fancy-no-backtrace"))]
+    #[cfg(not(feature = "fancy-base"))]
     return Box::new(DebugReportHandler::new());
 }
 
 impl dyn ReportHandler {
-    ///
+    #[allow(missing_docs)]
     pub fn is<T: ReportHandler>(&self) -> bool {
         // Get `TypeId` of the type this function is instantiated with.
         let t = core::any::TypeId::of::<T>();
@@ -122,7 +121,7 @@ impl dyn ReportHandler {
         t == concrete
     }
 
-    ///
+    #[allow(missing_docs)]
     pub fn downcast_ref<T: ReportHandler>(&self) -> Option<&T> {
         if self.is::<T>() {
             unsafe { Some(&*(self as *const dyn ReportHandler as *const T)) }
@@ -131,7 +130,7 @@ impl dyn ReportHandler {
         }
     }
 
-    ///
+    #[allow(missing_docs)]
     pub fn downcast_mut<T: ReportHandler>(&mut self) -> Option<&mut T> {
         if self.is::<T>() {
             unsafe { Some(&mut *(self as *mut dyn ReportHandler as *mut T)) }
@@ -173,11 +172,7 @@ pub trait ReportHandler: core::any::Any + Send + Sync {
     ///     }
     /// }
     /// ```
-    fn debug(
-        &self,
-        error: &(dyn Diagnostic),
-        f: &mut core::fmt::Formatter<'_>,
-    ) -> core::fmt::Result;
+    fn debug(&self, error: &dyn Diagnostic, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result;
 
     /// Override for the `Display` format
     fn display(
@@ -476,6 +471,7 @@ pub mod private {
     }
 
     #[cfg_attr(track_caller, track_caller)]
+    #[cold]
     pub fn new_adhoc<M>(message: M) -> Report
     where
         M: Display + Debug + Send + Sync + 'static,

src/eyreish/ptr.rs

@@ -43,7 +43,7 @@ where
         Box::from_raw(self.ptr.as_ptr())
     }
 
-    pub(crate) fn by_ref<'a>(&self) -> Ref<'a, T> {
+    pub(crate) const fn by_ref<'a>(&self) -> Ref<'a, T> {
         Ref {
             ptr: self.ptr,
             lifetime: PhantomData,
@@ -69,9 +69,9 @@ where
     lifetime: PhantomData<&'a T>,
 }
 
-impl<'a, T> Copy for Ref<'a, T> where T: ?Sized {}
+impl<T> Copy for Ref<'_, T> where T: ?Sized {}
 
-impl<'a, T> Clone for Ref<'a, T>
+impl<T> Clone for Ref<'_, T>
 where
     T: ?Sized,
 {
@@ -91,7 +91,7 @@ where
         }
     }
 
-    pub(crate) fn from_raw(ptr: NonNull<T>) -> Self {
+    pub(crate) const fn from_raw(ptr: NonNull<T>) -> Self {
         Ref {
             ptr,
             lifetime: PhantomData,
@@ -112,7 +112,7 @@ where
         }
     }
 
-    pub(crate) fn as_ptr(self) -> *const T {
+    pub(crate) const fn as_ptr(self) -> *const T {
         self.ptr.as_ptr() as *const T
     }
 
@@ -132,9 +132,9 @@ where
     lifetime: PhantomData<&'a mut T>,
 }
 
-impl<'a, T> Copy for Mut<'a, T> where T: ?Sized {}
+impl<T> Copy for Mut<'_, T> where T: ?Sized {}
 
-impl<'a, T> Clone for Mut<'a, T>
+impl<T> Clone for Mut<'_, T>
 where
     T: ?Sized,
 {
@@ -154,7 +154,7 @@ where
         }
     }
 
-    pub(crate) fn by_ref(self) -> Ref<'a, T> {
+    pub(crate) const fn by_ref(self) -> Ref<'a, T> {
         Ref {
             ptr: self.ptr,
             lifetime: PhantomData,
@@ -173,7 +173,7 @@ where
     }
 }
 
-impl<'a, T> Mut<'a, T> {
+impl<T> Mut<'_, T> {
     pub(crate) unsafe fn read(self) -> T {
         self.ptr.as_ptr().read()
     }

src/eyreish/wrapper.rs

@@ -9,11 +9,6 @@ use crate as miette;
 #[repr(transparent)]
 pub(crate) struct DisplayError<M>(pub(crate) M);
 
-#[repr(transparent)]
-pub(crate) struct MessageError<M>(pub(crate) M);
-
-pub(crate) struct NoneError;
-
 impl<M> Debug for DisplayError<M>
 where
     M: Display,
@@ -35,6 +30,9 @@ where
 impl<M> StdError for DisplayError<M> where M: Display + 'static {}
 impl<M> Diagnostic for DisplayError<M> where M: Display + 'static {}
 
+#[repr(transparent)]
+pub(crate) struct MessageError<M>(pub(crate) M);
+
 impl<M> Debug for MessageError<M>
 where
     M: Display + Debug,
@@ -56,21 +54,6 @@ where
 impl<M> StdError for MessageError<M> where M: Display + Debug + 'static {}
 impl<M> Diagnostic for MessageError<M> where M: Display + Debug + 'static {}
 
-impl Debug for NoneError {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        Debug::fmt("Option was None", f)
-    }
-}
-
-impl Display for NoneError {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        Display::fmt("Option was None", f)
-    }
-}
-
-impl StdError for NoneError {}
-impl Diagnostic for NoneError {}
-
 #[repr(transparent)]
 pub(crate) struct BoxedError(pub(crate) Box<dyn Diagnostic + Send + Sync>);
 
@@ -163,7 +146,7 @@ impl<E: Diagnostic, C: SourceCode> Diagnostic for WithSourceCode<E, C> {
     }
 
     fn source_code(&self) -> Option<&dyn miette::SourceCode> {
-        Some(&self.source_code)
+        self.error.source_code().or(Some(&self.source_code))
     }
 
     fn related<'a>(&'a self) -> Option<Box<dyn Iterator<Item = &'a dyn Diagnostic> + 'a>> {
@@ -197,7 +180,7 @@ impl<C: SourceCode> Diagnostic for WithSourceCode<Report, C> {
     }
 
     fn source_code(&self) -> Option<&dyn miette::SourceCode> {
-        Some(&self.source_code)
+        self.error.source_code().or(Some(&self.source_code))
     }
 
     fn related<'a>(&'a self) -> Option<Box<dyn Iterator<Item = &'a dyn Diagnostic> + 'a>> {
@@ -232,3 +215,88 @@ impl<C> StdError for WithSourceCode<Report, C> {
         self.error.source()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use thiserror::Error;
+
+    use crate::{Diagnostic, LabeledSpan, Report, SourceCode, SourceSpan};
+
+    #[derive(Error, Debug)]
+    #[error("inner")]
+    struct Inner {
+        pub(crate) at: SourceSpan,
+        pub(crate) source_code: Option<String>,
+    }
+
+    impl Diagnostic for Inner {
+        fn labels(&self) -> Option<Box<dyn Iterator<Item = LabeledSpan> + '_>> {
+            Some(Box::new(std::iter::once(LabeledSpan::underline(self.at))))
+        }
+
+        fn source_code(&self) -> Option<&dyn SourceCode> {
+            self.source_code.as_ref().map(|s| s as _)
+        }
+    }
+
+    #[test]
+    fn no_override() {
+        let inner_source = "hello world";
+        let outer_source = "abc";
+
+        let report = Report::from(Inner {
+            at: (0..5).into(),
+            source_code: Some(inner_source.to_string()),
+        })
+        .with_source_code(outer_source.to_string());
+
+        let underlined = String::from_utf8(
+            report
+                .source_code()
+                .unwrap()
+                .read_span(&(0..5).into(), 0, 0)
+                .unwrap()
+                .data()
+                .to_vec(),
+        )
+        .unwrap();
+        assert_eq!(underlined, "hello");
+    }
+
+    #[test]
+    #[cfg(feature = "fancy")]
+    fn two_source_codes() {
+        #[derive(Error, Debug)]
+        #[error("outer")]
+        struct Outer {
+            pub(crate) errors: Vec<Inner>,
+        }
+
+        impl Diagnostic for Outer {
+            fn related<'a>(&'a self) -> Option<Box<dyn Iterator<Item = &'a dyn Diagnostic> + 'a>> {
+                Some(Box::new(self.errors.iter().map(|e| e as _)))
+            }
+        }
+
+        let inner_source = "hello world";
+        let outer_source = "abc";
+
+        let report = Report::from(Outer {
+            errors: vec![
+                Inner {
+                    at: (0..5).into(),
+                    source_code: Some(inner_source.to_string()),
+                },
+                Inner {
+                    at: (1..2).into(),
+                    source_code: None,
+                },
+            ],
+        })
+        .with_source_code(outer_source.to_string());
+
+        let message = format!("{:?}", report);
+        assert!(message.contains(inner_source));
+        assert!(message.contains(outer_source));
+    }
+}

src/handler.rs

@@ -1,7 +1,5 @@
-use std::fmt;
-
-use atty::Stream;
-
+use crate::highlighters::Highlighter;
+use crate::highlighters::MietteHighlighter;
 use crate::protocol::Diagnostic;
 use crate::GraphicalReportHandler;
 use crate::GraphicalTheme;
@@ -9,24 +7,21 @@ use crate::NarratableReportHandler;
 use crate::ReportHandler;
 use crate::ThemeCharacters;
 use crate::ThemeStyles;
+use cfg_if::cfg_if;
+use std::fmt;
 
 /// Settings to control the color format used for graphical rendering.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+#[derive(Copy, Clone, Debug, Eq, PartialEq, Default)]
 pub enum RgbColors {
     /// Use RGB colors even if the terminal does not support them
     Always,
     /// Use RGB colors instead of ANSI if the terminal supports RGB
     Preferred,
     /// Always use ANSI, regardless of terminal support for RGB
+    #[default]
     Never,
 }
 
-impl Default for RgbColors {
-    fn default() -> RgbColors {
-        RgbColors::Never
-    }
-}
-
 /**
 Create a custom [`MietteHandler`] from options.
 
@@ -57,6 +52,12 @@ pub struct MietteHandlerOpts {
     pub(crate) context_lines: Option<usize>,
     pub(crate) tab_width: Option<usize>,
     pub(crate) with_cause_chain: Option<bool>,
+    pub(crate) break_words: Option<bool>,
+    pub(crate) wrap_lines: Option<bool>,
+    pub(crate) word_separator: Option<textwrap::WordSeparator>,
+    pub(crate) word_splitter: Option<textwrap::WordSplitter>,
+    pub(crate) highlighter: Option<MietteHighlighter>,
+    pub(crate) show_related_as_nested: Option<bool>,
 }
 
 impl MietteHandlerOpts {
@@ -82,12 +83,81 @@ impl MietteHandlerOpts {
         self
     }
 
+    /// Set a syntax highlighter when rendering in graphical mode.
+    /// Use [`force_graphical()`](MietteHandlerOpts::force_graphical()) to
+    /// force graphical mode.
+    ///
+    /// Syntax highlighting is disabled by default unless the
+    /// `syntect-highlighter` feature is enabled. Call this method
+    /// to override the default and use a custom highlighter
+    /// implementation instead.
+    ///
+    /// Use
+    /// [`without_syntax_highlighting()`](MietteHandlerOpts::without_syntax_highlighting())
+    /// To disable highlighting completely.
+    ///
+    /// Setting this option will not force color output. In all cases, the
+    /// current color configuration via
+    /// [`color()`](MietteHandlerOpts::color()) takes precedence over
+    /// highlighter configuration. However, this option does take precedence over
+    /// [`rgb_colors()`](MietteHandlerOpts::rgb_colors()) (meaning syntax highlighting will be
+    /// enabled regardless of the value of [`MietteHandlerOpts::rgb_colors`]).
+    pub fn with_syntax_highlighting(
+        mut self,
+        highlighter: impl Highlighter + Send + Sync + 'static,
+    ) -> Self {
+        self.highlighter = Some(MietteHighlighter::from(highlighter));
+        self
+    }
+
+    /// Disables syntax highlighting when rendering in graphical mode.
+    /// Use [`force_graphical()`](MietteHandlerOpts::force_graphical()) to
+    /// force graphical mode.
+    ///
+    /// Syntax highlighting is disabled by default unless the
+    /// `syntect-highlighter` feature is enabled. Call this method if you want
+    /// to disable highlighting when building with this feature.
+    pub fn without_syntax_highlighting(mut self) -> Self {
+        self.highlighter = Some(MietteHighlighter::nocolor());
+        self
+    }
+
     /// Sets the width to wrap the report at. Defaults to 80.
     pub fn width(mut self, width: usize) -> Self {
         self.width = Some(width);
         self
     }
 
+    /// If true, long lines can be wrapped.
+    ///
+    /// If false, long lines will not be broken when they exceed the width.
+    ///
+    /// Defaults to true.
+    pub fn wrap_lines(mut self, wrap_lines: bool) -> Self {
+        self.wrap_lines = Some(wrap_lines);
+        self
+    }
+
+    /// If true, long words can be broken when wrapping.
+    ///
+    /// If false, long words will not be broken when they exceed the width.
+    ///
+    /// Defaults to true.
+    pub fn break_words(mut self, break_words: bool) -> Self {
+        self.break_words = Some(break_words);
+        self
+    }
+    /// Sets the `textwrap::WordSeparator` to use when determining wrap points.
+    pub fn word_separator(mut self, word_separator: textwrap::WordSeparator) -> Self {
+        self.word_separator = Some(word_separator);
+        self
+    }
+
+    /// Sets the `textwrap::WordSplitter` to use when determining wrap points.
+    pub fn word_splitter(mut self, word_splitter: textwrap::WordSplitter) -> Self {
+        self.word_splitter = Some(word_splitter);
+        self
+    }
     /// Include the cause chain of the top-level error in the report.
     pub fn with_cause_chain(mut self) -> Self {
         self.with_cause_chain = Some(true);
@@ -100,6 +170,18 @@ impl MietteHandlerOpts {
         self
     }
 
+    /// Show related errors as siblings.
+    pub fn show_related_errors_as_siblings(mut self) -> Self {
+        self.show_related_as_nested = Some(false);
+        self
+    }
+
+    /// Show related errors as nested errors.
+    pub fn show_related_errors_as_nested(mut self) -> Self {
+        self.show_related_as_nested = Some(true);
+        self
+    }
+
     /// If true, colors will be used during graphical rendering, regardless
     /// of whether or not the terminal supports them.
     ///
@@ -123,6 +205,8 @@ impl MietteHandlerOpts {
     /// first place. That is handled by the [`MietteHandlerOpts::color`]
     /// setting. If colors are not being used, the value of `rgb_colors` has
     /// no effect.
+    ///
+    /// It also does not control colors when a syntax highlighter is in use.
     pub fn rgb_colors(mut self, color: RgbColors) -> Self {
         self.rgb_colors = color;
         self
@@ -193,15 +277,15 @@ impl MietteHandlerOpts {
             let characters = match self.unicode {
                 Some(true) => ThemeCharacters::unicode(),
                 Some(false) => ThemeCharacters::ascii(),
-                None if supports_unicode::on(Stream::Stderr) => ThemeCharacters::unicode(),
+                None if syscall::supports_unicode() => ThemeCharacters::unicode(),
                 None => ThemeCharacters::ascii(),
             };
             let styles = if self.color == Some(false) {
                 ThemeStyles::none()
-            } else if let Some(color) = supports_color::on(Stream::Stderr) {
+            } else if let Some(color_has_16m) = syscall::supports_color_has_16m() {
                 match self.rgb_colors {
                     RgbColors::Always => ThemeStyles::rgb(),
-                    RgbColors::Preferred if color.has_16m => ThemeStyles::rgb(),
+                    RgbColors::Preferred if color_has_16m => ThemeStyles::rgb(),
                     _ => ThemeStyles::ansi(),
                 }
             } else if self.color == Some(true) {
@@ -212,11 +296,13 @@ impl MietteHandlerOpts {
             } else {
                 ThemeStyles::none()
             };
+            let highlighter_opt =
+                HighlighterOption::select(self.color, self.highlighter, syscall::supports_color());
             let theme = self.theme.unwrap_or(GraphicalTheme { characters, styles });
-            let mut handler = GraphicalReportHandler::new()
+            let mut handler = GraphicalReportHandler::new_themed(theme)
                 .with_width(width)
-                .with_links(linkify)
-                .with_theme(theme);
+                .with_links(linkify);
+            handler.highlighter = highlighter_opt.into();
             if let Some(with_cause_chain) = self.with_cause_chain {
                 if with_cause_chain {
                     handler = handler.with_cause_chain();
@@ -233,6 +319,22 @@ impl MietteHandlerOpts {
             if let Some(w) = self.tab_width {
                 handler = handler.tab_width(w);
             }
+            if let Some(b) = self.break_words {
+                handler = handler.with_break_words(b)
+            }
+            if let Some(b) = self.wrap_lines {
+                handler = handler.with_wrap_lines(b)
+            }
+            if let Some(s) = self.word_separator {
+                handler = handler.with_word_separator(s)
+            }
+            if let Some(s) = self.word_splitter {
+                handler = handler.with_word_splitter(s)
+            }
+            if let Some(b) = self.show_related_as_nested {
+                handler = handler.with_show_related_as_nested(b)
+            }
+
             MietteHandler {
                 inner: Box::new(handler),
             }
@@ -257,26 +359,13 @@ impl MietteHandlerOpts {
         if let Some(linkify) = self.linkify {
             linkify
         } else {
-            supports_hyperlinks::on(Stream::Stderr)
+            syscall::supports_hyperlinks()
         }
     }
 
-    #[cfg(not(miri))]
     pub(crate) fn get_width(&self) -> usize {
-        self.width.unwrap_or_else(|| {
-            terminal_size::terminal_size()
-                .unwrap_or((terminal_size::Width(80), terminal_size::Height(0)))
-                .0
-                 .0 as usize
-        })
-    }
-
-    #[cfg(miri)]
-    // miri doesn't support a syscall (specifically ioctl)
-    // performed by terminal_size, which causes test execution to fail
-    // so when miri is running we'll just fallback to a constant
-    pub(crate) fn get_width(&self) -> usize {
-        self.width.unwrap_or(80)
+        self.width
+            .unwrap_or_else(|| syscall::terminal_width().unwrap_or(80))
     }
 }
 
@@ -313,7 +402,7 @@ impl Default for MietteHandler {
 }
 
 impl ReportHandler for MietteHandler {
-    fn debug(&self, diagnostic: &(dyn Diagnostic), f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    fn debug(&self, diagnostic: &dyn Diagnostic, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         if f.alternate() {
             return fmt::Debug::fmt(diagnostic, f);
         }
@@ -321,3 +410,219 @@ impl ReportHandler for MietteHandler {
         self.inner.debug(diagnostic, f)
     }
 }
+
+enum HighlighterOption {
+    Disable,
+    EnableCustom(MietteHighlighter),
+    #[cfg(feature = "syntect-highlighter")]
+    EnableSyntect,
+}
+
+impl HighlighterOption {
+    fn select(
+        color: Option<bool>,
+        highlighter: Option<MietteHighlighter>,
+        supports_color: bool,
+    ) -> HighlighterOption {
+        if color == Some(false) || (color.is_none() && !supports_color) {
+            return HighlighterOption::Disable;
+        }
+        highlighter
+            .map(HighlighterOption::EnableCustom)
+            .unwrap_or_default()
+    }
+}
+
+// NOTE: This is manually implemented so that it's clearer what's going on with
+// the conditional compilation — clippy isn't picking up the `cfg` stuff here
+#[allow(clippy::derivable_impls)]
+impl Default for HighlighterOption {
+    fn default() -> Self {
+        cfg_if! {
+            if #[cfg(feature = "syntect-highlighter")] {
+                // Because the syntect highlighter currently only supports 24-bit truecolor,
+                // it supersedes and ignores the `rgb_colors` config.
+                // TODO: In the future, if we find a way to convert the RGB syntect theme
+                // into an ANSI color theme, we can take `rgb_colors` into account.
+                HighlighterOption::EnableSyntect
+            } else {
+                HighlighterOption::Disable
+            }
+        }
+    }
+}
+
+impl From<HighlighterOption> for MietteHighlighter {
+    fn from(opt: HighlighterOption) -> Self {
+        match opt {
+            HighlighterOption::Disable => MietteHighlighter::nocolor(),
+            HighlighterOption::EnableCustom(highlighter) => highlighter,
+            #[cfg(feature = "syntect-highlighter")]
+            HighlighterOption::EnableSyntect => MietteHighlighter::syntect_truecolor(),
+        }
+    }
+}
+
+mod syscall {
+    use cfg_if::cfg_if;
+
+    #[inline]
+    pub(super) fn terminal_width() -> Option<usize> {
+        cfg_if! {
+            if #[cfg(any(feature = "fancy-no-syscall", miri))] {
+                None
+            } else {
+                terminal_size::terminal_size().map(|size| size.0 .0 as usize)
+            }
+        }
+    }
+
+    #[inline]
+    pub(super) fn supports_hyperlinks() -> bool {
+        cfg_if! {
+            if #[cfg(feature = "fancy-no-syscall")] {
+                false
+            } else {
+                supports_hyperlinks::on(supports_hyperlinks::Stream::Stderr)
+            }
+        }
+    }
+
+    #[inline]
+    pub(super) fn supports_color() -> bool {
+        cfg_if! {
+            if #[cfg(feature = "fancy-no-syscall")] {
+                false
+            } else {
+                supports_color::on(supports_color::Stream::Stderr).is_some()
+            }
+        }
+    }
+
+    #[inline]
+    pub(super) fn supports_color_has_16m() -> Option<bool> {
+        cfg_if! {
+            if #[cfg(feature = "fancy-no-syscall")] {
+                None
+            } else {
+                supports_color::on(supports_color::Stream::Stderr).map(|color| color.has_16m)
+            }
+        }
+    }
+
+    #[inline]
+    pub(super) fn supports_unicode() -> bool {
+        cfg_if! {
+            if #[cfg(feature = "fancy-no-syscall")] {
+                false
+            } else {
+                supports_unicode::on(supports_unicode::Stream::Stderr)
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::highlighters::BlankHighlighter;
+    use cfg_if::cfg_if;
+
+    #[test]
+    fn test_highlighter_option() {
+        // Syntax highlighting is enabled depending on several variables:
+        // - The `color` config
+        // - The `highlighter` config
+        // - Whether the `syntect-highlighter` feature is enabled
+        // - Whether the terminal supports color
+        //
+        // This test asserts the expected highlighter depending on combinations of those variables.
+
+        macro_rules! assert_highlighter_opt {
+            (opts = $opts:expr, supports_color = $sup_color:literal, expected = $expected:pat $(,)?) => {
+                assert_highlighter_opt!(
+                    opts = $opts,
+                    supports_color = $sup_color,
+                    expected_with_syntect = $expected,
+                    expected_without_syntect = $expected,
+                );
+            };
+
+            (
+                opts = $opts:expr,
+                supports_color = $sup_color:literal,
+                expected_with_syntect = $expected_with:pat,
+                expected_without_syntect = $expected_without:pat $(,)?
+            ) => {{
+                let highlighter_opt =
+                    HighlighterOption::select($opts.color, $opts.highlighter, $sup_color);
+                cfg_if! {
+                    if #[cfg(feature = "syntect-highlighter")] {
+                        assert!(matches!(highlighter_opt, $expected_with));
+                    } else {
+                        assert!(matches!(highlighter_opt, $expected_without));
+                    }
+                }
+            }};
+        }
+
+        // When color is explicitly disabled, highlighting is also always disabled.
+        assert_highlighter_opt!(
+            opts = MietteHandlerOpts::new().color(false),
+            supports_color = true,
+            expected = HighlighterOption::Disable,
+        );
+
+        // When color is unset and the terminal doesn't support color, highlighting is disabled.
+        assert_highlighter_opt!(
+            opts = MietteHandlerOpts::new(),
+            supports_color = false,
+            expected = HighlighterOption::Disable,
+        );
+
+        // With explicit or implicit color support, highlighting is automatically enabled when
+        // `syntect-highlighter` is enabled.
+        assert_highlighter_opt!(
+            opts = MietteHandlerOpts::new().color(true),
+            supports_color = false,
+            expected_with_syntect = HighlighterOption::EnableSyntect,
+            expected_without_syntect = HighlighterOption::Disable,
+        );
+        assert_highlighter_opt!(
+            opts = MietteHandlerOpts::new(),
+            supports_color = true,
+            expected_with_syntect = HighlighterOption::EnableSyntect,
+            expected_without_syntect = HighlighterOption::Disable,
+        );
+
+        // With explicit or implicit color support, if custom highlighting is set, it's enabled.
+        assert_highlighter_opt!(
+            opts = MietteHandlerOpts::new()
+                .color(true)
+                .with_syntax_highlighting(BlankHighlighter),
+            supports_color = false,
+            expected = HighlighterOption::EnableCustom(_),
+        );
+        assert_highlighter_opt!(
+            opts = MietteHandlerOpts::new().with_syntax_highlighting(BlankHighlighter),
+            supports_color = true,
+            expected = HighlighterOption::EnableCustom(_),
+        );
+
+        // Setting `RgbColors::Never` has no effect when syntax highlighting is enabled.
+        assert_highlighter_opt!(
+            opts = MietteHandlerOpts::new()
+                .color(true)
+                .rgb_colors(RgbColors::Never),
+            supports_color = false,
+            expected_with_syntect = HighlighterOption::EnableSyntect,
+            expected_without_syntect = HighlighterOption::Disable,
+        );
+        assert_highlighter_opt!(
+            opts = MietteHandlerOpts::new().rgb_colors(RgbColors::Never),
+            supports_color = true,
+            expected_with_syntect = HighlighterOption::EnableSyntect,
+            expected_without_syntect = HighlighterOption::Disable,
+        );
+    }
+}

src/handlers/debug.rs

@@ -13,7 +13,7 @@ pub struct DebugReportHandler;
 impl DebugReportHandler {
     /// Create a new [`NarratableReportHandler`](crate::NarratableReportHandler)
     /// There are no customization options.
-    pub fn new() -> Self {
+    pub const fn new() -> Self {
         Self
     }
 }
@@ -31,7 +31,7 @@ impl DebugReportHandler {
     pub fn render_report(
         &self,
         f: &mut fmt::Formatter<'_>,
-        diagnostic: &(dyn Diagnostic),
+        diagnostic: &dyn Diagnostic,
     ) -> fmt::Result {
         let mut diag = f.debug_struct("Diagnostic");
         diag.field("message", &format!("{}", diagnostic));
@@ -61,7 +61,7 @@ impl DebugReportHandler {
 }
 
 impl ReportHandler for DebugReportHandler {
-    fn debug(&self, diagnostic: &(dyn Diagnostic), f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    fn debug(&self, diagnostic: &dyn Diagnostic, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         if f.alternate() {
             return fmt::Debug::fmt(diagnostic, f);
         }

src/handlers/json.rs

@@ -13,7 +13,7 @@ pub struct JSONReportHandler;
 impl JSONReportHandler {
     /// Create a new [`JSONReportHandler`]. There are no customization
     /// options.
-    pub fn new() -> Self {
+    pub const fn new() -> Self {
         Self
     }
 }
@@ -49,7 +49,7 @@ impl fmt::Display for Escape<'_> {
     }
 }
 
-fn escape(input: &'_ str) -> Escape<'_> {
+const fn escape(input: &'_ str) -> Escape<'_> {
     Escape(input)
 }
 
@@ -60,7 +60,7 @@ impl JSONReportHandler {
     pub fn render_report(
         &self,
         f: &mut impl fmt::Write,
-        diagnostic: &(dyn Diagnostic),
+        diagnostic: &dyn Diagnostic,
     ) -> fmt::Result {
         self._render_report(f, diagnostic, None)
     }
@@ -68,7 +68,7 @@ impl JSONReportHandler {
     fn _render_report(
         &self,
         f: &mut impl fmt::Write,
-        diagnostic: &(dyn Diagnostic),
+        diagnostic: &dyn Diagnostic,
         parent_src: Option<&dyn SourceCode>,
     ) -> fmt::Result {
         write!(f, r#"{{"message": "{}","#, escape(&diagnostic.to_string()))?;
@@ -96,7 +96,7 @@ impl JSONReportHandler {
                 }
                 write!(f, r#""{}""#, escape(&error.to_string()))?;
             }
-            write!(f, "],")?
+            write!(f, "],")?;
         } else {
             write!(f, r#""causes": [],"#)?;
         }
@@ -154,7 +154,7 @@ impl JSONReportHandler {
     fn render_snippets(
         &self,
         f: &mut impl fmt::Write,
-        diagnostic: &(dyn Diagnostic),
+        diagnostic: &dyn Diagnostic,
         source: &dyn SourceCode,
     ) -> fmt::Result {
         if let Some(mut labels) = diagnostic.labels() {
@@ -170,7 +170,7 @@ impl JSONReportHandler {
 }
 
 impl ReportHandler for JSONReportHandler {
-    fn debug(&self, diagnostic: &(dyn Diagnostic), f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    fn debug(&self, diagnostic: &dyn Diagnostic, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         self.render_report(f, diagnostic)
     }
 }

src/handlers/mod.rs

@@ -5,20 +5,20 @@ Reporters included with `miette`.
 #[allow(unreachable_pub)]
 pub use debug::*;
 #[allow(unreachable_pub)]
-#[cfg(feature = "fancy-no-backtrace")]
+#[cfg(feature = "fancy-base")]
 pub use graphical::*;
 #[allow(unreachable_pub)]
 pub use json::*;
 #[allow(unreachable_pub)]
 pub use narratable::*;
 #[allow(unreachable_pub)]
-#[cfg(feature = "fancy-no-backtrace")]
+#[cfg(feature = "fancy-base")]
 pub use theme::*;
 
 mod debug;
-#[cfg(feature = "fancy-no-backtrace")]
+#[cfg(feature = "fancy-base")]
 mod graphical;
 mod json;
 mod narratable;
-#[cfg(feature = "fancy-no-backtrace")]
+#[cfg(feature = "fancy-base")]
 mod theme;

src/handlers/narratable.rs

@@ -21,7 +21,7 @@ pub struct NarratableReportHandler {
 impl NarratableReportHandler {
     /// Create a new [`NarratableReportHandler`]. There are no customization
     /// options.
-    pub fn new() -> Self {
+    pub const fn new() -> Self {
         Self {
             footer: None,
             context_lines: 1,
@@ -31,13 +31,13 @@ impl NarratableReportHandler {
 
     /// Include the cause chain of the top-level error in the report, if
     /// available.
-    pub fn with_cause_chain(mut self) -> Self {
+    pub const fn with_cause_chain(mut self) -> Self {
         self.with_cause_chain = true;
         self
     }
 
     /// Do not include the cause chain of the top-level error in the report.
-    pub fn without_cause_chain(mut self) -> Self {
+    pub const fn without_cause_chain(mut self) -> Self {
         self.with_cause_chain = false;
         self
     }
@@ -49,7 +49,7 @@ impl NarratableReportHandler {
     }
 
     /// Sets the number of lines of context to show around each error.
-    pub fn with_context_lines(mut self, lines: usize) -> Self {
+    pub const fn with_context_lines(mut self, lines: usize) -> Self {
         self.context_lines = lines;
         self
     }
@@ -69,7 +69,7 @@ impl NarratableReportHandler {
     pub fn render_report(
         &self,
         f: &mut impl fmt::Write,
-        diagnostic: &(dyn Diagnostic),
+        diagnostic: &dyn Diagnostic,
     ) -> fmt::Result {
         self.render_header(f, diagnostic)?;
         if self.with_cause_chain {
@@ -85,7 +85,7 @@ impl NarratableReportHandler {
         Ok(())
     }
 
-    fn render_header(&self, f: &mut impl fmt::Write, diagnostic: &(dyn Diagnostic)) -> fmt::Result {
+    fn render_header(&self, f: &mut impl fmt::Write, diagnostic: &dyn Diagnostic) -> fmt::Result {
         writeln!(f, "{}", diagnostic)?;
         let severity = match diagnostic.severity() {
             Some(Severity::Error) | None => "error",
@@ -96,7 +96,7 @@ impl NarratableReportHandler {
         Ok(())
     }
 
-    fn render_causes(&self, f: &mut impl fmt::Write, diagnostic: &(dyn Diagnostic)) -> fmt::Result {
+    fn render_causes(&self, f: &mut impl fmt::Write, diagnostic: &dyn Diagnostic) -> fmt::Result {
         if let Some(cause_iter) = diagnostic
             .diagnostic_source()
             .map(DiagnosticChain::from_diagnostic)
@@ -110,7 +110,7 @@ impl NarratableReportHandler {
         Ok(())
     }
 
-    fn render_footer(&self, f: &mut impl fmt::Write, diagnostic: &(dyn Diagnostic)) -> fmt::Result {
+    fn render_footer(&self, f: &mut impl fmt::Write, diagnostic: &dyn Diagnostic) -> fmt::Result {
         if let Some(help) = diagnostic.help() {
             writeln!(f, "diagnostic help: {}", help)?;
         }
@@ -118,7 +118,7 @@ impl NarratableReportHandler {
             writeln!(f, "diagnostic code: {}", code)?;
         }
         if let Some(url) = diagnostic.url() {
-            writeln!(f, "For more details, see {}", url)?;
+            writeln!(f, "For more details, see:\n{}", url)?;
         }
         Ok(())
     }
@@ -126,13 +126,13 @@ impl NarratableReportHandler {
     fn render_related(
         &self,
         f: &mut impl fmt::Write,
-        diagnostic: &(dyn Diagnostic),
+        diagnostic: &dyn Diagnostic,
         parent_src: Option<&dyn SourceCode>,
     ) -> fmt::Result {
         if let Some(related) = diagnostic.related() {
             writeln!(f)?;
             for rel in related {
-                match diagnostic.severity() {
+                match rel.severity() {
                     Some(Severity::Error) | None => write!(f, "Error: ")?,
                     Some(Severity::Warning) => write!(f, "Warning: ")?,
                     Some(Severity::Advice) => write!(f, "Advice: ")?,
@@ -152,7 +152,7 @@ impl NarratableReportHandler {
     fn render_snippets(
         &self,
         f: &mut impl fmt::Write,
-        diagnostic: &(dyn Diagnostic),
+        diagnostic: &dyn Diagnostic,
         source_code: Option<&dyn SourceCode>,
     ) -> fmt::Result {
         if let Some(source) = source_code {
@@ -218,10 +218,10 @@ impl NarratableReportHandler {
         Ok(())
     }
 
-    fn render_context<'a>(
+    fn render_context(
         &self,
         f: &mut impl fmt::Write,
-        source: &'a dyn SourceCode,
+        source: &dyn SourceCode,
         context: &LabeledSpan,
         labels: &[LabeledSpan],
     ) -> fmt::Result {
@@ -295,9 +295,9 @@ impl NarratableReportHandler {
         let mut column = context_data.column();
         let mut offset = context_data.span().offset();
         let mut line_offset = offset;
+        let mut line_str = String::with_capacity(context.len());
+        let mut lines = Vec::with_capacity(1);
         let mut iter = context.chars().peekable();
-        let mut line_str = String::new();
-        let mut lines = Vec::new();
         while let Some(char) = iter.next() {
             offset += char.len_utf8();
             let mut at_end_of_file = false;
@@ -344,7 +344,7 @@ impl NarratableReportHandler {
 }
 
 impl ReportHandler for NarratableReportHandler {
-    fn debug(&self, diagnostic: &(dyn Diagnostic), f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    fn debug(&self, diagnostic: &dyn Diagnostic, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         if f.alternate() {
             return fmt::Debug::fmt(diagnostic, f);
         }

src/handlers/theme.rs

@@ -1,4 +1,5 @@
-use atty::Stream;
+use std::io::IsTerminal;
+
 use owo_colors::Style;
 
 /**
@@ -31,10 +32,16 @@ impl GraphicalTheme {
 
     /// Graphical theme that draws using both ansi colors and unicode
     /// characters.
+    ///
+    /// Note that full rgb colors aren't enabled by default because they're
+    /// an accessibility hazard, especially in the context of terminal themes
+    /// that can change the background color and make hardcoded colors illegible.
+    /// Such themes typically remap ansi codes properly, treating them more
+    /// like CSS classes than specific colors.
     pub fn unicode() -> Self {
         Self {
             characters: ThemeCharacters::unicode(),
-            styles: ThemeStyles::rgb(),
+            styles: ThemeStyles::ansi(),
         }
     }
 
@@ -49,9 +56,9 @@ impl GraphicalTheme {
 
     /// A "basic" graphical theme that skips colors and unicode characters and
     /// just does monochrome ascii art. If you want a completely non-graphical
-    /// rendering of your `Diagnostic`s, check out
-    /// [crate::NarratableReportHandler], or write your own
-    /// [crate::ReportHandler]!
+    /// rendering of your [`Diagnostic`](crate::Diagnostic)s, check out
+    /// [`NarratableReportHandler`](crate::NarratableReportHandler), or write
+    /// your own [`ReportHandler`](crate::ReportHandler)
     pub fn none() -> Self {
         Self {
             characters: ThemeCharacters::ascii(),
@@ -63,7 +70,9 @@ impl GraphicalTheme {
 impl Default for GraphicalTheme {
     fn default() -> Self {
         match std::env::var("NO_COLOR") {
-            _ if !atty::is(Stream::Stdout) || !atty::is(Stream::Stderr) => Self::ascii(),
+            _ if !std::io::stdout().is_terminal() || !std::io::stderr().is_terminal() => {
+                Self::none()
+            }
             Ok(string) if string != "0" => Self::unicode_nocolor(),
             _ => Self::unicode(),
         }
@@ -71,7 +80,8 @@ impl Default for GraphicalTheme {
 }
 
 /**
-Styles for various parts of graphical rendering for the [crate::GraphicalReportHandler].
+Styles for various parts of graphical rendering for the
+[`GraphicalReportHandler`](crate::GraphicalReportHandler).
 */
 #[derive(Debug, Clone)]
 pub struct ThemeStyles {
@@ -151,7 +161,7 @@ impl ThemeStyles {
 // https://github.com/zesterer/ariadne/blob/e3cb394cb56ecda116a0a1caecd385a49e7f6662/src/draw.rs
 
 /// Characters to be used when drawing when using
-/// [crate::GraphicalReportHandler].
+/// [`GraphicalReportHandler`](crate::GraphicalReportHandler).
 #[allow(missing_docs)]
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct ThemeCharacters {

src/highlighters/blank.rs

@@ -0,0 +1,36 @@
+use owo_colors::Style;
+
+use crate::SpanContents;
+
+use super::{Highlighter, HighlighterState};
+
+/// The default syntax highlighter. It applies `Style::default()` to input text.
+/// This is used by default when no syntax highlighting features are enabled.
+#[derive(Debug, Clone)]
+pub struct BlankHighlighter;
+
+impl Highlighter for BlankHighlighter {
+    fn start_highlighter_state<'h>(
+        &'h self,
+        _source: &dyn SpanContents<'_>,
+    ) -> Box<dyn super::HighlighterState + 'h> {
+        Box::new(BlankHighlighterState)
+    }
+}
+
+impl Default for BlankHighlighter {
+    fn default() -> Self {
+        BlankHighlighter
+    }
+}
+
+/// The default highlighter state. It applies `Style::default()` to input text.
+/// This is used by default when no syntax highlighting features are enabled.
+#[derive(Debug, Clone)]
+pub struct BlankHighlighterState;
+
+impl HighlighterState for BlankHighlighterState {
+    fn highlight_line<'s>(&mut self, line: &'s str) -> Vec<owo_colors::Styled<&'s str>> {
+        vec![Style::default().style(line)]
+    }
+}

src/highlighters/mod.rs

@@ -0,0 +1,116 @@
+//! This module provides a trait for creating custom syntax highlighters that
+//! highlight [`Diagnostic`](crate::Diagnostic) source code with ANSI escape
+//! sequences when rendering with the [`GraphicalReportHighlighter`](crate::GraphicalReportHandler).
+//!
+//! It also provides built-in highlighter implementations that you can use out of the box.
+//! By default, there are no syntax highlighters exported by miette
+//! (except for the no-op [`BlankHighlighter`]).
+//! To enable support for specific highlighters, you should enable their associated feature flag.
+//!
+//! Currently supported syntax highlighters and their feature flags:
+//! * `syntect-highlighter` - Enables [`syntect`](https://docs.rs/syntect/latest/syntect/) syntax highlighting support via the [`SyntectHighlighter`]
+//!
+
+use std::{ops::Deref, sync::Arc};
+
+use crate::SpanContents;
+use owo_colors::Styled;
+
+#[cfg(feature = "syntect-highlighter")]
+pub use self::syntect::*;
+pub use blank::*;
+
+mod blank;
+#[cfg(feature = "syntect-highlighter")]
+mod syntect;
+
+/// A syntax highlighter for highlighting miette [`SourceCode`](crate::SourceCode) snippets.
+pub trait Highlighter {
+    ///  Creates a new [`HighlighterState`] to begin parsing and highlighting
+    /// a [`SpanContents`].
+    ///
+    /// The [`GraphicalReportHandler`](crate::GraphicalReportHandler) will call
+    /// this method at the start of rendering a [`SpanContents`].
+    ///
+    /// The [`SpanContents`] is provided as input only so that the [`Highlighter`]
+    /// can detect language syntax and make other initialization decisions prior
+    /// to highlighting, but it is not intended that the Highlighter begin
+    /// highlighting at this point. The returned [`HighlighterState`] is
+    /// responsible for the actual rendering.
+    fn start_highlighter_state<'h>(
+        &'h self,
+        source: &dyn SpanContents<'_>,
+    ) -> Box<dyn HighlighterState + 'h>;
+}
+
+/// A stateful highlighter that incrementally highlights lines of a particular
+/// source code.
+///
+/// The [`GraphicalReportHandler`](crate::GraphicalReportHandler)
+/// will create a highlighter state by calling
+/// [`start_highlighter_state`](Highlighter::start_highlighter_state) at the
+/// start of rendering, then it will iteratively call
+/// [`highlight_line`](HighlighterState::highlight_line) to render individual
+/// highlighted lines. This allows [`Highlighter`] implementations to maintain
+/// mutable parsing and highlighting state.
+pub trait HighlighterState {
+    /// Highlight an individual line from the source code by returning a vector of [Styled]
+    /// regions.
+    fn highlight_line<'s>(&mut self, line: &'s str) -> Vec<Styled<&'s str>>;
+}
+
+/// Arcified trait object for Highlighter. Used internally by [`GraphicalReportHandler`]
+///
+/// Wrapping the trait object in this way allows us to implement `Debug` and `Clone`.
+#[derive(Clone)]
+#[repr(transparent)]
+pub(crate) struct MietteHighlighter(Arc<dyn Highlighter + Send + Sync>);
+
+impl MietteHighlighter {
+    pub(crate) fn nocolor() -> Self {
+        Self::from(BlankHighlighter)
+    }
+
+    #[cfg(feature = "syntect-highlighter")]
+    pub(crate) fn syntect_truecolor() -> Self {
+        Self::from(SyntectHighlighter::default())
+    }
+}
+
+impl Default for MietteHighlighter {
+    #[cfg(feature = "syntect-highlighter")]
+    fn default() -> Self {
+        use std::io::IsTerminal;
+        match std::env::var("NO_COLOR") {
+            _ if !std::io::stdout().is_terminal() || !std::io::stderr().is_terminal() => {
+                //TODO: should use ANSI styling instead of 24-bit truecolor here
+                Self(Arc::new(SyntectHighlighter::default()))
+            }
+            Ok(string) if string != "0" => MietteHighlighter::nocolor(),
+            _ => Self(Arc::new(SyntectHighlighter::default())),
+        }
+    }
+    #[cfg(not(feature = "syntect-highlighter"))]
+    fn default() -> Self {
+        MietteHighlighter::nocolor()
+    }
+}
+
+impl<T: Highlighter + Send + Sync + 'static> From<T> for MietteHighlighter {
+    fn from(value: T) -> Self {
+        Self(Arc::new(value))
+    }
+}
+
+impl std::fmt::Debug for MietteHighlighter {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "MietteHighlighter(...)")
+    }
+}
+
+impl Deref for MietteHighlighter {
+    type Target = dyn Highlighter + Send + Sync;
+    fn deref(&self) -> &Self::Target {
+        &*self.0
+    }
+}

src/highlighters/syntect.rs

@@ -0,0 +1,171 @@
+use std::path::Path;
+
+// all syntect imports are explicitly qualified, but their paths are shortened for convenience
+#[allow(clippy::module_inception)]
+mod syntect {
+    pub(super) use syntect::{
+        highlighting::{
+            Color, HighlightIterator, HighlightState, Highlighter, Style, Theme, ThemeSet,
+        },
+        parsing::{ParseState, ScopeStack, SyntaxReference, SyntaxSet},
+    };
+}
+
+use owo_colors::{Rgb, Style, Styled};
+
+use crate::{
+    highlighters::{Highlighter, HighlighterState},
+    SpanContents,
+};
+
+use super::BlankHighlighterState;
+
+/// Highlights miette [`SpanContents`] with the [syntect](https://docs.rs/syntect/latest/syntect/) highlighting crate.
+///
+/// Currently only 24-bit truecolor output is supported due to syntect themes
+/// representing color as RGBA.
+#[derive(Debug, Clone)]
+pub struct SyntectHighlighter {
+    theme: syntect::Theme,
+    syntax_set: syntect::SyntaxSet,
+    use_bg_color: bool,
+}
+
+impl Default for SyntectHighlighter {
+    fn default() -> Self {
+        let theme_set = syntect::ThemeSet::load_defaults();
+        let theme = theme_set.themes["base16-ocean.dark"].clone();
+        Self::new_themed(theme, false)
+    }
+}
+
+impl Highlighter for SyntectHighlighter {
+    fn start_highlighter_state<'h>(
+        &'h self,
+        source: &dyn SpanContents<'_>,
+    ) -> Box<dyn HighlighterState + 'h> {
+        if let Some(syntax) = self.detect_syntax(source) {
+            let highlighter = syntect::Highlighter::new(&self.theme);
+            let parse_state = syntect::ParseState::new(syntax);
+            let highlight_state =
+                syntect::HighlightState::new(&highlighter, syntect::ScopeStack::new());
+            Box::new(SyntectHighlighterState {
+                syntax_set: &self.syntax_set,
+                highlighter,
+                parse_state,
+                highlight_state,
+                use_bg_color: self.use_bg_color,
+            })
+        } else {
+            Box::new(BlankHighlighterState)
+        }
+    }
+}
+
+impl SyntectHighlighter {
+    /// Create a syntect highlighter with the given theme and syntax set.
+    pub fn new(syntax_set: syntect::SyntaxSet, theme: syntect::Theme, use_bg_color: bool) -> Self {
+        Self {
+            theme,
+            syntax_set,
+            use_bg_color,
+        }
+    }
+
+    /// Create a syntect highlighter with the given theme and the default syntax set.
+    pub fn new_themed(theme: syntect::Theme, use_bg_color: bool) -> Self {
+        Self::new(
+            syntect::SyntaxSet::load_defaults_nonewlines(),
+            theme,
+            use_bg_color,
+        )
+    }
+
+    /// Determine syntect [`SyntaxReference`] to use for given [`SpanContents`].
+    fn detect_syntax(&self, contents: &dyn SpanContents<'_>) -> Option<&syntect::SyntaxReference> {
+        // use language if given
+        if let Some(language) = contents.language() {
+            return self.syntax_set.find_syntax_by_name(language);
+        }
+        // otherwise try to use any file extension provided in the name
+        if let Some(name) = contents.name() {
+            if let Some(ext) = Path::new(name).extension() {
+                return self
+                    .syntax_set
+                    .find_syntax_by_extension(ext.to_string_lossy().as_ref());
+            }
+        }
+        // finally, attempt to guess syntax based on first line
+        self.syntax_set.find_syntax_by_first_line(
+            std::str::from_utf8(contents.data())
+                .ok()?
+                .split('\n')
+                .next()?,
+        )
+    }
+}
+
+/// Stateful highlighting iterator for [`SyntectHighlighter`].
+#[derive(Debug)]
+pub(crate) struct SyntectHighlighterState<'h> {
+    syntax_set: &'h syntect::SyntaxSet,
+    highlighter: syntect::Highlighter<'h>,
+    parse_state: syntect::ParseState,
+    highlight_state: syntect::HighlightState,
+    use_bg_color: bool,
+}
+
+impl HighlighterState for SyntectHighlighterState<'_> {
+    fn highlight_line<'s>(&mut self, line: &'s str) -> Vec<Styled<&'s str>> {
+        if let Ok(ops) = self.parse_state.parse_line(line, self.syntax_set) {
+            let use_bg_color = self.use_bg_color;
+            syntect::HighlightIterator::new(
+                &mut self.highlight_state,
+                &ops,
+                line,
+                &self.highlighter,
+            )
+            .map(|(style, str)| convert_style(style, use_bg_color).style(str))
+            .collect()
+        } else {
+            vec![Style::default().style(line)]
+        }
+    }
+}
+
+/// Convert syntect [`syntect::Style`] into `owo_colors` [`Style`]
+#[inline]
+fn convert_style(syntect_style: syntect::Style, use_bg_color: bool) -> Style {
+    if use_bg_color {
+        let fg = blend_fg_color(syntect_style);
+        let bg = convert_color(syntect_style.background);
+        Style::new().color(fg).on_color(bg)
+    } else {
+        let fg = convert_color(syntect_style.foreground);
+        Style::new().color(fg)
+    }
+}
+
+/// Blend foreground RGB into background RGB according to alpha channel
+#[inline]
+fn blend_fg_color(syntect_style: syntect::Style) -> Rgb {
+    let fg = syntect_style.foreground;
+    if fg.a == 0xff {
+        return convert_color(fg);
+    }
+    let bg = syntect_style.background;
+    let ratio = fg.a as u32;
+    let r = (fg.r as u32 * ratio + bg.r as u32 * (255 - ratio)) / 255;
+    let g = (fg.g as u32 * ratio + bg.g as u32 * (255 - ratio)) / 255;
+    let b = (fg.b as u32 * ratio + bg.b as u32 * (255 - ratio)) / 255;
+    Rgb(r as u8, g as u8, b as u8)
+}
+
+/// Convert syntect color into owo color.
+///
+/// Note: ignores alpha channel. use [`blend_fg_color`] if you need that
+///
+#[inline]
+fn convert_color(color: syntect::Color) -> Rgb {
+    Rgb(color.r, color.g, color.b)
+}

src/lib.rs

@@ -1,5 +1,6 @@
 #![deny(missing_docs, missing_debug_implementations, nonstandard_style)]
 #![warn(unreachable_pub, rust_2018_idioms)]
+#![allow(unexpected_cfgs)]
 //! You run miette? You run her code like the software? Oh. Oh! Error code for
 //! coder! Error code for One Thousand Lines!
 //!
@@ -27,9 +28,9 @@
 //! " />
 //!
 //! > **NOTE: You must enable the `"fancy"` crate feature to get fancy report
-//! output like in the screenshots above.** You should only do this in your
-//! toplevel crate, as the fancy feature pulls in a number of dependencies that
-//! libraries and such might not want.
+//! > output like in the screenshots above.** You should only do this in your
+//! > toplevel crate, as the fancy feature pulls in a number of dependencies that
+//! > libraries and such might not want.
 //!
 //! ## Table of Contents <!-- omit in toc -->
 //!
@@ -43,9 +44,15 @@
 //!   - [... in `main()`](#-in-main)
 //!   - [... diagnostic code URLs](#-diagnostic-code-urls)
 //!   - [... snippets](#-snippets)
+//!   - [... help text](#-help-text)
+//!   - [... severity level](#-severity-level)
 //!   - [... multiple related errors](#-multiple-related-errors)
 //!   - [... delayed source code](#-delayed-source-code)
 //!   - [... handler options](#-handler-options)
+//!   - [... dynamic diagnostics](#-dynamic-diagnostics)
+//!   - [... syntax highlighting](#-syntax-highlighting)
+//!   - [... primary label](#-primary-label)
+//!   - [... collection of labels](#-collection-of-labels)
 //! - [Acknowledgements](#acknowledgements)
 //! - [License](#license)
 //!
@@ -94,7 +101,7 @@
 //!
 //! `thiserror` is a great way to define them, and plays nicely with `miette`!
 //! */
-//! use miette::{Diagnostic, SourceSpan};
+//! use miette::{Diagnostic, NamedSource, SourceSpan};
 //! use thiserror::Error;
 //!
 //! #[derive(Error, Debug, Diagnostic)]
@@ -108,7 +115,7 @@
 //!     // The Source that we're gonna be printing snippets out of.
 //!     // This can be a String if you don't have or care about file names.
 //!     #[source_code]
-//!     src: NamedSource,
+//!     src: NamedSource<String>,
 //!     // Snippets and highlights can be included in the diagnostic!
 //!     #[label("This bit here")]
 //!     bad_bit: SourceSpan,
@@ -121,12 +128,11 @@
 //! throughout your app (but NOT your libraries! Those should always return
 //! concrete types!).
 //! */
-//! use miette::{NamedSource, Result};
+//! use miette::Result;
 //! fn this_fails() -> Result<()> {
 //!     // You can use plain strings as a `Source`, or anything that implements
 //!     // the one-method `Source` trait.
 //!     let src = "source\n  text\n    here".to_string();
-//!     let len = src.len();
 //!
 //!     Err(MyBad {
 //!         src: NamedSource::new("bad_file.rs", src),
@@ -156,17 +162,20 @@
 //! <img src="https://raw.githubusercontent.com/zkat/miette/main/images/single-line-example.png" alt="
 //! Narratable printout:
 //! \
-//! Error: Types mismatched for operation.
-//!     Diagnostic severity: error
-//! Begin snippet starting at line 1, column 1
+//! diagnostic error code: oops::my::bad (link)
+//! Error: oops!
 //! \
-//! snippet line 1: 3 + &quot;5&quot;
-//!     label starting at line 1, column 1: int
-//!     label starting at line 1, column 1: doesn't support these values.
-//!     label starting at line 1, column 1: string
-//! diagnostic help: Change int or string to be the right types and try again.
-//! diagnostic code: nu::parser::unsupported_operation
-//! For more details, see https://docs.rs/nu-parser/0.1.0/nu-parser/enum.ParseError.html#variant.UnsupportedOperation">
+//! Begin snippet for bad_file.rs starting
+//! at line 2, column 3
+//! \
+//! snippet line 1: source
+//! \
+//! snippet line 2:  text
+//!     highlight starting at line 1, column 3: This bit here
+//! \
+//! snippet line 3: here
+//! \
+//! diagnostic help: try doing it better next time?">
 //!
 //! ## Using
 //!
@@ -185,7 +194,7 @@
 //!
 //! ```rust
 //! // lib/error.rs
-//! use miette::Diagnostic;
+//! use miette::{Diagnostic, SourceSpan};
 //! use thiserror::Error;
 //!
 //! #[derive(Error, Diagnostic, Debug)]
@@ -197,6 +206,29 @@
 //!     #[error("Oops it blew up")]
 //!     #[diagnostic(code(my_lib::bad_code))]
 //!     BadThingHappened,
+//!
+//!     #[error(transparent)]
+//!     // Use `#[diagnostic(transparent)]` to wrap another [`Diagnostic`]. You won't see labels otherwise
+//!     #[diagnostic(transparent)]
+//!     AnotherError(#[from] AnotherError),
+//!
+//!     /// Forward the diagnostic to a particular field.
+//!     #[error("other error")]
+//!     #[diagnostic(forward(the_actual_diagnostic))]
+//!     EvenMoreData {
+//!         unrelated_field_1: String,
+//!         unrelated_field_2: usize,
+//!
+//!         #[source]
+//!         the_actual_diagnostic: AnotherError,
+//!     }
+//! }
+//!
+//! #[derive(Error, Diagnostic, Debug)]
+//! #[error("another error")]
+//! pub struct AnotherError {
+//!    #[label("here")]
+//!    pub at: SourceSpan
 //! }
 //! ```
 //!
@@ -224,7 +256,7 @@
 //! use semver::Version;
 //!
 //! pub fn some_tool() -> Result<Version> {
-//!     Ok("1.2.x".parse().into_diagnostic()?)
+//!     "1.2.x".parse().into_diagnostic()
 //! }
 //! ```
 //!
@@ -239,13 +271,28 @@
 //! use semver::Version;
 //!
 //! pub fn some_tool() -> Result<Version> {
-//!     Ok("1.2.x"
+//!     "1.2.x"
 //!         .parse()
 //!         .into_diagnostic()
-//!         .wrap_err("Parsing this tool's semver version failed.")?)
+//!         .wrap_err("Parsing this tool's semver version failed.")
 //! }
 //! ```
 //!
+//! To construct your own simple adhoc error use the [`miette!`] macro:
+//! ```rust
+//! // my_app/lib/my_internal_file.rs
+//! use miette::{miette, Result};
+//! use semver::Version;
+//!
+//! pub fn some_tool() -> Result<Version> {
+//!     let version = "1.2.x";
+//!     version
+//!         .parse()
+//!         .map_err(|_| miette!("Invalid version {}", version))
+//! }
+//! ```
+//! There are also similar [bail!] and [ensure!] macros.
+//!
 //! ### ... in `main()`
 //!
 //! `main()` is just like any other part of your application-internal code. Use
@@ -253,9 +300,9 @@
 //! automatically.
 //!
 //! > **NOTE:** You must enable the `"fancy"` crate feature to get fancy report
-//! output like in the screenshots here.** You should only do this in your
-//! toplevel crate, as the fancy feature pulls in a number of dependencies that
-//! libraries and such might not want.
+//! > output like in the screenshots here.** You should only do this in your
+//! > toplevel crate, as the fancy feature pulls in a number of dependencies that
+//! > libraries and such might not want.
 //!
 //! ```rust
 //! use miette::{IntoDiagnostic, Result};
@@ -276,6 +323,23 @@
 //! miette = { version = "X.Y.Z", features = ["fancy"] }
 //! ```
 //!
+//! Another way to display a diagnostic is by printing them using the debug formatter.
+//! This is, in fact, what returning diagnostics from main ends up doing.
+//! To do it yourself, you can write the following:
+//!
+//! ```rust
+//! use miette::{IntoDiagnostic, Result};
+//! use semver::Version;
+//!
+//! fn just_a_random_function() {
+//!     let version_result: Result<Version> = "1.2.x".parse().into_diagnostic();
+//!     match version_result {
+//!         Err(e) => println!("{:?}", e),
+//!         Ok(version) => println!("{}", version),
+//!     }
+//! }
+//! ```
+//!
 //! ### ... diagnostic code URLs
 //!
 //! `miette` supports providing a URL for individual diagnostics. This URL will
@@ -377,7 +441,7 @@
 //! }
 //! ```
 //!
-//! #### ... help text
+//! ### ... help text
 //! `miette` provides two facilities for supplying help text for your errors:
 //!
 //! The first is the `#[help()]` format attribute that applies to structs or
@@ -413,6 +477,19 @@
 //! };
 //! ```
 //!
+//! ### ... severity level
+//! `miette` provides a way to set the severity level of a diagnostic.
+//!
+//! ```rust
+//! use miette::Diagnostic;
+//! use thiserror::Error;
+//!
+//! #[derive(Debug, Diagnostic, Error)]
+//! #[error("welp")]
+//! #[diagnostic(severity(Warning))]
+//! struct Foo;
+//! ```
+//!
 //! ### ... multiple related errors
 //!
 //! `miette` supports collecting multiple errors into a single diagnostic, and
@@ -557,7 +634,7 @@
 //!
 //! Usage is like so:
 //!
-//! ```rust
+//! ```rust,ignore
 //! miette::set_hook(Box::new(|_| {
 //!     Box::new(
 //!         miette::MietteHandlerOpts::new()
@@ -565,16 +642,152 @@
 //!             .unicode(false)
 //!             .context_lines(3)
 //!             .tab_width(4)
+//!             .break_words(true)
 //!             .build(),
 //!     )
 //! }))
 //!
-//! # .unwrap()
 //! ```
 //!
 //! See the docs for [`MietteHandlerOpts`] for more details on what you can
 //! customize!
 //!
+//! ### ... dynamic diagnostics
+//!
+//! If you...
+//! - ...don't know all the possible errors upfront
+//! - ...need to serialize/deserialize errors
+//!   then you may want to use [`miette!`], [`diagnostic!`] macros or
+//!   [`MietteDiagnostic`] directly to create diagnostic on the fly.
+//!
+//! ```rust,ignore
+//! # use miette::{miette, LabeledSpan, Report};
+//!
+//! let source = "2 + 2 * 2 = 8".to_string();
+//! let report = miette!(
+//!   labels = vec![
+//!       LabeledSpan::at(12..13, "this should be 6"),
+//!   ],
+//!   help = "'*' has greater precedence than '+'",
+//!   "Wrong answer"
+//! ).with_source_code(source);
+//! println!("{:?}", report)
+//! ```
+//!
+//! ### ... syntax highlighting
+//!
+//! `miette` can be configured to highlight syntax in source code snippets.
+//!
+//! <!-- TODO: screenshot goes here once default Theme is decided -->
+//!
+//! To use the built-in highlighting functionality, you must enable the
+//! `syntect-highlighter` crate feature. When this feature is enabled, `miette` will
+//! automatically use the [`syntect`] crate to highlight the `#[source_code]`
+//! field of your [`Diagnostic`].
+//!
+//! Syntax detection with [`syntect`] is handled by checking 2 methods on the [`SpanContents`] trait, in order:
+//! * [`language()`](SpanContents::language) - Provides the name of the language
+//!   as a string. For example `"Rust"` will indicate Rust syntax highlighting.
+//!   You can set the language of the [`SpanContents`] produced by a
+//!   [`NamedSource`] via the [`with_language`](NamedSource::with_language)
+//!   method.
+//! * [`name()`](SpanContents::name) - In the absence of an explicitly set
+//!   language, the name is assumed to contain a file name or file path.
+//!   The highlighter will check for a file extension at the end of the name and
+//!   try to guess the syntax from that.
+//!
+//! If you want to use a custom highlighter, you can provide a custom
+//! implementation of the [`Highlighter`](highlighters::Highlighter)
+//! trait to [`MietteHandlerOpts`] by calling the
+//! [`with_syntax_highlighting`](MietteHandlerOpts::with_syntax_highlighting)
+//! method. See the [`highlighters`] module docs for more details.
+//!
+//! ### ... primary label
+//!
+//! You can use the `primary` parameter to `label` to indicate that the label
+//! is the primary label.
+//!
+//! ```rust,ignore
+//! #[derive(Debug, Diagnostic, Error)]
+//! #[error("oops!")]
+//! struct MyError {
+//!     #[label(primary, "main issue")]
+//!     primary_span: SourceSpan,
+//!
+//!     #[label("other label")]
+//!     other_span: SourceSpan,
+//! }
+//! ```
+//!
+//! The `primary` parameter can be used at most once:
+//!
+//! ```rust,ignore
+//! #[derive(Debug, Diagnostic, Error)]
+//! #[error("oops!")]
+//! struct MyError {
+//!     #[label(primary, "main issue")]
+//!     primary_span: SourceSpan,
+//!
+//!     #[label(primary, "other label")] // Error: Cannot have more than one primary label.
+//!     other_span: SourceSpan,
+//! }
+//! ```
+//!
+//! ### ... collection of labels
+//!
+//! When the number of labels is unknown, you can use a collection of `SourceSpan`
+//! (or any type convertible into `SourceSpan`). For this, add the `collection`
+//! parameter to `label` and use any type than can be iterated over for the field.
+//!
+//! ```rust,ignore
+//! #[derive(Debug, Diagnostic, Error)]
+//! #[error("oops!")]
+//! struct MyError {
+//!     #[label("main issue")]
+//!     primary_span: SourceSpan,
+//!
+//!     #[label(collection, "related to this")]
+//!     other_spans: Vec<Range<usize>>,
+//! }
+//!
+//! let report: miette::Report = MyError {
+//!     primary_span: (6, 9).into(),
+//!     other_spans: vec![19..26, 30..41],
+//! }.into();
+//!
+//! println!("{:?}", report.with_source_code("About something or another or yet another ...".to_string()));
+//! ```
+//!
+//! A collection can also be of `LabeledSpan` if you want to have different text
+//! for different labels. Labels with no text will use the one from the `label`
+//! attribute
+//!
+//! ```rust,ignore
+//! #[derive(Debug, Diagnostic, Error)]
+//! #[error("oops!")]
+//! struct MyError {
+//!     #[label("main issue")]
+//!     primary_span: SourceSpan,
+//!
+//!     #[label(collection, "related to this")]
+//!     other_spans: Vec<LabeledSpan>, // LabeledSpan
+//! }
+//!
+//! let report: miette::Report = MyError {
+//!     primary_span: (6, 9).into(),
+//!     other_spans: vec![
+//!         LabeledSpan::new(None, 19, 7), // Use default text `related to this`
+//!         LabeledSpan::new(Some("and also this".to_string()), 30, 11), // Use specific text
+//!     ],
+//! }.into();
+//!
+//! println!("{:?}", report.with_source_code("About something or another or yet another ...".to_string()));
+//! ```
+//!
+//! ## MSRV
+//!
+//! This crate requires rustc 1.82.0 or later.
+//!
 //! ## Acknowledgements
 //!
 //! `miette` was not developed in a void. It owes enormous credit to various
@@ -602,13 +815,15 @@
 //! and some from [`thiserror`](https://github.com/dtolnay/thiserror), also
 //! under the Apache License. Some code is taken from
 //! [`ariadne`](https://github.com/zesterer/ariadne), which is MIT licensed.
+#[cfg(feature = "derive")]
 pub use miette_derive::*;
 
 pub use error::*;
 pub use eyreish::*;
-#[cfg(feature = "fancy-no-backtrace")]
+#[cfg(feature = "fancy-base")]
 pub use handler::*;
 pub use handlers::*;
+pub use miette_diagnostic::*;
 pub use named_source::*;
 #[cfg(feature = "fancy")]
 pub use panic::*;
@@ -616,13 +831,17 @@ pub use protocol::*;
 
 mod chain;
 mod diagnostic_chain;
+mod diagnostic_impls;
 mod error;
 mod eyreish;
-#[cfg(feature = "fancy-no-backtrace")]
+#[cfg(feature = "fancy-base")]
 mod handler;
 mod handlers;
+#[cfg(feature = "fancy-base")]
+pub mod highlighters;
 #[doc(hidden)]
 pub mod macro_helpers;
+mod miette_diagnostic;
 mod named_source;
 #[cfg(feature = "fancy")]
 mod panic;

src/macro_helpers.rs

@@ -1,3 +1,5 @@
+use crate::protocol::{LabeledSpan, SourceSpan};
+
 // Huge thanks to @jam1gamer for this hack:
 // https://twitter.com/jam1garner/status/1515887996444323840
 
@@ -36,3 +38,24 @@ impl<T> ToOption for &OptionalWrapper<T> {
         Some(value)
     }
 }
+
+#[doc(hidden)]
+#[derive(Debug)]
+pub struct ToLabelSpanWrapper {}
+pub trait ToLabeledSpan<T> {
+    #[doc(hidden)]
+    fn to_labeled_span(span: T) -> LabeledSpan;
+}
+impl ToLabeledSpan<LabeledSpan> for ToLabelSpanWrapper {
+    fn to_labeled_span(span: LabeledSpan) -> LabeledSpan {
+        span
+    }
+}
+impl<T> ToLabeledSpan<T> for ToLabelSpanWrapper
+where
+    T: Into<SourceSpan>,
+{
+    fn to_labeled_span(span: T) -> LabeledSpan {
+        LabeledSpan::new_with_span(None, span.into())
+    }
+}

src/miette_diagnostic.rs

@@ -0,0 +1,369 @@
+use std::{
+    error::Error,
+    fmt::{Debug, Display},
+};
+
+#[cfg(feature = "serde")]
+use serde::{Deserialize, Serialize};
+
+use crate::{Diagnostic, LabeledSpan, Severity};
+
+/// Diagnostic that can be created at runtime.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+pub struct MietteDiagnostic {
+    /// Displayed diagnostic message
+    pub message: String,
+    /// Unique diagnostic code to look up more information
+    /// about this Diagnostic. Ideally also globally unique, and documented
+    /// in the toplevel crate's documentation for easy searching.
+    /// Rust path format (`foo::bar::baz`) is recommended, but more classic
+    /// codes like `E0123` will work just fine
+    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
+    pub code: Option<String>,
+    /// [`Diagnostic`] severity. Intended to be used by
+    /// [`ReportHandler`](crate::ReportHandler)s to change the way different
+    /// [`Diagnostic`]s are displayed. Defaults to [`Severity::Error`]
+    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
+    pub severity: Option<Severity>,
+    /// Additional help text related to this Diagnostic
+    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
+    pub help: Option<String>,
+    /// URL to visit for a more detailed explanation/help about this
+    /// [`Diagnostic`].
+    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
+    pub url: Option<String>,
+    /// Labels to apply to this `Diagnostic`'s [`Diagnostic::source_code`]
+    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
+    pub labels: Option<Vec<LabeledSpan>>,
+}
+
+impl Display for MietteDiagnostic {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", &self.message)
+    }
+}
+
+impl Error for MietteDiagnostic {}
+
+impl Diagnostic for MietteDiagnostic {
+    fn code<'a>(&'a self) -> Option<Box<dyn Display + 'a>> {
+        self.code
+            .as_ref()
+            .map(Box::new)
+            .map(|c| c as Box<dyn Display>)
+    }
+
+    fn severity(&self) -> Option<Severity> {
+        self.severity
+    }
+
+    fn help<'a>(&'a self) -> Option<Box<dyn Display + 'a>> {
+        self.help
+            .as_ref()
+            .map(Box::new)
+            .map(|c| c as Box<dyn Display>)
+    }
+
+    fn url<'a>(&'a self) -> Option<Box<dyn Display + 'a>> {
+        self.url
+            .as_ref()
+            .map(Box::new)
+            .map(|c| c as Box<dyn Display>)
+    }
+
+    fn labels(&self) -> Option<Box<dyn Iterator<Item = LabeledSpan> + '_>> {
+        self.labels
+            .as_ref()
+            .map(|ls| ls.iter().cloned())
+            .map(Box::new)
+            .map(|b| b as Box<dyn Iterator<Item = LabeledSpan>>)
+    }
+}
+
+impl MietteDiagnostic {
+    /// Create a new dynamic diagnostic with the given message.
+    ///
+    /// # Examples
+    /// ```
+    /// use miette::{Diagnostic, MietteDiagnostic, Severity};
+    ///
+    /// let diag = MietteDiagnostic::new("Oops, something went wrong!");
+    /// assert_eq!(diag.to_string(), "Oops, something went wrong!");
+    /// assert_eq!(diag.message, "Oops, something went wrong!");
+    /// ```
+    pub fn new(message: impl Into<String>) -> Self {
+        Self {
+            message: message.into(),
+            labels: None,
+            severity: None,
+            code: None,
+            help: None,
+            url: None,
+        }
+    }
+
+    /// Return new diagnostic with the given code.
+    ///
+    /// # Examples
+    /// ```
+    /// use miette::{Diagnostic, MietteDiagnostic};
+    ///
+    /// let diag = MietteDiagnostic::new("Oops, something went wrong!").with_code("foo::bar::baz");
+    /// assert_eq!(diag.message, "Oops, something went wrong!");
+    /// assert_eq!(diag.code, Some("foo::bar::baz".to_string()));
+    /// ```
+    pub fn with_code(mut self, code: impl Into<String>) -> Self {
+        self.code = Some(code.into());
+        self
+    }
+
+    /// Return new diagnostic with the given severity.
+    ///
+    /// # Examples
+    /// ```
+    /// use miette::{Diagnostic, MietteDiagnostic, Severity};
+    ///
+    /// let diag = MietteDiagnostic::new("I warn you to stop!").with_severity(Severity::Warning);
+    /// assert_eq!(diag.message, "I warn you to stop!");
+    /// assert_eq!(diag.severity, Some(Severity::Warning));
+    /// ```
+    pub fn with_severity(mut self, severity: Severity) -> Self {
+        self.severity = Some(severity);
+        self
+    }
+
+    /// Return new diagnostic with the given help message.
+    ///
+    /// # Examples
+    /// ```
+    /// use miette::{Diagnostic, MietteDiagnostic};
+    ///
+    /// let diag = MietteDiagnostic::new("PC is not working").with_help("Try to reboot it again");
+    /// assert_eq!(diag.message, "PC is not working");
+    /// assert_eq!(diag.help, Some("Try to reboot it again".to_string()));
+    /// ```
+    pub fn with_help(mut self, help: impl Into<String>) -> Self {
+        self.help = Some(help.into());
+        self
+    }
+
+    /// Return new diagnostic with the given URL.
+    ///
+    /// # Examples
+    /// ```
+    /// use miette::{Diagnostic, MietteDiagnostic};
+    ///
+    /// let diag = MietteDiagnostic::new("PC is not working")
+    ///     .with_url("https://letmegooglethat.com/?q=Why+my+pc+doesn%27t+work");
+    /// assert_eq!(diag.message, "PC is not working");
+    /// assert_eq!(
+    ///     diag.url,
+    ///     Some("https://letmegooglethat.com/?q=Why+my+pc+doesn%27t+work".to_string())
+    /// );
+    /// ```
+    pub fn with_url(mut self, url: impl Into<String>) -> Self {
+        self.url = Some(url.into());
+        self
+    }
+
+    /// Return new diagnostic with the given label.
+    ///
+    /// Discards previous labels
+    ///
+    /// # Examples
+    /// ```
+    /// use miette::{Diagnostic, LabeledSpan, MietteDiagnostic};
+    ///
+    /// let source = "cpp is the best language";
+    ///
+    /// let label = LabeledSpan::at(0..3, "This should be Rust");
+    /// let diag = MietteDiagnostic::new("Wrong best language").with_label(label.clone());
+    /// assert_eq!(diag.message, "Wrong best language");
+    /// assert_eq!(diag.labels, Some(vec![label]));
+    /// ```
+    pub fn with_label(mut self, label: impl Into<LabeledSpan>) -> Self {
+        self.labels = Some(vec![label.into()]);
+        self
+    }
+
+    /// Return new diagnostic with the given labels.
+    ///
+    /// Discards previous labels
+    ///
+    /// # Examples
+    /// ```
+    /// use miette::{Diagnostic, LabeledSpan, MietteDiagnostic};
+    ///
+    /// let source = "helo wrld";
+    ///
+    /// let labels = vec![
+    ///     LabeledSpan::at_offset(3, "add 'l'"),
+    ///     LabeledSpan::at_offset(6, "add 'r'"),
+    /// ];
+    /// let diag = MietteDiagnostic::new("Typos in 'hello world'").with_labels(labels.clone());
+    /// assert_eq!(diag.message, "Typos in 'hello world'");
+    /// assert_eq!(diag.labels, Some(labels));
+    /// ```
+    pub fn with_labels(mut self, labels: impl IntoIterator<Item = LabeledSpan>) -> Self {
+        self.labels = Some(labels.into_iter().collect());
+        self
+    }
+
+    /// Return new diagnostic with new label added to the existing ones.
+    ///
+    /// # Examples
+    /// ```
+    /// use miette::{Diagnostic, LabeledSpan, MietteDiagnostic};
+    ///
+    /// let source = "helo wrld";
+    ///
+    /// let label1 = LabeledSpan::at_offset(3, "add 'l'");
+    /// let label2 = LabeledSpan::at_offset(6, "add 'r'");
+    /// let diag = MietteDiagnostic::new("Typos in 'hello world'")
+    ///     .and_label(label1.clone())
+    ///     .and_label(label2.clone());
+    /// assert_eq!(diag.message, "Typos in 'hello world'");
+    /// assert_eq!(diag.labels, Some(vec![label1, label2]));
+    /// ```
+    pub fn and_label(mut self, label: impl Into<LabeledSpan>) -> Self {
+        let mut labels = self.labels.unwrap_or_default();
+        labels.push(label.into());
+        self.labels = Some(labels);
+        self
+    }
+
+    /// Return new diagnostic with new labels added to the existing ones.
+    ///
+    /// # Examples
+    /// ```
+    /// use miette::{Diagnostic, LabeledSpan, MietteDiagnostic};
+    ///
+    /// let source = "helo wrld";
+    ///
+    /// let label1 = LabeledSpan::at_offset(3, "add 'l'");
+    /// let label2 = LabeledSpan::at_offset(6, "add 'r'");
+    /// let label3 = LabeledSpan::at_offset(9, "add '!'");
+    /// let diag = MietteDiagnostic::new("Typos in 'hello world!'")
+    ///     .and_label(label1.clone())
+    ///     .and_labels([label2.clone(), label3.clone()]);
+    /// assert_eq!(diag.message, "Typos in 'hello world!'");
+    /// assert_eq!(diag.labels, Some(vec![label1, label2, label3]));
+    /// ```
+    pub fn and_labels(mut self, labels: impl IntoIterator<Item = LabeledSpan>) -> Self {
+        let mut all_labels = self.labels.unwrap_or_default();
+        all_labels.extend(labels);
+        self.labels = Some(all_labels);
+        self
+    }
+}
+
+#[cfg(feature = "serde")]
+#[test]
+fn test_serialize_miette_diagnostic() {
+    use serde_json::json;
+
+    use crate::diagnostic;
+
+    let diag = diagnostic!("message");
+    let json = json!({ "message": "message" });
+    assert_eq!(json!(diag), json);
+
+    let diag = diagnostic!(
+        code = "code",
+        help = "help",
+        url = "url",
+        labels = [
+            LabeledSpan::at_offset(0, "label1"),
+            LabeledSpan::at(1..3, "label2")
+        ],
+        severity = Severity::Warning,
+        "message"
+    );
+    let json = json!({
+        "message": "message",
+        "code": "code",
+        "help": "help",
+        "url": "url",
+        "severity": "Warning",
+        "labels": [
+            {
+                "span": {
+                    "offset": 0,
+                    "length": 0
+                },
+                "label": "label1",
+                "primary": false
+            },
+            {
+                "span": {
+                    "offset": 1,
+                    "length": 2
+                },
+                "label": "label2",
+                "primary": false
+            }
+        ]
+    });
+    assert_eq!(json!(diag), json);
+}
+
+#[cfg(feature = "serde")]
+#[test]
+fn test_deserialize_miette_diagnostic() {
+    use serde_json::json;
+
+    use crate::diagnostic;
+
+    let json = json!({ "message": "message" });
+    let diag = diagnostic!("message");
+    assert_eq!(diag, serde_json::from_value(json).unwrap());
+
+    let json = json!({
+        "message": "message",
+        "help": null,
+        "code": null,
+        "severity": null,
+        "url": null,
+        "labels": null
+    });
+    assert_eq!(diag, serde_json::from_value(json).unwrap());
+
+    let diag = diagnostic!(
+        code = "code",
+        help = "help",
+        url = "url",
+        labels = [
+            LabeledSpan::at_offset(0, "label1"),
+            LabeledSpan::at(1..3, "label2")
+        ],
+        severity = Severity::Warning,
+        "message"
+    );
+    let json = json!({
+        "message": "message",
+        "code": "code",
+        "help": "help",
+        "url": "url",
+        "severity": "Warning",
+        "labels": [
+            {
+                "span": {
+                    "offset": 0,
+                    "length": 0
+                },
+                "label": "label1",
+                "primary": false
+            },
+            {
+                "span": {
+                    "offset": 1,
+                    "length": 2
+                },
+                "label": "label2",
+                "primary": false
+            }
+        ]
+    });
+    assert_eq!(diag, serde_json::from_value(json).unwrap());
+}

src/named_source.rs

@@ -3,54 +3,76 @@ use crate::{MietteError, MietteSpanContents, SourceCode, SpanContents};
 /// Utility struct for when you have a regular [`SourceCode`] type that doesn't
 /// implement `name`. For example [`String`]. Or if you want to override the
 /// `name` returned by the `SourceCode`.
-pub struct NamedSource {
-    source: Box<dyn SourceCode + 'static>,
+#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct NamedSource<S: SourceCode + 'static> {
+    source: S,
     name: String,
+    language: Option<String>,
 }
 
-impl std::fmt::Debug for NamedSource {
+impl<S: SourceCode> std::fmt::Debug for NamedSource<S> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("NamedSource")
             .field("name", &self.name)
-            .field("source", &"<redacted>");
+            .field("source", &"<redacted>")
+            .field("language", &self.language);
         Ok(())
     }
 }
 
-impl NamedSource {
+impl<S: SourceCode + 'static> NamedSource<S> {
     /// Create a new `NamedSource` using a regular [`SourceCode`] and giving
     /// its returned [`SpanContents`] a name.
-    pub fn new(name: impl AsRef<str>, source: impl SourceCode + Send + Sync + 'static) -> Self {
+    pub fn new(name: impl AsRef<str>, source: S) -> Self
+    where
+        S: Send + Sync,
+    {
         Self {
-            source: Box::new(source),
+            source,
             name: name.as_ref().to_string(),
+            language: None,
         }
     }
 
+    /// Gets the name of this `NamedSource`.
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
     /// Returns a reference the inner [`SourceCode`] type for this
     /// `NamedSource`.
-    pub fn inner(&self) -> &(dyn SourceCode + 'static) {
-        &*self.source
+    pub fn inner(&self) -> &S {
+        &self.source
+    }
+
+    /// Sets the [`language`](SpanContents::language) for this source code.
+    pub fn with_language(mut self, language: impl Into<String>) -> Self {
+        self.language = Some(language.into());
+        self
     }
 }
 
-impl SourceCode for NamedSource {
+impl<S: SourceCode + 'static> SourceCode for NamedSource<S> {
     fn read_span<'a>(
         &'a self,
         span: &crate::SourceSpan,
         context_lines_before: usize,
         context_lines_after: usize,
     ) -> Result<Box<dyn SpanContents<'a> + 'a>, MietteError> {
-        let contents = self
-            .inner()
-            .read_span(span, context_lines_before, context_lines_after)?;
-        Ok(Box::new(MietteSpanContents::new_named(
+        let inner_contents =
+            self.inner()
+                .read_span(span, context_lines_before, context_lines_after)?;
+        let mut contents = MietteSpanContents::new_named(
             self.name.clone(),
-            contents.data(),
-            *contents.span(),
-            contents.line(),
-            contents.column(),
-            contents.line_count(),
-        )))
+            inner_contents.data(),
+            *inner_contents.span(),
+            inner_contents.line(),
+            inner_contents.column(),
+            inner_contents.line_count(),
+        );
+        if let Some(language) = &self.language {
+            contents = contents.with_language(language);
+        }
+        Ok(Box::new(contents))
     }
 }

src/panic.rs

@@ -1,10 +1,8 @@
-#![cfg(feature = "fancy")]
-use std::fmt::Write;
+use std::{error::Error, fmt::Display};
 
 use backtrace::Backtrace;
-use thiserror::Error;
 
-use crate::{self as miette, Context, Diagnostic, Result};
+use crate::{Context, Diagnostic, Result};
 
 /// Tells miette to render panics using its rendering engine.
 pub fn set_panic_hook() {
@@ -15,7 +13,7 @@ pub fn set_panic_hook() {
             message = msg.to_string();
         }
         if let Some(msg) = payload.downcast_ref::<String>() {
-            message = msg.clone();
+            message.clone_from(msg);
         }
         let mut report: Result<()> = Err(Panic(message).into());
         if let Some(loc) = info.location() {
@@ -28,21 +26,39 @@ pub fn set_panic_hook() {
     }));
 }
 
-#[derive(Debug, Error, Diagnostic)]
-#[error("{0}{}", self.maybe_collect_backtrace())]
-#[diagnostic(help("set the `RUST_BACKTRACE=1` environment variable to display a backtrace."))]
+#[derive(Debug)]
 struct Panic(String);
 
+impl Display for Panic {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let msg = &self.0;
+        let panic = Panic::backtrace();
+        write!(f, "{msg}{panic}")
+    }
+}
+
+impl Error for Panic {}
+
+impl Diagnostic for Panic {
+    fn help<'a>(&'a self) -> Option<Box<dyn Display + 'a>> {
+        Some(Box::new(
+            "set the `RUST_BACKTRACE=1` environment variable to display a backtrace.",
+        ))
+    }
+}
+
 impl Panic {
-    fn maybe_collect_backtrace(&self) -> String {
+    fn backtrace() -> String {
+        use std::fmt::Write;
         if let Ok(var) = std::env::var("RUST_BACKTRACE") {
             if !var.is_empty() && var != "0" {
-                // This is all taken from human-panic: https://github.com/rust-cli/human-panic/blob/master/src/report.rs#L55-L107
                 const HEX_WIDTH: usize = std::mem::size_of::<usize>() + 2;
-                //Padding for next lines after frame's address
+                // Padding for next lines after frame's address
                 const NEXT_SYMBOL_PADDING: usize = HEX_WIDTH + 6;
                 let mut backtrace = String::new();
-                for (idx, frame) in Backtrace::new().frames().iter().skip(26).enumerate() {
+                let trace = Backtrace::new();
+                let frames = backtrace_ext::short_frames_strict(&trace).enumerate();
+                for (idx, (frame, sub_frames)) in frames {
                     let ip = frame.ip();
                     let _ = write!(backtrace, "\n{:4}: {:2$?}", idx, ip, HEX_WIDTH);
 
@@ -52,10 +68,10 @@ impl Panic {
                         continue;
                     }
 
-                    for (idx, symbol) in symbols.iter().enumerate() {
-                        //Print symbols from this address,
-                        //if there are several addresses
-                        //we need to put it on next line
+                    for (idx, symbol) in symbols[sub_frames].iter().enumerate() {
+                        // Print symbols from this address,
+                        // if there are several addresses
+                        // we need to put it on next line
                         if idx != 0 {
                             let _ = write!(backtrace, "\n{:1$}", "", NEXT_SYMBOL_PADDING);
                         }
@@ -66,7 +82,7 @@ impl Panic {
                             let _ = write!(backtrace, " - <unknown>");
                         }
 
-                        //See if there is debug information with file name and line
+                        // See if there is debug information with file name and line
                         if let (Some(file), Some(line)) = (symbol.filename(), symbol.lineno()) {
                             let _ = write!(
                                 backtrace,
@@ -85,3 +101,32 @@ impl Panic {
         "".into()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use std::error::Error;
+
+    use super::*;
+
+    #[test]
+    fn panic() {
+        let panic = Panic("ruh roh raggy".to_owned());
+
+        assert_eq!(panic.to_string(), "ruh roh raggy");
+        assert!(panic.source().is_none());
+        assert!(panic.code().is_none());
+        assert!(panic.severity().is_none());
+        assert_eq!(
+            panic.help().map(|h| h.to_string()),
+            Some(
+                "set the `RUST_BACKTRACE=1` environment variable to display a backtrace."
+                    .to_owned()
+            )
+        );
+        assert!(panic.url().is_none());
+        assert!(panic.source_code().is_none());
+        assert!(panic.labels().is_none());
+        assert!(panic.related().is_none());
+        assert!(panic.diagnostic_source().is_none());
+    }
+}

src/protocol.rs

@@ -9,7 +9,10 @@ use std::{
     panic::Location,
 };
 
-use crate::MietteError;
+#[cfg(feature = "serde")]
+use serde::{Deserialize, Serialize};
+
+use crate::{DiagnosticError, MietteError};
 
 /// Adds rich metadata to your Error that can be used by
 /// [`Report`](crate::Report) to print really nice and human-friendly error
@@ -66,16 +69,45 @@ pub trait Diagnostic: std::error::Error {
     }
 }
 
-impl std::error::Error for Box<dyn Diagnostic> {
-    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
-        (**self).source()
-    }
+macro_rules! box_error_impls {
+    ($($box_type:ty),*) => {
+        $(
+            impl std::error::Error for $box_type {
+                fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+                    (**self).source()
+                }
 
-    fn cause(&self) -> Option<&dyn std::error::Error> {
-        self.source()
+                fn cause(&self) -> Option<&dyn std::error::Error> {
+                    self.source()
+                }
+            }
+        )*
     }
 }
 
+box_error_impls! {
+    Box<dyn Diagnostic>,
+    Box<dyn Diagnostic + Send>,
+    Box<dyn Diagnostic + Send + Sync>
+}
+
+macro_rules! box_borrow_impls {
+    ($($box_type:ty),*) => {
+        $(
+            impl std::borrow::Borrow<dyn Diagnostic> for $box_type {
+                fn borrow(&self) -> &(dyn Diagnostic + 'static) {
+                    self.as_ref()
+                }
+            }
+        )*
+    }
+}
+
+box_borrow_impls! {
+    Box<dyn Diagnostic + Send>,
+    Box<dyn Diagnostic + Send + Sync>
+}
+
 impl<T: Diagnostic + Send + Sync + 'static> From<T>
     for Box<dyn Diagnostic + Send + Sync + 'static>
 {
@@ -102,7 +134,7 @@ impl From<&str> for Box<dyn Diagnostic> {
     }
 }
 
-impl<'a> From<&str> for Box<dyn Diagnostic + Send + Sync + 'a> {
+impl From<&str> for Box<dyn Diagnostic + Send + Sync + '_> {
     fn from(s: &str) -> Self {
         From::from(String::from(s))
     }
@@ -142,34 +174,52 @@ impl From<String> for Box<dyn Diagnostic + Send + Sync> {
 
 impl From<Box<dyn std::error::Error + Send + Sync>> for Box<dyn Diagnostic + Send + Sync> {
     fn from(s: Box<dyn std::error::Error + Send + Sync>) -> Self {
-        #[derive(thiserror::Error)]
-        #[error(transparent)]
-        struct BoxedDiagnostic(Box<dyn std::error::Error + Send + Sync>);
-        impl fmt::Debug for BoxedDiagnostic {
-            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-                fmt::Debug::fmt(&self.0, f)
-            }
-        }
-
-        impl Diagnostic for BoxedDiagnostic {}
-
-        Box::new(BoxedDiagnostic(s))
+        Box::new(DiagnosticError(s))
     }
 }
 
 /**
 [`Diagnostic`] severity. Intended to be used by
 [`ReportHandler`](crate::ReportHandler)s to change the way different
-[`Diagnostic`]s are displayed.
+[`Diagnostic`]s are displayed. Defaults to [`Severity::Error`].
 */
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+#[derive(Copy, Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[derive(Default)]
 pub enum Severity {
-    /// Critical failure. The program cannot continue.
-    Error,
-    /// Warning. Please take note.
-    Warning,
     /// Just some help. Here's how you could be doing it better.
     Advice,
+    /// Warning. Please take note.
+    Warning,
+    /// Critical failure. The program cannot continue.
+    /// This is the default severity, if you don't specify another one.
+    #[default]
+    Error,
+}
+
+#[cfg(feature = "serde")]
+#[test]
+fn test_serialize_severity() {
+    use serde_json::json;
+
+    assert_eq!(json!(Severity::Advice), json!("Advice"));
+    assert_eq!(json!(Severity::Warning), json!("Warning"));
+    assert_eq!(json!(Severity::Error), json!("Error"));
+}
+
+#[cfg(feature = "serde")]
+#[test]
+fn test_deserialize_severity() {
+    use serde_json::json;
+
+    let severity: Severity = serde_json::from_value(json!("Advice")).unwrap();
+    assert_eq!(severity, Severity::Advice);
+
+    let severity: Severity = serde_json::from_value(json!("Warning")).unwrap();
+    assert_eq!(severity, Severity::Warning);
+
+    let severity: Severity = serde_json::from_value(json!("Error")).unwrap();
+    assert_eq!(severity, Severity::Error);
 }
 
 /**
@@ -184,7 +234,7 @@ whole thing--meaning you should be able to support `SourceCode`s which are
 gigabytes or larger in size.
 */
 pub trait SourceCode: Send + Sync {
-    /// Read the bytes for a specific span from this SourceCode, keeping a
+    /// Read the bytes for a specific span from this `SourceCode`, keeping a
     /// certain number of lines before and after the span as context.
     fn read_span<'a>(
         &'a self,
@@ -196,17 +246,21 @@ pub trait SourceCode: Send + Sync {
 
 /// A labeled [`SourceSpan`].
 #[derive(Debug, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct LabeledSpan {
+    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
     label: Option<String>,
     span: SourceSpan,
+    primary: bool,
 }
 
 impl LabeledSpan {
     /// Makes a new labeled span.
-    pub fn new(label: Option<String>, offset: ByteOffset, len: ByteOffset) -> Self {
+    pub const fn new(label: Option<String>, offset: ByteOffset, len: usize) -> Self {
         Self {
             label,
-            span: (offset, len).into(),
+            span: SourceSpan::new(SourceOffset(offset), len),
+            primary: false,
         }
     }
 
@@ -215,33 +269,153 @@ impl LabeledSpan {
         Self {
             label,
             span: span.into(),
+            primary: false,
         }
     }
 
+    /// Makes a new labeled primary span using an existing span.
+    pub fn new_primary_with_span(label: Option<String>, span: impl Into<SourceSpan>) -> Self {
+        Self {
+            label,
+            span: span.into(),
+            primary: true,
+        }
+    }
+
+    /// Change the text of the label
+    pub fn set_label(&mut self, label: Option<String>) {
+        self.label = label;
+    }
+
+    /// Makes a new label at specified span
+    ///
+    /// # Examples
+    /// ```
+    /// use miette::LabeledSpan;
+    ///
+    /// let source = "Cpp is the best";
+    /// let label = LabeledSpan::at(0..3, "should be Rust");
+    /// assert_eq!(
+    ///     label,
+    ///     LabeledSpan::new(Some("should be Rust".to_string()), 0, 3)
+    /// )
+    /// ```
+    pub fn at(span: impl Into<SourceSpan>, label: impl Into<String>) -> Self {
+        Self::new_with_span(Some(label.into()), span)
+    }
+
+    /// Makes a new label that points at a specific offset.
+    ///
+    /// # Examples
+    /// ```
+    /// use miette::LabeledSpan;
+    ///
+    /// let source = "(2 + 2";
+    /// let label = LabeledSpan::at_offset(4, "expected a closing parenthesis");
+    /// assert_eq!(
+    ///     label,
+    ///     LabeledSpan::new(Some("expected a closing parenthesis".to_string()), 4, 0)
+    /// )
+    /// ```
+    pub fn at_offset(offset: ByteOffset, label: impl Into<String>) -> Self {
+        Self::new(Some(label.into()), offset, 0)
+    }
+
+    /// Makes a new label without text, that underlines a specific span.
+    ///
+    /// # Examples
+    /// ```
+    /// use miette::LabeledSpan;
+    ///
+    /// let source = "You have an eror here";
+    /// let label = LabeledSpan::underline(12..16);
+    /// assert_eq!(label, LabeledSpan::new(None, 12, 4))
+    /// ```
+    pub fn underline(span: impl Into<SourceSpan>) -> Self {
+        Self::new_with_span(None, span)
+    }
+
     /// Gets the (optional) label string for this `LabeledSpan`.
     pub fn label(&self) -> Option<&str> {
         self.label.as_deref()
     }
 
     /// Returns a reference to the inner [`SourceSpan`].
-    pub fn inner(&self) -> &SourceSpan {
+    pub const fn inner(&self) -> &SourceSpan {
         &self.span
     }
 
     /// Returns the 0-based starting byte offset.
-    pub fn offset(&self) -> usize {
+    pub const fn offset(&self) -> usize {
         self.span.offset()
     }
 
     /// Returns the number of bytes this `LabeledSpan` spans.
-    pub fn len(&self) -> usize {
+    pub const fn len(&self) -> usize {
         self.span.len()
     }
 
     /// True if this `LabeledSpan` is empty.
-    pub fn is_empty(&self) -> bool {
+    pub const fn is_empty(&self) -> bool {
         self.span.is_empty()
     }
+
+    /// True if this `LabeledSpan` is a primary span.
+    pub const fn primary(&self) -> bool {
+        self.primary
+    }
+}
+
+#[cfg(feature = "serde")]
+#[test]
+fn test_serialize_labeled_span() {
+    use serde_json::json;
+
+    assert_eq!(
+        json!(LabeledSpan::new(None, 0, 0)),
+        json!({
+            "span": { "offset": 0, "length": 0, },
+            "primary": false,
+        })
+    );
+
+    assert_eq!(
+        json!(LabeledSpan::new(Some("label".to_string()), 0, 0)),
+        json!({
+            "label": "label",
+            "span": { "offset": 0, "length": 0, },
+            "primary": false,
+        })
+    );
+}
+
+#[cfg(feature = "serde")]
+#[test]
+fn test_deserialize_labeled_span() {
+    use serde_json::json;
+
+    let span: LabeledSpan = serde_json::from_value(json!({
+        "label": null,
+        "span": { "offset": 0, "length": 0, },
+        "primary": false,
+    }))
+    .unwrap();
+    assert_eq!(span, LabeledSpan::new(None, 0, 0));
+
+    let span: LabeledSpan = serde_json::from_value(json!({
+        "span": { "offset": 0, "length": 0, },
+        "primary": false
+    }))
+    .unwrap();
+    assert_eq!(span, LabeledSpan::new(None, 0, 0));
+
+    let span: LabeledSpan = serde_json::from_value(json!({
+        "label": "label",
+        "span": { "offset": 0, "length": 0, },
+        "primary": false
+    }))
+    .unwrap();
+    assert_eq!(span, LabeledSpan::new(Some("label".to_string()), 0, 0));
 }
 
 /**
@@ -266,6 +440,15 @@ pub trait SpanContents<'a> {
     fn column(&self) -> usize;
     /// Total number of lines covered by this `SpanContents`.
     fn line_count(&self) -> usize;
+
+    /// Optional method. The language name for this source code, if any.
+    /// This is used to drive syntax highlighting.
+    ///
+    /// Examples: Rust, TOML, C
+    ///
+    fn language(&self) -> Option<&str> {
+        None
+    }
 }
 
 /**
@@ -285,11 +468,13 @@ pub struct MietteSpanContents<'a> {
     line_count: usize,
     // Optional filename
     name: Option<String>,
+    // Optional language
+    language: Option<String>,
 }
 
 impl<'a> MietteSpanContents<'a> {
     /// Make a new [`MietteSpanContents`] object.
-    pub fn new(
+    pub const fn new(
         data: &'a [u8],
         span: SourceSpan,
         line: usize,
@@ -303,11 +488,12 @@ impl<'a> MietteSpanContents<'a> {
             column,
             line_count,
             name: None,
+            language: None,
         }
     }
 
     /// Make a new [`MietteSpanContents`] object, with a name for its 'file'.
-    pub fn new_named(
+    pub const fn new_named(
         name: String,
         data: &'a [u8],
         span: SourceSpan,
@@ -322,8 +508,15 @@ impl<'a> MietteSpanContents<'a> {
             column,
             line_count,
             name: Some(name),
+            language: None,
         }
     }
+
+    /// Sets the [`language`](SpanContents::language) for syntax highlighting.
+    pub fn with_language(mut self, language: impl Into<String>) -> Self {
+        self.language = Some(language.into());
+        self
+    }
 }
 
 impl<'a> SpanContents<'a> for MietteSpanContents<'a> {
@@ -345,22 +538,24 @@ impl<'a> SpanContents<'a> for MietteSpanContents<'a> {
     fn name(&self) -> Option<&str> {
         self.name.as_deref()
     }
+    fn language(&self) -> Option<&str> {
+        self.language.as_deref()
+    }
 }
 
-/**
-Span within a [`SourceCode`] with an associated message.
-*/
-#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
+/// Span within a [`SourceCode`]
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct SourceSpan {
     /// The start of the span.
     offset: SourceOffset,
-    /// The total length of the span. Think of this as an offset from `start`.
-    length: SourceOffset,
+    /// The total length of the span
+    length: usize,
 }
 
 impl SourceSpan {
     /// Create a new [`SourceSpan`].
-    pub fn new(start: SourceOffset, length: SourceOffset) -> Self {
+    pub const fn new(start: SourceOffset, length: usize) -> Self {
         Self {
             offset: start,
             length,
@@ -368,37 +563,34 @@ impl SourceSpan {
     }
 
     /// The absolute offset, in bytes, from the beginning of a [`SourceCode`].
-    pub fn offset(&self) -> usize {
+    pub const fn offset(&self) -> usize {
         self.offset.offset()
     }
 
     /// Total length of the [`SourceSpan`], in bytes.
-    pub fn len(&self) -> usize {
-        self.length.offset()
+    pub const fn len(&self) -> usize {
+        self.length
     }
 
     /// Whether this [`SourceSpan`] has a length of zero. It may still be useful
     /// to point to a specific point.
-    pub fn is_empty(&self) -> bool {
-        self.length.offset() == 0
+    pub const fn is_empty(&self) -> bool {
+        self.length == 0
     }
 }
 
-impl From<(ByteOffset, ByteOffset)> for SourceSpan {
-    fn from((start, len): (ByteOffset, ByteOffset)) -> Self {
+impl From<(ByteOffset, usize)> for SourceSpan {
+    fn from((start, len): (ByteOffset, usize)) -> Self {
         Self {
             offset: start.into(),
-            length: len.into(),
+            length: len,
         }
     }
 }
 
-impl From<(SourceOffset, SourceOffset)> for SourceSpan {
-    fn from((start, len): (SourceOffset, SourceOffset)) -> Self {
-        Self {
-            offset: start,
-            length: len,
-        }
+impl From<(SourceOffset, usize)> for SourceSpan {
+    fn from((start, len): (SourceOffset, usize)) -> Self {
+        Self::new(start, len)
     }
 }
 
@@ -406,17 +598,36 @@ impl From<std::ops::Range<ByteOffset>> for SourceSpan {
     fn from(range: std::ops::Range<ByteOffset>) -> Self {
         Self {
             offset: range.start.into(),
-            length: range.len().into(),
+            length: range.len(),
+        }
+    }
+}
+
+impl From<std::ops::RangeInclusive<ByteOffset>> for SourceSpan {
+    /// # Panics
+    ///
+    /// Panics if the total length of the inclusive range would overflow a
+    /// `usize`. This will only occur with the range `0..=usize::MAX`.
+    fn from(range: std::ops::RangeInclusive<ByteOffset>) -> Self {
+        let (start, end) = range.clone().into_inner();
+        Self {
+            offset: start.into(),
+            length: if range.is_empty() {
+                0
+            } else {
+                // will not overflow because `is_empty() == false` guarantees
+                // that `start <= end`
+                (end - start)
+                    .checked_add(1)
+                    .expect("length of inclusive range should fit in a usize")
+            },
         }
     }
 }
 
 impl From<SourceOffset> for SourceSpan {
     fn from(offset: SourceOffset) -> Self {
-        Self {
-            offset,
-            length: 0.into(),
-        }
+        Self { offset, length: 0 }
     }
 }
 
@@ -424,11 +635,31 @@ impl From<ByteOffset> for SourceSpan {
     fn from(offset: ByteOffset) -> Self {
         Self {
             offset: offset.into(),
-            length: 0.into(),
+            length: 0,
         }
     }
 }
 
+#[cfg(feature = "serde")]
+#[test]
+fn test_serialize_source_span() {
+    use serde_json::json;
+
+    assert_eq!(
+        json!(SourceSpan::from(0)),
+        json!({ "offset": 0, "length": 0})
+    );
+}
+
+#[cfg(feature = "serde")]
+#[test]
+fn test_deserialize_source_span() {
+    use serde_json::json;
+
+    let span: SourceSpan = serde_json::from_value(json!({ "offset": 0, "length": 0})).unwrap();
+    assert_eq!(span, SourceSpan::from(0));
+}
+
 /**
 "Raw" type for the byte offset from the beginning of a [`SourceCode`].
 */
@@ -437,12 +668,13 @@ pub type ByteOffset = usize;
 /**
 Newtype that represents the [`ByteOffset`] from the beginning of a [`SourceCode`]
 */
-#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct SourceOffset(ByteOffset);
 
 impl SourceOffset {
     /// Actual byte offset.
-    pub fn offset(&self) -> ByteOffset {
+    pub const fn offset(&self) -> ByteOffset {
         self.0
     }
 
@@ -488,7 +720,7 @@ impl SourceOffset {
         Ok((
             loc.file().into(),
             fs::read_to_string(loc.file())
-                .map(|txt| Self::from_location(&txt, loc.line() as usize, loc.column() as usize))?,
+                .map(|txt| Self::from_location(txt, loc.line() as usize, loc.column() as usize))?,
         ))
     }
 }
@@ -521,3 +753,18 @@ fn test_source_offset_from_location() {
         source.len()
     );
 }
+
+#[cfg(feature = "serde")]
+#[test]
+fn test_serialize_source_offset() {
+    use serde_json::json;
+
+    assert_eq!(json!(SourceOffset::from(0)), 0);
+}
+
+#[cfg(feature = "serde")]
+#[test]
+fn test_deserialize_source_offset() {
+    let offset: SourceOffset = serde_json::from_str("0").unwrap();
+    assert_eq!(offset, SourceOffset::from(0));
+}

src/source_impls.rs

@@ -1,11 +1,7 @@
 /*!
 Default trait implementations for [`SourceCode`].
 */
-use std::{
-    borrow::{Cow, ToOwned},
-    fmt::Debug,
-    sync::Arc,
-};
+use std::{borrow::Cow, collections::VecDeque, fmt::Debug, sync::Arc};
 
 use crate::{MietteError, MietteSpanContents, SourceCode, SourceSpan, SpanContents};
 
@@ -19,7 +15,7 @@ fn context_info<'a>(
     let mut line_count = 0usize;
     let mut start_line = 0usize;
     let mut start_column = 0usize;
-    let mut before_lines_starts = Vec::new();
+    let mut before_lines_starts = VecDeque::new();
     let mut current_line_start = 0usize;
     let mut end_lines = 0usize;
     let mut post_span = false;
@@ -34,10 +30,10 @@ fn context_info<'a>(
             if offset < span.offset() {
                 // We're before the start of the span.
                 start_column = 0;
-                before_lines_starts.push(current_line_start);
+                before_lines_starts.push_back(current_line_start);
                 if before_lines_starts.len() > context_lines_before {
                     start_line += 1;
-                    before_lines_starts.remove(0);
+                    before_lines_starts.pop_front();
                 }
             } else if offset >= span.offset() + span.len().saturating_sub(1) {
                 // We're after the end of the span, but haven't necessarily
@@ -73,7 +69,7 @@ fn context_info<'a>(
     }
 
     if offset >= (span.offset() + span.len()).saturating_sub(1) {
-        let starting_offset = before_lines_starts.first().copied().unwrap_or_else(|| {
+        let starting_offset = before_lines_starts.front().copied().unwrap_or_else(|| {
             if context_lines_before == 0 {
                 span.offset()
             } else {
@@ -108,7 +104,18 @@ impl SourceCode for [u8] {
     }
 }
 
-impl<'src> SourceCode for &'src [u8] {
+impl SourceCode for &[u8] {
+    fn read_span<'a>(
+        &'a self,
+        span: &SourceSpan,
+        context_lines_before: usize,
+        context_lines_after: usize,
+    ) -> Result<Box<dyn SpanContents<'a> + 'a>, MietteError> {
+        <[u8] as SourceCode>::read_span(self, span, context_lines_before, context_lines_after)
+    }
+}
+
+impl SourceCode for Vec<u8> {
     fn read_span<'a>(
         &'a self,
         span: &SourceSpan,
@@ -136,7 +143,7 @@ impl SourceCode for str {
 }
 
 /// Makes `src: &'static str` or `struct S<'a> { src: &'a str }` usable.
-impl<'s> SourceCode for &'s str {
+impl SourceCode for &str {
     fn read_span<'a>(
         &'a self,
         span: &SourceSpan,

tests/color_format.rs

@@ -1,8 +1,8 @@
 #![cfg(feature = "fancy-no-backtrace")]
 
-use lazy_static::lazy_static;
 use miette::{Diagnostic, MietteHandler, MietteHandlerOpts, ReportHandler, RgbColors};
 use regex::Regex;
+use std::ffi::OsString;
 use std::fmt::{self, Debug};
 use std::sync::Mutex;
 use thiserror::Error;
@@ -42,23 +42,34 @@ fn color_format(handler: MietteHandler) -> ColorFormat {
     }
 }
 
-/// Runs a function with an environment variable set to a specific value, then
-/// sets it back to it's original value once completed.
-fn with_env_var<F: FnOnce()>(var: &str, value: &str, body: F) {
-    let old_value = std::env::var_os(var);
-    std::env::set_var(var, value);
-    body();
-    if let Some(old_value) = old_value {
-        std::env::set_var(var, old_value);
-    } else {
-        std::env::remove_var(var);
+/// Store the current value of an environment variable on construction, and then
+/// restore that value when the guard is dropped.
+struct EnvVarGuard<'a> {
+    var: &'a str,
+    old_value: Option<OsString>,
+}
+
+impl EnvVarGuard<'_> {
+    fn new(var: &str) -> EnvVarGuard<'_> {
+        EnvVarGuard {
+            var,
+            old_value: std::env::var_os(var),
+        }
     }
 }
 
-lazy_static! {
-    static ref COLOR_ENV_VARS: Mutex<()> = Mutex::new(());
+impl Drop for EnvVarGuard<'_> {
+    fn drop(&mut self) {
+        if let Some(old_value) = &self.old_value {
+            std::env::set_var(self.var, old_value);
+        } else {
+            std::env::remove_var(self.var);
+        }
+    }
 }
 
+static COLOR_ENV_VARS: Mutex<()> = Mutex::new(());
+
 /// Assert the color format used by a handler with different levels of terminal
 /// support.
 fn check_colors<F: Fn(MietteHandlerOpts) -> MietteHandlerOpts>(
@@ -72,22 +83,33 @@ fn check_colors<F: Fn(MietteHandlerOpts) -> MietteHandlerOpts>(
     //
     // Since environment variables are shared for the entire process, we need
     // to ensure that only one test that modifies these env vars runs at a time.
-    let guard = COLOR_ENV_VARS.lock().unwrap();
+    let lock = COLOR_ENV_VARS.lock().unwrap();
 
-    with_env_var("NO_COLOR", "1", || {
-        let handler = make_handler(MietteHandlerOpts::new()).build();
-        assert_eq!(color_format(handler), no_support);
-    });
-    with_env_var("FORCE_COLOR", "1", || {
-        let handler = make_handler(MietteHandlerOpts::new()).build();
-        assert_eq!(color_format(handler), ansi_support);
-    });
-    with_env_var("FORCE_COLOR", "3", || {
-        let handler = make_handler(MietteHandlerOpts::new()).build();
-        assert_eq!(color_format(handler), rgb_support);
-    });
+    let guards = (
+        EnvVarGuard::new("NO_COLOR"),
+        EnvVarGuard::new("FORCE_COLOR"),
+    );
+    // Clear color environment variables that may be set outside of 'cargo test'
+    std::env::remove_var("NO_COLOR");
+    std::env::remove_var("FORCE_COLOR");
 
-    drop(guard);
+    std::env::set_var("NO_COLOR", "1");
+    let handler = make_handler(MietteHandlerOpts::new()).build();
+    assert_eq!(color_format(handler), no_support);
+    std::env::remove_var("NO_COLOR");
+
+    std::env::set_var("FORCE_COLOR", "1");
+    let handler = make_handler(MietteHandlerOpts::new()).build();
+    assert_eq!(color_format(handler), ansi_support);
+    std::env::remove_var("FORCE_COLOR");
+
+    std::env::set_var("FORCE_COLOR", "3");
+    let handler = make_handler(MietteHandlerOpts::new()).build();
+    assert_eq!(color_format(handler), rgb_support);
+    std::env::remove_var("FORCE_COLOR");
+
+    drop(guards);
+    drop(lock);
 }
 
 #[test]

tests/derive.rs

@@ -6,12 +6,14 @@ fn related() {
     #[derive(Error, Debug, Diagnostic)]
     #[error("welp")]
     #[diagnostic(code(foo::bar::baz))]
+    #[allow(dead_code)]
     struct Foo {
         #[related]
         related: Vec<Baz>,
     }
 
     #[derive(Error, Debug, Diagnostic)]
+    #[allow(dead_code)]
     enum Bar {
         #[error("variant1")]
         #[diagnostic(code(foo::bar::baz))]
@@ -29,6 +31,7 @@ fn related() {
 
     #[derive(Error, Debug, Diagnostic)]
     #[error("welp2")]
+    #[allow(dead_code)]
     struct Baz;
 }
 
@@ -37,6 +40,7 @@ fn related_report() {
     #[derive(Error, Debug, Diagnostic)]
     #[error("welp")]
     #[diagnostic(code(foo::bar::baz))]
+    #[allow(dead_code)]
     struct Foo {
         #[related]
         related: Vec<Report>,
@@ -185,35 +189,30 @@ fn fmt_help() {
     #[derive(Debug, Diagnostic, Error)]
     #[error("welp")]
     #[diagnostic(code(foo::bar::baz), help("{} x {0} x {:?}", 1, "2"))]
-    struct FooStruct(String);
+    struct FooStruct<'a>(&'a str);
 
     assert_eq!(
         "1 x hello x \"2\"".to_string(),
-        FooStruct("hello".into()).help().unwrap().to_string()
+        FooStruct("hello").help().unwrap().to_string()
     );
 
     #[derive(Debug, Diagnostic, Error)]
     #[error("welp")]
     #[diagnostic(code(foo::bar::baz), help("{} x {my_field} x {:?}", 1, "2"))]
-    struct BarStruct {
-        my_field: String,
+    struct BarStruct<'a> {
+        my_field: &'a str,
     }
 
     assert_eq!(
         "1 x hello x \"2\"".to_string(),
-        BarStruct {
-            my_field: "hello".into()
-        }
-        .help()
-        .unwrap()
-        .to_string()
+        BarStruct { my_field: "hello" }.help().unwrap().to_string()
     );
 
     #[derive(Debug, Diagnostic, Error)]
     #[error("welp")]
-    enum FooEnum {
+    enum FooEnum<'a> {
         #[diagnostic(code(foo::x), help("{} x {0} x {:?}", 1, "2"))]
-        X(String),
+        X(&'a str),
 
         #[diagnostic(code(foo::x), help("{} x {len} x {:?}", 1, "2"))]
         Y { len: usize },
@@ -224,7 +223,7 @@ fn fmt_help() {
 
     assert_eq!(
         "1 x bar x \"2\"".to_string(),
-        FooEnum::X("bar".into()).help().unwrap().to_string()
+        FooEnum::X("bar").help().unwrap().to_string()
     );
 
     assert_eq!(
@@ -243,65 +242,49 @@ fn help_field() {
     #[derive(Debug, Diagnostic, Error)]
     #[error("welp")]
     #[diagnostic()]
-    struct Foo {
+    struct Foo<'a> {
         #[help]
-        do_this: Option<String>,
+        do_this: Option<&'a str>,
     }
 
     assert_eq!(
         "x".to_string(),
-        Foo {
-            do_this: Some("x".into())
-        }
-        .help()
-        .unwrap()
-        .to_string()
+        Foo { do_this: Some("x") }.help().unwrap().to_string()
     );
 
     #[derive(Debug, Diagnostic, Error)]
     #[error("welp")]
     #[diagnostic()]
-    enum Bar {
-        A(#[help] Option<String>),
+    enum Bar<'a> {
+        A(#[help] Option<&'a str>),
         B {
             #[help]
-            do_this: Option<String>,
+            do_this: Option<&'a str>,
         },
     }
 
     assert_eq!(
         "x".to_string(),
-        Bar::A(Some("x".into())).help().unwrap().to_string()
+        Bar::A(Some("x")).help().unwrap().to_string()
     );
     assert_eq!(
         "x".to_string(),
-        Bar::B {
-            do_this: Some("x".into())
-        }
-        .help()
-        .unwrap()
-        .to_string()
+        Bar::B { do_this: Some("x") }.help().unwrap().to_string()
     );
 
     #[derive(Debug, Diagnostic, Error)]
     #[error("welp")]
     #[diagnostic()]
-    struct Baz(#[help] Option<String>);
+    struct Baz<'a>(#[help] Option<&'a str>);
 
-    assert_eq!(
-        "x".to_string(),
-        Baz(Some("x".into())).help().unwrap().to_string()
-    );
+    assert_eq!("x".to_string(), Baz(Some("x")).help().unwrap().to_string());
 
     #[derive(Debug, Diagnostic, Error)]
     #[error("welp")]
     #[diagnostic()]
-    struct Quux(#[help] String);
+    struct Quux<'a>(#[help] &'a str);
 
-    assert_eq!(
-        "x".to_string(),
-        Quux("x".into()).help().unwrap().to_string()
-    );
+    assert_eq!("x".to_string(), Quux("x").help().unwrap().to_string());
 }
 
 #[test]
@@ -309,9 +292,10 @@ fn test_snippet_named_struct() {
     #[derive(Debug, Diagnostic, Error)]
     #[error("welp")]
     #[diagnostic(code(foo::bar::baz))]
-    struct Foo {
+    #[allow(dead_code)]
+    struct Foo<'a> {
         #[source_code]
-        src: String,
+        src: &'a str,
         #[label("var 1")]
         var1: SourceSpan,
         #[label = "var 2"]
@@ -331,8 +315,9 @@ fn test_snippet_unnamed_struct() {
     #[derive(Debug, Diagnostic, Error)]
     #[error("welp")]
     #[diagnostic(code(foo::bar::baz))]
-    struct Foo(
-        #[source_code] String,
+    #[allow(dead_code)]
+    struct Foo<'a>(
+        #[source_code] &'a str,
         #[label("{0}")] SourceSpan,
         #[label = "idk"] SourceSpan,
         #[label] SourceSpan,
@@ -346,11 +331,11 @@ fn test_snippet_enum() {
     #[derive(Debug, Diagnostic, Error)]
     #[error("welp")]
     #[allow(dead_code)]
-    enum Foo {
+    enum Foo<'a> {
         #[diagnostic(code(foo::a))]
         A {
             #[source_code]
-            src: String,
+            src: &'a str,
             msg: String,
             #[label("hi this is where the thing went wrong ({msg})")]
             var0: SourceSpan,
@@ -427,7 +412,7 @@ impl ForwardsTo {
     fn new() -> Self {
         ForwardsTo {
             src: SNIPPET_TEXT.into(),
-            label: SourceSpan::new(11.into(), 6.into()),
+            label: SourceSpan::new(11.into(), 6),
         }
     }
 }
@@ -516,9 +501,9 @@ fn test_forward_struct_named() {
         help("{help}"),
         forward(span)
     )]
-    struct Struct {
+    struct Struct<'a> {
         span: ForwardsTo,
-        help: &'static str,
+        help: &'a str,
     }
     // Also check the From impl here
     let diag = Struct {
@@ -535,7 +520,7 @@ fn test_forward_struct_unnamed() {
     #[derive(Debug, Diagnostic, Error)]
     #[error("display")]
     #[diagnostic(code(foo::bar::overridden), url("{1}"), forward(0))]
-    struct Struct(ForwardsTo, &'static str);
+    struct Struct<'a>(ForwardsTo, &'a str);
 
     // Also check the From impl here
     let diag = Struct(ForwardsTo::new(), "url here");
@@ -546,12 +531,12 @@ fn test_forward_struct_unnamed() {
 #[test]
 fn test_forward_enum_named() {
     #[derive(Debug, Diagnostic, Error)]
-    enum Enum {
+    enum Enum<'a> {
         #[error("help: {help_text}")]
         #[diagnostic(code(foo::bar::overridden), help("{help_text}"), forward(span))]
         Variant {
             span: ForwardsTo,
-            help_text: &'static str,
+            help_text: &'a str,
         },
     }
     // Also check the From impl here
@@ -569,10 +554,10 @@ fn test_forward_enum_named() {
 #[test]
 fn test_forward_enum_unnamed() {
     #[derive(Debug, Diagnostic, Error)]
-    enum ForwardEnumUnnamed {
+    enum ForwardEnumUnnamed<'a> {
         #[error("help: {1}")]
         #[diagnostic(code(foo::bar::overridden), help("{1}"), forward(0))]
-        Variant(ForwardsTo, &'static str),
+        Variant(ForwardsTo, &'a str),
     }
     // Also check the From impl here
     let variant = ForwardEnumUnnamed::Variant(ForwardsTo::new(), "overridden help please");
@@ -589,7 +574,7 @@ fn test_unit_struct_display() {
     #[error("unit only")]
     #[diagnostic(code(foo::bar::overridden), help("hello from unit help"))]
     struct UnitOnly;
-    assert_eq!(UnitOnly.help().unwrap().to_string(), "hello from unit help")
+    assert_eq!(UnitOnly.help().unwrap().to_string(), "hello from unit help");
 }
 
 #[test]
@@ -603,5 +588,47 @@ fn test_unit_enum_display() {
     assert_eq!(
         Enum::UnitVariant.help().unwrap().to_string(),
         "hello from unit help"
-    )
+    );
+}
+
+#[test]
+fn test_optional_source_code() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("struct with optional source")]
+    struct Struct {
+        #[source_code]
+        src: Option<String>,
+    }
+    assert!(Struct { src: None }.source_code().is_none());
+    assert!(Struct {
+        src: Some("".to_string())
+    }
+    .source_code()
+    .is_some());
+
+    #[derive(Debug, Diagnostic, Error)]
+    enum Enum {
+        #[error("variant1 with optional source")]
+        Variant1 {
+            #[source_code]
+            src: Option<String>,
+        },
+        #[error("variant2 with optional source")]
+        Variant2 {
+            #[source_code]
+            src: Option<String>,
+        },
+    }
+    assert!(Enum::Variant1 { src: None }.source_code().is_none());
+    assert!(Enum::Variant1 {
+        src: Some("".to_string())
+    }
+    .source_code()
+    .is_some());
+    assert!(Enum::Variant2 { src: None }.source_code().is_none());
+    assert!(Enum::Variant2 {
+        src: Some("".to_string())
+    }
+    .source_code()
+    .is_some());
 }

tests/narrated.rs

@@ -29,7 +29,7 @@ fn single_line_with_wide_char() -> Result<(), MietteError> {
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label("this bit here")]
         highlight: SourceSpan,
     }
@@ -65,7 +65,7 @@ fn single_line_highlight() -> Result<(), MietteError> {
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label("this bit here")]
         highlight: SourceSpan,
     }
@@ -101,7 +101,7 @@ fn single_line_highlight_offset_zero() -> Result<(), MietteError> {
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label("this bit here")]
         highlight: SourceSpan,
     }
@@ -136,7 +136,7 @@ fn single_line_highlight_with_empty_span() -> Result<(), MietteError> {
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label("this bit here")]
         highlight: SourceSpan,
     }
@@ -172,7 +172,7 @@ fn single_line_highlight_no_label() -> Result<(), MietteError> {
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label]
         highlight: SourceSpan,
     }
@@ -208,7 +208,7 @@ fn single_line_highlight_at_line_start() -> Result<(), MietteError> {
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label("this bit here")]
         highlight: SourceSpan,
     }
@@ -244,7 +244,7 @@ fn multiple_same_line_highlights() -> Result<(), MietteError> {
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label = "x"]
         highlight1: SourceSpan,
         #[label = "y"]
@@ -288,7 +288,7 @@ fn multiline_highlight_adjacent() -> Result<(), MietteError> {
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label = "these two lines"]
         highlight: SourceSpan,
     }
@@ -325,7 +325,7 @@ fn multiline_highlight_flyby() -> Result<(), MietteError> {
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label = "block 1"]
         highlight1: SourceSpan,
         #[label = "block 2"]
@@ -378,7 +378,7 @@ fn multiline_highlight_no_label() -> Result<(), MietteError> {
         #[source]
         source: Inner,
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label = "block 1"]
         highlight1: SourceSpan,
         #[label]
@@ -444,7 +444,7 @@ fn multiple_multiline_highlights_adjacent() -> Result<(), MietteError> {
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label = "this bit here"]
         highlight1: SourceSpan,
         #[label = "also this bit"]
@@ -492,7 +492,7 @@ fn multiple_multiline_highlights_overlapping_lines() -> Result<(), MietteError>
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label = "this bit here"]
         highlight1: SourceSpan,
         #[label = "also this bit"]
@@ -520,7 +520,7 @@ fn multiple_multiline_highlights_overlapping_offsets() -> Result<(), MietteError
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label = "this bit here"]
         highlight1: SourceSpan,
         #[label = "also this bit"]
@@ -559,7 +559,7 @@ fn related() -> Result<(), MietteError> {
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label("this bit here")]
         highlight: SourceSpan,
         #[related]
@@ -614,7 +614,7 @@ fn related_source_code_propagation() -> Result<(), MietteError> {
     #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
     struct MyBad {
         #[source_code]
-        src: NamedSource,
+        src: NamedSource<String>,
         #[label("this bit here")]
         highlight: SourceSpan,
         #[related]

tests/test_boxed.rs

@@ -1,6 +1,7 @@
 use miette::{miette, Diagnostic, LabeledSpan, Report, SourceSpan};
 use std::error::Error as StdError;
 use std::io;
+use std::ops::Deref;
 use thiserror::Error;
 
 #[derive(Error, Debug)]
@@ -159,7 +160,7 @@ impl Diagnostic for CustomDiagnostic {
 
 #[test]
 fn test_boxed_custom_diagnostic() {
-    fn assert_report(report: &Report) {
+    fn assert_report<T: ?Sized + Diagnostic>(report: &impl Deref<Target = T>) {
         assert_eq!(
             report.source().map(|source| source.to_string()),
             Some("oh no!".to_owned()),
@@ -215,10 +216,16 @@ fn test_boxed_custom_diagnostic() {
     let main_diagnostic = Box::new(main_diagnostic) as Box<dyn Diagnostic + Send + Sync + 'static>;
     let report = miette!(main_diagnostic);
     assert_report(&report);
+
+    // Now make sure that conversion to a trait-object is lossless!
+    let report_ref: &dyn Diagnostic = report.as_ref();
+    assert_report(&report_ref);
+
+    let report_box: Box<dyn Diagnostic> = report.into();
+    assert_report(&report_box);
 }
 
 #[test]
-#[ignore = "I don't know why this isn't working but it needs fixing."]
 fn test_boxed_sources() {
     let error = MyError {
         source: io::Error::new(io::ErrorKind::Other, "oh no!"),

tests/test_chain.rs

@@ -1,7 +1,7 @@
 use miette::{miette, Report};
 
 fn error() -> Report {
-    miette!(0).wrap_err(1).wrap_err(2).wrap_err(3)
+    miette!("0").wrap_err(1).wrap_err(2).wrap_err(3)
 }
 
 #[test]

tests/test_derive_attr.rs

@@ -10,7 +10,7 @@ fn enum_uses_base_attr() {
     enum MyBad {
         Only {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
         },
@@ -32,7 +32,7 @@ fn enum_uses_variant_attr() {
         #[diagnostic(code(error::on::variant))]
         Only {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
         },
@@ -55,7 +55,7 @@ fn multiple_attrs_allowed_on_item() {
     enum MyBad {
         Only {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
         },
@@ -79,7 +79,7 @@ fn multiple_attrs_allowed_on_variant() {
         #[diagnostic(help("try doing it correctly"))]
         Only {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
         },
@@ -104,7 +104,7 @@ fn attrs_can_be_split_between_item_and_variants() {
         #[diagnostic(url("https://example.com/foo/bar"))]
         Only {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
         },
@@ -130,7 +130,7 @@ fn attr_not_required() {
     enum MyBad {
         Only {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
         },

tests/test_derive_collection.rs

@@ -0,0 +1,306 @@
+use std::{
+    collections::{LinkedList, VecDeque},
+    ops::Range,
+};
+
+// Testing of the `diagnostic` attr used by derive(Diagnostic)
+use miette::{Diagnostic, LabeledSpan, NamedSource, SourceSpan};
+use thiserror::Error;
+
+#[test]
+fn attr_collection_in_enum() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("oops!")]
+    enum MyBad {
+        Only {
+            #[source_code]
+            src: NamedSource<String>,
+            #[label("this bit here")]
+            highlight: SourceSpan,
+            #[label(collection, "and here")]
+            highlight2: Vec<SourceSpan>,
+        },
+    }
+
+    let src = "source\n  text\n    here".to_string();
+    let err = MyBad::Only {
+        src: NamedSource::new("bad_file.rs", src),
+        highlight: (9, 4).into(),
+        highlight2: vec![(1, 2).into(), (3, 4).into()],
+    };
+    let mut label_iter = err.labels().unwrap();
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("this bit here".into()), 9usize, 4usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 1usize, 2usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 3usize, 4usize);
+    assert_eq!(err_span, expectation);
+}
+
+#[test]
+fn attr_collection_in_struct() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("oops!")]
+    struct MyBad {
+        #[source_code]
+        src: NamedSource<String>,
+        #[label("this bit here")]
+        highlight: SourceSpan,
+        #[label(collection, "and here")]
+        highlight2: Vec<SourceSpan>,
+    }
+
+    let src = "source\n  text\n    here".to_string();
+    let err = MyBad {
+        src: NamedSource::new("bad_file.rs", src),
+        highlight: (9, 4).into(),
+        highlight2: vec![(1, 2).into(), (3, 4).into()],
+    };
+    let mut label_iter = err.labels().unwrap();
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("this bit here".into()), 9usize, 4usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 1usize, 2usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 3usize, 4usize);
+    assert_eq!(err_span, expectation);
+}
+
+#[test]
+fn attr_collection_as_deque() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("oops!")]
+    struct MyBad {
+        #[source_code]
+        src: NamedSource<String>,
+        #[label("this bit here")]
+        highlight: SourceSpan,
+        #[label(collection, "and here")]
+        highlight2: VecDeque<SourceSpan>,
+    }
+
+    let src = "source\n  text\n    here".to_string();
+    let err = MyBad {
+        src: NamedSource::new("bad_file.rs", src),
+        highlight: (9, 4).into(),
+        highlight2: VecDeque::from([(1, 2).into(), (3, 4).into()]),
+    };
+    let mut label_iter = err.labels().unwrap();
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("this bit here".into()), 9usize, 4usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 1usize, 2usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 3usize, 4usize);
+    assert_eq!(err_span, expectation);
+}
+
+#[test]
+fn attr_collection_as_linked_list() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("oops!")]
+    struct MyBad {
+        #[source_code]
+        src: NamedSource<String>,
+        #[label("this bit here")]
+        highlight: SourceSpan,
+        #[label(collection, "and here")]
+        highlight2: LinkedList<SourceSpan>,
+    }
+
+    let src = "source\n  text\n    here".to_string();
+    let err = MyBad {
+        src: NamedSource::new("bad_file.rs", src),
+        highlight: (9, 4).into(),
+        highlight2: LinkedList::from([(1, 2).into(), (3, 4).into()]),
+    };
+    let mut label_iter = err.labels().unwrap();
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("this bit here".into()), 9usize, 4usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 1usize, 2usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 3usize, 4usize);
+    assert_eq!(err_span, expectation);
+}
+
+#[test]
+fn attr_collection_of_tuple() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("oops!")]
+    struct MyBad {
+        #[source_code]
+        src: NamedSource<String>,
+        #[label("this bit here")]
+        highlight: SourceSpan,
+        #[label(collection, "and here")]
+        highlight2: Vec<(usize, usize)>,
+    }
+
+    let src = "source\n  text\n    here".to_string();
+    let err = MyBad {
+        src: NamedSource::new("bad_file.rs", src),
+        highlight: (9, 4).into(),
+        highlight2: vec![(1, 2), (3, 4)],
+    };
+    let mut label_iter = err.labels().unwrap();
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("this bit here".into()), 9usize, 4usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 1usize, 2usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 3usize, 4usize);
+    assert_eq!(err_span, expectation);
+}
+
+#[test]
+fn attr_collection_of_range() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("oops!")]
+    struct MyBad {
+        #[source_code]
+        src: NamedSource<String>,
+        #[label("this bit here")]
+        highlight: SourceSpan,
+        #[label(collection, "and here")]
+        highlight2: Vec<Range<usize>>,
+    }
+
+    let src = "source\n  text\n    here".to_string();
+    let err = MyBad {
+        src: NamedSource::new("bad_file.rs", src),
+        highlight: (9, 4).into(),
+        highlight2: vec![1..3, 3..7],
+    };
+    let mut label_iter = err.labels().unwrap();
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("this bit here".into()), 9usize, 4usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 1usize, 2usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 3usize, 4usize);
+    assert_eq!(err_span, expectation);
+}
+
+#[test]
+fn attr_collection_of_labeled_span_in_struct() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("oops!")]
+    struct MyBad {
+        #[source_code]
+        src: NamedSource<String>,
+        #[label("this bit here")]
+        highlight: SourceSpan,
+        #[label(collection, "then there")]
+        highlight2: Vec<LabeledSpan>,
+    }
+
+    let src = "source\n  text\n    here".to_string();
+    let err = MyBad {
+        src: NamedSource::new("bad_file.rs", src),
+        highlight: (9, 4).into(),
+        highlight2: vec![
+            LabeledSpan::new_with_span(Some("continuing here".to_string()), (1, 2)),
+            LabeledSpan::new_with_span(None, (3, 4)),
+        ],
+    };
+    let mut label_iter = err.labels().unwrap();
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("this bit here".into()), 9usize, 4usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("continuing here".into()), 1usize, 2usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("then there".into()), 3usize, 4usize);
+    assert_eq!(err_span, expectation);
+}
+
+#[test]
+fn attr_collection_of_labeled_span_in_enum() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("oops!")]
+    enum MyBad {
+        Only {
+            #[source_code]
+            src: NamedSource<String>,
+            #[label("this bit here")]
+            highlight: SourceSpan,
+            #[label(collection, "then there")]
+            highlight2: Vec<LabeledSpan>,
+        },
+    }
+
+    let src = "source\n  text\n    here".to_string();
+    let err = MyBad::Only {
+        src: NamedSource::new("bad_file.rs", src),
+        highlight: (9, 4).into(),
+        highlight2: vec![
+            LabeledSpan::new_with_span(Some("continuing here".to_string()), (1, 2)),
+            LabeledSpan::new_with_span(None, (3, 4)),
+        ],
+    };
+    let mut label_iter = err.labels().unwrap();
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("this bit here".into()), 9usize, 4usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("continuing here".into()), 1usize, 2usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("then there".into()), 3usize, 4usize);
+    assert_eq!(err_span, expectation);
+}
+
+#[test]
+fn attr_collection_multi() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("oops!")]
+    struct MyBad {
+        #[source_code]
+        src: NamedSource<String>,
+        #[label("this bit here")]
+        highlight: SourceSpan,
+        #[label(collection, "and here")]
+        highlight2: Vec<SourceSpan>,
+        #[label(collection, "and there")]
+        highlight3: Vec<SourceSpan>,
+    }
+
+    let src = "source\n  text\n    here".to_string();
+    let err = MyBad {
+        src: NamedSource::new("bad_file.rs", src),
+        highlight: (9, 4).into(),
+        highlight2: vec![(1, 2).into(), (3, 4).into()],
+        highlight3: vec![(5, 6).into(), (7, 8).into()],
+    };
+    let mut label_iter = err.labels().unwrap();
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("this bit here".into()), 9usize, 4usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 1usize, 2usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and here".into()), 3usize, 4usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and there".into()), 5usize, 6usize);
+    assert_eq!(err_span, expectation);
+    let err_span = label_iter.next().unwrap();
+    let expectation = LabeledSpan::new(Some("and there".into()), 7usize, 8usize);
+    assert_eq!(err_span, expectation);
+}

tests/test_derive_source_chain.rs

@@ -0,0 +1,69 @@
+use std::sync::Arc;
+
+use miette::{miette, Diagnostic};
+use thiserror::Error;
+
+#[test]
+fn test_source() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("Bar")]
+    struct Bar;
+
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("Foo")]
+    struct Foo {
+        #[source]
+        bar: Bar,
+    }
+
+    let e = miette!(Foo { bar: Bar });
+    let mut chain = e.chain();
+
+    assert_eq!("Foo", chain.next().unwrap().to_string());
+    assert_eq!("Bar", chain.next().unwrap().to_string());
+    assert!(chain.next().is_none());
+}
+
+#[test]
+fn test_source_boxed() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("Bar")]
+    struct Bar;
+
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("Foo")]
+    struct Foo {
+        #[source]
+        bar: Box<dyn Diagnostic + Send + Sync>,
+    }
+
+    let error = miette!(Foo { bar: Box::new(Bar) });
+
+    let mut chain = error.chain();
+
+    assert_eq!("Foo", chain.next().unwrap().to_string());
+    assert_eq!("Bar", chain.next().unwrap().to_string());
+    assert!(chain.next().is_none());
+}
+
+#[test]
+fn test_source_arc() {
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("Bar")]
+    struct Bar;
+
+    #[derive(Debug, Diagnostic, Error)]
+    #[error("Foo")]
+    struct Foo {
+        #[source]
+        bar: Arc<dyn Diagnostic + Send + Sync>,
+    }
+
+    let error = miette!(Foo { bar: Arc::new(Bar) });
+
+    let mut chain = error.chain();
+
+    assert_eq!("Foo", chain.next().unwrap().to_string());
+    assert_eq!("Bar", chain.next().unwrap().to_string());
+    assert!(chain.next().is_none());
+}

tests/test_diagnostic_source_macro.rs

@@ -1,5 +1,16 @@
 use miette::Diagnostic;
 
+#[derive(Debug, miette::Diagnostic, thiserror::Error)]
+#[error("A complex error happened")]
+struct SourceError {
+    #[source_code]
+    code: String,
+    #[help]
+    help: String,
+    #[label("here")]
+    label: (usize, usize),
+}
+
 #[derive(Debug, miette::Diagnostic, thiserror::Error)]
 #[error("AnErr")]
 struct AnErr;
@@ -8,7 +19,7 @@ struct AnErr;
 #[error("TestError")]
 struct TestStructError {
     #[diagnostic_source]
-    asdf_inner_foo: AnErr,
+    asdf_inner_foo: SourceError,
 }
 
 #[derive(Debug, miette::Diagnostic, thiserror::Error)]
@@ -30,6 +41,14 @@ struct TestTupleError(#[diagnostic_source] AnErr);
 #[error("TestError")]
 struct TestBoxedError(#[diagnostic_source] Box<dyn Diagnostic>);
 
+#[derive(Debug, miette::Diagnostic, thiserror::Error)]
+#[error("TestError")]
+struct TestBoxedSendError(#[diagnostic_source] Box<dyn Diagnostic + Send>);
+
+#[derive(Debug, miette::Diagnostic, thiserror::Error)]
+#[error("TestError")]
+struct TestBoxedSendSyncError(#[diagnostic_source] Box<dyn Diagnostic + Send + Sync>);
+
 #[derive(Debug, miette::Diagnostic, thiserror::Error)]
 #[error("TestError")]
 struct TestArcedError(#[diagnostic_source] std::sync::Arc<dyn Diagnostic>);
@@ -37,7 +56,11 @@ struct TestArcedError(#[diagnostic_source] std::sync::Arc<dyn Diagnostic>);
 #[test]
 fn test_diagnostic_source() {
     let error = TestStructError {
-        asdf_inner_foo: AnErr,
+        asdf_inner_foo: SourceError {
+            code: String::new(),
+            help: String::new(),
+            label: (0, 0),
+        },
     };
     assert!(error.diagnostic_source().is_some());
 
@@ -56,6 +79,339 @@ fn test_diagnostic_source() {
     let error = TestBoxedError(Box::new(AnErr));
     assert!(error.diagnostic_source().is_some());
 
+    let error = TestBoxedSendError(Box::new(AnErr));
+    assert!(error.diagnostic_source().is_some());
+
+    let error = TestBoxedSendSyncError(Box::new(AnErr));
+    assert!(error.diagnostic_source().is_some());
+
     let error = TestArcedError(std::sync::Arc::new(AnErr));
     assert!(error.diagnostic_source().is_some());
 }
+
+#[cfg(feature = "fancy-no-backtrace")]
+#[test]
+fn test_diagnostic_source_pass_extra_info() {
+    let diag = TestBoxedError(Box::new(SourceError {
+        code: String::from("Hello\nWorld!"),
+        help: String::from("Have you tried turning it on and off again?"),
+        label: (1, 4),
+    }));
+    let mut out = String::new();
+    miette::GraphicalReportHandler::new_themed(miette::GraphicalTheme::unicode_nocolor())
+        .with_width(80)
+        .with_footer("this is a footer".into())
+        .render_report(&mut out, &diag)
+        .unwrap();
+    println!("Error: {}", out);
+    let expected = r#"
+  × TestError
+  ╰─▶   × A complex error happened
+         ╭─[1:2]
+       1 │ Hello
+         ·  ──┬─
+         ·    ╰── here
+       2 │ World!
+         ╰────
+        help: Have you tried turning it on and off again?
+      
+
+  this is a footer
+"#
+    .trim_start_matches('\n');
+
+    assert_eq!(expected, out);
+}
+
+#[cfg(feature = "fancy-no-backtrace")]
+#[test]
+fn test_diagnostic_source_is_output() {
+    let diag = TestStructError {
+        asdf_inner_foo: SourceError {
+            code: String::from("right here"),
+            help: String::from("That's where the error is!"),
+            label: (6, 4),
+        },
+    };
+    let mut out = String::new();
+    miette::GraphicalReportHandler::new_themed(miette::GraphicalTheme::unicode_nocolor())
+        .with_width(80)
+        .render_report(&mut out, &diag)
+        .unwrap();
+    println!("{}", out);
+
+    let expected = r#"
+  × TestError
+  ╰─▶   × A complex error happened
+         ╭────
+       1 │ right here
+         ·       ──┬─
+         ·         ╰── here
+         ╰────
+        help: That's where the error is!
+      
+"#
+    .trim_start_matches('\n');
+
+    assert_eq!(expected, out);
+}
+
+#[cfg(feature = "fancy-no-backtrace")]
+#[derive(Debug, miette::Diagnostic, thiserror::Error)]
+#[error("A nested error happened")]
+struct NestedError {
+    #[source_code]
+    code: String,
+    #[label("here")]
+    label: (usize, usize),
+    #[diagnostic_source]
+    the_other_err: Box<dyn Diagnostic>,
+}
+
+#[cfg(feature = "fancy-no-backtrace")]
+#[test]
+fn test_nested_diagnostic_source_is_output() {
+    let inner_error = TestStructError {
+        asdf_inner_foo: SourceError {
+            code: String::from("This is another error"),
+            help: String::from("You should fix this"),
+            label: (3, 4),
+        },
+    };
+    let diag = NestedError {
+        code: String::from("right here"),
+        label: (6, 4),
+        the_other_err: Box::new(inner_error),
+    };
+    let mut out = String::new();
+    miette::GraphicalReportHandler::new_themed(miette::GraphicalTheme::unicode_nocolor())
+        .with_width(80)
+        .with_footer("Yooo, a footer".to_string())
+        .render_report(&mut out, &diag)
+        .unwrap();
+    println!("{}", out);
+
+    let expected = r#"
+  × A nested error happened
+  ├─▶   × TestError
+  │   
+  ╰─▶   × A complex error happened
+         ╭────
+       1 │ This is another error
+         ·    ──┬─
+         ·      ╰── here
+         ╰────
+        help: You should fix this
+      
+   ╭────
+ 1 │ right here
+   ·       ──┬─
+   ·         ╰── here
+   ╰────
+
+  Yooo, a footer
+"#
+    .trim_start_matches('\n');
+
+    assert_eq!(expected, out);
+}
+
+#[cfg(feature = "fancy-no-backtrace")]
+#[derive(Debug, miette::Diagnostic, thiserror::Error)]
+#[error("A multi-error happened")]
+struct MultiError {
+    #[related]
+    related_errs: Vec<Box<dyn Diagnostic>>,
+}
+
+#[cfg(feature = "fancy-no-backtrace")]
+#[test]
+fn test_nested_cause_chains_for_related_errors_are_output() {
+    let inner_error = TestStructError {
+        asdf_inner_foo: SourceError {
+            code: String::from("This is another error"),
+            help: String::from("You should fix this"),
+            label: (3, 4),
+        },
+    };
+    let first_error = NestedError {
+        code: String::from("right here"),
+        label: (6, 4),
+        the_other_err: Box::new(inner_error),
+    };
+    let second_error = SourceError {
+        code: String::from("You're actually a mess"),
+        help: String::from("Get a grip..."),
+        label: (3, 4),
+    };
+    let multi_error = MultiError {
+        related_errs: vec![Box::new(first_error), Box::new(second_error)],
+    };
+    let diag = NestedError {
+        code: String::from("the outside world"),
+        label: (6, 4),
+        the_other_err: Box::new(multi_error),
+    };
+    let mut out = String::new();
+    miette::GraphicalReportHandler::new_themed(miette::GraphicalTheme::unicode_nocolor())
+        .with_width(80)
+        .with_footer("Yooo, a footer".to_string())
+        .render_report(&mut out, &diag)
+        .unwrap();
+    println!("{}", out);
+
+    let expected = r#"
+  × A nested error happened
+  ╰─▶   × A multi-error happened
+      
+      Error:
+        × A nested error happened
+        ├─▶   × TestError
+        │
+        ╰─▶   × A complex error happened
+               ╭────
+             1 │ This is another error
+               ·    ──┬─
+               ·      ╰── here
+               ╰────
+              help: You should fix this
+      
+         ╭────
+       1 │ right here
+         ·       ──┬─
+         ·         ╰── here
+         ╰────
+      
+      Error:
+        × A complex error happened
+         ╭────
+       1 │ You're actually a mess
+         ·    ──┬─
+         ·      ╰── here
+         ╰────
+        help: Get a grip...
+      
+   ╭────
+ 1 │ the outside world
+   ·       ──┬─
+   ·         ╰── here
+   ╰────
+
+  Yooo, a footer
+"#
+    .trim_start_matches('\n');
+
+    assert_eq!(expected, out);
+}
+
+#[cfg(feature = "fancy-no-backtrace")]
+#[test]
+fn test_display_related_errors_as_nested() {
+    let inner_error = TestStructError {
+        asdf_inner_foo: SourceError {
+            code: String::from("This is another error"),
+            help: String::from("You should fix this"),
+            label: (3, 4),
+        },
+    };
+    let first_error = NestedError {
+        code: String::from("right here"),
+        label: (6, 4),
+        the_other_err: Box::new(inner_error),
+    };
+    let second_error = SourceError {
+        code: String::from("You're actually a mess"),
+        help: String::from("Get a grip..."),
+        label: (3, 4),
+    };
+    let diag = MultiError {
+        related_errs: vec![
+            Box::new(MultiError {
+                related_errs: vec![Box::new(first_error), Box::new(AnErr)],
+            }),
+            Box::new(second_error),
+        ],
+    };
+
+    let mut out = String::new();
+    miette::GraphicalReportHandler::new_themed(miette::GraphicalTheme::unicode_nocolor())
+        .with_width(80)
+        .with_show_related_as_nested(true)
+        .render_report(&mut out, &diag)
+        .unwrap();
+    println!("{}", out);
+
+    let expected = r#"
+  × A multi-error happened
+  ├─▶   × A multi-error happened
+  │     ├─▶   × A nested error happened
+  │     │      ╭────
+  │     │    1 │ right here
+  │     │      ·       ──┬─
+  │     │      ·         ╰── here
+  │     │      ╰────
+  │     ╰─▶   × AnErr
+  ╰─▶   × A complex error happened
+         ╭────
+       1 │ You're actually a mess
+         ·    ──┬─
+         ·      ╰── here
+         ╰────
+        help: Get a grip...
+"#
+    .trim_start_matches('\n');
+
+    assert_eq!(expected, out);
+}
+
+#[cfg(feature = "fancy-no-backtrace")]
+#[derive(Debug, miette::Diagnostic, thiserror::Error)]
+#[error("A case1 error happened")]
+enum NestedEnumError {
+    Case1 {
+        #[source_code]
+        code: String,
+        #[diagnostic_source]
+        the_other_err: Case1Inner,
+    },
+}
+
+#[cfg(feature = "fancy-no-backtrace")]
+#[derive(Debug, miette::Diagnostic, thiserror::Error)]
+#[error("I am the inner error")]
+struct Case1Inner {
+    #[label("inner-label")]
+    label: (usize, usize),
+}
+
+#[cfg(feature = "fancy-no-backtrace")]
+#[test]
+fn source_is_inherited_to_causes() {
+    let diag = NestedEnumError::Case1 {
+        code: String::from("this is the parent source"),
+        the_other_err: Case1Inner { label: (8, 3) },
+    };
+    let mut out = String::new();
+    miette::GraphicalReportHandler::new_themed(miette::GraphicalTheme::unicode_nocolor())
+        .with_width(80)
+        .with_footer("Yooo, a footer".to_string())
+        .render_report(&mut out, &diag)
+        .unwrap();
+    println!("{}", out);
+
+    let expected = r#"
+  × A case1 error happened
+  ╰─▶   × I am the inner error
+         ╭────
+       1 │ this is the parent source
+         ·         ─┬─
+         ·          ╰── inner-label
+         ╰────
+      
+
+  Yooo, a footer
+"#
+    .trim_start_matches('\n');
+
+    assert_eq!(expected, out);
+}

tests/test_downcast.rs

@@ -3,7 +3,7 @@ mod drop;
 
 use self::common::*;
 use self::drop::{DetectDrop, Flag};
-use miette::{Diagnostic, Report};
+use miette::{Diagnostic, MietteDiagnostic, Report};
 use std::error::Error as StdError;
 use std::fmt::{self, Display};
 use std::io;
@@ -12,11 +12,19 @@ use std::io;
 fn test_downcast() {
     assert_eq!(
         "oh no!",
-        bail_literal().unwrap_err().downcast::<&str>().unwrap(),
+        bail_literal()
+            .unwrap_err()
+            .downcast::<MietteDiagnostic>()
+            .unwrap()
+            .message,
     );
     assert_eq!(
         "oh no!",
-        bail_fmt().unwrap_err().downcast::<String>().unwrap(),
+        bail_fmt()
+            .unwrap_err()
+            .downcast::<MietteDiagnostic>()
+            .unwrap()
+            .message,
     );
     assert_eq!(
         "oh no!",
@@ -32,11 +40,19 @@ fn test_downcast() {
 fn test_downcast_ref() {
     assert_eq!(
         "oh no!",
-        *bail_literal().unwrap_err().downcast_ref::<&str>().unwrap(),
+        bail_literal()
+            .unwrap_err()
+            .downcast_ref::<MietteDiagnostic>()
+            .unwrap()
+            .message,
     );
     assert_eq!(
         "oh no!",
-        bail_fmt().unwrap_err().downcast_ref::<String>().unwrap(),
+        bail_fmt()
+            .unwrap_err()
+            .downcast_ref::<MietteDiagnostic>()
+            .unwrap()
+            .message,
     );
     assert_eq!(
         "oh no!",
@@ -52,11 +68,19 @@ fn test_downcast_ref() {
 fn test_downcast_mut() {
     assert_eq!(
         "oh no!",
-        *bail_literal().unwrap_err().downcast_mut::<&str>().unwrap(),
+        bail_literal()
+            .unwrap_err()
+            .downcast_mut::<MietteDiagnostic>()
+            .unwrap()
+            .message,
     );
     assert_eq!(
         "oh no!",
-        bail_fmt().unwrap_err().downcast_mut::<String>().unwrap(),
+        bail_fmt()
+            .unwrap_err()
+            .downcast_mut::<MietteDiagnostic>()
+            .unwrap()
+            .message,
     );
     assert_eq!(
         "oh no!",

tests/test_fmt.rs

@@ -80,7 +80,6 @@ fn test_altdisplay() {
 
 #[test]
 #[ignore = "not really gonna work with the current printers"]
-#[cfg_attr(track_caller, ignore)]
 fn test_debug() {
     assert_eq!(EXPECTED_DEBUG_F, format!("{:?}", f().unwrap_err()));
     assert_eq!(EXPECTED_DEBUG_G, format!("{:?}", g().unwrap_err()));

tests/test_json.rs

@@ -20,7 +20,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
         }
@@ -52,7 +52,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -66,7 +65,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
         }
@@ -98,7 +97,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -112,7 +110,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
         }
@@ -144,7 +142,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -158,7 +155,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
         }
@@ -190,7 +187,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -204,7 +200,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label]
             highlight: SourceSpan,
         }
@@ -235,7 +231,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -249,7 +244,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
         }
@@ -281,7 +276,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -295,7 +289,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label = "x"]
             highlight1: SourceSpan,
             #[label = "y"]
@@ -347,7 +341,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -361,7 +354,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label = "these two lines"]
             highlight: SourceSpan,
         }
@@ -393,7 +386,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -407,7 +399,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label = "block 1"]
             highlight1: SourceSpan,
             #[label = "block 2"]
@@ -456,7 +448,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -472,7 +463,7 @@ mod json_report_handler {
             #[source]
             source: Inner,
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label = "block 1"]
             highlight1: SourceSpan,
             #[label]
@@ -532,7 +523,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -546,7 +536,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label = "this bit here"]
             highlight1: SourceSpan,
             #[label = "also this bit"]
@@ -588,7 +578,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -602,7 +591,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label = "this bit here"]
             highlight1: SourceSpan,
             #[label = "also this bit"]
@@ -644,7 +633,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -658,7 +646,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label = "this bit here"]
             highlight1: SourceSpan,
             #[label = "also this bit"]
@@ -700,7 +688,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -728,7 +715,6 @@ mod json_report_handler {
             "related": []
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -742,7 +728,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
             #[related]
@@ -822,7 +808,6 @@ mod json_report_handler {
             }]
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);
@@ -836,7 +821,7 @@ mod json_report_handler {
         #[diagnostic(code(oops::my::bad), help("try doing it better next time?"))]
         struct MyBad {
             #[source_code]
-            src: NamedSource,
+            src: NamedSource<String>,
             #[label("this bit here")]
             highlight: SourceSpan,
             #[related]
@@ -920,7 +905,6 @@ mod json_report_handler {
             }]
         }"#
         .lines()
-        .into_iter()
         .map(|s| s.trim_matches(|c| c == ' ' || c == '\n'))
         .collect();
         assert_eq!(expected, out);

tests/test_repr.rs

@@ -2,7 +2,6 @@ mod drop;
 
 use self::drop::{DetectDrop, Flag};
 use miette::Report;
-use std::marker::Unpin;
 use std::mem;
 
 #[test]