Documentation contains false performance claims and MVP status

[EffortlessSteven]

Summary

Multiple documentation files contain performance claims and MVP assertions that are not supported by the current implementation state.

False Claims in Documentation

README.md

• "815 MB/sec throughput" - Based on character counting, not parsing
• "118M tokens/sec processing rate" - No actual tokenization occurring
• "100x faster than Tree-sitter" - Comparing mocks to real parsers
• "Production-Ready GLR" - Lexer cannot safely convert types

PERFORMANCE_GUIDE.md

• Performance metrics table - Shows fictional benchmarks for non-functional parsing
• Optimization techniques - Suggest improvements to non-working components
• Throughput comparisons - All based on mock implementations

PROJECT_STATUS.md

• "v0.6.1-beta - Production Ready" - Contradicted by implementation gaps
• "Python Grammar Support: Successfully parses Python" - Lexer warnings indicate failure
• "100% test pass rate" - Tests pass because they're testing mocks, not real functionality

README Quick Start Section

// This example suggests working parsing
let tree = parser.parse(source, None).expect("Failed to parse");
if tree.error_count() == 0 {
    println!("Parse successful!");
}

Reality: Parser cannot successfully parse real code due to lexer implementation gaps.

Impact on Users

• Misleading adoption decisions: Users may choose rust-sitter based on false performance claims
• Development frustration: Developers expect working parser but encounter lexer warnings
• Ecosystem confusion: Other projects may integrate expecting production-ready functionality
• Technical credibility: False claims damage project and maintainer reputation

Required Documentation Updates

Immediate (Honesty First)

1. README.md: Remove all performance claims, add "Early Development" warnings
2. PROJECT_STATUS.md: Downgrade to "Alpha/Experimental" status
3. PERFORMANCE_GUIDE.md: Add disclaimer that benchmarks are preliminary/mock
4. Quick Start: Add warnings about current limitations

After Implementation Complete

1. Real benchmarks: Replace mock benchmarks with actual parsing measurements
2. Accurate status: Update to reflect true implementation completeness
3. Working examples: Ensure all code examples actually work
4. Performance validation: Verify claims against real-world usage

Priority

HIGH - Documentation accuracy is critical for project credibility

Files Requiring Updates

• README.md - Primary project description
• PROJECT_STATUS.md - Status claims
• PERFORMANCE_GUIDE.md - Benchmark claims
• ROADMAP.md - Completion assertions
• API_DOCUMENTATION.md - Working examples

Proposed Interim Messaging

"Rust Sitter is an experimental parser generator in early development. Core parsing functionality is under active development. Current benchmarks are preliminary and do not reflect real parsing performance."

Context

Discovered during comprehensive performance analysis that revealed the gap between documentation claims and implementation reality.

[EffortlessSteven]

The focus is on getting things connected and getting to the point where we can properly validate and fill in these mocks with real numbers.