@longzai-intelligence-workflow/core 0.0.1

package/src/utils/dag.utils.ts

@@ -0,0 +1,95 @@
+/**
+ * DAG 机件（环检测 + 拓扑分层 + 依赖满足判定）
+ *
+ * 共享基础（设计对齐 scheduler workflow 域已验证机件；真源归本包，禁止再镜像）。
+ */
+
+/**
+ * 依赖边（from 完成后 to 可启）
+ */
+export type DependencyEdge = { readonly from: string; readonly to: string };
+
+/**
+ * 环检测（DFS 三色标记；返回首个环路径，无环为 null）
+ *
+ * @param edges - 依赖边集合
+ */
+export function detectCycle(edges: readonly DependencyEdge[]): readonly string[] | null {
+  /**
+   * 邻接表
+   */
+  const adjacency = new Map<string, string[]>();
+  for (const edge of edges) {
+    adjacency.set(edge.from, [...(adjacency.get(edge.from) ?? []), edge.to]);
+  }
+
+  /**
+   * 节点访问状态（0=未访问 1=在栈 2=完成）
+   */
+  const state = new Map<string, 0 | 1 | 2>();
+
+  /**
+   * 当前 DFS 路径
+   */
+  const path: string[] = [];
+
+  /**
+   * 单节点深搜（返回环路径或 null）
+   */
+  const visit = (node: string): readonly string[] | null => {
+    /**
+     * 当前节点状态
+     */
+    const current = state.get(node) ?? 0;
+    if (current === 1) {
+      /**
+       * 环路径：当前路径中该节点之后的部分 + 首尾相接
+       */
+      const start = path.indexOf(node);
+      return [...path.slice(start), node];
+    }
+    if (current === 2) {
+      return null;
+    }
+    state.set(node, 1);
+    path.push(node);
+    for (const next of adjacency.get(node) ?? []) {
+      /**
+       * 后继环路径
+       */
+      const cycle = visit(next);
+      if (cycle !== null) {
+        return cycle;
+      }
+    }
+    path.pop();
+    state.set(node, 2);
+    return null;
+  };
+
+  /**
+   * 全部节点（确定性排序）
+   */
+  const nodes = [...new Set(edges.flatMap((edge) => [edge.from, edge.to]))].sort((left, right) => (left < right ? -1 : 1));
+  for (const node of nodes) {
+    /**
+     * 各节点环检测
+     */
+    const cycle = visit(node);
+    if (cycle !== null) {
+      return cycle;
+    }
+  }
+  return null;
+}
+
+/**
+ * 依赖满足判定（全部前置达完成/验收才算满足；无前置视为满足）
+ *
+ * @param node - 目标工作项 id
+ * @param edges - 依赖边集合
+ * @param settled - 已闭环（完成/验收）的工作项集合
+ */
+export function dependenciesMet(node: string, edges: readonly DependencyEdge[], settled: ReadonlySet<string>): boolean {
+  return edges.filter((edge) => edge.to === node).every((edge) => settled.has(edge.from));
+}

package/src/utils/declaration-frontmatter.utils.ts

@@ -0,0 +1,138 @@
+/**
+ * 声明档 frontmatter 解析（极简 YAML 方言 + 字符串数组扩展；自足实现零外部依赖）
+ *
+ * 方言与 data-engine stringifyFrontmatter 同源：顶层标量 + 字符串数组
+ * （`key:` 后随 `  - item` 行）；数组/嵌套之外的结构不在声明档契约内。
+ */
+
+/**
+ * 声明档解析结果（frontmatter 标量与字符串数组 + 正文）
+ */
+export type ParsedDeclaration = {
+  /**
+   * 顶层标量键值
+   */
+  readonly head: Record<string, string>;
+
+  /**
+   * 字符串数组键值（空数组键不出现）
+   */
+  readonly arrays: Record<string, readonly string[]>;
+
+  /**
+   * 正文（frontmatter 结束标记之后全文）
+   */
+  readonly body: string;
+};
+
+/**
+ * 剥标量引号（与 data-engine parseFrontmatterHead 同规则）
+ *
+ * @param raw - 原始值文本
+ * @returns 剥引号后的值
+ */
+function unquoteScalar(raw: string): string {
+  /**
+   * 首尾成对双引号判定后的剥壳结果
+   */
+  const unquoted =
+    raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"') ? raw.slice(1, -1) : raw;
+
+  return unquoted;
+}
+
+/**
+ * 提取正文（frontmatter 结束标记之后全文；无 frontmatter 时为原文）
+ *
+ * @param documentText - 文档全文
+ * @returns 正文文本
+ */
+function extractBody(documentText: string): string {
+  if (!documentText.startsWith('---\n')) {
+    return documentText;
+  }
+
+  /**
+   * frontmatter 结束标记位置
+   */
+  const end = documentText.indexOf('\n---\n', 4);
+  if (end === -1) {
+    return documentText;
+  }
+  return documentText.slice(end + '\n---\n'.length);
+}
+
+/**
+ * 解析声明档（frontmatter 标量 + 字符串数组；非法行跳过）
+ *
+ * @param documentText - 文档全文
+ * @returns 解析结果（无 frontmatter 时 head/arrays 为空对象、body 为全文）
+ */
+export function parseDeclaration(documentText: string): ParsedDeclaration {
+  /**
+   * 顶层标量键值累积
+   */
+  const head: Record<string, string> = {};
+
+  /**
+   * 字符串数组键值累积
+   */
+  const arrays: Record<string, readonly string[]> = {};
+
+  /**
+   * 正文（自足提取，零外部依赖）
+   */
+  const body = extractBody(documentText);
+  if (!documentText.startsWith('---\n')) {
+    return { head, arrays, body };
+  }
+
+  /**
+   * frontmatter 结束标记位置
+   */
+  const end = documentText.indexOf('\n---\n', 4);
+  if (end === -1) {
+    return { head, arrays, body };
+  }
+
+  /**
+   * frontmatter 头部行序列
+   */
+  const lines = documentText.slice(4, end).split('\n');
+
+  /**
+   * 当前数组键（最近一个 `key:` 或 `key: []` 行；非数组项行复位为 null）
+   */
+  let currentArrayKey: string | null = null;
+  for (const line of lines) {
+    if (line.startsWith('  - ') && currentArrayKey !== null) {
+      /**
+       * 数组项文本（剥引号）
+       */
+      const item = unquoteScalar(line.slice(4).trim());
+      arrays[currentArrayKey] = [...(arrays[currentArrayKey] ?? []), item];
+      continue;
+    }
+    currentArrayKey = null;
+    if (line.endsWith(': []')) {
+      currentArrayKey = line.slice(0, -4);
+      arrays[currentArrayKey] = [];
+      continue;
+    }
+    if (line.endsWith(':')) {
+      currentArrayKey = line.slice(0, -1);
+      arrays[currentArrayKey] = [];
+      continue;
+    }
+
+    /**
+     * 键值分隔符位置
+     */
+    const separator = line.indexOf(': ');
+    if (separator > 0 && !line.startsWith('  ')) {
+      head[line.slice(0, separator)] = unquoteScalar(line.slice(separator + 2));
+    }
+  }
+
+  return { head, arrays, body };
+}

package/src/utils/index.ts

@@ -0,0 +1,19 @@
+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);
+  const offset = (Math.max(page ?? 1, 1) - 1) * limit;
+  return { offset, limit };
+}
+
+export function getTotalPages(total: number, pageSize: number): number {
+  return Math.ceil(total / pageSize);
+}
+
+export function formatDate(date: string | Date): string {
+  return new Date(date).toISOString();
+}
+
+export * from './declaration-frontmatter.utils';
+export * from './dag.utils';
+export * from './work-item-rules.utils';

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

@@ -0,0 +1,194 @@
+/**
+ * 工作项判定核（纯函数、零 I/O——输入声明形态，输出视图与违规）
+ *
+ * 判定器契约：只判不动（对齐家族 verify 模式）；执行状态归声明档由属主维护，
+ * 本模块不做任何状态写入，仅依据声明现状派生视图与转移合法性。
+ */
+import type { WorkflowEdge, WorkflowGate, WorkflowItem, WorkItemStatus } from '../schemas/workflow-doc.schema';
+
+/**
+ * 工作项合法状态转移表（状态机唯一注册点；供编辑工具与判定器共用的规则真源）
+ */
+export const ALLOWED_STATUS_TRANSITIONS: Readonly<Record<WorkItemStatus, readonly WorkItemStatus[]>> = {
+  todo: ['doing', 'blocked', 'dropped'],
+  doing: ['blocked', 'done', 'dropped'],
+  blocked: ['todo', 'doing', 'dropped'],
+  done: ['todo', 'dropped'],
+  dropped: ['todo'],
+};
+
+/**
+ * 非法转移错误形态
+ */
+export type InvalidTransitionError = {
+  /**
+   * 错误码
+   */
+  readonly code: 'INVALID_TRANSITION';
+
+  /**
+   * 人读信息（含合法后继清单）
+   */
+  readonly message: string;
+};
+
+/**
+ * 判定状态转移合法性（注册表执法）
+ *
+ * @param from - 当前状态
+ * @param to - 目标状态
+ * @returns 合法时为 null；非法时携带合法后继清单
+ */
+export function checkStatusTransition(from: WorkItemStatus, to: WorkItemStatus): InvalidTransitionError | null {
+  /**
+   * 注册表中的合法后继
+   */
+  const allowed = ALLOWED_STATUS_TRANSITIONS[from];
+  if (allowed === undefined) {
+    return { code: 'INVALID_TRANSITION', message: `未知状态：${from}` };
+  }
+  if (!allowed.includes(to)) {
+    return { code: 'INVALID_TRANSITION', message: `非法转移：${from} → ${to}（合法后继：${allowed.join(' / ')}）` };
+  }
+  return null;
+}
+
+/**
+ * 工作项视图（快照派生：依赖满足与可启动判定）
+ */
+export type WorkItemView = {
+  /**
+   * 工作项 id
+   */
+  readonly id: string;
+
+  /**
+   * 执行状态（声明档现状）
+   */
+  readonly status: WorkItemStatus;
+
+  /**
+   * 依赖是否满足（全部前置达 done/dropped）
+   */
+  readonly depsMet: boolean;
+
+  /**
+   * 派生标注：todo 且依赖未满足
+   */
+  readonly blockedOnPrerequisite: boolean;
+
+  /**
+   * 现在是否可启动（todo + 依赖满足 + 挂靠门已批准或无门）
+   */
+  readonly canStart: boolean;
+};
+
+/**
+ * 未决裁定视图项
+ */
+export type PendingRulingView = {
+  /**
+   * 门键（at:kind）
+   */
+  readonly key: string;
+
+  /**
+   * 挂靠位置
+   */
+  readonly at: string;
+
+  /**
+   * 门类型
+   */
+  readonly kind: string;
+
+  /**
+   * 说明
+   */
+  readonly note: string;
+
+  /**
+   * 裁定状态（pending 未裁 / escalated 升级待裁）
+   */
+  readonly rulingStatus: 'pending' | 'escalated';
+};
+
+/**
+ * 工作流声明视图（判定器输出：全部工作项视图 + 未决裁定清单）
+ */
+export type WorkflowView = {
+  /**
+   * 工作项视图清单（按声明序）
+   */
+  readonly items: readonly WorkItemView[];
+
+  /**
+   * 未决裁定清单（pending 与 escalated）
+   */
+  readonly pendingRulings: readonly PendingRulingView[];
+};
+
+/**
+ * 已闭环状态集合（依赖满足判定基准：done 或 dropped 均不再阻塞后继）
+ *
+ * @param status - 工作项状态
+ */
+function isSettled(status: WorkItemStatus): boolean {
+  return status === 'done' || status === 'dropped';
+}
+
+/**
+ * 派生工作流声明视图（纯函数：声明现状 → 可启动/阻塞/未决裁定视图）
+ *
+ * @param items - 工作项清单（声明档现状）
+ * @param edges - 依赖边清单
+ * @param gates - 裁定门清单（含裁定事实）
+ */
+export function deriveWorkflowView(
+  items: readonly WorkflowItem[],
+  edges: readonly WorkflowEdge[],
+  gates: readonly WorkflowGate[],
+): WorkflowView {
+  /**
+   * 已闭环工作项 id 集合
+   */
+  const settled = new Set(items.filter((item) => isSettled(item.status)).map((item) => item.id));
+
+  /**
+   * 各工作项挂靠的未批准门（ruling.status 非 approved 即阻塞）
+   */
+  const unapprovedGateAt = new Set(gates.filter((gate) => gate.ruling.status !== 'approved' && gate.at !== 'workflow').map((gate) => gate.at));
+
+  /**
+   * 工作项视图累积
+   */
+  const views: WorkItemView[] = items.map((item) => {
+    /**
+     * 依赖满足判定（全部前置闭环）
+     */
+    const depsMet = edges.filter((edge) => edge.to === item.id).every((edge) => settled.has(edge.from));
+
+    return {
+      id: item.id,
+      status: item.status,
+      depsMet,
+      blockedOnPrerequisite: item.status === 'todo' && !depsMet,
+      canStart: item.status === 'todo' && depsMet && !unapprovedGateAt.has(item.id),
+    };
+  });
+
+  /**
+   * 未决裁定视图累积（pending 与 escalated）
+   */
+  const pendingRulings: PendingRulingView[] = gates
+    .filter((gate) => gate.ruling.status === 'pending' || gate.ruling.status === 'escalated')
+    .map((gate) => ({
+      key: `${gate.at}:${gate.kind}`,
+      at: gate.at,
+      kind: gate.kind,
+      note: gate.note,
+      rulingStatus: gate.ruling.status as 'pending' | 'escalated',
+    }));
+
+  return { items: views, pendingRulings };
+}