Skip to main content
Glama
README.md
<img src="docs/logo.svg" alt="" width="96" align="right">

# droidmap

[![CI](https://github.com/hussainshirazi/droidmap/actions/workflows/ci.yml/badge.svg)](https://github.com/hussainshirazi/droidmap/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/hussainshirazi/droidmap)](https://github.com/hussainshirazi/droidmap/releases/latest)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.hussainshirazi%2Fdroidmap-6e56cf)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.hussainshirazi/droidmap)
[![M8ven Score](https://m8ven.ai/badge/mcp/hussainshirazi/droidmap)](https://m8ven.ai/mcp/hussainshirazi/droidmap?s=readme)

**An Android-aware map of your project, for you, your pull requests and your AI coding agent.**

Generic code graphs see classes and calls. They do not see that:

- version 4 of your Room database has no migration to version 5, so users on 4 crash on update;
- an entity gained a column but the database version was not bumped, which crashes on update too;
- your migration test is named `migrationFrom1To4` but runs 1→2→3→4, while users on version 1 get `MIGRATION_1_4`, which no test runs;
- a change removed `Status.PAUSED`, but Room stored it by name in users' rows, which now crash when read;
- `navigate("settings")` points at a route no `NavHost` registers;
- a screen gets its `@HiltViewModel` with `viewModel()` instead of `hiltViewModel()`, and crashes when it opens;
- a ViewModel injects a repository that nothing binds, in Hilt or in Koin (a crash at runtime with Koin);
- a library added `ACCESS_NETWORK_STATE` to your merged manifest;
- a feature module gets `:core:data` through a convention plugin in `build-logic`, which your module rules forbid.

droidmap reads the Android wiring directly (Gradle, Room, Navigation, Hilt, Koin, the manifest, in Kotlin and Java) and turns it into a graph. Run its rules in CI, get a comment on every pull request saying what the change touches, ask it what depends on a class before you change it, and hand it to an AI agent over MCP.

It reads source files only: it never runs Gradle, never compiles your code and never sends anything anywhere. (The GitHub Action runs one Gradle task, for the merged manifest, only when you ask it to.)

![droidmap check and droidmap diff in a terminal](docs/demo.svg)

### On a real app

[Now in Android](https://github.com/android/nowinandroid) (35 modules, Hilt, Room, Navigation 3), on a laptop, in about 1.5 seconds each:

```console
$ droidmap check
warning room-migration-untested      core/database/src/main/kotlin/com/google/samples/apps/nowinandroid/core/database/NiaDatabase.kt:66
        NiaDatabase: 13 of 13 migration steps have no MigrationTestHelper test (1->2, 2->3, 3->4,
        4->5, 5->6, 6->7, 7->8, 8->9, 9->10, 10->11, 11->12, 12->13, 13->14)

1 warning
```

After a one-line change to `OfflineFirstTopicsRepository.syncWith` (output shortened):

```console
$ droidmap diff
Changed (1): OfflineFirstTopicsRepository (injectable)

Affected (what depends on the changed code):

  Screens: ForYouScreen, InterestsScreen, TopicScreen
  Navigation destinations: ForYouNavKey, InterestsNavKey, TopicNavKey
  ViewModels: ForYouViewModel, InterestsViewModel, TopicViewModel
  Dependency injection: DataModule.bindsTopicRepository, GetFollowableTopicsUseCase, SyncWorker
  Modules: :app, :app-nia-catalog, :core:data, :core:data-test, :core:domain, ... and 12 more

Tests that cover it (1): OfflineFirstTopicsRepositoryTest

$ droidmap diff --format tests
:core:data:test --tests com.google.samples.apps.nowinandroid.core.data.repository.OfflineFirstTopicsRepositoryTest
```

The last line goes straight to `./gradlew` in CI: one test class instead of the whole suite (see [Run only the tests a change can break](#run-only-the-tests-a-change-can-break)).

## Install

macOS or Linux:

```sh
curl -fsSL https://raw.githubusercontent.com/hussainshirazi/droidmap/main/install.sh | sh
```

Windows (PowerShell):

```powershell
irm https://raw.githubusercontent.com/hussainshirazi/droidmap/main/install.ps1 | iex
```

Homebrew: `brew tap hussainshirazi/droidmap https://github.com/hussainshirazi/droidmap` then `brew install droidmap`. Scoop: `scoop bucket add droidmap https://github.com/hussainshirazi/droidmap` then `scoop install droidmap/droidmap`.

Docker, for CI systems other than GitHub Actions (GitLab, Bitbucket, Jenkins, Bitrise): `docker run --rm -v "$PWD":/project ghcr.io/hussainshirazi/droidmap check` (from version 0.2.0).

Gradle (from version 0.3.0), in the root `build.gradle.kts`; then `./gradlew droidmapCheck` fails the build on errors:

```kotlin
plugins { id("io.github.hussainshirazi.droidmap") version "0.4.0" }

droidmap {
    failOn.set("warning")       // error (the default), warning, info or never
    mergedManifest.set(true)    // run each processReleaseMainManifest first: library permissions are checked too
}
```

Or download `droidmap.jar` from the [latest release](../../releases/latest) and run `java -jar droidmap.jar`. droidmap needs Java 17 or newer. The `droidmap` command uses `JAVA_HOME`, the `java` on your PATH, or else the Java that Android Studio brings, so with Android Studio installed there is nothing to set up. The jar is about 65 MB because it carries the Kotlin compiler's parser.

## Quick start

From anywhere inside your project:

```sh
droidmap init                     # once: the GitHub workflow and the MCP config for AI agents
droidmap check                    # run the rules; exit code 1 on errors
droidmap impact TopicEntity       # what depends on it, transitively
droidmap diff                     # what your uncommitted changes touch
droidmap diff --base main         # what your branch touches
droidmap report -o REPORT.md      # an overview, with module and screen-flow diagrams
```

## On pull requests (GitHub Action)

`droidmap init` writes this workflow to `.github/workflows/droidmap.yml`:

```yaml
name: droidmap
on: [push, pull_request]

jobs:
  droidmap:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # findings as code scanning alerts
      pull-requests: write     # the comment that says what the pull request touches
    steps:
      - uses: actions/checkout@v7
      - uses: hussainshirazi/droidmap@v0
```

On each pull request the Action comments with what the change touches, and updates that one comment on every push:

> ### droidmap: what this change touches
>
> Compared with `origin/main`: 1 changed file, 1 of them read by droidmap.
>
> **Changed** (1): `ItemEntity` room_entity
>
> **Affected** (what depends on the changed code):
>
> | | |
> |---|---|
> | Screens | `HomeScreen` |
> | ViewModels | `HomeViewModel` |
> | Room | `AppDatabase`, `ItemDao` |
> | Dependency injection | `DataModule.bindItems`, `OfflineItemRepository` |
> | Modules | `:app`, `:core:data`, `:core:database`, `:feature:detail-screen`, `:feature:home` |

When a change removes a declaration (a destination, a binding, a DAO method), the comment lists it under **Removed**, and what still depended on it under **Affected**.

Findings show up as code scanning alerts, as notes on the changed lines and in the job summary, and the step fails on errors. The Action needs no Java setup: it uses the JDK that GitHub's runners already have. To check the permissions that libraries add to the merged manifest as well, set `merge-manifest: true`: it runs `./gradlew processReleaseMainManifest` first, so that job needs the JDK your build uses (`actions/setup-java`).

| Input | Default | |
|---|---|---|
| `path` | `.` | the Android project's folder, when it is not the repository root |
| `fail-on` | `error` | `warning` or `info` to be stricter, `never` to only report |
| `comment` | `true` | `false` to keep the impact summary out of pull request comments (it stays in the job summary) |
| `upload-sarif` | `true` | `false` on a private repository without GitHub Advanced Security (code scanning is free on public ones) |
| `args` | | extra arguments for `droidmap check`, such as `--config tools/droidmap.toml` |
| `base` | `auto` | the git ref to compare with: `auto` is a pull request's base branch, `none` turns it off; another ref must be fetched (for example with `fetch-depth: 0`) |
| `merge-manifest` | off | `true` runs `processReleaseMainManifest` first, so the permissions libraries add are checked too; with product flavors, the variant's task, such as `processProdReleaseMainManifest`. It runs your build, so never use it in a `pull_request_target` workflow |
| `version` | the pinned release | a droidmap release such as `0.2.0` |

### Run only the tests a change can break

`droidmap diff --format tasks` lists the test task of each module a change can break: the modules with a changed file and every module that depends on them (a module that uses them only in its tests gets its tests run, nothing more). A change to the build setup (settings, the root build file, `gradle/`, `build-logic`) lists every module. It reads only the Gradle files, so it takes a moment, without running Gradle:

```yaml
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0   # the base branch, to compare with
      - run: curl -fsSL https://raw.githubusercontent.com/hussainshirazi/droidmap/main/install.sh | sh
      - run: |
          tasks=$(~/.local/bin/droidmap diff --base origin/${{ github.base_ref }} --format tasks --task testDebugUnitTest)
          if [ -n "$tasks" ]; then ./gradlew $tasks; else echo "No module affected"; fi
```

`--format modules` prints the module paths instead, one per line.

`--format tests` goes further: only the test classes whose calls reach the changed functions, as Gradle arguments (`:core:data:testDebugUnitTest --tests com.example.OfflineRepositoryTest ...`), so `./gradlew $(droidmap diff --base origin/main --format tests --task testDebugUnitTest)` runs just those. Calls are followed through what the code declares (a property's or parameter's type, a constructor, a function's return type), and a call on an interface reaches every implementation, so it errs towards running more tests. The text report and `impact` list the same tests under "Tests that cover it".

## With an AI agent (MCP)

`droidmap mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio. It rebuilds the graph when a file changes (parsing only the changed files), so its answers follow the code as the agent edits it.

**Claude Code plugin** (the server plus a skill that tells Claude when to use it: impact before changing an entity, route or binding, checks and the tests to run after). It needs nothing installed but Java, and finds the one Android Studio brings: the first time, it downloads the droidmap release that matches the plugin and checks its SHA-256.

```
/plugin install droidmap --marketplace hussainshirazi/droidmap
```

On Claude Code before 2.1.275, add the marketplace first: `/plugin marketplace add hussainshirazi/droidmap`, then `/plugin install droidmap@droidmap`. The skill is a plain [SKILL.md](plugin/skills/droidmap/SKILL.md); other agents that read skills can use the same file.

The plugin also has two hooks (from droidmap 0.4.0). When a session starts, droidmap notes the project's findings. When Claude is about to finish, it checks again, and if Claude's changes added an error (a migration that is missing or fails, a route nothing registers, a binding nothing provides), it stops Claude from finishing and tells it which, so Claude fixes it first. Findings that were there before the session are left alone, and if Claude stops a second time, the errors are left to you. On Now in Android each check takes about 2 seconds.

Measured with `claude plugin eval` ([the suite](plugin/evals/README.md): three tasks on a small Room, Hilt and Compose app, three runs each, with and without the plugin, 2026-11-15). Adding a column to an entity users already have data in: with the plugin, 3 of 3 runs were fully correct (version bumped, a migration with a default, registered and tested, the shipped schema untouched); without it, 0 of 3 were (two runs left the migration unregistered or untested). Renaming a route argument the ViewModel reads, and adding a screen with a `@HiltViewModel`: correct in every run either way.

**Any MCP client.** `droidmap init` writes `.mcp.json` (Claude Code), and `.cursor/mcp.json` or `.vscode/mcp.json` when those folders exist; commit them and everyone on the team gets the server. It never changes a file that exists: it prints what to add instead. By hand:

```sh
claude mcp add droidmap -- droidmap mcp .
```

```json
{ "mcpServers": { "droidmap": { "command": "droidmap", "args": ["mcp", "."] } } }
```

Without installing anything but Java: `"command": "java", "args": ["-jar", "/path/to/droidmap.jar", "mcp", "."]`. With Docker: `"command": "docker", "args": ["run", "--rm", "-i", "-v", "/path/to/project:/project", "ghcr.io/hussainshirazi/droidmap", "mcp"]`. droidmap is also listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.hussainshirazi/droidmap` (from version 0.2.0).

**Gemini in Android Studio** connects to MCP servers over HTTP only. Start droidmap's HTTP server in the project (it listens on `127.0.0.1` only, and keeps running until you stop it):

```sh
droidmap mcp --http 3920
```

then add it under Settings > Tools > AI > MCP Servers:

```json
{ "mcpServers": { "droidmap": { "httpUrl": "http://127.0.0.1:3920/mcp" } } }
```

Google's [Android CLI](https://developer.android.com/blog/posts/android-cli-now-stable-1-accelerate-developing-for-android-using-any-agent) gives agents Android Studio's inspections of one file at a time; droidmap adds what lies across files and modules (Room versions and migrations, routes and their arguments, bindings, the manifest), and needs no IDE running, so the same checks run in CI.

<a href="https://mcprush.com/to/droidmap-mcp?ref=badge"><img width="380" height="200" src="https://mcprush.com/badge/droidmap-mcp/card.svg" alt="droidmap MCP server" /></a>

| Tool | Use it to |
|---|---|
| `droidmap_impact` | see what depends on an entity, route, ViewModel, binding or module before changing it |
| `droidmap_diff` | see what the uncommitted changes (or a branch) touch, and which tests cover them |
| `droidmap_check` | run the rules after a change |
| `droidmap_show` | look at one node: its attributes, dependencies and users |
| `droidmap_find` | search nodes by name |
| `droidmap_report` | get a Markdown overview of the project |
| `droidmap_explain` | learn why a rule matters and how to fix what it found |

## What droidmap understands

| Area | What it reads |
|---|---|
| **Gradle** | Modules from `settings.gradle(.kts)`; `project(":x")` and type-safe `projects.x.y` dependencies in Kotlin DSL and Groovy; plugins from the version catalog; the project dependencies that **convention plugins in an included build** (`build-logic`) add to every module that applies them; and Kotlin Multiplatform source sets (a dependency in `commonTest` is a test dependency). |
| **Room** | Databases, entities, DAOs (the tables each `@Query` uses and the entities each `@Insert`, `@Update`, `@Delete` or `@Upsert` writes, inherited ones included), manual and auto migrations, the exported schema JSON, the columns each entity has compared with that JSON, and **which `MigrationTestHelper` test covers which migration step**. |
| **Navigation** | Compose Navigation with string routes (built from constants, templates and helper functions) or type-safe routes, **Navigation 3** (`entry<Key>`, and `NavEntry(key)` in a `when` over the keys), XML navigation graphs (across files, with deep links, menu items and actions that only pop back), and `navigate(...)` calls in Kotlin and Java: with routes, `R.id` actions, **Safe Args** directions (`HomeFragmentDirections.actionHomeToDetail(id)`), and through your own helpers such as `navigateToTab(route)`, up to five helpers deep. |
| **Hilt** | `@HiltViewModel`s, `@Inject` constructors and fields, `@Provides` and `@Binds` with qualifiers, entry points, and which screens, activities and fragments use which ViewModel. |
| **Koin** | Modules and definitions (`single`, `factory`, `viewModel`, `singleOf(::X)`, `bind`), Koin Annotations (with JSR-330; an annotated class counts only in a package a module's `@ComponentScan` covers), and what each definition gets with `get()`; `koinViewModel`, `koinInject` and `by inject()` uses. |
| **Manifest** | Permissions (including `tools:node="remove"`) and components from the source manifests, and, when a build has produced it, the merged manifest's permissions with the library that added each. |

Kotlin and Java are read with the Kotlin compiler's own parser (the one detekt and ktlint use), on several threads.

## Commands

```sh
droidmap init   [path]                               # write the GitHub workflow and MCP config (never overwrites)
droidmap check  [path] [--format text|json|sarif] [--fail-on error|warning|info|never] [--sarif FILE] [--base REF]
                [--update-baseline] [--baseline FILE] [--no-baseline]
droidmap impact <node> [path] [--depth N] [--json]   # what depends on a node
droidmap diff   [path] [--base REF] [--depth N] [--format text|markdown|json|modules|tasks|tests] [--task NAME]   # what a change touches
droidmap show   <node> [path] [--json]               # a node, its dependencies and its users
droidmap find   <text> [path] [--limit N] [--json]   # search nodes
droidmap report [path] [-o FILE]                     # the Markdown report, with Mermaid diagrams
droidmap build  [path] [-o DIR] [--node-link]        # write droidmap-out/graph.json and REPORT.md
droidmap rules                                       # list the rules and their default severities
droidmap explain <rule>                              # why a rule matters and how to fix what it finds
droidmap mcp    [path]                               # run the MCP server over stdio
```

Without `[path]`, droidmap works on the Gradle project around the current folder (the nearest `settings.gradle(.kts)` at or above it). Output is in colour in a terminal; `NO_COLOR=1` turns that off and `FORCE_COLOR=1` on.

`<node>` can be an id, a name or part of a name: `TopicEntity`, `:core:data`, `"editor?id={id}"`, `HomeViewModel`. `check`, `impact`, `show`, `find` and `report` also take `--config FILE` and `--graph FILE` (use a saved `graph.json` instead of scanning); `build`, `diff` and `mcp` take `--config FILE`.

### Adopting droidmap on a project that already has findings

`droidmap check --update-baseline` writes today's findings to `droidmap-baseline.json` at the project root. Commit it: from then on, `check` (and the GitHub Action, the Gradle plugin, `diff` and the MCP server) report only findings that are not in it, and say how many known ones they left out. A finding stays known when code above it moves or its message gains a detail; it is matched by its rule, file and what it is about, not its line. When you fix known findings, `check` says so, and `--update-baseline` drops them. `--baseline FILE` uses another file, `--no-baseline` shows everything. SARIF results carry a stable fingerprint, so GitHub code scanning follows each alert across commits.

`diff` compares the working tree (committed or not, new files included) with the point where your branch left `--base` (default `HEAD`: the uncommitted changes). A changed line counts for the innermost declaration around it, so editing one function does not mark its whole class.

`check --sarif FILE` also writes the findings as SARIF. `check --base REF` also compares Room schema files with that commit; your last release tag is the most precise choice, since only a shipped schema must never change. Add `droidmap-out/` to your `.gitignore` if you use `build`.

Exit codes: 0 when done, 1 when `check` finds something at `--fail-on` or above (or `find` matches nothing), 2 for a usage or config error, 3 for an internal error.

## Rules

| Rule | Default | Finds |
|---|---|---|
| [`room-migration-path`](docs/rules/room-migration-path.md) | error | a known schema version with no migration path to the current version |
| [`room-migration-sql`](docs/rules/room-migration-sql.md) | error | a manual migration whose SQL, replayed on the schema files, fails (a `NOT NULL` column without a default, a missing table) or leaves tables, columns, indices or foreign keys different from the new version's schema: Room throws on update. Also two statements in one `execSQL` (only the first runs) and `RENAME COLUMN`/`DROP COLUMN` below their Android version |
| [`room-schema-missing`](docs/rules/room-schema-missing.md) | warning | no exported schema JSON for the current version or an earlier one |
| [`room-schema-stale`](docs/rules/room-schema-stale.md) | warning | entities that no longer match the schema JSON of the current version: a changed entity without a version bump crashes on update |
| [`room-schema-changed`](docs/rules/room-schema-changed.md) | warning | with `--base REF`: the schema JSON of a version that already existed at `REF` changed, which is the same crash once that version has shipped |
| [`room-migration-untested`](docs/rules/room-migration-untested.md) | warning | migration steps no `MigrationTestHelper` test runs |
| [`room-migration-unused`](docs/rules/room-migration-unused.md) | warning | a manual `Migration` that app code never uses (not passed to `addMigrations`?), even if a test runs it |
| [`room-destructive-fallback`](docs/rules/room-destructive-fallback.md) | warning | `fallbackToDestructiveMigration()`, which deletes user data |
| [`room-insert-replace`](docs/rules/room-insert-replace.md) | off | `@Insert(onConflict = REPLACE)`, which deletes and re-inserts rows |
| [`room-enum-constant-removed`](docs/rules/room-enum-constant-removed.md) | error | with `--base REF`: an enum constant removed or renamed while Room stores the enum by name: rows users saved with it crash when read ("Can't convert value to enum") |
| [`room-database-not-singleton`](docs/rules/room-database-not-singleton.md) | warning | a Room database built in a DI provider that is not a singleton: each injection opens another instance, and their Flows miss each other's writes |
| [`datastore-duplicate-file`](docs/rules/datastore-duplicate-file.md) | error | two DataStores on one file (two delegates with one name, or one built in a provider that is not a singleton): "There are multiple DataStores active for the same file" |
| [`nav-unknown-target`](docs/rules/nav-unknown-target.md) | error | `navigate()` to a route or key no destination registers |
| [`nav-unreachable`](docs/rules/nav-unreachable.md) | warning | a destination nothing navigates to, starts at or refers to, and that no deep link or menu item opens |
| [`nav-argument-missing`](docs/rules/nav-argument-missing.md) | warning | a ViewModel that reads `savedStateHandle["topicId"]` when the destination showing it calls its argument `id`: always null |
| [`nav-route-type-unsupported`](docs/rules/nav-route-type-unsupported.md) | error | a type-safe route property Navigation has no NavType for (a data class, a `Set`, a date) with no `typeMap`: "could not find any NavType for argument" |
| [`nav-deeplink-not-in-manifest`](docs/rules/nav-deeplink-not-in-manifest.md) | warning | a deep link (`navDeepLink`, `<deepLink>`) whose scheme and host no activity's intent filter accepts, so the link does not open the app |
| [`hilt-missing-binding`](docs/rules/hilt-missing-binding.md) | warning | an injected project type with no `@Inject` constructor, `@Provides` or `@Binds` |
| [`hilt-duplicate-binding`](docs/rules/hilt-duplicate-binding.md) | error | the same type and qualifier bound twice in one source set |
| [`hilt-app-not-registered`](docs/rules/hilt-app-not-registered.md) | error | `@AndroidEntryPoint` classes, but the manifest's `<application android:name>` is not the `@HiltAndroidApp` class (or there is none): they crash when they open |
| [`hilt-fragment-host`](docs/rules/hilt-fragment-host.md) | error | an `@AndroidEntryPoint` fragment hosted by an activity that is not one (through its navigation graph, layout or a fragment transaction): it crashes when the fragment is attached |
| [`hilt-viewmodel-factory`](docs/rules/hilt-viewmodel-factory.md) | error | a `@HiltViewModel` got without Hilt's factory: `viewModel()` in a navigation destination, `by viewModels()` outside an `@AndroidEntryPoint`, `by navGraphViewModels()`. "Cannot create an instance of class" |
| [`workmanager-setup`](docs/rules/workmanager-setup.md) | warning | a `@HiltWorker` that nothing gives `HiltWorkerFactory` to, or a `Configuration.Provider` that WorkManager never asks because its default initializer is still in the manifest |
| [`workmanager-worker-renamed`](docs/rules/workmanager-worker-renamed.md) | warning | with `--base REF`: a Worker renamed, moved or deleted while users have its periodic work saved: it fails every time it runs, and `KEEP` keeps it |
| [`worker-input-missing`](docs/rules/worker-input-missing.md) | warning | a worker that reads an input key none of its work requests put: always null |
| [`koin-missing-definition`](docs/rules/koin-missing-definition.md) | warning | a type Koin is asked for (`get()`, `inject()`, `koinInject()`) that no Koin definition provides: `NoDefinitionFoundException` at runtime |
| [`gradle-unknown-project`](docs/rules/gradle-unknown-project.md) | error | a project dependency on a module settings does not include |
| [`gradle-forbidden-dependency`](docs/rules/gradle-forbidden-dependency.md) | error | a dependency your `[[gradle.forbid]]` rules ban |
| [`gradle-cycle`](docs/rules/gradle-cycle.md) | error | modules that depend on each other in a cycle |
| [`manifest-permission`](docs/rules/manifest-permission.md) | error | a permission not in your `allowed_permissions`, in a source manifest or added by a library to the merged one |
| [`component-not-in-manifest`](docs/rules/component-not-in-manifest.md) | error | an activity, service or receiver the code sends an explicit Intent to, but no manifest declares: `ActivityNotFoundException`, or a service that never runs |
| [`intent-extra-missing`](docs/rules/intent-extra-missing.md) | warning | a component that reads an Intent extra none of the Intents sent to it put: always null |
| [`notification-channel-missing`](docs/rules/notification-channel-missing.md) | warning | a notification built for a channel id the app never creates: not shown from Android 8, a crash in `startForeground` |
| [`gson-model-not-kept`](docs/rules/gson-model-not-kept.md) | warning | a class Gson reads by reflection (`fromJson`, `TypeToken`, a Retrofit API with `GsonConverterFactory`) whose fields R8 renames in a minified release build: no `@SerializedName`, `@Keep` or keep rule. Debug works, release reads empty fields |
| [`moshi-model-not-kept`](docs/rules/moshi-model-not-kept.md) | warning | the same for Moshi without code generation (`moshi.adapter(X::class.java)`, a Retrofit API with `MoshiConverterFactory`): a class with no `@JsonClass(generateAdapter = true)` whose fields have no `@Json(name)` |

## Configuration

Put a `.droidmap.toml` at the project root (all of it is optional):

```toml
[rules]
"room-migration-untested" = "error"   # error | warning | info | off
"room-insert-replace" = "error"

[manifest]
allowed_permissions = ["android.permission.INTERNET", "android.permission.POST_NOTIFICATIONS"]

[[gradle.forbid]]
from = ":feature:*"
to = ":feature:*"
reason = "features talk to each other through :core modules"

[ignore]
paths = ["benchmarks/**"]
```

An unknown rule name or severity is an error, so a typo never leaves a rule silently unchanged. `from`, `to` and `ignore.paths` are glob patterns where `*` also matches `:` and `/`. A forbid rule skips test dependencies unless it says `tests = true`, and `allow_same_parent = true` lets siblings such as `:feature:a:impl` and `:feature:a:api` depend on each other. With `allowed_permissions`, a permission a library adds to the merged manifest is reported with the library's name, so you can remove it (`tools:node="remove"`) or allow it.

## The graph

`droidmap build` writes `droidmap-out/graph.json` (schema `droidmap/1`) with three lists:

- `nodes`: id, kind, label, file, line, module and attrs;
- `edges`: source, target, kind, file, line and attrs;
- `unresolved`: what static analysis could not follow, with the reason.

An edge always means *source depends on target*, so impact is a walk backwards. Paths are relative to the project root and the output is deterministic, so it diffs cleanly. `--node-link` also writes the networkx node-link shape that tools such as graphify read.

Node kinds: `module`, `room_database`, `room_entity`, `room_dao`, `room_migration`, `room_schema`, `test`, `nav_destination`, `nav_route`, `screen`, `function`, `viewmodel`, `injectable`, `hilt_module`, `hilt_provider`, `koin_module`, `koin_definition`, `entry_point`, `component`, `permission`, `class`.

Edge kinds: `depends_on`, `contains_entity`, `contains_dao`, `queries`, `writes`, `has_schema`, `migrates`, `tests`, `registers`, `shows`, `navigates_to`, `starts_at`, `uses_viewmodel`, `injects`, `bound_by`, `requires`, `declared_in`, `uses_permission`, `declares`.

## Limits

droidmap reads the source and never runs Gradle. That is what makes it take seconds, work on a checkout nobody has built, and never run a project's build scripts; it also puts what only a build produces out of reach. And it is deliberately conservative: when it cannot resolve something (a route held in a variable, a version that is not a constant, a Koin definition whose type it cannot tell), it records it under `unresolved` instead of guessing, and the rules do not fire on it. A rule that guesses reports problems that are not there.

- Code a build generates (KSP, kapt) is not read. Safe Args does not need it: `HomeFragmentDirections.actionHomeToDetail()` is matched to its action by the names Safe Args gives the code it generates.
- The permissions libraries add come from the resolved dependencies, so the merged manifest is read only when a build has produced it (`<module>/build/intermediates/merged_manifests/`, or the Action's `merge-manifest` input). A merged manifest older than the build files is flagged as such.
- Names resolve by Kotlin's and Java's rules (imports, the package, enclosing classes and their supertypes), but without type inference, which needs the compiler and every dependency. A call on a variable, such as `repo.load()`, is traced when the variable's type is declared or comes from a constructor or a function's declared return type, not when it would have to be inferred (a lambda's `it`, a generic's type argument, a chain of library calls).
- Values built at runtime are not followed: a route read from a `var`, or built in a loop. Constants, string templates, functions that return them and helpers up to five levels deep are.

## Contributing

`./gradlew test fatJar` runs the tests and builds `build/libs/droidmap.jar`. [CONTRIBUTING.md](CONTRIBUTING.md) has where the code lives, what a new rule or fix needs, and the real-project checks in CI. Report a wrong or missed finding with the *False positive or missed problem* issue form; security problems privately, as [SECURITY.md](SECURITY.md) says.

## License

Apache-2.0. See [LICENSE](LICENSE).

TDQS

A4.5/5.0

Scored across 7 tools

Disambiguation5/5

Each tool targets a distinct action on the code graph: check (rule linting), diff (git change mapping), impact (transitive dependents), show (single-node detail), find (node search), report (project overview), explain (rule documentation). Descriptions even include explicit sibling disambiguation cues like 'use droidmap_diff for what a change touches' and 'use droidmap_impact for transitive, droidmap_show for direct links'.

Naming Consistency5/5

Every tool is a single lowercase word appended to a uniform 'droidmap_' namespace prefix, forming a predictable droidmap_<action> pattern. No camelCase mixing or inconsistent verb styles; the naming reads like a coherent family of graph/analysis operations.

Tool Count5/5

Seven tools is well within the ideal 3-15 range and each earns its place with a non-redundant role in a codebase-graph analysis workflow. Nothing feels padded or missing from the set.

Completeness4/5

The surface covers the full exploratory lifecycle: find a node, inspect it, map its dependents, diff changes, lint rules, understand findings, and get a whole-project report. The main minor gap is baseline handling: findings are excluded via droidmap-baseline.json, but no tool exists to create or update that baseline, leaving agents to work around it externally.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues