@netlify/build 27.18.5-rc → 27.18.5

package/src/plugins/child/load.js

@@ -0,0 +1,29 @@
+import filterObj from 'filter-obj'
+
+import { getLogic } from './logic.js'
+import { registerTypeScript } from './typescript.js'
+import { validatePlugin } from './validate.js'
+
+// Load context passed to every plugin method.
+// This also requires the plugin file and fire its top-level function.
+// This also validates the plugin.
+// Do it when parent requests it using the `load` event.
+// Also figure out the list of plugin steps. This is also passed to the parent.
+export const load = async function ({ pluginPath, inputs, packageJson, verbose }) {
+  const tsNodeService = registerTypeScript(pluginPath)
+  const logic = await getLogic({ pluginPath, inputs, tsNodeService })
+
+  validatePlugin(logic)
+
+  const methods = filterObj(logic, isEventHandler)
+  const events = Object.keys(methods)
+
+  // Context passed to every event handler
+  const context = { methods, inputs, packageJson, verbose }
+
+  return { events, context }
+}
+
+const isEventHandler = function (event, value) {
+  return typeof value === 'function'
+}

package/src/plugins/child/logic.js

@@ -0,0 +1,65 @@
+import { createRequire } from 'module'
+import { pathToFileURL } from 'url'
+
+import { ROOT_PACKAGE_JSON } from '../../utils/json.js'
+import { DEV_EVENTS, EVENTS } from '../events.js'
+
+import { addTsErrorInfo } from './typescript.js'
+
+const require = createRequire(import.meta.url)
+
+// Require the plugin file and fire its top-level function.
+// The returned object is the `logic` which includes all event handlers.
+export const getLogic = async function ({ pluginPath, inputs, tsNodeService }) {
+  const logic = await importLogic(pluginPath, tsNodeService)
+  const logicA = loadLogic({ logic, inputs })
+  return logicA
+}
+
+const importLogic = async function (pluginPath, tsNodeService) {
+  try {
+    // `ts-node` is not available programmatically for pure ES modules yet,
+    // which is currently making it impossible for local plugins to use both
+    // pure ES modules and TypeScript.
+    if (tsNodeService !== undefined) {
+      // eslint-disable-next-line import/no-dynamic-require
+      return require(pluginPath)
+    }
+
+    // `pluginPath` is an absolute file path but `import()` needs URLs.
+    // Converting those with `pathToFileURL()` is needed especially on Windows
+    // where the drive letter would not work with `import()`.
+    const returnValue = await import(pathToFileURL(pluginPath))
+    // Plugins should use named exports, but we still support default exports
+    // for backward compatibility with CommonJS
+    return returnValue.default === undefined ? returnValue : returnValue.default
+  } catch (error) {
+    addTsErrorInfo(error, tsNodeService)
+    // We must change `error.stack` instead of `error.message` because some
+    // errors thrown from `import()` access `error.stack` before throwing.
+    // `error.stack` is lazily instantiated by Node.js, so changing
+    // `error.message` afterwards would not modify `error.stack`. Therefore, the
+    // resulting stack trace, which is printed in the build logs, would not
+    // include the additional message prefix.
+    error.stack = `Could not import plugin:\n${error.stack}`
+    throw error
+  }
+}
+
+const loadLogic = function ({ logic, inputs }) {
+  if (typeof logic !== 'function') {
+    return logic
+  }
+
+  const metadata = {
+    events: new Set([...DEV_EVENTS, ...EVENTS]),
+    version: ROOT_PACKAGE_JSON.version,
+  }
+
+  try {
+    return logic(inputs, metadata)
+  } catch (error) {
+    error.message = `Could not load plugin:\n${error.message}`
+    throw error
+  }
+}

package/src/plugins/child/main.js

@@ -0,0 +1,51 @@
+import { setInspectColors } from '../../log/colors.js'
+import { sendEventToParent, getEventsFromParent } from '../ipc.js'
+
+import { handleProcessErrors, handleError } from './error.js'
+import { load } from './load.js'
+import { run } from './run.js'
+
+// Boot plugin child process.
+const bootPlugin = async function () {
+  const state = { context: { verbose: false } }
+
+  try {
+    handleProcessErrors()
+    setInspectColors()
+
+    // We need to fire them in parallel because `process.send()` can be slow
+    // to await, i.e. parent might send `load` event before child `ready` event
+    // returns.
+    await Promise.all([handleEvents(state), sendEventToParent('ready', {}, false)])
+  } catch (error) {
+    await handleError(error, state.context.verbose)
+  }
+}
+
+// Wait for events from parent to perform plugin methods
+const handleEvents = async function (state) {
+  await getEventsFromParent((callId, eventName, payload) => handleEvent({ callId, eventName, payload, state }))
+}
+
+// Each event can pass `context` information to the next event
+const handleEvent = async function ({
+  callId,
+  eventName,
+  payload,
+  state,
+  state: {
+    context: { verbose },
+  },
+}) {
+  try {
+    const { context, ...response } = await EVENTS[eventName](payload, state.context)
+    state.context = { ...state.context, ...context }
+    await sendEventToParent(callId, response, verbose)
+  } catch (error) {
+    await handleError(error, verbose)
+  }
+}
+
+const EVENTS = { load, run }
+
+bootPlugin()

package/src/plugins/child/run.js

@@ -0,0 +1,28 @@
+import { getNewEnvChanges, setEnvChanges } from '../../env/changes.js'
+import { logPluginMethodStart, logPluginMethodEnd } from '../../log/messages/ipc.js'
+
+import { cloneNetlifyConfig, getConfigMutations } from './diff.js'
+import { getUtils } from './utils.js'
+
+// Run a specific plugin event handler
+export const run = async function (
+  { event, error, constants, envChanges, netlifyConfig },
+  { methods, inputs, packageJson, verbose },
+) {
+  const method = methods[event]
+  const runState = {}
+  const utils = getUtils({ event, constants, runState })
+  const netlifyConfigCopy = cloneNetlifyConfig(netlifyConfig)
+  const runOptions = { utils, constants, inputs, netlifyConfig: netlifyConfigCopy, packageJson, error }
+
+  const envBefore = setEnvChanges(envChanges)
+
+  logPluginMethodStart(verbose)
+  await method(runOptions)
+  logPluginMethodEnd(verbose)
+
+  const newEnvChanges = getNewEnvChanges(envBefore, netlifyConfig, netlifyConfigCopy)
+
+  const configMutations = getConfigMutations(netlifyConfig, netlifyConfigCopy, event)
+  return { ...runState, newEnvChanges, configMutations }
+}

package/src/plugins/child/status.js

@@ -0,0 +1,74 @@
+import isPlainObj from 'is-plain-obj'
+import mapObj from 'map-obj'
+
+import { addErrorInfo } from '../../error/info.js'
+
+// Report status information to the UI
+export const show = function (runState, showArgs) {
+  validateShowArgs(showArgs)
+  const { title, summary, text, extraData } = removeEmptyStrings(showArgs)
+  runState.status = { state: 'success', title, summary, text, extraData }
+}
+
+// Validate arguments of `utils.status.show()`
+const validateShowArgs = function (showArgs) {
+  try {
+    validateShowArgsObject(showArgs)
+    const { title, summary, text, extraData, ...otherArgs } = showArgs
+    validateShowArgsKeys(otherArgs)
+    Object.entries({ title, summary, text }).forEach(validateStringArg)
+    validateShowArgsSummary(summary)
+    validateShowArgsExtraData(extraData)
+  } catch (error) {
+    error.message = `utils.status.show() ${error.message}`
+    addErrorInfo(error, { type: 'pluginValidation' })
+    throw error
+  }
+}
+
+const validateShowArgsObject = function (showArgs) {
+  if (showArgs === undefined) {
+    throw new Error('requires an argument')
+  }
+
+  if (!isPlainObj(showArgs)) {
+    throw new Error('argument must be a plain object')
+  }
+}
+
+const validateShowArgsKeys = function (otherArgs) {
+  const otherKeys = Object.keys(otherArgs).map((arg) => `"${arg}"`)
+  if (otherKeys.length !== 0) {
+    throw new Error(`must only contain "title", "summary" or "text" properties, not ${otherKeys.join(', ')}`)
+  }
+}
+
+const validateStringArg = function ([key, value]) {
+  if (value !== undefined && typeof value !== 'string') {
+    throw new Error(`"${key}" property must be a string`)
+  }
+}
+
+const validateShowArgsSummary = function (summary) {
+  if (summary === undefined || summary.trim() === '') {
+    throw new Error('requires specifying a "summary" property')
+  }
+}
+
+const validateShowArgsExtraData = function (extraData) {
+  if (extraData !== undefined && Array.isArray(extraData) === false) {
+    throw new TypeError('provided extra data must be an array')
+  }
+}
+
+const removeEmptyStrings = function (showArgs) {
+  return mapObj(showArgs, removeEmptyString)
+}
+
+const removeEmptyString = function (key, value) {
+  if (typeof value === 'string' && value.trim() === '') {
+    return [key]
+  }
+
+  return [key, value]
+}

package/src/plugins/child/typescript.js

@@ -0,0 +1,45 @@
+import { extname } from 'path'
+
+import { register } from 'ts-node'
+
+import { addErrorInfo } from '../../error/info.js'
+
+// Allow local plugins to be written with TypeScript.
+// Local plugins cannot be transpiled by the build command since they can be run
+// before it. Therefore, we type-check and transpile them automatically using
+// `ts-node`.
+export const registerTypeScript = function (pluginPath) {
+  if (!isTypeScriptPlugin(pluginPath)) {
+    return
+  }
+
+  return register()
+}
+
+// On TypeScript errors, adds information about the `ts-node` configuration,
+// which includes the resolved `tsconfig.json`.
+export const addTsErrorInfo = function (error, tsNodeService) {
+  if (tsNodeService === undefined) {
+    return
+  }
+
+  const {
+    config: {
+      raw: { compilerOptions },
+    },
+    options: realTsNodeOptions,
+  } = tsNodeService
+
+  // filter out functions as they cannot be serialized
+  const tsNodeOptions = Object.fromEntries(
+    Object.entries(realTsNodeOptions).filter(([, val]) => typeof val !== 'function'),
+  )
+
+  addErrorInfo(error, { tsConfig: { compilerOptions, tsNodeOptions } })
+}
+
+const isTypeScriptPlugin = function (pluginPath) {
+  return TYPESCRIPT_EXTENSIONS.has(extname(pluginPath))
+}
+
+const TYPESCRIPT_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts'])

package/src/plugins/child/utils.js

@@ -0,0 +1,56 @@
+import { bindOpts as cacheBindOpts } from '@netlify/cache-utils'
+import { add as functionsAdd, list as functionsList, listAll as functionsListAll } from '@netlify/functions-utils'
+import { getGitUtils } from '@netlify/git-utils'
+import { run, runCommand } from '@netlify/run-utils'
+
+import { failBuild, failPlugin, cancelBuild, failPluginWithWarning } from '../error.js'
+import { isSoftFailEvent } from '../events.js'
+
+import { addLazyProp } from './lazy.js'
+import { show } from './status.js'
+
+// Retrieve the `utils` argument.
+export const getUtils = function ({
+  event,
+  constants: { FUNCTIONS_SRC, INTERNAL_FUNCTIONS_SRC, CACHE_DIR },
+  runState,
+}) {
+  // eslint-disable-next-line fp/no-mutation
+  run.command = runCommand
+
+  const build = getBuildUtils(event)
+  const cache = getCacheUtils(CACHE_DIR)
+  const functions = getFunctionsUtils(FUNCTIONS_SRC, INTERNAL_FUNCTIONS_SRC)
+  const status = getStatusUtils(runState)
+  const utils = { build, cache, run, functions, status }
+  addLazyProp(utils, 'git', () => getGitUtils())
+  return utils
+}
+
+const getBuildUtils = function (event) {
+  if (isSoftFailEvent(event)) {
+    return {
+      failPlugin,
+      failBuild: failPluginWithWarning.bind(null, 'failBuild', event),
+      cancelBuild: failPluginWithWarning.bind(null, 'cancelBuild', event),
+    }
+  }
+
+  return { failBuild, failPlugin, cancelBuild }
+}
+
+const getCacheUtils = function (CACHE_DIR) {
+  return cacheBindOpts({ cacheDir: CACHE_DIR })
+}
+
+const getFunctionsUtils = function (FUNCTIONS_SRC, INTERNAL_FUNCTIONS_SRC) {
+  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 getStatusUtils = function (runState) {
+  return { show: show.bind(undefined, runState) }
+}

package/src/plugins/child/validate.js

@@ -0,0 +1,34 @@
+import { addErrorInfo } from '../../error/info.js'
+import { serializeArray } from '../../log/serialize.js'
+import { DEV_EVENTS, EVENTS } from '../events.js'
+
+// Validate the shape of a plugin return value
+export const validatePlugin = function (logic) {
+  try {
+    // This validation must work with the return value of `import()` which has
+    // a `Module` prototype, not `Object`
+    if (typeof logic !== 'object' || logic === null) {
+      throw new Error('Plugin must be an object or a function')
+    }
+
+    Object.entries(logic).forEach(([propName, value]) => {
+      validateEventHandler(value, propName)
+    })
+  } catch (error) {
+    addErrorInfo(error, { type: 'pluginValidation' })
+    throw error
+  }
+}
+
+// All other properties are event handlers
+const validateEventHandler = function (value, propName) {
+  if (!EVENTS.includes(propName) && !DEV_EVENTS.includes(propName)) {
+    throw new Error(`Invalid event '${propName}'.
+Please use a valid event name. One of:
+${serializeArray(EVENTS)}`)
+  }
+
+  if (typeof value !== 'function') {
+    throw new TypeError(`Invalid event handler '${propName}': must be a function`)
+  }
+}

package/src/plugins/compatibility.js

@@ -0,0 +1,132 @@
+import pEvery from 'p-every'
+import pLocate from 'p-locate'
+import semver from 'semver'
+
+import { importJsonFile } from '../utils/json.js'
+import { resolvePath } from '../utils/resolve.js'
+
+// Retrieve the `expectedVersion` of a plugin:
+//  - This is the version which should be run
+//  - This takes version pinning into account
+//  - If this does not match the currently cached version, it is installed first
+// This is also used to retrieve the `compatibleVersion` of a plugin
+//  - This is the most recent version compatible with this site
+//  - This is the same logic except it does not use version pinning
+//  - This is only used to print a warning message when the `compatibleVersion`
+//    is older than the currently used version.
+export const getExpectedVersion = async function ({ versions, nodeVersion, packageJson, buildDir, pinnedVersion }) {
+  const { version, conditions } = await getCompatibleEntry({
+    versions,
+    nodeVersion,
+    packageJson,
+    buildDir,
+    pinnedVersion,
+  })
+  const compatWarning = getCompatWarning(conditions)
+  return { version, compatWarning }
+}
+
+// This function finds the right `compatibility` entry to use with the plugin.
+//  - `compatibitlity` entries are meant for backward compatibility
+//    Plugins should define each major version in `compatibility`.
+//  - The entries are sorted from most to least recent version.
+//  - After their first successful run, plugins are pinned by their major
+//    version which is passed as `pinnedVersion` to the next builds.
+// When the plugin does not have a `pinnedVersion`, we use the most recent
+// `compatibility` entry with a successful condition.
+// When the plugin has a `pinnedVersion`, we do not use the `compatibility`
+// conditions. Instead, we just use the most recent entry with a `version`
+// matching `pinnedVersion`.
+// When no `compatibility` entry matches, we use:
+//  - If there is a `pinnedVersion`, use it unless `latestVersion` matches it
+//  - Otherwise, use `latestVersion`
+const getCompatibleEntry = async function ({ versions, nodeVersion, packageJson, buildDir, pinnedVersion }) {
+  if (pinnedVersion !== undefined) {
+    const matchingVersion = versions.find(({ version }) =>
+      semver.satisfies(version, pinnedVersion, { includePrerelease: true }),
+    )
+
+    return matchingVersion || { version: pinnedVersion }
+  }
+
+  const versionsWithConditions = versions.filter(hasConditions)
+  const compatibleEntry = await pLocate(versionsWithConditions, ({ conditions }) =>
+    matchesCompatField({ conditions, nodeVersion, packageJson, buildDir }),
+  )
+  return compatibleEntry || { version: versions[0].version }
+}
+
+// Ignore entries without conditions. Those are used to specify breaking
+// changes, i.e. meant to be used for version pinning instead.
+const hasConditions = function ({ conditions }) {
+  return conditions.length !== 0
+}
+
+const matchesCompatField = async function ({ conditions, nodeVersion, packageJson, buildDir }) {
+  return await pEvery(conditions, ({ type, condition }) =>
+    CONDITIONS[type].test(condition, { nodeVersion, packageJson, buildDir }),
+  )
+}
+
+// Retrieve warning message shown when using an older version with `compatibility`
+const getCompatWarning = function (conditions = []) {
+  return conditions.map(getConditionWarning).join(', ')
+}
+
+const getConditionWarning = function ({ type, condition }) {
+  return CONDITIONS[type].warning(condition)
+}
+
+// Plugins can use `compatibility.{version}.nodeVersion: 'allowedNodeVersion'`
+// to deliver different plugin versions based on the Node.js version
+const nodeVersionTest = function (allowedNodeVersion, { nodeVersion }) {
+  return semver.satisfies(nodeVersion, allowedNodeVersion)
+}
+
+const nodeVersionWarning = function (allowedNodeVersion) {
+  return `Node.js ${allowedNodeVersion}`
+}
+
+const siteDependenciesTest = async function (
+  allowedSiteDependencies,
+  { packageJson: { devDependencies, dependencies }, buildDir },
+) {
+  const siteDependencies = { ...devDependencies, ...dependencies }
+  return await pEvery(Object.entries(allowedSiteDependencies), ([dependencyName, allowedVersion]) =>
+    siteDependencyTest({ dependencyName, allowedVersion, siteDependencies, buildDir }),
+  )
+}
+
+const siteDependencyTest = async function ({ dependencyName, allowedVersion, siteDependencies, buildDir }) {
+  const siteDependency = siteDependencies[dependencyName]
+  if (typeof siteDependency !== 'string') {
+    return false
+  }
+
+  // if this is a valid version we can apply the rule directly
+  if (semver.clean(siteDependency) !== null) {
+    return semver.satisfies(siteDependency, allowedVersion)
+  }
+
+  try {
+    // if this is a range we need to get the exact version
+    const packageJsonPath = await resolvePath(`${dependencyName}/package.json`, buildDir)
+    const { version } = await importJsonFile(packageJsonPath)
+    return semver.satisfies(version, allowedVersion)
+  } catch {
+    return false
+  }
+}
+
+const siteDependenciesWarning = function (allowedSiteDependencies) {
+  return Object.entries(allowedSiteDependencies).map(siteDependencyWarning).join(',')
+}
+
+const siteDependencyWarning = function ([dependencyName, allowedVersion]) {
+  return `${dependencyName}@${allowedVersion}`
+}
+
+export const CONDITIONS = {
+  nodeVersion: { test: nodeVersionTest, warning: nodeVersionWarning },
+  siteDependencies: { test: siteDependenciesTest, warning: siteDependenciesWarning },
+}

package/src/plugins/error.js

@@ -0,0 +1,50 @@
+import { addErrorInfo } from '../error/info.js'
+import { logFailPluginWarning } from '../log/messages/plugins.js'
+
+// Stop build.
+// As opposed to throwing an error directly or to uncaught exceptions, this is
+// displayed as a user error, not an implementation error.
+export const failBuild = function (message, opts) {
+  throw normalizeError('failBuild', failBuild, message, opts)
+}
+
+// Stop plugin. Same as `failBuild` but only stops plugin not whole build
+export const failPlugin = function (message, opts) {
+  throw normalizeError('failPlugin', failPlugin, message, opts)
+}
+
+// Cancel build. Same as `failBuild` except it marks the build as "canceled".
+export const cancelBuild = function (message, opts) {
+  throw normalizeError('cancelBuild', cancelBuild, message, opts)
+}
+
+// `onSuccess`, `onEnd` and `onError` cannot cancel the build since they are run
+// or might be run after deployment. When calling `failBuild()` or
+// `cancelBuild()`, `failPlugin()` is run instead and a warning is printed.
+export const failPluginWithWarning = function (methodName, event, message, opts) {
+  logFailPluginWarning(methodName, event)
+  failPlugin(message, opts)
+}
+
+// An `error` option can be passed to keep the original error message and
+// stack trace. An additional `message` string is always required.
+const normalizeError = function (type, func, message, { error } = {}) {
+  const errorA = getError(error, message, func)
+  addErrorInfo(errorA, { type })
+  return errorA
+}
+
+const getError = function (error, message, func) {
+  if (error instanceof Error) {
+    // This might fail if `name` is a getter or is non-writable.
+    try {
+      error.message = `${message}\n${error.message}`
+    } catch {}
+    return error
+  }
+
+  const errorA = new Error(message)
+  // Do not include function itself in the stack trace
+  Error.captureStackTrace(errorA, func)
+  return errorA
+}

package/src/plugins/events.js

@@ -0,0 +1,17 @@
+export { DEV_EVENTS, EVENTS } from '@netlify/config'
+
+const isAmongEvents = function (events, event) {
+  return events.includes(event)
+}
+
+// Check if failure of the event should not make the build fail
+export const isSoftFailEvent = isAmongEvents.bind(null, ['onSuccess', 'onError', 'onEnd'])
+
+// Check if the event is triggered even when the build fails
+export const runsAlsoOnBuildFailure = isAmongEvents.bind(null, ['onError', 'onEnd'])
+
+// Check if the event is only triggered when the build fails
+export const runsOnlyOnBuildFailure = isAmongEvents.bind(null, ['onError'])
+
+// Check if the event is happening after deploy
+export const runsAfterDeploy = isAmongEvents.bind(null, ['onSuccess', 'onEnd'])