@gesslar/sassy 0.19.0

package/src/Theme.js

@@ -0,0 +1,289 @@
+/**
+ * @file Theme.js
+ *
+ * Defines the Theme class, representing a single theme compilation unit.
+ * Handles the complete lifecycle: loading source files, managing dependencies,
+ * compiling via Compiler, writing output, and supporting watch mode for live development.
+ * Maintains state for output, variable lookup, and resolution tracking.
+ *
+ * Responsibilities:
+ * - Load and validate theme source files
+ * - Track dependencies and variable resolution
+ * - Compile theme data into VS Code-compatible output
+ * - Write output files, supporting dry-run and hash-based skip
+ * - Support watch mode for live theme development
+ */
+import Sass from "./Sass.js"
+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"
+
+/**
+ * Theme class: manages the lifecycle of a theme compilation unit.
+ * See file-level docstring for responsibilities.
+ */
+export default class Theme {
+  #sourceFile = null
+  #source = null
+  #options = null
+  #dependencies = []
+  #lookup = null
+  #pool = null
+  #cache = null
+  #name = null
+
+  // Write-related properties
+  #output = null
+  #outputJson = null
+  #outputFileName = null
+  #outputHash = null
+
+  #cwd = null
+
+  /**
+   * 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, cwd, options) {
+    this.#sourceFile = themeFile
+    this.#name = themeFile.module
+    this.#outputFileName = `${this.#name}.color-theme.json`
+    this.#options = options
+    this.#cwd = cwd
+  }
+
+  /**
+   * Resets the theme's compilation state, clearing output and lookup data.
+   * Used when recompiling in watch mode or clearing previous state.
+   */
+  reset() {
+    this.#output = null
+    this.#outputJson = null
+    this.#outputHash = null
+    this.#lookup = null
+    this.#pool = null
+  }
+
+  get cwd() {
+    return this.#cwd
+  }
+
+  get options() {
+    return this.#options
+  }
+
+  set cache(cache) {
+    if(!this.cache)
+      this.#cache=cache
+  }
+
+  get cache() {
+    return this.#cache
+  }
+
+  get name() {
+    return this.#name
+  }
+
+  /**
+   * Gets the source file object.
+   *
+   * @returns {FileObject} The source theme file
+   */
+  get sourceFile() {
+    return this.#sourceFile
+  }
+
+  /**
+   * Gets the compiled theme output object.
+   *
+   * @returns {object|null} The compiled theme output
+   */
+  get output() {
+    return this.#output
+  }
+
+  /**
+   * Sets the compiled theme output object and updates derived JSON and hash.
+   *
+   * @param {object} data - The compiled theme output object
+   */
+  set output(data) {
+    this.#output = data
+    this.#outputJson = JSON.stringify(data, null, 2) + "\n"
+    this.#outputHash = Util.hashOf(this.#outputJson)
+  }
+
+  /**
+   * Gets the array of file dependencies.
+   *
+   * @returns {FileObject[]} Array of dependency files
+   */
+  get dependencies() {
+    return this.#dependencies
+  }
+
+  /**
+   * Sets the array of file dependencies.
+   *
+   * @param {FileObject[]} data - Array of dependency files
+   */
+  set dependencies(data) {
+    this.#dependencies = data
+
+    if(!this.#dependencies.includes(this.#sourceFile))
+      this.#dependencies.unshift(this.#sourceFile)
+  }
+
+  /**
+   * Gets the parsed source data from the theme file.
+   *
+   * @returns {object|null} The parsed source data
+   */
+  get source() {
+    return this.#source
+  }
+
+  /**
+   * Gets the variable lookup data for theme compilation.
+   *
+   * @returns {object|null} The lookup data object
+   */
+  get lookup() {
+    return this.#lookup
+  }
+
+  /**
+   * Sets the variable lookup data for theme compilation.
+   *
+   * @param {object} data - The lookup data object
+   */
+  set lookup(data) {
+    this.#lookup = data
+  }
+
+  /**
+   * Gets the pool data for variable resolution tracking or null if one has
+   * not been set.
+   *
+   * @returns {ThemePool|null} The pool for this theme.
+   */
+  get pool() {
+    return this.#pool
+  }
+
+  /**
+   * 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 If there is already a pool.
+   */
+  set pool(pool) {
+    if(this.#pool)
+      throw Sass.new("Cannot override existing pool.")
+
+    this.#pool = pool
+  }
+
+  /**
+   * Method to return true or false if this theme has a pool.
+   *
+   * @returns {boolean} True if a pool has been set, false otherwise.
+   */
+  hasPool() {
+    return this.#pool instanceof ThemePool
+  }
+
+  /**
+   * Loads and parses the theme source file.
+   * Validates that the source contains required configuration.
+   *
+   * @returns {Promise<this>} Returns this instance for method chaining
+   * @throws {Sass} If source file lacks required 'config' property
+   */
+  async load() {
+    const source = await this.#cache.loadCachedData(this.#sourceFile)
+
+    if(!source.config)
+      throw Sass.new(
+        `Source file does not contain 'config' 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)
+
+    return this
+  }
+
+  /**
+   * 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.
+   */
+  async build() {
+    const compiler = new Compiler()
+    await compiler.compile(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
+   */
+  async write(force=false) {
+    const output = this.#outputJson
+    const outputDir = new DirectoryObject(this.#options.outputDir)
+    const file = new FileObject(this.#outputFileName, outputDir)
+
+    if(this.#options.dryRun) {
+      Term.log(this.#outputJson)
+
+      return {status: "dry-run", file}
+    }
+
+    // Skip identical bytes
+    if(!force) {
+      const nextHash = this.#outputHash
+      const lastHash = await file.exists
+        ? Util.hashOf(await File.readFile(file))
+        : "kakadoodoo"
+
+      if(lastHash === nextHash)
+        return {status: "skipped", file}
+    }
+
+    // Real write (timed)
+    if(!await outputDir.exists)
+      await File.assureDirectory(outputDir, {recursive: true})
+
+    await File.writeFile(file, output)
+
+    return {status: "written", bytes: output.length, file}
+  }
+}

package/src/ThemePool.js

@@ -0,0 +1,139 @@
+
+/**
+ * @file ThemePool.js
+ *
+ * Defines the ThemePool class, a collection of ThemeTokens for lookup and dependency tracking.
+ * Manages resolved values, raw resolutions, and token relationships during theme compilation.
+ */
+
+import Sass from "./Sass.js"
+import ThemeToken from "./ThemeToken.js"
+
+/**
+ * ThemePool represents a collection of ThemeTokens serving both as a
+ * lookup of string>ThemeToken and dependencies.
+ *
+ * @class ThemePool
+ */
+export default class ThemePool {
+  #tokens = new Map()
+  #resolved = new Map()
+  #rawResolved = new Map()
+
+  /**
+   * Returns the map of encoded theme token ids to their token object.
+   *
+   * @returns {Map<string, ThemeToken>} Map of tokens to their children.
+   */
+  get getTokens() {
+    return this.#tokens
+  }
+
+  /**
+   * 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) {
+    return this.#resolved.get(name)
+  }
+
+  /**
+   * Sets a resolved value for a token key.
+   *
+   * @param {string} key - The token key.
+   * @param {string} value - The resolved value.
+   */
+  resolve(key, value) {
+    this.#resolved.set(key, value)
+  }
+
+  /**
+   * Sets a raw resolved value for a token key.
+   *
+   * @param {string} key - The token key.
+   * @param {string} value - The raw resolved value.
+   */
+  rawResolve(key, value) {
+    this.#rawResolved.set(key, value)
+  }
+
+  /**
+   * 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) {
+    return this.#resolved.has(name)
+  }
+
+  /**
+   * Checks if a token exists by its name.
+   *
+   * @param {ThemeToken} token - The token to check.
+   * @returns {boolean} True if the token exists.
+   */
+  hasToken(token) {
+    return this.has(token.name)
+  }
+
+  /**
+   * 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) {
+    return this.#tokens.get(token.getValue()) || 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, dependency=null) {
+    if(!(token instanceof ThemeToken))
+      throw Sass.new("Token must be of type ThemeToken.")
+
+    if(!(dependency === null || dependency instanceof ThemeToken))
+      throw Sass.new("Token must be null or of type ThemeToken.")
+
+    this.#tokens.set(token.getName(), token)
+
+    return token
+  }
+
+  /**
+   * Finds a token by its value.
+   *
+   * @param {string} value - The value to search for.
+   * @returns {ThemeToken|undefined} The found token or undefined.
+   */
+  findToken(value) {
+    return [...this.#tokens.entries()].find(arg => arg[0] === value)?.[1]
+  }
+
+  /**
+   * 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, token) {
+
+    do
+
+      if(candidate === token)
+        return true
+
+    while((token = this.reverseLookup(token)))
+
+    return false
+  }
+}

package/src/ThemeToken.js

@@ -0,0 +1,280 @@
+
+/**
+ * @file ThemeToken.js
+ *
+ * Defines the ThemeToken class, representing a single token in a theme tree.
+ * Encapsulates token data, relationships, and provides methods for property
+ * management, pool integration, and serialization during theme compilation.
+ */
+
+import Sass from "./Sass.js"
+import ThemePool from "./ThemePool.js"
+
+/**
+ * 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 {
+  #pool
+
+  #name = null
+  #kind = null
+  #rawValue = null
+  #value = null
+  #dependency = null
+  #parentTokenKey = null
+  #trail = new Array()
+  #parsedColor = null
+
+  /**
+   * Constructs a ThemeToken with a given token name.
+   *
+   * @param {string} name - The token name for this token.
+   */
+  constructor(name) {
+    if(typeof name !== "string")
+      throw Sass.new("Token name must be a bare string.")
+
+    this.setName(name)
+  }
+
+  /**
+   * 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=null, dependency) {
+    if(!(pool instanceof ThemePool))
+      throw Sass.new("Pool must be a ThemePool instance.")
+
+    if(this.#pool)
+      return this
+
+    if(!(dependency == null || dependency instanceof ThemeToken))
+      throw Sass.new("Dependency must be null or of type ThemeToken.")
+
+    this.#pool = pool
+
+    return pool.addToken(this, dependency)
+  }
+
+  /**
+   * Sets the name of this token (only if not already set).
+   *
+   * @param {string} name - The token name.
+   * @returns {ThemeToken} This token instance.
+   */
+  setName(name) {
+    if(!this.#name)
+      this.#name = name
+
+    return this
+  }
+
+  /**
+   * Gets the name of this token.
+   *
+   * @returns {string} The token name.
+   */
+  getName() {
+    return this.#name
+  }
+
+  /**
+   * Sets the kind of this token (only if not already set).
+   *
+   * @param {string} kind - The token kind.
+   * @returns {ThemeToken} This token instance.
+   */
+  setKind(kind) {
+    if(!this.#kind)
+      this.#kind = kind
+
+    return this
+  }
+
+  /**
+   * Gets the kind of this token.
+   *
+   * @returns {string} The token kind.
+   */
+  getKind() {
+    return this.#kind
+  }
+
+  /**
+   * Sets the value of this token.
+   *
+   * @param {string} value - The token value.
+   * @returns {ThemeToken} This token instance.
+   */
+  setValue(value) {
+    this.#value = value
+
+    return this
+  }
+
+  /**
+   * Gets the value of this token.
+   *
+   * @returns {string} The token value.
+   */
+  getValue() {
+    return this.#value
+  }
+
+  /**
+   * 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) {
+    if(!this.#rawValue)
+      this.#rawValue = raw
+
+    return this
+  }
+
+  /**
+   * Gets the raw value of this token.
+   *
+   * @returns {string} The raw token value.
+   */
+  getRawValue() {
+    return this.#rawValue
+  }
+
+  /**
+   * Sets the dependency of this token (only if not already set).
+   *
+   * @param {ThemeToken} dependency - The dependency token.
+   * @returns {ThemeToken} This token instance.
+   */
+  setDependency(dependency) {
+    if(!this.#dependency)
+      this.#dependency = dependency
+
+    return this
+  }
+
+  /**
+   * Gets the dependency of this token.
+   *
+   * @returns {ThemeToken|null} The dependency token or null.
+   */
+  getDependency() {
+    return this.#dependency || null
+  }
+
+  /**
+   * Sets the parent token key.
+   *
+   * @param {string} tokenKey - The parent token key.
+   * @returns {ThemeToken} This token instance.
+   */
+  setParentTokenKey(tokenKey) {
+    this.#parentTokenKey = tokenKey
+
+    return this
+  }
+
+  /**
+   * Gets the parent token key.
+   *
+   * @returns {string|null} The parent token key or null.
+   */
+  getParentTokenKey() {
+    return this.#parentTokenKey || 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) {
+    const current = this.#trail
+
+    trail.forEach(value => {
+      if(!current.includes(value))
+        current.push(value)
+    })
+
+    return this
+  }
+
+  /**
+   * Gets the trail array of this token.
+   *
+   * @returns {Array<ThemeToken>} The trail array.
+   */
+  getTrail() {
+    return this.#trail
+  }
+
+  /**
+   * Sets the parsed color object for this token.
+   *
+   * @param {object} parsedColor - The parsed Culori color object
+   * @returns {ThemeToken} This token instance.
+   */
+  setParsedColor(parsedColor) {
+    this.#parsedColor = parsedColor
+    return this
+  }
+
+  /**
+   * Gets the parsed color object of this token.
+   *
+   * @returns {object|null} The parsed Culori color object or null.
+   */
+  getParsedColor() {
+    return this.#parsedColor
+  }
+
+  /**
+   * 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) {
+    return this.#dependency && this.#dependency.getName() === name
+  }
+
+  /**
+   * Gets the ThemePool associated with this token.
+   *
+   * @returns {ThemePool} The associated pool.
+   */
+  getPool() {
+    return this.#pool
+  }
+
+  /**
+   * Returns a JSON representation of the ThemeToken.
+   *
+   * @returns {object} JSON representation of the ThemeToken
+   */
+  toJSON() {
+    return {
+      name: this.#name,
+      kind: this.#kind,
+      rawValue: this.#rawValue,
+      value: this.#value,
+      dependency: this.#dependency?.toJSON() ?? null,
+      parentTokenKey: this.#parentTokenKey,
+      trail: this.#trail,
+      parsedColor: this.#parsedColor
+    }
+  }
+}