@longzai-intelligence-issues/ledger 0.0.1

package/src/docs-refs/docs-refs.commands.ts

@@ -0,0 +1,693 @@
+/**
+ * docs 引用检查与机械修复（check / fix）
+ *
+ * 扫描 docs.scanRoots 的 markdown，提取 issue 引用 token（编号 / 编号+slug /
+ * 不完整 slug 前缀）；全 scope 按 (scopeKey, number) 查找，带 slug 段先精确后
+ * 前缀；0 命中→doc-ref-unknown，>1→doc-ref-ambiguous（列候选），前缀唯一→
+ * 通过（不完整 slug 引用支持）。fix 对唯一前缀机械展开完整 slug；独立棘轮基线。
+ */
+
+import type { LintBaselineEntry, LziIssuesConfig } from '@longzai-intelligence-issues/config';
+
+import { renderBaselineRegeneratedConfig } from '@longzai-intelligence-issues/config';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { walkFilesUnderRoots } from '@/fs/walk-surface.utils';
+import { scanRegistryDir } from '@/parser/registry.parser';
+
+/**
+ * docs 检查入参
+ */
+export type DocsCheckInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * 跳过基线豁免（write-baseline 再生口径）
+   */
+  ignoreBaseline?: boolean;
+};
+
+/**
+ * docs 修带入参
+ */
+export type DocsFixInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * 只呈现不落盘
+   */
+  dryRun?: boolean;
+};
+
+/**
+ * docs 修复结果
+ */
+export type DocsFixResult = {
+  /**
+   * 已修复文件清单
+   */
+  fixedFiles: string[];
+
+  /**
+   * 拒绝项清单（待人工面，存在即 exit 1 语义）
+   */
+  refused: DocRefViolation[];
+};
+
+/**
+ * docs 基线再生命令入参
+ */
+export type DocsBaselineInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * 收编指针
+   */
+  issuePointer: string;
+};
+
+/**
+ * docs 基线再生结果
+ */
+export type DocsBaselineResult =
+  | { ok: true; content: string; entryCount: number }
+  | { ok: false; error: string };
+
+/**
+ * docs 引用违例
+ */
+export type DocRefViolation = {
+  /**
+   * 引用所在文件仓库相对 posix 路径
+   */
+  file: string;
+
+  /**
+   * 行号（1 起）
+   */
+  line: number;
+
+  /**
+   * 列号（1 起）
+   */
+  column: number;
+
+  /**
+   * 规则名（doc-ref-unknown / doc-ref-ambiguous / baseline-stale）
+   */
+  rule: string;
+
+  /**
+   * 违规消息
+   */
+  message: string;
+};
+
+/**
+ * docs 引用检查结果
+ */
+export type DocRefCheckResult = {
+  /**
+   * 违例列表（active + baseline-stale）
+   */
+  violations: DocRefViolation[];
+
+  /**
+   * 基线豁免计数
+   */
+  suppressed: number;
+
+  /**
+   * 扫描文件数
+   */
+  scannedFiles: number;
+};
+
+/**
+ * 引用 token 提取模式（`[0035]` / `[0035-slug]` / `[0035-slug](./0035-slug.md)`）
+ */
+const DOC_REF_TOKEN_PATTERN = /\[([0-9]{3,4})(?:-([a-z0-9-]+))?\]/g;
+
+/**
+ * 注册表索引条目
+ */
+type RegistryIndexEntry = {
+  /**
+   * scope key
+   */
+  scopeKey: string;
+
+  /**
+   * 编号
+   */
+  number: string;
+
+  /**
+   * 完整 slug
+   */
+  slug: string;
+};
+
+/**
+ * 候选解析结果
+ */
+type RefResolution =
+  | { kind: 'ok' }
+  | { kind: 'unknown'; message: string }
+  | { kind: 'ambiguous'; message: string };
+
+/**
+ * 构建全 scope 注册表索引
+ *
+ * @param root - 仓库根绝对路径
+ * @param config - 解析后配置
+ * @returns 索引条目列表
+ */
+function buildRegistryIndex(root: string, config: LziIssuesConfig): RegistryIndexEntry[] {
+  return config.scopes.flatMap((scope) =>
+    scanRegistryDir(join(root, scope.registryDir)).map((record) => ({
+      scopeKey: scope.key,
+      number: record.id,
+      slug: record.slug,
+    })),
+  );
+}
+
+/**
+ * 解析引用 token（先精确后前缀；跨 scope 多义列候选）
+ *
+ * @param tokenNumber - 引用编号
+ * @param tokenSlug - 引用 slug 段（可空）
+ * @param index - 注册表索引
+ * @returns 解析结果
+ */
+function resolveRefToken(
+  tokenNumber: string,
+  tokenSlug: string | null,
+  index: readonly RegistryIndexEntry[],
+): RefResolution {
+  /**
+   * 同编号候选集
+   */
+  const numberMatches = index.filter((entry) => entry.number === tokenNumber);
+
+  if (numberMatches.length === 0) {
+    return { kind: 'unknown', message: `引用编号 ${tokenNumber} 在全部 scope 中无命中` };
+  }
+
+  /**
+   * slug 精确命中集
+   */
+  const exact = tokenSlug === null ? [] : numberMatches.filter((entry) => entry.slug === tokenSlug);
+
+  if (exact.length === 1) {
+    return { kind: 'ok' };
+  }
+
+  /**
+   * slug 前缀命中集（不完整 slug 引用支持）
+   */
+  const prefixed =
+    tokenSlug === null
+      ? numberMatches
+      : numberMatches.filter((entry) => entry.slug.startsWith(tokenSlug));
+
+  if (prefixed.length === 1) {
+    return { kind: 'ok' };
+  }
+
+  if (prefixed.length === 0) {
+    return {
+      kind: 'unknown',
+      message: `引用 ${tokenNumber}-${tokenSlug} 在 scope 候选集中无 slug 命中（编号命中：${numberMatches.map((e) => `${e.scopeKey}/${e.number}-${e.slug}`).join('、')}）`,
+    };
+  }
+
+  return {
+    kind: 'ambiguous',
+    message: `引用 ${tokenNumber}${tokenSlug === null ? '' : `-${tokenSlug}`} 命中不唯一——候选：${prefixed.map((e) => `${e.scopeKey}/${e.number}-${e.slug}`).join('、')}（请展开完整 slug 或注明 scope）`,
+  };
+}
+
+/**
+ * docs 引用检查
+ *
+ * @param input - 命令入参
+ * @param input.root - 仓库根绝对路径
+ * @param input.config - 解析后配置
+ * @param input.ignoreBaseline - 跳过基线豁免（write-baseline 再生口径）
+ * @returns 检查结果
+ * @throws {@link Error} 配置未登记 docs 节
+ */
+export function runDocsCheck(input: DocsCheckInput): DocRefCheckResult {
+  if (input.config.docs === undefined) {
+    throw new Error('配置未登记 docs 节（docs.scanRoots）——docs 引用检查显式拒绝隐式扫描面');
+  }
+
+  /**
+   * 注册表索引
+   */
+  const index = buildRegistryIndex(input.root, input.config);
+
+  /**
+   * 违例收集器（基线前）
+   */
+  const raw: DocRefViolation[] = [];
+
+  /**
+   * 扫描文件数
+   */
+  let scannedFiles = 0;
+
+  for (const scanRoot of input.config.docs.scanRoots) {
+    /**
+     * 扫描根下文件列表（严格遍历缺根抛错 + 排除剪枝）
+     */
+    const files = walkFilesUnderRoots(join(input.root, scanRoot), {
+      excludeGlobs: input.config.docs.exclusions.map((entry) => entry.glob),
+    });
+
+    scannedFiles += files.length;
+
+    for (const file of files) {
+      if (!input.config.docs.includeExtensions.some((ext) => file.endsWith(ext))) {
+        continue;
+      }
+
+      /**
+       * 文档全文
+       */
+      const content = readFileSync(join(input.root, scanRoot, file), 'utf8');
+
+      /**
+       * 行起点偏移列表
+       */
+      const lineStarts = computeLineStarts(content);
+
+      /**
+       * 相对扫描根的路径（基线键口径）
+       */
+      const relFile = scanRoot === '' ? file : `${scanRoot}/${file}`;
+
+      /**
+       * token 全局匹配游标
+       */
+      const pattern = new RegExp(DOC_REF_TOKEN_PATTERN.source, 'g');
+
+      /**
+       * 当前 token 命中（全局游标逐次推进）
+       */
+      let match = pattern.exec(content);
+
+      while (match !== null) {
+        /**
+         * 引用编号与 slug 段
+         */
+        const tokenNumber = match[1] ?? '';
+
+        /**
+         * 引用 slug 段（纯编号引用为 null）
+         */
+        const tokenSlug = match[2] ?? null;
+
+        /**
+         * 解析结果
+         */
+        const resolution = resolveRefToken(tokenNumber, tokenSlug, index);
+
+        if (resolution.kind !== 'ok') {
+          /**
+           * 命中位置（行 1 起 / 列 1 起）
+           */
+          const located = locateOffset(lineStarts, match.index ?? 0);
+
+          /**
+           * 违例登记
+           */
+          raw.push({
+            file: relFile,
+            line: located.line,
+            column: located.column,
+            rule: resolution.kind === 'unknown' ? 'doc-ref-unknown' : 'doc-ref-ambiguous',
+            message: resolution.message,
+          });
+        }
+
+        match = pattern.exec(content);
+      }
+    }
+  }
+
+  /**
+   * 基线查找表
+   */
+  const baseline = new Map<string, LintBaselineEntry>(
+    (input.config.docs.baseline ?? []).map((entry) => [`${entry.file}::${entry.rule}`, entry]),
+  );
+
+  if (input.ignoreBaseline === true) {
+    return { violations: raw, suppressed: 0, scannedFiles };
+  }
+
+  /**
+   * active 违例
+   */
+  const active: DocRefViolation[] = [];
+
+  /**
+   * 豁免计数
+   */
+  let suppressed = 0;
+
+  /**
+   * 命中基线键集合
+   */
+  const matchedKeys = new Set<string>();
+
+  for (const violation of raw) {
+    /**
+     * 基线键
+     */
+    const key = `${violation.file}::${violation.rule}`;
+
+    if (baseline.has(key)) {
+      suppressed += 1;
+      matchedKeys.add(key);
+
+      continue;
+    }
+
+    active.push(violation);
+  }
+
+  /**
+   * stale 基线条目
+   */
+  const stale: DocRefViolation[] = [...baseline.entries()]
+    .filter(([key]) => !matchedKeys.has(key))
+    .map(([key, entry]) => ({
+      file: key.split('::')[0] ?? '',
+      line: 0,
+      column: 0,
+      rule: 'baseline-stale',
+      message: `docs 基线条目已无对应现行违规——棘轮只许缩短，须同步删除该条目（收编指针：${entry.issue}）`,
+    }));
+
+  return {
+    violations: [...active, ...stale].sort(
+      (a, b) => a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule),
+    ),
+    suppressed,
+    scannedFiles,
+  };
+}
+
+/**
+ * docs 引用机械修复（唯一前缀展开为完整 slug）
+ *
+ * @param input - 命令入参
+ * @param input.root - 仓库根绝对路径
+ * @param input.config - 解析后配置
+ * @param input.dryRun - 只呈现不落盘
+ * @returns 修复结果（fixed / refused 清单；存在 refused 即 exit 1 语义）
+ * @throws {@link Error} 配置未登记 docs 节
+ */
+export function runDocsFix(input: DocsFixInput): DocsFixResult {
+  if (input.config.docs === undefined) {
+    throw new Error('配置未登记 docs 节（docs.scanRoots）——docs 修复显式拒绝隐式扫描面');
+  }
+
+  /**
+   * 注册表索引
+   */
+  const index = buildRegistryIndex(input.root, input.config);
+
+  /**
+   * 修复文件清单
+   */
+  const fixedFiles: string[] = [];
+
+  /**
+   * 拒绝项清单（待人工面）
+   */
+  const refused: DocRefViolation[] = [];
+
+  for (const scanRoot of input.config.docs.scanRoots) {
+    /**
+     * 扫描根下文件列表
+     */
+    const files = walkFilesUnderRoots(join(input.root, scanRoot), {
+      excludeGlobs: input.config.docs.exclusions.map((entry) => entry.glob),
+    });
+
+    for (const file of files) {
+      if (!input.config.docs.includeExtensions.some((ext) => file.endsWith(ext))) {
+        continue;
+      }
+
+      /**
+       * 文档全文
+       */
+      const content = readFileSync(join(input.root, scanRoot, file), 'utf8');
+
+      /**
+       * token 编辑列表（逆序应用防偏移漂移）
+       */
+      const edits: Array<{ start: number; end: number; replacement: string }> = [];
+
+      /**
+       * token 全局匹配游标
+       */
+      const pattern = new RegExp(DOC_REF_TOKEN_PATTERN.source, 'g');
+
+      /**
+       * 当前 token 命中（全局游标逐次推进）
+       */
+      let match = pattern.exec(content);
+
+      while (match !== null) {
+        /**
+         * 引用编号与 slug 段
+         */
+        const tokenNumber = match[1] ?? '';
+
+        /**
+         * 引用 slug 段（纯编号引用为 null）
+         */
+        const tokenSlug = match[2] ?? null;
+
+        if (tokenSlug !== null) {
+          /**
+           * 前缀唯一命中
+           */
+          const prefixed = index.filter(
+            (entry) => entry.number === tokenNumber && entry.slug.startsWith(tokenSlug),
+          );
+
+          if (prefixed.length > 1) {
+            /**
+             * 位置定位
+             */
+            const located = locateOffset(computeLineStarts(content), match.index ?? 0);
+
+            refused.push({
+              file,
+              line: located.line,
+              column: located.column,
+              rule: 'refused',
+              message: `引用 ${tokenNumber}-${tokenSlug} 前缀命中不唯一，无法机械归位（候选：${prefixed.map((e) => `${e.scopeKey}/${e.number}-${e.slug}`).join('、')}）——需人工核定`,
+            });
+          } else if (prefixed.length === 1 && prefixed[0]?.slug !== tokenSlug) {
+            /**
+             * 完整展开编辑（label 段替换，其余文本逐字节不动）
+             */
+            edits.push({
+              start: match.index ?? 0,
+              end: (match.index ?? 0) + match[0].length,
+              replacement: `[${tokenNumber}-${prefixed[0]?.slug}]`,
+            });
+          }
+        }
+
+        match = pattern.exec(content);
+      }
+
+      if (edits.length === 0) {
+        continue;
+      }
+
+      /**
+       * 修复产物（逆序编辑）
+       */
+      let fixed = content;
+
+      for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+        fixed = `${fixed.slice(0, edit.start)}${edit.replacement}${fixed.slice(edit.end)}`;
+      }
+
+      if (input.dryRun !== true && fixed !== content) {
+        writeFileSync(join(input.root, scanRoot, file), fixed);
+
+        fixedFiles.push(file);
+      } else if (input.dryRun === true) {
+        fixedFiles.push(file);
+      }
+    }
+  }
+
+  return { fixedFiles, refused };
+}
+
+/**
+ * docs 基线再生命令核（拒绝扩基线）
+ *
+ * @param input - 命令入参
+ * @param input.root - 仓库根绝对路径
+ * @param input.config - 解析后配置
+ * @param input.issuePointer - 收编指针
+ * @returns 再生结果
+ * @throws {@link Error} 配置未登记 docs 节
+ */
+export function runWriteDocsBaseline(input: DocsBaselineInput): DocsBaselineResult {
+  if (input.config.docs === undefined) {
+    throw new Error('配置未登记 docs 节——无法再生 docs 基线');
+  }
+
+  if (input.issuePointer.trim() === '') {
+    return { ok: false, error: '再生须携带非空 --issue <指针>（收编盖章）' };
+  }
+
+  /**
+   * 全集违例（跳过基线口径）
+   */
+  const raw = runDocsCheck({
+    root: input.root,
+    config: input.config,
+    ignoreBaseline: true,
+  }).violations;
+
+  /**
+   * 旧基线键集合
+   */
+  const oldKeys = new Set(
+    (input.config.docs.baseline ?? []).map((entry) => `${entry.file}::${entry.rule}`),
+  );
+
+  /**
+   * 基线外新增违规
+   */
+  const newOutside = raw.filter((v) => !oldKeys.has(`${v.file}::${v.rule}`));
+
+  if (newOutside.length > 0) {
+    return {
+      ok: false,
+      error: `存在 ${newOutside.length} 项基线外新增违规，拒绝再生（先处置新增违规后再收编存量）：\n${newOutside
+        .slice(0, 10)
+        .map((v) => `${v.file}:${v.line} [${v.rule}]`)
+        .join('\n')}`,
+    };
+  }
+
+  /**
+   * 再生条目
+   */
+  const entries: LintBaselineEntry[] = raw.map((v) => ({
+    file: v.file,
+    rule: v.rule,
+    issue: input.issuePointer,
+  }));
+
+  return {
+    ok: true,
+    content: renderBaselineRegeneratedConfig(input.config, 'docs', entries),
+    entryCount: entries.length,
+  };
+}
+
+/**
+ * 计算行起点偏移列表
+ *
+ * @param content - 文档全文
+ * @returns 每行起始偏移列表
+ */
+function computeLineStarts(content: string): number[] {
+  /**
+   * 行起点收集器（首行起点 0）
+   */
+  const starts = [0];
+
+  for (let index = 0; index < content.length; index += 1) {
+    if (content[index] === '\n') {
+      starts.push(index + 1);
+    }
+  }
+
+  return starts;
+}
+
+/**
+ * 行列定位结果（1 起）
+ */
+type LineColumn = {
+  /**
+   * 行号
+   */
+  line: number;
+
+  /**
+   * 列号
+   */
+  column: number;
+};
+
+/**
+ * 偏移定位行列（1 起）
+ *
+ * @param lineStarts - 行起点列表
+ * @param offset - 字符偏移
+ * @returns 行与列
+ */
+function locateOffset(lineStarts: readonly number[], offset: number): LineColumn {
+  /**
+   * 命中行下标（二分语义：最后一个不大于 offset 的起点）
+   */
+  let lineIndex = 0;
+
+  for (let index = 0; index < lineStarts.length; index += 1) {
+    if ((lineStarts[index] ?? 0) <= offset) {
+      lineIndex = index;
+    } else {
+      break;
+    }
+  }
+
+  return {
+    line: lineIndex + 1,
+    column: offset - (lineStarts[lineIndex] ?? 0) + 1,
+  };
+}