@gesslar/sassy 0.21.1 → 0.22.0

package/types/Evaluator.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Evaluator class for resolving variables and colour tokens in theme objects.
+ * Handles recursive substitution of token references in arrays of objects
+ * with support for colour manipulation functions.
+ */
+export default class Evaluator {
+    /**
+     * Regular expression used to locate variable substitution tokens. Supports:
+     *  - POSIX-ish:    $(variable.path)
+     *  - Legacy:       $variable.path
+     *  - Braced:       ${variable.path}
+     *
+     * Capturing groups allow extraction of the inner path variant irrespective
+     * of wrapping style. The pattern captures (entireMatch, posix, legacy,
+     * braced).
+     *
+     * @type {RegExp}
+     */
+    static sub: RegExp;
+    /**
+     * Regular expression for matching colour / transformation function calls
+     * within token strings, e.g. `darken($(std.accent), 10)`.
+     *
+     * @type {RegExp}
+     */
+    static func: RegExp;
+    /**
+     * Extracts a variable name from a string containing variable syntax.
+     * Supports $(var), $var, and ${var} patterns.
+     *
+     * @param {string} [str] - String that may contain a variable reference
+     * @returns {string|null} The variable name or null if none found
+     */
+    static extractVariableName(str?: string): string | null;
+    /**
+     * Extracts function name and arguments from a string containing function syntax.
+     * Supports functionName(args) patterns.
+     *
+     * @param {string} [str] - String that may contain a function call
+     * @returns {{func:string, args:string}|null} Object with {func, args} or null if none found
+     */
+    static extractFunctionCall(str?: string): {
+        func: string;
+        args: string;
+    } | null;
+    get pool(): ThemePool;
+    /**
+     * Resolve variables and theme token entries in two distinct passes to ensure
+     * deterministic scoping and to prevent partially-resolved values from
+     * leaking between stages:
+     *
+     *  1. Variable pass: each variable is resolved only with access to the
+     *     variable set itself (no theme values yet). This ensures variables are
+     *     self-contained building blocks.
+     *  2. Theme pass: theme entries are then resolved against the union of the
+     *     fully-resolved variables plus (progressively) the theme entries. This
+     *     allows theme keys to reference variables and other theme keys.
+     *
+     * Implementation details:
+     *  - The internal lookup map persists for the lifetime of this instance; new
+     *    entries overwrite prior values (last write wins) so previously resolved
+     *    data can seed later evaluations without a rebuild.
+     *  - Input array is mutated in-place (`value` fields change).
+     *  - No return value. Evident by the absence of a return statement.
+     *
+     * @param {Array<{flatPath:string,value:unknown}>} decomposed - Variable entries to resolve.
+     * @example
+     * // Example decomposed input with variables and theme references
+     * const evaluator = new Evaluator();
+     * const decomposed = [
+     *   { flatPath: 'vars.primary', value: '#3366cc' },
+     *   { flatPath: 'theme.colors.background', value: '$(vars.primary)' },
+     *   { flatPath: 'theme.colors.accent', value: 'lighten($(vars.primary), 20)' }
+     * ];
+     * evaluator.evaluate(decomposed);
+     * // After evaluation, values are resolved:
+     * // decomposed[1].value === '#3366cc'
+     * // decomposed[2].value === '#5588dd' (lightened color)
+     */
+    evaluate(decomposed: Array<{
+        flatPath: string;
+        value: unknown;
+    }>): void;
+    #private;
+}
+import ThemePool from "./ThemePool.js";

package/types/LintCommand.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Command handler for linting theme files for potential issues.
+ * Validates tokenColors for duplicate scopes, undefined variables, unused
+ * variables, and precedence issues that could cause unexpected theme
+ * behaviour.
+ */
+export default class LintCommand extends Command {
+    static SECTIONS: {
+        VARS: string;
+        COLORS: string;
+        TOKEN_COLORS: string;
+        SEMANTIC_TOKEN_COLORS: string;
+    };
+    static SEVERITY: {
+        HIGH: string;
+        MEDIUM: string;
+        LOW: string;
+    };
+    static ISSUE_TYPES: {
+        DUPLICATE_SCOPE: string;
+        UNDEFINED_VARIABLE: string;
+        UNUSED_VARIABLE: string;
+        PRECEDENCE_ISSUE: string;
+    };
+    static TEMPLATES: {
+        ENTRY_NAME: (index: any) => string;
+        OBJECT_NAME: (index: any) => string;
+        VARIABLE_PREFIX: string;
+    };
+    /**
+     * Creates a new LintCommand instance.
+     *
+     * @param {object} base - Base configuration containing cwd and packageJson
+     */
+    constructor(base: object);
+    /**
+     * Executes the lint command for a given theme file.
+     * Validates the theme and reports any issues found.
+     *
+     * @param {string} inputArg - Path to the theme file to lint
+     * @param {object} options - Linting options
+     * @returns {Promise<void>} Resolves when linting is complete
+     */
+    execute(inputArg: string, options?: object): Promise<void>;
+    /**
+     * Public method to lint a theme and return structured results for external
+     * consumption.
+     *
+     * Returns categorized lint results for tokenColors, semanticTokenColors, and colors.
+     *
+     * @param {Theme} theme - The compiled theme object
+     * @returns {Promise<object>} Object containing categorized lint results
+     */
+    lint(theme: Theme): Promise<object>;
+    #private;
+}
+import Command from "./Command.js";
+import Theme from "./Theme.js";

package/types/ResolveCommand.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Command handler for resolving theme tokens and variables to their final values.
+ * Provides introspection into the theme resolution process and variable dependencies.
+ */
+export default class ResolveCommand extends Command {
+    /**
+     * Creates a new ResolveCommand instance.
+     *
+     * @param {object} base - Base configuration containing cwd and packageJson
+     */
+    constructor(base: object);
+    /**
+     * Executes the resolve command for a given theme file and option.
+     * Validates mutual exclusivity of options and delegates to appropriate resolver.
+     *
+     * @param {string} inputArg - Path to the theme file to resolve
+     * @param {object} options - Resolution options (token, etc.)
+     * @returns {Promise<void>} Resolves when resolution is complete
+     */
+    execute(inputArg: string, options?: object): Promise<void>;
+    /**
+     * Resolves a specific color to its final value and displays the resolution trail.
+     * Shows the complete dependency chain for the requested color.
+     *
+     * @param {object} theme - The compiled theme object with pool
+     * @param {string} colorName - The color key to resolve
+     * @returns {void}
+     * @example
+     * // Resolve a color variable from a compiled theme
+     * await resolveCommand.resolveColor(theme, 'colors.primary');
+     * // Output:
+     * // colors.primary:
+     * //   $(vars.accent)
+     * //     → #3366cc
+     * // Resolution: #3366cc
+     */
+    resolveColor(theme: object, colorName: string): void;
+    /**
+     * Resolves a specific tokenColors scope to its final value and displays the resolution trail.
+     * Shows all matching scopes with disambiguation when multiple matches are found.
+     *
+     * @param {object} theme - The compiled theme object with output
+     * @param {string} scopeName - The scope to resolve (e.g., "entity.name.class" or "entity.name.class.1")
+     * @returns {void}
+     */
+    resolveTokenColor(theme: object, scopeName: string): void;
+    /**
+     * Resolves a specific semanticTokenColors scope to its final value.
+     * Uses the same logic as tokenColors since they have identical structure.
+     *
+     * @param {object} theme - The compiled theme object with output
+     * @param {string} scopeName - The scope to resolve (e.g., "keyword" or "keyword.1")
+     * @returns {void}
+     */
+    resolveSemanticTokenColor(theme: object, scopeName: string): void;
+    #private;
+}
+import Command from "./Command.js";

package/types/Session.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @typedef {object} SessionOptions
+ * @property {boolean} [watch] - Whether to enable file watching
+ * @property {boolean} [nerd] - Whether to show verbose output
+ * @property {boolean} [dryRun] - Whether to skip file writes
+ */
+/**
+ * @typedef {object} BuildRecord
+ * @property {number} timestamp - Epoch ms when the build started
+ * @property {number} loadTime - Time (ms) spent loading theme sources
+ * @property {number} buildTime - Time (ms) spent compiling the theme
+ * @property {number} writeTime - Time (ms) spent writing the output file
+ * @property {boolean} success - Whether the build completed successfully
+ * @property {string} [error] - Error message when success is false
+ */
+export default class Session {
+    /**
+     * Creates a new Session instance for managing theme compilation lifecycle.
+     * Sessions provide persistent state across rebuilds, error tracking, and
+     * individual theme management within the build system.
+     *
+     * @param {Command} command - The parent build command instance
+     * @param {Theme} theme - The theme instance to manage
+     * @param {SessionOptions} options - Build configuration options
+     */
+    constructor(command: Command, theme: Theme, options: SessionOptions);
+    get theme(): Theme;
+    /**
+     * Gets the theme instance managed by this session.
+     *
+     * @returns {Theme} The theme instance
+     */
+    getTheme(): Theme;
+    /**
+     * Gets the command instance orchestrating this session.
+     *
+     * @returns {Command} The command instance
+     */
+    getCommand(): Command;
+    /**
+     * Gets the session options.
+     *
+     * @returns {SessionOptions} The session options
+     */
+    getOptions(): SessionOptions;
+    /**
+     * Gets the build history for this session.
+     *
+     * @returns {Array<BuildRecord>} Array of build records
+     */
+    getHistory(): Array<BuildRecord>;
+    /**
+     * Gets the build statistics for this session.
+     *
+     * @returns {{builds: number, failures: number}} Build statistics
+     */
+    getStats(): {
+        builds: number;
+        failures: number;
+    };
+    /**
+     * Checks if a build is currently in progress.
+     *
+     * @returns {boolean} True if building
+     */
+    isBuilding(): boolean;
+    /**
+     * Checks if watch mode is enabled.
+     *
+     * @returns {boolean} True if watching
+     */
+    isWatching(): boolean;
+    /**
+     * Checks if there's an active file watcher.
+     *
+     * @returns {boolean} True if watcher exists
+     */
+    hasWatcher(): boolean;
+    run(): Promise<void>;
+    /**
+     * Displays a formatted summary of the session's build statistics and performance.
+     * Shows total builds, success/failure counts, success rate percentage, and timing
+     * information from the most recent build. Used during session cleanup to provide
+     * final statistics to the user.
+     *
+     * @returns {void}
+     */
+    showSummary(): void;
+    #private;
+}
+export type SessionOptions = {
+    /**
+     * - Whether to enable file watching
+     */
+    watch?: boolean;
+    /**
+     * - Whether to show verbose output
+     */
+    nerd?: boolean;
+    /**
+     * - Whether to skip file writes
+     */
+    dryRun?: boolean;
+};
+export type BuildRecord = {
+    /**
+     * - Epoch ms when the build started
+     */
+    timestamp: number;
+    /**
+     * - Time (ms) spent loading theme sources
+     */
+    loadTime: number;
+    /**
+     * - Time (ms) spent compiling the theme
+     */
+    buildTime: number;
+    /**
+     * - Time (ms) spent writing the output file
+     */
+    writeTime: number;
+    /**
+     * - Whether the build completed successfully
+     */
+    success: boolean;
+    /**
+     * - Error message when success is false
+     */
+    error?: string;
+};
+import Theme from "./Theme.js";
+import Command from "./Command.js";

package/types/Theme.d.ts

@@ -0,0 +1,336 @@
+import type { FileObject, DirectoryObject, Cache } from '@gesslar/toolkit';
+/**
+ * Theme class: manages the lifecycle of a theme compilation unit.
+ * See file-level docstring for responsibilities.
+ */
+export default class Theme {
+    /**
+     * Creates a new Theme instance.
+     *
+     * @param {FileObject} themeFile - The source theme file object
+     * @param {DirectoryObject} cwd - The project's directory.
+     * @param {object} options - Compilation options
+     */
+    constructor(themeFile: FileObject, cwd: DirectoryObject, options: object);
+    /**
+     * Resets the theme's compilation state, clearing output and lookup data.
+     * Used when recompiling in watch mode or clearing previous state.
+     */
+    reset(): void;
+    /**
+     * Gets the current working directory.
+     *
+     * @returns {DirectoryObject} The current working directory
+     */
+    getCwd(): DirectoryObject;
+    /**
+     * Gets the compilation options.
+     *
+     * @returns {object} The compilation options object
+     */
+    getOptions(): object;
+    /**
+     * Gets a specific compilation option.
+     *
+     * @param {string} option - The option name to retrieve
+     * @returns {unknown} The option value or undefined if not set
+     */
+    getOption(option: string): unknown;
+    /**
+     * Sets the cache instance for theme compilation.
+     *
+     * @param {Cache} cache - The cache instance to use for file operations
+     * @returns {this} Returns this instance for method chaining
+     */
+    setCache(cache: Cache): this;
+    /**
+     * Gets the cache instance.
+     *
+     * @returns {Cache|null} The cache instance or null if not set
+     */
+    getCache(): Cache | null;
+    /**
+     * Gets the theme name.
+     *
+     * @returns {string} The theme name derived from the source file
+     */
+    getName(): string;
+    /**
+     * Gets the output file name for the compiled theme.
+     *
+     * @returns {string} The output file name with extension
+     */
+    getOutputFileName(): string;
+    /**
+     * Gets the source file object.
+     *
+     * @returns {FileObject} The source theme file
+     */
+    getSourceFile(): FileObject;
+    /**
+     * Sets the compiled theme output object and updates derived JSON and hash.
+     *
+     * @param {object} data - The compiled theme output object
+     * @returns {this} Returns this instance for method chaining
+     */
+    setOutput(data: object): this;
+    /**
+     * Gets the compiled theme output object.
+     *
+     * @returns {object|null} The compiled theme output
+     */
+    getOutput(): object | null;
+    /**
+     * Checks if the source has colors defined.
+     *
+     * @returns {boolean} True if source has theme colors
+     */
+    sourceHasColors(): boolean;
+    /**
+     * Checks if the source has token colors defined.
+     *
+     * @returns {boolean} True if source has theme token colors
+     */
+    sourceHasTokenColors(): boolean;
+    /**
+     * Checks if the source has semantic token colors defined.
+     *
+     * @returns {boolean} True if source has theme semantic token colors
+     */
+    sourceHasSemanticTokenColors(): boolean;
+    /**
+     * Checks if the source has theme configuration.
+     *
+     * @returns {boolean} True if source has theme data
+     */
+    sourceHasTheme(): boolean;
+    /**
+     * Checks if the source has variables.
+     *
+     * @returns {boolean} True if source has vars section
+     */
+    sourceHasVars(): boolean;
+    /**
+     * Checks if the source has config section.
+     *
+     * @returns {boolean} True if source has config
+     */
+    sourceHasConfig(): boolean;
+    /**
+     * Gets the source colors data.
+     *
+     * @returns {object|null} The colors object or null if not defined
+     */
+    getSourceColors(): object | null;
+    /**
+     * Gets the source token colors data.
+     *
+     * @returns {Array|null} The token colors array or null if not defined
+     */
+    getSourceTokenColors(): any[] | null;
+    /**
+     * Gets the source semantic token colors data.
+     *
+     * @returns {object|null} The semantic token colors object or null if not defined
+     */
+    getSourceSemanticTokenColors(): object | null;
+    /**
+     * Gets the set of file dependencies.
+     *
+     * @returns {Set<Dependency>} Set of dependency files
+     */
+    getDependencies(): Set<Dependency>;
+    /**
+     * Adds a dependency to the theme with its source data.
+     *
+     * @param {FileObject} file - The dependency file object
+     * @param {object} source - The parsed source data from the file
+     * @returns {this} Returns this instance for method chaining
+     */
+    addDependency(file: FileObject, source: object): this;
+    /**
+     * Checks if the theme has any dependencies.
+     *
+     * @returns {boolean} True if theme has dependencies
+     */
+    hasDependencies(): boolean;
+    /**
+     * Gets the parsed source data from the theme file.
+     *
+     * @returns {object|null} The parsed source data
+     */
+    getSource(): object | null;
+    /**
+     * Gets the variable lookup data for theme compilation.
+     *
+     * @returns {object|null} The lookup data object
+     */
+    getLookup(): object | null;
+    /**
+     * Sets the variable lookup data for theme compilation.
+     *
+     * @param {object} data - The lookup data object
+     * @returns {this} Returns this instance for method chaining
+     */
+    setLookup(data: object): this;
+    /**
+     * Gets the pool data for variable resolution tracking or null if one has
+     * not been set.
+     *
+     * @returns {ThemePool|null} The pool for this theme.
+     */
+    getPool(): ThemePool | null;
+    /**
+     * Sets the pool data for variable resolution tracking. May not be over-
+     * written publicly. May only be reset
+     *
+     * @see reset
+     *
+     * @param {ThemePool} pool - The pool to assign to this theme
+     * @throws {Error} If there is already a pool.
+     * @returns {this} Returns this instance for method chaining
+     */
+    setPool(pool: ThemePool): this;
+    /**
+     * Method to return true or false if this theme has a pool.
+     *
+     * @returns {boolean} True if a pool has been set, false otherwise.
+     */
+    hasPool(): boolean;
+    /**
+     * Checks if the theme has compiled output.
+     *
+     * @returns {boolean} True if theme has been compiled
+     */
+    hasOutput(): boolean;
+    /**
+     * Checks if the theme has loaded source data.
+     *
+     * @returns {boolean} True if source data is available
+     */
+    hasSource(): boolean;
+    /**
+     * Checks if the theme has a cache instance.
+     *
+     * @returns {boolean} True if cache is available
+     */
+    hasCache(): boolean;
+    /**
+     * Checks if the theme has lookup data.
+     *
+     * @returns {boolean} True if lookup data exists
+     */
+    hasLookup(): boolean;
+    /**
+     * Checks if the theme is ready to be compiled.
+     * Requires source data and cache to be available.
+     *
+     * @returns {boolean} True if theme can be compiled
+     */
+    isReady(): boolean;
+    /**
+     * Checks if the theme has been fully compiled.
+     * Requires output, pool, and lookup data to be present.
+     *
+     * @returns {boolean} True if theme is fully compiled
+     */
+    isCompiled(): boolean;
+    /**
+     * Checks if the theme can be built/compiled.
+     * Same as isReady() but with more semantic naming.
+     *
+     * @returns {boolean} True if build can proceed
+     */
+    canBuild(): boolean;
+    /**
+     * Checks if the theme can be written to output.
+     * Requires the theme to be compiled.
+     *
+     * @returns {boolean} True if write can proceed
+     */
+    canWrite(): boolean;
+    /**
+     * Checks if the theme is in a valid state for operation.
+     * Basic validation that core properties are set.
+     *
+     * @returns {boolean} True if theme state is valid
+     */
+    isValid(): boolean;
+    /**
+     * Loads and parses the theme source file.
+     * Validates that the source contains required configuration.
+     * Skips loading if no cache is available (extension use case).
+     *
+     * @returns {Promise<this>} Returns this instance for method chaining
+     * @throws {Sass} If source file lacks required 'config' property
+     */
+    load(): Promise<this>;
+    /**
+     * Builds the theme by compiling source data into final output.
+     * Main entry point for theme compilation process.
+     *
+     * @returns {Promise<this>} Returns this instance for method chaining
+     */
+    build(): Promise<this>;
+    /**
+     * Writes the compiled theme output to a file or stdout.
+     * Handles dry-run mode, output directory creation, and duplicate write prevention.
+     *
+     * @param {boolean} [force] - Force a write. Used by the rebuild CLI option.
+     * @returns {Promise<void>} Resolves when write operation is complete
+     */
+    write(force?: boolean): Promise<void>;
+    #private;
+}
+/**
+ * Dependency class represents a theme file dependency.
+ * Manages the relationship between a file reference and its parsed source data.
+ */
+export class Dependency {
+    /**
+     * Sets the file object for this dependency.
+     *
+     * @param {FileObject} file - The file object of this dependency.
+     * @returns {this} This.
+     */
+    setSourceFile(file: FileObject): this;
+    /**
+     * Get the file object for this depenency.
+     *
+     * @returns {FileObject} The file object of this dependency.
+     */
+    getSourceFile(): FileObject;
+    /**
+     * Sets the source object for this dependency.
+     *
+     * @param {object} source - The parsed JSON from the file after loading.
+     * @returns {this} This.
+     */
+    setSource(source: object): this;
+    /**
+     * Gets the parsed source data for this dependency.
+     *
+     * @returns {object|null} The parsed source data
+     */
+    getSource(): object | null;
+    /**
+     * Checks if the dependency has a source file.
+     *
+     * @returns {boolean} True if source file is set
+     */
+    hasSourceFile(): boolean;
+    /**
+     * Checks if the dependency has parsed source data.
+     *
+     * @returns {boolean} True if source data is available
+     */
+    hasSource(): boolean;
+    /**
+     * Checks if the dependency is fully initialized.
+     *
+     * @returns {boolean} True if both file and source are set
+     */
+    isComplete(): boolean;
+    #private;
+}
+import ThemePool from "./ThemePool.js";