Bundle System

/**
 * Core bundle interface representing a collection of assets
 */
interface Bundle {
  /** Unique bundle identifier */
  readonly id: string;
  /** Bundle content type (e.g., 'js', 'css', 'html') */
  readonly type: string;
  /** Target environment for this bundle */
  readonly env: Environment;
  /** Build target configuration */
  readonly target: Target;
  /** Whether this bundle needs a stable name across builds */
  readonly needsStableName: ?boolean;
  /** Bundle loading behavior */
  readonly bundleBehavior: ?BundleBehavior;
  /** Whether this bundle can be split into smaller bundles */
  readonly isSplittable: ?boolean;
  /** Hash reference placeholder for the bundle content */
  readonly hashReference: string;
  
  /** Get all entry assets for this bundle */
  getEntryAssets(): Array<Asset>;
  /** Get the main entry asset */
  getMainEntry(): ?Asset;
  /** Check if bundle contains a specific asset */
  hasAsset(asset: Asset): boolean;
  /** Check if bundle contains a specific dependency */
  hasDependency(dependency: Dependency): boolean;
  /** Traverse all assets in the bundle */
  traverseAssets<TContext>(
    visit: GraphVisitor<Asset, TContext>, 
    startAsset?: Asset
  ): ?TContext;
  /** Traverse assets and dependencies in the bundle */
  traverse<TContext>(visit: GraphVisitor<BundleTraversable, TContext>): ?TContext;
  /** Get content hash for the bundle */
  getContentHash(): string;
}

/**
 * Bundle with naming information
 */
interface NamedBundle extends Bundle {
  /** Public bundle identifier */
  readonly publicId: string;
  /** Bundle file name */
  readonly name: string;
  /** Display name for reporting */
  readonly displayName: string;
}

/**
 * Final packaged bundle with file information
 */
interface PackagedBundle extends NamedBundle {
  /** File path of the packaged bundle */
  readonly filePath: FilePath;
  /** Bundle file statistics */
  readonly stats: Stats;
}

/**
 * Bundle graph interface for querying bundle relationships
 */
interface BundleGraph<TBundle: Bundle = Bundle> {
  /** Get all bundles in the graph */
  getBundles(): Array<TBundle>;
  /** Get child bundles (async dependencies) */
  getChildBundles(bundle: TBundle): Array<TBundle>;
  /** Get sibling bundles (same bundle group) */
  getSiblingBundles(bundle: TBundle): Array<TBundle>;
  /** Get bundles that contain a specific asset */
  getBundlesWithAsset(asset: Asset): Array<TBundle>;
  /** Get bundles that depend on a specific bundle */
  getParentBundles(bundle: TBundle): Array<TBundle>;
  
  /** Resolve async dependency to bundle and asset */
  resolveAsyncDependency(
    dependency: Dependency, 
    bundle: ?TBundle
  ): ?{bundle: TBundle, asset: Asset};
  
  /** Get dependency resolution between bundles */
  getDependencyResolution(
    dependency: Dependency, 
    bundle: ?TBundle
  ): ?{bundleGraph: BundleGraph<TBundle>, bundle: ?TBundle, asset: Asset};
  
  /** Get referenced bundles from a bundle */
  getReferencedBundles(bundle: TBundle): Array<TBundle>;
  
  /** Traverse bundles in the graph */
  traverseBundles<TContext>(
    visit: GraphVisitor<TBundle, TContext>,
    startBundle?: TBundle
  ): ?TContext;
  
  /** Get asset by ID */
  getAssetById(id: string): Asset;
  /** Get public ID for an asset */
  getAssetPublicId(asset: Asset): string;
  
  /** Get symbol resolution for an asset */
  getSymbolResolution(
    asset: Asset,
    symbol: Symbol,
    boundary: ?Bundle
  ): SymbolResolution;
  
  /** Get exported symbols from an asset */
  getExportedSymbols(asset: Asset, boundary: ?Bundle): Array<ExportSymbolResolution>;
  /** Get symbols used by an asset */
  getUsedSymbols(asset: Asset): ?Array<Symbol>;
  
  /** Check if asset is referenced by a bundle */
  isAssetReferenced(bundle: TBundle, asset: Asset): boolean;
  /** Check if asset is reachable from entry bundles */
  isAssetReachableFromEntry(asset: Asset): boolean;
  
  /** Get content hash for a bundle */
  getContentHash(bundle: TBundle): string;
}

/**
 * Mutable bundle graph for bundler plugins
 */
interface MutableBundleGraph extends BundleGraph<Bundle> {
  /** Add asset to a bundle */
  addAssetToBundle(asset: Asset, bundle: Bundle): void;
  /** Add entry asset to a bundle */
  addEntryToBundle(asset: Asset, bundle: Bundle): void;
  /** Create a new bundle */
  createBundle(opts: CreateBundleOpts): Bundle;
  /** Create a new bundle group */
  createBundleGroup(dependency: Dependency, target: Target): BundleGroup;
  /** Remove asset sub-graph from bundle */
  removeAssetGraphFromBundle(asset: Asset, bundle: Bundle): void;
  /** Remove bundle from graph */
  removeBundle(bundle: Bundle): void;
  /** Add dependency between bundles */
  addBundleToBundleGroup(bundle: Bundle, bundleGroup: BundleGroup): void;
  /** Create asset reference between bundles */
  createAssetReference(dependency: Dependency, asset: Asset, bundle: Bundle): void;
  /** Find bundles in the same bundle group */
  findBundlesWithDependency(dependency: Dependency): Array<Bundle>;
}

/**
 * Bundle group representing sibling bundles
 */
interface BundleGroup {
  /** Target environment */
  target: Target;
  /** Entry dependency that created this group */
  entryAsset: Asset;
  /** All bundles in this group */
  bundles: Array<Bundle>;
}

/**
 * Options for creating a new bundle
 */
interface CreateBundleOpts {
  /** Entry asset for the bundle */
  entryAsset?: Asset;
  /** Target environment */
  target: Target;
  /** Bundle content type */
  type?: string;
  /** Whether bundle needs stable name */
  needsStableName?: boolean;
  /** Bundle behavior */
  bundleBehavior?: BundleBehavior;
  /** Whether bundle is splittable */
  isSplittable?: boolean;
  /** Whether bundle is an entry point */
  isEntry?: boolean;
  /** Whether bundle should be inlined */
  isInline?: boolean;
  /** Asset processing pipeline */
  pipeline?: string;
  /** Bundle environment */
  env?: Environment;
}

/**
 * Symbol resolution result
 */
interface SymbolResolution {
  /** Resolved asset containing the symbol */
  asset: Asset;
  /** Exported symbol name */
  exportSymbol: Symbol;
  /** Local symbol name in the asset */
  symbol: ?Symbol;
  /** Location in source code */
  loc: ?SourceLocation;
}

/**
 * Export symbol resolution with re-export information  
 */
interface ExportSymbolResolution {
  /** Exported symbol name */
  exportSymbol: Symbol;
  /** Local symbol name */
  symbol: ?Symbol;
  /** Source asset if re-exported */
  asset: ?Asset;
  /** Location in source code */
  loc: ?SourceLocation;
}

/**
 * Bundle traversal node types
 */
type BundleTraversable = Asset | Bundle | Dependency;

/**
 * Graph visitor for bundle traversal
 */
interface GraphVisitor<TNode, TContext> {
  (node: TNode, context: TContext, actions: TraversalActions): ?TContext;
}

/**
 * Traversal control actions
 */
interface TraversalActions {
  /** Skip visiting children of current node */
  skipChildren(): void;
  /** Stop traversal entirely */
  stop(): void;
}

/**
 * Bundle processing result
 */
interface BundleResult {
  /** Bundle contents */
  contents: Blob;
  /** Source map */
  map?: SourceMap;
  /** Bundle metadata */
  type?: string;
}

import type { 
  BundleGraph, 
  MutableBundleGraph, 
  Bundle, 
  CreateBundleOpts 
} from '@parcel/types';

// Query bundle relationships
function analyzeBundles(bundleGraph: BundleGraph) {
  const bundles = bundleGraph.getBundles();
  
  for (const bundle of bundles) {
    console.log(`Bundle: ${bundle.name}`);
    
    // Get child bundles (async dependencies)
    const children = bundleGraph.getChildBundles(bundle);
    console.log(`  Children: ${children.map(b => b.name).join(', ')}`);
    
    // Get sibling bundles
    const siblings = bundleGraph.getSiblingBundles(bundle);
    console.log(`  Siblings: ${siblings.map(b => b.name).join(', ')}`);
    
    // Check bundle contents
    bundle.traverseAssets((asset) => {
      console.log(`  Asset: ${asset.filePath}`);
    });
  }
}

// Create bundles in a bundler plugin
function createCustomBundles(bundleGraph: MutableBundleGraph) {
  // Create a CSS bundle
  const cssBundle = bundleGraph.createBundle({
    type: 'css',
    target: getCurrentTarget(),
    needsStableName: true
  });
  
  // Find CSS assets and add them to the bundle
  const allBundles = bundleGraph.getBundles();
  for (const bundle of allBundles) {
    bundle.traverseAssets((asset) => {
      if (asset.type === 'css') {
        bundleGraph.addAssetToBundle(asset, cssBundle);
      }
    });
  }
}

// Resolve symbols across bundles
function resolveExports(bundleGraph: BundleGraph, asset: Asset) {
  // Get all exported symbols
  const exports = bundleGraph.getExportedSymbols(asset);
  
  for (const exportRes of exports) {
    console.log(`Export: ${exportRes.exportSymbol}`);
    
    if (exportRes.asset) {
      console.log(`  Re-exported from: ${exportRes.asset.filePath}`);
    }
  }
  
  // Resolve a specific symbol
  const resolution = bundleGraph.getSymbolResolution(asset, 'myExport');
  if (resolution) {
    console.log(`Symbol 'myExport' resolved to ${resolution.asset.filePath}:${resolution.symbol}`);
  }
}

// Traverse bundle graph
function traverseBundleGraph(bundleGraph: BundleGraph) {
  bundleGraph.traverseBundles((bundle, context, actions) => {
    if (bundle.type === 'js') {
      console.log(`Processing JS bundle: ${bundle.name}`);
      
      // Skip children if this is a worker bundle
      if (bundle.env.context === 'web-worker') {
        actions.skipChildren();
      }
    }
  });
}