@gesslar/bedoc 1.11.0 → 2.1.0

package/src/{core/Configuration.js → Configuration.js}

@@ -1,24 +1,16 @@
-import process from "node:process"
-import {Environment} from "./Core.js"
+import {Collection, Data, DirectoryObject, FileObject, FileSystem as FS, Promised, Sass, Tantrum} from "@gesslar/toolkit"
 import JSON5 from "json5"
+import process from "node:process"
 
 import {
   ConfigurationParameters,
   ConfigurationPriorityKeys,
 } from "./ConfigurationParameters.js"
-
-import * as ActionUtil from "./util/ActionUtil.js"
-import * as DataUtil from "./util/DataUtil.js"
-import * as FDUtil from "./util/FDUtil.js"
-
-const {loadDataFile} = ActionUtil
-const {isNothing, isType, mapObject} = DataUtil
-const {getFiles, composeFilename, fileExists} = FDUtil
-const {resolveDirectory, resolveFilename} = FDUtil
-const {fdType, fdTypes} = FDUtil
+import Environment from "./Environment.js"
 
 export default class Configuration {
   async validate({options, source}) {
+    const {basePath: base} = options
     const finalOptions = {}
 
     this.#mapEntryOptions({options, source})
@@ -34,14 +26,15 @@ export default class Configuration {
     // (Edit: No, I mean the ConfigurationParameters object. It's trash. Fix it
     // if you get this error.)
     const configValidationErrors = this.#validateConfigurationParameters()
-    if(configValidationErrors.length > 0)
-      throw new AggregateError(
-        configValidationErrors,
-        `ConfigurationParameters validation errors: `+
-          `${configValidationErrors.join(", ")}`,
+
+    if(configValidationErrors.length > 0) {
+      throw Tantrum.new(
+        `ConfigurationParameters validation errors`,
+        configValidationErrors.map(e => new Sass(e))
       )
+    }
 
-    const allOptions = this.#findAllOptions(options)
+    const allOptions = await this.#findAllOptions(options)
 
     Object.assign(finalOptions, await this.#mergeOptions(allOptions))
 
@@ -52,9 +45,10 @@ export default class Configuration {
     // Find them and add them to an array; the rest will be in pushed to the
     // end of the priority array.
     const orderedSections = []
+
     ConfigurationPriorityKeys.forEach(key => {
       if(!ConfigurationParameters[key])
-        throw new Error(`Invalid priority key: ${key}`)
+        throw Sass.new(`Invalid priority key: ${key}`)
 
       if(finalOptions[key])
         orderedSections.push({key, value: finalOptions[key]})
@@ -63,6 +57,7 @@ export default class Configuration {
     const remainingSections = Object.keys(ConfigurationParameters).filter(
       key => !ConfigurationPriorityKeys.includes(key),
     )
+
     orderedSections.push(
       ...remainingSections.map(key => {
         return {key, value: finalOptions[key]}
@@ -95,7 +90,7 @@ export default class Configuration {
         continue
 
       let {value} = section
-      const nothing = isNothing(value)
+      const nothing = Data.isNothing(value)
       const param = ConfigurationParameters[key]
       const {required, path} = param
 
@@ -110,29 +105,35 @@ export default class Configuration {
       if(path && !nothing) {
         const {mustExist, type: pathType} = path
 
-        // Special for `input` and `exclude` because they can be a comma-
-        // separated list of glob patterns.
+        // `input` and `exclude` are glob patterns (or arrays of them). Each
+        // is resolved against the base directory via DirectoryObject's glob.
         if(key === "input" || key === "exclude") {
-          if(isType(value, "array"))
-            value = await Promise.all(
-              value.map(pattern => getFiles(pattern)),
-            )
-          else if(isType(value, "string"))
-            value = await getFiles(value)
-          else
+          if(!Data.isType(value, "Array") && !Data.isType(value, "String")) {
             throw new TypeError(
               `Option \`${key}\` must be a string or an array of strings`,
             )
+          }
+
+          const patterns = Data.isType(value, "Array") ? value : [value]
 
-          finalOptions[key] = value.flat()
+          const settled = await Promised.settle(
+            patterns.map(async pat => {
+              const {files} = await base.glob(pat)
+
+              return files
+            })
+          )
+
+          value = Promised.values(settled).flat()
+
+          finalOptions[key] = value
 
           continue
         } else {
           if(mustExist === true) {
-            finalOptions[key] =
-              pathType === fdType.FILE
-                ? resolveFilename(value)
-                : resolveDirectory(value)
+            finalOptions[key] = pathType === FS.fdType.FILE
+              ? new FileObject(value)
+              : new DirectoryObject(value)
           }
         }
       }
@@ -141,6 +142,7 @@ export default class Configuration {
     return {
       status: "success",
       validated: true,
+      basePath: base,
       ...finalOptions,
     }
   }
@@ -150,17 +152,22 @@ export default class Configuration {
     if(source === Environment.CLI)
       return options
 
+    // `basePath` and `project` are consumed downstream as raw values (matching
+    // the shape the CLI provides); everything else is wrapped as {value, source}.
     for(const [key, value] of Object.entries(options)) {
+      if(key === "basePath" || key === "project")
+        continue
+
       options[key] = {value, source}
     }
 
     // We will need to inject some options if they are not available
     const cwd = process.cwd()
-    const dir = resolveDirectory(cwd)
+    const dir = new DirectoryObject(cwd)
 
     // Inject basePath if not available
     if(!options.basePath)
-      options.basePath = {value: dir, source}
+      options.basePath = dir
 
     // Add defaults which are missing
     for(const [key, param] of Object.entries(ConfigurationParameters)) {
@@ -196,7 +203,7 @@ export default class Configuration {
           errors.push(`Option \`${key}\` has no path type`)
 
         // Check if pathType is a valid key in FdTypes
-        if(!fdTypes.includes(pathType))
+        if(!FS.fdTypes.includes(pathType))
           errors.push(`Option \`${key}\` has invalid path type: ${pathType}`)
       }
     }
@@ -210,19 +217,23 @@ export default class Configuration {
    * @param {object} entryOptions - The command line options.
    * @returns {Promise<object[]>} All options from all sources.
    */
-  #findAllOptions(entryOptions) {
+  async #findAllOptions(entryOptions) {
+    const {basePath} = entryOptions
     const allOptions = []
     const environmentVariables = this.#getEnvironmentVariables()
+
     if(environmentVariables)
       allOptions.push({source: "environment", options: environmentVariables})
 
-    const packageJson = entryOptions?.packageJson
+    const packageJson = entryOptions?.project
+
     if(packageJson) {
       allOptions.push({source: "packageJson", options: packageJson})
     } else {
-      const packageJsonFile = composeFilename(process.cwd(), "package.json")
-      if(fileExists(packageJsonFile)) {
-        const packageJson = loadDataFile(packageJsonFile)
+      const packageJsonFile = basePath.getFile("package.json")
+
+      if(await packageJsonFile.exists) {
+        const packageJson = await packageJsonFile.loadData()
 
         if(packageJson.bedoc)
           allOptions.push({source: "packageJson", options: packageJson.bedoc})
@@ -238,15 +249,17 @@ export default class Configuration {
     if(useConfig) {
       const configFile =
         packageJson?.config
-          ? resolveFilename(packageJson?.config)
+          ? new FileObject(packageJson.config)
           : entryOptions.config?.value
-            ? resolveFilename(entryOptions.config.value)
-            : null
+            ? new FileObject(entryOptions.config.value)
+            : environmentVariables?.config
+              ? new FileObject(environmentVariables.config)
+              : null
 
       if(!configFile)
-        throw new Error("No config file specified")
+        throw Sass.new("No config file specified")
 
-      const configObject = loadDataFile(configFile)
+      const configObject = await configFile.loadData()
       const subConfigName =
         entryOptions?.sub ||
         packageJson?.sub ||
@@ -273,7 +286,7 @@ export default class Configuration {
     const subConfig = configObject.sub?.find(sub => sub.name === subConfigName)
 
     if(!subConfig)
-      throw new Error(`No such subconfiguration \`${subConfigName}\``)
+      throw Sass.new(`No such subconfiguration \`${subConfigName}\``)
 
     // We don't need this anymore
     delete subConfig.name
@@ -328,19 +341,21 @@ export default class Configuration {
       return acc
     }, {})
 
-    const mappedOptions = await mapObject(mergedOptions, (option, value) => {
-      const {value: entryValue, source: entrySource} = entryOptions[option] ?? {
-        value: undefined,
-        source: undefined,
-      }
+    const mappedOptions = await Collection.mapObject(mergedOptions,
+      (option, value) => {
+        const {value: entryValue, source: entrySource} =
+          entryOptions[option] ?? {
+            value: undefined,
+            source: undefined,
+          }
 
-      const entryDefaulted = entrySource === "default"
+        const entryDefaulted = entrySource === "default"
 
-      if(entryValue && value !== entryValue)
-        return entryDefaulted ? value : entryValue
+        if(entryValue && value !== entryValue)
+          return entryDefaulted ? value : entryValue
 
-      return value
-    })
+        return value
+      })
 
     // Last, but not least, add any defaulted options that are not in the
     // mapped options

package/src/{core/ConfigurationParameters.js → ConfigurationParameters.js}

@@ -1,13 +1,11 @@
-import * as DataUtil from "./util/DataUtil.js"
+import {Data} from "@gesslar/toolkit"
 
-const {newTypeSpec} = DataUtil
-
-const ConfigurationParameters = Object.freeze({
+const ConfigurationParameters = Data.deepFreezeObject({
   input: {
     short: "i",
     param: "file",
-    description: "Comma-separated glob patterns to match files",
-    type: newTypeSpec("string|string[]"),
+    description: "Glob pattern (or array of patterns) to match files",
+    type: Data.newTypeSpec("string|string[]"),
     required: true,
     path: {
       type: "file",
@@ -17,30 +15,30 @@ const ConfigurationParameters = Object.freeze({
   exclude: {
     short: "x",
     param: "file",
-    description: "Comma-separated glob patterns to exclude files",
-    type: newTypeSpec("string|string[]"),
+    description: "Glob pattern (or array of patterns) to exclude files",
+    type: Data.newTypeSpec("string|string[]"),
     required: false,
   },
   language: {
     short: "l",
     param: "lang",
     description: "Language parser to use",
-    type: newTypeSpec("string"),
+    type: Data.newTypeSpec("string"),
     required: false,
     exclusiveOf: "parser",
   },
   format: {
     short: "f",
     description: "Output format",
-    type: newTypeSpec("string"),
+    type: Data.newTypeSpec("string"),
     required: false,
-    exclusiveOf: "printer",
+    exclusiveOf: "formatter",
   },
   maxConcurrent: {
     short: "C",
     param: "num",
     description: "Maximum number of concurrent tasks",
-    type: newTypeSpec("number"),
+    type: Data.newTypeSpec("number"),
     required: false,
     default: 10,
   },
@@ -48,7 +46,7 @@ const ConfigurationParameters = Object.freeze({
     short: "k",
     param: "file",
     description: "Custom hooks JS file",
-    type: newTypeSpec("string"),
+    type: Data.newTypeSpec("string"),
     required: false,
     path: {
       type: "file",
@@ -59,7 +57,7 @@ const ConfigurationParameters = Object.freeze({
     short: "o",
     param: "dir",
     description: "Output directory",
-    type: newTypeSpec("string"),
+    type: Data.newTypeSpec("string"),
     required: false,
     path: {
       type: "directory",
@@ -70,7 +68,7 @@ const ConfigurationParameters = Object.freeze({
     short: "p",
     param: "file",
     description: "Custom parser JS file",
-    type: newTypeSpec("string"),
+    type: Data.newTypeSpec("string"),
     required: false,
     exclusiveOf: "language",
     path: {
@@ -78,11 +76,11 @@ const ConfigurationParameters = Object.freeze({
       mustExist: true,
     },
   },
-  printer: {
+  formatter: {
     short: "P",
     param: "file",
-    description: "Custom printer JS file",
-    type: newTypeSpec("string"),
+    description: "Custom formatter JS file",
+    type: Data.newTypeSpec("string"),
     required: false,
     exclusiveOf: "format",
     path: {
@@ -94,15 +92,15 @@ const ConfigurationParameters = Object.freeze({
     short: "T",
     param: "ms",
     description: "Timeout in milliseconds for hook execution",
-    type: newTypeSpec("number"),
+    type: Data.newTypeSpec("number"),
     required: false,
     default: 5000,
   },
   mock: {
     short: "m",
     param: "dir",
-    description: "Path to mock parsers and printers",
-    type: newTypeSpec("string"),
+    description: "Path to mock parsers and formatters",
+    type: Data.newTypeSpec("string"),
     required: false,
     path: {
       type: "directory",
@@ -113,7 +111,7 @@ const ConfigurationParameters = Object.freeze({
     short: "c",
     param: "file",
     description: "Use JSON config file",
-    type: newTypeSpec("string"),
+    type: Data.newTypeSpec("string"),
     required: false,
     path: {
       type: "file",
@@ -124,14 +122,14 @@ const ConfigurationParameters = Object.freeze({
     short: "s",
     param: "name",
     description: "Specify a subconfiguration",
-    type: newTypeSpec("string"),
+    type: Data.newTypeSpec("string"),
     required: false,
     dependent: "config",
   },
   debug: {
     short: "d",
     description: "Enable debug mode",
-    type: newTypeSpec("boolean"),
+    type: Data.newTypeSpec("boolean"),
     required: false,
     default: false,
   },
@@ -139,12 +137,22 @@ const ConfigurationParameters = Object.freeze({
     short: "D",
     param: "level",
     description: "Debug level",
-    type: newTypeSpec("number"),
+    type: Data.newTypeSpec("number"),
     required: false,
     default: 0,
   },
+  terse: {
+    short: "t",
+    description: "Terse output (hide per-stage progress lines)",
+    type: Data.newTypeSpec("boolean"),
+    required: false,
+    default: false,
+  },
 })
 
-const ConfigurationPriorityKeys = Object.freeze(["exclude", "input"])
+const ConfigurationPriorityKeys = Data.deepFreezeObject(["exclude", "input"])
 
-export {ConfigurationParameters, ConfigurationPriorityKeys}
+export {
+  ConfigurationParameters,
+  ConfigurationPriorityKeys
+}

package/src/Conveyor.js

@@ -0,0 +1,256 @@
+import {ActionBuilder, ActionRunner, ACTIVITY} from "@gesslar/actioneer"
+import {DirectoryObject, FileObject, Notify, Sass} from "@gesslar/toolkit"
+
+/**
+ * @import {CLIOutput} from "./CLIOutput.js"
+ * @import {Contract} from "@gesslar/negotiator"
+ */
+
+const {IF} = ACTIVITY
+
+export default class Conveyor {
+  #parser
+  #formatter
+  /** An instance of CLIOutput @type {CLIOutput} */
+  #cli
+
+  /** @type {DirectoryObject} */
+  #output
+
+  /** @type {Contract} */
+  #contract
+
+  #hooks
+  #basePath
+
+  constructor({
+    basePath,
+    parser,
+    formatter,
+    hooks,
+    contract,
+    output,
+    cli
+  }) {
+    this.#basePath = basePath
+    this.#parser = parser
+    this.#formatter = formatter
+    this.#hooks = hooks
+    this.#contract = contract
+    this.#output = output
+    this.#cli = cli
+  }
+
+  /**
+   * Emits a pipeline stage transition for a file.
+   *
+   * @param {FileObject} file - The file the stage pertains to.
+   * @param {string} stage - The stage name (read|parse|validate|format|write).
+   * @param {string} state - The new state (active|done|warning|error).
+   */
+  #emitStage = (file, stage, state) =>
+    Notify.emit("update-data", {file, message: {kind: "stage", stage, state}})
+
+  /**
+   * Defines the per-file processing pipeline.
+   *
+   * @param {ActionBuilder} builder - The Actioneer builder instance.
+   */
+  setup(builder) {
+    builder
+      .do("read", this.#readFile)
+      .do("parse", this.#parseFile)
+      .do("validate", this.#validateContracts)
+      .do("format", this.#formatFile)
+      .do("write", IF, this.#shouldWrite, this.#writeOutput)
+  }
+
+  /**
+   * Processes files through the parser→formatter pipeline with concurrency.
+   *
+   * @param {Array<FileObject>} files - List of files to process.
+   * @param {number} [maxConcurrent] - Maximum number of files to process at a time.
+   * @returns {Promise<object>} - Resolves with {succeeded, errored, warned}.
+   */
+  async convey(files, maxConcurrent = 10) {
+    const builder = new ActionBuilder(this)
+    const runner = new ActionRunner(builder)
+      .addSetup(async() => {
+        if(this.#output && !await this.#output.exists)
+          await this.#output.assureExists({recursive: true})
+      })
+
+    const destExtension = this.#formatter.meta.extension ?? "txt"
+    const contexts = files.map(file => ({
+      file,
+      output: new FileObject(`${file.module}.${destExtension}`, this.#output)
+    }))
+
+    Notify.emit("conveyor-start", contexts)
+
+    const settled = await runner.pipe(contexts, maxConcurrent)
+
+    return this.#categorize(settled, files)
+  }
+
+  // -- Pipeline activities --------------------------------------------------
+
+  #readFile = async ctx => {
+    try {
+      this.#emitStage(ctx.file, "read", "active")
+
+      const content = await ctx.file.read()
+
+      Notify.emit("update-data", {file: ctx.file, message: {kind: "input-size", value: Buffer.byteLength(content)}})
+      this.#emitStage(ctx.file, "read", "done")
+
+      return {...ctx, content}
+    } catch(error) {
+      this.#emitStage(ctx.file, "read", "error")
+
+      return {...ctx, status: "error", error: Sass.new(`Reading file ${ctx.file}`, error)}
+    }
+  }
+
+  #parseFile = async ctx => {
+    if(ctx.error)
+      return ctx
+
+    try {
+      this.#emitStage(ctx.file, "parse", "active")
+
+      const {content} = ctx
+      const builder = new ActionBuilder(new this.#parser())
+
+      if(this.#hooks?.Parse)
+        builder.withHooks(new this.#hooks.Parse())
+
+      const runner = new ActionRunner(builder)
+      const result = await runner.run(content)
+
+      this.#emitStage(ctx.file, "parse", "done")
+
+      return Object.assign(ctx, {...result})
+    } catch(error) {
+      this.#emitStage(ctx.file, "parse", "error")
+
+      return {...ctx, status: "error", error: Sass.new(`Parsing file ${ctx.file}`, error)}
+    }
+  }
+
+  #validateContracts = ctx => {
+    if(ctx.error)
+      return ctx
+
+    try {
+      this.#emitStage(ctx.file, "validate", "active")
+
+      this.#contract.validate(ctx)
+
+      this.#emitStage(ctx.file, "validate", "done")
+    } catch(err) {
+      if(err) {
+        this.#emitStage(ctx.file, "validate", "error")
+
+        throw Sass.new(`Parser validation for ${ctx.file.path}`, err)
+      }
+    }
+
+    return ctx
+  }
+
+  #formatFile = async ctx => {
+    if(ctx.error)
+      return ctx
+
+    this.#emitStage(ctx.file, "format", "active")
+
+    const {functions} = ctx
+    const builder = new ActionBuilder(new this.#formatter())
+
+    if(this.#hooks?.Format)
+      builder.withHooks(new this.#hooks.Format())
+
+    const runner = new ActionRunner(builder)
+    const formatResult = await runner.run(functions)
+
+    this.#emitStage(ctx.file, "format", "done")
+
+    return Object.assign(ctx, {formatResult})
+  }
+
+  #shouldWrite = ctx => {
+    if(ctx.error)
+      return ctx
+
+    const result = this.#output != null && ctx?.formatResult
+
+    if(result)
+      return result
+
+    Object.assign(ctx, {status: "warning", warning: `No output content for ${ctx.file.path}`})
+
+    Notify.emit("update-data", {file: ctx.file, message: {kind: "output-size", value: 0}})
+    this.#emitStage(ctx.file, "write", "warning")
+
+    return false
+  }
+
+  #writeOutput = async ctx => {
+    if(ctx.error)
+      return ctx
+
+    try {
+      this.#emitStage(ctx.file, "write", "active")
+
+      const {formatResult: content, output} = ctx
+
+      await output.write(content)
+
+      Notify.emit("update-data", {file: ctx.file, message: {kind: "output-size", value: Buffer.byteLength(content)}})
+      this.#emitStage(ctx.file, "write", "done")
+
+      return {...ctx, status: "success", output}
+    } catch(error) {
+      this.#emitStage(ctx.file, "write", "error")
+
+      return {...ctx, status: "error", error: Sass.new(`Writing file ${ctx.file}`, error)}
+    }
+  }
+
+  // -- Result categorization ------------------------------------------------
+
+  #categorize(settled, files) {
+    const succeeded = []
+    const warned = []
+    const errored = []
+
+    for(let i = 0; i < settled.length; i++) {
+      const entry = settled[i]
+      const file = files[i]
+
+      if(entry.status === "rejected") {
+        errored.push({input: file, error: entry.reason})
+        continue
+      }
+
+      const val = entry.value
+
+      switch(val?.status) {
+        case "success":
+          succeeded.push({input: file, output: val.output})
+          break
+        case "warning":
+          warned.push({input: file, warning: val.warning})
+          break
+        case "error":
+          errored.push({input: file, error: val.error})
+          break
+        default:
+          errored.push({input: file, error: new Error(`Unknown status: ${val?.status}`)})
+      }
+    }
+
+    return {succeeded, errored, warned}
+  }
+}