agent-file-tools 0.56.0

Agent File Tools — tree-sitter powered code analysis for AI agents
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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

use crate::commands::semantic_search::extensions::{ExactMode, LanePlan, QueryFacts, Readiness};
use crate::commands::semantic_search::plan_table::{SearchLaneKind, SearchShape};

/// Builds the legal row and then removes only lanes gated by unavailable resources.
pub fn plan<'a>(
    shape: &SearchShape,
    facts: &QueryFacts,
    readiness: &Readiness<'a>,
) -> LanePlan<'a> {
    let legal = legal_lanes(*shape, facts);
    let mut selected_lanes = legal
        .iter()
        .copied()
        .filter(|lane| lane_is_ready(*lane, readiness))
        .collect::<Vec<_>>();

    if selected_lanes.is_empty() {
        selected_lanes.push(SearchLaneKind::FallbackWalk);
    }

    let mut executed_callbacks = selected_lanes.clone();
    if readiness_disclosure_required(&legal, readiness) {
        executed_callbacks.push(SearchLaneKind::ReadinessDisclosure);
    }

    let exact_mode = if !legal.contains(&SearchLaneKind::Exact) {
        ExactMode::NotApplicable
    } else if readiness.lexical_index && facts.exact_input_tokens > 0 {
        ExactMode::Ready
    } else {
        ExactMode::Fallback
    };

    LanePlan {
        shape: *shape,
        query_facts: facts.clone(),
        exact_input: None,
        exact_mode,
        selected_lanes,
        executed_callbacks,
        readiness: readiness.clone(),
        variants: Vec::new(),
    }
}

/// Returns the all-ready retrieval row before resource gating.
///
/// Chair ruling R2a makes exact evidence shape-independent for every non-regex
/// query. The exact lane's score-free, admission-exempt result can lead only
/// when it finds the verbatim phrase, so selecting it cannot displace semantic
/// ranking when no exact evidence exists. Chair ruling R1a also treats a path
/// fact as lane-selection evidence without changing the token-count-driven
/// shape; a runtime-resolved path lookup runs before exact evidence. Chair
/// ruling R1b selects symbol lookup for natural-language queries only when the
/// classifier found an identifier-shaped token, leaving ordinary prose
/// unchanged. Regex remains on its pinned owner.
pub fn legal_lanes(shape: SearchShape, facts: &QueryFacts) -> Vec<SearchLaneKind> {
    let mut lanes = match shape {
        SearchShape::Identifier => vec![
            SearchLaneKind::Symbol,
            SearchLaneKind::Exact,
            SearchLaneKind::Lexical,
            SearchLaneKind::Variants,
        ],
        SearchShape::Short => vec![
            SearchLaneKind::Symbol,
            SearchLaneKind::Exact,
            SearchLaneKind::Lexical,
            SearchLaneKind::Variants,
            SearchLaneKind::Semantic,
        ],
        SearchShape::CodeLiteral => vec![SearchLaneKind::Exact, SearchLaneKind::Lexical],
        SearchShape::NaturalLanguage => vec![
            SearchLaneKind::Exact,
            SearchLaneKind::Lexical,
            SearchLaneKind::Semantic,
        ],
        SearchShape::LogExcerpt => vec![
            SearchLaneKind::Exact,
            SearchLaneKind::Anchored,
            SearchLaneKind::Lexical,
        ],
        SearchShape::Path => vec![
            SearchLaneKind::PathLookup,
            SearchLaneKind::Exact,
            SearchLaneKind::Lexical,
        ],
        SearchShape::Regex => vec![SearchLaneKind::FallbackWalk],
    };

    if shape == SearchShape::NaturalLanguage
        && facts.has_identifier_token
        && !lanes.contains(&SearchLaneKind::Symbol)
    {
        lanes.insert(0, SearchLaneKind::Symbol);
    }
    if shape != SearchShape::Regex
        && facts.has_path_token
        && !lanes.contains(&SearchLaneKind::PathLookup)
    {
        let before_exact = lanes
            .iter()
            .position(|lane| *lane == SearchLaneKind::Exact)
            .unwrap_or(0);
        lanes.insert(before_exact, SearchLaneKind::PathLookup);
    }
    lanes
}

fn lane_is_ready(lane: SearchLaneKind, readiness: &Readiness<'_>) -> bool {
    match lane {
        SearchLaneKind::Symbol => readiness.symbol_index,
        SearchLaneKind::Lexical | SearchLaneKind::Variants => readiness.lexical_index,
        SearchLaneKind::Semantic => readiness.semantic_index,
        SearchLaneKind::Exact
        | SearchLaneKind::Anchored
        | SearchLaneKind::PathLookup
        | SearchLaneKind::FallbackWalk
        | SearchLaneKind::ReadinessDisclosure => true,
    }
}

fn readiness_disclosure_required(legal: &[SearchLaneKind], readiness: &Readiness<'_>) -> bool {
    (!readiness.symbol_index && legal.contains(&SearchLaneKind::Symbol))
        || (!readiness.lexical_index
            && legal
                .iter()
                .any(|lane| matches!(lane, SearchLaneKind::Lexical | SearchLaneKind::Variants)))
        || (!readiness.semantic_index && legal.contains(&SearchLaneKind::Semantic))
}