Vincian Code Analysis - VS Code Extension 🎨

Transform your code with the wisdom of Leonardo da Vinci's artistic principles

Vincian Code Analysis brings Leonardo da Vinci's 7 artistic principles to software development. Get real-time feedback on code quality through inline scores, contextual tips, and intelligent quick fixes—all inspired by the Renaissance master's approach to creating masterpieces.

✨ Features

🎯 Real-time Code Analysis

Analyze your TypeScript code through the lens of 7 timeless principles:

• Movement 🎯 - Code flow and complexity
• Balance ⚖️ - Code distribution and structure
• Proportion 📏 - Right-sizing of functions and classes
• Contrast 🔍 - Clear distinctions and naming
• Unity 🔗 - Cohesion and single responsibility
• Simplicity 🎨 - Less is more, avoiding over-engineering
• Perspective 🏗️ - Architectural view and documentation

💡 Inline Intelligence

Hover to Learn:

• Hover over any code element to see relevant Vincian scores
• Get context-aware tips based on what you're hovering over
• See visual score bars (▰▰▰▰▰▰▰▰▱▱) at a glance
• Access quick actions directly from the tooltip

CodeLens Badges:

• File-level score displayed at the top of every file
• Function-level complexity warnings with "Simplify" buttons
• Class-level cohesion alerts
• Critical issue counter with "Fix All" action

🔧 Smart Quick Fixes

Movement Principle:

• Extract nested logic to separate functions
• Flatten deeply nested conditions with early returns
• Convert callbacks to async/await

Simplicity Principle:

• Extract magic numbers to named constants
• Remove unused imports
• Reduce abstraction layers

Contrast Principle:

• Rename cryptic variables to descriptive names
• Add type annotations for clarity
• Suggest better naming alternatives

Proportion Principle:

• Split large functions into smaller ones
• Introduce parameter objects for many parameters
• Split oversized classes

Unity Principle:

• Split classes by cohesion
• Move methods to appropriate classes
• Improve single responsibility

Perspective Principle:

• Generate JSDoc documentation templates
• Break circular dependencies
• Reorganize module structure

📊 Visual Score Report

View detailed analysis in a beautiful webview:

• Overall score with letter grade (A-F)
• Breakdown by each of the 7 principles
• Prioritized recommendations
• Confidence level and metadata
• Actionable next steps

🚀 Getting Started

Installation

1. Open VS Code
2. Press Ctrl+P (or Cmd+P on Mac)
3. Type: ext install aimastery-vincian-analysis
4. Press Enter

Or search for "Vincian Code Analysis" in the Extensions marketplace.

First Steps

1. Open a TypeScript file

2. See the magic happen:

   • Status bar shows: $(star) Vincian
   • Hover over any code to see scores
   • Look for CodeLens badges above functions/classes
   • Yellow squiggles indicate improvement opportunities

3. Analyze your code:

   • Press Ctrl+Alt+V to analyze the current file
   • Or click the Vincian status bar item
   • Or use Command Palette: "Vincian: Analyze Current File"

4. Apply quick fixes:

   • Look for the 💡 lightbulb icon
   • Press Ctrl+. to open quick fixes
   • Select a Vincian action to improve your code

📖 Usage Examples

Example 1: Fixing Complex Functions

Before:

function processData(data) {
  if (data) {
    if (data.valid) {
      if (data.type === 'user') {
        if (data.active) {
          return data.id;
        }
      }
    }
  }
  return null;
}

Hover shows: Movement score: 42/100 ⚠️ Tip: "This function might be too complex. Consider extracting smaller functions."

Click "Simplify" → Apply quick fix

After:

function processData(data: UserData): string | null {
  if (!data) return null;
  if (!data.valid) return null;
  if (data.type !== 'user') return null;
  if (!data.active) return null;
  return data.id;
}

New score: Movement: 88/100 ✅

Example 2: Extracting Magic Numbers

Before:

function retry() {
  for (let i = 0; i < 3; i++) {  // Hover over "3"
    // ... retry logic
  }
}

Hover shows: Simplicity score: 65/100 💡 Tip: "Extract this magic number to a named constant for better clarity."

Click "Extract to constant" → Enter name → "MAX_RETRIES"

After:

const MAX_RETRIES = 3;

function retry() {
  for (let i = 0; i < MAX_RETRIES; i++) {
    // ... retry logic
  }
}

Example 3: Improving Poor Names

Before:

function f(x, y) {  // Hover over "f"
  return x * y;
}

Hover shows: Contrast score: 35/100 ⚠️ Tip: "Use descriptive names that explain the purpose, not just the type."

Click "Rename to descriptive name" → Use VS Code rename

After:

function calculateArea(width: number, height: number): number {
  return width * height;
}

⌨️ Keyboard Shortcuts

Shortcut	Action
Ctrl+Alt+V	Analyze Current File
Ctrl+.	Open Quick Fix menu (when on issue)
Click status bar	View full Vincian report

⚙️ Configuration

Configure Vincian Analysis in VS Code settings:

{
  // Enable/disable automatic analysis on file save
  "vincian.autoAnalyze": true,

  // Show score in status bar
  "vincian.showInStatusBar": true,

  // Customize principle weights (advanced)
  "vincian.weights": {
    "movement": 1.0,
    "balance": 1.0,
    "proportion": 1.0,
    "contrast": 1.0,
    "unity": 1.0,
    "simplicity": 1.0,
    "perspective": 1.0
  }
}

🎨 The 7 Principles Explained

1. Movement (Code Flow) 🎯

Evaluates how smoothly code flows, measuring:

• Cyclomatic complexity - Avoid spaghetti logic
• Nesting depth - Keep it flat with early returns
• Function length - Break down complex operations

Good Movement:

// Early returns keep flow simple
if (!user) return null;
if (!user.isActive) return null;
return user.profile;

2. Balance (Code Distribution) ⚖️

Ensures even distribution of responsibilities:

• File size balance - No monster files
• Module organization - Even distribution of code
• Conditional balance - Symmetry in if/else branches

3. Proportion (Right-Sizing) 📏

Everything has its natural size:

• Function size - 10-50 lines ideal
• Class size - Under 300 lines
• Parameter count - Max 3-4 parameters
• Line length - Readable width

4. Contrast (Clarity) 🔍

Clear distinctions make code readable:

• Naming quality - Descriptive vs cryptic
• Type annotations - Explicit types
• Visibility modifiers - Clear encapsulation

Good Contrast:

// Clear, descriptive names
const MAX_LOGIN_ATTEMPTS = 3;
function validateUserCredentials(username: string): boolean

5. Unity (Cohesion) 🔗

All parts work together toward one purpose:

• LCOM4 metric - Class cohesion
• Single Responsibility - One reason to change
• Method cohesion - Related methods grouped

Good Unity:

// UserManager only handles users
class UserManager {
  private users: User[] = [];

  addUser(user: User): void { }
  removeUser(id: string): void { }
  findUser(id: string): User | undefined { }
}

6. Simplicity (Less is More) 🎨

Avoid over-engineering:

• Magic numbers - Extract to constants
• Dead code - Remove unused imports/variables
• Abstraction layers - No unnecessary complexity

7. Perspective (Architecture) 🏗️

The big picture:

• Documentation coverage - JSDoc for public APIs
• Circular dependencies - Avoid import cycles
• Module depth - Shallow import hierarchies

📊 Scoring System

Overall Score Calculation

Overall = Weighted average of all 7 principles

Grade Scale

Score	Grade	Meaning
90-100	A	Excellent - Da Vinci would approve!
80-89	B	Good - Minor improvements possible
70-79	C	Acceptable - Some refactoring recommended
60-69	D	Needs work - Multiple issues to address
0-59	F	Critical - Significant refactoring needed

Confidence Level

Each score includes a confidence percentage:

• 90-100%: High confidence, robust analysis
• 70-89%: Good confidence, reliable results
• 50-69%: Moderate confidence, use with judgment
• <50%: Low confidence, manual review recommended

🧪 Testing

Vincian Code Analysis includes 60+ tests:

• 45 unit tests (HoverProvider, CodeLensProvider, CodeActionProvider)
• 15 integration tests (full extension workflows)
• Test fixtures with real examples
• Performance benchmarks

Run tests:

npm test

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/yourusername/vincian-analyzer.git
cd vincian-analyzer

# Install dependencies
npm install

# Build
npm run compile

# Run in development
# Press F5 in VS Code to launch Extension Development Host

📝 Changelog

See CHANGELOG.md for version history.

🐛 Known Issues

• CodeLens uses simple regex-based function/class detection (AST-based detection coming in v9.0)
• Extract constant quick fix requires manual user input for constant name
• Webview report doesn't auto-update on file changes (requires re-analysis)

Report issues: GitHub Issues

🗺️ Roadmap

v9.0 - AST Power (Q2 2025)

• Full AST-based transformations
• Preview before apply
• Multi-file refactoring

v10.0 - AI Enhancement (Q3 2025)

• AI-powered naming suggestions
• Custom rule definitions
• Learning from your codebase

v11.0 - Team Features (Q4 2025)

• Team score tracking
• Historical trend analysis
• Shared configuration profiles

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Inspired by Leonardo da Vinci's approach to creating masterpieces
• Built with VS Code Extension API
• Uses TypeScript ESTree for AST parsing
• Cyclomatic complexity algorithm by Thomas J. McCabe

💬 Support

• Documentation: Full docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@aimastery.example.com

---

Made with ❤️ by the AI Mastery team

"Simplicity is the ultimate sophistication." - Leonardo da Vinci