@longzai-intelligence-workflow/core 0.0.2 → 0.0.5

package/src/__tests__/unit/utils.test.ts

@@ -1,69 +1,99 @@
 import { describe, expect, it } from 'bun:test';
 
-import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from '../../constants/workflow';
-import { formatDate, getPagination, getTotalPages } from '../../utils/index';
+import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from '@/constants/workflow';
+import { formatDate, getPagination, getTotalPages } from '@/utils/index';
 
 describe('getPagination', () => {
   it('默认参数返回 offset=0, limit=DEFAULT_PAGE_SIZE', () => {
-    // Arrange & Act
+    /*
+     * 不传参直接调用 getPagination 取得分页结果
+     */
     const result = getPagination();
 
-    // Assert
+    /*
+     * 断言默认偏移为 0 且条数取默认分页大小
+     */
     expect(result.offset).toBe(0);
     expect(result.limit).toBe(DEFAULT_PAGE_SIZE);
   });
 
   it('page=2, pageSize=10 返回 offset=10, limit=10', () => {
-    // Arrange & Act
+    /*
+     * 以第二页与每页十条的参数调用 getPagination
+     */
     const result = getPagination(2, 10);
 
-    // Assert
+    /*
+     * 断言偏移跳过第一页且条数原样返回
+     */
     expect(result.offset).toBe(10);
     expect(result.limit).toBe(10);
   });
 
   it('pageSize 超过 MAX_PAGE_SIZE 时限制为 MAX_PAGE_SIZE', () => {
-    // Arrange
+    /*
+     * 构造超出 MAX_PAGE_SIZE 的每页条数
+     */
     const oversizedPageSize = MAX_PAGE_SIZE + 50;
 
-    // Act
+    /*
+     * 将超限条数传入 getPagination
+     */
     const result = getPagination(1, oversizedPageSize);
 
-    // Assert
+    /*
+     * 断言条数被收口到 MAX_PAGE_SIZE
+     */
     expect(result.limit).toBe(MAX_PAGE_SIZE);
   });
 
   it('page=0 时默认为 page=1', () => {
-    // Arrange & Act
+    /*
+     * 以零页码调用 getPagination
+     */
     const result = getPagination(0, 10);
 
-    // Assert
+    /*
+     * 断言零页码被归位到首页偏移
+     */
     expect(result.offset).toBe(0);
     expect(result.limit).toBe(10);
   });
 
   it('page 为负数时默认为 page=1', () => {
-    // Arrange & Act
+    /*
+     * 以负数页码调用 getPagination
+     */
     const result = getPagination(-1, 10);
 
-    // Assert
+    /*
+     * 断言负页码同样回落到首页偏移
+     */
     expect(result.offset).toBe(0);
   });
 
   it('仅传入 page 时 pageSize 使用默认值', () => {
-    // Arrange & Act
+    /*
+     * 只传页码而省略每页条数调用 getPagination
+     */
     const result = getPagination(3);
 
-    // Assert
+    /*
+     * 断言偏移按默认条数折算且条数取默认值
+     */
     expect(result.offset).toBe((3 - 1) * DEFAULT_PAGE_SIZE);
     expect(result.limit).toBe(DEFAULT_PAGE_SIZE);
   });
 
   it('仅传入 pageSize 时 page 默认为 1', () => {
-    // Arrange & Act
+    /*
+     * 页码缺省而只传每页条数调用 getPagination
+     */
     const result = getPagination(undefined, 15);
 
-    // Assert
+    /*
+     * 断言首页偏移为零且条数原样保留
+     */
     expect(result.offset).toBe(0);
     expect(result.limit).toBe(15);
   });
@@ -71,86 +101,128 @@ describe('getPagination', () => {
 
 describe('getTotalPages', () => {
   it('正确计算总页数', () => {
-    // Arrange
+    /*
+     * 准备总数 45 与每页 10 条的输入
+     */
     const total = 45;
     const pageSize = 10;
 
-    // Act
+    /*
+     * 用该输入计算总页数
+     */
     const result = getTotalPages(total, pageSize);
 
-    // Assert
+    /*
+     * 断言有余数时向上取整为 5 页
+     */
     expect(result).toBe(5);
   });
 
   it('总数恰好整除时返回精确页数', () => {
-    // Arrange
+    /*
+     * 准备总数 40 与每页 10 条的整除输入
+     */
     const total = 40;
     const pageSize = 10;
 
-    // Act
+    /*
+     * 用该输入计算总页数
+     */
     const result = getTotalPages(total, pageSize);
 
-    // Assert
+    /*
+     * 断言整除时返回精确的 4 页
+     */
     expect(result).toBe(4);
   });
 
   it('总数为 0 时返回 0', () => {
-    // Arrange
+    /*
+     * 准备总数为 0 的空集输入
+     */
     const total = 0;
     const pageSize = 10;
 
-    // Act
+    /*
+     * 用该输入计算总页数
+     */
     const result = getTotalPages(total, pageSize);
 
-    // Assert
+    /*
+     * 断言空集时总页数为 0
+     */
     expect(result).toBe(0);
   });
 
   it('总数为 1 时返回 1', () => {
-    // Arrange
+    /*
+     * 准备总数为 1 的单条输入
+     */
     const total = 1;
     const pageSize = 10;
 
-    // Act
+    /*
+     * 用该输入计算总页数
+     */
     const result = getTotalPages(total, pageSize);
 
-    // Assert
+    /*
+     * 断言单条数据占 1 页
+     */
     expect(result).toBe(1);
   });
 });
 
 describe('formatDate', () => {
   it('将 Date 对象转换为 ISO 字符串', () => {
-    // Arrange
+    /*
+     * 构造固定时刻的日期对象
+     */
     const date = new Date('2025-01-15T10:30:00.000Z');
 
-    // Act
+    /*
+     * 将日期对象交给 formatDate 转换
+     */
     const result = formatDate(date);
 
-    // Assert
+    /*
+     * 断言输出与输入的 ISO 表示逐字符一致
+     */
     expect(result).toBe('2025-01-15T10:30:00.000Z');
   });
 
   it('将日期字符串转换为 ISO 字符串', () => {
-    // Arrange
+    /*
+     * 准备纯日期字符串输入
+     */
     const dateStr = '2025-06-01';
 
-    // Act
+    /*
+     * 把字符串交给 formatDate 转换
+     */
     const result = formatDate(dateStr);
 
-    // Assert
+    /*
+     * 断言输出包含原日期且类型为字符串
+     */
     expect(result).toContain('2025-06-01');
     expect(typeof result).toBe('string');
   });
 
   it('返回值为有效的 ISO 格式', () => {
-    // Arrange
+    /*
+     * 取当前时刻构造日期对象
+     */
     const date = new Date();
 
-    // Act
+    /*
+     * 将当前日期交给 formatDate 转换
+     */
     const result = formatDate(date);
 
-    // Assert
+    /*
+     * 断言输出经日期还原后与自身一致
+     */
     expect(new Date(result).toISOString()).toBe(result);
   });
 });

package/src/__tests__/work-item-rules.test.ts

@@ -3,8 +3,14 @@
  */
 import { describe, expect, test } from 'bun:test';
 
-import { parseGateLine, parseItemLine, type WorkflowEdge, type WorkflowGate, type WorkflowItem } from '../schemas/workflow-doc.schema';
-import { checkStatusTransition, deriveWorkflowView } from '../utils/work-item-rules.utils';
+import {
+  parseGateLine,
+  parseItemLine,
+  type WorkflowEdge,
+  type WorkflowGate,
+  type WorkflowItem,
+} from '@/schemas/workflow-doc.schema';
+import { checkStatusTransition, deriveWorkflowView } from '@/utils/work-item-rules.utils';
 
 describe('声明方言四段制解析', () => {
   test('工作项行：状态段执法', () => {
@@ -19,9 +25,13 @@ describe('声明方言四段制解析', () => {
   });
 
   test('裁定门行：裁定段四形态执法', () => {
-    expect(parseGateLine('t-013 | ruling | 载体指示待裁 | pending')?.ruling).toEqual({ status: 'pending' });
+    expect(parseGateLine('t-013 | ruling | 载体指示待裁 | pending')?.ruling).toEqual({
+      status: 'pending',
+    });
     expect(parseGateLine('workflow | ruling | TE 悬置 | pending')?.at).toBe('workflow');
-    expect(parseGateLine('t-013 | ruling | 载体指示待裁 | approved:user:decisions/019.md')?.ruling).toEqual({
+    expect(
+      parseGateLine('t-013 | ruling | 载体指示待裁 | approved:user:decisions/019.md')?.ruling,
+    ).toEqual({
       status: 'approved',
       decidedBy: 'user',
       evidence: 'decisions/019.md',
@@ -68,7 +78,10 @@ describe('视图派生（依赖门控与未决裁定）', () => {
     expect(byId.get('b')?.blockedOnPrerequisite).toBe(true);
     expect(byId.get('b')?.canStart).toBe(false);
     expect(byId.get('c')?.canStart).toBe(false);
-    expect(view.pendingRulings.map((ruling) => ruling.key)).toEqual(['b:ruling', 'workflow:ruling']);
+    expect(view.pendingRulings.map((ruling) => ruling.key)).toEqual([
+      'b:ruling',
+      'workflow:ruling',
+    ]);
   });
 
   test('前置闭环解除阻塞；门批准解除门控；escalated 仍属未决', () => {

package/src/index.ts

@@ -4,13 +4,27 @@
  * 提供共享基础类型、Schema、常量和工具函数。
  * 不依赖任何 domain 包。
  */
-// 类型导出
+/*
+ * 类型导出
+ */
 export * from './types/index';
-// 常量导出
+
+/*
+ * 常量导出
+ */
 export * from './constants/index';
-// 工具函数导出
+
+/*
+ * 工具函数导出
+ */
 export * from './utils/index';
-// zod schema 导出
+
+/*
+ * zod schema 导出
+ */
 export * from './schemas/index';
-// 端口契约导出（C1 合规，零框架依赖）
+
+/*
+ * 端口契约导出（C1 合规，零框架依赖）
+ */
 export * from './ports/index';

package/src/ports/action-executor.port.ts

@@ -6,6 +6,7 @@
  * 当工作流执行到 action 节点时，根据 action.type 调用对应 handler。
  *
  * 支持的 action 类型：
+ *
  * - feed.applyTags：调用 feed F-2 applyTags（Phase 2）
  * - feed.summarize：调用 feed F-3 summarize（Phase 2）
  * - llm.complete：调用 agent LlmCompletePort
@@ -16,7 +17,7 @@
  * C1 合规：本端口为零框架依赖的纯类型契约，由具体适配器层提供实现。
  */
 
-import type { Action, ActionContext, ActionResult, ActionType } from '../types';
+import type { Action, ActionContext, ActionResult, ActionType } from '@/types';
 
 /**
  * 单个 action handler 函数签名

package/src/ports/feed-event.port.ts

@@ -8,7 +8,7 @@
  * C1 合规：本端口为零框架依赖的纯类型契约，由 feed 项目的实现层提供具体实现。
  */
 
-import type { FeedEventFilter, FeedEventName, FeedEventPayload } from '../types';
+import type { FeedEventFilter, FeedEventName, FeedEventPayload } from '@/types';
 
 /**
  * feed 事件订阅句柄

package/src/ports/index.ts

@@ -6,4 +6,5 @@
  */
 
 export * from './feed-event.port';
+
 export * from './action-executor.port';

package/src/schemas/action-executor.schema.ts

@@ -5,6 +5,7 @@
  * 供 execution 子插件注册 action handler 时使用。
  *
  * 支持的 action 类型：
+ *
  * - feed.applyTags：调用 feed F-2 applyTags，为条目打标签
  * - feed.summarize：调用 feed F-3 summarize，生成摘要
  * - llm.complete：调用 agent LlmCompletePort，完成文本
@@ -15,7 +16,7 @@
 
 import { z } from 'zod';
 
-import { ACTION_TYPES } from '../constants/workflow';
+import { ACTION_TYPES } from '@/constants/workflow';
 
 /**
  * action 类型 Schema

package/src/schemas/definition.schema.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { NODE_TYPES } from '../constants/workflow';
+import { NODE_TYPES } from '@/constants/workflow';
 
 export const workflowNodeDtoSchema = z.object({
   nodeId: z.string(),

package/src/schemas/feed-event-trigger.schema.ts

@@ -12,7 +12,7 @@
 
 import { z } from 'zod';
 
-import { FEED_EVENT_NAMES } from '../constants/workflow';
+import { FEED_EVENT_NAMES } from '@/constants/workflow';
 
 /**
  * feed 事件名称 Schema

package/src/schemas/index.ts

@@ -1,8 +1,15 @@
 export * from './definition.schema';
+
 export * from './workflow-doc.schema';
+
 export * from './instance.schema';
+
 export * from './trigger.schema';
+
 export * from './monitoring.schema';
+
 export * from './feed-event-trigger.schema';
+
 export * from './action-executor.schema';
+
 export * from './workflow-doc.schema';

package/src/schemas/instance.schema.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { INSTANCE_STATUSES, NODE_EXECUTION_STATUSES } from '../constants/workflow';
+import { INSTANCE_STATUSES, NODE_EXECUTION_STATUSES } from '@/constants/workflow';
 
 export const instanceStatusDtoSchema = z.enum(INSTANCE_STATUSES);
 

package/src/schemas/monitoring.schema.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { ALERT_TYPES, METRIC_TYPES } from '../constants/workflow';
+import { ALERT_TYPES, METRIC_TYPES } from '@/constants/workflow';
 
 export const alertTypeDtoSchema = z.enum(ALERT_TYPES);
 

package/src/schemas/trigger.schema.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { TRIGGER_TYPES } from '../constants/workflow';
+import { TRIGGER_TYPES } from '@/constants/workflow';
 
 export const triggerTypeDtoSchema = z.enum(TRIGGER_TYPES);
 

package/src/schemas/workflow-doc.schema.ts

@@ -26,7 +26,8 @@ const KEBAB_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /**
  * 工作项指针备选：`task:<仓>/<slug>`（task 台账引用）或 `ref:<仓>/<仓内路径>`
  */
-const ITEM_REF_ALTERNATION = 'task:[a-z0-9][a-z0-9-]*\\/[a-z0-9\\/-]+|ref:[a-z0-9][a-z0-9-]*\\/[a-z0-9\\/. _-]+';
+const ITEM_REF_ALTERNATION =
+  'task:[a-z0-9][a-z0-9-]*\\/[a-z0-9\\/-]+|ref:[a-z0-9][a-z0-9-]*\\/[a-z0-9\\/. _-]+';
 
 /**
  * 工作项行：`<itemId> | <标题> | <指针> | <状态>`（四段制）
@@ -362,4 +363,5 @@ export function parseGateLine(line: string): WorkflowGate | null {
 /**
  * 家族引用（条目档 frontmatter 的 ref 字段值）
  */
-export const WORKFLOW_REF_PATTERN = /^workflow:(global|[a-z0-9][a-z0-9-]*)\/([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+export const WORKFLOW_REF_PATTERN =
+  /^workflow:(global|[a-z0-9][a-z0-9-]*)\/([a-z0-9]+(?:-[a-z0-9]+)*)$/;

package/src/types/action-executor.ts

@@ -14,7 +14,7 @@ import type {
   feedSummarizeActionSchema,
   llmCompleteActionSchema,
   webhookSendActionSchema,
-} from '../schemas';
+} from '@/schemas';
 import type { z } from 'zod';
 
 /**

package/src/types/feed-event-trigger.ts

@@ -10,7 +10,7 @@ import type {
   feedEventNameSchema,
   feedEventPayloadSchema,
   feedEventTriggerSchema,
-} from '../schemas';
+} from '@/schemas';
 import type { z } from 'zod';
 
 /**

package/src/types/index.ts

@@ -1,6 +1,11 @@
 export * from './definition';
+
 export * from './instance';
+
 export * from './trigger';
+
 export * from './monitoring';
+
 export * from './feed-event-trigger';
+
 export * from './action-executor';

package/src/utils/index.ts

@@ -1,4 +1,4 @@
-import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from '../constants/workflow';
+import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from '@/constants/workflow';
 
 export function getPagination(page?: number, pageSize?: number): { offset: number; limit: number } {
   const limit = Math.min(pageSize ?? DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE);
@@ -15,5 +15,7 @@ export function formatDate(date: string | Date): string {
 }
 
 export * from './declaration-frontmatter.utils';
+
 export * from './work-item-rules.utils';
+
 export * from './dag.utils';

package/src/utils/work-item-rules.utils.ts

@@ -1,3 +1,10 @@
+import type {
+  WorkflowEdge,
+  WorkflowGate,
+  WorkflowItem,
+  WorkItemStatus,
+} from '@/schemas/workflow-doc.schema';
+
 /**
  * 工作项判定核（纯函数、零 I/O——输入声明形态，输出视图与违规）
  *
@@ -6,12 +13,12 @@
  */
 import { dependenciesMet } from '@longzai-intelligence-dag/core';
 
-import type { WorkflowEdge, WorkflowGate, WorkflowItem, WorkItemStatus } from '../schemas/workflow-doc.schema';
-
 /**
  * 工作项合法状态转移表（状态机唯一注册点；供编辑工具与判定器共用的规则真源）
  */
-export const ALLOWED_STATUS_TRANSITIONS: Readonly<Record<WorkItemStatus, readonly WorkItemStatus[]>> = {
+export const ALLOWED_STATUS_TRANSITIONS: Readonly<
+  Record<WorkItemStatus, readonly WorkItemStatus[]>
+> = {
   todo: ['doing', 'blocked', 'dropped'],
   doing: ['blocked', 'done', 'dropped'],
   blocked: ['todo', 'doing', 'dropped'],
@@ -41,7 +48,10 @@ export type InvalidTransitionError = {
  * @param to - 目标状态
  * @returns 合法时为 null；非法时携带合法后继清单
  */
-export function checkStatusTransition(from: WorkItemStatus, to: WorkItemStatus): InvalidTransitionError | null {
+export function checkStatusTransition(
+  from: WorkItemStatus,
+  to: WorkItemStatus,
+): InvalidTransitionError | null {
   /**
    * 注册表中的合法后继
    */
@@ -50,7 +60,10 @@ export function checkStatusTransition(from: WorkItemStatus, to: WorkItemStatus):
     return { code: 'INVALID_TRANSITION', message: `未知状态：${from}` };
   }
   if (!allowed.includes(to)) {
-    return { code: 'INVALID_TRANSITION', message: `非法转移：${from} → ${to}（合法后继：${allowed.join(' / ')}）` };
+    return {
+      code: 'INVALID_TRANSITION',
+      message: `非法转移：${from} → ${to}（合法后继：${allowed.join(' / ')}）`,
+    };
   }
   return null;
 }
@@ -134,6 +147,7 @@ export type WorkflowView = {
  * 已闭环状态集合（依赖满足判定基准：done 或 dropped 均不再阻塞后继）
  *
  * @param status - 工作项状态
+ * @returns 状态为 done 或 dropped 时为 true，否则为 false
  */
 function isSettled(status: WorkItemStatus): boolean {
   return status === 'done' || status === 'dropped';
@@ -145,6 +159,7 @@ function isSettled(status: WorkItemStatus): boolean {
  * @param items - 工作项清单（声明档现状）
  * @param edges - 依赖边清单
  * @param gates - 裁定门清单（含裁定事实）
+ * @returns 工作流声明视图，含全部工作项视图与未决裁定清单
  */
 export function deriveWorkflowView(
   items: readonly WorkflowItem[],
@@ -159,7 +174,11 @@ export function deriveWorkflowView(
   /**
    * 各工作项挂靠的未批准门（ruling.status 非 approved 即阻塞）
    */
-  const unapprovedGateAt = new Set(gates.filter((gate) => gate.ruling.status !== 'approved' && gate.at !== 'workflow').map((gate) => gate.at));
+  const unapprovedGateAt = new Set(
+    gates
+      .filter((gate) => gate.ruling.status !== 'approved' && gate.at !== 'workflow')
+      .map((gate) => gate.at),
+  );
 
   /**
    * 工作项视图累积