Skip to content

docs: add timestamp annotations to all documentation headings #150

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
joshuaquek merged 1 commit into from
May 6, 2026
Merged

docs: add timestamp annotations to all documentation headings #150

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# ☁️ 🐋 CloudVoyager

<!-- Last updated: 2026-03-25 -->
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

Migrate your data from self-hosted SonarQube to SonarCloud — no re-scanning needed. This was done by reverse-engineering SonarScanner (scan report protobuf files) & then fully rebuilding everything from the ground up on Node.js.

CloudVoyager copies everything — projects, code issues, security hotspots, quality gates, quality profiles, permissions, and more — directly from SonarQube into SonarCloud. It is available as both a CLI tool and a Desktop app with a guided wizard interface.

<!-- Updated: 2026-02-19 -->
## ✅ Quick Start (Recommended)
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

**Choose your scenario:**

Expand All @@ -18,6 +18,7 @@ CloudVoyager copies everything — projects, code issues, security hotspots, qua
| Migrate **everything** from SonarQube to **multiple** SonarCloud orgs | [Full Migration — Multiple Orgs](docs/scenario-multi-org.md) |

## 🖥️ Desktop App (New!)
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

Prefer a visual interface? **CloudVoyager Desktop** provides a guided wizard UI — no terminal or config files needed. Includes a **Run History** sidebar for quick access to past migration results.

Expand Down Expand Up @@ -59,6 +60,7 @@ See the [Desktop App Guide](docs/desktop-app.md) for setup instructions and a wa

<!-- Updated: 2026-02-18 -->
## 🔥 Single Command Full Migration (Slightly Dangerous)
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

1. Download the latest release of CloudVoyager from the [releases page](https://github.com/sonar-solutions/cloudvoyager/releases).
2. Ensure that you have full admin access API tokens for your SonarQube server and your SonarCloud organization.
Expand All @@ -75,6 +77,7 @@ See the [Desktop App Guide](docs/desktop-app.md) for setup instructions and a wa

<!-- Updated: 2026-03-10 -->
## 🔄 Pause and Resume
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

All migrations support **automatic checkpointing**. Progress is saved after every phase (extract, build, encode, upload). If a migration is interrupted — whether by CTRL+C (graceful shutdown), a crash, or a network failure — simply re-run the same command to resume from where it left off. No data is lost or duplicated.

Expand All @@ -101,6 +104,7 @@ See the [Configuration Reference](docs/configuration.md#checkpoint-settings) for

<!-- Updated: 2026-03-19 -->
## 🔄 SonarQube Version Compatibility
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

CloudVoyager ships **four fully independent pipelines** — one per SonarQube version range. At runtime, `version-router.js` calls `/api/system/status`, detects the server version, and dynamically loads the matching pipeline. No special configuration is needed.

Expand All @@ -117,6 +121,7 @@ See [Backward Compatibility](docs/backward-compatibility.md) for technical detai

<!-- Updated: 2026-03-25 -->
## 🧪 CI / Regression Testing
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

Two independent workflows run on every push to `main`:

Expand All @@ -131,11 +136,13 @@ The regression suite tests all `migrate`, `sync-metadata`, and `verify` commands

<!-- Updated: 2026-02-19 -->
## 🛠️ Local Development
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

Want to build and test CloudVoyager locally? See the [Local Development Guide](docs/local-development.md) for step-by-step instructions.

<!-- Updated: 2026-04-01 -->
## 📚 Documentation
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

| Document | Description |
|----------|-------------|
Expand All @@ -155,6 +162,7 @@ Want to build and test CloudVoyager locally? See the [Local Development Guide](d

<!-- Updated: 2026-02-17 -->
## 📝 License
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

MIT

Expand Down
74 changes: 65 additions & 9 deletions docs/Audit & Error Events Logging Strategy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,21 @@
# Audit & Error Events Logging Strategy

<!-- last-updated="2026-05-07T01:15:00Z" updated-by="Claude" -->
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

This document describes the logging architecture, log levels, destinations, and audit trail implementation for CloudVoyager. All logging is handled through the centralized Winston-based logger at `src/shared/utils/logger/`.

---

## 1. Logging Architecture

<!-- <subsection-updated last-updated="2026-05-07T01:15:00Z" updated-by="Claude" /> -->
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

CloudVoyager uses [Winston](https://github.com/winstonjs/winston) as its logging framework, providing a flexible and extensible architecture for handling logs across all pipeline operations.

### Core Components

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

The logging system is split into three modules within `src/shared/utils/logger/`:

| File | Purpose |
Expand All @@ -24,6 +26,8 @@ The logging system is split into three modules within `src/shared/utils/logger/`

### Logger Initialization

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

The default logger is created with console transport and respects the `LOG_LEVEL` environment variable (defaults to `info`):

```javascript
Expand All @@ -46,7 +50,7 @@ const logger = winston.createLogger({

## 2. Log Levels

<!-- <subsection-updated last-updated="2026-05-07T01:15:00Z" updated-by="Claude" /> -->
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

CloudVoyager uses the standard severity levels defined by Winston. Each level has a specific use case within the migration pipelines.

Expand All @@ -59,6 +63,8 @@ CloudVoyager uses the standard severity levels defined by Winston. Each level ha

### Environment-Based Level Control

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

Set the log level via the `LOG_LEVEL` environment variable:

```bash
Expand All @@ -71,6 +77,8 @@ LOG_LEVEL=debug node migrate.js

### Usage Examples

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

```javascript
import logger from '../shared/utils/logger.js';

Expand All @@ -91,12 +99,14 @@ logger.debug(`Skipping project config for ${scProjectKey} (already applied)`);

## 3. Log Destinations

<!-- <subsection-updated last-updated="2026-05-07T01:15:00Z" updated-by="Claude" /> -->
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

CloudVoyager supports multiple log destinations, configurable based on environment and requirements.

### Console Transport

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

All logs are written to stdout by default with colorized output for readability:

```
Expand All @@ -107,6 +117,8 @@ All logs are written to stdout by default with colorized output for readability:

### File Transports

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

File logging is enabled by calling `enableFileLogging(commandName)`. This creates a timestamped directory under `migration-output/logs/` with four separate log files:

| File | Contents |
Expand All @@ -118,6 +130,8 @@ File logging is enabled by calling `enableFileLogging(commandName)`. This create

### Directory Structure

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

```
migration-output/
logs/
Expand All @@ -130,6 +144,8 @@ migration-output/

### Legacy Single File Transport

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

For ad-hoc logging, the `LOG_FILE` environment variable directs all logs to a single file:

```bash
Expand All @@ -140,10 +156,12 @@ LOG_FILE=/var/log/cloudvoyager.log node migrate.js

## 4. Structured Logging

<!-- <subsection-updated last-updated="2026-05-07T01:15:00Z" updated-by="Claude" /> -->
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

### Text Format

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

CloudVoyager uses a human-readable text format optimized for operator review:

```
Expand All @@ -159,6 +177,8 @@ With stack traces appended for errors:

### Format Examples

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

**Standard log entry:**
```
2026-05-07 01:15:00 [info]: Project JIRA-123 migrated successfully
Expand All @@ -174,6 +194,8 @@ Error: SonarQube API error

### JSON Extraction

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

For machine parsing, extract fields using standard text parsing:

```
Expand All @@ -190,12 +212,14 @@ For machine parsing, extract fields using standard text parsing:

## 5. Error Event Classification

<!-- <subsection-updated last-updated="2026-05-07T01:15:00Z" updated-by="Claude" /> -->
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

CloudVoyager defines a hierarchy of error types in `src/shared/utils/errors/`, all inheriting from the base `CloudVoyagerError` class.

### Error Class Hierarchy

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

```
CloudVoyagerError (base)
├── ConfigurationError <- Invalid configuration values
Expand All @@ -212,6 +236,8 @@ CloudVoyagerError (base)

### Base Error Class

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

```javascript
export class CloudVoyagerError extends Error {
constructor(message, statusCode = 500) {
Expand All @@ -225,6 +251,8 @@ export class CloudVoyagerError extends Error {

### API-Specific Errors

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

API errors include endpoint information for debugging:

```javascript
Expand All @@ -238,6 +266,8 @@ export class SonarQubeAPIError extends CloudVoyagerError {

### Error Logging Pattern

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

Errors are logged with context at the point of capture:

```javascript
Expand All @@ -257,12 +287,14 @@ try {

## 6. Audit Trail

<!-- <subsection-updated last-updated="2026-05-07T01:15:00Z" updated-by="Claude" /> -->
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

CloudVoyager logs specific events for compliance auditing and operational visibility.

### Migration Lifecycle Events

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

| Event | Level | Description |
|-------|-------|-------------|
| Migration start | `info` | Pipeline initialization with configuration |
Expand All @@ -275,6 +307,8 @@ CloudVoyager logs specific events for compliance auditing and operational visibi

### Audit Log Examples

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

**Project success:**
```
2026-05-07 01:15:00 [info]: Project JIRA-123 migrated successfully
Expand All @@ -292,6 +326,8 @@ CloudVoyager logs specific events for compliance auditing and operational visibi

### Step Tracking

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

Each project migration records step outcomes in `projectResult.steps`:

```javascript
Expand All @@ -310,6 +346,8 @@ const projectResult = {

### Compliance Recording

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

Failed steps are aggregated into a structured error log:

```javascript
Expand All @@ -325,12 +363,14 @@ if (failedSteps.length > 0) {

## 7. Log Rotation and Retention

<!-- <subsection-updated last-updated="2026-05-07T01:15:00Z" updated-by="Claude" /> -->
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> -->

CloudVoyager creates new log directories for each migration run, providing natural separation for rotation.

### Directory Naming Convention

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

Logs are stored in timestamped directories using ISO 8601 format (with colons/dots replaced):

```
Expand All @@ -341,6 +381,8 @@ migration-output/logs/2026-05-08T00-00-15/

### Rotation Strategy

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

| Aspect | Implementation |
|--------|----------------|
| Rotation trigger | New directory per `enableFileLogging()` call |
Expand All @@ -350,6 +392,8 @@ migration-output/logs/2026-05-08T00-00-15/

### Retention Recommendations

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

Since CloudVoyager does not implement automatic retention, it is recommended to:

1. **Set up external rotation** - Use `logrotate` on Linux or similar tools
Expand All @@ -369,6 +413,8 @@ Since CloudVoyager does not implement automatic retention, it is recommended to:

### Manual Cleanup

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

To clean up old logs manually:

```bash
Expand All @@ -378,6 +424,8 @@ find migration-output/logs -type d -mtime +30 -exec rm -rf {} +

### Disk Space Monitoring

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

Monitor log directory size to prevent disk exhaustion:

```bash
Expand All @@ -388,14 +436,20 @@ du -sh migration-output/logs/

## Quick Reference

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

### Importing the Logger

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

```javascript
import logger from '../shared/utils/logger.js';
```

### Enabling File Logging

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

```javascript
import { enableFileLogging } from '../shared/utils/logger.js';

Expand All @@ -404,14 +458,16 @@ enableFileLogging('migrate'); // Creates migration-output/logs/{timestamp}/clou

### Environment Variables

<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" />

| Variable | Default | Purpose |
|----------|---------|---------|
| `LOG_LEVEL` | `info` | Minimum log level to output |
| `LOG_FILE` | (none) | Single file for all logs |

### Log Level Quick Reference

- Use `error` for failures that prevent operation completion
<!-- <subsection-updated last-updated="2026-05-07T02:15:00Z" updated-by="Claude" /> that prevent operation completion
- Use `warn` for recoverable issues or partial successes
- Use `info` for significant milestones and configuration
- Use `debug` for diagnostic traces (not for production)
Loading