Add package-level feature scoping for the navigation graph (#19) (#22)

Lets a single-module app organized by feature packages view and export
the graph one feature at a time.

- Gradle: a new -Pnavgraph.export.package=<prefix> property on
  exportNavGraphImage/Html exports only the destinations under a package
  (matched by route or screen FQN), keeping internal edges and dropping
  cross-feature ones.
- IDE: a "Feature:" tool window selector, auto-discovered from the package
  layout, slices the graph by feature; the same selection scopes the export
  so the file matches what is on screen.
- Sample: feature-packaged screens (catalog, cart, orders) in :sample
  demonstrate the selector and the internal vs cross-feature edge behavior.
- Docs: the export and graph pages document the flag and the selector.

Author: skydoves

compose-nav-graph-gradle/src/main/kotlin/com/github/skydoves/navgraph/gradle/ExportNavGraphHtmlTask.kt

@@ -61,6 +61,12 @@ public abstract class ExportNavGraphHtmlTask : DefaultTask() {
   @get:Optional
   public abstract val deviceSpec: Property<String>
 
+  /** "" = the whole graph; else a package prefix (e.g. "com.app.feature.feed") to export only that feature's
+   *  subgraph (nodes whose route/screen FQN is under it, plus their internal edges). */
+  @get:Input
+  @get:Optional
+  public abstract val packageFilter: Property<String>
+
   @get:OutputFile
   public abstract val outputHtml: RegularFileProperty
 
@@ -73,7 +79,11 @@ public abstract class ExportNavGraphHtmlTask : DefaultTask() {
   @TaskAction
   public fun export() {
     val manifestFile = manifest.get().asFile
-    val graph = parseGraph(manifestFile.readText())
+    val pkg = packageFilter.orNull.orEmpty()
+    val graph = filterGraphByPackage(parseGraph(manifestFile.readText()), pkg)
+    if (pkg.isNotBlank() && graph.nodes.isEmpty()) {
+      logger.warn("navgraph: no destinations under package '$pkg'; exporting an empty graph.")
+    }
     val thumbsRoot: File? = thumbsDir.orNull?.asFile
     val device = parseDevice(deviceSpec.orNull)
     // "Generated" date = the graph data's timestamp (manifest mtime), not now() — keeps the output

compose-nav-graph-gradle/src/main/kotlin/com/github/skydoves/navgraph/gradle/ExportNavGraphImageTask.kt

@@ -67,6 +67,12 @@ public abstract class ExportNavGraphImageTask : DefaultTask() {
   @get:Optional
   public abstract val deviceSpec: Property<String>
 
+  /** "" = the whole graph; else a package prefix (e.g. "com.app.feature.feed") to export only that feature's
+   *  subgraph (nodes whose route/screen FQN is under it, plus their internal edges). */
+  @get:Input
+  @get:Optional
+  public abstract val packageFilter: Property<String>
+
   /** Supersampling factor — the image is rendered at this multiple and `g2.scale(scale)`d for crisp hi-DPI. */
   @get:Input
   @get:Optional
@@ -78,7 +84,11 @@ public abstract class ExportNavGraphImageTask : DefaultTask() {
   @TaskAction
   public fun export() {
     val manifestFile = manifest.get().asFile
-    val graph = parseGraph(manifestFile.readText())
+    val pkg = packageFilter.orNull.orEmpty()
+    val graph = filterGraphByPackage(parseGraph(manifestFile.readText()), pkg)
+    if (pkg.isNotBlank() && graph.nodes.isEmpty()) {
+      logger.warn("navgraph: no destinations under package '$pkg'; exporting an empty graph.")
+    }
     val thumbsRoot: File? = thumbsDir.orNull?.asFile
     val device = parseDevice(deviceSpec.orNull)
     val s = (scale.orNull ?: DEFAULT_SCALE).coerceIn(1, 8)

compose-nav-graph-gradle/src/main/kotlin/com/github/skydoves/navgraph/gradle/NavGraphGradlePlugin.kt

@@ -575,6 +575,7 @@ public class NavGraphGradlePlugin : Plugin<Project> {
         manifest.set(graphSourceDir.map { it.file("nav-graph.json") })
         this.thumbsDir.set(graphSourceDir.map { it.dir("thumbs") })
         deviceSpec.set(providers.gradleProperty("navgraph.export.device").orElse(""))
+        packageFilter.set(providers.gradleProperty("navgraph.export.package").orElse(""))
         outputHtml.set(
           layout.file(providers.gradleProperty("navgraph.export.out").map { File(it) })
             .orElse(navgraphDir.map { it.file("nav-graph.html") }),
@@ -589,6 +590,7 @@ public class NavGraphGradlePlugin : Plugin<Project> {
         manifest.set(graphSourceDir.map { it.file("nav-graph.json") })
         this.thumbsDir.set(graphSourceDir.map { it.dir("thumbs") })
         deviceSpec.set(providers.gradleProperty("navgraph.export.device").orElse(""))
+        packageFilter.set(providers.gradleProperty("navgraph.export.package").orElse(""))
         scale.set(providers.gradleProperty("navgraph.export.scale").map { it.toInt() })
         outputImage.set(
           layout.file(providers.gradleProperty("navgraph.export.out").map { File(it) })

compose-nav-graph-gradle/src/main/kotlin/com/github/skydoves/navgraph/gradle/NavManifest.kt

@@ -75,6 +75,19 @@ internal data class HPreviewParam(val name: String = "", val provider: String =
 
 internal data class HEdge(val from: String = "", val to: String = "", val label: String? = null)
 
+/** Restrict [graph] to a feature package [prefix] (e.g. `com.app.feature.feed`): keep nodes whose route FQN
+ *  (`id`) or screen FQN (`clickTargetFqn`) is under that package, plus edges with both endpoints kept. A blank
+ *  prefix returns [graph] unchanged. Backs the `-Pnavgraph.export.package=` filter for single-module apps that
+ *  organize screens by feature package. */
+internal fun filterGraphByPackage(graph: HGraph, prefix: String): HGraph {
+  if (prefix.isBlank()) return graph
+  fun underPackage(fqn: String?): Boolean =
+    fqn != null && (fqn == prefix || fqn.startsWith("$prefix."))
+  val nodes = graph.nodes.filter { underPackage(it.id) || underPackage(it.clickTargetFqn) }
+  val ids = nodes.mapTo(HashSet()) { it.id }
+  return graph.copy(nodes = nodes, edges = graph.edges.filter { it.from in ids && it.to in ids })
+}
+
 internal fun parseGraph(text: String): HGraph {
   val root = Json.parseToJsonElement(text).jsonObject
   val nodes = root.arr("nodes").map { el ->

compose-nav-graph-gradle/src/test/kotlin/com/github/skydoves/navgraph/gradle/NavManifestParseTest.kt

@@ -23,6 +23,52 @@ import org.junit.Test
 
 class NavManifestParseTest {
 
+  @Test
+  fun filterByPackage_keepsNodesUnderPrefixAndDropsCrossFeatureEdges() {
+    val graph = HGraph(
+      nodes = listOf(
+        HNode(id = "app.feed.FeedRoute", clickTargetFqn = "app.feed.FeedScreen"),
+        HNode(id = "app.feed.detail.DetailRoute"),
+        HNode(id = "app.profile.ProfileRoute"),
+      ),
+      edges = listOf(
+        HEdge(from = "app.feed.FeedRoute", to = "app.feed.detail.DetailRoute"),
+        HEdge(from = "app.feed.FeedRoute", to = "app.profile.ProfileRoute"),
+      ),
+    )
+
+    val feed = filterGraphByPackage(graph, "app.feed")
+
+    assertEquals(
+      listOf("app.feed.FeedRoute", "app.feed.detail.DetailRoute"),
+      feed.nodes.map {
+        it.id
+      },
+    )
+    assertEquals(1, feed.edges.size)
+    assertEquals("app.feed.detail.DetailRoute", feed.edges.single().to)
+  }
+
+  @Test
+  fun filterByPackage_matchesViaScreenFqnAndIgnoresPartialSegments() {
+    val graph = HGraph(
+      nodes = listOf(
+        HNode(id = "app.routes.SearchRoute", clickTargetFqn = "app.feed.SearchScreen"),
+        HNode(id = "app.feedback.FeedbackRoute"),
+      ),
+    )
+
+    // Kept via clickTargetFqn; `feedback` is NOT under `feed` (segment boundary).
+    val kept = filterGraphByPackage(graph, "app.feed").nodes.map { it.id }
+    assertEquals(listOf("app.routes.SearchRoute"), kept)
+  }
+
+  @Test
+  fun filterByPackage_blankPrefixReturnsUnchanged() {
+    val graph = HGraph(nodes = listOf(HNode(id = "app.A")))
+    assertEquals(graph, filterGraphByPackage(graph, ""))
+  }
+
   @Test
   fun parsesNodesEdgesArgsAndStart() {
     val json = """

compose-nav-graph-idea/src/main/kotlin/com/github/skydoves/navgraph/idea/NavFeatureGrouping.kt

@@ -0,0 +1,96 @@
+/*
+ * Designed and developed by 2026 skydoves (Jaewoong Eum)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.github.skydoves.navgraph.idea
+
+import com.github.skydoves.navgraph.idea.model.NavGraphDto
+import com.github.skydoves.navgraph.idea.model.NavNodeDto
+
+/**
+ * Splits one graph into **feature groups by package** — the within-module counterpart of [NavScopeGrouping]
+ * (which groups by Gradle module). For apps that keep every screen in a single `:app` module and organize them
+ * by feature package (`feature.feed`, `feature.profile`, …), this powers the tool window's "Feature:" selector
+ * so the user can view/export one feature's subgraph at a time. No IntelliJ types, so it is unit-testable, and
+ * the filter mirrors the Gradle `filterGraphByPackage` exactly so the on-screen view and an export agree.
+ *
+ * **Auto-discovery (no configuration).** Anchor at the longest package prefix every destination shares (the
+ * common root, e.g. `com.app.feature`), then bucket by the single segment that follows it (`feed`, `profile`).
+ * Screens deeper in a feature (`com.app.feature.feed.detail.DetailScreen`) fold into that feature. When fewer
+ * than two buckets emerge there is nothing to choose between, so [computeFeatures] returns empty and the caller
+ * hides the selector. A destination sitting directly under the common root (no further segment) has no feature
+ * of its own — it only appears under "All features".
+ */
+internal object NavFeatureGrouping {
+
+  /** @property name the segment shown in the selector; @property packagePrefix what [filterByPackage] keys on. */
+  data class Feature(val name: String, val packagePrefix: String)
+
+  /**
+   * The feature groups discovered in [graph], sorted by name. Empty when fewer than two distinct features
+   * exist (single-feature or flat apps) — the selector is then pointless and stays hidden.
+   */
+  fun computeFeatures(graph: NavGraphDto): List<Feature> {
+    val packages = graph.nodes.mapNotNull {
+      it.featureFqn()?.let(::packageOf)
+    }.filter { it.isNotBlank() }
+    if (packages.size < 2) return emptyList()
+
+    val common = commonPackagePrefix(packages)
+    val rootDepth = if (common.isEmpty()) 0 else common.split('.').size
+    // The segment right after the shared root is the feature; a package with nothing past the root contributes
+    // no feature key (those destinations live only under "All features").
+    val keys = LinkedHashSet<String>()
+    for (pkg in packages) {
+      val segments = pkg.split('.')
+      if (segments.size > rootDepth) keys.add(segments[rootDepth])
+    }
+    if (keys.size < 2) return emptyList()
+
+    return keys.sorted().map { key ->
+      Feature(name = key, packagePrefix = if (common.isEmpty()) key else "$common.$key")
+    }
+  }
+
+  /**
+   * Restrict [graph] to the destinations under [prefix] — a node is kept when its route FQN ([NavNodeDto.id])
+   * OR its screen FQN ([NavNodeDto.clickTargetFqn]) is the prefix or nested under it, and an edge survives only
+   * when both endpoints do. A blank [prefix] returns [graph] unchanged. Byte-for-byte the Gradle export filter.
+   */
+  fun filterByPackage(graph: NavGraphDto, prefix: String): NavGraphDto {
+    if (prefix.isBlank()) return graph
+    fun underPackage(fqn: String?): Boolean =
+      fqn != null && (fqn == prefix || fqn.startsWith("$prefix."))
+    val nodes = graph.nodes.filter { underPackage(it.id) || underPackage(it.clickTargetFqn) }
+    val ids = nodes.mapTo(HashSet()) { it.id }
+    return graph.copy(nodes = nodes, edges = graph.edges.filter { it.from in ids && it.to in ids })
+  }
+
+  /** The screen FQN drives the feature (it is where the code lives); the route id is the fallback when the
+   *  screen FQN is absent OR blank (a hand-authored manifest may carry an empty `clickTargetFqn`). */
+  private fun NavNodeDto.featureFqn(): String? =
+    (clickTargetFqn?.ifBlank { null } ?: id).ifBlank { null }
+
+  /** Package of a fully-qualified name: everything before the final segment (the simple type name). */
+  private fun packageOf(fqn: String): String = fqn.substringBeforeLast('.', "")
+
+  /** The longest run of leading package segments shared by every entry (segment-wise, never mid-segment). */
+  private fun commonPackagePrefix(packages: List<String>): String {
+    val split = packages.map { it.split('.') }
+    val first = split.first()
+    var depth = 0
+    while (depth < first.size && split.all { it.size > depth && it[depth] == first[depth] }) depth++
+    return first.take(depth).joinToString(".")
+  }
+}