Documentation
¶
Overview ¶
Package ledgerstatus 从演进台账文档派生「单号 → 状态」。
生命周期: Experimental(v0.47.0 定级)——internal 内部件,Go 可见性规则已挡住 外部引用,无对外兼容承诺;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。
为什么需要它 ¶
台账(docs/DISTRIBUTED-EVOLUTION-*.md)此前只在散文里记「这条单清了没」, 机器读不出来。代价是台账 §15 形态 (a) 记着的实例:一批单**早已由 8 个 PR 合入主干**,而接手的人按「单还挂着 open 标签」判断「还没人做」, 整条工作树作废。
本包是这条派生的**唯一真相**:门禁(cmd/ledgercheck)与部署清单 (cmd/deploymatrix)都从这里读,谁也不许自己再解析一遍台账—— 第二份解析必然漂移,而漂移的方向恰好是「门禁判的和台账写的不是一套」。
词表与判定面 ¶
台账是 markdown 散文,机器只能靠三处约定:
- 登记列:表头为 单号 / 单 / 已落单 / 结论单 的列——这一列里的 #N 是 **被登记的单号**(台账承认自己在跟这条单);
- 状态列:表头为 状态 的列——这一列给出该行的状态;
- 散文标记:正文行里出现「已合入」「仍开着」时,同行的单号继承该状态。
**PR 引用不是单号**:正文里以 PR 形态出现的 #N(落文档 PR #281、 合并 PR 分布在 #339 / #340)不进单号视图——它是 PR 号,进视图就等于 把两种号混成一种,而两种号撞车时(#331 既是某单的关闭 PR, 又是另一处的单号)合并结果就没有意义了。
parse.go —— 台账文本的容错解析。
解析口径全在这一份里:判据(cmd/ledgercheck)只消费本包派生出的事实, 不自己再读一遍 markdown——两处各读一遍,结论就会分叉,而分叉的方向 恰好是「门禁判的和台账写的不是一套」。
Index ¶
Constants ¶
const DefaultPath = "docs/DISTRIBUTED-EVOLUTION-20261117.md"
DefaultPath 本仓台账的默认路径(相对仓库根)。
放在包里而不是各命令各写一份:路径也是会漂的真相,抄两遍就等着它漂。
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Entry ¶
type Entry struct {
// Number 单号(不含 #)。
Number int
// Status 合并后的状态(口径见 Ledger.Status)。
Status Status
// ClosingPR 合并后的关闭 PR 号(0 = 没有)。
ClosingPR int
// Registered 该单号是否出现在登记面(登记表的登记列里)。
Registered bool
// Occurrences 全部出现点,按出现顺序。
Occurrences []Occurrence
}
Entry 一个单号在台账里的合并视图。
type Ledger ¶
type Ledger struct {
// contains filtered or unexported fields
}
Ledger 台账派生出的单号视图。
func (*Ledger) ClosingPR ¶
ClosingPR 返回关闭该单的 PR 号(没有则 ok=false)。
只认形如 #N 的原文;不合法的原文不进这里(它由门禁当违反报出来)。
type Occurrence ¶
type Occurrence struct {
// Number 单号(不含 #)。
Number int
// File 出现所在文件。
File string
// Line 出现所在行(1 起)。
Line int
// Kind 出现点性质。
Kind OccurrenceKind
// Status 该出现点**自带**的状态声明;StatusUnknown 表示此处没有声明
//(此时不代表该单仍开着,只代表这一处没说话)。
Status Status
// ClosingRef 该出现点声明的关闭 PR 号**原文**(形如 "#331")。
//
// 存原文而不是数字是有意的:判据「关闭 PR 号必须形如 #N」要判的就是
// 这个原文——解析时就把不合法的号丢掉,门禁就永远看不到它。
ClosingRef string
// Text 出现点的原始文本(截断)。
Text string
}
Occurrence 单号在台账里的一次出现。
type OccurrenceKind ¶
type OccurrenceKind string
OccurrenceKind 出现点的性质。
const ( // OccurrenceRegistry 登记点:登记表里登记该单号的那一行。 OccurrenceRegistry OccurrenceKind = "registry" // OccurrenceReference 引用点:正文里提到该单号(散文,或表格的非登记列)。 OccurrenceReference OccurrenceKind = "reference" )
type Problem ¶
type Problem struct {
// File 问题所在文件。
File string
// Line 问题所在行(1 起;0 = 不定位到行)。
Line int
// Kind 问题类别。
Kind ProblemKind
// Message 人可读说明。
Message string
}
Problem 台账自身的一处结构问题(指到文件与行)。
type ProblemKind ¶
type ProblemKind string
ProblemKind 台账结构问题的类别。
const ( // ProblemTableShape 表格形状不对(列数与表头不齐等)。 ProblemTableShape ProblemKind = "table_shape" )