Archit Search

🏛️ Intelligent Architecture Enforcement with AI-Powered Analysis

Features • Installation • Quick Start • Configuration • Commands

Archit Search is a comprehensive Visual Studio Code extension designed to prevent "Spaghetti Code" and maintain clean, scalable software architecture. By combining strict rule-based validation with AI-powered anomaly detection, this extension provides real-time feedback on architectural violations, helping development teams enforce best practices consistently.

🎯 Not just an import checker — Archit Search is a complete architecture enforcement platform with AI analysis, software metrics, deep cycle detection, quick fixes, and report generation.

📋 Table of Contents

• What Does Archit Search Do?
• Key Features
• Feature Comparison
• Supported Languages
• Installation
• Quick Start
• Configuration
• Commands
• Quick Fix Actions
• Software Metrics
• Architecture Reports
• Example Configurations
• Best Practices
• Troubleshooting
• License

What Does Archit Search Do?

Archit Search goes far beyond simple import validation. It's a complete architecture enforcement platform that includes:

Key Features

🕸️ Circular Dependency Detection

Direct Cycles (A ↔ B) Instantly identifies when File A imports File B and File B imports File A. These circular dependencies cause runtime errors, memory leaks, and maintenance nightmares.

Deep Multi-Level Cycles (A → B → C → D → A) Unlike basic linters, Archit Search uses depth-first search algorithms to detect complex cycles up to 20 levels deep. Find hidden architectural problems that other tools miss.

Example Detected Cycle:
UserController.js → AuthService.js → TokenManager.js → UserController.js
[Depth: 3, Files: 3]

🛡️ Architecture Layer Enforcement

Define clear boundaries between layers (Presentation, Domain, Infrastructure). The extension enforces unidirectional dependencies, preventing lower layers from importing upper layers.

{
  "architSearch.layers": [
    { "name": "Domain", "pattern": "**/domain/**" },
    { "name": "Application", "pattern": "**/services/**" },
    { "name": "Infrastructure", "pattern": "**/database/**" },
    { "name": "Presentation", "pattern": "**/pages/**" }
  ]
}

Result: Domain layer cannot import from Presentation layer.

🧠 AI-Powered Analysis

Statistical Anomaly Detection

Uses Z-Score analysis to detect files with unusual complexity. The AI engine learns from your codebase structure and identifies statistical anomalies.

• Vector Space Models — Tokenizes and vectorizes source code
• Z-Score Analysis — Identifies complexity outliers
• K-Nearest Neighbors — Classifies files by similarity

Semantic Path Analysis

The Smart Advisor analyzes file paths to detect Clean Architecture violations based on naming conventions.

⚠️ Suspicious: 'Data' layer importing from 'Presentation' layer
   Confidence: 95%
   File: models/User.js → pages/Dashboard.js

📦 High Coupling Detection (God Object Prevention)

Monitors the number of imports in each file. When a file exceeds the configured threshold, it triggers a warning indicating potential "God Object" anti-pattern.

{
  "architSearch.maxImports": 15
}

Warning: "High Coupling: 23 imports detected (threshold: 15). Consider splitting this file."

🔒 Module Encapsulation

Warns when internal module files are imported directly instead of through the module's public entry point (index.js or index.ts).

❌ import { utils } from '../utils/helpers/stringUtils'
✅ import { utils } from '../utils'

📁 Unused Import Detection

Identifies imports that are declared but never used in the file. Supports both ES6 import syntax and CommonJS require patterns.

• Reduces bundle size
• Improves code clarity
• Prevents dead code accumulation

⚡ Quick Fix Actions (Code Actions)

When violations are detected, the extension provides intelligent quick fix suggestions through the VS Code lightbulb menu:

📊 Software Metrics Calculator

Calculate industry-standard software metrics for your codebase:

📈 Architecture Report Export

Generate comprehensive architecture analysis reports in multiple formats:

Reports include project summary, dependency graph statistics, detected cycles, and actionable recommendations.

🌍 Multi-Language Localization

Full support for English and Thai languages. All UI elements update instantly when you change the language setting.

{
  "architSearch.language": "th"
}

Feature Comparison

Supported Languages

Archit Search analyzes import statements and dependencies across a wide range of programming languages:

Installation

From VS Code Marketplace

1. Open Visual Studio Code
2. Press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (macOS)
3. Search for "Archit Search"
4. Click the Install button

From VSIX File

1. Download the .vsix file from the releases page
2. Open VS Code
3. Press Ctrl+Shift+P and type "Install from VSIX"
4. Select the downloaded file

Quick Start

Step 1 — Open Your Project

Open your project folder in VS Code. Archit Search activates automatically when VS Code finishes loading.

Step 2 — Check Status Bar

Look at the bottom left corner. You'll see "Archit Search: Healthy 🟢" or the current health status.

Step 3 — View Violations

• Problems Panel — Press Ctrl+Shift+M to see detailed violation messages
• Archit Search Sidebar — Click the Archit Search icon in the Activity Bar

Step 4 — Configure Rules (Optional)

Create .vscode/settings.json to add custom rules:

{
  "architSearch.maxImports": 10,
  "architSearch.checkDeepCycles": true,
  "architSearch.layers": [
    { "name": "Domain", "pattern": "**/domain/**" },
    { "name": "Infrastructure", "pattern": "**/database/**" }
  ]
}

Step 5 — Use Quick Fixes

Click the 💡 lightbulb icon next to violations to see available fixes.

Configuration

All configuration is done through .vscode/settings.json in your project root.

Core Settings

{
  "architSearch.language": "en",
  "architSearch.maxImports": 15,
  "architSearch.checkCycles": true,
  "architSearch.checkDeepCycles": true,
  "architSearch.deepCycleMaxDepth": 10,
  "architSearch.enforceEncapsulation": true,
  "architSearch.enableAI": true,
  "architSearch.detectUnusedImports": false
}

UI Settings

{
  "architSearch.showMetricsInSidebar": true,
  "architSearch.autoExportReport": false,
  "architSearch.reportFormat": "html"
}

Architecture Layers

{
  "architSearch.layers": [
    { "name": "Domain", "pattern": "**/domain/**" },
    { "name": "Application", "pattern": "**/services/**" },
    { "name": "Infrastructure", "pattern": "**/database/**" },
    { "name": "Presentation", "pattern": "**/pages/**" }
  ]
}

Custom Rules

{
  "architSearch.rules": [
    {
      "source": "**/pages/**",
      "disallow": ["**/database/**"],
      "message": "UI components cannot access database directly"
    },
    {
      "source": "**/domain/**",
      "disallow": ["**/infrastructure/**", "**/pages/**"],
      "message": "Domain layer must remain pure"
    }
  ]
}

Complete Settings Reference

Commands

Access commands via Command Palette (Ctrl+Shift+P):

Quick Fix Actions

When you see a violation, click the 💡 lightbulb icon to access quick fixes:

For Circular Dependencies

For Layer Violations

For High Coupling

For Encapsulation Violations

Universal Actions

Software Metrics

Maintainability Index

Calculated using a simplified Halstead formula:

Instability Index (Robert C. Martin)

Formula: I = Ce / (Ca + Ce)

Coupling Metrics

• Afferent Coupling (Ca) — How many modules depend on this module
• Efferent Coupling (Ce) — How many modules this module depends on
• Total Coupling — Ca + Ce (lower is better)

Architecture Reports

Generate Report

1. Open Command Palette (Ctrl+Shift+P)
2. Type "Archit Search: Export Architecture Report"
3. Select report format (JSON, HTML, or Markdown)
4. Choose save location

Report Contents

• Metadata — Generation date, version info
• Project Summary — Files analyzed, health score, average metrics
• Dependency Graph — Total files, dependencies, average per file
• Circular Dependencies — List of detected cycles with depth
• Recommendations — Actionable suggestions for improvement

HTML Report Features

The HTML report includes a beautiful dark-themed dashboard with:

• Metric cards with visual indicators
• Cycle list with file paths
• Recommendation section
• Responsive design for all screen sizes

Example Configurations

Clean Architecture

{
  "architSearch.layers": [
    { "name": "Domain", "pattern": "**/domain/**" },
    { "name": "Application", "pattern": "**/application/**" },
    { "name": "Infrastructure", "pattern": "**/infrastructure/**" },
    { "name": "Presentation", "pattern": "**/presentation/**" }
  ],
  "architSearch.rules": [
    {
      "source": "**/domain/**",
      "disallow": ["**/infrastructure/**", "**/presentation/**"],
      "message": "Domain layer must remain pure"
    }
  ],
  "architSearch.maxImports": 10,
  "architSearch.checkDeepCycles": true
}

React Application

{
  "architSearch.layers": [
    { "name": "Hooks", "pattern": "**/hooks/**" },
    { "name": "Components", "pattern": "**/components/**" },
    { "name": "Pages", "pattern": "**/pages/**" },
    { "name": "Services", "pattern": "**/services/**" }
  ],
  "architSearch.rules": [
    {
      "source": "**/components/**",
      "disallow": ["**/pages/**"],
      "message": "Components should be reusable - don't import from pages"
    },
    {
      "source": "**/hooks/**",
      "disallow": ["**/pages/**", "**/components/**"],
      "message": "Hooks should not depend on UI components"
    }
  ],
  "architSearch.detectUnusedImports": true
}

NestJS Backend

{
  "architSearch.layers": [
    { "name": "Entity", "pattern": "**/entities/**" },
    { "name": "Repository", "pattern": "**/repositories/**" },
    { "name": "Service", "pattern": "**/services/**" },
    { "name": "Controller", "pattern": "**/controllers/**" }
  ],
  "architSearch.rules": [
    {
      "source": "**/entities/**",
      "disallow": ["**/services/**", "**/controllers/**"],
      "message": "Entities should not depend on upper layers"
    }
  ],
  "architSearch.maxImports": 12
}

Minimal Setup

{
  "architSearch.maxImports": 20,
  "architSearch.checkCycles": true,
  "architSearch.checkDeepCycles": true,
  "architSearch.enableAI": true
}

Best Practices

🎯 Define Layers Early

Establish architecture boundaries at the start of your project. It's easier to maintain rules than to fix spaghetti code later.

📐 Start with Loose Thresholds

Begin with higher maxImports (e.g., 20) and gradually lower it as your team adapts.

✍️ Use Meaningful Rule Messages

Write clear, actionable messages for violations:

{
  "message": "❌ UI cannot access database. Use a service layer instead."
}

📊 Review AI Insights Weekly

Treat AI suggestions as guidance, not absolute rules. Check the sidebar for anomaly reports.

🤝 Share Configuration

Commit .vscode/settings.json to version control so all team members have the same rules.

🚀 Gradual Adoption

For existing projects, enable features one at a time. Start with cycle detection before adding layer rules.

📝 Export Reports for Code Reviews

Generate HTML or Markdown reports before major code reviews or architecture discussions.

Troubleshooting

Extension Not Activating

• Ensure your workspace contains supported file types (.js, .ts, .py, etc.)
• Try reloading the window (Ctrl+Shift+P → "Developer: Reload Window")
• Check the Output panel for errors (View → Output → Select "Archit Search")

No Violations Showing

• Verify your settings.json syntax is valid JSON
• Check that glob patterns match your file structure
• Ensure the relevant checks are enabled (checkCycles, enableAI, etc.)

AI Not Providing Insights

• The AI engine needs time to learn (3+ seconds after opening)
• Ensure enableAI is set to true
• Check that you have enough files in your workspace (5+)

Metrics Showing Zero

• Metrics are calculated after the learning phase
• Wait for "Learning complete" notification
• Try running "Analyze Entire Project" command

Deep Cycles Not Detected

• Ensure checkDeepCycles is enabled
• The dependency graph is built during the learning phase
• Try increasing deepCycleMaxDepth if needed

Report Export Failed

• Check that you have write permissions to the target directory
• Ensure the workspace has been analyzed first
• Try a different format (JSON is simplest)

High Memory Usage

• Reduce deepCycleMaxDepth for very large projects
• Disable unused features like detectUnusedImports
• Exclude node_modules and other vendor directories

Technical Architecture

Archit Search is composed of modular components:

archit-search/
├── extension.js          # Main entry point
└── lib/
    ├── ImportParser.js       # Multi-language import parsing
    ├── RuleEngine.js         # Architecture rule validation
    ├── GraphAnalyzer.js      # Direct cycle detection (A↔B)
    ├── DeepCycleDetector.js  # Multi-level cycle detection
    ├── AIKernel.js           # Machine learning analysis
    ├── SmartAdvisor.js       # Semantic path analysis
    ├── MetricsCalculator.js  # Software metrics computation
    ├── UnusedImportDetector.js  # Unused import detection
    ├── QuickFixProvider.js   # Code action provider
    ├── ReportExporter.js     # Report generation
    ├── Visualizer.js         # Editor decorations
    ├── StatusBarManager.js   # Status bar UI
    ├── ArchitSidebarProvider.js  # Sidebar webview
    └── Localization.js       # i18n support

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting pull requests.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

See the LICENSE file for details.

Archit Search — Code with architectural confidence.

Made with ❤️ by Thirawat27

Report Bug • Request Feature