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

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.7";
   }
   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.7";
   }
   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}`;
     }
@@ -14387,12 +14393,16 @@ var IntrospectedProperty = class _IntrospectedProperty extends IntrospectedBase
   writable = false;
   readable = true;
   constructOnly;
+  /** GIR default-value attribute: the default value of the property as a string. */
+  defaultValue;
+  /** GIR getter attribute: name of the getter method for this property (used for nullable inference). */
+  getter;
   get namespace() {
     return this.parent.namespace;
   }
   copy(options2) {
     const { name, writable, readable, type, constructOnly, parent } = this;
-    return new _IntrospectedProperty({
+    const prop = new _IntrospectedProperty({
       name: options2?.name ?? name,
       writable,
       readable,
@@ -14400,6 +14410,9 @@ var IntrospectedProperty = class _IntrospectedProperty extends IntrospectedBase
       constructOnly,
       parent: options2?.parent ?? parent
     })._copyBaseProperties(this);
+    prop.defaultValue = this.defaultValue;
+    prop.getter = this.getter;
+    return prop;
   }
   accept(visitor) {
     const node = this.copy({
@@ -14457,6 +14470,11 @@ var IntrospectedProperty = class _IntrospectedProperty extends IntrospectedBase
       property.doc = parseDoc(element);
       property.metadata = parseMetadata(element);
     }
+    property.defaultValue = element.$["default-value"];
+    property.getter = element.$.getter;
+    if (element.$.nullable === "1" || element.$["allow-none"] === "1") {
+      property.type = new NullableType(property.type);
+    }
     return property;
   }
 };
@@ -14649,6 +14667,28 @@ var IntrospectedSignal = class _IntrospectedSignal extends IntrospectedClassMemb
 
 // ../lib/src/gir/introspected-classes.ts
 var log = new ConsoleReporter(true, "gir/introspected-classes", true);
+function hasExtendsShadowOf(cls, prerequisite, name) {
+  let current = cls.resolveParents().extends();
+  while (current) {
+    const node = current.node;
+    if (node !== prerequisite) {
+      const hasOwn = [...node.props, ...node.fields, ...node.members].some((m) => m.name === name);
+      if (hasOwn) return true;
+    }
+    current = current.extends();
+  }
+  return false;
+}
+function resolveNullableProperties(cls) {
+  for (const prop of cls.props) {
+    if (prop.type instanceof NullableType) continue;
+    const getterName = prop.getter ?? `get_${prop.name}`;
+    const getter = cls.members.find((m) => m.name === getterName && !(m instanceof IntrospectedStaticClassFunction));
+    if (getter instanceof IntrospectedClassFunction && getter.return() instanceof NullableType) {
+      prop.type = new NullableType(prop.type);
+    }
+  }
+}
 var IntrospectedClassFunction = class _IntrospectedClassFunction extends IntrospectedBase {
   parameters;
   return_type;
@@ -14659,6 +14699,8 @@ var IntrospectedClassFunction = class _IntrospectedClassFunction extends Introsp
   returnTypeDoc;
   /** If this function was generated from a signal, stores the signal name. */
   signalOrigin;
+  /** GIR glib:finish-func attribute: name of the function that finishes this async operation. */
+  finishFuncName;
   generics = [];
   constructor({
     name,
@@ -14705,6 +14747,7 @@ var IntrospectedClassFunction = class _IntrospectedClassFunction extends Introsp
     });
     fn.generics = [...this.generics];
     fn.returnTypeDoc = this.returnTypeDoc;
+    fn.finishFuncName = this.finishFuncName;
     if (interfaceParent) {
       fn.interfaceParent = interfaceParent;
     }
@@ -14726,6 +14769,7 @@ var IntrospectedClassFunction = class _IntrospectedClassFunction extends Introsp
   static fromXML(element, parent, options2) {
     const fn = IntrospectedFunction.fromXML(element, parent.namespace, options2);
     const { raw_name: name, output_parameters, parameters, return_type, doc: doc2, isIntrospectable: isIntrospectable2 } = fn;
+    const isShadowedBy = element.$["shadowed-by"] != null;
     const classFn = new _IntrospectedClassFunction({
       parent,
       name,
@@ -14733,10 +14777,11 @@ var IntrospectedClassFunction = class _IntrospectedClassFunction extends Introsp
       parameters,
       return_type,
       doc: doc2,
-      isIntrospectable: isIntrospectable2
+      isIntrospectable: isIntrospectable2 && !isShadowedBy
     });
     classFn.returnTypeDoc = fn.returnTypeDoc;
     classFn.generics = [...fn.generics];
+    classFn.finishFuncName = element.$["glib:finish-func"];
     return classFn;
   }
   anyify() {
@@ -14879,6 +14924,7 @@ var IntrospectedStaticClassFunction = class _IntrospectedStaticClassFunction ext
   static fromXML(m, parent, options2) {
     const fn = IntrospectedFunction.fromXML(m, parent.namespace, options2);
     const { raw_name: name, output_parameters, parameters, return_type, doc: doc2, isIntrospectable: isIntrospectable2 } = fn;
+    const isShadowedBy = m.$["shadowed-by"] != null;
     return new _IntrospectedStaticClassFunction({
       parent,
       name,
@@ -14886,7 +14932,7 @@ var IntrospectedStaticClassFunction = class _IntrospectedStaticClassFunction ext
       parameters,
       return_type,
       doc: doc2,
-      isIntrospectable: isIntrospectable2
+      isIntrospectable: isIntrospectable2 && !isShadowedBy
     });
   }
 };
@@ -15205,6 +15251,7 @@ var IntrospectedClass = class _IntrospectedClass extends IntrospectedBaseClass {
       if (extended?.node instanceof _IntrospectedClass) {
         for (const item of getItems(extended.node)) {
           if (items.has(item.name) || !validate3(item)) continue;
+          if (!hasExtendsShadowOf(this, extended.node, item.name)) continue;
           items.set(item.name, item);
         }
       }
@@ -15342,6 +15389,7 @@ var IntrospectedClass = class _IntrospectedClass extends IntrospectedBaseClass {
     _IntrospectedClass.parseBasicProperties(element, clazz, ns, options2);
     _IntrospectedClass.parseResolveNames(element, clazz, ns, name);
     _IntrospectedClass.parseInheritanceAndMembers(element, clazz, ns, options2);
+    resolveNullableProperties(clazz);
     return clazz;
   }
   static parseBasicProperties(element, clazz, ns, options2) {
@@ -15572,6 +15620,7 @@ var IntrospectedInterface = class _IntrospectedInterface extends IntrospectedBas
     _IntrospectedInterface.parseInterfaceBasicProperties(element, iface, namespace, options2);
     _IntrospectedInterface.parseInterfaceResolveNames(element, iface, namespace, name);
     _IntrospectedInterface.parseInterfaceMembers(element, iface, namespace, options2);
+    resolveNullableProperties(iface);
     return iface;
   }
   static parseInterfaceBasicProperties(element, iface, namespace, options2) {
@@ -15942,9 +15991,7 @@ var IntrospectedFunction = class _IntrospectedFunction extends IntrospectedNames
       ({ allowOptions, params }, p) => {
         const { type, isOptional } = p;
         if (allowOptions) {
-          if (type instanceof NullableType) {
-            params.push(p.copy({ isOptional: true }));
-          } else if (!isOptional) {
+          if (!isOptional) {
             params.push(p);
             return { allowOptions: false, params };
           } else {
@@ -17455,6 +17502,9 @@ function generatePromisifyOverloadedSignatures(node, async_parameters, sync_para
 }
 function findFinishMethodInClass(cls, node) {
   const members = node instanceof IntrospectedStaticClassFunction ? [...cls.constructors, ...cls.members.filter((m) => m instanceof IntrospectedStaticClassFunction)] : [...cls.members.filter((m) => !(m instanceof IntrospectedStaticClassFunction))];
+  if (node.finishFuncName) {
+    return members.find((m) => m.name === node.finishFuncName);
+  }
   return members.find(
     (m) => m.name === `${node.name.replace(/_async$/, "")}_finish` || m.name === `${node.name}_finish`
   );
@@ -20166,6 +20216,14 @@ var fixMissingParent = (node) => {
 var removeComplexFields = (node) => {
   const { namespace } = node;
   node.fields = node.fields.filter((f) => {
+    if (f.type instanceof ArrayType) {
+      const elementType = f.type.deepUnwrap();
+      if (elementType instanceof TypeIdentifier) {
+        const classNode = resolveTypeIdentifier(namespace, elementType);
+        return !classNode?.isPrivate;
+      }
+      return true;
+    }
     const type = f.type.deepUnwrap();
     if (type instanceof NativeType) {
       return true;
@@ -20380,19 +20438,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") {
@@ -20708,7 +20768,7 @@ function checkFunctionConflicts(ns, base, functionElement, conflict_ids, nextTyp
       return false;
     });
   });
-  const hasFieldConflicts = checkFieldPropertyConflicts(base, functionElement.name);
+  const hasFieldConflicts = functionElement instanceof IntrospectedStaticClassFunction ? false : checkFieldPropertyConflicts(base, functionElement.name);
   const hasGObjectConflicts = checkGObjectConflicts(base, functionElement.name);
   const hasConflict = hasParentConflict || hasGObjectConflicts;
   return {
@@ -20942,6 +21002,38 @@ function mergeDescs(descs, comment, indentCount = 1) {
   return def;
 }
 
+// ../lib/src/utils/gir-defaults.ts
+function resolveCEnumConstant(cIdentifier, ns) {
+  const own = ns.enum_constants.get(cIdentifier);
+  if (own) return [ns.namespace, own[0], own[1]];
+  for (const dep of ns.allDependencies) {
+    const depModule = ns.getInstalledImport(dep.namespace);
+    if (!depModule) continue;
+    const entry = depModule.enum_constants.get(cIdentifier);
+    if (entry) return [depModule.namespace, entry[0], entry[1]];
+  }
+  return null;
+}
+function convertSingleCValue(value, ns) {
+  const trimmed = value.trim();
+  if (trimmed === "NULL") return "null";
+  if (trimmed === "TRUE") return "true";
+  if (trimmed === "FALSE") return "false";
+  if (/^-?\d+\.\d+$/.test(trimmed)) {
+    const n = parseFloat(trimmed);
+    if (!Number.isNaN(n)) return String(n);
+  }
+  const entry = resolveCEnumConstant(trimmed, ns);
+  if (entry) return `${entry[0]}.${entry[1]}.${entry[2]}`;
+  return trimmed;
+}
+function convertCDefaultValue(rawValue, ns) {
+  if (rawValue.includes("|")) {
+    return rawValue.split("|").map((part) => convertSingleCValue(part, ns)).join(" | ");
+  }
+  return convertSingleCValue(rawValue, ns);
+}
+
 // ../lib/src/utils/path.ts
 import { dirname as dirname4, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
@@ -20989,6 +21081,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 +21272,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 +21312,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 +21507,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 +21536,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 +21560,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 +21581,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 +21601,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 +22280,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 +22336,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;
@@ -23364,6 +23525,12 @@ export const ${node.name}: ${node.name}Namespace & {
     if (tsProp.constructOnly) propTags.push({ tagName: "construct-only", paramName: "", text: "" });
     else if (tsProp.readable && !tsProp.writable) propTags.push({ tagName: "read-only", paramName: "", text: "" });
     else if (tsProp.writable && !tsProp.readable) propTags.push({ tagName: "write-only", paramName: "", text: "" });
+    if (tsProp.defaultValue !== void 0)
+      propTags.push({
+        tagName: "default",
+        paramName: "",
+        text: convertCDefaultValue(tsProp.defaultValue, this.namespace)
+      });
     desc.push(...this.addGirDocComment(tsProp.doc, propTags, indentCount));
     const indent = generateIndent(indentCount);
     const name = generateMemberName(tsProp);
@@ -24548,6 +24715,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 +24806,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 +27666,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.7";
   }
   const __dirname3 = dirname8(fileURLToPath5(import.meta.url));
   return JSON.parse(readFileSync7(join14(__dirname3, "..", "..", "package.json"), "utf8")).version;
@@ -28204,7 +28372,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.7",
 		"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.6",
+		"@girs/gio-2.0": "^2.88.0-4.0.0-rc.6",
+		"@girs/gjs": "^4.0.0-rc.6",
+		"@girs/glib-2.0": "^2.88.0-4.0.0-rc.6",
+		"@girs/gtk-4.0": "^4.23.0-4.0.0-rc.6"
 	}
 }

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.7",
 		"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.7",
   "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.7",
+    "@ts-for-gir/generator-base": "^4.0.0-rc.7",
+    "@ts-for-gir/generator-html-doc": "^4.0.0-rc.7",
+    "@ts-for-gir/generator-json": "^4.0.0-rc.7",
+    "@ts-for-gir/generator-typescript": "^4.0.0-rc.7",
+    "@ts-for-gir/lib": "^4.0.0-rc.7",
+    "@ts-for-gir/reporter": "^4.0.0-rc.7",
+    "@ts-for-gir/tsconfig": "^4.0.0-rc.7",
     "@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.7",
     "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[];
 }
 
 /**