fix: improve header matching, score diagnostics, and frontmatter parsing (#166, #167, #161, #164)

- Accept common header variations in Public API (Exports, Public, Export)
  instead of requiring exact "Exported" keyword (#166)
- Score suggestions now show point impact per category (e.g., "Sections (-6pts):
  missing ## Invariants, Error Cases") for clear diagnosis (#167)
- Add --explain flag to score command for color-coded subscore breakdown
- Strip inline YAML comments from frontmatter values (#161)
- Handle tab indentation and trailing whitespace in frontmatter
- --fix now renames near-miss headers to canonical form before adding exports (#164)

Closes #166, closes #167, closes #161, closes #164

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: corvid-agent

src/cli.rs

@@ -68,7 +68,11 @@ pub enum Command {
     /// Create a specsync.json config file
     Init,
     /// Score spec quality (0-100) with letter grades and improvement suggestions
-    Score,
+    Score {
+        /// Show detailed per-category breakdown explaining exactly why each spec lost points
+        #[arg(long)]
+        explain: bool,
+    },
     /// Watch spec and source files, re-running check on changes
     Watch,
     /// Run as an MCP (Model Context Protocol) server over stdio

src/commands/check.rs

@@ -372,6 +372,78 @@ fn auto_regen_stale_specs(
 
 // ─── Auto-fix: add undocumented exports to spec ─────────────────────────
 
+/// Normalize near-miss export headers within ## Public API.
+/// E.g., "### Exportd Functions" → "### Exported Functions"
+/// Returns true if the content was modified.
+fn fix_near_miss_headers(content: &mut String) -> bool {
+    use regex::Regex;
+    let re = Regex::new(r"(?m)^(### )(.+)$").unwrap();
+
+    // Find the Public API section bounds
+    let api_start = match content.find("## Public API") {
+        Some(pos) => pos,
+        None => return false,
+    };
+    let after = &content[api_start..];
+    let api_end = after[1..]
+        .find("\n## ")
+        .map(|p| api_start + 1 + p)
+        .unwrap_or(content.len());
+
+    let api_section = content[api_start..api_end].to_string();
+    let mut modified = false;
+
+    // Known canonical headers and their near-miss patterns
+    let canonical_map: &[(&[&str], &str)] = &[
+        (
+            &["exportd function", "exportd func", "exproted function", "expported function"],
+            "Exported Functions",
+        ),
+        (
+            &["exportd type", "exproted type", "expported type"],
+            "Exported Types",
+        ),
+        (
+            &["exportd class", "exproted class"],
+            "Exported Classes",
+        ),
+        (
+            &["exportd constant", "exportd const", "exproted constant"],
+            "Exported Constants",
+        ),
+    ];
+
+    let mut new_section = api_section.clone();
+    for cap in re.captures_iter(&api_section) {
+        let header_text = cap.get(2).unwrap().as_str();
+        let lower = header_text.to_ascii_lowercase();
+
+        // Skip headers that already match via is_export_header
+        if crate::parser::is_export_header(&format!("### {header_text}")) {
+            continue;
+        }
+
+        // Check for near-miss (Levenshtein distance ≤ 2 from any canonical)
+        for (patterns, canonical) in canonical_map {
+            for pattern in *patterns {
+                if lower.contains(pattern) {
+                    let old = format!("### {header_text}");
+                    let new = format!("### {canonical}");
+                    new_section = new_section.replacen(&old, &new, 1);
+                    modified = true;
+                    break;
+                }
+            }
+        }
+    }
+
+    if modified {
+        content.replace_range(api_start..api_end, &new_section);
+    }
+
+    modified
+}
+
 fn auto_fix_specs(root: &Path, spec_files: &[PathBuf], config: &types::SpecSyncConfig) -> usize {
     use crate::exports::get_exported_symbols_with_level;
     use crate::parser::{get_spec_symbols, parse_frontmatter};
@@ -384,6 +456,17 @@ fn auto_fix_specs(root: &Path, spec_files: &[PathBuf], config: &types::SpecSyncC
             Err(_) => continue,
         };
 
+        // First pass: fix near-miss headers
+        let mut content = content;
+        if fix_near_miss_headers(&mut content) {
+            let rel = spec_file.strip_prefix(root).unwrap_or(spec_file).display();
+            println!(
+                "  {} {rel}: renamed near-miss header(s) to canonical form",
+                "✓".green()
+            );
+            let _ = fs::write(spec_file, &content);
+        }
+
         let parsed = match parse_frontmatter(&content) {
             Some(p) => p,
             None => continue,

src/commands/score.rs

@@ -6,7 +6,7 @@ use crate::types;
 
 use super::load_and_discover;
 
-pub fn cmd_score(root: &Path, format: types::OutputFormat) {
+pub fn cmd_score(root: &Path, format: types::OutputFormat, explain: bool) {
     let json = matches!(format, types::OutputFormat::Json);
     let (config, spec_files) = load_and_discover(root, false);
     let scores: Vec<scoring::SpecScore> = spec_files
@@ -70,10 +70,33 @@ pub fn cmd_score(root: &Path, format: types::OutputFormat) {
             grade_colored,
             s.total
         );
-        println!(
-            "    Frontmatter: {}/20  Sections: {}/20  API: {}/20  Depth: {}/20  Fresh: {}/20",
-            s.frontmatter_score, s.sections_score, s.api_score, s.depth_score, s.freshness_score
-        );
+
+        if explain {
+            // Show color-coded per-category bars
+            println!(
+                "    {} {}/20  {} {}/20  {} {}/20  {} {}/20  {} {}/20",
+                "Frontmatter:".dimmed(),
+                colorize_subscore(s.frontmatter_score),
+                "Sections:".dimmed(),
+                colorize_subscore(s.sections_score),
+                "API:".dimmed(),
+                colorize_subscore(s.api_score),
+                "Depth:".dimmed(),
+                colorize_subscore(s.depth_score),
+                "Fresh:".dimmed(),
+                colorize_subscore(s.freshness_score),
+            );
+        } else {
+            println!(
+                "    Frontmatter: {}/20  Sections: {}/20  API: {}/20  Depth: {}/20  Fresh: {}/20",
+                s.frontmatter_score,
+                s.sections_score,
+                s.api_score,
+                s.depth_score,
+                s.freshness_score
+            );
+        }
+
         if !s.suggestions.is_empty() {
             for suggestion in &s.suggestions {
                 println!("    {} {suggestion}", "->".cyan());
@@ -103,3 +126,13 @@ pub fn cmd_score(root: &Path, format: types::OutputFormat) {
         project.grade_distribution[4]
     );
 }
+
+/// Colorize a subscore (out of 20) — green for 20, yellow for 10-19, red for <10.
+fn colorize_subscore(score: u32) -> String {
+    let s = score.to_string();
+    match score {
+        20 => s.green().to_string(),
+        10..=19 => s.yellow().to_string(),
+        _ => s.red().to_string(),
+    }
+}

src/main.rs

@@ -104,7 +104,7 @@ fn run() {
             format,
             provider,
         ),
-        Command::Score => commands::score::cmd_score(&root, format),
+        Command::Score { explain } => commands::score::cmd_score(&root, format, explain),
         Command::Watch => watch::run_watch(&root, cli.strict, cli.require_coverage),
         Command::Mcp => mcp::run_mcp_server(&root),
         Command::AddSpec { name } => commands::scaffold::cmd_add_spec(&root, &name),

src/parser.rs

@@ -24,11 +24,11 @@ pub fn parse_frontmatter(content: &str) -> Option<ParsedSpec> {
     let mut current_list: Vec<String> = Vec::new();
 
     for line in yaml_block.lines() {
-        // List item: "  - value"
+        // List item: "  - value" (supports spaces or tabs for indentation)
         if let Some(stripped) = line.trim_start().strip_prefix("- ")
             && current_key.is_some()
         {
-            current_list.push(stripped.trim().to_string());
+            current_list.push(strip_yaml_comment(stripped.trim()));
             continue;
         }
 
@@ -45,13 +45,13 @@ pub fn parse_frontmatter(content: &str) -> Option<ParsedSpec> {
                 current_list.clear();
             }
 
-            let value = line[colon_pos + 1..].trim();
+            let value = strip_yaml_comment(line[colon_pos + 1..].trim());
 
             if value.is_empty() || value == "[]" {
                 current_key = Some(key.to_string());
                 current_list.clear();
             } else {
-                set_scalar(&mut fm, key, value);
+                set_scalar(&mut fm, key, &value);
             }
             continue;
         }
@@ -77,6 +77,25 @@ pub fn parse_frontmatter(content: &str) -> Option<ParsedSpec> {
     })
 }
 
+/// Strip inline YAML comments from a value.
+/// Handles: `value # comment` → `value`
+/// Preserves: `value` (no comment), quoted strings with `#` inside.
+fn strip_yaml_comment(value: &str) -> String {
+    // Don't strip from quoted strings or bracket arrays
+    if value.starts_with('"') || value.starts_with('\'') || value.starts_with('[') {
+        return value.to_string();
+    }
+    // Find ` # ` pattern (space-hash-space) which is a YAML comment
+    if let Some(pos) = value.find(" #") {
+        // Verify the # is followed by a space or is at end of string (YAML comment convention)
+        let after = &value[pos + 2..];
+        if after.is_empty() || after.starts_with(' ') {
+            return value[..pos].trim_end().to_string();
+        }
+    }
+    value.to_string()
+}
+
 fn set_scalar(fm: &mut Frontmatter, key: &str, value: &str) {
     match key {
         "module" => fm.module = Some(value.to_string()),
@@ -123,6 +142,22 @@ fn set_field(fm: &mut Frontmatter, key: &str, values: &[String]) {
     }
 }
 
+/// Check if a ### header describes exported symbols (case-insensitive).
+/// Matches headers containing "Exported", "Exports", "Export", or "Public" as keywords.
+/// Examples that match:
+///   "### Exported Functions", "### TypeScript Exports", "### Exports",
+///   "### Public Types", "### Export Functions", "### Exported Symbols"
+/// Examples that do NOT match:
+///   "### API Endpoints", "### Component API", "### Configuration",
+///   "### Internal Functions", "### Route Handlers"
+pub fn is_export_header(header: &str) -> bool {
+    let lower = header.to_ascii_lowercase();
+    lower.contains("exported")
+        || lower.contains("exports")
+        || lower.contains("export ")
+        || lower.contains("public ")
+}
+
 static TABLE_ROW_RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"^\|\s*`(\w+)`").unwrap());
 
 static METHOD_HEADER_RE: LazyLock<Regex> =
@@ -179,12 +214,16 @@ pub fn get_spec_symbols(body: &str) -> Vec<String> {
             .find(|l| !l.is_empty())
             .unwrap_or("");
 
-        // Allowlist: only validate tables under ### headers containing "Exported"
-        // (e.g., "### Exported Functions", "### Exported Types").
+        // Allowlist: only validate tables under ### headers that describe exports.
+        // Accepted patterns (case-insensitive):
+        //   - "### Exported Functions", "### Exported Types" (contains "Exported")
+        //   - "### TypeScript Exports", "### Exports" (contains "Exports")
+        //   - "### Public Functions", "### Public Types" (contains "Public")
+        //   - "### Exported Symbols", "### Export Types" (contains "Export")
         // Tables directly under ## Public API (no ### header) are also validated.
         // Everything else (### API Endpoints, ### Component API, ### Route Handlers,
         // ### Configuration, ### Internal Functions, etc.) is informational only.
-        if header.starts_with("### ") && !header.contains("Exported") {
+        if header.starts_with("### ") && !is_export_header(header) {
             continue;
         }
 
@@ -246,6 +285,42 @@ mod tests {
         assert!(parsed.frontmatter.db_tables.is_empty());
     }
 
+    #[test]
+    fn test_strip_yaml_comment() {
+        assert_eq!(strip_yaml_comment("active"), "active");
+        assert_eq!(strip_yaml_comment("active # this is the status"), "active");
+        assert_eq!(strip_yaml_comment("value #no-space-means-not-comment"), "value #no-space-means-not-comment");
+        assert_eq!(strip_yaml_comment("[42, 57] # issue list"), "[42, 57] # issue list"); // brackets preserved
+        assert_eq!(strip_yaml_comment("\"quoted # value\""), "\"quoted # value\""); // quotes preserved
+        assert_eq!(strip_yaml_comment("value #"), "value");
+    }
+
+    #[test]
+    fn test_parse_frontmatter_inline_comments() {
+        let content = "---\nmodule: auth # the auth module\nversion: 1 # initial\nstatus: active # current status\nfiles:\n  - src/auth.ts # main file\n---\n\n# Auth\n";
+        let parsed = parse_frontmatter(content).unwrap();
+        assert_eq!(parsed.frontmatter.module.as_deref(), Some("auth"));
+        assert_eq!(parsed.frontmatter.version.as_deref(), Some("1"));
+        assert_eq!(parsed.frontmatter.status.as_deref(), Some("active"));
+        assert_eq!(parsed.frontmatter.files, vec!["src/auth.ts"]);
+    }
+
+    #[test]
+    fn test_parse_frontmatter_tabs_and_whitespace() {
+        // Tabs used for indentation instead of spaces
+        let content = "---\nmodule: auth\nversion: 1\nstatus: active\nfiles:\n\t- src/auth.ts\n\t- src/auth.utils.ts\n---\n\n# Auth\n";
+        let parsed = parse_frontmatter(content).unwrap();
+        assert_eq!(parsed.frontmatter.files, vec!["src/auth.ts", "src/auth.utils.ts"]);
+    }
+
+    #[test]
+    fn test_parse_frontmatter_trailing_spaces() {
+        let content = "---\nmodule: auth   \nversion: 1  \nstatus: active  \nfiles:\n  - src/auth.ts   \n---\n\n# Auth\n";
+        let parsed = parse_frontmatter(content).unwrap();
+        assert_eq!(parsed.frontmatter.module.as_deref(), Some("auth"));
+        assert_eq!(parsed.frontmatter.files, vec!["src/auth.ts"]);
+    }
+
     #[test]
     fn test_parse_frontmatter_missing() {
         let content = "# No frontmatter here\n\nJust markdown.";
@@ -368,6 +443,57 @@ Something
         assert!(parsed.frontmatter.tracks.is_empty());
     }
 
+    #[test]
+    fn test_is_export_header() {
+        // Should match
+        assert!(is_export_header("### Exported Functions"));
+        assert!(is_export_header("### Exported Types"));
+        assert!(is_export_header("### TypeScript Exports"));
+        assert!(is_export_header("### Exports"));
+        assert!(is_export_header("### Public Functions"));
+        assert!(is_export_header("### Public Types"));
+        assert!(is_export_header("### Export Types"));
+        assert!(is_export_header("### Exported Symbols"));
+        assert!(is_export_header("### exported functions")); // case-insensitive
+
+        // Should NOT match
+        assert!(!is_export_header("### API Endpoints"));
+        assert!(!is_export_header("### Component API"));
+        assert!(!is_export_header("### Route Handlers"));
+        assert!(!is_export_header("### Configuration"));
+        assert!(!is_export_header("### Internal Functions"));
+    }
+
+    #[test]
+    fn test_get_spec_symbols_accepts_header_variations() {
+        let body = r#"## Public API
+
+### TypeScript Exports
+
+| Function | Description |
+|----------|-------------|
+| `createAuth` | Creates auth |
+| `validateToken` | Validates |
+
+### Public Types
+
+| Type | Description |
+|------|-------------|
+| `AuthConfig` | Config type |
+
+### API Endpoints
+
+| Endpoint | Method |
+|----------|--------|
+| `/login` | POST |
+
+## Invariants
+"#;
+        let symbols = get_spec_symbols(body);
+        // Should extract from "TypeScript Exports" and "Public Types" but not "API Endpoints"
+        assert_eq!(symbols, vec!["createAuth", "validateToken", "AuthConfig"]);
+    }
+
     #[test]
     fn test_get_spec_symbols_top_level_table() {
         // Tables directly under ## Public API (no ### header) should be validated