@gesslar/sassy 0.19.0

package/src/Type.js

@@ -0,0 +1,206 @@
+/**
+ * @file Type specification and validation utilities.
+ * Provides TypeSpec class for parsing and validating complex type specifications
+ * including arrays, unions, and options.
+ */
+
+import Sass from "./Sass.js"
+import Data from "./Data.js"
+
+/**
+ * Type specification class for parsing and validating complex type definitions.
+ * Supports union types, array types, and validation options.
+ */
+export default class TypeSpec {
+  #specs
+
+  /**
+   * Creates a new TypeSpec instance.
+   *
+   * @param {string} string - The type specification string (e.g., "string|number", "object[]")
+   * @param {object} options - Additional parsing options
+   */
+  constructor(string, options) {
+    this.#specs = []
+    this.#parse(string, options)
+    Object.freeze(this.#specs)
+    this.specs = this.#specs
+    this.length = this.#specs.length
+    this.stringRepresentation = this.toString()
+    Object.freeze(this)
+  }
+
+  /**
+   * Returns a string representation of the type specification.
+   *
+   * @returns {string} The type specification as a string (e.g., "string|number[]")
+   */
+  toString() {
+    return this.#specs
+      .map(spec => {
+        return `${spec.typeName}${spec.array ? "[]" : ""}`
+      })
+      .join("|")
+  }
+
+  /**
+   * Returns a JSON representation of the TypeSpec.
+   *
+   * @returns {object} Object containing specs, length, and string representation
+   */
+  toJSON() {
+    // Serialize as a string representation or as raw data
+    return {
+      specs: this.#specs,
+      length: this.length,
+      stringRepresentation: this.toString(),
+    }
+  }
+
+  /**
+   * Executes a provided function once for each type specification.
+   *
+   * @param {Function} callback - Function to execute for each spec
+   */
+  forEach(callback) {
+    this.#specs.forEach(callback)
+  }
+
+  /**
+   * Tests whether all type specifications pass the provided test function.
+   *
+   * @param {Function} callback - Function to test each spec
+   * @returns {boolean} True if all specs pass the test
+   */
+  every(callback) {
+    return this.#specs.every(callback)
+  }
+
+  /**
+   * Tests whether at least one type specification passes the provided test function.
+   *
+   * @param {Function} callback - Function to test each spec
+   * @returns {boolean} True if at least one spec passes the test
+   */
+  some(callback) {
+    return this.#specs.some(callback)
+  }
+
+  /**
+   * Creates a new array with all type specifications that pass the provided test function.
+   *
+   * @param {Function} callback - Function to test each spec
+   * @returns {Array} New array with filtered specs
+   */
+  filter(callback) {
+    return this.#specs.filter(callback)
+  }
+
+  /**
+   * 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
+   * @returns {Array} New array with mapped values
+   */
+  map(callback) {
+    return this.#specs.map(callback)
+  }
+
+  /**
+   * 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
+   */
+  reduce(callback, initialValue) {
+    return this.#specs.reduce(callback, initialValue)
+  }
+
+  /**
+   * Returns the first type specification that satisfies the provided testing function.
+   *
+   * @param {Function} callback - Function to test each spec
+   * @returns {object|undefined} The first spec that matches, or undefined
+   */
+  find(callback) {
+    return this.#specs.find(callback)
+  }
+
+  /**
+   * 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 {object} options - Validation options
+   * @param {boolean} options.allowEmpty - Whether empty values are allowed
+   * @returns {boolean} True if the value matches any type specification
+   */
+  match(value, options) {
+    const allowEmpty = options?.allowEmpty ?? true
+    const empty = Data.isEmpty(value)
+
+    // If we have a list of types, because the string was validly parsed,
+    // we need to ensure that all of the types that were parsed are valid types
+    // in JavaScript.
+    if(this.length && !this.every(t => Data.isValidType(t.typeName)))
+      return false
+
+    // Now, let's do some checking with the types, respecting the array flag
+    // with the value
+    const valueType = Data.typeOf(value)
+    const isArray = valueType === "array"
+
+    // We need to ensure that we match the type and the consistency of the types
+    // in an array, if it is an array and an array is allowed.
+    const matchingTypeSpec = this.filter(spec => {
+      const {typeName: allowedType, array: allowedArray} = spec
+
+      if(valueType === allowedType && !isArray && !allowedArray)
+        return !allowEmpty ? !empty : true
+
+      if(isArray) {
+        if(allowedType === "array")
+          if(!allowedArray)
+            return true
+
+        if(empty)
+          if(allowEmpty)
+            return true
+
+        return Data.isArrayUniform(value, allowedType)
+      }
+    })
+
+    return matchingTypeSpec.length > 0
+  }
+
+  /**
+   * Parses a type specification string into individual type specs.
+   * Handles union types separated by delimiters and array notation.
+   *
+   * @private
+   * @param {string} string - The type specification string to parse
+   * @param {object} options - Parsing options
+   * @param {string} options.delimiter - The delimiter for union types
+   * @throws {TypeError} If the type specification is invalid
+   */
+  #parse(string, options) {
+    const delimiter = options?.delimiter ?? "|"
+    const parts = string.split(delimiter)
+
+    this.#specs = parts.map(part => {
+      const typeMatches = /(\w+)(\[\])?/.exec(part)
+      if(!typeMatches || typeMatches.length !== 3)
+        throw Sass.new(`Invalid type: ${part}`)
+
+      if(!Data.isValidType(typeMatches[1]))
+        throw Sass.new(`Invalid type: ${typeMatches[1]}`)
+
+      return {
+        typeName: typeMatches[1],
+        array: typeMatches[2] === "[]",
+      }
+    })
+  }
+}

package/src/Util.js

@@ -0,0 +1,132 @@
+import {createHash} from "node:crypto"
+import {performance} from "node:perf_hooks"
+
+/**
+ * Utility class providing common helper functions for string manipulation,
+ * timing, hashing, and option parsing.
+ */
+export default class Util {
+  /**
+   * Capitalizes the first letter of a string.
+   *
+   * @param {string} text - The text to capitalize
+   * @returns {string} Text with first letter capitalized
+   */
+  static capitalize(text) {
+    return `${text.slice(0,1).toUpperCase()}${text.slice(1)}`
+  }
+
+  /**
+   * Measure wall-clock time for an async function.
+   *
+   * @template T
+   * @param {() => Promise<T>} fn - Thunk returning a promise.
+   * @returns {Promise<{result: T, cost: number}>} Object containing result and elapsed ms (number, 1 decimal).
+   */
+  static async time(fn) {
+    const t0 = performance.now()
+    const result = await fn()
+    const cost = Math.round((performance.now() - t0) * 10) / 10
+
+    return {result, cost}
+  }
+
+  /**
+   * Right-align a string inside a fixed width (left pad with spaces).
+   * If the string exceeds width it is returned unchanged.
+   *
+   * @param {string|number} text - Text to align.
+   * @param {number} width - Target field width (default 80).
+   * @returns {string} Padded string.
+   */
+  static rightAlignText(text, width=80) {
+    const work = String(text)
+
+    if(work.length > width)
+      return work
+
+    const diff = width-work.length
+
+    return `${" ".repeat(diff)}${work}`
+  }
+
+  /**
+   * Compute sha256 hash (hex) of the provided string.
+   *
+   * @param {string} s - Input string.
+   * @returns {string} 64-char hexadecimal digest.
+   */
+  static hashOf(s) {
+    return createHash("sha256").update(s).digest("hex")
+  }
+
+  /**
+   * Extracts canonical option names from a Commander-style options object.
+   *
+   * Each key in the input object is a string containing one or more option
+   * forms, separated by commas (e.g. "-w, --watch"). This function splits each
+   * key, trims whitespace, and parses out the long option name (e.g. "watch")
+   * for each entry. If no long option ("--") is present, the short option (e.g.
+   * "v" from "-v") will be included in the result array. If both are present,
+   * the long option is preferred.
+   *
+   * Example:
+   *   generateOptionNames({"-w, --watch": "desc", "-v": "desc"})
+   *   → ["watch", "v"]
+   *
+   * Edge cases:
+   *   - If a key contains only a short option ("-v"), that short name will be
+   *     included in the result.
+   *   - If multiple long options are present, only the first is used.
+   *   - If the option string is malformed, may return undefined for that entry
+   *     (filtered out).
+   *
+   * @param {object} object - Mapping of option strings to descriptions.
+   * @returns {string[]} Array of canonical option names (long preferred, short if no long present).
+   */
+  static generateOptionNames(object) {
+    return Object.keys(object)
+      .map(key => {
+        return key
+          .split(",")
+          .map(o => o.trim())
+          .map(o => o.match(/^(?<sign>--?)(?<option>[\w-]+)/).groups)
+          .reduce((acc, curr) => acc.sign === "--" ? acc : curr, {})
+          ?.option
+      })
+      .filter(Boolean)
+  }
+
+  /**
+   * Asynchronously awaits all promises in parallel.
+   * 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
+   */
+  static async awaitAll(promises) {
+    return await Promise.all(promises)
+  }
+
+  /**
+   * Settles all promises (both fulfilled and rejected) in parallel.
+   * Wrapper around Promise.allSettled for consistency with other utility methods.
+   *
+   * @param {Promise[]} promises - Array of promises to settle
+   * @returns {Promise<Array>} Results of all settled promises with status and value/reason
+   */
+  static async settleAll(promises) {
+    return await Promise.allSettled(promises)
+  }
+
+  /**
+   * Returns the first promise to resolve or reject from an array of promises.
+   * 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
+   */
+  static async race(promises) {
+    return await Promise.race(promises)
+  }
+}

package/src/Valid.js

@@ -0,0 +1,50 @@
+import _assert from "node:assert/strict"
+
+import Sass from "./Sass.js"
+import Data from "./Data.js"
+
+export default class Valid {
+/**
+ * Validates a value against a type
+ *
+ * @param {*} value - The value to validate
+ * @param {string} type - The expected type in the form of "object",
+ *                        "object[]", "object|object[]"
+ * @param {object} [options] - Additional options for validation.
+ */
+  static validType(value, type, options) {
+    Valid.assert(
+      Data.isType(value, type, options),
+      `Invalid type. Expected ${type}, got ${JSON.stringify(value)}`,
+      1,
+    )
+  }
+
+  /**
+   * Asserts a condition
+   *
+   * @param {boolean} condition - The condition to assert
+   * @param {string} message - The message to display if the condition is not
+   *                           met
+   * @param {number} [arg] - The argument to display if the condition is not
+   *                         met (optional)
+   */
+  static assert(condition, message, arg = null) {
+    _assert(
+      Data.isType(condition, "boolean"),
+      `Condition must be a boolean, got ${condition}`,
+    )
+    _assert(
+      Data.isType(message, "string"),
+      `Message must be a string, got ${message}`,
+    )
+    _assert(
+      arg !== null || arg !== undefined && typeof arg === "number",
+      `Arg must be a number, got ${arg}`,
+    )
+
+    if(!condition)
+      throw Sass.new(`${message}${arg ? `: ${arg}` : ""}`)
+  }
+
+}

package/src/cli.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+/**
+ * @file Sassy theme compiler CLI.
+ *
+ * Responsibilities:
+ *  - Parse CLI arguments (supports JSON5 / YAML theme entries, globs resolved externally by the shell)
+ *  - Create Theme instances for compilation units
+ *  - Delegate compilation to Theme.build() which internally uses Compiler.compile()
+ *  - Write (or print with --dry-run) the resulting VS Code colour theme JSON
+ *  - Prevent unnecessary writes by hashing previous output
+ *  - (Optional) Watch all participating source + imported files and recompile on change
+ *
+ * Key Concepts:
+ *  Theme: {
+ *    sourceFile: FileObject          // entry theme file
+ *    source: object                  // raw parsed data (must contain `config`)
+ *    output: object                  // final theme JSON object
+ *    dependencies: FileObject[]      // secondary sources discovered during compile
+ *    lookup: object                  // variable lookup data for compilation
+ *    breadcrumbs: Map                // variable resolution tracking
+ *  }
+ *
+ * The Theme class manages its complete lifecycle:
+ *  - load() - loads and parses the source file
+ *  - build() - compiles the theme via Compiler
+ *  - write() - outputs the compiled theme to file or stdout
+ *  - Internal watch mode support with chokidar integration
+ *
+ * NOTE: The --profile flag is currently parsed but not yet producing timing output.
+ * Future enhancement could surface per-phase timings (load, compile, write, etc.).
+ */
+
+import {program} from "commander"
+import process from "node:process"
+import url from "node:url"
+import c from "@gesslar/colours"
+
+import Cache from "./Cache.js"
+import Sass from "./Sass.js"
+import BuildCommand from "./BuildCommand.js"
+import DirectoryObject from "./DirectoryObject.js"
+import FileObject from "./FileObject.js"
+import LintCommand from "./LintCommand.js"
+import ResolveCommand from "./ResolveCommand.js"
+import Term from "./Term.js"
+
+/**
+ * Main application entry point.
+ * Sets up command line interface, validates input files, and handles compilation.
+ * Supports watch mode for automatic recompilation when files change.
+ *
+ * @returns {Promise<void>} Resolves when build process completes or exits on error.
+ */
+
+/*  =========================
+    Main
+    ========================= */
+
+void (async function main() {
+  // we need nerd mode info here so that it's available in 'catch'
+  const sassyOptions = {}
+
+  setupAbortHandlers()
+
+  try {
+    // setup the colour aliases
+    // Term status stuff
+    c.alias.set("success", "{F070}")
+    c.alias.set("success-bracket", "{F076}")
+    c.alias.set("info", "{F038}")
+    c.alias.set("info-bracket", "{F087}")
+    c.alias.set("warn", "{F215}")
+    c.alias.set("warn-bracket", "{F208}")
+    c.alias.set("error", "{F196}")
+    c.alias.set("error-bracket", "{F160}")
+    c.alias.set("modified", "{F127}")
+    c.alias.set("modified-bracket", "{F165}")
+    c.alias.set("muted", "{F240}")
+    c.alias.set("muted-bracket", "{F244}")
+    // Lint command
+    c.alias.set("context", "{F159}")
+    // Resolve command
+    c.alias.set("head", "{F220}")
+    c.alias.set("leaf", "{F151}")
+    c.alias.set("func", "{F111}")
+    c.alias.set("parens", "{F098}")
+    c.alias.set("line", "{F142}")
+    c.alias.set("hex", "{F140}")
+    c.alias.set("hash", "{F147}{<B}")
+    c.alias.set("hexAlpha", "{F127}{<I}")
+    c.alias.set("arrow", "{F033}")
+
+    const cache = new Cache()
+    const cr = new DirectoryObject(url.fileURLToPath(new url.URL("..", import.meta.url)))
+    const cwd = new DirectoryObject(process.cwd())
+    const packageJson = new FileObject("package.json", cr)
+    const pkgJsonResult = await cache.loadCachedData(packageJson)
+    const pkgJson = pkgJsonResult
+
+    // These are available to all subcommands in addition to whatever they
+    // provide.
+    const alwaysAvailable = {
+      "nerd": ["--nerd", "enable stack tracing for debug purposes when errors are thrown"]
+    }
+
+    program
+      .name(pkgJson.name)
+      .description(pkgJson.description)
+      .version(pkgJson.version)
+
+    // Add the build subcommand
+    const buildCommand = new BuildCommand({cwd, packageJson: pkgJson})
+    buildCommand.cache = cache
+
+    void(await buildCommand.buildCli(program))
+      .addCliOptions(alwaysAvailable, false)
+
+    // Add the resolve subcommand
+    const resolveCommand = new ResolveCommand({cwd, packageJson: pkgJson})
+    resolveCommand.cache = cache
+
+    void(await resolveCommand.buildCli(program))
+      .addCliOptions(alwaysAvailable, false)
+
+    // Add the lint subcommand
+    const lintCommand = new LintCommand({cwd, packageJson: pkgJson})
+    lintCommand.cache = cache
+
+    void(await lintCommand.buildCli(program))
+      .addCliOptions(alwaysAvailable, false)
+
+    // Let'er rip, bitches! VROOM VROOM, motherfucker!!
+    await program.parseAsync()
+
+  } catch(error) {
+    Sass.new("Starting Sassy.", error)
+      .report(sassyOptions.nerd || true)
+
+    process.exit(1)
+  }
+
+  /**
+   * Creates handlers for various reasons that the application may crash.
+   */
+  function setupAbortHandlers() {
+    void["SIGINT", "SIGTERM", "SIGHUP"].forEach(signal => {
+      process.on(signal, async() => {
+        Term.log(`Received ${signal}, performing graceful shutdown...`)
+        await Term.resetTerminal()
+        process.exit(0)
+      })
+    })
+  }
+})()