@gtkx/codegen 1.0.0-rc.4 → 1.1.0

package/src/fingerprint.ts

@@ -1,9 +1,11 @@
 import { sortStrings } from "@gtkx/utils";
 import { createHash } from "node:crypto";
 import { type Dirent, existsSync, readdirSync, readFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import packageManifest from "../package.json" with { type: "json" };
+import { arrayGuard, hasFields, isNumber, isString, optionalGuard } from "./guards.js";
+import { readJsonFile } from "./json.js";
 
 type GiFingerprint = {
     value: string;
@@ -14,6 +16,17 @@ type GiFingerprint = {
 
 type ModuleExport = { module: string; export: string };
 
+type DocsFingerprintInput = {
+    basePath: string;
+    props: Record<string, ModuleExport>;
+    omittedProps: Record<string, string[]>;
+};
+
+type DocsFingerprint = {
+    value: string;
+    gi: GiFingerprint;
+};
+
 type JsxFingerprintInput = {
     reactVersion: string;
     components: Record<string, ModuleExport>;
@@ -27,9 +40,8 @@ type JsxFingerprint = {
     intrinsicElementCount: number;
 };
 
-const require = createRequire(import.meta.url);
 const FINGERPRINT_FILENAME = ".codegen-fingerprint.json";
-const CODEGEN_VERSION: string = (require("../package.json") as { version: string }).version;
+const CODEGEN_VERSION: string = packageManifest.version;
 const OVERRIDES_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "overrides");
 
 const sortAlpha = (values: string[]): string => sortStrings(values).join(",");
@@ -75,39 +87,87 @@ const computeGiFingerprint = (
     girPath,
 });
 
-const isGiStoreFresh = (
-    giStoreDir: string,
-    libraries: string[],
-    girPath: string[],
-): boolean => {
-    const sentinelPath = join(giStoreDir, FINGERPRINT_FILENAME);
+const readSentinel = (storeDir: string): unknown => readJsonFile(join(storeDir, FINGERPRINT_FILENAME));
 
-    if (!existsSync(sentinelPath)) {
-        return false;
-    }
+const isGiFingerprint = (value: unknown): value is GiFingerprint =>
+    hasFields<GiFingerprint>(value, {
+        value: isString,
+        girFiles: arrayGuard(isString),
+        libraries: arrayGuard(isString),
+        girPath: optionalGuard(arrayGuard(isString)),
+    });
 
-    let sentinel: GiFingerprint;
+const isDocsFingerprint = (value: unknown): value is DocsFingerprint =>
+    hasFields<DocsFingerprint>(value, { value: isString, gi: isGiFingerprint });
 
-    try {
-        sentinel = JSON.parse(readFileSync(sentinelPath, "utf8")) as GiFingerprint;
-    } catch {
-        return false;
-    }
+const isJsxFingerprint = (value: unknown): value is JsxFingerprint =>
+    hasFields<JsxFingerprint>(value, { value: isString, intrinsicElementCount: isNumber });
 
+const recordedGiValue = (sentinel: GiFingerprint, libraries: string[], girPath: string[]): string | undefined => {
     if (!hasMatchingRecordedInputs(sentinel, libraries, girPath)) {
-        return false;
+        return undefined;
     }
 
     try {
-        return hashGi(sentinel.girFiles, sentinel.libraries, girPath) === sentinel.value;
+        return hashGi(sentinel.girFiles, sentinel.libraries, girPath);
     } catch {
-        return false;
+        return undefined;
     }
 };
 
+const isGiStoreFresh = (
+    giStoreDir: string,
+    libraries: string[],
+    girPath: string[],
+): boolean => {
+    const sentinel = readSentinel(giStoreDir);
+
+    return isGiFingerprint(sentinel) && recordedGiValue(sentinel, libraries, girPath) === sentinel.value;
+};
+
 const hasMatchingRecordedInputs = (sentinel: GiFingerprint, libraries: string[], girPath: string[]): boolean =>
     sortAlpha(sentinel.libraries) === sortAlpha(libraries) && sortAlpha(sentinel.girPath ?? []) === sortAlpha(girPath);
 
+const hashDocs = (giValue: string, input: DocsFingerprintInput): string =>
+    createHash("sha256")
+        .update(
+            JSON.stringify([
+                giValue,
+                input.basePath,
+                serializeModuleExports(input.props),
+                serializeOmittedProps(input.omittedProps),
+            ]),
+        )
+        .digest("hex");
+
+const computeDocsFingerprint = (
+    girFiles: string[],
+    libraries: string[],
+    girPath: string[],
+    input: DocsFingerprintInput,
+): DocsFingerprint => {
+    const gi = computeGiFingerprint(girFiles, libraries, girPath);
+
+    return { value: hashDocs(gi.value, input), gi };
+};
+
+const isDocsOutputFresh = (
+    outDir: string,
+    libraries: string[],
+    girPath: string[],
+    input: DocsFingerprintInput,
+): boolean => {
+    const sentinel = readSentinel(outDir);
+
+    if (!isDocsFingerprint(sentinel)) {
+        return false;
+    }
+
+    const giValue = recordedGiValue(sentinel.gi, libraries, girPath);
+
+    return giValue !== undefined && hashDocs(giValue, input) === sentinel.value;
+};
+
 const serializeModuleExports = (map: Record<string, ModuleExport>): [string, string, string][] =>
     sortStrings(Object.keys(map)).map((type) => [type, map[type]?.module ?? "", map[type]?.export ?? ""]);
 
@@ -137,17 +197,9 @@ const jsxStoreFreshness = (
     jsxStoreDir: string,
     input: JsxFingerprintInput,
 ): { isFresh: boolean; intrinsicElementCount: number } => {
-    const sentinelPath = join(jsxStoreDir, FINGERPRINT_FILENAME);
-
-    if (!existsSync(sentinelPath)) {
-        return { isFresh: false, intrinsicElementCount: 0 };
-    }
+    const sentinel = readSentinel(jsxStoreDir);
 
-    let sentinel: JsxFingerprint;
-
-    try {
-        sentinel = JSON.parse(readFileSync(sentinelPath, "utf8")) as JsxFingerprint;
-    } catch {
+    if (!isJsxFingerprint(sentinel)) {
         return { isFresh: false, intrinsicElementCount: 0 };
     }
 
@@ -159,10 +211,12 @@ const jsxStoreFreshness = (
 export {
     FINGERPRINT_FILENAME,
     computeGiFingerprint,
+    computeDocsFingerprint,
     isGiStoreFresh,
+    isDocsOutputFresh,
     computeJsxFingerprint,
     jsxStoreFreshness,
+    type DocsFingerprintInput,
     type GiFingerprint,
     type JsxFingerprintInput,
-    type JsxFingerprint,
 };

package/src/gi.ts

@@ -17,6 +17,7 @@ const runGiCodegen = (library: Library, options: GiCodegenOptions): number => {
     const namespaces: GiNamespaceInput[] = Array.from(library.namespaces.values(), (namespace) => ({
         directory: namespaceDirectory(namespace),
         rawSource: generateNamespaceModule(namespace, library),
+        girFile: namespace.girFile,
     }));
 
     const fingerprint = computeGiFingerprint(library.girFiles, [...libraries], [...girPath]);

package/src/gir/ancestry.ts

@@ -1,12 +1,28 @@
 import type { GirClass } from "./class.js";
 import type { Library } from "./library.js";
 import type { GirType } from "./type.js";
+import { splitOptionalNamespace } from "./type-ref.js";
 
 type ResolvedAncestor = {
     klass: GirClass;
     namespaceName: string;
 };
 
+type ParentRef = {
+    namespaceName: string | undefined;
+    typeName: string;
+};
+
+const getParentRef = (klass: GirClass): ParentRef | undefined => {
+    if (klass.parent === undefined) {
+        return undefined;
+    }
+
+    const [namespaceName, typeName] = splitOptionalNamespace(klass.parent);
+
+    return { namespaceName, typeName };
+};
+
 const getAncestor = (resolved: GirType | undefined): ResolvedAncestor | undefined =>
     resolved !== undefined && (resolved.kind === "class" || resolved.kind === "interface")
         ? { klass: resolved.value, namespaceName: resolved.namespace.name }
@@ -28,6 +44,20 @@ const resolveInterface = (
     return resolved?.kind === "interface" ? getAncestor(resolved) : undefined;
 };
 
+const resolveInterfaces = (library: Library, defaultNamespace: string, names: string[]): ResolvedAncestor[] => {
+    const interfaces: ResolvedAncestor[] = [];
+
+    for (const name of names) {
+        const iface = resolveInterface(library, defaultNamespace, name);
+
+        if (iface !== undefined) {
+            interfaces.push(iface);
+        }
+    }
+
+    return interfaces;
+};
+
 function* ancestorChain(library: Library, klass: GirClass, namespaceName: string): Generator<ResolvedAncestor> {
     const visited: Set<string> = new Set();
     let current: ResolvedAncestor | undefined = { klass, namespaceName };
@@ -50,4 +80,4 @@ function* ancestorChain(library: Library, klass: GirClass, namespaceName: string
     }
 }
 
-export { resolveInterface, ancestorChain, type ResolvedAncestor };
+export { resolveClassOrInterface, resolveInterfaces, ancestorChain, getParentRef, type ResolvedAncestor };

package/src/gir/annotations.ts

@@ -0,0 +1,37 @@
+import { attr, getDoc, getDocDeprecated, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
+
+/** Release and deprecation annotations GIR carries on a documentable element. */
+type GirAnnotations = {
+    /** Library release the symbol appeared in, from the `version` attribute. */
+    since: string | undefined;
+    /** Whether GIR marks the symbol deprecated. */
+    isDeprecated: boolean;
+    /** Release the symbol was deprecated in, from the `deprecated-version` attribute. */
+    deprecatedSince: string | undefined;
+    /** Prose from `<doc-deprecated>` naming what to use instead. */
+    deprecationDoc: string | undefined;
+};
+
+type DocumentedNode = {
+    name: string;
+    doc: string | undefined;
+    annotations: GirAnnotations;
+};
+
+const annotationsFromNode = (node: RawNode | undefined): GirAnnotations => ({
+    since: attr(node, "version"),
+    isDeprecated: isAttrTrue(node, "deprecated"),
+    deprecatedSince: attr(node, "deprecated-version"),
+    deprecationDoc: getDocDeprecated(node),
+});
+
+const documentedFromNode = (node: RawNode): DocumentedNode => ({
+    name: nameAttr(node),
+    doc: getDoc(node),
+    annotations: annotationsFromNode(node),
+});
+
+const hasAnnotations = (annotations: GirAnnotations): boolean =>
+    annotations.since !== undefined || annotations.isDeprecated || annotations.deprecatedSince !== undefined;
+
+export { documentedFromNode, hasAnnotations, type GirAnnotations };

package/src/gir/callback.ts

@@ -3,6 +3,7 @@ import type { RawNode } from "./parse.js";
 import type { ParseContext } from "./type-id.js";
 import { type GirCallable, parseCallable } from "./parameter.js";
 
+/** The signature of a function pointer type GIR declares, whether named or anonymous. */
 type GirCallback = GirCallable;
 
 const callbackFromNode = (node: RawNode, context: ParseContext): GirCallback => parseCallable(node, context);
@@ -10,6 +11,7 @@ const callbackFromNode = (node: RawNode, context: ParseContext): GirCallback =>
 const callbackAsFunction = (callback: GirCallback): GirFunction => ({
     name: callback.name,
     doc: callback.doc,
+    annotations: callback.annotations,
     cIdentifier: undefined,
     movedTo: undefined,
     throws: callback.throws,

package/src/gir/class.ts

@@ -1,35 +1,72 @@
 import type { ParseContext } from "./type-id.js";
+import { documentedFromNode, type GirAnnotations } from "./annotations.js";
 import { functionFromNode, type GirFunction } from "./function.js";
 import { type GirCallable, parseCallable } from "./parameter.js";
-import { attr, getChildren, getDoc, GIR_CONSTRUCTOR_TAG, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
+import { attr, getChildren, GIR_CONSTRUCTOR_TAG, isAttrTrue, type RawNode } from "./parse.js";
 import { type GirProperty, propertyFromNode } from "./property.js";
 
+/** A `<virtual-method>` on a class or interface: the vtable slot's own documentation and signature. */
+type GirVirtualMethod = GirCallable & {
+    /** Method GIR names as invoking this slot, absent when the slot has no invoker. */
+    invoker: string | undefined;
+};
+
+/** A `<class>` or `<interface>` declared by a GIR namespace. */
 type GirClass = {
+    /** Name GIR gives the type, without its namespace prefix. */
     name: string;
+    /** Documentation GIR carries for the type. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the type. */
+    annotations: GirAnnotations;
+    /** C type of an instance, such as `GtkWidget`. */
     cType: string | undefined;
+    /** The class it derives from, qualified when it lives in another namespace. */
     parent: string | undefined;
+    /** GType name the type registers under, such as `GtkWidget`. */
     glibTypeName: string | undefined;
+    /** C function returning the GType, such as `gtk_widget_get_type`. */
     glibGetType: string | undefined;
+    /** Record holding the class or interface vtable, which virtual method bindings are laid out against. */
     glibTypeStruct: string | undefined;
+    /** C function that takes a reference, on a type that manages its own refcount. */
     glibRefFunc: string | undefined;
+    /** C function that drops a reference, on a type that manages its own refcount. */
     glibUnrefFunc: string | undefined;
+    /** Whether the type is its own GType fundamental rather than a GObject descendant. */
     fundamental: boolean;
+    /** Whether the class cannot be instantiated on its own. */
     isAbstract: boolean;
+    /** Whether the type came from an `<interface>` rather than a `<class>`. */
     isInterface: boolean;
+    /** Whether GIR exposes the type to bindings; codegen skips it when false. */
     introspectable: boolean;
+    /** Interfaces the class implements. */
     implements: string[];
+    /** Types an implementer of this interface must also provide. */
     prerequisites: string[];
+    /** Methods taking an instance. */
     methods: GirFunction[];
+    /** Functions returning a new instance. */
     constructors: GirFunction[];
+    /** Functions namespaced under the type that take no instance. */
     functions: GirFunction[];
+    /** GObject properties the type declares. */
     properties: GirProperty[];
+    /** GObject signals the type declares. */
     signals: GirCallable[];
+    /** Virtual methods the type declares, carrying the documentation their vtable slots are generated from. */
+    vfuncs: GirVirtualMethod[];
 };
 
+const virtualMethodsFromNode = (node: RawNode, context: ParseContext): GirVirtualMethod[] =>
+    getChildren(node, "virtual-method").map((vfunc) => ({
+        ...parseCallable(vfunc, context),
+        invoker: attr(vfunc, "invoker"),
+    }));
+
 const classFromNode = (node: RawNode, isInterface: boolean, context: ParseContext): GirClass => ({
-    name: nameAttr(node),
-    doc: getDoc(node),
+    ...documentedFromNode(node),
     cType: attr(node, "c:type"),
     parent: attr(node, "parent"),
     glibTypeName: attr(node, "glib:type-name"),
@@ -52,6 +89,7 @@ const classFromNode = (node: RawNode, isInterface: boolean, context: ParseContex
     functions: getChildren(node, "function").map((fn) => functionFromNode(fn, context)),
     properties: getChildren(node, "property").map((property) => propertyFromNode(property, context)),
     signals: getChildren(node, "glib:signal").map((signal) => parseCallable(signal, context)),
+    vfuncs: virtualMethodsFromNode(node, context),
 });
 
-export { classFromNode, type GirClass };
+export { classFromNode, type GirClass, type GirVirtualMethod };

package/src/gir/cursor-overrides.ts

@@ -0,0 +1,12 @@
+type CursorParameterNames = {
+    cursor: string;
+    base: string;
+    length: string;
+};
+
+const PARAMETERS_MISSING_ARRAY_EXTENT: Map<string, CursorParameterNames[]> = new Map([
+    ["g_utf8_validate", [{ cursor: "end", base: "str", length: "max_len" }]],
+    ["g_utf8_validate_len", [{ cursor: "end", base: "str", length: "max_len" }]],
+]);
+
+export { PARAMETERS_MISSING_ARRAY_EXTENT, type CursorParameterNames };

package/src/gir/emittable.ts

@@ -0,0 +1,8 @@
+type NamedEntity = {
+    name: string;
+    introspectable?: boolean | undefined;
+};
+
+const isEmittableEntity = (entity: NamedEntity): boolean => entity.name.length > 0 && entity.introspectable !== false;
+
+export { isEmittableEntity };

package/src/gir/enum.ts

@@ -1,39 +1,59 @@
-import { attr, getChildren, getDoc, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
+import { documentedFromNode, type GirAnnotations } from "./annotations.js";
+import { attr, getChildren, isAttrTrue, type RawNode } from "./parse.js";
 
+/** One member of a {@link GirEnum}. */
 type EnumMember = {
+    /** The member's GIR name, which the emitted key is derived from. */
     name: string;
+    /** Documentation prose from GIR, emitted as the member's JSDoc. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the member. */
+    annotations: GirAnnotations;
+    /** The member's numeric value, `0` when GIR declares none. */
     value: string;
+    /** C constant the member is exposed as, such as `GTK_ORIENTATION_HORIZONTAL`. */
     cIdentifier: string | undefined;
 };
 
+/** Whether an enum is a plain enumeration or a bitfield of flags. */
 type EnumKind = "enumeration" | "bitfield";
 
+/** An enumeration or bitfield declared by a GIR namespace. */
 type GirEnum = {
+    /** Whether the declaration is a plain enumeration or a bitfield. */
     kind: EnumKind;
+    /** Name the enum is exported under, without its namespace prefix. */
     name: string;
+    /** Documentation prose from GIR, emitted as the enum's JSDoc. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the enum. */
+    annotations: GirAnnotations;
+    /** GType name of the enum, absent when it is not registered with GLib. */
     glibTypeName: string | undefined;
+    /** C function returning the enum's GType, absent when it is not registered with GLib. */
     glibGetType: string | undefined;
+    /** Quark name of the GError domain the members are codes of, absent on enums that carry no domain. */
     errorDomain: string | undefined;
+    /** Whether the enum is introspectable; code generation skips the ones that are not. */
     introspectable: boolean;
+    /** The enum's members, in declaration order. */
     members: EnumMember[];
 };
 
+const enumMemberFromNode = (node: RawNode): EnumMember => ({
+    ...documentedFromNode(node),
+    value: attr(node, "value") ?? "0",
+    cIdentifier: attr(node, "c:identifier"),
+});
+
 const enumFromNode = (node: RawNode, kind: EnumKind): GirEnum => ({
     kind,
-    name: nameAttr(node),
-    doc: getDoc(node),
+    ...documentedFromNode(node),
     glibTypeName: attr(node, "glib:type-name"),
     glibGetType: attr(node, "glib:get-type"),
     errorDomain: attr(node, "glib:error-domain"),
     introspectable: isAttrTrue(node, "introspectable", true),
-    members: getChildren(node, "member").map((member) => ({
-        name: nameAttr(member),
-        doc: getDoc(member),
-        value: attr(member, "value") ?? "0",
-        cIdentifier: attr(member, "c:identifier"),
-    })),
+    members: getChildren(node, "member").map((member) => enumMemberFromNode(member)),
 });
 
-export { enumFromNode, type GirEnum };
+export { enumFromNode, type EnumMember, type GirEnum };

package/src/gir/field.ts

@@ -1,23 +1,39 @@
 import type { ParseContext, TypeId } from "./type-id.js";
-import { attr, getChild, getChildren, getDoc, intAttr, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
+import { documentedFromNode, type GirAnnotations } from "./annotations.js";
+import { attr, getChild, getChildren, intAttr, isAttrTrue, type RawNode } from "./parse.js";
 import { typeRefFromNode } from "./type-ref.js";
 
+/**
+ * One slot in a record or union layout: a named field, or a nested struct or union
+ * whose own members are laid out inline.
+ */
 type GirField = {
+    /** Field name as GIR spells it. */
     name: string;
+    /** Documentation prose from GIR, emitted as the field accessor's JSDoc. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the field. */
+    annotations: GirAnnotations;
+    /** The field's value type, absent for a nested struct or union and for one GIR leaves undeclared. */
     type: TypeId | undefined;
+    /** The C type spelled on the field, which decides whether it is read through a pointer. */
     cType: string | undefined;
+    /** Whether the field can be read; one that is neither readable nor writable gets no accessor at all. */
     readable: boolean;
+    /** Whether the field can be written, which is what earns it a setter alongside its getter. */
     writable: boolean;
+    /** Whether the field is private to the library, as every nested struct or union is. */
     private: boolean;
+    /** Width in bits when the field is a C bitfield member. */
     bits: number | undefined;
+    /** Members of a nested struct or union, absent for a named field. */
     inlineMembers: GirField[] | undefined;
-    inlineIsUnion: boolean;
+    /** Whether {@link GirField.inlineMembers} overlap as a union rather than following one another as a struct. */
+    isInlineUnion: boolean;
 };
 
 const fieldFromNode = (node: RawNode, context: ParseContext): GirField => ({
-    name: nameAttr(node),
-    doc: getDoc(node),
+    ...documentedFromNode(node),
     type: typeRefFromNode(node, context),
     cType: attr(getChild(node, "type"), "c:type"),
     readable: isAttrTrue(node, "readable", true),
@@ -25,12 +41,11 @@ const fieldFromNode = (node: RawNode, context: ParseContext): GirField => ({
     private: isAttrTrue(node, "private", false),
     bits: intAttr(node, "bits"),
     inlineMembers: undefined,
-    inlineIsUnion: false,
+    isInlineUnion: false,
 });
 
 const anonymousMemberFromNode = (node: RawNode, isUnion: boolean, context: ParseContext): GirField => ({
-    name: nameAttr(node),
-    doc: getDoc(node),
+    ...documentedFromNode(node),
     type: undefined,
     cType: undefined,
     readable: false,
@@ -38,7 +53,7 @@ const anonymousMemberFromNode = (node: RawNode, isUnion: boolean, context: Parse
     private: true,
     bits: undefined,
     inlineMembers: collectFields(node, context),
-    inlineIsUnion: isUnion,
+    isInlineUnion: isUnion,
 });
 
 const collectFields = (node: RawNode, context: ParseContext): GirField[] => [
@@ -47,4 +62,4 @@ const collectFields = (node: RawNode, context: ParseContext): GirField[] => [
     ...getChildren(node, "record").map((member) => anonymousMemberFromNode(member, false, context)),
 ];
 
-export { collectFields, fieldFromNode, type GirField };
+export { collectFields, type GirField };

package/src/gir/function.ts

@@ -1,19 +1,35 @@
+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 { 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";
 
+/** A callable declared by a GIR namespace, class, or record: a function, a method, or a constructor. */
 type GirFunction = {
+    /** Local name within its owner, taken from the `shadows` annotation when the callable has one. */
     name: string;
+    /** Documentation text carried by the GIR node. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the callable. */
+    annotations: GirAnnotations;
+    /** C symbol the callable is invoked through. */
     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. */
     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`. */
     finishFunc: string | undefined;
+    /** The instance the callable is invoked on, absent for constructors and namespace-level functions. */
     instance: GirParameter | undefined;
+    /** Parameters other than the instance one, in declaration order. */
     parameters: GirParameter[];
+    /** What the callable returns, with its transfer and nullability. */
     returnValue: GirReturnValue;
 };
 
@@ -35,18 +51,53 @@ const relaxMissingNullable = (fn: GirFunction): GirFunction => {
     return fn;
 };
 
+const parameterIndexFor = (parameters: GirParameter[], name: string): number => {
+    const index = parameters.findIndex((parameter) => parameter.name === name);
+
+    if (index === -1) {
+        throw new Error(`A cursor correction names a parameter the GIR does not declare: ${name}`);
+    }
+
+    return index;
+};
+
+const bindCursorParameters = (parameters: GirParameter[], corrections: CursorParameterNames[]): void => {
+    for (const names of corrections) {
+        const parameter = parameters[parameterIndexFor(parameters, names.cursor)];
+
+        if (parameter !== undefined) {
+            parameter.cursor = {
+                baseIndex: parameterIndexFor(parameters, names.base),
+                lengthIndex: parameterIndexFor(parameters, names.length),
+            };
+        }
+    }
+};
+
+const bindMissingArrayExtent = (fn: GirFunction): GirFunction => {
+    const corrections = fn.cIdentifier === undefined ? undefined : PARAMETERS_MISSING_ARRAY_EXTENT.get(fn.cIdentifier);
+
+    if (corrections !== undefined) {
+        bindCursorParameters(fn.parameters, corrections);
+    }
+
+    return fn;
+};
+
 const functionFromNode = (node: RawNode, context: ParseContext): GirFunction => {
     const instanceNode = getChild(getChild(node, "parameters"), "instance-parameter");
 
-    return 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),
-    });
+    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),
+        }),
+    );
 };
 
 export { functionFromNode, type GirFunction };