@longzai-intelligence-issues/ledger 0.0.1

package/src/freeze/freeze.commands.ts

@@ -0,0 +1,261 @@
+/**
+ * freeze / unfreeze（裁定语硬门）
+ *
+ * 冻结/解冻均属人类裁定事项：--reason/--note 必须含「用户裁定」，工具拒绝形式
+ * 冻结/解冻；状态行含 `｜`（复合元信息行）拒绝整行破坏性替换；幂等（重复
+ * freeze 更新理由）；解冻仅对已冻结案生效，恢复 🔴。
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  STATUS_LINE_LOCATE_PATTERN,
+  STATUS_LINE_PREFIX_SOURCE,
+  STATUS_LINE_SCAN_LINES,
+} from '@/parser/format.utils';
+
+/**
+ * 裁定语硬门关键词
+ */
+export const ADJUDICATION_KEYWORD = '用户裁定';
+
+/**
+ * freeze 命令入参
+ */
+export type FreezeIssueInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * issue 文件仓库相对路径
+   */
+  file: string;
+
+  /**
+   * 裁定理由（须含「用户裁定」）
+   */
+  reason: string;
+};
+
+/**
+ * unfreeze 命令入参
+ */
+export type UnfreezeIssueInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * issue 文件仓库相对路径
+   */
+  file: string;
+
+  /**
+   * 解冻注记（须含「用户裁定」）
+   */
+  note: string;
+};
+
+/**
+ * freeze / unfreeze 结果
+ */
+export type FreezeResult = {
+  /**
+   * 操作成功标记
+   */
+  ok: boolean;
+
+  /**
+   * 结果说明
+   */
+  message: string;
+
+  /**
+   * 幂等标记
+   */
+  idempotent: boolean;
+};
+
+/**
+ * 状态行定位结果
+ */
+type StatusLineLocation = {
+  /**
+   * 状态行文本
+   */
+  line: string;
+
+  /**
+   * 行下标
+   */
+  index: number;
+};
+
+/**
+ * 定位可写状态行（头部窗口内首个命中）
+ *
+ * @param raw - 文档全文
+ * @returns 状态行文本与行下标；未命中为 null
+ */
+function locateStatusLine(raw: string): StatusLineLocation | null {
+  /**
+   * 文档行数组
+   */
+  const lines = raw.split(/\r?\n/);
+
+  /**
+   * 扫描窗口上界
+   */
+  const limit = Math.min(lines.length, STATUS_LINE_SCAN_LINES);
+
+  for (let index = 0; index < limit; index += 1) {
+    if (STATUS_LINE_LOCATE_PATTERN.test(lines[index] ?? '')) {
+      return { line: lines[index] ?? '', index };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 执行冻结（幂等：重复调用更新理由）
+ *
+ * @param input - 命令入参
+ * @param input.root - 仓库根绝对路径
+ * @param input.file - issue 文件仓库相对路径
+ * @param input.reason - 裁定理由（须含「用户裁定」）
+ * @returns 操作结果
+ */
+export function freezeIssue(input: FreezeIssueInput): FreezeResult {
+  if (!input.reason.includes(ADJUDICATION_KEYWORD)) {
+    return {
+      ok: false,
+      message: `冻结属人类裁定事项：--reason 必须含「${ADJUDICATION_KEYWORD}」——工具拒绝形式冻结`,
+      idempotent: false,
+    };
+  }
+
+  return writeFrozenStatus(input.root, input.file, input.reason, 'freeze');
+}
+
+/**
+ * 执行解冻（仅对已冻结案生效）
+ *
+ * @param input - 命令入参
+ * @param input.root - 仓库根绝对路径
+ * @param input.file - issue 文件仓库相对路径
+ * @param input.note - 解冻注记（须含「用户裁定」）
+ * @returns 操作结果
+ */
+export function unfreezeIssue(input: UnfreezeIssueInput): FreezeResult {
+  if (!input.note.includes(ADJUDICATION_KEYWORD)) {
+    return {
+      ok: false,
+      message: `解冻属人类裁定事项：--note 必须含「${ADJUDICATION_KEYWORD}」——工具拒绝形式解冻`,
+      idempotent: false,
+    };
+  }
+
+  return writeFrozenStatus(input.root, input.file, input.note, 'unfreeze');
+}
+
+/**
+ * 冻结/解冻状态行写入核
+ *
+ * @param root - 仓库根绝对路径
+ * @param file - issue 文件仓库相对路径
+ * @param noteText - 理由/注记文本
+ * @param mode - 操作模式
+ * @returns 操作结果
+ */
+function writeFrozenStatus(
+  root: string,
+  file: string,
+  noteText: string,
+  mode: 'freeze' | 'unfreeze',
+): FreezeResult {
+  /**
+   * 文档全文
+   */
+  let raw = '';
+
+  try {
+    raw = readFileSync(join(root, file), 'utf8');
+  } catch {
+    return { ok: false, message: '读档失败（文件不存在或不可读）', idempotent: false };
+  }
+
+  /**
+   * 状态行定位结果
+   */
+  const located = locateStatusLine(raw);
+
+  if (located === null) {
+    return { ok: false, message: '未定位到状态行——冻结/解冻拒绝写入', idempotent: false };
+  }
+
+  if (located.line.includes('｜')) {
+    return {
+      ok: false,
+      message: '状态行为复合元信息行（含 ｜）——拒绝整行破坏性替换，请先经 normalize-header 迁移',
+      idempotent: false,
+    };
+  }
+
+  /**
+   * 已冻结判定
+   */
+  const alreadyFrozen = located.line.includes('已冻结');
+
+  if (mode === 'unfreeze' && !alreadyFrozen) {
+    return {
+      ok: false,
+      message: `非冻结案拒绝解冻（当前状态行：${located.line}）`,
+      idempotent: false,
+    };
+  }
+
+  /**
+   * 目标状态行
+   */
+  const targetLine =
+    mode === 'freeze'
+      ? `**状态**: ⚪ 已冻结（${noteText}——不推进、不处置、无验证判据；如需推进须先取得「解冻」的显式裁定）`
+      : `**状态**: 🔴 待处理（${noteText}——冻结解除，处置方向待重新评估）`;
+
+  /**
+   * 幂等判定（同模式同理由原文即目标）
+   */
+  if (located.line === targetLine) {
+    return { ok: true, message: '状态行已为目标形态——幂等零变更', idempotent: true };
+  }
+
+  /**
+   * 前缀保留改写（「状态…冒号」前缀原形态 + 空格规范）
+   */
+  const prefixMatch = new RegExp(`^(${STATUS_LINE_PREFIX_SOURCE})\\s*`).exec(located.line);
+
+  /**
+   * 改写后状态行
+   */
+  const rewrittenLine = `${prefixMatch?.[1] ?? '**状态**:'} ${targetLine.replace(/^\*\*状态\*\*:\s*/, '')}`;
+
+  /**
+   * 文档行数组
+   */
+  const lines = raw.split(/\r?\n/);
+
+  lines[located.index] = rewrittenLine;
+
+  writeFileSync(join(root, file), lines.join('\n'));
+
+  return {
+    ok: true,
+    message: mode === 'freeze' ? '已冻结（⚪）' : '已解冻恢复 🔴',
+    idempotent: false,
+  };
+}

package/src/fs/mini-glob.utils.ts

@@ -0,0 +1,216 @@
+/**
+ * 自研 mini-glob 编译器（零第三方依赖）
+ *
+ * 语义（apex numbering-guard 同款）：单星→段内任意；双星后随分隔→任意层级
+ * 目录；双星非后随分隔→任意字符；`?`→段内单字符；`{a,b}`→段内多选一（候选
+ * 项可含通配）；字符类 `[` 与裸大括号显式抛错（不静默误配）；整串锚定匹配。
+ */
+
+/**
+ * mini-glob 编译错误
+ */
+export class MiniGlobError extends Error {
+  /**
+   * 构造编译错误
+   *
+   * @param pattern - 涉事 glob 模式
+   * @param reason - 违规原因
+   */
+  constructor(pattern: string, reason: string) {
+    super(`glob 模式「${pattern}」非法：${reason}`);
+    this.name = 'MiniGlobError';
+  }
+}
+
+/**
+ * 正则特殊字符（转义表）
+ */
+const REGEX_SPECIALS = new Set(['.', '^', '$', '+', '(', ')', '|', '\\', ']']);
+
+/**
+ * 编译结果缓存（glob → RegExp）
+ */
+const compiledCache = new Map<string, RegExp>();
+
+/**
+ * 转义正则特殊字符
+ *
+ * @param char - 待转义单字符
+ * @returns 转义后文本
+ */
+function escapeChar(char: string): string {
+  return REGEX_SPECIALS.has(char) ? `\\${char}` : char;
+}
+
+/**
+ * 翻译不含大括号的片段（`*`/`?`/字符类抛错/字面转义）
+ *
+ * @param pattern - 完整 glob（错误消息用）
+ * @param segment - 待翻译片段
+ * @returns 正则片段
+ * @throws {@link MiniGlobError} 片段含字符类 `[`
+ */
+function translatePlainSegment(pattern: string, segment: string): string {
+  /**
+   * 输出收集器
+   */
+  let out = '';
+
+  /**
+   * 扫描下标
+   */
+  let index = 0;
+
+  while (index < segment.length) {
+    /**
+     * 当前字符
+     */
+    const char = segment[index] ?? '';
+
+    if (char === '[') {
+      throw new MiniGlobError(pattern, '不支持字符类 [（与既有生态对齐，显式抛错不静默误配）');
+    }
+
+    if (char === '*') {
+      /**
+       * 连续星号长度
+       */
+      let stars = 0;
+
+      while ((segment[index + stars] ?? '') === '*') {
+        stars += 1;
+      }
+
+      if (stars >= 2 && (segment[index + stars] ?? '') === '/') {
+        out += '(?:.*/)?';
+        index += stars + 1;
+
+        continue;
+      }
+
+      if (stars >= 2) {
+        out += '[\\s\\S]*';
+        index += stars;
+
+        continue;
+      }
+
+      out += '[^/]*';
+      index += 1;
+
+      continue;
+    }
+
+    if (char === '?') {
+      out += '[^/]';
+      index += 1;
+
+      continue;
+    }
+
+    out += escapeChar(char);
+    index += 1;
+  }
+
+  return out;
+}
+
+/**
+ * 翻译片段（含大括号多选一展开）
+ *
+ * @param pattern - 完整 glob
+ * @param segment - 待翻译片段
+ * @returns 正则片段
+ * @throws {@link MiniGlobError} 大括号未闭合 / 裸 `}` / 字符类 `[`
+ */
+function translateSegment(pattern: string, segment: string): string {
+  /**
+   * 首个大括号位置
+   */
+  const braceStart = segment.indexOf('{');
+
+  if (braceStart === -1) {
+    return translatePlainSegment(pattern, segment);
+  }
+
+  /**
+   * 配对闭括号位置
+   */
+  const braceEnd = segment.indexOf('}', braceStart + 1);
+
+  if (braceEnd === -1) {
+    throw new MiniGlobError(pattern, '大括号未闭合');
+  }
+
+  /**
+   * 大括号前的字面前缀
+   */
+  const prefix = segment.slice(0, braceStart);
+
+  /**
+   * 多选一候选内容（含大括号即嵌套形态，显式拒收）
+   */
+  const braceContent = segment.slice(braceStart + 1, braceEnd);
+
+  if (braceContent.includes('{')) {
+    throw new MiniGlobError(pattern, '不支持嵌套大括号');
+  }
+
+  /**
+   * 多选一候选列表
+   */
+  const candidates = braceContent.split(',');
+
+  /**
+   * 大括号后的剩余部分
+   */
+  const rest = segment.slice(braceEnd + 1);
+
+  /**
+   * 逐候选翻译结果（候选 + 剩余部分合并翻译，支持嵌套前后缀）
+   */
+  const translated = candidates.map((candidate) =>
+    translateSegment(pattern, `${prefix}${candidate}${rest}`),
+  );
+
+  return `(?:${translated.join('|')})`;
+}
+
+/**
+ * 编译 glob 模式为整串锚定正则
+ *
+ * @param pattern - glob 模式
+ * @returns 整串 `^…$` 正则
+ * @throws {@link MiniGlobError} 模式含不支持语法
+ */
+export function compileMiniGlob(pattern: string): RegExp {
+  /**
+   * 缓存命中结果
+   */
+  const cached = compiledCache.get(pattern);
+
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  /**
+   * 编译产物（^…$ 锚定）
+   */
+  const compiled = new RegExp(`^${translateSegment(pattern, pattern)}$`);
+
+  compiledCache.set(pattern, compiled);
+
+  return compiled;
+}
+
+/**
+ * 判定候选路径是否命中 glob
+ *
+ * @param pattern - glob 模式
+ * @param candidate - 候选 posix 相对路径
+ * @returns 是否命中
+ * @throws {@link MiniGlobError} 模式含不支持语法
+ */
+export function matchMiniGlob(pattern: string, candidate: string): boolean {
+  return compileMiniGlob(pattern).test(candidate);
+}