@xpack/xpm-lib 3.1.2 → 4.0.0

package/src/functions/filter-paths.ts

@@ -0,0 +1,126 @@
+/*
+ * 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 { PlatformDetector } from '../classes/platform-detector.js'
+
+// ============================================================================
+
+/**
+ * Replaces non-alphanumeric characters with dashes to make paths
+ * comply with file system names.
+ *
+ * @remarks
+ * This function sanitizes strings to be safely used as file or folder names
+ * by removing or replacing problematic characters that could cause issues
+ * across different file systems.
+ *
+ * Platform-specific processing:
+ *
+ * <ul>
+ * <li><b>Windows:</b> Preserves backslashes (<code>\\</code>) and colons
+ *    (<code>:</code>) for drive letters
+ *    and path separators (e.g., <code>C:\\path\\to\\file</code>). Replaces all
+ *    other non-alphanumeric characters with dashes.</li>
+ * <li><b>POSIX (Linux, macOS):</b> Preserves forward slashes (<code>/</code>)
+ *    for path separators. Replaces all other non-alphanumeric characters with
+ *    dashes.</li>
+ * </ul>
+ *
+ * Post-processing: After character replacement, consecutive dashes are
+ * collapsed to a single dash to avoid excessive dashes from adjacent
+ * special characters (e.g., "foo--bar" becomes "foo-bar").
+ *
+ * Common use cases include sanitizing build configuration names,
+ * user-provided identifiers, and template-generated path components.
+ *
+ * @param input - A path candidate.
+ * @param platformDetector - The platform detector instance to use. Defaults
+ * to a new {@link PlatformDetector} instance.
+ * @returns A validated path.
+ */
+export function filterPath(
+  input: string,
+  platformDetector: PlatformDetector = new PlatformDetector()
+): string {
+  const fixed = platformDetector.isWindows()
+    ? input.replace(/[^a-zA-Z0-9\\:]+/g, '-')
+    : input.replace(/[^a-zA-Z0-9/]+/g, '-')
+  return fixed.replace(/--/g, '-')
+}
+
+/**
+ * Replaces non-alphanumeric characters with dashes to make paths
+ * comply with POSIX file system names.
+ *
+ * @remarks
+ * This function provides explicit POSIX path sanitization regardless of the
+ * current platform. Useful when generating paths that will be used on
+ * Linux or macOS systems, or when consistency across platforms is required.
+ *
+ * Processing rules:
+ *
+ * <ul>
+ * <li>Preserves forward slashes (<code>/</code>) for path separators.</li>
+ * <li>Replaces all non-alphanumeric characters (except <code>/</code>) with
+ *    dashes.</li>
+ * <li>Collapses consecutive dashes to single dashes.</li>
+ * </ul>
+ *
+ * Use this function instead of {@link filterPath} when you need guaranteed
+ * POSIX-style sanitization even when running on Windows, such as when
+ * generating paths for remote Linux systems or container images.
+ *
+ * @param input - A path candidate.
+ * @returns A validated path.
+ */
+export function filterPosixPath(input: string): string {
+  /* istanbul ignore next */
+  const fixed = input.replace(/[^a-zA-Z0-9/]+/g, '-')
+
+  return fixed.replace(/--/g, '-')
+}
+
+/**
+ * Replaces non-alphanumeric characters with dashes to make paths
+ * comply with Windows file system names.
+ *
+ * @remarks
+ * This function provides explicit Windows path sanitization regardless of
+ * the current platform. Useful when generating paths that will be used on
+ * Windows systems, or when consistency across platforms is required.
+ *
+ * Processing rules:
+ *
+ * <ul>
+ * <li>Preserves backslashes (<code>\\</code>) for path separators.</li>
+ * <li>Preserves colons (<code>:</code>) for drive letter designation (e.g.,
+ *    <code>C:</code>).</li>
+ * <li>Replaces all other non-alphanumeric characters with dashes.</li>
+ * <li>Collapses consecutive dashes to single dashes.</li>
+ * </ul>
+ *
+ * Use this function instead of {@link filterPath} when you need guaranteed
+ * Windows-style sanitization even when running on POSIX systems, such as
+ * when generating paths for remote Windows systems or WSL environments.
+ *
+ * @param input - A path candidate.
+ * @returns A validated path.
+ */
+export function filterWin32Path(input: string): string {
+  /* istanbul ignore next */
+  const fixed = input.replace(/[^a-zA-Z0-9\\:]+/g, '-')
+
+  return fixed.replace(/--/g, '-')
+}
+
+// ----------------------------------------------------------------------------

package/src/functions/is-something.ts

@@ -0,0 +1,223 @@
+/*
+ * 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.
+ */
+
+// ============================================================================
+
+/**
+ * Determines whether a value is a JavaScript primitive.
+ *
+ * @remarks
+ * In JavaScript, primitives are immutable values that are not objects:
+ * `string`, `number`, `bigint`, `boolean`, `undefined`, and `symbol`.
+ * This function
+ * also treats null as a primitive, following JavaScript's `typeof` behavior
+ * despite null being technically an object type.
+ *
+ * Returns `true` for: `string`, `number`, `bigint`, `boolean`, `undefined`,
+ * `symbol`, and `null`.
+ *
+ * Returns `false` for: objects, arrays, functions, and class instances.
+ *
+ * Useful for distinguishing between value types and reference types when
+ * processing JSON data or validating configuration inputs.
+ *
+ * @param value - The value to test.
+ * @returns `true` if the value is a primitive or `null`, `false` otherwise.
+ */
+export function isPrimitive(value: unknown): boolean {
+  return (
+    (typeof value !== 'object' && typeof value !== 'function') || value === null
+  )
+}
+
+/**
+ * Determines whether a value is a string.
+ *
+ * @remarks
+ * This function acts as a TypeScript type guard, narrowing the type to
+ * `string` within conditional blocks. This enables safe string operations
+ * without type assertions.
+ *
+ * Example usage:
+ * ```typescript
+ * if (isString(value)) {
+ *   // TypeScript knows value is a string here
+ *   const length = value.length;
+ * }
+ * ```
+ *
+ * Only returns `true` for primitive string values, not String objects
+ * created with `new String()`.
+ *
+ * @param value - The value to test.
+ * @returns `true` if the value is a string, `false` otherwise.
+ */
+export function isString(value: unknown): boolean {
+  return typeof value === 'string'
+}
+
+/**
+ * Determines whether a value is a finite number.
+ *
+ * @remarks
+ * This function validates that a value is both a number type and
+ * mathematically finite, excluding `NaN`, `Infinity`, and `-Infinity`.
+ * This is essential when validating numeric configuration values or
+ * processing JSON data where numeric fields must contain valid,
+ * computable values.
+ *
+ * Returns `true` for: all finite numeric values, including `0`, negative
+ * numbers, and floating-point numbers.
+ *
+ * Returns `false` for: `NaN`, `Infinity`, `-Infinity`, strings, objects,
+ * arrays, and any non-number types.
+ *
+ * Only returns `true` for primitive number values, not Number objects
+ * created with `new Number()`.
+ *
+ * The finiteness check is crucial for mathematical operations and ensures
+ * that numeric properties in `package.json` or configuration files contain
+ * usable values rather than special numeric constants that could cause
+ * unexpected behaviour in calculations.
+ *
+ * @param value - The value to test.
+ * @returns `true` if the value is a finite number, `false` otherwise.
+ */
+export function isNumber(value: unknown): boolean {
+  return typeof value === 'number' && isFinite(value)
+}
+
+/**
+ * Determines whether a value is a boolean.
+ *
+ * @remarks
+ * Tests for primitive boolean values (`true` or `false`). Useful when
+ * validating configuration options or parsing JSON where boolean flags
+ * need to be distinguished from truthy/falsy values.
+ *
+ * Only returns `true` for the primitive boolean values `true` and `false`,
+ * not for boolean objects created with `new Boolean()`.
+ *
+ * Note: This does not check for truthy or falsy values - it only returns
+ * `true` for actual boolean primitives. Use standard JavaScript truthiness
+ * checks for conditional logic.
+ *
+ * @param value - The value to test.
+ * @returns `true` if the value is a boolean, `false` otherwise.
+ */
+export function isBoolean(value: unknown): boolean {
+  return typeof value === 'boolean'
+}
+
+/**
+ * Determines whether a value is a non-array object.
+ *
+ * @remarks
+ * This function distinguishes between objects and arrays, which is crucial
+ * when processing JSON structures where both use the object type but require
+ * different handling.
+ *
+ * Returns `true` for: plain objects, class instances, null and other
+ * object types.
+ *
+ * Returns `false` for: arrays, primitives, and functions.
+ *
+ * Note: Arrays in JavaScript are objects, so this function explicitly
+ * excludes them using `Array.isArray()`. Use {@link isJsonObject} for
+ * stricter JSON object validation that also excludes `undefined` and `null`.
+ *
+ * @param value - The value to test.
+ * @returns `true` if the value is a non-array object, `false` otherwise.
+ */
+export function isObject(value: unknown): boolean {
+  return typeof value === 'object' && !Array.isArray(value)
+}
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Determines whether a value is a JSON object.
+ *
+ * @remarks
+ * Validates that a value represents a JSON object, which is stricter than
+ * JavaScript's general object type. This is essential when working with
+ * parsed JSON data or `package.json` structures.
+ *
+ * Returns `true` for: plain objects (non-null,
+ * non-primitive, non-array values).
+ *
+ * Returns `false` for: undefined, null, primitives (string, number,
+ * boolean, etc.), and arrays.
+ *
+ * This is the primary validation function for JSON objects in the <b>xpm</b>
+ * codebase, used extensively when parsing `package.json` sections like
+ * `xpack.properties`, `xpack.buildConfigurations`, etc.
+ *
+ * @param value - The value to test.
+ * @returns `true` if the value is a JSON object, `false` otherwise.
+ */
+export function isJsonObject(value: unknown): boolean {
+  return value !== undefined && !isPrimitive(value) && !Array.isArray(value)
+}
+
+/**
+ * Determines whether a value is a JSON array.
+ *
+ * @remarks
+ * Validates that a value represents a JSON array, excluding `undefined`.
+ * This ensures the value is a proper array that could have been parsed
+ * from JSON.
+ *
+ * Returns `true` for: any array, including empty arrays.
+ *
+ * Returns `false` for: undefined, null, objects, and primitives.
+ *
+ * The undefined check is important for distinguishing between optional
+ * properties that are missing (undefined) versus properties that are
+ * explicitly empty arrays. This is common in package.json where array
+ * fields may be absent or present but empty.
+ *
+ * @param value - The value to test.
+ * @returns `true` if the value is a JSON array, `false` otherwise.
+ */
+export function isJsonArray(value: unknown): boolean {
+  return value !== undefined && Array.isArray(value)
+}
+
+/**
+ * Determines whether a value is a non-empty JSON object.
+ *
+ * @remarks
+ * Combines JSON object validation with a non-empty check, ensuring the
+ * object has at least one property. This is useful for validating
+ * configuration sections that must contain data to be meaningful.
+ *
+ * Returns `true` for: objects with one or more enumerable properties.
+ *
+ * Returns `false` for: empty objects `{}`, undefined, null, primitives,
+ * arrays, and any non-object types.
+ *
+ * The enumerable properties check uses `Object.keys()`, which only counts
+ * own enumerable string-keyed properties, not inherited properties or
+ * symbol-keyed properties.
+ *
+ * Common use cases include validating `xpack.actions`, `xpack.dependencies`,
+ * and other `package.json` sections where an empty object would be
+ * meaningless.
+ *
+ * @param value - The value to test.
+ * @returns `true` if the value is a non-empty JSON object, `false` otherwise.
+ */
+export function isNonEmptyJsonObject(value: unknown): boolean {
+  return isJsonObject(value) && Object.keys(value as object).length > 0
+}
+
+// ----------------------------------------------------------------------------

package/src/functions/matrix-expander.ts

@@ -0,0 +1,172 @@
+/*
+ * 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 * as os from 'node:os'
+
+import { Logger } from '@xpack/logger'
+
+// ----------------------------------------------------------------------------
+
+import { LiquidEngine } from '../classes/liquid-engine.js'
+import { LiquidSubstitutionsVariables } from '../data/substitutions-variables.js'
+import { ConfigurationError } from '../classes/errors.js'
+import { isJsonArray, isString } from './is-something.js'
+import { performSubstitutions } from './perform-substitutions.js'
+import { hasLiquidSyntax } from './utils.js'
+import { getErrorMessage } from './utils.js'
+import { JsonTemplateMatrix } from '../types/json.js'
+
+// ============================================================================
+
+/**
+ * Result of matrix validation and processing.
+ *
+ * @remarks
+ * This interface encapsulates the processed matrix data ready for
+ * Cartesian product generation.
+ */
+export interface ProcessedMatrix {
+  /**
+   * Array of matrix parameter names.
+   */
+  matrixKeys: string[]
+
+  /**
+   * Array of value arrays for each parameter.
+   */
+  matrixValues: string[][]
+}
+
+// ============================================================================
+
+/**
+ * Validates and processes a matrix object for template expansion.
+ *
+ * @remarks
+ * This function extracts common matrix processing logic used by both
+ * actions and build configurations template expansion. It validates the
+ * matrix structure, performs Liquid substitutions on matrix values if needed,
+ * and prepares the data for Cartesian product generation.
+ *
+ * Processing steps:
+ *
+ * <ol>
+ * <li>Validates that each matrix property is an array of strings.</li>
+ * <li>For each matrix parameter:
+ *   <ul>
+ *   <li>Collects the parameter name (key).</li>
+ *   <li>Joins array values with line breaks for substitution.</li>
+ *   <li>If values contain Liquid syntax, performs substitutions.</li>
+ *   <li>Splits the result back into individual values.</li>
+ *   </ul>
+ * </li>
+ * <li>Returns processed matrix keys and values ready for combination
+ *   generation.</li>
+ * </ol>
+ *
+ * Matrix value substitution enables dynamic matrix generation where matrix
+ * values themselves can reference other substitution variables, enabling
+ * flexible configuration without hardcoding platform-specific or
+ * environment-specific values.
+ *
+ * @param matrix - The matrix object from JSON template.
+ * @param templateName - The template name for error messages.
+ * @param templateType - The template type ('action' or 'buildConfiguration')
+ * for error messages.
+ * @param engine - The Liquid engine for substitutions.
+ * @param substitutionsVariables - The variables available for substitution.
+ * @param log - The logger instance for diagnostics.
+ * @returns The processed matrix keys and values.
+ *
+ * @throws {@link ConfigurationError}
+ * If the matrix structure is invalid or substitution fails.
+ */
+export async function processMatrixForExpansion({
+  matrix,
+  templateName,
+  templateType,
+  engine,
+  substitutionsVariables,
+  log,
+}: {
+  matrix: JsonTemplateMatrix
+  templateName: string
+  templateType: 'action' | 'buildConfiguration'
+  engine: LiquidEngine
+  substitutionsVariables: LiquidSubstitutionsVariables
+  log: Logger
+}): Promise<ProcessedMatrix> {
+  const matrixKeys: string[] = []
+  const matrixValues: string[][] = []
+
+  for (const [matrixKey, matrixValueArray] of Object.entries(matrix)) {
+    if (!isJsonArray(matrixValueArray)) {
+      throw new ConfigurationError(
+        `${templateType} "${templateName}" ` +
+          `matrix.${matrixKey} is not an array`
+      )
+    }
+
+    if (matrixValueArray.length === 0) {
+      throw new ConfigurationError(
+        `${templateType} "${templateName}" ` +
+          `matrix.${matrixKey} cannot be empty`
+      )
+    }
+
+    // Type assertion after validation
+    const validatedArray = matrixValueArray as unknown[]
+
+    for (const matrixValue of validatedArray) {
+      if (!isString(matrixValue)) {
+        throw new ConfigurationError(
+          `${templateType} "${templateName}" ` +
+            `matrix.${matrixKey} value is not a string`
+        )
+      }
+    }
+
+    matrixKeys.push(matrixKey)
+    const stringValue = (validatedArray as string[]).join(os.EOL)
+
+    if (hasLiquidSyntax(stringValue)) {
+      let substitutedValue
+      try {
+        substitutedValue = await performSubstitutions({
+          input: stringValue,
+          engine,
+          substitutionsVariables,
+          log,
+        })
+      } catch (error) {
+        const message =
+          getErrorMessage(error) +
+          ` in ${templateType} "${templateName}" ` +
+          `matrix substitution`
+        throw new ConfigurationError(message)
+      }
+
+      // Split back into array, removing trailing newline if present
+      matrixValues.push(
+        substitutedValue.replace(new RegExp(os.EOL + '$'), '').split(os.EOL)
+      )
+    } else {
+      // Type assertion safe here after validation
+      matrixValues.push(validatedArray as string[])
+    }
+  }
+
+  return { matrixKeys, matrixValues }
+}
+
+// ----------------------------------------------------------------------------