@gesslar/bedoc 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contributing to BeDoc
+
+Thank you for considering contributing to BeDoc! This document outlines the process and guidelines for contributing to the project. Please read it carefully before making any changes or submitting pull requests.
+
+---
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [How Can I Contribute?](#how-can-i-contribute)
+  - [Reporting Issues](#reporting-issues)
+  - [Feature Requests](#feature-requests)
+  - [Submitting Code Changes](#submitting-code-changes)
+- [Development Guidelines](#development-guidelines)
+  - [Code Style](#code-style)
+  - [Commit Messages](#commit-messages)
+  - [Pull Requests](#pull-requests)
+- [Setting Up Your Environment](#setting-up-your-environment)
+
+---
+
+## Code of Conduct
+
+All contributors must adhere to the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/). Respect and professionalism are expected in all interactions.
+
+---
+
+## How Can I Contribute?
+
+### Reporting Issues
+
+If you find a bug or something isn’t working as expected:
+
+1. Check the [issues](https://github.com/gesslar/BeDoc/issues) to ensure it hasn’t already been reported.
+2. Open a new issue with:
+   - A clear title.
+   - A detailed description of the problem.
+   - Steps to reproduce the issue.
+   - Relevant logs or screenshots (if applicable).
+
+### Feature Requests
+
+Have an idea for a new feature? Create an issue with:
+
+- A description of the feature.
+- Why it would be useful.
+- Potential challenges or considerations.
+
+### Submitting Code Changes
+
+We welcome code contributions! Before submitting a pull request:
+
+1. Fork the repository.
+2. Create a feature branch (`git checkout -b feature/your-feature-name`).
+3. Ensure all changes adhere to the [Code Style](#code-style).
+4. Add tests for your changes if applicable.
+5. Commit your changes with a [good commit message](#commit-messages).
+6. Push your branch and open a pull request.
+
+---
+
+## Development Guidelines
+
+### Code Style
+
+BeDoc enforces strict style rules. Please ensure your code adheres to the following:
+
+- Use **ESLint** with the provided flat configuration.
+- Formatting rules include:
+  - Insert final newlines.
+  - Trim trailing whitespace.
+  - Use `\n` for line endings.
+- JavaScript files are formatted using **ESLint**.
+- XML files are formatted using **Red Hat XML Formatter**.
+
+Make sure to enable auto-formatting on save in your editor. Project-specific VS Code settings are available in `.vscode/settings.json`.
+
+### Commit Messages
+
+Follow this structure for commit messages:
+
+- **Type**: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, etc.
+- **Scope**: A short scope or module name (e.g., `parser`, `hooks`).
+- **Message**: A concise summary of the change.
+
+Example:
+
+```
+feat(parser): add support for async hooks
+```
+
+### Pull Requests
+
+- Reference related issues in the description (e.g., `Closes #123`).
+- Provide a summary of the changes and why they’re needed.
+- Ensure all checks pass (e.g., linting, tests).
+- Keep pull requests focused; avoid unrelated changes.
+
+---
+
+## Setting Up Your Environment
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/gesslar/BeDoc.git
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Use the following tools:
+
+   - **Node.js** (v18 or later).
+   - **ESLint** for linting.
+   - Your preferred editor (VS Code recommended).
+
+4. Use the provided VS Code settings in `.vscode/settings.json` for consistent formatting.
+
+---
+
+Thank you for contributing to BeDoc! Your efforts make this project better for everyone.

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -0,0 +1,93 @@
+# BeDoc
+
+[![CodeQL Advanced](https://github.com/gesslar/BeDoc/actions/workflows/codeql.yml/badge.svg)](https://github.com/gesslar/BeDoc/actions/workflows/codeql.yml)
+[![Dependabot Updates](https://github.com/gesslar/BeDoc/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/gesslar/BeDoc/actions/workflows/dependabot/dependabot-updates)
+[![Auto PR and Merge - dev 🤗](https://github.com/gesslar/BeDoc/actions/workflows/autopr-dev.yml/badge.svg?branch=dev)](https://github.com/gesslar/BeDoc/actions/workflows/autopr-dev.yml)
+
+
+# BeDoc
+
+**BeDoc** is a powerful, pluggable documentation generator designed to handle any programming language and output format. With its extensible framework, you can easily create custom parsers and printers to generate structured documentation for your projects.
+
+---
+
+## Key Features
+
+- **Pluggable Design**: BeDoc works seamlessly with custom parsers and printers
+  to fit your unique needs. BeDoc also supports async operations, allowing for
+  efficient handling of large projects.
+- **Customizable Input**: Accommodate any text input, whether it’s a well-known
+  language like LPC or Lua, or an underserved format needing attention.
+- **Async Hooks**: Take advantage of BeDoc's powerful ability to use async
+  hooks to modify content in-flight, providing dynamic customization during the
+  documentation generation process.
+- **Versatile Output**: Generate documentation in formats like Markdown,
+  Wikitext, and more.
+- **Configurable**: Supports JSON-based configuration for seamless
+  customization.
+- **Integrated Workflow**: Use the CLI for smooth integration into your
+  development environment.
+
+---
+
+## Installation
+
+Install BeDoc globally using NPM:
+
+```bash
+npm install -g bedoc
+```
+
+Or add it to your project as a dependency:
+
+```bash
+npm install bedoc
+```
+
+---
+
+## Quick Start
+
+Here’s how to use BeDoc programmatically:
+
+```javascript
+const BeDoc = require('bedoc');
+
+// Initialize BeDoc with your configuration
+const docGenerator = new BeDoc({
+  input: './src',
+  output: './docs',
+  format: 'markdown',
+});
+
+// Generate documentation
+(async () => {
+  try {
+    await docGenerator.generate();
+    console.log('Documentation generated successfully!');
+  } catch (error) {
+    console.error('Error generating documentation:', error);
+  }
+})();
+```
+
+For detailed usage instructions and examples, visit the website:
+👉 **[BeDoc Documentation](https://bedoc.gesslar.dev/)**
+
+---
+
+## Contributing
+
+Contributions are welcome! Feel free to open an issue or submit a pull request.
+
+---
+
+## License
+
+This project is licensed under the [Unlicense](./LICENSE).
+
+---
+
+**Get started with BeDoc today and simplify your documentation workflow!**
+
+_Do not taunt Happy Fun Ball._

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@gesslar/bedoc",
+  "version": "1.0.0",
+  "description": "Pluggable documentation engine for any language and format",
+  "publisher": "gesslar",
+  "main": "./src/core/Core.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gesslar/BeDoc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gesslar/BeDoc/issues"
+  },
+  "bin": {
+    "bedoc": "src/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "lint:check": "npx eslint .",
+    "lint:fix": "npx eslint . --fix"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "dotenv": "^16.4.7",
+    "error-stack-parser": "^2.1.4",
+    "eslint-plugin-jsdoc": "^50.6.2",
+    "globby": "^14.0.2",
+    "micromatch": "^4.0.8",
+    "node-fetch": "^3.3.2",
+    "vscode-uri": "^3.0.8",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@stylistic/eslint-plugin-js": "^2.13.0",
+    "axios": "^1.7.9",
+    "chokidar": "^4.0.3",
+    "eslint": "^9.18.0",
+    "form-data": "^4.0.1"
+  },
+  "keywords": [
+    "documentation",
+    "plugin",
+    "parser",
+    "printer",
+    "generator",
+    "language",
+    "format",
+    "hooks"
+  ],
+  "author": "gesslar",
+  "license": "Unlicense",
+  "contributes": {
+    "commands": [
+      {
+        "command": "vscode-bedoc.generateDocs",
+        "title": "BeDoc: Generate Documentation"
+      }
+    ]
+  },
+  "extensionKind": [
+    "workspace",
+    "ui"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import {program} from "commander"
+import console from "node:console"
+import process from "node:process"
+
+import BeDoc, {Environment} from "./core/Core.js"
+import {ConfigurationParameters} from "./core/ConfigurationParameters.js"
+
+import * as ActionUtil from "./core/util/ActionUtil.js"
+import * as FDUtil from "./core/util/FDUtil.js"
+
+const {loadPackageJson} = ActionUtil
+const {resolveDirectory} = FDUtil
+
+// Main entry point
+;(async() => {
+  try {
+    // Get package info
+    const basePath = resolveDirectory(process.cwd())
+    const packageJson = loadPackageJson(basePath)
+
+    // Setup program
+    program.name(packageJson.name).description(packageJson.description)
+
+    // Build CLI
+    for(const [name, parameter] of Object.entries(ConfigurationParameters)) {
+      let arg = parameter.short
+        ? `-${parameter.short}, --${name}`
+        : `--${name}`
+
+      const param = parameter.param ? parameter.param : name
+
+      if(param)
+        arg += parameter.required ? ` <${param}>` : ` [${param}]`
+
+      const description = `${parameter.description} (${parameter.type})`
+      const defaultValue = parameter.default
+
+      program.option(arg, description, defaultValue)
+    }
+
+    // Add version option last
+    program.version(
+      packageJson.version,
+      "-v, --version",
+      "Output the version number",
+    )
+    program.helpOption("-h, --help", "Output usage information")
+    program.parse()
+
+    // Get options
+    const options = program.opts()
+
+    const sources = program._optionValueSources
+    const optionsWithSources = {}
+    for(const [key, value] of Object.entries(options)) {
+      const element = {
+        value,
+        source: sources[key],
+      }
+      optionsWithSources[key] = element
+    }
+
+    // Create core instance with validated config
+    BeDoc
+      .new({
+        options: {
+          ...optionsWithSources,
+          basePath: {value: basePath, source: "cli"},
+          packageJson: {value: packageJson, source: "cli"},
+        },
+        source: Environment.CLI
+      })
+  } catch(e) {
+    if(e instanceof Error) {
+      if(e instanceof AggregateError) {
+        for(const error of e.errors) {
+          console.error(`Error: ${error.message}`)
+        }
+      } else if(e.stack) {
+        console.error(e.stack)
+      } else {
+        console.error(`Error: ${e.message}`)
+      }
+    } else {
+      console.error(`Error: ${e}`)
+    }
+
+    process.exit(1)
+  }
+})()

package/src/core/ActionManager.js

@@ -0,0 +1,76 @@
+import {hookPoints} from "./HooksManager.js"
+
+export default class ActionManager {
+  #action = null
+  #meta = {}
+  #hooks = null
+  #contract
+  #module
+  #log
+  #debug
+
+  constructor(actionDefinition, logger) {
+    this.#log = logger
+    this.#debug = this.#log.newDebug()
+
+    this.#setupAction(actionDefinition)
+  }
+
+  #setupAction(actionDefinition) {
+    const debug = this.#debug
+
+    debug("Setting up action", 2)
+
+    const {action, contract, module, meta} = actionDefinition
+
+    if(!action)
+      throw new Error("Action is required")
+
+    if(!contract)
+      throw new Error("Contract is required")
+
+    if(!module)
+      throw new Error("Module is required")
+
+    this.#module = module
+    this.#action = action
+    this.#contract = contract
+    this.#meta = meta
+
+    debug("Action setup complete", 2)
+  }
+
+  get action() {
+    return this.#action
+  }
+
+  get hooks() {
+    return this.#hooks
+  }
+
+  set hooks(hookManager) {
+    if(this.hooks)
+      throw new Error("Hooks already set")
+
+    this.action.hook = hookManager.on.bind(this.action)
+    this.action.HOOKS = hookPoints
+    this.action.hooks = hookManager.hooks
+    this.#hooks = hookManager
+  }
+
+  get contract() {
+    return this.#contract
+  }
+
+  get module() {
+    return this.#module
+  }
+
+  get meta() {
+    return this.#meta
+  }
+
+  get log() {
+    return this.#log
+  }
+}