archcheck

package
v0.48.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package archcheck 是 architecture-policy.yaml 的**可执行面**。

生命周期: Experimental(v0.33.0 定级)——本包仍会改、删、拆,不承诺任何 兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。

为什么它是一个可导入的包,而不是一个放在 cmd/ 下的脚本

存在意义:policy 文件若只当文档读,半年后就与代码事实脱节;把它做成门禁, 规则违反即非零退出。但门禁执行体若锁在 package main 里,别的仓就**用不上**—— 于是每个宿主仓要么各写一遍判据(各判一套,漂移到没人发现为止),要么干脆不写 (policy 的依赖拓扑表变成死条文:躺在文件里、看起来有人维护过,实际一条都不判)。

所以这一层被下沉成包:宿主仓 import 它、喂自己的 policy、拿自己的判定结果, 不复制一行实现。

判据与实现分离

判据是**声明**(policy 文件)+ **执行体**(本包),两者分开:

  • 声明面:modules 段的依赖拓扑、rules 段的正则、facades 段的门面包清单
  • 执行面:本包的 AST 判定(go/ast 判 import、判函数体、判依赖方向)

结构性判定一律走 go/ast,不走逐行正则——import 声明有六种以上书写形态 (单行 / 块 / 别名 / 空白导入 / 点导入 / 括号同行),逐行正则必然漏, 且漏得毫无声响。

门禁的失败形态是「变绿」,不是「变红」

判据写错时最危险的不是报错,而是**什么都不判**却照样报「无阻断级违反」。 故本包把「给不出结论」与「没违规」严格分开:解析失败、policy 自相矛盾、 规则没有执行体——一律响亮失败(返回 error 或报成违反),绝不静默降级。

复用方须知

  1. policy 的 modules 段要求每个 root 指向**真实存在**的包目录:陈旧的 root 会被判成违反(「陈旧包根当天即红」),因为它让该模块对门禁隐形。
  2. 跨仓依赖用 `ext:<import 路径前缀>` 表达,如 `ext:github.com/yi-nology/goagent-kernel/netguard`。
  3. 报告用 WriteReport;是否阻断用 Result.HasBlocking。

调用面禁令与路径白名单怎么表达

policy **没有** `forbid_call_regex` / `allow_paths` 字段——判据面只有两种: **import 路径**(`forbid_import_regex`)与**源码文本**(`forbid_regex`)。 常见的两种诉求用现有字段就能表达:

| 诉求 | 表达方式 |
|---|---|
| 「某个第三方包只允许经某一个适配层引入」(路径白名单)| `forbid_import_regex` + `scope_exclude: [适配层目录]` |
| 「某目录禁止裸 fetch(,但 api 客户端目录与两个 SSE 钩子除外」(调用面禁令 + 路径白名单)| `forbid_regex`(匹配调用形态)+ `scope_exclude`(豁免目录)|

为什么不再加第三种判据面:每多一种判据面,policy 作者就要多记一套豁免语义 (负向前置的锚点写在哪、目录豁免算不算……)。本包已经因为「同一字段在两个分支 语义不同」吃过一次亏(import 分支不认 `negative_follow`,静默假红),那次的 修法是**让两个分支同构**,而不是再加一种。

builtinrules.go —— 内置规则 id 清单(policy 的 rules 段之外的那些),以及 「这条规则当前是否真的在判」的判定。

为什么需要这张清单

例外登记按「rule + path + line」精确豁免某条规则的某处违反。要登记一条例外, 先得知道那条规则的 id 存在——而**恒开规则的 id 不在 policy 的 rules 段里**: 它们要么由本执行体自己实现(未受管逃逸门禁、门包门禁、自校验),要么由 policy 的**段**驱动(execution_paths / sandbox_providers / egress_paths / dependency_direction)。

旧实现只把 rules 段的 id 收进「已见规则」集合,于是宿主照着本执行体给的指引 (未受管逃逸门禁的违规文案原文:「确需逃逸时在 policy 的 exceptions 里显式 登记豁免与拆除条件」)去登记时,自校验反而报它「指向不存在的规则」 ——**照着指引做就红**。

而恒开门禁恰恰是最需要豁免的那几条:PTC 的未受管逃逸门禁管的是「宿主显式声明 本层工具另有一套管控」这件事,宿主要**合法**表达这件事就只能登记例外。 指引说可以、机制不让——这是门禁自己的缺陷,不是宿主的写法问题。

实测(v0.32.0):宿主按指引登记 PTC 逃逸口的例外 ⇒

  • 逃逸违规本身没被豁免;
  • 自校验报「例外登记指向不存在的规则 "harness-ptc-unmanaged-escape"」⇒ 门禁红。

为什么「存在」与「在判」要分开

存在 ≠ 在判:门包门禁只在 policy 写了 facades 段时才有判定面;四段驱动的门禁 都可以被显式关掉(enabled: false)。

例外指向一条当前不判的规则 ⇒ 这条豁免**今天什么都没豁免**,却会在将来那条 规则被启用时无声地开始生效。与 ignore_dirs「豁免必须指向真实存在的目录」 是同一条纪律(那一条的理由:豁免指向不存在的目录时,它今天什么都没豁免, 却会在将来出现同名目录时整棵跳过),故同样判掉。

egresspaths.go —— 子进程出口的**声明面一致性**判据(P0-2 的后半)。

它拦的失效形态

@egress@ 给的是出口策略的**词表与判据**(env 生成、Verify、后端能力问询), 但词表本身不会跑到任何一个子进程上去。子进程一旦被 spawn,它的出站流量就 完全在本进程的 netguard 之外——「声明了受限出口」在那条路径上**没有任何东西 兑现**,而报告是全绿的,因为没有任何判据在问「这个 spawn 点在强制面内吗」。

这正是本仓反复强调的「声明强度 ≠ 实际强度」在执行面上的又一次实例: 判据停在工具调用,工具内部起的进程没有判据。

判据五条

  1. **每个子进程启动点必须登记**(未登记即红)。方向是 fail-closed: 「没登记」不等于「不要求出口」,而是**没人声明过它的出口是什么**—— 与 @sandbox_providers@ 的「有实现没登记必须报出来」同一条纪律。
  2. **登记的兑现必须能看见,且是两半**(mode >= proxy 时,含启动的那个函数里 既要出现出口 env 的生成/校验调用,**也要**出现后端能力的问询调用)。 只看得见 env 生成时,「声明了但没人执行」这一态是拦不住的:环境变量只是 **建议**,一个能改 env 却没有任何强制面的后端照样让流量自由出网,而报告里 「生成了 env」看起来就是「已兑现」。能力问询(SatisfiedBy)是那一半: 它问的是「你**能强制**这一档吗」,问不到即不起子进程。
  3. **禁网档不许落在环境变量上**(mode: denied 直接红)。环境变量拦不住 静态二进制、UDP 与原始 socket,登记成 denied 只是把「假装禁网」写进 policy——比明确不声明更危险。
  4. **陈旧登记当天即红**(文件/函数不存在,或那个函数里没有启动调用)。 与「陈旧包根当天即红」同一把尺子:声明与事实偏离而无人红,是无声漂移。
  5. **启动文件不得把全量环境交给子进程**(os.Environ() / procx.InheritAllExcept 即红,不看登记)。 登记段回答「出站策略是什么」,本条回答「子进程能看见宿主的哪些秘密」—— 两者正交:unrestricted 的启动点同样不该继承整份环境。详见 inheritsFullEnv。

为什么按「文件 + 函数」定位启动点

按包名太宽(一个包里可能既有 spawn 也有不 spawn 的函数),按行号太脆 (改一行注释就漂)。文件 + 函数是**改动的最小稳定单元**:函数搬走或改名, 登记就该跟着改,改漏了第 4 条会红。

判定面包含哪些启动形态

收集器在 spawnsites.go,覆盖三种形态(每一种都实测过漏判):限定符调用(含别名)、 点导入(无限定符)、**包级初始化**(var cmd = exec.Command(...),不在任何函数里)。 入口表按 import 路径归:除 os/exec 还含 os.StartProcess 与 syscall.Exec/ForkExec/StartProcess——它们同样绕开出口强制面,也各自接受 Env, 故「登记 + 兑现证据」这套判据对它们逐字适用。

判不了什么(写明,而不是假装覆盖)

  • 判不了「env 真的被子进程遵守」:环境变量只是建议,这是 egress 包 包头已写明的边界,本门禁不重复声明它能做到。
  • 判不了「围绕 cmd 包了一层自己的 spawn 工具再调用」:那需要类型的推导 或跨函数数据流,门禁不 import 被判的包也就拿不到类型信息。 这类封装最终仍要落到某个 os/exec 调用上,故**启动点**这一层是收口的; 但如果宿主把 spawn 挪进第三方库,本门禁看不见。

egressprobe.go —— 出口兑现的**调用证据**判定(AST 走法)。

与 egresspaths.go 分文件是因为两个关注点:那边判「登记与事实是否一致」, 这里判「函数体里有没有那**两个**调用」。合并会让 egresspaths.go 撞上 max_file_lines,而按行随便切一刀又会让「怎么认证据」这件事散落两处。

判据认结构,不认文本

三种书写形态都能命中:包限定(\`egress.Env(...)\`)、接收者调用(\`spec.Env(...)\`, 前提是本文件 import 了 egress)、以及 SatisfiedBy 的同款形态。逐行正则只认第一种, 而绕过去不需要动机——只需换个导入写法。

execution.go —— 执行路径门禁:执行必须经 `sandbox` 登记簿。

这条门禁拦的失效形态

上游 `sandbox` 的核心语义是「选不到满足档位的后端即拒绝,**绝不降级**」, 且「兜不住预算的后端不被选中」。这两条由 `Registry.Resolve` 保证。

但**执行路径**可以完全绕开登记簿:宿主直接调后端的裸执行入口 (本仓的 `ptc.Run`),于是——

  • 「要求了 OS 级隔离」却跑在进程内解释器上;
  • 「要求了内存兜底」而后端根本兜不住;
  • 审批门(`gatecheck.Managed`)整层被跳过。

而**门禁全绿**:档位登记门禁只核对「登记 ↔ 代码事实」,不核对 「**实际执行用的后端**是不是登记过的那个」。说谎的不是档位表,是**执行路径**。

判据

扫生产代码里的**限定符调用** `pkg.Fn(...)`:命中**裸执行入口**登记 ⇒ 违规。

为什么按「包名 + 符号」匹配,而不是按完整 import 路径

  1. **别名改不掉**:按 import 路径匹配时,宿主 `import p "…/ptc"` 换个别名就 绕过了。按 import 路径的**最后一段**(包名)匹配,别名不影响命中。
  2. **module 路径迁移不会陈旧**:本仓的 module 路径迁移过一次 (私有域名 → github.com)。若内置表写死完整 import 路径,迁移那天 忘了改门禁 ⇒ 判定**静默失配**(本仓纪律明令禁止写死 module 路径)。 按包名匹配则与 module 路径无关。

需要更精确时,登记项可填 `import_path` 二次收紧(限定到某一个具体模块)。

为什么同包调用不需要豁免

同包内的调用**没有限定符**(`Run(...)` 而不是 `ptc.Run(...)`)⇒ 根本不会被 扫到。实现内部的调用(`ptc.Provider.Exec` 调 `Run`)天然不构成绕过。

为什么裸入口是**内置表**而不是每个仓各登记一份

内置表记的是**本仓自己的 API 事实**(`ptc.Run` 不经登记簿)。 让每个仓在自己的 policy 里各登记一遍,就是**两份真相**——宿主改了登记、 本仓没改,两边各判一套,漂移到没人发现为止(且**没有任何信号**:门禁都绿)。

故:内置表(本仓的事实,宿主白拿)+ policy 段(宿主自己的事实)**并集**判。

这条门禁判不了什么(写明,而不是假装覆盖)

判不了「持有后端实例直接调 `provider.Exec(...)`」——那要判**接收者的静态类型**, 而 AST 拿不到变量的类型(要 `go/types` 才能推导)。 门禁不能 import 被判的包,也就不能靠类型信息定位调用点。 故:这类绕过**不在判定面内**,靠人工 review 与接线纪律兜。

importpattern.go —— forbid_import_regex 的「结构上命中不了」判据。

为什么需要它

forbid_import_regex 的判据面是 **import 路径**(imports.go 的 importViolationsIn), 而 Go 的 import 路径永远是 clean 形式:go 命令拒绝 a//b,也不存在以 / 结尾的 包路径。于是某些正则形状**一条都匹配不到**——它仍然是一条规则:计入「N 条规则」、 挂着 severity: error、selfcheck 只问「两个正则是否都为空」,于是它永不触发而 门禁照常绿(issue #41)。

判据为什么走 regexp/syntax 而不是 strings.Contains

最省事的修法是 strings.Contains(pattern, "//"),但它两头都错:

  • **假阳性**:[//] 是**字符类**(匹配单个 '/'),文本里含 '//' 却完全合法;
  • **假阴性(更要命)**:issue #41 自己举的例子 …/internal/(/|$) 里 **没有相邻的两个斜杠**——它是「前缀以 / 收尾」+「边界组 (/|$)」拼出来的 **语义上的** '//'。按文本判,这条规则会被判成健康,issue 就算「修好了」, 而缺陷原封不动地躺在仓里。

故判定面是语法树:判的是**结构**(字面量里是否强制相邻两个 '/'、结尾分支 是否要求以 '/' 收尾),不是文本长相。这也与仓内既有的纪律同源:结构性判断 走 AST,不走逐行正则。

判据的边界:只判「可证明永不命中」

本文件只报**能证明**永不命中的形态:返回空串**不等于**这条规则健康。 「这条规则还活着吗」的语义证明仍归 policy 的 examples 管 (require_rule_examples),两者分工明确:这里防「斜杠写重了」, 样例防「词表被改名 / 包被迁走」。反过来若在这里追求「一定命中」, 判据就变成不可判定的问题,只能靠误报凑数。

policy_egress.go —— egress_paths 段的声明面类型。

单列一份是因为 policy.go 已经贴着 max_file_lines:把「声明长什么样」与 「其余各段的声明」拆开,改动面也更清楚(这一段与 execution_paths 同族, 判据在 egresspaths.go)。

policy_tenant.go —— tenant_gate 段的声明类型(issue #172)。

与 policy.go 拆开的理由:policy.go 已接近 max_file_lines 阈值;租户门的形状 声明是一组自洽的字段(授权类型 / 租户字段 / 扫描面 / 共享面登记),单独成文件 比继续往 policy.go 里堆更容易读。

policy_wordtable.go —— word_tables 段的声明面(判定词表登记簿)。

为什么词表登记是**声明面**而不是内置清单

词表是**各仓自己的事实**(本仓有本仓的状态词表,宿主有宿主的), 而「消费方必须引用而不是手抄」这条纪律是**机制面**。两者分开: 换一个仓只需换 policy 一段,执行体一字不改——与 dependency_direction 段同构。

为什么 policy 里**不写取值清单**

取值必须由**代码派生**(表的键 → 常量声明 → 常量取值)。 policy 里若抄一份取值清单,那份清单自己就是第二份会漂移的真相—— 而它漂移的方向恰好是「门禁判的和代码跑的不是一套词表」, 失败形态是门禁变绿。故 policy 只声明「哪张表、在哪个包、枚举出口叫什么」。

ruleinfo.go —— 级别表与报告里的规则清单。

单独成文件是为了让 archcheck.go 保持在结构阈值之内(max_file_lines: 400): Run() 已经很长了,而级别表与清单是**装配**不是**判定**——继续塞进主线 只会让读者在判据里迷路。

sandbox.go —— 执行沙箱后端的**档位声明**核对(policy 的 sandbox_providers 段的执行体)。

这条门禁拦的失效形态

执行后端自报隔离档位(Provider.Level())。若那份声明只活在代码里,它有三个问题:

  1. **看不见**:review 时看不到「这个后端声称自己有多强」——档位是实现里的一个 常量,混在一堆方法之间,读者不会专门去看它。
  2. **漂移**:改了代码里的档位,声明面没有跟着变,而**没有任何东西会响**。
  3. **说谎没人管**:后端标了比实际更强的档位(例如「内核级」其实只是进程内解释器), 宿主据此做的风险判断全部落空——构建全绿、测试全绿、审计日志里只有一条 普通的进程记录。

怎么把信任边界写死

policy 的 sandbox_providers 段是**声明面**:每个后端一条登记(标识、档位、所在包), 档位填 `sandbox` 包的档位常量名(LevelNone / LevelProcess / LevelOS / LevelMachine)。 人 review 时看得到这一行,「它凭什么说自己有这一档」写在该条的 notes 里。

执行体核对两件事(都走 go/ast,不逐行看文本):

  1. **登记 ↔ 代码事实一致**:登记的标识与档位必须在该包的后端实现里对得上; 对不上就是漂移(代码改了、声明没改)。
  2. **实现 ↔ 登记齐全**:本仓每个后端实现都必须在 policy 里登记。未登记的后端, 它的档位声明**不在被复核的清单里**——它可以存在,但不能假装自己被复核过。

这条门禁判不了什么(写明,而不是假装覆盖)

它判不了「后端实际提供的隔离强度是否兑现其声明」——那要审实现,机械判不了。 它能保证的是三件事:声明**可见**(在 policy 里)、**不漂移**(门禁核对)、 **有签字**(人 review 时看到那一行)。

为什么用方法指纹判定「这是个后端实现」

判据是「实现了 ID + Level + Exec 三个方法」,**不是**「它 import 了 sandbox 包」。 后者只说明它见过那个包,前者才说明它实现了那个协议;而 import 路径在本仓与宿主仓 不同,写死路径会让复用方永远判不出来——于是这条门禁在宿主仓就成了摆设。

seamcontract.go —— 形态 B:接缝契约标记完备性(issue #369/#370)。

判据:导出接缝声明点(导出函数/方法/接口方法/结构体字段,参数或字段类型为 `func() time.Time`)的文档注释必须带齐

// @seam: no-reentry no-blocking panic-isolated

三条约束:不得重入 / 不得阻塞 / panic 处置(panic-isolated 或 panic-caller 恰一个)。缺一条即红(退出码 1)。

为什么是**导出声明点**:内部字段/参数是实现的自由,宿主看不到;契约要约束 的是宿主能注入的那个面。issue #369 的 20 条统计把字段与参数分开计,本门禁 按「声明点」计(一处 option 函数覆盖其字段),口径差异写在 docs/SEAM-CONTRACT.md,不假装是同一个数。

根本局限(必须记住):标记是**承诺不是事实**——声明了 no-reentry 但代码 仍在锁内调,本规则照样绿。兑现面由形态 A(只读扫描)与形态 C(panic 隔离) 承担,逐条契约用例是 #370 的形态 C 延伸。

seamlock.go —— 形态 A:时钟访问器「在锁内被调」的只读扫描(issue #370)。

这是**一阶 AST 启发式**,不是判定;默认 severity: warn,不阻断。它的输出 是疑似清单,供人工复核。漏判形态(必须与工具一起记住):

  1. **闭包作用域**:函数字面量按独立判定面处理。外层锁不传递给闭包(正确), 但闭包在锁内被调用时,闭包里的接缝调用不会被判出来(漏判)。
  2. **多出口解锁**:按源码顺序回放 Lock/Unlock。早退路径各自 Unlock 会让 后续语句被误认为「已解锁」(漏判;#366 的 quota_store.go:306 正是此形态)。
  3. **helper 形态**:持锁调本包函数、该函数内调接缝 ⇒ 不做跨函数调用图(漏判)。
  4. **接口接缝的自实现**:静态类型是接口时无法区分内核自调与宿主实现(不判)。
  5. **非 mutex 互斥**:channel 信号量 / atomic.Pointer 的 copy-on-write 判不了。

为什么仍然值得进 make check:它能在**修复后的代码**上把「把 m.now() 挪回锁内」 这类回归直接显示出来(warn 级),并且零依赖、零误报优势明显——它只对 `receiver.now()/clock()` 这类明确形态发声。

seampanic.go —— 形态 C:宿主接缝的 panic 外溢检测(issue #370)。

判据:policy 登记在 `seams.panic_scan.guarded_calls` 的宿主调用,其调用点必须 满足二者之一:

  1. 位于隔离包装器的回调内(subhub.Do / subhub.Invoke / async.GoSafe / async.RunSafe 等)——包装器自己 recover;
  2. 所在函数带 `defer func(){ ... recover() ... }()` 兜底。

这正是 #368 的验收形状:同一宿主接缝在批量 / 并发两条路径上的 panic 归属 必须相同;逃出心跳协程一次就是全部在途租约失保。

局限(与形态 A 同一条纪律:说清判不了什么):

  • 只按**调用名**精确匹配,不做类型/接口解析;同名但不同接缝的调用会被一并 要求隔离(宁可多要求,不漏判);
  • recover 只认 deferred 函数字面量内的调用,直接 `defer recover()` 不算;
  • 包装器清单是声明面:新增隔离原语要先登记,否则会被误报(清单缺失的 失败方向是**变红**,不是变绿——比反向漏判安全)。

seamrules.go —— 宿主接缝契约门禁的声明面与三门聚合(issue #369/#370)。

三种机判形态与取舍、各自漏判形态,见 docs/SEAM-CONTRACT.md 与 archcheck/seamcontract.go / seamlock.go / seampanic.go 的文件头。

实现分成四个文件,按判定形态切开(也避开 400 行结构阈值):

seamrules.go     声明面类型、默认值、判定面枚举、三门聚合
seamcontract.go  形态 B:契约标记完备性(阻断)
seamlock.go      形态 A:锁内调用只读扫描(warn,不阻断)
seampanic.go     形态 C:panic 外溢检测(阻断)

selfcheck_wordtable.go —— policy 自校验的 word_tables 段分支。

为什么词表登记面要单独接进自校验

word_tables 段的声明面会**自相矛盾**:包名写错、类别写错、归一出口挂在 判定词表上、同一张表登记两次……这些都不是「代码与声明不符」,而是**声明 自己跟自己打架**。

放在执行体里报红有两个毛病:

  1. **太晚**:执行体要跑到词表门禁那一步才报,而自校验是**提交前**就该拦的;
  2. **太窄**:自校验恒开(它是「声明面能不能信」的地基),而词表门禁段 可以被 policy 关掉——关掉之后,声明面里的矛盾就没人判了。

⇒ 声明面内部矛盾归**自校验**(恒开、提交前);代码事实类(谓词还在不在、 出口读不读那张表)留在执行体。同一件事只由一个主人判——两处都判会 变成「同一件事报两次」,读者要自己判断哪条才是根因。

spawnsites.go —— 子进程启动点的收集(出口门禁的「事实面」)。

判据(登记与否、兑现是否可见)在 egresspaths.go;这里只回答一个问题: **代码里到底有哪些地方起了子进程**。拆成两份是因为两类失效的形态不同: 判定写错会误报(有人会来修),收集写漏是**静默放行**(没人会来)——后者必须在 自己的文件里被逐形态钉住。

覆盖的三种形态(每一种都是实测漏判后才补上的)

  1. **限定符调用**:exec.Command(...)。别名(import ex "os/exec" ⇒ ex.Command) 同样命中——限定符按 **import 路径**解析,不按名字猜。
  2. **点导入**:import . "os/exec" ⇒ Command(...) 没有限定符。按「本文件点导入了 哪个启动包」补齐,否则换个导入写法就能让判定面消失。
  3. **包级初始化**:var cmd = exec.Command(...) 不在任何函数里。旧实现只走 *ast.FuncDecl,于是把 spawn 挪到包级变量就能让门禁变绿——而 spawnSite.fn 的 注释早就写着「空 = 函数外,如包级变量初始化」,即**承诺了却没人实现**。

入口表按 import 路径归,不止 os/exec

os.StartProcess 与 syscall.Exec/ForkExec/StartProcess 同样绕开出口强制面。 它们各自接受 Env,故「登记 + 兑现证据」这套判据对它们逐字适用——把它们留在 判定面之外,等于承认「换个 API 就能绕过登记」,而绕过是静默的。

tenantast.go —— 租户门的 AST 基础设施:解析、类型推导、形参/证据识别。

判定流程在 tenantgate.go;本文件只放「从语法树里读出什么」的纯函数, 便于把执行体保持在 max_file_lines 阈值以内(拆的是关注点,不是为拆而拆)。

tenantgate.go —— 租户过滤漏拼门(issue #172):隔离证据判据 + 登记面漂移检测。 租户表登记面三条判据在 tenantmanifest.go(issue #177 补齐到 6 条,与 bianque tenantcheck 同口径)。

为什么需要这条门禁

多租户隔离若依赖「人记得在查询里拼过滤列」,忘拼一次就是跨租户越权,且 没有任何机器能拦住。判据落在**服务层**(repo 层按 id 操作天然无过滤会假红, handler 层有授权下沉会假红;服务层才是租户读面的汇聚点):

  1. tenant-surface-missing-evidence:带授权上下文形参 + 返回租户域类型的 函数必须有隔离判定证据——调用登记的共享判定面 / 查询条件含过滤列 / 显式 `// tenant:iso <理由>`。三者皆无 = 漏拼即红。
  2. viewer-dropped:带授权上下文形参却完全不用 = 授权上下文被丢弃 = 红。
  3. shared-surface-missing:登记在册的共享判定面在代码里不存在 = 清单漂移 = 红(一条被静默放宽的登记等于没有登记)。

声明 tenant_tables_manifest 后再加**租户表登记面**三条(判据落点见 tenantmanifest.go 头注):tenant-policy-missing(模型面表缺登记)、 tenant-policy-drift(清单登记的表模型面已不存在)、tenant-table-name-missing (租户域模型没有可解析的表名方法)。不声明则只跑前三条。

形状归 policy,执行体通用

哪些类型算授权上下文、哪些字段算租户域、过滤列叫什么、共享判定面在哪, 全部由 policy 的 tenant_gate 段声明(TenantGate)。本文件不出现任何宿主 字面——换一个多租户仓只需换 policy,执行体一字不改。

租户类型清单由代码推导

不另立类型清单:推导面(TenantTypeRoots,缺省 = Roots)内任何含 TenantFields 字段名的 struct 都是租户域类型。新增模型自动入面。

判不了什么(写明边界)

本门禁判的是**静态证据存在性**,不是「过滤是否真的生效」:

  • 调用了共享判定面但没用返回值、Where 里写了过滤列但条件被注释掉, 这类语义缺陷判不了(需要类型/流分析或运行期判据);
  • 同包重名类型按包名索引,两个不同包同名时可能误判(与 bianque 原判据 同口径的已知边界);
  • 登记面清单与宿主 RLS 注册表的一致性靠宿主自己的 dump/校验测试保证 (注册表是 Go 符号,执行体调不到,见 tenantmanifest.go 头注)。

tenantgate_selfcheck.go —— tenant_gate 段的形状自校验。

这一段是**形状声明**:授权上下文类型名 / 租户域字段名 / 扫描面。缺了任一项, 执行体就没有判定面——要么对每个函数报「无证据」(假红一片),要么静默不判 (假绿)。两种失败形态都必须在这里变成红,而不是留给宿主去猜。

tenantmanifest.go —— 租户表登记面判据(issue #177,bianque tenantcheck 的 `tenant-policy-missing` / `tenant-policy-drift` / `tenant-table-name-missing` 三条):模型面推导出的租户表集合与 policy 声明的清单做**双向**核对。

为什么是清单不是注册表

宿主持有的 RLS 注册表是 Go 符号,执行体调不到;tenant_tables_manifest 是 宿主自己 dump 的产物(或由一条校验测试保证与注册表一致)。语义与 shared_surfaces 的「存在性核对」同族:登记面与代码面谁走了谁都不行—— 单向核对漏掉的正是漂移的另一半。

物理表名怎么解析

每个含租户字段的 struct 必须有可从 AST 识别的表名方法(缺省 TableName, policy 的 table_name_method 可改):方法体单条 `return "字面量"` 才可解析 ——动态拼接的表名执行体读不出,登记面核对不了这张表,按 deny-by-default 报 tenant-table-name-missing(与 bianque 原判据同口径:没有可解析表名的 模型本身就是红)。

thresholds.go —— 结构债阈值的执行体(超长文件 / god object)。

从 archcheck.go 拆出:Run 只保留「调一次、拿结论」的流程,阈值判定的 错误语义(遍历/解析失败 ⇒ 给不出结论)与报告文案集中在这里。

unmanaged.go —— 未受管逃逸门禁:生产代码不得显式选择「无判定环执行」。

这条门禁拦的失效形态

PTC 的安全默认是 fail-closed:**装配了工具绑定却没装判定环 ⇒ 拒绝执行** (见 ptc.Options.Stages)。但 fail-closed 留了一个**逃逸口**: `AllowUnmanaged: true` —— 宿主显式声明「我这一层的工具另有一套管控」。

逃逸口的通病是**真违规一起被放过**:一旦逃逸口可以在生产代码里随手写, 它就从「显式声明」退化成「默认路径」——而默认路径是没人会去看的地方。

于是本门禁把逃逸口**变成可见的**:生产代码里出现 ptc.Options/Provider/ SubprocessOptions 的 AllowUnmanaged 字段,即报违规。

为什么按「字段出现」判,而不是按「字段值为 true」判

按值判只能抓住字面量 true;`AllowUnmanaged: cfg.Unmanaged`(配置驱动) 与 `AllowUnmanaged: someVar` 都判不出来——而配置驱动恰恰是最该被看见的 那种形态(「这个部署可能跑未受管执行」)。故按**字段出现**判: 生产代码要表达这个意图,就得先在 policy 里显式登记豁免。

赋值路径(v0.33.0,issue #92)

「字段出现」只看复合字面量,`opts.AllowUnmanaged = true`(变量赋值)与 `opts.AllowUnmanaged = cfg.Unmanaged`(配置驱动)从它眼里溜过去。第二道 判据在 unmanaged_assign.go:AST 级类型追踪(go/types 的等价手段),对 持有着 ptc 逃逸类型的变量做该字段的**赋值**即报——同样不按值判。 接收方类型静态不可溯的形态(接口 / 无类型返回值 / 深层容器)仍是盲区, 但宿主自建的同名字段也因此不误报——报得准,规则才不会被习惯性忽略。

这条门禁判不了什么(写明,而不是假装覆盖)

  • 判不了接收方类型**静态不可溯**的赋值:经接口、无类型标注的函数返回值、 深层容器元素流转过来的值(unmanaged_assign.go 头注写明口径)。
  • 判不了宿主**自建**的同名结构体字段(那不是本包的逃逸口)。

unmanaged_assign.go —— 未受管逃逸门禁的**赋值路径**判定(v0.33.0,issue #92)。

盲区在哪

unmanaged.go 的字面量判据按「复合字面量里的字段出现」判——它判不出**变量 赋值**:`opts.AllowUnmanaged = true`(或 `= cfg.Unmanaged`,配置驱动同理) 里没有复合字面量,而接收方 opts 的类型要靠类型信息推导。而「另有一套管控, 开关在配置文件里」恰恰是生产代码最常见的写法——盲区等于没有判。

判据:AST 级类型追踪(go/types 的等价手段)

不引 go/types(它要把整仓类型检查一遍,且要加载依赖的导出数据——门禁的 成本与脆弱面都会失控)。等价手段是**三趟 AST 追踪**,覆盖静态可辨的形态:

  1. **类型层**:谁**是**逃逸类型(`type T ptc.Options`),谁的字段**带着** 逃逸类型(`type Cfg struct { O ptc.Options }`;`type Cfg struct { ptc.Options }` 嵌入同判——嵌入把字段提升到了外层);
  2. **变量层**:谁持着它们——带类型的 var 声明 / 短声明(含取址、切片与 map 容器)/ 函数参数、结果与接收者;
  3. **赋值层**:对持有着逃逸类型的变量做 `….AllowUnmanaged = …` 赋值即报。

按赋值路径判、**不按值判**(与字面量判据同一条纪律):`opts.AllowUnmanaged = cfg.X` 与 `= false` 都报——逃逸口的开与关不该由数据流决定,生产代码要表达 这个意图就得先在 policy 里登记豁免。

这条判据判不了什么(写明,而不是假装覆盖)

  • 接收方类型**静态不可溯**的形态:从无类型标注的返回值 / 接口 / 深层容器 元素里拿到的值。这类赋值不报——但**宿主自建**的同名字段也因此不误报, 这是类型感知换来的「报得准」。
  • 宿主自建的同名结构体字段:那不是本包的逃逸口(unmanaged.go 头注同款)。 类型追踪正是为了把两者分开:字段名一样、类型不同,判据只认 ptc 的类型。

反向验证见 unmanaged_test.go:注入赋值与配置驱动形态 ⇒ 红;宿主自建同名字段 ⇒ 不误伤。

unmanaged_gotypes.go —— 未受管逃逸门禁的**类型感知严格档**(issue #103)。

为什么有了 AST 追踪还要这一档

unmanaged_assign.go 的三趟 AST 追踪是 go/types 的「等价手段」——轻,但头注 自述了盲区:接收方类型**静态不可溯**的赋值(经无类型标注的函数返回值、 接口断言、深层容器元素流转)判不到。门禁越严,宿主越会去找「判不到的写法」 ——盲区不是靠把边界写成文档就能关上的:那等于把「怎么绕过」写成了文档。

严格档用 go/packages + go/types 做**真类型解析**(可选档,默认关):

  • 代价:整仓连同依赖做一遍类型检查(比 AST 判据慢一个量级,还要加载 依赖的导出数据)。这就是它必须是「可选的严格档」而不是默认档的原因。
  • 换来:赋值接收方的类型由 types 推导——函数返回值、接口断言、map / slice 元素、别名、defined type 包装,凡 types 解得出来的都判得到。

开法与失效形态

  • `cmd/archcheck -types` / `make architecture-check-types`(opt-in,不在 check 快速路径——成本原因,见上)。
  • **类型解析失败必须显式报错**(本文件的纪律与 unmanaged.go 同源: 「给不出结论」与「没违规」严格分开):packages.Load 失败、任何包带 类型错误、解析出零个包——一律返回 error(cmd 侧退出码 2,即 「门禁自己坏了」,不是「无违规」)。
  • 与 AST 判据同报一个规则(unmanagedEscapeRuleID),按 (path, line) 去重 ——两档都看得见的形态只报一次,报两次会让豁免登记也变成两份。

unmanaged_types.go —— 逃逸口赋值判定的**类型追踪层**(v0.33.0,issue #92)。

与判定层(unmanaged_assign.go)分开:这一层只回答「这个类型/变量/表达式 静态可辨地持有 ptc 的逃逸面吗」,不产生违规。判据是 go/types 的等价手段 (三趟 AST 追踪),覆盖的形态与残余盲区写在 unmanaged_assign.go 头注。

wordtable.go —— 判定词表登记门禁(word_tables 段的执行体,go/ast 判定)。

这条门禁防的是什么

判定词表(会话状态、任务状态、环节类别……)是**决定结论**的取值集合: 宿主按一张表落库,内核按另一张表判状态,同一个状态在两处得到相反结论, 而没有任何机器能拦住。

此前内核侧已经补齐了「导出枚举出口」(issue #356:内核词表可导出), 但**消费侧**仍各写一份字面量:内核新增一个取值,消费方那份不会跟着变, 且没有任何判据会红。⇒ 这条门禁把「消费方必须**引用**而不是手抄」 变成机器判据。

两条判据

  1. harness-word-table-enum-missing —— 登记的词表必须有一个**导出枚举出口**, 且该出口必须**读同一张表**(不得另抄一份清单,否则它就是第二个真相源)。
  2. harness-word-table-handcopy —— 别的包在生产代码里**手抄**了登记词表的取值。

两类词表(kind)

decision(缺省):取值**决定结论**。消费方不得手抄。 input:取值是**外部喂进来的词形**(归一词表)。消费方自由使用—— 那是输入数据,不是判定依据;门禁只判「这张表有导出枚举出口, 且出口读的是同一张表」。

为什么必须分两类:把输入词表当判定词表登记会引出成片假阳 (实测 protocol 的 43 个图表词形会命中 17 处,大半是 JSON 键、 HTTP 响应体这类无关上下文)。而它们同样需要保护—— 「这张归一表归 protocol 管、它的出口不许漂」正是要机判的。

「手抄」的判据形态(为什么它可机判)

取值属于登记词表 ⇒ 出现它的那处代码必须是**有名字的**: 要么它在常量声明里(本包给这个取值起了名字),要么它是主人表自身的 定义处,要么它根本不是字面量而是 owner.Const 这样的引用。 其余 ⇒ 那段字面量没有名字,判定与取值各写一份,改一处漏一处。

为什么允许「本包自有常量」:同一个拼写在不同包里可以是不同概念 (contract 的 "failed" 是会话状态,delegate 的 "failed" 是回执状态)。 要求它**命名**,而不是要求它**不许用**——否则合法用法也会被判红, 而判红到没人信它,它就等于没有。

形状归 policy,执行体通用

哪些包有哪张表、表由哪个变量承载、枚举出口叫什么、这张表是判定词表 还是输入词表,全部由 policy 的 word_tables 段声明。本文件不出现任何 具体词表——换一个仓只需换 policy。

边界(写明判不了什么)

  • 只判**字面量**形态:常量、枚举、映射键都判不到(它们已经是名字了);
  • 判定面只含**生产代码**(测试文件不判):测试夹具是临时的, 且把夹具纳入会逼出「只为跑用例而写的常量」噪声;
  • 判据是**出现点级**的:同一包里既定义了常量、又写了同一取值的裸字面量, 后者判红——「命名过了却还写字面量」比「没命名」更该改。 但「这段字面量是否在**判定路径**上」需要 go/types 档的类型信息 (RunOptions.TypeAware),本轮做不到,故此处只判「有没有名字」;
  • 词表取值集合由**代码派生**(表的键 → 常量声明 → 常量取值), policy 里不写取值清单:那份清单自己就是第二份会漂移的真相。

wordtable_anchor_all.go —— 关系锚点的「all 形态」:锚住两端**共有**的全部取值。

为什么要有这个形态

抽样锚定只钉住一两个取值 ⇒ 其余共有取值漂了(取值改了、别名指向变了、 某一端删了常量)要靠族覆盖 / 派生漂移判据兜 ⇒ 关系「说谎」在那部分取值 上没人判。all 形态把锚点从「抽样」升级成「覆盖全部同形取值」。

为什么这不是新机制

all 形态只是把**锚点取值集合**换成「两张表的共有取值集合」⇒ 判据 1~4 原样复用:

  • 判据 1(锚点存在):每个共有取值在本端必须有对应常量(没有 ⇒ 这一端 锚不住它 ⇒ 那一个取值上关系没人钉);
  • 判据 3(成对):两端锚定的都是共有取值 ⇒ 天然成对;
  • 判据 4(distinct 不同处声明):每个共有取值的两端根声明必须不同 ⇒ 「不同概念」在**全部**共有取值上都被验过,而不是只验了抽样的那几个。

wordtable_face.go —— 词表登记门禁的「函数面」判据(判定谓词 / 输入归一出口)。

为什么单独成文件

登记面判的是「这张表在不在、出口读不读它」(wordtable.go), 而本文件判的是「这张表**登记的另外两个函数面**与代码事实是否一致」:

  • 判定谓词(predicate):表的**判定面**。枚举出口读同一张表,只保证 「表 ↔ 出口」不漂;而判定面(IsKnownStatus / Valid)是另一个独立 读表的地方——它若另抄一份清单,判定就会与词表分叉。
  • 输入归一出口(normalizer):只属于 **kind: input**。没有归一出口, 消费方只能**自己**判这个词形 ⇒ 同一个输入词在不同消费方得到不同结论。

两者的失败形态都是**静默失管**(登记与事实偏离却没人发现), 故与登记面同口径:一律报红,且文案点名该改哪里。

wordtable_family.go —— 判定词表登记门禁的「族覆盖」判据(反向派生)。

这条判据防的是什么

取值派生只有**一个方向**:表的键 → 取值。由此产生一个没人管的洞—— 主人包**新增**一个同族常量却忘了把它加进表:

  • 它不在表里 ⇒ 手抄判据判不到它(它不是「表里的取值」);
  • 它不在枚举出口里 ⇒ 宿主看不到它(出口读的是那张表);
  • 它在主人包里是个**正经的导出常量** ⇒ 谁看代码都以为它受管。

⇒ 那个新取值的消费侧从此**没人管**:主人新增了取值,消费侧还在手抄旧清单, 而没有任何判据会红。这正是「派生方向只有「表 → 取值」,反向没判」。

判据(两条,都可机判)

  1. **族 ⊆ 表**:族里的每个常量,其取值都必须在登记的那张表里。 ⇒ 「常量加了、表没加」当天即红。
  2. **表 ⊆ 族**:表的每个键(常量名形态)都必须属于族前缀。 ⇒ 族前缀写错、或表里塞了别的族的键,当天即红。

「族」怎么声明:前缀 + 豁免

族用**前缀**声明(policy 的 family 字段):主人包里名字以它开头的、 取值可解析为非空字符串的常量,就是族成员。

为什么是前缀而不是「列出常量名」:列出常量名就是**第二份会漂的真相** ——policy 里抄一份清单,清单自己会漂,而它漂的方向恰好是「门禁判的和 代码跑的不是一套词表」。前缀是**形状**声明,与 backing / enum / predicate 同类。

同族里常含**另一张表**的常量(protocol 的 Decision* 同时含 decisionAll 的 3 个与 decisionSources 的 7 个)⇒ 族前缀判不出「哪些属于哪张表」。 故给一个显式豁免口(family_exclude,**按前缀**豁免一段,且必须写理由): 按前缀一段排除,不必把另一张表的常量逐个列出来——逐个列就是那份清单。

失败形态

全是**变红**:登记与事实偏离(族成员漏进表、族前缀写错、豁免已失效) 若被当成「没有违反」,门禁就是**静默空转**——一条都判不了却照常报绿。

wordtable_family_owner.go —— 族归属的派生:常量前缀归哪张表。

为什么要有这个文件

同一族里常含**另一张表**的常量(protocol 的 Decision* 同时含 decisionAll 的 3 个与 decisionSources 的 7 个)⇒ 族前缀判不出「哪些属于哪张表」。 此前靠**手写豁免**(family_exclude)逐段排除:一族分表变多时要逐段手写, 而手写的那份正是「第二份会漂的真相」——它漂的方向恰好是「门禁判的和 代码跑的不是一套词表」。

归属怎么派生

每张表声明自己**拥有**的常量名前缀(family 字段);一个常量归哪张表, 按**最长匹配前缀**决定(同包里更具体的前缀赢):

ConfidenceHigh     → "Confidence"     → confidenceAll
ConfidenceKindXxx  → "ConfidenceKind" → confidenceKinds(更具体 ⇒ 赢)
DecisionPending    → "Decision"       → decisionAll
DecisionSourceRule → "DecisionSource" → decisionSources(未登记也声明)

为什么是「最长匹配」而不是「谁先声明谁赢」:前缀之间有**包含关系** (Confidence ⊂ ConfidenceKind),包含关系下唯一能自洽的规则就是 「更具体的那个拥有它」——与 http mux 的最长匹配同一条思路。

为什么未登记的表也要声明前缀

不登记 ≠ 没人管:那张表的常量仍会被同包另一张表的族前缀命中。若不声明 归属,它们会被算成「漏进表」(假红)——那正是手写豁免存在的唯一理由。 声明了归属,豁免就不必手写。

wordtable_index.go —— 词表门禁的全仓索引:常量取值、import 别名、字符串字面量。

为什么索引单独成文件

这套判据要回答三个**跨包**问题:

  1. 主人包里那张表的**键**到底对应哪些取值(键是常量名,取值在常量声明里);
  2. 常量声明可能是**跨包别名**(statemachine 的 StatusCreated = contract.StatusCreated),取值解析必须能追过去;
  3. 某个包里有没有**手抄**了这些取值(要扫全部字符串字面量)。

三件事共用一份索引:同一件事扫两遍就多一份会漂移的实现, 而两份实现漂移时的表现是「门禁时红时绿」——最贵的失败形态。

wordtable_index_collect.go —— 索引的采集器:从一个文件里抽出常量、变量与字面量。

为什么与索引主体分开成文件:索引主体是「事实的形状」(有哪些包、 怎么解析跨包别名),采集器是「怎么从源码取事实」。两者混在一个文件里时, 取事实的细节(哪些字面量算取值、哪处算命名处)会把形状盖住——而形状 恰恰是读这套门禁的人最需要先看懂的部分。

wordtable_overlap.go —— 判定词表登记门禁的「同形撞车」判据。

这条判据防的是什么

同一个拼写可能是**多张判定词表**的取值,而它们的**含义**可能相同也可能不同: contract 的 "failed" 是会话失败、taskboard 的 "failed" 是任务失败。

手抄判据只按「值在不在表里」判 ⇒ 它分不出「这处字面量想说的是哪张表」 ⇒ 修法文案若只指向某一张表,就可能把人引到**错误的概念**上 (把任务失败改成引用会话失败常量 = 语义损坏)。

⇒ 凡两张登记的**判定词表**有同形取值,必须在 policy 的 relations 段 **显式声明关系**:

  • same :同一概念(一张表的别名/子集),引用任一家都对;
  • distinct :不同概念(同形只是拼写巧合),手抄方必须**在本包命名**。

为什么用**中心清单**而不是各表自己声明

关系是**两张表之间**的事,写在任一方都会引出「两边都声明了但不一致」的 第三种状态。中心清单(word_tables.relations)让「这对表是什么关系」 只有一个答案。

为什么值域必须封闭

写错的关系名若被当成「不是 same」,就会被落进「不同概念」那一档—— 而「不同概念」那一档的修法是**在本包另起一个名字**:把「同一概念」 误判成「不同概念」,代价是每个消费方都要多抄一份名字(词表从此不是 唯一真相源)。反向误判更贵:把「不同概念」当成「同一概念」⇒ 手抄指路 把人引向错误的常量 = 语义损坏。⇒ 写错的关系名必须当天即红。

失败形态

全是**变红**:

  • 撞了没声明 ⇒ 关系缺失(拼写巧合还是同一概念,没人说得清);
  • 声明了没撞 ⇒ 声明失真(今天没关系,将来两表一旦同形就会无声生效)。

wordtable_scan.go —— 判定词表门禁的「手抄」扫描面。

为什么扫描面单独成文件

扫描面判的是**出现点级**的事(这一处字面量有没有名字), 而 wordtable.go 判的是**登记面**的事(这张表在不在、出口读不读它)。 两种判据的失败形态不同(前者是假红,后者是静默失管), 混在一个文件里时,后写的那个会盖掉先写的那个——而读门禁的人 恰恰要先知道自己踩的是哪一类坑。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FindRoot

func FindRoot(start string) (string, error)

FindRoot 从 start 向上查找含 architecture-policy.yaml 的目录。

为什么向上找而不是要求调用方传绝对路径:门禁要在这个目录下判定所有包, 而包在磁盘上的位置是随仓库克隆位置变的。

func PolicyPath

func PolicyPath(root string, pol *Policy) string

PolicyPath 归一 policy 文件路径(相对仓库根),供报告与自校验定位。

func WriteReport

func WriteReport(w io.Writer, res *Result, opts ReportOptions) error

WriteReport 把结果写成人类可读的报告。

报告形状与「哪些规则在什么范围内」无关——三类规则(rules 段正则、facades 段、 modules 段 requires)的回显形状完全一样,复制三份意味着以后改截断口径要记得改三处。

返回写入错误:报告写了一半就失败(管道提前关闭、磁盘满),调用方需要知道 「这份报告不完整」——否则它会拿一份残缺的报告当结论。

Types

type DependencyDirection

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"`
}

DependencyDirection 是 dependency_direction 段的配置:依赖方向门禁的开关、 级别、豁免目录与**受管外部包面**。

为什么不塞进 modules 段:modules 段是**逐包**的声明,依赖方向是**跨包**的 规则,混在一段里会让「这条登记的字段」与「整个文件的配置」两种粒度互相干扰。

type EgressEntry

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"`
}

EgressEntry 是 egress_paths 段里的一条**子进程启动点**登记。

定位粒度是「文件 + 函数」:按包名太宽(一个包里可能既有 spawn 也有不 spawn 的 函数),按行号太脆(改一行注释就漂)。函数搬走或改名,登记就该跟着改, 改漏了判据会报陈旧。

type EgressPaths

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

EgressPaths 是 egress_paths 段的配置:开关、级别、受忽略目录与启动点清单。

形态与 execution_paths 段同构:都是「声明面 + 代码事实」的一致性判据。 差别在于执行路径门禁有**内置表**(记本仓自己的 API 事实),而这一段没有: 子进程启动点是每个仓自己的事实,本仓没有资格替宿主登记。

type Exception

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"`
}

Exception 是例外登记:精确豁免某条规则的某处违反。

豁免必须写 until(到期日)与 removal(拆除条件)——没有到期日的豁免等于永久豁免, 没有拆除条件的豁免是赖账。两者都由 policy 自校验强制。

type ExecutionEntry

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"`
}

ExecutionEntry 是 execution_paths 段里的一条**裸执行入口**登记。

「裸」指什么

不经 `sandbox` 登记簿就能跑起一段程序的入口。绕开登记簿意味着三样东西 同时失效:**档位下限**(`Resolve` 选不到就拒绝的那条)、**预算可兑现性** (兜不住内存的后端不被选中的那条)、**审批门**(`gatecheck.Managed` 那层)。

而这三条恰恰是宿主据以做风险判断的依据——声明还在,强制没了。

为什么按**包名**登记而不是完整 import 路径

  1. **别名改不掉**:按完整 import 路径匹配时,宿主 `import p "…/ptc"` 换个别名 就绕过了。按包名匹配,别名不影响命中。
  2. **module 路径迁移不会陈旧**:本仓的 module 路径迁移过一次 (私有域名 → github.com),写死完整路径会在迁移那天静默失配。

需要更精确时填 `import_path` 二次收紧(限定到某一个具体模块)。

type ExecutionPaths

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"`
}

ExecutionPaths 是 execution_paths 段的配置:开关、级别、受忽略目录与裸入口清单。

形态与 sandbox_providers 段同构(配置 + 逐条声明的表)。

本仓自己的裸入口不在这一段里

它们在判据执行体的**内置表**里(见 execution.go):内置表记的是本仓的 API 事实, 让每个仓各登记一遍就是两份真相。policy 段只登记**宿主自己的**裸入口。

type FacadeRule

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)
}

FacadeRule 声明一个门面包:它转发到哪、还允许带哪些签名所需的额外依赖。

type FamilyPrefixes added in v0.45.0

type FamilyPrefixes []string

FamilyPrefixes 是族前缀的声明面:**一个或多个**前缀。

形态兼容:YAML 里既可写字符串(family: Status)也可写列表 (family: [Status, Phase])——单前缀是常态,列表是「一族跨了两个前缀」 时的写法。

为什么允许多前缀:一族的常量**不一定**共享同一个前缀("StatusXxx" 与 "PhaseXxx" 同族),单前缀会漏掉一族的一半 ⇒ 漏掉的那半永远没人管 (它不在表里 ⇒ 手抄判据判不到它;它不在枚举出口里 ⇒ 宿主看不到它)。

func (FamilyPrefixes) String added in v0.45.0

func (f FamilyPrefixes) String() string

String 把族前缀渲染成一行(报告文案用)。

func (*FamilyPrefixes) UnmarshalYAML added in v0.45.0

func (f *FamilyPrefixes) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML 接受字符串或列表两种形态。

为什么自己实现:yaml.v3 默认只认一种形态,而 policy 是**声明面**—— 声明面多一种写法就多一种「宿主写不出来只能改执行体」的风险。

type Module

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"`
}

Module 是 modules 段的一条登记:roots 定位包目录,requires 声明**允许**的 依赖方向。

为什么这段必须被真的执行:requires 是一张包之间的依赖拓扑声明,写错或漏写时 它不会自己报警——半年后没人知道它已经不成立,而依赖缠绕恰好是最难靠 review 发现的债类型(零报错、零警告、构建全绿)。

requires 的条目有两种形态:

  • 模块 id:本仓内部模块,必须在 modules 段登记过,否则声明自相矛盾(判为 policy 解析失败,不静默降级)。
  • ext:<import 路径前缀>:外部包面,用于表达「本模块依赖某个外仓的哪个包」。 机制面迁到外仓之后,宿主的依赖拓扑表需要能表达跨仓依赖,而只认本仓模块 id 的判据表达不了。

type NegFollow

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

NegFollow 是负向前置的结构化表达:anchor 紧跟 forbid_follow 时,命中位置 (被禁词)落在 forbid_follow 里即豁免。

为什么不写进正则:Go 原生只支持 RE2,没有后顾断言((?!))。

type Policy

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"`

	// TenantGate 是租户过滤漏拼门的声明面(授权上下文的类型形状、租户域
	// 字段名、共享判定面清单)。段缺省即关闭——形状是判定前提,没有形状
	// 就判不了;声明了段却漏形状由自校验报红。
	TenantGate *TenantGate `yaml:"tenant_gate"`
	// Seams 是宿主接缝契约门禁的声明面(#369/#370);段缺省即关闭。
	Seams *SeamRules `yaml:"seams"`
	// WordTables 是判定词表登记门的声明面(词表清单 + 枚举出口)。
	//
	// 段缺省即关闭:这条门禁的判定面是**这张表登记了什么**,
	// 不是「仓里有没有词表」——判什么由各仓自己决定,机制面只管
	// 「登记了就得守住,登记与事实偏离当天即红」。
	WordTables *WordTables `yaml:"word_tables"`

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

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

Policy 是 architecture-policy.yaml 的反序列化结果。

func Load

func Load(path string) (*Policy, error)

Load 读取并解析一份 policy 文件。

解析失败一律响亮失败(返回 error),不静默降级:门禁给不出结论却显示成通过, 是这条工具最贵的失败形态。

type ReportOptions

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

ReportOptions 控制报告输出形状。

type Result

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

	// TypeAwarePackages 类型感知严格档(RunOptions.TypeAware)实际类型检查的
	// 包数;0 = 未启用。它是「严格档真的跑了」的凭据——开关开着而本仓有包
	// 目录却计到 0 的形态,RunWithOptions 已显式报错(类型解析失败 ≠ 无违规)。
	TypeAwarePackages int
	// Exceptions 是 policy 登记的例外清单(回显用,让债是显式的)。
	Exceptions []Exception
	// contains filtered or unexported fields
}

Result 是一次门禁运行的结果。

func Run

func Run(root string, pol *Policy) (*Result, error)

Run 对 root 执行全套门禁(默认档,不开类型感知严格档)。

func RunWithOptions added in v0.35.0

func RunWithOptions(root string, pol *Policy, opts RunOptions) (*Result, error)

RunWithOptions 对 root 执行全套门禁,opts 控制可选档。

返回 error 表示门禁**给不出结论**(policy 解析失败、源码解析失败、声明自相矛盾、 严格档类型解析失败)——调用方必须据此非零退出,绝不能当成「无违反」继续。

func (*Result) HasBlocking

func (r *Result) HasBlocking() bool

HasBlocking 报告本次运行是否应当以非零退出码阻断。

阈值门禁只在 enforce 为真时阻断——它是「报告口径」还是「真阈值」由 policy 决定。

type Rule

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"`
}

Rule 是一条正则式规则:匹配面由 scope/include/scope_exclude 圈定,判据由 forbid_regex(源码文本)或 forbid_import_regex(import 路径)给出。

type RuleExample

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

RuleExample 一条规则的样例。

Text 的**判据面**随规则类型而定,与真实判定同构:

  • forbid_regex 规则:Text 是一行源码;
  • forbid_import_regex 规则:Text 是一条 import 路径(不含引号)。

Want 只接受 hit / miss 两个值。**拼写错误必须报错**:把 want 写成 hitt 时 若按「非 hit 即 miss」处理,一条判据彻底坏掉的规则会因为「反例都通过」而绿。

type RuleInfo

type RuleInfo struct {
	ID       string
	Desc     string
	Severity string
}

RuleInfo 是报告用的一条规则元信息(ID、说明、级别)。

为什么单独一个类型:facades 段与 modules 段的规则**不在 rules 段里**, 它们没有 policy 里的 Rule 结构可复用,但报告形状必须一致。

type RunOptions added in v0.35.0

type RunOptions struct {
	// TypeAware 开类型感知严格档(go/packages + go/types,issue #103):
	// 覆盖赋值形态里 AST 追踪静态不可溯的盲区(函数返回值 / 接口断言 /
	// 深层容器流转)。代价是整仓类型检查(慢一个量级),故是 opt-in 档;
	// 类型解析失败显式报错,绝不当作无违规放行(unmanaged_gotypes.go)。
	TypeAware bool
}

Run 对 root 执行全套门禁,返回结果。

返回 error 表示门禁**给不出结论**(policy 解析失败、源码解析失败、声明自相矛盾)—— 调用方必须据此非零退出,绝不能当成「无违反」继续。 RunOptions Run 的可选开关。

type SandboxProvider

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"`
}

SandboxProvider 是 sandbox_providers 段里的一条**档位登记**:一个执行后端 自称提供哪一档隔离。

为什么档位要登记在案,而不是只写在代码里

后端自报的档位若只存在于实现中,它有三重失效:review 时看不见、改了没人会响、 标高了没人管。而档位是宿主做风险判断的依据——宿主据它决定「这次执行能不能 碰不可信输入」。于是档位声明需要一个**签字处**,policy 这一段就是那个签字处。

level 填常量名而不是档位值

填 `LevelProcess` 而不是 `process`:门禁**不能 import 被判的包**(它必须是最 底层的,否则「用它判别人」就变成「它自己也在被判定」,门禁的红绿会依赖它所判 的代码),所以它拿不到档位名表,只能比对代码里可静态识别的那一面——常量名。 policy 侧填同一份常量名,两侧就共用一份真相。

type SandboxProviders

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

SandboxProviders 是 sandbox_providers 段的配置:开关、级别、受忽略目录与登记清单。

形态与 dependency_direction 段同构(配置 + 清单),因为两者都是「一段跨包的 规则 + 一张逐条声明的表」。段缺省即启用——**未登记的后端会被报出来**, 而不是「没登记就当没这回事」。

type SeamLockScan added in v0.43.0

type SeamLockScan struct {
	Enabled *bool `yaml:"enabled"` // 缺省启用
	// Severity 只读扫描的级别(缺省 warn;形态 A 不宜阻断,见文件头)。
	Severity string `yaml:"severity"`
	// Accessors 视为「时钟访问器」的方法名(缺省 now/nowLocked/nowAt/clock)。
	Accessors []string `yaml:"accessors"`
}

SeamLockScan 形态 A 的配置。

type SeamPanicScan added in v0.43.0

type SeamPanicScan struct {
	Enabled  *bool  `yaml:"enabled"` // 缺省启用
	Severity string `yaml:"severity"`
	// GuardedCalls 必须 panic 隔离的宿主调用名(方法/函数名精确匹配)。
	// 清单是增量的:未登记的接缝由形态 B 的标记完备性兜底。
	GuardedCalls []string `yaml:"guarded_calls"`
	// Wrappers 视为「panic 隔离包装器」的调用(缺省 subhub.Do / subhub.Invoke
	// / async.GoSafe / async.RunSafe 等)。
	Wrappers []string `yaml:"wrappers"`
}

SeamPanicScan 形态 C 的配置。

type SeamRules added in v0.43.0

type SeamRules struct {
	// Enabled 段级开关(缺省启用;显式 false 才关)。
	Enabled *bool `yaml:"enabled"`
	// Severity 契约标记门禁的级别(缺省 error;形态 B 零假红,应阻断)。
	Severity string `yaml:"severity"`
	// Marker 可机读标记的前缀(缺省 "@seam:")。
	Marker string `yaml:"marker"`
	// Required 每条接缝标记必须带齐的约束词(缺省 no-reentry + no-blocking)。
	Required []string `yaml:"required"`
	// PanicDispositions panic 处置的取值域:恰出现一个。panic-isolated =
	// 内核隔离;panic-caller = 内核不 recover、由调用方兜(显式第三态)。
	PanicDispositions []string `yaml:"panic_dispositions"`
	// MinDeclarations 最少应枚举到的接缝声明数(缺省 0 = 不判)。本仓设 1:
	// 判定面若因重构/改包而枚举到 0 个,门禁必须响亮失败而不是静默变绿。
	MinDeclarations int `yaml:"min_declarations"`
	// LockScan 形态 A 只读扫描的配置。
	LockScan *SeamLockScan `yaml:"lock_scan"`
	// PanicScan 形态 C panic 外溢检测的配置。
	PanicScan *SeamPanicScan `yaml:"panic_scan"`
}

SeamRules 是 seams 段的声明面。

type TenantGate added in v0.38.0

type TenantGate struct {
	Enabled  *bool  `yaml:"enabled"`
	Severity string `yaml:"severity"`
	Desc     string `yaml:"desc"`

	// Roots 是服务层扫描面(相对仓根,递归)。
	Roots []string `yaml:"roots"`
	// TenantTypeRoots 是租户类型推导面;缺省(空)= Roots。
	TenantTypeRoots []string `yaml:"tenant_type_roots"`
	// AuthContextTypes 授权上下文类型名。可写限定名(pkg.Actor)或裸名(Actor)。
	// 限定名按**源级限定符**匹配,并解析 import 别名(`import a ".../pkg"`
	// 后的 a.Actor 仍算 pkg.Actor)——改名别名绕不过去。
	AuthContextTypes []string `yaml:"auth_context_types"`
	// TenantFields 租户域字段名:struct 含任一字段即租户域类型。
	TenantFields []string `yaml:"tenant_fields"`
	// FilterColumns 查询过滤列名(Where/Raw 的字符串字面量包含其一即证据)。
	FilterColumns []string `yaml:"filter_columns"`
	// SharedSurfaces 共享隔离判定面登记表(调用证据 + 存在性核对)。
	SharedSurfaces []TenantSharedSurface `yaml:"shared_surfaces"`
	// TenantTablesManifest 租户表登记面清单(issue #177):相对仓根的文本
	// 文件,每行一个物理表名(`#` 起行为注释)。声明后启用判据 4-6:执行体
	// 把模型面推导出的租户表集合与清单做**双向**核对(缺登记 / 登记漂移),
	// 并要求每个租户域类型有可解析的表名方法。空 = 只跑判据 1-3。
	TenantTablesManifest string `yaml:"tenant_tables_manifest"`
	// TableNameMethod 物理表名解析方法名(缺省 TableName,GORM 惯例)。
	// 只影响判据 6 与登记面集合的推导。
	TableNameMethod string `yaml:"table_name_method"`
}

TenantGate 是租户过滤漏拼门(issue #172)的声明面。

形状(哪些类型算授权上下文、哪些字段算租户域、共享判定面清单)由宿主 policy 声明;执行体是通用 AST 分析。内核代码里不得出现宿主租户字面—— 它们只出现在这份 policy 里。

六条判据(issue #177 补齐到 6,与 bianque tenantcheck 同口径)

  1. tenant-surface-missing-evidence:带授权上下文形参 + 返回租户域类型的 函数必须有隔离判定证据(调用登记的共享判定面 / 查询条件含过滤列 / 显式 `// tenant:iso <理由>`);三者皆无 = 红。
  2. viewer-dropped:带授权上下文形参却完全不用 = 红。
  3. shared-surface-missing:登记在册的共享判定面在代码里不存在 = 清单漂移 = 红。

后三条是**租户表登记面**判据(bianque 的 RLS 登记面),声明 tenant_tables_manifest 后启用;不声明则只跑前三条:

  1. tenant-policy-missing:含租户字段的模型映射出的物理表不在清单里 = 红 (漏登记 = 隔离策略不覆盖这张表)。
  2. tenant-policy-drift:清单登记的表在模型面已不存在 = 红(登记漂移 = 空登记)。双向核对,清单与模型面谁走了谁都不行。
  3. tenant-table-name-missing:含租户字段的模型没有可从 AST 识别的表名 方法(缺省 TableName,可用 table_name_method 配置)= 红——解析不出 物理表名,登记面核对不了这张表。

宿主持有的 RLS 注册表是 Go 符号,执行体调不到;清单是宿主自己 dump 的 产物(或由一条校验测试保证与注册表一致),语义与 shared_surfaces 的 「存在性核对」同族。

租户类型由代码推导

不另立类型清单:扫描 TenantTypeRoots(缺省 = Roots)下所有生产代码, 任何含 TenantFields 中字段名的 struct 都算租户域类型。新增模型自动入面。

type TenantSharedSurface added in v0.38.0

type TenantSharedSurface struct {
	Dir  string `yaml:"dir"`
	Name string `yaml:"name"`
	Note string `yaml:"note"`
}

TenantSharedSurface 是一条登记在册的共享租户隔离判定面。

Dir 是相对仓根的目录,Name 是函数/方法名。执行体做两件事:

  • 调用点匹配(服务层做隔离判定时走这些面);
  • 存在性核对(Dir 下必须有同名 FuncDecl,否则清单漂移 = 红)。

type Threshold

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=仅报告
}

Threshold 是结构债阈值:超长文件与 god object 的机械判据。

type Violation

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

Violation 是一处违反。

func CheckDependencyDirection

func CheckDependencyDirection(root string, pol *Policy) ([]Violation, error)

type WordTable added in v0.44.0

type WordTable struct {
	// Kind 词表类别(缺省 decision):decision = 取值决定结论;
	// input = 取值只是输入词形(消费方不判,主人与出口受判)。
	Kind string `yaml:"kind"`
	// Pkg 是这张表的**主人包**(相对仓库根的包目录)。
	Pkg string `yaml:"pkg"`
	// Backing 是承载取值的那张表(包级变量名,值是 map 字面量)。
	//
	// 取值 = 这张 map 的**键**:键是常量名,取值在常量声明里,且常量
	// 声明可能是**跨包别名**(statemachine 的 StatusCreated =
	// contract.StatusCreated)——解析要能追过去,否则派生不出取值,
	// 门禁会「一条都判不了却照常报绿」。
	Backing string `yaml:"backing"`
	// Enum 是这张表的**导出枚举出口**(包级函数名,返回切片)。
	//
	// 缺省 Backing 时,取值来源就是它返回的切片字面量。
	// 有 Backing 时,它**必须读同一张表**——读别的 map 就是第二个真相源。
	Enum string `yaml:"enum"`
	// Predicate 是这张表的**判定谓词**(主人包里的包级函数或方法)。
	//
	// 为什么要有这一面:枚举出口读同一张表,只保证「表 ↔ 出口」不漂;
	// 而**判定面**(IsKnownStatus / Valid 这类)是另一个独立读表的地方——
	// 它若另抄一份清单,判定就会与词表分叉,而没有任何判据会红。
	//
	// 声明了就必须守住:谓词不存在、或它不读登记的那张表 ⇒ 当天即红。
	// 没声明 = 这张表没有登记判定面(不判),故宿主要守住自己的判定面
	// 就得在这里写上它——**声明面靠 policy,不靠自觉**。
	//
	// 形态:包级函数写函数名(IsKnownStatus);方法写类型名.方法名
	// (StepStatus.Valid)。
	Predicate string `yaml:"predicate"`
	// Normalizer 是这张表的**输入归一出口**(仅 kind: input 有意义):
	// 把任意输入词形归一到档位/规范形态的**导出**函数。
	//
	// 为什么输入归一词表必须有它:没有归一出口,消费方只能**自己**判这个词形
	// ——于是同一个输入词在不同消费方得到不同结论,而这正是本段门禁
	// 要防的漂移(只是发生在输入侧而不是判定侧)。
	//
	// 判据:必须**导出**(宿主要用它;未导出的函数等于没有出口)、
	// 且必须读登记的那张表(归一到哪一档由那张表说了算;另抄一份清单
	// 就是第二个真相源)。
	Normalizer string `yaml:"normalizer"`
	// Family 是这张表的**族前缀**:主人包里名字以它开头的、取值可解析为
	// 非空字符串的常量,都属于这张表。
	//
	// 为什么要有这一面:取值派生只有「表 → 取值」一个方向。主人包**新增**一个
	// 同族常量却忘了加进表 ⇒ 那个新取值的消费侧从此没人管(它不在表里 ⇒
	// 手抄判据判不到它;它不在枚举出口里 ⇒ 宿主看不到它)。
	//
	// 为什么用「前缀」而不是「列出常量名」:列出常量名就是**第二份会漂的真相**
	// ——policy 里抄一份清单,清单自己会漂,而它漂的方向恰好是「门禁判的和
	// 代码跑的不是一套词表」。前缀是**形状**声明,与 backing / enum / predicate 同类。
	Family FamilyPrefixes `yaml:"family"`
	// FamilyExclude 是族内**有意不进这张表**的一段常量(按前缀豁免)。
	//
	// ⚠️ **已废弃**(第十四阶段):族归属改由「各表自己声明前缀 + 最长匹配
	// 前缀优先」派生(见 wordtable_family_owner.go)⇒ 同一族里另一张表的
	// 常量**不再**需要逐段手写豁免:那张表(或那张未登记的表)声明自己拥有
	// 的前缀即可。仍写这个字段 ⇒ 自校验当天即红,并写明怎么改。
	//
	// 为什么保留字段而不是直接删:宿主仓的 policy 里可能还有这段;删字段会
	// 让它们的 policy **静默**失效(yaml 忽略未知字段)⇒ 保留字段 + 自校验
	// 报红,才是「响亮地要求迁移」。
	FamilyExclude []WordTableFamilyExclude `yaml:"family_exclude"`
	// Desc 是给人看的那一句。
	Desc string `yaml:"desc"`
}

WordTable 是一张登记的判定词表。

type WordTableAnchor added in v0.46.0

type WordTableAnchor struct {
	// Pkg 是锚点常量所在包(必须等于该端表的主人包)。
	Pkg string `yaml:"pkg"`
	// Const 是锚点常量名(主人包里的包级常量)。
	Const string `yaml:"const"`
	// All 表示「这一端锚住两端**共有**的全部取值」(all 形态)。
	//
	// 为什么要有它:抽样锚定只钉住一两个取值,其余共有取值漂了要靠族覆盖 /
	// 派生漂移判据兜 ⇒ 关系「说谎」在那部分取值上没人判。All 把锚点从
	// 「抽样」升级成「覆盖全部同形取值」——而这不是新机制:它只是把
	// **锚点取值集合**换成「两张表的共有取值集合」,四条判据原样复用。
	//
	// 为什么形态是 `[{all: true}]` 而不是台账草稿里的 `a: all`:锚点列表是
	// **导出字段**([]WordTableAnchor),要支持标量就得换成一个自定义
	// UnmarshalYAML 的新类型 ⇒ 宿主构造该结构的代码会编译不过(拿破坏性
	// 变更换两个字符的写法,不划算)。形态统一 > 少写两个字符。
	All bool `yaml:"all"`
}

WordTableAnchor 是关系上的一个**锚点**:关系锚定的那个具体常量。

type WordTableAnchors added in v0.46.0

type WordTableAnchors struct {
	// A 是第一张表(a 端)的锚点。
	A []WordTableAnchor `yaml:"a"`
	// B 是第二张表(b 端)的锚点。
	B []WordTableAnchor `yaml:"b"`
}

WordTableAnchors 是一条关系两端各自的锚点列表。

type WordTableFamilyExclude added in v0.44.0

type WordTableFamilyExclude struct {
	// Prefix 是豁免的常量名前缀(写全名则只豁免那一个)。
	Prefix string `yaml:"prefix"`
	// Reason 是豁免理由(**必填**):没有理由的豁免等于让那族常量重新变成
	// 「没人管的真相」——与 exceptions 段同款纪律。
	Reason string `yaml:"reason"`
}

WordTableFamilyExclude 族内一段「有意不进这张表」的常量豁免。

type WordTableNotRegistered added in v0.44.0

type WordTableNotRegistered struct {
	// Subject 是这张表的**身份**(哪张表:包 + 表名 + 取值集)。
	Subject string `yaml:"subject"`
	// Reason 是**不登记的理由**(必填):理由要写「为什么不登记」,
	// 而不是「暂时没排上」——否则它随时会被当成待办而无人复核。
	Reason string `yaml:"reason"`
	// Pkg 是这张(未登记的)表所在的包——**归属派生**要靠它把前缀认到包里。
	//
	// 为什么未登记的表也要声明归属:一张表不登记(不判手抄),不代表它的
	// 常量可以**没人管**——那些常量仍会被同包另一张表的族前缀命中,若不
	// 声明归属,族覆盖判据就会把它们算成「漏进表」(假红)。
	Pkg string `yaml:"pkg"`
	// Prefixes 是这张(未登记的)表**自己拥有**的常量名前缀。
	//
	// 为什么它也算「归属声明」:族归属按**最长匹配前缀**派生(见
	// wordtable_family_owner.go)⇒ 一张表哪怕不登记,只要声明了自己拥有
	// 的前缀,那段常量就不必再由别的表逐段手写豁免。
	Prefixes FamilyPrefixes `yaml:"prefixes"`
}

WordTableNotRegistered 一张**有意不登记**的判定词表候选。

type WordTableRef added in v0.45.0

type WordTableRef struct {
	Pkg  string `yaml:"pkg"`
	Enum string `yaml:"enum"`
}

WordTableRef 是一张登记词表的**引用**(主人包 + 导出枚举出口)。

为什么用枚举出口而不是表名:枚举出口是每张表**唯一**的对外身份 (一个包里有多张表时,pkg 不足以区分它们)。

type WordTableRelation added in v0.45.0

type WordTableRelation struct {
	// A 是第一张表(主人包 + 导出枚举出口)。
	A WordTableRef `yaml:"a"`
	// B 是第二张表(主人包 + 导出枚举出口)。
	B WordTableRef `yaml:"b"`
	// Relation 是同形取值的语义关系:same(同一概念)/ distinct(不同概念)。
	Relation string `yaml:"relation"`
	// Anchors 把这条关系锚到**具体常量**上(可选)。
	//
	// 为什么要有:关系本身是**人写的事实**(「会话失败 ≠ 任务失败」是人判的)。
	// 主人包若改了某个取值的**含义**(不是拼写),关系不会跟着变 ⇒ 一条
	// **说谎**的关系会安静地留着。锚点让四条原本没人判的事实当天即红:
	// 锚点常量改名/被删、锚点取值不再属于它那张表、两端锚定取值不成对、
	// distinct 的两端锚点解析到同一处声明。
	//
	// 为什么是**可选**:键是字面量、根本没有常量可锚的表写不出锚点;
	// 强制要求会把那种表逼成「登记不进来」(门禁逼人造假比没有锚点更坏)。
	// 但**半边锚点没有配对语义** ⇒ 要写就两端都写(自校验当天即红)。
	Anchors *WordTableAnchors `yaml:"anchors"`
}

WordTableRelation 是两张登记词表之间的**同形关系**声明。

type WordTables added in v0.44.0

type WordTables struct {
	// Enabled 段级开关(缺省启用;显式 false 才关)。
	Enabled *bool `yaml:"enabled"`
	// Severity 两条判据的级别(缺省 error)。
	Severity string `yaml:"severity"`
	// Desc 是给人看的那一句。
	Desc string `yaml:"desc"`
	// IgnoreDirs 不参与手抄判定的目录(相对仓库根;含子目录)。
	//
	// 为什么需要它:这条门禁的判定面是「仓里所有包」,而某些目录
	// (参考实现、命令装配层)天然会把词表取值写进数据面而不是判定面。
	// 豁免必须**显式登记**并写明理由——静默跳过等于让该目录重新变成
	// 「没人管的真相」。
	IgnoreDirs []string `yaml:"ignore_dirs"`
	// Tables 登记的词表清单。
	Tables []WordTable `yaml:"tables"`
	// Relations 是**同形取值的两张表之间的关系**声明。
	//
	// 为什么需要它:同一个拼写可能是多张判定词表的取值,而它们的**含义**
	// 可能相同也可能不同(contract 的 "failed" 是会话失败、taskboard 的
	// "failed" 是任务失败)。手抄判据只按「值在不在表里」判 ⇒ 它分不出
	// 「这处字面量想说的是哪张表」⇒ 修法文案若只指向某一张表,就可能把人
	// 引到**错误的概念**上(把任务失败改成引用会话失败常量 = 语义损坏)。
	//
	// ⇒ 凡两张登记的**判定词表**有同形取值,必须在这里显式声明关系:
	//   - same     :同一概念(一张表的别名/子集),引用任一家都对;
	//   - distinct :不同概念(同形只是拼写巧合),手抄方必须**在本包命名**。
	//
	// 为什么用**中心清单**而不是各表自己声明:关系是**两张表之间**的事,
	// 写在任一方都会引出「两边都声明了但不一致」的第三种状态。
	Relations []WordTableRelation `yaml:"relations"`
	// NotRegistered 是**有意不登记**的判定词表候选清单。
	//
	// 为什么要有它:登记面是稀疏的,而稀疏本身没人记——「这张表我们决定
	// 不登记」这句话若只留在某个人的脑子里,下一个人会重新调研一遍,
	// 甚至直接把它登记进去(把几十处假阳引进门禁)。
	// 不登记也要留痕,与 exceptions 段同款纪律。
	NotRegistered []WordTableNotRegistered `yaml:"not_registered"`
}

WordTables 是 word_tables 段的配置。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL