# Knowledge Module Utilities

## Wiki-Link Parser

### Overview

The `wiki-link-parser.ts` utility provides parsing of wiki-style `[[links]]` from markdown content. This is the foundation for the Knowledge Module's linking system.

### Features

- **Multiple Link Formats**: Supports title, slug, and display text variations
- **Position Tracking**: Returns exact positions for link replacement or highlighting
- **Code Block Awareness**: Skips links in code blocks (inline and fenced)
- **Escape Support**: Respects escaped brackets `\[[not a link]]`
- **Edge Case Handling**: Properly handles nested brackets, empty links, and malformed syntax

### Usage

```typescript
import { parseWikiLinks } from "./utils/wiki-link-parser";

const content = "See [[Main Page]] and [[Getting Started|start here]].";
const links = parseWikiLinks(content);

// Result:
// [
//   {
//     raw: '[[Main Page]]',
//     target: 'Main Page',
//     displayText: 'Main Page',
//     start: 4,
//     end: 17
//   },
//   {
//     raw: '[[Getting Started|start here]]',
//     target: 'Getting Started',
//     displayText: 'start here',
//     start: 22,
//     end: 52
//   }
// ]
```

### Supported Link Formats

#### Basic Link (by title)

```markdown
[[Page Name]]
```

Links to a page by its title. Display text will be "Page Name".

#### Link with Display Text

```markdown
[[Page Name|custom display]]
```

Links to "Page Name" but displays "custom display".

#### Link by Slug

```markdown
[[page-slug-name]]
```

Links to a page by its URL slug (kebab-case).

### Edge Cases

#### Nested Brackets

```markdown
[[Page [with] brackets]] ✓ Parsed correctly
```

Single brackets inside link text are allowed.

#### Code Blocks (Not Parsed)

```markdown
Use `[[WikiLink]]` syntax for linking.

\`\`\`typescript
const link = "[[not parsed]]";
\`\`\`
```

Links inside inline code or fenced code blocks are ignored.

#### Escaped Brackets

```markdown
\[[not a link]] but [[real link]] works
```

Escaped brackets are not parsed as links.

#### Empty or Invalid Links

```markdown
[[]]           ✗ Empty link (ignored)
[[]] ✗ Whitespace only (ignored)
[[Target]] ✓ Trimmed to "Target"
```

### Return Type

```typescript
interface WikiLink {
  raw: string; // Full matched text: "[[Page Name]]"
  target: string; // Target page: "Page Name"
  displayText: string; // Display text: "Page Name" or custom
  start: number; // Start position in content
  end: number; // End position in content
}
```

### Testing

Comprehensive test suite (100% coverage) includes:

- Basic parsing (single, multiple, consecutive links)
- Display text variations
- Edge cases (brackets, escapes, empty links)
- Code block exclusion (inline, fenced, indented)
- Position tracking
- Unicode support
- Malformed input handling

Run tests:

```bash
pnpm test --filter=@mosaic/api -- wiki-link-parser.spec.ts
```

### Integration

This parser is designed to work with the Knowledge Module's linking system:

1. **On Entry Save**: Parse `[[links]]` from content
2. **Create Link Records**: Store references in database
3. **Backlink Tracking**: Maintain bidirectional link relationships
4. **Link Rendering**: Replace `[[links]]` with HTML anchors

See related issues:

- #59 - Wiki-link parser (this implementation)
- Future: Link resolution and storage
- Future: Backlink display and navigation

## Markdown Rendering

### Overview

The `markdown.ts` utility provides secure markdown rendering with GFM (GitHub Flavored Markdown) support, syntax highlighting, and XSS protection.

### Features

- **GFM Support**: Tables, task lists, strikethrough, autolinks
- **Syntax Highlighting**: Code blocks with language detection via highlight.js
- **XSS Protection**: HTML sanitization using sanitize-html
- **Header IDs**: Automatic ID generation for headers (for linking)
- **Security**: Blocks dangerous HTML (scripts, iframes, event handlers)

### Usage

```typescript
import { renderMarkdown, markdownToPlainText } from "./utils/markdown";

// Render markdown to HTML (async)
const html = await renderMarkdown("# Hello **World**");
// Result: <h1 id="hello-world">Hello <strong>World</strong></h1>

// Extract plain text (for search indexing)
const plainText = await markdownToPlainText("# Hello **World**");
// Result: "Hello World"
```

### Supported Markdown Features

#### Basic Formatting

- **Bold**: `**text**` or `__text__`
- _Italic_: `*text*` or `_text_`
- ~~Strikethrough~~: `~~text~~`
- `Inline code`: `` `code` ``

#### Headers

```markdown
# H1

## H2

### H3
```

#### Lists

```markdown
- Unordered list
  - Nested item

1. Ordered list
2. Another item
```

#### Task Lists

```markdown
- [ ] Unchecked task
- [x] Completed task
```

#### Tables

```markdown
| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |
```

#### Code Blocks

````markdown
```typescript
const greeting: string = "Hello";
console.log(greeting);
```
````

#### Links and Images

```markdown
[Link text](https://example.com)
![Alt text](https://example.com/image.png)
```

#### Blockquotes

```markdown
> This is a quote
> Multi-line quote
```

### Security

The renderer implements multiple layers of security:

1. **HTML Sanitization**: Only allows safe HTML tags and attributes
2. **URL Validation**: Blocks `javascript:` and other dangerous protocols
3. **External Links**: Automatically adds `target="_blank"` and `rel="noopener noreferrer"`
4. **Task Lists**: Checkboxes are disabled to prevent interaction
5. **No Event Handlers**: Blocks `onclick`, `onload`, etc.
6. **No Dangerous Tags**: Blocks `<script>`, `<iframe>`, `<object>`, `<embed>`

### Testing

Comprehensive test suite covers:

- Basic markdown rendering
- GFM features (tables, task lists, strikethrough)
- Code syntax highlighting
- Security (XSS prevention)
- Edge cases (unicode, long content, nested structures)

Run tests:

```bash
pnpm test --filter=@mosaic/api -- markdown.spec.ts
```

### Integration

The markdown renderer is integrated into the Knowledge Entry service:

1. **On Create**: Renders `content` to `contentHtml`
2. **On Update**: Re-renders if content changes
3. **Caching**: HTML is stored in database for performance

See `knowledge.service.ts` for implementation details.