@gesslar/sassy 0.19.0 → 0.20.2

package/README.md

@@ -107,7 +107,7 @@ npx @gesslar/sassy lint my-theme.yaml
 
 ### Debugging Your Themes
 
-**See what a color variable resolves to:**
+**See what a colour variable resolves to:**
 
 ```bash
 npx @gesslar/sassy resolve --color editor.background my-theme.yaml
@@ -119,7 +119,7 @@ npx @gesslar/sassy resolve --color editor.background my-theme.yaml
 npx @gesslar/sassy resolve --tokenColor keyword.control my-theme.yaml
 ```
 
-**Debug semantic token colors:**
+**Debug semantic token colours:**
 
 ```bash
 npx @gesslar/sassy resolve --semanticTokenColor variable.readonly my-theme.yaml
@@ -147,7 +147,7 @@ npx @gesslar/sassy lint my-theme.yaml
 ```
 
 The lint command performs comprehensive validation of your theme files to catch
-common issues that could cause unexpected behavior or poor maintainability.
+common issues that could cause unexpected behaviour or poor maintainability.
 
 ### Lint Command Checks
 
@@ -423,13 +423,12 @@ vars:
 config:
   name: "My Theme"
   type: dark
-  imports:
-    vars:
-      colors: "./colours.yaml"
+  import:
+    - "./colours.yaml"
 
 vars:
   # Use imported colours
-  accent: $(colors.palette.primary)
+  accent: $(palette.primary)
 
   # Build your design system
   std:
@@ -451,49 +450,48 @@ Sassy supports importing different types of theme components:
 
 ```yaml
 config:
-  imports:
-    # Import variables (merged into your vars section)
-    vars:
-      colors: "./shared/colours.yaml"
-      # Can import multiple files
-      typography: ["./shared/fonts.yaml", "./shared/sizes.yaml"]
-
-    # Import global configuration
-    global:
-      base: "./shared/base-config.yaml"
-
-    # Import VS Code colour definitions
-    colors:
-      ui: "./shared/ui-colours.yaml"
-
-    # Import syntax highlighting rules
-    tokenColors:
-      syntax: "./shared/syntax.yaml"
-
-    # Import semantic token colours
-    semanticTokenColors:
-      semantic: "./shared/semantic.yaml"
+  import:
+    - "./shared/colours.yaml"        # Variables and base config
+    - "./shared/ui-colours.yaml"     # VS Code color definitions  
+    - "./shared/syntax.yaml"         # Syntax highlighting rules
+    - "./shared/semantic.yaml"       # Semantic token colours
 ```
 
-**Import Format Options:**
+**Import Format:**
 
-- **Single file:** `"./path/to/file.yaml"`
-- **Multiple files:** `["./file1.yaml", "./file2.yaml"]`
+Imports are a simple array of file paths. Each file gets merged into your theme:
+
+- **Files:** `["./file1.yaml", "./file2.yaml", "./file3.yaml"]`
 - **File types:** Both `.yaml` and `.json5` are supported
 
 **Merge Order:**
 
-The merge happens in a precise order with each level overriding the previous:
+The merge behaviour depends on the type of theme content:
+
+**Objects (composable):** `colors`, `semanticTokenColors`, `vars`, `config`
+
+1. Imported files (merged in import order)
+2. Your theme file's own definitions (final override)
+
+Later sources override earlier ones using deep object merging.
+
+**Arrays (append-only):** `tokenColors`
+
+1. All imported `tokenColors` (in import order)
+2. Your theme file's `tokenColors` (appended last)
+
+**Why different?** VS Code reads `tokenColors` from top to bottom and stops at the first matching rule. This means:
+
+- **Imported rules** = specific styling (e.g., "make function names blue")
+- **Your main file rules** = fallbacks (e.g., "if nothing else matched, make it white")
+
+**Examples:**
+
+- If an import defines `keyword.control` and your main file also defines `keyword.control`, VS Code will use the imported version because it appears first in the final array.
 
-1. `global` imports (merged first)
-2. `colors` imports
-3. `tokenColors` imports
-4. `semanticTokenColors` imports
-5. Your theme file's own definitions (final override)
+- If your import has a broad rule like `storage` and your main file has a specific rule like `storage.type`, the broad `storage` rule will match first and your specific `storage.type` rule will never be used.
 
-Within each section, if you import multiple files, they merge in array order.
-This layered approach gives you fine-grained control over which definitions
-take precedence.
+> **Tip:** If you're unsure about rule precedence or conflicts, run `npx @gesslar/sassy lint your-theme.yaml` to see exactly what's happening with your `tokenColors`.
 
 ### Watch Mode for Development
 
@@ -574,7 +572,7 @@ different approaches and techniques.
 npx @gesslar/sassy build --nerd my-theme.yaml
 
 # Check what a specific variable resolves to
-npx @gesslar/sassy resolve --token problematic.variable my-theme.yaml
+npx @gesslar/sassy resolve --color problematic.variable my-theme.yaml
 ```
 
 **Variables not resolving:**
@@ -585,9 +583,10 @@ npx @gesslar/sassy resolve --token problematic.variable my-theme.yaml
 
 **Watch mode not updating:**
 
-- Check that files aren't being saved outside the watched directory
-- Try restarting watch mode
-- Verify file permissions
+- Ensure you're editing the original `.yaml` file (not the compiled `.color-theme.json`)
+- Check that imported files are in the same directory tree as your main theme
+- Try restarting watch mode if it seems stuck
+- Verify file permissions allow reading your theme files
 
 ## Getting Help
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/sassy",
-  "version": "0.19.0",
+  "version": "0.20.2",
   "displayName": "Sassy",
   "description": "Make gorgeous themes that speak as boldly as you do.",
   "publisher": "gesslar",

package/src/Compiler.js

@@ -58,16 +58,25 @@ export default class Compiler {
 
       theme.dependencies = importedFiles
 
+      // Handle tokenColors separately - imports first, then main source
+      // (append-only)
+      const mergedTokenColors = [
+        ...(imported.tokenColors ?? []),
+        ...(sourceTheme?.tokenColors ?? [])
+      ]
+
       const merged = Data.mergeObject({},
         imported,
         {
           vars: sourceVars ?? {},
           colors: sourceTheme?.colors ?? {},
-          tokenColors: sourceTheme?.tokenColors ?? [],
           semanticTokenColors: sourceTheme?.semanticTokenColors ?? {},
         }
       )
 
+      // Add tokenColors after merging to avoid mergeObject processing
+      merged.tokenColors = mergedTokenColors
+
       // Shred them up! Kinda. And evaluate the variables in place
       const vars = this.#decomposeObject(merged.vars)
       evaluate(vars)
@@ -173,7 +182,7 @@ export default class Compiler {
 
       imported.vars = Data.mergeObject(imported.vars, vars)
       imported.colors = Data.mergeObject(imported.colors, colors)
-      imported.tokenColors = Data.mergeArray(imported.tokenColors, tokenColors)
+      imported.tokenColors = [...imported.tokenColors, ...tokenColors]
     })
 
     return {imported,importedFiles}

package/src/Data.js

@@ -520,26 +520,4 @@ export default class Data {
     return arr.filter((_, index) => results[index])
   }
 
-  /**
-   * Shallowly merges multiple arrays, deduplicating while preserving order.
-   *
-   * @param {...any[]} sources - Arrays to merge
-   * @returns {Array} A new merged array
-   * @throws {Error} If the sources are not all arrays
-   */
-  static mergeArray(...sources) {
-    if(sources.some(source => !Array.isArray(source)))
-      throw Sass.new("All sources to mergeArray must be arrays.")
-
-    return sources.reduce((acc, curr) => {
-      const accSet = new Set(acc)
-
-      curr.forEach(value => {
-        accSet.has(value) && accSet.delete(value)
-        accSet.add(value)
-      })
-
-      return Array.from(accSet)
-    }, [])
-  }
 }

package/src/LintCommand.js

@@ -20,6 +20,8 @@ import c from "@gesslar/colours"
 
 import Command from "./Command.js"
 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 ThemePool from "./ThemePool.js"
@@ -190,7 +192,7 @@ export default class LintCommand extends Command {
 
     switch(issue.type) {
       case "duplicate-scope": {
-        const rules = issue.occurrences.map(occ => `'${occ.name}'`).join(", ")
+        const rules = issue.occurrences.map(occ => `{loc}'${occ.name}{/}'`).join(", ")
         Term.info(c`${indicator} Scope '{context}${issue.scope}{/}' is duplicated in ${rules}`)
         break
       }
@@ -201,15 +203,15 @@ export default class LintCommand extends Command {
       }
 
       case "unused-variable": {
-        Term.info(c`${indicator} Variable '{context}${issue.variable}{/}' is defined but never used`)
+        Term.info(c`${indicator} Variable '{context}${issue.variable}{/}' is defined in '{loc}${issue.occurence}{/}', but is never used`)
         break
       }
 
       case "precedence-issue": {
         if(issue.broadIndex === issue.specificIndex) {
-          Term.info(c`${indicator} Scope '{context}${issue.broadScope}{/}' makes more specific '{context}${issue.specificScope}' redundant in '${issue.broadRule}{/}'`)
+          Term.info(c`${indicator} Scope '{context}${issue.broadScope}{/}' makes more specific '{context}${issue.specificScope}{/}' redundant in '{loc}${issue.broadRule}{/}'`)
         } else {
-          Term.info(c`${indicator} Scope '{context}${issue.broadScope}{/}' in '${issue.broadRule}' masks more specific '{context}${issue.specificScope}{/}' in '${issue.specificRule}'`)
+          Term.info(c`${indicator} Scope '{context}${issue.broadScope}{/}' in '{loc}${issue.broadRule}{/}' masks more specific '{context}${issue.specificScope}{/}' in '{loc}${issue.specificRule}{/}'`)
         }
 
         break
@@ -314,8 +316,11 @@ export default class LintCommand extends Command {
       return issues
 
     // Get variables defined in the vars section only
-    const definedVars = new Set()
-    this.collectVarsDefinitions(theme.source.vars, definedVars)
+    const definedVars = new Map()
+    const {cwd} = this
+    const mainFile = new FileObject(theme.sourceFile.path)
+    const relativeMainPath = File.relativeOrAbsolutePath(cwd, mainFile)
+    this.collectVarsDefinitions(theme.source.vars, definedVars, "", relativeMainPath)
 
     // Also check dependencies for vars definitions
     if(theme.dependencies) {
@@ -323,7 +328,9 @@ export default class LintCommand extends Command {
         try {
           const depData = theme.cache?.loadCachedDataSync?.(dependency)
           if(depData?.vars) {
-            this.collectVarsDefinitions(depData.vars, definedVars)
+            const depFile = new FileObject(dependency.path)
+            const relativeDependencyPath = File.relativeOrAbsolutePath(cwd, depFile)
+            this.collectVarsDefinitions(depData.vars, definedVars, "", relativeDependencyPath)
           }
         } catch {
           // Ignore cache errors
@@ -368,12 +375,13 @@ export default class LintCommand extends Command {
     }
 
     // Find vars-defined variables that are never used in content sections
-    for(const varName of definedVars) {
+    for(const [varName, filename] of definedVars) {
       if(!usedVars.has(varName)) {
         issues.push({
           type: "unused-variable",
           severity: "low",
-          variable: `$${varName}`
+          variable: `$${varName}`,
+          occurence: filename,
         })
       }
     }
@@ -383,23 +391,24 @@ export default class LintCommand extends Command {
 
   /**
    * Recursively collects variable names defined in the vars section.
-   * Adds found variable names to the definedVars set.
+   * Adds found variable names to the definedVars map.
    *
    * @param {any} vars - The vars data structure to search
-   * @param {Set} definedVars - Set to add found variable names to
+   * @param {Map} definedVars - Map to add found variable names and filenames to
    * @param {string} prefix - Current prefix for nested vars
+   * @param {string} filename - The filename where this variable is defined
    */
-  collectVarsDefinitions(vars, definedVars, prefix = "") {
+  collectVarsDefinitions(vars, definedVars, prefix = "", filename = "") {
     if(!vars || typeof vars !== "object")
       return
 
     for(const [key, value] of Object.entries(vars)) {
       const varName = prefix ? `${prefix}.${key}` : key
-      definedVars.add(varName)
+      definedVars.set(varName, filename)
 
       // If the value is an object, recurse for nested definitions
       if(value && typeof value === "object" && !Array.isArray(value)) {
-        this.collectVarsDefinitions(value, definedVars, varName)
+        this.collectVarsDefinitions(value, definedVars, varName, filename)
       }
     }
   }

package/src/Session.js

@@ -39,6 +39,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 +63,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()
   }
 
   /**
@@ -206,9 +210,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

package/src/cli.js

@@ -80,6 +80,7 @@ void (async function main() {
     c.alias.set("muted-bracket", "{F244}")
     // Lint command
     c.alias.set("context", "{F159}")
+    c.alias.set("loc", "{F148}")
     // Resolve command
     c.alias.set("head", "{F220}")
     c.alias.set("leaf", "{F151}")