ai-git-tools 2.1.13 → 2.1.15

package/src/redmine/subtask-sync.js

@@ -0,0 +1,349 @@
+import {
+  analyzeSubtasks as defaultAnalyzeSubtasks,
+  MIN_MAX_SUBTASKS,
+  MAX_MAX_SUBTASKS,
+  normalizeFrontendAnalysis,
+  validateFrontendAnalysis,
+} from './subtask-analyzer.js';
+import {
+  formatSubtaskContent,
+  getManagedSubtaskKey,
+  buildManagedSubtaskKey,
+} from './subtask-formatters.js';
+
+function getProjectId(issue = {}) {
+  return issue.projectId ?? issue.project?.id ?? null;
+}
+
+function getTrackerId(issue = {}) {
+  return issue.trackerId ?? issue.tracker?.id ?? null;
+}
+
+function sameValue(left, right) {
+  return (left ?? null) === (right ?? null);
+}
+
+function normalizeRelations(relations = []) {
+  return (Array.isArray(relations) ? relations : [])
+    .map(relation => ({
+      id: relation?.id ?? null,
+      issueId: relation?.issue_id ?? relation?.issueId ?? null,
+      issueToId: relation?.issue_to_id ?? relation?.issueToId ?? null,
+      relationType: relation?.relation_type ?? relation?.relationType ?? null,
+    }))
+    .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+}
+
+function getParentSnapshot(parent) {
+  return {
+    id: parent.id,
+    subject: parent.subject || '',
+    description: parent.description || '',
+    projectId: getProjectId(parent),
+    trackerId: getTrackerId(parent),
+    children: Array.isArray(parent.children)
+      ? parent.children.map(child => ({
+        id: child.id,
+        subject: child.subject || '',
+        description: child.description || '',
+      }))
+      : [],
+    relations: normalizeRelations(parent.relations),
+  };
+}
+
+function assertParentMetadata(parent) {
+  if (getProjectId(parent) === null || getTrackerId(parent) === null) {
+    throw new Error(`Issue #${parent.id} 缺少建立子任務需要的 project 或 tracker 資訊`);
+  }
+}
+
+function sanitizeError(error, client) {
+  const secret = client?.apiKey;
+  return secret ? String(error?.message || error).replaceAll(secret, '[REDACTED]') : String(error?.message || error);
+}
+
+function assertDraftDoesNotContainPrivateFields(value, path = 'draft') {
+  if (!value || typeof value !== 'object') return;
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertDraftDoesNotContainPrivateFields(item, `${path}[${index}]`));
+    return;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    if (/raw|secret|token|password|private|credential|api[-_]?key/i.test(key)) {
+      throw new Error(`Frontend 子任務 draft 含有禁止保存的欄位：${path}.${key}`);
+    }
+    assertDraftDoesNotContainPrivateFields(item, `${path}.${key}`);
+  }
+}
+
+function hasParentConflict(expected, current) {
+  return expected.subject !== current.subject
+    || expected.description !== current.description
+    || !sameValue(getProjectId(expected), getProjectId(current))
+    || !sameValue(getTrackerId(expected), getTrackerId(current))
+    || JSON.stringify(normalizeRelations(expected.relations)) !== JSON.stringify(normalizeRelations(current.relations));
+}
+
+function getExistingChildTitles(children = []) {
+  return new Set(children.map(child => String(child.subject || '').trim().toLocaleLowerCase()).filter(Boolean));
+}
+
+function getExistingManagedKeys(children = []) {
+  return new Set(children.map(child => getManagedSubtaskKey(child.description)).filter(Boolean));
+}
+
+async function loadChildDetails(client, children = []) {
+  const unavailableChildIds = [];
+  if (typeof client?.getIssue !== 'function') {
+    return {
+      children,
+      unavailableChildIds: children
+        .filter(child => !child.description)
+        .map(child => child.id ?? 'unknown'),
+    };
+  }
+  const detailedChildren = await Promise.all(children.map(async child => {
+    if (child.description) return child;
+    if (child.id === undefined || child.id === null) {
+      unavailableChildIds.push('unknown');
+      return child;
+    }
+    try {
+      const detail = await client.getIssue(child.id);
+      return { ...child, description: detail.description || '' };
+    } catch {
+      unavailableChildIds.push(child.id);
+      return child;
+    }
+  }));
+  return { children: detailedChildren, unavailableChildIds };
+}
+
+/**
+ * 產生主 Issue 子任務 draft
+ * @param {{parentIssueId: number|string, client: object, analyzeSubtasksFn?: Function, maxSubtasks?: number, model?: string, maxRetries?: number, onProgress?: Function}} options
+ * @returns {Promise<object>}
+ */
+export async function generateSubtaskDraft({
+  parentIssueId,
+  client,
+  analyzeSubtasksFn = defaultAnalyzeSubtasks,
+  maxSubtasks = 8,
+  repositoryContext = {},
+  model,
+  maxRetries,
+  onProgress = () => {},
+}) {
+  onProgress({ phase: 'read-parent', parentIssueId });
+  const parent = await client.getIssue(parentIssueId, { include: 'children,relations' });
+  assertParentMetadata(parent);
+  onProgress({ phase: 'parent-read', parentIssueId, subject: parent.subject });
+  onProgress({ phase: 'scope-analysis', parentIssueId });
+  onProgress({ phase: 'analyze-subtasks', parentIssueId });
+  const analysis = await analyzeSubtasksFn({
+    issue: parent,
+    maxSubtasks,
+    repositoryContext,
+    model,
+    maxRetries,
+  });
+  if (analysis.schemaVersion !== 2) {
+    throw new Error('Frontend 子任務分析必須回傳 schemaVersion 2，請重新產生 preview');
+  }
+  validateFrontendAnalysis(analysis, parentIssueId, maxSubtasks);
+  onProgress({ phase: 'subtasks-analyzed', parentIssueId, count: analysis.subtasks.length });
+
+  if (analysis.scopeDecision?.status === 'none') {
+    throw new Error(`Issue #${parentIssueId} 沒有可建立的 Frontend 子任務`);
+  }
+  if (analysis.scopeDecision?.status === 'unclear') {
+    throw new Error(`Issue #${parentIssueId} 的 Frontend scope 不明，請先確認 unresolved items`);
+  }
+  if (!analysis.subtasks.length) {
+    throw new Error(`Issue #${parentIssueId} 沒有產生有效的 Frontend 子任務`);
+  }
+
+  const subtasks = analysis.subtasks.map((subtask, index) => {
+    onProgress({
+      phase: 'screen-enrichment',
+      index: index + 1,
+      total: analysis.subtasks.length,
+      parentIssueId,
+      title: subtask.title,
+    });
+    return {
+      ...subtask,
+      title: subtask.title,
+      content: formatSubtaskContent({
+        subtask,
+        parentIssueId: parent.id,
+        scopeDecision: analysis.scopeDecision,
+        evidence: analysis.evidence,
+      }),
+    };
+  });
+
+  return {
+    version: 2,
+    schemaVersion: 2,
+    generatedAt: new Date().toISOString(),
+    analysisScope: analysis.analysisScope,
+    maxSubtasks,
+    isIndivisible: Boolean(analysis.isIndivisible),
+    indivisibleReason: analysis.indivisibleReason || '',
+    scopeDecision: analysis.scopeDecision,
+    evidence: analysis.evidence || [],
+    unresolvedItems: analysis.unresolvedItems || [],
+    parent: getParentSnapshot(parent),
+    subtasks,
+  };
+
+}
+
+/**
+ * 套用已審核的子任務 draft
+ * @param {{draft: object, client: object, force?: boolean, onProgress?: Function}} options
+ * @returns {Promise<Array<object>>}
+ */
+export async function applySubtaskDraft({ draft, client, force = false, onProgress = () => {} }) {
+  validateSubtaskDraft(draft);
+  const parentIssueId = draft.parent.id;
+  const current = await client.getIssue(parentIssueId, { include: 'children,relations' });
+  if (!force && hasParentConflict(draft.parent, current)) {
+    return [{ parentIssueId, blocked: true, reason: 'conflict' }];
+  }
+  assertParentMetadata(draft.parent);
+
+  const childDetails = await loadChildDetails(
+    client,
+    Array.isArray(current.children) ? current.children : []
+  );
+  if (childDetails.unavailableChildIds.length > 0) {
+    return [{
+      parentIssueId,
+      blocked: true,
+      reason: 'child-detail-unavailable',
+      childIds: childDetails.unavailableChildIds,
+    }];
+  }
+  const children = childDetails.children;
+  const managedKeys = getExistingManagedKeys(children);
+  const titles = getExistingChildTitles(children);
+  const results = [];
+  for (const [index, subtask] of draft.subtasks.entries()) {
+    const subtaskId = subtask.id || subtask.key;
+    onProgress({
+      phase: 'create-child',
+      index: index + 1,
+      total: draft.subtasks.length,
+      parentIssueId,
+      key: subtaskId,
+      title: subtask.title,
+    });
+    const managedKey = buildManagedSubtaskKey(parentIssueId, subtaskId);
+    if (managedKeys.has(managedKey) || titles.has(String(subtask.title).trim().toLocaleLowerCase())) {
+      results.push({
+        ...(draft.version === 2 ? { id: subtaskId } : { key: subtaskId }),
+        title: subtask.title,
+        skipped: true,
+        reason: 'duplicate',
+      });
+      continue;
+    }
+
+    try {
+      const child = await client.createIssue({
+        projectId: getProjectId(draft.parent),
+        trackerId: getTrackerId(draft.parent),
+        subject: subtask.title,
+        description: subtask.content,
+        parentIssueId,
+      });
+      results.push({
+        ...(draft.version === 2 ? { id: subtaskId } : { key: subtaskId }),
+        title: subtask.title,
+        created: true,
+        childId: child?.id ?? child?.issue?.id ?? null,
+      });
+      managedKeys.add(managedKey);
+      titles.add(String(subtask.title).trim().toLocaleLowerCase());
+    } catch (error) {
+      results.push({
+        ...(draft.version === 2 ? { id: subtaskId } : { key: subtaskId }),
+        title: subtask.title,
+        created: false,
+        error: sanitizeError(error, client),
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * 驗證子任務 draft 基本結構
+ * @param {object} draft
+ */
+export function validateSubtaskDraft(draft = {}) {
+  assertDraftDoesNotContainPrivateFields(draft);
+  if (draft.version !== 2 || draft.schemaVersion !== 2) {
+    throw new Error('Frontend 子任務 draft v1 不受支援，請重新產生 schemaVersion 2 preview');
+  }
+  if (draft.analysisScope !== 'frontend') {
+    throw new Error('Frontend 子任務 draft 的 analysisScope 必須是 frontend');
+  }
+  const maxSubtasks = draft.maxSubtasks === undefined ? MAX_MAX_SUBTASKS : Number(draft.maxSubtasks);
+  if (!Number.isInteger(maxSubtasks) || maxSubtasks < MIN_MAX_SUBTASKS || maxSubtasks > MAX_MAX_SUBTASKS) {
+    throw new Error(`Frontend 子任務 draft 的 maxSubtasks 必須介於 ${MIN_MAX_SUBTASKS} 到 ${MAX_MAX_SUBTASKS} 之間`);
+  }
+  if (!draft.scopeDecision || !['full', 'partial'].includes(draft.scopeDecision.status)) {
+    throw new Error('Frontend 子任務 draft 缺少可套用的 scopeDecision');
+  }
+  if (!draft.parent || !Array.isArray(draft.subtasks) || draft.subtasks.length === 0) {
+    throw new Error('Frontend 子任務 draft 格式不受支援');
+  }
+  if (draft.parent.id === undefined || draft.parent.id === null) {
+    throw new Error('子任務 draft 缺少 parent Issue ID');
+  }
+  const ids = new Set();
+  for (const subtask of draft.subtasks) {
+    if (!subtask?.id || !subtask.title?.trim() || !subtask.content?.trim()) {
+      throw new Error('Frontend 子任務 draft 缺少 id、title 或 content');
+    }
+    if (ids.has(subtask.id)) throw new Error(`Frontend 子任務 draft ID 重複：${subtask.id}`);
+    ids.add(subtask.id);
+  }
+  const normalizedAnalysis = normalizeFrontendAnalysis({
+    schemaVersion: draft.schemaVersion,
+    issueId: draft.parent.id,
+    analysisScope: draft.analysisScope,
+    isIndivisible: Boolean(draft.isIndivisible),
+    indivisibleReason: draft.indivisibleReason || '',
+    scopeDecision: draft.scopeDecision,
+    evidence: Array.isArray(draft.evidence) ? draft.evidence : [],
+    unresolvedItems: Array.isArray(draft.unresolvedItems) ? draft.unresolvedItems : [],
+    subtasks: draft.subtasks,
+  });
+  validateFrontendAnalysis(normalizedAnalysis, draft.parent.id, maxSubtasks);
+}
+
+/**
+ * 將子任務 draft 序列化為 JSON
+ * @param {object} draft
+ * @returns {string}
+ */
+export function serializeSubtaskDraft(draft) {
+  validateSubtaskDraft(draft);
+  return `${JSON.stringify(draft, null, 2)}\n`;
+}
+
+/**
+ * 解析子任務 draft JSON
+ * @param {string} content
+ * @returns {object}
+ */
+export function parseSubtaskDraft(content) {
+  const draft = JSON.parse(content);
+  validateSubtaskDraft(draft);
+  return draft;
+}