Renderer contracts
Identities and blocks
An identity names one location in the book. IDs begin with an ASCII letter or digit and otherwise contain ASCII letters, digits, dots, underscores, or hyphens. Structured unit IDs and legacy defining roles share one global namespace. Malformed IDs, duplicate definitions, and unresolved references fail rendering. Forward references and references between nested chapter directories work.
definitionmeta.syntax.anchors.roles
Legacy {anchor} and {definition} roles define locations; {anchor-ref}
links to them. A neutral anchor inherits the surrounding definition, theorem,
or lemma label. A role’s label does not establish correspondence or a proof.
definitionmeta.syntax.anchors.inline A defining role stays in its paragraph. Put it immediately before the text to show the shield inline with that text.
definitionmeta.syntax.anchors.rendering Definitions become local HTML shields. References become ref shields linking to the defining chapter and fragment. Shields require no external badge service.
definitionmeta.syntax.anchors.literal Roles inside fenced or indented code, links, or HTML blocks remain literal. Escaped role prefixes and double-backtick demonstrations also remain literal. These are the supported custom roles, not a general MyST parser.
#![allow(unused)]
fn main() {
fn roles(source: &str) -> Result<Vec<Role>> {
let id_pattern = Regex::new(r"^[A-Za-z0-9][A-Za-z0-9_.-]*$")?;
let mut found = vec![];
let mut text_end = None;
let mut excluded = 0;
for (event, range) in Parser::new(source).into_offset_iter() {
match event {
Event::Start(
Tag::CodeBlock(_) | Tag::Link { .. } | Tag::Image { .. } | Tag::HtmlBlock,
) => {
excluded += 1;
text_end = None;
}
Event::End(TagEnd::CodeBlock | TagEnd::Link | TagEnd::Image | TagEnd::HtmlBlock) => {
excluded -= 1;
text_end = None;
}
Event::Text(_) if excluded == 0 => text_end = Some(range),
Event::Code(id) if excluded == 0 => {
if let Some(previous) = text_end.take() {
let removed = "{obligation}";
if previous.end == range.start
&& source[previous.clone()].ends_with(removed)
&& !source[..range.start - removed.len()].ends_with('\\')
&& source[range.clone()] == format!("`{id}`")
{
bail!("{{obligation}} has been removed; use a named definition, theorem, lemma, or example with :status: draft when formalization is pending");
}
for (prefix, definition, label, lean) in [
("{anchor}", true, None, false),
("{definition}", true, Some("definition"), false),
("{anchor-ref}", false, None, false),
("{lean.type}", false, None, true),
] {
if previous.end != range.start
|| !source[previous.clone()].ends_with(prefix)
{
continue;
}
let start = range.start - prefix.len();
if source[..start].ends_with('\\') {
continue;
}
// Double-backtick spans are literal demonstrations, not roles.
if source[range.clone()] != format!("`{id}`") {
continue;
}
ensure!(lean || id_pattern.is_match(&id), "invalid anchor ID `{id}`");
found.push(Role {
range: start..range.end,
id: id.into_string(),
definition,
label,
lean,
});
break;
}
}
}
_ => text_end = None,
}
}
Ok(found)
}
}
#![allow(unused)]
fn main() {
fn chapter_roles(source: &str) -> Result<Vec<Role>> {
let protected = protect_math(source);
let mut found = roles(&protected)?;
for unit in units::parse(source, "chapter")? {
found.push(Role {
range: unit.range,
id: unit.id,
definition: true,
label: None,
lean: false,
});
}
for block in directive_blocks(&protected) {
if block
.info
.split_whitespace()
.next()
.is_some_and(|name| MarkdownDirective::parse(name).is_some() || name == "{future-note}")
{
// These bodies are Markdown; grammar, judgment, and rule bodies are TeX.
ensure!(
!directive_blocks(&block.body).iter().any(|nested| {
["{definition}", "{example}", "{theorem}", "{lemma}", "{future-note}"]
.iter()
.any(|name| nested.info.starts_with(name))
}),
"definition, example, theorem, and lemma directives cannot be nested within one another"
);
found.extend(roles(&protect_math(&block.body))?);
}
}
Ok(found)
}
}
#![allow(unused)]
fn main() {
fn process_with_roots(
book: &mut Value,
lean_root: Option<&Path>,
project_root: Option<&Path>,
) -> Result<()> {
let key = if book.get("items").is_some_and(Value::is_array) {
"items"
} else if book.get("sections").is_some_and(Value::is_array) {
"sections"
} else {
bail!("unsupported mdBook input: expected an items or sections array");
};
let mut anchors = BTreeMap::new();
walk(&book[key], &mut |chapter| {
let source = chapter["content"]
.as_str()
.context("chapter has no content")?;
let path = chapter["path"].as_str().context("chapter has no path")?;
lint::check_latex(source, path)?;
for role in chapter_roles(source).with_context(|| path.to_owned())? {
if role.definition {
if let Some(previous) = anchors.insert(role.id.clone(), path.to_owned()) {
bail!("duplicate anchor `{}` in {previous} and {path}", role.id);
}
}
}
Ok(())
})?;
fn update(
items: &mut Value,
anchors: &BTreeMap<String, String>,
lean_root: Option<&Path>,
project_root: Option<&Path>,
) -> Result<()> {
if let Some(items) = items.as_array_mut() {
for item in items {
if let Some(chapter) = item.get_mut("Chapter") {
let path = chapter["path"].as_str().context("chapter has no path")?;
let source = chapter["content"]
.as_str()
.context("chapter has no content")?;
let content = render(
source,
path,
anchors,
lean_root,
project_root,
path,
"anchor",
)
.with_context(|| format!("chapter {path}"))?;
chapter["content"] = Value::String(content);
update(&mut chapter["sub_items"], anchors, lean_root, project_root)?;
}
}
}
Ok(())
}
update(&mut book[key], &anchors, lean_root, project_root)
}
}
#![allow(unused)]
fn main() {
fn relative_html(from: &str, to: &str) -> Result<String> {
// mdBook chapter paths are relative to the source directory.
let parts = |s: &str| -> Result<Vec<String>> {
Path::new(s)
.components()
.map(|c| match c {
std::path::Component::Normal(p) => Ok(p.to_string_lossy().into_owned()),
_ => bail!("chapter path must be relative and normalized: {s}"),
})
.collect()
};
let mut from = parts(from)?;
from.pop();
let mut to = parts(to)?;
let file = to.last_mut().context("empty chapter path")?;
*file = Path::new(file)
.with_extension("html")
.to_string_lossy()
.into_owned();
let common = from.iter().zip(&to).take_while(|(a, b)| a == b).count();
let path = std::iter::repeat_n("..".to_owned(), from.len() - common)
.chain(to[common..].iter().cloned())
.collect::<Vec<_>>()
.join("/");
Ok(path
.replace('%', "%25")
.replace(' ', "%20")
.replace('#', "%23")
.replace('?', "%3F"))
}
}
#![allow(unused)]
fn main() {
fn render_role(
role: &Role,
path: &str,
anchors: &BTreeMap<String, String>,
definition_label: &str,
) -> Result<String> {
ensure!(
!role.lean,
"lean.type has been replaced: use ```{{grammar}} path:Name with authored LaTeX in the body"
);
let target = anchors
.get(&role.id)
.with_context(|| format!("unknown anchor `{}`", role.id))?;
let fragment = format!("claim-{}", role.id);
let href = if target == path {
format!("#{fragment}")
} else {
format!("{}#{fragment}", relative_html(path, target)?)
};
let id_attr = if role.definition {
format!(" id=\"{fragment}\"")
} else {
String::new()
};
let label = if role.definition {
role.label.unwrap_or(definition_label)
} else {
"ref"
};
Ok(format!(
"<a{id_attr} class=\"spec-shield\" href=\"{}\" aria-label=\"{label}: {}\"><span class=\"spec-shield-label\">{label}</span><span class=\"spec-shield-name\">{}</span></a>",
escape(&href), escape(&role.id), escape(&role.id)
))
}
}
#![allow(unused)]
fn main() {
#[test]
fn indexes_forward_references_and_nested_chapters() {
let mut book = json!({"sections":[chapter("intro.md","See {anchor-ref}`model.live`."),
{"Chapter":{"path":"model/index.md","content":"{anchor}`model.live`\nLive objects.","sub_items":[chapter("model/details.md","See {anchor-ref}`model.live`.")]}}]});
process(&mut book).unwrap();
assert!(book["sections"][0]["Chapter"]["content"]
.as_str()
.unwrap()
.contains("model/index.html#claim-model.live"));
assert!(
book["sections"][1]["Chapter"]["sub_items"][0]["Chapter"]["content"]
.as_str()
.unwrap()
.contains("index.html#claim-model.live")
);
}
}
#![allow(unused)]
fn main() {
#[test]
fn cross_references_traverse_to_parent_and_bad_references_fail() {
let mut book = json!({"sections":[chapter("index.md","{anchor}`top`"),chapter("a/b.md","{anchor-ref}`top`")]});
process(&mut book).unwrap();
assert!(book.to_string().contains("../index.html#claim-top"));
for entries in [
vec![chapter("a.md", "{anchor-ref}`missing`")],
vec![
chapter("a.md", "{anchor}`x`"),
chapter("b.md", "{anchor}`x`"),
],
vec![chapter("a.md", "{anchor}`bad id`")],
] {
assert!(process(&mut json!({"sections":entries})).is_err());
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn literal_examples_are_not_anchors() {
let source="```text\n{anchor}`literal`\n```\n\n {anchor}`indented`\n\n`{anchor}`literal\n\n\\{anchor}`escaped`\n\n<!-- {anchor}`comment` -->\n\n[{anchor}`linked`](https://example.com)\n";
let mut book = json!({"sections":[chapter("a.md",source)]});
process(&mut book).unwrap();
assert_eq!(book["sections"][0]["Chapter"]["content"], source);
}
}
#![allow(unused)]
fn main() {
#[test]
fn typed_anchor_roles_share_ids_and_references_without_implying_proofs() {
let mut book = json!({"items": [
chapter("index.md", "{anchor}`navigation` See {anchor-ref}`state` and {anchor-ref}`slots`."),
chapter("model/state.md", "{definition}`state` State components.\n\n{definition}`slots` Slots hold references."),
]});
process(&mut book).unwrap();
let intro = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(intro.contains("aria-label=\"anchor: navigation\""));
assert!(intro.contains("model/state.html#claim-state"));
assert!(intro.contains("model/state.html#claim-slots"));
let body = book["items"][1]["Chapter"]["content"].as_str().unwrap();
assert!(body.contains("aria-label=\"definition: state\""));
assert!(body.contains("aria-label=\"definition: slots\""));
assert!(!body.contains("lean-selector"));
assert!(!body.contains("Theorem"));
for first in ["anchor", "definition"] {
for second in ["anchor", "definition"] {
let mut duplicate = json!({"items": [
chapter("a.md", &format!("{{{first}}}`same`")),
chapter("b.md", &format!("{{{second}}}`same`")),
]});
assert!(
format!("{:#}", process(&mut duplicate).unwrap_err()).contains("duplicate anchor")
);
}
}
let literal = "```text\n{definition}`duplicate`\n{obligation}`duplicate`\n```\n\n{definition}``double``\n\n\\{obligation}`escaped`";
let mut book = json!({"items": [chapter("literal.md", literal)]});
process(&mut book).unwrap();
assert_eq!(book["items"][0]["Chapter"]["content"], literal);
}
}
Inline roles label or refer to locations. Fenced directives create blocks:
{definition}, {grammar}, {judgment}, {rule}, {theorem}, {lemma},
{example}, and {heap}. Ordinary language fences such as lean, heap,
grammar, and text remain literal code.
A structured block starts with its kind and stable ID, followed by options and an authored body.
definitionmeta.syntax.draft
:status: draft marks unfinished formalization without
changing the kind. It permits omitted citations; supplied citations keep their
kind checks. A draft without citations has no source selector.
The former {lean.type}, {lean.judgment}, {lean.rule}, and {obligation}
forms are rejected with migration diagnostics. An {example} paragraph prefix
is also rejected: examples use fenced blocks.
definitionmeta.syntax.informational
A paragraph starting with {informational} and a space receives an inline
Informational label. Its remaining text keeps normal Markdown formatting.
The marker creates no identity and remains literal in code samples.
#![allow(unused)]
fn main() {
fn parse_block(
source: &str,
path: &str,
range: Range<usize>,
info: &str,
) -> Result<Option<SpecUnit>> {
let (directive, argument) = info.split_once(char::is_whitespace).unwrap_or((info, ""));
let Some(kind) = UnitKind::parse(directive) else {
return Ok(None);
};
// Legacy directives carry path:declaration on their opening line. Keep their
// interpretation, but never mistake them for reviewed structured units.
if argument.contains(':') {
ensure!(
kind != UnitKind::FutureNote,
"future notes cannot have formalization citations; use a stable unit ID"
);
return Ok(None);
}
let id = argument.trim();
if kind.is_math() && id.is_empty() {
bail!(
"{directive} requires a stable unit ID, a :lean: citation, and an authored LaTeX body"
);
}
ensure!(
valid_id(id),
"expected one stable unit ID after {directive}"
);
let raw = &source[range.clone()];
let opening_end = raw
.find('\n')
.context("unit has no body or closing fence")?
+ 1;
let closing_start = raw
.trim_end_matches(['\n', '\r'])
.rfind('\n')
.context("unit has no closing fence")?
+ 1;
let opening = raw[..opening_end].trim_start();
let marker = opening
.chars()
.next()
.context("unit has no opening fence")?;
let width = opening.chars().take_while(|c| *c == marker).count();
let closing = raw[closing_start..].trim();
ensure!(
matches!(marker, '`' | '~')
&& closing.chars().all(|c| c == marker)
&& closing.len() >= width,
"structured unit must have an explicit matching closing fence"
);
let contents = &raw[opening_end..closing_start];
let mut unit = SpecUnit {
id: id.to_owned(),
kind,
draft: false,
source_path: path.to_owned(),
range,
body: String::new(),
raw: raw.to_owned(),
lean: vec![],
rust: vec![],
tests: vec![],
uses: vec![],
};
let mut seen = BTreeSet::new();
let mut body_start = 0;
for line in contents.split_inclusive('\n') {
let line_text = line.trim_end_matches(['\n', '\r']);
if !line_text.starts_with(':') {
break;
}
let (option, value) = line_text[1..]
.split_once(':')
.context("unit option must have the form :name: value")?;
ensure!(seen.insert(option), "duplicate :{option}: option");
let values: Vec<_> = value.split_whitespace().map(str::to_owned).collect();
ensure!(!values.is_empty(), ":{option}: must not be empty");
if option == "status" {
ensure!(
values == ["draft"],
":status: only accepts `draft`; omit it for units ready for correspondence review"
);
unit.draft = true;
body_start += line.len();
continue;
}
let target = match option {
"lean" => &mut unit.lean,
"rust" => &mut unit.rust,
"tests" => &mut unit.tests,
"uses" => &mut unit.uses,
_ => bail!("unknown unit option :{option}:"),
};
let unique: BTreeSet<_> = values.iter().collect();
ensure!(
unique.len() == values.len(),
"duplicate value in :{option}:"
);
*target = values;
body_start += line.len();
}
unit.body = contents[body_start..].trim_matches(['\n', '\r']).to_owned();
// mdBook expands these even inside fenced code. The packet must contain
// exactly the authored content, not untracked external substitutions.
let includes = regex::Regex::new(r"\{\{\s*#(?:include|rustdoc_include|playground)\b")?;
ensure!(
!includes.is_match(&unit.raw),
"mdBook include, rustdoc_include, and playground directives are unsupported inside structured units; write the content directly or cite another unit"
);
for event in Parser::new(&unit.body) {
if let Event::Start(Tag::CodeBlock(CodeBlockKind::Fenced(info))) = event {
let (directive, argument) = info.split_once(char::is_whitespace).unwrap_or((&info, ""));
ensure!(
UnitKind::parse(directive).is_none() || !argument.contains(':'),
"legacy citation directives cannot nest inside structured units; create a separate unit with :lean: and refer to it with :uses:"
);
}
}
ensure!(
!unit.body.trim().is_empty(),
"unit requires an authored body"
);
ensure!(
!unit.body.starts_with(':'),
"unit options must immediately follow the opening fence, before the blank line and body"
);
if kind == UnitKind::FutureNote {
ensure!(
unit.lean.is_empty() && unit.rust.is_empty() && unit.tests.is_empty(),
"future notes cannot have formalization citations (:lean:, :rust:, or :tests:); use a specification unit for formalized content"
);
ensure!(!unit.draft, "future notes cannot have :status: draft; they are exploratory notes, not unfinished specification units");
}
ensure!(
kind == UnitKind::FutureNote || unit.draft || !unit.lean.is_empty() || !unit.rust.is_empty(),
"unit requires :lean: or :rust: citations; use :status: draft while its formalization is pending"
);
ensure!(
unit.tests.is_empty() || !unit.rust.is_empty(),
":tests: requires a :rust: implementation citation"
);
ensure!(
unit.lean.is_empty() || unit.rust.is_empty(),
"a unit cannot mix :lean: and :rust: citations"
);
ensure!(
!matches!(kind, UnitKind::Theorem | UnitKind::Lemma)
|| !unit.lean.is_empty()
|| (unit.draft && unit.rust.is_empty()),
"theorem and lemma units require a Lean theorem; Rust tests are not proofs"
);
ensure!(
!matches!(
kind,
UnitKind::Judgment
| UnitKind::Rule
| UnitKind::Theorem
| UnitKind::Lemma
| UnitKind::Example
) || unit.lean.is_empty()
|| unit.lean.len() == 1,
"{} requires exactly one Lean citation",
kind.label()
);
for dependency in &unit.uses {
ensure!(valid_id(dependency), "invalid dependency ID `{dependency}`");
ensure!(dependency != id, "unit cannot depend on itself");
}
ensure!(
parse(&unit.body, path)?.is_empty(),
"named units cannot nest; cite the other unit with :uses: or a link"
);
Ok(Some(unit))
}
}
#![allow(unused)]
fn main() {
fn directive_blocks(source: &str) -> Vec<DirectiveBlock> {
let mut found = vec![];
let mut block = None;
for (event, range) in Parser::new(source).into_offset_iter() {
match event {
Event::Start(Tag::CodeBlock(CodeBlockKind::Fenced(info)))
if [
"{heap}",
"{grammar}",
"{judgment}",
"{rule}",
"{definition}",
"{theorem}",
"{lemma}",
"{example}",
"{future-note}",
// Recognized only so the shared validator can reject it.
"{obligation}",
"{lean.type}",
"{lean.judgment}",
"{lean.rule}",
]
.iter()
.any(|name| info.starts_with(name)) =>
{
block = Some(DirectiveBlock {
range,
info: info.into_string(),
body: String::new(),
});
}
Event::Text(text) => {
if let Some(block) = &mut block {
block.body.push_str(&text);
}
}
Event::End(TagEnd::CodeBlock) => {
if let Some(mut block) = block.take() {
block.range.end = range.end;
found.push(block);
}
}
_ => {}
}
}
found
}
}
#![allow(unused)]
fn main() {
fn render(
source: &str,
path: &str,
anchors: &BTreeMap<String, String>,
lean_root: Option<&Path>,
project_root: Option<&Path>,
scope: &str,
definition_label: &str,
) -> Result<String> {
let protected = protect_math(source);
let source = protected.as_str();
let structured_units = units::parse(source, path)?;
let mut edits = vec![];
for role in roles(source)? {
let rendered = render_role(&role, path, anchors, definition_label)?;
edits.push((role.range, rendered));
}
for (event, range) in Parser::new(source).into_offset_iter() {
if matches!(event, Event::Start(Tag::Paragraph)) {
ensure!(
!source[range.clone()].starts_with("{example} "),
"the paragraph {{example}} marker has been replaced: use a fenced ```{{example}} path:anchor with a Markdown body and a Lean test, or label an unfinished scenario as informational"
);
if source[range.clone()].starts_with("{informational} ") {
edits.push((
range.start..range.start + "{informational}".len(),
"<span class=\"informational-label\">Informational</span>".to_owned(),
));
}
}
}
for block in directive_blocks(source) {
if let Some(unit) = structured_units
.iter()
.find(|unit| unit.range.start == block.range.start)
{
for dependency in &unit.uses {
ensure!(
anchors.contains_key(dependency),
"unknown unit dependency `{dependency}`"
);
}
edits.push((
block.range,
render_unit(unit, path, anchors, lean_root, project_root)?,
));
continue;
}
let start = block.range.start;
let kind = block.info;
let facts = block.body;
let (directive, argument) = kind.split_once(char::is_whitespace).unwrap_or((&kind, ""));
ensure!(
![
"{heap}",
"{grammar}",
"{rule}",
"{judgment}",
"{definition}",
"{theorem}",
"{lemma}",
"{example}",
"{future-note}"
]
.iter()
.any(|name| directive.starts_with(name) && directive != *name),
"separate the directive name and citation with whitespace"
);
ensure!(!matches!(directive, "{lean.type}" | "{lean.judgment}" | "{lean.rule}"),
"{directive} has been replaced: use ```{{grammar}} path:Name, ```{{judgment}} path:Name, or ```{{rule}} path:Name.case with authored LaTeX in the body");
let id = format!("{scope}-{start}");
if let Some(markdown) = MarkdownDirective::parse(directive) {
let name = markdown.name();
let label = markdown.label();
let citations = argument.split_whitespace().count();
if matches!(markdown, MarkdownDirective::Definition) {
ensure!(
citations > 0,
"definition requires at least one opening-line citation"
);
} else {
ensure!(
citations == 1,
"{name} requires exactly one opening-line citation"
);
}
ensure!(!facts.trim().is_empty(), "{name} requires a Markdown body");
let root =
lean_root.context("Lean directives require preprocessor.dada.lean-source")?;
let lean_source = match markdown {
MarkdownDirective::Definition => lean::definition_source(root, argument)?,
MarkdownDirective::Example => lean::example_source(root, argument.trim())?,
MarkdownDirective::Theorem | MarkdownDirective::Lemma => {
lean::theorem_source(root, argument.trim())?
}
};
let heading_label = if matches!(markdown, MarkdownDirective::Example) {
"example"
} else {
markdown.definition_label()
};
let (heading, body) = markdown_heading(&facts, path, anchors, heading_label)?;
ensure!(
!body.trim().is_empty(),
"{name} requires a Markdown body after its heading anchors"
);
let body = render(
body,
path,
anchors,
lean_root,
project_root,
&id,
markdown.definition_label(),
)?;
let selector = selector_header(
label,
(!heading.is_empty()).then_some(heading.as_str()),
&format!("{name}-{id}"),
"rendered",
"Lean",
);
// Blank lines terminate raw HTML blocks so mdBook renders the body
// as Markdown, including its explicit math delimiters and proof prose.
edits.push((block.range, format!(
"\n<figure class=\"lean-declaration lean-group lean-markdown lean-{name}\">{selector}<div class=\"lean-markdown-body\">\n\n{}\n\n</div><div class=\"lean-source\">{lean_source}</div></figure>\n\n",
body.trim_matches('\n')
)));
continue;
}
let view = match directive {
"{grammar}" => Some(lean::View::Grammar),
"{judgment}" => Some(lean::View::Judgment),
"{rule}" => Some(lean::View::Rule),
_ => None,
};
if let Some(view) = view {
let root =
lean_root.context("Lean directives require preprocessor.dada.lean-source")?;
edits.push((
block.range,
format!(
"\n{}\n",
lean::render_authored(root, argument.trim(), &facts, view, &id)?
),
));
continue;
}
ensure!(
argument.trim().is_empty(),
"{directive} does not accept opening-line arguments"
);
let graph = graph::render(&facts)?;
let selector = selector_header("Diagram", None, &format!("heap-{id}"), "rendered", "Facts");
let source = escape(&facts).replace('\n', " ");
edits.push((block.range, format!("\n<figure class=\"heap-figure\">{selector}{graph}<pre class=\"heap-facts\"><code>{source}</code></pre></figure>\n")));
}
edits.sort_by_key(|(range, _)| range.start);
let mut result = String::new();
let mut end = 0;
for (range, replacement) in edits {
ensure!(range.start >= end, "overlapping markup");
result.push_str(&source[end..range.start]);
result.push_str(&replacement);
end = range.end;
}
result.push_str(&source[end..]);
Ok(result)
}
}
#![allow(unused)]
fn main() {
#[test]
fn block_directives_are_distinct_from_literal_code_and_inline_roles() {
let literal =
"```heap\nnot facts\n```\n\n```grammar\nnot grammar\n```\n\n```lean\nnot lean\n```\n\n```text\n{lean.type}`Missing:Place`\n```";
let mut book = json!({"items": [chapter("a.md", literal)]});
process(&mut book).unwrap();
assert_eq!(book["items"][0]["Chapter"]["content"], literal);
let mut old = json!({"items": [chapter("a.md", "{lean.type}`Renderer:Place`")]});
let error = process(&mut old).unwrap_err();
assert!(format!("{error:#}").contains("lean.type"));
}
}
#![allow(unused)]
fn main() {
#[test]
fn informational_paragraphs_preserve_markdown_and_literal_examples() {
let source = "{informational} Rationale with [a link](state.md) and *emphasis*.\n\n```text\n{informational} Literal.\n```";
let mut book = json!({"items": [chapter("a.md", source)]});
process(&mut book).unwrap();
let output = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(output.contains("<span class=\"informational-label\">Informational</span> Rationale"));
assert!(output.contains("[a link](state.md) and *emphasis*"));
assert!(output.contains("{informational} Literal."));
}
}
#![allow(unused)]
fn main() {
#[test]
fn generated_grammar_directives_require_migration() {
let root = lean_fixtures();
for source in [
"```{lean.type}\nRenderer:Place\n```",
"```{grammar}\nSlot = Empty | Ref(target: Id);\n```",
] {
let mut book = json!({"items": [chapter("state.md", source)]});
let error = mdbook_dada::process_with_lean(&mut book, Some(&root)).expect_err(source);
let message = format!("{error:#}");
assert!(message.contains("state.md"));
assert!(message.contains("grammar"), "{source}: {message}");
assert!(message.contains("authored LaTeX"), "{source}: {message}");
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn inferred_judgment_and_rule_directives_require_migration() {
let root = lean_fixtures();
for (kind, target) in [
("judgment", "Renderer:Step"),
("rule", "Renderer:Step.allocVariable"),
] {
let source = format!("```{{lean.{kind}}}\n{target}\n```");
let mut book = json!({"items": [chapter("ops.md", &source)]});
let error = mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap_err();
let message = format!("{error:#}");
assert!(message.contains(&format!("lean.{kind}")));
assert!(message.contains(&format!("{{{kind}}}")));
assert!(message.contains("ops.md"));
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn drafts_keep_their_semantic_kind_without_claiming_a_formalization() {
let files = Sources::new();
for kind in [
"definition",
"grammar",
"judgment",
"rule",
"theorem",
"lemma",
"example",
] {
let source = format!("```{{{kind}}} model.draft\n:status: draft\n\nProposed content.\n```");
let parsed = units::parse(&source, "model.md").unwrap();
assert!(parsed[0].draft);
assert_eq!(
parsed[0].kind,
UnitKind::parse(&format!("{{{kind}}}")).unwrap()
);
let output = render(&source, &files.lean()).unwrap();
assert!(output.contains(&format!("{kind}: model.draft")));
assert!(output.contains("class=\"block-label unit-status\""));
assert!(output.contains(">Draft</span>"));
assert!(!output.contains("proof obligation"));
assert!(!output.contains("type=\"radio\""));
assert!(!output.contains(":status:"));
assert!(units::parse(&source.replace(":status: draft\n", ""), "model.md").is_err());
}
let current = render(
"```{definition} model.current\n:lean: Model:initial\n\nCurrent definition.\n```",
&files.lean(),
)
.unwrap();
assert!(!current.contains("unit-status"));
assert!(current.contains("value=\"lean\""));
}
}
#![allow(unused)]
fn main() {
#[test]
fn draft_status_is_explicit_and_does_not_relax_citation_checks() {
let files = Sources::new();
for options in [
":status:",
":status: checked",
":status: draft checked",
":status: draft\n:status: draft",
] {
let source = format!("```{{definition}} invalid.status\n{options}\n\nText.\n```");
let error = format!("{:#}", units::parse(&source, "model.md").unwrap_err());
assert!(error.contains("model.md:1"), "{error}");
}
for (kind, citation) in [
("definition", ":lean: Model:missing"),
("definition", ":lean: Model:initial_is_empty"),
("theorem", ":lean: Model:initial"),
("theorem", ":rust: tool.rs:check"),
("example", ":lean: Model:initial_is_empty"),
] {
let source =
format!("```{{{kind}}} invalid.citation\n:status: draft\n{citation}\n\nText.\n```");
assert!(render(&source, &files.lean()).is_err(), "{source}");
}
let output = render(
"```{definition} model.draft\n:status: draft\n:lean: Model:initial\n\nProposed explanation.\n```",
&files.lean(),
)
.unwrap();
assert!(output.contains("value=\"lean\""));
assert!(output.contains(">Draft</span>"));
}
}
#![allow(unused)]
fn main() {
#[test]
fn removed_obligation_syntax_is_rejected_at_every_authoring_entry_point() {
let files = Sources::new();
assert!(UnitKind::parse("{obligation}").is_none());
assert!(serde_json::from_str::<UnitKind>("\"obligation\"").is_err());
for source in [
"```{obligation} model.pending\nUnfinished.\n```",
"```{obligation} Model:initial\nUnfinished.\n```",
"```{obligation}pending\nvars = variables()\nvars.x = uninitialized()\n```",
"{obligation}`pending` Unfinished.",
"> ```{obligation} pending\n> Unfinished.\n> ```",
"- ```{obligation} pending\n Unfinished.\n ```",
"```{definition} Model:initial\n{obligation}`pending` Unfinished.\n```",
"````{definition} model.draft\n:status: draft\n\n```{obligation} pending\nUnfinished.\n```\n````",
] {
let error = format!("{:#}", units::parse(source, "model.md").unwrap_err());
assert!(error.contains("model.md"), "{error}");
assert!(error.contains("{obligation} has been removed"), "{error}");
assert!(error.contains(":status: draft"), "{error}");
assert!(render(source, &files.lean()).is_err(), "{source}");
}
}
}
A block’s header keeps its identity on the left and its view controls on the right. Rendered is selected initially. Lean-backed blocks offer Rendered/Lean; Rust-backed blocks offer Rendered/Rust; diagrams offer Rendered/Facts. Each selector controls its own block, including when blocks are nested.
A structured unit’s ID appears once, as a shield in its header. Draft status remains visible in both views. In legacy Markdown blocks, leading defining anchors move to the header; later anchors stay in the body. An unanchored legacy block shows its kind as a plain label. The source view identifies every citation and shows its selected text.
The selector supports comparison. It does not judge correspondence or check a proof. Header arrangement and visibility use the checked-in CSS; the cited asset test checks those rules without executing a browser.
#![allow(unused)]
fn main() {
/// Shared header for every rendered/source pair. The heading is generated HTML;
/// labels, group names, and radio values are escaped here.
pub(crate) fn selector_header(
label: &str,
heading: Option<&str>,
group: &str,
rendered_value: &str,
alternate: &str,
) -> String {
let label = escape(label);
let fallback = format!("<span class=\"block-label\">{label}</span>");
let heading = heading.unwrap_or(&fallback);
let group = escape(group);
let rendered_value = escape(rendered_value);
let alternate_value = escape(&alternate.to_ascii_lowercase());
let alternate = escape(alternate);
format!("<div class=\"lean-selector\" role=\"group\" aria-label=\"{label} view\"><div class=\"block-heading\">{heading}</div><div class=\"view-options\"><label><input type=\"radio\" name=\"{group}\" value=\"{rendered_value}\" checked> Rendered</label><label><input type=\"radio\" name=\"{group}\" value=\"{alternate_value}\"> {alternate}</label></div></div>")
}
}
#![allow(unused)]
fn main() {
fn markdown_heading<'a>(
source: &'a str,
path: &str,
anchors: &BTreeMap<String, String>,
definition_label: &str,
) -> Result<(String, &'a str)> {
let protected = protect_math(source);
let mut heading = Vec::new();
let mut end = 0;
for role in roles(&protected)? {
if !protected[end..role.range.start].trim().is_empty() || !role.definition {
break;
}
heading.push(render_role(&role, path, anchors, definition_label)?);
// A promoted role is preceded only by whitespace and other roles, so
// math protection has not changed its source offsets.
end = role.range.end;
}
Ok((heading.join(" "), &source[end..]))
}
}
#![allow(unused)]
fn main() {
fn render_unit(
unit: &units::SpecUnit,
path: &str,
anchors: &BTreeMap<String, String>,
lean_root: Option<&Path>,
project_root: Option<&Path>,
) -> Result<String> {
let label = unit.kind.label();
let lower_label = label.to_ascii_lowercase();
let role = Role {
range: unit.range.clone(),
id: unit.id.clone(),
definition: true,
label: None,
lean: false,
};
let mut heading = render_role(&role, path, anchors, &lower_label)?;
if unit.draft {
heading.push_str(" <span class=\"block-label unit-status\" title=\"Formalization and correspondence review pending\">Draft</span>");
}
let (alternate, cited_source) = if !unit.lean.is_empty() {
let root = lean_root.context("Lean directives require preprocessor.dada.lean-source")?;
("Lean", lean::selected_source(root, &unit.lean, unit.kind)?)
} else if !unit.rust.is_empty() {
let root = project_root.context("Rust citations require a configured project root")?;
let mut cited = String::new();
for target in unit.rust.iter().chain(&unit.tests) {
let selected = crate::rust_source::select(root, target)?;
cited.push_str(&format!(
"<figcaption>{}</figcaption><pre><code class=\"language-rust\">{}</code></pre>",
escape(target),
escape(&selected.selected).replace('\n', " ")
));
}
("Rust", cited)
} else {
("", String::new())
};
let header = if alternate.is_empty() {
format!("<div class=\"lean-selector\"><div class=\"block-heading\">{heading}</div></div>")
} else {
selector_header(
label,
Some(&heading),
&format!("unit-{}", unit.id),
"rendered",
alternate,
)
};
let body = if unit.kind.is_math() {
let tex = escape(unit.body.trim()).replace('\n', " ");
format!("<div class=\"lean-grammar\"><div class=\"math-display\">\\[{tex}\\]</div></div>")
} else {
let body = render(
&unit.body,
path,
anchors,
lean_root,
project_root,
&unit.id,
&lower_label,
)?;
format!(
"<div class=\"lean-markdown-body\">\n\n{}\n\n</div>",
body.trim_matches('\n')
)
};
let markdown_class = if unit.kind.is_math() {
""
} else {
" lean-markdown"
};
Ok(format!("\n<figure class=\"lean-declaration lean-group{markdown_class}\">{header}{body}<div class=\"lean-source\">{cited_source}</div></figure>\n\n"))
}
}
#![allow(unused)]
fn main() {
fn render(
source: &str,
path: &str,
anchors: &BTreeMap<String, String>,
lean_root: Option<&Path>,
project_root: Option<&Path>,
scope: &str,
definition_label: &str,
) -> Result<String> {
let protected = protect_math(source);
let source = protected.as_str();
let structured_units = units::parse(source, path)?;
let mut edits = vec![];
for role in roles(source)? {
let rendered = render_role(&role, path, anchors, definition_label)?;
edits.push((role.range, rendered));
}
for (event, range) in Parser::new(source).into_offset_iter() {
if matches!(event, Event::Start(Tag::Paragraph)) {
ensure!(
!source[range.clone()].starts_with("{example} "),
"the paragraph {{example}} marker has been replaced: use a fenced ```{{example}} path:anchor with a Markdown body and a Lean test, or label an unfinished scenario as informational"
);
if source[range.clone()].starts_with("{informational} ") {
edits.push((
range.start..range.start + "{informational}".len(),
"<span class=\"informational-label\">Informational</span>".to_owned(),
));
}
}
}
for block in directive_blocks(source) {
if let Some(unit) = structured_units
.iter()
.find(|unit| unit.range.start == block.range.start)
{
for dependency in &unit.uses {
ensure!(
anchors.contains_key(dependency),
"unknown unit dependency `{dependency}`"
);
}
edits.push((
block.range,
render_unit(unit, path, anchors, lean_root, project_root)?,
));
continue;
}
let start = block.range.start;
let kind = block.info;
let facts = block.body;
let (directive, argument) = kind.split_once(char::is_whitespace).unwrap_or((&kind, ""));
ensure!(
![
"{heap}",
"{grammar}",
"{rule}",
"{judgment}",
"{definition}",
"{theorem}",
"{lemma}",
"{example}",
"{future-note}"
]
.iter()
.any(|name| directive.starts_with(name) && directive != *name),
"separate the directive name and citation with whitespace"
);
ensure!(!matches!(directive, "{lean.type}" | "{lean.judgment}" | "{lean.rule}"),
"{directive} has been replaced: use ```{{grammar}} path:Name, ```{{judgment}} path:Name, or ```{{rule}} path:Name.case with authored LaTeX in the body");
let id = format!("{scope}-{start}");
if let Some(markdown) = MarkdownDirective::parse(directive) {
let name = markdown.name();
let label = markdown.label();
let citations = argument.split_whitespace().count();
if matches!(markdown, MarkdownDirective::Definition) {
ensure!(
citations > 0,
"definition requires at least one opening-line citation"
);
} else {
ensure!(
citations == 1,
"{name} requires exactly one opening-line citation"
);
}
ensure!(!facts.trim().is_empty(), "{name} requires a Markdown body");
let root =
lean_root.context("Lean directives require preprocessor.dada.lean-source")?;
let lean_source = match markdown {
MarkdownDirective::Definition => lean::definition_source(root, argument)?,
MarkdownDirective::Example => lean::example_source(root, argument.trim())?,
MarkdownDirective::Theorem | MarkdownDirective::Lemma => {
lean::theorem_source(root, argument.trim())?
}
};
let heading_label = if matches!(markdown, MarkdownDirective::Example) {
"example"
} else {
markdown.definition_label()
};
let (heading, body) = markdown_heading(&facts, path, anchors, heading_label)?;
ensure!(
!body.trim().is_empty(),
"{name} requires a Markdown body after its heading anchors"
);
let body = render(
body,
path,
anchors,
lean_root,
project_root,
&id,
markdown.definition_label(),
)?;
let selector = selector_header(
label,
(!heading.is_empty()).then_some(heading.as_str()),
&format!("{name}-{id}"),
"rendered",
"Lean",
);
// Blank lines terminate raw HTML blocks so mdBook renders the body
// as Markdown, including its explicit math delimiters and proof prose.
edits.push((block.range, format!(
"\n<figure class=\"lean-declaration lean-group lean-markdown lean-{name}\">{selector}<div class=\"lean-markdown-body\">\n\n{}\n\n</div><div class=\"lean-source\">{lean_source}</div></figure>\n\n",
body.trim_matches('\n')
)));
continue;
}
let view = match directive {
"{grammar}" => Some(lean::View::Grammar),
"{judgment}" => Some(lean::View::Judgment),
"{rule}" => Some(lean::View::Rule),
_ => None,
};
if let Some(view) = view {
let root =
lean_root.context("Lean directives require preprocessor.dada.lean-source")?;
edits.push((
block.range,
format!(
"\n{}\n",
lean::render_authored(root, argument.trim(), &facts, view, &id)?
),
));
continue;
}
ensure!(
argument.trim().is_empty(),
"{directive} does not accept opening-line arguments"
);
let graph = graph::render(&facts)?;
let selector = selector_header("Diagram", None, &format!("heap-{id}"), "rendered", "Facts");
let source = escape(&facts).replace('\n', " ");
edits.push((block.range, format!("\n<figure class=\"heap-figure\">{selector}{graph}<pre class=\"heap-facts\"><code>{source}</code></pre></figure>\n")));
}
edits.sort_by_key(|(range, _)| range.start);
let mut result = String::new();
let mut end = 0;
for (range, replacement) in edits {
ensure!(range.start >= end, "overlapping markup");
result.push_str(&source[end..range.start]);
result.push_str(&replacement);
end = range.end;
}
result.push_str(&source[end..]);
Ok(result)
}
}
#![allow(unused)]
fn main() {
#[test]
fn leading_declaration_shields_move_to_headers_without_losing_ids_or_body_markup() {
use pulldown_cmark::{Event, Parser, Tag};
let root = lean_fixtures();
for (kind, citation) in [
("definition", "Renderer:readSlot"),
("theorem", "Renderer:deallocVariable_requires_top"),
("lemma", "Renderer:deallocVariable_requires_top"),
("example", "Renderer:integer_primitive"),
] {
let source = format!(
"```{{{kind}}} {citation}\n\n {{anchor}}`lookup`\n{{definition}}`second` **Statement.** See {{anchor-ref}}`lookup`.\n\n\\\\[S(p)=s\\\\]\n\n{{anchor}}`later` Details.\n```"
);
let mut book = json!({"items": [
chapter("intro.md", "See {anchor-ref}`lookup`."),
chapter("model/state.md", &source)
]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let output = book["items"][1]["Chapter"]["content"].as_str().unwrap();
let (header, body) = output
.split_once("<div class=\"lean-markdown-body\">")
.unwrap();
assert!(header.contains("<div class=\"block-heading\"><a id=\"claim-lookup\""));
assert!(header.contains("id=\"claim-second\""));
assert!(header.contains(&format!("aria-label=\"{kind}: lookup\"")));
assert!(header.contains("class=\"view-options\""));
assert!(!header.contains("class=\"block-label\""));
assert_eq!(output.matches("id=\"claim-lookup\"").count(), 1);
assert_eq!(output.matches("id=\"claim-second\"").count(), 1);
assert!(body.contains("id=\"claim-later\""));
assert!(body.contains("href=\"#claim-lookup\""));
assert!(body.contains("<div class=\"math-display\">\\[S(p)=s\\]</div>"));
assert!(Parser::new(output).any(|event| matches!(event, Event::Start(Tag::Strong))));
assert!(book["items"][0]["Chapter"]["content"]
.as_str()
.unwrap()
.contains("model/state.html#claim-lookup"));
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn nonheading_roles_and_nested_diagrams_stay_in_the_markdown_body() {
let root = lean_fixtures();
for prefix in [
"Opening prose.\n\n{anchor}`body`",
"{anchor-ref}`outside`\n\n{anchor}`body`",
"`{anchor}`literal\n\n{anchor}`body`",
"<!-- Heading comment. -->\n\n{anchor}`body`",
] {
let source = format!(
"{{anchor}}`outside`\n\n````{{definition}} Renderer:readSlot\n{prefix} Statement.\n\n```{{heap}}\nvars = variables()\nvars.x = uninitialized()\n```\n````"
);
let mut book = json!({"items": [chapter("state.md", &source)]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let output = book["items"][0]["Chapter"]["content"].as_str().unwrap();
let (header, body) = output
.split_once("<div class=\"lean-markdown-body\">")
.unwrap();
assert!(header.contains("<span class=\"block-label\">Definition</span>"));
assert!(!header.contains("id=\"claim-body\""));
assert!(body.contains("id=\"claim-body\""));
assert!(body.contains("<span class=\"block-label\">Diagram</span>"));
assert!(body.contains("<svg"));
assert_eq!(output.matches("class=\"view-options\"").count(), 2);
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn unanchored_rendered_blocks_share_named_headers_and_grouped_choices() {
let root = lean_fixtures();
let radio_names = regex::Regex::new(r#"type="radio" name="([^"]+)""#).unwrap();
for (kind, label, citation, body, alternate) in [
(
"definition",
"Definition",
"Renderer:readSlot",
"Statement.",
"Lean",
),
(
"theorem",
"Theorem",
"Renderer:deallocVariable_requires_top",
"Statement.",
"Lean",
),
(
"lemma",
"Lemma",
"Renderer:deallocVariable_requires_top",
"Statement.",
"Lean",
),
(
"example",
"Example",
"Renderer:integer_primitive",
"Statement.",
"Lean",
),
("grammar", "Grammar", "Renderer:Slot", "s ::= r", "Lean"),
("judgment", "Judgment", "Renderer:Step", "S \\to S'", "Lean"),
("rule", "Rule", "Renderer:Step.allocVariable", "P", "Lean"),
("heap", "Diagram", "", "vars = variables()", "Facts"),
] {
let source = format!("```{{{kind}}} {citation}\n{body}\n```");
let mut book = json!({"items": [chapter("state.md", &source)]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let output = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(output.contains(&format!("aria-label=\"{label} view\"")));
assert!(output.contains(&format!("<div class=\"block-heading\"><span class=\"block-label\">{label}</span></div><div class=\"view-options\">")));
assert_eq!(output.matches("> Rendered</label>").count(), 1);
assert_eq!(output.matches(&format!("> {alternate}</label>")).count(), 1);
let names: Vec<_> = radio_names
.captures_iter(output)
.map(|capture| capture[1].to_owned())
.collect();
assert_eq!(names.len(), 2);
assert_eq!(names[0], names[1]);
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn structured_units_render_identified_headers_and_exact_lean_views() {
let files = Sources::new();
for (kind, citation, body, expected) in [
(
"definition",
"Model:initial",
"The initial object is empty.",
"def initial",
),
(
"grammar",
"Model:Thing",
"t ::= \\mathsf{empty}",
"inductive Thing",
),
("judgment", "Model:Step", "t \\to t'", "inductive Step"),
("rule", "Model:Step.same", "\\frac{}{t \\to t}", "| same"),
(
"theorem",
"Model:initial_is_empty",
"The initial object is empty.",
"theorem initial_is_empty",
),
(
"lemma",
"Model:initial_is_empty",
"The initial object is empty.",
"theorem initial_is_empty",
),
(
"example",
"Model:basic",
"The initial object is empty.",
"example : initial",
),
] {
let source = format!("```{{{kind}}} model.unit\n:lean: {citation}\n\n{body}\n```\n\nSee {{anchor-ref}}`model.unit`.");
let output = render(&source, &files.lean()).unwrap();
assert_eq!(output.matches("id=\"claim-model.unit\"").count(), 1);
assert!(output.contains("href=\"#claim-model.unit\""));
assert!(output.contains("class=\"view-options\""));
assert!(output.contains("value=\"lean\""));
assert!(!output.contains(":lean:"));
let selected = lean::select(
&files.lean(),
citation,
UnitKind::parse(&format!("{{{kind}}}")).unwrap(),
)
.unwrap();
assert!(
selected.selected.contains(expected),
"{}",
selected.selected
);
assert!(selected.source.contains("theorem initial_is_empty"));
assert!(selected.path.is_absolute());
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn meta_units_show_named_rust_implementation_and_test() {
let files = Sources::new();
let output = render("```{definition} meta.check\n:rust: tool.rs:check\n:tests: tool.rs:checks\n\nThe checker accepts this input.\n```", &files.lean()).unwrap();
assert!(output.contains("value=\"rust\""));
assert!(output.contains("pub fn check()"));
assert!(output.contains("fn checks()"));
assert!(!output.contains(":rust:"));
}
}
#![allow(unused)]
fn main() {
#[test]
fn view_styles_keep_headers_and_nested_choices_independent() {
let css = read_asset("theme/dada.css");
let options = css
.split_once(".lean-selector .view-options {")
.unwrap()
.1
.split_once('}')
.unwrap()
.0;
assert!(options.contains("margin-left:auto"));
// A nested diagram's radio button must not switch its enclosing Lean block.
// The selector reaches the block's own header, then changes only its children.
for pane in [".lean-source", ".lean-grammar", ".lean-markdown-body"] {
assert!(css.contains(&format!(
".lean-group:has(> .lean-selector input:is([value=\"lean\"], [value=\"rust\"]):checked) > {pane}"
)));
}
assert!(css.contains(
".heap-figure:has(input[value=\"facts\"]:checked) .heap-facts { display:block; }"
));
assert!(css.contains(
".heap-figure:has(input[value=\"facts\"]:checked) .heap-diagram { display:none; }"
));
for selector in [".lean-grammar", ".lean-source pre", ".heap-figure"] {
let declaration = css
.split_once(&format!("{selector} {{"))
.unwrap()
.1
.split_once('}')
.unwrap()
.0;
assert!(declaration.contains("overflow-x:auto"), "{selector}");
}
let mut book = json!({"items": [{"Chapter": {
"path": "local.md", "content": "{anchor}`local.identity`\n\n{anchor-ref}`local.identity`", "sub_items": []
}}]});
process(&mut book).unwrap();
let rendered = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert_eq!(rendered.matches("class=\"spec-shield\"").count(), 2);
assert!(rendered.contains("href=\"#claim-local.identity\""));
assert!(!rendered.contains("<img"));
assert!(!rendered.contains("src="));
assert!(
!css.contains("url("),
"shield styling must not fetch a remote badge"
);
}
}
Authored mathematics
The renderer preserves authored mathematics. Grammar, judgment, and rule bodies
are raw LaTeX; the renderer supplies display delimiters and does not interpret
Markdown within them. Definition, theorem, lemma, and example bodies are
Markdown and use explicit \\[ / \\] or \\( / \\) delimiters.
The preprocessor protects explicit math from Markdown escaping and smart punctuation, retaining TeX row breaks, primes, braces, and underscores. Code, links, and HTML literal contexts are excluded. Both mathematical text and source selections are escaped for HTML. MathJax typesets the result in the browser; the renderer does not translate Lean into mathematics or validate LaTeX as Lean.
definitionmeta.syntax.grammar.rendering A grammar’s ordered citations share one Rendered/Lean selector. Judgment and rule blocks use the same presentation, with their own authored notation.
#![allow(unused)]
fn main() {
fn protect_math(source: &str) -> String {
let literal: Vec<_> = Parser::new(source)
.into_offset_iter()
.filter_map(|(event, range)| match event {
Event::Start(
Tag::CodeBlock(_) | Tag::HtmlBlock | Tag::Link { .. } | Tag::Image { .. },
)
| Event::Code(_)
| Event::Html(_)
| Event::InlineHtml(_) => Some(range),
_ => None,
})
.collect();
let mut output = String::new();
let mut end = 0;
for (start, _) in source.match_indices(r"\\") {
if start < end
|| source[..start].ends_with('\\')
|| literal.iter().any(|range| range.contains(&start))
{
continue;
}
let (display, closing) = match source.as_bytes().get(start + 2) {
Some(b'[') => (true, r"\\]"),
Some(b'(') => (false, r"\\)"),
_ => continue,
};
let body_start = start + 3;
let Some(close) = source[body_start..].find(closing).map(|i| body_start + i) else {
continue;
};
if literal.iter().any(|range| range.contains(&close)) {
continue;
}
let body = &source[body_start..close];
output.push_str(&source[end..start]);
if display {
let tex = escape(body).replace('\n', " ");
output.push_str(&format!(
"\n\n<div class=\"math-display\">\\[{tex}\\]</div>\n\n"
));
} else {
// Inline HTML does not suppress Markdown parsing of its contents.
// Entities keep every TeX punctuation character out of that parser.
let tex: String = format!("\\({body}\\)")
.chars()
.map(|c| {
if c.is_alphanumeric() || c == ' ' {
c.to_string()
} else {
format!("&#{};", u32::from(c))
}
})
.collect();
output.push_str(&format!("<span class=\"math-inline\">{tex}</span>"));
}
end = close + closing.len();
}
output.push_str(&source[end..]);
output
}
}
#![allow(unused)]
fn main() {
fn render_unit(
unit: &units::SpecUnit,
path: &str,
anchors: &BTreeMap<String, String>,
lean_root: Option<&Path>,
project_root: Option<&Path>,
) -> Result<String> {
let label = unit.kind.label();
let lower_label = label.to_ascii_lowercase();
let role = Role {
range: unit.range.clone(),
id: unit.id.clone(),
definition: true,
label: None,
lean: false,
};
let mut heading = render_role(&role, path, anchors, &lower_label)?;
if unit.draft {
heading.push_str(" <span class=\"block-label unit-status\" title=\"Formalization and correspondence review pending\">Draft</span>");
}
let (alternate, cited_source) = if !unit.lean.is_empty() {
let root = lean_root.context("Lean directives require preprocessor.dada.lean-source")?;
("Lean", lean::selected_source(root, &unit.lean, unit.kind)?)
} else if !unit.rust.is_empty() {
let root = project_root.context("Rust citations require a configured project root")?;
let mut cited = String::new();
for target in unit.rust.iter().chain(&unit.tests) {
let selected = crate::rust_source::select(root, target)?;
cited.push_str(&format!(
"<figcaption>{}</figcaption><pre><code class=\"language-rust\">{}</code></pre>",
escape(target),
escape(&selected.selected).replace('\n', " ")
));
}
("Rust", cited)
} else {
("", String::new())
};
let header = if alternate.is_empty() {
format!("<div class=\"lean-selector\"><div class=\"block-heading\">{heading}</div></div>")
} else {
selector_header(
label,
Some(&heading),
&format!("unit-{}", unit.id),
"rendered",
alternate,
)
};
let body = if unit.kind.is_math() {
let tex = escape(unit.body.trim()).replace('\n', " ");
format!("<div class=\"lean-grammar\"><div class=\"math-display\">\\[{tex}\\]</div></div>")
} else {
let body = render(
&unit.body,
path,
anchors,
lean_root,
project_root,
&unit.id,
&lower_label,
)?;
format!(
"<div class=\"lean-markdown-body\">\n\n{}\n\n</div>",
body.trim_matches('\n')
)
};
let markdown_class = if unit.kind.is_math() {
""
} else {
" lean-markdown"
};
Ok(format!("\n<figure class=\"lean-declaration lean-group{markdown_class}\">{header}{body}<div class=\"lean-source\">{cited_source}</div></figure>\n\n"))
}
}
#![allow(unused)]
fn main() {
/// Check source citations and pair authored LaTeX with those source excerpts.
/// No mathematical syntax is generated from, or compared with, the Lean source.
pub fn render_authored(
root: &Path,
targets: &str,
body: &str,
view: View,
group: &str,
) -> Result<String> {
let targets: Vec<_> = targets.split_whitespace().collect();
ensure!(!targets.is_empty(), "expected Lean citations on the directive opening line; use ```{{grammar}} path:Name with authored LaTeX in the body");
ensure!(
view == View::Grammar || targets.len() == 1,
"judgment and rule directives require exactly one opening-line citation"
);
ensure!(
!body.trim().is_empty(),
"authored math directive requires a LaTeX body"
);
let mut source = String::new();
for target in targets {
let (file, selected) = read_source(root, target)?;
let (name, case) = if view == View::Rule {
let (name, case) = selected
.rsplit_once('.')
.context("rule expects path:Judgment.constructor")?;
(name, Some(case))
} else {
(selected.as_str(), None)
};
let declaration = extract(&file, name).with_context(|| target.to_owned())?;
ensure!(
!matches!(view, View::Judgment | View::Rule) || declaration.starts_with("inductive "),
"judgment and rule citations must select inductive declarations"
);
let declaration = if let Some(case) = case {
extract_case(&declaration, case)?
} else {
declaration
};
source.push_str(&format!(
"<figcaption>{}</figcaption><pre><code class=\"language-lean\">{}</code></pre>",
crate::escape(target),
highlighted(&declaration)?
));
}
// Keep blank lines inside the raw HTML block so Markdown cannot reinterpret
// the authored TeX. Escaping also keeps TeX text from becoming HTML markup.
let tex = crate::escape(body.trim()).replace('\n', " ");
let rendered = format!("<div class=\"math-display\">\\[{tex}\\]</div>");
let label = match view {
View::Grammar => "Grammar",
View::Judgment => "Judgment",
View::Rule => "Rule",
};
Ok(selector(&rendered, &source, group, label))
}
}
#![allow(unused)]
fn main() {
pub fn escape(s: &str) -> String {
s.replace('&', "&")
.replace('<', "<")
.replace('>', ">")
.replace('"', """)
.replace('\'', "'")
}
}
#![allow(unused)]
fn main() {
#[test]
fn authored_grammar_keeps_math_and_groups_citations_in_order() {
let root = lean_fixtures();
let source = r"```{grammar} Renderer:Slot Renderer.lean:Object
\begin{aligned}
s &::= \bot \mid r \\
o &::= p \mid \{f \mapsto s\} \mid {\overline s}
\end{aligned}
```";
let mut book = json!({"items": [chapter("state.md", source)]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let html = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(html.contains(r"s &::= \bot \mid r"));
assert!(html.contains(r"o &::= p \mid \{f \mapsto s\} \mid {\overline s}"));
assert!(html.find("Renderer:Slot").unwrap() < html.find("Renderer.lean:Object").unwrap());
let lean = html.split("class=\"lean-source\"").nth(1).unwrap();
assert!(lean.find("Slot").unwrap() < lean.find("Object").unwrap());
assert!(lean.contains("| uninitialized"));
assert!(lean.contains("| array"));
assert!(lean.contains("lean-keyword"));
assert_eq!(html.matches("class=\"lean-selector\"").count(), 1);
assert_eq!(html.matches("> Rendered</label>").count(), 1);
assert_eq!(html.matches("> Lean</label>").count(), 1);
let rendered = html.split("class=\"lean-source\"").next().unwrap();
assert!(!rendered.contains("uniqueKeys"));
assert!(!rendered.contains("FiniteMap"));
}
}
#![allow(unused)]
fn main() {
#[test]
fn authored_math_escapes_html_without_interpreting_placeholders() {
let root = lean_fixtures();
let source = r"```{rule} Renderer:Step.allocVariable
\frac{a < b & c > d}{${authorChosenName}}
```
";
let mut book = json!({"items": [chapter("ops.md", source)]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let html = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(html.contains(r"\frac{a < b & c > d}{${authorChosenName}}"));
assert!(!html.contains("a < b & c > d"));
let rendered = html.split("class=\"lean-source\"").next().unwrap();
assert!(!rendered.contains(r"\xrightarrow"));
assert!(!rendered.contains("insertFresh"));
}
}
#![allow(unused)]
fn main() {
#[test]
fn explicit_math_survives_markdown_and_smart_punctuation_in_prose_and_proof_bodies() {
use pulldown_cmark::{Event, Options, Parser};
let root = lean_fixtures();
let formula = r"\frac{S'=S[p\mapsto s]}{S'(q)=\begin{cases}s&q=p\\S(q)&q\ne p\end{cases}}";
let body = format!(
"**Statement.** The result is \\\\(S'_x \\ne S_x\\\\).\n\n\\\\[\n{formula}\n\\\\]\n\n**Proof outline.** Apply the rule."
);
for opening in [
None,
Some("{example} Renderer:integer_primitive"),
Some("{definition} Renderer:readSlot"),
Some("{theorem} Renderer:deallocVariable_requires_top"),
Some("{lemma} Renderer:deallocVariable_requires_top"),
] {
let source = opening.map_or_else(|| body.clone(), |info| format!("```{info}\n{body}\n```"));
let mut book = json!({"items": [chapter("proofs.md", &source)]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let markdown = book["items"][0]["Chapter"]["content"].as_str().unwrap();
let events: Vec<_> = Parser::new_ext(markdown, Options::ENABLE_SMART_PUNCTUATION).collect();
let rendered: String = events
.iter()
.filter_map(|event| match event {
Event::Text(text) | Event::Html(text) | Event::InlineHtml(text) => {
Some(text.as_ref())
}
_ => None,
})
.collect();
assert!(
rendered.contains(&format!(
"<div class=\"math-display\">\\[ {} \\]</div>",
mdbook_dada::escape(formula)
)),
"{rendered}"
);
assert!(
rendered.contains("<span class=\"math-inline\">\\(S'_x \\ne S_x\\)</span>"),
"{rendered}"
);
assert!(rendered.contains("Statement."));
assert!(rendered.contains("Proof outline."));
assert!(!rendered.contains('’'));
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn explicit_math_is_literal_in_code_links_and_html_and_does_not_define_roles() {
let literal = r"```text
\\[
S' \\ T
\\]
```
\\(S'_x\\)
`\\(S'\\)` and [\\(S'\\)](somewhere.md).
<pre>\\[S'\\]</pre>
Escaped \\\(S'\\).
";
let mut book = json!({"items": [chapter("literal.md", literal)]});
process(&mut book).unwrap();
assert_eq!(book["items"][0]["Chapter"]["content"], literal);
let mut math = json!({"items": [chapter("math.md", r"\\[\text{{anchor}`literal`}\\] \n\\(\text{{definition}`literal`}\\)")]});
process(&mut math).unwrap();
let output = math["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(output.contains("math-display"));
assert!(output.contains("math-inline"));
assert!(!output.contains("spec-shield"));
}
}
The renderer emits MathJax delimiters for the runtime configured by
book.toml and theme/mathjax.js. The bundled loader selects MathJax 4.1.3’s
CommonHTML build; mdBook’s built-in MathJax loader is disabled. Local previews
and published pages load that same script. Authored display breaks are retained,
and wide mathematical blocks can scroll horizontally.
The loader uses a CDN, so browser typesetting requires network access. The source text and selectors remain available independently. The tests inspect configuration and emitted HTML/CSS; they do not guarantee CDN availability or verify the appearance of every possible formula.
#![allow(unused)]
fn main() {
fn protect_math(source: &str) -> String {
let literal: Vec<_> = Parser::new(source)
.into_offset_iter()
.filter_map(|(event, range)| match event {
Event::Start(
Tag::CodeBlock(_) | Tag::HtmlBlock | Tag::Link { .. } | Tag::Image { .. },
)
| Event::Code(_)
| Event::Html(_)
| Event::InlineHtml(_) => Some(range),
_ => None,
})
.collect();
let mut output = String::new();
let mut end = 0;
for (start, _) in source.match_indices(r"\\") {
if start < end
|| source[..start].ends_with('\\')
|| literal.iter().any(|range| range.contains(&start))
{
continue;
}
let (display, closing) = match source.as_bytes().get(start + 2) {
Some(b'[') => (true, r"\\]"),
Some(b'(') => (false, r"\\)"),
_ => continue,
};
let body_start = start + 3;
let Some(close) = source[body_start..].find(closing).map(|i| body_start + i) else {
continue;
};
if literal.iter().any(|range| range.contains(&close)) {
continue;
}
let body = &source[body_start..close];
output.push_str(&source[end..start]);
if display {
let tex = escape(body).replace('\n', " ");
output.push_str(&format!(
"\n\n<div class=\"math-display\">\\[{tex}\\]</div>\n\n"
));
} else {
// Inline HTML does not suppress Markdown parsing of its contents.
// Entities keep every TeX punctuation character out of that parser.
let tex: String = format!("\\({body}\\)")
.chars()
.map(|c| {
if c.is_alphanumeric() || c == ' ' {
c.to_string()
} else {
format!("&#{};", u32::from(c))
}
})
.collect();
output.push_str(&format!("<span class=\"math-inline\">{tex}</span>"));
}
end = close + closing.len();
}
output.push_str(&source[end..]);
output
}
}
#![allow(unused)]
fn main() {
/// Check source citations and pair authored LaTeX with those source excerpts.
/// No mathematical syntax is generated from, or compared with, the Lean source.
pub fn render_authored(
root: &Path,
targets: &str,
body: &str,
view: View,
group: &str,
) -> Result<String> {
let targets: Vec<_> = targets.split_whitespace().collect();
ensure!(!targets.is_empty(), "expected Lean citations on the directive opening line; use ```{{grammar}} path:Name with authored LaTeX in the body");
ensure!(
view == View::Grammar || targets.len() == 1,
"judgment and rule directives require exactly one opening-line citation"
);
ensure!(
!body.trim().is_empty(),
"authored math directive requires a LaTeX body"
);
let mut source = String::new();
for target in targets {
let (file, selected) = read_source(root, target)?;
let (name, case) = if view == View::Rule {
let (name, case) = selected
.rsplit_once('.')
.context("rule expects path:Judgment.constructor")?;
(name, Some(case))
} else {
(selected.as_str(), None)
};
let declaration = extract(&file, name).with_context(|| target.to_owned())?;
ensure!(
!matches!(view, View::Judgment | View::Rule) || declaration.starts_with("inductive "),
"judgment and rule citations must select inductive declarations"
);
let declaration = if let Some(case) = case {
extract_case(&declaration, case)?
} else {
declaration
};
source.push_str(&format!(
"<figcaption>{}</figcaption><pre><code class=\"language-lean\">{}</code></pre>",
crate::escape(target),
highlighted(&declaration)?
));
}
// Keep blank lines inside the raw HTML block so Markdown cannot reinterpret
// the authored TeX. Escaping also keeps TeX text from becoming HTML markup.
let tex = crate::escape(body.trim()).replace('\n', " ");
let rendered = format!("<div class=\"math-display\">\\[{tex}\\]</div>");
let label = match view {
View::Grammar => "Grammar",
View::Judgment => "Judgment",
View::Rule => "Rule",
};
Ok(selector(&rendered, &source, group, label))
}
}
#![allow(unused)]
fn main() {
#[test]
fn pinned_mathjax_configuration_uses_one_loader() {
let config: toml::Value = toml::from_str(&read_asset("book.toml")).unwrap();
let html = &config["output"]["html"];
assert_eq!(html["mathjax-support"].as_bool(), Some(false));
let scripts = html["additional-js"].as_array().unwrap();
assert_eq!(
scripts.len(),
1,
"review any added loader for duplicate MathJax initialization"
);
assert_eq!(scripts[0].as_str(), Some("theme/mathjax.js"));
assert!(html["additional-css"]
.as_array()
.unwrap()
.iter()
.any(|path| path.as_str() == Some("theme/dada.css")));
let script = read_asset("theme/mathjax.js");
let urls = regex::Regex::new(r#"https://[^'"\s]+"#).unwrap();
let urls: Vec<_> = urls.find_iter(&script).map(|m| m.as_str()).collect();
assert_eq!(
urls,
["https://cdn.jsdelivr.net/npm/mathjax@4.1.3/tex-chtml.js"]
);
assert_eq!(
script.matches("document.createElement('script')").count(),
1
);
assert_eq!(
script
.matches("document.head.appendChild(mathjaxScript)")
.count(),
1
);
assert!(script.find("window.MathJax =").unwrap() < script.find("appendChild").unwrap());
assert!(script.contains("displayOverflow: 'overflow'"));
assert!(script.contains("inlineMath: [['\\\\(', '\\\\)']]"));
assert!(script.contains("displayMath: [['\\\\[', '\\\\]']]"));
}
}
#![allow(unused)]
fn main() {
#[test]
fn view_styles_keep_headers_and_nested_choices_independent() {
let css = read_asset("theme/dada.css");
let options = css
.split_once(".lean-selector .view-options {")
.unwrap()
.1
.split_once('}')
.unwrap()
.0;
assert!(options.contains("margin-left:auto"));
// A nested diagram's radio button must not switch its enclosing Lean block.
// The selector reaches the block's own header, then changes only its children.
for pane in [".lean-source", ".lean-grammar", ".lean-markdown-body"] {
assert!(css.contains(&format!(
".lean-group:has(> .lean-selector input:is([value=\"lean\"], [value=\"rust\"]):checked) > {pane}"
)));
}
assert!(css.contains(
".heap-figure:has(input[value=\"facts\"]:checked) .heap-facts { display:block; }"
));
assert!(css.contains(
".heap-figure:has(input[value=\"facts\"]:checked) .heap-diagram { display:none; }"
));
for selector in [".lean-grammar", ".lean-source pre", ".heap-figure"] {
let declaration = css
.split_once(&format!("{selector} {{"))
.unwrap()
.1
.split_once('}')
.unwrap()
.0;
assert!(declaration.contains("overflow-x:auto"), "{selector}");
}
let mut book = json!({"items": [{"Chapter": {
"path": "local.md", "content": "{anchor}`local.identity`\n\n{anchor-ref}`local.identity`", "sub_items": []
}}]});
process(&mut book).unwrap();
let rendered = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert_eq!(rendered.matches("class=\"spec-shield\"").count(), 2);
assert!(rendered.contains("href=\"#claim-local.identity\""));
assert!(!rendered.contains("<img"));
assert!(!rendered.contains("src="));
assert!(
!css.contains("url("),
"shield styling must not fetch a remote badge"
);
}
}
Write an overbar inside a group, as in {\overline f}. The command must have an
opening brace immediately before it and a literal ASCII space immediately after
it. A tab or newline does not satisfy the space requirement. Longer command
names are not matches.
The lint checks raw Markdown, including literal TeX samples, and reports a
source path and line number for either violation. A repository test checks all
Markdown below v2/md/, including files outside the table of contents. This is
an adjacency check; it does not parse the TeX expression or balance its braces.
#![allow(unused)]
fn main() {
/// Require an opening group immediately before each overbar command and a
/// literal space immediately after it. Longer TeX control words are separate commands.
pub fn check_latex(source: &str, path: &str) -> Result<()> {
let overline = Regex::new(r"\\overline([^A-Za-z]|$)")?;
for matched in overline.captures_iter(source) {
let command = matched.get(0).expect("a regex match has a full capture");
let line = source[..command.start()]
.bytes()
.filter(|&byte| byte == b'\n')
.count()
+ 1;
ensure!(
source[..command.start()].ends_with('{') && &matched[1] == " ",
"{path}:{line}: LaTeX style: use {{\\overline f}}; the command must be immediately preceded by `{{` and immediately followed by a literal space"
);
}
Ok(())
}
}
#![allow(unused)]
fn main() {
#[test]
fn overbars_require_a_preceding_brace_and_following_literal_space() {
for source in [
r"\overline f,x",
r"{ \overline f}",
r"\overline{f}",
r"{\overline{f}}",
"{\\overline\tf}",
"{\\overline\nf}",
"{\\overline\r\nf}",
"{\\overline\u{a0}f}",
r"\overline {f}",
r"{\overline7}",
r"{\overline\alpha}",
r"{\overline}",
r"{\overline",
r"\overline",
] {
let error = check_latex(source, "state.md").unwrap_err().to_string();
assert!(error.contains("state.md:1:"), "{source:?}: {error}");
assert!(error.contains(r"use {\overline f}"), "{error}");
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn grouped_overbars_and_other_control_words_are_allowed() {
for source in [
r"{\overline f},x",
r"{\overline {f_1, f_2}}",
r"{\overline {\overline f}}",
r"{\overline \alpha}",
r"{\overline f} + {\overline g}",
r"\overlineSomething f",
r"\overlined f",
"No math here.",
] {
check_latex(source, "state.md").unwrap();
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn diagnostics_count_source_lines_including_unicode_and_crlf() {
let source = "# α\r\n{\\overline f}\r\n\r\n\\overline f";
let error = check_latex(source, "nested/chapter.md")
.unwrap_err()
.to_string();
assert!(error.starts_with("nested/chapter.md:4:"), "{error}");
}
}
#![allow(unused)]
fn main() {
#[test]
fn book_build_checks_math_directives_examples_and_literal_tex() {
for source in [
r"Inline \\(\overline f\\).",
"```{grammar} Heap.lean:Object\n\\overline f\n```",
"````{example} Heap.lean:integer_primitive\n\\overline f\n````",
"```latex\n\\overline f\n```",
] {
let mut book = json!({"items": [{"Chapter": {
"path": "intro.md", "content": "Introduction.", "sub_items": [
{"Chapter": {"path": "nested/state.md", "content": source, "sub_items": []}}
]
}}]});
let error = process(&mut book).unwrap_err().to_string();
assert!(error.contains("nested/state.md:"), "{error}");
assert!(error.contains(r"use {\overline f}"), "{error}");
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn all_book_markdown_follows_latex_conventions() -> Result<()> {
fn scan(directory: &Path, errors: &mut Vec<String>, count: &mut usize) -> Result<()> {
let mut entries = fs::read_dir(directory)
.with_context(|| format!("read {}", directory.display()))?
.collect::<std::io::Result<Vec<_>>>()?;
entries.sort_by_key(|entry| entry.path());
for entry in entries {
let path = entry.path();
if entry.file_type()?.is_dir() {
scan(&path, errors, count)?;
} else if path.extension().is_some_and(|extension| extension == "md") {
*count += 1;
let source = fs::read_to_string(&path)
.with_context(|| format!("read {}", path.display()))?;
if let Err(error) = check_latex(&source, &path.display().to_string()) {
errors.push(error.to_string());
}
}
}
Ok(())
}
let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("../md");
let mut errors = Vec::new();
let mut count = 0;
scan(&root, &mut errors, &mut count)?;
assert!(count > 0, "no book Markdown found under {}", root.display());
assert!(errors.is_empty(), "{}", errors.join("\n"));
Ok(())
}
}
Lean selections
A completed definition selects one or more named def, abbrev, structure,
or inductive declarations, in citation order, including their bodies.
Theorems, axioms, anonymous examples, and constructor-only citations are not
valid definition targets.
definitionmeta.lean.definitions.extraction
Extraction recognizes column-zero declarations with indented continuations.
Structures and inductives put where on their first line. Definitions may have
multiline signatures and a := body, a where body, or indented equation clauses.
Definition abbreviations may have an indented signature and := body.
The scanner masks comments and literal contents to find boundaries, then retains
the original source tokens. A matching word in a comment is not a declaration.
definitionmeta.lean.definitions.selection
A grammar selects inductive, structure, or abbrev declarations. Its type
names are unqualified; type abbreviations put := on their first line. Supported
column-zero mutual inductives can be selected individually, as specified by
refmeta.sources.exact_selection.
definitionmeta.syntax.grammar.declarations
A structured grammar has an ID, one or more :lean: citations, and authored
LaTeX. Surrounding prose defines its mathematical categories and notation.
definitionmeta.syntax.grammar.validation Citation lookup checks existence and supported declaration kinds. It does not parse an independent grammar language, resolve mathematical symbols, or establish correspondence with Lean.
#![allow(unused)]
fn main() {
/// Resolve a citation with the same declaration-kind checks as the renderer.
pub fn select(root: &Path, target: &str, kind: crate::units::UnitKind) -> Result<LeanSelection> {
use crate::units::UnitKind;
ensure!(
kind != UnitKind::FutureNote,
"future notes cannot have formalization citations"
);
let (source, name) = read_source(root, target)?;
let selected = match kind {
UnitKind::FutureNote => unreachable!("rejected above"),
UnitKind::Definition => extract_definition(&source, &name),
UnitKind::Theorem | UnitKind::Lemma => extract_theorem(&source, &name),
UnitKind::Example => extract_example(&source, &name),
UnitKind::Grammar => extract(&source, &name),
UnitKind::Judgment => extract(&source, &name).and_then(|declaration| {
ensure!(
declaration.starts_with("inductive "),
"judgment citation must select an inductive declaration"
);
Ok(declaration)
}),
UnitKind::Rule => {
let (name, case) = name
.rsplit_once('.')
.context("rule expects path:Judgment.constructor")?;
extract(&source, name).and_then(|declaration| extract_case(&declaration, case))
}
}
.with_context(|| target.to_owned())?;
let (file, _) = target
.rsplit_once(':')
.context("expected path:Declaration")?;
let mut relative = std::path::PathBuf::from(file);
if relative.extension().is_none() {
relative.set_extension("lean");
}
// read_source already checks canonical containment, including symlinks.
let path = root.join(relative).canonicalize()?;
Ok(LeanSelection {
path,
source,
selected,
})
}
}
#![allow(unused)]
fn main() {
fn extract_declaration(source: &str, name: &str, selection: Selection) -> Result<String> {
let simple_name = |component: &str| {
!component.is_empty() && component.chars().all(|c| c.is_alphanumeric() || c == '_')
};
if selection != Selection::Type {
ensure!(
name.split('.').all(simple_name),
"use a declaration name with nonempty identifier components separated by single dots"
);
} else {
ensure!(
simple_name(name),
"use a simple unqualified declaration name"
);
}
let masked = mask(source)?;
validate_mutual_groups(&masked)?;
let mut found = Vec::new();
let mut offset = 0;
let lines: Vec<_> = masked
.split_inclusive('\n')
.map(|line| {
let start = offset;
offset += line.len();
(start, line)
})
.collect();
let structure_field = regex::Regex::new(r"^[ \t]+[A-Za-z_][A-Za-z0-9_']*[ \t]*:(?:[^:=]|$)")?;
for (i, &(start, line)) in lines.iter().enumerate() {
let words: Vec<_> = line.split_whitespace().collect();
if selection == Selection::Definition {
let declaration: Vec<_> = words
.iter()
.copied()
.skip_while(|word| {
matches!(
*word,
"private" | "protected" | "noncomputable" | "unsafe" | "partial" | "nonrec"
)
})
.collect();
// Literal names are intentionally not resolved through namespaces.
// A same-named declaration of the wrong kind must not disappear
// from an otherwise ambiguous citation.
if declaration.get(1) == Some(&name)
&& matches!(
declaration.first(),
Some(
&"def"
| &"abbrev"
| &"structure"
| &"inductive"
| &"theorem"
| &"lemma"
| &"axiom"
| &"opaque"
| &"constant"
| &"class"
)
)
{
ensure!(
declaration.len() == words.len(),
"declaration modifiers are unsupported"
);
ensure!(
matches!(declaration.first(), Some(&"def" | &"abbrev" | &"structure" | &"inductive")),
"definition citations must select def, abbrev, structure, or inductive declarations"
);
}
}
if words.get(1) != Some(&name) {
continue;
}
let supported = match selection {
Selection::Theorem => words.first() == Some(&"theorem"),
Selection::Type => {
matches!(words.first(), Some(&"inductive" | &"structure" | &"abbrev"))
}
Selection::Definition => matches!(
words.first(),
Some(&"def" | &"inductive" | &"structure" | &"abbrev")
),
};
if !supported {
continue;
}
ensure!(
!line.starts_with(char::is_whitespace),
"selected Lean declarations must begin at column zero"
);
if let Some((_, previous)) = lines[..i].iter().rev().find(|(_, l)| !l.trim().is_empty()) {
ensure!(
!previous.trim_start().starts_with("@["),
"declaration attributes are unsupported"
);
}
if let Some((_, boundary)) = lines[i + 1..]
.iter()
.find(|(_, l)| !l.trim().is_empty() && !l.starts_with(char::is_whitespace))
{
let mut words = boundary.split_whitespace();
let first = words.next().unwrap_or("");
let mut word = first;
while matches!(
word,
"private" | "protected" | "noncomputable" | "unsafe" | "partial" | "nonrec"
) {
word = words.next().unwrap_or("");
}
ensure!(
(word == first
|| matches!(
word,
"inductive" | "structure" | "abbrev" | "def" | "theorem" | "instance"
))
&& matches!(
word,
"inductive"
| "structure"
| "abbrev"
| "def"
| "theorem"
| "lemma"
| "example"
| "instance"
| "end"
| "namespace"
| "section"
| "mutual"
| "variable"
| "open"
| "#check"
),
"unsupported declaration boundary `{}`; continuation lines must be indented",
boundary.trim()
);
}
let end = lines[i + 1..]
.iter()
.find(|(_, l)| !l.trim().is_empty() && !l.starts_with(char::is_whitespace))
.map(|(n, _)| *n)
.unwrap_or(source.len());
let body = &source[start..end];
let text = &body[..scan(body)?.content_end];
{
let code = &masked[start..end];
// A structure field such as `variables : Store` is not a command.
// Only exempt a bare, indented field name followed by a type colon;
// `variable (x : Nat)` and `def sibling := ...` remain commands.
let commands = command_pattern()?
.find_iter(code)
.filter(|command| {
words[0] != "structure"
|| !structure_field
.is_match(code[command.start()..].lines().next().unwrap_or(""))
})
.count();
ensure!(
commands == 1,
"selected declaration must contain no other commands, even when indented"
);
}
if selection == Selection::Theorem {
ensure!(
has_definition_body(&masked[start..end]),
"theorem must include its proof body (`:=`)"
);
} else if selection == Selection::Definition && words[0] == "def" {
ensure!(
has_named_definition_body(&masked[start..end])?,
"definition must include a body (`:=`, `where`, or indented equations with `=>`)"
);
} else if words[0] != "abbrev" {
ensure!(
line.contains("where"),
"declaration header must contain `where` on its first line"
);
} else {
if selection == Selection::Definition {
ensure!(
has_definition_body(&masked[start..end]),
"abbreviation must include a body (`:=`)"
);
} else {
ensure!(line.contains(":="), "abbreviation header must contain `:=`");
}
}
found.push(text.to_owned());
}
ensure!(
found.len() == 1,
"expected one supported declaration `{name}`, found {}",
found.len()
);
Ok(found.remove(0))
}
}
#![allow(unused)]
fn main() {
fn has_named_definition_body(code: &str) -> Result<bool> {
if has_definition_body(code) {
return Ok(true);
}
let mut delimiters = Vec::new();
for (offset, c) in code.char_indices() {
match c {
'(' | '{' | '[' | '⦃' => delimiters.push(c),
')' | '}' | ']' | '⦄' => {
delimiters.pop();
}
'w' if delimiters.is_empty()
&& !follows_identifier(code, offset)
&& code[offset..].starts_with("where")
&& !code[offset + "where".len()..]
.chars()
.next()
.is_some_and(|c| c.is_alphanumeric() || matches!(c, '_' | '\'')) =>
{
return Ok(true);
}
'|' if delimiters.is_empty()
&& code[..offset]
.rsplit_once('\n')
.is_some_and(|(_, prefix)| !prefix.is_empty() && prefix.trim().is_empty()) =>
{
let arm = code[offset..].lines().next().unwrap_or("");
ensure!(
arm.contains("=>"),
"equation arms must put `=>` on their first line"
);
return Ok(true);
}
_ => {}
}
}
Ok(false)
}
}
#![allow(unused)]
fn main() {
/// Select the complete declarations associated with an authored definition.
/// Citations name declarations literally; enclosing namespaces are not inferred.
pub fn definition_source(root: &Path, targets: &str) -> Result<String> {
let targets: Vec<_> = targets.split_whitespace().collect();
ensure!(
!targets.is_empty(),
"definition requires at least one opening-line citation"
);
let mut output = String::new();
for target in targets {
let (source, name) = read_source(root, target)?;
let declaration = extract_definition(&source, &name).with_context(|| target.to_owned())?;
output.push_str(&format!(
"<figcaption>{}</figcaption><pre><code class=\"language-lean\">{}</code></pre>",
crate::escape(target),
highlighted(&declaration)?
));
}
Ok(output)
}
}
#![allow(unused)]
fn main() {
#[test]
fn definition_blocks_select_multiple_complete_declarations_and_preserve_markdown() {
use pulldown_cmark::{Event, Parser, Tag};
let root = lean_fixtures();
let source = r"````{definition} Renderer:readSlot Renderer:Stored Renderer:AllocatedObject Renderer:State.initial Renderer:FieldName Renderer:VariableId Renderer:Slot
{anchor}`slot-lookup` Write **lookup** as \\(S(p)=s\\).
\\[
S(p)=s \iff \mathsf{readSlot}(S,p)=\mathsf{some}(s)
\\]
1. A variable selects a slot.
2. A missing place has no slot.
```{grammar} Renderer:Place
p ::= x
```
````";
let input = json!({"items": [
chapter("state.md", source),
chapter("operations.md", "See {anchor-ref}`slot-lookup`."),
]});
let mut first = input.clone();
let mut second = input;
mdbook_dada::process_with_lean(&mut first, Some(&root)).unwrap();
mdbook_dada::process_with_lean(&mut second, Some(&root)).unwrap();
assert_eq!(first, second, "selectors must be deterministic");
let output = first["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(output.contains("aria-label=\"Definition view\""));
assert!(!output.contains("class=\"block-label\">Definition</span>"));
assert!(output.contains("aria-label=\"definition: slot-lookup\""));
assert!(output.contains("lean-keyword\">def</span> readSlot"));
assert!(output.contains("elements[index]?"));
assert!(!output.contains("def</span> writeSlot"));
assert!(!output.contains("A write never creates"));
assert!(output.contains("lean-keyword\">def</span> Stored"));
assert!(output.contains("lean-keyword\">def</span> AllocatedObject"));
assert!(output.contains("lean-keyword\">def</span> State.initial"));
assert!(output.contains("lean-keyword\">abbrev</span> FieldName"));
assert!(output.contains("lean-keyword\">structure</span> VariableId"));
assert!(output.contains("lean-keyword\">inductive</span> Slot"));
assert_eq!(output.matches("class=\"math-display\"").count(), 2);
assert!(output.contains("class=\"math-inline\""));
let events: Vec<_> = Parser::new(output).collect();
assert!(events
.iter()
.any(|event| matches!(event, Event::Start(Tag::Strong))));
assert!(events
.iter()
.any(|event| matches!(event, Event::Start(Tag::List(Some(1))))));
assert!(first["items"][1]["Chapter"]["content"]
.as_str()
.unwrap()
.contains("state.html#claim-slot-lookup"));
let mut duplicate = json!({"items": [chapter("state.md", source), chapter("other.md", "{anchor}`slot-lookup`")]});
assert!(format!(
"{:#}",
mdbook_dada::process_with_lean(&mut duplicate, Some(&root)).unwrap_err()
)
.contains("duplicate anchor"));
}
}
#![allow(unused)]
fn main() {
#[test]
fn definition_blocks_reject_missing_wrong_kind_and_malformed_citations() {
let root = lean_fixtures();
for source in [
"```{definition}\nBody.\n```",
"```{definition}Renderer:State\nBody.\n```",
"```{definition} Renderer:State\n \n```",
"```{definition} Renderer:deallocVariable_requires_top\nBody.\n```",
"```{definition} Renderer:integer_primitive\nBody.\n```",
"```{definition} Renderer:Step.allocVariable\nBody.\n```",
"```{definition} Renderer:State Renderer:missing\nBody.\n```",
"```{definition} ../Renderer:State\nBody.\n```",
"```{definition} Missing:State\nBody.\n```",
] {
let mut book = json!({"items": [chapter("state.md", source)]});
let error = mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap_err();
assert!(format!("{error:#}").contains("state.md"), "{source}");
}
let mut no_root =
json!({"items": [chapter("state.md", "```{definition} Renderer:State\nBody.\n```")]});
assert!(process(&mut no_root).is_err());
let literal = "````text\n```{definition} Missing:nope\nBody.\n```\n````\n\n ```{definition} Missing:nope\n Body.\n ```";
let mut book = json!({"items": [chapter("literal.md", literal)]});
process(&mut book).unwrap();
assert_eq!(book["items"][0]["Chapter"]["content"], literal);
}
}
#![allow(unused)]
fn main() {
#[test]
fn definitions_select_complete_equations_structure_literals_and_multiline_bodies() {
let source = "namespace Outer\ndef State.initial : State Primitive :=\n .state FiniteMap.empty FiniteMap.empty\ndef readSlot : State Primitive → Place → Option Slot\n | .state _ variables, .variable id => variables.lookup id\n | .state objects _, .field id name => do\n let .aggregate fields ← objects.lookup id | none\n fields.lookup name\ndef empty : Store where\n entries := []\n uniqueKeys := by\n exact List.nodup_nil\nabbrev Value\n (α : Type) :=\n Option α\nend Outer\n";
assert_eq!(
extract_definition(source, "State.initial").unwrap(),
"def State.initial : State Primitive :=\n .state FiniteMap.empty FiniteMap.empty"
);
let read = extract_definition(source, "readSlot").unwrap();
assert!(read.contains(" | .state _ variables"));
assert!(read.ends_with(" fields.lookup name"));
assert!(!read.contains("def empty"));
assert!(extract_definition(source, "empty")
.unwrap()
.ends_with(" exact List.nodup_nil"));
assert!(extract_definition(source, "Value")
.unwrap()
.ends_with(" Option α"));
assert!(extract_definition(source, "initial").is_err());
assert!(extract_definition(source, "Outer.State.initial").is_err());
// The math-only grammar directive retains its original type contract.
assert!(extract(source, "readSlot").is_err());
assert!(extract(source, "Value").is_err());
for source in [
"structure Foo where\n n : Nat",
"inductive Foo where\n | zero\n | succ (previous : Foo)",
"abbrev Foo := Nat",
] {
assert_eq!(extract_definition(source, "Foo").unwrap(), source);
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn definition_selection_ignores_comment_and_literal_decoys() {
let source = r###"/- def selected := 0 /- def selected := 1 -/ -/
def text := r##"
def selected := 2
"##
def other := "
def selected := 3
"
-- def selected := 4
def selected : Nat :=
let text := "def selected := 5"
let c := '"'
6
def next := 7
"###;
let selected = extract_definition(source, "selected").unwrap();
assert!(selected.starts_with("def selected : Nat :=\n"));
assert!(selected.ends_with(" 6"));
assert!(selected.contains("let text"));
assert!(!selected.contains("def next"));
}
}
#![allow(unused)]
fn main() {
#[test]
fn definitions_reject_unsupported_incomplete_and_ambiguous_sources() {
for source in [
"theorem selected : True := by trivial",
"axiom selected : Nat",
"opaque selected : Nat := 0",
"example : Nat := 0",
"private def selected := 0",
"@[simp]\ndef selected := 0",
" def selected := 0",
"def selected : Nat",
"def selected (n : Nat := 0) : Nat",
"def selected : Nat -- := 0",
"def selected : Nat /- where -/",
"def selected : Nat :=\n0",
"def selected : Nat → Nat\n| n => n",
"def selected : Nat → Nat\n | n\n => n",
"def selected := 0\ntermination_by 0",
"def selected := 0\n def sibling := 1",
"def selected := 0\n theorem sibling : True := by trivial",
"def selected := 0\nmystery next",
"def selected := 0\nnamespace Nested\ndef selected := 1\nend Nested",
"namespace A\ndef selected := 0\nend A\nnamespace B\ndef selected := 1\nend B",
"namespace A\ndef selected := 0\nend A\nnamespace B\ntheorem selected : True := by trivial\nend B",
"namespace A\ndef selected := 0\nend A\nnamespace B\nprivate def selected := 1\nend B",
"mutual\ndef selected := 0\nend",
] {
assert!(extract_definition(source, "selected").is_err(), "{source}");
}
for name in [".selected", "selected.", "N..selected", "N:selected"] {
assert!(extract_definition(&format!("def {name} := 0"), name).is_err());
}
}
}
A judgment selects one named inductive declaration. Its authored LaTeX presents the judgment; selecting it does not generate mathematical rules automatically.
definitionmeta.math.rule.selection
A rule selects one Judgment.constructor and displays the inductive header and
that constructor’s complete source. It does not include sibling constructors.
The author supplies the mathematical premises, conclusion, and rule label.
The selector checks declaration kinds and constructor names. It does not
interpret binder types, classify premises, or require that the declaration’s
result is Prop.
#![allow(unused)]
fn main() {
/// Resolve a citation with the same declaration-kind checks as the renderer.
pub fn select(root: &Path, target: &str, kind: crate::units::UnitKind) -> Result<LeanSelection> {
use crate::units::UnitKind;
ensure!(
kind != UnitKind::FutureNote,
"future notes cannot have formalization citations"
);
let (source, name) = read_source(root, target)?;
let selected = match kind {
UnitKind::FutureNote => unreachable!("rejected above"),
UnitKind::Definition => extract_definition(&source, &name),
UnitKind::Theorem | UnitKind::Lemma => extract_theorem(&source, &name),
UnitKind::Example => extract_example(&source, &name),
UnitKind::Grammar => extract(&source, &name),
UnitKind::Judgment => extract(&source, &name).and_then(|declaration| {
ensure!(
declaration.starts_with("inductive "),
"judgment citation must select an inductive declaration"
);
Ok(declaration)
}),
UnitKind::Rule => {
let (name, case) = name
.rsplit_once('.')
.context("rule expects path:Judgment.constructor")?;
extract(&source, name).and_then(|declaration| extract_case(&declaration, case))
}
}
.with_context(|| target.to_owned())?;
let (file, _) = target
.rsplit_once(':')
.context("expected path:Declaration")?;
let mut relative = std::path::PathBuf::from(file);
if relative.extension().is_none() {
relative.set_extension("lean");
}
// read_source already checks canonical containment, including symlinks.
let path = root.join(relative).canonicalize()?;
Ok(LeanSelection {
path,
source,
selected,
})
}
}
#![allow(unused)]
fn main() {
fn extract_case(declaration: &str, case: &str) -> Result<String> {
ensure!(
!case.is_empty() && case.chars().all(|c| c.is_alphanumeric() || c == '_'),
"use a simple constructor name"
);
let masked = mask(declaration)?;
let header = declaration
.lines()
.next()
.context("missing declaration header")?;
ensure!(
header.starts_with("inductive "),
"rule citation must select an inductive constructor"
);
let mut offset = 0;
let mut candidates = Vec::new();
for line in masked.split_inclusive('\n') {
let trimmed = line.trim_start();
let indent = line.len() - trimmed.len();
if let Some(row) = trimmed.strip_prefix('|') {
let name = row
.trim_start()
.split(|c: char| c.is_whitespace() || matches!(c, ':' | '(' | '{' | '['))
.next()
.unwrap_or("");
candidates.push((offset, indent, name));
}
offset += line.len();
}
let indent = candidates
.iter()
.map(|(_, indent, _)| *indent)
.min()
.context("inductive has no constructors")?;
let cases: Vec<_> = candidates
.into_iter()
.filter(|(_, i, _)| *i == indent)
.collect();
let found: Vec<_> = cases
.iter()
.enumerate()
.filter(|(_, (_, _, n))| *n == case)
.collect();
ensure!(
found.len() == 1,
"expected one constructor `{case}`, found {}",
found.len()
);
let (index, (start, _, _)) = found[0];
let end = cases
.get(index + 1)
.map(|(start, _, _)| *start)
.unwrap_or(declaration.len());
// A comment introducing the next declaration is not part of this case.
let selected = &declaration[*start..end];
let selected = &selected[..scan(selected)?.content_end];
Ok(format!("{header}\n{selected}"))
}
}
#![allow(unused)]
fn main() {
/// Check source citations and pair authored LaTeX with those source excerpts.
/// No mathematical syntax is generated from, or compared with, the Lean source.
pub fn render_authored(
root: &Path,
targets: &str,
body: &str,
view: View,
group: &str,
) -> Result<String> {
let targets: Vec<_> = targets.split_whitespace().collect();
ensure!(!targets.is_empty(), "expected Lean citations on the directive opening line; use ```{{grammar}} path:Name with authored LaTeX in the body");
ensure!(
view == View::Grammar || targets.len() == 1,
"judgment and rule directives require exactly one opening-line citation"
);
ensure!(
!body.trim().is_empty(),
"authored math directive requires a LaTeX body"
);
let mut source = String::new();
for target in targets {
let (file, selected) = read_source(root, target)?;
let (name, case) = if view == View::Rule {
let (name, case) = selected
.rsplit_once('.')
.context("rule expects path:Judgment.constructor")?;
(name, Some(case))
} else {
(selected.as_str(), None)
};
let declaration = extract(&file, name).with_context(|| target.to_owned())?;
ensure!(
!matches!(view, View::Judgment | View::Rule) || declaration.starts_with("inductive "),
"judgment and rule citations must select inductive declarations"
);
let declaration = if let Some(case) = case {
extract_case(&declaration, case)?
} else {
declaration
};
source.push_str(&format!(
"<figcaption>{}</figcaption><pre><code class=\"language-lean\">{}</code></pre>",
crate::escape(target),
highlighted(&declaration)?
));
}
// Keep blank lines inside the raw HTML block so Markdown cannot reinterpret
// the authored TeX. Escaping also keeps TeX text from becoming HTML markup.
let tex = crate::escape(body.trim()).replace('\n', " ");
let rendered = format!("<div class=\"math-display\">\\[{tex}\\]</div>");
let label = match view {
View::Grammar => "Grammar",
View::Judgment => "Judgment",
View::Rule => "Rule",
};
Ok(selector(&rendered, &source, group, label))
}
}
#![allow(unused)]
fn main() {
#[test]
fn authored_judgments_and_rules_keep_tex_and_show_cited_source() {
let root = lean_fixtures();
let source = r"```{judgment} Renderer:Step
S \xrightarrow{op} S'
```
```{rule} Renderer.lean:Step.allocVariable
\frac{\mathrm{authorPremise}}{\mathrm{authorConclusion}}
```
";
let mut book = json!({"items": [chapter("ops.md", source)]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let html = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(html.contains(r"S \xrightarrow{op} S'"));
assert!(html.contains(r"\frac{\mathrm{authorPremise}}{\mathrm{authorConclusion}}"));
assert!(html.contains("Renderer:Step"));
assert!(html.contains("Renderer.lean:Step.allocVariable"));
assert!(html.contains("| allocVariable"));
let selected_rule = html.rsplit("class=\"lean-source\"").next().unwrap();
assert!(selected_rule.contains("| allocVariable"));
assert!(!selected_rule.contains("| deallocVariable"));
assert_eq!(html.matches("class=\"lean-selector\"").count(), 2);
assert_eq!(html.matches("> Rendered</label>").count(), 2);
assert_eq!(html.matches("> Lean</label>").count(), 2);
// Each selector's two choices share a group, but different blocks do not.
let names: Vec<_> = regex::Regex::new(r#"type="radio" name="([^"]+)""#)
.unwrap()
.captures_iter(html)
.map(|captures| captures[1].to_owned())
.collect();
assert_eq!(names.len(), 4);
assert_eq!(names[0], names[1]);
assert_eq!(names[2], names[3]);
assert_ne!(names[0], names[2]);
// Selecting either a middle or final case must exclude its neighbors, even
// when the judgment and operation have an explicit Primitive parameter.
let cases = [
"allocVariable",
"deallocVariable",
"createPrimitive",
"createAggregate",
"createArray",
];
for case in cases {
let source = format!("```{{rule}} Renderer:Step.{case}\nP\n```");
let mut book = json!({"items": [chapter("ops.md", &source)]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let html = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(html.contains("Operation Primitive"));
for candidate in cases {
assert_eq!(
html.contains(&format!("| {candidate}")),
candidate == case,
"case {case} must select only its own constructor"
);
}
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn authored_math_requires_one_opening_argument_and_a_body() {
let root = lean_fixtures();
for source in [
"```{rule}\nRenderer:Step.allocVariable\n\\frac{P}{Q}\n```",
"```{judgment}\nRenderer:Step\nS \\to S'\n```",
"```{rule} Renderer:Step.allocVariable\n```",
"```{judgment} Renderer:Step\n \n```",
"```{rule} Renderer:Step.allocVariable Renderer:Step.allocVariable\nP\n```",
"```{judgment}Renderer:Step\nP\n```",
] {
let mut book = json!({"items": [chapter("ops.md", source)]});
let error = mdbook_dada::process_with_lean(&mut book, Some(&root)).expect_err(source);
assert!(format!("{error:#}").contains("ops.md"), "{source}");
}
let mut book =
json!({"items": [chapter("ops.md", "```{rule} Renderer:Step.allocVariable\nP\n```")]});
assert!(
process(&mut book).is_err(),
"Lean selection requires a source root"
);
}
}
#![allow(unused)]
fn main() {
#[test]
fn authored_math_rejects_missing_or_wrong_kind_source_selections() {
let root = lean_fixtures();
for (kind, target) in [
("judgment", "Missing:Step"),
("judgment", "Renderer:Missing"),
("judgment", "Renderer:VariableId"),
("rule", "Renderer:Step.missing"),
("rule", "Renderer:Step"),
("rule", "Renderer:VariableId.index"),
("rule", "../Renderer:Step.allocVariable"),
] {
let mut book =
json!({"items": [chapter("ops.md", &format!("```{{{kind}}} {target}\nP\n```"))]});
let error = mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap_err();
let message = format!("{error:#}");
assert!(message.contains("ops.md"), "{kind} {target}");
if target.starts_with("Renderer:VariableId") {
assert!(
message.contains("must select inductive declarations"),
"{kind} {target}: {message}"
);
}
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn selects_a_case_without_interpreting_its_binders() {
let source = "inductive J : Nat → Prop where\n -- | decoy : J 0\n | first {n : Nat} (proof : Unknown n) :\n J (match n with\n | 0 => 0\n | k => k)\n | second : J 1\n";
let first = extract_case(source, "first").unwrap();
assert!(first.starts_with("inductive J : Nat → Prop where\n | first"));
assert!(first.contains("Unknown n"));
assert!(first.contains("| k => k"));
assert!(!first.contains("second"));
assert!(extract_case(source, "decoy").is_err());
assert!(!extract_case(
"inductive J where\n | r\n-- Next declaration documentation",
"r"
)
.unwrap()
.contains("documentation"));
assert!(extract_case(source, "k").is_err());
assert!(
extract_case("inductive J : Prop where\n | intro{n : Nat} : J", "intro")
.unwrap()
.contains("intro{n")
);
assert!(extract_case("inductive J where\n | r\n | r\n", "r").is_err());
}
}
A theorem or lemma selects exactly one named Lean theorem, including its
statement and := proof body. Definitions, axioms, and anonymous examples are
rejected as targets. Multiline statements use indented continuations; neighboring
declarations are excluded. The distinction between theorem and lemma is the
author’s presentation choice.
definitionmeta.math.theorem.validation The renderer checks source selection, not the proof. Lean compilation and correspondence review are separate: Lean checks the proof; review compares the statement’s assumptions, quantifiers, and conclusion with the authored claim.
definitionmeta.syntax.nesting Definition, theorem, lemma, and example bodies cannot nest any of those four block kinds.
#![allow(unused)]
fn main() {
/// Resolve a citation with the same declaration-kind checks as the renderer.
pub fn select(root: &Path, target: &str, kind: crate::units::UnitKind) -> Result<LeanSelection> {
use crate::units::UnitKind;
ensure!(
kind != UnitKind::FutureNote,
"future notes cannot have formalization citations"
);
let (source, name) = read_source(root, target)?;
let selected = match kind {
UnitKind::FutureNote => unreachable!("rejected above"),
UnitKind::Definition => extract_definition(&source, &name),
UnitKind::Theorem | UnitKind::Lemma => extract_theorem(&source, &name),
UnitKind::Example => extract_example(&source, &name),
UnitKind::Grammar => extract(&source, &name),
UnitKind::Judgment => extract(&source, &name).and_then(|declaration| {
ensure!(
declaration.starts_with("inductive "),
"judgment citation must select an inductive declaration"
);
Ok(declaration)
}),
UnitKind::Rule => {
let (name, case) = name
.rsplit_once('.')
.context("rule expects path:Judgment.constructor")?;
extract(&source, name).and_then(|declaration| extract_case(&declaration, case))
}
}
.with_context(|| target.to_owned())?;
let (file, _) = target
.rsplit_once(':')
.context("expected path:Declaration")?;
let mut relative = std::path::PathBuf::from(file);
if relative.extension().is_none() {
relative.set_extension("lean");
}
// read_source already checks canonical containment, including symlinks.
let path = root.join(relative).canonicalize()?;
Ok(LeanSelection {
path,
source,
selected,
})
}
}
#![allow(unused)]
fn main() {
fn extract_declaration(source: &str, name: &str, selection: Selection) -> Result<String> {
let simple_name = |component: &str| {
!component.is_empty() && component.chars().all(|c| c.is_alphanumeric() || c == '_')
};
if selection != Selection::Type {
ensure!(
name.split('.').all(simple_name),
"use a declaration name with nonempty identifier components separated by single dots"
);
} else {
ensure!(
simple_name(name),
"use a simple unqualified declaration name"
);
}
let masked = mask(source)?;
validate_mutual_groups(&masked)?;
let mut found = Vec::new();
let mut offset = 0;
let lines: Vec<_> = masked
.split_inclusive('\n')
.map(|line| {
let start = offset;
offset += line.len();
(start, line)
})
.collect();
let structure_field = regex::Regex::new(r"^[ \t]+[A-Za-z_][A-Za-z0-9_']*[ \t]*:(?:[^:=]|$)")?;
for (i, &(start, line)) in lines.iter().enumerate() {
let words: Vec<_> = line.split_whitespace().collect();
if selection == Selection::Definition {
let declaration: Vec<_> = words
.iter()
.copied()
.skip_while(|word| {
matches!(
*word,
"private" | "protected" | "noncomputable" | "unsafe" | "partial" | "nonrec"
)
})
.collect();
// Literal names are intentionally not resolved through namespaces.
// A same-named declaration of the wrong kind must not disappear
// from an otherwise ambiguous citation.
if declaration.get(1) == Some(&name)
&& matches!(
declaration.first(),
Some(
&"def"
| &"abbrev"
| &"structure"
| &"inductive"
| &"theorem"
| &"lemma"
| &"axiom"
| &"opaque"
| &"constant"
| &"class"
)
)
{
ensure!(
declaration.len() == words.len(),
"declaration modifiers are unsupported"
);
ensure!(
matches!(declaration.first(), Some(&"def" | &"abbrev" | &"structure" | &"inductive")),
"definition citations must select def, abbrev, structure, or inductive declarations"
);
}
}
if words.get(1) != Some(&name) {
continue;
}
let supported = match selection {
Selection::Theorem => words.first() == Some(&"theorem"),
Selection::Type => {
matches!(words.first(), Some(&"inductive" | &"structure" | &"abbrev"))
}
Selection::Definition => matches!(
words.first(),
Some(&"def" | &"inductive" | &"structure" | &"abbrev")
),
};
if !supported {
continue;
}
ensure!(
!line.starts_with(char::is_whitespace),
"selected Lean declarations must begin at column zero"
);
if let Some((_, previous)) = lines[..i].iter().rev().find(|(_, l)| !l.trim().is_empty()) {
ensure!(
!previous.trim_start().starts_with("@["),
"declaration attributes are unsupported"
);
}
if let Some((_, boundary)) = lines[i + 1..]
.iter()
.find(|(_, l)| !l.trim().is_empty() && !l.starts_with(char::is_whitespace))
{
let mut words = boundary.split_whitespace();
let first = words.next().unwrap_or("");
let mut word = first;
while matches!(
word,
"private" | "protected" | "noncomputable" | "unsafe" | "partial" | "nonrec"
) {
word = words.next().unwrap_or("");
}
ensure!(
(word == first
|| matches!(
word,
"inductive" | "structure" | "abbrev" | "def" | "theorem" | "instance"
))
&& matches!(
word,
"inductive"
| "structure"
| "abbrev"
| "def"
| "theorem"
| "lemma"
| "example"
| "instance"
| "end"
| "namespace"
| "section"
| "mutual"
| "variable"
| "open"
| "#check"
),
"unsupported declaration boundary `{}`; continuation lines must be indented",
boundary.trim()
);
}
let end = lines[i + 1..]
.iter()
.find(|(_, l)| !l.trim().is_empty() && !l.starts_with(char::is_whitespace))
.map(|(n, _)| *n)
.unwrap_or(source.len());
let body = &source[start..end];
let text = &body[..scan(body)?.content_end];
{
let code = &masked[start..end];
// A structure field such as `variables : Store` is not a command.
// Only exempt a bare, indented field name followed by a type colon;
// `variable (x : Nat)` and `def sibling := ...` remain commands.
let commands = command_pattern()?
.find_iter(code)
.filter(|command| {
words[0] != "structure"
|| !structure_field
.is_match(code[command.start()..].lines().next().unwrap_or(""))
})
.count();
ensure!(
commands == 1,
"selected declaration must contain no other commands, even when indented"
);
}
if selection == Selection::Theorem {
ensure!(
has_definition_body(&masked[start..end]),
"theorem must include its proof body (`:=`)"
);
} else if selection == Selection::Definition && words[0] == "def" {
ensure!(
has_named_definition_body(&masked[start..end])?,
"definition must include a body (`:=`, `where`, or indented equations with `=>`)"
);
} else if words[0] != "abbrev" {
ensure!(
line.contains("where"),
"declaration header must contain `where` on its first line"
);
} else {
if selection == Selection::Definition {
ensure!(
has_definition_body(&masked[start..end]),
"abbreviation must include a body (`:=`)"
);
} else {
ensure!(line.contains(":="), "abbreviation header must contain `:=`");
}
}
found.push(text.to_owned());
}
ensure!(
found.len() == 1,
"expected one supported declaration `{name}`, found {}",
found.len()
);
Ok(found.remove(0))
}
}
#![allow(unused)]
fn main() {
/// Select exactly one named theorem, preserving its statement and complete proof.
/// Theorem and lemma Markdown blocks share this source-selection contract.
pub fn theorem_source(root: &Path, target: &str) -> Result<String> {
let (source, name) = read_source(root, target)?;
let theorem = extract_theorem(&source, &name).with_context(|| target.to_owned())?;
Ok(format!(
"<figcaption>{}</figcaption><pre><code class=\"language-lean\">{}</code></pre>",
crate::escape(target),
highlighted(&theorem)?
))
}
}
#![allow(unused)]
fn main() {
fn chapter_roles(source: &str) -> Result<Vec<Role>> {
let protected = protect_math(source);
let mut found = roles(&protected)?;
for unit in units::parse(source, "chapter")? {
found.push(Role {
range: unit.range,
id: unit.id,
definition: true,
label: None,
lean: false,
});
}
for block in directive_blocks(&protected) {
if block
.info
.split_whitespace()
.next()
.is_some_and(|name| MarkdownDirective::parse(name).is_some() || name == "{future-note}")
{
// These bodies are Markdown; grammar, judgment, and rule bodies are TeX.
ensure!(
!directive_blocks(&block.body).iter().any(|nested| {
["{definition}", "{example}", "{theorem}", "{lemma}", "{future-note}"]
.iter()
.any(|name| nested.info.starts_with(name))
}),
"definition, example, theorem, and lemma directives cannot be nested within one another"
);
found.extend(roles(&protect_math(&block.body))?);
}
}
Ok(found)
}
}
#![allow(unused)]
fn main() {
#[test]
fn authored_theorems_show_the_exact_named_statement_and_proof() {
let root = lean_fixtures();
let source = r"```{theorem} Renderer.lean:deallocVariable_requires_top
A successful deallocation removes the top slot.
\\[
S \xrightarrow{\mathsf{deallocVariable}(x)} S' \implies \operatorname{top}(V) = x
\\]
**Proof outline.** Inspect the deallocation constructor's top-slot premise.
```";
let mut book = json!({"items": [chapter("invariants.md", source)]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let html = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(html.contains(r"\implies \operatorname{top}(V) = x"));
assert!(html.contains("Renderer.lean:deallocVariable_requires_top"));
assert!(html.contains("lean-keyword\">theorem</span> deallocVariable_requires_top"));
assert!(html.contains("cases step"));
assert!(!html.contains("theorem</span> deallocVariable_pops"));
assert_eq!(html.matches("class=\"lean-selector\"").count(), 1);
assert_eq!(html.matches("> Rendered</label>").count(), 1);
assert_eq!(html.matches("> Lean</label>").count(), 1);
}
}
#![allow(unused)]
fn main() {
#[test]
fn authored_theorems_select_literal_qualified_names() {
let root = lean_fixtures();
let source = r"```{theorem} Renderer:Transfer.preserves_count
Copying a list preserves its length.
\\[P \implies Q\\]
```";
let mut book = json!({"items": [chapter("moves.md", source)]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let html = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(html.contains("Renderer:Transfer.preserves_count"));
assert!(html.contains("lean-keyword\">theorem</span> Transfer.preserves_count"));
assert!(html.contains("copy_preserves_count written"));
assert!(!html.contains("theorem</span> Transfer.read"));
for citation in [
"Renderer:RendererFixture.Transfer.preserves_count",
"Renderer:Transfer..preserves_count",
"Renderer:.Transfer.preserves_count",
"Renderer:Transfer.preserves_count.",
] {
let source = format!("```{{theorem}} {citation}\nP\n```");
let mut book = json!({"items": [chapter("moves.md", &source)]});
assert!(mdbook_dada::process_with_lean(&mut book, Some(&root)).is_err());
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn authored_theorems_reject_wrong_kinds_and_malformed_directives() {
let root = lean_fixtures();
for source in [
"```{theorem}\nP\n```",
"```{theorem}Renderer:deallocVariable_requires_top\nP\n```",
"```{theorem} Renderer:deallocVariable_requires_top Renderer:deallocVariable_pops\nP\n```",
"```{theorem} Renderer:deallocVariable_requires_top\n \n```",
"```{theorem} Renderer:Step\nP\n```",
"```{theorem} Renderer:Step.allocVariable\nP\n```",
"```{theorem} Renderer:integer_primitive\nP\n```",
"```{theorem} Renderer:initialFields\nP\n```",
"```{theorem} Renderer:missing\nP\n```",
"```{theorem} Missing:theorem\nP\n```",
"```{theorem} ../Renderer:deallocVariable_requires_top\nP\n```",
] {
let mut book = json!({"items": [chapter("invariants.md", source)]});
let error = mdbook_dada::process_with_lean(&mut book, Some(&root)).expect_err(source);
assert!(format!("{error:#}").contains("invariants.md"), "{source}");
}
let mut missing_root = json!({"items": [chapter("invariants.md", "```{theorem} Renderer:deallocVariable_requires_top\nP\n```")]});
assert!(process(&mut missing_root).is_err());
let literal = "````text\n```{theorem} Missing:nope\nP\n```\n````";
let mut book = json!({"items": [chapter("invariants.md", literal)]});
process(&mut book).unwrap();
assert_eq!(book["items"][0]["Chapter"]["content"], literal);
}
}
#![allow(unused)]
fn main() {
#[test]
fn markdown_proof_blocks_reject_invalid_targets_and_all_nested_proof_kinds() {
let root = lean_fixtures();
for kind in ["theorem", "lemma"] {
for citation in [
"",
"Renderer:Step",
"Renderer:Step.allocVariable",
"Renderer:initialFields",
"Renderer:integer_primitive",
"Renderer:missing",
"Missing:proof",
"../Renderer:deallocVariable_requires_top",
"Renderer:deallocVariable_requires_top Renderer:deallocVariable_pops",
] {
let source = format!("```{{{kind}}} {citation}\nClaim.\n```");
let mut book = json!({"items": [chapter("proofs.md", &source)]});
assert!(
mdbook_dada::process_with_lean(&mut book, Some(&root)).is_err(),
"{source}"
);
}
for source in [
format!("```{{{kind}}}Renderer:deallocVariable_requires_top\nClaim.\n```"),
format!("```{{{kind}}} Renderer:deallocVariable_requires_top\n \n```"),
] {
let mut book = json!({"items": [chapter("proofs.md", &source)]});
assert!(
mdbook_dada::process_with_lean(&mut book, Some(&root)).is_err(),
"{source}"
);
}
}
let targets = [
("definition", "Renderer:readSlot"),
("example", "Renderer:integer_primitive"),
("theorem", "Renderer:deallocVariable_requires_top"),
("lemma", "Renderer:deallocVariable_requires_top"),
];
for (outer, outer_target) in targets {
for (inner, inner_target) in targets {
let source = format!(
"````{{{outer}}} {outer_target}\n```{{{inner}}} {inner_target}\nNested.\n```\n````"
);
let mut book = json!({"items": [chapter("proofs.md", &source)]});
let error = mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap_err();
assert!(
format!("{error:#}").contains("cannot be nested"),
"{source}"
);
}
}
let literal = "````text\n```{lemma} Missing:nope\nLiteral.\n```\n````";
let mut book = json!({"items": [chapter("proofs.md", literal)]});
process(&mut book).unwrap();
assert_eq!(book["items"][0]["Chapter"]["content"], literal);
}
}
#![allow(unused)]
fn main() {
#[test]
fn selects_complete_named_theorems_without_comment_or_string_decoys() {
let source = r#"-- theorem preserves : False := by sorry
def text := "theorem preserves : False := by sorry"
/- theorem preserves : False := by sorry -/
theorem preserves
(n : Nat)
(h : n = 0) : n = 0 := by
have same : n = 0 := h
exact same
theorem next : True := by trivial
"#;
let selected = extract_theorem(source, "preserves").unwrap();
assert!(selected.starts_with("theorem preserves\n"));
assert!(selected.ends_with(" exact same"));
assert!(!selected.contains("sorry"));
assert!(!selected.contains("theorem next"));
assert_eq!(
extract_theorem(source, "next").unwrap(),
"theorem next : True := by trivial"
);
assert!(extract(source, "preserves").is_err());
}
}
#![allow(unused)]
fn main() {
#[test]
fn rejects_wrong_kind_ambiguous_and_incomplete_theorem_selections() {
for source in [
"def selected : True := by trivial",
"axiom selected : True",
"example : True := by trivial",
"inductive selected : Prop where\n | intro",
"theorem selected : True := by trivial\ntheorem selected : True := by trivial",
"theorem selected : True",
"theorem selected (n : Nat := 0) : True",
"@[simp]\ntheorem selected : True := by trivial",
" theorem selected : True := by trivial",
"theorem selected : True := by\ntrivial",
"theorem selected : True := by trivial\n theorem next : True := by trivial",
"theorem selected : True := by trivial\n def next := 0",
] {
assert!(extract_theorem(source, "selected").is_err(), "{source}");
}
assert!(extract_theorem("theorem selected : True := by trivial", "missing").is_err());
assert!(extract_theorem("theorem selected : True := by trivial", "N.selected").is_err());
}
}
An example citation selects a region between standalone Lean comments
-- ANCHOR: name and -- ANCHOR_END: name. That region contains exactly one
anonymous example proof, with optional comments and whitespace. The example
and following command start at column zero; proof continuations are indented.
The closing marker cannot truncate the proof or hide another command. Markers
are excluded from displayed source. Their name is local to the file, not a
Lean declaration name or a book ID.
definitionmeta.syntax.example
A structured example has an ID, one :lean: citation, and an authored Markdown
body. Its header says Example and initially displays the rendered body.
definitionmeta.examples.markdown The body supports paragraphs, lists, links, code, explicit math, roles, and heap diagrams. Longer enclosing fences permit literal fenced examples inside it. The nesting restrictions still apply.
definitionmeta.examples.validation Missing, duplicate, or malformed regions, unsupported proof forms, malformed citations, and empty bodies fail the build. Selecting the test does not elaborate or run it.
#![allow(unused)]
fn main() {
fn extract_example(source: &str, name: &str) -> Result<String> {
ensure!(
valid_anchor_name(name),
"invalid Lean example anchor `{name}`"
);
let (masked, comments) = mask_and_comments(source)?;
let mut names = HashSet::new();
let mut open = None;
let mut selected = None;
for offset in comments {
let line_start = source[..offset].rfind('\n').map_or(0, |n| n + 1);
if !source[line_start..offset].trim().is_empty() {
continue;
}
let line_end = source[offset..]
.find('\n')
.map_or(source.len(), |n| offset + n);
let comment = source[offset + 2..line_end].trim();
let (end, anchor) = if let Some(anchor) = comment.strip_prefix("ANCHOR:") {
(false, anchor.trim())
} else if let Some(anchor) = comment.strip_prefix("ANCHOR_END:") {
(true, anchor.trim())
} else {
continue;
};
ensure!(
valid_anchor_name(anchor),
"invalid Lean example anchor `{anchor}`"
);
if end {
let (opened, start) = open.take().with_context(|| {
format!("Lean example anchor `{anchor}` ends without a matching start")
})?;
ensure!(
opened == anchor,
"Lean example anchor `{opened}` ends with mismatched `{anchor}`"
);
if anchor == name {
selected = Some((start..line_start, (line_end + 1).min(source.len())));
}
} else {
ensure!(open.is_none(), "nested Lean example anchor `{anchor}`");
ensure!(
names.insert(anchor),
"duplicate Lean example anchor `{anchor}`"
);
open = Some((anchor, (line_end + 1).min(source.len())));
}
}
if let Some((anchor, _)) = open {
anyhow::bail!("unterminated Lean example anchor `{anchor}`");
}
let (range, after) =
selected.with_context(|| format!("missing Lean example anchor `{name}`"))?;
if let Some(next) = masked[after..].lines().find(|line| !line.trim().is_empty()) {
ensure!(
!next.starts_with(char::is_whitespace),
"Lean example anchor `{name}` ends before an indented continuation; place the end marker after the complete example and start the next command at column zero"
);
}
let mut lines = masked[range.clone()]
.lines()
.filter(|line| !line.trim().is_empty());
let header = lines
.next()
.with_context(|| format!("Lean example anchor `{name}` is empty"))?;
let keyword = header
.split(|c: char| c.is_whitespace() || matches!(c, ':' | '(' | '{' | '['))
.next();
ensure!(
keyword == Some("example"),
"Lean example anchor `{name}` must contain a column-zero anonymous `example`"
);
ensure!(
lines.all(|line| line.starts_with(char::is_whitespace)),
"Lean example anchor `{name}` must contain exactly one `example`; continuation lines must be indented"
);
// Lean allows sibling commands to be indented. Indentation alone therefore
// cannot establish that a marked span contains only the selected example.
// This restricted source style excludes command declarations inside proofs.
let command = command_pattern()?;
let declaration_count = command.find_iter(&masked[range.clone()]).count();
let example_count = regex::Regex::new(r"\bexample\b")?
.find_iter(&masked[range.clone()])
.count();
ensure!(
declaration_count == 1 && example_count == 1,
"Lean example anchor `{name}` must contain exactly one `example` and no other commands, even when indented"
);
ensure!(
has_definition_body(&masked[range.clone()]),
"Lean example anchor `{name}` must include the example body (`:=`)"
);
// Preserve code indentation while excluding surrounding blank lines and the
// anchor markers. Comments documenting the example remain visible.
Ok(source[range].trim_matches(['\n', '\r']).to_owned())
}
}
#![allow(unused)]
fn main() {
/// Select a marked anonymous Lean example and render its cited source.
/// This checks the marker structure, not Lean elaboration or prose agreement.
pub fn example_source(root: &Path, target: &str) -> Result<String> {
let (source, anchor) = read_source(root, target)?;
let example = extract_example(&source, &anchor).with_context(|| target.to_owned())?;
Ok(format!(
"<figcaption>{}</figcaption><pre><code class=\"language-lean\">{}</code></pre>",
crate::escape(target),
highlighted(&example)?
))
}
}
#![allow(unused)]
fn main() {
fn render(
source: &str,
path: &str,
anchors: &BTreeMap<String, String>,
lean_root: Option<&Path>,
project_root: Option<&Path>,
scope: &str,
definition_label: &str,
) -> Result<String> {
let protected = protect_math(source);
let source = protected.as_str();
let structured_units = units::parse(source, path)?;
let mut edits = vec![];
for role in roles(source)? {
let rendered = render_role(&role, path, anchors, definition_label)?;
edits.push((role.range, rendered));
}
for (event, range) in Parser::new(source).into_offset_iter() {
if matches!(event, Event::Start(Tag::Paragraph)) {
ensure!(
!source[range.clone()].starts_with("{example} "),
"the paragraph {{example}} marker has been replaced: use a fenced ```{{example}} path:anchor with a Markdown body and a Lean test, or label an unfinished scenario as informational"
);
if source[range.clone()].starts_with("{informational} ") {
edits.push((
range.start..range.start + "{informational}".len(),
"<span class=\"informational-label\">Informational</span>".to_owned(),
));
}
}
}
for block in directive_blocks(source) {
if let Some(unit) = structured_units
.iter()
.find(|unit| unit.range.start == block.range.start)
{
for dependency in &unit.uses {
ensure!(
anchors.contains_key(dependency),
"unknown unit dependency `{dependency}`"
);
}
edits.push((
block.range,
render_unit(unit, path, anchors, lean_root, project_root)?,
));
continue;
}
let start = block.range.start;
let kind = block.info;
let facts = block.body;
let (directive, argument) = kind.split_once(char::is_whitespace).unwrap_or((&kind, ""));
ensure!(
![
"{heap}",
"{grammar}",
"{rule}",
"{judgment}",
"{definition}",
"{theorem}",
"{lemma}",
"{example}",
"{future-note}"
]
.iter()
.any(|name| directive.starts_with(name) && directive != *name),
"separate the directive name and citation with whitespace"
);
ensure!(!matches!(directive, "{lean.type}" | "{lean.judgment}" | "{lean.rule}"),
"{directive} has been replaced: use ```{{grammar}} path:Name, ```{{judgment}} path:Name, or ```{{rule}} path:Name.case with authored LaTeX in the body");
let id = format!("{scope}-{start}");
if let Some(markdown) = MarkdownDirective::parse(directive) {
let name = markdown.name();
let label = markdown.label();
let citations = argument.split_whitespace().count();
if matches!(markdown, MarkdownDirective::Definition) {
ensure!(
citations > 0,
"definition requires at least one opening-line citation"
);
} else {
ensure!(
citations == 1,
"{name} requires exactly one opening-line citation"
);
}
ensure!(!facts.trim().is_empty(), "{name} requires a Markdown body");
let root =
lean_root.context("Lean directives require preprocessor.dada.lean-source")?;
let lean_source = match markdown {
MarkdownDirective::Definition => lean::definition_source(root, argument)?,
MarkdownDirective::Example => lean::example_source(root, argument.trim())?,
MarkdownDirective::Theorem | MarkdownDirective::Lemma => {
lean::theorem_source(root, argument.trim())?
}
};
let heading_label = if matches!(markdown, MarkdownDirective::Example) {
"example"
} else {
markdown.definition_label()
};
let (heading, body) = markdown_heading(&facts, path, anchors, heading_label)?;
ensure!(
!body.trim().is_empty(),
"{name} requires a Markdown body after its heading anchors"
);
let body = render(
body,
path,
anchors,
lean_root,
project_root,
&id,
markdown.definition_label(),
)?;
let selector = selector_header(
label,
(!heading.is_empty()).then_some(heading.as_str()),
&format!("{name}-{id}"),
"rendered",
"Lean",
);
// Blank lines terminate raw HTML blocks so mdBook renders the body
// as Markdown, including its explicit math delimiters and proof prose.
edits.push((block.range, format!(
"\n<figure class=\"lean-declaration lean-group lean-markdown lean-{name}\">{selector}<div class=\"lean-markdown-body\">\n\n{}\n\n</div><div class=\"lean-source\">{lean_source}</div></figure>\n\n",
body.trim_matches('\n')
)));
continue;
}
let view = match directive {
"{grammar}" => Some(lean::View::Grammar),
"{judgment}" => Some(lean::View::Judgment),
"{rule}" => Some(lean::View::Rule),
_ => None,
};
if let Some(view) = view {
let root =
lean_root.context("Lean directives require preprocessor.dada.lean-source")?;
edits.push((
block.range,
format!(
"\n{}\n",
lean::render_authored(root, argument.trim(), &facts, view, &id)?
),
));
continue;
}
ensure!(
argument.trim().is_empty(),
"{directive} does not accept opening-line arguments"
);
let graph = graph::render(&facts)?;
let selector = selector_header("Diagram", None, &format!("heap-{id}"), "rendered", "Facts");
let source = escape(&facts).replace('\n', " ");
edits.push((block.range, format!("\n<figure class=\"heap-figure\">{selector}{graph}<pre class=\"heap-facts\"><code>{source}</code></pre></figure>\n")));
}
edits.sort_by_key(|(range, _)| range.start);
let mut result = String::new();
let mut end = 0;
for (range, replacement) in edits {
ensure!(range.start >= end, "overlapping markup");
result.push_str(&source[end..range.start]);
result.push_str(&replacement);
end = range.end;
}
result.push_str(&source[end..]);
Ok(result)
}
}
#![allow(unused)]
fn main() {
fn chapter_roles(source: &str) -> Result<Vec<Role>> {
let protected = protect_math(source);
let mut found = roles(&protected)?;
for unit in units::parse(source, "chapter")? {
found.push(Role {
range: unit.range,
id: unit.id,
definition: true,
label: None,
lean: false,
});
}
for block in directive_blocks(&protected) {
if block
.info
.split_whitespace()
.next()
.is_some_and(|name| MarkdownDirective::parse(name).is_some() || name == "{future-note}")
{
// These bodies are Markdown; grammar, judgment, and rule bodies are TeX.
ensure!(
!directive_blocks(&block.body).iter().any(|nested| {
["{definition}", "{example}", "{theorem}", "{lemma}", "{future-note}"]
.iter()
.any(|name| nested.info.starts_with(name))
}),
"definition, example, theorem, and lemma directives cannot be nested within one another"
);
found.extend(roles(&protect_math(&block.body))?);
}
}
Ok(found)
}
}
#![allow(unused)]
fn main() {
#[test]
fn linked_examples_preserve_native_markdown_and_select_one_lean_test() {
use pulldown_cmark::{Event, Parser, Tag};
let root = lean_fixtures();
let source = r"Before.
````{example} Renderer:integer_primitive
**Create an integer.** See [the state](state.md).
1. Allocate `x`.
2. Create the value.
```text
createPrimitive(22, x)
```
After the operation, the payload is \\(22\\).
````
After.
";
let mut book = json!({"items": [chapter("examples.md", source)]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let output = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(output.contains("aria-label=\"Example view\""));
assert!(output.contains("Renderer:integer_primitive"));
assert!(output.contains("Step Int allocated (.createPrimitive 22 x) created"));
assert!(!output.contains("createAggregate"));
assert!(!output.contains("ANCHOR_END"));
assert!(output.contains("<span class=\"math-inline\">\(22\)</span>"));
// The HTML wrapper must leave the authored body to mdBook's Markdown parser.
let events: Vec<_> = Parser::new(output).collect();
assert!(events
.iter()
.any(|e| matches!(e, Event::Start(Tag::Strong))));
assert!(events
.iter()
.any(|e| matches!(e, Event::Start(Tag::List(Some(1))))));
assert!(events.iter().any(
|e| matches!(e, Event::Start(Tag::Link { dest_url, .. }) if dest_url.as_ref() == "state.md")
));
assert!(events
.iter()
.any(|e| matches!(e, Event::Start(Tag::CodeBlock(_)))));
assert!(events
.iter()
.any(|e| matches!(e, Event::Text(text) if text.as_ref() == "After.")));
let mut indented = json!({"items": [chapter("examples.md", "```{example} Renderer:integer_primitive\n createPrimitive(22, x)\n```")]});
mdbook_dada::process_with_lean(&mut indented, Some(&root)).unwrap();
let output = indented["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(Parser::new(output).any(|e| matches!(
e,
Event::Start(Tag::CodeBlock(pulldown_cmark::CodeBlockKind::Indented))
)));
}
}
#![allow(unused)]
fn main() {
#[test]
fn linked_example_bodies_index_anchors_and_scope_nested_selectors() {
let root = lean_fixtures();
let example = r"````{example} Renderer:nested_variables
See {anchor-ref}`outer`.
{anchor}`inner` The inner scope is removed.
```{heap}
vars = variables()
vars.x = uninitialized()
```
```{grammar} Renderer:Slot
s ::= \bot
```
````";
let mut book = json!({"items": [
chapter("intro.md", "{anchor}`outer` See {anchor-ref}`inner`."),
chapter("examples/scopes.md", example),
chapter("examples/another.md", &example.replace("{anchor}`inner`", "{anchor-ref}`inner`"))
]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let text = book["items"][1]["Chapter"]["content"].as_str().unwrap();
assert!(text.contains("../intro.html#claim-outer"));
assert!(text.contains("id=\"claim-inner\""));
assert!(text.contains("<svg"));
assert!(text.contains("math-display"));
assert!(book["items"][0]["Chapter"]["content"]
.as_str()
.unwrap()
.contains("examples/scopes.html#claim-inner"));
let all = book.to_string();
let names: Vec<_> = regex::Regex::new(r#"type="radio" name="([^"]+)""#)
.unwrap()
.captures_iter(text)
.map(|c| c[1].to_owned())
.collect();
assert_eq!(names.len(), 6);
assert_eq!(
names
.iter()
.collect::<std::collections::BTreeSet<_>>()
.len(),
3
);
assert!(all.contains("another.md"));
let mut duplicate =
json!({"items": [chapter("a.md", example), chapter("b.md", "{anchor}`inner`")]});
assert!(format!(
"{:#}",
mdbook_dada::process_with_lean(&mut duplicate, Some(&root)).unwrap_err()
)
.contains("duplicate anchor"));
}
}
#![allow(unused)]
fn main() {
#[test]
fn linked_examples_fail_on_invalid_citations_bodies_or_nesting() {
let root = lean_fixtures();
for source in [
"```{example}\nBody.\n```",
"```{example}Renderer:integer_primitive\nBody.\n```",
"```{example} Renderer:integer_primitive Renderer:empty_array\nBody.\n```",
"```{example} Renderer:integer_primitive\n \n```",
"```{example} Renderer:missing\nBody.\n```",
"```{example} Renderer:Step\nBody.\n```",
"```{example} ../Renderer:integer_primitive\nBody.\n```",
"````{example} Renderer:integer_primitive\n```{example} Renderer:empty_array\nNested.\n```\n````",
] {
let mut book = json!({"items": [chapter("examples.md", source)]});
let error = mdbook_dada::process_with_lean(&mut book, Some(&root)).expect_err(source);
assert!(format!("{error:#}").contains("examples.md"), "{source}");
}
let mut missing_root = json!({"items": [chapter("examples.md", "```{example} Renderer:integer_primitive\nBody.\n```")]});
assert!(process(&mut missing_root).is_err());
let literal = "````text\n```{example} Missing:nope\nLiteral.\n```\n````\n\n ```{example} Missing:nope\n Literal.\n ```";
let mut book = json!({"items": [chapter("examples.md", literal)]});
process(&mut book).unwrap();
assert_eq!(book["items"][0]["Chapter"]["content"], literal);
}
}
#![allow(unused)]
fn main() {
#[test]
fn ignores_anchor_decoys_in_strings_block_comments_and_inline_comments() {
let source = r#"/-
-- ANCHOR: absent
/- -- ANCHOR_END: mismatched -/
-- ANCHOR: actual
-/
def text := "
-- ANCHOR_END: absent
-- ANCHOR: actual
"
def inline := 0 -- ANCHOR: actual
-- A comment containing -- ANCHOR: actual
-- ANCHOR: actual
example : "-- ANCHOR_END: actual" = "-- ANCHOR_END: actual" := by
rfl
-- ANCHOR_END: actual
"#;
let example = extract_example(source, "actual").unwrap();
assert!(example.starts_with("example :"));
assert!(example.contains(" rfl"));
assert!(extract_example(source, "absent").is_err());
}
}
#![allow(unused)]
fn main() {
#[test]
fn requires_one_complete_anonymous_example() {
for (body, message) in [
("", "empty"),
("-- only a comment\n/- no proof -/", "empty"),
("def test := 0", "anonymous `example`"),
(" example : True := by trivial", "column-zero"),
(
"example : True := by trivial\nexample : True := by trivial",
"exactly one",
),
(
"example : True := by trivial\ndef extra := 0",
"exactly one",
),
(
"example : True := by trivial\n example : True := by trivial",
"exactly one",
),
(
"example : True := by trivial\n def extra := 0",
"exactly one",
),
(
"example : True := by trivial\n private theorem extra : True := by trivial",
"exactly one",
),
("example : True := by\ntrivial", "indented"),
("example : True", "example body"),
("example (n : Nat := 0) : n = n", "example body"),
("example : \"untrusted := text\" = \"text\"", "example body"),
] {
let source = format!("-- ANCHOR: test\n{body}\n-- ANCHOR_END: test\n");
let error = extract_example(&source, "test").unwrap_err().to_string();
assert!(error.contains(message), "{body:?}: {error}");
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn rejects_end_markers_that_cut_off_a_proof_continuation() {
for suffix in [" trivial", "\n-- proof continues\n/- more -/\n trivial"] {
let source =
format!("-- ANCHOR: test\nexample : True := by\n-- ANCHOR_END: test\n{suffix}\n");
let error = extract_example(&source, "test").unwrap_err().to_string();
assert!(error.contains("ends before an indented continuation"));
}
let complete = "-- ANCHOR: test\nexample : True := by\n trivial\n-- ANCHOR_END: test\n-- Next command\ndef next := 0\n";
assert!(extract_example(complete, "test").is_ok());
}
}
Citations name files relative to the configured Lean source root and may omit
.lean. Subdirectories are allowed; escaping the root, including through a
symlink, is rejected. Source views identify each citation and retain its selected
text. Imports, namespaces, and section variables remain in the retained source
context; an excerpt is not a standalone Lean file.
Definition and theorem names may contain dots when that exact name is written in the declaration. The selector does not infer namespace qualification.
definitionmeta.lean.definitions.errors Missing files, missing or ambiguous declarations, unsupported extraction forms, and wrong kinds fail with the citation and target identified. A failed selection is not silently omitted or presented as complete.
definitionmeta.math.citations.validation Directive argument counts and nonempty bodies are also checked. These are syntactic checks; they establish neither mathematical correspondence nor proofs.
definitionmeta.math.unsupported Unsupported source forms need an extractor extension or a source change before citation. Attributes, declaration modifiers, nested mutual groups, and nested commands within a selected declaration are unsupported. New authored LaTeX needs no corresponding Lean-to-LaTeX translation rule.
#![allow(unused)]
fn main() {
fn read_source(root: &Path, target: &str) -> Result<(String, String)> {
let (file, name) = target
.rsplit_once(':')
.context("expected path:Declaration")?;
let mut relative = std::path::PathBuf::from(file);
ensure!(
!file.is_empty()
&& relative
.components()
.all(|c| matches!(c, Component::Normal(_))),
"Lean path must be relative without traversal"
);
if relative.extension().is_none() {
relative.set_extension("lean");
}
ensure!(
relative.extension().is_some_and(|e| e == "lean"),
"expected a .lean file"
);
let canonical_root = root.canonicalize().context("Lean source directory")?;
let path = canonical_root
.join(&relative)
.canonicalize()
.with_context(|| format!("Lean file {file}"))?;
ensure!(
path.starts_with(&canonical_root),
"Lean source escapes configured directory"
);
let source = std::fs::read_to_string(path)?;
Ok((source, name.to_owned()))
}
}
#![allow(unused)]
fn main() {
fn extract_declaration(source: &str, name: &str, selection: Selection) -> Result<String> {
let simple_name = |component: &str| {
!component.is_empty() && component.chars().all(|c| c.is_alphanumeric() || c == '_')
};
if selection != Selection::Type {
ensure!(
name.split('.').all(simple_name),
"use a declaration name with nonempty identifier components separated by single dots"
);
} else {
ensure!(
simple_name(name),
"use a simple unqualified declaration name"
);
}
let masked = mask(source)?;
validate_mutual_groups(&masked)?;
let mut found = Vec::new();
let mut offset = 0;
let lines: Vec<_> = masked
.split_inclusive('\n')
.map(|line| {
let start = offset;
offset += line.len();
(start, line)
})
.collect();
let structure_field = regex::Regex::new(r"^[ \t]+[A-Za-z_][A-Za-z0-9_']*[ \t]*:(?:[^:=]|$)")?;
for (i, &(start, line)) in lines.iter().enumerate() {
let words: Vec<_> = line.split_whitespace().collect();
if selection == Selection::Definition {
let declaration: Vec<_> = words
.iter()
.copied()
.skip_while(|word| {
matches!(
*word,
"private" | "protected" | "noncomputable" | "unsafe" | "partial" | "nonrec"
)
})
.collect();
// Literal names are intentionally not resolved through namespaces.
// A same-named declaration of the wrong kind must not disappear
// from an otherwise ambiguous citation.
if declaration.get(1) == Some(&name)
&& matches!(
declaration.first(),
Some(
&"def"
| &"abbrev"
| &"structure"
| &"inductive"
| &"theorem"
| &"lemma"
| &"axiom"
| &"opaque"
| &"constant"
| &"class"
)
)
{
ensure!(
declaration.len() == words.len(),
"declaration modifiers are unsupported"
);
ensure!(
matches!(declaration.first(), Some(&"def" | &"abbrev" | &"structure" | &"inductive")),
"definition citations must select def, abbrev, structure, or inductive declarations"
);
}
}
if words.get(1) != Some(&name) {
continue;
}
let supported = match selection {
Selection::Theorem => words.first() == Some(&"theorem"),
Selection::Type => {
matches!(words.first(), Some(&"inductive" | &"structure" | &"abbrev"))
}
Selection::Definition => matches!(
words.first(),
Some(&"def" | &"inductive" | &"structure" | &"abbrev")
),
};
if !supported {
continue;
}
ensure!(
!line.starts_with(char::is_whitespace),
"selected Lean declarations must begin at column zero"
);
if let Some((_, previous)) = lines[..i].iter().rev().find(|(_, l)| !l.trim().is_empty()) {
ensure!(
!previous.trim_start().starts_with("@["),
"declaration attributes are unsupported"
);
}
if let Some((_, boundary)) = lines[i + 1..]
.iter()
.find(|(_, l)| !l.trim().is_empty() && !l.starts_with(char::is_whitespace))
{
let mut words = boundary.split_whitespace();
let first = words.next().unwrap_or("");
let mut word = first;
while matches!(
word,
"private" | "protected" | "noncomputable" | "unsafe" | "partial" | "nonrec"
) {
word = words.next().unwrap_or("");
}
ensure!(
(word == first
|| matches!(
word,
"inductive" | "structure" | "abbrev" | "def" | "theorem" | "instance"
))
&& matches!(
word,
"inductive"
| "structure"
| "abbrev"
| "def"
| "theorem"
| "lemma"
| "example"
| "instance"
| "end"
| "namespace"
| "section"
| "mutual"
| "variable"
| "open"
| "#check"
),
"unsupported declaration boundary `{}`; continuation lines must be indented",
boundary.trim()
);
}
let end = lines[i + 1..]
.iter()
.find(|(_, l)| !l.trim().is_empty() && !l.starts_with(char::is_whitespace))
.map(|(n, _)| *n)
.unwrap_or(source.len());
let body = &source[start..end];
let text = &body[..scan(body)?.content_end];
{
let code = &masked[start..end];
// A structure field such as `variables : Store` is not a command.
// Only exempt a bare, indented field name followed by a type colon;
// `variable (x : Nat)` and `def sibling := ...` remain commands.
let commands = command_pattern()?
.find_iter(code)
.filter(|command| {
words[0] != "structure"
|| !structure_field
.is_match(code[command.start()..].lines().next().unwrap_or(""))
})
.count();
ensure!(
commands == 1,
"selected declaration must contain no other commands, even when indented"
);
}
if selection == Selection::Theorem {
ensure!(
has_definition_body(&masked[start..end]),
"theorem must include its proof body (`:=`)"
);
} else if selection == Selection::Definition && words[0] == "def" {
ensure!(
has_named_definition_body(&masked[start..end])?,
"definition must include a body (`:=`, `where`, or indented equations with `=>`)"
);
} else if words[0] != "abbrev" {
ensure!(
line.contains("where"),
"declaration header must contain `where` on its first line"
);
} else {
if selection == Selection::Definition {
ensure!(
has_definition_body(&masked[start..end]),
"abbreviation must include a body (`:=`)"
);
} else {
ensure!(line.contains(":="), "abbreviation header must contain `:=`");
}
}
found.push(text.to_owned());
}
ensure!(
found.len() == 1,
"expected one supported declaration `{name}`, found {}",
found.len()
);
Ok(found.remove(0))
}
}
#![allow(unused)]
fn main() {
/// Resolve a citation with the same declaration-kind checks as the renderer.
pub fn select(root: &Path, target: &str, kind: crate::units::UnitKind) -> Result<LeanSelection> {
use crate::units::UnitKind;
ensure!(
kind != UnitKind::FutureNote,
"future notes cannot have formalization citations"
);
let (source, name) = read_source(root, target)?;
let selected = match kind {
UnitKind::FutureNote => unreachable!("rejected above"),
UnitKind::Definition => extract_definition(&source, &name),
UnitKind::Theorem | UnitKind::Lemma => extract_theorem(&source, &name),
UnitKind::Example => extract_example(&source, &name),
UnitKind::Grammar => extract(&source, &name),
UnitKind::Judgment => extract(&source, &name).and_then(|declaration| {
ensure!(
declaration.starts_with("inductive "),
"judgment citation must select an inductive declaration"
);
Ok(declaration)
}),
UnitKind::Rule => {
let (name, case) = name
.rsplit_once('.')
.context("rule expects path:Judgment.constructor")?;
extract(&source, name).and_then(|declaration| extract_case(&declaration, case))
}
}
.with_context(|| target.to_owned())?;
let (file, _) = target
.rsplit_once(':')
.context("expected path:Declaration")?;
let mut relative = std::path::PathBuf::from(file);
if relative.extension().is_none() {
relative.set_extension("lean");
}
// read_source already checks canonical containment, including symlinks.
let path = root.join(relative).canonicalize()?;
Ok(LeanSelection {
path,
source,
selected,
})
}
}
#![allow(unused)]
fn main() {
fn highlighted(declaration: &str) -> Result<String> {
let masked = mask(declaration)?;
let keywords = regex::Regex::new(
r"\b(inductive|structure|abbrev|def|theorem|where|deriving|example|by|let|have|show|exact)\b",
)?;
let mut html = String::new();
let mut last = 0;
for m in keywords.find_iter(&masked) {
html.push_str(&crate::escape(&declaration[last..m.start()]));
html.push_str(&format!(
"<span class=\"lean-keyword\">{}</span>",
&declaration[m.range()]
));
last = m.end();
}
html.push_str(&crate::escape(&declaration[last..]));
Ok(html.replace('\n', " "))
}
}
#![allow(unused)]
fn main() {
#[test]
fn authored_grammar_rejects_invalid_citations_and_missing_bodies() {
let root = lean_fixtures();
for target in [
"Missing:Place",
"Renderer:Missing",
"Renderer:Step.allocVariable",
"Renderer:allocVariable_contents",
"../Renderer:Place",
"Renderer:Object Renderer:Missing",
] {
let mut book =
json!({"items": [chapter("state.md", &format!("```{{grammar}} {target}\nP\n```"))]});
let error = mdbook_dada::process_with_lean(&mut book, Some(&root)).expect_err(target);
assert!(format!("{error:#}").contains("state.md"), "{target}");
}
for source in [
"```{grammar} Renderer:Object\n```",
"```{grammar} Renderer:Object\n \n```",
"```{grammar}Renderer:Object\nP\n```",
] {
let mut book = json!({"items": [chapter("state.md", source)]});
let error = mdbook_dada::process_with_lean(&mut book, Some(&root)).expect_err(source);
assert!(format!("{error:#}").contains("state.md"), "{source}");
}
let mut book =
json!({"items": [chapter("state.md", "```{grammar} Renderer:Slot\ns ::= r\n```")]});
assert!(
process(&mut book).is_err(),
"Lean citations require a source root"
);
}
}
#![allow(unused)]
fn main() {
#[test]
fn linked_examples_fail_on_invalid_citations_bodies_or_nesting() {
let root = lean_fixtures();
for source in [
"```{example}\nBody.\n```",
"```{example}Renderer:integer_primitive\nBody.\n```",
"```{example} Renderer:integer_primitive Renderer:empty_array\nBody.\n```",
"```{example} Renderer:integer_primitive\n \n```",
"```{example} Renderer:missing\nBody.\n```",
"```{example} Renderer:Step\nBody.\n```",
"```{example} ../Renderer:integer_primitive\nBody.\n```",
"````{example} Renderer:integer_primitive\n```{example} Renderer:empty_array\nNested.\n```\n````",
] {
let mut book = json!({"items": [chapter("examples.md", source)]});
let error = mdbook_dada::process_with_lean(&mut book, Some(&root)).expect_err(source);
assert!(format!("{error:#}").contains("examples.md"), "{source}");
}
let mut missing_root = json!({"items": [chapter("examples.md", "```{example} Renderer:integer_primitive\nBody.\n```")]});
assert!(process(&mut missing_root).is_err());
let literal = "````text\n```{example} Missing:nope\nLiteral.\n```\n````\n\n ```{example} Missing:nope\n Literal.\n ```";
let mut book = json!({"items": [chapter("examples.md", literal)]});
process(&mut book).unwrap();
assert_eq!(book["items"][0]["Chapter"]["content"], literal);
}
}
#![allow(unused)]
fn main() {
#[test]
fn authored_theorems_select_literal_qualified_names() {
let root = lean_fixtures();
let source = r"```{theorem} Renderer:Transfer.preserves_count
Copying a list preserves its length.
\\[P \implies Q\\]
```";
let mut book = json!({"items": [chapter("moves.md", source)]});
mdbook_dada::process_with_lean(&mut book, Some(&root)).unwrap();
let html = book["items"][0]["Chapter"]["content"].as_str().unwrap();
assert!(html.contains("Renderer:Transfer.preserves_count"));
assert!(html.contains("lean-keyword\">theorem</span> Transfer.preserves_count"));
assert!(html.contains("copy_preserves_count written"));
assert!(!html.contains("theorem</span> Transfer.read"));
for citation in [
"Renderer:RendererFixture.Transfer.preserves_count",
"Renderer:Transfer..preserves_count",
"Renderer:.Transfer.preserves_count",
"Renderer:Transfer.preserves_count.",
] {
let source = format!("```{{theorem}} {citation}\nP\n```");
let mut book = json!({"items": [chapter("moves.md", &source)]});
assert!(mdbook_dada::process_with_lean(&mut book, Some(&root)).is_err());
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn qualified_theorem_names_match_only_the_literal_declaration_name() {
let source = "namespace Outer\ntheorem MoveReference.dependent_follows : True := by\n trivial\ntheorem other : True := by trivial\nend Outer\n";
assert_eq!(
extract_theorem(source, "MoveReference.dependent_follows").unwrap(),
"theorem MoveReference.dependent_follows : True := by\n trivial"
);
assert!(extract_theorem(source, "dependent_follows").is_err());
assert!(extract_theorem(source, "Outer.MoveReference.dependent_follows").is_err());
assert!(extract_theorem(source, "Outer.other").is_err());
assert!(extract_theorem(source, "other").is_ok());
assert!(extract(
"inductive Qualified.Type where\n | constructor",
"Qualified.Type"
)
.is_err());
}
}
#![allow(unused)]
fn main() {
#[test]
fn definitions_reject_unsupported_incomplete_and_ambiguous_sources() {
for source in [
"theorem selected : True := by trivial",
"axiom selected : Nat",
"opaque selected : Nat := 0",
"example : Nat := 0",
"private def selected := 0",
"@[simp]\ndef selected := 0",
" def selected := 0",
"def selected : Nat",
"def selected (n : Nat := 0) : Nat",
"def selected : Nat -- := 0",
"def selected : Nat /- where -/",
"def selected : Nat :=\n0",
"def selected : Nat → Nat\n| n => n",
"def selected : Nat → Nat\n | n\n => n",
"def selected := 0\ntermination_by 0",
"def selected := 0\n def sibling := 1",
"def selected := 0\n theorem sibling : True := by trivial",
"def selected := 0\nmystery next",
"def selected := 0\nnamespace Nested\ndef selected := 1\nend Nested",
"namespace A\ndef selected := 0\nend A\nnamespace B\ndef selected := 1\nend B",
"namespace A\ndef selected := 0\nend A\nnamespace B\ntheorem selected : True := by trivial\nend B",
"namespace A\ndef selected := 0\nend A\nnamespace B\nprivate def selected := 1\nend B",
"mutual\ndef selected := 0\nend",
] {
assert!(extract_definition(source, "selected").is_err(), "{source}");
}
for name in [".selected", "selected.", "N..selected", "N:selected"] {
assert!(extract_definition(&format!("def {name} := 0"), name).is_err());
}
}
}
#![allow(unused)]
fn main() {
#[cfg(unix)]
#[test]
fn lean_citations_accept_subdirectories_but_reject_source_root_escapes() {
use mdbook_dada::{lean, units::UnitKind};
use std::os::unix::fs::symlink;
struct Sources(PathBuf);
impl Drop for Sources {
fn drop(&mut self) {
fs::remove_dir_all(&self.0).unwrap();
}
}
let path = std::env::temp_dir().join(format!(
"dada-renderer-paths-{}-{}",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
));
fs::create_dir(&path).unwrap();
let fixture = Sources(path);
let root = fixture.0.join("lean");
fs::create_dir_all(root.join("nested")).unwrap();
fs::create_dir(fixture.0.join("outside")).unwrap();
for path in [
root.join("nested/Model.lean"),
root.join("nested/Model.txt"),
fixture.0.join("outside/Model.lean"),
] {
fs::write(path, "def answer : Nat := 7\n").unwrap();
}
let explicit = lean::select(&root, "nested/Model.lean:answer", UnitKind::Definition).unwrap();
let inferred = lean::select(&root, "nested/Model:answer", UnitKind::Definition).unwrap();
assert_eq!(explicit.selected, "def answer : Nat := 7");
assert_eq!(inferred.selected, explicit.selected);
assert_eq!(
inferred.path,
root.join("nested/Model.lean").canonicalize().unwrap()
);
symlink(
fixture.0.join("outside/Model.lean"),
root.join("file-link.lean"),
)
.unwrap();
symlink(fixture.0.join("outside"), root.join("directory-link")).unwrap();
let absolute = format!("{}:answer", root.join("nested/Model.lean").display());
for (target, diagnostic) in [
("../outside/Model.lean:answer", "relative without traversal"),
(absolute.as_str(), "relative without traversal"),
("nested/Model.txt:answer", "expected a .lean file"),
("file-link:answer", "escapes configured directory"),
(
"directory-link/Model:answer",
"escapes configured directory",
),
] {
let error = lean::select(&root, target, UnitKind::Definition).unwrap_err();
assert!(
format!("{error:#}").contains(diagnostic),
"{target}: {error:#}"
);
}
}
}
Diagrams
definitionmeta.syntax.heap.state
A heap diagram describes one graph using node declarations and slot assignments.
It does not execute operations. Blank lines and lines beginning with # are
ignored; forward references are allowed. Identifiers accept Unicode letters and
digits, with a letter or underscore first. Quoted labels use JSON string escaping,
and quoted arguments may contain commas.
definitionmeta.syntax.heap.constructors
The supported node constructors are variables() or variables("name"),
object(Type) or object(Type,"name"), primitive(value) or
primitive(value,"name"), and array(length) or array(length,"name").
There is at most one variable-store group. It is a presentation aid, not an object.
definitionmeta.syntax.heap.slots
Assignments use node.field or array[index]. A slot contains owned(target),
showned(target), shlease(target), lease(edge), or uninitialized().
leased aliases lease; shared aliases shlease, never showned.
Arrays begin with all slots empty.
The legacy borrow, primitive, and array forms are diagram syntax. Their availability does not introduce them into Given or Shared.
#![allow(unused)]
fn main() {
fn identifier(s: &str) -> bool {
let mut chars = s.chars();
chars.next().is_some_and(|c| c.is_alphabetic() || c == '_')
&& chars.all(|c| c.is_alphanumeric() || c == '_')
}
}
#![allow(unused)]
fn main() {
fn args(s: &str) -> Result<Vec<String>> {
let mut parts = vec![];
let (mut quoted, mut escaped, mut start) = (false, false, 0);
for (i, c) in s.char_indices() {
if escaped {
escaped = false;
continue;
}
if quoted && c == '\\' {
escaped = true;
continue;
}
if c == '"' {
quoted = !quoted;
}
if c == ',' && !quoted {
parts.push(s[start..i].trim().to_owned());
start = i + 1;
}
}
ensure!(!quoted, "unterminated quoted argument");
if !s.trim().is_empty() {
parts.push(s[start..].trim().to_owned());
}
Ok(parts)
}
}
#![allow(unused)]
fn main() {
fn label(s: &str) -> Result<String> {
if s.starts_with('"') {
Ok(serde_json::from_str::<String>(s)?)
} else {
ensure!(
!s.is_empty() && !s.contains(['(', ')', '"']),
"invalid argument `{s}`"
);
Ok(s.to_owned())
}
}
}
#![allow(unused)]
fn main() {
fn parse(source: &str) -> Result<Vec<Node>> {
let mut nodes = Vec::<Node>::new();
let mut assignments = vec![];
for (line, text) in source.lines().enumerate() {
let text = text.trim();
if text.is_empty() || text.starts_with('#') {
continue;
}
let result = (|| -> Result<()> {
let (lhs, rhs) = text.split_once('=').context("expected an assignment")?;
let lhs = lhs.trim();
let (op, rest) = rhs
.trim()
.split_once('(')
.context("expected constructor(arguments)")?;
let op = op.trim();
let arguments = args(
rest.strip_suffix(')')
.context("expected closing parenthesis")?,
)?;
if lhs.contains('.') || lhs.contains('[') {
assignments.push((lhs.to_owned(), op.to_owned(), arguments));
return Ok(());
}
ensure!(identifier(lhs), "invalid node identifier `{lhs}`");
ensure!(!nodes.iter().any(|n| n.id == lhs), "duplicate node `{lhs}`");
let (kind, display) = match (op, arguments.as_slice()) {
("variables", []) => (Kind::Variables, "Variables".to_owned()),
("variables", [name]) => (Kind::Variables, label(name)?),
("object", [ty]) => (Kind::Object, format!("{} {lhs}", label(ty)?)),
("object", [ty, name]) => {
(Kind::Object, format!("{} {}", label(ty)?, label(name)?))
}
("primitive", [value]) => (Kind::Primitive, format!("{lhs}: {}", label(value)?)),
("primitive", [value, name]) => (
Kind::Primitive,
format!("{}: {}", label(name)?, label(value)?),
),
("array", [length]) | ("array", [length, _]) => {
let length = length
.parse::<usize>()
.context("array length must be a nonnegative integer")?;
ensure!(length <= 64, "diagram arrays are limited to 64 slots");
let name = if arguments.len() == 2 {
label(&arguments[1])?
} else {
lhs.to_owned()
};
(Kind::Array(length), format!("{name} · length {length}"))
}
_ => bail!("unknown constructor or wrong arity: {op}"),
};
ensure!(
!matches!(kind, Kind::Variables)
|| !nodes
.iter()
.any(|node| matches!(node.kind, Kind::Variables)),
"a heap diagram has at most one variable store"
);
let slots = if let Kind::Array(n) = kind {
(0..n).map(|i| (format!("[{i}]"), None)).collect()
} else {
vec![]
};
nodes.push(Node {
id: lhs.to_owned(),
label: display,
kind,
slots,
});
Ok(())
})();
result.with_context(|| format!("heap facts line {}: {text}", line + 1))?;
}
ensure!(!nodes.is_empty(), "empty heap diagram");
let mut seen = BTreeSet::new();
for (lhs, op, args) in assignments {
let (owner, slot, indexed) = if let Some((owner, index)) = lhs.split_once('[') {
let index = index
.strip_suffix(']')
.context("expected closing array index")?
.parse::<usize>()?;
(owner, format!("[{index}]"), Some(index))
} else {
let (owner, slot) = lhs.split_once('.').context("expected node.slot")?;
ensure!(identifier(slot), "invalid slot name `{slot}`");
(owner, slot.to_owned(), None)
};
ensure!(
seen.insert((owner.to_owned(), slot.clone())),
"duplicate slot `{lhs}`"
);
let value = match (op.as_str(), args.as_slice()) {
("uninitialized", []) => None,
("lease" | "leased", [target]) => Some(("leased".to_owned(), target.clone())),
("owned" | "showned" | "shlease" | "shared", [target]) => {
let target_node = nodes
.iter()
.find(|n| n.id == *target)
.with_context(|| format!("unknown target `{target}`"))?;
ensure!(
!matches!(target_node.kind, Kind::Variables),
"reference cannot target variable store `{target}`"
);
// `shared` is a diagram shorthand for a shared lease. Ownership is
// always spelled `showned`, never inferred from the other edges.
Some((
if op == "shared" {
"shlease".to_owned()
} else {
op
},
target.clone(),
))
}
_ => bail!("unknown reference constructor or wrong arity in `{lhs}`"),
};
let node = nodes
.iter_mut()
.find(|n| n.id == owner)
.with_context(|| format!("unknown slot owner `{owner}`"))?;
match (&node.kind, indexed) {
(Kind::Array(length), Some(index)) => {
ensure!(index < *length, "array index out of bounds in `{lhs}`");
node.slots[index].1 = value;
}
(Kind::Variables | Kind::Object, None) => node.slots.push((slot, value)),
_ => bail!("invalid slot projection in `{lhs}`"),
}
}
for node in &nodes {
for (_, value) in &node.slots {
if let Some((kind, target)) = value {
if kind == "leased" {
let (n, slot) = edge_target(&nodes, target)?;
let edge = nodes[n].slots[slot]
.1
.as_ref()
.context("lease target is uninitialized")?;
ensure!(
matches!(edge.0.as_str(), "owned" | "leased"),
"lease target must be an owned or leased edge: {target}"
);
}
}
}
}
Ok(nodes)
}
}
#![allow(unused)]
fn main() {
#[test]
fn facts_render_unicode_fields_and_reference_kinds() {
let facts="vars = variables()\nα = object(Point, \"α\")\nβ = primitive(22)\nvars.p = owned(α)\nvars.q = shared(α)\nα.x = owned(β)";
let svg = render(facts).unwrap();
assert!(svg.contains("Point α"));
assert!(svg.contains("heap-edge shlease"));
assert_eq!(svg.matches("<g class=\"heap-edge").count(), 3);
assert_eq!(svg, render(facts).unwrap());
}
}
#![allow(unused)]
fn main() {
#[test]
fn arrays_materialize_uninitialized_slots_and_validate_indices() {
let nodes = parse("a = array(2)\np = primitive(9)\na[0] = owned(p)").unwrap();
assert_eq!(nodes[0].slots.len(), 2);
assert!(nodes[0].slots[1].1.is_none());
assert!(render("a = array(2)\na[2] = uninitialized()").is_err());
}
}
#![allow(unused)]
fn main() {
#[test]
fn variable_store_groups_slots_without_becoming_a_reference_target() {
let facts = "vars = variables()\na = primitive(1)\nvars.x = owned(a)\nvars.y = lease(vars.x)\nvars.z = uninitialized()";
let nodes = parse(facts).unwrap();
assert_eq!(nodes[0].label, "Variables");
assert_eq!(nodes[0].slots.len(), 3);
let svg = render(facts).unwrap();
assert!(svg.contains("class=\"heap-variables\""));
assert!(svg.contains("class=\"heap-junction\""));
assert!(render(&format!("{facts}\nvars.bad = owned(vars)")).is_err());
assert!(render("vars = variables(\"Live variables\")")
.unwrap()
.contains("Live variables"));
}
}
#![allow(unused)]
fn main() {
#[test]
fn labels_are_escaped_and_quoted_commas_are_preserved() {
let svg = render("a = object(Point, \"<script>, &\\\"\")").unwrap();
assert!(!svg.contains("<script>"));
assert!(svg.contains("<script>, &""));
}
}
#![allow(unused)]
fn main() {
#[test]
fn diagram_forward_references_and_aliases_preserve_distinct_edges() {
let forward = r#"
References and lease supports may precede their declarations.
vars.α = owned(a)
vars.β = leased(vars.α)
vars.γ = shared(b)
vars.δ = showned(b)
vars = variables()
a = object(Container)
b = primitive(1)
"#;
let canonical = "vars = variables()\na = object(Container)\nb = primitive(1)\nvars.α = owned(a)\nvars.β = lease(vars.α)\nvars.γ = shlease(b)\nvars.δ = showned(b)";
let svg = graph::render(forward).unwrap();
let canonical_svg = graph::render(canonical).unwrap();
// The accessible description retains the authored facts; only the diagram
// after that description should be identical across the two spellings.
assert!(svg.contains(&format!("<desc>{}</desc>", mdbook_dada::escape(forward))));
assert_eq!(
svg.split_once("</desc>").unwrap().1,
canonical_svg.split_once("</desc>").unwrap().1
);
for kind in ["owned", "leased", "shlease", "showned"] {
assert_eq!(
svg.matches(&format!("class=\"heap-edge {kind}\"")).count(),
1
);
}
assert_eq!(svg.matches("class=\"heap-junction\"").count(), 1);
for field in ["α", "β", "γ", "δ"] {
assert!(svg.contains(&format!(">{field}</text>")));
}
}
}
Each node and explicitly assigned slot is declared once. Unknown targets, duplicate nodes or assignments, invalid projections, multiple variable stores, and out-of-bounds indices are rejected. Diagram arrays have at most 64 slots; that is a presentation limit, not a language bound.
Owned, showned, and shlease edges target objects, primitives, or arrays, never
the variable-store group. A lease names an initialized owned or leased edge,
such as α.f, vars.p, or items[0]. Its target may be declared later.
These checks validate diagram structure. Ownership cycles and conflicting owners are accepted so malformed language states can be illustrated. The parser does not establish language invariants or infer support edges.
#![allow(unused)]
fn main() {
fn parse(source: &str) -> Result<Vec<Node>> {
let mut nodes = Vec::<Node>::new();
let mut assignments = vec![];
for (line, text) in source.lines().enumerate() {
let text = text.trim();
if text.is_empty() || text.starts_with('#') {
continue;
}
let result = (|| -> Result<()> {
let (lhs, rhs) = text.split_once('=').context("expected an assignment")?;
let lhs = lhs.trim();
let (op, rest) = rhs
.trim()
.split_once('(')
.context("expected constructor(arguments)")?;
let op = op.trim();
let arguments = args(
rest.strip_suffix(')')
.context("expected closing parenthesis")?,
)?;
if lhs.contains('.') || lhs.contains('[') {
assignments.push((lhs.to_owned(), op.to_owned(), arguments));
return Ok(());
}
ensure!(identifier(lhs), "invalid node identifier `{lhs}`");
ensure!(!nodes.iter().any(|n| n.id == lhs), "duplicate node `{lhs}`");
let (kind, display) = match (op, arguments.as_slice()) {
("variables", []) => (Kind::Variables, "Variables".to_owned()),
("variables", [name]) => (Kind::Variables, label(name)?),
("object", [ty]) => (Kind::Object, format!("{} {lhs}", label(ty)?)),
("object", [ty, name]) => {
(Kind::Object, format!("{} {}", label(ty)?, label(name)?))
}
("primitive", [value]) => (Kind::Primitive, format!("{lhs}: {}", label(value)?)),
("primitive", [value, name]) => (
Kind::Primitive,
format!("{}: {}", label(name)?, label(value)?),
),
("array", [length]) | ("array", [length, _]) => {
let length = length
.parse::<usize>()
.context("array length must be a nonnegative integer")?;
ensure!(length <= 64, "diagram arrays are limited to 64 slots");
let name = if arguments.len() == 2 {
label(&arguments[1])?
} else {
lhs.to_owned()
};
(Kind::Array(length), format!("{name} · length {length}"))
}
_ => bail!("unknown constructor or wrong arity: {op}"),
};
ensure!(
!matches!(kind, Kind::Variables)
|| !nodes
.iter()
.any(|node| matches!(node.kind, Kind::Variables)),
"a heap diagram has at most one variable store"
);
let slots = if let Kind::Array(n) = kind {
(0..n).map(|i| (format!("[{i}]"), None)).collect()
} else {
vec![]
};
nodes.push(Node {
id: lhs.to_owned(),
label: display,
kind,
slots,
});
Ok(())
})();
result.with_context(|| format!("heap facts line {}: {text}", line + 1))?;
}
ensure!(!nodes.is_empty(), "empty heap diagram");
let mut seen = BTreeSet::new();
for (lhs, op, args) in assignments {
let (owner, slot, indexed) = if let Some((owner, index)) = lhs.split_once('[') {
let index = index
.strip_suffix(']')
.context("expected closing array index")?
.parse::<usize>()?;
(owner, format!("[{index}]"), Some(index))
} else {
let (owner, slot) = lhs.split_once('.').context("expected node.slot")?;
ensure!(identifier(slot), "invalid slot name `{slot}`");
(owner, slot.to_owned(), None)
};
ensure!(
seen.insert((owner.to_owned(), slot.clone())),
"duplicate slot `{lhs}`"
);
let value = match (op.as_str(), args.as_slice()) {
("uninitialized", []) => None,
("lease" | "leased", [target]) => Some(("leased".to_owned(), target.clone())),
("owned" | "showned" | "shlease" | "shared", [target]) => {
let target_node = nodes
.iter()
.find(|n| n.id == *target)
.with_context(|| format!("unknown target `{target}`"))?;
ensure!(
!matches!(target_node.kind, Kind::Variables),
"reference cannot target variable store `{target}`"
);
// `shared` is a diagram shorthand for a shared lease. Ownership is
// always spelled `showned`, never inferred from the other edges.
Some((
if op == "shared" {
"shlease".to_owned()
} else {
op
},
target.clone(),
))
}
_ => bail!("unknown reference constructor or wrong arity in `{lhs}`"),
};
let node = nodes
.iter_mut()
.find(|n| n.id == owner)
.with_context(|| format!("unknown slot owner `{owner}`"))?;
match (&node.kind, indexed) {
(Kind::Array(length), Some(index)) => {
ensure!(index < *length, "array index out of bounds in `{lhs}`");
node.slots[index].1 = value;
}
(Kind::Variables | Kind::Object, None) => node.slots.push((slot, value)),
_ => bail!("invalid slot projection in `{lhs}`"),
}
}
for node in &nodes {
for (_, value) in &node.slots {
if let Some((kind, target)) = value {
if kind == "leased" {
let (n, slot) = edge_target(&nodes, target)?;
let edge = nodes[n].slots[slot]
.1
.as_ref()
.context("lease target is uninitialized")?;
ensure!(
matches!(edge.0.as_str(), "owned" | "leased"),
"lease target must be an owned or leased edge: {target}"
);
}
}
}
}
Ok(nodes)
}
}
#![allow(unused)]
fn main() {
fn edge_target(nodes: &[Node], target: &str) -> Result<(usize, usize)> {
let (owner, slot) = if let Some((owner, slot)) = target.split_once('.') {
(owner, slot.to_owned())
} else if let Some((owner, index)) = target.split_once('[') {
let index = index
.strip_suffix(']')
.context("expected array edge index")?
.parse::<usize>()?;
(owner, format!("[{index}]"))
} else {
bail!("lease target must name an edge, such as α.f or vars.p: {target}");
};
let n = nodes
.iter()
.position(|n| n.id == owner)
.with_context(|| format!("unknown edge owner `{owner}`"))?;
let s = nodes[n]
.slots
.iter()
.position(|(name, _)| *name == slot)
.with_context(|| format!("unknown edge `{target}`"))?;
Ok((n, s))
}
}
#![allow(unused)]
fn main() {
#[test]
fn bad_facts_fail_instead_of_silently_changing_the_graph() {
for facts in [
"a = variables()\na = variables()",
"a = variables()\nb = variables()",
"a = frame()",
"a = variables()\na.p = owned(missing)",
"a = variables()\na.p = owned(a)",
"a = primitive(1)\na.x = uninitialized()",
"a = variables()\na.p = uninitialized()\na.p = uninitialized()",
"a = unknown()",
] {
assert!(render(facts).is_err(), "{facts}");
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn arrays_materialize_uninitialized_slots_and_validate_indices() {
let nodes = parse("a = array(2)\np = primitive(9)\na[0] = owned(p)").unwrap();
assert_eq!(nodes[0].slots.len(), 2);
assert!(nodes[0].slots[1].1.is_none());
assert!(render("a = array(2)\na[2] = uninitialized()").is_err());
}
}
#![allow(unused)]
fn main() {
#[test]
fn leases_join_edges_and_shleases_target_objects() {
let facts = "vars = variables()\nα = object(C)\nβ = primitive(1)\nvars.p = owned(α)\nα.f = owned(β)\nvars.q = lease(α.f)\nvars.r = lease(vars.q)\nvars.s = shlease(β)";
let svg = render(facts).unwrap();
assert_eq!(svg.matches("class=\"heap-junction\"").count(), 2);
assert!(svg.contains("heap-edge shlease"));
for target in ["β", "α.missing", "vars.s", "α.empty"] {
let bad = format!("{facts}\nα.empty = uninitialized()\nvars.bad = lease({target})");
assert!(render(&bad).is_err(), "{target}");
}
assert!(render(
"vars = variables()\na = array(1)\nb = primitive(2)\nvars.q = lease(a[0])\na[0] = owned(b)"
)
.is_ok());
assert!(render(
"vars = variables()\na = primitive(1)\nvars.p = owned(a)\nvars.q = shlease(vars.p)"
)
.is_err());
}
}
#![allow(unused)]
fn main() {
#[test]
fn cycles_self_loops_and_disconnected_cycles_render_deterministically() {
let rect = regex::Regex::new(
r#"<rect x="([\d.]+)" y="([\d.]+)" width="([\d.]+)" height="([\d.]+)""#,
)
.unwrap();
let paths = regex::Regex::new(r#"<path d="([^"]+)""#).unwrap();
for facts in [
"a = object(Node)\na.next = showned(a)",
"a = object(Node)\nb = object(Node)\na.next = showned(b)\nb.next = showned(a)",
"vars = variables()\na = object(Node)\nb = object(Node)\nvars.p = showned(a)\na.next = showned(b)\nb.next = showned(a)",
] {
let svg = render(facts).unwrap();
assert_eq!(svg, render(facts).unwrap());
assert!(!svg.contains("NaN"));
assert!(!svg.contains("heap-arrow"));
let nodes = parse(facts).unwrap();
let count = nodes.iter().flat_map(|n| &n.slots).filter(|(_, v)| v.is_some()).count();
assert_eq!(svg.matches("class=\"heap-endpoint\"").count(), count);
// Check every routed segment against every rendered rectangle, including
// the source and destination: only boundary contact is permitted.
let boxes: Vec<Vec<f64>> = rect.captures_iter(&svg).map(|c| (1..=4).map(|i| c[i].parse().unwrap()).collect()).collect();
for c in paths.captures_iter(&svg) {
let mut tokens = c[1].split_whitespace();
let mut last = (0.0_f64, 0.0_f64);
while let Some(op) = tokens.next() {
let x: f64 = tokens.next().unwrap().parse().unwrap();
let next = if op == "H" { (x,last.1) } else { (x,tokens.next().unwrap().parse().unwrap()) };
if op != "M" {
assert!(last.0 == next.0 || last.1 == next.1);
for b in &boxes {
let crosses = if last.0 == next.0 {
last.0 > b[0] && last.0 < b[0]+b[2] && last.1.min(next.1) < b[1]+b[3] && last.1.max(next.1) > b[1]
} else {
last.1 > b[1] && last.1 < b[1]+b[3] && last.0.min(next.0) < b[0]+b[2] && last.0.max(next.0) > b[0]
};
assert!(!crosses, "edge crosses box in {facts}");
}
}
last = next;
}
}
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn diagram_array_size_boundary_preserves_all_slots() {
let empty = graph::render("a = array(0)").unwrap();
assert!(empty.contains("length 0"));
assert!(!empty.contains("uninitialized"));
let maximum = graph::render("a = array(64)").unwrap();
assert_eq!(maximum.matches(": uninitialized</text>").count(), 64);
for index in 0..64 {
assert!(maximum.contains(&format!(">[{index}]: uninitialized</text>")));
}
let last = graph::render("a = array(64)\na[63] = owned(b)\nb = primitive(1)").unwrap();
assert_eq!(last.matches(": uninitialized</text>").count(), 63);
assert_eq!(last.matches("class=\"heap-edge owned\"").count(), 1);
let too_large = graph::render("a = array(65)").unwrap_err();
assert!(format!("{too_large:#}").contains("limited to 64 slots"));
assert!(graph::render("a = array(64)\na[64] = uninitialized()").is_err());
}
}
A diagram renders each stored reference as a labeled SVG edge. Explicit leases join their named supporting edge at a junction; object-targeting edges end at the target’s left boundary. Node and edge labels are HTML-escaped. The SVG description and Facts view retain the input facts.
Layout is deterministic for the same input. It places the variable group to the left of reachable objects when the graph allows it. It does not add graph edges or infer lease provenance.
#![allow(unused)]
fn main() {
pub fn render(source: &str) -> Result<String> {
let nodes = parse(source)?;
let lookup: BTreeMap<_, _> = nodes
.iter()
.enumerate()
.map(|(i, n)| (n.id.as_str(), i))
.collect();
// Assign depth by first-discovered owning root path. Cycles and disconnected objects remain
// renderable; the diagram language does not claim ownership well-formedness.
let mut depths = vec![None; nodes.len()];
for (i, n) in nodes.iter().enumerate() {
if matches!(n.kind, Kind::Variables) {
depths[i] = Some(0);
}
}
for _ in 0..nodes.len() {
let mut changed = false;
for (i, n) in nodes.iter().enumerate() {
if let Some(depth) = depths[i] {
for (_, value) in &n.slots {
if let Some((kind, target)) = value {
if !matches!(kind.as_str(), "owned" | "showned") {
continue;
}
let j = lookup[target.as_str()];
if depths[j].is_none() {
depths[j] = Some(depth + 1);
changed = true;
}
}
}
}
}
if !changed {
break;
}
}
let width = nodes
.iter()
.map(|n| n.label.chars().count())
.max()
.unwrap_or(0)
.max(18) as f64
* 8.0
+ 32.0;
let stride = width + 150.0;
let mut bottoms = BTreeMap::<usize, f64>::new();
let positions: Vec<_> = nodes
.iter()
.enumerate()
.map(|(i, n)| {
let depth = depths[i].unwrap_or(1);
let y = *bottoms.entry(depth).or_insert(30.0);
let height = 48.0 + 32.0 * n.slots.len() as f64;
bottoms.insert(depth, y + height + 65.0);
(30.0 + depth as f64 * stride, y, height)
})
.collect();
let canvas_width = positions
.iter()
.map(|(x, _, _)| x + width + 90.0)
.fold(0.0, f64::max);
let canvas_height = bottoms.values().copied().fold(0.0, f64::max);
let mut svg=format!("<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"heap-diagram\" role=\"img\" aria-label=\"Heap objects and references\" style=\"max-width:{canvas_width}px\" viewBox=\"0 0 {canvas_width} {canvas_height}\"><title>Heap objects and references</title><desc>{}</desc>",escape(source));
for (i, n) in nodes.iter().enumerate() {
let (x, y, height) = positions[i];
let class = if matches!(n.kind, Kind::Variables) {
"heap-variables"
} else {
"heap-object"
};
svg.push_str(&format!("<g class=\"{class}\"><rect x=\"{x}\" y=\"{y}\" width=\"{width}\" height=\"{height}\" rx=\"6\"/><text x=\"{}\" y=\"{}\" class=\"heap-title\">{}</text>",x+12.0,y+27.0,escape(&n.label)));
for (s, (slot, value)) in n.slots.iter().enumerate() {
let sy = y + 62.0 + s as f64 * 32.0;
let contents = if value.is_none() {
format!("{slot}: uninitialized")
} else {
slot.clone()
};
svg.push_str(&format!(
"<text x=\"{}\" y=\"{sy}\">{}</text>",
x + 12.0,
escape(&contents)
));
}
svg.push_str("</g>");
}
for (i, n) in nodes.iter().enumerate() {
let (x, y, _) = positions[i];
for (s, (_, value)) in n.slots.iter().enumerate() {
if let Some((kind, target)) = value {
let sy = y + 57.0 + s as f64 * 32.0;
let (tx, ey, edge_targeted) = if kind == "leased" {
let (n, slot) = edge_target(&nodes, target)?;
let (x, y, _) = positions[n];
(x + width + 12.0, y + 57.0 + slot as f64 * 32.0, true)
} else {
let (x, y, height) = positions[lookup[target.as_str()]];
(x, sy.clamp(y + 12.0, y + height - 12.0), false)
};
let sx = x + width;
let boxes: Vec<_> = positions
.iter()
.map(|&(x, y, h)| (x as i64, y as i64, width as i64, h as i64))
.collect();
let route = crate::routing::route(
((sx + 35.0) as i64, sy as i64),
(
(if edge_targeted { tx } else { tx - 20.0 }) as i64,
ey as i64,
),
&boxes,
)?;
let mut d = format!("M {sx} {sy} H {}", sx + 35.0);
for &(px, py) in route.iter().skip(1) {
d.push_str(&format!(" L {px} {py}"));
}
if !edge_targeted {
d.push_str(&format!(" L {tx} {ey}"));
}
let dot_class = if edge_targeted {
"heap-junction"
} else {
"heap-endpoint"
};
svg.push_str(&format!("<g class=\"heap-edge {kind}\"><path d=\"{d}\"/><circle class=\"{dot_class}\" cx=\"{tx}\" cy=\"{ey}\" r=\"3\" fill=\"currentColor\"/><text x=\"{}\" y=\"{}\">{kind}</text></g>",sx+5.0,sy-7.0));
}
}
}
svg.push_str("</svg>");
Ok(svg)
}
}
#![allow(unused)]
fn main() {
fn render(
source: &str,
path: &str,
anchors: &BTreeMap<String, String>,
lean_root: Option<&Path>,
project_root: Option<&Path>,
scope: &str,
definition_label: &str,
) -> Result<String> {
let protected = protect_math(source);
let source = protected.as_str();
let structured_units = units::parse(source, path)?;
let mut edits = vec![];
for role in roles(source)? {
let rendered = render_role(&role, path, anchors, definition_label)?;
edits.push((role.range, rendered));
}
for (event, range) in Parser::new(source).into_offset_iter() {
if matches!(event, Event::Start(Tag::Paragraph)) {
ensure!(
!source[range.clone()].starts_with("{example} "),
"the paragraph {{example}} marker has been replaced: use a fenced ```{{example}} path:anchor with a Markdown body and a Lean test, or label an unfinished scenario as informational"
);
if source[range.clone()].starts_with("{informational} ") {
edits.push((
range.start..range.start + "{informational}".len(),
"<span class=\"informational-label\">Informational</span>".to_owned(),
));
}
}
}
for block in directive_blocks(source) {
if let Some(unit) = structured_units
.iter()
.find(|unit| unit.range.start == block.range.start)
{
for dependency in &unit.uses {
ensure!(
anchors.contains_key(dependency),
"unknown unit dependency `{dependency}`"
);
}
edits.push((
block.range,
render_unit(unit, path, anchors, lean_root, project_root)?,
));
continue;
}
let start = block.range.start;
let kind = block.info;
let facts = block.body;
let (directive, argument) = kind.split_once(char::is_whitespace).unwrap_or((&kind, ""));
ensure!(
![
"{heap}",
"{grammar}",
"{rule}",
"{judgment}",
"{definition}",
"{theorem}",
"{lemma}",
"{example}",
"{future-note}"
]
.iter()
.any(|name| directive.starts_with(name) && directive != *name),
"separate the directive name and citation with whitespace"
);
ensure!(!matches!(directive, "{lean.type}" | "{lean.judgment}" | "{lean.rule}"),
"{directive} has been replaced: use ```{{grammar}} path:Name, ```{{judgment}} path:Name, or ```{{rule}} path:Name.case with authored LaTeX in the body");
let id = format!("{scope}-{start}");
if let Some(markdown) = MarkdownDirective::parse(directive) {
let name = markdown.name();
let label = markdown.label();
let citations = argument.split_whitespace().count();
if matches!(markdown, MarkdownDirective::Definition) {
ensure!(
citations > 0,
"definition requires at least one opening-line citation"
);
} else {
ensure!(
citations == 1,
"{name} requires exactly one opening-line citation"
);
}
ensure!(!facts.trim().is_empty(), "{name} requires a Markdown body");
let root =
lean_root.context("Lean directives require preprocessor.dada.lean-source")?;
let lean_source = match markdown {
MarkdownDirective::Definition => lean::definition_source(root, argument)?,
MarkdownDirective::Example => lean::example_source(root, argument.trim())?,
MarkdownDirective::Theorem | MarkdownDirective::Lemma => {
lean::theorem_source(root, argument.trim())?
}
};
let heading_label = if matches!(markdown, MarkdownDirective::Example) {
"example"
} else {
markdown.definition_label()
};
let (heading, body) = markdown_heading(&facts, path, anchors, heading_label)?;
ensure!(
!body.trim().is_empty(),
"{name} requires a Markdown body after its heading anchors"
);
let body = render(
body,
path,
anchors,
lean_root,
project_root,
&id,
markdown.definition_label(),
)?;
let selector = selector_header(
label,
(!heading.is_empty()).then_some(heading.as_str()),
&format!("{name}-{id}"),
"rendered",
"Lean",
);
// Blank lines terminate raw HTML blocks so mdBook renders the body
// as Markdown, including its explicit math delimiters and proof prose.
edits.push((block.range, format!(
"\n<figure class=\"lean-declaration lean-group lean-markdown lean-{name}\">{selector}<div class=\"lean-markdown-body\">\n\n{}\n\n</div><div class=\"lean-source\">{lean_source}</div></figure>\n\n",
body.trim_matches('\n')
)));
continue;
}
let view = match directive {
"{grammar}" => Some(lean::View::Grammar),
"{judgment}" => Some(lean::View::Judgment),
"{rule}" => Some(lean::View::Rule),
_ => None,
};
if let Some(view) = view {
let root =
lean_root.context("Lean directives require preprocessor.dada.lean-source")?;
edits.push((
block.range,
format!(
"\n{}\n",
lean::render_authored(root, argument.trim(), &facts, view, &id)?
),
));
continue;
}
ensure!(
argument.trim().is_empty(),
"{directive} does not accept opening-line arguments"
);
let graph = graph::render(&facts)?;
let selector = selector_header("Diagram", None, &format!("heap-{id}"), "rendered", "Facts");
let source = escape(&facts).replace('\n', " ");
edits.push((block.range, format!("\n<figure class=\"heap-figure\">{selector}{graph}<pre class=\"heap-facts\"><code>{source}</code></pre></figure>\n")));
}
edits.sort_by_key(|(range, _)| range.start);
let mut result = String::new();
let mut end = 0;
for (range, replacement) in edits {
ensure!(range.start >= end, "overlapping markup");
result.push_str(&source[end..range.start]);
result.push_str(&replacement);
end = range.end;
}
result.push_str(&source[end..]);
Ok(result)
}
}
#![allow(unused)]
fn main() {
/// Shared header for every rendered/source pair. The heading is generated HTML;
/// labels, group names, and radio values are escaped here.
pub(crate) fn selector_header(
label: &str,
heading: Option<&str>,
group: &str,
rendered_value: &str,
alternate: &str,
) -> String {
let label = escape(label);
let fallback = format!("<span class=\"block-label\">{label}</span>");
let heading = heading.unwrap_or(&fallback);
let group = escape(group);
let rendered_value = escape(rendered_value);
let alternate_value = escape(&alternate.to_ascii_lowercase());
let alternate = escape(alternate);
format!("<div class=\"lean-selector\" role=\"group\" aria-label=\"{label} view\"><div class=\"block-heading\">{heading}</div><div class=\"view-options\"><label><input type=\"radio\" name=\"{group}\" value=\"{rendered_value}\" checked> Rendered</label><label><input type=\"radio\" name=\"{group}\" value=\"{alternate_value}\"> {alternate}</label></div></div>")
}
}
#![allow(unused)]
fn main() {
#[test]
fn heap_fences_render_and_preserve_source() {
let mut book = json!({"sections":[chapter("a.md","Before.\n\n```{heap}\nvars = variables()\np = object(Point, \"α\")\nvars.p = owned(p)\n```\n\nAfter.")]});
process(&mut book).unwrap();
let text = book["sections"][0]["Chapter"]["content"].as_str().unwrap();
assert!(text.contains("<svg"));
assert!(text.contains("aria-label=\"Diagram view\""));
assert!(text.contains("value=\"rendered\" checked"));
assert!(text.contains("class=\"heap-facts\""));
assert!(text.contains("vars.p = owned(p) "));
assert!(text.contains("Before."));
assert!(text.contains("After."));
assert!(!text.contains("```{heap}"));
}
}
#![allow(unused)]
fn main() {
#[test]
fn facts_render_unicode_fields_and_reference_kinds() {
let facts="vars = variables()\nα = object(Point, \"α\")\nβ = primitive(22)\nvars.p = owned(α)\nvars.q = shared(α)\nα.x = owned(β)";
let svg = render(facts).unwrap();
assert!(svg.contains("Point α"));
assert!(svg.contains("heap-edge shlease"));
assert_eq!(svg.matches("<g class=\"heap-edge").count(), 3);
assert_eq!(svg, render(facts).unwrap());
}
}
#![allow(unused)]
fn main() {
#[test]
fn leases_join_edges_and_shleases_target_objects() {
let facts = "vars = variables()\nα = object(C)\nβ = primitive(1)\nvars.p = owned(α)\nα.f = owned(β)\nvars.q = lease(α.f)\nvars.r = lease(vars.q)\nvars.s = shlease(β)";
let svg = render(facts).unwrap();
assert_eq!(svg.matches("class=\"heap-junction\"").count(), 2);
assert!(svg.contains("heap-edge shlease"));
for target in ["β", "α.missing", "vars.s", "α.empty"] {
let bad = format!("{facts}\nα.empty = uninitialized()\nvars.bad = lease({target})");
assert!(render(&bad).is_err(), "{target}");
}
assert!(render(
"vars = variables()\na = array(1)\nb = primitive(2)\nvars.q = lease(a[0])\na[0] = owned(b)"
)
.is_ok());
assert!(render(
"vars = variables()\na = primitive(1)\nvars.p = owned(a)\nvars.q = shlease(vars.p)"
)
.is_err());
}
}
#![allow(unused)]
fn main() {
#[test]
fn cycles_self_loops_and_disconnected_cycles_render_deterministically() {
let rect = regex::Regex::new(
r#"<rect x="([\d.]+)" y="([\d.]+)" width="([\d.]+)" height="([\d.]+)""#,
)
.unwrap();
let paths = regex::Regex::new(r#"<path d="([^"]+)""#).unwrap();
for facts in [
"a = object(Node)\na.next = showned(a)",
"a = object(Node)\nb = object(Node)\na.next = showned(b)\nb.next = showned(a)",
"vars = variables()\na = object(Node)\nb = object(Node)\nvars.p = showned(a)\na.next = showned(b)\nb.next = showned(a)",
] {
let svg = render(facts).unwrap();
assert_eq!(svg, render(facts).unwrap());
assert!(!svg.contains("NaN"));
assert!(!svg.contains("heap-arrow"));
let nodes = parse(facts).unwrap();
let count = nodes.iter().flat_map(|n| &n.slots).filter(|(_, v)| v.is_some()).count();
assert_eq!(svg.matches("class=\"heap-endpoint\"").count(), count);
// Check every routed segment against every rendered rectangle, including
// the source and destination: only boundary contact is permitted.
let boxes: Vec<Vec<f64>> = rect.captures_iter(&svg).map(|c| (1..=4).map(|i| c[i].parse().unwrap()).collect()).collect();
for c in paths.captures_iter(&svg) {
let mut tokens = c[1].split_whitespace();
let mut last = (0.0_f64, 0.0_f64);
while let Some(op) = tokens.next() {
let x: f64 = tokens.next().unwrap().parse().unwrap();
let next = if op == "H" { (x,last.1) } else { (x,tokens.next().unwrap().parse().unwrap()) };
if op != "M" {
assert!(last.0 == next.0 || last.1 == next.1);
for b in &boxes {
let crosses = if last.0 == next.0 {
last.0 > b[0] && last.0 < b[0]+b[2] && last.1.min(next.1) < b[1]+b[3] && last.1.max(next.1) > b[1]
} else {
last.1 > b[1] && last.1 < b[1]+b[3] && last.0.min(next.0) < b[0]+b[2] && last.0.max(next.0) > b[0]
};
assert!(!crosses, "edge crosses box in {facts}");
}
}
last = next;
}
}
}
}
}
Diagram edges use horizontal and vertical segments ending in dots. Routing searches corridors around node rectangles, including gaps within a column, and penalizes distance and bends. It avoids box interiors; a missing route is an error. It does not guarantee that distinct edges or their labels never overlap. Lease junctions identify the explicitly named supporting edge.
#![allow(unused)]
fn main() {
pub fn route(start: Point, end: Point, boxes: &[Rect]) -> Result<Vec<Point>> {
let mut xs = vec![start.0, end.0];
let mut ys = vec![start.1, end.1];
for &(x, y, w, h) in boxes {
xs.extend([x - 20, x + w + 20]);
ys.extend([y - 20, y + h + 20]);
}
xs.sort_unstable();
xs.dedup();
ys.sort_unstable();
ys.dedup();
let nx = xs.len();
let index = |p: Point| -> Result<usize> {
Ok(
ys.binary_search(&p.1).ok().context("missing routing y")? * nx
+ xs.binary_search(&p.0).ok().context("missing routing x")?,
)
};
let point = |i: usize| (xs[i % nx], ys[i / nx]);
let initial = index(start)? * 2;
let goal = index(end)?;
let mut costs = vec![i64::MAX; nx * ys.len() * 2];
let mut previous = vec![None; costs.len()];
costs[initial] = 0;
let mut queue = BinaryHeap::from([Reverse((0, initial))]);
while let Some(Reverse((cost, state))) = queue.pop() {
if cost != costs[state] {
continue;
}
let node = state / 2;
if node == goal {
let mut path = vec![point(node)];
let mut current = state;
while let Some(parent) = previous[current] {
path.push(point(parent / 2));
current = parent;
}
path.reverse();
let mut compact: Vec<Point> = Vec::new();
for p in path {
while compact.len() >= 2 {
let a = compact[compact.len() - 2];
let b = compact[compact.len() - 1];
if (a.0 == b.0 && b.0 == p.0) || (a.1 == b.1 && b.1 == p.1) {
compact.pop();
} else {
break;
}
}
compact.push(p);
}
return Ok(compact);
}
let x = node % nx;
let y = node / nx;
let neighbors = [
(x.checked_sub(1).map(|x| y * nx + x), 0),
((x + 1 < nx).then_some(node + 1), 0),
(y.checked_sub(1).map(|y| y * nx + x), 1),
((y + 1 < ys.len()).then_some(node + nx), 1),
];
for (next, direction) in neighbors {
let Some(next) = next else {
continue;
};
let a = point(node);
let b = point(next);
if !clear(a, b, boxes) {
continue;
}
let step =
(a.0 - b.0).abs() + (a.1 - b.1).abs() + if state % 2 == direction { 0 } else { 25 };
let next_state = next * 2 + direction;
if cost + step < costs[next_state] {
costs[next_state] = cost + step;
previous[next_state] = Some(state);
queue.push(Reverse((cost + step, next_state)));
}
}
}
anyhow::bail!("no obstacle-free diagram route from {start:?} to {end:?}")
}
}
#![allow(unused)]
fn main() {
fn clear(a: Point, b: Point, boxes: &[Rect]) -> bool {
!boxes.iter().any(|&(x, y, w, h)| {
if a.0 == b.0 {
a.0 > x && a.0 < x + w && a.1.min(b.1) < y + h && a.1.max(b.1) > y
} else {
a.1 > y && a.1 < y + h && a.0.min(b.0) < x + w && a.0.max(b.0) > x
}
})
}
}
#![allow(unused)]
fn main() {
pub fn render(source: &str) -> Result<String> {
let nodes = parse(source)?;
let lookup: BTreeMap<_, _> = nodes
.iter()
.enumerate()
.map(|(i, n)| (n.id.as_str(), i))
.collect();
// Assign depth by first-discovered owning root path. Cycles and disconnected objects remain
// renderable; the diagram language does not claim ownership well-formedness.
let mut depths = vec![None; nodes.len()];
for (i, n) in nodes.iter().enumerate() {
if matches!(n.kind, Kind::Variables) {
depths[i] = Some(0);
}
}
for _ in 0..nodes.len() {
let mut changed = false;
for (i, n) in nodes.iter().enumerate() {
if let Some(depth) = depths[i] {
for (_, value) in &n.slots {
if let Some((kind, target)) = value {
if !matches!(kind.as_str(), "owned" | "showned") {
continue;
}
let j = lookup[target.as_str()];
if depths[j].is_none() {
depths[j] = Some(depth + 1);
changed = true;
}
}
}
}
}
if !changed {
break;
}
}
let width = nodes
.iter()
.map(|n| n.label.chars().count())
.max()
.unwrap_or(0)
.max(18) as f64
* 8.0
+ 32.0;
let stride = width + 150.0;
let mut bottoms = BTreeMap::<usize, f64>::new();
let positions: Vec<_> = nodes
.iter()
.enumerate()
.map(|(i, n)| {
let depth = depths[i].unwrap_or(1);
let y = *bottoms.entry(depth).or_insert(30.0);
let height = 48.0 + 32.0 * n.slots.len() as f64;
bottoms.insert(depth, y + height + 65.0);
(30.0 + depth as f64 * stride, y, height)
})
.collect();
let canvas_width = positions
.iter()
.map(|(x, _, _)| x + width + 90.0)
.fold(0.0, f64::max);
let canvas_height = bottoms.values().copied().fold(0.0, f64::max);
let mut svg=format!("<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"heap-diagram\" role=\"img\" aria-label=\"Heap objects and references\" style=\"max-width:{canvas_width}px\" viewBox=\"0 0 {canvas_width} {canvas_height}\"><title>Heap objects and references</title><desc>{}</desc>",escape(source));
for (i, n) in nodes.iter().enumerate() {
let (x, y, height) = positions[i];
let class = if matches!(n.kind, Kind::Variables) {
"heap-variables"
} else {
"heap-object"
};
svg.push_str(&format!("<g class=\"{class}\"><rect x=\"{x}\" y=\"{y}\" width=\"{width}\" height=\"{height}\" rx=\"6\"/><text x=\"{}\" y=\"{}\" class=\"heap-title\">{}</text>",x+12.0,y+27.0,escape(&n.label)));
for (s, (slot, value)) in n.slots.iter().enumerate() {
let sy = y + 62.0 + s as f64 * 32.0;
let contents = if value.is_none() {
format!("{slot}: uninitialized")
} else {
slot.clone()
};
svg.push_str(&format!(
"<text x=\"{}\" y=\"{sy}\">{}</text>",
x + 12.0,
escape(&contents)
));
}
svg.push_str("</g>");
}
for (i, n) in nodes.iter().enumerate() {
let (x, y, _) = positions[i];
for (s, (_, value)) in n.slots.iter().enumerate() {
if let Some((kind, target)) = value {
let sy = y + 57.0 + s as f64 * 32.0;
let (tx, ey, edge_targeted) = if kind == "leased" {
let (n, slot) = edge_target(&nodes, target)?;
let (x, y, _) = positions[n];
(x + width + 12.0, y + 57.0 + slot as f64 * 32.0, true)
} else {
let (x, y, height) = positions[lookup[target.as_str()]];
(x, sy.clamp(y + 12.0, y + height - 12.0), false)
};
let sx = x + width;
let boxes: Vec<_> = positions
.iter()
.map(|&(x, y, h)| (x as i64, y as i64, width as i64, h as i64))
.collect();
let route = crate::routing::route(
((sx + 35.0) as i64, sy as i64),
(
(if edge_targeted { tx } else { tx - 20.0 }) as i64,
ey as i64,
),
&boxes,
)?;
let mut d = format!("M {sx} {sy} H {}", sx + 35.0);
for &(px, py) in route.iter().skip(1) {
d.push_str(&format!(" L {px} {py}"));
}
if !edge_targeted {
d.push_str(&format!(" L {tx} {ey}"));
}
let dot_class = if edge_targeted {
"heap-junction"
} else {
"heap-endpoint"
};
svg.push_str(&format!("<g class=\"heap-edge {kind}\"><path d=\"{d}\"/><circle class=\"{dot_class}\" cx=\"{tx}\" cy=\"{ey}\" r=\"3\" fill=\"currentColor\"/><text x=\"{}\" y=\"{}\">{kind}</text></g>",sx+5.0,sy-7.0));
}
}
}
svg.push_str("</svg>");
Ok(svg)
}
}
#![allow(unused)]
fn main() {
#[test]
fn routes_around_boxes_and_through_column_gaps() {
let boxes = [(100, 0, 80, 80), (100, 140, 80, 80)];
for (start, end) in [
((0, 40), (240, 40)),
((0, 110), (240, 110)),
((240, 40), (0, 40)),
((200, 40), (200, 180)),
] {
let path = route(start, end, &boxes).unwrap();
assert_eq!(path.first(), Some(&start));
assert_eq!(path.last(), Some(&end));
for pair in path.windows(2) {
assert!(pair[0].0 == pair[1].0 || pair[0].1 == pair[1].1);
assert!(clear(pair[0], pair[1], &boxes));
}
}
assert_eq!(
route((0, 110), (240, 110), &boxes).unwrap(),
vec![(0, 110), (240, 110)]
);
}
}
#![allow(unused)]
fn main() {
#[test]
fn cycles_self_loops_and_disconnected_cycles_render_deterministically() {
let rect = regex::Regex::new(
r#"<rect x="([\d.]+)" y="([\d.]+)" width="([\d.]+)" height="([\d.]+)""#,
)
.unwrap();
let paths = regex::Regex::new(r#"<path d="([^"]+)""#).unwrap();
for facts in [
"a = object(Node)\na.next = showned(a)",
"a = object(Node)\nb = object(Node)\na.next = showned(b)\nb.next = showned(a)",
"vars = variables()\na = object(Node)\nb = object(Node)\nvars.p = showned(a)\na.next = showned(b)\nb.next = showned(a)",
] {
let svg = render(facts).unwrap();
assert_eq!(svg, render(facts).unwrap());
assert!(!svg.contains("NaN"));
assert!(!svg.contains("heap-arrow"));
let nodes = parse(facts).unwrap();
let count = nodes.iter().flat_map(|n| &n.slots).filter(|(_, v)| v.is_some()).count();
assert_eq!(svg.matches("class=\"heap-endpoint\"").count(), count);
// Check every routed segment against every rendered rectangle, including
// the source and destination: only boundary contact is permitted.
let boxes: Vec<Vec<f64>> = rect.captures_iter(&svg).map(|c| (1..=4).map(|i| c[i].parse().unwrap()).collect()).collect();
for c in paths.captures_iter(&svg) {
let mut tokens = c[1].split_whitespace();
let mut last = (0.0_f64, 0.0_f64);
while let Some(op) = tokens.next() {
let x: f64 = tokens.next().unwrap().parse().unwrap();
let next = if op == "H" { (x,last.1) } else { (x,tokens.next().unwrap().parse().unwrap()) };
if op != "M" {
assert!(last.0 == next.0 || last.1 == next.1);
for b in &boxes {
let crosses = if last.0 == next.0 {
last.0 > b[0] && last.0 < b[0]+b[2] && last.1.min(next.1) < b[1]+b[3] && last.1.max(next.1) > b[1]
} else {
last.1 > b[1] && last.1 < b[1]+b[3] && last.0.min(next.0) < b[0]+b[2] && last.0.max(next.0) > b[0]
};
assert!(!crosses, "edge crosses box in {facts}");
}
}
last = next;
}
}
}
}
}
#![allow(unused)]
fn main() {
#[test]
fn leases_join_edges_and_shleases_target_objects() {
let facts = "vars = variables()\nα = object(C)\nβ = primitive(1)\nvars.p = owned(α)\nα.f = owned(β)\nvars.q = lease(α.f)\nvars.r = lease(vars.q)\nvars.s = shlease(β)";
let svg = render(facts).unwrap();
assert_eq!(svg.matches("class=\"heap-junction\"").count(), 2);
assert!(svg.contains("heap-edge shlease"));
for target in ["β", "α.missing", "vars.s", "α.empty"] {
let bad = format!("{facts}\nα.empty = uninitialized()\nvars.bad = lease({target})");
assert!(render(&bad).is_err(), "{target}");
}
assert!(render(
"vars = variables()\na = array(1)\nb = primitive(2)\nvars.q = lease(a[0])\na[0] = owned(b)"
)
.is_ok());
assert!(render(
"vars = variables()\na = primitive(1)\nvars.p = owned(a)\nvars.q = shlease(vars.p)"
)
.is_err());
}
}
Future notes
A future note is exploratory Markdown outside the current specification,
introduced at chapter top level by {future-note} and a stable unit ID.
Placement inside a list or blockquote is rejected. It must not declare an
associated formalization: :lean:, :rust:, and :tests: are errors, as is a
citation in place of the opening ID. Draft status is also rejected; a future
note is not a specification unit waiting for approval. Nested specification
units and legacy citation blocks remain forbidden.
Notes may refer to existing concepts through :uses: or links. Their IDs,
references, authored bodies, and strict-chapter coverage are checked normally.
The rendered header identifies a Future note, without a formalization selector
or Draft badge. Literal authoring samples stay literal.
Evidence validation reports future note with correspondence not applicable.
The absence of a formalization does not fail validation, but preparing or
recording a correspondence review for a future note is an error. Draft
specification units still require formalization and block evidence validation.
The check rejects declared formalization associations; it does not infer that
uncited code implements an idea.
#![allow(unused)]
fn main() {
fn parse_block(
source: &str,
path: &str,
range: Range<usize>,
info: &str,
) -> Result<Option<SpecUnit>> {
let (directive, argument) = info.split_once(char::is_whitespace).unwrap_or((info, ""));
let Some(kind) = UnitKind::parse(directive) else {
return Ok(None);
};
// Legacy directives carry path:declaration on their opening line. Keep their
// interpretation, but never mistake them for reviewed structured units.
if argument.contains(':') {
ensure!(
kind != UnitKind::FutureNote,
"future notes cannot have formalization citations; use a stable unit ID"
);
return Ok(None);
}
let id = argument.trim();
if kind.is_math() && id.is_empty() {
bail!(
"{directive} requires a stable unit ID, a :lean: citation, and an authored LaTeX body"
);
}
ensure!(
valid_id(id),
"expected one stable unit ID after {directive}"
);
let raw = &source[range.clone()];
let opening_end = raw
.find('\n')
.context("unit has no body or closing fence")?
+ 1;
let closing_start = raw
.trim_end_matches(['\n', '\r'])
.rfind('\n')
.context("unit has no closing fence")?
+ 1;
let opening = raw[..opening_end].trim_start();
let marker = opening
.chars()
.next()
.context("unit has no opening fence")?;
let width = opening.chars().take_while(|c| *c == marker).count();
let closing = raw[closing_start..].trim();
ensure!(
matches!(marker, '`' | '~')
&& closing.chars().all(|c| c == marker)
&& closing.len() >= width,
"structured unit must have an explicit matching closing fence"
);
let contents = &raw[opening_end..closing_start];
let mut unit = SpecUnit {
id: id.to_owned(),
kind,
draft: false,
source_path: path.to_owned(),
range,
body: String::new(),
raw: raw.to_owned(),
lean: vec![],
rust: vec![],
tests: vec![],
uses: vec![],
};
let mut seen = BTreeSet::new();
let mut body_start = 0;
for line in contents.split_inclusive('\n') {
let line_text = line.trim_end_matches(['\n', '\r']);
if !line_text.starts_with(':') {
break;
}
let (option, value) = line_text[1..]
.split_once(':')
.context("unit option must have the form :name: value")?;
ensure!(seen.insert(option), "duplicate :{option}: option");
let values: Vec<_> = value.split_whitespace().map(str::to_owned).collect();
ensure!(!values.is_empty(), ":{option}: must not be empty");
if option == "status" {
ensure!(
values == ["draft"],
":status: only accepts `draft`; omit it for units ready for correspondence review"
);
unit.draft = true;
body_start += line.len();
continue;
}
let target = match option {
"lean" => &mut unit.lean,
"rust" => &mut unit.rust,
"tests" => &mut unit.tests,
"uses" => &mut unit.uses,
_ => bail!("unknown unit option :{option}:"),
};
let unique: BTreeSet<_> = values.iter().collect();
ensure!(
unique.len() == values.len(),
"duplicate value in :{option}:"
);
*target = values;
body_start += line.len();
}
unit.body = contents[body_start..].trim_matches(['\n', '\r']).to_owned();
// mdBook expands these even inside fenced code. The packet must contain
// exactly the authored content, not untracked external substitutions.
let includes = regex::Regex::new(r"\{\{\s*#(?:include|rustdoc_include|playground)\b")?;
ensure!(
!includes.is_match(&unit.raw),
"mdBook include, rustdoc_include, and playground directives are unsupported inside structured units; write the content directly or cite another unit"
);
for event in Parser::new(&unit.body) {
if let Event::Start(Tag::CodeBlock(CodeBlockKind::Fenced(info))) = event {
let (directive, argument) = info.split_once(char::is_whitespace).unwrap_or((&info, ""));
ensure!(
UnitKind::parse(directive).is_none() || !argument.contains(':'),
"legacy citation directives cannot nest inside structured units; create a separate unit with :lean: and refer to it with :uses:"
);
}
}
ensure!(
!unit.body.trim().is_empty(),
"unit requires an authored body"
);
ensure!(
!unit.body.starts_with(':'),
"unit options must immediately follow the opening fence, before the blank line and body"
);
if kind == UnitKind::FutureNote {
ensure!(
unit.lean.is_empty() && unit.rust.is_empty() && unit.tests.is_empty(),
"future notes cannot have formalization citations (:lean:, :rust:, or :tests:); use a specification unit for formalized content"
);
ensure!(!unit.draft, "future notes cannot have :status: draft; they are exploratory notes, not unfinished specification units");
}
ensure!(
kind == UnitKind::FutureNote || unit.draft || !unit.lean.is_empty() || !unit.rust.is_empty(),
"unit requires :lean: or :rust: citations; use :status: draft while its formalization is pending"
);
ensure!(
unit.tests.is_empty() || !unit.rust.is_empty(),
":tests: requires a :rust: implementation citation"
);
ensure!(
unit.lean.is_empty() || unit.rust.is_empty(),
"a unit cannot mix :lean: and :rust: citations"
);
ensure!(
!matches!(kind, UnitKind::Theorem | UnitKind::Lemma)
|| !unit.lean.is_empty()
|| (unit.draft && unit.rust.is_empty()),
"theorem and lemma units require a Lean theorem; Rust tests are not proofs"
);
ensure!(
!matches!(
kind,
UnitKind::Judgment
| UnitKind::Rule
| UnitKind::Theorem
| UnitKind::Lemma
| UnitKind::Example
) || unit.lean.is_empty()
|| unit.lean.len() == 1,
"{} requires exactly one Lean citation",
kind.label()
);
for dependency in &unit.uses {
ensure!(valid_id(dependency), "invalid dependency ID `{dependency}`");
ensure!(dependency != id, "unit cannot depend on itself");
}
ensure!(
parse(&unit.body, path)?.is_empty(),
"named units cannot nest; cite the other unit with :uses: or a link"
);
Ok(Some(unit))
}
}
#![allow(unused)]
fn main() {
/// Parse top-level ID-first units. Legacy citation-first directives are excluded.
pub fn parse(source: &str, path: &str) -> Result<Vec<SpecUnit>> {
reject_removed_syntax(source, path)?;
let mut units = Vec::new();
let mut current = None;
let mut depth = 0;
for (event, range) in Parser::new(source).into_offset_iter() {
match event {
Event::Start(Tag::CodeBlock(CodeBlockKind::Fenced(info)))
if depth != 0 && info.split_whitespace().next() == Some("{future-note}") =>
{
let line = source[..range.start]
.bytes()
.filter(|b| *b == b'\n')
.count()
+ 1;
bail!("{path}:{line}: future notes must be top-level units, not nested in lists or blockquotes");
}
Event::Start(Tag::CodeBlock(CodeBlockKind::Fenced(info))) if depth == 0 => {
current = Some((range.start, info.into_string()));
depth += 1;
}
Event::End(TagEnd::CodeBlock) if current.is_some() => {
let (start, info) = current.take().expect("matched code block");
let line = source[..start].bytes().filter(|b| *b == b'\n').count() + 1;
if let Some(unit) = parse_block(source, path, start..range.end, &info)
.with_context(|| format!("{path}:{line}"))?
{
ensure!(
!units.iter().any(|other: &SpecUnit| other.id == unit.id),
"{path}:{line}: duplicate unit ID `{}`",
unit.id
);
units.push(unit);
}
depth -= 1;
}
Event::Start(_) => depth += 1,
Event::End(_) => depth -= 1,
_ => {}
}
}
Ok(units)
}
}
#![allow(unused)]
fn main() {
fn render_unit(
unit: &units::SpecUnit,
path: &str,
anchors: &BTreeMap<String, String>,
lean_root: Option<&Path>,
project_root: Option<&Path>,
) -> Result<String> {
let label = unit.kind.label();
let lower_label = label.to_ascii_lowercase();
let role = Role {
range: unit.range.clone(),
id: unit.id.clone(),
definition: true,
label: None,
lean: false,
};
let mut heading = render_role(&role, path, anchors, &lower_label)?;
if unit.draft {
heading.push_str(" <span class=\"block-label unit-status\" title=\"Formalization and correspondence review pending\">Draft</span>");
}
let (alternate, cited_source) = if !unit.lean.is_empty() {
let root = lean_root.context("Lean directives require preprocessor.dada.lean-source")?;
("Lean", lean::selected_source(root, &unit.lean, unit.kind)?)
} else if !unit.rust.is_empty() {
let root = project_root.context("Rust citations require a configured project root")?;
let mut cited = String::new();
for target in unit.rust.iter().chain(&unit.tests) {
let selected = crate::rust_source::select(root, target)?;
cited.push_str(&format!(
"<figcaption>{}</figcaption><pre><code class=\"language-rust\">{}</code></pre>",
escape(target),
escape(&selected.selected).replace('\n', " ")
));
}
("Rust", cited)
} else {
("", String::new())
};
let header = if alternate.is_empty() {
format!("<div class=\"lean-selector\"><div class=\"block-heading\">{heading}</div></div>")
} else {
selector_header(
label,
Some(&heading),
&format!("unit-{}", unit.id),
"rendered",
alternate,
)
};
let body = if unit.kind.is_math() {
let tex = escape(unit.body.trim()).replace('\n', " ");
format!("<div class=\"lean-grammar\"><div class=\"math-display\">\\[{tex}\\]</div></div>")
} else {
let body = render(
&unit.body,
path,
anchors,
lean_root,
project_root,
&unit.id,
&lower_label,
)?;
format!(
"<div class=\"lean-markdown-body\">\n\n{}\n\n</div>",
body.trim_matches('\n')
)
};
let markdown_class = if unit.kind.is_math() {
""
} else {
" lean-markdown"
};
Ok(format!("\n<figure class=\"lean-declaration lean-group{markdown_class}\">{header}{body}<div class=\"lean-source\">{cited_source}</div></figure>\n\n"))
}
}
#![allow(unused)]
fn main() {
pub fn prepare(inventory: &Inventory, unit: &str, extra: &[String]) -> Result<Self> {
if !link_audit::is_subject(unit) {
ensure!(
inventory.unit(unit)?.kind != UnitKind::FutureNote,
"future notes have no formalization to review"
);
}
let mut inputs = inventory.inputs(unit)?;
for path in extra {
inputs.push(inventory.extra_input(path)?);
}
inputs.sort_by(|a, b| a.key.cmp(&b.key));
let mut bundle = Self {
schema: SCHEMA,
unit: unit.to_owned(),
inputs,
digest: String::new(),
};
bundle.digest = bundle.content_digest()?;
ensure!(
bundle.integrity_errors().is_empty(),
"duplicate inputs in bundle"
);
Ok(bundle)
}
}
#![allow(unused)]
fn main() {
/// Record a review only after checking the same current input set used by check.
/// Recording a mismatch is permitted and will cause required review checks to fail.
pub fn record(
inventory: &Inventory,
bundle: &ReviewBundle,
review: &ReviewRecord,
) -> Result<PathBuf> {
let current = Inventory::load(&inventory.root)?;
let inventory = ¤t;
if !link_audit::is_subject(&bundle.unit) {
ensure!(
inventory.unit(&bundle.unit)?.kind != UnitKind::FutureNote,
"cannot record correspondence for a future note: it has no formalization"
);
}
let mut errors = validate_bundle(inventory, bundle)?;
errors.extend(validate_review(bundle, review));
ensure!(
errors.is_empty(),
"cannot record review: {}",
errors.join("; ")
);
ensure!(
link_audit::is_subject(&bundle.unit) || !inventory.unit(&bundle.unit)?.draft,
"cannot record review for draft unit {}: complete its formalization and matching citations, remove :status: draft, then prepare and review a new bundle",
bundle.unit
);
for previous in &review.supersedes {
ensure!(valid_digest(previous), "invalid superseded review digest");
let old: ReviewRecord = read_json(
&inventory
.root
.join("evidence/records")
.join(&bundle.unit)
.join(format!("{previous}.json")),
)?;
ensure!(
old.digest()? == *previous,
"superseded review contents differ"
);
let prior: ReviewBundle = read_json(
&inventory
.root
.join("evidence/bundles")
.join(format!("{}.json", old.bundle)),
)?;
ensure!(
prior.unit == bundle.unit,
"superseded review must concern the same unit"
);
}
save_bundle(inventory, bundle)?;
write_immutable(
&inventory.root,
&PathBuf::from("evidence/records")
.join(&bundle.unit)
.join(format!("{}.json", review.digest()?)),
review,
)
}
}
#![allow(unused)]
fn main() {
/// Check all required units, including record presence, minimum inputs and freshness.
/// Neither the review's conclusion nor a passing result establishes a Lean proof.
pub fn check(inventory: &Inventory) -> Result<Report> {
let mut report = Report::default();
if let Err(error) = crate::mechanical::records(&inventory.root) {
report.issues.push(Issue {
unit: None,
message: "malformed mechanical execution evidence".into(),
details: vec![format!("{error:#}")],
});
}
let mut bundles = BTreeMap::new();
for path in json_files(&inventory.root, &inventory.root.join("evidence/bundles"))? {
match read_json::<ReviewBundle>(&path) {
Ok(bundle) => {
let errors = bundle.integrity_errors();
let name = path
.file_stem()
.and_then(|name| name.to_str())
.unwrap_or("");
if !errors.is_empty() || name != bundle.digest {
report.issues.push(Issue {
unit: inventory
.units
.contains_key(&bundle.unit)
.then_some(bundle.unit.clone()),
message: format!("invalid evidence bundle {}", path.display()),
details: errors,
});
} else {
bundles.insert(bundle.digest.clone(), bundle);
}
}
Err(error) => report.issues.push(Issue {
unit: None,
message: "malformed evidence bundle".into(),
details: vec![format!("{error:#}")],
}),
}
}
let audits = AuditInventory::build(inventory)?;
// Parse every saved decision, including retired subjects. Removing a link or
// unit retires its obligation, not the integrity checks on its history.
let mut all_records: BTreeMap<String, BTreeMap<String, ReviewRecord>> = BTreeMap::new();
let records_root = inventory.root.join("evidence/records");
for path in json_tree(&inventory.root, &records_root)? {
let parsed = (|| -> Result<(String, String, ReviewRecord)> {
let review: ReviewRecord = read_json(&path)?;
let digest = review.digest()?;
ensure!(
path.file_stem().and_then(|name| name.to_str()) == Some(&digest),
"record filename does not match contents"
);
let bundle = bundles
.get(&review.bundle)
.context("record's bundle is missing or malformed")?;
ensure!(
path == records_root
.join(&bundle.unit)
.join(format!("{digest}.json")),
"record filed under wrong subject"
);
let errors = validate_review(bundle, &review);
ensure!(errors.is_empty(), "invalid review: {}", errors.join("; "));
Ok((bundle.unit.clone(), digest, review))
})();
match parsed {
Ok((subject, digest, review)) => {
all_records
.entry(subject)
.or_default()
.insert(digest, review);
}
Err(error) => report.issues.push(Issue {
unit: None,
message: "malformed stored review".into(),
details: vec![format!("{}: {error:#}", path.display())],
}),
}
}
for (id, records) in &all_records {
for review in records.values() {
for previous in &review.supersedes {
if !records.contains_key(previous) {
report.issues.push(Issue {
unit: Some(id.clone()),
message: "review supersedes absent or unrelated evidence".into(),
details: vec![previous.clone()],
});
}
}
}
}
let required_subjects: BTreeSet<_> = inventory
.required
.iter()
.chain(audits.manifests.keys())
.cloned()
.collect();
let mut current_active = BTreeMap::new();
for id in &required_subjects {
// Derive inputs even for drafts: malformed
// citations never disappear because a formalization is unfinished.
let required = match if link_audit::is_subject(id) {
audits.inputs(inventory, id)
} else {
inventory.inputs(id)
} {
Ok(inputs) => inputs,
Err(error) => {
report.issues.push(Issue {
unit: Some(id.clone()),
message: "cannot resolve required evidence inputs".into(),
details: vec![format!("{error:#}")],
});
report.statuses.push(UnitStatus {
unit: id.clone(),
evidence: "invalid sources",
correspondence: "not checked",
});
continue;
}
};
if inventory
.units
.get(id)
.is_some_and(|unit| unit.kind == UnitKind::FutureNote)
{
report.statuses.push(UnitStatus {
unit: id.clone(),
evidence: "future note",
correspondence: "not applicable",
});
continue;
}
if inventory.units.get(id).is_some_and(|unit| unit.draft) {
report.statuses.push(UnitStatus {
unit: id.clone(),
evidence: "draft",
correspondence: "not asserted",
});
report.issues.push(Issue {
unit: Some(id.clone()),
message: format!("draft unit {id} requires formalization"),
details: vec![
"draft status preserves the unit's semantic kind but cannot count as completed correspondence evidence".into(),
],
});
continue;
}
let mut current = BTreeSet::new();
let mut stale = Vec::new();
for bundle in bundles.values().filter(|bundle| &bundle.unit == id) {
// Historical bundles compare with one independently derived current
// manifest. Re-reading all sources for each past review made the
// ordinary evidence test grow with the entire review history.
let errors = validate_bundle_against(inventory, bundle, required.clone())?;
if errors.is_empty() {
current.insert(bundle.digest.clone());
} else {
stale.extend(errors);
}
}
let empty_records = BTreeMap::new();
let records = all_records.get(id).unwrap_or(&empty_records);
let superseded: BTreeSet<_> = records
.values()
.flat_map(|review| review.supersedes.iter().cloned())
.collect();
let stale_active = records.iter().any(|(digest, review)| {
!superseded.contains(digest) && !current.contains(&review.bundle)
});
let active: Vec<_> = records
.iter()
.filter(|(digest, review)| {
current.contains(&review.bundle) && !superseded.contains(*digest)
})
.map(|(_, review)| review)
.collect();
// Cross-review order decisions may rely only on an entirely current,
// positive subject; a conflicting or stale active record blocks it.
if !stale_active
&& !active.is_empty()
&& active
.iter()
.all(|review| review.conclusion == Conclusion::Corresponds)
{
current_active.insert(
id.clone(),
active.iter().map(|review| (*review).clone()).collect(),
);
}
let evidence = if stale_active {
"stale"
} else if !current.is_empty() {
"current"
} else if !stale.is_empty() {
"stale"
} else {
"missing"
};
let correspondence = if stale_active {
"stale decision"
} else if active.is_empty() {
"missing"
} else if active
.iter()
.any(|review| review.conclusion == Conclusion::Mismatch)
{
"mismatch"
} else if active
.iter()
.any(|review| review.conclusion == Conclusion::Inconclusive)
{
"inconclusive"
} else {
"corresponds"
};
report.statuses.push(UnitStatus {
unit: id.clone(),
evidence,
correspondence,
});
if correspondence != "corresponds" {
let mut details = if evidence == "stale" {
stale
} else {
Vec::new()
};
details.sort();
details.dedup();
if evidence == "current" && active.is_empty() {
details.push("preparing a bundle does not record a completed review".into());
}
report.issues.push(Issue {
unit: Some(id.clone()),
message: format!("{evidence} evidence for {id}: correspondence {correspondence}"),
details,
});
}
}
for (unit, message) in link_audit::cross_validate(&audits, ¤t_active) {
report.issues.push(Issue {
unit: Some(unit),
message,
details: Vec::new(),
});
}
Ok(report)
}
}
#![allow(unused)]
fn main() {
#[test]
fn future_notes_render_without_formalization_or_draft_status() {
let files = Sources::new();
let source = "# Ideas\n\n````{future-note} future.views\n\nA possible **extension**.\n\n```dada\nclass Token {}\n```\n````\n\nSee {anchor-ref}`future.views`.";
let parsed = units::parse(source, "model.md").unwrap();
assert_eq!(parsed[0].kind, UnitKind::FutureNote);
assert!(!parsed[0].draft);
units::validate_coverage(&source[..source.find("\n\nSee").unwrap()], "model.md").unwrap();
let output = render(source, &files.lean()).unwrap();
assert!(output.contains("future note: future.views"));
assert!(output.contains("href=\"#claim-future.views\""));
assert!(output.contains("A possible **extension**."));
assert!(output.contains("class Token {}"));
assert!(!output.contains("type=\"radio\""));
assert!(!output.contains("unit-status"));
}
}
#![allow(unused)]
fn main() {
#[test]
fn future_notes_reject_formalizations_and_nested_specifications() {
let files = Sources::new();
for option in [
":lean: Model:initial",
":rust: tool.rs:check",
":tests: tool.rs:checks",
":status: draft",
] {
let source = format!("```{{future-note}} future.views\n{option}\n\nIdea.\n```");
let error = format!("{:#}", units::parse(&source, "model.md").unwrap_err());
assert!(error.contains("model.md:1"), "{error}");
assert!(error.contains("future notes cannot have"), "{error}");
assert!(render(&source, &files.lean()).is_err());
}
for source in [
"```{future-note} Model:initial\nIdea.\n```",
"> ```{future-note} future.views\n> :lean: Model:initial\n> \n> Idea.\n> ```",
"- ```{future-note} future.views\n :rust: tool.rs:check\n \n Idea.\n ```",
"````{future-note} future.views\n\n```{definition} Model:initial\nFormalized.\n```\n````",
"````{future-note} future.views\n\n```{definition} nested\n:lean: Model:initial\n\nFormalized.\n```\n````",
] {
assert!(units::parse(source, "model.md").is_err(), "{source}");
assert!(render(source, &files.lean()).is_err(), "{source}");
}
assert!(lean::select(&files.lean(), "Model:initial", UnitKind::FutureNote).is_err());
let literal =
"````text\n```{future-note} sample\n:lean: NotAReal:Citation\n\nLiteral syntax.\n```\n````";
assert!(units::parse(literal, "model.md").unwrap().is_empty());
assert_eq!(render(literal, &files.lean()).unwrap(), literal);
}
}
#![allow(unused)]
fn main() {
#[test]
fn future_notes_are_publishable_but_cannot_receive_correspondence_reviews() {
let fixture = Fixture::new();
let note = "\n```{future-note} future.views\n:uses: model.variable\n\nExplore richer views of {anchor-ref}`model.variable`.\n```\n";
fixture.write("md/model.md", &format!("{MODEL}{note}"));
let inventory = fixture.inventory();
assert!(inventory.required.contains("future.views"));
assert!(inventory
.inputs("future.views")
.unwrap()
.iter()
.any(|input| input.key == "unit:model.variable"));
for id in ["model.variable", "model.empty"] {
let bundle = ReviewBundle::prepare(&inventory, id, &[]).unwrap();
evidence::record(&inventory, &bundle, &review(&bundle)).unwrap();
}
for id in link_audit::subjects(&inventory).unwrap() {
let bundle = ReviewBundle::prepare(&inventory, &id, &[]).unwrap();
evidence::record(&inventory, &bundle, &review(&bundle)).unwrap();
}
let report = evidence::check(&inventory).unwrap();
assert!(report.is_ok(), "{}", report.render(&inventory));
let status = report
.statuses
.iter()
.find(|s| s.unit == "future.views")
.unwrap();
assert_eq!(status.evidence, "future note");
assert_eq!(status.correspondence, "not applicable");
assert!(ReviewBundle::prepare(&inventory, "future.views", &[]).is_err());
// Reusing an old specification approval cannot approve a future note.
let bundle = ReviewBundle::prepare(&inventory, "model.variable", &[]).unwrap();
fixture.write(
"md/model.md",
&format!(
"{}{}",
MODEL.replace(
"```{definition} model.variable\n:lean: Fixture:Variable",
"```{future-note} model.variable"
),
note
),
);
let error = evidence::record(&fixture.inventory(), &bundle, &review(&bundle)).unwrap_err();
assert!(error
.to_string()
.contains("cannot record correspondence for a future note"));
fixture.write(
"md/model.md",
&format!(
"{MODEL}{}",
note.replace(":uses: model.variable", ":uses: missing.unit")
),
);
assert!(Inventory::load(&fixture.0).is_err());
}
}