npm package: @principal-ade/argdown-parser
Description: Server-side Argdown parsing utilities using @argdown/core
Author: Principal ADE Team
Latest version: 0.1.1

# @principal-ade/argdown-parser

Server-side Argdown parsing utilities using `@argdown/core`.

## Overview

This package provides utilities for parsing Argdown content on the server side. It wraps `@argdown/core` and exposes a simple API for processing Argdown text into structured data that can be consumed by visualization components.

> **Note:** The parsing functions only work in Node.js environments. The `@argdown/core` library has dependencies (Chevrotain parser, etc.) that are not browser-compatible.

## Installation

```bash
npm install @principal-ade/argdown-parser
```

## Usage

### Processing Argdown (Server-side only)

```typescript
import { processArgdown } from '@principal-ade/argdown-parser';

const argdownSource = `
# Climate Debate

[Climate Change is Real]: Scientific consensus supports this.
  + <Scientific Evidence>: Multiple studies confirm warming trends.
  - <Skeptic View>: Natural cycles could explain changes.
`;

const result = await processArgdown(argdownSource);

// result.response contains:
// - arguments: Map of argument objects
// - statements: Map of statement objects
// - relations: Array of relations between nodes
// - ast: The abstract syntax tree
```

### Importing Types Only (Browser-safe)

For browser/UI code that only needs the type definitions:

```typescript
import type { ArgdownMapData, ArgdownResponse } from '@principal-ade/argdown-parser/types';

// Use these types to define props, etc.
interface MyComponentProps {
  data: ArgdownMapData;
}
```

### Validating Argdown

```typescript
import { validateArgdown } from '@principal-ade/argdown-parser';

const result = await validateArgdown(argdownSource);

if (result.valid) {
  console.log('Argdown syntax is valid');
} else {
  console.error('Errors:', result.errors);
}
```

### Extracting Metadata

```typescript
import { extractMetadata } from '@principal-ade/argdown-parser';

const metadata = extractMetadata(argdownSource);

// metadata contains:
// - title: First heading text
// - speakers: Array of speaker IDs from #speaker-* tags
// - tags: Array of all tags found
```

## API

### `processArgdown(source, options?)`

Parses Argdown source text and returns structured data.

- `source`: Raw Argdown text
- `options`: Optional request options
- Returns: `Promise<ArgdownMapData>`

### `validateArgdown(source)`

Validates Argdown syntax.

- `source`: Raw Argdown text
- Returns: `Promise<ArgdownValidationResult>`

### `extractMetadata(source)`

Extracts metadata without full parsing.

- `source`: Raw Argdown text
- Returns: `ArgdownMetadata`

## Exports

### Main export (`@principal-ade/argdown-parser`)

- `processArgdown` - Parse Argdown text (Node.js only)
- `validateArgdown` - Validate syntax (Node.js only)
- `extractMetadata` - Extract metadata (Node.js only)
- All types

### Types-only export (`@principal-ade/argdown-parser/types`)

- `ArgdownMapData` - Output of parsing
- `ArgdownResponse` - Parsed response structure
- `ArgdownArgument` - Argument node
- `ArgdownStatement` - Statement node
- `ArgdownRelation` - Relation between nodes
- `ArgdownMetadata` - Extracted metadata
- `ArgdownValidationResult` - Validation result

## Integration with argdown-renderer

This package is designed to work with `@principal-ade/argdown-renderer`:

```typescript
// Server-side (API route, build script, etc.)
import { processArgdown } from '@principal-ade/argdown-parser';

const data = await processArgdown(argdownSource);
// Send `data` to the client as JSON

// Client-side (React component)
import { ArgdownRenderer } from '@principal-ade/argdown-renderer';

<ArgdownRenderer data={data} />
```

## License

MIT