@gesslar/sassy 0.20.0 → 0.21.0

package/src/ResolveCommand.js

@@ -10,7 +10,6 @@ import Theme from "./Theme.js"
 import Util from "./Util.js"
 import Data from "./Data.js"
 
-
 // ansiColors.enabled = colorSupport.hasBasic
 
 /**
@@ -26,12 +25,12 @@ export default class ResolveCommand extends Command {
   constructor(base) {
     super(base)
 
-    this.cliCommand = "resolve <file>"
-    this.cliOptions = {
+    this.setCliCommand("resolve <file>")
+    this.setCliOptions({
       "color": ["-c, --color <key>", "resolve a color key to its final evaluated value"],
       "tokenColor": ["-t, --tokenColor <scope>", "resolve a tokenColors scope to its final evaluated value"],
       "semanticTokenColor": ["-s, --semanticTokenColor <scope>", "resolve a semanticTokenColors scope to its final evaluated value"],
-    }
+    })
   }
 
   /**
@@ -43,22 +42,23 @@ export default class ResolveCommand extends Command {
    * @returns {Promise<void>} Resolves when resolution is complete
    */
   async execute(inputArg, options={}) {
+    const cliOptionNames = this.getCliOptionNames()
     const intersection =
-      Data.arrayIntersection(this.cliOptionNames, Object.keys(options))
+      Data.arrayIntersection(cliOptionNames, Object.keys(options))
 
     if(intersection.length > 1)
       throw Sass.new(
-        `The options ${this.cliOptionNames.join(", ")} are ` +
+        `The options ${cliOptionNames.join(", ")} are ` +
         `mutually exclusive and may only have one expressed in the request.`
       )
 
-    const {cwd} = this
+    const cwd = this.getCwd()
     const optionName = Object.keys(options??{})
-      .find(o => this.cliOptionNames.includes(o))
+      .find(o => cliOptionNames.includes(o))
 
     if(!optionName) {
       throw Sass.new(
-        `No valid option provided. Please specify one of: ${this.cliOptionNames.join(", ")}.`
+        `No valid option provided. Please specify one of: ${cliOptionNames.join(", ")}.`
       )
     }
 
@@ -71,7 +71,8 @@ export default class ResolveCommand extends Command {
 
     const fileObject = await this.resolveThemeFileName(inputArg, cwd)
     const theme = new Theme(fileObject, cwd, options)
-    theme.cache = this.cache
+
+    theme.setCache(this.getCache())
 
     await theme.load()
     await theme.build()
@@ -88,11 +89,12 @@ export default class ResolveCommand extends Command {
    * @returns {void}
    */
   async resolveColor(theme, colorName) {
-    const pool = theme.pool
+    const pool = theme.getPool()
+
     if(!pool || !pool.has(colorName))
       return Term.info(`'${colorName}' not found.`)
 
-    const tokens = pool.getTokens
+    const tokens = pool.getTokens()
     const token = tokens.get(colorName)
     const trail = token.getTrail()
     const fullTrail = this.#buildCompleteTrail(token, trail)
@@ -114,7 +116,7 @@ export default class ResolveCommand extends Command {
    * @returns {void}
    */
   async resolveTokenColor(theme, scopeName) {
-    const tokenColors = theme.output?.tokenColors || []
+    const tokenColors = theme.getOutput()?.tokenColors || []
 
     // Check if this is a disambiguated scope (ends with .1, .2, etc.)
     const disambiguatedMatch = scopeName.match(/^(.+)\.(\d+)$/)
@@ -127,7 +129,9 @@ export default class ResolveCommand extends Command {
 
       if(index >= 0 && index < matches.length) {
         const match = matches[index]
+
         await this.#resolveScopeMatch(theme, match, `${baseScope}.${indexStr}`)
+
         return
       } else {
         return Term.info(`'${scopeName}' not found. Available: ${baseScope}.1 through ${baseScope}.${matches.length}`)
@@ -149,6 +153,7 @@ export default class ResolveCommand extends Command {
       Term.info(`Multiple entries found for '${scopeName}', please try again with the specific query:\n`)
       matches.forEach((match, index) => {
         const name = match.name || `Entry ${index + 1}`
+
         Term.info(`${name}: ${scopeName}.${index + 1}`)
       })
     }
@@ -161,24 +166,26 @@ export default class ResolveCommand extends Command {
 
       // Handle comma-separated scopes
       const scopes = entry.scope.split(",").map(s => s.trim())
+
       return scopes.includes(targetScope)
     })
   }
 
   async #resolveScopeMatch(theme, match, displayName) {
-    const pool = theme.pool
+    const pool = theme.getPool()
     const settings = match.settings || {}
     const name = match.name || "Unnamed"
 
     // Look for the foreground property specifically
     const foreground = settings.foreground
+
     if(!foreground) {
       return Term.info(`${displayName} (${name})\n\n(no foreground property)`)
     }
 
     // First, try to find the token by looking for variables that resolve to this value
     // but prioritize source variable names over computed results
-    const tokens = pool ? pool.getTokens : new Map()
+    const tokens = pool ? pool.getTokens() : new Map()
     let bestToken = null
 
     // First try to find a scope.* token that matches
@@ -205,16 +212,18 @@ export default class ResolveCommand extends Command {
       }
     }
 
-    if(!bestToken) {
-      return Term.info(`${displayName} (${name})\n\n(resolved to static value: ${foreground})`)
-    }
+    if(!bestToken)
+      return Term.info(
+        `${displayName} (${name})\n\n(resolved to static value: ${foreground})`
+      )
 
     const trail = bestToken.getTrail()
     const fullTrail = this.#buildCompleteTrail(bestToken, trail)
     const finalValue = bestToken.getValue()
     const [formattedFinalValue] = this.#formatLeaf(finalValue)
-
-    const output = c`{head}${displayName}{/} {hex}${(`${name}`)}{/}\n${this.#formatOutput(fullTrail)}\n\n{head}${"Resolution:"}{/} ${formattedFinalValue}`
+    const output = c`{head}${displayName}{/} {hex}${(`${name}`)}{/}\n`+
+                    `${this.#formatOutput(fullTrail)}\n\n{head}`+
+                    `${"Resolution:"}{/} ${formattedFinalValue}`
 
     Term.info(output)
   }
@@ -230,18 +239,19 @@ export default class ResolveCommand extends Command {
   async resolveSemanticTokenColor(theme, scopeName) {
     // semanticTokenColors has the same structure as tokenColors, so we can reuse the logic
     // but we need to look at the semanticTokenColors array instead
-    const originalTokenColors = theme.output?.tokenColors
+    const originalTokenColors = theme.getOutput()?.tokenColors
 
     // Temporarily replace tokenColors with semanticTokenColors for resolution
-    if(theme.output?.semanticTokenColors) {
-      theme.output.tokenColors = theme.output.semanticTokenColors
+    const themeOutput = theme.getOutput()
+    if(themeOutput?.semanticTokenColors) {
+      themeOutput.tokenColors = themeOutput.semanticTokenColors
     }
 
     await this.resolveTokenColor(theme, scopeName)
 
     // Restore original tokenColors
-    if(originalTokenColors) {
-      theme.output.tokenColors = originalTokenColors
+    if(originalTokenColors && themeOutput) {
+      themeOutput.tokenColors = originalTokenColors
     }
   }
 
@@ -251,6 +261,7 @@ export default class ResolveCommand extends Command {
 
     // Add the root token's original expression
     const rootRaw = rootToken.getRawValue()
+
     if(rootRaw !== rootToken.getName()) {
       steps.push({
         value: rootRaw,
@@ -265,6 +276,7 @@ export default class ResolveCommand extends Command {
         return
 
       const id = `${token.getName()}-${token.getRawValue()}`
+
       if(seen.has(id))
         return
 
@@ -290,7 +302,8 @@ export default class ResolveCommand extends Command {
         const depFinal = dependency.getValue()
 
         // Add dependency's expression if it's a function call
-        if(depRaw !== dependency.getName() && !steps.some(s => s.value === depRaw)) {
+        if(depRaw !== dependency.getName() &&
+           !steps.some(s => s.value === depRaw)) {
           steps.push({
             value: depRaw,
             type: "expression",
@@ -300,6 +313,7 @@ export default class ResolveCommand extends Command {
 
         // Process dependency's trail
         const depTrail = dependency.getTrail()
+
         if(depTrail && depTrail.length > 0) {
           depTrail.forEach(depToken => processToken(depToken, level + 1))
         }
@@ -372,10 +386,12 @@ export default class ResolveCommand extends Command {
         // Hex results are indented one extra level with just spaces and arrow
         const prefix = "   ".repeat(depth + 1)
         const arrow = c`{arrow}→{/} `
+
         out.push(`${prefix}${arrow}${line}`)
       } else {
         // Everything else just gets clean indentation
         const prefix = "   ".repeat(depth)
+
         out.push(`${prefix}${line}`)
       }
     })
@@ -411,17 +427,18 @@ export default class ResolveCommand extends Command {
 
     if(this.#func.test(value)) {
       const {func,args} = this.#func.exec(value).groups
+
       return [
         c`{func}${func}{/}{parens}${"("}{/}{leaf}${args}{/}{parens}${")"}{/}`,
         "function"
       ]
     }
 
-
     if(this.#sub.test(value)) {
       const {parens,none,braces} = Evaluator.sub.exec(value)?.groups || {}
       const style = (braces && ["{","}"]) || (parens && ["(",")"]) || (none && ["",""])
       const varValue = braces || parens || none || value
+
       return [
         c`{func}{/}{parens}${style[0]}{/}{leaf}${varValue}{/}{parens}${style[1]}{/}`,
         "variable"

package/src/Sass.js

@@ -24,7 +24,7 @@ export default class Sass extends Error {
    * Creates a new Sass instance.
    *
    * @param {string} message - The error message
-   * @param {...any} arg - Additional arguments passed to parent Error constructor
+   * @param {...unknown} [arg] - Additional arguments passed to parent Error constructor
    */
   constructor(message, ...arg) {
     super(message, ...arg)
@@ -115,6 +115,7 @@ export default class Sass extends Error {
           .split("\n")
           .map(line => {
             const at = line.match(/^\s{4}at\s(?<at>.*)$/)?.groups?.at ?? {}
+
             return at
               ? `* ${at}`
               : line

package/src/Session.js

@@ -7,19 +7,156 @@ import Term from "./Term.js"
 import Theme from "./Theme.js"
 import Util from "./Util.js"
 
+/**
+ * @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 {
+  /**
+   * The theme instance managed by this session.
+   *
+   * @type {Theme|null}
+   * @private
+   */
   #theme = null
+
+  /**
+   * The parent command orchestrating this session.
+   *
+   * @type {Command|null}
+   * @private
+   */
   #command = null
+
+  /**
+   * Build configuration options for this session.
+   *
+   * @type {SessionOptions|null}
+   * @private
+   */
   #options = null
+
+  /**
+   * Active file system watcher for theme dependencies.
+   *
+   * @type {import("chokidar").FSWatcher|null}
+   * @private
+   */
   #watcher = null
+
+  /**
+   * Historical records of builds executed during this session.
+   *
+   * @type {Array<BuildRecord>}
+   * @private
+   */
   #history = []
+
+  /**
+   * Cumulative build statistics for this session.
+   *
+   * @type {{builds: number, failures: number}}
+   * @private
+   */
   #stats = Object.seal({builds: 0, failures: 0})
+
+  /**
+   * Flag indicating whether a build is currently in progress.
+   *
+   * @type {boolean}
+   * @private
+   */
   #building = false
 
   get theme() {
     return this.#theme
   }
 
+  /**
+   * Gets the theme instance managed by this session.
+   *
+   * @returns {Theme} The theme instance
+   */
+  getTheme() {
+    return this.#theme
+  }
+
+  /**
+   * Gets the command instance orchestrating this session.
+   *
+   * @returns {Command} The command instance
+   */
+  getCommand() {
+    return this.#command
+  }
+
+  /**
+   * Gets the session options.
+   *
+   * @returns {SessionOptions} The session options
+   */
+  getOptions() {
+    return this.#options
+  }
+
+  /**
+   * Gets the build history for this session.
+   *
+   * @returns {Array<BuildRecord>} Array of build records
+   */
+  getHistory() {
+    return this.#history
+  }
+
+  /**
+   * Gets the build statistics for this session.
+   *
+   * @returns {{builds: number, failures: number}} Build statistics
+   */
+  getStats() {
+    return this.#stats
+  }
+
+  /**
+   * Checks if a build is currently in progress.
+   *
+   * @returns {boolean} True if building
+   */
+  isBuilding() {
+    return this.#building
+  }
+
+  /**
+   * Checks if watch mode is enabled.
+   *
+   * @returns {boolean} True if watching
+   */
+  isWatching() {
+    return this.#options?.watch === true
+  }
+
+  /**
+   * Checks if there's an active file watcher.
+   *
+   * @returns {boolean} True if watcher exists
+   */
+  hasWatcher() {
+    return this.#watcher !== null
+  }
+
   /**
    * Creates a new Session instance for managing theme compilation lifecycle.
    * Sessions provide persistent state across rebuilds, error tracking, and
@@ -27,10 +164,7 @@ export default class Session {
    *
    * @param {Command} command - The parent build command instance
    * @param {Theme} theme - The theme instance to manage
-   * @param {object} options - Build configuration options
-   * @param {boolean} [options.watch] - Whether to enable file watching
-   * @param {boolean} [options.nerd] - Whether to show verbose output
-   * @param {boolean} [options.dryRun] - Whether to skip file writes
+   * @param {SessionOptions} options - Build configuration options
    */
   constructor(command, theme, options) {
     this.#command = command
@@ -39,6 +173,15 @@ export default class Session {
   }
 
   async run() {
+
+    this.#building = true
+    await this.#command.asyncEmit("building")
+    this.#command.asyncEmit("recordBuildStart", this.#theme)
+    await this.#buildPipeline()
+
+    // This must come after, or you will fuck up the watching!
+    // Themes won't have their dependencies yet unless you build them
+    // at least once. - Samwise Gamgee
     if(this.#options.watch) {
       this.#command.emitter.on("closeSession", async() =>
         await this.#handleCloseSession())
@@ -54,11 +197,6 @@ export default class Session {
 
       await this.#resetWatcher()
     }
-
-    this.#building = true
-    await this.#command.asyncEmit("building")
-    this.#command.asyncEmit("recordBuildStart", this.#theme)
-    await this.#buildPipeline()
   }
 
   /**
@@ -84,11 +222,12 @@ export default class Session {
        */
 
       loadCost = (await Util.time(() => this.#theme.load())).cost
-      const bytes = await File.fileSize(this.#theme.sourceFile)
+      const bytes = await File.fileSize(this.#theme.getSourceFile())
+
       Term.status([
         ["success", Util.rightAlignText(`${loadCost.toLocaleString()}ms`, 10), ["[","]"]],
-        `${this.#theme.name} loaded`,
-        ["info", `${bytes} bytes`, ["[","]"]]
+        `${this.#theme.getName()} loaded`,
+        ["info", `${bytes.toLocaleString()} bytes`, ["[","]"]]
       ], this.#options)
       /**
        * ****************************************************************
@@ -97,30 +236,48 @@ export default class Session {
        */
 
       buildCost = (await Util.time(() => this.#theme.build())).cost
-
-      const compileResult =
-        await Promise.allSettled(this.#theme.dependencies.map(async dep => {
-
-          return await (async fileObject => {
-            const fileName = File.relativeOrAbsolutePath(this.#command.cwd, fileObject)
-            const fileSize = await File.fileSize(fileObject)
-            return [fileName, fileSize]
-          })(dep)
-
+      const dependencyFiles = Array
+        .from(this.#theme.getDependencies())
+        .map(d => d.getSourceFile())
+        .filter(f => f != null) // Filter out any null/undefined files
+
+      const compileResult = await Promise
+        .allSettled(dependencyFiles.map(async fileObject => {
+          if(!fileObject) {
+            throw new Error("Invalid dependency file object")
+          }
+
+          const fileName = File.relativeOrAbsolutePath(
+            this.#command.getCwd(), fileObject
+          )
+          const fileSize = await File.fileSize(fileObject)
+
+          return [fileName, fileSize]
         }))
 
       const rejected = compileResult.filter(result => result.status === "rejected")
+
       if(rejected.length > 0) {
         rejected.forEach(reject => Term.error(reject.reason))
         throw new Error("Compilation failed")
       }
 
-      const dependencies = compileResult.slice(1).map(dep => dep.value)
-      const totalBytes = compileResult.reduce((acc,curr) => acc + curr.value[1], 0)
+      const dependencies = compileResult
+        .slice(1)
+        .map(dep => dep?.value)
+        .filter(Boolean)
+
+      const totalBytes = compileResult.reduce(
+        (acc,curr) => acc + (curr?.value[1] ?? 0), 0
+      )
 
       Term.status([
-        ["success", Util.rightAlignText(`${buildCost.toLocaleString()}ms`, 10), ["[","]"]],
-        `${this.#theme.name} compiled`,
+        [
+          "success",
+          Util.rightAlignText(`${buildCost.toLocaleString()}ms`, 10),
+          ["[","]"]
+        ],
+        `${this.#theme.getName()} compiled`,
         ["success", `${compileResult[0].value[1].toLocaleString()} bytes`, ["[","]"]],
         ["info", `${totalBytes.toLocaleString()} total bytes`, ["(",")"]],
       ], this.#options)
@@ -146,19 +303,25 @@ export default class Session {
        */
 
       const writeResult = await Util.time(() => this.#theme.write(forceWrite))
+
       writeCost = writeResult.cost
-      const result = writeResult.result
       const {
         status: writeStatus,
         file: outputFile,
         bytes: writeBytes
-      } = result
-      const outputFilename = File.relativeOrAbsolutePath(this.#command.cwd, outputFile)
+      } = writeResult.result
+      const outputFilename = File.relativeOrAbsolutePath(
+        this.#command.getCwd(), outputFile
+      )
       const status = [
-        ["success", Util.rightAlignText(`${writeCost.toLocaleString()}ms`, 10), ["[","]"]],
+        [
+          "success",
+          Util.rightAlignText(`${writeCost.toLocaleString()}ms`, 10),
+          ["[","]"]
+        ],
       ]
 
-      if(writeStatus === "written") {
+      if(writeStatus.description === "written") {
         status.push(
           `${outputFilename} written`,
           ["success", `${writeBytes.toLocaleString()} bytes`, ["[","]"]]
@@ -166,7 +329,7 @@ export default class Session {
       } else {
         status.push(
           `${outputFilename}`,
-          ["warn", writeStatus.toLocaleUpperCase(), ["[","]"]]
+          ["warn", writeStatus.description.toLocaleUpperCase(), ["[","]"]]
         )
       }
 
@@ -194,8 +357,7 @@ export default class Session {
         error: error.message
       })
 
-      if(error instanceof Sass)
-        error.report(this.#options.nerd)
+      Sass.new("Build process failed.", error).report(this.#options.nerd)
     } finally {
       this.#building = false
       this.#command.asyncEmit("finishedBuilding")
@@ -206,9 +368,10 @@ export default class Session {
    * Handles a file change event and triggers a rebuild for the theme.
    *
    * @param {string} changed - Path to the changed file
+   * @param {object} _stats - OS-level file stat information
    * @returns {Promise<void>}
    */
-  async #handleFileChange(changed) {
+  async #handleFileChange(changed, _stats) {
     try {
       if(this.#building)
         return
@@ -216,16 +379,20 @@ export default class Session {
       this.#building = true
       this.#command.asyncEmit("building")
 
-      const changedFile = this.#theme.dependencies.find(dep => dep.path === changed)
+      const changedFile = Array.from(this.#theme.getDependencies()).find(
+        dep => dep.getSourceFile().path === changed
+      )?.getSourceFile()
 
       if(!changedFile)
         return
 
-      const fileName = File.relativeOrAbsolutePath(this.#command.cwd, changedFile)
+      const fileName = File.relativeOrAbsolutePath(
+        this.#command.getCwd(), changedFile
+      )
 
       const message = [
         ["info", "REBUILDING", ["[","]"]],
-        this.#theme.name,
+        this.#theme.getName(),
       ]
 
       if(this.#options.nerd)
@@ -257,7 +424,7 @@ export default class Session {
 
     Term.status([
       [builds > 0 ? "success" : "error", "SESSION SUMMARY"],
-      [builds > 0 ? "info" : "error", this.#theme.name, ["[", "]"]]
+      [builds > 0 ? "info" : "error", this.#theme.getName(), ["[", "]"]]
     ], this.#options)
 
     Term.status([
@@ -272,7 +439,8 @@ export default class Session {
 
     if(this.#history.length > 0) {
       const lastBuild = this.#history[this.#history.length - 1]
-      const totalTime = lastBuild.loadTime + lastBuild.buildTime + lastBuild.writeTime
+      const totalTime = lastBuild.loadTime +
+        lastBuild.buildTime + lastBuild.writeTime
 
       Term.status([
         [builds > 0 ? "info" : "muted", "Last Build", ["[", "]"]],
@@ -313,10 +481,11 @@ export default class Session {
     if(this.#watcher)
       await this.#watcher.close()
 
-    const dependencies = this.#theme.dependencies.map(d => d.path)
+    const dependencies = Array.from(this.#theme.getDependencies()).map(d => d.getSourceFile().path)
+
     this.#watcher = chokidar.watch(dependencies, {
       // Prevent watching own output files
-      ignored: [this.#theme.outputFileName],
+      ignored: [this.#theme.getOutputFileName()],
       // Add some stability options
       awaitWriteFinish: {
         stabilityThreshold: 100,

package/src/Term.js

@@ -9,7 +9,7 @@ export default class Term {
   /**
    * Log an informational message.
    *
-   * @param {...any} arg - Values to log.
+   * @param {...unknown} [arg] - Values to log.
    */
   static log(...arg) {
     console.log(...arg)
@@ -18,7 +18,7 @@ export default class Term {
   /**
    * Log an informational message.
    *
-   * @param {...any} arg - Values to log.
+   * @param {...unknown} [arg] - Values to log.
    */
   static info(...arg) {
     console.info(...arg)
@@ -27,16 +27,16 @@ export default class Term {
   /**
    * Log a warning message.
    *
-   * @param {any} msg - Warning text / object.
+   * @param {...unknown} [arg] - Warning text / object.
    */
-  static warn(...msg) {
-    console.warn(...msg)
+  static warn(...arg) {
+    console.warn(...arg)
   }
 
   /**
    * Log an error message (plus optional details).
    *
-   * @param {...any} arg - Values to log.
+   * @param {...unknown} [arg] - Values to log.
    */
   static error(...arg) {
     console.error(...arg)
@@ -45,7 +45,7 @@ export default class Term {
   /**
    * Log a debug message (no-op unless console.debug provided/visible by env).
    *
-   * @param {...any} arg - Values to log.
+   * @param {...unknown} [arg] - Values to log.
    */
   static debug(...arg) {
     console.debug(...arg)