mirror

type IdentityKind int

type IdentityRule struct {
	// Source 是待替换的源标识。
	Source string
	// Target 是替换后的目标标识。
	// 为空表示"剥离":删除源标识本身,而不是替换成占位符——
	// 占位符只是把内网痕迹换了个形式留在公开树里,反而更难发现。
	Target string
	// Kind 决定边界匹配语义,默认 KindModule。
	Kind IdentityKind
}

type Mapping struct {
	// Source 是 canonical module path,须与 RepoDir/go.mod 的 module 行一致。
	Source string
	// Target 是镜像 module path(如 github.com/org/repo)。
	Target string
}

type Options struct {
	// RepoDir 是 canonical 仓库的工作区路径(读取 go.mod、tag 与远端配置)。
	RepoDir string
	// Mapping 指定身份改写方向。
	Mapping Mapping
	// Tags 是要发布的 tag 列表,至少一个;每个 tag 独立生成孤儿快照,
	// 支持批量补历史版本。单个失败即中止,之前成功的保留。
	Tags []string
	// Remote 是 canonical 仓库中指向镜像仓库的远端名,默认 "github"。
	Remote string
	// Auth 是访问镜像远端用的凭据;零值(AuthNone)时 native 后端以
	// 本机 git 默认凭据(ssh-agent、credential helper)推送。
	Auth gitbackend.AuthConfig
	// ScrubRules 痕迹清理规则:发布前把内容里的内网痕迹清掉。
	//
	// **为什么镜像发布也需要它**:身份改写只管 **module path**,
	// 而内容里还有别���内网标识 —— 内网 registry 地址、部署代号、令牌。
	// 它们原样进**公开 module** 就是泄漏(历史同步侧早有这套规则)。
	//
	// 语义与历史同步侧**同一套原语**(mirror.ScrubRule):
	//   - auto:按 Replacement 替换(为空则删除命中内容);
	//   - mandatory:命中即**中止发布**(密钥类不进公开仓),不做自动替换。
	ScrubRules []ScrubRule
	// AllowOverwrite 允许覆盖镜像远端上 **tree 不一致**的同名 tag。
	// false 时检测到不一致直接报错,保护已发布版本不被误覆盖。
	//
	// ⚠️ **覆盖 = 同一个公开版本号出现两个不同的 h1**:
	// Go 的 checksum DB 对一个版本号只保留**首次**见到的 hash,
	// 之后任何拿到新 zip 的消费者都会得到 checksum mismatch,
	// 而且**无法通过重试自愈**(proxy 也会按版本永久缓存旧 zip)。
	// 这是「对外可见的公开 module」上最不可逆的一类破坏 ——
	// 所以它必须显式开启,且报告里必须打出「该版本号的 h1 将变化」。
	AllowOverwrite bool
	// AllowUnverifiedPush 远端不可达/认证失败时**盲推**(跳过一致性检查)。
	//
	// 与 AllowOverwrite 是两件事,必须分开授权:
	//   - AllowOverwrite:「我知道内容会变,确认覆盖」;
	//   - AllowUnverifiedPush:「我连不上远端,查不了状态,先推了再说」。
	//
	// 原实现里 AllowOverwrite 顺带允许了后者(文档没写),已拆开 ——
	// 一个开关同时管「覆盖」与「盲推」,等于把两个风险捆在一起授权。
	AllowUnverifiedPush bool
	// DryRun 为 true 时执行到远端一致性检查为止(校验、身份改写、门禁、
	// 远端比对),不合成 commit/tag、不推送;用于发布前预检。
	DryRun bool
}

type Report struct {
	Tags []TagReport
}

type Rewriter struct {
	// contains filtered or unexported fields
}

type ScrubHit struct {
	// Rule 命中的规则名。
	Rule string
	// Category 命中的类别。
	Category string
	// Line 行号(1 起)。
	Line int
	// Text 命中所在行(截断到 200 字节)。
	Text string
	// Mandatory 该命中是否强制人工处理(密钥类)。
	//
	// 必须区分:自动清理类的命中**已随内容一起发布**,
	// 强制人工类的命中意味着**这个文件没有被发布**。
	// 不区分的话,审计报告会把两者混为一谈。
	Mandatory bool
}

type ScrubResult struct {
	// Content 清理后的内容。
	Content []byte
	// Hits 全部命中项(含已清理与强制 hold 的)。
	Hits []ScrubHit
	// MandatoryHits 强制人工处理的命中项。
	MandatoryHits []ScrubHit
	// Cleaned 是否发生过自动清理。
	Cleaned bool
}

type ScrubRule struct {
	// Name 规则名,出现在计划的命中原因里。
	Name string
	// Category 类别分组(如 "internal-host" / "secret"),仅用于展示。
	Category string
	// Pattern 匹配模式。对**改写后**的内容生效。
	Pattern *regexp.Regexp
	// Severity 处理强度,默认 ScrubAuto。
	Severity ScrubSeverity
	// Replacement 命中后的替换文本。ScrubAuto 且为空表示**删除**命中内容。
	Replacement string
}

type ScrubSeverity string

type ScrubSummary struct {
	// ByRule 各规则命中数。
	ByRule map[string]int
	// Total 总命中数。
	Total int
	// Mandatory 强制人工处理的命中数。
	Mandatory int
}

type TagReport struct {
	Tag          string
	SourceCommit string
	Tree         string
	Commit       string
	// ReplacedFiles 是**内容真的被身份改写**的文件(仓库内相对路径)。
	ReplacedFiles []string
	// ResidualFiles 是**仍带着内网标识**的文件:规则本该改写,却因为
	// 二进制/超限而原样保留。非空即意味着本次发布被中止(未推送)。
	ResidualFiles []string
	// VerifyCmd 是发布后建议执行的验证命令。
	VerifyCmd string

	// RemoteTagExisted 表示推送前镜像远端已存在同名 tag。
	RemoteTagExisted bool
	// TreeMatchedRemote 表示远端已有 tag 的 tree 与本次合成结果一致
	// (重跑幂等的直接证据);仅在 RemoteTagExisted 且成功比对时有意义。
	TreeMatchedRemote bool
	// OverwroteDivergent 表示在 tree 不一致且 AllowOverwrite 下完成了覆盖。
	OverwroteDivergent bool
	// ScrubHits 本次发布清理掉的痕迹命中(逐条带规则名与行号)。
	//
	// 密钥类(mandatory)的命中**不回显原文**,只标记位置。
	ScrubHits []ScrubHit
	// TagAlreadyPublished 表示远端已有**同内容**的同名 tag,本次未重推。
	//
	// 幂等重跑不该改写对外可见的 tag 对象:tag 的 hash 变了,
	// 已经 pin 了 pseudo-version(形如 v0.0.0-<时间>-<commit12>)的消费者
	// 就拉不到那个版本了。内容一致时**什么都不动**才是真幂等。
	TagAlreadyPublished bool
	// H1WillChange 表示本次发布**改写了已发布版本的内容**:
	// 同一个公开版本号将出现两个不同的 h1,已发布过该版本的消费者
	// 会 checksum mismatch 且无法自愈。
	//
	// 报告里必须显式带出这一条 —— 覆盖是唯一会造成这种不可逆后果的动作。
	H1WillChange bool
	// Warning 面向人的提醒(覆盖/盲推这类「用户可能没意识到的后果」)。
	Warning string
}