@grafema/core 0.1.0-alpha.5 → 0.2.0-beta

package/src/plugins/discovery/WorkspaceDiscovery.ts

@@ -0,0 +1,184 @@
+/**
+ * WorkspaceDiscovery - Discovery plugin for npm/pnpm/yarn/lerna workspaces
+ *
+ * Detects workspace configuration and creates SERVICE nodes for each package.
+ * Priority: 110 (higher than MonorepoServiceDiscovery at 100)
+ *
+ * Supports:
+ * - pnpm-workspace.yaml
+ * - package.json workspaces (npm/yarn)
+ * - lerna.json
+ */
+
+import { join } from 'path';
+
+import { DiscoveryPlugin } from './DiscoveryPlugin.js';
+import { createSuccessResult, createErrorResult } from '../Plugin.js';
+import type { PluginContext, PluginResult, PluginMetadata } from '../Plugin.js';
+import { detectWorkspaceType } from './workspaces/detector.js';
+import { parsePnpmWorkspace, parseNpmWorkspace, parseLernaConfig } from './workspaces/parsers.js';
+import { resolveWorkspacePackages, type WorkspacePackage } from './workspaces/globResolver.js';
+import { NodeFactory } from '../../core/NodeFactory.js';
+import { resolveSourceEntrypoint } from './resolveSourceEntrypoint.js';
+
+/**
+ * Service info returned in result metadata
+ */
+interface ServiceInfo {
+  id: string;
+  name: string;
+  path: string;
+  type: string;
+  metadata: {
+    workspaceType: string;
+    relativePath: string;
+    entrypoint: string | null;
+    packageJson: Record<string, unknown>;
+  };
+}
+
+export class WorkspaceDiscovery extends DiscoveryPlugin {
+  get metadata(): PluginMetadata {
+    return {
+      name: 'WorkspaceDiscovery',
+      phase: 'DISCOVERY',
+      priority: 110, // Higher than MonorepoServiceDiscovery (100)
+      creates: {
+        nodes: ['SERVICE'],
+        edges: []
+      },
+      dependencies: []
+    };
+  }
+
+  async execute(context: PluginContext): Promise<PluginResult> {
+    const logger = this.log(context);
+    const { projectPath, graph } = context;
+
+    // Validate projectPath
+    if (!projectPath) {
+      return createErrorResult(new Error('projectPath is required'));
+    }
+
+    logger.debug('Detecting workspace type', { projectPath });
+
+    // Step 1: Detect workspace type
+    const detection = detectWorkspaceType(projectPath);
+
+    if (!detection.type) {
+      logger.debug('Not a workspace project, skipping');
+      return createSuccessResult({ nodes: 0, edges: 0 }, {
+        services: [],
+        skipped: true,
+        reason: 'No workspace configuration found'
+      });
+    }
+
+    logger.info('Workspace detected', {
+      type: detection.type,
+      configPath: detection.configPath
+    });
+
+    // Step 2: Parse workspace configuration
+    let config;
+    try {
+      switch (detection.type) {
+        case 'pnpm':
+          config = parsePnpmWorkspace(detection.configPath!);
+          break;
+        case 'npm':
+        case 'yarn':
+          config = parseNpmWorkspace(detection.configPath!);
+          break;
+        case 'lerna':
+          config = parseLernaConfig(detection.configPath!);
+          break;
+        default:
+          throw new Error(`Unknown workspace type: ${detection.type}`);
+      }
+    } catch (error) {
+      return createErrorResult(error as Error);
+    }
+
+    logger.debug('Workspace config parsed', {
+      patterns: config.patterns,
+      negativePatterns: config.negativePatterns
+    });
+
+    // Step 3: Resolve patterns to packages
+    const packages = resolveWorkspacePackages(projectPath, config);
+
+    logger.info('Workspace packages resolved', { count: packages.length });
+
+    // Step 4: Create SERVICE nodes
+    const services: ServiceInfo[] = [];
+
+    for (const pkg of packages) {
+      const serviceNode = this.createServiceNode(pkg, detection.type!, projectPath);
+
+      await graph.addNode(serviceNode);
+
+      services.push({
+        id: serviceNode.id,
+        name: pkg.name,
+        path: pkg.path,
+        type: 'workspace-package',
+        metadata: {
+          workspaceType: detection.type!,
+          relativePath: pkg.relativePath,
+          entrypoint: (serviceNode.metadata?.entrypoint as string | null) ?? null,
+          packageJson: pkg.packageJson as Record<string, unknown>
+        }
+      });
+    }
+
+    logger.info('Services created from workspace', {
+      count: services.length,
+      workspaceType: detection.type
+    });
+
+    return createSuccessResult(
+      { nodes: services.length, edges: 0 },
+      { services, workspaceType: detection.type }
+    );
+  }
+
+  /**
+   * Create SERVICE node from workspace package.
+   */
+  private createServiceNode(pkg: WorkspacePackage, workspaceType: string, _projectPath: string) {
+    // Resolve entrypoint (prefer TypeScript source)
+    const relativeEntrypoint = resolveSourceEntrypoint(pkg.path, pkg.packageJson)
+      ?? (pkg.packageJson.main as string | undefined)
+      ?? null;
+
+    // Convert to absolute path (REG-247: JSModuleIndexer expects absolute paths)
+    const absoluteEntrypoint = relativeEntrypoint
+      ? join(pkg.path, relativeEntrypoint)
+      : null;
+
+    const serviceNode = NodeFactory.createService(pkg.name, pkg.path, {
+      discoveryMethod: 'workspace',
+      entrypoint: absoluteEntrypoint ?? undefined,
+      version: pkg.packageJson.version as string | undefined,
+      description: pkg.packageJson.description as string | undefined,
+      dependencies: Object.keys(pkg.packageJson.dependencies || {})
+    });
+
+    // Add metadata for workspace-specific information
+    // BaseNodeRecord supports optional metadata field
+    const nodeWithMetadata = serviceNode as typeof serviceNode & { metadata: Record<string, unknown> };
+    nodeWithMetadata.metadata = {
+      workspaceType,
+      discoveryMethod: 'workspace',
+      relativePath: pkg.relativePath,
+      version: pkg.packageJson.version as string | undefined,
+      description: pkg.packageJson.description as string | undefined,
+      private: pkg.packageJson.private as boolean | undefined,
+      dependencies: Object.keys(pkg.packageJson.dependencies || {}),
+      entrypoint: absoluteEntrypoint
+    };
+
+    return nodeWithMetadata;
+  }
+}

package/src/plugins/discovery/resolveSourceEntrypoint.ts

@@ -0,0 +1,103 @@
+/**
+ * Resolves TypeScript source entrypoints for projects.
+ *
+ * This utility prefers TypeScript source files (src/index.ts) over compiled
+ * output (dist/index.js) when analyzing TypeScript projects.
+ *
+ * Resolution order:
+ * 1. If no tsconfig.json exists -> return null (not a TypeScript project)
+ * 2. Check package.json "source" field (explicit source declaration)
+ * 3. Try standard TypeScript source candidates
+ * 4. Return null if no source found (caller should fallback to main)
+ *
+ * @module resolveSourceEntrypoint
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Package.json fields relevant for source resolution
+ */
+export interface PackageJsonForResolution {
+  main?: string;
+  source?: string;  // Used by bundlers like Parcel
+}
+
+/**
+ * Standard TypeScript source candidates in priority order.
+ *
+ * Order rationale:
+ * - src/ is the most common convention
+ * - lib/ is used by some projects
+ * - root-level is fallback
+ * - index is more common than main
+ * - .ts preferred over .tsx over .mts
+ */
+const TS_SOURCE_CANDIDATES = [
+  'src/index.ts',
+  'src/index.tsx',
+  'src/index.mts',
+  'src/main.ts',
+  'src/main.tsx',
+  'lib/index.ts',
+  'lib/index.tsx',
+  'index.ts',
+  'index.tsx',
+  'index.mts',
+  'main.ts',
+  'main.tsx',
+] as const;
+
+/**
+ * Resolves the source entrypoint for a project, preferring TypeScript source
+ * over compiled output.
+ *
+ * @param projectPath - Absolute path to the project/service directory
+ * @param packageJson - Parsed package.json content (only relevant fields needed)
+ * @returns Source entrypoint relative to projectPath, or null if not found
+ *
+ * @example
+ * // TypeScript project with src/index.ts
+ * resolveSourceEntrypoint('/path/to/project', { main: 'dist/index.js' })
+ * // Returns: 'src/index.ts'
+ *
+ * @example
+ * // JavaScript project (no tsconfig.json)
+ * resolveSourceEntrypoint('/path/to/project', { main: 'index.js' })
+ * // Returns: null
+ *
+ * @example
+ * // TypeScript project with explicit source field
+ * resolveSourceEntrypoint('/path/to/project', { main: 'dist/index.js', source: 'lib/entry.ts' })
+ * // Returns: 'lib/entry.ts' (if file exists)
+ */
+export function resolveSourceEntrypoint(
+  projectPath: string,
+  packageJson: PackageJsonForResolution
+): string | null {
+  // Step 1: Check for TypeScript project indicator
+  const tsconfigPath = join(projectPath, 'tsconfig.json');
+  if (!existsSync(tsconfigPath)) {
+    return null; // Not a TypeScript project
+  }
+
+  // Step 2: Check package.json "source" field (explicit source declaration)
+  if (packageJson.source) {
+    const sourcePath = join(projectPath, packageJson.source);
+    if (existsSync(sourcePath)) {
+      return packageJson.source;
+    }
+  }
+
+  // Step 3: Try standard TypeScript source candidates
+  for (const candidate of TS_SOURCE_CANDIDATES) {
+    const candidatePath = join(projectPath, candidate);
+    if (existsSync(candidatePath)) {
+      return candidate;
+    }
+  }
+
+  // Step 4: Not found - caller should fallback to main
+  return null;
+}

package/src/plugins/discovery/workspaces/detector.ts

@@ -0,0 +1,63 @@
+/**
+ * Workspace Type Detector
+ *
+ * Detects which workspace system is used in a project by checking
+ * for configuration files in priority order: pnpm > npm/yarn > lerna.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+export type WorkspaceType = 'pnpm' | 'npm' | 'yarn' | 'lerna' | null;
+
+export interface WorkspaceDetectionResult {
+  type: WorkspaceType;
+  configPath: string | null;
+  rootPath: string;
+}
+
+/**
+ * Detect workspace type by checking for configuration files.
+ * Priority: pnpm > npm/yarn > lerna (most specific first)
+ *
+ * @param projectPath - Root directory of the project
+ * @returns Detection result with type, config path, and root path
+ */
+export function detectWorkspaceType(projectPath: string): WorkspaceDetectionResult {
+  // 1. Check for pnpm-workspace.yaml (highest priority)
+  const pnpmYaml = join(projectPath, 'pnpm-workspace.yaml');
+  const pnpmYml = join(projectPath, 'pnpm-workspace.yml');
+
+  if (existsSync(pnpmYaml)) {
+    return { type: 'pnpm', configPath: pnpmYaml, rootPath: projectPath };
+  }
+  if (existsSync(pnpmYml)) {
+    return { type: 'pnpm', configPath: pnpmYml, rootPath: projectPath };
+  }
+
+  // 2. Check for npm/yarn workspaces in package.json
+  const packageJsonPath = join(projectPath, 'package.json');
+  if (existsSync(packageJsonPath)) {
+    try {
+      const content = readFileSync(packageJsonPath, 'utf-8');
+      const pkg = JSON.parse(content);
+
+      if (pkg.workspaces) {
+        // Both npm and yarn use package.json workspaces - detect as 'npm'
+        // The format is compatible for both
+        return { type: 'npm', configPath: packageJsonPath, rootPath: projectPath };
+      }
+    } catch {
+      // Ignore JSON parse errors
+    }
+  }
+
+  // 3. Check for lerna.json
+  const lernaJsonPath = join(projectPath, 'lerna.json');
+  if (existsSync(lernaJsonPath)) {
+    return { type: 'lerna', configPath: lernaJsonPath, rootPath: projectPath };
+  }
+
+  // No workspace configuration found
+  return { type: null, configPath: null, rootPath: projectPath };
+}

package/src/plugins/discovery/workspaces/globResolver.ts

@@ -0,0 +1,229 @@
+/**
+ * Glob Resolver for Workspace Packages
+ *
+ * Resolves workspace glob patterns to actual directories containing package.json.
+ * Uses minimatch for pattern matching.
+ */
+
+import { readdirSync, statSync, existsSync, readFileSync, lstatSync } from 'fs';
+import { join, relative } from 'path';
+import { minimatch } from 'minimatch';
+import type { WorkspaceConfig } from './parsers.js';
+
+export interface WorkspacePackage {
+  path: string;
+  name: string;
+  relativePath: string;
+  packageJson: PackageJson;
+}
+
+interface PackageJson {
+  name?: string;
+  version?: string;
+  main?: string;
+  source?: string;
+  description?: string;
+  private?: boolean;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+/**
+ * Resolve workspace glob patterns to actual packages.
+ * Only directories with package.json are considered valid packages.
+ *
+ * @param projectPath - Root directory of the project
+ * @param config - Parsed workspace config with patterns and negativePatterns
+ * @returns Array of resolved workspace packages
+ */
+export function resolveWorkspacePackages(
+  projectPath: string,
+  config: WorkspaceConfig
+): WorkspacePackage[] {
+  const packages: WorkspacePackage[] = [];
+  const seen = new Set<string>();
+
+  // Expand all positive patterns
+  for (const pattern of config.patterns) {
+    const matches = expandGlob(projectPath, pattern);
+
+    for (const dir of matches) {
+      // Check for package.json
+      const pkgJsonPath = join(dir, 'package.json');
+      if (!existsSync(pkgJsonPath)) continue;
+
+      // Check negative patterns
+      const relPath = relative(projectPath, dir);
+      if (config.negativePatterns.some(neg => matchesPattern(relPath, neg))) continue;
+
+      // Avoid duplicates
+      if (seen.has(dir)) continue;
+      seen.add(dir);
+
+      // Parse package.json
+      let pkgJson: PackageJson;
+      try {
+        pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+      } catch {
+        // Skip malformed package.json
+        continue;
+      }
+
+      packages.push({
+        path: dir,
+        name: pkgJson.name || relPath.split('/').pop() || relPath,
+        relativePath: relPath,
+        packageJson: pkgJson
+      });
+    }
+  }
+
+  return packages;
+}
+
+/**
+ * Check if path matches pattern using minimatch.
+ * Normalizes path separators for cross-platform compatibility.
+ */
+function matchesPattern(path: string, pattern: string): boolean {
+  // Normalize path separators
+  const normalizedPath = path.replace(/\\/g, '/');
+  const normalizedPattern = pattern.replace(/\\/g, '/');
+  return minimatch(normalizedPath, normalizedPattern);
+}
+
+/**
+ * Expand glob pattern to actual directories.
+ */
+function expandGlob(basePath: string, pattern: string): string[] {
+  // Handle literal path (no wildcards)
+  if (!pattern.includes('*')) {
+    const fullPath = join(basePath, pattern);
+    if (existsSync(fullPath) && isDirectory(fullPath)) {
+      return [fullPath];
+    }
+    return [];
+  }
+
+  // Handle recursive glob (**)
+  if (pattern.includes('**')) {
+    return expandRecursiveGlob(basePath, pattern);
+  }
+
+  // Handle simple glob (packages/*)
+  return expandSimpleGlob(basePath, pattern);
+}
+
+/**
+ * Expand simple glob like "packages/*" or "apps/*".
+ */
+function expandSimpleGlob(basePath: string, pattern: string): string[] {
+  const parts = pattern.split('/');
+  const results: string[] = [];
+
+  // Find the first part with a wildcard
+  let currentPath = basePath;
+  let patternIndex = 0;
+
+  // Navigate to the parent directory of the glob
+  while (patternIndex < parts.length - 1) {
+    currentPath = join(currentPath, parts[patternIndex]);
+    patternIndex++;
+  }
+
+  // The last part contains the wildcard
+  const globPart = parts[patternIndex];
+
+  if (!existsSync(currentPath)) {
+    return [];
+  }
+
+  try {
+    const entries = readdirSync(currentPath);
+    for (const entry of entries) {
+      if (minimatch(entry, globPart)) {
+        const fullPath = join(currentPath, entry);
+        if (isDirectory(fullPath)) {
+          results.push(fullPath);
+        }
+      }
+    }
+  } catch {
+    // Ignore permission errors
+  }
+
+  return results;
+}
+
+/**
+ * Expand recursive glob like "apps/**" or "libs/**".
+ * Recursively walks directories and matches against pattern.
+ */
+function expandRecursiveGlob(basePath: string, pattern: string): string[] {
+  const results: string[] = [];
+  const maxDepth = 10; // Safety limit
+
+  function walk(dir: string, depth: number): void {
+    if (depth > maxDepth) return;
+
+    try {
+      const entries = readdirSync(dir);
+
+      for (const entry of entries) {
+        // Skip hidden directories and node_modules
+        if (entry.startsWith('.') || entry === 'node_modules') continue;
+
+        const fullPath = join(dir, entry);
+
+        // Skip symlinks to avoid infinite loops
+        if (!isDirectory(fullPath)) continue;
+
+        const relPath = relative(basePath, fullPath);
+
+        // Check if this directory matches the pattern
+        if (minimatch(relPath, pattern, { dot: false })) {
+          results.push(fullPath);
+        }
+
+        // Continue walking regardless of match (** can match at any depth)
+        walk(fullPath, depth + 1);
+      }
+    } catch {
+      // Ignore permission errors
+    }
+  }
+
+  // Start walking from pattern prefix or base
+  const parts = pattern.split('**');
+  const prefix = parts[0].replace(/\/$/, ''); // Remove trailing slash
+
+  if (prefix) {
+    const startPath = join(basePath, prefix);
+    if (existsSync(startPath) && isDirectory(startPath)) {
+      // Check if the start path itself matches
+      const relPath = relative(basePath, startPath);
+      if (minimatch(relPath, pattern, { dot: false })) {
+        results.push(startPath);
+      }
+      walk(startPath, 0);
+    }
+  } else {
+    walk(basePath, 0);
+  }
+
+  return results;
+}
+
+/**
+ * Check if path is a directory (not following symlinks).
+ */
+function isDirectory(path: string): boolean {
+  try {
+    const stat = lstatSync(path);
+    // Return true for real directories, false for symlinks
+    return stat.isDirectory() && !stat.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}

package/src/plugins/discovery/workspaces/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Workspace Detection and Resolution
+ *
+ * Exports utilities for detecting workspace types and resolving workspace packages.
+ */
+
+export {
+  detectWorkspaceType,
+  type WorkspaceType,
+  type WorkspaceDetectionResult
+} from './detector.js';
+
+export {
+  parsePnpmWorkspace,
+  parseNpmWorkspace,
+  parseLernaConfig,
+  type WorkspaceConfig
+} from './parsers.js';
+
+export {
+  resolveWorkspacePackages,
+  type WorkspacePackage
+} from './globResolver.js';

package/src/plugins/discovery/workspaces/parsers.ts

@@ -0,0 +1,99 @@
+/**
+ * Workspace Config Parsers
+ *
+ * Parse workspace configuration files and extract glob patterns.
+ * Supports pnpm-workspace.yaml, package.json workspaces, and lerna.json.
+ */
+
+import { readFileSync } from 'fs';
+import { parse as parseYaml } from 'yaml';
+
+export interface WorkspaceConfig {
+  patterns: string[];
+  negativePatterns: string[];
+}
+
+/**
+ * Parse pnpm-workspace.yaml
+ *
+ * Format:
+ * packages:
+ *   - 'packages/*'
+ *   - 'apps/**'
+ *   - '!packages/internal'
+ */
+export function parsePnpmWorkspace(configPath: string): WorkspaceConfig {
+  const content = readFileSync(configPath, 'utf-8');
+  const config = parseYaml(content) as { packages?: string[] };
+
+  const patterns: string[] = [];
+  const negativePatterns: string[] = [];
+
+  for (const pattern of config.packages || []) {
+    if (pattern.startsWith('!')) {
+      negativePatterns.push(pattern.slice(1));
+    } else {
+      patterns.push(pattern);
+    }
+  }
+
+  return { patterns, negativePatterns };
+}
+
+/**
+ * Parse npm/yarn workspaces from package.json
+ *
+ * Formats:
+ * - Array: { "workspaces": ["packages/*", "apps/**"] }
+ * - Object (yarn): { "workspaces": { "packages": ["packages/*"], "nohoist": [...] } }
+ */
+export function parseNpmWorkspace(packageJsonPath: string): WorkspaceConfig {
+  const content = readFileSync(packageJsonPath, 'utf-8');
+  const pkg = JSON.parse(content) as {
+    workspaces?: string[] | { packages?: string[] };
+  };
+
+  let workspaces: string[] = [];
+
+  if (Array.isArray(pkg.workspaces)) {
+    workspaces = pkg.workspaces;
+  } else if (pkg.workspaces?.packages) {
+    workspaces = pkg.workspaces.packages;
+  }
+
+  const patterns: string[] = [];
+  const negativePatterns: string[] = [];
+
+  for (const pattern of workspaces) {
+    if (pattern.startsWith('!')) {
+      negativePatterns.push(pattern.slice(1));
+    } else {
+      patterns.push(pattern);
+    }
+  }
+
+  return { patterns, negativePatterns };
+}
+
+/**
+ * Parse lerna.json
+ *
+ * Format:
+ * { "packages": ["packages/*", "components/*"] }
+ *
+ * Default: ["packages/*"] if packages field is missing
+ */
+export function parseLernaConfig(lernaJsonPath: string): WorkspaceConfig {
+  const content = readFileSync(lernaJsonPath, 'utf-8');
+  const config = JSON.parse(content) as { packages?: string[] };
+
+  // Lerna defaults to packages/* if not specified
+  const packages = config.packages ?? ['packages/*'];
+
+  // Return empty if explicitly set to empty array
+  if (packages.length === 0) {
+    return { patterns: [], negativePatterns: [] };
+  }
+
+  return { patterns: packages, negativePatterns: [] };
+}