@dbx-tools/projen 0.9.93 → 0.9.99

package/tasks/dev-watch.ts

@@ -0,0 +1,339 @@
+#!/usr/bin/env -S bun
+/** Restart a development command after relevant workspace changes settle. */
+import { isAbsolute, relative, resolve } from "node:path";
+import { configUtils } from "@dbx-tools/core";
+import * as exec from "@dbx-tools/core/exec";
+import { watch as pathWatch } from "@dbx-tools/path";
+import { log } from "@dbx-tools/shared-core";
+import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
+import {
+  DEV_RESTART_DEBOUNCE_MS,
+  DEV_RESTART_KEY,
+  DEV_WATCH_TASK,
+  SERVER_WATCH_DISABLED_ENV,
+} from "../src/dev-watch.ts";
+import {
+  readPackageManifest,
+  recordedPackages,
+  resolveRepoRoot,
+  workspaceDependencyDirectories,
+} from "../src/packages.ts";
+
+const logger = log.logger("projen:dev-watch");
+const SHUTDOWN_TIMEOUT_MS = 2_000;
+
+export interface DevWatchOptions {
+  readonly command: readonly string[];
+  readonly debounceMs: number;
+  readonly restartKey: string;
+  /** When true, run the command once and skip file-change restarts. */
+  readonly serverWatchDisabled: boolean;
+}
+
+interface WorkspacePackage {
+  readonly dir: string;
+  readonly name?: string;
+}
+
+function debounceMilliseconds(value: string): number {
+  const parsed = configUtils.toNumber(value);
+  if (parsed === undefined || parsed < 0) {
+    throw new InvalidArgumentError("must be a non-negative number of milliseconds");
+  }
+  return parsed;
+}
+
+function singleKey(value: string): string {
+  if (Array.from(value).length !== 1) {
+    throw new InvalidArgumentError("must be exactly one character");
+  }
+  return value;
+}
+
+/** Parse watcher flags while passing every token after the command through unchanged. */
+export function parseDevWatchOptions(args: string[]): DevWatchOptions {
+  const program = new Command()
+    .name(DEV_WATCH_TASK)
+    .description("Restart a development command after watched changes settle")
+    .exitOverride()
+    .configureOutput({
+      writeErr: (message) => {
+        if (import.meta.main) process.stderr.write(message);
+      },
+    })
+    .enablePositionalOptions()
+    .passThroughOptions()
+    .addOption(
+      new Option("--debounce-ms <milliseconds>", "quiet period before restart")
+        .default(DEV_RESTART_DEBOUNCE_MS)
+        .argParser(debounceMilliseconds),
+    )
+    .addOption(
+      new Option("--restart-key <key>", "interactive immediate-restart key")
+        .default(DEV_RESTART_KEY)
+        .argParser(singleKey),
+    )
+    .addOption(
+      new Option(
+        "--server-watch-disabled",
+        `run the command once without watching (${SERVER_WATCH_DISABLED_ENV})`,
+      ),
+    )
+    .argument("<command>")
+    .argument("[args...]")
+    .parse(["bun", DEV_WATCH_TASK, ...args]);
+  const options = program.opts<{
+    debounceMs: number;
+    restartKey: string;
+    serverWatchDisabled?: boolean;
+  }>();
+  const [command, commandArgs = []] = program.processedArgs as [string, string[]?];
+  const serverWatchDisabled =
+    options.serverWatchDisabled === true ||
+    configUtils.boolean(undefined, SERVER_WATCH_DISABLED_ENV, configUtils.ENV_ONLY) === true;
+  if (serverWatchDisabled) process.env[SERVER_WATCH_DISABLED_ENV] = "1";
+  return {
+    command: [command, ...commandArgs],
+    debounceMs: options.debounceMs,
+    restartKey: options.restartKey,
+    serverWatchDisabled,
+  };
+}
+
+function containsPath(parent: string, candidate: string): boolean {
+  const rel = relative(parent, candidate);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function workspacePackages(root: string): WorkspacePackage[] {
+  return recordedPackages(root)
+    .map(({ dir }) => {
+      const name = readPackageManifest(dir)?.name;
+      return { dir, name: typeof name === "string" ? name : undefined };
+    })
+    .sort((left, right) => right.dir.length - left.dir.length);
+}
+
+function optionArgument(
+  command: readonly string[],
+  longName: string,
+  shortName?: string,
+): string | undefined {
+  for (let index = 0; index < command.length; index++) {
+    const token = command[index]!;
+    if (token === longName || (shortName !== undefined && token === shortName)) {
+      return command[index + 1];
+    }
+    if (token.startsWith(`${longName}=`)) return token.slice(longName.length + 1);
+    if (shortName !== undefined && token.startsWith(`${shortName}=`)) {
+      return token.slice(shortName.length + 1);
+    }
+  }
+  return undefined;
+}
+
+function commandWorkingDirectory(command: readonly string[], cwd: string): string {
+  const configured = optionArgument(command, "--cwd");
+  return configured ? resolve(cwd, configured) : cwd;
+}
+
+function commandPackage(
+  command: readonly string[],
+  cwd: string,
+  packages: readonly WorkspacePackage[],
+): WorkspacePackage | undefined {
+  const selected = optionArgument(command, "--filter", "-F");
+  if (selected) {
+    const filtered = packages.find(({ name }) => name === selected);
+    if (filtered) return filtered;
+  }
+
+  const commandCwd = commandWorkingDirectory(command, cwd);
+  for (const token of command) {
+    if (token.startsWith("-")) continue;
+    const candidate = resolve(commandCwd, token);
+    const owner = packages.find(({ dir }) => containsPath(dir, candidate));
+    if (owner) return owner;
+  }
+  return packages.find(({ dir }) => containsPath(dir, commandCwd));
+}
+
+/** Source directories most likely to affect the command, using workspace dependency metadata. */
+export function devWatchDirectories(
+  command: readonly string[],
+  cwd: string = process.cwd(),
+): string[] {
+  const root = resolveRepoRoot(cwd);
+  const packages = workspacePackages(root);
+  const owner = commandPackage(command, cwd, packages);
+  if (!owner) return [commandWorkingDirectory(command, cwd)];
+  const dependencies = owner.name ? workspaceDependencyDirectories(owner.name, root) : [];
+  return dependencies.length > 0 ? dependencies : [owner.dir];
+}
+
+/** Compare one raw terminal character with the configured restart key. */
+export function isRestartKey(key: string, restartKey: string): boolean {
+  return key === restartKey || key.toLocaleLowerCase() === restartKey.toLocaleLowerCase();
+}
+
+/** Supervise one command until the user or host stops the task. */
+export async function main(args: string[] = process.argv.slice(2)): Promise<void> {
+  let options: DevWatchOptions;
+  try {
+    options = parseDevWatchOptions(args);
+  } catch (err) {
+    if (!(err instanceof CommanderError)) throw err;
+    if (err.exitCode !== 0) process.exitCode = err.exitCode;
+    return;
+  }
+  const cwd = process.cwd();
+  if (options.serverWatchDisabled) {
+    logger.info(`${SERVER_WATCH_DISABLED_ENV} is set; running without file watching`);
+    const [command, ...commandArgs] = options.command;
+    const { exitCode } = await exec.spawn(command!, commandArgs, {
+      cwd,
+      stdin: "ignore",
+      stdout: "inherit",
+      stderr: "inherit",
+      check: false,
+    });
+    if (exitCode !== 0) process.exitCode = exitCode;
+    return;
+  }
+
+  const root = resolveRepoRoot(cwd);
+  const watchDirectories = devWatchDirectories(options.command, cwd);
+  const commandLabel = options.command.map((part) => JSON.stringify(part)).join(" ");
+  let child: exec.ChildProcessResult | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let restartReason: string | undefined;
+  let restarting = false;
+  let stopping = false;
+
+  const watcher = pathWatch.watchFiles(watchDirectories, {
+    cwd: root,
+    ignoreInitial: true,
+  });
+
+  async function stopChild(): Promise<void> {
+    const current = child;
+    if (!current) return;
+    child = undefined;
+    try {
+      await exec.kill(current, {
+        gracefulTimeoutMs: SHUTDOWN_TIMEOUT_MS,
+        forceTimeoutMs: SHUTDOWN_TIMEOUT_MS,
+      });
+    } catch (err) {
+      logger.error("failed to stop command process tree:", err);
+    }
+  }
+
+  function startChild(reason: string): void {
+    logger.info(`${reason}; starting ${commandLabel}`);
+    const [command, ...commandArgs] = options.command;
+    const current = exec.spawn(command!, commandArgs, {
+      cwd,
+      stdin: "ignore",
+      stdout: "inherit",
+      stderr: "inherit",
+      check: false,
+    });
+    child = current;
+    void current
+      .then(({ exitCode }) => {
+        if (child !== current || stopping) return;
+        child = undefined;
+        logger.warn(
+          `command exited with code ${exitCode}; press ${JSON.stringify(options.restartKey)} or change a watched file to restart`,
+        );
+      })
+      .catch((err) => {
+        if (child !== current || stopping) return;
+        child = undefined;
+        logger.error("command failed:", err);
+      });
+  }
+
+  async function drainRestarts(): Promise<void> {
+    if (restarting) return;
+    restarting = true;
+    try {
+      while (restartReason !== undefined && !stopping) {
+        const reason = restartReason;
+        restartReason = undefined;
+        await stopChild();
+        if (!stopping) startChild(reason);
+      }
+    } finally {
+      restarting = false;
+    }
+  }
+
+  function requestRestart(reason: string): void {
+    restartReason = reason;
+    void drainRestarts();
+  }
+
+  function scheduleRestart(): void {
+    clearTimeout(timer);
+    timer = setTimeout(
+      () => requestRestart(`changes settled for ${options.debounceMs}ms`),
+      options.debounceMs,
+    );
+  }
+
+  watcher.on("all", scheduleRestart);
+  watcher.on("error", (err) => logger.error("watcher error:", err));
+  watcher.on("ready", () => {
+    const packages = watchDirectories.length;
+    logger.info(
+      `watching ${packages} workspace ${packages === 1 ? "directory" : "directories"} with ${options.debounceMs}ms restart debounce`,
+    );
+    logger.info(`press ${JSON.stringify(options.restartKey)} to restart; Ctrl-C to stop`);
+  });
+
+  const stdin = process.stdin;
+  const wasRaw = stdin.isTTY ? Boolean(stdin.isRaw) : false;
+  const onInput = (chunk: Buffer | string): void => {
+    for (const key of String(chunk)) {
+      if (key === "\u0003") {
+        void shutdown();
+        return;
+      }
+      if (isRestartKey(key, options.restartKey)) {
+        clearTimeout(timer);
+        requestRestart("manual restart requested");
+      }
+    }
+  };
+  if (stdin.isTTY) stdin.setRawMode(true);
+  stdin.resume();
+  stdin.on("data", onInput);
+
+  let finish!: () => void;
+  const complete = new Promise<void>((resolveComplete) => {
+    finish = resolveComplete;
+  });
+
+  async function shutdown(): Promise<void> {
+    if (stopping) return;
+    stopping = true;
+    clearTimeout(timer);
+    restartReason = undefined;
+    stdin.off("data", onInput);
+    if (stdin.isTTY) stdin.setRawMode(wasRaw);
+    stdin.pause();
+    await Promise.allSettled([watcher.close(), stopChild()]);
+    finish();
+  }
+
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+    process.once(signal, () => void shutdown());
+  }
+
+  requestRestart("initial start");
+  await complete;
+}
+
+if (import.meta.main) await main();

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",