@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/react/widgets.ts

@@ -1,185 +0,0 @@
-import { toCamelCase, toIdentifier, toUpperFirst } from "@gtkx/utils";
-import type { GirClass } from "../gir/class.js";
-import type { GirNamespace } from "../gir/namespace.js";
-import { splitQualifiedName } from "../gir/qualified-name.js";
-import type { GirRepository } from "../gir/repository.js";
-
-/**
- * Maps a kebab-case signal name to its `on`-prefixed camelCase handler prop
- * name (e.g. `value-changed` → `onValueChanged`).
- *
- * @param signalName - The GIR signal name
- */
-export const signalHandlerName = (signalName: string): string =>
-    `on${toUpperFirst(toIdentifier(toCamelCase(signalName)))}`;
-
-/** A class qualified by its declaring namespace and the GLib type name it exposes. */
-export type WidgetCandidate = {
-    readonly glibName: string;
-    readonly klass: GirClass;
-    readonly namespace: GirNamespace;
-};
-
-/**
- * Iterates every `(class, namespace, glibName)` triple in the repository whose
- * `glib:type-name` (or C type fallback) is defined.
- *
- * The order follows GIR file order within a namespace and `namespaces` map
- * iteration order between namespaces; callers that need stable output should
- * sort the result themselves.
- *
- * @param repository - The repository to walk
- */
-export function* iterateClassesWithGlibName(repository: GirRepository): IterableIterator<WidgetCandidate> {
-    for (const namespace of repository.namespaces.values()) {
-        for (const klass of namespace.classes) {
-            const glibName = klass.glibTypeName ?? klass.cType;
-            if (glibName === undefined) continue;
-            yield { glibName, klass, namespace };
-        }
-    }
-}
-
-const resolveParentClass = (
-    repository: GirRepository,
-    parent: string,
-    namespace: GirNamespace,
-): { readonly klass: GirClass; readonly namespace: GirNamespace } | undefined => {
-    const { namespaceName, typeName } = splitQualifiedName(parent, namespace.name);
-    const resolved = repository.resolveNamed(namespaceName, typeName);
-    if (resolved === undefined || (resolved.kind !== "class" && resolved.kind !== "interface")) return undefined;
-    return { klass: resolved.value, namespace: resolved.namespace };
-};
-
-/** A resolved interface qualified by the namespace that declares it. */
-export type ResolvedQualifiedInterface = { readonly klass: GirClass; readonly namespace: GirNamespace };
-
-/**
- * Resolves every interface a class implements, including the transitive
- * prerequisite interfaces of those interfaces, nearest first.
- *
- * Interfaces never appear in the GObject type-parent chain, so the React
- * runtime cannot reach an interface's signals or properties by walking a
- * widget's ancestors. Each implementing class must therefore carry its
- * interfaces' metadata directly. Prerequisite interfaces (e.g. a
- * `Gtk.SelectionModel`'s `Gio.ListModel`) are folded in transitively; class
- * prerequisites are ignored because their metadata is reachable through the
- * type-parent chain.
- *
- * @param klass - The class whose interfaces to resolve
- * @param namespace - The namespace the class lives in
- * @param repository - The repository for cross-namespace lookups
- */
-export const implementedInterfaces = (
-    klass: GirClass,
-    namespace: GirNamespace,
-    repository: GirRepository,
-): readonly ResolvedQualifiedInterface[] => {
-    const result: ResolvedQualifiedInterface[] = [];
-    const visited = new Set<string>();
-    const visit = (names: readonly string[], fromNamespace: GirNamespace): void => {
-        for (const name of names) {
-            const { namespaceName, typeName } = splitQualifiedName(name, fromNamespace.name);
-            const resolved = repository.resolveNamed(namespaceName, typeName);
-            if (resolved === undefined || resolved.kind !== "interface") continue;
-            const key = `${resolved.namespace.name}.${resolved.value.name}`;
-            if (visited.has(key)) continue;
-            visited.add(key);
-            result.push({ klass: resolved.value, namespace: resolved.namespace });
-            visit(resolved.value.prerequisites, resolved.namespace);
-        }
-    };
-    visit(klass.implements, namespace);
-    return result;
-};
-
-/**
- * Returns the GLib type names of a class and every ancestor it descends from,
- * nearest first. Used to let a subclass inherit slot-prop declarations made on
- * its ancestors.
- *
- * @param klass - The class to start from
- * @param namespace - The namespace the class lives in
- * @param repository - The repository for cross-namespace parent lookups
- */
-export const ancestorGlibNames = (
-    klass: GirClass,
-    namespace: GirNamespace,
-    repository: GirRepository,
-): readonly string[] => {
-    const names: string[] = [];
-    let currentClass: GirClass | undefined = klass;
-    let currentNamespace: GirNamespace | undefined = namespace;
-    while (currentClass !== undefined && currentNamespace !== undefined) {
-        const glibName = currentClass.glibTypeName ?? currentClass.cType;
-        if (glibName !== undefined) names.push(glibName);
-        if (currentClass.parent === undefined) break;
-        const next = resolveParentClass(repository, currentClass.parent, currentNamespace);
-        if (next === undefined) break;
-        currentClass = next.klass;
-        currentNamespace = next.namespace;
-    }
-    return names;
-};
-
-const descendsFrom = (
-    klass: GirClass,
-    namespace: GirNamespace,
-    repository: GirRepository,
-    matches: (glibName: string) => boolean,
-): boolean => {
-    let currentClass: GirClass | undefined = klass;
-    let currentNamespace: GirNamespace | undefined = namespace;
-    while (currentClass !== undefined && currentNamespace !== undefined) {
-        const glibName = currentClass.glibTypeName ?? currentClass.cType ?? "";
-        if (matches(glibName)) return true;
-        if (currentClass.parent === undefined) return false;
-        const next = resolveParentClass(repository, currentClass.parent, currentNamespace);
-        if (next === undefined) return false;
-        currentClass = next.klass;
-        currentNamespace = next.namespace;
-    }
-    return false;
-};
-
-/**
- * Decides whether a `<class>` is a "widget" for the React reconciler — a
- * descendant (direct or transitive) of `GtkWidget`.
- *
- * Walks the parent chain across namespaces. Returns `false` if any
- * ancestor cannot be resolved (which is preferable to silently treating
- * an unknown type as a widget).
- *
- * @param klass - The class to inspect
- * @param namespace - The namespace the class lives in
- * @param repository - The repository for cross-namespace parent lookups
- */
-export const isWidgetClass = (klass: GirClass, namespace: GirNamespace, repository: GirRepository): boolean =>
-    descendsFrom(klass, namespace, repository, (glibName) => glibName === "GtkWidget");
-
-const AUXILIARY_BASE_TYPES: ReadonlySet<string> = new Set(["GtkEventController", "GtkGesture", "GtkLayoutManager"]);
-
-/**
- * Decides whether a `<class>` is a non-widget React reconciler node — an event
- * controller, gesture, or layout manager (direct or transitive descendant of
- * `GtkEventController`, `GtkGesture`, or `GtkLayoutManager`). These are JSX
- * elements that need the same prop/signal metadata as widgets.
- *
- * @param klass - The class to inspect
- * @param namespace - The namespace the class lives in
- * @param repository - The repository for cross-namespace parent lookups
- */
-const isAuxiliaryReactType = (klass: GirClass, namespace: GirNamespace, repository: GirRepository): boolean =>
-    descendsFrom(klass, namespace, repository, (glibName) => AUXILIARY_BASE_TYPES.has(glibName));
-
-/**
- * Decides whether a `<class>` is any React reconciler node — a widget or one
- * of the auxiliary node kinds. This is the set of classes that need generated
- * prop, signal, and construct-only metadata.
- *
- * @param klass - The class to inspect
- * @param namespace - The namespace the class lives in
- * @param repository - The repository for cross-namespace parent lookups
- */
-export const isReactNodeClass = (klass: GirClass, namespace: GirNamespace, repository: GirRepository): boolean =>
-    isWidgetClass(klass, namespace, repository) || isAuxiliaryReactType(klass, namespace, repository);

package/src/store-fs.ts

@@ -1,157 +0,0 @@
-import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import { transpileSource } from "./transpile.js";
-
-/**
- * Filesystem primitives shared by the injected-package assemblers
- * ({@link ../gi-store.js}, {@link ../jsx-store.js}).
- */
-
-/**
- * Fields every injected-package store assembler needs: where the hidden store
- * lives, the visible alias symlink, and the version stamped onto its manifest.
- */
-export type StoreOptions = {
-    /** Absolute path to the hidden store directory (e.g. `node_modules/.gtkx/gi`). */
-    readonly storeDir: string;
-    /** Absolute path to the visible alias symlink (e.g. `node_modules/@gtkx/gi`). */
-    readonly linkDir: string;
-    /** Version string copied onto the emitted package's `package.json`. */
-    readonly version: string;
-};
-
-/** A transpilable source destined for the store, addressed by output stem. */
-export type StoreFile = {
-    /** Output path without extension, relative to the store root. */
-    readonly stem: string;
-    /** Source filename TypeScript uses for diagnostics. */
-    readonly fileName: string;
-    /** The TypeScript source to transpile and write. */
-    readonly source: string;
-};
-
-/** A symlink to create inside the store's own bundled `node_modules`. */
-export type StoreSymlink = {
-    /** Path segments under the store root the symlink is created at. */
-    readonly segments: readonly string[];
-    /** Absolute symlink target, or `"self"` for the store root itself. */
-    readonly target: string | "self";
-};
-
-/**
- * Assembles a store in a fresh temp directory and atomically swaps it into
- * place: writes every file pair, the `package.json`, the bundled
- * `node_modules` symlinks, then promotes the temp tree and re-points the
- * visible alias. An optional {@link WriteStoreParams.validate} runs against the
- * temp root before any file is written, so a failure aborts before the store
- * goes live.
- *
- * @param params - {@link WriteStoreParams}
- */
-export const writeStore = (params: WriteStoreParams): void => {
-    const tmp = tempStoreFor(params.storeDir);
-    params.validate?.(tmp);
-    for (const file of params.files) {
-        writeFilePair(tmp, file.stem, file.fileName, file.source);
-    }
-    writePackageJson(tmp, params.manifest);
-    for (const raw of params.rawFiles ?? []) {
-        writeFileSync(join(tmp, raw.relativePath), raw.content);
-    }
-    for (const { segments, target } of params.symlinks) {
-        symlinkRelative(join(tmp, ...segments), target === "self" ? tmp : target);
-    }
-    swapStore(tmp, params.storeDir, params.linkDir);
-};
-
-/** Inputs for {@link writeStore}. */
-export type WriteStoreParams = {
-    /** Absolute hidden store directory. */
-    readonly storeDir: string;
-    /** Absolute visible alias symlink. */
-    readonly linkDir: string;
-    /** The source files to transpile and write. */
-    readonly files: readonly StoreFile[];
-    /** The `package.json` manifest to serialize. */
-    readonly manifest: unknown;
-    /** The bundled `node_modules` symlinks to create. */
-    readonly symlinks: readonly StoreSymlink[];
-    /** Verbatim files (e.g. a fingerprint sentinel) written under the store root. */
-    readonly rawFiles?: readonly { readonly relativePath: string; readonly content: string }[];
-    /** Optional in-memory validation run on the temp root before files are written. */
-    readonly validate?: (tmp: string) => void;
-};
-
-/**
- * Transpiles `source` and writes the resulting `.js`/`.d.ts` pair at `stem`
- * (relative to `storeDir`), creating parent directories as needed.
- *
- * @param storeDir - Absolute store root the file is written under
- * @param stem - Output path without extension, relative to `storeDir`
- * @param fileName - Source filename TypeScript uses for diagnostics
- * @param source - The TypeScript source to transpile
- */
-export const writeFilePair = (storeDir: string, stem: string, fileName: string, source: string): void => {
-    const { js, dts } = transpileSource(fileName, source);
-    const jsPath = join(storeDir, `${stem}.js`);
-    mkdirSync(dirname(jsPath), { recursive: true });
-    writeFileSync(jsPath, js);
-    writeFileSync(join(storeDir, `${stem}.d.ts`), dts);
-};
-
-/**
- * Creates (or replaces) a relative directory symlink at `linkPath` pointing at
- * `realTarget`. Relative so the link survives the store being moved or cached.
- *
- * @param linkPath - Absolute path of the symlink to create
- * @param realTarget - Absolute path the symlink resolves to
- */
-export const symlinkRelative = (linkPath: string, realTarget: string): void => {
-    mkdirSync(dirname(linkPath), { recursive: true });
-    rmSync(linkPath, { recursive: true, force: true });
-    symlinkSync(relative(dirname(linkPath), realTarget), linkPath, "dir");
-};
-
-/**
- * Writes a pretty-printed `package.json` into `storeDir`.
- *
- * @param storeDir - Absolute directory to write `package.json` into
- * @param manifest - The manifest object to serialize
- */
-export const writePackageJson = (storeDir: string, manifest: unknown): void => {
-    writeFileSync(join(storeDir, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
-};
-
-/**
- * Swaps a fully-assembled temp store into place and re-points the visible alias
- * at it.
- *
- * The live store is renamed aside and the temp store renamed in before the old
- * tree is deleted, so the store is unavailable only for the duration of a single
- * rename instead of a full recursive delete. Not safe against a second codegen
- * run swapping the same store concurrently.
- *
- * @param tmp - Absolute temp store directory to promote
- * @param storeDir - Absolute final store directory
- * @param visibleLink - Absolute path of the visible alias symlink
- */
-export const swapStore = (tmp: string, storeDir: string, visibleLink: string): void => {
-    const previous = `${storeDir}.old`;
-    rmSync(previous, { recursive: true, force: true });
-    if (existsSync(storeDir)) {
-        renameSync(storeDir, previous);
-    }
-    renameSync(tmp, storeDir);
-    rmSync(previous, { recursive: true, force: true });
-    symlinkRelative(visibleLink, storeDir);
-};
-
-/**
- * Creates a fresh, per-run temporary store directory next to `storeDir` and
- * returns its path. The random suffix isolates concurrent or repeated runs so
- * they cannot corrupt each other's in-progress trees.
- */
-export const tempStoreFor = (storeDir: string): string => {
-    mkdirSync(dirname(storeDir), { recursive: true });
-    return mkdtempSync(`${storeDir}.tmp-`);
-};

package/src/transpile.ts

@@ -1,80 +0,0 @@
-import ts from "typescript";
-
-/**
- * Output of a single TypeScript transpile: the stripped `.js` and the
- * isolated-declaration `.d.ts` it produces.
- */
-export type TranspiledFile = {
-    /** Stripped-types JavaScript output. */
-    readonly js: string;
-    /** Generated TypeScript declaration output. */
-    readonly dts: string;
-};
-
-/**
- * The compiler options shared by the store's two TypeScript passes — the
- * single-file transpile here and the overlay type-check in `typecheck-store.ts`.
- * Each pass spreads these and adds its own emit/check-specific keys.
- */
-export const baseCompilerOptions = (): ts.CompilerOptions => ({
-    module: ts.ModuleKind.ESNext,
-    moduleResolution: ts.ModuleResolutionKind.Bundler,
-    target: ts.ScriptTarget.ESNext,
-    skipLibCheck: true,
-    jsx: ts.JsxEmit.ReactJSX,
-    jsxImportSource: "react",
-});
-
-const COMPILER_OPTIONS: ts.CompilerOptions = {
-    ...baseCompilerOptions(),
-    declaration: true,
-    skipDefaultLibCheck: true,
-    removeComments: false,
-    sourceMap: false,
-    declarationMap: false,
-};
-
-/**
- * Transpiles a single TypeScript source string to a `.js` / `.d.ts` pair.
- *
- * Uses `ts.transpileModule` for the JS half (type-stripping only, no
- * type checking) and `ts.transpileDeclaration` for the declaration half
- * (single-file declaration emit). Generated sources annotate every export
- * for isolated-declaration emit, so `transpileDeclaration` always
- * succeeds; an error-category diagnostic from it represents a writer bug
- * and is surfaced rather than swallowed.
- *
- * @param fileName - Source filename, used by TS for path resolution
- * @param source - The TypeScript source string
- */
-export const transpileSource = (fileName: string, source: string): TranspiledFile => {
-    const jsResult = ts.transpileModule(source, {
-        compilerOptions: COMPILER_OPTIONS,
-        fileName,
-        reportDiagnostics: false,
-    });
-    const dtsResult = ts.transpileDeclaration(source, {
-        compilerOptions: COMPILER_OPTIONS,
-        fileName,
-    });
-    const errorDiagnostics = (dtsResult.diagnostics ?? []).filter(
-        (diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error,
-    );
-    if (errorDiagnostics.length > 0) {
-        const messages = errorDiagnostics
-            .slice(0, 5)
-            .map((diagnostic) => {
-                const text = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
-                if (diagnostic.file && diagnostic.start !== undefined) {
-                    const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
-                    return `[${line + 1}:${character + 1}] ${text}`;
-                }
-                return text;
-            })
-            .join("\n");
-        throw new Error(
-            `transpileDeclaration produced ${errorDiagnostics.length} diagnostic(s) for ${fileName}:\n${messages}`,
-        );
-    }
-    return { js: jsResult.outputText, dts: dtsResult.outputText };
-};

package/src/typecheck-store.ts

@@ -1,136 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import ts from "typescript";
-import { baseCompilerOptions } from "./transpile.js";
-
-/**
- * One in-memory source destined for the injected `@gtkx/gi` store, plus whether
- * it is a hand-written overlay (the type-check target) or a generated module
- * declaration (checked against, but not reported on).
- */
-export type StoreSourceFile = {
-    /** Absolute virtual path of the source, under the store root. */
-    readonly path: string;
-    /** TypeScript source text (overlay `.ts`) or declaration text (generated `.d.ts`). */
-    readonly source: string;
-    /** Whether this is a hand-written overlay/augment source. */
-    readonly overlay: boolean;
-};
-
-const GI_SPECIFIER = "@gtkx/gi/";
-
-const COMPILER_OPTIONS: ts.CompilerOptions = {
-    ...baseCompilerOptions(),
-    customConditions: ["source"],
-    strict: true,
-    noEmit: true,
-    types: [],
-};
-
-/**
- * Source entries the overlay type-check resolves the runtime packages to.
- */
-export type RuntimeEntries = {
-    /** Absolute path to `@gtkx/ffi`'s source entry (`src/index.ts`). */
-    readonly ffiEntry: string;
-    /** Absolute path to `@gtkx/native`'s declaration entry (`dist/index.d.ts`). */
-    readonly nativeEntry: string;
-};
-
-const buildCompilerHost = (
-    storeRoot: string,
-    virtualSources: ReadonlyMap<string, string>,
-    entries: RuntimeEntries,
-): ts.CompilerHost => {
-    const readSource = (fileName: string): string | undefined =>
-        virtualSources.get(fileName) ?? (existsSync(fileName) ? readFileSync(fileName, "utf8") : undefined);
-
-    const resolveInjected = (specifier: string): string | undefined => {
-        if (specifier === "@gtkx/ffi") return entries.ffiEntry;
-        if (specifier === "@gtkx/native") return entries.nativeEntry;
-        if (!specifier.startsWith(GI_SPECIFIER)) return undefined;
-        const stem = specifier.slice(GI_SPECIFIER.length).replace(/\.js$/, "");
-        return [`${stem}.d.ts`, `${stem}.ts`, `${stem}/index.d.ts`, `${stem}/index.ts`]
-            .map((candidate) => join(storeRoot, candidate))
-            .find((candidate) => virtualSources.has(candidate));
-    };
-
-    const moduleResolutionHost: ts.ModuleResolutionHost = {
-        fileExists: (fileName) => virtualSources.has(fileName) || existsSync(fileName),
-        readFile: readSource,
-    };
-
-    return {
-        getSourceFile: (fileName, languageVersion) => {
-            const source = readSource(fileName);
-            return source === undefined ? undefined : ts.createSourceFile(fileName, source, languageVersion, true);
-        },
-        getDefaultLibFileName: (options) => ts.getDefaultLibFilePath(options),
-        writeFile: () => {},
-        getCurrentDirectory: () => storeRoot,
-        getCanonicalFileName: (fileName) => fileName,
-        useCaseSensitiveFileNames: () => true,
-        getNewLine: () => "\n",
-        fileExists: (fileName) => virtualSources.has(fileName) || existsSync(fileName),
-        readFile: readSource,
-        resolveModuleNameLiterals: (literals, containingFile, _redirectedReference, options) =>
-            literals.map((literal) => {
-                const injected = resolveInjected(literal.text);
-                if (injected !== undefined) {
-                    return { resolvedModule: { resolvedFileName: injected, extension: ts.Extension.Ts } };
-                }
-                return {
-                    resolvedModule: ts.resolveModuleName(literal.text, containingFile, options, moduleResolutionHost)
-                        .resolvedModule,
-                };
-            }),
-    };
-};
-
-const reportOverlayErrors = (program: ts.Program, overlayPaths: readonly string[], storeRoot: string): void => {
-    const errors: ts.Diagnostic[] = [];
-    for (const path of overlayPaths) {
-        const sourceFile = program.getSourceFile(path);
-        if (!sourceFile) continue;
-        for (const diagnostic of program.getSemanticDiagnostics(sourceFile)) {
-            if (diagnostic.category === ts.DiagnosticCategory.Error) errors.push(diagnostic);
-        }
-    }
-    if (errors.length === 0) return;
-    const formatted = ts.formatDiagnosticsWithColorAndContext(errors, {
-        getCurrentDirectory: () => storeRoot,
-        getCanonicalFileName: (fileName) => fileName,
-        getNewLine: () => "\n",
-    });
-    throw new Error(`Overlay type-check failed against the generated @gtkx/gi API:\n${formatted}`);
-};
-
-/**
- * Type-checks the hand-written overlay sources against the freshly generated
- * `@gtkx/gi` declarations, entirely in memory.
- *
- * The overlay augments generated classes (e.g. installs `Value.prototype.getBoxed`),
- * so its correctness is only meaningful relative to the exact API codegen just
- * produced. A {@link ts.Program} is assembled over the in-memory generated
- * declarations and overlay sources, resolving `@gtkx/gi/*` to the generated
- * declarations and `@gtkx/ffi` to its package source; every other specifier
- * (`react`, lib files) resolves from the real filesystem. Semantic errors on the
- * overlay sources abort codegen rather than ship broken bindings.
- *
- * @param storeRoot - Absolute root the virtual source paths are rooted at.
- * @param files - The in-memory generated declarations and overlay sources.
- * @param entries - Absolute source entries for `@gtkx/ffi` and `@gtkx/native`.
- * @throws When any overlay source has a semantic type error.
- */
-export const typecheckGiStore = (
-    storeRoot: string,
-    files: readonly StoreSourceFile[],
-    entries: RuntimeEntries,
-): void => {
-    const overlayPaths = files.filter((file) => file.overlay).map((file) => file.path);
-    if (overlayPaths.length === 0) return;
-    const virtualSources = new Map(files.map((file) => [file.path, file.source]));
-    const host = buildCompilerHost(storeRoot, virtualSources, entries);
-    const program = ts.createProgram({ rootNames: files.map((file) => file.path), options: COMPILER_OPTIONS, host });
-    reportOverlayErrors(program, overlayPaths, storeRoot);
-};

package/src/writers/alias.ts

@@ -1,19 +0,0 @@
-import type { ModuleContext } from "../dsl/context.js";
-import { aliasExportName } from "../dsl/identifier.js";
-import type { GirAlias } from "../gir/namespace.js";
-import { renderTsType } from "./ts-type.js";
-
-/**
- * Emits an `export type` declaration for a GIR `<alias>`.
- *
- * The alias is exported under {@link aliasExportName} — its GIR `name`, with
- * GObject's `Type` published as `GType`.
- *
- * @param context - The module context
- * @param alias - The alias to emit
- */
-export const emitAlias = (context: ModuleContext, alias: GirAlias): void => {
-    const exportName = aliasExportName(context.namespace.name, alias.name);
-    const targetType = renderTsType(context, alias.target);
-    context.module.appendDeclaration(`export type ${exportName} = ${targetType};`);
-};

package/src/writers/async.ts

@@ -1,44 +0,0 @@
-import type { GirFunction } from "../gir/function.js";
-
-/**
- * Detects the start half of a `Gio.AsyncReady` callable pair.
- *
- * Pairs follow two GIR conventions: an explicit `*_async` / `*_finish`
- * suffix (the older style), or a base name paired with a `<root>_finish`
- * (the modern GTK 4 style, e.g. `gtk_file_dialog_open` /
- * `gtk_file_dialog_open_finish`).
- *
- * The runtime convention is to wrap the pair with `promisify(asyncFn,
- * finishFn, cancellable, { leading })`. This detector returns the
- * matching finish counterpart's GIR name when one exists in the same
- * set of callables, so the class writer can wire the wrapper.
- *
- * @param fn - The candidate async-start callable
- * @param siblings - Other callables on the same type to scan for the
- *     matching `*_finish`
- * @returns The matching `*_finish` GIR name, or `undefined` when there is
- *     no pair
- */
-export const matchAsyncFinishName = (fn: GirFunction, siblings: readonly GirFunction[]): string | undefined => {
-    if (fn.name.endsWith("_async")) {
-        const root = fn.name.slice(0, -"_async".length);
-        const finishName = `${root}_finish`;
-        const match = siblings.find((sibling) => sibling.name === finishName);
-        return match === undefined ? undefined : finishName;
-    }
-    if (fn.name.endsWith("_finish")) return undefined;
-    const finishName = `${fn.name}_finish`;
-    const match = siblings.find((sibling) => sibling.name === finishName);
-    if (match === undefined) return undefined;
-    if (!hasAsyncReadyCallbackParameter(fn)) return undefined;
-    return finishName;
-};
-
-const hasAsyncReadyCallbackParameter = (fn: GirFunction): boolean => {
-    for (const parameter of fn.parameters) {
-        if (parameter.scope !== undefined) return true;
-        if (parameter.type?.kind !== "named") continue;
-        if (parameter.type.typeName === "AsyncReadyCallback") return true;
-    }
-    return false;
-};