Ember CLI Integration

/**
 * Main Ember CLI addon interface
 * Automatically instantiated by Ember CLI
 */
interface EmberCLIHTMLBarsAddon {
  /** Addon name from package.json */
  name: string;
  
  /** Parent registry for plugin loading */
  parentRegistry: PreprocessorRegistry | null;
  
  /**
   * Initialize the addon
   * Called by Ember CLI during addon setup
   */
  init(): void;
  
  /**
   * Transpile a custom tree using ember-cli-htmlbars processing
   * @param inputTree - Broccoli tree to process
   * @param htmlbarsOptions - Template compilation options
   * @returns Processed Broccoli tree
   */
  transpileTree(inputTree: BroccoliTree, htmlbarsOptions?: object): BroccoliTree;
  
  /**
   * Setup preprocessor registry for template handling
   * @param type - Registry type ('parent' or other)
   * @param registry - Preprocessor registry instance
   */
  setupPreprocessorRegistry(type: string, registry: PreprocessorRegistry): void;
  
  /**
   * Addon inclusion hook - sets up Babel plugins
   * Called when addon is included in build
   */
  included(): void;
  
  /**
   * Get HTMLBars compilation options
   * @returns Configuration object for template compilation
   */
  htmlbarsOptions(): HTMLBarsOptions;
  
  /**
   * Get path to template compiler
   * @returns Absolute path to ember-template-compiler.js
   */
  templateCompilerPath(): string;
  
  /**
   * Load and configure AST plugins
   * @returns Plugin configuration information
   */
  astPlugins(): PluginInfo;
  
  /**
   * Get project configuration
   * @returns Project config object
   */
  projectConfig(): object;
}

/**
 * Template preprocessor configuration
 * Automatically registered with Ember CLI
 */
interface TemplatePreprocessor {
  /** Preprocessor name */
  name: 'ember-cli-htmlbars';
  /** File extension to process */
  ext: 'hbs';
  /** Reference to addon instance */
  _addon: EmberCLIHTMLBarsAddon;
  
  /**
   * Transform template tree
   * @param tree - Input template tree
   * @returns Processed tree with JavaScript modules
   */
  toTree(tree: BroccoliTree): BroccoliTree;
  
  /**
   * Precompile individual template strings
   * @param string - Template string
   * @param options - Compilation options
   * @returns Compiled template string
   */
  precompile(string: string, options?: object): string;
}

// Automatically registered - no manual setup required
// Processes all .hbs files in:
// - app/templates/
// - app/components/
// - addon/templates/
// - addon/components/
// - addon-test-support/

// Custom configuration in ember-cli-build.js
module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    'ember-cli-htmlbars': {
      templateCompilerPath: 'custom/template-compiler.js'
    }
  });
  return app.toTree();
};

/**
 * Babel plugin configuration for inline precompilation
 * Handles hbs`` tagged template literals
 */
interface BabelPluginSetup {
  /** Plugin path */
  plugin: string;
  /** Plugin options */
  options: {
    /** Template compiler function */
    precompile?: Function;
    /** Production build flag */
    isProduction?: boolean;
    /** Module API polyfill requirement */
    ensureModuleApiPolyfill?: boolean;
    /** Supported import modules */
    modules: {
      'ember-cli-htmlbars': 'hbs';
      'ember-cli-htmlbars-inline-precompile': 'default';
      'htmlbars-inline-precompile': 'default';
    };
  };
}

// Source code
import { hbs } from 'ember-cli-htmlbars';
const template = hbs`<div>{{@name}}</div>`;

// Babel transforms to (simplified)
const template = Ember.HTMLBars.template(/* compiled function */);

/**
 * ember-cli-htmlbars build configuration
 * Set in ember-cli-build.js or addon configuration
 */
interface EmberCLIHTMLBarsConfig {
  /** Path to custom template compiler */
  templateCompilerPath?: string;
}

/**
 * HTMLBars compilation options
 * Generated from project configuration and plugins
 */
interface HTMLBarsOptions {
  /** HTMLBars flag */
  isHTMLBars: boolean;
  /** Ember environment variables */
  EmberENV: object;
  /** Template compiler instance */
  templateCompiler: object;
  /** Path to template compiler */
  templateCompilerPath: string;
  /** Plugin names for debugging */
  pluginNames: string[];
  /** AST plugin configuration */
  plugins: {
    ast: ASTPlugin[];
  };
  /** Dependency invalidation flag */
  dependencyInvalidation: boolean;  
  /** Plugin cache keys */
  pluginCacheKey: string[];
}

// ember-cli-build.js
module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    'ember-cli-htmlbars': {
      templateCompilerPath: require.resolve('./custom-template-compiler')
    }
  });
  return app.toTree();
};

// Custom AST plugin registration in addon
module.exports = {
  name: 'my-addon',
  included() {
    this.app.registry.add('htmlbars-ast-plugin', {
      name: 'my-transform',
      plugin: MyTransform
    });
  }
};

/**
 * Colocation feature detection and processing
 * Automatically enabled when requirements are met
 */
interface ColocationSupport {
  /**
   * Check if colocation is supported
   * Based on Ember, Babel, and Ember CLI versions
   * @returns True if colocation can be enabled
   */
  shouldColocateTemplates(): boolean;
}

// Component file: app/components/user-card.js
import Component from '@glimmer/component';

export default class UserCardComponent extends Component {
  // Component logic
}

// Colocated template: app/components/user-card.hbs
<div class="user-card">
  <h2>{{@user.name}}</h2>
</div>

// Babel transforms component to:
import Component from '@glimmer/component';
import { setComponentTemplate } from '@ember/component';
import __COLOCATED_TEMPLATE__ from './user-card.hbs';

class UserCardComponent extends Component {
  // Component logic
}

setComponentTemplate(__COLOCATED_TEMPLATE__, UserCardComponent);
export default UserCardComponent;

/**
 * Version compatibility utilities
 * Ensures proper integration across Ember ecosystem versions
 */
interface VersionCompatibility {
  /** Whether module API polyfill is required */
  requiresModuleApiPolyfill: boolean;
  /** Whether Babel tree wrapping is needed */
  requiresBabelTree: boolean;
  /** Whether addon is being used in an addon context */
  isAddon: boolean;
}

// Detailed logging via heimdalljs-logger
// Debug trees with broccoli-debug
// Version compatibility warnings
// Plugin configuration validation
// Template compiler path resolution errors
// AST plugin loading and execution errors

ember-cli-htmlbars:addon:my-app - Colocation processing: true
ember-cli-htmlbars:addon:my-app - using babel inline precompilation plugin (parallelized)
ember-cli-htmlbars:addon:my-app - setup *.hbs compiler with ['transform-1', 'transform-2']