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

package/{lib/types/modes.d.ts → src/types/modes.ts}

@@ -4,6 +4,7 @@
  * Kept in `@jesscss/core` to avoid cyclic workspace dependencies with `styles-config`.
  */
 export type MathMode = 'always' | 'parens-division' | 'parens' | 'strict';
+
 /**
  * Unit conversion modes.
  *
@@ -14,6 +15,7 @@ export type MathMode = 'always' | 'parens-division' | 'parens' | 'strict';
  * Kept in `@jesscss/core` to avoid cyclic workspace dependencies with `styles-config`.
  */
 export type UnitMode = 'loose' | 'preserve' | 'strict';
+
 /**
  * Equality modes for guard/comparison semantics.
  *
@@ -21,4 +23,3 @@ export type UnitMode = 'loose' | 'preserve' | 'strict';
  * - `strict`: type-strict equality behavior
  */
 export type EqualityMode = 'coerce' | 'strict';
-//# sourceMappingURL=modes.d.ts.map

package/src/types.d.ts

@@ -0,0 +1,9 @@
+declare interface Set<T> {
+  union<U>(b: Set<U>): Set<T | U>;
+  intersection<U>(b: Set<U>): Set<T | U>;
+  difference<U>(b: Set<U>): Set<T | U>;
+  symmetricDifference<U>(b: Set<U>): Set<T | U>;
+  isSubsetOf<U>(b: Set<U>): boolean;
+  isSupersetOf<U>(b: Set<U>): boolean;
+  isDisjointFrom<U>(b: Set<U>): boolean;
+}

package/src/types.ts

@@ -0,0 +1,68 @@
+import type { PluginInterface } from './plugin';
+export type ExtendSelectorKind = 'simple' | 'basic' | 'pseudo' | 'complex' | 'compound';
+
+export const enum MathMode {
+  /**
+   * @note - A Jess file always performs math for expressions,
+   * but that's because expressions are only parsed as such
+   * when wrapped with `$()`, whereas Less & SCSS try to
+   * parse expressions in regular value sequences.
+   */
+  ALWAYS = 0,
+  PARENS_DIVISION = 1,
+  PARENS = 2
+}
+
+export const enum UnitMode {
+  /** Less's default 1.x-4.x */
+  LOOSE = 0,
+  /**
+   * @todo - I think Less's current strict unit mode is weirder,
+   * so this may need another mode depending on behavior. But
+   * if it's too weird, it could be a breaking change.
+   */
+  STRICT = 1
+}
+
+export interface StylesConfig {
+  compile?: {
+    plugins?: PluginInterface[];
+    searchPaths?: string[];
+    enableJavaScript?: boolean;
+    mathMode?: MathMode;
+    unitMode?: UnitMode;
+    allowExtendSelectors?: ExtendSelectorKind[];
+  };
+  output?: {
+    collapseNesting?: boolean;
+    compress?: boolean;
+    sourceMap?: boolean;
+  };
+  language?: {
+    less?: LessOptions;
+    [key: string]: LessOptions | Record<string, any> | undefined;
+    // Future: scss?: ScssOptions, css?: CssOptions, etc.
+  };
+}
+
+export interface LessOptions {
+  allowExtendSelectors?: ExtendSelectorKind[];
+  mathMode?: MathMode;
+  unitMode?: UnitMode;
+  dumpLineNumbers?: string;
+  relativeUrls?: boolean;
+  compress?: boolean;
+  strictMath?: boolean;
+  strictUnits?: boolean;
+  javascriptEnabled?: boolean;
+  sourceMap?: boolean;
+  globalVars?: Record<string, any>;
+  modifyVars?: Record<string, any>;
+  urlArgs?: string;
+  rewriteUrls?: boolean;
+  rootpath?: string;
+  paths?: string[];
+  plugin?: any;
+  processImports?: boolean;
+  syncImport?: boolean;
+}

package/src/use-webpack-resolver.ts

@@ -0,0 +1,56 @@
+// jess/useWebpackResolver.ts
+import path from 'node:path';
+import fs from 'node:fs';
+import {
+  ResolverFactory,
+  CachedInputFileSystem
+} from 'enhanced-resolve';
+import type { PluginInterface } from './plugin.js';
+
+const { isArray } = Array;
+
+type WebpackResolverInstance = { apply(resolver: any): void };
+export type WebpackResolverCtor<Opts> = new (opts?: Opts) => WebpackResolverInstance;
+type InferCtorOpts<C> = C extends new (opts?: infer O) => any ? O : never;
+
+export function useWebpackResolver<Ctor extends WebpackResolverCtor<any>>(
+  CtorRef: Ctor
+): (opts?: InferCtorOpts<Ctor>) => PluginInterface {
+  return (opts?: InferCtorOpts<Ctor>): PluginInterface => {
+    const fileSystem = new CachedInputFileSystem(fs as any, 4000);
+    const pluginInstance: WebpackResolverInstance = new CtorRef(opts as any);
+
+    const er = ResolverFactory.createResolver({
+      fileSystem,
+      plugins: [pluginInstance]
+    });
+
+    const resolveOnce = (basedir: string, request: string) =>
+      new Promise<string | null>((resolve) => {
+        er.resolve({}, basedir, request, {}, (err, out) => {
+          resolve(err ? null : (out as string));
+        });
+      });
+
+    return {
+      name: `webpack-resolver(${CtorRef.name || 'ctor'})`,
+      async resolve(filePath, currentDir, searchPaths) {
+        const bases = [currentDir, ...searchPaths];
+        const out: string[] = [];
+        const seen = new Set<string>();
+        filePath = isArray(filePath) ? filePath : [filePath];
+        for (const base of bases) {
+          const baseDir = path.isAbsolute(base) ? base : path.resolve(currentDir, base);
+          for (const path of filePath) {
+            const abs = await resolveOnce(baseDir, path);
+            if (abs && !seen.has(abs)) {
+              seen.add(abs);
+              out.push(abs);
+            }
+          }
+        }
+        return out;
+      }
+    };
+  };
+}

package/src/visitor/__tests__/visitor.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest';
+import { Visitor, TreeVisitor, ABORT } from '../index.js';
+import { ruleset, rules, decl, any } from '../../tree/index.js';
+
+describe('Visitor Pattern', () => {
+  describe('accept() method', () => {
+    it('should visit node itself first, then children', () => {
+      const visited: string[] = [];
+
+      const visitor = {
+        enter: (node: any) => {
+          visited.push(`enter:${node?.type}`);
+        },
+        ruleset: (node: any) => {
+          visited.push(`ruleset`);
+          return node;
+        },
+        declaration: (node: any) => {
+          visited.push(`declaration`);
+          return node;
+        }
+      } as Visitor;
+
+      const declaration = decl({ name: 'color', value: any('red') });
+      const rs = ruleset({ selector: null as any, rules: rules([declaration]) });
+
+      rs.accept(visitor);
+
+      // Should visit ruleset first, then declaration
+      expect(visited).toContain('enter:Ruleset');
+      expect(visited).toContain('ruleset');
+      expect(visited).toContain('enter:Declaration');
+      expect(visited).toContain('declaration');
+
+      // Ruleset should be visited before declaration
+      const rulesetIndex = visited.findIndex(v => v === 'ruleset');
+      const declIndex = visited.findIndex(v => v === 'declaration');
+      expect(rulesetIndex).toBeLessThan(declIndex);
+    });
+
+    it('should handle node replacement', () => {
+      const visitor = {
+        declaration: (node: any) => {
+          return decl({ name: 'background', value: any('blue') });
+        }
+      } as unknown as Visitor;
+
+      const declaration = decl({ name: 'color', value: any('red') });
+      const result = declaration.accept(visitor);
+
+      expect(result.type).toBe('Declaration');
+      expect((result as any).name.valueOf()).toBe('background');
+    });
+
+    it('should recursively visit children', () => {
+      const visited: string[] = [];
+
+      const visitor = {
+        ruleset: (node: any) => {
+          visited.push('ruleset');
+          return node;
+        },
+        declaration: (node: any) => {
+          visited.push('declaration');
+          return node;
+        }
+      } as Visitor;
+
+      const decl1 = decl({ name: 'color', value: any('red') });
+      const decl2 = decl({ name: 'background', value: any('blue') });
+      const rs = ruleset({ selector: null as any, rules: rules([decl1, decl2]) });
+
+      rs.accept(visitor);
+
+      expect(visited.filter(v => v === 'ruleset')).toHaveLength(1);
+      expect(visited.filter(v => v === 'declaration')).toHaveLength(2);
+    });
+  });
+
+  describe('TreeVisitor with accept()', () => {
+    it('should use accept() if node has it, avoiding double-visiting', () => {
+      const visited: string[] = [];
+
+      class TestVisitor extends TreeVisitor {
+        override ruleset(node: any) {
+          visited.push('ruleset');
+          return node;
+        }
+
+        override declaration(node: any) {
+          visited.push('declaration');
+          return node;
+        }
+      }
+
+      const visitor = new TestVisitor();
+      const declaration = decl({ name: 'color', value: any('red') });
+      const rs = ruleset({ selector: null as any, rules: rules([declaration]) });
+
+      visitor.visit(rs);
+
+      // Should visit each node exactly once (no double-visiting)
+      expect(visited.filter(v => v === 'ruleset')).toHaveLength(1);
+      expect(visited.filter(v => v === 'declaration')).toHaveLength(1);
+    });
+  });
+
+  describe('Visitor return values', () => {
+    it('should handle ABORT symbol', () => {
+      const visited: string[] = [];
+
+      const visitor = {
+        enter: () => {
+          visited.push('enter');
+          return ABORT;
+        },
+        ruleset: () => {
+          visited.push('ruleset');
+        }
+      } as unknown as Visitor;
+
+      const rs = ruleset({ selector: null as any, rules: rules([]) });
+      const visitorInstance = new (class extends Visitor {
+        override visit(n: any) {
+          return super.visit(n);
+        }
+      })();
+      Object.assign(visitorInstance, visitor);
+      rs.accept(visitorInstance);
+
+      // Should stop after enter returns ABORT
+      expect(visited).toContain('enter');
+      expect(visited).not.toContain('ruleset');
+    });
+  });
+});

package/src/visitor/index.ts

@@ -0,0 +1,263 @@
+import {
+  Node,
+  type NodeVisitReturn,
+  ABORT,
+  REMOVE
+} from '../tree/node.js';
+// import { type isNode } from '../tree/util'
+import type * as tree from '../tree/index.js';
+
+// const { isArray } = Array
+
+// type GuardedType<T> = typeof isNode extends (value: any, type: T) => value is infer U ? U : never
+
+const lowerFirst = (s: string) => s.charAt(0).toLowerCase() + s.slice(1);
+export { ABORT, REMOVE };
+export const SKIP: unique symbol = Symbol('SKIP');
+
+type VisitorReturn = NodeVisitReturn | typeof SKIP;
+export type VisitorContext = {
+  visitDeeper?: boolean;
+};
+
+/**
+ * Define all the optional methods one can define on a visitor that can be visited
+ *
+ * @todo - Write type tests for methods
+ */
+export interface Visitor {
+
+  /** Optional methods called before entering / exiting the visitor */
+  enter?(n?: tree.Node): void | typeof ABORT;
+  /**
+   * `exit()` gets passed the top-most visitor result,
+   * in case we want to transform it on the way out.
+   */
+  exit?(val?: NodeVisitReturn): NodeVisitReturn;
+
+  /** Visitor methods */
+  atRule?(n: tree.AtRule, ctx?: VisitorContext): VisitorReturn;
+  atRuleExit?(n: tree.AtRule, ctx?: VisitorContext): void;
+  block?(n: tree.Block, ctx?: VisitorContext): VisitorReturn;
+  blockExit?(n: tree.Block, ctx?: VisitorContext): void;
+  bool?(n: tree.Bool, ctx?: VisitorContext): VisitorReturn;
+  boolExit?(n: tree.Bool, ctx?: VisitorContext): void;
+  ampersand?(n: tree.Ampersand, ctx?: VisitorContext): VisitorReturn;
+  ampersandExit?(n: tree.Ampersand, ctx?: VisitorContext): void;
+  any?(n: tree.Any, ctx?: VisitorContext): VisitorReturn;
+  anyExit?(n: tree.Any, ctx?: VisitorContext): void;
+  anonymous?(n: tree.Anonymous, ctx?: VisitorContext): VisitorReturn;
+  anonymousExit?(n: tree.Anonymous, ctx?: VisitorContext): void;
+  call?(n: tree.Call, ctx?: VisitorContext): VisitorReturn;
+  callExit?(n: tree.Call, ctx?: VisitorContext): void;
+  collection?(n: tree.Collection, ctx?: VisitorContext): VisitorReturn;
+  collectionExit?(n: tree.Collection, ctx?: VisitorContext): void;
+  color?(n: tree.Color, ctx?: VisitorContext): VisitorReturn;
+  colorExit?(n: tree.Color, ctx?: VisitorContext): void;
+  comment?(n: tree.Comment, ctx?: VisitorContext): VisitorReturn;
+  commentExit?(n: tree.Comment, ctx?: VisitorContext): void;
+  combinator?(n: tree.Combinator, ctx?: VisitorContext): VisitorReturn;
+  combinatorExit?(n: tree.Combinator, ctx?: VisitorContext): void;
+  condition?(n: tree.Condition, ctx?: VisitorContext): VisitorReturn;
+  conditionExit?(n: tree.Condition, ctx?: VisitorContext): void;
+  customDeclaration?(n: tree.CustomDeclaration, ctx?: VisitorContext): VisitorReturn;
+  customDeclarationExit?(n: tree.CustomDeclaration, ctx?: VisitorContext): void;
+  declaration?(n: tree.Declaration): VisitorReturn;
+  declarationExit?(n: tree.Declaration, ctx?: VisitorContext): void;
+  dimension?(n: tree.Dimension, ctx?: VisitorContext): VisitorReturn;
+  dimensionExit?(n: tree.Dimension, ctx?: VisitorContext): void;
+  expression?(n: tree.Expression, ctx?: VisitorContext): VisitorReturn;
+  expressionExit?(n: tree.Expression, ctx?: VisitorContext): void;
+  extend?(n: tree.Extend, ctx?: VisitorContext): VisitorReturn;
+  extendExit?(n: tree.Extend, ctx?: VisitorContext): void;
+  list?(n: tree.List<Node>, ctx?: VisitorContext): VisitorReturn;
+  listExit?(n: tree.List<Node>, ctx?: VisitorContext): void;
+  mixin?(n: tree.Mixin, ctx?: VisitorContext): VisitorReturn;
+  mixinExit?(n: tree.Mixin, ctx?: VisitorContext): void;
+  negative?(n: tree.Negative, ctx?: VisitorContext): VisitorReturn;
+  negativeExit?(n: tree.Negative, ctx?: VisitorContext): void;
+  func?(n: tree.Func, ctx?: VisitorContext): VisitorReturn;
+  funcExit?(n: tree.Func, ctx?: VisitorContext): void;
+  jsFunction?(n: tree.JsFunction): VisitorReturn;
+  jsFunctionExit?(n: tree.JsFunction, ctx?: VisitorContext): void;
+  nil?(n: tree.Nil, ctx?: VisitorContext): VisitorReturn;
+  nilExit?(n: tree.Nil, ctx?: VisitorContext): void;
+  operation?(n: tree.Operation, ctx?: VisitorContext): VisitorReturn;
+  operationExit?(n: tree.Operation, ctx?: VisitorContext): void;
+  paren?(n: tree.Paren, ctx?: VisitorContext): VisitorReturn;
+  parenExit?(n: tree.Paren, ctx?: VisitorContext): void;
+  queryCondition?(n: tree.QueryCondition, ctx?: VisitorContext): VisitorReturn;
+  queryConditionExit?(n: tree.QueryCondition, ctx?: VisitorContext): void;
+  quoted?(n: tree.Quoted, ctx?: VisitorContext): VisitorReturn;
+  quotedExit?(n: tree.Quoted, ctx?: VisitorContext): void;
+  ruleset?(n: tree.Ruleset, ctx?: VisitorContext): VisitorReturn;
+  rulesetExit?(n: tree.Ruleset, ctx?: VisitorContext): void;
+  rules?(n: tree.Rules, ctx?: VisitorContext): VisitorReturn;
+  rulesExit?(n: tree.Rules, ctx?: VisitorContext): void;
+  attributeSelector?(n: tree.AttributeSelector, ctx?: VisitorContext): VisitorReturn;
+  attributeSelectorExit?(n: tree.AttributeSelector, ctx?: VisitorContext): void;
+  basicSelector?(n: tree.BasicSelector, ctx?: VisitorContext): VisitorReturn;
+  basicSelectorExit?(n: tree.BasicSelector, ctx?: VisitorContext): void;
+  selectorList?(n: tree.SelectorList, ctx?: VisitorContext): VisitorReturn;
+  selectorListExit?(n: tree.SelectorList, ctx?: VisitorContext): void;
+  pseudoSelector?(n: tree.PseudoSelector, ctx?: VisitorContext): VisitorReturn;
+  pseudoSelectorExit?(n: tree.PseudoSelector, ctx?: VisitorContext): void;
+  compoundSelector?(n: tree.CompoundSelector, ctx?: VisitorContext): VisitorReturn;
+  compoundSelectorExit?(n: tree.CompoundSelector, ctx?: VisitorContext): void;
+  complexSelector?(n: tree.ComplexSelector, ctx?: VisitorContext): VisitorReturn;
+  complexSelectorExit?(n: tree.ComplexSelector, ctx?: VisitorContext): void;
+  sequence?(n: tree.Sequence, ctx?: VisitorContext): VisitorReturn;
+  sequenceExit?(n: tree.Sequence, ctx?: VisitorContext): void;
+  varDeclaration?(n: tree.VarDeclaration, ctx?: VisitorContext): VisitorReturn;
+  varDeclarationExit?(n: tree.VarDeclaration, ctx?: VisitorContext): void;
+  reference?(n: tree.Reference, ctx?: VisitorContext): VisitorReturn;
+  referenceExit?(n: tree.Reference, ctx?: VisitorContext): void;
+  styleImport?(n: tree.StyleImport, ctx?: VisitorContext): VisitorReturn;
+  styleImportExit?(n: tree.StyleImport, ctx?: VisitorContext): void;
+  interpolated?(n: tree.Interpolated, ctx?: VisitorContext): VisitorReturn;
+  interpolatedExit?(n: tree.Interpolated, ctx?: VisitorContext): void;
+  defaultGuard?(n: tree.DefaultGuard, ctx?: VisitorContext): VisitorReturn;
+  defaultGuardExit?(n: tree.DefaultGuard, ctx?: VisitorContext): void;
+  rest?(n: tree.Rest, ctx?: VisitorContext): VisitorReturn;
+  restExit?(n: tree.Rest, ctx?: VisitorContext): void;
+}
+
+export abstract class Visitor {
+  private readonly _methodMap = new Map<string, ((n: Node, ctx?: VisitorContext) => VisitorReturn) | false>();
+  /** Temporary state, set on first visit and later un-set when exiting */
+  protected startNode: Node | undefined;
+
+  getMethod(s: string) {
+    let lower = this._methodMap.get(s);
+    /**
+     * if we previously looked for the method and it doesn't exist,
+     * then explicitly set the map record to false.
+     */
+    if (!lower && lower !== false) {
+      // @ts-expect-error - Its ok if it doesn't exist
+      lower = this[lowerFirst(s)];
+      this._methodMap.set(s, lower ?? false);
+    }
+    return lower;
+  }
+
+  protected _visit(n: Node, ctx?: VisitorContext): VisitorReturn {
+    let fn = this.getMethod(n.type);
+    if (fn) {
+      return fn.call(this, n, ctx) ?? n;
+    }
+    return n;
+  }
+
+  visitExit(n: Node, ctx?: VisitorContext) {
+    let fn = this.getMethod(`${n.type}Exit`);
+    if (fn) {
+      fn.call(this, n, ctx);
+    }
+  }
+
+  /**
+   * Visit will always return a Node
+   */
+  visit(n: Node): Node {
+    this.startNode = n;
+    const originalVisit = this.visit;
+    /**
+     * Bind to inner _visit, so that all inner calls will not call this current method again
+     */
+    this.visit = this._visit.bind(this) as typeof this.visit;
+    let possibleAbort = this.enter?.(n);
+    if (possibleAbort === ABORT) {
+      return n;
+    }
+    let returnVal = this._visit(n);
+    this.visit = originalVisit.bind(this);
+    /** Apply any final transformations / decisions */
+    returnVal = this.exit?.(returnVal) ?? returnVal;
+    this.startNode = undefined;
+    if (returnVal instanceof Node) {
+      return returnVal;
+    }
+    return n;
+  }
+}
+
+/**
+ * This is a specific visitor type that auto-walks the tree,
+ * and optionally mutates children nodes.
+ *
+ * @note If you are extending this class, you DO NOT HAVE TO
+ * manually visit children nodes. This class will do it for you.
+ */
+export abstract class TreeVisitor extends Visitor {
+  /** Visit children nodes before or after visiting the parent node */
+  visitChildren: 'before' | 'after' = 'after';
+  visitedNodes = new Set<Node>();
+
+  constructor(
+    public reverse?: boolean
+  ) {
+    super();
+  }
+
+  override enter(n: tree.Node) {
+    this.visitedNodes.clear();
+  }
+
+  override _visit(n: Node, ctx: VisitorContext) {
+    if (this.visitedNodes.has(n)) {
+      return n;
+    }
+    this.visitedNodes.add(n);
+    const { reverse } = this;
+
+    // If node has accept() method, let it control traversal
+    // This allows nodes to customize traversal (e.g., Less.js compatibility)
+    // accept() will visit self and children, so we don't auto-visit here
+    const hasAccept = n.accept && typeof n.accept === 'function';
+    const hasCustomAccept = hasAccept && n.accept !== Node.prototype.accept;
+    if (hasCustomAccept) {
+      const returnVal = n.accept(this);
+      if (!returnVal || typeof returnVal === 'symbol') {
+        return returnVal;
+      }
+      // accept() already visited self and children, so we just handle exit
+      this.visitExit(n, ctx);
+      if (returnVal instanceof Node) {
+        this.visitedNodes.add(returnVal);
+      }
+      return returnVal;
+    }
+
+    // Default: auto-visit children (node doesn't have accept() or doesn't override it)
+    if (this.visitChildren === 'before') {
+      for (const node of n.children(true, reverse, true)) {
+        this._visit(node, ctx);
+      }
+      const returnVal = super._visit(n, ctx);
+      /** @node The exit function passes in the original node */
+      this.visitExit(n, ctx);
+      /** Don't visit new created nodes */
+      if (returnVal instanceof Node) {
+        this.visitedNodes.add(returnVal);
+      }
+      return returnVal;
+    }
+    let returnVal = super._visit(n, ctx);
+    if (!returnVal || typeof returnVal === 'symbol') {
+      return returnVal;
+    }
+
+    if (returnVal !== n) {
+      /** Don't visit new created nodes */
+      this.visitedNodes.add(returnVal);
+    } else {
+      for (const node of n.children(true, reverse, true)) {
+        this._visit(node, ctx);
+      }
+    }
+
+    this.visitExit(n, ctx);
+    return returnVal;
+  }
+}

package/{lib/visitor/less-visitor.js → src/visitor/less-visitor.ts}

@@ -1,7 +1,8 @@
 import { Visitor } from './index.js';
+
 /**
  * A visitor adapter for legacy Less plugins
  */
 export class LessVisitor extends Visitor {
-}
-//# sourceMappingURL=less-visitor.js.map
+
+}