@gesslar/toolkit 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -51,6 +51,7 @@
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "dependencies": {
     "@gesslar/colours": "^0.0.1",
+    "ajv": "^8.17.1",
     "globby": "^15.0.0",
     "json5": "^2.2.3",
     "yaml": "^2.8.1"

package/src/index.js

@@ -6,11 +6,14 @@ export {default as FS} from "./lib/FS.js"
 // Utility classes
 export {default as Cache} from "./lib/Cache.js"
 export {default as Collection} from "./lib/Collection.js"
+export {default as Contract} from "./lib/Contract.js"
 export {default as Data} from "./lib/Data.js"
 export {default as Glog} from "./lib/Glog.js"
 export {default as Sass} from "./lib/Sass.js"
+export {default as Schemer} from "./lib/Schemer.js"
 export {default as Tantrum} from "./lib/Tantrum.js"
 export {default as Term} from "./lib/Term.js"
+export {default as Terms} from "./lib/Terms.js"
 export {default as Type} from "./lib/TypeSpec.js"
 export {default as Util} from "./lib/Util.js"
 export {default as Valid} from "./lib/Valid.js"

package/src/lib/Contract.js

@@ -0,0 +1,257 @@
+import Sass from "./Sass.js"
+import Schemer from "./Schemer.js"
+import Terms from "./Terms.js"
+import Data from "./Data.js"
+
+/**
+ * Contract represents a successful negotiation between Terms.
+ * It handles validation and compatibility checking between what
+ * one action provides and what another accepts.
+ */
+export default class Contract {
+  #providerTerms = null
+  #consumerTerms = null
+  #validator = null
+  #debug = null
+  #isNegotiated = false
+
+  /**
+   * Creates a contract by negotiating between provider and consumer terms
+   *
+   * @param {Terms} providerTerms - What the provider offers
+   * @param {Terms} consumerTerms - What the consumer expects
+   * @param {object} options - Configuration options
+   * @param {import('../types.js').DebugFunction} [options.debug] - Debug function
+   */
+  constructor(providerTerms, consumerTerms, {debug = null} = {}) {
+    this.#providerTerms = providerTerms
+    this.#consumerTerms = consumerTerms
+    this.#debug = debug
+
+    // Perform the negotiation
+    this.#negotiate()
+  }
+
+  /**
+   * Extracts the actual schema from a terms definition
+   *
+   * @param {object} definition - Terms definition with TLD descriptor
+   * @returns {object} Extracted schema content
+   * @throws {Sass} If definition structure is invalid
+   * @private
+   */
+  static #extractSchemaFromTerms(definition) {
+    // Must be a plain object
+    if(!Data.isPlainObject(definition)) {
+      throw Sass.new("Terms definition must be a plain object")
+    }
+
+    // Must have exactly one key (the TLD/descriptor)
+    const keys = Object.keys(definition)
+    if(keys.length !== 1) {
+      throw Sass.new("Terms definition must have exactly one top-level key (descriptor)")
+    }
+
+    // Extract the content under the TLD
+    const [key] = keys
+
+    return definition[key]
+  }
+
+  /**
+   * Creates a contract from terms with schema validation
+   *
+   * @param {string} name - Contract identifier
+   * @param {object} termsDefinition - The terms definition
+   * @param {import('ajv').ValidateFunction|null} [validator] - Optional AJV schema validator function with .errors property
+   * @param {import('../types.js').DebugFunction} [debug] - Debug function
+   * @returns {Contract} New contract instance
+   */
+  static fromTerms(name, termsDefinition, validator = null, debug = null) {
+    // Validate the terms definition if validator provided
+    if(validator) {
+      const valid = validator(termsDefinition)
+
+      if(!valid) {
+        const error = Schemer.reportValidationErrors(validator.errors)
+        throw Sass.new(`Invalid terms definition for ${name}:\n${error}`)
+      }
+    }
+
+    // Extract schema from terms definition for validation
+    const schemaDefinition = Contract.#extractSchemaFromTerms(termsDefinition)
+    const termsSchemaValidator = Schemer.getValidator(schemaDefinition)
+
+    const contract = new Contract(null, null, {debug})
+    contract.#validator = termsSchemaValidator
+    contract.#isNegotiated = true // Single-party contract is automatically negotiated
+
+    return contract
+  }
+
+  /**
+   * Performs negotiation between provider and consumer terms
+   *
+   * @private
+   */
+  #negotiate() {
+    if(!this.#providerTerms || !this.#consumerTerms) {
+      // Single-party contract scenario
+      this.#isNegotiated = true
+
+      return
+    }
+
+    // Extract content for comparison (ignore TLD metadata)
+    const providerContent = Contract.#extractSchemaFromTerms(
+      this.#providerTerms.definition
+    )
+    const consumerContent = Contract.#extractSchemaFromTerms(
+      this.#consumerTerms.definition
+    )
+
+    // Compare terms for compatibility
+    const compatibility = this.#compareTerms(providerContent, consumerContent)
+
+    if(compatibility.status === "error") {
+      throw Sass.new(
+        `Contract negotiation failed: ${compatibility.errors.map(e => e.message).join(", ")}`
+      )
+    }
+
+    this.#isNegotiated = true
+    this.#debug?.(`Contract negotiated successfully`, 3)
+  }
+
+  /**
+   * Validates data against this contract
+   *
+   * @param {object} data - Data to validate
+   * @returns {boolean} True if valid
+   * @throws {Sass} If validation fails or contract not negotiated
+   */
+  validate(data) {
+    const debug = this.#debug
+
+    if(!this.#isNegotiated)
+      throw Sass.new("Cannot validate against unnegotiated contract")
+
+    if(!this.#validator)
+      throw Sass.new("No validator available for this contract")
+
+    debug?.("Validating data %o", 4, data)
+
+    const valid = this.#validator(data)
+
+    if(!valid) {
+      const error = Schemer.reportValidationErrors(this.#validator.errors)
+      throw Sass.new(`Contract validation failed:\n${error}`)
+    }
+
+    return true
+  }
+
+  /**
+   * Compares terms for compatibility
+   *
+   * @param {object} providerTerms - Terms offered by provider
+   * @param {object} consumerTerms - Terms expected by consumer
+   * @param {Array} stack - Stack trace for nested validation
+   * @returns {object} Result with status and errors
+   * @private
+   */
+  #compareTerms(providerTerms, consumerTerms, stack = []) {
+    const debug = this.#debug
+    const breadcrumb = key => (stack.length ? `@${stack.join(".")}` : key)
+    const errors = []
+
+    if(!providerTerms || !consumerTerms) {
+      return {
+        status: "error",
+        errors: [Sass.new("Both provider and consumer terms are required")]
+      }
+    }
+
+    debug?.("Comparing provider keys:%o with consumer keys:%o", 3,
+      Object.keys(providerTerms), Object.keys(consumerTerms))
+
+    // Check that consumer requirements are met by provider
+    for(const [key, consumerRequirement] of Object.entries(consumerTerms)) {
+      debug?.("Checking consumer requirement: %o [required = %o]", 3,
+        key, consumerRequirement.required ?? false)
+
+      if(consumerRequirement.required && !(key in providerTerms)) {
+        debug?.("Provider missing required capability: %o", 2, key)
+        errors.push(
+          Sass.new(`Provider missing required capability: ${key} ${breadcrumb(key)}`)
+        )
+        continue
+      }
+
+      if(key in providerTerms) {
+        const expectedType = consumerRequirement.dataType
+        const providedType = providerTerms[key]?.dataType
+
+        if(expectedType && providedType && expectedType !== providedType) {
+          errors.push(
+            Sass.new(
+              `Type mismatch for ${key}: Consumer expects ${expectedType}, provider offers ${providedType} ${breadcrumb(key)}`
+            )
+          )
+        }
+
+        // Recursive validation for nested requirements
+        if(consumerRequirement.contains) {
+          debug?.("Recursing into nested requirement: %o", 3, key)
+          const nestedResult = this.#compareTerms(
+            providerTerms[key]?.contains,
+            consumerRequirement.contains,
+            [...stack, key]
+          )
+
+          if(nestedResult.errors.length) {
+            errors.push(...nestedResult.errors)
+          }
+        }
+      }
+    }
+
+    return {status: errors.length === 0 ? "success" : "error", errors}
+  }
+
+  /**
+   * Check if contract negotiation was successful
+   *
+   * @returns {boolean} True if negotiated
+   */
+  get isNegotiated() {
+    return this.#isNegotiated
+  }
+
+  /**
+   * Get the provider terms (if any)
+   *
+   * @returns {Terms|null} Provider terms
+   */
+  get providerTerms() {
+    return this.#providerTerms
+  }
+
+  /**
+   * Get the consumer terms (if any)
+   *
+   * @returns {Terms|null} Consumer terms
+   */
+  get consumerTerms() {
+    return this.#consumerTerms
+  }
+
+  /**
+   * Get the contract validator
+   *
+   * @returns {(data: object) => boolean|null} The contract validator function
+   */
+  get validator() {
+    return this.#validator
+  }
+}

package/src/lib/Data.js

@@ -17,17 +17,18 @@ export default class Data {
  */
   static primitives = Object.freeze([
   // Primitives
-    "Undefined",
-    "Null",
+    "Bigint",
     "Boolean",
+    "Class",
+    "Null",
     "Number",
-    "Bigint",
     "String",
     "Symbol",
+    "Undefined",
 
     // Object Categories from typeof
-    "Object",
     "Function",
+    "Object",
   ])
 
   /**
@@ -38,21 +39,21 @@ export default class Data {
    */
   static constructors = Object.freeze([
   // Object Constructors
-    "Object",
     "Array",
-    "Function",
     "Date",
-    "RegExp",
     "Error",
+    "Float32Array",
+    "Float64Array",
+    "Function",
+    "Int8Array",
     "Map",
+    "Object",
+    "Promise",
+    "RegExp",
     "Set",
+    "Uint8Array",
     "WeakMap",
     "WeakSet",
-    "Promise",
-    "Int8Array",
-    "Uint8Array",
-    "Float32Array",
-    "Float64Array",
   ])
 
   /**
@@ -134,9 +135,8 @@ export default class Data {
    */
   static isValidType(type) {
     // Allow built-in types
-    if(Data.dataTypes.includes(type)) {
+    if(Data.dataTypes.includes(type))
       return true
-    }
 
     // Allow custom classes (PascalCase starting with capital letter)
     return /^[A-Z][a-zA-Z0-9]*$/.test(type)
@@ -155,12 +155,21 @@ export default class Data {
     if(!Data.isValidType(type))
       return false
 
+    // We gotta do classes up front. Ugh.
+    if(/^[Cc]lass$/.test(type)) {
+      if(typeof value === "function" &&
+      value.prototype &&
+      value.prototype.constructor === value)
+
+        return true
+    }
+
     const valueType = Data.typeOf(value)
 
     // Special cases that need extra validation
     switch(valueType) {
       case "Number":
-        return valueType === "Number" && !isNaN(value) // Excludes NaN
+        return type === "Number" && !isNaN(value) // Excludes NaN
       default:
         return valueType === type
     }

package/src/lib/Glog.js

@@ -1,7 +1,8 @@
-import Data from "./Data.js"
-import Util from "./Util.js"
 import c from "@gesslar/colours"
+
+import Data from "./Data.js"
 import Term from "./Term.js"
+import Util from "./Util.js"
 // ErrorStackParser will be dynamically imported when needed
 
 /**
@@ -237,10 +238,24 @@ class Glog {
   }
 
   // Traditional logger methods
-  debug(message, level = 0, ...arg) {
+  /**
+   * Log a debug message with specified verbosity level.
+   * Level 0 means debug OFF - use levels 1-4 for actual debug output.
+   * Debug messages only show when logLevel > 0.
+   *
+   * @param {string} message - Debug message to log
+   * @param {number} level - Debug verbosity level (1-4, default: 1)
+   * @param {...unknown} arg - Additional arguments to log
+   * @throws {Error} If level < 1 (level 0 = debug OFF)
+   */
+  debug(message, level = 1, ...arg) {
+    if(level < 1) {
+      throw new Error("Debug level must be >= 1 (level 0 = debug OFF)")
+    }
+
     const currentLevel = this.#logLevel || Glog.logLevel
 
-    if(level <= currentLevel) {
+    if(currentLevel > 0 && level <= currentLevel) {
       Term.debug(this.#compose("debug", message, level), ...arg)
     }
   }
@@ -369,10 +384,11 @@ export default new Proxy(Glog, {
     return new target(...argumentsList)
   },
   get(target, prop) {
+    // Hide execute method from public API
     if(prop === "execute") {
       return undefined
     }
 
-    return target[prop]
+    return Reflect.get(target, prop)
   }
 })

package/src/lib/Logger.js

@@ -180,3 +180,6 @@ export default class Logger {
     this.vscodeError?.(JSON.stringify(message))
   }
 }
+
+// NOTE: This is an artifact file kept for reference during Glog development.
+// Not exported from toolkit. Has broken imports to ./Core.js (actions package).

package/src/lib/Schemer.js

@@ -0,0 +1,89 @@
+import Ajv from "ajv"
+
+import Data from "./Data.js"
+import Util from "./Util.js"
+import Valid from "./Valid.js"
+
+/**
+ * Schemer provides utilities for compiling and validating JSON schemas using AJV.
+ *
+ * Usage:
+ *   - Use Schemer.fromFile(file, options) to create a validator from a file.
+ *   - Use Schemer.from(schemaData, options) to create a validator from a schema object.
+ *   - Use Schemer.getValidator(schema, options) to get a raw AJV validator function.
+ *   - Use Schemer.reportValidationErrors(errors) to format AJV validation errors.
+ */
+export default class Schemer {
+  static async fromFile(file, options={}) {
+    Valid.type(file, "FileObject")
+    Valid.assert(Data.isPlainObject(options), "Options must be a plain object.")
+
+    const schemaData = await file.loadData()
+
+    return Schemer.getValidator(schemaData, options)
+  }
+
+  static async from(schemaData={}, options={}) {
+    Valid.assert(Data.isPlainObject(schemaData), "Schema data must be a plain object.")
+    Valid.assert(Data.isPlainObject(options), "Options must be a plain object.")
+
+    return Schemer.getValidator(schemaData, options)
+  }
+
+  /**
+   * Creates a validator function from a schema object
+   *
+   * @param {object} schema - The schema to compile
+   * @param {object} [options] - AJV options
+   * @returns {(data: unknown) => boolean} The AJV validator function, which may have additional properties (e.g., `.errors`)
+   */
+  static getValidator(schema, options = {allErrors: true, verbose: true}) {
+    const ajv = new Ajv(options)
+
+    return ajv.compile(schema)
+  }
+
+  static reportValidationErrors(errors) {
+    if(!errors) {
+      return ""
+    }
+
+    return errors.reduce((errorMessages, error) => {
+      let msg = `- "${error.instancePath || "(root)"}" ${error.message}`
+
+      if(error.params) {
+        const details = []
+
+        if(error.params.type)
+          details.push(`  ➜ Expected type: ${error.params.type}`)
+
+        if(error.params.missingProperty)
+          details.push(`  ➜ Missing required field: ${error.params.missingProperty}`)
+
+        if(error.params.allowedValues) {
+          details.push(`  ➜ Allowed values: "${error.params.allowedValues.join('", "')}"`)
+          details.push(`  ➜ Received value: "${error.data}"`)
+          const closestMatch =
+            Util.findClosestMatch(error.data, error.params.allowedValues)
+
+          if(closestMatch)
+            details.push(`  ➜ Did you mean: "${closestMatch}"?`)
+        }
+
+        if(error.params.pattern)
+          details.push(`  ➜ Expected pattern: ${error.params.pattern}`)
+
+        if(error.params.format)
+          details.push(`  ➜ Expected format: ${error.params.format}`)
+
+        if(error.params.additionalProperty)
+          details.push(`  ➜ Unexpected property: ${error.params.additionalProperty}`)
+
+        if(details.length)
+          msg += `\n${details.join("\n")}`
+      }
+
+      return errorMessages ? `${errorMessages}\n${msg}` : msg
+    }, "")
+  }
+}

package/src/lib/Terms.js

@@ -0,0 +1,74 @@
+import JSON5 from "json5"
+import yaml from "yaml"
+
+import Data from "./Data.js"
+import DirectoryObject from "./DirectoryObject.js"
+import FileObject from "./FileObject.js"
+import Sass from "./Sass.js"
+import Valid from "./Valid.js"
+
+const refex = /^ref:\/\/(?<file>.*)$/
+
+/**
+ * Terms represents an interface definition - what an action promises to provide or accept.
+ * It's just the specification, not the negotiation. Contract handles the negotiation.
+ */
+export default class Terms {
+  #definition = null
+
+  constructor(definition) {
+    this.#definition = definition
+  }
+
+  /**
+   * Parses terms data, handling file references
+   *
+   * @param {string|object} termsData - Terms data or reference
+   * @param {DirectoryObject?} directoryObject - Directory context for file resolution
+   * @returns {object} Parsed terms data
+   */
+  static async parse(termsData, directoryObject) {
+    if(Data.isBaseType(termsData, "String")) {
+      const match = refex.exec(termsData)
+
+      if(match?.groups?.file) {
+        Valid.type(directoryObject, "DirectoryObject")
+
+        const file = new FileObject(match.groups.file, directoryObject)
+
+        return await file.loadData()
+      }
+
+      // Try parsing as YAML/JSON
+      try {
+        const result = JSON5.parse(termsData)
+
+        return result
+      } catch {
+        try {
+          const result = yaml.parse(termsData)
+
+          return result
+        } catch {
+          throw Sass.new(`Could not parse terms data as YAML or JSON: ${termsData}`)
+        }
+      }
+    }
+
+    if(Data.isBaseType(termsData, "Object")) {
+      return termsData
+    }
+
+    throw Sass.new(`Invalid terms data type: ${typeof termsData}`)
+  }
+
+  /**
+   * Get the terms definition
+   *
+   * @returns {object} The terms definition
+   */
+  get definition() {
+    return this.#definition
+  }
+
+}

package/src/lib/Util.js

@@ -62,6 +62,27 @@ export default class Util {
     return `${" ".repeat(diff)}${work}`
   }
 
+  /**
+   * Centre-align a string inside a fixed width (pad with spaces on left).
+   * 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 with text centred.
+   */
+  static centreAlignText(text, width=80) {
+    const work = String(text)
+
+    if(work.length >= width)
+      return work
+
+    const totalPadding = width - work.length
+    const leftPadding = Math.floor(totalPadding / 2)
+    const rightPadding = totalPadding - leftPadding
+
+    return `${" ".repeat(leftPadding)}${work}${" ".repeat(rightPadding)}`
+  }
+
   /**
    * Compute sha256 hash (hex) of the provided string.
    *

package/src/types/Collection.d.ts

@@ -211,7 +211,12 @@ export default class Collection {
   ): Promise<Record<string, R>>
 
   /** Allocate an object from a source array and spec */
-  static allocateObject(source: Array<unknown>, spec: Array<unknown> | ((source: Array<unknown>) => Promise<Array<unknown>> | Array<unknown>)): Promise<Record<string, unknown>>
+  static allocateObject(
+    source: Array<unknown>,
+    spec:
+      | Array<unknown>
+      | ((source: Array<unknown>) => Promise<Array<unknown>> | Array<unknown>)
+  ): Promise<Record<string, unknown>>
 
   /**
    * Flattens one level of an array of plain objects, transposing values so each