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

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

Optional: Set Up OpenRouter API (for AI summarization):

Obtain an API key from OpenRouter. Set the environment variable:

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:

code-to-markdown [tool] <input directory> <output file> [options]

• Example (Extract all TypeScript files):

  code-to-markdown typescript ./src ./output.md

• Example (Extract interfaces from C# files, single directory):

  code-to-markdown csharp-interfaces ./src --single-dir ./output.md

• Example (Generic extraction with extension):

  code-to-markdown all ./src ./output.md .txt

2. Configuration File

Use a .codemarkdown.json file for multiple jobs:

code-to-markdown --config [path/to/config]

• Example Config File (.codemarkdown.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:

  code-to-markdown --config

3. Interactive Mode

Launch without arguments for prompts:

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:

## 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:

   git clone https://gitlab.com/RedSerenity/node/code-to-markdown.git
   cd code-to-markdown

2. Install Dependencies: Ensure you have Node.js installed, then run:

   npm install

3. Build the Project: Compile the TypeScript code:

   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 for details.