@ts-for-gir/cli 4.0.0-rc.4 → 4.0.0-rc.6

package/dist-templates/types-locally/package.json

@@ -11,7 +11,7 @@
 		"clear": "rm -rf dist @types"
 	},
 	"devDependencies": {
-		"@ts-for-gir/cli": "^4.0.0-rc.4",
+		"@ts-for-gir/cli": "^4.0.0-rc.6",
 		"esbuild": "^0.28.0",
 		"typescript": "^6.0.2"
 	}

package/dist-templates/types-npm/package.json

@@ -14,10 +14,10 @@
 		"typescript": "^6.0.2"
 	},
 	"dependencies": {
-		"@girs/adw-1": "^1.10.0-4.0.0-rc.4",
-		"@girs/gio-2.0": "^2.88.0-4.0.0-rc.4",
-		"@girs/gjs": "^4.0.0-rc.4",
-		"@girs/glib-2.0": "^2.88.0-4.0.0-rc.4",
-		"@girs/gtk-4.0": "^4.23.0-4.0.0-rc.4"
+		"@girs/adw-1": "^1.10.0-4.0.0-rc.5",
+		"@girs/gio-2.0": "^2.88.0-4.0.0-rc.5",
+		"@girs/gjs": "^4.0.0-rc.5",
+		"@girs/glib-2.0": "^2.88.0-4.0.0-rc.5",
+		"@girs/gtk-4.0": "^4.23.0-4.0.0-rc.5"
 	}
 }

package/dist-templates/types-workspace/package.json

@@ -16,7 +16,7 @@
 		"clear": "rm -rf @girs packages/*/dist"
 	},
 	"devDependencies": {
-		"@ts-for-gir/cli": "^4.0.0-rc.4",
+		"@ts-for-gir/cli": "^4.0.0-rc.6",
 		"typescript": "^6.0.2"
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-for-gir/cli",
-  "version": "4.0.0-rc.4",
+  "version": "4.0.0-rc.6",
   "description": "TypeScript type definition generator for GObject introspection GIR files",
   "main": "src/index.ts",
   "module": "src/index.ts",
@@ -55,31 +55,31 @@
     ".": "./src/index.ts"
   },
   "devDependencies": {
-    "@gi.ts/parser": "^4.0.0-rc.4",
-    "@ts-for-gir/generator-base": "^4.0.0-rc.4",
-    "@ts-for-gir/generator-html-doc": "^4.0.0-rc.4",
-    "@ts-for-gir/generator-json": "^4.0.0-rc.4",
-    "@ts-for-gir/generator-typescript": "^4.0.0-rc.4",
-    "@ts-for-gir/lib": "^4.0.0-rc.4",
-    "@ts-for-gir/reporter": "^4.0.0-rc.4",
-    "@ts-for-gir/tsconfig": "^4.0.0-rc.4",
+    "@gi.ts/parser": "^4.0.0-rc.6",
+    "@ts-for-gir/generator-base": "^4.0.0-rc.6",
+    "@ts-for-gir/generator-html-doc": "^4.0.0-rc.6",
+    "@ts-for-gir/generator-json": "^4.0.0-rc.6",
+    "@ts-for-gir/generator-typescript": "^4.0.0-rc.6",
+    "@ts-for-gir/lib": "^4.0.0-rc.6",
+    "@ts-for-gir/reporter": "^4.0.0-rc.6",
+    "@ts-for-gir/tsconfig": "^4.0.0-rc.6",
     "@types/ejs": "^3.1.5",
     "@types/inquirer": "^9.0.9",
-    "@types/node": "^24.12.2",
+    "@types/node": "^25.6.0",
     "@types/yargs": "^17.0.35",
     "esbuild": "^0.28.0",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.3.2",
-    "@ts-for-gir/templates": "^4.0.0-rc.4",
+    "@inquirer/prompts": "^8.4.2",
+    "@ts-for-gir/templates": "^4.0.0-rc.6",
     "colorette": "^2.0.20",
     "cosmiconfig": "^9.0.1",
-    "ejs": "^5.0.1",
+    "ejs": "^5.0.2",
     "glob": "^13.0.6",
-    "inquirer": "^13.3.2",
-    "prettier": "^3.8.1",
-    "typedoc": "^0.28.18",
+    "inquirer": "^13.4.2",
+    "prettier": "^3.8.3",
+    "typedoc": "^0.28.19",
     "yargs": "^18.0.0"
   }
 }

package/src/commands/run-generation-command.ts

@@ -6,6 +6,7 @@ import {
 	Logger,
 	NSRegistry,
 	ReporterService,
+	ResolveType,
 } from "@ts-for-gir/lib";
 import { getOptionsGeneration, load } from "../config.ts";
 import { GenerationHandler } from "../generation-handler.ts";
@@ -45,7 +46,11 @@ export async function runGenerationCommand(args: ConfigFlags, options: Generatio
 
 		moduleLoader.parse(keep);
 
-		const girModules = Array.from(keep).map((girModuleResolvedBy) => girModuleResolvedBy.module as GirModule);
+		// In external-deps mode, only generate the user-requested module(s). Transitively-loaded
+		// deps stay in the registry for type resolution but must not produce their own output.
+		const toGenerate = generateConfig.externalDeps ? keep.filter((m) => m.resolvedBy === ResolveType.BY_HAND) : keep;
+
+		const girModules = Array.from(toGenerate).map((girModuleResolvedBy) => girModuleResolvedBy.module as GirModule);
 
 		await tsForGir.start(girModules);
 	} catch (error) {

package/src/config/config-loader.ts

@@ -59,6 +59,24 @@ export function getOptionsGeneration(config: UserConfig): OptionsGeneration {
 	return generateConfig;
 }
 
+/**
+ * Parse `Namespace=npm-package` strings (from repeatable `--external-package` flag) into a
+ * map. Silently drops entries that don't contain `=`. Empty input returns undefined so the
+ * field stays absent in the merged config (rather than `{}`, which would shadow rc values).
+ */
+function parseExternalPackagePairs(pairs: string[] | undefined): Record<string, string> | undefined {
+	if (!pairs || pairs.length === 0) return undefined;
+	const map: Record<string, string> = {};
+	for (const pair of pairs) {
+		const eq = pair.indexOf("=");
+		if (eq < 1) continue;
+		const ns = pair.slice(0, eq).trim();
+		const pkg = pair.slice(eq + 1).trim();
+		if (ns && pkg) map[ns] = pkg;
+	}
+	return Object.keys(map).length > 0 ? map : undefined;
+}
+
 /**
  * Validate the configuration
  */
@@ -111,9 +129,21 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 	const configFile = await loadConfigFile(cliOptions.configName);
 	const configFileData = configFile?.config || {};
 
+	// `--external-package GLib=@girs/glib-2.0` arrives as a string[]; collapse to Record.
+	// Drop the raw array so it doesn't pollute the merged UserConfig surface.
+	const externalPackagesFromCli = parseExternalPackagePairs(
+		(cliOptions as { externalPackage?: string[] }).externalPackage,
+	);
+	const { externalPackage: _externalPackage, ...cliOptionsClean } = cliOptions as ConfigFlags & {
+		externalPackage?: string[];
+	};
+
 	const userConfig: UserConfig = {
-		...cliOptions,
+		...cliOptionsClean,
 	};
+	if (externalPackagesFromCli) {
+		userConfig.externalPackages = externalPackagesFromCli;
+	}
 
 	if (configFileData) {
 		// Boolean options — config file overrides CLI defaults
@@ -130,6 +160,8 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 			["noAdvancedVariants", options.noAdvancedVariants.default],
 			["package", options.package.default],
 			["reporter", options.reporter.default],
+			["externalDeps", options.externalDeps.default],
+			["allowMissingDeps", options.allowMissingDeps.default],
 			["combined", docOptions.combined.default],
 			["merge", docOptions.merge.default],
 		];
@@ -153,7 +185,6 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 
 		// Array options — config file overrides CLI defaults
 		const arrayKeys: Array<[keyof UserConfig, unknown]> = [
-			["girDirectories", options.girDirectories.default],
 			["ignore", options.ignore.default],
 			["modules", options.modules.default],
 		];
@@ -161,6 +192,18 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 			mergeConfigValue(userConfig, configFileData, key, defaultVal);
 		}
 
+		// girDirectories: rc-file entries are prepended to the current dirs (CLI-provided or
+		// system defaults) rather than replacing them. This lets projects add local GIR dirs
+		// (e.g. a Vala build output) without having to enumerate all system paths in the rc.
+		// To use ONLY the specified dirs (no system fallback), pass --girDirectories on the CLI.
+		if (configFileData.girDirectories?.length) {
+			const current = userConfig.girDirectories as string[];
+			const toAdd = (configFileData.girDirectories as string[]).filter((d) => !current.includes(d));
+			if (toAdd.length > 0) {
+				userConfig.girDirectories = [...toAdd, ...current];
+			}
+		}
+
 		// Special handling for root
 		if (userConfig.root === options.root.default && (configFileData.root || configFile?.filepath)) {
 			userConfig.root =
@@ -172,6 +215,11 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 		if (isDefaultOutdir && configFileData.outdir) {
 			userConfig.outdir = userConfig.print ? null : configFileData.outdir;
 		}
+
+		// externalPackages is a Record<string, string> in rc files; CLI overrides take precedence.
+		if (!externalPackagesFromCli && configFileData.externalPackages) {
+			userConfig.externalPackages = configFileData.externalPackages;
+		}
 	}
 
 	// Make paths absolute relative to root
@@ -186,6 +234,5 @@ export async function load(cliOptions: ConfigFlags): Promise<UserConfig> {
 	if (userConfig.girDirectories) {
 		userConfig.girDirectories = userConfig.girDirectories.map(resolveToRoot);
 	}
-
 	return validate(userConfig);
 }

package/src/config/defaults.ts

@@ -31,6 +31,8 @@ export const defaults = {
 	package: false,
 	reporter: false,
 	reporterOutput: "ts-for-gir-report.json",
+	externalDeps: false,
+	allowMissingDeps: false,
 	combined: true,
 	/** Default theme for `ts-for-gir doc` (HTML documentation). */
 	theme: "gi-docgen",

package/src/config/options.ts

@@ -146,6 +146,26 @@ export const options: { [name: string]: Options } = {
 		default: defaults.reporterOutput,
 		normalize: true,
 	},
+	externalDeps: {
+		type: "boolean",
+		description:
+			"Emit imports from installed @girs/* npm packages instead of regenerating dep types. Implies single-file ambient .d.ts output. Designed for project-local Vala/C bridges. Strict by default — missing transitive dep GIRs abort the run; pass --allow-missing-deps to override.",
+		default: defaults.externalDeps,
+		normalize: true,
+	},
+	allowMissingDeps: {
+		type: "boolean",
+		description:
+			"In --external-deps mode, allow generation to proceed when app-specific transitive dep GIRs are missing (e.g. CI without libsoup3-devel). Note: GLib/Gio/GObject GIRs are still architecturally required for class-hierarchy resolution. Default strict behavior prevents silent type-quality drift between environments.",
+		default: defaults.allowMissingDeps,
+		normalize: true,
+	},
+	externalPackage: {
+		type: "string",
+		description:
+			"Override the default namespace→npm package mapping for --external-deps mode. Repeatable. Format: 'Namespace=@scope/pkg'. Example: --external-package Soup=@girs/soup-3.0",
+		array: true,
+	},
 };
 
 /**
@@ -173,6 +193,9 @@ export const generateOptions = {
 	package: options.package,
 	reporter: options.reporter,
 	reporterOutput: options.reporterOutput,
+	externalDeps: options.externalDeps,
+	allowMissingDeps: options.allowMissingDeps,
+	externalPackage: options.externalPackage,
 };
 
 export const listOptions = {

package/src/module-loader.ts

@@ -168,7 +168,13 @@ export class ModuleLoader {
 				const girModule = await this.loadAndCreateGirModule(dependency);
 				if (!girModule) {
 					if (!failedGirModules.has(dependency.packageName)) {
-						this.log.warn(WARN_NO_GIR_FILE_FOUND_FOR_PACKAGE(dependency.packageName));
+						// In external-deps mode the strict check after loading turns missing
+						// transitive deps into a hard error; suppress the per-dep warn here so
+						// the user sees one consolidated error instead of a wall of warnings.
+						// `--allow-missing-deps` opts into the same suppression with a soft fail.
+						if (!this.config.externalDeps) {
+							this.log.warn(WARN_NO_GIR_FILE_FOUND_FOR_PACKAGE(dependency.packageName));
+						}
 						failedGirModules.add(dependency.packageName);
 					}
 				} else if (girModule?.packageName) {
@@ -239,23 +245,49 @@ export class ModuleLoader {
 
 		const dependencies = await this.fileFinder.girFilePathToDependencies(girFiles);
 
+		// Load GJS force-loads as DEPENDENCE so they are never treated as user-requested
+		// modules. This ensures --external-deps mode doesn't emit output files for them.
+		const { loaded: forceLoaded, failed: forceFailed } = await this.loadGirModules(
+			[GLib, Gio, GObject, Cairo],
+			ignore,
+			[],
+			ResolveType.DEPENDENCE,
+		);
+
+		// Load user-requested modules (and their transitive deps) starting from the
+		// already-loaded force-load registry so they are not double-loaded.
 		const { loaded, failed } = await this.loadGirModules(
-			[
-				GLib,
-				Gio,
-				GObject,
-				Cairo,
-				...dependencies.filter(
-					(dep) =>
-						dep.namespace !== "GLib" &&
-						dep.namespace !== "Gio" &&
-						dep.namespace !== "GObject" &&
-						dep.namespace !== "cairo",
-				),
-			],
+			dependencies.filter(
+				(dep) =>
+					dep.namespace !== "GLib" &&
+					dep.namespace !== "Gio" &&
+					dep.namespace !== "GObject" &&
+					dep.namespace !== "cairo",
+			),
 			ignore,
+			forceLoaded,
+			ResolveType.BY_HAND,
+			forceFailed,
 		);
 
+		// External-deps mode is strict by default: any transitive dep GIR that couldn't be
+		// loaded would silently degrade type quality. The hardcoded GLib/Gio/GObject/cairo
+		// force-loads above are exempt (they exist for runtime convenience, not because the
+		// input GIR references them).
+		if (this.config.externalDeps && !this.config.allowMissingDeps && failed.size > 0) {
+			const exempt = new Set(["GLib-2.0", "Gio-2.0", "GObject-2.0", "cairo-1.0"]);
+			const critical = Array.from(failed).filter((pkg) => !exempt.has(pkg));
+			if (critical.length > 0) {
+				throw new Error(
+					`Missing GIR files for transitive dependencies in --external-deps mode:\n` +
+						critical.map((pkg) => `  - ${pkg}`).join("\n") +
+						`\n\nInstall the corresponding -devel packages, add their directories to ` +
+						`--girDirectories, or pass --allow-missing-deps to generate anyway ` +
+						`(warning: degraded type quality).`,
+				);
+			}
+		}
+
 		let keep: GirModuleResolvedBy[] = [];
 		if (doNotAskForVersionOnConflict) {
 			keep = loaded;

package/src/types/command-args.ts

@@ -50,6 +50,12 @@ export interface GenerateCommandArgs extends BaseCommandArgs {
 	reporter: boolean;
 	/** Output file path for the reporter */
 	reporterOutput: string;
+	/** Emit imports from installed @girs/* npm packages instead of regenerating dep types */
+	externalDeps: boolean;
+	/** Allow externalDeps generation when transitive dep GIRs are missing (degraded type quality) */
+	allowMissingDeps: boolean;
+	/** Override default namespace→npm package mapping. Repeatable. Format: `Namespace=@girs/pkg` */
+	externalPackage?: string[];
 }
 
 /**