@gtkx/codegen 1.0.0-rc.4 → 1.1.0

package/src/store/store-fs.ts

@@ -1,5 +1,17 @@
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { errorMessage } from "@gtkx/utils";
+import {
+    chmodSync,
+    existsSync,
+    mkdirSync,
+    realpathSync,
+    renameSync,
+    rmSync,
+    symlinkSync,
+    writeFileSync,
+} from "node:fs";
 import { dirname, join, relative } from "node:path";
+import { keepFailedProject, type SourceModule } from "../compile.js";
+import { createStagingDir } from "../staging.js";
 import { compileStore } from "./compile-store.js";
 
 /** Where one generated store is written and how it is reached. */
@@ -12,10 +24,7 @@ type StoreOptions = {
     version: string;
 };
 
-type StoreFile = {
-    fileName: string;
-    source: string;
-};
+type StoreLink = Pick<StoreOptions, "storeDir" | "linkDir">;
 
 type Manifest = {
     name: string;
@@ -38,19 +47,25 @@ type RawFile = { relativePath: string; content: string };
 type WriteStoreParams = {
     storeDir: string;
     linkDir: string;
-    files: StoreFile[];
+    files: SourceModule[];
     manifest: Manifest;
     rawFiles?: RawFile[];
     requiresEnvReference?: boolean;
 };
 
 const STORE_DIR_MODE = 0o755;
+const FAILED_STORE_SUFFIX = ".failed";
 
 const subpathExport = (stem: string): { types: string; default: string } => ({
     types: `./${stem}.d.ts`,
     default: `./${stem}.js`,
 });
 
+const namespaceBarrel = (directory: string): { fileName: string; source: string } => ({
+    fileName: `${directory}/index.ts`,
+    source: `export * from "./${directory}.js";\n`,
+});
+
 const buildManifest = (input: ManifestInput): Manifest => {
     const manifest: Manifest = {
         name: input.name,
@@ -69,29 +84,36 @@ const buildManifest = (input: ManifestInput): Manifest => {
 
 const writeStore = (params: WriteStoreParams): void => {
     const tmp = createTempStore(params.storeDir);
+    const keepAt = `${params.storeDir}${FAILED_STORE_SUFFIX}`;
 
     try {
-        for (const file of params.files) {
-            writeSourceFile(tmp, file.fileName, file.source);
-        }
-
-        compileStore({
-            storeDir: tmp,
-            files: params.files,
-            packageName: params.manifest.name,
-            ...(params.requiresEnvReference !== undefined && { requiresEnvReference: params.requiresEnvReference }),
-        });
-
-        writePackageJson(tmp, params.manifest);
-        const rawFiles = params.rawFiles ?? [];
-
-        for (const raw of rawFiles) {
-            writeFileSync(join(tmp, raw.relativePath), raw.content);
-        }
-
-        swapStore(tmp, params.storeDir, params.linkDir);
-    } finally {
-        rmSync(tmp, { recursive: true, force: true });
+        buildTempStore(tmp, params);
+        swapStore(tmp, params.storeDir);
+        ensureStoreLink(params);
+    } catch (error) {
+        throw keepFailedProject({ projectDir: tmp, keepAt, error });
+    }
+
+    rmSync(keepAt, { recursive: true, force: true });
+};
+
+const buildTempStore = (tmp: string, params: WriteStoreParams): void => {
+    for (const file of params.files) {
+        writeSourceFile(tmp, file.fileName, file.source);
+    }
+
+    compileStore({
+        storeDir: tmp,
+        files: params.files,
+        packageName: params.manifest.name,
+        ...(params.requiresEnvReference !== undefined && { requiresEnvReference: params.requiresEnvReference }),
+    });
+
+    writePackageJson(tmp, params.manifest);
+    const rawFiles = params.rawFiles ?? [];
+
+    for (const raw of rawFiles) {
+        writeFileSync(join(tmp, raw.relativePath), raw.content);
     }
 };
 
@@ -111,7 +133,7 @@ const writePackageJson = (storeDir: string, manifest: Manifest): void => {
     writeFileSync(join(storeDir, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
 };
 
-const swapStore = (tmp: string, storeDir: string, visibleLink: string): void => {
+const swapStore = (tmp: string, storeDir: string): void => {
     const previous = `${storeDir}.old`;
     rmSync(previous, { recursive: true, force: true });
 
@@ -121,15 +143,46 @@ const swapStore = (tmp: string, storeDir: string, visibleLink: string): void =>
 
     renameSync(tmp, storeDir);
     rmSync(previous, { recursive: true, force: true });
-    symlinkRelative(visibleLink, storeDir);
 };
 
+const isStoreLinked = (link: StoreLink): boolean => {
+    try {
+        return realpathSync(link.linkDir) === realpathSync(link.storeDir);
+    } catch {
+        return false;
+    }
+};
+
+const ensureStoreLink = (link: StoreLink): void => {
+    if (!existsSync(join(link.storeDir, "package.json")) || isStoreLinked(link)) {
+        return;
+    }
+
+    symlinkRelative(link.linkDir, link.storeDir);
+};
+
+const storeWriteMessage = (storeDir: string, error: unknown): string =>
+    `Cannot write the generated store to ${storeDir}: ${errorMessage(error)}. ` +
+    "Codegen writes the store into the node_modules the @gtkx packages resolve from, " +
+    `so ${dirname(storeDir)} has to be writable.`;
+
 const createTempStore = (storeDir: string): string => {
-    mkdirSync(dirname(storeDir), { recursive: true });
-    const tmp = mkdtempSync(`${storeDir}.tmp-`);
-    chmodSync(tmp, STORE_DIR_MODE);
+    try {
+        const tmp = createStagingDir(storeDir);
+        chmodSync(tmp, STORE_DIR_MODE);
 
-    return tmp;
+        return tmp;
+    } catch (error) {
+        throw new Error(storeWriteMessage(storeDir, error), { cause: error });
+    }
 };
 
-export { subpathExport, buildManifest, writeStore, type StoreOptions, type RawFile };
+export {
+    subpathExport,
+    buildManifest,
+    ensureStoreLink,
+    namespaceBarrel,
+    writeStore,
+    type StoreOptions,
+    type RawFile,
+};

package/src/store/store-links.ts

@@ -0,0 +1,49 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { type ResolvedStore, resolveStore } from "./resolve-store.js";
+import { ensureStoreLink } from "./store-fs.js";
+
+const resolvedStores: Map<string, ResolvedStore> = new Map();
+
+const resolveStoreOrNull = (projectRoot: string): ResolvedStore | null => {
+    try {
+        return resolveStore(projectRoot);
+    } catch {
+        return null;
+    }
+};
+
+const isStoreDirPresent = (store: ResolvedStore): boolean => existsSync(join(store.gi.storeDir, "package.json"));
+
+const storeFor = (projectRoot: string): ResolvedStore | null => {
+    const cached = resolvedStores.get(projectRoot);
+
+    if (cached !== undefined && isStoreDirPresent(cached)) {
+        return cached;
+    }
+
+    const resolved = resolveStoreOrNull(projectRoot);
+    resolvedStores.delete(projectRoot);
+
+    if (resolved !== null) {
+        resolvedStores.set(projectRoot, resolved);
+    }
+
+    return resolved;
+};
+
+const ensureStoreLinks = (projectRoot: string): void => {
+    const store = storeFor(projectRoot);
+
+    if (store === null) {
+        return;
+    }
+
+    for (const unit of [store.gi, store.jsx]) {
+        if (unit !== null) {
+            ensureStoreLink(unit);
+        }
+    }
+};
+
+export { ensureStoreLinks };

package/src/writer/comparison-context.ts

@@ -0,0 +1,18 @@
+import { ModuleContext } from "./context.js";
+
+const COMPARISON_CONTEXTS: WeakMap<ModuleContext, ModuleContext> = new WeakMap();
+
+const comparisonContextFor = (context: ModuleContext): ModuleContext => {
+    const existing = COMPARISON_CONTEXTS.get(context);
+
+    if (existing !== undefined) {
+        return existing;
+    }
+
+    const created = new ModuleContext(context.namespace, context.library);
+    COMPARISON_CONTEXTS.set(context, created);
+
+    return created;
+};
+
+export { comparisonContextFor };

package/src/writer/context.ts

@@ -1,6 +1,6 @@
 import type { Library } from "../gir/library.js";
 import type { GirNamespace } from "../gir/namespace.js";
-import { ModuleBuilder } from "./module.js";
+import { type Declaration, ModuleBuilder } from "./module.js";
 
 class ModuleContext {
     public module: ModuleBuilder = new ModuleBuilder();
@@ -55,12 +55,22 @@ class ModuleContext {
         return namespaceName;
     }
 
-    qualify(namespaceName: string, typeName: string): string {
+    declare(declaration: Declaration): void {
+        const { name, code, owner } = declaration;
+
+        this.module.appendDeclaration({
+            name,
+            code,
+            owner: owner === undefined ? undefined : `${this.namespace.name}.${owner}`,
+        });
+    }
+
+    qualify(namespaceName: string, name: string): string {
         if (namespaceName === this.namespace.name) {
-            return typeName;
+            return name;
         }
 
-        return `${this.addCrossNamespaceImport(namespaceName)}.${typeName}`;
+        return `${this.addCrossNamespaceImport(namespaceName)}.${name}`;
     }
 }
 

package/src/writer/doc-tags.ts

@@ -0,0 +1,70 @@
+type JsDocParam = { name: string; doc: string };
+type JsDocDeprecation = { since: string | undefined; doc: string | undefined };
+
+type JsDocSpec = {
+    params?: JsDocParam[];
+    returns?: string | undefined;
+    throws?: string | undefined;
+    deprecated?: JsDocDeprecation | undefined;
+    since?: string | undefined;
+    identifiers?: Map<string, string> | undefined;
+};
+
+type DocConverter = (text: string) => string;
+
+const WHITESPACE_RUN_PATTERN = /\s+/g;
+const PICTURE_PATTERN = /<picture[\s\S]*?<\/picture>/g;
+const VIDEO_PATTERN = /<video[\s\S]*?(?:<\/video>|\/>)/g;
+const IMAGE_PATTERN = /<img[^>]*>/g;
+
+const stripDocMedia = (markdown: string): string =>
+    markdown.replaceAll(PICTURE_PATTERN, "").replaceAll(VIDEO_PATTERN, "").replaceAll(IMAGE_PATTERN, "");
+
+const flatten = (text: string, convert: DocConverter): string =>
+    convert(text).replaceAll(WHITESPACE_RUN_PATTERN, " ").trim();
+
+const paramLines = (params: JsDocParam[] | undefined, convert: DocConverter): string[] =>
+    (params ?? [])
+        .map((param) => ({ name: param.name, text: flatten(param.doc, convert) }))
+        .filter((entry) => entry.text.length > 0)
+        .map((entry) => `@param ${entry.name} ${entry.text}`);
+
+const returnsLines = (returns: string | undefined, convert: DocConverter): string[] => {
+    const text = convert(returns ?? "").trim();
+
+    return text.length === 0 ? [] : `@returns ${text}`.split("\n");
+};
+
+const simpleTagLine = (tag: string, value: string | undefined, convert: DocConverter): string[] => {
+    const text = flatten(value ?? "", convert);
+
+    return text.length === 0 ? [] : [`${tag} ${text}`];
+};
+
+const sinceClause = (since: string | undefined): string =>
+    since === undefined || since.length === 0 ? "" : `Since ${since}.`;
+
+const deprecatedText = (deprecation: JsDocDeprecation, convert: DocConverter): string =>
+    [sinceClause(deprecation.since), flatten(deprecation.doc ?? "", convert)]
+        .filter((part) => part.length > 0)
+        .join(" ");
+
+const deprecatedLine = (deprecation: JsDocDeprecation | undefined, convert: DocConverter): string[] => {
+    if (deprecation === undefined) {
+        return [];
+    }
+
+    const text = deprecatedText(deprecation, convert);
+
+    return [text.length === 0 ? "@deprecated" : `@deprecated ${text}`];
+};
+
+const renderDocTagLines = (spec: JsDocSpec, convert: DocConverter): string[] => [
+    ...paramLines(spec.params, convert),
+    ...returnsLines(spec.returns, convert),
+    ...simpleTagLine("@throws", spec.throws, convert),
+    ...deprecatedLine(spec.deprecated, convert),
+    ...simpleTagLine("@since", spec.since, convert),
+];
+
+export { renderDocTagLines, stripDocMedia, type JsDocDeprecation, type JsDocParam, type JsDocSpec };

package/src/writer/doc.ts

@@ -1,11 +1,15 @@
+import { type JsDocSpec, renderDocTagLines, stripDocMedia } from "./doc-tags.js";
 import { gtkDocToMarkdown } from "./gtk-doc.js";
 
 const escapeCommentTerminators = (doc: string): string => doc.replaceAll("*/", String.raw`*\/`);
 
-const renderJsDocLines = (lines: string[]): string => {
+const convertDoc = (doc: string, identifiers: Map<string, string> | undefined): string =>
+    escapeCommentTerminators(stripDocMedia(gtkDocToMarkdown(doc, identifiers)));
+
+const renderJsDocLines = (lines: string[], isCollapsible: boolean): string => {
     const [single, ...rest] = lines;
 
-    if (single !== undefined && rest.length === 0) {
+    if (isCollapsible && single !== undefined && rest.length === 0) {
         return `/** ${single} */\n`;
     }
 
@@ -14,12 +18,31 @@ const renderJsDocLines = (lines: string[]): string => {
     return `/**\n${body}\n */\n`;
 };
 
-const renderJsDoc = (doc: string | undefined): string => {
-    if (doc === undefined || doc.length === 0) {
-        return "";
+const docLines = (doc: string | undefined, identifiers: Map<string, string> | undefined): string[] =>
+    doc === undefined || doc.length === 0 ? [] : convertDoc(doc, identifiers).split("\n");
+
+const appendNote = (lines: string[], note: string): string[] =>
+    lines.length === 0 ? note.split("\n") : [...lines, "", ...note.split("\n")];
+
+const appendTags = (lines: string[], tagLines: string[]): string[] => {
+    if (lines.length === 0 || tagLines.length === 0) {
+        return [...lines, ...tagLines];
     }
 
-    return renderJsDocLines(escapeCommentTerminators(gtkDocToMarkdown(doc)).split("\n"));
+    return [...lines, "", ...tagLines];
+};
+
+const specLines = (spec: JsDocSpec | undefined): string[] =>
+    spec === undefined ? [] : renderDocTagLines(spec, (text) => convertDoc(text, spec.identifiers));
+
+const renderJsDoc = (doc: string | undefined, note?: string, spec?: JsDocSpec): string => {
+    const described = docLines(doc, spec?.identifiers);
+    const withNote = note === undefined ? described : appendNote(described, note);
+    const tagLines = specLines(spec);
+    const lines = appendTags(withNote, tagLines);
+
+    return lines.length === 0 ? "" : renderJsDocLines(lines, tagLines.length === 0);
 };
 
+export { type JsDocSpec } from "./doc-tags.js";
 export { renderJsDoc };

package/src/writer/gtk-doc.ts

@@ -1,7 +1,7 @@
 import { camelCase } from "@gtkx/utils";
 
 const CONSTANT_MAP: Record<string, string> = { TRUE: "true", FALSE: "false", NULL: "null" };
-const CALLABLE_LINK_KINDS: Set<string> = new Set(["method", "func", "ctor", "vfunc"]);
+const CALLABLE_LINK_KINDS: Set<string> = new Set(["method", "func", "ctor", "vfunc", "id"]);
 const SENTINEL = String.fromCodePoint(0xE0_00);
 const CODE_BLOCK_OPEN = "|[";
 const CODE_BLOCK_CLOSE = "]|";
@@ -9,10 +9,23 @@ const CODE_LANGUAGE_PATTERN = /^\s*<!--\s*language="([^"]*)"\s*-->/;
 const FENCED_BLOCK_PATTERN = /```[\s\S]*?```/g;
 const INLINE_CODE_PATTERN = /`[^`\n]*`/g;
 const LINK_PATTERN = /\[(\w+)@([\w.:%#-]+)\]/g;
-const CONSTANT_PATTERN = /(?<!\w)%(\w+)/g;
-const TYPE_REF_PATTERN = /(?<!\w)#(\w+)/g;
+const CONSTANT_PATTERN = /(?<![\w\\])%(\w+)/g;
+const ESCAPED_CONSTANT_PATTERN = /\\%/g;
+const TYPE_REF_PATTERN = /(?<!\w)#(\w+)(::[\w-]+|:[\w-]+)?/g;
 const PARAM_REF_PATTERN = /(?<!\w)@(\w+)/g;
 const FUNCTION_REF_PATTERN = /\b([a-z_][a-z0-9_]*)\(\)/g;
+const HTML_COMMENT_PATTERN = /<!--[\s\S]*?-->/g;
+const DOCBOOK_TAG_PATTERN = /<\/?(?:itemizedlist|listitem|para|literal|link|informalexample|programlisting)[\s>]/;
+const DOCBOOK_LISTING_OPEN = "<programlisting>";
+const DOCBOOK_LISTING_CLOSE = "</programlisting>";
+const DOCBOOK_EXAMPLE_PATTERN = /<\/?informalexample>\s*/g;
+const DOCBOOK_ITEM_OPEN_PATTERN = /<listitem>\s*(?:<para>\s*)?/g;
+const DOCBOOK_ITEM_CLOSE_PATTERN = /(?:<\/para>\s*)?<\/listitem>\s*/g;
+const DOCBOOK_LINK_PATTERN = /<link\s+linkend="[^"]*">([\s\S]*?)<\/link>/g;
+const DOCBOOK_LITERAL_PATTERN = /<literal>([\s\S]*?)<\/literal>/g;
+const DOCBOOK_LIST_PATTERN = /<\/?itemizedlist>\s*/g;
+const DOCBOOK_PARA_PATTERN = /<\/?para>\s*/g;
+const BLANK_LINE_RUN_PATTERN = /\n{3,}/g;
 
 const renderLink = (kind: string, target: string): string => {
     const segments = target.split(/::|[.:]/);
@@ -27,6 +40,17 @@ const renderLink = (kind: string, target: string): string => {
     return `\`${symbol}${CALLABLE_LINK_KINDS.has(kind) ? "()" : ""}\``;
 };
 
+const renderTypeRef = (name: string, member: string | undefined): string => {
+    if (member === undefined) {
+        return `\`${name}\``;
+    }
+
+    return renderLink(member.startsWith("::") ? "signal" : "property", `${name}${member}`);
+};
+
+const renderParamRef = (name: string, identifiers: Map<string, string> | undefined): string =>
+    `\`${identifiers?.get(name) ?? name}\``;
+
 const trimTrailingNewlines = (value: string): string => {
     let end = value.length;
 
@@ -46,32 +70,69 @@ const renderCodeFence = (body: string): string => {
     return `\`\`\`${fence}\n${code}\n\`\`\``;
 };
 
-const protectCodeBlocks = (raw: string, protect: (value: string) => string): string => {
+const renderListing = (code: string): string => `\n\`\`\`\n${code.trim()}\n\`\`\`\n`;
+
+const replaceDocBookTags = (text: string): string =>
+    replaceDelimited(text, [DOCBOOK_LISTING_OPEN, DOCBOOK_LISTING_CLOSE], renderListing)
+        .replaceAll(DOCBOOK_EXAMPLE_PATTERN, "\n")
+        .replaceAll(DOCBOOK_ITEM_OPEN_PATTERN, "\n- ")
+        .replaceAll(DOCBOOK_ITEM_CLOSE_PATTERN, "\n")
+        .replaceAll(DOCBOOK_LINK_PATTERN, (_match, label: string) => label)
+        .replaceAll(DOCBOOK_LITERAL_PATTERN, (_match, literal: string) => `\`${literal}\``)
+        .replaceAll(DOCBOOK_LIST_PATTERN, "\n\n")
+        .replaceAll(DOCBOOK_PARA_PATTERN, "\n\n");
+
+const docBookToMarkdown = (text: string): string => {
+    if (!DOCBOOK_TAG_PATTERN.test(text)) {
+        return text;
+    }
+
+    return replaceDocBookTags(text).replaceAll(BLANK_LINE_RUN_PATTERN, "\n\n").trim();
+};
+
+const replaceDelimited = (raw: string, bounds: [string, string], render: (body: string) => string): string => {
+    const [open, close] = bounds;
     let result = "";
     let cursor = 0;
 
     while (cursor < raw.length) {
-        const open = raw.indexOf(CODE_BLOCK_OPEN, cursor);
+        const start = raw.indexOf(open, cursor);
 
-        if (open === -1) {
+        if (start === -1) {
             break;
         }
 
-        const close = raw.indexOf(CODE_BLOCK_CLOSE, open + CODE_BLOCK_OPEN.length);
+        const end = raw.indexOf(close, start + open.length);
 
-        if (close === -1) {
+        if (end === -1) {
             break;
         }
 
-        result += raw.slice(cursor, open);
-        result += protect(renderCodeFence(raw.slice(open + CODE_BLOCK_OPEN.length, close)));
-        cursor = close + CODE_BLOCK_CLOSE.length;
+        result += raw.slice(cursor, start);
+        result += render(raw.slice(start + open.length, end));
+        cursor = end + close.length;
     }
 
     return result + raw.slice(cursor);
 };
 
-const gtkDocToMarkdown = (raw: string): string => {
+const protectCodeBlocks = (raw: string, protect: (value: string) => string): string =>
+    replaceDelimited(raw, [CODE_BLOCK_OPEN, CODE_BLOCK_CLOSE], (body) => protect(renderCodeFence(body)));
+
+const stripHtmlComments = (text: string): string => {
+    let current = text;
+    let previous = "";
+
+    while (current !== previous) {
+        previous = current;
+        current = current.replaceAll(HTML_COMMENT_PATTERN, "");
+    }
+
+    return current;
+};
+
+// eslint-disable-next-line gtkx/no-library-prefix
+const gtkDocToMarkdown = (raw: string, identifiers?: Map<string, string>): string => {
     const stash: string[] = [];
 
     const protect = (value: string): string => {
@@ -81,14 +142,20 @@ const gtkDocToMarkdown = (raw: string): string => {
         return token;
     };
 
-    let text = protectCodeBlocks(raw, protect);
+    let text = protectCodeBlocks(docBookToMarkdown(raw), protect);
     text = text.replaceAll(FENCED_BLOCK_PATTERN, (block) => protect(block));
     text = text.replaceAll(INLINE_CODE_PATTERN, (span) => protect(span));
     text = text.replaceAll(LINK_PATTERN, (_match, kind: string, target: string) => protect(renderLink(kind, target)));
     text = text.replaceAll(CONSTANT_PATTERN, (_match, name: string) => protect(`\`${CONSTANT_MAP[name] ?? name}\``));
-    text = text.replaceAll(TYPE_REF_PATTERN, (_match, name: string) => protect(`\`${name}\``));
-    text = text.replaceAll(PARAM_REF_PATTERN, (_match, name: string) => protect(`\`${name}\``));
+    text = text.replaceAll(ESCAPED_CONSTANT_PATTERN, "%");
+
+    text = text.replaceAll(TYPE_REF_PATTERN, (_match, name: string, member: string | undefined) =>
+        protect(renderTypeRef(name, member)),
+    );
+
+    text = text.replaceAll(PARAM_REF_PATTERN, (_match, name: string) => protect(renderParamRef(name, identifiers)));
     text = text.replaceAll(FUNCTION_REF_PATTERN, (_match, name: string) => protect(`\`${name}()\``));
+    text = stripHtmlComments(text);
 
     for (let index = stash.length - 1; index >= 0; index -= 1) {
         const value = stash[index] ?? "";