@longzai-intelligence-debts/ledger 0.0.0-stage → 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,861 @@
+import "./rolldown-runtime-BqT_7tdF.js";
+import { LziDebtsConfig } from "@longzai-intelligence-debts/config";
+/**
+ * 注册表目录扫描工具
+ *
+ * fs 编排层，读侧统一入口：lint、index check 与 list 共用本扫描，文件枚举
+ * 口径单一
+ */
+/**
+ * 扫描到的注册表条目
+ */
+type ScannedDebt = {
+  /**
+   * 文件基名
+   *
+   * @remarks
+   *   含扩展名
+   */
+  basename: string;
+  /**
+   * 编号键
+   *
+   * @remarks
+   *   数字字符串原样，宽口径非编号形态为 null
+   */
+  key: string | null;
+  /**
+   * 绝对路径
+   */
+  absPath: string;
+};
+/**
+ * 扫描注册表目录
+ *
+ * @remarks
+ *   仅 `.md` 文件，按编号键升序，目录不存在返回空数组
+ * @param dirAbs - 注册表目录绝对路径
+ * @returns 扫描条目列表
+ */
+declare function scanDebtsDir(dirAbs: string): ScannedDebt[];
+/**
+ * debts README 索引差量核
+ *
+ * 只查不写。索引行人工登记、工具只检查不写入，与 decision 项目 index 先例
+ * 同款裁定。判定三态：缺行即文件在而索引无、多行即索引有而文件无、slug 漂
+ * 移即索引链接 slug 与实际文件 slug 不一致。报文附期望行供人工粘贴
+ *
+ * @remarks
+ *   debts 索引方言为四列表格行，列为编号、标题、类型、状态。类型与状态是
+ *   技术债的首要追踪维度，表格行承载两列。链接引用提取复用 docs 平台
+ *   registry-index 宽口径工厂，表格单元格内的链接天然可匹配
+ */
+/**
+ * 索引差量发现条目
+ */
+type IndexCheckFinding = {
+  /**
+   * 发现类别
+   *
+   * @remarks
+   *   readme-missing 即 README 未建、missing 即缺行、stale 即多行、
+   *   slug-drift 即 slug 漂移
+   */
+  kind: 'readme-missing' | 'missing' | 'stale' | 'slug-drift';
+  /**
+   * 相关文件
+   *
+   * @remarks
+   *   posix 相对注册表目录
+   */
+  file: string;
+  /**
+   * 发现消息
+   */
+  message: string;
+};
+/**
+ * 索引差量结果
+ */
+type IndexCheckResult = {
+  /**
+   * 新鲜判定
+   *
+   * @remarks
+   *   无任何发现
+   */
+  ok: boolean;
+  /**
+   * 发现列表
+   */
+  findings: IndexCheckFinding[];
+  /**
+   * 期望索引行列表
+   *
+   * @remarks
+   *   供人工粘贴
+   */
+  expectedLines: string[];
+  /**
+   * 注册表文件数
+   */
+  fileCount: number;
+  /**
+   * 索引引用数
+   */
+  indexedCount: number;
+};
+/**
+ * 索引差量入参
+ */
+type IndexCheckInput = {
+  /**
+   * 注册表目录绝对路径
+   */
+  registryDirAbs: string;
+};
+/**
+ * 索引表行渲染入参
+ */
+type IndexTableRowInput = {
+  /**
+   * 编号
+   */
+  number: string;
+  /**
+   * 标题
+   */
+  title: string;
+  /**
+   * 链接目标文件基名
+   */
+  target: string;
+  /**
+   * 债务类型中文名
+   */
+  typeLabel: string;
+  /**
+   * 状态中文名
+   */
+  statusLabel: string;
+};
+/**
+ * 渲染索引表行
+ *
+ * @param input - 索引表行渲染入参
+ * @returns 索引表行全文
+ */
+declare function renderIndexTableRow(input: IndexTableRowInput): string;
+/**
+ * 运行索引差量检查
+ *
+ * @remarks
+ *   只读，本函数不写任何文件
+ * @param input - 检查入参
+ * @returns 差量结果
+ */
+declare function runIndexCheck(input: IndexCheckInput): IndexCheckResult;
+/**
+ * lint 违例条目
+ */
+type DebtsLintViolation = {
+  /**
+   * 规则名
+   */
+  rule: string;
+  /**
+   * 文件
+   *
+   * @remarks
+   *   posix 相对仓库根
+   */
+  file: string;
+  /**
+   * 行号
+   *
+   * @remarks
+   *   1 起算
+   */
+  line: number;
+  /**
+   * 违例消息
+   */
+  message: string;
+};
+/**
+ * lint 结果
+ */
+type DebtsLintResult = {
+  /**
+   * 基线豁免后的违例列表
+   */
+  violations: DebtsLintViolation[];
+  /**
+   * 扫描文件数
+   */
+  fileCount: number;
+  /**
+   * 基线豁免命中数
+   *
+   * @remarks
+   *   棘轮观测面
+   */
+  exemptedCount: number;
+};
+/**
+ * lint 入参
+ */
+type DebtsLintInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+  /**
+   * 解析后配置
+   */
+  config: LziDebtsConfig;
+};
+/**
+ * 运行 lint
+ *
+ * @remarks
+ *   全 scope 注册表，只读
+ * @param input - lint 入参
+ * @returns lint 结果，违例空列表为通过
+ */
+declare function runDebtsLint(input: DebtsLintInput): DebtsLintResult;
+/**
+ * debt 文档解析器
+ *
+ * 判定全部基于本解析器产物，口径单一真源在 format.utils。解析头部即 H1
+ * 与 blockquote 元数据行全集，另扫描正文固定节命中次序与第四节内容，供
+ * lint 的节结构与收口一致性规则和 settle 的占位拦截消费
+ */
+/**
+ * 解析后的 debt 头部与正文结构
+ */
+type ParsedDebt = {
+  /**
+   * H1 编号
+   *
+   * @remarks
+   *   数字字符串原样
+   */
+  number: string;
+  /**
+   * H1 标题
+   */
+  title: string;
+  /**
+   * 债务类型中文名
+   *
+   * @remarks
+   *   行缺席为 null，词表判定归 lint
+   */
+  typeLabel: string | null;
+  /**
+   * 记录日期
+   *
+   * @remarks
+   *   YYYY-MM-DD
+   */
+  date: string | null;
+  /**
+   * 状态中文名
+   *
+   * @remarks
+   *   行缺席为 null，词表判定归 lint
+   */
+  statusLabel: string | null;
+  /**
+   * 来源
+   */
+  source: string | null;
+  /**
+   * 关联
+   *
+   * @remarks
+   *   可选行缺席为 null
+   */
+  ref: string | null;
+  /**
+   * 清偿日期
+   *
+   * @remarks
+   *   YYYY-MM-DD，行缺席为 null
+   */
+  settleDate: string | null;
+  /**
+   * 清偿记录
+   *
+   * @remarks
+   *   指向操作细节正本，行缺席为 null
+   */
+  settleRecord: string | null;
+  /**
+   * 豁免日期
+   *
+   * @remarks
+   *   YYYY-MM-DD，行缺席为 null
+   */
+  waiveDate: string | null;
+  /**
+   * 豁免理由
+   *
+   * @remarks
+   *   行缺席为 null
+   */
+  waiveReason: string | null;
+  /**
+   * 头部元数据结束行号
+   *
+   * @remarks
+   *   1 起算，正文起始参考
+   */
+  headerEndLine: number;
+  /**
+   * 状态行行号
+   *
+   * @remarks
+   *   0 表示状态行缺席，settle 与 waive 翻态定位用
+   */
+  statusLineIndex: number;
+  /**
+   * 正文固定节命中次序
+   *
+   * @remarks
+   *   元素为节下标即 0 至 3，按出现次序记录，缺席节不出现
+   */
+  sectionHits: number[];
+  /**
+   * 第四节正文内容
+   *
+   * @remarks
+   *   节头与下一节头或文末之间的非空行拼接，节缺席或全空为 null
+   */
+  settleSectionContent: string | null;
+};
+/**
+ * 解析问题条目
+ */
+type DebtParseIssue = {
+  /**
+   * 行号
+   *
+   * @remarks
+   *   1 起算，0 为全文级
+   */
+  line: number;
+  /**
+   * 问题消息
+   */
+  message: string;
+};
+/**
+ * 解析结果
+ */
+type DebtParseResult = {
+  /**
+   * 解析后的头部与正文结构
+   *
+   * @remarks
+   *   H1 非法时为 null
+   */
+  debt: ParsedDebt | null;
+  /**
+   * 解析问题列表
+   *
+   * @remarks
+   *   空列表为合法建档态
+   */
+  issues: DebtParseIssue[];
+};
+/**
+ * 解析 debt 文档全文
+ *
+ * @param content - 文档全文
+ * @returns 解析结果。骨架建档态即占位值可解析且无问题
+ */
+declare function parseDebtDoc(content: string): DebtParseResult;
+/**
+ * 正文固定节扫描结果
+ */
+type SectionScanResult = {
+  /**
+   * 节命中次序
+   */
+  sectionHits: number[];
+  /**
+   * 第四节正文内容
+   *
+   * @remarks
+   *   节缺席或全空为 null
+   */
+  settleSectionContent: string | null;
+};
+/**
+ * debts 格式口径单一真源
+ *
+ * 全部格式口径即文件名形态、H1 形态、头部元数据行、债务类型与状态词表、
+ * 正文固定节、占位符集中于此模块。读侧解析器、lint 与索引差量和写侧模板
+ * 渲染共用同一真源，杜绝两套口径漂移，create 产物在构造上天然通过 lint。
+ * slug 段消费 docs 平台共享基础模块的编号域源串，全族同源
+ *
+ * @remarks
+ *   debts 定位：语义分型技术债注册表。与 records 的无分型通道不同，本域
+ *   头部元数据带类型与状态两个词表维度，正文带固定四节结构，生命周期翻态
+ *   仅经 settle 与 waive 两条通道
+ */
+/**
+ * 文件名形态
+ *
+ * @remarks
+ *   编号 3-4 位零填充加编号域宽收集 slug 加 `\.md`
+ */
+declare const DEBT_FILENAME_PATTERN: RegExp;
+/**
+ * slug 合法形态
+ *
+ * @remarks
+ *   编号域宽收集 ASCII kebab，与全族共享基础同源，允许数字
+ */
+declare const ASCII_KEBAB_SLUG_PATTERN: RegExp;
+/**
+ * H1 形态
+ *
+ * @remarks
+ *   编号入 H1，em dash 分隔，产品群编号注册表主流形态
+ */
+declare const DEBT_H1_PATTERN: RegExp;
+/**
+ * 债务类型行形态
+ *
+ * @remarks
+ *   blockquote 元数据行，值为类型中文名
+ */
+declare const TYPE_LINE_PATTERN: RegExp;
+/**
+ * 记录日期行形态
+ *
+ * @remarks
+ *   blockquote 元数据行，YYYY-MM-DD
+ */
+declare const DATE_LINE_PATTERN: RegExp;
+/**
+ * 状态行形态
+ *
+ * @remarks
+ *   blockquote 元数据行，值为状态中文名
+ */
+declare const STATUS_LINE_PATTERN: RegExp;
+/**
+ * 来源行形态
+ *
+ * @remarks
+ *   blockquote 元数据行，非空
+ */
+declare const SOURCE_LINE_PATTERN: RegExp;
+/**
+ * 关联行形态
+ *
+ * @remarks
+ *   blockquote 元数据行，可选，非空
+ */
+declare const REF_LINE_PATTERN: RegExp;
+/**
+ * 清偿日期行形态
+ *
+ * @remarks
+ *   blockquote 元数据行，仅已清偿债在场，YYYY-MM-DD
+ */
+declare const SETTLE_DATE_LINE_PATTERN: RegExp;
+/**
+ * 清偿记录行形态
+ *
+ * @remarks
+ *   blockquote 元数据行，已清偿债可选，指向操作细节正本
+ */
+declare const SETTLE_RECORD_LINE_PATTERN: RegExp;
+/**
+ * 豁免日期行形态
+ *
+ * @remarks
+ *   blockquote 元数据行，仅已豁免债在场，YYYY-MM-DD
+ */
+declare const WAIVE_DATE_LINE_PATTERN: RegExp;
+/**
+ * 豁免理由行形态
+ *
+ * @remarks
+ *   blockquote 元数据行，仅已豁免债在场，非空
+ */
+declare const WAIVE_REASON_LINE_PATTERN: RegExp;
+/**
+ * 头部元数据键：债务类型
+ */
+declare const TYPE_LINE_KEY = "债务类型";
+/**
+ * 头部元数据键：记录日期
+ */
+declare const DATE_LINE_KEY = "记录日期";
+/**
+ * 头部元数据键：状态
+ */
+declare const STATUS_LINE_KEY = "状态";
+/**
+ * 头部元数据键：来源
+ */
+declare const SOURCE_LINE_KEY = "来源";
+/**
+ * 头部元数据键：关联
+ */
+declare const REF_LINE_KEY = "关联";
+/**
+ * 头部元数据键：清偿日期
+ */
+declare const SETTLE_DATE_LINE_KEY = "清偿日期";
+/**
+ * 头部元数据键：清偿记录
+ */
+declare const SETTLE_RECORD_LINE_KEY = "清偿记录";
+/**
+ * 头部元数据键：豁免日期
+ */
+declare const WAIVE_DATE_LINE_KEY = "豁免日期";
+/**
+ * 头部元数据键：豁免理由
+ */
+declare const WAIVE_REASON_LINE_KEY = "豁免理由";
+/**
+ * 债务类型键全集
+ *
+ * @remarks
+ *   `create --type` 的封闭枚举，lint 按对应中文名执法
+ */
+declare const DEBT_TYPE_KEYS: readonly ['transition', 'architecture', 'implementation', 'test', 'dependency', 'documentation'];
+/**
+ * 债务类型键
+ */
+type DebtTypeKey = (typeof DEBT_TYPE_KEYS)[number];
+/**
+ * 债务类型中文名正本词表
+ *
+ * @remarks
+ *   键为 ASCII 枚举供命令行消费，值为头部元数据行与索引表的中文名。
+ *   transition 过渡债：过渡期措施即双轨回落锚点与兼容垫片，所有过渡
+ *   措施必须立档，清偿路径节必须写明退役判据。architecture 架构债：
+ *   分层越界、所有权错位、拓扑简化。implementation 实现债：已知次优
+ *   实现。test 测试债：关键路径缺测或测试薄弱。dependency 依赖债：
+ *   钉版、过期、重复依赖。documentation 文档债：文档缺失或与实现漂移
+ */
+declare const CANONICAL_DEBT_TYPE_LABELS: Record<DebtTypeKey, string>;
+/**
+ * 债务状态键全集
+ */
+declare const DEBT_STATUS_KEYS: readonly ['open', 'settled', 'waived'];
+/**
+ * 债务状态键
+ */
+type DebtStatusKey = (typeof DEBT_STATUS_KEYS)[number];
+/**
+ * 债务状态中文名正本词表
+ *
+ * @remarks
+ *   open 未清偿：债在册待偿付。settled 已清偿：经 settle 翻态，须回填
+ *   清偿日期与第四节清偿记录。waived 已豁免：经 waive 翻态，须携带
+ *   豁免日期与豁免理由，理由须含用户裁定
+ */
+declare const CANONICAL_DEBT_STATUS_LABELS: Record<DebtStatusKey, string>;
+/**
+ * 正文固定节键全集
+ *
+ * @remarks
+ *   次序即规范位次，一背景、二债务事实、三清偿路径、四清偿记录
+ */
+declare const SECTION_KEYS: readonly ['背景', '债务事实', '清偿路径', '清偿记录'];
+/**
+ * 正文固定节序数前缀
+ */
+declare const SECTION_ORDINALS: readonly ['一', '二', '三', '四'];
+/**
+ * 正文固定节头形态全集
+ *
+ * @remarks
+ *   下标与 `SECTION_KEYS` 对位，`## 一、背景` 形态
+ */
+declare const SECTION_HEADER_PATTERNS: readonly RegExp[];
+/**
+ * 正文前三节占位符
+ *
+ * @remarks
+ *   建档即骨架，内容随立档回填
+ */
+declare const SECTION_PLACEHOLDER = "待补充";
+/**
+ * 第四节占位符
+ *
+ * @remarks
+ *   收口即 settle 与 waive 前必须替换为实文，settle 门禁拦截占位收口
+ */
+declare const SETTLE_SECTION_PLACEHOLDER = "待收口后回填";
+/**
+ * 索引链接模式
+ *
+ * @remarks
+ *   README 索引表单元格中的注册表文件链接，消费 docs 平台
+ *   registry-index 基础模块的宽口径工厂。编号域方言，比对锚为链接
+ *   目标即编号加 slug，链接文本形态宽容，表格单元格内的链接天然可匹配
+ */
+declare const INDEX_LINK_PATTERN: RegExp;
+/**
+ * 正则捕获组安全取值
+ *
+ * @param match - 正则命中结果
+ * @param index - 捕获组下标
+ * @returns 捕获组值
+ * @throws {@link Error} 未命中或捕获组越界，即格式口径与调用侧失配
+ */
+declare function captureGroup(match: RegExpMatchArray | null, index: number): string;
+/**
+ * 从文件名提取编号键
+ *
+ * @param basename - 文件基名
+ * @returns 编号键即数字字符串原样，非编号形态为 null
+ */
+declare function extractDebtKey(basename: string): string | null;
+/**
+ * 判定日期字符串是否为真实存在的日历日期
+ *
+ * @param date - 日期字符串
+ * @returns 真实日历日期为 true
+ */
+declare function isRealCalendarDate(date: string): boolean;
+/**
+ * 按中文名反查债务类型键
+ *
+ * @param label - 类型中文名
+ * @returns 命中的类型键，未命中为 null
+ */
+declare function debtTypeKeyFromLabel(label: string): DebtTypeKey | null;
+/**
+ * 按中文名反查债务状态键
+ *
+ * @param label - 状态中文名
+ * @returns 命中的状态键，未命中为 null
+ */
+declare function debtStatusKeyFromLabel(label: string): DebtStatusKey | null;
+/**
+ * 债务状态翻转核
+ *
+ * settle 清偿与 waive 豁免共用的翻态内核：翻状态行值、在状态行后追加收口
+ * 元数据行。幂等守卫即目标态已达成时零变更返回，状态行零命中即拒绝假翻态。
+ * settle 前置门禁拦截占位收口，第四节清偿记录仍为占位时拒绝清偿，先回填
+ * 证据再收口。waive 理由强制含用户裁定，非裁定不得豁免
+ */
+/**
+ * 翻转成功结果
+ */
+type FlipSuccess = {
+  /**
+   * 成功标记
+   */
+  ok: true;
+  /**
+   * 翻转后全文
+   *
+   * @remarks
+   *   幂等零变更时为原文
+   */
+  content: string;
+  /**
+   * 是否发生变更
+   *
+   * @remarks
+   *   幂等命中为 false
+   */
+  changed: boolean;
+};
+/**
+ * 翻转失败结果
+ */
+type FlipFailure = {
+  /**
+   * 成功标记
+   */
+  ok: false;
+  /**
+   * 失败原因
+   */
+  error: string;
+};
+/**
+ * 翻转结果
+ */
+type FlipOutcome = FlipSuccess | FlipFailure;
+/**
+ * settle 入参
+ */
+type SettleInput = {
+  /**
+   * 债档全文
+   */
+  content: string;
+  /**
+   * 清偿日期
+   *
+   * @remarks
+   *   YYYY-MM-DD
+   */
+  date: string;
+  /**
+   * 清偿记录
+   *
+   * @remarks
+   *   可选，指向操作细节正本
+   */
+  settleRecord?: string;
+};
+/**
+ * 清偿翻态
+ *
+ * @param input - settle 入参
+ * @returns 翻转结果。已清偿债幂等零变更，仅未清偿债可清偿，第四节占位即拒
+ */
+declare function settleDebtDoc(input: SettleInput): FlipOutcome;
+/**
+ * waive 入参
+ */
+type WaiveInput = {
+  /**
+   * 债档全文
+   */
+  content: string;
+  /**
+   * 豁免日期
+   *
+   * @remarks
+   *   YYYY-MM-DD
+   */
+  date: string;
+  /**
+   * 豁免理由
+   */
+  reason: string;
+};
+/**
+ * 豁免翻态
+ *
+ * @param input - waive 入参
+ * @returns 翻转结果。已豁免债幂等零变更，理由须含用户裁定，仅未清偿债可豁免
+ */
+declare function waiveDebtDoc(input: WaiveInput): FlipOutcome;
+/**
+ * instance 模式渲染入参
+ */
+type DebtTemplateValues = {
+  /**
+   * 编号
+   *
+   * @remarks
+   *   3-4 位零填充，编号门禁取号分配
+   */
+  number: string;
+  /**
+   * slug
+   *
+   * @remarks
+   *   ASCII kebab，中文标题须显式 `--slug`
+   */
+  slug: string;
+  /**
+   * 一句话标题
+   */
+  title: string;
+  /**
+   * 债务类型键
+   *
+   * @remarks
+   *   渲染为中文名正本词表值
+   */
+  type: DebtTypeKey;
+  /**
+   * 记录日期
+   *
+   * @remarks
+   *   YYYY-MM-DD
+   */
+  date: string;
+  /**
+   * 来源
+   *
+   * @remarks
+   *   出处与日期
+   */
+  source: string;
+  /**
+   * 关联
+   *
+   * @remarks
+   *   可选，缺席时省略关联行
+   */
+  ref?: string;
+};
+/**
+ * 渲染标准模板骨架
+ *
+ * @remarks
+ *   skeleton 模式，占位符形态，供 template 命令展示与指南活样板消费
+ * @returns 骨架全文，以单个换行结尾
+ */
+declare function renderDebtTemplateSkeleton(): string;
+/**
+ * 渲染标准模板实例
+ *
+ * @remarks
+ *   instance 模式，头部元数据代入实际值，正文保留占位形态，建档即骨架，
+ *   内容随立档与收口回填
+ * @param values - 实际值入参
+ * @returns 可直接落盘的 debt 文档全文，以单个换行结尾
+ */
+declare function renderDebtTemplate(values: DebtTemplateValues): string;
+/**
+ * 渲染注册表 README 格式存根
+ *
+ * @remarks
+ *   init 命令落盘，一页式格式速览：定位、词表、建档与收口、索引纪律。
+ *   索引行人工登记，工具只检查不写入，与 decision 项目 index 先例同款裁定
+ * @param scopeTitle - scope 人类可读名
+ * @returns README 存根全文
+ */
+declare function renderRegistryReadmeStub(scopeTitle: string): string;
+/**
+ * 模板字段说明条目
+ *
+ * @remarks
+ *   template 命令 `--format json` 载荷
+ */
+type TemplateFieldDoc = {
+  /**
+   * 字段名
+   *
+   * @remarks
+   *   渲染入参名或元信息键
+   */
+  name: string;
+  /**
+   * 是否必填
+   */
+  required: boolean;
+  /**
+   * 字段说明
+   */
+  description: string;
+};
+/**
+ * 标准模板字段说明全集
+ *
+ * @remarks
+ *   供 agent 与使用者程序化消费
+ */
+declare const TEMPLATE_FIELDS: readonly TemplateFieldDoc[];
+export { ASCII_KEBAB_SLUG_PATTERN, CANONICAL_DEBT_STATUS_LABELS, CANONICAL_DEBT_TYPE_LABELS, DATE_LINE_KEY, DATE_LINE_PATTERN, DEBT_FILENAME_PATTERN, DEBT_H1_PATTERN, DEBT_STATUS_KEYS, DEBT_TYPE_KEYS, DebtParseIssue, DebtParseResult, DebtStatusKey, DebtTemplateValues, DebtTypeKey, DebtsLintInput, DebtsLintResult, DebtsLintViolation, FlipFailure, FlipOutcome, FlipSuccess, INDEX_LINK_PATTERN, IndexCheckFinding, IndexCheckInput, IndexCheckResult, IndexTableRowInput, ParsedDebt, REF_LINE_KEY, REF_LINE_PATTERN, SECTION_HEADER_PATTERNS, SECTION_KEYS, SECTION_ORDINALS, SECTION_PLACEHOLDER, SETTLE_DATE_LINE_KEY, SETTLE_DATE_LINE_PATTERN, SETTLE_RECORD_LINE_KEY, SETTLE_RECORD_LINE_PATTERN, SETTLE_SECTION_PLACEHOLDER, SOURCE_LINE_KEY, SOURCE_LINE_PATTERN, STATUS_LINE_KEY, STATUS_LINE_PATTERN, ScannedDebt, SectionScanResult, SettleInput, TEMPLATE_FIELDS, TYPE_LINE_KEY, TYPE_LINE_PATTERN, TemplateFieldDoc, WAIVE_DATE_LINE_KEY, WAIVE_DATE_LINE_PATTERN, WAIVE_REASON_LINE_KEY, WAIVE_REASON_LINE_PATTERN, WaiveInput, captureGroup, debtStatusKeyFromLabel, debtTypeKeyFromLabel, extractDebtKey, isRealCalendarDate, parseDebtDoc, renderDebtTemplate, renderDebtTemplateSkeleton, renderIndexTableRow, renderRegistryReadmeStub, runDebtsLint, runIndexCheck, scanDebtsDir, settleDebtDoc, waiveDebtDoc };

package/dist/index.js

@@ -0,0 +1,8 @@
+import"./rolldown-runtime-BqT_7tdF.js";import{existsSync as e,readFileSync as t,readdirSync as n}from"node:fs";import{join as r,posix as i}from"node:path";import{NUMBERED_SLUG_PATTERN as a,NUMBERED_SLUG_SOURCE as o,buildIndexLinkPattern as s,extractIndexRefs as c}from"@longzai-intelligence-docs/core";const l=RegExp(`^(\\d{3,4})-(${o})\\.md$`),u=a,d=/^# (\d{3,4}) — (.+)$/,f=/^> 债务类型：(.+)$/,p=/^> 记录日期：(\d{4}-\d{2}-\d{2})$/,m=/^> 状态：(.+)$/,h=/^> 来源：(.+)$/,g=/^> 关联：(.+)$/,_=/^> 清偿日期：(\d{4}-\d{2}-\d{2})$/,v=/^> 清偿记录：(.+)$/,y=/^> 豁免日期：(\d{4}-\d{2}-\d{2})$/,b=/^> 豁免理由：(.+)$/,x=`债务类型`,S=`记录日期`,C=`状态`,w=`来源`,T=`关联`,E=`清偿日期`,D=`清偿记录`,O=`豁免日期`,k=`豁免理由`,A=[`transition`,`architecture`,`implementation`,`test`,`dependency`,`documentation`],j={transition:`过渡债`,architecture:`架构债`,implementation:`实现债`,test:`测试债`,dependency:`依赖债`,documentation:`文档债`},M=[`open`,`settled`,`waived`],N={open:`未清偿`,settled:`已清偿`,waived:`已豁免`},P=[`背景`,`债务事实`,`清偿路径`,`清偿记录`],F=[`一`,`二`,`三`,`四`],I=[/^## 一、背景$/,/^## 二、债务事实$/,/^## 三、清偿路径$/,/^## 四、清偿记录$/],L=`待补充`,R=`待收口后回填`,z=s({numberSource:`\\d{3,4}`,slugSource:o});function B(e,t){if(e===null||e[t]===void 0)throw Error(`正则捕获组 ${t} 未命中，格式口径内部错误`);return e[t]}function V(e){let t=/^(\d{1,4})[-._]/.exec(e);return t===null?null:B(t,1)}function H(e){let[t,n,r]=e.split(`-`).map(e=>Number.parseInt(e,10));if(t===void 0||n===void 0||r===void 0)return!1;let i=new Date(Date.UTC(t,n-1,r));return i.getUTCFullYear()===t&&i.getUTCMonth()===n-1&&i.getUTCDate()===r}function U(e){for(let t of A)if(j[t]===e)return t;return null}function W(e){for(let t of M)if(N[t]===e)return t;return null}function G(e){return ee(e)?n(e).filter(e=>e.endsWith(`.md`)&&e!==`README.md`).map(t=>({basename:t,key:V(t),absPath:r(e,t)})).sort((e,t)=>(e.key??`zzzz`).localeCompare(t.key??`zzzz`)):[]}function ee(e){try{return n(e).length>=0}catch{return!1}}function K(e){let t=e.split(`
+`),n=[],r=d.exec(t[0]??``);if(r===null)return n.push({line:1,message:`首行须为「# NNNN — 标题」形态 H1，编号入 H1，em dash 分隔`}),{debt:null,issues:n};let i=/* @__PURE__ */ new Map,a=0,o=1;for(;o<t.length;){let e=t[o]??``;if(e.trim()===``){o+=1;continue}let n=[[f,x],[p,S],[m,C],[h,w],[g,T],[_,E],[v,D],[y,O],[b,k]],r=!1;for(let[t,s]of n){let n=t.exec(e);if(n!==null){i.set(s,B(n,1)),s===`状态`&&(a=o),r=!0;break}}if(r)o+=1;else break}let{sectionHits:s,settleSectionContent:c}=te(t);return{debt:{number:B(r,1),title:B(r,2),typeLabel:i.get(`债务类型`)??null,date:i.get(`记录日期`)??null,statusLabel:i.get(`状态`)??null,source:i.get(`来源`)??null,ref:i.get(`关联`)??null,settleDate:i.get(`清偿日期`)??null,settleRecord:i.get(`清偿记录`)??null,waiveDate:i.get(`豁免日期`)??null,waiveReason:i.get(`豁免理由`)??null,headerEndLine:o,statusLineIndex:a,sectionHits:s,settleSectionContent:c},issues:n}}function te(e){let t=[],n=-1;for(let r=0;r<e.length;r+=1){let i=e[r]??``;for(let e=0;e<I.length;e+=1)I[e]?.test(i)===!0&&(t.push(e),e===3&&(n=r+1))}let r=[];if(n>=0)for(let t=n;t<e.length;t+=1){let n=e[t]??``;if(n.startsWith(`## `))break;n.trim()!==``&&r.push(n.trim())}return{sectionHits:t,settleSectionContent:r.length===0?null:r.join(`
+`)}}function q(e){return`| ${e.number} | [${e.title}](./${e.target}) | ${e.typeLabel} | ${e.statusLabel} |`}function ne(n){let i=[],a=G(n.registryDirAbs).filter(e=>l.test(e.basename)),o=new Map(a.map(e=>{let t=l.exec(e.basename);return[t===null?e.key??e.basename:B(t,1),e]})),s=r(n.registryDirAbs,`README.md`),u=e(s)?c(t(s,`utf8`),z):/* @__PURE__ */ new Map;e(s)||i.push({kind:`readme-missing`,file:`README.md`,message:`注册表 README 未建，init 可落存根，索引行人工登记`});let d=[];for(let e of a){let n=l.exec(e.basename);if(n===null)continue;let r=B(n,1),a=B(n,2),o=K(t(e.absPath,`utf8`));d.push(q({number:r,title:o.debt?.title??a,target:e.basename,typeLabel:o.debt?.typeLabel??`未知类型`,statusLabel:o.debt?.statusLabel??`未知状态`})),u.has(r)?u.get(r)!==a&&i.push({kind:`slug-drift`,file:e.basename,message:`索引 slug 漂移：索引指向 ${r}-${u.get(r)}.md，实际为 ${e.basename}`}):i.push({kind:`missing`,file:e.basename,message:`索引缺行：${e.basename}，期望行见报文，人工登记`})}for(let[e,t]of u)o.has(e)||i.push({kind:`stale`,file:`${e}-${t}.md`,message:`索引多行：引用 ${e}-${t}.md 但文件不存在，删除索引行或补文件`});return{ok:i.length===0,findings:i,expectedLines:d,fileCount:a.length,indexedCount:u.size}}function J(e){let n=[],r=0,a=0;for(let r of e.config.scopes){let o=G(ie(e.root,r.registryDir));a+=o.length;for(let e of o)Y(n,i.join(r.registryDir,e.basename),e.basename,t(e.absPath,`utf8`))}let o=new Set(e.config.lint.baseline.map(e=>`${e.file}|${e.rule}`));return{violations:n.filter(e=>{let t=o.has(`${e.file}|${e.rule}`);return t&&(r+=1),!t}),fileCount:a,exemptedCount:r}}function Y(e,t,n,r){let i=l.exec(n);if(i===null){e.push({rule:`D-FILENAME`,file:t,line:0,message:`文件名须为「NNNN-<slug>.md」形态，编号 3-4 位零填充加 ASCII kebab`});return}let a=K(r);if(a.debt===null)for(let n of a.issues)e.push({rule:`D-H1`,file:t,line:n.line,message:n.message});else a.debt.number!==i[1]&&e.push({rule:`D-H1-NUMBER`,file:t,line:1,message:`H1 编号「${a.debt.number}」与文件名编号「${i[1]}」不一致`}),a.debt.typeLabel===null?e.push({rule:`D-TYPE-LINE`,file:t,line:a.debt.headerEndLine+1,message:`头部缺「> 债务类型：<类型中文名>」元数据行`}):U(a.debt.typeLabel)===null&&e.push({rule:`D-TYPE-LINE`,file:t,line:2,message:`债务类型「${a.debt.typeLabel}」不在词表内，合法值为 ${Object.values(j).join(`、`)}`}),a.debt.date===null?e.push({rule:`D-DATE-LINE`,file:t,line:a.debt.headerEndLine+1,message:`头部缺「> 记录日期：YYYY-MM-DD」元数据行`}):H(a.debt.date)||e.push({rule:`D-DATE-REAL`,file:t,line:2,message:`记录日期「${a.debt.date}」非真实日历日期`}),a.debt.statusLabel===null?e.push({rule:`D-STATUS-LINE`,file:t,line:a.debt.headerEndLine+1,message:`头部缺「> 状态：<状态中文名>」元数据行`}):W(a.debt.statusLabel)===null&&e.push({rule:`D-STATUS-LINE`,file:t,line:2,message:`状态「${a.debt.statusLabel}」不在词表内，合法值为未清偿、已清偿、已豁免`}),a.debt.source===null&&e.push({rule:`D-SOURCE-LINE`,file:t,line:a.debt.headerEndLine+1,message:`头部缺「> 来源：<出处>」元数据行`}),X(e,t,a.debt.sectionHits),re(e,t,a.debt)}function X(e,t,n){for(let r=0;r<P.length;r+=1)n.includes(r)||e.push({rule:`D-SECTION-MISSING`,file:t,line:0,message:`正文缺固定节「${P[r]}」`});let r=-1;for(let i of n){if(i<=r){e.push({rule:`D-SECTION-ORDER`,file:t,line:0,message:`正文固定节乱序或重复，规范次序为背景、债务事实、清偿路径、清偿记录`});break}r=i}}function re(e,t,n){let r=n.statusLabel===null?null:W(n.statusLabel);r===`open`?(n.settleDate!==null||n.waiveDate!==null)&&e.push({rule:`D-SETTLE-CONSISTENCY`,file:t,line:2,message:`未清偿债不得携带清偿日期或豁免日期元数据行，翻态仅经 settle 与 waive 通道`}):r===`settled`?(n.settleDate===null?e.push({rule:`D-SETTLE-CONSISTENCY`,file:t,line:2,message:`已清偿债缺「> 清偿日期：YYYY-MM-DD」元数据行`}):H(n.settleDate)||e.push({rule:`D-SETTLE-CONSISTENCY`,file:t,line:2,message:`清偿日期「${n.settleDate}」非真实日历日期`}),(n.settleSectionContent===null||n.settleSectionContent===`待收口后回填`)&&e.push({rule:`D-SETTLE-CONSISTENCY`,file:t,line:0,message:`已清偿债第四节清偿记录须回填实文，不得保留占位`})):r===`waived`&&(n.waiveDate===null?e.push({rule:`D-SETTLE-CONSISTENCY`,file:t,line:2,message:`已豁免债缺「> 豁免日期：YYYY-MM-DD」元数据行`}):H(n.waiveDate)||e.push({rule:`D-SETTLE-CONSISTENCY`,file:t,line:2,message:`豁免日期「${n.waiveDate}」非真实日历日期`}),n.waiveReason===null&&e.push({rule:`D-SETTLE-CONSISTENCY`,file:t,line:2,message:`已豁免债缺「> 豁免理由：<理由>」元数据行，理由须含用户裁定`}))}function ie(e,t){return`${e.replace(/\/+$/,``)}/${t}`}function ae(e){let t=K(e.content);if(t.debt===null)return{ok:!1,error:`债档 H1 非法，无法定位翻态锚点`};if(t.debt.statusLabel===N.settled)return{ok:!0,content:e.content,changed:!1};if(t.debt.statusLabel!==N.open)return{ok:!1,error:`状态为「${t.debt.statusLabel}」，仅未清偿债可清偿`};if(t.debt.settleSectionContent===null||t.debt.settleSectionContent===`待收口后回填`)return{ok:!1,error:`第四节清偿记录仍为占位，先回填清偿证据再执行 settle`};let n=[`> 清偿日期：${e.date}`];return e.settleRecord!==void 0&&n.push(`> 清偿记录：${e.settleRecord}`),{ok:!0,content:Z(e.content,t.debt.statusLineIndex,N.settled,n),changed:!0}}function oe(e){let t=K(e.content);if(t.debt===null)return{ok:!1,error:`债档 H1 非法，无法定位翻态锚点`};if(t.debt.statusLabel===N.waived)return{ok:!0,content:e.content,changed:!1};if(t.debt.statusLabel!==N.open)return{ok:!1,error:`状态为「${t.debt.statusLabel}」，仅未清偿债可豁免`};if(!e.reason.includes(`用户裁定`))return{ok:!1,error:`豁免理由须含「用户裁定」，非裁定不得豁免`};let n=[`> 豁免日期：${e.date}`,`> 豁免理由：${e.reason}`];return{ok:!0,content:Z(e.content,t.debt.statusLineIndex,N.waived,n),changed:!0}}function Z(e,t,n,r){let i=e.split(`
+`),a=i[t];if(a===void 0||!a.startsWith(`> 状态：`))throw Error(`状态行定位失败，拒绝假翻态`);return i[t]=`> 状态：${n}`,i.splice(t+1,0,...r),i.join(`
+`)}function Q(e,t,n,r,i,a){let o=[`# ${e} — ${t}`,``,`> 债务类型：${n}`,`> 记录日期：${r}`,`> 状态：未清偿`,`> 来源：${i}`];return a!==void 0&&o.push(`> 关联：${a}`),o}function $(){let e=[];for(let t=0;t<P.length;t+=1){let n=P[t],r=F[t],i=t===3?R:L;e.push(`## ${r}、${n}`,``,i,``)}return e}function se(){return[...Q(`<NNNN>`,`<一句话标题>`,`<债务类型中文名>`,`<YYYY-MM-DD>`,`<出处与日期>`,`<可选：关联条目链接，缺席省略本行>`),``,...$()].join(`
+`)}function ce(e){return[...Q(e.number,e.title,j[e.type],e.date,e.source,e.ref),``,...$()].join(`
+`)}function le(e){return[`# ${e} debts 注册表`,``,"本目录是 lzi-debts 技术债注册表，文件名 `NNNN-<slug>.md`，编号独立序列。",``,`debts 定位：**语义分型的技术债注册表**，一债一档带生命周期。所有过渡措施必须立档，无档过渡即违规。`,``,`## 债务类型词表`,``,"- `transition` 过渡债：过渡期措施，含双轨回落锚点与兼容垫片，清偿路径节必须写明退役判据","- `architecture` 架构债：分层越界、所有权错位、拓扑简化","- `implementation` 实现债：已知次优实现","- `test` 测试债：关键路径缺测或测试薄弱","- `dependency` 依赖债：钉版、过期、重复依赖","- `documentation` 文档债：文档缺失或与实现漂移",``,`## 状态词表`,``,"- `未清偿`：债在册待偿付","- `已清偿`：经 `settle` 翻态，第四节须回填清偿记录","- `已豁免`：经 `waive` 翻态，理由须含用户裁定",``,`## 建档与收口`,``,"- `lzi-debts create --title <t> --type <key> --source <src>` 取号经 numbering 插件，写入时刻确定，禁止手工定号","- `lzi-debts settle --number <n>` 先回填第四节清偿记录再清偿翻态","- `lzi-debts waive --number <n> --reason <r>` 豁免理由须含用户裁定","- 标准模板：`lzi-debts template`，字段契约 `--format json`",``,`## 索引`,``,"- 索引行**人工登记**，工具只检查不写入：`lzi-debts index check` 报差量并附期望行",``,`| 编号 | 标题 | 类型 | 状态 |`,`| --- | --- | --- | --- |`,``,`## 头部元数据`,``,"- `> 债务类型：<类型中文名>` 强制","- `> 记录日期：YYYY-MM-DD` 强制","- `> 状态：<状态中文名>` 强制","- `> 来源：<出处与日期>` 强制","- `> 关联：<条目链接>` 可选",``].join(`
+`)}const ue=[{name:`number`,required:!0,description:`scope 内编号，3-4 位零填充，由编号门禁取号分配，写入时刻确定`},{name:`slug`,required:!0,description:`ASCII kebab slug，小写字母、数字与连字符，禁中文，中文标题须显式 --slug`},{name:`title`,required:!0,description:`一句话标题`},{name:`债务类型`,required:!0,description:`封闭词表键即 transition、architecture、implementation、test、dependency、documentation，头部元数据行写对应中文名`},{name:`记录日期`,required:!0,description:`YYYY-MM-DD，头部 blockquote 元数据行，强制`},{name:`状态`,required:!0,description:`三值词表即未清偿、已清偿、已豁免，建档固定未清偿，翻态仅经 settle 与 waive 通道`},{name:`来源`,required:!0,description:`出处与日期，头部 blockquote 元数据行，强制`},{name:`关联`,required:!1,description:`关联条目链接，头部 blockquote 元数据行，缺席省略整行`},{name:`正文四节`,required:!0,description:`固定四节即背景、债务事实、清偿路径、清偿记录，建档为占位，内容随立档与收口回填`}];export{u as ASCII_KEBAB_SLUG_PATTERN,N as CANONICAL_DEBT_STATUS_LABELS,j as CANONICAL_DEBT_TYPE_LABELS,S as DATE_LINE_KEY,p as DATE_LINE_PATTERN,l as DEBT_FILENAME_PATTERN,d as DEBT_H1_PATTERN,M as DEBT_STATUS_KEYS,A as DEBT_TYPE_KEYS,z as INDEX_LINK_PATTERN,T as REF_LINE_KEY,g as REF_LINE_PATTERN,I as SECTION_HEADER_PATTERNS,P as SECTION_KEYS,F as SECTION_ORDINALS,L as SECTION_PLACEHOLDER,E as SETTLE_DATE_LINE_KEY,_ as SETTLE_DATE_LINE_PATTERN,D as SETTLE_RECORD_LINE_KEY,v as SETTLE_RECORD_LINE_PATTERN,R as SETTLE_SECTION_PLACEHOLDER,w as SOURCE_LINE_KEY,h as SOURCE_LINE_PATTERN,C as STATUS_LINE_KEY,m as STATUS_LINE_PATTERN,ue as TEMPLATE_FIELDS,x as TYPE_LINE_KEY,f as TYPE_LINE_PATTERN,O as WAIVE_DATE_LINE_KEY,y as WAIVE_DATE_LINE_PATTERN,k as WAIVE_REASON_LINE_KEY,b as WAIVE_REASON_LINE_PATTERN,B as captureGroup,W as debtStatusKeyFromLabel,U as debtTypeKeyFromLabel,V as extractDebtKey,H as isRealCalendarDate,K as parseDebtDoc,ce as renderDebtTemplate,se as renderDebtTemplateSkeleton,q as renderIndexTableRow,le as renderRegistryReadmeStub,J as runDebtsLint,ne as runIndexCheck,G as scanDebtsDir,ae as settleDebtDoc,oe as waiveDebtDoc};

package/dist/rolldown-runtime-BqT_7tdF.js

@@ -0,0 +1 @@
+import"node:module";export{};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@longzai-intelligence-debts/ledger",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Longzai Intelligence Debts 注册表引擎",
+  "keywords": [
+    "debts",
+    "ledger",
+    "lint",
+    "longzai-intelligence",
+    "registry"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "lzi-lint lint",
+    "lint:fix": "lzi-lint fix",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage"
+  },
+  "dependencies": {
+    "@longzai-intelligence-debts/config": "0.0.2",
+    "@longzai-intelligence-docs/core": "0.0.22"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.