@zachrizzo/code-y
TypeScript icon, indicating that this package has built-in type declarations

0.7.0 • Public • Published

Code-y: Your Complete Local-First AI-Powered Code Documentation Platform

Code-y is the most comprehensive, 100% local-first command-line tool and documentation platform for React, TypeScript, and JavaScript projects. It combines advanced static code analysis, AI-powered insights, and an interactive web interface to give you unprecedented visibility into your codebase. Everything runs on your machine - your code never leaves your workstation.

🔒 Privacy-First Philosophy

Your code stays on your machine. Code-y is designed with privacy as the foundation:

  • All AI processing happens locally via Ollama or your own OpenAI API key
  • Vector embeddings are generated and stored locally
  • No data transmission to external services (unless you explicitly configure OpenAI)
  • Complete offline capability with local AI models
  • Full control over your documentation and analysis data

🚀 Complete Feature Overview

🧠 Advanced Code Analysis Engine

Deep AST (Abstract Syntax Tree) Parsing

  • Multi-language Support: Full TypeScript (.ts, .tsx) and JavaScript (.js, .jsx) analysis
  • Nested Code Extraction: Discovers functions within functions, methods within classes, and complex component hierarchies
  • Entity Recognition: Automatically identifies and categorizes:
    • React Components (functional and class-based)
    • Functions and arrow functions
    • Classes and their methods
    • Interfaces and types
    • Constants and variables
    • Custom hooks

Comprehensive Relationship Mapping

  • Import/Export Analysis: Tracks all module dependencies and exports
  • Component Usage Detection: Identifies where components are rendered (JSX usage)
  • Method Call Tracking: Maps function and method invocations across files
  • Inheritance Relationships: Detects class extensions and interface implementations
  • Circular Dependency Detection: Identifies and warns about circular imports
  • Prop Drilling Analysis: Detects excessive prop passing through component hierarchies

Intelligent Duplicate Detection

  • Multi-level Similarity Analysis:
    • Exact duplicates (100% identical code)
    • Near duplicates (95%+ similarity with minor differences)
    • Structural similarity (same logic, different variable names)
    • Pattern-based similarity (similar algorithms or approaches)
  • Smart Deduplication: Automatically consolidates duplicate entities while preserving all file locations
  • Similarity Scoring: Uses advanced algorithms including:
    • Hash-based comparison for exact matches
    • Token-based Jaccard similarity
    • AST structure comparison
    • Code length and complexity analysis

🤖 Local AI-Powered Intelligence

Flexible AI Backend Options

  • Ollama Integration (Recommended): 100% local AI processing
    • Supports multiple models (Gemma, Llama, CodeLlama, etc.)
    • Automatic model management and downloading
    • No internet required after initial setup
  • OpenAI Integration: Optional cloud-based processing with your API key
  • LangFlow Workflows: Visual AI pipeline designer for custom workflows

Advanced Vector Similarity System

  • Semantic Code Search: Find code by meaning, not just keywords
  • FAISS Vector Database: High-performance similarity search with 768-dimensional embeddings
  • Nomic Embed Text Model: Specialized embedding model for code understanding
  • Cosine Similarity Scoring: Precise similarity measurements with configurable thresholds
  • Real-time Vector Generation: Automatic embedding creation during analysis

AI-Generated Documentation

  • Intelligent Descriptions: Context-aware explanations for components, functions, and methods
  • Prop Documentation: Automatic description generation for component properties
  • Code Explanation: Natural language explanations of complex code logic
  • Smart Caching: Avoids regenerating descriptions for unchanged code

📊 Interactive Documentation Interface

Multi-View Dashboard

  • Component Explorer: Browse all components with filtering and search
  • Function Library: Dedicated view for standalone functions
  • Class Browser: Object-oriented code exploration
  • Method Inspector: Deep dive into class and component methods

Advanced Visualization Tools

  • Interactive Relationship Graph:
    • Force-directed network visualization
    • Zoom, pan, and focus controls
    • Node filtering by type and connections
    • Real-time layout algorithms
  • Code Architecture Overview:
    • File structure visualization
    • Dependency flow diagrams
    • Component hierarchy trees
    • Import/export relationship maps

Comprehensive Search & Discovery

  • Global Search: Find any code entity across your entire project
  • Semantic Search: AI-powered search that understands code meaning
  • Advanced Filtering: Filter by file type, component type, method count, etc.
  • Similarity Explorer: Discover similar code patterns and potential refactoring opportunities

Code Quality Analysis

  • Duplicate Code Reports: Detailed analysis of code duplication with severity levels
  • Similarity Warnings: Identify potentially redundant implementations
  • Relationship Analysis: Understand component coupling and dependencies
  • Architecture Insights: High-level codebase structure analysis

💬 Intelligent Chat Interface

Context-Aware AI Assistant

  • Codebase-Aware Conversations: Chat about your specific code with full context
  • Natural Language Queries: Ask questions like "How does the Button component work?"
  • Code Explanation: Get detailed explanations of complex code sections
  • Refactoring Suggestions: AI-powered recommendations for code improvements

Advanced Chat Features

  • Session Memory: Maintains conversation context across interactions
  • Code References: Direct links to discussed code sections
  • Multi-model Support: Choose from different AI models for varied perspectives
  • Export Conversations: Save important discussions for team sharing

🛠️ Powerful CLI Interface

Main Commands

  • generate: Complete documentation generation and server startup
  • serve-ui: Start the documentation interface without regeneration
  • init: Initialize configuration files and setup
  • cleanup: Remove temporary files and AI environments
  • build: Build the documentation for deployment
  • start: Display help and available commands

Global Options

  • --cwd <path>: Set working directory (work on any project from anywhere)
  • --help: Comprehensive help system
  • --version: Version information

Generate Command Options

  • Project Configuration:

    • --root <path>: Specify project root directory
    • --port <number>: Set documentation server port (default: 3000)
    • --output <path>: Custom output directory for documentation files
  • AI Configuration:

    • --ollama-url <url>: Ollama server URL (default: http://localhost:11434)
    • --ollama-model <model>: Chat model selection (default: gemma:3b)
    • --ollama-embedding-model <model>: Embedding model (default: nomic-embed-text:latest)
    • --generate-descriptions: Enable AI description generation
    • --no-ai: Disable all AI features for basic documentation
  • Analysis Options:

    • --langflow-config <path>: Custom LangFlow configuration file
    • --cleanup-on-exit: Clean up temporary files when done
    • --keep-environment: Preserve Python virtual environment for faster subsequent runs

🔧 Advanced Configuration

Configuration File Support

  • codey.config.js: Main configuration file with full option support
  • Environment Variables: Override settings via environment variables
  • LangFlow Configuration: Visual AI workflow designer integration
  • Custom Embedding Models: Support for different AI models and providers

Flexible Architecture

  • Docker Integration: Automatic container management for AI services
  • Python Environment Management: Automatic virtual environment creation and management
  • Service Discovery: Automatic detection and configuration of AI services
  • Fallback Systems: Graceful degradation when AI services are unavailable

📈 Performance & Scalability

Optimized Processing

  • Incremental Analysis: Only reprocess changed files
  • Parallel Processing: Multi-threaded analysis for large codebases
  • Smart Caching: Intelligent caching of analysis results and AI responses
  • Memory Management: Efficient handling of large projects

Scalable Architecture

  • Batch Processing: Handle thousands of files efficiently
  • Streaming Analysis: Process large files without memory issues
  • Background Processing: Non-blocking AI operations
  • Resource Management: Automatic cleanup and optimization

🚀 Quick Start

Installation & Basic Usage

# Install globally
npm install -g code-y

# Generate documentation for current directory
npx code-y generate

# Generate with AI descriptions
npx code-y generate --generate-descriptions

# Work on a different project
npx code-y --cwd /path/to/project generate

# Start with custom configuration
npx code-y generate --langflow-config ./my-ai-config.json

Advanced Usage Examples

# Complete AI-powered analysis
npx code-y generate --generate-descriptions --ollama-model llama3:8b

# Basic documentation without AI
npx code-y generate --no-ai

# Custom output and port
npx code-y generate --output ./my-docs --port 8080

# Clean up after analysis
npx code-y cleanup

# Just serve existing documentation
npx code-y serve-ui --port 3001

📁 Project Structure

your-project/
├── documentation/           # Generated documentation
│   ├── docs-data/          # JSON data files
│   │   ├── component-index.json
│   │   ├── [component-slug].json
│   │   └── config.json
│   └── vector-db/          # Vector embeddings (if AI enabled)
├── codey.config.js         # Configuration file (optional)
├── langflow-config.json    # AI workflow configuration (optional)
└── docs-url.txt           # Quick access URL file

🔧 Configuration Options

codey.config.js Example

module.exports = {
  root: './src',
  output: './documentation',
  port: 3000,
  generateDescriptions: true,
  ollamaUrl: 'http://localhost:11434',
  ollamaModel: 'gemma:3b',
  ollamaEmbeddingModel: 'nomic-embed-text:latest',
  showCode: true,
  showMethods: true,
  showSimilarity: true,
  theme: 'light',
  exclude: [
    '**/node_modules/**',
    '**/dist/**',
    '**/.next/**'
  ],
  include: [
    '**/*.tsx',
    '**/*.jsx',
    '**/*.ts',
    '**/*.js'
  ]
}

🤝 Contributing

We welcome contributions! Please see our contributing guidelines for:

  • Code contributions and pull requests
  • Bug reports and feature requests
  • Documentation improvements
  • AI model integrations

📄 License

This project is licensed under a custom license. See the LICENSE file for details.

🔗 Links


Code-y: Where AI meets code analysis, all running locally on your machine.

Package Sidebar

Install

npm i @zachrizzo/code-y

Weekly Downloads

0

Version

0.7.0

License

SEE LICENSE IN LICENSE

Unpacked Size

4.12 MB

Total Files

231

Last publish

Collaborators

  • zachrizzo