@dbx-tools/projen 0.1.1 → 0.3.43

package/src/clean.ts

@@ -0,0 +1,88 @@
+/**
+ * The `clean` task (`pnpm run clean`): enumerate the workspace's generated files (plus every
+ * `node_modules` directory) and delete a chosen subset. This is the pure filesystem
+ * half - reusable enumerate/remove helpers; the task that drives them (argv `-y`, the
+ * `@clack/prompts` multiselect picker with all preselected, the TTY guard) lives in
+ * `tasks/clean.ts`, which forwards to these functions.
+ *
+ * "Generated" is detected structurally, not by a hardcoded list: every file this
+ * toolchain writes is set READ-ONLY (projen's own config + the generated barrels; see
+ * {@link isReadonly}), while every hand-authored source stays writable. So a read-only
+ * file under the repo is a clean target - EXCEPT anything inside a dot-prefixed folder
+ * (`.projen`, `.vscode`, `.git`, ...) and `.gitignore` itself, which clean always leaves
+ * alone (projen re-syncs `.projen`/`.vscode` on the next synth). `node_modules` is
+ * enumerated separately (see {@link listNodeModulesDirs}) as whole directories.
+ *
+ * Deleting only generated files is never destructive to the ability to regenerate:
+ * `.projenrc.ts` imports the engine by SOURCE path (relative into the repo, e.g.
+ * `packages/node/projen/src/...`, or from an installed package such as
+ * `@dbx-tools/projen`), so even after deleting every barrel, manifest, and
+ * `.projen/*`, `pnpm exec projen` still rebuilds the whole tree. Removing `node_modules` additionally requires a
+ * `pnpm install` first - the engine's runtime deps live there - so a clean that takes
+ * `node_modules` must be followed by reinstall, then re-synth.
+ */
+import { existsSync, rmSync, statSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { find } from "@dbx-tools/path";
+import { isReadonly, makeWritable } from "./generated";
+import { repoRoot, toPosix } from "./packages";
+
+/**
+ * Basenames `clean` never removes even when they are generated/read-only. `.gitignore`
+ * is hand-relevant git plumbing: nuking it would un-ignore `node_modules`/build output
+ * on the very next tool run, so it is always kept.
+ */
+const CLEAN_SKIP_FILES: ReadonlySet<string> = new Set([".gitignore"]);
+
+/**
+ * Every generated (read-only) file in the workspace, as absolute paths sorted by
+ * repo-relative posix path. Skips vendor/build/VCS dirs via node-path's built-in
+ * ignores AND every dot-prefixed folder (`.projen`, `.vscode`, `.github`, ...), and
+ * {@link CLEAN_SKIP_FILES} entry (`.gitignore`).
+ */
+export function listGeneratedFiles(root: string = repoRoot): string[] {
+  const rel = (f: string): string => toPosix(relative(root, f));
+  return [...find.findFiles("**/*", { cwd: root })]
+    .map((f) => join(root, f))
+    .filter(isReadonly)
+    .filter((f) => !CLEAN_SKIP_FILES.has(basename(f)))
+    .sort((a, b) => rel(a).localeCompare(rel(b)));
+}
+
+/**
+ * Every `node_modules` directory in the workspace (the root's plus each package's), as
+ * absolute paths sorted by repo-relative posix path. The walk RECORDS a `node_modules`
+ * dir but never descends into it, so a nested store/symlink `node_modules`
+ * (`node_modules/.pnpm/x/node_modules`, a package's linked deps) is never listed on its
+ * own - removing the top-level dir takes it along. Other vendor/build/VCS dirs are
+ * skipped for speed.
+ */
+export function listNodeModulesDirs(root: string = repoRoot): string[] {
+  if (!existsSync(root)) return [];
+  const rel = (f: string): string => toPosix(relative(root, f));
+  return [...find.findFiles("**/node_modules", { cwd: root, ignoreOptions: { dot: false } })]
+    .map((match) => join(root, match))
+    .sort((a, b) => rel(a).localeCompare(rel(b)));
+}
+
+/**
+ * Delete the given paths - generated files and/or whole directories (`node_modules`).
+ * A regular file has its read-only bit cleared first (so unlink also works on Windows);
+ * a directory is removed recursively and is NOT chmod'd (file mode `0o644` would strip
+ * a dir's traversal bit and break the recursive delete). Missing paths are ignored (a
+ * racing watcher may have already removed one). Returns the count actually removed.
+ */
+export function removePaths(paths: readonly string[]): number {
+  let removed = 0;
+  for (const path of paths) {
+    try {
+      if (!existsSync(path)) continue;
+      if (statSync(path).isFile()) makeWritable(path);
+      rmSync(path, { recursive: true, force: true });
+      removed++;
+    } catch {
+      // Already gone, or racing the watcher - nothing to do.
+    }
+  }
+  return removed;
+}

package/src/cli-bin.ts

@@ -0,0 +1,72 @@
+/**
+ * Generated `bin/<name>.mjs` launchers for a CLI package's TypeScript entries.
+ *
+ * A CLI's real entry is a `.ts` file, which Node cannot run on its own, so something
+ * has to register tsx first. A `#!/usr/bin/env -S npx tsx` shebang does that only for
+ * a WORKSPACE checkout: `npx` resolves tsx from the current working directory, and a
+ * globally installed CLI (`npm i -g @dbx-tools/cli`) has no relationship to whatever
+ * directory the user happens to be in - so every first invocation stalls to fetch tsx
+ * from the network, or fails outright when offline.
+ *
+ * {@link CliBinLauncher} emits a tiny `.mjs` sibling that npm points its bin symlink
+ * at. Because the launcher reaches tsx through a bare `import` specifier, NODE
+ * resolves it relative to the launcher's own location - i.e. the CLI package's own
+ * `node_modules` - which is exactly where the `cli` tag's runtime tsx dependency
+ * installs it. The `.ts` entry stays the source of truth; the launcher only registers
+ * the loader and hands off.
+ *
+ * {@link addCliBinLaunchers} discovers the entries by scanning the package's `bin/`
+ * directory at synth, so a new CLI just needs its `.ts` file plus a `package.json`
+ * bin pointing at the matching `.mjs`.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { type Project, TextFile } from "projen";
+import { header } from "./generated";
+
+/** Directory (package-relative) holding a CLI's executable entries. */
+const BIN_DIR = "bin";
+
+/** Render the launcher source for a `.ts` entry sitting beside it. */
+function renderLauncher(entryFileName: string): string {
+  return `#!/usr/bin/env node
+${header({
+  tool: "projen synth (cli tag)",
+  source: `./${entryFileName}`,
+})}
+// Resolved as a bare specifier so Node looks in THIS file's package rather than the
+// caller's cwd - the only way a globally installed CLI finds its own tsx.
+import { register } from "tsx/esm/api";
+
+register();
+await import(new URL(${JSON.stringify(`./${entryFileName}`)}, import.meta.url).href);
+`;
+}
+
+/**
+ * A projen-owned, read-only `.mjs` launcher that registers tsx and defers to the
+ * `.ts` entry beside it.
+ */
+export class CliBinLauncher extends TextFile {
+  constructor(project: Project, entryFileName: string) {
+    super(project, join(BIN_DIR, entryFileName.replace(/\.ts$/, ".mjs")), {
+      readonly: true,
+      executable: true,
+      lines: renderLauncher(entryFileName).split("\n"),
+    });
+  }
+}
+
+/**
+ * Emit a {@link CliBinLauncher} for every `.ts` entry in the package's `bin/`
+ * directory. A package with no `bin/` directory is left alone.
+ */
+export function addCliBinLaunchers(project: Project): void {
+  const binDir = join(project.outdir, BIN_DIR);
+  if (!existsSync(binDir)) return;
+
+  for (const entry of readdirSync(binDir).sort()) {
+    if (!entry.endsWith(".ts") || entry.endsWith(".d.ts")) continue;
+    new CliBinLauncher(project, entry);
+  }
+}

package/src/codegen.ts

@@ -0,0 +1,339 @@
+/**
+ * Codegen generator (ts-to-zod based).
+ *
+ * Scans every package whose `package.json` declares a `codegen`
+ * field and turns the listed upstream `.d.ts` inputs into read-only `src/`
+ * modules of zod schemas plus matching inferred TypeScript types. Each input
+ * emits one `src/<name>.ts` (schemas + `export type X = z.infer<typeof
+ * xSchema>` lines); the barrel generator then namespaces it into the package's
+ * root barrel like any other `src/` module (`sdkModel.dashboards.genieMessageSchema`).
+ *
+ * The single source of truth for "which packages get generated content, from
+ * which inputs" is each consumer's own `package.json`:
+ *
+ *   {
+ *     "name": "@dbx-tools/shared-sdk-model",
+ *     "codegen": {
+ *       "inputs": [
+ *         "node_modules/@databricks/sdk-experimental/dist/apis/dashboards/model.d.ts"
+ *       ]
+ *     }
+ *   }
+ *
+ * Each entry under `inputs` is a path (relative to the package for
+ * `node_modules/...`, else repo-root-relative), optionally suffixed with
+ * `=<name>` to override the auto-derived basename:
+ *
+ *   - `apis/dashboards/model.d.ts`     -> `src/dashboards.ts`
+ *   - `apis/dashboards/model.d.ts=foo` -> `src/foo.ts`
+ *
+ * Generated modules are written read-only with the standard do-not-edit header
+ * (see `./generated`), so they are indistinguishable from any other generated
+ * file and hand-written `src/` modules (writable) are never touched. Stale
+ * generated modules from a removed input are cleaned up on each run.
+ *
+ * Each input is preprocessed with the TypeScript compiler API before ts-to-zod
+ * sees it: every `import` declaration is dropped, and any type reference whose
+ * root identifier was introduced by one of those imports is rewritten to
+ * `unknown` (codegen output is a pure data-shape surface; peer SDK runtime
+ * modules don't belong here).
+ *
+ * `ts-to-zod` and `typescript` are loaded lazily (heavy, and only needed when
+ * codegen actually runs), so importing this module stays cheap. Codegen runs as
+ * part of synth's post-synthesize pass (see `GeneratedSource` in `project.ts`);
+ * SDK `.d.ts` inputs change rarely, so there's no separate task or watcher.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join, resolve } from "node:path";
+import type * as ts from "typescript";
+import { lazyRequire } from "./_lazy-require";
+import { header, isReadonly, makeReadonly, makeWritable } from "./generated";
+import { log, object } from "@dbx-tools/shared-core";
+import { readPackageManifest, repoRoot, recordedPackages } from "./packages";
+
+const logger = log.logger("projen:codegen");
+
+/** Do-not-edit banner stamped on every generated codegen module. */
+const HEADER = header({
+  tool: "projen synth (codegen: ts-to-zod)",
+  source: "the upstream .d.ts declared in package.json codegen.inputs",
+});
+
+interface CodegenInput {
+  /** Absolute path to the source `.d.ts` file. */
+  source: string;
+  /** Output basename (e.g. `dashboards` -> emits `src/dashboards.ts`). */
+  name: string;
+}
+
+/** Read a package's `package.json` `codegen.inputs`, or `undefined` if absent. */
+function codegenInputs(dir: string): string[] | undefined {
+  const codegen = readPackageManifest(dir)?.codegen;
+  if (!object.isRecord(codegen)) return undefined;
+  const inputs = codegen.inputs;
+  return Array.isArray(inputs) && inputs.length > 0 ? (inputs as string[]) : undefined;
+}
+
+function deriveName(path: string): string {
+  const file = basename(path);
+  // SDK convention: `apis/<api>/model.d.ts`. Use the parent directory's name
+  // so `apis/dashboards/model.d.ts` -> `dashboards`.
+  if (file === "model.d.ts" || file === "model.ts") return basename(dirname(path));
+  return file.replace(/\.d\.ts$|\.ts$/, "");
+}
+
+function parseInputArg(value: string): CodegenInput {
+  const eq = value.indexOf("=");
+  if (eq === -1) return { source: value, name: deriveName(value) };
+  return { source: value.slice(0, eq), name: value.slice(eq + 1) };
+}
+
+/**
+ * Resolve a codegen input to an absolute path. A `node_modules/...` source is
+ * searched for in each `node_modules` from the consuming package up to the
+ * filesystem root, so it resolves whether the dependency is nested under the
+ * package or hoisted to the workspace root. Any other source is treated as
+ * repo-root-relative.
+ */
+function resolveInputSource(source: string, fromDir: string): string {
+  if (source.startsWith("node_modules/")) {
+    let dir = fromDir;
+    for (;;) {
+      const candidate = resolve(dir, source);
+      if (existsSync(candidate)) return candidate;
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return resolve(repoRoot, source);
+}
+
+/**
+ * Parse `entryPath` as TypeScript, drop every `import` declaration, and rewrite
+ * any type reference whose root identifier was introduced by one of those
+ * imports to the `unknown` keyword. ts-to-zod then sees a self-contained source
+ * where the dropped peer modules surface as `z.unknown()` schemas.
+ */
+function stripImports(tsRuntime: typeof ts, entryPath: string): string {
+  const text = readFileSync(entryPath, "utf-8");
+  const sf = tsRuntime.createSourceFile(
+    entryPath,
+    text,
+    tsRuntime.ScriptTarget.Latest,
+    /*setParentNodes*/ true,
+    tsRuntime.ScriptKind.TS,
+  );
+
+  const namespaceAliases = new Set<string>();
+  const importedNames = new Set<string>();
+  for (const stmt of sf.statements) {
+    if (!tsRuntime.isImportDeclaration(stmt) || !stmt.importClause) continue;
+    const c = stmt.importClause;
+    if (c.name) importedNames.add(c.name.text);
+    const nb = c.namedBindings;
+    if (!nb) continue;
+    if (tsRuntime.isNamespaceImport(nb)) {
+      namespaceAliases.add(nb.name.text);
+    } else {
+      for (const el of nb.elements) importedNames.add(el.name.text);
+    }
+  }
+
+  const unknownType = (): ts.KeywordTypeNode =>
+    tsRuntime.factory.createKeywordTypeNode(tsRuntime.SyntaxKind.UnknownKeyword);
+
+  const transformer: ts.TransformerFactory<ts.SourceFile> = (context) => (root) => {
+    const visitor: ts.Visitor = (node) => {
+      if (tsRuntime.isImportDeclaration(node)) return undefined;
+
+      // `ns.X` / `X` in TYPE position -> `unknown`, only when the root
+      // identifier came from an import; local declarations stay untouched.
+      if (tsRuntime.isTypeReferenceNode(node)) {
+        const tn = node.typeName;
+        if (
+          tsRuntime.isQualifiedName(tn) &&
+          tsRuntime.isIdentifier(tn.left) &&
+          namespaceAliases.has(tn.left.text)
+        ) {
+          return unknownType();
+        }
+        if (tsRuntime.isIdentifier(tn) && importedNames.has(tn.text)) {
+          return unknownType();
+        }
+      }
+
+      // `ns.X` in VALUE position: drop the namespace prefix so ts-to-zod sees a
+      // bare identifier.
+      if (
+        tsRuntime.isPropertyAccessExpression(node) &&
+        tsRuntime.isIdentifier(node.expression) &&
+        namespaceAliases.has(node.expression.text)
+      ) {
+        return node.name;
+      }
+
+      return tsRuntime.visitEachChild(node, visitor, context);
+    };
+    return tsRuntime.visitEachChild(root, visitor, context);
+  };
+
+  const result = tsRuntime.transform(sf, [transformer]);
+  const printer = tsRuntime.createPrinter({ removeComments: false });
+  const transformed = result.transformed[0] ?? sf;
+  const out = printer.printFile(transformed);
+  result.dispose();
+  return out;
+}
+
+/**
+ * Final shaping before ts-to-zod sees the source:
+ *
+ *   1. Promote every top-level `interface` / `type` to an `export` (ts-to-zod
+ *      only emits schemas for exported declarations and bails on exported types
+ *      referencing non-exported ones).
+ *   2. Rewrite each JSDoc block so its leading prose becomes a single
+ *      `@description` tag (ts-to-zod emits a matching `.describe(...)` call).
+ *      The original prose is dropped so it doesn't appear twice. Other tags
+ *      (`@minimum`, `@format`, ...) flow through verbatim.
+ */
+function preprocess(source: string): string {
+  const out = source.replace(/^(interface|type)\s/gm, "export $1 ");
+  return out.replace(/\/\*\*([\s\S]*?)\*\//g, (match, body: string) => {
+    if (/@description\b/.test(body)) return match;
+
+    const lines = body
+      .replace(/^\n/, "")
+      .split("\n")
+      .map((line) => line.replace(/^\s*\*\s?/, "").replace(/\s+$/, ""));
+
+    const firstTagIdx = lines.findIndex((line) => /^@\w+/.test(line));
+    const descLines = firstTagIdx === -1 ? lines : lines.slice(0, firstTagIdx);
+    const tagLines = firstTagIdx === -1 ? [] : lines.slice(firstTagIdx);
+
+    const description = descLines.join(" ").replace(/\s+/g, " ").trim();
+    if (!description) return match;
+
+    const rebuilt = [`@description ${description}`, ...tagLines];
+    return `/**\n${rebuilt.map((line) => ` * ${line}`.trimEnd()).join("\n")}\n */`;
+  });
+}
+
+/**
+ * Take ts-to-zod's `getInferredTypes(...)` output - shaped for a separate file
+ * (banner, `import { z } from "zod"`, `import * as generated from "<schemas>"`,
+ * then `export type X = z.infer<typeof generated.xSchema>` lines) - and rewrite
+ * it for inclusion in the same file as the schemas: drop the banner and both
+ * imports, and drop the `generated.` namespace prefix from every reference so
+ * the type aliases bind to the colocated schema constants.
+ */
+function inlineInferredTypes(inferredFile: string): string {
+  return inferredFile
+    .replace(/^\/\/ Generated by ts-to-zod\s*\n/, "")
+    .replace(/^import \{ z \} from "zod";\s*\n+/m, "")
+    .replace(/^import \* as generated from "[^"]*";\s*\n+/m, "")
+    .replace(/\bgenerated\.(\w+)/g, "$1")
+    .trim();
+}
+
+/** True if `<srcDir>/<file>` is a codegen-generated module (read-only + our header). */
+function isGeneratedModule(srcDir: string, file: string): boolean {
+  if (!file.endsWith(".ts")) return false;
+  const path = join(srcDir, file);
+  if (!isReadonly(path)) return false;
+  try {
+    return readFileSync(path, "utf8").startsWith("// GENERATED by projen synth (codegen:");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Regenerate the codegen `src/` modules for one consumer package. The
+ * package's `package.json` is read-only - the `inputs` list comes out, nothing
+ * flows back. Returns the package dir so the caller can rebuild its barrel.
+ */
+function generatePackage(
+  tsRuntime: typeof ts,
+  generate: typeof import("ts-to-zod").generate,
+  dir: string,
+  inputs: string[],
+): string {
+  const parsed = inputs.map(parseInputArg);
+  const srcDir = resolve(dir, "src");
+  mkdirSync(srcDir, { recursive: true });
+
+  // Remove prior generated modules (read-only + our header) so a dropped input
+  // can't leave a stale module behind. Hand-written `src/` files stay writable
+  // and are never matched, so they're left alone.
+  const emitted = new Set(parsed.map((input) => `${input.name}.ts`));
+  for (const file of readdirSync(srcDir)) {
+    if (!emitted.has(file) && isGeneratedModule(srcDir, file)) {
+      makeWritable(join(srcDir, file));
+      rmSync(join(srcDir, file));
+    }
+  }
+
+  let warnings = 0;
+  for (const input of parsed) {
+    const sourcePath = resolveInputSource(input.source, dir);
+    if (!existsSync(sourcePath)) {
+      throw new Error(`codegen input not found: ${input.source}`);
+    }
+
+    const sourceText = preprocess(stripImports(tsRuntime, sourcePath));
+    const { getZodSchemasFile, getInferredTypes, errors } = generate({
+      sourceText,
+      // Carry JSDoc through so the `@description` tag stays visible alongside
+      // the matching `.describe(...)`.
+      keepComments: true,
+    });
+    if (errors.length) {
+      warnings += errors.length;
+      for (const err of errors) logger.warn(`  ! ${err}`);
+    }
+
+    // ts-to-zod adds an import line only when the source references external
+    // types; bundling makes everything self-contained, so this is never read.
+    const importPath = `./${input.name}.js`;
+    const schemas = getZodSchemasFile(importPath);
+    const inferred = inlineInferredTypes(getInferredTypes(importPath));
+    const content = HEADER + "\n" + schemas.trimEnd() + "\n\n" + inferred + "\n";
+    const outPath = resolve(srcDir, `${input.name}.ts`);
+    makeWritable(outPath);
+    writeFileSync(outPath, content);
+    makeReadonly(outPath);
+  }
+
+  logger.success(
+    `${basename(dir)}: ${parsed.length} module(s)` + (warnings ? ` (${warnings} warning(s))` : ""),
+  );
+  return dir;
+}
+
+/**
+ * Regenerate the `generated/` tree for every package declaring a
+ * `codegen` field. Returns the package dirs it wrote so the caller can rebuild
+ * their barrels. `ts-to-zod` + `typescript` are lazy-loaded.
+ */
+export function generateCodegen(): string[] {
+  const targets = recordedPackages()
+    .map((p) => ({ dir: p.dir, inputs: codegenInputs(p.dir) }))
+    .filter((t): t is { dir: string; inputs: string[] } => t.inputs !== undefined);
+
+  if (targets.length === 0) {
+    logger.info("no packages declare a `codegen` field");
+    return [];
+  }
+
+  const require = createRequire(import.meta.url);
+  const tsRuntime = lazyRequire<typeof ts>(require, "typescript", "codegen");
+  const { generate } = lazyRequire<typeof import("ts-to-zod")>(require, "ts-to-zod", "codegen");
+
+  const written: string[] = [];
+  for (const target of targets) {
+    written.push(generatePackage(tsRuntime, generate, target.dir, target.inputs));
+  }
+  return written;
+}

package/src/dbx-tools-config.ts

@@ -0,0 +1,84 @@
+/**
+ * In-memory `package.json` `dbxToolsConfig` record for a package.
+ *
+ * Values are read and written on the component's object; each write flushes the
+ * record to the manifest through `project.package.addField`.
+ */
+import { object } from "@dbx-tools/shared-core";
+import { Component, javascript } from "projen";
+
+/** `package.json` field name for the dbx-tools config object. */
+const DBX_TOOLS_CONFIG_KEY = "dbxToolsConfig";
+
+/** Options for {@link DBXToolsConfig}. */
+export interface DBXToolsConfigOptions {
+  /** Initial tags to record (distinct; order preserved). */
+  readonly tags?: string[];
+}
+
+function readDBXToolsConfig(pkg: javascript.NodePackage): Record<string, unknown> {
+  try {
+    const manifest = pkg.manifest as unknown;
+    if (object.isRecord(manifest)) {
+      const config = manifest[DBX_TOOLS_CONFIG_KEY];
+      if (object.isRecord(config)) {
+        return config;
+      }
+    }
+  } catch {}
+  return {};
+}
+
+function loadConfig(dbxToolsConfig: DBXToolsConfig, pkg: javascript.NodePackage) {
+  const { tags, ...config } = readDBXToolsConfig(pkg);
+  if (Array.isArray(tags))
+    object
+      .sequence(tags)
+      .filter((v: unknown) => typeof v === "string")
+      .forEach((v: string) => dbxToolsConfig.tags.push(v));
+  Object.entries(config).forEach(([key, value]) => {
+    dbxToolsConfig[key] = value;
+  });
+}
+
+/**
+ * Owns a package's in-memory `dbxToolsConfig` object. Callers mutate it
+ * directly - push to {@link DBXToolsConfig.tags}, or assign any other key
+ * through the index signature. Every own key (i.e. not inherited from
+ * `Component`) is collected by {@link DBXToolsConfig.data} and written through
+ * `project.package.addField` at synth, so nothing is cached on a field.
+ */
+export class DBXToolsConfig extends Component {
+  private readonly inheritedKeys: ReadonlySet<string>;
+  readonly tags: string[];
+  [key: string]: unknown;
+
+  constructor(
+    override readonly project: javascript.NodeProject,
+    options: DBXToolsConfigOptions = {},
+  ) {
+    super(project);
+    this.inheritedKeys = new Set(Object.keys(this));
+    this.tags = [];
+    loadConfig(this, project.package);
+    options.tags?.forEach((v: string) => this.tags.push(v));
+  }
+
+  data(): Record<string, unknown> {
+    const dataRecord: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(this)) {
+      if (this.inheritedKeys.has(key)) continue;
+      dataRecord[key] = value;
+    }
+    dataRecord.tags = object.sequence(this.tags).distinct().toArray();
+    return dataRecord;
+  }
+
+  preSynthesize(): void {
+    let dataRecord: Record<string, unknown> | undefined = this.data();
+    if (object.isEmpty(dataRecord, { recursive: true })) {
+      dataRecord = undefined;
+    }
+    this.project.package.addField(DBX_TOOLS_CONFIG_KEY, dataRecord);
+  }
+}

package/src/engine-root.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolution of the projen engine package root.
+ *
+ * Deliberately projen-free and dependency-light, so locating the engine's
+ * install never pulls in projen itself.
+ */
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { project } from "@dbx-tools/core";
+import { functionModule } from "@dbx-tools/shared-core";
+
+const ENGINE_PKG = "@dbx-tools/projen";
+
+/**
+ * Absolute path to the projen engine package root.
+ *
+ * Walks up from this module with shared-core's {@link project.root} (the nearest
+ * package bounded by the enclosing npm/git root), so it resolves both in-repo and
+ * when installed as a dependency. Memoized with shared-core's
+ * {@link functionModule.memoize}, which caches only a successful result - a
+ * throw is retried on the next call.
+ */
+export const resolvePkgRoot = functionModule.memoize((): string => {
+  const found = project.root(dirname(fileURLToPath(import.meta.url)));
+  if (!found) throw new Error(`${ENGINE_PKG} package root not found`);
+  return found;
+});

package/src/generated.ts

@@ -0,0 +1,65 @@
+/**
+ * Read-only / do-not-edit helpers for generated output projen does not own as a
+ * native `FileBase`: the barrels we write, openapi artifacts, and any other
+ * toolchain file stamped via {@link stampGenerated}.
+ *
+ * projen already writes its own generated files read-only with a marker; these give
+ * barrels and other watch-time output the same contract - a do-not-edit header and a
+ * read-only (0o444) bit. Rewriting one therefore goes through {@link makeWritable}
+ * first, then {@link stampGenerated}.
+ */
+import { chmodSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+
+const READONLY = 0o444;
+const WRITABLE = 0o644;
+
+/** Drop the read-only bit if the file exists (no-op otherwise). */
+export function makeWritable(file: string): void {
+  if (existsSync(file)) chmodSync(file, WRITABLE);
+}
+
+/** Set the read-only bit if the file exists (no-op otherwise). */
+export function makeReadonly(file: string): void {
+  if (existsSync(file)) chmodSync(file, READONLY);
+}
+
+/**
+ * True if the file exists and has no owner-write bit. This is the toolchain's
+ * generated-file signal: everything projen and the barrel generator write is set read-only
+ * (see {@link makeReadonly}), while hand-authored source stays writable - so a
+ * read-only file under the repo (outside vendor/build dirs) is a generated file.
+ */
+export function isReadonly(file: string): boolean {
+  try {
+    return (statSync(file).mode & 0o200) === 0;
+  } catch {
+    return false;
+  }
+}
+
+export interface HeaderOpts {
+  /** What produced the file, e.g. `"projen watch"`. */
+  readonly tool: string;
+  /** What the file is derived from, e.g. `"the exporting modules beside it"`. */
+  readonly source?: string;
+}
+
+/** 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.`];
+  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`;
+}
+
+/**
+ * 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.
+ */
+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}`;
+  writeFileSync(file, next);
+  makeReadonly(file);
+}