@c7-digital/ledger 0.0.2

package/lib-lite/scripts/build.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env tsx
+/**
+ * Unified build script that uses SDK version-based spec files and runs all build steps
+ */
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { exec } from "child_process";
+import { promisify } from "util";
+import { readdir, writeFile, mkdir, unlink, copyFile } from "fs/promises";
+import { existsSync } from "fs";
+import { brandTypes } from "./enhance-types.js";
+import { generateSchemaModule } from "./generate-schema-modules.js";
+import { generateAsyncApiTypes } from "./generate-asyncapi-types.js";
+const execAsync = promisify(exec);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const projectRoot = join(__dirname, "..");
+/**
+ * Get SDK version from command line arguments or discover latest
+ */
+function getSdkVersion() {
+    const args = process.argv.slice(2);
+    const versionArg = args.find(arg => arg.startsWith("--sdk-version="));
+    if (versionArg) {
+        return versionArg.split("=")[1];
+    }
+    return undefined;
+}
+/**
+ * Discover spec files based on SDK version or find latest version-based specs
+ */
+async function discoverSpecFiles(sdkVersion) {
+    const specsDir = join(projectRoot, "specs");
+    const files = await readdir(specsDir);
+    if (sdkVersion) {
+        console.log(`🔍 Looking for spec files with SDK version: ${sdkVersion}`);
+        const openApiFile = `openapi_${sdkVersion}.yaml`;
+        const asyncApiFile = `asyncapi_${sdkVersion}.yaml`;
+        const result = {};
+        if (files.includes(openApiFile)) {
+            result.openapi = join(specsDir, openApiFile);
+            console.log(`📄 Found OpenAPI spec: ${openApiFile}`);
+        }
+        else {
+            console.warn(`⚠️  OpenAPI spec not found: ${openApiFile}`);
+        }
+        if (files.includes(asyncApiFile)) {
+            result.asyncapi = join(specsDir, asyncApiFile);
+            console.log(`📄 Found AsyncAPI spec: ${asyncApiFile}`);
+        }
+        else {
+            console.warn(`⚠️  AsyncAPI spec not found: ${asyncApiFile}`);
+        }
+        return { specs: result, version: sdkVersion };
+    }
+    else {
+        console.log("🔍 Auto-discovering latest version-based spec files...");
+        // Look for files with version pattern (not date pattern)
+        const versionPattern = /\d+\.\d+\.\d+(-snapshot\.\d{8}\.\d+)?/;
+        const openApiFiles = files
+            .filter(f => f.startsWith("openapi_") && f.endsWith(".yaml") && versionPattern.test(f))
+            .sort()
+            .reverse();
+        const asyncApiFiles = files
+            .filter(f => f.startsWith("asyncapi_") && f.endsWith(".yaml") && versionPattern.test(f))
+            .sort()
+            .reverse();
+        const result = {};
+        let detectedVersion = "";
+        if (openApiFiles.length > 0) {
+            result.openapi = join(specsDir, openApiFiles[0]);
+            console.log(`📄 Found OpenAPI spec: ${openApiFiles[0]}`);
+            // Extract version from filename
+            const match = openApiFiles[0].match(/openapi_(.+)\.yaml/);
+            if (match)
+                detectedVersion = match[1];
+        }
+        if (asyncApiFiles.length > 0) {
+            result.asyncapi = join(specsDir, asyncApiFiles[0]);
+            console.log(`📄 Found AsyncAPI spec: ${asyncApiFiles[0]}`);
+            // Use version from AsyncAPI if OpenAPI wasn't found
+            if (!detectedVersion) {
+                const match = asyncApiFiles[0].match(/asyncapi_(.+)\.yaml/);
+                if (match)
+                    detectedVersion = match[1];
+            }
+        }
+        if (!detectedVersion) {
+            throw new Error("Could not detect SDK version from spec files. Please specify --sdk-version=<version>");
+        }
+        console.log(`🎯 Detected SDK version: ${detectedVersion}`);
+        return { specs: result, version: detectedVersion };
+    }
+}
+/**
+ * Generate OpenAPI types using openapi-typescript
+ */
+async function generateTypes(specPath) {
+    console.log("🔄 Generating OpenAPI types...");
+    const outputPath = join(projectRoot, "src", "generated", "api.ts");
+    try {
+        const { stdout, stderr } = await execAsync(`pnpm exec openapi-typescript "${specPath}" --output "${outputPath}"`);
+        if (stderr && !stderr.includes("Warning")) {
+            console.warn("openapi-typescript warnings:", stderr);
+        }
+        if (stdout) {
+            console.log(stdout);
+        }
+        console.log("✅ Generated OpenAPI types");
+    }
+    catch (error) {
+        console.error("❌ Error generating OpenAPI types:", error.message);
+        throw error;
+    }
+}
+/**
+ * Generate schema modules for both OpenAPI and AsyncAPI
+ */
+function generateSchemaModules(specs) {
+    console.log("🔄 Generating schema modules...");
+    const outputDir = join(projectRoot, "src", "generated");
+    if (specs.openapi) {
+        generateSchemaModule(specs.openapi, join(outputDir, "openapi-schema.ts"), "OPENAPI_SCHEMA");
+    }
+    if (specs.asyncapi) {
+        generateSchemaModule(specs.asyncapi, join(outputDir, "asyncapi-schema.ts"), "ASYNCAPI_SCHEMA");
+    }
+    console.log("✅ All schema modules generated");
+}
+/**
+ * Ensure the generated directory exists
+ */
+async function ensureGeneratedDirectory() {
+    const outputDir = join(projectRoot, "src", "generated");
+    await mkdir(outputDir, { recursive: true });
+}
+/**
+ * Clean up any temporary files
+ */
+async function cleanupTempFiles() {
+    const generatedDir = join(projectRoot, "src", "generated");
+    const tempFiles = [
+        join(generatedDir, "api.ts.tmp"),
+        join(generatedDir, "async-api.ts.tmp"),
+        join(projectRoot, "temp-asyncapi-as-openapi.yaml"),
+    ];
+    for (const tempFile of tempFiles) {
+        if (existsSync(tempFile)) {
+            try {
+                await unlink(tempFile);
+                console.log(`🧹 Cleaned up ${tempFile}`);
+            }
+            catch (error) {
+                // Ignore cleanup errors, but log them
+                console.warn(`⚠️  Could not clean up ${tempFile}:`, error.message);
+            }
+        }
+    }
+}
+/**
+ * Generate SDK version constant file
+ */
+async function generateSdkVersionFile(version) {
+    console.log("🔄 Generating SDK version constant...");
+    const outputDir = join(projectRoot, "src", "generated");
+    const outputPath = join(outputDir, "sdk-version.ts");
+    const content = `// Auto-generated file - do not edit manually
+// Generated from SDK version: ${version}
+
+export const SDK_VERSION = "${version}";
+`;
+    await writeFile(outputPath, content, "utf-8");
+    console.log(`✅ Generated SDK version constant: ${version}`);
+}
+/**
+ * Brand API types with value.proto constraints (in-place)
+ */
+function brandApiTypes() {
+    console.log("🔄 Branding API types in-place...");
+    // Brand OpenAPI types (overwrite original file)
+    const apiPath = join(projectRoot, "src", "generated", "api.ts");
+    brandTypes(apiPath, apiPath, "OpenAPI");
+    // Brand AsyncAPI types (overwrite original file)
+    const asyncApiPath = join(projectRoot, "src", "generated", "async-api.ts");
+    brandTypes(asyncApiPath, asyncApiPath, "AsyncAPI");
+    console.log("✅ All types branded in-place");
+}
+/**
+ * Create stub schema files for lite build
+ */
+async function createStubSchemaFiles() {
+    console.log("🔄 Creating stub schema files for lite build...");
+    const outputDir = join(projectRoot, "src", "generated");
+    const openApiStub = `// Stub file for lite build - no schema content
+export const OPENAPI_SCHEMA = "";
+`;
+    const asyncApiStub = `// Stub file for lite build - no schema content
+export const ASYNCAPI_SCHEMA = "";
+`;
+    await writeFile(join(outputDir, "openapi-schema.ts"), openApiStub, "utf-8");
+    await writeFile(join(outputDir, "asyncapi-schema.ts"), asyncApiStub, "utf-8");
+    console.log("✅ Created stub schema files");
+}
+/**
+ * Replace validation module with lite version in lib-lite
+ */
+async function useLiteValidation() {
+    console.log("🔄 Replacing validation with lite version...");
+    const libLiteDir = join(projectRoot, "lib-lite", "src");
+    // Copy validation-lite.js over validation.js
+    const liteValidationJs = join(libLiteDir, "validation-lite.js");
+    const validationJs = join(libLiteDir, "validation.js");
+    if (existsSync(liteValidationJs)) {
+        await copyFile(liteValidationJs, validationJs);
+        await unlink(liteValidationJs);
+        console.log("✅ Replaced validation.js with lite version");
+    }
+    // Copy validation-lite.d.ts over validation.d.ts
+    const liteValidationDts = join(libLiteDir, "validation-lite.d.ts");
+    const validationDts = join(libLiteDir, "validation.d.ts");
+    if (existsSync(liteValidationDts)) {
+        await copyFile(liteValidationDts, validationDts);
+        await unlink(liteValidationDts);
+        console.log("✅ Replaced validation.d.ts with lite version");
+    }
+    // Also remove validation-lite files from lib/ (they shouldn't be there)
+    const libDir = join(projectRoot, "lib", "src");
+    const libLiteValidationJs = join(libDir, "validation-lite.js");
+    const libLiteValidationDts = join(libDir, "validation-lite.d.ts");
+    if (existsSync(libLiteValidationJs)) {
+        await unlink(libLiteValidationJs);
+    }
+    if (existsSync(libLiteValidationDts)) {
+        await unlink(libLiteValidationDts);
+    }
+}
+/**
+ * Compile TypeScript code
+ */
+async function compileTypeScript(outDir = "lib") {
+    console.log(`🔄 Compiling TypeScript to ${outDir}...`);
+    try {
+        let tscCommand = `pnpm exec tsc -p ${join(projectRoot, "tsconfig.json")}`;
+        let aliasCommand = `pnpm exec tsc-alias -p ${join(projectRoot, "tsconfig.json")}`;
+        if (outDir !== "lib") {
+            // Create a temporary tsconfig for different output directory
+            const tempTsConfig = {
+                extends: "./tsconfig.json",
+                compilerOptions: {
+                    outDir: `./${outDir}`,
+                    declarationDir: `./${outDir}`,
+                },
+            };
+            const tempConfigPath = join(projectRoot, "tsconfig.temp.json");
+            await writeFile(tempConfigPath, JSON.stringify(tempTsConfig, null, 2), "utf-8");
+            tscCommand = `pnpm exec tsc -p ${tempConfigPath}`;
+            aliasCommand = `pnpm exec tsc-alias -p ${tempConfigPath}`;
+        }
+        // Run tsc first (tsc-alias depends on tsc output)
+        const { stdout: tscStdout, stderr: tscStderr } = await execAsync(tscCommand);
+        if (tscStderr) {
+            console.error("TypeScript compiler errors/warnings:");
+            console.error(tscStderr);
+        }
+        if (tscStdout) {
+            console.log("TypeScript compiler output:");
+            console.log(tscStdout);
+        }
+        // Run tsc-alias after tsc completes
+        const { stdout: aliasStdout, stderr: aliasStderr } = await execAsync(aliasCommand);
+        if (aliasStderr) {
+            console.warn("tsc-alias warnings:", aliasStderr);
+        }
+        if (aliasStdout) {
+            console.log(aliasStdout);
+        }
+        // Clean up temp config if created
+        if (outDir !== "lib") {
+            const tempConfigPath = join(projectRoot, "tsconfig.temp.json");
+            if (existsSync(tempConfigPath)) {
+                await unlink(tempConfigPath);
+            }
+        }
+        console.log(`✅ TypeScript compilation complete for ${outDir}`);
+    }
+    catch (error) {
+        console.error(`❌ Error compiling TypeScript to ${outDir}:`);
+        console.error(error.message);
+        // If the error has stdout/stderr, display them
+        if (error && typeof error === "object" && "stdout" in error && error.stdout) {
+            console.error("TypeScript stdout:");
+            console.error(error.stdout);
+        }
+        if (error && typeof error === "object" && "stderr" in error && error.stderr) {
+            console.error("TypeScript stderr:");
+            console.error(error.stderr);
+        }
+        console.error("💡 Note: TypeScript compilation failed, but code generation was successful.");
+        console.error("💡 Check the errors above and fix any type issues in your source files.");
+        throw error;
+    }
+}
+/**
+ * Main build function - builds both regular and lite versions
+ */
+async function build() {
+    console.log("🚀 Starting SDK version-aware build process...");
+    try {
+        // Step 1: Get SDK version and discover spec files
+        const sdkVersion = getSdkVersion();
+        const { specs, version } = await discoverSpecFiles(sdkVersion);
+        if (!specs.openapi && !specs.asyncapi) {
+            throw new Error(`No spec files found for SDK version: ${version}`);
+        }
+        // Step 2: Ensure generated directory exists
+        await ensureGeneratedDirectory();
+        // Step 3: Generate SDK version constant (independent, can run early)
+        const sdkVersionPromise = generateSdkVersionFile(version);
+        // Step 4: Run type generation in parallel (all independent)
+        const parallelTasks = [];
+        if (specs.openapi) {
+            parallelTasks.push(generateTypes(specs.openapi));
+        }
+        if (specs.asyncapi) {
+            parallelTasks.push(generateAsyncApiTypes(specs.asyncapi));
+        }
+        // Wait for SDK version file and all parallel type generation
+        await Promise.all([sdkVersionPromise, ...parallelTasks]);
+        // Step 5: Brand types (depends on generated types)
+        brandApiTypes();
+        console.log("🎯 Building regular version with full schemas...");
+        // Step 6a: Generate full schema modules for regular build
+        generateSchemaModules(specs);
+        // Step 6b: Compile regular TypeScript (depends on all previous steps)
+        await compileTypeScript("lib");
+        console.log("🎯 Building lite version without schemas...");
+        // Step 7a: Create stub schema files for lite build
+        await createStubSchemaFiles();
+        // Step 7b: Compile lite TypeScript to separate directory
+        await compileTypeScript("lib-lite");
+        // Step 7c: Replace validation with lite version (no yaml dependency)
+        await useLiteValidation();
+        // Step 8: Clean up any temporary files
+        await cleanupTempFiles();
+        console.log(`🎉 Both regular and lite builds completed successfully for version: ${version}!`);
+        console.log(`📦 Regular build: lib/ (with validation schemas)`);
+        console.log(`📦 Lite build: lib-lite/ (without validation schemas)`);
+    }
+    catch (error) {
+        console.error("❌ Build failed:", error.message);
+        // Attempt cleanup even on failure
+        try {
+            await cleanupTempFiles();
+        }
+        catch (cleanupError) {
+            console.warn("⚠️  Could not clean up temp files after build failure");
+        }
+        process.exit(1);
+    }
+}
+// Run the build if this script is executed directly
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    build();
+}
+// Export for use in other scripts
+export { build };

package/lib-lite/scripts/enhance-types.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+declare function brandTypes(inputPath: string, outputPath: string, label?: string): void;
+export { brandTypes };

package/lib-lite/scripts/enhance-types.js

@@ -0,0 +1,174 @@
+#!/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 } from "fs";
+// 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 = [
+    // 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, outputPath, label) {
+    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();
+    // 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 = [];
+    let match;
+    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, outputPath, label = "API") {
+    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/lib-lite/scripts/generate-asyncapi-types.d.ts

@@ -0,0 +1,9 @@
+#!/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.
+ */
+declare function generateAsyncApiTypes(specPath?: string): Promise<void>;
+export { generateAsyncApiTypes };