Merge pull request #217 from redbadger/rustdoc-typegen

rustdoc typegen

Author: StuartHarris

Cargo.lock

@@ -7,7 +7,7 @@ edition.workspace = true
 repository.workspace = true
 license.workspace = true
 keywords.workspace = true
-rust-version.workspace = true
+rust-version = "1.70"
 
 [[bin]]
 name = "crux"
@@ -16,9 +16,28 @@ path = "src/main.rs"
 [dependencies]
 anyhow.workspace = true
 clap = { version = "4.5.35", features = ["derive"] }
+ascent = "0.8.0"
 console = "0.15.11"
+env_logger = "0.10.2"
+guppy = "0.17.4"
+heck = "0.5.0"
 ignore = "0.4.23"
+iter_tools = "0.24.0"
+lazy-regex = "3.4.1"
+libc = "0.2.171"
+log = "0.4.26"
 ramhorns = "1.0.1"
+rustdoc-json = "0.9.5"
+rustdoc-types = "0.38.0"
 serde = { workspace = true, features = ["derive"] }
+serde-generate = "0.29.0"
+serde-reflection = "0.5.0"
+serde_json = "1.0.140"
 similar = { version = "2.7.0", features = ["inline"] }
+thiserror = "2.0.12"
 toml = "0.8.20"
+
+[dev-dependencies]
+insta = { version = "1.42.2" }
+pretty_assertions = "1.4.1"
+rstest = "0.25.0"

crux_cli/Cargo.toml

@@ -0,0 +1,19 @@
+#!/usr/bin/env fish
+argparse h/help -- $argv
+or return
+
+if set -q _flag_help
+    echo must specify example as the single argument
+    return 0
+end
+
+argparse --min-args=1 -- $argv
+or return
+
+cargo build
+
+pushd $argv[1]
+RUST_LOG=info ../../target/debug/crux codegen \
+    --lib shared \
+    --output ./shared_types/generated
+popd

crux_cli/codegen.fish

@@ -1,6 +1,7 @@
 use std::path::PathBuf;
 
-use clap::{ArgAction, Args, Parser, Subcommand};
+use clap::{ArgAction, Args, Parser, Subcommand, ValueHint::DirPath};
+use heck::{ToPascalCase, ToSnakeCase};
 
 #[derive(Parser)]
 #[command(
@@ -13,12 +14,27 @@ use clap::{ArgAction, Args, Parser, Subcommand};
     arg_required_else_help(true),
     propagate_version = true
 )]
-pub(crate) struct Cli {
+pub struct Cli {
     #[command(subcommand)]
-    pub command: Option<Commands>,
+    pub command: Commands,
 
     #[arg(long, short, action = ArgAction::Count)]
     pub verbose: u8,
+}
+
+#[derive(Subcommand)]
+pub enum Commands {
+    #[command(visible_alias = "doc")]
+    Doctor(DoctorArgs),
+
+    #[command(visible_alias = "gen")]
+    Codegen(CodegenArgs),
+}
+
+#[derive(Args)]
+pub struct DoctorArgs {
+    #[arg(long, short)]
+    pub fix: Option<PathBuf>,
 
     #[arg(long, short, default_value = "false")]
     pub include_source_code: bool,
@@ -31,16 +47,69 @@ pub(crate) struct Cli {
     pub path: Option<PathBuf>,
 }
 
-#[derive(Subcommand)]
-pub(crate) enum Commands {
-    #[command(visible_alias = "doc")]
-    Doctor(DoctorArgs),
+#[derive(Args)]
+pub struct CodegenArgs {
+    /// name of the library containing your Crux App
+    #[arg(long, short, value_name = "STRING")]
+    pub lib: String,
+    /// Output directory for generated code
+    #[arg(
+        long,
+        short,
+        value_name = "DIR",
+        value_hint = DirPath,
+        default_value = "./shared/generated",
+    )]
+    pub output: PathBuf,
+    /// Java package name
+    #[arg(
+        long,
+        short,
+        value_name = "dotted.case",
+        value_parser = dotted_case,
+        default_value = "com.crux.example.shared.types"
+    )]
+    pub java_package: String,
+    /// Swift package name
+    #[arg(
+        long,
+        short,
+        value_name = "PascalCase",
+        value_parser = pascal_case,
+        default_value = "SharedTypes")]
+    pub swift_package: String,
+    /// TypeScript package name
+    #[arg(
+        long,
+        short,
+        value_name = "snake_case",
+        value_parser = snake_case,
+        default_value = "shared_types")]
+    pub typescript_package: String,
 }
 
-#[derive(Args)]
-pub(crate) struct DoctorArgs {
-    #[arg(long, short)]
-    pub(crate) fix: Option<PathBuf>,
+fn dotted_case(s: &str) -> Result<String, String> {
+    if s == s.to_snake_case().replace('_', ".") {
+        Ok(s.to_string())
+    } else {
+        Err(format!("Invalid dotted case: {}", s))
+    }
+}
+
+fn pascal_case(s: &str) -> Result<String, String> {
+    if s == s.to_pascal_case() {
+        Ok(s.to_string())
+    } else {
+        Err(format!("Invalid pascal case: {}", s))
+    }
+}
+
+fn snake_case(s: &str) -> Result<String, String> {
+    if s == s.to_snake_case() {
+        Ok(s.to_string())
+    } else {
+        Err(format!("Invalid snake case: {}", s))
+    }
 }
 
 #[cfg(test)]

crux_cli/src/args.rs

@@ -0,0 +1,77 @@
+# Crux CLI codegen for foreign types
+
+The codegen command on the `crux` CLI generates code for foreign types in Swift,
+Kotlin and TypeScript.
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> This is a work in progress and is not yet ready for general use.
+
+```sh
+# currently requires Rust nightly to be installed (`rustup install nightly`)
+crux codegen --lib shared
+```
+
+The `--lib` flag specifies the library to generate code for. The `shared`
+library is used in this example.
+
+## How it works
+
+### Source data
+
+Generate `rustdoc` JSON for the library, using the
+[`rustdoc_json`][rustdocJsonReference] crate. We want to use the latest format
+version so we currently require Rust nightly to be installed
+(`rustup install nightly`). This JSON describes all the public and private items
+in the library and is deserialized using the
+[`rustdoc-types`][rustdocTypesReference] crate.
+
+### Build a graph
+
+```mermaid
+graph TD
+    Ty([Type])
+    S([Struct])
+    SF([Struct Field])
+    E([Enum])
+    V([Variant])
+    I([Impl])
+    AI([Associated Item])
+    TA([App Trait])
+    TE([Effect Trait])
+    S --> |Field| SF
+    E --> |Variant| V
+    V --> |Field| SF
+    SF --> |Type| Ty
+    I --> |AssociatedItem| AI
+    AI --> |AssociatedType| Ty
+    I -.-> |TraitApp| TA
+    I -.-> |TraitEffect| TE
+```
+
+Process the data using the [`ascent`][ascentCrateReference] crate to run a logic
+program (similar to Datalog) on the items, summaries and crates that are listed in the JSON.
+
+We find any structs that implement the `App` trait, and build a hierarchy of those, so that we can determine which one is the root app.
+
+We then dig into its associated items to find the ViewModel, Event, and Effect (with each effect's Operation and Output).
+
+We also find any foreign crates that are needed and queue them for processing.
+
+### Create an intermediate representation
+
+Finally we take the set of edges we are interested in and use them to build an intermediate representation that is compatible with the [`serde_generate`][serdeGenerateReference] crate. This allows us to use the same backend that we are currently using in order to maintain backwards compatibility.
+
+### Generate foreign types
+
+The IR is used to generate code for foreign types in Swift, Kotlin and
+TypeScript, via a vendored version of the
+[`serde_generate`][serdeGenerateReference] crate.
+
+We will likely want to change this in the future to allow us to generate more
+idiomatic code for each language, and support Crux more fully.
+
+[ascentCrateReference]: https://crates.io/crates/ascent
+[rustdocJsonReference]: https://crates.io/crates/rustdoc-json
+[rustdocTypesReference]: https://crates.io/crates/rustdoc-types
+[serdeGenerateReference]: https://crates.io/crates/serde-generate