feat!: rewrite to typescript with modern templates and structured API

- migrate all source from ES5 CommonJS to strict TypeScript ESM
- replace winston with lightweight console/file logger
- replace commander v2 with commander v13
- replace xml2js v0.4 with v0.6
- add vitest test suite (32 tests)
- fix pipe regex bug in escape.cell (string literal instead of regex)
- fix console.assert misuse in parser
- add structured member data (params, returnType, templateParams, qualifiers)
- add modern templates with code-block signatures and parameter tables
- preserve classic templates at templates/classic/
- add java language support with dedicated templates
- add interface/enum compound type handling
- add variable initializer support
- fix compound parsing order with two-pass index resolution
- add CI workflow and README badges

Author: auscaster

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm run lint
+      - run: npm test

.gitignore

@@ -1,3 +1,4 @@
 node_modules/
+dist/
 npm-debug.log
-package-lock.json
+*.tsbuildinfo

README.md

@@ -1,80 +1,113 @@
 # Moxygen
 
-Moxygen is a Doxygen XML to Markdown converter for C++ developers who want a minimal and beautiful solution for documentating their projects.
+[![CI](https://github.com/sourcey/moxygen/actions/workflows/ci.yml/badge.svg)](https://github.com/sourcey/moxygen/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/moxygen)](https://www.npmjs.com/package/moxygen)
+[![Node](https://img.shields.io/node/v/moxygen)](https://nodejs.org)
+[![License](https://img.shields.io/npm/l/moxygen)](https://github.com/sourcey/moxygen/blob/master/LICENCE)
 
-Moxygen is currently used in conjunction with GitBook to generate the API documentation for [LibSourcey](http://sourcey.com/libsourcey/).
+Doxygen XML to Markdown converter for C++ and Java developers who want minimal, beautiful API documentation.
 
 ## Features
 
-* **Multi page output**: Output single or multiple files
-* **Internal linking**: Anchors in comments and function definitions are supported
-* **Markdown comments**: Markdown in Doxygen comments are rendered
-* **Doxygen groups**: Doxygen [grouping](http://www.doxygen.nl/manual/grouping.html) is supported for more organised documentation
-* **Custom templates**: Modify the core Markdown templates to add your own flavour
-* **Optional index**: Optionally render a top level index
+- **Multi-language** - C++ and Java supported out of the box
+- **Multi-page output** - single file, per-group, per-class, or per-page
+- **Internal linking** - anchors in comments and function definitions
+- **Markdown comments** - Markdown in Doxygen comments is rendered
+- **Doxygen groups** - [grouping](http://www.doxygen.nl/manual/grouping.html) support for organised docs
+- **Custom templates** - modify the Handlebars templates to suit your needs
+- **Optional index** - optionally render a top-level index
 
-## Usage
+## Install
 
-1. Add `GENERATE_XML=YES` to your `Doxyfile` first.
-2. Run `doxygen` to generate the XML documentation.
-3. Install `moxygen` like so: `npm install moxygen -g`.
-4. Run `moxygen` providing the folder location of the XML documentation as the first argument ie. `{OUTPUT_DIRECTORY}/xml`.  
-  ```
-  Usage: moxygen [options] <doxygen XML directory>
+```
+npm install moxygen -g
+```
 
-  Options:
+Requires Node.js 18+.
 
-    -V, --version          output the version number
-    -o, --output <file>    output file, must contain "%s" when using `groups` or `classes`
-    -g, --groups           output doxygen groups into separate files
-    -c, --classes          output doxygen classes into separate files
-    -p, --pages            output doxygen pages into separate files
-    -n, --noindex          disable generation of the index, ignored with `groups` or `classes`
-    -a, --anchors          add anchors to internal links
-    -H, --html-anchors     add html anchors to internal links
-    -l, --language <lang>  programming language
-    -t, --templates <dir>  custom templates directory
-    -L, --logfile [file]   output log messages to file
-    -q, --quiet            quiet mode
-    -h, --help             output usage information
-  ```
+## Usage
 
-## Multi-page Output
+1. Add `GENERATE_XML=YES` to your `Doxyfile`
+2. Run `doxygen` to generate the XML documentation
+3. Run `moxygen` pointing to the XML output directory
 
-Moxygen supports the doxygen [groups](http://www.doxygen.nl/manual/grouping.html#modules) syntax for generating multi page documentation. Every [\defgroup](http://www.doxygen.nl/manual/commands.html#cmddefgroup) in your source code will be parsed and output into a separate markdown file, with internal reference updated accordingly.
+```
+moxygen [options] <doxygen XML directory>
+
+Options:
+  -V, --version          output the version number
+  -o, --output <file>    output file, must contain "%s" when using groups or classes
+  -g, --groups           output doxygen groups into separate files
+  -c, --classes          output doxygen classes into separate files
+  -p, --pages            output doxygen pages into separate files
+  -n, --noindex          disable generation of the index
+  -a, --anchors          add anchors to internal links
+  -H, --html-anchors     add HTML anchors to internal links
+  -l, --language <lang>  programming language (default: cpp)
+  -t, --templates <dir>  custom templates directory
+  -L, --logfile [file]   output log messages to file (default: moxygen.log)
+  -q, --quiet            quiet mode
+  -h, --help             display help
+```
 
-Example:
+## Examples
 
+Single file output:
 ```
-moxygen --anchors --groups --output api-%s.md /path/to/doxygen/xml
+moxygen --anchors /path/to/doxygen/xml
 ```
 
-## Example
+Multi-file grouped output:
+```
+moxygen --anchors --groups --output api-%s.md /path/to/doxygen/xml
+```
 
-To get a feel for how Moxygen works you can play with the example which is located in the [example](/example) folder. The example contains:
+Per-class files:
+```
+moxygen --classes --output api-%s.md /path/to/doxygen/xml
+```
 
-* Documented C++ example code
-* A `Doxyfile` file (for doxygen 1.8.13)
-* Pre-generated XML output in [example/xml](/example/xml)
-* Pre-generated output Markdown files in [example/doc](/example/doc)
+Java project:
+```
+moxygen --language java --anchors /path/to/doxygen/xml
+```
 
-To fully build the example, follow these steps (once you've installed `doxygen`. See **Development & Contribution**, below):
+## Custom Templates
 
-1. Rebuild the XML: run `doxygen` from within the example folder.
-2. Rebuild the Moxygen output: from within this directory,
+Moxygen uses Handlebars templates for output. The default modern templates produce clean Markdown with code-block signatures and parameter tables.
 
+To use the classic (pre-1.0) template style:
 ```
-node bin/moxygen.js --groups --pages --anchors --output=example/doc/api-%s.md example/xml
+moxygen --templates ./templates/classic /path/to/xml
+```
+
+To create your own templates, copy the `templates/cpp/` directory and modify. Templates receive the full parsed compound data including structured parameter info, inheritance, and more.
+
+## Programmatic API
+
+```typescript
+import { run } from 'moxygen';
+
+await run({
+  directory: '/path/to/doxygen/xml',
+  output: 'api.md',
+  anchors: true,
+});
 ```
 
-## Development & Contribution
+## Development
 
-You can develop this project as you would any other Node project:
+```bash
+npm install
+npm run build
+npm test
+```
 
-1. Clone this repo.
-2. `npm install` from this directory.
+To test against the example:
+```bash
+npm run example
+```
 
-This project is tested through integration, by building the `example/`. To quickly test this project:
+## Licence
 
-1. Install `doxygen` (`brew install doxygen`, `choco install doxygen`, for example). Only must be done once per computer.
-2. `npm test` from this directory. This will run Doxygen on the `example/` and build the output.
+MIT

TODO.md

@@ -1,40 +1,59 @@
-# group `bicycle` {#group__bicycle}
+# bicycle {#group__bicycle}
 
 Bicycle module contains the bicycle class. Bicycles are a useful way of transporting oneself, without too much effort.
 
-## Summary
+### Classes
 
- Members                        | Descriptions                                
---------------------------------|---------------------------------------------
-`class `[`transport::Bicycle`](#classtransport_1_1Bicycle) | Standard bicycle class.
+| Name | Description |
+|------|-------------|
+| [`Bicycle`](#classtransport_1_1Bicycle) | Standard bicycle class. |
 
-# class `transport::Bicycle` {#classtransport_1_1Bicycle}
+## Bicycle {#classtransport_1_1Bicycle}
+
+> **Subclasses:** `transport::MountainBike`, `transport::RacingBike`
+> **Defined in:** `bicycle.h`
 
 Standard bicycle class.
 
 [Bicycle](#classtransport_1_1Bicycle) implements a standard bicycle. Bicycles are a useful way of transporting oneself, without too much effort (unless you go uphill or against the wind). If there are a lot of people on the road, you can use `RingBell` to ring your bell (**note**, not all bicycles have bells!).
 
-## Summary
+### Members
+
+| Name | Description |
+|------|-------------|
+| [`PedalHarder`](#classtransport_1_1Bicycle_1a7df6cce8f18012fb07bef5be9dadd8ef) | PedalHarder makes you go faster (usually). |
+| [`RingBell`](#classtransport_1_1Bicycle_1a7d2be572f09c78b4d4ae38ef22f3e98b) | Ring bell on the bike. |
+| [`~Bicycle`](#classtransport_1_1Bicycle_1a5f62d09b772a7705634bfb3551803c25) | Default destructor. |
 
- Members                        | Descriptions                                
---------------------------------|---------------------------------------------
-`public virtual void `[`PedalHarder`](#classtransport_1_1Bicycle_1a7df6cce8f18012fb07bef5be9dadd8ef)`()` | PedalHarder makes you go faster (usually).
-`public virtual void `[`RingBell`](#classtransport_1_1Bicycle_1a7d2be572f09c78b4d4ae38ef22f3e98b)`()` | Ring bell on the bike.
-`public virtual  `[`~Bicycle`](#classtransport_1_1Bicycle_1a5f62d09b772a7705634bfb3551803c25)`()` | Default destructor.
+---
 
-## Members
+#### PedalHarder {#classtransport_1_1Bicycle_1a7df6cce8f18012fb07bef5be9dadd8ef}
 
-#### `public virtual void `[`PedalHarder`](#classtransport_1_1Bicycle_1a7df6cce8f18012fb07bef5be9dadd8ef)`()` {#classtransport_1_1Bicycle_1a7df6cce8f18012fb07bef5be9dadd8ef}
+```cpp
+virtual void PedalHarder()
+```
 
 PedalHarder makes you go faster (usually).
 
-#### `public virtual void `[`RingBell`](#classtransport_1_1Bicycle_1a7d2be572f09c78b4d4ae38ef22f3e98b)`()` {#classtransport_1_1Bicycle_1a7d2be572f09c78b4d4ae38ef22f3e98b}
+---
+
+#### RingBell {#classtransport_1_1Bicycle_1a7d2be572f09c78b4d4ae38ef22f3e98b}
+
+```cpp
+virtual void RingBell()
+```
 
 Ring bell on the bike.
 
 RingBell rings the bell on the bike. Note that not all bikes have bells.
 
-#### `public virtual  `[`~Bicycle`](#classtransport_1_1Bicycle_1a5f62d09b772a7705634bfb3551803c25)`()` {#classtransport_1_1Bicycle_1a5f62d09b772a7705634bfb3551803c25}
+---
+
+#### ~Bicycle {#classtransport_1_1Bicycle_1a5f62d09b772a7705634bfb3551803c25}
+
+```cpp
+virtual ~Bicycle()
+```
 
 Default destructor.