@gtkx/codegen 1.2.1 → 1.3.0

package/src/fingerprint.ts

@@ -1,9 +1,10 @@
-import { sortStrings } from "@gtkx/utils";
-import { createHash } from "node:crypto";
+import { createHash, type Hash } from "node:crypto";
 import { type Dirent, existsSync, readdirSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import packageManifest from "../package.json" with { type: "json" };
+import { EXTERNAL_NAMESPACES } from "./gir/external-namespaces.js";
 import { arrayGuard, hasFields, isNumber, isString, optionalGuard } from "./guards.js";
 import { readJsonFile } from "./json.js";
 
@@ -11,7 +12,11 @@ type GiInputs = {
     girFiles: string[];
     libraries: string[];
     girPath: string[];
+    storeVersion: string | undefined;
     isByteArrayTyped: boolean;
+    isValueUnwrapped: boolean;
+    isFinishTrimmed: boolean;
+    isInoutInPlace: boolean;
 };
 
 type GiFingerprint = {
@@ -36,6 +41,7 @@ type DocsFingerprint = {
 
 type JsxFingerprintInput = {
     reactVersion: string;
+    reactSubexports: string[];
     components: Record<string, ModuleExport>;
     lazyElements: string[];
     props: Record<string, ModuleExport>;
@@ -47,25 +53,139 @@ type JsxFingerprint = {
     intrinsicElementCount: number;
 };
 
+type InstalledManifest = { name: string; version: string };
+
 const FINGERPRINT_FILENAME = ".codegen-fingerprint.json";
-const CODEGEN_VERSION: string = packageManifest.version;
-const OVERRIDES_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "overrides");
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const OVERRIDES_ROOT = join(PACKAGE_ROOT, "overrides");
+const requireFromCodegen = createRequire(import.meta.url);
+const codegenHashCache: Map<string, string> = new Map();
+
+const compareOrdinal = (a: string, b: string): number => {
+    if (a < b) {
+        return -1;
+    }
+
+    return a > b ? 1 : 0;
+};
 
-const sortAlpha = (values: string[]): string => sortStrings(values).join(",");
+const sortOrdinal = (values: string[]): string[] => values.toSorted(compareOrdinal);
+const sortAlpha = (values: string[]): string => sortOrdinal(values).join(",");
 
-const overrideFiles = (): string[] => {
-    if (!existsSync(OVERRIDES_ROOT)) {
+const filesUnder = (root: string): string[] => {
+    if (!existsSync(root)) {
         return [];
     }
 
-    return readdirSync(OVERRIDES_ROOT, { recursive: true, withFileTypes: true })
+    return readdirSync(root, { recursive: true, withFileTypes: true })
         .filter((entry: Dirent) => entry.isFile())
         .map((entry: Dirent) => join(entry.parentPath, entry.name));
 };
 
+const hashTree = (hash: Hash, label: string, root: string): void => {
+    const files = sortOrdinal(filesUnder(root));
+
+    for (const file of files) {
+        hash.update("\n");
+        hash.update(join(label, relative(root, file)));
+        hash.update("\0");
+        hash.update(readFileSync(file));
+    }
+};
+
+const isInstalledManifest = (value: unknown): value is InstalledManifest =>
+    hasFields<InstalledManifest>(value, { name: isString, version: isString });
+
+const tryResolve = (specifier: string): string | undefined => {
+    try {
+        return requireFromCodegen.resolve(specifier);
+    } catch {
+        return undefined;
+    }
+};
+
+const manifestVersion = (path: string | undefined, name: string): string | undefined => {
+    if (path === undefined) {
+        return undefined;
+    }
+
+    const manifest = readJsonFile(path);
+
+    return isInstalledManifest(manifest) && manifest.name === name ? manifest.version : undefined;
+};
+
+const packageRootFor = (name: string): string | undefined => {
+    const entry = tryResolve(name);
+
+    if (entry === undefined) {
+        return undefined;
+    }
+
+    for (let directory = dirname(entry); directory !== dirname(directory); directory = dirname(directory)) {
+        if (manifestVersion(join(directory, "package.json"), name) !== undefined) {
+            return directory;
+        }
+    }
+
+    return undefined;
+};
+
+const installedVersion = (name: string): string | undefined => {
+    const direct = manifestVersion(tryResolve(`${name}/package.json`), name);
+
+    if (direct !== undefined) {
+        return direct;
+    }
+
+    const root = packageRootFor(name);
+
+    return root === undefined ? undefined : manifestVersion(join(root, "package.json"), name);
+};
+
+const dependencyVersions = (): string[] =>
+    sortOrdinal(
+        Object.entries(packageManifest.dependencies)
+            .filter(([name]) => !name.startsWith("@types/"))
+            .map(([name, range]) => `${name}@${installedVersion(name) ?? range}`),
+    );
+
+const hashPackageCode = (hash: Hash, label: string, root: string): void => {
+    hashTree(hash, join(label, "src"), join(root, "src"));
+    hashTree(hash, join(label, "dist"), join(root, "dist"));
+};
+
+const computeCodegenHash = (): string => {
+    const hash = createHash("sha256");
+    hash.update(dependencyVersions().join(","));
+    hashPackageCode(hash, "codegen", PACKAGE_ROOT);
+    hashTree(hash, "overrides", OVERRIDES_ROOT);
+    const utilsRoot = packageRootFor("@gtkx/utils");
+
+    if (utilsRoot !== undefined) {
+        hashPackageCode(hash, "@gtkx/utils", utilsRoot);
+    }
+
+    return hash.digest("hex");
+};
+
+const codegenHash = (): string => {
+    const cached = codegenHashCache.get("codegen");
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const value = computeCodegenHash();
+    codegenHashCache.set("codegen", value);
+
+    return value;
+};
+
 const hashGi = (inputs: GiInputs): string => {
     const hash = createHash("sha256");
-    hash.update(CODEGEN_VERSION);
+    hash.update(codegenHash());
+    hash.update("\n");
+    hash.update(JSON.stringify(EXTERNAL_NAMESPACES));
     hash.update("\n");
     hash.update(sortAlpha(inputs.libraries));
     hash.update("\n");
@@ -73,9 +193,16 @@ const hashGi = (inputs: GiInputs): string => {
     hash.update("\n");
     hash.update(String(inputs.isByteArrayTyped));
     hash.update("\n");
-    const hashedFiles = sortStrings([...inputs.girFiles, ...overrideFiles()]);
+    hash.update(String(inputs.isValueUnwrapped));
+    hash.update("\n");
+    hash.update(String(inputs.isFinishTrimmed));
+    hash.update("\n");
+    hash.update(String(inputs.isInoutInPlace));
+    hash.update("\n");
+    hash.update(String(inputs.storeVersion));
+    const girFiles = sortOrdinal(inputs.girFiles);
 
-    for (const file of hashedFiles) {
+    for (const file of girFiles) {
         hash.update("\n");
         hash.update(file);
         hash.update("\0");
@@ -161,19 +288,20 @@ const isDocsOutputFresh = (outDir: string, inputs: GiInputs, input: DocsFingerpr
 };
 
 const serializeModuleExports = (map: Record<string, ModuleExport>): [string, string, string][] =>
-    sortStrings(Object.keys(map)).map((type) => [type, map[type]?.module ?? "", map[type]?.export ?? ""]);
+    sortOrdinal(Object.keys(map)).map((type) => [type, map[type]?.module ?? "", map[type]?.export ?? ""]);
 
 const serializeOmittedProps = (map: Record<string, string[]>): [string, string][] =>
-    sortStrings(Object.keys(map)).map((type) => [type, sortAlpha(map[type] ?? [])]);
+    sortOrdinal(Object.keys(map)).map((type) => [type, sortAlpha(map[type] ?? [])]);
 
 const hashJsx = (input: JsxFingerprintInput): string =>
     createHash("sha256")
         .update(
             JSON.stringify([
-                CODEGEN_VERSION,
+                codegenHash(),
                 input.reactVersion,
+                sortOrdinal(input.reactSubexports),
                 serializeModuleExports(input.components),
-                sortStrings(input.lazyElements),
+                sortOrdinal(input.lazyElements),
                 serializeModuleExports(input.props),
                 serializeOmittedProps(input.omittedProps),
             ]),

package/src/gi.ts

@@ -1,8 +1,9 @@
 import type { Library } from "./gir/library.js";
 import type { StoreOptions } from "./store/store-fs.js";
 import { computeGiFingerprint } from "./fingerprint.js";
+import { externalPackageFor } from "./gir/external-namespaces.js";
 import { namespaceDirectory } from "./gir/namespace.js";
-import { type GiNamespaceInput, writeGiStore } from "./store/gi-store.js";
+import { type GiExternalNamespaceInput, type GiNamespaceInput, writeGiStore } from "./store/gi-store.js";
 import { generateNamespaceModule } from "./store/gi/pipeline.js";
 
 type GiCodegenOptions = {
@@ -10,25 +11,59 @@ type GiCodegenOptions = {
     libraries: string[];
     girPath: string[];
     isByteArrayTyped: boolean;
+    isValueUnwrapped: boolean;
+    isFinishTrimmed: boolean;
+    isInoutInPlace: boolean;
 };
 
-const runGiCodegen = (library: Library, options: GiCodegenOptions): number => {
-    const { gi, libraries, girPath, isByteArrayTyped } = options;
+type SplitNamespaces = {
+    namespaces: GiNamespaceInput[];
+    externalNamespaces: GiExternalNamespaceInput[];
+};
+
+const splitNamespaces = (library: Library): SplitNamespaces => {
+    const namespaces: GiNamespaceInput[] = [];
+    const externalNamespaces: GiExternalNamespaceInput[] = [];
+
+    for (const namespace of library.namespaces.values()) {
+        const packageName = externalPackageFor(namespace.name);
+
+        if (packageName !== undefined) {
+            externalNamespaces.push({
+                directory: namespaceDirectory(namespace),
+                packageName,
+                girFile: namespace.girFile,
+            });
 
-    const namespaces: GiNamespaceInput[] = Array.from(library.namespaces.values(), (namespace) => ({
-        directory: namespaceDirectory(namespace),
-        rawSource: generateNamespaceModule(namespace, library),
-        girFile: namespace.girFile,
-    }));
+            continue;
+        }
+
+        namespaces.push({
+            directory: namespaceDirectory(namespace),
+            rawSource: generateNamespaceModule(namespace, library),
+            girFile: namespace.girFile,
+        });
+    }
+
+    return { namespaces, externalNamespaces };
+};
+
+const runGiCodegen = (library: Library, options: GiCodegenOptions): number => {
+    const { gi, libraries, girPath, isByteArrayTyped, isValueUnwrapped, isFinishTrimmed, isInoutInPlace } = options;
+    const { namespaces, externalNamespaces } = splitNamespaces(library);
 
     const fingerprint = computeGiFingerprint({
         girFiles: library.girFiles,
         libraries: [...libraries],
         girPath: [...girPath],
+        storeVersion: gi.version,
         isByteArrayTyped,
+        isValueUnwrapped,
+        isFinishTrimmed,
+        isInoutInPlace,
     });
 
-    writeGiStore(gi, namespaces, fingerprint);
+    writeGiStore(gi, namespaces, externalNamespaces, fingerprint);
 
     return library.namespaces.size;
 };

package/src/gir/external-namespaces.ts

@@ -0,0 +1,8 @@
+type ExternalNamespace = { namespace: string; packageName: string };
+
+const EXTERNAL_NAMESPACES: ExternalNamespace[] = [{ namespace: "cairo", packageName: "@gtkx/cairo" }];
+
+const externalPackageFor = (namespaceName: string): string | undefined =>
+    EXTERNAL_NAMESPACES.find((entry) => entry.namespace === namespaceName)?.packageName;
+
+export { EXTERNAL_NAMESPACES, externalPackageFor, type ExternalNamespace };

package/src/gir/finish-overrides.ts

@@ -0,0 +1,5 @@
+const FUNCTIONS_MISSING_FINISH_FUNC: Map<string, string> = new Map([
+    ["g_file_replace_contents_bytes_async", "replace_contents_finish"],
+]);
+
+export { FUNCTIONS_MISSING_FINISH_FUNC };

package/src/gir/function.ts

@@ -1,9 +1,12 @@
 import type { GirAnnotations } from "./annotations.js";
 import type { ParseContext } from "./type-id.js";
 import { type CursorParameterNames, PARAMETERS_MISSING_ARRAY_EXTENT } from "./cursor-overrides.js";
+import { FUNCTIONS_MISSING_FINISH_FUNC } from "./finish-overrides.js";
+import { HIDDEN_SYMBOLS } from "./hidden-symbols.js";
 import { PARAMETERS_MISSING_NULLABLE_ANNOTATION } from "./nullable-overrides.js";
 import { type GirParameter, type GirReturnValue, parameterFromNode, parseCallable } from "./parameter.js";
 import { attr, getChild, type RawNode } from "./parse.js";
+import { RETURNS_MISSING_UCS4_ARRAY_TYPE } from "./ucs4-overrides.js";
 
 /** A callable declared by a GIR namespace, class, or record: a function, a method, or a constructor. */
 type GirFunction = {
@@ -17,13 +20,16 @@ type GirFunction = {
     cIdentifier: string | undefined;
     /** Whether the C function takes a trailing `GError` out parameter and can fail. */
     throws: boolean;
-    /** Whether the GIR marks the callable as introspectable, and so bindable. */
+    /** Whether the callable is bindable: the GIR marks it introspectable and GTKX does not hide it. */
     introspectable: boolean;
     /** Qualified `Type.member` the GIR redirects the callable to, from its `moved-to` annotation. */
     movedTo: string | undefined;
     /** Name of the callable that shadows this one, from the GIR's `shadowed-by` annotation. */
     shadowedBy: string | undefined;
-    /** Name of the callable that completes this asynchronous one, from the GIR's `glib:finish-func`. */
+    /**
+     * Name of the callable that completes this asynchronous one, from the GIR's `glib:finish-func`
+     * or a GTKX override for a GIR that lacks the annotation.
+     */
     finishFunc: string | undefined;
     /** The instance the callable is invoked on, absent for constructors and namespace-level functions. */
     instance: GirParameter | undefined;
@@ -84,20 +90,52 @@ const bindMissingArrayExtent = (fn: GirFunction): GirFunction => {
     return fn;
 };
 
+const bindMissingUcs4ReturnArray = (fn: GirFunction, context: ParseContext): GirFunction => {
+    if (fn.cIdentifier !== undefined && RETURNS_MISSING_UCS4_ARRAY_TYPE.has(fn.cIdentifier)) {
+        fn.returnValue.type = context.addContainer({
+            kind: "carray",
+            element: context.addPrimitive("unichar"),
+            elementCType: "gunichar",
+            arrayCType: "gunichar*",
+            lengthParameterIndex: undefined,
+            fixedSize: undefined,
+            isZeroTerminated: true,
+        });
+    }
+
+    return fn;
+};
+
+const annotatedFinishFunc = (node: RawNode, cIdentifier: string | undefined): string | undefined => {
+    const annotated = attr(node, "glib:finish-func");
+
+    if (annotated !== undefined) {
+        return annotated;
+    }
+
+    return cIdentifier === undefined ? undefined : FUNCTIONS_MISSING_FINISH_FUNC.get(cIdentifier);
+};
+
+const isHiddenSymbol = (cIdentifier: string | undefined): boolean =>
+    cIdentifier !== undefined && HIDDEN_SYMBOLS.has(cIdentifier);
+
 const functionFromNode = (node: RawNode, context: ParseContext): GirFunction => {
     const instanceNode = getChild(getChild(node, "parameters"), "instance-parameter");
-
-    return bindMissingArrayExtent(
-        relaxMissingNullable({
-            ...parseCallable(node, context),
-            name: attr(node, "shadows") ?? attr(node, "name") ?? "",
-            cIdentifier: attr(node, "c:identifier"),
-            movedTo: attr(node, "moved-to"),
-            shadowedBy: attr(node, "shadowed-by"),
-            finishFunc: attr(node, "glib:finish-func"),
-            instance: instanceNode === undefined ? undefined : parameterFromNode(instanceNode, context),
-        }),
-    );
+    const callable = parseCallable(node, context);
+    const cIdentifier = attr(node, "c:identifier");
+
+    const fn: GirFunction = {
+        ...callable,
+        introspectable: callable.introspectable && !isHiddenSymbol(cIdentifier),
+        name: attr(node, "shadows") ?? attr(node, "name") ?? "",
+        cIdentifier,
+        movedTo: attr(node, "moved-to"),
+        shadowedBy: attr(node, "shadowed-by"),
+        finishFunc: annotatedFinishFunc(node, cIdentifier),
+        instance: instanceNode === undefined ? undefined : parameterFromNode(instanceNode, context),
+    };
+
+    return bindMissingUcs4ReturnArray(bindMissingArrayExtent(relaxMissingNullable(fn)), context);
 };
 
 export { functionFromNode, type GirFunction };

package/src/gir/hidden-symbols.ts

@@ -0,0 +1,39 @@
+const HIDDEN_SYMBOLS: Set<string> = new Set([
+    "g_action_map_add_action_entries",
+    "g_ascii_dtostr",
+    "g_ascii_formatd",
+    "g_file_info_set_attribute",
+    "g_file_set_attribute",
+    "g_log_set_writer_func",
+    "g_object_get_data",
+    "g_object_get_qdata",
+    "g_object_set_data",
+    "g_object_set_data_full",
+    "g_object_set_qdata",
+    "g_object_set_qdata_full",
+    "g_object_steal_data",
+    "g_object_steal_qdata",
+    "g_param_spec_get_qdata",
+    "g_param_spec_set_qdata",
+    "g_param_spec_set_qdata_full",
+    "g_param_spec_steal_qdata",
+    "g_ref_string_acquire",
+    "g_ref_string_length",
+    "g_ref_string_new",
+    "g_ref_string_new_intern",
+    "g_ref_string_new_len",
+    "g_ref_string_release",
+    "g_stpcpy",
+    "g_strcanon",
+    "g_strchomp",
+    "g_strchug",
+    "g_strdelimit",
+    "g_strdown",
+    "g_strreverse",
+    "g_strup",
+    "g_thread_exit",
+    "g_thread_new",
+    "g_thread_try_new",
+]);
+
+export { HIDDEN_SYMBOLS };

package/src/gir/library.ts

@@ -24,6 +24,18 @@ type TypeTable = {
     index: Map<string, number>;
 };
 
+/** Behavior a project opted into ahead of the next major version, through the `future` block of its config. */
+type FutureBehavior = {
+    /** Whether byte sequences render as `Uint8Array` rather than `number[]`. */
+    isByteArrayTyped?: boolean;
+    /** Whether a `GObject.Value` a binding hands back surfaces as what it holds rather than as the value. */
+    isValueUnwrapped?: boolean;
+    /** Whether a promisified result drops the leading success boolean of a throwing finish function. */
+    isFinishTrimmed?: boolean;
+    /** Whether a handle-passing inout parameter is mutated in place rather than packed into the result. */
+    isInoutInPlace?: boolean;
+};
+
 /** A namespace whose header has been read and whose shell is registered, before its body is parsed. */
 type DiscoveredNamespace = {
     /** Attributes and includes read from the namespace's GIR file. */
@@ -84,12 +96,15 @@ class Library {
      *
      * @param libraries GIR identifiers to load, such as `Gtk-4.0`.
      * @param girPath Directories searched, in order, for each `.gir` file.
-     * @param isByteArrayTyped Whether byte sequences render as `Uint8Array` rather than `number[]`.
+     * @param future Behavior the project opted into ahead of the next major version.
      * @returns A library holding every namespace that was parsed.
      */
-    static load(libraries: string[], girPath: string[], isByteArrayTyped = false): Library {
+    static load(libraries: string[], girPath: string[], future: FutureBehavior = {}): Library {
         const library = new Library();
-        library.isByteArrayTypedValue = isByteArrayTyped;
+        library.isByteArrayTypedValue = future.isByteArrayTyped === true;
+        library.isValueUnwrappedValue = future.isValueUnwrapped === true;
+        library.isFinishTrimmedValue = future.isFinishTrimmed === true;
+        library.isInoutInPlaceValue = future.isInoutInPlace === true;
         this.drive(library, libraries, girPath);
 
         return library;
@@ -102,6 +117,9 @@ class Library {
     private typeTables: TypeTable[] = [];
     private girFilesValue: string[] = [];
     private isByteArrayTypedValue = false;
+    private isValueUnwrappedValue = false;
+    private isFinishTrimmedValue = false;
+    private isInoutInPlaceValue = false;
 
     /** Creates a library with no namespaces loaded; {@link Library.load} builds a populated one. */
     constructor() {
@@ -336,6 +354,21 @@ class Library {
         return this.isByteArrayTypedValue;
     }
 
+    /** Whether a `GObject.Value` a binding hands back surfaces as what it holds rather than as the value. */
+    public get isValueUnwrapped(): boolean {
+        return this.isValueUnwrappedValue;
+    }
+
+    /** Whether a promisified result drops the leading success boolean of a throwing finish function. */
+    public get isFinishTrimmed(): boolean {
+        return this.isFinishTrimmedValue;
+    }
+
+    /** Whether a handle-passing inout parameter is mutated in place rather than packed into the result. */
+    public get isInoutInPlace(): boolean {
+        return this.isInoutInPlaceValue;
+    }
+
     /** Paths of the `.gir` files that were read, in the order they were discovered. */
     public get girFiles(): string[] {
         return this.girFilesValue;

package/src/gir/ucs4-overrides.ts

@@ -0,0 +1,7 @@
+const RETURNS_MISSING_UCS4_ARRAY_TYPE: Set<string> = new Set([
+    "g_utf8_to_ucs4",
+    "g_utf8_to_ucs4_fast",
+    "g_utf16_to_ucs4",
+]);
+
+export { RETURNS_MISSING_UCS4_ARRAY_TYPE };

package/src/jsx.ts

@@ -6,6 +6,7 @@ import {
     type JsxFingerprintInput,
     jsxStoreFreshness,
 } from "./fingerprint.js";
+import { externalPackageFor } from "./gir/external-namespaces.js";
 import { type ModuleExport, readBuiltinElements } from "./react/element-config.js";
 import { writeJsxStore } from "./store/jsx-store.js";
 import { ELEMENTS_FILENAME, renderGeneratedElements } from "./store/jsx/generated-elements.js";
@@ -39,6 +40,7 @@ const runJsxCodegen = async (options: RunJsxCodegenOptions): Promise<RunJsxCodeg
 
     const fingerprintInput: JsxFingerprintInput = {
         reactVersion: options.jsx.version,
+        reactSubexports: options.reactSubexports,
         components,
         lazyElements,
         props,
@@ -53,7 +55,9 @@ const runJsxCodegen = async (options: RunJsxCodegenOptions): Promise<RunJsxCodeg
         }
     }
 
-    const { namespaces, metadata, intrinsicElementCount, elements } = generateJsxFiles(options.getLibrary(), {
+    const library = options.getLibrary();
+
+    const { namespaces, metadata, intrinsicElementCount, elements } = generateJsxFiles(library, {
         reactSubexports: options.reactSubexports,
         components,
         lazyElements,
@@ -61,15 +65,36 @@ const runJsxCodegen = async (options: RunJsxCodegenOptions): Promise<RunJsxCodeg
         omittedProps,
     });
 
-    writeJsxStore(options.jsx, namespaces, metadata, [
-        {
-            relativePath: FINGERPRINT_FILENAME,
-            content: `${JSON.stringify(computeJsxFingerprint(fingerprintInput, intrinsicElementCount), null, 2)}\n`,
-        },
-        { relativePath: ELEMENTS_FILENAME, content: renderGeneratedElements(elements) },
-    ]);
+    writeJsxStore({
+        options: options.jsx,
+        namespaces,
+        metadata,
+        externalPackages: storeExternalPackages(library),
+        rawFiles: [
+            {
+                relativePath: FINGERPRINT_FILENAME,
+                content:
+                    `${JSON.stringify(computeJsxFingerprint(fingerprintInput, intrinsicElementCount), null, 2)}\n`,
+            },
+            { relativePath: ELEMENTS_FILENAME, content: renderGeneratedElements(elements) },
+        ],
+    });
 
     return { isRegenerated: true, intrinsicElementCount };
 };
 
+const storeExternalPackages = (library: Library): string[] => {
+    const packages: Set<string> = new Set();
+
+    for (const namespace of library.namespaces.values()) {
+        const packageName = externalPackageFor(namespace.name);
+
+        if (packageName !== undefined) {
+            packages.add(packageName);
+        }
+    }
+
+    return [...packages];
+};
+
 export { runJsxCodegen };

package/src/runner.ts

@@ -8,6 +8,7 @@ import { runGiCodegen } from "./gi.js";
 import { Library } from "./gir/library.js";
 import { generateGlModules, type GlGenerationReport } from "./khronos/pipeline.js";
 import { sweepStagingDirs } from "./staging.js";
+import { externalPackageNotices } from "./store/external-package-links.js";
 import { ensureStoreLink, type StoreOptions } from "./store/store-fs.js";
 
 type GlCodegenOptions = {
@@ -41,6 +42,12 @@ type CodegenRunnerOptions = {
     isForced?: boolean;
     /** Emits GIR byte sequences as `Uint8Array` rather than `number[]`; defaults to false. */
     isByteArrayTyped?: boolean;
+    /** Surfaces a `GObject.Value` a binding hands back as what it holds rather than as the value; defaults to false. */
+    isValueUnwrapped?: boolean;
+    /** Drops the leading success boolean from promisified results of a throwing finish; defaults to false. */
+    isFinishTrimmed?: boolean;
+    /** Mutates a handle-passing inout parameter in place instead of packing it into the result; defaults to false. */
+    isInoutInPlace?: boolean;
 };
 
 /** What a `runCodegen` run produced. */
@@ -51,6 +58,8 @@ type CodegenRunnerResult = {
     namespaces: number;
     /** How many JSX elements the jsx store binds, zero when no jsx store was requested. */
     intrinsicElements: number;
+    /** Deprecation notices about how the store was wired, one line each; empty when nothing needs attention. */
+    notices: string[];
     /** Wall-clock duration of the run, in milliseconds. */
     duration: number;
 };
@@ -83,6 +92,7 @@ const runCodegen = async (options: CodegenRunnerOptions): Promise<CodegenRunnerR
         isRegenerated: store.isRegenerated,
         namespaces: store.namespaces,
         intrinsicElements: store.intrinsicElements,
+        notices: externalPackageNotices(options.gi),
         duration: Date.now() - start,
     };
 };
@@ -160,13 +170,17 @@ const emitStoresWithConfig = async (config: {
 }): Promise<StoreResult> => {
     const { options, gi, jsx, libraries, girPath } = config;
     const isByteArrayTyped = options.isByteArrayTyped === true;
+    const isValueUnwrapped = options.isValueUnwrapped === true;
+    const isFinishTrimmed = options.isFinishTrimmed === true;
+    const isInoutInPlace = options.isInoutInPlace === true;
+    const future = { isByteArrayTyped, isValueUnwrapped, isFinishTrimmed, isInoutInPlace };
     let library: Library | undefined;
-    const loadLibrary = (): Library => (library ??= Library.load(libraries, girPath, isByteArrayTyped));
-    const giInputs = { girFiles: [] as string[], libraries, girPath, isByteArrayTyped };
+    const loadLibrary = (): Library => (library ??= Library.load(libraries, girPath, future));
+    const giInputs = { girFiles: [] as string[], libraries, girPath, storeVersion: gi.version, ...future };
     const isGiRegenerated = options.isForced === true || !isGiStoreFresh(gi.storeDir, giInputs);
 
     const namespaces = isGiRegenerated
-        ? runGiCodegen(loadLibrary(), { gi, libraries, girPath, isByteArrayTyped })
+        ? runGiCodegen(loadLibrary(), { gi, libraries, girPath, ...future })
         : 0;
 
     if (jsx === undefined) {