@polymorphism-tech/morph-spec 3.2.0 → 4.2.0

package/src/types/index.js

@@ -1,477 +0,0 @@
-/**
- * @fileoverview Type definitions and contracts for CLI Auto Context Detection
- * @module morph-spec/cli-auto-context-detection
- *
- * This file defines the interfaces and types used throughout the CLI Auto Context Detection feature.
- * Since MORPH-SPEC uses JavaScript (ESM), we use JSDoc for type annotations instead of TypeScript.
- */
-
-// ============================================================================
-// PROJECT CONTEXT (Scanner Output)
-// ============================================================================
-
-/**
- * Parsed package.json content
- * @typedef {Object} PackageJson
- * @property {string} name - Package name
- * @property {string} [version] - Package version
- * @property {string} [description] - Package description
- * @property {Object.<string, string>} [dependencies] - Production dependencies
- * @property {Object.<string, string>} [devDependencies] - Development dependencies
- * @property {Object.<string, string>} [scripts] - NPM scripts
- * @property {string} [type] - Module type (commonjs | module)
- * @property {Object} [engines] - Node.js engine requirements
- */
-
-/**
- * Directory structure analysis
- * @typedef {Object} DirectoryStructure
- * @property {boolean} hasSrc - Has src/ directory
- * @property {boolean} hasBackend - Has backend/ or server/ directory
- * @property {boolean} hasFrontend - Has frontend/ or client/ directory
- * @property {boolean} hasTests - Has test/ or tests/ directory
- * @property {string[]} topLevelDirs - List of top-level directories
- * @property {string} pattern - Detected pattern (monorepo | single-project | multi-stack)
- */
-
-/**
- * Infrastructure files detected
- * @typedef {Object} InfraFiles
- * @property {string[]} dockerfiles - Paths to Dockerfiles
- * @property {string[]} dockerComposeFiles - Paths to docker-compose.yml files
- * @property {string[]} bicepFiles - Paths to *.bicep files
- * @property {string[]} pipelines - Paths to CI/CD pipeline configs
- * @property {boolean} hasAzure - Has Azure-related files
- * @property {boolean} hasDocker - Has Docker-related files
- * @property {boolean} hasDevOps - Has CI/CD configs
- */
-
-/**
- * Complete project context collected by scanner
- * @typedef {Object} ProjectContext
- * @property {string} cwd - Current working directory (absolute path)
- * @property {PackageJson|null} packageJson - Parsed package.json (if exists)
- * @property {string[]} csprojFiles - Paths to *.csproj files
- * @property {string|null} solutionFile - Path to *.sln file (if exists)
- * @property {string|null} readme - Content of README.md (if exists)
- * @property {string|null} claudeMd - Content of CLAUDE.md (if exists)
- * @property {DirectoryStructure} structure - Detected directory structure
- * @property {InfraFiles} infraFiles - Detected infrastructure files
- * @property {string|null} gitRemote - Git remote URL (if in git repo)
- * @property {Date} scannedAt - Timestamp when scan was performed
- */
-
-// ============================================================================
-// PROJECT CONFIG (LLM Output)
-// ============================================================================
-
-/**
- * Technology specification
- * @typedef {Object} TechSpec
- * @property {string} tech - Technology name (e.g., "Next.js", ".NET", "PostgreSQL")
- * @property {string} version - Version (e.g., "15", "10", "16")
- * @property {string} [details] - Additional details (e.g., "Server Components", "Minimal API")
- */
-
-/**
- * Technology stack information
- * @typedef {Object} StackInfo
- * @property {TechSpec|null} frontend - Frontend technology (null if backend-only)
- * @property {TechSpec} backend - Backend technology
- * @property {TechSpec|null} database - Database technology (null if no persistence)
- * @property {string|null} hosting - Hosting platform (e.g., "Azure", "Vercel", "Docker")
- */
-
-/**
- * Complete project configuration detected by LLM
- * @typedef {Object} ProjectConfig
- * @property {string} name - Project name (from package.json or repo)
- * @property {string} description - Project description (1-2 sentences)
- * @property {string} type - Project type (monorepo | blazor-server | nextjs | cli-tool | dotnet-api | other)
- * @property {StackInfo} stack - Technology stack
- * @property {string} architecture - Architecture pattern (clean-architecture | monolith | microservices | layered | other)
- * @property {string} projectStructure - Description of folder structure
- * @property {string} conventions - Detected code conventions (e.g., "ESM modules", "PascalCase for classes")
- * @property {string|null} repository - Git repository URL
- * @property {boolean} hasAzure - Uses Azure infrastructure
- * @property {boolean} hasDocker - Uses Docker containerization
- * @property {boolean} hasDevOps - Uses CI/CD pipelines
- * @property {number} confidence - LLM confidence score (0-100)
- * @property {string[]} warnings - Warnings or uncertainties detected
- */
-
-// ============================================================================
-// SANITIZED CONTEXT (Input to LLM)
-// ============================================================================
-
-/**
- * Sanitized project context (safe to send to LLM)
- * @typedef {Object} SanitizedContext
- * @property {Object} packageJson - Sanitized package.json (secrets removed)
- * @property {string[]} csprojFilenames - Filenames only (not full content)
- * @property {boolean} hasSolution - Whether *.sln exists (no content)
- * @property {string|null} readmeSummary - First 500 chars of README.md
- * @property {string|null} claudeMdSummary - First 500 chars of CLAUDE.md
- * @property {DirectoryStructure} structure - Directory structure (safe)
- * @property {Object} infraSummary - Infrastructure summary (no secrets)
- * @property {string|null} gitRemoteDomain - Git remote domain only (e.g., "github.com")
- * @property {number} totalFiles - Total file count (for context)
- */
-
-// ============================================================================
-// GENERATED CONFIGS
-// ============================================================================
-
-/**
- * Generated configuration files
- * @typedef {Object} GeneratedConfigs
- * @property {string} projectMd - Rendered project.md content
- * @property {string} configJson - Rendered config.json content (as string)
- * @property {Object} configObject - Parsed config.json (as object)
- */
-
-// ============================================================================
-// USER REVIEW
-// ============================================================================
-
-/**
- * User approval response
- * @typedef {Object} ApprovalResponse
- * @property {'approve'|'edit'|'cancel'} action - User action
- * @property {GeneratedConfigs} [editedConfigs] - Edited configs (if action === 'edit')
- * @property {string} [cancelReason] - Reason for cancellation (if action === 'cancel')
- */
-
-// ============================================================================
-// ERRORS
-// ============================================================================
-
-/**
- * LLM Analysis Error
- * @typedef {Error} LLMAnalysisError
- * @property {string} name - "LLMAnalysisError"
- * @property {string} message - Error message
- * @property {number} statusCode - HTTP status code (if API error)
- * @property {number} attempts - Number of retry attempts made
- * @property {Error} [originalError] - Original error from API
- */
-
-/**
- * Validation Error
- * @typedef {Error} ValidationError
- * @property {string} name - "ValidationError"
- * @property {string} message - Error message
- * @property {string} field - Field that failed validation
- * @property {any} value - Invalid value
- * @property {Object} [schema] - JSON schema that was violated
- */
-
-// ============================================================================
-// SERVICE INTERFACES
-// ============================================================================
-
-/**
- * Project Scanner Interface
- * @interface IProjectScanner
- */
-export class IProjectScanner {
-  /**
-   * Scan the project directory and collect context
-   * @param {string} cwd - Current working directory
-   * @returns {Promise<ProjectContext>}
-   */
-  async scan(cwd) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Read and parse package.json
-   * @param {string} cwd - Current working directory
-   * @returns {Promise<PackageJson|null>}
-   */
-  async readPackageJson(cwd) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Find all .csproj files recursively
-   * @param {string} cwd - Current working directory
-   * @returns {Promise<string[]>}
-   */
-  async findCsprojFiles(cwd) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Detect directory structure
-   * @param {string} cwd - Current working directory
-   * @returns {Promise<DirectoryStructure>}
-   */
-  async detectDirectoryStructure(cwd) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Find infrastructure files (Docker, Bicep, pipelines)
-   * @param {string} cwd - Current working directory
-   * @returns {Promise<InfraFiles>}
-   */
-  async findInfraFiles(cwd) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Get git remote URL
-   * @param {string} cwd - Current working directory
-   * @returns {Promise<string|null>}
-   */
-  async getGitRemote(cwd) {
-    throw new Error('Not implemented');
-  }
-}
-
-/**
- * Context Sanitizer Interface
- * @interface IContextSanitizer
- */
-export class IContextSanitizer {
-  /**
-   * Sanitize project context (remove secrets, truncate files)
-   * @param {ProjectContext} context - Raw project context
-   * @returns {SanitizedContext}
-   */
-  sanitize(context) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Detect and redact secrets from text
-   * @param {string} text - Text to sanitize
-   * @returns {string} Sanitized text
-   */
-  redactSecrets(text) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Check if file should be excluded from LLM analysis
-   * @param {string} filepath - File path
-   * @returns {boolean} True if file should be excluded
-   */
-  shouldExcludeFile(filepath) {
-    throw new Error('Not implemented');
-  }
-}
-
-/**
- * LLM Analyzer Interface
- * @interface ILLMAnalyzer
- */
-export class ILLMAnalyzer {
-  /**
-   * 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: 30000)
-   * @returns {Promise<ProjectConfig>}
-   * @throws {LLMAnalysisError} If analysis fails
-   */
-  async analyze(context, options) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Build structured prompt for LLM
-   * @param {SanitizedContext} context - Sanitized context
-   * @returns {string} Prompt text
-   */
-  buildPrompt(context) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Invoke Claude Code's LLM (via Task tool or internal API)
-   * @param {string} prompt - Prompt text
-   * @param {Object} options - Invocation options
-   * @returns {Promise<string>} JSON response from LLM
-   * @throws {LLMAnalysisError}
-   */
-  async invokeLLM(prompt, options) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Parse and validate LLM JSON response
-   * @param {string} response - Raw LLM response
-   * @returns {ProjectConfig}
-   * @throws {ValidationError} If response doesn't match schema
-   */
-  parseJsonResponse(response) {
-    throw new Error('Not implemented');
-  }
-}
-
-/**
- * Config Generator Interface
- * @interface IConfigGenerator
- */
-export class IConfigGenerator {
-  /**
-   * Generate configuration files from project config
-   * @param {ProjectConfig} projectConfig - Detected project config
-   * @returns {Promise<GeneratedConfigs>}
-   */
-  async generate(projectConfig) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Render project.md template
-   * @param {ProjectConfig} config - Project config
-   * @returns {string} Rendered markdown
-   */
-  renderProjectMd(config) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Render config.json template
-   * @param {ProjectConfig} config - Project config
-   * @returns {string} Rendered JSON string
-   */
-  renderConfigJson(config) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Validate config.json against schema
-   * @param {string} configJson - JSON string
-   * @returns {boolean} True if valid
-   * @throws {ValidationError} If validation fails
-   */
-  validateConfigJson(configJson) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Backup existing configuration files
-   * @param {string} cwd - Current working directory
-   * @returns {Promise<void>}
-   */
-  async backupExisting(cwd) {
-    throw new Error('Not implemented');
-  }
-}
-
-/**
- * User Review Interface
- * @interface IUserReview
- */
-export class IUserReview {
-  /**
-   * Prompt user for approval of generated configs
-   * @param {GeneratedConfigs} configs - Generated configs
-   * @param {ProjectConfig} projectConfig - Detected project config
-   * @returns {Promise<ApprovalResponse>}
-   */
-  async promptForApproval(configs, projectConfig) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Display diff between current and generated configs
-   * @param {string} current - Current config content
-   * @param {string} generated - Generated config content
-   * @returns {void}
-   */
-  displayDiff(current, generated) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Open configs in editor for manual editing
-   * @param {GeneratedConfigs} configs - Configs to edit
-   * @returns {Promise<GeneratedConfigs>} Edited configs
-   */
-  async openInEditor(configs) {
-    throw new Error('Not implemented');
-  }
-}
-
-/**
- * File Writer Interface
- * @interface IFileWriter
- */
-export class IFileWriter {
-  /**
-   * Save generated configs to filesystem
-   * @param {string} cwd - Current working directory
-   * @param {GeneratedConfigs} configs - Configs to save
-   * @returns {Promise<void>}
-   */
-  async save(cwd, configs) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Write project.md file
-   * @param {string} filepath - File path
-   * @param {string} content - File content
-   * @returns {Promise<void>}
-   */
-  async writeProjectMd(filepath, content) {
-    throw new Error('Not implemented');
-  }
-
-  /**
-   * Write config.json file
-   * @param {string} filepath - File path
-   * @param {string} content - File content (JSON string)
-   * @returns {Promise<void>}
-   */
-  async writeConfigJson(filepath, content) {
-    throw new Error('Not implemented');
-  }
-}
-
-// ============================================================================
-// ORCHESTRATOR (Main Flow)
-// ============================================================================
-
-/**
- * CLI Auto Context Detection Orchestrator
- * @interface IAutoContextOrchestrator
- */
-export class IAutoContextOrchestrator {
-  /**
-   * Execute the complete auto-detection flow
-   * @param {string} cwd - Current working directory
-   * @param {Object} [options] - Orchestration options
-   * @param {boolean} [options.skipReview] - Skip user review (auto-approve)
-   * @param {boolean} [options.fallbackOnError] - Fallback to wizard on LLM error
-   * @returns {Promise<{success: boolean, configs: GeneratedConfigs|null}>}
-   */
-  async execute(cwd, options) {
-    throw new Error('Not implemented');
-  }
-}
-
-// ============================================================================
-// EXPORTS
-// ============================================================================
-
-export {
-  // Types
-  PackageJson,
-  DirectoryStructure,
-  InfraFiles,
-  ProjectContext,
-  TechSpec,
-  StackInfo,
-  ProjectConfig,
-  SanitizedContext,
-  GeneratedConfigs,
-  ApprovalResponse,
-  LLMAnalysisError,
-  ValidationError,
-};