@dbx-tools/projen 0.9.40 → 0.9.46

package/src/codegen.ts

@@ -1,20 +1,20 @@
 /**
  * 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/`
+ * Scans every package whose `dbxToolsConfig.codegenInputs` declares upstream
+ * `.d.ts` inputs and turns them 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`:
+ * which inputs" is the typed config serialized into each package manifest:
  *
  *   {
  *     "name": "@dbx-tools/shared-sdk-model",
- *     "codegen": {
- *       "inputs": [
+ *     "dbxToolsConfig": {
+ *       "codegenInputs": [
  *         "node_modules/@databricks/sdk-experimental/dist/apis/dashboards/model.d.ts"
  *       ]
  *     }
@@ -46,18 +46,23 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { basename, dirname, join, resolve } from "node:path";
-import { log, object } from "@dbx-tools/shared-core";
+import { log } from "@dbx-tools/shared-core";
 import type * as ts from "typescript";
 import { lazyRequire } from "./_lazy-require.ts";
 import { header, makeReadonly, makeWritable } from "./generated.ts";
-import { readPackageManifest, recordedPackages, resolveRepoRoot } from "./packages.ts";
+import {
+  readDbxToolsConfig,
+  readPackageManifest,
+  recordedPackages,
+  resolveRepoRoot,
+} from "./packages.ts";
 
 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",
+  source: "the upstream .d.ts declared in dbxToolsConfig.codegenInputs",
 });
 
 interface CodegenInput {
@@ -77,11 +82,9 @@ function sourceLabel(source: string): string {
   return source.startsWith(nodeModulesPrefix) ? source.slice(nodeModulesPrefix.length) : source;
 }
 
-/** Read a package's `package.json` `codegen.inputs`, or `undefined` if absent. */
+/** Read a package's serialized `dbxToolsConfig.codegenInputs`, 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;
+  const inputs = readDbxToolsConfig(dir)?.codegenInputs;
   return Array.isArray(inputs) && inputs.length > 0 ? (inputs as string[]) : undefined;
 }
 
@@ -100,7 +103,7 @@ function parseInputArg(value: string): CodegenInput {
 }
 
 /**
- * The `src/` modules a set of `codegen.inputs` specs will emit, as package-relative
+ * The `src/` modules a set of codegen input specs will emit, as package-relative
  * posix paths - WITHOUT resolving or reading any input.
  *
  * This exists so callers that only need to know WHICH files are generated (the
@@ -316,9 +319,9 @@ function generatePackage(
     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,
+      // JSDoc is rewritten to `@description` so ts-to-zod emits `.describe()`.
+      // Keep the generated module comment-free; Zod owns the prose.
+      keepComments: false,
     });
     if (errors.length) {
       for (const err of errors) logger.warn(`${destination} from ${source}: ${err}`);
@@ -344,9 +347,9 @@ function generatePackage(
 }
 
 /**
- * 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.
+ * Regenerate source modules for every package declaring `dbxToolsConfig.codegenInputs`.
+ * Returns the package dirs it wrote so the caller can rebuild their barrels.
+ * `ts-to-zod` and `typescript` are lazy-loaded.
  */
 export function generateCodegen(
   projectRoot: string = resolveRepoRoot(),
@@ -365,7 +368,7 @@ export function generateCodegen(
   // than printing a line about work that was never asked for. `debug` keeps it
   // reachable when someone is actually chasing why codegen produced nothing.
   if (targets.length === 0) {
-    logger.debug("no packages declare a `codegen` field");
+    logger.debug("no packages declare dbxToolsConfig.codegenInputs");
     return [];
   }
 

package/src/dbx-tools-config.ts

@@ -1,25 +1,62 @@
 /** Typed `package.json` `dbxToolsConfig` record for a package. */
 import { javascript } from "projen";
+import { z } from "zod";
 
 /** `package.json` field name for the dbx-tools config object. */
-const DBX_TOOLS_CONFIG_KEY = "dbxToolsConfig";
+const CONFIG_KEY = "dbxToolsConfig";
 
 /** Options for {@link DBXToolsConfig}. */
 export interface DBXToolsConfigOptions {
   /** Initial tags to record (distinct; order preserved). */
   readonly tags?: string[];
+  /** Declaration inputs converted to generated Zod modules (distinct; order preserved). */
+  readonly codegenInputs?: string[];
+  /** Whether the package receives compiled npm publication machinery. */
+  readonly publishable?: boolean;
 }
 
-interface DBXToolsConfigData {
-  readonly tags?: string[];
-  readonly packageRoots?: string[];
-  readonly syncResynthPaths?: string[];
-}
+/** Serialized dbx-tools package and workspace generator configuration. */
+export const DBXToolsConfigDataSchema = z
+  .object({
+    tags: z.array(z.string().min(1)).readonly().optional().describe("Package runtime tags."),
+    codegenInputs: z
+      .array(z.string().min(1))
+      .readonly()
+      .optional()
+      .describe("Declaration inputs converted to generated Zod modules."),
+    packageRoots: z
+      .array(z.string().min(1))
+      .readonly()
+      .optional()
+      .describe("Repository paths scanned for JavaScript packages."),
+    publishable: z
+      .boolean()
+      .optional()
+      .describe("Whether compiled npm publication machinery is enabled."),
+    syncResynthPaths: z
+      .array(z.string().min(1))
+      .readonly()
+      .optional()
+      .describe("Additional paths that trigger watcher resynthesis."),
+  })
+  .strict()
+  .readonly()
+  .describe("dbxToolsConfig serialized in a generated package manifest.");
+
+/** Serialized dbx-tools package and workspace generator configuration. */
+export type DBXToolsConfigData = z.infer<typeof DBXToolsConfigDataSchema>;
 
 /** Owns the typed in-memory `dbxToolsConfig` written to `package.json`. */
 export class DBXToolsConfig {
+  /** Runtime tags that select package mixins. */
   readonly tags: string[];
+  /** Declaration inputs converted to generated Zod modules. */
+  readonly codegenInputs: string[];
+  /** Repository paths scanned for JavaScript package discovery. */
   packageRoots?: string[];
+  /** Whether compiled npm publication machinery is enabled. */
+  publishable: boolean;
+  /** Additional repository paths that trigger watcher resynthesis. */
   syncResynthPaths?: string[];
 
   constructor(
@@ -27,18 +64,24 @@ export class DBXToolsConfig {
     options: DBXToolsConfigOptions = {},
   ) {
     this.tags = [...(options.tags ?? [])];
-    project.package.addField(DBX_TOOLS_CONFIG_KEY, () => {
+    this.codegenInputs = [...(options.codegenInputs ?? [])];
+    this.publishable = options.publishable ?? true;
+    project.package.addField(CONFIG_KEY, () => {
       const data = this.data();
       return Object.keys(data).length === 0 ? undefined : data;
     });
   }
 
+  /** Render the serializable package manifest record. */
   data(): DBXToolsConfigData {
     const tags = [...new Set(this.tags)];
-    return {
+    const codegenInputs = [...new Set(this.codegenInputs)];
+    return DBXToolsConfigDataSchema.parse({
       ...(tags.length ? { tags } : {}),
+      ...(codegenInputs.length ? { codegenInputs } : {}),
+      ...(!this.publishable ? { publishable: false } : {}),
       ...(this.packageRoots?.length ? { packageRoots: this.packageRoots } : {}),
       ...(this.syncResynthPaths?.length ? { syncResynthPaths: this.syncResynthPaths } : {}),
-    };
+    });
   }
 }

package/src/generated.ts

@@ -1,14 +1,14 @@
 /**
  * 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}.
+ * native `FileBase`: package barrels, codegen modules, PythonMonkey bundles,
+ * 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";
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 
 /** First line of every banner {@link header} builds. */
 const MARKER = "// GENERATED by";
@@ -26,20 +26,7 @@ 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;
-  }
-}
-
+/** Inputs for the durable generated-file banner. */
 export interface HeaderOpts {
   /** What produced the file, e.g. `"projen watch"`. */
   readonly tool: string;

package/src/mixin.ts

@@ -38,10 +38,6 @@ export function create(
 ): ConstructsMixin {
   return {
     supports,
-    applyTo: (construct: IConstruct): void => {
-      if (supports(construct)) {
-        (applyTo as (construct: IConstruct) => void)(construct);
-      }
-    },
+    applyTo: applyTo as (construct: IConstruct) => void,
   };
 }

package/src/packages.ts

@@ -2,7 +2,7 @@
  * Package discovery + shared filesystem helpers.
  *
  * Terminology (Bit-style): a **tag** names a target environment
- * (React/Vite, Node, agnostic, ...); a workspace **package** is a folder with a
+ * (React/Bun, Node, agnostic, ...); a workspace **package** is a folder with a
  * `src/` holding at least one module file (`.ts`/`.tsx`/`.js`/`.jsx`). "Scope" is
  * reserved for the npm `@scope/` in package identifiers (e.g. `@dbx-tools/ui-app`).
  *
@@ -20,7 +20,7 @@
  * path relative to the root, reading NO manifest. {@link recordedPackages} reads
  * the recorded members from `pnpm-workspace.yaml` - the SOURCE OF TRUTH - and
  * augments each with the `name` and `tags` read back from its own `package.json`
- * (post-synth: barrels, watch, openapi), which is authoritative and so reflects any
+ * (post-synth: barrels and watch), which is authoritative and so reflects any
  * synth-time name override or resolved tag set.
  */
 import { existsSync, readFileSync } from "node:fs";
@@ -29,6 +29,7 @@ import * as projectUtils from "@dbx-tools/core/project-utils";
 import { find } from "@dbx-tools/path";
 import { json, object, stringUtils } from "@dbx-tools/shared-core";
 import { parse } from "yaml";
+import { DBXToolsConfigDataSchema, type DBXToolsConfigData } from "./dbx-tools-config.ts";
 import { isGenerated } from "./generated.ts";
 
 /** Resolve the nearest package/projenrc root at call time. */
@@ -255,16 +256,18 @@ export function readPackageManifest(dir: string): Record<string, unknown> | unde
   }
 }
 
-/** A package's `dbxToolsConfig` object, or `undefined` when absent. */
-export function readDbxToolsConfig(dir: string): Record<string, unknown> | undefined {
+/** A package's validated `dbxToolsConfig` object, or `undefined` when absent. */
+export function readDbxToolsConfig(dir: string): DBXToolsConfigData | undefined {
   const config = readPackageManifest(dir)?.dbxToolsConfig;
-  return object.isRecord(config) ? config : undefined;
+  if (config === undefined) return undefined;
+  const parsed = DBXToolsConfigDataSchema.safeParse(config);
+  return parsed.success ? parsed.data : undefined;
 }
 
 /** Read `<dir>/package.json`'s `dbxToolsConfig.tags` (`undefined` if absent). */
 function readManifestTags(dir: string): string[] | undefined {
   const tags = readDbxToolsConfig(dir)?.tags;
-  return Array.isArray(tags) ? (tags as string[]) : undefined;
+  return tags ? [...tags] : undefined;
 }
 
 /**
@@ -280,7 +283,7 @@ export function syncResynthPaths(projectRoot: string = resolveRepoRoot()): strin
 /**
  * The recorded workspace members from `pnpm-workspace.yaml` (the source of truth),
  * each augmented with the `tags` read back from its `package.json`. This is what
- * every post-synth command (barrels, watch, openapi) uses: the manifest is
+ * every post-synth command (barrels and watch) uses: the manifest is
  * authoritative, so it reflects the resolved tag set.
  * Sorted by path.
  */
@@ -333,18 +336,18 @@ export function workspaceDependencyDirectories(
 }
 
 /**
- * The configured roots recorded in the root manifest. Older workspaces without
- * that field fall back to the distinct first segment of every recorded member,
- * unioned with the defaults.
+ * The configured package roots plus the first segment of every recorded member.
+ * The member union includes self-synthesizing extra workspace members; older
+ * manifests without configured roots fall back to {@link DEFAULT_PACKAGE_ROOTS}.
  */
 export function recordedRoots(projectRoot: string = resolveRepoRoot()): string[] {
   const configured = readDbxToolsConfig(projectRoot)?.packageRoots;
-  if (Array.isArray(configured)) {
-    const roots = stringUtils.parseList(configured.map((root) => String(root)));
-    if (roots.length) return roots;
-  }
-  const roots = new Set<string>(DEFAULT_PACKAGE_ROOTS);
+  const configuredRoots = Array.isArray(configured)
+    ? stringUtils.parseList(configured.map((root) => String(root)))
+    : [];
+  const roots = new Set<string>(configuredRoots.length ? configuredRoots : DEFAULT_PACKAGE_ROOTS);
   for (const member of readRecordedMembers(projectRoot)) {
+    if (configuredRoots.some((root) => member === root || member.startsWith(`${root}/`))) continue;
     const pkg = packageOfMember(projectRoot, member);
     if (pkg) roots.add(pkg.root);
   }

package/src/pnpm-workspace.ts

@@ -76,9 +76,6 @@ const DEFAULT_CATALOG: Catalog = {
   typescript: "^5.9.3",
   commander: "^15.0.0",
   "@clack/prompts": "^1.7.0",
-  "openapi-fetch": "^0.17.0",
-  tsoa: "^6.6.0",
-  concurrently: "^10.0.3",
   "@databricks/appkit": "0.81.0",
   "@databricks/appkit-ui": "0.81.0",
   "@databricks/sdk-experimental": "^0.17.0",
@@ -141,7 +138,7 @@ const DEFAULT_WORKSPACE_YAML: javascript.PnpmWorkspaceYamlOptions = {
 export interface DBXToolsPNPMWorkspaceOptions {
   /** Initial `catalog:` registry. Defaults to {@link DEFAULT_CATALOG}. */
   readonly catalog?: Catalog;
-  /** Initial build allowances, merged over `{ esbuild: true }`. */
+  /** Initial build allowances merged over the engine's reviewed defaults. */
   readonly allowBuilds?: AllowBuilds;
 }