@gesslar/sassy 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/sassy",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "displayName": "Sassy",
   "description": "Make gorgeous themes that speak as boldly as you do.",
   "publisher": "gesslar",
@@ -19,7 +19,8 @@
     "lint": "eslint src/",
     "submit": "npm publish --access public",
     "examples": "node ./examples/validator.js",
-    "test": "node -p \"require('fs').readFileSync('TESTING.txt', 'utf8')\""
+    "test": "node -p \"require('fs').readFileSync('TESTING.txt', 'utf8')\"",
+    "update": "npx npm-check-updates -u && npm install"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -44,17 +45,20 @@
     "@gesslar/colours": "^0.0.1",
     "chokidar": "^4.0.3",
     "color-support": "^1.1.3",
-    "commander": "^14.0.0",
+    "commander": "^14.0.1",
     "culori": "^4.0.2",
     "globby": "^14.1.0",
     "json5": "^2.2.3",
     "yaml": "^2.8.1"
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin": "^5.2.3",
-    "@typescript-eslint/eslint-plugin": "^8.33.0",
-    "@typescript-eslint/parser": "^8.33.0",
-    "eslint": "^9.28.0",
-    "eslint-plugin-jsdoc": "^50.6.17"
+    "@stylistic/eslint-plugin": "^5.3.1",
+    "@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",
+    "typescript": "^5.9.2"
   }
 }

package/src/BuildCommand.js

@@ -28,13 +28,13 @@ export default class BuildCommand extends Command {
   constructor(base) {
     super(base)
 
-    this.cliCommand = "build <file...>"
-    this.cliOptions = {
+    this.setCliCommand("build <file...>")
+    this.setCliOptions({
       "watch": ["-w, --watch", "watch for changes"],
       "output-dir": ["-o, --output-dir <dir>", "specify an output directory"],
       "dry-run": ["-n, --dry-run", "print theme JSON to stdout; do not write files"],
       "silent": ["-s, --silent", "silent mode. only print errors or dry-run"],
-    }
+    })
   }
 
   /**
@@ -51,7 +51,7 @@ export default class BuildCommand extends Command {
    * @throws {Error} When theme compilation fails
    */
   async execute(fileNames, options) {
-    const {cwd} = this
+    const cwd = this.getCwd()
 
     if(options.watch) {
       options.watch && this.#initialiseInputHandler()
@@ -69,7 +69,7 @@ export default class BuildCommand extends Command {
       fileNames.map(async fileName => {
         const fileObject = await this.resolveThemeFileName(fileName, cwd)
         const theme = new Theme(fileObject, cwd, options)
-        theme.cache = this.cache
+          .setCache(this.getCache())
 
         return new Session(this, theme, options)
       })
@@ -83,12 +83,11 @@ export default class BuildCommand extends Command {
     }
 
     const sessions = sessionResults.map(result => result.value)
-    const firstRun = await Promise.allSettled(
-      sessions.map(async session => await session.run())
-    )
+    const firstRun = await Promise.allSettled(sessions.map(
+      async session => await session.run()))
     const rejected = firstRun.filter(reject => reject.status === "rejected")
-    if(rejected.length > 0) {
 
+    if(rejected.length > 0) {
       rejected.forEach(reject => Term.error(reject.reason))
 
       if(firstRun.length === rejected.length)

package/src/Cache.js

@@ -52,6 +52,7 @@ export default class Cache {
 
     if(this.#modifiedTimes.has(fileObject.path)) {
       const lastCached = this.#modifiedTimes.get(fileObject.path)
+
       if(lastModified > lastCached) {
         this.#cleanup(fileObject)
       } else {

package/src/Colour.js

@@ -23,7 +23,6 @@ const _colourCache = new Map()
 // Cache for mixed colours to avoid recomputation
 const _mixCache = new Map()
 
-
 /**
  * Parses a colour string into a colour object with caching.
  *
@@ -58,10 +57,12 @@ const asColour = s => {
     throw Sass.new("asColour(): received null/undefined")
 
   const k = String(s).trim()
+
   if(!k)
     throw Sass.new("asColour(): received empty string")
 
   let v = _colourCache.get(k)
+
   if(!v) {
     v = parse(k) // returns undefined if invalid
 
@@ -140,9 +141,11 @@ export default class Colour {
 
     // Use multiplicative scaling for more natural results
     const factor = 1 + (amount / 100)
+
     oklchColor.l = clamp(oklchColor.l * factor, 0, 1)
 
     const result = `${formatHex(oklchColor)}${extracted.alpha?.hex??""}`.toLowerCase()
+
     return result
   }
 
@@ -177,12 +180,12 @@ export default class Colour {
 
     // Use multiplicative scaling
     const factor = 1 + (amount / 100)
+
     oklchColor.l = clamp(oklchColor.l * factor, 0, 1)
 
     return formatHex(oklchColor).toLowerCase()
   }
 
-
   /**
    * Inverts a hex colour by flipping its lightness value.
    * Preserves hue and saturation while inverting the lightness component.
@@ -193,6 +196,7 @@ export default class Colour {
   static invert(hex) {
     const extracted = Colour.parseHexColour(hex)
     const hslColour = hsl(extracted.colour)
+
     hslColour.l = 1 - hslColour.l  // culori uses 0-1 for lightness
     const modifiedColour = formatHex(hslColour)
 
@@ -360,6 +364,7 @@ export default class Colour {
 
     // memoize by raw inputs (strings) + normalized ratio
     const key = mixKey(colourA, colourB, t)
+
     if(_mixCache.has(key))
       return _mixCache.get(key)
 
@@ -379,6 +384,7 @@ export default class Colour {
     const out = (a < 1 ? formatHex8(withAlpha) : formatHex(mixed)).toLowerCase()
 
     _mixCache.set(key, out)
+
     return out
   }
 

package/src/Command.js

@@ -1,5 +1,6 @@
 import Sass from "./Sass.js"
 import FileObject from "./FileObject.js"
+import DirectoryObject from "./DirectoryObject.js"
 
 /**
  * Base class for command-line interface commands.
@@ -19,7 +20,7 @@ export default class Command {
    * Creates a new Command instance.
    *
    * @param {object} config - Configuration object
-   * @param {object} config.cwd - Current working directory object
+   * @param {DirectoryObject} config.cwd - Current working directory object
    * @param {object} config.packageJson - Package.json data
    */
   constructor({cwd,packageJson}) {
@@ -27,21 +28,12 @@ export default class Command {
     this.#packageJson = packageJson
   }
 
-  get cache() {
-    return this.#cache
-  }
-
-  set cache(cache) {
-    if(!this.#cache)
-      this.#cache = cache
-  }
-
   /**
    * Gets the current working directory object.
    *
-   * @returns {object} The current working directory
+   * @returns {DirectoryObject} The current working directory
    */
-  get cwd() {
+  getCwd() {
     return this.#cwd
   }
 
@@ -50,44 +42,71 @@ export default class Command {
    *
    * @returns {object} The package.json object
    */
-  get packageJson() {
+  getPackageJson() {
     return this.#packageJson
   }
 
   /**
-   * Gets the CLI command string.
+   * Sets the cache instance for the command.
    *
-   * @returns {string|null} The CLI command string
+   * @param {Cache} cache - The cache instance to set
+   * @returns {this} Returns this instance for method chaining
    */
-  get cliCommand() {
-    return this.#cliCommand
+  setCache(cache) {
+    this.#cache = cache
+
+    return this
+  }
+
+  /**
+   * Gets the cache instance.
+   *
+   * @returns {Cache|null} The cache instance or null if not set
+   */
+  getCache() {
+    return this.#cache
   }
 
   /**
    * Sets the CLI command string.
    *
    * @param {string} data - The CLI command string
+   * @returns {this} Returns this instance for method chaining
    */
-  set cliCommand(data) {
+  setCliCommand(data) {
     this.#cliCommand = data
+
+    return this
   }
 
   /**
-   * Gets the CLI options object.
+   * Gets the CLI command string.
    *
-   * @returns {object|null} The CLI options configuration
+   * @returns {string|null} The CLI command string
    */
-  get cliOptions() {
-    return this.#cliOptions
+  getCliCommand() {
+    return this.#cliCommand
   }
 
   /**
    * Sets the CLI options object.
    *
    * @param {object} data - The CLI options configuration
+   * @returns {this} Returns this instance for method chaining
    */
-  set cliOptions(data) {
+  setCliOptions(data) {
     this.#cliOptions = data
+
+    return this
+  }
+
+  /**
+   * Gets the CLI options object.
+   *
+   * @returns {object|null} The CLI options configuration
+   */
+  getCliOptions() {
+    return this.#cliOptions
   }
 
   /**
@@ -95,10 +114,47 @@ export default class Command {
    *
    * @returns {string[]} Array of option names
    */
-  get cliOptionNames() {
+  getCliOptionNames() {
     return this.#optionNames
   }
 
+  /**
+   * Checks if the command has a cache instance.
+   *
+   * @returns {boolean} True if cache is available
+   */
+  hasCache() {
+    return this.#cache !== null
+  }
+
+  /**
+   * Checks if the command has a CLI command string configured.
+   *
+   * @returns {boolean} True if CLI command is set
+   */
+  hasCliCommand() {
+    return this.#cliCommand !== null
+  }
+
+  /**
+   * Checks if the command has CLI options configured.
+   *
+   * @returns {boolean} True if CLI options are set
+   */
+  hasCliOptions() {
+    return this.#cliOptions !== null
+  }
+
+  /**
+   * 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() {
+    return this.hasCliCommand() && this.hasCliOptions()
+  }
+
   /**
    * Builds the CLI command interface using the commander.js program instance.
    * Initializes the command with its options and action handler.
@@ -107,22 +163,24 @@ export default class Command {
    * @returns {Promise<this>} Returns this instance for method chaining
    */
   async buildCli(program) {
-    if(!this.cliCommand)
+    if(!this.hasCliCommand())
       throw Sass.new("This command has no CLI command string.")
 
-    if(!this.cliOptions)
+    if(!this.hasCliOptions())
       throw Sass.new("This command has no CLI options.")
 
-    this.#command = program.command(this.cliCommand)
+    this.#command = program.command(this.getCliCommand())
     this.#command.action(async(...arg) => {
       try {
         await this.execute(...arg)
       } catch(error) {
-        throw Sass.new(`Trying to execute ${this.constructor.name} with ${JSON.stringify(...arg)}`, error)
+        throw Sass.new(
+          `Trying to execute ${this.constructor.name} with `+
+          `${JSON.stringify(...arg)}`, error)
       }
     })
 
-    this.addCliOptions(this.cliOptions, true)
+    this.addCliOptions(this.getCliOptions(), true)
 
     return this
   }
@@ -133,7 +191,7 @@ export default class 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 {this} Returns this instance for method chaining
+   * @returns {Promise<this>} Returns this instance for method chaining
    */
   addCliOption(name, options, preserve) {
     if(!this.#command)
@@ -185,7 +243,7 @@ export default class Command {
    * resolve or reject using Promise.allSettled().
    *
    * @param {string} event - The event name to emit
-   * @param {any[]} [arg] - Arguments to pass to event listeners
+   * @param {...unknown} [arg] - Arguments to pass to event listeners
    * @returns {Promise<void>} Resolves when all listeners have completed
    */
   async asyncEmit(event, arg) {
@@ -193,7 +251,9 @@ export default class Command {
       arg = arg || new Array()
       const listeners = this.emitter.listeners(event)
 
-      const settled = await Promise.allSettled(listeners.map(listener => listener(arg)))
+      const settled =
+        await Promise.allSettled(listeners.map(listener => listener(arg)))
+
       const rejected = settled.filter(reject => reject.status === "rejected")
 
       if(rejected.length > 0) {

package/src/Compiler.js

@@ -29,12 +29,12 @@ export default class Compiler {
    * Compiles a theme source file into a VS Code colour theme.
    * Processes configuration, variables, imports, and theme definitions.
    *
-   * @param {object} theme - The file object containing source data and metadata
+   * @param {Theme} theme - The file object containing source data and metadata
    * @returns {Promise<void>} Resolves when compilation is complete
    */
   async compile(theme) {
     try {
-      const source = theme.source
+      const source = theme.getSource()
       const {config: sourceConfig} = source ?? {}
       const {vars: sourceVars} = source
       const {theme: sourceTheme} = source
@@ -43,6 +43,7 @@ export default class Compiler {
       const evaluate = (...arg) => evaluator.evaluate(...arg)
 
       const config = this.#decomposeObject(sourceConfig)
+
       evaluate(config)
       const recompConfig = this.#composeObject(config)
 
@@ -54,9 +55,12 @@ export default class Compiler {
 
       // Let's get all of the imports!
       const imports = recompConfig.import ?? []
-      const {imported,importedFiles} = await this.#import(imports, theme)
+      const {imported,importByFile} =
+        await this.#import(imports, theme)
 
-      theme.dependencies = importedFiles
+      importByFile.forEach((themeData,file) => {
+        theme.addDependency(file,themeData)
+      })
 
       // Handle tokenColors separately - imports first, then main source
       // (append-only)
@@ -79,19 +83,28 @@ export default class Compiler {
 
       // Shred them up! Kinda. And evaluate the variables in place
       const vars = this.#decomposeObject(merged.vars)
+
       evaluate(vars)
+
       const workColors = this.#decomposeObject(merged.colors)
+
       evaluate(workColors)
+
       const workTokenColors = this.#decomposeObject(merged.tokenColors)
+
       evaluate(workTokenColors)
-      const workSemanticTokenColors = this.#decomposeObject(merged.semanticTokenColors)
+
+      const workSemanticTokenColors =
+        this.#decomposeObject(merged.semanticTokenColors)
+
       evaluate(workSemanticTokenColors)
 
-      theme.lookup = evaluator.lookup
+      theme.setLookup(evaluator.lookup)
 
       // Now let's do some reducing... into a form that works for VS Code
       const reducer = (acc,curr) => {
         acc[curr.flatPath] = curr.value
+
         return acc
       }
 
@@ -107,16 +120,16 @@ export default class Compiler {
         sourceConfig.custom ?? {},
         {
           colors,
+          tokenColors,
           semanticTokenColors,
-          tokenColors
         }
       )
 
       // Voilà!
-      theme.output = output
-      theme.pool = evaluator.pool
+      theme.setOutput(output)
+      theme.setPool(evaluator.pool)
     } catch(error) {
-      throw Sass.new(`Compiling ${theme.name}`, error)
+      throw Sass.new(`Compiling ${theme.getName()}`, error)
     }
   }
 
@@ -126,66 +139,78 @@ export default class Compiler {
    *
    * @param {Array<string>} imports - The import filenames.
    * @param {Theme} theme - The theme object being compiled.
-   * @returns {Promise<object>} Object containing imported data and file references
+   * @returns {Promise<object,Map>} Object containing imported data and file references
    */
   async #import(imports, theme) {
-    const importedFiles = []
     const imported = {
       vars: {},
       colors: {},
-      tokenColors: []
+      tokenColors: [],
+      semanticTokenColors: {}
     }
+    const importByFile = new Map()
 
     imports = typeof imports === "string"
       ? [imports]
       : imports
 
-
     if(!Data.isArrayUniform(imports, "string"))
       throw new Sass(
         `All import entries must be strings. Got ${JSON.stringify(imports)}`
       )
 
-    const loaded = []
+    const loaded = new Map()
 
     for(const importing of imports) {
       try {
-        const file = new FileObject(importing, theme.sourceFile.directory)
-
-        importedFiles.push(file)
+        const file = new FileObject(importing, theme.getSourceFile().directory)
 
         // Get the cached version or a new version. Who knows? I don't know.
         const {result, cost} = await Util.time(async() => {
-          return await theme.cache.loadCachedData(file)
+          return await theme.getCache().loadCachedData(file)
         })
 
-        if(theme.options.nerd) {
+        if(theme.getOptions().nerd) {
           Term.status([
             ["muted", Util.rightAlignText(`${cost.toLocaleString()}ms`, 10), ["[","]"]],
             "",
-            ["muted", `${File.relativeOrAbsolutePath(theme.cwd,file)}`],
-            ["muted", `${theme.name}`,["(",")"]],
-          ], theme.options)
+            ["muted", `${File.relativeOrAbsolutePath(theme.getCwd(),file)}`],
+            ["muted", `${theme.getName()}`,["(",")"]],
+          ], theme.getOptions())
         }
 
-        if(result) {
-          loaded.push(result)
-        }
+        if(result)
+          loaded.set(file, result)
+
       } catch(error) {
         throw Sass.new(`Attempting to import ${importing}`, error)
       }
     }
 
-    loaded.forEach(data => {
-      const {vars={}} = data ?? {}
-      const {colors={},tokenColors=[]} = data.theme ?? {}
-
-      imported.vars = Data.mergeObject(imported.vars, vars)
-      imported.colors = Data.mergeObject(imported.colors, colors)
-      imported.tokenColors = [...imported.tokenColors, ...tokenColors]
+    loaded.forEach((load, file) => {
+      const vars = load?.vars ?? {}
+      const colors = load?.theme?.colors ?? {}
+      const tokenColors = load?.theme?.tokenColors ?? []
+      const semanticTokenColors = load?.theme?.semanticTokenColors ?? {}
+
+      importByFile.set(file, new Map([
+        ["vars", vars],
+        ["colors", colors],
+        ["tokenColors", tokenColors],
+        ["semanticTokenColors", semanticTokenColors]
+      ]))
+
+      imported.vars =
+        Data.mergeObject(imported.vars, vars)
+      imported.colors =
+        Data.mergeObject(imported.colors, colors)
+      imported.tokenColors =
+        [...imported.tokenColors, ...tokenColors]
+      imported.semanticTokenColors =
+        Data.mergeObject(imported.semanticTokenColors, semanticTokenColors)
     })
 
-    return {imported,importedFiles}
+    return {imported,importByFile}
   }
 
   /**
@@ -209,8 +234,9 @@ export default class Compiler {
       if(isObject(item)) {
         result.push(...this.#decomposeObject(work[key], currPath))
       } else if(Array.isArray(work[key])) {
-        item.forEach((item, index) => {
+        work[key].forEach((item, index) => {
           const path = [...currPath, String(index+1)]
+
           result.push({
             key,
             value: String(item),
@@ -308,7 +334,7 @@ export default class Compiler {
    * Checks if a value is a plain object (not null or array).
    * Utility method for type checking during compilation.
    *
-   * @param {*} value - The value to check
+   * @param {unknown} value - The value to check
    * @returns {boolean} True if the value is a plain object
    */
   #isObject(value) {