@codedrifters/configulator 0.0.314 → 0.0.316

package/lib/index.js

@@ -286,6 +286,7 @@ __export(index_exports, {
   TIER_AWARE_BUNDLE_NAMES: () => TIER_AWARE_BUNDLE_NAMES,
   TestRunner: () => TestRunner,
   TsDocCoverageKind: () => TsDocCoverageKind,
+  TsdocConfig: () => TsdocConfig,
   TurboRepo: () => TurboRepo,
   TurboRepoTask: () => TurboRepoTask,
   TypeScriptConfig: () => TypeScriptConfig,
@@ -27868,16 +27869,32 @@ var _TurboRepo = class _TurboRepo extends import_lib2.Component {
       this.globalEnv.push(name);
     }
   }
-  /**
-   * Sets GIT_BRANCH_NAME so root tasks (e.g. build:all) pass the current branch.
-   * Value must be exactly $(...) so Projen's task runtime expands it; the shell
-   * then expands ${GIT_BRANCH_NAME:-$(git rev-parse --abbrev-ref HEAD)}.
-   */
-  activateBranchNameEnvVar() {
-    this.addGlobalEnvVar(
-      "GIT_BRANCH_NAME",
-      '$(echo "${GIT_BRANCH_NAME:-$(git rev-parse --abbrev-ref HEAD)}")'
+  activateBranchNameEnvVar(options) {
+    const value = '$(echo "${GIT_BRANCH_NAME:-$(git rev-parse --abbrev-ref HEAD)}")';
+    if (options === void 0) {
+      this.project.logger.warn(
+        "TurboRepo.activateBranchNameEnvVar() with no arguments is deprecated. It writes GIT_BRANCH_NAME to the root `globalEnv`, which forces every task in the monorepo to miss cache on every branch switch. Pass `{ tasks: [...] }` and name only the tasks that actually consume the branch (e.g. CDK synth/package) to preserve cross-branch cache hits for everything else."
+      );
+      this.addGlobalEnvVar("GIT_BRANCH_NAME", value);
+      return;
+    }
+    const knownTaskNames = this.tasks.map((task) => task.name);
+    const unknown = options.tasks.filter(
+      (name) => !knownTaskNames.includes(name)
     );
+    if (unknown.length > 0) {
+      throw new Error(
+        `TurboRepo.activateBranchNameEnvVar: unknown task name(s) ${JSON.stringify(
+          unknown
+        )}. Known tasks on this TurboRepo: ${JSON.stringify(knownTaskNames)}.`
+      );
+    }
+    for (const name of options.tasks) {
+      const task = this.tasks.find((t) => t.name === name);
+      if (task && !task.env.includes("GIT_BRANCH_NAME")) {
+        task.env.push("GIT_BRANCH_NAME");
+      }
+    }
   }
   preSynthesize() {
     let nextDependsOn = this.project.deps.all.filter((d) => d.version === "workspace:*").map((d) => [d.name, ROOT_TURBO_TASK_NAME].join("#"));
@@ -27911,7 +27928,6 @@ var _TurboRepo = class _TurboRepo extends import_lib2.Component {
         ui: this.isRootProject ? this.ui : void 0,
         dangerouslyDisablePackageManagerCheck: this.isRootProject ? this.dangerouslyDisablePackageManagerCheck : void 0,
         cacheDir: this.isRootProject ? this.cacheDir : void 0,
-        daemon: this.isRootProject ? this.daemon : void 0,
         envMode: this.isRootProject ? this.envMode : void 0,
         /**
          * All tasks
@@ -33154,7 +33170,7 @@ export default preview;
 }
 
 // src/projects/astro-project.ts
-var import_projen21 = require("projen");
+var import_projen23 = require("projen");
 var import_ts_deepmerge3 = require("ts-deepmerge");
 
 // src/projects/monorepo-layout.ts
@@ -33302,7 +33318,7 @@ function resolveReactViteSiteProjectOutdir(packageName) {
 }
 
 // src/projects/typescript-project.ts
-var import_projen20 = require("projen");
+var import_projen22 = require("projen");
 var import_javascript4 = require("projen/lib/javascript");
 var import_release = require("projen/lib/release");
 var import_ts_deepmerge2 = require("ts-deepmerge");
@@ -34291,12 +34307,98 @@ var MonorepoProject = class extends import_typescript3.TypeScriptAppProject {
   }
 };
 
+// src/typescript/tsdoc-config.ts
+var import_projen20 = require("projen");
+var STANDARD_MODIFIER_TAGS = [
+  "@default",
+  "@defaultValue",
+  "@experimental",
+  "@internal"
+];
+var ALWAYS_ON_SCOPES = ["@codedrifters"];
+var TsdocConfig = class _TsdocConfig extends import_projen20.Component {
+  /**
+   * Derive a workspace scope from a scoped package name (`@scope/name`).
+   * Returns `undefined` when the name is unscoped.
+   *
+   * @internal
+   */
+  static scopeFromPackageName(packageName) {
+    if (!packageName || !packageName.startsWith("@")) {
+      return void 0;
+    }
+    const slash = packageName.indexOf("/");
+    if (slash <= 1) {
+      return void 0;
+    }
+    return packageName.slice(0, slash);
+  }
+  constructor(project, options = {}) {
+    super(project);
+    const scopeFromName = _TsdocConfig.scopeFromPackageName(
+      project.package.packageName
+    );
+    const scopeSet = /* @__PURE__ */ new Set([
+      ...ALWAYS_ON_SCOPES,
+      ...scopeFromName ? [scopeFromName] : [],
+      ...options.workspaceScopes ?? []
+    ]);
+    const tagSet = /* @__PURE__ */ new Set([
+      ...STANDARD_MODIFIER_TAGS,
+      ...Array.from(scopeSet),
+      ...options.additionalModifierTags ?? []
+    ]);
+    const tagDefinitions = Array.from(tagSet).sort((a, b) => a.localeCompare(b)).map((tagName) => ({
+      tagName,
+      syntaxKind: "modifier",
+      allowMultiple: true
+    }));
+    new import_projen20.JsonFile(project, "tsdoc.json", {
+      obj: {
+        $schema: "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+        tagDefinitions
+      }
+    });
+    project.addPackageIgnore("tsdoc.json");
+  }
+};
+
+// src/typescript/typescript-config.ts
+var import_node_path2 = require("path");
+var import_projen21 = require("projen");
+var import_path2 = require("projen/lib/util/path");
+var TypeScriptConfig = class extends import_projen21.Component {
+  constructor(project) {
+    super(project);
+    let tsPaths = {};
+    const workspaceDeps = project.deps.all.filter(
+      (d) => d.version === "workspace:*"
+    );
+    workspaceDeps.forEach((dep) => {
+      const subproject = project.root.subprojects.find((p) => p.package.packageName === dep.name);
+      if (!subproject) {
+        throw new Error(`Could not find subproject ${dep.name} in monorepo.`);
+      }
+      tsPaths = {
+        ...tsPaths,
+        [dep.name]: [
+          (0, import_path2.ensureRelativePathStartsWithDot)(
+            (0, import_node_path2.relative)(project.outdir, subproject.outdir)
+          )
+        ]
+      };
+    });
+    project.tsconfig?.file.addOverride("compilerOptions.paths", tsPaths);
+    project.tsconfigDev?.file.addOverride("compilerOptions.paths", tsPaths);
+  }
+};
+
 // src/projects/typescript-project.ts
 var TestRunner = {
   JEST: "jest",
   VITEST: "vitest"
 };
-var TypeScriptProject = class extends import_projen20.typescript.TypeScriptProject {
+var TypeScriptProject = class extends import_projen22.typescript.TypeScriptProject {
   constructor(userOptions) {
     if (!(userOptions.parent instanceof MonorepoProject)) {
       throw new Error(
@@ -34426,34 +34528,46 @@ var TypeScriptProject = class extends import_projen20.typescript.TypeScriptProje
     this.eslint?.addRules({
       "tsdoc/syntax": "warn"
     });
-    this.eslint?.addOverride({
-      files: ["src/**/*.ts"],
-      excludedFiles: ["**/*.test.*", "**/*.spec.*", "**/*.generated.ts"],
-      rules: {
-        "jsdoc/require-jsdoc": [
-          "warn",
-          {
-            publicOnly: true,
-            require: {
-              FunctionDeclaration: true,
-              ClassDeclaration: true
-            },
-            contexts: [
-              "ExportNamedDeclaration > FunctionDeclaration",
-              "ExportNamedDeclaration > ClassDeclaration",
-              "ExportNamedDeclaration > VariableDeclaration",
-              "ExportNamedDeclaration > TSInterfaceDeclaration",
-              "ExportNamedDeclaration > TSTypeAliasDeclaration",
-              "ExportNamedDeclaration > TSEnumDeclaration"
-            ],
-            checkConstructors: false,
-            checkGetters: false,
-            checkSetters: false,
-            enableFixer: false
-          }
-        ]
-      }
-    });
+    const requireJsdoc = options.requireJsdoc ?? "off";
+    if (requireJsdoc !== "off") {
+      const publicOnly = requireJsdoc === "public";
+      this.eslint?.addOverride({
+        files: ["src/**/*.ts"],
+        excludedFiles: ["**/*.test.*", "**/*.spec.*", "**/*.generated.ts"],
+        rules: {
+          "jsdoc/require-jsdoc": [
+            "warn",
+            {
+              publicOnly,
+              require: {
+                FunctionDeclaration: true,
+                ClassDeclaration: true
+              },
+              ...publicOnly ? {
+                contexts: [
+                  "ExportNamedDeclaration > FunctionDeclaration",
+                  "ExportNamedDeclaration > ClassDeclaration",
+                  "ExportNamedDeclaration > VariableDeclaration",
+                  "ExportNamedDeclaration > TSInterfaceDeclaration",
+                  "ExportNamedDeclaration > TSTypeAliasDeclaration",
+                  "ExportNamedDeclaration > TSEnumDeclaration"
+                ]
+              } : {},
+              checkConstructors: false,
+              checkGetters: false,
+              checkSetters: false,
+              enableFixer: false
+            }
+          ]
+        }
+      });
+    }
+    if (options.tsdocConfig !== false) {
+      new TsdocConfig(
+        this,
+        typeof options.tsdocConfig === "object" ? options.tsdocConfig : {}
+      );
+    }
     if (options.apiExtractor !== false) {
       new ApiExtractor(
         this,
@@ -34606,10 +34720,10 @@ var AstroProject = class extends TypeScriptProject {
       adapter: options.adapter
     });
     if (options.sampleCode === true) {
-      new import_projen21.SampleFile(this, "src/pages/index.astro", {
+      new import_projen23.SampleFile(this, "src/pages/index.astro", {
         contents: DEFAULT_INDEX_ASTRO
       });
-      new import_projen21.SampleFile(this, "public/favicon.svg", {
+      new import_projen23.SampleFile(this, "public/favicon.svg", {
         contents: DEFAULT_FAVICON_SVG
       });
     }
@@ -34634,19 +34748,19 @@ var DEFAULT_FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0
 `;
 
 // src/projects/aws-cdk-project.ts
-var import_projen24 = require("projen");
+var import_projen26 = require("projen");
 var import_javascript5 = require("projen/lib/javascript");
 var import_release2 = require("projen/lib/release");
 var import_ts_deepmerge4 = require("ts-deepmerge");
 
 // src/workflows/aws-deploy-workflow.ts
 var import_utils11 = __toESM(require_lib());
-var import_projen22 = require("projen");
+var import_projen24 = require("projen");
 var import_build = require("projen/lib/build");
 var import_github5 = require("projen/lib/github");
 var import_workflows_model5 = require("projen/lib/github/workflows-model");
 var PROD_DEPLOY_NAME = "prod-deploy";
-var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen22.Component {
+var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen24.Component {
   constructor(project, options = {}) {
     super(project);
     this.project = project;
@@ -34910,7 +35024,7 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen22.Compone
 };
 
 // src/workflows/aws-teardown-workflow.ts
-var import_projen23 = require("projen");
+var import_projen25 = require("projen");
 var import_github6 = require("projen/lib/github");
 var import_workflows_model6 = require("projen/lib/github/workflows-model");
 var DEFAULT_TEARDOWN_BRANCH_PATTERNS = [
@@ -34932,7 +35046,7 @@ var resolveBranchPatterns = (explicit, targets) => {
   }
   return [...DEFAULT_TEARDOWN_BRANCH_PATTERNS];
 };
-var AwsTeardownWorkflow = class extends import_projen23.Component {
+var AwsTeardownWorkflow = class extends import_projen25.Component {
   constructor(rootProject, options) {
     super(rootProject);
     this.rootProject = rootProject;
@@ -35114,7 +35228,7 @@ var AwsTeardownWorkflow = class extends import_projen23.Component {
 };
 
 // src/projects/aws-cdk-project.ts
-var AwsCdkProject = class extends import_projen24.awscdk.AwsCdkTypeScriptApp {
+var AwsCdkProject = class extends import_projen26.awscdk.AwsCdkTypeScriptApp {
   constructor(userOptions) {
     if (!(userOptions.parent instanceof MonorepoProject)) {
       throw new Error(
@@ -35311,7 +35425,7 @@ var AwsCdkProject = class extends import_projen24.awscdk.AwsCdkTypeScriptApp {
 };
 
 // src/projects/react-vite-site-project.ts
-var import_projen25 = require("projen");
+var import_projen27 = require("projen");
 var import_ts_deepmerge5 = require("ts-deepmerge");
 var ReactViteSiteProject = class extends TypeScriptProject {
   constructor(userOptions) {
@@ -35350,7 +35464,7 @@ var ReactViteSiteProject = class extends TypeScriptProject {
     };
     super(options);
     this.package.addField("type", "module");
-    new import_projen25.TextFile(this, ".nvmrc", { lines: ["v24.11.0"] });
+    new import_projen27.TextFile(this, ".nvmrc", { lines: ["v24.11.0"] });
     this.tsconfig?.file.addOverride("compilerOptions.target", "ES2020");
     this.tsconfig?.file.addOverride("compilerOptions.lib", [
       "ES2020",
@@ -35400,7 +35514,7 @@ var ReactViteSiteProject = class extends TypeScriptProject {
       "build",
       ".turbo"
     ]);
-    new import_projen25.SampleFile(this, "vite.config.ts", {
+    new import_projen27.SampleFile(this, "vite.config.ts", {
       contents: `import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import tailwindcss from '@tailwindcss/vite';
@@ -35412,7 +35526,7 @@ export default defineConfig({
 });
 `
     });
-    new import_projen25.SampleFile(this, "src/vite-env.d.ts", {
+    new import_projen27.SampleFile(this, "src/vite-env.d.ts", {
       contents: `/// <reference types="vite/client" />
 
 interface ImportMetaEnv {
@@ -35427,7 +35541,7 @@ interface ImportMeta {
     });
     if (options.testRunner !== TestRunner.JEST) {
       this.tryRemoveFile("vitest.config.ts");
-      new import_projen25.SampleFile(this, "vitest.config.ts", {
+      new import_projen27.SampleFile(this, "vitest.config.ts", {
         contents: `import { defineConfig, mergeConfig } from 'vitest/config';
 import react from '@vitejs/plugin-react';
 import viteConfig from './vite.config';
@@ -35571,7 +35685,7 @@ export default mergeConfig(
     }
     if (userOptions.sampleCode === true) {
       const siteName = options.name;
-      new import_projen25.SampleFile(this, "index.html", {
+      new import_projen27.SampleFile(this, "index.html", {
         contents: `<!doctype html>
 <html>
   <head>
@@ -35586,7 +35700,7 @@ export default mergeConfig(
 </html>
 `
       });
-      new import_projen25.SampleFile(this, "src/routes.tsx", {
+      new import_projen27.SampleFile(this, "src/routes.tsx", {
         contents: `import { createBrowserRouter } from 'react-router-dom';
 import App from './App';
 
@@ -35595,7 +35709,7 @@ export const router = createBrowserRouter([
 ]);
 `
       });
-      new import_projen25.SampleFile(this, "src/main.tsx", {
+      new import_projen27.SampleFile(this, "src/main.tsx", {
         contents: `import React from 'react';
 import ReactDOM from 'react-dom/client';
 import { RouterProvider } from 'react-router-dom';
@@ -35609,7 +35723,7 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
 );
 `
       });
-      new import_projen25.SampleFile(this, "src/App.tsx", {
+      new import_projen27.SampleFile(this, "src/App.tsx", {
         contents: `export default function App() {
   return (
     <main className="p-4">
@@ -35619,11 +35733,11 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
 }
 `
       });
-      new import_projen25.SampleFile(this, "src/index.css", {
+      new import_projen27.SampleFile(this, "src/index.css", {
         contents: `@import "tailwindcss";
 `
       });
-      new import_projen25.SampleFile(this, "src/setupTests.ts", {
+      new import_projen27.SampleFile(this, "src/setupTests.ts", {
         contents: `import '@testing-library/jest-dom';
 `
       });
@@ -35632,7 +35746,7 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
 };
 
 // src/projects/starlight-project.ts
-var import_projen26 = require("projen");
+var import_projen28 = require("projen");
 var STARLIGHT_ROLE = {
   DOCS: "docs",
   SITE: "site"
@@ -35674,10 +35788,10 @@ var StarlightProject = class extends AstroProject {
       turbo.compileTask.inputs.push("src/content/**");
     }
     if (userOptions.sampleContent === true) {
-      new import_projen26.SampleFile(this, "src/content/docs/index.mdx", {
+      new import_projen28.SampleFile(this, "src/content/docs/index.mdx", {
         contents: DEFAULT_INDEX_MDX
       });
-      new import_projen26.SampleFile(this, "src/content.config.ts", {
+      new import_projen28.SampleFile(this, "src/content.config.ts", {
         contents: DEFAULT_CONTENT_CONFIG_TS
       });
     }
@@ -35749,36 +35863,6 @@ export const collections = {
   docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
 };
 `;
-
-// src/typescript/typescript-config.ts
-var import_node_path2 = require("path");
-var import_projen27 = require("projen");
-var import_path2 = require("projen/lib/util/path");
-var TypeScriptConfig = class extends import_projen27.Component {
-  constructor(project) {
-    super(project);
-    let tsPaths = {};
-    const workspaceDeps = project.deps.all.filter(
-      (d) => d.version === "workspace:*"
-    );
-    workspaceDeps.forEach((dep) => {
-      const subproject = project.root.subprojects.find((p) => p.package.packageName === dep.name);
-      if (!subproject) {
-        throw new Error(`Could not find subproject ${dep.name} in monorepo.`);
-      }
-      tsPaths = {
-        ...tsPaths,
-        [dep.name]: [
-          (0, import_path2.ensureRelativePathStartsWithDot)(
-            (0, import_node_path2.relative)(project.outdir, subproject.outdir)
-          )
-        ]
-      };
-    });
-    project.tsconfig?.file.addOverride("compilerOptions.paths", tsPaths);
-    project.tsconfigDev?.file.addOverride("compilerOptions.paths", tsPaths);
-  }
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AGENT_MODEL,
@@ -35892,6 +35976,7 @@ var TypeScriptConfig = class extends import_projen27.Component {
   TIER_AWARE_BUNDLE_NAMES,
   TestRunner,
   TsDocCoverageKind,
+  TsdocConfig,
   TurboRepo,
   TurboRepoTask,
   TypeScriptConfig,