@dbx-tools/projen 0.6.229 → 0.7.0

package/src/release-dispatch.ts

@@ -9,8 +9,9 @@ export const RELEASE_SUMMARY_PROVIDER_NAMES = ["cursor", "codex", "claude"] as c
 export type ReleaseSummaryProviderName = (typeof RELEASE_SUMMARY_PROVIDER_NAMES)[number];
 
 /** Immutable repository path for one version's release summary. */
-export function releaseSummaryFile(version: string): string {
-  return `${RELEASE_SUMMARY_DIRECTORY}/v${version.replace(/^v/, "")}.md`;
+export function releaseSummaryFile(version: string, component?: string): string {
+  const prefix = component ? `${component.replace(/[^a-zA-Z0-9-]+/g, "-")}-` : "";
+  return `${RELEASE_SUMMARY_DIRECTORY}/${prefix}v${version.replace(/^v/, "")}.md`;
 }
 
 export const RELEASE_SUMMARY_FILE = releaseSummaryFile(RELEASE_VERSION);

package/src/release-plan.ts

@@ -0,0 +1,236 @@
+/**
+ * Deterministic affected release plan derived from manifest and graph changes.
+ *
+ * @module
+ */
+
+import type {
+  ReleaseArtifact,
+  ReleaseProjectNode,
+  ReleaseUnit,
+  ReleaseUnitGraph,
+} from "./release-catalog.ts";
+
+/** Why a unit entered one release. */
+export type ReleaseReason = "direct" | "propagated";
+
+/** One independently versioned unit selected for publication. */
+export interface PlannedReleaseUnit {
+  readonly id: string;
+  readonly component: string;
+  readonly oldVersion: string;
+  readonly newVersion: string;
+  readonly tag: string;
+  readonly reason: ReleaseReason;
+  readonly sourceHash: string;
+}
+
+/** One selected package publication. */
+export interface PlannedPackage {
+  readonly unit: string;
+  readonly identity: string;
+  readonly path: string;
+  readonly version: string;
+}
+
+/** One selected virtual artifact publication. */
+export interface PlannedArtifact extends ReleaseArtifact {
+  readonly version: string;
+}
+
+/** One selected native Rust matrix row and the packages built in that row. */
+export interface PlannedRustTarget {
+  readonly os: string;
+  readonly cpu: string;
+  readonly node: string;
+  readonly cargo: string;
+  readonly runner: string;
+  readonly python: string;
+  readonly libc: string;
+  readonly cargoExcludes: string;
+  readonly packages: readonly string[];
+}
+
+/** Complete plan persisted as a workflow artifact and used for recovery. */
+export interface ReleasePlan {
+  readonly schemaVersion: 1;
+  readonly units: readonly PlannedReleaseUnit[];
+  readonly publishBatches: readonly (readonly string[])[];
+  readonly nodePackages: readonly PlannedPackage[];
+  readonly pythonPackages: readonly PlannedPackage[];
+  readonly rustPackages: readonly PlannedPackage[];
+  readonly artifacts: readonly PlannedArtifact[];
+  readonly rustTargets: readonly PlannedRustTarget[];
+  readonly stages: {
+    readonly rust: boolean;
+    readonly python: boolean;
+    readonly node: boolean;
+    readonly github: boolean;
+    readonly docs: boolean;
+  };
+  readonly omittedStages: readonly string[];
+}
+
+/** Build the affected plan from the previous and reviewed release graphs. */
+export function buildReleasePlan(
+  current: ReleaseUnitGraph,
+  previous?: ReleaseUnitGraph,
+): ReleasePlan {
+  const previousUnits = new Map(previous?.units.map((unit) => [unit.id, unit]) ?? []);
+  const units = current.units.flatMap<PlannedReleaseUnit>((unit) => {
+    const old = previousUnits.get(unit.id);
+    if (!old || old.version === unit.version) return [];
+    return [
+      {
+        id: unit.id,
+        component: unit.component,
+        oldVersion: old.version,
+        newVersion: unit.version,
+        tag: `${unit.component}-v${unit.version}`,
+        reason: old.sourceHash === unit.sourceHash ? "propagated" : "direct",
+        sourceHash: unit.sourceHash,
+      },
+    ];
+  });
+  const selected = new Set(units.map((unit) => unit.id));
+  const versions = new Map(units.map((unit) => [unit.id, unit.newVersion]));
+  const packagePlan = (language: ReleaseProjectNode["language"]): PlannedPackage[] =>
+    current.projects
+      .filter(
+        (project) =>
+          project.publish &&
+          project.language === language &&
+          project.unit !== undefined &&
+          selected.has(project.unit),
+      )
+      .map((project) => ({
+        unit: project.unit!,
+        identity: project.identity,
+        path: project.path,
+        version: versions.get(project.unit!)!,
+      }))
+      .sort((a, b) => a.identity.localeCompare(b.identity));
+  const artifacts = current.artifacts
+    .filter((artifact) => artifact.publish && selected.has(artifact.unit))
+    .map((artifact) => ({
+      ...artifact,
+      version: versions.get(artifact.unit)!,
+    }));
+  const rustPackagesByUnit = new Map<string, string[]>();
+  for (const project of current.projects) {
+    if (
+      project.language === "rust" &&
+      project.publish &&
+      project.unit &&
+      selected.has(project.unit)
+    ) {
+      rustPackagesByUnit.set(project.unit, [
+        ...(rustPackagesByUnit.get(project.unit) ?? []),
+        project.identity,
+      ]);
+    }
+  }
+  const rustTargetsByKey = new Map<string, PlannedRustTarget>();
+  for (const artifact of artifacts) {
+    const targets = artifact.data?.targets;
+    if (!Array.isArray(targets)) continue;
+    for (const value of targets) {
+      if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+      const target = value as Record<string, unknown>;
+      const required = ["os", "cpu", "node", "cargo", "runner", "python"] as const;
+      if (!required.every((field) => typeof target[field] === "string")) continue;
+      const key = String(target.node);
+      const currentTarget = rustTargetsByKey.get(key);
+      rustTargetsByKey.set(key, {
+        os: String(target.os),
+        cpu: String(target.cpu),
+        node: String(target.node),
+        cargo: String(target.cargo),
+        runner: String(target.runner),
+        python: String(target.python),
+        libc: typeof target.libc === "string" ? target.libc : "",
+        cargoExcludes: typeof target.cargoExcludes === "string" ? target.cargoExcludes : "",
+        packages: [
+          ...new Set([
+            ...(currentTarget?.packages ?? []),
+            ...(rustPackagesByUnit.get(artifact.unit) ?? []),
+          ]),
+        ].sort(),
+      });
+    }
+  }
+  const rustTargets = [...rustTargetsByKey.values()].sort((a, b) => a.node.localeCompare(b.node));
+  const publishBatches = current.publishBatches
+    .map((batch) => batch.filter((unit) => selected.has(unit)))
+    .filter((batch) => batch.length > 0);
+  const nodePackages = packagePlan("javascript");
+  const pythonPackages = packagePlan("python");
+  const rustPackages = packagePlan("rust");
+  const stages = {
+    rust:
+      rustPackages.length > 0 ||
+      artifacts.some((artifact) => ["cargo", "github-binary"].includes(artifact.kind)),
+    python: pythonPackages.length > 0 || artifacts.some((artifact) => artifact.kind === "pypi"),
+    node: nodePackages.length > 0 || artifacts.some((artifact) => artifact.kind === "npm"),
+    github: artifacts.some((artifact) => artifact.kind === "github-binary"),
+    docs: units.length > 0 || artifacts.some((artifact) => artifact.kind === "documentation"),
+  };
+  const omittedStages = Object.entries(stages)
+    .filter(([, enabled]) => !enabled)
+    .map(([name]) => name);
+  return {
+    schemaVersion: 1,
+    units,
+    publishBatches,
+    nodePackages,
+    pythonPackages,
+    rustPackages,
+    artifacts,
+    rustTargets,
+    stages,
+    omittedStages,
+  };
+}
+
+/** Reconstruct a one-component plan for an idempotent manual recovery. */
+export function buildRecoveryReleasePlan(
+  current: ReleaseUnitGraph,
+  component: string,
+  version: string,
+): ReleasePlan {
+  const unit = current.units.find(
+    (candidate) => candidate.component === component || candidate.id === component,
+  );
+  if (!unit) throw new Error(`Unknown recovery component ${component}`);
+  if (unit.version !== version) {
+    throw new Error(`Recovery version ${version} does not match ${unit.component}@${unit.version}`);
+  }
+  const previous: ReleaseUnitGraph = {
+    ...current,
+    units: current.units.map((candidate) =>
+      candidate.id === unit.id
+        ? { ...candidate, version: "0.0.0", sourceHash: candidate.sourceHash }
+        : candidate,
+    ),
+  };
+  return buildReleasePlan(current, previous);
+}
+
+/** Validate that graph units and package identities are internally consistent. */
+export function validateReleasePlanGraph(graph: ReleaseUnitGraph): void {
+  const units = new Map<string, ReleaseUnit>();
+  for (const unit of graph.units) {
+    if (units.has(unit.id)) throw new Error(`Duplicate release plan unit ${unit.id}`);
+    units.set(unit.id, unit);
+  }
+  for (const project of graph.projects) {
+    if (project.unit && !units.has(project.unit)) {
+      throw new Error(`Release project ${project.identity} has unknown unit ${project.unit}`);
+    }
+  }
+  for (const artifact of graph.artifacts) {
+    if (!units.has(artifact.unit)) {
+      throw new Error(`Release artifact ${artifact.id} has unknown unit ${artifact.unit}`);
+    }
+  }
+}

package/src/release-please.ts

@@ -0,0 +1,242 @@
+/**
+ * Release Please integration for Projen-owned polyglot release units.
+ *
+ * Release Please remains responsible for semantic version selection, release
+ * pull requests, tags, and GitHub Releases. This plugin contributes only the
+ * dependency propagation encoded by the generated release-unit graph.
+ *
+ * @module
+ */
+
+import type { Commit } from "release-please/build/src/commit.js";
+import type {
+  CandidateReleasePullRequest,
+  RepositoryConfig,
+} from "release-please/build/src/manifest.js";
+import { ManifestPlugin } from "release-please/build/src/plugin.js";
+import type { Release } from "release-please/build/src/release.js";
+import type { Scm } from "release-please/build/src/scm.js";
+import type { Strategy } from "release-please/build/src/strategy.js";
+import { CompositeUpdater } from "release-please/build/src/updaters/composite.js";
+import { ReleasePleaseManifest } from "release-please/build/src/updaters/release-please-manifest.js";
+import { BranchName } from "release-please/build/src/util/branch-name.js";
+import { PullRequestBody } from "release-please/build/src/util/pull-request-body.js";
+import { PullRequestTitle } from "release-please/build/src/util/pull-request-title.js";
+import { Version } from "release-please/build/src/version.js";
+import { PatchVersionUpdate } from "release-please/build/src/versioning-strategy.js";
+import { satisfies, validRange } from "semver";
+import type { ReleaseDependencyEdge, ReleaseUnit, ReleaseUnitGraph } from "./release-catalog.ts";
+
+/** Options for {@link ReleaseUnitWorkspacePlugin}. */
+export interface ReleaseUnitWorkspacePluginOptions {
+  readonly graph: ReleaseUnitGraph;
+  readonly manifestPath?: string;
+  readonly merge?: boolean;
+}
+
+/**
+ * Propagate Release Please candidates through the cross-language release graph.
+ *
+ * Direct candidates retain the semantic increment selected from their commits.
+ * A dependent introduced only by graph propagation receives a patch.
+ */
+export class ReleaseUnitWorkspacePlugin extends ManifestPlugin {
+  private readonly graph: ReleaseUnitGraph;
+  private readonly manifestPath: string;
+  private readonly merge: boolean;
+  private strategiesByPath: Record<string, Strategy> = {};
+  private releasesByPath: Record<string, Release> = {};
+
+  constructor(
+    github: Scm,
+    targetBranch: string,
+    repositoryConfig: RepositoryConfig,
+    options: ReleaseUnitWorkspacePluginOptions,
+  ) {
+    super(github, targetBranch, repositoryConfig);
+    this.graph = options.graph;
+    this.manifestPath = options.manifestPath ?? ".release-please-manifest.json";
+    this.merge = options.merge ?? true;
+  }
+
+  public override async run(
+    candidates: CandidateReleasePullRequest[],
+  ): Promise<CandidateReleasePullRequest[]> {
+    const unitsById = new Map(this.graph.units.map((unit) => [unit.id, unit]));
+    const unitsByPath = new Map(this.graph.units.map((unit) => [releaseUnitPath(unit), unit]));
+    const inScope: CandidateReleasePullRequest[] = [];
+    const outOfScope: CandidateReleasePullRequest[] = [];
+    const versions = new Map<string, Version>();
+    const direct = new Set<string>();
+
+    for (const candidate of candidates) {
+      const unit = unitsByPath.get(candidate.path);
+      if (!unit || !candidate.pullRequest.version) {
+        outOfScope.push(candidate);
+        continue;
+      }
+      inScope.push(candidate);
+      direct.add(unit.id);
+      versions.set(unit.id, candidate.pullRequest.version);
+    }
+    if (inScope.length === 0) return candidates;
+
+    const queue = [...direct];
+    const propagated = new Set<string>();
+    while (queue.length > 0) {
+      const changed = queue.shift()!;
+      const changedVersion = versions.get(changed);
+      if (!changedVersion) continue;
+      for (const edge of this.graph.edges.filter((candidate) => candidate.to === changed)) {
+        if (!shouldPropagate(edge, changedVersion, unitsById.get(changed))) continue;
+        if (versions.has(edge.from)) continue;
+        const dependent = unitsById.get(edge.from);
+        if (!dependent) throw new Error(`Release graph references unknown unit ${edge.from}`);
+        versions.set(dependent.id, new PatchVersionUpdate().bump(Version.parse(dependent.version)));
+        propagated.add(dependent.id);
+        queue.push(dependent.id);
+      }
+    }
+
+    for (const id of propagated) {
+      const unit = unitsById.get(id)!;
+      inScope.push(await this.newCandidate(unit, versions.get(id)!));
+    }
+
+    const merged = this.merge ? mergeCandidates(inScope, this.targetBranch) : inScope;
+    const manifestVersions = new Map(
+      [...versions].map(([id, version]) => {
+        const unit = unitsById.get(id);
+        if (!unit) throw new Error(`Release version resolved for unknown unit ${id}`);
+        return [releaseUnitPath(unit), version] as const;
+      }),
+    );
+    const first = merged[0];
+    if (first) {
+      const manifestVersion = versions.values().next().value;
+      if (!manifestVersion) throw new Error("Release Please resolved no component versions");
+      const updater = new ReleasePleaseManifest({
+        version: manifestVersion,
+        versionsMap: manifestVersions,
+      });
+      const existing = first.pullRequest.updates.find(
+        (update) => update.path === this.manifestPath,
+      );
+      if (existing) {
+        existing.updater = new CompositeUpdater(existing.updater, updater);
+      } else {
+        first.pullRequest.updates.push({
+          path: this.manifestPath,
+          createIfMissing: false,
+          updater,
+        });
+      }
+    }
+    return [...outOfScope, ...merged];
+  }
+
+  public override async preconfigure(
+    strategiesByPath: Record<string, Strategy>,
+    _commitsByPath: Record<string, Commit[]>,
+    releasesByPath: Record<string, Release>,
+  ): Promise<Record<string, Strategy>> {
+    this.strategiesByPath = strategiesByPath;
+    this.releasesByPath = releasesByPath;
+    return strategiesByPath;
+  }
+
+  private async newCandidate(
+    unit: ReleaseUnit,
+    version: Version,
+  ): Promise<CandidateReleasePullRequest> {
+    const path = releaseUnitPath(unit);
+    const strategy = this.strategiesByPath[path];
+    if (!strategy) throw new Error(`Release Please strategy not found for ${path}`);
+    const pullRequest = await strategy.buildReleasePullRequest(
+      [],
+      this.releasesByPath[path],
+      false,
+      [],
+      { newVersion: version },
+    );
+    if (!pullRequest) throw new Error(`Release Please did not build a candidate for ${unit.id}`);
+    return {
+      path,
+      pullRequest,
+      config: this.repositoryConfig[path] ?? { releaseType: "simple" },
+    };
+  }
+}
+
+/** Attach graph propagation to a Release Please manifest instance. */
+export function addReleaseUnitPlugin(
+  plugins: ManifestPlugin[],
+  github: Scm,
+  targetBranch: string,
+  repositoryConfig: RepositoryConfig,
+  graph: ReleaseUnitGraph,
+  manifestPath?: string,
+): void {
+  plugins.push(
+    new ReleaseUnitWorkspacePlugin(github, targetBranch, repositoryConfig, {
+      graph,
+      manifestPath,
+    }),
+  );
+}
+
+/** Stable synthetic component path consumed by Release Please. */
+export function releaseUnitPath(unit: Pick<ReleaseUnit, "component">): string {
+  return `.release-units/${unit.component}`;
+}
+
+function shouldPropagate(
+  edge: ReleaseDependencyEdge,
+  newVersion: Version,
+  dependency: ReleaseUnit | undefined,
+): boolean {
+  if (edge.propagation === "never") return false;
+  if (edge.propagation === "always") return true;
+  if (!edge.requirement || !dependency) return true;
+  let requirement = edge.requirement;
+  if (requirement.startsWith("workspace:")) {
+    const workspaceRange = requirement.slice("workspace:".length);
+    if (workspaceRange === "*") return true;
+    requirement = workspaceRange ? `${workspaceRange}${dependency.version}` : dependency.version;
+  }
+  requirement = requirement.replace(/^==/, "=").replaceAll(",", " ");
+  if (!validRange(requirement)) return true;
+  return !satisfies(newVersion.toString(), requirement, { includePrerelease: true });
+}
+
+function mergeCandidates(
+  candidates: CandidateReleasePullRequest[],
+  targetBranch: string,
+): CandidateReleasePullRequest[] {
+  if (candidates.length <= 1) return candidates;
+  const releaseData = candidates.flatMap((candidate) => candidate.pullRequest.body.releaseData);
+  const labels = [...new Set(candidates.flatMap((candidate) => candidate.pullRequest.labels))];
+  const rawUpdates = candidates.flatMap((candidate) => candidate.pullRequest.updates);
+  const updatesByPath = new Map<string, (typeof rawUpdates)[number]>();
+  for (const update of rawUpdates) {
+    const current = updatesByPath.get(update.path);
+    updatesByPath.set(update.path, {
+      ...update,
+      updater: current ? new CompositeUpdater(current.updater, update.updater) : update.updater,
+    });
+  }
+  return [
+    {
+      path: ".",
+      pullRequest: {
+        title: PullRequestTitle.ofTargetBranch(targetBranch),
+        body: new PullRequestBody(releaseData, { useComponents: true }),
+        updates: [...updatesByPath.values()],
+        labels,
+        headRefName: BranchName.ofTargetBranch(targetBranch).toString(),
+        draft: !candidates.some((candidate) => !candidate.pullRequest.draft),
+      },
+      config: { releaseType: "simple" },
+    },
+  ];
+}