Merge pull request #147 from paritytech/worktree-require-ts-examples

feat(codegen): require a `ts` example on every trait method

Author: pgherveou

README.md

@@ -65,7 +65,7 @@ scripts/codegen.sh       Regenerate the TS client from the Rust source
 
 ## How it works
 
-1. The protocol is defined as Rust traits in [`rust/crates/truapi/`](rust/crates/truapi/), with each method tagged `#[wire(id = N)]` for a stable byte-level dispatch table.
+1. The protocol is defined as Rust traits in [`rust/crates/truapi/`](rust/crates/truapi/), with each method tagged `#[wire(id = N)]` for a stable byte-level dispatch table. Every method's doc comment must carry a ` ```ts ` example, which codegen extracts into the playground's EXAMPLE tab; the build fails if any method is missing one.
 2. `truapi-codegen` reads rustdoc JSON for that crate and generates the TypeScript client under git-ignored paths in `js/packages/truapi/`.
 3. Higher-level SDKs wrap the typed client; the transport encodes SCALE frames and ships them over `MessagePort` (or `postMessage` in iframe mode) to the host.
 4. The host decodes the frame, dispatches to the matching trait method, encodes the response, and ships it back.

rust/crates/truapi-codegen/src/ts.rs

@@ -365,6 +365,8 @@ pub fn generate(
 ) -> Result<()> {
     fs::create_dir_all(output_dir)?;
     validate_versioned_wrapper_shapes(api)?;
+    let wrappers = collect_versioned_wrappers(api);
+    playground::validate_method_examples(api, &wrappers, target_version)?;
 
     let types_code = generate_types(api, target_version)?;
     fs::write(Path::new(output_dir).join("types.ts"), types_code)?;

rust/crates/truapi-codegen/src/ts/playground.rs

@@ -197,6 +197,47 @@ pub(super) fn split_playground_docs(docs: Option<&str>) -> Result<PlaygroundDocs
     })
 }
 
+/// Fails if any public trait method lacks a valid ` ```ts ` example in its
+/// doc comment. Every method renders an EXAMPLE tab in the playground from
+/// the extracted `exampleSource`; a missing or mis-fenced example would
+/// silently leave that tab empty and dump the snippet into the description.
+pub(super) fn validate_method_examples(
+    api: &ApiDefinition,
+    wrappers: &HashMap<String, VersionedWrapper>,
+    target_version: u32,
+) -> Result<()> {
+    for service in public_services(api)? {
+        let trait_def = service.trait_def;
+        for method in included_methods(trait_def, wrappers, target_version)? {
+            validate_example_docs(&trait_def.name, &method.name, method.docs.as_deref())?;
+        }
+    }
+    Ok(())
+}
+
+/// Checks a single method's doc comment carries exactly one ` ```ts ` example
+/// that `split_playground_docs` can extract. Rejects a missing example, an
+/// example fenced with an unrecognized label, and any code fence left behind
+/// in the description (which means the example was not extracted).
+fn validate_example_docs(trait_name: &str, method_name: &str, docs: Option<&str>) -> Result<()> {
+    let parsed = split_playground_docs(docs)?;
+    if let Some(description) = &parsed.description
+        && description.contains("```")
+    {
+        bail!(
+            "{trait_name}::{method_name} has a code fence left in its description; \
+             examples must be fenced with ```ts so they are extracted into exampleSource"
+        );
+    }
+    if parsed.client_example.is_none() {
+        bail!(
+            "{trait_name}::{method_name} has no ```ts example in its doc comment; \
+             every TrUAPI method must carry one so the playground renders an EXAMPLE tab"
+        );
+    }
+    Ok(())
+}
+
 pub(super) fn playground_type_name(value: &str) -> String {
     value.replace("T.", "")
 }
@@ -401,6 +442,35 @@ mod tests {
         assert_eq!(data_type_id_from_ts(""), None);
     }
 
+    #[test]
+    fn validate_example_docs_accepts_ts_fence() {
+        let docs = "Summary line.\n\n```ts\nconst x = 1;\n```";
+        assert!(validate_example_docs("CoinPayment", "create_purse", Some(docs)).is_ok());
+    }
+
+    #[test]
+    fn validate_example_docs_rejects_missing_example() {
+        let docs = "Summary line with no example.";
+        let err = validate_example_docs("CoinPayment", "create_purse", Some(docs)).unwrap_err();
+        assert!(err.to_string().contains("no ```ts example"));
+    }
+
+    #[test]
+    fn validate_example_docs_rejects_missing_docs() {
+        let err = validate_example_docs("CoinPayment", "create_purse", None).unwrap_err();
+        assert!(err.to_string().contains("no ```ts example"));
+    }
+
+    #[test]
+    fn validate_example_docs_rejects_unrecognized_label() {
+        let docs = "Summary.\n\n```truapi-client-example\nconst x = 1;\n```";
+        let err = validate_example_docs("CoinPayment", "create_purse", Some(docs)).unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("code fence left in its description")
+        );
+    }
+
     #[test]
     fn data_type_id_kebabs_named_types() {
         assert_eq!(