1#!/usr/bin/env python3
2"""
3Report Validation Script
4Ensures research reports meet quality standards before delivery
5"""
6 
7import argparse
8import re
9import sys
10from pathlib import Path
11from typing import List, Tuple, Dict
12 
13 
14class ReportValidator:
15    """Validates research report quality"""
16 
17    def __init__(self, report_path: Path):
18        self.report_path = report_path
19        self.content = self._read_report()
20        self.errors: List[str] = []
21        self.warnings: List[str] = []
22 
23    def _read_report(self) -> str:
24        """Read report file"""
25        try:
26            with open(self.report_path, 'r', encoding='utf-8') as f:
27                return f.read()
28        except Exception as e:
29            print(f"❌ ERROR: Cannot read report: {e}")
30            sys.exit(1)
31 
32    def validate(self) -> bool:
33        """Run all validation checks"""
34        print(f"\n{'='*60}")
35        print(f"VALIDATING REPORT: {self.report_path.name}")
36        print(f"{'='*60}\n")
37 
38        checks = [
39            ("Executive Summary", self._check_executive_summary),
40            ("Required Sections", self._check_required_sections),
41            ("Citations", self._check_citations),
42            ("Bibliography", self._check_bibliography),
43            ("Placeholder Text", self._check_placeholders),
44            ("Content Truncation", self._check_content_truncation),
45            ("Word Count", self._check_word_count),
46            ("Source Count", self._check_source_count),
47            ("Broken Links", self._check_broken_references),
48        ]
49 
50        for check_name, check_func in checks:
51            print(f"⏳ Checking: {check_name}...", end=" ")
52            passed = check_func()
53            if passed:
54                print("✅ PASS")
55            else:
56                print("❌ FAIL")
57 
58        self._print_summary()
59 
60        return len(self.errors) == 0
61 
62    def _check_executive_summary(self) -> bool:
63        """Check executive summary exists and is 200-400 words"""
64        pattern = r'## Executive Summary(.*?)(?=##|\Z)'
65        match = re.search(pattern, self.content, re.DOTALL | re.IGNORECASE)
66 
67        if not match:
68            self.errors.append("Missing 'Executive Summary' section")
69            return False
70 
71        summary = match.group(1).strip()
72        word_count = len(summary.split())
73 
74        if word_count > 400:
75            self.warnings.append(f"Executive summary too long: {word_count} words (should be ≤400)")
76 
77        if word_count < 50:
78            self.warnings.append(f"Executive summary too short: {word_count} words (should be ≥50)")
79 
80        return True
81 
82    def _check_required_sections(self) -> bool:
83        """Check all required sections are present"""
84        required = [
85            "Executive Summary",
86            "Introduction",
87            "Main Analysis",
88            "Synthesis",
89            "Limitations",
90            "Recommendations",
91            "Bibliography",
92            "Methodology"
93        ]
94 
95        # Recommended sections (warnings if missing, not errors)
96        recommended = [
97            "Counterevidence Register",
98            "Claims-Evidence Table"
99        ]
100 
101        missing = []
102        for section in required:
103            if not re.search(rf'##.*{section}', self.content, re.IGNORECASE):
104                missing.append(section)
105 
106        if missing:
107            self.errors.append(f"Missing sections: {', '.join(missing)}")
108            return False
109 
110        # Check recommended sections (warnings only)
111        missing_recommended = []
112        for section in recommended:
113            if not re.search(rf'##.*{section}', self.content, re.IGNORECASE):
114                missing_recommended.append(section)
115 
116        if missing_recommended:
117            self.warnings.append(f"Missing recommended sections (for academic rigor): {', '.join(missing_recommended)}")
118 
119        return True
120 
121    def _check_citations(self) -> bool:
122        """Check citation format and presence"""
123        # Find all citation references [1], [2], etc.
124        citations = re.findall(r'\[(\d+)\]', self.content)
125 
126        if not citations:
127            self.errors.append("No citations found in report")
128            return False
129 
130        unique_citations = set(citations)
131 
132        if len(unique_citations) < 10:
133            self.warnings.append(f"Only {len(unique_citations)} unique sources cited (recommended: ≥10)")
134 
135        # Check for consecutive citation numbers
136        citation_nums = sorted([int(c) for c in unique_citations])
137        if citation_nums:
138            max_citation = max(citation_nums)
139            expected = set(range(1, max_citation + 1))
140            missing = expected - set(citation_nums)
141 
142            if missing:
143                self.warnings.append(f"Non-consecutive citation numbers, missing: {sorted(missing)}")
144 
145        return True
146 
147    def _check_bibliography(self) -> bool:
148        """Check bibliography exists, matches citations, and has no truncation placeholders"""
149        pattern = r'## Bibliography(.*?)(?=##|\Z)'
150        match = re.search(pattern, self.content, re.DOTALL | re.IGNORECASE)
151 
152        if not match:
153            self.errors.append("Missing 'Bibliography' section")
154            return False
155 
156        bib_section = match.group(1)
157 
158        # CRITICAL: Check for truncation placeholders (2025 CiteGuard enhancement)
159        truncation_patterns = [
160            (r'\[\d+-\d+\]', 'Citation range (e.g., [8-75])'),
161            (r'Additional.*citations', 'Phrase "Additional citations"'),
162            (r'would be included', 'Phrase "would be included"'),
163            (r'\[\.\.\.continue', 'Pattern "[...continue"'),
164            (r'\[Continue with', 'Pattern "[Continue with"'),
165            (r'etc\.(?!\w)', 'Standalone "etc."'),
166            (r'and so on', 'Phrase "and so on"'),
167        ]
168 
169        for pattern_re, description in truncation_patterns:
170            if re.search(pattern_re, bib_section, re.IGNORECASE):
171                self.errors.append(f"⚠️ CRITICAL: Bibliography contains truncation placeholder: {description}")
172                self.errors.append(f"   This makes the report UNUSABLE - complete bibliography required")
173                return False
174 
175        # Count bibliography entries [1], [2], etc.
176        bib_entries = re.findall(r'^\[(\d+)\]', bib_section, re.MULTILINE)
177 
178        if not bib_entries:
179            self.errors.append("Bibliography has no entries")
180            return False
181 
182        # Check citation number continuity (no gaps)
183        bib_nums = sorted([int(n) for n in bib_entries])
184        if bib_nums:
185            expected = list(range(1, bib_nums[-1] + 1))
186            actual = bib_nums
187            missing = [n for n in expected if n not in actual]
188            if missing:
189                self.errors.append(f"Bibliography has gaps in numbering: missing {missing}")
190                return False
191 
192        # Find citations in text
193        text_citations = set(re.findall(r'\[(\d+)\]', self.content))
194        bib_citations = set(bib_entries)
195 
196        # Check all citations have bibliography entries
197        missing_in_bib = text_citations - bib_citations
198        if missing_in_bib:
199            self.errors.append(f"Citations missing from bibliography: {sorted(missing_in_bib)}")
200            return False
201 
202        # Check for unused bibliography entries
203        unused = bib_citations - text_citations
204        if unused:
205            self.warnings.append(f"Unused bibliography entries: {sorted(unused)}")
206 
207        return True
208 
209    def _check_placeholders(self) -> bool:
210        """Check for placeholder text that shouldn't be in final report"""
211        placeholders = [
212            'TBD', 'TODO', 'FIXME', 'XXX',
213            '[citation needed]', '[needs citation]',
214            '[placeholder]', '[TODO]', '[TBD]'
215        ]
216 
217        found_placeholders = []
218        for placeholder in placeholders:
219            if placeholder in self.content:
220                found_placeholders.append(placeholder)
221 
222        if found_placeholders:
223            self.errors.append(f"Found placeholder text: {', '.join(found_placeholders)}")
224            return False
225 
226        return True
227 
228    def _check_content_truncation(self) -> bool:
229        """Check for content truncation patterns (2025 Progressive Assembly enhancement)"""
230        truncation_patterns = [
231            (r'Content continues', 'Phrase "Content continues"'),
232            (r'Due to length', 'Phrase "Due to length"'),
233            (r'would continue', 'Phrase "would continue"'),
234            (r'\[Sections \d+-\d+', 'Pattern "[Sections X-Y"'),
235            (r'Additional sections', 'Phrase "Additional sections"'),
236            (r'comprehensive.*word document that continues', 'Pattern "comprehensive...document that continues"'),
237        ]
238 
239        for pattern_re, description in truncation_patterns:
240            if re.search(pattern_re, self.content, re.IGNORECASE):
241                self.errors.append(f"⚠️ CRITICAL: Content truncation detected: {description}")
242                self.errors.append(f"   Report is INCOMPLETE and UNUSABLE - regenerate with progressive assembly")
243                return False
244 
245        return True
246 
247    def _check_word_count(self) -> bool:
248        """Check overall report length"""
249        word_count = len(self.content.split())
250 
251        if word_count < 500:
252            self.warnings.append(f"Report is very short: {word_count} words (consider expanding)")
253        # No upper limit warning - progressive assembly supports unlimited lengths
254 
255        return True
256 
257    def _check_source_count(self) -> bool:
258        """Check minimum source count"""
259        pattern = r'## Bibliography(.*?)(?=##|\Z)'
260        match = re.search(pattern, self.content, re.DOTALL | re.IGNORECASE)
261 
262        if not match:
263            return True  # Already caught in bibliography check
264 
265        bib_section = match.group(1)
266        bib_entries = re.findall(r'^\[(\d+)\]', bib_section, re.MULTILINE)
267 
268        source_count = len(set(bib_entries))
269 
270        if source_count < 10:
271            self.warnings.append(f"Only {source_count} sources (recommended: ≥10)")
272 
273        return True
274 
275    def _check_broken_references(self) -> bool:
276        """Check for broken internal references"""
277        # Find all markdown links [text](./path)
278        internal_links = re.findall(r'\[.*?\]\((\.\/.*?)\)', self.content)
279 
280        broken = []
281        for link in internal_links:
282            # Remove anchor if present
283            link_path = link.split('#')[0]
284            full_path = self.report_path.parent / link_path
285 
286            if not full_path.exists():
287                broken.append(link)
288 
289        if broken:
290            self.errors.append(f"Broken internal links: {', '.join(broken)}")
291            return False
292 
293        return True
294 
295    def _print_summary(self):
296        """Print validation summary"""
297        print(f"\n{'='*60}")
298        print(f"VALIDATION SUMMARY")
299        print(f"{'='*60}\n")
300 
301        if self.errors:
302            print(f"❌ ERRORS ({len(self.errors)}):")
303            for error in self.errors:
304                print(f"   • {error}")
305            print()
306 
307        if self.warnings:
308            print(f"⚠️  WARNINGS ({len(self.warnings)}):")
309            for warning in self.warnings:
310                print(f"   • {warning}")
311            print()
312 
313        if not self.errors and not self.warnings:
314            print("✅ ALL CHECKS PASSED - Report meets quality standards!\n")
315        elif not self.errors:
316            print("✅ VALIDATION PASSED (with warnings)\n")
317        else:
318            print("❌ VALIDATION FAILED - Please fix errors before delivery\n")
319 
320 
321def main():
322    parser = argparse.ArgumentParser(
323        description="Validate research report quality",
324        formatter_class=argparse.RawDescriptionHelpFormatter,
325        epilog="""
326Examples:
327  python validate_report.py --report report.md
328  python validate_report.py -r ~/.claude/research_output/research_report_20251104_153045.md
329        """
330    )
331 
332    parser.add_argument(
333        '--report', '-r',
334        type=str,
335        required=True,
336        help='Path to research report markdown file'
337    )
338 
339    args = parser.parse_args()
340 
341    report_path = Path(args.report)
342 
343    if not report_path.exists():
344        print(f"❌ ERROR: Report file not found: {report_path}")
345        sys.exit(1)
346 
347    validator = ReportValidator(report_path)
348    passed = validator.validate()
349 
350    sys.exit(0 if passed else 1)
351 
352 
353if __name__ == '__main__':
354    main()
355