Merge pull request #915 from githru/refactor/csm-improvements

refactor(engine): CSM 코드 구조 및 가독성 개선

Author: SingTheCode

packages/analysis-engine/src/csm.ts

@@ -1,6 +1,17 @@
+import {
+  collectSquashNodes,
+  extractNestedMergeParents,
+  findSquashEndIndex,
+  findSquashStartNodeIndex,
+  getParentCommits,
+} from "./csm.util";
 import { convertPRCommitsToCommitNodes, convertPRDetailToCommitRaw } from "./pullRequest";
 import type { CommitDict, CommitNode, CSMDictionary, CSMNode, PullRequest, PullRequestDict, StemDict } from "./types";
 
+/**
+ * Builds a CSM node.
+ * For merge commits, collects squashed commits using DFS traversal.
+ */
 const buildCSMNode = (baseCommitNode: CommitNode, commitDict: CommitDict, stemDict: StemDict): CSMNode => {
   if (baseCommitNode.commit.parents.length <= 1) {
     return {
@@ -9,11 +20,8 @@ const buildCSMNode = (baseCommitNode: CommitNode, commitDict: CommitDict, stemDi
     };
   }
 
-  const mergeParentCommits = baseCommitNode.commit.parents
-    .slice(1)
-    .map((parentId) => commitDict.get(parentId))
-    .filter((commit): commit is CommitNode => !!commit);
-
+  // Return empty source for non-merge commits
+  const mergeParentCommits = getParentCommits(baseCommitNode, commitDict);
   if (mergeParentCommits.length === 0) {
     return {
       base: baseCommitNode,
@@ -25,59 +33,41 @@ const buildCSMNode = (baseCommitNode: CommitNode, commitDict: CommitDict, stemDi
 
   const squashTaskQueue: CommitNode[] = [...mergeParentCommits];
   while (squashTaskQueue.length > 0) {
-    // get target
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const squashStartNode = squashTaskQueue.shift()!;
+    const squashStartNode = squashTaskQueue.shift();
+    if (!squashStartNode?.stemId) {
+      continue;
+    }
 
-    // get target's stem
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const squashStemId = squashStartNode.stemId!;
+    const squashStemId = squashStartNode.stemId;
     const squashStem = stemDict.get(squashStemId);
     if (!squashStem) {
       continue;
     }
 
-    // find squashStartNode index in stem
-    const squashStartNodeIndex = squashStem.nodes.findIndex(({ commit: { id } }) => id === squashStartNode.commit.id);
+    // Find the index of the start node in the stem
+    const squashStartNodeIndex = findSquashStartNodeIndex(squashStem, squashStartNode.commit.id);
     if (squashStartNodeIndex === -1) {
       continue;
     }
 
-    // collect nodes from squashStartNode to end of stem
-    // (or until the next mergedIntoStem node for future merges)
-    const spliceCommitNodes: CommitNode[] = [];
-
-    // First, find the end index (before next mergedIntoStem or end of stem)
-    let endIndex = squashStem.nodes.length - 1;
-    for (let i = squashStartNodeIndex + 1; i < squashStem.nodes.length; i++) {
-      if (squashStem.nodes[i].mergedIntoBaseStem) {
-        endIndex = i - 1;
-        break;
-      }
-    }
-
-    // Collect nodes from start to end
-    for (let i = squashStartNodeIndex; i <= endIndex; i++) {
-      spliceCommitNodes.push(squashStem.nodes[i]);
-    }
-
-    // remove collected nodes from stem
-    squashStem.nodes.splice(squashStartNodeIndex, spliceCommitNodes.length);
-    squashCommitNodes.push(...spliceCommitNodes);
-
-    // check nested-merge
-    const nestedMergeParentCommitIds = spliceCommitNodes
-      .filter((node) => node.commit.parents.length > 1)
-      .map((node) => node.commit.parents)
-      .reduce((pCommitIds, parents) => [...pCommitIds, ...parents], []);
-    const nestedMergeParentCommits = nestedMergeParentCommitIds
-      .map((commitId) => commitDict.get(commitId))
-      .filter((node): node is CommitNode => node !== undefined)
-      .filter((node) => node.stemId !== baseCommitNode.stemId && node.stemId !== squashStemId);
-
-    squashTaskQueue.push(...nestedMergeParentCommits);
+    // Find the end index for squash collection
+    const endIndex = findSquashEndIndex(squashStem, squashStartNodeIndex);
+
+    // Collect nodes and remove from stem
+    const collectedNodes = collectSquashNodes(squashStem, squashStartNodeIndex, endIndex);
+    squashCommitNodes.push(...collectedNodes);
+
+    // Handle nested merges: add branches to queue if collected nodes contain merge commits
+    const nestedMergeParents = extractNestedMergeParents(
+      collectedNodes,
+      commitDict,
+      baseCommitNode.stemId ?? "",
+      squashStemId
+    );
+    squashTaskQueue.push(...nestedMergeParents);
   }
 
+  // Sort by sequence order (reverse -> forward)
   squashCommitNodes.sort((a, b) => a.commit.sequence - b.commit.sequence);
 
   return {
@@ -86,6 +76,14 @@ const buildCSMNode = (baseCommitNode: CommitNode, commitDict: CommitDict, stemDi
   };
 };
 
+/**
+ * Integrates Pull Request information into a CSM node.
+ * Reflects PR details in commit message and statistics.
+ *
+ * @param csmNode - Existing CSM node
+ * @param pr - Pull Request information
+ * @returns CSM node with integrated PR information
+ */
 const buildCSMNodeWithPullRequest = (csmNode: CSMNode, pr: PullRequest): CSMNode => {
   const convertedCommit = convertPRDetailToCommitRaw(csmNode.base.commit, pr);
 
@@ -99,13 +97,16 @@ const buildCSMNodeWithPullRequest = (csmNode: CSMNode, pr: PullRequest): CSMNode
 };
 
 /**
- * CSM 생성
+ * Builds a CSM (Commit Summary Model) dictionary.
+ * Creates CSM nodes for each commit in the base branch,
+ * and integrates Pull Request information if available.
  *
- * @param {Map<string, CommitNode>} commitDict
- * @param {Map<string, Stem>} stemDict
- * @param {string} baseBranchName
- * @param {Array<PullRequest>} pullRequests
- * @returns {CSMDictionary}
+ * @param commitDict - Commit dictionary
+ * @param stemDict - Stem dictionary
+ * @param baseBranchName - Base branch name (e.g., 'main', 'master')
+ * @param pullRequests - Pull Request array (optional)
+ * @returns CSM dictionary (CSM node array per branch)
+ * @throws {Error} When there are no stems or no base branch stem
  */
 export const buildCSMDict = (
   commitDict: CommitDict,
@@ -118,7 +119,7 @@ export const buildCSMDict = (
     // return {};
   }
 
-  // v0.1 에서는 master STEM 으로만 CSM 생성함
+  // In v0.1, CSM is only created from the master STEM
   const masterStem = stemDict.get(baseBranchName);
   if (!masterStem) {
     throw new Error("no master-stem");

packages/analysis-engine/src/csm.util.ts

@@ -0,0 +1,74 @@
+import type { CommitDict, CommitNode, Stem } from "./types";
+
+/** Gets the second parent (starting point of merged branch) of a merge commit. */
+export const getParentCommits = (baseCommitNode: CommitNode, commitDict: CommitDict): CommitNode[] => {
+  return baseCommitNode.commit.parents
+    .slice(1)
+    .map((parentId) => commitDict.get(parentId))
+    .filter((commit): commit is CommitNode => !!commit);
+};
+
+/** Finds the index of a specific commit node in a stem. */
+export const findSquashStartNodeIndex = (stem: Stem, commitId: string): number => {
+  return stem.nodes.findIndex(({ commit: { id } }) => id === commitId);
+};
+
+/**
+ * Finds the end index for squash collection.
+ * Collects until the next mergedIntoStem node appears or until the end of the stem.
+ */
+export const findSquashEndIndex = (stem: Stem, startIndex: number): number => {
+  let endIndex = stem.nodes.length - 1;
+
+  for (let i = startIndex + 1; i < stem.nodes.length; i++) {
+    if (stem.nodes[i].mergedIntoBaseStem) {
+      endIndex = i - 1;
+      break;
+    }
+  }
+
+  return endIndex;
+};
+
+/**
+ * Collects nodes from start index to end index in a stem and removes them.
+ *
+ * @param stem - Target stem
+ * @param startIndex - Start index
+ * @param endIndex - End index
+ * @returns Array of collected commit nodes
+ */
+export const collectSquashNodes = (stem: Stem, startIndex: number, endIndex: number): CommitNode[] => {
+  const nodesToCollect: CommitNode[] = [];
+
+  for (let i = startIndex; i <= endIndex; i++) {
+    nodesToCollect.push(stem.nodes[i]);
+  }
+
+  // Remove collected nodes from stem
+  stem.nodes.splice(startIndex, nodesToCollect.length);
+
+  return nodesToCollect;
+};
+
+/**
+ * Extracts parent commits of nested merges from squashed nodes.
+ * Returns parent commits that do not belong to the base stem or current squash stem.
+ */
+export const extractNestedMergeParents = (
+  squashedNodes: CommitNode[],
+  commitDict: CommitDict,
+  baseStemId: string,
+  currentSquashStemId: string
+): CommitNode[] => {
+  // Collect all parent commit IDs from merge commits
+  const nestedMergeParentCommitIds = squashedNodes
+    .filter((node) => node.commit.parents.length > 1)
+    .map((node) => node.commit.parents)
+    .reduce((pCommitIds, parents) => [...pCommitIds, ...parents], []);
+
+  return nestedMergeParentCommitIds
+    .map((commitId) => commitDict.get(commitId))
+    .filter((node): node is CommitNode => node !== undefined)
+    .filter((node) => node.stemId !== baseStemId && node.stemId !== currentSquashStemId);
+};