@sous-io/sous 0.2.15 → 0.2.17

package/src/commands/repo/search.ts

@@ -2,21 +2,32 @@
  * `sous repo search <text>`.
  *
  * Searches the cached index of every repository this project trusts: recipe
- * names, namespace names and descriptions. It reads only what is already on
- * disk, so it works offline and never downloads anything; a repository whose
- * index has not been fetched yet is named at the end rather than silently left
- * out of the results.
+ * names, namespace names and descriptions. By default it reads only what is
+ * already on disk, so it works offline and never downloads anything; a
+ * repository whose index has not been fetched yet is named at the end rather
+ * than silently left out of the results. `--latest` searches each index as
+ * upstream serves it, saving nothing, and `--installed` searches only the
+ * recipes the lockfile pins, showing the installed version.
  */
 
 import { Args, Flags } from "@oclif/core";
 import { BaseCommand } from "../../base-command.js";
 import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import { readTrustedIndexes } from "../../lib/repos/catalog-inputs.js";
+import {
+  LINKED_NOTE,
+  describeIndexSource,
+  pinnedCell,
+} from "../../lib/repos/catalog-display.js";
+import { readEffectiveLinks } from "../../lib/repos/links.js";
 import { renderTable, type TableColumn } from "../../utils/table.js";
+import { browsingFlags } from "../../utils/flags.js";
 import {
   blankLine,
   footer,
   indent,
   log,
+  note,
   paragraph,
   section,
   showCommandVars,
@@ -45,12 +56,24 @@ const COLUMNS: TableColumn[] = [
   },
 ];
 
+/** The column an `--installed` search adds: the version the lockfile pins. */
+const INSTALLED_COLUMN: TableColumn = {
+  key: "installed",
+  header: "Installed",
+  overflow: "truncate",
+  minWidth: 9,
+};
+
 /** One recipe that matched, ready to be shown. */
 type Match = {
   repo: string;
   key: string;
   description: string;
   versions: string[];
+  /** The version the lockfile pins, when it pins this recipe from this repository. */
+  installed?: string;
+  /** The linked checkout builds read it from, when it is installed and its repository is linked. */
+  linkedPath?: string;
 };
 
 export default class RepoSearch extends BaseCommand {
@@ -67,6 +90,7 @@ export default class RepoSearch extends BaseCommand {
   static examples = [
     "<%= config.bin %> repo search task",
     "<%= config.bin %> repo search browser --limit 50",
+    "<%= config.bin %> repo search task --installed --latest",
   ];
 
   static args = {
@@ -78,6 +102,7 @@ export default class RepoSearch extends BaseCommand {
 
   static flags = {
     ...BaseCommand.baseFlags,
+    ...browsingFlags(),
     limit: Flags.integer({
       description: "How many matches to show",
       default: 25,
@@ -92,6 +117,8 @@ export default class RepoSearch extends BaseCommand {
       Project: this.projectLabel,
       Config: this.configContext.configPath,
       Searching: args.text,
+      Reading: describeIndexSource(flags.latest),
+      ...(flags.installed ? { Showing: "only what this project has installed" } : {}),
     });
 
     section("Recipes matching your search");
@@ -104,16 +131,17 @@ export default class RepoSearch extends BaseCommand {
 
     const repos = Object.keys(service.currentRepos()).sort();
     const matches: Match[] = [];
-    const notFetched: string[] = [];
-
-    for (const repo of repos) {
-      const index = service.cachedIndex(repo);
-      if (index === undefined) {
-        notFetched.push(repo);
-        continue;
-      }
+    const indexes = await readTrustedIndexes(service, { latest: flags.latest });
+    const { notFetched, notChecked } = indexes;
+    const lock = service.lockService.read();
+    const links = readEffectiveLinks(this.configContext.sousDir);
 
+    for (const { name: repo, index } of indexes.repos) {
       for (const [key, recipe] of Object.entries(index.recipes)) {
+        const locked = lock.recipes[key];
+        const installed = locked?.repo === repo ? locked.version : undefined;
+        if (flags.installed && installed === undefined) continue;
+
         const namespace = key.slice(0, key.indexOf("/"));
         const haystack = [
           key,
@@ -129,6 +157,10 @@ export default class RepoSearch extends BaseCommand {
           key,
           description: recipe.description ?? "",
           versions: Object.keys(recipe.versions).sort(),
+          ...(installed === undefined ? {} : { installed }),
+          ...(installed === undefined || links[repo] === undefined
+            ? {}
+            : { linkedPath: links[repo]!.path }),
         });
       }
     }
@@ -148,7 +180,9 @@ export default class RepoSearch extends BaseCommand {
         repos.length === 0
           ? "This project trusts no repositories yet, so there is nothing to search. " +
             "Add one with 'sous repo add <url>'."
-          : `Nothing in the repositories this project trusts matches '${args.text}'.`
+          : flags.installed
+            ? `Nothing this project has installed matches '${args.text}'.`
+            : `Nothing in the repositories this project trusts matches '${args.text}'.`
       );
     } else {
       const shown = matches.slice(0, flags.limit);
@@ -156,11 +190,18 @@ export default class RepoSearch extends BaseCommand {
         key: match.key,
         repo: match.repo,
         versions: match.versions.join(", "),
+        installed: pinnedCell(match.installed, match.linkedPath),
         description:
           match.description.length > 0 ? match.description : "no description published",
       }));
 
-      for (const line of renderTable(COLUMNS, rows, { indent: INDENT })) {
+      // Narrowed to what is installed, the installed version sits right after
+      // the recipe, ahead of every version the repository publishes.
+      const columns = flags.installed
+        ? [COLUMNS[0]!, INSTALLED_COLUMN, ...COLUMNS.slice(1)]
+        : COLUMNS;
+
+      for (const line of renderTable(columns, rows, { indent: INDENT })) {
         log(indent(line, INDENT));
       }
 
@@ -179,9 +220,21 @@ export default class RepoSearch extends BaseCommand {
       );
     }
 
+    if (notChecked.length > 0) {
+      summary.push(
+        `These repositories could not be reached, so they were searched as the cache ` +
+          `has them and were not checked: ${notChecked.join(", ")}.`
+      );
+    }
+
     if (summary.length > 0) {
       blankLine();
-      for (const line of summary) log(indent(line));
+      for (const line of summary) paragraph(line);
+    }
+
+    if (matches.slice(0, flags.limit).some((match) => match.linkedPath !== undefined)) {
+      blankLine();
+      note(LINKED_NOTE);
     }
 
     footer();

package/src/commands/repo/submit.ts

@@ -1,25 +1,49 @@
-import { Command, Flags } from "@oclif/core";
-import { findRepoRoot, submitRepo } from "../../lib/repos/release/index.js";
+import { Args, Command, Flags } from "@oclif/core";
+import { discoverConfig, refreshDiscoveredConfig } from "../../lib/config-discovery.js";
+import { loadEnvFiles } from "../../lib/env-local.js";
+import { isInteractive } from "../../lib/interactive.js";
+import { enabledRepos } from "../../lib/repos/defaults.js";
+import {
+  findRepoRoot,
+  renderChangelog,
+  submitRepo,
+  type SubmitResult,
+} from "../../lib/repos/release/index.js";
+import {
+  findSubmitCheckout,
+  type SubmitProject,
+} from "../../lib/repos/release/submit-checkout.js";
+import { submitQuestions } from "../../lib/repos/release/submit-questions.js";
+import type { ProposalStatus } from "../../lib/repos/providers/provider.js";
+import { loadSettings } from "../../lib/settings.js";
 import { reportCommandError } from "../../utils/command-errors.js";
-import { nonInteractiveFlag } from "../../utils/flags.js";
+import { confirmationFlag, nonInteractiveFlag } from "../../utils/flags.js";
 import {
+  BULLET,
   blankLine,
   dryRunNotice,
   footer,
   header,
   log,
+  note,
+  paragraph,
   section,
   showCommandVars,
   showVariables,
+  warning,
 } from "../../utils/formatting.js";
 
 /**
- * `sous repo submit` proposes the committed changes in a recipe repository to
- * that repository's maintainers.
+ * `sous repo submit` carries a proposed change to a recipe repository's
+ * maintainers through its whole life: it opens the proposal, updates it when
+ * there is more to send, reports where it stands, and starts the next one once
+ * it was merged.
  *
  * Like `sous repo init` and `sous repo release`, this command does NOT extend
- * BaseCommand: it runs inside a RECIPE repository, which is not a sous project
- * and has no `.sous/` directory of its own.
+ * BaseCommand: it runs inside a RECIPE repository, which is not a sous project.
+ * It can also be run from a project, naming a repository the project links, and
+ * then looks for the project's config itself, optionally: finding none is not a
+ * failure while the working directory is inside a recipe repository.
  *
  * Submitting never publishes and never writes to a repository directly. Sous
  * validates first, then hands the fork, branch and pull request mechanics to the
@@ -29,7 +53,7 @@ import {
  */
 export default class RepoSubmit extends Command {
   static description =
-    "Propose this recipe repository's committed changes to its maintainers";
+    "Propose a recipe repository's changes to its maintainers, and follow the proposal through";
 
   /**
    * The other spelling of the topic. It lives under a hidden topic, so it is
@@ -38,25 +62,46 @@ export default class RepoSubmit extends Command {
   static aliases = ["repos:submit"];
 
   static examples = [
-    "<%= config.bin %> repo submit",
-    '<%= config.bin %> repo submit --title "Add a linting recipe"',
-    "<%= config.bin %> repo submit --draft",
+    '<%= config.bin %> repo submit --title "Add a linting recipe" --body "Adds lint rules."',
+    "<%= config.bin %> repo submit sous-recipes",
+    "<%= config.bin %> repo submit --status",
+    "<%= config.bin %> repo submit --commit --yes --title \"Fix a typo\" --body \"Fixes it.\"",
     "<%= config.bin %> repo submit --dry-run",
   ];
 
+  static args = {
+    repo: Args.string({
+      description: "The linked repository to propose a change from, when run inside a project",
+      required: false,
+    }),
+  };
+
   static flags = {
     title: Flags.string({
-      description: "Title for the proposal. Defaults to the last commit's subject.",
+      description: "The proposal's title; required for a new proposal, and replaces an open one's",
     }),
     body: Flags.string({
-      description: "Body for the proposal. Defaults to a summary sous writes.",
+      description:
+        "The proposal's description; required for a new proposal, and replaces an open one's",
+    }),
+    branch: Flags.string({
+      description: "The branch to work with, instead of the one that is checked out",
+    }),
+    status: Flags.boolean({
+      description: "Only report where the branch's proposal stands",
+      default: false,
+    }),
+    commit: Flags.boolean({
+      description: "Commit uncommitted changes for you, after listing them and asking once",
+      default: false,
     }),
     draft: Flags.boolean({
-      description: "Open the proposal as a draft",
+      description: "Open a new proposal as a draft",
       default: false,
     }),
+    yes: confirmationFlag(),
     "dry-run": Flags.boolean({
-      description: "Check everything and print the plan without sending anything",
+      description: "Check everything and print the plan without writing or sending anything",
       default: false,
     }),
     // This command does not extend BaseCommand, so it declares the global
@@ -70,30 +115,121 @@ export default class RepoSubmit extends Command {
   }
 
   async run(): Promise<void> {
-    const { flags } = await this.parse(RepoSubmit);
+    const { args, flags } = await this.parse(RepoSubmit);
     const dryRun = flags["dry-run"];
-    const rootDir = findRepoRoot(process.cwd());
+    const interactive = isInteractive();
+    const cwd = process.cwd();
 
     showCommandVars({
-      Repository: rootDir,
-      Title: flags.title ?? "(the last commit's subject)",
-      Draft: flags.draft,
-      "Dry Run": dryRun,
+      "Working directory": cwd,
+      Repository: args.repo ?? "(the one the working directory is in)",
+      Branch: flags.branch ?? "(the one that is checked out)",
+      Mode: flags.status ? "Status only" : dryRun ? "Dry run" : "Propose",
+    });
+
+    const checkout = await findSubmitCheckout({
+      cwd,
+      ...(args.repo === undefined ? {} : { repo: args.repo }),
+      ...(await this.projectFor(cwd, args.repo)),
+      interactive,
+    });
+
+    section("The checkout");
+    showVariables({
+      Checkout: checkout.rootDir,
+      ...(checkout.repo === undefined ? {} : { Repository: checkout.repo }),
     });
+    blankLine();
+    note(checkout.reason);
+    for (const entry of checkout.notes) note(entry);
 
-    section("Proposing a change");
+    section(flags.status ? "Looking the proposal up" : "Proposing a change");
 
     const result = await submitRepo({
-      rootDir,
-      title: flags.title,
-      body: flags.body,
+      rootDir: checkout.rootDir,
+      ...(flags.title === undefined ? {} : { title: flags.title }),
+      ...(flags.body === undefined ? {} : { body: flags.body }),
+      ...(flags.branch === undefined ? {} : { branch: flags.branch }),
+      statusOnly: flags.status,
+      commit: flags.commit,
       draft: flags.draft,
       dryRun,
+      questions: submitQuestions({ interactive, yes: flags.yes }),
       onStep: (message) => log(`  ${message}`),
-      onNotice: (message) => (dryRun ? dryRunNotice(message) : log(`  ${message}`)),
+      onNotice: (message) => (dryRun ? dryRunNotice(message) : note(message)),
+      onWarning: (message) => warning(message),
     });
 
-    section(dryRun ? "What would be proposed" : "What was proposed");
+    this.report(result);
+    footer();
+  }
+
+  /**
+   * The project around the working directory, when the run needs one: always
+   * when a repository was named, and otherwise only when the working directory
+   * is not a recipe repository itself (the checkout finder decides that; a
+   * project found here is simply handed to it). A project whose config does not
+   * load is an error, because the run cannot say what the argument names.
+   *
+   * @param cwd - The working directory.
+   * @param repo - The repository the command line named, when it named one.
+   */
+  private async projectFor(
+    cwd: string,
+    repo: string | undefined
+  ): Promise<{ project?: SubmitProject }> {
+    const discovered = discoverConfig(cwd, undefined);
+    if (discovered === null) return {};
+    if (repo === undefined && insideRecipeRepo(cwd)) return {};
+
+    loadEnvFiles(discovered.sousDir);
+    const refreshed = refreshDiscoveredConfig(discovered);
+    const settings = await loadSettings(refreshed);
+    return { project: { sousDir: refreshed.sousDir, repos: enabledRepos(settings) } };
+  }
+
+  /**
+   * Prints what the run did, or would do, as a key and value list followed by
+   * one sentence, and the changelog when one was generated.
+   *
+   * @param result - What the submission reported.
+   */
+  private report(result: SubmitResult): void {
+    const noun = result.proposalNoun;
+
+    if (result.outcome === "cancelled") {
+      blankLine();
+      log("  Nothing was written and nothing was sent.");
+      return;
+    }
+
+    if (result.outcome === "status") {
+      section(`The ${noun} for '${result.branch}'`);
+      if (result.status === undefined) {
+        showVariables({ Repository: `${result.repo.owner}/${result.repo.name}`, Branch: result.branch });
+        blankLine();
+        paragraph(`The branch '${result.branch}' has no ${noun}.`);
+        return;
+      }
+      showVariables(statusFacts(result, result.status));
+      return;
+    }
+
+    if (result.changelog !== undefined) {
+      section("What merging this changes");
+      printChangelog(renderChangelog(result.changelog));
+    }
+
+    const heading =
+      result.outcome === "created"
+        ? result.dryRun
+          ? `The ${noun} this would open`
+          : `The ${noun} that was opened`
+        : result.dryRun
+          ? `The ${noun} this would update`
+          : `The ${noun} for '${result.branch}'`;
+    section(heading);
+
     showVariables({
       Provider: result.provider,
       Repository: `${result.repo.owner}/${result.repo.name}`,
@@ -101,20 +237,29 @@ export default class RepoSubmit extends Command {
       "Target branch": result.baseBranch,
       "Pushed to": result.dryRun ? "(nothing was pushed)" : result.pushedTo,
       "Through a fork": result.usedFork,
-      Title: result.title,
-      Proposal: result.url ?? "(the provider printed no address)",
+      ...(result.title === undefined ? {} : { Title: result.title }),
+      ...(result.committed === undefined ? {} : { Committed: result.committed.join(", ") }),
+      Address: result.url ?? (result.dryRun ? "(not opened yet)" : "(the provider printed no address)"),
     });
 
+    if (result.status !== undefined && !result.dryRun) {
+      blankLine();
+      showVariables(statusFacts(result, result.status));
+    }
+
     blankLine();
     if (result.dryRun) {
-      log("  Nothing was sent. Run the command again without --dry-run to propose it.");
+      log("  Nothing was written and nothing was sent.");
+    } else if (result.outcome === "created") {
+      paragraph(
+        `The ${noun} is open for review. The maintainers decide what happens next; sous ` +
+          `never publishes on their behalf.`
+      );
+    } else if (result.outcome === "updated") {
+      paragraph(`The ${noun} was updated with what this run sent.`);
     } else {
-      log("  The maintainers decide what happens next; sous never publishes on their");
-      log("  behalf. Anything they ask for goes on the same branch, and the proposal");
-      log("  updates itself when you push again.");
+      paragraph(`There was nothing new to send, so the ${noun} was left as it was.`);
     }
-
-    footer();
   }
 
   /**
@@ -129,3 +274,68 @@ export default class RepoSubmit extends Command {
     return this.exit(exitCode);
   }
 }
+
+/**
+ * Prints the Markdown changelog for a terminal: the heading is already the
+ * section's, emphasis and code marks are dropped, a list item becomes a real
+ * bullet, and every line is wrapped.
+ *
+ * @param markdown - The changelog as it goes into the proposal.
+ */
+function printChangelog(markdown: string): void {
+  const lines = markdown.split("\n").slice(2);
+  for (const raw of lines) {
+    const line = raw.replace(/\*\*/g, "").replace(/`/g, "");
+    if (line.trim().length === 0) {
+      blankLine();
+    } else if (line.startsWith("- ")) {
+      paragraph(`${BULLET} ${line.slice(2)}`, { indent: 4, hangingIndent: 2 });
+    } else {
+      paragraph(line);
+    }
+  }
+}
+
+/** True when the directory is inside a recipe repository. */
+function insideRecipeRepo(cwd: string): boolean {
+  try {
+    findRepoRoot(cwd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The facts about where a proposal stands, as a key and value list.
+ *
+ * @param result - The submission, for the repository and the noun.
+ * @param status - What the provider reported.
+ */
+function statusFacts(result: SubmitResult, status: ProposalStatus): Record<string, unknown> {
+  const { proposal } = status;
+  const state =
+    proposal.state === "open"
+      ? proposal.draft
+        ? "open, as a draft"
+        : "open"
+      : proposal.state === "merged"
+        ? "merged"
+        : "closed without being merged";
+  return {
+    [`The ${result.proposalNoun}`]: proposal.title,
+    State: state,
+    ...(status.review === undefined ? {} : { Review: status.review }),
+    ...(status.checks === undefined
+      ? {}
+      : {
+          Checks:
+            `${status.checks.passed} passed, ${status.checks.failed} failed, ` +
+            `${status.checks.pending} still running`,
+        }),
+    ...(status.mergeable === undefined
+      ? {}
+      : { Mergeable: status.mergeable ? "yes" : "no, it conflicts with its target branch" }),
+    ...(proposal.url === undefined ? {} : { Address: proposal.url }),
+  };
+}