@longzai-intelligence-progress-board/data 0.0.0-stage → 0.0.5

package/dist/index.d.ts

@@ -0,0 +1,580 @@
+/**
+ * 板目录契约——编排产物与呈现登记的单一正本
+ *
+ * 上游为仓根 `board:sync` 经编排工具族生成的 `domains.catalog.json` 产物,
+ * 下游为板应用数据层薄壳与本包推导核,契约字段语义与编排侧导出面对齐
+ */
+/**
+ * 目录契约版本
+ *
+ * 与编排侧 `EXPORT_SCHEMA_VERSION` 同步递增,工厂装载时校验
+ */
+declare const CATALOG_SCHEMA_VERSION = 1;
+/**
+ * 推进状态词表
+ *
+ * 取值限于四态语义键,中文标签经 `STAGE_STATUS_LABELS` 映射,禁止脱离词表自造状态
+ */
+type StageStatus = 'done' | 'blocked' | 'todo' | 'doing';
+/**
+ * 状态中文标签映射
+ */
+declare const STAGE_STATUS_LABELS: Record<StageStatus, string>;
+/**
+ * 键值事实行
+ *
+ * 条目独立页与身份要素呈现复用
+ */
+type KeyValueRow = {
+  /**
+   * 行标签
+   */
+  label: string;
+  /**
+   * 行取值
+   */
+  value: string;
+  /**
+   * 等宽字体标注,路径与版本号类取值为真
+   *
+   * @default false
+   */
+  mono?: boolean;
+};
+/**
+ * 关键计数要素行
+ *
+ * 进度行携带核验计数,状态行携带状态染色
+ */
+type SummaryRow = {
+  /**
+   * 行标签
+   */
+  label: string;
+  /**
+   * 行取值
+   */
+  value: string;
+  /**
+   * 状态染色,携带时以状态徽标呈现取值
+   */
+  status?: StageStatus;
+  /**
+   * 补充说明
+   */
+  note?: string;
+  /**
+   * 进度数据,仅进度行携带
+   */
+  progress?: {
+    /**
+     * 已过计数
+     */
+    passed: number;
+    /**
+     * 总计数
+     */
+    total: number;
+  };
+};
+/**
+ * 注册表条目登记
+ *
+ * 真源为仓内 `docs` 各注册表,本契约只做呈现登记,维护先改真源再改呈现
+ */
+type RegistryEntry = {
+  /**
+   * 条目路由标识,全站唯一,形态为「域标识-条目 slug」
+   */
+  routeId: string;
+  /**
+   * 条目标题,取注册表条目登记名
+   */
+  title: string;
+  /**
+   * 一句话说明,缺省取正本锚点说明
+   */
+  note: string;
+  /**
+   * 推进状态,无状态语义的注册表缺省
+   */
+  status?: StageStatus;
+  /**
+   * 条目独立页键值事实行
+   */
+  facts: KeyValueRow[];
+};
+/**
+ * 文档域登记
+ *
+ * 一域对位仓内 `docs` 下同名注册表或文档通道,`registered` 以目录实况为真源
+ */
+type DomainRegistration = {
+  /**
+   * 域标识,与 `docs` 目录名一致
+   */
+  id: string;
+  /**
+   * 域显示名
+   */
+  label: string;
+  /**
+   * 域一句话定位
+   */
+  note: string;
+  /**
+   * 正本目录,等宽呈现于空态与独立页
+   */
+  sourceDir: string;
+  /**
+   * 该仓是否实有此域,真源为 `docs` 目录实况
+   */
+  registered: boolean;
+  /**
+   * 注册表条目全集
+   */
+  entries: RegistryEntry[];
+};
+/**
+ * 分区来源组
+ *
+ * 并档分区内按来源域分组的呈现单元,单域分区仅一组
+ */
+type SectionGroup = {
+  /**
+   * 来源域标识
+   */
+  domainId: string;
+  /**
+   * 来源域显示名,并档分区分组标题使用
+   */
+  label: string;
+  /**
+   * 正本目录,等宽呈现于空态
+   */
+  sourceDir: string;
+  /**
+   * 该域条目全集
+   */
+  entries: RegistryEntry[];
+};
+/**
+ * 板分区
+ *
+ * 六分区构成规则的产物,并档分区携带多个来源组
+ */
+type BoardSection = {
+  /**
+   * 分区路由标识,单域分区为域标识,并档分区为并入域标识连缀
+   */
+  id: string;
+  /**
+   * 分区显示名,并档分区为并入域显示名以「与」连缀
+   */
+  label: string;
+  /**
+   * 分区一句话定位
+   */
+  note: string;
+  /**
+   * 来源组序列,单域分区仅一项
+   */
+  groups: SectionGroup[];
+  /**
+   * 分区条目全集,按来源组序拼接
+   */
+  entries: RegistryEntry[];
+};
+/**
+ * 目录产物原文条目
+ */
+type CatalogEntry = {
+  /**
+   * 条目路由标识
+   */
+  routeId: string;
+  /**
+   * 条目标题
+   */
+  title: string;
+  /**
+   * 一句话说明
+   */
+  note: string;
+  /**
+   * 推进状态原文,四态语义键
+   */
+  status?: string;
+  /**
+   * 键值事实行全集
+   */
+  facts: Array<{
+    label: string;
+    value: string;
+    mono?: boolean;
+  }>;
+};
+/**
+ * 目录产物原文域
+ */
+type CatalogDomain = {
+  /**
+   * 域标识
+   */
+  id: string;
+  /**
+   * 域显示名
+   */
+  label: string;
+  /**
+   * 域一句话定位
+   */
+  note: string;
+  /**
+   * 正本目录
+   */
+  sourceDir: string;
+  /**
+   * 该域是否实有
+   */
+  registered: boolean;
+  /**
+   * 条目全集
+   */
+  entries: CatalogEntry[];
+};
+/**
+ * 目录产物原文形态
+ */
+type BoardCatalogJson = {
+  /**
+   * 目录契约版本
+   */
+  schemaVersion: number;
+  /**
+   * 板标题
+   */
+  boardTitle: string;
+  /**
+   * 域目录全集
+   */
+  domains: Record<string, CatalogDomain>;
+};
+/**
+ * 计数徽标配色档
+ *
+ * 随所属分级取红、黄、绿、灰系
+ */
+type PipTone = 'bad' | 'todo' | 'ok' | 'neutral';
+/**
+ * 侧边栏子级条目
+ */
+type NavChild = {
+  /**
+   * 条目标识
+   */
+  id: string;
+  /**
+   * 显示名
+   */
+  label: string;
+  /**
+   * 跳转目标路由
+   */
+  to: string;
+  /**
+   * 状态圆点,仅携带状态语义的条目使用
+   */
+  dot?: StageStatus;
+  /**
+   * 计数徽标
+   */
+  pip?: {
+    tone: PipTone;
+    count: number;
+  };
+  /**
+   * 点击后滚动定位的卡片段标识,仅总览子级携带
+   */
+  scrollTo?: string;
+  /**
+   * 当前分区命中该值时子级高亮
+   */
+  activeSection?: string;
+};
+/**
+ * 侧边栏父级条目
+ */
+type NavSection = {
+  /**
+   * 分区标识
+   */
+  id: string;
+  /**
+   * 显示名
+   */
+  label: string;
+  /**
+   * 跳转目标路由
+   */
+  to: string;
+  /**
+   * 当前分区命中这些值时父级同样高亮,用于跨分区挂靠
+   */
+  alsoActiveFor?: string[];
+  /**
+   * 子级条目,空注册表分区缺省
+   */
+  children?: NavChild[];
+};
+/**
+ * 顶部导航条目
+ */
+type TopNavItem = {
+  /**
+   * 事项标识
+   */
+  id: string;
+  /**
+   * 显示名
+   */
+  label: string;
+  /**
+   * 跳转目标路由
+   */
+  to: string;
+  /**
+   * 状态圆点,总览类事项缺省
+   */
+  dot?: StageStatus;
+};
+/**
+ * 面包屑单项
+ */
+type CrumbEntry = {
+  /**
+   * 显示名
+   */
+  label: string;
+  /**
+   * 跳转路由,缺省为纯文本级
+   */
+  to?: string;
+};
+/**
+ * 条目索引行
+ */
+type EntryIndexRow = {
+  /**
+   * 命中的注册表条目
+   */
+  entry: RegistryEntry;
+  /**
+   * 所属分区标识
+   */
+  sectionId: string;
+};
+/**
+ * 注册表族优先序
+ *
+ * 事项分区先取注册表族,固定序为 issue 注册表、feature 注册表、技术债、决策库、台账族
+ */
+declare const REGISTRY_FAMILY_ORDER: readonly string[];
+/**
+ * 文档域优先序
+ *
+ * 注册表族不足五位时以文档域补足,固定序为作业记录、过错判例、计划归档、变更规格、思考与反思、探索发现、自由故事
+ */
+declare const DOC_DOMAIN_ORDER: readonly string[];
+/**
+ * 域全序
+ *
+ * 注册表族在前文档域在后的候选全序,装配核以此序显式遍历,不依赖产物键序
+ */
+declare const DOMAIN_FULL_ORDER: readonly string[];
+/**
+ * 分区取位上限
+ *
+ * 总览之外最多五个事项分区,超出者并入末位分区并档呈现
+ */
+declare const SECTION_SLOT_COUNT = 5;
+/**
+ * 并档分区兜底显示名
+ *
+ * 并入域超过两个时不再连缀域名,固定以其他文档域命名
+ */
+declare const MERGED_SECTION_FALLBACK_LABEL = "其他文档域";
+/**
+ * 候选域全集解析
+ *
+ * 注册表族全体先于文档域,仅收录登记为实有的域
+ *
+ * @param domains - 文档域登记全集
+ * @returns 有序候选域标识序列
+ */
+declare const resolveCandidateDomainIds: (domains: Record<string, DomainRegistration>) => string[];
+/**
+ * 板分区全集解析
+ *
+ * 六分区构成规则的可执行正本:候选不超过五域时各成单域分区,
+ * 超过五域时前四域各成单域分区,余域并入末位分区并档呈现,
+ * 无候选时返回空序列,板仅余总览
+ *
+ * @param domains - 文档域登记全集
+ * @returns 事项分区序列,总览不在其列
+ */
+declare const resolveBoardSections: (domains: Record<string, DomainRegistration>) => BoardSection[];
+/**
+ * 总览分区标识
+ *
+ * 总览恒居六分区首位,根路由即总览
+ */
+declare const OVERVIEW_SECTION_ID = "overview";
+/**
+ * 总览分区显示名
+ */
+declare const OVERVIEW_SECTION_LABEL = "总览";
+/**
+ * 总览分区一句话定位
+ */
+declare const OVERVIEW_SECTION_NOTE = "各分区导览与关键计数";
+/**
+ * 分区元信息
+ */
+type SectionMeta = {
+  /**
+   * 分区显示名
+   */
+  label: string;
+  /**
+   * 分区一句话定位
+   */
+  note: string;
+  /**
+   * 面包屑用短标题
+   */
+  title: string;
+};
+/**
+ * 板导航推导产物
+ *
+ * 查询函数闭包持有 `Map` 索引,消费侧禁绕过函数直取索引结构
+ */
+type BoardNavigation = {
+  /**
+   * 分区标识全集,总览居首,分区按构成序排列
+   */
+  sectionIds: readonly string[];
+  /**
+   * 分区元信息查询
+   *
+   * @remarks
+   *   以 `Map` 承载,未命中返回 `undefined`,原型链键不参与命中
+   */
+  findSectionMeta: (id: string) => SectionMeta | undefined;
+  /**
+   * 判定字符串是否为合法分区标识
+   */
+  isSectionId: (value: string) => boolean;
+  /**
+   * 按分区标识查板分区
+   *
+   * @remarks
+   *   命中的板分区,总览与未命中返回 `undefined`
+   */
+  findBoardSection: (id: string) => BoardSection | undefined;
+  /**
+   * 按条目路由标识查索引行
+   *
+   * @remarks
+   *   以 `Map` 承载,未命中返回 `undefined`,原型链键不参与命中
+   */
+  findEntryIndex: (itemId: string) => EntryIndexRow | undefined;
+  /**
+   * 顶部导航条目全集
+   *
+   * 事项级导航,总览居首,分区按构成序排列
+   */
+  topNavItems: TopNavItem[];
+  /**
+   * 侧边栏分区全集
+   *
+   * 父级为分区锚点,子级为分区内条目,空注册表分区仅父级
+   */
+  navSections: NavSection[];
+};
+/**
+ * 分区状态圆点解析
+ *
+ * 分区携带未开始或受阻条目时显点,受阻优先,进行中不亮点
+ *
+ * @param entries - 分区条目全集
+ * @returns 圆点状态,无显点语义返回 `undefined`
+ */
+declare const sectionDotOf: (entries: RegistryEntry[]) => StageStatus | undefined;
+/**
+ * 板导航推导
+ *
+ * 以板分区全集构建分区元信息表、全站条目索引与两栏导航条目,
+ * 索引结构一律 `Map`,键集合封闭于总览加实际分区与实际条目
+ *
+ * @param sections - 板分区全集,依构成序
+ * @returns 板导航推导产物
+ */
+declare const buildBoardNavigation: (sections: BoardSection[]) => BoardNavigation;
+/**
+ * 板数据装配产物
+ *
+ * 域登记、板分区与导航推导的聚合承载,查询函数闭包持有索引结构
+ */
+type BoardData = {
+  /**
+   * 板标题,以仓名为身份宣告
+   */
+  boardTitle: string;
+  /**
+   * 文档域登记全集
+   *
+   * @remarks
+   *   键为域标识,装配序为域全序,不依赖产物键序
+   */
+  domains: Record<string, DomainRegistration>;
+  /**
+   * 域全序标识序列,词表全域俱在
+   */
+  domainIds: readonly string[];
+  /**
+   * 按域标识取实有条目数
+   *
+   * @remarks
+   *   未实有与未登记域为 `0`
+   */
+  domainCount: (id: string) => number;
+  /**
+   * 按域标识取已完成条目数
+   *
+   * @remarks
+   *   未实有与未登记域为 `0`
+   */
+  domainDoneCount: (id: string) => number;
+  /**
+   * 板分区全集,依构成序,总览不在其列
+   */
+  sections: ReturnType<typeof resolveBoardSections>;
+  /**
+   * 板导航推导产物
+   */
+  navigation: BoardNavigation;
+};
+/**
+ * 板数据装配工厂
+ *
+ * 校验目录契约版本与词表全域在场后按域全序装配,域缺席即抛错暴露产物
+ * 与词表的漂移,禁止静默丢域
+ *
+ * @param catalog - 目录产物原文,板内 `data` 目录的 `domains.catalog.json`
+ * @returns 板数据装配产物
+ * @throws {@link Error} 目录契约版本不符或词表域缺席时抛出,暴露产物与词表的漂移
+ */
+declare const createBoardData: (catalog: BoardCatalogJson) => BoardData;
+export { BoardCatalogJson, BoardData, BoardNavigation, BoardSection, CATALOG_SCHEMA_VERSION, CatalogDomain, CatalogEntry, CrumbEntry, DOC_DOMAIN_ORDER, DOMAIN_FULL_ORDER, DomainRegistration, EntryIndexRow, KeyValueRow, MERGED_SECTION_FALLBACK_LABEL, NavChild, NavSection, OVERVIEW_SECTION_ID, OVERVIEW_SECTION_LABEL, OVERVIEW_SECTION_NOTE, PipTone, REGISTRY_FAMILY_ORDER, RegistryEntry, SECTION_SLOT_COUNT, STAGE_STATUS_LABELS, SectionGroup, SectionMeta, StageStatus, SummaryRow, TopNavItem, buildBoardNavigation, createBoardData, resolveBoardSections, resolveCandidateDomainIds, sectionDotOf };

package/dist/index.js

@@ -0,0 +1 @@
+const e=1,t={blocked:`受阻`,done:`已完成`,doing:`进行中`,todo:`未开始`},n=[`issues`,`features`,`debts`,`decisions`,`ledgers`],r=[`records`,`pitfalls`,`plans`,`specs`,`reflections`,`findings`,`stories`],i=[...n,...r],a=5,o=`其他文档域`,s=e=>({domainId:e.id,entries:e.entries,label:e.label,sourceDir:e.sourceDir}),c=e=>({entries:e.entries,groups:[s(e)],id:e.id,label:e.label,note:e.note}),l=e=>({entries:e.flatMap(e=>e.entries),groups:e.map(s),id:e.map(e=>e.id).join(`-`),label:e.length<=2?e.map(e=>e.label).join(`与`):o,note:`并入域的合并登记,条目按来源域分组呈现`}),u=e=>i.filter(t=>e[t]?.registered===!0),d=e=>{let t=u(e).flatMap(t=>{let n=e[t];return n===void 0?[]:[n]});if(t.length<=5)return t.map(c);let n=t.slice(0,4),r=t.slice(4);return[...n.map(c),l(r)]},f=`overview`,p=`总览`,m=`各分区导览与关键计数`,h=e=>{if(e.some(e=>e.status===`blocked`))return`blocked`;if(e.some(e=>e.status===`todo`))return`todo`},g=(e,t)=>({dot:t.status,id:t.routeId,label:t.title,to:`/${e}/${t.routeId}`}),_=e=>{let t=new Map([[f,{label:p,note:m,title:p}],...e.map(e=>[e.id,{label:e.label,note:e.note,title:e.label}])]),n=[f,...e.map(e=>e.id)],r=new Map(e.map(e=>[e.id,e])),i=new Map(e.flatMap(e=>e.entries.map(t=>[t.routeId,{entry:t,sectionId:e.id}])));return{findBoardSection:e=>r.get(e),findEntryIndex:e=>i.get(e),findSectionMeta:e=>t.get(e),isSectionId:e=>t.has(e),navSections:[{id:f,label:p,to:`/`},...e.map(e=>({children:e.entries.length===0?void 0:e.entries.map(t=>g(e.id,t)),id:e.id,label:e.label,to:`/${e.id}`}))],sectionIds:n,topNavItems:[{id:f,label:p,to:`/`},...e.map(e=>({dot:h(e.entries),id:e.id,label:e.label,to:`/${e.id}`}))]}},v=new Set(Object.keys(t)),y=e=>v.has(e),b=e=>{if(e!==void 0)return y(e)?e:void 0},x=e=>({facts:e.facts,note:e.note,routeId:e.routeId,status:b(e.status),title:e.title}),S=e=>({entries:e.entries.map(x),id:e.id,label:e.label,note:e.note,registered:e.registered,sourceDir:e.sourceDir}),C=e=>{if(e.schemaVersion!==1)throw Error(`目录契约版本不符：期望 1 实到 ${String(e.schemaVersion)}`);let t=i.map(t=>{let n=e.domains[t];if(n===void 0)throw Error(`目录产物缺域：${t}`);return S(n)}),n=Object.fromEntries(t.map(e=>[e.id,e])),r=d(n),a=new Map(t.map(e=>[e.id,e.registered?e.entries.length:0])),o=new Map(t.map(e=>[e.id,e.registered?e.entries.filter(e=>e.status===`done`).length:0]));return{boardTitle:e.boardTitle,domainCount:e=>a.get(e)??0,domainDoneCount:e=>o.get(e)??0,domainIds:i,domains:n,navigation:_(r),sections:r}};export{e as CATALOG_SCHEMA_VERSION,r as DOC_DOMAIN_ORDER,i as DOMAIN_FULL_ORDER,o as MERGED_SECTION_FALLBACK_LABEL,f as OVERVIEW_SECTION_ID,p as OVERVIEW_SECTION_LABEL,m as OVERVIEW_SECTION_NOTE,n as REGISTRY_FAMILY_ORDER,a as SECTION_SLOT_COUNT,t as STAGE_STATUS_LABELS,_ as buildBoardNavigation,C as createBoardData,d as resolveBoardSections,u as resolveCandidateDomainIds,h as sectionDotOf};

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@longzai-intelligence-progress-board/data",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.5",
+  "description": "Longzai Intelligence 进度板数据消费推导包",
+  "keywords": [
+    "data",
+    "longzai-intelligence",
+    "progress-board"
+  ],
+  "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",
+    "clean": "lzi-dev-tools clean",
+    "typecheck": "lzi-typecheck",
+    "lint": "lzi-lint lint",
+    "lint:fix": "lzi-lint fix",
+    "test": "lzi-bun test",
+    "test:coverage": "lzi-bun test --coverage",
+    "test:watch": "lzi-bun test --watch"
+  },
+  "devDependencies": {
+    "@longzai-intelligence-builder/esm": "^0.2.28"
+  }
+}

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.