@dbx-tools/projen 0.9.95 → 0.9.105

package/README.md

@@ -2,23 +2,8 @@
 
 Projen engine for Bun-first dbx-tools workspaces.
 
-Import this package from `.projenrc.ts` when a repository should discover
-packages from the filesystem and generate manifests, tsconfigs,
-barrels, codegen outputs, and release tasks.
-
-Key features:
-
-- Filesystem package discovery: every `src`-bearing folder under configured
-  workspace roots becomes a TypeScript package.
-- Tag-driven runtime defaults for shared libraries, Node packages, CLIs,
-  servers, and React/browser UI packages.
-- Generated package manifests, tsconfigs, package-root barrels, Bun app configs,
-  VS Code settings, and a committed `pnpm-workspace.yaml` retained for
-  Databricks Apps deployment.
-- Extensible mixin system so repositories can add deps, tasks, or generated
-  files based on package predicates.
-- Zod schema generation from `.d.ts` inputs.
-- Read-only generated-file ownership, cleanup, and watch-loop helpers.
+Use it from `.projenrc.ts` to discover packages from the filesystem and generate
+manifests, tsconfigs, barrels, code generation, and release tasks.
 
 ## Define A Workspace Root
 
@@ -34,6 +19,11 @@ const rootProject = new project.DBXToolsNodeProject({
 rootProject.synth();
 ```
 
+The project discovers every `src`-bearing folder under the configured roots and
+applies defaults for shared libraries, Node packages, CLIs, servers, and React
+packages. It can also generate Zod schemas from declarations and coordinate
+generated-file cleanup and watch tasks.
+
 Every `src`-bearing folder under the configured roots becomes a
 `DBXToolsTypeScriptProject`. Folder path drives package name and runtime tags.
 
@@ -338,6 +328,22 @@ wrong fix, since the consumer authors no JSX and cannot know a transitive
 dependency started to. The option is inert without JSX in the graph: it selects
 how JSX syntax compiles and adds no lib, global, or type dependency.
 
+Keep the generated tsconfigs package-local. Each package build config owns its
+`rootDir`, declaration output, package-specific globals, and publish boundary.
+Projen also places a no-emit config in each `test/` directory so TypeScript 6,
+editors, and type-aware ESLint resolve the nearest project for test files. A
+single config per runtime folder would merge package output boundaries and would
+remove that nearest-config behavior. The runtime tag mixins already centralize
+the environment differences without replacing the package configs.
+
+Compilation preserves TypeScript's incremental cache. The root compile task
+passes the package configs to batched `tsc --build` processes, and each config
+retains its own `tsconfig.tsbuildinfo`. Synthesis also retains Projen's native
+change detection: unchanged generated files are not rewritten, and dependency
+installation runs only when the generated root manifest changes or
+`node_modules` is absent. Repository discovery is process-cached so every child
+package reuses the root probe instead of invoking `git`, `ssh`, and `gh` again.
+
 ## Work With Package Discovery
 
 ```ts
@@ -497,6 +503,8 @@ bun run release --publish local --install never
 bun run release --local-registry false --local-pypi auto
 bun run release --demo-deploy
 bun run release --no-release-notes
+bun run release --release-notes-text "# Release 1.2.3"
+bun run release --release-notes-file ./notes.md
 bun run release --release-notes-instructions "Focus on operator-visible changes."
 ```
 
@@ -512,6 +520,8 @@ After bump and configured validation, release writes
 --ephemeral -o`. The standard prompt forbids running tests or other validation
 commands. If Genie fails or writes an empty file, the step keeps going with a
 short git-log summary. `--no-release-notes` skips the file.
+`--release-notes-text` writes supplied markdown directly, while
+`--release-notes-file` copies a prepared markdown file. Both bypass Genie.
 `--release-notes-instructions` appends run-specific guidance to the standard
 Genie prompt. Notes are committed with the version bump and are not recorded in
 the annotated tag. They are skipped on `--no-bump` because that path requires an
@@ -522,7 +532,8 @@ already committed tree.
 installed while still regenerating versioned sources. Local release validation
 runs `eslint:fix` before branch preparation and bump, then runs the selected
 fail-closed tasks; CI remains check-only.
-`--no-validation` skips optional task checks locally and in CI, not version or immutable-source checks.
+CI rebuilds the selected release artifacts instead of checking generated-source fingerprints.
+`--no-validation` skips optional task checks locally and in CI, not workspace-version or immutable-source checks.
 `--no-docs` skips building and deploying the site, not package README validation.
 Scopes select artifacts, not the normal commit and tag-push transaction.
 The annotated tag records CI step selections, so publishing a selected scope does
@@ -588,8 +599,10 @@ release [options]
 | `--no-pypi`                           | skip Python build and publication, including local Python publication                         |
 | `--docs`                              | build and deploy docs for a selected scope                                                    |
 | `--no-docs`                           | skip documentation build and deployment                                                       |
-| `--no-validation`                     | skip optional release validation tasks; version/source checks remain mandatory                |
+| `--no-validation`                     | skip optional release validation tasks; workspace version checks remain mandatory             |
 | `--no-release-notes`                  | skip writing docs/releases notes (Genie and git-log fallback)                                 |
+| `--release-notes-text <markdown>`     | write supplied markdown without invoking Genie                                                |
+| `--release-notes-file <path>`         | copy supplied markdown without invoking Genie                                                 |
 | `--release-notes-instructions <text>` | append custom instructions to the Genie release-notes prompt                                  |
 | `--demo-deploy`                       | after tagging, stage and deploy the AppKit demo app (off by default)                          |
 | `--profile <name>`                    | Databricks CLI profile for --demo-deploy                                                      |

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.9.95";
+export const PACKAGE_VERSION = "0.9.105";
 export * as barrels from "./src/barrels.ts";
 export * as bunApp from "./src/bun-app.ts";
 export * as bunWorkflow from "./src/bun-workflow.ts";

package/package.json

@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/core": "^0.9.95",
-    "@dbx-tools/path": "^0.9.95",
-    "@dbx-tools/shared-core": "^0.9.95",
+    "@dbx-tools/core": "^0.9.105",
+    "@dbx-tools/path": "^0.9.105",
+    "@dbx-tools/shared-core": "^0.9.105",
     "commander": "^15.0.0",
     "concurrently": "^10.0.3",
     "constructs": "^10.6.0",
@@ -54,7 +54,7 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.9.95",
+  "version": "0.9.105",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/project-js.ts

@@ -12,7 +12,7 @@ import * as projectUtils from "@dbx-tools/core/project-utils";
 import { ignore, match } from "@dbx-tools/path";
 import { object, stringUtils, type OneOrMany } from "@dbx-tools/shared-core";
 import { type IConstruct } from "constructs";
-import { Component, LogLevel, Project, javascript, typescript } from "projen";
+import { Component, LogLevel, Project, type Task, javascript, typescript } from "projen";
 import { JobPermission, type JobStep } from "projen/lib/github/workflows-model";
 import type { ReleaseProjectOptions } from "projen/lib/release";
 import { generateBarrels } from "./barrels.ts";
@@ -587,7 +587,6 @@ export type DBXToolsJavaScriptProjectOptions = CommonProjectOptions &
     /** Release build prerequisites installed before repository validation tasks. */
     readonly releaseSetupSteps?: readonly JobStep[];
     /** Repository-specific synthesis commands run before release source verification. */
-    readonly releaseSynthesisCommands?: readonly string[];
     /** Set to `false` to omit normal npm workspace publication. */
     readonly nodeRelease?: boolean;
     /** Unified dbx-tools release workflow, or no release surface. Defaults to `dbx-tools`. */
@@ -605,8 +604,9 @@ export type DBXToolsJavaScriptProjectOptions = CommonProjectOptions &
     readonly extraWorkspaceMembers?: readonly string[];
     /**
      * Install workspace dependencies once from the custom root instead of once
-     * per child project during post-synthesis. Defaults to `true`; set `false` to
-     * preserve projen's native per-project install tasks.
+     * per child project during post-synthesis. Defaults to `true`; set `false`
+     * on the root to preserve every native child install, or on an individual
+     * child to retain that package's native install lifecycle.
      */
     readonly rootInstallOnly?: boolean;
   };
@@ -636,7 +636,7 @@ export class DBXToolsNodeProject
   rootTsconfig?: DBXToolsRootTsconfig;
   readonly extraWorkspaceMembers: readonly string[];
   readonly releaseBranch: string;
-  private readonly rootInstallOnly: boolean;
+  readonly rootInstallOnly: boolean;
 
   constructor(options: DBXToolsJavaScriptProjectOptions = {}) {
     validateReleaseOptions(options);
@@ -684,18 +684,67 @@ export class DBXToolsNodeProject
  *
  * Every projen child has its own `NodePackage` post-synth hook, which otherwise
  * runs the install task against the same root workspace once per package. Clear
- * the public child install tasks while leaving dependency resolution and the
- * root's real install/install:ci tasks intact. Applied in root `preSynthesize`
- * so manually attached late children are included and repeated synths remain
- * idempotent.
+ * the public child install tasks and suppress Projen's protected install hook,
+ * while leaving the rest of `NodePackage.postSynthesize` (including dependency
+ * resolution) and the root's real install/install:ci tasks intact. A child can
+ * set `rootInstallOnly: false` when it owns a package-local dependency tree.
+ * Applied in root `preSynthesize` so manually attached late children are
+ * included and repeated synths remain idempotent.
  */
+class RootInstallOnlyChild extends Component {
+  private readonly child: DBXToolsNodeProject | DBXToolsTypeScriptProject;
+  private readonly installDependencies: (trigger: unknown) => void;
+  private suppressed = false;
+
+  constructor(child: DBXToolsNodeProject | DBXToolsTypeScriptProject) {
+    super(child, "RootInstallOnly");
+    this.child = child;
+    const nodePackage = child.package as unknown as {
+      installDependencies(trigger: unknown): void;
+    };
+    if (typeof nodePackage.installDependencies !== "function") {
+      throw new Error("Projen NodePackage no longer exposes installDependencies");
+    }
+    this.installDependencies = nodePackage.installDependencies;
+  }
+
+  public override preSynthesize(): void {
+    const nodePackage = this.child.package as unknown as {
+      installDependencies(trigger: unknown): void;
+    };
+    if (
+      hasCustomInstallSteps(
+        this.child.package.installTask,
+        this.child.package.installAndUpdateLockfileCommand,
+      ) ||
+      hasCustomInstallSteps(this.child.package.installCiTask, this.child.package.installCommand)
+    ) {
+      if (this.suppressed) nodePackage.installDependencies = this.installDependencies;
+      this.suppressed = false;
+      return;
+    }
+    this.child.package.installTask.reset();
+    this.child.package.installCiTask.reset();
+    nodePackage.installDependencies = () => {};
+    this.suppressed = true;
+  }
+}
+
+function hasCustomInstallSteps(task: Task, defaultCommand: string): boolean {
+  if (task.steps.length === 0) return false;
+  if (task.steps.length !== 1) return true;
+  const step = task.steps[0]!;
+  return step.exec !== defaultCommand;
+}
+
+/** Suppress redundant child install tasks when the workspace root owns dependency installation. */
 export const ROOT_INSTALL_ONLY_MIXIN = mixin.create(
   (construct: IConstruct): construct is DBXToolsNodeProject | DBXToolsTypeScriptProject =>
     (construct instanceof DBXToolsNodeProject || construct instanceof DBXToolsTypeScriptProject) &&
-    construct.parent !== undefined,
+    construct.parent !== undefined &&
+    construct.rootInstallOnly,
   (child) => {
-    child.package.installTask.reset();
-    child.package.installCiTask.reset();
+    if (!child.node.tryFindChild("RootInstallOnly")) new RootInstallOnlyChild(child);
   },
 );
 
@@ -717,7 +766,7 @@ export class DBXToolsTypeScriptProject
   rootTsconfig?: DBXToolsRootTsconfig;
   readonly extraWorkspaceMembers: readonly string[];
   readonly releaseBranch: string;
-  private readonly rootInstallOnly: boolean;
+  readonly rootInstallOnly: boolean;
 
   constructor(options: DBXToolsTypeScriptProjectOptions) {
     validateReleaseOptions(options);
@@ -1331,7 +1380,6 @@ function initProject(
       pythonRoot: options.releasePythonRoot,
       validationTasks: options.releaseValidationTasks,
       setupSteps: options.releaseSetupSteps,
-      synthesisCommands: options.releaseSynthesisCommands,
     });
   }
 }

package/src/python-node-bindings.ts

@@ -1,14 +1,58 @@
 /** Shared pyproject-backed configuration for PythonMonkey Node bindings. */
-import { readFileSync, realpathSync, rmSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, realpathSync, rmSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { find } from "@dbx-tools/path";
 import { object, stringUtils } from "@dbx-tools/shared-core";
 import { parse } from "smol-toml";
 import ts from "typescript";
 import { runTaskCommand } from "./_task-command.ts";
+import { makeReadonly } from "./generated.ts";
+import { publicFunctionExports, publicNamespaceExports } from "./module-exports.ts";
 import { resolveRepoRoot, workspaceDependencyDirectories } from "./packages.ts";
 
+const FINGERPRINT_VERSION = 5;
+const INPUT_FINGERPRINT_LABEL = "dbx-tools binding inputs sha256";
+const CONTENT_FINGERPRINT_LABEL = "dbx-tools binding content sha256";
+const PYTHON_KEYWORDS = new Set([
+  "and",
+  "as",
+  "assert",
+  "async",
+  "await",
+  "break",
+  "class",
+  "continue",
+  "def",
+  "del",
+  "elif",
+  "else",
+  "except",
+  "False",
+  "finally",
+  "for",
+  "from",
+  "global",
+  "if",
+  "import",
+  "in",
+  "is",
+  "lambda",
+  "None",
+  "nonlocal",
+  "not",
+  "or",
+  "pass",
+  "raise",
+  "return",
+  "True",
+  "try",
+  "while",
+  "with",
+  "yield",
+]);
+
 /** Resolved function replacement consumed while generating one PythonMonkey bundle. */
 export interface ResolvedPythonNodeFunctionOverride {
   readonly handlerExport: string;
@@ -38,6 +82,8 @@ export interface ResolvedPythonNodeBindings {
 export interface GeneratePythonNodeBindingsOptions {
   /** Verify generated output without changing it. */
   readonly check?: boolean;
+  /** Regenerate outputs without consulting fingerprints. */
+  readonly force?: boolean;
 }
 
 /** Generate or verify every pyproject-configured Node binding in a repository. */
@@ -46,10 +92,14 @@ export function generatePythonNodeBindings(
   options: GeneratePythonNodeBindingsOptions = {},
 ): void {
   const task = resolve(dirname(fileURLToPath(import.meta.url)), "../tasks/python-node-bindings.ts");
-  const configuredProjects = pythonNodeBindingProjects(projectRoot);
+  const force = options.force ?? process.env.CI === "true";
+  const configuredProjects = pythonNodeBindingProjects(projectRoot).map((project) => ({
+    project,
+    configs: resolvePythonNodeBindings(projectRoot, project).map(resolvePythonNodeBindingModules),
+  }));
   const directories = new Set<string>();
-  for (const project of configuredProjects) {
-    for (const config of resolvePythonNodeBindings(projectRoot, project)) {
+  for (const { configs } of configuredProjects) {
+    for (const config of configs) {
       directories.add(relative(projectRoot, join(config.moduleDirectory, "_generated", "node")));
     }
   }
@@ -64,7 +114,12 @@ export function generatePythonNodeBindings(
   for (const directory of stale) {
     rmSync(resolve(projectRoot, directory), { recursive: true, force: true });
   }
-  for (const project of configuredProjects) {
+  for (const { configs, project } of configuredProjects) {
+    const inputFingerprint = pythonNodeBindingInputFingerprint(projectRoot, configs);
+    if (!force && pythonNodeBindingOutputsCurrent(configs, inputFingerprint)) {
+      for (const output of pythonNodeBindingOutputs(configs)) makeReadonly(output);
+      continue;
+    }
     runTaskCommand(projectRoot, "bun", [
       task,
       "--root",
@@ -72,10 +127,194 @@ export function generatePythonNodeBindings(
       "--project",
       project,
       ...(options.check ? ["--check"] : []),
+      ...(force ? ["--force"] : []),
     ]);
   }
 }
 
+/** Resolve automatically discovered bindable namespaces for one configured package. */
+export function resolvePythonNodeBindingModules(
+  config: ResolvedPythonNodeBindings,
+): ResolvedPythonNodeBindings {
+  if (config.modules.length > 0) return config;
+  const packageEntrypoint = Bun.resolveSync(config.entrypoint, config.projectDirectory);
+  const modules = publicNamespaceExports(packageEntrypoint).filter(
+    (module) =>
+      publicFunctionExports(resolvePythonNodeBindingModule(packageEntrypoint, module)).length > 0,
+  );
+  return { ...config, modules };
+}
+
+/** Map a JavaScript export or namespace to its generated Python identifier. */
+export function pythonNodeBindingFunctionName(javascriptName: string): string {
+  const name = stringUtils.toIdentifierWithOptions({ delimiter: "_" }, javascriptName);
+  if (!isPythonNodeBindingIdentifier(name)) {
+    throw new Error(
+      `JavaScript export ${javascriptName} does not map to a valid Python function name`,
+    );
+  }
+  return name;
+}
+
+/** Whether a value is a legal non-keyword Python identifier. */
+export function isPythonNodeBindingIdentifier(value: string): boolean {
+  return /^[_A-Za-z]\w*$/.test(value) && !PYTHON_KEYWORDS.has(value);
+}
+
+/** Content fingerprint for every source and toolchain input affecting generated bindings. */
+export function pythonNodeBindingInputFingerprint(
+  root: string,
+  configs: readonly ResolvedPythonNodeBindings[],
+): string {
+  const canonicalRoot = canonicalPath(root);
+  const fingerprintPath = (path: string): string => relative(canonicalRoot, canonicalPath(path));
+  const sourceFile = canonicalPath(fileURLToPath(import.meta.url));
+  const sourceDirectory = dirname(sourceFile);
+  const files = new Set<string>([
+    sourceFile,
+    canonicalPath(resolve(sourceDirectory, "../tasks/python-node-bindings.ts")),
+    canonicalPath(join(sourceDirectory, "generated.ts")),
+    canonicalPath(join(sourceDirectory, "module-exports.ts")),
+    canonicalPath(join(sourceDirectory, "packages.ts")),
+    canonicalPath(join(sourceDirectory, "python-node-runtime.ts")),
+  ]);
+  const versionFile = join(root, "VERSION");
+  if (existsSync(versionFile)) files.add(canonicalPath(versionFile));
+  for (const config of configs) {
+    for (const input of config.watchInputs) files.add(canonicalPath(resolve(root, input)));
+    for (const { handlerFile } of config.functionOverrides) files.add(canonicalPath(handlerFile));
+    const packageEntrypoint = canonicalPath(
+      Bun.resolveSync(config.entrypoint, config.projectDirectory),
+    );
+    files.add(packageEntrypoint);
+    const packageManifest = nearestPackageManifest(packageEntrypoint);
+    if (packageManifest) files.add(canonicalPath(packageManifest));
+    for (const module of config.modules) {
+      files.add(canonicalPath(resolvePythonNodeBindingModule(packageEntrypoint, module)));
+    }
+  }
+
+  const hash = createHash("sha256");
+  hash.update(
+    JSON.stringify({
+      configs: configs.map((config) => ({
+        bindingDirectory: fingerprintPath(config.bindingDirectory),
+        bindingName: config.bindingName,
+        entrypoint: config.entrypoint,
+        functionOverrides: config.functionOverrides.map((override) => ({
+          handlerExport: override.handlerExport,
+          handlerFile: fingerprintPath(override.handlerFile),
+          targetExport: override.targetExport,
+          targetModule: override.targetModule,
+        })),
+        moduleDirectory: fingerprintPath(config.moduleDirectory),
+        modules: config.modules,
+        package: config.package,
+        project: config.project,
+        runtimeOutput: fingerprintPath(config.runtimeOutput),
+      })),
+      format: FINGERPRINT_VERSION,
+    }),
+  );
+  for (const { file, path } of [...files]
+    .map((file) => ({ file, path: fingerprintPath(file) }))
+    .sort((left, right) => left.path.localeCompare(right.path))) {
+    hash.update("\0file\0");
+    hash.update(path);
+    hash.update("\0");
+    hash.update(existsSync(file) ? readFileSync(file) : "<missing>");
+  }
+  return hash.digest("hex");
+}
+
+/** Complete generated output set for one Python project's Node bindings. */
+export function pythonNodeBindingOutputs(configs: readonly ResolvedPythonNodeBindings[]): string[] {
+  const nodeDirectory = pythonNodeBindingDirectory(configs);
+  return [
+    join(nodeDirectory, "_runtime.js"),
+    join(nodeDirectory, "_runtime.py"),
+    ...configs.flatMap((config) =>
+      config.modules.length > 0
+        ? config.modules.map((module) =>
+            join(config.bindingDirectory, `${pythonNodeBindingFunctionName(module)}.py`),
+          )
+        : [join(config.bindingDirectory, "index.py")],
+    ),
+  ].sort();
+}
+
+/** Whether all expected outputs exactly match their input and body fingerprints. */
+export function pythonNodeBindingOutputsCurrent(
+  configs: readonly ResolvedPythonNodeBindings[],
+  inputFingerprint: string,
+): boolean {
+  const generatedPackage = join(configs[0]!.moduleDirectory, "_generated", "__init__.py");
+  if (existsSync(generatedPackage)) return false;
+  const expected = pythonNodeBindingOutputs(configs);
+  const actual = filesBelow(pythonNodeBindingDirectory(configs)).sort();
+  if (actual.length !== expected.length || actual.some((file, index) => file !== expected[index])) {
+    return false;
+  }
+  return expected.every((output) => pythonNodeBindingFingerprintCurrent(output, inputFingerprint));
+}
+
+/** Prefix generated output with its input fingerprint and a self-validating body digest. */
+export function fingerprintPythonNodeBindingOutput(
+  contents: string,
+  inputFingerprint: string,
+  output: string,
+): string {
+  const prefix = output.endsWith(".py") ? "#" : "//";
+  const contentFingerprint = createHash("sha256").update(contents).digest("hex");
+  return [
+    `${prefix} ${INPUT_FINGERPRINT_LABEL}: ${inputFingerprint}`,
+    `${prefix} ${CONTENT_FINGERPRINT_LABEL}: ${contentFingerprint}`,
+    contents,
+  ].join("\n");
+}
+
+function pythonNodeBindingDirectory(configs: readonly ResolvedPythonNodeBindings[]): string {
+  const moduleDirectory = configs[0]?.moduleDirectory;
+  if (!moduleDirectory) throw new Error("Expected at least one Node binding configuration");
+  return join(moduleDirectory, "_generated", "node");
+}
+
+function pythonNodeBindingFingerprintCurrent(output: string, inputFingerprint: string): boolean {
+  try {
+    const [inputLine, contentLine, ...bodyLines] = readFileSync(output, "utf8").split("\n");
+    const prefix = output.endsWith(".py") ? "#" : "//";
+    if (inputLine !== `${prefix} ${INPUT_FINGERPRINT_LABEL}: ${inputFingerprint}`) return false;
+    const escapedPrefix = prefix === "//" ? "\\/\\/" : "#";
+    const expectedContent = contentLine?.match(
+      new RegExp(`^${escapedPrefix} ${CONTENT_FINGERPRINT_LABEL}: ([a-f0-9]{64})$`),
+    )?.[1];
+    if (!expectedContent) return false;
+    return createHash("sha256").update(bodyLines.join("\n")).digest("hex") === expectedContent;
+  } catch {
+    return false;
+  }
+}
+
+function filesBelow(directory: string): string[] {
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.name === "__pycache__" || entry.name.endsWith(".pyc")) return [];
+    const path = join(directory, entry.name);
+    return entry.isDirectory() ? filesBelow(path) : [path];
+  });
+}
+
+function nearestPackageManifest(path: string): string | undefined {
+  let directory = dirname(path);
+  while (true) {
+    const manifest = join(directory, "package.json");
+    if (existsSync(manifest)) return manifest;
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
 /** Resolve every configured binding in a repository. */
 export function resolveAllPythonNodeBindings(
   projectRoot: string = resolveRepoRoot(),
@@ -102,16 +341,28 @@ export function pythonNodeBindingProjects(projectRoot: string): string[] {
 
 function existingBindingDirectories(projectRoot: string): string[] {
   const directories = new Set<string>();
-  for (const file of find.findFiles("**/_generated/node/**/*", {
-    cwd: projectRoot,
-    ignore: () => false,
-  })) {
-    const segments = file.split("/");
-    const generated = segments.lastIndexOf("_generated");
-    if (generated >= 0 && segments[generated + 1] === "node") {
-      directories.add(segments.slice(0, generated + 2).join("/"));
+  const ignored = new Set([
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "__pycache__",
+    "dist",
+    "node_modules",
+  ]);
+  const visit = (directory: string): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (!entry.isDirectory() || ignored.has(entry.name)) continue;
+      const path = join(directory, entry.name);
+      if (entry.name === "node" && basename(directory) === "_generated") {
+        directories.add(relative(projectRoot, path));
+        continue;
+      }
+      visit(path);
     }
-  }
+  };
+  visit(projectRoot);
   return [...directories].sort();
 }
 
@@ -192,16 +443,23 @@ type BindingSourceConfig = Omit<ResolvedPythonNodeBindings, "watchInputs">;
 
 /** Transitive workspace source files reachable from configured binding modules. */
 function bindingSourceInputs(root: string, config: BindingSourceConfig): string[] {
-  const allowed = config.workspaceDirectories.map(canonicalPath);
   const packageEntrypoint = Bun.resolveSync(config.entrypoint, config.projectDirectory);
   const entrypoints =
     config.modules.length > 0
       ? config.modules.map((module) => resolvePythonNodeBindingModule(packageEntrypoint, module))
       : [packageEntrypoint];
-  const pending = [
-    ...entrypoints,
-    ...config.functionOverrides.map(({ handlerFile }) => handlerFile),
-  ];
+  return transitiveSourceFiles(
+    [...entrypoints, ...config.functionOverrides.map(({ handlerFile }) => handlerFile)],
+    config.workspaceDirectories,
+  ).map((path) => relative(root, path));
+}
+
+function transitiveSourceFiles(
+  entrypoints: readonly string[],
+  allowedDirectories: readonly string[],
+): string[] {
+  const allowed = allowedDirectories.map(canonicalPath);
+  const pending = [...entrypoints];
   const visited = new Set<string>();
   while (pending.length > 0) {
     const candidate = canonicalPath(pending.pop()!);
@@ -227,7 +485,7 @@ function bindingSourceInputs(root: string, config: BindingSourceConfig): string[
       }
     }
   }
-  return [...visited].sort().map((path) => relative(root, path));
+  return [...visited].sort();
 }
 
 /** Resolve one configured namespace from a package entrypoint barrel. */
@@ -247,10 +505,17 @@ export function resolvePythonNodeBindingModule(entrypoint: string, module: strin
 }
 
 function canonicalPath(path: string): string {
-  try {
-    return realpathSync(path);
-  } catch {
-    return resolve(path);
+  const missing: string[] = [];
+  let candidate = resolve(path);
+  while (true) {
+    try {
+      return resolve(realpathSync(candidate), ...missing);
+    } catch {
+      const parent = dirname(candidate);
+      if (parent === candidate) return resolve(path);
+      missing.unshift(basename(candidate));
+      candidate = parent;
+    }
   }
 }
 

package/src/release.ts

@@ -51,8 +51,6 @@ export interface DBXToolsReleaseOptions {
   readonly validationTasks?: readonly string[];
   /** Repository prerequisites installed before release validation and artifact builds. */
   readonly setupSteps?: readonly JobStep[];
-  /** Repository-specific synthesis commands run before the root Projen synthesis check. */
-  readonly synthesisCommands?: readonly string[];
 }
 
 /** Locate the unified workflow when release generation is enabled. */
@@ -204,14 +202,6 @@ function releaseBuildJob(
           // ============================================================================
         ),
       },
-      {
-        name: "Verify generated sources",
-        run: [
-          ...(options.synthesisCommands ?? []),
-          "bunx projen",
-          "git diff --ignore-space-at-eol --exit-code",
-        ].join("\n"),
-      },
       { name: "Verify workspace versions", run: "bun run version:check" },
       ...(options.setupSteps ?? []),
       ...releaseBuildSteps(

package/src/tsconfig.ts

@@ -55,7 +55,7 @@ export class DBXToolsRootTsconfig extends Component {
       extends: javascript.TypescriptConfigExtends.fromTypescriptConfigs([this.base]),
       compilerOptions: {
         lib: ["ESNext"],
-        types: ["node"],
+        types: ["node", "bun"],
       },
       include: [".projenrc.ts"],
       exclude: ["node_modules", "**/dist", "**/node_modules"],

package/tasks/bump.ts

@@ -35,6 +35,11 @@ export async function main(): Promise<void> {
 
       if (opts.synth) {
         runTaskCommand(root, process.execPath, [".projenrc.ts"]);
+        // Package manifests are generated during the first synthesis, while
+        // cross-package derived artifacts can read those manifests earlier in
+        // the same pass. A second pass makes the new version visible to every
+        // generator and leaves release validation on a converged tree.
+        runTaskCommand(root, process.execPath, [".projenrc.ts"]);
       }
       logger.success(`workspace version synchronized at ${next.version}`);
     });

package/tasks/python-node-bindings.ts

@@ -12,11 +12,18 @@ import type { BunPlugin } from "bun";
 import stdLibBrowser from "node-stdlib-browser";
 import ts from "typescript";
 import { header, makeReadonly, makeWritable } from "../src/generated.ts";
-import { publicFunctionExports, publicNamespaceExports } from "../src/module-exports.ts";
+import { publicFunctionExports } from "../src/module-exports.ts";
 import { resolveRepoRoot } from "../src/packages.ts";
 import {
   generatePythonNodeBindings,
+  fingerprintPythonNodeBindingOutput,
+  isPythonNodeBindingIdentifier,
+  pythonNodeBindingFunctionName as pythonFunctionName,
+  pythonNodeBindingInputFingerprint,
+  pythonNodeBindingOutputs,
+  pythonNodeBindingOutputsCurrent,
   resolvePythonNodeBindingModule,
+  resolvePythonNodeBindingModules,
   resolvePythonNodeBindings,
   type ResolvedPythonNodeBindings,
   type ResolvedPythonNodeFunctionOverride,
@@ -35,50 +42,13 @@ function bindingIndex(value: string, count: number, project: string): number {
   return index;
 }
 
-const PYTHON_KEYWORDS = new Set([
-  "and",
-  "as",
-  "assert",
-  "async",
-  "await",
-  "break",
-  "class",
-  "continue",
-  "def",
-  "del",
-  "elif",
-  "else",
-  "except",
-  "False",
-  "finally",
-  "for",
-  "from",
-  "global",
-  "if",
-  "import",
-  "in",
-  "is",
-  "lambda",
-  "None",
-  "nonlocal",
-  "not",
-  "or",
-  "pass",
-  "raise",
-  "return",
-  "True",
-  "try",
-  "while",
-  "with",
-  "yield",
-]);
-
 export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
   const { values } = parseArgs({
     args,
     options: {
       binding: { type: "string" },
       check: { type: "boolean" },
+      force: { type: "boolean" },
       module: { type: "string" },
       project: { type: "string" },
       root: { type: "string" },
@@ -89,11 +59,13 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     if (values.binding !== undefined || values.module !== undefined) {
       throw new Error("--binding and --module require --project");
     }
-    generatePythonNodeBindings(root, { check: values.check });
+    generatePythonNodeBindings(root, { check: values.check, force: values.force });
     return;
   }
 
-  const configs = resolvePythonNodeBindings(root, values.project).map(discoverBindingModules);
+  const configs = resolvePythonNodeBindings(root, values.project).map(
+    resolvePythonNodeBindingModules,
+  );
   if (configs.length > 1 && configs.some(({ modules }) => modules.length === 0)) {
     throw new Error(
       "Every Node binding must export a namespace with bindable functions or configure modules",
@@ -105,6 +77,18 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
       : bindingIndex(values.binding, configs.length, values.project);
   const config = selectedBinding === undefined ? configs[0] : configs[selectedBinding];
   if (!config) throw new Error("Expected at least one Node binding configuration");
+  const inputFingerprint = pythonNodeBindingInputFingerprint(root, configs);
+  if (
+    selectedBinding === undefined &&
+    !values.force &&
+    pythonNodeBindingOutputsCurrent(configs, inputFingerprint)
+  ) {
+    for (const output of pythonNodeBindingOutputs(configs)) makeReadonly(output);
+    if (values.check) {
+      logger.info(`verified ${relative(root, dirname(config.runtimeOutput))} from fingerprints`);
+    }
+    return;
+  }
   if (selectedBinding === undefined && (configs.length > 1 || config.modules.length > 0)) {
     prepareBindingDirectory(configs);
     writeRuntimeLoader(configs);
@@ -115,6 +99,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
           values.project,
           ...(values.root ? ["--root", values.root] : []),
           ...(values.check ? ["--check"] : []),
+          ...(values.force ? ["--force"] : []),
           "--binding",
           String(binding),
           "--module",
@@ -217,9 +202,9 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     const entrypoint = Bun.resolveSync(binding.entrypoint, binding.projectDirectory);
     return binding.modules.length > 0
       ? binding.modules.map((module) => ({
-        key: runtimeModuleName(binding, module),
-        entrypoint: resolvePythonNodeBindingModule(entrypoint, module),
-      }))
+          key: runtimeModuleName(binding, module),
+          entrypoint: resolvePythonNodeBindingModule(entrypoint, module),
+        }))
       : [{ key: runtimeModuleName(binding), entrypoint }];
   });
   const runtimeExports = [
@@ -304,18 +289,6 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
   }
   await generate();
 
-  function discoverBindingModules(
-    candidate: ResolvedPythonNodeBindings,
-  ): ResolvedPythonNodeBindings {
-    if (candidate.modules.length > 0) return candidate;
-    const packageEntrypoint = Bun.resolveSync(candidate.entrypoint, candidate.projectDirectory);
-    const modules = publicNamespaceExports(packageEntrypoint).filter(
-      (module) =>
-        publicFunctionExports(resolvePythonNodeBindingModule(packageEntrypoint, module)).length > 0,
-    );
-    return { ...candidate, modules };
-  }
-
   async function generate(): Promise<void> {
     const result = await Bun.build({
       entrypoints: [shimEntry],
@@ -367,8 +340,8 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
         ...bindings.flatMap((binding) => [
           ...(binding.modules.length > 0
             ? binding.modules.map((module) =>
-              join(binding.bindingDirectory, `${pythonFunctionName(module)}.py`),
-            )
+                join(binding.bindingDirectory, `${pythonFunctionName(module)}.py`),
+              )
             : [join(binding.bindingDirectory, "index.py")]),
         ]),
       ].filter((file): file is string => Boolean(file)),
@@ -414,16 +387,6 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     return grouped;
   }
 
-  function pythonFunctionName(javascriptName: string): string {
-    const name = stringUtils.toIdentifierWithOptions({ delimiter: "_" }, javascriptName);
-    if (!/^[_A-Za-z]\w*$/.test(name) || PYTHON_KEYWORDS.has(name)) {
-      throw new Error(
-        `JavaScript export ${javascriptName} does not map to a valid Python function name`,
-      );
-    }
-    return name;
-  }
-
   function runtimeModuleName(binding: ResolvedPythonNodeBindings, module?: string): string {
     return [binding.bindingName, ...(module ? [pythonFunctionName(module)] : [])].join("__");
   }
@@ -987,18 +950,18 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
   function pythonDataclass(record: PythonRecord): string {
     const body = record.fields.length
       ? record.fields
-        .map((field) => {
-          const defaultArgument = Object.hasOwn(field, "defaultValue")
-            ? pythonDefault(field.defaultValue)
-            : "default=None";
-          return [
-            `    ${field.pythonName}: ${pythonOptionalType(field.type)} = field(`,
-            `        ${defaultArgument},`,
-            `        metadata={"javascript_name": ${JSON.stringify(field.javascriptName)}},`,
-            "    )",
-          ].join("\n");
-        })
-        .join("\n")
+          .map((field) => {
+            const defaultArgument = Object.hasOwn(field, "defaultValue")
+              ? pythonDefault(field.defaultValue)
+              : "default=None";
+            return [
+              `    ${field.pythonName}: ${pythonOptionalType(field.type)} = field(`,
+              `        ${defaultArgument},`,
+              `        metadata={"javascript_name": ${JSON.stringify(field.javascriptName)}},`,
+              "    )",
+            ].join("\n");
+          })
+          .join("\n")
       : "    pass";
     return `@dataclass(kw_only=True)\nclass ${record.name}:\n${body}`;
   }
@@ -1026,17 +989,17 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     }
     const body = response.fields.length
       ? response.fields
-        .map(
-          ({ name, required, type }) =>
-            `    ${name}: ${required ? type : `NotRequired[${type}]`}`,
-        )
-        .join("\n")
+          .map(
+            ({ name, required, type }) =>
+              `    ${name}: ${required ? type : `NotRequired[${type}]`}`,
+          )
+          .join("\n")
       : "    pass";
     return `class ${response.name}(TypedDict):\n${body}`;
   }
 
   function isPythonIdentifier(value: string): boolean {
-    return /^[_A-Za-z]\w*$/.test(value) && !PYTHON_KEYWORDS.has(value);
+    return isPythonNodeBindingIdentifier(value);
   }
 
   function pythonProtocol(protocol: PythonProtocol): string {
@@ -1045,18 +1008,18 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     );
     const methods = protocol.methods.length
       ? protocol.methods
-        .map((method) => {
-          const parameters = method.parameters.map(
-            ({ name, required, type }) => `        ${name}: ${type}${required ? "" : " = ..."},`,
-          );
-          return [
-            `    async def ${method.name}(`,
-            "        self,",
-            ...parameters,
-            `    ) -> ${method.returnType}: ...`,
-          ].join("\n");
-        })
-        .join("\n\n")
+          .map((method) => {
+            const parameters = method.parameters.map(
+              ({ name, required, type }) => `        ${name}: ${type}${required ? "" : " = ..."},`,
+            );
+            return [
+              `    async def ${method.name}(`,
+              "        self,",
+              ...parameters,
+              `    ) -> ${method.returnType}: ...`,
+            ].join("\n");
+          })
+          .join("\n\n")
       : "";
     const body = [...properties, methods].filter(Boolean).join("\n\n") || "    pass";
     return `class ${protocol.name}(Protocol):\n${body}`;
@@ -1149,7 +1112,8 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 
   function writeGenerated(output: string, contents: string, kind: string): void {
     const destination = relative(root, output);
-    if (existsSync(output) && readFileSync(output, "utf8") === contents) {
+    const generated = fingerprintPythonNodeBindingOutput(contents, inputFingerprint, output);
+    if (existsSync(output) && readFileSync(output, "utf8") === generated) {
       if (values.check) logger.info(`verified ${destination}`);
       return;
     }
@@ -1158,7 +1122,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     }
     mkdirSync(dirname(output), { recursive: true });
     makeWritable(output);
-    writeFileSync(output, contents);
+    writeFileSync(output, generated);
     makeReadonly(output);
     logger.info(`generated ${destination}`);
   }

package/tasks/release-notes.ts

@@ -8,7 +8,7 @@
  */
 
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { log } from "@dbx-tools/shared-core";
 
 import { captureTaskCommand, tryTaskCommand } from "../src/_task-command.ts";
@@ -20,6 +20,10 @@ const GENIE_PROMPT =
 
 /** Inputs for one notes write. */
 export interface WriteReleaseNotesOptions {
+  /** Complete release-note content supplied by the caller instead of Genie. */
+  readonly content?: string;
+  /** File containing complete release notes supplied by the caller instead of Genie. */
+  readonly file?: string;
   /** Extra agent instructions appended after the standard release-note requirements. */
   readonly instructions?: string;
   readonly prefix: string;
@@ -60,6 +64,25 @@ export function writeReleaseNotes(options: WriteReleaseNotesOptions): string {
   const destination = releaseNotesPath(root, version);
   mkdirSync(dirname(destination), { recursive: true });
   const relative = join("docs", "releases", `v${version}.md`);
+  const suppliedContent = options.content?.trim();
+  const suppliedFile = options.file?.trim();
+  if (suppliedContent && suppliedFile) {
+    throw new Error("release notes content and file are mutually exclusive");
+  }
+  if (options.content !== undefined) {
+    if (!suppliedContent) throw new Error("release notes content must not be empty");
+    writeFileSync(destination, `${suppliedContent}\n`);
+    logger.info("wrote supplied release notes", { path: relative });
+    return destination;
+  }
+  if (options.file !== undefined) {
+    if (!suppliedFile) throw new Error("release notes file must not be empty");
+    const content = readNotes(resolve(root, suppliedFile));
+    if (!content) throw new Error(`release notes file is empty or unreadable: ${suppliedFile}`);
+    writeFileSync(destination, `${content}\n`);
+    logger.info("copied supplied release notes", { path: relative, source: suppliedFile });
+    return destination;
+  }
   const genieArgs = [
     "exec",
     "-C",

package/tasks/release.ts

@@ -236,6 +236,10 @@ export async function runRelease(
     readonly releaseNotes?: boolean;
     /** Additional instructions appended to the standard Genie release-notes prompt. */
     readonly releaseNotesInstructions?: string;
+    /** Complete release notes supplied directly instead of invoking Genie. */
+    readonly releaseNotesText?: string;
+    /** Path to complete release notes supplied instead of invoking Genie. */
+    readonly releaseNotesFile?: string;
     readonly writeReleaseNotes?: typeof writeReleaseNotes;
   },
 ): Promise<string> {
@@ -247,6 +251,21 @@ export async function runRelease(
   if (options.demoDeploy && !demoProfile) {
     throw new Error("--demo-deploy requires --profile <name>");
   }
+  if (options.releaseNotesText !== undefined && options.releaseNotesFile !== undefined) {
+    throw new Error("--release-notes-text and --release-notes-file are mutually exclusive");
+  }
+  if (
+    options.releaseNotesInstructions !== undefined &&
+    (options.releaseNotesText !== undefined || options.releaseNotesFile !== undefined)
+  ) {
+    throw new Error("--release-notes-instructions cannot be combined with supplied release notes");
+  }
+  if (
+    options.releaseNotes === false &&
+    (options.releaseNotesText !== undefined || options.releaseNotesFile !== undefined)
+  ) {
+    throw new Error("--no-release-notes cannot be combined with supplied release notes");
+  }
 
   if (install === "always") runTaskCommand(root, "bun", ["install"]);
   if (selection.validation && hasPackageScript(root, "eslint:fix")) {
@@ -279,6 +298,8 @@ export async function runRelease(
       prefix,
       root,
       version,
+      content: options.releaseNotesText,
+      file: options.releaseNotesFile,
       instructions: options.releaseNotesInstructions,
     });
   }
@@ -380,9 +401,11 @@ export function createReleaseCommand(): Command {
     .option("--no-docs", "skip documentation build and deployment")
     .option(
       "--no-validation",
-      "skip optional release validation tasks; version/source checks remain mandatory",
+      "skip optional release validation tasks; workspace version checks remain mandatory",
     )
     .option("--no-release-notes", "skip writing docs/releases notes (Genie and git-log fallback)")
+    .option("--release-notes-text <markdown>", "write supplied markdown without invoking Genie")
+    .option("--release-notes-file <path>", "copy supplied markdown without invoking Genie")
     .option(
       "--release-notes-instructions <text>",
       "append custom instructions to the Genie release-notes prompt",
@@ -410,6 +433,8 @@ export function createReleaseCommand(): Command {
           profile?: string;
           releaseNotes?: boolean;
           releaseNotesInstructions?: string;
+          releaseNotesText?: string;
+          releaseNotesFile?: string;
         },
       ) => {
         await runRelease({
@@ -433,6 +458,8 @@ export function createReleaseCommand(): Command {
           demoProfile: options.profile,
           releaseNotes: options.releaseNotes,
           releaseNotesInstructions: options.releaseNotesInstructions,
+          releaseNotesText: options.releaseNotesText,
+          releaseNotesFile: options.releaseNotesFile,
         });
       },
     );