@gesslar/sassy 0.20.0 → 0.21.0

package/src/Theme.js

@@ -22,6 +22,20 @@ import Term from "./Term.js"
 import ThemePool from "./ThemePool.js"
 import Util from "./Util.js"
 
+const outputFileExtension = "color-theme.json"
+const obviouslyASentinelYouCantMissSoShutUpAboutIt = "kakadoodoo"
+
+// Symbol enums for magic values
+const WriteStatus = {
+  DRY_RUN: Symbol("dry-run"),
+  SKIPPED: Symbol("skipped"),
+  WRITTEN: Symbol("written")
+}
+
+const PropertyKey = {
+  CONFIG: Symbol("config")
+}
+
 /**
  * Theme class: manages the lifecycle of a theme compilation unit.
  * See file-level docstring for responsibilities.
@@ -30,7 +44,13 @@ export default class Theme {
   #sourceFile = null
   #source = null
   #options = null
-  #dependencies = []
+  /**
+   * The dependencies of this theme.
+   *
+   * @type {Set<Dependency>}
+   * @private
+   */
+  #dependencies = new Set()
   #lookup = null
   #pool = null
   #cache = null
@@ -54,7 +74,7 @@ export default class Theme {
   constructor(themeFile, cwd, options) {
     this.#sourceFile = themeFile
     this.#name = themeFile.module
-    this.#outputFileName = `${this.#name}.color-theme.json`
+    this.#outputFileName = `${this.#name}.${outputFileExtension}`
     this.#options = options
     this.#cwd = cwd
   }
@@ -71,75 +91,223 @@ export default class Theme {
     this.#pool = null
   }
 
-  get cwd() {
+  /**
+   * Gets the current working directory.
+   *
+   * @returns {DirectoryObject} The current working directory
+   */
+  getCwd() {
     return this.#cwd
   }
 
-  get options() {
+  /**
+   * Gets the compilation options.
+   *
+   * @returns {object} The compilation options object
+   */
+  getOptions() {
     return this.#options
   }
 
-  set cache(cache) {
-    if(!this.cache)
+  /**
+   * Gets a specific compilation option.
+   *
+   * @param {string} option - The option name to retrieve
+   * @returns {*} The option value or undefined if not set
+   */
+  getOption(option) {
+    return this.#options?.[option] ?? undefined
+  }
+
+  /**
+   * 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) {
+    if(!this.#cache)
       this.#cache=cache
+
+    return this
   }
 
-  get cache() {
+  /**
+   * Gets the cache instance.
+   *
+   * @returns {Cache|null} The cache instance or null if not set
+   */
+  getCache() {
     return this.#cache
   }
 
-  get name() {
+  /**
+   * Gets the theme name.
+   *
+   * @returns {string} The theme name derived from the source file
+   */
+  getName() {
     return this.#name
   }
 
+  /**
+   * Gets the output file name for the compiled theme.
+   *
+   * @returns {string} The output file name with extension
+   */
+  getOutputFileName() {
+    return this.#outputFileName
+  }
+
   /**
    * Gets the source file object.
    *
    * @returns {FileObject} The source theme file
    */
-  get sourceFile() {
+  getSourceFile() {
     return this.#sourceFile
   }
 
+  /**
+   * 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) {
+    this.#output = data
+    this.#outputJson = JSON.stringify(data, null, 2) + "\n"
+    this.#outputHash = Util.hashOf(this.#outputJson)
+
+    return this
+  }
+
   /**
    * Gets the compiled theme output object.
    *
    * @returns {object|null} The compiled theme output
    */
-  get output() {
+  getOutput() {
     return this.#output
   }
 
   /**
-   * Sets the compiled theme output object and updates derived JSON and hash.
+   * Checks if the source has colors defined.
    *
-   * @param {object} data - The compiled theme output object
+   * @returns {boolean} True if source has theme colors
    */
-  set output(data) {
-    this.#output = data
-    this.#outputJson = JSON.stringify(data, null, 2) + "\n"
-    this.#outputHash = Util.hashOf(this.#outputJson)
+  sourceHasColors() {
+    return !!this.#source?.theme?.colors
+  }
+
+  /**
+   * Checks if the source has token colors defined.
+   *
+   * @returns {boolean} True if source has theme token colors
+   */
+  sourceHasTokenColors() {
+    return !!this.#source?.theme?.tokenColors
+  }
+
+  /**
+   * Checks if the source has semantic token colors defined.
+   *
+   * @returns {boolean} True if source has theme semantic token colors
+   */
+  sourceHasSemanticTokenColors() {
+    return !!this.#source?.theme?.semanticTokenColors
+  }
+
+  /**
+   * Checks if the source has theme configuration.
+   *
+   * @returns {boolean} True if source has theme data
+   */
+  sourceHasTheme() {
+    return !!this.#source?.theme
+  }
+
+  /**
+   * Checks if the source has variables.
+   *
+   * @returns {boolean} True if source has vars section
+   */
+  sourceHasVars() {
+    return !!this.#source?.vars
+  }
+
+  /**
+   * Checks if the source has config section.
+   *
+   * @returns {boolean} True if source has config
+   */
+  sourceHasConfig() {
+    return !!this.#source?.config
+  }
+
+  /**
+   * Gets the source colors data.
+   *
+   * @returns {object|null} The colors object or null if not defined
+   */
+  getSourceColors() {
+    if(!this.sourceHasColors())
+      return null
+
+    return this.#source.theme.colors
+  }
+
+  /**
+   * Gets the source token colors data.
+   *
+   * @returns {Array|null} The token colors array or null if not defined
+   */
+  getSourceTokenColors() {
+    if(!this.sourceHasTokenColors())
+      return null
+
+    return this.#source.theme.tokenColors
+  }
+
+  /**
+   * Gets the source semantic token colors data.
+   *
+   * @returns {object|null} The semantic token colors object or null if not defined
+   */
+  getSourceSemanticTokenColors() {
+    if(!this.sourceHasSemanticTokenColors())
+      return null
+
+    return this.#source.theme.semanticTokenColors
   }
 
   /**
    * Gets the array of file dependencies.
    *
-   * @returns {FileObject[]} Array of dependency files
+   * @returns {Set<Dependency>} Array of dependency files
    */
-  get dependencies() {
+  getDependencies() {
     return this.#dependencies
   }
 
   /**
-   * Sets the array of file dependencies.
+   * Adds a dependency to the theme with its source data.
    *
-   * @param {FileObject[]} data - Array of dependency files
+   * @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
    */
-  set dependencies(data) {
-    this.#dependencies = data
+  addDependency(file, source) {
+    this.#dependencies.add(
+      new Dependency()
+        .setSourceFile(file)
+        .setSource(source))
+
+    return this
+  }
 
-    if(!this.#dependencies.includes(this.#sourceFile))
-      this.#dependencies.unshift(this.#sourceFile)
+  hasDependencies() {
+    return this.#dependencies.size > 0
   }
 
   /**
@@ -147,7 +315,7 @@ export default class Theme {
    *
    * @returns {object|null} The parsed source data
    */
-  get source() {
+  getSource() {
     return this.#source
   }
 
@@ -156,7 +324,7 @@ export default class Theme {
    *
    * @returns {object|null} The lookup data object
    */
-  get lookup() {
+  getLookup() {
     return this.#lookup
   }
 
@@ -164,9 +332,12 @@ export default class Theme {
    * Sets the variable lookup data for theme compilation.
    *
    * @param {object} data - The lookup data object
+   * @returns {this} Returns this instance for method chaining
    */
-  set lookup(data) {
+  setLookup(data) {
     this.#lookup = data
+
+    return this
   }
 
   /**
@@ -175,7 +346,7 @@ export default class Theme {
    *
    * @returns {ThemePool|null} The pool for this theme.
    */
-  get pool() {
+  getPool() {
     return this.#pool
   }
 
@@ -186,13 +357,14 @@ export default class Theme {
    * @see reset
    *
    * @param {ThemePool} pool - The pool to assign to this theme
-   * @throws If there is already a pool.
+   * @throws {Error} If there is already a pool.
+   * @returns {this} Returns this instance for method chaining
    */
-  set pool(pool) {
-    if(this.#pool)
-      throw Sass.new("Cannot override existing pool.")
+  setPool(pool) {
+    if(!this.#pool)
+      this.#pool = pool
 
-    this.#pool = pool
+    return this
   }
 
   /**
@@ -204,36 +376,115 @@ export default class Theme {
     return this.#pool instanceof ThemePool
   }
 
+  /**
+   * Checks if the theme has compiled output.
+   *
+   * @returns {boolean} True if theme has been compiled
+   */
+  hasOutput() {
+    return this.#output !== null
+  }
+
+  /**
+   * Checks if the theme has loaded source data.
+   *
+   * @returns {boolean} True if source data is available
+   */
+  hasSource() {
+    return this.#source !== null
+  }
+
+  /**
+   * Checks if the theme has a cache instance.
+   *
+   * @returns {boolean} True if cache is available
+   */
+  hasCache() {
+    return this.#cache !== null
+  }
+
+  /**
+   * Checks if the theme has lookup data.
+   *
+   * @returns {boolean} True if lookup data exists
+   */
+  hasLookup() {
+    return this.#lookup !== null
+  }
+
+  /**
+   * 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() {
+    return this.hasSource() && this.hasCache()
+  }
+
+  /**
+   * 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() {
+    return this.hasOutput() && this.hasPool() && this.hasLookup()
+  }
+
+  /**
+   * Checks if the theme can be built/compiled.
+   * Same as isReady() but with more semantic naming.
+   *
+   * @returns {boolean} True if build can proceed
+   */
+  canBuild() {
+    return this.isReady()
+  }
+
+  /**
+   * Checks if the theme can be written to output.
+   * Requires the theme to be compiled.
+   *
+   * @returns {boolean} True if write can proceed
+   */
+  canWrite() {
+    return this.hasOutput()
+  }
+
+  /**
+   * 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() {
+    return this.#sourceFile !== null && this.#name !== null
+  }
+
   /**
    * 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
    */
   async load() {
+    // Skip loading if no cache (extension use case)
+    if(!this.#cache)
+      return this
+
     const source = await this.#cache.loadCachedData(this.#sourceFile)
 
-    if(!source.config)
+    if(!source[PropertyKey.CONFIG.description])
       throw Sass.new(
-        `Source file does not contain 'config' property: ${this.#sourceFile.path}`
+        `Source file does not contain '${PropertyKey.CONFIG.description}' property: ${this.#sourceFile.path}`
       )
 
     this.#source = source
-  }
 
-  /**
-   * Adds a file dependency to the theme.
-   *
-   * @param {FileObject} file - The file to add as a dependency
-   * @returns {this} Returns this instance for method chaining
-   * @throws {Sass} If the file parameter is not a valid file
-   */
-  addDependency(file) {
-    if(!file.isFile)
-      throw Sass.new("File must be a dependency.")
-
-    this.#dependencies.push(file)
+    this.addDependency(this.#sourceFile, this.#source)
 
     return this
   }
@@ -242,11 +493,14 @@ export default class Theme {
    * Builds the theme by compiling source data into final output.
    * Main entry point for theme compilation process.
    *
-   * @returns {Promise<void>} Resolves when build is complete.
+   * @returns {Promise<this>} Returns this instance for method chaining
    */
   async build() {
     const compiler = new Compiler()
+
     await compiler.compile(this)
+
+    return this
   }
 
   /**
@@ -264,7 +518,7 @@ export default class Theme {
     if(this.#options.dryRun) {
       Term.log(this.#outputJson)
 
-      return {status: "dry-run", file}
+      return {status: WriteStatus.DRY_RUN, file}
     }
 
     // Skip identical bytes
@@ -272,10 +526,10 @@ export default class Theme {
       const nextHash = this.#outputHash
       const lastHash = await file.exists
         ? Util.hashOf(await File.readFile(file))
-        : "kakadoodoo"
+        : obviouslyASentinelYouCantMissSoShutUpAboutIt
 
       if(lastHash === nextHash)
-        return {status: "skipped", file}
+        return {status: WriteStatus.SKIPPED, file}
     }
 
     // Real write (timed)
@@ -284,6 +538,77 @@ export default class Theme {
 
     await File.writeFile(file, output)
 
-    return {status: "written", bytes: output.length, file}
+    return {status: WriteStatus.WRITTEN, bytes: output.length, file}
+  }
+}
+
+export class Dependency {
+  #sourceFile = null
+  #source = null
+
+  /**
+   * Sets the file object for this dependency.
+   *
+   * @param {FileObject} file - The file object of this dependency.
+   * @returns {this} This.
+   */
+  setSourceFile(file) {
+    if(!this.#sourceFile)
+      this.#sourceFile = file
+
+    return this
+  }
+
+  /**
+   * Get the file object for this depenency.
+   *
+   * @returns {FileObject} The file object of this dependency.
+   */
+  getSourceFile() {
+    return this.#sourceFile
+  }
+
+  /**
+   * Sets the source object for this dependency.
+   *
+   * @param {object} source - The parsed JSON from the file after loading.
+   * @returns {this} This.
+   */
+  setSource(source) {
+    if(!this.#source)
+      this.#source = source
+
+    return this
+  }
+
+  getSource() {
+    return this.#source
+  }
+
+  /**
+   * Checks if the dependency has a source file.
+   *
+   * @returns {boolean} True if source file is set
+   */
+  hasSourceFile() {
+    return this.#sourceFile !== null
+  }
+
+  /**
+   * Checks if the dependency has parsed source data.
+   *
+   * @returns {boolean} True if source data is available
+   */
+  hasSource() {
+    return this.#source !== null
+  }
+
+  /**
+   * Checks if the dependency is fully initialized.
+   *
+   * @returns {boolean} True if both file and source are set
+   */
+  isComplete() {
+    return this.hasSourceFile() && this.hasSource()
   }
 }

package/src/ThemePool.js

@@ -25,7 +25,7 @@ export default class ThemePool {
    *
    * @returns {Map<string, ThemeToken>} Map of tokens to their children.
    */
-  get getTokens() {
+  getTokens() {
     return this.#tokens
   }
 

package/src/ThemeToken.js

@@ -229,6 +229,7 @@ export default class ThemeToken {
    */
   setParsedColor(parsedColor) {
     this.#parsedColor = parsedColor
+
     return this
   }
 

package/src/Type.js

@@ -60,7 +60,7 @@ export default class TypeSpec {
   /**
    * Executes a provided function once for each type specification.
    *
-   * @param {Function} callback - Function to execute for each spec
+   * @param {function(unknown): void} callback - Function to execute for each spec
    */
   forEach(callback) {
     this.#specs.forEach(callback)
@@ -69,7 +69,7 @@ export default class TypeSpec {
   /**
    * Tests whether all type specifications pass the provided test function.
    *
-   * @param {Function} callback - Function to test each spec
+   * @param {function(unknown): boolean} callback - Function to test each spec
    * @returns {boolean} True if all specs pass the test
    */
   every(callback) {
@@ -79,7 +79,7 @@ export default class TypeSpec {
   /**
    * Tests whether at least one type specification passes the provided test function.
    *
-   * @param {Function} callback - Function to test each spec
+   * @param {function(unknown): boolean} callback - Function to test each spec
    * @returns {boolean} True if at least one spec passes the test
    */
   some(callback) {
@@ -89,7 +89,7 @@ export default class TypeSpec {
   /**
    * Creates a new array with all type specifications that pass the provided test function.
    *
-   * @param {Function} callback - Function to test each spec
+   * @param {function(unknown): boolean} callback - Function to test each spec
    * @returns {Array} New array with filtered specs
    */
   filter(callback) {
@@ -99,7 +99,7 @@ export default class TypeSpec {
   /**
    * Creates a new array populated with the results of calling the provided function on every spec.
    *
-   * @param {Function} callback - Function to call on each spec
+   * @param {function(unknown): unknown} callback - Function to call on each spec
    * @returns {Array} New array with mapped values
    */
   map(callback) {
@@ -109,9 +109,9 @@ export default class TypeSpec {
   /**
    * Executes a reducer function on each spec, resulting in a single output value.
    *
-   * @param {Function} callback - Function to execute on each spec
-   * @param {*} initialValue - Initial value for the accumulator
-   * @returns {*} The final accumulated value
+   * @param {function(unknown, unknown): unknown} callback - Function to execute on each spec
+   * @param {unknown} initialValue - Initial value for the accumulator
+   * @returns {unknown} The final accumulated value
    */
   reduce(callback, initialValue) {
     return this.#specs.reduce(callback, initialValue)
@@ -120,7 +120,7 @@ export default class TypeSpec {
   /**
    * Returns the first type specification that satisfies the provided testing function.
    *
-   * @param {Function} callback - Function to test each spec
+   * @param {function(unknown): boolean} callback - Function to test each spec
    * @returns {object|undefined} The first spec that matches, or undefined
    */
   find(callback) {
@@ -131,7 +131,7 @@ export default class TypeSpec {
    * Tests whether a value matches any of the type specifications.
    * Handles array types, union types, and empty value validation.
    *
-   * @param {*} value - The value to test against the type specifications
+   * @param {unknown} value - The value to test against the type specifications
    * @param {object} options - Validation options
    * @param {boolean} options.allowEmpty - Whether empty values are allowed
    * @returns {boolean} True if the value matches any type specification
@@ -191,6 +191,7 @@ export default class TypeSpec {
 
     this.#specs = parts.map(part => {
       const typeMatches = /(\w+)(\[\])?/.exec(part)
+
       if(!typeMatches || typeMatches.length !== 3)
         throw Sass.new(`Invalid type: ${part}`)
 

package/src/Util.js

@@ -102,7 +102,7 @@ export default class Util {
    * Wrapper around Promise.all for consistency with other utility methods.
    *
    * @param {Promise[]} promises - Array of promises to await
-   * @returns {Promise<any[]>} Results of all promises
+   * @returns {Promise<unknown[]>} Results of all promises
    */
   static async awaitAll(promises) {
     return await Promise.all(promises)
@@ -124,7 +124,7 @@ export default class Util {
    * Wrapper around Promise.race for consistency with other utility methods.
    *
    * @param {Promise[]} promises - Array of promises to race
-   * @returns {Promise<any>} Result of the first settled promise
+   * @returns {Promise<unknown>} Result of the first settled promise
    */
   static async race(promises) {
     return await Promise.race(promises)