feat: add functions.generate util (#6487)

* feat: support return values from plugin steps

* feat: log generated functions

* feat: log generated functions

* chore: add test

* refactor: add `functions.generate` util

* chore: add debug log

* chore: fix Windows test

* refactor: simplify `generate` util

Author: eduardoboucas

packages/build/src/log/messages/core_steps.js

@@ -67,20 +67,40 @@ export const logFunctionsToBundle = function ({
   internalFunctions,
   internalFunctionsSrc,
   frameworkFunctions,
+  generatedFunctions,
   type = 'Functions',
 }) {
+  let needsSpace = false
+
+  if (generatedFunctions.length !== 0) {
+    for (const id in generatedFunctions) {
+      const { displayName, generatorType, functionNames } = generatedFunctions[id]
+
+      if (needsSpace) log(logs, '')
+
+      log(logs, `Packaging ${type} generated by ${THEME.highlightWords(displayName)} ${generatorType}:`)
+      logArray(logs, functionNames, { indent: false })
+
+      needsSpace = true
+    }
+  }
+
   if (internalFunctions.length !== 0) {
+    if (needsSpace) log(logs, '')
+
     log(logs, `Packaging ${type} from ${THEME.highlightWords(internalFunctionsSrc)} directory:`)
     logArray(logs, internalFunctions, { indent: false })
+
+    needsSpace = true
   }
 
   if (frameworkFunctions.length !== 0) {
-    if (internalFunctions.length !== 0) {
-      log(logs, '')
-    }
+    if (needsSpace) log(logs, '')
 
     log(logs, `Packaging ${type} generated by your framework:`)
     logArray(logs, frameworkFunctions, { indent: false })
+
+    needsSpace = true
   }
 
   if (!userFunctionsSrcExists) {
@@ -93,9 +113,7 @@ export const logFunctionsToBundle = function ({
     return
   }
 
-  if (internalFunctions.length !== 0 || frameworkFunctions.length !== 0) {
-    log(logs, '')
-  }
+  if (needsSpace) log(logs, '')
 
   log(logs, `Packaging ${type} from ${THEME.highlightWords(userFunctionsSrc)} directory:`)
   logArray(logs, userFunctions, { indent: false })

packages/build/src/plugins/child/run.js

@@ -19,8 +19,9 @@ export const run = async function (
   return context.with(getGlobalContext(), async () => {
     const method = methods[event]
     const runState = {}
+    const generatedFunctions = []
     const systemLog = getSystemLog()
-    const utils = getUtils({ event, constants, runState })
+    const utils = getUtils({ event, constants, generatedFunctions, runState })
     const netlifyConfigCopy = cloneNetlifyConfig(netlifyConfig)
     const runOptions = {
       utils,
@@ -43,6 +44,7 @@ export const run = async function (
     const newEnvChanges = getNewEnvChanges(envBefore, netlifyConfig, netlifyConfigCopy)
 
     const configMutations = getConfigMutations(netlifyConfig, netlifyConfigCopy, event)
-    return { ...runState, newEnvChanges, configMutations }
+    const returnValue = generatedFunctions.length ? { generatedFunctions } : undefined
+    return { ...runState, newEnvChanges, configMutations, returnValue }
   })
 }

packages/build/src/plugins/child/utils.js

@@ -13,13 +13,14 @@ import { show } from './status.js'
 export const getUtils = function ({
   event,
   constants: { FUNCTIONS_SRC, INTERNAL_FUNCTIONS_SRC, CACHE_DIR },
+  generatedFunctions = [],
   runState,
 }) {
   run.command = runCommand
 
   const build = getBuildUtils(event)
   const cache = getCacheUtils(CACHE_DIR)
-  const functions = getFunctionsUtils(FUNCTIONS_SRC, INTERNAL_FUNCTIONS_SRC)
+  const functions = getFunctionsUtils(FUNCTIONS_SRC, INTERNAL_FUNCTIONS_SRC, generatedFunctions)
   const status = getStatusUtils(runState)
   const utils = { build, cache, run, functions, status }
   addLazyProp(utils, 'git', () => getGitUtils())
@@ -42,12 +43,15 @@ const getCacheUtils = function (CACHE_DIR) {
   return cacheBindOpts({ cacheDir: CACHE_DIR })
 }
 
-const getFunctionsUtils = function (FUNCTIONS_SRC, INTERNAL_FUNCTIONS_SRC) {
+const getFunctionsUtils = function (FUNCTIONS_SRC, INTERNAL_FUNCTIONS_SRC, generatedFunctions) {
   const functionsDirectories = [INTERNAL_FUNCTIONS_SRC, FUNCTIONS_SRC].filter(Boolean)
   const add = (src) => functionsAdd(src, INTERNAL_FUNCTIONS_SRC, { fail: failBuild })
   const list = functionsList.bind(null, functionsDirectories, { fail: failBuild })
   const listAll = functionsListAll.bind(null, functionsDirectories, { fail: failBuild })
-  return { add, list, listAll }
+  const generate = (functionPath) => generatedFunctions.push({ path: functionPath })
+
+  /** @type import('../../types/options/netlify_plugin_functions_util.js').NetlifyPluginFunctionsUtil */
+  return { add, list, listAll, generate }
 }
 
 const getStatusUtils = function (runState) {

packages/build/src/plugins_core/edge_functions/index.ts

@@ -206,6 +206,7 @@ const logFunctions = async ({
     internalFunctionsSrc: internalSrcDirectory,
     frameworkFunctions: frameworkFunctions.map(({ name }) => name),
     type: 'Edge Functions',
+    generatedFunctions: [],
   })
 }
 

packages/build/src/plugins_core/functions/index.ts

@@ -1,10 +1,11 @@
-import { resolve } from 'path'
+import { basename, resolve } from 'path'
 
 import { type NodeBundlerName, RUNTIME, zipFunctions, type FunctionResult } from '@netlify/zip-it-and-ship-it'
 import { pathExists } from 'path-exists'
 
 import { addErrorInfo } from '../../error/info.js'
 import { log } from '../../log/logger.js'
+import type { ReturnValue } from '../../types/step.js'
 import { logBundleResults, logFunctionsNonExistingDir, logFunctionsToBundle } from '../../log/messages/core_steps.js'
 import { FRAMEWORKS_API_FUNCTIONS_ENDPOINT } from '../../utils/frameworks_api.js'
 
@@ -68,6 +69,7 @@ const zipFunctionsAndLogResults = async ({
   functionsConfig,
   functionsDist,
   functionsSrc,
+  generatedFunctions,
   frameworkFunctionsSrc,
   internalFunctionsSrc,
   isRunningLocally,
@@ -94,7 +96,9 @@ const zipFunctionsAndLogResults = async ({
     // Printing an empty line before bundling output.
     log(logs, '')
 
-    const sourceDirectories = [internalFunctionsSrc, frameworkFunctionsSrc, functionsSrc].filter(Boolean)
+    const sourceDirectories = [internalFunctionsSrc, frameworkFunctionsSrc, functionsSrc, ...generatedFunctions].filter(
+      Boolean,
+    )
     const results = await zipItAndShipIt.zipFunctions(sourceDirectories, functionsDist, zisiParameters)
 
     validateCustomRoutes(results)
@@ -128,6 +132,7 @@ const coreStep = async function ({
   repositoryRoot,
   userNodeVersion,
   systemLog,
+  returnValues,
 }) {
   const functionsSrc = relativeFunctionsSrc === undefined ? undefined : resolve(buildDir, relativeFunctionsSrc)
   const functionsDist = resolve(buildDir, relativeFunctionsDist)
@@ -154,6 +159,8 @@ const coreStep = async function ({
     }
   }
 
+  const generatedFunctions = getGeneratedFunctionPaths(returnValues)
+
   logFunctionsToBundle({
     logs,
     userFunctions,
@@ -162,9 +169,15 @@ const coreStep = async function ({
     internalFunctions,
     internalFunctionsSrc: relativeInternalFunctionsSrc,
     frameworkFunctions,
+    generatedFunctions: getGeneratedFunctionsByGenerator(returnValues),
   })
 
-  if (userFunctions.length === 0 && internalFunctions.length === 0 && frameworkFunctions.length === 0) {
+  if (
+    userFunctions.length === 0 &&
+    internalFunctions.length === 0 &&
+    frameworkFunctions.length === 0 &&
+    generatedFunctions.length === 0
+  ) {
     return {}
   }
 
@@ -183,6 +196,7 @@ const coreStep = async function ({
     repositoryRoot,
     userNodeVersion,
     systemLog,
+    generatedFunctions,
   })
 
   const metrics = getMetrics(internalFunctions, userFunctions)
@@ -203,6 +217,7 @@ const hasFunctionsDirectories = async function ({
   buildDir,
   constants: { INTERNAL_FUNCTIONS_SRC, FUNCTIONS_SRC },
   packagePath,
+  returnValues,
 }) {
   const hasFunctionsSrc = FUNCTIONS_SRC !== undefined && FUNCTIONS_SRC !== ''
 
@@ -218,7 +233,49 @@ const hasFunctionsDirectories = async function ({
 
   const frameworkFunctionsSrc = resolve(buildDir, packagePath || '', FRAMEWORKS_API_FUNCTIONS_ENDPOINT)
 
-  return await pathExists(frameworkFunctionsSrc)
+  if (await pathExists(frameworkFunctionsSrc)) {
+    return true
+  }
+
+  // We must run the core step if the return value of any of the previous steps
+  // has declared generated functions.
+  for (const id in returnValues) {
+    if (returnValues[id].generatedFunctions && returnValues[id].generatedFunctions.length !== 0) {
+      return true
+    }
+  }
+
+  return false
+}
+
+// Takes a list of return values and produces an array with the paths of all
+// generated functions.
+const getGeneratedFunctionPaths = (returnValues: Record<string, ReturnValue>) => {
+  return Object.values(returnValues).flatMap(
+    (returnValue) => returnValue.generatedFunctions?.map((func) => func.path) || [],
+  )
+}
+
+// Takes a list of return values and produces an object with the names of the
+// generated functions for each generator. This is used for printing logs only.
+const getGeneratedFunctionsByGenerator = (returnValues: Record<string, ReturnValue>) => {
+  const result: Record<string, { displayName: string; generatorType: string; functionNames: string[] }> = {}
+
+  for (const id in returnValues) {
+    const { displayName, generatedFunctions, generatorType } = returnValues[id]
+
+    if (!generatedFunctions || generatedFunctions.length === 0) {
+      continue
+    }
+
+    result[id] = {
+      displayName,
+      generatorType,
+      functionNames: generatedFunctions.map((func) => basename(func.path)),
+    }
+  }
+
+  return result
 }
 
 export const bundleFunctions = {

packages/build/src/steps/core_step.ts

@@ -42,6 +42,7 @@ export const fireCoreStep = async function ({
   deployId,
   outputFlusher,
   api,
+  returnValues,
 }) {
   const logsA = outputFlusher ? addOutputFlusher(logs, outputFlusher) : logs
 
@@ -83,6 +84,7 @@ export const fireCoreStep = async function ({
       enhancedSecretScan,
       edgeFunctionsBootstrapURL,
       deployId,
+      returnValues,
     })
     const {
       netlifyConfig: netlifyConfigA,

packages/build/src/steps/plugin.js

@@ -54,6 +54,7 @@ export const firePluginStep = async function ({
     const {
       newEnvChanges,
       configMutations: newConfigMutations,
+      returnValue,
       status,
     } = await callChild({
       childProcess,
@@ -100,6 +101,7 @@ export const firePluginStep = async function ({
       headersPath: headersPathA,
       redirectsPath: redirectsPathA,
       newStatus,
+      returnValue,
     }
   } catch (newError) {
     const errorType = getPluginErrorType(newError, loadedFrom, packageName)

packages/build/src/steps/return.js

@@ -29,6 +29,7 @@ export const getStepReturn = function ({
   systemLog,
   quiet,
   metrics,
+  returnValue,
 }) {
   if (newError !== undefined) {
     return handleStepError({
@@ -51,5 +52,15 @@ export const getStepReturn = function ({
     logTimer(logs, durationNs, timerName, systemLog, outputFlusher)
   }
 
-  return { newEnvChanges, netlifyConfig, configMutations, headersPath, redirectsPath, newStatus, timers, metrics }
+  return {
+    newEnvChanges,
+    netlifyConfig,
+    configMutations,
+    headersPath,
+    redirectsPath,
+    newStatus,
+    timers,
+    metrics,
+    returnValue,
+  }
 }

packages/build/src/steps/run_step.ts

@@ -71,6 +71,7 @@ export const runStep = async function ({
   enhancedSecretScan,
   edgeFunctionsBootstrapURL,
   extensionMetadata,
+  returnValues,
 }) {
   // Add relevant attributes to the upcoming span context
   const attributes: StepExecutionAttributes = {
@@ -111,6 +112,7 @@ export const runStep = async function ({
       explicitSecretKeys,
       enhancedSecretScan,
       deployId,
+      returnValues,
       featureFlags,
     })
     span.setAttribute('build.execution.step.should_run', shouldRun)
@@ -140,6 +142,7 @@ export const runStep = async function ({
       timers: timersA,
       durationNs,
       metrics,
+      returnValue,
     } = await fireStep({
       extensionMetadata,
       defaultConfig,
@@ -188,6 +191,7 @@ export const runStep = async function ({
       edgeFunctionsBootstrapURL,
       deployId,
       api,
+      returnValues,
     })
 
     const newValues = await getStepReturn({
@@ -216,6 +220,7 @@ export const runStep = async function ({
       systemLog,
       quiet: quiet || coreStepQuiet,
       metrics,
+      returnValue,
     })
 
     span.end()
@@ -269,6 +274,7 @@ const shouldRunStep = async function ({
   explicitSecretKeys,
   enhancedSecretScan,
   deployId,
+  returnValues,
   featureFlags = {},
 }) {
   if (
@@ -284,6 +290,7 @@ const shouldRunStep = async function ({
         explicitSecretKeys,
         enhancedSecretScan,
         deployId,
+        returnValues,
         featureFlags,
       })))
   ) {
@@ -354,6 +361,7 @@ const tFireStep = function ({
   deployId,
   extensionMetadata,
   api,
+  returnValues,
 }) {
   if (coreStep !== undefined) {
     return fireCoreStep({
@@ -393,6 +401,7 @@ const tFireStep = function ({
       edgeFunctionsBootstrapURL,
       deployId,
       api,
+      returnValues,
     })
   }