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
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
//! Arg dispatch and exit codes. The binary is a shim over `run` (`src/cli:V14`).
//!
//! A node, not a loose `main.rs`, because exit codes and usage are real
//! contracts and every §T row about them was unreachable while this file had
//! no `SPEC.md` to hold them.

use crate::{code, fed, lens, plan, slice, spec, split, state, tokens, wave};
use std::path::{Path, PathBuf};
use std::process::ExitCode;

mod parse;
use clap::Parser;
use parse::{Cmd, Verdict};

mod args;
use args::*;

mod propose;
use propose::*;

mod author;
use author::*;

mod adopt;
use adopt::*;

mod steps;
use steps::*;

mod measure;
use measure::*;

mod swift;
use swift::*;

mod check;
use check::*;

mod validate;
use validate::*;

mod plumb;
use plumb::*;

/// The verb list, and the SOURCE the README's Commands section is generated
/// from (`dev:T2`). Public so `sherd-dev` reads the text this binary actually
/// prints rather than a second copy of it: two lists of one command set is
/// the founding defect §C names, and `B2` is what it costs -- `oneshot`
/// dispatched for weeks while appearing in no usage.
pub const USAGE: &str = "\
sherd -- federated SPEC.md for small-context local models

  sherd init [dir] [--stdout]  scaffold a SPEC.md, §F rows from child dirs
  sherd budget [dir] [--format text|json]  token cost of every node, against the working budget
  sherd lens <dir> [--depth rule|why|all]  the context pack for one node
  sherd fed [dir]        the federation edges declared by a node
  sherd check [dir] [--format text|json]  microlith structural check of every node
  sherd debt [--check|--record]  lint ratchet: density & shape vs .lint-debt
  sherd coverage [--check|--record]  coverage floor vs .coverage
  sherd validate [--format text|json]  DAG + ids + ceilings + slice drift, one verdict
  sherd split [dir]      propose a federation split. writes nothing
  sherd seam [dir]       the public types each node declares. writes nothing
  sherd wave [dir]       the rounds a parallel build would run. writes nothing
  sherd adopt <dir> [--map FILE] [--check]  migrate a single-file SPEC.md onto a federation
  sherd sync [dir] [--check]  regenerate §N from §F. exit 1 if it wrote
  sherd route <query>    which node owns a question. 0 hit · 2 miss · 3 ambiguous
  sherd review [rev]     mechanical checks on what a commit added (default HEAD)
  sherd slice [--check|--list]  regenerate distilled slices from their sources
  sherd outcome <node> <kept|reverted>  record whether a node's work survived review
  sherd graph [--tree|--table|--dot]  federation DAG, generated from §F
  sherd plan [--format text|json]  next 3 steps, with what would invalidate each
  sherd plan --triage    unmanaged rows, with a proposed home for each
  sherd plan --milestone <M> [--format text|json]  next 3 steps among the rows milestone M claims
  sherd apply [--land]   execute step 1 only, commit it to a run branch, stop
  sherd land [--push]    fast-forward main to this run branch, if it earned it
  sherd ask <dir> <q>    ask the endpoint from a node's lens pack
  sherd tdd <dir> <Vn> <task>   red -> judge -> green -> gate -> repair
  sherd oneshot <dir> <Vn> <task>   the monolith arm: one call, whole repo
  sherd completions <shell>  shell completion script (bash zsh fish elvish powershell)
  sherd man              the man page, roff, on stdout

  -v, --verbose        dump every prompt and stream every reply
  -V, --version        print `sherd <semver>` and exit 0

exit: 0 clean · 1 violation · 2 usage";

/// The answer to `--version`: the crate version this binary was built from.
///
/// `env!`, so it cannot drift from `Cargo.toml` -- a second spelling of a
/// version number is the founding defect §C names, one field over.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// Parse argv and dispatch. The binary itself holds nothing (`src/cli:V14`).
#[must_use]
pub fn run() -> ExitCode {
    run_args(std::env::args().skip(1).collect())
}

/// As [`run`], from an explicit argv.
///
/// `run` read `std::env::args` directly, so dispatch -- usage, exit codes,
/// every verb's routing -- could not be exercised at all. This node measured
/// 0.0% coverage over 445 lines with no test module (`.:R50`), and an
/// untestable entry point is why. Exit codes and usage are real contracts
/// per this module's own header; a contract nothing can call is a comment.
///
/// The grammar is `parse::Cli` (`src/cli:V21`); this function only routes a
/// parsed value. A parse failure is clap's usage error -- exit 2 -- and
/// `--help`/`--version` are its success paths, exit 0.
#[must_use]
pub fn run_args(args: Vec<String>) -> ExitCode {
    let cli = match parse::Cli::try_parse_from(
        std::iter::once("sherd".to_string()).chain(args.iter().cloned()),
    ) {
        Ok(c) => c,
        Err(e) => {
            // Not `e.exit()`: that ends the process, and a test could never
            // see the code it chose.
            let code = if e.use_stderr() { 2 } else { 0 };
            let _ = e.print();
            return ExitCode::from(code);
        }
    };
    #[cfg(feature = "ollama")]
    if cli.verbose {
        crate::ollama::set_verbose(true);
    }
    let Some(mut cmd) = cli.cmd else {
        println!("{USAGE}");
        return ExitCode::SUCCESS;
    };
    // A verb with an `At` selector takes its root from the PARSED selector.
    // Scanning raw argv instead let any directory named like a flag value or
    // a query win over the trailing path.
    let root = match at_of(&cmd) {
        Some(at) => match root_at(at.as_deref()) {
            Ok(r) => r,
            Err(e) => return usage(&e),
        },
        // The rest take a `dir` field, or nothing: the parsed field, never a
        // raw argument, so `--format json` cannot be read as a directory.
        None => {
            let named: Vec<String> = std::iter::once("sherd".to_string())
                .chain(dir_of(&cmd).map(String::from))
                .collect();
            let root = root_for(&named);
            absolutize_dir(&mut cmd, &root, &cwd());
            root
        }
    };
    #[cfg(feature = "ollama")]
    crate::ollama::load_pace();
    dispatch(&root, cmd)
}

/// The `At` selector of a verb that carries one; `None` for verbs that don't.
fn at_of(cmd: &Cmd) -> Option<&Option<String>> {
    match cmd {
        Cmd::Debt { at, .. }
        | Cmd::Coverage { at, .. }
        | Cmd::Validate { at, .. }
        | Cmd::Graph { at, .. }
        | Cmd::Route { at, .. }
        | Cmd::Outcome { at, .. }
        | Cmd::Slice { at, .. }
        | Cmd::Review { at, .. }
        | Cmd::Plan { at, .. }
        | Cmd::Apply { at, .. }
        | Cmd::Land { at, .. } => Some(&at.at),
        _ => None,
    }
}

/// Make a `dir` that named ANOTHER repository absolute. The root is chosen by
/// walking up from that directory, so `arg_dir` would otherwise join the same
/// relative path onto a root that already ends in it.
///
/// Only then: inside the repository it was typed in, `[dir]` stays
/// ROOT-relative wherever the caller stands (`src/cli:V17`), so `seam code`
/// typed in `src/` is a miss that teaches `src/code`, never a hit that means
/// something else one directory over.
fn absolutize_dir(cmd: &mut Cmd, root: &Path, here: &Path) {
    if same_dir(&repo_root_from(here), root) {
        return;
    }
    let fix = |d: &mut String| {
        let p = here.join(&*d);
        if p.is_dir() {
            *d = p.to_string_lossy().into_owned();
        }
    };
    match cmd {
        Cmd::Init { dir, .. }
        | Cmd::Budget { dir, .. }
        | Cmd::Fed { dir }
        | Cmd::Check { dir, .. }
        | Cmd::Split { dir, .. }
        | Cmd::Seam { dir }
        | Cmd::Wave { dir, .. }
        | Cmd::Sync { dir, .. } => {
            if let Some(d) = dir {
                fix(d);
            }
        }
        Cmd::Lens { dir, .. }
        | Cmd::Adopt { dir, .. }
        | Cmd::Ask { dir, .. }
        | Cmd::Tdd { dir, .. }
        | Cmd::Oneshot { dir, .. } => fix(dir),
        _ => {}
    }
}

/// Whether two spellings name one directory (`src/cli:B17`): a root walked up
/// from `../src/code` is spelled `src/..`. Canonical only to COMPARE, since
/// `canonicalize` rewrites symlinks and neither path may travel on (`B9`).
fn same_dir(a: &Path, b: &Path) -> bool {
    match (a.canonicalize(), b.canonicalize()) {
        (Ok(x), Ok(y)) => x == y,
        _ => a == b,
    }
}

/// The `dir` a verb without an `At` selector was given, if any.
fn dir_of(cmd: &Cmd) -> Option<&str> {
    match cmd {
        Cmd::Init { dir, .. }
        | Cmd::Budget { dir, .. }
        | Cmd::Fed { dir }
        | Cmd::Check { dir, .. }
        | Cmd::Split { dir, .. }
        | Cmd::Seam { dir }
        | Cmd::Wave { dir, .. }
        | Cmd::Sync { dir, .. } => dir.as_deref(),
        Cmd::Lens { dir, .. }
        | Cmd::Adopt { dir, .. }
        | Cmd::Ask { dir, .. }
        | Cmd::Tdd { dir, .. }
        | Cmd::Oneshot { dir, .. } => Some(dir),
        _ => None,
    }
}

/// The repository root for an `At` selector: walk up from the named
/// directory, or from the CWD when none was given.
fn root_at(at: Option<&str>) -> Result<PathBuf, String> {
    let here = cwd();
    let Some(a) = at else {
        return Ok(repo_root_from(&here));
    };
    let p = here.join(a);
    if p.is_dir() {
        Ok(repo_root_from(&p))
    } else {
        Err(format!("`{a}` is not a directory"))
    }
}

/// Route one parsed verb. Split from [`run_args`] so the parse and the
/// routing each fit a screen.
fn dispatch(root: &Path, cmd: Cmd) -> ExitCode {
    match cmd {
        Cmd::Budget { dir, format } => budget_as(
            root,
            &arg_dir(dir.as_deref(), root),
            format.format.is_json(),
        ),
        Cmd::Debt { check, record, .. } => debt_cmd(
            root,
            ratchet(check, record).map(Ratchet::flag),
            &crate::land::cargo_bin(),
        ),
        Cmd::Coverage { check, record, .. } => coverage_in(
            root,
            ratchet(check, record).map(Ratchet::flag),
            &crate::land::cargo_bin(),
            &crate::debt::swift_bin(),
        ),
        // `.:B9` (the ROOT's, not this node's): this passed
        // `PathBuf::from(d)` while `budget` and `fed` went through
        // `arg_dir`, so it never got T10's root resolution and `lens .`
        // reported a different chain than `budget` for the same node.
        // Fixing a shared helper has to be followed by finding who does not
        // use it.
        Cmd::Lens { dir, depth } => {
            lens_cmd(root, &arg_dir(Some(&dir), root), depth.into())
        }
        Cmd::Fed { dir } => fed_cmd(&arg_dir(dir.as_deref(), root)),
        Cmd::Init { dir, stdout } => init_cmd(root, dir.as_deref(), stdout),
        Cmd::Graph {
            tree, table, dot, ..
        } => {
            let view = match (dot, table, tree) {
                (true, _, _) => GraphView::Dot,
                (_, true, _) => GraphView::Table,
                (_, _, true) => GraphView::Tree,
                _ => GraphView::Mermaid,
            };
            print!("{}", graph_render(root, view));
            ExitCode::SUCCESS
        }
        Cmd::Check { format, .. } => check_as(root, format.format.is_json()),
        Cmd::Validate { format, .. } if format.format.is_json() => {
            validate_json_cmd(root)
        }
        Cmd::Validate { .. } => validate(root),
        Cmd::Split { dir, apply } => split_cmd(
            root,
            &dir.map_or_else(|| root.to_path_buf(), |d| root.join(d)),
            apply,
        ),
        Cmd::Seam { dir } => seam_cmd(root, &arg_dir(dir.as_deref(), root)),
        Cmd::Wave { dir, format } if format.format.is_json() => {
            wave_json_cmd(root, &arg_dir(dir.as_deref(), root))
        }
        Cmd::Wave { dir, .. } => wave_cmd(root, &arg_dir(dir.as_deref(), root)),
        Cmd::Adopt { dir, map, check } => {
            adopt_cmd(root, &dir, map.as_deref(), check)
        }
        Cmd::Sync { dir, check } => {
            sync_cmd(root, dir.map(|d| root.join(d)).as_ref(), check)
        }
        Cmd::Route { query, .. } => route_cmd(root, &query),
        Cmd::Outcome { node, verdict, .. } => outcome_cmd(root, &node, verdict),
        Cmd::Slice { check, list, .. } => slice_cmd(
            root,
            match (check, list) {
                (true, _) => "--check",
                (_, true) => "--list",
                _ => "",
            },
        ),
        Cmd::Review { rev, .. } => {
            review_cmd(root, rev.as_deref().unwrap_or("HEAD"))
        }
        Cmd::Plan {
            format,
            triage,
            milestone,
            ..
        } => {
            let mode = match (triage, milestone) {
                (true, _) => PlanMode::Triage,
                (_, Some(m)) => PlanMode::Milestone(m),
                _ => PlanMode::Current,
            };
            plan_verb(root, format.format.is_json(), mode)
        }
        Cmd::Land { push, .. } => land_verb(root, push),
        Cmd::Completions { shell } => {
            clap_complete::generate(
                clap_complete::Shell::from(shell),
                &mut parse::command(),
                "sherd",
                &mut std::io::stdout(),
            );
            ExitCode::SUCCESS
        }
        Cmd::Man => match clap_mangen::Man::new(parse::command())
            .render(&mut std::io::stdout())
        {
            Ok(()) => ExitCode::SUCCESS,
            Err(e) => {
                eprintln!("sherd: man: {e}");
                ExitCode::from(1)
            }
        },
        model => model_verb(root, model),
    }
}

/// The ratchet mode a `--check` / `--record` pair selects.
#[derive(Clone, Copy)]
enum Ratchet {
    Check,
    Record,
}

impl Ratchet {
    /// The mode string the ratchet verbs read.
    const fn flag(self) -> &'static str {
        match self {
            Self::Check => "--check",
            Self::Record => "--record",
        }
    }
}

/// The grammar refuses `--check` with `--record`; neither is no mode.
fn ratchet(check: bool, record: bool) -> Option<Ratchet> {
    match (check, record) {
        (true, _) => Some(Ratchet::Check),
        (_, true) => Some(Ratchet::Record),
        _ => None,
    }
}

/// The `graph` rendering a flag picks; mermaid when none does.
#[derive(Clone, Copy)]
enum GraphView {
    Dot,
    Table,
    Tree,
    Mermaid,
}

fn graph_render(root: &Path, view: GraphView) -> String {
    match view {
        GraphView::Dot => fed::dot(root),
        GraphView::Table => fed::table(root),
        GraphView::Tree => fed::tree(root),
        GraphView::Mermaid => fed::mermaid(root),
    }
}

/// What `plan` is asked for; the grammar refuses `--triage` with `--milestone`.
enum PlanMode {
    Triage,
    Milestone(String),
    Current,
}

/// `outcome <node> <kept|reverted|failed>`, in the selected repository's
/// store (`SHERD_STATE` first, as everywhere else).
fn outcome_cmd(root: &Path, node: &str, verdict: Verdict) -> ExitCode {
    let store = crate::state::resolve(
        std::env::var("SHERD_STATE").ok(),
        crate::state::git_common_dir(root),
    );
    outcome_in(&store, node, verdict)
}

/// The store-taking core of `outcome_cmd`: a test brings its own store, as
/// `plan::record_outcome_in` does, so no test mutates the ambient state.
fn outcome_in(store: &Path, node: &str, verdict: Verdict) -> ExitCode {
    let mut st = crate::state::State::at(store);
    plan::record_outcome_in(&mut st, Path::new(node), verdict.is_kept());
    st.save();
    let (tried, k) = plan::record_in(&st, Path::new(node));
    eprintln!(
        "{node}: {k}/{tried} kept · believability {:.2}",
        plan::believability_in(&st, Path::new(node))
    );
    ExitCode::SUCCESS
}

/// `plan`, its `--triage` and `--milestone` forms.
fn plan_verb(root: &Path, json: bool, mode: PlanMode) -> ExitCode {
    match mode {
        PlanMode::Triage if json => {
            usage("plan --triage has no --format json yet")
        }
        PlanMode::Triage => triage_cmd(root),
        PlanMode::Milestone(m) if plan::milestone_declared(root, &m) => {
            plan_cmd(root, Some(&m), json)
        }
        PlanMode::Milestone(m) => usage(&format!(
            "no node declares milestone `{m}` -- a `| {m} |` row in some node's \u{a7}T"
        )),
        PlanMode::Current => plan_cmd(root, None, json),
    }
}

/// The verbs that need the `ollama` feature, or say so.
///
/// The model verbs exist in `USAGE` whatever this build carries, so a
/// consumer reading `--help` sees the whole tool. Without the feature they
/// are not "unknown" -- they are NOT COMPILED IN, and saying so is the
/// difference between a typo and a build choice.
#[cfg(not(feature = "ollama"))]
fn model_verb(_root: &Path, cmd: Cmd) -> ExitCode {
    let verb = match cmd {
        Cmd::Apply { .. } => "apply",
        Cmd::Ask { .. } => "ask",
        Cmd::Oneshot { .. } => "oneshot",
        _ => "tdd",
    };
    needs_ollama(verb)
}

#[cfg(feature = "ollama")]
fn model_verb(root: &Path, cmd: Cmd) -> ExitCode {
    match cmd {
        Cmd::Apply { land, push, .. } => match plan::apply(root, 3) {
            Ok(sha) => {
                eprintln!(
                    "\napplied as {sha}. Run `sherd plan` again before the next step -- \
                           this commit changed the specs that plan it."
                );
                // --land asks to land it now; the evidence still decides.
                if land {
                    land_verb(root, push)
                } else {
                    ExitCode::SUCCESS
                }
            }
            Err(e) => {
                eprintln!("sherd: {e}");
                ExitCode::from(1)
            }
        },
        Cmd::Ask { dir, question } => {
            ask(root, &arg_dir(Some(&dir), root), &question)
        }
        Cmd::Oneshot {
            dir,
            invariant,
            task,
        } => {
            let dir = arg_dir(Some(&dir), root);
            let run = crate::tdd::Run::new(root, &dir, &invariant, &task);
            match crate::tdd::oneshot(&run) {
                Ok(_) => ExitCode::SUCCESS,
                Err(e) => {
                    eprintln!("sherd: {e}");
                    ExitCode::from(1)
                }
            }
        }
        Cmd::Tdd {
            dir,
            invariant,
            task,
        } => tdd_cmd(root, &arg_dir(Some(&dir), root), &invariant, &task),
        _ => ExitCode::from(2),
    }
}

/// A verb this build does not carry, named as such.
///
/// Exit 2, the USAGE code: nothing is wrong with the repository or the
/// request, the binary simply was not built with it. `.:V117` freezes the
/// model half until `0.7`, and `default = []` means the published crate is
/// the deterministic core -- so this is the common path, not an edge.
#[cfg(not(feature = "ollama"))]
fn needs_ollama(verb: &str) -> ExitCode {
    eprintln!(
        "sherd: `{verb}` needs the `ollama` feature, which this build does not \
         carry. Install it with `cargo install sherd --features ollama`."
    );
    ExitCode::from(2)
}

/// `land`, shared by the verb and by `apply --land`.
///
/// Local by default. Pushing is the outward-facing act, and an unattended run
/// that pushes at 3am publishes unreviewed generated code; `--push` opts in.
/// The local branches are the record of every try -- git as the memory.
fn land_verb(root: &Path, push: bool) -> ExitCode {
    match crate::land::land(root, push) {
        Ok(msg) => {
            eprintln!("{msg}");
            ExitCode::SUCCESS
        }
        Err(e) => {
            eprintln!("sherd: not landing -- {e}");
            eprintln!(
                "     the branch is untouched; it is the record of the try"
            );
            ExitCode::from(1)
        }
    }
}

fn usage(msg: &str) -> ExitCode {
    eprintln!("sherd: {msg}\n\n{USAGE}");
    ExitCode::from(2)
}

#[cfg(test)]
#[path = "tests/fixtures.rs"]
mod fixtures;

#[cfg(test)]
#[path = "tests/dispatch.rs"]
mod tests;

#[cfg(test)]
#[path = "tests/routes.rs"]
mod routes;

#[cfg(test)]
#[path = "tests/unread.rs"]
pub(crate) mod unread;

#[cfg(test)]
#[path = "tests/verdicts.rs"]
mod verdicts;