@gtkx/codegen 1.0.0 → 1.1.0

package/src/store/resolve-store.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, realpathSync } from "node:fs";
-import { dirname, join, parse } from "node:path";
+import { dirname, join, parse, relative, sep } from "node:path";
 import type { StoreOptions } from "./store-fs.js";
+import { sweepStagingDirs } from "../staging.js";
 
 /**
  * Where a project's generated stores live, ready to spread into `runCodegen`. `jsx` is null when the
@@ -15,10 +16,20 @@ type ResolvedStore = {
     reactSubexports: string[];
 };
 
-type ResolvedPackage = { dir: string; version: string };
+type ResolvedPackage = { dir: string; nodeModules: string; version: string };
+type StoreConsumer = { name: string; nodeModules: string };
 
 const STORE_DIR = ".gtkx";
 const SCOPE = "@gtkx";
+const STORE_NAMES: string[] = ["gi", "jsx"];
+
+const STORE_CONSUMERS: string[] = [
+    "@gtkx/cli",
+    "@gtkx/components",
+    "@gtkx/css",
+    "@gtkx/react",
+    "@gtkx/testing",
+];
 
 const readManifest = (path: string): { version?: string; exports?: Record<string, unknown> } =>
     JSON.parse(readFileSync(path, "utf8")) as { version?: string; exports?: Record<string, unknown> };
@@ -28,14 +39,14 @@ const subexportNames = (packageDir: string): string[] =>
         .filter((key) => key.startsWith("./") && key !== "./package.json")
         .map((key) => key.slice(2));
 
-const loadPackage = (manifest: string): ResolvedPackage | null => {
+const loadPackage = (manifest: string, nodeModules: string): ResolvedPackage | null => {
     if (!existsSync(manifest)) {
         return null;
     }
 
     const real = realpathSync(manifest);
 
-    return { dir: dirname(real), version: readManifest(real).version ?? "0.0.0" };
+    return { dir: dirname(real), nodeModules, version: readManifest(real).version ?? "0.0.0" };
 };
 
 const nodeModulesChain = function* (projectRoot: string): Generator<string> {
@@ -52,49 +63,153 @@ const nodeModulesChain = function* (projectRoot: string): Generator<string> {
 
 const resolvePackage = (projectRoot: string, packageName: string): ResolvedPackage | null => {
     for (const nodeModules of nodeModulesChain(projectRoot)) {
-        const found = loadPackage(join(nodeModules, packageName, "package.json"));
+        const found = loadPackage(join(nodeModules, packageName, "package.json"), nodeModules);
 
         if (found !== null) {
             return found;
         }
     }
 
-    return loadPackage(join(projectRoot, "packages", packageName.replace(/^@[^/]+\//, ""), "package.json"));
+    const unscoped = packageName.replace(/^@[^/]+\//, "");
+
+    return loadPackage(join(projectRoot, "packages", unscoped, "package.json"), join(projectRoot, "node_modules"));
+};
+
+const isWithin = (parent: string, child: string): boolean => {
+    const path = relative(parent, child);
+
+    return path === "" || (path !== ".." && !path.startsWith(`..${sep}`));
 };
 
+const canImport = (fromNodeModules: string, targetNodeModules: string): boolean =>
+    isWithin(dirname(targetNodeModules), dirname(fromNodeModules));
+
 const storeOptions = (nodeModules: string, name: string, version: string): StoreOptions => ({
     storeDir: join(nodeModules, STORE_DIR, name),
     linkDir: join(nodeModules, SCOPE, name),
     version,
 });
 
+const resolveRuntime = (projectRoot: string): ResolvedPackage => {
+    const runtime = resolvePackage(projectRoot, "@gtkx/runtime");
+
+    if (runtime === null) {
+        throw new Error(`Cannot resolve @gtkx/runtime from ${projectRoot}; is it installed?`);
+    }
+
+    return runtime;
+};
+
+const storeNodeModules = (runtime: ResolvedPackage, react: ResolvedPackage | null): string => {
+    if (react !== null && canImport(react.nodeModules, runtime.nodeModules)) {
+        return react.nodeModules;
+    }
+
+    return runtime.nodeModules;
+};
+
+const findUnreachableConsumer = (projectRoot: string, nodeModules: string): StoreConsumer | null => {
+    for (const name of STORE_CONSUMERS) {
+        const consumer = resolvePackage(projectRoot, name);
+
+        if (consumer !== null && !canImport(consumer.nodeModules, nodeModules)) {
+            return { name, nodeModules: consumer.nodeModules };
+        }
+    }
+
+    return null;
+};
+
+const unreachableConsumerMessage = (consumer: StoreConsumer, nodeModules: string): string =>
+    `Cannot write the generated store to ${nodeModules}: ${consumer.name} is installed in ` +
+    `${consumer.nodeModules}, above it, so that copy can never import the generated @gtkx/gi. Install every ` +
+    "@gtkx package in one node_modules, then run gtkx codegen again.";
+
+const checkConsumers = (projectRoot: string, nodeModules: string): void => {
+    const consumer = findUnreachableConsumer(projectRoot, nodeModules);
+
+    if (consumer !== null) {
+        throw new Error(unreachableConsumerMessage(consumer, nodeModules));
+    }
+};
+
+const jsxOptions = (react: ResolvedPackage | null, nodeModules: string): StoreOptions | null =>
+    react === null ? null : storeOptions(nodeModules, "jsx", react.version);
+
+const getReactSubexports = (react: ResolvedPackage | null): string[] =>
+    react === null ? [] : subexportNames(react.dir);
+
+const storePaths = (nodeModules: string): string[] =>
+    STORE_NAMES.flatMap((name) => [join(nodeModules, STORE_DIR, name), join(nodeModules, SCOPE, name)]);
+
+const findStoreNodeModules = (projectRoot: string): string | null => {
+    const runtime = resolvePackage(projectRoot, "@gtkx/runtime");
+
+    if (runtime === null) {
+        return null;
+    }
+
+    return storeNodeModules(runtime, resolvePackage(projectRoot, "@gtkx/react"));
+};
+
+const getShadowingStorePaths = (projectRoot: string): string[] => {
+    const nodeModules = join(projectRoot, "node_modules");
+    const anchored = findStoreNodeModules(projectRoot);
+
+    if (anchored === null || anchored === nodeModules) {
+        return [];
+    }
+
+    return storePaths(nodeModules);
+};
+
+const stagingRoots = (projectRoot: string): string[] => {
+    const nodeModules = join(projectRoot, "node_modules");
+    const anchored = findStoreNodeModules(projectRoot);
+
+    return anchored === null || anchored === nodeModules ? [nodeModules] : [nodeModules, anchored];
+};
+
+const sweepProjectStaging = (projectRoot: string): void => {
+    for (const nodeModules of stagingRoots(projectRoot)) {
+        for (const name of STORE_NAMES) {
+            sweepStagingDirs(join(nodeModules, STORE_DIR, name));
+        }
+    }
+};
+
 /**
  * Resolves where a project's `@gtkx/gi` and `@gtkx/jsx` stores belong, from the project root alone. The
  * result supplies every `runCodegen` input except `libraries` and `girPath`, so a caller that has
  * already resolved those can spread it straight into the call.
  *
+ * Both stores go in one `node_modules`, found by walking the project's `node_modules` chain upwards:
+ * the one `@gtkx/react` resolves from, or `@gtkx/runtime`'s when no React is installed. That is the
+ * project's own directory when it installs those packages itself, and the workspace root when npm or
+ * yarn hoisted them there. Keeping the pair together is what lets the jsx store import the gi store, and
+ * anchoring them where the `@gtkx` packages sit is what lets `@gtkx/react`, the CLI, and the project's
+ * sources all reach the bindings. A package manager that hoists therefore gives every project sharing
+ * that `node_modules` one shared store.
+ *
  * Store versions come from the installed `@gtkx/runtime` and `@gtkx/react`, so a dependency upgrade
  * invalidates the stores. Pass explicit `gi` or `jsx` options to `runCodegen` to override any of it.
  *
- * @param projectRoot Directory holding the project's `package.json` and `node_modules`.
+ * @param projectRoot Directory holding the project's `package.json`, whose `node_modules` chain is walked.
  * @returns The store locations and the React subexports that shape the jsx store.
- * @throws If `@gtkx/runtime` cannot be resolved from the project.
+ * @throws If `@gtkx/runtime` cannot be resolved from the project, or a `@gtkx` package that imports the
+ * bindings is installed above the `node_modules` the stores would go in, since it could not reach them.
  */
 const resolveStore = (projectRoot: string): ResolvedStore => {
-    const runtime = resolvePackage(projectRoot, "@gtkx/runtime");
-
-    if (runtime === null) {
-        throw new Error(`Cannot resolve @gtkx/runtime from ${projectRoot}; is it installed?`);
-    }
-
+    const runtime = resolveRuntime(projectRoot);
     const react = resolvePackage(projectRoot, "@gtkx/react");
-    const nodeModules = join(projectRoot, "node_modules");
+    const nodeModules = storeNodeModules(runtime, react);
+    checkConsumers(projectRoot, nodeModules);
 
     return {
         gi: storeOptions(nodeModules, "gi", runtime.version),
-        jsx: react === null ? null : storeOptions(nodeModules, "jsx", react.version),
-        reactSubexports: react === null ? [] : subexportNames(react.dir),
+        jsx: jsxOptions(react, nodeModules),
+        reactSubexports: getReactSubexports(react),
     };
 };
 
-export { resolveStore, type ResolvedStore };
+export { getShadowingStorePaths, resolveStore, sweepProjectStaging, type ResolvedStore };

package/src/store/store-fs.ts

@@ -1,5 +1,17 @@
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { errorMessage } from "@gtkx/utils";
+import {
+    chmodSync,
+    existsSync,
+    mkdirSync,
+    realpathSync,
+    renameSync,
+    rmSync,
+    symlinkSync,
+    writeFileSync,
+} from "node:fs";
 import { dirname, join, relative } from "node:path";
+import { keepFailedProject, type SourceModule } from "../compile.js";
+import { createStagingDir } from "../staging.js";
 import { compileStore } from "./compile-store.js";
 
 /** Where one generated store is written and how it is reached. */
@@ -12,10 +24,7 @@ type StoreOptions = {
     version: string;
 };
 
-type StoreFile = {
-    fileName: string;
-    source: string;
-};
+type StoreLink = Pick<StoreOptions, "storeDir" | "linkDir">;
 
 type Manifest = {
     name: string;
@@ -38,19 +47,25 @@ type RawFile = { relativePath: string; content: string };
 type WriteStoreParams = {
     storeDir: string;
     linkDir: string;
-    files: StoreFile[];
+    files: SourceModule[];
     manifest: Manifest;
     rawFiles?: RawFile[];
     requiresEnvReference?: boolean;
 };
 
 const STORE_DIR_MODE = 0o755;
+const FAILED_STORE_SUFFIX = ".failed";
 
 const subpathExport = (stem: string): { types: string; default: string } => ({
     types: `./${stem}.d.ts`,
     default: `./${stem}.js`,
 });
 
+const namespaceBarrel = (directory: string): { fileName: string; source: string } => ({
+    fileName: `${directory}/index.ts`,
+    source: `export * from "./${directory}.js";\n`,
+});
+
 const buildManifest = (input: ManifestInput): Manifest => {
     const manifest: Manifest = {
         name: input.name,
@@ -69,29 +84,36 @@ const buildManifest = (input: ManifestInput): Manifest => {
 
 const writeStore = (params: WriteStoreParams): void => {
     const tmp = createTempStore(params.storeDir);
+    const keepAt = `${params.storeDir}${FAILED_STORE_SUFFIX}`;
 
     try {
-        for (const file of params.files) {
-            writeSourceFile(tmp, file.fileName, file.source);
-        }
-
-        compileStore({
-            storeDir: tmp,
-            files: params.files,
-            packageName: params.manifest.name,
-            ...(params.requiresEnvReference !== undefined && { requiresEnvReference: params.requiresEnvReference }),
-        });
-
-        writePackageJson(tmp, params.manifest);
-        const rawFiles = params.rawFiles ?? [];
-
-        for (const raw of rawFiles) {
-            writeFileSync(join(tmp, raw.relativePath), raw.content);
-        }
-
-        swapStore(tmp, params.storeDir, params.linkDir);
-    } finally {
-        rmSync(tmp, { recursive: true, force: true });
+        buildTempStore(tmp, params);
+        swapStore(tmp, params.storeDir);
+        ensureStoreLink(params);
+    } catch (error) {
+        throw keepFailedProject({ projectDir: tmp, keepAt, error });
+    }
+
+    rmSync(keepAt, { recursive: true, force: true });
+};
+
+const buildTempStore = (tmp: string, params: WriteStoreParams): void => {
+    for (const file of params.files) {
+        writeSourceFile(tmp, file.fileName, file.source);
+    }
+
+    compileStore({
+        storeDir: tmp,
+        files: params.files,
+        packageName: params.manifest.name,
+        ...(params.requiresEnvReference !== undefined && { requiresEnvReference: params.requiresEnvReference }),
+    });
+
+    writePackageJson(tmp, params.manifest);
+    const rawFiles = params.rawFiles ?? [];
+
+    for (const raw of rawFiles) {
+        writeFileSync(join(tmp, raw.relativePath), raw.content);
     }
 };
 
@@ -111,7 +133,7 @@ const writePackageJson = (storeDir: string, manifest: Manifest): void => {
     writeFileSync(join(storeDir, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
 };
 
-const swapStore = (tmp: string, storeDir: string, visibleLink: string): void => {
+const swapStore = (tmp: string, storeDir: string): void => {
     const previous = `${storeDir}.old`;
     rmSync(previous, { recursive: true, force: true });
 
@@ -121,15 +143,46 @@ const swapStore = (tmp: string, storeDir: string, visibleLink: string): void =>
 
     renameSync(tmp, storeDir);
     rmSync(previous, { recursive: true, force: true });
-    symlinkRelative(visibleLink, storeDir);
 };
 
+const isStoreLinked = (link: StoreLink): boolean => {
+    try {
+        return realpathSync(link.linkDir) === realpathSync(link.storeDir);
+    } catch {
+        return false;
+    }
+};
+
+const ensureStoreLink = (link: StoreLink): void => {
+    if (!existsSync(join(link.storeDir, "package.json")) || isStoreLinked(link)) {
+        return;
+    }
+
+    symlinkRelative(link.linkDir, link.storeDir);
+};
+
+const storeWriteMessage = (storeDir: string, error: unknown): string =>
+    `Cannot write the generated store to ${storeDir}: ${errorMessage(error)}. ` +
+    "Codegen writes the store into the node_modules the @gtkx packages resolve from, " +
+    `so ${dirname(storeDir)} has to be writable.`;
+
 const createTempStore = (storeDir: string): string => {
-    mkdirSync(dirname(storeDir), { recursive: true });
-    const tmp = mkdtempSync(`${storeDir}.tmp-`);
-    chmodSync(tmp, STORE_DIR_MODE);
+    try {
+        const tmp = createStagingDir(storeDir);
+        chmodSync(tmp, STORE_DIR_MODE);
 
-    return tmp;
+        return tmp;
+    } catch (error) {
+        throw new Error(storeWriteMessage(storeDir, error), { cause: error });
+    }
 };
 
-export { subpathExport, buildManifest, writeStore, type StoreOptions, type RawFile };
+export {
+    subpathExport,
+    buildManifest,
+    ensureStoreLink,
+    namespaceBarrel,
+    writeStore,
+    type StoreOptions,
+    type RawFile,
+};

package/src/store/store-links.ts

@@ -0,0 +1,49 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { type ResolvedStore, resolveStore } from "./resolve-store.js";
+import { ensureStoreLink } from "./store-fs.js";
+
+const resolvedStores: Map<string, ResolvedStore> = new Map();
+
+const resolveStoreOrNull = (projectRoot: string): ResolvedStore | null => {
+    try {
+        return resolveStore(projectRoot);
+    } catch {
+        return null;
+    }
+};
+
+const isStoreDirPresent = (store: ResolvedStore): boolean => existsSync(join(store.gi.storeDir, "package.json"));
+
+const storeFor = (projectRoot: string): ResolvedStore | null => {
+    const cached = resolvedStores.get(projectRoot);
+
+    if (cached !== undefined && isStoreDirPresent(cached)) {
+        return cached;
+    }
+
+    const resolved = resolveStoreOrNull(projectRoot);
+    resolvedStores.delete(projectRoot);
+
+    if (resolved !== null) {
+        resolvedStores.set(projectRoot, resolved);
+    }
+
+    return resolved;
+};
+
+const ensureStoreLinks = (projectRoot: string): void => {
+    const store = storeFor(projectRoot);
+
+    if (store === null) {
+        return;
+    }
+
+    for (const unit of [store.gi, store.jsx]) {
+        if (unit !== null) {
+            ensureStoreLink(unit);
+        }
+    }
+};
+
+export { ensureStoreLinks };

package/src/writer/comparison-context.ts

@@ -0,0 +1,18 @@
+import { ModuleContext } from "./context.js";
+
+const COMPARISON_CONTEXTS: WeakMap<ModuleContext, ModuleContext> = new WeakMap();
+
+const comparisonContextFor = (context: ModuleContext): ModuleContext => {
+    const existing = COMPARISON_CONTEXTS.get(context);
+
+    if (existing !== undefined) {
+        return existing;
+    }
+
+    const created = new ModuleContext(context.namespace, context.library);
+    COMPARISON_CONTEXTS.set(context, created);
+
+    return created;
+};
+
+export { comparisonContextFor };

package/src/writer/context.ts

@@ -1,6 +1,6 @@
 import type { Library } from "../gir/library.js";
 import type { GirNamespace } from "../gir/namespace.js";
-import { type DeclaredType, ModuleBuilder } from "./module.js";
+import { type Declaration, ModuleBuilder } from "./module.js";
 
 class ModuleContext {
     public module: ModuleBuilder = new ModuleBuilder();
@@ -55,16 +55,22 @@ class ModuleContext {
         return namespaceName;
     }
 
-    declaredType(owner: string, name: string = owner): DeclaredType {
-        return { name, owner: `${this.namespace.name}.${owner}` };
+    declare(declaration: Declaration): void {
+        const { name, code, owner } = declaration;
+
+        this.module.appendDeclaration({
+            name,
+            code,
+            owner: owner === undefined ? undefined : `${this.namespace.name}.${owner}`,
+        });
     }
 
-    qualify(namespaceName: string, typeName: string): string {
+    qualify(namespaceName: string, name: string): string {
         if (namespaceName === this.namespace.name) {
-            return typeName;
+            return name;
         }
 
-        return `${this.addCrossNamespaceImport(namespaceName)}.${typeName}`;
+        return `${this.addCrossNamespaceImport(namespaceName)}.${name}`;
     }
 }
 

package/src/writer/module.ts

@@ -1,30 +1,109 @@
 import { ImportsBuilder } from "./imports.js";
 
-type DeclaredType = {
+type Declaration = {
     name: string;
-    owner: string;
+    code: string;
+    owner?: string | undefined;
 };
 
+type ExportedDeclaration = {
+    name: string;
+    spaces: string[];
+};
+
+const EXPORTED_DECLARATION = /^export (?:abstract )?(class|const|enum|function|interface|type) ([A-Za-z_$][\w$]*)/mu;
+
+const SPACES_BY_KEYWORD: Map<string, string[]> = new Map([
+    ["class", ["value", "type"]],
+    ["const", ["value"]],
+    ["enum", ["value", "type"]],
+    ["function", ["value"]],
+    ["interface", []],
+    ["type", ["type"]],
+]);
+
+const getExportedDeclaration = (code: string): ExportedDeclaration | undefined => {
+    const match = EXPORTED_DECLARATION.exec(code);
+    const spaces = SPACES_BY_KEYWORD.get(match?.[1] ?? "");
+    const name = match?.[2];
+
+    return spaces === undefined || name === undefined ? undefined : { name, spaces };
+};
+
+const exportedNameText = (exported: ExportedDeclaration | undefined): string =>
+    exported === undefined ? "no name at all" : `'${exported.name}'`;
+
 class ModuleBuilder {
     private bindings: string[] = [];
     private bindingNames: Set<string> = new Set();
     private hoistedDescriptors: Map<string, string> = new Map();
+    private claimedSpaces: Set<string> = new Set();
     private declarations: string[] = [];
+    private declaredNames: Set<string> = new Set();
     private declaredTypes: Map<string, string> = new Map();
     private registrations: string[] = [];
+    private requiredNames: Set<string> = new Set();
     public imports: ImportsBuilder = new ImportsBuilder();
 
-    private claimTypeName(declared: DeclaredType): void {
-        const owner = this.declaredTypes.get(declared.name);
+    private claimSpace(name: string, space: string): void {
+        const key = `${space} ${name}`;
+
+        if (this.claimedSpaces.has(key)) {
+            throw new Error(
+                `The generated module declares '${name}' twice in its ${space} space. ` +
+                "A module may declare each exported name once per declaration space.",
+            );
+        }
+
+        this.claimedSpaces.add(key);
+    }
+
+    private claimExportedName(declaration: Declaration): void {
+        const exported = getExportedDeclaration(declaration.code);
+        const spaces = exported?.name === declaration.name ? exported.spaces : undefined;
+
+        if (spaces === undefined) {
+            throw new Error(
+                `The declaration recorded as '${declaration.name}' exports ${exportedNameText(exported)}. ` +
+                "A declaration may only be recorded under the name its own code exports.",
+            );
+        }
+
+        for (const space of spaces) {
+            this.claimSpace(declaration.name, space);
+        }
+    }
+
+    private claimTypeName(declaration: Declaration): void {
+        const { name, owner } = declaration;
+
+        if (owner === undefined) {
+            return;
+        }
+
+        const previous = this.declaredTypes.get(name);
 
-        if (owner !== undefined && owner !== declared.owner) {
+        if (previous !== undefined && previous !== owner) {
             throw new Error(
-                `The generated type '${declared.name}' is declared for both ${owner} and ${declared.owner}. ` +
+                `The generated type '${name}' is declared for both ${previous} and ${owner}. ` +
                 "Rename one of them, or drop the namespace from the configuration.",
             );
         }
 
-        this.declaredTypes.set(declared.name, declared.owner);
+        this.declaredTypes.set(name, owner);
+    }
+
+    private verifyRegistrations(): void {
+        const missing = [...this.requiredNames].filter((name) => !this.declaredNames.has(name));
+
+        if (missing.length === 0) {
+            return;
+        }
+
+        throw new Error(
+            `The generated module registers ${missing.join(", ")}, which it never declares. ` +
+            "A registration may only name a symbol whose declaration the same module emits.",
+        );
     }
 
     appendBinding(code: string, name?: string): void {
@@ -53,19 +132,27 @@ class ModuleBuilder {
         return name;
     }
 
-    appendDeclaration(code: string, declared?: DeclaredType): void {
-        if (declared !== undefined) {
-            this.claimTypeName(declared);
-        }
+    appendDeclaration(declaration: Declaration): void {
+        this.claimExportedName(declaration);
+        this.claimTypeName(declaration);
+        this.declaredNames.add(declaration.name);
+        this.declarations.push(declaration.code);
+    }
 
-        this.declarations.push(code);
+    hasExports(): boolean {
+        return this.declaredNames.size > 0;
     }
 
-    appendRegistration(code: string): void {
+    appendRegistration(code: string, requires: string[] = []): void {
+        for (const name of requires) {
+            this.requiredNames.add(name);
+        }
+
         this.registrations.push(code);
     }
 
     toSource(): string {
+        this.verifyRegistrations();
         const sections: string[] = [];
         const importsBlock = this.imports.toSource();
 
@@ -89,4 +176,4 @@ class ModuleBuilder {
     }
 }
 
-export { type DeclaredType, ModuleBuilder };
+export { type Declaration, ModuleBuilder };