@gtkx/codegen 1.0.0-rc.2 → 1.0.0-rc.4

package/src/docs/api-reference.ts

@@ -5,43 +5,91 @@ import type { GirRecord } from "../gir/record.js";
 import { Library } from "../gir/library.js";
 import { type GirNamespace, namespaceDirectory } from "../gir/namespace.js";
 import { dedupeCallables, isEmittableCallable } from "../store/gi/callables.js";
-import { isClassStructRecord } from "../store/gi/class-struct-record.js";
 import { namespaceFunctionExportName } from "../store/gi/function.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";
 import { createElementPageContext, type ElementPageContext, renderElementPage } from "./element-page.js";
 import { docsSignatureContext, firstSentence, namespaceOrder } from "./render.js";
 import { type GiSymbolEntry, renderSymbolPage, type SymbolPageOptions } from "./symbol-page.js";
 
+/** What to index and the element config the rendered pages reflect. */
 type ApiReferenceOptions = {
+    /** GIR library identifiers to load, such as `"Gtk-4.0"`; their dependencies are pulled in too. */
     libraries: string[];
+    /** Directories to search for `.gir` files. */
     girPath: string[];
+    /** Base props interfaces per element, as read by `readBuiltinElements`; without it pages miss them. */
+    props?: ElementProps;
+    /** GObject properties the project omits from generated props; without it pages show props that do not exist. */
+    omittedProps?: OmittedProps;
 };
 
+/** Narrows an `ApiReference.symbols` enumeration. */
+type ApiSymbolQuery = {
+    /** GIR namespace to keep, matched case-insensitively; every namespace when omitted. */
+    namespace?: string;
+    /** Symbol kinds to keep; every kind when omitted. */
+    kinds?: ApiSymbolKind[];
+};
+
+/** What an indexed symbol is: one of the GIR symbol kinds, or a JSX element. */
 type ApiSymbolKind = GiSymbolEntry["kind"] | "element";
 
+/** An indexed symbol, without its reference page. */
 type ApiSymbol = {
+    /** GIR namespace declaring the symbol, such as `"Gtk"`. */
     namespace: string;
+    /** Name within the namespace, which for an element is its GLib type name. */
     name: string;
+    /** Kind the reference groups and filters the symbol by, `"element"` for a JSX tag. */
     kind: ApiSymbolKind;
+    /** First sentence of the symbol's GIR documentation, elided past 220 characters and empty when it has none. */
     summary: string;
 };
 
+/** How much of one namespace the reference indexes. */
 type ApiNamespaceSummary = {
+    /** GIR namespace name, such as `"Gtk"`. */
     name: string;
+    /** The `@gtkx/gi` subpath the namespace's symbols are imported from. */
     importPath: string;
+    /** How many symbols other than JSX elements the namespace contributes. */
     symbols: number;
+    /** How many JSX elements the namespace contributes. */
     elements: number;
 };
 
+/** What an `ApiReference.lookup` found: a rendered page, several candidates for the name, or nothing. */
 type ApiLookupResult =
-    | { outcome: "page"; symbol: ApiSymbol; markdown: string } |
-    { outcome: "ambiguous"; candidates: ApiSymbol[] } |
-    { outcome: "notFound" };
-
+    | {
+        /** Discriminant selecting the variant. */
+        outcome: "page";
+        /** Index entry for the symbol the query resolved to. */
+        symbol: ApiSymbol;
+        /** The symbol's complete reference page, rendered as Markdown. */
+        markdown: string;
+    } |
+    {
+        /** Discriminant selecting the variant. */
+        outcome: "ambiguous";
+        /** Every symbol the name answers to, to be narrowed by namespace or kind. */
+        candidates: ApiSymbol[];
+    } |
+    {
+        /** Discriminant selecting the variant. */
+        outcome: "notFound";
+    };
+
+/** A fuzzy search over indexed symbol names. */
 type ApiSearchOptions = {
+    /** Text matched case-insensitively against each symbol's name and its qualified `Namespace.Name` form. */
     query: string;
+    /** GIR namespace to keep, matched case-insensitively; every namespace when omitted. */
     namespace?: string;
+    /** Symbol kinds to keep; every kind when omitted. */
     kinds?: ApiSymbolKind[];
+    /** Maximum number of results, 20 by default. */
     limit?: number;
 };
 
@@ -56,6 +104,7 @@ type ElementEntry = {
 type SymbolEntry = GiSymbolEntry | ElementEntry;
 type ScoredEntry = { score: number; entry: SymbolEntry };
 
+/** Every kind the reference indexes, in the order a namespace overview groups its symbols. */
 const API_SYMBOL_KINDS: ApiSymbolKind[] = [
     "element",
     "class",
@@ -90,6 +139,32 @@ const compareNames = (a: string, b: string): number => {
     return a > b ? 1 : 0;
 };
 
+const isQueriedEntry = (
+    entry: SymbolEntry,
+    namespaceFilter: string | undefined,
+    kinds: Set<ApiSymbolKind> | undefined,
+): boolean => {
+    if (namespaceFilter !== undefined && entry.namespace.name.toLowerCase() !== namespaceFilter) {
+        return false;
+    }
+
+    return kinds === undefined || kinds.has(entry.kind);
+};
+
+const compareApiSymbols = (a: ApiSymbol, b: ApiSymbol): number => {
+    const byNamespace = namespaceOrder(a.namespace).localeCompare(namespaceOrder(b.namespace));
+
+    return byNamespace === 0 ? a.name.localeCompare(b.name) : byNamespace;
+};
+
+/**
+ * Loads the GIR data for the given libraries and indexes every symbol and JSX element in it. The result is
+ * a read-only view: it generates no store and needs none, so a tool can explore the bindings a project would
+ * get without running codegen.
+ *
+ * @param options Which libraries to index, where to find them, and the project's element config.
+ * @returns The indexed reference.
+ */
 const loadApiReference = (options: ApiReferenceOptions): ApiReference => new ApiReference(options);
 
 const functionEntry = (
@@ -136,23 +211,19 @@ const classEntries = (namespace: GirNamespace): GiSymbolEntry[] => {
     return entries;
 };
 
-const recordEntry = (library: Library, namespace: GirNamespace, record: GirRecord): GiSymbolEntry | undefined => {
+const recordEntry = (namespace: GirNamespace, record: GirRecord): GiSymbolEntry | undefined => {
     if (!record.introspectable || record.isVtable || record.name.length === 0) {
         return undefined;
     }
 
-    if (isClassStructRecord(library, namespace.name, record)) {
-        return undefined;
-    }
-
     return { kind: "record", namespace, name: record.name, doc: record.doc, record };
 };
 
-const recordEntries = (library: Library, namespace: GirNamespace): GiSymbolEntry[] => {
+const recordEntries = (namespace: GirNamespace): GiSymbolEntry[] => {
     const entries: GiSymbolEntry[] = [];
 
     for (const record of namespace.records) {
-        const entry = recordEntry(library, namespace, record);
+        const entry = recordEntry(namespace, record);
 
         if (entry !== undefined) {
             entries.push(entry);
@@ -270,6 +341,7 @@ const searchScore = (entry: SymbolEntry, query: string): number => {
     return 0;
 };
 
+/** An index over the GIR data a project's bindings are generated from, queryable and renderable as Markdown. */
 class ApiReference {
     private library: Library;
     private libraries: string[];
@@ -280,13 +352,23 @@ class ApiReference {
     private byNamespace: Map<string, SymbolEntry[]> = new Map();
     private elementsByClass: Map<string, string> = new Map();
 
+    private props: ElementProps;
+    private omittedProps: OmittedProps;
+
     constructor(options: ApiReferenceOptions) {
         this.libraries = options.libraries;
+        this.props = options.props ?? {};
+        this.omittedProps = options.omittedProps ?? {};
         this.library = Library.load(options.libraries, options.girPath);
         this.elementContext = createElementPageContext(this.library, (): string | undefined => undefined);
         this.buildIndex();
     }
 
+    private applyElementConfig(): void {
+        setElementProps(this.props);
+        setOmittedProps(this.omittedProps);
+    }
+
     private add(entry: SymbolEntry): void {
         this.entries.push(entry);
 
@@ -322,7 +404,7 @@ class ApiReference {
     private indexNamespace(namespace: GirNamespace): void {
         const entries = [
             ...classEntries(namespace),
-            ...recordEntries(this.library, namespace),
+            ...recordEntries(namespace),
             ...valueEntries(namespace),
         ];
 
@@ -367,6 +449,8 @@ class ApiReference {
 
     private renderPage(entry: SymbolEntry): string {
         if (entry.kind === "element") {
+            this.applyElementConfig();
+
             return renderElementPage(entry.element, this.elementContext);
         }
 
@@ -415,10 +499,18 @@ class ApiReference {
         return scored;
     }
 
+    /** Paths of the `.gir` files the index was built from, including the ones pulled in as dependencies. */
     get girFiles(): string[] {
         return this.library.girFiles;
     }
 
+    /**
+     * Resolves a name to a single symbol and renders its reference page. The name may be bare (`Button`) or
+     * qualified (`Gtk.Button`), and is matched case-insensitively; a name several symbols answer to is
+     * reported as ambiguous rather than picked between.
+     *
+     * @param kind Restricts the match to one kind, which is how a class and its JSX element are told apart.
+     */
     lookup(query: string, kind?: ApiSymbolKind): ApiLookupResult {
         const trimmed = query.trim();
 
@@ -440,6 +532,21 @@ class ApiReference {
         return { outcome: "page", symbol: this.toApiSymbol(entry), markdown: this.renderPage(entry) };
     }
 
+    /** Every indexed symbol the query keeps, ordered by namespace (Gtk, then Adw, then alphabetically) and name. */
+    symbols(query: ApiSymbolQuery = {}): ApiSymbol[] {
+        const namespaceFilter = query.namespace?.toLowerCase();
+        const kinds = query.kinds === undefined ? undefined : new Set(query.kinds);
+
+        return this.entries
+            .filter((entry) => isQueriedEntry(entry, namespaceFilter, kinds))
+            .map((entry) => this.toApiSymbol(entry))
+            .toSorted(compareApiSymbols);
+    }
+
+    /**
+     * Symbols whose name matches the query, best first: an exact name beats a prefix, which beats a
+     * substring, and shorter names win ties. An empty query matches nothing.
+     */
     search(options: ApiSearchOptions): ApiSymbol[] {
         const query = options.query.trim().toLowerCase();
 
@@ -455,6 +562,7 @@ class ApiReference {
         return scored.slice(0, limit).map((item) => this.toApiSymbol(item.entry));
     }
 
+    /** A summary of every indexed namespace, ordered Gtk, Adw, then alphabetically. */
     namespaces(): ApiNamespaceSummary[] {
         const summaries = [...this.byNamespace].map(([name, entries]) => ({
             name,
@@ -466,6 +574,10 @@ class ApiReference {
         return sortStringsBy(summaries, (summary) => namespaceOrder(summary.name));
     }
 
+    /**
+     * Sorted names of everything a namespace contributes, JSX elements included. The namespace is matched
+     * case-insensitively, and an unindexed one yields an empty array.
+     */
     symbolNames(namespaceName: string): string[] {
         const namespace = this.findNamespace(namespaceName);
 
@@ -478,6 +590,7 @@ class ApiReference {
         return sortStrings(entries.map((entry) => entry.name));
     }
 
+    /** Renders the reference's Markdown landing page: every namespace, its import path, and its totals. */
     overview(): string {
         const rows = this.namespaces().map(
             (summary) =>
@@ -505,6 +618,10 @@ class ApiReference {
         ].join("\n");
     }
 
+    /**
+     * Renders one namespace's Markdown page: its import line and its symbol names grouped by kind. The
+     * namespace is matched case-insensitively, and an unindexed one yields undefined.
+     */
     namespaceOverview(name: string): string | undefined {
         const namespace = this.findNamespace(name);
 
@@ -554,4 +671,5 @@ export {
     type ApiNamespaceSummary,
     type ApiLookupResult,
     type ApiSearchOptions,
+    type ApiSymbolQuery,
 };

package/src/docs/element-page.ts

@@ -13,6 +13,7 @@ import {
     newlyImplementedInterfaces,
     signalHandlerName,
 } from "../store/jsx/intrinsic-elements.js";
+import { isOmittedProp } from "../store/jsx/omitted-props.js";
 import { isObjectProp } from "../store/jsx/props.js";
 import {
     classMethodEntries,
@@ -120,12 +121,7 @@ const propertyEntry = (
     property: GirProperty,
     jsName: string,
 ): PropEntry => {
-    const isObject = isObjectProp(
-        { library: context.library, klass: owner.klass, namespace: owner.namespace },
-        property,
-        jsName,
-    );
-
+    const isObject = isObjectProp(context.library, property);
     const baseType = renderDocsType(context.library, property.type, false);
     const type = isObject ? `${baseType} | ReactElement` : baseType;
     const meta: string[] = [`\`${type}\``];
@@ -149,14 +145,14 @@ const propertyEntry = (
     return { name: jsName, meta: meta.join(" · "), doc: docMarkdown(property.doc) };
 };
 
-const propJsName = (property: GirProperty, seen: Set<string>): string | undefined => {
+const propJsName = (property: GirProperty, owner: MemberOwner, seen: Set<string>): string | undefined => {
     if (!property.introspectable) {
         return undefined;
     }
 
     const jsName = toCamelIdentifier(property.name);
 
-    if (seen.has(jsName)) {
+    if (seen.has(jsName) || isOmittedProp(owner.glibName, jsName)) {
         return undefined;
     }
 
@@ -169,7 +165,7 @@ const ownerPropEntries = (context: ElementPageContext, owner: MemberOwner, seen:
     const entries: PropEntry[] = [];
 
     for (const property of owner.klass.properties) {
-        const jsName = propJsName(property, seen);
+        const jsName = propJsName(property, owner, seen);
 
         if (jsName !== undefined) {
             entries.push(propertyEntry(context, owner, property, jsName));

package/src/docs/pipeline.ts

@@ -6,6 +6,7 @@ import { Library } from "../gir/library.js";
 import { namespaceDirectory } from "../gir/namespace.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";
 import { createElementPageContext, type ElementPageContext, renderElementPage } from "./element-page.js";
 import { elementSlug, firstSentence, namespaceOrder } from "./render.js";
 
@@ -27,7 +28,8 @@ type DocsOptions = {
     outDir: string;
     basePath?: string;
     props?: ElementProps;
-    force?: boolean;
+    omittedProps?: OmittedProps;
+    isForced?: boolean;
 };
 
 type DocsManifest = {
@@ -43,7 +45,7 @@ type Page = { path: string; content: string };
 type NamespacePages = { docs: DocsNamespace; pages: Page[] };
 
 type DocsResult = {
-    regenerated: boolean;
+    isRegenerated: boolean;
     namespaces: DocsNamespace[];
 };
 
@@ -191,7 +193,7 @@ const generatePages = (options: DocsOptions, basePath: string, library: Library)
 };
 
 const cachedDocsResult = (options: DocsOptions, manifestPath: string): DocsResult | undefined => {
-    if (options.force === true || !isGiStoreFresh(options.outDir, options.libraries, options.girPath)) {
+    if (options.isForced === true || !isGiStoreFresh(options.outDir, options.libraries, options.girPath)) {
         return undefined;
     }
 
@@ -201,7 +203,7 @@ const cachedDocsResult = (options: DocsOptions, manifestPath: string): DocsResul
 
     const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as DocsManifest;
 
-    return { regenerated: false, namespaces: manifest.namespaces };
+    return { isRegenerated: false, namespaces: manifest.namespaces };
 };
 
 const writePages = (outDir: string, pages: Page[]): void => {
@@ -214,6 +216,7 @@ const writePages = (outDir: string, pages: Page[]): void => {
 
 const writeDocs = (options: DocsOptions): DocsResult => {
     setElementProps(options.props ?? {});
+    setOmittedProps(options.omittedProps ?? {});
     const basePath = options.basePath ?? "/reference";
     const manifestPath = join(options.outDir, MANIFEST_FILENAME);
     const cached = cachedDocsResult(options, manifestPath);
@@ -235,7 +238,7 @@ const writeDocs = (options: DocsOptions): DocsResult => {
         JSON.stringify(computeGiFingerprint(library.girFiles, options.libraries, options.girPath)),
     );
 
-    return { regenerated: true, namespaces };
+    return { isRegenerated: true, namespaces };
 };
 
-export { writeDocs, type DocsElementLink, type DocsNamespace, type DocsOptions, type DocsResult };
+export { writeDocs };

package/src/docs/render.ts

@@ -45,8 +45,8 @@ const renderDocsHandlerResultType = (library: Library, signal: GirCallable): str
         library,
         signal,
         renderType: (ref, nullable) => renderDocsType(library, ref, nullable),
-        includeCallerAllocated: false,
-        optOut: true,
+        shouldIncludeCallerAllocated: false,
+        isOptOut: true,
     });
 
 const renderDocsHandlerParameters = (library: Library, signal: GirCallable): string[] =>
@@ -69,16 +69,16 @@ const stripDocMedia = (markdown: string): string =>
         .replaceAll(/<video[\s\S]*?(?:<\/video>|\/>)/g, "")
         .replaceAll(/<img[^>]*>/g, "");
 
-const demoteLine = (line: string, isInFence: boolean): { text: string; inFence: boolean } => {
+const demoteLine = (line: string, isInFence: boolean): { text: string; isInFence: boolean } => {
     if (FENCE_LINE.test(line)) {
-        return { text: line, inFence: !isInFence };
+        return { text: line, isInFence: !isInFence };
     }
 
     if (isInFence) {
-        return { text: line, inFence: isInFence };
+        return { text: line, isInFence };
     }
 
-    return { text: HEADING_LINE.test(line) ? `#${line}` : line, inFence: isInFence };
+    return { text: HEADING_LINE.test(line) ? `#${line}` : line, isInFence };
 };
 
 const demoteHeadings = (markdown: string): string => {
@@ -87,7 +87,7 @@ const demoteHeadings = (markdown: string): string => {
 
     for (const line of markdown.split("\n")) {
         const result = demoteLine(line, isInFence);
-        isInFence = result.inFence;
+        isInFence = result.isInFence;
         lines.push(result.text);
     }
 

package/src/docs/symbol-page.ts

@@ -49,12 +49,17 @@ import {
     type SignatureEntry,
 } from "./render.js";
 
+/** What every indexed GIR symbol carries, whatever its kind. */
 type GiSymbolBase = {
+    /** GIR namespace declaring the symbol. */
     namespace: GirNamespace;
+    /** Name the bindings export it under: camelCase for functions, PascalCase for classes, the GIR name otherwise. */
     name: string;
+    /** Raw gtk-doc text from the GIR, undefined when the symbol is undocumented. */
     doc: string | undefined;
 };
 
+/** A GIR symbol the reference indexes, discriminated by `kind` and carrying the GIR node its page renders from. */
 type GiSymbolEntry =
     | (GiSymbolBase & { kind: "class" | "interface"; klass: GirClass }) |
     (GiSymbolBase & { kind: "record"; record: GirRecord }) |
@@ -270,7 +275,7 @@ const propertyMeta = (property: GirProperty, accessor: ResolvedAccessor, origin:
         meta.push("construct-only");
     }
 
-    if (!accessor.writable) {
+    if (!accessor.isWritable) {
         meta.push("read-only");
     } else if (!accessor.hasGetter) {
         meta.push("write-only");
@@ -495,7 +500,7 @@ const recordPage = (entry: GiSymbolBase & { kind: "record"; record: GirRecord },
 };
 
 const fieldMeta = (field: ResolvedRecordField): string =>
-    [`\`${field.tsType}\``, ...(field.writable ? [] : ["read-only"])].join(" · ");
+    [`\`${field.tsType}\``, ...(field.isWritable ? [] : ["read-only"])].join(" · ");
 
 const fieldsSection = (record: GirRecord, context: ModuleContext, claimedNames: Set<string>): string[] => {
     const { slots } = computeRecordFieldSlots(context, record.fields, record.isUnion);

package/src/fingerprint.ts

@@ -5,7 +5,6 @@ import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** The freshness sentinel of the `@gtkx/gi` store, derived purely from the GIR inputs. */
 type GiFingerprint = {
     value: string;
     girFiles: string[];
@@ -15,15 +14,14 @@ type GiFingerprint = {
 
 type ModuleExport = { module: string; export: string };
 
-/** The `@gtkx/react` element config that shapes the generated `@gtkx/jsx` store. */
 type JsxFingerprintInput = {
     reactVersion: string;
     components: Record<string, ModuleExport>;
     lazyElements: string[];
     props: Record<string, ModuleExport>;
+    omittedProps: Record<string, string[]>;
 };
 
-/** The freshness sentinel of the `@gtkx/jsx` store, derived from the React element config. */
 type JsxFingerprint = {
     value: string;
     intrinsicElementCount: number;
@@ -36,8 +34,6 @@ const OVERRIDES_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "o
 
 const sortAlpha = (values: string[]): string => sortStrings(values).join(",");
 
-// The overrides are copied verbatim into the store, so editing one changes the output even though no
-// GIR file moved. Without them in the hash a stale override survives every non-forced run.
 const overrideFiles = (): string[] => {
     if (!existsSync(OVERRIDES_ROOT)) {
         return [];
@@ -55,6 +51,7 @@ const hashGi = (girFiles: string[], libraries: string[], girPath: string[]): str
     hash.update(sortAlpha(libraries));
     hash.update("\n");
     hash.update(sortAlpha(girPath));
+    hash.update("\n");
     const hashedFiles = sortStrings([...girFiles, ...overrideFiles()]);
 
     for (const file of hashedFiles) {
@@ -67,14 +64,22 @@ const hashGi = (girFiles: string[], libraries: string[], girPath: string[]): str
     return hash.digest("hex");
 };
 
-const computeGiFingerprint = (girFiles: string[], libraries: string[], girPath: string[]): GiFingerprint => ({
+const computeGiFingerprint = (
+    girFiles: string[],
+    libraries: string[],
+    girPath: string[],
+): GiFingerprint => ({
     value: hashGi(girFiles, libraries, girPath),
     girFiles,
     libraries,
     girPath,
 });
 
-const isGiStoreFresh = (giStoreDir: string, libraries: string[], girPath: string[]): boolean => {
+const isGiStoreFresh = (
+    giStoreDir: string,
+    libraries: string[],
+    girPath: string[],
+): boolean => {
     const sentinelPath = join(giStoreDir, FINGERPRINT_FILENAME);
 
     if (!existsSync(sentinelPath)) {
@@ -106,6 +111,9 @@ const hasMatchingRecordedInputs = (sentinel: GiFingerprint, libraries: string[],
 const serializeModuleExports = (map: Record<string, ModuleExport>): [string, string, string][] =>
     sortStrings(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] ?? [])]);
+
 const hashJsx = (input: JsxFingerprintInput): string =>
     createHash("sha256")
         .update(
@@ -115,6 +123,7 @@ const hashJsx = (input: JsxFingerprintInput): string =>
                 serializeModuleExports(input.components),
                 sortStrings(input.lazyElements),
                 serializeModuleExports(input.props),
+                serializeOmittedProps(input.omittedProps),
             ]),
         )
         .digest("hex");
@@ -127,11 +136,11 @@ const computeJsxFingerprint = (input: JsxFingerprintInput, intrinsicElementCount
 const jsxStoreFreshness = (
     jsxStoreDir: string,
     input: JsxFingerprintInput,
-): { fresh: boolean; intrinsicElementCount: number } => {
+): { isFresh: boolean; intrinsicElementCount: number } => {
     const sentinelPath = join(jsxStoreDir, FINGERPRINT_FILENAME);
 
     if (!existsSync(sentinelPath)) {
-        return { fresh: false, intrinsicElementCount: 0 };
+        return { isFresh: false, intrinsicElementCount: 0 };
     }
 
     let sentinel: JsxFingerprint;
@@ -139,12 +148,12 @@ const jsxStoreFreshness = (
     try {
         sentinel = JSON.parse(readFileSync(sentinelPath, "utf8")) as JsxFingerprint;
     } catch {
-        return { fresh: false, intrinsicElementCount: 0 };
+        return { isFresh: false, intrinsicElementCount: 0 };
     }
 
     return sentinel.value === hashJsx(input)
-        ? { fresh: true, intrinsicElementCount: sentinel.intrinsicElementCount }
-        : { fresh: false, intrinsicElementCount: 0 };
+        ? { isFresh: true, intrinsicElementCount: sentinel.intrinsicElementCount }
+        : { isFresh: false, intrinsicElementCount: 0 };
 };
 
 export {

package/src/gi.ts

@@ -1,26 +1,28 @@
 import type { Library } from "./gir/library.js";
+import type { StoreOptions } from "./store/store-fs.js";
 import { computeGiFingerprint } from "./fingerprint.js";
 import { namespaceDirectory } from "./gir/namespace.js";
-import { type GiNamespaceInput, type GiStoreOptions, writeGiStore } from "./store/gi-store.js";
+import { type GiNamespaceInput, writeGiStore } from "./store/gi-store.js";
 import { generateNamespaceModule } from "./store/gi/pipeline.js";
 
-/**
- * Generates the `@gtkx/gi` store from the loaded GIR library and links it into the project. This is the
- * react-free half of codegen: it can run before `@gtkx/gi` (or `@gtkx/react`) exists, since it produces them.
- *
- * @returns The number of namespaces written.
- */
-const runGiCodegen = (library: Library, gi: GiStoreOptions, libraries: string[], girPath: string[]): number => {
+type GiCodegenOptions = {
+    gi: StoreOptions;
+    libraries: string[];
+    girPath: string[];
+};
+
+const runGiCodegen = (library: Library, options: GiCodegenOptions): number => {
+    const { gi, libraries, girPath } = options;
+
     const namespaces: GiNamespaceInput[] = Array.from(library.namespaces.values(), (namespace) => ({
         directory: namespaceDirectory(namespace),
         rawSource: generateNamespaceModule(namespace, library),
     }));
 
-    writeGiStore(gi, namespaces, computeGiFingerprint(library.girFiles, [...libraries], [...girPath]));
+    const fingerprint = computeGiFingerprint(library.girFiles, [...libraries], [...girPath]);
+    writeGiStore(gi, namespaces, fingerprint);
 
     return library.namespaces.size;
 };
 
-export { isGiStoreFresh } from "./fingerprint.js";
-export type { GiStoreOptions } from "./store/gi-store.js";
 export { runGiCodegen };

package/src/gir/field.ts

@@ -11,7 +11,6 @@ type GirField = {
     writable: boolean;
     private: boolean;
     bits: number | undefined;
-    /** Members of an anonymous nested `<union>`/`<record>`, which occupies a slot but has no type. */
     inlineMembers: GirField[] | undefined;
     inlineIsUnion: boolean;
 };
@@ -29,9 +28,6 @@ const fieldFromNode = (node: RawNode, context: ParseContext): GirField => ({
     inlineIsUnion: false,
 });
 
-// A record may embed an anonymous `<union>` or `<record>` instead of naming a type for it. The
-// member occupies a real slot and contributes its own size and alignment, but carries no `<type>`,
-// so it has to be admitted as a field whose layout comes from its own children.
 const anonymousMemberFromNode = (node: RawNode, isUnion: boolean, context: ParseContext): GirField => ({
     name: nameAttr(node),
     doc: getDoc(node),

package/src/gir/gir-path.ts

@@ -4,6 +4,13 @@ import { existsSync } from "node:fs";
 
 const SYSTEM_GIR_PATH = "/usr/share/gir-1.0";
 
+/**
+ * The directories to search for `.gir` files, in precedence order: the config's own `girPath`, then
+ * `GTKX_GIR_PATH`, then `/usr/share/gir-1.0`, then the girdir pkg-config reports for
+ * gobject-introspection-1.0. Duplicates are dropped, and the last two are included only when they exist.
+ *
+ * @throws If pkg-config is installed but fails while being queried.
+ */
 const resolveGirPath = (configGirPath: string[] | undefined): string[] => {
     const paths: string[] = [];