gitforest 0.1.0

package/src/utils/errors.ts

@@ -0,0 +1,17 @@
+/**
+ * Error handling utilities
+ */
+
+/**
+ * Safely convert an unknown error to a string message.
+ * Handles Error objects, strings, and unknown types gracefully.
+ */
+export function errorToString(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return String(error);
+}

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility exports
+ * Pure functions for filtering and sorting (no dependencies on state)
+ */
+
+export { sortProjects, filterProjects } from "./project-utils.ts";
+export { errorToString } from "./errors.ts";
+export { withTimeout, createTimeoutController, TimeoutError } from "./timeout.ts";

package/src/utils/markdown.ts

@@ -0,0 +1,230 @@
+export interface MarkdownNode {
+  type: 'heading' | 'paragraph' | 'code' | 'codeblock' | 'list' | 'listitem' | 'blockquote' | 'hr' | 'link' | 'bold' | 'italic' | 'text';
+  content?: string;
+  level?: number; // for headings (1-6)
+  language?: string; // for code blocks
+  url?: string; // for links
+  children?: MarkdownNode[];
+}
+
+export function parseMarkdown(markdown: string): MarkdownNode[] {
+  const lines = markdown.split('\n');
+  const nodes: MarkdownNode[] = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // Skip empty lines
+    if (!line?.trim()) {
+      i++;
+      continue;
+    }
+
+    // Horizontal rule
+    if (/^---+\s*$/.test(line)) {
+      nodes.push({ type: 'hr' });
+      i++;
+      continue;
+    }
+
+    // Code block
+    if (line.startsWith('```')) {
+      const language = line.slice(3).trim();
+      const content: string[] = [];
+      i++;
+      while (i < lines.length && !lines[i]?.startsWith('```')) {
+        content.push(lines[i] || '');
+        i++;
+      }
+      nodes.push({
+        type: 'codeblock',
+        content: content.join('\n'),
+        language: language || undefined
+      });
+      i++; // Skip closing ```
+      continue;
+    }
+
+    // Blockquote
+    if (line.startsWith('>')) {
+      const content = line.replace(/^>\s?/, '');
+      nodes.push({
+        type: 'blockquote',
+        content: content
+      });
+      i++;
+      continue;
+    }
+
+    // Heading
+    const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      nodes.push({
+        type: 'heading',
+        level: headingMatch[1]?.length || 1,
+        content: headingMatch[2] || ''
+      });
+      i++;
+      continue;
+    }
+
+    // List item
+    const listMatch = line.match(/^([\s]*)[-*+]\s+(.+)$/);
+    if (listMatch) {
+      const listNodes: MarkdownNode[] = [];
+      
+      while (i < lines.length) {
+        const currentLine = lines[i];
+        const currentMatch = currentLine?.match(/^([\s]*)[-*+]\s+(.+)$/);
+        
+        if (!currentMatch) break;
+        
+        listNodes.push({
+          type: 'listitem',
+          content: currentMatch[2] || ''
+        });
+        i++;
+      }
+      
+      nodes.push({
+        type: 'list',
+        children: listNodes
+      });
+      continue;
+    }
+
+    // Paragraph
+    nodes.push(parseParagraph(line));
+    i++;
+  }
+
+  return nodes;
+}
+
+function parseParagraph(text: string): MarkdownNode {
+  const children: MarkdownNode[] = [];
+  let remaining = text;
+
+  while (remaining) {
+    // Check for code
+    const codeMatch = remaining.match(/^`([^`]+)`/);
+    if (codeMatch) {
+      children.push({
+        type: 'code',
+        content: codeMatch[1]
+      });
+      remaining = remaining.slice(codeMatch[0].length);
+      continue;
+    }
+
+    // Check for bold
+    const boldMatch = remaining.match(/^\*\*([^*]+)\*\*/);
+    if (boldMatch) {
+      children.push({
+        type: 'bold',
+        content: boldMatch[1]
+      });
+      remaining = remaining.slice(boldMatch[0].length);
+      continue;
+    }
+
+    // Check for italic
+    const italicMatch = remaining.match(/^\*([^*]+)\*/);
+    if (italicMatch) {
+      children.push({
+        type: 'italic',
+        content: italicMatch[1]
+      });
+      remaining = remaining.slice(italicMatch[0].length);
+      continue;
+    }
+
+    // Check for link
+    const linkMatch = remaining.match(/^\[([^\]]+)\]\(([^)]+)\)/);
+    if (linkMatch) {
+      children.push({
+        type: 'link',
+        content: linkMatch[1],
+        url: linkMatch[2]
+      });
+      remaining = remaining.slice(linkMatch[0].length);
+      continue;
+    }
+
+    // Regular text - find next special character
+    const nextSpecial = remaining.search(/[`\*\[]/);
+    if (nextSpecial === -1) {
+      children.push({
+        type: 'text',
+        content: remaining
+      });
+      break;
+    } else if (nextSpecial > 0) {
+      children.push({
+        type: 'text',
+        content: remaining.slice(0, nextSpecial)
+      });
+      remaining = remaining.slice(nextSpecial);
+    } else {
+      // Special character at start but no match - treat as text
+      children.push({
+        type: 'text',
+        content: remaining[0]
+      });
+      remaining = remaining.slice(1);
+    }
+  }
+
+  return {
+    type: 'paragraph',
+    children
+  };
+}
+
+export function truncateMarkdown(nodes: MarkdownNode[], maxLines: number): MarkdownNode[] {
+  const lines: MarkdownNode[] = [];
+  
+  function countLines(node: MarkdownNode): number {
+    if (node.type === 'text' || node.type === 'code' || node.type === 'bold' || 
+        node.type === 'italic' || node.type === 'link') {
+      return Math.ceil((node.content?.length || 0) / 80) || 1;
+    }
+    if (node.type === 'paragraph') {
+      return 1;
+    }
+    if (node.type === 'heading') {
+      return 1;
+    }
+    if (node.type === 'codeblock') {
+      return (node.content?.split('\n').length || 0) + 2; // +2 for borders
+    }
+    if (node.type === 'list' && node.children) {
+      return node.children.length;
+    }
+    if (node.type === 'listitem' || node.type === 'blockquote') {
+      return 1;
+    }
+    if (node.type === 'hr') {
+      return 1;
+    }
+    return 1;
+  }
+  
+  function addNode(node: MarkdownNode): boolean {
+    const linesNeeded = countLines(node);
+    if (lines.length + linesNeeded > maxLines) {
+      return false;
+    }
+    lines.push(node);
+    return true;
+  }
+  
+  for (const node of nodes) {
+    if (!addNode(node)) {
+      break;
+    }
+  }
+  
+  return lines;
+}

package/src/utils/project-utils.ts

@@ -0,0 +1,129 @@
+/**
+ * Utility functions for filtering and sorting projects
+ * These are extracted to avoid circular dependencies between state and scanner
+ */
+
+import type { Project, SortField, SortDirection } from "../types/index.ts";
+
+/**
+ * Get status priority for sorting (lower = more attention needed)
+ */
+function getStatusPriority(project: Project): number {
+  if (project.type === "non-git") return 100;
+  if (!project.status) return 99;
+
+  let priority = 0;
+
+  // Dirty repos need attention
+  if (project.status.isDirty) priority -= 40;
+
+  // Out of sync repos need attention
+  if (project.status.isAhead) priority -= 20;
+  if (project.status.isBehind) priority -= 30;
+
+  // No remote = might need setup
+  if (!project.status.hasRemote) priority -= 10;
+
+  return priority;
+}
+
+/**
+ * Sort projects based on configuration
+ */
+export function sortProjects(
+  projects: Project[],
+  sortBy: SortField,
+  direction: SortDirection
+): Project[] {
+  const sorted = [...projects].sort((a, b) => {
+    let comparison = 0;
+
+    switch (sortBy) {
+      case "name":
+        comparison = a.name.localeCompare(b.name);
+        break;
+
+      case "branch": {
+        const aBranch = a.status?.currentBranch ?? "";
+        const bBranch = b.status?.currentBranch ?? "";
+        comparison = aBranch.localeCompare(bBranch);
+        break;
+      }
+
+      case "status":
+        // Lower priority = needs more attention
+        // For "desc": most attention-needed first (lowest priority numbers first)
+        // For "asc": least attention-needed first (highest priority numbers first)
+        comparison = getStatusPriority(a) - getStatusPriority(b);
+        // Don't invert for desc - we want lower priority (more important) first
+        return direction === "desc" ? comparison : -comparison;
+
+      case "sync": {
+        const aStatus = a.status;
+        const bStatus = b.status;
+        const aDelta = aStatus ? (aStatus.unpushedCommits ?? 0) + (aStatus.unpulledCommits ?? 0) : 0;
+        const bDelta = bStatus ? (bStatus.unpushedCommits ?? 0) + (bStatus.unpulledCommits ?? 0) : 0;
+        comparison = aDelta - bDelta;
+        break;
+      }
+
+      case "language": {
+        const aLang = (a.status as any)?.language || "";
+        const bLang = (b.status as any)?.language || "";
+        comparison = aLang.localeCompare(bLang);
+        break;
+      }
+
+      case "lastActivity":
+        // Handle both Date objects and string timestamps
+        const aTime = a.status?.lastLocalCommit ? 
+          (typeof a.status.lastLocalCommit === 'string' ? 
+            new Date(a.status.lastLocalCommit).getTime() : 
+            a.status.lastLocalCommit.getTime()) : 0;
+        const bTime = b.status?.lastLocalCommit ? 
+          (typeof b.status.lastLocalCommit === 'string' ? 
+            new Date(b.status.lastLocalCommit).getTime() : 
+            b.status.lastLocalCommit.getTime()) : 0;
+        // For desc: most recent first (higher date value first)
+        // For asc: oldest first (lower date value first)
+        comparison = aTime - bTime;
+        break;
+
+      case "stars":
+      case "forks":
+      case "size":
+        // Projects don't include GitHub metadata directly; keep stable
+        comparison = 0;
+        break;
+    }
+
+    return direction === "desc" ? -comparison : comparison;
+  });
+
+  return sorted;
+}
+
+/**
+ * Filter projects based on text search
+ */
+export function filterProjects(projects: Project[], filterText: string): Project[] {
+  if (!filterText.trim()) return projects;
+
+  const lower = filterText.toLowerCase();
+
+  return projects.filter((p) => {
+    // Match name
+    if (p.name.toLowerCase().includes(lower)) return true;
+
+    // Match path
+    if (p.path.toLowerCase().includes(lower)) return true;
+
+    // Match project marker
+    if (p.projectMarker?.toLowerCase().includes(lower)) return true;
+
+    // Match type
+    if (p.type.toLowerCase().includes(lower)) return true;
+
+    return false;
+  });
+}

package/src/utils/rate-limiter.ts

@@ -0,0 +1,134 @@
+/**
+ * Rate limiting utilities for batch operations
+ */
+
+/**
+ * Semaphore for controlling concurrent operations
+ */
+export class Semaphore {
+  private permits: number;
+  private waiting: Array<() => void> = [];
+
+  constructor(maxConcurrent: number) {
+    this.permits = maxConcurrent;
+  }
+
+  async acquire(): Promise<void> {
+    if (this.permits > 0) {
+      this.permits--;
+      return;
+    }
+
+    return new Promise<void>((resolve) => {
+      this.waiting.push(resolve);
+    });
+  }
+
+  release(): void {
+    if (this.waiting.length > 0) {
+      const next = this.waiting.shift();
+      if (next) next();
+    } else {
+      this.permits++;
+    }
+  }
+
+  /**
+   * Execute a function with semaphore protection
+   */
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      this.release();
+    }
+  }
+}
+
+/**
+ * Rate limiter that enforces a minimum delay between operations
+ */
+export class RateLimiter {
+  private lastOperation: number = 0;
+
+  constructor(private minDelayMs: number) {}
+
+  async wait(): Promise<void> {
+    const now = Date.now();
+    const elapsed = now - this.lastOperation;
+    
+    if (elapsed < this.minDelayMs) {
+      await new Promise((resolve) => 
+        setTimeout(resolve, this.minDelayMs - elapsed)
+      );
+    }
+    
+    this.lastOperation = Date.now();
+  }
+}
+
+export interface BatchItemResult<R> {
+  success: boolean;
+  result?: R;
+  error?: Error;
+}
+
+export interface ProcessBatchOptions<T, R> {
+  /** Maximum concurrent operations (default: 5) */
+  concurrency?: number;
+  /** Minimum delay between operations in ms (default: 0) */
+  minDelay?: number;
+  /** Progress callback */
+  onProgress?: (completed: number, total: number) => void;
+  /** Error handler - return true to continue, false to stop */
+  onError?: (error: Error, item: T) => boolean;
+  /** Optional result transformer */
+  transform?: (result: R) => R;
+}
+
+/**
+ * Process items in batches with rate limiting
+ */
+export async function processBatch<T, R>(
+  items: T[],
+  processor: (item: T) => Promise<R>,
+  options: ProcessBatchOptions<T, R> = {}
+): Promise<BatchItemResult<R>[]> {
+  const {
+    concurrency = 5,
+    minDelay = 0,
+    onProgress,
+    onError,
+  } = options;
+
+  const semaphore = new Semaphore(concurrency);
+  const rateLimiter = minDelay > 0 ? new RateLimiter(minDelay) : null;
+  let completed = 0;
+
+  const processItem = async (item: T): Promise<BatchItemResult<R>> => {
+    return semaphore.run(async () => {
+      if (rateLimiter) {
+        await rateLimiter.wait();
+      }
+
+      try {
+        const result = await processor(item);
+        completed++;
+        onProgress?.(completed, items.length);
+        return { success: true, result };
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (onError && !onError(err, item)) {
+          throw err; // Stop processing
+        }
+        completed++;
+        onProgress?.(completed, items.length);
+        return { success: false, error: err };
+      }
+    });
+  };
+
+  const promises = items.map((item) => processItem(item));
+  return await Promise.all(promises);
+}

package/src/utils/retry.ts

@@ -0,0 +1,147 @@
+/**
+ * Retry utilities with exponential backoff
+ */
+
+export class RetryError extends Error {
+  constructor(
+    message: string,
+    public readonly attempts: number,
+    public readonly lastError: Error
+  ) {
+    super(message);
+    this.name = 'RetryError';
+  }
+}
+
+export interface RetryOptions {
+  /** Maximum number of retry attempts (default: 3) */
+  maxAttempts?: number;
+  /** Initial delay in milliseconds (default: 1000) */
+  initialDelay?: number;
+  /** Maximum delay in milliseconds (default: 30000) */
+  maxDelay?: number;
+  /** Backoff multiplier (default: 2) */
+  backoffFactor?: number;
+  /** Function to determine if error is retryable */
+  shouldRetry?: (error: Error, attempt: number) => boolean;
+  /** Callback on each retry */
+  onRetry?: (error: Error, attempt: number, nextDelay: number) => void;
+}
+
+/**
+ * Execute a function with automatic retry and exponential backoff
+ * 
+ * Retries failed operations with increasing delays between attempts.
+ * Useful for handling transient failures in network requests.
+ * 
+ * @param fn - Async function to execute
+ * @param options - Retry configuration options
+ * @returns Promise resolving to the function's return value
+ * @throws {RetryError} If all retry attempts fail
+ * 
+ * @example
+ * ```typescript
+ * const data = await withRetry(
+ *   () => fetch('https://api.example.com/data'),
+ *   {
+ *     maxAttempts: 3,
+ *     initialDelay: 1000,
+ *     shouldRetry: (err) => err.message.includes('timeout')
+ *   }
+ * );
+ * ```
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const {
+    maxAttempts = 3,
+    initialDelay = 1000,
+    maxDelay = 30000,
+    backoffFactor = 2,
+    shouldRetry = () => true,
+    onRetry,
+  } = options;
+
+  let lastError: Error = new Error('No attempts made');
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      if (attempt === maxAttempts || !shouldRetry(lastError, attempt)) {
+        break;
+      }
+
+      const delay = Math.min(
+        initialDelay * Math.pow(backoffFactor, attempt - 1),
+        maxDelay
+      );
+
+      onRetry?.(lastError, attempt, delay);
+
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  throw new RetryError(
+    `Failed after ${maxAttempts} attempts: ${lastError.message}`,
+    maxAttempts,
+    lastError
+  );
+}
+
+/**
+ * Determine if a GitHub API error should be retried
+ * 
+ * Implements retry logic specific to GitHub API errors:
+ * - Retries on rate limits (429) and server errors (5xx)
+ * - Retries on network errors
+ * - Does not retry on client errors (4xx except 429)
+ * 
+ * @param error - The error that occurred
+ * @param _attempt - The attempt number (unused)
+ * @returns true if the error is retryable, false otherwise
+ * 
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => githubApiCall(),
+ *   {
+ *     shouldRetry: shouldRetryGitHubError
+ *   }
+ * );
+ * ```
+ */
+export function shouldRetryGitHubError(error: Error, _attempt: number): boolean {
+  const message = error.message.toLowerCase();
+  
+  // Rate limit errors - always retry
+  if (message.includes('rate limit') || message.includes('429')) {
+    return true;
+  }
+  
+  // Server errors (5xx) - retry
+  if (message.includes('500') || message.includes('502') || 
+      message.includes('503') || message.includes('504')) {
+    return true;
+  }
+  
+  // Network errors - retry
+  if (message.includes('network') || message.includes('econnreset') ||
+      message.includes('etimedout') || message.includes('fetch failed')) {
+    return true;
+  }
+  
+  // Client errors (4xx except 429) - don't retry
+  if (message.includes('401') || message.includes('403') || 
+      message.includes('404') || message.includes('422')) {
+    return false;
+  }
+  
+  // Default: retry up to 3 times
+  return true;
+}