@gtkx/codegen 1.0.0-rc.3 → 1.0.0

package/src/khronos/render.ts

@@ -1,8 +1,11 @@
-import { lowerFirst, sourceStringLiteral, toCamelIdentifier } from "@gtkx/utils";
+import { sourceStringLiteral, toCamelIdentifier } from "@gtkx/utils";
+import type { GlDocContext } from "./doc-context.js";
 import type { CommandPlan, GlScalar, ReturnPlan } from "./plan.js";
+import type { GlSymbolProvenance } from "./select.js";
 import { tBind, tInlineStruct, tRef, tString, tUint8, tVoid } from "../analysis/descriptor.js";
-import { type OutArg, planArgs, scalarAliasOrGroup, scalarPrefixArgs, trackInto } from "./args.js";
-import { commandJsDoc, inParamDocLine, singularJsDoc } from "./jsdoc.js";
+import { type InArg, type OutArg, planArgs, returnPlanTsType, scalarPrefixArgs, trackInto } from "./args.js";
+import { commandJsDoc, derivedJsDoc, inParamDocLine } from "./jsdoc.js";
+import { commandExportName } from "./notes.js";
 
 type RenderedCommand = {
     exportName: string;
@@ -10,6 +13,12 @@ type RenderedCommand = {
     declaration: string;
 };
 
+type SingularContext = {
+    plan: CommandPlan & { isOk: true };
+    provenance: GlSymbolProvenance;
+    docs: GlDocContext;
+};
+
 type EmittedReturn = {
     tsType: string;
     descriptor: string;
@@ -34,9 +43,6 @@ const glBind = (name: string, argList: string, returnType: string): string =>
         returnType,
     });
 
-const commandExportName = (name: string): string =>
-    toCamelIdentifier(name.startsWith("gl") ? lowerFirst(name.slice(2)) : name);
-
 const singularize = (plural: string): string =>
     plural.endsWith("ies") ? `${plural.slice(0, -3)}y` : plural.replace(/s$/, "");
 
@@ -48,32 +54,27 @@ const buildEmittedReturn = (
     returnGroup: string | undefined,
     usedTypes: Set<string>,
 ): EmittedReturn => {
-    const track = trackInto(usedTypes);
+    const tsType = trackInto(usedTypes)(returnPlanTsType(plan, returnGroup));
+    const cast = (call: string): string => `${call} as ${tsType}`;
 
     switch (plan.kind) {
         case "void": {
-            return { tsType: "void", descriptor: tVoid };
+            return { tsType, descriptor: tVoid };
         }
         case "scalar": {
-            const alias = track(scalarAliasOrGroup(plan.scalar, returnGroup));
-
-            return { tsType: alias, descriptor: plan.scalar.descriptor, expr: (call) => `${call} as ${alias}` };
+            return { tsType, descriptor: plan.scalar.descriptor, expr: cast };
         }
         case "boolean": {
-            return { tsType: "boolean", descriptor: tUint8, expr: (call) => `(${call} as number) !== 0` };
+            return { tsType, descriptor: tUint8, expr: (call) => `(${call} as number) !== 0` };
         }
         case "string": {
-            return { tsType: "string", descriptor: tString("borrowed"), expr: (call) => `${call} as string` };
+            return { tsType, descriptor: tString("borrowed"), expr: cast };
         }
         case "sync": {
-            return { tsType: track("GLsync"), descriptor: tInlineStruct(), expr: (call) => `${call} as GLsync` };
+            return { tsType, descriptor: tInlineStruct(), expr: cast };
         }
         case "opaque-pointer": {
-            return {
-                tsType: track("GLpointer"),
-                descriptor: tInlineStruct(),
-                expr: (call) => `${call} as GLpointer`,
-            };
+            return { tsType, descriptor: tInlineStruct(), expr: cast };
         }
     }
 };
@@ -117,19 +118,20 @@ const returnStatements = (call: string, returned: EmittedReturn, outs: OutArg[])
 };
 
 const renderCommand = (
-    plan: CommandPlan & { ok: true },
-    feature: string,
+    plan: CommandPlan & { isOk: true },
+    provenance: GlSymbolProvenance,
     usedTypes: Set<string>,
+    docs: GlDocContext,
 ): RenderedCommand => {
     const { command } = plan;
     const exportName = commandExportName(command.name);
     const { args, ins, outs } = planArgs(plan, usedTypes);
     const returned = buildEmittedReturn(plan.returnPlan, command.returnGroup, usedTypes);
     const signature = ins.map((arg) => `${arg.name}: ${arg.tsType}`).join(", ");
-    const argNames = args.map((arg) => (arg.out ? arg.cellName : arg.name)).join(", ");
+    const argNames = args.map((arg) => (arg.isOut ? arg.cellName : arg.name)).join(", ");
     const descriptors = renderDescriptorList(args.map((arg) => arg.descriptor));
     const tsReturn = returnTsType(returned, outs);
-    const jsDoc = commandJsDoc({ command, feature, ins, outs, returnPlan: plan.returnPlan });
+    const jsDoc = commandJsDoc({ plan, provenance, ins, outs, docs });
     const seeds = outs.map((out) => out.seed);
     const bindExpression = glBind(command.name, descriptors, returned.descriptor);
     const isInline = plan.params.some((paramPlan) => paramPlan.kind === "string-out");
@@ -150,15 +152,17 @@ const renderCommand = (
     };
 };
 
-const singularCommandJsDoc = (
-    plan: CommandPlan & { ok: true },
-    feature: string,
-    summary: string,
-    body: string[],
-): string => singularJsDoc({ commandName: plan.command.name, feature, summary, body });
+const singularCommandJsDoc = (context: SingularContext, summary: string, body: string[]): string =>
+    derivedJsDoc({
+        command: context.plan.command,
+        provenance: context.provenance,
+        docs: context.docs,
+        summary,
+        body,
+    });
 
 const genSingularScalars = (
-    plan: CommandPlan & { ok: true },
+    plan: CommandPlan & { isOk: true },
 ): { countScalar: GlScalar; outScalar: GlScalar; lenParamName: string } | undefined => {
     const countPlan = plan.params.at(-2);
 
@@ -175,7 +179,7 @@ const genSingularScalars = (
     return { countScalar: countPlan.scalar, outScalar: outPlan.scalar, lenParamName: outPlan.lenParamName };
 };
 
-const genSingularObjectClass = (plan: CommandPlan & { ok: true }, lenParamName: string): string | undefined => {
+const genSingularObjectClass = (plan: CommandPlan & { isOk: true }, lenParamName: string): string | undefined => {
     const countParam = plan.command.params[plan.params.length - 2];
     const outParam = plan.command.params[plan.params.length - 1];
 
@@ -190,7 +194,7 @@ const genSingularObjectClass = (plan: CommandPlan & { ok: true }, lenParamName:
     return outParam.objectClass;
 };
 
-const genSingularShape = (plan: CommandPlan & { ok: true }): GenSingularShape | undefined => {
+const genSingularShape = (plan: CommandPlan & { isOk: true }): GenSingularShape | undefined => {
     const scalars = genSingularScalars(plan);
 
     if (scalars === undefined) {
@@ -206,10 +210,25 @@ const genSingularShape = (plan: CommandPlan & { ok: true }): GenSingularShape |
     return { countScalar: scalars.countScalar, outScalar: scalars.outScalar, objectClass };
 };
 
+const genSingularJsDoc = (context: SingularContext, prefix: InArg[], shape: GenSingularShape): string => {
+    const { command } = context.plan;
+
+    return singularCommandJsDoc(
+        context,
+        `Returns one ${shape.objectClass} object name via ` +
+        `\`${command.name}(${prefix.length > 0 ? "..., " : ""}1, ...)\`.`,
+        [
+            ...prefix.map((arg) => inParamDocLine(context.plan, arg, context.docs)),
+            ` * @returns \`${shape.outScalar.tsAlias}\`, object class \`${shape.objectClass}\``,
+        ],
+    );
+};
+
 const deriveGenSingular = (
-    plan: CommandPlan & { ok: true },
-    feature: string,
+    plan: CommandPlan & { isOk: true },
+    provenance: GlSymbolProvenance,
     usedTypes: Set<string>,
+    docs: GlDocContext,
 ): RenderedCommand | undefined => {
     if (!GEN_FAMILY.test(plan.command.name)) {
         return undefined;
@@ -227,21 +246,14 @@ const deriveGenSingular = (
         return undefined;
     }
 
-    const { countScalar, outScalar, objectClass } = shape;
+    const { countScalar, outScalar } = shape;
     const exportName = singularize(commandExportName(plan.command.name));
     const bindingName = `${plan.command.name}Single`;
     const descriptors = [...prefix.map((arg) => arg.descriptor), countScalar.descriptor, tRef(outScalar.descriptor)];
     usedTypes.add(outScalar.tsAlias);
     const signature = prefix.map((arg) => `${arg.name}: ${arg.tsType}`).join(", ");
     const callArgs = [...prefix.map((arg) => arg.name), "1", "out"].join(", ");
-
-    const jsDoc = singularCommandJsDoc(
-        plan,
-        feature,
-        `Returns one ${objectClass} object name via ` +
-        `\`${plan.command.name}(${prefix.length > 0 ? "..., " : ""}1, ...)\`.`,
-        [...prefix.map((arg) => inParamDocLine(plan.command, arg)), ` * @returns The new ${objectClass} object name`],
-    );
+    const jsDoc = genSingularJsDoc({ plan, provenance, docs }, prefix, shape);
 
     const body = ["    const out = { value: 0 };", `    ${bindingName}(${callArgs});`, "    return out.value;"].join(
         "\n",
@@ -256,7 +268,7 @@ const deriveGenSingular = (
     };
 };
 
-const deleteSingularAlias = (plan: CommandPlan & { ok: true }): string | undefined => {
+const deleteSingularAlias = (plan: CommandPlan & { isOk: true }): string | undefined => {
     if (plan.params.length !== 2) {
         return undefined;
     }
@@ -274,7 +286,7 @@ const deleteSingularAlias = (plan: CommandPlan & { ok: true }): string | undefin
     return arrayPlan.scalar.tsAlias;
 };
 
-const deleteSingularObjectClass = (plan: CommandPlan & { ok: true }): string | undefined => {
+const deleteSingularObjectClass = (plan: CommandPlan & { isOk: true }): string | undefined => {
     const [countParam, arrayParam] = plan.command.params;
 
     if (countParam === undefined || arrayParam === undefined) {
@@ -289,9 +301,10 @@ const deleteSingularObjectClass = (plan: CommandPlan & { ok: true }): string | u
 };
 
 const deriveDeleteSingular = (
-    plan: CommandPlan & { ok: true },
-    feature: string,
+    plan: CommandPlan & { isOk: true },
+    provenance: GlSymbolProvenance,
     usedTypes: Set<string>,
+    docs: GlDocContext,
 ): RenderedCommand | undefined => {
     if (!DELETE_FAMILY.test(plan.command.name)) {
         return undefined;
@@ -313,10 +326,9 @@ const deriveDeleteSingular = (
     const exportName = singularize(commandExportName(plan.command.name));
 
     const jsDoc = singularCommandJsDoc(
-        plan,
-        feature,
+        { plan, provenance, docs },
         `Deletes one ${objectClass} object name via \`${plan.command.name}(1, ...)\`.`,
-        [` * @param name - The ${objectClass} object name to delete`],
+        [` * @param name - \`${scalarAlias}\`, object class \`${objectClass}\``],
     );
 
     return {

package/src/khronos/select.ts

@@ -1,3 +1,4 @@
+import { sortStringsBy } from "@gtkx/utils";
 import type { GlEnum, GlFeature, GlInterfaceBlock, GlRegistry } from "./model.js";
 
 type GlProfile = "core";
@@ -8,60 +9,94 @@ type GlSelection = {
     profile: GlProfile;
 };
 
+type GlSymbolKind = "command" | "enum";
+
+type GlRemoval = {
+    feature: string;
+    comment?: string;
+};
+
+type GlSymbolProvenance = {
+    feature: string;
+    requireComment?: string;
+    removals: GlRemoval[];
+};
+
+type GlRemovedSymbol = {
+    name: string;
+    kind: GlSymbolKind;
+    feature: string;
+    comment?: string;
+};
+
 type GlSubset = {
-    commands: Map<string, string>;
-    enums: Map<string, string>;
+    commands: Map<string, GlSymbolProvenance>;
+    enums: Map<string, GlSymbolProvenance>;
+    removed: GlRemovedSymbol[];
 };
 
-const isBlockApplicable = (block: GlInterfaceBlock, selection: GlSelection): boolean =>
-    block.profile === undefined || block.profile === selection.profile;
+type SelectionState = GlSubset & {
+    history: Map<string, GlRemoval[]>;
+};
 
-const addMissing = (target: Map<string, string>, names: string[], value: string): void => {
-    for (const name of names) {
-        if (!target.has(name)) {
-            target.set(name, value);
-        }
-    }
+type MemberContext = {
+    feature: GlFeature;
+    block: GlInterfaceBlock;
+    kind: GlSymbolKind;
 };
 
-const applyRequires = (
-    feature: GlFeature,
-    selection: GlSelection,
-    commands: Map<string, string>,
-    enums: Map<string, string>,
-): void => {
-    for (const block of feature.requires) {
-        if (!isBlockApplicable(block, selection)) {
-            continue;
-        }
+const isBlockApplicable = (block: GlInterfaceBlock, selection: GlSelection): boolean =>
+    (block.profile === undefined || block.profile === selection.profile) &&
+    (block.api === undefined || block.api === selection.api);
+
+const targetFor = (state: SelectionState, kind: GlSymbolKind): Map<string, GlSymbolProvenance> =>
+    kind === "command" ? state.commands : state.enums;
 
-        addMissing(commands, block.commands, feature.name);
-        addMissing(enums, block.enums, feature.name);
+const commentEntry = (comment: string | undefined): { comment?: string } =>
+    comment === undefined ? {} : { comment };
+
+const requireMember = (state: SelectionState, name: string, context: MemberContext): void => {
+    const target = targetFor(state, context.kind);
+
+    if (target.has(name)) {
+        return;
     }
+
+    const { block, feature } = context;
+
+    target.set(name, {
+        feature: feature.name,
+        ...(block.comment !== undefined && { requireComment: block.comment }),
+        removals: [...(state.history.get(name) ?? [])],
+    });
 };
 
-const removeBlock = (block: GlInterfaceBlock, commands: Map<string, string>, enums: Map<string, string>): void => {
-    for (const name of block.commands) {
-        commands.delete(name);
-    }
+const removeMember = (state: SelectionState, name: string, context: MemberContext): void => {
+    const { block, feature, kind } = context;
+    const removal: GlRemoval = { feature: feature.name, ...commentEntry(block.comment) };
+    targetFor(state, kind).delete(name);
+    state.history.set(name, [...(state.history.get(name) ?? []), removal]);
+    state.removed.push({ name, kind, ...removal });
+};
+
+const applyMembers = (state: SelectionState, names: string[], context: MemberContext): void => {
+    const apply = context.block.kind === "require" ? requireMember : removeMember;
 
-    for (const name of block.enums) {
-        enums.delete(name);
+    for (const name of names) {
+        apply(state, name, context);
     }
 };
 
-const applyRemoves = (
-    feature: GlFeature,
-    selection: GlSelection,
-    commands: Map<string, string>,
-    enums: Map<string, string>,
-): void => {
-    for (const block of feature.removes) {
-        if (!isBlockApplicable(block, selection)) {
-            continue;
-        }
+const applyBlock = (state: SelectionState, feature: GlFeature, block: GlInterfaceBlock): void => {
+    applyMembers(state, block.commands, { feature, block, kind: "command" });
+    applyMembers(state, block.enums, { feature, block, kind: "enum" });
+};
 
-        removeBlock(block, commands, enums);
+const applyFeature = (state: SelectionState, feature: GlFeature, selection: GlSelection): void => {
+    for (const block of feature.blocks) {
+        if (isBlockApplicable(block, selection)) {
+            applyBlock(state, feature, block);
+        }
     }
 };
 
@@ -70,22 +105,28 @@ const selectSubset = (registry: GlRegistry, selection: GlSelection): GlSubset =>
         .filter((feature) => feature.api === selection.api && feature.number <= selection.version)
         .toSorted((a, b) => a.number - b.number);
 
-    const commands: Map<string, string> = new Map();
-    const enums: Map<string, string> = new Map();
-
-    for (const feature of features) {
-        applyRequires(feature, selection, commands, enums);
-    }
+    const state: SelectionState = {
+        commands: new Map(),
+        enums: new Map(),
+        removed: [],
+        history: new Map(),
+    };
 
     for (const feature of features) {
-        applyRemoves(feature, selection, commands, enums);
+        applyFeature(state, feature, selection);
     }
 
-    return { commands, enums };
+    return {
+        commands: state.commands,
+        enums: state.enums,
+        removed: sortStringsBy(state.removed, (entry) => entry.name),
+    };
 };
 
-const resolveEnum = (registry: GlRegistry, name: string): GlEnum => {
-    const found = registry.enums.find((candidate) => candidate.name === name);
+const resolveEnum = (registry: GlRegistry, name: string, api: string): GlEnum => {
+    const found = registry.enums.find(
+        (candidate) => candidate.name === name && (candidate.api === undefined || candidate.api === api),
+    );
 
     if (found === undefined) {
         throw new Error(`Enum token ${name} has no definition in the registry`);
@@ -94,4 +135,4 @@ const resolveEnum = (registry: GlRegistry, name: string): GlEnum => {
     return found;
 };
 
-export { selectSubset, resolveEnum, type GlSelection };
+export { selectSubset, resolveEnum, type GlRemoval, type GlSelection, type GlSubset, type GlSymbolProvenance };

package/src/react/element-config.ts

@@ -2,15 +2,18 @@ import type { ModuleExport } from "@gtkx/react/config";
 import { readdirSync } from "node:fs";
 import type { OmittedProps } from "../store/jsx/omitted-props.js";
 
-/** The codegen-relevant subset of a React element config; behaviors are ignored at codegen time. */
-type BuiltinElement = { component?: ModuleExport; lazy?: boolean; props?: ModuleExport; omitProps?: string[] };
+type BuiltinElement = { component?: ModuleExport; isLazy?: boolean; props?: ModuleExport; omittedProps?: string[] };
 
 /** The framework's built-in element config, split into the maps codegen consumes. */
 type BuiltinElements = {
+    /** Component wrappers keyed by GLib type name; an element without one inherits its nearest ancestor's. */
     components: Record<string, ModuleExport>;
+    /** GLib type names with no GObject of their own, exported as elements that drop their construct-only props. */
     lazyElements: string[];
+    /** Base props interfaces the generated element props extend, keyed by GLib type name. */
     props: Record<string, ModuleExport>;
-    omitProps: OmittedProps;
+    /** Props left out of the generated element props, keyed by GLib type name. */
+    omittedProps: OmittedProps;
 };
 
 const CONFIG_ENTRYPOINT = "config";
@@ -29,10 +32,6 @@ const presentNamespaceDirs = (giStoreDir: string): Set<string> => {
     return dirs;
 };
 
-/**
- * The clean, reconciler-free `@gtkx/react` config entrypoints to import: the base `config` entry plus
- * each namespace's `<ns>/config` entry whose GIR namespace is present in the gi store.
- */
 const configEntrypoints = (reactSubexports: string[], present: Set<string>): string[] =>
     reactSubexports.filter((sub) => {
         if (sub === CONFIG_ENTRYPOINT) {
@@ -61,30 +60,34 @@ const applyBuiltinElement = (target: BuiltinElements, type: string, config: Buil
         target.props[type] = config.props;
     }
 
-    if (config.omitProps !== undefined) {
-        target.omitProps[type] = [...(target.omitProps[type] ?? []), ...config.omitProps];
+    if (config.omittedProps !== undefined) {
+        target.omittedProps[type] = [...(target.omittedProps[type] ?? []), ...config.omittedProps];
     }
 
-    if (config.lazy === true) {
+    if (config.isLazy === true) {
         target.lazyElements.push(type);
     }
 };
 
-/**
- * Reads the framework's built-in element config by importing the freshly linked `@gtkx/react` config
- * entrypoints. These are reconciler-free, so importing them resolves `@gtkx/gi` but never `virtual:gtkx-config`;
- * it must run only after the gi store has been linked.
- */
 const collectBuiltinElements = (target: BuiltinElements, elements: Record<string, BuiltinElement>): void => {
     for (const [type, config] of Object.entries(elements)) {
         applyBuiltinElement(target, type, config);
     }
 };
 
+/**
+ * Reads the framework's built-in element config by importing the `config` entrypoints of the installed
+ * `@gtkx/react`, skipping the per-namespace ones whose namespace the gi store does not carry. Those
+ * entrypoints are reconciler-free, so importing them resolves `@gtkx/gi` but never `virtual:gtkx-config`,
+ * which means this must run only after the gi store has been written and linked.
+ *
+ * @param reactSubexports Subexport names of the installed `@gtkx/react`, as `resolveStore` reports them.
+ * @param giStoreDir The gi store directory, whose subdirectories name the generated namespaces.
+ */
 const readBuiltinElements = async (reactSubexports: string[], giStoreDir: string): Promise<BuiltinElements> => {
     const present = presentNamespaceDirs(giStoreDir);
     const entrypoints = configEntrypoints(reactSubexports, present);
-    const result: BuiltinElements = { components: {}, lazyElements: [], props: {}, omitProps: {} };
+    const result: BuiltinElements = { components: {}, lazyElements: [], props: {}, omittedProps: {} };
 
     for (const entrypoint of entrypoints) {
         collectBuiltinElements(result, await importBuiltinElements(entrypoint));
@@ -93,5 +96,5 @@ const readBuiltinElements = async (reactSubexports: string[], giStoreDir: string
     return result;
 };
 
-export { type ModuleExport } from "@gtkx/react/config";
-export { readBuiltinElements, type BuiltinElement, type BuiltinElements };
+export type { ModuleExport } from "@gtkx/react/config";
+export { readBuiltinElements, type BuiltinElements };