instruction-files 0.2.0

Discovery, auditing, and sync for AGENTS.md/CLAUDE.md instruction files
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

//! Discovery, auditing, and sync for AGENTS.md/CLAUDE.md instruction files.

mod audit;
mod discovery;
pub use agent_runbooks as runbooks;
#[cfg(feature = "ontology")]
pub mod ontology;
#[cfg(feature = "spec-audit")]
pub mod spec_audit;
mod types;

pub use audit::{
    check_actionable, check_context_invariant, check_line_budget, check_staleness,
    check_tree_paths,
};
pub use discovery::{find_instruction_files, find_root};
#[cfg(feature = "ontology")]
pub use ontology::check_ontology_terms;
pub use runbooks::init_runbooks;
pub use types::{AuditConfig, Issue, is_agent_file};

use agent_kit::audit_common::LINE_BUDGET;
use anyhow::Result;
use std::path::Path;

/// Run the full audit with the given configuration.
///
/// Returns `Ok(())` on success, calls `std::process::exit(1)` on issues found.
///
/// When the `ontology` feature is enabled and `ontology_dir` is provided,
/// instruction files are also scanned for `[term:Name]` annotations and
/// each term is verified against the ontology directory.
pub fn run(
    config: &AuditConfig,
    root_override: Option<&Path>,
    #[cfg(feature = "ontology")] ontology_dir: Option<&Path>,
) -> Result<()> {
    println!("Auditing docs...\n");

    let root = match root_override {
        Some(p) => p.to_path_buf(),
        None => find_root(config),
    };
    let files = find_instruction_files(&root, config);
    let mut issues: Vec<Issue> = Vec::new();

    for doc in &files {
        let rel = doc
            .strip_prefix(&root)
            .unwrap_or(doc)
            .to_string_lossy()
            .to_string();
        if let Ok(content) = std::fs::read_to_string(doc) {
            issues.extend(check_tree_paths(&rel, &content, &root));
            issues.extend(check_actionable(&rel, &content, config));
            issues.extend(check_context_invariant(&rel, &content, config));
            #[cfg(feature = "ontology")]
            if let Some(onto_dir) = ontology_dir {
                issues.extend(check_ontology_terms(&rel, &content, onto_dir));
            }
        }
    }

    let (budget_issues, counts, total) = check_line_budget(&files, &root, config);
    issues.extend(budget_issues);
    issues.extend(check_staleness(&files, &root, config));

    for issue in &issues {
        let mut loc = format!("  {}", issue.file);
        if issue.line > 0 {
            if issue.end_line > issue.line {
                loc.push_str(&format!(":{}-{}", issue.line, issue.end_line));
            } else {
                loc.push_str(&format!(":{}", issue.line));
            }
        }
        let marker = if issue.warning { "\u{26a0}" } else { "\u{2717}" };
        println!("{:<50} {} {}", loc, marker, issue.message);
    }

    let mark = if total <= LINE_BUDGET {
        "\u{2713}"
    } else {
        "\u{2717}"
    };
    println!(
        "\nCombined instruction files: {} lines (budget: {}) {}",
        total, LINE_BUDGET, mark
    );
    for (name, n) in &counts {
        println!("  {}: {}", name, n);
    }

    let n = issues.len();
    if n > 0 {
        println!("\nFound {} issue(s)", n);
        std::process::exit(1);
    } else {
        println!("\nNo issues found \u{2713}");
    }

    Ok(())
}