chore: codebase refactoring and cleanup and documentation update (#1886)

Co-authored-by: AayushSaini101 <kumaraayush9810@gmail.com>
Co-authored-by: Chan <bot+chan@asyncapi.io>
Co-authored-by: Ashish Padhy <ashishpadhy1729@gmail.com>

Author: 3 people

DEVELOPMENT.md

@@ -28,16 +28,22 @@ npm install
 To run all tests locally:
 
 - CLI tests: `npm run cli:test`
+- Unit tests: `npm run unit:test`
 - Github action tests: `npm run action:test`
+- Single test file: `npm run test:one -- <path-to-test-file>`
 
 ### Adding tests
 
 1. Create new test files in the appropriate directory under `test/`:
+   - Unit tests: `test/unit/<category>/<name>.test.ts`
+   - Integration tests: `test/integration/<command>.test.ts`
 
 2. Follow the existing test patterns.
 
 3. Run your new tests using the commands mentioned above.
 
+> 📘 **For detailed debugging and testing guidelines**, see the [Debugging & Testing Guide](/docs/debugging-testing.md).
+
 ## Release process
 
 To release a major/minor/patch:
@@ -137,5 +143,9 @@ If you encounter any issues during development or testing, please check the foll
 1. Ensure you're using the correct Node.js version (24.0.0 or higher) and npm version (8.19.0 or higher).
 2. Clear the `node_modules` directory and reinstall dependencies if you encounter unexpected behavior.
 3. For Docker-related issues, make sure Docker is running and you have sufficient permissions.
+4. For permission errors, try: `sudo chown -R $(whoami) ./lib ./node_modules`
+5. For path alias issues, rebuild the project: `npm run build`
+
+> 📘 **For comprehensive debugging help**, see the [Debugging & Testing Guide](/docs/debugging-testing.md).
 
 If problems persist, please open an issue on the GitHub repository.

README.md

@@ -13,6 +13,7 @@ CLI to work with your AsyncAPI files. Currently under development, we are workin
 - [Installation](#installation)
 - [Usage](#usage)
 - [Architecture](#architecture)
+- [Debugging & Testing](#debugging--testing)
 - [Github Action](#github-action)
 - [Contributing](#contributing)
   * [Set up development environment](#set-up-development-environment)
@@ -30,6 +31,9 @@ The [usage guide](/docs/usage.md) provides information about different ways to u
 ## Architecture
 The [architecture guide](/docs/architecture.md) provides information about the architecture.
 
+## Debugging & Testing
+The [debugging & testing guide](/docs/debugging-testing.md) provides step-by-step instructions for debugging CLI commands, API endpoints, and services, along with comprehensive testing guidelines.
+
 ## Github Action
 
 The AsyncAPI CLI can be used as a GitHub Action. You can find more information in the [GitHub Action guide](https://www.asyncapi.com/docs/tools/cli/github-action).

docs/architecture.md

@@ -3,95 +3,150 @@ title: 'CLI Architecture'
 weight: 40
 ---
 
-The AsyncAPI CLI uses oclif (Open CLI Framework) as its core framework, which enables developers to build powerful and scalable command-line applications.
+# CLI Architecture
 
-**Structure of the AsyncAPI CLI**: The CLI is primarily divided into two components: commands and the core part.
+## Overview
 
-1. **Command Component**: The commands include all the necessary functionalities that help developers interact with features like creating new AsyncAPI projects, validating AsyncAPI files, formatting AsyncAPI files, and more.  
-2. **Core Component**: The core part of the CLI contains various utilities that facilitate the efficient creation of new commands.
+The AsyncAPI CLI is built with [oclif](https://oclif.io/) and provides both command-line operations and a REST API server for working with AsyncAPI specifications.
 
 ---
 
-### Detailed Explanation of Key Directories in the CLI
-
-#### `src/commands/`
-- **Purpose:** Implements the CLI commands available to the user.
-- **Subdirectories:**
-  - `config/`: Stores configuration-related files for commands.
-  - `generate/`: Generates typed models or other artifacts like clients, applications, or documentation using AsyncAPI Generator templates.
-    - **Files:**
-      - `fromTemplate.ts`: Contains logic for generating files using templates.
-      - `models.ts`: Defines the models used during generation.
-  - `new/`: Create a new AsyncAPI project, specification files, or templates for clients and applications.
-    - **Files:**
-      - `file.ts`: Handles file creation logic.
-      - `template.ts`: Manages templates for new projects.
-  - `start/`: Implements starting functionalities like launching a local server or studio.
-    - **Files:**
-      - `studio.ts`: Integrates with the AsyncAPI Studio.
-
-- **Standalone Files:**
-  - `bundle.ts`: Bundles one or multiple AsyncAPI documents and their references together.
-  - `convert.ts`: Converts AsyncAPI documents from older to newer versions or transforms OpenAPI/Postman-collection documents into AsyncAPI.
-  - `diff.ts`: Compares two AsyncAPI documents.
-  - `format.ts`: Converts AsyncAPI documents from any format to YAML, YML, or JSON.
-  - `optimize.ts`: Optimizes AsyncAPI documents for performance.
-  - `pretty.ts`: Beautifies the AsyncAPI spec file (indentation, styling) in place or outputs the formatted spec to a new file.
-  - `validate.ts`: Validates AsyncAPI documents for correctness.
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────┐
+│  Entry Points                                   │
+│  ┌──────────┐              ┌──────────┐         │
+│  │   CLI    │              │   API    │         │
+│  │  (oclif) │              │ (Express)│         │
+│  └────┬─────┘              └────┬─────┘         │
+└───────┼─────────────────────────┼───────────────┘
+        └───────────┬─────────────┘
+                    ▼
+        ┌───────────────────────┐
+        │   Domain Services     │
+        │  Validation, Generator│
+        │  Convert, Config      │
+        └───────────┬───────────┘
+                    ▼
+        ┌───────────────────────┐
+        │   Domain Models       │
+        │  Specification,Context│
+        └───────────┬───────────┘
+                    ▼
+        ┌───────────────────────┐
+        │   Utilities           │
+        │  Logger, Helpers      │
+        └───────────────────────┘
+```
 
 ---
 
-#### `src/core/`
-- **Purpose:** Provides foundational components and utilities for the CLI.
-- **Subdirectories:**
-  - `errors/`: Centralized error definitions.
-  - `flags/`: Defines CLI flags and their behavior.
-  - `hooks/`: Event hooks used for customization.
-  - `models/`: Core data models used across the application.
-  - `utils/`: Utility functions for common operations.
-
-- **Standalone Files:**
-  - `base.ts`: Base class or logic for CLI commands.
-  - `global.d.ts`: Global TypeScript definitions.
-  - `globals.ts`: Stores global variables and configurations.
-  - `parser.ts`: Parses AsyncAPI documents.
+## Directory Structure
+
+```
+src/
+├── apps/
+│   ├── cli/              # CLI commands & internals
+│   └── api/              # REST API (Express)
+├── domains/
+│   ├── models/           # Specification, Context
+│   └── services/         # Business logic
+├── errors/               # Custom errors
+├── interfaces/           # TypeScript types
+└── utils/                # Utilities
+```
 
 ---
 
-#### `test/`
-- **Purpose:** Implements the test suite for the CLI.
-- **Subdirectories:**
-  - `fixtures/`: Contains mock data or files for testing.
-  - `hooks/`: Tests related to hooks.
-  - `integration/`: Integration tests to verify end-to-end functionality.
-  - `system/`: System-level tests.
-  - `unit/`: Unit tests for individual modules or functions.
+## Core Components
+
+### CLI Application
+
+| Component | Description |
+|-----------|-------------|
+| **Entry Points** | `bin/run` (dev), `bin/run_bin` (prod) |
+| **Base Command** | Metrics, parser integration, error handling |
+
+**Commands:**
+- **Core:** `validate`, `convert`, `format`, `optimize`, `diff`, `bundle`
+- **Generation:** `generate client`, `generate models`, `generate fromTemplate`
+- **Config:** `config context`, `config analytics`, `config versions`
+- **Utility:** `new file`, `new template`, `start api|studio|preview`, `pretty`
+
+### API Server
+
+**Endpoints:** `/v1/validate`, `/v1/parse`, `/v1/generate`, `/v1/convert`, `/v1/bundle`, `/v1/diff`, `/v1/docs`, `/v1/help`, `/v1/version`
+
+**Features:** Express with Helmet security, CORS, compression, RFC 7807 error responses
+
+### Domain Services
+
+All services extend `BaseService` and return `ServiceResult<T>`:
+
+| Service | Purpose |
+|---------|---------|
+| `ValidationService` | Validates specs with Spectral, calculates scores |
+| `GeneratorService` | Generates code/models |
+| `ConvertService` | Converts between AsyncAPI/OpenAPI formats |
+| `ConfigService` | Manages CLI config and contexts |
+| `ArchiverService` | Creates ZIP archives |
+
+### Domain Models
+
+| Model | Purpose |
+|-------|---------|
+| **Specification** | Loads from file, URL, or context; auto-detects `asyncapi.json\|yml\|yaml` |
+| **Context** | Manages multiple AsyncAPI contexts; stored in `~/.asyncapi/` |
+
+### Error Classes
+
+`ContextError`, `SpecificationFileError`, `ValidationError`, `GeneratorError`, `DiffError`
 
 ---
 
-### Use Cases
+## Execution Flow
 
-1. **Generate AsyncAPI Artifacts:**
-   - Use the `generate` command to create client/server code, documentation, or other artifacts based on AsyncAPI templates.
+**CLI Command:**
+```
+User Command → oclif → Base Command → Domain Service → ServiceResult
+```
 
-2. **Create New Projects:**
-   - The `new` command helps users scaffold new AsyncAPI projects with predefined templates.
+**API Request:**
+```
+HTTP Request → Express → Controller → Domain Service → HTTP Response
+```
 
-3. **Validate AsyncAPI Documents:**
-   - The `validate` command ensures AsyncAPI documents conform to the specification.
+---
 
-4. **Optimize and Format Documents:**
-   - The `optimize` and `pretty` commands provide tools for improving document readability and performance.
+## Extension Points
 
-5. **Compare Documents:**
-   - The `diff` command enables comparison between two AsyncAPI documents to track changes.
+| Add | Steps |
+|-----|-------|
+| **New Command** | Create in `src/apps/cli/commands/`, extend `Command`, implement `run()` |
+| **New API Endpoint** | Create controller in `src/apps/api/controllers/`, register in `index.ts` |
+| **New Service** | Create in `src/domains/services/`, extend `BaseService`, return `ServiceResult<T>` |
 
-6. **Integration with AsyncAPI Studio:**
-   - The `start` command integrates with the AsyncAPI Studio for editing and visualizing documents.
+---
+
+## Configuration
 
-7. **Convert Between Formats:**
-   - The `convert` command supports converting AsyncAPI documents between formats like YAML and JSON.
+| Config | Location |
+|--------|----------|
+| CLI Context | `~/.asyncapi/contexts.json`, `~/.asyncapi/.current` |
+| Analytics | `~/.asyncapi-analytics` |
+
+**Environment Variables:**
+- `NODE_ENV` — `development` | `production` | `test`
+- `PORT` — API server port (default: 3000)
+- `ASYNCAPI_METRICS_*` — Metrics configuration
 
 ---
 
-This structure ensures the CLI is modular, scalable, and easy to maintain. Let me know if you need further clarification or additional details!
+## Technology Stack
+
+| Category | Technologies |
+|----------|--------------|
+| **Core** | oclif, TypeScript, Express |
+| **AsyncAPI** | @asyncapi/parser, generator, converter, bundler, diff, optimizer |
+| **Supporting** | winston, ajv, chalk, @clack/prompts |

docs/contributing-prs.md

@@ -0,0 +1,114 @@
+---
+title: 'Contributing via Pull Requests'
+weight: 50
+---
+
+# Contributing via Pull Requests
+
+## Getting Started
+
+1. **Open an issue first** (unless it's a trivial fix)
+2. **Set up environment** — Follow [DEVELOPMENT.md](../DEVELOPMENT.md)
+3. **Create a branch** — Use prefixes: `feat/`, `fix/`, `docs/`, `refactor/`, `test/`, `chore/`
+
+---
+
+## PR Title Format
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+| Type | Description | Release |
+|------|-------------|---------|
+| `feat:` | New feature | MINOR |
+| `fix:` | Bug fix | PATCH |
+| `docs:` | Documentation | None |
+| `chore:` | Maintenance | None |
+| `test:` | Tests only | None |
+| `refactor:` | Code refactoring | None |
+
+**Breaking changes:** Add `!` → `feat!:`, `fix!:`
+
+**Examples:**
+- ✅ `feat: add AsyncAPI 3.0 validation support`
+- ✅ `fix: resolve context loading with special characters`
+- ❌ `Added new feature`
+- ❌ `fix bug`
+
+---
+
+## PR Checklist
+
+**Before submitting:**
+- [ ] Branch synced with `main`
+- [ ] `npm run build` passes
+- [ ] `npm run cli:test` passes
+- [ ] `npm run lint` passes (max 5 warnings)
+- [ ] Documentation updated (if needed)
+
+**Code quality:**
+- [ ] Follows existing code patterns
+- [ ] TypeScript types used (avoid `any`)
+- [ ] Error handling implemented
+- [ ] Tests added for new functionality
+- [ ] No `console.log` or commented code
+
+---
+
+## Code Standards
+
+| Area | Guideline |
+|------|-----------|
+| **TypeScript** | Explicit types, interfaces for objects, prefer `const` |
+| **Organization** | Follow existing structure, use path aliases (`@/`, `@cli/`, `@domains/`) |
+| **Errors** | Use custom errors from `src/errors/`, return `ServiceResult<T>` from services |
+| **Commands** | Extend base `Command`, use domain services for business logic |
+
+---
+
+## Testing
+
+**Add tests for:**
+- New commands or API endpoints
+- Bug fixes (regression tests)
+- New domain services
+- Complex business logic
+
+```bash
+npm run cli:test      # All tests
+npm run unit:test     # Unit tests only
+```
+
+---
+
+## Best Practices
+
+| ❌ Avoid | ✅ Do |
+|----------|-------|
+| Large PRs (>500 lines) | Small, focused PRs |
+| Multiple concerns in one PR | One issue per PR |
+| Skipping tests | Comprehensive tests |
+| Hardcoded values | Externalize configuration |
+| Force push to main | Rebase instead of merge |
+
+---
+
+## Review Process
+
+1. CI runs automated checks
+2. Maintainers review code
+3. Address feedback promptly
+4. PR merged when approved
+
+---
+
+## Quick Reference
+
+```bash
+# Setup
+npm install && npx lefthook install
+
+# Before PR
+npm run build && npm run lint && npm run cli:test
+```
+
+**Quality over speed** — Write good code, tests, and documentation.