@netlify/build 0.5.0 → 1.0.0-dl-test

package/types/netlify_plugin.d.ts

@@ -0,0 +1,29 @@
+import { PluginInputs } from './config/inputs'
+import { OnBuild, OnEnd, OnError, OnPostBuild, OnPreBuild, OnSuccess } from './netlify_event_handler'
+
+export interface NetlifyPlugin<TInputs extends PluginInputs = PluginInputs> {
+  /**
+   * Runs before the build command is executed.
+   */
+  onPreBuild?: OnPreBuild<TInputs>
+  /**
+   * runs directly after the build command is executed and before Functions? bundling and Edge Handlers bundling.
+   */
+  onBuild?: OnBuild<TInputs>
+  /**
+   * 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?: OnPostBuild<TInputs>
+  /**
+   * 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?: OnError<TInputs>
+  /**
+   * runs when the deploy succeeds. Can’t be used to prevent a build from being deployed.
+   */
+  onSuccess?: OnSuccess<TInputs>
+  /**
+   * 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?: OnEnd<TInputs>
+}

package/types/netlify_plugin_constants.d.ts

@@ -0,0 +1,51 @@
+export interface NetlifyPluginConstants {
+  /**
+   * 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 internal Edge Functions source code lives. This is where build plugins should place auto-generated functions.
+   * `undefined` if the version of @netlify/build does not support internal Edge Functions
+   */
+  INTERNAL_EDGE_FUNCTIONS_SRC?: string
+  /**
+   * the directory where internal function source code lives. This is where build plugins should place auto-generated functions.
+   * `undefined` if the version of @netlify/build does not support internal functions
+   */
+  INTERNAL_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 built Edge Functions are placed before deployment. Its value is always defined, but the target might not have been created yet.
+   */
+  EDGE_FUNCTIONS_DIST: string
+  /**
+   * the directory where Edge Functions source code lives.
+   * `undefined` if no `netlify/edge-functions` directory exists.
+   */
+  EDGE_FUNCTIONS_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
+}

package/types/netlify_plugin_options.d.ts

@@ -0,0 +1,23 @@
+import { PluginInputs, StringKeys } from './config/inputs'
+import { NetlifyConfig } from './config/netlify_config'
+import { NetlifyPluginConstants } from './netlify_plugin_constants'
+import { NetlifyPluginUtils } from './options/netlify_plugin_utils'
+import { JSONValue } from './utils/json_value'
+
+export interface NetlifyPluginOptions<TInputs extends PluginInputs<StringKeys<TInputs>> = PluginInputs> {
+  /**
+   * 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: TInputs
+  /**
+   * @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, JSONValue>>
+  constants: NetlifyPluginConstants
+  utils: NetlifyPluginUtils
+}

package/types/options/index.d.ts

@@ -0,0 +1 @@
+export { NetlifyPluginUtils } 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 }) => never
+>

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_functions_util.d.ts

@@ -0,0 +1,32 @@
+import type { listFunctions, listFunctionsFiles } from '@netlify/zip-it-and-ship-it'
+
+type Resolved<T> = T extends Promise<infer U> ? U : T
+
+export type ListedFunction = Resolved<ReturnType<typeof listFunctions>>[0]
+export type ListedFunctionFile = Resolved<ReturnType<typeof listFunctionsFiles>>[0]
+
+export interface NetlifyPluginFunctionsUtil {
+  /**
+   * Returns the list of Netlify Functions main files as a Promise resolving to an array of objects with the following properties:
+   *
+   * - `name`: Function name, as used in the URL `https://{hostname}/.netlify/functions/{name}`
+   * - `mainFile`: absolute path to the Function's main file
+   * - `extension`: file extension of the Function's main file. For Go Functions, this might be an empty string.  For Node.js Functions, this is either `.js` or `.zip`.
+   * - `runtime` `"js" | "go"`: Function's language runtime. TypeScript Functions use the "js" runtime
+   */
+  list(): Promise<Array<ListedFunction>>
+
+  /**
+   * Same as `list()` except it also returns the files required by the Functions' main files. This is much slower. The object have the following additional member:
+   *
+   * - `srcFile`: absolute path to the file
+   */
+  listAll(): Promise<Array<ListedFunctionFile>>
+
+  /**
+   * Add a Functions file or directory to a build.
+   *
+   * @param path Path to the function file or directory.
+   */
+  add(path: string): Promise<void>
+}

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,15 @@
+import { NetlifyPluginBuildUtil } from './netlify_plugin_build_util'
+import { NetlifyPluginCacheUtil } from './netlify_plugin_cache_util'
+import { NetlifyPluginFunctionsUtil } from './netlify_plugin_functions_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
+  functions: NetlifyPluginFunctionsUtil
+}

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/README.md

@@ -1,3 +0,0 @@
-# Netlify Build
-
-Coming soon

package/src/core/bin.js

@@ -1,139 +0,0 @@
-#!/usr/bin/env node
-const { exit } = require('process')
-
-const filterObj = require('filter-obj')
-const yargs = require('yargs')
-
-require('../utils/polyfills')
-
-const build = require('./main')
-
-// CLI entry point
-const runCli = async function() {
-  const flags = parseFlags()
-  const { features, ...flagsA } = filterObj(flags, isUserFlag)
-
-  if (features) {
-    return printFeatures()
-  }
-
-  const success = await build(flagsA)
-  const exitCode = success ? 0 : 1
-  exit(exitCode)
-}
-
-const parseFlags = function() {
-  return yargs
-    .options(FLAGS)
-    .usage(USAGE)
-    .parse()
-}
-
-const FLAGS = {
-  config: {
-    string: true,
-    describe: `Path to the configuration file.
-Defaults to any netlify.toml in the git repository root directory or the base directory`,
-  },
-  defaultConfig: {
-    string: true,
-    describe: `JSON configuration object containing default values.
-Each configuration default value is used unless overriden through the main configuration file.
-Default: none.`,
-    hidden: true,
-  },
-  cachedConfig: {
-    string: true,
-    describe: `JSON configuration object returned by @netlify/config.
-This is done as a performance optimization to cache the configuration loading logic.
-Default: none.`,
-    hidden: true,
-  },
-  cwd: {
-    string: true,
-    describe: `Current directory. Used to retrieve the configuration file.
-Default: current directory`,
-  },
-  repositoryRoot: {
-    string: true,
-    describe: `Git repository root directory. Used to retrieve the configuration file.
-Default: automatically guessed`,
-  },
-  token: {
-    string: true,
-    describe: `Netlify API token for authentication.
-The NETLIFY_AUTH_TOKEN environment variable can be used as well.`,
-  },
-  siteId: {
-    string: true,
-    describe: `Netlify Site ID.`,
-  },
-  context: {
-    string: true,
-    describe: `Build context.
-Default: 'production'`,
-  },
-  branch: {
-    string: true,
-    describe: `Repository branch.
-Default: automatically guessed`,
-  },
-  baseRelDir: {
-    boolean: true,
-    describe: `Feature flag meant for backward compatibility.
-When enabled, if the 'build.base' configuration property is defined, it is used
-to try to retrieve a second configuration file and discard the first one.
-Default: true`,
-    hidden: true,
-  },
-  dry: {
-    alias: 'dry-run',
-    boolean: true,
-    describe: `Run in dry mode, i.e. printing commands without
-executing them.
-Default: false`,
-  },
-  nodePath: {
-    string: true,
-    describe: `Path to the Node.js binary to use in user commands and build plugins.
-Default: Current Node.js binary`,
-  },
-  features: {
-    boolean: true,
-    describe: `Print currently enabled feature flags.
-Default: false`,
-  },
-  mode: {
-    string: true,
-    describe: `Environment in which this is loaded. Can be:
-  - 'buildbot': within Netlify Buildbot
-  - 'cli': within Netlify CLI
-  - 'require': through require('@netlify/build')`,
-    hidden: true,
-  },
-}
-
-const USAGE = `netlify-build [OPTIONS...]
-
-Run Netlify Build system locally.
-
-Options can also be specified as environment variables prefixed with
-NETLIFY_BUILD_. For example the environment variable NETLIFY_BUILD_DRY=true can
-be used instead of the CLI flag --dry.`
-
-// Remove `yargs`-specific options, shortcuts, dash-cased and aliases
-const isUserFlag = function(key, value) {
-  return value !== undefined && !INTERNAL_KEYS.includes(key) && key.length !== 1 && !key.includes('-')
-}
-
-const INTERNAL_KEYS = ['help', 'version', '_', '$0', 'dryRun']
-
-const printFeatures = function() {
-  console.log(['', ...FEATURES, ''].join(FEATURES_DELIMITER))
-  exit(0)
-}
-
-const FEATURES = ['cachesave']
-const FEATURES_DELIMITER = '_'
-
-runCli()