Documentation
// Copyright © 2026 Stephan Kunz
//! Low-level XML parsing helpers.

use core::ops::Range;

use crate::xml_element::XmlElement;

pub(crate) fn skip_whitespace(text: &str, mut pos: usize) -> usize {
	let b = text.as_bytes();
	while pos < b.len() && matches!(b[pos], b' ' | b'\t' | b'\n' | b'\r') {
		pos += 1;
	}
	pos
}

/// Search `bytes[start..]` for `needle`; return absolute index of first byte.
pub(crate) fn find_bytes(bytes: &[u8], start: usize, needle: &[u8]) -> Option<usize> {
	if needle.is_empty() {
		return Some(start);
	}
	let end = bytes.len().checked_sub(needle.len() - 1)?;
	if start >= end {
		return None;
	}
	bytes[start..end + needle.len() - 1]
		.windows(needle.len())
		.position(|w| w == needle)
		.map(|p| p + start)
}

/// Scan from `start` (position after `<`) for the unquoted `>` that closes a
/// tag.  Returns the index *after* `>`.
pub(crate) fn find_tag_end(text: &str, start: usize) -> Option<usize> {
	let b = text.as_bytes();
	let mut i = start;
	let mut q: u8 = 0;
	while i < b.len() {
		match b[i] {
			c @ (b'"' | b'\'') if q == 0 => q = c,
			c if c == q => q = 0,
			b'>' if q == 0 => return Some(i + 1),
			_ => {}
		}
		i += 1;
	}
	None
}

/// Extract the tag name starting at `pos` (first char after `<` or `</`).
pub(crate) fn extract_tag_name(text: &str, pos: usize) -> &str {
	let b = text.as_bytes();
	let mut end = pos;
	while end < b.len() && !matches!(b[end], b' ' | b'\t' | b'\n' | b'\r' | b'>' | b'/' | b'?') {
		end += 1;
	}
	&text[pos..end]
}

pub(crate) fn self_closing(bytes: &[u8], tag_end: usize) -> bool {
	tag_end >= 2 && bytes[tag_end - 2] == b'/'
}

/// Find the range of the close tag `</tag_name>` that matches the open tag
/// ending at `start`, counting nested same-named elements.
pub(crate) fn find_close_tag(text: &str, start: usize, tag_name: &str) -> Option<Range<usize>> {
	let b = text.as_bytes();
	let tag = tag_name.as_bytes();
	let mut pos = start;
	let mut depth: usize = 1;

	while pos < b.len() {
		let lt = b[pos..].iter().position(|&c| c == b'<')?;
		pos += lt;

		// Comment
		if b.get(pos + 1..pos + 4) == Some(b"!--") {
			pos = find_bytes(b, pos + 4, b"-->")? + 3;
			continue;
		}
		// PI
		if b.get(pos + 1) == Some(&b'?') {
			pos = find_bytes(b, pos + 2, b"?>")? + 2;
			continue;
		}
		// CDATA
		if b.get(pos + 1..pos + 9) == Some(b"![CDATA[") {
			pos = find_bytes(b, pos + 9, b"]]>")? + 3;
			continue;
		}

		if b.get(pos + 1) == Some(&b'/') {
			// Close tag — check if it matches our name
			let ns = pos + 2;
			if b.get(ns..ns + tag.len()) == Some(tag)
				&& matches!(
					b.get(ns + tag.len()),
					Some(&b'>') | Some(&b' ') | Some(&b'\t') | Some(&b'\n') | Some(&b'\r')
				) {
				depth -= 1;
				if depth == 0 {
					let gt = b[ns + tag.len()..]
						.iter()
						.position(|&c| c == b'>')?;
					return Some(pos..ns + tag.len() + gt + 1);
				}
			}
			// Skip past this close tag
			pos += b[pos..].iter().position(|&c| c == b'>')? + 1;
			continue;
		}

		// Opening tag — depth-track only same name
		let ns = pos + 1;
		if b.get(ns..ns + tag.len()) == Some(tag)
			&& matches!(
				b.get(ns + tag.len()),
				Some(&b'>') | Some(&b' ') | Some(&b'\t') | Some(&b'\n') | Some(&b'\r') | Some(&b'/')
			) {
			let te = find_tag_end(text, ns)?;
			if !self_closing(b, te) {
				depth += 1;
			}
			pos = te;
			continue;
		}

		// Any other opening tag: skip its opening marker
		pos = find_tag_end(text, pos + 1)?;
	}

	None
}

/// Parse one node starting at `pos` (must point to `<`).
/// `content_end` is the limit for sibling searches on the returned element.
pub(crate) fn parse_element_at(xml_text: &str, pos: usize, content_end: usize) -> Option<XmlElement<'_>> {
	let b = xml_text.as_bytes();
	if b.get(pos) != Some(&b'<') {
		return None;
	}

	// Comment, PI, CDATA — handled by parse_body_node_at, not here
	if b.get(pos + 1..pos + 4) == Some(b"!--")
		|| b.get(pos + 1) == Some(&b'?')
		|| b.get(pos + 1..pos + 9) == Some(b"![CDATA[")
		|| b.get(pos + 1) == Some(&b'/')
	{
		return None;
	}

	// Regular element
	let tag_end = find_tag_end(xml_text, pos + 1)?;
	if self_closing(b, tag_end) {
		return Some(XmlElement::new(xml_text, pos..tag_end, tag_end..tag_end, content_end));
	}

	let tag_name = extract_tag_name(xml_text, pos + 1);
	let close = find_close_tag(xml_text, tag_end, tag_name)?;
	Some(XmlElement::new(xml_text, pos..tag_end, close, content_end))
}

/// Advance past whitespace and any PI nodes (`<?…?>`), returning the next
/// position of a valid body node, or `None` if `end` is reached or a
/// close-tag is next.
pub(crate) fn advance_body_cursor(xml_text: &str, mut pos: usize, end: usize) -> Option<usize> {
	let b = xml_text.as_bytes();
	loop {
		pos = skip_whitespace(xml_text, pos);
		if pos >= end {
			return None;
		}
		if b[pos] != b'<' {
			return Some(pos); // text node
		}
		if b.get(pos + 1) == Some(&b'/') {
			return None; // close tag — stop
		}
		if b.get(pos + 1) == Some(&b'?') {
			// Skip PI silently (not valid in body)
			pos = find_bytes(b, pos + 2, b"?>")? + 2;
			continue;
		}
		return Some(pos);
	}
}

/// Parse one body node at `pos` (result of `advance_body_cursor`).
/// Returns `None` on malformed input.
pub(crate) fn parse_body_node_at(xml_text: &str, pos: usize, content_end: usize) -> Option<crate::body::BodyNode<'_>> {
	use crate::body::{BodyComment, BodyNode};
	use crate::xml_text::XmlText;

	let b = xml_text.as_bytes();

	if b.get(pos) != Some(&b'<') {
		// Plain text node — scan to next '<' or content_end
		let mut end = pos;
		while end < content_end && b[end] != b'<' {
			end += 1;
		}
		return Some(BodyNode::Text(XmlText::new(xml_text, pos..end, content_end)));
	}

	// Comment
	if b.get(pos + 1..pos + 4) == Some(b"!--") {
		let end = find_bytes(b, pos + 4, b"-->")? + 3;
		return Some(BodyNode::Comment(BodyComment::new(xml_text, pos..end, content_end)));
	}

	// CDATA — surfaces as Text
	if b.get(pos + 1..pos + 9) == Some(b"![CDATA[") {
		let end = find_bytes(b, pos + 9, b"]]>")? + 3;
		return Some(BodyNode::Text(XmlText::new(xml_text, pos..end, content_end)));
	}

	// Regular element
	parse_element_at(xml_text, pos, content_end).map(crate::body::BodyNode::Element)
}

/// Convenience wrapper used by leaf node `next_sibling()` methods.
pub(crate) fn next_body_sibling(xml_text: &str, after: usize, content_end: usize) -> Option<crate::body::BodyNode<'_>> {
	let pos = advance_body_cursor(xml_text, after, content_end)?;
	parse_body_node_at(xml_text, pos, content_end)
}

// ── tests ────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
	use super::*;

	#[test]
	fn find_bytes_empty_needle() {
		assert_eq!(find_bytes(b"abc", 2, b""), Some(2));
	}

	#[test]
	fn find_bytes_needle_larger_than_haystack() {
		// `bytes.len() < needle.len() - 1` triggers the `checked_sub` None branch.
		assert_eq!(find_bytes(b"", 0, b"abc"), None);
		assert_eq!(find_bytes(b"x", 0, b"abc"), None);
	}

	#[test]
	fn parse_element_at_rejects_non_open_bracket() {
		assert!(parse_element_at("abc", 0, 3).is_none());
	}

	#[test]
	fn parse_element_at_rejects_close_tag() {
		assert!(parse_element_at("</a>", 0, 4).is_none());
	}

	#[test]
	fn parse_element_at_fails_on_unclosed_comment() {
		assert!(parse_element_at("<!--x", 0, 5).is_none());
	}

	#[test]
	fn parse_element_at_fails_on_unclosed_pi() {
		assert!(parse_element_at("<?x", 0, 3).is_none());
	}

	#[test]
	fn parse_element_at_fails_on_unclosed_cdata() {
		assert!(parse_element_at("<![CDATA[x", 0, 10).is_none());
	}

	#[test]
	fn parse_element_at_fails_on_unclosed_tag() {
		// `find_tag_end` returns None — no `>` in the input.
		assert!(parse_element_at("<unterminated", 0, 13).is_none());
	}

	#[test]
	fn parse_element_at_fails_on_unmatched_close() {
		// Tag opens but no matching close tag exists.
		assert!(parse_element_at("<a>body", 0, 7).is_none());
	}

	#[test]
	fn parse_element_at_fails_on_close_tag_with_no_gt() {
		// The close tag's name matches but the `>` is missing.
		assert!(parse_element_at("<a>x</a   ", 0, 10).is_none());
	}

	#[test]
	fn parse_element_at_fails_on_foreign_close_tag_with_no_gt() {
		// A different close tag is encountered whose `>` is missing.
		assert!(parse_element_at("<a>x</y", 0, 7).is_none());
	}

	#[test]
	fn parse_element_at_fails_on_nested_same_name_unclosed() {
		// Same-named nested open tag whose own `>` is unreachable (unterminated
		// attribute quote) — exercises `find_tag_end` failure inside the
		// same-name branch of `find_close_tag`.
		assert!(parse_element_at("<a><a attr=\"unclosed", 0, 20).is_none());
	}

	#[test]
	fn parse_element_at_fails_on_foreign_open_tag_unclosed() {
		// Different-named open tag whose `>` is unreachable — exercises the
		// fallback `find_tag_end` call in `find_close_tag`.
		assert!(parse_element_at("<a><b attr=\"unclosed", 0, 20).is_none());
	}

	#[test]
	fn parse_element_at_fails_on_unclosed_comment_in_body() {
		// `find_close_tag` encounters `<!--` inside the element body and
		// `find_bytes` for `-->` returns None.
		assert!(parse_element_at("<a><!-- unclosed", 0, 16).is_none());
	}

	#[test]
	fn parse_element_at_fails_on_unclosed_pi_in_body() {
		// `find_close_tag` encounters `<?` inside the element body and
		// `find_bytes` for `?>` returns None.
		assert!(parse_element_at("<a><?unclosed", 0, 13).is_none());
	}

	#[test]
	fn parse_element_at_fails_on_unclosed_cdata_in_body() {
		// `find_close_tag` encounters `<![CDATA[` inside the body and
		// `find_bytes` for `]]>` returns None.
		assert!(parse_element_at("<a><![CDATA[unclosed", 0, 20).is_none());
	}
}