title: &'s str,

source: &'s str,

validate_config: impl FnMut(&C) -> anyhow::Result<()>,

) -> anyhow::Result<MarkdownTestSuite<'s, C>>

C: Clone + Default + for<'de> Deserialize<'de>,

let parser = Parser::new(title, source, validate_config);

parser.parse()

/// Header sections.

sections: IndexVec<SectionId, Section<'s, C>>,

/// Test files embedded within the Markdown file.

files: IndexVec<EmbeddedFileId, EmbeddedFile<'s>>,

pub(crate) fn tests(&self) -> MarkdownTestIterator<'_, 's, C> {

MarkdownTestIterator {

suite: self,

current_file_index: 0,

}

}

type Hash = SipHasher128Hash;

fn from(SipHasher128Hash(hash): SipHasher128Hash) -> Hash128 {

Hash128(hash)

}

fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {

let Self(hash) = self;

// Only write the first half for concision

write!(f, "{:x}", hash[0])

}

suite: &'m MarkdownTestSuite<'s, C>,

section: &'m Section<'s, C>,

files: &'m [EmbeddedFile<'s>],

const MAX_TITLE_LENGTH: usize = 20;

const ELLIPSIS: char = '\u{2026}';

fn contracted_title(title: &str) -> String {

if title.len() <= Self::MAX_TITLE_LENGTH {

return (*title).to_string();

}

format!(

"{}{}",

title

.chars()

.take(Self::MAX_TITLE_LENGTH)

.collect::<String>(),

Self::ELLIPSIS

)

}

fn joined_name(&self, contracted: bool) -> String {

let mut name_fragments = vec![];

let mut parent_id = self.section.parent_id;

while let Some(next_id) = parent_id {

let parent = &self.suite.sections[next_id];

name_fragments.insert(0, parent.title);

parent_id = parent.parent_id;

}

name_fragments.push(self.section.title);

let full_name = name_fragments.join(" - ");

if !contracted {

return full_name;

}

let mut contracted_name = name_fragments

.iter()

.map(|fragment| Self::contracted_title(fragment))

.collect::<Vec<_>>()

.join(" - ");

let mut hasher = StableSipHasher128::new();

full_name.hash(&mut hasher);

let _ = write!(contracted_name, " ({:x})", hasher.finish::<Hash128>());

contracted_name

}

pub(crate) fn uncontracted_name(&self) -> String {

self.joined_name(false)

}

pub(crate) fn name(&self) -> String {

self.joined_name(true)

}

pub fn files(&self) -> impl Iterator<Item = &'m EmbeddedFile<'s>> {

self.files.iter()

}

pub fn configuration(&self) -> &C {

&self.section.config

}

pub(crate) fn should_snapshot_diagnostics(&self) -> bool {

self.section

.directives

.has_directive_set(MdtestDirective::SnapshotDiagnostics)

}

#[expect(clippy::result_unit_err)]

pub fn should_expect_panic(&self) -> Result<Option<&str>, ()> {

self.section.directives.get(MdtestDirective::ExpectPanic)

}

pub fn should_skip_pulling_types(&self) -> bool {

self.section

.directives

.has_directive_set(MdtestDirective::PullTypesSkip)

}

type Item = MarkdownTest<'m, 's, C>;

fn next(&mut self) -> Option<Self::Item> {

let mut current_file_index = self.current_file_index;

let mut file = self.suite.files.get(current_file_index.into());

let section_id = file?.section;

while file.is_some_and(|file| file.section == section_id) {

current_file_index += 1;

file = self.suite.files.get(current_file_index.into());

}

let files = &self.suite.files[EmbeddedFileId::from_usize(self.current_file_index)

..EmbeddedFileId::from_usize(current_file_index)];

self.current_file_index = current_file_index;

Some(MarkdownTest {

suite: self.suite,

section: &self.suite.sections[section_id],

files,

})

}

title: &'s str,

level: u8,

parent_id: Option<SectionId>,

config: C,

directives: MdtestDirectives,

fn range(&self) -> TextRange {

self.0

}

/// The expected snapshot content.

pub(crate) expected: &'s str,

/// The range of the inline snapshot block, including both fences.

pub(crate) range: BacktickOffsets,

fn range(&self) -> TextRange {

self.range.0

}

pub(crate) fn new(

md_index: &LineIndex,

dimensions: impl IntoIterator<Item = BacktickOffsets>,

) -> EmbeddedFileSourceMap {

EmbeddedFileSourceMap {

start_line_and_line_count: dimensions

.into_iter()

.map(|d| {

let start_line = md_index.line_index(d.start()).get();

let end_line = md_index.line_index(d.end()).get();

let code_line_count = (end_line - start_line) - 1;

(start_line, code_line_count)

})

.collect(),

}

}

/// Returns the absolute line number in the markdown file for a given line number

/// relative to the concatenated code blocks.

///

/// Returns an `Err` if the relative line number is out of bounds where

/// the returned value is the absolute line number of the last code block.

///

/// # Panics

/// If called when the markdown file has no code blocks.

pub(crate) fn to_absolute_line_number(

&self,

relative_line_number: OneIndexed,

) -> std::result::Result<OneIndexed, OneIndexed> {

let mut relative_line_number = relative_line_number.get();

for (start_line, line_count) in &self.start_line_and_line_count {

if relative_line_number > *line_count {

relative_line_number -= *line_count;

} else {

let absolute_line_number = start_line + relative_line_number;

return Ok(OneIndexed::new(absolute_line_number)

.expect("absolute line number must be >= 1"));

}

}

let last_line_number = self

.start_line_and_line_count

.last()

.and_then(|(start_line, line_count)| OneIndexed::new(start_line + line_count));

Err(last_line_number.expect("markdown file to have at least one code block"))

}

fn as_str(&self) -> &str {

match self {

EmbeddedFilePath::Autogenerated(PySourceType::Python) => "mdtest_snippet.py",

EmbeddedFilePath::Autogenerated(PySourceType::Stub) => "mdtest_snippet.pyi",

EmbeddedFilePath::Autogenerated(PySourceType::Ipynb) => "mdtest_snippet.ipynb",

EmbeddedFilePath::Explicit(path) => path,

}

}

fn is_explicit(&self) -> bool {

matches!(self, EmbeddedFilePath::Explicit(_))

}

fn is_allowed_explicit_path(path: &str) -> bool {

[

PySourceType::Python,

PySourceType::Stub,

PySourceType::Ipynb,

]

.iter()

.all(|source_type| path != EmbeddedFilePath::Autogenerated(*source_type).as_str())

}

section: SectionId,

path: EmbeddedFilePath<'s>,

pub lang: &'s str,

pub code: Cow<'s, str>,

/// The checkable code blocks

pub code_blocks: Vec<CodeBlock<'s>>,

fn append_code(&mut self, backtick_offsets: BacktickOffsets, new_code: &str) {

// Treat empty code blocks as non-existent, instead of creating

// an additional empty line:

if new_code.is_empty() {

return;

}

let existing_code = self.code.to_mut();

existing_code.push('\n');

let start_offset = existing_code.text_len();

existing_code.push_str(new_code);

self.code_blocks.push(CodeBlock {

backticks: backtick_offsets,

embedded_start_offset: start_offset,

inline_snapshot_block: None,

});

}

pub(crate) fn relative_path(&self) -> &str {

self.path.as_str()

}

/// Returns the full path using unix file-path convention.

pub fn full_path(&self, project_root: &SystemPath) -> SystemPathBuf {

// Don't use `SystemPath::absolute` here because it's platform dependent

// and we want to use unix file-path convention.

let relative_path = self.relative_path();

if relative_path.starts_with('/') {

SystemPathBuf::from(relative_path)

} else {

project_root.join(relative_path)

}

}

fn is_checkable(&self) -> bool {

matches!(self.lang, "py" | "python" | "pyi" | "ipynb" | "toml")

}

/// The offsets of the code block's code fences in the markdown source.

backticks: BacktickOffsets,

/// The offset in the concatenated file source at which this code block starts.

embedded_start_offset: TextSize,

/// The code block's associated inline snapshot block (capture the expected rendered diagnostics output).

inline_snapshot_block: Option<InlineSnapshotBlock<'s>>,

pub(crate) fn backtick_offsets(&self) -> BacktickOffsets {

self.backticks

}

pub(crate) fn embedded_start_offset(&self) -> TextSize {

self.embedded_start_offset

}

pub(crate) fn inline_snapshot_block(&self) -> Option<&InlineSnapshotBlock<'s>> {

self.inline_snapshot_block.as_ref()

}

fn new(root_section_id: SectionId) -> Self {

Self(vec![root_section_id])

}

fn push(&mut self, section_id: SectionId) {

self.0.push(section_id);

}

fn pop(&mut self) -> Option<SectionId> {

let popped = self.0.pop();

debug_assert_ne!(popped, None, "Should never pop the implicit root section");

debug_assert!(

!self.0.is_empty(),

"Should never pop the implicit root section"

);

popped

}

fn top(&mut self) -> SectionId {

*self

.0

.last()

.expect("Should never pop the implicit root section")

}

/// [`Section`]s of the final [`MarkdownTestSuite`].

sections: IndexVec<SectionId, Section<'s, C>>,

/// [`EmbeddedFile`]s of the final [`MarkdownTestSuite`].

files: IndexVec<EmbeddedFileId, EmbeddedFile<'s>>,

/// The unparsed remainder of the Markdown source.

cursor: Cursor<'s>,

// Number of consecutive empty lines.

preceding_blank_lines: usize,

// Explicitly specified path for the upcoming code block.

explicit_path: Option<&'s str>,

source: &'s str,

/// Stack of ancestor sections.

stack: SectionStack,

/// Names of embedded files in current active section.

current_section_files: IndexMap<EmbeddedFilePath<'s>, EmbeddedFileId, FxBuildHasher>,

/// Whether or not the current section has a config block.

current_section_has_config: bool,

/// Callback to validate config blocks

validate_config: F,

C: Clone + Default + for<'de> Deserialize<'de>,

F: FnMut(&C) -> anyhow::Result<()>,

fn new(title: &'s str, source: &'s str, validate_config: F) -> Self {

let mut sections = IndexVec::default();

let root_section_id = sections.push(Section {

title,

level: 0,

parent_id: None,

config: C::default(),

directives: MdtestDirectives::default(),

});

Self {

sections,

source,

files: IndexVec::default(),

cursor: Cursor::new(source),

preceding_blank_lines: 0,

explicit_path: None,

stack: SectionStack::new(root_section_id),

current_section_files: IndexMap::default(),

current_section_has_config: false,

validate_config,

}

}

fn parse(mut self) -> anyhow::Result<MarkdownTestSuite<'s, C>> {

self.parse_impl()?;

Ok(self.finish())

}

fn finish(mut self) -> MarkdownTestSuite<'s, C> {

self.sections.shrink_to_fit();

self.files.shrink_to_fit();

MarkdownTestSuite {

sections: self.sections,

files: self.files,

}

}

fn skip_non_newline_whitespace(&mut self) {

self.cursor.eat_while(|c| c.is_whitespace() && c != '\n');

}

fn skip_to_beginning_of_next_line(&mut self) -> bool {

if let Some(position) = memchr::memchr(b'\n', self.cursor.as_bytes()) {

self.cursor.skip_bytes(position + 1);

true

} else {

false

}

}

fn consume_until(&mut self, mut end_predicate: impl FnMut(char) -> bool) -> Option<&'s str> {

let start = self.cursor.offset().to_usize();

while !self.cursor.is_eof() {

if end_predicate(self.cursor.first()) {

return Some(&self.source[start..self.cursor.offset().to_usize()]);

}

self.cursor.bump();

}

None

}

fn parse_impl(&mut self) -> anyhow::Result<()> {

const SECTION_CONFIG_SNAPSHOT: &str = "snapshot-diagnostics";

const SECTION_CONFIG_PULLTYPES: &str = "pull-types:skip";

const SECTION_CONFIG_EXPECT_PANIC: &str = "expect-panic";

const HTML_COMMENT_ALLOWLIST: &[&str] = &["fmt:on", "fmt:off"];

const CODE_BLOCK_END: &[u8] = b"```";

const HTML_COMMENT_END: &[u8] = b"-->";

while let Some(first) = self.cursor.bump() {

match first {

'<' if self.cursor.eat_char3('!', '-', '-') => {

if let Some(position) =

memchr::memmem::find(self.cursor.as_bytes(), HTML_COMMENT_END)

{

let html_comment = self.cursor.as_str()[..position].trim();

let (directive, value) = match html_comment.split_once(':') {

Some((directive, value)) => {

(directive.trim(), Some(value.trim().to_string()))

}

None => (html_comment, None),

};

match directive {

SECTION_CONFIG_SNAPSHOT => {

anyhow::ensure!(

value.is_none(),

"The `{SECTION_CONFIG_SNAPSHOT}` directive \

);

self.process_mdtest_directive(

MdtestDirective::SnapshotDiagnostics,

None,

)?;

}

SECTION_CONFIG_PULLTYPES => {

anyhow::ensure!(

value.is_none(),

"The `{SECTION_CONFIG_PULLTYPES}` directive \

);

self.process_mdtest_directive(

MdtestDirective::PullTypesSkip,

None,

)?;

}

SECTION_CONFIG_EXPECT_PANIC => {

self.process_mdtest_directive(MdtestDirective::ExpectPanic, value)?;

}

_ => {

if !HTML_COMMENT_ALLOWLIST.contains(&html_comment) {

bail!(

"Unknown HTML comment `{html_comment}` -- \

);

}

}

}

self.cursor.skip_bytes(position + HTML_COMMENT_END.len());

} else {

bail!("Unterminated HTML comment.");

}

}

'#' => {

self.explicit_path = None;

self.preceding_blank_lines = 0;

// Determine header level (number of '#' characters)

let mut header_level = 1;

while self.cursor.eat_char('#') {

header_level += 1;

}

// Parse header title

if let Some(title) = self.consume_until(|c| c == '\n') {

let title = title.trim();

if !title.is_empty() {

self.process_header(header_level, title)?;

}

}

}

'`' => {

if self.cursor.eat_char2('`', '`') {

// We saw the triple-backtick beginning of a code block.

let backtick_offset_start = self.cursor.offset() - "```".text_len();

if self.preceding_blank_lines < 1 && self.explicit_path.is_none() {

bail!(

"Code blocks must start on a new line \

);

}

self.skip_non_newline_whitespace();

// Parse the code block language specifier

let lang = self

.consume_until(|c| matches!(c, ' ' | '\n'))

.unwrap_or_default();

self.skip_non_newline_whitespace();

let metadata = self.consume_until(|c| c == '\n').unwrap_or_default().trim();

if !self.cursor.eat_char('\n') {

bail!(

"Trailing code-block metadata is not supported. \

);

}

let ignore = if metadata.is_empty() {

false

} else if let Some(attributes) = metadata

.strip_prefix('{')

.and_then(|metadata| metadata.strip_suffix('}'))

{

attributes

.split_ascii_whitespace()

.any(|attribute| attribute == r#"data-mdtest="ignore""#)

} else {

bail!(

"Trailing code-block metadata must use the `{{...}}` \

);

};

if let Some(position) =

memchr::memmem::find(self.cursor.as_bytes(), CODE_BLOCK_END)

{

let mut code = &self.cursor.as_str()[..position];

self.cursor.skip_bytes(position + CODE_BLOCK_END.len());

if code.ends_with('\n') {

code = &code[..code.len() - '\n'.len_utf8()];

}

let backtick_offset_end = self.cursor.offset();

self.process_code_block(

lang,

code,

ignore,

BacktickOffsets(TextRange::new(

backtick_offset_start,

backtick_offset_end,

)),

)?;

} else {

let code_block_start = self.cursor.token_len();

let line = self.source.count_lines(TextRange::up_to(code_block_start));

bail!("Unterminated code block on line {line}.");

}

self.explicit_path = None;

} else if self.preceding_blank_lines > 0 {

// This could be a line that specifies an explicit path for a Markdown code block (`module.py`:)

self.explicit_path = None;

if let Some(path) = self.consume_until(|c| matches!(c, '`' | '\n')) {

if self.cursor.eat_char('`') {

self.skip_non_newline_whitespace();

if self.cursor.eat_char(':') {

self.explicit_path = Some(path);

}

}

}

}

self.preceding_blank_lines = 0;

}

'\n' => {

self.preceding_blank_lines += 1;

continue;

}

c => {

self.preceding_blank_lines = 0;

self.explicit_path = None;

if c.is_whitespace() {

self.skip_non_newline_whitespace();

if self.cursor.eat_char('`')

&& self.cursor.eat_char('`')

&& self.cursor.eat_char('`')

{

bail!("Indented code blocks are not supported.");

}

}

}

}

if !self.skip_to_beginning_of_next_line() {

break;

}

}

Ok(())

}

fn process_header(&mut self, header_level: usize, title: &'s str) -> anyhow::Result<()> {

self.pop_sections_to_level(header_level);

let parent = self.stack.top();

let section = Section {

title,

level: header_level.try_into()?,

parent_id: Some(parent),

config: self.sections[parent].config.clone(),

directives: self.sections[parent].directives.clone(),

};

if !self.current_section_files.is_empty() {

bail!(

"Header '{}' not valid inside a test case; parent '{}' has code files.",

section.title,

self.sections[parent].title,

);

}

let section_id = self.sections.push(section);

self.stack.push(section_id);

self.current_section_files.clear();

self.current_section_has_config = false;

Ok(())

}

fn process_code_block(

&mut self,

lang: &'s str,

code: &'s str,

ignore: bool,

backtick_offsets: BacktickOffsets,

) -> anyhow::Result<()> {

// We never pop the implicit root section.

let section = self.stack.top();

let test_name = self.sections[section].title;

if ignore {

return Ok(());

}

if lang == "toml" && self.explicit_path.is_none() {

return self.process_config_block(code);

}

if matches!(lang, "ignore" | "pycon") {

return Ok(());

}

if lang == "snapshot" {

return self.process_inline_snapshot(code, backtick_offsets);

}

if let Some(explicit_path) = self.explicit_path {

let expected_extension = if lang == "python" { "py" } else { lang };

if !expected_extension.is_empty()

&& lang != "text"

&& !SystemPath::new(explicit_path)

.extension()

.is_none_or(|extension| extension.eq_ignore_ascii_case(expected_extension))

{

let backtick_start = self.line_number(backtick_offsets.start());

bail!(

"File extension of test file path `{explicit_path}` \

);

}

}

let path = match self.explicit_path {

Some(path) => {

if !EmbeddedFilePath::is_allowed_explicit_path(path) {

bail!(

"The file name `{path}` in test `{test_name}` must not be used explicitly.",

);

}

EmbeddedFilePath::Explicit(path)

}

None => match lang {

"py" | "python" => EmbeddedFilePath::Autogenerated(PySourceType::Python),

"pyi" => EmbeddedFilePath::Autogenerated(PySourceType::Stub),

"ipynb" => EmbeddedFilePath::Autogenerated(PySourceType::Ipynb),

"" => {

bail!(

"Cannot auto-generate file name for code block \

);

}

_ => {

bail!(

"Cannot auto-generate file name for code block \

);

}

},

};

let has_merged_snippets = self.current_section_has_merged_snippets();

let has_explicit_file_paths = self.current_section_has_explicit_file_paths();

match self.current_section_files.entry(path.clone()) {

Entry::Vacant(entry) => {

if has_merged_snippets {