@crossplatformai/dependency-graph 0.9.2

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2024-2026 CrossPlatform.ai. All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying, distribution,
+modification, or use of this software, via any medium, is strictly prohibited
+without the express written permission of CrossPlatform.ai.
+
+For licensing inquiries, contact: legal@crossplatform.ai

package/README.md

@@ -0,0 +1,204 @@
+# @repo/dependency-graph
+
+Shared utility plugin for workspace dependency graph analysis. Provides workspace discovery, graph building, traversal, and analysis utilities.
+
+## Zero Dependencies
+
+This plugin follows the **zero dependencies** pattern. It defines interfaces for external services (`FileSystemClient`, `GlobClient`, `YamlClient`) and accepts implementations via dependency injection.
+
+## Installation
+
+```bash
+pnpm add @repo/dependency-graph
+```
+
+## Usage
+
+### Discovering Workspaces
+
+```typescript
+import { discoverWorkspaces } from '@repo/dependency-graph';
+import { readFile } from 'node:fs/promises';
+import { glob } from 'glob';
+import { parse } from 'yaml';
+
+const packages = await discoverWorkspaces(process.cwd(), {
+  fs: {
+    readFile: async (path, encoding) => readFile(path, encoding),
+    exists: async (path) => {
+      try {
+        await readFile(path);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  },
+  glob: {
+    glob: async (pattern, options) => glob(pattern, options),
+  },
+  yaml: {
+    parse: (content) => parse(content),
+  },
+});
+```
+
+### Building Dependency Graph
+
+```typescript
+import { buildDependencyGraph } from '@repo/dependency-graph';
+
+const graph = buildDependencyGraph(packages);
+```
+
+### Finding Affected Packages
+
+```typescript
+import { findAffectedPackages } from '@repo/dependency-graph';
+
+const affected = findAffectedPackages(
+  graph,
+  'my-package',
+  { includeSelf: true }
+);
+```
+
+### Detecting Cycles
+
+```typescript
+import { detectCycles } from '@repo/dependency-graph';
+
+const cycles = detectCycles(graph);
+if (cycles.length > 0) {
+  console.error('Circular dependencies detected:', cycles);
+}
+```
+
+### Mapping Files to Packages
+
+```typescript
+import { mapFilesToPackages } from '@repo/dependency-graph';
+
+const changedFiles = ['apps/web/src/index.ts', 'packages/ui/src/button.tsx'];
+const fileMap = mapFilesToPackages(changedFiles, packages);
+
+console.log(fileMap);
+// Map { 'web' => ['apps/web/src/index.ts'], '@repo/shared' => ['packages/ui/src/button.tsx'] }
+```
+
+## API
+
+### Types
+
+- `WorkspacePackage` - Package metadata from package.json
+- `DependencyGraph` - Graph representation of package dependencies
+- `DependencyNode` - Node in the dependency graph
+- `GraphStats` - Statistics about the dependency graph
+
+### Client Interfaces (Dependency Injection)
+
+- `FileSystemClient` - File system operations interface
+- `GlobClient` - Glob pattern matching interface
+- `YamlClient` - YAML parsing interface
+
+### Functions
+
+#### Workspace Discovery
+
+- `discoverWorkspaces(rootDir, config)` - Discover all workspace packages
+
+#### Graph Building
+
+- `buildDependencyGraph(packages)` - Build dependency graph from packages
+
+#### Graph Traversal
+
+- `findAffectedPackages(graph, packageName, options)` - Find all packages affected by changes
+- `findDependencyPath(graph, from, to)` - Find shortest path between packages
+- `findAllPaths(graph, from, to)` - Find all paths between packages
+
+#### Graph Analysis
+
+- `analyzeGraph(graph)` - Get comprehensive graph statistics
+- `detectCycles(graph)` - Detect circular dependencies
+- `getTransitiveDependencies(graph, packageName)` - Get all transitive dependencies
+- `getTransitiveDependents(graph, packageName)` - Get all transitive dependents
+
+#### File Mapping
+
+- `findPackageForFile(filePath, packages)` - Find which package owns a file
+- `mapFilesToPackages(files, packages)` - Map array of files to their packages
+
+## Dependency Injection Pattern
+
+This plugin requires clients to be provided by the host application:
+
+```typescript
+import type { WorkspaceDiscoveryConfig } from '@repo/dependency-graph';
+import { readFile } from 'node:fs/promises';
+import { glob } from 'glob';
+import { parse as parseYaml } from 'yaml';
+
+// Create config with real implementations
+const config: WorkspaceDiscoveryConfig = {
+  fs: {
+    readFile: (path, encoding) => readFile(path, encoding),
+    exists: async (path) => {
+      try {
+        await readFile(path);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  },
+  glob: {
+    glob: (pattern, options) => glob(pattern, options),
+  },
+  yaml: {
+    parse: (content) => parseYaml(content),
+  },
+};
+
+// Use with dependency injection
+const packages = await discoverWorkspaces(process.cwd(), config);
+```
+
+## Testing
+
+For testing, provide mock implementations:
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+
+const mockConfig = {
+  fs: {
+    readFile: vi.fn(),
+    exists: vi.fn(),
+  },
+  glob: {
+    glob: vi.fn(),
+  },
+  yaml: {
+    parse: vi.fn(),
+  },
+};
+
+// Mock implementations
+mockConfig.fs.readFile.mockResolvedValue('{}');
+mockConfig.glob.glob.mockResolvedValue(['apps/web', 'packages/ui']);
+mockConfig.yaml.parse.mockReturnValue({ packages: ['apps/*', 'packages/*'] });
+
+const packages = await discoverWorkspaces('/fake/root', mockConfig);
+```
+
+## Why Zero Dependencies?
+
+- **Flexibility**: Use any file system, glob, or YAML library
+- **Version Control**: Host controls all dependency versions
+- **Testing**: Easy to mock with simple interfaces
+- **Reusability**: Works across different environments (Node.js, Bun, Deno, etc.)
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@crossplatformai/dependency-graph",
+  "description": "Shared dependency graph plugin for CrossPlatform.ai projects",
+  "version": "0.9.2",
+  "private": false,
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crossplatformai/dependency-graph.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit --skipLibCheck",
+    "format": "prettier --write \"src/**/*.ts\" \"*.json\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"*.json\"",
+    "lint": "eslint . --cache --fix --max-warnings 0",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "publish:next": "npm publish --tag next",
+    "publish:production": "npm publish --tag latest"
+  },
+  "dependencies": {
+    "glob": "^11.0.1",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@crossplatformai/prettier-config": "^0.0.2",
+    "@crossplatformai/typescript-config": "^0.6.3",
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^22.13.0",
+    "eslint": "^9.21.0",
+    "eslint-config-prettier": "^10.0.0",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-prettier": "^5.2.1",
+    "globals": "^15.13.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.18.0",
+    "vitest": "^3.0.6"
+  },
+  "prettier": "@crossplatformai/prettier-config",
+  "packageManager": "pnpm@10.29.3+sha512.498e1fb4cca5aa06c1dcf2611e6fafc50972ffe7189998c409e90de74566444298ffe43e6cd2acdc775ba1aa7cc5e092a8b7054c811ba8c5770f84693d33d2dc"
+}

package/src/cli/pr-preview.ts

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { glob } from 'glob';
+import { parse as parseYaml } from 'yaml';
+
+// Import dependency graph functions from parent module
+import {
+  discoverWorkspaces,
+  buildDependencyGraph,
+  findAffectedPackages,
+  type WorkspacePackage,
+} from '../index.js';
+
+interface ChangedFile {
+  path: string;
+  status: 'modified' | 'added' | 'deleted';
+}
+
+interface DeploymentIndicator {
+  file?: string;
+  field?: string;
+  dependency?: string;
+}
+
+interface PlatformDetection {
+  platform: string;
+  indicators: DeploymentIndicator[];
+}
+
+const WORKFLOW_MAPPING: Record<string, string> = {
+  'deploy-web.yml': 'web',
+  'deploy-api-origin.yml': 'api-origin',
+  'deploy-api-edge.yml': 'api-edge',
+  'release-mobile.yml': 'mobile',
+  'release-desktop.yml': 'desktop',
+  'release-cli.yml': 'cli',
+};
+
+// Convention-based deployment detection (order matters - most specific first)
+const PLATFORM_INDICATORS: PlatformDetection[] = [
+  {
+    platform: 'cloudflare-workers',
+    indicators: [{ file: 'wrangler.toml' }],
+  },
+  {
+    platform: 'expo',
+    indicators: [{ file: 'app.json' }, { file: 'eas.json' }],
+  },
+  {
+    platform: 'npm-package',
+    indicators: [{ field: 'bin' }],
+  },
+  {
+    platform: 'electron',
+    indicators: [
+      { dependency: 'electron' },
+      { dependency: 'electron-builder' },
+    ],
+  },
+  {
+    platform: 'next.js',
+    indicators: [
+      { file: 'next.config.js' },
+      { file: 'next.config.mjs' },
+      { file: 'next.config.ts' },
+      { dependency: 'next' },
+    ],
+  },
+  {
+    platform: 'node.js',
+    indicators: [
+      { field: 'start' }, // has start script
+    ],
+  },
+];
+
+const DEFAULT_APP_DIRECTORIES = ['apps'];
+
+function isDeployableApp(pkg: WorkspacePackage): {
+  deployable: boolean;
+  platform?: string;
+} {
+  // Check if package is in apps directory (configurable in future)
+  const isInAppDirectory = DEFAULT_APP_DIRECTORIES.some(
+    (dir) => pkg.path.includes(`/${dir}/`) || pkg.path.endsWith(`/${dir}`),
+  );
+
+  if (!isInAppDirectory) {
+    return { deployable: false };
+  }
+
+  // Detect platform based on indicators
+  for (const platformDetection of PLATFORM_INDICATORS) {
+    const hasIndicators = platformDetection.indicators.some((indicator) => {
+      if (indicator.file) {
+        try {
+          const filePath = resolve(pkg.path, indicator.file);
+          readFileSync(filePath, 'utf-8');
+          return true;
+        } catch {
+          return false;
+        }
+      }
+
+      if (indicator.field) {
+        const scripts = pkg.packageJson.scripts as
+          | Record<string, string>
+          | undefined;
+        if (indicator.field === 'start' && scripts?.start) {
+          return true;
+        }
+        const packageJsonField =
+          pkg.packageJson[indicator.field as keyof typeof pkg.packageJson];
+        if (indicator.field !== 'start' && packageJsonField) {
+          return true;
+        }
+      }
+
+      if (indicator.dependency) {
+        return !!(
+          pkg.dependencies[indicator.dependency] ||
+          pkg.devDependencies[indicator.dependency]
+        );
+      }
+
+      return false;
+    });
+
+    if (hasIndicators) {
+      return { deployable: true, platform: platformDetection.platform };
+    }
+  }
+
+  // If in apps directory but no specific platform detected, not deployable
+  return { deployable: false };
+}
+
+async function getChangedFiles(): Promise<ChangedFile[]> {
+  const { execSync } = await import('node:child_process');
+
+  try {
+    // Try local production first, then fall back to origin/production
+    let baseBranch = 'production';
+    try {
+      execSync('git rev-parse production', {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+      });
+    } catch {
+      baseBranch = 'origin/production';
+    }
+
+    const output = execSync(`git diff --name-status ${baseBranch}...HEAD`, {
+      encoding: 'utf-8',
+    });
+
+    return output
+      .trim()
+      .split('\n')
+      .filter((line) => line)
+      .map((line) => {
+        const [status, path] = line.split('\t');
+
+        return {
+          path: path ?? '',
+          status:
+            status === 'D' ? 'deleted' : status === 'A' ? 'added' : 'modified',
+        };
+      })
+      .filter((file): file is ChangedFile => file.path !== '');
+  } catch {
+    console.error(
+      'Failed to get changed files. Ensure you are on a branch with commits compared to production.',
+    );
+    process.exit(1);
+  }
+}
+
+async function main() {
+  try {
+    const rootDir = resolve(process.cwd());
+    const changedFiles = await getChangedFiles();
+
+    console.log(
+      `\n📦 Release Preview - Changed Files: ${changedFiles.length}\n`,
+    );
+
+    changedFiles.forEach((file) => {
+      console.log(`  ${file.status === 'deleted' ? '❌' : '📝'} ${file.path}`);
+    });
+
+    const packages = await discoverWorkspaces(rootDir, {
+      fs: {
+        readFile: (path) => {
+          try {
+            return Promise.resolve(readFileSync(path, 'utf-8'));
+          } catch {
+            return Promise.reject(new Error(`Failed to read file: ${path}`));
+          }
+        },
+        exists: (path) => {
+          try {
+            readFileSync(path, 'utf-8');
+            return Promise.resolve(true);
+          } catch {
+            return Promise.resolve(false);
+          }
+        },
+      },
+      glob: {
+        glob: async (pattern, options) => glob(pattern, options),
+      },
+      yaml: {
+        parse: (content) => parseYaml(content) as Record<string, unknown>,
+      },
+    });
+
+    const graph = buildDependencyGraph(packages);
+    const changedPackages = new Set<string>();
+
+    for (const file of changedFiles) {
+      if (file.status === 'deleted') continue;
+
+      // Convert absolute package paths to relative for comparison
+      const pkg = packages.find((p) => {
+        const relativePkgPath = p.path.replace(rootDir + '/', '');
+        return file.path.startsWith(relativePkgPath);
+      });
+
+      if (pkg) {
+        changedPackages.add(pkg.name);
+      }
+    }
+
+    const changedWorkflows = changedFiles.filter((f) =>
+      f.path.startsWith('.github/workflows/'),
+    );
+
+    const workflowAffectedApps = new Set<string>();
+    for (const workflow of changedWorkflows) {
+      const workflowName = workflow.path.split('/').pop();
+      if (workflowName && WORKFLOW_MAPPING[workflowName]) {
+        workflowAffectedApps.add(WORKFLOW_MAPPING[workflowName]);
+      }
+    }
+
+    console.log(
+      `\n📦 Changed packages: ${Array.from(changedPackages).join(', ') || 'none'}\n`,
+    );
+
+    if (changedPackages.size === 0) {
+      console.log('\n✨ No packages changed - no deployments needed\n');
+      return;
+    }
+
+    const affected = findAffectedPackages(changedPackages, graph, {
+      direction: 'upstream',
+      respectAffectsUpstream: true,
+    });
+
+    // Find all deployable apps (affected and unaffected)
+    const allDeployableApps = packages
+      .map((pkg) => {
+        const detection = isDeployableApp(pkg);
+        return detection.deployable
+          ? { name: pkg.name, pkg, platform: detection.platform }
+          : null;
+      })
+      .filter(
+        (
+          item,
+        ): item is {
+          name: string;
+          pkg: WorkspacePackage;
+          platform: string | undefined;
+        } => item !== null,
+      );
+
+    // Categorize apps by deployment type
+    const affectedApps = allDeployableApps.filter(
+      (app): app is NonNullable<typeof app> =>
+        affected.has(app.name) || workflowAffectedApps.has(app.name),
+    );
+    const unaffectedApps = allDeployableApps.filter(
+      (app): app is NonNullable<typeof app> =>
+        !affected.has(app.name) && !workflowAffectedApps.has(app.name),
+    );
+
+    // Separate deploys (web-based) vs releases (installed)
+    const getAppCategory = (platform?: string) => {
+      switch (platform) {
+        case 'next.js':
+        case 'cloudflare-workers':
+        case 'node.js':
+          return 'deploy';
+        case 'expo':
+        case 'electron':
+        case 'npm-package':
+          return 'release';
+        default:
+          return 'deploy'; // default to deploy for generic
+      }
+    };
+
+    const getAppIcon = (platform?: string) => {
+      switch (platform) {
+        case 'next.js':
+        case 'cloudflare-workers':
+        case 'node.js':
+          return '🌐';
+        case 'expo':
+          return '📱';
+        case 'electron':
+          return '🖥️';
+        case 'npm-package':
+          return '⚡';
+        default:
+          return '🌐';
+      }
+    };
+
+    const affectedDeploys = affectedApps.filter(
+      (app): app is NonNullable<typeof app> =>
+        getAppCategory(app.platform) === 'deploy',
+    );
+    const affectedReleases = affectedApps.filter(
+      (app): app is NonNullable<typeof app> =>
+        getAppCategory(app.platform) === 'release',
+    );
+
+    console.log(`\n🚀 PR Preview\n`);
+
+    if (affectedApps.length === 0) {
+      console.log('No apps affected by changes.\n');
+    } else {
+      if (affectedDeploys.length > 0) {
+        console.log('📋 Apps that will be DEPLOYED:');
+        for (const item of affectedDeploys) {
+          const platformDisplay =
+            item.platform === 'generic' ? '' : ` (${item.platform})`;
+          const icon = getAppIcon(item.platform);
+          console.log(`${icon} ${item.name}${platformDisplay}`);
+        }
+        console.log('');
+      }
+
+      if (affectedReleases.length > 0) {
+        console.log('📋 Apps that will be RELEASED:');
+        for (const item of affectedReleases) {
+          const platformDisplay =
+            item.platform === 'generic' ? '' : ` (${item.platform})`;
+          const icon = getAppIcon(item.platform);
+          console.log(`${icon} ${item.name}${platformDisplay}`);
+        }
+        console.log('');
+      }
+    }
+
+    if (unaffectedApps.length > 0) {
+      console.log(`📋 Apps that will NOT be affected:`);
+      for (const item of unaffectedApps) {
+        const platformDisplay =
+          item.platform === 'generic' ? '' : ` (${item.platform})`;
+        console.log(`⏭️ ${item.name}${platformDisplay}`);
+      }
+      console.log('');
+    }
+
+    console.log(`Legend:`);
+    console.log(`🌐 = Deploy (web-based, instant updates)`);
+    console.log(`📱 = Release (mobile app, user installs)`);
+    console.log(`🖥️ = Release (desktop app, user installs)`);
+    console.log(`⚡ = Release (CLI tool, user installs)`);
+    console.log(`⏭️ = Unaffected (no changes needed)`);
+    console.log(`📝 = File changed`);
+    console.log(`❌ = File deleted\n`);
+  } catch (error) {
+    console.error(
+      'Error:',
+      error instanceof Error ? error.message : String(error),
+    );
+    process.exit(1);
+  }
+}
+
+void main();