Feature/destinations

[vkatz]

Tiamat destinations prototype

• closes Annotation support #107

• Add example

• Add doc / readme

• Check annotations (https://kotlinlang.org/docs/whatsnew21.html#support-for-requiring-opt-in-to-extend-apis)

• Update (dump) api

• Fix detekt

[gemini-code-assist]

Hello @vkatz, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

Summary of Changes

This pull request introduces the initial prototype for Tiamat Destinations, a new feature for the Tiamat navigation library. The changes include adding necessary dependencies and plugins, defining core components like the InstallIn annotation and TiamatGraph interface, and setting up a compiler plugin to generate code based on these annotations. The goal is to simplify navigation graph creation and management in Compose Multiplatform projects.

Highlights

• Tiamat Destinations Core: Introduces the core components for Tiamat Destinations, including the InstallIn annotation for binding NavDestinations to TiamatGraphs, and the TiamatGraph interface for defining navigation graphs.
• Compiler Plugin: Sets up a Kotlin compiler plugin that automatically generates the destinations() function for TiamatGraph implementations, populating it with the NavDestinations annotated with @InstallIn.
• Gradle Plugin: Adds a Gradle plugin to apply the compiler plugin to Kotlin Multiplatform projects.
• Example Usage: Provides an example of how to use Tiamat Destinations in a Compose Multiplatform project, demonstrating the use of InstallIn and TiamatGraph to define and manage navigation.
• M2P Plugin Integration: Integrates the M2P plugin for publishing the compiler and gradle plugins to a local Maven repository.

Changelog

Click here to see the changelog

• build.gradle.kts
  • Applies compose compiler plugin conditionally.
  • Adds tiamat-destinations to the list of api validation projects.
  • Replaces subprojects configuration with rootProject configuration for createLocalM2 task.
  • Adds dependencies for tiamat-destinations-compiler and tiamat-destinations-gradle-plugin to createLocalM2 task.
• example/content/build.gradle.kts
  • Adds the tiamat destinations compiler plugin.
  • Adds a dependency on the tiamat-destinations project.
• example/content/src/commonMain/kotlin/composegears/tiamat/example/content/App.kt
  • Adds experimental API opt-in.
  • Introduces TiamatGraph objects and NavDestinations with InstallIn annotations.
  • Adds a LaunchedEffect to print the destinations of the graphs.
• gradle/libs.versions.toml
  • Adds versions for autoService, core, and junit.
  • Adds libraries for zacsweers-kctfork, junit, kotlin-compiler-embeddable, and kotlin-gradle-plugin-api.
  • Adds a plugin for tiamat-destinations-compiler.
• plugins/src/main/kotlin/M2P.kt
  • Adds groupId, artifactId, and version properties to the M2PExtension interface.
  • Configures MavenPublication with groupId, artifactId, and version from the extension.
  • Updates the maven repository URL to use the root project's directory.
  • Removes the createM2PTask function.
• settings.gradle.kts
  • Includes the tiamat-destinations project.
  • Includes the tiamat-destinations-compiler and tiamat-destinations-gradle-plugin build.
  • Configures dependency substitution for the tiamat-destinations-compiler module.
• tiamat-destinations-compiler/compiler-plugin/build.gradle.kts
  • Creates a new module for the compiler plugin.
  • Applies the kotlin("jvm") and m2p plugins.
  • Adds dependencies for kotlin-compiler-embeddable, zacsweers-kctfork, and junit.
  • Configures the m2p extension with artifactId and description.
  • Configures publishing with a MavenPublication for the kotlin compiler plugin.
• tiamat-destinations-compiler/compiler-plugin/settings.gradle.kts
  • Enables TYPESAFE_PROJECT_ACCESSORS feature preview.
  • Includes the plugins build.
  • Configures repositories and version catalogs.
• tiamat-destinations-compiler/compiler-plugin/src/main/kotlin/com/composegears/tiamat/destinations/TiamatDestinationsCommandLineProcessor.kt
  • Creates a CommandLineProcessor for the compiler plugin.
• tiamat-destinations-compiler/compiler-plugin/src/main/kotlin/com/composegears/tiamat/destinations/TiamatDestinationsComponentRegistrar.kt
  • Creates a ComponentRegistrar for the compiler plugin.
• tiamat-destinations-compiler/compiler-plugin/src/main/kotlin/com/composegears/tiamat/destinations/TiamatDestinationsIrGenerationExtension.kt
  • Creates an IrGenerationExtension for the compiler plugin.
  • Adds logic to find all variables and classes annotated with @Installin.
  • Adds logic to validate types.
  • Adds logic to override the destinations() function for each TiamatGraph class.
• tiamat-destinations-compiler/compiler-plugin/src/main/resources/META-INF/services/org.jetbrains.kotlin.compiler.plugin.CommandLineProcessor
  • Registers the CommandLineProcessor.
• tiamat-destinations-compiler/compiler-plugin/src/main/resources/META-INF/services/org.jetbrains.kotlin.compiler.plugin.CompilerPluginRegistrar
  • Registers the ComponentRegistrar.
• tiamat-destinations-compiler/compiler-plugin/src/test/kotlin/com/composegears/tiamat/destinations/TiamatDestinationsCompilerPluginTest.kt
  • Creates tests for the compiler plugin.
  • Adds tests to check if the plugin handles multiple destination types and fails with incorrect annotation use.
• tiamat-destinations-compiler/gradle-plugin/build.gradle.kts
  • Creates a new module for the gradle plugin.
  • Applies the kotlin("jvm"), java-gradle-plugin, and m2p plugins.
  • Adds a dependency for kotlin-gradle-plugin-api.
  • Configures the gradlePlugin extension.
  • Configures the m2p extension with artifactId and description.
  • Configures publishing with a MavenPublication for the gradle plugin.
• tiamat-destinations-compiler/gradle-plugin/settings.gradle.kts
  • Enables TYPESAFE_PROJECT_ACCESSORS feature preview.
  • Includes the plugins build.
  • Configures repositories and version catalogs.
• tiamat-destinations-compiler/gradle-plugin/src/main/kotlin/com/composegears/tiamat/destinations/TiamatDestinationsCompilerPlugin.kt
  • Creates a KotlinCompilerPluginSupportPlugin for the gradle plugin.
• tiamat-destinations/api/android/tiamat-destinations.api
  • Adds API definitions for the tiamat-destinations module.
• tiamat-destinations/api/jvm/tiamat-destinations.api
  • Adds API definitions for the tiamat-destinations module.
• tiamat-destinations/build.gradle.kts
  • Creates a new module for tiamat-destinations.
  • Applies the kotlin multiplatform, android library, compose compiler, jetbrains compose, and m2p plugins.
  • Configures kotlin multiplatform targets.
  • Configures source sets with dependencies.
  • Configures android namespace and compileSdk.
  • Configures the m2p extension with description.
• tiamat-destinations/src/commonMain/kotlin/com/composegears/tiamat/destinations/InstallIn.kt
  • Creates the InstallIn annotation.
• tiamat-destinations/src/commonMain/kotlin/com/composegears/tiamat/destinations/TiamatGraph.kt
  • Creates the TiamatGraph interface and TiamatMergedGraph class.
• tiamat-destinations/src/commonMain/kotlin/com/composegears/tiamat/Сompose.kt
  • Adds rememberNavController functions that take a TiamatGraph as a parameter.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

---

Did you know?

Kotlin's name is inspired by an island near St. Petersburg, Russia, just as Java was named after an island in Indonesia.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new Tiamat Destinations feature, including a compiler plugin and Gradle plugin to facilitate navigation between destinations in a Compose Multiplatform project. The changes include modifications to build configurations, plugin implementations, and example usage. Overall, the feature seems well-structured, but there are some areas that could benefit from further review and refinement.

Summary of Findings

• Compiler Plugin Validation: The compiler plugin's core logic in TiamatDestinationsIrGenerationExtension.kt requires careful validation to ensure it correctly identifies and processes navigation destinations. The error message in the same file could be improved for clarity.
• Gradle Plugin Configuration: The Gradle plugin setup in TiamatDestinationsCompilerPlugin.kt and related build files needs thorough testing to confirm it integrates seamlessly with different project structures and build configurations.
• Code Generation Logic: The code generation logic within the compiler plugin should be reviewed to ensure it produces efficient and maintainable code. Consider potential performance implications and maintainability aspects of the generated code.

Merge Readiness

The pull request introduces a significant new feature with a compiler plugin and Gradle plugin. Due to the complexity and potential impact of these changes, I recommend a thorough review and testing of the compiler plugin's code generation logic and the Gradle plugin's integration with various project setups. I am unable to approve this pull request, and recommend that others review and approve this code before merging. Addressing the identified issues, particularly those related to compiler plugin validation and Gradle plugin configuration, is crucial before merging. At a minimum, the high severity issues should be addressed before merging.