@codedrifters/configulator 0.0.243 → 0.0.245

package/lib/index.js

@@ -210,6 +210,7 @@ __export(index_exports, {
   ROOT_CI_TASK_NAME: () => ROOT_CI_TASK_NAME,
   ROOT_TURBO_TASK_NAME: () => ROOT_TURBO_TASK_NAME,
   ResetTask: () => ResetTask,
+  STARLIGHT_ROLE: () => STARLIGHT_ROLE,
   StarlightProject: () => StarlightProject,
   TestRunner: () => TestRunner,
   TurboRepo: () => TurboRepo,
@@ -229,6 +230,7 @@ __export(index_exports, {
   bcmWriterBundle: () => bcmWriterBundle,
   companyProfileBundle: () => companyProfileBundle,
   formatLayoutViolation: () => formatLayoutViolation,
+  formatStarlightSingletonViolation: () => formatStarlightSingletonViolation,
   getLatestEligibleVersion: () => getLatestEligibleVersion,
   githubWorkflowBundle: () => githubWorkflowBundle,
   industryDiscoveryBundle: () => industryDiscoveryBundle,
@@ -255,6 +257,7 @@ __export(index_exports, {
   turborepoBundle: () => turborepoBundle,
   typescriptBundle: () => typescriptBundle,
   validateMonorepoLayout: () => validateMonorepoLayout,
+  validateStarlightSingleton: () => validateStarlightSingleton,
   vitestBundle: () => vitestBundle
 });
 module.exports = __toCommonJS(index_exports);
@@ -901,7 +904,12 @@ var baseBundle = {
         "- The docs site is monorepo-wide. Sub-project documentation belongs",
         "  inside that single site (under `docs/content/`), not in a per-package",
         "  `docs/` folder.",
-        "- Configulator's `StarlightProject` defaults its `outdir` to `/docs`.",
+        "- Configulator's `StarlightProject` defaults its `outdir` to `/docs` and",
+        '  its `role` to `"docs"`. A second `StarlightProject` with `role: "docs"`',
+        "  fails synth \u2014 the singleton rule is enforced at validate time.",
+        "- Additional Starlight sites (client-facing, marketing, etc.) must set",
+        '  `role: "site"`, which routes them under `sites/<scope>/<name>` just',
+        "  like a plain `AstroProject`.",
         "- `/sites` is reserved for end-user-facing web front ends (marketing",
         "  sites, SPAs, client-facing apps). It deliberately does not host the",
         "  dev-docs site.",
@@ -917,7 +925,8 @@ var baseBundle = {
         "| `TypeScriptProject` | `packages/<scope>/<name>` |",
         "| `AwsCdkProject` | `apps/<scope>/<name>` |",
         "| `AstroProject` | `sites/<scope>/<name>` |",
-        "| `StarlightProject` (role = docs) | `docs/` |",
+        "| `StarlightProject` (role = docs, default) | `docs/` |",
+        "| `StarlightProject` (role = site) | `sites/<scope>/<name>` |",
         "",
         "`<scope>` is parsed from the sub-project's package name (everything",
         "after `@` and before `/`). `<name>` is the unscoped part of the",
@@ -988,6 +997,28 @@ var baseBundle = {
 
 // src/agent/bundles/project-context.ts
 var PROJECT_CONTEXT_PATH = "docs/project-context.md";
+var SUBPROJECT_ROLE_GUIDANCE = [
+  "### Sub-project roles",
+  "",
+  "When the repository follows the configulator monorepo layout,",
+  "every sub-project's role is derivable from the first segment of",
+  "its `outdir` path. No other lookup is required.",
+  "",
+  "- `apps/<scope>/<name>` \u2014 deployable application (CDK stack,",
+  "  mobile app, backend service).",
+  "- `packages/<scope>/<name>` \u2014 shared library (published npm",
+  "  package or workspace-internal library).",
+  "- `sites/<scope>/<name>` \u2014 user-facing web front end that is",
+  "  not the monorepo-wide docs site.",
+  "- `docs/` \u2014 the single Starlight documentation site for the",
+  "  whole monorepo (exactly one per repo; lives at `/docs`, not",
+  "  under `sites/`).",
+  "",
+  "Repositories that have not adopted the layout contract may use a",
+  "different folder structure \u2014 in that case fall back to whatever",
+  `\`${PROJECT_CONTEXT_PATH}\` documents explicitly.`,
+  ""
+];
 var PROJECT_CONTEXT_READER_SECTION = [
   "## Project Context",
   "",
@@ -1002,6 +1033,7 @@ var PROJECT_CONTEXT_READER_SECTION = [
   "",
   "You are a **read-only consumer** of this file. Do not edit it.",
   "",
+  ...SUBPROJECT_ROLE_GUIDANCE,
   "---",
   ""
 ];
@@ -1014,6 +1046,7 @@ var PROJECT_CONTEXT_MAINTAINER_SECTION = [
   "key stakeholders. Use it to judge relevance when scanning source",
   "material in this session.",
   "",
+  ...SUBPROJECT_ROLE_GUIDANCE,
   "### Seed on first use",
   "",
   `If \`${PROJECT_CONTEXT_PATH}\` does not exist, create it from this`,
@@ -1043,7 +1076,7 @@ var PROJECT_CONTEXT_MAINTAINER_SECTION = [
   "",
   "## Key Stakeholders",
   "TODO: named people or teams and what they care about.",
-  "",
+  "{{monorepoLayoutSeedBlock}}",
   "## References",
   "TODO: links to BCM docs, competitive analysis, product roadmap, and",
   "other authoritative sources.",
@@ -1068,6 +1101,26 @@ var PROJECT_CONTEXT_MAINTAINER_SECTION = [
   "---",
   ""
 ];
+var MONOREPO_LAYOUT_SEED_BLOCK = [
+  "",
+  "## Sub-Projects",
+  "",
+  "TODO: one bullet per sub-project, grouped by role. The role is",
+  "derivable from the first segment of each sub-project's `outdir`.",
+  "",
+  "### Applications (`apps/`)",
+  "TODO: deployable applications (CDK stacks, mobile apps, services).",
+  "",
+  "### Packages (`packages/`)",
+  "TODO: shared libraries (published npm packages, workspace-internal libraries).",
+  "",
+  "### Sites (`sites/`)",
+  "TODO: user-facing web front ends (marketing sites, SPAs, client apps).",
+  "",
+  "### Docs (`docs/`)",
+  "TODO: the single monorepo-wide Starlight documentation site.",
+  ""
+].join("\n");
 
 // src/agent/bundles/bcm-writer.ts
 var bcmWriterSubAgent = {
@@ -12594,9 +12647,30 @@ var ProjectMetadata = class _ProjectMetadata extends import_projen2.Component {
       labels: options.labels,
       milestones: options.milestones,
       docsPath: options.docsPath,
-      deployment: options.deployment
+      deployment: options.deployment,
+      monorepoLayoutSeedBlock: this.resolveMonorepoLayoutSeedBlock()
     };
   }
+  /**
+   * Return the maintainer-seed addendum for the `project-context`
+   * bundle, or an empty string when the root project either has no
+   * layout-enforcement opinion or has opted out (`layoutEnforcement:
+   * "off"`).
+   *
+   * Uses duck-typing on the root project's `layoutEnforcement`
+   * property to avoid a circular import with `MonorepoProject`. The
+   * concrete `MonorepoProject` class exposes this property as a
+   * string; anything else resolves to the empty string so repos that
+   * predate the monorepo layout contract see no change.
+   */
+  resolveMonorepoLayoutSeedBlock() {
+    const root = this.project.root;
+    const enforcement = root.layoutEnforcement;
+    if (typeof enforcement !== "string" || enforcement === "off") {
+      return "";
+    }
+    return MONOREPO_LAYOUT_SEED_BLOCK;
+  }
   /**
    * Attempts to auto-detect repository owner and name from the Projen
    * project's package.json repository field.
@@ -14616,7 +14690,12 @@ var FALLBACKS = {
   "githubProject.name": "<project-name>",
   "githubProject.number": "<project-number>",
   "githubProject.nodeId": "<project-node-id>",
-  docsPath: "<docs-path>"
+  docsPath: "<docs-path>",
+  // The monorepo-layout seed block is additive: when absent, the
+  // seeded `project-context.md` template reads cleanly without it.
+  // Fall back to an empty string so no placeholder text leaks into
+  // rendered prompts for repos that predate the layout contract.
+  monorepoLayoutSeedBlock: ""
 };
 var TEMPLATE_RE = /\{\{(\w+(?:\.\w+)*)\}\}/g;
 function getNestedValue(obj, path2) {
@@ -15661,7 +15740,7 @@ function validateMonorepoLayout(root) {
   const rootOutdir = toPosix(root.outdir);
   for (const sub of root.subprojects) {
     const className = sub.constructor.name;
-    const expectedRoot = LAYOUT_ROOT_BY_PROJECT_TYPE[className];
+    const expectedRoot = expectedRootFor(sub, className);
     if (expectedRoot === void 0) {
       continue;
     }
@@ -15677,11 +15756,40 @@ function validateMonorepoLayout(root) {
   }
   return violations;
 }
+function validateStarlightSingleton(root) {
+  const docsRoleProjects = [];
+  for (const sub of root.subprojects) {
+    if (sub.constructor.name !== "StarlightProject") {
+      continue;
+    }
+    if (getStarlightRole(sub) === "docs") {
+      docsRoleProjects.push(sub.name);
+    }
+  }
+  if (docsRoleProjects.length <= 1) {
+    return void 0;
+  }
+  return { projectNames: docsRoleProjects };
+}
+function expectedRootFor(sub, className) {
+  if (className === "StarlightProject") {
+    return getStarlightRole(sub) === "site" ? MONOREPO_LAYOUT.SITES : MONOREPO_LAYOUT.DOCS;
+  }
+  return LAYOUT_ROOT_BY_PROJECT_TYPE[className];
+}
+function getStarlightRole(sub) {
+  const role = sub.role;
+  return role === "site" ? "site" : "docs";
+}
 function formatLayoutViolation(violation) {
   const { projectName, projectType, outdir, expectedRoot } = violation;
   const expectedExample = expectedRoot === MONOREPO_LAYOUT.DOCS ? "docs/" : `${expectedRoot}/<scope>/<name>`;
   return `[monorepo-layout] ${projectType} "${projectName}" has outdir "${outdir}", which is outside the expected root "${expectedRoot}/" (expected e.g. "${expectedExample}"). See docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md.`;
 }
+function formatStarlightSingletonViolation(violation) {
+  const names = violation.projectNames.map((n) => `"${n}"`).join(", ");
+  return `[monorepo-layout] Multiple StarlightProject instances with role: "docs" found (${names}). ADR-006 allows exactly one docs-role Starlight project per MonorepoProject. Either remove the duplicates or set role: "site" on the additional ones so they land under sites/. See docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md.`;
+}
 function outdirMatchesRoot(relOutdir, expectedRoot) {
   const segments = relOutdir.split("/").filter((s) => s.length > 0);
   if (segments.length === 0) {
@@ -16487,10 +16595,20 @@ var MonorepoProject = class extends import_typescript3.TypeScriptAppProject {
    * layout contract. Runs in `preSynthesize` so all sub-projects are
    * attached by the time we inspect the tree.
    *
+   * Two checks run in sequence:
+   *
+   * 1. **Outdir-vs-root validation.** Every sub-project's `outdir` must
+   *    live under the root expected for its project type (ADR-006 §4).
+   * 2. **Docs-singleton validation.** At most one `StarlightProject`
+   *    may carry `role: "docs"` (ADR-006 §3).
+   *
    * Behavior is controlled by `layoutEnforcement`:
-   * - `"off"`  — skip validation.
-   * - `"warn"` — log a `console.warn` per violation; continue.
-   * - `"error"` — throw on the first violation.
+   * - `"off"`  — skip both checks.
+   * - `"warn"` — log a `console.warn` per violation; continue. Singleton
+   *   violations also warn in this mode rather than throwing, so all
+   *   layout findings are surfaced consistently.
+   * - `"error"` — throw on the first outdir violation, or on the
+   *   singleton violation if outdir validation passed.
    */
   preSynthesize() {
     super.preSynthesize();
@@ -16498,15 +16616,22 @@ var MonorepoProject = class extends import_typescript3.TypeScriptAppProject {
       return;
     }
     const violations = validateMonorepoLayout(this);
-    if (violations.length === 0) {
-      return;
-    }
+    const singletonViolation = validateStarlightSingleton(this);
     if (this.layoutEnforcement === LAYOUT_ENFORCEMENT.ERROR) {
-      throw new Error(formatLayoutViolation(violations[0]));
+      if (violations.length > 0) {
+        throw new Error(formatLayoutViolation(violations[0]));
+      }
+      if (singletonViolation !== void 0) {
+        throw new Error(formatStarlightSingletonViolation(singletonViolation));
+      }
+      return;
     }
     for (const violation of violations) {
       console.warn(formatLayoutViolation(violation));
     }
+    if (singletonViolation !== void 0) {
+      console.warn(formatStarlightSingletonViolation(singletonViolation));
+    }
   }
   /**
    * Allows a sub project to request installation of dependency at the Monorepo root
@@ -17503,8 +17628,13 @@ var AwsCdkProject = class extends import_projen20.awscdk.AwsCdkTypeScriptApp {
 
 // src/projects/starlight-project.ts
 var import_projen21 = require("projen");
+var STARLIGHT_ROLE = {
+  DOCS: "docs",
+  SITE: "site"
+};
 var StarlightProject = class extends AstroProject {
   constructor(userOptions) {
+    const role = userOptions.role ?? STARLIGHT_ROLE.DOCS;
     const starlightConfig = buildStarlightConfig(userOptions);
     const starlightSpec = {
       name: "starlight",
@@ -17512,8 +17642,10 @@ var StarlightProject = class extends AstroProject {
       defaultImport: true,
       args: JSON.stringify(starlightConfig, null, 2)
     };
+    const resolvedOutdir = userOptions.outdir ?? (role === STARLIGHT_ROLE.DOCS ? MONOREPO_LAYOUT.DOCS : void 0);
     const mergedOptions = {
       ...userOptions,
+      outdir: resolvedOutdir,
       integrations: [starlightSpec, ...userOptions.integrations ?? []],
       depsUpgradeOptions: {
         ...userOptions.depsUpgradeOptions,
@@ -17525,6 +17657,7 @@ var StarlightProject = class extends AstroProject {
       }
     };
     super(mergedOptions);
+    this.role = role;
     const starlightVersion = userOptions.starlightVersion ?? VERSION.STARLIGHT_VERSION;
     const sharpVersion = userOptions.sharpVersion ?? VERSION.SHARP_VERSION;
     this.addDeps(
@@ -17652,6 +17785,7 @@ var TypeScriptConfig = class extends import_projen22.Component {
   ROOT_CI_TASK_NAME,
   ROOT_TURBO_TASK_NAME,
   ResetTask,
+  STARLIGHT_ROLE,
   StarlightProject,
   TestRunner,
   TurboRepo,
@@ -17671,6 +17805,7 @@ var TypeScriptConfig = class extends import_projen22.Component {
   bcmWriterBundle,
   companyProfileBundle,
   formatLayoutViolation,
+  formatStarlightSingletonViolation,
   getLatestEligibleVersion,
   githubWorkflowBundle,
   industryDiscoveryBundle,
@@ -17697,6 +17832,7 @@ var TypeScriptConfig = class extends import_projen22.Component {
   turborepoBundle,
   typescriptBundle,
   validateMonorepoLayout,
+  validateStarlightSingleton,
   vitestBundle
 });
 //# sourceMappingURL=index.js.map