@sous-io/sous 0.2.29 → 0.2.31

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,6 +67,14 @@ import {
   type ValidatedRecipe,
   type ValidationProblem,
 } from "./validate.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";
@@ -204,7 +219,7 @@ export async function buildIndex(
         tag: tag.tag,
         prerelease: semver.prerelease(tag.version) !== null,
         ...(await releasedAtOf(rootDir, tag.tag, run)),
-        ...(rebuilt.dependencies === undefined ? {} : { dependencies: rebuilt.dependencies }),
+        ...rebuilt.description,
       };
     }
 
@@ -265,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.
 
@@ -294,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),
         };
       }
 
@@ -435,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. */
@@ -446,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;
       /**
@@ -458,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. */
@@ -487,31 +507,40 @@ function declaredDependencies(
   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) {
+  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, { kind: "remote", repo: answer.identity, range: answer.range ?? "*" });
+        byKey.set(key, { where: "remote", repo: answer.identity, range: answer.range ?? "*" });
+        cover(key, { written, kind, named: answer.keys.length === 1 });
       }
       continue;
     }
@@ -533,16 +562,18 @@ function declaredDependencies(
       // own index by the consumer; only a recipe has a key to record.
       if (parsed.recipe !== undefined) {
         byKey.set(refKey(parsed), {
-          kind: "remote",
+          where: "remote",
           repo: parsed.location.identity,
           range: parsed.range ?? "*",
         });
+        cover(refKey(parsed), { written, kind, named: true });
       }
       continue;
     }
 
     if (parsed.recipe !== undefined) {
       addSibling(refKey(parsed), parsed.range, true);
+      cover(refKey(parsed), { written, kind, named: true });
       continue;
     }
 
@@ -552,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 };
 }
 
 /**
@@ -628,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 Object.keys(resolved).length === 0 ? undefined : resolved;
+  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(", ")}]`
+    );
+  }
+
+  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'.`,
+    },
+  ];
 }
 
 /**
@@ -679,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`
@@ -726,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 &&
@@ -743,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[];
 };
@@ -800,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(
+          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) {
@@ -813,6 +948,7 @@ async function rebuildTaggedVersion(
 
       return {
         hash,
+        description: {},
         problems: [
           {
             level: "warning",

package/src/lib/repos/resolver.ts

@@ -13,7 +13,10 @@
  * project) and `subscribes` (co-subscribed with full semantics), and those refs
  * resolve the same way. The manifest lives inside the recipe's own files, so
  * the caller supplies a loader; that is also the seam where a caller decides
- * whether it is willing to fetch anything at this point.
+ * whether it is willing to fetch anything at this point. When the loader has no
+ * manifest to give, the lists are read from the version's index entry instead,
+ * which records the entry that declared each dependency; only a version whose
+ * entry predates that record goes unwalked.
  *
  * Two things the resolver deliberately does NOT do: it never downloads
  * anything, and it never resolves against a repository the project has not
@@ -25,7 +28,8 @@ import semver from "semver";
 import { ConfigError } from "../errors.js";
 import type { IndexFile } from "./formats/index-file.js";
 import type { LockKind } from "./formats/lockfile.js";
-import type { RecipeManifest } from "./formats/recipe-manifest.js";
+import type { RecipeManifest, VariableDefinition } from "./formats/recipe-manifest.js";
+import { indexDependencyLists, type DependencyLists } from "./declarations.js";
 import {
   formatRef,
   isBrowsedReading,
@@ -81,8 +85,9 @@ export type ResolverRepo = {
 
 /**
  * Loads a resolved recipe's manifest, which is what names its dependencies.
- * Returning undefined means "not available", and the recipe is reported under
- * `missingManifests` rather than having its dependencies walked.
+ * Returning undefined means "not available": the recipe's dependencies are then
+ * read from its index entry, and when that does not record them either, it is
+ * reported under `missingManifests` rather than having its dependencies walked.
  */
 export type RecipeManifestLoader = (
   recipe: ResolvedRecipe
@@ -141,6 +146,17 @@ export type ResolvedRecipe = {
    * published against rather than at whatever its range would reach today.
    */
   dependencies?: Record<string, IndexDependency>;
+  /**
+   * The variable definitions the index records for this exact version, when it
+   * records them: the questions it asks, known before its files are fetched.
+   */
+  variables?: VariableDefinition[];
+  /**
+   * The manifest `depends` and `subscribes` lists the index records for this
+   * exact version, when it records them, so the recipe can be walked before its
+   * files are fetched.
+   */
+  declares?: DependencyLists;
 };
 
 /** A repository something needs that the project has not added. */
@@ -166,7 +182,10 @@ export type ResolveResult = {
   resolved: ResolvedRecipe[];
   /** Repositories a dependency needs that the project has not added. */
   missingRepos: MissingRepo[];
-  /** Resolved recipes whose manifest the loader could not produce. */
+  /**
+   * Resolved recipes whose dependencies could not be read: the loader produced
+   * no manifest, and the index entry does not record them.
+   */
   missingManifests: string[];
   /** Any dependency cycle found, as the chain of recipe keys forming it. */
   cycles: string[][];
@@ -495,15 +514,15 @@ export async function resolveRefs(
     }
     walked.set(recipe.key, recipe.version);
 
-    const manifest = await context.loadManifest(recipe);
-    if (manifest === undefined) {
+    const lists = dependencyListsOf(recipe, await context.loadManifest(recipe));
+    if (lists === undefined) {
       missingManifests.add(recipe.key);
       continue;
     }
 
     for (const [kind, refs] of [
-      ["depends", manifest.depends ?? []],
-      ["subscribes", manifest.subscribes ?? []],
+      ["depends", lists.depends],
+      ["subscribes", lists.subscribes],
     ] as Array<[LockKind, string[]]>) {
       for (const written of refs) {
         queue.push(dependencyRequest(written, recipe, kind, context));
@@ -593,8 +612,9 @@ async function keepOnlyReachable(
     } catch {
       manifest = undefined;
     }
+    const lists = dependencyListsOf(recipe, manifest);
 
-    if (manifest === undefined) {
+    if (lists === undefined) {
       // An unreadable manifest is already reported as a missing manifest. Keep
       // everything this recipe held rather than dropping a dependency over it.
       for (const other of resolved.values()) {
@@ -606,8 +626,8 @@ async function keepOnlyReachable(
     }
 
     for (const [kind, refs] of [
-      ["depends", manifest.depends ?? []],
-      ["subscribes", manifest.subscribes ?? []],
+      ["depends", lists.depends],
+      ["subscribes", lists.subscribes],
     ] as Array<[LockKind, string[]]>) {
       for (const written of refs) {
         for (const target of dependencyTargets(written, recipe, context, resolved)) {
@@ -663,6 +683,24 @@ function dependencyTargets(
     : [refKey(item.ref)];
 }
 
+/**
+ * What a resolved recipe declares under `depends` and `subscribes`: its
+ * manifest's lists when the manifest could be read, and otherwise the lists its
+ * index entry records, or undefined when neither says.
+ *
+ * @param recipe - The resolved recipe, carrying the lists its index entry records.
+ * @param manifest - Its manifest, when the loader produced one.
+ */
+function dependencyListsOf(
+  recipe: ResolvedRecipe,
+  manifest: RecipeManifest | undefined
+): DependencyLists | undefined {
+  if (manifest !== undefined) {
+    return { depends: manifest.depends ?? [], subscribes: manifest.subscribes ?? [] };
+  }
+  return recipe.declares;
+}
+
 /** Records one more reason a repository is needed. */
 function recordMissingRepo(into: Map<string, MissingRepo>, missing: MissingRepo): void {
   const existing = into.get(missing.name);
@@ -775,6 +813,7 @@ function resolveRecipeRef(
 
   const version = pickVersion(key, entry, ranges, prerelease, context.keep?.[key]);
   const versionEntry = entry.versions[version]!;
+  const declares = indexDependencyLists(versionEntry);
 
   const requestedBy = [...(previous?.requestedBy ?? [])];
   if (!requestedBy.includes(item.requestedBy)) requestedBy.push(item.requestedBy);
@@ -793,6 +832,8 @@ function resolveRecipeRef(
     ...(versionEntry.dependencies === undefined
       ? {}
       : { dependencies: versionEntry.dependencies }),
+    ...(versionEntry.variables === undefined ? {} : { variables: versionEntry.variables }),
+    ...(declares === undefined ? {} : { declares }),
     // A recipe held as a co-subscription by anyone is a co-subscription; a
     // build dependency only stays one while nothing subscribes to it.
     kind: previous?.kind === "subscribes" || item.kind === "subscribes" ? "subscribes" : "depends",

package/src/lib/repos/subscription-service.ts

@@ -56,7 +56,7 @@ import {
   type LockedRecipe,
   type Lockfile,
 } from "./formats/lockfile.js";
-import type { RecipeManifest } from "./formats/recipe-manifest.js";
+import type { RecipeManifest, VariableDefinition } from "./formats/recipe-manifest.js";
 import {
   RefSource,
   Qualification,
@@ -292,9 +292,9 @@ export type SubscribeOutcome = {
    */
   questions?: PlannedVariable[];
   /**
-   * Recipes a dry run could not describe, because their files are not on this
-   * machine and a dry run downloads nothing. Their questions are unknown until
-   * they are installed.
+   * Recipes a dry run could not describe: their files are not on this machine,
+   * a dry run downloads nothing, and their repository's index does not record
+   * their questions. Their questions are unknown until they are installed.
    */
   unreadable?: string[];
   /** Dependency cycles the resolver noticed, reported rather than treated as fatal. */
@@ -303,6 +303,28 @@ export type SubscribeOutcome = {
   dryRun: boolean;
 };
 
+/** What `previewSubscription` is asked about. */
+export type PreviewSubscriptionOptions = {
+  /** The indexes to resolve against, keyed by short name; the cached ones by default. */
+  indexes?: Map<string, IndexFile>;
+  /** Whether prerelease versions may take part in range matching. */
+  prerelease?: boolean;
+};
+
+/** What subscribing to a ref would install and ask, worked out without changing anything. */
+export type SubscriptionPreview = {
+  /** Every recipe version the subscription would install, sorted by key. */
+  resolved: ResolvedRecipe[];
+  /** Repositories the closure needs that the project does not trust yet. */
+  missingRepos: MissingRepo[];
+  /** Every question the closure would ask, and where each answer would go. */
+  questions: PlannedVariable[];
+  /** Recipes whose questions cannot be listed; see `SubscribeOutcome.unreadable`. */
+  unreadable: string[];
+  /** Dependency cycles the resolver noticed. */
+  cycles: string[][];
+};
+
 /** What `unsubscribe` is asked to do. */
 export type UnsubscribeOptions = {
   /** The ref to unsubscribe from. */
@@ -3529,9 +3551,10 @@ export class SubscriptionService {
    * Every variable definition the resolved closure publishes, attributed to the
    * recipe that declared it and to the chain that pulled it in.
    *
-   * A recipe whose files are not on this machine contributes nothing rather
-   * than failing, which is what lets a dry run describe as much of the closure
-   * as it can without downloading any of it.
+   * A recipe whose files are not on this machine is described from the
+   * definitions its index entry records, and contributes nothing rather than
+   * failing when the entry records none, which is what lets a dry run describe
+   * as much of the closure as it can without downloading any of it.
    *
    * @param resolved - The recipe versions the resolution settled on.
    */
@@ -3581,12 +3604,12 @@ export class SubscriptionService {
     });
 
     for (const recipe of ordered) {
-      const manifest = readRecipeManifestIn(this.recipeDirectory(recipe));
-      if (manifest === undefined) continue;
+      const variables = this.publishedVariables(recipe);
+      if (variables === undefined) continue;
 
       const publisher = describe(recipe);
       const requiredBy = chainFor(recipe).map(describe);
-      for (const definition of manifest.variables ?? []) {
+      for (const definition of variables) {
         defined.push({ definition, recipe: publisher, requiredBy });
       }
     }
@@ -3604,11 +3627,70 @@ export class SubscriptionService {
    */
   private unreadableRecipes(resolved: ResolvedRecipe[]): string[] {
     return resolved
-      .filter((recipe) => readRecipeManifestIn(this.recipeDirectory(recipe)) === undefined)
+      .filter((recipe) => this.publishedVariables(recipe) === undefined)
       .map((recipe) => recipe.key)
       .sort();
   }
 
+  /**
+   * The variable definitions one resolved recipe publishes: from its manifest
+   * when its files are on this machine (a linked checkout's working copy
+   * included), otherwise from its index entry, or undefined when neither can
+   * say.
+   *
+   * @param recipe - The resolved recipe.
+   */
+  private publishedVariables(recipe: ResolvedRecipe): VariableDefinition[] | undefined {
+    const manifest = readRecipeManifestIn(this.recipeDirectory(recipe));
+    if (manifest !== undefined) return manifest.variables ?? [];
+    return recipe.variables;
+  }
+
+  /**
+   * Works out what subscribing to a ref would install and which questions it
+   * would ask, from the indexes and the files already on this machine. Nothing
+   * is fetched, trusted or written, which is what lets `sous recipe show`
+   * describe a recipe before anyone subscribes to it. A repository the closure
+   * needs and the project does not trust is reported, and its recipes are not
+   * resolved.
+   *
+   * @param parsed - The fully qualified ref, with the exact version to describe as its range.
+   * @param options - The indexes to read, and whether prereleases may match.
+   */
+  async previewSubscription(
+    parsed: ParsedRef,
+    options: PreviewSubscriptionOptions = {}
+  ): Promise<SubscriptionPreview> {
+    const repos = this.resolverRepos();
+    const indexes = options.indexes ?? (await this.loadIndexes(Object.keys(repos)));
+    const result = await resolveRefs(
+      [
+        {
+          ref: parsed,
+          requestedBy: PROJECT_REQUESTER,
+          kind: "subscribes",
+          ...(options.prerelease === true ? { prerelease: true } : {}),
+        },
+      ],
+      {
+        indexes,
+        repos,
+        loadManifest: (recipe) => this.loadRecipeManifest(recipe, true),
+        ...(options.prerelease === true ? { prerelease: true } : {}),
+      }
+    );
+
+    return {
+      resolved: result.resolved,
+      missingRepos: result.missingRepos,
+      questions: planQuestions(this.definedVariables(result.resolved), this.ladderContext(), {
+        sousDir: this.sousDir,
+      }),
+      unreadable: this.unreadableRecipes(result.resolved),
+      cycles: result.cycles,
+    };
+  }
+
   /** The environment layers and mapping records this project resolves against. */
   private ladderContext(): LadderContext {
     return loadLadderContext({