ftreeview 0.1.1

package/src/hooks/useTree.js

@@ -0,0 +1,508 @@
+/**
+ * useTree - FileNode Tree Builder Hook
+ *
+ * Provides utilities for building and managing a hierarchical file tree structure.
+ * This hook creates FileNode objects from the file system and handles tree traversal.
+ */
+
+import { readdirSync, statSync, lstatSync, readlinkSync } from 'node:fs';
+import { resolve, basename, relative, sep } from 'node:path';
+import { useState, useCallback, useRef } from 'react';
+import { DEFAULT_CONFIG } from '../lib/constants.js';
+import {
+  mapGitStatusToChangeStatus,
+  mergeChangeStatus,
+  normalizeChangeStatus,
+} from '../lib/changeStatus.js';
+import { createIgnoreFilter } from './useIgnore.js';
+
+/**
+ * Creates a FileNode object from file system entry information
+ * Handles permission errors and symlink detection
+ *
+ * @param {string} absPath - Absolute path to the file/directory
+ * @param {string} rootPath - Root directory path for relative path calculation
+ * @param {number} depth - Nesting level in the tree
+ * @param {boolean} isDir - Whether this is a directory
+ * @param {boolean} isSymlink - Whether this is a symbolic link
+ * @returns {FileNode} A FileNode object
+ */
+function createFileNode(absPath, rootPath, depth, isDir, isSymlink = false) {
+  let stats;
+  let targetPath = null;
+  let hasError = false;
+  let error = null;
+
+  // Handle permission errors
+  try {
+    // Use lstatSync for symlinks (doesn't follow them)
+    stats = isSymlink ? lstatSync(absPath) : statSync(absPath);
+
+    // For symlinks, try to read the target
+    if (isSymlink) {
+      try {
+        targetPath = readlinkSync(absPath);
+      } catch (e) {
+        // Can't read symlink target - mark as error but keep node
+        hasError = true;
+        error = 'Cannot read symlink';
+      }
+    }
+  } catch (e) {
+    if (e.code === 'EACCES' || e.code === 'EPERM') {
+      // Permission denied - create error node
+      return {
+        name: basename(absPath),
+        path: relative(rootPath, absPath).split(sep).join('/'),
+        absPath,
+        isDir,
+        children: null,
+        expanded: false,
+        depth,
+        size: 0,
+        mode: 0,
+        gitStatus: '',
+        changeStatus: '',
+        hasError: true,
+        error: 'Permission denied',
+      };
+    }
+    // Re-throw other errors
+    throw e;
+  }
+
+  return {
+    name: basename(absPath),
+    path: relative(rootPath, absPath).split(sep).join('/'),
+    absPath,
+    isDir,
+    children: isDir ? [] : null,
+    expanded: false,
+    depth,
+    size: stats.size,
+    mode: stats.mode,
+    gitStatus: '', // Will be populated by git status hook (T10)
+    changeStatus: '', // Combined A/M indicator from git + watcher states
+    isSymlink,
+    targetPath,
+    hasError,
+    error,
+  };
+}
+
+/**
+ * Compare function for sorting FileNodes
+ * Directories come first, then files, both sorted case-insensitively
+ *
+ * @param {FileNode} a - First node to compare
+ * @param {FileNode} b - Second node to compare
+ * @returns {number} Comparison result for sort
+ */
+function compareNodes(a, b) {
+  // Directories always come before files
+  if (a.isDir && !b.isDir) return -1;
+  if (!a.isDir && b.isDir) return 1;
+
+  // Within the same type, sort case-insensitively
+  return a.name.localeCompare(b.name, undefined, { sensitivity: 'base' });
+}
+
+/**
+ * Recursively builds a FileNode tree from the file system
+ *
+ * @param {string} rootPath - Absolute path to the directory to scan (root on initial call)
+ * @param {object} options - Configuration options
+ * @param {number} [options.depth] - Maximum depth to traverse (default: from DEFAULT_CONFIG)
+ * @param {number} [currentDepth=0] - Current traversal depth (internal)
+ * @param {object} [ignoreFilter] - Ignore filter instance (internal)
+ * @param {string|null} [baseRootPath] - Absolute root path used for node.path (internal)
+ * @returns {FileNode} The root FileNode of the tree
+ */
+export function buildTree(rootPath, options = {}, currentDepth = 0, ignoreFilter = null, baseRootPath = null) {
+  const { depth = DEFAULT_CONFIG.maxDepth, showHidden = false } = options;
+  const finalBaseRootPath = baseRootPath || rootPath;
+
+  // Create ignore filter on initial call
+  if (ignoreFilter === null) {
+    ignoreFilter = createIgnoreFilter(finalBaseRootPath, options);
+  }
+
+  // Create root node
+  const rootNode = createFileNode(rootPath, finalBaseRootPath, currentDepth, true, false);
+  rootNode.expanded = true; // Root always starts expanded
+
+  // Check if we've reached the depth limit
+  if (currentDepth >= depth) {
+    return rootNode;
+  }
+
+  try {
+    // Load .gitignore patterns for this directory
+    if (ignoreFilter.loadPatternsForDirectory) {
+      ignoreFilter.loadPatternsForDirectory(rootPath);
+    }
+
+    // Read directory entries with file type information
+    const entries = readdirSync(rootPath, { withFileTypes: true });
+
+    // Process each entry
+    for (const entry of entries) {
+      const entryName = entry.name;
+      const entryAbsPath = resolve(rootPath, entryName);
+
+      // Always hide .git directory (even if ignore filtering is disabled)
+      if (entryName === '.git') {
+        continue;
+      }
+
+      // Skip hidden files if not showing them
+      if (!showHidden && entryName.startsWith('.')) {
+        continue;
+      }
+
+      const isDir = entry.isDirectory();
+      const isSymlink = entry.isSymbolicLink();
+
+      // Calculate relative path for ignore filtering
+      const entryRelativePath = relative(finalBaseRootPath, entryAbsPath);
+
+      // Check if this entry should be ignored
+      if (ignoreFilter.shouldIgnore(entryRelativePath)) {
+        continue;
+      }
+
+      // Create child node with symlink detection
+      let childNode;
+      try {
+        childNode = createFileNode(
+          entryAbsPath,
+          finalBaseRootPath,
+          currentDepth + 1,
+          isDir,
+          isSymlink,
+        );
+      } catch (e) {
+        // Handle permission errors for individual entries
+        if (e.code === 'EACCES' || e.code === 'EPERM') {
+          childNode = {
+            name: entryName,
+            path: relative(finalBaseRootPath, entryAbsPath).split(sep).join('/'),
+            absPath: entryAbsPath,
+            isDir,
+            children: null,
+            expanded: false,
+            depth: currentDepth + 1,
+            size: 0,
+            mode: 0,
+            gitStatus: '',
+            changeStatus: '',
+            hasError: true,
+            error: 'Permission denied',
+            isSymlink,
+            targetPath: null,
+          };
+        } else {
+          // For other errors, skip this entry
+          continue;
+        }
+      }
+
+      // Recursively build subtree for directories (but not for symlinks to directories)
+      if (isDir && !isSymlink) {
+        const childOptions = { ...options, showHidden };
+        const subtree = buildTree(
+          entryAbsPath,
+          childOptions,
+          currentDepth + 1,
+          ignoreFilter,
+          finalBaseRootPath,
+        );
+        childNode.children = subtree.children;
+      }
+
+      rootNode.children.push(childNode);
+    }
+
+    // Sort children: directories first, then case-insensitive alphabetical
+    rootNode.children.sort(compareNodes);
+  } catch (error) {
+    // If we can't read a directory, handle permission errors
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      rootNode.hasError = true;
+      rootNode.error = 'Permission denied';
+      rootNode.children = [];
+    } else {
+      // For other errors, also leave children empty
+      rootNode.children = [];
+    }
+  }
+
+  return rootNode;
+}
+
+/**
+ * Flattens a FileNode tree into an array of visible nodes
+ * Only includes children of expanded directories for rendering
+ *
+ * @param {FileNode} root - The root FileNode of the tree
+ * @returns {FileNode[]} Array of visible FileNodes in traversal order
+ */
+export function flattenTree(root) {
+  const result = [];
+
+  /**
+   * Recursive helper to traverse and collect visible nodes
+   * @param {FileNode} node - Current node being traversed
+   */
+  function traverse(node) {
+    // Add current node to result
+    result.push(node);
+
+    // If node is expanded and has children, traverse them
+    if (node.expanded && node.children && node.children.length > 0) {
+      for (const child of node.children) {
+        traverse(child);
+      }
+    }
+  }
+
+  traverse(root);
+  return result;
+}
+
+/**
+ * Applies git status from statusMap to tree nodes
+ * Propagates git status through the tree with aggregation for directories
+ *
+ * Priority order for aggregation (highest to lowest):
+ * D (deleted) > M (modified) > A (added) > U (untracked) > R (renamed) > clean
+ *
+ * @param {FileNode} root - The root FileNode of the tree
+ * @param {Map<string, string>} statusMap - Map of file paths to git status codes
+ * @returns {FileNode} The modified root node with gitStatus set
+ */
+export function applyGitStatus(root, statusMap) {
+  /**
+   * Walk the tree recursively and set gitStatus on nodes
+   * @param {FileNode} node - Current node being processed
+   */
+  function walk(node) {
+    if (!node.isDir) {
+      // File: lookup in statusMap, default to empty string (clean)
+      node.gitStatus = statusMap.get(node.path) || '';
+    } else {
+      // Directory: aggregate from children
+      let aggregatedStatus = '';
+
+      // First walk all children to populate their gitStatus
+      for (const child of node.children) {
+        walk(child);
+
+        // Aggregate child status with priority ordering
+        const childStatus = child.gitStatus;
+
+        if (childStatus === 'D') {
+          // Deleted has highest priority
+          aggregatedStatus = 'D';
+        } else if (childStatus === 'M' && aggregatedStatus !== 'D') {
+          // Modified has second priority
+          aggregatedStatus = 'M';
+        } else if (childStatus === 'A' && aggregatedStatus !== 'D' && aggregatedStatus !== 'M') {
+          // Added has third priority
+          aggregatedStatus = 'A';
+        } else if (childStatus === 'U' && !aggregatedStatus) {
+          // Untracked (no status yet)
+          aggregatedStatus = 'U';
+        } else if (childStatus === 'R' && !aggregatedStatus) {
+          // Renamed (no status yet)
+          aggregatedStatus = 'R';
+        }
+      }
+
+      node.gitStatus = aggregatedStatus;
+    }
+  }
+
+  walk(root);
+  return root;
+}
+
+/**
+ * Applies combined added/modified indicators to tree nodes.
+ * Uses git + watcher status sources and propagates to directories.
+ *
+ * Priority order: M > A > clean
+ *
+ * @param {FileNode} root - The root FileNode of the tree
+ * @param {Map<string, string>} gitStatusMap - Map of git statuses by path
+ * @param {Map<string, string>} watcherStatusMap - Map of watcher statuses by path
+ * @returns {FileNode} The modified root node with changeStatus set
+ */
+export function applyChangeIndicators(root, gitStatusMap = new Map(), watcherStatusMap = new Map()) {
+  /**
+   * Walk the tree recursively and set changeStatus on nodes.
+   *
+   * @param {FileNode} node - Current node being processed
+   * @returns {''|'A'|'M'} Node indicator status
+   */
+  function walk(node) {
+    if (!node.isDir) {
+      const gitChangeStatus = mapGitStatusToChangeStatus(
+        gitStatusMap.get(node.path) || node.gitStatus || ''
+      );
+      const watcherChangeStatus = normalizeChangeStatus(
+        watcherStatusMap.get(node.path) || ''
+      );
+      const fileChangeStatus = mergeChangeStatus(gitChangeStatus, watcherChangeStatus);
+      node.changeStatus = fileChangeStatus;
+      return fileChangeStatus;
+    }
+
+    // Allow direct watcher events on directories (e.g., addDir)
+    let aggregatedStatus = normalizeChangeStatus(watcherStatusMap.get(node.path) || '');
+
+    if (node.children && node.children.length > 0) {
+      for (const child of node.children) {
+        const childStatus = walk(child);
+        aggregatedStatus = mergeChangeStatus(aggregatedStatus, childStatus);
+      }
+    }
+
+    // Never show the indicator on the root "parent" folder (depth 0).
+    const finalStatus = node.depth === 0 ? '' : aggregatedStatus;
+    node.changeStatus = finalStatus;
+    return finalStatus;
+  }
+
+  walk(root);
+  return root;
+}
+
+/**
+ * Merge expanded state from old tree into new tree
+ * This preserves the expand/collapse state across rebuilds
+ *
+ * @param {FileNode} oldTree - The old tree structure before rebuild
+ * @param {FileNode} newTree - The newly built tree structure
+ * @returns {FileNode} The new tree with expanded states applied
+ */
+export function mergeExpandState(oldTree, newTree) {
+  if (!oldTree || !newTree) return newTree;
+
+  // Build a map of expanded paths from old tree
+  const expandedPaths = new Set();
+
+  function collectExpanded(node) {
+    if (node.isDir && node.expanded) {
+      expandedPaths.add(node.path);
+    }
+    if (node.children) {
+      for (const child of node.children) {
+        collectExpanded(child);
+      }
+    }
+  }
+
+  collectExpanded(oldTree);
+
+  // Apply expanded state to new tree
+  function applyExpanded(node) {
+    if (node.isDir && expandedPaths.has(node.path)) {
+      node.expanded = true;
+    }
+    if (node.children) {
+      for (const child of node.children) {
+        applyExpanded(child);
+      }
+    }
+  }
+
+  applyExpanded(newTree);
+  return newTree;
+}
+
+/**
+ * React hook for building and managing a file tree
+ * Provides state management and rebuild functionality for the file tree
+ *
+ * @param {string} rootPath - Root directory path to explore
+ * @param {object} options - Configuration options
+ * @returns {{tree: FileNode, flatList: FileNode[], refreshFlatList: Function, rebuildTree: Function, getTree: Function}} The tree structure and tree management functions
+ */
+export function useTree(rootPath, options = {}) {
+  const absPath = resolve(rootPath);
+
+  // Initial tree build
+  const [tree, setTree] = useState(() => buildTree(absPath, options));
+
+  // Keep ref to current tree to avoid closure staleness
+  const treeRef = useRef(tree);
+  treeRef.current = tree;
+
+  // Flattened list for rendering
+  const [flatList, setFlatList] = useState(() => flattenTree(tree));
+
+  /**
+   * Refresh only the flattened visible list from the current tree state.
+   * Useful for UI-only changes (expand/collapse) without filesystem rescans.
+   */
+  const refreshFlatList = useCallback(() => {
+    const currentTree = treeRef.current;
+    if (!currentTree) {
+      return;
+    }
+    setFlatList(flattenTree(currentTree));
+  }, []);
+
+  /**
+   * Rebuild the tree, optionally preserving expanded states
+   * This is called when:
+   * - Filesystem state changes (watcher events)
+   * - User refreshes with 'r' key (rebuilds fresh from filesystem)
+   * - Any operation that needs a full rescan from disk
+   *
+   * @param {boolean} preserveState - Whether to preserve expanded states
+   */
+  const rebuildTree = useCallback((preserveState = true) => {
+    // Get current tree from ref (always fresh)
+    const oldTree = treeRef.current;
+
+    // Rebuild tree
+    const newTree = buildTree(absPath, options);
+
+    // Merge expanded state if requested and old tree exists
+    const mergedTree = preserveState && oldTree
+      ? mergeExpandState(oldTree, newTree)
+      : newTree;
+
+    // DEBUG: Log what we're doing
+    if (process.env.FTREE_DEBUG) {
+      const flat = flattenTree(mergedTree);
+      console.log(`[DEBUG] rebuildTree: BEFORE setTree, flatList has ${flat.length} items`);
+      console.log(`[DEBUG] rebuildTree: root has ${mergedTree.children?.length || 0} direct children`);
+      console.log(`[DEBUG] rebuildTree: newTree root has ${newTree.children?.length || 0} direct children`);
+    }
+
+    setTree(mergedTree);
+    setFlatList(flattenTree(mergedTree));
+
+    // DEBUG: Log after setTree/setFlatList
+    if (process.env.FTREE_DEBUG) {
+      console.log(`[DEBUG] rebuildTree: AFTER setTree/setFlatList, flatList state updated`);
+    }
+  }, [absPath, options]);
+
+  /**
+   * Get the current tree state
+   * Useful for external code to read the tree before rebuild
+   */
+  const getTree = useCallback(() => treeRef.current, []);
+
+  return {
+    tree,
+    flatList,
+    refreshFlatList,
+    rebuildTree,
+    getTree,
+  };
+}

package/src/hooks/useWatcher.js

@@ -0,0 +1,129 @@
+/**
+ * useWatcher - File System Watcher Hook
+ *
+ * Provides file system watching capabilities using chokidar.
+ * Detects file changes, additions, and deletions with debouncing.
+ */
+
+import { useEffect, useState, useRef } from 'react';
+import chokidar from 'chokidar';
+import { DEFAULT_CONFIG } from '../lib/constants.js';
+
+function shouldUsePolling(rootPath) {
+  // Allow override via env var for tricky filesystems (WSL /mnt, network drives, etc.)
+  const envOverride = process.env.FTREE_USE_POLLING;
+  if (envOverride === '1' || envOverride === 'true') {
+    return true;
+  }
+  if (envOverride === '0' || envOverride === 'false') {
+    return false;
+  }
+
+  // WSL often needs polling for /mnt/* paths.
+  const isWsl = process.platform === 'linux' && (process.env.WSL_INTEROP || process.env.WSL_DISTRO_NAME);
+  if (isWsl && typeof rootPath === 'string' && rootPath.startsWith('/mnt/')) {
+    return true;
+  }
+
+  return false;
+}
+
+export function useWatcher(rootPath, onTreeChange, options = {}) {
+  const debounceMs = options.debounceMs ?? DEFAULT_CONFIG.debounceDelay;
+  const [isWatching, setIsWatching] = useState(false);
+  const watcherRef = useRef(null);
+  const onTreeChangeRef = useRef(onTreeChange);
+  const mountedRef = useRef(true);
+  const debounceTimerRef = useRef(null);
+  const pendingChangesRef = useRef(new Map()); // path -> event
+  const sawAnyEventRef = useRef(false);
+
+  // Keep callback ref in sync
+  useEffect(() => {
+    onTreeChangeRef.current = onTreeChange;
+  }, [onTreeChange]);
+
+  // Setup and teardown watcher
+  useEffect(() => {
+    mountedRef.current = true;
+
+    if (options.noWatch || !rootPath) {
+      setIsWatching(false);
+      return () => {
+        mountedRef.current = false;
+      };
+    }
+
+    const usePolling = shouldUsePolling(rootPath);
+    const watcher = chokidar.watch(rootPath, {
+      ignored: /(^|[\/\\])\.\./,
+      persistent: true,
+      ignoreInitial: true,
+      followSymlinks: false,
+      ...(usePolling ? { usePolling: true, interval: 300 } : {}),
+    });
+    watcherRef.current = watcher;
+
+    const flushPendingChange = () => {
+      debounceTimerRef.current = null;
+      const hadAnyEvent = sawAnyEventRef.current;
+      const pendingMap = pendingChangesRef.current;
+      sawAnyEventRef.current = false;
+      pendingChangesRef.current = new Map();
+
+      if (hadAnyEvent && mountedRef.current && onTreeChangeRef.current) {
+        const batch = Array.from(pendingMap.entries()).map(([path, event]) => ({ event, path }));
+        onTreeChangeRef.current(batch);
+      }
+    };
+
+    watcher.on('all', (event, path) => {
+      sawAnyEventRef.current = true;
+
+      // Keep a best-effort batch of "change indicator relevant" events.
+      // Prefer add/addDir over change for the same path within the debounce window.
+      if (event === 'add' || event === 'addDir') {
+        pendingChangesRef.current.set(path, event);
+      } else if (event === 'change') {
+        if (!pendingChangesRef.current.has(path)) {
+          pendingChangesRef.current.set(path, event);
+        }
+      }
+
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+      }
+
+      debounceTimerRef.current = setTimeout(flushPendingChange, debounceMs);
+    });
+
+    watcher.on('error', () => {
+      setIsWatching(false);
+    });
+
+    watcher.on('ready', () => {
+      setIsWatching(true);
+    });
+
+    return () => {
+      mountedRef.current = false;
+
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+        debounceTimerRef.current = null;
+      }
+      pendingChangesRef.current = new Map();
+      sawAnyEventRef.current = false;
+
+      if (watcherRef.current) {
+        watcherRef.current.close();
+        watcherRef.current = null;
+      }
+      setIsWatching(false);
+    };
+  }, [rootPath, options.noWatch, debounceMs]);
+
+  return { isWatching };
+}
+
+// Only default export to avoid conflicts with bundling

package/src/index.js

@@ -0,0 +1,22 @@
+/**
+ * ftree - Main entry point re-export
+ *
+ * This module re-exports the public API for the ftree library.
+ * When imported programmatically, it provides access to the core components.
+ */
+
+// Re-export CLI for programmatic usage
+export { default as CLI } from './cli.js';
+
+// Re-export constants for use in components
+export * from './lib/constants.js';
+
+// TODO: Export TreeView component when implemented in T2
+// export { TreeView } from './components/TreeView.jsx';
+
+// Export icon and color utilities
+export * from './lib/icons.js';
+
+// TODO: Export core utilities when implemented
+// export * from './lib/scanner.js';
+// export * from './lib/git.js';