@c7-digital/ledger 0.0.2

package/scripts/enhance-types.ts

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// Script to automatically brand OpenAPI generated types with value.proto constraints
+// Ideally the spec would provide this, but this is sufficient for now.
+
+import { readFileSync, writeFileSync, unlinkSync } from "fs";
+import { join, dirname } from "path";
+
+interface ValueProtoPattern {
+  // The JSDoc comment pattern to match
+  commentPattern: string;
+  // The target type to replace with (for string fields)
+  targetType: string;
+}
+
+// Patterns to find fields with value.proto references based on JSDoc comments
+// Each entry automatically handles both string and string[] cases
+const VALUE_PROTO_PATTERNS: ValueProtoPattern[] = [
+  // LedgerString patterns
+  {
+    commentPattern: "Must be a valid LedgerString",
+    targetType: "LedgerString",
+  },
+
+  // PartyIdString patterns
+  {
+    commentPattern: "Must be a valid PartyIdString",
+    targetType: "PartyIdString",
+  },
+
+  // UserIdString patterns
+  {
+    commentPattern: "Must be a valid UserIdString",
+    targetType: "UserIdString",
+  },
+
+  // NameString patterns
+  {
+    commentPattern: "Must be a valid NameString",
+    targetType: "NameString",
+  },
+
+  // PackageIdString patterns
+  {
+    commentPattern: "Must be a valid PackageIdString",
+    targetType: "PackageIdString",
+  },
+  {
+    commentPattern: "The identifier uses the package-id reference format",
+    targetType: "PackageIdString",
+  },
+];
+
+function brandApiTypes(inputPath: string, outputPath: string, label: string): number {
+  console.log(`🔄 Branding ${label} types with value.proto constraints...`);
+  const content = readFileSync(inputPath, "utf-8");
+  let brandedContent = content;
+
+  // Add imports at the top if not already present
+  if (!content.includes('from "../valueTypes.js"')) {
+    const importStatement = `import { LedgerString, PartyIdString, UserIdString, NameString, PackageIdString } from "../valueTypes.js";\n\n`;
+    brandedContent = importStatement + brandedContent;
+  }
+
+  let replacementCount = 0;
+
+  // Track usage of each comment pattern
+  const patternUsage = new Map<string, { count: number; examples: string[] }>();
+
+  // This regex captures JSDoc comments followed by field declarations
+  // We're looking for: /** JSDoc comment */ fieldName?: fieldType;
+  // 
+  // Regex breakdown:
+  // /\/\*\*                           - Match opening /** (literal forward slash, asterisk, asterisk)
+  // ([^*]|[\r\n]|(\*+([^*/]|[\r\n])))* - Match JSDoc content (non-greedy):
+  //   [^*]                            - Any character except asterisk
+  //   |[\r\n]                         - OR newline characters (carriage return or line feed)
+  //   |(\*+([^*/]|[\r\n]))            - OR one or more asterisks followed by non-closing chars
+  // \*+\/                             - Match closing */ (one or more asterisks + forward slash)
+  // \s*                               - Match optional whitespace after JSDoc
+  // (\w+)                             - Capture group 4: field name (word characters)
+  // (\?)?                             - Capture group 5: optional question mark for optional fields
+  // \s*:\s*                           - Match colon with optional whitespace around it
+  // ([^;,\}\n]+)                      - Capture group 6: field type (everything except semicolon, comma, closing brace, newline)
+  //
+  // The regex handles multi-line JSDoc with @description tags and indented fields within object types
+  const fieldRegex =
+    /\/\*\*([^*]|[\r\n]|(\*+([^*/]|[\r\n])))*\*+\/\s*(\w+)(\?)?\s*:\s*([^;,\}\n]+)/g;
+
+  // Use a more compatible approach for regex matching
+  const matches: RegExpExecArray[] = [];
+  let match: RegExpExecArray | null;
+  while ((match = fieldRegex.exec(content)) !== null) {
+    matches.push(match);
+  }
+
+
+  // Process each match
+  for (const match of matches) {
+    if (match.length < 6) continue;
+
+    const fullMatch = match[0];
+    const jsDocComment = match[0].substring(3, match[0].indexOf("*/")); // Extract JSDoc content
+    const fieldName = match[4]; // Field name
+    const isOptional = match[5] === "?"; // Optional marker
+    const fieldType = match[6]; // Field type (could be anything)
+
+
+    // Skip if we don't have the necessary data
+    if (!fullMatch || !fieldName || !fieldType) continue;
+
+    // Check if this is a string-related type that we care about
+    const trimmedFieldType = fieldType.trim();
+    if (trimmedFieldType === "string" || trimmedFieldType === "string[]") {
+      // Check if the JSDoc comment matches any of our patterns
+      for (const { commentPattern, targetType } of VALUE_PROTO_PATTERNS) {
+        // Check if JSDoc contains the pattern
+        if (jsDocComment.includes(commentPattern)) {
+          // Extra validation: ensure this is actually a value.proto constraint comment
+          if (
+            commentPattern.includes("Must be a valid") ||
+            commentPattern.includes("package-id reference format")
+          ) {
+            // Determine the correct target type based on whether it's an array
+            const finalTargetType =
+              trimmedFieldType === "string[]" ? `${targetType}[]` : targetType;
+
+            // Create the branded declaration
+            const brandedDeclaration = fullMatch.replace(trimmedFieldType, finalTargetType);
+
+            // Replace in the content
+            brandedContent = brandedContent.replace(fullMatch, brandedDeclaration);
+            replacementCount++;
+
+            // Track pattern usage
+            const fieldExample = `${fieldName}${isOptional ? "?" : ""}: ${trimmedFieldType} → ${finalTargetType}`;
+            if (!patternUsage.has(commentPattern)) {
+              patternUsage.set(commentPattern, { count: 0, examples: [] });
+            }
+            const usage = patternUsage.get(commentPattern)!;
+            usage.count++;
+            if (usage.examples.length < 3) {
+              // Keep up to 3 examples per pattern
+              usage.examples.push(fieldExample);
+            }
+
+            // Log the branding with field name
+            const optionalMarker = isOptional ? "?" : "";
+            console.log(
+              `✅ Branded ${fieldName}${optionalMarker}: ${trimmedFieldType} → ${finalTargetType}`
+            );
+            // console.log(`JSDoc: ${jsDocComment}`);
+            // console.log(`Pattern: ${commentPattern}`);
+            // console.log(`---------------------------------`);
+            break; // Stop checking patterns once we've found a match
+          }
+        }
+      }
+    }
+  }
+
+  // Write branded content directly to the output file
+  console.log(`📝 Writing branded types to ${outputPath}...`);
+  writeFileSync(outputPath, brandedContent);
+
+  console.log(`🎉 Branded ${replacementCount} field declarations with value.proto constraints`);
+
+  // Report pattern usage summary
+  if (patternUsage.size > 0) {
+    console.log(`\n📊 Pattern Usage Summary:`);
+    console.log(`════════════════════════════════════════`);
+
+    // Sort patterns by usage count (descending)
+    const sortedPatterns = Array.from(patternUsage.entries()).sort(
+      ([, a], [, b]) => b.count - a.count
+    );
+
+    for (const [pattern, { count, examples }] of sortedPatterns) {
+      console.log(`\n🔖 "${pattern}"`);
+      console.log(`   Used ${count} time${count === 1 ? "" : "s"}`);
+      console.log(`   Examples:`);
+      for (const example of examples) {
+        console.log(`     • ${example}`);
+      }
+      if (count > examples.length) {
+        console.log(`     ... and ${count - examples.length} more`);
+      }
+    }
+    console.log(`\n════════════════════════════════════════`);
+  }
+
+  return replacementCount;
+}
+
+function brandTypes(inputPath: string, outputPath: string, label: string = "API"): void {
+  brandApiTypes(inputPath, outputPath, label);
+}
+
+// Export the function for use in other scripts
+export { brandTypes };
+
+// Check if this script is being run directly
+// For ES modules, we check if the import.meta.url matches the process.argv[1]
+const isMainModule =
+  process.argv[1] &&
+  (process.argv[1].endsWith("brand-types.ts") || process.argv[1].endsWith("enhance-types.ts"));
+if (isMainModule) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2) {
+    console.error("Usage: brand-types.ts <input-file> <output-file> [label]");
+    process.exit(1);
+  }
+
+  if (!args[0] || !args[1]) {
+    console.error("Input and output files must be specified.");
+    process.exit(1);
+  }
+  const inputPath = args[0];
+  const outputPath = args[1];
+  const label = args[2] || "API";
+
+  brandTypes(inputPath, outputPath, label);
+}

package/scripts/generate-asyncapi-types.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+/**
+ * Generate TypeScript types from AsyncAPI specification by converting to OpenAPI format
+ *
+ * This script converts the AsyncAPI YAML to OpenAPI format and uses the existing
+ * openapi-typescript generator to create types. Much simpler than custom schema parsing.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+import { exec } from "child_process";
+import { promisify } from "util";
+
+const execAsync = promisify(exec);
+const __dirname = process.cwd();
+
+async function generateAsyncApiTypes(specPath?: string): Promise<void> {
+  try {
+    // Get spec path from parameter or command line argument
+    const asyncApiSpecPath = specPath || process.argv[2];
+    if (!asyncApiSpecPath) {
+      console.error("Usage: node generate-asyncapi-types.ts <path-to-asyncapi-spec>");
+      process.exit(1);
+    }
+
+    // Read the AsyncAPI specification
+    const asyncApiPath = path.resolve(asyncApiSpecPath);
+    const asyncApiContent = fs.readFileSync(asyncApiPath, "utf8");
+    const asyncApiSpec = yaml.parse(asyncApiContent);
+
+    // Convert AsyncAPI to OpenAPI format by changing the header
+    const openApiSpec = {
+      ...asyncApiSpec,
+      openapi: "3.0.3",
+      info: asyncApiSpec.info,
+      components: asyncApiSpec.components,
+      // Remove AsyncAPI-specific fields
+      asyncapi: undefined,
+      channels: undefined,
+      operations: undefined,
+      // Add empty paths since OpenAPI requires it
+      paths: {},
+    };
+
+    // Clean up undefined properties
+    delete openApiSpec.asyncapi;
+    delete openApiSpec.channels;
+    delete openApiSpec.operations;
+
+    // Create temporary OpenAPI file
+    const tempOpenApiPath = path.join(__dirname, "temp-asyncapi-as-openapi.yaml");
+    fs.writeFileSync(tempOpenApiPath, yaml.stringify(openApiSpec));
+
+    console.log(`📝 Created temporary OpenAPI file: ${tempOpenApiPath}`);
+    console.log(`🔄 Generating types using openapi-typescript...`);
+
+    // Use the existing openapi-typescript generator
+    const outputPath = path.join(__dirname, "src", "generated", "async-api.ts");
+    const generateCommand = `pnpm exec openapi-typescript "${tempOpenApiPath}" --output "${outputPath}"`;
+
+    const { stdout, stderr } = await execAsync(generateCommand);
+
+    if (stderr && !stderr.includes("Warning")) {
+      console.warn("openapi-typescript warnings:", stderr);
+    }
+
+    if (stdout) {
+      console.log("openapi-typescript output:", stdout);
+    }
+
+    // Now add channels interface for WebSocket connections
+    console.log(`🔄 Adding channels interface for WebSocket connections...`);
+
+    // Parse the original AsyncAPI spec to extract channels
+    let channelsInterface = "\nexport interface channels {\n";
+
+    if (asyncApiSpec.channels) {
+      for (const [channelPath, channelData] of Object.entries(asyncApiSpec.channels)) {
+        const channel = channelData as any;
+        channelsInterface += `  "${channelPath}": {\n`;
+
+        // Add description if available
+        if (channel.description) {
+          channelsInterface += `    /** @description ${channel.description} */\n`;
+        }
+
+        // Add operations (publish/subscribe)
+        if (channel.publish) {
+          channelsInterface += `    publish: {\n`;
+          if (channel.publish.description) {
+            channelsInterface += `      /** @description ${channel.publish.description} */\n`;
+          }
+          if (channel.publish.message) {
+            const messageRef = channel.publish.message.$ref || channel.publish.message;
+            const messageName =
+              typeof messageRef === "string" && messageRef.includes("#/")
+                ? messageRef.replace("#/components/messages/", "")
+                : messageRef;
+            channelsInterface += `      message: components["schemas"]["${messageName}"];\n`;
+          }
+          channelsInterface += `    };\n`;
+        }
+
+        if (channel.subscribe) {
+          channelsInterface += `    subscribe: {\n`;
+          if (channel.subscribe.description) {
+            channelsInterface += `      /** @description ${channel.subscribe.description} */\n`;
+          }
+          if (channel.subscribe.message) {
+            const messageRef = channel.subscribe.message.$ref || channel.subscribe.message;
+            const messageName =
+              typeof messageRef === "string" && messageRef.includes("#/")
+                ? messageRef.replace("#/components/messages/", "")
+                : messageRef;
+            channelsInterface += `      message: components["schemas"]["${messageName}"];\n`;
+          }
+          channelsInterface += `    };\n`;
+        }
+
+        channelsInterface += `  };\n`;
+      }
+    }
+
+    channelsInterface += "}\n";
+
+    // Append channels interface to the generated file
+    const generatedContent = fs.readFileSync(outputPath, "utf8");
+    const brandedContent = generatedContent + channelsInterface;
+    fs.writeFileSync(outputPath, brandedContent);
+
+    // Clean up temporary file
+    fs.unlinkSync(tempOpenApiPath);
+    console.log(`🧹 Cleaned up temporary file`);
+
+    console.log(`✅ Generated AsyncAPI types with channels interface: ${outputPath}`);
+  } catch (error) {
+    console.error("❌ Error generating AsyncAPI types:", (error as Error).message);
+
+    // Clean up temporary file on error
+    const tempOpenApiPath = path.join(__dirname, "temp-asyncapi-as-openapi.yaml");
+    if (fs.existsSync(tempOpenApiPath)) {
+      fs.unlinkSync(tempOpenApiPath);
+      console.log(`🧹 Cleaned up temporary file after error`);
+    }
+
+    process.exit(1);
+  }
+}
+
+// Export the function for use in other scripts
+export { generateAsyncApiTypes };
+
+// Only run directly if this file is executed as main module
+if (import.meta.url === `file://${process.argv[1]}`) {
+  generateAsyncApiTypes();
+}

package/scripts/generate-schema-modules.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env tsx
+
+import { readFileSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function generateSchemaModule(yamlPath: string, outputPath: string, exportName: string) {
+  const yamlContent = readFileSync(yamlPath, "utf-8");
+
+  // Escape the YAML content for TypeScript string literal
+  const escapedContent = yamlContent
+    .replace(/\\/g, "\\\\")
+    .replace(/`/g, "\\`")
+    .replace(/\$\{/g, "\\${");
+
+  const tsContent = `// Auto-generated file - do not edit manually
+// Generated from ${yamlPath}
+
+export const ${exportName} = \`${escapedContent}\`;
+`;
+
+  writeFileSync(outputPath, tsContent, "utf-8");
+  console.log(`✅ Generated ${outputPath} from ${yamlPath}`);
+}
+
+// Export the function for use in other scripts
+export { generateSchemaModule };
+
+// Only run directly if this file is executed as main module
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const projectRoot = join(__dirname, "..");
+  const specsDir = join(projectRoot, "specs");
+  const outputDir = join(projectRoot, "src", "generated");
+
+  // Generate modules for both schemas
+  generateSchemaModule(
+    join(specsDir, "openapi_2025-08-31.yaml"),
+    join(outputDir, "openapi-schema.ts"),
+    "OPENAPI_SCHEMA"
+  );
+
+  generateSchemaModule(
+    join(specsDir, "asyncapi_2025-08-31.yaml"),
+    join(outputDir, "asyncapi-schema.ts"),
+    "ASYNCAPI_SCHEMA"
+  );
+
+  console.log("🎉 All schema modules generated successfully!");
+}