Files
cflmy c7f3a8422c fix(ci): anchor AST goldens to LF bytes and test CRLF explicitly
The Windows CI failure was a checkout byte-identity problem, not a Markdown
semantics change: CRLF goldens compared with LF parser output produced
'0 line(s) differ'.

- add .gitattributes: text files are LF, native products are binary, and the
  intentional CRLF fixture stays a byte fixture
- report the first differing byte and whether only line endings differ
- fail early when a golden contains CR instead of the opaque mismatch
- assert exactly one CRLF fixture and that its golden is canonical LF
- add a markdown test proving CRLF/LF have equal structure while spans remain
  byte offsets into the original source
2026-11-20 13:54:16 +08:00

382 lines
13 KiB
Rust

//! AST conformance golden tests for the frozen `marqdo.md.v1` Markdown profile.
//!
//! Each `tests/conformance/ast/*.mq.md` fixture is parsed with
//! [`marqdo_markdown::parse`] and the canonical AST root is serialized to
//! pretty JSON. The result is compared byte-for-byte with the sibling
//! `*.ast.json` golden.
//!
//! Regenerate goldens deliberately with:
//!
//! ```text
//! UPDATE_GOLDENS=1 cargo test -p marqdo-cli --test conformance_ast
//! ```
//!
//! Updating is the *only* way goldens change; the test fails if a fixture has
//! no golden and if a golden has no fixture.
use std::fs;
use std::path::{Path, PathBuf};
/// Repository root (the workspace above `crates/cli`).
fn repo_root() -> PathBuf {
Path::new(env!("CARGO_MANIFEST_DIR"))
.parent()
.expect("crates/cli has a parent")
.parent()
.expect("crates has a parent")
.to_path_buf()
}
fn ast_dir() -> PathBuf {
repo_root().join("tests").join("conformance").join("ast")
}
/// All fixture paths, sorted by file name for deterministic ordering.
fn fixture_paths() -> Vec<PathBuf> {
let dir = ast_dir();
let mut paths: Vec<PathBuf> = fs::read_dir(&dir)
.unwrap_or_else(|error| panic!("cannot read {}: {error}", dir.display()))
.filter_map(Result::ok)
.map(|entry| entry.path())
.filter(|path| path.extension().is_some_and(|ext| ext == "md"))
.collect();
paths.sort();
paths
}
/// Serialize the canonical AST view with a trailing newline.
fn golden_text(source: &str) -> String {
let document = marqdo_markdown::parse(source);
let mut text = serde_json::to_string_pretty(&document.root)
.expect("the canonical AST view is always serializable");
text.push('\n');
text
}
/// Golden path for a fixture: `foo.mq.md` -> `foo.ast.json` (the extension
/// replacement must keep the `.mq` marker, not overwrite `md` only).
fn golden_path(fixture: &Path) -> PathBuf {
let name = fixture
.file_name()
.expect("fixture has a file name")
.to_string_lossy();
let stem = name
.strip_suffix(".mq.md")
.unwrap_or_else(|| panic!("fixture `{}` must end in .mq.md", fixture.display()));
fixture.with_file_name(format!("{stem}.ast.json"))
}
fn write_golden(path: &Path, text: &str) {
fs::write(path, text)
.unwrap_or_else(|error| panic!("cannot write golden {}: {error}", path.display()));
}
/// First byte offset at which two inputs differ, if any.
fn first_byte_difference(expected: &[u8], actual: &[u8]) -> Option<usize> {
expected
.iter()
.zip(actual.iter())
.position(|(left, right)| left != right)
.or_else(|| (expected.len() != actual.len()).then_some(expected.len().min(actual.len())))
}
/// Render a short escaped byte window around `offset`.
fn byte_window(bytes: &[u8], offset: usize) -> String {
let start = offset.saturating_sub(8);
let end = (offset + 8).min(bytes.len());
bytes[start..end]
.iter()
.map(|byte| format!("{byte:02x}"))
.collect::<Vec<_>>()
.join(" ")
}
/// Whether two byte strings are identical after normalizing CRLF to LF.
fn only_line_endings_differ(expected: &[u8], actual: &[u8]) -> bool {
fn normalize(bytes: &[u8]) -> Vec<u8> {
let mut out = Vec::with_capacity(bytes.len());
let mut index = 0;
while index < bytes.len() {
if bytes[index] == b'\r' && bytes.get(index + 1) == Some(&b'\n') {
out.push(b'\n');
index += 2;
} else {
out.push(bytes[index]);
index += 1;
}
}
out
}
expected != actual && normalize(expected) == normalize(actual)
}
/// Report a compact, byte-aware diff summary for one fixture.
fn report_mismatch(fixture: &Path, expected: &str, actual: &str) {
let expected_lines: Vec<&str> = expected.lines().collect();
let actual_lines: Vec<&str> = actual.lines().collect();
let mut differences = 0usize;
let mut first: Option<usize> = None;
for index in 0..expected_lines.len().max(actual_lines.len()) {
if expected_lines.get(index) != actual_lines.get(index) {
differences += 1;
if first.is_none() {
first = Some(index);
}
}
}
let first = first.unwrap_or(0);
let start = first.saturating_sub(3);
let end = (first + 8).min(expected_lines.len().max(actual_lines.len()));
let mut message = format!(
"AST golden mismatch for `{}`.\n\
expected {} byte(s), actual {} byte(s).\n\
{} line(s) differ (first at line {}).\n",
fixture.display(),
expected.len(),
actual.len(),
differences,
first + 1
);
match first_byte_difference(expected.as_bytes(), actual.as_bytes()) {
Some(offset) => {
message.push_str(&format!(
"first byte difference at offset {offset}.\n\
expected bytes: {}\n\
actual bytes: {}\n",
byte_window(expected.as_bytes(), offset),
byte_window(actual.as_bytes(), offset)
));
if only_line_endings_differ(expected.as_bytes(), actual.as_bytes()) {
message.push_str(
"the only difference is line endings (CRLF vs LF); \
this is a checkout/fixture byte-identity problem, not a \
Markdown semantics change. Ensure .gitattributes keeps \
goldens at LF and keep intentional CRLF inputs as byte \
fixtures.\n",
);
}
}
None => message.push_str("the two strings are byte-identical.\n"),
}
message.push_str("--- expected (golden) ---\n");
for index in start..end {
message.push_str(&format!(
"{:>4} | {}\n",
index + 1,
expected_lines.get(index).copied().unwrap_or("<missing>")
));
}
message.push_str("--- actual (parser) ---\n");
for index in start..end {
message.push_str(&format!(
"{:>4} | {}\n",
index + 1,
actual_lines.get(index).copied().unwrap_or("<missing>")
));
}
// The most common cause is an executable payload of the wrong shape. Point
// at the offending source region so authors can fix the fixture quickly.
if let Ok(source) = fs::read_to_string(fixture) {
if let Ok(value) = serde_json::from_str::<serde_json::Value>(expected) {
if let Some(span) = value.get("span") {
let start = span.get("start").and_then(serde_json::Value::as_u64);
let end = span.get("end").and_then(serde_json::Value::as_u64);
if let (Some(start), Some(end)) = (start, end) {
let slice = source.get(start as usize..end as usize).unwrap_or("");
message.push_str(&format!("first node source: {slice:?}\n"));
}
}
}
}
message.push_str(
"Run `UPDATE_GOLDENS=1 cargo test -p marqdo-cli --test conformance_ast` \
only for an intentional profile change.\n",
);
panic!("{message}");
}
#[test]
fn ast_goldens_match_the_frozen_profile() {
let fixtures = fixture_paths();
assert!(
fixtures.len() >= 100,
"the P0 corpus must keep at least 100 AST fixtures, found {}",
fixtures.len()
);
let update = std::env::var_os("UPDATE_GOLDENS").is_some_and(|value| value == "1");
let mut updated = 0usize;
let mut failures: Vec<String> = Vec::new();
for fixture in &fixtures {
let source = fs::read_to_string(fixture)
.unwrap_or_else(|error| panic!("cannot read fixture {}: {error}", fixture.display()));
let golden = golden_path(fixture);
let actual = golden_text(&source);
if update {
write_golden(&golden, &actual);
updated += 1;
continue;
}
let expected = fs::read_to_string(&golden).unwrap_or_else(|error| {
panic!(
"missing AST golden for `{}` ({error}).\n\
Run `UPDATE_GOLDENS=1 cargo test -p marqdo-cli --test conformance_ast`.",
fixture.display()
)
});
if expected != actual {
failures.push(fixture.display().to_string());
}
}
if update {
println!(
"UPDATE_GOLDENS=1: rewrote {updated} AST golden(s) under {}",
ast_dir().display()
);
return;
}
// A golden without a fixture is stale corpus output; fail rather than keep
// silently ignored files.
let golden_count = fs::read_dir(ast_dir())
.expect("ast fixture directory is readable")
.filter_map(Result::ok)
.filter(|entry| {
entry
.path()
.extension()
.is_some_and(|extension| extension == "json")
})
.count();
assert_eq!(
golden_count,
fixtures.len(),
"every AST fixture needs exactly one golden (orphan *.ast.json files?)"
);
if failures.is_empty() {
return;
}
// Re-read the mismatching fixtures to produce a detailed, line-based diff.
// This keeps the common pass path cheap and the failure path informative.
for fixture in &fixtures {
let source = fs::read_to_string(fixture).expect("fixture is readable");
let golden = golden_path(fixture);
let expected = fs::read_to_string(&golden).expect("golden is readable");
let actual = golden_text(&source);
if expected != actual {
report_mismatch(fixture, &expected, &actual);
}
}
}
/// Goldens are canonical JSON: UTF-8, LF line endings and a trailing newline.
/// A CRLF checkout used to fail with "0 line(s) differ", which hid the real
/// cause. This test fails early with a direct byte-level diagnosis instead.
#[test]
fn ast_goldens_use_canonical_lf_bytes() {
let dir = ast_dir();
let mut checked = 0usize;
for entry in fs::read_dir(&dir).expect("ast fixture directory is readable") {
let path = entry.expect("directory entry").path();
if !path
.extension()
.is_some_and(|extension| extension == "json")
{
continue;
}
let bytes = fs::read(&path).expect("golden is readable");
assert!(
std::str::from_utf8(&bytes).is_ok(),
"golden {} is not valid UTF-8",
path.display()
);
assert!(
!bytes.contains(&b'\r'),
"golden {} contains CR bytes; canonical JSON goldens must use LF only",
path.display()
);
assert!(
bytes.ends_with(b"\n"),
"golden {} must end with exactly one trailing LF",
path.display()
);
checked += 1;
}
assert!(
checked >= 100,
"expected the full AST golden corpus, saw {checked}"
);
}
/// The profile's line-ending semantics are tested with an explicit byte
/// fixture, not by relying on the checkout platform. Exactly one fixture keeps
/// CRLF bytes; see `.gitattributes`.
#[test]
fn crlf_fixture_is_preserved_as_bytes() {
let fixture = ast_dir().join("146-crlf-line-endings.mq.md");
let bytes = fs::read(&fixture).expect("CRLF fixture is readable");
assert!(
bytes.windows(2).any(|window| window == b"\r\n"),
"the CRLF fixture lost its CRLF bytes (checkout normalization?)"
);
assert!(
bytes
.iter()
.enumerate()
.all(|(index, byte)| *byte != b'\r' || bytes.get(index + 1) == Some(&b'\n')),
"CRLF fixture contains a lone CR byte"
);
assert!(
!bytes
.split(|byte| *byte == b'\n')
.any(|line| !line.ends_with(b"\r") && !line.is_empty()),
"CRLF fixture mixes bare LF line endings with CRLF"
);
let golden = ast_dir().join("146-crlf-line-endings.ast.json");
let golden_bytes = fs::read(&golden).expect("CRLF golden is readable");
assert!(
!golden_bytes.contains(&b'\r'),
"the CRLF fixture's golden is canonical LF JSON, not CRLF text"
);
let mut crlf_fixtures = 0usize;
for entry in fs::read_dir(ast_dir()).expect("ast fixture directory is readable") {
let path = entry.expect("directory entry").path();
if path.extension().is_some_and(|extension| extension == "md") {
let bytes = fs::read(&path).expect("fixture is readable");
if bytes.contains(&b'\r') {
assert_eq!(
path.file_name(),
fixture.file_name(),
"unexpected CRLF fixture {}; add it deliberately and document it",
path.display()
);
crlf_fixtures += 1;
}
}
}
assert_eq!(
crlf_fixtures, 1,
"exactly one CRLF byte fixture is expected"
);
}
#[test]
fn byte_diff_helpers_distinguish_line_endings_from_semantics() {
assert_eq!(first_byte_difference(b"abc", b"abc"), None);
assert_eq!(first_byte_difference(b"abc", b"abd"), Some(2));
assert_eq!(first_byte_difference(b"ab", b"abc"), Some(2));
assert!(only_line_endings_differ(b"a\nb\n", b"a\r\nb\r\n"));
assert!(!only_line_endings_differ(b"a\nb\n", b"a\nc\n"));
assert!(!only_line_endings_differ(b"a\r\nb\n", b"a\r\nb\n"));
}