@gesslar/sassy 2.0.1 → 3.0.0

package/types/Command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Command.d.ts","sourceRoot":"","sources":["../src/Command.js"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;;GAGG;AACH;IAUE;;;;;OAKG;IACH,kCAHW,eAAe,EAMzB;IAED;;;;OAIG;IACH,UAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAED;;;;;OAKG;IACH,gBAHW,KAAK,GACH,IAAI,CAMhB;IAED;;;;OAIG;IACH,YAFa,KAAK,GAAC,IAAI,CAItB;IAED;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;;;OAIG;IACH,iBAFa,MAAM,GAAC,IAAI,CAIvB;IAED;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;;;OAIG;IACH,iBAFa,MAAM,GAAC,IAAI,CAIvB;IAED;;;;OAIG;IACH,qBAFa,KAAK,CAAC,MAAM,CAAC,CAIzB;IAED;;;;OAIG;IACH,YAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,iBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,iBAFa,OAAO,CAInB;IAED;;;;;OAKG;IACH,YAFa,OAAO,CAInB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAuBzB;IAED;;;;;;;OAOG;IACH,mBALW,MAAM,WACN,KAAK,CAAC,MAAM,CAAC,YACb,OAAO,GACL,OAAO,CAAC,IAAI,CAAC,CAYzB;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,YACN,OAAO,GACL,IAAI,CAOhB;IAED;;;;;;;OAOG;IACH,+BALW,MAAM,OACN,eAAe,GACb,OAAO,CAAC,UAAU,CAAC,CAY/B;;CACF;qCA/OiC,kBAAkB;2BAE5B,kBAAkB;gCADb,kBAAkB"}

package/types/Compiler.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @import {Theme} from "./Theme.js"
+ */
+/**
+ * Main compiler class for processing theme source files.
+ * Handles the complete compilation pipeline from source to VS Code theme output.
+ */
+export default class Compiler {
+    /**
+     * Compiles a theme source file into a VS Code colour theme.
+     * Processes configuration, variables, imports, and theme definitions.
+     *
+     * @param {Theme} theme - The file object containing source data and metadata
+     * @returns {Promise<void>} Resolves when compilation is complete
+     */
+    compile(theme: Theme): Promise<void>;
+    #private;
+}
+//# sourceMappingURL=Compiler.d.ts.map

package/types/Compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Compiler.d.ts","sourceRoot":"","sources":["../src/Compiler.js"],"names":[],"mappings":"AAiBA;;GAEG;AAEH;;;GAGG;AACH;IACE;;;;;;OAMG;IACH,uBAFa,OAAO,CAAC,IAAI,CAAC,CA4GzB;;CA4NF"}

package/types/Evaluator.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Evaluator class for resolving variables and colour tokens in theme objects.
+ * Handles recursive substitution of token references in arrays of objects
+ * with support for colour manipulation functions.
+ */
+export default class Evaluator {
+    /**
+     * Regular expression used to locate variable substitution tokens. Supports:
+     *  - POSIX-ish:    $(variable.path)
+     *  - Legacy:       $variable.path
+     *  - Braced:       ${variable.path}
+     *
+     * Capturing groups allow extraction of the inner path variant irrespective
+     * of wrapping style. The pattern captures (entireMatch, posix, legacy,
+     * braced).
+     *
+     * @type {RegExp}
+     */
+    static sub: RegExp;
+    /**
+     * Regular expression for matching colour / transformation function calls
+     * within token strings, e.g. `darken($(std.accent), 10)`.
+     *
+     * @type {RegExp}
+     */
+    static func: RegExp;
+    /**
+     * Extracts a variable name from a string containing variable syntax.
+     * Supports $(var), $var, and ${var} patterns.
+     *
+     * @param {string} [str] - String that may contain a variable reference
+     * @returns {string|null} The variable name or null if none found
+     */
+    static extractVariableName(str?: string): string | null;
+    /**
+     * Extracts function name and arguments from a string containing function syntax.
+     * Supports functionName(args) patterns.
+     *
+     * @param {string} [str] - String that may contain a function call
+     * @returns {{func:string, args:string}|null} Object with {func, args} or null if none found
+     */
+    static extractFunctionCall(str?: string): {
+        func: string;
+        args: string;
+    } | null;
+    /**
+     * Regular expression for expanding palette alias syntax. The `$` prefix
+     * inside variable references is shorthand for `palette.`:
+     *  - `$$name`    → `$palette.name`
+     *  - `$($name)`  → `$(palette.name)`
+     *  - `${$name}`  → `${palette.name}`
+     *
+     * @type {RegExp}
+     */
+    static paletteAlias: RegExp;
+    /**
+     * Expands palette alias references in a string value.
+     * Converts `$$name`, `$($name)`, and `${$name}` to their
+     * full `palette.` equivalents before variable resolution.
+     *
+     * @param {string} value - The string potentially containing palette aliases
+     * @returns {string} The string with palette aliases expanded
+     */
+    static expandPaletteAliases(value: string): string;
+    get pool(): ThemePool;
+    /**
+     * Resolve variables and theme token entries in two distinct passes to ensure
+     * deterministic scoping and to prevent partially-resolved values from
+     * leaking between stages:
+     *
+     *  1. Variable pass: each variable is resolved only with access to the
+     *     variable set itself (no theme values yet). This ensures variables are
+     *     self-contained building blocks.
+     *  2. Theme pass: theme entries are then resolved against the union of the
+     *     fully-resolved variables plus (progressively) the theme entries. This
+     *     allows theme keys to reference variables and other theme keys.
+     *
+     * Implementation details:
+     *  - The internal lookup map persists for the lifetime of this instance; new
+     *    entries overwrite prior values (last write wins) so previously resolved
+     *    data can seed later evaluations without a rebuild.
+     *  - Input array is mutated in-place (`value` fields change).
+     *  - No return value. Evident by the absence of a return statement.
+     *
+     * @param {Array<{flatPath:string,value:unknown}>} decomposed - Variable entries to resolve.
+     * @example
+     * // Example decomposed input with variables and theme references
+     * const evaluator = new Evaluator();
+     * const decomposed = [
+     *   { flatPath: 'vars.primary', value: '#3366cc' },
+     *   { flatPath: 'theme.colors.background', value: '$(vars.primary)' },
+     *   { flatPath: 'theme.colors.accent', value: 'lighten($(vars.primary), 20)' }
+     * ];
+     * evaluator.evaluate(decomposed);
+     * // After evaluation, values are resolved:
+     * // decomposed[1].value === '#3366cc'
+     * // decomposed[2].value === '#5588dd' (lightened color)
+     */
+    evaluate(decomposed: Array<{
+        flatPath: string;
+        value: unknown;
+    }>): void;
+    #private;
+}
+import ThemePool from "./ThemePool.js";
+//# sourceMappingURL=Evaluator.d.ts.map

package/types/Evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Evaluator.d.ts","sourceRoot":"","sources":["../src/Evaluator.js"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH;IAWE;;;;;;;;;;;OAWG;IACH,YAFU,MAAM,CAEwF;IAExG;;;;;OAKG;IACH,aAFU,MAAM,CAE4C;IAE5D;;;;;;OAMG;IACH,iCAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAMvB;IAED;;;;;;OAMG;IACH,iCAHW,MAAM,GACJ;QAAC,IAAI,EAAC,MAAM,CAAC;QAAC,IAAI,EAAC,MAAM,CAAA;KAAC,GAAC,IAAI,CAW3C;IAOD;;;;;;;;OAQG;IACH,qBAFU,MAAM,CAEkE;IAElF;;;;;;;OAOG;IACH,mCAHW,MAAM,GACJ,MAAM,CAUlB;IA/BD,sBAEC;IA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,qBAdW,KAAK,CAAC;QAAC,QAAQ,EAAC,MAAM,CAAC;QAAA,KAAK,EAAC,OAAO,CAAA;KAAC,CAAC,QAmEhD;;CAuOF;sBAvaqB,gBAAgB"}

package/types/LintCommand.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @import {ThemePool} from "./ThemePool.js"
+ */
+/**
+ * Command handler for linting theme files for potential issues.
+ * Validates tokenColors for duplicate scopes, undefined variables, unused
+ * variables, and precedence issues that could cause unexpected theme
+ * behaviour.
+ */
+export default class LintCommand extends Command {
+    static SECTIONS: {
+        VARS: string;
+        COLORS: string;
+        TOKEN_COLORS: string;
+        SEMANTIC_TOKEN_COLORS: string;
+    };
+    static SEVERITY: {
+        HIGH: string;
+        MEDIUM: string;
+        LOW: string;
+    };
+    static ISSUE_TYPES: {
+        DUPLICATE_SCOPE: string;
+        UNDEFINED_VARIABLE: string;
+        UNUSED_VARIABLE: string;
+        PRECEDENCE_ISSUE: string;
+    };
+    static TEMPLATES: {
+        ENTRY_NAME: (index: any) => string;
+        OBJECT_NAME: (index: any) => string;
+        VARIABLE_PREFIX: string;
+    };
+    /**
+     * Creates a new LintCommand instance.
+     *
+     * @param {object} base - Base configuration containing cwd and packageJson
+     */
+    constructor(base: object);
+    /**
+     * Executes the lint command for a given theme file.
+     * Validates the theme and reports any issues found.
+     *
+     * @param {string} inputArg - Path to the theme file to lint
+     * @param {object} options - Linting options
+     * @returns {Promise<void>} Resolves when linting is complete
+     */
+    execute(inputArg: string, options?: object): Promise<void>;
+    /**
+     * Public method to lint a theme and return structured results for external
+     * consumption.
+     *
+     * Returns categorized lint results for tokenColors, semanticTokenColors, and colors.
+     *
+     * @param {Theme} theme - The compiled theme object
+     * @returns {Promise<object>} Object containing categorized lint results
+     */
+    lint(theme: Theme): Promise<object>;
+    #private;
+}
+import Command from "./Command.js";
+import Theme from "./Theme.js";
+//# sourceMappingURL=LintCommand.d.ts.map

package/types/LintCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LintCommand.d.ts","sourceRoot":"","sources":["../src/LintCommand.js"],"names":[],"mappings":"AAyBA;;GAEG;AAKH;;;;;GAKG;AACH;IAGE;;;;;MAKC;IAGD;;;;MAIC;IAGD;;;;;MAKC;IAGD;;;;MAIC;IACD;;;;OAIG;IACH,kBAFW,MAAM,EAYhB;IAED;;;;;;;OAOG;IACH,kBAJW,MAAM,YACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAczB;IAED;;;;;;;;OAQG;IACH,YAHW,KAAK,GACH,OAAO,CAAC,MAAM,CAAC,CAyC3B;;CAykBF;oBAjtBmB,cAAc;kBAEhB,YAAY"}

package/types/ResolveCommand.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Command handler for resolving theme tokens and variables to their final values.
+ * Provides introspection into the theme resolution process and variable dependencies.
+ */
+export default class ResolveCommand extends Command {
+    /**
+     * Creates a new ResolveCommand instance.
+     *
+     * @param {object} base - Base configuration containing cwd and packageJson
+     */
+    constructor(base: object);
+    /**
+     * Builds the CLI command, adding extra options that are not mutually exclusive.
+     *
+     * @param {object} program - The commander.js program instance
+     * @returns {Promise<this>} Returns this instance for method chaining
+     */
+    buildCli(program: object): Promise<this>;
+    /**
+     * Executes the resolve command for a given theme file and option.
+     * Validates mutual exclusivity of options and delegates to appropriate resolver.
+     *
+     * @param {string} inputArg - Path to the theme file to resolve
+     * @param {object} options - Resolution options (token, etc.)
+     * @returns {Promise<void>} Resolves when resolution is complete
+     */
+    execute(inputArg: string, options?: object): Promise<void>;
+    /**
+     * Resolves a specific color to its final value and displays the resolution trail.
+     * Shows the complete dependency chain for the requested color.
+     *
+     * @param {object} theme - The compiled theme object with pool
+     * @param {string} colorName - The color key to resolve
+     * @returns {void}
+     * @example
+     * // Resolve a color variable from a compiled theme
+     * await resolveCommand.resolveColor(theme, 'colors.primary');
+     * // Output:
+     * // colors.primary:
+     * //   $(vars.accent)
+     * //     → #3366cc
+     * // Resolution: #3366cc
+     */
+    resolveColor(theme: object, colorName: string): void;
+    /**
+     * Resolves a specific tokenColors scope to its final value and displays the resolution trail.
+     * Shows all matching scopes with disambiguation when multiple matches are found.
+     *
+     * @param {object} theme - The compiled theme object with output
+     * @param {string} scopeName - The scope to resolve (e.g., "entity.name.class" or "entity.name.class.1")
+     * @returns {void}
+     */
+    resolveTokenColor(theme: object, scopeName: string): void;
+    /**
+     * Resolves a specific semanticTokenColors scope to its final value.
+     * Uses the same logic as tokenColors since they have identical structure.
+     *
+     * @param {object} theme - The compiled theme object with output
+     * @param {string} scopeName - The scope to resolve (e.g., "keyword" or "keyword.1")
+     * @returns {void}
+     */
+    resolveSemanticTokenColor(theme: object, scopeName: string): void;
+    #private;
+}
+import Command from "./Command.js";
+//# sourceMappingURL=ResolveCommand.d.ts.map

package/types/ResolveCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResolveCommand.d.ts","sourceRoot":"","sources":["../src/ResolveCommand.js"],"names":[],"mappings":"AAWA;;;GAGG;AACH;IAIE;;;;OAIG;IACH,kBAFW,MAAM,EAchB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAOzB;IAED;;;;;;;OAOG;IACH,kBAJW,MAAM,YACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAiDzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,oBAZW,MAAM,aACN,MAAM,GACJ,IAAI,CA2BhB;IAED;;;;;;;OAOG;IACH,yBAJW,MAAM,aACN,MAAM,GACJ,IAAI,CA4ChB;IAuED;;;;;;;OAOG;IACH,iCAJW,MAAM,aACN,MAAM,GACJ,IAAI,CAoBhB;;CAwQF;oBAviBmB,cAAc"}

package/types/Session.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @import {Command} from "./Command.js"
+ * @import {Theme} from "./Theme.js"
+ * @import {FSWatcher} from "chokidar"
+ */
+/**
+ * @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
+ */
+/**
+ * @import {Theme} from "./Theme.js"
+ * @import {Command} from "./Command.js"
+ */
+export default class Session {
+    /**
+     * Creates a new Session instance for managing theme compilation lifecycle.
+     * Sessions provide persistent state across rebuilds, error tracking, and
+     * individual theme management within the build system.
+     *
+     * @param {Command} command - The parent build command instance
+     * @param {Theme} theme - The theme instance to manage
+     * @param {SessionOptions} options - Build configuration options
+     */
+    constructor(command: path, theme: path, options: SessionOptions);
+    get theme(): any;
+    /**
+     * Gets the theme instance managed by this session.
+     *
+     * @returns {Theme} The theme instance
+     */
+    getTheme(): path;
+    /**
+     * Gets the command instance orchestrating this session.
+     *
+     * @returns {Command} The command instance
+     */
+    getCommand(): path;
+    /**
+     * Gets the session options.
+     *
+     * @returns {SessionOptions} The session options
+     */
+    getOptions(): SessionOptions;
+    /**
+     * Gets the build history for this session.
+     *
+     * @returns {Array<BuildRecord>} Array of build records
+     */
+    getHistory(): Array<BuildRecord>;
+    /**
+     * Gets the build statistics for this session.
+     *
+     * @returns {{builds: number, failures: number}} Build statistics
+     */
+    getStats(): {
+        builds: number;
+        failures: number;
+    };
+    /**
+     * Checks if a build is currently in progress.
+     *
+     * @returns {boolean} True if building
+     */
+    isBuilding(): boolean;
+    /**
+     * Checks if watch mode is enabled.
+     *
+     * @returns {boolean} True if watching
+     */
+    isWatching(): boolean;
+    /**
+     * Checks if there's an active file watcher.
+     *
+     * @returns {boolean} True if watcher exists
+     */
+    hasWatcher(): boolean;
+    run(): Promise<void>;
+    /**
+     * Displays a formatted summary of the session's build statistics and
+     * performance. Shows total builds, success/failure counts, success rate
+     * percentage, and timing information from the most recent build. Used during
+     * session cleanup to provide final statistics to the user.
+     *
+     * @returns {void}
+     */
+    showSummary(): void;
+    #private;
+}
+export type SessionOptions = {
+    /**
+     * - Whether to enable file watching
+     */
+    watch?: boolean;
+    /**
+     * - Whether to show verbose output
+     */
+    nerd?: boolean;
+    /**
+     * - Whether to skip file writes
+     */
+    dryRun?: boolean;
+};
+export type BuildRecord = {
+    /**
+     * - Epoch ms when the build started
+     */
+    timestamp: number;
+    /**
+     * - Time (ms) spent loading theme sources
+     */
+    loadTime: number;
+    /**
+     * - Time (ms) spent compiling the theme
+     */
+    buildTime: number;
+    /**
+     * - Time (ms) spent writing the output file
+     */
+    writeTime: number;
+    /**
+     * - Whether the build completed successfully
+     */
+    success: boolean;
+    /**
+     * - Error message when success is false
+     */
+    error?: string;
+};
+//# sourceMappingURL=Session.d.ts.map

package/types/Session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Session.d.ts","sourceRoot":"","sources":["../src/Session.js"],"names":[],"mappings":"AAKA;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;;;;;;GAQG;AAEH;;;GAGG;AAEH;IAqIE;;;;;;;;OAQG;IACH,qBAJW,IAAO,SACP,IAAK,WACL,cAAc,EAMxB;IAzFD,iBAEC;IAED;;;;OAIG;IACH,YAFa,IAAK,CAIjB;IAED;;;;OAIG;IACH,cAFa,IAAO,CAInB;IAED;;;;OAIG;IACH,cAFa,cAAc,CAI1B;IAED;;;;OAIG;IACH,cAFa,KAAK,CAAC,WAAW,CAAC,CAI9B;IAED;;;;OAIG;IACH,YAFa;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAI9C;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAiBD,qBA0BC;IAwND;;;;;;;OAOG;IACH,eAFa,IAAI,CAkChB;;CAyFF;;;;;YA3hBa,OAAO;;;;WACP,OAAO;;;;aACP,OAAO;;;;;;eAKP,MAAM;;;;cACN,MAAM;;;;eACN,MAAM;;;;eACN,MAAM;;;;aACN,OAAO;;;;YACP,MAAM"}