@sous-io/sous 0.2.28 → 0.2.30

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

@@ -56,20 +56,33 @@ import {
   type LockedRecipe,
   type Lockfile,
 } from "./formats/lockfile.js";
-import type { RecipeManifest } from "./formats/recipe-manifest.js";
-import { formatRef, parseRef, refKey, type ParsedRef } from "./ref.js";
+import type { RecipeManifest, VariableDefinition } from "./formats/recipe-manifest.js";
 import {
+  RefSource,
+  Qualification,
   SousScope,
+  formatRef,
+  isNamedReading,
+  matchNames,
+  namespaceOfKey,
+  parseRef,
+  parseShortRef,
+  refKey,
+  splitRecipeKey,
+  type ParsedRef,
+  type RefReading,
   describeReference,
   findReference,
   pickReference,
   referenceReposFromIndexes,
   referenceToRef,
   type ReferenceMatch,
+  type ReferenceRepo,
 } from "../refs/index.js";
 import { describeIndexSearch } from "./ref-search.js";
 import {
   PROJECT_REQUESTER,
+  proposeRepoName,
   resolveRefs,
   type MissingRepo,
   type RefRequest,
@@ -279,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. */
@@ -290,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. */
@@ -639,6 +674,26 @@ export class SubscriptionService {
     return identity === undefined ? undefined : this.indexCache.readCached(identity);
   }
 
+  /**
+   * Every trusted repository as a reference searches it, read from the cached
+   * indexes alone: what it publishes, where each recipe lives, and its
+   * canonical identity, so a reference written as a location finds it whatever
+   * this project calls it. A repository whose index has never been fetched can
+   * still be named, just not searched inside.
+   */
+  cachedReferenceRepos(): ReferenceRepo[] {
+    const repos = this.resolverRepos();
+    return Object.keys(repos).map((name) => {
+      const { url, identity } = repos[name]!;
+      const index = this.cachedIndex(name);
+      const base =
+        index === undefined
+          ? { name, url, namespaces: [], recipes: [] }
+          : referenceReposFromIndexes([name], new Map([[name, index]]), { [name]: url })[0]!;
+      return { ...base, identity };
+    });
+  }
+
   // --- Repository identity ----------------------------------------------------------------------
 
   /**
@@ -796,27 +851,30 @@ export class SubscriptionService {
    * @param options - The ref, the prerelease and always-pull flags, and the trust flag.
    */
   async subscribe(options: SubscribeOptions): Promise<SubscribeOutcome> {
-    const written = parseRef(options.ref);
     const dryRun = options.dryRun === true;
 
-    // A one-word ref is a guess at a name, and the guess is settled here, from
-    // the cached indexes alone. Everything after this point works with a fully
-    // qualified ref, so what is confirmed is exactly what is installed.
-    const parsed = await this.resolveBareRef(written, options);
+    // What the ref names is settled here, from the cached indexes alone: a
+    // one-word ref is a guess at a name, and a location is matched against the
+    // repository at that location (trusted first, when it is not yet). Every
+    // step after this works with a fully qualified ref, so what is confirmed
+    // is exactly what is installed.
+    const { parsed, trusted: trustedForRef } = await this.resolveWrittenRef(options.ref, options);
     const key = refKey(parsed);
 
     // The last gate before anything is fetched or written: what this will do to
     // the project, in plain sentences, and a question.
     await this.confirmSubscription(parsed, options);
 
-    const { resolved, trusted, cycles } = await this.resolveClosure(parsed, options);
+    const closure = await this.resolveClosure(parsed, options);
+    const { resolved, cycles } = closure;
+    const trusted = [...trustedForRef, ...closure.trusted];
 
     const before = this.lock.read();
     const after = this.lock.applyResolution(before, resolved, this.lockRepoInputs());
     const diff = this.lock.diff(before, after);
 
     const resolvedFrom =
-      formatRef(written) === formatRef(parsed) ? {} : { resolvedFrom: formatRef(written) };
+      options.ref.trim() === formatRef(parsed) ? {} : { resolvedFrom: options.ref.trim() };
 
     if (dryRun) {
       // The questions are planned even here, so `--dry-run` is the command an
@@ -881,6 +939,161 @@ export class SubscriptionService {
 
   // --- Working out what a one-word ref meant -----------------------------------------------------
 
+  /**
+   * Settles what a ref typed on the command line names, in any form it was
+   * written: a short ref goes through `resolveBareRef`; a location (a URL, an
+   * SSH remote, a provider-scheme locator, a browser URL) is matched against
+   * the trusted repository at that location and settled through its index.
+   * When no reading's repository is trusted yet, the trust ceremony runs for
+   * it first, exactly as it runs for a dependency's repository, and nothing is
+   * fetched from it before the answer.
+   *
+   * @param written - The ref exactly as the user wrote it.
+   * @param options - The trust and accept-first flags.
+   * @returns The fully qualified ref, and any repository trusted to settle it.
+   */
+  private async resolveWrittenRef(
+    written: string,
+    options: SubscribeOptions
+  ): Promise<{ parsed: ParsedRef; trusted: string[] }> {
+    const readings = parseRef(written, RefSource.CommandLine, this.providers);
+    const first = readings[0]!;
+    if (first.location === undefined && isNamedReading(first)) {
+      return { parsed: await this.resolveBareRef(first, options), trusted: [] };
+    }
+
+    const trusted = await this.trustLocation(written, readings, options);
+    const chosen = await this.pickLocated(written, options.acceptFirst);
+    const range = "range" in first ? first.range : undefined;
+    return {
+      parsed: referenceToRef(chosen, {
+        namespace: chosen.namespace!,
+        ...(range === undefined ? {} : { range }),
+      }),
+      trusted,
+    };
+  }
+
+  /**
+   * The one namespace or recipe a location names among the trusted
+   * repositories, settled through their cached indexes and chosen between the
+   * way every reference is.
+   *
+   * @param written - The location as written.
+   * @param acceptFirst - Whether `--accept-first` was passed.
+   */
+  private async pickLocated(written: string, acceptFirst?: boolean): Promise<ReferenceMatch> {
+    const repoOrder = this.repoSearchOrder();
+    const indexes = await this.loadIndexes(repoOrder);
+    this.indexesSnapshot = indexes;
+
+    const matches = findReference(
+      written,
+      [SousScope.Namespace, SousScope.Recipe],
+      { repos: this.referenceRepos(repoOrder, indexes) }
+    );
+
+    return pickReference(matches, {
+      search: written.trim(),
+      interactive: this.interactive,
+      ...(acceptFirst === undefined ? {} : { acceptFirst }),
+      details: [
+        `  The repository at that location is trusted, but its index publishes no namespace ` +
+          `or recipe there.`,
+        `  Run 'sous repo list --latest' to read what it publishes now.`,
+      ],
+      write: (message: string) => this.write(message),
+      choose: (message, offered) => this.choose(message, offered),
+    });
+  }
+
+  /**
+   * The trusted repositories as a reference searches them, each carrying its
+   * canonical identity so a location finds it whatever this project calls it.
+   *
+   * @param repoOrder - The repositories, in search order.
+   * @param indexes - Their indexes.
+   */
+  private referenceRepos(repoOrder: string[], indexes: Map<string, IndexFile>) {
+    const repos = this.resolverRepos();
+    const urls: Record<string, string | undefined> = {};
+    for (const name of repoOrder) urls[name] = repos[name]?.url;
+    return referenceReposFromIndexes(repoOrder, indexes, urls).map((repo) => ({
+      ...repo,
+      ...(repos[repo.name] === undefined ? {} : { identity: repos[repo.name]!.identity }),
+    }));
+  }
+
+  /**
+   * Makes sure the repository a located ref names is trusted: nothing happens
+   * when any reading's repository already is. Otherwise the one repository the
+   * location names goes through the trust ceremony; a location that reads as
+   * several repositories (a GitLab URL with nested groups) is first a question
+   * of which one, since nothing may be fetched from a repository to find out
+   * before it is trusted.
+   *
+   * @param written - The location as written.
+   * @param readings - Every reading of it.
+   * @param options - The trust and accept-first flags.
+   * @returns The short names of the repositories trusted here.
+   */
+  private async trustLocation(
+    written: string,
+    readings: RefReading[],
+    options: SubscribeOptions
+  ): Promise<string[]> {
+    const repos = this.resolverRepos();
+    const known = new Set(Object.values(repos).map((repo) => repo.identity));
+    const located = readings.filter((reading) => reading.location !== undefined);
+    if (located.some((reading) => known.has(reading.location!.identity))) return [];
+
+    let chosen = located[0]!;
+    const identities = new Set(located.map((reading) => reading.location!.identity));
+    if (identities.size > 1) {
+      const offered: ReferenceMatch[] = located.map((reading) => ({
+        scope:
+          isNamedReading(reading) && reading.recipe !== undefined
+            ? SousScope.Recipe
+            : SousScope.Namespace,
+        key: formatRef(reading, this.providers),
+        label: formatRef(reading, this.providers),
+        repo: reading.location!.url,
+        ...(isNamedReading(reading) ? { namespace: reading.namespace } : {}),
+        ...(isNamedReading(reading) && reading.recipe !== undefined
+          ? { recipe: reading.recipe }
+          : {}),
+        qualification: Qualification.Full,
+      }));
+      const picked = await pickReference(offered, {
+        search: written.trim(),
+        interactive: this.interactive,
+        ...(options.acceptFirst === undefined ? {} : { acceptFirst: options.acceptFirst }),
+        prompt: `'${written.trim()}' can be read as more than one repository. Which one?`,
+        write: (message: string) => this.write(message),
+        choose: (message, list) => this.choose(message, list),
+      });
+      chosen = located[offered.indexOf(picked)]!;
+    }
+
+    const location = chosen.location!;
+    const outcome = await this.trust.confirmTrust(
+      [
+        {
+          name: proposeRepoName(repos, location.identity),
+          url: location.url,
+          identity: location.identity,
+          provider: location.provider,
+          requiredBy: [{ ref: written.trim(), requestedBy: PROJECT_REQUESTER }],
+        },
+      ],
+      {
+        interactive: this.interactive,
+        ...(options.trust === undefined ? {} : { trustFlag: options.trust }),
+      }
+    );
+    return outcome.added;
+  }
+
   /**
    * Settles what a ref names, reading nothing but the cached indexes.
    *
@@ -898,33 +1111,39 @@ export class SubscriptionService {
     written: ParsedRef,
     options: SubscribeOptions
   ): Promise<ParsedRef> {
-    if (written.recipe !== undefined) return written;
-
-    const repoOrder = this.repoSearchOrder(written.repo);
+    // A ref that names a recipe, spelled as it is published, says what it
+    // names already. One word, or a spelling in another case, is searched.
+    const search =
+      written.repo === undefined ? refKey(written) : `${written.repo}:${refKey(written)}`;
+    if (written.recipe !== undefined && refKey(written) === refKey(written).toLowerCase()) {
+      return written;
+    }
+
+    const qualifier =
+      written.repo === undefined
+        ? undefined
+        : (matchNames(written.repo, Object.keys(this.currentRepos()))[0] ?? written.repo);
+    const repoOrder = this.repoSearchOrder(qualifier);
     const indexes = await this.loadIndexes(repoOrder);
     if (written.repo === undefined) this.indexesSnapshot = indexes;
 
     const context = { repos: referenceReposFromIndexes(repoOrder, indexes) };
-    const matches = findReference(
-      written.namespace,
-      [SousScope.Namespace, SousScope.Recipe],
-      context
-    );
+    const matches = findReference(search, [SousScope.Namespace, SousScope.Recipe], context);
 
     if (matches.length === 0) {
       throw new ConfigError(
         [
-          `Nothing called '${written.namespace}' was found: no namespace has that name, ` +
+          `Nothing called '${refKey(written)}' was found: no namespace has that name, ` +
             `and no recipe does either.`,
-          ...describeIndexSearch({ name: written.namespace, repoOrder, indexes }),
-          `  Run 'sous repo search ${written.namespace}' to look for something like it, or ` +
+          ...describeIndexSearch({ name: refKey(written), repoOrder, indexes }),
+          `  Run 'sous repo search ${refKey(written)}' to look for something like it, or ` +
             `'sous repo add <url>' to add the repository that publishes it.`,
         ].join("\n")
       );
     }
 
     const chosen = await pickReference(matches, {
-      search: written.namespace,
+      search,
       interactive: this.interactive,
       ...(options.acceptFirst === undefined ? {} : { acceptFirst: options.acceptFirst }),
       write: (message: string) => this.write(message),
@@ -1272,6 +1491,26 @@ export class SubscriptionService {
     }
   }
 
+  /**
+   * The subscription key a ref typed on the command line names. A short ref
+   * names its own key, matched against the keys in force exactly first and then
+   * ignoring case; a location is settled through the trusted repository at that
+   * location, the way `subscribe` settles one.
+   *
+   * @param written - The ref as typed.
+   * @param keys - The subscription keys in force.
+   */
+  private async subscriptionKeyFor(written: string, keys: string[]): Promise<string> {
+    const readings = parseRef(written, RefSource.CommandLine, this.providers);
+    const first = readings[0]!;
+    if (first.location === undefined && isNamedReading(first)) {
+      const key = refKey(first);
+      return matchNames(key, new Set(keys))[0] ?? key;
+    }
+    const chosen = await this.pickLocated(written);
+    return refKey(referenceToRef(chosen, { namespace: chosen.namespace! }));
+  }
+
   /**
    * Removes one subscription and everything that was only there because of it.
    * Removal is refcounted: a recipe another subscription (or another recipe)
@@ -1280,12 +1519,14 @@ export class SubscriptionService {
    * @param options - The ref to unsubscribe from.
    */
   async unsubscribe(options: UnsubscribeOptions): Promise<UnsubscribeOutcome> {
-    const parsed = parseRef(options.ref);
-    const key = refKey(parsed);
     const dryRun = options.dryRun === true;
 
     const managed = this.readSubscriptionEntries();
     const configured = enabledSubscriptions(this.settings);
+    const key = await this.subscriptionKeyFor(options.ref, [
+      ...Object.keys(managed),
+      ...Object.keys(configured),
+    ]);
     const before = this.lock.read();
     const held = this.keysHeldBySubscription(before, key);
 
@@ -1521,7 +1762,7 @@ export class SubscriptionService {
     for (const key of Object.keys(subscriptions).sort()) {
       let qualifier: string | undefined;
       try {
-        qualifier = parseRef(key).repo;
+        qualifier = parseShortRef(key, RefSource.Config).repo;
       } catch {
         // A ref that does not parse cannot name this repository, and reporting
         // it here would bury the removal under an unrelated complaint.
@@ -1974,7 +2215,7 @@ export class SubscriptionService {
       const entry = subscriptions[key]!;
       let request: RefRequest;
       try {
-        const parsed = parseRef(key);
+        const parsed = parseShortRef(key, RefSource.Config);
         request = {
           ref: { ...parsed, ...(entry.range === undefined ? {} : { range: entry.range }) },
           requestedBy: PROJECT_REQUESTER,
@@ -2082,7 +2323,7 @@ export class SubscriptionService {
 
     let parsed: ParsedRef;
     try {
-      parsed = parseRef(key);
+      parsed = parseShortRef(key, RefSource.Config);
     } catch {
       return false;
     }
@@ -2127,7 +2368,7 @@ export class SubscriptionService {
   ): Lockfile {
     const coverOf = (key: string): string | undefined => {
       try {
-        return refKey(parseRef(key));
+        return refKey(parseShortRef(key, RefSource.Config));
       } catch {
         return undefined;
       }
@@ -2217,7 +2458,7 @@ export class SubscriptionService {
         if (scope.kind === "all") return true;
         let parsed: ParsedRef;
         try {
-          parsed = parseRef(key);
+          parsed = parseShortRef(key, RefSource.Config);
         } catch {
           return false;
         }
@@ -2311,7 +2552,7 @@ export class SubscriptionService {
       if (entry.repo !== repoName) continue;
       const range = this.effectiveRangeFor(key, entry, subscriptions);
       if (range === undefined) continue;
-      const subscription = subscriptions[key] ?? subscriptions[key.split("/")[0]!];
+      const subscription = subscriptions[key] ?? subscriptions[namespaceOfKey(key)];
 
       const found = findNewerInRange({
         index,
@@ -2403,7 +2644,7 @@ export class SubscriptionService {
 
       let parsed: ParsedRef;
       try {
-        parsed = parseRef(key);
+        parsed = parseShortRef(key, RefSource.Config);
       } catch (error) {
         report.failed.push({ key, reason: describeError(error) });
         continue;
@@ -2670,7 +2911,7 @@ export class SubscriptionService {
 
       for (const [key, entry] of Object.entries(recipes)) {
         if (entry.repo !== repoName) continue;
-        const subscription = subscriptions[key] ?? subscriptions[key.split("/")[0]!];
+        const subscription = subscriptions[key] ?? subscriptions[namespaceOfKey(key)];
 
         // Always-pull re-resolves WITHIN what was declared; it never widens it.
         // A recipe held only through another recipe's `depends` has no
@@ -3062,11 +3303,11 @@ export class SubscriptionService {
     const provider = requireProvider(request.url, request.providerId, this.providers);
     const canonical = provider.canonicalize(request.url);
 
-    const namespace = request.key.slice(0, request.key.indexOf("/"));
+    const { namespace, name } = splitRecipeKey(request.key);
     const key: StoreKey = {
       identity: request.identity,
       namespace,
-      name: request.key.slice(namespace.length + 1),
+      name,
       version: request.version,
     };
 
@@ -3231,7 +3472,7 @@ export class SubscriptionService {
     entry: LockedRecipe,
     subscriptions: Record<string, SubscriptionEntry>
   ): string | undefined {
-    const namespace = key.split("/")[0]!;
+    const namespace = namespaceOfKey(key);
     return effectiveRangeForHolders(key, entry.requestedBy, {
       subscriptionRange: (held) => {
         // A subscription the config no longer declares is not a hold sous can
@@ -3270,15 +3511,20 @@ export class SubscriptionService {
     if (manifest === undefined) return undefined;
 
     for (const dependency of manifest.depends ?? []) {
-      let parsed: ParsedRef;
+      // Every reading counts: a dependency that reads more than one way still
+      // declares its range for whichever reading the lockfile settled on.
+      let readings: RefReading[];
       try {
-        parsed = parseRef(dependency);
+        readings = parseRef(dependency, RefSource.Manifest, this.providers);
       } catch {
         continue;
       }
-      const dependencyKey = refKey(parsed);
-      if (dependencyKey !== key && dependencyKey !== namespace) continue;
-      return parsed.range ?? "*";
+      for (const reading of readings) {
+        if (!isNamedReading(reading)) continue;
+        const dependencyKey = refKey(reading);
+        if (dependencyKey !== key && dependencyKey !== namespace) continue;
+        return reading.range ?? "*";
+      }
     }
 
     return undefined;
@@ -3305,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.
    */
@@ -3357,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 });
       }
     }
@@ -3380,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({

package/src/lib/repos/update-plan.ts

@@ -31,7 +31,7 @@ export type UpdatePlanFacts = {
   missingRepos: MissingRepo[];
   /** The questions the new versions ask that nothing answers yet. */
   questions: PlannedVariable[];
-  /** Recipes whose files are not on this machine, so their questions are unknown. */
+  /** Recipes whose files are not on this machine and whose index does not record their questions. */
   unreadable: string[];
   /** Repositories whose index could not be fetched, so their pins stay where they are. */
   unreachable: Array<{ repo: string; reason: string }>;
@@ -153,7 +153,8 @@ export function formatUpdatePlan(
   if (facts.unreadable.length > 0) {
     notes.push(
       `A dry run downloads no recipe, so the dependencies of the versions not on this ` +
-        `machine yet are not shown: ${facts.unreadable.join(", ")}.`
+        `machine yet, and not described by their index, are not shown: ` +
+        `${facts.unreadable.join(", ")}.`
     );
   }
   for (const entry of facts.unreachable) {