perf: O(1) document entry lookups in ProjectNode

[CybotTM]

Summary

Optimizes document entry lookups in ProjectNode from O(n) iteration to O(1) hash-based lookups.

This PR contains 3 distinct commits, each addressing a specific concern:

1. Preparatory Refactor: File path comparison (4 files)

Replaces object identity comparison (===) with file path comparison when matching DocumentEntryNode instances.

Why this matters:

• Object identity fails when entries are deserialized from cache (new instances)
• File path is the natural unique identifier for documents
• Enables the O(1) optimization in commit 2

Changed files:

• GlobalMenuPass.php - root document lookup
• ToctreeValidationPass.php - root document check
• RenderContext.php - getDocumentNodeForEntry()
• DocumentTreeIterator.php - current()

2. Performance Improvement: O(1) caching (1 file)

Adds hash-based O(1) lookups to ProjectNode:

// Before: O(n) iteration
foreach ($this->documentEntries as $entry) {
    if ($entry->getFile() === $file) return $entry;
}

// After: O(1) hash lookup
return $this->documentEntries[$file];

Changes to ProjectNode.php:

• Cache root document entry for instant getRootDocumentEntry()
• Use direct hash lookup in getDocumentEntry() by file path
• Re-key array in setDocumentEntries() via addDocumentEntry()
• Invalidate cache on reset()
• Update type annotation: DocumentEntryNode[] → array<string, DocumentEntryNode>

3. Test Adaptation (1 file)

Updates FunctionalTest.php to use withIsRoot(true) instead of manually creating a DocumentEntryNode that gets overwritten by the compiler.

Performance Impact

Method	Before	After
getRootDocumentEntry()	O(n)	O(1)
getDocumentEntry($file)	O(n)	O(1)

This is particularly impactful for large documentation projects with hundreds or thousands of documents.

See Performance Analysis Report for detailed benchmarks.

Test Plan

• All existing tests pass
• Code style checks pass for changed files
• No breaking changes to public API

---

Related PRs

PR	Description	Status
#1287	Rendering caching layer	Independent
#1288	RST parsing optimizations	Independent
#1289	CLI container caching	Independent
#1291	Symfony 8 compatibility	✅ Merged
#1293	This PR - ProjectNode O(1) document lookup

All PRs can be merged independently in any order.

[jaapio]

Thanks, this makes a lot of sense.