@ibgib/vcs-gib 0.0.21 → 0.0.26

package/src/engine/status/status-helper.mts

@@ -0,0 +1,380 @@
+/**
+ * @module status-helper
+ *
+ * Pure status inspection helpers and pending `.ib.*.md` comment metadata detection.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { Dirent } from 'node:fs';
+import crypto from 'node:crypto';
+
+import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } from '../item/item-types.mjs';
+import { getIbGibWithMetaspaceFallback } from '../item/item-helper.mjs';
+import { B2tFSBranchIbGib_V1 } from '../branch/branch-types.mjs';
+import { isPathFiltered, parseFilterFileContent } from '../filter/glob-helper.mjs';
+import { getB2tFSIndexIbGib } from '../index/index-helper.mjs';
+import { B2tFSStagedItemRecord } from '../index/index-types.mjs';
+import { getOrCreateBranchSpace } from '../branch/branch-space-helper.mjs';
+
+export interface VcsStatusItem {
+    path: string;
+    fsType: 'file' | 'folder';
+    status: 'untracked' | 'modified' | 'deleted' | 'staged';
+}
+
+export interface PendingCommentInfo {
+    /** Relative path of the companion file, e.g. "src/.ib.index.mts.md" or ".ib.architecture.md" */
+    commentRelPath: string;
+    /** Full disk path of the companion file */
+    commentFullPath: string;
+    /** Target relative path this comment attaches to, e.g. "src/index.mts" or "src" (folder) or "" (root) */
+    targetRelPath: string;
+    /** 'file' if .ib.<filename>.md matches a file, or 'folder' */
+    targetType: 'file' | 'folder';
+    /** The topic name (the * in .ib.*.md) or filename */
+    topicName: string;
+    /** Raw text content of the markdown comment file */
+    content: string;
+}
+
+export interface RepoStatusResult {
+    branchName: string;
+    activeWorktreeDir: string;
+    staged: VcsStatusItem[];
+    modified: VcsStatusItem[];
+    deleted: VcsStatusItem[];
+    untracked: VcsStatusItem[];
+    pendingComments: PendingCommentInfo[];
+}
+
+/**
+ * Returns true if filename is a `.ib.*.md` comment metadata file.
+ */
+export function isCommentMetadataFilename(filename: string): boolean {
+    return filename.startsWith('.ib.') && filename.endsWith('.md') && filename.length > '.ib..md'.length;
+}
+
+/**
+ * Extracts the inner topic / filename from `.ib.<topic>.md`.
+ */
+export function extractCommentTopicName(filename: string): string {
+    if (!isCommentMetadataFilename(filename)) { return ''; }
+    return filename.slice(4, -3); // strips leading '.ib.' and trailing '.md'
+}
+
+/**
+ * Pure helper to walk the branch graph items.
+ */
+export async function walkBranchGraph({
+    item,
+    space,
+    metaspace,
+    currentRelPath,
+    outMap,
+}: {
+    item: B2tFSItemIbGib_V1;
+    space: any;
+    metaspace?: any;
+    currentRelPath: string;
+    outMap: Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder' }>;
+}): Promise<void> {
+    if (!item || !item.data) { return; }
+
+    const { fsType, fileHash } = item.data;
+    if (currentRelPath) {
+        outMap.set(currentRelPath, { relPath: currentRelPath, fileHash, fsType });
+    }
+
+    if (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 childRelPath = currentRelPath
+                    ? `${currentRelPath}/${childItem.data.name}`
+                    : childItem.data.name;
+                await walkBranchGraph({
+                    item: childItem,
+                    space,
+                    metaspace,
+                    currentRelPath: childRelPath,
+                    outMap,
+                });
+            }
+        }
+    }
+}
+
+/**
+ * Pure helper to scan physical workspace, separating source files from `.ib.*.md` comment files.
+ */
+export async function scanPhysicalWorkspace({
+    dirPath,
+    baseDir,
+    vcsFolderName,
+    filterPatterns,
+    outSourceMap,
+    outCommentFiles,
+}: {
+    dirPath: string;
+    baseDir: string;
+    vcsFolderName: string;
+    filterPatterns: string[];
+    outSourceMap: Map<string, { relPath: string; fullPath: string; isDirectory: boolean; fileHash?: string }>;
+    outCommentFiles: Array<{ relPath: string; fullPath: string; parentRelPath: string; filename: string }>;
+}): Promise<void> {
+    let entries: Dirent[] = [];
+    try {
+        entries = await fs.readdir(dirPath, { withFileTypes: true });
+    } catch {
+        return;
+    }
+
+    for (const entry of entries) {
+        const fullEntryPath = path.join(dirPath, entry.name);
+        const relPath = path.relative(baseDir, fullEntryPath).replace(/\\/g, '/');
+
+        // Ignore vcs storage folder, .git, and worktrees folder b
+        if (
+            relPath === vcsFolderName || relPath.startsWith(vcsFolderName + '/') ||
+            relPath === '.git' || relPath.startsWith('.git/') ||
+            relPath === 'b' || relPath.startsWith('b/')
+        ) {
+            continue;
+        }
+
+        if (isPathFiltered({ relativePath: relPath, isDirectory: entry.isDirectory(), filterPatterns })) {
+            continue;
+        }
+
+        if (entry.isDirectory()) {
+            outSourceMap.set(relPath, { relPath, fullPath: fullEntryPath, isDirectory: true });
+            await scanPhysicalWorkspace({
+                dirPath: fullEntryPath,
+                baseDir,
+                vcsFolderName,
+                filterPatterns,
+                outSourceMap,
+                outCommentFiles,
+            });
+        } else if (entry.isFile()) {
+            if (isCommentMetadataFilename(entry.name)) {
+                const parentRelPath = path.relative(baseDir, dirPath).replace(/\\/g, '/');
+                outCommentFiles.push({
+                    relPath,
+                    fullPath: fullEntryPath,
+                    parentRelPath: parentRelPath === '.' ? '' : parentRelPath,
+                    filename: entry.name,
+                });
+            } else {
+                let fileHash: string | undefined;
+                try {
+                    const fileData = await fs.readFile(fullEntryPath);
+                    fileHash = crypto.createHash('sha256').update(fileData).digest('hex');
+                } catch {
+                    // File unreadable
+                }
+                outSourceMap.set(relPath, { relPath, fullPath: fullEntryPath, isDirectory: false, fileHash });
+            }
+        }
+    }
+}
+
+/**
+ * Computes complete repository status, including staged, modified, deleted, untracked,
+ * and mapped pending `.ib.*.md` comment files.
+ */
+export async function getRepoStatus({
+    metaspace,
+    localSpace,
+    vcsPath,
+    repoRoot,
+    vcsFolderName = '.vcsgib',
+}: {
+    metaspace: any;
+    localSpace: any;
+    vcsPath: string;
+    repoRoot: string;
+    vcsFolderName?: string;
+}): Promise<RepoStatusResult> {
+    const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, vcsPath });
+    const branchName = indexIbGib?.data?.activeBranch || 'main';
+    const activeWorktreeDir = branchName === 'main' ? repoRoot : path.join(repoRoot, 'b', branchName);
+
+    const { space: activeBranchSpace } = await getOrCreateBranchSpace({
+        metaspace,
+        vcsPath,
+        branchName,
+    });
+
+    const stagedMap = new Map<string, B2tFSStagedItemRecord>();
+    const indexStagedPaths = indexIbGib?.data?.stagedPaths || {};
+    for (const [relPath, itemRec] of Object.entries(indexStagedPaths)) {
+        stagedMap.set(relPath, itemRec);
+    }
+
+    let rootItemAddr: string | undefined;
+    const branchAddrs = [
+        ...(indexIbGib?.rel8ns?.branch || []),
+        ...(indexIbGib?.rel8ns?.branch_tjp || []),
+    ];
+
+    if (branchAddrs.length > 0) {
+        let branchIbGibs: B2tFSBranchIbGib_V1[] = [];
+        for (const bAddr of branchAddrs) {
+            const bIbGib = await getIbGibWithMetaspaceFallback({
+                addr: bAddr,
+                space: activeBranchSpace,
+                metaspace,
+            });
+            if (bIbGib) {
+                branchIbGibs.push(bIbGib as B2tFSBranchIbGib_V1);
+            }
+        }
+
+        const activeBranchIbGib = branchIbGibs.find(
+            (b) => (b as B2tFSBranchIbGib_V1)?.data?.name === branchName,
+        ) as B2tFSBranchIbGib_V1 || (branchIbGibs.at(0) as B2tFSBranchIbGib_V1);
+
+        rootItemAddr = activeBranchIbGib?.rel8ns?.b2tFS_item?.at(0) || activeBranchIbGib?.rel8ns?.b2tfs_item?.at(0);
+    }
+
+    let filterPatterns: string[] = [];
+    const ignorePath = path.join(activeWorktreeDir, '.ibgibignore');
+    try {
+        const ignoreContent = await fs.readFile(ignorePath, 'utf8');
+        filterPatterns = parseFilterFileContent(ignoreContent);
+    } catch {
+        // Ignore file missing is fine
+    }
+
+    const branchItemsMap = new Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder' }>();
+    if (rootItemAddr) {
+        const rootItem = await getIbGibWithMetaspaceFallback({
+            addr: rootItemAddr,
+            space: activeBranchSpace,
+            metaspace,
+        }) as B2tFSItemIbGib_V1;
+
+        if (rootItem) {
+            await walkBranchGraph({
+                item: rootItem,
+                space: activeBranchSpace,
+                metaspace,
+                currentRelPath: '',
+                outMap: branchItemsMap,
+            });
+        }
+    }
+
+    const physicalItemsMap = new Map<string, { relPath: string; fullPath: string; isDirectory: boolean; fileHash?: string }>();
+    const rawCommentFiles: Array<{ relPath: string; fullPath: string; parentRelPath: string; filename: string }> = [];
+
+    await scanPhysicalWorkspace({
+        dirPath: activeWorktreeDir,
+        baseDir: activeWorktreeDir,
+        vcsFolderName,
+        filterPatterns,
+        outSourceMap: physicalItemsMap,
+        outCommentFiles: rawCommentFiles,
+    });
+
+    const staged: VcsStatusItem[] = [];
+    const modified: VcsStatusItem[] = [];
+    const deleted: VcsStatusItem[] = [];
+    const untracked: VcsStatusItem[] = [];
+
+    for (const [relPath, stagedRec] of stagedMap.entries()) {
+        staged.push({
+            path: relPath,
+            fsType: stagedRec.fsType || 'file',
+            status: 'staged',
+        });
+    }
+
+    for (const [relPath, physItem] of physicalItemsMap.entries()) {
+        if (stagedMap.has(relPath)) {
+            continue;
+        }
+
+        const branchItem = branchItemsMap.get(relPath);
+        if (!branchItem) {
+            untracked.push({
+                path: relPath,
+                fsType: physItem.isDirectory ? 'folder' : 'file',
+                status: 'untracked',
+            });
+        } else {
+            if (!physItem.isDirectory && physItem.fileHash && branchItem.fileHash && physItem.fileHash !== branchItem.fileHash) {
+                modified.push({
+                    path: relPath,
+                    fsType: 'file',
+                    status: 'modified',
+                });
+            }
+        }
+    }
+
+    for (const [relPath, branchItem] of branchItemsMap.entries()) {
+        if (!relPath || relPath === '.' || relPath === '') { continue; }
+        if (!physicalItemsMap.has(relPath) && !stagedMap.has(relPath)) {
+            deleted.push({
+                path: relPath,
+                fsType: branchItem.fsType,
+                status: 'deleted',
+            });
+        }
+    }
+
+    // Map raw comment files to targets (file or folder)
+    const pendingComments: PendingCommentInfo[] = [];
+    for (const raw of rawCommentFiles) {
+        const topicName = extractCommentTopicName(raw.filename);
+        const candidateFileRelPath = raw.parentRelPath ? `${raw.parentRelPath}/${topicName}` : topicName;
+
+        let targetType: 'file' | 'folder' = 'folder';
+        let targetRelPath = raw.parentRelPath;
+
+        if (physicalItemsMap.has(candidateFileRelPath) && !physicalItemsMap.get(candidateFileRelPath)?.isDirectory) {
+            targetType = 'file';
+            targetRelPath = candidateFileRelPath;
+        } else if (branchItemsMap.has(candidateFileRelPath) && branchItemsMap.get(candidateFileRelPath)?.fsType === 'file') {
+            targetType = 'file';
+            targetRelPath = candidateFileRelPath;
+        } else if (stagedMap.has(candidateFileRelPath)) {
+            targetType = 'file';
+            targetRelPath = candidateFileRelPath;
+        }
+
+        let content = '';
+        try {
+            content = await fs.readFile(raw.fullPath, 'utf8');
+        } catch {
+            // Unreadable comment file
+        }
+
+        pendingComments.push({
+            commentRelPath: raw.relPath,
+            commentFullPath: raw.fullPath,
+            targetRelPath,
+            targetType,
+            topicName,
+            content,
+        });
+    }
+
+    return {
+        branchName,
+        activeWorktreeDir,
+        staged,
+        modified,
+        deleted,
+        untracked,
+        pendingComments,
+    };
+}

package/src/test/test-helpers.mts

@@ -0,0 +1,168 @@
+/**
+ * @module test-helpers
+ *
+ * Pure-function diagnostic helpers for logging and inspecting b2tfs ibgib
+ * state during tests. These are NOT production code — they are imported only
+ * by test files (*.respec.mts) and the handful of vcs-gib commands that
+ * temporarily wire in diagnostic logging.
+ *
+ * Usage pattern:
+ *
+ * ```ts
+ * import { logBranchState, logItemState } from '../../test/test-helpers.mjs';
+ * await logBranchState({ label: 'after commit', branchIbGib, space });
+ * ```
+ */
+
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { getLatestAddrs } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+
+import { B2tFSBranchIbGib_V1 } from '../engine/branch/branch-types.mjs';
+import { B2tFSItemIbGib_V1 } from '../engine/item/item-types.mjs';
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function shortAddr(addr: IbGibAddr | undefined): string {
+    if (!addr) { return '(none)'; }
+    // show the first 12 chars of the gib portion for easy visual matching
+    const caretIdx = addr.lastIndexOf('^');
+    if (caretIdx === -1) { return addr.slice(0, 40); }
+    const ib = addr.slice(0, caretIdx);
+    const gib = addr.slice(caretIdx + 1);
+    // gib may be punctiliarHash.tjpGib  — show first 8 of each
+    const dotIdx = gib.indexOf('.');
+    const gibShort = dotIdx === -1
+        ? gib.slice(0, 8)
+        : `${gib.slice(0, 8)}.${gib.slice(dotIdx + 1, dotIdx + 9)}`;
+    return `${ib}^${gibShort}`;
+}
+
+function shortAddrs(addrs: IbGibAddr[] | undefined): string {
+    if (!addrs || addrs.length === 0) { return '[]'; }
+    return `[\n    ${addrs.map(shortAddr).join('\n    ')}\n  ]`;
+}
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Exported diagnostic helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Logs a compact snapshot of a b2tfs branch ibgib and the latest addr for its
+ * b2tfs_item timeline as known by the given space.
+ */
+export async function logBranchState({
+    label,
+    branchIbGib,
+    space,
+}: {
+    label: string;
+    branchIbGib: B2tFSBranchIbGib_V1 | IbGib_V1 | undefined;
+    space?: IbGibSpaceAny;
+}): Promise<void> {
+    const lc = `[logBranchState][${label}]`;
+
+    if (!branchIbGib) {
+        console.log(`${lc} branchIbGib: (UNDEFINED)`);
+        return;
+    }
+
+    const b = branchIbGib as B2tFSBranchIbGib_V1;
+    const addr = getIbGibAddr({ ibGib: b });
+    const n = (b.data as any)?.n ?? '?';
+    const name = b.data?.name ?? '?';
+    const tjpAddr = b.rel8ns?.tjp?.at(0);
+    const itemAddrs = b.rel8ns?.b2tfs_item ?? [];
+
+    console.log(`${lc}
+  addr      : ${shortAddr(addr)}
+  name      : ${name}
+  n         : ${n}
+  tjp       : ${shortAddr(tjpAddr)}
+  b2tfs_item: ${shortAddrs(itemAddrs)} (${itemAddrs.length} total, tip: ${shortAddr(itemAddrs.at(-1))})`);
+
+    if (space && tjpAddr) {
+        try {
+            const res = await getLatestAddrs({ addrs: [tjpAddr], space });
+            const latest = (res?.data as any)?.latestAddrs?.[0];
+            console.log(`  [space ${(space as any).ib ?? space.constructor.name}] latestAddr for branch TJP: ${shortAddr(latest)}`);
+        } catch (e) {
+            console.log(`  [space] getLatestAddrs for branch TJP THREW: ${e}`);
+        }
+    }
+}
+
+/**
+ * Logs a compact snapshot of a b2tfs item ibgib and optionally the latest addr
+ * for its timeline as known by the given space.
+ */
+export async function logItemState({
+    label,
+    itemIbGib,
+    space,
+}: {
+    label: string;
+    itemIbGib: B2tFSItemIbGib_V1 | IbGib_V1 | undefined;
+    space?: IbGibSpaceAny;
+}): Promise<void> {
+    const lc = `[logItemState][${label}]`;
+
+    if (!itemIbGib) {
+        console.log(`${lc} itemIbGib: (UNDEFINED)`);
+        return;
+    }
+
+    const item = itemIbGib as B2tFSItemIbGib_V1;
+    const addr = getIbGibAddr({ ibGib: item });
+    const n = (item.data as any)?.n ?? '?';
+    const fsType = item.data?.fsType ?? '?';
+    const filename = item.data?.filename ?? item.data?.name ?? '?';
+    const tjpAddr = item.rel8ns?.tjp?.at(0);
+    const textContent = (item.data as any)?.textContent as string | undefined;
+    const binRel8n = (item.rel8ns as any)?.bin ?? (item.rel8ns as any)?.binary;
+
+    console.log(`${lc}
+  addr      : ${shortAddr(addr)}
+  filename  : ${filename}  fsType: ${fsType}
+  n         : ${n}
+  tjp       : ${shortAddr(tjpAddr)}
+  text      : ${textContent !== undefined ? JSON.stringify(textContent.slice(0, 120)) : binRel8n ? `(binary, bin rel8n: ${shortAddrs(binRel8n)})` : '(none)'}`);
+
+    if (space && tjpAddr) {
+        try {
+            const res = await getLatestAddrs({ addrs: [tjpAddr], space });
+            const latest = (res?.data as any)?.latestAddrs?.[0];
+            console.log(`  [space ${(space as any).ib ?? space.constructor.name}] latestAddr for item TJP: ${shortAddr(latest)}`);
+        } catch (e) {
+            console.log(`  [space] getLatestAddrs for item TJP THREW: ${e}`);
+        }
+    }
+}
+
+/**
+ * Logs a one-line separator to make log sections visually scannable.
+ */
+export function logCheckpoint(label: string): void {
+    const bar = '─'.repeat(60);
+    console.log(`\n${bar}\n  CHECKPOINT: ${label}\n${bar}`);
+}
+
+/**
+ * Logs the full addr (no shortening) for debugging addr comparison issues.
+ */
+export function logAddr(label: string, addr: IbGibAddr | undefined): void {
+    console.log(`[ADDR][${label}]: ${addr ?? '(undefined)'}`);
+}
+
+/**
+ * Logs a set of addrs with short formatting.
+ */
+export function logAddrs(label: string, addrs: IbGibAddr[] | undefined): void {
+    console.log(`[ADDRS][${label}]: ${shortAddrs(addrs)}`);
+}