@longzai-intelligence-ledger/core 0.0.1

package/README.md

@@ -0,0 +1,5 @@
+# @longzai-intelligence-ledger/core
+
+Longzai Intelligence Ledger 校验引擎：台账族文件面盘点、六类规则、编排执行与 eslint 风格报告。机制域零仓库知识，阈值与豁免由调用方经完整选项注入。
+
+主导出契约：`runLedgerCheck`、`resolveLedgerCheckOptions`、`collectLedgerFileSet`、`formatLedgerCheckReport`、六类规则函数、`matchesAnyGlob`、markdown 行级工具。

package/dist/index.d.ts

@@ -0,0 +1,387 @@
+//#region src/ledger-check.types.d.ts
+/**
+ * 台账形态校验违例
+ *
+ * 单条违例对应一行 eslint 风格报告，severity 当前仅有 error 一级
+ */
+type LedgerViolation = {
+  /**
+   * 违例文件路径，相对仓库根
+   */
+  file: string;
+  /**
+   * 违例行号，一基
+   *
+   * 文件级违例时为 null
+   */
+  line: number | null;
+  /**
+   * 规则标识
+   *
+   * line-width、workstream-size、status-vocabulary、commit-hash、link-resolution、temp-path 六类
+   */
+  ruleId: string;
+  /**
+   * 违例说明，中文完整短句
+   */
+  message: string;
+};
+/**
+ * 台账形态校验解析后的完整选项
+ *
+ * 由局部配置与默认值合并而成，引擎只消费完整形态
+ */
+type ResolvedLedgerCheckOptions = {
+  /**
+   * 仓库根绝对路径
+   */
+  repoRoot: string;
+  /**
+   * 台账族根目录，相对仓库根
+   */
+  ledgersRoot: string;
+  /**
+   * 单行最大字符数
+   */
+  maxLineLength: number;
+  /**
+   * 工作流档最大行数
+   */
+  maxWorkstreamLines: number;
+  /**
+   * 工作流档最大字节数
+   */
+  maxWorkstreamBytes: number;
+  /**
+   * 合法状态词表，默认词表与配置附加词表的并集
+   */
+  statusVocabulary: string[];
+  /**
+   * 体量豁免 glob 清单，相对台账族根
+   */
+  sizeExemptGlobs: string[];
+  /**
+   * 临时路径豁免 glob 清单，相对台账族根
+   */
+  tmpPathAllowGlobs: string[];
+  /**
+   * 哈希禁令豁免 glob 清单，相对台账族根
+   */
+  hashExemptGlobs: string[];
+};
+/**
+ * 台账族文件盘点条目
+ */
+type LedgerFileEntry = {
+  /**
+   * 文件绝对路径
+   */
+  absolutePath: string;
+  /**
+   * 文件路径，相对仓库根，恒以 posix 分隔符表达
+   */
+  relativePath: string;
+  /**
+   * 文件全文
+   */
+  content: string;
+};
+/**
+ * 台账族文件面分类结果
+ */
+type LedgerFileSet = {
+  /**
+   * 索引位文件清单
+   *
+   * 各账 ledger.md 与 workstreams 目录内全部 markdown 档
+   */
+  indexFiles: LedgerFileEntry[];
+  /**
+   * 工作流档清单
+   *
+   * workstreams 目录内的三 位编号档，不含目录 README
+   */
+  workstreamFiles: LedgerFileEntry[];
+  /**
+   * 台账族内全部 markdown 文件，封存面除外
+   */
+  allFiles: LedgerFileEntry[];
+};
+/**
+ * 台账形态校验结果
+ */
+type LedgerCheckResult = {
+  /**
+   * 违例清单，按文件路径与行号排序
+   */
+  violations: LedgerViolation[];
+  /**
+   * 扫描文件计数
+   */
+  summary: {
+    /**
+     * 扫描的 markdown 文件总数
+     */
+    files: number;
+    /**
+     * 索引位文件数
+     */
+    indexFiles: number;
+    /**
+     * 违例总数
+     */
+    errors: number;
+  };
+};
+/**
+ * 规则消费的源文件入参形态
+ *
+ * 各规则统一消费相对路径与全文内容，不触磁盘
+ */
+type LedgerSourceFile = {
+  /**
+   * 文件路径，相对仓库根
+   */
+  relativePath: string;
+  /**
+   * 文件全文
+   */
+  content: string;
+};
+//#endregion
+//#region src/default-options.constants.d.ts
+/**
+ * 默认单行最大字符数
+ */
+declare const DEFAULT_MAX_LINE_LENGTH = 400;
+/**
+ * 默认工作流档最大行数
+ */
+declare const DEFAULT_MAX_WORKSTREAM_LINES = 100;
+/**
+ * 默认工作流档最大字节数
+ */
+declare const DEFAULT_WORKSTREAM_BYTES = 16000;
+/**
+ * 默认台账族根目录，相对仓库根
+ */
+declare const DEFAULT_LEDGERS_ROOT = "docs/ledgers";
+/**
+ * 默认状态词表
+ */
+declare const DEFAULT_STATUS_VOCABULARY: string[];
+/**
+ * 校验选项局部输入形态
+ *
+ * 全部字段可省略，省略项沿用默认值
+ */
+type PartialLedgerCheckOptions = {
+  repoRoot: string;
+  ledgersRoot?: string;
+  maxLineLength?: number;
+  maxWorkstreamLines?: number;
+  maxWorkstreamBytes?: number;
+  extraStatusVocabulary?: string[];
+  sizeExemptGlobs?: string[];
+  tmpPathAllowGlobs?: string[];
+  hashExemptGlobs?: string[];
+};
+/**
+ * 解析校验选项
+ *
+ * 将局部选项与默认值合并为引擎消费的完整形态
+ *
+ * @param options - 局部校验选项，仅 repoRoot 必填
+ * @returns 完整校验选项
+ */
+declare const resolveLedgerCheckOptions: (options: PartialLedgerCheckOptions) => ResolvedLedgerCheckOptions;
+//#endregion
+//#region src/glob-match.utils.d.ts
+/**
+ * glob 匹配工具
+ *
+ * 支持 `**` 跨段、`*` 单段与 `?` 单字符三类通配，覆盖台账豁免清单的声明需求
+ * 其余字符按字面匹配，分隔符恒按 posix 形态比较
+ */
+/**
+ * 判断路径是否命中任一 glob
+ *
+ * @param relativePath - 相对路径，posix 分隔符形态
+ * @param globs - glob 清单
+ * @returns 命中任一表达式时为 true
+ */
+declare const matchesAnyGlob: (relativePath: string, globs: string[]) => boolean;
+//#endregion
+//#region src/markdown.utils.d.ts
+/**
+ * markdown 行级工具
+ *
+ * 供各规则消费，统一围栏代码块的豁免口径
+ */
+/**
+ * 标记各行是否处于围栏代码块内
+ *
+ * 围栏判定只识别行首三连反引号形态，与台账族书写习惯一致
+ *
+ * @param lines - 文件全文按行拆分后的数组
+ * @returns 与行数等长的布尔数组，true 表示该行在围栏内
+ */
+declare const markFencedLines: (lines: string[]) => boolean[];
+/**
+ * 单行字符数
+ *
+ * 按码点计数，中文与半角字符均计一字符
+ *
+ * @param line - 单行文本
+ * @returns 码点数
+ */
+declare const countLineLength: (line: string) => number;
+/**
+ * 提取单行内全部 markdown 链接目标
+ *
+ * 识别行内链接与图片的目标段，锚点链接与空目标不返回
+ *
+ * @param line - 单行文本
+ * @returns 链接目标数组，按出现顺序排列
+ */
+declare const extractLinkTargets: (line: string) => string[];
+//#endregion
+//#region src/scan.utils.d.ts
+/**
+ * 盘点台账族文件面
+ *
+ * @param repoRoot - 仓库根绝对路径
+ * @param ledgersRoot - 台账族根目录，相对仓库根
+ * @returns 分类后的文件面
+ * @throws {@link Error} 当台账族根不存在时抛出
+ */
+declare const collectLedgerFileSet: (repoRoot: string, ledgersRoot: string) => LedgerFileSet;
+/**
+ * 判断是否为索引位文件
+ *
+ * 各账 ledger.md 与 workstreams 目录内全部 markdown 档
+ *
+ * @param relativePath - 相对仓库根路径
+ * @param ledgersRoot - 台账族根目录
+ * @returns 索引位文件为 true
+ */
+declare const isIndexFile: (relativePath: string, ledgersRoot: string) => boolean;
+/**
+ * 判断是否为工作流档
+ *
+ * workstreams 目录内以三位编号命名的档，目录 README 不计
+ *
+ * @param relativePath - 相对仓库根路径
+ * @param ledgersRoot - 台账族根目录
+ * @returns 工作流档为 true
+ */
+declare const isWorkstreamFile: (relativePath: string, ledgersRoot: string) => boolean;
+//#endregion
+//#region src/check-commit-hash.rule.d.ts
+/**
+ * 检查索引位文件提交哈希
+ *
+ * @param file - 文件条目
+ * @param ledgersRoot - 台账族根目录
+ * @param hashExemptGlobs - 哈希禁令豁免清单
+ * @returns 违例清单
+ */
+declare const checkCommitHash: (file: LedgerSourceFile, ledgersRoot: string, hashExemptGlobs: string[]) => LedgerViolation[];
+//#endregion
+//#region src/check-line-width.rule.d.ts
+/**
+ * 检查索引位文件行宽
+ *
+ * @param file - 文件条目
+ * @param maxLineLength - 单行最大字符数
+ * @returns 违例清单
+ */
+declare const checkLineWidth: (file: LedgerSourceFile, maxLineLength: number) => LedgerViolation[];
+//#endregion
+//#region src/check-link-resolution.rule.d.ts
+/**
+ * 检查索引位文件链接可解析性
+ *
+ * @param file - 文件条目
+ * @param repoRoot - 仓库根绝对路径
+ * @returns 违例清单
+ */
+declare const checkLinkResolution: (file: LedgerSourceFile, repoRoot: string) => LedgerViolation[];
+//#endregion
+//#region src/check-status-vocabulary.rule.d.ts
+/**
+ * 检查总账聚合表状态列
+ *
+ * 仅检查 ledger.md 内表头含状态列的表格
+ *
+ * @param file - 总账文件条目
+ * @param statusVocabulary - 合法状态词表
+ * @returns 违例清单
+ */
+declare const checkStatusVocabulary: (file: LedgerSourceFile, statusVocabulary: string[]) => LedgerViolation[];
+//#endregion
+//#region src/check-temp-path.rule.d.ts
+/**
+ * 检查文件临时路径引用
+ *
+ * @param file - 文件条目
+ * @param ledgersRoot - 台账族根目录
+ * @param tmpPathAllowGlobs - 临时路径豁免清单
+ * @returns 违例清单
+ */
+declare const checkTempPath: (file: LedgerSourceFile, ledgersRoot: string, tmpPathAllowGlobs: string[]) => LedgerViolation[];
+//#endregion
+//#region src/check-workstream-size.rule.d.ts
+/**
+ * 检查单个工作流档体量
+ *
+ * @param file - 文件条目
+ * @param options - 体量阈值与豁免清单，globs 以台账族内相对路径表达
+ * @returns 违例清单
+ */
+declare const checkWorkstreamSize: (file: LedgerSourceFile, options: WorkstreamSizeOptions) => LedgerViolation[];
+/**
+ * 体量规则选项
+ */
+type WorkstreamSizeOptions = {
+  /**
+   * 台账族根目录
+   */
+  ledgersRoot: string;
+  /**
+   * 工作流档最大行数
+   */
+  maxWorkstreamLines: number;
+  /**
+   * 工作流档最大字节数
+   */
+  maxWorkstreamBytes: number;
+  /**
+   * 体量豁免清单
+   */
+  sizeExemptGlobs: string[];
+};
+//#endregion
+//#region src/run-ledger-check.utils.d.ts
+/**
+ * 执行台账形态校验
+ *
+ * @param options - 完整校验选项
+ * @returns 校验结果，含违例清单与扫描计数
+ * @throws {@link Error} 当台账族根不存在时由盘点环节抛出
+ */
+declare const runLedgerCheck: (options: ResolvedLedgerCheckOptions) => LedgerCheckResult;
+//#endregion
+//#region src/format-report.utils.d.ts
+/**
+ * 格式化校验报告
+ *
+ * @param result - 校验结果
+ * @param options - 格式化选项，rootLabel 为报告头展示的仓库根标签
+ * @returns 报告全文，无违例时为通过短语
+ */
+declare const formatLedgerCheckReport: (result: LedgerCheckResult, options?: {
+  rootLabel?: string;
+}) => string;
+//#endregion
+export { DEFAULT_LEDGERS_ROOT, DEFAULT_MAX_LINE_LENGTH, DEFAULT_MAX_WORKSTREAM_LINES, DEFAULT_STATUS_VOCABULARY, DEFAULT_WORKSTREAM_BYTES, type LedgerCheckResult, type LedgerFileEntry, type LedgerFileSet, type LedgerViolation, type PartialLedgerCheckOptions, type ResolvedLedgerCheckOptions, checkCommitHash, checkLineWidth, checkLinkResolution, checkStatusVocabulary, checkTempPath, checkWorkstreamSize, collectLedgerFileSet, countLineLength, extractLinkTargets, formatLedgerCheckReport, isIndexFile, isWorkstreamFile, markFencedLines, matchesAnyGlob, resolveLedgerCheckOptions, runLedgerCheck };

package/dist/index.js

@@ -0,0 +1,9 @@
+import{existsSync as e,readFileSync as t,readdirSync as n}from"node:fs";import{dirname as r,isAbsolute as i,join as a,normalize as o,relative as s,resolve as c,sep as l}from"node:path";const u=400,d=100,f=16e3,p=`docs/ledgers`,m=[`待建档`,`待启动`,`进行中`,`已收口`,`不适用`],h=e=>({repoRoot:e.repoRoot,ledgersRoot:e.ledgersRoot??`docs/ledgers`,maxLineLength:e.maxLineLength??400,maxWorkstreamLines:e.maxWorkstreamLines??100,maxWorkstreamBytes:e.maxWorkstreamBytes??16e3,statusVocabulary:[...m,...e.extraStatusVocabulary??[]],sizeExemptGlobs:e.sizeExemptGlobs??[],tmpPathAllowGlobs:e.tmpPathAllowGlobs??[],hashExemptGlobs:e.hashExemptGlobs??[]}),g=e=>{let t=``,n=0;for(;n<e.length;){let r=e.charAt(n);if(r===`*`){if(e.startsWith(`**`,n)){t+=`.*`,n+=2;continue}t+=`[^/]*`,n+=1;continue}if(r===`?`){t+=`[^/]`,n+=1;continue}t+=r.replace(/[\\^$.+()[\]{}|]/gu,`\\$&`),n+=1}return RegExp(`^(?:${t})$`,`u`)},_=(e,t)=>t.some(t=>g(t).test(e)),v=e=>{let t=[],n=!1;for(let r of e){if(/^\s*```/.test(r)){t.push(!1),n=!n;continue}t.push(n)}return t},y=e=>Array.from(e).length,b=e=>{let t=[],n=e.replaceAll(/`[^`]*`/gu,``);for(let e of n.matchAll(/\]\(([^)]*)\)/gu)){let n=e[1]?.trim()??``;n===``||n.startsWith(`#`)||t.push(n)}return t},x=/* @__PURE__ */ new Set([`archives`,`node_modules`,`dist`,`.turbo`,`.git`,`out`,`coverage`]),S=(e,r)=>{let i=a(e,r),o=[],c=r=>{for(let i of n(r,{withFileTypes:!0})){if(i.isDirectory()){if(x.has(i.name))continue;c(a(r,i.name));continue}if(!i.name.endsWith(`.md`))continue;let n=a(r,i.name);o.push({absolutePath:n,relativePath:s(e,n).split(l).join(`/`),content:t(n,`utf8`)})}};return c(i),{indexFiles:o.filter(e=>C(e.relativePath,r)),workstreamFiles:o.filter(e=>w(e.relativePath,r)),allFiles:o}},C=(e,t)=>{let n=T(e,t);return n===null?!1:/^[^/]+\/ledger\.md$/.test(n)?!0:/^[^/]+\/workstreams\/[^/]+\.md$/.test(n)},w=(e,t)=>{let n=T(e,t);return n!==null&&/^[^/]+\/workstreams\/\d{3}[^/]*\.md$/.test(n)},T=(e,t)=>{let n=`${t.replace(/\/$/u,``)}/`;return e.startsWith(n)?e.slice(n.length):null},E=/\b(?=[0-9a-f]{7,40}\b)(?=[0-9a-f]*[a-f])[0-9a-f]{7,40}\b/gu,D=(e,t,n)=>{let r=e.relativePath.startsWith(`${t}/`)?e.relativePath.slice(t.length+1):e.relativePath;if(_(r,n))return[];let i=[],a=e.content.split(`
+`),o=v(a);return a.forEach((t,n)=>{if(o[n]===!0)return;let r=t.match(E)??[];for(let t of r)i.push({file:e.relativePath,line:n+1,ruleId:`commit-hash`,message:`索引面出现提交哈希 ${t}，证据指针请归逐仓档`})}),i},O=(e,t)=>{let n=[],r=e.content.split(`
+`),i=v(r);return r.forEach((r,a)=>{if(i[a]===!0)return;let o=y(r);o>t&&n.push({file:e.relativePath,line:a+1,ruleId:`line-width`,message:`单行 ${o} 字符超过上限 ${t} 字符，请拆条或下沉明细`})}),n},k=(e,t)=>{let n=[],r=e.content.split(`
+`),i=v(r);return r.forEach((r,a)=>{if(i[a]!==!0)for(let i of b(r)){if(A(i))continue;let r=i.split(`#`)[0]?.trim()??``;r!==``&&(j(r,e.relativePath,t)||n.push({file:e.relativePath,line:a+1,ruleId:`link-resolution`,message:`链接目标 ${r} 不存在，请修正或改为指针文本`}))}}),n},A=e=>/^(https?:|mailto:|tel:)/iu.test(e)?!0:e.includes(`xxx`),j=(t,n,a)=>{let s=c(a,r(n),t);if(e(s))return!0;let l=i(t)?c(a,`.${t}`):c(a,t);return l.startsWith(`${a}${a.endsWith(`/`)?``:`/`}`)===!1||e(l)||o(s)===o(l)},M=/^已并入 \d{3}$/u,N=/* @__PURE__ */ new Set([``,`—`,`——`]),P=(e,t)=>{let n=[],r=e.content.split(`
+`),i=null;return r.forEach((r,a)=>{if(!r.trimStart().startsWith(`|`)){i=null;return}let o=F(r);if(i===null){let e=o.findIndex(e=>e.trim()===`状态`);e!==-1&&!I(o)&&(i=e);return}if(I(o))return;let s=o[i]?.trim()??``;L(s,t)||n.push({file:e.relativePath,line:a+1,ruleId:`status-vocabulary`,message:`聚合表状态值「${s}」未命中词表，详细状态描述请归逐仓档`})}),n},F=e=>e.trim().replace(/^\|/u,``).replace(/\|$/u,``).split(`|`),I=e=>e.every(e=>/^[-: ]*$/.test(e.trim())),L=(e,t)=>N.has(e)||M.test(e)?!0:t.includes(e),R=[`/tmp/`,`/private/tmp/`,`/var/folders/`],z=(e,t,n)=>{let r=e.relativePath.startsWith(`${t}/`)?e.relativePath.slice(t.length+1):e.relativePath;if(_(r,n))return[];let i=[];return e.content.split(`
+`).forEach((t,n)=>{let r=R.find(e=>t.includes(e));r!==void 0&&i.push({file:e.relativePath,line:n+1,ruleId:`temp-path`,message:`引用临时目录路径 ${r}，临时产物路径不入台账`})}),i},B=(e,t)=>{let n=e.relativePath.startsWith(`${t.ledgersRoot}/`)?e.relativePath.slice(t.ledgersRoot.length+1):e.relativePath;if(_(n,t.sizeExemptGlobs))return[];let r=[],i=e.content.split(`
+`).length,a=Buffer.byteLength(e.content,`utf8`);return i>t.maxWorkstreamLines&&r.push({file:e.relativePath,line:null,ruleId:`workstream-size`,message:`工作流档 ${i} 行超过上限 ${t.maxWorkstreamLines} 行，请拆分下沉`}),a>t.maxWorkstreamBytes&&r.push({file:e.relativePath,line:null,ruleId:`workstream-size`,message:`工作流档 ${a} 字节超过上限 ${t.maxWorkstreamBytes} 字节，请拆分下沉`}),r},V=e=>{let t=S(e.repoRoot,e.ledgersRoot),n=[];for(let r of t.indexFiles)n.push(...O(r,e.maxLineLength)),n.push(...D(r,e.ledgersRoot,e.hashExemptGlobs)),n.push(...k(r,e.repoRoot));for(let r of t.workstreamFiles)n.push(...B(r,{ledgersRoot:e.ledgersRoot,maxWorkstreamLines:e.maxWorkstreamLines,maxWorkstreamBytes:e.maxWorkstreamBytes,sizeExemptGlobs:e.sizeExemptGlobs}));for(let r of t.allFiles)r.relativePath.endsWith(`/ledger.md`)&&n.push(...P(r,e.statusVocabulary)),n.push(...z(r,e.ledgersRoot,e.tmpPathAllowGlobs));return n.sort((e,t)=>e.file===t.file?(e.line??0)-(t.line??0):e.file<t.file?-1:1),{violations:n,summary:{files:t.allFiles.length,indexFiles:t.indexFiles.length,errors:n.length}}},H=(e,t={})=>{let n=[];if(e.violations.length===0)return n.push(`台账形态门禁通过：扫描 ${e.summary.files} 份 markdown，索引位 ${e.summary.indexFiles} 份，零违例`),n.join(`
+`);for(let t of e.violations){let e=t.line===null?t.file:`${t.file}:${t.line}`;n.push(`${e} [${t.ruleId}] ${t.message}`)}return t.rootLabel!==void 0&&n.push(`仓库根：${t.rootLabel}`),n.push(`台账形态门禁未通过：违例 ${e.summary.errors} 项，扫描 ${e.summary.files} 份 markdown，索引位 ${e.summary.indexFiles} 份`),n.join(`
+`)};export{p as DEFAULT_LEDGERS_ROOT,u as DEFAULT_MAX_LINE_LENGTH,d as DEFAULT_MAX_WORKSTREAM_LINES,m as DEFAULT_STATUS_VOCABULARY,f as DEFAULT_WORKSTREAM_BYTES,D as checkCommitHash,O as checkLineWidth,k as checkLinkResolution,P as checkStatusVocabulary,z as checkTempPath,B as checkWorkstreamSize,S as collectLedgerFileSet,y as countLineLength,b as extractLinkTargets,H as formatLedgerCheckReport,C as isIndexFile,w as isWorkstreamFile,v as markFencedLines,_ as matchesAnyGlob,h as resolveLedgerCheckOptions,V as runLedgerCheck};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@longzai-intelligence-ledger/core",
+  "version": "0.0.1",
+  "description": "Longzai Intelligence Ledger 台账形态校验引擎",
+  "keywords": [
+    "ledger",
+    "lint",
+    "longzai-intelligence",
+    "rules"
+  ],
+  "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": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "clean": "lzi-dev-cli clean"
+  }
+}