@sous-io/sous 0.2.28 → 0.2.30

package/src/lib/repos/providers/gitlab.ts

@@ -28,7 +28,11 @@ import { fetchText, type FetchLike } from "./http.js";
 import {
   buildCanonicalRepo,
   invalidRepoUrl,
+  readingsAfterRepository,
   splitRepoUrl,
+  withoutGitSuffix,
+  type LocationReading,
+  type WrittenLocation,
   type AuthStatus,
   type CanonicalRepo,
   type ChangeProposal,
@@ -80,6 +84,70 @@ export class GitlabProvider extends ProviderBase {
   /** What GitLab calls a proposal. */
   readonly proposalNoun = "merge request";
 
+  /** The host a `gitlab://` locator means when it names none. */
+  readonly defaultHost = GITLAB_HOST;
+
+  /**
+   * A GitLab project path nests (`group/subgroup/project`), so where it ends is
+   * only certain when the location says so: a `-` segment (GitLab's own
+   * separator, as in `/-/tree/main/...`) or a `.git` suffix ends it. Otherwise
+   * every split that leaves a project of at least two segments and at most a
+   * namespace and a recipe after it is a reading, and the caller keeps the one
+   * an index confirms.
+   *
+   * readLocation({ host: "gitlab.com", segments: ["a", "b", "c", "d"] });
+   * // -> project "a/b" naming "c/d", project "a/b/c" naming "d",
+   * //    and project "a/b/c/d" naming nothing
+   *
+   * @param location - The host and the segments after it.
+   */
+  readLocation(location: WrittenLocation): LocationReading[] {
+    const { segments } = location;
+
+    const separator = segments.indexOf("-");
+    if (separator >= 2) {
+      return readingsAfterRepository(
+        this.projectPath(segments.slice(0, separator)),
+        segments.slice(separator)
+      );
+    }
+
+    const suffixed = segments.findIndex((segment) => /\.git$/i.test(segment));
+    if (suffixed >= 1) {
+      return readingsAfterRepository(
+        this.projectPath(segments.slice(0, suffixed + 1)),
+        segments.slice(suffixed + 1)
+      );
+    }
+
+    const readings: LocationReading[] = [];
+    for (let end = 2; end <= segments.length; end++) {
+      const rest = segments.slice(end);
+      if (rest.length > 2) continue;
+      readings.push({ repoPath: this.projectPath(segments.slice(0, end)), named: rest });
+    }
+    return readings;
+  }
+
+  /**
+   * The canonical locator always marks where the project path ends with `-`,
+   * because without it a nested group reads more than one way.
+   *
+   * @param host - The project's host.
+   * @param repoPath - The project's path on that host.
+   * @param rest - What is named inside it.
+   */
+  formatLocator(host: string, repoPath: string, rest: string): string {
+    const where = host === this.defaultHost ? repoPath : `${host}/${repoPath}`;
+    return `${this.id}://${where}${rest.length === 0 ? "" : `/-/${rest}`}`;
+  }
+
+  /** A project path from its segments, with the last one's `.git` gone. */
+  private projectPath(segments: string[]): string {
+    const last = segments.length - 1;
+    return segments.map((segment, index) => (index === last ? withoutGitSuffix(segment) : segment)).join("/");
+  }
+
   matches(url: string): boolean {
     const parts = splitRepoUrl(url);
     if (parts === undefined) return false;

package/src/lib/repos/providers/provider.ts

@@ -56,6 +56,44 @@ export type CanonicalRepo = {
   sshUrl: string;
 };
 
+/**
+ * A location as written in a ref, taken apart only as far as every host agrees:
+ * the host, and the path segments after it. Which of those segments are the
+ * repository and which name something inside it is a host's own rule, so a
+ * provider answers that (see `RepoProvider.readLocation`).
+ *
+ *     https://gitlab.com/group/sub/project/-/tree/main/recipes/workflow/alpha
+ *     // -> { host: "gitlab.com",
+ *     //      segments: ["group", "sub", "project", "-", "tree", "main", ...] }
+ */
+export type WrittenLocation = {
+  /** The host, lowercased, such as `github.com`. */
+  host: string;
+  /** Every path segment after the host, in order, none of them empty. */
+  segments: string[];
+};
+
+/**
+ * One way a provider reads a written location. A location on a host where a
+ * repository path can be any length (a GitLab group nests) may have several.
+ */
+export type LocationReading = {
+  /** The repository's path on the host, such as `sous-io/sous-recipes`, with no `.git`. */
+  repoPath: string;
+  /**
+   * The segments after the repository that name something inside it: a
+   * namespace, a namespace and a recipe, or a namespace and `*`. Empty when the
+   * location names only the repository.
+   */
+  named?: string[];
+  /**
+   * A browser URL's path inside the repository, copied from a host's file view
+   * (after `tree/` or `blob/`), with the branch still in front of it. It is
+   * settled against the `path` each recipe's index entry records.
+   */
+  browsed?: string;
+};
+
 /** Options every provider call accepts, all of them for testing seams. */
 export type ProviderOptions = {
   /**
@@ -215,6 +253,27 @@ export interface RepoProvider {
   readonly id: ProviderId;
   /** What this provider can do; see ProviderFeature. */
   readonly features: ProviderFeature[];
+  /**
+   * The host a locator such as `github://owner/repo/...` means when it names
+   * none. A provider without a public host of its own leaves it out.
+   */
+  readonly defaultHost?: string;
+  /**
+   * Every way this provider reads a location inside one of its repositories:
+   * where the repository path ends, and whether the rest names a namespace, a
+   * recipe or a browser path. An empty list means the provider reads no such
+   * location.
+   */
+  readLocation(location: WrittenLocation): LocationReading[];
+  /**
+   * The canonical locator for something inside one of this provider's
+   * repositories, which is how sous prints a located ref.
+   *
+   * @param host - The repository's host.
+   * @param repoPath - The repository's path on that host.
+   * @param rest - What is named inside it, such as `workflow/alpha`.
+   */
+  formatLocator(host: string, repoPath: string, rest: string): string;
   /** True when this provider handles the given repository URL. */
   matches(url: string): boolean;
   /** Takes a repository URL apart, raising a ConfigError when it does not fit. */
@@ -339,6 +398,43 @@ export function supportsSubmit(provider: RepoProvider): provider is SubmitCapabl
   );
 }
 
+/** The words a host's file view puts between a repository and a path: `tree/` and `blob/`. */
+const BROWSE_WORDS = new Set(["tree", "blob"]);
+
+/**
+ * A repository's last path segment without a `.git` suffix.
+ *
+ * @param segment - The segment as written.
+ */
+export function withoutGitSuffix(segment: string): string {
+  return segment.replace(/\.git$/i, "");
+}
+
+/**
+ * Every reading of the segments after a repository: what they name, and, when
+ * they start with `tree/` or `blob/`, the browser path they could also be. Both
+ * are returned when both are possible (a namespace could be called `tree`), and
+ * the caller keeps the one the repository's index confirms. A leading `-`
+ * segment (GitLab's separator between a project and its pages) is dropped
+ * first, wherever it is written.
+ *
+ * readingsAfterRepository("o/r", ["tree", "main", "recipes", "workflow", "alpha"]);
+ * // -> [{ repoPath: "o/r", browsed: "main/recipes/workflow/alpha" },
+ * //     { repoPath: "o/r", named: ["tree", "main", "recipes", "workflow", "alpha"] }]
+ *
+ * @param repoPath - The repository's path on its host.
+ * @param rest - The segments after it.
+ */
+export function readingsAfterRepository(repoPath: string, rest: string[]): LocationReading[] {
+  const after = rest[0] === "-" ? rest.slice(1) : rest;
+  const readings: LocationReading[] = [];
+  if (after.length >= 2 && BROWSE_WORDS.has(after[0]!.toLowerCase())) {
+    readings.push({ repoPath, browsed: after.slice(1).join("/") });
+  }
+  readings.push({ repoPath, named: after });
+  return readings;
+}
+
 /**
  * Normalizes a repository URL for matching: trims it, drops a trailing slash
  * and a trailing `.git`, and lowercases the scheme and host only.

package/src/lib/repos/release/index-builder.ts

@@ -26,6 +26,13 @@
  * its ranges long afterwards. Those dependencies are resolved exactly once: when
  * the version is first recorded, against the repository as it stands then (or,
  * for a version rebuilt from its tag, as it stood at that tag), and never again.
+ *
+ * A version recorded here is also DESCRIBED, so a consumer can say what
+ * subscribing to it brings in and asks before anything is fetched: each
+ * dependency carries the manifest entry that declared it and whether it is a
+ * co-subscription or a build dependency, and the version carries the variable
+ * definitions its manifest publishes. Those fields are frozen with the rest of
+ * the entry; a version published before they existed keeps its entry as it is.
  */
 
 import fs from "node:fs";
@@ -60,7 +67,17 @@ import {
   type ValidatedRecipe,
   type ValidationProblem,
 } from "./validate.js";
-import { parseDependencyRef } from "../ref.js";
+import {
+  describeDependencyKind,
+  foldDeclaration,
+  type CoveringEntry,
+  type DependencyDeclaration,
+  type GatheredDeclaration,
+} from "../declarations.js";
+import type { DependencyKind } from "../formats/common.js";
+import { isNamedReading, namespaceOfKey, parseRef, refKey } from "../../refs/parse.js";
+import { RefSource } from "../../refs/scopes.js";
+import type { SettledDependency } from "./settle.js";
 
 /** A version that is ready to publish but has no tag yet. */
 export type PendingRelease = {
@@ -113,6 +130,12 @@ export type BuildIndexOptions = {
    * index that describes itself.
    */
   publishing?: Record<string, string>;
+  /**
+   * The dependencies that read more than one way, as `settleDependencyLocations`
+   * settled them, keyed by the dependency as written. Each is recorded under
+   * the keys it reached, with the repository it settled on.
+   */
+  settled?: Map<string, SettledDependency>;
 };
 
 /** The index file's absolute path in a repository. */
@@ -181,14 +204,22 @@ export async function buildIndex(
     // repository as it stood at the tag, which is what it was released against.
     for (const tag of recipeTags) {
       if (Object.hasOwn(versions, tag.version)) continue;
-      const rebuilt = await rebuildTaggedVersion(rootDir, tag, recipe, tagsByKey, existing, run);
+      const rebuilt = await rebuildTaggedVersion(
+        rootDir,
+        tag,
+        recipe,
+        tagsByKey,
+        existing,
+        run,
+        options.settled
+      );
       problems.push(...rebuilt.problems);
       versions[tag.version] = {
         hash: rebuilt.hash,
         tag: tag.tag,
         prerelease: semver.prerelease(tag.version) !== null,
         ...(await releasedAtOf(rootDir, tag.tag, run)),
-        ...(rebuilt.dependencies === undefined ? {} : { dependencies: rebuilt.dependencies }),
+        ...rebuilt.description,
       };
     }
 
@@ -197,7 +228,7 @@ export async function buildIndex(
     const hasTag = recipeTags.some((entry) => entry.tag === tagName);
     const workingHash = await hashDirectory(recipe.dir);
     const where = relativeTo(rootDir, recipe.manifestPath);
-    const declared = declaredDependencies(recipe, validation);
+    const declared = declaredDependencies(recipe, validation, options.settled);
 
     // A version the index publishes must have a tag, with one exception: the
     // version the manifest declares right now, which is the one a release is in
@@ -249,6 +280,9 @@ export async function buildIndex(
             ...checkRecordedDependencies(key, version, published.dependencies, declared)
           );
         }
+        if (taggedHash === workingHash) {
+          problems.push(...checkRecordedLists(key, version, published, recipe));
+        }
       }
       // A tagged version the index did not record was rebuilt from its tag above.
 
@@ -278,13 +312,12 @@ export async function buildIndex(
       // follows on the very commit that carries this index.
       const published = existingVersions[version];
       if (options.publishing?.[key] === version || published !== undefined) {
-        const dependencies = resolveIndexDependencies(declared, current);
         versions[version] = {
           hash: workingHash,
           tag: tagName,
           prerelease: semver.prerelease(version) !== null,
           releasedAt: published?.releasedAt ?? now.toISOString(),
-          ...(dependencies === undefined ? {} : { dependencies }),
+          ...describeVersion(recipe, declared, current),
         };
       }
 
@@ -419,10 +452,10 @@ export function describeIndexDrift(
  * `DeclaredDependencies`. A whole-namespace declaration is expanded into one
  * entry per recipe the namespace holds.
  */
-type DeclaredDependency =
+type DeclaredLocation =
   | {
       /** A recipe in another repository, named by its location. */
-      kind: "remote";
+      where: "remote";
       /** The canonical identity of the repository publishing it. */
       repo: string;
       /** The range the manifest declared, `*` when it declared none. */
@@ -430,7 +463,7 @@ type DeclaredDependency =
     }
   | {
       /** A recipe in this same repository. */
-      kind: "sibling";
+      where: "sibling";
       /** The range the manifest declared, when it declared one. */
       range?: string;
       /**
@@ -442,6 +475,9 @@ type DeclaredDependency =
       named: boolean;
     };
 
+/** One declared dependency: where it lives, and the manifest entry bringing it in. */
+type DeclaredDependency = DeclaredLocation & DependencyDeclaration;
+
 /** Everything one recipe's manifest declares, under `depends` and `subscribes`. */
 type DeclaredDependencies = {
   /** Every dependency, keyed `namespace/recipe`; a later declaration wins over an earlier one. */
@@ -464,49 +500,80 @@ type SiblingState = {
  *
  * @param recipe - The recipe whose dependencies are being read.
  * @param validation - The validated repository, for expanding namespace refs.
+ * @param settled - The dependencies that read more than one way, as the release settled them.
  */
 function declaredDependencies(
   recipe: ValidatedRecipe,
-  validation: RepoValidation
+  validation: RepoValidation,
+  settled: Map<string, SettledDependency> = new Map()
 ): DeclaredDependencies {
-  const byKey = new Map<string, DeclaredDependency>();
+  const byKey = new Map<string, DeclaredLocation>();
   const namespaces = new Set<string>();
-  const declared = [
-    ...(recipe.manifest.depends ?? []),
-    ...(recipe.manifest.subscribes ?? []),
+  // Which entry brings each recipe in, and whether as a co-subscription, by the
+  // rule every reader of the index shares (`foldDeclaration`).
+  const declarations = new Map<string, GatheredDeclaration>();
+  const declared: ReadonlyArray<readonly [DependencyKind, string]> = [
+    ...(recipe.manifest.depends ?? []).map((written) => ["depends", written] as const),
+    ...(recipe.manifest.subscribes ?? []).map((written) => ["subscribes", written] as const),
   ];
 
+  /** Records that one entry covers one recipe. */
+  const cover = (key: string, entry: CoveringEntry): void => {
+    declarations.set(key, foldDeclaration(declarations.get(key), entry));
+  };
+
   /** Records one sibling, remembering whether any declaration named it. */
   const addSibling = (key: string, range: string | undefined, named: boolean): void => {
     const before = byKey.get(key);
-    const namedBefore = before?.kind === "sibling" && before.named;
+    const namedBefore = before?.where === "sibling" && before.named;
     byKey.set(key, {
-      kind: "sibling",
+      where: "sibling",
       ...(range === undefined ? {} : { range }),
       named: named || namedBefore,
     });
   };
 
-  for (const written of declared) {
-    let parsed;
+  for (const [kind, written] of declared) {
+    // A dependency that reads more than one way was settled by the release,
+    // and what it settled on is what a consumer reads instead of probing.
+    const answer = settled.get(written.trim());
+    if (answer !== undefined) {
+      for (const key of answer.keys) {
+        byKey.set(key, { where: "remote", repo: answer.identity, range: answer.range ?? "*" });
+        cover(key, { written, kind, named: answer.keys.length === 1 });
+      }
+      continue;
+    }
+
+    let readings;
     try {
-      parsed = parseDependencyRef(written);
+      readings = parseRef(written, RefSource.Manifest);
     } catch {
       // A dependency that does not parse is already reported by validation.
       continue;
     }
-
-    if (parsed.kind === "remote") {
-      byKey.set(`${parsed.namespace}/${parsed.recipe}`, {
-        kind: "remote",
-        repo: parsed.canonicalRepo!,
-        range: parsed.range ?? "*",
-      });
+    // Several readings, or a browser path, are settled above or reported by
+    // the settling step; there is nothing more to record here.
+    const parsed = readings[0]!;
+    if (readings.length !== 1 || !isNamedReading(parsed)) continue;
+
+    if (parsed.location !== undefined) {
+      // A whole namespace in another repository is read from that repository's
+      // own index by the consumer; only a recipe has a key to record.
+      if (parsed.recipe !== undefined) {
+        byKey.set(refKey(parsed), {
+          where: "remote",
+          repo: parsed.location.identity,
+          range: parsed.range ?? "*",
+        });
+        cover(refKey(parsed), { written, kind, named: true });
+      }
       continue;
     }
 
     if (parsed.recipe !== undefined) {
-      addSibling(`${parsed.namespace}/${parsed.recipe}`, parsed.range, true);
+      addSibling(refKey(parsed), parsed.range, true);
+      cover(refKey(parsed), { written, kind, named: true });
       continue;
     }
 
@@ -516,10 +583,17 @@ function declaredDependencies(
       if (entry.manifest.namespace !== parsed.namespace) continue;
       if (entry.key === recipe.key) continue;
       addSibling(entry.key, undefined, false);
+      cover(entry.key, { written, kind, named: false });
     }
   }
 
-  return { byKey, namespaces };
+  const described = new Map<string, DeclaredDependency>();
+  for (const [key, dependency] of byKey) {
+    const { declared: entry, kind } = declarations.get(key)!;
+    described.set(key, { ...dependency, declared: entry, kind });
+  }
+
+  return { byKey: described, namespaces };
 }
 
 /**
@@ -592,24 +666,105 @@ function siblingState(
 function resolveIndexDependencies(
   declared: DeclaredDependencies,
   siblings: SiblingState
-): Record<string, IndexDependency> | undefined {
+): Record<string, IndexDependency> {
   const resolved: Record<string, IndexDependency> = {};
 
   for (const [key, dependency] of declared.byKey) {
-    if (dependency.kind === "remote") {
-      resolved[key] = { repo: dependency.repo, range: dependency.range };
+    const how = { declared: dependency.declared, kind: dependency.kind };
+    if (dependency.where === "remote") {
+      resolved[key] = { repo: dependency.repo, range: dependency.range, ...how };
       continue;
     }
     if (dependency.range === undefined) {
       const settled = siblings.settled.get(key);
-      resolved[key] = settled === undefined ? { range: "*" } : { version: settled };
+      resolved[key] = {
+        ...(settled === undefined ? { range: "*" } : { version: settled }),
+        ...how,
+      };
       continue;
     }
     const best = semver.maxSatisfying(siblings.published.get(key) ?? [], dependency.range);
-    resolved[key] = best === null ? { range: dependency.range } : { version: best };
+    resolved[key] = {
+      ...(best === null ? { range: dependency.range } : { version: best }),
+      ...how,
+    };
+  }
+
+  return resolved;
+}
+
+/**
+ * Everything a version records about itself beyond its hash, tag and date: its
+ * dependencies, resolved and each with the entry that declared it, its
+ * manifest's `depends` and `subscribes` lists as written, and the variable
+ * definitions its manifest publishes. All are recorded even when empty, so a
+ * reader can tell "none" from "not recorded".
+ *
+ * @param recipe - The recipe, with the manifest of the version being recorded.
+ * @param declared - What that manifest declares.
+ * @param siblings - What each recipe here is published at, for this resolution.
+ */
+function describeVersion(
+  recipe: ValidatedRecipe,
+  declared: DeclaredDependencies,
+  siblings: SiblingState
+): VersionDescription {
+  return {
+    dependencies: resolveIndexDependencies(declared, siblings),
+    depends: (recipe.manifest.depends ?? []).map((written) => written.trim()),
+    subscribes: (recipe.manifest.subscribes ?? []).map((written) => written.trim()),
+    variables: recipe.manifest.variables ?? [],
+  };
+}
+
+/** What `describeVersion` records about a version. */
+type VersionDescription = Pick<
+  IndexVersion,
+  "dependencies" | "depends" | "subscribes" | "variables"
+>;
+
+/**
+ * Checks the manifest lists the index records for an already published
+ * version against the version's manifest. They are copied, not resolved, so
+ * any difference means the index was edited.
+ *
+ * @param key - The recipe's key, `namespace/recipe`.
+ * @param version - The published version.
+ * @param published - The version's index entry.
+ * @param recipe - The recipe, with the version's manifest.
+ */
+function checkRecordedLists(
+  key: string,
+  version: string,
+  published: IndexVersion,
+  recipe: ValidatedRecipe
+): ValidationProblem[] {
+  const differences: string[] = [];
+  for (const list of ["depends", "subscribes"] as const) {
+    const recorded = published[list];
+    if (recorded === undefined) continue;
+    const declared = (recipe.manifest[list] ?? []).map((written) => written.trim());
+    if (JSON.stringify(recorded) === JSON.stringify(declared)) continue;
+    differences.push(
+      `'${list}': the index records [${recorded.join(", ")}], and the manifest declares ` +
+        `[${declared.join(", ")}]`
+    );
   }
 
-  return Object.keys(resolved).length === 0 ? undefined : resolved;
+  if (differences.length === 0) return [];
+  return [
+    {
+      level: "error",
+      where: `${INDEX_FILENAME} recipes['${key}'].versions['${version}']`,
+      message:
+        `version ${version} of '${key}' is already published, and the lists the index ` +
+        `records for it disagree with its manifest:\n` +
+        differences.map((line) => `    - ${line}\n`).join("") +
+        `  A published version never changes. If the index was edited, restore the entry; ` +
+        `to publish different lists, bump the version in this manifest, or with ` +
+        `'sous repo release --bump patch'.`,
+    },
+  ];
 }
 
 /**
@@ -643,7 +798,7 @@ function checkRecordedDependencies(
   for (const [name, dependency] of declared.byKey) {
     const entry = entries[name];
     if (entry === undefined) {
-      if (dependency.kind === "remote" || dependency.named) {
+      if (dependency.where === "remote" || dependency.named) {
         differences.push(
           `'${name}': the manifest declares ${describeDeclared(dependency)}, and the index ` +
             `records nothing for it`
@@ -663,7 +818,7 @@ function checkRecordedDependencies(
     if (declared.byKey.has(name)) continue;
     // A recipe the declared namespace held when the version was published, and
     // no longer does, is history rather than a disagreement.
-    const namespace = name.slice(0, name.indexOf("/"));
+    const namespace = namespaceOfKey(name);
     if (entry.repo === undefined && declared.namespaces.has(namespace)) continue;
     differences.push(
       `'${name}': the index records ${describeRecorded(entry)}, and the manifest does not ` +
@@ -690,7 +845,11 @@ function checkRecordedDependencies(
 
 /** True when a recorded dependency honours what the manifest declares for it. */
 function recordedSatisfies(entry: IndexDependency, dependency: DeclaredDependency): boolean {
-  if (dependency.kind === "remote") {
+  // How it was declared is recorded only since sous described recipes in the
+  // index; an entry that records it has to agree with the manifest too.
+  if (entry.declared !== undefined && entry.declared !== dependency.declared) return false;
+  if (entry.kind !== undefined && entry.kind !== dependency.kind) return false;
+  if (dependency.where === "remote") {
     return (
       entry.repo === dependency.repo &&
       entry.range === dependency.range &&
@@ -707,23 +866,34 @@ function recordedSatisfies(entry: IndexDependency, dependency: DeclaredDependenc
 function describeRecorded(entry: IndexDependency): string {
   const what =
     entry.version !== undefined ? `version ${entry.version}` : `the range '${entry.range}'`;
-  return entry.repo === undefined ? what : `${what} from ${entry.repo}`;
+  const from = entry.repo === undefined ? what : `${what} from ${entry.repo}`;
+  return entry.declared === undefined || entry.kind === undefined
+    ? from
+    : `${from}, through the entry '${entry.declared}' as a ${describeDependencyKind(entry.kind)}`;
 }
 
 /** Describes a declared dependency the way an author would say it. */
 function describeDeclared(dependency: DeclaredDependency): string {
-  if (dependency.kind === "remote") {
-    return `the range '${dependency.range}' from ${dependency.repo}`;
+  const how =
+    `, through the entry '${dependency.declared}' as a ` +
+    describeDependencyKind(dependency.kind);
+  if (dependency.where === "remote") {
+    return `the range '${dependency.range}' from ${dependency.repo}${how}`;
   }
-  return dependency.range === undefined ? "it with no range" : `the range '${dependency.range}'`;
+  return dependency.range === undefined
+    ? `it with no range${how}`
+    : `the range '${dependency.range}'${how}`;
 }
 
 /** What rebuilding one tagged version from its tag produced. */
 type RebuiltVersion = {
   /** The content hash of the recipe folder at the tag. */
   hash: string;
-  /** The dependencies it was released against, when they could be worked out. */
-  dependencies?: Record<string, IndexDependency>;
+  /**
+   * Its dependencies and variable definitions when the recipe could be read at
+   * the tag, and nothing when it could not; see `describeVersion`.
+   */
+  description: VersionDescription;
   /** A warning when they could not. */
   problems: ValidationProblem[];
 };
@@ -741,6 +911,7 @@ type RebuiltVersion = {
  * @param tagsByKey - Every release tag, grouped by recipe.
  * @param existing - The committed index, when there is one.
  * @param run - The command runner git calls go through.
+ * @param settled - The dependencies that read more than one way, as the release settled them.
  */
 async function rebuildTaggedVersion(
   rootDir: string,
@@ -748,7 +919,8 @@ async function rebuildTaggedVersion(
   recipe: ValidatedRecipe,
   tagsByKey: Map<string, RecipeTag[]>,
   existing: IndexFile | undefined,
-  run: RunOptions["run"]
+  run: RunOptions["run"],
+  settled?: Map<string, SettledDependency>
 ): Promise<RebuiltVersion> {
   return withTaggedTree(
     rootDir,
@@ -762,11 +934,12 @@ async function rebuildTaggedVersion(
         const snapshot = validateRepo(treeDir);
         const tagged = snapshot.recipes.find((entry) => entry.key === recipe.key);
         if (tagged !== undefined) {
-          const dependencies = resolveIndexDependencies(
-            declaredDependencies(tagged, snapshot),
+          const description = describeVersion(
+            tagged,
+            declaredDependencies(tagged, snapshot, settled),
             siblingState(snapshot, tagsByKey, existing)
           );
-          return { hash, ...(dependencies === undefined ? {} : { dependencies }), problems: [] };
+          return { hash, description, problems: [] };
         }
         reason = `The repository manifest at that tag does not list '${recipe.key}'.`;
       } catch (error) {
@@ -775,6 +948,7 @@ async function rebuildTaggedVersion(
 
       return {
         hash,
+        description: {},
         problems: [
           {
             level: "warning",

package/src/lib/repos/release/index.ts

@@ -11,6 +11,7 @@ export * from "./validate.js";
 export * from "./tags.js";
 export * from "./git-state.js";
 export * from "./index-builder.js";
+export * from "./settle.js";
 export * from "./plan.js";
 export * from "./bump.js";
 export * from "./submit-service.js";