@longzai-intelligence-docs/compile-plugin 0.0.0-stage → 0.0.15

package/dist/index.d.ts

@@ -0,0 +1,512 @@
+import "./rolldown-runtime-BqT_7tdF.js";
+import * as z from "zod";
+//#region src/compile.plugin.d.ts
+/**
+ * compile 内置插件
+ *
+ * 文档派生域的一方插件即 items 真源合成与工具面抽取与快照新鲜度校验，
+ * 契约承 ADR 0131，对外经 definePlugin 声明四命令，宿主经内置插件列表
+ * 装载，外部联邦装载同样可用
+ */
+/**
+ * compile 内置插件定义
+ */
+declare const compilePlugin: import("@longzai-intelligence-docs/core").DocsPlugin;
+//#endregion
+//#region src/compile-config.schema.d.ts
+/**
+ * compile 插件配置 schema 即整体缺省
+ */
+declare const CompilePluginConfigSchema: z.ZodDefault<z.ZodObject<{
+  sourceRoot: z.ZodDefault<z.ZodString>;
+  documents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    output: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    toolFace: z.ZodDefault<z.ZodBoolean>;
+    exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  }, z.core.$strip>>>;
+  toolFace: z.ZodDefault<z.ZodObject<{
+    bins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    invocations: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
+/**
+ * compile 插件配置即解析后形态
+ */
+type CompilePluginConfig = z.output<typeof CompilePluginConfigSchema>;
+/**
+ * compile 插件配置书写形态
+ */
+type CompilePluginConfigInput = z.input<typeof CompilePluginConfigSchema>;
+/**
+ * 解析 compile 插件配置
+ *
+ * @param input - 宿主注入的 plugins.compile.options 节
+ * @returns 解析后配置，未书写时节为整体缺省
+ * @throws {@link Error} 配置违反 schema 时
+ */
+declare const parseCompilePluginConfig: (input: unknown) => CompilePluginConfig;
+//#endregion
+//#region src/check/finding-types.d.ts
+/**
+ * 校验与上报共用类型
+ */
+/**
+ * compile 违规类别
+ */
+type CompileFindingKind = 'snapshot-missing' | 'snapshot-stale' | 'anchor-missing' | 'command-not-found';
+/**
+ * 单条 compile 违规
+ */
+type CompileFinding = {
+  /**
+   * 违规类别
+   */
+  kind: CompileFindingKind;
+  /**
+   * 违规报文，含定位与处置指引
+   */
+  message: string;
+};
+//#endregion
+//#region src/check/compile-check.core.d.ts
+/**
+ * 执行 compile 校验
+ *
+ * @param root - 仓库根目录绝对路径
+ * @param config - 解析后的插件配置
+ * @returns 违规清单，空即全绿
+ * @throws {@link Error} 扫描或条目元信息非法时由建模上抛
+ */
+declare const runCompileCheck: (root: string, config: CompilePluginConfig) => Promise<readonly CompileFinding[]>;
+//#endregion
+//#region src/scan/frontmatter.utils.d.ts
+/**
+ * 条目元信息解析后形态
+ *
+ * 五键均未声明时对应字段为 `null`，零元数据条目完全正常
+ */
+type ItemMeta = {
+  /**
+   * 稳定身份键，未声明时为 `null`
+   */
+  id: string | null;
+  /**
+   * 条目类型提示串，未声明时为 `null`
+   */
+  type: string | null;
+  /**
+   * 标题提示串，未声明时为 `null`
+   */
+  title: string | null;
+  /**
+   * 锚定的源码文件路径即仓库根相对路径，未声明时为 `null`
+   */
+  anchor: string | null;
+  /**
+   * 锚定的命令定义名，未声明时为 `null`
+   */
+  command: string | null;
+};
+//#endregion
+//#region src/scan/items-scan.core.d.ts
+/**
+ * 文档内产出条目
+ */
+type SourceItem = {
+  /**
+   * 条目文件名即文档目录内相对路径
+   */
+  fileName: string;
+  /**
+   * 定序键即文件名数值前缀
+   */
+  order: number;
+  /**
+   * 条目文件解析出的元信息
+   */
+  meta: ItemMeta;
+  /**
+   * 正文，已去尾空白
+   */
+  body: string;
+};
+/**
+ * 文档条目解析入参
+ */
+type ResolveDocumentItemsInput = {
+  /**
+   * 文档目录绝对路径
+   */
+  documentDir: string;
+  /**
+   * 文档目录名
+   */
+  documentName: string;
+  /**
+   * 真源根的仓库根相对显示路径
+   */
+  sourceRootLabel: string;
+  /**
+   * 该文档的排除 glob 集合
+   */
+  exclude: readonly string[];
+};
+/**
+ * 解析单文档目录下全部产出条目
+ *
+ * 文件名数值前缀强制，无前缀即报错，同目录数值重复即报错，正文空白即剔除
+ * 暂存，exclude 以 glob 匹配条目文件名整串命中即整条目排除，产出按前缀数值
+ * 升序，文档目录不存在时返回空集即零条目文档为正常态
+ *
+ * @param input - 解析入参
+ * @returns 按前缀数值升序排列的产出条目列表
+ * @throws {@link Error} 条目文件名无数值前缀、前缀数值重复或元信息非法时
+ */
+declare const resolveDocumentItems: (input: ResolveDocumentItemsInput) => Promise<readonly SourceItem[]>;
+//#endregion
+//#region src/scan/manifest-scan.utils.d.ts
+/**
+ * manifest 面扫描
+ *
+ * 读取仓库根 package.json 的清单四字段即 name 与 description 与 version 与
+ * bin，作为产物头部身份信息与工具面 bin 缺省来源
+ */
+/**
+ * manifest 面形态
+ */
+type ManifestFace = {
+  /**
+   * 包名
+   */
+  name: string | null;
+  /**
+   * 包描述
+   */
+  description: string | null;
+  /**
+   * 包版本
+   */
+  version: string | null;
+  /**
+   * bin 名集合，书写形态为单串时归一为单元素集合
+   */
+  bins: readonly string[];
+};
+//#endregion
+//#region src/scan/tool-face-scan.core.d.ts
+/**
+ * 工具面黑盒抽取
+ *
+ * 逐 bin 运行 `--help` 解析 commander 形态帮助文本为结构化命令清单，逐命令
+ * 再取细化帮助，非 commander 形态降级记录原文不中断，调用方式可经配置覆写
+ * 以覆盖 dist 未构建场景即以 `bun` 直跑源码入口
+ */
+/**
+ * 工具面选项条目
+ */
+type ToolFaceOption = {
+  /**
+   * 选项旗标原文，如 `--scope <key>`
+   */
+  flags: string;
+  /**
+   * 选项说明
+   */
+  description: string;
+};
+/**
+ * 工具面命令条目
+ */
+type ToolFaceCommand = {
+  /**
+   * 命令名即首词
+   */
+  name: string;
+  /**
+   * 用法列原文，已去 ` [options]` 尾缀
+   */
+  invocation: string;
+  /**
+   * 顶层帮助中的命令说明
+   */
+  summary: string;
+  /**
+   * 细化帮助中的命令描述
+   */
+  detailDescription: string;
+  /**
+   * 细化帮助解析出的选项集合
+   */
+  options: readonly ToolFaceOption[];
+  /**
+   * 细化帮助是否解析成功
+   */
+  detailParsed: boolean;
+};
+/**
+ * 解析成功的工具面
+ */
+type ParsedToolFace = {
+  /**
+   * bin 名
+   */
+  bin: string;
+  /**
+   * 降级标记，恒为 `false`
+   */
+  degraded: false;
+  /**
+   * 用法行原文
+   */
+  usage: string;
+  /**
+   * bin 级描述
+   */
+  description: string;
+  /**
+   * bin 级选项集合
+   */
+  options: readonly ToolFaceOption[];
+  /**
+   * 命令集合，保持帮助输出顺序
+   */
+  commands: readonly ToolFaceCommand[];
+};
+/**
+ * 降级工具面
+ */
+type DegradedToolFace = {
+  /**
+   * bin 名
+   */
+  bin: string;
+  /**
+   * 降级标记，恒为 `true`
+   */
+  degraded: true;
+  /**
+   * 帮助输出原文
+   */
+  raw: string;
+  /**
+   * 降级原因
+   */
+  reason: string;
+};
+/**
+ * 工具面联合形态
+ */
+type ToolFace = ParsedToolFace | DegradedToolFace;
+/**
+ * 帮助文本解析出的命令条目
+ */
+type HelpCommandEntry = {
+  /**
+   * 命令名即首词
+   */
+  name: string;
+  /**
+   * 用法列原文，已去 `[options]` 尾缀
+   */
+  invocation: string;
+  /**
+   * 命令说明
+   */
+  summary: string;
+};
+/**
+ * 帮助文本解析结果
+ */
+type ParsedHelp = {
+  /**
+   * 用法行原文，非 commander 形态即 `null`
+   */
+  usage: string | null;
+  /**
+   * 用法行与首个区块之间的描述
+   */
+  description: string;
+  /**
+   * 选项条目集合
+   */
+  options: ToolFaceOption[];
+  /**
+   * 命令条目集合
+   */
+  commands: HelpCommandEntry[];
+};
+/**
+ * 解析 commander 形态帮助文本为选项与命令区块
+ *
+ * 判定口径为存在 `Usage:` 行，缺失即视为非 commander 形态，区块条目按两个
+ * 以上连续空白切分左列与右列，左列为命令或旗标、右列为说明，跨列折行的
+ * 说明尾行会落入左列，属已知精度边界，此类行以原样保留不丢弃
+ *
+ * @param text - 帮助输出全文
+ * @returns 解析出的用法行、bin 级描述、bin 级选项与命令清单
+ */
+declare const parseCommanderHelp: (text: string) => ParsedHelp;
+/**
+ * 全量工具面抽取入参
+ */
+type ExtractToolFaceInput = {
+  /**
+   * bin 名集合
+   */
+  bins: readonly string[];
+  /**
+   * bin 名到调用方式的覆写映射
+   */
+  invocations: Readonly<Record<string, readonly string[]>>;
+  /**
+   * 工作目录绝对路径
+   */
+  root: string;
+};
+/**
+ * 抽取全部 bin 的工具面
+ *
+ * @param input - 抽取入参
+ * @returns 工具面集合，顺序与 bins 声明一致
+ */
+declare const extractToolFace: (input: ExtractToolFaceInput) => Promise<readonly ToolFace[]>;
+//#endregion
+//#region src/model/compile-model.core.d.ts
+/**
+ * 单个文档的视图
+ */
+type DocumentView = {
+  /**
+   * 文档名即真源目录名，产物 basename 去 `.md`
+   */
+  document: string;
+  /**
+   * 产物路径即仓库根相对路径
+   */
+  output: string;
+  /**
+   * 文档标题，缺省为文档名
+   */
+  title: string;
+  /**
+   * 是否追加工具面命令参考节
+   */
+  toolFace: boolean;
+  /**
+   * 该文档产出条目即已定序已过滤
+   */
+  items: readonly SourceItem[];
+};
+/**
+ * 真源视图
+ */
+type CompileSourceView = {
+  /**
+   * 仓库根目录绝对路径
+   */
+  root: string;
+  /**
+   * 真源根的仓库根相对路径
+   */
+  sourceRootLabel: string;
+  /**
+   * manifest 面
+   */
+  manifest: ManifestFace;
+  /**
+   * 工具面集合
+   */
+  toolFace: readonly ToolFace[];
+  /**
+   * 各文档视图
+   */
+  documents: readonly DocumentView[];
+};
+/**
+ * 构建真源视图
+ *
+ * @param root - 仓库根目录绝对路径
+ * @param config - 解析后的插件配置
+ * @returns 真源视图
+ * @throws {@link Error} 任一文档条目文件名或元信息非法时，报错携带条目定位
+ */
+declare const buildSourceView: (root: string, config: CompilePluginConfig) => Promise<CompileSourceView>;
+//#endregion
+//#region src/compose/surface-composer.core.d.ts
+/**
+ * 合成单个文档产物
+ *
+ * @param view - 真源视图
+ * @param documentView - 该文档视图
+ * @returns 产物 markdown 全文，恒以单个换行收尾
+ */
+declare const composeSurface: (view: CompileSourceView, documentView: DocumentView) => string;
+/**
+ * 合成全部文档产物
+ *
+ * @param view - 真源视图
+ * @returns 文档名到产物路径与产物全文的集合
+ */
+declare const composeAllSurfaces: (view: CompileSourceView) => readonly {
+  document: string;
+  output: string;
+  markdown: string;
+}[];
+//#endregion
+//#region src/compile.commands.d.ts
+/**
+ * scan 结果形态
+ */
+type CompileScanResult = {
+  /**
+   * manifest 面四字段
+   */
+  manifest: {
+    name: string | null;
+    description: string | null;
+    version: string | null;
+    bins: readonly string[];
+  };
+  /**
+   * 工具面集合
+   */
+  toolFace: readonly unknown[];
+  /**
+   * 各文档条目清单
+   */
+  documents: readonly {
+    document: string;
+    output: string;
+    items: readonly {
+      file: string;
+      order: number;
+      metadata: readonly string[];
+    }[];
+  }[];
+};
+/**
+ * 执行 scan 即扫描真源面出清单
+ *
+ * @param root - 仓库根目录绝对路径
+ * @param config - 解析后的插件配置
+ * @returns scan 结果
+ * @throws {@link Error} 条目文件名或元信息非法时
+ */
+declare const runCompileScan: (root: string, config: CompilePluginConfig) => Promise<CompileScanResult>;
+/**
+ * 执行 derive 即建模派生并写盘
+ *
+ * @param root - 仓库根目录绝对路径
+ * @param config - 解析后的插件配置
+ * @param dryRun - 只打印不写盘
+ * @returns 写盘清单即文档名与产物路径与条目数
+ * @throws {@link Error} 未配置文档或条目文件名或元信息非法时
+ */
+declare const runCompileDerive: (root: string, config: CompilePluginConfig, dryRun: boolean) => Promise<readonly {
+  document: string;
+  output: string;
+  itemCount: number;
+}[]>;
+//#endregion
+export { type CompilePluginConfig, type CompilePluginConfigInput, CompilePluginConfigSchema, type CompileSourceView, type DocumentView, type SourceItem, type ToolFace, buildSourceView, compilePlugin, composeAllSurfaces, composeSurface, extractToolFace, parseCommanderHelp, parseCompilePluginConfig, resolveDocumentItems, runCompileCheck, runCompileDerive, runCompileScan };

package/dist/index.js

@@ -0,0 +1,14 @@
+import"./rolldown-runtime-BqT_7tdF.js";import{definePlugin as e,pluginCommand as t}from"@longzai-intelligence-docs/core";import*as n from"zod";import{mkdir as r,stat as i,writeFile as a}from"node:fs/promises";import{dirname as o,join as s}from"node:path";const c=`.lzi/docs/sources`,l=n.object({output:n.string().min(1).refine(e=>!e.startsWith(`/`),`产物路径须为仓库根相对路径`).refine(e=>e.endsWith(`.md`),`产物路径须为 md 文件`),title:n.string().min(1).optional(),toolFace:n.boolean().default(!1),exclude:n.array(n.string().min(1)).default([])}),u=n.object({bins:n.array(n.string().min(1)).optional(),invocations:n.record(n.string().min(1),n.array(n.string().min(1))).default({})}),d=n.object({sourceRoot:n.string().min(1).default(c),documents:n.array(l).default([]),toolFace:u.default({invocations:{}})}).default({sourceRoot:c,documents:[],toolFace:{invocations:{}}}),f=e=>{let t=e.split(`/`).at(-1)??e;return t.endsWith(`.md`)?t.slice(0,-3):t},p=e=>{let t=d.safeParse(e);if(!t.success)throw Error(`compile 插件配置非法：${t.error.issues.map(e=>`${e.path.join(`.`)||`根节`}——${e.message}`).join(`，`)}`);let n=/* @__PURE__ */ new Map;for(let e of t.data.documents){let t=f(e.output),r=n.get(t);if(r!==void 0)throw Error(`compile 插件配置非法：产物 basename '${t}' 跨文档重复，${r} 与 ${e.output}，真源目录无法区分归属`);n.set(t,e.output)}return t.data},m=[`<!-- 本文件由 lzi-docs compile 派生维护，禁止手工编辑 -->`,`<!-- 真源为 .lzi/docs/sources 下文档条目与 lzi-docs.config.ts 的 plugins.compile 配置，变更后重新执行 compile-derive 重建 -->`],h=(e,t,n)=>`<!-- compile:source ${e}/${t}/${n} -->`,g=e=>e.replaceAll(`|`,`\\|`).replaceAll(`
+`,` `),_=e=>e.length===0?``:[`| 选项 | 说明 |`,`| --- | --- |`,...e.map(e=>`| \`${g(e.flags)}\` | ${g(e.description)} |`)].join(`
+`),v=e=>{if(e.degraded)return[`### ${e.bin}`,``,`该 bin 的帮助输出未呈可解析形态，以下为原文。`,``,"````",e.raw.trimEnd(),"````"].join(`
+`);let t=[`### ${e.bin}`,``];e.description!==``&&t.push(e.description,``),t.push(`用法：\`${g(e.usage.replace(/^Usage:\s*/,``))}\``);let n=_(e.options);n!==``&&t.push(``,`**全局选项**`,``,n);for(let n of e.commands){let r=n.detailDescription===``?n.summary:n.detailDescription;t.push(``,`#### ${e.bin} ${n.name}`,``),r!==``&&t.push(r,``),t.push(`用法：\`${e.bin} ${g(n.invocation)}\``);let i=_(n.options);i!==``&&t.push(``,`**选项**`,``,i)}return t.join(`
+`)},y=e=>[`## 命令参考`,``,"本节由工具面自 `--help` 输出抽取合成，源为 bin 帮助文案。",``,e.map(e=>v(e)).join(`
+
+`)].join(`
+`),b=(e,t)=>{let n=[...m,``,`# ${t.title}`,``];for(let r of t.items)n.push(h(e.sourceRootLabel,t.document,r.fileName),r.body,``);return t.toolFace&&e.toolFace.length>0&&n.push(y(e.toolFace),``),`${n.join(`
+`).trimEnd()}\n`},x=e=>e.documents.map(t=>({document:t.document,output:t.output,markdown:b(e,t)})),S=/* @__PURE__ */ new Set([`id`,`type`,`title`,`anchor`,`command`]),C={id:null,type:null,title:null,anchor:null,command:null},w=e=>{let t=e.split(`
+`);if(t[0]?.trim()!==`---`)return{metaLines:[],body:e};let n=-1;for(let e=1;e<t.length;e+=1)if(t[e]?.trim()===`---`){n=e;break}return n===-1?{metaLines:[],body:e}:{metaLines:t.slice(1,n),body:t.slice(n+1).join(`
+`)}},T=(e,t)=>{let n={...C},r=/* @__PURE__ */ new Set;for(let i of e){let e=i.trim();if(e===``)continue;let a=/^([^\s:]+):\s*(.*)$/.exec(e);if(a===null)throw Error(`条目 ${t} 的 frontmatter 存在无法解析的行 '${e}'`);let o=a[1]??``,s=(a[2]??``).trim();if(o===`order`)throw Error(`条目 ${t} 的 frontmatter 键 order 已废弃，定序由文件名数值前缀唯一承载`);if(!S.has(o))throw Error(`条目 ${t} 的 frontmatter 含未知元数据键 '${o}'，仅支持 id 与 type 与 title 与 anchor 与 command`);if(r.has(o))throw Error(`条目 ${t} 的 frontmatter 重复声明 ${o}`);if(r.add(o),s===``)throw Error(`条目 ${t} 的元数据键 ${o} 值为空`);(o===`id`||o===`type`||o===`title`||o===`anchor`||o===`command`)&&(n[o]=s)}return n},ee=/^(\d+)-(.+)$/,E=async e=>{try{return await i(e),!0}catch{return!1}},D=e=>{let t=e.endsWith(`.md`)?e.slice(0,-3):e,n=ee.exec(t);if(n===null)return null;let r=n[1]??``;return{order:Number(r),slug:n[2]??``}},O=async e=>{let t=new Bun.Glob(`*.md`),n=[];for await(let r of t.scan({cwd:e,onlyFiles:!0}))n.push(r);return n.sort()},k=(e,t,n)=>`${e}/${t}/${n}`,A=async e=>{let t=[];if(!await E(e.documentDir))return t;let n=await O(e.documentDir),r=/* @__PURE__ */ new Set,i=e.exclude.map(e=>new Bun.Glob(e));for(let a of n){if(i.some(e=>e.match(a)))continue;let n=D(a);if(n===null)throw Error(`条目 ${k(e.sourceRootLabel,e.documentName,a)} 文件名无数值前缀，形态须为 NNN-slug.md，顺序性由前缀承载`);if(r.has(n.order))throw Error(`文档 ${e.documentName} 内条目前缀数值 ${String(n.order)} 重复，文件 ${a} 与先登记者冲突`);r.add(n.order);let o=await Bun.file(s(e.documentDir,a)).text(),{metaLines:c,body:l}=w(o),u=T(c,k(e.sourceRootLabel,e.documentName,a));l.trim()!==``&&t.push({fileName:a,order:n.order,meta:u,body:l.trimEnd()})}return t.sort((e,t)=>e.order-t.order)},j=e=>typeof e==`object`&&!!e,M=async e=>{let t={name:null,description:null,version:null,bins:[]};try{let n=await Bun.file(`${e}/package.json`).json();if(!j(n))return t;typeof n.name==`string`&&(t.name=n.name),typeof n.description==`string`&&(t.description=n.description),typeof n.version==`string`&&(t.version=n.version);let r=n.bin;typeof r==`string`?t.bins=[r]:j(r)&&(t.bins=Object.keys(r))}catch{return t}return t},N=[{name:`options`,pattern:/^Options:\s*$/},{name:`commands`,pattern:/^Commands:\s*$/}],P=/^\s+\S/,F=e=>{let t=e.split(`
+`),n=t.findIndex(e=>e.startsWith(`Usage:`));if(n===-1)return{usage:null,description:``,options:[],commands:[]};let r=/* @__PURE__ */ new Map;for(let e=0;e<t.length;e+=1)for(let n of N)n.pattern.test(t[e]??``)&&(r.has(n.name)||r.set(n.name,e));let i=r.size===0?t.length:Math.min(...r.values()),a=t.slice(n+1,i).filter(e=>e.trim()!==``),o=e=>{let n=r.get(e);if(n===void 0)return[];let i=[];for(let e=n+1;e<t.length;e+=1){let n=t[e]??``;if(P.test(n))i.push(n);else if(n.trim()!==``)break}return i},s=e=>{let t=e.trim().split(/\s{2,}/);return{left:t[0]??``,right:t.slice(1).join(` `)}},c=o(`options`).map(e=>{let{left:t,right:n}=s(e);return{flags:t,description:n}}),l=o(`commands`).map(e=>{let{left:t,right:n}=s(e);return{name:t.split(/\s+/)[0]??``,invocation:t.replace(/\s*\[options\]/g,``).trim(),summary:n}});return{usage:(t[n]??``).trim(),description:a.join(`
+`),options:c,commands:l}},I=async(e,t)=>{try{let n=Bun.spawn({cmd:[...e],cwd:t,stdout:`pipe`,stderr:`pipe`});return{exitCode:await n.exited,stdout:await new Response(n.stdout).text(),stderr:await new Response(n.stderr).text()}}catch(e){return{exitCode:null,stdout:``,stderr:e instanceof Error?e.message:String(e)}}},L=async e=>{let t=await I([...e.invocation,`--help`],e.root),n=t.stdout===``?t.stderr:t.stdout;if(t.exitCode!==0)return{bin:e.bin,degraded:!0,raw:n,reason:`运行退出码 ${String(t.exitCode)}`};let r=F(n);if(r.usage===null)return{bin:e.bin,degraded:!0,raw:n,reason:`帮助输出未含 Usage 行即非 commander 形态`};let i=[];for(let t of r.commands){let n=await I([...e.invocation,t.name,`--help`],e.root),r=n.stdout===``?n.stderr:n.stdout,a=n.exitCode===0?F(r):null;i.push({name:t.name,invocation:t.invocation,summary:t.summary,detailDescription:a?.description??``,options:a?.options??[],detailParsed:a!==null&&a.usage!==null})}return{bin:e.bin,degraded:!1,usage:r.usage,description:r.description,options:r.options,commands:i}},R=async e=>{let t=[];for(let n of e.bins)t.push(await L({bin:n,invocation:e.invocations[n]??[n],root:e.root}));return t},z=e=>{let t=e.split(`/`).at(-1)??e;return t.endsWith(`.md`)?t.slice(0,-3):t},B=async(e,t)=>{let n=await M(e),r=t.toolFace.bins??n.bins,i=r.length>0?await R({bins:r,invocations:t.toolFace.invocations,root:e}):[],a=[];for(let n of t.documents){let r=z(n.output),i=await A({documentDir:s(e,t.sourceRoot,r),documentName:r,sourceRootLabel:t.sourceRoot,exclude:n.exclude});a.push({document:r,output:n.output,title:n.title??r,toolFace:n.toolFace,items:i})}return{root:e,sourceRootLabel:t.sourceRoot,manifest:n,toolFace:i,documents:a}},V=e=>{let t=e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`);return[RegExp(`name\\s*[:=]\\s*(['"\`])${t}\\1`),RegExp(`\\.command\\(\\s*(['"\`])${t}\\1`)]},H=async e=>{let t=[];for(let n of e.documents)for(let r of n.items){let i=`${e.sourceRootLabel}/${n.document}/${r.fileName}`;if(r.meta.anchor===null&&r.meta.command===null)continue;if(r.meta.anchor===null){t.push({kind:`anchor-missing`,message:`条目 ${i} 声明了 command 而无 anchor，命令锚定需要 anchor 指向命令定义所在源码文件`});continue}let a=s(e.root,r.meta.anchor);if(!await Bun.file(a).exists()){t.push({kind:`anchor-missing`,message:`条目 ${i} 的 anchor 指向的文件不存在：${r.meta.anchor}`});continue}if(r.meta.command===null)continue;let o=await Bun.file(a).text();V(r.meta.command).some(e=>e.test(o))||t.push({kind:`command-not-found`,message:`条目 ${i} 的 command '${r.meta.command}' 在锚点源码 ${r.meta.anchor} 中未命中命令定义，命令可能已改名`})}return t},U=async(e,t)=>{let n=await B(e,t),r=x(n),i=/* @__PURE__ */ new Map;for(let t of r){let n=s(e,t.output);if(!await Bun.file(n).exists()){i.set(t.document,{status:`missing`,expected:t.markdown});continue}let r=await Bun.file(n).text();i.set(t.document,{status:r===t.markdown?`fresh`:`stale`,expected:t.markdown})}return i},W=async(e,t)=>{let n=await B(e,t),r=[...await H(n)];for(let t of x(n)){let n=s(e,t.output);await Bun.file(n).exists()?await Bun.file(n).text()!==t.markdown&&r.push({kind:`snapshot-stale`,message:`文档 ${t.document} 的产物过期：${t.output} 与真源合成结果不一致，执行 compile-derive 重建`}):r.push({kind:`snapshot-missing`,message:`文档 ${t.document} 的产物缺失：${t.output}，执行 compile-derive 生成`})}return r},G=async(e,t)=>{let n=await U(e.root,t),r=0,i=0;for(let t of e.documents)for(let e of t.items)r+=1,(e.meta.id!==null||e.meta.type!==null||e.meta.title!==null||e.meta.anchor!==null||e.meta.command!==null)&&(i+=1);return{repo:e.manifest.name??``,itemCount:r,metadataCoverage:r===0?1:i/r,documents:e.documents.map(e=>({document:e.document,output:e.output,itemCount:e.items.length,freshness:n.get(e.document)?.status??`missing`})),toolFace:e.toolFace.map(e=>({bin:e.bin,degraded:e.degraded,commandCount:e.degraded?0:e.commands.length}))}},K=e=>e===`fresh`?`新鲜`:e===`stale`?`过期`:`缺失`,q=e=>{let t=e.documents.map(e=>`| ${e.document} | \`${e.output}\` | ${e.itemCount} | ${K(e.freshness)} |`),n=e.toolFace.map(e=>`| \`${e.bin}\` | ${e.degraded?`是`:`否`} | ${e.commandCount} |`);return[`# compile inventory：${e.repo===``?`未识别包名`:e.repo}`,``,`- 条目总数：${e.itemCount}`,`- 元数据覆盖率：${(e.metadataCoverage*100).toFixed(0)}%`,``,`## 文档`,``,`| 文档 | 产物 | 条目数 | 新鲜度 |`,`| --- | --- | --- | --- |`,...t.length>0?t:[`| 无 | 无 | 0 | 缺失 |`],``,`## 工具面`,``,`| bin | 降级 | 命令数 |`,`| --- | --- | --- |`,...n.length>0?n:[`| 无 | 是 | 0 |`],``].join(`
+`)},J=e=>e.documents.length===0,Y=async(e,t)=>{let n=await B(e,t);return{manifest:n.manifest,toolFace:n.toolFace,documents:n.documents.map(e=>({document:e.document,output:e.output,items:e.items.map(e=>({file:e.fileName,order:e.order,metadata:[[`id`,e.meta.id],[`type`,e.meta.type],[`title`,e.meta.title],[`anchor`,e.meta.anchor],[`command`,e.meta.command]].filter(([,e])=>e!==null).map(([e])=>e)}))}))}},X=async(e,t,n)=>{if(J(t))throw Error(`plugins.compile.options 未配置任何文档，请在 lzi-docs.config.ts 的 documents 节配置后重试`);let i=await B(e,t),c=x(i);for(let t of c)if(!n){let n=s(e,t.output);await r(o(n),{recursive:!0}),await a(n,t.markdown,`utf-8`)}return c.map(e=>({document:e.document,output:e.output,itemCount:i.documents.find(t=>t.document===e.document)?.items.length??0}))},Z=async(e,t)=>{if(J(t))throw Error(`plugins.compile.options 未配置任何文档，请在 lzi-docs.config.ts 的 documents 节配置后重试`);return{findings:await W(e,t),documentCount:t.documents.length}},Q=async(e,t)=>{let n=await B(e,t),r=await G(n,t);return{markdown:q(r),data:r}},$=n.object({}),te=n.object({dryRun:n.boolean().default(!1)}),ne=n.object({}),re=n.object({json:n.boolean().default(!1)}),ie=e({name:`compile`,version:`0.0.1`,configSchema:d,commands:[e=>ae(e),e=>oe(e),e=>se(e),e=>ce(e)]});function ae(e){return t({name:`compile-scan`,description:`扫描真源面出清单：文档条目、manifest 面与工具面帮助抽取`,schema:$,action:async()=>{try{let t=await Y(process.cwd(),p(e.pluginConfig));process.stdout.write(`${JSON.stringify(t,null,2)}\n`)}catch(e){process.stderr.write(`错误: ${e instanceof Error?e.message:String(e)}\n`),process.exit(1)}}})}function oe(e){return t({name:`compile-derive`,description:`建模并派生文档产物写盘，同输入逐字节相同输出`,options:[{flags:`--dry-run`,description:`只打印合成结果不写盘`}],schema:te,action:async t=>{try{let n=await X(process.cwd(),p(e.pluginConfig),t.dryRun);for(let e of n)process.stdout.write(`${t.dryRun?`预览`:`已写入`} ${e.output}，文档 ${e.document}，条目 ${e.itemCount}\n`)}catch(e){process.stderr.write(`错误: ${e instanceof Error?e.message:String(e)}\n`),process.exit(1)}}})}function se(e){return t({name:`compile-check`,description:`只读校验：快照新鲜度逐字节比对与锚点命令定义命中`,schema:ne,action:async()=>{try{let t=await Z(process.cwd(),p(e.pluginConfig));for(let e of t.findings)process.stderr.write(`[compile:${e.kind}] ${e.message}\n`);t.findings.length>0&&process.exit(1),process.stdout.write(`校验通过，文档 ${t.documentCount} 份全绿\n`)}catch(e){process.stderr.write(`错误: ${e instanceof Error?e.message:String(e)}\n`),process.exit(1)}}})}function ce(e){return t({name:`compile-report`,description:`单仓 inventory 上报：文档计数、条目数、元数据覆盖率与产物新鲜度`,options:[{flags:`--json`,description:`以 JSON 形态输出`}],schema:re,action:async t=>{try{let n=await Q(process.cwd(),p(e.pluginConfig));process.stdout.write(`${t.json?JSON.stringify(n.data,null,2):n.markdown}\n`)}catch(e){process.stderr.write(`错误: ${e instanceof Error?e.message:String(e)}\n`),process.exit(1)}}})}export{d as CompilePluginConfigSchema,B as buildSourceView,ie as compilePlugin,x as composeAllSurfaces,b as composeSurface,R as extractToolFace,F as parseCommanderHelp,p as parseCompilePluginConfig,A as resolveDocumentItems,W as runCompileCheck,X as runCompileDerive,Y as runCompileScan};

package/dist/rolldown-runtime-BqT_7tdF.js

@@ -0,0 +1 @@
+import"node:module";export{};

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@longzai-intelligence-docs/compile-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.15",
+  "description": "Longzai Intelligence Docs compile 插件",
+  "keywords": [
+    "compile",
+    "docs",
+    "longzai-intelligence",
+    "plugin"
+  ],
+  "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-cli/core": "^0.0.11",
+    "@longzai-intelligence-docs/core": "0.0.15",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14"
+  },
+  "packageManager": "bun@1.4.0"
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.