@gtkx/gir 0.9.0 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/gir",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "GObject Introspection file parser for GTKX",
   "keywords": [
     "gtk",

package/src/doc-sanitizer.ts

@@ -0,0 +1,370 @@
+type GirLinkType =
+    | "class"
+    | "iface"
+    | "struct"
+    | "enum"
+    | "flags"
+    | "error"
+    | "callback"
+    | "method"
+    | "vfunc"
+    | "func"
+    | "ctor"
+    | "property"
+    | "signal"
+    | "const"
+    | "type"
+    | "id";
+
+interface GirLink {
+    type: GirLinkType;
+    namespace: string | undefined;
+    target: string;
+    member: string | undefined;
+}
+
+const GIR_LINK_PATTERN = /\[([a-z]+)@([^\]]+)\]/gi;
+
+function parseGirLink(type: string, reference: string): GirLink | undefined {
+    const linkType = type.toLowerCase() as GirLinkType;
+
+    const validTypes: GirLinkType[] = [
+        "class",
+        "iface",
+        "struct",
+        "enum",
+        "flags",
+        "error",
+        "callback",
+        "method",
+        "vfunc",
+        "func",
+        "ctor",
+        "property",
+        "signal",
+        "const",
+        "type",
+        "id",
+    ];
+
+    if (!validTypes.includes(linkType)) {
+        return undefined;
+    }
+
+    const parts = reference.split(".");
+    if (parts.length === 0) {
+        return undefined;
+    }
+
+    if (linkType === "property" || linkType === "signal") {
+        const colonIndex = reference.indexOf(":");
+        if (colonIndex !== -1) {
+            const beforeColon = reference.substring(0, colonIndex);
+            const afterColon = reference.substring(colonIndex + 1);
+            const beforeParts = beforeColon.split(".");
+            if (beforeParts.length >= 2) {
+                return {
+                    type: linkType,
+                    namespace: beforeParts[0],
+                    target: beforeParts.slice(1).join("."),
+                    member: afterColon.replace("::", ""),
+                };
+            }
+            return {
+                type: linkType,
+                namespace: undefined,
+                target: beforeColon,
+                member: afterColon.replace("::", ""),
+            };
+        }
+    }
+
+    if (parts.length === 1) {
+        return {
+            type: linkType,
+            namespace: undefined,
+            target: parts[0] ?? "",
+            member: undefined,
+        };
+    }
+
+    if (parts.length === 2) {
+        const first = parts[0] ?? "";
+        const second = parts[1] ?? "";
+        const isNamespace = first.length > 0 && first[0] === first[0]?.toUpperCase();
+
+        if (linkType === "func" || linkType === "const") {
+            return {
+                type: linkType,
+                namespace: first,
+                target: second,
+                member: undefined,
+            };
+        }
+
+        if (isNamespace) {
+            return {
+                type: linkType,
+                namespace: first,
+                target: second,
+                member: undefined,
+            };
+        }
+
+        return {
+            type: linkType,
+            namespace: undefined,
+            target: first,
+            member: second,
+        };
+    }
+
+    return {
+        type: linkType,
+        namespace: parts[0],
+        target: parts[1] ?? "",
+        member: parts.slice(2).join(".") || undefined,
+    };
+}
+
+function formatGirLinkForTsDoc(link: GirLink): string {
+    let displayText: string;
+    if (link.member) {
+        displayText = `${link.target}.${link.member}`;
+    } else {
+        displayText = link.target;
+    }
+
+    const linkTarget = link.namespace ? `${link.namespace}.${displayText}` : displayText;
+
+    switch (link.type) {
+        case "class":
+        case "iface":
+        case "struct":
+        case "enum":
+        case "flags":
+        case "error":
+        case "callback":
+        case "type":
+            return `{@link ${linkTarget}}`;
+
+        case "method":
+        case "vfunc":
+        case "func":
+        case "ctor":
+            return `{@link ${linkTarget}}`;
+
+        case "property":
+            return `{@link ${linkTarget}}`;
+
+        case "signal":
+            return `{@link ${linkTarget}}`;
+
+        case "const":
+            return `{@link ${linkTarget}}`;
+
+        case "id":
+            return `\`${link.target}\``;
+
+        default:
+            return `\`${displayText}\``;
+    }
+}
+
+function convertGirLinks(text: string): string {
+    return text.replace(GIR_LINK_PATTERN, (_, type: string, reference: string) => {
+        const link = parseGirLink(type, reference);
+        if (!link) {
+            return `\`${reference}\``;
+        }
+        return formatGirLinkForTsDoc(link);
+    });
+}
+
+const NAMESPACE_TO_DOCS_PATH: Record<string, string> = {
+    Gtk: "gtk4",
+    Gdk: "gdk4",
+    Gsk: "gsk4",
+    Adw: "adw1",
+    GLib: "glib",
+    GObject: "gobject",
+    Gio: "gio",
+    Pango: "Pango",
+    PangoCairo: "PangoCairo",
+    GdkPixbuf: "gdk-pixbuf",
+    Cairo: "cairo",
+};
+
+function getDocsBaseUrl(namespace: string | undefined): string {
+    if (!namespace) {
+        return "https://docs.gtk.org/gtk4";
+    }
+    const docsPath = NAMESPACE_TO_DOCS_PATH[namespace];
+    if (docsPath) {
+        return `https://docs.gtk.org/${docsPath}`;
+    }
+    return `https://docs.gtk.org/${namespace.toLowerCase()}`;
+}
+
+function convertHtmlImageElements(text: string, baseUrl: string): string {
+    let result = text;
+
+    result = result.replace(/<picture[^>]*>([\s\S]*?)<\/picture>/gi, (_, pictureContent: string) => {
+        const imgMatch = /<img[^>]*alt="([^"]*)"[^>]*src="([^"]*)"[^>]*\/?>/i.exec(pictureContent);
+        if (!imgMatch) {
+            const imgMatch2 = /<img[^>]*src="([^"]*)"[^>]*alt="([^"]*)"[^>]*\/?>/i.exec(pictureContent);
+            if (imgMatch2) {
+                const src = imgMatch2[1];
+                const alt = imgMatch2[2];
+                return `![${alt}](${baseUrl}/${src})`;
+            }
+            return "";
+        }
+        const alt = imgMatch[1];
+        const src = imgMatch[2];
+        return `![${alt}](${baseUrl}/${src})`;
+    });
+
+    result = result.replace(/<img[^>]*alt="([^"]*)"[^>]*src="([^"]*)"[^>]*\/?>/gi, (_, alt: string, src: string) => {
+        if (src.startsWith("http://") || src.startsWith("https://")) {
+            return `![${alt}](${src})`;
+        }
+        return `![${alt}](${baseUrl}/${src})`;
+    });
+
+    result = result.replace(/<img[^>]*src="([^"]*)"[^>]*alt="([^"]*)"[^>]*\/?>/gi, (_, src: string, alt: string) => {
+        if (src.startsWith("http://") || src.startsWith("https://")) {
+            return `![${alt}](${src})`;
+        }
+        return `![${alt}](${baseUrl}/${src})`;
+    });
+
+    result = result.replace(/<img[^>]*src="([^"]*)"[^>]*\/?>/gi, (_, src: string) => {
+        if (src.startsWith("http://") || src.startsWith("https://")) {
+            return `![](${src})`;
+        }
+        return `![](${baseUrl}/${src})`;
+    });
+
+    result = result.replace(/<source[^>]*\/?>/gi, "");
+
+    return result;
+}
+
+function convertMarkdownImageUrls(text: string, baseUrl: string): string {
+    return text.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (match, alt: string, src: string) => {
+        if (src.startsWith("http://") || src.startsWith("https://")) {
+            return match;
+        }
+        return `![${alt}](${baseUrl}/${src})`;
+    });
+}
+
+function convertKbdElements(text: string): string {
+    return text.replace(/<kbd>([^<]*)<\/kbd>/gi, "`$1`");
+}
+
+function stripHtmlLinks(text: string): string {
+    return text.replace(/\[([^\]]+)\]\([^)]+\.html[^)]*\)/gi, "$1");
+}
+
+function convertAtAnnotations(text: string): string {
+    return text.replace(/(?<!\{)@([a-zA-Z_][a-zA-Z0-9_]*)\b(?!\s*\{)/g, "`$1`");
+}
+
+function escapeXmlStyleTags(text: string): string {
+    return text.replace(/<(\/?)(child|object|property|signal|template|style|item|attribute)>/gi, "`<$1$2>`");
+}
+
+function cleanupWhitespace(text: string): string {
+    let result = text.replace(/\n{3,}/g, "\n\n");
+    result = result.replace(/[ \t]+$/gm, "");
+    return result.trim();
+}
+
+export interface SanitizeDocOptions {
+    escapeXmlTags?: boolean;
+    namespace?: string;
+}
+
+export function sanitizeDoc(doc: string, options: SanitizeDocOptions = {}): string {
+    let result = doc;
+
+    const baseUrl = getDocsBaseUrl(options.namespace);
+    result = convertHtmlImageElements(result, baseUrl);
+    result = convertMarkdownImageUrls(result, baseUrl);
+    result = convertKbdElements(result);
+    result = stripHtmlLinks(result);
+    result = convertGirLinks(result);
+    result = convertAtAnnotations(result);
+
+    if (options.escapeXmlTags) {
+        result = escapeXmlStyleTags(result);
+    }
+
+    result = cleanupWhitespace(result);
+
+    return result;
+}
+
+export function formatDoc(doc: string | undefined, indent: string = "", options: SanitizeDocOptions = {}): string {
+    if (!doc) {
+        return "";
+    }
+
+    const sanitized = sanitizeDoc(doc, options);
+    if (!sanitized) {
+        return "";
+    }
+
+    const lines = sanitized.split("\n").map((line) => line.trim());
+    const firstLine = lines[0] ?? "";
+
+    if (lines.length === 1 && firstLine.length < 80) {
+        return `${indent}/** ${firstLine} */\n`;
+    }
+
+    const formattedLines = lines.map((line) => `${indent} * ${line}`);
+    return `${indent}/**\n${formattedLines.join("\n")}\n${indent} */\n`;
+}
+
+interface DocParameter {
+    name: string;
+    doc: string | undefined;
+}
+
+export function formatMethodDoc(
+    doc: string | undefined,
+    params: DocParameter[],
+    indent: string = "  ",
+    options: SanitizeDocOptions = {},
+): string {
+    const sanitizedDoc = doc ? sanitizeDoc(doc, options) : undefined;
+
+    const hasDocumentation = sanitizedDoc || params.some((p) => p.doc);
+    if (!hasDocumentation) {
+        return "";
+    }
+
+    const lines: string[] = [];
+
+    if (sanitizedDoc) {
+        for (const line of sanitizedDoc.split("\n")) {
+            lines.push(` * ${line.trim()}`);
+        }
+    }
+
+    for (const param of params) {
+        if (param.doc && param.name && param.name !== "..." && param.name !== "") {
+            const sanitizedParamDoc = sanitizeDoc(param.doc, options);
+            const paramDocFirstLine = sanitizedParamDoc.split("\n")[0]?.trim() ?? "";
+            lines.push(` * @param ${param.name} - ${paramDocFirstLine}`);
+        }
+    }
+
+    if (lines.length === 0) {
+        return "";
+    }
+
+    return `${indent}/**\n${indent}${lines.join(`\n${indent}`)}\n${indent} */\n`;
+}

package/src/index.ts

@@ -1,2 +1,3 @@
+export * from "./doc-sanitizer.js";
 export * from "./parser.js";
 export * from "./types.js";

package/src/parser.ts

@@ -186,18 +186,22 @@ export class GirParser {
         }
         return methods
             .filter((method) => method["@_introspectable"] !== "0")
-            .map((method) => ({
-                name: String(method["@_name"] ?? ""),
-                cIdentifier: String(method["@_c:identifier"] ?? ""),
-                returnType: this.parseReturnType(method["return-value"] as Record<string, unknown> | undefined),
-                parameters: this.parseParameters(
-                    (method.parameters && typeof method.parameters === "object" && method.parameters !== null
-                        ? method.parameters
-                        : {}) as Record<string, unknown>,
-                ),
-                throws: method["@_throws"] === "1",
-                doc: extractDoc(method),
-            }));
+            .map((method) => {
+                const returnValue = method["return-value"] as Record<string, unknown> | undefined;
+                return {
+                    name: String(method["@_name"] ?? ""),
+                    cIdentifier: String(method["@_c:identifier"] ?? ""),
+                    returnType: this.parseReturnType(returnValue),
+                    parameters: this.parseParameters(
+                        (method.parameters && typeof method.parameters === "object" && method.parameters !== null
+                            ? method.parameters
+                            : {}) as Record<string, unknown>,
+                    ),
+                    throws: method["@_throws"] === "1",
+                    doc: extractDoc(method),
+                    returnDoc: returnValue ? extractDoc(returnValue) : undefined,
+                };
+            });
     }
 
     private parseConstructors(constructors: Record<string, unknown>[]): GirConstructor[] {
@@ -206,18 +210,22 @@ export class GirParser {
         }
         return constructors
             .filter((ctor) => ctor["@_introspectable"] !== "0")
-            .map((ctor) => ({
-                name: String(ctor["@_name"] ?? ""),
-                cIdentifier: String(ctor["@_c:identifier"] ?? ""),
-                returnType: this.parseReturnType(ctor["return-value"] as Record<string, unknown> | undefined),
-                parameters: this.parseParameters(
-                    (ctor.parameters && typeof ctor.parameters === "object" && ctor.parameters !== null
-                        ? ctor.parameters
-                        : {}) as Record<string, unknown>,
-                ),
-                throws: ctor["@_throws"] === "1",
-                doc: extractDoc(ctor),
-            }));
+            .map((ctor) => {
+                const returnValue = ctor["return-value"] as Record<string, unknown> | undefined;
+                return {
+                    name: String(ctor["@_name"] ?? ""),
+                    cIdentifier: String(ctor["@_c:identifier"] ?? ""),
+                    returnType: this.parseReturnType(returnValue),
+                    parameters: this.parseParameters(
+                        (ctor.parameters && typeof ctor.parameters === "object" && ctor.parameters !== null
+                            ? ctor.parameters
+                            : {}) as Record<string, unknown>,
+                    ),
+                    throws: ctor["@_throws"] === "1",
+                    doc: extractDoc(ctor),
+                    returnDoc: returnValue ? extractDoc(returnValue) : undefined,
+                };
+            });
     }
 
     private parseFunctions(functions: Record<string, unknown>[]): GirFunction[] {
@@ -226,18 +234,22 @@ export class GirParser {
         }
         return functions
             .filter((func) => func["@_introspectable"] !== "0")
-            .map((func) => ({
-                name: String(func["@_name"] ?? ""),
-                cIdentifier: String(func["@_c:identifier"] ?? ""),
-                returnType: this.parseReturnType(func["return-value"] as Record<string, unknown> | undefined),
-                parameters: this.parseParameters(
-                    (func.parameters && typeof func.parameters === "object" && func.parameters !== null
-                        ? func.parameters
-                        : {}) as Record<string, unknown>,
-                ),
-                throws: func["@_throws"] === "1",
-                doc: extractDoc(func),
-            }));
+            .map((func) => {
+                const returnValue = func["return-value"] as Record<string, unknown> | undefined;
+                return {
+                    name: String(func["@_name"] ?? ""),
+                    cIdentifier: String(func["@_c:identifier"] ?? ""),
+                    returnType: this.parseReturnType(returnValue),
+                    parameters: this.parseParameters(
+                        (func.parameters && typeof func.parameters === "object" && func.parameters !== null
+                            ? func.parameters
+                            : {}) as Record<string, unknown>,
+                    ),
+                    throws: func["@_throws"] === "1",
+                    doc: extractDoc(func),
+                    returnDoc: returnValue ? extractDoc(returnValue) : undefined,
+                };
+            });
     }
 
     private parseParameters(parametersNode: Record<string, unknown>): GirParameter[] {

package/src/types.ts

@@ -178,6 +178,8 @@ export type GirMethod = {
     throws?: boolean;
     /** Documentation for the method. */
     doc?: string;
+    /** Documentation for the return value. */
+    returnDoc?: string;
 };
 
 /**
@@ -196,6 +198,8 @@ export type GirConstructor = {
     throws?: boolean;
     /** Documentation for the constructor. */
     doc?: string;
+    /** Documentation for the return value. */
+    returnDoc?: string;
 };
 
 /**
@@ -214,6 +218,8 @@ export type GirFunction = {
     throws?: boolean;
     /** Documentation for the function. */
     doc?: string;
+    /** Documentation for the return value. */
+    returnDoc?: string;
 };
 
 /**
@@ -344,6 +350,10 @@ export type FfiTypeDescriptor = {
     borrowed?: boolean;
     /** Inner type for ref types (as descriptor) or boxed types (as GLib type name string). */
     innerType?: FfiTypeDescriptor | string;
+    /** Library name for boxed types that need dynamic type lookup. */
+    lib?: string;
+    /** Explicit get_type function name for boxed types (when naive transformation doesn't work). */
+    getTypeFn?: string;
     /** Item type for array types. */
     itemType?: FfiTypeDescriptor;
     /** List type for arrays (glist, gslist) - indicates native GList/GSList iteration. */
@@ -414,6 +424,8 @@ export type RegisteredType = {
     namespace: string;
     transformedName: string;
     glibTypeName?: string;
+    sharedLibrary?: string;
+    glibGetType?: string;
 };
 
 const CLASS_RENAMES = new Map<string, string>([["Error", "GError"]]);
@@ -441,7 +453,7 @@ export class TypeRegistry {
      * @param namespace - The namespace containing the class
      * @param name - The class name
      */
-    registerType(namespace: string, name: string): void {
+    registerNativeClass(namespace: string, name: string): void {
         const transformedName = normalizeTypeName(name, namespace);
         this.types.set(`${namespace}.${name}`, {
             kind: "class",
@@ -486,8 +498,16 @@ export class TypeRegistry {
      * @param namespace - The namespace containing the record
      * @param name - The record name
      * @param glibTypeName - Optional GLib type name for boxed type handling
+     * @param sharedLibrary - The shared library containing this record's type
+     * @param glibGetType - The GLib get_type function name
      */
-    registerRecord(namespace: string, name: string, glibTypeName?: string): void {
+    registerRecord(
+        namespace: string,
+        name: string,
+        glibTypeName?: string,
+        sharedLibrary?: string,
+        glibGetType?: string,
+    ): void {
         const transformedName = normalizeTypeName(name, namespace);
         this.types.set(`${namespace}.${name}`, {
             kind: "record",
@@ -495,6 +515,8 @@ export class TypeRegistry {
             namespace,
             transformedName,
             glibTypeName,
+            sharedLibrary,
+            glibGetType,
         });
     }
 
@@ -557,7 +579,7 @@ export class TypeRegistry {
         const registry = new TypeRegistry();
         for (const ns of namespaces) {
             for (const cls of ns.classes) {
-                registry.registerType(ns.name, cls.name);
+                registry.registerNativeClass(ns.name, cls.name);
             }
             for (const iface of ns.interfaces) {
                 registry.registerInterface(ns.name, iface.name);
@@ -570,7 +592,13 @@ export class TypeRegistry {
             }
             for (const record of ns.records) {
                 if (record.glibTypeName && !record.disguised) {
-                    registry.registerRecord(ns.name, record.name, record.glibTypeName);
+                    registry.registerRecord(
+                        ns.name,
+                        record.name,
+                        record.glibTypeName,
+                        ns.sharedLibrary,
+                        record.glibGetType,
+                    );
                 }
             }
             for (const callback of ns.callbacks) {
@@ -934,6 +962,8 @@ export class TypeMapper {
                             type: "boxed",
                             borrowed: isReturn,
                             innerType: registered.glibTypeName ?? registered.transformedName,
+                            lib: registered.sharedLibrary,
+                            getTypeFn: registered.glibGetType,
                         },
                         externalType,
                         kind: registered.kind,
@@ -1023,6 +1053,8 @@ export class TypeMapper {
                                 type: "boxed",
                                 borrowed: isReturn,
                                 innerType: registered.glibTypeName ?? registered.transformedName,
+                                lib: registered.sharedLibrary,
+                                getTypeFn: registered.glibGetType,
                             },
                             externalType: isExternal ? externalType : undefined,
                         };
@@ -1081,6 +1113,8 @@ export class TypeMapper {
                             type: "boxed",
                             borrowed: isReturn,
                             innerType: registered.glibTypeName ?? registered.transformedName,
+                            lib: registered.sharedLibrary,
+                            getTypeFn: registered.glibGetType,
                         },
                         externalType,
                         kind: registered.kind,
@@ -1182,20 +1216,26 @@ export class TypeMapper {
 
         if (param.type.name === "Gtk.DrawingAreaDrawFunc" || param.type.name === "DrawingAreaDrawFunc") {
             this.onExternalTypeUsed?.({
-                namespace: "Cairo",
+                namespace: "cairo",
                 name: "Context",
                 transformedName: "Context",
                 kind: "record",
             });
             this.onSameNamespaceClassUsed?.("DrawingArea", "DrawingArea");
             return {
-                ts: "(self: DrawingArea, cr: Cairo.Context, width: number, height: number) => void",
+                ts: "(self: DrawingArea, cr: cairo.Context, width: number, height: number) => void",
                 ffi: {
                     type: "callback",
                     trampoline: "drawFunc",
                     argTypes: [
                         { type: "gobject", borrowed: true },
-                        { type: "boxed", borrowed: true, innerType: "CairoContext" },
+                        {
+                            type: "boxed",
+                            borrowed: true,
+                            innerType: "CairoContext",
+                            lib: "libcairo-gobject.so.2",
+                            getTypeFn: "cairo_gobject_context_get_type",
+                        },
                         { type: "int", size: 32, unsigned: false },
                         { type: "int", size: 32, unsigned: false },
                     ],