@gtkx/codegen 1.0.0-rc.3 → 1.0.0

package/src/analysis/descriptor.ts

@@ -64,23 +64,23 @@ type BoxedOptions = {
     ownership: Ownership;
     sharedLibrary: string | undefined;
     getTypeFnName: string;
-    callerAllocated: boolean;
-    inline?: boolean;
+    isCallerAllocated: boolean;
+    isInline?: boolean;
     size: number | undefined;
 };
 
 type StructOptions = {
     size: number | string | undefined;
     wrapperClass: string | undefined;
-    callerAllocated: boolean;
-    inline?: boolean;
+    isCallerAllocated: boolean;
+    isInline?: boolean;
 };
 
 type FundamentalOptions = {
     ownership: Ownership;
     typeName: string | undefined;
     wrapperClass: string | undefined;
-    inline?: boolean | undefined;
+    isInline?: boolean | undefined;
 };
 
 type ListDescriptorName = "list" | "slist" | "ptrArray" | "gArray";
@@ -165,8 +165,8 @@ const tBoxed = (glibName: string, options: BoxedOptions): string =>
                 ? undefined
                 : `sharedLibrary: ${sourceStringLiteral(options.sharedLibrary)}`,
             `getTypeFnName: ${sourceStringLiteral(options.getTypeFnName)}`,
-            options.callerAllocated ? "callerAllocated: true" : undefined,
-            options.inline === true ? "inline: true" : undefined,
+            options.isCallerAllocated ? "isCallerAllocated: true" : undefined,
+            options.isInline === true ? "isInline: true" : undefined,
             options.size === undefined ? undefined : `size: ${String(options.size)}`,
         ]),
     ]);
@@ -177,13 +177,13 @@ const tStruct = (ownership: Ownership, options: StructOptions): string =>
         optionsObject([
             options.size === undefined ? undefined : `size: ${String(options.size)}`,
             options.wrapperClass === undefined ? undefined : `wrapperClass: ${options.wrapperClass}`,
-            options.callerAllocated ? "callerAllocated: true" : undefined,
-            options.inline === true ? "inline: true" : undefined,
+            options.isCallerAllocated ? "isCallerAllocated: true" : undefined,
+            options.isInline === true ? "isInline: true" : undefined,
         ]),
     ]);
 
 const tInlineStruct = (): string =>
-    tStruct("borrowed", { size: undefined, wrapperClass: undefined, callerAllocated: false });
+    tStruct("borrowed", { size: undefined, wrapperClass: undefined, isCallerAllocated: false });
 
 const tFundamental = (lib: string, refFunc: string, unrefFunc: string, options: FundamentalOptions): string =>
     call("fundamental", [
@@ -194,7 +194,7 @@ const tFundamental = (lib: string, refFunc: string, unrefFunc: string, options:
             `ownership: ${sourceStringLiteral(options.ownership)}`,
             options.typeName === undefined ? undefined : `typeName: ${sourceStringLiteral(options.typeName)}`,
             options.wrapperClass === undefined ? undefined : `wrapperClass: ${options.wrapperClass}`,
-            options.inline === true ? "inline: true" : undefined,
+            options.isInline === true ? "isInline: true" : undefined,
         ]),
     ]);
 
@@ -252,9 +252,9 @@ const tBind = (args: BindArgs): string =>
 const tFn = (
     lib: string,
     cIdentifier: string,
-    spec: { args: string; returns: string; throws: boolean },
+    spec: { args: string; returns: string; canThrow: boolean },
 ): string => {
-    const throwsEntry = spec.throws ? ", throws: true" : "";
+    const throwsEntry = spec.canThrow ? ", canThrow: true" : "";
 
     return call("fn", [
         sourceStringLiteral(lib),
@@ -293,8 +293,5 @@ export {
     tFn,
     type Ownership,
     type ScalarDescriptorName,
-    type BoxedOptions,
-    type StructOptions,
-    type FundamentalOptions,
     type ListDescriptorName,
 };

package/src/analysis/inheritance.ts

@@ -5,9 +5,10 @@ import type { Library } from "../gir/library.js";
 import type { GirProperty } from "../gir/property.js";
 import type { TypeId } from "../gir/type-id.js";
 import type { ModuleContext } from "../writer/context.js";
-import { ancestorChain, type ResolvedAncestor, resolveInterface } from "../gir/ancestry.js";
+import { ancestorChain, type ResolvedAncestor, resolveInterfaces } from "../gir/ancestry.js";
 import { methodExportName } from "../store/gi/method.js";
 import { resolveAccessorType } from "../store/gi/property-accessor.js";
+import { vfuncMemberNames } from "../store/gi/vtable.js";
 import { inputParameters } from "./param-structure.js";
 import { renderTsType } from "./ts-type.js";
 
@@ -45,29 +46,11 @@ const RESERVED_SIGNAL_MEMBERS = new Set([
     "removeEventListener",
 ]);
 
-const resolveImplementedInterface = (
-    context: AncestryContext,
-    name: string,
-    defaultNamespace: string = context.namespace.name,
-): ResolvedAncestor | undefined => resolveInterface(context.library, defaultNamespace, name);
-
 const resolveDirectInterfaces = (
     context: AncestryContext,
     klass: GirClass,
     defaultNamespace: string,
-): ResolvedAncestor[] => {
-    const interfaces: ResolvedAncestor[] = [];
-
-    for (const implementName of klass.implements) {
-        const iface = resolveImplementedInterface(context, implementName, defaultNamespace);
-
-        if (iface !== undefined) {
-            interfaces.push(iface);
-        }
-    }
-
-    return interfaces;
-};
+): ResolvedAncestor[] => resolveInterfaces(context.library, defaultNamespace, klass.implements);
 
 const resolvePrerequisiteReference = (context: ModuleContext, name: string): string | undefined => {
     const resolved = context.library.resolveType(context.namespace.name, name);
@@ -221,25 +204,45 @@ const mergeOmissionName = (
     return ancestor.returnType !== returnType || ancestor.arity !== arity ? name : undefined;
 };
 
-const collectInterfaceMergeOmissions = (
+const classChainVfuncNames = (context: ModuleContext, klass: GirClass): Set<string> => {
+    const names: Set<string> = new Set(vfuncMemberNames(context, context.namespace.name, klass));
+
+    forEachAncestor(context, klass, (ancestor) => {
+        for (const name of vfuncMemberNames(context, ancestor.namespaceName, ancestor.klass)) {
+            names.add(name);
+        }
+    });
+
+    return names;
+};
+
+const methodMergeOmissions = (context: ModuleContext, klass: GirClass, iface: GirClass): string[] => {
+    const ancestors = ancestorClassMethodSignatures(context, klass);
+
+    return iface.methods
+        .map((method) => mergeOmissionName(context, method, ancestors))
+        .filter((name): name is string => name !== undefined);
+};
+
+const vfuncMergeOmissions = (
     context: ModuleContext,
     klass: GirClass,
     iface: { klass: GirClass; namespaceName: string },
 ): string[] => {
-    const ancestors = ancestorClassMethodSignatures(context, klass);
-    const omissions: string[] = [];
+    const claimed = classChainVfuncNames(context, klass);
 
-    for (const method of iface.klass.methods) {
-        const name = mergeOmissionName(context, method, ancestors);
-
-        if (name !== undefined) {
-            omissions.push(name);
-        }
-    }
-
-    return omissions;
+    return vfuncMemberNames(context, iface.namespaceName, iface.klass).filter((name) => claimed.has(name));
 };
 
+const collectInterfaceMergeOmissions = (
+    context: ModuleContext,
+    klass: GirClass,
+    iface: { klass: GirClass; namespaceName: string },
+): string[] => [
+    ...methodMergeOmissions(context, klass, iface.klass),
+    ...vfuncMergeOmissions(context, klass, iface),
+];
+
 const collectInheritedPropertyTypes = (context: ModuleContext, klass: GirClass): Map<string, string> => {
     const types: Map<string, string> = new Map();
 
@@ -416,7 +419,6 @@ const enumIdentity = (context: ModuleContext, ref: TypeId | undefined): string |
 };
 
 export {
-    resolveImplementedInterface,
     resolvePrerequisiteReference,
     forEachAncestor,
     collectInterfaceProperties,
@@ -425,6 +427,5 @@ export {
     collectInheritedMethods,
     conflictRename,
     reservedSignalMemberRename,
-    type OwnedProperty,
     type InheritedMethods,
 };

package/src/analysis/nul-terminated-bytes.ts

@@ -0,0 +1,31 @@
+import type { Library } from "../gir/library.js";
+import type { GirCallable, GirParameter } from "../gir/parameter.js";
+import type { TypeId } from "../gir/type-id.js";
+import { isOutParameter } from "../gir/parameter.js";
+import { carrayFor, isUnboundedArray, primitiveCategoryFor } from "./type-shape.js";
+
+const BYTE_CATEGORIES: Set<string> = new Set(["int8", "uint8"]);
+const CHAR_POINTER = /char\s*\*/;
+
+const isByteElement = (library: Library, element: TypeId): boolean => {
+    const category = primitiveCategoryFor(library, element);
+
+    return category !== undefined && BYTE_CATEGORIES.has(category);
+};
+
+const isNulTerminatedBytes = (library: Library, ref: TypeId | undefined): boolean => {
+    const type = carrayFor(library, ref);
+
+    if (type?.arrayCType === undefined || !CHAR_POINTER.test(type.arrayCType)) {
+        return false;
+    }
+
+    return isUnboundedArray(type) && isByteElement(library, type.element);
+};
+
+const nulTerminatedByteParams = (library: Library, callable: GirCallable): GirParameter[] =>
+    callable.parameters.filter(
+        (parameter) => !isOutParameter(parameter) && isNulTerminatedBytes(library, parameter.type),
+    );
+
+export { nulTerminatedByteParams };

package/src/analysis/param-capability.ts

@@ -0,0 +1,172 @@
+import type { GirCallable, GirParameter } from "../gir/parameter.js";
+import type { CArrayType, TypeId } from "../gir/type-id.js";
+import type { GirType } from "../gir/type.js";
+import type { ModuleContext } from "../writer/context.js";
+import { isCallerAllocatedOut, isInoutParameter } from "../gir/parameter.js";
+import { constructibleName } from "../store/gi/method.js";
+import { isCollectibleCallerOut, isHandlePassedInPlace, underlyingType } from "../store/gi/param-marshal.js";
+import { isScalarRef, recordInlineSize } from "./descriptor-render.js";
+
+const POINTER_DEPTH = 1;
+
+const isPointerType = (context: ModuleContext, type: GirType): boolean => {
+    switch (type.kind) {
+        case "primitive": {
+            return type.category === "string";
+        }
+        case "record": {
+            return recordInlineSize(context, type.value) === undefined;
+        }
+        case "class":
+        case "interface":
+        case "carray":
+        case "list":
+        case "hashtable": {
+            return true;
+        }
+        case "alias":
+        case "callback":
+        case "enum":
+        case "varargs": {
+            return false;
+        }
+    }
+};
+
+const isPointerElement = (context: ModuleContext, element: TypeId): boolean => {
+    if (isScalarRef(context.library, element)) {
+        return false;
+    }
+
+    const type = underlyingType(context, element);
+
+    return type !== undefined && isPointerType(context, type);
+};
+
+const carrayIndirection = (context: ModuleContext, type: CArrayType): number =>
+    POINTER_DEPTH + (isPointerElement(context, type.element) ? POINTER_DEPTH : 0);
+
+const typeIndirection = (context: ModuleContext, type: GirType): number | undefined => {
+    switch (type.kind) {
+        case "primitive": {
+            return type.category === "string" ? POINTER_DEPTH : undefined;
+        }
+        case "callback":
+        case "class":
+        case "hashtable":
+        case "interface":
+        case "list":
+        case "record": {
+            return POINTER_DEPTH;
+        }
+        case "carray": {
+            return carrayIndirection(context, type);
+        }
+        case "alias":
+        case "enum":
+        case "varargs": {
+            return undefined;
+        }
+    }
+};
+
+const baseIndirection = (context: ModuleContext, ref: TypeId | undefined): number | undefined => {
+    if (isScalarRef(context.library, ref)) {
+        return 0;
+    }
+
+    const type = ref === undefined ? undefined : underlyingType(context, ref);
+
+    return type === undefined ? undefined : typeIndirection(context, type);
+};
+
+const declaredIndirection = (parameter: GirParameter): number | undefined => {
+    const cType = parameter.cType;
+
+    if (cType === undefined) {
+        return undefined;
+    }
+
+    return cType.split("*").length - 1;
+};
+
+const marshalledIndirection = (context: ModuleContext, parameter: GirParameter): number | undefined => {
+    const base = baseIndirection(context, parameter.type);
+
+    if (base === undefined) {
+        return undefined;
+    }
+
+    if (isCallerAllocatedOut(parameter) || isHandlePassedInPlace(context, parameter)) {
+        return base;
+    }
+
+    if (isInoutParameter(parameter) && !isScalarRef(context.library, parameter.type)) {
+        return base;
+    }
+
+    return base + POINTER_DEPTH;
+};
+
+const hasCallerSuppliedLength = (context: ModuleContext, parameter: GirParameter): boolean => {
+    const type = parameter.type === undefined ? undefined : underlyingType(context, parameter.type);
+
+    return type?.kind === "carray" && type.lengthParameterIndex !== undefined;
+};
+
+const isUnbuildableCallerOut = (context: ModuleContext, parameter: GirParameter): boolean =>
+    constructibleName(context, parameter.type) === undefined || !isCollectibleCallerOut(context, parameter);
+
+const isUnmarshalableCallerOut = (context: ModuleContext, parameter: GirParameter): boolean => {
+    if (hasCallerSuppliedLength(context, parameter)) {
+        return true;
+    }
+
+    return isUnbuildableCallerOut(context, parameter) && !parameter.optional;
+};
+
+const hasIndirectionMismatch = (context: ModuleContext, parameter: GirParameter): boolean => {
+    const declared = declaredIndirection(parameter);
+    const marshalled = marshalledIndirection(context, parameter);
+
+    if (declared === undefined || marshalled === undefined) {
+        return false;
+    }
+
+    return declared !== marshalled;
+};
+
+const isTypeErasedCallback = (context: ModuleContext, parameter: GirParameter): boolean => {
+    if (parameter.closureIndex === undefined) {
+        return false;
+    }
+
+    const type = parameter.type === undefined ? undefined : underlyingType(context, parameter.type);
+
+    return type?.kind === "callback" && type.value.parameters.length === 0;
+};
+
+const isUnmarshalableCallParam = (context: ModuleContext, parameter: GirParameter): boolean => {
+    if (parameter.isVarargs) {
+        return false;
+    }
+
+    if (isTypeErasedCallback(context, parameter)) {
+        return true;
+    }
+
+    if (parameter.direction === "in") {
+        return false;
+    }
+
+    if (isCallerAllocatedOut(parameter)) {
+        return isUnmarshalableCallerOut(context, parameter);
+    }
+
+    return hasIndirectionMismatch(context, parameter);
+};
+
+const hasUnmarshalableParam = (context: ModuleContext, callable: GirCallable): boolean =>
+    callable.parameters.some((parameter) => isUnmarshalableCallParam(context, parameter));
+
+export { hasUnmarshalableParam };

package/src/analysis/param-structure.ts

@@ -2,6 +2,7 @@ import { toCamelIdentifier } from "@gtkx/utils";
 import type { GirFunction } from "../gir/function.js";
 import type { Library } from "../gir/library.js";
 import type { TypeId } from "../gir/type-id.js";
+import type { JsDocParam } from "../writer/doc-tags.js";
 import { type GirCallable, type GirParameter, isCallerAllocatedOut, isOutParameter } from "../gir/parameter.js";
 import { isCellInout, shouldOmitPrimaryReturn } from "./descriptor-render.js";
 
@@ -14,8 +15,9 @@ type HandlerResultOptions = {
     library: Library;
     signal: GirCallable;
     renderType: (ref: TypeId | undefined, isNullable: boolean) => string;
-    includeCallerAllocated: boolean;
-    optOut: boolean;
+    shouldIncludeCallerAllocated: boolean;
+    isOptOut: boolean;
+    shouldExcludeOut?: (parameter: GirParameter) => boolean;
 };
 
 const isInputParameter = (options: {
@@ -75,8 +77,6 @@ const closureAndDestroyIndices = (fn: GirFunction): Set<number> => {
     return indices;
 };
 
-// The emitted argument list is the instance parameter followed by every parameter `planParameter`
-// keeps, so a GIR index only lines up with an emitted index when nothing before it was dropped.
 const emittedArgIndices = (fn: GirFunction, instanceOffset: number): Map<number, number> => {
     const closureIndices = closureAndDestroyIndices(fn);
     const map: Map<number, number> = new Map();
@@ -110,7 +110,7 @@ const carrayLengthIndex = (library: Library, ref: TypeId | undefined): number |
     return type.lengthParameterIndex;
 };
 
-const arrayLengthSources = (library: Library, fn: GirFunction): Map<number, number> => {
+const arrayLengthSources = (library: Library, fn: GirCallable): Map<number, number> => {
     const map: Map<number, number> = new Map();
 
     for (const [index, parameter] of fn.parameters.entries()) {
@@ -124,19 +124,7 @@ const arrayLengthSources = (library: Library, fn: GirFunction): Map<number, numb
     return map;
 };
 
-const hasCallerAllocatedArrayLength = (library: Library, fn: GirFunction): boolean => {
-    for (const arrayIndex of arrayLengthSources(library, fn).values()) {
-        const array = fn.parameters[arrayIndex];
-
-        if (array !== undefined && isCallerAllocatedOut(array)) {
-            return true;
-        }
-    }
-
-    return false;
-};
-
-const returnArrayLengthIndices = (library: Library, fn: GirFunction): Set<number> => {
+const returnArrayLengthIndices = (library: Library, fn: GirCallable): Set<number> => {
     const returnType = fn.returnValue.type === undefined ? undefined : library.typeFor(fn.returnValue.type);
 
     if (returnType?.kind !== "carray") {
@@ -152,7 +140,7 @@ const returnArrayLengthIndices = (library: Library, fn: GirFunction): Set<number
     return new Set([lengthIndex]);
 };
 
-const foldedLengthIndices = (library: Library, fn: GirFunction): Set<number> => {
+const foldedLengthIndices = (library: Library, fn: GirCallable): Set<number> => {
     const indices: Set<number> = new Set(arrayLengthSources(library, fn).keys());
 
     for (const index of returnArrayLengthIndices(library, fn)) {
@@ -162,6 +150,20 @@ const foldedLengthIndices = (library: Library, fn: GirFunction): Set<number> =>
     return indices;
 };
 
+const foldedLengthParameters = (library: Library, fn: GirCallable): Set<GirParameter> => {
+    const folded: Set<GirParameter> = new Set();
+
+    for (const index of foldedLengthIndices(library, fn)) {
+        const parameter = fn.parameters[index];
+
+        if (parameter !== undefined) {
+            folded.add(parameter);
+        }
+    }
+
+    return folded;
+};
+
 const parameterIdentifier = (parameter: GirParameter, index: number): string => {
     if (parameter.name.length === 0) {
         return `arg${String(index)}`;
@@ -170,17 +172,62 @@ const parameterIdentifier = (parameter: GirParameter, index: number): string =>
     return toCamelIdentifier(parameter.name);
 };
 
+const handlerParameters = (
+    parameters: GirParameter[],
+    shouldExclude: (parameter: GirParameter) => boolean = () => false,
+): GirParameter[] =>
+    parameters.filter(
+        (parameter) => !parameter.isVarargs && !isOutParameter(parameter) && !shouldExclude(parameter),
+    );
+
+const documentedParameters = (
+    library: Library,
+    fn: GirFunction,
+    shouldSkip: (parameter: GirParameter) => boolean = () => false,
+    renames?: Map<string, string>,
+): JsDocParam[] =>
+    inputParameters(library, fn)
+        .filter(({ parameter }) => !shouldSkip(parameter))
+        .map(({ parameter, index }) => ({
+            name: renames?.get(parameter.name) ?? parameterIdentifier(parameter, index),
+            doc: parameter.doc ?? "",
+        }))
+        .filter((entry) => entry.doc.length > 0);
+
+const documentedHandlerParameters = (parameters: GirParameter[]): JsDocParam[] =>
+    handlerParameters(parameters)
+        .map((parameter, index) => ({ name: parameterIdentifier(parameter, index), doc: parameter.doc ?? "" }))
+        .filter((entry) => entry.doc.length > 0);
+
+const handlerRenames = (parameters: GirParameter[]): Map<string, string> => {
+    const renames: Map<string, string> = new Map();
+
+    for (const [index, parameter] of parameters.entries()) {
+        renames.set(parameter.name, parameterIdentifier(parameter, index));
+    }
+
+    return renames;
+};
+
+const renamesWithInstance = (parameters: GirParameter[], instance: GirParameter | undefined): Map<string, string> => {
+    const renames = handlerRenames(parameters);
+
+    if (instance !== undefined && instance.name.length > 0) {
+        renames.set(instance.name, "this");
+    }
+
+    return renames;
+};
+
 const renderHandlerParameters = (
     parameters: GirParameter[],
     renderType: (ref: TypeId | undefined, isNullable: boolean) => string,
     shouldExclude: (parameter: GirParameter) => boolean = () => false,
 ): string[] =>
-    parameters
-        .filter((parameter) => !parameter.isVarargs && !isOutParameter(parameter) && !shouldExclude(parameter))
-        .map(
-            (parameter, index) =>
-                `${parameterIdentifier(parameter, index)}: ${renderType(parameter.type, parameter.nullable)}`,
-        );
+    handlerParameters(parameters, shouldExclude).map(
+        (parameter, index) =>
+            `${parameterIdentifier(parameter, index)}: ${renderType(parameter.type, parameter.nullable)}`,
+    );
 
 const foldOutParamShape = (primary: string | undefined, outTypes: string[]): string => {
     if (primary !== undefined) {
@@ -199,9 +246,9 @@ const foldOutParamShape = (primary: string | undefined, outTypes: string[]): str
 const isHandlerOutParameter = (options: {
     library: Library;
     parameter: GirParameter;
-    includeCallerAllocated: boolean;
+    shouldIncludeCallerAllocated: boolean;
 }): boolean => {
-    const { library, parameter, includeCallerAllocated } = options;
+    const { library, parameter, shouldIncludeCallerAllocated } = options;
 
     if (parameter.isVarargs) {
         return false;
@@ -215,7 +262,7 @@ const isHandlerOutParameter = (options: {
         return true;
     }
 
-    return includeCallerAllocated && isCallerAllocatedOut(parameter);
+    return shouldIncludeCallerAllocated && isCallerAllocatedOut(parameter);
 };
 
 const scalarResultType = (primary: string | undefined, isOptOut: boolean): string => {
@@ -227,18 +274,23 @@ const scalarResultType = (primary: string | undefined, isOptOut: boolean): strin
 };
 
 const renderHandlerResultType = (options: HandlerResultOptions): string => {
-    const { library, signal, renderType, includeCallerAllocated, optOut } = options;
+    const { library, signal, renderType, shouldIncludeCallerAllocated, isOptOut } = options;
+    const shouldExcludeOut = options.shouldExcludeOut ?? (() => false);
 
     const primary = shouldOmitPrimaryReturn(library, signal.returnValue)
         ? undefined
         : renderType(signal.returnValue.type, signal.returnValue.nullable);
 
     const outTypes = signal.parameters
-        .filter((parameter) => isHandlerOutParameter({ library, parameter, includeCallerAllocated }))
+        .filter(
+            (parameter) =>
+                isHandlerOutParameter({ library, parameter, shouldIncludeCallerAllocated }) &&
+                !shouldExcludeOut(parameter),
+        )
         .map((parameter) => renderType(parameter.type, parameter.nullable));
 
     if (outTypes.length === 0) {
-        return scalarResultType(primary, optOut);
+        return scalarResultType(primary, isOptOut);
     }
 
     return foldOutParamShape(primary, outTypes);
@@ -249,10 +301,16 @@ export {
     inputParameters,
     closureAndDestroyIndices,
     arrayLengthSources,
-    hasCallerAllocatedArrayLength,
     foldedLengthIndices,
+    foldedLengthParameters,
     parameterIdentifier,
+    documentedParameters,
+    documentedHandlerParameters,
+    handlerRenames,
+    renamesWithInstance,
+    handlerParameters,
     renderHandlerParameters,
     foldOutParamShape,
     renderHandlerResultType,
+    type InputParameter,
 };

package/src/analysis/ts-type.ts

@@ -19,7 +19,7 @@ type ReferenceName = {
 type TsTypeTarget = {
     containerStyle: "map" | "record";
     callbackType: string;
-    byteArrayAsNumber: boolean;
+    shouldRenderByteArrayAsNumber: boolean;
     renderNamed: (resolved: GirType | undefined, name: ReferenceName) => string;
     renderGtype: () => string;
 };
@@ -100,10 +100,8 @@ const renderContainerType = (
     return renderSequenceType(library, target, type);
 };
 
-// An array whose length nothing states decodes as the bare pointer it is, so its TypeScript type has
-// to say so too rather than promising elements nothing can count.
 const renderSequenceType = (library: Library, target: TsTypeTarget, type: CArrayType | ListType): string => {
-    if (type.kind === "list" && type.flavor === "gbytearray" && target.byteArrayAsNumber) {
+    if (type.kind === "list" && type.flavor === "gbytearray" && target.shouldRenderByteArrayAsNumber) {
         return "number[]";
     }
 
@@ -129,7 +127,7 @@ const renderNamedType = (
 const moduleTarget = (context: ModuleContext): TsTypeTarget => ({
     containerStyle: "map",
     callbackType: "((...args: any[]) => any)",
-    byteArrayAsNumber: true,
+    shouldRenderByteArrayAsNumber: true,
     renderNamed: (_resolved, name) => context.qualify(name.namespaceName, name.typeName),
     renderGtype: () => gtypeTsType(context),
 });
@@ -148,7 +146,7 @@ const recordTypeTarget = (
     const target: TsTypeTarget = {
         containerStyle: "record",
         callbackType: "((...args: unknown[]) => unknown)",
-        byteArrayAsNumber: false,
+        shouldRenderByteArrayAsNumber: false,
         renderNamed: (resolved, name) => {
             if (resolved?.kind === "alias") {
                 return resolved.value.target === undefined

package/src/analysis/type-shape.ts

@@ -0,0 +1,24 @@
+import type { Library } from "../gir/library.js";
+import type { PrimitiveCategory } from "../gir/primitives.js";
+import type { CArrayType, TypeId } from "../gir/type-id.js";
+import type { GirType } from "../gir/type.js";
+
+const resolvedTypeFor = (library: Library, ref: TypeId | undefined): GirType | undefined =>
+    ref === undefined ? undefined : library.typeFor(ref);
+
+const carrayFor = (library: Library, ref: TypeId | undefined): CArrayType | undefined => {
+    const type = resolvedTypeFor(library, ref);
+
+    return type?.kind === "carray" ? type : undefined;
+};
+
+const primitiveCategoryFor = (library: Library, ref: TypeId | undefined): PrimitiveCategory | undefined => {
+    const type = resolvedTypeFor(library, ref);
+
+    return type?.kind === "primitive" ? type.category : undefined;
+};
+
+const isUnboundedArray = (type: CArrayType): boolean =>
+    type.isZeroTerminated && type.lengthParameterIndex === undefined && type.fixedSize === undefined;
+
+export { carrayFor, isUnboundedArray, primitiveCategoryFor };