@redserenity/code-to-markdown/README.md

A tool to extract code content from various file types and create a markdown document for AI to consume

# Code-to-Markdown

**Code-to-Markdown** is a command-line tool that extracts content from code files and converts it into Markdown format. It supports various programming languages (C#, TypeScript, Markdown, and generic file types), with options to extract full content or specific elements like interfaces. The tool can process files recursively or within a single directory, and optionally leverage AI (via OpenRouter) to generate summaries of the extracted code.

## Features
- Extract all content or interfaces from C#, TypeScript, and Markdown files.
- Support for custom file extensions with the `all` tool.
- Recursive or single-directory file processing.
- Optional AI-powered summarization using OpenRouter.
- Flexible execution via CLI arguments, configuration files, or interactive prompts.
- Output formatted as Markdown with file paths and optional summaries.

## Installation

```bash
npm install -g @redserenity/code-to-markdown
```

### Optional: Set Up OpenRouter API (for AI summarization):
Obtain an API key from [OpenRouter](https://openrouter.ai/).
Set the environment variable:
```bash
export OPENROUTER_API_KEY="your-api-key-here"
```

## Usage

The tool supports three modes of operation: CLI arguments, configuration file, and interactive prompts.

### 1. CLI Arguments
Run directly with arguments:
```bash
code-to-markdown [tool] <input directory> <output file> [options]
```
- **Example (Extract all TypeScript files)**:
  ```bash
  code-to-markdown typescript ./src ./output.md
  ```
- **Example (Extract interfaces from C# files, single directory)**:
  ```bash
  code-to-markdown csharp-interfaces ./src --single-dir ./output.md
  ```
- **Example (Generic extraction with extension)**:
  ```bash
  code-to-markdown all ./src ./output.md .txt
  ```

### 2. Configuration File
Use a `.codemarkdown.json` file for multiple jobs:
```bash
code-to-markdown --config [path/to/config]
```
- **Example Config File (`.codemarkdown.json`)**:
  ```json
  {
    "jobs": {
      "ts-full": {
        "tool": "typescript",
        "inputDir": "./src",
        "outputFile": "./ts-output.md",
        "singleDir": false,
        "useAI": true
      },
      "cs-interfaces": {
        "tool": "csharp-interfaces",
        "inputDir": "./src",
        "outputFile": "./cs-output.md",
        "singleDir": true
      }
    },
    "config": {
      "provider": "openrouter",
      "model": "gpt-3.5-turbo"
    }
  }
  ```
- **Run**:
  ```bash
  code-to-markdown --config
  ```

### 3. Interactive Mode
Launch without arguments for prompts:
```bash
code-to-markdown
```
Follow the interactive steps to select a tool, input/output paths, and options.

### Available Tools
- `all <extension>`: Extract all content from files with a specified extension.
- `csharp`: Extract all content from C# files (`.cs`).
- `csharp-interfaces`: Extract interfaces from C# files.
- `markdown`: Extract all content from Markdown files (`.md`).
- `typescript`: Extract all content from TypeScript files (`.ts`).
- `typescript-interfaces`: Extract interfaces from TypeScript files.

### Options
- `--single-dir`: Process only the specified directory (no recursion).
- `--help`: Display usage instructions.
- `--config [path]`: Use a configuration file (defaults to `.codemarkdown.json` in current directory).

## Output Format
The generated Markdown includes:
- **File Path**: Relative path to the input file.
- **Optional Summary**: AI-generated summary (if `useAI` is enabled).
- **Code Block**: Extracted content in a language-specific code block.

**Example Output**:
```markdown
## File Path: src/ai/aiConfig.ts
### Summary
This file defines a type for configuring an AI model with a provider and optional model specification.

```ts
export interface AIConfig {
    provider: string;
    model?: string;
}
``
```

## Development
1. **Clone the Repository**:
   ```bash
   git clone https://gitlab.com/RedSerenity/node/code-to-markdown.git
   cd code-to-markdown
   ```

2. **Install Dependencies**:
   Ensure you have [Node.js](https://nodejs.org/) installed, then run:
   ```bash
   npm install
   ```

3. **Build the Project**:
   Compile the TypeScript code:
   ```bash
   npm run build
   ```

## Project Structure
- **`src/ai/`**: AI-related modules for provider abstraction and OpenRouter integration.
- **`src/handlers/`**: Language-specific handlers for file processing (e.g., C#, TypeScript).
- **`src/libs/`**: Core utilities for CLI parsing, configuration loading, and file processing.
- **`src/main.ts`**: Entry point orchestrating execution modes.

## Requirements
- Node.js 16+.
- TypeScript (for development).
- OpenRouter API key (optional, for AI features).

## Contributing
Feel free to submit issues or pull requests to enhance functionality, add new language handlers, or improve AI integration.

## License
This project is licensed under the MIT License. See [LICENSE](./LICENSE) for details.