Add "classes" object to manifest.json file (#864)

Author: TooTallNate

.changeset/major-mails-act.md

@@ -0,0 +1,6 @@
+---
+"@workflow/swc-plugin": patch
+"@workflow/builders": patch
+---
+
+Add "classes" object to `manifest.json` file

packages/builders/src/apply-swc-transform.ts

@@ -37,6 +37,13 @@ export type WorkflowManifest = {
       };
     };
   };
+  classes?: {
+    [relativeFileName: string]: {
+      [className: string]: {
+        classId: string;
+      };
+    };
+  };
 };
 
 export async function applySwcTransform(

packages/builders/src/base-builder.ts

@@ -414,6 +414,12 @@ export abstract class BaseBuilder {
               fileManifest.workflows
             );
           }
+          if (fileManifest.classes) {
+            workflowManifest.classes = Object.assign(
+              workflowManifest.classes || {},
+              fileManifest.classes
+            );
+          }
         } catch (error) {
           // Log warning but continue - don't fail build for workflow-only file issues
           console.log(
@@ -904,7 +910,7 @@ export const OPTIONS = handler;`;
   }
 
   /**
-   * Creates a manifest JSON file containing step/workflow metadata
+   * Creates a manifest JSON file containing step/workflow/class metadata
    * and graph data for visualization.
    */
   protected async createManifest({
@@ -927,8 +933,9 @@ export const OPTIONS = handler;`;
         manifest.workflows,
         workflowGraphs
       );
+      const classes = this.convertClassesManifest(manifest.classes);
 
-      const output = { version: '1.0.0', steps, workflows };
+      const output = { version: '1.0.0', steps, workflows, classes };
 
       await mkdir(manifestDir, { recursive: true });
       await writeFile(
@@ -944,9 +951,13 @@ export const OPTIONS = handler;`;
         (acc, w) => acc + Object.keys(w).length,
         0
       );
+      const classCount = Object.values(classes).reduce(
+        (acc, c) => acc + Object.keys(c).length,
+        0
+      );
 
       console.log(
-        `Created manifest with ${stepCount} step(s) and ${workflowCount} workflow(s)`,
+        `Created manifest with ${stepCount} step(s), ${workflowCount} workflow(s), and ${classCount} class(es)`,
         `${Date.now() - buildStart}ms`
       );
     } catch (error) {
@@ -1005,4 +1016,19 @@ export const OPTIONS = handler;`;
     }
     return result;
   }
+
+  private convertClassesManifest(
+    classes: WorkflowManifest['classes']
+  ): Record<string, Record<string, { classId: string }>> {
+    const result: Record<string, Record<string, { classId: string }>> = {};
+    if (!classes) return result;
+
+    for (const [filePath, entries] of Object.entries(classes)) {
+      result[filePath] = {};
+      for (const [name, data] of Object.entries(entries)) {
+        result[filePath][name] = { classId: data.classId };
+      }
+    }
+    return result;
+  }
 }

packages/builders/src/swc-esbuild-plugin.ts

@@ -218,6 +218,10 @@ export function createSwcPlugin(options: SwcPluginOptions): Plugin {
             options.workflowManifest.steps || {},
             workflowManifest.steps
           );
+          options.workflowManifest.classes = Object.assign(
+            options.workflowManifest.classes || {},
+            workflowManifest.classes
+          );
 
           return {
             contents: transformedCode,

packages/swc-plugin-workflow/spec.md

@@ -17,13 +17,18 @@ Directives must:
 
 ## JSON Manifest
 
-All modes emit a JSON manifest comment at the top of the file containing metadata about discovered workflows and steps:
+All modes emit a JSON manifest comment at the top of the file containing metadata about discovered workflows, steps, and classes with custom serialization:
 
 ```javascript
-/**__internal_workflows{"workflows":{"path/file.ts":{"myWorkflow":{"workflowId":"workflow//path/file.ts//myWorkflow"}}},"steps":{"path/file.ts":{"myStep":{"stepId":"step//path/file.ts//myStep"}}}}*/
+/**__internal_workflows{"workflows":{"path/file.ts":{"myWorkflow":{"workflowId":"workflow//path/file.ts//myWorkflow"}}},"steps":{"path/file.ts":{"myStep":{"stepId":"step//path/file.ts//myStep"}}},"classes":{"path/file.ts":{"Point":{"classId":"class//path/file.ts//Point"}}}}*/
 ```
 
-This manifest is used by bundlers and the runtime to discover and register workflows and steps.
+The manifest includes:
+- **`workflows`**: Map of workflow function names to their `workflowId`
+- **`steps`**: Map of step function names to their `stepId`
+- **`classes`**: Map of class names with custom serialization to their `classId`
+
+This manifest is used by bundlers and the runtime to discover and register workflows, steps, and serializable classes.
 
 ## ID Generation
 
@@ -340,6 +345,7 @@ export class Point {
 Output (Client Mode):
 ```javascript
 import { registerSerializationClass } from "workflow/internal/class-serialization";
+/**__internal_workflows{"classes":{"input.js":{"Point":{"classId":"class//input.js//Point"}}}}*/;
 export class Point {
     constructor(x, y) {
         this.x = x;
@@ -377,7 +383,7 @@ Output (Step Mode):
 ```javascript
 import { registerStepFunction } from "workflow/internal/private";
 import { registerSerializationClass } from "workflow/internal/class-serialization";
-/**__internal_workflows{"steps":{"input.js":{"MyService.process":{"stepId":"step//input.js//MyService.process"}}}}*/;
+/**__internal_workflows{"steps":{"input.js":{"MyService.process":{"stepId":"step//input.js//MyService.process"}}},"classes":{"input.js":{"MyService":{"classId":"class//input.js//MyService"}}}}*/;
 export class MyService {
     static async process(data) {
         return data.value * 2;
@@ -390,7 +396,7 @@ registerSerializationClass("class//input.js//MyService", MyService);
 Output (Workflow Mode):
 ```javascript
 import { registerSerializationClass } from "workflow/internal/class-serialization";
-/**__internal_workflows{"steps":{"input.js":{"MyService.process":{"stepId":"step//input.js//MyService.process"}}}}*/;
+/**__internal_workflows{"steps":{"input.js":{"MyService.process":{"stepId":"step//input.js//MyService.process"}}},"classes":{"input.js":{"MyService":{"classId":"class//input.js//MyService"}}}}*/;
 export class MyService {
 }
 MyService.process = globalThis[Symbol.for("WORKFLOW_USE_STEP")]("step//input.js//MyService.process");
@@ -448,6 +454,7 @@ export class Point {
 Output:
 ```javascript
 import { registerSerializationClass } from "workflow/internal/class-serialization";
+/**__internal_workflows{"classes":{"input.js":{"Point":{"classId":"class//input.js//Point"}}}}*/;
 export class Point {
     constructor(x, y) {
         this.x = x;

packages/swc-plugin-workflow/transform/src/lib.rs

@@ -230,6 +230,8 @@ pub struct StepTransform {
     // Track identifiers that are known to be WORKFLOW_SERIALIZE symbols
     // (local name -> "workflow-serialize" or "workflow-deserialize")
     serialization_symbol_identifiers: HashMap<String, String>,
+    // Track class names for the manifest (preserved copy before drain)
+    classes_for_manifest: HashSet<String>,
 }
 
 // Structure to track variable names and their access patterns
@@ -1094,6 +1096,7 @@ impl StepTransform {
             static_step_methods_to_strip: Vec::new(),
             classes_needing_serialization: HashSet::new(),
             serialization_symbol_identifiers: HashMap::new(),
+            classes_for_manifest: HashSet::new(),
         }
     }
 
@@ -3006,6 +3009,22 @@ impl StepTransform {
             metadata.insert("workflows", format!("{{{}}}", workflow_entries.join(",")));
         }
 
+        // Build classes metadata
+        if !self.classes_for_manifest.is_empty() {
+            let mut sorted_classes: Vec<_> = self.classes_for_manifest.iter().collect();
+            sorted_classes.sort();
+
+            let class_entries: Vec<String> = sorted_classes
+                .into_iter()
+                .map(|class_name| {
+                    let class_id = naming::format_name("class", &self.filename, class_name);
+                    format!("\"{}\":{{\"classId\":\"{}\"}}", class_name, class_id)
+                })
+                .collect();
+
+            metadata.insert("classes", format!("{{{}}}", class_entries.join(",")));
+        }
+
         // Build the final comment structure
         let relative_filename = self.filename.replace('\\', "/"); // Normalize path separators
         let mut parts = Vec::new();
@@ -3022,6 +3041,12 @@ impl StepTransform {
                 relative_filename, metadata["steps"]
             ));
         }
+        if metadata.contains_key("classes") {
+            parts.push(format!(
+                "\"classes\":{{\"{}\":{}}}",
+                relative_filename, metadata["classes"]
+            ));
+        }
 
         if parts.is_empty() {
             String::new()
@@ -3234,6 +3259,9 @@ impl VisitMut for StepTransform {
         // First pass: collect step functions
         program.visit_mut_children_with(self);
 
+        // Preserve class names for manifest before they get drained during registration
+        self.classes_for_manifest = self.classes_needing_serialization.clone();
+
         // Add necessary imports and registrations
         match program {
             Program::Module(module) => {

packages/swc-plugin-workflow/transform/tests/errors/instance-methods/output-client.js

@@ -1,5 +1,5 @@
 import { registerSerializationClass } from "workflow/internal/class-serialization";
-/**__internal_workflows{"steps":{"input.js":{"TestClass.staticMethod":{"stepId":"step//input.js//TestClass.staticMethod"}}}}*/;
+/**__internal_workflows{"steps":{"input.js":{"TestClass.staticMethod":{"stepId":"step//input.js//TestClass.staticMethod"}}},"classes":{"input.js":{"TestClass":{"classId":"class//input.js//TestClass"}}}}*/;
 export class TestClass {
     // Error: instance methods can't have directives
     async instanceMethod() {

packages/swc-plugin-workflow/transform/tests/errors/instance-methods/output-step.js

@@ -1,6 +1,6 @@
 import { registerStepFunction } from "workflow/internal/private";
 import { registerSerializationClass } from "workflow/internal/class-serialization";
-/**__internal_workflows{"steps":{"input.js":{"TestClass.staticMethod":{"stepId":"step//input.js//TestClass.staticMethod"}}}}*/;
+/**__internal_workflows{"steps":{"input.js":{"TestClass.staticMethod":{"stepId":"step//input.js//TestClass.staticMethod"}}},"classes":{"input.js":{"TestClass":{"classId":"class//input.js//TestClass"}}}}*/;
 export class TestClass {
     // Error: instance methods can't have directives
     async instanceMethod() {

packages/swc-plugin-workflow/transform/tests/errors/instance-methods/output-workflow.js

@@ -1,5 +1,5 @@
 import { registerSerializationClass } from "workflow/internal/class-serialization";
-/**__internal_workflows{"steps":{"input.js":{"TestClass.staticMethod":{"stepId":"step//input.js//TestClass.staticMethod"}}}}*/;
+/**__internal_workflows{"steps":{"input.js":{"TestClass.staticMethod":{"stepId":"step//input.js//TestClass.staticMethod"}}},"classes":{"input.js":{"TestClass":{"classId":"class//input.js//TestClass"}}}}*/;
 export class TestClass {
     // Error: instance methods can't have directives
     async instanceMethod() {

packages/swc-plugin-workflow/transform/tests/fixture/custom-serialization-imported/output-client.js

@@ -1,6 +1,7 @@
 import { registerSerializationClass } from "workflow/internal/class-serialization";
 // Test custom serialization with imported symbols from '@workflow/serde'
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
+/**__internal_workflows{"classes":{"input.js":{"Color":{"classId":"class//input.js//Color"},"Vector":{"classId":"class//input.js//Vector"}}}}*/;
 // Class using imported symbols
 export class Vector {
     constructor(x, y, z){