@gesslar/bedoc 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/bedoc",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Pluggable documentation engine for any language and format",
   "publisher": "gesslar",
   "author": "gesslar",

package/src/BeDoc.js

@@ -7,7 +7,7 @@ import Conveyor from "./Conveyor.js"
 import Discovery from "./Discovery.js"
 
 /**
- * @import {FileObject, Glog} from "@gesslar/toolkit"
+ * @import {DirectoryObject, FileObject, Glog} from "@gesslar/toolkit"
  */
 
 export default class BeDoc {
@@ -30,20 +30,50 @@ export default class BeDoc {
   }
 
   /**
-   * Create a new instance of BeDoc.
+   * Resolve and validate configuration from all sources (CLI, environment,
+   * package.json, config file). This runs independently of any BeDoc instance
+   * so the resulting config object can be built first and shared with other
+   * consumers (e.g. CLIOutput) before a BeDoc instance exists.
    *
    * @param {object} args
-   * @param {object} args.options - The options passed into BeDoc
+   * @param {object} args.options - The raw options (with sources) to resolve
    * @param {string} args.source - The environment BeDoc is running in
+   * @returns {Promise<object>} The validated configuration object
+   */
+  static async resolveConfig({options, source}) {
+    const config = new Configuration()
+
+    return await config.validate({options, source})
+  }
+
+  /**
+   * Create a new instance of BeDoc.
+   *
+   * Configuration may be supplied pre-resolved (via {@link resolveConfig}) when
+   * a caller needs the config object before the instance exists — e.g. the CLI
+   * resolves it first to share with CLIOutput. Otherwise pass raw `options` and
+   * `source` and BeDoc resolves them itself, so any environment can construct a
+   * BeDoc in a single call.
+   *
+   * @param {object} args
+   * @param {object} [args.config] - Pre-validated configuration (see resolveConfig)
+   * @param {object} [args.options] - Raw options to resolve, if config is absent
+   * @param {string} [args.source] - The environment BeDoc is running in
+   * @param {DirectoryObject} [args.basePath] - The project base path
    * @param {Glog} args.glog - The Glog logger instance
+   * @param {Function} args.validateBeDocSchema - The action schema validator
+   * @param {object} args.cliOutput - The CLI output instance
    * @returns {Promise<BeDoc>} A new instance of BeDoc
    */
-  static async new({options, source, glog, validateBeDocSchema, cliOutput}) {
-    const {basePath} = options
+  static async new({
+    config, options, source, basePath, glog, validateBeDocSchema, cliOutput
+  }) {
+    const resolved = config ?? await BeDoc.resolveConfig({options, source})
+    const base = basePath ?? resolved.basePath ?? options?.basePath
 
-    const bedoc = new this({basePath, glog, cliOutput})
+    const bedoc = new this({basePath: base, glog, cliOutput})
 
-    await bedoc.#configure({options, source, glog, validateBeDocSchema})
+    bedoc.#configure({config: resolved, glog, validateBeDocSchema})
 
     const discovered = await bedoc.#discover()
 
@@ -60,29 +90,27 @@ export default class BeDoc {
   }
 
   /**
-   * Validate configuration and store as options.
+   * Apply validated configuration to this instance.
    *
-   * @param {object} options - The raw options passed into BeDoc
-   * @param {string} source - The environment BeDoc is running in
+   * @param {object} config - The validated configuration object
+   * @param {Glog} glog - The Glog logger instance
+   * @param {Function} validateBeDocSchema - The action schema validator
    */
-  async #configure({options, source, glog, validateBeDocSchema}) {
+  #configure({config, glog, validateBeDocSchema}) {
     this.#glog = glog
     this.#validateBeDocSchema = validateBeDocSchema
 
-    const config = new Configuration()
-    const validConfig = await config.validate({options, source})
-
-    if(validConfig.debug && validConfig.debugLevel > 0)
-      glog.withLogLevel(validConfig.debugLevel)
+    if(config.debug && config.debugLevel > 0)
+      glog.withLogLevel(config.debugLevel)
     else
       glog.withLogLevel(0)
 
-    if(validConfig.status === "error")
-      throw Tantrum.new("BeDoc configuration failed", validConfig.errors)
+    if(config.status === "error")
+      throw Tantrum.new("BeDoc configuration failed", config.errors)
 
-    glog.debug("Creating new BeDoc instance with options: `%o`", 4, validConfig)
+    glog.debug("Creating new BeDoc instance with options: `%o`", 4, config)
 
-    this.#options = validConfig
+    this.#options = config
   }
 
   /**

package/src/CLIOutput.js

@@ -66,9 +66,9 @@ export default class CLIOutput  {
    */
   #files = new Map()
 
-  constructor({basePath, terse = false}) {
-    this.#basePath = basePath
-    this.#terse = terse
+  constructor({config}) {
+    this.#basePath = config.basePath
+    this.#terse = Boolean(config.terse)
 
     Notify.on("conveyor-start", this.#conveyorStart)
     Notify.on("update-data", this.#updateData)

package/src/Configuration.js

@@ -142,6 +142,7 @@ export default class Configuration {
     return {
       status: "success",
       validated: true,
+      basePath: base,
       ...finalOptions,
     }
   }

package/src/cli.js

@@ -71,28 +71,33 @@ void (async() => {
       optionsWithSources[key] = element
     }
 
-    // Create core instance with validated config
+    // Resolve and validate configuration up front, before constructing
+    // anything that depends on it. Everything downstream — CLIOutput, BeDoc,
+    // the logger — consumes this single validated config object.
     const prjPath = new DirectoryObject()
-    const cliOutput = new CLIOutput({
-      basePath: prjPath,
-      terse: Boolean(options.terse),
-    })
     const prjPkJsonFile = new FileObject("package.json", prjPath)
     const prjPkjJson = await prjPkJsonFile.loadData()
     const pkjBedoc = prjPkjJson?.bedoc ?? {}
+
+    const config = await BeDoc.resolveConfig({
+      options: {
+        ...optionsWithSources,
+        basePath: prjPath,
+        project: pkjBedoc,
+      },
+      source: Environment.CLI,
+    })
+
+    const cliOutput = new CLIOutput({config})
+
     const validateBeDocSchema = await loadSchemaValidator(thisPath)
 
     const bedoc = await BeDoc
       .new({
-        options: {
-          ...optionsWithSources,
-          basePath: prjPath,
-          project: pkjBedoc,
-        },
-        source: Environment.CLI,
+        config,
         glog,
         validateBeDocSchema,
-        cliOutput
+        cliOutput,
       })
 
     if(!(bedoc instanceof BeDoc)) {