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

package/src/logger/deprecation-processing.ts

@@ -0,0 +1,109 @@
+import type { Deprecation } from '../deprecation.js';
+import type { Logger } from '../logger.js';
+import type { WarningDiagnostic } from '../jess-error.js';
+
+/**
+ * The maximum number of repetitions of the same deprecation warning
+ * that will be emitted before hiding the rest.
+ */
+const MAX_REPETITIONS = 5;
+
+/**
+ * A logger wrapper that provides special handling for deprecation warnings:
+ * - Making deprecations fatal (throwing errors)
+ * - Limiting repetition (max 5 per deprecation)
+ */
+export class DeprecationProcessingLogger implements Logger {
+  /** A map of how many times each deprecation has been emitted */
+  private readonly _warningCounts = new Map<Deprecation, number>();
+
+  /** The inner logger to delegate to */
+  private readonly _inner: Logger;
+
+  /** Deprecation warnings of these types will cause an error to be thrown */
+  readonly fatalDeprecations: Set<Deprecation>;
+
+  /** Whether repetitions of the same warning should be limited */
+  readonly limitRepetition: boolean;
+
+  constructor(
+    inner: Logger,
+    options: {
+      fatalDeprecations?: Iterable<Deprecation>;
+      limitRepetition?: boolean;
+    } = {}
+  ) {
+    this._inner = inner;
+    this.fatalDeprecations = new Set(options.fatalDeprecations ?? []);
+    this.limitRepetition = options.limitRepetition ?? true;
+  }
+
+  /**
+   * Processes a deprecation warning.
+   *
+   * If the deprecation is in fatalDeprecations, this throws an error.
+   * If it's already been warned for MAX_REPETITIONS times and limitRepetition is true, the warning is dropped.
+   * Otherwise, this is passed on to the inner logger.
+   */
+  warnForDeprecation(
+    deprecation: Deprecation,
+    warning: WarningDiagnostic
+  ): void {
+    if (this.fatalDeprecations.has(deprecation)) {
+      const message = `${warning.message}\n\nThis is only an error because you've set the ${deprecation.id} deprecation to be fatal.\nRemove this setting if you need to keep using this feature.`;
+      const error = new Error(message);
+      error.name = 'DeprecationError';
+      throw error;
+    }
+
+    if (this.limitRepetition) {
+      const count = (this._warningCounts.get(deprecation) ?? 0) + 1;
+      this._warningCounts.set(deprecation, count);
+      if (count > MAX_REPETITIONS) {
+        return;
+      }
+    }
+
+    // Pass to inner logger
+    this._inner.warn?.(warning.message);
+  }
+
+  /**
+   * Prints a warning indicating the number of deprecation warnings that were
+   * omitted due to repetition.
+   */
+  summarize(): void {
+    let total = 0;
+    for (const [deprecation, count] of this._warningCounts.entries()) {
+      if (count > MAX_REPETITIONS) {
+        total += count - MAX_REPETITIONS;
+      }
+    }
+    if (total > 0) {
+      this._inner.warn?.(
+        `${total} repetitive deprecation warnings omitted.\nRun in verbose mode to see all warnings.`
+      );
+    }
+  }
+
+  // Delegate other logger methods to inner logger
+  configure?(log: Logger): void {
+    this._inner.configure?.(log);
+  }
+
+  log?(...args: any[]): void {
+    this._inner.log?.(...args);
+  }
+
+  info?(...args: any[]): void {
+    this._inner.info?.(...args);
+  }
+
+  warn?(...args: any[]): void {
+    this._inner.warn?.(...args);
+  }
+
+  error?(...args: any[]): void {
+    this._inner.error?.(...args);
+  }
+}

package/src/logger.ts

@@ -0,0 +1,31 @@
+import chalk from 'chalk';
+
+export interface Logger {
+  configure?(log: Logger): void;
+  log?(...args: any[]): void;
+  info?(...args: any[]): void;
+  warn?(...args: any[]): void;
+  error?(...args: any[]): void;
+}
+/** Configure with custom behavior */
+export const logger: Required<Logger> = {
+  configure(log: Logger) {
+    Object.assign(logger, log);
+  },
+
+  log(...args: any[]) {
+    console.log(...args);
+  },
+
+  info(...args: any[]) {
+    console.info(...args);
+  },
+
+  warn(...args: any[]) {
+    console.error(chalk.yellow(...args));
+  },
+
+  error(...args: any[]) {
+    console.error(chalk.red(...args));
+  }
+};

package/src/plugin.ts

@@ -0,0 +1,292 @@
+import type { Rules } from './tree/rules.js';
+import { join, isAbsolute, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import type { Visitor } from './visitor/index.js';
+import { type ErrorDiagnostic, type WarningDiagnostic, JessError } from './jess-error.js';
+
+export type ISafeParseResult = {
+  /**
+   * The parsed tree, if parsing succeeded
+   */
+  tree?: Rules;
+  /**
+   * Normalized errors from parsing.
+   * This should include ALL errors from lexing, parsing, and any plugin-level issues.
+   * Plugins should convert all errors to normalized ErrorDiagnostic format.
+   * Always an array (empty if no errors).
+   */
+  errors: ErrorDiagnostic[];
+  /**
+   * Normalized warnings from parsing.
+   * This should include ALL warnings from lexing, parsing, and any plugin-level issues.
+   * Plugins should convert all warnings to normalized WarningDiagnostic format.
+   * Always an array (empty if no warnings).
+   */
+  warnings: WarningDiagnostic[];
+};
+
+export type PluginParseOptions = {
+  compilerOptions?: Record<string, any>;
+};
+
+export interface PluginInterface {
+  /**
+   * e.g. 'less-plugin'
+   */
+  name: string;
+
+  /**
+   * Queryable filter if we have resolved the extension
+   * no dots e.g. `['less', 'scss']`
+   */
+  supportedExtensions?: string[];
+
+  /**
+   * Expand an import path into a set of paths to try.
+   * e.g.
+   *   `@import 'foo'` -> `['./foo.less']`
+   *   `@import 'foo'` -> `['./foo.scss', './_foo.scss']`
+   */
+  expandImport?(importPath: string, currentDir: string): string[];
+
+  /**
+   * e.g.
+   *   `./foo` -> `/Users/foo/bar/foo`
+   *   `@/alias` -> `/Users/foo/bar/src/alias`
+   *   `one/two` -> `/Users/foo/node_modules/one/two`
+   *
+   * Does not attempt to check if the path exists.
+   * Note: paths may already be absolute.
+   *
+   * If the plugin has nothing to change, return `null` or return the array as-is.
+   *
+   * @note - I suppose a plugin doesn't have to resolve to an absolute path, if it's
+   *         using some other method to handle the resolved paths in `locate()`.
+   *         To that end, `locate()` shouldn't presume that the paths are absolute.
+   */
+  resolve?(path: string | string[], currentDir: string, searchPaths: string[]): null | string[] | Promise<null | string[]>;
+
+  /**
+   * Pick the first one that exists. Return null to let another plugin handle the path.
+   */
+  locate?(pathCandidates: string[], currentDir: string): null | string | Promise<string | null>;
+
+  /**
+   * Get the source code for the file.
+   */
+  getSource?(absoluteFilePath: string): Promise<string>;
+
+  /**
+   * If we have the extension in `supportedExtensions`, and this method exists,
+   * then this plugin is assumed to be able to parse the file.
+   */
+  parse?(filePath: string, source: string, options?: PluginParseOptions): Rules;
+
+  /** No errors thrown; instead will return errors in the result */
+  safeParse?(filePath: string, source: string, options?: PluginParseOptions): ISafeParseResult;
+
+  /** If this method exists, then the plugin can return a JS module / object */
+  import?(absoluteFilePath: string): Promise<Record<string, any>>;
+
+  /** Post-parse or post-eval visitor(s) */
+  visitor?: Visitor | Visitor[];
+  /** Pre-eval visitor(s) - called before node.eval() during the preEval phase */
+  preEvalVisitor?: Visitor | Visitor[];
+  /** Post-eval visitor(s) - called after node.eval() (alternative to visitor for clarity) */
+  postEvalVisitor?: Visitor | Visitor[];
+  /** Optional cleanup hook for plugins that manage external resources */
+  dispose?(): void;
+}
+
+const { isArray } = Array;
+
+export abstract class AbstractPlugin implements PluginInterface {
+  abstract name: string;
+
+  /**
+   * Does a basic path resolution. Node resolution is in other plugins.
+   */
+  resolve(filePath: string | string[], currentDir: string, searchPaths: string[]) {
+    const bases = [currentDir, ...searchPaths];
+    const out: string[] = [];
+    const seen = new Set<string>();
+    filePath = isArray(filePath) ? filePath : [filePath];
+    for (const base of bases) {
+      const baseDir = isAbsolute(base) ? base : join(currentDir, base);
+      for (const path of filePath) {
+        const abs = resolve(baseDir, path);
+        if (abs && !seen.has(abs)) {
+          seen.add(abs);
+          out.push(abs);
+        }
+      }
+    }
+    return out;
+  }
+
+  /** Default source getter */
+  async getSource(absoluteFilePath: string): Promise<string> {
+    try {
+      const result = await readFile(absoluteFilePath, 'utf8');
+      return result;
+    } catch (error: unknown) {
+      throw error;
+    }
+  }
+
+  /** Gets the first match using from the filesystem that exists */
+  locate(pathCandidates: string[], currentDir: string): null | string {
+    for (const candidate of pathCandidates) {
+      const absolutePath = isAbsolute(candidate) ? candidate : join(currentDir, candidate);
+      if (existsSync(absolutePath)) {
+        return absolutePath;
+      }
+    }
+    return null;
+  }
+
+  parse(filePath: string, source: string, options?: PluginParseOptions): Rules {
+    const safeParse: PluginInterface['safeParse'] = (this as PluginInterface).safeParse;
+    if (!safeParse) {
+      throw new Error(`Plugin "${this.name}" does not support parsing`);
+    }
+    const { tree, errors } = safeParse.call(this, filePath, source, options);
+    if (errors.length > 0) {
+      const firstError = errors[0]!;
+      throw new JessError({
+        code: firstError.code,
+        phase: firstError.phase,
+        severity: 'error',
+        ctx: firstError.file ? { file: firstError.file } : undefined,
+        filePath: firstError.filePath,
+        source: firstError.file?.source,
+        line: firstError.line,
+        column: firstError.column,
+        reason: firstError.reason,
+        fix: firstError.fix,
+        note: firstError.note,
+        errors: firstError.errors,
+        lexerErrors: firstError.lexerErrors
+      });
+    }
+    if (!tree) {
+      throw new Error(`Plugin "${this.name}" failed to parse "${filePath}"`);
+    }
+    return tree;
+  }
+
+  /** Implement using the JS plugin w/ Deno */
+  // import(absoluteFilePath: string): Promise<Record<string, any>> {
+  //   return import(absoluteFilePath);
+  // }
+}
+
+export type Plugin = <T extends Record<string, any>>(opts?: T) => PluginInterface;
+
+// export abstract class FileManager<O extends Record<string, any> = Record<string, any>> {
+//   abstract supportedExtensions?: string[];
+
+//   constructor(
+//     public opts: Partial<O> = {}
+//   ) {}
+
+//   /**
+//    * Turns relative paths into absolute paths.
+//    * e.g.
+//    *   `./foo` -> `/Users/foo/bar/foo`
+//    *   `@/alias` -> `/Users/foo/bar/src/alias`
+//    *   `one/two` -> `/Users/foo/node_modules/one/two`
+//    *
+//    * Does not attempt to check if the path exists.
+//    * Note: paths may already be absolute.
+//    */
+//   abstract resolver?(paths: Set<string>, currentDir: string): Set<string>;
+
+//   /**
+//    * e.g.
+//    *   Less file manager: `@import 'foo'` -> `['./foo.less']`
+//    *   Sass file manager: `@import 'foo'` -> `['./foo.scss', './_foo.scss']`
+//    */
+//   abstract getPathsToTry?(filePath: string, currentDir: string, paths: string[], options: PathOptions): Set<string>;
+
+//   /**
+//    * Get the final resolved path.
+//    *
+//    * @param filePath Will be a partial path
+//    * @param paths The paths to search. This should always contain
+//    * the directory context where the file was imported. Can be
+//    * a fully-qualified path or a glob. Relative paths
+//    * will be resolved relative to process.cwd(). Plugins
+//    * may alter the paths array and return false to let another
+//    * plugin handle the path resolution.
+//    * @param options Determined by the file manager
+//    */
+//   resolvePath(
+//     filePath: string,
+//     currentDir: string,
+//     paths: string[],
+//     options: PathOptions
+//   ): string | string[] {
+//     filePath = this.opts.resolver(filePath);
+//     const pathsTried: string[] = [];
+//     if (isAbsolute(filePath)) {
+//       pathsTried.push(filePath);
+//       if (existsSync(filePath)) {
+//         return filePath;
+//       }
+//     }
+//     let isRelative = filePath.startsWith('.');
+//     let tryPath: string | undefined;
+//     if (options.allowBareRelative || isRelative) {
+//       tryPath = join(currentDir, filePath);
+//       pathsTried.push(tryPath);
+//       if (existsSync(tryPath)) {
+//         return tryPath;
+//       }
+//     }
+
+//     if (!isRelative) {
+//       try {
+//         tryPath = require.resolve(filePath);
+//         if (existsSync(tryPath)) {
+//           return tryPath;
+//         }
+//       } catch (err) {
+//         // ignore
+//       }
+//     }
+
+//     for (let i = 0; i < paths.length; i++) {
+//       tryPath = join(paths[i]!, filePath);
+//       pathsTried.push(tryPath);
+//       if (existsSync(tryPath)) {
+//         return tryPath;
+//       }
+//     }
+//     return pathsTried;
+//   }
+
+//   async loadFile(fullPath: string) {
+//     return await readFile(fullPath, 'utf8');
+//   }
+
+//   /**
+//    * Can override this instead of `getTree` if we want
+//    * to preserve extension-checking logic.
+//    */
+//   protected async _getTree(fullPath: string, options?: Record<string, any>): Promise<Rules | false> {
+//     return false;
+//   }
+
+//   /**
+//    * @param fullPath The fully resolved path
+//    */
+//   async getTree(fullPath: string, options?: Record<string, any>): Promise<Rules | false> {
+//     const supported = this.supportedExtensions;
+//     if (supported && !supported.includes(extname(fullPath))) {
+//       return false;
+//     }
+//     return await this._getTree(fullPath, options);
+//   }
+// }

package/src/tree/LOOKUP_CHAINS.md

@@ -0,0 +1,35 @@
+# Lookup Chains in Core Tree
+
+This note documents the intended scope model for variable/mixin lookup.
+
+## Two Chains
+
+- `parent` chain: definition/evaluation structure (lexical ancestry).
+- `sourceParent` chain: call-site/source ancestry used for fallback behaviors (notably Less-style leaky lookups).
+
+Both are needed; they represent different questions.
+
+## Detached Rulesets / Mixin Calls
+
+When evaluating a mixin with parameters:
+
+1. Parameter declarations live in a **wrapper Rules scope**.
+2. The cloned mixin body is evaluated as a **child Rules node** of that wrapper.
+3. Emitted output should be the evaluated body rules, not the wrapper declarations.
+
+This keeps parameter bindings available to lookup during evaluation while preventing parameter declarations from leaking into caller-visible output scope.
+
+## Reference Lookup Order (Variable)
+
+For untargeted variable lookup in `Reference`:
+
+1. Resolve against `resolvedTarget` (primary scope).
+2. If unresolved and `leakyRules` is enabled, fallback to:
+   - `rulesParent`
+   - then `sourceRulesParent`
+
+The fallback chain allows call-site style resolution without overriding primary lexical resolution.
+
+## Rule of Thumb
+
+If a fix requires "remove things after eval," re-check whether those nodes should have been in emitted output scope at all. Prefer modeling scope through wrapper ancestry over post-hoc cleanup.

package/src/tree/README.md

@@ -0,0 +1,18 @@
+## Changes for 2.0
+
+
+- We align names of AST nodes with CST nodes, where possible
+- We assume all value sequences are space separated. Any Node that has pre-whitespace with a single space is therefore ommitted.
+
+
+Target module
+```js
+import { seq as $$seq } from 'jess';
+
+export let mixin
+```
+```js
+import { mixin } from './something.jess'
+
+mixin()
+```