@gtkx/codegen 1.0.0-rc.4 → 1.1.0

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";
@@ -9,7 +10,7 @@ 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 { 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 { docsSignatureContext, firstSentence, namespaceOrder } from "./render.js";
 import { type GiSymbolEntry, renderSymbolPage, type SymbolPageOptions } from "./symbol-page.js";
 
@@ -34,7 +35,16 @@ type ApiSymbolQuery = {
 };
 
 /** What an indexed symbol is: one of the GIR symbol kinds, or a JSX element. */
-type ApiSymbolKind = GiSymbolEntry["kind"] | "element";
+type ApiSymbolKind =
+    "alias" |
+    "callback" |
+    "class" |
+    "constant" |
+    "element" |
+    "enum" |
+    "function" |
+    "interface" |
+    "record";
 
 /** An indexed symbol, without its reference page. */
 type ApiSymbol = {
@@ -93,16 +103,30 @@ type ApiSearchOptions = {
     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[] = [
@@ -139,6 +163,9 @@ 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,
@@ -188,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[] => {
@@ -212,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[] => {
@@ -239,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,
         })),
@@ -248,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,
     })),
@@ -280,29 +307,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;
     }
 
@@ -355,12 +366,13 @@ class ApiReference {
     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();
     }
 
@@ -484,7 +496,7 @@ class ApiReference {
     private scoreEntries(
         query: string,
         namespaceFilter: string | undefined,
-        kinds: ApiSymbolKind[] | undefined,
+        kinds: Set<ApiSymbolKind> | undefined,
     ): ScoredEntry[] {
         const scored: ScoredEntry[] = [];
 
@@ -535,7 +547,7 @@ class ApiReference {
     /** 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 = query.kinds === undefined ? undefined : new Set(query.kinds);
+        const kinds = symbolKindSet(query.kinds);
 
         return this.entries
             .filter((entry) => isQueriedEntry(entry, namespaceFilter, kinds))
@@ -556,7 +568,7 @@ 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));

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,31 @@ 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,
+    qualifiedClassName,
     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 +51,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.`;
@@ -86,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}**`);
@@ -120,29 +113,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 +170,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 +184,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 +209,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 +217,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 +233,7 @@ const ownerSignalEntries = (
             name,
             signature: renderDocsSignalSignature(context.library, signal, selfType),
             doc: docMarkdown(signal.doc),
+            tags: signalTags(signal, true),
             origin: owner.origin,
         });
     }
@@ -235,7 +243,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));
@@ -260,12 +268,13 @@ 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),
         `# ${entry.glibName}`,
         docMarkdown(entry.klass.doc),
+        ...annotationNotes(entry.klass.annotations),
         importBlock(entry),
         ...hierarchySection(entry, context),
         ...propsSection(entry, context, selfType),
@@ -274,4 +283,4 @@ const renderElementPage = (entry: GlibNamedClass, context: ElementPageContext):
     ]);
 };
 
-export { createElementPageContext, renderElementPage, type ElementPageContext };
+export { renderElementPage, type ElementPageContext };

package/src/docs/handwritten-props.ts

@@ -0,0 +1,230 @@
+import type { ModuleExport } from "@gtkx/react/config";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+
+type HandwrittenProp = {
+    name: string;
+    type: string;
+    doc: string;
+};
+
+type AliasSite = {
+    sourceFile: ts.SourceFile;
+    declaration: ts.TypeAliasDeclaration;
+};
+
+type NamedBinding = ts.ImportSpecifier | ts.ExportSpecifier;
+
+const RESOLUTION_OPTIONS: ts.CompilerOptions = {
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    customConditions: ["source"],
+};
+
+const CONTAINING_FILE = fileURLToPath(import.meta.url);
+const WHITESPACE_RUN = /\s+/g;
+const propsByRef: Map<string, HandwrittenProp[]> = new Map();
+
+const moduleFileFor = (specifier: string, containingFile: string): string | undefined =>
+    ts.resolveModuleName(specifier, containingFile, RESOLUTION_OPTIONS, ts.sys).resolvedModule?.resolvedFileName;
+
+const parseModule = (filePath: string): ts.SourceFile =>
+    ts.createSourceFile(filePath, ts.sys.readFile(filePath) ?? "", ts.ScriptTarget.Latest, true);
+
+const specifierText = (node: ts.Expression | undefined): string | undefined =>
+    node !== undefined && ts.isStringLiteral(node) ? node.text : undefined;
+
+const boundName = (elements: readonly NamedBinding[], name: string): string | undefined => {
+    for (const element of elements) {
+        if (element.name.text === name) {
+            return (element.propertyName ?? element.name).text;
+        }
+    }
+
+    return undefined;
+};
+
+const findAliasInModule = (specifier: string, sourceFile: ts.SourceFile, name: string): AliasSite | undefined => {
+    const filePath = moduleFileFor(specifier, sourceFile.fileName);
+
+    return filePath === undefined ? undefined : findAlias(parseModule(filePath), name);
+};
+
+const importedAlias = (
+    statement: ts.ImportDeclaration,
+    sourceFile: ts.SourceFile,
+    name: string,
+): AliasSite | undefined => {
+    const bindings = statement.importClause?.namedBindings;
+    const specifier = specifierText(statement.moduleSpecifier);
+
+    if (specifier === undefined || bindings === undefined || !ts.isNamedImports(bindings)) {
+        return undefined;
+    }
+
+    const imported = boundName(bindings.elements, name);
+
+    return imported === undefined ? undefined : findAliasInModule(specifier, sourceFile, imported);
+};
+
+const exportedAlias = (
+    statement: ts.ExportDeclaration,
+    sourceFile: ts.SourceFile,
+    name: string,
+): AliasSite | undefined => {
+    const specifier = specifierText(statement.moduleSpecifier);
+
+    if (specifier === undefined) {
+        return undefined;
+    }
+
+    const clause = statement.exportClause;
+
+    if (clause === undefined) {
+        return findAliasInModule(specifier, sourceFile, name);
+    }
+
+    const exported = ts.isNamedExports(clause) ? boundName(clause.elements, name) : undefined;
+
+    return exported === undefined ? undefined : findAliasInModule(specifier, sourceFile, exported);
+};
+
+const statementAlias = (statement: ts.Statement, sourceFile: ts.SourceFile, name: string): AliasSite | undefined => {
+    if (ts.isTypeAliasDeclaration(statement)) {
+        return statement.name.text === name ? { sourceFile, declaration: statement } : undefined;
+    }
+
+    if (ts.isImportDeclaration(statement)) {
+        return importedAlias(statement, sourceFile, name);
+    }
+
+    return ts.isExportDeclaration(statement) ? exportedAlias(statement, sourceFile, name) : undefined;
+};
+
+const propType = (type: ts.TypeNode, sourceFile: ts.SourceFile): string => {
+    const parts: readonly ts.TypeNode[] = ts.isUnionTypeNode(type) ? type.types : [type];
+
+    return parts
+        .filter((part) => part.kind !== ts.SyntaxKind.UndefinedKeyword)
+        .map((part) => part.getText(sourceFile).replaceAll(WHITESPACE_RUN, " "))
+        .join(" | ");
+};
+
+const propDoc = (member: ts.TypeElement): string => {
+    const comments = ts
+        .getJSDocCommentsAndTags(member)
+        .map((node) => (ts.isJSDoc(node) ? ts.getTextOfJSDocComment(node.comment) : undefined));
+
+    return comments.filter((text) => text !== undefined).join(" ").replaceAll(WHITESPACE_RUN, " ").trim();
+};
+
+const propertyProp = (member: ts.PropertySignature, sourceFile: ts.SourceFile): HandwrittenProp | undefined => {
+    const { name, type } = member;
+
+    if (type === undefined || !(ts.isIdentifier(name) || ts.isStringLiteral(name))) {
+        return undefined;
+    }
+
+    return { name: name.text, type: propType(type, sourceFile), doc: propDoc(member) };
+};
+
+const indexProp = (member: ts.IndexSignatureDeclaration, sourceFile: ts.SourceFile): HandwrittenProp | undefined => {
+    const keyType = member.parameters[0]?.type;
+
+    if (keyType === undefined) {
+        return undefined;
+    }
+
+    return {
+        name: keyType.getText(sourceFile).replaceAll("`", ""),
+        type: propType(member.type, sourceFile),
+        doc: propDoc(member),
+    };
+};
+
+const memberProp = (member: ts.TypeElement, sourceFile: ts.SourceFile): HandwrittenProp | undefined => {
+    if (ts.isPropertySignature(member)) {
+        return propertyProp(member, sourceFile);
+    }
+
+    return ts.isIndexSignatureDeclaration(member) ? indexProp(member, sourceFile) : undefined;
+};
+
+const literalProps = (type: ts.TypeLiteralNode, sourceFile: ts.SourceFile): HandwrittenProp[] => {
+    const props: HandwrittenProp[] = [];
+
+    for (const member of type.members) {
+        const prop = memberProp(member, sourceFile);
+
+        if (prop !== undefined) {
+            props.push(prop);
+        }
+    }
+
+    return props;
+};
+
+const referenceProps = (type: ts.TypeReferenceNode, sourceFile: ts.SourceFile): HandwrittenProp[] => {
+    if (!ts.isIdentifier(type.typeName)) {
+        return [];
+    }
+
+    const site = findAlias(sourceFile, type.typeName.text);
+
+    return site === undefined ? [] : typeNodeProps(site.declaration.type, site.sourceFile);
+};
+
+const declaredProps = (ref: ModuleExport): HandwrittenProp[] => {
+    const filePath = moduleFileFor(ref.module, CONTAINING_FILE);
+
+    if (filePath === undefined) {
+        throw new Error(`Cannot resolve ${ref.module}, which declares the ${ref.export} element props`);
+    }
+
+    const site = findAlias(parseModule(filePath), ref.export);
+
+    if (site === undefined) {
+        throw new Error(`${ref.module} declares no type named ${ref.export}`);
+    }
+
+    return typeNodeProps(site.declaration.type, site.sourceFile);
+};
+
+const handwrittenPropsFor = (ref: ModuleExport): HandwrittenProp[] => {
+    const key = `${ref.module}#${ref.export}`;
+    const cached = propsByRef.get(key);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const props = declaredProps(ref);
+    propsByRef.set(key, props);
+
+    return props;
+};
+
+function findAlias(sourceFile: ts.SourceFile, name: string): AliasSite | undefined {
+    for (const statement of sourceFile.statements) {
+        const site = statementAlias(statement, sourceFile, name);
+
+        if (site !== undefined) {
+            return site;
+        }
+    }
+
+    return undefined;
+}
+
+function typeNodeProps(type: ts.TypeNode, sourceFile: ts.SourceFile): HandwrittenProp[] {
+    if (ts.isTypeLiteralNode(type)) {
+        return literalProps(type, sourceFile);
+    }
+
+    if (ts.isIntersectionTypeNode(type)) {
+        return type.types.flatMap((part) => typeNodeProps(part, sourceFile));
+    }
+
+    return ts.isTypeReferenceNode(type) ? referenceProps(type, sourceFile) : [];
+}
+
+export { handwrittenPropsFor, type HandwrittenProp };