@gtkx/codegen 0.21.0 → 1.0.0-rc.1

package/src/docs/pipeline.ts

@@ -0,0 +1,182 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ElementProp } from "@gtkx/config";
+import { sortStringsBy } from "@gtkx/utils";
+import { computeFingerprint, FINGERPRINT_FILENAME, isStoreFresh } from "../fingerprint.js";
+import { Library } from "../gir/library.js";
+import { namespaceDirectory } from "../gir/namespace.js";
+import { collectIntrinsicElementClasses, type GlibNamedClass } from "../store/react/intrinsic-elements.js";
+import { createElementPageContext, renderElementPage } from "./element-page.js";
+import { elementSlug, firstSentence, namespaceOrder } from "./render.js";
+
+export type DocsElementLink = {
+    text: string;
+    link: string;
+};
+
+export type DocsNamespace = {
+    name: string;
+    directory: string;
+    link: string;
+    elements: DocsElementLink[];
+};
+
+export type DocsOptions = {
+    libraries: string[];
+    girPath: string[];
+    outDir: string;
+    basePath?: string;
+    elementProps?: Record<string, ElementProp[]>;
+    force?: boolean;
+};
+
+type DocsManifest = {
+    namespaces: DocsNamespace[];
+};
+
+const MANIFEST_FILENAME = "manifest.json";
+
+const namespaceIndexPage = (namespace: DocsNamespace, elements: GlibNamedClass[]): string => {
+    const rows = elements.map((entry, index) => {
+        const link = namespace.elements[index]?.link ?? "";
+        const description = firstSentence(entry.klass.doc).replaceAll("|", "\\|");
+        return `| [${entry.glibName}](${link}) | ${description} |`;
+    });
+    return [
+        "---",
+        `description: ${JSON.stringify(`Reference pages for the ${namespace.elements.length} JSX elements in the ${namespace.name} namespace.`)}`,
+        "---",
+        "",
+        `# ${namespace.name} elements`,
+        "",
+        `Elements in this namespace are imported from \`@gtkx/jsx/${namespace.directory}\`; the matching classes, enums, and functions are imported from \`@gtkx/gi/${namespace.directory}\`.`,
+        "",
+        "| Element | Description |",
+        "| --- | --- |",
+        ...rows,
+        "",
+    ].join("\n");
+};
+
+const rootIndexPage = (namespaces: DocsNamespace[], libraries: string[]): string => {
+    const rows = namespaces.map(
+        (ns) => `| [${ns.name}](${ns.link}) | \`@gtkx/jsx/${ns.directory}\` | ${ns.elements.length} |`,
+    );
+    const librariesList = libraries.map((library) => `\`${library}\``).join(", ");
+    return [
+        "---",
+        `description: "Generated reference documentation for every JSX element in this project's GIR libraries."`,
+        "---",
+        "",
+        "# Element Reference",
+        "",
+        `This reference documents every JSX element generated from the GObject-Introspection data for ${librariesList}, together with the namespaces they pull in. It is produced by \`gtkx docs\` using the same pipeline that generates the \`@gtkx/jsx\` and \`@gtkx/gi\` bindings, so every page matches the types your editor sees.`,
+        "",
+        "Each element page lists:",
+        "",
+        "- **Props** derived from GObject properties, plus the element props GTKX adds (such as `children` and named slots), with types, defaults, and upstream documentation.",
+        "- **Signals** as `on<Signal>` handler props with their exact handler signatures.",
+        "- **Methods** available on the underlying instance through the `ref` prop.",
+        "",
+        "## Namespaces",
+        "",
+        "| Namespace | Import | Elements |",
+        "| --- | --- | --- |",
+        ...rows,
+        "",
+    ].join("\n");
+};
+
+type GeneratedDocs = {
+    pages: { path: string; content: string }[];
+    namespaces: DocsNamespace[];
+};
+
+const generatePages = (options: DocsOptions, basePath: string, library: Library): GeneratedDocs => {
+    const intrinsicElements = collectIntrinsicElementClasses(library);
+
+    const byNamespace = new Map<string, GlibNamedClass[]>();
+    for (const entry of intrinsicElements) {
+        const list = byNamespace.get(entry.namespace.name) ?? [];
+        list.push(entry);
+        byNamespace.set(entry.namespace.name, list);
+    }
+
+    const linkByGlibName = new Map<string, string>();
+    for (const entry of intrinsicElements) {
+        const directory = namespaceDirectory(entry.namespace);
+        const slug = elementSlug(entry.klass.name);
+        const link = `${basePath}/${directory}/${slug}`;
+        const existing = [...linkByGlibName.values()].includes(link);
+        if (existing) throw new Error(`Docs page slug collision for ${entry.glibName} at ${link}`);
+        linkByGlibName.set(entry.glibName, link);
+    }
+
+    const pageContext = createElementPageContext(library, options.elementProps ?? {}, (glibName) =>
+        linkByGlibName.get(glibName),
+    );
+
+    const pages: { path: string; content: string }[] = [];
+    const namespaces: DocsNamespace[] = [];
+    const orderedNames = sortStringsBy([...byNamespace.keys()], namespaceOrder);
+    for (const name of orderedNames) {
+        const elements = sortStringsBy(byNamespace.get(name) ?? [], (entry) => entry.glibName);
+        const directory = name.toLowerCase();
+        const namespaceDocs: DocsNamespace = {
+            name,
+            directory,
+            link: `${basePath}/${directory}/`,
+            elements: elements.map((entry) => ({
+                text: entry.glibName,
+                link: linkByGlibName.get(entry.glibName) ?? "",
+            })),
+        };
+        for (const entry of elements) {
+            const slug = elementSlug(entry.klass.name);
+            pages.push({ path: `${directory}/${slug}.md`, content: renderElementPage(entry, pageContext) });
+        }
+        pages.push({ path: `${directory}/index.md`, content: namespaceIndexPage(namespaceDocs, elements) });
+        namespaces.push(namespaceDocs);
+    }
+    pages.push({ path: "index.md", content: rootIndexPage(namespaces, options.libraries) });
+    return { pages, namespaces };
+};
+
+export type DocsResult = {
+    regenerated: boolean;
+    namespaces: DocsNamespace[];
+};
+
+export const writeDocs = (options: DocsOptions): DocsResult => {
+    const basePath = options.basePath ?? "/reference";
+    const elementProps = options.elementProps ?? {};
+    const manifestPath = join(options.outDir, MANIFEST_FILENAME);
+    if (options.force !== true && isStoreFresh(options.outDir, options.libraries, elementProps)) {
+        if (existsSync(manifestPath)) {
+            const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as DocsManifest;
+            return { regenerated: false, namespaces: manifest.namespaces };
+        }
+    }
+
+    const library = Library.load(options.libraries, options.girPath);
+    const { pages, namespaces } = generatePages(options, basePath, library);
+
+    rmSync(options.outDir, { recursive: true, force: true });
+    mkdirSync(options.outDir, { recursive: true });
+    for (const page of pages) {
+        const target = join(options.outDir, page.path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, page.content);
+    }
+    const manifest: DocsManifest = { namespaces };
+    writeFileSync(manifestPath, JSON.stringify(manifest));
+    writeFileSync(
+        join(options.outDir, FINGERPRINT_FILENAME),
+        JSON.stringify({
+            value: computeFingerprint(library.girFiles, options.libraries, elementProps),
+            girFiles: library.girFiles,
+            libraries: options.libraries,
+        }),
+    );
+    return { regenerated: true, namespaces };
+};

package/src/docs/render.ts

@@ -0,0 +1,191 @@
+import { sortStringsBy, toPascalCase } from "@gtkx/utils";
+import { collectInheritedMethods, conflictRename } from "../analysis/inheritance.js";
+import { renderHandlerParameters, renderHandlerResultType } from "../analysis/param-structure.js";
+import { renderBaseTypeFor, type TsTypeTarget } from "../analysis/ts-type.js";
+import type { GirClass } from "../gir/class.js";
+import type { GirFunction } from "../gir/function.js";
+import type { Library } from "../gir/library.js";
+import type { GirNamespace } from "../gir/namespace.js";
+import type { GirSignal } from "../gir/parameter.js";
+import type { TypeId } from "../gir/type-id.js";
+import { dedupeCallables, indexMethodsByName, renderInstanceMethodSignature } from "../store/gi/callables.js";
+import { methodExportName } from "../store/gi/method.js";
+import { ModuleContext } from "../writer/context.js";
+import { gtkDocToMarkdown } from "../writer/gtk-doc.js";
+
+const docsTarget = (library: Library): TsTypeTarget => ({
+    containerStyle: "record",
+    callbackType: "((...args: unknown[]) => unknown)",
+    byteArrayAsNumber: false,
+    renderNamed: (resolved, name) => {
+        if (resolved?.kind === "alias") {
+            return resolved.value.target === undefined
+                ? "number"
+                : renderBaseTypeFor(library, docsTarget(library), resolved.value.target);
+        }
+        return `${name.namespaceName}.${name.typeName}`;
+    },
+    renderGtype: () => "GObject.Type",
+});
+
+export const renderDocsType = (library: Library, ref: TypeId | undefined, isNullable: boolean): string => {
+    const base = renderBaseTypeFor(library, docsTarget(library), ref);
+    return isNullable ? `${base} | null` : base;
+};
+
+const renderDocsHandlerResultType = (library: Library, signal: GirSignal): string =>
+    renderHandlerResultType({
+        library,
+        signal,
+        renderType: (ref, nullable) => renderDocsType(library, ref, nullable),
+        includeCallerAllocated: false,
+        optOut: true,
+    });
+
+const renderDocsHandlerParameters = (library: Library, signal: GirSignal): string[] =>
+    renderHandlerParameters(signal.parameters, (ref, nullable) => renderDocsType(library, ref, nullable));
+
+export const renderDocsSignalSignature = (library: Library, signal: GirSignal, selfType: string): string => {
+    const params = [...renderDocsHandlerParameters(library, signal), `self: ${selfType}`];
+    return `(${params.join(", ")}) => ${renderDocsHandlerResultType(library, signal)}`;
+};
+
+export const renderDocsSignalHandlerType = (library: Library, signal: GirSignal): string =>
+    `(${renderDocsHandlerParameters(library, signal).join(", ")}) => ${renderDocsHandlerResultType(library, signal)}`;
+
+const DOCS_DEFAULT_VALUES: Record<string, string> = { TRUE: "true", FALSE: "false", NULL: "null" };
+
+export const docsDefaultValue = (value: string): string => DOCS_DEFAULT_VALUES[value] ?? value;
+
+const stripDocMedia = (markdown: string): string =>
+    markdown
+        .replace(/<picture[\s\S]*?<\/picture>/g, "")
+        .replace(/<video[\s\S]*?(?:<\/video>|\/>)/g, "")
+        .replace(/<img[^>]*>/g, "");
+
+const demoteHeadings = (markdown: string): string => {
+    let inFence = false;
+    return markdown
+        .split("\n")
+        .map((line) => {
+            if (/^\s*(```|~~~)/.test(line)) {
+                inFence = !inFence;
+                return line;
+            }
+            if (inFence) return line;
+            return /^#{1,5}\s/.test(line) ? `#${line}` : line;
+        })
+        .join("\n");
+};
+
+export const docMarkdown = (doc: string | undefined): string =>
+    doc === undefined || doc.length === 0 ? "" : demoteHeadings(stripDocMedia(gtkDocToMarkdown(doc))).trim();
+
+const stripMarkdown = (markdown: string): string =>
+    markdown
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/`([^`]*)`/g, "$1")
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/[*_#>]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+
+export const firstSentence = (doc: string | undefined): string => {
+    const text = stripMarkdown(docMarkdown(doc));
+    if (text.length === 0) return "";
+    const match = text.match(/^.*?[.!?](?=\s|$)/);
+    const sentence = match?.[0] ?? text;
+    return sentence.length > 220 ? `${sentence.slice(0, 217)}...` : sentence;
+};
+
+export const elementSlug = (className: string): string =>
+    className
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+        .toLowerCase();
+
+export const joinSections = (sections: string[]): string =>
+    `${sections.filter((section) => section.length > 0).join("\n\n")}\n`;
+
+export const metaBlock = (name: string, meta: string, doc: string): string => {
+    const lines = [`### \`${name}\``, "", meta];
+    if (doc.length > 0) lines.push("", doc);
+    return lines.join("\n");
+};
+
+export const signatureBlock = (name: string, signature: string, notes: string[]): string => {
+    const lines = [`### \`${name}\``, "", `\`\`\`ts\n${signature}\n\`\`\``];
+    for (const note of notes) {
+        if (note.length > 0) lines.push("", note);
+    }
+    return lines.join("\n");
+};
+
+const LEADING_NAMESPACES = ["Gtk", "Adw"];
+
+export const namespaceOrder = (name: string): string => {
+    const index = LEADING_NAMESPACES.indexOf(name);
+    return index === -1 ? `1${name}` : `0${index}`;
+};
+
+const DOCS_SIGNATURE_NAMESPACE = "$docs";
+
+export const docsSignatureContext = (namespace: GirNamespace, library: Library): ModuleContext =>
+    new ModuleContext({ ...namespace, name: DOCS_SIGNATURE_NAMESPACE }, library);
+
+export type SignatureEntry = {
+    name: string;
+    signature: string;
+    doc: string;
+};
+
+export type OriginSignatureEntry = SignatureEntry & { origin: string | undefined };
+
+export const originSignatureBlocks = (entries: OriginSignatureEntry[]): string[] =>
+    sortStringsBy(entries, (item) => item.name).map((item) =>
+        signatureBlock(item.name, item.signature, [
+            item.origin === undefined ? "" : `From \`${item.origin}\`.`,
+            item.doc,
+        ]),
+    );
+
+export const classMethodEntries = (library: Library, namespace: GirNamespace, klass: GirClass): SignatureEntry[] => {
+    const realContext = new ModuleContext(namespace, library);
+    const signatureContext = docsSignatureContext(namespace, library);
+    const className = toPascalCase(klass.name);
+    const inherited = collectInheritedMethods(realContext, klass);
+    return instanceMethodEntries(signatureContext, klass.methods, (method) =>
+        conflictRename(realContext, method, inherited, className),
+    );
+};
+
+export const methodsSectionBlocks = (entries: SignatureEntry[], intro: string): string[] =>
+    entries.length === 0
+        ? []
+        : ["## Methods", intro, ...entries.map((item) => signatureBlock(item.name, item.signature, [item.doc]))];
+
+export const instanceMethodEntries = (
+    signatureContext: ModuleContext,
+    methods: GirFunction[],
+    rename: (fn: GirFunction) => string | undefined,
+): SignatureEntry[] => {
+    const deduped = dedupeCallables(methods);
+    const siblings = indexMethodsByName(deduped);
+    const entries: SignatureEntry[] = [];
+    for (const method of deduped) {
+        const nameOverride = rename(method);
+        const rendered = renderInstanceMethodSignature(
+            signatureContext,
+            { ...method, doc: undefined },
+            siblings,
+            nameOverride,
+        );
+        if (rendered === undefined) continue;
+        entries.push({
+            name: nameOverride ?? methodExportName(method),
+            signature: rendered.trim().replace(/;$/, ""),
+            doc: docMarkdown(method.doc),
+        });
+    }
+    return sortStringsBy(entries, (entry) => entry.name);
+};