[diskann-benchmark] Add type reflection to enable documentation of benchmark inputs.

Cargo.toml

@@ -27,6 +27,7 @@ members = [
     "diskann-record",
     "diskann-tools",
     "diskann-bftree",
+    "diskann-macros",
 ]
 
 default-members = [
@@ -66,6 +67,7 @@ diskann-inmem = { path = "diskann-inmem", default-features = false, version = "0
 diskann-disk = { path = "diskann-disk", version = "0.60.0" }
 diskann-label-filter = { path = "diskann-label-filter", version = "0.60.0" }
 # Infra
+diskann-macros = { path = "diskann-macros", version = "0.60.0" }
 diskann-benchmark-runner = { path = "diskann-benchmark-runner", version = "0.60.0" }
 diskann-benchmark-core = { path = "diskann-benchmark-core", version = "0.60.0" }
 diskann-tools = { path = "diskann-tools", version = "0.60.0" }

diskann-benchmark-runner/Cargo.toml

@@ -10,7 +10,9 @@ edition = "2024"
 [dependencies]
 anyhow = { workspace = true }
 clap = { workspace = true, features = ["derive"] }
+diskann-macros = { workspace = true }
 half = { workspace = true }
+hashbrown = { workspace = true }
 indicatif = "0.18.3"
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
@@ -25,6 +27,7 @@ expect_used = "warn"
 panic = "warn"
 
 [dev-dependencies]
+diskann-utils = { workspace = true, default-features = false, features = ["testing"] }
 tempfile.workspace = true
 
 [features]

diskann-benchmark-runner/dev/main.rs

@@ -25,7 +25,13 @@ fn main() -> anyhow::Result<()> {
 #[derive(Debug, clap::Parser)]
 struct Cli {
     /// Emulate enabling various features for feature gated functionality.
-    #[arg(long, value_delimiter = ',', num_args = 0..)]
+    ///
+    /// Currently available features:
+    /// * `gated-feature-0`
+    /// * `gated-feature-1`
+    /// * `gated-feature-2`
+    /// * `gated-feature-3`
+    #[arg(long, value_delimiter = ',', num_args = 1)]
     features: Vec<String>,
 
     /// The actual application.

diskann-benchmark-runner/src/app.rs

@@ -121,6 +121,11 @@ pub enum Commands {
     },
     #[command(subcommand)]
     Check(Check),
+    /// Provide information about all registered types.
+    TypeInfo {
+        /// Provide information for the given type.
+        describe: Option<String>,
+    },
 }
 
 /// Subcommands for regression check operations.
@@ -207,12 +212,28 @@ impl App {
                 if let Some(describe) = describe {
                     if let Some(input) = registry.input(describe) {
                         let repr = jobs::Unprocessed::format_input(input)?;
+
+                        // Render JSON.
                         writeln!(
                             output,
-                            "The example JSON representation for \"{}\" is:",
+                            "The example JSON representation for \"{}\" is:\n",
                             describe
                         )?;
                         writeln!(output, "{}", serde_json::to_string_pretty(&repr)?)?;
+
+                        // Render Type Info.
+                        match input.raw_reflection() {
+                            Some(reflection) => {
+                                writeln!(output, "\nType Information:\n\n{}", reflection.render())?;
+
+                                writeln!(
+                                    output,
+                                    "More type information available using `type-info`"
+                                )?;
+                            }
+                            None => writeln!(output, "\n\nNo Type Information Available")?,
+                        }
+
                         return Ok(());
                     } else {
                         writeln!(output, "No input found for \"{}\"", describe)?;
@@ -386,6 +407,11 @@ impl App {
             }
             // Extensions
             Commands::Check(check) => return self.check(check, registry, output),
+
+            // Types
+            Commands::TypeInfo { describe } => {
+                self.type_info(describe.as_deref(), registry, output)?
+            }
         };
         Ok(())
     }
@@ -482,6 +508,29 @@ impl App {
             }
         }
     }
+
+    fn type_info(
+        &self,
+        describe: Option<&str>,
+        registry: &registry::Registry,
+        mut output: &mut dyn Output,
+    ) -> anyhow::Result<()> {
+        match describe {
+            Some(type_name) => match registry.type_info(type_name) {
+                Some(reflection) => writeln!(output, "{}", reflection.render())?,
+                None => anyhow::bail!("No type information for \"{}\"", type_name),
+            },
+            None => {
+                let mut all_types: Vec<_> = registry.type_names().collect();
+                all_types.sort_unstable();
+                writeln!(output, "All registered types:")?;
+                for type_name in all_types {
+                    writeln!(output, "  {}", type_name)?;
+                }
+            }
+        }
+        Ok(())
+    }
 }
 
 ///////////
@@ -541,8 +590,6 @@ mod tests {
 
     use crate::{registry, test::TestConfig, ux};
 
-    const ENV: &str = "DISKANN_TEST";
-
     // Expected I/O files.
     const STDIN: &str = "stdin.txt";
     const STDOUT: &str = "stdout.txt";
@@ -560,42 +607,6 @@ mod tests {
 
     const ALL_GENERATED_OUTPUTS: [&str; 2] = [OUTPUT_FILE, CHECK_OUTPUT_FILE];
 
-    // Read the entire contents of a file to a string.
-    fn read_to_string<P: AsRef<Path>>(path: P, ctx: &str) -> String {
-        match std::fs::read_to_string(path.as_ref()) {
-            Ok(s) => ux::normalize(s),
-            Err(err) => panic!(
-                "failed to read {} {:?} with error: {}",
-                ctx,
-                path.as_ref(),
-                err
-            ),
-        }
-    }
-
-    // Check if `DISKANN_TEST=overwrite` is configured. Return `true` if so - otherwise
-    // return `false`.
-    //
-    // If `DISKANN_TEST` is set but its value is not `overwrite` - panic.
-    fn overwrite() -> bool {
-        match std::env::var(ENV) {
-            Ok(v) => {
-                if v == "overwrite" {
-                    true
-                } else {
-                    panic!(
-                        "Unknown value for {}: \"{}\". Expected \"overwrite\"",
-                        ENV, v
-                    );
-                }
-            }
-            Err(std::env::VarError::NotPresent) => false,
-            Err(std::env::VarError::NotUnicode(_)) => {
-                panic!("Value for {} is not unicode", ENV);
-            }
-        }
-    }
-
     // Test Runner
     struct Test {
         dir: PathBuf,
@@ -606,15 +617,15 @@ mod tests {
         fn new(dir: &Path) -> Self {
             Self {
                 dir: dir.into(),
-                overwrite: overwrite(),
+                overwrite: ux::test::overwrite(),
             }
         }
 
         fn parse_stdin(&self, tempdir: &Path) -> Vec<App> {
             let path = self.dir.join(STDIN);
 
             // Read the standard input file to a string.
-            let stdin = read_to_string(&path, "standard input");
+            let stdin = ux::test::read_to_string(&path, "standard input");
 
             let output: Vec<App> = stdin
                 .lines()
@@ -723,7 +734,7 @@ mod tests {
             if self.overwrite {
                 std::fs::write(output, stdout).unwrap();
             } else {
-                let expected = read_to_string(&output, "expected standard output");
+                let expected = ux::test::read_to_string(&output, "expected standard output");
                 if stdout != expected {
                     panic!("Got:\n--\n{}\n--\nExpected:\n--\n{}\n--", stdout, expected);
                 }
@@ -765,9 +776,9 @@ mod tests {
             } else {
                 match (was_generated, is_expected) {
                     (true, true) => {
-                        let output_contents = read_to_string(generated_path, "generated");
+                        let output_contents = ux::test::read_to_string(generated_path, "generated");
 
-                        let expected_contents = read_to_string(expected_path, "expected");
+                        let expected_contents = ux::test::read_to_string(expected_path, "expected");
 
                         if output_contents != expected_contents {
                             panic!(
@@ -777,7 +788,7 @@ mod tests {
                         }
                     }
                     (true, false) => {
-                        let output_contents = read_to_string(generated_path, "generated");
+                        let output_contents = ux::test::read_to_string(generated_path, "generated");
 
                         panic!(
                             "{} was generated when none was expected. Contents:\n\n{}",

diskann-benchmark-runner/src/files.rs

@@ -7,7 +7,7 @@ use std::path::{Path, PathBuf};
 
 use serde::{Deserialize, Serialize};
 
-use super::Checker;
+use crate::{Checker, Reflect};
 
 /// A file that is used as an input to for a benchmark.
 ///
@@ -27,6 +27,16 @@ pub struct InputFile {
     path: PathBuf,
 }
 
+impl Reflect for InputFile {
+    fn ty() -> crate::reflect::Type {
+        <PathBuf as Reflect>::ty()
+    }
+
+    fn format_type_name(f: &mut dyn std::fmt::Write) -> std::fmt::Result {
+        f.write_str("benchmark::InputFile")
+    }
+}
+
 impl InputFile {
     /// Create a new input file from the path-like `path`.
     pub fn new<P>(path: P) -> Self

diskann-benchmark-runner/src/input.rs

@@ -3,7 +3,7 @@
  * Licensed under the MIT license.
  */
 
-use crate::Checker;
+use crate::{Checker, Reflect};
 
 /// Inputs to [`Benchmarks`](crate::Benchmark).
 ///
@@ -16,7 +16,7 @@ pub trait Input: Sized + std::fmt::Debug + 'static {
     /// [`Deserialize`](serde::Deserialize) implementation.
     ///
     /// Final object validation is performed via [`from_raw`](Self::from_raw).
-    type Raw: serde::de::DeserializeOwned + serde::Serialize;
+    type Raw: serde::de::DeserializeOwned + serde::Serialize + Reflect;
 
     /// Return the discriminant associated with this type.
     ///
@@ -39,7 +39,7 @@ pub trait Input: Sized + std::fmt::Debug + 'static {
 }
 
 pub(crate) mod internal {
-    use crate::{Checker, Features, internal::visibility::Visibility};
+    use crate::{Checker, Features, Reflection, internal::visibility::Visibility};
 
     /// Runtime representation of a deserialized [`Input`].
     #[derive(Debug)]
@@ -145,6 +145,10 @@ pub(crate) mod internal {
             self.0.visibility()
         }
 
+        pub(crate) fn raw_reflection(&self) -> Option<Reflection> {
+            self.0.raw_reflection()
+        }
+
         pub(crate) fn as_any(&self) -> &dyn std::any::Any {
             self.0.as_any()
         }
@@ -221,6 +225,7 @@ pub(crate) mod internal {
         fn visibility(&self) -> Visibility<'_>;
 
         // reflection
+        fn raw_reflection(&self) -> Option<Reflection>;
         fn as_any(&self) -> &dyn std::any::Any;
         fn type_name(&self) -> &'static str;
     }
@@ -261,6 +266,9 @@ pub(crate) mod internal {
         fn visibility(&self) -> Visibility<'_> {
             Visibility::Available
         }
+        fn raw_reflection(&self) -> Option<Reflection> {
+            Some(Reflection::new::<T::Raw>())
+        }
         fn as_any(&self) -> &dyn std::any::Any {
             self
         }
@@ -305,6 +313,9 @@ pub(crate) mod internal {
                 features: &self.features,
             }
         }
+        fn raw_reflection(&self) -> Option<Reflection> {
+            None
+        }
         fn as_any(&self) -> &dyn std::any::Any {
             self
         }

diskann-benchmark-runner/src/internal/mod.rs

@@ -6,6 +6,7 @@
 use anyhow::Context;
 
 pub(crate) mod regression;
+pub(crate) mod typemap;
 pub(crate) mod visibility;
 
 /// Attempt to load and deserialize from a JSON file on disk identified with `path`.