@jesscss/core 2.0.0-alpha.4 → 2.0.0-alpha.6

package/src/tree/extend.ts

@@ -0,0 +1,391 @@
+import type { Class } from 'type-fest';
+import { defineType, Node, F_VISIBLE, F_NON_STATIC, F_IMPLICIT_AMPERSAND, type NodeOptions } from './node.js';
+import { type Context } from '../context.js';
+import { Selector } from './selector.js';
+import { Ampersand } from './ampersand.js';
+import type { Ruleset } from './ruleset.js';
+import { Nil } from './nil.js';
+import { ComplexSelector, type ComplexSelectorComponent } from './selector-complex.js';
+import { Combinator } from './combinator.js';
+import { type PrintOptions, getPrintOptions } from './util/print.js';
+import { type MaybePromise, isThenable } from '@jesscss/awaitable-pipe';
+import { isNode } from './util/is-node.js';
+import { N } from './node-type.js';
+import { getImplicitSelector, selectorHasAuthoredAmpersand, wrapParentSelectorForNestedContext } from './util/selector-utils.js';
+import { addParentEdge } from './util/cursor.js';
+import { CANONICAL, EVAL } from './node-base.js';
+
+export enum ExtendFlag {
+  /** Sass and Jess default */
+  All = 0,
+  /** Less default - must not be a partial selector match */
+  Exact = 1
+}
+
+export type ExtendValue = {
+  /** The current selector. By default is `&` */
+  selector?: Selector;
+  /** The target to extend */
+  target: Selector;
+  /**
+   * Optional namespace scoping for extend targets.
+   *
+   * - `namespace: '*'` means "search all extend roots in this file (ignore namespace scoping)".
+   * - `namespace: 'ns'` means "search the extend root(s) assigned to namespace `ns`".
+   */
+  namespace?: string;
+  flag?: ExtendFlag;
+};
+/**
+ * Extends selectors - parsed by Less as an independent statement
+ * at the beginning of rules.
+ *
+ * @todo - figure out eval -- use Rules lookups
+ * @note - there is some pseudo-code somewhere that smartly
+ * registers selectors by a string code.
+ */
+export type ExtendChildData = {
+  selector: Selector | undefined;
+  target: Selector;
+  namespace: string | undefined;
+  flag: ExtendFlag | undefined;
+};
+
+export interface Extend extends Node<ExtendValue, NodeOptions, ExtendChildData> {
+  type: 'Extend';
+  shortType: 'extend';
+  eval(context: Context): MaybePromise<Selector>;
+}
+
+export class Extend extends Node<ExtendValue, NodeOptions, ExtendChildData> {
+  static override childKeys = ['selector', 'target'] as const;
+
+  readonly selector: ExtendValue['selector'];
+  readonly target!: Selector;
+  private readonly namespace: string | undefined;
+  private readonly flag: ExtendFlag | undefined;
+
+  override clone(deep?: boolean, cloneFn?: (n: Node) => Node, ctx?: Context): this {
+    const selector = this.get('selector', ctx);
+    const target = this.get('target', ctx);
+    const namespace = this.get('namespace', ctx);
+    const flag = this.get('flag', ctx);
+    const cloneChild = cloneFn ?? ((n: Node) => n.clone(deep, cloneFn, ctx));
+    const options = this._meta?.options;
+    let priorChildParents: Array<[Node, Node | undefined]> | undefined;
+    if (!deep) {
+      priorChildParents = [];
+      if (selector instanceof Node) {
+        priorChildParents.push([selector, selector.parent]);
+      }
+      if (target instanceof Node) {
+        priorChildParents.push([target, target.parent]);
+      }
+    }
+    const newNode = new (this.constructor as Class<this>)(
+      {
+        selector: deep && selector instanceof Node ? cloneChild(selector) : selector,
+        target: deep ? cloneChild(target) : target,
+        namespace,
+        flag
+      },
+      options ? { ...options } : undefined,
+      this.location,
+      this.treeContext
+    );
+    if (priorChildParents) {
+      const renderKey = ctx?.renderKey ?? (this.renderKey === CANONICAL ? EVAL : this.renderKey);
+      for (const [child, priorParent] of priorChildParents) {
+        addParentEdge(child, renderKey, newNode);
+        (child as unknown as { parent?: Node }).parent = priorParent;
+      }
+    }
+    newNode.inherit(this);
+    return newNode;
+  }
+
+  constructor(value: ExtendValue, options?: any, location?: any, treeContext?: any) {
+    super(value, options, location, treeContext);
+    this.selector = value.selector;
+    this.target = value.target;
+    this.namespace = value.namespace;
+    this.flag = value.flag;
+    if (this.selector instanceof Node) {
+      this.adopt(this.selector);
+    }
+    if (this.target instanceof Node) {
+      this.adopt(this.target);
+    }
+    this.removeFlag(F_VISIBLE);
+    this.addFlag(F_NON_STATIC);
+  }
+
+  override valueOf(context?: Context) {
+    return `$extend ${this.get('target', context).valueOf()}`;
+  }
+
+  override toTrimmedString(options?: PrintOptions): string {
+    options = getPrintOptions(options);
+    const w = options.writer!;
+    const context = options.context;
+    let target = this.get('target', context);
+    let selector = this.get('selector', context);
+    let flag = this.get('flag', context);
+    let namespace = this.get('namespace', context);
+    const mark = w.mark();
+    w.add('$extend');
+    if (selector) {
+      let out = w.capture(() => selector.toString(options)).trim();
+      w.add(' ');
+      w.add(out, selector);
+      w.add(' ->');
+    }
+    let out = w.capture(() => target.toString(options)).trim();
+    w.add(' ');
+    if (namespace) {
+      w.add(`${namespace}|`);
+    }
+    w.add(out, target);
+    if (flag === ExtendFlag.Exact) {
+      w.add(' !exact');
+    }
+    w.add(';');
+    return w.getSince(mark);
+  }
+
+  // Don't preEval Extend - let it be evaluated in evalNode when the ruleset is in the frame
+  // This ensures the ampersand resolves to the correct ruleset selector, not the parent frame
+
+  override evalNode(context: Context): MaybePromise<Nil> {
+    let selector = this.get('selector', context);
+    let target = this.get('target', context);
+    let flag = this.get('flag', context);
+    let namespace = this.get('namespace', context);
+    const hasExplicitSelector = selector !== undefined;
+
+    const currentFrame = context.rulesetFrames.at(-1);
+
+    // If selector is undefined, convert it to ampersand so it resolves to the ruleset's selector
+    // If selector is already set to a non-ampersand (e.g., from a bubbled extend), keep it as-is
+    // The parser sets the selector correctly when bubbling extends, so we should preserve it
+    if (!selector) {
+      // Set selector to ampersand - it will resolve to the current ruleset's selector when evaluated
+      // This matches the conceptual model: .c:extend(.ext all) is like { &:extend(.ext all); } inside .c
+      // The frame selector should already be :is(.a, .b) .c (the evaluated selector from preEval)
+      selector = Ampersand.create(undefined);
+      // Make the ampersand visible so it's included in the selector when evaluated
+      // This ensures the parent selector is properly included in the extend selector
+      selector.addFlag(F_VISIBLE);
+    }
+    // If selector is already set (e.g., .ext7 from a bubbled extend), use it directly
+    // Don't convert non-ampersand selectors to ampersand - they should be used as-is
+    // Get current extend root from registry stack
+    const extendRoot = context.extendRoots.getCurrentExtendRoot();
+    if (!extendRoot) {
+      /** Throw error? */
+      return new Nil();
+    }
+
+    const maybeSel = selector.eval(context);
+    if (isThenable(maybeSel)) {
+      return (maybeSel as Promise<Selector | Nil>).then((sel) => {
+        if (sel instanceof Nil) {
+          return new Nil();
+        }
+        // Resolve ampersand to its current parent selector if needed (live resolution for extend)
+        let resolvedSel: Selector = sel;
+        if (isNode(sel, N.Ampersand)) {
+          const ampResolved = sel.getResolvedSelector();
+          if (ampResolved && !(ampResolved instanceof Nil)) {
+            resolvedSel = ampResolved;
+          }
+        }
+        resolvedSel = resolveExtendSelectorInFrame(
+          resolvedSel,
+          hasExplicitSelector,
+          currentFrame,
+          context
+        );
+        resolvedSel = materializeImplicitAmpersands(resolvedSel, flag !== ExtendFlag.All);
+        const rs = currentFrame as Ruleset;
+        const docOrder = getDocumentOrderForExtend(rs, context);
+        const fromReferenceScope = context.inReferenceImportScope;
+        context.extends.push([target, resolvedSel, flag === ExtendFlag.All, extendRoot, this, docOrder, fromReferenceScope, namespace]);
+        return new Nil();
+      });
+    }
+    const sel = maybeSel as Selector | Nil;
+    if (sel instanceof Nil) {
+      return new Nil();
+    }
+    // Resolve ampersand to its current parent selector if needed (live resolution for extend)
+    let resolvedSel: Selector = sel;
+    if (isNode(sel, N.Ampersand)) {
+      const ampResolved = sel.getResolvedSelector();
+      if (ampResolved && !(ampResolved instanceof Nil)) {
+        resolvedSel = ampResolved;
+      }
+    }
+    resolvedSel = resolveExtendSelectorInFrame(
+      resolvedSel,
+      hasExplicitSelector,
+      currentFrame,
+      context
+    );
+    resolvedSel = materializeImplicitAmpersands(resolvedSel, flag !== ExtendFlag.All);
+    const rs = currentFrame && isNode(currentFrame, N.Ruleset) ? currentFrame as Ruleset : undefined;
+    const docOrder = getDocumentOrderForExtend(rs, context);
+    const fromReferenceScope = context.inReferenceImportScope;
+    context.extends.push([target, resolvedSel, flag === ExtendFlag.All, extendRoot, this, docOrder, fromReferenceScope, namespace]);
+    return new Nil();
+  }
+}
+
+function materializeImplicitAmpersands(
+  selector: Selector,
+  includeNonListImplicit: boolean
+): Selector {
+  const materialize = (node: Selector): Selector => {
+    if (isNode(node, N.Ampersand)) {
+      const amp = node as Ampersand;
+      const n = amp as unknown as Node;
+      if (n.hasFlag(F_IMPLICIT_AMPERSAND)) {
+        const resolved = amp.getResolvedSelector();
+        if (
+          resolved
+          && !(resolved instanceof Nil)
+          && (includeNonListImplicit || isNode(resolved, N.SelectorList))
+        ) {
+          return materialize(resolved.copy(true) as Selector);
+        }
+      }
+      return node.copy(true) as Selector;
+    }
+
+    if (isNode(node, N.ComplexSelector)) {
+      const complex = node as ComplexSelector;
+      const parts: Selector[] = [];
+      for (const part of complex.get('value') as unknown as Selector[]) {
+        if (isNode(part, N.Ampersand)) {
+          const amp = part as Ampersand;
+          const n = amp as unknown as Node;
+          if (n.hasFlag(F_IMPLICIT_AMPERSAND)) {
+            const resolved = amp.getResolvedSelector();
+            if (
+              resolved
+              && !(resolved instanceof Nil)
+              && (includeNonListImplicit || isNode(resolved, N.SelectorList))
+            ) {
+              const repl = materialize(resolved.copy(true) as Selector);
+              if (isNode(repl, N.ComplexSelector)) {
+                parts.push(...((repl as ComplexSelector).get('value') as unknown as Selector[]).map(x => x.copy(true) as Selector));
+              } else {
+                parts.push(repl);
+              }
+              continue;
+            }
+          }
+        }
+        const repl = materialize(part);
+        parts.push(repl);
+      }
+      return ComplexSelector.create(parts as ComplexSelectorComponent[]).inherit(node) as Selector;
+    }
+
+    const value = (node as Selector & { value?: Selector[] }).value;
+    if (Array.isArray(value)) {
+      const cloned = node.copy(true) as Selector & { value?: Selector[] };
+      cloned.value = value.map(item => materialize(item as Selector));
+      return cloned as Selector;
+    }
+
+    return node.copy(true) as Selector;
+  };
+
+  return materialize(selector);
+}
+
+/** Document order for extend: prefer parse location startOffset (source order), else assigned map, else push order (length). */
+function getDocumentOrderForExtend(rs: Ruleset | undefined, context: Context): number {
+  if (!rs) {
+    return context.extends.length;
+  }
+  const loc = (rs as Node).location;
+  const fromLoc = Array.isArray(loc) && loc.length >= 1 && typeof loc[0] === 'number' ? loc[0] : undefined;
+  if (fromLoc !== undefined) {
+    return fromLoc;
+  }
+  const fromMap = context.documentOrderByRuleset?.get(rs);
+  if (fromMap !== undefined) {
+    return fromMap;
+  }
+  return context.extends.length;
+}
+export const extend = defineType(Extend, 'Extend');
+
+function resolveExtendSelectorInFrame(
+  selector: Selector,
+  hasExplicitSelector: boolean,
+  currentFrame: Node | undefined,
+  context: Context
+): Selector {
+  if (!currentFrame || !isNode(currentFrame, N.Ruleset)) {
+    return selector;
+  }
+
+  const rs = currentFrame as Ruleset;
+  const fullSel = rs.getEffectiveSelector(false, context);
+  let resolvedSel = selector;
+  let usedParentListComposition = false;
+
+  if (!hasExplicitSelector) {
+    const ownSel = rs.getOwnSelector(context);
+    const parentFrame = context.rulesetFrames.at(-2);
+    const parentSel = (
+      parentFrame && isNode(parentFrame, N.Ruleset)
+        ? (parentFrame as Ruleset).getEffectiveSelector(false, context)
+        : undefined
+    );
+    if (
+      ownSel
+      && parentSel
+      && !(parentSel instanceof Nil)
+      && isNode(parentSel, N.SelectorList)
+    ) {
+      resolvedSel = ComplexSelector.create([
+        wrapParentSelectorForNestedContext(parentSel as Selector),
+        Combinator.create(' '),
+        ownSel.copy(true) as Selector
+      ] as unknown as ComplexSelectorComponent[]) as unknown as Selector;
+      usedParentListComposition = true;
+    }
+  }
+
+  if (!hasExplicitSelector && !usedParentListComposition) {
+    if (fullSel && !(fullSel instanceof Nil)) {
+      return fullSel as Selector;
+    }
+
+    const parentSel = rs.getEffectiveSelector(false, context);
+    if (parentSel && !(parentSel instanceof Nil) && resolvedSel.valueOf() !== (parentSel as Selector).valueOf()) {
+      return ComplexSelector.create([
+        (parentSel as Selector).copy(true),
+        Combinator.create(' '),
+        resolvedSel.copy(true)
+      ]) as unknown as Selector;
+    }
+
+    return resolvedSel;
+  }
+
+  if (
+    hasExplicitSelector
+    && selectorHasAuthoredAmpersand(resolvedSel)
+    && fullSel
+    && !(fullSel instanceof Nil)
+  ) {
+    return getImplicitSelector(resolvedSel, fullSel as Selector, false);
+  }
+
+  return resolvedSel;
+}

package/src/tree/function.ts

@@ -0,0 +1,254 @@
+import { type Context } from '../context.js';
+import { defineType, F_VISIBLE, Node, type LocationInfo, type OptionalLocation, type TreeContext } from './node.js';
+import type { Any, AnyRole } from './any.js';
+import { Any as AnyCtor } from './any.js';
+import { Interpolated } from './interpolated.js';
+import { Rules } from './rules.js';
+import { type List, list } from './list.js';
+import type { Declaration } from './declaration.js';
+import type { VarDeclaration } from './declaration-var.js';
+import { VarDeclaration as VarDeclarationCtor } from './declaration-var.js';
+import { Nil } from './nil.js';
+import { N } from './node-type.js';
+import { isNode } from './util/is-node.js';
+import { type PrintOptions, getPrintOptions } from './util/print.js';
+import { getParent, getSourceParent, setChildren } from './util/field-helpers.js';
+
+/**
+ * Stylesheet-defined function with a return value.
+ * Called `Func` to avoid conflict with the built-in `Function` class.
+ *
+ * Parsed by Sass/Jess-like languages (e.g. SCSS `@function`).
+ *
+ * Evaluation model:
+ * - Evaluate the function body in an isolated scope (like mixins) with bound params.
+ * - Then look up a declaration by name (default: `return`) and return its value.
+ */
+export type FuncValue<Name extends AnyRole = 'name'> = {
+  name?: Any<Name> | Interpolated<Name>;
+  params?: List<Node>;
+  body: Node;
+};
+
+export type FuncOptions = {
+  /**
+   * Declaration name to look up after evaluating the body.
+   * Defaults to `'return'` (a `return: <expr>;` declaration).
+   */
+  returnName?: string;
+};
+
+export type FuncChildData = {
+  name: FuncValue['name'];
+  params: FuncValue['params'];
+  body: Node;
+};
+
+export interface Func extends Node<FuncValue, FuncOptions, FuncChildData> {
+  type: 'Func';
+  shortType: 'fn';
+}
+
+export class Func extends Node<FuncValue, FuncOptions, FuncChildData> {
+  static override childKeys = ['name', 'params', 'body'] as const;
+
+  name: FuncValue['name'];
+  params: FuncValue['params'];
+  body!: Node;
+
+  constructor(value: FuncValue, options?: FuncOptions, location?: OptionalLocation, treeContext?: TreeContext) {
+    super(value, options, location, treeContext);
+    this.name = value.name;
+    this.params = value.params;
+    this.body = value.body;
+    if (this.name instanceof Node) {
+      this.adopt(this.name);
+    }
+    if (this.params instanceof Node) {
+      this.adopt(this.params);
+    }
+    if (this.body instanceof Node) {
+      this.adopt(this.body);
+    }
+    this.removeFlag(F_VISIBLE);
+  }
+
+  get nameKey(): string | undefined {
+    return this.getNameKey();
+  }
+
+  getNameKey(context?: Context): string | undefined {
+    const name = this.get('name', context);
+    if (!name) {
+      return undefined;
+    }
+    return String(name.valueOf());
+  }
+
+  override toTrimmedString(options?: PrintOptions): string {
+    options = getPrintOptions(options);
+    const w = options.writer!;
+    const mark = w.mark();
+    const context = options.context;
+    const name = this.get('name', context);
+    const params = this.get('params', context);
+    const body = this.get('body', context);
+
+    w.add('$function', this);
+    w.add(' ');
+    w.add(name ? `${name}` : '@', this);
+    w.add('(');
+    if (params) {
+      params.toString(options);
+    }
+    w.add(') ');
+
+    // Body is always emitted as braced rules. If it's not a Rules node already, wrap it.
+    const bodyRules = body instanceof Rules ? body : Rules.create([body]);
+    bodyRules.toBraced(options);
+
+    return w.getSince(mark);
+  }
+
+  /**
+   * Execute the function and return its looked-up value.
+   *
+   * Functions follow the same scoped-body model as simple mixins:
+   * bind args into an ephemeral param scope, evaluate one render-keyed body
+   * wrapper, then read the return declaration from that evaluated scope.
+   */
+  async evalCall(context: Context, args: List<Node> = list([]), _contentNode?: Node): Promise<Node> {
+    const returnName = this.options?.returnName ?? 'return';
+    const name = this.get('name', context);
+    const params = this.get('params', context);
+    const bodyNode = this.get('body', context);
+    const renderKey = context.nextRenderKey();
+    const invocationParent = context.caller
+      ? getParent(context.caller, context) ?? context.rulesContext
+      : context.rulesContext ?? getParent(this, context);
+    const callerSourceNode = context.caller && isNode(context.caller, N.Call) && context.caller.get('name') instanceof Node
+      ? context.caller.get('name')
+      : context.caller;
+    const sourceParent = callerSourceNode
+      ? getSourceParent(callerSourceNode as Node, context)
+      : getSourceParent(this, context);
+    const scope = this._createInvocationScope(params, args, renderKey, invocationParent, context);
+    const bodyRules = this._createInvocationBodyRules(bodyNode, renderKey, scope ?? invocationParent, sourceParent, context);
+
+    const previousRulesContext = context.rulesContext;
+    const previousLookupScope = context.lookupScope;
+    const previousRenderKey = context.renderKey;
+    context.rulesContext = scope ?? bodyRules;
+    context.lookupScope = scope ?? bodyRules;
+    context.renderKey = renderKey;
+    let evaluated: Rules;
+    try {
+      evaluated = await bodyRules.eval(context);
+    } finally {
+      context.rulesContext = previousRulesContext;
+      context.lookupScope = previousLookupScope;
+      context.renderKey = previousRenderKey;
+    }
+
+    if (!(evaluated instanceof Rules)) {
+      throw new Error(`Function ${String(name?.valueOf() ?? '<anonymous>')} must evaluate to rules`);
+    }
+
+    const returnLookupOptions = { searchParents: false, context };
+    const decl = evaluated.find('declaration', returnName, 'Declaration', returnLookupOptions) as Declaration | undefined
+      ?? evaluated.find('declaration', returnName, 'VarDeclaration', returnLookupOptions) as VarDeclaration | undefined;
+    if (!decl) {
+      throw new Error(`Function ${String(name?.valueOf() ?? '<anonymous>')} must return a value (missing "${returnName}: ...")`);
+    }
+    context.rulesContext = scope ?? evaluated;
+    context.lookupScope = scope ?? evaluated;
+    context.renderKey = evaluated.renderKey;
+    try {
+      const returnValue = (decl as Declaration).get('value', context);
+      return await returnValue.eval(context);
+    } finally {
+      context.rulesContext = previousRulesContext;
+      context.lookupScope = previousLookupScope;
+      context.renderKey = previousRenderKey;
+    }
+  }
+
+  private _createInvocationScope(
+    params: List<Node> | undefined,
+    args: List<Node>,
+    renderKey: symbol,
+    parent: Node | undefined,
+    context: Context
+  ): Rules | undefined {
+    if (!params) {
+      return undefined;
+    }
+    const scope = Rules.create([], {
+      rulesVisibility: {
+        Ruleset: 'public',
+        Declaration: 'public',
+        VarDeclaration: 'public',
+        Mixin: 'public'
+      }
+    });
+    scope.renderKey = renderKey;
+    scope.parent = parent;
+
+    const invocationContext = {
+      ...context,
+      renderKey,
+      rulesContext: scope,
+      lookupScope: scope
+    };
+    const argItems = args.get('value', context);
+    const paramItems = params.get('value', context);
+
+    for (let i = 0; i < paramItems.length; i++) {
+      const param = paramItems[i]!;
+      if (!isNode(param, N.VarDeclaration)) {
+        continue;
+      }
+      const boundParam = new VarDeclarationCtor({
+        name: new AnyCtor(String(param.get('name', context).valueOf()), { role: 'property' }),
+        value: new Nil()
+      }, { ...(param.options ?? {}), paramVar: true }, param.location, this.treeContext);
+      boundParam.index = param.index ?? -(i + 1);
+      scope.push(boundParam);
+
+      const boundValue = argItems[i] ?? param.get('value', context);
+      if (boundValue) {
+        boundParam.setCurrentValue(boundValue, invocationContext);
+      }
+    }
+
+    return scope;
+  }
+
+  private _createInvocationBodyRules(
+    bodyNode: Node,
+    renderKey: symbol,
+    parent: Node | undefined,
+    sourceParent: Node | undefined,
+    context: Context
+  ): Rules {
+    let bodyRules: Rules;
+    if (bodyNode instanceof Rules) {
+      bodyRules = bodyNode.createShallowBodyWrapper(undefined, renderKey);
+    } else {
+      bodyRules = Rules.create([], undefined, Array.isArray(this.location) && this.location.length === 6 ? (this.location as LocationInfo) : undefined, this.treeContext);
+      bodyRules.renderKey = renderKey;
+      setChildren(bodyRules, [bodyNode], { ...context, renderKey }, { markDirty: false });
+    }
+    bodyRules.parent = parent;
+    bodyRules.sourceParent = sourceParent;
+    bodyRules.index = this.index;
+    return bodyRules;
+  }
+}
+
+export const fn = defineType(Func, 'Func', 'fn') as (
+  value: FuncValue | { name?: string; params?: List<Node>; body: Node },
+  options?: FuncOptions,
+  location?: OptionalLocation,
+  treeContext?: TreeContext
+) => Func;