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, 50 insertions, 0 deletions

diff --git a/subplot.md b/subplot.md
index cae70f6..269343b 100644
--- a/subplot.md
+++ b/subplot.md
@@ -1095,6 +1095,56 @@ bindings:
 ~~~
 ~~~~~~
 
+## Named code blocks must have an appropriate class
+
+_Requirement: Named code blocks must carry an appropriate class such as file or example_
+
+Justification: Eventually we may want to add other meanings to named blocks,
+currently the identifier cannot be used except to refer to the block as a named file,
+but we may want to in the future so this is here to try and prevent any future
+incompatibilities.
+
+~~~scenario
+given file named-code-blocks-appropriate.subplot
+given file named-code-blocks-appropriate.md
+given file b.yaml
+given an installed subplot
+when I try to run subplot docgen named-code-blocks-appropriate.subplot -o foo.html
+then command fails
+and stderr contains "#example-1 at named-code-blocks-appropriate.md:7:1"
+and stderr doesn't contain "example-2"
+and stderr doesn't contain "example-3"
+~~~
+
+~~~{#named-code-blocks-appropriate.subplot .file .yaml .numberLines}
+title: Named code blocks carry appropriate classes step
+markdowns:
+  - named-code-blocks-appropriate.md
+bindings:
+  - b.yaml
+~~~
+
+~~~~~~{#named-code-blocks-appropriate.md .file .markdown .numberLines}
+# This is a title
+
+~~~scenario
+given precondition
+~~~
+
+~~~{#example-1 .numberLines}
+This example is bad
+~~~
+
+~~~{#example-2 .file .numberLines}
+This example is OK because of .file
+~~~
+
+~~~{#example-3 .example .numberLines}
+This example is OK because of .example
+~~~
+
+~~~~~~
+
 ## No scenarios means codegen fails
 
 If you attempt to `subplot codegen` on a document which contains no scenarios, the