@gesslar/sassy 0.21.1 → 0.21.3

package/src/Sass.js

@@ -1,166 +0,0 @@
-/**
- * @file Sass.js
- *
- * Defines the Sass class, a custom error type for theme compilation
- * errors.
- *
- * Supports error chaining, trace management, and formatted reporting for both
- * user-friendly and verbose (nerd) output.
- *
- * Used throughout the theme engine for structured error handling and
- * debugging.
- */
-
-import Term from "./Term.js"
-
-/**
- * Custom error class for Sassy theme compilation errors.
- * Provides error chaining, trace management, and formatted error reporting.
- */
-export default class Sass extends Error {
-  #trace = []
-
-  /**
-   * Creates a new Sass instance.
-   *
-   * @param {string} message - The error message
-   * @param {...unknown} [arg] - Additional arguments passed to parent Error constructor
-   */
-  constructor(message, ...arg) {
-    super(message, ...arg)
-
-    this.trace = message
-  }
-
-  /**
-   * Gets the error trace array.
-   *
-   * @returns {Array<string>} Array of trace messages
-   */
-  get trace() {
-    return this.#trace
-  }
-
-  /**
-   * Adds a message to the beginning of the trace array.
-   *
-   * @param {string} message - The trace message to add
-   */
-  set trace(message) {
-    this.#trace.unshift(message)
-  }
-
-  /**
-   * Adds a trace message and returns this instance for chaining.
-   *
-   * @param {string} message - The trace message to add
-   * @returns {this} This Sass instance for method chaining
-   */
-  addTrace(message) {
-    if(typeof message !== "string")
-      throw Sass.new(`Sass.addTrace expected string, got ${JSON.stringify(message)}`)
-
-    this.trace = message
-
-    return this
-  }
-
-  /**
-   * Reports the error to the terminal with formatted output.
-   * Optionally includes detailed stack trace information.
-   *
-   * @param {boolean} [nerdMode] - Whether to include detailed stack trace
-   */
-  report(nerdMode=false) {
-    Term.error(
-      `${Term.terminalBracket(["error", "Something Went Wrong"])}\n` +
-      this.trace.join("\n")
-    )
-
-    if(nerdMode) {
-      Term.error(
-        "\n" +
-        `${Term.terminalBracket(["error", "Nerd Vittles"])}\n` +
-        this.#fullBodyMassage(this.stack)
-      )
-
-      this.cause?.stack && Term.error(
-        "\n" +
-        `${Term.terminalBracket(["error", "Rethrown From"])}\n` +
-        this.#fullBodyMassage(this.cause?.stack)
-      )
-    }
-  }
-
-  /**
-   * Formats the stack trace for display, removing the first line and
-   * formatting each line with appropriate indentation.
-   *
-   * Note: Returns formatted stack trace or undefined if no stack available.
-   *
-   * @param {string} stack - The error stack to massage.
-   * @returns {string|undefined} Formatted stack trace or undefined
-   */
-  #fullBodyMassage(stack) {
-    // Remove the first line, it's already been reported
-
-    stack = stack ?? ""
-
-    const {rest} = stack.match(/^.*?\n(?<rest>[\s\S]+)$/m)?.groups ?? {}
-    const lines = []
-
-    if(rest) {
-      lines.push(
-        ...rest
-          .split("\n")
-          .map(line => {
-            const at = line.match(/^\s{4}at\s(?<at>.*)$/)?.groups?.at ?? {}
-
-            return at
-              ? `* ${at}`
-              : line
-          })
-      )
-    }
-
-    return lines.join("\n")
-  }
-
-  /**
-   * Creates an Sass from an existing Error object with additional
-   * trace message.
-   *
-   * @param {Error} error - The original error object
-   * @param {string} message - Additional trace message to add
-   * @returns {Sass} New Sass instance with trace from the original error
-   * @throws {Sass} If the first parameter is not an Error instance
-   */
-  static from(error, message) {
-    if(!(error instanceof Error))
-      throw Sass.new("Sass.from must take an Error object.")
-
-    const oldMessage = error.message
-    const newError = new Sass(oldMessage, {cause: error}).addTrace(message)
-
-    return newError
-  }
-
-  /**
-   * Factory method to create or enhance Sass instances.
-   * If error parameter is provided, enhances existing Sass or wraps
-   * other errors. Otherwise creates a new Sass instance.
-   *
-   * @param {string} message - The error message
-   * @param {Error|Sass} [error] - Optional existing error to wrap or enhance
-   * @returns {Sass} New or enhanced Sass instance
-   */
-  static new(message, error) {
-    if(error) {
-      return error instanceof Sass
-        ? error.addTrace(message)
-        : Sass.from(error, message)
-    } else {
-      return new Sass(message)
-    }
-  }
-}

package/src/Term.js

@@ -1,175 +0,0 @@
-import c from "@gesslar/colours"
-// import colorSupport from "color-support"
-import console from "node:console"
-import process from "node:process"
-
-import Sass from "./Sass.js"
-
-export default class Term {
-  /**
-   * Log an informational message.
-   *
-   * @param {...unknown} [arg] - Values to log.
-   */
-  static log(...arg) {
-    console.log(...arg)
-  }
-
-  /**
-   * Log an informational message.
-   *
-   * @param {...unknown} [arg] - Values to log.
-   */
-  static info(...arg) {
-    console.info(...arg)
-  }
-
-  /**
-   * Log a warning message.
-   *
-   * @param {...unknown} [arg] - Warning text / object.
-   */
-  static warn(...arg) {
-    console.warn(...arg)
-  }
-
-  /**
-   * Log an error message (plus optional details).
-   *
-   * @param {...unknown} [arg] - Values to log.
-   */
-  static error(...arg) {
-    console.error(...arg)
-  }
-
-  /**
-   * Log a debug message (no-op unless console.debug provided/visible by env).
-   *
-   * @param {...unknown} [arg] - Values to log.
-   */
-  static debug(...arg) {
-    console.debug(...arg)
-  }
-
-  /**
-   * Emit a status line to the terminal.
-   *
-   * Accepts either a plain string or an array of message segments (see
-   * `terminalMessage()` for formatting options). If `silent` is true, output
-   * is suppressed.
-   *
-   * This is a convenient shortcut for logging status updates, with optional
-   * formatting and easy suppression.
-   *
-   * @param {string | Array<string | [string, string]>} args - Message or segments.
-   * @param {object} [options] - Behaviour flags.
-   * @param {boolean} options.silent - When true, suppress output.
-   * @returns {void}
-   */
-  static status(args, {silent=false} = {}) {
-    if(silent)
-      return
-
-    return Term.info(Term.terminalMessage(args))
-  }
-
-  /**
-   * Constructs a formatted status line.
-   *
-   * Input forms:
-   *  - string: printed as-is
-   *  - array: each element is either:
-   *    - a plain string (emitted unchanged), or
-   *    - a tuple: [level, text] where `level` maps to an ansiColors alias
-   *        (e.g. success, info, warn, error, modified).
-   *    - a tuple: [level, text, [openBracket,closeBracket]] where `level` maps to an ansiColors alias
-   *        (e.g. success, info, warn, error, modified). These are rendered as
-   *        colourised bracketed segments: [TEXT].
-   *
-   * The function performs a shallow validation: tuple elements must both be
-   * strings; otherwise a TypeError is thrown. Nested arrays beyond depth 1 are
-   * not supported.
-   *
-   * Recursion: array input is normalised into a single string then re-dispatched
-   * through `status` to leverage the string branch (keeps logic DRY).
-   *
-   * @param {string | Array<string, string> | Array<string, string, string>} argList - Message spec.
-   * @returns {void}
-   */
-  static terminalMessage(argList) {
-    if(typeof argList === "string")
-      return argList
-
-    if(Array.isArray(argList)) {
-      const message = argList
-        .map(args => {
-          // Bracketed
-          if(Array.isArray(args))
-
-            if(args.length === 3 && Array.isArray(args[2]))
-              return Term.terminalBracket(args)
-
-            else
-              return Term.terminalBracket([...args])
-
-          // Plain string, no decoration
-          if(typeof args === "string")
-            return args
-        })
-        .join(" ")
-
-      return Term.terminalMessage(message)
-    }
-
-    throw Sass.new("Invalid arguments passed to terminalMessage")
-  }
-
-  /**
-   * Construct a single coloured bracketed segment from a tuple specifying
-   * the style level and the text. The first element ("level") maps to an
-   * `ansiColors` alias (e.g. success, info, warn, error, modified) and is
-   * used both for the inner text colour and to locate its matching
-   * "-bracket" alias for the surrounding square brackets. The second
-   * element is the raw text to display.
-   *
-   * Input validation: every element of `parts` must be a string; otherwise
-   * an `Sass` error is thrown. (Additional elements beyond the first two are
-   * ignored – the method destructures only the first pair.)
-   *
-   * Example:
-   *  terminalBracket(["success", "COMPILED"]) → "[COMPILED]" with coloured
-   *  brackets + inner text (assuming colour support is available in the
-   *  terminal).
-   *
-   * This method does not append trailing spaces; callers are responsible for
-   * joining multiple segments with appropriate separators.
-   *
-   * @param {string[]} parts - Tuple: [level, text]. Additional entries ignored.
-   * @returns {string} Colourised bracketed segment (e.g. "[TEXT]").
-   * @throws {Sass} If any element of `parts` is not a string.
-   */
-  static terminalBracket([level, text, brackets=["",""]]) {
-    if(!(typeof level === "string" && typeof text === "string"))
-      throw Sass.new("Each element must be a string.")
-
-    return "" +
-        c`{${level}-bracket}${brackets[0]}{/}`
-      + c`{${level}}${text}{/}`
-      + c`{${level}-bracket}${brackets[1]}{/}`
-  }
-
-  static async resetTerminal() {
-    await Term.directWrite("\x1b[?25h")
-    process.stdin.setRawMode(false)
-  }
-
-  static async clearLines(num) {
-    await Term.directWrite(`${"\r\x1b[2K\x1b[1A".repeat(num)}`)
-  }
-
-  static directWrite(output) {
-    return new Promise(resolve => {
-      process.stdout.write(output, () => resolve())
-    })
-  }
-}

package/src/Type.js

@@ -1,207 +0,0 @@
-/**
- * @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(unknown): void} 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(unknown): boolean} 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(unknown): boolean} 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(unknown): boolean} 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(unknown): unknown} 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(unknown, unknown): unknown} callback - Function to execute on each spec
-   * @param {unknown} initialValue - Initial value for the accumulator
-   * @returns {unknown} 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(unknown): boolean} 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 {unknown} 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

@@ -1,132 +0,0 @@
-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<unknown[]>} 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<unknown>} Result of the first settled promise
-   */
-  static async race(promises) {
-    return await Promise.race(promises)
-  }
-}