bash

type Assignment struct {
	Name  string // 变量名
	Value string // 变量值(原始文本,含引号)
}

type CommandInfo struct {
	Name         string             // 命令名(已跳过 env/sudo 等前缀)
	Args         []string           // 参数列表
	Assignments  []*Assignment      // 环境变量前缀赋值
	Redirections []*RedirectionInfo // 重定向列表
	// Position is the sequential position within the current shell context.
	// Semantics verified against extract.go: NodeSubshell starts a fresh
	// context and resets Position to 0; NodeList / NodePipeline accumulate
	// outer ctx.position + inner index (so a command inside a nested list
	// sees outer parent position plus its own index). Position is NOT a
	// global absolute index across the whole command string — use it to
	// locate commands within a single shell level, not to uniquely
	// identify a command in nested structures.
	//
	// Position 是当前 shell context 内的顺序位置. 语义按 extract.go 核实:
	// NodeSubshell 开启新 context, Position 从 0 重算; NodeList /
	// NodePipeline 内累加外层 ctx.position + 内部索引 (嵌套 list 里的
	// 命令看到的是外层父位置 + 自己索引). Position 不是跨整条命令串的
	// 全局绝对索引 — 用于在同一 shell 层级内定位命令, 不能唯一标识嵌套
	// 结构中的某条命令.
	Position int

	// Operator is the bash connector preceding this command (&& / || / | / ;).
	// The first command in a list / pipeline (i == 0) inherits the parent
	// ctx.operator; an outermost command has "" (no preceding operator).
	// Consumers: "" means "starting position with no prior connector";
	// non-empty is one of &&, ||, |, ;.
	//
	// Operator 是命令前面的连接符 (&& / || / | / ;). list / pipeline 内第一个
	// 命令 (i == 0) 从父 ctx.operator 继承, 最外层命令为 "" (无前序操作符).
	// 消费者: "" 表示"起始位置, 无前序连接符"; 非空为 &&, ||, |, ; 之一.
	Operator string

	// InSubshell is true iff the command is enclosed in a NodeSubshell.
	// Remains true inside nested subshells.
	//
	// InSubshell 在命令被 NodeSubshell 包裹时为 true. 嵌套 subshell 内仍为 true.
	InSubshell bool

	// InPipeline is true iff the command is a stage of a NodePipeline.
	// **Always check this before reading PipePosition** — non-pipe commands
	// have PipePosition == 0 (zero-value default), which collides with the
	// "first pipeline stage" value. InPipeline is the only reliable
	// discriminator.
	//
	// InPipeline 在命令为 NodePipeline 阶段时为 true. **读 PipePosition 前
	// 必须先查 InPipeline** — 非管道命令 PipePosition == 0 (零值), 和"管道
	// 第一阶段"的值冲突; InPipeline 是唯一可靠的区分.
	InPipeline bool

	// PipePosition is the stage index within a pipeline (0 = first stage).
	// For non-pipe commands this field defaults to 0 which carries no
	// meaning — always gate reads behind InPipeline.
	//
	// PipePosition 是管道内阶段位置 (0 = 第一阶段). 非管道命令时字段默认 0,
	// 无实际含义 — 读取前先检查 InPipeline.
	PipePosition int
	Background   bool   // 位于 `&` 左侧, 后台执行. EN: left of an `&` connector, backgrounded.
	RawText      string // 命令的原始文本

	// ArgQuoted is a parallel slice to Args (len(ArgQuoted) == len(Args))
	// recording per-arg quoting regime at parse time. true means the arg
	// was a fully-literal QuotedString (single quotes '...' or ANSI-C
	// $'...') whose body undergoes no parameter / command substitution.
	// false means the arg was either unquoted or double-quoted "...",
	// where $VAR / $(cmd) expand at runtime. Mirrors the heredoc Quoted
	// contract on RedirectionInfo so arg-level security analysis can
	// distinguish "inert literal" args from "possibly expanded" args --
	// a quoted `'$HOME/.ssh'` arg is *not* the same runtime target as
	// an unquoted `$HOME/.ssh`, and downstream consumers (permission
	// layer danger attribution) need the regime to render faithful
	// reasons without re-parsing the original source.
	//
	// ArgQuoted 是与 Args 平行的 slice (len(ArgQuoted) == len(Args)),
	// 记录每个 arg 在 parse 时的引号语义. true 表示该 arg 是完全字面
	// QuotedString (单引号 '...' 或 ANSI-C $'...'), body 不做参数 /
	// 命令替换. false 表示 arg 未加引号或在双引号 "..." 内, $VAR /
	// $(cmd) 会在运行时展开. 与 RedirectionInfo 上 heredoc 的 Quoted
	// 契约镜像, 让 arg 级安全分析区分 "inert literal" 与 "可能展开"
	// -- `'$HOME/.ssh'` (quoted) 与 `$HOME/.ssh` (unquoted) 运行时
	// 不是同一目标, 下游 (permission 层危险归因) 需要这个 regime 才
	// 能给出忠实原因, 不必回到源文本二次解析.
	ArgQuoted []bool
}

type HeredocInfo struct {
	Tag       string // 分隔符标签(去除引号后)
	Body      string // heredoc 内容
	BodyStart int    // Body 在原文中的起始字节位置. EN: byte offset of Body start within the ORIGINAL source string.
	BodyEnd   int    // Body 在原文中的结束字节位置 (半开区间). EN: byte offset of Body end (exclusive) within the ORIGINAL source string.
}

type Node struct {
	Type     NodeType // 节点类型
	Value    string   // 节点的原始文本(或解析后的值)
	Children []*Node  // 子节点列表
	Start    int      // 在源文本中的字节起始位置
	End      int      // 字节结束位置(不含)

	// Operator: List 节点的操作符(&&, ||, ;, &)
	Operator string

	// RedirectOp: Redirection/Heredoc 节点的操作符(>, >>, <, <<, 2>&1 等)
	RedirectOp string

	// RedirectTarget: 重定向目标文件名/fd
	RedirectTarget string

	// Quoted: QuotedString 节点 - true 表示单引号(阻止变量展开)
	Quoted bool

	// HeredocTag: Heredoc 节点的分隔符标签
	HeredocTag string

	// HeredocStripTabs: Heredoc <<- 变体,去除行首 tab
	HeredocStripTabs bool

	// HeredocQuoted: Heredoc 分隔符被引号包裹(阻止变量展开)
	HeredocQuoted bool

	// HeredocBody: Heredoc 的内容体
	HeredocBody string

	// HeredocBodyStart / HeredocBodyEnd: Heredoc body 在原文中的字节
	// 半开区间 [start, end). 用于审计 / 安全消费者把危险 heredoc 定位
	// 回用户输入的精确位置. 不变量: source[Start:End] 等于 HeredocBody
	// (闭合 heredoc 末尾有合成 '\n', 未闭合没有).
	//
	// HeredocBodyStart / HeredocBodyEnd: byte offsets of the heredoc
	// body within the original source, as a half-open interval
	// [Start, End). Lets audit / security consumers pinpoint a dangerous
	// heredoc back to the user's raw input. Invariant:
	// source[Start:End] == HeredocBody (closed heredocs append a
	// synthetic trailing '\n', unterminated ones do not).
	HeredocBodyStart int
	HeredocBodyEnd   int

	// Assignments: SimpleCommand 节点的环境变量赋值前缀(VAR=value cmd args)
	Assignments []*Assignment

	// Background: List 节点 - true 表示 & 后台执行
	Background bool
}

type NodeType int

type RedirectionInfo struct {
	Operator string // 操作符:>, >>, <, <<, 2>&1 等
	Target   string // 目标文件/fd
	IsStatic bool   // 目标是否静态(无变量展开)

	HeredocTag       string // Heredoc 分隔符标签 (仅 Operator 以 "<<" 开头时填值). EN: heredoc delimiter tag, populated only for "<<*" operators.
	HeredocStripTabs bool   // <<- 变体, 去行首 tab. EN: <<- variant, strip leading tabs from body.
	HeredocQuoted    bool   // 分隔符被引号包裹, body 不展开变量. EN: delimiter was quoted; body does NOT expand variables / command substitutions.
	HeredocBody      string // Heredoc 原始 body. EN: raw heredoc body text.

	// HeredocBodyStart / HeredocBodyEnd: Heredoc body 在**原文**的字节
	// 半开区间, 仅 Operator 以 "<<" 开头且成功匹配到 body 时非零. 让
	// AnalyzeDanger 等安全消费者把危险 heredoc 定位回用户源码位置,
	// DangerInfo 可 surface "source bytes N-M" 给运维 / TUI / 审计.
	//
	// HeredocBodyStart / HeredocBodyEnd: byte offsets of the heredoc
	// body within the ORIGINAL source (half-open interval). Populated
	// only for "<<*" operators with a matched body. Lets security
	// consumers (AnalyzeDanger) point DangerInfo back to concrete
	// "source bytes N-M" for operators / TUI / audit.
	HeredocBodyStart int
	HeredocBodyEnd   int
}