@gesslar/bedoc 1.9.0 → 1.10.0

package/dist/bedoc.action.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://bedoc.gesslar.dev/schemas/v1/bedoc.action.json",
+  "title": "BeDoc Action Schema",
+  "type": "object",
+  "properties": {
+    "accepts": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "object"
+        }
+      },
+      "required": [
+        "type"
+      ]
+    },
+    "provides": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "object"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "not": {
+        "properties": {
+          "required": {}
+        },
+        "required": [
+          "required"
+        ]
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "required": [
+        "accepts"
+      ]
+    },
+    {
+      "required": [
+        "provides"
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/bedoc",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Pluggable documentation engine for any language and format",
   "publisher": "gesslar",
   "author": "gesslar",
@@ -37,6 +37,7 @@
     "lint:fix": "npx eslint . --fix"
   },
   "dependencies": {
+    "ajv": "^8.17.1",
     "commander": "^13.0.0",
     "dotenv": "^16.4.7",
     "error-stack-parser": "^2.1.4",

package/src/core/ContractManager.js

@@ -0,0 +1,112 @@
+import yaml from "yaml"
+import JSON5 from "json5"
+
+import * as FDUtil from "./util/FDUtil.js"
+import * as ContractUtil from "./util/ContractUtil.js"
+import * as DataUtil from "./util/DataUtil.js"
+
+const {resolveFilename, readFile} = FDUtil
+const {loadSchema, getValidator} = ContractUtil
+const {findClosestMatch} = DataUtil
+
+const refex = /^ref:\/\/(.*)$/
+
+export default class ContractManager {
+  static async newContract(actionType, terms) {
+    // Load and validate against the BeDoc contract schema
+    const schema = await loadSchema()
+    const validator = getValidator(schema)
+    const valid = validator(terms)
+
+    if(!valid) {
+      const error = ContractManager.reportValidationErrors(validator.errors)
+
+      throw new Error(`Invalid contract terms:\n${error}`)
+    }
+
+    const dataValidator = getValidator({
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "$id": `${actionType} Schema`,
+      title: `${actionType} Schema`,
+      type: "object",
+      properties: terms,
+    })
+
+    return new Contract(dataValidator)
+  }
+
+  static parse(contractData, directoryObject) {
+    if(typeof contractData === "string") {
+      const match = refex.exec(contractData)
+
+      if(match)
+        contractData = readFile(resolveFilename(match[1], directoryObject))
+
+      return yaml.parse(String(contractData))
+    }
+
+    throw new Error(`Invalid contract data: ${JSON5.stringify(contractData)}`)
+  }
+
+  static reportValidationErrors(errors) {
+    return errors.reduce((acc, 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 =
+            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 acc ? `${acc}\n${msg}` : msg
+    }, "")
+  }
+}
+
+class Contract {
+  #validator = null
+
+  constructor(validator) {
+    this.#validator = validator
+  }
+
+  get validator() {
+    return this.#validator
+  }
+
+  validate(data) {
+    const validator = this.validator
+    const valid = validator(data)
+
+    if(!valid) {
+      const error = ContractManager.reportValidationErrors(validator.errors)
+
+      throw new Error(`This document violates the agreed upon contract:\n${error}`)
+    }
+  }
+}

package/src/core/Conveyor.js

@@ -107,6 +107,9 @@ export default class Conveyor {
         return {status: "warning", file, warning: mess}
       }
 
+      parse.contract.validate(parseResult)
+      print.contract.validate(parseResult)
+
       // Step 3: Print file
       const printResult = await print.runAction({
         file,

package/src/core/Core.js

@@ -42,7 +42,7 @@ export default class Core {
     const instance = new Core({...validConfig, name: "BeDoc"})
     const debug = instance.logger.newDebug()
 
-    debug("Creating new BeDoc instance with options: `%o`", 2, validConfig)
+    debug("Creating new BeDoc instance with options: `%o`", 3, validConfig)
 
     const discovery = new Discovery(instance)
     const actionDefs = await discovery.discoverActions({
@@ -52,7 +52,7 @@ export default class Core {
 
     const validCrit = discovery.satisfyCriteria(actionDefs, validConfig)
 
-    debug("Actions that met criteria: `%o`", 2, validCrit)
+    debug("Actions that met criteria: `%o`", 3, validCrit)
 
     if(Object.values(validCrit).some(arr => arr.length === 0))
       throw new Error("No found matching parser and printer")
@@ -63,6 +63,7 @@ export default class Core {
       const printer = validCrit.print[printers]
       const printerSchema = printer.contract
       const satisfied = []
+
       for(const parser of validCrit.parse) {
         const parserSchema = parser.contract
         const result = schemaCompare(parserSchema, printerSchema)

package/src/core/Discovery.js

@@ -1,12 +1,13 @@
-// import {process} from "node:process"
-import yaml from "yaml"
 import {execSync} from "child_process"
+import path from "node:path"
 
+import ContractManager from "./ContractManager.js"
 import * as FDUtil from "./util/FDUtil.js"
 import * as ActionUtil from "./util/ActionUtil.js"
 import * as DataUtil from "./util/DataUtil.js"
-import {composeDirectory,directoryExists} from "./util/FDUtil.js"
 
+const {composeDirectory,directoryExists,resolveDirectory} = FDUtil
+const {newContract,parse} = ContractManager
 const {ls,fileExists,composeFilename,getFiles} = FDUtil
 const {actionTypes, actionMetaRequirements, loadJson} = ActionUtil
 const {isType} = DataUtil
@@ -34,15 +35,16 @@ export default class Discovery {
 
     debug("Discovering actions", 2)
 
-    debug("Specific modules provided: %o", 2, specific)
+    debug("Specific modules provided: %o", 2, Object.values(specific).filter(Boolean).length)
+    debug("Specific modules provided: %o", 3, specific)
 
-    const bucket = []
+    const files = []
     const options = this.core.options ?? {}
 
     if(options?.mockPath) {
       debug("Discovering mock actions in `%s`", 2, options.mockPath)
 
-      bucket.push(
+      files.push(
         ...(await getFiles([
           `${options.mockPath}/bedoc-*-printer.js`,
           `${options.mockPath}/bedoc-*-parser.js`,
@@ -52,22 +54,20 @@ export default class Discovery {
       debug("Mock path not set, discovering actions in node_modules", 2)
 
       debug("Looking for actions in project's package.json", 2)
+      if(this.core.packageJson) {
+        const exported = (this.core.packageJson.modules || [])
+          .map(m => composeFilename(options.basePath, m))
+          .flat()
 
-      if(this.core.packageJson?.modules) {
-        const actions = this.core.packageJson?.modules
+        debug("Found %o modules in project's package.json", 2, exported.length)
+        debug("Found modules in project's package.json: %o", 2, exported)
 
-        debug("Found %o actions in package.json", 3, actions)
-        debug("Actions found in package.json action in package.json: %o", 3, actions)
-
-        if(actions && typeof(actions) === "object")
-          bucket.push(...actions)
-        else
-          debug("No actions found in package.json", 3)
+        files.push(...exported)
       } else {
-        debug("No actions found in project's package.json", 2)
+        debug("No modules found in project's package.json", 2)
       }
 
-      debug("Looking for actions in node_modules (global and locally installed)", 2)
+      debug("Looking for modules in node_modules (global and locally installed)", 2)
       const directories = [
         execSync("npm root").toString().trim(),
         execSync("npm root -g").toString().trim(),
@@ -96,58 +96,52 @@ export default class Discovery {
           const {directories: scopedPackages} = await ls(scopedDir.absolutePath)
 
           debug("Found %o directories under scoped package %o", 2, directories.length, scopedDir.name)
+          debug("Found directories under scoped package %o\n%o", 2, scopedDir.absolutePath, scopedPackages.map(d => d.absolutePath))
 
           dirsToSearch.push(...scopedPackages)
         }
 
-        debug("Found %o directories to search for actions", 2, dirsToSearch.length)
-
-        const exports = dirsToSearch
-          .filter(d => !d.name.startsWith("."))
-          .map(d => this.#getModuleExports(d))
-
-        debug("Found %o module exports under %o", 2, exports.length, nodeModulesDir.absolutePath)
+        debug("1 Found %o directories to search for actions", 2, dirsToSearch.length)
+        debug("2 Found directories to search for actions: %o", 3, dirsToSearch)
 
-        bucket.push(...exports.flat())
-      }
-    }
+        const visibleDirs = dirsToSearch.filter(d => !d.name.startsWith("."))
 
-    debug("Discovered %d actions", 2, bucket.length)
+        for(const dir of visibleDirs) {
+          const packageJsonFile = composeFilename(dir, "package.json")
 
-    return await this.#loadActionsAndContracts(bucket, specific)
-  }
+          if(!fileExists(packageJsonFile))
+            continue
 
-  /**
-   * Get the exports from a module's package.json file, resolved to file paths
-   *
-   * @param {object} dirMap The directory map object
-   * @returns {object[]} The discovered module exports
-   */
-  #getModuleExports(dirMap) {
-    const debug = this.#debug
-    debug("Getting module exports from %o", 3, dirMap.absolutePath)
+          const packageJson = loadJson(packageJsonFile)
+          if(!packageJson.bedoc)
+            continue
 
-    const packageJsonFile = composeFilename(dirMap, "package.json")
-    if(!fileExists(packageJsonFile))
-      return []
+          const {modules} = packageJson.bedoc ?? null
+          if(!modules || !Array.isArray(modules))
+            continue
 
-    debug("Loading package.json from %o", 3, packageJsonFile.absolutePath)
+          const moduleFiles = modules
+            .map(f => composeFilename(dir, f))
+            .filter(f => fileExists(f))
 
-    const packageJson = loadJson(packageJsonFile)
-    debug("Loaded package.json from %o", 3, packageJsonFile.absolutePath)
+          debug("Discovered %d modules from package.json file: %o", 2,
+            modules.length,
+            packageJsonFile.absolutePath
+          )
+          debug("Discovered from package.json files: %o", 3, modules)
 
-    const bedocPackageJsonModules = packageJson.bedoc?.modules ?? []
-
-    debug("Discovered %o published modules", 2, bedocPackageJsonModules.length)
-    debug("Published modules %o", 3, bedocPackageJsonModules)
+          files.push(...moduleFiles)
+        }
+      }
+    }
 
-    const bedocModuleFiles = bedocPackageJsonModules
-      .map(m => composeFilename(dirMap, m))
-      .filter(m => fileExists(m))
+    debug("Discovered %d modules", 2, files.length)
+    debug("Discovered modules", 2, files.map(f => f.path))
+    debug("Discovered modules %o", 3, files)
 
-    debug("Composed modules %o", 3, bedocModuleFiles)
+    // const available = files.map(f => this.#getModuleExports(f))
 
-    return bedocModuleFiles
+    return await this.#loadActionsAndContracts(files, specific)
   }
 
   /**
@@ -163,7 +157,7 @@ export default class Discovery {
 
     debug("Loading actions and contracts", 2)
     debug("Loading %d module files", 2, moduleFiles.length)
-    debug("Specific modules to load: %o", 2, specificModules)
+    debug("Specific modules to load: %o", 3, specificModules)
 
     const resultActions = {}
     actionTypes.forEach(actionType => (resultActions[actionType] = []))
@@ -190,12 +184,19 @@ export default class Discovery {
       debug("Loading module `%s`", 2, file.absoluteUri)
 
       const loading = await this.#loadModule(file)
-      const loaded = loading.actions.map((action, index) => {
-        const contract = yaml.parse(loading.contracts[index])
+      for(let index = 0; index < loading.actions.length; index++) {
+        const action = loading.actions[index]
 
-        return {file, action, contract}
-      })
-      loadedActions.push(...loaded)
+        if(!file.directory)
+          file.directory = resolveDirectory(path.dirname(file.path))
+
+        debug(`Loading %o contract from %o`, 2, action.meta.action, file.path)
+
+        const terms = parse(loading.contracts[index], file.directory)
+        const contract = await newContract(action.meta.action, terms)
+
+        loadedActions.push({file, action, contract})
+      }
     }
 
     debug("Loaded %d actions", 2, loadedActions.length)
@@ -350,7 +351,7 @@ export default class Discovery {
   async #loadModule(module) {
     const debug = this.#debug
 
-    debug("2 Loading module `%j`", 2, module)
+    debug("Loading module `%j`", 2, module)
 
     const {absoluteUri} = module
     const moduleExports = await import(absoluteUri)

package/src/core/contract/ParseContract.js

@@ -0,0 +1,7 @@
+import {Contract} from "../ContractManager.js"
+
+export default class ParseContract extends Contract {
+  constructor(actionDefinition, logger) {
+    super(actionDefinition, logger)
+  }
+}

package/src/core/contract/PrintContract.js

@@ -0,0 +1,7 @@
+import {Contract} from "../ContractManager.js"
+
+export default class PrintContract extends Contract {
+  constructor(actionDefinition, logger) {
+    super(actionDefinition, logger)
+  }
+}

package/src/core/util/ContractUtil.js

@@ -0,0 +1,63 @@
+import fetch from "node-fetch"
+import JSON5 from "json5"
+import Ajv from "ajv"
+import {fileURLToPath,URL} from "node:url"
+
+import * as FDUtil from "./FDUtil.js"
+
+const {composeFilename,fileExists,readFile,writeFile} = FDUtil
+
+const schemaUrl = "https://bedoc.gesslar.dev/schemas/v1/bedoc.action.json"
+const localSchema = "./dist/bedoc.action.json"
+
+/**
+ * Takes a schema and returns a validator function
+ *
+ * @param {object} schema The schema to compile
+ * @returns {Function} The schema validator function
+ */
+function getValidator(schema) {
+  const ajv = new Ajv({allErrors: true, verbose: true})
+  const f = ajv.compile(schema)
+
+  return f
+}
+
+/**
+ * Downloads and preserves a copy of the action schema
+ * within the dist/ folder.
+ *
+ * @returns {object} The schema validator
+ */
+async function fetchSchema() {
+  const response = await fetch(schemaUrl)
+  const schema = await response.text()
+
+  const output = composeFilename(fileURLToPath(new URL("../../../", import.meta.url)), localSchema)
+  writeFile(output, schema)
+
+  return JSON5.parse(schema)
+}
+
+/**
+ * Loads a schema from file or fetches it if it is missing.
+ *
+ * @returns {object} The schema object
+ */
+async function loadSchema() {
+  const schemaFile = composeFilename(fileURLToPath(new URL("../../../", import.meta.url)), localSchema)
+
+  if(fileExists(schemaFile)) {
+    const schema = readFile(schemaFile)
+
+    return JSON5.parse(schema)
+  }
+
+  return await fetchSchema()
+}
+
+export {
+  fetchSchema,
+  getValidator,
+  loadSchema,
+}

package/src/core/util/DataUtil.js

@@ -383,6 +383,9 @@ function deepFreezeObject(obj) {
 /**
  * Validates that a schema matches the expected structure.
  *
+ * TODO get rid of this and all of its uses. We have a new
+ *      contract system now.
+ *
  * @param {object} schema - The schema to validate.
  * @param {object} definition - The expected structure.
  * @param {Array} stack - The stack trace for nested validation.
@@ -452,6 +455,60 @@ function schemaCompare(schema, definition, stack = [], logger = new Logger()) {
   return {status: errors.length === 0 ? "success" : "error", errors}
 }
 
+/**
+ * Determine the Levenshtein distance between two string values
+ *
+ * @param {string} a The first value for comparison.
+ * @param {string} b The second value for comparison.
+ * @returns {number} The Levenshtein distance
+ */
+function levenshteinDistance(a, b) {
+  const matrix = Array.from({length: a.length + 1}, (_, i) =>
+    Array.from({length: b.length + 1}, (_, j) =>
+      (i === 0 ? j : j === 0 ? i : 0)
+    )
+  )
+
+  for(let i = 1; i <= a.length; i++) {
+    for(let j = 1; j <= b.length; j++) {
+      matrix[i][j] =
+                a[i - 1] === b[j - 1]
+                  ? matrix[i - 1][j - 1]
+                  : 1 + Math.min(
+                    matrix[i - 1][j], matrix[i][j - 1],
+                    matrix[i - 1][j - 1]
+                  )
+    }
+  }
+
+  return matrix[a.length][b.length]
+}
+
+/**
+ * Determine the closest match between a string and allowed values
+ * from the Levenshtein distance.
+ *
+ * @param {string} input The input string to resolve
+ * @param {Array<string>} allowedValues The values which are permitted
+ * @returns {string} Suggested, probable match.
+ */
+function findClosestMatch(input, allowedValues) {
+  const threshold = 2 // Max edit distance for a "close match"
+  let closestMatch = null
+  let closestDistance = Infinity
+
+  for(const value of allowedValues) {
+    const distance = levenshteinDistance(input, value)
+    if(distance < closestDistance && distance <= threshold) {
+      closestMatch = value
+      closestDistance = distance
+    }
+  }
+
+  return closestMatch
+}
+
+
 export {
   // Classes
   TypeSpec,
@@ -465,6 +522,7 @@ export {
   arrayPad,
   cloneObject,
   deepFreezeObject,
+  findClosestMatch,
   isArrayUniform,
   isArrayUnique,
   isBaseType,
@@ -473,6 +531,7 @@ export {
   isObjectEmpty,
   isType,
   isValidType,
+  levenshteinDistance,
   mapObject,
   newTypeSpec,
   prependString,