@dbx-tools/projen 0.6.222 → 0.6.224

package/README.md

@@ -37,6 +37,34 @@ project.synth();
 Every `src`-bearing folder under the configured roots becomes a
 `DBXToolsTypeScriptProject`. Folder path drives package name and runtime tags.
 
+Use `DBXToolsTypeScriptProject` itself as the root when one package needs the
+same Bun workspace, repository, task, and release defaults without a separate
+non-compiling root. It preserves Projen's native compiling `tsconfig.json`
+instead of creating a second owner. An explicit `outdir` is the workspace root
+for naming, Git metadata, package discovery, codegen, and barrels even when the
+calling process has a different current directory.
+
+The unified dbx-tools release surface is enabled by default. Set
+`releaseMode: "disabled"` to omit its workflow and bump/version/release tasks.
+The inherited Projen `release` and `releaseTrigger` options are intentionally
+not part of this engine's public options because they create a competing release
+workflow.
+
+Repository policy stays in the consuming `.projenrc.ts`:
+
+- `releaseDocs` supplies repository-defined preparation and build steps plus
+  the Pages artifact path. The engine adds release checkout, Bun caching,
+  artifact upload, and deployment without naming a docs script or output tree.
+- `releasePythonRoot` passes the actual Python package root to local release
+  preparation. Omit it when the workspace has no standard Python packages.
+- `pullRequestTitlePolicy` configures semantic title types and scope policy.
+  Omit it or pass `false` to disable the title job.
+- `workflowCacheIgnorePaths` excludes generated output trees that may contain
+  package manifests from the dependency-only Bun cache key.
+- `extraWorkspaceMembers` declares self-synthesizing tooling packages outside
+  `packageRoots`. Their version, generated entrypoint, formatting, linting, and
+  workspace membership are derived from that declaration.
+
 Dependency installation runs once from this root. The default-on
 `ROOT_INSTALL_ONLY_MIXIN` clears child `install` / `install:ci` task steps during
 root pre-synthesis, including packages attached after root construction. Set
@@ -53,9 +81,9 @@ new package membership.
 without turning Python packages into JavaScript workspace projects. It generates
 the root and member `pyproject.toml` files, standard `py:*` tasks, the VS Code
 interpreter setting, and an optional manual PyPI trusted-publishing workflow.
-Every generated TOML file is parsed and reserialized with `smol-toml`, so nested
-tables and arrays use consistent formatting instead of projen's indented table
-headers.
+Projen's native `PyprojectTomlFile` owns generated TOML formatting. Temporary
+publication stamping uses parsed TOML, changes versions and sibling
+dependencies structurally, and restores the original files byte-for-byte.
 
 ```ts
 import { project, projectPy } from "@dbx-tools/projen";
@@ -121,6 +149,10 @@ are library-local. Release wheels replace sibling Git requirements with matching
 native-wheel versions, and dependent publishers wait for their dependencies.
 Each crate builds its own `<crate>-uniffi-bindgen` executable so a workspace
 build has no colliding binary outputs. Packaging runs that prebuilt executable.
+Cargo manifests, target config, and UniFFI config are generated from structured
+Projen `TomlFile` objects. Local and release Python generation share one
+dependency-free helper for generator arguments, target-specific executable
+names, generated headers, empty `__init__.py`, and native-library placement.
 
 `sync --watch` runs a focused Rust watcher beside the OpenAPI watcher. Changes
 inside an existing UniFFI crate regenerate that crate and its dependent bindings
@@ -425,10 +457,12 @@ Use `--local-registry false` or `--local-pypi false` to disable either local
 publish. An explicit `--local-pypi http://localhost:3141/user/index/` overrides
 auto-detection; `--python-root` defaults to `packages/py`.
 
-The GitHub PR workflow runs synth plus the workspace TypeScript compile rather
-than the complete root build. Release preparation has already run Rust tests,
-workspace type-checking, and local package preflight before opening the PR.
-JavaScript behavior tests remain an explicit developer task.
+The GitHub PR workflow runs the explicit `pr:validate` task through Projen's
+public `BuildWorkflow` `buildTask` option. That task runs synth plus the
+workspace TypeScript compile rather than the complete root build. Release
+preparation has already run Rust tests, workspace type-checking, and local
+package preflight before opening the PR. JavaScript behavior tests remain an
+explicit developer task.
 
 The configured release branch publishes only when a reviewed PR changes
 `VERSION`. Its workflow creates the annotated `v*` public release boundary.

package/index.ts

@@ -3,7 +3,7 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 
 export const PACKAGE_IDENTIFIER = "@dbx-tools/projen";
-export const PACKAGE_VERSION = "0.6.222";
+export const PACKAGE_VERSION = "0.6.224";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";
@@ -25,6 +25,7 @@ export * as projectRs from "./src/project-rs.ts";
 export * as publish from "./src/publish.ts";
 export * as release from "./src/release.ts";
 export * as releaseDispatch from "./src/release-dispatch.ts";
+export * as releaseGithub from "./src/release-github.ts";
 export * as scaffold from "./src/scaffold.ts";
 export * as tags from "./src/tags.ts";
 export * as tsconfig from "./src/tsconfig.ts";
@@ -47,7 +48,7 @@ export { PnpmWorkspaceState } from "./src/pnpm-workspace.ts";
 export type { Catalog, AllowBuilds, DBXToolsPNPMWorkspaceOptions } from "./src/pnpm-workspace.ts";
 export type { DBXToolsProjectLanguage, DBXToolsProjectOptions, DBXToolsProject, ApplyToProjectsOptions } from "./src/project.ts";
 export { PackageIdentifier, PROJEN_VERSION, DBX_TOOLS_LICENSE, DBXToolsNodeProject, ROOT_INSTALL_ONLY_MIXIN, DBXToolsTypeScriptProject } from "./src/project-js.ts";
-export type { DBXToolsJavaScriptProject, DBXToolsJavaScriptProjectOptions, DBXToolsTypeScriptProjectOptions } from "./src/project-js.ts";
+export type { DBXToolsJavaScriptProject, DBXToolsReleaseMode, PullRequestTitlePolicyOptions, DBXToolsJavaScriptProjectOptions, DBXToolsTypeScriptProjectOptions } from "./src/project-js.ts";
 export { DBXToolsPythonProject, DBXToolsPythonWorkspace } from "./src/project-py.ts";
 export type { PythonRepositoryOptions, PythonPackageOptions, PythonTrustedPublisherOptions, DBXToolsPythonProjectOptions, PythonReleaseOptions, DBXToolsPythonWorkspaceOptions } from "./src/project-py.ts";
 export { RustReleaseOs, RustReleaseCpu, UNIFFI_RELEASE_TARGETS, DBXToolsRustProject, DBXToolsRustWorkspace } from "./src/project-rs.ts";
@@ -56,6 +57,7 @@ export { COMPILED_DIR, COMPILED_COMPILER_OPTIONS } from "./src/publish.ts";
 export { DBXToolsRelease } from "./src/release.ts";
 export type { ReleaseStage, ReleaseDocsOptions, DBXToolsReleaseOptions } from "./src/release.ts";
 export { RELEASE_TAG, RELEASE_SHA, RELEASE_VERSION } from "./src/release-dispatch.ts";
+export type { GithubRepositoryIdentity } from "./src/release-github.ts";
 export { AGNOSTIC_COMPILER_OPTIONS, PACKAGE_TAG_MIXINS } from "./src/tags.ts";
 export type { PackageTag } from "./src/tags.ts";
 export { DBXToolsRootTsconfig } from "./src/tsconfig.ts";

package/package.json

@@ -5,13 +5,13 @@
     "clobber": "projen clobber",
     "compile": "projen compile",
     "default": "projen default",
-    "demo": "projen demo",
     "eject": "projen eject",
     "package": "projen package",
     "post-compile": "projen post-compile",
     "post-upgrade": "projen post-upgrade",
     "pre-compile": "projen pre-compile",
     "test": "projen test",
+    "test:external-consumer": "projen test:external-consumer",
     "upgrade": "projen upgrade",
     "watch": "projen watch",
     "projen": "projen"
@@ -25,9 +25,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/core": "0.6.222",
-    "@dbx-tools/path": "0.6.222",
-    "@dbx-tools/shared-core": "0.6.222",
+    "@dbx-tools/core": "0.6.224",
+    "@dbx-tools/path": "0.6.224",
+    "@dbx-tools/shared-core": "0.6.224",
     "commander": "^15.0.0",
     "concurrently": "^10.0.3",
     "constructs": "^10.6.0",
@@ -47,7 +47,7 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.6.222",
+  "version": "0.6.224",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/barrels.ts

@@ -63,7 +63,7 @@ import { json, string } from "@dbx-tools/shared-core";
 import isIdentifier from "is-identifier";
 import { header, isGenerated, makeReadonly, makeWritable, type HeaderOpts } from "./generated.ts";
 import { moduleExports, moduleStatements, type ModuleExport } from "./module-exports.ts";
-import { isModuleFile, toPosix, recordedPackages, repoRoot } from "./packages.ts";
+import { isModuleFile, toPosix, recordedPackages, resolveRepoRoot } from "./packages.ts";
 
 /**
  * A `src`-relative posix path excluded from the root barrel:
@@ -555,8 +555,14 @@ function writeBarrel(file: string, content: string): void {
  * order, so one unwritable barrel silently left the rest of the repo stale with
  * nothing in the log to say which packages had been skipped.
  */
-export function generateBarrels(opts: { dirs?: string[] } = {}): number {
-  const dirs = opts.dirs ?? recordedPackages().map((p) => p.dir);
+export function generateBarrels(
+  opts: { dirs?: string[]; includeRoot?: boolean; projectRoot?: string } = {},
+): number {
+  const projectRoot = opts.projectRoot ?? resolveRepoRoot();
+  const dirs = opts.dirs ?? [
+    ...(opts.includeRoot ? [projectRoot] : []),
+    ...recordedPackages(projectRoot).map((p) => p.dir),
+  ];
   let total = 0;
   const failures: { dir: string; err: unknown }[] = [];
   for (const dir of dirs) {
@@ -567,7 +573,7 @@ export function generateBarrels(opts: { dirs?: string[] } = {}): number {
     }
   }
   if (failures.length) {
-    const names = failures.map((f) => relative(repoRoot, f.dir) || f.dir);
+    const names = failures.map((f) => relative(projectRoot, f.dir) || f.dir);
     throw new AggregateError(
       failures.map((f) => f.err),
       `${string.pluralize(failures.length, "barrel")} failed: ${names.join(", ")}`,

package/src/bun-workflow.ts

@@ -3,15 +3,8 @@ import { TextFile, javascript } from "projen";
 
 export const BUN_VERSION = "1.3.14";
 
-const cacheKeyScript = `#!/usr/bin/env node
-import { createHash } from "node:crypto";
-import { readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-const root = process.cwd();
-const ignored = new Set([
+const DEFAULT_CACHE_IGNORE_PATHS = [
   ".git",
-  ".docs-build",
   ".venv",
   ".worktrees",
   "coverage",
@@ -19,12 +12,24 @@ const ignored = new Set([
   "lib",
   "node_modules",
   "target",
-]);
+] as const;
+
+function cacheKeyScript(extraIgnorePaths: readonly string[]): string {
+  const ignorePaths = [...new Set(extraIgnorePaths)].sort();
+  return `#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, sep } from "node:path";
+
+const root = process.cwd();
+const ignoredNames = new Set(${JSON.stringify(DEFAULT_CACHE_IGNORE_PATHS)});
+const ignoredPaths = new Set(${JSON.stringify(ignorePaths)});
 const manifests = [];
 const walk = (directory) => {
   for (const entry of readdirSync(directory, { withFileTypes: true })) {
-    if (ignored.has(entry.name)) continue;
     const path = join(directory, entry.name);
+    const relativePath = path.slice(root.length + 1).split(sep).join("/");
+    if (ignoredNames.has(entry.name) || ignoredPaths.has(relativePath)) continue;
     if (entry.isDirectory()) walk(path);
     else if (entry.name === "package.json") manifests.push(path);
   }
@@ -66,15 +71,27 @@ const dependencies = manifests
   });
 process.stdout.write(createHash("sha256").update(JSON.stringify(dependencies)).digest("hex"));
 `;
+}
 
-const configured = new WeakSet<javascript.NodeProject>();
+const configured = new WeakMap<javascript.NodeProject, string>();
 
-function ensureCacheKeyScript(project: javascript.NodeProject): void {
-  if (configured.has(project)) return;
-  new TextFile(project.root, ".projen/bun-cache-key.mjs", {
-    lines: cacheKeyScript.trimEnd().split("\n"),
+function ensureCacheKeyScript(
+  project: javascript.NodeProject,
+  ignorePaths: readonly string[],
+): void {
+  const root = project.root as javascript.NodeProject;
+  const key = JSON.stringify([...new Set(ignorePaths)].sort());
+  const existing = configured.get(root);
+  if (existing !== undefined) {
+    if (existing !== key) {
+      throw new Error("Bun workflow cache ignore paths must be consistent across one project");
+    }
+    return;
+  }
+  new TextFile(root, ".projen/bun-cache-key.mjs", {
+    lines: cacheKeyScript(ignorePaths).trimEnd().split("\n"),
   });
-  configured.add(project);
+  configured.set(root, key);
 }
 
 function stepCondition(condition: string | undefined, cacheMiss = false): string | undefined {
@@ -88,6 +105,8 @@ function stepCondition(condition: string | undefined, cacheMiss = false): string
 export interface BunWorkflowCacheOptions {
   readonly setupCondition?: string;
   readonly condition?: string;
+  /** Repository-relative output paths excluded from dependency manifest hashing. */
+  readonly ignorePaths?: readonly string[];
 }
 
 /** Set up Bun and restore its global package cache. */
@@ -95,7 +114,7 @@ export function bunCacheRestoreSteps(
   project: javascript.NodeProject,
   options: BunWorkflowCacheOptions = {},
 ): readonly Record<string, unknown>[] {
-  ensureCacheKeyScript(project);
+  ensureCacheKeyScript(project, options.ignorePaths ?? []);
   const condition = stepCondition(options.condition);
   const setupCondition = stepCondition(options.setupCondition);
   return [

package/src/clean.ts

@@ -25,7 +25,7 @@ import { existsSync, rmSync, statSync } from "node:fs";
 import { basename, join, relative } from "node:path";
 import { find } from "@dbx-tools/path";
 import { isReadonly, makeWritable } from "./generated.ts";
-import { repoRoot, toPosix } from "./packages.ts";
+import { resolveRepoRoot, toPosix } from "./packages.ts";
 
 /**
  * Basenames `clean` never removes even when they are generated/read-only. `.gitignore`
@@ -40,7 +40,7 @@ const CLEAN_SKIP_FILES: ReadonlySet<string> = new Set([".gitignore"]);
  * ignores AND every dot-prefixed folder (`.projen`, `.vscode`, `.github`, ...), and
  * {@link CLEAN_SKIP_FILES} entry (`.gitignore`).
  */
-export function listGeneratedFiles(root: string = repoRoot): string[] {
+export function listGeneratedFiles(root: string = resolveRepoRoot()): string[] {
   const rel = (f: string): string => toPosix(relative(root, f));
   return [...find.findFiles("**/*", { cwd: root })]
     .map((f) => join(root, f))
@@ -57,7 +57,7 @@ export function listGeneratedFiles(root: string = repoRoot): string[] {
  * own - removing the top-level dir takes it along. Other vendor/build/VCS dirs are
  * skipped for speed.
  */
-export function listNodeModulesDirs(root: string = repoRoot): string[] {
+export function listNodeModulesDirs(root: string = resolveRepoRoot()): string[] {
   if (!existsSync(root)) return [];
   const rel = (f: string): string => toPosix(relative(root, f));
   return [...find.findFiles("**/node_modules", { cwd: root, ignoreOptions: { dot: false } })]

package/src/codegen.ts

@@ -50,7 +50,7 @@ import { log, object } from "@dbx-tools/shared-core";
 import type * as ts from "typescript";
 import { lazyRequire } from "./_lazy-require.ts";
 import { header, isReadonly, makeReadonly, makeWritable } from "./generated.ts";
-import { readPackageManifest, repoRoot, recordedPackages } from "./packages.ts";
+import { readPackageManifest, recordedPackages, resolveRepoRoot } from "./packages.ts";
 
 const logger = log.logger("projen:codegen");
 
@@ -115,7 +115,7 @@ export function codegenModulePaths(inputs: readonly string[]): string[] {
  * package or hoisted to the workspace root. Any other source is treated as
  * repo-root-relative.
  */
-function resolveInputSource(source: string, fromDir: string): string {
+function resolveInputSource(source: string, fromDir: string, projectRoot: string): string {
   if (source.startsWith("node_modules/")) {
     let dir = fromDir;
     for (;;) {
@@ -126,7 +126,7 @@ function resolveInputSource(source: string, fromDir: string): string {
       dir = parent;
     }
   }
-  return resolve(repoRoot, source);
+  return resolve(projectRoot, source);
 }
 
 /**
@@ -276,6 +276,7 @@ function isGeneratedModule(srcDir: string, file: string): boolean {
 function generatePackage(
   tsRuntime: typeof ts,
   generate: typeof import("ts-to-zod").generate,
+  projectRoot: string,
   dir: string,
   inputs: string[],
 ): string {
@@ -296,7 +297,7 @@ function generatePackage(
 
   let warnings = 0;
   for (const input of parsed) {
-    const sourcePath = resolveInputSource(input.source, dir);
+    const sourcePath = resolveInputSource(input.source, dir, projectRoot);
     if (!existsSync(sourcePath)) {
       throw new Error(`codegen input not found: ${input.source}`);
     }
@@ -336,9 +337,16 @@ function generatePackage(
  * `codegen` field. Returns the package dirs it wrote so the caller can rebuild
  * their barrels. `ts-to-zod` + `typescript` are lazy-loaded.
  */
-export function generateCodegen(): string[] {
-  const targets = recordedPackages()
-    .map((p) => ({ dir: p.dir, inputs: codegenInputs(p.dir) }))
+export function generateCodegen(
+  projectRoot: string = resolveRepoRoot(),
+  options: { includeRoot?: boolean } = {},
+): string[] {
+  const packageDirs = [
+    ...(options.includeRoot ? [projectRoot] : []),
+    ...recordedPackages(projectRoot).map((pkg) => pkg.dir),
+  ];
+  const targets = packageDirs
+    .map((dir) => ({ dir, inputs: codegenInputs(dir) }))
     .filter((t): t is { dir: string; inputs: string[] } => t.inputs !== undefined);
 
   // Nothing to generate is the NORMAL case for a workspace that declares no
@@ -356,7 +364,7 @@ export function generateCodegen(): string[] {
 
   const written: string[] = [];
   for (const target of targets) {
-    written.push(generatePackage(tsRuntime, generate, target.dir, target.inputs));
+    written.push(generatePackage(tsRuntime, generate, projectRoot, target.dir, target.inputs));
   }
   return written;
 }

package/src/packages.ts

@@ -30,12 +30,13 @@ import { find } from "@dbx-tools/path";
 import { json, object, string } from "@dbx-tools/shared-core";
 import { parse } from "yaml";
 
-/**
- * The repo root: the nearest package/projenrc root, falling back to the current
- * working directory. Detection (npm prefix, git top-level, root markers) lives
- * in `@dbx-tools/core`'s {@link coreProject.root}.
- */
-export const repoRoot = coreProject.root() ?? process.cwd();
+/** Resolve the nearest package/projenrc root at call time. */
+export function resolveRepoRoot(cwd: string = process.cwd()): string {
+  return coreProject.root(cwd) ?? cwd;
+}
+
+/** Current-process repository root for executable task entrypoints. */
+export const repoRoot = resolveRepoRoot();
 
 /**
  * Default package roots. Each is scanned for packages; override via the
@@ -49,8 +50,8 @@ export const DEFAULT_PACKAGE_ROOTS = ["packages"] as const;
  * {@link coreProject.name}, which is also what a consuming repo's own tooling
  * sees, so the engine and its host agree on the name.
  */
-export function projectName(): string {
-  return coreProject.name(repoRoot);
+export function projectName(projectRoot: string = resolveRepoRoot()): string {
+  return coreProject.name(projectRoot);
 }
 
 const MODULE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
@@ -168,7 +169,7 @@ export class DiscoveredPackage {
 }
 
 /** Read the raw workspace member globs from `pnpm-workspace.yaml` (source of truth). */
-function readRecordedMembers(projectRoot: string = repoRoot): string[] {
+function readRecordedMembers(projectRoot: string = resolveRepoRoot()): string[] {
   const file = resolve(projectRoot, "pnpm-workspace.yaml");
   if (!existsSync(file)) return [];
   const doc = parse(readFileSync(file, "utf8")) as {
@@ -218,7 +219,7 @@ function collectPackageDirs(rootAbs: string): string[] {
  * recorded set. Sorted by member path.
  */
 export function scanPackages(
-  projectRoot: string = repoRoot,
+  projectRoot: string = resolveRepoRoot(),
   roots: readonly string[] = DEFAULT_PACKAGE_ROOTS,
 ): DiscoveredPackage[] {
   const out: DiscoveredPackage[] = [];
@@ -285,7 +286,7 @@ function readManifestTags(dir: string): string[] | undefined {
  * the root `package.json` `dbxToolsConfig.syncResynthPaths` (set via the
  * {@link DBXToolsProjectOptions.syncResynthPaths} option at synth).
  */
-export function syncResynthPaths(projectRoot: string = repoRoot): string[] {
+export function syncResynthPaths(projectRoot: string = resolveRepoRoot()): string[] {
   const paths = readDbxToolsConfig(projectRoot)?.syncResynthPaths;
   return Array.isArray(paths) ? string.parseList(paths.map((p) => String(p))) : [];
 }
@@ -297,7 +298,7 @@ export function syncResynthPaths(projectRoot: string = repoRoot): string[] {
  * authoritative, so it reflects the resolved tag set.
  * Sorted by path.
  */
-export function recordedPackages(projectRoot: string = repoRoot): RecordedPackage[] {
+export function recordedPackages(projectRoot: string = resolveRepoRoot()): RecordedPackage[] {
   const out: RecordedPackage[] = [];
   for (const member of readRecordedMembers(projectRoot)) {
     const pkg = packageOfMember(projectRoot, member);
@@ -318,7 +319,7 @@ export function recordedPackages(projectRoot: string = repoRoot): RecordedPackag
  * that field fall back to the distinct first segment of every recorded member,
  * unioned with the defaults.
  */
-export function recordedRoots(projectRoot: string = repoRoot): string[] {
+export function recordedRoots(projectRoot: string = resolveRepoRoot()): string[] {
   const configured = readDbxToolsConfig(projectRoot)?.packageRoots;
   if (Array.isArray(configured)) {
     const roots = string.parseList(configured.map((root) => String(root)));