ai-git-tools 2.1.14 → 2.1.16

package/src/redmine/subtask-sync.js

@@ -1,4 +1,10 @@
-import { analyzeSubtasks as defaultAnalyzeSubtasks } from './subtask-analyzer.js';
+import {
+  analyzeSubtasks as defaultAnalyzeSubtasks,
+  MIN_MAX_SUBTASKS,
+  MAX_MAX_SUBTASKS,
+  normalizeFrontendAnalysis,
+  validateFrontendAnalysis,
+} from './subtask-analyzer.js';
 import {
   formatSubtaskContent,
   getManagedSubtaskKey,
@@ -17,10 +23,33 @@ 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) {
-  const snapshot = { ...parent, children: Array.isArray(parent.children) ? parent.children : [] };
-  delete snapshot.raw;
-  return snapshot;
+  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) {
@@ -34,11 +63,26 @@ function sanitizeError(error, client) {
   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));
+    || !sameValue(getTrackerId(expected), getTrackerId(current))
+    || JSON.stringify(normalizeRelations(expected.relations)) !== JSON.stringify(normalizeRelations(current.relations));
 }
 
 function getExistingChildTitles(children = []) {
@@ -49,17 +93,39 @@ function getExistingManagedKeys(children = []) {
   return new Set(children.map(child => getManagedSubtaskKey(child.description)).filter(Boolean));
 }
 
+function getReplaceableChildren(parent, children, parentIssueId) {
+  const childrenById = new Map(children.map(child => [String(child.id), child]));
+  const managedPrefix = buildManagedSubtaskKey(parentIssueId, '');
+  return (Array.isArray(parent?.children) ? parent.children : [])
+    .map(child => childrenById.get(String(child?.id)))
+    .filter(child => getManagedSubtaskKey(child?.description)?.startsWith(managedPrefix));
+}
+
 async function loadChildDetails(client, children = []) {
-  if (typeof client?.getIssue !== 'function') return children;
-  return Promise.all(children.map(async child => {
-    if (child.description || child.id === undefined || child.id === null) return child;
+  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, { include: '' });
+      const detail = await client.getIssue(child.id);
       return { ...child, description: detail.description || '' };
     } catch {
+      unavailableChildIds.push(child.id);
       return child;
     }
   }));
+  return { children: detailedChildren, unavailableChildIds };
 }
 
 /**
@@ -72,6 +138,7 @@ export async function generateSubtaskDraft({
   client,
   analyzeSubtasksFn = defaultAnalyzeSubtasks,
   maxSubtasks = 8,
+  repositoryContext = {},
   model,
   maxRetries,
   onProgress = () => {},
@@ -80,36 +147,74 @@ export async function generateSubtaskDraft({
   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 });
 
-  const subtasks = analysis.subtasks.map(subtask => ({
-    ...subtask,
-    title: subtask.title,
-    content: formatSubtaskContent({ subtask, parentIssueId: parent.id }),
-  }));
+  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: 1,
+    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,
-    unresolvedItems: analysis.unresolvedItems || [],
   };
+
 }
 
 /**
  * 套用已審核的子任務 draft
- * @param {{draft: object, client: object, force?: boolean, onProgress?: Function}} options
+ * @param {{draft: object, client: object, force?: boolean, replace?: boolean, onProgress?: Function}} options
  * @returns {Promise<Array<object>>}
  */
-export async function applySubtaskDraft({ draft, client, force = false, onProgress = () => {} }) {
+export async function applySubtaskDraft({ draft, client, force = false, replace = false, onProgress = () => {} }) {
   validateSubtaskDraft(draft);
   const parentIssueId = draft.parent.id;
   const current = await client.getIssue(parentIssueId, { include: 'children,relations' });
@@ -118,25 +223,73 @@ export async function applySubtaskDraft({ draft, client, force = false, onProgre
   }
   assertParentMetadata(draft.parent);
 
-  const children = await loadChildDetails(
+  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 replaceableChildren = replace
+    ? getReplaceableChildren(draft.parent, children, parentIssueId)
+    : [];
+  const replacedChildIds = new Set();
   const managedKeys = getExistingManagedKeys(children);
   const titles = getExistingChildTitles(children);
   const results = [];
   for (const [index, subtask] of draft.subtasks.entries()) {
+    const subtaskId = subtask.id || subtask.key;
+    const managedKey = buildManagedSubtaskKey(parentIssueId, subtaskId);
+    const replacement = replace
+      ? replaceableChildren.find(child => !replacedChildIds.has(String(child.id))
+        && getManagedSubtaskKey(child.description) === managedKey)
+        || replaceableChildren.find(child => !replacedChildIds.has(String(child.id)))
+      : null;
     onProgress({
-      phase: 'create-child',
+      phase: replacement ? 'replace-child' : 'create-child',
       index: index + 1,
       total: draft.subtasks.length,
       parentIssueId,
-      key: subtask.key,
+      key: subtaskId,
       title: subtask.title,
     });
-    const managedKey = buildManagedSubtaskKey(parentIssueId, subtask.key);
+    if (replacement) {
+      replacedChildIds.add(String(replacement.id));
+      try {
+        await client.updateIssue(replacement.id, {
+          subject: subtask.title,
+          description: subtask.content,
+        });
+        results.push({
+          ...(draft.version === 2 ? { id: subtaskId } : { key: subtaskId }),
+          title: subtask.title,
+          updated: true,
+          childId: replacement.id,
+        });
+      } catch (error) {
+        results.push({
+          ...(draft.version === 2 ? { id: subtaskId } : { key: subtaskId }),
+          title: subtask.title,
+          updated: false,
+          childId: replacement.id,
+          error: sanitizeError(error, client),
+        });
+      }
+      continue;
+    }
     if (managedKeys.has(managedKey) || titles.has(String(subtask.title).trim().toLocaleLowerCase())) {
-      results.push({ key: subtask.key, title: subtask.title, skipped: true, reason: 'duplicate' });
+      results.push({
+        ...(draft.version === 2 ? { id: subtaskId } : { key: subtaskId }),
+        title: subtask.title,
+        skipped: true,
+        reason: 'duplicate',
+      });
       continue;
     }
 
@@ -149,7 +302,7 @@ export async function applySubtaskDraft({ draft, client, force = false, onProgre
         parentIssueId,
       });
       results.push({
-        key: subtask.key,
+        ...(draft.version === 2 ? { id: subtaskId } : { key: subtaskId }),
         title: subtask.title,
         created: true,
         childId: child?.id ?? child?.issue?.id ?? null,
@@ -158,7 +311,7 @@ export async function applySubtaskDraft({ draft, client, force = false, onProgre
       titles.add(String(subtask.title).trim().toLocaleLowerCase());
     } catch (error) {
       results.push({
-        key: subtask.key,
+        ...(draft.version === 2 ? { id: subtaskId } : { key: subtaskId }),
         title: subtask.title,
         created: false,
         error: sanitizeError(error, client),
@@ -173,17 +326,46 @@ export async function applySubtaskDraft({ draft, client, force = false, onProgre
  * @param {object} draft
  */
 export function validateSubtaskDraft(draft = {}) {
-  if (draft.version !== 1 || !draft.parent || !Array.isArray(draft.subtasks) || draft.subtasks.length === 0) {
-    throw new Error('子任務 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?.key || !subtask.title?.trim() || !subtask.content?.trim()) {
-      throw new Error('子任務 draft 缺少 key、title 或 content');
+    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);
 }
 
 /**