Documentation - ArchSentinel

Introduction

ArchSentinel is a powerful static analysis tool designed for developers and teams who prioritize Software Architecture. Unlike standard linters that focus on syntax and code style, ArchSentinel models your entire project as a directed graph to detect structural anomalies, architectural violations, and dependency cycles.

Whether you are implementing Clean Architecture, Hexagonal Architecture, Onion Architecture, or your own custom modular design, ArchSentinel ensures that your dependency rules are respected, preventing "Spaghetti Code" before it merges into your codebase.

Why ArchSentinel?

As projects grow, maintaining architectural integrity becomes increasingly difficult. New team members might inadvertently introduce dependencies that violate the core principles of your architecture (e.g., the Domain layer importing the Infrastructure layer).

ArchSentinel solves this by:

Providing Real-time Feedback: See violations directly in your editor as you type.
Visualizing Complexity: Understand your project's structure at a glance.
Preventing Technical Debt: Catch architectural erosion early.

Key Features

1. Boundary Enforcement

Define strict architectural rules. If a restricted layer is imported where it shouldn't be, ArchSentinel flags it immediately.

Real-time Linting: Red squiggles appear on forbidden imports.
Customizable Rules: Define rules that match your specific architecture.

2. Interactive Architecture Graph

Visualize your project's health with a physics-based, interactive graph.

Red Edges: Forbidden dependencies (Violations).
Yellow Edges: Suppressed/Ignored violations.
Gray Edges: Healthy, allowed connections.

3. Scientific Metrics (Instability)

ArchSentinel calculates Robert C. Martin's Instability Metric (I) for every file to help you identify volatile components.

Formula: I = FanOut / (FanIn + FanOut)

4. Circular Dependency Detection

Automatically detects dangerous cycles (e.g., A -> B -> C -> A) that can cause runtime errors, infinite loops, and testing nightmares.

Installation

Open Visual Studio Code.
Go to the Extensions view by clicking the square icon on the sidebar or pressing Ctrl+Shift+X.
Search for "ArchSentinel".
Click Install.
Reload VS Code to activate the extension.

Getting Started Automatically New in v1.0

ArchSentinel v1.0 introduces Smart Auto-Configuration. Instead of writing rules from scratch, let the extension detect your project structure.

Open the Command Palette (Ctrl+Shift+P).
Run ArchSentinel: Init / Auto-Detect.
The extension will scan your workspace for common patterns (e.g., src/domain, lib/infrastructure) and generate an optimized arch-rules.json file for you.

Configuration Guide

To start using ArchSentinel, you need to define your architectural rules. Create a file named arch-rules.json in the root of your workspace.

Example: Clean Architecture

{
  "rules": [
    {
      "scope": "src/domain",
      "forbidden": ["src/infrastructure", "src/ui", "react", "flutter"],
      "message": "❌ The Domain layer must remain pure and independent."
    },
    {
      "scope": "src/application",
      "forbidden": ["src/ui", "src/infrastructure/web"],
      "message": "⚠️ Application layer should not depend on UI details."
    }
  ]
}

Configuration Options

Property	Type	Description
scope	string	The file path or directory where this rule applies.
forbidden	string[]	List of paths or package names not allowed to be imported.
message	string	Custom error message to display.

Usage Guide

1. Interactive Architecture Graph

Visualize your project's health with the new interactive graph.

Focus Mode: Click on any node (file) to dim the rest of the graph and focus solely on its dependencies and dependents.
Smart Resolution: Fully supports relative paths (../) and package imports.

To open: Command Palette > ArchSentinel: Show Architecture Graph

2. Handling Violations (Quick Fix)

When ArchSentinel detects a forbidden import, it marks it with a red squiggle. You have two options:

Fix the Code

Refactor your code to remove the dependency (e.g., use Dependency Injection).

Suppress It

Use the Quick Fix (Lightbulb icon) or Ctrl+. to add // arch-ignore.

Understanding Metrics

ArchSentinel uses Instability (I) to measure the resilience of your components.

Interpreting the Score

I = 0 (Maximally Stable) No outgoing dependencies. Responsible and independent.
I = 1 (Maximally Instable) No incoming dependencies. Irresponsible and dependent.

Supported Languages

TypeScript .ts, .tsx

JavaScript .js, .jsx

Dart .dart

Python Planned

Contributing

Contributions are welcome! Visit the GitHub Repository.

ArchSentinel Documentation