sherd 0.6.0

two-axis federation of SPEC.md and source over a dir DAG, for small-context local models
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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
//! `wave`'s reading of shell scripts (`src/wave:V5`): which scripts a
//! script INVOKES, resolved lexically from what the file itself says.
//!
//! An invocation is `source X`, `. X`, `bash X`, `sh X`, `exec X`, `sh <X`,
//! or `X` at command position, where `X` ends in `.sh`. A path is resolved
//! from a literal, or from an expression the file itself makes:
//! `$(dirname "$0")` and `BASH_SOURCE` (the script's own dir),
//! `$(git rev-parse --show-toplevel)` (the root), `$(cd X && pwd)` (X), a
//! variable the same file assigned one of those, and `${VAR:-default}` (VAR
//! if known, else the default the file wrote). A variable the file does NOT
//! bind -- an argument, the environment -- is INFERRED when the literal tail
//! after it names a tracked script from the root: `$REPO_ROOT/b/x.sh` with
//! `REPO_ROOT="$1"` is `b/x.sh`. That edge may be false, and a false edge is
//! the safe direction (`src/wave:V6`). A variable the file assigned a script
//! (`X=…/y.sh`, `X=${ENV:-…/y.sh}`) and then RUNS -- `"$X" verb` -- is a
//! call of that value, resolved the same ways (`src/wave:V10`). Anything else -- a name built at run
//! time, a tail naming no tracked script -- is UNRESOLVED and handed back as
//! written.

use std::collections::BTreeMap;
use std::path::{Component, Path, PathBuf};

/// What one invocation resolved to.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) enum Target {
    /// A tracked script.
    Script(PathBuf),
    /// A tracked script named by its root-relative tail after a variable the
    /// file never bound (`src/wave:V6`).
    Inferred(PathBuf),
    /// The call as written, which names no tracked script.
    Unresolved(String),
}

/// Where a script sits and what it may resolve against.
pub(super) struct Context<'a> {
    pub script: &'a Path,
    pub root: &'a Path,
    pub all: &'a [PathBuf],
}

type Vars = BTreeMap<String, PathBuf>;
/// Variables holding a script, by the value the file wrote (`src/wave:V10`).
type Held = BTreeMap<String, String>;

/// Every invocation in a script's text, in order.
pub(super) fn calls(text: &str, cx: &Context<'_>) -> Vec<Target> {
    let mut vars = Vars::new();
    let mut held = Held::new();
    let mut out = Vec::new();
    for line in text.lines() {
        let line = line.trim();
        if line.starts_with('#') {
            continue;
        }
        let words = words(line);
        assign(&words, cx, &mut vars, &mut held);
        for call in invoked(&words, &held) {
            out.push(resolve(&call, cx, &vars));
        }
    }
    out
}

/// Record each leading `NAME=value` whose value names a path this can
/// resolve, and each whose value names a script. Later assignments win, as
/// they do when the script runs.
fn assign(
    words: &[String],
    cx: &Context<'_>,
    vars: &mut Vars,
    held: &mut Held,
) {
    let prefix = ["export", "readonly", "local"];
    for w in words.iter().filter(|w| !prefix.contains(&w.as_str())) {
        let Some((name, value)) = w.split_once('=') else {
            break;
        };
        if !is_name(name) {
            break;
        }
        let value = unquote(value);
        let dir = eval(&value, cx, vars);
        set(vars, name, dir);
        let call = held_call(&value, vars, held);
        set(held, name, call);
    }
}

/// Bind `name`, or forget it when the new value says nothing this can use.
fn set<V>(map: &mut BTreeMap<String, V>, name: &str, value: Option<V>) {
    match value {
        Some(v) => map.insert(name.to_string(), v),
        None => map.remove(name),
    };
}

/// The call a value makes when run, if it names a script: itself when it
/// ends in `.sh`; for `${NAME:-default}` what NAME holds when this file
/// bound it, else the default -- an override from outside is not known, and
/// the default is what runs without one. A default `bash X` / `sh X` is `X`.
fn held_call(value: &str, vars: &Vars, held: &Held) -> Option<String> {
    if value.ends_with(".sh") {
        return Some(value.to_string());
    }
    let (inner, tail) = balanced(value.strip_prefix("${")?, '{', '}')?;
    let (name, default) = inner.split_once(":-").filter(|_| tail.is_empty())?;
    match held.get(name) {
        Some(call) => Some(call.clone()),
        None if vars.contains_key(name) => None,
        None => default_call(default),
    }
}

/// A `${NAME:-default}` default that runs a script: `X.sh`, or `bash X.sh`.
fn default_call(default: &str) -> Option<String> {
    let words = words(default);
    let call = match words.as_slice() {
        [runner, x] if is_runner(&unquote(runner)) => unquote(x),
        _ => default.to_string(),
    };
    call.ends_with(".sh").then_some(call)
}

/// The call a word makes if it is run: itself when it ends in `.sh`, the
/// value of a variable holding a script when it is `$X` or `${X}`.
fn script_word(bare: &str, held: &Held) -> Option<String> {
    if bare.ends_with(".sh") {
        return Some(bare.to_string());
    }
    let rest = bare.strip_prefix('$')?;
    let name = rest
        .strip_prefix('{')
        .and_then(|r| r.strip_suffix('}'))
        .unwrap_or(rest);
    held.get(name).cloned()
}

fn is_name(s: &str) -> bool {
    let mut cs = s.chars();
    cs.next()
        .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
        && cs.all(|c| c.is_ascii_alphanumeric() || c == '_')
}

fn is_assignment(w: &str) -> bool {
    w.split_once('=').is_some_and(|(n, _)| is_name(n))
}

/// The scripts a line invokes, including inside `$( … )`.
fn invoked(words: &[String], held: &Held) -> Vec<String> {
    let mut out = Vec::new();
    let mut at_command = true;
    let mut runner = false;
    // A shell anywhere in this command reads a `<script` redirect as its
    // program: `ssh host sh <x.sh` runs x.sh, `cat <x.sh` does not.
    let mut shell_in_command = false;
    for w in words {
        for inner in substitutions(w) {
            out.extend(invoked(&self::words(&inner), held));
        }
        let bare = unquote(w);
        shell_in_command |= matches!(bare.as_str(), "sh" | "bash");
        if is_separator(&bare) {
            at_command = true;
            runner = false;
            shell_in_command = false;
            continue;
        }
        let call = script_word(&bare, held);
        let script = call.is_some();
        if shell_in_command && script && bare.starts_with('<') {
            out.push(bare);
            continue;
        }
        let flag = runner && bare.starts_with('-');
        let prefix = at_command && is_assignment(w);
        if flag || prefix {
            continue;
        }
        let next_runner = at_command && !script && is_runner(&bare);
        if let Some(call) = call.filter(|_| at_command || runner) {
            out.push(call);
        }
        runner = next_runner;
        at_command = false;
    }
    out
}

fn is_runner(w: &str) -> bool {
    matches!(w, "source" | "." | "bash" | "sh" | "exec")
}

fn is_separator(w: &str) -> bool {
    matches!(
        w,
        ";" | "&&"
            | "||"
            | "|"
            | "&"
            | "then"
            | "do"
            | "else"
            | "elif"
            | "if"
            | "while"
            | "until"
            | "!"
            | "time"
            | "{"
            | "("
    )
}

/// The bodies of the `$( … )` substitutions in one word.
fn substitutions(word: &str) -> Vec<String> {
    let mut out = Vec::new();
    let mut rest = word;
    while let Some(i) = rest.find("$(") {
        let after = rest.get(i.saturating_add(2)..).unwrap_or("");
        match balanced(after, '(', ')') {
            Some((inner, tail)) => {
                out.push(inner.to_string());
                rest = tail;
            }
            None => break,
        }
    }
    out
}

/// Shell words: split on unquoted blanks outside `$( … )`, with `;`, `|`
/// and `&` runs as words of their own.
fn words(line: &str) -> Vec<String> {
    let mut out = Vec::new();
    let mut cur = String::new();
    let mut quote: Option<char> = None;
    let mut depth = 0usize;
    let mut chars = line.chars().peekable();
    while let Some(c) = chars.next() {
        match (quote, c) {
            (Some(q), _) if c == q => {
                quote = None;
                cur.push(c);
            }
            (Some(_), _) => cur.push(c),
            (None, '\'' | '"') => {
                quote = Some(c);
                cur.push(c);
            }
            (None, '(') => {
                depth = depth.saturating_add(1);
                cur.push(c);
            }
            (None, ')') => {
                depth = depth.saturating_sub(1);
                cur.push(c);
            }
            (None, ' ' | '\t') if depth == 0 => flush(&mut cur, &mut out),
            (None, ';' | '|' | '&') if depth == 0 => {
                flush(&mut cur, &mut out);
                let mut op = c.to_string();
                while chars.next_if_eq(&c).is_some() {
                    op.push(c);
                }
                out.push(op);
            }
            _ => cur.push(c),
        }
    }
    flush(&mut cur, &mut out);
    out
}

fn flush(cur: &mut String, out: &mut Vec<String>) {
    if !cur.is_empty() {
        out.push(std::mem::take(cur));
    }
}

fn unquote(w: &str) -> String {
    w.chars().filter(|c| *c != '"' && *c != '\'').collect()
}

/// The path an expression names, if the file itself says: `$( … )` and
/// `$VAR` / `${VAR}` / `${VAR:-default}` at the front, then any literal
/// tail joined on. A tail that still holds a `$` is built at run time, and
/// is not guessed.
fn eval(expr: &str, cx: &Context<'_>, vars: &Vars) -> Option<PathBuf> {
    if expr.starts_with('/') && !expr.contains('$') {
        return Some(normalize(Path::new(expr)));
    }
    let (base, tail) = if let Some(rest) = expr.strip_prefix("$(") {
        let (inner, tail) = balanced(rest, '(', ')')?;
        (command_dir(inner.trim(), cx, vars)?, tail)
    } else if let Some(rest) = expr.strip_prefix("${") {
        let (inner, tail) = balanced(rest, '{', '}')?;
        (braced(inner, cx, vars)?, tail)
    } else {
        let rest = expr.strip_prefix('$')?;
        let end = rest
            .find(|c: char| !(c.is_ascii_alphanumeric() || c == '_'))
            .unwrap_or(rest.len());
        let (name, tail) = rest.split_at(end);
        (vars.get(name).cloned()?, tail)
    };
    if tail.contains('$') {
        return None;
    }
    Some(normalize(&base.join(tail.trim_start_matches('/'))))
}

/// `${NAME}`, or `${NAME:-default}`: NAME when this file assigned it, else
/// the default the file wrote.
fn braced(inner: &str, cx: &Context<'_>, vars: &Vars) -> Option<PathBuf> {
    match inner.split_once(":-") {
        Some((name, default)) => {
            vars.get(name).cloned().or_else(|| eval(default, cx, vars))
        }
        None => vars.get(inner).cloned(),
    }
}

/// The directory a command substitution prints, for the commands a script
/// uses to find itself: `dirname "$0"`, `cd X && pwd`, and the repo root.
fn command_dir(cmd: &str, cx: &Context<'_>, vars: &Vars) -> Option<PathBuf> {
    if let Some(arg) = cmd.strip_prefix("dirname ") {
        let own = arg.contains("$0") || arg.contains("BASH_SOURCE");
        return own.then(|| cx.script.parent().map(Path::to_path_buf))?;
    }
    if cmd.starts_with("git rev-parse --show-toplevel") {
        return Some(cx.root.to_path_buf());
    }
    // `cd "$X/.." 2>/dev/null && pwd`: the path is the first word only.
    let rest = cmd.strip_prefix("cd ")?;
    let arg = words(rest).into_iter().next()?;
    eval(&unquote(&arg), cx, vars)
}

/// The text up to the bracket that closes an already-open one, and what
/// follows it.
fn balanced(s: &str, open: char, close: char) -> Option<(&str, &str)> {
    let mut depth = 1usize;
    for (i, c) in s.char_indices() {
        if c == open {
            depth = depth.saturating_add(1);
        } else if c == close {
            depth = depth.saturating_sub(1);
            if depth == 0 {
                return Some((s.get(..i)?, s.get(i.saturating_add(1)..)?));
            }
        }
    }
    None
}

/// Lexical normalisation: `.` dropped, `..` pops. No filesystem access, so
/// the answer does not depend on what exists or where a symlink points.
fn normalize(p: &Path) -> PathBuf {
    let mut out = PathBuf::new();
    for c in p.components() {
        match c {
            Component::CurDir => {}
            Component::ParentDir => {
                out.pop();
            }
            other => out.push(other.as_os_str()),
        }
    }
    out
}

/// One invoked word, onto a tracked script or back as written.
fn resolve(call: &str, cx: &Context<'_>, vars: &Vars) -> Target {
    let call = call.trim_start_matches('<');
    let candidates: Vec<PathBuf> = if call.starts_with('$') {
        eval(call, cx, vars).into_iter().collect()
    } else if call.contains('$') {
        Vec::new()
    } else {
        let here = cx.script.parent().unwrap_or(cx.root);
        vec![normalize(&here.join(call)), normalize(&cx.root.join(call))]
    };
    // Inference is for a variable the file left UNBOUND (`src/wave:V6`). One
    // it bound has a lexical answer, and a miss there stays a miss: a
    // `$(dirname "$0")` root does not get to borrow the repository root's.
    let bound = !candidates.is_empty();
    if let Some(p) = candidates.into_iter().find(|c| cx.all.contains(c)) {
        return Target::Script(p);
    }
    if bound {
        return Target::Unresolved(call.to_string());
    }
    unbound_tail(call)
        .map(|tail| normalize(&cx.root.join(tail)))
        .filter(|p| cx.all.contains(p))
        .map_or_else(|| Target::Unresolved(call.to_string()), Target::Inferred)
}

/// The literal path after a leading `$NAME`, `${NAME}` or `${NAME:-x}`, when
/// the rest holds no `$` -- `$REPO_ROOT/b/x.sh` is `b/x.sh`. `None` for
/// anything built at run time past the first word.
fn unbound_tail(call: &str) -> Option<&str> {
    let rest = call.strip_prefix('$')?;
    let tail = if let Some(braced) = rest.strip_prefix('{') {
        balanced(braced, '{', '}')?.1
    } else {
        let end = rest
            .find(|c: char| !(c.is_ascii_alphanumeric() || c == '_'))
            .unwrap_or(rest.len());
        rest.get(end..)?
    };
    let tail = tail.strip_prefix('/')?;
    (!tail.is_empty() && !tail.contains('$')).then_some(tail)
}