@dbx-tools/projen 0.6.222 → 0.6.224

package/src/project-py.ts

@@ -2,9 +2,7 @@
 import { project as coreProject } from "@dbx-tools/core";
 import { string } from "@dbx-tools/shared-core";
 import { Component, License, TextFile, type Project, javascript, python, vscode } from "projen";
-import type { IResolver } from "projen/lib/file";
 import { JobPermission } from "projen/lib/github/workflows-model";
-import { parse, stringify } from "smol-toml";
 import { BUN_VERSION, bunCacheRestoreSteps, bunCacheSaveStep } from "./bun-workflow.ts";
 import { DBX_TOOLS_LICENSE, projectReleaseBranch, projectRepositoryUrl } from "./project-js.ts";
 import { isDBXToolsJavaScriptProject } from "./project-predicate.ts";
@@ -14,7 +12,7 @@ import {
   releaseArtifactSteps,
   releasePublishCondition,
   releaseStageCondition,
-  releaseWorkflow,
+  tryReleaseWorkflow,
 } from "./release.ts";
 import { readWorkspaceVersion } from "./workspace-version.ts";
 
@@ -111,24 +109,6 @@ const DEFAULT_DEV_DEPENDENCIES = [
 
 const quote = (value: string): string => JSON.stringify(value);
 
-interface TomlSynthesizer {
-  synthesizeContent(resolver: IResolver): string | undefined;
-}
-
-function formatPyproject(file: python.PyprojectTomlFile): void {
-  const target = file as unknown as TomlSynthesizer;
-  const synthesize = target.synthesizeContent.bind(file);
-  target.synthesizeContent = (resolver) => {
-    const content = synthesize(resolver);
-    if (!content) return content;
-    const marker = content.startsWith("# ") ? content.slice(0, content.indexOf("\n")) : undefined;
-    const body = stringify(parse(content))
-      .trimEnd()
-      .replace(/ = \[ (.*) \]$/gm, " = [$1]");
-    return `${marker ? `${marker}\n\n` : ""}${body}\n`;
-  };
-}
-
 /** Repository-relative path for a Python package directory. */
 export function pythonPackagePath(repository: PythonRepositoryOptions, directory: string): string {
   return `${repository.root ?? "packages/py"}/${directory}`;
@@ -222,7 +202,6 @@ export class DBXToolsPythonProject extends python.PythonProject implements DBXTo
     if (pkg.uniffi !== undefined) {
       this.uv.file.addOverride("tool.dbx_tools.config.uniffi", pkg.uniffi);
     }
-    formatPyproject(this.uv.file);
     this.uv.file.readonly = true;
 
     for (const path of [".gitattributes", ".gitignore"]) {
@@ -397,7 +376,6 @@ export class DBXToolsPythonWorkspace extends Component {
       "tool.uv.sources",
       Object.fromEntries(options.packages.map((pkg) => [pkg.name, { workspace: true }])),
     );
-    formatPyproject(file);
     file.readonly = true;
     return file;
   }
@@ -433,7 +411,10 @@ export class DBXToolsPythonWorkspace extends Component {
     const allPublications = [...publications, ...uniffiPublications];
     if (allPublications.length === 0) return;
     const usesRustArtifacts = uniffiPublications.length > 0;
-    const workflow = releaseWorkflow(project);
+    const workflow = tryReleaseWorkflow(project);
+    if (!workflow) {
+      throw new Error("Python release requires the root dbx-tools release mode");
+    }
     workflow.addJob("build-python", {
       if: usesRustArtifacts
         ? "${{ always() && needs.verify-context.result == 'success' && needs.rust-build.result != 'failure' && needs.rust-build.result != 'cancelled' && (github.event_name == 'push' || inputs.stage == 'all' || inputs.stage == 'python') }}"
@@ -445,7 +426,9 @@ export class DBXToolsPythonWorkspace extends Component {
       env: { BUN_VERSION },
       steps: [
         ...releaseSourceSteps(),
-        ...bunCacheRestoreSteps(project),
+        ...bunCacheRestoreSteps(project, {
+          ignorePaths: project.workflowCacheIgnorePaths,
+        }),
         { name: "Setup uv", uses: "astral-sh/setup-uv@v7" },
         { name: "Install release helpers", run: "bun install" },
         bunCacheSaveStep(),

package/src/project-rs.ts

@@ -1,10 +1,11 @@
 /** Filesystem-discovered Rust workspaces and UniFFI binding package wiring. */
 import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { exec, project as coreProject } from "@dbx-tools/core";
 import { string } from "@dbx-tools/shared-core";
-import { Component, Project, TextFile, javascript } from "projen";
+import { Component, Project, TextFile, TomlFile, javascript } from "projen";
 import { JobPermission, type Job, type JobStep } from "projen/lib/github/workflows-model";
 import { BUN_VERSION } from "./bun-workflow.ts";
 import {
@@ -28,7 +29,7 @@ import {
   nodeReleaseSetupSteps,
   releaseArtifactSteps,
   releaseStageCondition,
-  releaseWorkflow,
+  tryReleaseWorkflow,
 } from "./release.ts";
 import { readWorkspaceVersion } from "./workspace-version.ts";
 
@@ -180,6 +181,7 @@ export const UNIFFI_RELEASE_TARGETS: readonly UniFFIReleaseTarget[] = [
 
 const UBRN_VERSION = "0.31.0-5";
 const RELEASE_PLATFORMS_ENV = "DBX_TOOLS_RELEASE_PLATFORMS";
+const require = createRequire(import.meta.url);
 const RUST_CACHE_ENV = {
   CARGO_INCREMENTAL: "0",
   CARGO_TERM_COLOR: "always",
@@ -262,17 +264,25 @@ function rustCliRegistrySource(binaries: readonly RustReleaseBinaryMapping[]): s
   ].join("\n");
 }
 
-function uniffiReleaseTaskSource(): string {
+function taskSource(name: string): string {
   const sourceDirectory = dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    resolve(sourceDirectory, "../tasks/uniffi-release.mjs"),
-    resolve(sourceDirectory, "../../tasks/uniffi-release.mjs"),
+    resolve(sourceDirectory, `../tasks/${name}`),
+    resolve(sourceDirectory, `../../tasks/${name}`),
   ];
   const source = candidates.find(existsSync);
-  if (!source) throw new Error("Could not locate tasks/uniffi-release.mjs");
+  if (!source) throw new Error(`Could not locate tasks/${name}`);
   return readFileSync(source, "utf8");
 }
 
+function smolTomlSource(name: "dist/index.cjs" | "LICENSE"): string {
+  const entry = require.resolve("smol-toml");
+  return readFileSync(
+    resolve(dirname(entry), name === "LICENSE" ? "../LICENSE" : "index.cjs"),
+    "utf8",
+  );
+}
+
 /** Keep tracked workspace package versions in Cargo.lock aligned with VERSION. */
 class RustWorkspaceVersionLock extends Component {
   public override postSynthesize(): void {
@@ -390,26 +400,23 @@ function cargoDependency(
   };
 }
 
-function tomlValue(value: unknown): string {
-  if (typeof value === "string") return JSON.stringify(value);
-  if (typeof value === "boolean" || typeof value === "number") return String(value);
-  if (Array.isArray(value)) return `[${value.map(tomlValue).join(", ")}]`;
-  if (value && typeof value === "object") {
-    return `{ ${Object.entries(value)
-      .map(([key, entry]) => `${key} = ${tomlValue(entry)}`)
-      .join(", ")} }`;
-  }
-  throw new Error(`Unsupported Cargo TOML value: ${String(value)}`);
-}
-
-function renderToml(value: Record<string, unknown>): string {
-  const blocks: string[] = [];
-  for (const [section, entries] of Object.entries(value)) {
-    if (!entries || typeof entries !== "object" || Array.isArray(entries)) continue;
-    const rows = Object.entries(entries).map(([key, entry]) => `${key} = ${tomlValue(entry)}`);
-    blocks.push(`${section === "bin" ? "[[bin]]" : `[${section}]`}\n${rows.join("\n")}`);
+function structuredTomlSections(value: Readonly<Record<string, unknown>>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [section, contents] of Object.entries(value)) {
+    const path = section.split(".");
+    let target = result;
+    for (const part of path.slice(0, -1)) {
+      const current = target[part];
+      if (current === undefined) {
+        target[part] = {};
+      } else if (!current || typeof current !== "object" || Array.isArray(current)) {
+        throw new Error(`Conflicting TOML section ${section}`);
+      }
+      target = target[part] as Record<string, unknown>;
+    }
+    target[path.at(-1)!] = contents;
   }
-  return `${blocks.join("\n\n")}\n`;
+  return result;
 }
 
 /** One generated Cargo workspace member. */
@@ -455,9 +462,11 @@ export class DBXToolsRustProject extends Project implements DBXToolsProject {
         : {}),
       ...(this.uniffi || binary
         ? {
-            bin: this.uniffi
-              ? { name: `${crateName}-uniffi-bindgen`, path: "uniffi-bindgen.rs" }
-              : { name: binaryName, path: "src/main.rs" },
+            bin: [
+              this.uniffi
+                ? { name: `${crateName}-uniffi-bindgen`, path: "uniffi-bindgen.rs" }
+                : { name: binaryName, path: "src/main.rs" },
+            ],
           }
         : {}),
       ...(options.features || options.defaultFeatures
@@ -489,20 +498,19 @@ export class DBXToolsRustProject extends Project implements DBXToolsProject {
           }
         : {}),
     };
-    new TextFile(this, "Cargo.toml", { lines: renderToml(manifest).trimEnd().split("\n") });
+    new TomlFile(this, "Cargo.toml", { marker: false, obj: manifest });
     if (this.uniffi) {
       new TextFile(this, "uniffi-bindgen.rs", {
         lines: ["fn main() {", "    uniffi::uniffi_bindgen_main();", "}", ""],
       });
-      new TextFile(this, "uniffi.toml", {
-        lines: renderToml(
+      new TomlFile(this, "uniffi.toml", {
+        marker: false,
+        obj: structuredTomlSections(
           options.uniffiConfig ?? {
             "bindings.python": { cdylib_name: crateName.replaceAll("-", "_") },
             "bindings.typescript": { strictTypeChecking: true },
           },
-        )
-          .trimEnd()
-          .split("\n"),
+        ),
       });
     }
   }
@@ -833,8 +841,9 @@ function configureRustBindingFiles(
     const dependencies = bindingDependencies(plan, pkg, "python");
     if (dependencies.length === 0) continue;
     pkg.tryRemoveFile("uniffi.toml");
-    new TextFile(pkg, "uniffi.toml", {
-      lines: renderToml({
+    new TomlFile(pkg, "uniffi.toml", {
+      marker: false,
+      obj: structuredTomlSections({
         "bindings.python": { cdylib_name: pkg.crateName.replaceAll("-", "_") },
         "bindings.typescript": { strictTypeChecking: true },
         ...pkg.packageOptions.uniffiConfig,
@@ -847,9 +856,7 @@ function configureRustBindingFiles(
             )}.bindings`,
           ]),
         ),
-      })
-        .trimEnd()
-        .split("\n"),
+      }),
     });
   }
 }
@@ -936,39 +943,41 @@ function configureRustWorkspaceFiles(
         .filter((pkg) => !pkg.uniffi)
         .map((pkg) => `${resolved.root}/${pkg.packageOptions.directory}`),
       resolver: "2",
+      package: {
+        version: readWorkspaceVersion(project.outdir),
+        edition: options.edition ?? "2021",
+        "rust-version": options.rustVersion ?? "1.82",
+        license: options.license ?? DBX_TOOLS_LICENSE,
+        repository: resolved.repository,
+      },
+      ...(options.workspaceDependencies
+        ? {
+            dependencies: Object.fromEntries(
+              Object.entries(options.workspaceDependencies).map(([name, value]) => [
+                name,
+                cargoDependency(value),
+              ]),
+            ),
+          }
+        : {}),
     },
-    "workspace.package": {
-      version: readWorkspaceVersion(project.outdir),
-      edition: options.edition ?? "2021",
-      "rust-version": options.rustVersion ?? "1.82",
-      license: options.license ?? DBX_TOOLS_LICENSE,
-      repository: resolved.repository,
-    },
-    ...(options.workspaceDependencies
-      ? {
-          "workspace.dependencies": Object.fromEntries(
-            Object.entries(options.workspaceDependencies).map(([name, value]) => [
-              name,
-              cargoDependency(value),
-            ]),
-          ),
-        }
-      : {}),
   };
-  new TextFile(project, "Cargo.toml", {
-    lines: renderToml(manifest).trimEnd().split("\n"),
+  new TomlFile(project, "Cargo.toml", {
+    marker: false,
+    obj: manifest,
   });
-  new TextFile(project, ".cargo/config.toml", {
-    lines: renderToml({
-      "target.x86_64-pc-windows-msvc": {
-        rustflags: ["-C", "target-feature=+crt-static"],
-      },
-      "target.aarch64-pc-windows-msvc": {
-        rustflags: ["-C", "target-feature=+crt-static"],
+  new TomlFile(project, ".cargo/config.toml", {
+    marker: false,
+    obj: {
+      target: {
+        "x86_64-pc-windows-msvc": {
+          rustflags: ["-C", "target-feature=+crt-static"],
+        },
+        "aarch64-pc-windows-msvc": {
+          rustflags: ["-C", "target-feature=+crt-static"],
+        },
       },
-    })
-      .trimEnd()
-      .split("\n"),
+    },
   });
   new RustWorkspaceVersionLock(project);
 }
@@ -1086,12 +1095,27 @@ function planRustRelease(
 }
 
 function configureRustReleaseTask(project: javascript.NodeProject, plan: RustReleasePlan): void {
+  const supportFiles = [
+    plan.releaseTask,
+    ".projen/uniffi-python.js",
+    ".projen/smol-toml.cjs",
+    ".projen/smol-toml.LICENSE",
+  ] as const;
   if (plan.bindings.length) {
     new TextFile(project, plan.releaseTask, {
-      lines: uniffiReleaseTaskSource().trimEnd().split("\n"),
+      lines: taskSource("uniffi-release.mjs").trimEnd().split("\n"),
+    });
+    new TextFile(project, supportFiles[1], {
+      lines: taskSource("uniffi-python.js").trimEnd().split("\n"),
+    });
+    new TextFile(project, supportFiles[2], {
+      lines: smolTomlSource("dist/index.cjs").trimEnd().split("\n"),
+    });
+    new TextFile(project, supportFiles[3], {
+      lines: smolTomlSource("LICENSE").trimEnd().split("\n"),
     });
   } else {
-    project.tryRemoveFile(plan.releaseTask);
+    for (const path of supportFiles) project.tryRemoveFile(path);
   }
 }
 
@@ -1476,8 +1500,11 @@ export class DBXToolsRustWorkspace {
   ): void {
     if (!project.github || !isDBXToolsJavaScriptProject()(project)) return;
     const plan = planRustRelease(project, options, targets, this.packages, this.bindingMappings);
+    const workflow = tryReleaseWorkflow(project);
+    if (!workflow) {
+      throw new Error("Rust release requires the root dbx-tools release mode");
+    }
     configureRustReleaseTask(project, plan);
-    const workflow = releaseWorkflow(project);
     if (plan.hasTargetOutputs && plan.targets.length) {
       workflow.addJob("rust-build", rustBuildJob(plan));
     }

package/src/release-github.ts

@@ -0,0 +1,37 @@
+/** GitHub repository identity used by release preparation. */
+export interface GithubRepositoryIdentity {
+  hostname: string;
+  owner: string;
+  repository: string;
+}
+
+/** Parse a GitHub repository URL without treating its owner as the authenticated actor. */
+export function githubRepositoryIdentity(repositoryUrl: string): GithubRepositoryIdentity {
+  const url = new URL(repositoryUrl);
+  const [owner, name] = url.pathname.split("/").filter(Boolean);
+  if (!owner || !name) {
+    throw new Error(`Cannot determine GitHub repository identity from ${repositoryUrl}`);
+  }
+  return {
+    hostname: url.hostname,
+    owner,
+    repository: name.replace(/\.git$/, ""),
+  };
+}
+
+/** Ask GitHub CLI for the current actor's token on the repository host. */
+export function githubTokenArguments(hostname: string): string[] {
+  return ["auth", "token", "--hostname", hostname];
+}
+
+/** GitHub CLI token variable for a public, data-residency, or enterprise host. */
+export function githubTokenEnvironmentName(hostname: string): "GH_TOKEN" | "GH_ENTERPRISE_TOKEN" {
+  return hostname === "github.com" || hostname.endsWith(".ghe.com")
+    ? "GH_TOKEN"
+    : "GH_ENTERPRISE_TOKEN";
+}
+
+/** Host-qualified repository selector consumed by GitHub CLI. */
+export function githubRepositorySpecifier(identity: GithubRepositoryIdentity): string {
+  return `${identity.hostname}/${identity.owner}/${identity.repository}`;
+}

package/src/release.ts

@@ -20,6 +20,12 @@ export type ReleaseStage = "all" | "node" | "python" | "docs";
 export interface ReleaseDocsOptions {
   readonly siteUrl: string;
   readonly base?: string;
+  /** Repository-defined setup and generation steps run before saving the Bun cache. */
+  readonly prepareSteps: readonly JobStep[];
+  /** Repository-defined documentation build and validation steps. */
+  readonly buildSteps: readonly JobStep[];
+  /** Directory uploaded as the GitHub Pages artifact. */
+  readonly artifactPath: string;
 }
 
 /** Options for {@link DBXToolsRelease}. */
@@ -30,6 +36,8 @@ export interface DBXToolsReleaseOptions {
   readonly nodeRelease?: boolean;
   /** Build and deploy generated documentation through GitHub Pages. */
   readonly docs?: ReleaseDocsOptions;
+  /** Python package root passed to local release preparation. */
+  readonly pythonRoot?: string;
 }
 
 /** Locate the unified workflow so attached language workspaces can add jobs. */
@@ -39,6 +47,11 @@ export function releaseWorkflow(project: DBXToolsJavaScriptProject): GithubWorkf
   return workflow;
 }
 
+/** Locate the unified workflow when release generation is enabled. */
+export function tryReleaseWorkflow(project: DBXToolsJavaScriptProject): GithubWorkflow | undefined {
+  return releaseWorkflows.get(project);
+}
+
 /** Whether the unified workflow publishes the normal npm workspace. */
 export function hasNodeRelease(project: DBXToolsJavaScriptProject): boolean {
   return nodeReleaseProjects.has(project);
@@ -98,7 +111,7 @@ export function releaseArtifactSteps(options: {
 export function nodeReleaseSetupSteps(project: DBXToolsJavaScriptProject): readonly JobStep[] {
   return [
     ...releaseSourceSteps(),
-    ...bunCacheRestoreSteps(project),
+    ...bunCacheRestoreSteps(project, { ignorePaths: project.workflowCacheIgnorePaths }),
     {
       name: "Setup Node.js",
       uses: "actions/setup-node@v6",
@@ -270,44 +283,14 @@ function addDocsJobs(
     },
     steps: [
       ...releaseSourceSteps(),
-      ...bunCacheRestoreSteps(project),
-      {
-        name: "Setup Node.js",
-        uses: "actions/setup-node@v6",
-        with: { "node-version": "22" },
-      },
-      {
-        name: "Setup Python",
-        uses: "actions/setup-python@v6",
-        with: { "python-version": "3.11" },
-      },
-      { name: "Setup Rust", uses: "dtolnay/rust-toolchain@stable" },
-      { name: "Configure Pages", uses: "actions/configure-pages@v5" },
-      { name: "Install dependencies", run: "bun install" },
-      {
-        name: "Validate public source documentation",
-        run: "bun docs/scripts/check-source-docs.mjs",
-      },
-      { name: "Generate docs from READMEs", run: "bun docs/scripts/sync-readmes.mjs" },
-      { name: "Install docs dependencies", run: "bun install --cwd .docs-build/site" },
+      ...bunCacheRestoreSteps(project, { ignorePaths: project.workflowCacheIgnorePaths }),
+      ...options.prepareSteps,
       bunCacheSaveStep(),
-      {
-        name: "Generate API docs",
-        run: "bun docs/scripts/generate-api-docs.mjs",
-      },
-      {
-        name: "Check generated titles",
-        run: "bun docs/scripts/check-generated-titles.mjs",
-      },
-      { name: "Build docs", run: "bun run --cwd .docs-build/site build" },
-      {
-        name: "Check generated links",
-        run: "bun run --cwd .docs-build/site check-links",
-      },
+      ...options.buildSteps,
       {
         name: "Upload Pages artifact",
         uses: "actions/upload-pages-artifact@v4",
-        with: { path: ".docs-build/dist" },
+        with: { path: options.artifactPath },
       },
     ],
   });
@@ -355,7 +338,13 @@ export class DBXToolsRelease extends Component {
               exec: taskScript(
                 project,
                 "release-pr.ts",
-                `--prefix ${tagPrefix} --base ${releaseBranch}`,
+                [
+                  `--prefix ${tagPrefix}`,
+                  `--base ${releaseBranch}`,
+                  ...(options.pythonRoot
+                    ? [`--python-root ${JSON.stringify(options.pythonRoot)}`]
+                    : []),
+                ].join(" "),
               ),
               receiveArgs: true,
               description: "Prepare, validate, locally publish, and open a reviewed release PR",

package/src/tsconfig.ts

@@ -1,7 +1,7 @@
 /**
  * Root `tsconfig.base.json` and `tsconfig.json` for the projenrc program.
  */
-import { Component, JsonFile, type Project, javascript } from "projen";
+import { Component, type Project, javascript, typescript } from "projen";
 
 /**
  * Compiler options for the ROOT program only (`.projenrc.ts` + the engine as
@@ -37,24 +37,24 @@ export class DBXToolsRootTsconfig extends Component {
   constructor(scope: Project) {
     super(scope);
 
-    new JsonFile(scope, "tsconfig.base.json", {
-      marker: true,
-      readonly: true,
-      obj: { compilerOptions: BASE_COMPILER_OPTIONS },
-    });
+    if (scope instanceof typescript.TypeScriptProject) {
+      return;
+    }
 
-    new JsonFile(scope, "tsconfig.json", {
-      marker: true,
-      readonly: true,
-      obj: {
-        extends: "./tsconfig.base.json",
-        compilerOptions: {
-          lib: ["ESNext"],
-          types: ["node"],
-        } satisfies javascript.TypeScriptCompilerOptions,
-        include: [".projenrc.ts"],
-        exclude: ["node_modules", "**/dist", "**/node_modules"],
+    const base = new javascript.TypescriptConfig(scope, {
+      fileName: "tsconfig.base.json",
+      compilerOptions: BASE_COMPILER_OPTIONS,
+    });
+    base.file.readonly = true;
+    const root = new javascript.TypescriptConfig(scope, {
+      extends: javascript.TypescriptConfigExtends.fromTypescriptConfigs([base]),
+      compilerOptions: {
+        lib: ["ESNext"],
+        types: ["node"],
       },
+      include: [".projenrc.ts"],
+      exclude: ["node_modules", "**/dist", "**/node_modules"],
     });
+    root.file.readonly = true;
   }
 }

package/tasks/local-publish.ts

@@ -16,7 +16,7 @@ export interface LocalPublishOptions {
   readonly version: string;
   readonly localRegistry: string;
   readonly localPypi: string;
-  readonly pythonRoot: string;
+  readonly pythonRoot?: string;
   readonly localCargo: boolean;
 }
 
@@ -50,7 +50,7 @@ export async function publishLocalRelease(options: LocalPublishOptions): Promise
   const localRegistry = resolveLocalRegistry(options.localRegistry);
   const activeIndexes = activePythonIndexes();
   const localPypi = resolveLocalPypi(options.localPypi, activeIndexes);
-  const pythonRoot = resolve(options.root, options.pythonRoot);
+  const pythonRoot = options.pythonRoot ? resolve(options.root, options.pythonRoot) : undefined;
   const localPublishes: Promise<unknown>[] = [];
 
   if (
@@ -79,7 +79,7 @@ export async function publishLocalRelease(options: LocalPublishOptions): Promise
     );
   }
 
-  if (localPypi && existsSync(pythonRoot)) {
+  if (localPypi && pythonRoot && existsSync(pythonRoot)) {
     const publishPythonScript = fileURLToPath(new URL("./publish-python.ts", import.meta.url));
     logger.info(`publishing Python ${options.version} to local devpi ${localPypi.publishUrl}`);
     localPublishes.push(