chore: Get rid of common::instrament, inline into main crate

common/src/lib.rs

@@ -1,3 +1 @@
 #![allow(clippy::cargo_common_metadata)]
-
-pub mod instrament;

core/src/lib.rs

@@ -20,6 +20,12 @@ pub use crate::stages::Stage;
 use log::{debug, info};
 use std::io::{BufRead, Error, Write};
 
+/// Internal macros. Have to live here to be usable in unit, not just integration
+/// (`./tests`) tests. Do not [move from
+/// here](https://stackoverflow.com/questions/26731243/how-do-i-use-a-macro-across-module-files#comment115383139_63234531)
+#[macro_use]
+pub mod macros;
+
 /// Main components around [`Stage`]s and their [processing][Stage::substitute].
 pub mod stages;
 

common/src/instrament.rs → core/src/macros.rs

@@ -1,3 +1,9 @@
+/// Sanitize a string for use as a filename.
+///
+/// A 'best effort' in replacing characters illegal in filenames with a stand-in
+/// [`char`]. For Unix, it's easy, for Windows, it's a bit of guessing. Use with
+/// caution.
+#[must_use]
 pub fn sanitize_for_filename_use(filename: &str) -> String {
     const REPLACEMENT: char = '_';
     filename
@@ -14,6 +20,22 @@ pub fn sanitize_for_filename_use(filename: &str) -> String {
         .join(&REPLACEMENT.to_string())
 }
 
+/// This macro allows `rstest` (test case parametrization) and `insta` (snapshot
+/// testing) to coexist.
+///
+/// The gist is that it generates a whole new `struct` from a function signature.
+/// Implementing [`std::fmt::Display`] for it, the struct can be used to represent a
+/// test case automatically: whatever was passed into the test function by `rstest` and
+/// its `case`s will form the `struct` fields, which form the name. As a result, all
+/// tests get unique, easily identified names.
+///
+/// One caveat is that a closure is now required to run a test case. Quite ugly. In
+/// general, **do not use this macro** if you can avoid it. Consider this macro as
+/// potentially breaking at any point. When using *either* `rstest` *or* `insta`, this
+/// macro is not needed.
+///
+/// For context, see [this
+/// issue](https://github.com/la10736/rstest/issues/183#issuecomment-1564021215).
 #[macro_export]
 macro_rules! instrament {
     ($(#[$attr:meta])* fn $name:ident ( $( $(#[$arg_attr:meta])* $arg:ident : $type:ty),* ) $body:expr ) => {
@@ -32,7 +54,7 @@ macro_rules! instrament {
                         )*
                     ];
 
-                    let name = $crate::instrament::sanitize_for_filename_use(&items.join("-"));
+                    let name = $crate::macros::sanitize_for_filename_use(&items.join("-"));
                     write!(f, "{}", name)
                 }
             }

core/src/stages/german/driver.rs

@@ -472,7 +472,6 @@ fn is_valid(word: &str, predicate: &impl Fn(&str) -> bool) -> bool {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use common::instrament;
     use rstest::rstest;
 
     #[test]

core/src/stages/german/words.rs

@@ -206,7 +206,6 @@ impl Replace for String {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use common::instrament;
     use rstest::rstest;
     use serde::Serialize;