@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

package/src/llm/analyzer.js

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview LLMAnalyzer - Analyzes project context using Claude Code's LLM
+ * @module morph-spec/llm/analyzer
+ */
+
+import { spawn } from 'child_process';
+import { detectClaudeCode, isInteractive } from './environment-detector.js';
+import { buildPrompt } from './prompt-builder.js';
+import Ajv from 'ajv';
+import projectConfigSchema from './project-config-schema.json' with { type: 'json' };
+
+/**
+ * @typedef {import('../types/index.js').SanitizedContext} SanitizedContext
+ * @typedef {import('../types/index.js').ProjectConfig} ProjectConfig
+ */
+
+/**
+ * LLM Analysis Error
+ */
+export class LLMAnalysisError extends Error {
+  constructor(message, statusCode = 500, attempts = 0, originalError = null) {
+    super(message);
+    this.name = 'LLMAnalysisError';
+    this.statusCode = statusCode;
+    this.attempts = attempts;
+    this.originalError = originalError;
+  }
+}
+
+/**
+ * Validation Error
+ */
+export class ValidationError extends Error {
+  constructor(message, field, value, schema = null) {
+    super(message);
+    this.name = 'ValidationError';
+    this.field = field;
+    this.value = value;
+    this.schema = schema;
+  }
+}
+
+/**
+ * LLMAnalyzer - Analyzes project context using Claude Code's embedded LLM
+ * @class
+ */
+export class LLMAnalyzer {
+  constructor() {
+    this.ajv = new Ajv({ allErrors: true });
+    this.validateSchema = this.ajv.compile(projectConfigSchema);
+  }
+
+  /**
+   * Analyze project context using Claude Code's LLM
+   * @param {SanitizedContext} context - Sanitized project context
+   * @param {Object} [options] - Analysis options
+   * @param {number} [options.timeout] - Timeout in ms (default: 60000 for user, no timeout for LLM)
+   * @returns {Promise<ProjectConfig>}
+   * @throws {LLMAnalysisError} If analysis fails
+   */
+  async analyze(context, options = {}) {
+    // Check if Claude Code is available
+    if (!detectClaudeCode()) {
+      throw new LLMAnalysisError(
+        'Claude Code environment not detected. This feature requires Claude Code CLI.',
+        503,
+        0
+      );
+    }
+
+    // Build the prompt
+    const prompt = buildPrompt(context);
+
+    // Determine timeout: 60s for interactive (user present), no timeout for LLM-only
+    const timeout = options.timeout || (isInteractive() ? 60000 : 0);
+
+    // Invoke Claude Code LLM
+    const response = await this.invokeLLM(prompt, { timeout });
+
+    // Parse and validate JSON response
+    const projectConfig = this.parseJsonResponse(response);
+
+    return projectConfig;
+  }
+
+  /**
+   * Build structured prompt for LLM
+   * @param {SanitizedContext} context - Sanitized context
+   * @returns {string} Prompt text
+   */
+  buildPrompt(context) {
+    return buildPrompt(context);
+  }
+
+  /**
+   * Invoke Claude Code's LLM via spawning a subprocess
+   *
+   * IMPLEMENTATION NOTE: This is a placeholder implementation.
+   * The actual Claude Code invocation mechanism depends on how Claude Code exposes its LLM.
+   *
+   * Possible approaches:
+   * 1. Spawn `claude` CLI with a special flag for JSON mode
+   * 2. Use an internal API/IPC mechanism
+   * 3. Write prompt to a temp file and invoke Claude Code agent
+   *
+   * For now, we'll simulate the response for testing purposes.
+   *
+   * @param {string} prompt - Prompt text
+   * @param {Object} options - Invocation options
+   * @param {number} options.timeout - Timeout in ms (0 = no timeout)
+   * @returns {Promise<string>} JSON response from LLM
+   * @throws {LLMAnalysisError}
+   */
+  async invokeLLM(prompt, options = {}) {
+    return new Promise((resolve, reject) => {
+      // TODO: Replace with actual Claude Code invocation
+      // For now, this is a placeholder that would need to be implemented
+      // based on how Claude Code exposes its LLM for programmatic access
+
+      // Example approach (pseudo-code):
+      // const claudeProcess = spawn('claude', ['--mode=json', '--prompt', prompt]);
+
+      // Placeholder: Simulate a timeout if needed
+      const { timeout } = options;
+
+      let output = '';
+      let errorOutput = '';
+
+      // Simulated response for testing (to be replaced with actual Claude Code invocation)
+      // In real implementation, this would spawn Claude Code process:
+      /*
+      const claudeProcess = spawn('claude-code', [
+        '--json',
+        '--prompt-from-stdin'
+      ]);
+
+      claudeProcess.stdin.write(prompt);
+      claudeProcess.stdin.end();
+
+      claudeProcess.stdout.on('data', (data) => {
+        output += data.toString();
+      });
+
+      claudeProcess.stderr.on('data', (data) => {
+        errorOutput += data.toString();
+      });
+
+      claudeProcess.on('close', (code) => {
+        if (code !== 0) {
+          reject(new LLMAnalysisError(
+            `Claude Code exited with code ${code}: ${errorOutput}`,
+            500,
+            1
+          ));
+          return;
+        }
+
+        resolve(output);
+      });
+
+      if (timeout > 0) {
+        setTimeout(() => {
+          claudeProcess.kill();
+          reject(new LLMAnalysisError('LLM analysis timeout', 504, 1));
+        }, timeout);
+      }
+      */
+
+      // For now, reject with a "not implemented" error
+      // This will be replaced when we know the exact Claude Code invocation mechanism
+      reject(new LLMAnalysisError(
+        'LLM invocation not yet implemented. Awaiting Claude Code API documentation.',
+        501,
+        0
+      ));
+    });
+  }
+
+  /**
+   * Parse and validate LLM JSON response
+   * @param {string} response - Raw LLM response
+   * @returns {ProjectConfig}
+   * @throws {ValidationError} If response doesn't match schema
+   */
+  parseJsonResponse(response) {
+    // Try to parse JSON
+    let parsed;
+    try {
+      parsed = JSON.parse(response);
+    } catch (error) {
+      throw new ValidationError(
+        'LLM response is not valid JSON',
+        'response',
+        response,
+        null
+      );
+    }
+
+    // Validate against schema
+    const valid = this.validateSchema(parsed);
+    if (!valid) {
+      const errors = this.validateSchema.errors || [];
+      const errorMessages = errors.map(err => `${err.instancePath} ${err.message}`).join(', ');
+
+      throw new ValidationError(
+        `Schema validation failed: ${errorMessages}`,
+        'schema',
+        parsed,
+        projectConfigSchema
+      );
+    }
+
+    return parsed;
+  }
+}

package/src/llm/environment-detector.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Environment Detector - Detects if running in Claude Code
+ * @module morph-spec/llm/environment-detector
+ */
+
+/**
+ * Detect if running inside Claude Code environment
+ * @returns {boolean} True if Claude Code is available
+ */
+export function detectClaudeCode() {
+  // Check for environment variables that Claude Code sets
+  const claudeEnvVars = [
+    'CLAUDE_CODE_SESSION',
+    'CLAUDE_API_KEY',
+    'ANTHROPIC_API_KEY'
+  ];
+
+  // Check if any Claude-specific env var is set
+  const hasClaudeEnv = claudeEnvVars.some(varName => process.env[varName]);
+
+  // Check if we can detect Claude Code CLI
+  // (This is a heuristic - Claude Code sets these when running)
+  const hasClaudeCLI = process.env.TERM_PROGRAM === 'claude' ||
+                       process.env.CLAUDE_CODE_VERSION;
+
+  return hasClaudeEnv || hasClaudeCLI;
+}
+
+/**
+ * Get Claude Code version if available
+ * @returns {string|null} Version string or null
+ */
+export function getClaudeCodeVersion() {
+  return process.env.CLAUDE_CODE_VERSION || null;
+}
+
+/**
+ * Check if running in interactive mode (user is present)
+ * @returns {boolean} True if interactive
+ */
+export function isInteractive() {
+  return process.stdout.isTTY && process.stdin.isTTY;
+}

package/src/llm/few-shot-examples.js

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview Few-shot examples for LLM prompt
+ * @module morph-spec/llm/few-shot-examples
+ */
+
+/**
+ * Example 1: Next.js + Supabase stack
+ */
+export const EXAMPLE_NEXTJS_SUPABASE = {
+  input: {
+    packageJson: {
+      name: 'my-nextjs-app',
+      dependencies: ['next', 'react', '@supabase/supabase-js', 'tailwindcss'],
+      devDependencies: ['typescript', 'eslint'],
+      scripts: { dev: 'next dev', build: 'next build' },
+      type: 'module'
+    },
+    csprojFilenames: [],
+    hasSolution: false,
+    readmeSummary: 'A modern web application built with Next.js 15 and Supabase...',
+    claudeMdSummary: null,
+    structure: {
+      hasSrc: true,
+      hasBackend: false,
+      hasFrontend: true,
+      hasTests: true,
+      topLevelDirs: ['src', 'app', 'components', 'lib', 'public', 'test'],
+      pattern: 'single-project'
+    },
+    infraSummary: {
+      dockerfilesCount: 1,
+      dockerComposeCount: 1,
+      bicepFilesCount: 0,
+      pipelinesCount: 0,
+      hasAzure: false,
+      hasDocker: true,
+      hasDevOps: false
+    },
+    gitRemoteDomain: 'github.com',
+    totalFiles: 60
+  },
+  output: {
+    name: 'my-nextjs-app',
+    description: 'A modern web application built with Next.js 15 and Supabase for backend',
+    type: 'nextjs',
+    stack: {
+      frontend: {
+        tech: 'Next.js',
+        version: '15',
+        details: 'App Router with Server Components'
+      },
+      backend: {
+        tech: 'Supabase',
+        version: 'latest',
+        details: 'PostgreSQL with real-time features'
+      },
+      database: {
+        tech: 'PostgreSQL',
+        version: '16',
+        details: 'Managed by Supabase'
+      },
+      hosting: 'Docker'
+    },
+    architecture: 'layered',
+    projectStructure: 'Next.js App Router: app/ for routes, components/ for UI, lib/ for utilities',
+    conventions: 'ESM modules, TypeScript, functional components with hooks',
+    repository: null,
+    hasAzure: false,
+    hasDocker: true,
+    hasDevOps: false,
+    confidence: 95,
+    warnings: []
+  }
+};
+
+/**
+ * Example 2: Blazor Server + .NET + Azure SQL
+ */
+export const EXAMPLE_BLAZOR_AZURE = {
+  input: {
+    packageJson: null,
+    csprojFilenames: ['MyApp.Web.csproj', 'MyApp.Domain.csproj', 'MyApp.Infrastructure.csproj'],
+    hasSolution: true,
+    readmeSummary: 'Enterprise web application built with Blazor Server and .NET 10...',
+    claudeMdSummary: 'Stack: Blazor Server + .NET 10 + Azure SQL. Architecture: Clean Architecture with DDD patterns...',
+    structure: {
+      hasSrc: true,
+      hasBackend: false,
+      hasFrontend: false,
+      hasTests: true,
+      topLevelDirs: ['src', 'test', 'infra', 'docs'],
+      pattern: 'single-project'
+    },
+    infraSummary: {
+      dockerfilesCount: 1,
+      dockerComposeCount: 0,
+      bicepFilesCount: 5,
+      pipelinesCount: 1,
+      hasAzure: true,
+      hasDocker: true,
+      hasDevOps: true
+    },
+    gitRemoteDomain: 'github.com',
+    totalFiles: 120
+  },
+  output: {
+    name: 'MyApp',
+    description: 'Enterprise web application built with Blazor Server and .NET 10, deployed to Azure',
+    type: 'blazor-server',
+    stack: {
+      frontend: {
+        tech: 'Blazor',
+        version: '10',
+        details: 'Blazor Server with SignalR'
+      },
+      backend: {
+        tech: '.NET',
+        version: '10',
+        details: 'Minimal API with Clean Architecture'
+      },
+      database: {
+        tech: 'Azure SQL',
+        version: 'latest',
+        details: 'Entity Framework Core'
+      },
+      hosting: 'Azure'
+    },
+    architecture: 'clean-architecture',
+    projectStructure: 'Clean Architecture: Domain (entities), Application (use cases), Infrastructure (EF Core), Web (Blazor UI)',
+    conventions: 'C# 14, nullable reference types, record types for DTOs, async/await, PascalCase',
+    repository: null,
+    hasAzure: true,
+    hasDocker: true,
+    hasDevOps: true,
+    confidence: 98,
+    warnings: []
+  }
+};
+
+/**
+ * Example 3: Monorepo with Next.js + .NET API
+ */
+export const EXAMPLE_MONOREPO = {
+  input: {
+    packageJson: {
+      name: 'monorepo-app',
+      dependencies: [],
+      devDependencies: ['turbo', 'lerna'],
+      scripts: { dev: 'turbo dev', build: 'turbo build' },
+      type: 'module'
+    },
+    csprojFilenames: ['backend/Api/Api.csproj', 'backend/Domain/Domain.csproj'],
+    hasSolution: true,
+    readmeSummary: 'Monorepo application with Next.js frontend and .NET backend API...',
+    claudeMdSummary: null,
+    structure: {
+      hasSrc: false,
+      hasBackend: true,
+      hasFrontend: true,
+      hasTests: true,
+      topLevelDirs: ['frontend', 'backend', 'packages', 'test'],
+      pattern: 'monorepo'
+    },
+    infraSummary: {
+      dockerfilesCount: 2,
+      dockerComposeCount: 1,
+      bicepFilesCount: 0,
+      pipelinesCount: 1,
+      hasAzure: false,
+      hasDocker: true,
+      hasDevOps: true
+    },
+    gitRemoteDomain: 'github.com',
+    totalFiles: 200
+  },
+  output: {
+    name: 'monorepo-app',
+    description: 'Monorepo application with Next.js frontend and .NET backend API',
+    type: 'monorepo',
+    stack: {
+      frontend: {
+        tech: 'Next.js',
+        version: 'latest',
+        details: 'App Router'
+      },
+      backend: {
+        tech: '.NET',
+        version: 'latest',
+        details: 'Minimal API'
+      },
+      database: null,
+      hosting: 'Docker'
+    },
+    architecture: 'microservices',
+    projectStructure: 'Monorepo: frontend/ (Next.js), backend/ (. NET API), packages/ (shared libs)',
+    conventions: 'Turbo for monorepo orchestration, ESM for frontend, C# for backend',
+    repository: null,
+    hasAzure: false,
+    hasDocker: true,
+    hasDevOps: true,
+    confidence: 90,
+    warnings: ['Database technology not detected - may not persist data']
+  }
+};
+
+/**
+ * Get all few-shot examples
+ * @returns {Array} Array of examples
+ */
+export function getFewShotExamples() {
+  return [
+    EXAMPLE_NEXTJS_SUPABASE,
+    EXAMPLE_BLAZOR_AZURE,
+    EXAMPLE_MONOREPO
+  ];
+}

package/src/llm/project-config-schema.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ProjectConfig",
+  "description": "Project configuration detected by LLM",
+  "type": "object",
+  "required": [
+    "name",
+    "description",
+    "type",
+    "stack",
+    "architecture",
+    "projectStructure",
+    "conventions",
+    "hasAzure",
+    "hasDocker",
+    "hasDevOps",
+    "confidence",
+    "warnings"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Project name (from package.json or repository)"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 500,
+      "description": "Project description (1-2 sentences)"
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "monorepo",
+        "blazor-server",
+        "nextjs",
+        "cli-tool",
+        "dotnet-api",
+        "other"
+      ],
+      "description": "Project type"
+    },
+    "stack": {
+      "type": "object",
+      "required": ["backend"],
+      "properties": {
+        "frontend": {
+          "oneOf": [
+            {
+              "type": "object",
+              "required": ["tech", "version"],
+              "properties": {
+                "tech": {
+                  "type": "string",
+                  "description": "Frontend technology (e.g., Next.js, Blazor)"
+                },
+                "version": {
+                  "type": "string",
+                  "description": "Version (e.g., 15, 10)"
+                },
+                "details": {
+                  "type": "string",
+                  "description": "Additional details (e.g., App Router, Server Components)"
+                }
+              }
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "backend": {
+          "type": "object",
+          "required": ["tech", "version"],
+          "properties": {
+            "tech": {
+              "type": "string",
+              "description": "Backend technology (e.g., .NET, Supabase, Node.js)"
+            },
+            "version": {
+              "type": "string",
+              "description": "Version (e.g., 10, 18, latest)"
+            },
+            "details": {
+              "type": "string",
+              "description": "Additional details (e.g., Minimal API, Express)"
+            }
+          }
+        },
+        "database": {
+          "oneOf": [
+            {
+              "type": "object",
+              "required": ["tech", "version"],
+              "properties": {
+                "tech": {
+                  "type": "string",
+                  "description": "Database technology (e.g., PostgreSQL, Azure SQL)"
+                },
+                "version": {
+                  "type": "string",
+                  "description": "Version"
+                },
+                "details": {
+                  "type": "string",
+                  "description": "Additional details"
+                }
+              }
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "hosting": {
+          "oneOf": [
+            {
+              "type": "string",
+              "description": "Hosting platform (e.g., Azure, Vercel, Docker)"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "architecture": {
+      "type": "string",
+      "enum": [
+        "clean-architecture",
+        "monolith",
+        "microservices",
+        "layered",
+        "other"
+      ],
+      "description": "Architecture pattern"
+    },
+    "projectStructure": {
+      "type": "string",
+      "minLength": 10,
+      "description": "Description of folder structure"
+    },
+    "conventions": {
+      "type": "string",
+      "minLength": 5,
+      "description": "Detected code conventions"
+    },
+    "repository": {
+      "oneOf": [
+        {
+          "type": "string",
+          "format": "uri"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Git repository URL"
+    },
+    "hasAzure": {
+      "type": "boolean",
+      "description": "Uses Azure infrastructure"
+    },
+    "hasDocker": {
+      "type": "boolean",
+      "description": "Uses Docker containerization"
+    },
+    "hasDevOps": {
+      "type": "boolean",
+      "description": "Uses CI/CD pipelines"
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 100,
+      "description": "LLM confidence score (0-100)"
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Warnings or uncertainties detected"
+    }
+  }
+}