@xpack/xpm-lib 3.1.2 → 4.0.0

package/src/classes/build-configurations.ts

@@ -0,0 +1,2127 @@
+/*
+ * This file is part of the xPack project (http://xpack.github.io).
+ * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software
+ * for any purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can
+ * be obtained from https://opensource.org/license/mit.
+ */
+
+// ----------------------------------------------------------------------------
+
+import assert from 'node:assert'
+import * as path from 'node:path'
+import * as os from 'node:os'
+
+import { Logger } from '@xpack/logger'
+
+// ----------------------------------------------------------------------------
+
+import { LiquidEngine } from './liquid-engine.js'
+import {
+  LiquidSubstitutionsVariables,
+  LiquidSubstitutionsStrings,
+} from '../data/substitutions-variables.js'
+import { filterPath } from '../functions/filter-paths.js'
+import { isJsonObject, isString } from '../functions/is-something.js'
+import { getErrorMessage, hasLiquidSyntax } from '../functions/utils.js'
+import { performSubstitutions } from '../functions/perform-substitutions.js'
+import {
+  JsonBuildConfigurations,
+  JsonBuildConfigurationTemplate,
+  JsonBuildConfiguration,
+  JsonBuildConfigurationContent,
+  JsonDependencies,
+  JsonBuildConfigurationInherits,
+} from '../types/json.js'
+import { Actions, Action } from './actions.js'
+import { buildFolderRelativePathPropertyName } from './data-model.js'
+import { ConfigurationError } from './errors.js'
+import { TemplateExpander } from './template-expander.js'
+
+// ============================================================================
+
+/**
+ * Configuration parameters for constructing a build configurations collection.
+ *
+ * @remarks
+ * This interface defines the required configuration for creating an
+ * instance of {@link BuildConfigurations}. Most properties are mandatory
+ * except for the optional <code>jsonBuildConfigurations</code>, which can
+ * be undefined if there are no build configurations defined in the package.
+ *
+ * The parameters provide the collection with access to the Liquid templating
+ * engine, substitution variables hierarchy, build configuration definitions
+ * from the package manifest, and the logger for diagnostic output during
+ * configuration processing.
+ */
+export interface BuildConfigurationsConstructorParameters {
+  /**
+   * The Liquid templating engine for variable substitution.
+   */
+  engine: LiquidEngine
+
+  /**
+   * The variables available for substitution in configuration definitions.
+   */
+  substitutionsVariables: LiquidSubstitutionsVariables
+
+  /**
+   * The JSON build configurations definitions, or undefined if no build
+   * configurations are defined.
+   */
+  jsonBuildConfigurations: JsonBuildConfigurations | undefined
+
+  /**
+   * The logger instance for output and diagnostics.
+   */
+  log: Logger
+}
+
+/**
+ * A collection of <b>xpm</b> build configurations.
+ *
+ * @remarks
+ * This class manages build configurations defined in package metadata,
+ * including template expansion with matrix parameters and initialisation of
+ * derived configuration instances.
+ *
+ * Configuration lifecycle phases:
+ *
+ * <ol>
+ * <li><b>Construction:</b> Basic setup without processing configurations.</li>
+ * <li><b>Initialisation:</b> Template name expansion without content
+ *    evaluation.</li>
+ * <li><b>Retrieval:</b> On-demand instantiation when accessed via
+ *    <code>get()</code>.</li>
+ * <li><b>Configuration Initialisation:</b> Full processing including
+ *    inheritance, property resolution, dependency substitution, and
+ *    action preparation.</li>
+ * </ol>
+ *
+ * This lazy evaluation strategy ensures that only configurations actually
+ * used incur the cost of template evaluation, inheritance resolution, and
+ * variable substitution.
+ */
+export class BuildConfigurations {
+  // --------------------------------------------------------------------------
+  // Public Members.
+
+  /**
+   * The logger instance for output and diagnostics.
+   *
+   * @remarks
+   * This logger provides trace-level diagnostics throughout the build
+   * configuration lifecycle, including template expansion, inheritance
+   * resolution, property merging, and dependency substitution. It enables
+   * detailed debugging of complex build configuration hierarchies without
+   * impacting runtime performance when tracing is disabled.
+   */
+  readonly log: Logger
+
+  /**
+   * The Liquid templating engine for variable substitution.
+   *
+   * @remarks
+   * This engine instance is shared across all build configurations and
+   * configured with custom filters for platform detection, path
+   * manipulation, and xpm-specific operations. It processes templates in
+   * configuration names, matrix parameters, properties, dependencies, and
+   * actions, ensuring consistent template evaluation throughout the
+   * configuration lifecycle.
+   */
+  readonly engine: LiquidEngine
+
+  /**
+   * The variables available for substitution in configuration definitions.
+   *
+   * @remarks
+   * This comprehensive variable hierarchy provides the base context for all
+   * build configuration template evaluation, extended per-configuration with
+   * specific properties, dependencies, and matrix parameters.
+   *
+   * Base hierarchy includes:
+   *
+   * <ol>
+   * <li><b>Environment variables:</b> <code>env</code> namespace with system
+   *    environment.</li>
+   * <li><b>Platform detection:</b> <code>os</code> namespace with
+   *    platform-specific values.</li>
+   * <li><b>Path utilities:</b> <code>path</code> namespace with path
+   *    manipulationfunctions.</li>
+   * <li><b>Package metadata:</b> <code>package</code> namespace with
+   *    name, version, dependencies.</li>
+   * </ol>
+   *
+   * Individual configurations extend this with their own `properties`,
+   * `configuration`, and `matrix` namespaces during initialisation.
+   */
+  readonly substitutionsVariables: LiquidSubstitutionsVariables
+
+  /**
+   * The JSON object containing build configuration definitions.
+   *
+   * @remarks
+   * This object holds raw build configuration definitions from the
+   * `package.json` `xpack.buildConfigurations` section. Configurations can be:
+   *
+   * <ol>
+   * <li><b>Regular configurations:</b> Direct objects with properties,
+   *    dependencies, actions, and inheritance.</li>
+   * <li><b>Template configurations:</b> Objects with <code>matrix</code>
+   *    and <code>template</code>
+   *    properties for generating multiple configurations from a single
+   *    definition.</li>
+   * </ol>
+   *
+   * Template configuration names (containing `{{` markers) trigger matrix
+   * expansion during initialisation, creating concrete configurations from
+   * the Cartesian product of matrix parameter values. Each configuration
+   * can inherit from others, creating complex dependency hierarchies.
+   */
+  readonly jsonBuildConfigurations: JsonBuildConfigurations
+
+  // --------------------------------------------------------------------------
+  // Protected Members.
+
+  /**
+   * Map of build configuration names to their corresponding instances.
+   *
+   * @remarks
+   * This map serves as the primary configuration registry, populated during
+   * collection initialisation with entries for all discovered configurations.
+   *
+   * Key characteristics:
+   *
+   * <ol>
+   * <li>Known only after <code>BuildConfigurations.initialise()</code>
+   *    completes.</li>
+   * <li>Possibly empty if there are no build configurations defined.</li>
+   * <li>Values can be <code>undefined</code> to indicate a configuration
+   *    exists but hasn't been instantiated yet (lazy loading).</li>
+   * <li>For template configurations, contains one entry per expanded
+   *    combination, not the original template definition.</li>
+   * </ol>
+   *
+   * Configurations transition from `undefined` to instantiated when first
+   * accessed via {@link BuildConfigurations.get}, implementing the
+   * lazy evaluation pattern to avoid unnecessary processing.
+   */
+  protected readonly _buildConfigurationsMap: Map<
+    string,
+    BuildConfiguration | undefined
+  > = new Map<string, BuildConfiguration | undefined>()
+
+  /**
+   * Map of expanded build configuration names to their JSON source names.
+   *
+   * @remarks
+   * This reverse mapping enables retrieving the original configuration
+   * definition from `jsonBuildConfigurations` when lazy-loading
+   * configuration instances.
+   *
+   * Mapping behavior:
+   *
+   * <ol>
+   * <li><b>For regular configurations:</b> Maps configuration name to itself
+   *    (identity mapping).</li>
+   * <li><b>For template configurations:</b> Maps each generated configuration
+   *    name
+   *    back to the original template name (e.g., <code>release-x64</code> →
+   *    <code>release-\{\{ matrix.arch \}\}</code>).</li>
+   * <li>Known only after <code>BuildConfigurations.initialise()</code>
+   *    completes.</li>
+   * <li>Enables <code>BuildConfigurations.get()</code> to locate the
+   *    correct JSON definition when instantiating a configuration on
+   *    demand.</li>
+   * </ol>
+   *
+   * This indirection is essential for lazy evaluation, allowing deferred
+   * instantiation while maintaining the connection to original definitions.
+   */
+  protected readonly _jsonBuildConfigurationsNamesMap: Map<string, string> =
+    new Map<string, string>()
+
+  /**
+   * Set of all build configuration names for duplicate detection.
+   *
+   * @remarks
+   * This set provides O(1) existence checks for configuration names,
+   * enabling efficient validation during template expansion to prevent
+   * duplicate configurations.
+   *
+   * Duplicate scenarios detected:
+   *
+   * <ol>
+   * <li>Explicit duplicates in <code>package.json</code> with identical
+   *    names.</li>
+   * <li>Template expansion conflicts where different templates generate the
+   *    same concrete configuration name.</li>
+   * <li>Conflicts between template-generated names and explicitly defined
+   *    configuration names.</li>
+   * </ol>
+   *
+   * Detection occurs during {@link BuildConfigurations.initialise},
+   * throwing {@link ConfigurationError} when duplicates are found to ensure
+   * configuration name uniqueness.
+   */
+  protected readonly _namesSet: Set<string> = new Set<string>()
+
+  /**
+   * Flag indicating whether the collection has been initialised.
+   *
+   * @remarks
+   * This flag prevents redundant initialisation and ensures idempotent
+   * behavior when {@link BuildConfigurations.initialise} is called
+   * multiple times.
+   *
+   * State transitions:
+   *
+   * <ol>
+   * <li>Initially <code>false</code> after construction.</li>
+   * <li>Set to <code>true</code> after successful template expansion
+   *    and configuration
+   *    name registration.</li>
+   * <li>Checked at the beginning of
+   *    <code>BuildConfigurations.initialise()</code> to return early if
+   *    already initialised.</li>
+   * </ol>
+   *
+   * This pattern supports safe repeated calls during complex initialisation
+   * sequences without duplicating work or corrupting internal state.
+   */
+  protected _isInitialised = false
+
+  /**
+   * Cached array of all build configuration names in the collection.
+   *
+   * @remarks
+   * This array provides O(1) access to configuration names without
+   * repeatedly creating new arrays from the map keys, improving performance
+   * when the names are accessed multiple times.
+   *
+   * Key characteristics:
+   *
+   * <ol>
+   * <li>Empty initially after construction.</li>
+   * <li>Populated during
+   *    <code>BuildConfigurations.initialise()</code> after all
+   *    configuration names are determined.</li>
+   * <li>Contains all configuration names including those generated from
+   *    templates.</li>
+   * <li>Returned by the <code>names</code> getter for efficient repeated
+   *    access.</li>
+   * </ol>
+   *
+   * This cached approach avoids the overhead of calling
+   * `Array.from(map.keys())` on every access whilst still
+   * providing a clean getter interface.
+   */
+  protected _names: string[] = []
+
+  // --------------------------------------------------------------------------
+  // Constructor and async initialiser.
+
+  /**
+   * Constructs a build configurations collection.
+   *
+   * @remarks
+   * The constructor performs partial initialisation. Complete
+   * initialisation requires calling
+   * {@link BuildConfigurations.initialise}.
+   *
+   * @param engine - The Liquid templating engine for variable substitution.
+   * @param substitutionsVariables - The variables available for substitution.
+   * @param jsonBuildConfigurations - The JSON build configurations definitions,
+   * or undefined if no build configurations are defined.
+   * @param log - The logger instance for output and diagnostics.
+   */
+  constructor({
+    engine,
+    substitutionsVariables,
+    jsonBuildConfigurations,
+    log,
+  }: BuildConfigurationsConstructorParameters) {
+    assert(log, 'log is required')
+    assert(engine, 'engine is required')
+    assert(substitutionsVariables, 'substitutionsVariables is required')
+
+    log.trace(`${BuildConfigurations.name}()`)
+
+    this.log = log
+    this.engine = engine
+    this.substitutionsVariables = substitutionsVariables
+    this.jsonBuildConfigurations = jsonBuildConfigurations ?? {}
+
+    // log.trace('substitutionsVariables => ', this.substitutionsVariables)
+  }
+
+  /**
+   * Completes the async initialisation of the build configurations collection.
+   *
+   * @remarks
+   * This method implements the first step of lazy evaluation. It processes
+   * all build configuration definitions by expanding template configuration
+   * names based on matrix parameters, but does not evaluate the configuration
+   * content or perform Liquid substitutions. The actual template evaluation
+   * and variable substitution occur later when individual configurations are
+   * initialised via {@link BuildConfiguration.initialise}, and only
+   * for configurations that are actually used. This approach avoids unnecessary
+   * operations on unused configurations.
+   *
+   * Processing steps:
+   *
+   * <ol>
+   * <li>Return early if already initialised (idempotent behaviour).</li>
+   * <li>Iterate through all build configuration definitions from the JSON
+   *    object.</li>
+   * <li>For template configurations (names containing <code>\{\{</code>):
+   *   <ul>
+   *   <li>Call <code>_processTemplate()</code> to expand and register all
+   *      generated configurations.</li>
+   *   </ul>
+   * </li>
+   * <li>For regular configurations:
+   *   <ul>
+   *   <li>Validate uniqueness of the configuration name.</li>
+   *   <li>Register the configuration in internal maps with
+   *      <code>undefined</code> value (lazy loading).</li>
+   *   </ul>
+   * </li>
+   * <li>Cache the array of all configuration names for efficient repeated
+   *    access.</li>
+   * </ol>
+   *
+   * @returns A promise that resolves to `true` if initialisation was performed,
+   * or `false` if already initialised.
+   *
+   * @throws {@link ConfigurationError}
+   * If duplicate names are detected or template expansion fails.
+   */
+  async initialise(): Promise<boolean> {
+    const log = this.log
+
+    if (this._isInitialised) {
+      log.trace(`${BuildConfigurations.name}.initialise() again`)
+      return false
+    }
+
+    log.trace(`${BuildConfigurations.name}.initialise()`)
+
+    for (const [
+      buildConfigurationName,
+      jsonBuildConfiguration,
+    ] of Object.entries(this.jsonBuildConfigurations)) {
+      if (hasLiquidSyntax(buildConfigurationName)) {
+        await this._processTemplate({
+          buildConfigurationName,
+          jsonBuildConfigurationTemplate:
+            jsonBuildConfiguration as JsonBuildConfigurationTemplate,
+        })
+      } else {
+        if (this._namesSet.has(buildConfigurationName)) {
+          throw new ConfigurationError(
+            `build configuration name ` +
+              `"${buildConfigurationName}" already defined`
+          )
+        } else {
+          this._buildConfigurationsMap.set(buildConfigurationName, undefined)
+          this._jsonBuildConfigurationsNamesMap.set(
+            buildConfigurationName,
+            buildConfigurationName
+          )
+          this._namesSet.add(buildConfigurationName)
+        }
+      }
+    }
+
+    const names = Array.from(this._buildConfigurationsMap.keys())
+    this._names = names
+
+    log.trace(`${BuildConfigurations.name}.initialise() =>`, names)
+
+    this._isInitialised = true
+    return true
+  }
+
+  // --------------------------------------------------------------------------
+  // Public Methods.
+
+  /**
+   * The number of build configurations in the collection.
+   *
+   * @remarks
+   * This value is known only after `initialise()`.
+   *
+   * This getter provides direct access to the collection size, enabling
+   * callers to check for emptiness or iterate with knowledge of the
+   * collection's extent.
+   *
+   * @returns The number of build configurations in the collection.
+   */
+  get size(): number {
+    assert(
+      this._isInitialised,
+      'BuildConfigurations collection must be initialised before ' +
+        'accessing size'
+    )
+
+    return this._buildConfigurationsMap.size
+  }
+
+  /**
+   * Indicates whether the collection is empty.
+   *
+   * @remarks
+   * This value is known only after `initialise()`.
+   *
+   * @returns `true` if there are no build configurations, `false` otherwise.
+   */
+  get isEmpty(): boolean {
+    assert(
+      this._isInitialised,
+      'BuildConfigurations collection must be initialised before ' +
+        'accessing isEmpty'
+    )
+
+    return this._buildConfigurationsMap.size === 0
+  }
+
+  /**
+   * The names of all build configurations.
+   *
+   * @remarks
+   * This value is known only after `initialise()`.
+   *
+   * This getter returns the cached array of configuration names for
+   * efficient repeated access without recreating the array.
+   *
+   * @returns An array of build configuration names.
+   */
+  get names(): string[] {
+    assert(
+      this._isInitialised,
+      'BuildConfigurations collection must be initialised before ' +
+        'accessing names'
+    )
+
+    return this._names
+  }
+
+  /**
+   * Retrieves the JSON configuration name for a build configuration.
+   *
+   * @param buildConfigurationName - The build configuration name to resolve.
+   * @returns The JSON configuration name associated with the given build
+   * configuration name.
+   *
+   * @remarks
+   * For template-generated configurations, this returns the template
+   * name.
+   *
+   * @throws {@link InputError}
+   * If the build configuration does not exist.
+   */
+  getJsonName(buildConfigurationName: string): string {
+    assert(
+      this._isInitialised,
+      'BuildConfigurations collection must be initialised before ' +
+        'accessing getJsonName()'
+    )
+
+    const name = this._jsonBuildConfigurationsNamesMap.get(
+      buildConfigurationName
+    )
+    if (name === undefined) {
+      throw new ConfigurationError(
+        `build configuration "${buildConfigurationName}" does not exist`
+      )
+    }
+
+    return name
+  }
+
+  /**
+   * Determines whether a JSON definition exists for a build configuration.
+   *
+   * @param buildConfigurationName - The build configuration name to check.
+   * @returns `true` if a JSON definition exists, `false` otherwise.
+   */
+  hasJson(buildConfigurationName: string): boolean {
+    assert(
+      this._isInitialised,
+      'BuildConfigurations collection must be initialised before ' +
+        'accessing hasJson()'
+    )
+
+    return this._jsonBuildConfigurationsNamesMap.has(buildConfigurationName)
+  }
+
+  /**
+   * Retrieves the JSON build configuration definition.
+   *
+   * @param buildConfigurationName - The build configuration name to resolve.
+   * @returns The JSON build configuration definition.
+   */
+  getJson(buildConfigurationName: string): JsonBuildConfiguration {
+    assert(
+      this._isInitialised,
+      'BuildConfigurations collection must be initialised before ' +
+        'accessing getJson()'
+    )
+
+    return this.jsonBuildConfigurations[
+      this.getJsonName(buildConfigurationName)
+    ]
+  }
+
+  /**
+   * Determines whether a build configuration is hidden.
+   *
+   * @param buildConfigurationName - The build configuration name to check.
+   * @returns `true` if the configuration is hidden, `false` otherwise.
+   */
+  isHidden(buildConfigurationName: string): boolean {
+    assert(
+      this._isInitialised,
+      'BuildConfigurations collection must be initialised before ' +
+        'accessing isHidden()'
+    )
+
+    const jsonBuildConfigurationName = this.getJsonName(buildConfigurationName)
+    if (jsonBuildConfigurationName.includes('{{')) {
+      const jsonBuildConfigurationTemplate: JsonBuildConfigurationTemplate =
+        this.jsonBuildConfigurations[
+          jsonBuildConfigurationName
+        ] as JsonBuildConfigurationTemplate
+      return jsonBuildConfigurationTemplate.template.hidden ?? false
+    }
+
+    const jsonBuildConfigurationContent: JsonBuildConfigurationContent = this
+      .jsonBuildConfigurations[
+      jsonBuildConfigurationName
+    ] as JsonBuildConfigurationContent
+    return jsonBuildConfigurationContent.hidden ?? false
+  }
+
+  /**
+   * Determines whether a build configuration exists in the collection.
+   *
+   * @param buildConfigurationName - The build configuration name to check.
+   * @returns `true` if the configuration exists, `false` otherwise.
+   */
+  has(buildConfigurationName: string): boolean {
+    assert(
+      this._isInitialised,
+      'BuildConfigurations collection must be initialised before ' +
+        'accessing has()'
+    )
+
+    return this._buildConfigurationsMap.has(buildConfigurationName)
+  }
+
+  /**
+   * Retrieves a build configuration by name, creating it if required.
+   *
+   * @remarks
+   * This method implements lazy evaluation to avoid unnecessary
+   * operations. Build configurations are instantiated on demand but
+   * remain uninitialised until actually used.
+   *
+   * Retrieval process:
+   *
+   * <ol>
+   * <li>Check if the configuration already exists in the internal map.</li>
+   * <li>If found and already instantiated, return the existing instance.</li>
+   * <li>If the configuration name is unknown (not in JSON name mapping),
+   *    throw <code>InputError</code>.</li>
+   * <li>For known but not yet instantiated configurations:
+   *   <ul>
+   *   <li>Resolve the original JSON configuration name (handles both
+   *      regular and template-generated configurations).</li>
+   *   <li>Retrieve the JSON configuration definition.</li>
+   *   <li>Create a new <code>BuildConfiguration</code> instance.</li>
+   *   <li>Store the instance in the map for future access.</li>
+   *   </ul>
+   * </li>
+   * <li>Return the configuration instance (still uninitialised).</li>
+   * </ol>
+   *
+   * The two-step lazy evaluation process:
+   *
+   * <ol>
+   * <li>During collection initialisation
+   *    (<code>BuildConfigurations.initialise()</code>), only the
+   *    matrix of options is evaluated for each template, expanding
+   *    configuration names without processing their content.</li>
+   * <li>Later, when a configuration is accessed via this method and
+   *    subsequently initialised
+   *    (<code>BuildConfiguration.initialise()</code>), the template
+   *    is fully evaluated and Liquid substitutions are performed on
+   *    all properties.</li>
+   * </ol>
+   *
+   * This approach ensures that only build configurations that are
+   * actually used incur the cost of template evaluation and variable
+   * substitution.
+   *
+   * @param buildConfigurationName - The build configuration name to retrieve.
+   * @returns The build configuration instance.
+   *
+   * @throws {@link InputError}
+   * If a configuration with the specified name does not exist.
+   */
+  get(buildConfigurationName: string): BuildConfiguration {
+    assert(
+      this._isInitialised,
+      'BuildConfigurations collection must be initialised before ' +
+        'accessing get()'
+    )
+
+    const log = this.log
+    log.trace(`${BuildConfigurations.name}.get(${buildConfigurationName})`)
+
+    let buildConfiguration = this._buildConfigurationsMap.get(
+      buildConfigurationName
+    )
+    if (buildConfiguration === undefined) {
+      // This will throw InputError if the configuration doesn't exist
+      const jsonBuildConfigurationName: string = this.getJsonName(
+        buildConfigurationName
+      )
+
+      // Safety net: This fallback to empty object is defensive programming.
+      // The jsonBuildConfigurations[jsonBuildConfigurationName] should always
+      // be defined because getJsonName() throws if the configuration doesn't
+      // exist. The ?? {} provides protection against unexpected inconsistencies
+      // between the names map and the configurations object.
+      /* c8 ignore start - safety net, they are always defined */
+      const jsonBuildConfiguration: JsonBuildConfigurationContent = (this
+        .jsonBuildConfigurations[jsonBuildConfigurationName] ??
+        {}) as JsonBuildConfigurationContent
+      /* c8 ignore stop */
+
+      buildConfiguration = new BuildConfiguration({
+        buildConfigurationName,
+        jsonBuildConfiguration,
+        parentBuildConfigurations: this,
+      })
+      this._buildConfigurationsMap.set(
+        buildConfigurationName,
+        buildConfiguration
+      )
+    }
+
+    // await buildConfiguration.initialise()
+    return buildConfiguration
+  }
+
+  // --------------------------------------------------------------------------
+  // Private Methods.
+
+  /**
+   * Processes a template build configuration by expanding it and registering
+   * the generated configurations.
+   *
+   * @remarks
+   * This helper method is called during collection initialisation for each
+   * build configuration whose name contains template syntax
+   * (<code>\{\{</code> markers).
+   *
+   * Processing steps:
+   *
+   * <ol>
+   * <li>Calls <code>_expandTemplateBuildConfigurations()</code> to generate
+   *    all configuration instances from the template's matrix parameters.</li>
+   * <li>Validates that each expanded configuration name is unique and does
+   *    not conflict with existing configurations.</li>
+   * <li>Registers each expanded configuration in the internal maps:
+   *   <ul>
+   *   <li><code>_buildConfigurationsMap</code>: Maps name to configuration
+   *      instance.</li>
+   *   <li><code>_jsonBuildConfigurationsNamesMap</code>: Maps expanded name
+   *      back to original template name.</li>
+   *   <li><code>_namesSet</code>: Tracks all registered
+   *      names for duplicate detection.</li>
+   *   </ul>
+   * </li>
+   * </ol>
+   *
+   * @param buildConfigurationName - The template configuration name
+   * containing Liquid variables.
+   * @param jsonBuildConfiguration - The JSON template definition containing
+   * matrix parameters and a configuration template.
+   * @returns A promise that resolves when processing is complete.
+   *
+   * @throws {@link ConfigurationError}
+   * If duplicate configuration names are detected during expansion or if
+   * template expansion fails.
+   */
+  protected async _processTemplate({
+    buildConfigurationName,
+    jsonBuildConfigurationTemplate,
+  }: {
+    buildConfigurationName: string
+    jsonBuildConfigurationTemplate: JsonBuildConfigurationTemplate
+  }): Promise<void> {
+    // Expand templates and generate multiple build configurations.
+    try {
+      const expandedBuildConfigurationsMap =
+        await this._expandTemplateBuildConfigurations({
+          buildConfigurationName,
+          jsonBuildConfigurationTemplate,
+        })
+      for (const [
+        expandedBuildConfigurationName,
+        expandedBuildConfiguration,
+      ] of expandedBuildConfigurationsMap) {
+        if (this._namesSet.has(expandedBuildConfigurationName)) {
+          throw new ConfigurationError(
+            `duplicate build configuration name ` +
+              `"${expandedBuildConfigurationName}" ` +
+              `could not be generated from template.`
+          )
+        } else {
+          this._buildConfigurationsMap.set(
+            expandedBuildConfigurationName,
+            expandedBuildConfiguration
+          )
+          this._jsonBuildConfigurationsNamesMap.set(
+            expandedBuildConfigurationName,
+            buildConfigurationName
+          )
+          this._namesSet.add(expandedBuildConfigurationName)
+        }
+      }
+    } catch (error) {
+      const message =
+        getErrorMessage(error) +
+        ` in buildConfiguration "${buildConfigurationName}"`
+      throw new ConfigurationError(message)
+    }
+  }
+
+  /**
+   * Expands a template build configuration into multiple configurations.
+   *
+   * @remarks
+   * This method uses the {@link TemplateExpander} to compute the Cartesian
+   * product of matrix parameter values and creates a configuration for each
+   * combination, substituting matrix values into both the configuration name
+   * and content.
+   *
+   * Processing steps:
+   *
+   * <ol>
+   * <li>Validates matrix and template structure.</li>
+   * <li>Delegates to <code>TemplateExpander</code> for matrix processing and
+   *    name expansion.</li>
+   * <li>Creates configuration instances via factory callback for each
+   *    combination.</li>
+   * </ol>
+   *
+   * Matrix variables are scoped to individual configurations and accessible
+   * via the `matrix` namespace during property, dependency, and action
+   * evaluation.
+   *
+   * @param buildConfigurationName - The template configuration name containing
+   * Liquid variables.
+   * @param jsonBuildConfigurationTemplate - The template definition containing
+   * matrix parameters and a configuration template.
+   * @returns A promise that resolves to a map of expanded configuration names
+   * to their corresponding instances.
+   *
+   * @throws {@link ConfigurationError}
+   * If the matrix structure is invalid or substitution fails.
+   */
+  protected async _expandTemplateBuildConfigurations({
+    buildConfigurationName,
+    jsonBuildConfigurationTemplate,
+  }: {
+    buildConfigurationName: string
+    jsonBuildConfigurationTemplate: JsonBuildConfigurationTemplate
+  }): Promise<Map<string, BuildConfiguration>> {
+    const log = this.log
+    log.trace(
+      `${BuildConfigurations.name}.` +
+        `#expandTemplateBuildConfigurations(${buildConfigurationName})`
+    )
+
+    // Validate template structure
+    if (!isJsonObject(jsonBuildConfigurationTemplate.matrix)) {
+      throw new ConfigurationError(
+        `buildConfiguration "${buildConfigurationName}" ` +
+          `matrix is not an object`
+      )
+    }
+    if (!isJsonObject(jsonBuildConfigurationTemplate.template)) {
+      throw new ConfigurationError(
+        `buildConfiguration "${buildConfigurationName}" ` +
+          `template is not a JSON object`
+      )
+    }
+
+    // Use TemplateExpander for matrix processing and expansion
+    const expander = new TemplateExpander<
+      JsonBuildConfigurationContent,
+      BuildConfiguration
+    >({
+      engine: this.engine,
+      substitutionsVariables: this.substitutionsVariables,
+      log: this.log,
+    })
+
+    return await expander.expandTemplate({
+      templateName: buildConfigurationName,
+      matrix: jsonBuildConfigurationTemplate.matrix,
+      templateContent: jsonBuildConfigurationTemplate.template,
+      templateType: 'buildConfiguration',
+      instanceFactory: (
+        expandedName: string,
+        combination: Record<string, string>,
+        templateContent: JsonBuildConfigurationContent,
+        originalTemplateName: string
+      ) =>
+        new BuildConfiguration({
+          buildConfigurationName: expandedName,
+          templateBuildConfigurationName: originalTemplateName,
+          jsonBuildConfiguration: templateContent,
+          parentBuildConfigurations: this,
+          matrixParameters: { ...combination },
+        }),
+    })
+  }
+}
+
+// ============================================================================
+
+/**
+ * Configuration parameters for constructing a build configuration instance.
+ *
+ * @remarks
+ * This interface defines the required configuration for creating an
+ * instance of {@link BuildConfiguration}. Most properties are mandatory
+ * except for the optional <code>templateBuildConfigurationName</code> and
+ * <code>matrixParameters</code>, which are only needed for template-generated
+ * configurations created from matrix expansion.
+ *
+ * The parameters provide the configuration with its identity (name,
+ * optional template name), the JSON configuration definition, access to
+ * the parent collection for shared resources, and optional matrix parameter
+ * values for template-generated configurations.
+ */
+export interface BuildConfigurationConstructorParameters {
+  /**
+   * The configuration name after substitution.
+   */
+  buildConfigurationName: string
+
+  /**
+   * The template configuration name, if derived from a template.
+   */
+  templateBuildConfigurationName?: string
+
+  /**
+   * The JSON configuration definition.
+   */
+  jsonBuildConfiguration: JsonBuildConfigurationContent
+
+  /**
+   * The parent configurations collection.
+   */
+  parentBuildConfigurations: BuildConfigurations
+
+  /**
+   * Optional matrix parameter values for template-generated configurations.
+   */
+  matrixParameters?: LiquidSubstitutionsStrings
+}
+
+/**
+ * An individual <b>xpm</b> build configuration.
+ *
+ * @remarks
+ * Build configurations are initialised lazily and may inherit
+ * properties, dependencies, and actions from other configurations.
+ *
+ * A configuration can exist in three states:
+ *
+ * <ol>
+ * <li><b>Undefined:</b> Name is known but instance not yet created.</li>
+ * <li><b>Instantiated:</b> Object exists but not yet fully processed.</li>
+ * <li><b>Initialised:</b> Inheritance resolved, properties evaluated,
+ *    dependencies substituted, and actions prepared.</li>
+ * </ol>
+ *
+ * Inheritance is processed recursively with circular reference detection.
+ * Later inherited properties override earlier ones, and local properties
+ * override all inherited ones. Dependencies and actions are merged from
+ * all inherited configurations.
+ */
+export class BuildConfiguration {
+  // --------------------------------------------------------------------------
+  // Public Members.
+
+  /**
+   * The build configuration name after substitution.
+   *
+   * @remarks
+   * This is the final, expanded configuration name used for identification
+   * and selection. For template-generated configurations, this is the
+   * concrete name after matrix substitution (e.g., `release-x64` rather than
+   * `release-{{ matrix.arch }}`).
+   *
+   * The name is used for:
+   *
+   * <ol>
+   * <li>User-facing identification when listing or selecting
+   *   configurations.</li>
+   * <li><b>Build folder path generation (default:</b>
+   *   <code>build/\{name\}</code>).</li>
+   * <li>Logging and diagnostic output to track configuration lifecycle.</li>
+   * <li>Inheritance references from other configurations.</li>
+   * </ol>
+   *
+   * Names must be unique within the configurations collection, enforced
+   * during {@link BuildConfigurations.initialise}.
+   */
+  readonly name: string
+
+  /**
+   * The template build configuration name, if derived from a template.
+   *
+   * @remarks
+   * For template-generated configurations, this preserves the original
+   * template name containing Liquid variables (e.g.,
+   * `release-{{ matrix.arch }}`), while `buildConfigurationName` holds the
+   * expanded concrete name.
+   *
+   * Usage:
+   *
+   * <ol>
+   * <li>Undefined for regular (non-template) configurations.</li>
+   * <li>Set to the template name for configurations generated from matrix
+   *    expansion.</li>
+   * <li>Used to determine whether full JSON substitution is needed during
+   *    initialisation (templates require complete substitution, regular
+   *    configurations only substitute specific fields).</li>
+   * <li>Enables tracing and debugging of template expansion process.</li>
+   * </ol>
+   */
+  readonly templateName?: string
+
+  /**
+   * The parent build configurations collection.
+   *
+   * @remarks
+   * This reference maintains the hierarchical relationship between
+   * individual configurations and their containing collection, providing
+   * essential context for configuration initialisation.
+   *
+   * The parent collection provides access to:
+   *
+   * <ol>
+   * <li>Liquid templating engine for variable substitution.</li>
+   * <li>Base substitution variables hierarchy (package metadata,
+   *    environment, platform detection).</li>
+   * <li>Logger instance for diagnostic output.</li>
+   * <li>JSON build configurations lookup for inheritance resolution.</li>
+   * <li>Other configuration instances when processing inheritance chains.</li>
+   * </ol>
+   *
+   * This design enables configurations to access shared resources without
+   * duplicating them, while supporting complex inheritance relationships
+   * where configurations reference and inherit from each other.
+   */
+  readonly parentBuildConfigurations: BuildConfigurations
+
+  /**
+   * The list of inherited configuration names.
+   *
+   * @remarks
+   * This array specifies the inheritance chain for this configuration,
+   * processed sequentially during initialisation with later entries
+   * overriding earlier ones.
+   *
+   * Inheritance processing:
+   *
+   * <ol>
+   * <li>Populated from <code>inherits</code> or deprecated
+   *    <code>inherit</code> field during
+   *    initialisation.</li>
+   * <li>Supports both string (single parent) and array (multiple parents)
+   *    formats.</li>
+   * <li>Each inherited configuration is initialised recursively before
+   *    merging its properties, dependencies, and actions.</li>
+   * <li>Circular references are detected and rejected with
+   *    <code>InputError</code>.</li>
+   * <li>Later inherited configurations override properties from earlier
+   *    ones, and local properties override all inherited ones.</li>
+   * </ol>
+   */
+  inheritsNames: string[] = []
+
+  /**
+   * Indicates whether the configuration is hidden.
+   *
+   * @remarks
+   * Hidden configurations are used for inheritance bases or intermediate
+   * configurations that shouldn't be directly selected for building.
+   *
+   * Effects of hidden status:
+   *
+   * <ol>
+   * <li>Hidden configurations don't compute build folder relative paths
+   *    during initialisation (optimization for inheritance-only configs).</li>
+   * <li>May be excluded from user-facing configuration lists depending on
+   *    application logic.</li>
+   * <li>Still fully initialised and available for inheritance by other
+   *    configurations.</li>
+   * <li>Derived from <code>hidden</code> field in JSON configuration definition
+   *    (defaults to <code>false</code>).</li>
+   * </ol>
+   *
+   * Common use case:
+   *
+   * Base configurations that define common properties,
+   * dependencies, or actions inherited by multiple concrete configurations.
+   */
+  readonly isHidden: boolean
+
+  /**
+   * The resolved properties for this configuration.
+   *
+   * @remarks
+   * This object contains the final merged properties after inheritance
+   * resolution and becomes available in the `properties` namespace for
+   * Liquid template substitution.
+   *
+   * Property resolution order:
+   *
+   * <ol>
+   * <li>Start with empty object.</li>
+   * <li>Merge properties from each inherited configuration in sequence
+   *    (later overrides earlier).</li>
+   * <li>Merge local properties from JSON definition (overrides all
+   *    inherited).</li>
+   * <li>Add computed <code>buildFolderRelativePath</code> property
+   *    for non-hidden
+   *    configurations.</li>
+   * </ol>
+   *
+   * Properties are accessible in templates as `{{ properties.key }}` and
+   * commonly used for compiler flags, toolchain paths, optimization
+   * settings, and build-specific configuration values.
+   */
+  properties: LiquidSubstitutionsStrings = {}
+
+  /**
+   * The resolved dependencies after substitutions.
+   *
+   * @remarks
+   * This object contains the final merged dependencies after inheritance
+   * resolution and Liquid template substitution.
+   *
+   * Dependency resolution workflow:
+   *
+   * <ol>
+   * <li>Start with empty object.</li>
+   * <li>Merge <code>dependencies</code> from each inherited configuration
+   *    in sequence
+   *    (later overrides earlier).</li>
+   * <li>Merge local <code>dependencies</code> from JSON definition.</li>
+   * <li>Perform Liquid template substitution on the entire
+   *    <code>dependencies</code>
+   *    object with full configuration context (properties, matrix, etc.).</li>
+   * </ol>
+   *
+   * This enables configuration-specific dependencies with dynamic version
+   * ranges or package selection based on matrix parameters, platform
+   * detection, or configuration properties.
+   */
+  dependencies: JsonDependencies = {}
+
+  /**
+   * The resolved development dependencies after substitutions.
+   *
+   * @remarks
+   * This object contains the final merged development dependencies after
+   * inheritance resolution and Liquid template substitution.
+   *
+   * Resolution workflow mirrors `dependencies`:
+   *
+   * <ol>
+   * <li>Start with empty object.</li>
+   * <li>Merge <code>devDependencies</code> from each inherited configuration
+   *    in sequence
+   *    (later overrides earlier).</li>
+   * <li>Merge local <code>devDependencies</code> from JSON definition.</li>
+   * <li>Perform Liquid template substitution on the entire
+   *    <code>devDependencies</code>
+   *    object with full configuration context.</li>
+   * </ol>
+   *
+   * Typical use: Test frameworks, build tools, or debugging utilities
+   * specific to certain configurations (e.g., debug builds might include
+   * additional analysis tools).
+   */
+  devDependencies: JsonDependencies = {}
+
+  /**
+   * The JSON build configuration content from package metadata.
+   *
+   * @remarks
+   * This holds the raw configuration definition as it appears in
+   * `package.json`, before inheritance resolution and variable substitution.
+   *
+   * The definition is preserved to:
+   *
+   * <ol>
+   * <li>Enable external modification (e.g., <code>xpm uninstall</code>
+   *    updates this
+   *    directly).</li>
+   * <li>Support deferred template evaluation during
+   *    <code>BuildConfiguration.initialise()</code>.</li>
+   * <li>Provide the source for inheritance when other configurations
+   *    reference this one.</li>
+   * <li>Allow re-evaluation with different variable contexts if needed.</li>
+   * </ol>
+   *
+   * This immutable storage ensures configurations can be safely referenced
+   * during inheritance resolution without side effects.
+   */
+  jsonBuildConfiguration: JsonBuildConfigurationContent
+
+  /**
+   * Indicates whether this configuration originates from a template.
+   *
+   * @remarks
+   * This flag determines the substitution strategy during configuration
+   * initialisation, with template configurations requiring more extensive
+   * processing.
+   *
+   * Template vs regular configuration processing:
+   *
+   * <ol>
+   * <li>Template configurations (<code>isTemplate === true</code>):
+   *   <ul>
+   *   <li>Entire JSON configuration is stringified and substituted.</li>
+   *   <li>Matrix parameters available throughout all fields.</li>
+   *   <li>More expensive but supports matrix references anywhere.</li>
+   *   </ul>
+   * </li>
+   * <li>Regular configurations (<code>isTemplate === false</code>):
+   *   <ul>
+   *   <li>Only <code>inherits</code> field is substituted initially.</li>
+   *   <li>Other fields processed selectively during inheritance
+   *     resolution.</li>
+   *   <li>More efficient for configurations without matrix parameters.</li>
+   *   </ul>
+   * </li>
+   * </ol>
+   *
+   * Set to `true` when `templateBuildConfigurationName` is defined,
+   * indicating the configuration was generated from a template expansion.
+   */
+  isTemplate: boolean
+
+  // --------------------------------------------------------------------------
+  // Protected Members.
+
+  /**
+   * The logger instance for output and diagnostics.
+   *
+   * @remarks
+   * This logger provides trace-level diagnostics throughout the build
+   * configuration lifecycle, including template substitution, inheritance
+   * resolution, property merging, dependency substitution, and action
+   * preparation.
+   *
+   * It is initialised in the constructor from the parent collection's logger
+   * and used consistently across all helper methods to maintain coherent
+   * logging output. This enables detailed debugging of complex configuration
+   * hierarchies without impacting runtime performance when tracing is
+   * disabled.
+   */
+  protected readonly _log: Logger
+
+  /**
+   * The variables used for substitution in this configuration.
+   *
+   * @remarks
+   * This extended variable hierarchy combines the base collection variables
+   * with configuration-specific context, enabling accurate template
+   * evaluation.
+   *
+   * Extension hierarchy:
+   *
+   * <ol>
+   * <li>Starts with parent collection's base variables (env, os, path,
+   *    package).</li>
+   * <li>Extended with <code>properties</code>: Merged from inheritance
+   *    chain and local
+   *    properties.</li>
+   * <li>Extended with <code>matrix</code>: Parameter values for
+   *    template-generated
+   *    configurations.</li>
+   * <li>Extended with <code>configuration</code>: The configuration
+   *    object itself
+   *    (name, dependencies, properties) accessible for self-reference.</li>
+   * </ol>
+   *
+   * This complete context is used for all substitutions within the
+   * configuration: properties, dependencies, devDependencies, and actions.
+   */
+  protected _substitutionsVariables: LiquidSubstitutionsVariables
+
+  /**
+   * The matrix parameter values for template-generated configurations.
+   *
+   * @remarks
+   * For template-generated configurations, this object contains the specific
+   * matrix parameter values that produced this configuration instance from
+   * the template.
+   *
+   * Usage pattern:
+   *
+   * <ol>
+   * <li>Undefined for regular (non-template) configurations.</li>
+   * <li>For template configurations, contains key-value pairs from the matrix
+   *    combination (e.g.,
+   *   <code>\{ arch: 'x64', optimize: 'speed' \}</code>).</li>
+   * <li>Merged into substitution variables during initialisation, making
+   *    values accessible via the <code>matrix</code> namespace throughout the
+   *    configuration.</li>
+   * <li>Used in configuration name substitution, property values,
+   *    dependencies, and action commands.</li>
+   * </ol>
+   *
+   * Example: A template `release-{{ matrix.arch }}` with matrix parameters
+   * `{ arch: 'x64' }` becomes the concrete configuration `release-x64`.
+   */
+  protected readonly matrixParameters?: LiquidSubstitutionsStrings
+
+  /**
+   * The actions associated with this build configuration.
+   *
+   * @remarks
+   * This actions collection is created during configuration initialisation
+   * and combines inherited actions with local action definitions.
+   *
+   * Action assembly workflow:
+   *
+   * <ol>
+   * <li>Undefined until <code>BuildConfiguration.initialise()</code> is
+   *    called.</li>
+   * <li>Collect actions from all inherited configurations in the inheritance
+   *    chain.</li>
+   * <li>Create new <code>Actions</code> collection with inherited
+   *    actions map and local action definitions.</li>
+   * <li>Actions inherit the configuration's substitution variables context,
+   *    including properties and matrix parameters.</li>
+   * </ol>
+   *
+   * Actions are accessible after configuration initialisation but remain
+   * themselves uninitialised until retrieved and initialised individually,
+   * maintaining the lazy evaluation pattern.
+   */
+  protected _actions: Actions | undefined
+
+  /**
+   * The resolved build folder relative path.
+   *
+   * @remarks
+   * This path specifies where build outputs for this configuration should be
+   * placed, computed during initialisation and added back to properties for
+   * use in subsequent substitutions.
+   *
+   * Computation workflow:
+   *
+   * <ol>
+   * <li>Undefined until <code>BuildConfiguration.initialise()</code> is
+   *    called.</li>
+   * <li>Not computed for hidden configurations (optimization).</li>
+   * <li>If <code>buildFolderRelativePath</code> property exists, perform Liquid
+   *    substitution with full configuration context.</li>
+   * <li>Otherwise, generate default path:
+   *    <code>build/\{sanitized-config-name\}</code>.</li>
+   * <li>Added to <code>properties.buildFolderRelativePath</code> for use
+   *    in action
+   *    commands and dependency references.</li>
+   * </ol>
+   *
+   * The path is relative to the package root and used by build tools to
+   * organize outputs from different configurations.
+   */
+  protected _buildFolderRelativePath?: string
+
+  /**
+   * Set of inherited configuration names for circular reference detection.
+   *
+   * @remarks
+   * This set tracks the inheritance chain being processed to detect and
+   * prevent circular inheritance references.
+   *
+   * Detection mechanism:
+   *
+   * <ol>
+   * <li>Initially empty when configuration initialisation begins.</li>
+   * <li>Each inherited configuration name is added before processing that
+   *    configuration's inheritance.</li>
+   * <li>If a configuration attempts to inherit from a name already in the
+   *    set, a circular reference exists.</li>
+   * <li>Circular references trigger <code>InputError</code> with details
+   * about    the problematic inheritance chain.</li>
+   * </ol>
+   *
+   * Example: If config A inherits from B, B from C, and C from A, the
+   * circular dependency is detected when C attempts to inherit from A.
+   */
+  protected _inheritedNamesSet: Set<string> = new Set<string>()
+
+  /**
+   * Flag indicating whether the configuration has been initialised.
+   *
+   * @remarks
+   * This flag ensures idempotent initialization and prevents redundant
+   * processing when {@link BuildConfiguration.initialise} is called
+   * multiple times.
+   *
+   * State transitions:
+   *
+   * <ol>
+   * <li>Initially <code>false</code> after construction.</li>
+   * <li>Set to <code>true</code> after successful inheritance resolution,
+   *    property
+   *    merging, dependency substitution, and action preparation.</li>
+   * <li>Checked at the start of
+   *    <code>BuildConfiguration.initialise()</code> to return early if
+   *    already initialised.</li>
+   * </ol>
+   *
+   * This pattern is critical for inheritance processing, as configurations
+   * may be initialised multiple times when referenced by multiple children,
+   * but should only process their inheritance chain once.
+   */
+  protected _isInitialised = false
+
+  // --------------------------------------------------------------------------
+  // Constructor and async initialiser.
+
+  /**
+   * Constructs a build configuration instance.
+   *
+   * @param buildConfigurationName - The configuration name after substitution.
+   * @param templateBuildConfigurationName - The template configuration name, if
+   * derived from a template.
+   * @param jsonBuildConfiguration - The JSON configuration definition.
+   * @param parentBuildConfigurations - The parent configurations collection.
+   * @param matrixParameters - Optional matrix parameter values for
+   * template-generated configurations.
+   *
+   * @remarks
+   * The constructor performs partial initialisation. Full initialisation
+   * requires calling {@link BuildConfiguration.initialise}.
+   */
+  constructor({
+    buildConfigurationName,
+    templateBuildConfigurationName,
+    jsonBuildConfiguration,
+    parentBuildConfigurations,
+    matrixParameters,
+  }: BuildConfigurationConstructorParameters) {
+    assert(buildConfigurationName, 'buildConfigurationName is required')
+    assert(jsonBuildConfiguration, 'jsonBuildConfiguration is required')
+    assert(parentBuildConfigurations, 'parentBuildConfigurations is required')
+
+    const log = parentBuildConfigurations.log
+    this._log = log
+
+    log.trace(`${BuildConfiguration.name}(${buildConfigurationName})`)
+
+    this.name = buildConfigurationName
+    this.jsonBuildConfiguration = jsonBuildConfiguration
+    this.parentBuildConfigurations = parentBuildConfigurations
+    if (matrixParameters !== undefined) {
+      this.matrixParameters = matrixParameters
+    }
+    if (templateBuildConfigurationName !== undefined) {
+      this.templateName = templateBuildConfigurationName
+    }
+
+    this._substitutionsVariables = {
+      ...this.parentBuildConfigurations.substitutionsVariables,
+    }
+
+    this.isHidden = this.jsonBuildConfiguration.hidden ?? false
+
+    this.isTemplate = this.templateName !== undefined
+
+    // The rest of the initialisation is done in the async initialiser.
+  }
+
+  /**
+   * Completes the async initialisation of the build configuration.
+   *
+   * @remarks
+   * This method resolves inheritance, applies variable substitutions,
+   * computes dependencies, and prepares actions.
+   *
+   * Initialisation workflow:
+   *
+   * <ol>
+   * <li>Return early if already initialised (idempotent behaviour).</li>
+   * <li>For template configurations: Call
+   *    <code>_substituteTemplate()</code> to substitute
+   *    matrix parameters throughout the entire JSON structure.</li>
+   * <li>For non-template configurations: Call
+   *    <code>_substituteInherits()</code> to substitute
+   *    only the inherits field.</li>
+   * <li>Call <code>_processInherits()</code> to:
+   *   <ul>
+   *   <li>Process inheritance chain recursively with circular reference
+   *      detection.</li>
+   *   <li>Merge properties, dependencies, and devDependencies from inherited
+   *      configurations (later overrides earlier).</li>
+   *   <li>Collect inherited actions into a map.</li>
+   *   </ul>
+   * </li>
+   * <li>Apply local properties and update substitution variables context.</li>
+   * <li>For visible configurations: Compute build folder relative path via
+   *    <code>_getBuildFolderRelativePath()</code>.</li>
+   * <li>Substitute Liquid templates in dependencies and devDependencies.</li>
+   * <li>Create actions collection with inherited actions and local
+   * actions.</li>
+   * </ol>
+   *
+   * The substitution context includes package variables, configuration
+   * properties, matrix parameters (for templates), and the configuration
+   * object itself accessible via `configuration.name`, etc.
+   *
+   * @returns A promise that resolves to `true` if initialisation was performed,
+   * or `false` if already initialised.
+   *
+   * @throws {@link ConfigurationError}
+   * If substitutions fail.
+   *
+   * @throws {@link InputError}
+   * If inheritance references are invalid or circular.
+   */
+  async initialise(): Promise<boolean> {
+    const log = this._log
+    log.trace(`${BuildConfiguration.name}.initialise()` + ` @${this.name}`)
+
+    if (this._isInitialised) {
+      log.trace(
+        `${BuildConfiguration.name}.initialise()` + ` @${this.name} again`
+      )
+      return false
+    }
+
+    log.trace(`${BuildConfiguration.name}.initialise()` + ` @${this.name}`)
+    let localJsonBuildConfiguration: JsonBuildConfigurationContent
+
+    if (this.isTemplate) {
+      localJsonBuildConfiguration = await this._substituteTemplate()
+    } else {
+      localJsonBuildConfiguration = await this._substituteInherits()
+    }
+
+    // Add inherited properties, dependencies, devDependencies, and actions.
+    const inheritedActionsMap = await this._processInherits(
+      localJsonBuildConfiguration
+    )
+
+    this.properties = {
+      ...this.properties,
+      ...localJsonBuildConfiguration.properties,
+    }
+
+    assert(this.name, 'buildConfigurationName missing')
+    this._substitutionsVariables = {
+      ...this.parentBuildConfigurations.substitutionsVariables,
+      properties: {
+        ...this._substitutionsVariables.properties,
+        ...this.properties,
+      },
+      matrix: this.matrixParameters ?? {},
+      configuration: {
+        ...localJsonBuildConfiguration,
+        name: this.name,
+      },
+    }
+
+    if (!this.isHidden) {
+      this._buildFolderRelativePath = await this._getBuildFolderRelativePath()
+
+      // Add the buildFolderRelativePath property.
+      // Note: the async initialiser was needed due to this async operation.
+      const properties = this._substitutionsVariables.properties
+      properties.buildFolderRelativePath = this._buildFolderRelativePath
+    }
+
+    this.dependencies = {
+      ...this.dependencies,
+      ...localJsonBuildConfiguration.dependencies,
+    }
+
+    this.devDependencies = {
+      ...this.devDependencies,
+      ...localJsonBuildConfiguration.devDependencies,
+    }
+
+    const unsubstitutedDependencies = {
+      dependencies: this.dependencies,
+      devDependencies: this.devDependencies,
+    }
+
+    const stringifiedDependencies = JSON.stringify(unsubstitutedDependencies)
+
+    if (hasLiquidSyntax(stringifiedDependencies)) {
+      let substitutedDependencies
+      try {
+        substitutedDependencies = await performSubstitutions({
+          log,
+          engine: this.parentBuildConfigurations.engine,
+          input: stringifiedDependencies,
+          substitutionsVariables: this._substitutionsVariables,
+        })
+      } catch (error) {
+        const message =
+          getErrorMessage(error) +
+          ` in buildConfiguration "${this.name}" dependencies`
+        throw new ConfigurationError(message)
+      }
+      const parsedDependencies = JSON.parse(
+        substitutedDependencies
+      ) as JsonBuildConfigurationContent
+
+      // Safety net: These fallbacks to empty objects handle cases where the
+      // dependencies fields might be undefined after JSON parsing. This is
+      // unlikely because the JSON schema validation ensures these are objects
+      // when present, but provides robustness against malformed configuration
+      // or future schema changes.
+      /* c8 ignore start - safety net, they are always defined */
+      this.dependencies = parsedDependencies.dependencies ?? {}
+      this.devDependencies = parsedDependencies.devDependencies ?? {}
+      /* c8 ignore stop */
+    }
+
+    this._actions = new Actions({
+      log: this._log,
+      engine: this.parentBuildConfigurations.engine,
+      substitutionsVariables: this._substitutionsVariables,
+      inheritedActionsMap,
+      jsonActions: localJsonBuildConfiguration.actions,
+      buildConfiguration: this,
+    })
+
+    log.trace(
+      `${BuildConfiguration.name}.initialise() `,
+      `@{this.buildConfigurationName}`
+    )
+
+    if (!this.isHidden) {
+      log.trace(
+        this.name,
+        'buildFolderRelativePath =>',
+        this._buildFolderRelativePath
+      )
+    }
+    log.trace(this.name, 'properties => ', this.properties)
+    log.trace(this.name, 'dependencies => ', this.dependencies)
+    log.trace(this.name, 'devDependencies => ', this.devDependencies)
+
+    // Action names are not available at this point.
+    // log.trace(this.buildConfigurationName, 'actions => ',
+    // this._actions.names)
+
+    this._isInitialised = true
+    return true
+  }
+
+  // --------------------------------------------------------------------------
+  // Public Methods.
+
+  /**
+   * Retrieves the actions collection for this build configuration.
+   *
+   * @returns The actions collection.
+   */
+  get actions(): Actions {
+    assert(
+      this._isInitialised,
+      'BuildConfiguration must be initialised before ' + 'accessing actions'
+    )
+
+    assert(this._actions !== undefined, 'Actions not initialised')
+    return this._actions
+  }
+
+  /**
+   * Retrieves the build folder relative path for this configuration.
+   *
+   * @returns The build folder relative path.
+   */
+  get buildFolderRelativePath(): string {
+    assert(
+      this._isInitialised,
+      'BuildConfiguration must be initialised before ' +
+        'accessing buildFolderRelativePath'
+    )
+    assert(
+      this._buildFolderRelativePath !== undefined,
+      'BuildConfiguration _buildFolderRelativePath not initialised'
+    )
+    return this._buildFolderRelativePath
+  }
+
+  // --------------------------------------------------------------------------
+  // Private Methods.
+
+  /**
+   * Performs template substitution on the entire build configuration JSON.
+   *
+   * @remarks
+   * This method is invoked during initialisation for template-generated
+   * configurations to substitute matrix parameters throughout the entire
+   * configuration definition.
+   *
+   * Processing steps:
+   *
+   * <ol>
+   * <li>Stringify the entire JSON build configuration object.</li>
+   * <li>Check if the stringified JSON contains template syntax
+   *    (<code>\{\{</code> or <code>\{%</code>).</li>
+   * <li>If templates are found:
+   *   <ul>
+   *   <li>Perform Liquid substitutions with complete variable context
+   *      including matrix parameters.</li>
+   *   <li>Parse the substituted JSON string back into an object.</li>
+   *   </ul>
+   * </li>
+   * <li>If no templates are found, return the original configuration
+   *    as-is.</li>
+   * </ol>
+   *
+   * This comprehensive substitution approach ensures matrix parameters can
+   * be referenced anywhere within the configuration (properties, dependencies,
+   * actions, etc.), which is necessary for template-generated configurations
+   * but would be unnecessarily expensive for regular configurations.
+   *
+   * @returns A promise that resolves to the build configuration content with
+   * all template variables substituted.
+   *
+   * @throws {@link ConfigurationError}
+   * If Liquid template substitution fails.
+   */
+  // eslint-disable-next-line max-len
+  protected async _substituteTemplate(): Promise<JsonBuildConfigurationContent> {
+    const log = this._log
+
+    // For templates, perform substitutions on the entire build
+    // configuration JSON, since there can be matrix references everywhere.
+
+    let localJsonBuildConfiguration: JsonBuildConfigurationContent
+
+    const stringifiedJsonBuildConfiguration = JSON.stringify(
+      this.jsonBuildConfiguration
+    )
+    if (hasLiquidSyntax(stringifiedJsonBuildConfiguration)) {
+      let substitutedJsonBuildConfiguration
+      try {
+        substitutedJsonBuildConfiguration = await performSubstitutions({
+          log,
+          engine: this.parentBuildConfigurations.engine,
+          input: stringifiedJsonBuildConfiguration,
+          substitutionsVariables: {
+            ...this._substitutionsVariables,
+            // Safety net: This fallback ensures matrix is always an object.
+            // matrixParameters should be defined when processing templates with
+            // matrix expansion, but this handles edge cases where
+            // initialisation
+            // order or template logic might reference matrix before it's set.
+            /* c8 ignore start - safety net, they are always defined */
+            matrix: this.matrixParameters ?? {},
+            /* c8 ignore stop */
+            configuration: {
+              ...this.jsonBuildConfiguration,
+              name: this.name,
+            },
+          },
+        })
+      } catch (error) {
+        const message =
+          getErrorMessage(error) + ` in buildConfiguration "${this.name}"`
+        throw new ConfigurationError(message)
+      }
+
+      localJsonBuildConfiguration = JSON.parse(
+        substitutedJsonBuildConfiguration
+      ) as JsonBuildConfigurationContent
+    } else {
+      localJsonBuildConfiguration = this.jsonBuildConfiguration
+    }
+    return localJsonBuildConfiguration
+  }
+
+  /**
+   * Performs selective substitution on the inherits field only.
+   *
+   * @remarks
+   * This method is invoked during initialisation for regular (non-template)
+   * configurations to substitute template variables in the inheritance
+   * specification whilst leaving other fields untouched until later processing.
+   *
+   * Processing steps:
+   *
+   * <ol>
+   * <li>Extract the <code>inherits</code> (or deprecated
+   *    <code>inherit</code>) field from the
+   *    configuration.</li>
+   * <li>Stringify the inherits field and check for template syntax
+   *    (<code>\{\{</code> or <code>\{%</code>).</li>
+   * <li>If templates are found:
+   *   <ul>
+   *   <li>Perform Liquid substitutions with current variable context.</li>
+   *   <li>Parse the substituted JSON string back into an object.</li>
+   *   <li>Return a new configuration object with the substituted inherits
+   *      field and all other fields unchanged.</li>
+   *   </ul>
+   * </li>
+   * <li>If no templates are found, return the original configuration
+   *    as-is.</li>
+   * </ol>
+   *
+   * This selective approach is more efficient than full JSON substitution
+   * for regular configurations that do not have matrix parameters. The
+   * remaining fields (properties, dependencies, actions) are processed
+   * during inheritance resolution and dependency substitution phases.
+   *
+   * @returns A promise that resolves to the build configuration content with
+   * the inherits field substituted.
+   *
+   * @throws {@link ConfigurationError}
+   * If Liquid template substitution fails on the inherits field.
+   */
+  // eslint-disable-next-line max-len
+  protected async _substituteInherits(): Promise<JsonBuildConfigurationContent> {
+    const log = this._log
+
+    let localJsonBuildConfiguration: JsonBuildConfigurationContent
+
+    // For non-templates, first perform substitutions on 'inherits' only.
+    // The rest of the entries are collected as-is and processed later.
+    const stringifiedJsonInherits = JSON.stringify(
+      this.jsonBuildConfiguration.inherits ?? {}
+    )
+    if (hasLiquidSyntax(stringifiedJsonInherits)) {
+      let substitutedJsonInherits
+      try {
+        substitutedJsonInherits = await performSubstitutions({
+          log,
+          engine: this.parentBuildConfigurations.engine,
+          input: stringifiedJsonInherits,
+          substitutionsVariables: {
+            ...this._substitutionsVariables,
+            configuration: {
+              ...this.jsonBuildConfiguration,
+              name: this.name,
+            },
+          },
+        })
+      } catch (error) {
+        const message =
+          getErrorMessage(error) +
+          ` in buildConfiguration "${this.name}" inherits`
+        throw new ConfigurationError(message)
+      }
+
+      localJsonBuildConfiguration = {
+        ...this.jsonBuildConfiguration,
+        inherits: JSON.parse(
+          substitutedJsonInherits
+        ) as JsonBuildConfigurationInherits,
+      }
+    } else {
+      localJsonBuildConfiguration = this.jsonBuildConfiguration
+    }
+    return localJsonBuildConfiguration
+  }
+
+  /**
+   * Parses the inherits field from JSON configuration.
+   *
+   * @remarks
+   * This helper method extracts and normalises inheritance information from
+   * the configuration, supporting both the current <code>inherits</code>
+   * field and the deprecated <code>inherit</code> field. It handles both
+   * string and array formats.
+   *
+   * Processing steps:
+   *
+   * <ol>
+   * <li>Check for <code>inherits</code> field (current standard).</li>
+   * <li>Fall back to <code>inherit</code> field (deprecated).</li>
+   * <li>Convert single strings to single-element arrays.</li>
+   * <li>Join array elements with line breaks and split to handle
+   *    multi-line strings.</li>
+   * </ol>
+   *
+   * @param localJsonBuildConfiguration - The JSON configuration content.
+   * @returns Array of inherited configuration names.
+   */
+  private _parseInheritsField(
+    localJsonBuildConfiguration: JsonBuildConfigurationContent
+  ): string[] {
+    let jsonInherits: string[] = []
+    if (isString(localJsonBuildConfiguration.inherits)) {
+      jsonInherits = [localJsonBuildConfiguration.inherits as string]
+    } else if (Array.isArray(localJsonBuildConfiguration.inherits)) {
+      jsonInherits = localJsonBuildConfiguration.inherits as string[]
+    } else if (isString(localJsonBuildConfiguration.inherit)) {
+      jsonInherits = [localJsonBuildConfiguration.inherit as string]
+    } else if (Array.isArray(localJsonBuildConfiguration.inherit)) {
+      jsonInherits = localJsonBuildConfiguration.inherit as string[]
+    }
+
+    if (jsonInherits.length > 0) {
+      const joinedInherits = jsonInherits.join(os.EOL)
+      return joinedInherits.split(os.EOL)
+    }
+    return jsonInherits
+  }
+
+  /**
+   * Processes and merges a single inherited configuration.
+   *
+   * @remarks
+   * This helper method handles the initialisation of a single inherited
+   * configuration and merges its properties, dependencies, and actions into
+   * the current configuration.
+   *
+   * Processing steps:
+   *
+   * <ol>
+   * <li>Detect circular references by checking the inherited names set.</li>
+   * <li>Initialise the inherited configuration recursively.</li>
+   * <li>Merge properties, dependencies, and devDependencies using spread
+   *    operator (later values override earlier ones).</li>
+   * <li>Collect inherited actions into the provided map.</li>
+   * </ol>
+   *
+   * @param inheritedBuildConfigurationName - Name of the configuration to
+   * inherit from.
+   * @param inheritedActionsMap - Map to accumulate inherited actions.
+   * @returns A promise that resolves when processing is complete.
+   *
+   * @throws {@link InputError}
+   * If a circular inheritance reference is detected.
+   *
+   * @throws {@link InputError}
+   * If the inherited configuration name does not exist.
+   */
+  private async _processInheritedConfiguration(
+    inheritedBuildConfigurationName: string,
+    inheritedActionsMap: Map<string, Action>
+  ): Promise<void> {
+    if (inheritedBuildConfigurationName.trim() === '') {
+      return
+    }
+
+    if (
+      !this.parentBuildConfigurations.hasJson(inheritedBuildConfigurationName)
+    ) {
+      throw new ConfigurationError(
+        `buildConfiguration "${this.name}" ` +
+          `inherits from missing "${inheritedBuildConfigurationName}"`
+      )
+    }
+
+    if (this._inheritedNamesSet.has(inheritedBuildConfigurationName)) {
+      throw new ConfigurationError(
+        `buildConfiguration "${this.name}" ` +
+          `inherits from circular reference ` +
+          `"${inheritedBuildConfigurationName}"`
+      )
+    }
+
+    this._inheritedNamesSet.add(inheritedBuildConfigurationName)
+
+    const inheritedBuildConfiguration = this.parentBuildConfigurations.get(
+      inheritedBuildConfigurationName
+    )
+
+    await inheritedBuildConfiguration.initialise()
+
+    // Merge properties, dependencies, devDependencies.
+    // Later ones override earlier ones.
+    this.properties = {
+      ...this.properties,
+      ...inheritedBuildConfiguration.properties,
+    }
+
+    this.dependencies = {
+      ...this.dependencies,
+      ...inheritedBuildConfiguration.dependencies,
+    }
+
+    this.devDependencies = {
+      ...this.devDependencies,
+      ...inheritedBuildConfiguration.devDependencies,
+    }
+
+    await inheritedBuildConfiguration.actions.initialise()
+    for (const actionName of inheritedBuildConfiguration.actions.names) {
+      const action = inheritedBuildConfiguration.actions.get(actionName)
+      inheritedActionsMap.set(actionName, action)
+    }
+  }
+
+  /**
+   * Processes inheritance for a build configuration.
+   *
+   * @remarks
+   * This method implements the inheritance resolution mechanism for build
+   * configurations, enabling configurations to share properties, dependencies,
+   * and actions by inheriting from one or more base configurations,
+   * recursively.
+   *
+   * Processing workflow:
+   *
+   * <ol>
+   * <li>Extract inheritance specification from the configuration:
+   *   <ul>
+   *   <li>Supports both the current <code>inherits</code> field and the
+   *      deprecated <code>inherit</code> field for backwards
+   *      compatibility.</li>
+   *   <li>Handles both string format (single parent) and array format
+   *      (multiple parents).</li>
+   *   <li>Normalises line-separated names within array elements to support
+   *      multi-line specifications.</li>
+   *   </ul>
+   * </li>
+   * <li>Process each inherited configuration sequentially:
+   *   <ul>
+   *   <li>Skip empty names from the inheritance list.</li>
+   *   <li>Validate that the inherited configuration exists in the parent
+   *      collection.</li>
+   *   <li>Detect circular references by checking
+   *      <code>_inheritedNamesSet</code>.</li>
+   *   <li>Recursively initialise the inherited configuration (which may
+   *      itself have inheritance).</li>
+   *   </ul>
+   * </li>
+   * <li>Merge inherited content into the current configuration:
+   *   <ul>
+   *   <li>Properties: Later inherited configurations override earlier ones,
+   *      local properties override all inherited.</li>
+   *   <li>Dependencies and devDependencies: Same override behaviour as
+   *      properties.</li>
+   *   <li>Actions: Collected into a map where later definitions override
+   *      earlier ones with the same name.</li>
+   *   </ul>
+   * </li>
+   * </ol>
+   *
+   * The inheritance chain is processed depth-first, ensuring that transitive
+   * inheritance (A inherits B, B inherits C) is fully resolved before merging
+   * properties. Circular references are detected to prevent infinite recursion.
+   *
+   * @param localJsonBuildConfiguration - The JSON configuration content after
+   * template or inherits field substitution.
+   * @returns A promise that resolves to a map of inherited actions, where
+   * keys are action names and values are action instances from all inherited
+   * configurations.
+   *
+   * @throws {@link InputError}
+   * If an inherited configuration name does not exist in the parent collection.
+   *
+   * @throws {@link InputError}
+   * If a circular inheritance reference is detected.
+   */
+  protected async _processInherits(
+    localJsonBuildConfiguration: JsonBuildConfigurationContent
+  ): Promise<Map<string, Action>> {
+    const log = this._log
+
+    const inheritsNames = this._parseInheritsField(localJsonBuildConfiguration)
+    this.inheritsNames = inheritsNames
+
+    log.trace(this.name, 'inherits from', this.inheritsNames)
+
+    const inheritedActionsMap: Map<string, Action> = new Map<string, Action>()
+
+    for (const inheritedBuildConfigurationName of inheritsNames) {
+      await this._processInheritedConfiguration(
+        inheritedBuildConfigurationName,
+        inheritedActionsMap
+      )
+    }
+
+    return inheritedActionsMap
+  }
+
+  /**
+   * Computes the build folder relative path for this configuration.
+   *
+   * @remarks
+   * This method resolves the build folder relative path property when
+   * provided and uses a default value based on the configuration name
+   * otherwise.
+   *
+   * Resolution strategy:
+   *
+   * <ol>
+   * <li>Check if buildFolderRelativePath property exists in configuration
+   *    properties.</li>
+   * <li>If present and non-empty, perform Liquid substitutions with the
+   *    full configuration context.</li>
+   * <li>If substitution fails or property is empty/missing, generate a
+   *    default path: `build/{filtered-configuration-name}` where the
+   *    configuration name is sanitized for filesystem compatibility.</li>
+   * </ol>
+   *
+   * The computed path is added back to the properties as
+   * `buildFolderRelativePath` for use in subsequent substitutions.
+   *
+   * @returns A promise that resolves to the build folder relative path.
+   */
+  protected async _getBuildFolderRelativePath(): Promise<string> {
+    const log = this._log
+
+    let folderPath: string
+    if (
+      buildFolderRelativePathPropertyName in
+      this._substitutionsVariables.properties
+    ) {
+      folderPath = this._substitutionsVariables.properties[
+        buildFolderRelativePathPropertyName
+      ] as string
+      if (folderPath !== '') {
+        try {
+          // log.trace(this.#substitutionsVariables.configuration)
+          const substitutedFolderPath = await performSubstitutions({
+            log,
+            engine: this.parentBuildConfigurations.engine,
+            input: folderPath,
+            substitutionsVariables: this._substitutionsVariables,
+          })
+          return substitutedFolderPath
+        } catch (error) {
+          const message =
+            getErrorMessage(error) + ` in buildConfiguration "${this.name}"`
+          throw new ConfigurationError(message)
+        }
+      }
+    }
+
+    // Provide a default value, based on the name.
+    const defaultFolderPath = path.join('build', filterPath(this.name))
+    return defaultFolderPath
+  }
+}
+
+// ----------------------------------------------------------------------------