test(common/validators): checkstyle walker claims XSD conformance but ignores element nesting

[dekobon]

Summary

assert_checkstyle_well_formed_and_structural in the lib-crate test
helper claims to "assert structural conformance to
tests/fixtures/checkstyle-report-1.0.0.xsd", but it never validates
element nesting/parentage — it only validates each element's own name
and attributes plus overall tag-balance. Any Checkstyle output whose
elements are nested in violation of the XSD containment hierarchy
passes, defeating the only safeguard for the checkstyle output
format.

Location

• tests/common/validators.rs:105-202
  (assert_checkstyle_well_formed_and_structural + check_element)

Evidence

The XSD (tests/fixtures/checkstyle-report-1.0.0.xsd) defines a strict
containment hierarchy:

• checkstyleType (root <checkstyle>) may contain <file>,
  <exception>, <error>.
• fileType (<file>) may contain <error>, <exception>.
• errorType (<error>) is attribute-only — it may contain no
  child elements.

The walker tracks only a scalar depth counter and a saw_root flag:

let mut saw_root = false;
let mut depth = 0usize;
...
Event::Start(start) => {
    check_element(&start, &mut saw_root, pos);
    depth += 1;
}
...
Event::End(end) => {
    ...
    depth = depth.saturating_sub(1);
}
...
assert!(saw_root, "checkstyle: document did not contain a <checkstyle> root element");
assert!(depth == 0, "checkstyle: unbalanced element depth {depth} at EOF");

check_element validates the element's own name and attributes but
is never told its parent. Nothing rejects, for example:

• <error> nested inside another <error> (XSD: errorType has no
  child elements).
• <file> nested inside a <file> or inside an <error>.
• <checkstyle> appearing as a non-root element (it only needs to
  appear somewhere; <file><checkstyle version="x"/></file> sets
  saw_root = true and passes, with no actual <checkstyle> root).
• <error> / <file> appearing at arbitrary depth.

The depth check only confirms start/end tags are balanced
(well-formedness), not that they nest per the XSD. The saw_root
flag only confirms a <checkstyle> token appeared, not that it is the
document root.

Relatedly, attr_value calls start.attributes().with_checks(false),
which disables quick-xml's duplicate-attribute detection, and it
returns the first matching attribute — so a writer emitting a
duplicate attribute (<error line="1" line="2" .../>) would silently
validate against the first value.

Expected Behavior

Either:

1. The walker tracks the parent element (e.g., a small element stack)
   and rejects illegal nesting per the XSD containment rules; or
2. The docstring stops claiming "structural conformance to the XSD"
   and instead describes what is actually checked — per-element name +
   attribute validation plus tag-balance well-formedness, not XSD
   nesting.

Actual Behavior

The helper advertises XSD structural conformance but accepts arbitrary
element nesting. A regression in src/output/checkstyle.rs that
nested <error>/<file> incorrectly, or emitted a <checkstyle>
that is not the document root, would pass every checkstyle
integration test in tests/checkstyle_test.rs.

Impact

High blast radius: this helper is the sole automated structural check
for the Checkstyle output format (consumed by all assertions in
tests/checkstyle_test.rs). A too-lenient validator gives false
confidence that the emitted XML conforms to the Checkstyle XSD when it
may not, so a structural writer regression ships undetected. (Distinct
from #899, which concerns the CLI copy's false "byte-for-byte sync"
docstring, not the validator's nesting coverage.)

[dekobon]

General Plan for Fix

Root Cause

assert_checkstyle_well_formed_and_structural validates each element
in isolation (name + required attributes) and confirms tag-balance via
a scalar depth counter, but it never records the parent of the
element currently being entered. The XSD it claims to mirror defines a
containment hierarchy (checkstyle > file > error/exception;
error is leaf-only; error/exception may also sit directly under
checkstyle). Without parent tracking, illegal nesting is invisible to
the walker, and saw_root only proves a <checkstyle> token appeared,
not that it is the root.

Implementation Steps

1. Replace the scalar depth: usize with a Vec<&'static str> (or
   small enum) element stack. On Event::Start, after check_element
   succeeds, validate the new element against the top of the stack
   (parent), then push; on Event::End, pop. Event::Empty validates
   parent without pushing.
2. Encode the XSD containment rules in a single allowed_child(parent, child) helper:
   • root (empty stack): only checkstyle
   • checkstyle: file | error | exception
   • file: error | exception
   • error: nothing (leaf)
   • exception: nothing (xs:string text content only)
     On violation, panic with parent + child + byte position.
3. Replace the saw_root flag with "stack was empty when checkstyle
   was entered" so a non-root <checkstyle> is rejected.
4. (Optional, smaller-scope) Re-enable duplicate-attribute detection by
   dropping with_checks(false) in attr_value, or add an explicit
   duplicate check; surface a descriptive panic.
5. If parent tracking is judged out of scope, instead correct the
   docstring (module doc lines 12-18 + the fn doc) to drop the
   "structural conformance to the XSD" claim and state precisely what
   is validated.
6. Apply the identical change to the CLI copy
   (big-code-analysis-cli/tests/common/validators.rs) to keep the
   shared core in lock-step (see docs(cli-tests): validators.rs 'byte-for-byte' sync claim is false; copies diverge #899).

Tests to Add/Update

• Add negative tests in tests/checkstyle_test.rs asserting that the
  validator panics on: <error> nested in <error>; <file> nested
  in <file>; a <checkstyle> that is not the document root
  (<file><checkstyle version="x"/></file>); <error> directly under
  the root with no <file> is allowed (XSD permits it) — guard
  against over-tightening.
• Verify each new negative test fails (panics) against the fixed
  walker and would have passed (no panic) against the current one.
• A duplicate-attribute negative test if step 4 is taken.

Verification

• cargo test -p big-code-analysis passes (checkstyle suite)
• cargo clippy -p big-code-analysis --tests clean
• Manual verification: hand-craft a malformed Checkstyle document
  with mis-nested <error>/<file> and confirm the validator now
  rejects it, while a valid writer-emitted document still passes.