@ibgib/vcs-gib 0.0.23 → 0.0.29

package/src/cli/commands/commit-cmd.mts

@@ -2,13 +2,15 @@
  * @module commit-cmd
  * 
  * Command handler for `vcs commit -m "message"`.
- * Validates staged items, evolves the B2tFS root folder item graph in localSpace,
- * creates a CommentIbGib_V1 commit comment node, advances active B2tFSBranchIbGib_V1 pointer,
- * clears staged items in B2tFSIndexIbGib_V1, and updates read-only index projection cache.
+ * Ingests staged items and co-located .ib.*.md comment metadata files,
+ * attaches comments to corresponding file and folder b2tfs_items,
+ * attaches overall commit message to root b2tfs_item, evolves root item,
+ * advances B2tFSBranchIbGib_V1 with committedPaths, and clears index staging area.
  */
 
 import path from 'node:path';
 import fs from 'node:fs/promises';
+import { Dirent } from 'node:fs';
 import crypto from 'node:crypto';
 
 import { getUUID, extractErrorMsg, delay } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
@@ -16,19 +18,18 @@ import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
 import { ROOT } from '@ibgib/ts-gib/dist/V1/constants.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 import { putInSpace, persistTransformResult } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
-import { getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
 import { createCommentIbGib } from '@ibgib/core-gib/dist/common/comment/comment-helper.mjs';
 import { CommentIbGib_V1 } from '@ibgib/core-gib/dist/common/comment/comment-types.mjs';
 
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
 import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
-import { getB2tFSItemIb } from '../../engine/item/item-atom-helper.mjs';
 import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } from '../../engine/item/item-types.mjs';
 import { getIbGibWithMetaspaceFallback, createB2tFSItemIbGib, evolveB2tFSItemIbGib } from '../../engine/item/item-helper.mjs';
-import { getB2tFSBranchSpaceName } from '../../engine/branch/branch-helper.mjs';
+import { getB2tFSBranchSpaceName, resolveContextualBranchName } from '../../engine/branch/branch-helper.mjs';
 import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
 import { getB2tFSIndexIbGib, updateB2tFSIndexIbGib, getSpaceQualifiedIbGibAddr } from '../../engine/index/index-helper.mjs';
 import { B2tFSStagedItemRecord } from '../../engine/index/index-types.mjs';
+import { isCommentMetadataFilename, extractCommentTopicName } from '../../engine/status/status-helper.mjs';
 import { TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
 import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
@@ -45,7 +46,7 @@ export interface CommitCmdOpts {
 
 export interface CommitCmdResult {
     commitAddr: string;
-    commentAddr: string;
+    commentAddr?: string;
     branchName: string;
     committedPaths: string[];
     rootItemAddr: string;
@@ -78,18 +79,18 @@ export async function executeCommitCmd({
             throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d)`);
         }
 
-        // Validate message
-        if (!message || message.trim().length === 0) {
-            throw new Error(`Commit message is required (E: 2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e)`);
-        }
-
         // Fetch authoritative repository index from localSpace
         const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, vcsPath });
         if (!indexIbGib) {
             throw new Error(`Repository index B2tFSIndexIbGib_V1 not found in localSpace (E: 3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f)`);
         }
 
-        const branchName = indexIbGib.data?.activeBranch || 'main';
+        const branchName = resolveContextualBranchName({
+            targetDir: absTargetDir,
+            repoRoot,
+            indexIbGib,
+        });
+        const activeWorktreeDir = branchName === 'main' ? repoRoot : path.join(repoRoot, 'b', branchName);
 
         // Target active branch space b2s_<activeBranch>
         const { space: activeSpace } = await getOrCreateBranchSpace({
@@ -98,24 +99,22 @@ export async function executeCommitCmd({
             branchName,
         });
 
-        // Validate staged items
-        const stagedPathsMap = indexIbGib.data?.stagedPaths || {};
-        const stagedAddrs = indexIbGib.data?.staged_item || [];
+        // Verify there are staged items
+        const stagedPathsMap: { [relPath: string]: B2tFSStagedItemRecord } = { ...(indexIbGib.data?.stagedPaths || {}) };
         const committedPaths = Object.keys(stagedPathsMap);
-
-        if (committedPaths.length === 0 || stagedAddrs.length === 0) {
-            throw new Error(`Nothing to commit (no staged items) (E: 4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a)`);
+        if (committedPaths.length === 0) {
+            throw new Error(`Nothing to commit (no staged items found in index) (E: 4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a)`);
         }
 
-        // Fetch active branch node from activeSpace
+        // Find active branch node
+        let currentBranchIbGib: B2tFSBranchIbGib_V1 | undefined;
+        let currentBranchAddr: string | undefined;
+
         const branchAddrs = [
             ...(indexIbGib.rel8ns?.branch || []),
             ...(indexIbGib.rel8ns?.branch_tjp || []),
         ];
 
-        let currentBranchIbGib: B2tFSBranchIbGib_V1 | undefined;
-        let currentBranchAddr: string | undefined;
-
         if (branchAddrs.length > 0) {
             let branchIbGibs: B2tFSBranchIbGib_V1[] = [];
             for (const bAddr of branchAddrs) {
@@ -133,35 +132,54 @@ export async function executeCommitCmd({
                 (b) => (b as B2tFSBranchIbGib_V1)?.data?.name === branchName,
             ) as B2tFSBranchIbGib_V1 || (branchIbGibs.at(-1) as B2tFSBranchIbGib_V1);
 
-
             if (currentBranchIbGib) {
                 currentBranchAddr = getIbGibAddr({ ibGib: currentBranchIbGib });
             }
         }
 
-        const currentRootAddr = currentBranchIbGib?.rel8ns?.b2tfs_item?.at(-1);
-
+        const currentRootAddr = currentBranchIbGib?.rel8ns?.b2tFS_item?.at(-1) || currentBranchIbGib?.rel8ns?.b2tfs_item?.at(-1);
 
-        // 1. Create CommentIbGib_V1 commit comment node in activeSpace
-        const commentRes = await createCommentIbGib({
-            text: message.trim(),
-            saveInSpace: true,
-            space: activeSpace,
-        });
-        const commentIbGib = commentRes.newIbGib as CommentIbGib_V1;
-        const commentAddr = getIbGibAddr({ ibGib: commentIbGib });
-        await metaspace.registerNewIbGib({ ibGib: commentIbGib, space: activeSpace });
-
-        // 2. Evolve root folder item graph with staged items in activeSpace
+        // 1. Evolve root item graph with staged items and ingest co-located .ib.*.md comment files
         const repoName = path.basename(repoRoot) || 'root';
-        const { newRootAddr } = await commitCmd_buildEvolvedRootItem({
+        let { newRootItem, newRootAddr, ingestedCommentCount } = await commitCmd_buildEvolvedRootItem({
             currentRootAddr,
             stagedPathsMap,
             space: activeSpace,
             metaspace,
             repoName,
+            worktreeDir: activeWorktreeDir,
         });
 
+        if ((!message || message.trim().length === 0) && ingestedCommentCount === 0) {
+            throw new Error(`Commit message is required (-m "message" or companion comment files) (E: 2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e)`);
+        }
+
+        // 2. If CLI message is provided, attach CommentIbGib to the root b2tfs item
+        let commentAddr: string | undefined;
+        if (message && message.trim().length > 0) {
+            const commentRes = await createCommentIbGib({
+                text: message.trim(),
+                saveInSpace: true,
+                space: activeSpace,
+            });
+            const commentIbGib = commentRes.newIbGib as CommentIbGib_V1;
+            commentAddr = getIbGibAddr({ ibGib: commentIbGib });
+            await metaspace.registerNewIbGib({ ibGib: commentIbGib, space: activeSpace });
+
+            const existingComments = newRootItem.rel8ns?.comment || [];
+            const evolveRootRes = await evolveB2tFSItemIbGib({
+                existingItem: newRootItem,
+                rel8nsToUpdate: {
+                    comment: [...existingComments, commentAddr],
+                },
+            });
+            await persistTransformResult({ resTransform: evolveRootRes, space: activeSpace });
+            await metaspace.registerNewIbGib({ ibGib: evolveRootRes.newIbGib, space: activeSpace });
+
+            newRootItem = evolveRootRes.newIbGib as B2tFSItemIbGib_V1;
+            newRootAddr = getIbGibAddr({ ibGib: newRootItem });
+        }
+
         // 3. Advance B2tFSBranchIbGib_V1 node inside activeSpace
         const branchUuid = currentBranchIbGib?.data?.uuid || (await getUUID());
         const newBranchRes = await Factory_V1.firstGen({
@@ -173,10 +191,11 @@ export async function executeCommitCmd({
                 uuid: branchUuid,
                 classname: 'B2tFSBranchIbGib_V1',
                 committedAt: new Date().toISOString(),
+                committedPaths,
             },
             rel8ns: {
                 b2tfs_item: [newRootAddr],
-                comment: [commentAddr],
+                ...(commentAddr ? { comment: [commentAddr] } : {}),
             },
         });
 
@@ -212,7 +231,8 @@ export async function executeCommitCmd({
 
         if (!quiet) {
             const shortGib = newBranchIbGib.gib ? newBranchIbGib.gib.slice(0, 7) : 'commit';
-            console.log(`[${branchName} ${shortGib}] ${message.trim()} (I: 5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b)`);
+            const logMsg = message ? message.trim() : '(committed)';
+            console.log(`[${branchName} ${shortGib}] ${logMsg} (I: 5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b)`);
             console.log(` ${committedPaths.length} file(s) changed`);
         }
 
@@ -241,13 +261,16 @@ async function commitCmd_buildEvolvedRootItem({
     space,
     metaspace,
     repoName,
+    worktreeDir,
 }: {
     currentRootAddr?: string;
     stagedPathsMap: { [relPath: string]: B2tFSStagedItemRecord };
     space: any;
     metaspace: any;
     repoName: string;
-}): Promise<{ newRootItem: B2tFSItemIbGib_V1; newRootAddr: string }> {
+    worktreeDir: string;
+}): Promise<{ newRootItem: B2tFSItemIbGib_V1; newRootAddr: string; ingestedCommentCount: number }> {
+    let ingestedCommentCount = 0;
     const itemsByRelPath = new Map<string, { itemAddr: string; fsType: 'file' | 'folder'; item?: B2tFSItemIbGib_V1 }>();
 
     if (currentRootAddr) {
@@ -276,6 +299,63 @@ async function commitCmd_buildEvolvedRootItem({
         });
     }
 
+    // 1. Ingest co-located .ib.<filename>.md comment files for staged files
+    for (const [relPath, itemRec] of itemsByRelPath.entries()) {
+        if (itemRec.fsType !== 'file') { continue; }
+
+        const dir = path.dirname(relPath);
+        const base = path.basename(relPath);
+        const commentDir = dir === '.' ? worktreeDir : path.join(worktreeDir, dir);
+        const commentFullPath = path.join(commentDir, `.ib.${base}.md`);
+
+        let commentText = '';
+        try {
+            commentText = await fs.readFile(commentFullPath, 'utf8');
+        } catch {
+            // No comment file for this file
+            continue;
+        }
+
+        if (commentText.trim().length > 0) {
+            const commentRes = await createCommentIbGib({
+                text: commentText.trim(),
+                saveInSpace: true,
+                space,
+            });
+            const commentIbGib = commentRes.newIbGib as CommentIbGib_V1;
+            const commentAddr = getIbGibAddr({ ibGib: commentIbGib });
+            await metaspace.registerNewIbGib({ ibGib: commentIbGib, space });
+            ingestedCommentCount++;
+
+            const currentItem = itemRec.item || (await getIbGibWithMetaspaceFallback({
+                addr: itemRec.itemAddr,
+                space,
+                metaspace,
+            }) as B2tFSItemIbGib_V1);
+
+            if (currentItem) {
+                const existingComments = currentItem.rel8ns?.comment || [];
+                const evolvedItemRes = await evolveB2tFSItemIbGib({
+                    existingItem: currentItem,
+                    rel8nsToUpdate: {
+                        comment: [...existingComments, commentAddr],
+                    },
+                });
+                await persistTransformResult({ resTransform: evolvedItemRes, space });
+                await metaspace.registerNewIbGib({ ibGib: evolvedItemRes.newIbGib, space });
+
+                itemRec.itemAddr = getIbGibAddr({ ibGib: evolvedItemRes.newIbGib });
+                itemRec.item = evolvedItemRes.newIbGib as B2tFSItemIbGib_V1;
+            }
+
+            try {
+                await fs.unlink(commentFullPath);
+            } catch {
+                // Delete failed / ignore
+            }
+        }
+    }
+
     // Ensure parent folder entries exist for all items
     const allRelPaths = Array.from(itemsByRelPath.keys());
     for (const relPath of allRelPaths) {
@@ -331,6 +411,46 @@ async function commitCmd_buildEvolvedRootItem({
             }
         }
 
+        // Check for folder-level .ib.<topic>.md files in this folder
+        const folderDiskPath = folderRelPath ? path.join(worktreeDir, folderRelPath) : worktreeDir;
+        const folderCommentAddrs: string[] = [];
+
+        try {
+            const dirents = await fs.readdir(folderDiskPath, { withFileTypes: true });
+            for (const dirent of dirents) {
+                if (dirent.isFile() && isCommentMetadataFilename(dirent.name)) {
+                    const topicName = extractCommentTopicName(dirent.name);
+                    const isCoLocatedFileComment = itemsByRelPath.has(folderRelPath ? `${folderRelPath}/${topicName}` : topicName);
+
+                    if (!isCoLocatedFileComment) {
+                        const fullCommentPath = path.join(folderDiskPath, dirent.name);
+                        const commentContent = await fs.readFile(fullCommentPath, 'utf8');
+
+                        if (commentContent.trim().length > 0) {
+                            const commentRes = await createCommentIbGib({
+                                text: commentContent.trim(),
+                                saveInSpace: true,
+                                space,
+                            });
+                            const commentIbGib = commentRes.newIbGib as CommentIbGib_V1;
+                            const cAddr = getIbGibAddr({ ibGib: commentIbGib });
+                            await metaspace.registerNewIbGib({ ibGib: commentIbGib, space });
+                            folderCommentAddrs.push(cAddr);
+                            ingestedCommentCount++;
+                        }
+
+                        try {
+                            await fs.unlink(fullCommentPath);
+                        } catch {
+                            // ignore delete error
+                        }
+                    }
+                }
+            }
+        } catch {
+            // Folder may not exist on disk
+        }
+
         const folderName = folderRelPath ? path.basename(folderRelPath) : repoName;
         const nameHash = crypto.createHash('sha256').update(folderName).digest('hex');
 
@@ -341,13 +461,17 @@ async function commitCmd_buildEvolvedRootItem({
         if (existingFolderRec && existingFolderRec.item) {
             const oldChildAddrs = existingFolderRec.item.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
             const toRemoveChildAddrs = oldChildAddrs.filter(a => !childAddrs.includes(a));
+            const existingComments = existingFolderRec.item.rel8ns?.comment || [];
 
             folderRes = await evolveB2tFSItemIbGib({
                 existingItem: existingFolderRec.item,
                 dataToUpdate: {
                     nameHash,
                 },
-                rel8nsToUpdate: childAddrs.length > 0 ? { [B2TFS_CHILD_ITEM_REL8N_NAME]: childAddrs } : undefined,
+                rel8nsToUpdate: {
+                    ...(childAddrs.length > 0 ? { [B2TFS_CHILD_ITEM_REL8N_NAME]: childAddrs } : {}),
+                    ...(folderCommentAddrs.length > 0 ? { comment: [...existingComments, ...folderCommentAddrs] } : {}),
+                },
                 rel8nsToRemove: toRemoveChildAddrs.length > 0 ? { [B2TFS_CHILD_ITEM_REL8N_NAME]: toRemoveChildAddrs } : undefined,
             });
         } else {
@@ -357,7 +481,10 @@ async function commitCmd_buildEvolvedRootItem({
                 data: {
                     nameHash,
                 },
-                rel8ns: childAddrs.length > 0 ? { [B2TFS_CHILD_ITEM_REL8N_NAME]: childAddrs } : undefined,
+                rel8ns: {
+                    ...(childAddrs.length > 0 ? { [B2TFS_CHILD_ITEM_REL8N_NAME]: childAddrs } : {}),
+                    ...(folderCommentAddrs.length > 0 ? { comment: folderCommentAddrs } : {}),
+                },
             });
         }
 
@@ -374,7 +501,7 @@ async function commitCmd_buildEvolvedRootItem({
         }
     }
 
-    return { newRootItem: rootFolderItem!, newRootAddr: rootFolderAddr };
+    return { newRootItem: rootFolderItem!, newRootAddr: rootFolderAddr, ingestedCommentCount };
 }
 
 function commitCmd_getParentRelPath(relPath: string): string {

package/src/cli/commands/commit-log-cmd.respec.mts

@@ -1,6 +1,6 @@
 /**
  * @module commit-log-cmd.respec
- * 
+ *
  * Unit tests for `vcs commit` and `vcs log` command handlers.
  */
 
@@ -8,9 +8,11 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 
 import {
-    respecfully, ifWe, iReckon
+    respecfully, ifWe, ifWeMight, iReckon
 } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
 
+import { getDependencyGraph } from '@ibgib/core-gib/dist/common/other/graph-helper.mjs';
+import { getFromSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
 import { executeInitCmd } from './init-cmd.mjs';
 import { executeAddCmd } from './add-cmd.mjs';
 import { executeStatusCmd } from './status-cmd.mjs';
@@ -18,8 +20,12 @@ import { executeCommitCmd } from './commit-cmd.mjs';
 import { executeLogCmd } from './log-cmd.mjs';
 import { executeBranchCmd } from './branch-cmd.mjs';
 import { executeCheckoutCmd } from './checkout-cmd.mjs';
+import { executeMergeCmd } from './merge-cmd.mjs';
+import { executeGenerateCommentCmd } from './generate-comment-cmd.mjs';
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
 import { getB2tFSIndexIbGib } from '../../engine/index/index-helper.mjs';
+import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
+import { getIbGibWithMetaspaceFallback } from '../../engine/item/item-helper.mjs';
 
 const lc = `[apps/vcs-gib/src/cli/commands/commit-log-cmd.respec.node.mts]`;
 
@@ -267,8 +273,215 @@ await respecfully(lc, `vcs commit and vcs log Command Handlers`, async () => {
             });
 
             iReckon(lc, logRes.branchName).willEqual('feature-log');
-            iReckon(lc, logRes.commits.length).willEqual(1);
+            iReckon(lc, logRes.commits.length).willEqual(2);
             iReckon(lc, logRes.commits[0].message).willEqual('Feature branch commit');
+            iReckon(lc, logRes.commits[1].message).willEqual('Main branch commit');
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+
+    await ifWe(lc, `generates companion comment files, displays in status, ingests on commit, and projects in file log`, async () => {
+        const testDir = path.join(process.cwd(), '.test_commit_log_companion');
+        const vcsFolderName = '.vcsgib_test_commit_companion';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            const filePath = path.join(testDir, 'app.ts');
+            await fs.writeFile(filePath, 'console.log("hello world");', 'utf8');
+
+            // 1. Test generate-comment
+            const genRes = await executeGenerateCommentCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                paths: ['app.ts'],
+                quiet: true,
+            });
+
+            iReckon(lc, genRes.createdFiles.length).willEqual(1);
+            iReckon(lc, genRes.createdFiles[0]).includes('.ib.app.ts.md');
+
+            const companionPath = path.join(testDir, '.ib.app.ts.md');
+            let companionExists = false;
+            try {
+                await fs.access(companionPath);
+                companionExists = true;
+            } catch { }
+            iReckon(lc, companionExists).isGonnaBeTrue();
+
+            // Write custom notes into companion file
+            await fs.writeFile(companionPath, 'feat: initial implementation of app.ts\n* added console log', 'utf8');
+
+            // Write folder-level notes
+            const folderCompanionPath = path.join(testDir, '.ib.architecture.md');
+            await fs.writeFile(folderCompanionPath, 'Arch overview: client-side entrypoint', 'utf8');
+
+            // Stage app.ts
+            await executeAddCmd({
+                paths: ['app.ts'],
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // 2. Test status with comments
+            const statusRes = await executeStatusCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                comments: true,
+                quiet: true,
+            });
+
+            iReckon(lc, statusRes.pendingComments.length).willEqual(2);
+            const fileComment = statusRes.pendingComments.find(c => c.targetType === 'file');
+            iReckon(lc, Boolean(fileComment)).isGonnaBeTrue();
+            iReckon(lc, fileComment?.content).includes('initial implementation of app.ts');
+
+            // 3. Commit staged files and notes
+            const commitRes = await executeCommitCmd({
+                message: 'Initial root commit',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, commitRes.committedPaths).includes('app.ts');
+
+            // Verify companion files were consumed and removed
+            let companionStillExists = false;
+            try {
+                await fs.access(companionPath);
+                companionStillExists = true;
+            } catch { }
+            iReckon(lc, companionStillExists).isGonnaBeFalse();
+
+            let folderCompanionStillExists = false;
+            try {
+                await fs.access(folderCompanionPath);
+                folderCompanionStillExists = true;
+            } catch { }
+            iReckon(lc, folderCompanionStillExists).isGonnaBeFalse();
+
+            // 4. Test file-specific log (vcs log app.ts)
+            const fileLogRes = await executeLogCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                filePath: 'app.ts',
+                quiet: true,
+            });
+
+            iReckon(lc, fileLogRes.commits.length >= 1).isGonnaBeTrue();
+            iReckon(lc, fileLogRes.commits[0].message).includes('initial implementation of app.ts');
+
+            // 5. Test root log with allComments
+            const rootLogRes = await executeLogCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                allComments: true,
+                quiet: true,
+            });
+
+            iReckon(lc, rootLogRes.commits.length).willEqual(1);
+            iReckon(lc, rootLogRes.commits[0].message).willEqual('Initial root commit');
+            iReckon(lc, rootLogRes.commits[0].committedPaths).includes('app.ts');
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+
+    await ifWe(lc, `preserves and unions file comments across 3-way branch merges`, async () => {
+        const testDir = path.join(process.cwd(), '.test_commit_log_merge_comments');
+        const vcsFolderName = '.vcsgib_test_commit_merge_comments';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Base commit on main
+            const appFile = path.join(testDir, 'app.ts');
+            await fs.writeFile(appFile, 'const a = 1;\nconst b = 2;\n', 'utf8');
+            await executeAddCmd({ paths: ['app.ts'], targetDir: testDir, vcsFolderName, quiet: true });
+            await executeCommitCmd({ message: 'Base commit on main', targetDir: testDir, vcsFolderName, quiet: true });
+
+            // Create feature branch
+            await executeBranchCmd({ branchName: 'feature-comments', targetDir: testDir, vcsFolderName, quiet: true });
+            const checkoutRes = await executeCheckoutCmd({ branchName: 'feature-comments', targetDir: testDir, vcsFolderName, quiet: true });
+
+            // On feature branch: modify app.ts and attach companion note
+            const featureAppFile = path.join(checkoutRes.worktreePath, 'app.ts');
+            await fs.writeFile(featureAppFile, 'const a = 1;\nconst b = 200;\n', 'utf8');
+            const featureNoteFile = path.join(checkoutRes.worktreePath, '.ib.app.ts.md');
+            await fs.writeFile(featureNoteFile, 'feat(feature-comments): updated b to 200', 'utf8');
+
+            await executeAddCmd({ paths: ['app.ts'], targetDir: checkoutRes.worktreePath, vcsFolderName, quiet: true });
+            await executeCommitCmd({ message: 'Feature branch commit', targetDir: checkoutRes.worktreePath, vcsFolderName, quiet: true });
+
+            // Switch back to main branch
+            await executeCheckoutCmd({ branchName: 'main', targetDir: testDir, vcsFolderName, quiet: true });
+
+            // On main branch: modify app.ts and attach companion note
+            await fs.writeFile(appFile, 'const a = 100;\nconst b = 2;\n', 'utf8');
+            const mainNoteFile = path.join(testDir, '.ib.app.ts.md');
+            await fs.writeFile(mainNoteFile, 'feat(main): updated a to 100', 'utf8');
+
+            await executeAddCmd({ paths: ['app.ts'], targetDir: testDir, vcsFolderName, quiet: true });
+            await executeCommitCmd({ message: 'Main branch update', targetDir: testDir, vcsFolderName, quiet: true });
+
+            // Merge feature-comments into main
+            await executeMergeCmd({ incomingBranchName: 'feature-comments', targetDir: testDir, vcsFolderName, quiet: true });
+
+            // Check file log on main: both comments should be present!
+            const mergedFileLog = await executeLogCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                filePath: 'app.ts',
+                quiet: true,
+            });
+
+            const allMessages = mergedFileLog.commits.map(c => c.message).join(' -- ');
+            iReckon(lc, allMessages).includes('updated b to 200');
+            iReckon(lc, allMessages).includes('updated a to 100');
+
+            // Verify getDependencyGraph works 100% within main branch space alone (no metaspace fallback)
+            const { metaspace, vcsPath } = await bootstrapVcsMetaspace({
+                repoPath: testDir,
+                vcsFolderName,
+            });
+            const { space: mainSpace } = await getOrCreateBranchSpace({
+                metaspace,
+                vcsPath,
+                branchName: 'main',
+            });
+            const indexIbGib = await getB2tFSIndexIbGib({ space: metaspace.zeroSpace, vcsPath });
+            const mainBranchAddr = indexIbGib?.rel8ns?.branch?.at(-1) || indexIbGib?.rel8ns?.branch_tjp?.at(-1);
+            const mainBranch = await getIbGibWithMetaspaceFallback({ addr: mainBranchAddr!, space: mainSpace, metaspace });
+            const mainRootAddr = mainBranch?.rel8ns?.b2tfs_item?.at(-1);
+            const mainRoot = await getIbGibWithMetaspaceFallback({ addr: mainRootAddr!, space: mainSpace, metaspace });
+            let appItem: any;
+            for (const childAddr of mainRoot?.rel8ns?.b2tfs_child || []) {
+                const child = await getIbGibWithMetaspaceFallback({ addr: childAddr, space: mainSpace, metaspace });
+                if (child?.data?.name === 'app.ts') {
+                    appItem = child;
+                    break;
+                }
+            }
+            iReckon(lc, appItem).isGonnaBeTruthy();
+
+            // Ensure getDependencyGraph runs strictly within mainSpace with NO metaspace fallback
+            const depGraph = await getDependencyGraph({
+                ibGib: appItem,
+                space: mainSpace,
+            });
+
+            const graphValues = Object.values(depGraph);
+            const foundCommentB = graphValues.some(x => (x.data as any)?.text === 'feat(feature-comments): updated b to 200');
+            iReckon(lc, foundCommentB).isGonnaBeTruthy();
         } finally {
             await fs.rm(testDir, { recursive: true, force: true });
         }