Skip to content

Latest commit

 

History

History
121 lines (82 loc) · 3.72 KB

README.md

File metadata and controls

121 lines (82 loc) · 3.72 KB

English • 简体中文

Shamash Logo

current release | install plugin | License | CI | Plugin Verify

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)

Shamash IntelliJ demo

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