fix: report circular includes as errors instead of orphaned files (#251)

[raifdmueller]

Summary

• Detect circular include cycles in the AsciiDoc include graph during index building
• Report circular includes as circular_include errors in validation instead of misleading orphaned_file warnings
• Handles both mutual circular includes (A→B→A) and self-includes (A→A)

Changes

• src/dacli/mcp_app.py: Added cycle detection using DFS in _build_index(). Also catches CircularIncludeError during parsing as fallback.
• src/dacli/services/validation_service.py: Reports stored circular include errors as "circular_include" type errors and excludes involved files from orphaned file detection.
• src/dacli/structure_index.py: Added _circular_include_errors list to store detected cycles.
• tests/test_circular_include_validation_251.py: 5 new tests covering mutual circular includes, self-includes, CLI output, and non-orphan assertion.

Test plan

• All 620 tests pass (615 existing + 5 new)
• Circular includes (A↔B) reported as circular_include errors, not orphaned_file warnings
• Self-includes (A→A) reported as circular_include errors
• CLI validate command shows circular_include with exit code 4
• No regressions in existing validation tests

Fixes #251

🤖 Generated with Claude Code

[raifdmueller]

Code Review

Overall: Good, one minor note

Cycle Detection

DFS algorithm with visited/in_stack sets is correct. Properly detects both mutual (A↔B) and self-referencing cycles.

Architecture

• Circular errors stored on StructureIndex._circular_include_errors - initialized in __init__, cleared in clear()
• Validation service excludes circular files from orphaned detection - prevents the confusing "orphaned file" message
• Also catches CircularIncludeError during parsing as fallback

Minor Note

index._circular_include_errors is set externally from mcp_app.py (breaking encapsulation). Consider adding a setter or passing it through build_from_documents() in a future refactor. Not blocking.

Tests

5 tests covering circular A↔B, self-reference, CLI, error format, and not-orphaned check.

Version Conflict

All 3 PRs bump to 0.4.25. Will need rebase after earlier merges.

Reviewed-by: R{AI}f D. Müller (AI-assisted review)