@xpack/xpm-lib 3.1.2 → 4.0.0

package/src/classes/combinations-generator.ts

@@ -0,0 +1,331 @@
+/*
+ * 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 { Logger } from '@xpack/logger'
+import { ConfigurationError } from './errors.js'
+
+// ============================================================================
+
+/**
+ * The default maximum number of combinations that can be generated.
+ *
+ * @remarks
+ * This constant defines the default limit for the total number of
+ * combinations that a {@link CombinationsGenerator} instance can produce.
+ * The limit exists to prevent performance issues and memory exhaustion when
+ * working with large matrices.
+ *
+ * This value can be overridden by providing a custom `maxCombinations`
+ * parameter when constructing a {@link CombinationsGenerator} instance.
+ *
+ * The limit is intentionally low (42 * 10).
+ */
+export const COMBINATIONS_GENERATOR_MAX_COMBINATIONS_LIMIT = 42 * 10
+
+/**
+ * A matrix combination mapping parameter names to their values.
+ *
+ * @remarks
+ * This type represents a single combination generated from a matrix of
+ * parameters, where each key is a parameter name and each value is a
+ * string from that parameter's array of possible values.
+ *
+ * Example: `{ arch: 'x64', platform: 'linux', optimize: 'speed' }`
+ */
+export type MatrixCombination = Record<string, string>
+
+// ============================================================================
+
+/**
+ * Configuration parameters for constructing a combinations generator instance.
+ *
+ * @remarks
+ * This interface defines the required configuration for creating an
+ * instance of {@link CombinationsGenerator}. All properties are mandatory.
+ *
+ * The parameters provide the matrix parameter names, their corresponding
+ * value arrays for Cartesian product computation, and the logger for
+ * diagnostic output during combination generation.
+ */
+export interface CombinationsGeneratorConstructorParameters {
+  /**
+   * The array of parameter names.
+   */
+  matrixKeys: string[]
+
+  /**
+   * The array of value arrays for each parameter.
+   */
+  matrixValues: string[][]
+
+  /**
+   * The logger instance for output and diagnostics.
+   */
+  log: Logger
+
+  /**
+   * Optional maximum combinations limit to prevent excessive generation.
+   *
+   * @remarks
+   * This parameter allows configuring a custom limit on the total number of
+   * combinations that can be generated. If the calculated total exceeds this
+   * limit, a {@link ConfigurationError} is thrown to prevent performance
+   * issues or memory exhaustion. The default value is 10,000 combinations.
+   */
+  maxCombinations?: number
+}
+
+/**
+ * Generates all possible combinations from a matrix of parameters.
+ *
+ * @remarks
+ * This class computes the Cartesian product of multiple parameter arrays,
+ * producing all possible combinations of parameter values using a
+ * memory-efficient generator pattern. It uses a recursive algorithm to
+ * systematically explore all combinations one at a time.
+ *
+ * The generation process:
+ *
+ * <ol>
+ * <li>Takes arrays of parameter names (keys) and their corresponding value
+ *    arrays.</li>
+ * <li>Recursively iterates through each parameter, selecting one value at a
+ *    time.</li>
+ * <li>Yields complete combinations one at a time without storing them all
+ *    in memory.</li>
+ * <li>Backtracks to explore other value combinations.</li>
+ * </ol>
+ *
+ * Example usage:
+ * ```typescript
+ * const generator = new CombinationsGenerator({
+ *   matrixKeys: ['arch', 'optimize'],
+ *   matrixValues: [['x64', 'arm'], ['speed', 'size']],
+ *   log
+ * });
+ * for (const combo of generator.generate()) {
+ *   // Process one combination at a time without storing all in memory
+ *   // Results:
+ *   //   { arch: 'x64', optimize: 'speed' }
+ *   //   { arch: 'x64', optimize: 'size' }
+ *   //   { arch: 'arm', optimize: 'speed' }
+ *   //   { arch: 'arm', optimize: 'size' }
+ *   await processConfiguration(combo);
+ * }
+ * ```
+ */
+export class CombinationsGenerator {
+  // --------------------------------------------------------------------------
+  // Protected Members.
+
+  /**
+   * The logger instance for output and diagnostics.
+   *
+   * @remarks
+   * This logger provides trace-level diagnostics during combination
+   * generation, enabling visibility into the recursive exploration of the
+   * parameter space without impacting performance when tracing is disabled.
+   */
+  protected readonly _log: Logger
+
+  /**
+   * The array of parameter names.
+   *
+   * @remarks
+   * This array contains the names of all matrix parameters in the order
+   * they should be processed during combination generation. Each key
+   * corresponds to a parameter that will appear in the generated
+   * combinations.
+   */
+  protected readonly _matrixKeys: string[]
+
+  /**
+   * The array of value arrays for each parameter.
+   *
+   * @remarks
+   * This two-dimensional array contains the possible values for each
+   * parameter. The outer array corresponds one-to-one with
+   * <code>matrixKeys</code>, where <code>matrixValues[i]</code> contains
+   * all possible values for the parameter <code>matrixKeys[i]</code>.
+   *
+   * The Cartesian product of all these value arrays produces the complete
+   * set of combinations.
+   */
+  protected readonly _matrixValues: string[][]
+
+  /**
+   * The maximum number of combinations allowed.
+   *
+   * @remarks
+   * This limit prevents excessive generation of combinations, protecting
+   * against performance issues and memory exhaustion.
+   */
+  protected readonly _maxCombinations: number
+
+  // --------------------------------------------------------------------------
+  // Constructor.
+
+  /**
+   * Constructs a combinations generator instance.
+   *
+   * @param matrixKeys - The array of parameter names.
+   * @param matrixValues - The array of value arrays for each parameter.
+   * @param log - The logger instance for output and diagnostics.
+   *
+   * @remarks
+   * The constructor validates that the structure of keys and values is
+   * correct and prepares the generator for combination generation. The
+   * actual generation is performed by calling `*generate`.
+   */
+  constructor({
+    matrixKeys,
+    matrixValues,
+    maxCombinations = COMBINATIONS_GENERATOR_MAX_COMBINATIONS_LIMIT,
+    log,
+  }: CombinationsGeneratorConstructorParameters) {
+    this._log = log
+    this._matrixKeys = matrixKeys
+    this._matrixValues = matrixValues
+    this._maxCombinations = maxCombinations
+
+    log.trace(
+      `${CombinationsGenerator.name}.constructor: ` +
+        `matrixKeys=${JSON.stringify(this._matrixKeys)} ` +
+        `matrixValues=${JSON.stringify(this._matrixValues)}`
+    )
+  }
+
+  // --------------------------------------------------------------------------
+  // Public Methods.
+
+  /**
+   * Generates combinations one at a time using a generator pattern.
+   *
+   * @remarks
+   * This method yields combinations one at a time instead of building the
+   * entire array in memory. This is particularly useful for large matrices
+   * where storing all combinations would be impractical.
+   *
+   * Memory efficiency:
+   *
+   * <ul>
+   * <li>For a matrix with 10 parameters and 5 values each (9,765,625
+   *    combinations), only one combination object exists in memory at a
+   *    time, regardless of matrix size.</li>
+   * <li>No array allocation or storage required.</li>
+   * <li>Immediate processing of each combination without waiting for all to
+   *    be generated.</li>
+   * </ul>
+   *
+   * Example usage:
+   * ```typescript
+   * for (const combo of generator.generate()) {
+   *   // Process one combination at a time
+   *   await processConfiguration(combo)
+   * }
+   * ```
+   *
+   * <b>Yields:</b> Individual matrix combinations one at a time.
+   */
+  *generate(): Generator<MatrixCombination> {
+    // Empty matrix produces no combinations
+    if (this._matrixKeys.length === 0) {
+      return
+    }
+
+    // Calculate total combinations
+    const totalCombinations = this._matrixValues.reduce(
+      (product, values) => product * values.length,
+      1
+    )
+
+    if (totalCombinations > this._maxCombinations) {
+      throw new ConfigurationError(
+        `Matrix would generate ${String(totalCombinations)} combinations, ` +
+          `exceeding limit of ${String(this._maxCombinations)}. ` +
+          `Consider using fewer parameters or values.`
+      )
+    }
+
+    yield* this._generateRecursively(0, {})
+  }
+
+  // --------------------------------------------------------------------------
+  // Private Methods.
+
+  /**
+   * Recursively generates combinations as a generator, yielding one at
+   * a time.
+   *
+   * @remarks
+   * This method implements the recursive algorithm for generating the
+   * Cartesian product of parameter values using the generator pattern.
+   *
+   * Algorithm steps:
+   *
+   * <ol>
+   * <li><b>Base case:</b> If all parameters have been assigned values
+   *    (<code>index === matrixKeys.length</code>), yield a copy of the
+   *    current combination and return.</li>
+   * <li><b>Recursive case:</b> For the parameter at the current index:
+   *   <ul>
+   *   <li>Iterate through all possible values for this parameter.</li>
+   *   <li>Assign each value to the combination object.</li>
+   *   <li>Recursively yield combinations for the next parameter using
+   *      <code>yield*</code>.</li>
+   *   <li>Remove the assigned value (backtrack) before trying the next
+   *      value.</li>
+   *   </ul>
+   * </li>
+   * </ol>
+   *
+   * The combination object is reused and modified during traversal, with
+   * only copies of complete combinations being yielded. This approach
+   * minimises memory allocation whilst maintaining correctness.
+   *
+   * @param index - The current parameter index being processed.
+   * @param combination - The partial combination being built.
+   *
+   * <b>Yields:</b> Complete combinations one at a time.
+   */
+  protected *_generateRecursively(
+    index: number,
+    combination: Record<string, string>
+  ): Generator<MatrixCombination> {
+    const log = this._log
+    log.trace(
+      `${CombinationsGenerator.name}.` +
+        `_generateRecursively(${String(index)},` +
+        `${JSON.stringify(combination)})`
+    )
+
+    if (index === this._matrixKeys.length) {
+      log.trace('combination complete =>', combination)
+      yield { ...combination }
+
+      return
+    }
+
+    const key = this._matrixKeys[index]
+    const values = this._matrixValues[index]
+
+    for (const value of values) {
+      combination[key] = value
+      yield* this._generateRecursively(index + 1, combination)
+      // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+      delete combination[key]
+    }
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/classes/data-model.ts

@@ -0,0 +1,337 @@
+/*
+ * 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 os from 'node:os'
+
+import { Logger } from '@xpack/logger'
+
+// ----------------------------------------------------------------------------
+
+import {
+  LiquidSubstitutionsVariables,
+  liquidSubstitutionsVariablesBase,
+} from '../data/substitutions-variables.js'
+import { isJsonObject } from '../functions/is-something.js'
+import { Actions } from './actions.js'
+import { BuildConfigurations } from './build-configurations.js'
+import { LiquidEngine } from './liquid-engine.js'
+import { JsonXpmPackage } from '../types/json.js'
+
+// ============================================================================
+
+/**
+ * The property name used for the build folder relative path.
+ */
+export const buildFolderRelativePathPropertyName = 'buildFolderRelativePath'
+
+// ============================================================================
+
+/**
+ * Configuration parameters for constructing a data model instance.
+ *
+ * @remarks
+ * This interface defines the required configuration for creating an
+ * instance of {@link DataModel}. Both properties are mandatory.
+ *
+ * The parameters provide the parsed <code>package.json</code> content
+ * containing package metadata and <b>xpm</b>-specific configuration, along
+ * with the logger for diagnostic output during data model initialization
+ * and template processing.
+ */
+export interface DataModelConstructorParameters {
+  /**
+   * The JSON package definition.
+   */
+  jsonPackage: JsonXpmPackage
+
+  /**
+   * The logger instance for output and diagnostics.
+   */
+  log: Logger
+}
+
+/**
+ * Represents a lazy-loading data model for an <b>xpm</b> package.
+ *
+ * @remarks
+ * This class prepares substitution variables, creates the Liquid
+ * engine, and exposes actions and build configurations defined in the package.
+ *
+ * The package processor serves as the top-level coordinator for all
+ * Liquid-based template processing in an <b>xpm</b> package. It establishes the
+ * foundation for variable substitution throughout the package hierarchy:
+ *
+ * <ol>
+ * <li>Initializes base substitution variables (platform detection, system
+ *    information, etc.).</li>
+ * <li>Adds package-specific variables from <code>package.json</code>
+ *     metadata.</li>
+ * <li>Merges user-defined properties from <code>xpack.properties</code>.</li>
+ * <li>Creates package-level actions accessible across all contexts.</li>
+ * <li>Creates build configurations, each inheriting the base substitution
+ *    context and adding configuration-specific variables.</li>
+ * </ol>
+ *
+ * This hierarchical structure ensures that templates at any level have
+ * access to appropriate variables while maintaining clear scoping rules.
+ * Package-level actions are available globally, while configuration-level
+ * actions are scoped to their respective configurations.
+ */
+export class DataModel {
+  // --------------------------------------------------------------------------
+  // Public Members.
+
+  /**
+   * The variables available for Liquid substitutions.
+   *
+   * @remarks
+   * This sealed object provides the base substitution context inherited by
+   * all actions and build configurations within the package.
+   *
+   * Variable hierarchy:
+   *
+   * <ol>
+   * <li><b>Base variables (xpmLiquidSubstitutionsVariablesBase):</b>
+   *   <ul>
+   *   <li><code>env</code>: Environment variables from process.env</li>
+   *   <li><code>os</code>: Platform detection (platform, arch, endianness,
+   *      version)</li>
+   *   <li><code>path</code>: Path utilities (sep, delimiter, cwd)</li>
+   *   </ul>
+   * </li>
+   * <li><b>Package metadata:</b>
+   *   <ul>
+   *   <li><code>package</code>: Complete <code>package.json</code> content
+   *      (name, version,
+   *      dependencies, etc.)</li>
+   *   </ul>
+   * </li>
+   * <li><b>User-defined properties:</b>
+   *   <ul>
+   *   <li><code>properties</code>: Merged from
+   *      <code>xpack.properties</code> if present</li>
+   *   </ul>
+   * </li>
+   * </ol>
+   *
+   * The object is sealed after initialization to prevent accidental
+   * modification. Child components (actions and configurations) extend this
+   * context with their own scoped variables (configuration, matrix) without
+   * modifying the original sealed object.
+   */
+  readonly substitutionsVariables: LiquidSubstitutionsVariables
+
+  /**
+   * The actions collection for this package.
+   *
+   * @remarks
+   * This collection manages package-level actions defined in
+   * `xpack.actions`, which are globally accessible and not tied to specific
+   * build configurations.
+   *
+   * Package-level actions characteristics:
+   *
+   * <ol>
+   * <li>Created during construction but initially unpopulated.</li>
+   * <li>Populated during the collection's own initialisation when
+   *    <code>Actions.initialise()</code> is called.</li>
+   * <li>Have access to package-level substitution variables but not
+   *    configuration-specific variables.</li>
+   * <li>Suitable for package-wide tasks like testing, documentation
+   *    generation, or global cleanup.</li>
+   * <li>Can be used alongside configuration-specific actions, which inherit
+   *    from package-level actions.</li>
+   * </ol>
+   */
+  readonly actions: Actions
+
+  /**
+   * The build configurations collection for this package.
+   *
+   * @remarks
+   * This collection manages all build configurations defined in
+   * `xpack.buildConfigurations`, supporting inheritance, template expansion,
+   * and configuration-specific properties and dependencies.
+   *
+   * Build configurations characteristics:
+   *
+   * <ol>
+   * <li>Created during construction but initially unpopulated.</li>
+   * <li>Populated during the collection's own initialisation when
+   *    <code>BuildConfigurations.initialise()</code> is called.</li>
+   * <li>Each configuration inherits the package-level substitution variables
+   *    and extends them with configuration-specific context.</li>
+   * <li>Support complex inheritance chains where configurations can inherit
+   *    properties, dependencies, and actions from other configurations.</li>
+   * <li>Can be generated from templates with matrix expansion for
+   *    multi-platform or multi-variant builds.</li>
+   * <li>Each configuration maintains its own actions collection, inheriting
+   *    package-level actions and adding configuration-specific ones.</li>
+   * </ol>
+   */
+  readonly buildConfigurations: BuildConfigurations
+
+  /**
+   * The logger instance for output and diagnostics.
+   *
+   * @remarks
+   * This logger provides trace-level diagnostics for the entire package
+   * processing hierarchy, including Liquid engine creation, variable
+   * initialization, action collection setup, and build configuration
+   * preparation. It's passed down to child components (actions and build
+   * configurations) to maintain consistent logging throughout the package
+   * lifecycle.
+   */
+  protected readonly _log: Logger
+
+  // --------------------------------------------------------------------------
+  // Private Members.
+
+  /**
+   * The Liquid engine used for substitutions.
+   *
+   * @remarks
+   * This LiquidEngine instance is configured with strict mode and custom
+   * filters for xpm-specific operations. It's shared across all actions and
+   * build configurations within the package, ensuring consistent template
+   * processing behavior.
+   *
+   * Engine characteristics:
+   *
+   * <ol>
+   * <li>Strict mode enabled to catch undefined variable references.</li>
+   * <li>Custom filters for platform detection (<code>isPlatform</code>,
+   *    <code>isArch</code>).</li>
+   * <li>Custom filters for path sanitization (<code>filterPath</code>,
+   *    <code>filterPosixPath</code>,
+   *    <code>filterWin32Path</code>).</li>
+   * <li>Shared instance reduces memory overhead and ensures consistent
+   *    template evaluation across all package components.</li>
+   * </ol>
+   */
+  protected readonly _engine: LiquidEngine
+
+  /**
+   * The JSON package definition.
+   *
+   * @remarks
+   * This object contains the complete `package.json` content, including both
+   * standard npm fields and xpm-specific extensions in the `xpack` section.
+   *
+   * Required structure:
+   *
+   * <ol>
+   * <li>Standard npm fields: name, version, dependencies, devDependencies.</li>
+   * <li>Required <code>xpack</code> section containing xpm-specific
+   *    configuration.</li>
+   * <li>Optional <code>xpack.properties</code> for user-defined
+   *    substitution variables.</li>
+   * <li>Optional <code>xpack.actions</code> for package-level executable
+   *    actions.</li>
+   * <li>Optional <code>xpack.buildConfigurations</code> for build configuration
+   *    definitions.</li>
+   * </ol>
+   *
+   * The package definition is validated during construction, requiring the
+   * `xpack` section to be present and be a valid JSON object.
+   */
+  protected readonly _jsonPackage: JsonXpmPackage
+
+  // --------------------------------------------------------------------------
+  // Constructor.
+
+  /**
+   * Constructs a Liquid package processor.
+   *
+   * @remarks
+   * The constructor initializes the Liquid engine and prepares the
+   * substitution variables context that will be inherited by all actions
+   * and build configurations.
+   *
+   * Initialization sequence:
+   *
+   * <ol>
+   * <li>Create <code>LiquidEngine</code> with custom filters and strict
+   * configuration.</li>
+   * <li>Validate <code>xpack</code> section exists in
+   *    <code>package.json</code>.</li>
+   * <li>Initialize base substitution variables (os, platform, arch, etc.).</li>
+   * <li>Add package metadata to substitution context.</li>
+   * <li>Merge <code>xpack.properties</code> if defined, allowing user-defined
+   * variables.</li>
+   * <li>Seal substitution variables to prevent accidental modification.</li>
+   * <li>Create package-level actions collection (initially empty, populated
+   *    during initialisation).</li>
+   * <li>Create build configurations collection (initially empty, populated
+   *    during initialisation).</li>
+   * </ol>
+   *
+   * The substitution variables object is sealed to ensure immutability of
+   * the base context. Individual actions and configurations will extend this
+   * context with their own scoped variables without modifying the original.
+   *
+   * @param jsonPackage - The JSON package definition.
+   * @param log - The logger instance for output and diagnostics.
+   */
+  constructor({ jsonPackage, log }: DataModelConstructorParameters) {
+    log.trace(`${DataModel.name}()`)
+
+    this._log = log
+    this._engine = new LiquidEngine()
+
+    assert(
+      isJsonObject(jsonPackage.xpack),
+      'xpack section missing in package.json'
+    )
+    this._jsonPackage = jsonPackage
+
+    // os.version() available since 12.x
+    assert(
+      typeof os.version === 'function',
+      'Mandatory os.version available only since 12.x'
+    )
+
+    this.substitutionsVariables = {
+      ...liquidSubstitutionsVariablesBase,
+      package: jsonPackage,
+    }
+
+    if (isJsonObject(jsonPackage.xpack.properties)) {
+      this.substitutionsVariables.properties = {
+        ...jsonPackage.xpack.properties,
+      }
+    }
+
+    // Prevent adding/removing properties.
+    Object.seal(this.substitutionsVariables)
+
+    // Empty actions.
+    this.actions = new Actions({
+      log: this._log,
+      engine: this._engine,
+      substitutionsVariables: this.substitutionsVariables,
+      jsonActions: this._jsonPackage.xpack.actions,
+    })
+
+    // Empty build configurations.
+    this.buildConfigurations = new BuildConfigurations({
+      log: this._log,
+      engine: this._engine,
+      substitutionsVariables: this.substitutionsVariables,
+      jsonBuildConfigurations: this._jsonPackage.xpack.buildConfigurations,
+    })
+  }
+}
+
+// ----------------------------------------------------------------------------