archcheck

type DependencyDirection struct {
	Enabled    *bool    `yaml:"enabled"` // 指针：缺省即启用，只有显式 false 才关
	Severity   string   `yaml:"severity"`
	Desc       string   `yaml:"desc"`
	IgnoreDirs []string `yaml:"ignore_dirs"`

	// ExtPrefixes 是**受管外部包面**清单：这些 import 路径前缀下的外部包，
	// 全部纳入本门禁的判定面。
	//
	// 为什么要有这一层（policy 级），而不能只靠各模块 requires 里写的 ext: 条目：
	// 若「哪些外部包受管」本身也只由各模块自己声明，那么**最后一个声明它的模块
	// 一旦撤掉声明，整片包面就随之消失**——那些 import 重新变成不判定的。
	// 而外部包没有「未登记目录」那道兜底（它是别的仓的包，本仓没有它的目录），
	// 于是这条边就静默失管了：门禁变绿，而不是变红。
	//
	// 这一层与内部模块的结构同构：
	//   - 受管面：modules 段（内部）/ ext_prefixes（外部）
	//   - 逐模块的边：requires
	ExtPrefixes []string `yaml:"ext_prefixes"`
}

type EgressEntry struct {
	// Path 启动点所在文件（相对仓根，正斜杠）。
	Path string `yaml:"path"`
	// Fn 含启动调用的函数名（空 = 该文件内全部启动点）。
	Fn string `yaml:"fn"`
	// Mode 该启动点的出口档位：unrestricted / proxy / denied（缺省 unrestricted，
	// 但**仍须显式登记**——「没登记」不等于「不要求」）。
	Mode string `yaml:"mode"`
	// Plumbing 兑现证据的函数名（缺省 Env / Verify）——「这一档落成 env」那一半。
	Plumbing []string `yaml:"plumbing"`
	// Capability 能力问询证据的函数名（缺省 SatisfiedBy）——「这一档有人强制」那一半。
	//
	// 两半分开可配而不是并成一个列表：它们是**两条**判据，报错要说清缺哪一半
	// （加 Env 与加后端是两种完全不同的修法）。
	Capability []string `yaml:"capability"`
	// Notes 为什么是这个档（写给人看的那一句）。
	Notes string `yaml:"notes"`
}

type EgressPaths struct {
	Enabled    *bool         `yaml:"enabled"`
	Severity   string        `yaml:"severity"`
	Desc       string        `yaml:"desc"`
	IgnoreDirs []string      `yaml:"ignore_dirs"`
	Entries    []EgressEntry `yaml:"entries"`
}

type Exception struct {
	Rule      string `yaml:"rule"`
	Path      string `yaml:"path"`
	Line      int    `yaml:"line"`
	Violation string `yaml:"violation"`
	Reason    string `yaml:"reason"`
	Until     string `yaml:"until"`
	Removal   string `yaml:"removal"`
}

type ExecutionEntry struct {
	// PackageName 入口所在包的**包名**（import 路径的最后一段，如 `ptc`）。
	PackageName string `yaml:"package_name"`
	// Symbol 入口的符号名（包级函数）。
	Symbol string `yaml:"symbol"`
	// ImportPath 可选：填了则 import 路径必须**逐字相等**（更精确）。
	ImportPath string `yaml:"import_path"`
	// Notes 该入口为什么是裸的（写给人看的那一句）。
	Notes string `yaml:"notes"`
}

type ExecutionPaths struct {
	Enabled    *bool            `yaml:"enabled"`
	Severity   string           `yaml:"severity"`
	Desc       string           `yaml:"desc"`
	IgnoreDirs []string         `yaml:"ignore_dirs"`
	RawEntries []ExecutionEntry `yaml:"raw_entries"`
}

type FacadeRule struct {
	Package        string   `yaml:"package"`
	Desc           string   `yaml:"desc"`
	Severity       string   `yaml:"severity"`
	Upstream       []string `yaml:"upstream"`        // 允许作为转发目标的 import 路径
	AllowedImports []string `yaml:"allowed_imports"` // 签名所需的额外 import（不含 upstream）
}

type Module struct {
	ID       string   `yaml:"id"`
	Roots    []string `yaml:"roots"`
	Requires []string `yaml:"requires"`
	Owner    string   `yaml:"owner"`
	Managed  bool     `yaml:"managed"`
	Notes    string   `yaml:"notes"`
}

type NegFollow struct {
	Anchor       string `yaml:"anchor"`
	ForbidFollow string `yaml:"forbid_follow"`
}

type Policy struct {
	Version    int                 `yaml:"version"`
	Modules    []Module            `yaml:"modules"`
	Rules      []Rule              `yaml:"rules"`
	Facades    []FacadeRule        `yaml:"facades"`
	DepDir     DependencyDirection `yaml:"dependency_direction"`
	Thresholds Threshold           `yaml:"thresholds"`
	Exceptions []Exception         `yaml:"exceptions"`

	// SandboxProviders 是执行沙箱后端的档位登记段（声明面）。
	//
	// 指针而非值：段整体缺省时，**门禁仍然开启**——因为「本仓有后端实现却没登记」
	// 必须报出来，而不是「没登记就当没这回事」。指针只用于区分「段不存在」与
	// 「段存在但为空」，两者的判定结果相同（都要靠代码事实说话）。
	SandboxProviders *SandboxProviders `yaml:"sandbox_providers"`

	// ExecutionPaths 是执行路径门禁的声明面（裸执行入口清单）。
	//
	// 段缺省即启用——「执行必须经登记簿」是**默认要求**，
	// 不是「登记了才管」。没登记的裸入口不会被这条门禁抓到（判据面有限，
	// 见 execution.go 的「判不了什么」），但默认开着总比默认关着好。
	ExecutionPaths *ExecutionPaths `yaml:"execution_paths"`

	// EgressPaths 是子进程出口门禁的声明面（逐个启动点登记出口档位）。
	//
	// 段缺省即启用：「子进程在不在出口强制面内」这个问题必须有人问，
	// 而不是「宿主登记了才问」——不登记就没人问，正是这条门禁要防的静默失效。
	EgressPaths *EgressPaths `yaml:"egress_paths"`

	// RequireRuleExamples 要求每条**有执行体**的规则都自带 examples。
	//
	// 默认 false：宿主仓不必为了升级判据而先给全部规则补样例（那会让一次
	// 依赖升级变成一次策略改写）。本仓自己开 true——口径是「本仓的每条规则
	// 都必须能被加载期验活」，而这条口径若只写在注释里就是散文，不是门禁。
	RequireRuleExamples bool `yaml:"require_rule_examples"`

	// Path 记录 policy 文件路径。自校验违规要指向它，而宿主仓的 policy
	// 不一定叫 architecture-policy.yaml——写死文件名等于让复用方永远看到
	// 一个指向不存在文件的报错位置。
	Path string `yaml:"-"`
}

type ReportOptions struct {
	// Full 为真时输出全部违反，否则每条规则截断到 10 条。
	Full bool
}

type Result struct {
	// Violations 是全部违反（含警告级与已命中例外的）。
	Violations []Violation
	// Blocking 是阻断级违反数，Warnings 是警告级数。
	Blocking int
	Warnings int
	// Excused 是命中已登记例外（且未到期）的违反数。
	Excused int
	// ExpiredExceptions 是已到期的例外——它们不再豁免任何东西。
	ExpiredExceptions []string
	// ThresholdFindings 是结构阈值（超长文件 / god object）的发现。
	ThresholdFindings []string
	// ThresholdEnforced 报告阈值是否阻断。
	ThresholdEnforced bool
	// Rules 是报告顺序下的规则清单。
	Rules []RuleInfo
	// Exceptions 是 policy 登记的例外清单（回显用，让债是显式的）。
	Exceptions []Exception
	// contains filtered or unexported fields
}

type Rule struct {
	ID           string      `yaml:"id"`
	Desc         string      `yaml:"desc"`
	Severity     string      `yaml:"severity"` // error（默认，违反即非零退出）| warn（报告口径，不阻断）
	Scope        []string    `yaml:"scope"`
	ScopeExclude []string    `yaml:"scope_exclude"`
	Include      []string    `yaml:"include"`
	IgnoreTest   bool        `yaml:"ignore_test"`
	OnlyTest     bool        `yaml:"only_test"` // 只扫测试文件（配合 severity: warn 做夹具体检）
	ForbidImport string      `yaml:"forbid_import_regex"`
	ForbidRegex  string      `yaml:"forbid_regex"`
	NegFollow    []NegFollow `yaml:"negative_follow"`
	// ImportExempt import 路径级的**精确**例外（issue #15）。
	//
	// 存在的原因：只有 `forbid_import_regex`（正则禁令）时，宿主若要放行
	// 被禁依赖树里的**某个具体子包**，只有三条路：
	//   1. 放宽整条正则 ⇒ 把整棵树的其余部分一起放行；
	//   2. 改成逐包白名单 ⇒ 上游将来新增一个包就**静默放行**
	//      （一条被静默放宽的声明等于没有声明）；
	//   3. 绕开 —— 在宿主侧自写一层转译。
	//
	// 第 3 条可行，但代价是同一个上游能力要在宿主侧再写一遍转译
	// （类型不许外泄、等价性自己核）——而这层转译本可以由上游的一个
	// import 例外免掉。
	//
	// 粒度必须是**精确 import 路径**（不是正则前缀——后者等于放宽整棵树）。
	// 未登记的包**仍然被拒** ⇒ 上游新增包不会静默放行。
	ImportExempt []string `yaml:"import_exempt"`

	// Examples 规则自带的样例：**加载期**就判「这条规则还活着吗」。
	//
	// 与 tests 的分工：测试证明「今天这条规则能判」，examples 证明「这次加载
	// 这条规则确实判得动」——前者在 CI 里跑一次，后者在**每一次**门禁运行、
	// 每一个复用本判据的宿主仓里跑。规则会随包名/命令名/词表漂移，而漂移
	// 不会报错：它只是静静地不再命中，门禁继续绿着。
	//
	// 判据复用**真实判定核**（regexViolationsIn / importViolationsIn，与文件遍历
	// 调的是同一份代码），不是另写一套近似实现——另写一套的话，样例过了也说明不了
	// 真判定能过（两套实现各自漂移，而样例那套只看几个字符串、漂得更慢）。
	Examples []RuleExample `yaml:"examples"`
}

type RuleExample struct {
	// Text 样例（源码行或 import 路径）。
	Text string `yaml:"text"`
	// Want 期望：hit = 必须被判违规；miss = 必须不被判违规。
	Want string `yaml:"want"`
}

type RuleInfo struct {
	ID       string
	Desc     string
	Severity string
}

type SandboxProvider struct {
	ID      string `yaml:"id"`
	Level   string `yaml:"level"`
	Package string `yaml:"package"`
	// Supports 登记该后端能兑现哪些预算项。
	//
	// 取值是上游 `guardx/sandbox` 的预算项名：wall_clock / max_calls /
	// max_bytes / max_memory。缺省（未填）= 只兑现基本三闸——
	// 与上游「不实现 Capable 的后端只兑现三闸、不兑现内存」的缺省语义一致。
	//
	// 为什么登记这一维：档位（Level）答的是「能力面多强」，预算支持面答的是
	// 「资源兜底兑现哪几项」。两者**正交**——进程内解释器的能力面与
	// LevelProcess 同级，却兜不住内存。少了这一维，「要求了内存兜底而后端
	// 兜不住」这件事在声明面是隐形的，宿主只能在运行期才发现。
	//
	// 门禁核对的是「登记与代码事实一致」：后端**没有** `Supports` 方法 ⇒ 只能
	// 登记基本三闸；后端**有** `Supports` 方法 ⇒ 可以登记含 max_memory。
	// 判据同样走 `go/ast` 的方法指纹（门禁不能 import 被判的包）。
	Supports []string `yaml:"supports"`
	Notes    string   `yaml:"notes"`
}

type SandboxProviders struct {
	Enabled    *bool             `yaml:"enabled"`
	Severity   string            `yaml:"severity"`
	Desc       string            `yaml:"desc"`
	IgnoreDirs []string          `yaml:"ignore_dirs"`
	Providers  []SandboxProvider `yaml:"providers"`
}

type Threshold struct {
	MaxFileLines      int `yaml:"max_file_lines"`
	MaxMethodsPerType int `yaml:"max_methods_per_type"`
	// ForwardingShellMaxChars 是「转发壳」的方法体长度上限（字符）。nil = 用缺省值。
	//
	// 转发壳 = 方法体只有一条转发语句、且剥掉注释与空白后长度不超过此值。
	// god object 阈值比的是**实质方法数**（方法数 − 转发壳数），因为方法总数在
	// façade 上等于**公共 API 表面规模**，不是复杂度集中度（issue #13）。
	//
	// 显式写 0 = 关闭该区分（所有方法都算实质方法），判定逐字退回旧行为。
	ForwardingShellMaxChars *int     `yaml:"forwarding_shell_max_chars"`
	ScanRoots               []string `yaml:"scan_roots"`
	Enforce                 bool     `yaml:"enforce"` // true=超限即非零退出；false=仅报告
}

type Violation struct {
	Rule string // 规则 ID
	Path string // 相对仓库根的路径
	Line int    // 行号（0 表示不指向具体行）
	Text string // 人类可读说明
	Kind string // 违规形态（同一规则下的细分类别）
}