YamlDepsSync.java
package network.ike.plugin.ws;
import network.ike.plugin.ws.vcs.VcsOperations;
import network.ike.workspace.Manifest;
import network.ike.workspace.ManifestException;
import network.ike.workspace.ManifestReader;
import network.ike.workspace.Subproject;
import org.apache.maven.api.plugin.Log;
import org.apache.maven.api.plugin.MojoException;
import java.io.File;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
/**
* Re-derive each subproject's {@code depends-on} edges from POM
* contents and rewrite {@code workspace.yaml} when they have drifted.
*
* <p><b>Why.</b> {@code ws:add} derives {@code depends-on} once at
* add time. POMs change every commit; without a periodic re-derive the
* YAML graph drifts from POM reality, and {@code ws:overview},
* {@code ws:release} topo-sort, and {@code ws:cascade} all use the
* stale graph silently. This sync runs as part of the post-mutation
* hook so any goal that touches the workspace also leaves the YAML
* matching the POMs.
*
* <p><b>Idempotent.</b> Same POMs in → same YAML out. Re-running
* back-to-back produces no further change.
*
* <p><b>Merge, not replace.</b> Derivation only knows {@code build}
* edges, so only build edges are machine-owned: hand-declared entries
* with any other relationship ({@code bundle}, {@code content},
* {@code tooling}) are preserved verbatim — comments included — and
* are never downgraded to {@code build}
* (IKE-Network/ike-issues#963, #964). See {@link DependsOnMerge}.
*
* <p><b>Each member in its own section.</b> A member's edges are written
* to the block in that member's own section of the manifest, and a
* member with no {@code depends-on:} key gains one there. The summary
* the sync returns is read back from the manifest it wrote, member by
* member, so the re-derivation commit describes its own diff
* (IKE-Network/ike-issues#1387).
*
* <p><b>Acyclic by construction.</b> Contracting the module graph to
* repo granularity can manufacture a cycle no module edge actually
* forms. Before writing, the prospective repo-level ordering graph is
* checked; on a cycle nothing is written and the contributing
* module-level edges are reported with file locations
* (IKE-Network/ike-issues#962, {@link DependsOnCycleGate}).
*
* <p>Subprojects that aren't cloned on disk are left untouched —
* we can't read the POM that drives the derivation.
*
* <p>Subprojects whose checkout <em>drifts</em> from the manifest —
* a different branch than the entry declares, or a detached HEAD away
* from the {@code sha:} pin — are likewise left untouched: the POM on
* disk does not represent the manifest's declared state, and deriving
* from it strips edges that are real on the declared branch
* (IKE-Network/ike-issues#968). A checkout without git metadata
* derives as before — branch verification needs a repository.
*
* <p>See {@code IKE-Network/ike-issues#279}.
*/
final class YamlDepsSync {
private YamlDepsSync() {}
/**
* Outcome of a sync: whether {@code workspace.yaml} was rewritten,
* and one summary line per subproject whose own block the rewrite
* changed, in manifest order, for the re-derivation commit message
* (IKE-Network/ike-issues#964, #1387).
*/
record SyncResult(boolean changed, List<String> changeLines) {
static final SyncResult UNCHANGED =
new SyncResult(false, List.of());
}
/**
* Refresh {@code depends-on} edges for the workspace at
* {@code workspaceRoot}.
*
* @param workspaceRoot the workspace root directory
* @param log plugin log for the per-subproject summary
* @return the sync outcome; unchanged when the manifest was already
* up to date, would have become cyclic, or could not be
* processed
*/
static SyncResult run(File workspaceRoot, Log log) {
Path manifestPath = Manifests.path(workspaceRoot);
if (!Files.isRegularFile(manifestPath)) {
log.debug("yaml-deps-sync: no workspace.yaml — skipping");
return SyncResult.UNCHANGED;
}
try {
Manifest manifest = ManifestReader.read(manifestPath);
String yaml = Files.readString(manifestPath, StandardCharsets.UTF_8);
// ── Phase 1: derive and dry-run the merges; no writes ──
Map<String, List<WsAddMojo.DerivedDep>> derivedByName =
new LinkedHashMap<>();
Map<String, Map<String, List<WsAddMojo.PomRef>>> edgeSources =
new LinkedHashMap<>();
Map<String, Set<String>> prospective = new LinkedHashMap<>();
Set<String> known = manifest.subprojects().keySet();
List<String> driftSkipped = new ArrayList<>();
for (Map.Entry<String, Subproject> entry
: manifest.subprojects().entrySet()) {
String name = entry.getKey();
Subproject sub = entry.getValue();
prospective.put(name,
DependsOnCycleGate.orderingTargets(sub, known));
Path subDir = workspaceRoot.toPath().resolve(name);
if (!Files.exists(subDir.resolve("pom.xml"))) {
// Not cloned — leave existing depends-on alone
continue;
}
if (Files.exists(subDir.resolve(".git"))) {
String drift = driftReason(subDir,
declaredBranch(sub, manifest), sub.sha());
if (drift != null) {
// Drifted checkout — its POM does not represent
// the manifest's declared state (#968).
driftSkipped.add(name + " — " + drift);
continue;
}
}
WsAddMojo.Derivation derivation =
WsAddMojo.deriveDependenciesDetailed(
workspaceRoot.toPath(), manifestPath,
subDir, name);
DependsOnMerge.Result merged = DependsOnMerge.merge(
yaml, name, derivation.deps());
if (!merged.changed(yaml)) continue;
derivedByName.put(name, derivation.deps());
edgeSources.put(name, derivation.producerSources());
prospective.put(name,
orderingTargets(merged.finalRelationships(), known));
}
if (!driftSkipped.isEmpty()) {
log.warn(" yaml-deps-sync: left " + driftSkipped.size()
+ " drifted subproject(s) alone — the checkout "
+ "disagrees with the manifest, so its POM does "
+ "not represent the declared state; recorded "
+ "depends-on kept (IKE-Network/ike-issues#968):");
for (String skipped : driftSkipped) {
log.warn(" " + skipped);
}
log.warn(" Align checkouts to the manifest: "
+ "mvn ws:reconcile-branches-publish -Dfrom=manifest");
log.warn(" Or accept checkouts as truth: "
+ "mvn ws:reconcile-branches-publish");
}
if (derivedByName.isEmpty()) {
log.debug("yaml-deps-sync: workspace.yaml is up to date");
return SyncResult.UNCHANGED;
}
// ── Phase 2: acyclicity gate (#962) ────────────────────
List<String> cycle = DependsOnCycleGate.findCycle(prospective);
if (!cycle.isEmpty()) {
log.error(DependsOnCycleGate.diagnostic(
workspaceRoot.toPath(), cycle, edgeSources));
return SyncResult.UNCHANGED;
}
// ── Phase 3: apply the merges and write once ───────────
String updated = yaml;
for (Map.Entry<String, List<WsAddMojo.DerivedDep>> entry
: derivedByName.entrySet()) {
updated = DependsOnMerge.merge(
updated, entry.getKey(), entry.getValue()).yaml();
}
if (updated.equals(yaml)) {
log.debug("yaml-deps-sync: workspace.yaml is up to date");
return SyncResult.UNCHANGED;
}
Files.writeString(manifestPath, updated, StandardCharsets.UTF_8);
// ── Phase 4: report what was written (#1387) ───────────
// Each line is read back from the two texts: what a
// member's own block recorded before against what it
// records now. A merge step's own account says what was
// asked of it, which is not what the file holds when the
// step landed in another member's block or a later step
// wrote over it.
int totalAdded = 0;
int totalRemoved = 0;
List<String> changeLines = new ArrayList<>();
for (String name : manifest.subprojects().keySet()) {
BlockChange change = BlockChange.between(name,
DependsOnMerge.recorded(yaml, name),
DependsOnMerge.recorded(updated, name));
if (change == null) continue;
totalAdded += change.added();
totalRemoved += change.removed();
changeLines.add(change.summary());
if (change.removed() == 0) {
log.info(" workspace.yaml: " + change.summary());
} else {
// Removals may be discarding a hand edit — say so
// where the user can see it (#964).
log.warn(" workspace.yaml: " + change.summary()
+ " — build edges are re-derived from POMs; "
+ "a deliberately absent edge needs a non-build "
+ "relationship (e.g. bundle) to survive");
}
}
log.info(" yaml-deps-sync: " + totalAdded + " edge(s) added, "
+ totalRemoved + " edge(s) removed");
return new SyncResult(true, List.copyOf(changeLines));
} catch (IOException | ManifestException e) {
log.warn("yaml-deps-sync: cannot update workspace.yaml — "
+ e.getMessage());
return SyncResult.UNCHANGED;
}
}
/**
* What a sync wrote to one member's {@code depends-on} block, as the
* difference between the block read from the manifest text before
* and after (IKE-Network/ike-issues#1387).
*
* @param summary the member's line for the log and for the
* re-derivation commit message
* @param added the number of edges the block gained, counting an
* edge re-recorded under another relationship
* @param removed the number of edges the block lost outright
*/
private record BlockChange(String summary, int added, int removed) {
/**
* Compare one member's block before and after a sync.
*
* <p>An edge whose relationship moved — a {@code build} edge
* that derivation now reads as {@code bundle} (#965) — is a
* supersede, not a discard: it counts as added and is named
* apart from the removals, so the hand-edit warning on removals
* (#964) stays honest.
*
* @param name the member
* @param before the block as the manifest recorded it
* @param after the block as the manifest records it now
* @return the change, or null when the block is the same
*/
static BlockChange between(String name,
DependsOnMerge.Recorded before,
DependsOnMerge.Recorded after) {
if (before.equals(after)) return null;
List<String> added = new ArrayList<>();
List<String> versioned = new ArrayList<>();
Map<String, List<String>> moved = new LinkedHashMap<>();
for (Map.Entry<String, DependsOnMerge.Edge> entry
: after.edges().entrySet()) {
String target = entry.getKey();
DependsOnMerge.Edge now = entry.getValue();
DependsOnMerge.Edge was = before.edges().get(target);
if (was == null) {
added.add(target);
} else if (!was.relationship()
.equalsIgnoreCase(now.relationship())) {
added.add(target);
moved.computeIfAbsent(
was.relationship() + "→" + now.relationship(),
transition -> new ArrayList<>()).add(target);
} else if (now.versionProperty() != null
&& !now.versionProperty()
.equals(was.versionProperty())) {
versioned.add(target);
}
}
List<String> removed = new ArrayList<>();
for (String target : before.edges().keySet()) {
if (!after.edges().containsKey(target)) removed.add(target);
}
boolean created = !before.present() && after.present();
if (added.isEmpty() && removed.isEmpty() && versioned.isEmpty()) {
// No edge changed: a block written for a member that
// has no edges, or the managed marker on an existing one.
return new BlockChange(name + (created
? ": add managed block, no edges"
: ": annotate managed block"), 0, 0);
}
StringBuilder summary = new StringBuilder(name)
.append(" depends-on (+").append(added.size())
.append(", -").append(removed.size()).append(')');
if (!added.isEmpty()) summary.append(" added ").append(added);
if (!removed.isEmpty()) {
summary.append(" removed ").append(removed);
}
for (Map.Entry<String, List<String>> transition
: moved.entrySet()) {
summary.append(' ').append(transition.getKey())
.append(' ').append(transition.getValue());
}
if (!versioned.isEmpty()) {
summary.append(" version-property ").append(versioned);
}
if (created) summary.append(" in a new block");
return new BlockChange(summary.toString(),
added.size(), removed.size());
}
}
/**
* The branch the manifest declares for a subproject: its own
* {@code branch:} field, falling back to {@code defaults.branch}.
*
* @param sub the subproject entry
* @param manifest the parsed manifest
* @return the declared branch, or null when neither is set
*/
private static String declaredBranch(Subproject sub, Manifest manifest) {
if (sub.branch() != null && !sub.branch().isBlank()) {
return sub.branch();
}
return manifest.defaults() == null
? null : manifest.defaults().branch();
}
/**
* Why a cloned subproject's checkout cannot back a re-derivation,
* or null when it can (IKE-Network/ike-issues#968).
*
* <p>A checkout on a different branch than the manifest declares —
* or detached anywhere but the manifest's {@code sha:} pin — is the
* same epistemic situation as an absent clone: the POM on disk does
* not represent the declared state. Unreadable git state counts as
* drift for the same reason.
*
* @param subDir the subproject checkout directory
* @param declaredBranch the manifest branch (may be null)
* @param pinnedSha the manifest {@code sha:} pin (may be null)
* @return a human-readable drift description, or null when coherent
*/
private static String driftReason(Path subDir, String declaredBranch,
String pinnedSha) {
try {
String checkout = VcsOperations.currentBranch(subDir.toFile());
if (checkout == null || checkout.isBlank()) {
String head = VcsOperations.headSha(subDir.toFile());
if (pinnedSha != null && pinnedSha.startsWith(head)) {
// Parked exactly on the manifest pin — coherent.
return null;
}
return "detached at " + head
+ (declaredBranch == null ? ""
: ", manifest declares " + declaredBranch);
}
if (declaredBranch != null && !declaredBranch.isBlank()
&& !declaredBranch.equals(checkout)) {
return "checkout on " + checkout
+ ", manifest declares " + declaredBranch;
}
return null;
} catch (MojoException e) {
return "git state unreadable (" + e.getMessage() + ")";
}
}
/**
* Ordering-edge targets of a merged entry set: every final entry
* except {@code relationship: bundle}, restricted to known
* subprojects — the same rule as
* {@link DependsOnCycleGate#orderingTargets}.
*/
private static Set<String> orderingTargets(
Map<String, String> finalRelationships, Set<String> known) {
Set<String> targets = new LinkedHashSet<>();
for (Map.Entry<String, String> e : finalRelationships.entrySet()) {
if ("bundle".equalsIgnoreCase(e.getValue())) continue;
if (known.contains(e.getKey())) targets.add(e.getKey());
}
return targets;
}
}