@dbx-tools/projen 0.9.43 → 0.9.46

package/src/watch.ts

@@ -7,13 +7,13 @@
  * decls - reacting to our own output would loop), exits on a watcher error chokidar
  * cannot recover from ({@link FATAL_WATCH_ERROR_CODES}), and shuts down on SIGINT. Callers
  * pass the paths to watch and an `onBatch` handler; the concern-specific glue - which
- * barrels to rebuild, when to regenerate openapi, when to re-synth - lives in the task
- * that owns it (`tasks/barrels.ts`, `tasks/openapi.ts`, `tasks/projenrc.ts`), each
- * forwarding here rather than duplicating the watch machinery.
+ * barrels to rebuild or when to re-synth - lives in the task that owns it
+ * (`tasks/barrels.ts` or `tasks/projenrc.ts`), each forwarding here rather than
+ * duplicating the watch machinery.
  *
  * `watchRoots()` is the one shared input - the package roots where every
- * watchable source file lives - so the barrels and openapi watchers don't each
- * recompute it. {@link watchFiles} owns the chokidar wiring; this is thin glue.
+ * watchable source file lives. {@link watchFiles} owns the chokidar wiring; this
+ * is thin glue.
  */
 import { isAbsolute, resolve } from "node:path";
 import { watch as pathWatch } from "@dbx-tools/path";

package/src/workspace-lock.ts

@@ -6,6 +6,7 @@ import { log } from "@dbx-tools/shared-core";
 const MUTATION_LOCK_SCOPE = "dbx-tools-workspace-mutation";
 const logger = log.logger("projen:workspace-lock");
 
+/** Optional preflight used before and after acquiring the workspace mutation lock. */
 export interface WorkspaceMutationLockOptions {
   /**
    * When this returns false, skip both the lock and the callback. After the

package/src/workspace-version.ts

@@ -3,10 +3,10 @@
  *
  * The repo-root `VERSION` file holds one plain `x.y.z` string that every
  * generated manifest copies at synth: the root and `projen/` package.json, every
- * JS member, every Python `pyproject.toml`, the generated openapi packages, and
- * the example apps. Synth only READS this file (defaulting to {@link
- * DEFAULT_VERSION} when it is absent on a fresh tree); it never rewrites it, so an
- * ordinary `bunx projen` cannot move a package version up or down.
+ * JavaScript member, every Python `pyproject.toml`, and the example apps. Synth
+ * only READS this file (defaulting to {@link DEFAULT_VERSION} when it is absent
+ * on a fresh tree); it never rewrites it, so an ordinary `bunx projen` cannot
+ * move a package version up or down.
  *
  * Only the pure `bump` task changes the number. It increments the checked-in
  * file while release preparation owns the surrounding Git transaction.

package/tasks/barrels.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env -S bun
+/** Generate package barrels once or keep affected barrels current in watch mode. */
 import { sep } from "node:path";
 import { parseArgs } from "node:util";
 import { log, object, stringUtils } from "@dbx-tools/shared-core";
@@ -11,12 +12,9 @@ const logger = log.logger("projen:barrels");
 /** The recorded package dir that owns `abs`, if any (for a targeted barrel rebuild). */
 function ownerPackageDir(
   abs: string,
-  packages: readonly { readonly dir: string; readonly tags: readonly string[] }[],
+  packages: readonly { readonly dir: string }[],
 ): string | undefined {
-  // The OpenAPI task rebuilds generated-client barrels after writing its files.
-  return packages.find(
-    ({ dir, tags }) => !tags.includes("openapi") && (abs === dir || abs.startsWith(dir + sep)),
-  )?.dir;
+  return packages.find(({ dir }) => abs === dir || abs.startsWith(dir + sep))?.dir;
 }
 
 function changedBarrelTargets(changed: readonly string[]): object.Sequence<string> {

package/tasks/clean.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env -S bun
+/** Interactively remove generated files and installed dependency directories. */
 import { relative } from "node:path";
 import { log, stringUtils } from "@dbx-tools/shared-core";
 import { listGeneratedFiles, listNodeModulesDirs, removePaths } from "../src/clean.ts";

package/tasks/lib/compile-workspace.ts

@@ -1,9 +1,12 @@
 #!/usr/bin/env -S bun
-/** Compile source-first workspace packages in a few TypeScript processes. */
+/** Batch package type-checks and run package-owned compile lifecycles. */
 import { existsSync, readFileSync } from "node:fs";
 import { availableParallelism } from "node:os";
 import { join, resolve } from "node:path";
 import * as exec from "@dbx-tools/core/exec";
+import { log } from "@dbx-tools/shared-core";
+
+const logger = log.logger("projen:compile");
 
 interface PackageManifest {
   readonly name?: string;
@@ -13,8 +16,14 @@ interface PackageManifest {
 
 interface TaskManifest {
   readonly tasks?: {
+    readonly "pre-compile"?: {
+      readonly steps?: Array<{ readonly exec?: string; readonly execArgs?: string[] }>;
+    };
     readonly compile?: {
-      readonly steps?: Array<{ readonly execArgs?: string[] }>;
+      readonly steps?: Array<{ readonly exec?: string; readonly execArgs?: string[] }>;
+    };
+    readonly "post-compile"?: {
+      readonly steps?: Array<{ readonly exec?: string; readonly execArgs?: string[] }>;
     };
   };
 }
@@ -40,6 +49,10 @@ function plainTypeScriptBuild(steps: unknown): boolean {
   );
 }
 
+function hasSteps(steps: unknown): boolean {
+  return Array.isArray(steps) && steps.length > 0;
+}
+
 /** Read the root's concrete workspace paths on every run, including newly added members. */
 export function compilePlan(root: string): CompilePlan {
   const workspace = readJson<PackageManifest>(join(root, "package.json"));
@@ -51,14 +64,13 @@ export function compilePlan(root: string): CompilePlan {
     const script = manifest.scripts?.compile;
     if (!script) continue;
     const taskPath = join(directory, ".projen", "tasks.json");
-    const steps = existsSync(taskPath)
-      ? readJson<TaskManifest>(taskPath).tasks?.compile?.steps
-      : undefined;
+    const tasks = existsSync(taskPath) ? readJson<TaskManifest>(taskPath).tasks : undefined;
+    const plainCompile = plainTypeScriptBuild(tasks?.compile?.steps);
     if (
       script === "projen compile" &&
-      !manifest.scripts?.precompile &&
-      !manifest.scripts?.postcompile &&
-      plainTypeScriptBuild(steps)
+      plainCompile &&
+      !hasSteps(tasks?.["pre-compile"]?.steps) &&
+      !hasSteps(tasks?.["post-compile"]?.steps)
     ) {
       typescriptConfigs.push(join(directory, "tsconfig.json"));
     } else {
@@ -78,9 +90,7 @@ export async function main(): Promise<void> {
     const batchCount = Math.min(4, availableParallelism(), plan.typescriptConfigs.length);
     const batches = Array.from({ length: batchCount }, () => [] as string[]);
     plan.typescriptConfigs.forEach((config, index) => batches[index % batchCount]!.push(config));
-    console.log(
-      `Type-checking ${plan.typescriptConfigs.length} workspaces in ${batchCount} batches`,
-    );
+    logger.info(`type-checking ${plan.typescriptConfigs.length} workspaces in ${batchCount} batches`);
     for (const [index, batch] of batches.entries()) {
       jobs.push({
         name: `TypeScript batch ${index + 1}`,
@@ -96,24 +106,36 @@ export async function main(): Promise<void> {
   for (const pkg of plan.customPackages) {
     jobs.push({
       name: pkg.name,
-      result: exec.spawn("bun", ["run", "compile"], {
-        cwd: pkg.directory,
-        stdin: "ignore",
-        stdout: (line) => console.log(`${pkg.name}: ${line.replace(emoji, "")}`),
-        stderr: (line) => console.error(`${pkg.name}: ${line.replace(emoji, "")}`),
-      }),
+      result: compileCustomPackage(pkg),
     });
   }
   const results = await Promise.allSettled(jobs.map((job) => job.result));
   let failed = false;
   for (const [index, result] of results.entries()) {
     if (result.status === "rejected") {
-      console.error(`${jobs[index]!.name} compile failed:`, result.reason);
+      logger.error(`${jobs[index]!.name} compile failed:`, result.reason);
       failed = true;
     } else if (result.value.exitCode !== 0) {
-      console.error(`${jobs[index]!.name} compile exited with ${result.value.exitCode}`);
+      logger.error(`${jobs[index]!.name} compile exited with ${result.value.exitCode}`);
       failed = true;
     }
   }
   if (failed) process.exitCode = 1;
 }
+
+async function compileCustomPackage(pkg: {
+  readonly name: string;
+  readonly directory: string;
+}): Promise<exec.ExecResult> {
+  let result: exec.ExecResult | undefined;
+  for (const task of ["pre-compile", "compile", "post-compile"]) {
+    result = await exec.spawn("bun", ["run", task], {
+      cwd: pkg.directory,
+      stdin: "ignore",
+      stdout: (line) => logger.info(`${pkg.name}: ${line.replace(emoji, "")}`),
+      stderr: (line) => logger.error(`${pkg.name}: ${line.replace(emoji, "")}`),
+    });
+    if (result.exitCode !== 0) return result;
+  }
+  return result!;
+}

package/tasks/lib/local-publish.ts

@@ -3,7 +3,6 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as projectUtils from "@dbx-tools/core/project-utils";
 import { log, net } from "@dbx-tools/shared-core";
-import { Command } from "commander";
 import { activePythonIndexes, resolveLocalPypi } from "./python-registry.ts";
 import { runTaskCommandAsync } from "../../src/_task-command.ts";
 
@@ -93,30 +92,3 @@ export async function publishLocalRelease(
   logger.success(`published local workspace ${options.version}`);
   return { npm: Boolean(localRegistry), python: Boolean(localPypi) };
 }
-
-export async function main(): Promise<void> {
-  await new Command()
-    .requiredOption("--version <version>", "release version")
-    .option("--root <path>", "repository root")
-    .option("--python-root <path>", "Python package root", "packages/py")
-    .option("--local-registry <url>", "local npm registry", "auto")
-    .option("--local-pypi <url>", "local devpi index", "auto")
-    .action(
-      async (options: {
-        version: string;
-        root?: string;
-        pythonRoot: string;
-        localRegistry: string;
-        localPypi: string;
-      }) => {
-        await publishLocalRelease({
-          localPypi: options.localPypi,
-          localRegistry: options.localRegistry,
-          pythonRoot: options.pythonRoot,
-          root: options.root ?? projectUtils.root() ?? process.cwd(),
-          version: options.version,
-        });
-      },
-    )
-    .parseAsync();
-}

package/tasks/lib/publish-npm.ts

@@ -22,6 +22,7 @@ import { runTaskCommand } from "../../src/_task-command.ts";
 const DEFAULT_REGISTRY = "https://registry.npmjs.org";
 const logger = log.logger("projen:publish-npm");
 
+/** Registry and archive identity used to verify idempotent npm publication. */
 export interface NpmReleaseIdentity {
   readonly access?: "public" | "restricted";
   readonly contentDigest?: string;
@@ -41,6 +42,7 @@ interface NpmArchiveManifest {
   readonly version?: string;
 }
 
+/** Transform applied to a packed npm manifest before archive verification. */
 export type NpmArchiveManifestTransform = (
   manifest: NpmArchiveManifest,
 ) => Readonly<Record<string, unknown>>;
@@ -143,6 +145,7 @@ function registryUrl(registry: string, name: string, version: string): string {
   return `${registry.replace(/\/$/, "")}/${encodeURIComponent(name)}/${encodeURIComponent(version)}`;
 }
 
+/** Verify that registry metadata represents the exact locally packed release. */
 export function npmReleaseMatches(
   local: NpmReleaseIdentity,
   published: NpmReleaseIdentity | undefined,
@@ -173,6 +176,7 @@ export function npmReleaseMatches(
   return true;
 }
 
+/** Read one published npm release identity, or `undefined` when it is absent. */
 export async function publishedNpmRelease(
   name: string,
   version: string,
@@ -232,6 +236,7 @@ function readNpmArchiveManifest(path: string): NpmArchiveManifest {
   return JSON.parse(result.stdout) as NpmArchiveManifest;
 }
 
+/** Read and hash the release identity embedded in an npm archive. */
 export function readNpmArchiveIdentity(path: string): NpmReleaseIdentity {
   const manifest = readNpmArchiveManifest(path);
   if (!manifest.name || !manifest.version) {
@@ -326,6 +331,7 @@ export function npmArchiveContentDigest(path: string): string {
   }
 }
 
+/** Pack one workspace package and optionally transform only its archived manifest. */
 export function packNpmPackage(
   directory: string,
   destination: string,
@@ -404,6 +410,7 @@ export function packNpmPackage(
   }
 }
 
+/** Publish dependency-ordered npm archives, skipping only exact registry matches. */
 export async function publishNpmArchives(options: {
   readonly directory: string;
   readonly dryRun?: boolean;
@@ -443,6 +450,7 @@ export async function publishNpmArchives(options: {
   }
 }
 
+/** Parse npm archive publication options and execute the publisher. */
 export async function main(): Promise<void> {
   const program = new Command();
   program

package/tasks/lib/publish-python.ts

@@ -1,4 +1,8 @@
 #!/usr/bin/env -S bun
+/**
+ * Build selected uv workspace packages from isolated publication copies and
+ * optionally publish the resulting distributions.
+ */
 import {
   chmodSync,
   cpSync,

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

@@ -1,4 +1,8 @@
 #!/usr/bin/env -S bun
+/**
+ * Generate a shared PythonMonkey runtime and typed Python wrappers from each
+ * package's serialized node-binding configuration.
+ */
 import {
   existsSync,
   mkdirSync,
@@ -10,7 +14,7 @@ import {
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
-import { stringUtils } from "@dbx-tools/shared-core";
+import { log, stringUtils } from "@dbx-tools/shared-core";
 import type { BunPlugin } from "bun";
 import stdLibBrowser from "node-stdlib-browser";
 import ts from "typescript";
@@ -23,6 +27,8 @@ import {
   type ResolvedPythonNodeFunctionOverride,
 } from "../../src/python-node-bindings.ts";
 
+const logger = log.logger("projen:python-node-bindings");
+
 type FunctionOverride = ResolvedPythonNodeFunctionOverride;
 
 function bindingIndex(value: string, count: number, project: string): number {
@@ -180,6 +186,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     ["fs/promises", resolve(shimRoot, "fs-promises.ts")],
     ["os", resolve(shimRoot, "os.ts")],
     ["process", resolve(shimRoot, "process.ts")],
+    ["readline", resolve(shimRoot, "readline.ts")],
   ]);
   const bridgeSource = [
     "export const __pythonGet = (target, name) => target[name];",
@@ -316,7 +323,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
       target: "browser",
     });
     if (!result.success) {
-      for (const message of result.logs) console.error(message);
+      for (const message of result.logs) logger.error(message);
       throw new Error(`Could not bundle ${config.entrypoint}`);
     }
     if (result.outputs.length !== 1) {
@@ -438,7 +445,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
       .map((name) => `    ${JSON.stringify(name)},`)
       .join("\n");
     const dataclasses = records.map(pythonDataclass).join("\n\n\n");
-    const responseTypes = responses.map(pythonResponse).join("\n\n\n");
+    const responseTypes = orderPythonResponses(responses).map(pythonResponse).join("\n\n\n");
     const protocolTypes = protocols.map(pythonProtocol).join("\n\n\n");
     const wrappers = functions
       .map(({ async, javascriptName, pythonName, parameters, returnType }) =>
@@ -526,6 +533,39 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     readonly type: string;
   }
 
+  /**
+   * Emit nested response types before the responses that reference them.
+   *
+   * Functional TypedDict declarations evaluate their field types immediately,
+   * unlike class annotations protected by `from __future__ import annotations`.
+   */
+  function orderPythonResponses(responses: readonly PythonResponse[]): PythonResponse[] {
+    const ordered: PythonResponse[] = [];
+    const visited = new Set<string>();
+    const visiting = new Set<string>();
+
+    const visit = (response: PythonResponse): void => {
+      if (visited.has(response.name) || visiting.has(response.name)) return;
+      visiting.add(response.name);
+      for (const dependency of responses) {
+        if (
+          dependency.name !== response.name &&
+          response.fields.some(({ type }) =>
+            new RegExp(`\\b${dependency.name}\\b`).test(type),
+          )
+        ) {
+          visit(dependency);
+        }
+      }
+      visiting.delete(response.name);
+      visited.add(response.name);
+      ordered.push(response);
+    };
+
+    for (const response of responses) visit(response);
+    return ordered;
+  }
+
   interface PythonProtocol {
     readonly methods: readonly PythonProtocolMethod[];
     readonly name: string;
@@ -658,10 +698,8 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     const placeholder: PythonRecord = { name, fields: [] };
     records.set(name, placeholder);
     const fields = checker.getPropertiesOfType(type).map((property) => {
-      const declaration = property.valueDeclaration ?? property.declarations?.[0];
-      if (!declaration) throw new Error(`${path}.${property.name} has no TypeScript declaration`);
       const propertyType = withoutUndefined(
-        checker.getTypeOfSymbolAtLocation(property, declaration),
+        resolvedPropertyType(checker, type, property, `${path}.${property.name}`),
       );
       return {
         javascriptName: property.name,
@@ -782,13 +820,15 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
       );
     }
     const properties = checker.getPropertiesOfType(type).filter(publicProperty);
-    const methods = properties.filter((property) => {
-      const declaration = property.valueDeclaration ?? property.declarations?.[0];
-      return Boolean(
-        declaration &&
-        checker.getTypeOfSymbolAtLocation(property, declaration).getCallSignatures().length,
-      );
-    });
+    const methods = properties.filter(
+      (property) =>
+        resolvedPropertyType(
+          checker,
+          type,
+          property,
+          `${path}.${property.name}`,
+        ).getCallSignatures().length > 0,
+    );
     if (methods.length > 0) {
       const name = pythonObjectName(type, path, "Result");
       if (protocols.has(name)) return name;
@@ -847,14 +887,14 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
       const protocolProperties = properties
         .filter(({ name }) => !methodNames.has(name))
         .map((property) => {
-          const declaration = property.valueDeclaration ?? property.declarations?.[0];
-          if (!declaration) throw new Error(`${path}.${property.name} has no declaration`);
           return {
             name: pythonFunctionName(property.name),
             required: !(property.flags & ts.SymbolFlags.Optional),
             type: pythonReturnType(
               checker,
-              withoutUndefined(checker.getTypeOfSymbolAtLocation(property, declaration)),
+              withoutUndefined(
+                resolvedPropertyType(checker, type, property, `${path}.${property.name}`),
+              ),
               responses,
               protocols,
               `${path}.${property.name}`,
@@ -868,14 +908,14 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     if (responses.has(name)) return name;
     responses.set(name, { name, fields: [] });
     const fields = properties.map((property) => {
-      const declaration = property.valueDeclaration ?? property.declarations?.[0];
-      if (!declaration) throw new Error(`${path}.${property.name} has no TypeScript declaration`);
       return {
         name: property.name,
         required: !(property.flags & ts.SymbolFlags.Optional),
         type: pythonReturnType(
           checker,
-          withoutUndefined(checker.getTypeOfSymbolAtLocation(property, declaration)),
+          withoutUndefined(
+            resolvedPropertyType(checker, type, property, `${path}.${property.name}`),
+          ),
           responses,
           protocols,
           `${path}.${property.name}`,
@@ -908,12 +948,28 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
   }
 
   function publicProperty(property: ts.Symbol): boolean {
+    if (!property.declarations?.length) return true;
     return (property.declarations ?? []).some((declaration) => {
       const flags = ts.getCombinedModifierFlags(declaration as ts.Declaration);
       return !(flags & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected));
     });
   }
 
+  function resolvedPropertyType(
+    checker: ts.TypeChecker,
+    owner: ts.Type,
+    property: ts.Symbol,
+    path: string,
+  ): ts.Type {
+    const location =
+      property.valueDeclaration ??
+      property.declarations?.[0] ??
+      owner.aliasSymbol?.declarations?.[0] ??
+      owner.getSymbol()?.declarations?.[0];
+    if (!location) throw new Error(`${path} has no TypeScript type location`);
+    return checker.getTypeOfSymbolAtLocation(property, location);
+  }
+
   function pythonObjectName(type: ts.Type, path: string, suffix: string): string {
     const name = type.aliasSymbol?.getName() ?? type.getSymbol()?.getName();
     if (name && name !== "__type") return name;
@@ -1096,7 +1152,7 @@ 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) {
-      if (values.check) console.log(`verified ${destination}`);
+      if (values.check) logger.info(`verified ${destination}`);
       return;
     }
     if (values.check) {
@@ -1106,7 +1162,7 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     makeWritable(output);
     writeFileSync(output, contents);
     makeReadonly(output);
-    console.log(`generated ${destination}`);
+    logger.info(`generated ${destination}`);
   }
 }
 

package/tasks/lib/python-registry.ts

@@ -1,3 +1,4 @@
+/** Resolve active uv indexes and writable loopback devpi publication targets. */
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
@@ -5,8 +6,11 @@ import { net } from "@dbx-tools/shared-core";
 import { parse } from "smol-toml";
 import { captureTaskCommand } from "../../src/_task-command.ts";
 
+/** Paired Python package index and upload endpoints for a local registry. */
 export interface LocalPythonRegistry {
+  /** PEP 503 package index URL used for dependency resolution. */
   readonly indexUrl: string;
+  /** Registry upload URL used for publication. */
   readonly publishUrl: string;
 }
 

package/tasks/lib/python-release.ts

@@ -22,6 +22,7 @@ const directSibling = (
   return directory === sibling.directory || directory.endsWith(`/${sibling.directory}`);
 };
 
+/** Parse the publication identity and private flag from one Python manifest. */
 export function pythonProjectInfo(
   source: string,
   toml: { parse(source: string): unknown },
@@ -41,6 +42,7 @@ export function pythonProjectInfo(
   };
 }
 
+/** Project sibling dependencies and the release version into an isolated manifest copy. */
 export function preparePythonProjectForPublication(
   source: string,
   options: {

package/tasks/lib/release.ts

@@ -115,7 +115,7 @@ export async function runRelease(
   const selection = releaseStepSelection(options);
   const install = options.install ?? "auto";
 
-  if (install === "always") runTaskCommand(root, "bun", ["install", "--frozen-lockfile"]);
+  if (install === "always") runTaskCommand(root, "bun", ["install"]);
 
   prepareReleaseBranch({ branch, remote, root });
 

package/tasks/projenrc.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env -S bun
+/** Resynthesize when the root definition or configured generator inputs change. */
 import { resolve } from "node:path";
 import { log } from "@dbx-tools/shared-core";
 import { repoRoot, syncResynthPaths } from "../src/packages.ts";

package/tasks/sync.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env -S bun
+/** Synthesize once or supervise the focused Projen and barrel watch loops. */
 import { fileURLToPath } from "node:url";
 import { log } from "@dbx-tools/shared-core";
 import concurrently from "concurrently";
@@ -46,8 +47,8 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     // Watch: one initial full synth to bring the tree up to date, then focused
     // watchers under `concurrently`. The projenrc watcher is the intelligent stand-in
     // for stock `projen --watch` - it re-synths (+install) ONLY when `.projenrc.ts` or
-    // a configured `syncResynthPaths` entry changes, while barrels/openapi keep generated
-    // OUTPUT fresh on source edits with no full synth.
+    // a configured `syncResynthPaths` entry changes, while the barrel watcher keeps
+    // generated package exports fresh on source edits with no full synth.
     //
     // VS Code auto-runs this on folder open, so from here down nothing is allowed to be
     // fatal: errors are logged and retried, and only a stop signal ends the task.
@@ -67,11 +68,10 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
     const watchers = [
       watcher("projenrc.ts", "projenrc", "magenta"),
       watcher("barrels.ts", "barrels", "cyan", "--watch"),
-      watcher("openapi.ts", "openapi", "green", "--watch"),
     ];
     const { result } = concurrently(watchers, {
       prefix: "name",
-      // No `killOthersOn`: one watcher falling over is no reason to tear the other two
+      // No `killOthersOn`: one watcher falling over is no reason to tear the other
       // down. `-1` is concurrently's spelling for "restart forever", so a crashed
       // watcher comes back instead of silently leaving its outputs stale.
       restartTries: -1,