commandmod

type CommandEvent struct {
	// Raw is the command line exactly as written, before any resolution.
	Raw string

	// Invocations is every invocation the line performs, flattened out of the
	// pipelines, chains, subshells and wrappers that nest them. Order is the
	// order they appear in the line, not the order they would run — a rule
	// asks what is about to run, not when.
	Invocations []Invocation
}

type Effect int

type FileTarget struct {
	// Path is the path as the command line names it, with quoting undone and
	// nothing else done to it. It is not resolved against a root or cleaned
	// here: this package knows what a command line says, and where the
	// repository sits is the file module's question.
	Path string

	// Effect is what is about to happen to it.
	Effect Effect

	// Payload is what the LINE determines about the resulting bytes, which for
	// most commands is nothing.
	//
	// The zero value is PayloadNone, so a target built without thinking about
	// content claims none — which is why every construction site in this
	// package could stay as it was and only the ones that genuinely know
	// something had to change.
	//
	// It is a statement about the line, not the outcome: `cp a.md b.md` yields
	// PayloadCopyOf naming a.md, and turning that into bytes is filemod's,
	// because it means reading the filesystem and this package does not. See
	// payload.go for the whole argument.
	Payload Payload

	// MTimeOnly marks a write that changes no bytes when the file already
	// exists — `touch`, and nothing else today.
	//
	// It exists because `touch` is the one command whose PAYLOAD depends on
	// something this package refuses to look at. Creating a file, it determines
	// an empty one; against a file already there it changes only the timestamp
	// and every byte survives. One line, two outcomes, chosen by the tree.
	//
	// So the line states both halves — the create payload in Payload, and this
	// flag saying "only if it is a create" — and filemod, which has already
	// stat'd the path, picks. Without it a caller applying the payload
	// uniformly would report `touch existing.md` as emptying the file, and a
	// guardrail refusing empty results would fire on a command that changes
	// nothing.
	MTimeOnly bool

	// Into are the sources copied INTO this path when it is a directory —
	// `cp a.md b.md target-dir/`, whose real results are target-dir/a.md and
	// target-dir/b.md.
	//
	// The second case, after MTimeOnly, where one line means different things
	// depending on the tree, and it is the same shape of answer. Whether the
	// last operand is a directory decides whether this line writes ONE file
	// (a two-operand copy onto a path) or SEVERAL (a copy into a directory),
	// and this package refuses to look. So it states both readings — Path with
	// its Payload for the file case, and this list for the directory case —
	// and filemod, which has already stat'd the path, picks.
	//
	// Empty for every other command, and empty for a two-operand copy, where
	// there is no directory reading to state: `cp a.md b.md` writes b.md
	// whether or not b.md exists, and the only way `b.md` is a directory is
	// the one this field covers.
	//
	// The resulting NAME is base(source), which is the utility's own rule and
	// is not a tree question. What is a tree question is whether the rule
	// applies at all, and that is exactly what is deferred.
	Into []string

	// Recursive marks a Remove that takes a DIRECTORY with it, everything
	// inside included — `rm -r`/`-R`/`--recursive`, and the source of an `mv`,
	// which moves a directory whole without asking for a flag.
	//
	// The third case of one line meaning different things depending on the
	// tree, after MTimeOnly and Into: `rm -rf scanners/x` removes one file if
	// scanners/x is a file and every file under it if it is a directory, and
	// only a stat can tell. So the line states that it WOULD reach inside, and
	// filemod, which stats, lists what is inside. Without it a directory
	// removal named no file at all, and a rule guarding a file was defeated by
	// deleting the folder it sits in.
	//
	// False for a plain `rm dir`, which fails on a directory and removes
	// nothing.
	Recursive bool

	// Grounded is the sr-file call that names this target, parsed — the one
	// program whose line carries citations for the file it changes (see
	// internal/grounding). Nil for every other program. It travels on the
	// target so its citations are keyed by the same path, resolved against the
	// same `cd`s, as the change itself.
	Grounded *grounding.FileCommand
}

type Invocation struct {
	// Bin is the program, as its basename — `npm`, not `/usr/local/bin/npm`.
	// A rule about npm should not have to enumerate the paths npm can live at,
	// and an agent should not be able to evade one by spelling the path out.
	Bin string

	// Argv is the resolved argument vector, program included. Resolved means
	// quoting and escaping are already undone: `n\pm` and `n""pm` both arrive
	// here as `npm`.
	Argv []string

	// Gaps are the positions in Argv where a word of the line was dropped
	// because it could not be resolved without running something or guessing
	// at an environment the line does not set (`$(pwd)/x`, `$UNSET`, `${X:-y}`):
	// i means a word stood immediately before Argv[i], len(Argv) that one
	// trailed the vector. Argv alone cannot tell a `-C $D` from a `-C` followed
	// by the next word; a consumer that must not judge the wrong thing (a gate
	// resolving a folder) reads this to fail closed. Nil when every word resolved.
	Gaps []int

	// Flags are the flags parsed out of Argv, keyed by name without its
	// leading dashes. Each value is every occurrence of that flag, in the
	// order given — a flag given once is a one-element slice, not a bare
	// string, so a repeated flag (`--cite:user a --cite:user b`) is not lost
	// to a last-wins collision the way a plain map would lose it. A flag
	// given without a value carries an empty string at that position, so a
	// rule can still ask whether a flag is present without knowing whether
	// that flag takes one.
	Flags map[string][]string

	// Cwd is the directory this program runs in, as far as the line itself
	// says — threaded through every `cd` ahead of it in its own scope (a
	// subshell's `cd` does not leak out of the subshell; see cwd.go):
	//
	//	"."          where the command line started — no `cd` moved it
	//	"sub/dir"    relative to where the line started (`cd sub/dir && …`)
	//	"/abs/dir"   absolute, once a `cd` named an absolute directory
	//	""           unknown — a `cd` this module cannot resolve without
	//	             running something (`cd "$DIR"`, `cd -`, `pushd`)
	//
	// Where the line started is the harness's working directory for the tool
	// call, which this pure function of a string does not have: a consumer
	// joins a relative Cwd onto it. Empty means unknown rather than "the
	// start", because a program whose directory was lost must not be read as
	// running where the line began — that is a guess, and a path resolved
	// against it could name a file the command never touches.
	Cwd string

	// Env is the environment the line itself sets for this program, NAME to
	// value: a prefix (`FOO=1 cmd`), a wrapper's assignments (`env FOO=1 cmd`,
	// `sudo FOO=1 cmd`), and an `export FOO=1` earlier in the same shell scope
	// (a subshell's export stays inside it). The value is "" when it is not a
	// literal word (`FOO=$X`, `FOO=$(cmd)`): the name is certain, the value is
	// not. Nil/empty when the line sets nothing. Only what the text says: the
	// environment the harness started with is not in it.
	Env map[string]string

	// Stdin is the text the line itself feeds this program: the body of a heredoc
	// (`<<EOF`, `<<'EOF'`, `<<-EOF`) or the word of a here-string (`<<<word`, newline
	// appended) attached to its command. Nil unless that text is literal: a pipe from
	// another command, a `< file`, a variable or substitution in an unquoted heredoc
	// body all leave it nil, because what the program reads is then not knowable.
	Stdin *string
}

type Module struct{}

type Payload struct {
	Kind PayloadKind

	// Text is the literal bytes, for PayloadLiteral and PayloadAppend. Exact,
	// including any trailing newline — see echoOutput, where the newline is the
	// difference between a correct fingerprint and a wrong one.
	Text string

	// From are the paths whose current contents become the result, IN ORDER, for
	// PayloadCopyOf. Spelled as the command line spells them, like
	// FileTarget.Path.
	//
	// One entry for a copy, several for a concatenation. The order is the
	// command's own — `cat b.md a.md > c.md` is not the same file as
	// `cat a.md b.md > c.md`, so a set would be the wrong shape here.
	From []string
}

type PayloadKind int

type Pending interface {
	// Tool is what the harness calls it. Read only to know how to read the
	// arguments — a rule never sees it.
	Tool() string
	// Arguments are the tool's own, as the harness gave them.
	Arguments() json.RawMessage
}

type ReadTarget struct {
	// Path is the path as the command line names it, quoting undone, exactly as
	// FileTarget.Path is — not resolved against a root or cleaned.
	Path string
}