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

package/src/tree/util/field-helpers.ts

@@ -0,0 +1,354 @@
+import { CANONICAL, EVAL, type Node, type RenderKey } from '../node-base.js';
+import type { Context } from '../../context.js';
+import type { Rules } from '../rules.js';
+import { isNode } from './is-node.js';
+import { N } from '../node-type.js';
+import { addEdgeAt, addParentEdge, removeParentEdge } from './cursor.js';
+
+function getParentEdgeRenderKeys(
+  node: Node,
+  ctx: Context,
+  edge?: Map<unknown, Node | undefined>
+): unknown[] {
+  const keys: unknown[] = [];
+  const push = (key: unknown): void => {
+    if (key === undefined || key === CANONICAL || keys.includes(key)) {
+      return;
+    }
+    keys.push(key);
+  };
+  push(ctx.renderKey);
+  push(ctx.rulesContext?.renderKey);
+  push(node.renderKey);
+  if (edge?.has(EVAL)) {
+    push(EVAL);
+  }
+  return keys;
+}
+
+function setRulesValueArray(rules: Rules, nodes: Node[]): void {
+  const mutableRules = rules as Rules & { _setValueArray?: (nodes: Node[]) => void };
+  if (typeof mutableRules._setValueArray !== 'function') {
+    throw new Error('Rules is missing _setValueArray');
+  }
+  mutableRules._setValueArray(nodes);
+}
+
+type ChildWriteTarget =
+  | {
+    kind: 'canonical';
+    currentChildren: readonly Node[];
+  }
+  | {
+    kind: 'wrapper';
+    renderKey: RenderKey;
+    currentChildren: readonly Node[];
+  }
+  | {
+    kind: 'overlay';
+    renderKey: RenderKey;
+    currentChildren: readonly Node[];
+  };
+
+function resolveChildWriteTarget(
+  rules: Rules,
+  ctx: Context
+): ChildWriteTarget {
+  const resolvedRenderKey = ctx.renderKey ?? rules.renderKey;
+  const renderKey = resolvedRenderKey === CANONICAL ? undefined : resolvedRenderKey;
+  if (renderKey === undefined) {
+    return {
+      kind: 'canonical',
+      currentChildren: rules.value
+    };
+  }
+  if (rules.renderKey !== undefined && rules.renderKey === renderKey) {
+    return {
+      kind: 'wrapper',
+      renderKey,
+      currentChildren: rules.value
+    };
+  }
+  return {
+    kind: 'overlay',
+    renderKey,
+    currentChildren: rules.get('value', ctx)
+  };
+}
+
+function maybeMarkScopeDirty(
+  rules: Rules,
+  ctx: Context,
+  options: { markDirty?: boolean }
+): void {
+  if (options.markDirty !== false) {
+    markScopeDirty(rules, ctx);
+  }
+}
+
+function connectRenderChildren(
+  rules: Rules,
+  nodes: readonly Node[],
+  renderKey: RenderKey
+): void {
+  for (let index = 0; index < nodes.length; index++) {
+    const node = nodes[index]!;
+    addEdgeAt(rules, 'value', index, renderKey, node);
+    addParentEdge(node, renderKey, rules);
+  }
+}
+
+function disconnectMissingRenderChildren(
+  previous: readonly Node[],
+  next: readonly Node[],
+  renderKey: RenderKey
+): void {
+  for (const child of previous) {
+    if (!next.includes(child)) {
+      removeParentEdge(child, renderKey);
+    }
+  }
+}
+
+/**
+ * Resolve the effective parent for the current render placement.
+ *
+ * Node graph invariants:
+ * - `node.parent` stores the canonical fallback parent.
+ * - `node.parentEdges` stores placement-specific parent overrides keyed by render key.
+ * - callers should treat this as the primary upward traversal surface when rebuilding
+ *   the current render path (for example, reconstructing the active Ruleset / AtRule frames).
+ * - secondary lookup lanes such as `CALLER` are intentionally not followed here; they are
+ *   opt-in traversal choices layered on top of the primary parent walk.
+ */
+export function getParent(
+  node: Node,
+  ctx: Context
+): Node | undefined {
+  for (const renderKey of getParentEdgeRenderKeys(node, ctx, node.parentEdges)) {
+    const parent = node.parentEdges?.get(renderKey);
+    if (parent !== undefined) {
+      return parent;
+    }
+  }
+  return node.parent;
+}
+
+/**
+ * Write the primary parent for a node.
+ *
+ * For canonical writes this mutates `node.parent`.
+ * For render-keyed writes this records a placement override in `node.parentEdges`
+ * without disturbing canonical parentage.
+ *
+ * This should be the default way eval/adoption code captures the "current frame"
+ * onto emitted nodes. If later serialization needs to guess the parent from text,
+ * the real bug is usually that `setParent(...)` was not called with the correct
+ * render placement when the node was created.
+ */
+export function setParent(
+  node: Node,
+  parent: Node | undefined,
+  ctx: Context
+): void {
+  if (ctx.renderKey !== undefined && ctx.renderKey !== CANONICAL) {
+    if (parent) {
+      addParentEdge(node, ctx.renderKey, parent);
+    } else {
+      removeParentEdge(node, ctx.renderKey);
+    }
+    return;
+  }
+  node.parent = parent;
+}
+
+export function isEvaluated(
+  node: Node,
+  _ctx: Context
+): boolean {
+  return node.evaluated;
+}
+
+export function setEvaluated(
+  node: Node,
+  value: boolean,
+  _ctx: Context
+): void {
+  node.evaluated = value;
+}
+
+export function isPreEvaluated(
+  node: Node,
+  _ctx: Context
+): boolean {
+  return node.preEvaluated;
+}
+
+export function setPreEvaluated(
+  node: Node,
+  value: boolean,
+  _ctx: Context
+): void {
+  node.preEvaluated = value;
+}
+
+export function getIndex(
+  node: Node,
+  _ctx: Context
+): number {
+  return node.index;
+}
+
+export function setIndex(
+  node: Node,
+  index: number,
+  _ctx: Context
+): void {
+  node.index = index;
+}
+
+export function getSourceParent(
+  node: Node,
+  _ctx: Context
+): Node | undefined {
+  return node.sourceParent;
+}
+
+export function setSourceParent(
+  node: Node,
+  parent: Node | undefined,
+  _ctx: Context
+): void {
+  node.sourceParent = parent;
+}
+
+export function getChildren(
+  rules: Rules,
+  ctx: Context
+): readonly Node[] {
+  return rules.get('value', ctx);
+}
+
+export function setChildren(
+  rules: Rules,
+  nodes: readonly Node[],
+  ctx: Context,
+  options: { markDirty?: boolean } = {}
+): void {
+  const target = resolveChildWriteTarget(rules, ctx);
+  if (target.kind === 'canonical') {
+    setRulesValueArray(rules, [...nodes]);
+    for (const node of nodes) {
+      rules.adopt(node, ctx);
+    }
+    maybeMarkScopeDirty(rules, ctx, options);
+    return;
+  }
+  if (target.kind === 'wrapper') {
+    setRulesValueArray(rules, [...nodes]);
+  }
+  disconnectMissingRenderChildren(target.currentChildren, nodes, target.renderKey);
+  connectRenderChildren(rules, nodes, target.renderKey);
+  maybeMarkScopeDirty(rules, ctx, options);
+}
+
+export function setChildAt(
+  rules: Rules,
+  index: number,
+  node: Node,
+  ctx: Context,
+  options: { markDirty?: boolean } = {}
+): void {
+  const target = resolveChildWriteTarget(rules, ctx);
+  if (target.kind !== 'canonical') {
+    if (target.currentChildren[index] === node) {
+      return;
+    }
+    const previous = target.currentChildren[index];
+    if (target.kind === 'wrapper') {
+      const nextValue = [...target.currentChildren];
+      nextValue[index] = node;
+      setRulesValueArray(rules, nextValue);
+    }
+    if (previous && previous !== node) {
+      removeParentEdge(previous, target.renderKey);
+    }
+    addEdgeAt(rules, 'value', index, target.renderKey, node);
+    addParentEdge(node, target.renderKey, rules);
+    maybeMarkScopeDirty(rules, ctx, options);
+    return;
+  }
+  const currentChildren = [...target.currentChildren];
+  const prev = currentChildren[index];
+  if (prev === node) {
+    return;
+  }
+  currentChildren[index] = node;
+  setRulesValueArray(rules, currentChildren);
+  rules.adopt(node, ctx);
+  maybeMarkScopeDirty(rules, ctx, options);
+}
+
+export function markScopeDirty(
+  _rules: Rules,
+  _ctx: Context
+): void {
+  // Registry delta tracking removed with EvalSession.
+  // Registry rebuilds from children on next access.
+}
+
+export interface EvalDependency {
+  dependsOn: Set<import('../declaration-var.js').VarDeclaration> | null;
+  sourceExpr?: Node;
+}
+
+export function getDependency(
+  node: Node,
+  ctx: Context
+): EvalDependency | null {
+  return ctx.dependencyMap.get(node) ?? null;
+}
+
+export function setDependency(
+  node: Node,
+  dependency: EvalDependency,
+  ctx: Context
+): void {
+  ctx.dependencyMap.set(node, dependency);
+}
+
+export function mergeDependencies(
+  nodes: readonly (Node | undefined)[],
+  ctx: Context
+): EvalDependency | null {
+  let merged: Set<import('../declaration-var.js').VarDeclaration> | null = null;
+  let sourceExpr: Node | undefined;
+  for (const node of nodes) {
+    if (!node) {
+      continue;
+    }
+    const dep = getDependency(node, ctx);
+    if (dep?.dependsOn && dep.dependsOn.size > 0) {
+      if (!merged) {
+        merged = new Set(dep.dependsOn);
+        sourceExpr = dep.sourceExpr;
+      } else {
+        for (const v of dep.dependsOn) {
+          merged.add(v);
+        }
+      }
+    }
+  }
+  return merged ? { dependsOn: merged, sourceExpr } : null;
+}
+
+export function isTopLevelVarDeclaration(
+  node: Node,
+  ctx: Context
+): node is import('../declaration-var.js').VarDeclaration {
+  if (!isNode(node, N.VarDeclaration)) {
+    return false;
+  }
+  const parent = getParent(node, ctx);
+  return !!parent && isNode(parent, N.Rules) && parent === ctx.root;
+}

package/src/tree/util/is-node.ts

@@ -0,0 +1,43 @@
+import type { NToNode } from '../tree.js';
+import { Node } from '../node.js';
+
+/**
+ * Fast bitmask-based node type check.
+ *
+ * With no type argument, checks if value is a Node (instanceof or duck-type).
+ * With a bitmask argument, checks if the node's type matches via bitwise AND.
+ *
+ * Examples:
+ *   isNode(x)                              // is it any node?
+ *   isNode(x, N.Selector)                  // is it any Selector subtype? (narrows to Selector)
+ *   isNode(x, N.Mixin | N.Func)           // is it a Mixin or Func? (boolean, no narrowing)
+ *   isNode(x, N.BasicSelector)            // is it specifically a BasicSelector? (narrows)
+ */
+
+export function isNode(value: unknown): value is Node;
+
+export function isNode<M extends keyof NToNode>(
+  value: unknown,
+  mask: M
+): value is NToNode[M];
+
+export function isNode(value: unknown, mask: number): boolean;
+
+export function isNode(
+  value: unknown,
+  mask?: number
+): boolean {
+  if (!value) {
+    return false;
+  }
+  if (mask === undefined) {
+    /** No-arg: check if it's any Node (including types not in the bitmask table) */
+    if (value instanceof Node) {
+      return true;
+    }
+    const record = value as Record<string, unknown>;
+    return typeof record.type === 'string' && typeof record.children === 'function';
+  }
+  const record = value as Record<string, unknown>;
+  return ((record.nodeType as number) & mask) !== 0;
+}

package/src/tree/util/list-like.ts

@@ -0,0 +1,93 @@
+import { List } from '../list.js';
+import { Sequence } from '../sequence.js';
+import { Paren } from '../paren.js';
+import { Node } from '../node.js';
+import { Rules } from '../rules.js';
+import { Ruleset } from '../ruleset.js';
+import { Mixin } from '../mixin.js';
+import { Comment } from '../comment.js';
+import { Declaration } from '../declaration.js';
+
+export type ListItems = readonly Node[];
+export type EntryKey = number | string | Node;
+
+function unwrapDirectListContainer(node: Node): List | Sequence | undefined {
+  if (node instanceof List || node instanceof Sequence) {
+    return node;
+  }
+  if (node instanceof Paren && node.get('value') instanceof Node) {
+    const inner = node.get('value');
+    if (inner instanceof List || inner instanceof Sequence) {
+      return inner;
+    }
+  }
+  return undefined;
+}
+
+export function isListContainer(node: Node): boolean {
+  return unwrapDirectListContainer(node) !== undefined;
+}
+
+export function getListItems(node: Node): ListItems | undefined {
+  const container = unwrapDirectListContainer(node);
+  return container?.get('value');
+}
+
+export function isBracketedList(node: Node): boolean {
+  if (node instanceof Paren) {
+    return (node.options?.delimiter ?? 'paren') === 'square' && unwrapDirectListContainer(node) !== undefined;
+  }
+  const parent = node.parent;
+  return parent instanceof Paren
+    && parent.get('value') === node
+    && (parent.options?.delimiter ?? 'paren') === 'square'
+    && unwrapDirectListContainer(parent) !== undefined;
+}
+
+export function getListSeparator(node: Node): ',' | ';' | '/' | ' ' {
+  const container = unwrapDirectListContainer(node);
+  if (container instanceof List) {
+    return container.options?.sep ?? ' ';
+  }
+  return ' ';
+}
+
+export function coerceListItems(node: Node): ListItems {
+  if (node instanceof List && node.length === 1 && node.get('value')[0] instanceof Sequence) {
+    return node.get('value')[0].get('value');
+  }
+  return getListItems(node) ?? [node];
+}
+
+export function* iterateItems(input: Node): Generator<[Node, EntryKey]> {
+  const items = getListItems(input);
+  if (items) {
+    for (let key = 0; key < items.length; key++) {
+      const value = items[key];
+      if (value) {
+        yield [value, key];
+      }
+    }
+    return;
+  }
+
+  if (input instanceof Rules || input instanceof Ruleset || input instanceof Mixin) {
+    const rules = input instanceof Rules
+      ? input.value
+      : input instanceof Ruleset
+        ? input.get('rules')?.value ?? []
+        : input.get('rules')?.value ?? [];
+    for (const rule of rules) {
+      if (!rule || rule instanceof Comment) {
+        continue;
+      }
+      if (!(rule instanceof Declaration)) {
+        continue;
+      }
+      yield [rule.get('value'), rule.get('name')];
+    }
+    return;
+  }
+
+  yield [input, 0];
+}