feat: add --staged flag to devtrail validate for pre-commit hooks

montfort · claude · montfort · commit d9ea8748544f · 2026-04-01T01:14:25.000-06:00
Replaces pre-commit-docs.sh (464 lines) with native CLI support.
Adds validate_paths() for partial validation of git-staged files,
skipping orphan checks. Makes detect_doc_type() public.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/cli/src/commands/init.rs b/cli/src/commands/init.rs
@@ -70,7 +70,7 @@ pub fn run(path: &str) -> Result<()> {
     println!("    2. Check DEVTRAIL.md for governance rules");
     println!(
         "    3. Run {} to validate your setup",
-        "bash scripts/pre-commit-docs.sh".cyan()
+        "devtrail validate".cyan()
     );
     println!(
         "    4. Commit: {}",
diff --git a/cli/src/commands/validate.rs b/cli/src/commands/validate.rs
@@ -1,12 +1,12 @@
-use anyhow::Result;
+use anyhow::{bail, Result};
 use colored::Colorize;
 use std::collections::BTreeMap;
 use std::path::PathBuf;
 
 use crate::utils;
 use crate::validation::{self, Severity, ValidationIssue};
 
-pub fn run(path: &str, fix: bool) -> Result<()> {
+pub fn run(path: &str, fix: bool, staged: bool) -> Result<()> {
     let resolved = match utils::resolve_project_root(path) {
         Some(r) => r,
         None => {
@@ -32,6 +32,11 @@ pub fn run(path: &str, fix: bool) -> Result<()> {
     let target = resolved.path;
     let devtrail_dir = target.join(".devtrail");
 
+    // --staged mode: validate only git-staged .devtrail/ documents
+    if staged {
+        return run_staged(&target, &devtrail_dir);
+    }
+
     // Header
     println!();
     println!("  {}", "DevTrail Validate".bold().cyan());
@@ -46,7 +51,7 @@ pub fn run(path: &str, fix: bool) -> Result<()> {
         println!(
             "  {} Create documents with {} or {}",
             "→".blue().bold(),
-            "devtrail-new".cyan(),
+            "devtrail new".cyan(),
             "/devtrail-new".cyan()
         );
         println!();
@@ -66,6 +71,58 @@ pub fn run(path: &str, fix: bool) -> Result<()> {
     exit_with_code(&result)
 }
 
+fn run_staged(project_root: &std::path::Path, devtrail_dir: &std::path::Path) -> Result<()> {
+    // Get staged files from git
+    let output = std::process::Command::new("git")
+        .args(["diff", "--cached", "--name-only"])
+        .current_dir(project_root)
+        .output();
+
+    let output = match output {
+        Ok(o) if o.status.success() => o,
+        _ => {
+            bail!("Not a git repository or git is not available. --staged requires a git repo.");
+        }
+    };
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let staged_paths: Vec<PathBuf> = stdout
+        .lines()
+        .filter(|line| line.starts_with(".devtrail/") && line.ends_with(".md"))
+        .map(|line| project_root.join(line))
+        .collect();
+
+    if staged_paths.is_empty() {
+        println!(
+            "  {} No staged documentation to validate.",
+            "✓".green().bold()
+        );
+        return Ok(());
+    }
+
+    // Header
+    println!();
+    println!("  {}", "DevTrail Validate (staged)".bold().cyan());
+    println!(
+        "  {} file(s)",
+        staged_paths.len().to_string().dimmed()
+    );
+    println!();
+
+    let (result, doc_count) = validation::validate_paths(&staged_paths, devtrail_dir);
+
+    if doc_count == 0 {
+        println!(
+            "  {} No DevTrail documents among staged files.",
+            "✓".green().bold()
+        );
+        return Ok(());
+    }
+
+    print_results(&result, doc_count);
+    exit_with_code(&result)
+}
+
 fn apply_fixes(devtrail_dir: &std::path::Path) {
     let paths = crate::document::discover_documents(devtrail_dir);
     let mut fixed_count = 0;
diff --git a/cli/src/document.rs b/cli/src/document.rs
@@ -63,6 +63,68 @@ impl DocType {
         "AILOG", "AIDEC", "ADR", "ETH", "REQ", "TES", "INC", "TDE",
         "SEC", "MCARD", "SBOM", "DPIA",
     ];
+
+    /// All DocType variants in display order
+    pub const ALL: &'static [DocType] = &[
+        DocType::Ailog, DocType::Aidec, DocType::Adr, DocType::Eth,
+        DocType::Req, DocType::Tes, DocType::Inc, DocType::Tde,
+        DocType::Sec, DocType::Mcard, DocType::Sbom, DocType::Dpia,
+    ];
+
+    /// Human-readable display name
+    pub fn display_name(&self) -> &'static str {
+        match self {
+            DocType::Ailog => "AI Action Log",
+            DocType::Aidec => "AI Decision",
+            DocType::Adr => "Architecture Decision Record",
+            DocType::Eth => "Ethical Review",
+            DocType::Req => "Requirement",
+            DocType::Tes => "Test Plan",
+            DocType::Inc => "Incident Post-mortem",
+            DocType::Tde => "Technical Debt",
+            DocType::Sec => "Security Assessment",
+            DocType::Mcard => "Model/System Card",
+            DocType::Sbom => "Software Bill of Materials",
+            DocType::Dpia => "Data Protection Impact Assessment",
+        }
+    }
+
+    /// Subdirectory under .devtrail/ where this document type lives
+    pub fn directory(&self) -> &'static str {
+        match self {
+            DocType::Ailog => "07-ai-audit/agent-logs",
+            DocType::Aidec => "07-ai-audit/decisions",
+            DocType::Eth => "07-ai-audit/ethical-reviews",
+            DocType::Adr => "02-design/decisions",
+            DocType::Req => "01-requirements",
+            DocType::Tes => "04-testing",
+            DocType::Inc => "05-operations/incidents",
+            DocType::Tde => "06-evolution/technical-debt",
+            DocType::Sec => "08-security",
+            DocType::Mcard => "09-ai-models",
+            DocType::Sbom => "07-ai-audit",
+            DocType::Dpia => "07-ai-audit/ethical-reviews",
+        }
+    }
+
+    /// Parse a DocType from a user-provided string (case-insensitive)
+    pub fn from_str_loose(s: &str) -> Option<DocType> {
+        match s.to_lowercase().as_str() {
+            "ailog" => Some(DocType::Ailog),
+            "aidec" => Some(DocType::Aidec),
+            "adr" => Some(DocType::Adr),
+            "eth" => Some(DocType::Eth),
+            "req" => Some(DocType::Req),
+            "tes" => Some(DocType::Tes),
+            "inc" => Some(DocType::Inc),
+            "tde" => Some(DocType::Tde),
+            "sec" => Some(DocType::Sec),
+            "mcard" => Some(DocType::Mcard),
+            "sbom" => Some(DocType::Sbom),
+            "dpia" => Some(DocType::Dpia),
+            _ => None,
+        }
+    }
 }
 
 impl fmt::Display for DocType {
@@ -154,7 +216,7 @@ pub fn parse_document(path: &Path) -> Result<DevTrailDocument> {
 }
 
 /// Detect document type from filename prefix
-fn detect_doc_type(filename: &str) -> Option<DocType> {
+pub fn detect_doc_type(filename: &str) -> Option<DocType> {
     for prefix in DocType::ALL_PREFIXES {
         if filename.starts_with(&format!("{}-", prefix)) {
             return DocType::from_prefix(prefix);
@@ -276,4 +338,37 @@ mod tests {
         assert_eq!(fm.title.as_deref(), Some("Test"));
         assert!(body.contains("# Body"));
     }
+
+    #[test]
+    fn test_doc_type_all_has_12_entries() {
+        assert_eq!(DocType::ALL.len(), 12);
+        assert_eq!(DocType::ALL_PREFIXES.len(), 12);
+    }
+
+    #[test]
+    fn test_doc_type_directory_mapping() {
+        for dt in DocType::ALL {
+            let dir = dt.directory();
+            assert!(!dir.is_empty(), "{} has empty directory", dt.prefix());
+            assert!(!dir.starts_with('/'), "{} directory should be relative", dt.prefix());
+        }
+    }
+
+    #[test]
+    fn test_doc_type_display_names() {
+        for dt in DocType::ALL {
+            let name = dt.display_name();
+            assert!(!name.is_empty(), "{} has empty display_name", dt.prefix());
+        }
+    }
+
+    #[test]
+    fn test_doc_type_from_str_loose() {
+        assert_eq!(DocType::from_str_loose("ailog"), Some(DocType::Ailog));
+        assert_eq!(DocType::from_str_loose("AILOG"), Some(DocType::Ailog));
+        assert_eq!(DocType::from_str_loose("AiLog"), Some(DocType::Ailog));
+        assert_eq!(DocType::from_str_loose("sec"), Some(DocType::Sec));
+        assert_eq!(DocType::from_str_loose("mcard"), Some(DocType::Mcard));
+        assert_eq!(DocType::from_str_loose("invalid"), None);
+    }
 }
diff --git a/cli/src/main.rs b/cli/src/main.rs
@@ -68,6 +68,9 @@ enum Commands {
         /// Automatically fix simple issues
         #[arg(long)]
         fix: bool,
+        /// Validate only git-staged files (for pre-commit hooks)
+        #[arg(long)]
+        staged: bool,
     },
     /// Check regulatory compliance (EU AI Act, ISO 42001, NIST AI RMF)
     Compliance {
@@ -114,6 +117,18 @@ enum Commands {
         #[arg(long, default_value = "text", value_parser = ["text", "markdown", "json"])]
         output: String,
     },
+    /// Create a new DevTrail document from a template
+    New {
+        /// Target directory (default: current directory)
+        #[arg(default_value = ".")]
+        path: String,
+        /// Document type (e.g., ailog, adr, sec)
+        #[arg(long, short = 't')]
+        doc_type: Option<String>,
+        /// Document title
+        #[arg(long)]
+        title: Option<String>,
+    },
     /// Show version, author, and license information
     About,
     /// Analyze code complexity using cognitive and cyclomatic metrics
@@ -153,7 +168,7 @@ fn main() {
         Commands::UpdateFramework => commands::update_framework::run(),
         Commands::UpdateCli => commands::update_cli::run(),
         Commands::Remove { full } => commands::remove::run(full),
-        Commands::Validate { path, fix } => commands::validate::run(&path, fix),
+        Commands::Validate { path, fix, staged } => commands::validate::run(&path, fix, staged),
         Commands::Audit {
             path,
             from,
@@ -172,6 +187,11 @@ fn main() {
             period,
             output,
         } => commands::metrics::run(&path, &period, &output),
+        Commands::New {
+            path,
+            doc_type,
+            title,
+        } => commands::new::run(&path, doc_type.as_deref(), title.as_deref()),
         Commands::Status { path } => commands::status::run(&path),
         Commands::Repair { path } => commands::repair::run(&path),
         Commands::About => commands::about::run(),
diff --git a/cli/src/validation.rs b/cli/src/validation.rs
@@ -84,6 +84,44 @@ pub fn validate_all(devtrail_dir: &Path) -> (ValidationResult, usize) {
     (result, doc_count)
 }
 
+/// Validate a specific set of document paths (used for --staged mode).
+/// Skips orphan document checking since that is not meaningful for partial validation.
+pub fn validate_paths(paths: &[PathBuf], devtrail_dir: &Path) -> (ValidationResult, usize) {
+    let mut result = ValidationResult::default();
+    let mut doc_count = 0;
+
+    for path in paths {
+        if !path.exists() {
+            continue;
+        }
+        let filename = path.file_name().and_then(|n| n.to_str()).unwrap_or("");
+        if document::detect_doc_type(filename).is_none() {
+            continue;
+        }
+        match document::parse_document(path) {
+            Ok(doc) => {
+                doc_count += 1;
+                result.merge(validate_document(&doc, devtrail_dir));
+            }
+            Err(e) => {
+                doc_count += 1;
+                result.errors.push(ValidationIssue {
+                    file: path.clone(),
+                    rule: "PARSE-001".to_string(),
+                    message: format!("Failed to parse document: {e}"),
+                    severity: Severity::Error,
+                    fix_hint: Some(
+                        "Check that the file has valid YAML frontmatter between --- delimiters"
+                            .to_string(),
+                    ),
+                });
+            }
+        }
+    }
+
+    (result, doc_count)
+}
+
 /// REF-002: Check for documents with no traceability links.
 /// A document is orphan if it has no `related` field AND is not referenced
 /// by any other document's `related` field.
diff --git a/cli/tests/validate_test.rs b/cli/tests/validate_test.rs
@@ -417,24 +417,61 @@ fn test_new_templates_exist_in_dist() {
     assert!(devtrail.join("09-ai-models").exists(), "09-ai-models/ directory missing");
 }
 
-/// F2.QA.02.02 — Verify devtrail-new.sh has all 12 types configured
+/// F2.QA.02.02 — Verify devtrail new supports all 12 document types via DocType::ALL
 #[test]
-fn test_devtrail_new_script_has_all_types() {
-    let script_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
-        .parent()
-        .unwrap()
-        .join("dist/scripts/devtrail-new.sh");
+fn test_new_supports_all_doc_types() {
+    let source_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("src/document.rs");
 
-    let content = std::fs::read_to_string(&script_path).expect("Cannot read devtrail-new.sh");
+    let content = std::fs::read_to_string(&source_path).expect("Cannot read document.rs");
 
-    // Verify all 12 types are in DOC_PATHS
-    for doc_type in &["ailog", "aidec", "adr", "eth", "req", "tes", "inc", "tde", "sec", "mcard", "sbom", "dpia"] {
+    for doc_type in &["Ailog", "Aidec", "Adr", "Eth", "Req", "Tes", "Inc", "Tde", "Sec", "Mcard", "Sbom", "Dpia"] {
         assert!(
-            content.contains(&format!("[\"{}\"]", doc_type)),
-            "devtrail-new.sh missing DOC_PATHS entry for '{}'", doc_type
+            content.contains(&format!("DocType::{}", doc_type)),
+            "document.rs missing DocType::{}", doc_type
         );
     }
+}
+
+#[test]
+fn test_validate_staged_no_git_repo() {
+    let dir = tempfile::TempDir::new().unwrap();
+
+    // Create minimal .devtrail/
+    let devtrail = dir.path().join(".devtrail");
+    std::fs::create_dir_all(&devtrail).unwrap();
+    std::fs::write(devtrail.join("config.yml"), "language: en\n").unwrap();
+
+    let mut cmd = Command::cargo_bin("devtrail").unwrap();
+    cmd.arg("validate")
+        .arg("--staged")
+        .arg(dir.path().to_str().unwrap())
+        .assert()
+        .failure()
+        .stderr(predicates::str::contains("git"));
+}
+
+#[test]
+fn test_validate_staged_no_staged_docs() {
+    let dir = tempfile::TempDir::new().unwrap();
+
+    // Init a git repo
+    std::process::Command::new("git")
+        .args(["init"])
+        .current_dir(dir.path())
+        .output()
+        .unwrap();
+
+    // Create .devtrail/
+    let devtrail = dir.path().join(".devtrail");
+    std::fs::create_dir_all(&devtrail).unwrap();
+    std::fs::write(devtrail.join("config.yml"), "language: en\n").unwrap();
 
-    // Verify the menu has 12 options
-    assert!(content.contains("1-12 or name"), "devtrail-new.sh menu does not show 1-12 range");
+    let mut cmd = Command::cargo_bin("devtrail").unwrap();
+    cmd.arg("validate")
+        .arg("--staged")
+        .arg(dir.path().to_str().unwrap())
+        .assert()
+        .success()
+        .stdout(predicates::str::contains("No staged documentation"));
 }
