@confytome/core

Core plugin system and OpenAPI 3.1.0 generator from JSDoc comments. Plugin registry, service layer, and CLI for extensible API documentation generation.

✨ Core Features

• 🔌 Plugin Registry System - Automatic generator discovery and management
• 📊 OpenAPI 3.1.0 Generation - JSDoc to OpenAPI specification conversion
• 🎯 Service Layer - Centralized branding, versioning, and templating
• 🔧 CLI Interface - Comprehensive command-line tools
• 📝 Project Initialization - Quick project setup with templates
• 🧪 Testing Framework - Complete test coverage for all components

🚀 Installation

# Global installation (recommended)
npm install -g @confytome/core

# Local project installation
npm install @confytome/core

📋 Commands

Core Generation Commands

# Initialize new confytome project
confytome init

# Generate OpenAPI specification from JSDoc
confytome openapi -c confytome.json -f src/routes/*.js

# Generate using project config
confytome generate

Plugin Management Commands

# List all available generators
confytome generators

# Get detailed generator information
confytome info <generator-name>

# Validate generator dependencies
confytome validate

# Run specific generators
confytome run <generator1> <generator2>

# Run all spec consumer generators
confytome run-all

⚙️ Configuration

Project Configuration (confytome.json)

{
  "serverConfig": "./serverConfig.json",
  "inputFiles": [
    "src/routes/**/*.js",
    "src/models/**/*.js"
  ],
  "outputDir": "./docs",
  "excludeBrand": false
}

Server Configuration (serverConfig.json)

{
  "info": {
    "title": "My API",
    "version": "1.0.0",
    "description": "API documentation"
  },
  "servers": [
    {
      "url": "https://api.example.com",
      "description": "Production server"
    }
  ]
}

🏗️ Plugin-First Architecture

The core package implements a plugin-based approach with automatic discovery and dependency injection:

Plugin Registry System

• Automatic Discovery - Scans workspace packages and external npm modules
• Manifest Validation - Validates plugin compatibility and dependencies
• Dynamic Loading - Loads generators on-demand with proper error handling

Service Layer

• BrandingService - Consistent branding across all generators
• VersionService - Centralized version management
• TemplateService - Template processing and management

Generator Factory

• Dependency Injection - Provides services to generator instances
• Error Handling - Comprehensive error reporting and recovery
• Plugin Isolation - Safe execution environment for external plugins

📦 Generated Files

| File | Description | Size | |------|-------------|------| | api-spec.json | OpenAPI 3.1.0 specification | ~25KB | | confytome.json | Project configuration | ~1KB | | serverConfig.json | API server configuration | ~2KB |

💡 Usage Examples

Basic OpenAPI Generation

# From JSDoc comments in your routes
confytome openapi \\
  --config ./confytome.json \\
  --files "src/routes/*.js"

Advanced Plugin Usage

# Run specific generators
confytome run html markdown

# Get plugin information
confytome info html

# List all available plugins
confytome generators

Programmatic Usage

import { GeneratorRegistry } from '@confytome/core/services/GeneratorRegistry.js';
import { GeneratorFactory } from '@confytome/core/services/GeneratorFactory.js';

// Initialize registry
const registry = new GeneratorRegistry();
await registry.initialize();

// Create generator instance
const htmlGenerator = await GeneratorFactory.createGenerator('html', './docs');
await htmlGenerator.generate();

🧪 Plugin Development

Creating New Generators

import { SpecConsumerGeneratorBase } from '@confytome/core/utils/base-generator.js';

export class MyGenerator extends SpecConsumerGeneratorBase {
  constructor(outputDir, services) {
    super('my-generator', 'Generating custom format', outputDir, services);
  }

  async generate() {
    return this.generateDocument('myformat', 'api-docs.myformat', (spec, services) => {
      // Your generation logic here
      return this.processOpenAPISpec(spec);
    });
  }
}

Plugin Manifest (confytome-plugin.json)

{
  "name": "my-generator",
  "type": "spec-consumer",
  "description": "My custom documentation generator",
  "main": "./generate-my-format.js",
  "className": "MyGenerator",
  "version": "1.0.0",
  "standalone": true
}

🔧 API Reference

Core Services

GeneratorRegistry

const registry = new GeneratorRegistry();
await registry.initialize();

// Get all generators
const generators = registry.getAllGenerators();

// Validate generator
const validation = registry.validateGenerator('html');

GeneratorFactory

// Create generator instance
const generator = await GeneratorFactory.createGenerator('html', './docs', options);

// Execute generator
const result = await GeneratorFactory.executeGenerator('markdown');

Service Layer

import { BrandingService, VersionService } from '@confytome/core/services/index.js';

// Access services in generators
const branding = new BrandingService({ excludeBrand: false });
const version = new VersionService();

🛠️ Development & Testing

Running Tests

# Run all core tests
npm run test:core

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

Development Scripts

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Regenerate CLI templates
npm run regenerate:cli

🔍 Debugging

Verbose Output

# Enable debug logging
DEBUG=confytome:* confytome openapi -c confytome.json

Common Issues

Plugin Not Found

# Validate plugin discovery
confytome generators

# Check plugin manifest
confytome info <plugin-name>

Generation Errors

# Validate dependencies
confytome validate

# Check input files
confytome openapi --files "src/**/*.js" --dry-run

🌟 Ecosystem Integration

@confytome/core works seamlessly with generator packages:

• @confytome/markdown - Confluence-friendly Markdown
• @confytome/html - Professional HTML documentation
• @confytome/swagger - Interactive Swagger UI
• @confytome/postman - Postman collections

External Plugins

Create external plugins following the confytome-plugin-* naming convention:

npm install confytome-plugin-custom
confytome run custom

📄 License

MIT License - see the LICENSE file for details.

Generate beautiful, comprehensive API documentation from your existing JSDoc comments in seconds.