@gesslar/sassy 0.21.1 → 0.22.0

package/package.json

@@ -1,23 +1,33 @@
 {
   "name": "@gesslar/sassy",
-  "version": "0.21.1",
+  "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/cli.js",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
   "bin": "src/cli.js",
+  "exports": {
+    ".": {
+      "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"
@@ -43,6 +53,7 @@
   ],
   "dependencies": {
     "@gesslar/colours": "^0.0.1",
+    "@gesslar/toolkit": "^0.0.3",
     "chokidar": "^4.0.3",
     "color-support": "^1.1.3",
     "commander": "^14.0.1",
@@ -52,13 +63,13 @@
     "yaml": "^2.8.1"
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin": "^5.3.1",
+    "@stylistic/eslint-plugin": "^5.4.0",
     "@types/vscode": "^1.104.0",
     "@typescript-eslint/eslint-plugin": "^8.44.0",
     "@typescript-eslint/parser": "^8.44.0",
     "esbuild": "^0.25.10",
-    "eslint": "^9.35.0",
-    "eslint-plugin-jsdoc": "^59.0.1",
+    "eslint": "^9.36.0",
+    "eslint-plugin-jsdoc": "^60.1.0",
     "typescript": "^5.9.2"
   }
 }

package/src/BuildCommand.js

@@ -1,10 +1,9 @@
 import {EventEmitter} from "node:events"
 import process from "node:process"
 
+import {Sass, Term} from "@gesslar/toolkit"
 import Command from "./Command.js"
-import Sass from "./Sass.js"
 import Session from "./Session.js"
-import Term from "./Term.js"
 import Theme from "./Theme.js"
 
 /**

package/src/Colour.js

@@ -13,10 +13,8 @@ import {
   parse
 } from "culori"
 
-import Sass from "./Sass.js"
+import {Util, Sass} from "@gesslar/toolkit"
 import ThemeToken from "./ThemeToken.js"
-import Util from "./Util.js"
-
 // Cache for parsed colours to improve performance
 const _colourCache = new Map()
 

package/src/Command.js

@@ -1,7 +1,4 @@
-import Sass from "./Sass.js"
-import FileObject from "./FileObject.js"
-import DirectoryObject from "./DirectoryObject.js"
-import Cache from "./Cache.js"
+import {Sass, FileObject, DirectoryObject, Cache} from "@gesslar/toolkit"
 
 /**
  * Base class for command-line interface commands.
@@ -237,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/src/Compiler.js

@@ -11,14 +11,9 @@
  * Supports extension points for custom phases and output formats.
  */
 
-import Sass from "./Sass.js"
-import Data from "./Data.js"
+import {Sass, Data, File, FileObject, Term, Util} from "@gesslar/toolkit"
 import Evaluator from "./Evaluator.js"
-import File from "./File.js"
-import FileObject from "./FileObject.js"
-import Term from "./Term.js"
 import Theme from "./Theme.js"
-import Util from "./Util.js"
 
 /**
  * Main compiler class for processing theme source files.

package/src/Evaluator.js

@@ -13,7 +13,7 @@
 
 import {parse} from "culori"
 
-import Sass from "./Sass.js"
+import {Sass} from "@gesslar/toolkit"
 import Colour from "./Colour.js"
 import ThemePool from "./ThemePool.js"
 import ThemeToken from "./ThemeToken.js"

package/src/LintCommand.js

@@ -20,9 +20,8 @@ import c from "@gesslar/colours"
 
 import Command from "./Command.js"
 import Evaluator from "./Evaluator.js"
-import File from "./File.js"
-import Term from "./Term.js"
 import Theme from "./Theme.js"
+import {Term} from "@gesslar/toolkit"
 import ThemePool from "./ThemePool.js"
 
 // oops, need to have @gesslar/colours support this, too!

package/src/ResolveCommand.js

@@ -2,13 +2,10 @@ import c from "@gesslar/colours"
 // import colorSupport from "color-support"
 
 import Command from "./Command.js"
-import Sass from "./Sass.js"
+import {Sass, Term, Util, Data} from "@gesslar/toolkit"
 import Colour from "./Colour.js"
 import Evaluator from "./Evaluator.js"
-import Term from "./Term.js"
 import Theme from "./Theme.js"
-import Util from "./Util.js"
-import Data from "./Data.js"
 
 // ansiColors.enabled = colorSupport.hasBasic
 
@@ -436,10 +433,10 @@ export default class ResolveCommand extends Command {
 
     if(this.#func.test(value)) {
       const result = Evaluator.extractFunctionCall(value)
-      
+
       if(!result)
         return [c`{leaf}${value}{/}`, "literal"]
-        
+
       const {func, args} = result
 
       return [

package/src/Session.js

@@ -1,11 +1,8 @@
 import chokidar from "chokidar"
 
 import Command from "./Command.js"
-import Sass from "./Sass.js"
-import File from "./File.js"
-import Term from "./Term.js"
+import {Sass, File, Term, Util} from "@gesslar/toolkit"
 import Theme from "./Theme.js"
-import Util from "./Util.js"
 
 /**
  * @typedef {object} SessionOptions

package/src/Theme.js

@@ -13,15 +13,9 @@
  * - Write output files, supporting dry-run and hash-based skip
  * - Support watch mode for live theme development
  */
-import Sass from "./Sass.js"
+import {Sass, DirectoryObject, File, FileObject, Term, Util, Cache} from "@gesslar/toolkit"
 import Compiler from "./Compiler.js"
-import DirectoryObject from "./DirectoryObject.js"
-import File from "./File.js"
-import FileObject from "./FileObject.js"
-import Term from "./Term.js"
 import ThemePool from "./ThemePool.js"
-import Util from "./Util.js"
-import Cache from "./Cache.js"
 
 const outputFileExtension = "color-theme.json"
 const obviouslyASentinelYouCantMissSoShutUpAboutIt = "kakadoodoo"

package/src/ThemePool.js

@@ -6,7 +6,7 @@
  * Manages resolved values, raw resolutions, and token relationships during theme compilation.
  */
 
-import Sass from "./Sass.js"
+import {Sass} from "@gesslar/toolkit"
 import ThemeToken from "./ThemeToken.js"
 
 /**

package/src/ThemeToken.js

@@ -7,7 +7,7 @@
  * management, pool integration, and serialization during theme compilation.
  */
 
-import Sass from "./Sass.js"
+import {Sass} from "@gesslar/toolkit"
 import ThemePool from "./ThemePool.js"
 
 /**

package/src/cli.js

@@ -36,14 +36,10 @@ import process from "node:process"
 import url from "node:url"
 import c from "@gesslar/colours"
 
-import Cache from "./Cache.js"
-import Sass from "./Sass.js"
+import {Cache, Sass, DirectoryObject, FileObject, Term} from "@gesslar/toolkit"
 import BuildCommand from "./BuildCommand.js"
-import DirectoryObject from "./DirectoryObject.js"
-import FileObject from "./FileObject.js"
 import LintCommand from "./LintCommand.js"
 import ResolveCommand from "./ResolveCommand.js"
-import Term from "./Term.js"
 
 /**
  * Main application entry point.

package/src/index.js

@@ -0,0 +1,40 @@
+/**
+ * @file API entry point for @gesslar/sassy
+ *
+ * Exports classes and utilities for programmatic use by other npm packages.
+ *
+ * This allows other projects to import and use Sassy's functionality
+ * programmatically.
+ *
+ * @example
+ * // Import specific classes
+ * import { Theme, LintCommand, Compiler } from '@gesslar/sassy'
+ *
+ * // Import everything
+ * import * as Sassy from '@gesslar/sassy'
+ *
+ * // Create and use a Theme programmatically
+ * const theme = new Theme(fileObject)
+ * await theme.load('./my-theme.json5')
+ * await theme.build()
+ */
+
+// Core theme functionality
+export {default as Theme} from "./Theme.js"
+export {default as Compiler} from "./Compiler.js"
+export {default as Evaluator} from "./Evaluator.js"
+
+// Command classes for programmatic access
+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"
+
+// Data handling and utilities
+export {default as Session} from "./Session.js"
+
+// Color utilities
+export {default as Colour} from "./Colour.js"
+
+// Note: CLI functionality remains in cli.js and is accessible via the 'sassy'
+// command when installed globally or via npx

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