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

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.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' });

package/package.json

@@ -1,26 +1,21 @@
 {
   "name": "@ts-for-gir/cli",
-  "version": "4.0.0-beta.25",
+  "version": "4.0.0-beta.26",
   "description": "TypeScript type definition generator for GObject introspection GIR files",
-  "module": "lib/index.js",
-  "main": "lib/index.js",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
   "type": "module",
   "bin": {
-    "ts-for-gir": "./lib/start.js"
+    "ts-for-gir": "bin/ts-for-gir.js"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22.7.0"
   },
   "scripts": {
-    "start": "yarn node --max_old_space_size=9216 lib/start.js",
-    "start:dev": "yarn node --max_old_space_size=9216 --loader ts-node/esm src/start.ts",
-    "build": "yarn lint && yarn build:ts && yarn chmod",
-    "chmod": "chmod +x ./lib/start.js",
-    "build:ts": "tsc",
-    "clear": "yarn clear:build",
-    "clear:build": "rimraf ./lib",
-    "watch": "yarn build:ts --watch",
-    "lint": "eslint . --fix"
+    "start": "node --experimental-specifier-resolution=node --experimental-strip-types --experimental-transform-types --no-warnings src/start.ts",
+    "check:types": "tsc --noEmit",
+    "check:deps": "dpdm -T src/index.ts",
+    "check": "yarn check:types && yarn check:deps"
   },
   "repository": {
     "type": "git",
@@ -28,10 +23,7 @@
   },
   "author": "Pascal Garber <pascal@artandcode.studio>",
   "files": [
-    "src",
-    "bin",
-    "lib",
-    "templates"
+    "src"
   ],
   "license": "Apache-2.0",
   "bugs": {
@@ -52,31 +44,33 @@
     "type definitions",
     "cli"
   ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
   "devDependencies": {
-    "@types/inquirer": "^9.0.8",
-    "@types/node": "^24.0.1",
+    "@types/ejs": "^3.1.5",
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^24.2.1",
     "@types/yargs": "^17.0.33",
-    "@typescript-eslint/eslint-plugin": "^8.34.0",
-    "@typescript-eslint/parser": "^8.34.0",
-    "eslint": "^9.29.0",
-    "eslint-config-prettier": "^10.1.5",
-    "eslint-plugin-prettier": "^5.4.1",
-    "rimraf": "^6.0.1",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.8.3"
+    "dpdm": "^3.14.0",
+    "typescript": "^5.9.2"
   },
   "dependencies": {
-    "@gi.ts/parser": "^4.0.0-beta.25",
-    "@inquirer/prompts": "^7.5.3",
-    "@ts-for-gir/generator-base": "^4.0.0-beta.25",
-    "@ts-for-gir/generator-html-doc": "^4.0.0-beta.25",
-    "@ts-for-gir/generator-typescript": "^4.0.0-beta.25",
-    "@ts-for-gir/lib": "^4.0.0-beta.25",
+    "@gi.ts/parser": "^4.0.0-beta.26",
+    "@inquirer/prompts": "^7.8.2",
+    "@ts-for-gir/generator-base": "^4.0.0-beta.26",
+    "@ts-for-gir/generator-html-doc": "^4.0.0-beta.26",
+    "@ts-for-gir/generator-json": "^4.0.0-beta.26",
+    "@ts-for-gir/generator-typescript": "^4.0.0-beta.26",
+    "@ts-for-gir/lib": "^4.0.0-beta.26",
+    "@ts-for-gir/reporter": "^4.0.0-beta.26",
+    "@ts-for-gir/templates": "^4.0.0-beta.26",
     "colorette": "^2.0.20",
     "cosmiconfig": "^9.0.0",
+    "ejs": "^3.1.10",
     "glob": "^11.0.3",
-    "inquirer": "^12.6.3",
-    "prettier": "^3.5.3",
+    "inquirer": "^12.9.2",
+    "prettier": "^3.6.2",
     "yargs": "^18.0.0"
   }
 }

package/src/commands/analyze.ts

@@ -0,0 +1,344 @@
+/**
+ * Everything you need for the `ts-for-gir analyze` command is located here
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { APP_NAME, Logger } from "@ts-for-gir/lib";
+import type { ProblemEntry } from "@ts-for-gir/reporter";
+import { analyzeOptions } from "../config.ts";
+import type { AnalyzeCommandArgs, ReportData } from "../types/index.ts";
+import { createBuilder } from "./command-builder.ts";
+
+const command = "analyze [options]";
+
+const description = "Analyze report files generated by ts-for-gir reporter";
+
+const examples: ReadonlyArray<[string, string?]> = [
+	[`${APP_NAME} analyze -f ./ts-for-gir-report.json`, "Show summary statistics of the report"],
+	[`${APP_NAME} analyze -f ./ts-for-gir-report.json --summary`, "Show only summary statistics"],
+	[`${APP_NAME} analyze -f ./ts-for-gir-report.json --severity error critical`, "Show only errors and critical issues"],
+	[
+		`${APP_NAME} analyze -f ./ts-for-gir-report.json --category type_resolution --detailed`,
+		"Show detailed type resolution problems",
+	],
+	[`${APP_NAME} analyze -f ./ts-for-gir-report.json --namespace GLib --top 5`, "Show top 5 problems in GLib namespace"],
+	[
+		`${APP_NAME} analyze -f ./ts-for-gir-report.json --type time_t --export ./time_t_issues.json`,
+		"Export all time_t related issues",
+	],
+	[
+		`${APP_NAME} analyze -f ./ts-for-gir-report.json --search "Unable to resolve" --format csv`,
+		"Search for resolution failures and export as CSV",
+	],
+];
+
+const builder = createBuilder<AnalyzeCommandArgs>(analyzeOptions, examples);
+
+const parseReportDate = (dateValue: string | Date): Date => {
+	return typeof dateValue === "string" ? new Date(dateValue) : dateValue;
+};
+
+const loadReportFile = (filePath: string): ReportData => {
+	if (!existsSync(filePath)) {
+		throw new Error(`Report file not found: ${filePath}`);
+	}
+
+	try {
+		const content = readFileSync(filePath, "utf-8");
+		const report = JSON.parse(content) as ReportData;
+
+		// Convert string dates to Date objects
+		report.metadata.generatedAt = parseReportDate(report.metadata.generatedAt);
+		report.statistics.startTime = parseReportDate(report.statistics.startTime);
+
+		if (report.statistics.endTime) {
+			report.statistics.endTime = parseReportDate(report.statistics.endTime);
+		}
+
+		// Convert problem timestamps
+		report.problems = report.problems.map((problem) => ({
+			...problem,
+			timestamp: parseReportDate(problem.timestamp),
+		}));
+
+		return report;
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : "Unknown error";
+		throw new Error(`Failed to parse report file: ${errorMessage}`);
+	}
+};
+
+const filterProblems = (problems: ProblemEntry[], args: AnalyzeCommandArgs): ProblemEntry[] => {
+	let filtered = [...problems];
+
+	// Filter by severity
+	if (args.severity?.length) {
+		filtered = filtered.filter((p) => args.severity?.includes(p.severity));
+	}
+
+	// Filter by category
+	if (args.category?.length) {
+		filtered = filtered.filter((p) => args.category?.includes(p.category));
+	}
+
+	// Filter by namespace
+	if (args.namespace?.length) {
+		filtered = filtered.filter((p) =>
+			args.namespace?.some((ns) => p.location?.includes(ns) || p.module?.includes(ns) || p.metadata?.namespace === ns),
+		);
+	}
+
+	// Filter by type name
+	if (args.type?.length) {
+		filtered = filtered.filter((p) => Boolean(p.typeName && args.type?.includes(p.typeName)));
+	}
+
+	// Search filter
+	if (args.search) {
+		const searchLower = args.search.toLowerCase();
+		filtered = filtered.filter(
+			(p) =>
+				p.message.toLowerCase().includes(searchLower) ||
+				p.details?.toLowerCase().includes(searchLower) ||
+				p.typeName?.toLowerCase().includes(searchLower),
+		);
+	}
+
+	// Time range filters
+	if (args.since) {
+		const sinceDate = new Date(args.since);
+		filtered = filtered.filter((p) => p.timestamp >= sinceDate);
+	}
+
+	if (args.until) {
+		const untilDate = new Date(args.until);
+		filtered = filtered.filter((p) => p.timestamp <= untilDate);
+	}
+
+	return filtered;
+};
+
+const displaySummary = (report: ReportData, args: AnalyzeCommandArgs): void => {
+	const { statistics } = report;
+
+	console.log("📊 Report Summary\n");
+
+	// Basic info
+	console.log(`Generated: ${report.metadata.generatedAt}`);
+	console.log(`Version: ${report.metadata.version}`);
+	console.log(`Total Problems: ${statistics.totalProblems}`);
+
+	if (statistics.durationMs) {
+		console.log(`Generation Duration: ${(statistics.durationMs / 1000).toFixed(2)}s`);
+	}
+
+	// Problems by severity
+	console.log("\n🔴 Problems by Severity:");
+	Object.entries(statistics.bySeverity)
+		.filter(([, count]) => count > 0)
+		.sort(([, a], [, b]) => b - a)
+		.forEach(([severity, count]) => {
+			console.log(`  ${severity}: ${count}`);
+		});
+
+	// Problems by category
+	console.log("\n📂 Problems by Category:");
+	Object.entries(statistics.byCategory)
+		.filter(([, count]) => count > 0)
+		.sort(([, a], [, b]) => b - a)
+		.forEach(([category, count]) => {
+			console.log(`  ${category}: ${count}`);
+		});
+
+	// Top problematic namespaces
+	if (statistics.typeStatistics.problematicNamespaces.length > 0) {
+		console.log("\n🏢 Most Problematic Namespaces:");
+		const topCount = args.top ?? 10;
+		statistics.typeStatistics.problematicNamespaces.slice(0, topCount).forEach((ns) => {
+			console.log(`  ${ns.namespace}: ${ns.problems} problems`);
+			if (args.detailed) {
+				const typesList = ns.types.slice(0, 5).join(", ");
+				const moreTypes = ns.types.length > 5 ? "..." : "";
+				console.log(`    Types: ${typesList}${moreTypes}`);
+			}
+		});
+	}
+
+	// Common unresolved types
+	if (statistics.typeStatistics.commonUnresolvedTypes.length > 0) {
+		console.log("\n🔍 Most Common Unresolved Types:");
+		const topCount = args.top ?? 10;
+		statistics.typeStatistics.commonUnresolvedTypes.slice(0, topCount).forEach((type) => {
+			console.log(`  ${type.type}: ${type.count} occurrences`);
+			if (args.detailed) {
+				const namespacesList = type.namespaces.slice(0, 3).join(", ");
+				const moreNamespaces = type.namespaces.length > 3 ? "..." : "";
+				console.log(`    Namespaces: ${namespacesList}${moreNamespaces}`);
+			}
+		});
+	}
+};
+
+const displayProblems = (problems: ProblemEntry[], args: AnalyzeCommandArgs): void => {
+	if (problems.length === 0) {
+		console.log("No problems match the specified filters.");
+		return;
+	}
+
+	console.log(`\n🔍 Found ${problems.length} matching problems:\n`);
+
+	problems.forEach((problem, index) => {
+		const message = `${index + 1}. [${problem.severity.toUpperCase()}] ${problem.message}`;
+
+		console.log(message);
+
+		if (args.detailed) {
+			console.log(`   ID: ${problem.id}`);
+			console.log(`   Category: ${problem.category}`);
+			console.log(`   Module: ${problem.module}`);
+			if (problem.typeName) {
+				console.log(`   Type: ${problem.typeName}`);
+			}
+			if (problem.location) {
+				console.log(`   Location: ${problem.location}`);
+			}
+			if (problem.details) {
+				console.log(`   Details: ${problem.details}`);
+			}
+			console.log(`   Timestamp: ${problem.timestamp}`);
+			if (problem.metadata && Object.keys(problem.metadata).length > 0) {
+				console.log(`   Metadata: ${JSON.stringify(problem.metadata)}`);
+			}
+		} else if (problem.typeName) {
+			const location = problem.location ?? "unknown";
+			console.log(`   Type: ${problem.typeName} | Location: ${location}`);
+		}
+
+		if (index < problems.length - 1) {
+			console.log("");
+		}
+	});
+};
+
+const formatAsTable = (problems: ProblemEntry[]): string => {
+	if (problems.length === 0) {
+		return "No problems found.";
+	}
+
+	const headers = ["Severity", "Category", "Module", "Type", "Message"];
+	const rows = problems.map((p) => [
+		p.severity,
+		p.category,
+		p.module ?? "",
+		p.typeName ?? "",
+		p.message.length > 50 ? `${p.message.substring(0, 47)}...` : p.message,
+	]);
+
+	const columnWidths = headers.map((header, i) => Math.max(header.length, ...rows.map((row) => row[i].length)));
+
+	const separator = columnWidths.map((w) => "-".repeat(w)).join(" | ");
+	const headerRow = headers.map((h, i) => h.padEnd(columnWidths[i])).join(" | ");
+	const dataRows = rows.map((row) => row.map((cell, i) => cell.padEnd(columnWidths[i])).join(" | "));
+
+	return [headerRow, separator, ...dataRows].join("\n");
+};
+
+const formatAsCsv = (problems: ProblemEntry[]): string => {
+	const headers = ["id", "severity", "category", "module", "typeName", "location", "message", "details", "timestamp"];
+	const rows = problems.map((p) => [
+		p.id,
+		p.severity,
+		p.category,
+		p.module ?? "",
+		p.typeName ?? "",
+		p.location ?? "",
+		`"${p.message.replace(/"/g, '""')}"`,
+		`"${(p.details ?? "").replace(/"/g, '""')}"`,
+		p.timestamp.toISOString(),
+	]);
+
+	return [headers.join(","), ...rows.map((row) => row.join(","))].join("\n");
+};
+
+const exportResults = (problems: ProblemEntry[], filePath: string, format: string, logger: Logger): void => {
+	let content: string;
+
+	switch (format) {
+		case "json": {
+			content = JSON.stringify(problems, null, 2);
+			break;
+		}
+		case "csv": {
+			content = formatAsCsv(problems);
+			break;
+		}
+		case "table": {
+			content = formatAsTable(problems);
+			break;
+		}
+		default: {
+			throw new Error(`Unsupported export format: ${format}`);
+		}
+	}
+
+	writeFileSync(filePath, content, "utf-8");
+	logger.success(`Results exported to: ${filePath}`);
+};
+
+const handler = async (args: AnalyzeCommandArgs): Promise<void> => {
+	const logger = new Logger(args.verbose ?? false, "AnalyzeCommand");
+
+	try {
+		// Load and parse report file
+		const report = loadReportFile(args.reportFile);
+
+		if (args.verbose) {
+			logger.info(`Loaded report with ${report.problems.length} problems`);
+		}
+
+		// Show summary if requested or if no specific filters are applied
+		const hasFilters = Boolean(args.severity || args.category || args.namespace || args.type || args.search);
+
+		if (args.summary || !hasFilters) {
+			displaySummary(report, args);
+		}
+
+		// If summary-only mode, stop here
+		if (args.summary) {
+			return;
+		}
+
+		// Filter problems based on criteria
+		const filteredProblems = filterProblems(report.problems, args);
+
+		// Display filtered results
+		if (hasFilters || args.detailed) {
+			displayProblems(filteredProblems, args);
+		}
+
+		// Export results if requested
+		if (args.export) {
+			const format = args.format ?? "json";
+			exportResults(filteredProblems, args.export, format, logger);
+		}
+
+		// Show filter summary if filters were applied
+		if (hasFilters && !args.summary) {
+			console.log(
+				`\n📋 Filter Summary: Showing ${filteredProblems.length} of ${report.problems.length} total problems`,
+			);
+		}
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : "Unknown error";
+		logger.error(`Analysis failed: ${errorMessage}`);
+		process.exit(1);
+	}
+};
+
+export const analyze = {
+	command,
+	description,
+	builder,
+	handler,
+	examples,
+};

package/src/commands/command-builder.ts

@@ -0,0 +1,30 @@
+/**
+ * Helper to build yargs commands with common structure
+ */
+
+import type { ConfigFlags } from "@ts-for-gir/lib";
+import type { Argv, BuilderCallback, Options } from "yargs";
+
+export interface CommandDefinition {
+	command: string;
+	description: string;
+	builder: BuilderCallback<unknown, ConfigFlags>;
+	handler: (args: ConfigFlags) => Promise<void>;
+	examples: ReadonlyArray<[string, string?]>;
+}
+
+/**
+ * Creates a builder function for yargs commands
+ */
+export function createBuilder<TArgs>(
+	options: Record<string, Options>,
+	examples: ReadonlyArray<[string, string?]>,
+): BuilderCallback<TArgs, ConfigFlags> {
+	return (yargs: Argv<TArgs>) => {
+		const optionNames = Object.keys(options);
+		for (const optionName of optionNames) {
+			yargs = yargs.option(optionName, options[optionName]);
+		}
+		return yargs.example(examples) as Argv<ConfigFlags>;
+	};
+}