@codedrifters/configulator 0.0.238 → 0.0.240

package/lib/index.mjs

@@ -767,6 +767,91 @@ var baseBundle = {
       ].join("\n"),
       tags: ["workflow"]
     },
+    {
+      name: "monorepo-layout",
+      description: "Canonical monorepo top-level folders (docs, apps, packages, sites), the @ownerscope/<name> scoping rule, the docs-singleton carve-out, and the scaffolding skills that place new sub-projects",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: [
+        "# Monorepo Layout",
+        "",
+        "Every monorepo built with `@codedrifters/configulator` uses a single,",
+        "fixed top-level folder layout. Agents, scaffolding skills, pnpm-workspace",
+        "globs, Turbo filters, and CI cache keys all assume these roots.",
+        "",
+        "## Four Canonical Top-Level Folders",
+        "",
+        "| Folder | Purpose | Examples |",
+        "|--------|---------|----------|",
+        "| `/docs` | **Single** Starlight site covering the entire monorepo. The one site that lives outside `/sites`. | Monorepo-wide developer docs, ADRs, how-to guides. |",
+        "| `/apps/@scope/<name>` | Deployable applications \u2014 anything that runs or ships as a running process. | AWS CDK stacks, mobile apps (iOS/Android), backend services. |",
+        "| `/packages/@scope/<name>` | Shared libraries \u2014 published npm packages and workspace-internal libraries. | `@codedrifters/configulator`, `@codedrifters/constructs`, `@codedrifters/utils`. |",
+        "| `/sites/@scope/<name>` | User-facing web front ends that are **not** the monorepo-wide docs site. | Marketing sites, SPAs, per-client static sites. |",
+        "",
+        "No other top-level folder is part of this contract. Generated roots",
+        "(`.projen/`, `.github/`, `node_modules/`, `.turbo/`, etc.) are orthogonal",
+        "and unchanged.",
+        "",
+        "## Scoping Rule",
+        "",
+        "Every sub-project under `apps/`, `packages/`, or `sites/` is named",
+        "`@ownerscope/<name>`, where **scope is the owning party** (not a category).",
+        "",
+        "- `@codedrifters/configulator` \u2014 a shared library owned by CodeDrifters \u2192 `packages/@codedrifters/configulator`",
+        "- `@codedrifters/infrastructure-stack` \u2014 an AWS CDK app owned by CodeDrifters \u2192 `apps/@codedrifters/infrastructure-stack`",
+        "- `@clientA/iphone-app` \u2014 a mobile app owned by Client A \u2192 `apps/@clientA/iphone-app`",
+        "- `@clientB/marketing-site` \u2014 a marketing site owned by Client B \u2192 `sites/@clientB/marketing-site`",
+        "",
+        "The scope identifies **who owns the sub-project**, not what kind of",
+        "sub-project it is. Kind is captured by the top-level folder (`apps/`,",
+        "`packages/`, `sites/`). Never scope by category (e.g. `@apps/foo`,",
+        "`@libs/bar`) \u2014 the top-level folder already carries that information.",
+        "",
+        "## Docs-Singleton Carve-Out",
+        "",
+        "There is **exactly one** Starlight docs site per monorepo, and it lives",
+        "at `/docs`. It is **not** `sites/@scope/docs`.",
+        "",
+        "- 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`.",
+        "- `/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.",
+        "",
+        "## Project-Type \u2192 `outdir` Mapping",
+        "",
+        "Configulator project types default their `outdir` according to the",
+        "following table. Override `outdir` explicitly only when you have a",
+        "genuine reason \u2014 the defaults cover the common path.",
+        "",
+        "| Configulator project type | Default `outdir` |",
+        "|---------------------------|------------------|",
+        "| `TypeScriptProject` | `packages/<scope>/<name>` |",
+        "| `AwsCdkProject` | `apps/<scope>/<name>` |",
+        "| `AstroProject` | `sites/<scope>/<name>` |",
+        "| `StarlightProject` (role = docs) | `docs/` |",
+        "",
+        "`<scope>` is parsed from the sub-project's package name (everything",
+        "after `@` and before `/`). `<name>` is the unscoped part of the",
+        "package name.",
+        "",
+        "## Placing New Sub-Projects",
+        "",
+        "Never hand-roll a sub-project path. Use one of the scaffolding skills,",
+        "which take `@scope/<name>` as input, validate it, and place the new",
+        "project in the correct folder:",
+        "",
+        "- `/create-package` \u2014 scaffolds a new `TypeScriptProject` under `packages/<scope>/<name>`",
+        "- `/create-app` \u2014 scaffolds a new `AwsCdkProject` under `apps/<scope>/<name>`",
+        "- `/create-site` \u2014 scaffolds a new `AstroProject` under `sites/<scope>/<name>`",
+        "",
+        "The monorepo-wide docs site at `/docs` is a singleton and is created",
+        "once per repo via `StarlightProject` \u2014 it is not scaffolded per",
+        "sub-project."
+      ].join("\n"),
+      tags: ["project"]
+    },
     {
       name: "issue-conventions",
       description: "Issue title prefixes, GitHub issue type mapping, prerequisite issues",
@@ -15487,6 +15572,77 @@ import {
 } from "projen/lib/typescript";
 import { merge } from "ts-deepmerge";
 
+// src/projects/monorepo-layout.ts
+var MONOREPO_LAYOUT = {
+  DOCS: "docs",
+  APPS: "apps",
+  PACKAGES: "packages",
+  SITES: "sites"
+};
+var LAYOUT_ENFORCEMENT = {
+  OFF: "off",
+  WARN: "warn",
+  ERROR: "error"
+};
+var LAYOUT_ROOT_BY_PROJECT_TYPE = {
+  TypeScriptProject: MONOREPO_LAYOUT.PACKAGES,
+  AwsCdkProject: MONOREPO_LAYOUT.APPS,
+  AstroProject: MONOREPO_LAYOUT.SITES,
+  StarlightProject: MONOREPO_LAYOUT.DOCS
+};
+function validateMonorepoLayout(root) {
+  const violations = [];
+  const rootOutdir = toPosix(root.outdir);
+  for (const sub of root.subprojects) {
+    const className = sub.constructor.name;
+    const expectedRoot = LAYOUT_ROOT_BY_PROJECT_TYPE[className];
+    if (expectedRoot === void 0) {
+      continue;
+    }
+    const relOutdir = relativeOutdir(rootOutdir, toPosix(sub.outdir));
+    if (!outdirMatchesRoot(relOutdir, expectedRoot)) {
+      violations.push({
+        projectName: sub.name,
+        projectType: className,
+        outdir: relOutdir,
+        expectedRoot
+      });
+    }
+  }
+  return violations;
+}
+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 outdirMatchesRoot(relOutdir, expectedRoot) {
+  const segments = relOutdir.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0) {
+    return false;
+  }
+  if (segments[0] !== expectedRoot) {
+    return false;
+  }
+  if (expectedRoot === MONOREPO_LAYOUT.DOCS) {
+    return true;
+  }
+  return segments.length >= 2;
+}
+function toPosix(p) {
+  return p.replace(/\\/g, "/");
+}
+function relativeOutdir(rootOutdir, subOutdir) {
+  if (subOutdir === rootOutdir) {
+    return "";
+  }
+  const prefix2 = rootOutdir.endsWith("/") ? rootOutdir : `${rootOutdir}/`;
+  if (subOutdir.startsWith(prefix2)) {
+    return subOutdir.slice(prefix2.length);
+  }
+  return subOutdir;
+}
+
 // src/tasks/reset-task.ts
 import { Component as Component13 } from "projen";
 var ResetTask = class _ResetTask extends Component13 {
@@ -15995,6 +16151,11 @@ var MonorepoProject = class extends TypeScriptAppProject {
        * By default treat as a registry consumer (upgrade workflow syncs configulator).
        */
       configulatorRegistryConsumer: true,
+      /**
+       * ADR-006 layout enforcement defaults to "warn" during rollout so
+       * legacy outdirs log actionable warnings but do not break synth.
+       */
+      layoutEnforcement: LAYOUT_ENFORCEMENT.WARN,
       /**
        * We don't want sample code generated for the root project.
        */
@@ -16108,6 +16269,7 @@ var MonorepoProject = class extends TypeScriptAppProject {
     this.tsconfig?.removeInclude(`${this.srcdir}/**/*.ts`);
     this.pnpmVersion = options.pnpmVersion;
     this.configulatorRegistryConsumer = options.configulatorRegistryConsumer ?? true;
+    this.layoutEnforcement = options.layoutEnforcement ?? LAYOUT_ENFORCEMENT.WARN;
     new VSCodeConfig(this);
     new PnpmWorkspace(this, options.pnpmOptions?.pnpmWorkspaceOptions);
     if (options.turbo) {
@@ -16202,6 +16364,32 @@ var MonorepoProject = class extends TypeScriptAppProject {
       );
     }
   }
+  /**
+   * Validate sub-project `outdir` values against the ADR-006 monorepo
+   * layout contract. Runs in `preSynthesize` so all sub-projects are
+   * attached by the time we inspect the tree.
+   *
+   * Behavior is controlled by `layoutEnforcement`:
+   * - `"off"`  — skip validation.
+   * - `"warn"` — log a `console.warn` per violation; continue.
+   * - `"error"` — throw on the first violation.
+   */
+  preSynthesize() {
+    super.preSynthesize();
+    if (this.layoutEnforcement === LAYOUT_ENFORCEMENT.OFF) {
+      return;
+    }
+    const violations = validateMonorepoLayout(this);
+    if (violations.length === 0) {
+      return;
+    }
+    if (this.layoutEnforcement === LAYOUT_ENFORCEMENT.ERROR) {
+      throw new Error(formatLayoutViolation(violations[0]));
+    }
+    for (const violation of violations) {
+      console.warn(formatLayoutViolation(violation));
+    }
+  }
   /**
    * Allows a sub project to request installation of dependency at the Monorepo root
    * They must provide a function that is executed after dependencies have been installed
@@ -17322,10 +17510,13 @@ export {
   DEFAULT_TEARDOWN_BRANCH_PATTERNS,
   DEFAULT_TYPE_LABELS,
   JsiiFaker,
+  LAYOUT_ENFORCEMENT,
+  LAYOUT_ROOT_BY_PROJECT_TYPE,
   MCP_TRANSPORT,
   MERGE_METHODS,
   MIMIMUM_RELEASE_AGE,
   MINIMUM_RELEASE_AGE,
+  MONOREPO_LAYOUT,
   MonorepoProject,
   PROD_DEPLOY_NAME,
   PnpmWorkspace,
@@ -17352,6 +17543,7 @@ export {
   baseBundle,
   bcmWriterBundle,
   companyProfileBundle,
+  formatLayoutViolation,
   getLatestEligibleVersion,
   githubWorkflowBundle,
   industryDiscoveryBundle,
@@ -17373,6 +17565,7 @@ export {
   softwareProfileBundle,
   turborepoBundle,
   typescriptBundle,
+  validateMonorepoLayout,
   vitestBundle
 };
 //# sourceMappingURL=index.mjs.map