@gtkx/codegen 1.0.0 → 1.2.0

package/src/docs/pipeline.ts

@@ -1,9 +1,17 @@
 import { sortStringsBy } from "@gtkx/utils";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { computeGiFingerprint, FINGERPRINT_FILENAME, isGiStoreFresh } from "../fingerprint.js";
+import {
+    computeDocsFingerprint,
+    type DocsFingerprintInput,
+    FINGERPRINT_FILENAME,
+    type GiInputs,
+    isDocsOutputFresh,
+} from "../fingerprint.js";
 import { Library } from "../gir/library.js";
 import { namespaceDirectory } from "../gir/namespace.js";
+import { arrayGuard, hasFields, isString } from "../guards.js";
+import { readJsonFile } from "../json.js";
 import { type ElementProps, setElementProps } from "../store/jsx/element-prop-imports.js";
 import { collectIntrinsicElementClasses, type GlibNamedClass } from "../store/jsx/intrinsic-elements.js";
 import { type OmittedProps, setOmittedProps } from "../store/jsx/omitted-props.js";
@@ -30,9 +38,11 @@ type DocsOptions = {
     props?: ElementProps;
     omittedProps?: OmittedProps;
     isForced?: boolean;
+    isByteArrayTyped?: boolean;
 };
 
 type DocsManifest = {
+    generator: string;
     namespaces: DocsNamespace[];
 };
 
@@ -50,6 +60,9 @@ type DocsResult = {
 };
 
 const MANIFEST_FILENAME = "manifest.json";
+const MANIFEST_GENERATOR = "gtkx-docs";
+const ROOT_INDEX_FILENAME = "index.md";
+const DEFAULT_BASE_PATH = "/reference";
 
 const namespaceIndexPage = (namespace: DocsNamespace, elements: GlibNamedClass[]): string => {
     const rows = elements.map((entry, index) => {
@@ -144,6 +157,28 @@ const buildElementLinks = (elements: GlibNamedClass[], basePath: string): Map<st
     return linkByGlibName;
 };
 
+const isEntryInsideOutDir = (value: string): boolean =>
+    value.length > 0 && value !== "." && value !== ".." && !value.includes("/") && !value.includes("\\");
+
+const isChildEntry = (value: unknown): value is string => isString(value) && isEntryInsideOutDir(value);
+
+const ownedEntry = (entry: string, source: string): string => {
+    if (isEntryInsideOutDir(entry)) {
+        return entry;
+    }
+
+    throw new Error(
+        `Refusing to generate documentation outside the output directory: ${source} maps to \`${entry}\`, ` +
+        "which is not an entry inside it. The GIR that declares it is malformed.",
+    );
+};
+
+const elementPagePath = (directory: string, entry: GlibNamedClass): string => {
+    const slug = ownedEntry(elementSlug(entry.klass.name), `the element ${entry.glibName}`);
+
+    return `${directory}/${slug}.md`;
+};
+
 const namespacePages = (input: {
     name: string;
     elements: GlibNamedClass[];
@@ -152,7 +187,7 @@ const namespacePages = (input: {
     pageContext: ElementPageContext;
 }): NamespacePages => {
     const { name, elements, basePath, linkByGlibName, pageContext } = input;
-    const directory = name.toLowerCase();
+    const directory = ownedEntry(namespaceDirectory({ name }), `the GIR namespace ${name}`);
 
     const docs: DocsNamespace = {
         name,
@@ -162,7 +197,7 @@ const namespacePages = (input: {
     };
 
     const pages: Page[] = elements.map((entry) => ({
-        path: `${directory}/${elementSlug(entry.klass.name)}.md`,
+        path: elementPagePath(directory, entry),
         content: renderElementPage(entry, pageContext),
     }));
 
@@ -187,21 +222,97 @@ const generatePages = (options: DocsOptions, basePath: string, library: Library)
         namespaces.push(result.docs);
     }
 
-    pages.push({ path: "index.md", content: rootIndexPage(namespaces, options.libraries) });
+    pages.push({ path: ROOT_INDEX_FILENAME, content: rootIndexPage(namespaces, options.libraries) });
 
     return { pages, namespaces };
 };
 
-const cachedDocsResult = (options: DocsOptions, manifestPath: string): DocsResult | undefined => {
-    if (options.isForced === true || !isGiStoreFresh(options.outDir, options.libraries, options.girPath)) {
-        return undefined;
+const isGeneratorTag = (value: unknown): value is string => value === MANIFEST_GENERATOR;
+
+const isDocsElementLink = (value: unknown): value is DocsElementLink =>
+    hasFields<DocsElementLink>(value, { text: isString, link: isString });
+
+const isDocsNamespace = (value: unknown): value is DocsNamespace =>
+    hasFields<DocsNamespace>(value, {
+        name: isString,
+        directory: isChildEntry,
+        link: isString,
+        elements: arrayGuard(isDocsElementLink),
+    });
+
+const isDocsManifest = (value: unknown): value is DocsManifest =>
+    hasFields<DocsManifest>(value, { generator: isGeneratorTag, namespaces: arrayGuard(isDocsNamespace) });
+
+const readDocsManifest = (manifestPath: string): DocsManifest | undefined => {
+    const parsed = readJsonFile(manifestPath);
+
+    return isDocsManifest(parsed) ? parsed : undefined;
+};
+
+const outDirRefusal = (outDir: string, reason: string): Error =>
+    new Error(
+        `Refusing to generate documentation into ${outDir}: ${reason}. Point the output directory at an ` +
+        "empty directory or at one gtkx generated, or remove it yourself first.",
+    );
+
+const giInputs = (options: DocsOptions, girFiles: string[]): GiInputs => ({
+    girFiles,
+    libraries: options.libraries,
+    girPath: options.girPath,
+    isByteArrayTyped: options.isByteArrayTyped === true,
+});
+
+const assertOwnedOutDir = (options: DocsOptions, manifest: DocsManifest | undefined): void => {
+    const stats = statSync(options.outDir, { throwIfNoEntry: false });
+
+    if (stats === undefined) {
+        return;
+    }
+
+    if (!stats.isDirectory()) {
+        throw outDirRefusal(options.outDir, "it already exists and is not a directory");
     }
 
-    if (!existsSync(manifestPath)) {
+    if (manifest !== undefined || readdirSync(options.outDir).length === 0) {
+        return;
+    }
+
+    throw outDirRefusal(
+        options.outDir,
+        `it is not empty and holds no ${MANIFEST_FILENAME} written by \`gtkx docs\`, ` +
+        "so its contents are not gtkx's to replace",
+    );
+};
+
+const clearOutDir = (options: DocsOptions, manifest: DocsManifest | undefined): void => {
+    if (manifest === undefined) {
+        return;
+    }
+
+    const entries = [
+        ...manifest.namespaces.map((namespace) => namespace.directory),
+        ROOT_INDEX_FILENAME,
+        MANIFEST_FILENAME,
+        FINGERPRINT_FILENAME,
+    ];
+
+    for (const entry of entries) {
+        rmSync(join(options.outDir, entry), { recursive: true, force: true });
+    }
+};
+
+const cachedDocsResult = (
+    options: DocsOptions,
+    manifest: DocsManifest | undefined,
+    input: DocsFingerprintInput,
+): DocsResult | undefined => {
+    if (manifest === undefined || options.isForced === true) {
         return undefined;
     }
 
-    const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as DocsManifest;
+    if (!isDocsOutputFresh(options.outDir, giInputs(options, []), input)) {
+        return undefined;
+    }
 
     return { isRegenerated: false, namespaces: manifest.namespaces };
 };
@@ -214,29 +325,34 @@ const writePages = (outDir: string, pages: Page[]): void => {
     }
 };
 
+const docsFingerprintInput = (options: DocsOptions): DocsFingerprintInput => ({
+    basePath: options.basePath ?? DEFAULT_BASE_PATH,
+    props: options.props ?? {},
+    omittedProps: options.omittedProps ?? {},
+});
+
 const writeDocs = (options: DocsOptions): DocsResult => {
-    setElementProps(options.props ?? {});
-    setOmittedProps(options.omittedProps ?? {});
-    const basePath = options.basePath ?? "/reference";
+    const input = docsFingerprintInput(options);
+    setElementProps(input.props);
+    setOmittedProps(input.omittedProps);
     const manifestPath = join(options.outDir, MANIFEST_FILENAME);
-    const cached = cachedDocsResult(options, manifestPath);
+    const previous = readDocsManifest(manifestPath);
+    const cached = cachedDocsResult(options, previous, input);
 
     if (cached !== undefined) {
         return cached;
     }
 
-    const library = Library.load(options.libraries, options.girPath);
-    const { pages, namespaces } = generatePages(options, basePath, library);
-    rmSync(options.outDir, { recursive: true, force: true });
+    assertOwnedOutDir(options, previous);
+    const library = Library.load(options.libraries, options.girPath, options.isByteArrayTyped === true);
+    const { pages, namespaces } = generatePages(options, input.basePath, library);
+    clearOutDir(options, previous);
     mkdirSync(options.outDir, { recursive: true });
-    writePages(options.outDir, pages);
-    const manifest: DocsManifest = { namespaces };
+    const manifest: DocsManifest = { generator: MANIFEST_GENERATOR, namespaces };
     writeFileSync(manifestPath, JSON.stringify(manifest));
-
-    writeFileSync(
-        join(options.outDir, FINGERPRINT_FILENAME),
-        JSON.stringify(computeGiFingerprint(library.girFiles, options.libraries, options.girPath)),
-    );
+    writePages(options.outDir, pages);
+    const fingerprint = computeDocsFingerprint(giInputs(options, library.girFiles), input);
+    writeFileSync(join(options.outDir, FINGERPRINT_FILENAME), JSON.stringify(fingerprint));
 
     return { isRegenerated: true, namespaces };
 };

package/src/docs/render.ts

@@ -1,4 +1,4 @@
-import { pascalCase, sortStringsBy } from "@gtkx/utils";
+import { sanitizeTypeIdentifier, sortStringsBy } from "@gtkx/utils";
 import type { GirAnnotations } from "../gir/annotations.js";
 import type { GirClass } from "../gir/class.js";
 import type { GirFunction } from "../gir/function.js";
@@ -286,10 +286,13 @@ const originSignatureBlocks = (entries: OriginSignatureEntry[]): string[] =>
         signatureEntryBlock(item, item.origin === undefined ? [] : [`From \`${item.origin}\`.`]),
     );
 
+const qualifiedClassName = (namespaceName: string, className: string): string =>
+    `${namespaceName}.${sanitizeTypeIdentifier(className)}`;
+
 const classMethodEntries = (library: Library, namespace: GirNamespace, klass: GirClass): SignatureEntry[] => {
     const realContext = new ModuleContext(namespace, library);
     const signatureContext = docsSignatureContext(namespace, library);
-    const className = pascalCase(klass.name);
+    const className = sanitizeTypeIdentifier(klass.name);
     const inherited = collectInheritedMethods(realContext, klass);
 
     return instanceMethodEntries(signatureContext, klass, (method) =>
@@ -307,7 +310,7 @@ const instanceMethodEntries = (
 ): SignatureEntry[] => {
     const deduped = dedupeCallables(klass.methods);
 
-    const scope = instanceScope(pascalCase(klass.name), {
+    const scope = instanceScope(sanitizeTypeIdentifier(klass.name), {
         constructors: dedupeCallables(klass.constructors),
         functions: dedupeCallables(klass.functions),
         methods: deduped,
@@ -362,6 +365,7 @@ export {
     originSignatureBlocks,
     classMethodEntries,
     methodsSectionBlocks,
+    qualifiedClassName,
     tagNotes,
     type MetaDocEntry,
     type SignatureEntry,

package/src/docs/symbol-page.ts

@@ -1,4 +1,4 @@
-import { pascalCase, sortStringsBy, upperFirst } from "@gtkx/utils";
+import { sanitizeTypeIdentifier, sortStringsBy, upperFirst } from "@gtkx/utils";
 import type { GirAnnotations } from "../gir/annotations.js";
 import type { GirClass } from "../gir/class.js";
 import type { EnumMember, GirEnum } from "../gir/enum.js";
@@ -16,7 +16,6 @@ import { PRIMITIVE_TS_TYPE, primitiveCategory } from "../gir/primitives.js";
 import { callableSpec } from "../store/gi/callable-doc.js";
 import {
     dedupeCallables,
-    indexMethodsByName,
     instanceScope,
     matchStaticFinishFunction,
     renderInstanceMethodSignature,
@@ -51,6 +50,7 @@ import {
     type OriginSignatureEntry,
     plainText,
     propertyMetaLine,
+    qualifiedClassName,
     renderDocsSignalHandlerType,
     renderDocsType,
     signalTags,
@@ -145,7 +145,6 @@ type MemberOwner = {
 type PropertyAccessorSetup = {
     context: ModuleContext;
     claimedNames: Set<string>;
-    methodByName: Map<string, GirFunction>;
 };
 
 type ResolvedRecordField = NonNullable<ReturnType<typeof resolveRecordFieldEntry>>;
@@ -202,9 +201,6 @@ const pageHeader = (entry: GiSymbolEntry, kindLabel: string): string[] => [
     importBlock(entry),
 ];
 
-const qualifiedClassName = (namespaceName: string, className: string): string =>
-    `${namespaceName}.${pascalCase(className)}`;
-
 const elementNote = (entry: ClassSymbol, options: SymbolPageOptions): string[] => {
     const glibName = options.elementNameFor(entry.namespace.name, entry.klass.name);
 
@@ -354,7 +350,7 @@ const memberOwners = (entry: ClassSymbol, library: Library): MemberOwner[] => [
 
 const interfaceMethodNames = (library: Library, owner: MemberOwner): string[] => {
     const context = docsSignatureContext(owner.namespace, library);
-    const className = pascalCase(owner.klass.name);
+    const className = sanitizeTypeIdentifier(owner.klass.name);
     const methods = dedupeCallables(owner.klass.methods);
 
     const scope = instanceScope(className, {
@@ -393,7 +389,6 @@ const propertyAccessorSetup = (
     return {
         context: docsSignatureContext(owner.namespace, library),
         claimedNames,
-        methodByName: indexMethodsByName(dedupeCallables(owner.klass.methods)),
     };
 };
 
@@ -402,9 +397,16 @@ const getAccessNotes = (accessor: ResolvedAccessor): string[] => {
         return ["read-only"];
     }
 
-    return accessor.hasGetter ? [] : ["write-only"];
+    if (!accessor.hasGetter) {
+        return ["write-only"];
+    }
+
+    return accessor.readType === accessor.writeType ? [] : [`writes \`${accessor.writeType}\``];
 };
 
+const documentedAccessorType = (accessor: ResolvedAccessor): string =>
+    accessor.hasGetter ? accessor.readType : accessor.writeType;
+
 const ownerPropertyEntries = (owner: MemberOwner, setup: PropertyAccessorSetup, seen: Set<string>): MetaDocEntry[] => {
     const entries: MetaDocEntry[] = [];
 
@@ -413,7 +415,6 @@ const ownerPropertyEntries = (owner: MemberOwner, setup: PropertyAccessorSetup,
             context: setup.context,
             property,
             claimedNames: setup.claimedNames,
-            methodByName: setup.methodByName,
         });
 
         if (accessor === undefined || seen.has(accessor.jsName)) {
@@ -425,7 +426,7 @@ const ownerPropertyEntries = (owner: MemberOwner, setup: PropertyAccessorSetup,
         entries.push({
             name: accessor.jsName,
             meta: propertyMetaLine({
-                type: accessor.tsType,
+                type: documentedAccessorType(accessor),
                 property,
                 accessNotes: getAccessNotes(accessor),
                 origin: owner.origin,

package/src/fingerprint.ts

@@ -1,9 +1,18 @@
 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 GiInputs = {
+    girFiles: string[];
+    libraries: string[];
+    girPath: string[];
+    isByteArrayTyped: boolean;
+};
 
 type GiFingerprint = {
     value: string;
@@ -14,6 +23,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 +47,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(",");
@@ -44,15 +63,17 @@ const overrideFiles = (): string[] => {
         .map((entry: Dirent) => join(entry.parentPath, entry.name));
 };
 
-const hashGi = (girFiles: string[], libraries: string[], girPath: string[]): string => {
+const hashGi = (inputs: GiInputs): string => {
     const hash = createHash("sha256");
     hash.update(CODEGEN_VERSION);
     hash.update("\n");
-    hash.update(sortAlpha(libraries));
+    hash.update(sortAlpha(inputs.libraries));
+    hash.update("\n");
+    hash.update(sortAlpha(inputs.girPath));
     hash.update("\n");
-    hash.update(sortAlpha(girPath));
+    hash.update(String(inputs.isByteArrayTyped));
     hash.update("\n");
-    const hashedFiles = sortStrings([...girFiles, ...overrideFiles()]);
+    const hashedFiles = sortStrings([...inputs.girFiles, ...overrideFiles()]);
 
     for (const file of hashedFiles) {
         hash.update("\n");
@@ -64,49 +85,80 @@ const hashGi = (girFiles: string[], libraries: string[], girPath: string[]): str
     return hash.digest("hex");
 };
 
-const computeGiFingerprint = (
-    girFiles: string[],
-    libraries: string[],
-    girPath: string[],
-): GiFingerprint => ({
-    value: hashGi(girFiles, libraries, girPath),
-    girFiles,
-    libraries,
-    girPath,
+const computeGiFingerprint = (inputs: GiInputs): GiFingerprint => ({
+    value: hashGi(inputs),
+    girFiles: inputs.girFiles,
+    libraries: inputs.libraries,
+    girPath: inputs.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 });
 
-    if (!hasMatchingRecordedInputs(sentinel, libraries, girPath)) {
-        return false;
+const recordedGiValue = (sentinel: GiFingerprint, inputs: GiInputs): string | undefined => {
+    if (!hasMatchingRecordedInputs(sentinel, inputs)) {
+        return undefined;
     }
 
     try {
-        return hashGi(sentinel.girFiles, sentinel.libraries, girPath) === sentinel.value;
+        return hashGi({ ...inputs, girFiles: sentinel.girFiles, libraries: sentinel.libraries });
     } catch {
-        return false;
+        return undefined;
     }
 };
 
-const hasMatchingRecordedInputs = (sentinel: GiFingerprint, libraries: string[], girPath: string[]): boolean =>
-    sortAlpha(sentinel.libraries) === sortAlpha(libraries) && sortAlpha(sentinel.girPath ?? []) === sortAlpha(girPath);
+const isGiStoreFresh = (giStoreDir: string, inputs: GiInputs): boolean => {
+    const sentinel = readSentinel(giStoreDir);
+
+    return isGiFingerprint(sentinel) && recordedGiValue(sentinel, inputs) === sentinel.value;
+};
+
+const hasMatchingRecordedInputs = (sentinel: GiFingerprint, inputs: GiInputs): boolean =>
+    sortAlpha(sentinel.libraries) === sortAlpha(inputs.libraries) &&
+    sortAlpha(sentinel.girPath ?? []) === sortAlpha(inputs.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 = (inputs: GiInputs, input: DocsFingerprintInput): DocsFingerprint => {
+    const gi = computeGiFingerprint(inputs);
+
+    return { value: hashDocs(gi.value, input), gi };
+};
+
+const isDocsOutputFresh = (outDir: string, inputs: GiInputs, input: DocsFingerprintInput): boolean => {
+    const sentinel = readSentinel(outDir);
+
+    if (!isDocsFingerprint(sentinel)) {
+        return false;
+    }
+
+    const giValue = recordedGiValue(sentinel.gi, inputs);
+
+    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 +189,9 @@ const jsxStoreFreshness = (
     jsxStoreDir: string,
     input: JsxFingerprintInput,
 ): { isFresh: boolean; intrinsicElementCount: number } => {
-    const sentinelPath = join(jsxStoreDir, FINGERPRINT_FILENAME);
+    const sentinel = readSentinel(jsxStoreDir);
 
-    if (!existsSync(sentinelPath)) {
-        return { isFresh: false, intrinsicElementCount: 0 };
-    }
-
-    let sentinel: JsxFingerprint;
-
-    try {
-        sentinel = JSON.parse(readFileSync(sentinelPath, "utf8")) as JsxFingerprint;
-    } catch {
+    if (!isJsxFingerprint(sentinel)) {
         return { isFresh: false, intrinsicElementCount: 0 };
     }
 
@@ -159,9 +203,13 @@ const jsxStoreFreshness = (
 export {
     FINGERPRINT_FILENAME,
     computeGiFingerprint,
+    computeDocsFingerprint,
     isGiStoreFresh,
+    isDocsOutputFresh,
     computeJsxFingerprint,
     jsxStoreFreshness,
+    type DocsFingerprintInput,
+    type GiInputs,
     type GiFingerprint,
     type JsxFingerprintInput,
 };

package/src/gi.ts

@@ -9,17 +9,25 @@ type GiCodegenOptions = {
     gi: StoreOptions;
     libraries: string[];
     girPath: string[];
+    isByteArrayTyped: boolean;
 };
 
 const runGiCodegen = (library: Library, options: GiCodegenOptions): number => {
-    const { gi, libraries, girPath } = options;
+    const { gi, libraries, girPath, isByteArrayTyped } = options;
 
     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]);
+    const fingerprint = computeGiFingerprint({
+        girFiles: library.girFiles,
+        libraries: [...libraries],
+        girPath: [...girPath],
+        isByteArrayTyped,
+    });
+
     writeGiStore(gi, namespaces, fingerprint);
 
     return library.namespaces.size;

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 }
@@ -64,4 +80,4 @@ function* ancestorChain(library: Library, klass: GirClass, namespaceName: string
     }
 }
 
-export { resolveInterfaces, ancestorChain, type ResolvedAncestor };
+export { resolveClassOrInterface, resolveInterfaces, ancestorChain, getParentRef, type ResolvedAncestor };

package/src/gir/annotations.ts

@@ -34,4 +34,4 @@ const documentedFromNode = (node: RawNode): DocumentedNode => ({
 const hasAnnotations = (annotations: GirAnnotations): boolean =>
     annotations.since !== undefined || annotations.isDeprecated || annotations.deprecatedSince !== undefined;
 
-export { annotationsFromNode, documentedFromNode, hasAnnotations, type GirAnnotations };
+export { documentedFromNode, hasAnnotations, type GirAnnotations };

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 };