npm package: @goedelsoup/nx-weaver
Description: Nx plugin for OpenTelemetry Weaver integration
Latest version: 0.1.0

# Nx Weaver Plugin

An Nx plugin for integrating OpenTelemetry Weaver into your Nx workspace. This plugin provides executors and generators to validate, generate, and manage Weaver configurations and generated code.

## Features

- **Validate Executor**: Validate Weaver configuration files and schemas
- **Generate Executor**: Generate code from Weaver configurations
- **Docs Executor**: Generate documentation from Weaver configurations
- **Clean Executor**: Clean generated Weaver assets
- **Init Generator**: Initialize Weaver configuration in your workspace
- **Setup Project Generator**: Set up Weaver for specific projects

## Documentation

For comprehensive documentation, see the [Documentation Guide](docs/README.md).

- [Getting Started](docs/getting-started/) - Installation and basic setup
- [User Guide](docs/user-guide/) - Detailed usage instructions
- [API Reference](docs/api/) - TypeScript types and utilities
- [Examples](docs/examples/) - Real-world usage examples

## Installation

```bash
pnpm add @goedelsoup/nx-weaver
```

## Usage

### Initializing Weaver in Your Workspace

```bash
nx generate @goedelsoup/nx-weaver:init
```

This will create a default `weaver.yaml` configuration file in your workspace root.

### Setting Up Weaver for a Specific Project

```bash
nx generate @goedelsoup/nx-weaver:setup-project my-project
```

This will create a project-specific Weaver configuration and documentation.

### Running Executors

#### Validate Configuration

```bash
nx run my-project:validate
```

Options:
- `--config`: Path to the Weaver configuration file (default: `weaver.yaml`)
- `--schema`: Path to the schema file to validate against
- `--verbose`: Enable verbose output
- `--dryRun`: Perform a dry run without making changes

#### Generate Code

```bash
nx run my-project:generate
```

Options:
- `--config`: Path to the Weaver configuration file (default: `weaver.yaml`)
- `--output`: Output directory for generated files
- `--template`: Template to use for code generation
- `--verbose`: Enable verbose output
- `--dryRun`: Perform a dry run without making changes

#### Generate Documentation

```bash
nx run my-project:docs
```

Options:
- `--config`: Path to the Weaver configuration file (default: `weaver.yaml`)
- `--output`: Output directory for documentation files
- `--format`: Output format (`markdown`, `html`, or `json`)
- `--verbose`: Enable verbose output
- `--dryRun`: Perform a dry run without making changes

#### Clean Generated Files

```bash
nx run my-project:clean
```

Options:
- `--patterns`: File patterns to clean
- `--output`: Output directory to clean
- `--verbose`: Enable verbose output
- `--dryRun`: Perform a dry run without making changes

## Configuration

### Weaver Configuration File (`weaver.yaml`)

```yaml
version: "1.0"
name: "my-weaver-workspace"

# Component definitions
components:
  my-service:
    name: "my-service"
    type: "service"
    language: "typescript"
    path: "./src"

# Pipeline definitions
pipelines:
  my-pipeline:
    name: "my-pipeline"
    components: ["my-service"]

# Output configuration
output:
  directory: "./generated"
  format: "typescript"
```

### Project Configuration

Add Weaver targets to your `project.json`:

```json
{
  "targets": {
    "validate": {
      "executor": "@goedelsoup/nx-weaver:validate",
      "options": {
        "config": "weaver.yaml"
      }
    },
    "generate": {
      "executor": "@goedelsoup/nx-weaver:generate",
      "options": {
        "config": "weaver.yaml",
        "output": "generated"
      }
    },
    "docs": {
      "executor": "@goedelsoup/nx-weaver:docs",
      "options": {
        "config": "weaver.yaml",
        "output": "docs",
        "format": "markdown"
      }
    },
    "clean": {
      "executor": "@goedelsoup/nx-weaver:clean",
      "options": {
        "patterns": ["generated/**/*"]
      }
    }
  }
}
```