@polymorphism-tech/morph-spec 1.0.4 → 2.1.0

package/detectors/standards-generator.js

@@ -0,0 +1,275 @@
+/**
+ * Standards Generator - Generates inferred-standards.md from detection results
+ */
+
+/**
+ * Generate inferred standards
+ * @param {Object} detectionResults - Results from all detectors
+ * @returns {Promise<Object>} Generated standards
+ */
+export async function generateStandards(detectionResults) {
+  const { structure, config, conversation } = detectionResults;
+
+  const standards = {
+    markdown: generateMarkdown(structure, config, conversation),
+    recommendations: generateRecommendations(structure, config, conversation),
+    gaps: identifyGaps(structure, config)
+  };
+
+  return standards;
+}
+
+/**
+ * Generate markdown content for inferred-standards.md
+ */
+function generateMarkdown(structure, config, conversation) {
+  const sections = [];
+
+  // Header
+  sections.push(`# Inferred Standards (Auto-generated)`);
+  sections.push(``);
+  sections.push(`> ⚠️ This file is auto-generated by MORPH-SPEC detection system.`);
+  sections.push(`> Manual edits will be overwritten. Create custom standards in \`overrides.md\`.`);
+  sections.push(``);
+  sections.push(`**Generated:** ${new Date().toISOString()}`);
+  sections.push(``);
+  sections.push(`---`);
+  sections.push(``);
+
+  // Stack Summary
+  sections.push(`## 🎯 Project Stack`);
+  sections.push(``);
+  sections.push(`- **Type**: ${structure?.stack || 'unknown'}`);
+  sections.push(`- **Language**: ${config?.language || 'unknown'}`);
+  sections.push(`- **Version**: ${config?.version || 'unknown'}`);
+  sections.push(`- **Architecture**: ${structure?.architecture || 'unknown'}`);
+  if (structure?.uiLibrary) {
+    sections.push(`- **UI Library**: ${structure.uiLibrary}`);
+  }
+  sections.push(``);
+
+  // Technologies
+  if (config?.technologies?.length > 0) {
+    sections.push(`## 🛠️ Technologies Detected`);
+    sections.push(``);
+    config.technologies.forEach(tech => {
+      sections.push(`- ${tech}`);
+    });
+    sections.push(``);
+  }
+
+  // Patterns
+  if (structure?.patterns?.length > 0) {
+    sections.push(`## 📐 Patterns in Use`);
+    sections.push(``);
+    structure.patterns.forEach(pattern => {
+      sections.push(`- ${pattern}`);
+    });
+    sections.push(``);
+  }
+
+  // Coding Standards (inferred)
+  sections.push(`## 💻 Inferred Coding Standards`);
+  sections.push(``);
+  sections.push(generateCodingStandards(structure, config));
+  sections.push(``);
+
+  // Architecture Patterns
+  if (structure?.architecture !== 'unknown') {
+    sections.push(`## 🏗️ Architecture Pattern`);
+    sections.push(``);
+    sections.push(generateArchitectureSection(structure));
+    sections.push(``);
+  }
+
+  // Dependencies
+  if (config?.dependencies?.length > 0) {
+    sections.push(`## 📦 Key Dependencies`);
+    sections.push(``);
+    const importantDeps = filterImportantDependencies(config.dependencies);
+    importantDeps.slice(0, 10).forEach(dep => {
+      sections.push(`- ${dep}`);
+    });
+    if (config.dependencies.length > 10) {
+      sections.push(`- ... and ${config.dependencies.length - 10} more`);
+    }
+    sections.push(``);
+  }
+
+  // User Preferences (from conversation)
+  if (conversation?.preferences && Object.keys(conversation.preferences).some(k => conversation.preferences[k])) {
+    sections.push(`## 🎨 User Preferences (from past decisions)`);
+    sections.push(``);
+    Object.entries(conversation.preferences).forEach(([key, value]) => {
+      if (value) {
+        sections.push(`- **${formatKey(key)}**: ${value}`);
+      }
+    });
+    sections.push(``);
+  }
+
+  return sections.join('\n');
+}
+
+/**
+ * Generate coding standards section
+ */
+function generateCodingStandards(structure, config) {
+  if (config?.language === 'csharp') {
+    return `### C# / .NET Conventions
+
+Based on detected patterns in your codebase:
+
+- **Naming**: PascalCase for classes, camelCase for variables
+- **Async**: Methods with \`Async\` suffix
+- **DI**: Constructor injection (${structure.patterns.includes('Dependency Injection') ? '✅ detected' : '⚠️ not detected'})
+- **Tests**: ${structure.patterns.includes('Unit Tests') ? '✅ Present' : '⚠️ Not detected'}
+
+**Recommendation**: Refer to \`.morph/standards/coding.md\` for complete .NET standards.`;
+  }
+
+  if (config?.language === 'javascript') {
+    return `### JavaScript / TypeScript Conventions
+
+Based on detected patterns in your codebase:
+
+- **Package Manager**: ${config.packageManager}
+- **Framework**: ${config.technologies.join(', ')}
+
+**Recommendation**: Refer to framework standards for JavaScript best practices.`;
+  }
+
+  return 'No specific coding standards inferred. Check framework standards for guidance.';
+}
+
+/**
+ * Generate architecture section
+ */
+function generateArchitectureSection(structure) {
+  const { architecture } = structure;
+
+  const descriptions = {
+    'clean-architecture': `### Clean Architecture
+
+Your project follows Clean Architecture pattern:
+
+- ✅ **Domain** layer detected (core business logic)
+- ✅ **Application** layer detected (use cases)
+- ✅ **Infrastructure** layer detected (implementations)
+
+**Key principles**:
+- Domain has no dependencies
+- Application depends on Domain
+- Infrastructure implements Application interfaces`,
+
+    'cqrs': `### CQRS Pattern
+
+Your project uses Command Query Responsibility Segregation:
+
+- ✅ **Commands** detected (write operations)
+- ✅ **Queries** detected (read operations)
+
+**Key principles**:
+- Separate read and write models
+- Commands return void or Task
+- Queries return data`,
+
+    'mvc': `### MVC Pattern
+
+Your project uses Model-View-Controller pattern:
+
+- ✅ **Controllers** detected
+- ✅ **Models** detected
+- ✅ **Views** detected`
+  };
+
+  return descriptions[architecture] || `Architecture: ${architecture}`;
+}
+
+/**
+ * Generate recommendations
+ */
+function generateRecommendations(structure, config, conversation) {
+  const recommendations = [];
+
+  // Recommend based on stack
+  if (structure?.stack === 'blazor') {
+    if (!structure.uiLibrary) {
+      recommendations.push('Consider adding Fluent UI Blazor or MudBlazor for consistent UI components');
+    }
+
+    if (!structure.patterns.includes('AI Agents') && config?.technologies?.includes('Microsoft Agent Framework')) {
+      recommendations.push('Setup detected Agent Framework but no agents found - check .morph/standards/agent-framework-setup.md');
+    }
+  }
+
+  // Recommend tests
+  if (!structure?.patterns?.includes('Unit Tests')) {
+    recommendations.push('No unit tests detected - consider adding test project');
+  }
+
+  // Recommend DI
+  if (!structure?.patterns?.includes('Dependency Injection')) {
+    recommendations.push('Consider implementing Dependency Injection pattern');
+  }
+
+  // Architecture recommendations
+  if (structure?.architecture === 'unknown' && structure?.folders?.hasServices) {
+    recommendations.push('Service layer detected but no clear architecture - consider Clean Architecture or CQRS');
+  }
+
+  return recommendations;
+}
+
+/**
+ * Identify gaps between framework and project
+ */
+function identifyGaps(structure, config) {
+  const gaps = [];
+
+  // Check for missing patterns
+  const expectedPatterns = {
+    blazor: ['Service Layer', 'Repository Pattern', 'Dependency Injection'],
+    nextjs: ['API Routes', 'Components'],
+  };
+
+  const expected = expectedPatterns[structure?.stack];
+  if (expected) {
+    expected.forEach(pattern => {
+      if (!structure?.patterns?.includes(pattern)) {
+        gaps.push(`Missing: ${pattern}`);
+      }
+    });
+  }
+
+  return gaps;
+}
+
+/**
+ * Filter important dependencies
+ */
+function filterImportantDependencies(deps) {
+  const important = deps.filter(dep => {
+    // Framework packages
+    if (dep.includes('Microsoft.') || dep.includes('System.')) return true;
+    // UI libraries
+    if (dep.includes('Blazor') || dep.includes('FluentUI') || dep.includes('Mud')) return true;
+    // Common tools
+    if (dep.includes('Hangfire') || dep.includes('Serilog') || dep.includes('AutoMapper')) return true;
+    // AI/ML
+    if (dep.includes('Agents') || dep.includes('AI') || dep.includes('OpenAI')) return true;
+    return false;
+  });
+
+  return important.length > 0 ? important : deps;
+}
+
+/**
+ * Format key for display
+ */
+function formatKey(key) {
+  return key
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, str => str.toUpperCase())
+    .trim();
+}

package/detectors/structure-detector.js

@@ -0,0 +1,221 @@
+/**
+ * Structure Detector - Analyzes folder structure to infer stack and architecture
+ */
+
+import { glob } from 'glob';
+import { join } from 'path';
+import { existsSync } from 'fs';
+
+/**
+ * Detect project structure
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Structure detection results
+ */
+export async function detectStructure(projectPath) {
+  const result = {
+    stack: 'unknown',
+    architecture: 'unknown',
+    uiLibrary: null,
+    patterns: [],
+    folders: {
+      hasPages: false,
+      hasComponents: false,
+      hasServices: false,
+      hasRepositories: false,
+      hasAgents: false
+    }
+  };
+
+  // Detect stack
+  result.stack = await detectStack(projectPath);
+
+  // Detect architecture pattern
+  result.architecture = await detectArchitecture(projectPath);
+
+  // Detect UI library
+  if (result.stack === 'blazor') {
+    result.uiLibrary = await detectUILibrary(projectPath);
+  }
+
+  // Detect patterns
+  result.patterns = await detectPatterns(projectPath);
+
+  // Analyze folders
+  result.folders = await analyzeFolders(projectPath);
+
+  return result;
+}
+
+/**
+ * Detect stack type
+ */
+async function detectStack(projectPath) {
+  const patterns = {
+    blazor: [
+      '**/*.razor',
+      '**/Pages/**/*.razor',
+      '**/Components/**/*.razor'
+    ],
+    nextjs: [
+      'pages/**/*.tsx',
+      'app/**/*.tsx',
+      'next.config.js',
+      'next.config.mjs'
+    ],
+    shopify: [
+      '**/*.liquid',
+      'sections/**/*.liquid',
+      'templates/**/*.liquid'
+    ],
+    dotnet: [
+      '**/*.csproj',
+      '**/Program.cs'
+    ]
+  };
+
+  for (const [stack, globs] of Object.entries(patterns)) {
+    for (const pattern of globs) {
+      const files = await glob(pattern, { cwd: projectPath, nodir: true });
+      if (files.length > 0) {
+        return stack;
+      }
+    }
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Detect architecture pattern
+ */
+async function detectArchitecture(projectPath) {
+  const checks = [
+    {
+      pattern: 'clean-architecture',
+      indicators: [
+        existsSync(join(projectPath, 'src', 'Application')),
+        existsSync(join(projectPath, 'src', 'Domain')),
+        existsSync(join(projectPath, 'src', 'Infrastructure'))
+      ]
+    },
+    {
+      pattern: 'cqrs',
+      indicators: [
+        await glob('**/Commands/**/*.cs', { cwd: projectPath }).then(f => f.length > 0),
+        await glob('**/Queries/**/*.cs', { cwd: projectPath }).then(f => f.length > 0)
+      ]
+    },
+    {
+      pattern: 'mvc',
+      indicators: [
+        existsSync(join(projectPath, 'Controllers')),
+        existsSync(join(projectPath, 'Models')),
+        existsSync(join(projectPath, 'Views'))
+      ]
+    }
+  ];
+
+  for (const { pattern, indicators } of checks) {
+    if (indicators.every(Boolean)) {
+      return pattern;
+    }
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Detect UI library (Blazor projects)
+ */
+async function detectUILibrary(projectPath) {
+  const csprojFiles = await glob('**/*.csproj', { cwd: projectPath });
+
+  for (const csprojFile of csprojFiles) {
+    const content = await import('fs').then(fs =>
+      fs.promises.readFile(join(projectPath, csprojFile), 'utf8')
+    );
+
+    if (content.includes('FluentUI.Blazor') || content.includes('Microsoft.FluentUI.AspNetCore.Components')) {
+      return 'fluent-ui';
+    }
+
+    if (content.includes('MudBlazor')) {
+      return 'mudblazor';
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Detect common patterns
+ */
+async function detectPatterns(projectPath) {
+  const patterns = [];
+
+  // Check for specific patterns
+  const checks = [
+    {
+      name: 'Repository Pattern',
+      glob: '**/*Repository.cs'
+    },
+    {
+      name: 'Service Layer',
+      glob: '**/*Service.cs'
+    },
+    {
+      name: 'DTOs',
+      glob: '**/*Dto.cs'
+    },
+    {
+      name: 'Entity Framework',
+      glob: '**/Migrations/**/*.cs'
+    },
+    {
+      name: 'Dependency Injection',
+      glob: '**/DependencyInjection.cs'
+    },
+    {
+      name: 'Hangfire Jobs',
+      glob: '**/*Job.cs'
+    },
+    {
+      name: 'AI Agents',
+      glob: '**/*Agent.cs'
+    },
+    {
+      name: 'Unit Tests',
+      glob: '**/*.Tests/**/*.cs'
+    }
+  ];
+
+  for (const { name, glob: pattern } of checks) {
+    const files = await glob(pattern, { cwd: projectPath, nodir: true });
+    if (files.length > 0) {
+      patterns.push(name);
+    }
+  }
+
+  return patterns;
+}
+
+/**
+ * Analyze folder structure
+ */
+async function analyzeFolders(projectPath) {
+  const folders = {
+    hasPages: false,
+    hasComponents: false,
+    hasServices: false,
+    hasRepositories: false,
+    hasAgents: false
+  };
+
+  folders.hasPages = await glob('**/Pages/**/*', { cwd: projectPath }).then(f => f.length > 0);
+  folders.hasComponents = await glob('**/Components/**/*', { cwd: projectPath }).then(f => f.length > 0);
+  folders.hasServices = await glob('**/Services/**/*', { cwd: projectPath }).then(f => f.length > 0);
+  folders.hasRepositories = await glob('**/Repositories/**/*', { cwd: projectPath }).then(f => f.length > 0);
+  folders.hasAgents = await glob('**/Agents/**/*', { cwd: projectPath }).then(f => f.length > 0);
+
+  return folders;
+}

package/docs/README.md

@@ -0,0 +1,149 @@
+# MORPH-SPEC API Documentation
+
+This directory contains the API documentation for MORPH-SPEC Framework libraries.
+
+## Available Documentation
+
+### API Reference (`/api`)
+
+Comprehensive API documentation generated from JSDoc comments in the source code.
+
+**Libraries Documented:**
+- **state-manager** - Feature state management, agents, checkpoints, outputs tracking
+- **cost-calculator** - Azure infrastructure cost calculation from Bicep files
+- **design-system-generator** - UI design system parsing and theme generation
+
+**View Documentation:**
+- Open `api/index.html` in your browser
+- Or run `npm run docs:serve` to start a local server at http://localhost:8080
+
+## Running Tests
+
+### Run Tests
+
+```bash
+npm test
+```
+
+Runs all 85 unit tests with 100% pass rate.
+
+### Run Tests with Coverage
+
+```bash
+npm run test:coverage
+```
+
+Generates coverage report (HTML + text + lcov). **Current coverage: 98.03%**
+
+- **Statements:** 98.03%
+- **Branches:** 88.74%
+- **Functions:** 100%
+- **Lines:** 98.03%
+
+Coverage reports are generated in `coverage/` directory.
+
+### Coverage Summary Only
+
+```bash
+npm run test:coverage:summary
+```
+
+Shows text summary without generating HTML report.
+
+## Generating Documentation
+
+### Build API Docs
+
+```bash
+npm run docs
+```
+
+Generates HTML documentation from JSDoc comments in `src/lib/` to `docs/api/`.
+
+### Watch Mode
+
+```bash
+npm run docs:watch
+```
+
+Automatically regenerates documentation when source files change.
+
+### Serve Locally
+
+```bash
+npm run docs:serve
+```
+
+Starts a local HTTP server at http://localhost:8080 to view documentation.
+
+## Documentation Standards
+
+### JSDoc Format
+
+All library functions in `src/lib/` use JSDoc comments with:
+
+- **@param** - Parameter descriptions with types
+- **@returns** - Return value description with type
+- **@throws** - Exceptions that may be thrown
+- **@example** - Usage examples (when applicable)
+
+**Example:**
+
+```javascript
+/**
+ * Calculate cost of a single resource
+ * @param {Object} resource - Resource object with type, sku, minReplicas
+ * @param {string} resource.type - Azure resource type
+ * @param {string} resource.sku - SKU name
+ * @param {number} [resource.minReplicas] - Minimum replicas (Container Apps)
+ * @returns {Object} Cost result with cost, warning, estimated, details
+ * @throws {Error} If resource type is invalid
+ */
+export function calculateResourceCost(resource) {
+  // Implementation
+}
+```
+
+### Module-Level Documentation
+
+Each library file starts with a block comment describing:
+
+- Purpose and responsibilities
+- Usage context (CLI commands, internal automation)
+- Key features
+
+**Example:**
+
+```javascript
+/**
+ * MORPH-SPEC State Manager Library
+ *
+ * Manages state.json for tracking features, progress, agents, and checkpoints.
+ * Used both by CLI commands and internal automation.
+ */
+```
+
+## Updating Documentation
+
+1. **Update JSDoc comments** in source files (`src/lib/*.js`)
+2. **Regenerate docs:** `npm run docs`
+3. **Review:** Open `docs/api/index.html`
+4. **Commit:** Include updated `docs/api/` in your commit
+
+## Template
+
+Documentation is generated using the [docdash](https://github.com/clenemt/docdash) template for JSDoc, configured in `jsdoc.json`.
+
+**Features:**
+- Clean, modern design
+- Full-text search
+- Responsive layout
+- Syntax highlighting
+- Type definitions
+- Source code links
+
+## Links
+
+- **GitHub:** https://github.com/lucasPolymorphism/morph-spec-framework
+- **npm:** https://www.npmjs.com/package/@polymorphism-tech/morph-spec
+- **Website:** https://polymorphism.com.br/morph-spec