@gesslar/bedoc 1.11.0 → 2.1.0

package/dist/types/cli.d.ts.map

@@ -1,10 +1 @@
-{
-  "version": 3,
-  "file": "cli.d.ts",
-  "sourceRoot": "",
-  "sources": [
-    "../../src/cli.js"
-  ],
-  "names": [],
-  "mappings": ""
-}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.js"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/bedoc",
-  "version": "1.11.0",
+  "version": "2.1.0",
   "description": "Pluggable documentation engine for any language and format",
   "publisher": "gesslar",
   "author": "gesslar",
@@ -10,9 +10,6 @@
     "type": "git",
     "url": "git+https://github.com/gesslar/BeDoc.git"
   },
-  "bugs": {
-    "url": "https://github.com/gesslar/BeDoc/issues"
-  },
   "bin": {
     "bedoc": "src/cli.js"
   },
@@ -32,30 +29,34 @@
   },
   "type": "module",
   "types": "dist/types/index.d.ts",
+  "engines": {
+    "node": ">=24"
+  },
   "scripts": {
-    "lint:check": "npx eslint .",
-    "lint:fix": "npx eslint . --fix"
+    "update": "npx npm-check-updates -u && npm install",
+    "lint": "npx eslint .",
+    "lint:fix": "npx eslint . --fix",
+    "pr": "gt submit -p --ai",
+    "patch": "npm version patch",
+    "minor": "npm version minor",
+    "major": "npm version major"
   },
   "dependencies": {
-    "ajv": "^8.17.1",
-    "commander": "^13.0.0",
-    "dotenv": "^16.4.7",
-    "error-stack-parser": "^2.1.4",
-    "globby": "^14.0.2",
-    "json5": "^2.2.3",
-    "micromatch": "^4.0.8",
-    "node-fetch": "^3.3.2",
-    "yaml": "^2.7.0"
+    "@gesslar/actioneer": "^3.0.1",
+    "@gesslar/colours": "^1.0.0",
+    "@gesslar/negotiator": "^1.0.0",
+    "@gesslar/toolkit": "^5.5.1",
+    "commander": "^15.0.0",
+    "error-stack-parser": "^2.1.4"
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin-js": "^3.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.22.0",
-    "@typescript-eslint/parser": "^8.22.0",
-    "axios": "^1.7.9",
-    "chokidar": "^4.0.3",
-    "eslint": "^9.18.0",
-    "eslint-plugin-jsdoc": "^50.6.3",
-    "form-data": "^4.0.1"
+    "@gesslar/uglier": "^2.4.1",
+    "axios": "^1.17.0",
+    "chokidar": "^5.0.0",
+    "dotenv": "^17.4.2",
+    "eslint": "^10.4.1",
+    "form-data": "^4.0.5",
+    "node-fetch": "^3.3.2"
   },
   "keywords": [
     "documentation",

package/src/Action.js

@@ -0,0 +1,9 @@
+import {Data} from "@gesslar/toolkit"
+
+export default Data.deepFreezeObject({
+  actionTypes: ["parser", "formatter"],
+  actionMetaRequirements: {
+    parser: [{kind: "parser"}, "input"],
+    formatter: [{kind: "formatter"}, "format"],
+  },
+})

package/src/BeDoc.js

@@ -0,0 +1,304 @@
+import {Contract} from "@gesslar/negotiator"
+import {Data, Sass, Tantrum} from "@gesslar/toolkit"
+import {hrtime} from "node:process"
+
+import Configuration from "./Configuration.js"
+import Conveyor from "./Conveyor.js"
+import Discovery from "./Discovery.js"
+
+/**
+ * @import {DirectoryObject, FileObject, Glog} from "@gesslar/toolkit"
+ */
+
+export default class BeDoc {
+  #glog
+  #options
+  #actionDefs
+  #validCrit
+  #validSchemas
+  #contract
+  #actions
+  #validateBeDocSchema
+  #hooks
+  #basePath
+  #cli
+
+  constructor({basePath, glog, cliOutput}) {
+    this.#glog = glog
+    this.#basePath = basePath
+    this.#cli = cliOutput
+  }
+
+  /**
+   * 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 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({
+    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: base, glog, cliOutput})
+
+    bedoc.#configure({config: resolved, glog, validateBeDocSchema})
+
+    const discovered = await bedoc.#discover()
+
+    if(!discovered) {
+      return {
+        status: "fail",
+        message: "No matching actions specified or discovered.",
+      }
+    }
+
+    return await (await bedoc.#negotiate())
+      .#validateActions()
+      .#setupHooks()
+  }
+
+  /**
+   * Apply validated configuration to this instance.
+   *
+   * @param {object} config - The validated configuration object
+   * @param {Glog} glog - The Glog logger instance
+   * @param {Function} validateBeDocSchema - The action schema validator
+   */
+  #configure({config, glog, validateBeDocSchema}) {
+    this.#glog = glog
+    this.#validateBeDocSchema = validateBeDocSchema
+
+    if(config.debug && config.debugLevel > 0)
+      glog.withLogLevel(config.debugLevel)
+    else
+      glog.withLogLevel(0)
+
+    if(config.status === "error")
+      throw Tantrum.new("BeDoc configuration failed", config.errors)
+
+    glog.debug("Creating new BeDoc instance with options: `%o`", 4, config)
+
+    this.#options = config
+  }
+
+  /**
+   * Discover and filter actions that match the configuration criteria.
+   *
+   * @returns {Promise<boolean>} Whether matching actions were found
+   */
+  async #discover() {
+    const glog = this.#glog
+    const options = this.#options
+
+    const discovery = new Discovery({options, glog})
+
+    this.#actionDefs = await discovery.discoverActions({
+      parser: options.parser,
+      formatter: options.formatter,
+    }, this.#validateBeDocSchema)
+
+    this.#validCrit = discovery.satisfyCriteria(this.#actionDefs, options)
+
+    glog.debug("Actions that met criteria %o", 4, this.#validCrit)
+
+    return !Object.values(this.#validCrit).some(arr => arr.length === 0)
+  }
+
+  /**
+   * Negotiate contracts between discovered parsers and formatters.
+   *
+   * @returns {Promise<BeDoc>} This object for chaining.
+   */
+  async #negotiate() {
+    const glog = this.#glog
+    const validSchemas = {parser: [], formatter: []}
+
+    let formatters = this.#validCrit.formatter.length
+
+    while(formatters--) {
+      const formatter = this.#validCrit.formatter[formatters]
+      const {terms: consumes} = formatter
+      const satisfied = []
+
+      for(const parser of this.#validCrit.parser) {
+        try {
+          const {terms: provides} = parser
+
+          const contract = await Contract.negotiate(provides, consumes)
+
+          satisfied.push({...parser, contract})
+        } catch(err) {
+          glog.error(err)
+
+          glog.debug("%o action incompatible with %o action", 3,
+            parser.action.default.meta.input,
+            formatter.action.default.meta.format
+          )
+        }
+      }
+
+      if(satisfied.length > 0) {
+        validSchemas.formatter.push(formatter)
+        validSchemas.parser.push(...satisfied)
+      }
+    }
+
+    this.#validSchemas = validSchemas
+
+    return this
+  }
+
+  /**
+   * Validate that exactly one action per type was negotiated, then
+   * instantiate the action classes.
+   *
+   * @returns {BeDoc} This object for chaining.
+   */
+  #validateActions() {
+    const glog = this.#glog
+
+    const schemas = {}
+
+    for(const [key, value] of Object.entries(this.#validSchemas)) {
+      if(value.length === 0)
+        throw Sass.new(`No matching '${key}' action found`)
+
+      if(value.length > 1)
+        throw Sass.new(`Multiple matching '${key}' actions found`)
+
+      schemas[key] = value[0]
+    }
+
+    this.#validSchemas = schemas
+    this.#contract = schemas.parser.contract
+
+    glog.debug("Contracts satisfied between parser and formatter", 2)
+
+    const actions = {}
+
+    for(const [, {action}] of Object.entries(this.#validSchemas)) {
+      const {kind} = action.default.meta
+
+      glog.debug("Assigning %o action", 2, kind)
+
+      actions[kind] = action.default
+    }
+
+    this.#actions = actions
+
+    return this
+  }
+
+  async #setupHooks() {
+    /** @type {Glog} */
+    const glog = this.#glog
+
+    if(!this.#options.hooks)
+      return this
+
+    /** @type {FileObject} */
+    const hooksFile = this.#options.hooks
+
+    if(!hooksFile)
+      return this
+
+    if(!await hooksFile.exists) {
+      glog.warn(`File not found: ${hooksFile.path}`)
+
+      return this
+    }
+
+    const loaded = await hooksFile.import()
+    if(!loaded)
+      return this
+
+    const hooks = {}
+    if(loaded.Parse && Data.isType(loaded.Parse, "Function"))
+      hooks.Parse = loaded.Parse
+
+    if(loaded.Format && Data.isType(loaded.Format, "Function"))
+      hooks.Format = loaded.Format
+
+    if(Data.isEmpty(hooks)) {
+      glog.warn(`No hooks found in ${hooksFile.path}`)
+
+      return this
+    }
+
+    this.#hooks = hooks
+
+    return this
+  }
+
+  async processFiles() {
+    const glog = this.#glog
+
+    glog.debug("Starting file processing with conveyor", 1)
+
+    const {input, output, maxConcurrent} = this.#options
+
+    if(!input?.length)
+      throw Sass.new("No input files specified")
+
+    const conveyor = new Conveyor({
+      parser: this.#actions.parser,
+      formatter: this.#actions.formatter,
+      contract: this.#contract,
+      hooks: this.#hooks,
+      glog,
+      output,
+      basePath: this.#basePath,
+      cli: this.#cli
+    })
+
+    const processStart = hrtime.bigint()
+    const processResult = await conveyor.convey(input, maxConcurrent)
+    const processEnd = hrtime.bigint()
+
+    glog.debug("Conveyor complete", 1)
+
+    const result = {
+      totalFiles: input.length,
+      succeeded: processResult.succeeded,
+      warned: processResult.warned,
+      errored: processResult.errored,
+      duration: ((Number(processEnd - processStart)) / 1_000_000).toFixed(2),
+    }
+
+    glog.debug("File processing complete", 1)
+
+    return result
+  }
+}

package/src/CLIOutput.js

@@ -0,0 +1,198 @@
+import c from "@gesslar/colours"
+import {FileSystem as FS, Notify, Term} from "@gesslar/toolkit"
+import process from "node:process"
+import {stripVTControlCharacters} from "node:util"
+
+/**
+ * Glyph sets for the framed output blocks. The `unicode` set is used when the
+ * terminal can render box-drawing/geometric characters; `ascii` is the plain
+ * fallback. In the ascii set the status markers are shape-distinct (not just
+ * colour-distinct) so they remain legible when colour is also unavailable.
+ */
+const GLYPHS = {
+  unicode: {
+    upper: "╭▸", upperDone: "╭─", mid: "│", lower: "╰▸", lowerDone: "╰─",
+    pending: "□", active: "▸", success: "■", warning: "■", error: "■",
+  },
+  ascii: {
+    upper: ",>", upperDone: ",-", mid: "|", lower: "`>", lowerDone: "`-",
+    pending: ".", active: ">", success: "#", warning: "!", error: "x",
+  },
+}
+
+/**
+ * Rough check for whether the terminal can render Unicode glyphs. Mirrors the
+ * common heuristic: everything outside the raw Linux kernel console is assumed
+ * capable on POSIX; on Windows, only modern terminals are.
+ *
+ * @returns {boolean} True if Unicode glyphs are safe to emit.
+ */
+function supportsUnicode() {
+  if(process.platform === "win32")
+    return Boolean(process.env.WT_SESSION || process.env.TERM_PROGRAM)
+
+  return process.env.TERM !== "linux"
+}
+
+/**
+ * Handles CLI output for the BeDoc pipeline, rendering progress and status
+ * for each file as it moves through the read → parse → validate → format →
+ * write stages.
+ *
+ * Listens to a {@link Notify} instance and tracks per-file state in an
+ * internal map so that output can be updated in-place as each stage completes.
+ *
+ * Each file is drawn as a framed block: an Input line (top border), one line
+ * per pipeline stage, and an Output line (bottom border). Colour is emitted
+ * only when {@link Term.hasColor} is true (honouring NO_COLOR/FORCE_COLOR), and
+ * the glyph set degrades to ASCII when Unicode is unsupported.
+ */
+export default class CLIOutput  {
+  /** Pipeline stages, in order, matching the Conveyor activity names. */
+  #stages = ["read", "parse", "validate", "format", "write"]
+
+  /** The active glyph set (unicode or ascii). */
+  #g = supportsUnicode() ? GLYPHS.unicode : GLYPHS.ascii
+
+  #basePath
+
+  /** When true, only Input/Output lines are drawn (no per-stage lines). */
+  #terse
+
+  /**
+   * Tracks per-file state keyed by file path/identifier.
+   *
+   * @type {Map<string, object>}
+   */
+  #files = new Map()
+
+  constructor({config}) {
+    this.#basePath = config.basePath
+    this.#terse = Boolean(config.terse)
+
+    Notify.on("conveyor-start", this.#conveyorStart)
+    Notify.on("update-data", this.#updateData)
+
+    c.alias.set("border", "{F033}")
+    c.alias.set("fileName", "{<B}")
+    c.alias.set("fileSize", "{F070}")
+
+    c.alias.set("success", "{F064}")
+    c.alias.set("pending", "{F033}")
+    c.alias.set("warning", "{F178}")
+    c.alias.set("error", "{F124}")
+  }
+
+  /**
+   * Seeds the tracking map when the conveyor announces its work set.
+   *
+   * @param {Array<object>} ctx - One entry per file, each {file, output}.
+   */
+  #conveyorStart = ctx => {
+    ctx.forEach(e => this.#files.set(e.file, {
+      output: e.output,
+      stages: Object.fromEntries(this.#stages.map(s => [s, "pending"])),
+      size: {
+        input: undefined, // undefined = pending, null = err, 0 = warning, number = success
+        output: undefined, // undefined = pending, null = err, 0 = warning, number = success
+      }
+    }))
+  }
+
+  /**
+   * Applies a single update for a file and re-renders. Messages are either a
+   * size update ({kind: "input-size"|"output-size", value}) or a stage
+   * transition ({kind: "stage", stage, state}).
+   *
+   * @param {object} update - The update payload.
+   * @param {object} update.file - The file the update pertains to.
+   * @param {object} update.message - The update message (see above).
+   */
+  #updateData = ({file, message}) => {
+    const item = this.#files.get(file)
+
+    if(!item)
+      return
+
+    switch(message.kind) {
+      case "input-size":
+        item.size.input = message.value
+        break
+
+      case "output-size":
+        item.size.output = message.value
+        break
+
+      case "stage":
+        item.stages[message.stage] = message.state
+        break
+    }
+
+    this.render()
+  }
+
+  /**
+   * Maps a stage state to its coloured glyph.
+   *
+   * @param {string} state - One of pending|active|done|warning|error.
+   * @returns {string} The coloured marker.
+   */
+  #marker(state) {
+    switch(state) {
+      case "active": return `{pending}${this.#g.active}{/}`
+      case "done": return `{success}${this.#g.success}{/}`
+      case "warning": return `{warning}${this.#g.warning}{/}`
+      case "error": return `{error}${this.#g.error}{/}`
+      default: return `{pending}${this.#g.pending}{/}`
+    }
+  }
+
+  /**
+   * Maps an input/output size to its coloured glyph. undefined is pending,
+   * null is error, 0 is warning, any other number is success.
+   *
+   * @param {number|null|undefined} size - The tracked size value.
+   * @returns {string} The coloured marker.
+   */
+  #sizeMarker(size) {
+    if(size === undefined)
+      return `{pending}${this.#g.pending}{/}`
+
+    if(size === null)
+      return `{error}${this.#g.error}{/}`
+
+    if(size === 0)
+      return `{warning}${this.#g.warning}{/}`
+
+    return `{success}${this.#g.success}{/}`
+  }
+
+  render(cls=true) {
+    const lines = []
+
+    for(const [file, {output, stages, size}] of this.#files) {
+      const srcRel = FS.toRelativePath(this.#basePath.path, file.path)
+      const outRel = FS.toRelativePath(this.#basePath.path, output.path)
+      const done = size.output !== undefined
+
+      lines.push(
+        `{border}${done ? this.#g.upperDone : this.#g.upper}{/}${this.#sizeMarker(size.input)} Input {fileName}${srcRel}{B>}` +
+        (size.input ? ` ({fileSize}${size.input.toLocaleString()}{/} bytes)` : "")
+      )
+
+      if(!this.#terse)
+        for(const stage of this.#stages)
+          lines.push(`{border}${this.#g.mid}{/}  ${this.#marker(stages[stage])} ${stage}`)
+
+      lines.push(
+        `{border}${done ? this.#g.lowerDone : this.#g.lower}{/}${this.#sizeMarker(size.output)} Output {fileName}${outRel}{/}` +
+        (size.output ? ` ({fileSize}${size.output.toLocaleString()}{/} bytes)` : "")
+      )
+    }
+
+    const out = c`${lines.join("\n")}\n`
+
+    cls && Term.cls()
+    Term.write(Term.hasColor ? out : stripVTControlCharacters(out))
+  }
+}