[Expose Function Metadata] Working prototype for function metadata CLI command (#28235)

This is a rough prototype, I am very open to any suggestions.

Adds an API that can be used to expose function metadata. This is exposed in the form of a system udf. You can access the results through the CLI (`npx convex api-spec`) .

Two assumptions made in this PR are that:
- `any` is the default args validator value
- `any` is the default return validator value

We may decide that we only want to return functions that have both args and returns validators.

GitOrigin-RevId: 381916295dc8361f19bb36397da7dc5935833a66

Author: jordanhunt22

npm-packages/convex/src/cli/apiSpec.ts

@@ -0,0 +1,39 @@
+import { logOutput, oneoffContext } from "../bundler/context.js";
+import {
+  deploymentSelectionFromOptions,
+  fetchDeploymentCredentialsWithinCurrentProject,
+} from "./lib/api.js";
+import { runQuery } from "./lib/run.js";
+import { Command } from "@commander-js/extra-typings";
+import { actionDescription } from "./lib/command.js";
+
+export const apiSpec = new Command("api-spec")
+  .summary("List function metadata from your deployment")
+  .description(
+    "List argument and return values to your Convex functions.\n\n" +
+      "By default, this inspects your dev deployment.",
+  )
+  .addDeploymentSelectionOptions(
+    actionDescription("Read function metadata from"),
+  )
+  .showHelpAfterError()
+  .action(async (options) => {
+    const ctx = oneoffContext;
+    const deploymentSelection = deploymentSelectionFromOptions(options);
+
+    const { adminKey, url: deploymentUrl } =
+      await fetchDeploymentCredentialsWithinCurrentProject(
+        ctx,
+        deploymentSelection,
+      );
+
+    const functions = (await runQuery(
+      ctx,
+      deploymentUrl,
+      adminKey,
+      "_system/cli/modules:apiSpec",
+      {},
+    )) as any[];
+
+    logOutput(ctx, JSON.stringify(functions, null, 2));
+  });

npm-packages/convex/src/cli/index.ts

@@ -29,6 +29,7 @@ import { data } from "./data.js";
 import inquirer from "inquirer";
 import inquirerSearchList from "inquirer-search-list";
 import { format } from "util";
+import { apiSpec } from "./apiSpec.js";
 
 const MINIMUM_MAJOR_VERSION = 16;
 const MINIMUM_MINOR_VERSION = 15;
@@ -120,6 +121,7 @@ async function main() {
     .addCommand(update)
     .addCommand(logout)
     .addCommand(networkTest, { hidden: true })
+    .addCommand(apiSpec, { hidden: true })
     .addHelpCommand("help <command>", "Show help for given <command>")
     .version(version)
     // Hide version and help so they don't clutter

npm-packages/system-udfs/convex/_generated/api.d.ts

@@ -15,6 +15,7 @@ import type {
   FunctionReference,
 } from "convex/server";
 import type * as _system_cli_exports from "../_system/cli/exports.js";
+import type * as _system_cli_modules from "../_system/cli/modules.js";
 import type * as _system_cli_queryEnvironmentVariables from "../_system/cli/queryEnvironmentVariables.js";
 import type * as _system_cli_queryImport from "../_system/cli/queryImport.js";
 import type * as _system_cli_queryTable from "../_system/cli/queryTable.js";
@@ -69,6 +70,7 @@ import type * as tableDefs_snapshotImport from "../tableDefs/snapshotImport.js";
  */
 declare const fullApi: ApiFromModules<{
   "_system/cli/exports": typeof _system_cli_exports;
+  "_system/cli/modules": typeof _system_cli_modules;
   "_system/cli/queryEnvironmentVariables": typeof _system_cli_queryEnvironmentVariables;
   "_system/cli/queryImport": typeof _system_cli_queryImport;
   "_system/cli/queryTable": typeof _system_cli_queryTable;

npm-packages/system-udfs/convex/_system/cli/README.md

@@ -1,3 +1,3 @@
 These UDFs are not used by the dashboard, but they are used by the CLI.
 
-They get deployed with a backend push, just like the \_system/frontend ones.
+They get deployed with a funrun push, just like the \_system/frontend ones.

npm-packages/system-udfs/convex/_system/cli/modules.ts

@@ -0,0 +1,61 @@
+import { ValidatorJSON } from "../../../../convex/dist/internal-cjs-types/values";
+import { UdfType, Visibility } from "../frontend/common";
+import { queryPrivateSystem } from "../secretSystemTables";
+import { v } from "convex/values";
+
+type FunctionSpec = {
+  identifier: string;
+  function_type: UdfType;
+  visibility: Visibility;
+  args?: ValidatorJSON;
+  returns?: ValidatorJSON;
+};
+
+type HttpFunctionSpec = {
+  function_type: "HttpAction";
+  method: string;
+  path: string;
+};
+
+type FunctionSpecs = (FunctionSpec | HttpFunctionSpec)[];
+
+export const DEFAULT_ARGS_VALIDATOR = '{ "type": "any" }';
+export const DEFAULT_RETURN_VALIDATOR = '{ "type": "any" }';
+
+export const apiSpec = queryPrivateSystem({
+  args: {
+    componentId: v.optional(v.union(v.string(), v.null())),
+  },
+  handler: async ({ db }): Promise<FunctionSpecs> => {
+    const result: FunctionSpecs = [];
+    for await (const module of db.query("_modules")) {
+      const analyzeResult = module.analyzeResult;
+      if (!analyzeResult) {
+        // `Skipping ${module.path}`
+        continue;
+      }
+
+      for (const fn of analyzeResult.sourceMapped?.functions || []) {
+        result.push({
+          identifier: module.path + ":" + fn.name,
+          function_type: fn.udfType,
+          visibility: fn.visibility ?? { kind: "public" },
+          args: JSON.parse(fn.args ?? DEFAULT_ARGS_VALIDATOR),
+          returns:
+            JSON.parse(fn.returns ?? DEFAULT_RETURN_VALIDATOR) ??
+            JSON.parse(DEFAULT_RETURN_VALIDATOR),
+        });
+      }
+
+      for (const httpFn of analyzeResult.sourceMapped?.httpRoutes || []) {
+        result.push({
+          function_type: "HttpAction",
+          method: httpFn.route.method,
+          path: httpFn.route.path,
+        });
+      }
+    }
+
+    return result;
+  },
+});

npm-packages/system-udfs/convex/_system/frontend/modules.ts

@@ -7,6 +7,7 @@ import {
 } from "./common";
 import { queryPrivateSystem } from "../secretSystemTables";
 import { v } from "convex/values";
+import { DEFAULT_ARGS_VALIDATOR } from "../cli/modules";
 
 /**
  * Return all user defined modules + their functions.
@@ -73,7 +74,7 @@ function processHttpRoute(f: {
     lineno: lineno ? Number(lineno) : undefined,
     udfType: "HttpAction",
     visibility: { kind: "public" },
-    argsValidator: f.args || '{ "type": "any" }',
+    argsValidator: f.args || DEFAULT_ARGS_VALIDATOR,
   } as const;
 }
 
@@ -90,6 +91,6 @@ function processFunction(f: {
     ...f,
     lineno: lineno ? Number(lineno) : undefined,
     visibility: f.visibility ?? { kind: "public" },
-    argsValidator: f.args || '{ "type": "any" }',
+    argsValidator: f.args || DEFAULT_ARGS_VALIDATOR,
   };
 }

npm-packages/system-udfs/convex/schema.ts

@@ -46,6 +46,8 @@ const analyzedFunction = v.object({
   pos: v.optional(analyzedSourcePosition),
   udfType,
   visibility: v.optional(v.union(v.null(), udfVisibility)),
+  args: v.optional(v.string()),
+  returns: v.union(v.string(), v.null()),
 });
 
 const analyzedHttpRoute = v.object({