@dbx-tools/projen 0.6.47 → 0.6.48

package/README.md

@@ -111,9 +111,14 @@ schema modules. They are written read-only, and the root ESLint task runs with
 `--fix` (which fails on a read-only file), so each generated module is added to
 `ignorePatterns` at synth - named individually via `codegen.codegenModulePaths()`,
 never as a blanket `<package>/src/**`. A codegen package may hold hand-written
-modules beside its generated ones, and those must stay linted. `generateBarrels()` writes package-root `index.ts` barrels with
-module namespaces and flat unique type exports, returning the number that
-actually changed. A barrel whose export surface is unchanged is left untouched,
+modules beside its generated ones, and those must stay linted.
+
+`generateBarrels()` writes package-root `index.ts` barrels with module
+namespaces and flat unique type exports, returning the number that actually
+changed. A name two modules both declare is ambiguous and stays namespace-only —
+except when one of them is generated: the hand-written module is the curated view
+of the generated shape (`shared-genie`'s `genie-model.ts` extends its own
+codegen'd `dashboards.ts`), so it owns the name and stays hoisted. A barrel whose export surface is unchanged is left untouched,
 read-only bit included, so concurrent writers never collide over it. Every
 package is attempted even if one fails; the failures are re-thrown together as an
 `AggregateError` naming each package, rather than the first one abandoning the

package/package.json

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

package/src/barrels.ts

@@ -33,6 +33,15 @@
  * 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).
  *
+ * One collision is NOT ambiguous, though: a HAND-WRITTEN module and a GENERATED
+ * one (a codegen `src/` module, recognised by its do-not-edit banner) declaring
+ * the same name. The hand-written module is by definition the curated view of the
+ * generated shape - `shared-genie`'s `genie-model.ts` extends and re-exports its
+ * own generated `dashboards.ts` - so it WINS and its name is still hoisted.
+ * Treating that pair as ambiguous is what silently dropped `GenieMessage`,
+ * `GenieSpace`, and `MessageStatus` from the barrel the moment the two modules
+ * became siblings, breaking every consumer importing them by name.
+ *
  * The result gets a do-not-edit header + read-only bit (see `./generated`).
  */
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -40,7 +49,7 @@ import { join, relative } 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, type HeaderOpts } from "./generated.ts";
+import { header, isGenerated, makeReadonly, makeWritable, type HeaderOpts } from "./generated.ts";
 import { moduleExports, moduleStatements, type ModuleExport } from "./module-exports.ts";
 import { isModuleFile, toPosix, recordedPackages, repoRoot } from "./packages.ts";
 
@@ -140,8 +149,10 @@ function namespaceLines(content: string): { ns: string; modulePath: string }[] {
  * package's modules - `export type { ... }` for types, `export { ... }` for
  * non-function values (classes, consts, enums, …). `export function` names are
  * never hoisted; they stay namespace-only (`posixPath.toPosix`). 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
+ * by two or more modules is ambiguous and left namespace-only - UNLESS exactly one
+ * of them is hand-written and the rest are generated, in which case the
+ * hand-written module owns the name (see the module doc). `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 {
@@ -157,17 +168,32 @@ function hoistUniqueExports(content: string, pkgDir: string, suppress: Set<strin
   // Uniqueness is tallied over hoistable types AND values together - name ->
   // { count, owning module }. Functions are excluded from hoisting and from
   // this tally so they do not block a same-named type/class in another module.
-  const seen = new Map<string, { count: number; modulePath: string }>();
+  //
+  // A generated module never claims a name a hand-written sibling also declares:
+  // it is counted only while no hand-written module owns the name, and it yields
+  // ownership as soon as one does. So a curated re-export
+  // (`genie-model.ts`'s `GenieMessage`, extending generated `dashboards.ts`)
+  // stays hoisted, while two HAND-WRITTEN modules claiming one name are still
+  // ambiguous and stay namespace-only.
+  const seen = new Map<string, { count: number; modulePath: string; generated: boolean }>();
   const perModule = new Map<string, ModuleExport[]>();
   for (const { modulePath } of namespaces) {
-    const exports = moduleExports(join(pkgDir, modulePath.replace(/^\.\//, ""))).filter(
-      (e) => !e.isFunction,
-    );
+    const file = join(pkgDir, modulePath.replace(/^\.\//, ""));
+    const exports = moduleExports(file).filter((e) => !e.isFunction);
     perModule.set(modulePath, exports);
+    const generated = isGenerated(file);
     for (const { name } of exports) {
       const prior = seen.get(name);
-      if (prior) prior.count += 1;
-      else seen.set(name, { count: 1, modulePath });
+      if (!prior) {
+        seen.set(name, { count: 1, modulePath, generated });
+        continue;
+      }
+      // Hand-written beats generated, either direction, without counting as a clash.
+      if (prior.generated !== generated) {
+        if (prior.generated) seen.set(name, { count: 1, modulePath, generated });
+        continue;
+      }
+      prior.count += 1;
     }
   }
 

package/src/generated.ts

@@ -10,6 +10,9 @@
  */
 import { chmodSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 
+/** First line of every banner {@link header} builds. */
+const MARKER = "// GENERATED by";
+
 const READONLY = 0o444;
 const WRITABLE = 0o644;
 
@@ -46,12 +49,29 @@ export interface HeaderOpts {
 
 /** Build the do-not-edit banner (line comments, for TS/JS). */
 export function header(opts: HeaderOpts): string {
-  const lines = [`// GENERATED by ${opts.tool} - DO NOT EDIT.`];
+  const lines = [`${MARKER} ${opts.tool} - DO NOT EDIT.`];
   if (opts.source) lines.push(`// Regenerated from ${opts.source}.`);
   lines.push("// Hand edits are overwritten on the next watch; this file is read-only.");
   return `${lines.join("\n")}\n`;
 }
 
+/**
+ * True if the file exists and carries the do-not-edit banner {@link header}
+ * writes - i.e. a toolchain wrote it and a hand edit would be overwritten.
+ *
+ * Prefer this over {@link isReadonly} when the answer must survive a fresh
+ * clone: git tracks no read-only bit, so a generated file checked out before the
+ * first synth looks hand-authored by mode alone, while the banner is part of the
+ * committed content.
+ */
+export function isGenerated(file: string): boolean {
+  try {
+    return readFileSync(file, "utf8").startsWith(MARKER);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Prepend the do-not-edit header to a file some tool just wrote (e.g. a
  * generated barrel `index.ts`), then set it read-only. Idempotent.
@@ -59,7 +79,7 @@ export function header(opts: HeaderOpts): string {
 export function stampGenerated(file: string, opts: HeaderOpts): void {
   makeWritable(file);
   const body = readFileSync(file, "utf8");
-  const next = body.startsWith("// GENERATED by") ? body : `${header(opts)}\n${body}`;
+  const next = body.startsWith(MARKER) ? body : `${header(opts)}\n${body}`;
   writeFileSync(file, next);
   makeReadonly(file);
 }