Shamash — Enforce architectural boundaries in JVM…

Pitch

Description

Comments

About this project

Shamash is a powerful JVM architecture enforcement tool that helps teams define, validate, and maintain architectural boundaries. With its dual engines—ASM for bytecode analysis and PSI for source code validation—Shamash delivers comprehensive insights and reports, making it easier to manage dependencies and architectural integrity throughout the development lifecycle.

Shamash is a powerful JVM architecture enforcement tool designed to assist development teams in defining, validating, and continuously enforcing architectural boundaries. With its dual-engine approach, Shamash offers both bytecode-level analysis and source code validation, ensuring comprehensive monitoring of architectural compliance.

Key Features

ASM (Bytecode Engine): Analyzes compiled .class files and (optionally) dependency JARs, detecting forbidden dependencies, cycles, coupling hotspots, and architectural drift without needing access to the source code.
PSI (Source Engine): Utilizes IntelliJ PSI to analyze source code, providing a strict YAML schema for defining rules, validating designs, and generating dashboards. It features suppressions, guided fixes, and exportable reports that enhance user experience in the development process.

Engine Use Cases

PSI for Development Feedback: Ideal for obtaining source-aware feedback during day-to-day development, including IDE-native dashboards and guided fixes.
ASM for Build Verification: Focused on ensuring that the built artifacts reflect the intended architectural design by analyzing bytecode directly, making it suitable for CI environments.

Both engines can be configured with respective YAML files:

ASM Configuration: asm.yml
PSI Configuration: psi.yml

Architecture Enforcement Capabilities

Define roles (e.g., controller, service, repository) and placement rules.
Identify forbidden dependencies between roles, packages, and modules.
Detect dependency cycles with clear, path-aware error reporting.

Advanced Analysis Outputs

Generate dependency and call graphs with configurable detail.
Monitor architectural health through hotspot detection and scoring.
Export comprehensive reports in various formats including JSON, SARIF, HTML, and XML.

Additional Features

Dead code and deprecation detection enhancing code quality.
Visibility into JVM internals and advanced inspections for deeper analysis.

Shamash is designed for integrated use, allowing teams to response effectively to architectural integrity challenges in both the development and CI/CD phases. For extensive documentation and hands-on examples, refer to the documentation directory. For a quick start guide, see the QUICK_START page.