@ts-for-gir/cli 4.0.0-beta.25 → 4.0.0-beta.27

package/README.md

@@ -45,6 +45,7 @@ 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 list [modules..]      Lists all available GIR modules
+  ts-for-gir analyze               Analyze report files generated by ts-for-gir reporter
   ts-for-gir copy [modules..]      Scan for *.gir files and copy them to a new directory
   ts-for-gir doc [modules..]       The HTML documentation generator is not yet implemented, but feel free to implement it 🤗
 
@@ -111,9 +112,14 @@ Options:
       --noPrettyPrint           Do not prettify the generated types
                                                       [boolean] [default: false]
       --noAdvancedVariants      Disable GLib.Variant class with string parsing
-                                                       [boolean] [default: true]
+                                                       [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 (default: 
+                                ts-for-gir-report.json)
+                                           [string] [default: "ts-for-gir-report.json"]
 
 Examples:
   ts-for-gir generate                       Run 'ts-for-gir generate' in your gjs
@@ -155,6 +161,66 @@ Examples:
   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
 ```
 
+## Analyze report files
+
+```bash
+$ npx @ts-for-gir/cli analyze --help
+
+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]
+      --severity     Filter by problem severity (debug, info, warning, error, critical)
+                                                                          [array]
+      --category     Filter by problem category                         [array]
+      --namespace    Filter by namespace/module                        [array]
+      --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]
+      --format       Output format (table, json, summary)
+                                                  [string] [default: "summary"]
+      --export       Export filtered results to file                  [string]
+      --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 in table format
+  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
+  ts-for-gir analyze -f ./report.json --type time_t --format json
+                                            Analyze specific type problems in JSON format
+```
+
+The `analyze` command is designed to help developers and AI agents efficiently 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 summary 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
+- **AI-Friendly**: Structured output perfect for automated analysis and debugging
+
+**Common Use Cases:**
+- Debug type resolution failures for specific libraries
+- Identify patterns in generation problems across modules
+- Export specific error categories for detailed analysis
+- Monitor type generation quality over time
+- Automated problem detection in CI/CD pipelines
+
 ## Generate HTML documentation
 
 ```bash
@@ -310,7 +376,7 @@ 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 (`true`) as these advanced features can impact performance, especially with older TypeScript versions.
+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
@@ -402,4 +468,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
 ```

package/bin/ts-for-gir-dev.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+/**
+ * CLI Wrapper for TypeScript Execution
+ * 
+ * This wrapper is required to execute our CLI tool with the necessary Node.js parameters.
+ * Due to "type": "module" specified in package.json, Node.js only accepts .js files 
+ * and rejects .ts or .sh files directly. This wrapper bridges that gap by:
+ * 
+ * 1. Providing a .js entry point that Node.js can execute
+ * 2. Spawning the actual TypeScript file with experimental Node.js flags
+ * 3. Enabling TypeScript execution without compilation step
+ * 
+ * The experimental flags used:
+ * - --experimental-specifier-resolution=node: Enables Node.js-style module resolution
+ * - --experimental-strip-types: Strips TypeScript types during execution
+ * - --experimental-transform-types: Transforms TypeScript syntax to JavaScript
+ * - --no-warnings: Suppresses experimental feature warnings
+ */
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+// Get the current file's directory in ES module context
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Resolve the path to the actual TypeScript CLI entry point
+const tsPath = resolve(__dirname, '../src/start.ts');
+
+// Configure Node.js arguments for TypeScript execution
+const nodeArgs = [
+  '--experimental-specifier-resolution=node',
+  '--experimental-strip-types',
+  '--experimental-transform-types',
+  '--no-warnings',
+  tsPath,
+  ...process.argv.slice(2), // Forward all CLI arguments to the TypeScript file
+];
+
+// Spawn the Node.js process with TypeScript support and inherit stdio
+spawn('node', nodeArgs, { stdio: 'inherit' });