feat: Warn when named codeblocks lack classes

To both improve debugability when writing scenarios, and also
to protect against future incompatibilities which might occur
if we add more classes which are appropriate for named code
blocks, we require that named blocks have one of `file` or `example`
as classes or else we warn.

Signed-off-by: Daniel Silverstone <dsilvers@digital-scurf.org>

1 files changed, 37 insertions, 1 deletions

diff --git a/src/doc.rs b/src/doc.rs
index fe263ad..e218020 100644
--- a/src/doc.rs
+++ b/src/doc.rs
@@ -38,6 +38,10 @@ static KNOWN_FILE_CLASSES: &[&str] = &["rust", "yaml", "python", "sh", "shell",
 /// which we use to invert the default numberLines on .file blocks.
 static KNOWN_BLOCK_CLASSES: &[&str] = &["numberLines", "noNumberLines"];
 
+/// The set of classes which subplot will recognise as being appropriate
+/// for having IDs.
+static ID_OK_CLASSES: &[&str] = &["file", "example"];
+
 /// A parsed Subplot document.
 ///
 /// # Example
@@ -340,6 +344,37 @@ impl Document {
         set
     }
 
+    /// Check labelled code blocks have some appropriate class
+    pub fn check_named_code_blocks_have_appropriate_class(
+        &self,
+        warnings: &mut Warnings,
+    ) -> Result<bool, SubplotError> {
+        let mut okay = true;
+        for md in self.markdowns.iter() {
+            for block in md.named_blocks() {
+                if !block.all_attrs().iter().any(|attr| {
+                    attr.name() == "class"
+                        && ID_OK_CLASSES
+                            .iter()
+                            .any(|class| attr.value() == Some(class))
+                }) {
+                    // For now, named blocks must be files
+                    warnings.push(Warning::MissingAppropriateClassOnNamedCodeBlock(
+                        block
+                            .attr("id")
+                            .expect("Named blocks should have IDs")
+                            .value()
+                            .unwrap_or("(unknown-id)")
+                            .to_string(),
+                        block.location().to_string(),
+                    ));
+                    okay = false;
+                }
+            }
+        }
+        Ok(okay)
+    }
+
     /// Check that all named files (in matched steps) are actually present in the
     /// document.
     pub fn check_named_files_exist(
@@ -563,7 +598,8 @@ pub fn codegen(
         return Err(SubplotError::TemplateSupportNotPresent);
     }
     let mut warnings = Warnings::default();
-    if !doc.check_named_files_exist(&template, &mut warnings)?
+    if !doc.check_named_code_blocks_have_appropriate_class(&mut warnings)?
+        || !doc.check_named_files_exist(&template, &mut warnings)?
         || !doc.check_matched_steps_have_impl(&template, &mut warnings)
         || !doc.check_embedded_files_are_used(&template, &mut warnings)?
     {