@dbx-tools/projen 0.9.61 → 0.9.64

package/README.md

@@ -205,9 +205,11 @@ The workspace creates one repository-wide binding lifecycle:
 - `python-node-bindings` generates every configured bridge.
 - `python-node-bindings:check` verifies generated files and fails on stale
   `_generated/node` directories.
-- `python-node-bindings:watch` watches all configured bridges and regenerates
-  only Python projects affected by a Node package, transitive workspace
-  dependency, binding manifest, or function override change.
+- `python-node-bindings:watch` watches only configured module entrypoints and
+  their transitive workspace source imports. Tests, compiled output, generated
+  bindings, and unrelated modules do not trigger regeneration or acquire the
+  workspace mutation lock. Binding-manifest and generator changes regenerate
+  the affected projects and restart the watcher when its input graph changes.
 
 When a runtime owner is configured, the workspace also creates one shared
 runtime lifecycle:
@@ -483,6 +485,7 @@ 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-instructions "Focus on operator-visible changes."
 ```
 
 `--demo-deploy` is off by default. After tagging and any local registry
@@ -493,14 +496,17 @@ recorded in the annotated tag.
 After bump, release writes `docs/releases/vX.Y.Z.md` with `dbx genie exec -C
 "$PWD" --sandbox read-only --ephemeral -o`. If Genie fails or writes an empty
 file, the step keeps going with a short git-log summary. `--no-release-notes`
-skips the file. 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 already committed tree.
+skips the file. `--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 already committed tree.
 
 `--install auto` keeps Projen's normal local dependency-install behavior;
 `always` performs a manifest-resolved install first, and `never` uses dependencies already
-installed while still regenerating versioned sources. `--no-validation` skips
-optional task checks locally and in CI, not version or immutable-source checks.
+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.
 `--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
@@ -568,6 +574,7 @@ release [options]
 | `--no-docs`                           | skip documentation build and deployment                                                       |
 | `--no-validation`                     | skip optional release validation tasks; version/source checks remain mandatory                |
 | `--no-release-notes`                  | skip writing docs/releases notes (Genie and git-log fallback)                                 |
+| `--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)                          |
 | `--no-local-publish`                  | skip publishing to configured local registries                                                |
 | `--local-registry <auto\|false\|url>` | local npm registry selection (default: "auto")                                                |

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.61";
+export const PACKAGE_VERSION = "0.9.64";
 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.61",
-    "@dbx-tools/path": "^0.9.61",
-    "@dbx-tools/shared-core": "^0.9.61",
+    "@dbx-tools/core": "^0.9.64",
+    "@dbx-tools/path": "^0.9.64",
+    "@dbx-tools/shared-core": "^0.9.64",
     "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.61",
+  "version": "0.9.64",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/python-node-bindings.ts

@@ -1,10 +1,11 @@
 /** Shared pyproject-backed configuration for PythonMonkey Node bindings. */
-import { readFileSync, rmSync } from "node:fs";
+import { readFileSync, realpathSync, rmSync } from "node:fs";
 import { 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 { resolveRepoRoot, workspaceDependencyDirectories } from "./packages.ts";
 
@@ -29,6 +30,7 @@ export interface ResolvedPythonNodeBindings {
   readonly projectDirectory: string;
   readonly pyproject: string;
   readonly runtimeOutput: string;
+  readonly watchInputs: readonly string[];
   readonly workspaceDirectories: readonly string[];
 }
 
@@ -152,7 +154,7 @@ export function resolvePythonNodeBindings(
     }
     const bindingName = nodePackageName(packageName);
     const bindingDirectory = join(moduleDirectory, "_generated", "node", bindingName);
-    return {
+    const resolved = {
       project,
       projectDirectory,
       pyproject,
@@ -177,11 +179,85 @@ export function resolvePythonNodeBindings(
       }),
       workspaceDirectories: workspaceDependencyDirectories(packageName, root),
     };
+    return {
+      ...resolved,
+      watchInputs: bindingSourceInputs(root, resolved),
+    };
   });
   validateBindings(configs);
   return configs;
 }
 
+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),
+  ];
+  const visited = new Set<string>();
+  while (pending.length > 0) {
+    const candidate = canonicalPath(pending.pop()!);
+    if (
+      visited.has(candidate) ||
+      !allowed.some((directory) => containsResolvedPath(directory, candidate))
+    ) {
+      continue;
+    }
+    visited.add(candidate);
+    let source: string;
+    try {
+      source = readFileSync(candidate, "utf8");
+    } catch {
+      continue;
+    }
+    const dependencies = ts.preProcessFile(source, true, true).importedFiles;
+    for (const dependency of dependencies) {
+      try {
+        pending.push(Bun.resolveSync(dependency.fileName, dirname(candidate)));
+      } catch {
+        // Built-ins and external packages are outside the workspace source graph.
+      }
+    }
+  }
+  return [...visited].sort().map((path) => relative(root, path));
+}
+
+/** Resolve one configured namespace from a package entrypoint barrel. */
+export function resolvePythonNodeBindingModule(entrypoint: string, module: string): string {
+  if (!/^[$A-Z_a-z][$\w]*$/.test(module)) {
+    throw new Error(`Node binding module must be a TypeScript identifier: ${module}`);
+  }
+  const source = readFileSync(entrypoint, "utf8");
+  const escaped = module.replaceAll(/[$()*+.?[\\\]^{|}]/g, "\\$&");
+  const match = new RegExp(`export\\s+\\*\\s+as\\s+${escaped}\\s+from\\s+["']([^"']+)["']`).exec(
+    source,
+  );
+  if (!match?.[1]) {
+    throw new Error(`${entrypoint} does not export namespace ${module}`);
+  }
+  return Bun.resolveSync(match[1], dirname(entrypoint));
+}
+
+function canonicalPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+function containsResolvedPath(parent: string, candidate: string): boolean {
+  return candidate === parent || candidate.startsWith(`${parent}${sep}`);
+}
+
 /** All paths that can change a workspace-backed generated Node runtime. */
 export function pythonNodeBindingWatchInputs(config: ResolvedPythonNodeBindings): string[] {
   if (config.workspaceDirectories.length === 0) {
@@ -189,7 +265,7 @@ export function pythonNodeBindingWatchInputs(config: ResolvedPythonNodeBindings)
   }
   return [
     config.pyproject,
-    ...config.workspaceDirectories,
+    ...config.watchInputs,
     ...config.functionOverrides.map(({ handlerFile }) => handlerFile),
   ];
 }

package/tasks/python-node-bindings-watch.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env -S bun
 /** Keep every configured Python Node bridge current with one repository watcher. */
-import { dirname, resolve, sep } from "node:path";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { log, object } from "@dbx-tools/shared-core";
+import { log } from "@dbx-tools/shared-core";
 import { runTaskCommand } from "../src/_task-command.ts";
 import { repoRoot } from "../src/packages.ts";
 import {
@@ -12,36 +12,24 @@ import {
   resolveAllPythonNodeBindings,
   type ResolvedPythonNodeBindings,
 } from "../src/python-node-bindings.ts";
-import { watchLoop, watchRoots } from "../src/watch.ts";
+import { watchLoop } from "../src/watch.ts";
 import { withWorkspaceMutationLock } from "../src/workspace-lock.ts";
 
 const logger = log.logger("projen:python-node-bindings-watch");
 const generator = fileURLToPath(new URL("./python-node-bindings.ts", import.meta.url));
+const watcher = fileURLToPath(import.meta.url);
+const bindingSource = fileURLToPath(new URL("../src/python-node-bindings.ts", import.meta.url));
+const toolingInputs = [generator, watcher, bindingSource];
 
 function generate(project: string): void {
   runTaskCommand(repoRoot, "bun", [generator, "--root", repoRoot, "--project", project]);
 }
 
-function containsPath(parent: string, candidate: string): boolean {
-  const resolvedParent = resolve(parent);
-  const resolvedCandidate = resolve(candidate);
-  return (
-    resolvedCandidate === resolvedParent || resolvedCandidate.startsWith(`${resolvedParent}${sep}`)
-  );
-}
-
 /**
- * Watch broad package roots, each configured Python workspace root, and only
- * exceptional inputs such as function overrides that live outside those roots.
+ * Watch only configured manifests and transitive workspace source inputs.
  */
 function watchPaths(configs: readonly ResolvedPythonNodeBindings[]): string[] {
-  const roots = watchRoots();
-  const pythonRoots = configs.map(({ projectDirectory }) => dirname(projectDirectory));
-  const covered = [...roots, ...pythonRoots];
-  const explicitInputs = configs
-    .flatMap(pythonNodeBindingWatchInputs)
-    .filter((input) => !covered.some((root) => containsPath(root, input)));
-  return [...object.sequence(covered, explicitInputs).distinct()].sort();
+  return [...new Set([...configs.flatMap(pythonNodeBindingWatchInputs), ...toolingInputs])].sort();
 }
 
 function selection(
@@ -51,14 +39,20 @@ function selection(
   readonly all: boolean;
   readonly configs: ResolvedPythonNodeBindings[];
   readonly projects: string[];
+  readonly restart: boolean;
 } {
   const configs = resolveAllPythonNodeBindings(repoRoot);
   const manifests = new Set([...previous, ...configs].map(({ pyproject }) => resolve(pyproject)));
-  const all = changed.some((path) => manifests.has(resolve(path)));
+  const all = changed.some(
+    (path) =>
+      manifests.has(resolve(path)) ||
+      toolingInputs.some((input) => resolve(input) === resolve(path)),
+  );
   return {
     all,
     configs,
     projects: all ? [] : affectedPythonNodeBindingProjects(repoRoot, configs, changed),
+    restart: watchPaths(previous).join("\n") !== watchPaths(configs).join("\n"),
   };
 }
 
@@ -77,11 +71,15 @@ export async function main(): Promise<void> {
       if (next.all) {
         generatePythonNodeBindings(repoRoot);
         logger.success("regenerated all Python Node bindings");
-        return;
+      } else {
+        for (const project of next.projects) {
+          generate(project);
+          logger.success(`regenerated ${project} Node bindings`);
+        }
       }
-      for (const project of next.projects) {
-        generate(project);
-        logger.success(`regenerated ${project} Node bindings`);
+      if (next.restart) {
+        logger.info("binding inputs changed; restarting watcher");
+        setTimeout(() => process.exit(0), 0);
       }
     },
     {

package/tasks/python-node-bindings.ts

@@ -16,6 +16,7 @@ import { publicFunctionExports, publicNamespaceExports } from "../src/module-exp
 import { resolveRepoRoot } from "../src/packages.ts";
 import {
   generatePythonNodeBindings,
+  resolvePythonNodeBindingModule,
   resolvePythonNodeBindings,
   type ResolvedPythonNodeBindings,
   type ResolvedPythonNodeFunctionOverride,
@@ -139,7 +140,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
   );
   const packageEntrypoint = Bun.resolveSync(config.entrypoint, projectDirectory);
   const entrypoint = selectedModule
-    ? resolveGeneratedModule(packageEntrypoint, selectedModule)
+    ? resolvePythonNodeBindingModule(packageEntrypoint, selectedModule)
     : packageEntrypoint;
   const functions = publicFunctionExports(entrypoint);
   if (functions.length === 0) {
@@ -217,7 +218,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     return binding.modules.length > 0
       ? binding.modules.map((module) => ({
           key: runtimeModuleName(binding, module),
-          entrypoint: resolveGeneratedModule(entrypoint, module),
+          entrypoint: resolvePythonNodeBindingModule(entrypoint, module),
         }))
       : [{ key: runtimeModuleName(binding), entrypoint }];
   });
@@ -310,7 +311,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     const packageEntrypoint = Bun.resolveSync(candidate.entrypoint, candidate.projectDirectory);
     const modules = publicNamespaceExports(packageEntrypoint).filter(
       (module) =>
-        publicFunctionExports(resolveGeneratedModule(packageEntrypoint, module)).length > 0,
+        publicFunctionExports(resolvePythonNodeBindingModule(packageEntrypoint, module)).length > 0,
     );
     return { ...candidate, modules };
   }
@@ -1220,19 +1221,4 @@ function pythonRuntimeLoader(source: string): string {
   ].join("\n");
 }
 
-function resolveGeneratedModule(entrypoint: string, module: string): string {
-  if (!/^[$A-Z_a-z][$\w]*$/.test(module)) {
-    throw new Error(`Node binding module must be a TypeScript identifier: ${module}`);
-  }
-  const source = readFileSync(entrypoint, "utf8");
-  const escaped = module.replaceAll(/[$()*+.?[\\\]^{|}]/g, "\\$&");
-  const match = new RegExp(`export\\s+\\*\\s+as\\s+${escaped}\\s+from\\s+["']([^"']+)["']`).exec(
-    source,
-  );
-  if (!match?.[1]) {
-    throw new Error(`${entrypoint} does not export namespace ${module}`);
-  }
-  return Bun.resolveSync(match[1], dirname(entrypoint));
-}
-
 if (import.meta.main) await main();

package/tasks/release-notes.ts

@@ -20,6 +20,8 @@ const GENIE_PROMPT =
 
 /** Inputs for one notes write. */
 export interface WriteReleaseNotesOptions {
+  /** Extra agent instructions appended after the standard release-note requirements. */
+  readonly instructions?: string;
   readonly prefix: string;
   readonly root: string;
   readonly version: string;
@@ -27,6 +29,12 @@ export interface WriteReleaseNotesOptions {
   readonly runGenie?: (args: readonly string[]) => boolean;
 }
 
+/** Compose the stable release-note prompt with optional caller guidance. */
+export function releaseNotesPrompt(instructions?: string): string {
+  const additional = instructions?.trim();
+  return additional ? `${GENIE_PROMPT}\n\nAdditional instructions:\n${additional}` : GENIE_PROMPT;
+}
+
 /** Path of the notes file for one workspace version. */
 export function releaseNotesPath(root: string, version: string): string {
   return join(root, "docs", "releases", `v${version}.md`);
@@ -61,7 +69,7 @@ export function writeReleaseNotes(options: WriteReleaseNotesOptions): string {
     "--ephemeral",
     "-o",
     relative,
-    GENIE_PROMPT,
+    releaseNotesPrompt(options.instructions),
   ] as const;
   const ran =
     options.runGenie?.([...genieArgs]) ??

package/tasks/release.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env -S bun
 /** Run the configured release transaction. */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import * as projectUtils from "@dbx-tools/core/project-utils";
 import { log } from "@dbx-tools/shared-core";
 import { Command, Option } from "commander";
@@ -20,6 +22,14 @@ import { readWorkspaceVersion } from "../src/workspace-version.ts";
 
 const logger = log.logger("projen:release");
 
+/** Whether the root manifest exposes one repository-owned script. */
+function hasPackageScript(root: string, name: string): boolean {
+  const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
+    scripts?: Record<string, string>;
+  };
+  return Boolean(manifest.scripts?.[name]);
+}
+
 function gitHead(root: string, ref: string): string | undefined {
   if (!taskCommandSucceeds(root, "git", ["rev-parse", "--verify", ref])) return undefined;
   return captureTaskCommand(root, "git", ["rev-parse", ref], { check: true });
@@ -110,6 +120,8 @@ export async function runRelease(
     readonly demoDeploy?: boolean;
     /** Write `docs/releases/vX.Y.Z.md` via Genie, with a git-log fallback. On by default. */
     readonly releaseNotes?: boolean;
+    /** Additional instructions appended to the standard Genie release-notes prompt. */
+    readonly releaseNotesInstructions?: string;
     readonly writeReleaseNotes?: typeof writeReleaseNotes;
   },
 ): Promise<string> {
@@ -118,6 +130,9 @@ export async function runRelease(
   const install = options.install ?? "auto";
 
   if (install === "always") runTaskCommand(root, "bun", ["install"]);
+  if (selection.validation && hasPackageScript(root, "eslint:fix")) {
+    runTaskCommand(root, "bun", ["run", "eslint:fix"]);
+  }
 
   prepareReleaseBranch({ branch, remote, root });
 
@@ -132,7 +147,12 @@ export async function runRelease(
   const tag = `${prefix}${version}`;
   assertReleaseVersion(version, { root, prefixes: [prefix], assertNext: true });
   if ((options.releaseNotes ?? true) && (options.bump ?? true)) {
-    (options.writeReleaseNotes ?? writeReleaseNotes)({ prefix, root, version });
+    (options.writeReleaseNotes ?? writeReleaseNotes)({
+      prefix,
+      root,
+      version,
+      instructions: options.releaseNotesInstructions,
+    });
   }
 
   if (taskCommandSucceeds(root, "git", ["rev-parse", "--verify", `refs/tags/${tag}`])) {
@@ -242,6 +262,10 @@ export function createReleaseCommand(): Command {
       "skip optional release validation tasks; version/source checks remain mandatory",
     )
     .option("--no-release-notes", "skip writing docs/releases notes (Genie and git-log fallback)")
+    .option(
+      "--release-notes-instructions <text>",
+      "append custom instructions to the Genie release-notes prompt",
+    )
     .option("--demo-deploy", "after tagging, stage and deploy the AppKit demo app (off by default)")
     .option("--no-local-publish", "skip publishing to configured local registries")
     .option("--local-registry <auto|false|url>", "local npm registry selection", "auto")
@@ -262,6 +286,7 @@ export function createReleaseCommand(): Command {
           validate: string[];
           demoDeploy?: boolean;
           releaseNotes?: boolean;
+          releaseNotesInstructions?: string;
         },
       ) => {
         await runRelease({
@@ -283,6 +308,7 @@ export function createReleaseCommand(): Command {
           validationTasks: options.validate,
           demoDeploy: options.demoDeploy,
           releaseNotes: options.releaseNotes,
+          releaseNotesInstructions: options.releaseNotesInstructions,
         });
       },
     );