@longzai-intelligence-readme/core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,254 @@
+import { LziReadmeExemption } from "@longzai-intelligence-readme/config";
+//#region src/types.d.ts
+/**
+ * 门禁引擎类型定义
+ */
+/**
+ * 违例级别：error 计入 exitCode 阻断；warn 为线索级报告不阻断（人工判定）
+ */
+type ReadmeSeverity = 'error' | 'warn';
+/**
+ * README 文件类别：仓库根 / 嵌套（packages、apps 下）
+ */
+type ReadmeFileKind = 'root' | 'nested';
+/**
+ * 单条违例
+ */
+type ReadmeViolation = {
+  /**
+   * 仓库相对 posix 路径（如 `README.md`、`packages/core/README.md`）
+   */
+  file: string;
+  /**
+   * 行号（1-based）；文件级规则（标题缺失等）为 null
+   */
+  line: number | null;
+  /**
+   * 规则标识（如 `E-BRAND-CN`、`W-MECH`）
+   */
+  rule: string;
+  /**
+   * 级别
+   */
+  severity: ReadmeSeverity;
+  /**
+   * 违例说明（含整改指引）
+   */
+  message: string;
+  /**
+   * 命中行摘录（截断；文件级规则缺省）
+   */
+  excerpt?: string;
+};
+/**
+ * 被豁免的违例（附豁免原因）
+ */
+type ReadmeExemptedViolation = ReadmeViolation & {
+  /**
+   * 豁免原因（来自配置登记，原样展示）
+   */
+  reason: string;
+};
+/**
+ * 扫描目标（发现器产出）
+ */
+type ReadmeScanTarget = {
+  /**
+   * 仓库相对 posix 路径
+   */
+  relPath: string;
+  /**
+   * 文件类别
+   */
+  kind: ReadmeFileKind;
+};
+/**
+ * 门禁汇总
+ */
+type ReadmeGateSummary = {
+  /**
+   * 扫描 README 文件数
+   */
+  filesScanned: number;
+  /**
+   * 根 README 数（0 或 1）
+   */
+  rootCount: number;
+  /**
+   * 嵌套 README 数
+   */
+  nestedCount: number;
+  /**
+   * error 违例数（豁免不计入）
+   */
+  errorCount: number;
+  /**
+   * warn 违例数（豁免不计入）
+   */
+  warnCount: number;
+  /**
+   * 豁免命中数
+   */
+  exemptedCount: number;
+};
+/**
+ * 门禁报告（text/json 格式化的唯一数据源）
+ */
+type ReadmeGateReport = {
+  /**
+   * 规则集版本（与规范草案版本绑定）
+   */
+  rulesVersion: string;
+  /**
+   * 规则依据指针（草案位置留痕）
+   */
+  specPointer: string;
+  /**
+   * 生效违例（error + warn，豁免已剔除）
+   */
+  violations: ReadmeViolation[];
+  /**
+   * 豁免命中的违例（单列展示）
+   */
+  exempted: ReadmeExemptedViolation[];
+  /**
+   * 汇总计数
+   */
+  summary: ReadmeGateSummary;
+};
+//#endregion
+//#region src/rules.d.ts
+/**
+ * 行级规则定义（逐行正则命中即报告）
+ */
+type ReadmeLineRule = {
+  /**
+   * 规则标识
+   */
+  id: string;
+  /**
+   * 级别
+   */
+  severity: ReadmeSeverity;
+  /**
+   * 命中正则（全局标志；实现层逐行新建实例探测）
+   */
+  pattern: RegExp;
+  /**
+   * 违例说明（含整改指引）
+   */
+  message: string;
+};
+/**
+ * error 行级规则表
+ *
+ * 覆盖草案 v2 负面清单 a–f、i–l 与品牌口径（标题级规则见 scan 层）。
+ */
+declare const ERROR_LINE_RULES: readonly ReadmeLineRule[];
+/**
+ * warn 行级规则表（草案 g/k 线索级：人工判定，不阻断）
+ */
+declare const WARN_LINE_RULES: readonly ReadmeLineRule[];
+/**
+ * 全部行级规则（error 在前，warn 在后）
+ */
+declare const LINE_RULES: readonly ReadmeLineRule[];
+/**
+ * 根标题合规形态：`# Longzai Intelligence <Name>`
+ */
+declare const ROOT_TITLE_PATTERN: RegExp;
+/**
+ * 一级标题行形态（用于定位根标题）
+ */
+declare const H1_HEADING_PATTERN: RegExp;
+/**
+ * 禁止段落标题（许可证/贡献——由 package.json 承载）
+ */
+declare const FORBIDDEN_SECTION_PATTERN: RegExp;
+/**
+ * 立项文体节标题（发布 README 精简口径，内部细节迁内部承接文件）
+ */
+declare const CHARTER_SECTION_PATTERN: RegExp;
+/**
+ * 结构树行形态（含树形字符）
+ */
+declare const TREE_LINE_PATTERN: RegExp;
+/**
+ * 结构树行内注释形态（树行 + 行内 # 注释）
+ */
+declare const TREE_ANNOTATED_PATTERN: RegExp;
+/**
+ * 结构树注释行数阈值（达到即报 E-TREE-ANNOTATED）
+ */
+declare const TREE_ANNOTATED_THRESHOLD = 3;
+/**
+ * 结构树总行数阈值（超过即报 E-TREE-LONG）
+ */
+declare const TREE_LONG_THRESHOLD = 40;
+/**
+ * 单规则单文件保留命中上限（防超长文件刷屏）
+ */
+declare const MAX_HITS_PER_RULE = 8;
+/**
+ * 摘录截断长度
+ */
+declare const EXCERPT_MAX_LENGTH = 120;
+//#endregion
+//#region src/discover.utils.d.ts
+/**
+ * 收集单仓全部 README 扫描目标
+ *
+ * @param repoRoot - 仓库根目录绝对路径
+ * @returns 扫描目标列表（根在前，嵌套按路径字典序）
+ */
+declare const collectReadmeTargets: (repoRoot: string) => ReadmeScanTarget[];
+//#endregion
+//#region src/scan.utils.d.ts
+/**
+ * 扫描单个 README 内容
+ *
+ * @param target - 扫描目标（相对路径 + 类别）
+ * @param content - README 全文
+ * @returns 违例清单（按行号升序）
+ */
+declare const scanReadmeContent: (target: ReadmeScanTarget, content: string) => ReadmeViolation[];
+//#endregion
+//#region src/gate.core.d.ts
+/**
+ * 门禁运行参数
+ */
+type RunReadmeGateOptions = {
+  /**
+   * 仓库根目录绝对路径
+   */
+  repoRoot: string;
+  /**
+   * 豁免登记列表（来自就地配置；缺省空）
+   */
+  exemptions?: LziReadmeExemption[];
+};
+/**
+ * 运行 README 门禁
+ *
+ * @param options - 门禁运行参数
+ * @returns 门禁报告（违例、豁免与汇总）
+ */
+declare const runReadmeGate: (options: RunReadmeGateOptions) => ReadmeGateReport;
+//#endregion
+//#region src/format-gate-report.utils.d.ts
+/**
+ * 渲染 text 形态报告
+ *
+ * @param report - 门禁报告
+ * @returns stdout 全文（不含汇总错误行——失败汇总由命令层写 stderr）
+ */
+declare const formatGateReport: (report: ReadmeGateReport) => string;
+/**
+ * 渲染 json 形态报告
+ *
+ * @param report - 门禁报告
+ * @returns JSON 全文（缩进 2 空格）
+ */
+declare const formatGateReportJson: (report: ReadmeGateReport) => string;
+//#endregion
+export { CHARTER_SECTION_PATTERN, ERROR_LINE_RULES, EXCERPT_MAX_LENGTH, FORBIDDEN_SECTION_PATTERN, H1_HEADING_PATTERN, LINE_RULES, MAX_HITS_PER_RULE, ROOT_TITLE_PATTERN, type ReadmeExemptedViolation, type ReadmeFileKind, type ReadmeGateReport, type ReadmeGateSummary, type ReadmeLineRule, type ReadmeScanTarget, type ReadmeSeverity, type ReadmeViolation, type RunReadmeGateOptions, TREE_ANNOTATED_PATTERN, TREE_ANNOTATED_THRESHOLD, TREE_LINE_PATTERN, TREE_LONG_THRESHOLD, WARN_LINE_RULES, collectReadmeTargets, formatGateReport, formatGateReportJson, runReadmeGate, scanReadmeContent };

package/dist/index.js

@@ -0,0 +1,3 @@
+import{readFileSync as e,readdirSync as t,statSync as n}from"node:fs";import{join as r}from"node:path";import{RULES_SPEC_POINTER as i,RULES_VERSION as a}from"@longzai-intelligence-readme/config";const o=[{id:`E-BRAND-CN`,severity:`error`,pattern:/龙智|龙仔智能|隆智|龙崽/g,message:`中文品牌译名——品牌唯一正确表达为 "Longzai Intelligence"，任何中文译名禁止`},{id:`E-SHORT-SCOPE`,severity:`error`,pattern:/@lzi\//g,message:`短 scope 包名——包名一律长形式 @longzai-intelligence-*`},{id:`E-BAD-ABBR`,severity:`error`,pattern:/\bLI\b|\bLZ\b/g,message:`禁用缩写——品牌缩写仅 LZI/lzi`},{id:`E-INTERNAL-NET`,severity:`error`,pattern:/\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3})\b|\b[\w-]+\.(?:local|internal|corp)\b/g,message:`内网地址/域名——README 按发布口径处理，不得含内网信息（示例也用占位形态）`},{id:`E-ABS-PATH`,severity:`error`,pattern:/\/Volumes\/|\/Users\/[A-Za-z0-9_-]+|\/home\/[A-Za-z0-9_-]+/g,message:`本机绝对路径——示例一律用 ~/ 或 <占位> 形态`},{id:`E-EMAIL`,severity:`error`,pattern:/[\w.+-]+@(?!([\w-]+\.)*example\.(?:com|org|net)\b)[A-Za-z][\w-]*(?:\.[\w-]+)*\.[A-Za-z]{2,}/g,message:`邮箱形态——README 不含联系方式（文档示例域 example.* 及其子域除外）`},{id:`E-CREDENTIAL`,severity:`error`,pattern:/(?:api[_-]?key|secret|passwd|password|token)\s*[:=]\s*(?!['"]?(?:your-|xxx|<))\S+/gi,message:`凭据形态——密钥/token/口令及其实值不得出现（占位示例除外）`},{id:`E-SCALE`,severity:`error`,pattern:/\d{2,}\s*个(?:子)?(?:项目|仓库|仓)/g,message:`内部规模数字（「N 个项目」类）——不入发布 README`},{id:`E-OPS`,severity:`error`,pattern:/\bbun\s+(?:push-all|push|version:upgrade-across|version:upgrade|agent:sync|vscode:sync)\b/g,message:`跨仓运维命令——产品群级操作不入 README`},{id:`E-ORG-COMPARE`,severity:`error`,pattern:/与\s*`?@longzai-intelligence-[a-z-]+`?(?:[、，]\s*`?@longzai-intelligence-[a-z-]+`?)*\s*同级/g,message:`内部组织结构对比表述——不入发布 README`},{id:`E-GIT-REMOTE`,severity:`error`,pattern:/git@[A-Za-z0-9.-]+:[\w./-]+|longzai-tech\b/g,message:`内部 git remote/组织账号/托管位置——不入 README`},{id:`E-DEV-CONSTRAINT`,severity:`error`,pattern:/禁止在[^，。\n]{0,12}(?:运行|执行)|请在(?:子包|各应用目录|应用目录|包目录|各仓)/g,message:`内部工程约束——面向仓内开发者的禁令/流程，迁内部承接文件`},{id:`E-MIT`,severity:`error`,pattern:/\[MIT\]|MIT License/gi,message:`MIT 表述——默认 UNLICENSED，禁默认 MIT`}],s=[{id:`W-MECH`,severity:`warn`,pattern:/\.lzi\/|\.lzi\b|lzi-architecture(?:\.sample)?\.yaml|docs\/ledgers|lzi-[a-z-]+\.config\.ts/g,message:`内部治理机制命名/路径（线索级，人工判定；机制即本仓产品者可豁免登记）`},{id:`W-TOOL`,severity:`warn`,pattern:/\blzi-(?:builder|projects|dev-cli|release|env|git|decision|issues|vscode|agent|npm-registry|bun)\b/g,message:`内部工具名（线索级，人工判定）`},{id:`W-ADR`,severity:`warn`,pattern:/ADR[\s-]?\d{3,4}/g,message:`ADR 编号引用（线索级，人工判定；指向本仓决策记录者可豁免登记）`}],c=[...o,...s],l=/^#\s+Longzai Intelligence(\s|$)/,u=/^#\s+/,d=/^#{1,3}\s*(?:许可证|贡献|License|Contributing)\s*$/,f=/^#{1,3}\s*(?:创建初衷|工作范围)\s*$/,p=/[│├└]/,m=/#\s+\S/,h=3,g=40,_=8,v=120,y=/* @__PURE__ */ new Set([`node_modules`,`dist`,`out`,`.turbo`,`.git`,`build`,`.next`,`coverage`,`.cache`,`target`,`.venv`]),b=[`packages`,`apps`],x=e=>{let t=[];C(r(e,`README.md`))&&t.push({relPath:`README.md`,kind:`root`});for(let n of b){let i=r(e,n);w(i)&&S(i,n,0,t)}return t},S=(e,n,i,a)=>{if(i>3)return;let o;try{o=t(e,{withFileTypes:!0})}catch{return}for(let t of o){if(y.has(t.name))continue;let o=`${n}/${t.name}`;t.isDirectory()?S(r(e,t.name),o,i+1,a):t.isFile()&&t.name===`README.md`&&a.push({relPath:o,kind:`nested`})}},C=e=>{try{return n(e).isFile()}catch{return!1}},w=e=>{try{return n(e).isDirectory()}catch{return!1}},T=(e,t)=>{let n=[],r=t.split(`
+`);return n.push(...E(e.relPath,r)),n.push(...D(e,r)),n.sort((e,t)=>(e.line??0)-(t.line??0)),n},E=(e,t)=>{let n=[];for(let r of c){let i=0;for(let a=0;a<t.length&&i<8;a+=1){let o=t[a];if(o===void 0)break;new RegExp(r.pattern.source,r.pattern.flags).test(o)&&(n.push({file:e,line:a+1,rule:r.id,severity:r.severity,message:r.message,excerpt:A(o)}),i+=1)}}return n},D=(e,t)=>{let n=[];e.kind===`root`&&n.push(...O(e.relPath,t));let r=t.map((e,t)=>({line:e,number:t+1})).filter(e=>d.test(e.line));for(let t of r)n.push({file:e.relPath,line:t.number,rule:`E-FORBIDDEN-SECTION`,severity:`error`,message:`许可证/贡献段落——由 package.json 承载，README 不设该段`,excerpt:A(t.line)});let i=t.map((e,t)=>({line:e,number:t+1})).filter(e=>f.test(e.line));for(let t of i)n.push({file:e.relPath,line:t.number,rule:`E-CHARTER-SECTION`,severity:`error`,message:`立项文体节（创建初衷/工作范围）——发布 README 精简口径，内部细节迁内部承接文件`,excerpt:A(t.line)});return n.push(...k(e.relPath,t)),n},O=(e,t)=>{let n=t.findIndex(e=>u.test(e)),r=n===-1?void 0:t[n];return r!==void 0&&l.test(r)?[]:[{file:e,line:n===-1?null:n+1,rule:`E-ROOT-TITLE`,severity:`error`,message:"根标题须为 `# Longzai Intelligence <Name>`——缺品牌前缀/纯中文/仓库名或包名充当标题均不合规",excerpt:r===void 0?void 0:A(r)}]},k=(e,t)=>{let n=[],r=t.map((e,t)=>({line:e,number:t+1})).filter(e=>p.test(e.line));if(r.length===0)return n;let i=r.filter(e=>m.test(e.line));return i.length>=3&&n.push({file:e,line:i[0]?.number??null,rule:`E-TREE-ANNOTATED`,severity:`error`,message:`结构树逐行注释（${i.length} 行）——树只表达层级，职责在正文说明`,excerpt:i[0]===void 0?void 0:A(i[0].line)}),r.length>40&&n.push({file:e,line:r[0]?.number??null,rule:`E-TREE-LONG`,severity:`error`,message:`结构树过长（${r.length} 行 > 40）——发布 README 精简口径`,excerpt:r[0]===void 0?void 0:A(r[0].line)}),n},A=e=>{let t=e.trim();return t.length>120?`${t.slice(0,120)}…`:t},j=t=>{let n=t.exemptions??[],o=x(t.repoRoot),s=[];for(let n of o){let i=null;try{i=e(r(t.repoRoot,n.relPath),`utf8`)}catch{continue}s.push(...T(n,i))}let c=e=>{for(let t of n)if(t.file===e.file&&t.rule===e.rule)return t;return null},l=[],u=[];for(let e of s){let t=c(e);t===null?l.push(e):u.push({...e,reason:t.reason})}return{rulesVersion:a,specPointer:i,violations:l,exempted:u,summary:{filesScanned:o.length,rootCount:o.filter(e=>e.kind===`root`).length,nestedCount:o.filter(e=>e.kind===`nested`).length,errorCount:l.filter(e=>e.severity===`error`).length,warnCount:l.filter(e=>e.severity===`warn`).length,exemptedCount:u.length}}},M=e=>{let t=[];t.push(`[INFO] readme:check 规则版本 ${e.rulesVersion}`),t.push(`[INFO] 依据 ${e.specPointer}`),t.push(`[INFO] 扫描 README ${e.summary.filesScanned} 个（根 ${e.summary.rootCount}、嵌套 ${e.summary.nestedCount}）`);for(let n of e.violations)t.push(N(n));for(let n of e.exempted)t.push(P(n));return e.summary.errorCount===0?t.push(`[SUCCESS] readme:check 通过（0 error、${e.summary.warnCount} warn、豁免 ${e.summary.exemptedCount}）`):t.push(`✖ ${e.summary.errorCount} error、${e.summary.warnCount} warn（豁免 ${e.summary.exemptedCount}）`),t.join(`
+`)},N=e=>{let t=e.line===null?e.file:`${e.file}:${e.line}`,n=e.excerpt===void 0?``:`｜摘录：${e.excerpt}`;return`${t} [${e.rule}] ${e.message}${n}`},P=e=>`[豁免] ${e.line===null?e.file:`${e.file}:${e.line}`} [${e.rule}]（原因：${e.reason}）`,F=e=>JSON.stringify(e,null,2);export{f as CHARTER_SECTION_PATTERN,o as ERROR_LINE_RULES,v as EXCERPT_MAX_LENGTH,d as FORBIDDEN_SECTION_PATTERN,u as H1_HEADING_PATTERN,c as LINE_RULES,_ as MAX_HITS_PER_RULE,l as ROOT_TITLE_PATTERN,m as TREE_ANNOTATED_PATTERN,h as TREE_ANNOTATED_THRESHOLD,p as TREE_LINE_PATTERN,g as TREE_LONG_THRESHOLD,s as WARN_LINE_RULES,x as collectReadmeTargets,M as formatGateReport,F as formatGateReportJson,j as runReadmeGate,T as scanReadmeContent};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@longzai-intelligence-readme/core",
+  "version": "0.0.1",
+  "description": "Longzai Intelligence README 门禁引擎（发布口径规则集、README 发现器、报告）",
+  "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"
+  },
+  "dependencies": {
+    "@longzai-intelligence-readme/config": "0.0.1",
+    "zod": "^4.4.3"
+  }
+}