@ts-for-gir/cli 4.0.0-beta.9 → 4.0.0-rc.1

package/README.md

@@ -18,7 +18,7 @@
 
 # CLI
 
-CLI tool to generate Typescript Type Definition files for GJS.
+CLI tool to generate TypeScript type definitions and HTML documentation for GObject Introspection Repository (GIR) files, primarily for GJS applications.
 
 ## Getting started
 
@@ -37,18 +37,16 @@ npx @ts-for-gir/cli --help
 > ts-for-gir --help
 > ```
 
-```bash
-$ npx @ts-for-gir/cli --help
-
+```
 TypeScript type definition generator for GObject introspection GIR files
 
 Commands:
   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 copy [modules..]      Scan for *.gir files and copy them to a new d
-                                   irectory
-  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]
@@ -57,19 +55,17 @@ Options:
 
 ## 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
 ```
 
-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
-$ npx @ts-for-gir/cli generate --help
-
+```
 ts-for-gir generate [modules..]
 
 Generates .d.ts files from GIR for GJS
@@ -77,65 +73,169 @@ 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
-  /*/gir-1.0","/usr/share/gnome-shell","/usr/share/gnome-shell/gir-1.0","/usr/li
-        b64/mutter-*","/usr/lib/mutter-*","/usr/lib/x86_64-linux-gnu/mutter-*"]]
-      --root                    Root directory of your project
-                 [string] [default: "/home/jumplink/Projekte/gjsify/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]
+                                                      [boolean] [default: false]
       --ignoreVersionConflicts  Skip prompts for library version selection when
                                 multiple versions are detected
-                                                       [string] [default: false]
+                                                      [boolean] [default: false]
   -p, --print                   Print the output to console and create no files
-                                                       [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 n
-                                amespace               [string] [default: false]
+  -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]
+                                                      [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 pa
-                                ckages which can be used with package managers l
-                                ike Yarn and PNPM      [string] [default: false]
-      --onlyVersionPrefix       Only use the version prefix for the ambient modu
-                                le exports. This is useful if, for whatever reas
-                                on, you want to use different library versions o
-                                f the same library in your project.
-                                                       [string] [default: false]
+      --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                [string] [default: false]
+                                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 project to generate typings for yo
-                                            ur 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 --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
-$ npx @ts-for-gir/cli 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
@@ -143,37 +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
-  /*/gir-1.0","/usr/share/gnome-shell","/usr/share/gnome-shell/gir-1.0","/usr/li
-        b64/mutter-*","/usr/lib/mutter-*","/usr/lib/x86_64-linux-gnu/mutter-*"]]
-      --root            Root directory of your project
-                 [string] [default: "/home/jumplink/Projekte/gjsify/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]
   -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 [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
-$ npx @ts-for-gir/cli doc --help
+```
+ts-for-gir copy [modules..]
 
-ts-for-gir doc [modules..]
+Scan for *.gir files and copy them to a new directory
+
+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]
 
-The HTML documentation generator is not yet implemented, but feel free to implem
-ent it 🤗
+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.
@@ -192,12 +357,28 @@ export default {
 
 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
@@ -216,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`:
 
@@ -253,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.
@@ -263,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:
 
@@ -287,10 +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
 ```
 
-# package
+### 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.
+
+```bash
+ts-for-gir generate * --noPrettyPrint
+```
+
+### 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.
+
+```bash
+ts-for-gir generate * --noAdvancedVariants=false
+```
+
+### 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`.
 
@@ -298,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:
@@ -329,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
 
@@ -348,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",
@@ -376,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
+```