@custom-elements-manifest/analyzer/src/create.js

<!-- [=> See Source <=](../../docs/analyzer/index.md) -->

import ts from 'typescript';
import { FEATURES } from './features/index.js';
import { withErrorHandling } from './utils/index.js';

/**
 * CORE
 *
 * This function is the core of the analyzer. It takes an array of ts sourceFiles, and creates a
 * custom elements manifest.
 */
export function create({modules, plugins = [], context = {dev:false}}) {
  const customElementsManifest = {
    schemaVersion: '1.0.0',
    readme: '',
    modules: [],
  };

  const { dev } = context;

  const mergedPlugins = [
    ...FEATURES,
    ...plugins,
  ];

  if(dev) console.log('[INITIALIZE PLUGINS]');
  mergedPlugins.forEach(({name, initialize}) => {
    withErrorHandling(name, () => {
      initialize?.({ts, customElementsManifest, context});
    });
  });

  modules.forEach(currModule => {
    if(dev) console.log('[COLLECT PHASE]: ', currModule.fileName);
    /**
     * COLLECT PHASE
     * First pass through all modules. Can be used to gather imports, exports, types, default values,
     * which you may need to know the existence of in a later phase.
     */
    collect(currModule, context, mergedPlugins);
  });

  modules.forEach(currModule => {
    if(dev) console.log('[ANALYZE PHASE]: ', currModule.fileName);
    const moduleDoc = {
      kind: "javascript-module",
      path: currModule.fileName,
      declarations: [],
      exports: []
    };

    /**
     * ANALYZE PHASE
     * Go through the AST of every separate module, and gather as much as information as we can
     * This includes a modules imports, which are not specified in custom-elements.json, but are
     * required for the LINK PHASE, and deleted when processed
     */
    analyze(currModule, moduleDoc, context, mergedPlugins);
    customElementsManifest.modules.push(moduleDoc);

    if(dev) console.log('[MODULE LINK PHASE]: ', currModule.fileName);
    /**
     * LINK PHASE
     * All information for a module has been gathered, now we can link information together. Like:
     * - Finding a CustomElement's tagname by finding its customElements.define() call (or 'export')
     * - Applying inheritance to classes (adding `inheritedFrom` properties/attrs/events/methods)
     */
    mergedPlugins.forEach(({name, moduleLinkPhase}) => {
      withErrorHandling(name, () => {
        moduleLinkPhase?.({ts, moduleDoc, context});
      });
    });
  });

  if(dev) console.log('[PACKAGE LINK PHASE]');
  /**
   * PACKAGE LINK PHASE
   * All modules have now been parsed, we can now link information from across modules together
   * - Link classes to their definitions etc
   * - Match tagNames for classDocs
   * - Apply inheritance
   */
  mergedPlugins.forEach(({name, packageLinkPhase}) => {
    withErrorHandling(name, () => {
      packageLinkPhase?.({customElementsManifest, context});
    });
  });

  return customElementsManifest;
}

function collect(source, context, mergedPlugins) {
  visitNode(source);

  function visitNode(node) {
    mergedPlugins.forEach(({name, collectPhase}) => {
      withErrorHandling(name, () => {
        collectPhase?.({ts, node, context});
      });
    });

    ts.forEachChild(node, visitNode);
  }
}

function analyze(source, moduleDoc, context, mergedPlugins) {
  visitNode(source);

  function visitNode(node) {
    mergedPlugins.forEach(({name, analyzePhase}) => {
      withErrorHandling(name, () => {
        analyzePhase?.({ts, node, moduleDoc, context});
      });
    });

    ts.forEachChild(node, visitNode);
  }
}