versionary 1.0.1 → 1.2.0

package/dist/release/release.d.ts

@@ -15,6 +15,12 @@ export type RunReleaseResult = {
         tag: string;
         version: string;
     }[];
+    releaseTargets: {
+        path: string;
+        tag: string;
+        version: string;
+        dependencies: string[];
+    }[];
 } | {
     action: "release-published";
     message: string;
@@ -24,6 +30,12 @@ export type RunReleaseResult = {
         tagStatus: "created" | "exists";
         metadataStatus: "created" | "exists";
     }[];
+    releaseTargets: {
+        path: string;
+        tag: string;
+        version: string;
+        dependencies: string[];
+    }[];
 };
 export interface RunReleaseOptions {
     logger?: VersionaryPluginContext["logger"];

package/dist/release/release.js

@@ -8,7 +8,8 @@ import { resolveVersionStrategy } from "../strategy/resolve.js";
 import { getChangelogDefaults } from "./plan.js";
 import { isReleaseCommitMessage } from "./pr.js";
 import { executeIdempotentReleaseTarget } from "./recovery.js";
-import { readPendingReleaseTargets } from "./state.js";
+import { hasReleaseStateChangeAtHead, readPendingReleaseTargets, readRecordedPendingReleaseTargets, } from "./state.js";
+import { releaseTargetHandoff } from "./targets.js";
 function escapeRegExp(input) {
     return input.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
@@ -132,7 +133,8 @@ export async function runRelease(cwd = process.cwd()) {
 }
 export async function runReleaseDetailed(cwd = process.cwd(), options = {}) {
     const commitMessage = getHeadCommitMessage(cwd);
-    if (!isReleaseCommitMessage(commitMessage)) {
+    if (!isReleaseCommitMessage(commitMessage) &&
+        !hasReleaseStateChangeAtHead(cwd)) {
         return {
             action: "release-skipped",
             reason: "No release commit context detected; skipping release stage.",
@@ -145,18 +147,33 @@ export async function runReleaseDetailed(cwd = process.cwd(), options = {}) {
         defaultChangelogFormat: strategy.getDefaultChangelogFormat?.(),
     });
     const referenceCommentMode = loaded.config["release-reference-comments"] ?? "off";
-    const version = strategy.readVersion(cwd, loaded.config);
-    const defaultTag = `v${version}`;
     const releaseTargets = readPendingReleaseTargets(cwd);
-    const targets = releaseTargets.length > 0
+    if (loaded.config["separate-release-prs"] && releaseTargets.length === 0) {
+        return {
+            action: "release-skipped",
+            reason: "No untagged package release targets found; skipping release stage.",
+        };
+    }
+    // Recorded-but-fully-tagged targets mean this release already published, so
+    // replaying them keeps a re-run idempotent (and still repairs missing release
+    // metadata). Only a repo that never recorded any target may fall back to
+    // tagging the root package.
+    const recordedTargets = releaseTargets.length > 0
         ? releaseTargets
+        : readRecordedPendingReleaseTargets(cwd);
+    const version = recordedTargets.length === 0
+        ? strategy.readVersion(cwd, loaded.config)
+        : undefined;
+    const targets = recordedTargets.length > 0
+        ? recordedTargets
         : [
             {
                 path: ".",
-                version,
-                tag: defaultTag,
+                version: version,
+                tag: `v${version}`,
             },
         ];
+    const releaseTargetPlan = releaseTargetHandoff(targets, options.logger);
     if (options["dry-run"]) {
         const targetList = targets.map((target) => `${target.tag} (${target.version})`);
         return {
@@ -165,6 +182,7 @@ export async function runReleaseDetailed(cwd = process.cwd(), options = {}) {
                 tag: target.tag,
                 version: target.version,
             })),
+            releaseTargets: releaseTargetPlan,
             message: `Dry run: would publish releases ${targetList.join(", ")}`,
         };
     }
@@ -221,6 +239,7 @@ export async function runReleaseDetailed(cwd = process.cwd(), options = {}) {
     return {
         action: "release-published",
         releases,
+        releaseTargets: releaseTargetPlan,
         message: `Published releases ${published.join(", ")}`,
     };
 }

package/dist/release/state.d.ts

@@ -2,9 +2,24 @@ export interface ReleaseTargetState {
     path: string;
     version: string;
     tag: string;
+    dependencies?: string[];
+}
+export interface PendingReleaseCohort {
+    branch: string;
+    targets: ReleaseTargetState[];
 }
 export declare function getBaselineStatePath(cwd: string): string;
+export declare function getPackageStateDirectory(cwd: string): string;
 export declare function readBaselineSha(cwd?: string): string | null;
 export declare function readReleaseTargets(cwd?: string): ReleaseTargetState[];
 export declare function readPendingReleaseTargets(cwd?: string): ReleaseTargetState[];
-export declare function writeBaselineSha(cwd?: string, sha?: string, releaseTargets?: ReleaseTargetState[]): void;
+export declare function readRecordedPendingReleaseTargets(cwd?: string): ReleaseTargetState[];
+export declare function readPendingReleaseCohorts(cwd?: string): PendingReleaseCohort[];
+/**
+ * Pending targets remain in the manifest after publishing, so the tag set is
+ * the durable evidence that the pending release actually completed.
+ */
+export declare function hasFullyUntaggedPendingRelease(cwd?: string): boolean;
+export declare function writePackageReleaseState(cwd: string, baselineSha: string, releaseTargets: ReleaseTargetState[], branch: string): string[];
+export declare function hasReleaseStateChangeAtHead(cwd?: string): boolean;
+export declare function writeBaselineSha(cwd?: string, sha?: string, releaseTargets?: ReleaseTargetState[]): string[];

package/dist/release/state.js

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { loadConfig } from "../config/load-config.js";
@@ -41,6 +42,11 @@ function validateReleaseTargets(value, key, filePath) {
             typeof record.tag !== "string") {
             throw new Error(`Invalid release manifest at ${filePath}: ${key} must contain string path, version, and tag.`);
         }
+        if (record.dependencies !== undefined &&
+            (!Array.isArray(record.dependencies) ||
+                !record.dependencies.every((dependency) => typeof dependency === "string"))) {
+            throw new Error(`Invalid release manifest at ${filePath}: ${key} dependencies must be an array of package-path strings.`);
+        }
     }
 }
 export function getBaselineStatePath(cwd) {
@@ -51,6 +57,57 @@ export function getBaselineStatePath(cwd) {
     }
     return path.join(cwd, ".versionary-manifest.json");
 }
+export function getPackageStateDirectory(cwd) {
+    return `${getBaselineStatePath(cwd)}.d`;
+}
+function packageStateFileName(packagePath) {
+    const slug = packagePath === "."
+        ? "root"
+        : packagePath
+            .replaceAll("\\", "/")
+            .replace(/[^A-Za-z0-9._-]+/gu, "-")
+            .replace(/^-+|-+$/gu, "") || "package";
+    const digest = createHash("sha256")
+        .update(packagePath)
+        .digest("hex")
+        .slice(0, 12);
+    return `${slug}-${digest}.json`;
+}
+function parsePackageStateFile(raw, filePath) {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Invalid package release state at ${filePath}: expected an object.`);
+    }
+    const state = parsed;
+    if (state[MANIFEST_VERSION_KEY] !== 1) {
+        throw new Error(`Unsupported ${MANIFEST_VERSION_KEY} in ${filePath}: ${String(state[MANIFEST_VERSION_KEY])}.`);
+    }
+    if (typeof state.path !== "string" ||
+        typeof state[BASELINE_SHA_KEY] !== "string" ||
+        typeof state["release-branch"] !== "string") {
+        throw new Error(`Invalid package release state at ${filePath}: path, baseline-sha, and release-branch must be strings.`);
+    }
+    validateReleaseTargets([state["release-target"]], "release-target", filePath);
+    const target = state["release-target"];
+    if (target.path !== state.path) {
+        throw new Error(`Invalid package release state at ${filePath}: release target path must match state path.`);
+    }
+    return state;
+}
+function readPackageStates(cwd) {
+    const directory = getPackageStateDirectory(cwd);
+    if (!fs.existsSync(directory)) {
+        return [];
+    }
+    return fs
+        .readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .map((entry) => {
+        const filePath = path.join(directory, entry.name);
+        return parsePackageStateFile(fs.readFileSync(filePath, "utf8"), filePath);
+    })
+        .sort((a, b) => a.path.localeCompare(b.path));
+}
 export function readBaselineSha(cwd = process.cwd()) {
     const filePath = getBaselineStatePath(cwd);
     if (!fs.existsSync(filePath)) {
@@ -64,22 +121,132 @@ export function readBaselineSha(cwd = process.cwd()) {
 // so this list must persist entries across releases rather than be replaced.
 export function readReleaseTargets(cwd = process.cwd()) {
     const filePath = getBaselineStatePath(cwd);
-    if (!fs.existsSync(filePath)) {
-        return [];
-    }
-    const parsed = parseStateFile(fs.readFileSync(filePath, "utf8"), filePath);
-    return parsed[RELEASE_TARGETS_KEY] ?? [];
+    const legacyTargets = fs.existsSync(filePath)
+        ? (parseStateFile(fs.readFileSync(filePath, "utf8"), filePath)[RELEASE_TARGETS_KEY] ?? [])
+        : [];
+    const packageTargets = readPackageStates(cwd).map((state) => state["release-target"]);
+    return [
+        ...new Map([...legacyTargets, ...packageTargets].map((target) => [
+            target.path,
+            target,
+        ])).values(),
+    ].sort((a, b) => a.path.localeCompare(b.path));
 }
 // The publish set introduced by the current release PR. `release` consumes this
 // so it only publishes/announces what this PR bumped, not every package in the
 // accumulated baseline.
 export function readPendingReleaseTargets(cwd = process.cwd()) {
+    return collectPendingReleaseCohorts(cwd, {
+        allowPartiallyTagged: true,
+    }).flatMap((cohort) => cohort.targets);
+}
+// Every target the release state records, including cohorts whose tags already
+// exist. `release` needs these to tell "this repo never recorded a release"
+// apart from "this release was already published"; only the former may fall
+// back to tagging the root package.
+export function readRecordedPendingReleaseTargets(cwd = process.cwd()) {
+    return collectPendingReleaseCohorts(cwd, {
+        allowPartiallyTagged: true,
+        includeFullyTagged: true,
+    }).flatMap((cohort) => cohort.targets);
+}
+export function readPendingReleaseCohorts(cwd = process.cwd()) {
+    return collectPendingReleaseCohorts(cwd, {});
+}
+function collectPendingReleaseCohorts(cwd, options) {
     const filePath = getBaselineStatePath(cwd);
-    if (!fs.existsSync(filePath)) {
-        return [];
+    const packageStates = readPackageStates(cwd);
+    const sidecarPaths = new Set(packageStates.map((state) => state.path));
+    const byBranch = new Map();
+    for (const state of packageStates) {
+        const targets = byBranch.get(state["release-branch"]) ?? [];
+        targets.push(state["release-target"]);
+        byBranch.set(state["release-branch"], targets);
+    }
+    if (fs.existsSync(filePath)) {
+        const parsed = parseStateFile(fs.readFileSync(filePath, "utf8"), filePath);
+        const legacyPending = (parsed[PENDING_RELEASE_TARGETS_KEY] ?? []).filter((target) => !sidecarPaths.has(target.path));
+        if (legacyPending.length > 0) {
+            const branch = loadConfig(cwd).config["release-branch"] ?? "versionary/release";
+            byBranch.set(branch, [...(byBranch.get(branch) ?? []), ...legacyPending]);
+        }
+    }
+    const pending = [];
+    for (const [branch, unsortedTargets] of byBranch) {
+        const targets = [...unsortedTargets].sort((a, b) => a.path.localeCompare(b.path));
+        const tagged = targets.filter((target) => hasLocalTag(cwd, target.tag));
+        if (tagged.length === targets.length && !options.includeFullyTagged) {
+            continue;
+        }
+        if (tagged.length > 0 &&
+            tagged.length < targets.length &&
+            !options.allowPartiallyTagged) {
+            const existingTags = tagged.map((target) => target.tag).join(", ");
+            const missingTags = targets
+                .filter((target) => !tagged.includes(target))
+                .map((target) => target.tag)
+                .join(", ");
+            throw new Error(`Pending release cohort on ${branch} is partially tagged and cannot move safely. Existing tags: ${existingTags}. Missing tags: ${missingTags}. Rerun the original release workflow to complete it.`);
+        }
+        pending.push({ branch, targets });
+    }
+    return pending.sort((a, b) => a.branch.localeCompare(b.branch));
+}
+function hasLocalTag(cwd, tag) {
+    try {
+        execFileSync("git", ["show-ref", "--verify", "--quiet", `refs/tags/${tag}`], {
+            cwd,
+            stdio: "ignore",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Pending targets remain in the manifest after publishing, so the tag set is
+ * the durable evidence that the pending release actually completed.
+ */
+export function hasFullyUntaggedPendingRelease(cwd = process.cwd()) {
+    return readPendingReleaseCohorts(cwd).length > 0;
+}
+export function writePackageReleaseState(cwd, baselineSha, releaseTargets, branch) {
+    const directory = getPackageStateDirectory(cwd);
+    fs.mkdirSync(directory, { recursive: true });
+    const written = [];
+    for (const target of releaseTargets) {
+        const filePath = path.join(directory, packageStateFileName(target.path));
+        const state = {
+            [MANIFEST_VERSION_KEY]: 1,
+            path: target.path,
+            [BASELINE_SHA_KEY]: baselineSha,
+            "release-target": target,
+            "release-branch": branch,
+        };
+        fs.writeFileSync(filePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+        written.push(path.relative(cwd, filePath));
+    }
+    return written.sort((a, b) => a.localeCompare(b));
+}
+export function hasReleaseStateChangeAtHead(cwd = process.cwd()) {
+    const relativeDirectory = path.relative(cwd, getPackageStateDirectory(cwd));
+    try {
+        const changed = execFileSync("git", ["diff-tree", "--no-commit-id", "--name-only", "-r", "HEAD^", "HEAD"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .split("\n")
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+        return changed.some((entry) => entry === relativeDirectory ||
+            entry.startsWith(`${relativeDirectory}${path.sep}`) ||
+            entry.startsWith(`${relativeDirectory}/`));
+    }
+    catch {
+        return false;
     }
-    const parsed = parseStateFile(fs.readFileSync(filePath, "utf8"), filePath);
-    return parsed[PENDING_RELEASE_TARGETS_KEY] ?? [];
 }
 export function writeBaselineSha(cwd = process.cwd(), sha, releaseTargets) {
     const baselineShaValue = sha ??
@@ -114,4 +281,10 @@ export function writeBaselineSha(cwd = process.cwd(), sha, releaseTargets) {
         [PENDING_RELEASE_TARGETS_KEY]: nextPending,
     };
     fs.writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    const written = [path.relative(cwd, filePath)];
+    if (releaseTargets !== undefined &&
+        fs.existsSync(getPackageStateDirectory(cwd))) {
+        written.push(...writePackageReleaseState(cwd, baselineShaValue, releaseTargets, loadConfig(cwd).config["release-branch"] ?? "versionary/release"));
+    }
+    return written.sort((a, b) => a.localeCompare(b));
 }

package/dist/release/targets.d.ts

@@ -0,0 +1,21 @@
+import type { ReleaseTargetState } from "./state.js";
+export interface ReleaseTargetOrder {
+    ordered: ReleaseTargetState[];
+    cyclicPaths: string[];
+}
+/**
+ * Return a deterministic dependency-first handoff for downstream publishers.
+ * Dependencies outside this release set are already published and do not
+ * constrain the current targets.
+ *
+ * A cycle cannot be ordered dependency-first, so the remaining targets are
+ * emitted in package-path order instead. The ordering is advisory metadata, so
+ * degrading it must not block tagging; callers surface `cyclicPaths` so the
+ * cycle still gets reported.
+ */
+export declare function orderReleaseTargets(targets: readonly ReleaseTargetState[]): ReleaseTargetOrder;
+export declare function releaseTargetHandoff(targets: readonly ReleaseTargetState[], logger?: {
+    warn: (message: string) => void;
+}): Array<ReleaseTargetState & {
+    dependencies: string[];
+}>;

package/dist/release/targets.js

@@ -0,0 +1,85 @@
+function comparePaths(left, right) {
+    return left.localeCompare(right);
+}
+function buildDependencyGraph(targets) {
+    const releasingPaths = new Set(targets.map((target) => target.path));
+    return new Map(targets.map((target) => [
+        target.path,
+        new Set((target.dependencies ?? []).filter((dependencyPath) => dependencyPath !== target.path &&
+            releasingPaths.has(dependencyPath))),
+    ]));
+}
+/**
+ * Return the paths that actually sit on a dependency cycle, meaning those that
+ * are reachable from themselves. Packages that merely depend on a cycle are
+ * blocked by it but are not part of it, so naming them would send maintainers
+ * to inspect manifests that are fine.
+ */
+function findCyclicPaths(graph) {
+    const cyclic = [];
+    for (const path of graph.keys()) {
+        const seen = new Set();
+        const stack = [...(graph.get(path) ?? [])];
+        let onCycle = false;
+        while (stack.length > 0) {
+            const current = stack.pop();
+            if (current === path) {
+                onCycle = true;
+                break;
+            }
+            if (seen.has(current)) {
+                continue;
+            }
+            seen.add(current);
+            stack.push(...(graph.get(current) ?? []));
+        }
+        if (onCycle) {
+            cyclic.push(path);
+        }
+    }
+    return cyclic.sort(comparePaths);
+}
+/**
+ * Return a deterministic dependency-first handoff for downstream publishers.
+ * Dependencies outside this release set are already published and do not
+ * constrain the current targets.
+ *
+ * A cycle cannot be ordered dependency-first, so the remaining targets are
+ * emitted in package-path order instead. The ordering is advisory metadata, so
+ * degrading it must not block tagging; callers surface `cyclicPaths` so the
+ * cycle still gets reported.
+ */
+export function orderReleaseTargets(targets) {
+    const graph = buildDependencyGraph(targets);
+    const remaining = [...targets].sort((left, right) => comparePaths(left.path, right.path));
+    const emitted = new Set();
+    const ordered = [];
+    while (remaining.length > 0) {
+        const readyIndex = remaining.findIndex((target) => [...(graph.get(target.path) ?? [])].every((dependencyPath) => emitted.has(dependencyPath)));
+        // Nothing is ready only when every remaining target waits on a cycle;
+        // break the deadlock with the first target in package-path order.
+        const [target] = remaining.splice(readyIndex === -1 ? 0 : readyIndex, 1);
+        if (!target) {
+            continue;
+        }
+        ordered.push(target);
+        emitted.add(target.path);
+    }
+    return { ordered, cyclicPaths: findCyclicPaths(graph) };
+}
+export function releaseTargetHandoff(targets, logger) {
+    const { ordered, cyclicPaths } = orderReleaseTargets(targets);
+    if (cyclicPaths.length > 0) {
+        const quoted = cyclicPaths.map((path) => `"${path}"`).join(", ");
+        logger?.warn(`Release dependencies contain a cycle: ${quoted}. Publishing order for those packages falls back to package-path order.`);
+    }
+    const releasingPaths = new Set(targets.map((target) => target.path));
+    return ordered.map((target) => ({
+        ...target,
+        // Dependencies outside the release set are already published, and the
+        // documented contract is that every entry names a target in this handoff.
+        dependencies: [...new Set(target.dependencies ?? [])]
+            .filter((dependencyPath) => dependencyPath !== target.path && releasingPaths.has(dependencyPath))
+            .sort(comparePaths),
+    }));
+}

package/dist/scm/github-plugin.js

@@ -223,6 +223,50 @@ export function createGitHubPlugin() {
                 state: toReviewRequestState(created, `pull request #${created.number} in ${repoRef(repo)}`),
             };
         },
+        async listOpenReviewRequests(input, _context) {
+            const repo = getRepoFromEnv();
+            const octokit = new Octokit({ auth: getGitHubToken() });
+            const pulls = [];
+            try {
+                for (let page = 1;; page += 1) {
+                    const response = await octokit.pulls.list({
+                        owner: repo.owner,
+                        repo: repo.repo,
+                        state: "open",
+                        base: input.baseBranch,
+                        per_page: 100,
+                        page,
+                    });
+                    pulls.push(...response.data);
+                    if (response.data.length < 100) {
+                        break;
+                    }
+                }
+            }
+            catch (error) {
+                const { message } = parseGitHubError(error);
+                throw new Error(`Failed listing open pull requests into "${input.baseBranch}": [${repoRef(repo)}] ${message}`);
+            }
+            const requiredLabels = new Set(input.labels ?? []);
+            return pulls
+                .filter((pull) => pull.head.ref.startsWith(input.headBranchPrefix))
+                .filter((pull) => {
+                const labels = new Set(pull.labels
+                    .map((label) => typeof label === "string" ? label : (label.name ?? ""))
+                    .filter(Boolean));
+                return [...requiredLabels].every((label) => labels.has(label));
+            })
+                .map((pull) => ({
+                id: String(pull.id),
+                number: pull.number,
+                url: pull.html_url,
+                state: toReviewRequestState(pull, `pull request #${pull.number} in ${repoRef(repo)}`),
+                baseBranch: pull.base.ref,
+                headBranch: pull.head.ref,
+                title: pull.title,
+            }))
+                .sort((a, b) => a.headBranch.localeCompare(b.headBranch));
+        },
         async closeReviewRequestIfExists(input, _context) {
             const repo = getRepoFromEnv();
             const octokit = new Octokit({ auth: getGitHubToken() });

package/dist/scm/types.d.ts

@@ -20,6 +20,16 @@ export interface ScmReviewRequestResult {
     url: string;
     state: "open" | "closed" | "merged";
 }
+export interface ScmListReviewRequestsInput {
+    baseBranch: string;
+    headBranchPrefix: string;
+    labels?: string[];
+}
+export interface ScmReviewRequestSummary extends ScmReviewRequestResult {
+    baseBranch: string;
+    headBranch: string;
+    title: string;
+}
 export interface ScmCloseReviewRequestInput {
     baseBranch: string;
     headBranch: string;
@@ -58,6 +68,7 @@ export interface ScmReleaseReferenceCommentsResult {
 export interface ScmClient {
     provider: ScmProvider;
     createOrUpdateReviewRequest: (input: ScmReviewRequestInput, context: ScmClientContext) => Promise<ScmReviewRequestResult>;
+    listOpenReviewRequests: (input: ScmListReviewRequestsInput, context: ScmClientContext) => Promise<ScmReviewRequestSummary[]>;
     closeReviewRequestIfExists: (input: ScmCloseReviewRequestInput, context: ScmClientContext) => Promise<ScmCloseReviewRequestResult>;
     createReleaseMetadata: (input: ScmReleaseMetadataInput, context: ScmClientContext) => Promise<ScmReleaseMetadataResult>;
     createReleaseReferenceComments?: (input: ScmReleaseReferenceCommentsInput, context: ScmClientContext) => Promise<ScmReleaseReferenceCommentsResult>;

package/dist/strategy/cmake.d.ts

@@ -0,0 +1,2 @@
+import type { VersionStrategy } from "./types.js";
+export declare const cmakeVersionStrategy: VersionStrategy;