@hyperweb/telescope 1.15.0

package/src/generators/create-react-query-bundle.ts

@@ -0,0 +1,111 @@
+import { aggregateImports, getImportStatements } from '../imports';
+import { join, dirname, extname, basename } from 'path';
+import { TelescopeBuilder } from '../builder';
+import { createScopedRpcHookFactory } from '@cosmology/ast';
+import { ProtoRef } from '@cosmology/types';
+import { TelescopeParseContext } from '../build';
+import { writeAstToFile } from '../utils/files';
+import { fixlocalpaths } from '../utils';
+import * as dotty from 'dotty';
+import { createEmptyProtoRef } from '@cosmology/proto-parser';
+import { camel, makeUseHookName, makeUsePkgHookName } from '@cosmology/utils';
+import { variableSlug } from '@cosmology/utils';
+import { swapKeyValue } from '@cosmology/utils';
+
+export const plugin = (
+    builder: TelescopeBuilder
+) => {
+    // if react query is enabled
+    // generate hooks.ts based on query hooks generated in each package.
+    // eg: __fixtures__/output1/hooks.ts
+    if (!builder.options.reactQuery.enabled) {
+        return;
+    }
+
+    const localname = 'hooks.ts';
+
+    // get mapping of packages and rpc query filenames.
+    const obj = {};
+    const instantHooksMapping = {}
+    const methodSet = new Set()
+    const bundlerFiles = builder.stateManagers["reactQuery"];
+
+    if (!bundlerFiles || !bundlerFiles.length) {
+        return;
+    }
+
+    let nameMapping = builder.options.reactQuery?.instantExport?.nameMapping;
+
+    nameMapping = swapKeyValue(nameMapping ?? {});
+
+    bundlerFiles.map(bundlerFile => {
+        const path = `./${bundlerFile.localname.replace(/\.ts$/, '')}`;
+        dotty.put(obj, bundlerFile.package, path);
+
+        // build instantHooksMapping
+        bundlerFile.instantExportedMethods?.forEach((method)=>{
+          const methodName = method.name;
+
+          const useHookName = makeUseHookName(camel(methodName));
+          const hookNameWithPkg = `${bundlerFile.package}.${useHookName}`;
+          let instantHookName = null;
+
+          if(nameMapping[hookNameWithPkg]){
+            instantHookName = nameMapping[hookNameWithPkg]
+          } else {
+            if(methodSet.has(useHookName)){
+              instantHookName = makeUsePkgHookName(bundlerFile.package, methodName);
+            } else {
+              instantHookName = useHookName
+            }
+          }
+
+          dotty.put(instantHooksMapping, instantHookName, {
+            useHookName,
+            importedVarName: variableSlug(path),
+            comment: `${bundlerFile.package}.${useHookName}\n${method.comment ?? methodName}`
+          });
+
+          methodSet.add(instantHookName);
+        });
+    });
+
+    // create proto ref for context
+    const pkg = '@root';
+    const ref: ProtoRef = createEmptyProtoRef(pkg, localname)
+
+    // create context
+    const pCtx = new TelescopeParseContext(
+        ref,
+        builder.store,
+        builder.options
+    );
+
+    // generate code for createRpcQueryHooks and imports of related packages.
+    const ast = createScopedRpcHookFactory(
+        pCtx.proto,
+        obj,
+        'createRpcQueryHooks',
+        instantHooksMapping
+    )
+
+    // generate imports added by context.addUtil
+    const imports = fixlocalpaths(aggregateImports(pCtx, {}, localname));
+    const importStmts = getImportStatements(
+        localname,
+        imports,
+        builder.options
+    );
+
+    // construct the AST
+    const prog = []
+        .concat(importStmts)
+        .concat(ast);
+
+    // write the file.
+    const filename = join(builder.outPath, localname);
+    builder.files.push(localname);
+
+    writeAstToFile(builder.outPath, builder.options, prog, filename);
+
+};

package/src/generators/create-registries.ts

@@ -0,0 +1,70 @@
+import { buildAllImports, getDepsFromMutations } from '../imports';
+import { Bundler } from '../bundler';
+import { parse } from '../parse';
+import { TelescopeBuilder } from '../builder';
+import { getExportedTypeNames } from '../utils/files';
+
+export const plugin = (
+  builder: TelescopeBuilder,
+  bundler: Bundler
+) => {
+
+  if (!builder.options.aminoEncoding?.enabled) {
+    return;
+  }
+
+  const mutationContexts = bundler
+    .contexts
+    .filter(context => context.mutations.length > 0);
+
+  // [x] write out one registry helper for all contexts w/mutations
+  const registries = mutationContexts.map(c => {
+
+    const enabled = c.amino.pluginValue('aminoEncoding.enabled');
+    if (!enabled) return;
+
+    if (c.proto.isExcluded()) return;
+
+    const localname = bundler.getLocalFilename(c.ref, 'registry');
+    const filename = bundler.getFilename(localname);
+    const ctx = bundler.getFreshContext(c);
+
+    // get mutations, services
+    parse(ctx);
+
+    ctx.buildRegistry();
+    ctx.buildRegistryLoader();
+    ctx.buildHelperObject();
+
+    const serviceImports = getDepsFromMutations(
+      ctx.mutations,
+      localname
+    );
+
+    const imports = buildAllImports(ctx, serviceImports, localname);
+    const prog = []
+      .concat(imports)
+      .concat(ctx.body);
+
+    const exportedTypeNames = getExportedTypeNames(prog);
+
+    exportedTypeNames.forEach((name) => {
+      builder.store.setTypeFilesMapping(name, localname);
+    });
+
+    bundler.addExportObjToBundle(c.ref.proto.package, localname, exportedTypeNames);
+
+    bundler.writeAst(prog, filename);
+    bundler.addToBundle(c, localname);
+
+    return {
+      package: c.ref.proto.package,
+      localname,
+      filename
+    };
+
+  }).filter(Boolean);
+
+  bundler.addRegistries(registries);
+
+};

package/src/generators/create-root-readme.ts

@@ -0,0 +1,316 @@
+import { TelescopeBuilder } from "../builder";
+import { writeContentToFile } from "../utils/files";
+import { join, basename } from "path";
+import { makeAliasNameWithPackageAtEnd } from "@cosmology/utils";
+
+/**
+ * Gets the aliased function name if it's duplicated across multiple files
+ */
+function getAliasedFunctionName(builder: TelescopeBuilder, functionName: string, packageName: string): string {
+    const duplicatedHelperFuncs = builder.store.getHelperFuncsInMultipleFiles();
+    const isDuplicated = duplicatedHelperFuncs.includes(functionName);
+
+    if (isDuplicated) {
+        const serialNumber = builder.store.getAndIncTypeSerialNumber(functionName);
+        if (serialNumber > 0) {
+            return makeAliasNameWithPackageAtEnd({ package: packageName, name: functionName });
+        }
+    }
+
+    return functionName;
+}
+
+/**
+ * Cleans up comments by removing lint directives and technical annotations
+ */
+function cleanComment(comment: string): string {
+    if (!comment) return comment;
+
+    // Remove lint directives and technical annotations
+    const cleanedComment = comment
+        // Remove buf:lint:ignore directives
+        .replace(/buf:lint:ignore\s+[A-Z_]+/gi, '')
+        // Remove other common lint directives
+        .replace(/lint:ignore[:\s]+[A-Z_]+/gi, '')
+        // Remove protolint directives
+        .replace(/protolint:disable[:\s]+[A-Z_]+/gi, '')
+        // Remove eslint directives
+        .replace(/eslint-disable[:\s-]+[a-z-]+/gi, '')
+        // Remove multiple consecutive spaces
+        .replace(/\s+/g, ' ')
+        // Remove leading/trailing whitespace
+        .trim();
+
+    return cleanedComment;
+}
+
+/**
+ * Gets the project name from the output path
+ */
+function getProjectName(outPath: string): string {
+    return basename(outPath);
+}
+
+/**
+ * Gets the appropriate import path for a function, considering bundle exports
+ */
+function getImportPath(builder: TelescopeBuilder, functionName: string, packageName: string, projectName: string, sourceFilename?: string): string {
+    const duplicatedHelperFuncs = builder.store.getHelperFuncsInMultipleFiles();
+    const isDuplicated = duplicatedHelperFuncs.includes(functionName);
+
+    // If the function is duplicated (and thus potentially aliased), it should be available in the bundle
+    if (isDuplicated) {
+        // Check the aliased function name to see if it would be different
+        const aliasedName = getAliasedFunctionName(builder, functionName, packageName);
+        if (aliasedName !== functionName) {
+            // Extract the top-level package name (e.g., 'akash' from 'akash.audit.v1beta2')
+            const topLevelPackage = packageName.split('.')[0];
+
+            // Function is aliased and should be available in bundle
+            return `${projectName}/${topLevelPackage}/bundle`;
+        }
+    }
+
+    // If we have source filename info, use the full file path
+    // This handles all functions with specific file locations
+    if (sourceFilename) {
+        // Remove .ts extension and convert to proper import path
+        const filePath = sourceFilename.replace(/\.ts$/, '');
+        return `${projectName}/${filePath}`;
+    }
+
+    // Fallback: import from the specific package path
+    return `${projectName}/${packageName.replace(/\./g, '/')}`;
+}
+
+/**
+ * Gets all types for a package by looking at export objects and filtering out extended forms
+ */
+function getTypesForPackage(builder: TelescopeBuilder, packageName: string): Array<{ name: string, sourceFile: string }> {
+    const types: Array<{ name: string, sourceFile: string }> = [];
+
+    // Get all contexts for this package
+    const packageContexts = builder.contexts.filter(ctx => ctx.ref.proto.package === packageName);
+
+    packageContexts.forEach(context => {
+        // Get types from this context
+        const contextTypes = context.types.filter(type => !type.isNested);
+
+        contextTypes.forEach(typeInfo => {
+            const typeName = typeInfo.name;
+            // Filter out extended forms (these are created during code generation but not in the types array)
+            if (!typeName.endsWith('ProtoMsg') &&
+                !typeName.endsWith('Amino') &&
+                !typeName.endsWith('AminoMsg') &&
+                !typeName.endsWith('Encoded') &&
+                !typeName.endsWith('SDKType')) {
+
+                // Get the actual source file from the store mapping
+                const typeFiles = builder.store.getTypeFilesMapping(typeName);
+                let sourceFile: string;
+
+                if (typeFiles && typeFiles.length > 0) {
+                    // Use the first (or most relevant) file where this type is defined
+                    sourceFile = typeFiles[0];
+                } else {
+                    // Fallback to context ref filename if not in mapping
+                    sourceFile = context.ref.filename.replace(/\.proto$/, '.ts');
+                }
+
+                types.push({
+                    name: typeName,
+                    sourceFile
+                });
+            }
+        });
+    });
+
+    // Remove duplicates and sort
+    const uniqueTypes = types.filter((type, index, self) =>
+        index === self.findIndex(t => t.name === type.name)
+    );
+
+    return uniqueTypes.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export const plugin = (builder: TelescopeBuilder) => {
+    if (!builder.options.readme.enabled && !builder.options.mcpServer.enabled) {
+        return;
+    }
+
+    const readmePath = join(builder.outPath, "README.md");
+    const projectName = getProjectName(builder.outPath);
+
+    // Get function mappings from builder
+    const functionMappings = builder.getFunctionMappings();
+
+    // Generate package documentation
+    let packageDocs = "";
+
+    Object.keys(functionMappings).sort().forEach(packageName => {
+        const packageServices = functionMappings[packageName];
+
+        // Check if package has any methods before adding it
+        const hasQueryMethods = packageServices.Query && Object.keys(packageServices.Query).length > 0;
+        const hasMsgMethods = packageServices.Msg && Object.keys(packageServices.Msg).length > 0;
+
+        if (!hasQueryMethods && !hasMsgMethods) {
+            return; // Skip empty packages
+        }
+
+        packageDocs += `## ${packageName}\n\n`;
+
+        // Types section
+        const types = getTypesForPackage(builder, packageName);
+        if (types && types.length > 0) {
+            packageDocs += `### Types\n\n`;
+            packageDocs += `| Type | Name | Source |\n`;
+            packageDocs += `| --- | --- | --- |\n`;
+            types.forEach(type => {
+                packageDocs += `| Type | \`${type.name}\` | [View source ↗](${type.sourceFile}) |\n`;
+            });
+            packageDocs += '\n';
+        }
+
+        // Query section
+        if (packageServices.Query) {
+            packageDocs += `### Query Methods\n\n`;
+            const queryMethods = Object.keys(packageServices.Query);
+            queryMethods.forEach((methodName, index) => {
+                const method = packageServices.Query[methodName];
+
+                // Get the aliased function name using the same logic as bundler
+                const aliasedFunctionName = getAliasedFunctionName(builder, method.functionName, packageName);
+                const aliasedHookName = getAliasedFunctionName(builder, method.hookName, packageName);
+
+                packageDocs += `**${methodName}**\n\n`;
+
+                // Add comment directly after title (if exists)
+                if (method.comment) {
+                    packageDocs += `${cleanComment(method.comment)}\n\n`;
+                }
+
+                // Add import code block
+                const functionImportPath = getImportPath(builder, method.functionName, packageName, projectName, method.sourceFilename);
+                const hookImportPath = method.hookName ? getImportPath(builder, method.hookName, packageName, projectName, method.hookSourceFilename) : functionImportPath;
+
+                packageDocs += `\`\`\`ts\n`;
+                packageDocs += `import { ${aliasedFunctionName} } from '${functionImportPath}'\n`;
+                if (method.hookName && aliasedHookName !== aliasedFunctionName) {
+                    packageDocs += `import { ${aliasedHookName} } from '${hookImportPath}'\n`;
+                }
+                packageDocs += `\`\`\`\n\n`;
+
+                // Add function details in organized format
+                packageDocs += `| Field | Value | Source |\n`;
+                packageDocs += `| --- | --- | --- |\n`;
+
+                // Function source
+                const functionSourcePath = method.sourceFilename || `${packageName.replace(/\./g, '/')}/query.rpc.func.ts`;
+                packageDocs += `| Function | \`${aliasedFunctionName}\` | [View source ↗](${functionSourcePath}) |\n`;
+
+                // Hook source (React)
+                if (method.hookName && aliasedHookName !== aliasedFunctionName) {
+                    const hookSourcePath = method.hookSourceFilename || `${packageName.replace(/\./g, '/')}/query.rpc.react.ts`;
+                    packageDocs += `| Hook | \`${aliasedHookName}\` | [View source ↗](${hookSourcePath}) |\n`;
+                }
+
+                // Request type source
+                if (method.requestType) {
+                    const requestSourcePath = method.typeSourceFilename || `${packageName.replace(/\./g, '/')}/query.ts`;
+                    packageDocs += `| Request | \`${method.requestType}\` | [View source ↗](${requestSourcePath}) |\n`;
+                }
+
+                // Response type source
+                if (method.responseType) {
+                    const responseSourcePath = method.typeSourceFilename || `${packageName.replace(/\./g, '/')}/query.ts`;
+                    packageDocs += `| Response | \`${method.responseType}\` | [View source ↗](${responseSourcePath}) |\n`;
+                }
+
+                // Add spacing between methods (but not after the last one)
+                if (index < queryMethods.length - 1) {
+                    packageDocs += '\n---\n\n';
+                } else {
+                    packageDocs += '\n';
+                }
+            });
+        }
+
+        // Transaction section
+        if (packageServices.Msg) {
+            packageDocs += `### Transaction Methods\n\n`;
+            const msgMethods = Object.keys(packageServices.Msg);
+            msgMethods.forEach((methodName, index) => {
+                const method = packageServices.Msg[methodName];
+
+                // Get the aliased function name using the same logic as bundler
+                const aliasedFunctionName = getAliasedFunctionName(builder, method.functionName, packageName);
+                const aliasedHookName = getAliasedFunctionName(builder, method.hookName, packageName);
+
+                packageDocs += `**${methodName}**\n\n`;
+
+                // Add comment directly after title (if exists)
+                if (method.comment) {
+                    packageDocs += `${cleanComment(method.comment)}\n\n`;
+                }
+
+                // Add import code block
+                const functionImportPath = getImportPath(builder, method.functionName, packageName, projectName, method.sourceFilename);
+                const hookImportPath = method.hookName ? getImportPath(builder, method.hookName, packageName, projectName, method.hookSourceFilename) : functionImportPath;
+
+                packageDocs += `\`\`\`ts\n`;
+                packageDocs += `import { ${aliasedFunctionName} } from '${functionImportPath}'\n`;
+                if (method.hookName && aliasedHookName !== aliasedFunctionName) {
+                    packageDocs += `import { ${aliasedHookName} } from '${hookImportPath}'\n`;
+                }
+                packageDocs += `\`\`\`\n\n`;
+
+                // Add function details in organized format
+                packageDocs += `| Field | Value | Source |\n`;
+                packageDocs += `| --- | --- | --- |\n`;
+
+                // Function source
+                const functionSourcePath = method.sourceFilename || `${packageName.replace(/\./g, '/')}/tx.rpc.func.ts`;
+                packageDocs += `| Function | \`${aliasedFunctionName}\` | [View source ↗](${functionSourcePath}) |\n`;
+
+                // Hook source (React)
+                if (method.hookName && aliasedHookName !== aliasedFunctionName) {
+                    const hookSourcePath = method.hookSourceFilename || `${packageName.replace(/\./g, '/')}/tx.rpc.react.ts`;
+                    packageDocs += `| Hook | \`${aliasedHookName}\` | [View source ↗](${hookSourcePath}) |\n`;
+                }
+
+                // Request type source
+                if (method.requestType) {
+                    const requestSourcePath = method.typeSourceFilename || `${packageName.replace(/\./g, '/')}/tx.ts`;
+                    packageDocs += `| Request | \`${method.requestType}\` | [View source ↗](${requestSourcePath}) |\n`;
+                }
+
+                // Response type source
+                if (method.responseType) {
+                    const responseSourcePath = method.typeSourceFilename || `${packageName.replace(/\./g, '/')}/tx.ts`;
+                    packageDocs += `| Response | \`${method.responseType}\` | [View source ↗](${responseSourcePath}) |\n`;
+                }
+
+                // Add spacing between methods (but not after the last one)
+                if (index < msgMethods.length - 1) {
+                    packageDocs += '\n---\n\n';
+                } else {
+                    packageDocs += '\n';
+                }
+            });
+        }
+
+        // Add spacing between packages
+        packageDocs += '\n';
+    });
+
+    const readmeContent = `# Package Documentation
+${packageDocs}`;
+
+    writeContentToFile(
+        builder.outPath,
+        builder.options,
+        readmeContent,
+        readmePath
+    );
+};

package/src/generators/create-rpc-msg-client-all.ts

@@ -0,0 +1,167 @@
+import * as dotty from 'dotty';
+import { createEmptyProtoRef, getNestedProto } from '@cosmology/proto-parser';
+import { join } from 'path';
+import { TelescopeBuilder } from '../builder';
+import { createScopedRpcFactory, createScopedGrpcWebMsgFactory, createRpcMsgExtension, importStmt } from '@cosmology/ast';
+import { ProtoRef } from '@cosmology/types';
+import { fixlocalpaths, getRelativePath } from '../utils';
+import { Bundler } from '../bundler';
+import { aggregateImports, getDepsFromQueries, getImportStatements } from '../imports';
+import { TelescopeParseContext } from '../build';
+import { pascal } from 'case';
+
+export const plugin = (
+    builder: TelescopeBuilder,
+    bundler: Bundler
+) => {
+    // if not enabled, exit
+    if (!builder.options?.rpcClients?.enabled) {
+        return;
+    }
+
+    if (builder.options?.rpcClients?.inline) {
+        return;
+    }
+
+    // if no scopes, do them all!
+    if (
+        !builder.options.rpcClients.scoped ||
+        !builder.options.rpcClients.scoped.length ||
+        !builder.options.rpcClients.scopedIsExclusive
+    ) {
+        return makeAllRPCBundles(
+            builder,
+            bundler
+        );
+    }
+};
+
+const getFileName = (dir, filename) => {
+    filename = filename.replace(/\.ts$/, '');
+    const localname = join(dir, filename + '.tx');
+    return localname + '.ts';
+};
+
+const makeAllRPCBundles = (
+    builder: TelescopeBuilder,
+    bundler: Bundler
+) => {
+
+    if (!builder.options.rpcClients.bundle) return;
+
+    const dir = bundler.bundle.base;
+    const filename = 'rpc';
+
+    // refs with services
+    const refs = builder.store.getProtos().filter((ref: ProtoRef) => {
+        const proto = getNestedProto(ref.traversed);
+        if (!proto?.Msg || proto.Msg?.type !== 'Service') {
+            return;
+        }
+        return true;
+    });
+
+    const check = refs.filter((ref: ProtoRef) => {
+        const [base] = ref.proto.package.split('.');
+        return base === bundler.bundle.base;
+    });
+
+    if (!check.length) {
+        // if there are no services
+        // exit the plugin
+        return;
+    }
+
+    const packages = refs.reduce((m, ref: ProtoRef) => {
+        const [base] = ref.proto.package.split('.');
+        if (base === 'cosmos' || base === bundler.bundle.base)
+            return [...new Set([...m, ref.proto.package])];
+        return m;
+    }, []);
+
+    const methodName = 'createRPCMsgClient'
+    const localname = getFileName(dir, filename ?? 'rpc');
+
+    const obj = {};
+    builder.rpcMsgClients.forEach(file => {
+
+        // ADD all option
+        // which defaults to including cosmos
+        // and defaults to base for each
+        if (!packages.includes(file.package)) {
+            return;
+        }
+
+        const f = localname;
+        const f2 = file.localname;
+        const importPath = getRelativePath(f, f2);
+        dotty.put(obj, file.package, importPath);
+    });
+
+    const ctx = new TelescopeParseContext(
+        createEmptyProtoRef(dir, localname),
+        builder.store,
+        builder.options
+    );
+
+    let rpcast;
+    let msgExt: any = [];
+    let txRpcImport: any = [];
+    switch (builder.options?.rpcClients?.type) {
+        case "grpc-gateway":
+        case "tendermint":
+            ctx.proto.addUtil('Rpc');
+
+            rpcast = createScopedRpcFactory(
+                obj,
+                methodName,
+                'MsgClientImpl', // make option later,
+                ctx.options
+            );
+
+            if (ctx.proto.pluginValue('env') === 'v-next' && ctx.proto.pluginValue('rpcClients.extensions') && ctx.proto.pluginValue('stargateClients.addGetTxRpc')) {
+                const txRpcName = 'getSigning' + pascal(bundler.bundle.base + 'TxRpc');
+
+                txRpcImport = importStmt([txRpcName], `./client${ctx.options.restoreImportExtension ?? ""}`)
+
+                msgExt = createRpcMsgExtension(ctx.proto, txRpcName);
+            }
+            break;
+        case "grpc-web":
+            ctx.proto.addUtil('grpc');
+            ctx.proto.addUtil('NodeHttpTransport');
+
+            rpcast = createScopedGrpcWebMsgFactory(
+                obj,
+                methodName,
+                'MsgClientImpl', // make option later,
+                ctx.options
+            );
+            break;
+        default:
+            break;
+    }
+
+    const serviceImports = getDepsFromQueries(
+        ctx.queries,
+        localname
+    );
+
+    const imports = aggregateImports(ctx, serviceImports, localname);
+
+    const importStmts = getImportStatements(
+        localname,
+        [...fixlocalpaths(imports)],
+        builder.options
+    );
+
+    const prog = []
+        .concat(txRpcImport)
+        .concat(importStmts)
+        .concat(rpcast)
+        .concat(msgExt);
+
+    const writeFilename = bundler.getFilename(localname);
+    bundler.writeAst(prog, writeFilename);
+    bundler.addToBundleToPackage(`${dir}.ClientFactory`, localname)
+};