@gtkx/codegen 1.0.0-rc.4 → 1.1.0

package/src/docs/pipeline.ts

@@ -1,13 +1,20 @@
 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";
-import { createElementPageContext, type ElementPageContext, renderElementPage } from "./element-page.js";
+import { type ElementPageContext, renderElementPage } from "./element-page.js";
 import { elementSlug, firstSentence, namespaceOrder } from "./render.js";
 
 type DocsElementLink = {
@@ -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),
     }));
 
@@ -175,7 +208,7 @@ const generatePages = (options: DocsOptions, basePath: string, library: Library)
     const intrinsicElements = collectIntrinsicElementClasses(library);
     const byNamespace = groupElementsByNamespace(intrinsicElements);
     const linkByGlibName = buildElementLinks(intrinsicElements, basePath);
-    const pageContext = createElementPageContext(library, (glibName: string) => linkByGlibName.get(glibName));
+    const pageContext: ElementPageContext = { library, linkFor: (glibName) => linkByGlibName.get(glibName) };
     const pages: Page[] = [];
     const namespaces: DocsNamespace[] = [];
     const orderedNames = sortStringsBy(byNamespace.keys(), namespaceOrder);
@@ -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,31 +1,57 @@
-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";
 import type { Library } from "../gir/library.js";
 import type { GirNamespace } from "../gir/namespace.js";
 import type { GirCallable } from "../gir/parameter.js";
+import type { GirProperty } from "../gir/property.js";
 import type { TypeId } from "../gir/type-id.js";
+import type { JsDocDeprecation, JsDocParam, JsDocSpec } from "../writer/doc-tags.js";
 import { collectInheritedMethods, conflictRename } from "../analysis/inheritance.js";
 import { renderHandlerParameters, renderHandlerResultType } from "../analysis/param-structure.js";
 import { recordTypeTarget, renderBaseType, type TsTypeTarget } from "../analysis/ts-type.js";
-import { dedupeCallables, instanceScope, renderInstanceMethodSignature } from "../store/gi/callables.js";
+import {
+    dedupeCallables,
+    instanceMemberSpec,
+    instanceScope,
+    renderInstanceMethodSignature,
+} from "../store/gi/callables.js";
+import { annotationSpec, handlerSpec, selfHandlerSpec } from "../store/gi/doc-spec.js";
 import { methodExportName } from "../store/gi/method.js";
 import { ModuleContext } from "../writer/context.js";
+import { stripDocMedia } from "../writer/doc-tags.js";
 import { gtkDocToMarkdown } from "../writer/gtk-doc.js";
 
 type SignatureEntry = {
     name: string;
     signature: string;
     doc: string;
+    tags?: JsDocSpec | undefined;
 };
 
 type OriginSignatureEntry = SignatureEntry & { origin: string | undefined };
 
+type MetaDocEntry = {
+    name: string;
+    meta: string;
+    doc: string;
+    tags?: JsDocSpec | undefined;
+};
+
+type PropertyMetaOptions = {
+    type: string;
+    property: GirProperty;
+    accessNotes: string[];
+    origin: string | undefined;
+};
+
 const DOCS_DEFAULT_VALUES: Record<string, string> = { TRUE: "true", FALSE: "false", NULL: "null" };
 const FENCE_LINE = /^\s*(```|~~~)/;
 const HEADING_LINE = /^#{1,5}\s/;
 const LEADING_NAMESPACES = ["Gtk", "Adw"];
 const DOCS_SIGNATURE_NAMESPACE = "$docs";
+const WHITESPACE_RUN = /\s+/g;
 
 const docsTarget = (library: Library): TsTypeTarget =>
     recordTypeTarget(
@@ -63,12 +89,6 @@ const renderDocsSignalHandlerType = (library: Library, signal: GirCallable): str
 
 const docsDefaultValue = (value: string): string => DOCS_DEFAULT_VALUES[value] ?? value;
 
-const stripDocMedia = (markdown: string): string =>
-    markdown
-        .replaceAll(/<picture[\s\S]*?<\/picture>/g, "")
-        .replaceAll(/<video[\s\S]*?(?:<\/video>|\/>)/g, "")
-        .replaceAll(/<img[^>]*>/g, "");
-
 const demoteLine = (line: string, isInFence: boolean): { text: string; isInFence: boolean } => {
     if (FENCE_LINE.test(line)) {
         return { text: line, isInFence: !isInFence };
@@ -102,12 +122,15 @@ const stripMarkdown = (markdown: string): string =>
         .replaceAll(/```[\s\S]*?```/g, " ")
         .replaceAll(/`([^`]*)`/g, "$1")
         .replaceAll(/\[([^[\]]*)\]\([^)]*\)/g, "$1")
-        .replaceAll(/[*_#>]/g, "")
-        .replaceAll(/\s+/g, " ")
+        .replaceAll(/[*#>]/g, "")
+        .replaceAll(WHITESPACE_RUN, " ")
         .trim();
 
+const inlineMarkdown = (doc: string | undefined): string => docMarkdown(doc).replaceAll(WHITESPACE_RUN, " ").trim();
+const plainText = (doc: string | undefined): string => stripMarkdown(docMarkdown(doc));
+
 const firstSentence = (doc: string | undefined): string => {
-    const text = stripMarkdown(docMarkdown(doc));
+    const text = plainText(doc);
 
     if (text.length === 0) {
         return "";
@@ -138,16 +161,102 @@ const implementsLine = (names: string[]): string[] => {
 const joinSections = (sections: string[]): string =>
     `${sections.filter((section) => section.length > 0).join("\n\n")}\n`;
 
-const metaBlock = (name: string, meta: string, doc: string): string => {
-    const lines = [`### \`${name}\``, "", meta];
+const paramNotes = (params: JsDocParam[] | undefined): string[] => {
+    const entries = (params ?? [])
+        .map((param) => ({ name: param.name, text: inlineMarkdown(param.doc) }))
+        .filter((entry) => entry.text.length > 0);
+
+    if (entries.length === 0) {
+        return [];
+    }
+
+    const bullets = entries.map((entry) => `- \`${entry.name}\`: ${entry.text}`);
+
+    return [["**Parameters**", "", ...bullets].join("\n")];
+};
 
-    if (doc.length > 0) {
-        lines.push("", doc);
+const labelledNote = (label: string, text: string): string[] => (text.length === 0 ? [] : [`${label} ${text}`]);
+
+const deprecationNote = (deprecation: JsDocDeprecation | undefined): string[] => {
+    if (deprecation === undefined) {
+        return [];
+    }
+
+    const since = deprecation.since;
+    const heading = since === undefined ? "**Deprecated.**" : `**Deprecated since ${since}.**`;
+    const text = inlineMarkdown(deprecation.doc);
+    const body = text.length === 0 ? heading : `${heading} ${text}`;
+
+    return [`> ${body}`];
+};
+
+const sinceNote = (since: string | undefined): string[] =>
+    since === undefined || since.length === 0 ? [] : [`_Available since ${since}._`];
+
+const tagNotes = (spec: JsDocSpec | undefined): string[] => {
+    if (spec === undefined) {
+        return [];
+    }
+
+    return [
+        ...paramNotes(spec.params),
+        ...labelledNote("**Returns**", docMarkdown(spec.returns)),
+        ...labelledNote("**Throws**", inlineMarkdown(spec.throws)),
+        ...deprecationNote(spec.deprecated),
+        ...sinceNote(spec.since),
+    ];
+};
+
+const deprecationMeta = (annotations: GirAnnotations): string[] => {
+    if (!annotations.isDeprecated) {
+        return [];
+    }
+
+    const since = annotations.deprecatedSince;
+
+    return [since === undefined ? "deprecated" : `deprecated since ${since}`];
+};
+
+const annotationNotes = (annotations: GirAnnotations): string[] => tagNotes(annotationSpec(annotations));
+
+const signalTags = (signal: GirCallable, isSelfIncluded: boolean): JsDocSpec =>
+    isSelfIncluded ? selfHandlerSpec(signal) : handlerSpec(signal, signal.parameters);
+
+const metaBlock = (entry: MetaDocEntry): string => {
+    const lines = [`### \`${entry.name}\``, "", entry.meta];
+
+    for (const note of [entry.doc, ...tagNotes(entry.tags)]) {
+        if (note.length > 0) {
+            lines.push("", note);
+        }
     }
 
     return lines.join("\n");
 };
 
+const sortedMetaBlocks = (entries: MetaDocEntry[]): string[] =>
+    sortStringsBy(entries, (item) => item.name).map((item) => metaBlock(item));
+
+const propertyMetaLine = ({ type, property, accessNotes, origin }: PropertyMetaOptions): string => {
+    const meta = [`\`${type}\``];
+
+    if (property.defaultValue !== undefined) {
+        meta.push(`default \`${docsDefaultValue(property.defaultValue)}\``);
+    }
+
+    if (property.constructOnly) {
+        meta.push("construct-only");
+    }
+
+    meta.push(...accessNotes, ...deprecationMeta(property.annotations));
+
+    if (origin !== undefined) {
+        meta.push(`from \`${origin}\``);
+    }
+
+    return meta.join(" · ");
+};
+
 const signatureBlock = (name: string, signature: string, notes: string[]): string => {
     const lines = [`### \`${name}\``, "", `\`\`\`ts\n${signature}\n\`\`\``];
 
@@ -160,6 +269,9 @@ const signatureBlock = (name: string, signature: string, notes: string[]): strin
     return lines.join("\n");
 };
 
+const signatureEntryBlock = (entry: SignatureEntry, leadingNotes: string[] = []): string =>
+    signatureBlock(entry.name, entry.signature, [...leadingNotes, entry.doc, ...tagNotes(entry.tags)]);
+
 const namespaceOrder = (name: string): string => {
     const index = LEADING_NAMESPACES.indexOf(name);
 
@@ -171,16 +283,16 @@ const docsSignatureContext = (namespace: GirNamespace, library: Library): Module
 
 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,
-        ]),
+        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) =>
@@ -189,9 +301,7 @@ const classMethodEntries = (library: Library, namespace: GirNamespace, klass: Gi
 };
 
 const methodsSectionBlocks = (entries: SignatureEntry[], intro: string): string[] =>
-    entries.length === 0
-        ? []
-        : ["## Methods", intro, ...entries.map((item) => signatureBlock(item.name, item.signature, [item.doc]))];
+    entries.length === 0 ? [] : ["## Methods", intro, ...entries.map((item) => signatureEntryBlock(item))];
 
 const instanceMethodEntries = (
     signatureContext: ModuleContext,
@@ -200,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,
@@ -210,13 +320,7 @@ const instanceMethodEntries = (
 
     for (const method of deduped) {
         const nameOverride = rename(method);
-
-        const rendered = renderInstanceMethodSignature(
-            signatureContext,
-            { ...method, doc: undefined },
-            scope,
-            nameOverride,
-        );
+        const rendered = renderInstanceMethodSignature(signatureContext, method, scope, nameOverride);
 
         if (rendered === undefined) {
             continue;
@@ -224,32 +328,46 @@ const instanceMethodEntries = (
 
         entries.push({
             name: nameOverride ?? methodExportName(method),
-            signature: rendered.trim().replace(/;$/, ""),
+            signature: signatureText(rendered),
             doc: docMarkdown(method.doc),
+            tags: instanceMemberSpec(signatureContext, method, scope),
         });
     }
 
     return sortStringsBy(entries, (entry) => entry.name);
 };
 
+const signatureText = (rendered: string): string => {
+    const start = rendered.startsWith("/**") ? rendered.indexOf("*/") + 2 : 0;
+
+    return rendered.slice(start).trim().replace(/;$/, "");
+};
+
 export {
     renderDocsType,
     renderDocsSignalSignature,
     renderDocsSignalHandlerType,
-    docsDefaultValue,
+    annotationNotes,
+    deprecationMeta,
     docMarkdown,
     firstSentence,
     elementSlug,
     implementsLine,
     joinSections,
-    metaBlock,
+    plainText,
+    propertyMetaLine,
+    signalTags,
     signatureBlock,
+    signatureEntryBlock,
+    sortedMetaBlocks,
     namespaceOrder,
     docsSignatureContext,
     originSignatureBlocks,
     classMethodEntries,
     methodsSectionBlocks,
-    instanceMethodEntries,
+    qualifiedClassName,
+    tagNotes,
+    type MetaDocEntry,
     type SignatureEntry,
     type OriginSignatureEntry,
 };