Function plan

jslibs/extended-css/src/parse/selectorList/plan.ts:11–164

(tokens: IRToken[])

 * Builds a final, optimized query out of intermediate representation tokens.
 */
export function plan(tokens: IRToken[]): Selector {
  if (tokens.length === 0) return [];

  const steps: Selector = [];
  let haveContextualStep = false; // true after we've emitted anything that can serve as context for requiresContext

  const emitBridge = (comb: CombToken) => {
    switch (comb.literal) {
      case ' ':
        steps.push(new Descendant());
        break;
      case '+':
        steps.push(new NextSibling());
        break;
      case '~':
        steps.push(new SubsequentSibling());
        break;
      case '>':
        steps.push(new Child());
        break;
      default:
        throw new Error(`Unknown combinator: "${comb.literal}"`);
    }
    haveContextualStep = true;
  };

  const emitExt = (name: keyof typeof extPseudoClasses, args: string) => {
    const extClass = extPseudoClasses[name];
    if (!extClass) {
      throw new Error(`Unknown extended pseudo-class ":${name}"`);
    }
    if (extClass.requiresContext && !haveContextualStep) {
      steps.push(new RawQuery('*'));
      haveContextualStep = true;
    }
    steps.push(new extClass(args));
    haveContextualStep = true;
  };

  // ---------- Relative selector (starts with a combinator) ----------
  const startsWithCombinator = tokens[0].kind === 'comb';
  if (startsWithCombinator) {
    /**
     * Special case: if the selector start with a combinator, then it's a relative selector.
     * In this case we cannot optimize by merging adjacent "raw" runs; instead, we must rely on filtering via
     * .matches at each step.
     * This behavior is required to support the :has() pseudo-class.
     * See: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selector_structure#relative_selector
     */
    for (let i = 0; i < tokens.length; i++) {
      const t = tokens[i];

      switch (t.kind) {
        case 'comb': {
          // Mirror default path invariants
          const next = tokens[i + 1];
          if (!next) {
            throw new Error('Relative selector ends with a dangling combinator');