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

package/src/tree/util/serialize-types.ts

@@ -0,0 +1,318 @@
+import { Node } from '../node.js';
+
+export type SerializeTypesOptions = {
+  // Include primitive main values next to the type when useful
+  showValues?: boolean;
+  // Include options next to the type when useful
+  showOptions?: boolean;
+  // Max length for printed strings; longer strings are truncated with …
+  maxStringLength?: number;
+  // Use shortType instead of type
+  useShortType?: boolean;
+  // Indentation size in spaces
+  indentSize?: number;
+};
+
+const defaultOptions: Required<SerializeTypesOptions> = {
+  showValues: true,
+  showOptions: false,
+  maxStringLength: 40,
+  useShortType: false,
+  indentSize: 2
+};
+
+function isJessNode(value: unknown): value is Node {
+  return value instanceof Node;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && !Array.isArray(value) && typeof value === 'object';
+}
+
+function truncate(str: string, max: number): string {
+  if (str.length <= max) {
+    return str;
+  }
+  return `${str.slice(0, max - 1)}…`;
+}
+
+function formatPrimitive(value: unknown, opts: Required<SerializeTypesOptions>): string {
+  if (typeof value === 'string') {
+    const content = truncate(value, opts.maxStringLength);
+    return `'${content.replace(/'/g, '\\\'')}'`;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  if (value === null) {
+    return 'null';
+  }
+  if (value === undefined) {
+    return 'undefined';
+  }
+  return String(value);
+}
+
+function indent(depth: number, size: number): string {
+  return ''.padStart(depth * size);
+}
+
+function summarizeArray(items: unknown[], opts: Required<SerializeTypesOptions>): string {
+  // For non-node arrays emit a compact summary: [a, b]
+  const parts = items.map((item) => {
+    if (isJessNode(item)) {
+      return opts.useShortType ? (item as any).shortType : (item as any).type;
+    }
+    if (Array.isArray(item)) {
+      return '[' + summarizeArray(item, opts) + ']';
+    }
+    return formatPrimitive(item, opts);
+  });
+  return parts.join(', ');
+}
+
+function serializeArray(arr: unknown[], depth: number, opts: Required<SerializeTypesOptions>, visiting: Set<Node>): string {
+  const pad = indent(depth, opts.indentSize);
+  if (arr.length === 0) {
+    return `${pad}[]`;
+  }
+  const first = arr[0];
+  if (isJessNode(first)) {
+    const inner = arr.map(item => serializeNode(item as Node, depth + 1, opts, visiting)).join('\n');
+    return `${pad}[\n${inner}\n${pad}]`;
+  }
+  // Not a node array; show compact
+  return `${pad}[${summarizeArray(arr, opts)}]`;
+}
+
+function serializePlainObject(obj: Record<string, unknown>, depth: number, opts: Required<SerializeTypesOptions>, visiting: Set<Node>): string {
+  const keys = Object.keys(obj).filter(k => obj[k] !== undefined);
+  if (keys.length === 0) {
+    return '';
+  }
+  const lines: string[] = [];
+  for (const key of keys) {
+    const v = obj[key];
+    if (isJessNode(v)) {
+      const inner = '\n' + serializeNode(v, depth + 2, opts, visiting);
+      lines.push(`${indent(depth + 1, opts.indentSize)}${key}: ${inner}`);
+    } else if (Array.isArray(v)) {
+      const inner = serializeArray(v, depth + 2, opts, visiting);
+      lines.push(`${indent(depth + 1, opts.indentSize)}${key}:\n${inner}`);
+    } else if (isPlainObject(v)) {
+      const inner = serializePlainObject(v as Record<string, unknown>, depth + 1, opts, visiting);
+      if (inner) {
+        lines.push(`${indent(depth + 1, opts.indentSize)}${key}: {\n${inner}\n${indent(depth + 1, opts.indentSize)}}`);
+      } else {
+        lines.push(`${indent(depth + 1, opts.indentSize)}${key}: {}`);
+      }
+    } else {
+      lines.push(`${indent(depth + 1, opts.indentSize)}${key}: ${formatPrimitive(v, opts)}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function serializeNodeOptions(n: Node, depth: number, opts: Required<SerializeTypesOptions>, visiting: Set<Node>): string | null {
+  if (!opts.showOptions) {
+    return null;
+  }
+  const nodeOptions = (n as any).options;
+  if (!nodeOptions || typeof nodeOptions !== 'object') {
+    return null;
+  }
+  // Check if there are any non-undefined properties
+  const keys = Object.keys(nodeOptions).filter(k => nodeOptions[k] !== undefined);
+  if (keys.length === 0) {
+    return null;
+  }
+  return serializePlainObject(nodeOptions, depth + 1, opts, visiting);
+}
+
+function getNodeRole(n: Node): string | undefined {
+  return (n as any).role ?? (n as any).options?.role;
+}
+
+function getNodeValue(n: Node): unknown {
+  const childKeys = (n.constructor as typeof Node).childKeys;
+  const NODE_INTERNAL = new Set([
+    'parent', 'index', 'frames', 'pre', 'post', 'state', 'nodeType',
+    'preEvaluated', 'evaluated',
+    'renderKey',
+    'isSelector', 'keySetLibrary', 'role',
+    'fullRender',
+    'rulesetRegistry', 'mixinRegistry', 'declarationRegistry', 'functionRegistry',
+    'rulesIndexed', '_indexing',
+    '_valueOf', '_keySet', '_visibleKeySet', '_requiredKeySet'
+  ]);
+
+  if ((n as any).type === 'Color') {
+    const color = n as any;
+    const value: Record<string, unknown> = {};
+    if (color._nodeValue !== undefined) {
+      value.node = color._nodeValue;
+    }
+    if (color._rgbChannels !== undefined) {
+      value.rgb = color.rgb;
+    }
+    if (color._hslChannels !== undefined) {
+      value.hsl = color.hsl;
+    }
+    if (color._alphaValue !== undefined) {
+      value.alpha = color.alpha;
+    }
+    return Object.keys(value).length > 0 ? value : undefined;
+  }
+
+  if (Array.isArray(childKeys)) {
+    if (childKeys.length === 1) {
+      return (n as any)[childKeys[0]!];
+    }
+
+    const obj: Record<string, unknown> = {};
+    for (const key of childKeys) {
+      const value = (n as any)[key];
+      if (value !== undefined) {
+        obj[key] = value;
+      }
+    }
+    for (const key of Object.keys(n)) {
+      if (key.startsWith('_') || NODE_INTERNAL.has(key) || childKeys.includes(key)) {
+        continue;
+      }
+      const value = (n as any)[key];
+      if (value !== undefined) {
+        obj[key] = value;
+      }
+    }
+    return Object.keys(obj).length > 0 ? obj : undefined;
+  }
+
+  const directValue = (n as any).value as unknown;
+  if (directValue !== undefined) {
+    return directValue;
+  }
+
+  const obj: Record<string, unknown> = {};
+  for (const key of Object.keys(n)) {
+    if (key.startsWith('_') || NODE_INTERNAL.has(key)) {
+      continue;
+    }
+    const value = (n as any)[key];
+    if (value !== undefined && !isJessNode(value) && !Array.isArray(value)) {
+      obj[key] = value;
+    }
+  }
+  return Object.keys(obj).length > 0 ? obj : undefined;
+}
+
+function serializeNode(n: Node, depth: number, opts: Required<SerializeTypesOptions>, visiting: Set<Node>): string {
+  const typeName = opts.useShortType ? (n as any).shortType : (n as any).type;
+  const pad = indent(depth, opts.indentSize);
+  const role = getNodeRole(n);
+  const meta = role ? ` [role=${role}]` : '';
+  const open = `${pad}(${typeName}${meta}`;
+
+  // Protect against cycles
+  if (visiting.has(n)) {
+    return `${open} …)`;
+  }
+  visiting.add(n);
+
+  const value = getNodeValue(n);
+  const optionsStr = serializeNodeOptions(n, depth, opts, visiting);
+
+  // If the main value is a primitive, include it inline
+  if (
+    value === null
+    || value === undefined
+    || typeof value === 'string'
+    || typeof value === 'number'
+    || typeof value === 'boolean'
+  ) {
+    visiting.delete(n);
+    if (optionsStr) {
+      if (opts.showValues && value !== undefined) {
+        const rendered = formatPrimitive(value, opts);
+        return `${open}\n${optionsStr}\n${indent(depth + 1, opts.indentSize)}${rendered}\n${pad})`;
+      }
+      return `${open}\n${optionsStr}\n${pad})`;
+    }
+    if (opts.showValues && value !== undefined) {
+      const rendered = formatPrimitive(value, opts);
+      return `${open} ${rendered})`;
+    }
+    return `${open})`;
+  }
+
+  // If the main value is a Node, print it on next line
+  if (isJessNode(value)) {
+    const inner = '\n' + serializeNode(value, depth + 1, opts, visiting);
+    visiting.delete(n);
+    if (optionsStr) {
+      return `${open}\n${optionsStr}${inner}\n${pad})`;
+    }
+    return `${open}${inner}\n${pad})`;
+  }
+
+  // Special-case Number plain object: print compact form
+  if (typeName === 'Num' && isPlainObject(value)) {
+    const num = (value as any).number;
+    const keys = Object.keys(value as Record<string, unknown>).filter(k => (value as any)[k] !== undefined);
+    if (typeof num === 'number' && (keys.length === 1 || (keys.length === 0))) {
+      visiting.delete(n);
+      if (optionsStr) {
+        return `${open}\n${optionsStr}\n${indent(depth + 1, opts.indentSize)}${num}\n${pad})`;
+      }
+      return `${open} ${num})`;
+    }
+  }
+
+  // If the main value is an array
+  if (Array.isArray(value)) {
+    const arrStr = serializeArray(value, depth + 1, opts, visiting);
+    visiting.delete(n);
+    if (optionsStr) {
+      return `${open}\n${optionsStr}\n${arrStr}\n${pad})`;
+    }
+    return `${open}\n${arrStr}\n${pad})`;
+  }
+
+  // If the main value is a plain object, print key: value summaries
+  if (isPlainObject(value)) {
+    const inner = serializePlainObject(value as Record<string, unknown>, depth, opts, visiting);
+    visiting.delete(n);
+    if (optionsStr) {
+      return `${open}\n${optionsStr}${inner ? '\n' + inner : ''}\n${pad})`;
+    }
+    return inner ? `${open}\n${inner}\n${pad})` : `${open})`;
+  }
+
+  visiting.delete(n);
+  if (optionsStr) {
+    return `${open}\n${optionsStr}\n${pad})`;
+  }
+  return `${open})`;
+}
+
+function serializeUnknown(value: unknown, depth: number, opts: Required<SerializeTypesOptions>, visiting: Set<Node>): string {
+  if (isJessNode(value)) {
+    return serializeNode(value, depth, opts, visiting);
+  }
+  if (Array.isArray(value)) {
+    const arr = summarizeArray(value, opts);
+    return `${indent(depth, opts.indentSize)}[${arr}]`;
+  }
+  if (isPlainObject(value)) {
+    const keys = Object.keys(value);
+    const parts = keys.map(k => `${k}: ${formatPrimitive((value as Record<string, unknown>)[k], opts)}`);
+    return `${indent(depth, opts.indentSize)}{ ${parts.join(', ')} }`;
+  }
+  return `${indent(depth, opts.indentSize)}${formatPrimitive(value, opts)}`;
+}
+
+export function serializeTypes(value: unknown, options?: SerializeTypesOptions): string {
+  const opts: Required<SerializeTypesOptions> = { ...defaultOptions, ...(options ?? {}) };
+  const visiting = new Set<Node>();
+  return serializeUnknown(value, 0, opts, visiting);
+}

package/src/tree/util/should-operate.ts

@@ -0,0 +1,78 @@
+import type { MathMode } from '../../types/modes.js';
+import type { Operator } from './calculate.js';
+import { isNode } from './is-node.js';
+import { N } from '../node-type.js';
+import type { Node } from '../node.js';
+
+export type MathFrameState = {
+  mathMode: MathMode;
+  /**
+   * Boolean stack. The current frame is the top-most value.
+   * - `true` enables Less/Sass "math in parens" semantics
+   * - `false` explicitly disables it (e.g. for call args)
+   */
+  parenFrames: ReadonlyArray<boolean>;
+  /** Number stack, modeled as a depth counter */
+  calcFrames: number;
+};
+
+export function isInParens(parenFrames: ReadonlyArray<boolean>): boolean {
+  return parenFrames.at(-1) ?? false;
+}
+
+/**
+ * Shared calculation decision logic for both eval-time (`Context.shouldOperate`)
+ * and parse-time decisions (Less→Jess conversion).
+ *
+ * This must remain behaviorally equivalent to `Context.shouldOperate`.
+ */
+export function shouldOperateWithMathFrames(
+  state: MathFrameState,
+  op: Operator,
+  left: Node,
+  right: Node
+): boolean {
+  const { mathMode, calcFrames } = state;
+  const inParens = isInParens(state.parenFrames);
+  const inCalc = calcFrames !== 0;
+
+  if (inCalc) {
+    /** Only collapse safe units */
+    if (isNode(left, N.Dimension) && isNode(right, N.Dimension)) {
+      const lUnit = left.unit;
+      const rUnit = right.unit;
+      if ((op === '+' || op === '-') && lUnit === rUnit) {
+        return true;
+      }
+      /** Can't make square units */
+      if (op === '*' && (!lUnit || !rUnit)) {
+        return true;
+      }
+      /** Can't divide by a unit */
+      if (op === '/' && !rUnit) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  // Preserve CSS/Less slash syntax such as `font: small/20px` even under
+  // aggressive math modes. Keyword-like `Any` operands are overwhelmingly
+  // shorthand/value syntax, not arithmetic.
+  if (op === '/' && (isNode(left, N.Any) || isNode(right, N.Any))) {
+    return false;
+  }
+
+  /** Parens for Less/SCSS will set `canOperate` to true */
+  if (mathMode === 'always' || inParens) {
+    return true;
+  }
+  if (mathMode === 'parens-division') {
+    return op !== '/';
+  }
+  if (mathMode === 'parens' || mathMode === 'strict') {
+    return false;
+  }
+  return true;
+}

package/src/tree/util/sourcemap.ts

@@ -0,0 +1,37 @@
+import {
+  GenMapping,
+  addMapping,
+  setSourceContent,
+  toEncodedMap
+} from '@jridgewell/gen-mapping';
+import type { OutputWriter, SourceSegment } from './print.js';
+
+export type BuildSourceMapOptions = {
+  file?: string;
+  sourcesContent?: Map<string, string>;
+};
+
+export function buildSourceMap(writer: OutputWriter, opts: BuildSourceMapOptions = {}) {
+  const map = new GenMapping({ file: opts.file });
+  const segs: SourceSegment[] = writer.getSegments();
+
+  for (const s of segs) {
+    if (s.source) {
+      addMapping(map, {
+        generated: { line: s.genLine + 1, column: s.genColumn },
+        source: s.source,
+        original: { line: s.origLine + 1, column: s.origColumn }
+      });
+      const content = opts.sourcesContent?.get(s.source);
+      if (content !== undefined) {
+        setSourceContent(map, s.source, content);
+      }
+    } else {
+      addMapping(map, {
+        generated: { line: s.genLine + 1, column: s.genColumn }
+      });
+    }
+  }
+
+  return toEncodedMap(map);
+}

package/src/types/config.ts

@@ -0,0 +1,247 @@
+import type { EqualityMode, MathMode, UnitMode } from './modes.js';
+
+export type { EqualityMode, MathMode, UnitMode };
+export type ExtendSelectorKind = 'simple' | 'basic' | 'pseudo' | 'complex' | 'compound';
+
+/**
+ * Less compiler options.
+ *
+ * Kept in `@jesscss/core` to avoid cyclic workspace dependencies with `styles-config`.
+ * Based on less.js default-options.js and bin/lessc.
+ */
+export interface LessOptions {
+  /**
+   * Restrict which selector shapes are allowed in extend targets.
+   * When set, any other selector kind is a parse error.
+   *
+   * Supported kinds mirror selector node types in lowercase:
+   * - `simple`
+   * - `basic`
+   * - `pseudo`
+   * - `compound`
+   * - `complex`
+   *
+   * @default undefined
+   */
+  allowExtendSelectors?: ExtendSelectorKind[];
+
+  /**
+   * Inline Javascript - @plugin still allowed
+   * @default false
+   */
+  javascriptEnabled?: boolean;
+
+  /**
+   * Outputs a makefile import dependency list to stdout.
+   * @default false
+   */
+  depends?: boolean;
+
+  /**
+   * @deprecated Compress using less built-in compression.
+   * This does an okay job but does not utilise all the tricks of
+   * dedicated css compression.
+   * @default false
+   */
+  compress?: boolean;
+
+  /**
+   * Runs the less parser and just reports errors without any output.
+   * @default false
+   */
+  lint?: boolean;
+
+  /**
+   * Sets available include paths.
+   * If the file in an @import rule does not exist at that exact location,
+   * less will look for it at the location(s) passed to this option.
+   * @default []
+   */
+  paths?: string[];
+
+  /**
+   * Color output in the terminal
+   * @default true
+   */
+  color?: boolean;
+
+  /**
+   * @deprecated This option has confusing behavior and may be removed in a future version.
+   *
+   * Controls how @import statements for .less files are handled inside selector blocks (rulesets).
+   *
+   * Behavior:
+   * - @import at root level: Always processed
+   * - @import inside @-rules (@media, @supports, etc.): Processed (these are not selector blocks)
+   * - @import inside selector blocks (.class, #id, etc.): Behavior depends on this option
+   *
+   * Options:
+   * - `false` (default): All @import statements are processed regardless of context.
+   * - `true`: @import statements inside selector blocks are silently ignored and not output.
+   * - `'error'`: @import statements inside selector blocks will throw an error instead of being silently ignored.
+   *
+   * Note: Only affects .less file imports. CSS imports (url(...) or .css files) are
+   * always output as CSS @import statements regardless of this setting.
+   *
+   * @see https://github.com/less/less.js/issues/656
+   * @default false
+   */
+  strictImports?: boolean | 'error';
+
+  /**
+   * Allow Imports from Insecure HTTPS Hosts
+   * @default false
+   */
+  insecure?: boolean;
+
+  /**
+   * Allows you to add a path to every generated import and url in your css.
+   * This does not affect less import statements that are processed, just ones
+   * that are left in the output css.
+   * @default ''
+   */
+  rootpath?: string;
+
+  /**
+   * By default URLs are kept as-is, so if you import a file in a sub-directory
+   * that references an image, exactly the same URL will be output in the css.
+   * This option allows you to re-write URL's in imported files so that the
+   * URL is always relative to the base imported file
+   * @default false
+   */
+  rewriteUrls?: boolean | 'all' | 'local' | 'off';
+
+  /**
+   * How to process math operations
+   * - 'always': eagerly try to solve all operations
+   * - 'parens-division': require parens for division "/"
+   * - 'parens' or 'strict': require parens for all operations
+   * @default 'parens-division'
+   */
+  mathMode?: MathMode;
+
+  /**
+   * How to handle unit conversions in math operations
+   * - 'loose': Less's default 1.x-4.x behavior
+   * - 'preserve': Create calc() expressions for unit errors
+   * - 'strict': strict unit mode
+   * @default 'loose'
+   */
+  unitMode?: UnitMode;
+
+  /**
+   * How to handle equality/coercion in guards and comparisons.
+   * - 'coerce': Less-compatible coercion behavior
+   * - 'strict': type-strict behavior
+   * @default 'coerce'
+   */
+  equalityMode?: EqualityMode;
+
+  /**
+   * @deprecated Use `mathMode` instead. This option maps to `mathMode` as follows:
+   * - 0 or 'always' → 'always'
+   * - 1 or 'parens-division' → 'parens-division'
+   * - 2 or 'parens' or 'strict' → 'parens'
+   * - 3 or 'strict-legacy' → 'parens' (removed, will default to 'strict)
+   * @default undefined (uses mathMode if provided, otherwise 'parens-division')
+   */
+  math?: 0 | 1 | 2 | 3 | MathMode | 'strict-legacy';
+
+  /**
+   * @deprecated Use `unitMode` instead. If `true`, sets `unitMode` to 'strict'.
+   * If `false` or undefined, uses the `unitMode` value (defaults to 'loose').
+   * @default false
+   */
+  strictUnits?: boolean;
+
+  /**
+   * Effectively the declaration is put at the top of your base Less file,
+   * meaning it can be used but it also can be overridden if this variable
+   * is defined in the file.
+   * @default null
+   */
+  globalVars?: Record<string, string> | null;
+
+  /**
+   * As opposed to the global variable option, this puts the declaration at the
+   * end of your base file, meaning it will override anything defined in your Less file.
+   * @default null
+   */
+  modifyVars?: Record<string, string> | null;
+
+  /**
+   * This option allows you to specify a argument to go on to every URL.
+   * @default ''
+   */
+  urlArgs?: string;
+
+  /**
+   * @removed The dumpLineNumbers option is not useful nor supported in browsers. Use sourcemaps instead.
+   *
+   * @default undefined
+   */
+  dumpLineNumbers?: string;
+
+  /**
+   * Source map options
+   * @default undefined
+   */
+  sourceMap?: boolean | {
+    sourceMapFullFilename?: string;
+    sourceMapRootpath?: string;
+    sourceMapBasepath?: string;
+    sourceMapURL?: string;
+    sourceMapFileInline?: boolean;
+    outputSourceFiles?: boolean;
+    disableSourcemapAnnotation?: boolean;
+    sourceMapOutputFilename?: string;
+    sourceMapFilename?: string;
+  };
+
+  /**
+   * Verbose output
+   * @default false
+   */
+  verbose?: boolean;
+
+  /**
+   * Silent mode (suppress errors)
+   * @default false
+   */
+  silent?: boolean;
+
+  /**
+   * Quiet mode (suppress warnings)
+   * @default false
+   */
+  quiet?: boolean;
+
+  /**
+   * @deprecated This is legacy Less behavior.
+   *
+   * Controls whether mixins and detached rulesets "leak" their inner rules.
+   * When true:
+   * - Mixins: Mixin and VarDeclaration nodes are 'public' and 'optional' respectively
+   * - Detached rulesets: Mixin and VarDeclaration nodes are 'public' and 'private' respectively
+   * When false:
+   * - Both mixins and detached rulesets: Mixin and VarDeclaration nodes are 'private'
+   * @default true
+   */
+  leakyRules?: boolean;
+
+  /**
+   * Whether to collapse nested selectors (Less 1.x-4.x style flattening)
+   * When true, nested selectors like `.parent { .child { } }` are flattened to `.parent .child { }`
+   * @default false
+   */
+  collapseNesting?: boolean;
+
+  /**
+   * @deprecated This is legacy Less behavior.
+   *
+   * Whether to bubble root-only at-rules (@font-face, @keyframes, etc.) to the root
+   * when they are nested inside rulesets. Modern CSS supports nesting these at-rules.
+   * @default true
+   */
+  bubbleRootAtRules?: boolean;
+}

package/src/types/index.ts

@@ -0,0 +1,12 @@
+import { type ILexingResult, type IRecognitionException, type IToken } from '@chevrotain/types';
+import type { Node } from '../tree/index.js';
+
+export * from './modes.js';
+export * from './config.js';
+
+export interface IParseResult<T extends Node = Node> {
+  lexerResult: ILexingResult;
+  errors: IRecognitionException[];
+  tree: T;
+  warnings?: Array<{ message: string; token?: IToken; deprecation?: string }>;
+}