feat(context): add doc-vs-code distinction and test-to-code ratio

Add SpanChangeKind enum (WhitespaceOnly, DocsOnly, Mixed, Semantic) for
richer modified-symbol classification. Doc-only changes suggest `docs`
type. Modified symbols show [docs only] / [docs + code] suffix.

Also add test-to-code ratio check: >80% test additions suggests `test`
type. Uses cross-multiplication to avoid integer truncation.

Author: Sephyi

src/domain/symbol.rs

@@ -19,6 +19,22 @@ pub enum SymbolKind {
     Type,
 }
 
+/// Richer classification of what changed within a symbol's span.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[allow(dead_code)]
+pub enum SpanChangeKind {
+    /// No changes within the symbol span
+    Unchanged,
+    /// Only whitespace/indentation changed
+    WhitespaceOnly,
+    /// Only doc comments changed (code unchanged)
+    DocsOnly,
+    /// Both doc comments and code changed
+    Mixed,
+    /// Code changed (no doc changes, or docs not present)
+    Semantic,
+}
+
 /// How a symbol was affected by the change.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 #[non_exhaustive]
@@ -48,6 +64,9 @@ pub struct CodeSymbol {
     /// For symbols that exist in both HEAD and staged, indicates if only whitespace changed.
     /// None = symbol is purely added or removed, not a modification.
     pub is_whitespace_only: Option<bool>,
+    /// Richer classification of what changed within this symbol's span.
+    /// None for purely added or removed symbols.
+    pub span_change_kind: Option<SpanChangeKind>,
     /// Full signature extracted from tree-sitter AST (everything before the body).
     /// e.g., "pub fn connect(host: &str, timeout: Duration) -> Result<Connection>"
     /// None for languages or constructs where signature extraction isn't supported.

src/eval.rs

@@ -516,6 +516,7 @@ impl EvalRunner {
                 is_public: def.is_public,
                 is_added: def.is_added,
                 is_whitespace_only: def.is_whitespace_only,
+                span_change_kind: None,
                 signature: def.signature,
                 parent_scope: def.parent_scope,
             })

src/services/analyzer.rs

@@ -346,6 +346,7 @@ impl AnalyzerService {
                         is_public,
                         is_added,
                         is_whitespace_only: None,
+                        span_change_kind: None,
                         signature,
                         parent_scope,
                     });

src/services/context.rs

@@ -6,7 +6,8 @@ use std::collections::HashSet;
 
 use crate::config::Config;
 use crate::domain::{
-    ChangeStatus, CodeSymbol, CommitType, FileCategory, PromptContext, StagedChanges, SymbolKind,
+    ChangeStatus, CodeSymbol, CommitType, FileCategory, PromptContext, SpanChangeKind,
+    StagedChanges, SymbolKind,
 };
 
 const SYSTEM_PROMPT_RESERVE: usize = 2_000;
@@ -114,6 +115,13 @@ impl ContextBuilder {
                     old_start,
                     old_end,
                 );
+                symbol.span_change_kind = Self::classify_span_change_rich(
+                    &file_change.diff,
+                    symbol.line,
+                    symbol.end_line,
+                    old_start,
+                    old_end,
+                );
             }
         }
 
@@ -135,7 +143,16 @@ impl ContextBuilder {
             && modified_symbols
                 .iter()
                 .all(|s| s.is_whitespace_only == Some(true));
-        let commit_type = Self::infer_commit_type(changes, &symbols_deduped, all_modified_ws);
+        let all_modified_docs = !modified_symbols.is_empty()
+            && modified_symbols
+                .iter()
+                .all(|s| s.span_change_kind == Some(SpanChangeKind::DocsOnly));
+        let commit_type = Self::infer_commit_type(
+            changes,
+            &symbols_deduped,
+            all_modified_ws,
+            all_modified_docs,
+        );
         let scope = if config.format.include_scope {
             Self::infer_scope(changes)
         } else {
@@ -297,10 +314,114 @@ impl ContextBuilder {
         Some(old_text == new_text)
     }
 
+    /// Classify changes within a symbol span with doc-vs-code distinction.
+    ///
+    /// Returns a richer `SpanChangeKind` that distinguishes whitespace-only,
+    /// doc-only, mixed, and semantic changes. Returns `None` if no changes
+    /// fall within the symbol span.
+    pub(crate) fn classify_span_change_rich(
+        diff: &str,
+        new_start: usize,
+        new_end: usize,
+        old_start: usize,
+        old_end: usize,
+    ) -> Option<SpanChangeKind> {
+        use crate::services::analyzer::DiffHunk;
+
+        let hunks = DiffHunk::parse_from_diff(diff);
+        let mut added_in_span: Vec<&str> = Vec::new();
+        let mut removed_in_span: Vec<&str> = Vec::new();
+
+        let mut current_old_line: usize = 0;
+        let mut current_new_line: usize = 0;
+        let mut hunk_idx: usize = 0;
+        let mut in_hunk = false;
+
+        for line in diff.lines() {
+            if line.starts_with("@@") {
+                if hunk_idx < hunks.len() {
+                    current_old_line = hunks[hunk_idx].old_start;
+                    current_new_line = hunks[hunk_idx].new_start;
+                    hunk_idx += 1;
+                    in_hunk = true;
+                }
+                continue;
+            }
+
+            if !in_hunk || line.starts_with("+++") || line.starts_with("---") {
+                continue;
+            }
+
+            if let Some(content) = line.strip_prefix('+') {
+                if current_new_line >= new_start && current_new_line <= new_end {
+                    added_in_span.push(content);
+                }
+                current_new_line += 1;
+            } else if let Some(content) = line.strip_prefix('-') {
+                if current_old_line >= old_start && current_old_line <= old_end {
+                    removed_in_span.push(content);
+                }
+                current_old_line += 1;
+            } else {
+                current_old_line += 1;
+                current_new_line += 1;
+            }
+        }
+
+        if added_in_span.is_empty() && removed_in_span.is_empty() {
+            return None;
+        }
+
+        // Check whitespace-only first (same logic as classify_span_change)
+        let old_text: String = removed_in_span
+            .iter()
+            .flat_map(|l| l.chars())
+            .filter(|c| !c.is_whitespace())
+            .collect();
+        let new_text: String = added_in_span
+            .iter()
+            .flat_map(|l| l.chars())
+            .filter(|c| !c.is_whitespace())
+            .collect();
+        if old_text == new_text {
+            return Some(SpanChangeKind::WhitespaceOnly);
+        }
+
+        // Classify each changed line as doc or code
+        let has_doc = added_in_span
+            .iter()
+            .chain(removed_in_span.iter())
+            .any(|l| Self::is_doc_comment(l));
+        let has_code = added_in_span.iter().chain(removed_in_span.iter()).any(|l| {
+            let trimmed = l.trim();
+            !trimmed.is_empty() && !Self::is_doc_comment(l)
+        });
+
+        match (has_doc, has_code) {
+            (true, false) => Some(SpanChangeKind::DocsOnly),
+            (true, true) => Some(SpanChangeKind::Mixed),
+            (false, _) => Some(SpanChangeKind::Semantic),
+        }
+    }
+
+    /// Check if a line looks like a doc comment or regular comment.
+    fn is_doc_comment(line: &str) -> bool {
+        let trimmed = line.trim();
+        trimmed.starts_with("///")
+            || trimmed.starts_with("//!")
+            || trimmed.starts_with("/**")
+            || trimmed.starts_with("* ") // inside /** */ block
+            || trimmed.starts_with("*/")
+            || trimmed.starts_with('#') // Python/Ruby comments
+            || trimmed.starts_with("\"\"\"") // Python docstrings
+            || (trimmed.starts_with("//") && !trimmed.starts_with("///") && !trimmed.starts_with("//!"))
+    }
+
     pub fn infer_commit_type(
         changes: &StagedChanges,
         symbols: &[CodeSymbol],
         all_modified_whitespace_only: bool,
+        all_modified_docs_only: bool,
     ) -> CommitType {
         let categories: Vec<_> = changes.files.iter().map(|f| f.category).collect();
 
@@ -314,6 +435,20 @@ impl ContextBuilder {
             return CommitType::Test;
         }
 
+        // Predominantly test additions (>80%) → test type
+        // Cross-multiply to avoid integer division truncation (F-009):
+        // test_additions/total_additions > 80/100  ⟹  test_additions * 100 > total_additions * 80
+        let test_additions: usize = changes
+            .files
+            .iter()
+            .filter(|f| f.category == FileCategory::Test)
+            .map(|f| f.additions)
+            .sum();
+        let total_additions: usize = changes.files.iter().map(|f| f.additions).sum();
+        if total_additions > 0 && test_additions * 100 > total_additions * 80 {
+            return CommitType::Test;
+        }
+
         // All config -> chore
         if categories.iter().all(|c| *c == FileCategory::Config) {
             return CommitType::Chore;
@@ -330,6 +465,12 @@ impl ContextBuilder {
             return CommitType::Style;
         }
 
+        // All modified symbols are docs-only and no added/removed symbols → docs
+        // (catches doc comment edits inside existing functions/structs)
+        if all_modified_docs_only && symbols.is_empty() {
+            return CommitType::Docs;
+        }
+
         // Explicit bug evidence -> fix
         if Self::detect_bug_evidence(changes) {
             return CommitType::Fix;
@@ -629,6 +770,14 @@ impl ContextBuilder {
                 }
             };
 
+            // Append doc-vs-code suffix when span_change_kind is informative
+            let suffix = match new_sym.span_change_kind {
+                Some(SpanChangeKind::DocsOnly) => " [docs only]",
+                Some(SpanChangeKind::Mixed) => " [docs + code]",
+                _ => "",
+            };
+            let line = format!("{}{}", line, suffix);
+
             if output.len() + line.len() + 1 > char_budget {
                 break;
             }

src/services/splitter.rs

@@ -125,7 +125,8 @@ impl CommitSplitter {
 
             // Whitespace classification requires full build(); pass false here
             // since sub_symbols are not yet classified via classify_span_change.
-            let commit_type = ContextBuilder::infer_commit_type(&sub_changes, &sub_symbols, false);
+            let commit_type =
+                ContextBuilder::infer_commit_type(&sub_changes, &sub_symbols, false, false);
             let scope = ContextBuilder::infer_scope(&sub_changes);
 
             groups.push(CommitGroup {