@gtkx/gir 0.9.2 → 0.9.4

package/package.json

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

package/src/doc-sanitizer.ts

@@ -127,7 +127,12 @@ function parseGirLink(type: string, reference: string): GirLink | undefined {
     };
 }
 
-function formatGirLinkForTsDoc(link: GirLink): string {
+interface LinkFormatOptions {
+    linkStyle: "namespaced" | "prefixed";
+    currentNamespace: string | undefined;
+}
+
+function formatGirLinkForTsDoc(link: GirLink, options: LinkFormatOptions): string {
     let displayText: string;
     if (link.member) {
         displayText = `${link.target}.${link.member}`;
@@ -135,7 +140,17 @@ function formatGirLinkForTsDoc(link: GirLink): string {
         displayText = link.target;
     }
 
-    const linkTarget = link.namespace ? `${link.namespace}.${displayText}` : displayText;
+    let linkTarget: string;
+    if (options.linkStyle === "prefixed") {
+        const effectiveNamespace = link.namespace ?? options.currentNamespace;
+        if (effectiveNamespace && effectiveNamespace !== "Gtk") {
+            linkTarget = `${effectiveNamespace}${displayText}`;
+        } else {
+            linkTarget = displayText;
+        }
+    } else {
+        linkTarget = link.namespace ? `${link.namespace}.${displayText}` : displayText;
+    }
 
     switch (link.type) {
         case "class":
@@ -171,37 +186,37 @@ function formatGirLinkForTsDoc(link: GirLink): string {
     }
 }
 
-function convertGirLinks(text: string): string {
+function convertGirLinks(text: string, options: LinkFormatOptions): string {
     return text.replace(GIR_LINK_PATTERN, (_, type: string, reference: string) => {
         const link = parseGirLink(type, reference);
         if (!link) {
             return `\`${reference}\``;
         }
-        return formatGirLinkForTsDoc(link);
+        return formatGirLinkForTsDoc(link, options);
     });
 }
 
-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",
+const GTK_DOCS_BASE_URLS: Record<string, string> = {
+    Gtk: "https://docs.gtk.org/gtk4",
+    Gdk: "https://docs.gtk.org/gdk4",
+    Gsk: "https://docs.gtk.org/gsk4",
+    GLib: "https://docs.gtk.org/glib",
+    GObject: "https://docs.gtk.org/gobject",
+    Gio: "https://docs.gtk.org/gio",
+    Pango: "https://docs.gtk.org/Pango",
+    PangoCairo: "https://docs.gtk.org/PangoCairo",
+    GdkPixbuf: "https://docs.gtk.org/gdk-pixbuf",
+    Cairo: "https://docs.gtk.org/cairo",
+    Adw: "https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest",
 };
 
 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}`;
+    const baseUrl = GTK_DOCS_BASE_URLS[namespace];
+    if (baseUrl) {
+        return baseUrl;
     }
     return `https://docs.gtk.org/${namespace.toLowerCase()}`;
 }
@@ -273,7 +288,21 @@ function convertAtAnnotations(text: string): string {
 }
 
 function escapeXmlStyleTags(text: string): string {
-    return text.replace(/<(\/?)(child|object|property|signal|template|style|item|attribute)>/gi, "`<$1$2>`");
+    const codeBlockPattern = /```[\s\S]*?```/g;
+    const codeBlocks: string[] = [];
+
+    let processed = text.replace(codeBlockPattern, (match) => {
+        codeBlocks.push(match);
+        return `__CODE_BLOCK_${codeBlocks.length - 1}__`;
+    });
+
+    processed = processed.replace(/<(\/?)(child|object|property|signal|template|style|item|attribute)>/gi, "`<$1$2>`");
+
+    for (let i = 0; i < codeBlocks.length; i++) {
+        processed = processed.replace(`__CODE_BLOCK_${i}__`, codeBlocks[i] ?? "");
+    }
+
+    return processed;
 }
 
 function cleanupWhitespace(text: string): string {
@@ -282,9 +311,44 @@ function cleanupWhitespace(text: string): string {
     return result.trim();
 }
 
+interface CodeBlockProtection {
+    text: string;
+    restore: (formatted: string, linePrefix: string) => string;
+}
+
+function protectCodeBlocks(text: string): CodeBlockProtection {
+    const codeBlockPattern = /```[\s\S]*?```/g;
+    const codeBlocks: string[] = [];
+
+    const processed = text.replace(codeBlockPattern, (match) => {
+        codeBlocks.push(match);
+        return `__PROTECTED_CODE_BLOCK_${codeBlocks.length - 1}__`;
+    });
+
+    const restore = (formatted: string, linePrefix: string): string => {
+        let result = formatted;
+        for (let i = 0; i < codeBlocks.length; i++) {
+            const placeholder = `__PROTECTED_CODE_BLOCK_${i}__`;
+            const codeBlock = codeBlocks[i];
+            if (codeBlock === undefined) continue;
+
+            const codeLines = codeBlock.split("\n");
+            const prefixedCodeLines = codeLines.map((line, index) => {
+                if (index === 0) return line;
+                return `${linePrefix}${line}`;
+            });
+            result = result.replace(placeholder, prefixedCodeLines.join("\n"));
+        }
+        return result;
+    };
+
+    return { text: processed, restore };
+}
+
 export interface SanitizeDocOptions {
     escapeXmlTags?: boolean;
     namespace?: string;
+    linkStyle?: "namespaced" | "prefixed";
 }
 
 export function sanitizeDoc(doc: string, options: SanitizeDocOptions = {}): string {
@@ -295,7 +359,12 @@ export function sanitizeDoc(doc: string, options: SanitizeDocOptions = {}): stri
     result = convertMarkdownImageUrls(result, baseUrl);
     result = convertKbdElements(result);
     result = stripHtmlLinks(result);
-    result = convertGirLinks(result);
+
+    const linkFormatOptions: LinkFormatOptions = {
+        linkStyle: options.linkStyle ?? "namespaced",
+        currentNamespace: options.namespace,
+    };
+    result = convertGirLinks(result, linkFormatOptions);
     result = convertAtAnnotations(result);
 
     if (options.escapeXmlTags) {
@@ -317,15 +386,19 @@ export function formatDoc(doc: string | undefined, indent: string = "", options:
         return "";
     }
 
-    const lines = sanitized.split("\n").map((line) => line.trim());
+    const { text: protectedText, restore } = protectCodeBlocks(sanitized);
+
+    const lines = protectedText.split("\n").map((line) => line.trim());
     const firstLine = lines[0] ?? "";
 
     if (lines.length === 1 && firstLine.length < 80) {
-        return `${indent}/** ${firstLine} */\n`;
+        const result = `${indent}/** ${firstLine} */\n`;
+        return restore(result, `${indent} * `);
     }
 
     const formattedLines = lines.map((line) => `${indent} * ${line}`);
-    return `${indent}/**\n${formattedLines.join("\n")}\n${indent} */\n`;
+    const result = `${indent}/**\n${formattedLines.join("\n")}\n${indent} */\n`;
+    return restore(result, `${indent} * `);
 }
 
 interface DocParameter {
@@ -347,9 +420,11 @@ export function formatMethodDoc(
     }
 
     const lines: string[] = [];
+    let protection: CodeBlockProtection | undefined;
 
     if (sanitizedDoc) {
-        for (const line of sanitizedDoc.split("\n")) {
+        protection = protectCodeBlocks(sanitizedDoc);
+        for (const line of protection.text.split("\n")) {
             lines.push(` * ${line.trim()}`);
         }
     }
@@ -366,5 +441,6 @@ export function formatMethodDoc(
         return "";
     }
 
-    return `${indent}/**\n${indent}${lines.join(`\n${indent}`)}\n${indent} */\n`;
+    const result = `${indent}/**\n${indent}${lines.join(`\n${indent}`)}\n${indent} */\n`;
+    return protection ? protection.restore(result, `${indent} * `) : result;
 }