# MORPH-SPEC API Documentation

This directory contains the API documentation for MORPH-SPEC Framework libraries.

## Available Documentation

### API Reference (`/api`)

Comprehensive API documentation generated from JSDoc comments in the source code.

**Libraries Documented:**
- **state-manager** - Feature state management, agents, checkpoints, outputs tracking
- **cost-calculator** - Azure infrastructure cost calculation from Bicep files
- **design-system-generator** - UI design system parsing and theme generation

**View Documentation:**
- Open `api/index.html` in your browser
- Or run `npm run docs:serve` to start a local server at http://localhost:8080

## Running Tests

### Run Tests

```bash
npm test
```

Runs all 85 unit tests with 100% pass rate.

### Run Tests with Coverage

```bash
npm run test:coverage
```

Generates coverage report (HTML + text + lcov). **Current coverage: 98.03%**

- **Statements:** 98.03%
- **Branches:** 88.74%
- **Functions:** 100%
- **Lines:** 98.03%

Coverage reports are generated in `coverage/` directory.

### Coverage Summary Only

```bash
npm run test:coverage:summary
```

Shows text summary without generating HTML report.

## Generating Documentation

### Build API Docs

```bash
npm run docs
```

Generates HTML documentation from JSDoc comments in `src/lib/` to `docs/api/`.

### Watch Mode

```bash
npm run docs:watch
```

Automatically regenerates documentation when source files change.

### Serve Locally

```bash
npm run docs:serve
```

Starts a local HTTP server at http://localhost:8080 to view documentation.

## Documentation Standards

### JSDoc Format

All library functions in `src/lib/` use JSDoc comments with:

- **@param** - Parameter descriptions with types
- **@returns** - Return value description with type
- **@throws** - Exceptions that may be thrown
- **@example** - Usage examples (when applicable)

**Example:**

```javascript
/**
 * Calculate cost of a single resource
 * @param {Object} resource - Resource object with type, sku, minReplicas
 * @param {string} resource.type - Azure resource type
 * @param {string} resource.sku - SKU name
 * @param {number} [resource.minReplicas] - Minimum replicas (Container Apps)
 * @returns {Object} Cost result with cost, warning, estimated, details
 * @throws {Error} If resource type is invalid
 */
export function calculateResourceCost(resource) {
  // Implementation
}
```

### Module-Level Documentation

Each library file starts with a block comment describing:

- Purpose and responsibilities
- Usage context (CLI commands, internal automation)
- Key features

**Example:**

```javascript
/**
 * MORPH-SPEC State Manager Library
 *
 * Manages state.json for tracking features, progress, agents, and checkpoints.
 * Used both by CLI commands and internal automation.
 */
```

## Updating Documentation

1. **Update JSDoc comments** in source files (`src/lib/*.js`)
2. **Regenerate docs:** `npm run docs`
3. **Review:** Open `docs/api/index.html`
4. **Commit:** Include updated `docs/api/` in your commit

## Template

Documentation is generated using the [docdash](https://github.com/clenemt/docdash) template for JSDoc, configured in `jsdoc.json`.

**Features:**
- Clean, modern design
- Full-text search
- Responsive layout
- Syntax highlighting
- Type definitions
- Source code links

## Links

- **GitHub:** https://github.com/lucasPolymorphism/morph-spec-framework
- **npm:** https://www.npmjs.com/package/@polymorphism-tech/morph-spec
- **Website:** https://polymorphism.com.br/morph-spec
