@principal-ai/codebase-composition 0.1.0

package/src/providers/GitVersionControlProvider.ts

@@ -0,0 +1,500 @@
+import ignore from 'ignore';
+import type { Ignore } from 'ignore';
+
+import {
+  VersionControlProvider,
+  VersionControlLayer,
+  VersionControlIgnorePattern,
+} from '../types/version-control-layer';
+
+// Minimal file system interface needed by this provider and electron-react
+export interface FileSystemAdapter {
+  readFile(path: string): Promise<{ content: string } | null>;
+  fileExists?(path: string): Promise<boolean>;
+  isDirectory?(path: string): Promise<boolean>;
+  readDirectory?(path: string): Promise<string[]>;
+  getFileStats?(path: string): Promise<{
+    size: number;
+    isDirectory: boolean;
+    lastModified: Date;
+  } | null>;
+
+  /**
+   * Fast filtered file tree building - adapters must implement this efficiently
+   * for their environment (e.g., using fdir in Node.js, batch APIs for remote, etc.)
+   * @returns paths: Array of relative paths from directoryPath (directories end with '/')
+   * @returns stats: Optional map of path to file stats for performance
+   */
+  buildFilteredFileTree(
+    directoryPath: string,
+    patterns?: string[], // Array of gitignore-style patterns to exclude
+    sourceDirectory?: string, // Optional source directory for scoped filtering
+  ): Promise<{
+    paths: string[];
+    stats?: Map<
+      string,
+      {
+        size: number;
+        isDirectory: boolean;
+        lastModified: Date;
+      }
+    >;
+  }>;
+}
+
+// Git interface needed by this provider and electron-react
+export interface GitAdapter {
+  getCurrentBranch?(repoPath: string): Promise<string | null>;
+  getCurrentCommit?(repoPath: string): Promise<string | null>;
+  getRemotes?(
+    repoPath: string,
+  ): Promise<Array<{ name: string; url: string; type?: 'push' | 'fetch' | 'both' }>>;
+  getStatus?(
+    repoPath: string,
+  ): Promise<{ modified: string[]; untracked: string[]; staged: string[] }>;
+
+  // Extended methods for electron-react
+  detectRepository?(path: string): Promise<{
+    isGitRepository: boolean;
+    currentBranch?: string;
+    owner?: string;
+    repo?: string;
+  } | null>;
+  watchGitRepository?(path: string): Promise<boolean>;
+  stopWatchingGit?(): Promise<void>;
+  onGitStatusChange?(
+    callback: (data: {
+      changedFiles: Array<{
+        path: string;
+        status: 'added' | 'modified' | 'deleted' | 'renamed';
+        lastModified?: Date;
+      }>;
+    }) => void,
+  ): () => void;
+}
+
+// Shell adapter interface for electron-react
+export interface ShellAdapter {
+  openExternal(url: string): Promise<void>;
+}
+
+// Path utilities that work in both Node and browser environments
+const path = {
+  join: (...parts: string[]) => {
+    const joined = parts.filter(p => p).join('/');
+    return joined.replace(/\/+/g, '/');
+  },
+  dirname: (p: string) => {
+    const parts = p.split('/');
+    parts.pop();
+    return parts.join('/') || '/';
+  },
+  relative: (from: string, to: string) => {
+    if (!from || from === '.') return to;
+    if (to.startsWith(from + '/')) return to.slice(from.length + 1);
+    if (to === from) return '.';
+    return to;
+  },
+  basename: (p: string) => {
+    const parts = p.split('/');
+    return parts[parts.length - 1] || '';
+  },
+};
+
+/**
+ * Git implementation of VersionControlProvider for core library
+ * Handles .gitignore parsing and Git-specific operations
+ */
+export class GitVersionControlProvider implements VersionControlProvider {
+  constructor(
+    private fileSystemAdapter: FileSystemAdapter,
+    private gitAdapter?: GitAdapter,
+  ) {}
+
+  async detect(directoryPath: string): Promise<boolean> {
+    // Check if .git directory exists
+    let currentPath = directoryPath;
+
+    while (currentPath && currentPath !== '/' && currentPath !== '.') {
+      const gitPath = path.join(currentPath, '.git');
+
+      // Try using isDirectory if available, otherwise check for .git/HEAD file
+      if (this.fileSystemAdapter.isDirectory) {
+        if (await this.fileSystemAdapter.isDirectory(gitPath)) {
+          return true;
+        }
+      } else if (this.fileSystemAdapter.fileExists) {
+        // Fallback: check for .git/HEAD file
+        const headPath = path.join(gitPath, 'HEAD');
+        if (await this.fileSystemAdapter.fileExists(headPath)) {
+          return true;
+        }
+      }
+
+      // Move up one directory
+      const parent = path.dirname(currentPath);
+      if (parent === currentPath) break; // Reached root
+      currentPath = parent;
+    }
+
+    return false;
+  }
+
+  async getRepositoryRoot(directoryPath: string): Promise<string | null> {
+    let currentPath = directoryPath;
+
+    while (currentPath && currentPath !== '/' && currentPath !== '.') {
+      const gitPath = path.join(currentPath, '.git');
+
+      // Check using same logic as detect
+      let isGitRepo = false;
+      if (this.fileSystemAdapter.isDirectory) {
+        isGitRepo = await this.fileSystemAdapter.isDirectory(gitPath);
+      } else if (this.fileSystemAdapter.fileExists) {
+        const headPath = path.join(gitPath, 'HEAD');
+        isGitRepo = await this.fileSystemAdapter.fileExists(headPath);
+      }
+
+      if (isGitRepo) {
+        return currentPath;
+      }
+
+      // Move up one directory
+      const parent = path.dirname(currentPath);
+      if (parent === currentPath) break; // Reached root
+      currentPath = parent;
+    }
+
+    return null;
+  }
+
+  async createLayer(repositoryRoot: string): Promise<VersionControlLayer> {
+    // PERFORMANCE OPTIMIZATION: Return minimal git metadata since buildFilteredFileTree
+    // now handles all filtering. This avoids expensive file reads for .git/HEAD, .git/config, etc.
+
+    const ignorePatterns = await this.extractIgnorePatterns(repositoryRoot);
+
+    // Return default values instead of reading git files
+    const currentBranch = 'main'; // Default branch name
+    const currentRevision = 'unknown'; // Skip expensive git file reads
+    const remotes: Array<{ name: string; url: string; type: 'push' | 'fetch' | 'both' }> = []; // Empty remotes
+
+    return {
+      id: `vcs-git-${repositoryRoot.replace(/[^a-zA-Z0-9]/g, '-')}`,
+      name: 'Git Version Control',
+      type: 'version-control',
+      enabled: true,
+      workspaceRoot: repositoryRoot,
+      vcsData: {
+        system: 'git',
+        repositoryRoot,
+        currentBranch: currentBranch || 'unknown',
+        currentRevision: currentRevision || 'unknown',
+        remotes: remotes || [],
+        ignorePatterns,
+      },
+      derivedFrom: {
+        fileSets: [
+          {
+            id: 'git-files',
+            name: '.git directory and .gitignore files',
+            patterns: [
+              { type: 'glob', pattern: '.git/**' },
+              { type: 'glob', pattern: '**/.gitignore' },
+            ],
+          },
+        ],
+        derivationType: 'content',
+        description: 'Git version control metadata and ignore patterns',
+      },
+    };
+  }
+
+  /**
+   * Extract all .gitignore patterns from the repository
+   */
+  async extractIgnorePatterns(repositoryRoot: string): Promise<VersionControlIgnorePattern[]> {
+    const patterns: VersionControlIgnorePattern[] = [];
+
+    // Always add .git directory as ignored
+    patterns.push({
+      pattern: '.git',
+      type: 'exact',
+      source: 'implicit',
+      scope: 'repository',
+      negated: false,
+      description: 'Git metadata directory',
+    });
+
+    // Parse root .gitignore
+    const rootGitignorePath = path.join(repositoryRoot, '.gitignore');
+    const rootPatterns = await this.parseGitignoreFile(rootGitignorePath, repositoryRoot);
+    patterns.push(...rootPatterns);
+
+    // Find and parse subdirectory .gitignore files
+    if (this.fileSystemAdapter.readDirectory) {
+      const subdirPatterns = await this.findAndParseGitignoreFiles(repositoryRoot, repositoryRoot);
+      patterns.push(...subdirPatterns);
+    }
+
+    return patterns;
+  }
+
+  /**
+   * Recursively find and parse .gitignore files
+   */
+  private async findAndParseGitignoreFiles(
+    currentPath: string,
+    repositoryRoot: string,
+  ): Promise<VersionControlIgnorePattern[]> {
+    const patterns: VersionControlIgnorePattern[] = [];
+
+    if (!this.fileSystemAdapter.readDirectory) {
+      return patterns;
+    }
+
+    try {
+      const entries = await this.fileSystemAdapter.readDirectory(currentPath);
+
+      for (const entry of entries) {
+        const fullPath = path.join(currentPath, entry);
+
+        // Skip .git directory
+        if (entry === '.git') continue;
+
+        // Check for .gitignore file
+        if (entry === '.gitignore' && currentPath !== repositoryRoot) {
+          const gitignorePatterns = await this.parseGitignoreFile(fullPath, repositoryRoot);
+          patterns.push(...gitignorePatterns);
+        }
+
+        // Recursively check subdirectories
+        if (
+          this.fileSystemAdapter.isDirectory &&
+          (await this.fileSystemAdapter.isDirectory(fullPath))
+        ) {
+          const subdirPatterns = await this.findAndParseGitignoreFiles(fullPath, repositoryRoot);
+          patterns.push(...subdirPatterns);
+        }
+      }
+    } catch (error) {
+      console.warn(`Error reading directory ${currentPath}:`, error);
+    }
+
+    return patterns;
+  }
+
+  /**
+   * Parse a .gitignore file and return patterns using the ignore library
+   */
+  private async parseGitignoreFile(
+    gitignorePath: string,
+    repositoryRoot: string,
+  ): Promise<VersionControlIgnorePattern[]> {
+    const patterns: VersionControlIgnorePattern[] = [];
+
+    try {
+      const result = await this.fileSystemAdapter.readFile(gitignorePath);
+      if (!result) return patterns;
+
+      const content = result.content;
+      const lines = content.split('\n');
+      const relativePath = path.relative(repositoryRoot, path.dirname(gitignorePath));
+      // For root gitignore, use "./" prefix to show it's in the current directory
+      const source = relativePath === '.' ? './.gitignore' : `${relativePath}/.gitignore`;
+
+      // Use ignore library to validate patterns as we process them
+      const ig = ignore();
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+
+        // Skip empty lines and comments
+        if (!trimmed || trimmed.startsWith('#')) continue;
+
+        // Handle negation patterns
+        const negated = trimmed.startsWith('!');
+        const pattern = negated ? trimmed.slice(1) : trimmed;
+
+        // Validate pattern using ignore library
+        try {
+          // Test if the pattern is valid by trying to add it to ignore
+          const testIgnore = ignore();
+          testIgnore.add([trimmed]); // Add the original line (with ! if present)
+
+          // Determine pattern type based on content
+          const hasGlobChars = /[*?[\]]/.test(pattern);
+          const hasSlash = pattern.includes('/');
+          const patternType = hasGlobChars || hasSlash ? 'glob' : 'exact';
+
+          // Determine scope
+          const scope = source === '.gitignore' ? 'repository' : 'directory';
+
+          patterns.push({
+            pattern: pattern,
+            type: patternType,
+            source,
+            scope,
+            negated,
+            description: `From ${source}`,
+          });
+
+          // Add valid patterns to our ignore instance for potential future use
+          ig.add([trimmed]);
+        } catch (err) {
+          console.warn(`Invalid gitignore pattern: ${trimmed} in ${source}`, err);
+        }
+      }
+    } catch (error) {
+      console.warn(`Error reading gitignore file ${gitignorePath}:`, error);
+    }
+
+    return patterns;
+  }
+
+  /**
+   * Create an ignore instance from patterns for efficient filtering
+   * This can be used by FilesystemService or other components
+   */
+  createIgnoreFromPatterns(patterns: VersionControlIgnorePattern[]): Ignore | null {
+    const ig = ignore();
+
+    // Convert patterns back to gitignore format
+    const gitignoreLines = patterns.map(p => (p.negated ? `!${p.pattern}` : p.pattern));
+
+    if (gitignoreLines.length > 0) {
+      ig.add(gitignoreLines);
+    }
+
+    return ig;
+  }
+
+  /**
+   * Get current branch name
+   */
+  async getCurrentBranch(repositoryRoot: string): Promise<string | null> {
+    // First try using GitAdapter if available
+    if (this.gitAdapter?.getCurrentBranch) {
+      try {
+        return await this.gitAdapter.getCurrentBranch(repositoryRoot);
+      } catch (error) {
+        console.warn('Error getting branch via GitAdapter:', error);
+      }
+    }
+
+    // Fallback to reading .git/HEAD file
+    try {
+      const headPath = path.join(repositoryRoot, '.git', 'HEAD');
+      const result = await this.fileSystemAdapter.readFile(headPath);
+      if (!result) return null;
+
+      const content = result.content.trim();
+      if (content.startsWith('ref: refs/heads/')) {
+        return content.replace('ref: refs/heads/', '');
+      }
+
+      // Detached HEAD state
+      return 'HEAD';
+    } catch (error) {
+      console.warn('Error reading .git/HEAD:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Get current commit SHA
+   */
+  async getCurrentRevision(repositoryRoot: string): Promise<string | null> {
+    // First try using GitAdapter if available
+    if (this.gitAdapter?.getCurrentCommit) {
+      try {
+        return await this.gitAdapter.getCurrentCommit(repositoryRoot);
+      } catch (error) {
+        console.warn('Error getting commit via GitAdapter:', error);
+      }
+    }
+
+    // Fallback to reading from .git files
+    try {
+      const headPath = path.join(repositoryRoot, '.git', 'HEAD');
+      const headResult = await this.fileSystemAdapter.readFile(headPath);
+      if (!headResult) return null;
+
+      const headContent = headResult.content.trim();
+
+      // If HEAD points to a ref, read that ref
+      if (headContent.startsWith('ref: ')) {
+        const ref = headContent.replace('ref: ', '');
+        const refPath = path.join(repositoryRoot, '.git', ref);
+        const refResult = await this.fileSystemAdapter.readFile(refPath);
+        if (refResult) {
+          return refResult.content.trim().substring(0, 7); // Short SHA
+        }
+      } else {
+        // Direct commit SHA in HEAD (detached state)
+        return headContent.substring(0, 7);
+      }
+    } catch (error) {
+      console.warn('Error reading git revision:', error);
+    }
+
+    return null;
+  }
+
+  /**
+   * Get remote repositories
+   */
+  async getRemotes(
+    repositoryRoot: string,
+  ): Promise<Array<{ name: string; url: string; type: 'push' | 'fetch' | 'both' }>> {
+    // First try using GitAdapter if available
+    if (this.gitAdapter?.getRemotes) {
+      try {
+        const remotes = await this.gitAdapter.getRemotes(repositoryRoot);
+        // Ensure all remotes have a type, default to 'both' if not specified
+        return remotes.map(remote => ({
+          name: remote.name,
+          url: remote.url,
+          type: remote.type || 'both',
+        }));
+      } catch (error) {
+        console.warn('Error getting remotes via GitAdapter:', error);
+      }
+    }
+
+    // Fallback to reading .git/config file
+    try {
+      const configPath = path.join(repositoryRoot, '.git', 'config');
+      const result = await this.fileSystemAdapter.readFile(configPath);
+      if (!result) return [];
+
+      const remotes: Array<{ name: string; url: string; type: 'push' | 'fetch' | 'both' }> = [];
+      const lines = result.content.split('\n');
+      let currentRemote: string | null = null;
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+
+        // Check for remote section
+        const remoteMatch = trimmed.match(/^\[remote "(.+)"\]$/);
+        if (remoteMatch) {
+          currentRemote = remoteMatch[1];
+          continue;
+        }
+
+        // Extract URL for current remote
+        if (currentRemote && trimmed.startsWith('url = ')) {
+          const url = trimmed.replace('url = ', '');
+          // Git remotes are typically used for both fetch and push unless specified otherwise
+          remotes.push({ name: currentRemote, url, type: 'both' });
+          currentRemote = null;
+        }
+      }
+
+      return remotes;
+    } catch (error) {
+      console.warn('Error reading .git/config:', error);
+      return [];
+    }
+  }
+}

package/src/providers/PackageManagerApiProvider.ts

@@ -0,0 +1,108 @@
+/**
+ * Package management API provider for checking versions, vulnerabilities, and licenses
+ */
+
+export type PackageManager = 'npm' | 'pnpm' | 'yarn';
+
+export interface PackageVersionInfo {
+  name: string;
+  currentVersion: string;
+}
+
+export interface VersionCheckResult {
+  packageName: string;
+  currentVersion: string;
+  latestVersion?: string;
+  updateType?: 'major' | 'minor' | 'patch' | 'none';
+  isOutdated: boolean;
+  isDeprecated?: boolean;
+  deprecationMessage?: string;
+  error?: string;
+}
+
+export interface VulnerabilityInfo {
+  id: string;
+  severity: 'low' | 'moderate' | 'high' | 'critical';
+  title: string;
+  description?: string;
+  fixAvailable?: boolean;
+}
+
+export interface VulnerabilityCheckResult {
+  packageName: string;
+  version: string;
+  vulnerabilities: VulnerabilityInfo[];
+  error?: string;
+}
+
+export interface LicenseInfo {
+  license: string;
+  licenseType: 'permissive' | 'copyleft' | 'proprietary' | 'unknown';
+  requiresAttribution: boolean;
+  requiresShareAlike: boolean;
+  allowsCommercialUse: boolean;
+}
+
+export interface LicenseCheckResult {
+  packageName: string;
+  version: string;
+  license?: LicenseInfo;
+  error?: string;
+}
+
+export interface DependencyCheckProgress {
+  phase:
+    | 'idle'
+    | 'counting'
+    | 'checking-versions'
+    | 'checking-vulnerabilities'
+    | 'checking-licenses'
+    | 'complete';
+  current: number;
+  total: number;
+  message?: string;
+}
+
+export interface BatchCheckOptions {
+  batchSize?: number; // How many packages to check at once
+  maxConcurrent?: number; // Max concurrent API calls
+  skipCache?: boolean; // Force fresh checks
+}
+
+/**
+ * Abstract provider for package manager API operations
+ * Implementations can use direct API calls, server proxies, or mock data
+ */
+export abstract class PackageManagerApiProvider {
+  /**
+   * Check versions for multiple packages, yielding results as they complete
+   */
+  abstract checkVersions(
+    packages: PackageVersionInfo[],
+    packageManager: PackageManager,
+    options?: BatchCheckOptions,
+  ): AsyncGenerator<VersionCheckResult, void, unknown>;
+
+  /**
+   * Check vulnerabilities for multiple packages, yielding results as they complete
+   */
+  abstract checkVulnerabilities(
+    packages: PackageVersionInfo[],
+    packageManager: PackageManager,
+    options?: BatchCheckOptions,
+  ): AsyncGenerator<VulnerabilityCheckResult, void, unknown>;
+
+  /**
+   * Check licenses for multiple packages, yielding results as they complete
+   */
+  abstract checkLicenses(
+    packages: PackageVersionInfo[],
+    packageManager: PackageManager,
+    options?: BatchCheckOptions,
+  ): AsyncGenerator<LicenseCheckResult, void, unknown>;
+
+  /**
+   * Get overall progress of the current check operation
+   */
+  abstract getProgress(): DependencyCheckProgress;
+}

package/src/providers/README.md

@@ -0,0 +1,88 @@
+# Layer Providers
+
+This directory contains provider implementations for the layer system.
+
+## GitVersionControlProvider
+
+A Git implementation of the `VersionControlProvider` interface that:
+
+- Detects Git repositories by looking for `.git` directories
+- Parses `.gitignore` files throughout the repository
+- Extracts branch, commit, and remote information
+- Creates `VersionControlLayer` objects with Git metadata
+
+### Usage with Electron-React
+
+```typescript
+import {
+  VersionControlLayerFactory,
+  GitVersionControlProvider,
+  FileSystemModule,
+} from 'core/layers';
+import { ElectronPlatformAdapters } from '../adapters';
+
+// Use electron's existing adapters
+const adapters = new ElectronPlatformAdapters();
+
+// Create Git provider using electron's adapters
+const gitProvider = new GitVersionControlProvider(
+  adapters.fileSystem, // ElectronFileSystemAdapter
+  adapters.git, // ElectronGitAdapter (optional)
+);
+
+// Register with factory
+const vcsFactory = new VersionControlLayerFactory();
+vcsFactory.registerProvider('git', gitProvider);
+
+// Use in FileSystemModule
+const fsModule = new FileSystemModule({
+  directoryPath: '/path/to/repo',
+  buildFileSystemTree: async (path, filters) => {
+    // ... your implementation
+  },
+  versionControlLayerFactory: vcsFactory,
+});
+
+// Load filesystem with VCS awareness
+const result = await fsModule.loadFileSystemTree();
+// result.versionControlLayer will contain Git metadata
+```
+
+### Adapter Requirements
+
+The `GitVersionControlProvider` requires a `FileSystemAdapter` with these methods:
+
+- `readFile(path)` - Read file contents
+- `fileExists(path)` - Check if file exists (optional)
+- `isDirectory(path)` - Check if path is directory (optional)
+- `readDirectory(path)` - List directory contents (optional)
+
+Optionally, you can provide a `GitAdapter` for more accurate Git operations:
+
+- `getCurrentBranch(repoPath)` - Get current branch name
+- `getCurrentCommit(repoPath)` - Get current commit SHA
+- `getRemotes(repoPath)` - Get remote repositories
+- `getStatus(repoPath)` - Get working tree status
+
+### Features
+
+- **Repository Detection**: Walks up directory tree to find `.git` directory
+- **Ignore Pattern Parsing**: Recursively finds and parses all `.gitignore` files
+- **Pattern Types**: Supports glob, exact, and regex patterns
+- **Pattern Scopes**: Repository-wide or directory-specific patterns
+- **Negation Support**: Handles `!` negation patterns in `.gitignore`
+- **Fallback Logic**: Falls back to file reading when Git adapter not available
+
+### Integration with Shared-Lib
+
+This provider is compatible with the same interfaces used by `markdown-slides-shared-lib/workspace`,
+making it easy to migrate from shared-lib's `GitVersionControlProvider` to this one:
+
+```typescript
+// Before (using shared-lib)
+import { GitVersionControlProvider } from 'markdown-slides-shared-lib/workspace';
+
+// After (using core)
+import { GitVersionControlProvider } from 'core/layers';
+// Same usage, same interface!
+```