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

package/bin/ts-for-gir

@@ -7268,7 +7268,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 function getPackageVersion() {
   if (true) {
-    return "4.0.0-rc.5";
+    return "4.0.0-rc.6";
   }
   const currentModulePath = fileURLToPath(import.meta.url);
   const currentDir = dirname(currentModulePath);
@@ -8165,7 +8165,7 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 var NEW_LINE_REG_EXP = /[\n\r]+/g;
 function getPackageVersion2() {
   if (true) {
-    return "4.0.0-rc.5";
+    return "4.0.0-rc.6";
   }
   const currentModulePath = fileURLToPath2(import.meta.url);
   const currentDir = dirname2(currentModulePath);
@@ -12726,6 +12726,12 @@ var DependencyManager = class _DependencyManager {
     };
   }
   createImportPath(packageName, namespace, version) {
+    if (this.config.externalDeps) {
+      const override3 = this.config.externalPackages?.[namespace];
+      if (override3) return override3;
+      const importName2 = transformImportName(packageName);
+      return `${this.config.npmScope}/${importName2}`;
+    }
     if (!this.config.package) {
       return `gi://${namespace}?version=${version}`;
     }
@@ -20380,19 +20386,21 @@ var NSRegistry = class {
     );
   }
   transform(options2) {
-    const GLib = this.assertNamespace("GLib", "2.0");
-    const Gio = this.assertNamespace("Gio", "2.0");
-    const GObject = this.assertNamespace("GObject", "2.0");
-    Gio.package_version = [...GLib.package_version];
-    GObject.package_version = [...GLib.package_version];
+    const GLib = this.namespace("GLib", "2.0");
+    const Gio = this.namespace("Gio", "2.0");
+    const GObject = this.namespace("GObject", "2.0");
+    if (GLib && Gio) Gio.package_version = [...GLib.package_version];
+    if (GLib && GObject) GObject.package_version = [...GLib.package_version];
     const interfaceVisitor = new InterfaceVisitor();
     this.registerTransformation(interfaceVisitor);
     const classVisitor = new ClassVisitor();
     this.registerTransformation(classVisitor);
-    console.log("Adding generics...");
-    generify(this, options2.inferGenerics);
-    console.log("Injecting types...");
-    inject(this);
+    if (GLib && Gio) {
+      console.log("Adding generics...");
+      generify(this, options2.inferGenerics);
+      console.log("Injecting types...");
+      inject(this);
+    }
   }
   defaultVersionOf(name) {
     if (name === "GLib" || name === "Gio" || name === "GObject") {
@@ -20989,6 +20997,8 @@ var 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"
@@ -21178,6 +21188,23 @@ var options = {
     description: "Output file path for the reporter (default: ts-for-gir-report.json)",
     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 \u2014 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\u2192npm package mapping for --external-deps mode. Repeatable. Format: 'Namespace=@scope/pkg'. Example: --external-package Soup=@girs/soup-3.0",
+    array: true
   }
 };
 var generateOptions = {
@@ -21201,7 +21228,10 @@ var generateOptions = {
   noAdvancedVariants: options.noAdvancedVariants,
   package: options.package,
   reporter: options.reporter,
-  reporterOutput: options.reporterOutput
+  reporterOutput: options.reporterOutput,
+  externalDeps: options.externalDeps,
+  allowMissingDeps: options.allowMissingDeps,
+  externalPackage: options.externalPackage
 };
 var listOptions = {
   modules: options.modules,
@@ -21393,6 +21423,18 @@ function getOptionsGeneration(config) {
   };
   return generateConfig;
 }
+function parseExternalPackagePairs(pairs) {
+  if (!pairs || pairs.length === 0) return void 0;
+  const map2 = {};
+  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) map2[ns] = pkg;
+  }
+  return Object.keys(map2).length > 0 ? map2 : void 0;
+}
 function validate2(config) {
   return config;
 }
@@ -21410,9 +21452,16 @@ function mergeConfigValue(userConfig, configFileData, key, optionDefault, valida
 async function load(cliOptions) {
   const configFile = await loadConfigFile(cliOptions.configName);
   const configFileData = configFile?.config || {};
+  const externalPackagesFromCli = parseExternalPackagePairs(
+    cliOptions.externalPackage
+  );
+  const { externalPackage: _externalPackage, ...cliOptionsClean } = cliOptions;
   const userConfig = {
-    ...cliOptions
+    ...cliOptionsClean
   };
+  if (externalPackagesFromCli) {
+    userConfig.externalPackages = externalPackagesFromCli;
+  }
   if (configFileData) {
     const booleanKeys = [
       ["verbose", options.verbose.default],
@@ -21427,6 +21476,8 @@ async function load(cliOptions) {
       ["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]
     ];
@@ -21446,13 +21497,19 @@ async function load(cliOptions) {
       mergeConfigValue(userConfig, configFileData, key, defaultVal);
     }
     const arrayKeys = [
-      ["girDirectories", options.girDirectories.default],
       ["ignore", options.ignore.default],
       ["modules", options.modules.default]
     ];
     for (const [key, defaultVal] of arrayKeys) {
       mergeConfigValue(userConfig, configFileData, key, defaultVal);
     }
+    if (configFileData.girDirectories?.length) {
+      const current = userConfig.girDirectories;
+      const toAdd = configFileData.girDirectories.filter((d) => !current.includes(d));
+      if (toAdd.length > 0) {
+        userConfig.girDirectories = [...toAdd, ...current];
+      }
+    }
     if (userConfig.root === options.root.default && (configFileData.root || configFile?.filepath)) {
       userConfig.root = configFileData.root || (configFile?.filepath ? dirname5(configFile.filepath) : options.root.default);
     }
@@ -21460,6 +21517,9 @@ async function load(cliOptions) {
     if (isDefaultOutdir && configFileData.outdir) {
       userConfig.outdir = userConfig.print ? null : configFileData.outdir;
     }
+    if (!externalPackagesFromCli && configFileData.externalPackages) {
+      userConfig.externalPackages = configFileData.externalPackages;
+    }
   }
   const resolveToRoot = (path) => path.startsWith("/") ? path : resolve4(userConfig.root, path);
   if (userConfig.outdir) {
@@ -22136,7 +22196,9 @@ var ModuleLoader = class {
         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));
+            if (!this.config.externalDeps) {
+              this.log.warn(WARN_NO_GIR_FILE_FOUND_FOR_PACKAGE(dependency.packageName));
+            }
             failedGirModules.add(dependency.packageName);
           }
         } else if (girModule?.packageName) {
@@ -22190,18 +22252,33 @@ var ModuleLoader = class {
     const GObject = await this.dependencyManager.get("GObject", "2.0");
     const Cairo = await this.dependencyManager.get("cairo", "1.0");
     const dependencies = await this.fileFinder.girFilePathToDependencies(girFiles);
+    const { loaded: forceLoaded, failed: forceFailed } = await this.loadGirModules(
+      [GLib, Gio, GObject, Cairo],
+      ignore,
+      [],
+      0 /* DEPENDENCE */
+    );
     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"
-        )
-      ],
-      ignore
+      dependencies.filter(
+        (dep) => dep.namespace !== "GLib" && dep.namespace !== "Gio" && dep.namespace !== "GObject" && dep.namespace !== "cairo"
+      ),
+      ignore,
+      forceLoaded,
+      1 /* BY_HAND */,
+      forceFailed
     );
+    if (this.config.externalDeps && !this.config.allowMissingDeps && failed.size > 0) {
+      const exempt = /* @__PURE__ */ 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:
+` + critical.map((pkg) => `  - ${pkg}`).join("\n") + `
+
+Install the corresponding -devel packages, add their directories to --girDirectories, or pass --allow-missing-deps to generate anyway (warning: degraded type quality).`
+        );
+      }
+    }
     let keep = [];
     if (doNotAskForVersionOnConflict) {
       keep = loaded;
@@ -24548,6 +24625,7 @@ var TypeDefinitionGenerator = class _TypeDefinitionGenerator {
   }
   async exportGjs() {
     const { config, dependencyManager } = this;
+    if (config.externalDeps) return;
     if (!config.outdir) return;
     const gjs2 = dependencyManager.getGjs();
     const templateProcessor = new TemplateProcessor(
@@ -24638,7 +24716,7 @@ ${domContent.append}`, config.outdir, "dom.d.ts");
   }
   async finish(girModules) {
     await this.exportGjs();
-    if (!this.config.package) {
+    if (!this.config.package && !this.config.externalDeps) {
       await this.exportAllModules(girModules);
     }
   }
@@ -27498,7 +27576,7 @@ import { fileURLToPath as fileURLToPath5 } from "node:url";
 import { i18n, JSX as JSX8, ReflectionKind as ReflectionKind4 } from "typedoc";
 function getTsForGirVersion() {
   if (true) {
-    return "4.0.0-rc.5";
+    return "4.0.0-rc.6";
   }
   const __dirname3 = dirname8(fileURLToPath5(import.meta.url));
   return JSON.parse(readFileSync7(join14(__dirname3, "..", "..", "package.json"), "utf8")).version;
@@ -28204,7 +28282,8 @@ async function runGenerationCommand(args, options2) {
     }
     tsForGir = new GenerationHandler(generateConfig, options2.generatorType, registry);
     moduleLoader.parse(keep);
-    const girModules = Array.from(keep).map((girModuleResolvedBy) => girModuleResolvedBy.module);
+    const toGenerate = generateConfig.externalDeps ? keep.filter((m) => m.resolvedBy === 1 /* BY_HAND */) : keep;
+    const girModules = Array.from(toGenerate).map((girModuleResolvedBy) => girModuleResolvedBy.module);
     await tsForGir.start(girModules);
   } catch (error) {
     if (generateConfig.reporter && tsForGir) {

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.5",
+		"@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.5",
+		"@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.5",
+  "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,14 +55,14 @@
     ".": "./src/index.ts"
   },
   "devDependencies": {
-    "@gi.ts/parser": "^4.0.0-rc.5",
-    "@ts-for-gir/generator-base": "^4.0.0-rc.5",
-    "@ts-for-gir/generator-html-doc": "^4.0.0-rc.5",
-    "@ts-for-gir/generator-json": "^4.0.0-rc.5",
-    "@ts-for-gir/generator-typescript": "^4.0.0-rc.5",
-    "@ts-for-gir/lib": "^4.0.0-rc.5",
-    "@ts-for-gir/reporter": "^4.0.0-rc.5",
-    "@ts-for-gir/tsconfig": "^4.0.0-rc.5",
+    "@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": "^25.6.0",
@@ -72,7 +72,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.2",
-    "@ts-for-gir/templates": "^4.0.0-rc.5",
+    "@ts-for-gir/templates": "^4.0.0-rc.6",
     "colorette": "^2.0.20",
     "cosmiconfig": "^9.0.1",
     "ejs": "^5.0.2",

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[];
 }
 
 /**