@netlify/build 18.13.12 → 18.15.1

package/types/config/netlify_config.d.ts

@@ -0,0 +1,51 @@
+import { Many } from '../utils/many'
+
+import { Build } from './build'
+import { Functions } from './functions'
+
+type HttpStatusCode = number
+
+interface Redirect {
+  from: string
+  to: string
+  status?: HttpStatusCode
+  force: boolean
+  signed?: string
+  query: Partial<Record<string, string>>
+  headers: Partial<Record<string, string>>
+  conditions: Record<'language' | 'role' | 'country', readonly string[]>
+}
+
+interface Header {
+  for: string
+  values: Partial<Record<string, Many<string, 'mutable'>>>
+}
+
+interface EdgeHandler {
+  path?: `/${string}`
+  handler: string
+}
+
+/* eslint-disable camelcase -- some properties are named in snake case in this API */
+
+interface NetlifyConfig {
+  /**
+   * array of redirects with their modifiable options
+   */
+  redirects: Redirect[]
+  /**
+   * array of headers with their modifiable options
+   */
+  headers: Header[]
+  /**
+   * array of Edge Handlers with their modifiable options
+   */
+  edge_handlers: EdgeHandler[]
+  /**
+   * object with options for modifying [functions](https://docs.netlify.com/configure-builds/file-based-configuration/#functions)
+   */
+  functions: Functions
+  build: Build
+}
+
+/* eslint-enable camelcase */

package/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './netlify_event'
+export * from './netlify_plugin'
+export * from './netlify_plugin_options'

package/types/netlify_event.d.ts

@@ -0,0 +1,5 @@
+import { NetlifyPluginOptions } from './netlify_plugin_options'
+
+export interface NetlifyEvent<PluginOptions extends NetlifyPluginOptions = NetlifyPluginOptions> {
+  (options: PluginOptions): void | Promise<void>
+}

package/types/netlify_plugin.d.ts

@@ -0,0 +1,29 @@
+import { NetlifyEvent } from './netlify_event'
+import { NetlifyPluginOptions } from './netlify_plugin_options'
+
+export interface NetlifyPlugin {
+  /**
+   * Runs before the build command is executed.
+   */
+  onPreBuild?: NetlifyEvent
+  /**
+   * runs directly after the build command is executed and before Functions? bundling and Edge Handlers bundling.
+   */
+  onBuild?: NetlifyEvent
+  /**
+   * runs after the build command completes; after onBuild? tasks, Functions? bundling, and Edge Handlers bundling are executed; and before the deploy stage. Can be used to prevent a build from being deployed.
+   */
+  onPostBuild?: NetlifyEvent
+  /**
+   * runs when an error occurs in the build or deploy stage, failing the build. Can’t be used to prevent a build from being deployed.
+   */
+  onError?: NetlifyEvent<NetlifyPluginOptions & { error: Error }>
+  /**
+   * runs when the deploy succeeds. Can’t be used to prevent a build from being deployed.
+   */
+  onSuccess?: NetlifyEvent
+  /**
+   * runs after completion of the deploy stage, regardless of build error or success; is useful for resources cleanup. Can’t be used to prevent a build from being deployed.
+   */
+  onEnd?: NetlifyEvent<NetlifyPluginOptions & { error?: Error }>
+}

package/types/netlify_plugin_options.d.ts

@@ -0,0 +1,56 @@
+import { NetlifyConfig } from './config/netlify_config'
+import { NetlifyPluginUtils } from './options/netlify_plugin_utils'
+
+export interface NetlifyPluginOptions {
+  constants: {
+    /**
+     * path to the Netlify configuration file.
+     * `undefined` if none was used.
+     */
+    CONFIG_PATH?: string
+    /**
+     * directory that contains the deploy-ready HTML files and assets generated by the build. Its value is always defined, but the target might not have been created yet.
+     */
+    PUBLISH_DIR: string
+    /**
+     * the directory where function source code lives.
+     * `undefined` if no `netlify/functions` directory exists in the base directory and if not specified by the user.
+     */
+    FUNCTIONS_SRC?: string
+    /**
+     * the directory where built serverless functions are placed before deployment. Its value is always defined, but the target might not have been created yet.
+     */
+    FUNCTIONS_DIST: string
+    /**
+     * the directory where Edge Handlers source code lives.
+     * `undefined` if no `netlify/edge-handlers` directory exists in the base directory and if not specified in `netlify.toml`.
+     */
+    EDGE_HANDLERS_SRC?: string
+    /**
+     * boolean indicating whether the build was [run locally](https://docs.netlify.com/cli/get-started/#run-builds-locally) or on Netlify
+     */
+    IS_LOCAL: boolean
+    /**
+     * version of Netlify Build as a `major.minor.patch` string
+     */
+    NETLIFY_BUILD_VERSION: string
+    /**
+     * the Netlify site ID
+     */
+    SITE_ID: string
+  }
+  /**
+   * If your plugin requires additional values from the user, you can specify these requirements in an `inputs` array in the plugin’s [`manifest.yml` file](https://docs.netlify.com/configure-builds/build-plugins/create-plugins/#anatomy-of-a-plugin).
+   */
+  inputs: Partial<Record<string, string>>
+  /**
+   * @see https://docs.netlify.com/configure-builds/build-plugins/create-plugins/#netlifyconfig
+   */
+  netlifyConfig: NetlifyConfig
+  /**
+   * When an event handler executes, the contents of the `package.json` in a site's base directory get passed to a plugin.
+   * The data fields are normalized to prevent plugin errors. If the site has no `package.json`, the argument is an empty object.
+   */
+  packageJson: Partial<Record<string, string>>
+  utils: NetlifyPluginUtils
+}

package/types/options/index.d.ts

@@ -0,0 +1 @@
+export * from './netlify_plugin_utils'

package/types/options/netlify_plugin_build_util.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Report errors or cancel builds
+ */
+export type NetlifyPluginBuildUtil = Record<
+  'failBuild' | 'failPlugin' | 'cancelBuild',
+  (message: string, options?: { error: Error }) => void
+>

package/types/options/netlify_plugin_cache_util.d.ts

@@ -0,0 +1,39 @@
+import { Many } from '../utils/many'
+
+/**
+ * Cache files between builds
+ */
+export type NetlifyPluginCacheUtil = {
+  save(
+    path: Many<string>,
+    options?: {
+      ttl?: number
+      digests?: string[]
+      /**
+       * @default `process.cwd()`
+       */
+      cwd?: string
+    },
+  ): Promise<boolean>
+  list(options: {
+    /**
+     * @default `process.cwd()`
+     */
+    cwd?: string
+    /**
+     * @default 1
+     */
+    depth?: number
+  }): Promise<string[]>
+} & Record<
+  'restore' | 'remove' | 'has',
+  (
+    path: Many<string>,
+    options?: {
+      /**
+       * @default `process.cwd()`
+       */
+      cwd?: string
+    },
+  ) => Promise<boolean>
+>

package/types/options/netlify_plugin_git_util.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Retrieve Git-related information such as the list of modified/created/deleted files
+ * @see https://github.com/netlify/build/blob/master/packages/git-utils/README.md
+ */
+export interface NetlifyPluginGitUtil {
+  fileMatch(globPattern: string): readonly string[]
+  /**
+   * Array of all modified files.
+   */
+  modifiedFiles: readonly string[]
+  /**
+   * Array of all created files.
+   */
+  createdFiles: readonly string[]
+  /**
+   * Array of all deleted files.
+   */
+  deletedFiles: readonly string[]
+  /**
+   * Array of commits with details.
+   */
+  commits: ReadonlyArray<{
+    sha: string
+    parents: string
+    author: {
+      name: string
+      email: string
+      date: string
+    }
+    committer: {
+      name: string
+      email: string
+      date: string
+    }
+    message: string
+  }>
+  /**
+   * How many lines of code have changed
+   */
+  linesOfCode(): Promise<number>
+}

package/types/options/netlify_plugin_run_util.d.ts

@@ -0,0 +1,24 @@
+import { Options as ExecaOptions, ExecaChildProcess } from 'execa'
+
+type NetlifyPluginRunUtilOptions = Omit<ExecaOptions, 'preferLocal'> & {
+  /**
+   * @default true
+   */
+  preferLocal?: ExecaOptions['preferLocal']
+}
+
+type NetlifyPluginRunUtilResult = ExecaChildProcess
+
+/**
+ * Run commands and processes
+ * @see https://github.com/netlify/build/blob/master/packages/run-utils/README.md
+ */
+export interface NetlifyPluginRunUtil {
+  (
+    file: string,
+    // eslint-disable-next-line fp/no-arguments -- params are named `arguments` in the docs. Unrelated to JS's `arguments`
+    arguments?: readonly string[],
+    options?: NetlifyPluginRunUtilOptions,
+  ): Promise<NetlifyPluginRunUtilResult>
+  command(command: string, options?: NetlifyPluginRunUtilOptions): Promise<NetlifyPluginRunUtilResult>
+}

package/types/options/netlify_plugin_status_util.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Display information in the deploy summary
+ */
+export interface NetlifyPluginStatusUtil {
+  /**
+   * Only one status is shown per plugin.
+   * Calling `utils.status.show()` twice overrides the previous status.
+   */
+  show(options: {
+    /**
+     * Default to the plugin's name followed by a generic title.
+     */
+    title?: string
+    /**
+     * Message below the title
+     */
+    summary: string
+    /**
+     * Detailed information shown in a collapsible section.
+     * @default ""
+     */
+    text?: string
+  }): void
+}

package/types/options/netlify_plugin_utils.d.ts

@@ -0,0 +1,13 @@
+import { NetlifyPluginBuildUtil } from './netlify_plugin_build_util'
+import { NetlifyPluginCacheUtil } from './netlify_plugin_cache_util'
+import { NetlifyPluginGitUtil } from './netlify_plugin_git_util'
+import { NetlifyPluginRunUtil } from './netlify_plugin_run_util'
+import { NetlifyPluginStatusUtil } from './netlify_plugin_status_util'
+
+export interface NetlifyPluginUtils {
+  build: NetlifyPluginBuildUtil
+  status: NetlifyPluginStatusUtil
+  cache: NetlifyPluginCacheUtil
+  run: NetlifyPluginRunUtil
+  git: NetlifyPluginGitUtil
+}

package/types/utils/json_value.d.ts

@@ -0,0 +1 @@
+export type JSONValue = string | number | boolean | null | { [key: string]: JSONValue } | Array<JSONValue>

package/types/utils/many.d.ts

@@ -0,0 +1,6 @@
+type ArrayByMode<T, Mode extends 'immutable' | 'mutable' = 'immutable'> = {
+  immutable: readonly T[]
+  mutable: T[]
+}[Mode]
+
+export type Many<T, Mode extends 'immutable' | 'mutable' = 'immutable'> = T | ArrayByMode<T, Mode>

package/src/commands/get.js

@@ -1,35 +0,0 @@
-'use strict'
-
-const { EVENTS } = require('../plugins/events')
-const { buildCommandCore } = require('../plugins_core/build_command')
-const { deploySite } = require('../plugins_core/deploy')
-const { bundleFunctions } = require('../plugins_core/functions')
-
-// Get commands for all events
-const getCommands = function (commands) {
-  const commandsA = addCoreCommands(commands)
-  const commandsB = sortCommands(commandsA)
-  const events = getEvents(commandsB)
-  return { commands: commandsB, events }
-}
-
-const addCoreCommands = function (commands) {
-  return [buildCommandCore, ...commands, bundleFunctions, deploySite]
-}
-
-// Sort plugin commands by event order.
-const sortCommands = function (commands) {
-  return EVENTS.flatMap((event) => commands.filter((command) => command.event === event))
-}
-
-// Retrieve list of unique events
-const getEvents = function (commands) {
-  const events = commands.map(getEvent)
-  return [...new Set(events)]
-}
-
-const getEvent = function ({ event }) {
-  return event
-}
-
-module.exports = { getCommands }

package/src/log/messages/commands.js

@@ -1,32 +0,0 @@
-'use strict'
-
-const { getLogHeaderFunc } = require('../header_func')
-const { log, logMessage } = require('../logger')
-const { THEME } = require('../theme')
-
-const logCommand = function ({ logs, event, packageName, coreCommandDescription, index, error, netlifyConfig }) {
-  const description = getDescription({ coreCommandDescription, netlifyConfig, packageName, event })
-  const logHeaderFunc = getLogHeaderFunc(error)
-  logHeaderFunc(logs, `${index + 1}. ${description}`)
-  logMessage(logs, '')
-}
-
-const getDescription = function ({ coreCommandDescription, netlifyConfig, packageName, event }) {
-  return coreCommandDescription === undefined
-    ? `${event} command from ${packageName}`
-    : coreCommandDescription({ netlifyConfig })
-}
-
-const logBuildCommandStart = function (logs, buildCommand) {
-  log(logs, THEME.highlightWords(`$ ${buildCommand}`))
-}
-
-const logCommandSuccess = function (logs) {
-  logMessage(logs, '')
-}
-
-module.exports = {
-  logCommand,
-  logBuildCommandStart,
-  logCommandSuccess,
-}