feat(agnix-rules): derive tool mappings from rules.json (#176) (#178)

* feat(agnix-rules): derive tool mappings from rules.json at compile time

- Enhanced build.rs to extract VALID_TOOLS and TOOL_RULE_PREFIXES from rules.json
- VALID_TOOLS: unique tools from evidence.applies_to.tool field
- TOOL_RULE_PREFIXES: mapping of (prefix, tool) for tool-specific rules
- Added helper functions: valid_tools(), get_tool_for_prefix(), get_prefixes_for_tool()
- Added is_valid_tool() and normalize_tool_name() for tool validation
- All mappings generated at compile time with zero runtime cost

* build: add agnix-rules as workspace dependency

- Add agnix-rules to [workspace.dependencies] in root Cargo.toml
- Add agnix-rules.workspace = true to agnix-core dependencies

* fix(agnix-rules): exclude mixed-tool prefixes from mapping

Prefixes where some rules have a tool and others have empty applies_to
are now excluded from TOOL_RULE_PREFIXES. This prevents incorrect
filtering where generic rules would be blocked.

For example: CC-MEM- has some rules with "claude-code" and some with
empty applies_to (making them generic), so CC-MEM- is not in the mapping.

* refactor(config): use derived tool mappings from agnix-rules

Replace hardcoded tool_mapping in is_rule_for_tools() with
TOOL_RULE_PREFIXES derived from rules.json at compile time.

- Use agnix_rules::TOOL_RULE_PREFIXES for prefix-to-tool lookup
- Add backward compat: "copilot" alias for "github-copilot"
- Maintain existing behavior for generic rules (apply to all tools)

* refactor(cli): use agnix_rules::valid_tools() in rule_parity test

Replace hardcoded tool list with valid_tools() derived from rules.json.
This ensures the test automatically stays in sync with actual tool data.

* test: add review-requested test coverage

Add tests for critical and high severity review findings:

- test_tool_rule_prefixes_consistency: verifies every tool in
  TOOL_RULE_PREFIXES is also in VALID_TOOLS (no orphaned entries)
- test_is_tool_alias_case_sensitivity: verifies "Copilot" and
  "COPILOT" match "github-copilot" via case-insensitive alias
- test_mixed_tool_prefix_as: verifies AS- returns None (all generic)
- test_mixed_tool_prefix_cc_mem: verifies CC-MEM- returns None (mixed)
- test_consistent_tool_prefix_cc_hk: verifies CC-HK- returns Some

* fix: address all review findings (medium/low severity)

- Add doc comment to is_tool_alias() explaining why only github-copilot
  has an alias (backward compatibility with configs using 'copilot')
- Add comment noting TOOL_RULE_PREFIXES is small (~6 entries) so
  linear search is acceptable, but could use HashMap if it grows
- Add tests for get_prefixes_for_tool() edge cases:
  - Empty string as tool (returns empty Vec)
  - Unknown tool (returns empty Vec)
  - Tool with multiple prefixes (claude-code returns multiple)
- Add tests for is_tool_alias() edge cases:
  - Unknown alias returns false
  - Canonical name 'github-copilot' is NOT treated as alias of itself
- Add tests for get_tool_for_prefix() edge cases:
  - Empty prefix returns None
  - Unknown prefix returns None
- Add test verifying empty tool strings are treated as generic
  (not added to VALID_TOOLS or TOOL_RULE_PREFIXES)
- Add clippy allow attribute to rule_parity.rs for test patterns

* docs: add CHANGELOG entry for tool mappings derivation

* style: apply cargo fmt

* fix: address Gemini review feedback

- Use rsplit_once in extract_rule_prefix for efficiency and to handle
  edge cases like trailing hyphens correctly
- Make get_prefixes_for_tool case-insensitive for API consistency
- Simplify test_is_tool_alias_case_sensitivity with loop iteration

Author: avifenesh

CHANGELOG.md

@@ -91,6 +91,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added validation pipeline tests for AGENTS.md path collection and files_checked counter (#83)
 
 ### Changed
+- Tool mappings derived from rules.json at compile time (#176)
+  - VALID_TOOLS and TOOL_RULE_PREFIXES now extracted from rules.json evidence metadata
+  - New helper functions in agnix-rules: valid_tools(), get_tool_for_prefix(), get_prefixes_for_tool()
+  - Config tools array validation uses derived mappings instead of hardcoded list
+  - Backward compatibility maintained with "copilot" alias for "github-copilot"
+  - Zero runtime cost - all mappings resolved at compile time
 - Narrowed agnix-core public API surface (#85)
   - Made `parsers`, `rules`, `schemas`, and `file_utils` modules private
   - Re-exported `Validator` trait for custom validator implementations

Cargo.lock

@@ -19,6 +19,9 @@ keywords = ["agent", "linter", "claude", "skills", "mcp"]
 categories = ["development-tools", "command-line-utilities"]
 
 [workspace.dependencies]
+# Internal crates
+agnix-rules = { path = "crates/agnix-rules", version = "0.1.0" }
+
 # Core dependencies
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

Cargo.toml

@@ -6,6 +6,9 @@
 //! 3. Covered by test fixtures in tests/fixtures/
 //! 4. Have valid evidence metadata
 
+// Allow common test patterns that clippy flags but are intentional in tests
+#![allow(clippy::field_reassign_with_default)]
+
 use regex::Regex;
 use serde::Deserialize;
 use std::collections::{BTreeSet, HashMap};
@@ -666,13 +669,8 @@ fn test_evidence_test_coverage_accuracy() {
 fn test_applies_to_tool_values() {
     let rules_index = load_rules_json();
 
-    let valid_tools = [
-        "claude-code",
-        "cursor",
-        "github-copilot",
-        "windsurf",
-        // Add more as needed
-    ];
+    // Use valid_tools derived from rules.json at compile time
+    let valid_tools = agnix_rules::valid_tools();
 
     for rule in &rules_index.rules {
         if let Some(ref tool) = rule.evidence.applies_to.tool {
@@ -686,3 +684,47 @@ fn test_applies_to_tool_values() {
         }
     }
 }
+
+// ============================================================================
+// Tool Mapping Consistency Tests (Review-requested coverage)
+// ============================================================================
+
+#[test]
+fn test_tool_rule_prefixes_consistency() {
+    // Every tool in TOOL_RULE_PREFIXES must also exist in VALID_TOOLS
+    // This ensures no orphaned tools or prefixes exist
+    let valid_tools = agnix_rules::valid_tools();
+
+    for (prefix, tool) in agnix_rules::TOOL_RULE_PREFIXES {
+        assert!(
+            valid_tools.contains(tool),
+            "Tool '{}' from prefix '{}' is not in VALID_TOOLS. \
+             TOOL_RULE_PREFIXES and VALID_TOOLS must be consistent.",
+            tool,
+            prefix
+        );
+    }
+}
+
+#[test]
+fn test_is_tool_alias_case_sensitivity() {
+    // Test that tool alias matching is case insensitive
+    // "Copilot" (mixed case) and "COPILOT" (uppercase) should both
+    // be recognized as valid tools via the alias mechanism
+
+    // The is_tool_alias function is private, but we can test through
+    // LintConfig::is_rule_enabled which uses it internally
+
+    use agnix_core::LintConfig;
+
+    let aliases = ["Copilot", "COPILOT", "copilot"];
+    for alias in aliases {
+        let mut config = LintConfig::default();
+        config.tools = vec![alias.to_string()];
+        assert!(
+            config.is_rule_enabled("COP-001"),
+            "Alias '{}' should match 'github-copilot' and enable COP-* rules",
+            alias
+        );
+    }
+}

crates/agnix-cli/tests/rule_parity.rs

@@ -12,6 +12,7 @@ keywords = ["agent", "linter", "validation", "mcp", "skills"]
 categories = ["development-tools", "parser-implementations"]
 
 [dependencies]
+agnix-rules.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 serde_yaml.workspace = true

crates/agnix-core/Cargo.toml

@@ -332,26 +332,44 @@ impl LintConfig {
 
     /// Check if a rule applies based on the tools array
     fn is_rule_for_tools(&self, rule_id: &str) -> bool {
-        // Tool-specific rule prefixes and their corresponding tool names
-        let tool_mapping: &[(&str, &[&str])] = &[
-            ("CC-", &["claude-code"]), // Claude Code specific rules
-            ("COP-", &["copilot"]),    // GitHub Copilot specific rules
-            ("CUR-", &["cursor"]),     // Cursor specific rules
-        ];
-
-        for (prefix, tool_names) in tool_mapping {
+        // Use TOOL_RULE_PREFIXES derived from rules.json at compile time.
+        // Note: TOOL_RULE_PREFIXES is small (~6 entries), so linear search is acceptable.
+        // If this grows significantly larger, consider using a HashMap for O(1) lookups.
+        for (prefix, tool) in agnix_rules::TOOL_RULE_PREFIXES {
             if rule_id.starts_with(prefix) {
-                // Check if any of the required tools is in the tools list
-                return tool_names
+                // Check if the required tool is in the tools list (case-insensitive)
+                // Also accept backward-compat aliases (e.g., "copilot" for "github-copilot")
+                return self
+                    .tools
                     .iter()
-                    .any(|t| self.tools.iter().any(|u| u.eq_ignore_ascii_case(t)));
+                    .any(|t| t.eq_ignore_ascii_case(tool) || Self::is_tool_alias(t, tool));
             }
         }
 
         // Generic rules (AS-*, XML-*, REF-*, XP-*, AGM-*, MCP-*, PE-*) apply to all tools
         true
     }
 
+    /// Check if a user-provided tool name is a backward-compatible alias
+    /// for the canonical tool name from rules.json.
+    ///
+    /// Currently only "github-copilot" has an alias ("copilot"). This exists for
+    /// backward compatibility: early versions of agnix used the shorter "copilot"
+    /// name in configs, and we need to continue supporting that for existing users.
+    /// The canonical names in rules.json use the full "github-copilot" to match
+    /// the official tool name from GitHub's documentation.
+    ///
+    /// Note: This function does NOT treat canonical names as aliases of themselves.
+    /// For example, "github-copilot" is NOT an alias for "github-copilot" - that's
+    /// handled by the direct eq_ignore_ascii_case comparison in is_rule_for_tools().
+    fn is_tool_alias(user_tool: &str, canonical_tool: &str) -> bool {
+        // Backward compatibility: accept short names as aliases
+        match canonical_tool {
+            "github-copilot" => user_tool.eq_ignore_ascii_case("copilot"),
+            _ => false,
+        }
+    }
+
     /// Check if a rule's category is enabled
     fn is_category_enabled(&self, rule_id: &str) -> bool {
         match rule_id {
@@ -1651,4 +1669,45 @@ exclude = []
         // Other CC-* rules should still work
         assert!(config.is_rule_enabled("CC-AG-001"));
     }
+
+    // ===== is_tool_alias Edge Case Tests =====
+
+    #[test]
+    fn test_is_tool_alias_unknown_alias_returns_false() {
+        // Unknown aliases should return false
+        assert!(!LintConfig::is_tool_alias("unknown", "github-copilot"));
+        assert!(!LintConfig::is_tool_alias("gh-copilot", "github-copilot"));
+        assert!(!LintConfig::is_tool_alias("", "github-copilot"));
+    }
+
+    #[test]
+    fn test_is_tool_alias_canonical_name_not_alias_of_itself() {
+        // Canonical name "github-copilot" is NOT treated as an alias of itself.
+        // This is by design - canonical names match via direct comparison in
+        // is_rule_for_tools(), not through the alias mechanism.
+        assert!(!LintConfig::is_tool_alias(
+            "github-copilot",
+            "github-copilot"
+        ));
+        assert!(!LintConfig::is_tool_alias(
+            "GitHub-Copilot",
+            "github-copilot"
+        ));
+    }
+
+    #[test]
+    fn test_is_tool_alias_copilot_is_alias_for_github_copilot() {
+        // "copilot" is an alias for "github-copilot" (backward compatibility)
+        assert!(LintConfig::is_tool_alias("copilot", "github-copilot"));
+        assert!(LintConfig::is_tool_alias("Copilot", "github-copilot"));
+        assert!(LintConfig::is_tool_alias("COPILOT", "github-copilot"));
+    }
+
+    #[test]
+    fn test_is_tool_alias_no_aliases_for_other_tools() {
+        // Other tools have no aliases defined
+        assert!(!LintConfig::is_tool_alias("claude", "claude-code"));
+        assert!(!LintConfig::is_tool_alias("cc", "claude-code"));
+        assert!(!LintConfig::is_tool_alias("cur", "cursor"));
+    }
 }

crates/agnix-core/src/config.rs

@@ -2,7 +2,13 @@
 //!
 //! Generates Rust code from rules.json at compile time.
 //! Supports both local crate builds (crates.io) and workspace builds (development).
+//!
+//! Generated constants:
+//! - `RULES_DATA`: All rule (id, name) tuples
+//! - `VALID_TOOLS`: Unique tool names from evidence.applies_to.tool
+//! - `TOOL_RULE_PREFIXES`: Mapping of (prefix, tool) for tool-specific rules
 
+use std::collections::{BTreeMap, BTreeSet};
 use std::env;
 use std::fs;
 use std::path::{Path, PathBuf};
@@ -156,10 +162,122 @@ fn main() {
         ));
     }
 
+    generated_code.push_str("];\n\n");
+
+    // =========================================================================
+    // Extract unique tools from evidence.applies_to.tool
+    // =========================================================================
+    let mut tools: BTreeSet<String> = BTreeSet::new();
+
+    for rule in rules_array {
+        if let Some(tool) = rule
+            .get("evidence")
+            .and_then(|e| e.get("applies_to"))
+            .and_then(|a| a.get("tool"))
+            .and_then(|t| t.as_str())
+        {
+            if !tool.is_empty() {
+                tools.insert(tool.to_string());
+            }
+        }
+    }
+
+    // Generate VALID_TOOLS constant
+    generated_code
+        .push_str("/// Valid tool names derived from rules.json evidence.applies_to.tool.\n");
+    generated_code.push_str("/// \n");
+    generated_code
+        .push_str("/// These are the tools that have at least one rule specifically for them.\n");
+    generated_code.push_str("pub const VALID_TOOLS: &[&str] = &[\n");
+    for tool in &tools {
+        generated_code.push_str(&format!("    \"{}\",\n", escape_str(tool)));
+    }
+    generated_code.push_str("];\n\n");
+
+    // =========================================================================
+    // Derive prefix-to-tool mappings from rule IDs
+    // =========================================================================
+    // Group rules by their prefix and track:
+    // 1. Which tools are specified for rules with this prefix
+    // 2. Whether any rule with this prefix has NO tool (making it generic)
+    #[derive(Default)]
+    struct PrefixInfo {
+        tools: BTreeSet<String>,
+        has_generic: bool, // true if any rule in this prefix has no tool specified
+    }
+
+    let mut prefix_info: BTreeMap<String, PrefixInfo> = BTreeMap::new();
+
+    for rule in rules_array {
+        let id = rule["id"].as_str().unwrap_or("");
+        let tool = rule
+            .get("evidence")
+            .and_then(|e| e.get("applies_to"))
+            .and_then(|a| a.get("tool"))
+            .and_then(|t| t.as_str());
+
+        if let Some(prefix) = extract_rule_prefix(id) {
+            let info = prefix_info.entry(prefix).or_default();
+            if let Some(tool_name) = tool {
+                if !tool_name.is_empty() {
+                    info.tools.insert(tool_name.to_string());
+                } else {
+                    info.has_generic = true;
+                }
+            } else {
+                // No tool specified = generic rule, applies to all tools
+                info.has_generic = true;
+            }
+        }
+    }
+
+    // Only include prefixes that:
+    // 1. Have exactly one tool specified AND
+    // 2. Have NO generic rules (all rules specify that tool)
+    generated_code.push_str("/// Mapping of rule ID prefixes to their associated tools.\n");
+    generated_code.push_str("/// \n");
+    generated_code.push_str(
+        "/// Derived from rules.json: for each prefix, this is the tool that all rules\n",
+    );
+    generated_code
+        .push_str("/// with that prefix apply to. Only includes prefixes where ALL rules\n");
+    generated_code
+        .push_str("/// consistently specify the same tool (excludes generic prefixes).\n");
+    generated_code.push_str("pub const TOOL_RULE_PREFIXES: &[(&str, &str)] = &[\n");
+
+    for (prefix, info) in &prefix_info {
+        // Only include if: exactly one tool AND no generic rules
+        if info.tools.len() == 1 && !info.has_generic {
+            let tool = info.tools.iter().next().unwrap();
+            generated_code.push_str(&format!(
+                "    (\"{}\", \"{}\"),\n",
+                escape_str(prefix),
+                escape_str(tool)
+            ));
+        }
+    }
     generated_code.push_str("];\n");
 
     // Write to OUT_DIR
     let out_dir = env::var("OUT_DIR").unwrap();
     let dest_path = Path::new(&out_dir).join("rules_data.rs");
     fs::write(&dest_path, generated_code).expect("Failed to write generated rules");
 }
+
+/// Extract the rule prefix from a rule ID.
+///
+/// Examples:
+/// - "CC-HK-001" -> "CC-HK-"
+/// - "COP-001" -> "COP-"
+/// - "AS-001" -> "AS-"
+fn extract_rule_prefix(rule_id: &str) -> Option<String> {
+    // Find the last hyphen. If it exists and is followed by only digits,
+    // we've found our prefix. This is more efficient than splitting into a vector
+    // and correctly handles edge cases like trailing hyphens.
+    if let Some((prefix, suffix)) = rule_id.rsplit_once('-') {
+        if !suffix.is_empty() && suffix.chars().all(|c| c.is_ascii_digit()) {
+            return Some(format!("{}-", prefix));
+        }
+    }
+    None
+}