@gesslar/sassy 0.21.3 → 0.22.0

package/package.json

@@ -1,27 +1,33 @@
 {
   "name": "@gesslar/sassy",
-  "version": "0.21.3",
+  "version": "0.22.0",
   "displayName": "Sassy",
   "description": "Make gorgeous themes that speak as boldly as you do.",
   "publisher": "gesslar",
   "license": "Unlicense",
   "type": "module",
   "main": "src/index.js",
+  "types": "types/index.d.ts",
   "bin": "src/cli.js",
   "exports": {
-    ".": "./src/index.js",
-    "./cli": "./src/cli.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js"
+    }
   },
   "files": [
     "src/",
+    "types/",
     "UNLICENSE.txt"
   ],
   "scripts": {
     "clean": "rm -rfv ./dist",
-    "build": "npm run clean && mkdir -pv ./dist && npm pack --pack-destination ./dist/",
+    "clean-types": "rm -rfv ./types",
+    "types": "npx tsc src/*.js types-helper.d.ts --allowJs --declaration --emitDeclarationOnly --outDir types --target ES2022 --module ESNext --moduleResolution Node --esModuleInterop --skipLibCheck --resolveJsonModule && node fix-types.js",
+    "build": "npm run clean && npm run types && mkdir -pv ./dist && npm pack --pack-destination ./dist/",
     "exec": "node ./src/cli.js",
     "lint": "eslint src/",
-    "submit": "npm publish --access public",
+    "submit": "npm run build && npm publish --access public",
     "examples": "node ./examples/validator.js",
     "test": "node -p \"require('fs').readFileSync('TESTING.txt', 'utf8')\"",
     "update": "npx npm-check-updates -u && npm install"

package/src/Command.js

@@ -234,37 +234,4 @@ export default class Command {
     return fileObject
   }
 
-  /**
-   * Emits an event asynchronously and waits for all listeners to complete.
-   * Unlike the standard EventEmitter.emit() which is synchronous, this method
-   * properly handles async event listeners by waiting for all of them to
-   * resolve or reject using Promise.allSettled().
-   *
-   * @param {string} event - The event name to emit
-   * @param {...unknown} [arg] - Arguments to pass to event listeners
-   * @returns {Promise<void>} Resolves when all listeners have completed
-   */
-  async asyncEmit(event, arg) {
-    try {
-      arg = arg || new Array()
-      const listeners = this.emitter.listeners(event)
-
-      const settled =
-        await Promise.allSettled(listeners.map(listener => listener(arg)))
-
-      const rejected = settled.filter(reject => reject.status === "rejected")
-
-      if(rejected.length > 0) {
-        if(rejected[0].reason instanceof Error)
-          throw rejected[0].reason
-        else
-          throw Sass.new(rejected[0].reason)
-      }
-    } catch(error) {
-      throw Sass.new(
-        `Processing '${event}' event with ${arg&&arg.length?`'${arg}'`:"no arguments"}.`,
-        error
-      )
-    }
-  }
 }

package/types/BuildCommand.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Command handler for building VS Code themes from source files.
+ * Handles compilation, watching for changes, and output generation.
+ */
+export default class BuildCommand extends Command {
+    /**
+     * Creates a new BuildCommand instance.
+     *
+     * @param {object} base - Base configuration object
+     * @param {string} base.cwd - Current working directory path
+     * @param {object} base.packageJson - Package.json configuration data
+     */
+    constructor(base: {
+        cwd: string;
+        packageJson: object;
+    });
+    /** @type {EventEmitter} Internal event emitter for watch mode coordination */
+    emitter: EventEmitter;
+    /**
+     * Executes the build command for the provided theme files.
+     * Processes each file in parallel, optionally watching for changes.
+     *
+     * @param {string[]} fileNames - Array of theme file paths to process
+     * @param {object} options - Build options
+     * @param {boolean} [options.watch] - Enable watch mode for file changes
+     * @param {string} [options.output-dir] - Custom output directory path
+     * @param {boolean} [options.dry-run] - Print JSON to stdout without writing files
+     * @param {boolean} [options.silent] - Silent mode, only show errors or dry-run output
+     * @returns {Promise<void>} Resolves when all files are processed
+     * @throws {Error} When theme compilation fails
+     */
+    execute(fileNames: string[], options: {
+        watch?: boolean;
+        output?: string;
+        dry?: boolean;
+        silent?: boolean;
+    }): Promise<void>;
+    #private;
+}
+import Command from "./Command.js";

package/types/Colour.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Colour manipulation utility class providing static methods for colour operations.
+ * Handles hex colour parsing, alpha manipulation, mixing, and format conversions.
+ */
+export default class Colour {
+    /**
+     * Regular expression for matching long hex colour codes with optional alpha.
+     * Matches patterns like #ff0000 or #ff0000ff
+     *
+     * @type {RegExp}
+     */
+    static longHex: RegExp;
+    /**
+     * Regular expression for matching short hex colour codes with optional alpha.
+     * Matches patterns like #f00 or #f00f
+     *
+     * @type {RegExp}
+     */
+    static shortHex: RegExp;
+    /**
+     * Lightens or darkens a hex colour by a specified amount.
+     * Always uses OKLCH as the working color space for consistent perceptual results.
+     *
+     * @param {string} hex - The hex colour code (e.g., "#ff0000" or "#f00")
+     * @param {number} amount - The amount to lighten (+) or darken (-) as a percentage
+     * @returns {string} The modified hex colour with preserved alpha
+     */
+    static lightenOrDarken(hex: string, amount?: number): string;
+    /**
+     * Lightens or darkens a color using OKLCH as working space for consistent results.
+     * Preserves original color information from tokens when available.
+     *
+     * @param {ThemeToken|object|string} tokenOrColor - ThemeToken, Culori color object, or hex string
+     * @param {number} amount - The amount to lighten (+) or darken (-) as a percentage
+     * @returns {string} The modified hex colour
+     */
+    static lightenOrDarkenWithToken(tokenOrColor: ThemeToken | object | string, amount?: number): string;
+    /**
+     * Inverts a hex colour by flipping its lightness value.
+     * Preserves hue and saturation while inverting the lightness component.
+     *
+     * @param {string} hex - The hex colour code to invert
+     * @returns {string} The inverted hex colour with preserved alpha
+     */
+    static invert(hex: string): string;
+    /**
+     * Converts a hex alpha value to a decimal percentage.
+     * Takes a 2-digit hex alpha value and converts it to a percentage (0-100).
+     *
+     * @param {string} hex - The hex alpha value (e.g., "ff", "80")
+     * @returns {number} The alpha as a percentage rounded to 2 decimal places
+     */
+    static hexAlphaToDecimal(hex: string): number;
+    /**
+     * Converts a decimal percentage to a hex alpha value.
+     * Takes a percentage (0-100) and converts it to a 2-digit hex alpha value.
+     *
+     * @param {number} dec - The alpha percentage (0-100)
+     * @returns {string} The hex alpha value (e.g., "ff", "80")
+     */
+    static decimalAlphaToHex(dec: number): string;
+    static isHex(value: any): boolean;
+    /**
+     * Normalises a short hex colour code to a full 6-character format.
+     * Converts 3-character hex codes like "#f00" to "#ff0000".
+     *
+     * @param {string} code - The short hex colour code
+     * @returns {string} The normalized 6-character hex colour code
+     */
+    static normaliseHex(code: string): string;
+    /**
+     * Parses a hex colour string and extracts colour and alpha components.
+     * Supports both short (#f00) and long (#ff0000) formats with optional alpha.
+     *
+     * @param {string} hex - The hex colour string to parse
+     * @returns {object} Object containing colour and optional alpha information
+     * @throws {Sass} If the hex value is invalid or missing
+     */
+    static parseHexColour(hex: string): object;
+    /**
+     * Sets the alpha transparency of a hex colour to a specific value.
+     * Replaces any existing alpha with the new value.
+     *
+     * @param {string} hex - The hex colour code
+     * @param {number} amount - The alpha value (0-1, where 0 is transparent and 1 is opaque)
+     * @returns {string} The hex colour with the new alpha value
+     */
+    static setAlpha(hex: string, amount: number): string;
+    /**
+     * Adjusts the alpha transparency of a hex colour by a relative amount.
+     * Multiplies the current alpha by (1 + amount) and clamps the result.
+     *
+     * @param {string} hex - The hex colour code
+     * @param {number} amount - The relative amount to adjust alpha (-1 to make transparent, positive to increase)
+     * @returns {string} The hex colour with adjusted alpha
+     */
+    static addAlpha(hex: string, amount: number): string;
+    /**
+     * Removes alpha channel from a hex colour, returning only the solid colour.
+     *
+     * @param {string} hex - The hex colour code with or without alpha
+     * @returns {string} The solid hex colour without alpha
+     */
+    static solid(hex: string): string;
+    /**
+     * Mixes two hex colours together in a specified ratio.
+     * Blends both the colours and their alpha channels if present.
+     *
+     * @param {string} colourA - The first hex colour
+     * @param {string} colourB - The second hex colour
+     * @param {number} ratio - The mixing ratio as percentage (0-100, where 50 is equal mix)
+     * @returns {string} The mixed hex colour with blended alpha
+     */
+    static mix(colourA: string, colourB: string, ratio?: number): string;
+    static getColourParser(name: any): Promise<any>;
+    /**
+     * Converts colour values from various formats to hex.
+     * Supports RGB, RGBA, HSL, HSLA, OKLCH, and OKLCHA colour modes, and MORE!
+     *
+     * @param {string} input - The colour expression
+     * @returns {string} The resulting hex colour
+     * @throws {Sass} If the wrong function or value is provided
+     */
+    static toHex(input: string): string;
+}
+import ThemeToken from "./ThemeToken.js";

package/types/Command.d.ts

@@ -0,0 +1,135 @@
+import type { FileObject, DirectoryObject, Cache } from '@gesslar/toolkit';
+/**
+ * Base class for command-line interface commands.
+ * Provides common functionality for CLI option handling and file resolution.
+ */
+export default class Command {
+    /**
+     * Creates a new Command instance.
+     *
+     * @param {object} config - Configuration object
+     * @param {DirectoryObject} config.cwd - Current working directory object
+     * @param {object} config.packageJson - Package.json data
+     */
+    constructor({ cwd, packageJson }: {
+        cwd: DirectoryObject;
+        packageJson: object;
+    });
+    /**
+     * Gets the current working directory object.
+     *
+     * @returns {DirectoryObject} The current working directory
+     */
+    getCwd(): DirectoryObject;
+    /**
+     * Gets the package.json data.
+     *
+     * @returns {object} The package.json object
+     */
+    getPackageJson(): object;
+    /**
+     * Sets the cache instance for the command.
+     *
+     * @param {Cache} cache - The cache instance to set
+     * @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;
+    /**
+     * Sets the CLI command string.
+     *
+     * @param {string} data - The CLI command string
+     * @returns {this} Returns this instance for method chaining
+     */
+    setCliCommand(data: string): this;
+    /**
+     * Gets the CLI command string.
+     *
+     * @returns {string|null} The CLI command string
+     */
+    getCliCommand(): string | null;
+    /**
+     * Sets the CLI options object.
+     *
+     * @param {object} data - The CLI options configuration
+     * @returns {this} Returns this instance for method chaining
+     */
+    setCliOptions(data: object): this;
+    /**
+     * Gets the CLI options object.
+     *
+     * @returns {object|null} The CLI options configuration
+     */
+    getCliOptions(): object | null;
+    /**
+     * Gets the array of CLI option names.
+     *
+     * @returns {string[]} Array of option names
+     */
+    getCliOptionNames(): string[];
+    /**
+     * Checks if the command has a cache instance.
+     *
+     * @returns {boolean} True if cache is available
+     */
+    hasCache(): boolean;
+    /**
+     * Checks if the command has a CLI command string configured.
+     *
+     * @returns {boolean} True if CLI command is set
+     */
+    hasCliCommand(): boolean;
+    /**
+     * Checks if the command has CLI options configured.
+     *
+     * @returns {boolean} True if CLI options are set
+     */
+    hasCliOptions(): boolean;
+    /**
+     * Checks if the command is ready to be built.
+     * Requires both CLI command and options to be set.
+     *
+     * @returns {boolean} True if command can be built
+     */
+    canBuild(): boolean;
+    /**
+     * Builds the CLI command interface using the commander.js program instance.
+     * Initializes the command with its options and action handler.
+     *
+     * @param {object} program - The commander.js program instance
+     * @returns {Promise<this>} Returns this instance for method chaining
+     */
+    buildCli(program: object): Promise<this>;
+    /**
+     * Adds a single CLI option to the command.
+     *
+     * @param {string} name - The option name
+     * @param {string[]} options - Array containing option flag and description
+     * @param {boolean} preserve - Whether to preserve this option name in the list
+     * @returns {Promise<this>} Returns this instance for method chaining
+     */
+    addCliOption(name: string, options: string[], preserve: boolean): Promise<this>;
+    /**
+     * Adds multiple CLI options to the command.
+     *
+     * @param {object} options - Object mapping option names to [flag, description] arrays
+     * @param {boolean} preserve - Whether to preserve option names in the list
+     * @returns {this} Returns this instance for method chaining
+     */
+    addCliOptions(options: object, preserve: boolean): this;
+    /**
+     * Resolves a theme file name to a FileObject and validates its existence.
+     *
+     * @param {string} fileName - The theme file name or path
+     * @param {object} cwd - The current working directory object
+     * @returns {Promise<FileObject>} The resolved and validated FileObject
+     * @throws {Sass} If the file does not exist
+     */
+    resolveThemeFileName(fileName: string, cwd: object): Promise<FileObject>;
+    #private;
+}

package/types/Compiler.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Main compiler class for processing theme source files.
+ * Handles the complete compilation pipeline from source to VS Code theme output.
+ */
+export default class Compiler {
+    /**
+     * Compiles a theme source file into a VS Code colour theme.
+     * Processes configuration, variables, imports, and theme definitions.
+     *
+     * @param {Theme} theme - The file object containing source data and metadata
+     * @returns {Promise<void>} Resolves when compilation is complete
+     */
+    compile(theme: Theme): Promise<void>;
+    #private;
+}
+import Theme from "./Theme.js";

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";

package/types/ThemePool.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ThemePool represents a collection of ThemeTokens serving both as a
+ * lookup of string>ThemeToken and dependencies.
+ *
+ * @class ThemePool
+ */
+export default class ThemePool {
+    /**
+     * Returns the map of encoded theme token ids to their token object.
+     *
+     * @returns {Map<string, ThemeToken>} Map of tokens to their children.
+     */
+    getTokens(): Map<string, ThemeToken>;
+    /**
+     * Retrieves a resolved token by its name.
+     *
+     * @param {string} name - The token to look up.
+     * @returns {string|undefined} The resolved token string or undefined.
+     */
+    lookup(name: string): string | undefined;
+    /**
+     * Sets a resolved value for a token key.
+     *
+     * @param {string} key - The token key.
+     * @param {string} value - The resolved value.
+     */
+    resolve(key: string, value: string): void;
+    /**
+     * Sets a raw resolved value for a token key.
+     *
+     * @param {string} key - The token key.
+     * @param {string} value - The raw resolved value.
+     */
+    rawResolve(key: string, value: string): void;
+    /**
+     * Checks if a token name exists in resolved map.
+     *
+     * @param {string} name - The token name to check.
+     * @returns {boolean} True if the token exists.
+     */
+    has(name: string): boolean;
+    /**
+     * Checks if a token exists by its name.
+     *
+     * @param {ThemeToken} token - The token to check.
+     * @returns {boolean} True if the token exists.
+     */
+    hasToken(token: ThemeToken): boolean;
+    /**
+     * Retrieves a token's dependency.
+     *
+     * @param {ThemeToken} token - The token to look up.
+     * @returns {ThemeToken?} The dependent token with the given token, or undefined.
+     */
+    reverseLookup(token: ThemeToken): ThemeToken | null;
+    /**
+     * Adds a token to the pool, optionally setting up dependencies if required.
+     *
+     * @param {ThemeToken} token - The token to add.
+     * @param {ThemeToken} [dependency] - The dependent token.
+     * @returns {ThemeToken} The token that was added.
+     */
+    addToken(token: ThemeToken, dependency?: ThemeToken): ThemeToken;
+    /**
+     * Finds a token by its value.
+     *
+     * @param {string} value - The value to search for.
+     * @returns {ThemeToken|undefined} The found token or undefined.
+     */
+    findToken(value: string): ThemeToken | undefined;
+    /**
+     * Checks if one token is an ancestor of another using reverse lookup.
+     *
+     * @param {ThemeToken} candidate - Potential ancestor token.
+     * @param {ThemeToken} token - Potential descendant token.
+     * @returns {boolean} True if candidate is an ancestor of token.
+     */
+    isAncestorOf(candidate: ThemeToken, token: ThemeToken): boolean;
+    #private;
+}
+import ThemeToken from "./ThemeToken.js";

package/types/ThemeToken.d.ts

@@ -0,0 +1,150 @@
+/**
+ * ThemeToken represents a single token in a theme tree, encapsulating theme
+ * token data and relationships.
+ *
+ * Provides property management, factory methods, tree integration, and
+ * serialization.
+ *
+ * @class ThemeToken
+ */
+export default class ThemeToken {
+    /**
+     * Constructs a ThemeToken with a given token name.
+     *
+     * @param {string} name - The token name for this token.
+     */
+    constructor(name: string);
+    /**
+     * Adds this token to a ThemePool with optional dependency.
+     *
+     * @param {ThemePool} pool - The pool to add to.
+     * @param {ThemeToken} [dependency] - Optional dependency token.
+     * @returns {ThemeToken} This token instance.
+     */
+    addToPool(pool?: ThemePool, dependency?: ThemeToken): ThemeToken;
+    /**
+     * Sets the name of this token (only if not already set).
+     *
+     * @param {string} name - The token name.
+     * @returns {ThemeToken} This token instance.
+     */
+    setName(name: string): ThemeToken;
+    /**
+     * Gets the name of this token.
+     *
+     * @returns {string} The token name.
+     */
+    getName(): string;
+    /**
+     * Sets the kind of this token (only if not already set).
+     *
+     * @param {string} kind - The token kind.
+     * @returns {ThemeToken} This token instance.
+     */
+    setKind(kind: string): ThemeToken;
+    /**
+     * Gets the kind of this token.
+     *
+     * @returns {string} The token kind.
+     */
+    getKind(): string;
+    /**
+     * Sets the value of this token.
+     *
+     * @param {string} value - The token value.
+     * @returns {ThemeToken} This token instance.
+     */
+    setValue(value: string): ThemeToken;
+    /**
+     * Gets the value of this token.
+     *
+     * @returns {string} The token value.
+     */
+    getValue(): string;
+    /**
+     * Sets the raw value of this token (only if not already set).
+     *
+     * @param {string} raw - The raw token value.
+     * @returns {ThemeToken} This token instance.
+     */
+    setRawValue(raw: string): ThemeToken;
+    /**
+     * Gets the raw value of this token.
+     *
+     * @returns {string} The raw token value.
+     */
+    getRawValue(): string;
+    /**
+     * Sets the dependency of this token (only if not already set).
+     *
+     * @param {ThemeToken} dependency - The dependency token.
+     * @returns {ThemeToken} This token instance.
+     */
+    setDependency(dependency: ThemeToken): ThemeToken;
+    /**
+     * Gets the dependency of this token.
+     *
+     * @returns {ThemeToken|null} The dependency token or null.
+     */
+    getDependency(): ThemeToken | null;
+    /**
+     * Sets the parent token key.
+     *
+     * @param {string} tokenKey - The parent token key.
+     * @returns {ThemeToken} This token instance.
+     */
+    setParentTokenKey(tokenKey: string): ThemeToken;
+    /**
+     * Gets the parent token key.
+     *
+     * @returns {string|null} The parent token key or null.
+     */
+    getParentTokenKey(): string | null;
+    /**
+     * Adds a trail of tokens to this token's trail array.
+     *
+     * @param {Array<ThemeToken>} trail - Array of tokens to add.
+     * @returns {ThemeToken} This token instance.
+     */
+    addTrail(trail: Array<ThemeToken>): ThemeToken;
+    /**
+     * Gets the trail array of this token.
+     *
+     * @returns {Array<ThemeToken>} The trail array.
+     */
+    getTrail(): Array<ThemeToken>;
+    /**
+     * Sets the parsed color object for this token.
+     *
+     * @param {object} parsedColor - The parsed Culori color object
+     * @returns {ThemeToken} This token instance.
+     */
+    setParsedColor(parsedColor: object): ThemeToken;
+    /**
+     * Gets the parsed color object of this token.
+     *
+     * @returns {object|null} The parsed Culori color object or null.
+     */
+    getParsedColor(): object | null;
+    /**
+     * Checks if this token has an ancestor with the given token name.
+     *
+     * @param {string} name - The name of the ancestor token to check for.
+     * @returns {boolean} True if ancestor exists.
+     */
+    hasDependency(name: string): boolean;
+    /**
+     * Gets the ThemePool associated with this token.
+     *
+     * @returns {ThemePool} The associated pool.
+     */
+    getPool(): ThemePool;
+    /**
+     * Returns a JSON representation of the ThemeToken.
+     *
+     * @returns {object} JSON representation of the ThemeToken
+     */
+    toJSON(): object;
+    #private;
+}
+import ThemePool from "./ThemePool.js";

package/types/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/types/index.d.ts

@@ -0,0 +1,9 @@
+export { default as Theme } from "./Theme.js";
+export { default as Compiler } from "./Compiler.js";
+export { default as Evaluator } from "./Evaluator.js";
+export { default as Command } from "./Command.js";
+export { default as BuildCommand } from "./BuildCommand.js";
+export { default as LintCommand } from "./LintCommand.js";
+export { default as ResolveCommand } from "./ResolveCommand.js";
+export { default as Session } from "./Session.js";
+export { default as Colour } from "./Colour.js";