1.0.0 • Published 7 months ago

codewrangler v1.0.0

Weekly downloads
-
License
Apache-2.0
Repository
github
Last release
7 months ago

CodeWrangler

CodeWrangler is an extensible documentation automation platform that transforms code repositories into structured knowledge bases. Built with a powerful plugin architecture, it enables seamless integration with AI services, documentation generators, and analysis tools.

Table of Contents

Overview

CodeWrangler is an intelligent documentation assistant that automatically creates comprehensive knowledge bases from your code repositories. It's designed to bridge the gap between your codebase and AI language models like ChatGPT and Claude, making it easier to have meaningful conversations about your code.

Key Features

  • 🌳 Smart Repository Scanning: Advanced file tree generation with intelligent filtering and customizable ignore patterns
  • šŸ”Œ Plugin Architecture: Extensible pipeline system supporting custom documentation workflows and integrations
  • šŸ¤– AI Integration Ready: Built-in support for LLM-powered documentation enhancement and code analysis
  • šŸ“¦ Template Engine: Flexible template system supporting multiple output formats and custom variables
  • ⚔ High Performance: Parallel processing and caching capabilities for efficient handling of large repositories
  • šŸ”„ Incremental Updates: Smart change detection for efficient documentation maintenance

Development Status and Demo

This library is currently in active development. The core functionality has been implemented, but there are still some features and improvements that are in progress. We welcome any feedback or contributions from the community as we work towards a stable release.

Demo

Quick Start

Installation

Supports Node.js 18.x and above

npm install -g codewrangler

Basic Usage

# Generate documentation for TypeScript files
cw "\.ts$" --output typescript-docs

# Watch mode with custom template
cw "\.js$" --template-dir ./my-templates --watch

# Generate documentation with AI analysis
cw "\.py$" --output python-docs --enable-ai-analysis

Template System

CodeWrangler uses a powerful templating system that supports customization at multiple levels.

Directory Structure

templates/
ā”œā”€ā”€ page.md          # Overall documentation template
ā”œā”€ā”€ directory.md     # Directory entry template
└── file.md         # File entry template

Template Variables

Page Template

# Project Documentation: {{PROJECT_NAME}}

## Overview

This documentation was automatically generated on {{GENERATION_DATE}}.

## Directory Structure

\`\`\`
{{DIRECTORY_STRUCTURE}}
\`\`\`

## File Contents

{{DIRECTORY_CONTENT}}

## Summary

- Total Files: {{TOTAL_FILES}}
- Total Directories: {{TOTAL_DIRECTORIES}}
- Total Size: {{TOTAL_SIZE}}

File Template

### File: {{NAME}}

- **Path:** {{PATH}}
- **Extension:** {{EXTENSION}}
- **Size:** {{SIZE}} bytes
- **Depth:** {{DEEP}}
- **Lines:** {{LINES}}

### Content:

\`\`\`{{EXTENSION}}
{{CONTENT}}
\`\`\`

Directory Template

### Directory: {{NAME}}

- **Path:** {{PATH}}
- **Size:** {{SIZE}} bytes
- **Files:** {{LENGTH}}
- **Total Files (including subdirectories):** {{DEEP_LENGTH}}
- **Depth:** {{DEEP}}

#### Contents:

{{CONTENT}}

Custom Templates

Create your own templates by placing them in a custom directory:

mkdir custom-templates
echo "# {{PROJECT_NAME}}" > custom-templates/page.md
cw "\.ts$" --template-dir ./custom-templates

Command Line Interface

Usage: cw [options] <pattern>

Arguments:
  pattern                         File pattern to match (e.g., "\.ts$")

Options:
  -V, --version                  Display version information
  -d, --dir <dir>               Directory to search (default: current)
  -o, --output <name>           Output file name (default: "output")
  -t, --template-dir <dir>      Custom templates directory
  -c, --config <path>           Config file path
  --watch                       Watch for file changes
  -h, --help                    Display help information

Configuration

Configuration File (codewrangler.json)

{
  "core": {
    "dir": "./src",
    "pattern": "\\.ts$",
    "outputFile": "documentation"
  },
  "templates": {
    "directory": "./templates",
    "variables": {
      "AUTHOR": "Your Name",
      "VERSION": "1.0.0"
    }
  },
  "plugins": {
    "tree-visualizer": {
      "enabled": true,
      "format": "ascii"
    },
    "compress": {
      "enabled": true
    },
    "ai-summary": {
      "enabled": true,
      "model": "gpt-4"
    },
    "relative-documentation": {
      "enabled": true
    }
  }
}

Plugin System

CodeWrangler supports plugins for extending functionality. Plugins can hook into various stages of the documentation process.

1. Repository Tree Visualizer

  • Generates visual and textual representations of repository structure
  • Features:
    • ASCII tree visualization
    • Interactive HTML tree view
    • Directory size analysis
    • Custom ignore patterns
    • Multiple export formats (ASCII, HTML, JSON)
  • Use Case: Quickly understand project structure and organization

2. Smart Prompt Engine

  • Enhances AI interactions by providing contextual code references
  • Features:
    • Links questions to specific code files and line numbers
    • Maintains conversation history with code context
    • Suggests relevant files for current discussion
    • Tracks code changes during conversation
    • Generates contextual prompts for better AI responses
  • Use Case: More efficient and context-aware AI assistance

3. Documentation Crawler

  • Automatically aggregates and indexes library documentation
  • Features:
    • Identifies project dependencies
    • Scrapes official documentation sites
    • Creates offline documentation cache
    • Integrates with popular package managers (npm, pip, composer)
    • Generates dependency graphs
  • Use Case: Centralized documentation access and dependency understanding

4. Environment Analyzer

  • Analyzes and reports on development environment configuration
  • Features:
    • Runtime environment detection
    • Installed tools and versions
    • System capabilities assessment
    • Configuration compatibility checks
    • Environment-specific recommendations
  • Use Case: Environment-aware assistance and troubleshooting

5. Code Summarizer

  • Creates concise versions of code files by removing non-essential parts
  • Features:
    • Smart comment preservation
    • Redundant code detection
    • Configuration file summarization
    • Custom summarization rules
    • Diff view support
  • Use Case: Focus on essential code components

Creating a Plugin (In development)

import { Plugin, BaseNode } from "codewrangler";

export class CustomPlugin implements Plugin {
  name = "custom-plugin";

  async beforeScan(options: ScanOptions): Promise<void> {
    // Pre-scan setup
  }

  async afterRender(content: string): Promise<string> {
    // Post-render modifications
    return modifiedContent;
  }
}

Using Plugins

const pipeline = new DocumentationPipeline()
  .use(new TypeScriptDocsPlugin())
  .use(new AIAnalysisPlugin())
  .use(new CustomPlugin());

await pipeline.process({
  input: "./src",
  pattern: ".ts$",
});

Advanced Usage

AI Integration Example

import { LangChain } from "langchain";

const pipeline = new DocumentationPipeline().use(
  new LangChainPlugin({
    prompt: `
      Analyze this codebase and provide:
      1. Architecture overview
      2. Key components
      3. Improvement suggestions
    `,
    model: "gpt-4",
  })
);

Custom Template Example

const customTemplate = new Template({
  content: `
    # {{PROJECT_NAME}}
    Author: {{AUTHOR}}
    
    ## Analysis
    {{AI_ANALYSIS}}
    
    ## Components
    {{COMPONENTS}}
  `,
});

Development

Prerequisites

  • Node.js 18+
  • TypeScript 4.5+
  • npm or yarn

Setup

# Clone repository
git clone https://github.com/aminesayagh/Code-Wrangler

# Install dependencies
cd codewrangler
npm install

# Build project
npm run build

# Run tests
npm test

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

License

Apache 2.0 License - See LICENSE for details.

Built with ā¤ļø by the CodeWrangler team

For more information, visit our Documentation. For check out the Demo For communicate with the team, visit our Discussions or Issues