@gtkx/codegen 1.2.2 → 1.4.0

package/src/gir/library.ts

@@ -24,6 +24,18 @@ type TypeTable = {
     index: Map<string, number>;
 };
 
+/** Behavior a project opted into ahead of the next major version, through the `future` block of its config. */
+type FutureBehavior = {
+    /** Whether byte sequences render as `Uint8Array` rather than `number[]`. */
+    isByteArrayTyped?: boolean;
+    /** Whether a `GObject.Value` a binding hands back surfaces as what it holds rather than as the value. */
+    isValueUnwrapped?: boolean;
+    /** Whether a promisified result drops the leading success boolean of a throwing finish function. */
+    isFinishTrimmed?: boolean;
+    /** Whether a handle-passing inout parameter is mutated in place rather than packed into the result. */
+    isInoutInPlace?: boolean;
+};
+
 /** A namespace whose header has been read and whose shell is registered, before its body is parsed. */
 type DiscoveredNamespace = {
     /** Attributes and includes read from the namespace's GIR file. */
@@ -84,12 +96,15 @@ class Library {
      *
      * @param libraries GIR identifiers to load, such as `Gtk-4.0`.
      * @param girPath Directories searched, in order, for each `.gir` file.
-     * @param isByteArrayTyped Whether byte sequences render as `Uint8Array` rather than `number[]`.
+     * @param future Behavior the project opted into ahead of the next major version.
      * @returns A library holding every namespace that was parsed.
      */
-    static load(libraries: string[], girPath: string[], isByteArrayTyped = false): Library {
+    static load(libraries: string[], girPath: string[], future: FutureBehavior = {}): Library {
         const library = new Library();
-        library.isByteArrayTypedValue = isByteArrayTyped;
+        library.isByteArrayTypedValue = future.isByteArrayTyped === true;
+        library.isValueUnwrappedValue = future.isValueUnwrapped === true;
+        library.isFinishTrimmedValue = future.isFinishTrimmed === true;
+        library.isInoutInPlaceValue = future.isInoutInPlace === true;
         this.drive(library, libraries, girPath);
 
         return library;
@@ -102,6 +117,9 @@ class Library {
     private typeTables: TypeTable[] = [];
     private girFilesValue: string[] = [];
     private isByteArrayTypedValue = false;
+    private isValueUnwrappedValue = false;
+    private isFinishTrimmedValue = false;
+    private isInoutInPlaceValue = false;
 
     /** Creates a library with no namespaces loaded; {@link Library.load} builds a populated one. */
     constructor() {
@@ -336,6 +354,21 @@ class Library {
         return this.isByteArrayTypedValue;
     }
 
+    /** Whether a `GObject.Value` a binding hands back surfaces as what it holds rather than as the value. */
+    public get isValueUnwrapped(): boolean {
+        return this.isValueUnwrappedValue;
+    }
+
+    /** Whether a promisified result drops the leading success boolean of a throwing finish function. */
+    public get isFinishTrimmed(): boolean {
+        return this.isFinishTrimmedValue;
+    }
+
+    /** Whether a handle-passing inout parameter is mutated in place rather than packed into the result. */
+    public get isInoutInPlace(): boolean {
+        return this.isInoutInPlaceValue;
+    }
+
     /** Paths of the `.gir` files that were read, in the order they were discovered. */
     public get girFiles(): string[] {
         return this.girFilesValue;

package/src/gir/ucs4-overrides.ts

@@ -0,0 +1,7 @@
+const RETURNS_MISSING_UCS4_ARRAY_TYPE: Set<string> = new Set([
+    "g_utf8_to_ucs4",
+    "g_utf8_to_ucs4_fast",
+    "g_utf16_to_ucs4",
+]);
+
+export { RETURNS_MISSING_UCS4_ARRAY_TYPE };

package/src/guards.ts

@@ -12,6 +12,11 @@ const isString = (value: unknown): value is string => typeof value === "string";
 const arrayGuard = <T>(isEntry: Guard<T>): Guard<T[]> =>
     (value: unknown): value is T[] => Array.isArray(value) && value.every((entry: unknown) => isEntry(entry));
 
+const recordGuard = <T>(isEntry: Guard<T>): Guard<Record<string, T>> =>
+    (value: unknown): value is Record<string, T> =>
+        isRecord(value) && !Array.isArray(value) &&
+        Object.values(value).every((entry: unknown) => isEntry(entry));
+
 const optionalGuard = <T>(isPresent: Guard<T>): OptionalGuard<T> =>
     Object.assign((value: unknown): value is T | undefined => value === undefined || isPresent(value), {
         __optional__: true as const,
@@ -20,4 +25,4 @@ const optionalGuard = <T>(isPresent: Guard<T>): OptionalGuard<T> =>
 const hasFields = <T extends object>(value: unknown, guards: FieldGuards<T>): value is T =>
     isRecord(value) && Object.entries(guards).every(([name, guard]) => (guard as Guard<unknown>)(value[name]));
 
-export { arrayGuard, hasFields, isBoolean, isNumber, isString, optionalGuard };
+export { arrayGuard, hasFields, isBoolean, isNumber, isString, optionalGuard, recordGuard };

package/src/index.ts

@@ -20,6 +20,8 @@ export { type BuiltinElements, type ModuleExport, readBuiltinElements } from "./
 /** @public */
 export { type CodegenRunnerOptions, type CodegenRunnerResult, runCodegen } from "./runner.js";
 /** @public */
+export { type GeneratedLibraries, readGeneratedLibraries } from "./store/gi/generated-libraries.js";
+/** @public */
 export type { ElementProps } from "./store/jsx/element-prop-imports.js";
 /** @public */
 export { type GeneratedElement, readGeneratedElements } from "./store/jsx/generated-elements.js";

package/src/jsx.ts

@@ -6,6 +6,7 @@ import {
     type JsxFingerprintInput,
     jsxStoreFreshness,
 } from "./fingerprint.js";
+import { externalPackageFor } from "./gir/external-namespaces.js";
 import { type ModuleExport, readBuiltinElements } from "./react/element-config.js";
 import { writeJsxStore } from "./store/jsx-store.js";
 import { ELEMENTS_FILENAME, renderGeneratedElements } from "./store/jsx/generated-elements.js";
@@ -39,6 +40,7 @@ const runJsxCodegen = async (options: RunJsxCodegenOptions): Promise<RunJsxCodeg
 
     const fingerprintInput: JsxFingerprintInput = {
         reactVersion: options.jsx.version,
+        reactSubexports: options.reactSubexports,
         components,
         lazyElements,
         props,
@@ -53,7 +55,9 @@ const runJsxCodegen = async (options: RunJsxCodegenOptions): Promise<RunJsxCodeg
         }
     }
 
-    const { namespaces, metadata, intrinsicElementCount, elements } = generateJsxFiles(options.getLibrary(), {
+    const library = options.getLibrary();
+
+    const { namespaces, metadata, intrinsicElementCount, elements } = generateJsxFiles(library, {
         reactSubexports: options.reactSubexports,
         components,
         lazyElements,
@@ -61,15 +65,36 @@ const runJsxCodegen = async (options: RunJsxCodegenOptions): Promise<RunJsxCodeg
         omittedProps,
     });
 
-    writeJsxStore(options.jsx, namespaces, metadata, [
-        {
-            relativePath: FINGERPRINT_FILENAME,
-            content: `${JSON.stringify(computeJsxFingerprint(fingerprintInput, intrinsicElementCount), null, 2)}\n`,
-        },
-        { relativePath: ELEMENTS_FILENAME, content: renderGeneratedElements(elements) },
-    ]);
+    writeJsxStore({
+        options: options.jsx,
+        namespaces,
+        metadata,
+        externalPackages: storeExternalPackages(library),
+        rawFiles: [
+            {
+                relativePath: FINGERPRINT_FILENAME,
+                content:
+                    `${JSON.stringify(computeJsxFingerprint(fingerprintInput, intrinsicElementCount), null, 2)}\n`,
+            },
+            { relativePath: ELEMENTS_FILENAME, content: renderGeneratedElements(elements) },
+        ],
+    });
 
     return { isRegenerated: true, intrinsicElementCount };
 };
 
+const storeExternalPackages = (library: Library): string[] => {
+    const packages: Set<string> = new Set();
+
+    for (const namespace of library.namespaces.values()) {
+        const packageName = externalPackageFor(namespace.name);
+
+        if (packageName !== undefined) {
+            packages.add(packageName);
+        }
+    }
+
+    return [...packages];
+};
+
 export { runJsxCodegen };

package/src/runner.ts

@@ -8,6 +8,7 @@ import { runGiCodegen } from "./gi.js";
 import { Library } from "./gir/library.js";
 import { generateGlModules, type GlGenerationReport } from "./khronos/pipeline.js";
 import { sweepStagingDirs } from "./staging.js";
+import { externalPackageNotices } from "./store/external-package-links.js";
 import { ensureStoreLink, type StoreOptions } from "./store/store-fs.js";
 
 type GlCodegenOptions = {
@@ -41,6 +42,12 @@ type CodegenRunnerOptions = {
     isForced?: boolean;
     /** Emits GIR byte sequences as `Uint8Array` rather than `number[]`; defaults to false. */
     isByteArrayTyped?: boolean;
+    /** Surfaces a `GObject.Value` a binding hands back as what it holds rather than as the value; defaults to false. */
+    isValueUnwrapped?: boolean;
+    /** Drops the leading success boolean from promisified results of a throwing finish; defaults to false. */
+    isFinishTrimmed?: boolean;
+    /** Mutates a handle-passing inout parameter in place instead of packing it into the result; defaults to false. */
+    isInoutInPlace?: boolean;
 };
 
 /** What a `runCodegen` run produced. */
@@ -51,6 +58,8 @@ type CodegenRunnerResult = {
     namespaces: number;
     /** How many JSX elements the jsx store binds, zero when no jsx store was requested. */
     intrinsicElements: number;
+    /** Deprecation notices about how the store was wired, one line each; empty when nothing needs attention. */
+    notices: string[];
     /** Wall-clock duration of the run, in milliseconds. */
     duration: number;
 };
@@ -83,6 +92,7 @@ const runCodegen = async (options: CodegenRunnerOptions): Promise<CodegenRunnerR
         isRegenerated: store.isRegenerated,
         namespaces: store.namespaces,
         intrinsicElements: store.intrinsicElements,
+        notices: externalPackageNotices(options.gi),
         duration: Date.now() - start,
     };
 };
@@ -160,13 +170,17 @@ const emitStoresWithConfig = async (config: {
 }): Promise<StoreResult> => {
     const { options, gi, jsx, libraries, girPath } = config;
     const isByteArrayTyped = options.isByteArrayTyped === true;
+    const isValueUnwrapped = options.isValueUnwrapped === true;
+    const isFinishTrimmed = options.isFinishTrimmed === true;
+    const isInoutInPlace = options.isInoutInPlace === true;
+    const future = { isByteArrayTyped, isValueUnwrapped, isFinishTrimmed, isInoutInPlace };
     let library: Library | undefined;
-    const loadLibrary = (): Library => (library ??= Library.load(libraries, girPath, isByteArrayTyped));
-    const giInputs = { girFiles: [] as string[], libraries, girPath, isByteArrayTyped };
+    const loadLibrary = (): Library => (library ??= Library.load(libraries, girPath, future));
+    const giInputs = { girFiles: [] as string[], libraries, girPath, storeVersion: gi.version, ...future };
     const isGiRegenerated = options.isForced === true || !isGiStoreFresh(gi.storeDir, giInputs);
 
     const namespaces = isGiRegenerated
-        ? runGiCodegen(loadLibrary(), { gi, libraries, girPath, isByteArrayTyped })
+        ? runGiCodegen(loadLibrary(), { gi, libraries, girPath, ...future })
         : 0;
 
     if (jsx === undefined) {

package/src/store/external-package-links.ts

@@ -0,0 +1,226 @@
+import { existsSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { EXTERNAL_NAMESPACES, type ExternalNamespace } from "../gir/external-namespaces.js";
+import { nodeModulesChain } from "./resolve-store.js";
+import { type StoreLink, symlinkRelative } from "./store-fs.js";
+
+type ExternalPackageSource = "store" | "hoisted" | "codegen";
+
+type ExternalPackageResolution = {
+    packageName: string;
+    directory: string;
+    dir: string;
+    source: ExternalPackageSource;
+};
+
+const DEPENDENCY_FIELDS = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+const codegenRequire = createRequire(import.meta.url);
+const codegenPackageDirs: Map<string, string | undefined> = new Map();
+const ensuredStores: Set<string> = new Set();
+
+const storeAnchor = (link: StoreLink): string => dirname(dirname(link.linkDir));
+const namespaceShimDirectory = (entry: ExternalNamespace): string => entry.namespace.toLowerCase();
+
+const resolveFromStore = (link: StoreLink, packageName: string): string | undefined => {
+    const chain = nodeModulesChain(dirname(storeAnchor(link)));
+
+    for (const nodeModules of chain) {
+        const manifest = join(nodeModules, packageName, "package.json");
+
+        if (existsSync(manifest)) {
+            return dirname(realpathSync(manifest));
+        }
+    }
+
+    return undefined;
+};
+
+const projectManifestPath = (link: StoreLink): string => join(dirname(storeAnchor(link)), "package.json");
+
+const readManifest = (manifestPath: string): Record<string, unknown> | undefined => {
+    try {
+        return JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>;
+    } catch {
+        return undefined;
+    }
+};
+
+const sectionNames = (section: unknown): string[] =>
+    typeof section === "object" && section !== null ? Object.keys(section) : [];
+
+const declaredDependencies = (manifest: Record<string, unknown>): Set<string> =>
+    new Set(DEPENDENCY_FIELDS.flatMap((field) => sectionNames(manifest[field])));
+
+const isDeclaredByProject = (link: StoreLink, packageName: string): boolean => {
+    const manifest = readManifest(projectManifestPath(link));
+
+    return manifest === undefined || declaredDependencies(manifest).has(packageName);
+};
+
+const resolveFromCodegen = (packageName: string): string | undefined => {
+    if (codegenPackageDirs.has(packageName)) {
+        return codegenPackageDirs.get(packageName);
+    }
+
+    let dir: string | undefined;
+
+    try {
+        dir = dirname(realpathSync(codegenRequire.resolve(`${packageName}/package.json`)));
+    } catch {
+        dir = undefined;
+    }
+
+    codegenPackageDirs.set(packageName, dir);
+
+    return dir;
+};
+
+const resolveEntry = (link: StoreLink, entry: ExternalNamespace): ExternalPackageResolution | undefined => {
+    const directory = namespaceShimDirectory(entry);
+    const chainResolved = resolveFromStore(link, entry.packageName);
+
+    if (chainResolved !== undefined) {
+        const source = isDeclaredByProject(link, entry.packageName) ? "store" : "hoisted";
+
+        return { packageName: entry.packageName, directory, dir: chainResolved, source };
+    }
+
+    const codegenDir = resolveFromCodegen(entry.packageName);
+
+    if (codegenDir !== undefined) {
+        return { packageName: entry.packageName, directory, dir: codegenDir, source: "codegen" };
+    }
+
+    return undefined;
+};
+
+const resolveExternalPackages = (link: StoreLink): ExternalPackageResolution[] => {
+    const resolutions: ExternalPackageResolution[] = [];
+
+    for (const entry of EXTERNAL_NAMESPACES) {
+        const resolution = resolveEntry(link, entry);
+
+        if (resolution !== undefined) {
+            resolutions.push(resolution);
+        }
+    }
+
+    return resolutions;
+};
+
+const isLinkedTo = (linkPath: string, dir: string): boolean => {
+    try {
+        return realpathSync(linkPath) === realpathSync(dir);
+    } catch {
+        return false;
+    }
+};
+
+const applyLink = (storeDir: string, resolution: ExternalPackageResolution): void => {
+    const linkPath = join(storeDir, "node_modules", resolution.packageName);
+
+    if (resolution.source === "codegen") {
+        if (!isLinkedTo(linkPath, resolution.dir)) {
+            symlinkRelative(linkPath, resolution.dir);
+        }
+
+        return;
+    }
+
+    rmSync(linkPath, { recursive: true, force: true });
+};
+
+const tryApplyLink = (storeDir: string, resolution: ExternalPackageResolution): void => {
+    try {
+        applyLink(storeDir, resolution);
+    } catch {
+        return;
+    }
+};
+
+const ensureExternalPackageLinks = (link: StoreLink): void => {
+    if (ensuredStores.has(link.storeDir)) {
+        return;
+    }
+
+    if (!existsSync(join(link.storeDir, "package.json"))) {
+        return;
+    }
+
+    for (const resolution of resolveExternalPackages(link)) {
+        tryApplyLink(link.storeDir, resolution);
+    }
+
+    ensuredStores.add(link.storeDir);
+};
+
+const resetExternalPackageLinks = (storeDir: string): void => {
+    ensuredStores.delete(storeDir);
+};
+
+const externalPackageNotice = (resolution: ExternalPackageResolution): string =>
+    `${resolution.packageName} is not installed in this project, so the copy @gtkx/codegen depends on was ` +
+    `linked into the generated store; add ${resolution.packageName} to your dependencies, because GTKX 2.0 ` +
+    "stops doing this.";
+
+const hoistedPackageNotice = (resolution: ExternalPackageResolution): string =>
+    `${resolution.packageName} is not declared in this project's package.json and only resolves because ` +
+    `your package manager hoisted it; add ${resolution.packageName} to your dependencies, because GTKX 2.0 ` +
+    "requires the direct dependency.";
+
+const hasShim = (storeDir: string, entry: ExternalNamespace): boolean =>
+    existsSync(join(storeDir, namespaceShimDirectory(entry), "index.js"));
+
+const hasStoreLocalLink = (storeDir: string, packageName: string): boolean =>
+    existsSync(join(storeDir, "node_modules", packageName, "package.json"));
+
+const unresolvableMessage = (link: StoreLink, entry: ExternalNamespace): string =>
+    `Cannot resolve ${entry.packageName} from ${storeAnchor(link)} or from @gtkx/codegen; ` +
+    "install it next to @gtkx/runtime.";
+
+const linkFailedMessage = (link: StoreLink, entry: ExternalNamespace): string =>
+    `Cannot link ${entry.packageName} into the generated store at ${link.storeDir}; ` +
+    `install ${entry.packageName} next to @gtkx/runtime.`;
+
+const entryNotice = (link: StoreLink, entry: ExternalNamespace): string | undefined => {
+    if (!hasShim(link.storeDir, entry)) {
+        return undefined;
+    }
+
+    const resolution = resolveEntry(link, entry);
+
+    if (resolution === undefined) {
+        throw new Error(unresolvableMessage(link, entry));
+    }
+
+    if (resolution.source === "store") {
+        return undefined;
+    }
+
+    if (resolution.source === "hoisted") {
+        return hoistedPackageNotice(resolution);
+    }
+
+    if (!hasStoreLocalLink(link.storeDir, resolution.packageName)) {
+        throw new Error(linkFailedMessage(link, entry));
+    }
+
+    return externalPackageNotice(resolution);
+};
+
+const externalPackageNotices = (link: StoreLink): string[] => {
+    const notices: string[] = [];
+
+    for (const entry of EXTERNAL_NAMESPACES) {
+        const notice = entryNotice(link, entry);
+
+        if (notice !== undefined) {
+            notices.push(notice);
+        }
+    }
+
+    return notices;
+};
+
+export { ensureExternalPackageLinks, externalPackageNotices, resetExternalPackageLinks };

package/src/store/gi/callable-doc.ts

@@ -12,7 +12,7 @@ import {
 } from "../../analysis/param-structure.js";
 import { renderJsDoc } from "../../writer/doc.js";
 import { annotationSpec, THROWS_TEXT } from "./doc-spec.js";
-import { isCallbackParameter, returnedOutParameters } from "./method.js";
+import { isCallbackParameter, returnedOutParameters, shouldTrimFinishBoolean } from "./method.js";
 
 type CallableDocOptions = {
     finishFn?: GirFunction | undefined;
@@ -53,9 +53,9 @@ const tupleReturnsText = (primary: string | undefined, outs: InputParameter[]):
     return bullets.length === 0 ? undefined : `Tuple of:\n\n${bullets.join("\n")}`;
 };
 
-const returnsText = (context: ModuleContext, fn: GirFunction): string | undefined => {
+const returnsText = (context: ModuleContext, fn: GirFunction, isPrimaryTrimmed: boolean): string | undefined => {
     const outs = returnedOutParameters(context, fn);
-    const isPrimaryOmitted = shouldOmitPrimaryReturn(context.library, fn.returnValue);
+    const isPrimaryOmitted = isPrimaryTrimmed || shouldOmitPrimaryReturn(context.library, fn.returnValue);
     const primary = isPrimaryOmitted ? undefined : fn.returnValue.doc;
 
     if (outs.length === 0) {
@@ -92,7 +92,11 @@ const callableSpec = (context: ModuleContext, callable: GirFunction, options: Ca
         (parameter) => options.finishFn !== undefined && isCallbackParameter(context, parameter),
         options.renames,
     ),
-    returns: returnsText(context, options.finishFn ?? callable),
+    returns: returnsText(
+        context,
+        options.finishFn ?? callable,
+        options.finishFn !== undefined && shouldTrimFinishBoolean(context, options.finishFn),
+    ),
     throws: canCallableThrow(callable, options.finishFn) ? THROWS_TEXT : undefined,
 });
 

package/src/store/gi/callables.ts

@@ -358,7 +358,7 @@ const renderPromisifiedCallable = (
     const body = renderPromisifiedBody(
         context,
         callable,
-        finishCallExpression(callable, finishFn, member.ownerName),
+        { fn: finishFn, expression: finishCallExpression(callable, finishFn, member.ownerName) },
         toCamelIdentifier(cIdentifier),
     );
 

package/src/store/gi/class.ts

@@ -247,6 +247,35 @@ const appendClassRegistrations = (context: ModuleContext, klass: GirClass, class
         gtypeExpr,
         vfuncs: renderVfuncMetadata(context, klass),
     });
+
+    appendClassStructRegistration(context, klass, className, gtypeExpr);
+};
+
+const appendClassStructRegistration = (
+    context: ModuleContext,
+    klass: GirClass,
+    className: string,
+    gtypeExpr: string | undefined,
+): void => {
+    const typeStruct = klass.glibTypeStruct;
+
+    if (gtypeExpr === undefined || typeStruct === undefined) {
+        return;
+    }
+
+    const resolved = context.library.resolveType(context.namespace.name, typeStruct);
+
+    if (resolved?.kind !== "record" || !isEmittableEntity(resolved.value)) {
+        return;
+    }
+
+    const structName = sanitizeTypeIdentifier(resolved.value.name);
+    context.addRuntimeImport("registerClassStruct");
+
+    context.module.appendRegistration(`registerClassStruct(${className}, ${structName});`, [
+        className,
+        structName,
+    ]);
 };
 
 const addAncestorInterfaceKeys = (context: ModuleContext, ancestor: ResolvedAncestor, keys: Set<string>): void => {

package/src/store/gi/constructor-props.ts

@@ -76,7 +76,7 @@ const renderRootConstructor = (context: ModuleContext): string => {
     context.addRuntimeTypeImport("AnyClass");
     context.addRuntimeImport("getClassType");
     context.addRuntimeImport("newObjectWithProperties");
-    const body = "newObjectWithProperties(getClassType(this.constructor as AnyClass), props, this);";
+    const body = "return newObjectWithProperties(getClassType(this.constructor as AnyClass), props, this);";
 
     return renderBlock("constructor(props: object = {})", body);
 };

package/src/store/gi/function.ts

@@ -48,6 +48,7 @@ const renderFnExpression = (context: ModuleContext, fn: GirFunction): string | u
         args: arrayLiteral(params),
         returns: returnPlan.descriptor,
         isReturnSkipped: returnPlan.isSkipped,
+        isReturnUnpacked: returnPlan.isUnpacked,
         canThrow: fn.throws,
     });
 };
@@ -132,7 +133,7 @@ const matchNamespaceFinish = (context: ModuleContext, fn: GirFunction): Namespac
 const renderPromisifiedNamespaceFunction = (options: NamespaceFunctionOptions, finish: NamespaceFinish): string => {
     const { context, fn, exportName, bindingName } = options;
     const { signature, returnType } = renderPromisifiedSignature(context, fn, finish.fn);
-    const body = renderPromisifiedBody(context, fn, finish.exportName, bindingName);
+    const body = renderPromisifiedBody(context, fn, { fn: finish.fn, expression: finish.exportName }, bindingName);
 
     return renderBlock(`export function ${exportName}(${signature}): ${returnType}`, body);
 };

package/src/store/gi/generated-libraries.ts

@@ -0,0 +1,91 @@
+import { sortStrings } from "@gtkx/utils";
+import { join } from "node:path";
+import type { GirNamespace } from "../../gir/namespace.js";
+import { arrayGuard, hasFields, isString, recordGuard } from "../../guards.js";
+import { readJsonFile } from "../../json.js";
+
+/** What a generated `@gtkx/gi` store binds, and the library releases it was generated against. */
+type GeneratedLibraries = {
+    /** GIR identifiers the store binds, such as `Gtk-4.0`, expanded from the project's `libraries`. */
+    libraries: string[];
+    /**
+     * `MAJOR.MINOR` release, keyed by GIR identifier. A library whose GIR declares no `MAJOR_VERSION`
+     * and `MINOR_VERSION` is absent, so an entry is present only for those that name their release.
+     */
+    versions: Record<string, string>;
+};
+
+const LIBRARIES_FILENAME = "libraries.json";
+const MAJOR_CONSTANT = "MAJOR_VERSION";
+const MINOR_CONSTANT = "MINOR_VERSION";
+const DIGITS = /^\d+$/;
+
+const constantValue = (namespace: GirNamespace, name: string): string | undefined => {
+    const constant = namespace.constants.find((entry) => entry.name === name);
+
+    return constant !== undefined && DIGITS.test(constant.value) ? constant.value : undefined;
+};
+
+const namespaceVersion = (namespace: GirNamespace): string | undefined => {
+    const major = constantValue(namespace, MAJOR_CONSTANT);
+    const minor = constantValue(namespace, MINOR_CONSTANT);
+
+    return major === undefined || minor === undefined ? undefined : `${major}.${minor}`;
+};
+
+const getNamespaceName = (library: string): string => {
+    const separator = library.indexOf("-");
+
+    return separator === -1 ? library : library.slice(0, separator);
+};
+
+const collectGeneratedLibraries = (
+    namespaces: Map<string, GirNamespace>,
+    libraries: string[],
+): GeneratedLibraries => {
+    const sorted = sortStrings(libraries);
+    const versions: Record<string, string> = {};
+
+    for (const library of sorted) {
+        const namespace = namespaces.get(getNamespaceName(library));
+        const version = namespace === undefined ? undefined : namespaceVersion(namespace);
+
+        if (version !== undefined) {
+            versions[library] = version;
+        }
+    }
+
+    return { libraries: sorted, versions };
+};
+
+const renderGeneratedLibraries = (generated: GeneratedLibraries): string =>
+    `${JSON.stringify(generated, null, 2)}\n`;
+
+const isGeneratedLibraries = (value: unknown): value is GeneratedLibraries =>
+    hasFields<GeneratedLibraries>(value, {
+        libraries: arrayGuard(isString),
+        versions: recordGuard(isString),
+    });
+
+/**
+ * Reads which GIR libraries a generated `@gtkx/gi` store binds and which release of each its GIR declared,
+ * out of the inventory codegen writes into the store. Answers "what does this project bind, and how new does
+ * the installed library have to be" without parsing a `.gir` file or querying pkg-config.
+ *
+ * @param giStoreDir The gi store directory, as given by `resolveStore(projectRoot).gi.storeDir`.
+ * @returns What the store recorded, or null when it holds no inventory codegen wrote, which covers an absent,
+ * unreadable, unparseable and structurally foreign store file alike.
+ */
+const readGeneratedLibraries = (giStoreDir: string): GeneratedLibraries | null => {
+    const parsed = readJsonFile(join(giStoreDir, LIBRARIES_FILENAME));
+
+    return isGeneratedLibraries(parsed) ? parsed : null;
+};
+
+export {
+    LIBRARIES_FILENAME,
+    collectGeneratedLibraries,
+    type GeneratedLibraries,
+    readGeneratedLibraries,
+    renderGeneratedLibraries,
+};