@ibgib/vcs-gib 0.0.23 → 0.0.29

package/src/cli/commands/generate-comment-cmd.mts

@@ -0,0 +1,171 @@
+/**
+ * @module generate-comment-cmd
+ * 
+ * Command handler for `vcs generate-comment` (synonyms: `gen-comment`, `gen-msg`, `gcomm`, `gmsg`).
+ * Scans repository status or target paths and creates `.ib.<file>.md` or `.ib.<topic>.md` companion metadata files.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+import { getRepoStatus } from '../../engine/status/status-helper.mjs';
+
+const lcFile = `[generate-comment-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface GenerateCommentCmdOpts {
+    targetDir?: string;
+    vcsFolderName?: string;
+    paths?: string[];
+    folderTopic?: string;
+    quiet?: boolean;
+}
+
+export interface GenerateCommentCmdResult {
+    createdFiles: string[];
+    skippedFiles: string[];
+}
+
+export async function executeGenerateCommentCmd({
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    paths = [],
+    folderTopic = 'notes',
+    quiet = false,
+}: GenerateCommentCmdOpts = {}): Promise<GenerateCommentCmdResult> {
+    const lc = `${lcFile}[${executeGenerateCommentCmd.name}]`;
+
+    try {
+        if (logalot) {
+            console.log(`${lc} starting executeGenerateCommentCmd (I: 8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e)`);
+        }
+
+        const absTargetDir = path.resolve(targetDir);
+
+        const { metaspace, localSpace, vcsPath, repoRoot } = await bootstrapVcsMetaspace({
+            repoPath: absTargetDir,
+            vcsFolderName,
+        });
+
+        // Verify repo exists
+        try {
+            await fs.access(vcsPath);
+        } catch {
+            throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f)`);
+        }
+
+        const statusRes = await getRepoStatus({
+            metaspace,
+            localSpace,
+            vcsPath,
+            repoRoot,
+            vcsFolderName,
+        });
+
+        const activeWorktreeDir = statusRes.activeWorktreeDir;
+        const targetRelPaths: string[] = [];
+
+        if (paths.length > 0) {
+            for (const p of paths) {
+                const absP = path.resolve(activeWorktreeDir, p);
+                const relP = path.relative(activeWorktreeDir, absP).replace(/\\/g, '/');
+                if (relP && !targetRelPaths.includes(relP)) {
+                    targetRelPaths.push(relP);
+                }
+            }
+        } else {
+            // Auto-detect from staged and modified items
+            for (const s of statusRes.staged) {
+                if (!targetRelPaths.includes(s.path)) {
+                    targetRelPaths.push(s.path);
+                }
+            }
+            for (const m of statusRes.modified) {
+                if (!targetRelPaths.includes(m.path)) {
+                    targetRelPaths.push(m.path);
+                }
+            }
+            for (const u of statusRes.untracked) {
+                if (!targetRelPaths.includes(u.path)) {
+                    targetRelPaths.push(u.path);
+                }
+            }
+        }
+
+        const createdFiles: string[] = [];
+        const skippedFiles: string[] = [];
+
+        for (const relP of targetRelPaths) {
+            const absP = path.join(activeWorktreeDir, relP);
+
+            let isDirectory = false;
+            try {
+                const stat = await fs.stat(absP);
+                isDirectory = stat.isDirectory();
+            } catch {
+                // If path doesn't exist yet on disk, guess based on extension
+                isDirectory = !path.extname(relP);
+            }
+
+            let commentFileName: string;
+            let commentDirPath: string;
+
+            if (isDirectory) {
+                commentDirPath = absP;
+                commentFileName = `.ib.${folderTopic}.md`;
+            } else {
+                commentDirPath = path.dirname(absP);
+                const baseName = path.basename(absP);
+                commentFileName = `.ib.${baseName}.md`;
+            }
+
+            const commentFullPath = path.join(commentDirPath, commentFileName);
+            const commentRelPath = path.relative(activeWorktreeDir, commentFullPath).replace(/\\/g, '/');
+
+            try {
+                await fs.access(commentFullPath);
+                // Already exists
+                skippedFiles.push(commentRelPath);
+            } catch {
+                // Does not exist -> create boilerplate template
+                const headerTarget = relP ? `\`${relP}\`` : 'root';
+                const boilerplate = `# ${headerTarget}\n\n(Enter contemporaneous notes/comments here)\n`;
+                await fs.mkdir(commentDirPath, { recursive: true });
+                await fs.writeFile(commentFullPath, boilerplate, 'utf8');
+                createdFiles.push(commentRelPath);
+            }
+        }
+
+        if (!quiet) {
+            if (createdFiles.length > 0) {
+                console.log(`Generated ${createdFiles.length} comment file(s):`);
+                for (const f of createdFiles) {
+                    console.log(`  created: ${f}`);
+                }
+            }
+            if (skippedFiles.length > 0) {
+                for (const f of skippedFiles) {
+                    console.log(`  already exists: ${f}`);
+                }
+            }
+            if (createdFiles.length === 0 && skippedFiles.length === 0) {
+                console.log(`No modified or staged files found to generate comments for.`);
+            }
+        }
+
+        return {
+            createdFiles,
+            skippedFiles,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b)`);
+        }
+    }
+}

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

@@ -3,7 +3,7 @@
  * 
  * Command handler for `vcs log`.
  * Reads active branch timeline from B2tFSIndexIbGib_V1 in localSpace,
- * walks branch timeline history backward, and displays formatted commit history.
+ * walks branch or item timeline history backward, and displays formatted commit and comment history.
  */
 
 import path from 'node:path';
@@ -11,12 +11,13 @@ import fs from 'node:fs/promises';
 
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-import { getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-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 { resolveContextualBranchName } from '../../engine/branch/branch-helper.mjs';
 import { getIbGibWithMetaspaceFallback } from '../../engine/item/item-helper.mjs';
+import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } from '../../engine/item/item-types.mjs';
 import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
 import { getB2tFSIndexIbGib, extractBranchNameFromAddr } from '../../engine/index/index-helper.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
@@ -25,29 +26,36 @@ const lcFile = `[log-cmd]`;
 const logalot = GLOBAL_LOG_A_LOT;
 
 export interface VcsLogItem {
-    branchAddr: string;
+    branchAddr?: string;
     commitAddr: string;
     commentAddr?: string;
     message: string;
     timestamp: string;
     author: string;
     rootItemAddr?: string;
+    committedPaths?: string[];
+    itemComments?: Array<{ path: string; name?: string; message: string }>;
 }
 
 export interface LogCmdOpts {
     targetDir?: string;
     vcsFolderName?: string;
+    filePath?: string;
+    allComments?: boolean;
     quiet?: boolean;
 }
 
 export interface LogCmdResult {
     branchName: string;
+    targetPath?: string;
     commits: VcsLogItem[];
 }
 
 export async function executeLogCmd({
     targetDir = process.cwd(),
     vcsFolderName = '.vcsgib',
+    filePath,
+    allComments = false,
     quiet = false,
 }: LogCmdOpts = {}): Promise<LogCmdResult> {
     const lc = `${lcFile}[${executeLogCmd.name}]`;
@@ -77,7 +85,11 @@ export async function executeLogCmd({
             throw new Error(`Repository index B2tFSIndexIbGib_V1 not found in localSpace (E: 3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a)`);
         }
 
-        const branchName = indexIbGib.data?.activeBranch || 'main';
+        const branchName = resolveContextualBranchName({
+            targetDir: absTargetDir,
+            repoRoot,
+            indexIbGib,
+        });
 
         // Target active branch space b2s_<activeBranch>
         const { space: activeSpace } = await getOrCreateBranchSpace({
@@ -87,45 +99,122 @@ export async function executeLogCmd({
         });
 
         // 2. Fetch active branch node address matching active branchName
-        const branchAddrs = [
-            ...(indexIbGib.rel8ns?.branch || []),
-            ...(indexIbGib.rel8ns?.branch_tjp || []),
-        ];
+        const branchAddrs = indexIbGib.rel8ns?.branch || indexIbGib.rel8ns?.branch_tjp || [];
 
         let currBranchAddr: string | undefined;
-
-        // Match branchName against branchAddrs by space-qualified address or raw atom ib string
-        for (const addr of branchAddrs) {
-            const parsedName = extractBranchNameFromAddr(addr);
-            if (parsedName === branchName) {
-                currBranchAddr = addr;
-                break;
-            }
-        }
-
-        // Fallback: fetch branch nodes via getIbGibWithMetaspaceFallback to match b.data?.name === branchName
-        if (!currBranchAddr) {
-            for (const addr of branchAddrs) {
+        if (branchAddrs.length > 0) {
+            let branchIbGibs: B2tFSBranchIbGib_V1[] = [];
+            for (const bAddr of branchAddrs) {
                 const bIbGib = await getIbGibWithMetaspaceFallback({
-                    addr,
+                    addr: bAddr,
                     space: activeSpace,
                     metaspace,
-                }) as B2tFSBranchIbGib_V1;
-                if (bIbGib?.data?.name === branchName) {
-                    currBranchAddr = addr;
-                    break;
+                });
+                if (bIbGib) {
+                    branchIbGibs.push(bIbGib as B2tFSBranchIbGib_V1);
                 }
             }
+
+            const matchingBranches = branchIbGibs.filter(b => b?.data?.name === branchName);
+            const activeBranchIbGib = matchingBranches.sort((a, b) => (b.data?.n || 0) - (a.data?.n || 0))[0]
+                || branchIbGibs.at(-1);
+
+            if (activeBranchIbGib) {
+                currBranchAddr = getIbGibAddr({ ibGib: activeBranchIbGib });
+            }
         }
 
-        // Ultimate fallback if no match found
-        if (!currBranchAddr) {
-            currBranchAddr = branchAddrs.at(0);
+        const commits: VcsLogItem[] = [];
+
+        // #region File-Specific Log Mode (vcs log <filePath>)
+        if (filePath) {
+            const normalizedRelPath = path.relative(repoRoot, path.resolve(absTargetDir, filePath)).replace(/\\/g, '/');
+
+            // Find current root item
+            const branchIbGib = currBranchAddr
+                ? await getIbGibWithMetaspaceFallback({ addr: currBranchAddr, space: activeSpace, metaspace }) as B2tFSBranchIbGib_V1
+                : undefined;
+            const rootItemAddr = branchIbGib?.rel8ns?.b2tFS_item?.at(-1) || branchIbGib?.rel8ns?.b2tfs_item?.at(-1);
+
+            if (!rootItemAddr) {
+                throw new Error(`No root item found on branch ${branchName} (E: 4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b)`);
+            }
+
+            const targetItem = await logCmd_findItemByPath({
+                rootItemAddr,
+                targetRelPath: normalizedRelPath,
+                space: activeSpace,
+                metaspace,
+            });
+
+            if (!targetItem) {
+                throw new Error(`Path '${normalizedRelPath}' not found in active branch snapshot (E: 5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c)`);
+            }
+
+            // Walk target item timeline history backward
+            const visitedItemAddrs = new Set<string>();
+            let currItem: B2tFSItemIbGib_V1 | undefined = targetItem;
+
+            while (currItem) {
+                const itemAddr = getIbGibAddr({ ibGib: currItem });
+                if (visitedItemAddrs.has(itemAddr)) { break; }
+                visitedItemAddrs.add(itemAddr);
+
+                const commentAddrs = currItem.rel8ns?.comment || [];
+                for (const cAddr of commentAddrs) {
+                    const commentIbGib = await getIbGibWithMetaspaceFallback({
+                        addr: cAddr,
+                        space: activeSpace,
+                        metaspace,
+                    }) as CommentIbGib_V1;
+
+                    if (commentIbGib) {
+                        commits.push({
+                            commitAddr: itemAddr,
+                            commentAddr: cAddr,
+                            message: commentIbGib.data?.text || '',
+                            timestamp: commentIbGib.data?.textTimestamp || commentIbGib.data?.timestamp || '',
+                            author: 'vcs-user',
+                        });
+                    }
+                }
+
+                const pastAddr = currItem.rel8ns?.past?.at(0) || currItem.rel8ns?.ancestor?.at(0);
+                if (pastAddr) {
+                    currItem = await getIbGibWithMetaspaceFallback({
+                        addr: pastAddr,
+                        space: activeSpace,
+                        metaspace,
+                    }) as B2tFSItemIbGib_V1;
+                } else {
+                    currItem = undefined;
+                }
+            }
+
+            if (!quiet) {
+                console.log(`File: ${normalizedRelPath} (branch: ${branchName}) (I: 6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d)`);
+                if (commits.length === 0) {
+                    console.log('No comments found for this file.');
+                } else {
+                    for (const commit of commits) {
+                        console.log(`\nitem ${commit.commitAddr}`);
+                        if (commit.timestamp) { console.log(`Date:   ${commit.timestamp}`); }
+                        console.log(`\n    ${commit.message}\n`);
+                    }
+                }
+            }
+
+            return {
+                branchName,
+                targetPath: normalizedRelPath,
+                commits,
+            };
         }
+        // #endregion File-Specific Log Mode
+
+        // #region Standard Branch Log Mode
         const visitedAddrs = new Set<string>();
-        const commits: VcsLogItem[] = [];
 
-        // 3. Walk timeline history backward
         while (currBranchAddr && !visitedAddrs.has(currBranchAddr)) {
             visitedAddrs.add(currBranchAddr);
 
@@ -139,28 +228,68 @@ export async function executeLogCmd({
                 break;
             }
 
-            const commentAddr = branchIbGib.rel8ns?.comment?.at(0);
-            const rootItemAddr = branchIbGib.rel8ns?.b2tfs_item?.at(0);
+            const rootItemAddr = branchIbGib.rel8ns?.b2tFS_item?.at(-1) || branchIbGib.rel8ns?.b2tfs_item?.at(-1);
+
+            let rootItem: B2tFSItemIbGib_V1 | undefined;
+            if (rootItemAddr) {
+                rootItem = await getIbGibWithMetaspaceFallback({
+                    addr: rootItemAddr,
+                    space: activeSpace,
+                    metaspace,
+                }) as B2tFSItemIbGib_V1;
+            }
+
+            let commentAddrs = [
+                ...(branchIbGib.rel8ns?.comment || []),
+                ...(rootItem?.rel8ns?.comment || []),
+            ];
+            // Deduplicate
+            commentAddrs = Array.from(new Set(commentAddrs));
 
-            if (commentAddr) {
+            let message = '';
+            let timestamp = branchIbGib.data?.committedAt || '';
+            // If branch has a direct comment, use that first, otherwise use the last added comment on root item
+            let primaryCommentAddr = branchIbGib.rel8ns?.comment?.at(-1) || rootItem?.rel8ns?.comment?.at(-1) || commentAddrs.at(0);
+
+            if (primaryCommentAddr) {
                 const commentIbGib = await getIbGibWithMetaspaceFallback({
-                    addr: commentAddr,
+                    addr: primaryCommentAddr,
                     space: activeSpace,
                     metaspace,
                 }) as CommentIbGib_V1;
 
-                const message = commentIbGib?.data?.text || '';
-                const timestamp = commentIbGib?.data?.textTimestamp || commentIbGib?.data?.timestamp || branchIbGib.data?.committedAt || '';
-                const author = 'vcs-user';
+                if (commentIbGib?.data?.text) {
+                    message = commentIbGib.data.text;
+                }
+                if (commentIbGib?.data?.textTimestamp || commentIbGib?.data?.timestamp) {
+                    timestamp = commentIbGib.data.textTimestamp || commentIbGib.data.timestamp || timestamp;
+                }
+            }
+
+            const committedPaths = branchIbGib.data?.committedPaths || [];
+            const itemComments: Array<{ path: string; name?: string; message: string }> = [];
 
+            if (allComments && rootItem) {
+                await logCmd_collectAllItemComments({
+                    item: rootItem,
+                    space: activeSpace,
+                    metaspace,
+                    currentRelPath: '',
+                    outComments: itemComments,
+                });
+            }
+
+            if (message || primaryCommentAddr || (committedPaths && committedPaths.length > 0)) {
                 commits.push({
                     branchAddr: currBranchAddr,
-                    commitAddr: commentAddr,
-                    commentAddr,
-                    message,
+                    commitAddr: currBranchAddr,
+                    commentAddr: primaryCommentAddr,
+                    message: message || '(no commit message)',
                     timestamp,
-                    author,
+                    author: 'vcs-user',
                     rootItemAddr,
+                    committedPaths,
+                    itemComments: itemComments.length > 0 ? itemComments : undefined,
                 });
             }
 
@@ -178,6 +307,16 @@ export async function executeLogCmd({
                     console.log(`Author: ${commit.author}`);
                     console.log(`Date:   ${commit.timestamp}`);
                     console.log(`\n    ${commit.message}\n`);
+                    if (commit.committedPaths && commit.committedPaths.length > 0) {
+                        console.log(`Changed: ${commit.committedPaths.join(', ')}`);
+                    }
+                    if (commit.itemComments && commit.itemComments.length > 0) {
+                        console.log('Item Comments:');
+                        for (const ic of commit.itemComments) {
+                            const label = ic.name ? `${ic.path} (${ic.name})` : ic.path;
+                            console.log(`  * [${label}]: ${ic.message}`);
+                        }
+                    }
                 }
             }
         }
@@ -186,6 +325,7 @@ export async function executeLogCmd({
             branchName,
             commits,
         };
+        // #endregion Standard Branch Log Mode
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)} (E: 5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c)`);
         throw error;
@@ -195,3 +335,115 @@ export async function executeLogCmd({
         }
     }
 }
+
+async function logCmd_findItemByPath({
+    rootItemAddr,
+    targetRelPath,
+    space,
+    metaspace,
+}: {
+    rootItemAddr: string;
+    targetRelPath: string;
+    space: any;
+    metaspace?: any;
+}): Promise<B2tFSItemIbGib_V1 | undefined> {
+    const rootItem = await getIbGibWithMetaspaceFallback({
+        addr: rootItemAddr,
+        space,
+        metaspace,
+    }) as B2tFSItemIbGib_V1;
+
+    if (!rootItem) { return undefined; }
+    if (!targetRelPath || targetRelPath === '.' || targetRelPath === '') {
+        return rootItem;
+    }
+
+    const segments = targetRelPath.split('/');
+    let currentItem: B2tFSItemIbGib_V1 = rootItem;
+
+    for (const segment of segments) {
+        if (currentItem.data?.fsType !== 'folder') {
+            return undefined;
+        }
+
+        const childAddrs = currentItem.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
+        let nextItem: B2tFSItemIbGib_V1 | undefined;
+
+        for (const cAddr of childAddrs) {
+            const child = await getIbGibWithMetaspaceFallback({
+                addr: cAddr,
+                space,
+                metaspace,
+            }) as B2tFSItemIbGib_V1;
+
+            if (child && child.data?.name === segment) {
+                nextItem = child;
+                break;
+            }
+        }
+
+        if (!nextItem) {
+            return undefined;
+        }
+        currentItem = nextItem;
+    }
+
+    return currentItem;
+}
+
+async function logCmd_collectAllItemComments({
+    item,
+    space,
+    metaspace,
+    currentRelPath,
+    outComments,
+}: {
+    item: B2tFSItemIbGib_V1;
+    space: any;
+    metaspace?: any;
+    currentRelPath: string;
+    outComments: Array<{ path: string; name?: string; message: string }>;
+}): Promise<void> {
+    if (!item || !item.data) { return; }
+
+    const itemComments = item.rel8ns?.comment || [];
+    for (const cAddr of itemComments) {
+        const commentIbGib = await getIbGibWithMetaspaceFallback({
+            addr: cAddr,
+            space,
+            metaspace,
+        }) as CommentIbGib_V1;
+
+        if (commentIbGib && commentIbGib.data?.text) {
+            outComments.push({
+                path: currentRelPath || '(root)',
+                name: (commentIbGib.data as any)?.name,
+                message: commentIbGib.data.text,
+            });
+        }
+    }
+
+    if (item.data.fsType === 'folder') {
+        const childAddrs = item.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
+        for (const childAddr of childAddrs) {
+            const childItem = await getIbGibWithMetaspaceFallback({
+                addr: childAddr,
+                space,
+                metaspace,
+            }) as B2tFSItemIbGib_V1;
+
+            if (childItem && childItem.data) {
+                const childRel = currentRelPath
+                    ? `${currentRelPath}/${childItem.data.name}`
+                    : childItem.data.name;
+                await logCmd_collectAllItemComments({
+                    item: childItem,
+                    space,
+                    metaspace,
+                    currentRelPath: childRel,
+                    outComments,
+                });
+            }
+        }
+    }
+}