@gtkx/codegen 1.0.0 → 1.1.0

package/src/analysis/ts-type.ts

@@ -1,6 +1,8 @@
+import { sanitizeTypeIdentifier } from "@gtkx/utils";
 import type { Library } from "../gir/library.js";
 import type { EntityType, GirType } from "../gir/type.js";
 import type { ModuleContext } from "../writer/context.js";
+import { isEmittableEntity } from "../gir/emittable.js";
 import { PRIMITIVE_TS_TYPE } from "../gir/primitives.js";
 import {
     type CArrayType,
@@ -24,21 +26,14 @@ type TsTypeTarget = {
     renderGtype: () => string;
 };
 
-const willEmitEntity = (type: EntityType): boolean => {
-    switch (type.kind) {
-        case "callback": {
-            return type.value.introspectable && type.value.name.length > 0;
-        }
-        case "record": {
-            return type.value.introspectable && type.value.name.length > 0;
-        }
-        case "alias":
-        case "class":
-        case "enum":
-        case "interface": {
-            return true;
-        }
-    }
+const willEmitEntity = (type: EntityType): boolean => isEmittableEntity(type.value);
+
+const referenceName = (library: Library, ref: TypeId): ReferenceName | undefined => {
+    const name = library.nameFor(ref);
+
+    return name === undefined
+        ? undefined
+        : { namespaceName: name.namespaceName, typeName: sanitizeTypeIdentifier(name.typeName) };
 };
 
 const renderPrimitiveType = (target: TsTypeTarget, type: Extract<GirType, { kind: "primitive" }>): string =>
@@ -56,12 +51,13 @@ const renderBaseType = (library: Library, target: TsTypeTarget, ref: TypeId | un
     }
 
     const type = library.typeFor(ref);
-    const name = library.nameFor(ref);
 
     if (type === undefined) {
-        return renderNamedType(target, undefined, name);
+        return renderNamedType(target, undefined, undefined);
     }
 
+    const name = referenceName(library, ref);
+
     switch (type.kind) {
         case "primitive": {
             return renderPrimitiveType(target, type);

package/src/analysis/type-key.ts

@@ -0,0 +1,14 @@
+import type { Library } from "../gir/library.js";
+import type { TypeId } from "../gir/type-id.js";
+
+const typeKey = (library: Library, ref: TypeId | undefined): string => {
+    if (ref === undefined) {
+        return "void";
+    }
+
+    const type = library.typeFor(ref);
+
+    return type?.kind === "primitive" && type.category === "void" ? "void" : `${String(ref.nsId)}.${String(ref.id)}`;
+};
+
+export { typeKey };

package/src/compile.ts

@@ -1,20 +1,37 @@
-import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { errorMessage, normalizeError } from "@gtkx/utils";
+import { existsSync, mkdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import ts from "typescript";
+import { createStagingDir, sweepStrandedDirs } from "./staging.js";
 
-type SourceModule = {
+type ProjectFile = {
     fileName: string;
+    origin?: string | undefined;
+};
+
+type SourceModule = ProjectFile & {
     source: string;
 };
 
 type CompileProjectParams = {
     projectDir: string;
-    fileNames: string[];
+    files: ProjectFile[];
     compilerOptions: Record<string, unknown>;
     label: string;
 };
 
+type DiagnosedFile = {
+    fileName: string;
+    text: string;
+};
+
+type FailedProjectInput = {
+    projectDir: string;
+    keepAt: string;
+    error: unknown;
+};
+
 const BASE_COMPILER_OPTIONS = {
     module: "esnext",
     moduleResolution: "bundler",
@@ -43,6 +60,10 @@ const CHECK_OPTIONS = {
     noEmit: true,
 };
 
+const CHECK_DIR = ".gtkx-check";
+const FAILED_CHECK_DIR = `${CHECK_DIR}.failed`;
+const LEGACY_CHECK_PREFIX = `${CHECK_DIR}-`;
+
 const FORMAT_HOST: ts.FormatDiagnosticsHost = {
     getCanonicalFileName: (fileName) => fileName,
     getCurrentDirectory: () => ts.sys.getCurrentDirectory(),
@@ -72,54 +93,107 @@ const linkToolingModules = (projectDir: string): (() => void) => {
 const isProjectFile = (rel: string): boolean =>
     !rel.startsWith("..") && !isAbsolute(rel) && !rel.split(/[/\\]/).includes("node_modules");
 
-const projectDiagnosticLine = (diagnostic: ts.Diagnostic, projectDir: string): string | undefined => {
+const projectDiagnosticFile = (diagnostic: ts.Diagnostic, projectDir: string): DiagnosedFile | undefined => {
     const { file, start } = diagnostic;
 
     if (file === undefined || start === undefined) {
         return undefined;
     }
 
-    const filePath = relative(projectDir, file.fileName);
+    const fileName = relative(projectDir, file.fileName);
 
-    if (!isProjectFile(filePath)) {
+    if (!isProjectFile(fileName)) {
         return undefined;
     }
 
     const { line, character } = file.getLineAndCharacterOfPosition(start);
     const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
 
-    return `${filePath}:${String(line + 1)}:${String(character + 1)} - ${message} (TS${String(diagnostic.code)})`;
+    return {
+        fileName,
+        text: `${fileName}:${String(line + 1)}:${String(character + 1)} - ${message} (TS${String(diagnostic.code)})`,
+    };
 };
 
-const projectDiagnosticLines = (diagnostics: ts.Diagnostic[], projectDir: string): string[] => {
-    const lines: string[] = [];
+const projectDiagnosticFiles = (diagnostics: ts.Diagnostic[], projectDir: string): DiagnosedFile[] => {
+    const diagnosed: DiagnosedFile[] = [];
 
     for (const diagnostic of diagnostics) {
-        const line = projectDiagnosticLine(diagnostic, projectDir);
+        const entry = projectDiagnosticFile(diagnostic, projectDir);
+
+        if (entry !== undefined) {
+            diagnosed.push(entry);
+        }
+    }
+
+    return diagnosed;
+};
+
+const collectOrigins = (files: ProjectFile[]): Map<string, string> => {
+    const origins: Map<string, string> = new Map();
+
+    for (const { fileName, origin } of files) {
+        if (origin !== undefined) {
+            origins.set(fileName, origin);
+        }
+    }
 
-        if (line !== undefined) {
-            lines.push(line);
+    return origins;
+};
+
+const groupByOrigin = (diagnosed: DiagnosedFile[], origins: Map<string, string>): Map<string, Set<string>> => {
+    const grouped: Map<string, Set<string>> = new Map();
+
+    for (const { fileName } of diagnosed) {
+        const origin = origins.get(fileName);
+
+        if (origin !== undefined) {
+            grouped.set(origin, (grouped.get(origin) ?? new Set<string>()).add(fileName));
         }
     }
 
-    return lines;
+    return grouped;
 };
 
-const diagnosticError = (label: string, projectDir: string, diagnostics: ts.Diagnostic[]): Error => {
-    const lines = projectDiagnosticLines(diagnostics, projectDir);
+const originLines = (diagnosed: DiagnosedFile[], files: ProjectFile[]): string[] =>
+    [...groupByOrigin(diagnosed, collectOrigins(files))].map(
+        ([origin, generated]) => `Generated from ${origin}: ${[...generated].join(", ")}`,
+    );
+
+const diagnosticError = (params: CompileProjectParams, diagnostics: ts.Diagnostic[]): Error => {
+    const diagnosed = projectDiagnosticFiles(diagnostics, params.projectDir);
+    const { label } = params;
 
-    if (lines.length > 0) {
-        return new Error(`Type checking ${label} found ${String(lines.length)} error(s):\n${lines.join("\n")}`);
+    if (diagnosed.length === 0) {
+        return new Error(`Type checking ${label} failed:\n${ts.formatDiagnostics(diagnostics, FORMAT_HOST).trim()}`);
     }
 
-    return new Error(`Type checking ${label} failed:\n${ts.formatDiagnostics(diagnostics, FORMAT_HOST).trim()}`);
+    const lines = [...diagnosed.map((entry) => entry.text), ...originLines(diagnosed, params.files)];
+
+    return new Error(`Type checking ${label} found ${String(diagnosed.length)} error(s):\n${lines.join("\n")}`);
+};
+
+const keepFailedProject = (input: FailedProjectInput): Error => {
+    const { projectDir, keepAt, error } = input;
+
+    if (!existsSync(projectDir)) {
+        return normalizeError(error);
+    }
+
+    rmSync(keepAt, { recursive: true, force: true });
+    renameSync(projectDir, keepAt);
+    const rebased = errorMessage(error).split(projectDir).join(keepAt);
+
+    return new Error(`${rebased}\nThe generated sources are kept at ${keepAt}, where every path above resolves.`, {
+        cause: error,
+    });
 };
 
 const runProgram = (params: CompileProjectParams): ts.Diagnostic[] => {
     const parsed = ts.parseJsonConfigFileContent(
         {
             compilerOptions: { ...BASE_COMPILER_OPTIONS, ...params.compilerOptions },
-            files: params.fileNames.map((name) => `./${name}`),
+            files: params.files.map((file) => `./${file.fileName}`),
         },
         ts.sys,
         params.projectDir,
@@ -147,17 +221,24 @@ const compileProject = (params: CompileProjectParams): void => {
         const diagnostics = runProgram(params);
 
         if (diagnostics.length > 0) {
-            throw diagnosticError(params.label, params.projectDir, diagnostics);
+            throw diagnosticError(params, diagnostics);
         }
     } finally {
         unlinkToolingModules();
     }
 };
 
+const stageCheckProject = (checkRoot: string): string => {
+    const projectDir = createStagingDir(join(checkRoot, CHECK_DIR));
+    sweepStrandedDirs(checkRoot, LEGACY_CHECK_PREFIX);
+
+    return projectDir;
+};
+
 const checkModules = (params: { modules: SourceModule[]; resolveFrom: string; label: string }): void => {
     const checkRoot = join(params.resolveFrom, "node_modules");
-    mkdirSync(checkRoot, { recursive: true });
-    const projectDir = mkdtempSync(join(checkRoot, ".gtkx-check-"));
+    const projectDir = stageCheckProject(checkRoot);
+    const keepAt = join(checkRoot, FAILED_CHECK_DIR);
 
     try {
         for (const module of params.modules) {
@@ -168,13 +249,16 @@ const checkModules = (params: { modules: SourceModule[]; resolveFrom: string; la
 
         compileProject({
             projectDir,
-            fileNames: params.modules.map((module) => module.fileName),
+            files: params.modules,
             compilerOptions: CHECK_OPTIONS,
             label: params.label,
         });
-    } finally {
-        rmSync(projectDir, { recursive: true, force: true });
+    } catch (error) {
+        throw keepFailedProject({ projectDir, keepAt, error });
     }
+
+    rmSync(projectDir, { recursive: true, force: true });
+    rmSync(keepAt, { recursive: true, force: true });
 };
 
-export { compileProject, checkModules, type SourceModule };
+export { compileProject, checkModules, keepFailedProject, type ProjectFile, type SourceModule };

package/src/docs/api-reference.ts

@@ -1,7 +1,8 @@
-import { pascalCase, sortStrings, sortStringsBy } from "@gtkx/utils";
+import { sanitizeIdentifier, sanitizeTypeIdentifier, sortStrings, sortStringsBy } from "@gtkx/utils";
 import type { GirClass } from "../gir/class.js";
 import type { GirFunction } from "../gir/function.js";
 import type { GirRecord } from "../gir/record.js";
+import { isEmittableEntity } from "../gir/emittable.js";
 import { Library } from "../gir/library.js";
 import { type GirNamespace, namespaceDirectory } from "../gir/namespace.js";
 import { dedupeCallables, isEmittableCallable } from "../store/gi/callables.js";
@@ -214,13 +215,13 @@ const functionEntry = (
 };
 
 const classEntry = (namespace: GirNamespace, klass: GirClass): GiSymbolEntry | undefined => {
-    if (!klass.introspectable || klass.name.length === 0) {
+    if (!isEmittableEntity(klass)) {
         return undefined;
     }
 
     const kind = klass.isInterface ? "interface" : "class";
 
-    return { kind, namespace, name: pascalCase(klass.name), doc: klass.doc, klass };
+    return { kind, namespace, name: sanitizeTypeIdentifier(klass.name), doc: klass.doc, klass };
 };
 
 const classEntries = (namespace: GirNamespace): GiSymbolEntry[] => {
@@ -238,11 +239,11 @@ const classEntries = (namespace: GirNamespace): GiSymbolEntry[] => {
 };
 
 const recordEntry = (namespace: GirNamespace, record: GirRecord): GiSymbolEntry | undefined => {
-    if (!record.introspectable || record.isVtable || record.name.length === 0) {
+    if (record.isVtable || !isEmittableEntity(record)) {
         return undefined;
     }
 
-    return { kind: "record", namespace, name: record.name, doc: record.doc, record };
+    return { kind: "record", namespace, name: sanitizeTypeIdentifier(record.name), doc: record.doc, record };
 };
 
 const recordEntries = (namespace: GirNamespace): GiSymbolEntry[] => {
@@ -265,7 +266,7 @@ const valueEntries = (namespace: GirNamespace): GiSymbolEntry[] => [
         .map<GiSymbolEntry>((enumeration) => ({
             kind: "enum",
             namespace,
-            name: enumeration.name,
+            name: sanitizeTypeIdentifier(enumeration.name),
             doc: enumeration.doc,
             enumeration,
         })),
@@ -274,21 +275,21 @@ const valueEntries = (namespace: GirNamespace): GiSymbolEntry[] => [
         .map<GiSymbolEntry>((callback) => ({
             kind: "callback",
             namespace,
-            name: callback.name,
+            name: sanitizeTypeIdentifier(callback.name),
             doc: callback.doc,
             callback,
         })),
     ...namespace.aliases.map<GiSymbolEntry>((alias) => ({
         kind: "alias",
         namespace,
-        name: alias.name,
+        name: sanitizeTypeIdentifier(alias.name),
         doc: alias.doc,
         alias,
     })),
     ...namespace.constants.map<GiSymbolEntry>((constant) => ({
         kind: "constant",
         namespace,
-        name: constant.name,
+        name: sanitizeIdentifier(constant.name),
         doc: constant.doc,
         constant,
     })),

package/src/docs/element-page.ts

@@ -29,6 +29,7 @@ import {
     originSignatureBlocks,
     type OriginSignatureEntry,
     propertyMetaLine,
+    qualifiedClassName,
     renderDocsSignalSignature,
     renderDocsType,
     signalTags,
@@ -76,7 +77,9 @@ const hierarchySection = (entry: GlibNamedClass, context: ElementPageContext): s
     const parts = ancestors.map((ancestor) => {
         const glib = getGlibName(ancestor.klass);
 
-        return glib === undefined ? `\`${ancestor.namespaceName}.${ancestor.klass.name}\`` : glibLabel(context, glib);
+        return glib === undefined
+            ? `\`${qualifiedClassName(ancestor.namespaceName, ancestor.klass.name)}\``
+            : glibLabel(context, glib);
     });
 
     parts.push(`**${entry.glibName}**`);
@@ -265,7 +268,7 @@ const methodsSection = (entry: GlibNamedClass, context: ElementPageContext, self
 };
 
 const renderElementPage = (entry: GlibNamedClass, context: ElementPageContext): string => {
-    const selfType = `${entry.namespace.name}.${entry.klass.name}`;
+    const selfType = qualifiedClassName(entry.namespace.name, entry.klass.name);
 
     return joinSections([
         frontmatter(entry),

package/src/docs/pipeline.ts

@@ -1,9 +1,16 @@
 import { sortStringsBy } from "@gtkx/utils";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { computeGiFingerprint, FINGERPRINT_FILENAME, isGiStoreFresh } from "../fingerprint.js";
+import {
+    computeDocsFingerprint,
+    type DocsFingerprintInput,
+    FINGERPRINT_FILENAME,
+    isDocsOutputFresh,
+} from "../fingerprint.js";
 import { Library } from "../gir/library.js";
 import { namespaceDirectory } from "../gir/namespace.js";
+import { arrayGuard, hasFields, isString } from "../guards.js";
+import { readJsonFile } from "../json.js";
 import { type ElementProps, setElementProps } from "../store/jsx/element-prop-imports.js";
 import { collectIntrinsicElementClasses, type GlibNamedClass } from "../store/jsx/intrinsic-elements.js";
 import { type OmittedProps, setOmittedProps } from "../store/jsx/omitted-props.js";
@@ -33,6 +40,7 @@ type DocsOptions = {
 };
 
 type DocsManifest = {
+    generator: string;
     namespaces: DocsNamespace[];
 };
 
@@ -50,6 +58,9 @@ type DocsResult = {
 };
 
 const MANIFEST_FILENAME = "manifest.json";
+const MANIFEST_GENERATOR = "gtkx-docs";
+const ROOT_INDEX_FILENAME = "index.md";
+const DEFAULT_BASE_PATH = "/reference";
 
 const namespaceIndexPage = (namespace: DocsNamespace, elements: GlibNamedClass[]): string => {
     const rows = elements.map((entry, index) => {
@@ -144,6 +155,28 @@ const buildElementLinks = (elements: GlibNamedClass[], basePath: string): Map<st
     return linkByGlibName;
 };
 
+const isEntryInsideOutDir = (value: string): boolean =>
+    value.length > 0 && value !== "." && value !== ".." && !value.includes("/") && !value.includes("\\");
+
+const isChildEntry = (value: unknown): value is string => isString(value) && isEntryInsideOutDir(value);
+
+const ownedEntry = (entry: string, source: string): string => {
+    if (isEntryInsideOutDir(entry)) {
+        return entry;
+    }
+
+    throw new Error(
+        `Refusing to generate documentation outside the output directory: ${source} maps to \`${entry}\`, ` +
+        "which is not an entry inside it. The GIR that declares it is malformed.",
+    );
+};
+
+const elementPagePath = (directory: string, entry: GlibNamedClass): string => {
+    const slug = ownedEntry(elementSlug(entry.klass.name), `the element ${entry.glibName}`);
+
+    return `${directory}/${slug}.md`;
+};
+
 const namespacePages = (input: {
     name: string;
     elements: GlibNamedClass[];
@@ -152,7 +185,7 @@ const namespacePages = (input: {
     pageContext: ElementPageContext;
 }): NamespacePages => {
     const { name, elements, basePath, linkByGlibName, pageContext } = input;
-    const directory = name.toLowerCase();
+    const directory = ownedEntry(namespaceDirectory({ name }), `the GIR namespace ${name}`);
 
     const docs: DocsNamespace = {
         name,
@@ -162,7 +195,7 @@ const namespacePages = (input: {
     };
 
     const pages: Page[] = elements.map((entry) => ({
-        path: `${directory}/${elementSlug(entry.klass.name)}.md`,
+        path: elementPagePath(directory, entry),
         content: renderElementPage(entry, pageContext),
     }));
 
@@ -187,21 +220,90 @@ const generatePages = (options: DocsOptions, basePath: string, library: Library)
         namespaces.push(result.docs);
     }
 
-    pages.push({ path: "index.md", content: rootIndexPage(namespaces, options.libraries) });
+    pages.push({ path: ROOT_INDEX_FILENAME, content: rootIndexPage(namespaces, options.libraries) });
 
     return { pages, namespaces };
 };
 
-const cachedDocsResult = (options: DocsOptions, manifestPath: string): DocsResult | undefined => {
-    if (options.isForced === true || !isGiStoreFresh(options.outDir, options.libraries, options.girPath)) {
-        return undefined;
+const isGeneratorTag = (value: unknown): value is string => value === MANIFEST_GENERATOR;
+
+const isDocsElementLink = (value: unknown): value is DocsElementLink =>
+    hasFields<DocsElementLink>(value, { text: isString, link: isString });
+
+const isDocsNamespace = (value: unknown): value is DocsNamespace =>
+    hasFields<DocsNamespace>(value, {
+        name: isString,
+        directory: isChildEntry,
+        link: isString,
+        elements: arrayGuard(isDocsElementLink),
+    });
+
+const isDocsManifest = (value: unknown): value is DocsManifest =>
+    hasFields<DocsManifest>(value, { generator: isGeneratorTag, namespaces: arrayGuard(isDocsNamespace) });
+
+const readDocsManifest = (manifestPath: string): DocsManifest | undefined => {
+    const parsed = readJsonFile(manifestPath);
+
+    return isDocsManifest(parsed) ? parsed : undefined;
+};
+
+const outDirRefusal = (outDir: string, reason: string): Error =>
+    new Error(
+        `Refusing to generate documentation into ${outDir}: ${reason}. Point the output directory at an ` +
+        "empty directory or at one gtkx generated, or remove it yourself first.",
+    );
+
+const assertOwnedOutDir = (options: DocsOptions, manifest: DocsManifest | undefined): void => {
+    const stats = statSync(options.outDir, { throwIfNoEntry: false });
+
+    if (stats === undefined) {
+        return;
+    }
+
+    if (!stats.isDirectory()) {
+        throw outDirRefusal(options.outDir, "it already exists and is not a directory");
+    }
+
+    if (manifest !== undefined || readdirSync(options.outDir).length === 0) {
+        return;
+    }
+
+    throw outDirRefusal(
+        options.outDir,
+        `it is not empty and holds no ${MANIFEST_FILENAME} written by \`gtkx docs\`, ` +
+        "so its contents are not gtkx's to replace",
+    );
+};
+
+const clearOutDir = (options: DocsOptions, manifest: DocsManifest | undefined): void => {
+    if (manifest === undefined) {
+        return;
     }
 
-    if (!existsSync(manifestPath)) {
+    const entries = [
+        ...manifest.namespaces.map((namespace) => namespace.directory),
+        ROOT_INDEX_FILENAME,
+        MANIFEST_FILENAME,
+        FINGERPRINT_FILENAME,
+    ];
+
+    for (const entry of entries) {
+        rmSync(join(options.outDir, entry), { recursive: true, force: true });
+    }
+};
+
+const cachedDocsResult = (
+    options: DocsOptions,
+    manifest: DocsManifest | undefined,
+    input: DocsFingerprintInput,
+): DocsResult | undefined => {
+    if (manifest === undefined || options.isForced === true) {
         return undefined;
     }
 
-    const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as DocsManifest;
+    if (!isDocsOutputFresh(options.outDir, options.libraries, options.girPath, input)) {
+        return undefined;
+    }
 
     return { isRegenerated: false, namespaces: manifest.namespaces };
 };
@@ -214,28 +316,36 @@ const writePages = (outDir: string, pages: Page[]): void => {
     }
 };
 
+const docsFingerprintInput = (options: DocsOptions): DocsFingerprintInput => ({
+    basePath: options.basePath ?? DEFAULT_BASE_PATH,
+    props: options.props ?? {},
+    omittedProps: options.omittedProps ?? {},
+});
+
 const writeDocs = (options: DocsOptions): DocsResult => {
-    setElementProps(options.props ?? {});
-    setOmittedProps(options.omittedProps ?? {});
-    const basePath = options.basePath ?? "/reference";
+    const input = docsFingerprintInput(options);
+    setElementProps(input.props);
+    setOmittedProps(input.omittedProps);
     const manifestPath = join(options.outDir, MANIFEST_FILENAME);
-    const cached = cachedDocsResult(options, manifestPath);
+    const previous = readDocsManifest(manifestPath);
+    const cached = cachedDocsResult(options, previous, input);
 
     if (cached !== undefined) {
         return cached;
     }
 
+    assertOwnedOutDir(options, previous);
     const library = Library.load(options.libraries, options.girPath);
-    const { pages, namespaces } = generatePages(options, basePath, library);
-    rmSync(options.outDir, { recursive: true, force: true });
+    const { pages, namespaces } = generatePages(options, input.basePath, library);
+    clearOutDir(options, previous);
     mkdirSync(options.outDir, { recursive: true });
-    writePages(options.outDir, pages);
-    const manifest: DocsManifest = { namespaces };
+    const manifest: DocsManifest = { generator: MANIFEST_GENERATOR, namespaces };
     writeFileSync(manifestPath, JSON.stringify(manifest));
+    writePages(options.outDir, pages);
 
     writeFileSync(
         join(options.outDir, FINGERPRINT_FILENAME),
-        JSON.stringify(computeGiFingerprint(library.girFiles, options.libraries, options.girPath)),
+        JSON.stringify(computeDocsFingerprint(library.girFiles, options.libraries, options.girPath, input)),
     );
 
     return { isRegenerated: true, namespaces };

package/src/docs/render.ts

@@ -1,4 +1,4 @@
-import { pascalCase, sortStringsBy } from "@gtkx/utils";
+import { sanitizeTypeIdentifier, sortStringsBy } from "@gtkx/utils";
 import type { GirAnnotations } from "../gir/annotations.js";
 import type { GirClass } from "../gir/class.js";
 import type { GirFunction } from "../gir/function.js";
@@ -286,10 +286,13 @@ const originSignatureBlocks = (entries: OriginSignatureEntry[]): string[] =>
         signatureEntryBlock(item, item.origin === undefined ? [] : [`From \`${item.origin}\`.`]),
     );
 
+const qualifiedClassName = (namespaceName: string, className: string): string =>
+    `${namespaceName}.${sanitizeTypeIdentifier(className)}`;
+
 const classMethodEntries = (library: Library, namespace: GirNamespace, klass: GirClass): SignatureEntry[] => {
     const realContext = new ModuleContext(namespace, library);
     const signatureContext = docsSignatureContext(namespace, library);
-    const className = pascalCase(klass.name);
+    const className = sanitizeTypeIdentifier(klass.name);
     const inherited = collectInheritedMethods(realContext, klass);
 
     return instanceMethodEntries(signatureContext, klass, (method) =>
@@ -307,7 +310,7 @@ const instanceMethodEntries = (
 ): SignatureEntry[] => {
     const deduped = dedupeCallables(klass.methods);
 
-    const scope = instanceScope(pascalCase(klass.name), {
+    const scope = instanceScope(sanitizeTypeIdentifier(klass.name), {
         constructors: dedupeCallables(klass.constructors),
         functions: dedupeCallables(klass.functions),
         methods: deduped,
@@ -362,6 +365,7 @@ export {
     originSignatureBlocks,
     classMethodEntries,
     methodsSectionBlocks,
+    qualifiedClassName,
     tagNotes,
     type MetaDocEntry,
     type SignatureEntry,