@ts-for-gir/cli 4.0.0-beta.4 → 4.0.0-beta.41

package/README.md

@@ -18,13 +18,12 @@
 
 # CLI
 
-CLI tool to generate Typescript Type Definition files for GJS and node-gtk.
+CLI tool to generate TypeScript type definitions and HTML documentation for GObject Introspection Repository (GIR) files, primarily for GJS applications.
 
 ## Getting started
 
 ``` bash
-npm install -g @ts-for-gir/cli
-ts-for-gir --help
+npx @ts-for-gir/cli --help
 ```
 
 > Alternatively you can also add @ts-for-gir/cli to your dependencies:
@@ -32,117 +31,211 @@ ts-for-gir --help
 > npm install --save-dev @ts-for-gir/cli
 > ```
 >
-> Or without installing using `npx`:
+> Or globally install it:
 > ```bash
-> npx @ts-for-gir/cli --help
+> npm install -g @ts-for-gir/cli
+> ts-for-gir --help
 > ```
 
-After you have installed `@ts-for-gir/cli` you can run the `ts-for-gir` command:
-
-```bash
-$ ts-for-gir --help
-
-Typescript .d.ts generator from GIR for GJS or node-gtk
+```
+TypeScript type definition generator for GObject introspection GIR files
 
 Commands:
-  ts-for-gir generate [modules..]  Generates .d.ts files from GIR for GJS or nod
-                                   e-gtk
+  ts-for-gir generate [modules..]  Generates .d.ts files from GIR for GJS
+  ts-for-gir json [modules..]      Generates JSON representation from GIR files for analysis and tooling
+  ts-for-gir doc [modules..]       Generates HTML documentation from GIR files using TypeDoc
   ts-for-gir list [modules..]      Lists all available GIR modules
-  ts-for-gir doc [modules..]       The HTML documentation generator is not yet i
-                                   mplemented, but feel free to implement it 🤗
+  ts-for-gir copy [modules..]      Scan for *.gir files and copy them to a new directory
+  ts-for-gir analyze               Analyze report files generated by ts-for-gir reporter
 
 Options:
   --version  Show version number                                       [boolean]
-  --help     Show help                                                 [boolean]                                             [boolean]
+  --help     Show help                                                 [boolean]
 ```
 
 ## Example
 
-To generate the Typescript type definitions of Gtk-4.0 for GJS run:
+To generate the TypeScript type definitions of Gtk-4.0 for GJS run:
 
 ```
 ts-for-gir generate Gtk-4.0
 ```
 
-To generate this types for [node-gtk](https://github.com/romgrk/node-gtk) run:
-
-```
-ts-for-gir generate Gtk-4.0 -e node
-```
-
-You can also look at the [examples](https://github.com/gjsify/ts-for-gir/tree/main/examples) to see how the types are generated there.
+You can also look at the [examples](https://github.com/gjsify/ts-for-gir/tree/main/examples) to see how the types are generated and/or used there.
 
 ## Generate .d.ts files
 
-```bash
-$ ts-for-gir generate --help
-
-ts-for-gir generate [modules..]
-
+```
 ts-for-gir generate [modules..]
 
-Generates .d.ts files from GIR for GJS or node-gtk
+Generates .d.ts files from GIR for GJS
 
 Options:
       --version                 Show version number                    [boolean]
       --help                    Show help                              [boolean]
-      --modules                 GIR modules to load, e.g. 'Gio-2.0'. Accepts mul
-                                tiple modules           [array] [default: ["*"]]
-  -g, --girDirectories          GIR directories
-  [array] [default: ["/usr/local/share/gir-1.0","/usr/share/gir-1.0","/usr/share
-  /gnome-shell","/usr/share/gnome-shell/gir-1.0","/usr/lib64/mutter-10","/usr/li
-  b64/mutter-11","/usr/lib64/mutter-12","/usr/lib/x86_64-linux-gnu/mutter-10","/
-  usr/lib/x86_64-linux-gnu/mutter-11","/usr/lib/x86_64-linux-gnu/mutter-12","/ho
-  me/jumplink/.local/share/flatpak/exports/share/gir-1.0","/var/lib/flatpak/expo
-                                                            rts/share/gir-1.0"]]
-      --root                    Root directory of your project
-                        [string] [default: "/home/jumplink/Projekte/ts-for-gir"]
+      --modules                 GIR modules to load, e.g. 'Gio-2.0'. Accepts
+                                multiple modules        [array] [default: ["*"]]
+  -g, --girDirectories          GIR directories                          [array]
+      --root                    Root directory of your project           [string]
   -o, --outdir                  Directory to output to
                                                   [string] [default: "./@types"]
   -i, --ignore                  Modules that should be ignored
                                                            [array] [default: []]
   -v, --verbose                 Switch on/off the verbose mode
-                                                       [string] [default: false]
-      --ignoreVersionConflicts  Do not ask for package versions if multiple vers
-                                ions are found         [string] [default: false]
+                                                      [boolean] [default: false]
+      --ignoreVersionConflicts  Skip prompts for library version selection when
+                                multiple versions are detected
+                                                      [boolean] [default: false]
   -p, --print                   Print the output to console and create no files
-                                                       [string] [default: false]
-      --configName              Name of the config if you want to use a differen
-                                t name    [string] [default: ".ts-for-girrc.js"]
-  -d, --noNamespace             Do not export all symbols for each module as a n
-                                amespace               [string] [default: false]
+                                                      [boolean] [default: false]
+      --configName              Specify a custom name for the configuration file
+                                          [string] [default: ".ts-for-girrc.js"]
+  -d, --noNamespace             Do not export all symbols for each module as a
+                                namespace             [boolean] [default: false]
   -n, --noComments              Do not generate documentation comments
-                                                       [string] [default: false]
-      --noDebugComments         Do not generate debugging inline comments
-                                                       [string] [default: false]
-      --fixConflicts            Fix Inheritance and implementation type conflict
-                                s                       [string] [default: true]
+                                                      [boolean] [default: false]
       --promisify               Generate promisified functions for async/finish
-                                calls                   [string] [default: true]
+                                calls                  [boolean] [default: true]
       --npmScope                Scope of the generated NPM packages
                                                      [string] [default: "@girs"]
+      --workspace               Uses the workspace protocol for the generated
+                                packages              [boolean] [default: false]
+      --onlyVersionPrefix       Only use the version prefix for the ambient
+                                module exports        [boolean] [default: false]
+      --noPrettyPrint           Do not prettify the generated types
+                                                      [boolean] [default: false]
+      --noAdvancedVariants      Disable GLib.Variant class with string parsing
+                                                      [boolean] [default: false]
+      --package                 Generate the typescript types with package.json
+                                support               [boolean] [default: false]
+      --reporter                Enable generation problem reporter and create a
+                                detailed report file  [boolean] [default: false]
+      --reporterOutput          Output file path for the reporter
+                               [string] [default: "ts-for-gir-report.json"]
 
 Examples:
-  ts-for-gir generate                       Run 'ts-for-gir generate' in your gj
-                                            s or node-gtk project to generate ty
-                                            pings for your project, pass the gir
-                                             modules you need for your project
-  ts-for-gir generate Gtk*                  You can also use wild cards
-  ts-for-gir generate '*'                   If you want to parse all of your loc
-                                            ally installed gir modules run
-  ts-for-gir generate '*' -e gjs            Generate .d.ts. files only for gjs
-  ts-for-gir generate '*' -e node           Generate .d.ts. files only for node
-  ts-for-gir generate --configName='.ts-fo  Use a special config file
-  r-gir.gtk4.rc.js
-  ts-for-gir generate --ignore=Gtk-4.0 xra  Generate .d.ts. files but not for Gt
-  ndr-1.3                                   k-4.0 and xrandr-1.3
+  ts-for-gir generate                                Run 'ts-for-gir generate'
+                                                     in your gjs project to
+                                                     generate typings
+  ts-for-gir generate 'Gtk*'                         You can also use wild cards
+  ts-for-gir generate '*'                            Parse all locally installed
+                                                     gir modules
+  ts-for-gir generate --configName='.rc.js'          Use a special config file
+  ts-for-gir generate --ignore=Gtk-4.0 xrandr-1.3   Generate .d.ts files but
+                                                     not for Gtk-4.0 and
+                                                     xrandr-1.3
 ```
 
-## List available GIR modules
+## Generate TypeDoc JSON
+
+Generates TypeDoc JSON output enriched with GIR-specific metadata. This is useful as an intermediate step before generating HTML documentation (see `doc --merge`), or for custom tooling.
+
+```
+ts-for-gir json [modules..]
+
+Generates JSON representation from GIR files for analysis and tooling
+
+Options:
+      --version                 Show version number                    [boolean]
+      --help                    Show help                              [boolean]
+      --modules                 GIR modules to load, e.g. 'Gio-2.0'. Accepts
+                                multiple modules        [array] [default: ["*"]]
+  -g, --girDirectories          GIR directories                          [array]
+      --root                    Root directory of your project           [string]
+  -o, --outdir                  Directory to output to
+                                                  [string] [default: "./@types"]
+  -i, --ignore                  Modules that should be ignored
+                                                           [array] [default: []]
+  -v, --verbose                 Switch on/off the verbose mode
+                                                      [boolean] [default: false]
+      --ignoreVersionConflicts  Skip prompts for library version selection when
+                                multiple versions are detected
+                                                      [boolean] [default: false]
+      --configName              Specify a custom name for the configuration file
+                                          [string] [default: ".ts-for-girrc.js"]
+
+Examples:
+  ts-for-gir json                          Generate JSON for all modules
+  ts-for-gir json Gtk-4.0 --outdir ./json  Generate JSON for Gtk-4.0 into ./json
+  ts-for-gir json '*' --outdir ./json      Generate JSON for all modules
+```
+
+## Generate HTML documentation
+
+Generates a browsable HTML API reference using TypeDoc. Supports two modes:
+
+- **Direct mode**: Generates `.d.ts` files from GIR, then converts to HTML in one step.
+- **Merge mode** (`--merge`): Reads pre-generated JSON files (from `ts-for-gir json`) and produces HTML. This uses less memory and is suitable for large module sets.
+
+The generated documentation uses a custom theme inspired by [gi-docgen](https://gnome.pages.gitlab.gnome.org/gi-docgen/) with a 3-column layout, GIR metadata badges, and categorized module listings.
+
+See the live documentation at [gjsify.github.io/docs](https://gjsify.github.io/docs).
+
+```
+ts-for-gir doc [modules..]
+
+Generates HTML documentation from GIR files using TypeDoc
+
+Options:
+      --version                 Show version number                    [boolean]
+      --help                    Show help                              [boolean]
+      --modules                 GIR modules to load, e.g. 'Gio-2.0'. Accepts
+                                multiple modules        [array] [default: ["*"]]
+  -g, --girDirectories          GIR directories                          [array]
+      --root                    Root directory of your project           [string]
+  -o, --outdir                  Directory to output to
+                                                    [string] [default: "./docs"]
+  -i, --ignore                  Modules that should be ignored
+                                                           [array] [default: []]
+  -v, --verbose                 Switch on/off the verbose mode
+                                                      [boolean] [default: false]
+      --ignoreVersionConflicts  Skip prompts for library version selection when
+                                multiple versions are detected
+                                                      [boolean] [default: false]
+      --configName              Specify a custom name for the configuration file
+                                          [string] [default: ".ts-for-girrc.js"]
+      --combined                Generate a single unified documentation for all
+                                modules (use --no-combined for separate
+                                per-module docs)       [boolean] [default: true]
+      --sourceLinkTemplate      URL template for source links in generated
+                                documentation. Supports {path}, {line},
+                                {gitRevision} placeholders              [string]
+      --theme                   Theme for HTML documentation generation.
+                                Use "default" for TypeDoc's built-in theme.
+                                              [string] [default: "gi-docgen"]
+      --readme                  Path to a README file for the documentation
+                                index page. Use "none" to disable.      [string]
+      --merge                   Use TypeDoc merge mode to generate HTML from
+                                pre-generated JSON files (requires --jsonDir)
+                                                      [boolean] [default: false]
+      --jsonDir                 Directory containing pre-generated TypeDoc JSON
+                                files for merge mode (from 'ts-for-gir json')
+                                                                        [string]
+
+Examples:
+  ts-for-gir doc Gtk-4.0 --outdir ./docs       Generate HTML documentation
+                                                for Gtk-4.0
+  ts-for-gir doc '*' --outdir ./docs            Generate documentation for all
+                                                locally installed GIR modules
+  ts-for-gir doc --merge --jsonDir ./json       Generate HTML from pre-generated
+      --outdir ./docs                           JSON files (low memory)
+```
+
+### Two-phase workflow
+
+For large module sets, you can split documentation generation into two phases to reduce peak memory usage:
 
 ```bash
-$ ts-for-gir list --help
- 
+# Phase 1: Generate JSON files (one per module)
+ts-for-gir json '*' --outdir ./json
+
+# Phase 2: Merge JSON files into HTML documentation
+ts-for-gir doc --merge --jsonDir ./json --outdir ./docs
+```
+
+## List available GIR modules
+
+```
 ts-for-gir list [modules..]
 
 Lists all available GIR modules
@@ -150,38 +243,102 @@ Lists all available GIR modules
 Options:
       --version         Show version number                            [boolean]
       --help            Show help                                      [boolean]
-      --modules         GIR modules to load, e.g. 'Gio-2.0'. Accepts multiple mo
-                        dules                           [array] [default: ["*"]]
-  -g, --girDirectories  GIR directories
-  [array] [default: ["/usr/local/share/gir-1.0","/usr/share/gir-1.0","/usr/share
-  /gnome-shell","/usr/share/gnome-shell/gir-1.0","/usr/lib64/mutter-10","/usr/li
-  b64/mutter-11","/usr/lib64/mutter-12","/usr/lib/x86_64-linux-gnu/mutter-10","/
-  usr/lib/x86_64-linux-gnu/mutter-11","/usr/lib/x86_64-linux-gnu/mutter-12","/ho
-  me/jumplink/.local/share/flatpak/exports/share/gir-1.0","/var/lib/flatpak/expo
-                                                            rts/share/gir-1.0"]]
+      --modules         GIR modules to load, e.g. 'Gio-2.0'. Accepts
+                        multiple modules                [array] [default: ["*"]]
+  -g, --girDirectories  GIR directories                                  [array]
+      --root            Root directory of your project                   [string]
   -i, --ignore          Modules that should be ignored     [array] [default: []]
-      --configName      Name of the config if you want to use a different name
+      --configName      Specify a custom name for the configuration file
                                           [string] [default: ".ts-for-girrc.js"]
-  -v, --verbose         Switch on/off the verbose mode [string] [default: false]
+  -v, --verbose         Switch on/off the verbose mode [boolean] [default: false]
 
 Examples:
-  ts-for-gir list -g ./vala-girs/gir-1.0    Lists all available GIR modules in .
-                                            /vala-girs/gir-1.0
-  ts-for-gir list --ignore=Gtk-3.0 xrandr-  Lists all available GIR modules in /
-  1.3                                       usr/share/gir-1.0 but not Gtk-3.0 an
-                                            d xrandr-1.3
+  ts-for-gir list -g ./vala-girs/gir-1.0             Lists all available GIR
+                                                      modules in
+                                                      ./vala-girs/gir-1.0
+  ts-for-gir list --ignore=Gtk-3.0 xrandr-1.3        Lists all available GIR
+                                                      modules but not Gtk-3.0
+                                                      and xrandr-1.3
 ```
 
-## Generate HTML documentation
+## Copy GIR files
 
-```bash
-$ ts-for-gir doc --help
+```
+ts-for-gir copy [modules..]
 
-ts-for-gir doc [modules..]
+Scan for *.gir files and copy them to a new directory
 
-The HTML documentation generator is not yet implemented, but feel free to implem
-ent it 🤗
+Options:
+      --version         Show version number                            [boolean]
+      --help            Show help                                      [boolean]
+      --modules         GIR modules to load, e.g. 'Gio-2.0'. Accepts
+                        multiple modules                [array] [default: ["*"]]
+  -g, --girDirectories  GIR directories                                  [array]
+      --root            Root directory of your project                   [string]
+  -o, --outdir          Directory to output to            [string] [default: "./@types"]
+  -i, --ignore          Modules that should be ignored     [array] [default: []]
+      --configName      Specify a custom name for the configuration file
+                                          [string] [default: ".ts-for-girrc.js"]
+  -v, --verbose         Switch on/off the verbose mode [boolean] [default: false]
+
+Examples:
+  ts-for-gir copy -o ./gir                            Copy found *.gir files to
+                                                      ./gir
+  ts-for-gir copy -g /usr/share/gir-1.0               Copy all found *.gir files
+      --ignore=Gtk-3.0 xrandr-1.3 -o ./gir            excluding Gtk-3.0 and
+                                                      xrandr-1.3 to ./gir
+```
+
+## Analyze report files
+
+```
+ts-for-gir analyze [options]
+
+Analyze report files generated by ts-for-gir reporter
+
+Options:
+      --version      Show version number                               [boolean]
+      --help         Show help                                         [boolean]
+  -f, --reportFile   Path to the report file to analyze     [string] [required]
+  -s, --severity     Filter by problem severity
+                     (debug, info, warning, error, critical)             [array]
+  -c, --category     Filter by problem category                         [array]
+  -n, --namespace    Filter by namespace/module                         [array]
+  -t, --type         Filter by specific type name                       [array]
+      --search       Search for text in messages, details, or type names
+                                                                        [string]
+      --since        Filter problems since date/time (ISO format)       [string]
+      --until        Filter problems until date/time (ISO format)       [string]
+      --top          Show top N most problematic items       [number] [default: 10]
+      --format       Output format (table, json, csv)
+                                                    [string] [default: "table"]
+  -e, --export       Export filtered results to file                    [string]
+  -d, --detailed     Show detailed problem information [boolean] [default: false]
+      --summary      Show summary statistics only      [boolean] [default: false]
+  -v, --verbose      Enable verbose output             [boolean] [default: false]
+
+Examples:
+  ts-for-gir analyze -f ./ts-for-gir-report.json
+                                            Show summary statistics of the report
+  ts-for-gir analyze -f ./report.json --severity error critical
+                                            Show only critical and error problems
+  ts-for-gir analyze -f ./report.json --category type_resolution --format table
+                                            Show type resolution problems
+  ts-for-gir analyze -f ./report.json --namespace Gtk --top 10
+                                            Show top 10 problems in Gtk namespace
+  ts-for-gir analyze -f ./report.json --search "Unable to resolve" --export errors.json
+                                            Export unresolved type errors to file
 ```
+
+The `analyze` command helps debug type generation issues by providing powerful filtering and analysis capabilities for ts-for-gir report files.
+
+**Key Features:**
+- **Comprehensive Filtering**: Filter by severity, category, namespace, type name, or search text
+- **Multiple Output Formats**: Table, JSON, or CSV format for different use cases
+- **Statistical Analysis**: Show most problematic types, namespaces, and categories
+- **Export Capabilities**: Save filtered results for further analysis
+- **Time-based Filtering**: Analyze problems within specific time ranges
+
 ## Config
 
 In addition to the option of passing options as a CLI flag, you can also write them in a config file.
@@ -190,27 +347,38 @@ To do that, create a new config file called `.ts-for-girrc.js` in your project r
 ```js
 // or on CommonJs: exports.default = {
 export default {
-  print: false,
   verbose: true,
-  environments: ['gjs', 'node'],
   outdir: '@types',
   girDirectories: ['/usr/share/gir-1.0'],
   modules: ['*'],
   ignore: [],
-  noNamespace: false,
-  buildType: 'lib',
-  moduleType: 'esm'
 }
 ```
 
 The javascript config files must also be in ESM format if you are inside a ESM Package, this is the case if `"type": "module"` is defined in your package.json. Alternatively, the file can be saved in json format, then it works in both cases.
 
-You can pass the config file name to the CLI using [configName](#configName).
+You can pass the config file name to the CLI using [configName](#configname).
+
+### Doc-specific config
+
+For documentation generation, you can configure doc-specific options in the config file:
+
+```js
+export default {
+  modules: ['Gtk-4.0', 'Gdk-4.0', 'Gio-2.0', 'GLib-2.0', 'GObject-2.0'],
+  outdir: './docs',
+  merge: true,
+  jsonDir: './json',
+  readme: './DOC.md',
+  verbose: true,
+  sourceLinkTemplate: 'https://github.com/user/repo/blob/main/{path}#L{line}',
+}
+```
 
 ## Options
 
 ### girDirectories
-Directories in which `*.gir` files are to be searched for. Default is `["/usr/share/gir-1.0"]`. More than one can be specified. If you want to generate the types for the GNOME Shell you have to search in several folders for the corresponding types: 
+Directories in which `*.gir` files are to be searched for. Default is `["/usr/share/gir-1.0"]`. More than one can be specified. If you want to generate the types for the GNOME Shell you have to search in several folders for the corresponding types:
 ```js
 girDirectories: [
   // General gir files
@@ -229,7 +397,7 @@ girDirectories: [
 ```
 
 ### outdir
-The `outdir` option is used to specify the name of the directory where the generated TypeScript types should be saved. The default value of the `outdir` option is `"./@types"`.
+The `outdir` option is used to specify the name of the directory where the generated TypeScript types should be saved. The default value of the `outdir` option is `"./@types"` for `generate` and `"./docs"` for `doc`.
 
 Here is an example of how you can use the outdir option in the CLI of `ts-for-gir`:
 
@@ -241,97 +409,23 @@ In this example, the generated TypeScript types will be saved in the `./types` d
 
 It is important to note that the outdir option should be a valid directory path, and `ts-for-gir` will create the directory if it does not exist. If the specified directory already contains files, `ts-for-gir` will overwrite the existing files with the newly generated types.
 
-### environments
-The `environments` option allows you to specify the JavaScript environment for which you want to generate the TypeScript type definitions. The available values are `"gjs"` and `"node"`. You can also specify both environments.
-
-The default value for this option is `"gjs"`.
-
-To specify the environments option when running ts-for-gir, you would add the `--environments` or `-e` flag, followed by a comma-separated list of values. For example:
-
-```bash
-ts-for-gir generate * --environments gjs node
-```
-
-This option is useful if you want to generate type definitions for use in different JavaScript environments, such as in a `GJS` application or in a `Node.js` application using [node-gtk](https://github.com/romgrk/node-gtk). By specifying the appropriate environment, ts-for-gir can generate type definitions that are optimized for that environment, ensuring that your code will be type-checked correctly and you will receive meaningful error messages in your development environment.
-
 ### ignore
 The `ignore` CLI option allows you to specify modules that should be ignored when generating TypeScript types. This can be useful if you have multiple versions of a library installed but only want to generate types for one of them.
 
 To use the ignore option, pass one or more module names as arguments. For example, to ignore the `Gtk-3.0` module, you would use the following command:
 
 ```bash
-ts-for-gir generate Gtk-* --ignore Gtk-3.0
+ts-for-gir generate Gtk-* --ignore */Gtk-3.0
 ```
 
 You can also ignore multiple modules:
 
 ```bash
-ts-for-gir generate * --ignore Gtk-2.0 Gtk-3.0 Gtk-4.0
+ts-for-gir generate * --ignore */Gtk-2.0 */Gtk-3.0 */Gtk-4.0
 ```
 
 Note that ignoring a module will prevent ts-for-gir from generating types for that module and any submodules that it might contain.
 
-### buildType
-`ts-for-gir` supports two build types for generating the types: `"lib"` and `"types"`.
-
-* If `"lib"` is specified, `.js` files are generated as well as `.d.ts`, this is useful for some bundlers that expect a `.js` file. Some bundlers are also able to generate the import of this file only once, even if it occurs multiple times in your code.
-* If `"types"` is specified, only `.d.ts` files are generated. In this mode it is recommended to add the generated `"@types/gjs.d.ts"` and `"@types/ambient.d.ts"` under `"include"` in the `tsconfig` to make the generated types known in your project.
-
-### moduleType
-The `moduleType` CLI option determines the format in which the generated JavaScript files should be exported. The option takes either `"esm"` or `"cjs"` as its value, with `"esm"` being the default.
-
-> This option is only relevant if the `buildType` is set to `"lib"`. The choice of `moduleType` may affect how the generated code is used in other parts of your project, so it's important to choose the right format that works best for your use case.
-
-The choice of `moduleType` is also important in the context of the bundler that you plan to use in your project. For example, if you are using a bundler that only supports ESM (such as Rollup), you would need to set `moduleType` to "esm". On the other hand, if you are using a bundler that supports both ESM and CommonJS (such as Webpack), you can choose whichever format you prefer. Ultimately, the choice of `moduleType` will depend on your project requirements and the tools that you are using. For Example, if you want to build a GNOME Shell Extension, you should use `"cjs"` because `ESM` is currently not supported for GNOME Shell Extensions. For [node-gtk](https://github.com/romgrk/node-gtk) you also need to use `"cjs"`. If you want to build a regular GJS Application we recommend to use `ESM`.
-
-When `"esm"` is set, the generated JavaScript files will use the ECMAScript module (ESM) format for imports and exports. For example, the generated code might look like this:
-
-```ts
-// Gtk-4.0.d.ts
-import type GLib from './GLib-2.0.js';
-
-namespace Gtk {
-  class Window extends Widget {
-    ...
-  }
-  function builder_error_quark(): GLib.Quark
-}
-
-export default Gtk;
-```
-
-```js
-// Gtk-4.0.js
-import Gtk from 'gi://Gtk?version=4.0';
-export default Gtk;
-```
-
-> The `"esm"` module type is recommended for GJS applications as it makes use of the ESM import syntax, which is more modern and flexible compared to imports.gi / CommonJS imports. This allows for a more streamlined and convenient way of using the generated types in your GJS application. Support for ES modules can be activated in `gjs` with its `gjs -m` flag.
-
-When `"cjs"` and [`noNamespace`](#nonamespace) is set, the generated JavaScript files will use the CommonJS format exports and the `imports.gi` object for imports. For example:
-
-```ts
-// Gtk-4.0.d.ts
-import type * as GLib from './GLib-2.0.js';
-
-export class Window extends Widget {
-  ...
-}
-export function builder_error_quark(): GLib.Quark
-```
-
-```js
-// Gtk-4.0.js
-imports.gi.versions.Gtk = '4.0'
-const Gtk = imports.gi.Gtk;
-  
-module.exports = { Gtk };
-exports.default = Gtk;
-```
-
-> It is recommended to also set the [noNamespace](#nonamespace) option to true when using the `"cjs"` moduleType option. This will ensure that the generated code is fully compatible with the CommonJS format.
-
-
 ### verbose
 The `--verbose` or `-v` option is a flag that can be used to enable verbose output in the console when running the CLI. When this option is enabled, additional warnings and information about the processing of GIR files and the generation of TypeScript definitions will be printed to the console. This information can be useful for debugging purposes or for understanding what is happening behind the scenes when generating the TypeScript definitions.
 
@@ -340,7 +434,7 @@ The `ignoreVersionConflicts` CLI option allows you to disable the prompt to choo
 
 This option can be useful in certain scenarios where you want to generate types for all versions of a library, even if there are conflicts between the versions. Note that this may result in type conflicts and other issues, so it should be used with caution.
 
-Another way to disable the prompt and ignore conflicting versions of `.gir` files is to use the [ignore CLI option](#ignore). 
+Another way to disable the prompt and ignore conflicting versions of `.gir` files is to use the [ignore CLI option](#ignore).
 
 ### print
 The `print` CLI option allows you to output the generated TypeScript definitions to the console, instead of saving them to files on disk. This is useful if you want to quickly inspect the generated types without having to save them to disk and open them in an editor.
@@ -350,7 +444,7 @@ By default, the print option is disabled and the generated types will be saved t
 ### configName
 The `configName` CLI option allows you to specify the name of the configuration file to be used when generating the TypeScript definitions. This option is useful if you want to use a custom configuration file instead of the default one.
 
-By default,` ts-for-gir` looks for a configuration file named `.ts-for-girrc.js` in the current directory. If a different configuration file name is required, the `configName` option can be used to specify the name of the configuration file.
+By default, `ts-for-gir` looks for a configuration file named `.ts-for-girrc.js` in the current directory. If a different configuration file name is required, the `configName` option can be used to specify the name of the configuration file.
 
 For example, if you have a configuration file named `custom-config.js`, you can use the following command to generate TypeScript definitions using this configuration file:
 
@@ -374,20 +468,24 @@ When `noComments` is set to `true`, `ts-for-gir` will not include TSDoc comments
 To use the noComments option, pass it as a command line argument to `ts-for-gir`:
 
 ```bash
-ts-for-gir generate * --noComments`
+ts-for-gir generate * --noComments
 ```
 
-### noDebugComments
-The `noDebugComments` CLI option is used to control the generation of inline comments in the generated TypeScript files. These comments are used for debugging purposes and can be useful in tracking down issues with the generated types.
+### noPrettyPrint
+The `noPrettyPrint` option controls whether the generated TypeScript definitions are formatted using Prettier. When set to `true`, the output will not be formatted, which can be useful for debugging or in cases where you want to handle formatting separately.
 
-By default, the `noDebugComments` option is disabled and these inline comments will be included in the generated TypeScript files. If you do not require these comments for debugging purposes, you can use the -`-noDebugComments` option to disable their generation and keep your TypeScript code more compact.
+```bash
+ts-for-gir generate * --noPrettyPrint
+```
 
-### fixConflicts
-The `fixConflicts` CLI option is used to resolve type conflicts between the GObject Introspection descriptions in GIR XML format and TypeScript. For example, properties in the GIR XML format can be overwritten by methods, which is not allowed in TypeScript. When this option is active, `ts-for-gir` attempts to resolve these conflicts. However, it's important to note that this may result in generating types that do not exist.
+### noAdvancedVariants
+The `noAdvancedVariants` option disables the advanced GLib.Variant class with string parsing capabilities. This option is enabled by default (`false`) as these advanced features can impact performance, especially with older TypeScript versions.
 
-> If you have found an issue with the `fixConflicts` CLI option, we encourage you to report it. Reporting issues helps improve the quality of `ts-for-gir` and makes it a better tool for everyone.
+```bash
+ts-for-gir generate * --noAdvancedVariants=false
+```
 
-# package
+### package
 
 The `--package` option of ts-for-gir is used to package the generated TypeScript type definitions into an NPM package. The generated package can be easily installed and used in other TypeScript projects via `npm install`.
 
@@ -395,14 +493,14 @@ The `--package` option of ts-for-gir is used to package the generated TypeScript
 
 When this option is used, each GObject introspection module will be packaged into its own NPM package. The package name will be in the format of `@girs/<lower case module name>-<version>`.
 
-For example, if the `--package` option is used to generate the TypeScript type definitions for the `Gtk-4.0` module, then the generated NPM package will have the name `@girs/gtk-3.0`.
+For example, if the `--package` option is used to generate the TypeScript type definitions for the `Gtk-4.0` module, then the generated NPM package will have the name `@girs/gtk-4.0`.
 
 > You can change the NPM package scope name with the [`--npmScope`](#npmscope) option.
 
 To use the generated NPM package in your TypeScript project, you can also install our pregenerated packages:
 
 ```bash
-npm install @girs/gtk-3.0
+npm install @girs/gtk-4.0
 ```
 
 Then, import the desired module in your TypeScript code:
@@ -426,10 +524,10 @@ The `--npmScope` CLI option can be used to specify a custom NPM package scope na
 Here's an example command to generate NPM packages with a custom scope name:
 
 ```bash
-ts-for-gir --buildType lib --package --npmScope my-scope
+ts-for-gir generate * --package --npmScope my-scope
 ```
 
-This command will generate NPM packages with the scope `my-scope` instead of the default `@girs` scope. For `Gtk-4.0` this would generate a package with the name of `@my-scope/gtk-4.0`.
+This command will generate NPM packages with the scope `@my-scope` instead of the default `@girs` scope. For `Gtk-4.0` this would generate a package with the name of `@my-scope/gtk-4.0`.
 
 ## Ambient modules
 
@@ -445,7 +543,7 @@ To use ambient modules, the `ambient.d.ts` file must be imported either in the c
 ```json
 // tsconfig.json
 {
-  "compilerOptions": {   
+  "compilerOptions": {
     "lib": ["ESNext"],
     "types": [],
     "target": "ESNext",
@@ -473,4 +571,20 @@ declare module "gi://Gtk" {
   import Gtk from "gi://Gtk?version=4.0";
   export default Gtk;
 }
-```
+```
+
+## reporter
+
+The `--reporter` option enables the generation of a problem reporter and creates a detailed report file.
+
+```bash
+ts-for-gir generate * --reporter
+```
+
+## reporterOutput
+
+The `--reporterOutput` option specifies the output file path for the reporter. The default value is `ts-for-gir-report.json`.
+
+```bash
+ts-for-gir generate * --reporterOutput custom-report.json
+```