@fgv/ts-res 5.0.0-2 → 5.0.0-21

package/src/packlets/bundle/bundleBuilder.ts

@@ -0,0 +1,159 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Result, succeed, Hash } from '@fgv/ts-utils';
+import { ResourceManagerBuilder } from '../resources';
+import {
+  SystemConfiguration,
+  PredefinedSystemConfiguration,
+  getPredefinedSystemConfiguration
+} from '../config';
+import { IBundle, IBundleCreateParams, IBundleMetadata } from './model';
+import { BundleNormalizer } from './bundleNormalizer';
+
+/**
+ * Builder for creating resource bundles from a ResourceManagerBuilder.
+ * Handles the compilation, configuration extraction, and integrity verification
+ * needed to create a complete, portable bundle.
+ * @public
+ */
+export class BundleBuilder {
+  /**
+   * Creates a resource bundle from a ResourceManagerBuilder.
+   * @param builder - The ResourceManagerBuilder containing the resources to bundle
+   * @param systemConfig - The SystemConfiguration used to create the builder
+   * @param params - Optional parameters for bundle creation
+   * @returns Success with the created bundle if successful, Failure with error message otherwise
+   * @public
+   */
+  public static create(
+    builder: ResourceManagerBuilder,
+    systemConfig: SystemConfiguration,
+    params?: IBundleCreateParams
+  ): Result<IBundle> {
+    /* c8 ignore next 2 - defense in depth */
+    params = params ?? {};
+    const hashNormalizer = params.hashNormalizer ?? new Hash.Crc32Normalizer();
+
+    const builderToUse =
+      params.normalize === true
+        ? BundleNormalizer.normalize(builder, systemConfig)
+        : /* c8 ignore next 1 - is tested but coverage gets confused */
+          succeed(builder);
+
+    return builderToUse.onSuccess((targetBuilder) => {
+      return systemConfig.getConfig().onSuccess((config) => {
+        return targetBuilder.getCompiledResourceCollection().onSuccess((compiledCollection) => {
+          return BundleBuilder._generateChecksum(compiledCollection, hashNormalizer).onSuccess((checksum) => {
+            /* c8 ignore next 1 - defense in depth */
+            const dateBuilt = params.dateBuilt ?? new Date().toISOString();
+
+            const metadata: IBundleMetadata = {
+              dateBuilt,
+              checksum,
+              version: params.version,
+              description: params.description
+            };
+
+            const bundle: IBundle = {
+              metadata,
+              config,
+              compiledCollection
+            };
+
+            return succeed(bundle);
+          });
+        });
+      });
+    });
+  }
+
+  /**
+   * Creates a resource bundle from a ResourceManagerBuilder using a predefined system configuration.
+   * This is a convenience method for the common case of using predefined configurations.
+   * @param builder - The ResourceManagerBuilder containing the resources to bundle
+   * @param configName - The name of the predefined system configuration used
+   * @param params - Optional parameters for bundle creation
+   * @returns Success with the created bundle if successful, Failure with error message otherwise
+   * @public
+   */
+  public static createFromPredefined(
+    builder: ResourceManagerBuilder,
+    configName: PredefinedSystemConfiguration,
+    params?: IBundleCreateParams
+  ): Result<IBundle> {
+    /* c8 ignore next 1 */
+    params = params ?? {};
+    const hashNormalizer = params.hashNormalizer ?? new Hash.Crc32Normalizer();
+
+    // Determine which builder to use based on normalization setting
+    const builderToUse = params.normalize
+      ? BundleNormalizer.normalizeFromPredefined(builder, configName)
+      : succeed(builder);
+
+    return builderToUse.onSuccess((targetBuilder) => {
+      return getPredefinedSystemConfiguration(configName).onSuccess((systemConfig) => {
+        return systemConfig.getConfig().onSuccess((config) => {
+          return targetBuilder.getCompiledResourceCollection().onSuccess((compiledCollection) => {
+            return BundleBuilder._generateChecksum(compiledCollection, hashNormalizer).onSuccess(
+              (checksum) => {
+                /* c8 ignore next 1 - defense in depth */
+                const dateBuilt = params.dateBuilt ?? new Date().toISOString();
+
+                const metadata: IBundleMetadata = {
+                  dateBuilt,
+                  checksum,
+                  version: params.version,
+                  /* c8 ignore next 1 - defense in depth */
+                  description: params?.description
+                };
+
+                const bundle: IBundle = {
+                  metadata,
+                  config,
+                  compiledCollection
+                };
+
+                return succeed(bundle);
+              }
+            );
+          });
+        });
+      });
+    });
+  }
+
+  /**
+   * Generates a hash checksum for the compiled resource collection.
+   * The checksum is calculated using the provided hash normalizer.
+   * @param compiledCollection - The compiled resource collection to generate checksum for
+   * @param hashNormalizer - The hash normalizer to use for checksum generation
+   * @returns Success with the checksum string if successful, Failure otherwise
+   * @internal
+   */
+  private static _generateChecksum(
+    compiledCollection: unknown,
+    hashNormalizer: Hash.HashingNormalizer
+  ): Result<string> {
+    return hashNormalizer.computeHash(compiledCollection);
+  }
+}

package/src/packlets/bundle/bundleLoader.ts

@@ -0,0 +1,157 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Result, succeed, fail, Collections, Hash } from '@fgv/ts-utils';
+import { CompiledResourceCollection, IResourceManager } from '../runtime';
+import { SystemConfiguration } from '../config';
+import { ResourceType } from '../resource-types';
+import { QualifierType } from '../qualifier-types';
+import { IBundle } from './model';
+
+/**
+ * Parameters for creating a BundleLoader.
+ * @public
+ */
+export interface IBundleLoaderCreateParams {
+  /**
+   * The bundle to load.
+   */
+  bundle: IBundle;
+
+  /**
+   * Whether to skip checksum verification during loading.
+   * Default is false - checksum verification is performed.
+   */
+  skipChecksumVerification?: boolean;
+
+  /**
+   * Optional hash normalizer for verifying checksums. If not provided,
+   * a CRC32 normalizer will be used for browser compatibility.
+   * Must match the normalizer used during bundle creation.
+   */
+  hashNormalizer?: Hash.HashingNormalizer;
+}
+
+/**
+ * Loader for creating an IResourceManager from a resource bundle.
+ * Handles integrity verification and reconstruction of the runtime resource manager.
+ * @public
+ */
+export class BundleLoader {
+  /**
+   * Creates an IResourceManager from a resource bundle.
+   * @param params - Parameters for bundle loading including the bundle and options
+   * @returns Success with the IResourceManager if successful, Failure with error message otherwise
+   * @public
+   */
+  public static createManagerFromBundle(params: IBundleLoaderCreateParams): Result<IResourceManager> {
+    /* c8 ignore next 1 - defense in depth */
+    const hashNormalizer = params.hashNormalizer ?? new Hash.Crc32Normalizer();
+
+    return BundleLoader._verifyBundleIntegrity(
+      params.bundle,
+      params.skipChecksumVerification ?? false,
+      hashNormalizer
+    ).onSuccess(() => {
+      return BundleLoader._createSystemConfiguration(params.bundle).onSuccess((systemConfig) => {
+        return BundleLoader._createCompiledResourceCollection(
+          params.bundle,
+          systemConfig.qualifierTypes,
+          systemConfig.resourceTypes
+        );
+      });
+    });
+  }
+
+  /**
+   * Verifies the integrity of a bundle by checking its checksum.
+   * @param bundle - The bundle to verify
+   * @param skipVerification - Whether to skip verification
+   * @param hashNormalizer - The hash normalizer to use for verification
+   * @returns Success if verification passes or is skipped, Failure otherwise
+   * @internal
+   */
+  private static _verifyBundleIntegrity(
+    bundle: IBundle,
+    skipVerification: boolean,
+    hashNormalizer: Hash.HashingNormalizer
+  ): Result<boolean> {
+    if (skipVerification) {
+      return succeed(true);
+    }
+
+    return BundleLoader._generateChecksum(bundle.compiledCollection, hashNormalizer).onSuccess(
+      (calculatedChecksum) => {
+        if (calculatedChecksum !== bundle.metadata.checksum) {
+          return fail(
+            `Bundle integrity verification failed: expected checksum ${bundle.metadata.checksum}, got ${calculatedChecksum}`
+          );
+        }
+        return succeed(true);
+      }
+    );
+  }
+
+  /**
+   * Generates a hash checksum for the compiled resource collection.
+   * @param compiledCollection - The compiled resource collection to generate checksum for
+   * @param hashNormalizer - The hash normalizer to use for checksum generation
+   * @returns Success with the checksum string if successful, Failure otherwise
+   * @internal
+   */
+  private static _generateChecksum(
+    compiledCollection: unknown,
+    hashNormalizer: Hash.HashingNormalizer
+  ): Result<string> {
+    return hashNormalizer.computeHash(compiledCollection);
+  }
+
+  /**
+   * Creates a SystemConfiguration from the bundle's configuration.
+   * @param bundle - The bundle containing the configuration
+   * @returns Success with the SystemConfiguration if successful, Failure otherwise
+   * @internal
+   */
+  private static _createSystemConfiguration(bundle: IBundle): Result<SystemConfiguration> {
+    return SystemConfiguration.create(bundle.config);
+  }
+
+  /**
+   * Creates a CompiledResourceCollection from the bundle.
+   * @param bundle - The bundle to load
+   * @param qualifierTypes - The qualifier type collector from the system configuration
+   * @param resourceTypes - The resource type collector from the system configuration
+   * @returns Success with the CompiledResourceCollection if successful, Failure otherwise
+   * @internal
+   */
+  private static _createCompiledResourceCollection(
+    bundle: IBundle,
+    qualifierTypes: Collections.IReadOnlyResultMap<string, QualifierType>,
+    resourceTypes: Collections.IReadOnlyResultMap<string, ResourceType>
+  ): Result<CompiledResourceCollection> {
+    return CompiledResourceCollection.create({
+      compiledCollection: bundle.compiledCollection,
+      qualifierTypes,
+      resourceTypes
+    });
+  }
+}

package/src/packlets/bundle/bundleNormalizer.ts

@@ -0,0 +1,173 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Result, succeed, MessageAggregator } from '@fgv/ts-utils';
+import { ResourceManagerBuilder } from '../resources';
+import { ResourceCandidate } from '../resources';
+import { SystemConfiguration, PredefinedSystemConfiguration } from '../config';
+import { Condition, ConditionSet } from '../conditions';
+
+/**
+ * Normalizes ResourceManagerBuilder instances to ensure consistent ordering
+ * of internal entities, enabling order-independent bundle checksums.
+ *
+ * The normalization process rebuilds the ResourceManagerBuilder from the ground up
+ * in a canonical order to ensure identical index assignments regardless of
+ * original construction order.
+ * @public
+ */
+export class BundleNormalizer {
+  /**
+   * Creates a normalized ResourceManagerBuilder from an existing builder.
+   * The normalized builder will have identical entities but arranged in
+   * canonical order to ensure consistent index assignments.
+   *
+   * @param originalBuilder - The ResourceManagerBuilder to normalize
+   * @param systemConfig - The SystemConfiguration used to create the original builder
+   * @returns Success with the normalized ResourceManagerBuilder if successful, Failure otherwise
+   */
+  public static normalize(
+    originalBuilder: ResourceManagerBuilder,
+    systemConfig: SystemConfiguration
+  ): Result<ResourceManagerBuilder> {
+    // Create a fresh builder using the same system configuration
+    return ResourceManagerBuilder.create({
+      qualifiers: systemConfig.qualifiers,
+      resourceTypes: systemConfig.resourceTypes
+    }).onSuccess((normalizedBuilder) => {
+      return BundleNormalizer._addNormalizedResources(originalBuilder, normalizedBuilder).onSuccess(() =>
+        succeed(normalizedBuilder)
+      );
+    });
+  }
+
+  /**
+   * Creates a normalized ResourceManagerBuilder using a predefined system configuration.
+   * This is a convenience method for the common case of using predefined configurations.
+   *
+   * @param originalBuilder - The ResourceManagerBuilder to normalize
+   * @param configName - The name of the predefined system configuration used
+   * @returns Success with the normalized ResourceManagerBuilder if successful, Failure otherwise
+   */
+  public static normalizeFromPredefined(
+    originalBuilder: ResourceManagerBuilder,
+    configName: PredefinedSystemConfiguration
+  ): Result<ResourceManagerBuilder> {
+    return ResourceManagerBuilder.createPredefined(configName).onSuccess((normalizedBuilder) => {
+      return BundleNormalizer._addNormalizedResources(originalBuilder, normalizedBuilder).onSuccess(() =>
+        succeed(normalizedBuilder)
+      );
+    });
+  }
+
+  /**
+   * Normalizes all conditions from the original builder by adding them to the
+   * normalized builder in sorted order using loose condition declarations.
+   *
+   * @param originalBuilder - The source ResourceManagerBuilder
+   * @param normalizedBuilder - The target normalized ResourceManagerBuilder
+   * @returns Success if all conditions were normalized successfully, Failure otherwise
+   * @internal
+   */
+  private static _normalizeConditions(
+    originalBuilder: ResourceManagerBuilder,
+    normalizedBuilder: ResourceManagerBuilder
+  ): Result<boolean> {
+    const conditions = Array.from(originalBuilder.conditions.values()).sort(Condition.compare);
+
+    const errors = new MessageAggregator();
+    for (const condition of conditions) {
+      const looseDecl = condition.toLooseConditionDecl();
+      normalizedBuilder.addCondition(looseDecl).aggregateError(errors);
+    }
+
+    return errors.returnOrReport(succeed(true));
+  }
+
+  /**
+   * Normalizes all condition sets from the original builder by adding them to the
+   * normalized builder in sorted order using loose condition set declarations.
+   *
+   * @param originalBuilder - The source ResourceManagerBuilder
+   * @param normalizedBuilder - The target normalized ResourceManagerBuilder
+   * @returns Success if all condition sets were normalized successfully, Failure otherwise
+   * @internal
+   */
+  private static _normalizeConditionSets(
+    originalBuilder: ResourceManagerBuilder,
+    normalizedBuilder: ResourceManagerBuilder
+  ): Result<boolean> {
+    const conditionSets = Array.from(originalBuilder.conditionSets.values()).sort(ConditionSet.compare);
+
+    const errors = new MessageAggregator();
+    for (const conditionSet of conditionSets) {
+      const conditions = conditionSet.toConditionSetArrayDecl();
+      normalizedBuilder.addConditionSet(conditions).aggregateError(errors);
+    }
+
+    return errors.returnOrReport(succeed(true));
+  }
+
+  /**
+   * Normalizes all candidates by sorting them first by resource ID, then by condition set.
+   *
+   * @param originalBuilder - The source ResourceManagerBuilder
+   * @param normalizedBuilder - The target normalized ResourceManagerBuilder
+   * @returns Success if all candidates were normalized successfully, Failure otherwise
+   * @internal
+   */
+  private static _normalizeCandidates(
+    originalBuilder: ResourceManagerBuilder,
+    normalizedBuilder: ResourceManagerBuilder
+  ): Result<boolean> {
+    const candidates = Array.from(originalBuilder.getAllCandidates()).sort((c1, c2) => {
+      const idCompare = c1.id.localeCompare(c2.id);
+      return idCompare !== 0 ? idCompare : ResourceCandidate.compare(c1, c2);
+    });
+
+    const errors = new MessageAggregator();
+    for (const candidate of candidates) {
+      const decl = candidate.toLooseResourceCandidateDecl();
+      normalizedBuilder.addLooseCandidate(decl).aggregateError(errors);
+    }
+
+    return errors.returnOrReport(succeed(true));
+  }
+
+  /**
+   * Adds normalized resources to the target builder by first normalizing conditions,
+   * then condition sets, then candidates.
+   *
+   * @param originalBuilder - The source ResourceManagerBuilder
+   * @param normalizedBuilder - The target normalized ResourceManagerBuilder
+   * @returns Success if all resources were added successfully, Failure otherwise
+   * @internal
+   */
+  private static _addNormalizedResources(
+    originalBuilder: ResourceManagerBuilder,
+    normalizedBuilder: ResourceManagerBuilder
+  ): Result<boolean> {
+    return BundleNormalizer._normalizeConditions(originalBuilder, normalizedBuilder)
+      .onSuccess(() => BundleNormalizer._normalizeConditionSets(originalBuilder, normalizedBuilder))
+      .onSuccess(() => BundleNormalizer._normalizeCandidates(originalBuilder, normalizedBuilder));
+  }
+}

package/src/packlets/bundle/bundleUtils.ts

@@ -0,0 +1,142 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Result, succeed, fail } from '@fgv/ts-utils';
+import { SystemConfiguration } from '../config';
+import { Compiled as ResourceJsonCompiled } from '../resource-json';
+import { IBundleMetadata } from './model';
+import { bundle as bundleConverter } from './convert';
+
+/**
+ * Components extracted from a bundle for reuse in different contexts.
+ * @public
+ */
+export interface IBundleComponents {
+  /**
+   * The system configuration from the bundle.
+   */
+  systemConfiguration: SystemConfiguration;
+
+  /**
+   * The compiled resource collection from the bundle.
+   */
+  compiledCollection: ResourceJsonCompiled.ICompiledResourceCollection;
+
+  /**
+   * The bundle metadata including build information.
+   */
+  metadata: IBundleMetadata;
+}
+
+/**
+ * Utility functions for working with resource bundles.
+ * Provides reusable logic for bundle detection, parsing, and component extraction.
+ * @public
+ */
+export class BundleUtils {
+  /**
+   * Checks if the given object appears to be a bundle file by examining its structure.
+   * This is a lightweight check that doesn't perform full validation.
+   * @param data - The data to check
+   * @returns True if the data appears to be a bundle structure
+   * @public
+   */
+  public static isBundleFile(data: unknown): boolean {
+    return bundleConverter.convert(data).isSuccess();
+  }
+
+  /**
+   * Extracts and validates components from a bundle for reuse.
+   * Performs full validation of the bundle structure and creates typed components.
+   * @param bundleData - The raw bundle data to extract components from
+   * @returns Success with bundle components if valid, Failure with error message otherwise
+   * @public
+   */
+  public static extractBundleComponents(bundleData: unknown): Result<IBundleComponents> {
+    return bundleConverter
+      .convert(bundleData)
+      .withErrorFormat((err) => `Invalid bundle structure: ${err}`)
+      .onSuccess((bundle) => {
+        return SystemConfiguration.create(bundle.config)
+          .withErrorFormat((err) => `Invalid system configuration in bundle: ${err}`)
+          .onSuccess((systemConfiguration) => {
+            return succeed({
+              systemConfiguration,
+              compiledCollection: bundle.compiledCollection,
+              metadata: bundle.metadata
+            });
+          });
+      });
+  }
+
+  /**
+   * Extracts just the metadata from potential bundle data without full validation.
+   * Useful for displaying bundle information without processing the entire bundle.
+   * @param data - The data to extract metadata from
+   * @returns Success with metadata if found and valid, Failure otherwise
+   * @public
+   */
+  public static extractBundleMetadata(data: unknown): Result<IBundleMetadata> {
+    return bundleConverter
+      .convert(data)
+      .onSuccess((bundle) => {
+        return succeed(bundle.metadata);
+      })
+      .withErrorFormat((err) => {
+        return `Not a bundle file: ${err}`;
+      });
+  }
+
+  /**
+   * Parses bundle data from a JSON string.
+   * Convenience method that combines JSON parsing with bundle component extraction.
+   * @param jsonString - The JSON string containing bundle data
+   * @returns Success with bundle components if valid, Failure with error message otherwise
+   * @public
+   */
+  public static parseBundleFromJson(jsonString: string): Result<IBundleComponents> {
+    try {
+      const data = JSON.parse(jsonString);
+      return BundleUtils.extractBundleComponents(data);
+    } catch (error) {
+      /* c8 ignore next 1 - defense in depth */
+      return fail(`Failed to parse JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Checks if a file name suggests it might be a bundle file.
+   * This is a heuristic check based on file naming conventions.
+   * @param fileName - The file name to check
+   * @returns True if the file name suggests a bundle file
+   * @public
+   */
+  public static isBundleFileName(fileName: string): boolean {
+    const lowerName = fileName.toLowerCase();
+    return (
+      lowerName.endsWith('.bundle.json') ||
+      lowerName.endsWith('-bundle.json') ||
+      lowerName.endsWith('_bundle.json') ||
+      (lowerName.includes('bundle') && lowerName.endsWith('.json'))
+    );
+  }
+}