155 lines (126 loc) · 11.3 KB

StarryNote v2.1 — Traceability Matrix

Purpose: Maps every requirement to its implementation and tests.
Generated: 2026-03-07

Requirement → Implementation → Test Mapping

R1: File Discovery & Classification

Req ID	Requirement	Implementation	Test(s)
R1.1	Scan directories recursively (DFS)	`StarryScanner.scan()` in `scanner.py`	`test_scan_finds_files`, `test_scan_recursive`, `test_deeply_nested_scan`
R1.2	Detect file types by binary header (MIME)	`StarryScanner.mime.from_file()` via python-magic	`test_scan_detects_text_mime`, `test_multimodal_scanner`
R1.3	Skip irrelevant directories	`StarryScanner.should_skip()` + dir pruning	`test_skips_venv`, `test_skips_pycache`, `test_skips_git`, `test_prunes_skip_directories`
R1.4	Package files as UniversalResource	`UniversalResource` dataclass	`test_resource_creation`, `test_resource_fields_are_strings`, `test_resource_has_size`
R1.5	Track scan statistics	`ScanResult` dataclass	`test_returns_scan_result`, `test_tracks_total_bytes`, `test_tracks_size_per_resource`
R1.6	Handle scan errors gracefully	Error tracking in `ScanResult.errors`	`test_handles_nonexistent_directory`
R1.7	Support unfiltered scanning	`scan(apply_filter=False)`	`test_no_filter_mode`

R2: Template System

Req ID	Requirement	Implementation	Test(s)
R2.1	10-section study guide structure	`master_template.md` sections I-X	`test_section_exists[...]` (×10), `test_sections_are_numbered`
R2.2	Cyberpunk Mermaid styling	`classDef default/highlight` in template	`test_has_cyberpunk_styling`, `test_mermaid_uses_graph_td`
R2.3	3-tier exam questions	Question blocks with Application/Analysis/Synthesis	`test_has_exam_questions`
R2.4	Collapsible answers	`<details>/<summary>` tags	`test_has_collapsible_answers`
R2.5	Metacognitive calibration	Confidence meter 🔴🟡🟢🔵	`test_has_confidence_meter`
R2.6	Zero HTML comments in template	All instructions in system prompt	`test_no_html_comments`, `test_no_ai_instruction_markers`
R2.7	Template loading with fallback	`TemplateLoader._load()`	`test_loads_real_template`, `test_recovery_mode_on_missing_template`
R2.8	Template cleaning	`TemplateLoader.clean()`	`test_strips_html_comments`, `test_strips_multiline_comments`, `test_collapses_whitespace`
R2.9	Template compaction	`TemplateLoader.make_compact()`	`test_compacts_real_template`, `test_removes_duplicate_rows`

R3: Prompt Engineering

Req ID	Requirement	Implementation	Test(s)
R3.1	Knowledge Architect identity	`PromptBuilder._build_rules()`	`test_contains_knowledge_architect`
R3.2	Core directives (Authorship, Synthesis, Formatting, Tone)	`_build_rules()` lines 1-4	`test_core_directives`
R3.3	Mermaid rules in prompt	Type restrictions + classDef injection	`test_mermaid_rules`, `test_classdef_constants_match`
R3.4	Section-specific rules	Rules per section in prompt	`test_section_specific_rules`
R3.5	Output rules (all 10 sections required)	"Generate ALL 10 sections" directive	`test_output_rules`, `test_prompt_enforces_all_sections`
R3.6	Difficulty level vocabulay	Foundational/Intermediate/Advanced/Expert	`test_difficulty_levels_defined`
R3.7	Subject classification	CS/MATH/BIO/HUMANITIES/SOCIAL/OTHER	`test_subject_classes_defined`
R3.8	Resource type vocabulary	7 allowed types	`test_resource_types_defined`
R3.9	No HTML comments in prompt	Zero `<!--` in output	`test_no_html_comments`
R3.10	Image vs text mode	Context label switching	`test_image_mode_label`, `test_text_mode_label`

R4: AI Engine & Inference

Req ID	Requirement	Implementation	Test(s)
R4.1	Route image MIME to image analyzer	`MimeClassifier` + `process_resource()`	`test_routes_jpeg`, `test_routes_png`, `test_routes_gif`, `test_routes_webp`
R4.2	Route PDF MIME to PDF analyzer	`MimeClassifier` + `process_resource()`	`test_routes_pdf`
R4.3	Route text MIME to text analyzer	`MimeClassifier` + `process_resource()`	`test_routes_python`, `test_routes_java`, `test_routes_html`, `test_routes_markdown`, `test_routes_css`, `test_routes_shell_script`, `test_routes_plaintext`
R4.4	Route Office docs to Office analyzer	`MimeClassifier` + `_analyze_office()`	`test_routes_docx`, `test_routes_pptx`, `test_routes_xlsx`
R4.5	Route JSON/CSV/XML to structured analyzer	`MimeClassifier` + `_analyze_structured()`	`test_routes_json`, `test_routes_csv`, `test_routes_xml`
R4.6	Route binary files to binary analyzer	`MimeClassifier` + `_analyze_binary()`	`test_routes_zip_to_binary`, `test_routes_mp4_to_binary`, `test_routes_mp3_to_binary`
R4.7	Fallback unknown MIME to text	`MimeClassifier.classify()` default	`test_routes_unknown_to_text`, `test_completely_unknown`
R4.8	Sufficient token budget	`MAX_TOKENS = 8192`	`test_max_tokens_is_sufficient`
R4.9	Template in prompt	Template wrapped with START/END markers	`test_prompt_contains_template`
R4.10	Source in prompt	Raw content injected	`test_prompt_contains_source_input`

R5: Post-Processing Pipeline

Req ID	Requirement	Implementation	Test(s)
R5.1	Replace forbidden Mermaid types	`MermaidFixer._replace_forbidden_types()`	`test_replaces_sequence_diagram`, `test_replaces_mindmap`, `test_replaces_class_diagram`
R5.2	Inject classDef if missing	`MermaidFixer._inject_classdef()`	`test_injects_classdef_when_missing`, `test_does_not_duplicate_classdef`
R5.3	Remove inline style directives	`MermaidFixer._remove_inline_styles()`	`test_removes_inline_style_directives`
R5.4	Remove trailing semicolons	`MermaidFixer._remove_semicolons()`	`test_removes_trailing_semicolons`
R5.5	Strip leaked AI instructions	`OutputCleaner.clean()`	`test_strips_html_ai_instructions`, `test_strips_bracket_ai_instructions`
R5.6	Strip leaked rule markers	`OutputCleaner._LEAK_PATTERNS`	`test_strips_rules_marker`, `test_strips_diagram_selection_marker`
R5.7	Strip unfilled placeholders	`OutputCleaner._LEAK_PATTERNS[-1]`	`test_strips_unfilled_placeholders`
R5.8	Validate section completeness	`OutputValidator.validate()`	`test_detects_all_sections`, `test_detects_missing_sections`
R5.9	Validate Mermaid presence	`ValidationResult.has_mermaid`	`test_detects_missing_mermaid`
R5.10	Validate exam questions	`ValidationResult.has_exam_questions`	`test_detects_missing_exam_questions`
R5.11	Detect leaked instructions in output	`OutputValidator.validate()` warnings	`test_warns_about_leaked_instructions`
R5.12	Full pipeline orchestration	`PostProcessor.process()`	`test_cleans_and_fixes_in_one_pass`, `test_realistic_dirty_output`

R6: Output Persistence

Req ID	Requirement	Implementation	Test(s)
R6.1	Create Instructions/ directory	`StarryFormatter.__init__()`	`test_creates_instructions_directory`, `test_does_not_fail_if_dir_exists`
R6.2	Generate clean filenames	`save_guide()` naming logic	`test_save_correct_filename`, `test_save_replaces_spaces`, `test_save_strips_extension`
R6.3	Write UTF-8 content	`open(path, 'w', encoding='utf-8')`	`test_save_utf8_content`
R6.4	Post-process on save	`PostProcessor.process()` in `save_guide()`	`test_strips_leaked_instructions_on_save`, `test_fixes_mermaid_on_save`
R6.5	Validate saved guides	`StarryFormatter.validate_guide()`	`test_validates_complete_guide`

R7: Terminal UI

Req ID	Requirement	Implementation	Test(s)
R7.1	MIME icon mapping	`_icon()` function	`test_image_icon`, `test_pdf_icon`, `test_python_icon`, `test_unknown_mime_fallback`
R7.2	Human-readable file sizes	`_sz()` function	`test_bytes`, `test_kilobytes`, `test_megabytes`, `test_gigabytes`, `test_terabytes`
R7.3	Knowledge density star rating	`_density()` function	`test_minimum_one_star`, `test_scales_with_ratio`, `test_max_five_stars`, `test_zero_input_no_crash`
R7.4	Directory skip patterns	`_should_skip()` function	`test_skips_venv`, `test_skips_pycache`, `test_does_not_skip_source`

R8: Universal File Type Support

Req ID	Requirement	Implementation	Test(s)
R8.1	Classify image MIME types	`MimeClassifier.IMAGE_TYPES`	`test_image_types` (8 parameterized), `test_unknown_image_type`
R8.2	Classify PDF MIME type	`MimeClassifier.PDF_TYPES`	`test_pdf`
R8.3	Classify Office document types	`MimeClassifier.OFFICE_TYPES`	`test_office_types` (7 parameterized)
R8.4	Classify structured data types	`MimeClassifier.STRUCTURED_TYPES`	`test_structured_types` (5 parameterized)
R8.5	Classify text/code MIME types	`MimeClassifier.TEXT_TYPES`	`test_text_types` (14 parameterized)
R8.6	Classify binary MIME types	`MimeClassifier.BINARY_TYPES`	`test_binary_types` (12 parameterized), `test_unknown_audio/video/font`
R8.7	Fallback unknown to text	`MimeClassifier.classify()`	`test_unknown_application_type`, `test_completely_unknown`
R8.8	Read UTF-8 text files	`TextExtractor.read_text_file()`	`test_reads_utf8`
R8.9	Read Latin-1 text files (fallback)	`TextExtractor.read_text_file()`	`test_reads_latin1`
R8.10	Truncate large text files	`max_chars` param	`test_truncates_large_files`
R8.11	Handle binary content in text files	Error replacement encoding	`test_handles_binary_content_gracefully`
R8.12	Read and pretty-print JSON	`TextExtractor.read_json_file()`	`test_reads_json`, `test_handles_invalid_json`, `test_truncates_large_json`
R8.13	Read CSV as formatted table	`TextExtractor.read_csv_file()`	`test_reads_csv`, `test_truncates_large_csv`
R8.14	Extract text from Office docs (ZIP/XML)	`TextExtractor.read_office_file()`	`test_reads_docx_like_zip`, `test_handles_empty_docx`, `test_handles_non_zip_file`
R8.15	Generate metadata for binary files	`TextExtractor.read_binary_preview()`	`test_generates_metadata`, `test_handles_missing_file`
R8.16	Read empty files without crash	`TextExtractor.read_text_file()`	`test_reads_empty_file`
R8.17	Binary MIME heuristic detection	`MimeClassifier._is_binary_mime()`	`test_unknown_audio`, `test_unknown_video`, `test_unknown_font`
R8.18	Content size limits	`MAX_TEXT_CHARS`, `MAX_PDF_CHARS`	`test_truncates_large_files`, `test_truncates_large_json`, `test_truncates_large_csv`

Coverage Summary

Category	Requirements	Tests	Coverage
File Discovery	7	22	100%
Template System	9	33	100%
Prompt Engineering	10	14	100%
AI Engine & Routing	10	46	100%
Post-Processing	12	28	100%
Output Persistence	5	15	100%
Terminal UI	4	28	100%
Universal File Types	18	92	100%
Edge Cases	—	19	—
Integration	—	2	—
TOTAL	75	288	100%