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
//! Argv RESOLUTION -- which repo, which dir, which depth a command acts on (V5, V15, V17).
use *;
/// The repo root, not the invocation directory.
///
/// `sherd` is a shim over `cargo run`, so CWD is wherever you typed it. Using
/// CWD federated from a SUBDIRECTORY silently -- fewer nodes, a truncated
/// chain, and no error to say so. Walk up to the git root instead.
/// The repo root a run is ABOUT, which is not always the one it was launched
/// from.
///
/// Every `[dir]` verb takes a path that may live in ANOTHER repository, and
/// resolving the root from the CWD then silently answers about the wrong
/// tree: `sherd check ../their-project` reported this crate's own nodes and
/// exited 0 (`src/cli:B5`). When the first argument names an existing directory, the
/// root is the one ABOVE IT.
///
/// Any argument may be the directory, not just the first: `plan --triage
/// <dir>` put a FLAG at position one, so a scan of `args[1]` alone found no
/// dir and answered about the CWD -- the same bug one flag to the left, and
/// the fix for it was incomplete until a stranger showed the flag-first form
/// (`B7`).
///
/// A run with no directory argument at all -- `HEAD` for `review`, `--check`
/// alone for `sync` -- leaves the CWD walk alone, and an in-repo path
/// resolves to the same root it always did.
///
/// And the directory it names is made ABSOLUTE before the walk. A relative
/// one was handed over as typed, and `parent()` climbs a relative path to
/// `""`, which holds no `.git`: the walk ran out of parents and returned its
/// own START -- the argument -- as the "root", after which `arg_dir` joined
/// that argument on a second time. `sherd seam code` from `src/` reported
/// `code/code matched no node`, and the doubling is the proof (`src/cli:B9`,
/// which is NOT the root's `B9`).
pub
/// As [`root_for`], from an explicit invocation directory (`V6`).
///
/// Split for the reason [`repo_root_from`] is: a test can be HANDED the
/// directory a command was typed in, rather than mutating the process CWD --
/// which is global, and races every other test in the binary.
///
/// The candidate is resolved against `cwd` BEFORE anything reads it, so the
/// scan and the walk agree about what the path means. `join` is LEXICAL and
/// total: an absolute argument is left alone, there is no I/O to fail, and
/// the spelling the caller passed survives. `canonicalize` would also
/// collapse `..`, but it rewrites symlinks -- macOS hands out
/// `/var/folders/...` and resolves it to `/private/var/...` -- so the root
/// would stop comparing equal to the path it was given.
pub
/// The directory the command was typed in, or `.` when it cannot be read.
pub
/// The root from the CWD, for tests that assert about THIS checkout.
///
/// Dispatch reaches the walk through [`root_for_from`], which is HANDED its
/// directory, so this is a test convenience and is compiled as one -- left in
/// the shipping build it is dead code, which the gate denies.
pub
/// The walk, given a starting directory (V6).
///
/// Split from `repo_root` so a test can be HANDED a tree instead of
/// discovering one. `B1` is what the unsplit version cost: the test asserted
/// that `repo_root()` finds a `.git` and a `SPEC.md`, which it always does
/// when the runner sits in this checkout and never does anywhere else -- so
/// the suite passed here and failed in a tarball, and the assertion was
/// about the runner's location rather than about the walk.
pub
/// The `[dir]` argument, resolved AGAINST ROOT.
///
/// It used to be handed back verbatim, so `src/tdd` stayed relative while
/// `fed::discover` returns absolute paths -- the two never compared equal.
/// `sherd fed` survived that only because the CWD happens to be the repo root;
/// from a subdirectory it read the wrong `SPEC.md` or none.
///
/// `join` leaves an absolute argument alone, so passing a full path still
/// works.
pub
/// A `[dir]` that matched no node, said in full (V2, V18).
///
/// The path is named absolute, because that is what was looked for. What the
/// old message left out is WHY it was looked for there: `arg_dir` resolves
/// `[dir]` against the repo root, so `seam code` typed in `src/` is a miss
/// even though `src/code` is right there. The contract stays -- an argument
/// that means a different node depending on where the caller stands is the
/// ambiguity `B5` and `B7` were about -- and the miss now teaches the
/// spelling that works instead of ending the conversation.
pub