How androidpoet/compose-guard works
ComposeGuard is a multi-module Kotlin repository centered on an IntelliJ Platform plugin for Android Studio/IntelliJ IDEA, with a small Android sample app used to demonstrate the plugin’s findings.
Top-level architecture
The repository is organized into three practical boundaries:
1. compose-guard/ — the core IntelliJ/Android Studio plugin
2. app/ — an Android demo application that showcases Compose rule violations
3. sample/ — standalone sample source used by tests and rule demonstrations
Supporting this are root Gradle build files, CI workflows, and packaging assets.
---
1) Plugin module: compose-guard/
This is the main product. It is packaged as an IntelliJ Platform plugin defined by src/main/resources/META-INF/plugin.xml.
Core responsibility
The plugin analyzes Kotlin source files containing Jetpack Compose code and surfaces rule violations directly in the IDE.
Main functional subsystems
• Rule engine
- Located under rules/
- Contains the domain model for a “Compose rule” and the rule registry
- Rules are grouped by category:
- naming
- modifiers
- parameters
- composables
- state
- effects
- performance
- stricter
- The registry acts as the catalog of all supported rules and is the main source of truth for what the plugin can detect.
• IDE analysis and presentation
- inspection/
- Implements IDE inspections for rule violations
- Includes a suppressor for built-in inspections related to ComposeGuard’s own findings
- annotator/
- Adds inline annotations/highlighting in editor text
- inlay/
- Provides inlay hints next to code, likely for compact rule badges/status indicators
- linemarker/
- Adds gutter markers for composable functions, matching the README’s red/orange/gray/green status indicators
• Quick fix system
- quickfix/
- Each rule category has dedicated code actions such as:
- rename composable / parameter
- add modifier or default value
- wrap state in remember
- move modifier / reorder parameters
- add key/contentType to lazy lists
- use lifecycle-aware collection
- suppress specific rule
- These are the remediation path from a detected violation back to editable source code
• Settings and configuration
- settings/
- Manages global enablement, display options, category-level toggles, individual rule toggles, and experimental rules
- This is the main boundary between plugin behavior and user preference
• Statistics and dashboard
- statistics/
- Collects violation counts and aggregates them for a tool window dashboard
- toolwindow/
- Exposes the “ComposeGuard Statistics” panel in the IDE
- This subsystem is separate from code analysis: it consumes violation data and presents project-wide trends
Data flow inside the plugin
The likely flow is:
1. IDE opens or edits Kotlin files
2. Plugin hooks into IDE analysis points
- inspections
- annotators
- inlay providers
- line marker providers
3. Compose-specific rules inspect PSI/UAST-like source structure
4. Violations are created with severity and metadata
5. Violations are rendered in multiple IDE surfaces
- editor highlighting
- gutter icons
- inline hints
- tooltips
6. If the user invokes a fix, a quick fix mutates source code
7. Statistics service records the violation for the dashboard
This creates a closed loop: detection → presentation → correction → aggregate reporting.
Architectural boundary: “analysis vs. UI”
A useful diagram boundary is to separate:
• Rule evaluation and violation generation
• IDE presentation and user interaction
• Fix application and statistics aggregation
That separation is visible in the module layout and helps explain how the plugin stays extensible: rules are independent of how findings are shown.
---
2) Android demo app: app/
This is a conventional Android application module, not the plugin itself.
Purpose
It serves as a showcase/demo environment for ComposeGuard rules. The source tree contains multiple Compose demos:
• AllRulesDemo.kt
• ComposableRulesDemo.kt
• ModifierRulesDemo.kt
• NamingRulesDemo.kt
• ParameterRulesDemo.kt
• StateRulesDemo.kt
These files provide concrete code patterns that trigger the plugin’s inspections. The app’s main entry point is sample/MainActivity.kt, with a Compose theme under sample/ui/theme/.
Role in the architecture
This module is best viewed as an example consumer of the plugin’s analysis capabilities. It is not part of the plugin runtime, but it provides realistic Compose source for manual validation and screenshots.
---
3) Sample sources: sample/
The sample/ComposeGuardTestSample.kt file is a test fixture-style source sample. It likely holds intentionally structured code that exercises many rules at once, supporting automated tests and rule metadata validation.
This is distinct from the Android app:
• app/ is a runnable UI demo
• sample/ is a source fixture for tests and rule verification
---
Rule taxonomy and behavior
The rule set is the heart of the repository. The README and file layout show these rule groups:
• Naming
- composable naming
- modifier naming
- CompositionLocal naming
- preview and multipreview naming
- event callback naming
• Modifiers
- required modifier parameters
- default modifier values
- modifier ordering
- modifier reuse and top-most placement
- avoid composed {}
• State
- remember state
- use type-specific mutable state
- hoist state
- avoid mutable state as parameter
• Parameters
- parameter ordering
- trailing lambda conventions
- explicit dependencies
- mutable type parameters
- ViewModel forwarding
• Composables
- content emission
- multiple content slots
- effect keys
- movable content
- preview visibility
• Stricter
- Material 2 usage detection
- unstable collections detection
• Experimental / performance
- lazy list key/contentType rules
- derived state candidate detection
- lifecycle-aware collection
- defer state reads
A good diagram would depict these as rule families feeding into the same detection pipeline, rather than as separate subsystems.
---
Quick fixes as a parallel output path
Each rule can optionally expose a matching quick fix. The quick fixes are not generic utilities; they are strongly tied to rule findings and implement specific refactor actions. This creates a direct mapping:
• violation detected by rule
• quick fix offered by IDE
• source code updated in place
That pairing is an important architectural feature because the plugin is not just diagnostic; it is corrective.
---
Configuration and suppression model
The plugin includes two important control planes:
• Global and per-category settings
- enable/disable the plugin
- toggle gutter icons and inlay hints
- enable/disable rule categories and individual rules
- optionally enable experimental rules
• Inline suppression
- specific rule suppressions are supported in source code
These form the main boundaries for controlling signal/noise in existing codebases.
---
Test architecture
The src/test tree is extensive and mirrors the rule structure closely. Tests are organized by feature area:
• rule registry and rule metadata tests
• per-category rule tests
• quick fix tests
• settings state tests
This indicates a highly modular architecture where each rule is expected to be independently testable, and each quick fix is expected to be tied to a corresponding rule scenario.
The test layout also suggests a strong emphasis on:
• rule completeness
• metadata correctness
• quick-fix behavior
• category grouping integrity
---
CI and build tooling
Relevant infrastructure that affects the architecture:
• Gradle Kotlin DSL at the root and module level
• GitHub Actions
- android.yml for Android/sample module work
- intellij-plugin.yml for plugin validation/building
• IntelliJ run configurations under .run/
• Spotless formatting configuration
• Version catalog in gradle/libs.versions.toml
These don’t change runtime behavior, but they define how the plugin and sample app are built, tested, and packaged.
---
How to draw the architecture diagram
A clear diagram for this repository should show:
• Kotlin source code in an IDE
- flowing into ComposeGuard plugin analysis
• Rule registry
- feeding multiple rule families
• Findings
- flowing outward to:
- editor highlights/annotations
- gutter markers
- inline hints
- tooltips
- statistics dashboard
- quick fixes
• Settings
- controlling which rules and UI surfaces are active
• Sample Android app
- acting as a consumer/demo source target
• Tests
- validating rules, fixes, and settings independently
The key architectural idea is that ComposeGuard is an IDE-native static analysis and remediation system for Jetpack Compose, with a modular rule engine and multiple presentation channels layered on top of the same violation model.
Main entry points: ComposeRuleRegistry.kt Rule registry · settings Settings · composeguard Rule tests · build.gradle.kts Gradle build
Components 17
Build & CI
Root build, formatting, and workflow automation.
- Gradle build · Root Gradle and dependency/version management for the multi-module repo.
build.gradle.kts - CI workflows · GitHub Actions and repository automation for Android and plugin validation.
.github/workflows - Docs · Repository documentation, changelog, release notes, and rule catalog.
README.md
ComposeGuard Plugin
The IntelliJ Platform plugin and its analysis pipeline.
- Plugin entry · IntelliJ Platform plugin descriptor and packaging boundary.
compose-guard/src/main/resources/META-INF/plugin.xml - Rule registry · Central catalog of ComposeGuard rules and shared rule model.
compose-guard/src/main/kotlin/io/androidpoet/composeguard/rules/ComposeRuleRegistry.kt - Analysis surfaces · IDE inspection, annotator, inlay, and line-marker integrations that render findings.
- Rule families · Grouped rule categories for naming, modifiers, parameters, composables, state, and stricter/performance checks.
- Quick fixes · Code actions that remediate rule violations in place.
compose-guard/src/main/kotlin/io/androidpoet/composeguard/quickfix - Settings · Global, per-category, and per-rule controls plus experimental rule toggles.
compose-guard/src/main/kotlin/io/androidpoet/composeguard/settings - Statistics · Violation counting and project-level statistics collection.
compose-guard/src/main/kotlin/io/androidpoet/composeguard/statistics - Dashboard · ComposeGuard statistics panel shown inside the IDE.
compose-guard/src/main/kotlin/io/androidpoet/composeguard/toolwindow
Demo App
Runnable Android sample used to showcase plugin findings.
- Android app · Runnable Compose demo application that showcases rule violations.
app/src/main/kotlin/io/androidpoet/composeguard/sample - Demo screens · Sample Compose screens that intentionally exercise rule categories.
app/src/main/kotlin/io/androidpoet/composeguard/sample/AllRulesDemo.kt - Main activity · Android entry point hosting the demo Compose content.
app/src/main/kotlin/io/androidpoet/composeguard/sample/MainActivity.kt - Theme · Compose theme used by the demo application.
app/src/main/kotlin/io/androidpoet/composeguard/sample/ui/theme/Theme.kt
Samples & Tests
Source fixtures and test coverage for rules, fixes, and settings.
- Rule tests · Tests covering rules, metadata, quick fixes, and settings behavior.
compose-guard/src/test/kotlin/io/androidpoet/composeguard - Test sample · Standalone source fixture used for rule verification and demonstrations.
sample/ComposeGuardTestSample.kt
Connections 19
- Gradle build → Plugin entry: builds · Root build config assembles the plugin module.
- Gradle build → Android app: builds · Root build config includes the Android demo module.
- CI workflows → Gradle build: validates · Workflows run build and verification tasks.
- Plugin entry → Rule registry: loads · The plugin descriptor anchors the runtime plugin components.
- Rule registry → Rule families: organizes · Registry groups the supported rule families.
- Rule registry → Analysis surfaces: feeds · Detected rules are consumed by IDE presentation layers.
- Analysis surfaces → Quick fixes: offers fixes · UI findings expose matching remediation actions.
- Settings → Rule registry: filters · Rule and category toggles constrain which rules participate.
- Settings → Analysis surfaces: controls · Settings govern editor affordances like highlighting and hints.
- Settings → Statistics: controls · Statistics and dashboard behavior are influenced by configuration.
- Analysis surfaces → Statistics: records · Findings are aggregated into violation statistics.
- Statistics → Dashboard: displays · Aggregated statistics are rendered in the dashboard tool window.
- Main activity → Demo screens: hosts · The activity hosts the sample Compose screens.
- Android app → Theme: uses · The app applies a shared Compose theme.
- Demo screens → Rule registry: triggers · Demo code is designed to activate ComposeGuard rules.
- Test sample → Rule tests: backs · Fixture source underpins automated rule and quick-fix tests.
- Rule tests → Rule registry: verifies · Tests validate rule metadata and detection behavior.
- Rule tests → Quick fixes: verifies · Tests validate source actions and remediation logic.
- Docs → Rule registry: describes · Documentation explains the rule catalog and plugin behavior.