@dbx-tools/projen 0.1.1 → 0.3.43

package/README.md

@@ -3,7 +3,7 @@
 Projen engine for dbx-tools pnpm workspaces.
 
 Import this package from `.projenrc.ts` when a repository should discover
-workspace packages from the filesystem and generate manifests, tsconfigs,
+packages from the filesystem and generate manifests, tsconfigs,
 barrels, OpenAPI clients, codegen outputs, and release tasks.
 
 Key features:
@@ -28,7 +28,7 @@ import { project as projectApi } from "@dbx-tools/projen";
 const project = new projectApi.DBXToolsNodeProject({
   name: "my-apps",
   scope: "my-apps",
-  workspacePackageRoots: ["workspaces", "examples"],
+  packageRoots: ["packages", "examples"],
 });
 
 project.synth();
@@ -44,19 +44,28 @@ new package membership.
 ## Customize Packages With Mixins
 
 ```ts
-import { mixin, project as projectApi, projectPredicate } from "@dbx-tools/projen";
+import { project as projectApi } from "@dbx-tools/projen";
 
 const project = new projectApi.DBXToolsNodeProject();
 
-project.with(
-  mixin.mixin(projectPredicate.hasTag("shared"), (pkg) => {
-    pkg.addDeps("zod@catalog:");
-  }),
-);
+projectApi.applyToProjects(project, { tags: "shared" }, (pkg) => {
+  pkg.addDeps("zod@catalog:");
+});
 
 project.synth();
 ```
 
+`applyToProjects` AND-s its globs (prefix a glob with `!` to negate) into one
+predicate over the DBXTools child packages, then applies it as a `constructs`
+mixin across the subtree. Filter on the folder (`path`), the tags (`tags`), or
+the name from whichever angle fits: `name` matches the raw projen name verbatim,
+while `identifierPackageName`, `identifierScope`, and `identifierName` match the
+parsed `@scope/name`, its scope, and its unscoped half. Two flags widen the
+selection past DBXTools children - `includeRoots` for the tree root and
+`includeNonDBXToolsProjects` for plain projen projects (which widens the callback
+parameter to `Project`). Drop to `mixin.create(predicate, fn)` +
+`project.with(...)` only when you need a predicate the filters cannot express.
+
 Built-in tag mixins set runtime defaults for `shared`, `node`, `cli`, `server`,
 `ui`, and `openapi`. Repo-specific mixins layer package-specific dependencies,
 scripts, and generated files on top.
@@ -64,13 +73,13 @@ scripts, and generated files on top.
 ## Work With Package Discovery
 
 ```ts
-import { workspace } from "@dbx-tools/projen";
+import { packages } from "@dbx-tools/projen";
 
-const discovered = workspace.scanPackages(process.cwd(), ["workspaces"]);
-const recorded = workspace.workspacePackages();
+const discovered = packages.scanPackages(process.cwd(), ["packages"]);
+const recorded = packages.recordedPackages();
 ```
 
-`scanPackages()` reads the filesystem during synth. `workspacePackages()` reads
+`scanPackages()` reads the filesystem during synth. `recordedPackages()` reads
 the generated `pnpm-workspace.yaml` plus package manifests for post-synth tools.
 Use the latter for docs, linting, and release checks that should match the
 recorded workspace.
@@ -106,8 +115,25 @@ project.pnpmWorkspace?.addCatalog("react", "^19");
 project.pnpmWorkspace?.allowBuild("esbuild");
 ```
 
-`pnpmWorkspace.DBXToolsPNPMWorkspace` owns `pnpm-workspace.yaml`, package
-members, catalog entries, overrides, and build-script allowlists.
+projen's native `javascript.PnpmWorkspaceYaml` writes `pnpm-workspace.yaml`;
+`pnpmWorkspace.PnpmWorkspaceState` supplies the options it renders and tracks
+package members, catalog entries, and build-script allowances. Any other pnpm
+setting goes through the root's `workspaceYaml` option, which is projen's typed
+`PnpmWorkspaceYamlOptions`:
+
+```ts
+new DBXToolsNodeProject({ workspaceYaml: { overrides: { glob: "^13.0.0" } } });
+```
+
+`allowBuild` writes pnpm's `allowBuilds` map rather than projen's own
+`allowScripts` option, which for pnpm renders `onlyBuiltDependencies` - a key
+current pnpm does not read, so the list would leave every build script skipped.
+Only allowances are declared; a dependency that is never allowed needs no entry,
+because pnpm warns and moves on.
+
+The engine also applies `catalogMode: manual` (keeps `pnpm add` out of the
+generated catalog) and `verifyDepsBeforeRun: warn`. The file is emitted for the
+tree ROOT only; a member package never gets a nested one.
 
 ## Clean And Watch Generated Files
 
@@ -131,7 +157,7 @@ file contract as the CLI.
 - `mixin` / `projectPredicate` - constructs mixin factory and package
   predicates.
 - `tags` - built-in runtime tag mixins and compiler floors.
-- `workspace` - filesystem discovery and recorded package metadata.
+- `packages` - filesystem discovery and recorded package metadata.
 - `pnpmWorkspace` - generated pnpm workspace file and catalog model.
 - `barrels` / `moduleExports` - public entrypoint generation.
 - `codegen` - `.d.ts` to zod schema generation.
@@ -142,4 +168,7 @@ file contract as the CLI.
 - `publish` - packaging and tag-based release helpers.
 - `engineRoot` - engine package root resolution for bootstrapped repos.
 
-The user-facing CLI is [`dbx-tools`](../../cli/dbx-tools).
+The engine registers its commands as projen tasks on the workspace root, so run
+them with `pnpm run <task>` - `sync` (add `--watch`), `barrels`, `openapi`, and
+`clean`. [`@dbx-tools/cli`](../packages/cli/dbx-tools) is only needed to
+bootstrap a folder that has no `.projenrc.ts` or toolchain yet.

package/index.ts

@@ -1,7 +1,10 @@
-// Public API of @dbx-tools/projen: the projen engine (project classes, tags,
-// mixins, predicates, and the generator utilities). Hand-authored barrel.
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
 export * as barrels from "./src/barrels";
 export * as clean from "./src/clean";
+export * as cliBin from "./src/cli-bin";
 export * as codegen from "./src/codegen";
 export * as dbxToolsConfig from "./src/dbx-tools-config";
 export * as engineRoot from "./src/engine-root";
@@ -9,26 +12,45 @@ export * as generated from "./src/generated";
 export * as mixin from "./src/mixin";
 export * as moduleExports from "./src/module-exports";
 export * as openapi from "./src/openapi";
+export * as packages from "./src/packages";
 export * as pnpmWorkspace from "./src/pnpm-workspace";
 export * as project from "./src/project";
 export * as projectPredicate from "./src/project-predicate";
-export * as publish from "./src/publish";
+export * as release from "./src/release";
 export * as scaffold from "./src/scaffold";
 export * as tags from "./src/tags";
 export * as tsconfig from "./src/tsconfig";
 export * as vite from "./src/vite";
 export * as vscode from "./src/vscode";
 export * as watch from "./src/watch";
-export * as workspace from "./src/workspace";
-export type { BarrelModifier } from "./src/barrels";
+export { generateBarrels } from "./src/barrels";
+export { listGeneratedFiles, listNodeModulesDirs, removePaths } from "./src/clean";
+export { CliBinLauncher, addCliBinLaunchers } from "./src/cli-bin";
+export { generateCodegen } from "./src/codegen";
+export { DBXToolsConfig } from "./src/dbx-tools-config";
 export type { DBXToolsConfigOptions } from "./src/dbx-tools-config";
+export { resolvePkgRoot } from "./src/engine-root";
+export { makeWritable, makeReadonly, isReadonly, header, stampGenerated } from "./src/generated";
 export type { HeaderOpts } from "./src/generated";
+export { create } from "./src/mixin";
 export type { ConstructsMixin } from "./src/mixin";
-export type { ModuleExport } from "./src/module-exports";
-export type { Catalog, PnpmWorkspaceConfig, DBXToolsPNPMWorkspaceOptions } from "./src/pnpm-workspace";
-export type { DBXToolsProject, DBXToolsProjectOptions, DBXToolsTypeScriptProjectOptions } from "./src/project";
-export type { BumpLevel } from "./src/publish";
-export type { WorkspaceTag } from "./src/tags";
-export type { ViteConfigFileOptions } from "./src/vite";
+export { moduleStatements } from "./src/module-exports";
+export type { ModuleStatement, ModuleExport } from "./src/module-exports";
+export { isTsoaController, generateOpenapi } from "./src/openapi";
+export { repoRoot, DEFAULT_PACKAGE_ROOTS, projectName, toPosix, isGeneratedFile, isModuleFile, DiscoveredPackage, scanPackages, readPackageManifest, syncResynthPaths, recordedPackages, recordedRoots } from "./src/packages";
+export type { RecordedPackage } from "./src/packages";
+export { PnpmWorkspaceState } from "./src/pnpm-workspace";
+export type { Catalog, AllowBuilds, DBXToolsPNPMWorkspaceOptions } from "./src/pnpm-workspace";
+export { PackageIdentifier, identifier, applyCompilerOptions, applyIncludes, applyTasks, applyExports, addExports, addPackageFiles, srcModuleExports, PROJEN_VERSION, DBXToolsNodeProject, DBXToolsTypeScriptProject, taskScript, applyToProjects } from "./src/project";
+export type { DBXToolsProject, DBXToolsProjectOptions, DBXToolsTypeScriptProjectOptions, ApplyToProjectsOptions } from "./src/project";
+export { isProject, isDBXToolsProject, hasName, hasIdentifierPackageName, hasIdentifierName, hasIdentifierScope, hasTag, hasPath } from "./src/project-predicate";
+export { DBXToolsRelease } from "./src/release";
+export type { StandaloneRelease, DBXToolsReleaseOptions } from "./src/release";
+export { runSynth } from "./src/scaffold";
+export { AGNOSTIC_COMPILER_OPTIONS, PACKAGE_TAG_MIXINS } from "./src/tags";
+export type { PackageTag } from "./src/tags";
+export { DBXToolsRootTsconfig } from "./src/tsconfig";
+export { ViteConfigFile } from "./src/vite";
+export { DBXToolsVsCode } from "./src/vscode";
+export { watchRoots, watchLoop } from "./src/watch";
 export type { IgnoreGroupOptions } from "./src/watch";
-export type { WorkspacePackage } from "./src/workspace";

package/package.json

@@ -2,28 +2,24 @@
   "name": "@dbx-tools/projen",
   "devDependencies": {
     "@types/node": "^24.6.0",
-    "commit-and-tag-version": "^12",
     "constructs": "^10.0.0",
     "projen": "^0.101.6",
-    "ts-node": "^10.9.2",
+    "tsoa": "^6.6.0",
     "typescript": "^5.9.3"
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@dbx-tools/core": "^0.0.0",
-    "@dbx-tools/path": "^0.0.0",
-    "@dbx-tools/shared-core": "^0.0.0",
-    "@typescript-eslint/typescript-estree": "^8",
+    "@dbx-tools/core": "^0.3.40",
+    "@dbx-tools/path": "^0.3.40",
+    "@dbx-tools/shared-core": "^0.3.40",
     "commander": "^15.0.0",
-    "consola": "^3.4.2",
+    "concurrently": "^10.0.3",
     "constructs": "^10.6.0",
     "is-identifier": "^1",
     "openapi-typescript": "^7.13.0",
     "oxc-parser": "^0.90.0",
-    "p-memoize": "^8.0.0",
-    "projen": "^0.101.6",
+    "projen": "^0.101.16",
     "ts-to-zod": "^5.1.0",
-    "tsoa": "^6.6.0",
     "tsx": "^4.23.0",
     "yaml": "^2.9.0"
   },
@@ -36,15 +32,19 @@
   },
   "main": "index.ts",
   "license": "Apache-2.0",
-  "version": "0.1.1",
+  "version": "0.3.43",
   "types": "index.ts",
   "type": "module",
   "exports": {
     ".": "./index.ts",
-    "./engine-root": "./src/engine-root.ts",
     "./package.json": "./package.json"
   },
-  "//": "~~ Generated by projen. To modify, edit .projenrc.ts and run \"pnpm exec projen\".",
+  "files": [
+    "index.ts",
+    "src",
+    "tasks"
+  ],
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
   "scripts": {
     "build": "projen build",
     "bump": "projen bump",
@@ -56,9 +56,7 @@
     "post-compile": "projen post-compile",
     "post-upgrade": "projen post-upgrade",
     "pre-compile": "projen pre-compile",
-    "release": "projen release",
     "test": "projen test",
-    "unbump": "projen unbump",
     "upgrade": "projen upgrade",
     "watch": "projen watch",
     "projen": "projen"

package/src/_lazy-require.ts

@@ -0,0 +1,46 @@
+/**
+ * Loading heavy generator tools out of the CONSUMING workspace.
+ *
+ * The generators (`openapi.ts`, `codegen.ts`) each drive a large toolchain that
+ * only matters when that generator actually has work to do, so none of them are
+ * imported at module scope and several are not engine dependencies at all. Node
+ * resolves a bare specifier from the engine's own location by walking up, and under
+ * pnpm that walk passes through `node_modules/.pnpm/node_modules` - the hidden
+ * directory holding every package installed ANYWHERE in the workspace. So a tool
+ * declared by some member package (`tsoa`, via the `server` tag) or by the root
+ * (`typescript`) resolves fine from here without the engine shipping its own copy.
+ *
+ * The failure mode is a consumer whose workspace never installed the tool, which
+ * surfaces as a bare MODULE_NOT_FOUND naming a package they never asked for. The
+ * helper below turns that into the install command instead.
+ */
+
+/** How to obtain each lazily-loaded tool, for the error message. */
+const INSTALL_HINTS: Record<string, string> = {
+  tsoa: "pnpm add tsoa",
+  typescript: "pnpm add -D typescript",
+  "ts-to-zod": "pnpm add -D ts-to-zod",
+};
+
+/**
+ * `require` a generator tool from the workspace, reporting a missing one as an
+ * actionable error rather than a raw MODULE_NOT_FOUND.
+ *
+ * @param require - a `createRequire(import.meta.url)` bound to the calling module,
+ *   so the resolution walk starts at the engine and reaches the consumer's install.
+ * @param name - bare package specifier of the tool.
+ * @param reason - what the tool is needed for, named in the error.
+ */
+export function lazyRequire<T>(require: NodeJS.Require, name: string, reason: string): T {
+  try {
+    return require(name) as T;
+  } catch (cause) {
+    if ((cause as NodeJS.ErrnoException)?.code !== "MODULE_NOT_FOUND") throw cause;
+    const hint = INSTALL_HINTS[name] ?? `pnpm add -D ${name}`;
+    throw new Error(
+      `${reason} needs the \`${name}\` package, which is not installed in this workspace. ` +
+        `Add it to the package that needs it (\`${hint}\`) and re-run.`,
+      { cause },
+    );
+  }
+}

package/src/barrels.ts

@@ -0,0 +1,331 @@
+/**
+ * Barrel generator.
+ *
+ * For every package it writes a single `index.ts` **at the package root** (above
+ * `src/`) that namespace-re-exports every module under `src/`, subject to a few
+ * rules (see {@link isExcluded}):
+ *   1. a file/folder whose name starts with `_` is private and never barrelled;
+ *   2. test / `.d.ts` files are skipped;
+ *   3. a `src/**​/index.ts` is a hand-authored subpath entry, not a module;
+ *   4. only files that actually contain an `export` are re-exported.
+ *
+ * A hand-authored `exports.ts` sitting next to the generated `index.ts` (a Vite-style
+ * override) is spliced in last and wins: its exports are appended, and any generated
+ * `export * as <ns>` whose namespace it also declares is dropped so the custom one
+ * takes priority. This keeps the barrel auto-generated while letting you add or
+ * override individual exports.
+ *
+ * Each eligible module becomes `export * as <name> from "./src/x"` (camelCase
+ * namespace from its path segments; invalid identifiers suffixed with `Module`),
+ * sorted by module path.
+ *
+ * On top of the namespace lines, every export that is UNIQUE across the package
+ * (declared in exactly one module) is also HOISTED to the barrel's top level, so
+ * consumers can write `GenieMessage` or `DBXToolsNodeProject` instead of
+ * `genieModel.GenieMessage` / `project.DBXToolsNodeProject`. Types go out as
+ * `export type { ... }` (required under `isolatedModules`), values as
+ * `export { ... }`. The module namespaces stay either way, so a namespaced call
+ * site keeps working.
+ *
+ * Uniqueness is tallied over types and values TOGETHER: a name carried by two
+ * modules is ambiguous whichever kind it is, and hoisting one module's value
+ * beside another's same-named type would emit two conflicting re-exports. Such a
+ * name stays namespace-only. Names that collide with a generated namespace, or
+ * that a hand-authored `exports.ts` declares, are never hoisted (that file wins).
+ *
+ * The result gets a do-not-edit header + read-only bit (see `./generated`).
+ */
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { find } from "@dbx-tools/path";
+import { string } from "@dbx-tools/shared-core";
+import isIdentifier from "is-identifier";
+import { header, makeReadonly, makeWritable, stampGenerated, type HeaderOpts } from "./generated";
+import { moduleExports, moduleStatements, type ModuleExport } from "./module-exports";
+import { isModuleFile, toPosix, recordedPackages } from "./packages";
+
+/**
+ * A `src`-relative posix path excluded from the root barrel:
+ *   1. any path segment starting with `_` (private module or folder);
+ *   2. a test / spec file;
+ *   3. a `.d.ts` declaration;
+ *   4. a `src/**​/index.ts` - a hand-authored subpath entry (e.g. `src/react/index.ts`
+ *      behind a package's `./react` export), not a module to namespace into the barrel.
+ */
+function isExcluded(relPath: string): boolean {
+  return (
+    /(^|\/)_/.test(relPath) ||
+    /\.(test|spec)\./.test(relPath) ||
+    /\.d\.ts$/.test(relPath) ||
+    /(^|\/)index\.ts$/.test(relPath)
+  );
+}
+
+/** Module file extension, for stripping to an extensionless module path. */
+const MODULE_EXT_RE = /\.(tsx?|jsx?|mts|cts)$/;
+
+/** True for a TypeScript source file (preferred over a compiled `.js` sibling). */
+function isSourceExt(file: string): boolean {
+  return /\.(tsx?|mts|cts)$/.test(file);
+}
+
+/** Top-level statement types that make a file a re-exportable module. */
+const EXPORT_STATEMENT_TYPES = new Set([
+  "ExportNamedDeclaration",
+  "ExportDefaultDeclaration",
+  "ExportAllDeclaration",
+  "TSExportAssignment",
+]);
+
+/** True when the file has at least one top-level export statement. */
+function hasExport(file: string): boolean {
+  return moduleStatements(file).some((stmt) => EXPORT_STATEMENT_TYPES.has(stmt.type));
+}
+
+/**
+ * The do-not-edit banner stamped on every generated barrel. Deliberately stable
+ * (no timestamp) so a barrel is a pure function of its exporting modules - which
+ * is what lets {@link generateForPackage} skip the rewrite when nothing changed.
+ */
+const BARREL_HEADER: HeaderOpts = {
+  tool: "projen watch",
+  source: "the exporting modules in ./src",
+};
+
+/** `pnpm-workspace` -> `pnpmWorkspace`; nested paths join in camelCase. */
+function kebabToCamel(segment: string): string {
+  return segment.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/** Derive a valid namespace identifier from a relocated barrel module path. */
+function modulePathToNamespace(modulePath: string): string {
+  const rel = modulePath.replace(/^\.\/src\//, "").replace(/\.(tsx?|jsx?|mjs|cjs)$/, "");
+  const segments = rel.split("/").map(kebabToCamel);
+  let name =
+    segments.length === 1
+      ? segments[0]!
+      : segments[0]! +
+        segments
+          .slice(1)
+          .map((s) => string.capitalize(s))
+          .join("");
+  if (!isIdentifier(name)) {
+    name = `${name}Module`;
+  }
+  return name;
+}
+
+/** A `./src/x` module path parsed out of a generated `export * as <ns>` line. */
+function namespaceLines(content: string): { ns: string; modulePath: string }[] {
+  const out: { ns: string; modulePath: string }[] = [];
+  for (const line of content.split("\n")) {
+    const match = /^export \* as (\w+) from "(\.\/src\/.+)";\s*$/.exec(line);
+    if (match) out.push({ ns: match[1]!, modulePath: match[2]! });
+  }
+  return out;
+}
+
+/**
+ * Append hoisted top-level re-exports for every export that is UNIQUE across the
+ * package's modules - `export type { ... }` for types, `export { ... }` for
+ * values. A name declared by two or more modules is ambiguous and left
+ * namespace-only. `suppress` names (a hand-authored `exports.ts` surface) are
+ * never hoisted so that file stays authoritative.
+ */
+function hoistUniqueExports(content: string, pkgDir: string, suppress: Set<string>): string {
+  const namespaces = namespaceLines(content);
+  if (namespaces.length === 0) return content;
+
+  // A hoisted name must never collide with a generated `export * as <ns>`
+  // namespace (e.g. a `mixin.ts` exporting a `mixin` value alongside the
+  // `export * as mixin` line), so treat every namespace id as suppressed too.
+  const blocked = new Set<string>(suppress);
+  for (const { ns } of namespaces) blocked.add(ns);
+
+  // Uniqueness is tallied over types AND values together - name -> { count,
+  // owning module } - so a name any two modules share stays namespace-only
+  // whichever kind each one is. `moduleExports` already dedupes within a module,
+  // so a count above one always means more than one module.
+  const seen = new Map<string, { count: number; modulePath: string }>();
+  const perModule = new Map<string, ModuleExport[]>();
+  for (const { modulePath } of namespaces) {
+    const abs = join(pkgDir, modulePath.replace(/^\.\//, ""));
+    const exports = moduleExports(withTsExt(abs));
+    perModule.set(modulePath, exports);
+    for (const { name } of exports) {
+      const prior = seen.get(name);
+      if (prior) prior.count += 1;
+      else seen.set(name, { count: 1, modulePath });
+    }
+  }
+
+  const lines: string[] = [];
+  for (const { modulePath } of namespaces) {
+    const types: string[] = [];
+    const values: string[] = [];
+    for (const { name, isType } of perModule.get(modulePath) ?? []) {
+      if (blocked.has(name)) continue;
+      const entry = seen.get(name);
+      // Unique across the package AND this is the module that owns it.
+      if (!entry || entry.count !== 1 || entry.modulePath !== modulePath) continue;
+      (isType ? types : values).push(name);
+    }
+    if (values.length) lines.push(`export { ${values.join(", ")} } from "${modulePath}";`);
+    if (types.length) lines.push(`export type { ${types.join(", ")} } from "${modulePath}";`);
+  }
+  if (lines.length === 0) return content;
+  return `${content.replace(/\n+$/, "")}\n${lines.join("\n")}\n`;
+}
+
+/** Resolve a barrel module path (`./src/x`, extensionless) to its on-disk `.ts(x)` file. */
+function withTsExt(absNoExt: string): string {
+  for (const ext of [".ts", ".tsx", ".mts", ".cts"]) {
+    if (existsSync(absNoExt + ext)) return absNoExt + ext;
+  }
+  return `${absNoExt}.ts`;
+}
+
+/** Hand-authored override barrel: a sibling of the generated `index.ts`. */
+const CUSTOM_EXPORTS_FILE = "exports.ts";
+
+/**
+ * Best-effort set of the top-level export names a module declares - named
+ * declarations, `export { x }` specifiers, `export * as ns`, and default. A bare
+ * `export *` re-exports opaque names that can't be resolved statically, so a custom
+ * `exports.ts` should name what it means to override explicitly.
+ */
+function customExportNames(file: string): Set<string> {
+  const names = new Set<string>();
+  const body = moduleStatements(file) as ReadonlyArray<Record<string, any>>;
+  const add = (node: Record<string, any> | undefined | null): void => {
+    if (node && typeof node.name === "string") names.add(node.name);
+    else if (node && typeof node.value === "string") names.add(node.value);
+  };
+  for (const stmt of body) {
+    if (stmt.type === "ExportDefaultDeclaration") {
+      names.add("default");
+    } else if (stmt.type === "ExportAllDeclaration") {
+      add(stmt.exported); // `export * as ns from ...`; a bare `export *` has none
+    } else if (stmt.type === "ExportNamedDeclaration") {
+      for (const spec of stmt.specifiers ?? []) add(spec.exported);
+      const decl = stmt.declaration;
+      if (decl?.id) add(decl.id);
+      for (const d of decl?.declarations ?? []) if (d.id?.type === "Identifier") add(d.id);
+    }
+  }
+  return names;
+}
+
+/**
+ * Splice a hand-authored `<pkg>/exports.ts` into the barrel. Any generated
+ * `export * as <ns>` whose namespace the custom file also declares is dropped (so the
+ * custom export wins - a plain `export *` cannot otherwise override an explicit
+ * `export * as`), then the whole module is re-exported last.
+ */
+function mergeCustomExports(content: string, pkgDir: string): string {
+  if (!existsSync(join(pkgDir, CUSTOM_EXPORTS_FILE))) return content;
+  const overridden = customExportNames(join(pkgDir, CUSTOM_EXPORTS_FILE));
+  const kept = content.split("\n").filter((line) => {
+    const ns = /^export \* as (\w+) from /.exec(line)?.[1];
+    return !(ns && overridden.has(ns));
+  });
+  return `${kept.join("\n").replace(/\n+$/, "")}\nexport * from "./exports";\n`;
+}
+
+/**
+ * Rebuild one package's root barrel. Returns 1 only if the barrel's contents
+ * actually changed - a module was added, removed, renamed, or toggled its
+ * `export` - and 0 for a no-op. An edit *inside* an already-exported module (even
+ * adding a new named export) leaves the namespace `export * as … from "./src/x"`
+ * list identical, so it is a no-op.
+ */
+function generateForPackage(pkgDir: string): number {
+  const srcDir = join(pkgDir, "src");
+  if (!existsSync(srcDir)) return 0;
+
+  const rootBarrel = join(pkgDir, "index.ts");
+  // Snapshot the current barrel so we can tell a real change (module added/removed/
+  // renamed) from an edit *inside* an already-exported module, which leaves the
+  // `export * as … from "./src/x"` list - and therefore this file - byte-for-byte
+  // identical.
+  const before = existsSync(rootBarrel) ? readFileSync(rootBarrel, "utf8") : undefined;
+
+  // The re-exportable module set under `src/`: every source file that actually
+  // exports something, minus the private / test / declaration files and any
+  // `src/**/index.ts` (those are hand-authored subpath entries behind a package's
+  // `./sub` export, not modules to namespace into the root barrel). `findFiles`
+  // yields posix paths relative to `srcDir`; `hasExport` parses each via
+  // `moduleStatements` and needs the absolute path.
+  const candidates = [...find.findFiles("**/*", { cwd: srcDir })]
+    .map(toPosix)
+    .filter(isModuleFile)
+    .filter((f) => !isExcluded(f))
+    .filter((f) => hasExport(join(srcDir, f)));
+
+  // Collapse each extensionless module path to one entry, preferring a TypeScript
+  // source over a sibling compiled artifact (`math.ts` wins over a committed
+  // `math.js`), so a module is barrelled exactly once. Then sort by module path.
+  const byModulePath = new Map<string, string>();
+  for (const f of candidates) {
+    const stem = f.replace(MODULE_EXT_RE, "");
+    const existing = byModulePath.get(stem);
+    if (!existing || (!isSourceExt(existing) && isSourceExt(f))) byModulePath.set(stem, f);
+  }
+  const modulePaths = [...byModulePath.keys()].sort((a, b) => a.localeCompare(b));
+
+  // No eligible modules -> no barrel: drop any stale root barrel and bail.
+  if (modulePaths.length === 0) {
+    if (existsSync(rootBarrel)) {
+      makeWritable(rootBarrel);
+      rmSync(rootBarrel, { force: true });
+    }
+    return 0;
+  }
+
+  // Unlock the read-only barrel so the rewrite below can replace it.
+  makeWritable(rootBarrel);
+
+  // `./src/<path-without-ext>` namespaced by its path segments (camelCase; invalid
+  // identifiers suffixed with `Module`).
+  let content = modulePaths
+    .map((stem) => {
+      const modulePath = `./src/${stem}`;
+      return `export * as ${modulePathToNamespace(modulePath)} from "${modulePath}";`;
+    })
+    .join("\n");
+  // Hoist package-unique named exports to the top level. Names a hand-authored
+  // `exports.ts` declares are suppressed so that file stays authoritative.
+  const customPath = join(pkgDir, CUSTOM_EXPORTS_FILE);
+  const suppress = existsSync(customPath) ? customExportNames(customPath) : new Set<string>();
+  content = hoistUniqueExports(content, pkgDir, suppress);
+  // A sibling `exports.ts` overrides/extends the generated barrel and wins on conflict.
+  content = mergeCustomExports(content, pkgDir);
+
+  // The barrel only *changes* when its set of exporting modules does. If the
+  // stamped result matches what's already on disk, restore the read-only bit we
+  // cleared above and report no change (0) - this keeps the watcher quiet on
+  // ordinary in-file edits (which leave the export * as … list identical).
+  content = `${content.replace(/\n+$/, "")}\n`;
+  const next = `${header(BARREL_HEADER)}\n${content}`;
+  if (before === next) {
+    makeReadonly(rootBarrel);
+    return 0;
+  }
+
+  writeFileSync(rootBarrel, content);
+  stampGenerated(rootBarrel, BARREL_HEADER);
+  return 1;
+}
+
+/**
+ * Rebuild barrels for the given package dirs (default: every package recorded in
+ * `pnpm-workspace.yaml` - the source of truth, read via `recordedPackages()`).
+ * Returns the number of barrels whose contents actually changed (an unchanged
+ * export surface is a no-op), so callers can stay quiet when nothing moved.
+ */
+export function generateBarrels(opts: { dirs?: string[] } = {}): number {
+  const dirs = opts.dirs ?? recordedPackages().map((p) => p.dir);
+  let total = 0;
+  for (const dir of dirs) total += generateForPackage(dir);
+  return total;
+}