@sous-io/sous 0.2.28 → 0.2.30

package/src/commands/recipe/show.ts

@@ -2,27 +2,41 @@
  * `sous recipe show <ref>`.
  *
  * Shows one recipe in full: where it is published, every version it publishes,
- * what the version this project would use depends on, the questions it asks,
- * and where its files land in this project. It reads only what sous already has
- * on disk: the repository's cached index, the project's lockfile, and the
- * recipe's own files when they are in the store or a linked working copy.
- * `--latest` reads the repository's index from upstream instead, saving
- * nothing, and `--installed` looks the ref up among installed recipes only.
+ * what the version this project would use depends on and how each dependency is
+ * declared, everything subscribing to it would install, every question that
+ * would ask, and where its files land in this project. It reads only what sous
+ * already has on disk: the repository's cached index, the project's lockfile,
+ * and the recipe's own files when they are in the store or a linked working
+ * copy. The index describes each version's dependencies and questions, so a
+ * recipe nothing has installed is described as fully as one in the store, its
+ * files excepted. `--latest` reads the repository's index from upstream
+ * instead, saving nothing, and `--installed` looks the ref up among installed
+ * recipes only.
  */
 
 import { Args } from "@oclif/core";
+import semver from "semver";
 import { BaseCommand } from "../../base-command.js";
 import { resolveRootScope } from "../../lib/settings.js";
-import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import {
+  subscriptionServiceFor,
+  type SubscriptionPreview,
+  type SubscriptionService,
+} from "../../lib/repos/subscription-service.js";
 import { loadCatalogContext } from "../../lib/repos/catalog-inputs.js";
 import {
   describeInstalled,
   describeRecipe,
+  type CatalogInputs,
   type RecipeContentListing,
   type RecipeDependencyListing,
-  type RecipeVariableListing,
+  type RecipeDetail,
   type RecipeVersionListing,
 } from "../../lib/repos/catalog.js";
+import { PROJECT_REQUESTER } from "../../lib/repos/resolver.js";
+import { describeDeclaration, describeDependencyKind } from "../../lib/repos/declarations.js";
+import { formatQuestionPlan } from "../../lib/vars/question-plan.js";
+import { describeError } from "../../lib/repos/release/validate.js";
 import {
   INDENT,
   describeIndexSource,
@@ -61,14 +75,19 @@ const DEPENDENCY_COLUMNS: TableColumn[] = [
   { key: "kind", header: "Kind", overflow: "wrap", priority: "medium", minWidth: 16 },
 ];
 
-/** The columns the variable listing shows. */
-const VARIABLE_COLUMNS: TableColumn[] = [
-  { key: "name", header: "Variable", overflow: "truncate", minWidth: 10 },
-  { key: "type", header: "Type", priority: "medium" },
-  { key: "env", header: "Environment variable", overflow: "truncate", minWidth: 12 },
-  { key: "required", header: "Required", priority: "medium" },
-  { key: "secret", header: "Secret", priority: "low" },
-  { key: "prompt", header: "What it asks", overflow: "wrap", flex: 1, priority: "low", minWidth: 16 },
+/** The columns the listing of everything a subscription installs shows. */
+const INSTALLS_COLUMNS: TableColumn[] = [
+  { key: "key", header: "Recipe", kind: "path", overflow: "truncate", minWidth: 12 },
+  { key: "version", header: "Version", overflow: "truncate", minWidth: 7 },
+  { key: "kind", header: "Kind", overflow: "wrap", minWidth: 16 },
+  {
+    key: "neededBy",
+    header: "Needed by",
+    overflow: "wrap",
+    flex: 1,
+    priority: "medium",
+    minWidth: 12,
+  },
 ];
 
 /** The columns the content listing shows. */
@@ -86,7 +105,8 @@ const CONTENT_COLUMNS: TableColumn[] = [
 ];
 
 export default class RecipeShow extends BaseCommand {
-  static description = "Show one recipe: its versions, dependencies, variables and files";
+  static description =
+    "Show one recipe: its versions, dependencies, what subscribing installs and asks, and its files";
 
   /**
    * The other spelling of the topic. It lives under a hidden topic, so it is
@@ -165,24 +185,76 @@ export default class RecipeShow extends BaseCommand {
     printBrowsingNotes({ notChecked: notChecked.filter((name) => name === detail.repo) });
 
     this.printVersions(detail.versions);
-    this.printDependencies(detail.dependencies, detail.manifestRead);
+    this.printDependencies(
+      detail.dependencies,
+      detail.manifestRead || detail.dependenciesRecorded
+    );
 
-    if (!detail.manifestRead) {
+    const preview = await this.preview(service, inputs, detail);
+    if (typeof preview === "string") {
+      blankLine();
+      paragraph(preview);
+    } else {
+      this.printInstalls(preview);
+      this.printQuestions(preview);
+    }
+
+    if (detail.manifestRead) {
+      this.printContents(detail.contents);
+    } else {
+      blankLine();
+      subheading("Where its files land in this project");
       blankLine();
       paragraph(
-        "The recipe's own files are not on this machine, so the questions it asks and " +
-          "the files it publishes are not known here. Subscribing to it fetches them."
+        "The recipe's own files are not on this machine, so the files it publishes are " +
+          "not known here. Subscribing to it fetches them."
       );
-      footer();
-      return;
     }
 
-    this.printVariables(detail.variables);
-    this.printContents(detail.contents);
-
     footer();
   }
 
+  /**
+   * Works out what subscribing to the described version would install and ask,
+   * from the same indexes the rest of the page reads, fetching nothing. The
+   * answer is a sentence instead when it cannot be worked out.
+   *
+   * @param service - The project's subscription service.
+   * @param inputs - The catalog's inputs, whose indexes the preview resolves against.
+   * @param detail - The recipe being described.
+   */
+  private async preview(
+    service: SubscriptionService,
+    inputs: CatalogInputs,
+    detail: RecipeDetail
+  ): Promise<SubscriptionPreview | string> {
+    if (detail.describing === undefined) {
+      return (
+        "This recipe publishes no version a subscription would install, so nothing " +
+        "is described below."
+      );
+    }
+    try {
+      return await service.previewSubscription(
+        {
+          repo: detail.repo,
+          namespace: detail.namespace,
+          recipe: detail.name,
+          range: detail.describing,
+        },
+        {
+          indexes: new Map(inputs.repos.map((repo) => [repo.name, repo.index])),
+          ...(semver.prerelease(detail.describing) === null ? {} : { prerelease: true }),
+        }
+      );
+    } catch (error) {
+      return (
+        `Sous could not work out what subscribing to version ${detail.describing} ` +
+        `would install. ${describeError(error)}`
+      );
+    }
+  }
+
   /**
    * Every published version, newest first, with what each one is to this
    * project.
@@ -207,24 +279,21 @@ export default class RecipeShow extends BaseCommand {
   }
 
   /**
-   * What the described version depends on, from both sides: what the recipe's
-   * manifest declares, and what its repository's index resolved that to when it
-   * was released.
+   * What the described version depends on: the manifest entry that brings each
+   * dependency in and whether it is a co-subscription or a build dependency,
+   * and what its repository's index resolved it to when it was released.
    *
    * @param dependencies - The dependencies the catalog listed.
-   * @param manifestRead - Whether the recipe's own manifest could be read.
+   * @param known - Whether the manifest or the index says what the version declares.
    */
-  private printDependencies(
-    dependencies: RecipeDependencyListing[],
-    manifestRead: boolean
-  ): void {
+  private printDependencies(dependencies: RecipeDependencyListing[], known: boolean): void {
     blankLine();
     subheading("What it depends on");
     blankLine();
 
     if (dependencies.length === 0) {
       paragraph(
-        manifestRead
+        known
           ? "This recipe depends on nothing else."
           : "The repository's index records no dependencies for this version."
       );
@@ -233,7 +302,10 @@ export default class RecipeShow extends BaseCommand {
 
     const rows = dependencies.map((entry) => ({
       key: entry.key,
-      declared: entry.declared ?? "not declared in the manifest",
+      declared:
+        entry.declared === undefined
+          ? "not recorded in the index"
+          : describeDeclaration(entry.declared),
       resolved:
         entry.resolvedVersion ??
         (entry.resolvedRange === undefined
@@ -249,32 +321,69 @@ export default class RecipeShow extends BaseCommand {
   }
 
   /**
-   * The questions the recipe asks, and the environment variable each answer is
-   * stored under.
+   * Every recipe a subscription to the described version would install, each
+   * with whether its files land in the project and what brings it in, and the
+   * repositories it would need that the project does not trust yet.
    *
-   * @param variables - The variables the catalog listed.
+   * @param preview - What subscribing would install and ask.
    */
-  private printVariables(variables: RecipeVariableListing[]): void {
+  private printInstalls(preview: SubscriptionPreview): void {
     blankLine();
-    subheading("What it asks you");
+    subheading("What subscribing installs");
     blankLine();
 
-    if (variables.length === 0) {
-      paragraph("This recipe asks no questions.");
-      return;
+    const rows = preview.resolved.map((recipe) => {
+      const subscribed = recipe.requestedBy.includes(PROJECT_REQUESTER);
+      const holders = recipe.requestedBy.filter((holder) => holder !== PROJECT_REQUESTER);
+      return {
+        key: recipe.key,
+        version: recipe.version,
+        kind: subscribed ? "the subscription itself" : describeDependencyKind(recipe.kind),
+        neededBy: holders.length === 0 ? "this subscription" : holders.join(", "),
+      };
+    });
+
+    for (const line of renderTable(INSTALLS_COLUMNS, rows, { indent: INDENT })) {
+      log(indent(line, INDENT));
     }
 
-    const rows = variables.map((entry) => ({
-      name: entry.name,
-      type: entry.type,
-      env: entry.env,
-      required: entry.required ? "yes" : "no",
-      secret: entry.secret ? "yes" : "no",
-      prompt: entry.prompt,
-    }));
+    if (preview.missingRepos.length > 0) {
+      blankLine();
+      paragraph(
+        `Subscribing also needs ${
+          preview.missingRepos.length === 1 ? "a repository" : "repositories"
+        } this project does not trust yet, so what ${
+          preview.missingRepos.length === 1 ? "it publishes" : "they publish"
+        } is not listed above: ` +
+          preview.missingRepos
+            .map(
+              (missing) =>
+                `${missing.name}${missing.url === undefined ? "" : ` (${missing.url})`}, ` +
+                `needed by ${missing.requiredBy.map((entry) => entry.requestedBy).join(", ")}`
+            )
+            .join("; ") +
+          "."
+      );
+    }
+  }
 
-    for (const line of renderTable(VARIABLE_COLUMNS, rows, { indent: INDENT })) {
-      log(indent(line, INDENT));
+  /**
+   * Every question a subscription to the described version would ask, laid out
+   * exactly as `sous subscription add --dry-run` lays them out, without the
+   * flags that answer them ahead of time.
+   *
+   * @param preview - What subscribing would install and ask.
+   */
+  private printQuestions(preview: SubscriptionPreview): void {
+    blankLine();
+    subheading("What subscribing asks you");
+    blankLine();
+
+    for (const line of formatQuestionPlan(preview.questions, {
+      unreadable: preview.unreadable,
+      answerHints: false,
+    })) {
+      log(line === "" ? "" : indent(line));
     }
   }
 
@@ -311,13 +420,3 @@ export default class RecipeShow extends BaseCommand {
   }
 }
 
-/**
- * Plain-language wording for how a dependency was declared.
- *
- * @param kind - What the manifest declared it as, when the manifest was read.
- */
-function describeDependencyKind(kind: "depends" | "subscribes" | undefined): string {
-  if (kind === "depends") return "build dependency";
-  if (kind === "subscribes") return "co-subscription";
-  return "unknown";
-}

package/src/commands/repo/contribute.ts

@@ -6,7 +6,6 @@ import {
   SousScope,
   findReference,
   pickReference,
-  referenceReposFromIndexes,
   type ReferenceRepo,
 } from "../../lib/refs/index.js";
 import {
@@ -374,15 +373,7 @@ export default class RepoContribute extends BaseCommand {
       shellEnv: this.shellEnv,
     });
 
-    const trusted = service.currentRepos();
-    const repos: ReferenceRepo[] = Object.keys(trusted).map((name) => {
-      const url = trusted[name]?.url;
-      const index = service.cachedIndex(name);
-      if (index === undefined) {
-        return { name, ...(url === undefined ? {} : { url }), namespaces: [], recipes: [] };
-      }
-      return referenceReposFromIndexes([name], new Map([[name, index]]), { [name]: url })[0]!;
-    });
+    const repos: ReferenceRepo[] = service.cachedReferenceRepos();
 
     const matches = findReference(
       ref,

package/src/commands/repo/gc.ts

@@ -17,6 +17,7 @@ import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js"
 import { resolveStoreSettings } from "../../lib/repos/store/settings.js";
 import type { StoreKey } from "../../lib/repos/store/contract.js";
 import { renderTable, type TableColumn } from "../../utils/table.js";
+import { splitRecipeKey } from "../../lib/refs/parse.js";
 import {
   blankLine,
   dryRunNotice,
@@ -120,12 +121,12 @@ export default class RepoGc extends BaseCommand {
     const keep: StoreKey[] = Object.entries(lock.recipes).flatMap(([key, entry]) => {
       const identity = lock.repos[entry.repo]?.identity;
       if (identity === undefined) return [];
-      const namespace = key.slice(0, key.indexOf("/"));
+      const { namespace, name } = splitRecipeKey(key);
       return [
         {
           identity,
           namespace,
-          name: key.slice(namespace.length + 1),
+          name,
           version: entry.version,
         },
       ];

package/src/commands/repo/release.ts

@@ -30,6 +30,7 @@ import {
   releaseScope,
   remoteUrl,
   scopeProblems,
+  settleDependencyLocations,
   uncommittedChanges,
   validateRepo,
   warningsIn,
@@ -38,6 +39,7 @@ import {
   type ReleasePlan,
   type ReleaseScope,
   type RepoValidation,
+  type SettledDependency,
   type ValidationProblem,
 } from "../../lib/repos/release/index.js";
 import {
@@ -195,7 +197,14 @@ export default class RepoRelease extends Command {
     }
     log(`  Read ${describeCount(validation.recipes.length, "recipe")}.`);
 
-    if (flags.check) return await this.runCheck(rootDir, validation);
+    // A dependency that reads more than one way is settled before anything is
+    // planned or written, so a repository that cannot be reached stops the run
+    // with nothing changed.
+    const settling = await settleDependencyLocations(validation);
+    reportProblems(settling.problems);
+    if (hasErrors(settling.problems)) return this.stopForErrors(settling.problems);
+
+    if (flags.check) return await this.runCheck(rootDir, validation, settling.settled);
 
     // --- Plan -------------------------------------------------------------
 
@@ -284,6 +293,7 @@ export default class RepoRelease extends Command {
       existing,
       sousVersion: SOUS_VERSION,
       publishing,
+      settled: settling.settled,
     });
     reportProblems(rebuilt.problems);
     if (hasErrors(rebuilt.problems)) return this.stopForErrors(rebuilt.problems);
@@ -365,15 +375,22 @@ export default class RepoRelease extends Command {
    *
    * @param rootDir - The repository's root directory.
    * @param validation - The validated repository.
+   * @param settled - The dependencies that read more than one way, as settled.
    */
   private async runCheck(
     rootDir: string,
-    validation: RepoValidation
+    validation: RepoValidation,
+    settled: Map<string, SettledDependency>
   ): Promise<void> {
     section("Checking the index");
 
     const existing = readExistingIndex(rootDir);
-    const result = await buildIndex({ validation, existing, sousVersion: SOUS_VERSION });
+    const result = await buildIndex({
+      validation,
+      existing,
+      sousVersion: SOUS_VERSION,
+      settled,
+    });
     reportProblems(result.problems);
     if (hasErrors(result.problems)) return this.stopForErrors(result.problems);
 

package/src/commands/repo/search.ts

@@ -21,6 +21,7 @@ import {
 } from "../../lib/repos/catalog-display.js";
 import { readEffectiveLinks } from "../../lib/repos/links.js";
 import { renderTable, type TableColumn } from "../../utils/table.js";
+import { namespaceOfKey } from "../../lib/refs/parse.js";
 import { browsingFlags } from "../../utils/flags.js";
 import {
   blankLine,
@@ -142,7 +143,7 @@ export default class RepoSearch extends BaseCommand {
         const installed = locked?.repo === repo ? locked.version : undefined;
         if (flags.installed && installed === undefined) continue;
 
-        const namespace = key.slice(0, key.indexOf("/"));
+        const namespace = namespaceOfKey(key);
         const haystack = [
           key,
           recipe.description ?? "",

package/src/commands/vars/ask.ts

@@ -48,7 +48,9 @@ import {
   referenceContextFromVariables,
   variableReferenceKey,
   type ReferenceMatch,
+  type ReferenceRepo,
 } from "../../lib/refs/index.js";
+import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
 import {
   applyProvidedAnswers,
   askForMissing,
@@ -212,7 +214,10 @@ export default class VarsAsk extends BaseCommand {
 
     // What the reference and the flags name, as the fully qualified reference of
     // every variable to ask. Undefined means everything the usual rules pick.
-    const only = await this.resolveSelection(defined, context, selection);
+    // A reference written as a location settles against the trusted
+    // repositories, read from the cached indexes; a definitions file has none.
+    const trusted = flags.file === undefined ? this.trustedRepos() : [];
+    const only = await this.resolveSelection(defined, context, selection, trusted);
 
     const askOptions = {
       sousDir: this.configContext.sousDir,
@@ -257,13 +262,17 @@ export default class VarsAsk extends BaseCommand {
    * @param defined - Every variable definition in play.
    * @param ladder - The environment layers, for resolving environment variable names.
    * @param selection - The reference and the flags, as the caller wrote them.
+   * @param trusted - The trusted repositories, which settle a reference written as a location.
    * @returns The variables to ask, or undefined when nothing narrowed anything.
    */
   private async resolveSelection(
     defined: DefinedVariable[],
     ladder: LadderContext,
-    selection: Selection
+    selection: Selection,
+    trusted: ReferenceRepo[] = []
   ): Promise<string[] | undefined> {
+    const contextOf = (pool: DefinedVariable[]) =>
+      referenceContextFromVariables(pool, ladder, trusted);
     const { name, repo, namespace, vars } = selection;
     if (name === undefined && repo === undefined && namespace === undefined && vars === undefined) {
       return undefined;
@@ -272,13 +281,13 @@ export default class VarsAsk extends BaseCommand {
     let pool = defined;
 
     if (repo !== undefined) {
-      const match = await this.pick(findRepository(repo, contextOf(pool, ladder)), repo, selection);
+      const match = await this.pick(findRepository(repo, contextOf(pool)), repo, selection);
       pool = pool.filter((entry) => entry.recipe.repo === match.repo);
     }
 
     if (namespace !== undefined) {
       const match = await this.pick(
-        findNamespace(namespace, contextOf(pool, ladder)),
+        findNamespace(namespace, contextOf(pool)),
         namespace,
         selection
       );
@@ -287,7 +296,7 @@ export default class VarsAsk extends BaseCommand {
 
     if (name !== undefined) {
       const match = await this.pick(
-        findReference(name, ALL_SCOPES, contextOf(pool, ladder)),
+        findReference(name, ALL_SCOPES, contextOf(pool)),
         name,
         selection
       );
@@ -298,7 +307,7 @@ export default class VarsAsk extends BaseCommand {
       const chosen: DefinedVariable[] = [];
       for (const wanted of vars) {
         const match = await this.pick(
-          findVariable(wanted, contextOf(pool, ladder)),
+          findVariable(wanted, contextOf(pool)),
           wanted,
           selection
         );
@@ -317,6 +326,23 @@ export default class VarsAsk extends BaseCommand {
     return [...new Set(pool.map(variableReferenceKey))];
   }
 
+  /**
+   * The trusted repositories as a reference searches them, from the cached
+   * indexes alone. A project whose repositories cannot be read this way still
+   * answers every other form of reference, so a failure here is an empty list.
+   */
+  private trustedRepos(): ReferenceRepo[] {
+    try {
+      return subscriptionServiceFor({
+        configContext: this.configContext,
+        settings: this.settings,
+        shellEnv: this.shellEnv,
+      }).cachedReferenceRepos();
+    } catch {
+      return [];
+    }
+  }
+
   /**
    * Settles which of the things a reference could have meant this run proceeds
    * with, through the rule every command shares.
@@ -356,10 +382,6 @@ function narrowTo(pool: DefinedVariable[], match: ReferenceMatch): DefinedVariab
   });
 }
 
-/** The reference context for the variables still in the running. */
-function contextOf(pool: DefinedVariable[], ladder: LadderContext) {
-  return referenceContextFromVariables(pool, ladder);
-}
 
 /** What this run is asking about, in the words the header shows. */
 function describeSelection(selection: Selection, all: boolean): string {