@longzai-intelligence-records/ledger 0.0.1

package/src/lint/lint.core.ts

@@ -0,0 +1,228 @@
+/**
+ * records lint 核（判定全部基于解析器产物——口径单一真源）
+ *
+ * 规则面：文件名形态 / H1（含编号一致性）/ 记录日期行（含真实日历日）/ 来源
+ * 行。存量豁免走棘轮基线（file + rule 逐条登记，只许缩短——基线外的旧违例
+ * 依旧拦截，不放大豁免面）。records 无分型，故无任何分型节校验（decisions/021）。
+ */
+
+import type { LziRecordsConfig } from '@longzai-intelligence-records/config';
+
+import { readFileSync } from 'node:fs';
+import { posix } from 'node:path';
+
+import { scanRecordsDir } from '@/fs/scan-registry.utils';
+import { isRealCalendarDate, RECORD_FILENAME_PATTERN } from '@/parser/format.utils';
+import { parseRecordDoc } from '@/parser/record.parser';
+
+/**
+ * lint 违例条目
+ */
+export type RecordsLintViolation = {
+  /**
+   * 规则名
+   */
+  rule: string;
+
+  /**
+   * 文件（posix 相对仓库根）
+   */
+  file: string;
+
+  /**
+   * 行号（1 起算）
+   */
+  line: number;
+
+  /**
+   * 违例消息
+   */
+  message: string;
+};
+
+/**
+ * lint 结果
+ */
+export type RecordsLintResult = {
+  /**
+   * 基线豁免后的违例列表
+   */
+  violations: RecordsLintViolation[];
+
+  /**
+   * 扫描文件数
+   */
+  fileCount: number;
+
+  /**
+   * 基线豁免命中数（棘轮观测面）
+   */
+  exemptedCount: number;
+};
+
+/**
+ * lint 入参
+ */
+export type RecordsLintInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 解析后配置
+   */
+  config: LziRecordsConfig;
+};
+
+/**
+ * 运行 lint（全 scope 注册表；只读）
+ *
+ * @param input - lint 入参
+ * @returns lint 结果（违例空 = 通过）
+ */
+export function runRecordsLint(input: RecordsLintInput): RecordsLintResult {
+  /**
+   * 原始违例列表
+   */
+  const raw: RecordsLintViolation[] = [];
+
+  /**
+   * 豁免命中数
+   */
+  let exemptedCount = 0;
+
+  for (const scope of input.config.scopes) {
+    /**
+     * 注册表绝对目录
+     */
+    const dirAbs = joinPosixSafe(input.root, scope.registryDir);
+
+    /**
+     * 扫描条目
+     */
+    const entries = scanRecordsDir(dirAbs);
+
+    for (const entry of entries) {
+      /**
+       * 文件相对路径（posix，与基线登记口径一致）
+       */
+      const fileRel = posix.join(scope.registryDir, entry.basename);
+
+      /**
+       * 文件名形态判定
+       */
+      const filenameMatch = RECORD_FILENAME_PATTERN.exec(entry.basename);
+
+      if (filenameMatch === null) {
+        raw.push({
+          rule: 'R-FILENAME',
+          file: fileRel,
+          line: 0,
+          message: `文件名须为「NNNN-<slug>.md」（编号 3-4 位零填充 + ASCII kebab）`,
+        });
+
+        continue;
+      }
+
+      /**
+       * 解析结果
+       */
+      const parsed = parseRecordDoc(readFileSync(entry.absPath, 'utf8'));
+
+      if (parsed.record === null) {
+        for (const issue of parsed.issues) {
+          raw.push({ rule: 'R-H1', file: fileRel, line: issue.line, message: issue.message });
+        }
+
+        continue;
+      }
+
+      /**
+       * H1 编号与文件名编号一致性
+       */
+      if (parsed.record.number !== filenameMatch[1]) {
+        raw.push({
+          rule: 'R-H1-NUMBER',
+          file: fileRel,
+          line: 1,
+          message: `H1 编号「${parsed.record.number}」与文件名编号「${filenameMatch[1]}」不一致`,
+        });
+      }
+
+      /**
+       * 记录日期行判定（缺席或非真实日历日）
+       */
+      if (parsed.record.date === null) {
+        raw.push({
+          rule: 'R-DATE-LINE',
+          file: fileRel,
+          line: parsed.record.headerEndLine + 1,
+          message: '头部缺「> 记录日期：YYYY-MM-DD」元数据行',
+        });
+      } else if (!isRealCalendarDate(parsed.record.date)) {
+        raw.push({
+          rule: 'R-DATE-REAL',
+          file: fileRel,
+          line: 2,
+          message: `记录日期「${parsed.record.date}」非真实日历日期`,
+        });
+      }
+
+      /**
+       * 来源行判定
+       */
+      if (parsed.record.source === null) {
+        raw.push({
+          rule: 'R-SOURCE-LINE',
+          file: fileRel,
+          line: parsed.record.headerEndLine + 1,
+          message: '头部缺「> 来源：<出处>」元数据行',
+        });
+      }
+    }
+  }
+
+  /**
+   * 基线豁免（file + rule 精确命中即豁免；豁免面只许缩短）
+   */
+  const baselineKeys = new Set(
+    input.config.lint.baseline.map((entry) => `${entry.file}|${entry.rule}`),
+  );
+
+  /**
+   * 豁免后违例列表
+   */
+  const violations = raw.filter((violation) => {
+    /**
+     * 豁免命中标记
+     */
+    const hit = baselineKeys.has(`${violation.file}|${violation.rule}`);
+
+    if (hit) {
+      exemptedCount += 1;
+    }
+
+    return !hit;
+  });
+
+  return {
+    violations,
+    fileCount: input.config.scopes.reduce(
+      (count, scope) => count + scanRecordsDir(joinPosixSafe(input.root, scope.registryDir)).length,
+      0,
+    ),
+    exemptedCount,
+  };
+}
+
+/**
+ * 拼接注册表绝对目录（posix 段拼接 + 根锚定）
+ *
+ * @param root - 仓库根绝对路径
+ * @param registryDir - 注册表目录（posix 相对）
+ * @returns 绝对路径
+ */
+function joinPosixSafe(root: string, registryDir: string): string {
+  return `${root.replace(/\/+$/, '')}/${registryDir}`;
+}

package/src/parser/format.utils.ts

@@ -0,0 +1,151 @@
+/**
+ * records 格式口径单一真源
+ *
+ * 全部格式口径（文件名形态、H1 形态、头部元数据行、占位符）集中于此模块。
+ * 读侧（解析器 / lint / 索引差量）与写侧（模板渲染）共用同一真源，杜绝两套
+ * 口径漂移——create 产物在构造上天然通过 lint。
+ *
+ * records 定位（decisions/021）：广义降级 fallback 通道，无语义分型——格式面
+ * 只有头部元数据强制（记录日期 / 来源 / 可选关联），正文自由格式、无固定节。
+ */
+
+/**
+ * 文件名形态（编号 3-4 位零填充 + ASCII kebab slug + .md）
+ */
+export const RECORD_FILENAME_PATTERN = /^(\d{3,4})-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$/;
+
+/**
+ * slug 合法形态（ASCII kebab，小写字母/数字/连字符——与 issues 家族口径一致）
+ */
+export const ASCII_KEBAB_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * H1 形态（编号入 H1，em dash 分隔——产品群 records 主流形态）
+ */
+export const RECORD_H1_PATTERN = /^# (\d{3,4}) — (.+)$/;
+
+/**
+ * 记录日期行形态（blockquote 元数据，YYYY-MM-DD）
+ */
+export const DATE_LINE_PATTERN = /^> 记录日期：(\d{4}-\d{2}-\d{2})$/;
+
+/**
+ * 来源行形态（blockquote 元数据，非空）
+ */
+export const SOURCE_LINE_PATTERN = /^> 来源：(.+)$/;
+
+/**
+ * 关联行形态（blockquote 元数据，可选行，非空）
+ */
+export const REF_LINE_PATTERN = /^> 关联：(.+)$/;
+
+/**
+ * 头部元数据键：记录日期
+ */
+export const DATE_LINE_KEY = '记录日期';
+
+/**
+ * 头部元数据键：来源
+ */
+export const SOURCE_LINE_KEY = '来源';
+
+/**
+ * 头部元数据键：关联
+ */
+export const REF_LINE_KEY = '关联';
+
+/**
+ * 正文占位符（建档即骨架，内容随工作回填）
+ */
+export const SECTION_PLACEHOLDER = '（待补充）';
+
+/**
+ * 正文自由格式指引行（渲染产物与骨架共享——fallback 通道定位的显式声明）
+ */
+export const BODY_GUIDANCE =
+  '（正文自由格式——所有不清楚归属、被去除的内容都落此通道；无分型，无固定节）';
+
+/**
+ * 索引行引用形态（README 索引行中的注册表文件链接——非全局模式，
+ * matchAll 消费侧自建全局实例，避免模块级正则共享 lastIndex 状态）
+ */
+export const INDEX_LINK_PATTERN =
+  /\[?\d{3,4}[^\]\n]*\]?\(\.\/(\d{3,4})-([a-z0-9]+(?:-[a-z0-9]+)*)\.md\)/;
+
+/**
+ * 正则捕获组安全取值（守卫形态——替代非空断言；未命中即内部口径错误）
+ *
+ * @param match - 正则命中结果
+ * @param index - 捕获组下标
+ * @returns 捕获组值
+ * @throws {@link Error} 未命中或捕获组越界（格式口径与调用侧失配）
+ */
+export function captureGroup(match: RegExpMatchArray | null, index: number): string {
+  if (match === null || match[index] === undefined) {
+    throw new Error(`正则捕获组 ${index} 未命中（格式口径内部错误）`);
+  }
+
+  return match[index];
+}
+
+/**
+ * 提取 README 内容中的注册表引用集（编号 → slug，重复引用以后者为准）
+ *
+ * @param content - README 全文
+ * @returns 编号键 → slug 映射
+ */
+export function extractIndexRefs(content: string): Map<string, string> {
+  /**
+   * 引用集
+   */
+  const refs = new Map<string, string>();
+
+  for (const match of content.matchAll(new RegExp(INDEX_LINK_PATTERN.source, 'g'))) {
+    refs.set(captureGroup(match, 1), captureGroup(match, 2));
+  }
+
+  return refs;
+}
+
+/**
+ * 从文件名提取编号键（宽口径：任何 `NNNN-*` 形态的 .md 基名）
+ *
+ * @param basename - 文件基名
+ * @returns 编号键（数字字符串原样）；非编号形态为 null
+ */
+export function extractRecordKey(basename: string): string | null {
+  /**
+   * 宽口径命中（数字前缀 + 连字符）
+   */
+  const match = /^(\d{1,4})[-._]/.exec(basename);
+
+  return match === null ? null : captureGroup(match, 1);
+}
+
+/**
+ * 判定日期字符串是否为真实存在的日历日期（YYYY-MM-DD）
+ *
+ * @param date - 日期字符串
+ * @returns 真实日历日期为 true
+ */
+export function isRealCalendarDate(date: string): boolean {
+  /**
+   * 年 / 月 / 日数值
+   */
+  const [year, month, day] = date.split('-').map((part) => Number.parseInt(part, 10));
+
+  if (year === undefined || month === undefined || day === undefined) {
+    return false;
+  }
+
+  /**
+   * 构造日期（JS Date 会对越界日/月进位——进位即非法）
+   */
+  const constructed = new Date(Date.UTC(year, month - 1, day));
+
+  return (
+    constructed.getUTCFullYear() === year &&
+    constructed.getUTCMonth() === month - 1 &&
+    constructed.getUTCDate() === day
+  );
+}

package/src/parser/record.parser.ts

@@ -0,0 +1,202 @@
+/**
+ * record 文档解析器
+ *
+ * 判定全部基于本解析器产物（口径单一真源 format.utils）。解析头部：H1（编号
+ * 入 H1）+ blockquote 元数据行（记录日期 / 来源 / 可选关联）；正文自由格式
+ * 不解析（无分型——decisions/021）。
+ */
+
+import {
+  captureGroup,
+  DATE_LINE_KEY,
+  DATE_LINE_PATTERN,
+  RECORD_H1_PATTERN,
+  REF_LINE_KEY,
+  REF_LINE_PATTERN,
+  SOURCE_LINE_KEY,
+  SOURCE_LINE_PATTERN,
+} from '@/parser/format.utils';
+
+/**
+ * 解析后的 record 头部
+ */
+export type ParsedRecord = {
+  /**
+   * H1 编号（数字字符串原样）
+   */
+  number: string;
+
+  /**
+   * H1 标题
+   */
+  title: string;
+
+  /**
+   * 记录日期（YYYY-MM-DD）
+   */
+  date: string | null;
+
+  /**
+   * 来源
+   */
+  source: string | null;
+
+  /**
+   * 关联（可选行缺席为 null）
+   */
+  ref: string | null;
+
+  /**
+   * 头部元数据结束行号（1 起算；正文起始参考）
+   */
+  headerEndLine: number;
+};
+
+/**
+ * 解析问题条目（行级）
+ */
+export type RecordParseIssue = {
+  /**
+   * 行号（1 起算；0 = 全文级）
+   */
+  line: number;
+
+  /**
+   * 问题消息
+   */
+  message: string;
+};
+
+/**
+ * 解析结果
+ */
+export type RecordParseResult = {
+  /**
+   * 解析后的头部（H1 非法时为 null）
+   */
+  record: ParsedRecord | null;
+
+  /**
+   * 解析问题列表（空 = 合法建档态）
+   */
+  issues: RecordParseIssue[];
+};
+
+/**
+ * 解析 record 文档全文
+ *
+ * @param content - 文档全文
+ * @returns 解析结果：头部字段 + 行级问题（骨架建档态 = 占位值可解析、无问题）
+ */
+export function parseRecordDoc(content: string): RecordParseResult {
+  /**
+   * 行列表
+   */
+  const lines = content.split('\n');
+
+  /**
+   * 问题列表
+   */
+  const issues: RecordParseIssue[] = [];
+
+  /**
+   * H1 命中（首行必须为合法 H1）
+   */
+  const h1Match = RECORD_H1_PATTERN.exec(lines[0] ?? '');
+
+  if (h1Match === null) {
+    issues.push({
+      line: 1,
+      message: `首行须为「# NNNN — 标题」形态 H1（编号入 H1，em dash 分隔）`,
+    });
+
+    return { record: null, issues };
+  }
+
+  /**
+   * 元数据命中集（键 → 值）
+   */
+  const meta = new Map<string, string>();
+
+  /**
+   * 头部扫描行号（H1 后自第 2 行起，直到非空非 blockquote 行止）
+   */
+  let cursor = 1;
+
+  while (cursor < lines.length) {
+    /**
+     * 当前行
+     */
+    const line = lines[cursor] ?? '';
+
+    if (line.trim() === '') {
+      cursor += 1;
+
+      continue;
+    }
+
+    /**
+     * 记录日期行命中
+     */
+    const dateMatch = DATE_LINE_PATTERN.exec(line);
+
+    if (dateMatch !== null) {
+      meta.set(DATE_LINE_KEY, captureGroup(dateMatch, 1));
+      cursor += 1;
+
+      continue;
+    }
+
+    /**
+     * 来源行命中
+     */
+    const sourceMatch = SOURCE_LINE_PATTERN.exec(line);
+
+    if (sourceMatch !== null) {
+      meta.set(SOURCE_LINE_KEY, captureGroup(sourceMatch, 1));
+      cursor += 1;
+
+      continue;
+    }
+
+    /**
+     * 关联行命中
+     */
+    const refMatch = REF_LINE_PATTERN.exec(line);
+
+    if (refMatch !== null) {
+      meta.set(REF_LINE_KEY, captureGroup(refMatch, 1));
+      cursor += 1;
+
+      continue;
+    }
+
+    break;
+  }
+
+  /**
+   * 记录日期缺席判定
+   */
+  if (!meta.has(DATE_LINE_KEY)) {
+    issues.push({ line: cursor + 1, message: `头部缺「> ${DATE_LINE_KEY}：YYYY-MM-DD」元数据行` });
+  }
+
+  /**
+   * 来源缺席判定
+   */
+  if (!meta.has(SOURCE_LINE_KEY)) {
+    issues.push({ line: cursor + 1, message: `头部缺「> ${SOURCE_LINE_KEY}：<出处>」元数据行` });
+  }
+
+  return {
+    record: {
+      number: captureGroup(h1Match, 1),
+      title: captureGroup(h1Match, 2),
+      date: meta.get(DATE_LINE_KEY) ?? null,
+      source: meta.get(SOURCE_LINE_KEY) ?? null,
+      ref: meta.get(REF_LINE_KEY) ?? null,
+      headerEndLine: cursor,
+    },
+    issues,
+  };
+}