@gtkx/codegen 1.0.0-rc.3 → 1.0.0

package/src/compile.ts

@@ -29,8 +29,10 @@ const BASE_COMPILER_OPTIONS = {
     noImplicitReturns: true,
     noFallthroughCasesInSwitch: true,
     allowUnreachableCode: false,
+    allowImportingTsExtensions: true,
     forceConsistentCasingInFileNames: true,
     resolveJsonModule: true,
+    rewriteRelativeImportExtensions: true,
     skipLibCheck: true,
     types: ["node"],
 };
@@ -47,7 +49,6 @@ const FORMAT_HOST: ts.FormatDiagnosticsHost = {
     getNewLine: () => "\n",
 };
 
-/** `@gtkx/codegen`'s own `node_modules`, which has `@types/node` plus the `@gtkx/*` deps the store typecheck needs. */
 const codegenModules = (): string => {
     const sourceDir = dirname(fileURLToPath(import.meta.url));
 
@@ -176,4 +177,4 @@ const checkModules = (params: { modules: SourceModule[]; resolveFrom: string; la
     }
 };
 
-export { compileProject, checkModules, type SourceModule, type CompileProjectParams };
+export { compileProject, checkModules, type SourceModule };

package/src/docs/api-reference.ts

@@ -6,55 +6,128 @@ import { Library } from "../gir/library.js";
 import { type GirNamespace, namespaceDirectory } from "../gir/namespace.js";
 import { dedupeCallables, isEmittableCallable } from "../store/gi/callables.js";
 import { namespaceFunctionExportName } from "../store/gi/function.js";
+import { type ElementProps, setElementProps } from "../store/jsx/element-prop-imports.js";
 import { collectIntrinsicElementClasses, type GlibNamedClass } from "../store/jsx/intrinsic-elements.js";
-import { createElementPageContext, type ElementPageContext, renderElementPage } from "./element-page.js";
+import { type OmittedProps, setOmittedProps } from "../store/jsx/omitted-props.js";
+import { type ElementPageContext, renderElementPage } from "./element-page.js";
 import { docsSignatureContext, firstSentence, namespaceOrder } from "./render.js";
 import { type GiSymbolEntry, renderSymbolPage, type SymbolPageOptions } from "./symbol-page.js";
 
+/** What to index and the element config the rendered pages reflect. */
 type ApiReferenceOptions = {
+    /** GIR library identifiers to load, such as `"Gtk-4.0"`; their dependencies are pulled in too. */
     libraries: string[];
+    /** Directories to search for `.gir` files. */
     girPath: string[];
+    /** Base props interfaces per element, as read by `readBuiltinElements`; without it pages miss them. */
+    props?: ElementProps;
+    /** GObject properties the project omits from generated props; without it pages show props that do not exist. */
+    omittedProps?: OmittedProps;
 };
 
-type ApiSymbolKind = GiSymbolEntry["kind"] | "element";
+/** Narrows an `ApiReference.symbols` enumeration. */
+type ApiSymbolQuery = {
+    /** GIR namespace to keep, matched case-insensitively; every namespace when omitted. */
+    namespace?: string;
+    /** Symbol kinds to keep; every kind when omitted. */
+    kinds?: ApiSymbolKind[];
+};
 
+/** What an indexed symbol is: one of the GIR symbol kinds, or a JSX element. */
+type ApiSymbolKind =
+    "alias" |
+    "callback" |
+    "class" |
+    "constant" |
+    "element" |
+    "enum" |
+    "function" |
+    "interface" |
+    "record";
+
+/** An indexed symbol, without its reference page. */
 type ApiSymbol = {
+    /** GIR namespace declaring the symbol, such as `"Gtk"`. */
     namespace: string;
+    /** Name within the namespace, which for an element is its GLib type name. */
     name: string;
+    /** Kind the reference groups and filters the symbol by, `"element"` for a JSX tag. */
     kind: ApiSymbolKind;
+    /** First sentence of the symbol's GIR documentation, elided past 220 characters and empty when it has none. */
     summary: string;
 };
 
+/** How much of one namespace the reference indexes. */
 type ApiNamespaceSummary = {
+    /** GIR namespace name, such as `"Gtk"`. */
     name: string;
+    /** The `@gtkx/gi` subpath the namespace's symbols are imported from. */
     importPath: string;
+    /** How many symbols other than JSX elements the namespace contributes. */
     symbols: number;
+    /** How many JSX elements the namespace contributes. */
     elements: number;
 };
 
+/** What an `ApiReference.lookup` found: a rendered page, several candidates for the name, or nothing. */
 type ApiLookupResult =
-    | { outcome: "page"; symbol: ApiSymbol; markdown: string } |
-    { outcome: "ambiguous"; candidates: ApiSymbol[] } |
-    { outcome: "notFound" };
-
+    | {
+        /** Discriminant selecting the variant. */
+        outcome: "page";
+        /** Index entry for the symbol the query resolved to. */
+        symbol: ApiSymbol;
+        /** The symbol's complete reference page, rendered as Markdown. */
+        markdown: string;
+    } |
+    {
+        /** Discriminant selecting the variant. */
+        outcome: "ambiguous";
+        /** Every symbol the name answers to, to be narrowed by namespace or kind. */
+        candidates: ApiSymbol[];
+    } |
+    {
+        /** Discriminant selecting the variant. */
+        outcome: "notFound";
+    };
+
+/** A fuzzy search over indexed symbol names. */
 type ApiSearchOptions = {
+    /** Text matched case-insensitively against each symbol's name and its qualified `Namespace.Name` form. */
     query: string;
+    /** GIR namespace to keep, matched case-insensitively; every namespace when omitted. */
     namespace?: string;
+    /** Symbol kinds to keep; every kind when omitted. */
     kinds?: ApiSymbolKind[];
+    /** Maximum number of results, 20 by default. */
     limit?: number;
 };
 
+/** An indexed JSX element, carrying the widget class its page renders from. */
 type ElementEntry = {
+    /** Discriminant marking the entry as a JSX element rather than a GIR symbol. */
     kind: "element";
+    /** GIR namespace declaring the widget class. */
     namespace: GirNamespace;
+    /** Element name, which is the class's GLib type name such as `GtkButton`. */
     name: string;
+    /** Documentation text carried by the widget class's GIR node. */
     doc: string | undefined;
+    /** The widget class the element is generated from. */
     element: GlibNamedClass;
 };
 
+/** Anything the index holds: a GIR symbol or a JSX element. */
 type SymbolEntry = GiSymbolEntry | ElementEntry;
-type ScoredEntry = { score: number; entry: SymbolEntry };
 
+/** A search hit: an indexed entry and how well its name answered the query. */
+type ScoredEntry = {
+    /** Match strength, ranked best first: an exact name, then a prefix, then a substring. */
+    score: number;
+    /** The entry that matched. */
+    entry: SymbolEntry;
+};
+
+/** Every kind the reference indexes, in the order a namespace overview groups its symbols. */
 const API_SYMBOL_KINDS: ApiSymbolKind[] = [
     "element",
     "class",
@@ -89,6 +162,35 @@ const compareNames = (a: string, b: string): number => {
     return a > b ? 1 : 0;
 };
 
+const symbolKindSet = (kinds: ApiSymbolKind[] | undefined): Set<ApiSymbolKind> | undefined =>
+    kinds === undefined ? undefined : new Set(kinds);
+
+const isQueriedEntry = (
+    entry: SymbolEntry,
+    namespaceFilter: string | undefined,
+    kinds: Set<ApiSymbolKind> | undefined,
+): boolean => {
+    if (namespaceFilter !== undefined && entry.namespace.name.toLowerCase() !== namespaceFilter) {
+        return false;
+    }
+
+    return kinds === undefined || kinds.has(entry.kind);
+};
+
+const compareApiSymbols = (a: ApiSymbol, b: ApiSymbol): number => {
+    const byNamespace = namespaceOrder(a.namespace).localeCompare(namespaceOrder(b.namespace));
+
+    return byNamespace === 0 ? a.name.localeCompare(b.name) : byNamespace;
+};
+
+/**
+ * Loads the GIR data for the given libraries and indexes every symbol and JSX element in it. The result is
+ * a read-only view: it generates no store and needs none, so a tool can explore the bindings a project would
+ * get without running codegen.
+ *
+ * @param options Which libraries to index, where to find them, and the project's element config.
+ * @returns The indexed reference.
+ */
 const loadApiReference = (options: ApiReferenceOptions): ApiReference => new ApiReference(options);
 
 const functionEntry = (
@@ -204,29 +306,13 @@ const narrowToExactMatches = (candidates: SymbolEntry[], trimmed: string, isQual
     return exact.length > 0 ? exact : candidates;
 };
 
-const isSearchFilterMatch = (
-    entry: SymbolEntry,
-    namespaceFilter: string | undefined,
-    kinds: ApiSymbolKind[] | undefined,
-): boolean => {
-    if (namespaceFilter !== undefined && entry.namespace.name.toLowerCase() !== namespaceFilter) {
-        return false;
-    }
-
-    if (kinds !== undefined && !kinds.includes(entry.kind)) {
-        return false;
-    }
-
-    return true;
-};
-
 const getScoredEntry = (
     entry: SymbolEntry,
     query: string,
     namespaceFilter: string | undefined,
-    kinds: ApiSymbolKind[] | undefined,
+    kinds: Set<ApiSymbolKind> | undefined,
 ): ScoredEntry | undefined => {
-    if (!isSearchFilterMatch(entry, namespaceFilter, kinds)) {
+    if (!isQueriedEntry(entry, namespaceFilter, kinds)) {
         return undefined;
     }
 
@@ -265,6 +351,7 @@ const searchScore = (entry: SymbolEntry, query: string): number => {
     return 0;
 };
 
+/** An index over the GIR data a project's bindings are generated from, queryable and renderable as Markdown. */
 class ApiReference {
     private library: Library;
     private libraries: string[];
@@ -275,13 +362,24 @@ class ApiReference {
     private byNamespace: Map<string, SymbolEntry[]> = new Map();
     private elementsByClass: Map<string, string> = new Map();
 
+    private props: ElementProps;
+    private omittedProps: OmittedProps;
+
+    /** Indexes every symbol and JSX element in the GIR data the options point at. */
     constructor(options: ApiReferenceOptions) {
         this.libraries = options.libraries;
+        this.props = options.props ?? {};
+        this.omittedProps = options.omittedProps ?? {};
         this.library = Library.load(options.libraries, options.girPath);
-        this.elementContext = createElementPageContext(this.library, (): string | undefined => undefined);
+        this.elementContext = { library: this.library, linkFor: (): string | undefined => undefined };
         this.buildIndex();
     }
 
+    private applyElementConfig(): void {
+        setElementProps(this.props);
+        setOmittedProps(this.omittedProps);
+    }
+
     private add(entry: SymbolEntry): void {
         this.entries.push(entry);
 
@@ -362,6 +460,8 @@ class ApiReference {
 
     private renderPage(entry: SymbolEntry): string {
         if (entry.kind === "element") {
+            this.applyElementConfig();
+
             return renderElementPage(entry.element, this.elementContext);
         }
 
@@ -395,7 +495,7 @@ class ApiReference {
     private scoreEntries(
         query: string,
         namespaceFilter: string | undefined,
-        kinds: ApiSymbolKind[] | undefined,
+        kinds: Set<ApiSymbolKind> | undefined,
     ): ScoredEntry[] {
         const scored: ScoredEntry[] = [];
 
@@ -410,10 +510,18 @@ class ApiReference {
         return scored;
     }
 
+    /** Paths of the `.gir` files the index was built from, including the ones pulled in as dependencies. */
     get girFiles(): string[] {
         return this.library.girFiles;
     }
 
+    /**
+     * Resolves a name to a single symbol and renders its reference page. The name may be bare (`Button`) or
+     * qualified (`Gtk.Button`), and is matched case-insensitively; a name several symbols answer to is
+     * reported as ambiguous rather than picked between.
+     *
+     * @param kind Restricts the match to one kind, which is how a class and its JSX element are told apart.
+     */
     lookup(query: string, kind?: ApiSymbolKind): ApiLookupResult {
         const trimmed = query.trim();
 
@@ -435,6 +543,21 @@ class ApiReference {
         return { outcome: "page", symbol: this.toApiSymbol(entry), markdown: this.renderPage(entry) };
     }
 
+    /** Every indexed symbol the query keeps, ordered by namespace (Gtk, then Adw, then alphabetically) and name. */
+    symbols(query: ApiSymbolQuery = {}): ApiSymbol[] {
+        const namespaceFilter = query.namespace?.toLowerCase();
+        const kinds = symbolKindSet(query.kinds);
+
+        return this.entries
+            .filter((entry) => isQueriedEntry(entry, namespaceFilter, kinds))
+            .map((entry) => this.toApiSymbol(entry))
+            .toSorted(compareApiSymbols);
+    }
+
+    /**
+     * Symbols whose name matches the query, best first: an exact name beats a prefix, which beats a
+     * substring, and shorter names win ties. An empty query matches nothing.
+     */
     search(options: ApiSearchOptions): ApiSymbol[] {
         const query = options.query.trim().toLowerCase();
 
@@ -444,12 +567,13 @@ class ApiReference {
 
         const limit = Math.max(1, Math.floor(options.limit ?? DEFAULT_SEARCH_LIMIT));
         const namespaceFilter = options.namespace?.toLowerCase();
-        const scored = this.scoreEntries(query, namespaceFilter, options.kinds);
+        const scored = this.scoreEntries(query, namespaceFilter, symbolKindSet(options.kinds));
         scored.sort(compareScoredEntries);
 
         return scored.slice(0, limit).map((item) => this.toApiSymbol(item.entry));
     }
 
+    /** A summary of every indexed namespace, ordered Gtk, Adw, then alphabetically. */
     namespaces(): ApiNamespaceSummary[] {
         const summaries = [...this.byNamespace].map(([name, entries]) => ({
             name,
@@ -461,6 +585,10 @@ class ApiReference {
         return sortStringsBy(summaries, (summary) => namespaceOrder(summary.name));
     }
 
+    /**
+     * Sorted names of everything a namespace contributes, JSX elements included. The namespace is matched
+     * case-insensitively, and an unindexed one yields an empty array.
+     */
     symbolNames(namespaceName: string): string[] {
         const namespace = this.findNamespace(namespaceName);
 
@@ -473,6 +601,7 @@ class ApiReference {
         return sortStrings(entries.map((entry) => entry.name));
     }
 
+    /** Renders the reference's Markdown landing page: every namespace, its import path, and its totals. */
     overview(): string {
         const rows = this.namespaces().map(
             (summary) =>
@@ -500,6 +629,10 @@ class ApiReference {
         ].join("\n");
     }
 
+    /**
+     * Renders one namespace's Markdown page: its import line and its symbol names grouped by kind. The
+     * namespace is matched case-insensitively, and an unindexed one yields undefined.
+     */
     namespaceOverview(name: string): string | undefined {
         const namespace = this.findNamespace(name);
 
@@ -549,4 +682,5 @@ export {
     type ApiNamespaceSummary,
     type ApiLookupResult,
     type ApiSearchOptions,
+    type ApiSymbolQuery,
 };

package/src/docs/element-page.ts

@@ -1,11 +1,12 @@
-import { sortStringsBy, toCamelIdentifier, upperFirst } from "@gtkx/utils";
+import { toCamelIdentifier, upperFirst } from "@gtkx/utils";
 import type { GirClass } from "../gir/class.js";
 import type { Library } from "../gir/library.js";
+import type { HandwrittenProp } from "./handwritten-props.js";
 import { ancestorChain } from "../gir/ancestry.js";
 import { type GirNamespace, namespaceDirectory } from "../gir/namespace.js";
 import { type GirProperty, isConstructableProperty } from "../gir/property.js";
+import { annotationSpec } from "../store/gi/doc-spec.js";
 import { elementPropTypeFor } from "../store/jsx/element-prop-imports.js";
-import { buildGirIndex, type GirIndex } from "../store/jsx/gir-index.js";
 import {
     getGlibName,
     type GlibNamedClass,
@@ -15,23 +16,30 @@ import {
 } from "../store/jsx/intrinsic-elements.js";
 import { isOmittedProp } from "../store/jsx/omitted-props.js";
 import { isObjectProp } from "../store/jsx/props.js";
+import { handwrittenPropsFor } from "./handwritten-props.js";
 import {
+    annotationNotes,
     classMethodEntries,
     docMarkdown,
-    docsDefaultValue,
     firstSentence,
     implementsLine,
     joinSections,
-    metaBlock,
+    type MetaDocEntry,
     methodsSectionBlocks,
     originSignatureBlocks,
+    type OriginSignatureEntry,
+    propertyMetaLine,
     renderDocsSignalSignature,
     renderDocsType,
+    signalTags,
+    sortedMetaBlocks,
 } from "./render.js";
 
+/** Shared state an element's reference page renders from. */
 type ElementPageContext = {
+    /** Parsed GIR the element, its ancestors, and the interfaces it implements are read from. */
     library: Library;
-    girIndex: GirIndex;
+    /** Resolves a GLib type name to the URL of its page, undefined when it has none. */
     linkFor: (glibName: string) => string | undefined;
 };
 
@@ -42,24 +50,6 @@ type MemberOwner = {
     glibName: string | undefined;
 };
 
-type PropEntry = {
-    name: string;
-    meta: string;
-    doc: string;
-};
-
-type SignalEntry = {
-    name: string;
-    signature: string;
-    doc: string;
-    origin: string | undefined;
-};
-
-const createElementPageContext = (
-    library: Library,
-    linkFor: (glibName: string) => string | undefined,
-): ElementPageContext => ({ library, girIndex: buildGirIndex(library), linkFor });
-
 const frontmatter = (entry: GlibNamedClass): string => {
     const sentence = firstSentence(entry.klass.doc);
     const description = sentence.length > 0 ? sentence : `API reference for the ${entry.glibName} element.`;
@@ -120,29 +110,45 @@ const propertyEntry = (
     owner: MemberOwner,
     property: GirProperty,
     jsName: string,
-): PropEntry => {
+): MetaDocEntry => {
     const isObject = isObjectProp(context.library, property);
     const baseType = renderDocsType(context.library, property.type, false);
     const type = isObject ? `${baseType} | ReactElement` : baseType;
-    const meta: string[] = [`\`${type}\``];
 
-    if (property.defaultValue !== undefined) {
-        meta.push(`default \`${docsDefaultValue(property.defaultValue)}\``);
-    }
+    const accessNotes = isConstructableProperty(property)
+        ? []
+        : [`read-only, observe with \`onNotify${upperFirst(jsName)}\``];
 
-    if (property.constructOnly) {
-        meta.push("construct-only");
-    }
+    return {
+        name: jsName,
+        meta: propertyMetaLine({ type, property, accessNotes, origin: owner.origin }),
+        doc: docMarkdown(property.doc),
+        tags: annotationSpec(property.annotations),
+    };
+};
 
-    if (!isConstructableProperty(property)) {
-        meta.push(`read-only, observe with \`onNotify${upperFirst(jsName)}\``);
+const handwrittenPropMeta = (prop: HandwrittenProp, owner: MemberOwner): string =>
+    [`\`${prop.type}\``, ...(owner.origin === undefined ? [] : [`from \`${owner.origin}\``])].join(" · ");
+
+const handwrittenPropEntries = (owner: MemberOwner, seen: Set<string>): MetaDocEntry[] => {
+    const declared = owner.glibName === undefined ? undefined : elementPropTypeFor(owner.glibName);
+
+    if (declared === undefined) {
+        return [];
     }
 
-    if (owner.origin !== undefined) {
-        meta.push(`from \`${owner.origin}\``);
+    const entries: MetaDocEntry[] = [];
+
+    for (const prop of handwrittenPropsFor(declared)) {
+        if (seen.has(prop.name)) {
+            continue;
+        }
+
+        seen.add(prop.name);
+        entries.push({ name: prop.name, meta: handwrittenPropMeta(prop, owner), doc: prop.doc });
     }
 
-    return { name: jsName, meta: meta.join(" · "), doc: docMarkdown(property.doc) };
+    return entries;
 };
 
 const propJsName = (property: GirProperty, owner: MemberOwner, seen: Set<string>): string | undefined => {
@@ -161,8 +167,8 @@ const propJsName = (property: GirProperty, owner: MemberOwner, seen: Set<string>
     return jsName;
 };
 
-const ownerPropEntries = (context: ElementPageContext, owner: MemberOwner, seen: Set<string>): PropEntry[] => {
-    const entries: PropEntry[] = [];
+const ownerPropEntries = (context: ElementPageContext, owner: MemberOwner, seen: Set<string>): MetaDocEntry[] => {
+    const entries: MetaDocEntry[] = [...handwrittenPropEntries(owner, seen)];
 
     for (const property of owner.klass.properties) {
         const jsName = propJsName(property, owner, seen);
@@ -175,8 +181,8 @@ const ownerPropEntries = (context: ElementPageContext, owner: MemberOwner, seen:
     return entries;
 };
 
-const propertyEntries = (entry: GlibNamedClass, context: ElementPageContext, seen: Set<string>): PropEntry[] => {
-    const entries: PropEntry[] = [];
+const propertyEntries = (entry: GlibNamedClass, context: ElementPageContext, seen: Set<string>): MetaDocEntry[] => {
+    const entries: MetaDocEntry[] = [];
 
     for (const owner of memberOwners(entry, context)) {
         entries.push(...ownerPropEntries(context, owner, seen));
@@ -200,9 +206,7 @@ const propsSection = (entry: GlibNamedClass, context: ElementPageContext, selfTy
         return ["## Props", intro];
     }
 
-    const sorted = sortStringsBy(entries, (item) => item.name);
-
-    return ["## Props", intro, ...sorted.map((item) => metaBlock(item.name, item.meta, item.doc))];
+    return ["## Props", intro, ...sortedMetaBlocks(entries)];
 };
 
 const ownerSignalEntries = (
@@ -210,8 +214,8 @@ const ownerSignalEntries = (
     owner: MemberOwner,
     selfType: string,
     seen: Set<string>,
-): SignalEntry[] => {
-    const entries: SignalEntry[] = [];
+): OriginSignatureEntry[] => {
+    const entries: OriginSignatureEntry[] = [];
 
     for (const signal of owner.klass.signals) {
         const name = signalHandlerName(signal.name);
@@ -226,6 +230,7 @@ const ownerSignalEntries = (
             name,
             signature: renderDocsSignalSignature(context.library, signal, selfType),
             doc: docMarkdown(signal.doc),
+            tags: signalTags(signal, true),
             origin: owner.origin,
         });
     }
@@ -235,7 +240,7 @@ const ownerSignalEntries = (
 
 const signalsSection = (entry: GlibNamedClass, context: ElementPageContext, selfType: string): string[] => {
     const seen: Set<string> = new Set();
-    const entries: SignalEntry[] = [];
+    const entries: OriginSignatureEntry[] = [];
 
     for (const owner of memberOwners(entry, context)) {
         entries.push(...ownerSignalEntries(context, owner, selfType, seen));
@@ -266,6 +271,7 @@ const renderElementPage = (entry: GlibNamedClass, context: ElementPageContext):
         frontmatter(entry),
         `# ${entry.glibName}`,
         docMarkdown(entry.klass.doc),
+        ...annotationNotes(entry.klass.annotations),
         importBlock(entry),
         ...hierarchySection(entry, context),
         ...propsSection(entry, context, selfType),
@@ -274,4 +280,4 @@ const renderElementPage = (entry: GlibNamedClass, context: ElementPageContext):
     ]);
 };
 
-export { createElementPageContext, renderElementPage, type ElementPageContext };
+export { renderElementPage, type ElementPageContext };