npm package: @nimbus-ds/nimbus-context-sync
Description: Documentation building system for Nimbus
Latest version: 1.0.5

# Nimbus Documentation Build System

This is a TypeScript-based documentation build system for the Nimbus project. It handles building, updating, and synchronizing documentation with the API.

## Features

- Document changes detection based on content hashing
- API synchronization with CRUD operations
- MDX file parsing and processing for documentation
- Component props fetching from GitHub repositories
- Dry-run mode for local development
- Git integration for branch comparison
- TypeScript-based with proper type definitions
- Parametrizable file paths via command line arguments

## Structure

The system follows SOLID principles and is organized into several modules:

```
docs-build/
├── src/
│   ├── api/              - API interaction layer
│   ├── commands/         - Command implementations
│   ├── core/             - Core documentation processing
│   ├── hashing/          - Document hashing functionality
│   ├── services/         - External services like GitHub
│   ├── utils/            - Utility services like Git operations
│   ├── config.ts         - Configuration settings
│   ├── types.ts          - Type definitions
│   └── index.ts          - Main entry point
├── package.json
├── tsconfig.json
└── README.md
```

## Getting Started

### Prerequisites

- Node.js 14+ and Yarn
- Git

### Installation

```bash
cd docs-build
yarn install
```

### Build

```bash
yarn build
```

### Usage

To generate a preview of document changes:

```bash
yarn build:docs preview
```

To update document hashes and sync with the API:

```bash
yarn build:docs update
```

To parse MDX files and generate documentation chunks:

```bash
yarn parse-mdx
```

To preview MDX parsing changes without updating files:

```bash
yarn parse-mdx:preview
```

Use the `--force` flag to override dry-run mode in local development:

```bash
yarn build:docs update --force
```

### Custom File Paths

You can specify custom file paths for hash storage and document files:

```bash
yarn build:docs update --hashesFile=./custom-path/hashes.json --genDocumentsFile=./custom-path/documents.json
```

### Using Mock Hashes for Comparison

For development or testing, you can use a mock hashes file instead of comparing with the master branch:

```bash
# First initialize the mock hashes file (only needed once)
yarn init:mock

# Then run with the mock hashes file
yarn build:docs update --hashMocks=.docs-build/hash-mocks.json

# Or use the convenience script
yarn build:docs:mock
```

This is especially useful before a file is merged into the master branch when you need to test change detection.

When using the mock hashes feature:
1. On first run, an empty mock hashes file will be created if it doesn't exist
2. Changes will be detected compared to the mock hashes file, not the master branch
3. The mock hashes file will be updated with the current hashes after processing

For MDX parsing with mock hashes:
```bash
yarn parse-mdx:mock
```

## Environment Variables

The system uses the following environment variables:

- `DOCS_API_ENDPOINT` - The API endpoint for document operations
- `DOCS_API_KEY` - API authentication key (optional, if needed)
- `GITHUB_TOKEN` - GitHub token for API access (optional, but recommended)

## GitHub Actions Integration

This system is designed to be run from GitHub Actions. In the GitHub environment, it will automatically detect it's running in CI/CD and switch to production mode.

## Development

For local development, the system runs in dry-run mode by default, which prevents modifications to production files and API.

To force the system to make actual changes in development:

```bash
yarn build:docs update --force
```

## License

Internal - Nimbus Project