@xpack/xpm-lib 3.0.0

package/src/lib/liquid-build-configurations.ts

@@ -0,0 +1,410 @@
+/*
+ * 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.
+ */
+
+/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */
+
+// ----------------------------------------------------------------------------
+
+import assert from 'node:assert'
+import path from 'node:path'
+
+import { Logger } from '@xpack/logger'
+
+import { XpmLiquidEngine } from './liquid-engine.js'
+import {
+  XpmLiquidSubstitutionsVariables,
+  XpmLiquidSubstitutionsStrings,
+} from './substitutions-variables.js'
+import { buildFolderRelativePathPropertyName } from './liquid-package.js'
+import {
+  JsonBuildConfiguration,
+  JsonBuildConfigurations,
+  JsonDependencies,
+} from './types.js'
+import { performSubstitutions } from './functions/perform-substitutions.js'
+import { XpmLiquidActions } from './liquid-actions.js'
+import { isString } from './functions/utils.js'
+import { filterPath } from './functions/utils.js'
+
+// ----------------------------------------------------------------------------
+
+// A collection of build configurations.
+export class XpmLiquidBuildConfigurations {
+  // --------------------------------------------------------------------------
+  // Members.
+
+  readonly log: Logger
+  readonly engine: XpmLiquidEngine
+  readonly substitutionsVariables: XpmLiquidSubstitutionsVariables
+  readonly jsonBuildConfigurations: JsonBuildConfigurations
+
+  readonly #buildConfigurationsMap: Map<
+    string,
+    XpmLiquidBuildConfiguration | undefined
+  >
+  readonly #jsonBuildConfigurationsNamesMap: Map<string, string>
+
+  #isInitialised = false
+
+  // --------------------------------------------------------------------------
+  // Constructor and async initialiser.
+
+  constructor({
+    log,
+    engine,
+    substitutionsVariables,
+    jsonBuildConfigurations,
+  }: {
+    log: Logger
+    engine: XpmLiquidEngine
+    substitutionsVariables: XpmLiquidSubstitutionsVariables
+    jsonBuildConfigurations: JsonBuildConfigurations | undefined
+  }) {
+    log.trace(`${XpmLiquidBuildConfigurations.name}()`)
+
+    this.log = log
+    this.engine = engine
+    this.substitutionsVariables = substitutionsVariables
+    this.jsonBuildConfigurations = jsonBuildConfigurations ?? {}
+
+    // Possibly empty if there are no build configurations.
+    this.#buildConfigurationsMap = new Map<
+      string,
+      XpmLiquidBuildConfiguration | undefined
+    >()
+    this.#jsonBuildConfigurationsNamesMap = new Map<string, string>()
+    // log.trace('substitutionsVariables => ', this.substitutionsVariables)
+  }
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async initialise(): Promise<void> {
+    if (this.#isInitialised) {
+      return
+    }
+
+    for (const buildConfigurationName of Object.keys(
+      this.jsonBuildConfigurations
+    )) {
+      if (buildConfigurationName.includes('{{')) {
+        // TODO: expand templates and generate multiple build configurations.
+      } else {
+        this.#buildConfigurationsMap.set(buildConfigurationName, undefined)
+        this.#jsonBuildConfigurationsNamesMap.set(
+          buildConfigurationName,
+          buildConfigurationName
+        )
+      }
+    }
+
+    this.log.trace(
+      `${XpmLiquidBuildConfigurations.name}.initialise() =>`,
+      Array.from(this.#buildConfigurationsMap.keys())
+    )
+
+    this.#isInitialised = true
+  }
+
+  // --------------------------------------------------------------------------
+  // Methods.
+
+  empty(): boolean {
+    return this.#buildConfigurationsMap.size === 0
+  }
+
+  names(): string[] {
+    const buildConfigurationsNames = Array.from(
+      this.#buildConfigurationsMap.keys()
+    )
+
+    this.log.trace(
+      `${XpmLiquidBuildConfigurations.name}.names() =>`,
+      buildConfigurationsNames
+    )
+    return buildConfigurationsNames
+  }
+
+  hasJson(buildConfigurationName: string): boolean {
+    return this.#jsonBuildConfigurationsNamesMap.has(buildConfigurationName)
+  }
+
+  getJson(buildConfigurationName: string): JsonBuildConfiguration {
+    return this.jsonBuildConfigurations[
+      this.getJsonName(buildConfigurationName)
+    ]
+  }
+
+  isHidden(buildConfigurationName: string): boolean {
+    return (
+      this.jsonBuildConfigurations[this.getJsonName(buildConfigurationName)]
+        .hidden ?? false
+    )
+  }
+
+  has(buildConfigurationName: string): boolean {
+    return this.#buildConfigurationsMap.has(buildConfigurationName)
+  }
+
+  async get(
+    buildConfigurationName: string
+  ): Promise<XpmLiquidBuildConfiguration> {
+    let buildConfiguration = this.#buildConfigurationsMap.get(
+      buildConfigurationName
+    )
+    if (buildConfiguration === undefined) {
+      const jsonBuildConfigurationName: string =
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        this.#jsonBuildConfigurationsNamesMap.get(buildConfigurationName)!
+
+      buildConfiguration = new XpmLiquidBuildConfiguration({
+        buildConfigurationName,
+        jsonBuildConfigurationName,
+        parentBuildConfigurations: this,
+      })
+      await buildConfiguration.initialise()
+      this.#buildConfigurationsMap.set(
+        buildConfigurationName,
+        buildConfiguration
+      )
+    }
+
+    return buildConfiguration
+  }
+
+  getJsonName(buildConfigurationName: string): string {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    return this.#jsonBuildConfigurationsNamesMap.get(buildConfigurationName)!
+  }
+}
+
+// ----------------------------------------------------------------------------
+
+// An individual build configuration.
+export class XpmLiquidBuildConfiguration {
+  // --------------------------------------------------------------------------
+  // Members.
+
+  readonly hidden: boolean
+
+  // The actual (un-substituted) name from package.json.
+  readonly jsonBuildConfigurationName: string
+  // Points to the actual buildConfiguration in package.json.
+  readonly jsonBuildConfiguration: JsonBuildConfiguration
+
+  substitutionsVariables: XpmLiquidSubstitutionsVariables
+
+  properties: XpmLiquidSubstitutionsStrings = {}
+
+  jsonDependencies: JsonDependencies = {}
+  jsonDevDependencies: JsonDependencies = {}
+
+  // For templates, the actual values.
+  matrixParameters?: XpmLiquidSubstitutionsStrings
+
+  // The name after performing the substitutions.
+  readonly #buildConfigurationName: string
+
+  readonly #parentBuildConfigurations: XpmLiquidBuildConfigurations
+
+  #actions: XpmLiquidActions | undefined
+
+  #buildFolderRelativePath?: string
+
+  #isInitialised = false
+
+  // --------------------------------------------------------------------------
+  // Constructor and async initialiser.
+
+  constructor({
+    buildConfigurationName, // The Liquid-processed name.
+    jsonBuildConfigurationName, // The raw name from package.json.
+    parentBuildConfigurations,
+  }: {
+    buildConfigurationName: string
+    jsonBuildConfigurationName: string
+    parentBuildConfigurations: XpmLiquidBuildConfigurations
+  }) {
+    parentBuildConfigurations.log.trace(
+      `${XpmLiquidBuildConfiguration.name}(${buildConfigurationName})`
+    )
+
+    this.#buildConfigurationName = buildConfigurationName
+    this.jsonBuildConfigurationName = jsonBuildConfigurationName
+    this.#parentBuildConfigurations = parentBuildConfigurations
+
+    this.jsonBuildConfiguration =
+      parentBuildConfigurations.jsonBuildConfigurations[
+        jsonBuildConfigurationName
+      ] ?? {}
+
+    this.substitutionsVariables = {
+      ...this.#parentBuildConfigurations.substitutionsVariables,
+    }
+
+    this.hidden = this.jsonBuildConfiguration.hidden ?? false
+
+    // The rest of the initialisation is done in the async initialiser.
+  }
+
+  async initialise(): Promise<void> {
+    if (this.#isInitialised) {
+      return
+    }
+
+    const log = this.#parentBuildConfigurations.log
+    const jsonBuildConfiguration = this.jsonBuildConfiguration
+
+    // TODO: add matrixParameters
+
+    // Process both the new 'inherits' and the deprecated 'inherit'.
+    let inherits: string[] = []
+    if (isString(jsonBuildConfiguration.inherits)) {
+      inherits = [jsonBuildConfiguration.inherits]
+    } else if (Array.isArray(jsonBuildConfiguration.inherits)) {
+      inherits = jsonBuildConfiguration.inherit as string[]
+    } else if (isString(jsonBuildConfiguration.inherit)) {
+      inherits = [jsonBuildConfiguration.inherit]
+    } else if (Array.isArray(jsonBuildConfiguration.inherit)) {
+      inherits = jsonBuildConfiguration.inherit as string[]
+    }
+
+    // Add inherited configuration properties.
+    // TODO: detect circular references.
+    for (const inheritedBuildConfigurationName of inherits) {
+      if (
+        this.#parentBuildConfigurations.hasJson(inheritedBuildConfigurationName)
+      ) {
+        const inheritedBuildConfiguration =
+          await this.#parentBuildConfigurations.get(
+            inheritedBuildConfigurationName
+          )
+
+        this.properties = {
+          ...this.properties,
+          ...inheritedBuildConfiguration.properties,
+        }
+
+        this.jsonDependencies = {
+          ...this.jsonDependencies,
+          ...inheritedBuildConfiguration.jsonDependencies,
+        }
+        this.jsonDevDependencies = {
+          ...this.jsonDevDependencies,
+          ...inheritedBuildConfiguration.jsonDevDependencies,
+        }
+      } else {
+        log.warn(
+          'buildConfiguration',
+          this.#buildConfigurationName,
+          'inherits from missing',
+          inheritedBuildConfigurationName,
+          '(ignored)'
+        )
+      }
+    }
+
+    this.properties = {
+      ...this.properties,
+      ...jsonBuildConfiguration.properties,
+    }
+
+    this.jsonDependencies = {
+      ...this.jsonDependencies,
+      ...jsonBuildConfiguration.dependencies,
+    }
+    this.jsonDevDependencies = {
+      ...this.jsonDevDependencies,
+      ...jsonBuildConfiguration.devDependencies,
+    }
+
+    this.substitutionsVariables = {
+      ...this.#parentBuildConfigurations.substitutionsVariables,
+      properties: {
+        ...this.substitutionsVariables.properties,
+        ...this.properties,
+      },
+      configuration: {
+        ...jsonBuildConfiguration,
+        name: this.#buildConfigurationName,
+      },
+    }
+
+    // Add the buildFolderRelativePath property.
+    // Note: the async initialiser was needed due to this async operation.
+    const properties = this.substitutionsVariables.properties
+    properties.buildFolderRelativePath = await this.getBuildFolderRelativePath()
+
+    // Please note that substitutionsVariables is not fully set at this point;
+    // it will be in the async initialiser after the constructor returns.
+    this.#actions = new XpmLiquidActions({
+      log: this.#parentBuildConfigurations.log,
+      engine: this.#parentBuildConfigurations.engine,
+      substitutionsVariables: this.substitutionsVariables,
+      jsonActions: this.jsonBuildConfiguration.actions,
+    })
+    // Note: this must be done manually by the application.
+    // await this.#actions.initialise()
+
+    log.trace(
+      `${XpmLiquidBuildConfiguration.name}.initialise() =>`,
+      this.#buildConfigurationName
+    )
+    log.trace('properties => ', this.properties)
+    log.trace('dependencies => ', this.jsonDependencies)
+    log.trace('devDependencies => ', this.jsonDevDependencies)
+    // log.trace('substitutionsVariables => ', this.substitutionsVariables)
+
+    this.#isInitialised = true
+  }
+
+  // --------------------------------------------------------------------------
+  // Methods.
+
+  get actions(): XpmLiquidActions {
+    assert(this.#actions !== undefined)
+    return this.#actions
+  }
+
+  async getBuildFolderRelativePath(): Promise<string> {
+    this.#buildFolderRelativePath ??= await this.#getBuildFolderRelativePath()
+    return this.#buildFolderRelativePath
+  }
+
+  async #getBuildFolderRelativePath(): Promise<string> {
+    const log = this.#parentBuildConfigurations.log
+
+    let folderPath: string
+    if (
+      buildFolderRelativePathPropertyName in
+      this.substitutionsVariables.properties
+    ) {
+      folderPath = this.substitutionsVariables.properties[
+        buildFolderRelativePathPropertyName
+      ] as string
+      if (folderPath !== '') {
+        try {
+          return await performSubstitutions({
+            log,
+            engine: this.#parentBuildConfigurations.engine,
+            input: folderPath,
+            substitutionsVariables: this.substitutionsVariables,
+          })
+        } catch (err) {
+          log.trace(err)
+        }
+      }
+    }
+
+    // Provide a default value, based on the name.
+    return path.join('build', filterPath(this.#buildConfigurationName))
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/lib/liquid-drop.ts

@@ -0,0 +1,99 @@
+/*
+ * 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.
+ */
+
+/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */
+
+// ----------------------------------------------------------------------------
+
+// https://www.npmjs.com/package/liquidjs
+import { Liquid, Context, Drop } from 'liquidjs'
+
+// https://www.npmjs.com/package/@xpack/logger
+import { Logger } from '@xpack/logger'
+
+import { XpmLiquidSubstitutionsStrings } from './substitutions-variables.js'
+
+// ----------------------------------------------------------------------------
+
+// https://liquidjs.com/
+
+export class XpmLiquidPropertiesDrop extends Drop {
+  // --------------------------------------------------------------------------
+  // Members.
+
+  readonly #log: Logger
+  readonly #properties: XpmLiquidSubstitutionsStrings
+  readonly #engine: Liquid
+
+  // --------------------------------------------------------------------------
+  // Constructor.
+
+  constructor({
+    log,
+    engine,
+    properties,
+  }: {
+    log: Logger
+    engine: Liquid
+    properties: XpmLiquidSubstitutionsStrings
+  }) {
+    super()
+
+    log.trace(`${XpmLiquidPropertiesDrop.name}()`)
+
+    this.#log = log
+    this.#engine = engine
+    this.#properties = properties
+  }
+
+  // --------------------------------------------------------------------------
+  // Methods.
+
+  override async liquidMethodMissing(
+    key: string,
+    context: Context
+  ): Promise<string | string[]> {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (this.#properties[key] === undefined) {
+      throw new Error(`properties have no ${key} key`)
+    }
+
+    const log = this.#log
+
+    const value = this.#properties[key] ?? ''
+    log.trace(
+      `${XpmLiquidPropertiesDrop.name}.liquidMethodMissing('${key}') value = |`,
+      value,
+      '|'
+    )
+
+    let result: string | string[]
+
+    const valueString = Array.isArray(value) ? value.join('') : value
+    if (valueString.includes('{{') || valueString.includes('{%')) {
+      result = (await this.#engine.parseAndRender(
+        valueString,
+        context
+      )) as string
+    } else {
+      result = value
+    }
+    log.trace(
+      `${XpmLiquidPropertiesDrop.name}.liquidMethodMissing('${key}') ` +
+        `result = |`,
+      result,
+      '|'
+    )
+    return result
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/lib/liquid-engine.ts

@@ -0,0 +1,135 @@
+/*
+ * 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.
+ */
+
+/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */
+
+// ----------------------------------------------------------------------------
+
+import * as os from 'node:os'
+import * as path from 'node:path'
+import * as util from 'node:util'
+
+// https://www.npmjs.com/package/liquidjs
+import { Liquid } from 'liquidjs'
+
+// ----------------------------------------------------------------------------
+
+export class XpmLiquidEngine extends Liquid {
+  // --------------------------------------------------------------------------
+  // Members.
+
+  // --------------------------------------------------------------------------
+  // Constructor.
+
+  constructor() {
+    super({
+      strictFilters: true,
+      strictVariables: true,
+      trimTagLeft: false,
+      trimTagRight: false,
+      trimOutputLeft: false,
+      trimOutputRight: false,
+      greedy: false,
+      lenientIf: true,
+    })
+
+    // https://liquidjs.com/api/classes/liquid_.liquid.html#registerFilter
+    // https://nodejs.org/dist/latest-v16.x/docs/api/path.html
+
+    // Add the main path manipulation functions.
+    this.registerFilter('path_basename', (p: string, ...arg) =>
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      path.basename(p, ...arg)
+    )
+
+    this.registerFilter('path_dirname', (p: string) => path.dirname(p))
+
+    this.registerFilter('path_normalize', (p: string) => path.normalize(p))
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+    this.registerFilter('path_join', (p, ...args) => path.join(p, ...args))
+
+    this.registerFilter('path_relative', (from: string, to: string) =>
+      path.relative(from, to)
+    )
+
+    this.registerFilter('path_posix_basename', (p: string, ...arg) =>
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      path.posix.basename(p, ...arg)
+    )
+
+    this.registerFilter('path_posix_dirname', (p: string) =>
+      path.posix.dirname(p)
+    )
+
+    this.registerFilter('path_posix_normalize', (p: string) =>
+      path.posix.normalize(p)
+    )
+
+    this.registerFilter('path_posix_join', (p, ...args) =>
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      path.posix.join(p, ...args)
+    )
+
+    this.registerFilter('path_posix_relative', (from: string, to: string) =>
+      path.posix.relative(from, to)
+    )
+
+    this.registerFilter('path_win32_basename', (p: string, ...arg) =>
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      path.win32.basename(p, ...arg)
+    )
+
+    this.registerFilter('path_win32_dirname', (p: string) =>
+      path.win32.dirname(p)
+    )
+
+    this.registerFilter('path_win32_normalize', (p: string) =>
+      path.win32.normalize(p)
+    )
+
+    this.registerFilter('path_win32_join', (p, ...args) =>
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      path.win32.join(p, ...args)
+    )
+
+    this.registerFilter('path_win32_relative', (from: string, to: string) =>
+      path.win32.relative(from, to)
+    )
+
+    // https://nodejs.org/dist/latest-v16.x/docs/api/util.html
+
+    this.registerFilter('util_format', (format, ...args) => {
+      // console.log([...args])
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      return util.format(format, ...args)
+    })
+
+    // Custom action.
+    this.registerFilter(
+      'to_filename',
+      // Replace non alphanumeric chars with dashes to make the paths
+      // comply with filesystem names.
+      (input: string): string => {
+        /* c8 ignore start */ /* istanbul ignore next */
+        const fixed =
+          os.platform() === 'win32'
+            ? input.replace(/[^a-zA-Z0-9\\:]+/g, '-')
+            : input.replace(/[^a-zA-Z0-9/]+/g, '-')
+        /* c8 ignore stop */
+
+        return fixed.replace(/--/g, '-')
+      }
+    )
+  }
+}
+
+// ----------------------------------------------------------------------------