# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build and Test Commands

```bash
bundle install              # Install dependencies
bundle exec rake test       # Run tests
bundle exec rake rubocop    # Run linter
bundle exec rake            # Run both tests and linter

# Run a single test file
bundle exec ruby -Ilib:test test/paragraph_test.rb

# Run a specific test by name
bundle exec ruby -Ilib:test test/paragraph_test.rb -n test_paragraph_with_text
```

## Architecture

Ezdoc is a Ruby gem for creating .docx files using a DSL. The gem generates valid Office Open XML (OOXML) documents.

### Core Components

- **Document** (`lib/ezdoc/document.rb`): Entry point via `Document.create`. Includes the Builder module and maintains a collection of nodes.

- **Builder** (`lib/ezdoc/builder.rb`): DSL methods (`p`, `text`, `b`, `i`, `u`, `ul`, `ol`, `li`, `table`, `tr`, `td`). Uses a format stack for nested formatting and target tracking for content placement.

- **Nodes** (`lib/ezdoc/nodes/`): Document element representations (Paragraph, Run, List, ListItem, Table, TableRow, TableCell). All inherit from `Nodes::Base`.

- **Package** (`lib/ezdoc/package.rb`): Assembles the docx ZIP structure using rubyzip. Coordinates XML generation.

- **XML generators** (`lib/ezdoc/xml/`): Generate OOXML-compliant XML:
  - `DocumentXml`: Main content with paragraphs, lists, tables
  - `ContentTypes`: [Content_Types].xml
  - `Relationships`: .rels files
  - `Numbering`: numbering.xml for lists

### Data Flow

1. User calls DSL methods on Document
2. Builder creates Node objects, pushed to Document's `@nodes` array
3. On save, Package creates ZIP with XML generators producing each required file
4. XML generators use Nokogiri to build OOXML with proper namespaces

### Testing

Tests use Minitest. `EzdocTestHelpers` module provides helpers that create temp documents and extract XML for assertions.