@gtkx/codegen 1.0.0-rc.4 → 1.1.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

@@ -1,4 +1,4 @@
-import type { ModuleExport } from "@gtkx/react/internal";
+import type { ModuleExport } from "@gtkx/react/config";
 import { readdirSync } from "node:fs";
 import type { OmittedProps } from "../store/jsx/omitted-props.js";
 
@@ -96,5 +96,5 @@ const readBuiltinElements = async (reactSubexports: string[], giStoreDir: string
     return result;
 };
 
-export type { ModuleExport } from "@gtkx/react/internal";
+export type { ModuleExport } from "@gtkx/react/config";
 export { readBuiltinElements, type BuiltinElements };

package/src/runner.ts

@@ -1,20 +1,14 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import type { ModuleExport } from "./react/element-config.js";
 import type { OmittedProps } from "./store/jsx/omitted-props.js";
-import type { StoreOptions } from "./store/store-fs.js";
 import { checkModules } from "./compile.js";
 import { isGiStoreFresh } from "./fingerprint.js";
 import { runGiCodegen } from "./gi.js";
 import { Library } from "./gir/library.js";
 import { generateGlModules, type GlGenerationReport } from "./khronos/pipeline.js";
-
-/** A named export in a module, referenced as plain data (the module is never imported at runtime). */
-type ModuleExport = {
-    /** Specifier the export is imported from. */
-    module: string;
-    /** Identifier the module exports it under. */
-    export: string;
-};
+import { sweepStagingDirs } from "./staging.js";
+import { ensureStoreLink, type StoreOptions } from "./store/store-fs.js";
 
 type GlCodegenOptions = {
     registryPath: string;
@@ -71,6 +65,10 @@ type StoreResult = {
  * store or the React element config changed, unless `options.isForced` is set. Pass the spread of
  * `resolveStore(projectRoot)` for everything but `libraries` and `girPath`.
  *
+ * Every store already on disk is linked at its `linkDir` before anything is generated, so a link an install
+ * pruned out of `node_modules` is restored without regenerating the store, and the gi store is reachable
+ * under its own specifier while the jsx store is type checked.
+ *
  * @param options What to generate and where to write it.
  * @returns A summary of what was regenerated and how long the run took.
  * @throws If `girPath` is empty, which would otherwise generate nothing and report success.
@@ -174,6 +172,17 @@ const emitStoresWithConfig = async (config: {
     return emitJsxStore({ options, jsx, gi, loadLibrary, isGiRegenerated, namespaces });
 };
 
+const prepareStores = (stores: (StoreOptions | undefined)[]): void => {
+    for (const store of stores) {
+        if (store === undefined) {
+            continue;
+        }
+
+        sweepStagingDirs(store.storeDir);
+        ensureStoreLink(store);
+    }
+};
+
 const emitStores = async (options: CodegenRunnerOptions): Promise<StoreResult> => {
     const { gi, jsx, libraries, girPath } = options;
 
@@ -181,6 +190,8 @@ const emitStores = async (options: CodegenRunnerOptions): Promise<StoreResult> =
         throw new Error("codegen needs at least one GIR search path; pass the result of resolveGirPath");
     }
 
+    prepareStores([gi, jsx]);
+
     return emitStoresWithConfig({ options, gi, jsx, libraries, girPath });
 };
 

package/src/staging.ts

@@ -0,0 +1,69 @@
+import { mkdirSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const STAGING_SUFFIX = ".tmp-";
+const OWNER_PATTERN = /^(?<pid>\d+)-/;
+
+const errorCode = (error: unknown): string | undefined =>
+    error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : undefined;
+
+const isOwnerRunning = (pid: number): boolean => {
+    if (!Number.isSafeInteger(pid) || pid <= 0) {
+        return false;
+    }
+
+    try {
+        process.kill(pid, 0);
+
+        return true;
+    } catch (error) {
+        return errorCode(error) === "EPERM";
+    }
+};
+
+const isStranded = (entry: string, prefix: string): boolean => {
+    if (!entry.startsWith(prefix)) {
+        return false;
+    }
+
+    const owner = OWNER_PATTERN.exec(entry.slice(prefix.length))?.groups?.pid;
+
+    return owner === undefined || !isOwnerRunning(Number(owner));
+};
+
+const readEntries = (parentDir: string): string[] => {
+    try {
+        return readdirSync(parentDir);
+    } catch {
+        return [];
+    }
+};
+
+const removeStrandedDir = (path: string): void => {
+    try {
+        rmSync(path, { recursive: true, force: true });
+    } catch {
+        return;
+    }
+};
+
+const sweepStrandedDirs = (parentDir: string, prefix: string): void => {
+    for (const entry of readEntries(parentDir)) {
+        if (isStranded(entry, prefix)) {
+            removeStrandedDir(join(parentDir, entry));
+        }
+    }
+};
+
+const sweepStagingDirs = (target: string): void => {
+    sweepStrandedDirs(dirname(target), `${basename(target)}${STAGING_SUFFIX}`);
+};
+
+const createStagingDir = (target: string): string => {
+    mkdirSync(dirname(target), { recursive: true });
+    sweepStagingDirs(target);
+
+    return mkdtempSync(`${target}${STAGING_SUFFIX}${String(process.pid)}-`);
+};
+
+export { createStagingDir, sweepStagingDirs, sweepStrandedDirs };

package/src/store/compile-store.ts

@@ -1,6 +1,6 @@
 import { rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { compileProject, type SourceModule } from "../compile.js";
+import { compileProject, type ProjectFile, type SourceModule } from "../compile.js";
 
 type CompileStoreParams = {
     storeDir: string;
@@ -29,16 +29,18 @@ const writeEnvReference = (storeDir: string): (() => void) => {
 };
 
 const compileStore = (params: CompileStoreParams): void => {
-    const fileNames = params.files.map((file) => file.fileName);
-
     const removeEnvReference = params.requiresEnvReference === true
         ? writeEnvReference(params.storeDir)
         : (): void => undefined;
 
+    const files: ProjectFile[] = params.requiresEnvReference === true
+        ? [{ fileName: ENV_REFERENCE_FILE }, ...params.files]
+        : params.files;
+
     try {
         compileProject({
             projectDir: params.storeDir,
-            fileNames: params.requiresEnvReference === true ? [ENV_REFERENCE_FILE, ...fileNames] : fileNames,
+            files,
             compilerOptions: EMIT_OPTIONS,
             label: `the generated ${params.packageName} store`,
         });
@@ -51,4 +53,4 @@ const compileStore = (params: CompileStoreParams): void => {
     }
 };
 
-export { compileStore, type CompileStoreParams };
+export { compileStore };