English • 简体中文

| | | |

Shamash

Shamash is a JVM architecture enforcement tool that helps teams define, validate, and continuously enforce architectural boundaries. It prevents architecture drift in JVM codebases by catching forbidden dependencies and cycles early.

Use cases

• Stop layer violations (controller → repository, service → web, etc.)
• Detect dependency cycles and show a representative cycle path
• Catch module boundary breaks during refactors/migrations
• Generate SARIF/HTML/JSON/XML reports for CI/PR visibility

Two engines

• PSI (source): dashboards, suppressions, guided fixes
• ASM (bytecode): deterministic “what ships” verification + CI gates + exports

Try it in 60 seconds (IntelliJ)

• Download
• Tools → Shamash ASM Dashboard
• Create ASM Config (from Reference)
• Build (./gradlew assemble)
• Run ASM Scan → results + exports in .shamash/

---

Why two engines?

Use PSI when you want source-aware feedback (IDE-native dashboards, suppressions, guided fixes). Use ASM when you need build-artifact truth (bytecode-level reality, JAR visibility, CI-friendly scans).

Run both:

• PSI for day-to-day development feedback
• ASM for “what actually ships” bytecode verification

Both engines are configurable via

• ASM reads asm.yml
• PSI reads psi.yml

These YAML configs define roles, rules, scope, validation behavior, exports, and (when enabled) analysis outputs like graphs/hotspots/scores.

---

Demo (GIF)

---

What it covers

Show details

Architecture enforcement

• Roles (e.g., controller/service/repository) and placement rules
• Forbidden dependencies (role → role, package → package, module → module)
• Dependency cycles (with representative cycle paths)
• Config validation with clear, path-aware errors

Analysis outputs

• Dependency / call graph analysis (configurable granularity)
• Hotspots and scoring (architecture health indicators)
• Exportable reports (JSON / SARIF / HTML / XML)

Bytecode Analysis

• Dead code detection
• Deprecation / shadow usage detection
• Additional JVM internals visibility and advanced inspections

---

Documentation & Examples

Docs + Test Bed applications: ./docs/

---

Gradle kotlin DSL

See: Quick Start — Gradle Kotlin DSL

# one-time: generate the starter config in shamash/configs/asm.yml
gradlew shamashInit

# validate config
gradlew shamashValidate

# run scan gate (also runs on ./gradlew check now)
gradlew shamashScan
gradlew check

---

Quick Start (CLI + intellij plugin + gradle DSL)

See QUICK_START

More

JVM architecture enforcement in IDE + CI