future-proof enums

Add variants and attributes to future-proof enums. My guiding principles
were:

1. enums that reflect markdown should be exhaustive, since we can assume
  a fairly stable markdown spec
2. enums that reflect mdq-specific inputs or non-markdown outputs
  (specifically, errors) should be non-exhaustive, so that mdq can add new
  features without breaking the API

Resolves #377. See that ticket for an analysis of the enums currently in
the code base.

## Breaking changes

- add `FrontMatterVariant::Json` variant
- change `FrontMatterVariant::separator()`'s signature to reflect that
Json doesn't have a separator line.
- add various `#[non_exhaustive]` attributes

Author: yshavit

src/md_elem/tree.rs

@@ -493,8 +493,40 @@ pub mod elem {
 
     #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
     pub enum FrontMatterVariant {
+        /// ```markdown
+        /// +++
+        /// front = 'matter'
+        /// +++
+        /// ```
         Toml,
+
+        /// ```markdown
+        /// ---
+        /// front: matter
+        /// ---
+        /// ```
         Yaml,
+
+        /// ```markdown
+        /// {
+        ///   "front": "matter"
+        /// }
+        /// ```
+        ///
+        /// The [`FrontMatter::body`] for a `FrontMatter` of this variant will be the entire JSON text, including the
+        /// opening and closing braces. This means you should not print any surrounding prefix or suffix delimiter
+        /// lines when rendering front matter of this variant, unlike the other variants. The body will _not_ include
+        /// a trailing newline after the last closing brace.
+        ///
+        /// <div class="warning">
+        ///
+        /// mdq does not currently support parsing JSON front matter. This enum variant is provided for completeness
+        /// and future-proofing. API consumers should still account for it (and may create [`MdElem::FrontMatter`] nodes
+        /// with it); just be aware that [`MdDoc::parse`] will not produce any front matter nodes with this variant
+        /// as of this version.
+        ///
+        /// </div>
+        Json,
     }
 
     impl FrontMatterVariant {
@@ -510,21 +542,26 @@ pub mod elem {
             match self {
                 FrontMatterVariant::Toml => "toml",
                 FrontMatterVariant::Yaml => "yaml",
+                FrontMatterVariant::Json => "json",
             }
         }
 
-        /// Gets the separator that's used in front matter syntax to specify this variant.
+        /// Gets the separator used in front matter syntax to specify this variant.
+        ///
+        /// JSON has no such separator; see [`FrontMatterVariant::Json`].
         ///
         /// ```
         /// use mdq::md_elem::elem::FrontMatterVariant;
         ///
-        /// assert_eq!(FrontMatterVariant::Toml.separator(), "+++");
-        /// assert_eq!(FrontMatterVariant::Yaml.separator(), "---");
+        /// assert_eq!(FrontMatterVariant::Toml.separator(), Some("+++"));
+        /// assert_eq!(FrontMatterVariant::Yaml.separator(), Some("---"));
+        /// assert_eq!(FrontMatterVariant::Json.separator(), None);
         /// ```
-        pub fn separator(self) -> &'static str {
+        pub fn separator(self) -> Option<&'static str> {
             match self {
-                FrontMatterVariant::Toml => "+++",
-                FrontMatterVariant::Yaml => "---",
+                FrontMatterVariant::Toml => Some("+++"),
+                FrontMatterVariant::Yaml => Some("---"),
+                FrontMatterVariant::Json => None,
             }
         }
     }
@@ -860,7 +897,7 @@ pub mod elem {
         pub item: Vec<MdElem>,
     }
 
-    /// ~~deleted~~, _emphasized_, or **strong**; see [`Span`]
+    /// ~~deleted (strikethrough)~~, _emphasized_, or **strong**; see [`Span`]
     #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
     pub enum SpanVariant {
         Delete,

src/output/fmt_md.rs

@@ -55,6 +55,7 @@ pub struct MdWriterOptions {
 
 /// Whether to put link definitions at the end of each section, or at the bottom of the whole document.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Default, ValueEnum)]
+#[non_exhaustive]
 pub enum ReferencePlacement {
     /// Show link definitions in the first section that uses the link.
     ///
@@ -402,11 +403,15 @@ impl<'md> MdWriterState<'_, 'md> {
 
     fn write_front_matter<W: SimpleWrite>(&mut self, out: &mut Output<W>, front_matter: &'md FrontMatter) {
         out.with_pre_block(|out| {
-            out.write_str(front_matter.variant.separator());
-            out.write_char('\n');
+            if let Some(sep) = front_matter.variant.separator() {
+                out.write_str(sep);
+                out.write_char('\n');
+            }
             out.write_str(&front_matter.body);
-            out.write_char('\n');
-            out.write_str(front_matter.variant.separator());
+            if let Some(sep) = front_matter.variant.separator() {
+                out.write_char('\n');
+                out.write_str(sep);
+            }
         })
     }
 
@@ -582,6 +587,7 @@ pub(crate) mod tests {
         CodeBlock(CodeBlock{variant: CodeVariant::Math{metadata: Some(_)}, ..}),
         FrontMatter(FrontMatter{variant: FrontMatterVariant::Toml, ..}),
         FrontMatter(FrontMatter{variant: FrontMatterVariant::Yaml, ..}),
+        FrontMatter(FrontMatter{variant: FrontMatterVariant::Json, ..}),
         Paragraph(_),
         BlockQuote(_),
         List(_),
@@ -1394,6 +1400,20 @@ pub(crate) mod tests {
                 +++"#},
             );
         }
+
+        #[test]
+        fn json() {
+            check_render(
+                md_elems![FrontMatter {
+                    variant: FrontMatterVariant::Json,
+                    body: "{\n  'one': 'two'\n}".replace('\'', "\"").to_string(),
+                }],
+                indoc! {r#"
+                {
+                  "one": "two"
+                }"#},
+            );
+        }
     }
 
     mod inline {

src/output/link_transform.rs

@@ -10,6 +10,7 @@ use std::ops::Deref;
 
 /// Whether to render links as inline, reference form, or keep them as they were.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Default, ValueEnum)]
+#[non_exhaustive]
 pub enum LinkTransform {
     /// Keep links as they were in the original
     Keep,

src/output/tree_ref_serde.rs

@@ -212,16 +212,10 @@ impl<'md> SerdeElem<'md> {
                     language,
                 }
             }
-            MdElem::FrontMatter(fm) => {
-                let variant = match fm.variant {
-                    FrontMatterVariant::Yaml => "yaml",
-                    FrontMatterVariant::Toml => "toml",
-                };
-                Self::FrontMatter {
-                    variant,
-                    body: &fm.body,
-                }
-            }
+            MdElem::FrontMatter(fm) => Self::FrontMatter {
+                variant: fm.variant.name(),
+                body: &fm.body,
+            },
             MdElem::Inline(Inline::Link(link)) => match link {
                 crate::md_elem::elem::Link::Standard(standard_link) => Self::Link {
                     display: inlines_to_string(&standard_link.display, inlines_writer),

src/run/cli.rs

@@ -240,6 +240,7 @@ impl CliOptions {
 
 /// Output formats, analogous to `--output` in the CLI.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, ValueEnum)]
+#[non_exhaustive]
 pub enum OutputFormat {
     /// Output results as Markdown.
     Markdown,

src/run/run_main.rs

@@ -12,6 +12,7 @@ use std::io::Write;
 
 /// The run's overall possible error.
 #[derive(Debug)]
+#[non_exhaustive]
 pub enum Error {
     /// User provided an invalid selector string.
     ///