@longzai-intelligence-issues/ledger 0.0.1

package/src/fs/walk-surface.utils.ts

@@ -0,0 +1,298 @@
+/**
+ * 扫描面分层遍历基座
+ *
+ * include glob 反推最小目录前缀集（截断=保守超集，glob 可匹配路径必落某推导
+ * 前缀下）；前缀遍历宽容（缺前缀静默跳过=未来目录合法），全仓遍历严格（缺根
+ * 抛错防扫描面缩水）。剪枝：.git 恒跳过 / 排除 glob 整树剪枝 / 符号链接跳过；
+ * 文件名级零内容读取、零子进程、零网络；输出 posix 相对路径升序。
+ *
+ * 前缀约定：无尾斜杠的 posix 相对目录路径，'' 表示全仓根。
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join, posix } from 'node:path';
+
+import { matchMiniGlob } from '@/fs/mini-glob.utils';
+
+/**
+ * 遍历选项
+ */
+export type WalkOptions = {
+  /**
+   * 排除 glob 列表（目录命中即整树剪枝，按原相对路径 / 尾斜杠 / 子树三口径测试）
+   */
+  excludeGlobs?: readonly string[];
+};
+
+/**
+ * 通配判定字符集（`*` `?` `{` `}`）
+ */
+const WILDCARD_CHARS = new Set(['*', '?', '{', '}']);
+
+/**
+ * 判定 glob 段是否含通配
+ *
+ * @param segment - 路径段
+ * @returns 是否含通配字符
+ */
+function hasWildcard(segment: string): boolean {
+  return [...segment].some((char) => WILDCARD_CHARS.has(char));
+}
+
+/**
+ * include glob 反推最小目录前缀集
+ *
+ * 末段恒为文件名模式不参与推导；字面段续推、通配段截断（截断=更短前缀=
+ * 覆盖超集）、`{a,b}` 分叉（候选项含通配即截断该分支）；任一模式贡献空前缀
+ * 则全仓标记（''）。候选去重后按包含关系裁剪（宽前缀吞并其下窄前缀）。
+ * 空模式集产出空前缀集（无扫描面）。
+ *
+ * @param includeGlobs - include glob 列表
+ * @returns 最小目录前缀集（无尾斜杠 posix 相对路径，'' 表示全仓）
+ */
+export function deriveWalkPrefixes(includeGlobs: readonly string[]): string[] {
+  /**
+   * 候选前缀收集器
+   */
+  const candidates: string[] = [];
+
+  for (const glob of includeGlobs) {
+    /**
+     * glob 路径段列表
+     */
+    const segments = glob.split('/').filter((segment) => segment !== '');
+
+    /**
+     * 末段（文件名模式）剔除后的目录段
+     */
+    const dirSegments = segments.slice(0, -1);
+
+    /**
+     * 分叉游标集（当前所有字面前缀，'' 为根）
+     */
+    let prefixes: string[] = [''];
+
+    for (const segment of dirSegments) {
+      /**
+       * 整段大括号多选一形态
+       */
+      const braceMatch = /^\{([^{}]+)\}$/.exec(segment);
+
+      if (braceMatch !== null) {
+        /**
+         * 下一层游标收集器
+         */
+        const forked: string[] = [];
+
+        for (const option of (braceMatch[1] ?? '').split(',')) {
+          if (hasWildcard(option)) {
+            /**
+             * 通配候选：截断该分支（保留当前前缀）
+             */
+            forked.push(...prefixes);
+          } else {
+            forked.push(...prefixes.map((prefix) => joinPrefix(prefix, option)));
+          }
+        }
+
+        prefixes = forked;
+
+        continue;
+      }
+
+      if (hasWildcard(segment)) {
+        break;
+      }
+
+      prefixes = prefixes.map((prefix) => joinPrefix(prefix, segment));
+    }
+
+    candidates.push(...prefixes);
+  }
+
+  /**
+   * 去重后的候选集
+   */
+  const unique = [...new Set(candidates)];
+
+  /**
+   * 包含关系裁剪：宽前缀（含 ''）吞并其下窄前缀
+   */
+  return unique.filter(
+    (prefix) =>
+      prefix === '' ||
+      !unique.some((other) => other !== prefix && (other === '' || prefix.startsWith(`${other}/`))),
+  );
+}
+
+/**
+ * 拼接前缀（根前缀 '' 直接取段名）
+ *
+ * @param prefix - 当前前缀（'' 为根）
+ * @param segment - 追加段
+ * @returns 拼接后前缀
+ */
+function joinPrefix(prefix: string, segment: string): string {
+  return prefix === '' ? segment : `${prefix}/${segment}`;
+}
+
+/**
+ * 判定目录是否命中排除 glob（原相对路径 / 尾斜杠 / 子树三口径）
+ *
+ * @param excludeGlobs - 排除 glob 列表
+ * @param dirRel - 目录相对路径（posix，无尾斜杠）
+ * @returns 是否整树排除
+ */
+function isDirExcluded(excludeGlobs: readonly string[], dirRel: string): boolean {
+  return excludeGlobs.some(
+    (glob) =>
+      matchMiniGlob(glob, dirRel) ||
+      matchMiniGlob(glob, `${dirRel}/`) ||
+      matchMiniGlob(glob, `${dirRel}/**`),
+  );
+}
+
+/**
+ * 判定文件是否命中排除 glob
+ *
+ * @param excludeGlobs - 排除 glob 列表
+ * @param fileRel - 文件相对路径（posix）
+ * @returns 是否排除
+ */
+function isFileExcluded(excludeGlobs: readonly string[], fileRel: string): boolean {
+  return excludeGlobs.some((glob) => matchMiniGlob(glob, fileRel));
+}
+
+/**
+ * 判定目录是否需要访问（在通往某前缀的路径上，或整体落于某前缀内）
+ *
+ * @param prefixes - 目录前缀集（'' 表示全仓）
+ * @param dirRel - 目录相对路径
+ * @returns 是否访问
+ */
+function shouldVisitDir(prefixes: readonly string[], dirRel: string): boolean {
+  return prefixes.some(
+    (prefix) =>
+      prefix === '' ||
+      dirRel === prefix ||
+      dirRel.startsWith(`${prefix}/`) ||
+      prefix.startsWith(`${dirRel}/`),
+  );
+}
+
+/**
+ * 判定文件是否在采集面内（落于某前缀下；'' 全仓）
+ *
+ * @param prefixes - 目录前缀集
+ * @param fileRel - 文件相对路径
+ * @returns 是否采集
+ */
+function isFileInSurface(prefixes: readonly string[], fileRel: string): boolean {
+  return prefixes.some((prefix) => prefix === '' || fileRel.startsWith(`${prefix}/`));
+}
+
+/**
+ * 目录遍历核心（递归）
+ *
+ * @param dirAbs - 当前目录绝对路径
+ * @param dirRel - 当前目录相对路径（'' 为根层）
+ * @param prefixes - 目录前缀集
+ * @param excludeGlobs - 排除 glob 列表
+ * @param strict - 严格模式（目录缺失抛错；宽容模式静默跳过）
+ * @param collector - 文件相对路径收集器
+ * @throws {@link Error} 严格模式下目录缺失
+ */
+function walkDir(
+  dirAbs: string,
+  dirRel: string,
+  prefixes: readonly string[],
+  excludeGlobs: readonly string[],
+  strict: boolean,
+  collector: string[],
+): void {
+  if (!existsSync(dirAbs)) {
+    if (strict) {
+      throw new Error(`扫描面目录缺失：${dirAbs}（严格模式防扫描面静默缩水）`);
+    }
+
+    return;
+  }
+
+  /**
+   * 当前目录条目列表（按名排序保证输出确定）
+   */
+  const entries = readdirSync(dirAbs, { withFileTypes: true }).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+
+  for (const entry of entries) {
+    /**
+     * 条目相对路径（posix）
+     */
+    const rel = dirRel === '' ? entry.name : `${dirRel}/${entry.name}`;
+
+    if (entry.isDirectory()) {
+      if (entry.name === '.git' || isDirExcluded(excludeGlobs, rel)) {
+        continue;
+      }
+
+      if (!shouldVisitDir(prefixes, rel)) {
+        continue;
+      }
+
+      walkDir(join(dirAbs, entry.name), rel, prefixes, excludeGlobs, strict, collector);
+
+      continue;
+    }
+
+    if (entry.isFile()) {
+      if (isFileExcluded(excludeGlobs, rel) || !isFileInSurface(prefixes, rel)) {
+        continue;
+      }
+
+      collector.push(posix.normalize(rel));
+    }
+  }
+}
+
+/**
+ * 前缀定向遍历（宽容：前缀目录缺失静默跳过——scope 登记未来目录属合法现状）
+ *
+ * @param root - 遍历根绝对路径
+ * @param prefixes - deriveWalkPrefixes 产物（'' 表示全仓）
+ * @param options - 遍历选项（排除 glob）
+ * @returns 命中文件相对路径列表（posix 升序）
+ */
+export function walkFilesUnderPrefixes(
+  root: string,
+  prefixes: readonly string[],
+  options: WalkOptions = {},
+): string[] {
+  /**
+   * 文件收集器
+   */
+  const collector: string[] = [];
+
+  walkDir(root, '', prefixes, options.excludeGlobs ?? [], false, collector);
+
+  return collector.sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * 全仓严格遍历（缺根抛错，audit 防缩水口径）
+ *
+ * @param root - 遍历根绝对路径
+ * @param options - 遍历选项（排除 glob）
+ * @returns 命中文件相对路径列表（posix 升序）
+ * @throws {@link Error} 根目录缺失
+ */
+export function walkFilesUnderRoots(root: string, options: WalkOptions = {}): string[] {
+  /**
+   * 文件收集器
+   */
+  const collector: string[] = [];
+
+  walkDir(root, '', [''], options.excludeGlobs ?? [], true, collector);
+
+  return collector.sort((a, b) => a.localeCompare(b));
+}

package/src/health/health.commands.ts

@@ -0,0 +1,327 @@
+/**
+ * 黄灯巡检观测（health）与分诊台账（triage）
+ *
+ * health：状态分布、黄灯总数、最老黄灯账龄（mtime 天）、A-B-C 分类分布；
+ * triage：只收黄灯，B>C>A 优先级分类，台账 append-only 落
+ * .lzi/issues/runs/ledger/triage-<ts>.json（temp+rename 原子写）。
+ */
+
+import type { LziIssuesConfig } from '@longzai-intelligence-issues/config';
+
+import { existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { type IssueDocRecord, scanRegistryDir } from '@/parser/registry.parser';
+import { classifyIssue } from '@/triage/triage.classify';
+
+/**
+ * 巡检报告
+ */
+export type HealthReport = {
+  /**
+   * 状态分布（状态归类 → 计数）
+   */
+  statusCounts: Record<string, number>;
+
+  /**
+   * 黄灯总数（含旧格式 legacy-yellow）
+   */
+  yellowTotal: number;
+
+  /**
+   * 最老黄灯账龄（天，mtime 口径向下取整；无黄灯为 0）
+   */
+  oldestYellowAgeDays: number;
+
+  /**
+   * A-B-C 分类分布
+   */
+  categoryCounts: Record<string, number>;
+};
+
+/**
+ * 分诊台账条目
+ */
+export type TriageItem = {
+  /**
+   * issue 编号
+   */
+  id: string;
+
+  /**
+   * issue 文件仓库相对路径
+   */
+  file: string;
+
+  /**
+   * 状态归类
+   */
+  status: string;
+
+  /**
+   * 分类（A/B/C）
+   */
+  category: 'A' | 'B' | 'C';
+
+  /**
+   * 分类依据（中文说明）
+   */
+  reason: string;
+
+  /**
+   * 判据命令列表（空表示待补录）
+   */
+  criteriaCommands: string[];
+};
+
+/**
+ * 分诊台账文件结构
+ */
+export type TriageLedgerFile = {
+  /**
+   * 生成时刻（毫秒）
+   */
+  generatedAtMs: number;
+
+  /**
+   * 参与扫描的注册表目录
+   */
+  registryDirs: string[];
+
+  /**
+   * 台账条目（黄灯）
+   */
+  items: TriageItem[];
+};
+
+/**
+ * 采集条目（解析产物 + 仓库相对路径 + 注册表目录）
+ */
+type CollectedEntry = {
+  /**
+   * 解析产物
+   */
+  record: IssueDocRecord;
+
+  /**
+   * issue 文件仓库相对路径
+   */
+  file: string;
+
+  /**
+   * 注册表目录
+   */
+  registryDir: string;
+};
+
+/**
+ * 收集各注册表解析产物（附仓库相对路径与注册表目录）
+ *
+ * @param root - 仓库根绝对路径
+ * @param config - 解析后配置
+ * @param dirRels - 限定注册表目录（缺省全部）
+ * @returns 采集条目列表
+ */
+function collectRecords(
+  root: string,
+  config: LziIssuesConfig,
+  dirRels?: readonly string[],
+): CollectedEntry[] {
+  /**
+   * 参与扫描的 scope 列表
+   */
+  const scopes =
+    dirRels === undefined
+      ? config.scopes
+      : config.scopes.filter((scope) => dirRels.includes(scope.registryDir));
+
+  return scopes.flatMap((scope) =>
+    scanRegistryDir(join(root, scope.registryDir)).map((record) => ({
+      record,
+      file: `${scope.registryDir}/${record.file}`,
+      registryDir: scope.registryDir,
+    })),
+  );
+}
+
+/**
+ * 黄灯巡检命令入参
+ */
+export type RunHealthInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * 限定注册表目录（缺省全部）
+   */
+  dirRels?: readonly string[];
+};
+
+/**
+ * 黄灯巡检
+ *
+ * @param input - 命令入参
+ * @returns 巡检报告
+ */
+export function runHealth(input: RunHealthInput): HealthReport {
+  /**
+   * 采集结果
+   */
+  const collected = collectRecords(input.root, input.config, input.dirRels);
+
+  /**
+   * 状态分布
+   */
+  const statusCounts: Record<string, number> = {};
+
+  for (const { record } of collected) {
+    statusCounts[record.status] = (statusCounts[record.status] ?? 0) + 1;
+  }
+
+  /**
+   * 黄灯记录列表
+   */
+  const yellows = collected.filter(
+    ({ record }) => record.status === 'yellow' || record.status === 'legacy-yellow',
+  );
+
+  /**
+   * 最老黄灯 mtime（0 = 无黄灯）
+   */
+  const oldestMtime = yellows.reduce((max, { record }) => Math.max(max, record.modifiedAtMs), 0);
+
+  /**
+   * A-B-C 分类分布
+   */
+  const categoryCounts: Record<string, number> = {};
+
+  for (const { record } of yellows) {
+    /**
+     * 分类结果
+     */
+    const { category } = classifyIssue(record);
+
+    categoryCounts[category] = (categoryCounts[category] ?? 0) + 1;
+  }
+
+  return {
+    statusCounts,
+    yellowTotal: yellows.length,
+    oldestYellowAgeDays:
+      oldestMtime === 0 ? 0 : Math.max(0, Math.floor((Date.now() - oldestMtime) / 86_400_000)),
+    categoryCounts,
+  };
+}
+
+/**
+ * 分诊命令入参
+ */
+export type RunTriageInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * 台账输出目录覆盖（缺省 <root>/.lzi/issues/runs/ledger）
+   */
+  outDir?: string;
+};
+
+/**
+ * 分诊命令结果
+ */
+export type RunTriageResult = {
+  /**
+   * 台账绝对路径
+   */
+  ledgerPath: string;
+
+  /**
+   * 台账对象
+   */
+  ledger: TriageLedgerFile;
+};
+
+/**
+ * 分诊台账落盘（append-only：triage-<时刻>.json 不覆盖历史）
+ *
+ * @param input - 命令入参
+ * @returns 台账绝对路径与台账对象
+ */
+export function runTriage(input: RunTriageInput): RunTriageResult {
+  /**
+   * 采集结果
+   */
+  const collected = collectRecords(input.root, input.config);
+
+  /**
+   * 台账条目（黄灯，B>C>A 分类）
+   */
+  const items: TriageItem[] = collected
+    .filter(({ record }) => record.status === 'yellow' || record.status === 'legacy-yellow')
+    .map(({ record, file }) => {
+      /**
+       * 分类结果
+       */
+      const classified = classifyIssue(record);
+
+      return {
+        id: record.id,
+        file,
+        status: record.status,
+        category: classified.category,
+        reason: classified.reason,
+        criteriaCommands: record.criteria?.criteria.map((c) => c.command) ?? [],
+      };
+    });
+
+  /**
+   * 台账对象
+   */
+  const ledger: TriageLedgerFile = {
+    generatedAtMs: Date.now(),
+    registryDirs: input.config.scopes.map((scope) => scope.registryDir),
+    items,
+  };
+
+  /**
+   * 台账目录
+   */
+  const ledgerDir = input.outDir ?? join(input.root, '.lzi', 'issues', 'runs', 'ledger');
+
+  mkdirSync(ledgerDir, { recursive: true });
+
+  /**
+   * 目标路径（时刻命名，append-only；同毫秒碰撞时顺延 +1 保证不覆盖）
+   */
+  let ledgerPath = join(ledgerDir, `triage-${ledger.generatedAtMs}.json`);
+
+  while (existsSync(ledgerPath) || existsSync(`${ledgerPath}.tmp`)) {
+    ledger.generatedAtMs += 1;
+    ledgerPath = join(ledgerDir, `triage-${ledger.generatedAtMs}.json`);
+  }
+
+  /**
+   * 临时路径（temp+rename 原子写）
+   */
+  const tempPath = `${ledgerPath}.tmp`;
+
+  writeFileSync(tempPath, `${JSON.stringify(ledger, null, 2)}\n`);
+
+  renameSync(tempPath, ledgerPath);
+
+  return { ledgerPath, ledger };
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * 引擎包入口
+ *
+ * 汇出格式真源、解析器、模板渲染、fs 基座、编号门禁、lint 与观测、收口与
+ * 冻结、证书库、引用检查、提示词全部引擎面。
+ */
+
+export * from './close/evidence-reader.utils.js';
+
+export * from './docs-refs/docs-refs.commands.js';
+
+export * from './prompts/prompts.commands.js';
+
+export * from './close/green-flip.commands.js';
+
+export * from './close/verify-close.commands.js';
+
+export * from './fs/mini-glob.utils.js';
+
+export * from './fs/walk-surface.utils.js';
+
+export * from './freeze/freeze.commands.js';
+
+export * from './health/health.commands.js';
+
+export * from './lint/lint-baseline.commands.js';
+
+export * from './lint/lint.core.js';
+
+export * from './normalize/normalize-header.commands.js';
+
+export * from './numbering/numbering.commands.js';
+
+export * from './numbering/numbering.core.js';
+
+export * from './parser/format.utils.js';
+
+export * from './parser/guide-fixture.utils.js';
+
+export * from './parser/registry.parser.js';
+
+export * from './template/issue-template.renderer.js';
+
+export * from './triage/triage.classify.js';
+
+export * from './vault/vault.commands.js';