Refactor test utilities to improve names

9 files changed, 221 insertions, 157 deletions

diff --git a/tests/test_utils/hast.rs b/tests/test_utils/hast.rs
index db5326c..bc8f472 100644
--- a/tests/test_utils/hast.rs
+++ b/tests/test_utils/hast.rs
@@ -1,6 +1,9 @@
-#![allow(dead_code)]
+//! HTML syntax tree: [hast][].
+//!
+//! [hast]: https://github.com/syntax-tree/hast
 
-// ^-- To do: fix later
+#![allow(dead_code)]
+// ^-- To do: externalize.
 
 extern crate alloc;
 extern crate micromark;
diff --git a/tests/test_utils/to_swc.rs b/tests/test_utils/hast_util_to_swc.rs
index 02de514..a4bb9b9 100644
--- a/tests/test_utils/to_swc.rs
+++ b/tests/test_utils/hast_util_to_swc.rs
@@ -1,10 +1,37 @@
+//! Turn an HTML AST into a JavaScript AST.
+//!
+//! Port of <https://github.com/syntax-tree/hast-util-to-estree>, by the same
+//! author:
+//!
+//! (The MIT License)
+//!
+//! Copyright (c) 2016 Titus Wormer <tituswormer@gmail.com>
+//!
+//! Permission is hereby granted, free of charge, to any person obtaining
+//! a copy of this software and associated documentation files (the
+//! 'Software'), to deal in the Software without restriction, including
+//! without limitation the rights to use, copy, modify, merge, publish,
+//! distribute, sublicense, and/or sell copies of the Software, and to
+//! permit persons to whom the Software is furnished to do so, subject to
+//! the following conditions:
+//!
+//! The above copyright notice and this permission notice shall be
+//! included in all copies or substantial portions of the Software.
+//!
+//! THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+//! EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+//! MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+//! IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+//! CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+//! TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+//! SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
 extern crate swc_common;
 extern crate swc_ecma_ast;
 use crate::test_utils::{
     hast,
-    micromark_swc_utils::position_to_span,
     swc::{parse_esm_to_tree, parse_expression_to_tree},
-    swc_utils::create_ident,
+    swc_utils::{create_ident, position_to_span},
 };
 use core::str;
 use micromark::{Location, MdxExpressionKind};
@@ -41,7 +68,7 @@ struct Context<'a> {
 }
 
 #[allow(dead_code)]
-pub fn to_swc(
+pub fn hast_util_to_swc(
     tree: &hast::Node,
     path: Option<String>,
     location: Option<&Location>,
diff --git a/tests/test_utils/to_hast.rs b/tests/test_utils/mdast_util_to_hast.rs
index 1ba8d35..c07d15b 100644
--- a/tests/test_utils/to_hast.rs
+++ b/tests/test_utils/mdast_util_to_hast.rs
@@ -1,3 +1,31 @@
+//! Turn a markdown AST into an HTML AST.
+//!
+//! Port of <https://github.com/syntax-tree/mdast-util-to-hast>, by the same
+//! author:
+//!
+//! (The MIT License)
+//!
+//! Copyright (c) 2016 Titus Wormer <tituswormer@gmail.com>
+//!
+//! Permission is hereby granted, free of charge, to any person obtaining
+//! a copy of this software and associated documentation files (the
+//! 'Software'), to deal in the Software without restriction, including
+//! without limitation the rights to use, copy, modify, merge, publish,
+//! distribute, sublicense, and/or sell copies of the Software, and to
+//! permit persons to whom the Software is furnished to do so, subject to
+//! the following conditions:
+//!
+//! The above copyright notice and this permission notice shall be
+//! included in all copies or substantial portions of the Software.
+//!
+//! THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+//! EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+//! MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+//! IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+//! CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+//! TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+//! SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
 use crate::test_utils::hast;
 use micromark::{mdast, sanitize, unist::Position};
 
@@ -34,7 +62,7 @@ enum Result {
 }
 
 #[allow(dead_code)]
-pub fn to_hast(mdast: &mdast::Node) -> hast::Node {
+pub fn mdast_util_to_hast(mdast: &mdast::Node) -> hast::Node {
     let mut definitions = vec![];
 
     // Collect definitions.
diff --git a/tests/test_utils/to_document.rs b/tests/test_utils/mdx_plugin_recma_document.rs
index 938df1b..a62862c 100644
--- a/tests/test_utils/to_document.rs
+++ b/tests/test_utils/mdx_plugin_recma_document.rs
@@ -1,7 +1,12 @@
+//! Turn a JavaScript AST, coming from MD(X), into a component.
+//!
+//! Port of <https://github.com/mdx-js/mdx/blob/main/packages/mdx/lib/plugin/recma-document.js>,
+//! by the same author.
+
 extern crate swc_ecma_ast;
 use crate::test_utils::{
-    micromark_swc_utils::{bytepos_to_point, prefix_error_with_point, span_to_position},
-    to_swc::Program,
+    hast_util_to_swc::Program,
+    swc_utils::{bytepos_to_point, prefix_error_with_point, span_to_position},
 };
 use micromark::{
     unist::{Point, Position},
@@ -66,7 +71,7 @@ impl Default for Options {
 }
 
 #[allow(dead_code)]
-pub fn to_document(
+pub fn mdx_plugin_recma_document(
     mut program: Program,
     options: &Options,
     location: Option<&Location>,
diff --git a/tests/test_utils/jsx_rewrite.rs b/tests/test_utils/mdx_plugin_recma_jsx_rewrite.rs
index 33879b0..6a4d451 100644
--- a/tests/test_utils/jsx_rewrite.rs
+++ b/tests/test_utils/mdx_plugin_recma_jsx_rewrite.rs
@@ -1,11 +1,16 @@
+//! Rewrite JSX tags to accept them from props and an optional provider.
+//!
+//! Port of <https://github.com/mdx-js/mdx/blob/main/packages/mdx/lib/plugin/recma-jsx-rewrite.js>,
+//! by the same author.
+
 extern crate swc_common;
 extern crate swc_ecma_ast;
 use crate::test_utils::{
-    micromark_swc_utils::{position_to_string, span_to_position},
+    hast_util_to_swc::Program,
     swc_utils::{
         create_binary_expression, create_ident, create_ident_expression, create_member_expression,
+        position_to_string, span_to_position,
     },
-    to_swc::Program,
 };
 use micromark::{id_cont, id_start, unist::Position, Location};
 use swc_ecma_visit::{noop_visit_mut_type, VisitMut, VisitMutWith};
@@ -25,7 +30,7 @@ pub struct Options {
 
 /// Rewrite JSX in an MDX file so that components can be passed in and provided.
 #[allow(dead_code)]
-pub fn jsx_rewrite(
+pub fn mdx_plugin_recma_jsx_rewrite(
     mut program: Program,
     options: &Options,
     location: Option<&Location>,
diff --git a/tests/test_utils/micromark_swc_utils.rs b/tests/test_utils/micromark_swc_utils.rs
deleted file mode 100644
index 13678d5..0000000
--- a/tests/test_utils/micromark_swc_utils.rs
+++ /dev/null
@@ -1,134 +0,0 @@
-extern crate swc_common;
-use micromark::{
-    mdast::Stop,
-    unist::{Point, Position},
-    Location,
-};
-use swc_common::{BytePos, Span, SyntaxContext, DUMMY_SP};
-use swc_ecma_visit::{noop_visit_mut_type, VisitMut};
-
-/// Turn a unist position, into an SWC span, of two byte positions.
-///
-/// > 👉 **Note**: SWC byte positions are offset by one: they are `0` when they
-/// > are missing or incremented by `1` when valid.
-pub fn position_to_span(position: Option<&Position>) -> Span {
-    position.map_or(DUMMY_SP, |d| Span {
-        lo: point_to_bytepos(&d.start),
-        hi: point_to_bytepos(&d.end),
-        ctxt: SyntaxContext::empty(),
-    })
-}
-
-/// Turn an SWC span, of two byte positions, into a unist position.
-///
-/// This assumes the span comes from a fixed tree, or is a dummy.
-///
-/// > 👉 **Note**: SWC byte positions are offset by one: they are `0` when they
-/// > are missing or incremented by `1` when valid.
-pub fn span_to_position(span: &Span, location: Option<&Location>) -> Option<Position> {
-    let lo = span.lo.0 as usize;
-    let hi = span.hi.0 as usize;
-
-    if lo > 0 && hi > 0 {
-        if let Some(location) = location {
-            if let Some(start) = location.to_point(lo - 1) {
-                if let Some(end) = location.to_point(hi - 1) {
-                    return Some(Position { start, end });
-                }
-            }
-        }
-    }
-
-    None
-}
-
-/// Turn a unist point into an SWC byte position.
-///
-/// > 👉 **Note**: SWC byte positions are offset by one: they are `0` when they
-/// > are missing or incremented by `1` when valid.
-pub fn point_to_bytepos(point: &Point) -> BytePos {
-    BytePos(point.offset as u32 + 1)
-}
-
-/// Turn an SWC byte position into a unist point.
-///
-/// This assumes the byte position comes from a fixed tree, or is a dummy.
-///
-/// > 👉 **Note**: SWC byte positions are offset by one: they are `0` when they
-/// > are missing or incremented by `1` when valid.
-pub fn bytepos_to_point(bytepos: &BytePos, location: Option<&Location>) -> Option<Point> {
-    let pos = bytepos.0 as usize;
-
-    if pos > 0 {
-        if let Some(location) = location {
-            return location.to_point(pos - 1);
-        }
-    }
-
-    None
-}
-
-/// Prefix an error message with an optional point.
-pub fn prefix_error_with_point(reason: String, point: Option<&Point>) -> String {
-    if let Some(point) = point {
-        format!("{}: {}", point_to_string(point), reason)
-    } else {
-        reason
-    }
-}
-
-/// Serialize a unist position for humans.
-pub fn position_to_string(position: &Position) -> String {
-    format!(
-        "{}-{}",
-        point_to_string(&position.start),
-        point_to_string(&position.end)
-    )
-}
-
-/// Serialize a unist point for humans.
-pub fn point_to_string(point: &Point) -> String {
-    format!("{}:{}", point.line, point.column)
-}
-
-/// Visitor to fix SWC byte positions.
-///
-/// This assumes the byte position comes from an **unfixed** tree.
-///
-/// > 👉 **Note**: SWC byte positions are offset by one: they are `0` when they
-/// > are missing or incremented by `1` when valid.
-#[derive(Debug, Default, Clone)]
-pub struct RewriteContext<'a> {
-    pub prefix_len: usize,
-    pub stops: &'a [Stop],
-    pub location: Option<&'a Location>,
-}
-
-impl<'a> VisitMut for RewriteContext<'a> {
-    noop_visit_mut_type!();
-
-    // Rewrite spans.
-    fn visit_mut_span(&mut self, span: &mut Span) {
-        let mut result = DUMMY_SP;
-        let lo_rel = span.lo.0 as usize;
-        let hi_rel = span.hi.0 as usize;
-
-        if lo_rel > self.prefix_len && hi_rel > self.prefix_len {
-            if let Some(lo_abs) =
-                Location::relative_to_absolute(self.stops, lo_rel - 1 - self.prefix_len)
-            {
-                if let Some(hi_abs) =
-                    Location::relative_to_absolute(self.stops, hi_rel - 1 - self.prefix_len)
-                {
-                    result = Span {
-                        lo: BytePos(lo_abs as u32 + 1),
-                        hi: BytePos(hi_abs as u32 + 1),
-                        ctxt: SyntaxContext::empty(),
-                    };
-                }
-            }
-        }
-
-        *span = result;
-    }
-}
diff --git a/tests/test_utils/mod.rs b/tests/test_utils/mod.rs
index 99ded2f..8d1f144 100644
--- a/tests/test_utils/mod.rs
+++ b/tests/test_utils/mod.rs
@@ -1,8 +1,7 @@
 pub mod hast;
-pub mod jsx_rewrite;
-pub mod micromark_swc_utils;
+pub mod hast_util_to_swc;
+pub mod mdast_util_to_hast;
+pub mod mdx_plugin_recma_document;
+pub mod mdx_plugin_recma_jsx_rewrite;
 pub mod swc;
 pub mod swc_utils;
-pub mod to_document;
-pub mod to_hast;
-pub mod to_swc;
diff --git a/tests/test_utils/swc.rs b/tests/test_utils/swc.rs
index 7e44898..3c97d28 100644
--- a/tests/test_utils/swc.rs
+++ b/tests/test_utils/swc.rs
@@ -1,10 +1,9 @@
+//! Bridge between `micromark` and SWC.
 extern crate micromark;
 extern crate swc_common;
 extern crate swc_ecma_ast;
 extern crate swc_ecma_parser;
-use crate::test_utils::micromark_swc_utils::{
-    bytepos_to_point, prefix_error_with_point, RewriteContext,
-};
+use crate::test_utils::swc_utils::{bytepos_to_point, prefix_error_with_point, RewriteContext};
 use micromark::{mdast::Stop, unist::Point, Location, MdxExpressionKind, MdxSignal};
 use swc_common::{
     source_map::Pos, sync::Lrc, BytePos, FileName, FilePathMapping, SourceFile, SourceMap, Spanned,
diff --git a/tests/test_utils/swc_utils.rs b/tests/test_utils/swc_utils.rs
index 1e1a526..5a45af6 100644
--- a/tests/test_utils/swc_utils.rs
+++ b/tests/test_utils/swc_utils.rs
@@ -1,8 +1,140 @@
-extern crate swc_common;
-extern crate swc_ecma_ast;
+//! Lots of helpers for dealing with SWC, particularly from unist.
 
-use swc_common::DUMMY_SP;
+use micromark::{
+    mdast::Stop,
+    unist::{Point, Position},
+    Location,
+};
+
+use swc_common::{BytePos, Span, SyntaxContext, DUMMY_SP};
 use swc_ecma_ast::{BinExpr, BinaryOp, Expr, Ident, MemberExpr, MemberProp};
+use swc_ecma_visit::{noop_visit_mut_type, VisitMut};
+
+/// Turn a unist position, into an SWC span, of two byte positions.
+///
+/// > 👉 **Note**: SWC byte positions are offset by one: they are `0` when they
+/// > are missing or incremented by `1` when valid.
+pub fn position_to_span(position: Option<&Position>) -> Span {
+    position.map_or(DUMMY_SP, |d| Span {
+        lo: point_to_bytepos(&d.start),
+        hi: point_to_bytepos(&d.end),
+        ctxt: SyntaxContext::empty(),
+    })
+}
+
+/// Turn an SWC span, of two byte positions, into a unist position.
+///
+/// This assumes the span comes from a fixed tree, or is a dummy.
+///
+/// > 👉 **Note**: SWC byte positions are offset by one: they are `0` when they
+/// > are missing or incremented by `1` when valid.
+pub fn span_to_position(span: &Span, location: Option<&Location>) -> Option<Position> {
+    let lo = span.lo.0 as usize;
+    let hi = span.hi.0 as usize;
+
+    if lo > 0 && hi > 0 {
+        if let Some(location) = location {
+            if let Some(start) = location.to_point(lo - 1) {
+                if let Some(end) = location.to_point(hi - 1) {
+                    return Some(Position { start, end });
+                }
+            }
+        }
+    }
+
+    None
+}
+
+/// Turn a unist point into an SWC byte position.
+///
+/// > 👉 **Note**: SWC byte positions are offset by one: they are `0` when they
+/// > are missing or incremented by `1` when valid.
+pub fn point_to_bytepos(point: &Point) -> BytePos {
+    BytePos(point.offset as u32 + 1)
+}
+
+/// Turn an SWC byte position into a unist point.
+///
+/// This assumes the byte position comes from a fixed tree, or is a dummy.
+///
+/// > 👉 **Note**: SWC byte positions are offset by one: they are `0` when they
+/// > are missing or incremented by `1` when valid.
+pub fn bytepos_to_point(bytepos: &BytePos, location: Option<&Location>) -> Option<Point> {
+    let pos = bytepos.0 as usize;
+
+    if pos > 0 {
+        if let Some(location) = location {
+            return location.to_point(pos - 1);
+        }
+    }
+
+    None
+}
+
+/// Prefix an error message with an optional point.
+pub fn prefix_error_with_point(reason: String, point: Option<&Point>) -> String {
+    if let Some(point) = point {
+        format!("{}: {}", point_to_string(point), reason)
+    } else {
+        reason
+    }
+}
+
+/// Serialize a unist position for humans.
+pub fn position_to_string(position: &Position) -> String {
+    format!(
+        "{}-{}",
+        point_to_string(&position.start),
+        point_to_string(&position.end)
+    )
+}
+
+/// Serialize a unist point for humans.
+pub fn point_to_string(point: &Point) -> String {
+    format!("{}:{}", point.line, point.column)
+}
+
+/// Visitor to fix SWC byte positions.
+///
+/// This assumes the byte position comes from an **unfixed** tree.
+///
+/// > 👉 **Note**: SWC byte positions are offset by one: they are `0` when they
+/// > are missing or incremented by `1` when valid.
+#[derive(Debug, Default, Clone)]
+pub struct RewriteContext<'a> {
+    pub prefix_len: usize,
+    pub stops: &'a [Stop],
+    pub location: Option<&'a Location>,
+}
+
+impl<'a> VisitMut for RewriteContext<'a> {
+    noop_visit_mut_type!();
+
+    // Rewrite spans.
+    fn visit_mut_span(&mut self, span: &mut Span) {
+        let mut result = DUMMY_SP;
+        let lo_rel = span.lo.0 as usize;
+        let hi_rel = span.hi.0 as usize;
+
+        if lo_rel > self.prefix_len && hi_rel > self.prefix_len {
+            if let Some(lo_abs) =
+                Location::relative_to_absolute(self.stops, lo_rel - 1 - self.prefix_len)
+            {
+                if let Some(hi_abs) =
+                    Location::relative_to_absolute(self.stops, hi_rel - 1 - self.prefix_len)
+                {
+                    result = Span {
+                        lo: BytePos(lo_abs as u32 + 1),
+                        hi: BytePos(hi_abs as u32 + 1),
+                        ctxt: SyntaxContext::empty(),
+                    };
+                }
+            }
+        }
+
+        *span = result;
+    }
+}
 
 /// Generate an ident.
 ///