@xpack/xpm-lib 3.1.2 → 4.0.0

package/src/functions/perform-substitutions.ts

@@ -0,0 +1,253 @@
+/*
+ * 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 { Context } from 'liquidjs'
+
+import { Logger } from '@xpack/logger'
+
+// ----------------------------------------------------------------------------
+
+import { LiquidEngine } from '../classes/liquid-engine.js'
+import { TemplateError } from '../classes/errors.js'
+import {
+  LiquidPropertiesDrop,
+  LiquidMatrixDrop,
+} from '../classes/liquid-drop.js'
+import {
+  LiquidSubstitutionsVariables,
+  LiquidSubstitutionsStrings,
+} from '../data/substitutions-variables.js'
+
+// ============================================================================
+
+// This limit prevents infinite loops from circular template references.
+// Chosen to be high enough for deeply nested legitimate templates
+// (typical nesting is < 10 levels) while catching pathological cases.
+// In practice, most templates resolve in 2-5 iterations.
+const PERFORM_SUBSTITUTION_MAX_ITERATIONS = 42 // Prevent infinite loops
+// This limit prevents memory exhaustion from exponentially expanding
+// templates. Set to 10MB to accommodate legitimate large outputs
+// (e.g., generated code files, documentation) whilst catching
+// pathological cases such as unbounded loops or recursive expansions.
+// Typical template outputs are a few hundred bytes.
+const PERFORM_SUBSTITUTION_MAX_OUTPUT_SIZE = 42 * 1024 // 42KB
+
+/**
+ * Performs substitutions on an input string using Liquid.
+ *
+ * @remarks
+ * This function processes Liquid template syntax (variables and tags) by
+ * repeatedly rendering the input until no more substitutions are detected.
+ * The iterative approach supports nested substitutions where one property
+ * references another.
+ *
+ * Processing workflow:
+ *
+ * <ol>
+ * <li>Skip processing for empty strings to avoid unnecessary overhead.</li>
+ * <li>Prepare Liquid context with substitution variables.</li>
+ * <li>If <code>properties</code> exist, wrap them in
+ *    <code>LiquidPropertiesDrop</code>
+ *    for lazy evaluation and nested substitution support.</li>
+ * <li>If <code>matrix</code> parameters exist, wrap them in
+ *    <code>LiquidMatrixDrop</code>
+ *    for template expansion variable access.</li>
+ * <li>Iterate while Liquid syntax (<code>\{\{</code> or <code>\{%</code>)
+ *   is present:
+ *    <ul>
+ *    <li>Parse and render the current string.</li>
+ *    <li>Break if no changes occur (safety check).</li>
+ *    <li>Continue with the substituted result.</li>
+ *    </ul>
+ * </li>
+ * <li>Return the fully substituted string.</li>
+ * </ol>
+ *
+ * The Drop pattern enables recursive property resolution: when a template
+ * accesses `{{ properties.foo }}` and `foo` contains `{{ properties.bar }}`,
+ * the next iteration resolves `bar`, and so on until no Liquid syntax
+ * remains.
+ *
+ * Error handling:
+ *
+ * Liquid rendering errors are caught, stripped of line
+ * number information (which can be misleading for nested templates), and
+ * re-thrown as {@link ConfigurationError}.
+ *
+ * @param log - The logger instance for output and diagnostics.
+ * @param engine - The Liquid engine used to render substitutions.
+ * @param input - The input string, possibly containing substitutions.
+ * @param substitutionsVariables - The variables available for substitution.
+ * @param maxIterations - Optional maximum number of substitution iterations
+ * to prevent infinite loops from circular references. Defaults to 420.
+ * @param maxOutputSize - Optional maximum output size in bytes to prevent
+ * memory exhaustion from exponentially expanding templates. Defaults to 43008
+ * bytes (42KB).
+ * @returns The fully substituted string.
+ *
+ * @throws {@link TemplateError}
+ * If Liquid rendering fails, iteration limit is exceeded, or output size
+ * limit is exceeded.
+ */
+export async function performSubstitutions({
+  engine,
+  input,
+  substitutionsVariables,
+  log,
+  maxIterations = PERFORM_SUBSTITUTION_MAX_ITERATIONS,
+  maxOutputSize = PERFORM_SUBSTITUTION_MAX_OUTPUT_SIZE,
+}: {
+  engine: LiquidEngine
+  input: string
+  substitutionsVariables: LiquidSubstitutionsVariables
+  log: Logger
+  maxIterations?: number
+  maxOutputSize?: number
+}): Promise<string> {
+  assert(engine, 'engine is required')
+  assert(substitutionsVariables, 'substitutionsVariables is required')
+  assert(log, 'log is required')
+  assert(maxIterations > 0, 'maxIterations must be a positive integer')
+  assert(maxOutputSize > 0, 'maxOutputSize must be a positive integer')
+
+  if (input.trim() === '') {
+    // Spare it the trouble for empty strings.
+    return input
+  }
+
+  // Wrap properties into a liquid drop (a mechanism to process
+  // substitutions immediately).
+  let properties: LiquidSubstitutionsStrings | LiquidPropertiesDrop =
+    substitutionsVariables.properties
+  let matrix: LiquidSubstitutionsStrings | LiquidMatrixDrop | undefined =
+    substitutionsVariables.matrix
+
+  if (Object.keys(substitutionsVariables.properties).length > 0) {
+    properties = new LiquidPropertiesDrop({
+      log,
+      engine,
+      properties: substitutionsVariables.properties,
+    })
+  }
+  if (
+    substitutionsVariables.matrix &&
+    Object.keys(substitutionsVariables.matrix).length > 0
+  ) {
+    matrix = new LiquidMatrixDrop({
+      log,
+      engine,
+      matrix: substitutionsVariables.matrix,
+    })
+  }
+
+  // Passing the engine options is important, otherwise unknown
+  // variables do not trigger exceptions.
+  const context = new Context(
+    {
+      ...substitutionsVariables,
+      properties,
+      matrix,
+    },
+    engine.options,
+    { sync: false }
+  )
+
+  log.trace(`performSubstitutions('${input}')`)
+
+  let current: string = input
+  let substituted: string = current
+  let count = 0
+  const LIQUID_SYNTAX_REGEX = /\{\{|\{%/
+
+  // Iterate until all substitutions are done.
+  while (LIQUID_SYNTAX_REGEX.test(current)) {
+    // Safety net: This limit prevents infinite loops from circular template
+    // references. In normal operation, templates resolve in a few iterations.
+    // The check is unlikely to trigger because:
+    // 1. Templates are validated during configuration loading
+    // 2. Liquid engine throws errors for most invalid references
+    // 3. The break below catches non-changing substitutions
+    // However, this protects against edge cases like deeply nested context
+    // references or malformed template logic that the engine doesn't catch.
+    /* c8 ignore start - safety net, normally should not get there. */
+    if (++count > maxIterations) {
+      throw new TemplateError(
+        `Substitution limit exceeded ` +
+          `(${String(maxIterations)} iterations). ` +
+          `Possible circular reference in template.`
+      )
+    }
+    /* c8 ignore stop */
+    // May throw.
+    try {
+      substituted = (await engine.parseAndRender(current, context)) as string
+
+      /* c8 ignore start - safety net. */
+      if (substituted.length > maxOutputSize) {
+        throw new TemplateError(
+          `Template expansion exceeded size limit ` +
+            `(${String(maxOutputSize)} bytes). ` +
+            `Output was ${String(substituted.length)} bytes.`
+        )
+      } /* c8 ignore stop */
+
+      // Safety net: This check detects when a substitution pass produces no
+      // changes despite template markers being present. This is unlikely
+      // because:
+      // 1. The while condition checks for markers ({{ or {%)
+      // 2. Liquid engine normally processes all markers or throws errors
+      // 3. Valid markers always resolve to something (even empty string)
+      // However, this catches edge cases like malformed markers that pass the
+      // simple includes() check but don't match Liquid's parser, preventing
+      // infinite loops when the iteration limit isn't reached.
+      /* c8 ignore start - safety net, normally errors throw. */
+      if (substituted === current) {
+        log.warn(
+          `performSubstitutions() step ${String(count)} => (`,
+          substituted,
+          ') did not change'
+        )
+
+        break
+      } /* c8 ignore stop */
+    } catch (error) {
+      if (error instanceof Error) {
+        log.trace(`Liquid error: ${error.message}`)
+        const cleanMessage = error.message.replace(/, line:.*/g, '')
+        throw new TemplateError(cleanMessage)
+        // Safety net: This handles the unlikely case where something other than
+        // an Error is thrown. JavaScript/TypeScript allows throwing any value,
+        // but Liquid engine and Node.js fs operations consistently throw Error
+        // instances. This provides robust error handling for unexpected
+        // scenarios.
+        /* c8 ignore start - safety net, currently all are Errors */
+      } else {
+        throw new TemplateError(String(error))
+      }
+      /* c8 ignore stop */
+    }
+
+    log.trace(
+      `performSubstitutions() step ${String(count)} => (`,
+      substituted,
+      ')'
+    )
+    current = substituted
+  }
+
+  return substituted
+}
+
+// ----------------------------------------------------------------------------

package/src/functions/utils.ts

@@ -0,0 +1,151 @@
+/*
+ * 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'
+
+// ============================================================================
+
+/**
+ * Extracts an error message string from an unknown error value.
+ *
+ * @remarks
+ * This utility handles error values of any type, extracting the message
+ * property from `Error` instances or converting other types to strings.
+ * Useful for consistent error reporting when the error type is unknown.
+ *
+ * TypeScript's catch clause types errors as `unknown` for safety, since
+ * JavaScript allows throwing any value (not just `Error` instances). This
+ * function provides a type-safe way to extract a message string:
+ *
+ * <ul>
+ * <li><b>For Error instances:</b> Returns the <code>message</code>
+ *    property.</li>
+ * <li><b>For other types:</b> Converts to string using <code>String()</code>,
+ *    which handles
+ *    primitives, objects with <code>toString()</code>, <code>null</code>,
+ *    and <code>undefined</code> gracefully.</li>
+ * </ul>
+ *
+ * Common usage pattern:
+ * ```typescript
+ * try {
+ *   // code that might throw
+ * } catch (error) {
+ *   const message = getErrorMessage(error);
+ *   log.error(message);
+ * }
+ * ```
+ *
+ * @param error - The error value to convert.
+ * @returns The error message string.
+ */
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message
+  }
+  return String(error)
+}
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Builds a unique key using the current platform and architecture.
+ *
+ * @remarks
+ * Generates a platform identifier string used for matching binary packages
+ * to the current system or for platform-specific configuration.
+ *
+ * Platform key format: `<platform>-<arch>`
+ *
+ * Examples:
+ *
+ * <ul>
+ * <li><code>darwin-x64</code> (macOS on Intel)</li>
+ * <li><code>darwin-arm64</code> (macOS on Apple Silicon)</li>
+ * <li><code>linux-x64</code> (Linux on 64-bit Intel/AMD)</li>
+ * <li><code>win32-x64</code> (Windows on 64-bit)</li>
+ * </ul>
+ *
+ * Architecture coercion rules (when doForce32bit is true):
+ *
+ * <ul>
+ * <li><b>x64 → ia32:</b> Coerces 64-bit Intel/AMD architecture to 32-bit
+ *    on all platforms.</li>
+ * <li><b>arm64 → arm:</b> Coerces 64-bit ARM architecture to 32-bit
+ *    on all platforms.</li>
+ * </ul>
+ *
+ * This coercion is useful for backward compatibility scenarios where only
+ * 32-bit binaries are available but can run on 64-bit systems. The
+ * platform key matches the naming conventions used in binary xPack
+ * distributions.
+ *
+ * @param doForce32bit - Whether to coerce 64-bit architectures to
+ * their 32-bit equivalents.
+ * @param platformDetector - The platform detector instance to use. Defaults
+ * to a new {@link PlatformDetector} instance.
+ * @returns The platform key in the form `platform-arch`.
+ */
+export function getPlatformKey({
+  doForce32bit = false,
+  platformDetector = new PlatformDetector(),
+}: {
+  doForce32bit?: boolean
+  platformDetector?: PlatformDetector
+} = {}): string {
+  const { platform, arch } = platformDetector.getPlatformInfo({ doForce32bit })
+  const key = `${platform}-${arch}`
+  return key
+}
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Checks whether a string contains Liquid template syntax.
+ *
+ * @remarks
+ * This utility function detects the presence of Liquid template markers
+ * in a string, indicating that the string requires template processing.
+ *
+ * Liquid syntax patterns detected:
+ *
+ * <ol>
+ * <li><b>Variable output:</b> <code>\{\{</code> marks the start of a variable
+ *    interpolation (e.g., <code>\{\{ package.name \}\}</code>).</li>
+ * <li><b>Control flow:</b> <code>\{%</code> marks the start of a tag
+ *    for logic or iteration (e.g., <code>\{% if condition %\}</code>,
+ *    <code>\{% for item in array %\}</code>).</li>
+ * </ol>
+ *
+ * The function uses a regular expression to efficiently scan the string
+ * for these markers without needing to check for both patterns separately.
+ * This is more efficient than calling <code>includes()</code> twice and
+ * provides a single point of maintenance for Liquid syntax detection logic.
+ *
+ * Common usage:
+ *
+ * <ul>
+ * <li>Determine whether to process a value through the Liquid engine.</li>
+ * <li>Skip unnecessary template evaluation for static strings.</li>
+ * <li>Validate configuration values for template content.</li>
+ * </ul>
+ *
+ * @param value - The string to check for Liquid syntax.
+ * @returns <code>true</code> if the string contains Liquid syntax markers,
+ * <code>false</code> otherwise.
+ */
+export function hasLiquidSyntax(value: string): boolean {
+  return /\{\{|\{%/.test(value)
+}
+
+// ----------------------------------------------------------------------------

package/src/index.ts

@@ -9,27 +9,80 @@
  * be obtained from https://opensource.org/license/mit.
  */
 
-/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */
+// ----------------------------------------------------------------------------
+
+/**
+ * A Node.js TypeScript module with the core code for <b>xpm</b> and
+ * <b>xpm enabled</b> projects.
+ *
+ * @remarks
+ * This library groups together various classes and functions used in common
+ * by <b>xpm</b> and the Visual Studio Code extension.
+ *
+ * The main functionality is to manage actions and build configurations,
+ * especially those defined using Liquid templates.
+ *
+ * <h3>The Lazy Evaluation Mechanism</h3>
+ *
+ * Actions ({@link Actions}) and build configurations
+ * ({@link BuildConfigurations}) implement a two-step lazy evaluation
+ * process to avoid unnecessary operations:
+ *
+ * <ol>
+ * <li><b>Name Expansion:</b> During collection initialisation, only
+ *    the matrix of
+ *    options is evaluated for each template, expanding template names into
+ *    concrete action or configuration names without processing their
+ * content.</li>
+ * <li><b>Content Evaluation:</b> Later, when an action or build
+ *    configuration is  actually accessed and initialised (via
+ *    <code>Action.initialise()</code>
+ *    or <code>BuildConfiguration.initialise()</code>), the template
+ *    is fully
+ *    evaluated and Liquid substitutions are performed.</li>
+ * </ol>
+ *
+ * This approach ensures that only items that are actually used incur the cost
+ * of template evaluation and variable substitution, significantly improving
+ * performance for projects with many actions or configurations.
+ *
+ * @packageDocumentation
+ */
+
+// ----------------------------------------------------------------------------
+
+// Public entry point for the xpm-lib TypeScript library.
+export * from './functions/chmod-recursively.js'
+export * from './functions/filter-paths.js'
+export * from './functions/is-something.js'
+export * from './functions/matrix-expander.js'
+export * from './functions/perform-substitutions.js'
+export * from './functions/utils.js'
+
+export * from './classes/errors.js'
+export * from './classes/init-template-base.js'
+export * from './classes/actions.js'
+export * from './classes/build-configurations.js'
+export * from './classes/combinations-generator.js'
+export * from './classes/liquid-drop.js'
+export * from './classes/liquid-engine.js'
+export * from './classes/data-model.js'
+export * from './classes/package.js'
+export * from './classes/platform-detector.js'
+export * from './classes/policies.js'
+export * from './classes/template-expander.js'
+
+export * from './data/substitutions-variables.js'
+
+export * from './types/json.js'
+export * from './types/xpm-init-template.js'
+export * from './types/xpm.js'
 
 // ----------------------------------------------------------------------------
 
-// Re-export all library definitions.
-export * from './lib/functions/chmod-recursive.js'
-export * from './lib/functions/perform-substitutions.js'
-export * from './lib/functions/utils.js'
-
-export * from './lib/errors.js'
-export * from './lib/init-template-base.js'
-export * from './lib/liquid-actions.js'
-export * from './lib/liquid-build-configurations.js'
-export * from './lib/liquid-drop.js'
-export * from './lib/liquid-engine.js'
-export * from './lib/liquid-package.js'
-export * from './lib/package.js'
-export * from './lib/policies.js'
-export * from './lib/substitutions-variables.js'
-export * from './lib/types.js'
-
-export * from 'liquidjs'
+// Note: liquidjs is not re-exported to avoid API Extractor conflicts.
+// Consumers should import it directly: import { Liquid } from 'liquidjs'
+// This ensures they use the same version as this library via peer dependencies.
+// export * as liquidjs from 'liquidjs'
 
 // ----------------------------------------------------------------------------