All files / lib/compiler/parser staticSubtrees.js

96.8% Statements 212/219
93.47% Branches 86/92
100% Functions 5/5
96.8% Lines 212/219

Press n or j to go to the next uncovered block, b, p or k for the previous block.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 4x 4x 4x 4x 4x 4x 4x 4x 4x 4x 4x 4x 3x 3x 4x 4x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 3178x 3178x 3178x 3178x 3178x 3178x 3178x 2x 2x 2x 2x 2x 2x 1x 1x 1x 1x 1x 3178x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 31205x 51283x 51283x 28019x 28019x 28019x 28019x 28019x 28019x 28019x 28019x 28019x 28019x 28019x 28019x 1x 1x 28019x     28017x     28017x       28018x 28018x 28018x 28018x 28018x 28018x 28018x 28018x 28018x 28019x 2x 2x 28018x 28019x 4168x 4168x 28018x 28018x 28018x 51283x 51283x 23261x 51283x 3x 51283x 51283x 31205x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 51858x 22471x 22471x 51858x 1551x 1551x 27836x 51858x 532x 532x 532x 532x 532x 532x 532x 27363x 27363x 4842x 2370x 2370x 2472x 2472x 27363x 101x 101x 27363x 22419x 22419x 171x 171x 22248x 22419x 8407x 8407x 13841x 22419x 1551x 1551x 12290x 22417x 69x 69x 12221x 22417x 17051x 2289x 2289x 17051x 970x 970x 17051x 249x 249x 17051x 8713x 22129x 6929x 3881x 3881x 6929x 4831x 4831x 4831x 27363x 1x 27363x 27363x  
/**
 * @file staticSubtrees.js
 * @description Marks static subtrees with `data-ax-static` so the patcher can skip them.
 *
 * An optimisation pass, not a directive: it never changes what a template
 * means, only how much of it the runtime has to revisit. It also lowers the
 * block-contract directives (`<@static>`, `<@isolated>`, `<@pure>`,
 * `<@deterministic>`) to the `div` wrappers the runtime understands.
 */
import { logger } from '../../core/runtime/AvenxLogger.js';
import { AvenxErrorCodes } from '../../core/runtime/AvenxError.js';
import { CompilerError, TemplateValidationError } from '../errors/index.js';
import { parseHTML, serializeHTML } from './htmlTree.js';
import { getCustomVoidTags } from './projectConfig.js';
 
/**
 * The error raised when a pass over the template AST meets a node type it has
 * no branch for.
 *
 * Both static-subtree passes need this, and they need to raise the *same*
 * thing: `optimizeStaticSubtrees` degrades gracefully on any ordinary failure,
 * so the only way an exhaustiveness bug can reach a developer is if it is
 * distinguishable from the failures that pass is allowed to swallow.
 * @param {object} node - The node that has no branch.
 * @param {string} pass - The function that could not read it, for the message.
 * @returns {CompilerError} The error to throw.
 */
function unhandledNodeType(node, pass) {
  const type = node && node.type !== undefined ? String(node.type) : String(node);
  const hasLocation = node && node.line !== null && node.line !== undefined;
  const where = hasLocation ? ` at line ${node.line}, column ${node.column}` : '';
  const error = new CompilerError(AvenxErrorCodes.COMPILER_UNHANDLED_AST_NODE, type, where, pass);
  /**
   * Marks the error as an invariant violation rather than a template problem,
   * so `optimizeStaticSubtrees` rethrows it instead of warning and carrying on.
   * @type {boolean}
   */
  error.isExhaustivenessFailure = true;
  if (hasLocation) {
    error.setLocation({ line: node.line, column: node.column });
  }
  return error;
}
 
/**
 * Identifies static elements/subtrees and marks them with data-ax-static="true".
 * @param {string} template - The compiled HTML template.
 * @param {string} [filePath] - The component file path, used to resolve project-specific
 *   void tags from `avenx.config.json`.
 * @param {object} [options] - Parser state the pass reads.
 * @param {string[]} [options.customVoidTags] - Void tags configured on the parser itself.
 * @param {function(HTMLNode[], boolean): void} [options.markStaticNodes] - The marking
 *   walk to run. Defaults to {@link markStaticNodes}; the parser passes its own
 *   method so an instance override still takes effect.
 * @returns {string} The optimized template.
 */
export function optimizeStaticSubtrees(template, filePath, { customVoidTags = [], markStaticNodes: mark } = {}) {
  const walk = mark || markStaticNodes;
  try {
    const voidTags = [...(customVoidTags || []), ...getCustomVoidTags(filePath)];
    const nodes = parseHTML(template, voidTags);
    walk(nodes, false);
    return serializeHTML(nodes, voidTags);
  } catch (err) {
    // Marking static subtrees is an optimization, so an ordinary failure
    // degrades to the unoptimized template rather than failing the build.
    // An unhandled node type is not an ordinary failure: it means a pass
    // cannot read what the parser now produces, and swallowing it here is
    // exactly the silent mis-handling the check exists to prevent.
    if (err && err.isExhaustivenessFailure) {
      throw err;
    }
    logger.warn(new TemplateValidationError(AvenxErrorCodes.COMPILER_STATIC_SUBTREE_OPTIMIZATION_FAILED, err).message);
    return template;
  }
}
 
/**
 * Recursively traverses nodes to find and mark the root of static subtrees.
 * @param {HTMLNode[]} nodes - The nodes to mark, in place.
 * @param {boolean} [parentIsStatic] - Whether the parent is already marked static.
 * @param {boolean} [inSlot] - Indicates if the current node is inside a slot or component transclusion boundary.
 * @param {function(HTMLNode[], boolean, boolean): void} [visitChildren] - How to descend
 *   into an element's children. Defaults to this function; the parser passes its
 *   own method so an instance override sees every level of the walk.
 * @returns {void}
 */
export function markStaticNodes(nodes, parentIsStatic = false, inSlot = false, visitChildren = markStaticNodes) {
  for (const node of nodes) {
    switch (node.type) {
      case 'element': {
        const lowerTag = node.tagName.toLowerCase();
        const isSlot = lowerTag === 'slot';
        const isComponent = Boolean(
          node.attrs['data-avenx-comp'] || node.attrs['data-ax-comp'] || /^[A-Z]/.test(node.tagName),
        );
        const currentInSlot = inSlot || isSlot || isComponent;
        const hasStaticContract = node.contracts && node.contracts.has('static');
        const nodeStatic = !currentInSlot && (hasStaticContract || isStaticNode(node));
        node.isStatic = nodeStatic;
 
        // Convert contract block directives to div wrappers with respective data attributes
        if (lowerTag === '@static') {
          node.tagName = 'div';
          node.attrs['data-ax-static'] = 'true';
        } else if (lowerTag === '@isolated') {
          node.tagName = 'div';
          node.attrs['data-ax-isolated'] = 'true';
        } else if (lowerTag === '@pure') {
          node.tagName = 'div';
          node.attrs['data-ax-pure'] = 'true';
        } else if (lowerTag === '@deterministic') {
          node.tagName = 'div';
          node.attrs['data-ax-deterministic'] = 'true';
        }
 
        // Clean up raw contract attributes from DOM element output
        if (node.attrs) {
          if (node.attrs['static'] !== undefined) delete node.attrs['static'];
          if (node.attrs['pure'] !== undefined) delete node.attrs['pure'];
          if (node.attrs['deterministic'] !== undefined) delete node.attrs['deterministic'];
          if (node.attrs['isolated'] !== undefined) delete node.attrs['isolated'];
        }
 
        if (node.contracts && node.contracts.has('pure') && node.contracts.has('deterministic') && !nodeStatic) {
          node.attrs['data-ax-memo'] = 'true';
        }
 
        if (nodeStatic && !parentIsStatic) {
          node.attrs['data-ax-static'] = 'true';
        }
        visitChildren(node.children, nodeStatic, currentInSlot);
        break;
      }
      case 'text':
      case 'comment':
        break;
      default:
        throw unhandledNodeType(node, 'markStaticNodes');
    }
  }
}
 
/**
 * Recursively checks whether a node is a <slot> tag, or has a <slot>
 * anywhere among its descendants. Used to disqualify a subtree from the
 * static-optimization pass, since slots are dynamic transclusion points
 * that DomPatcher must always be able to patch (see issue #200).
 * @param {HTMLNode} node - The node to inspect.
 * @returns {boolean} True when the node is or contains a slot.
 */
export function containsSlot(node) {
  if (node.type !== 'element') {
    return false;
  }
  if (node.tagName.toLowerCase() === 'slot') {
    return true;
  }
  return node.children.some((child) => containsSlot(child));
}
 
/**
 * Recursively determines if a node (and all its descendants) are completely static.
 * @param {HTMLNode} node - The node to inspect.
 * @returns {boolean} True when nothing in the subtree can change after the first render.
 */
export function isStaticNode(node) {
  switch (node.type) {
    case 'text': {
      if (node.content && (node.content.includes('{{') || node.content.includes('{%'))) {
        return false;
      }
      return true;
    }
    case 'comment': {
      return true;
    }
    case 'element': {
      const lowerTag = node.tagName.toLowerCase();
      if (lowerTag === 'template' || lowerTag === 'slot') {
        return false;
      }
 
      if (lowerTag.startsWith('@')) {
        return false;
      }
 
      if (containsSlot(node)) {
        return false;
      }
 
      if (/^[A-Z]/.test(node.tagName)) {
        return false;
      }
 
      for (const [name, val] of Object.entries(node.attrs)) {
        if (name.startsWith('@') || name.startsWith(':')) {
          return false;
        }
        if ((name.startsWith('data-ax-') && name !== 'data-ax-static') || name.startsWith('data-avenx-')) {
          return false;
        }
        if (val && (val.includes('{{') || val.includes('{%'))) {
          return false;
        }
      }
 
      for (const child of node.children) {
        if (!isStaticNode(child)) {
          return false;
        }
      }
 
      return true;
    }
    default:
      throw unhandledNodeType(node, 'isStaticNode');
  }
}