@sous-io/sous 0.2.16 → 0.2.17

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 }),
+  };
+}

package/src/lib/repos/formats/common.ts

@@ -313,6 +313,26 @@ export function extensibleObject<Shape extends z.ZodRawShape>(shape: Shape) {
   return z.preprocess(stripExtensionKeys, z.strictObject(shape));
 }
 
+/**
+ * The `submissions` block a repo manifest and a recipe manifest may both carry:
+ * whether the recipes it covers take proposed changes, and where to send a
+ * change instead when they do not. On a repo manifest it covers every recipe;
+ * on a recipe manifest it covers that recipe, and wins over the repository's.
+ *
+ *     submissions:
+ *       allowed: false
+ *       instead: Propose changes in sous-io/sous, under recipes/core/sous-skills/.
+ */
+export const submissionsSchema = extensibleObject({
+  /** Whether a proposed change to the covered recipes is accepted. Defaults to true. */
+  allowed: z.boolean().default(true),
+  /** Where a change should go instead, printed when one is proposed anyway. */
+  instead: z.string().min(1, "must not be empty").optional(),
+});
+
+/** A validated `submissions` block. */
+export type Submissions = z.infer<typeof submissionsSchema>;
+
 // --- Error reporting ----------------------------------------------------------------------------
 
 /** Renders a zod issue path (`["variables",0,"name"]`) as `variables[0].name`. */

package/src/lib/repos/formats/recipe-manifest.ts

@@ -34,6 +34,7 @@ import {
   recipeNameSchema,
   relativePathSchema,
   semverVersionSchema,
+  submissionsSchema,
   variableNameSchema,
 } from "./common.js";
 import { parseDependencyRef } from "../ref.js";
@@ -301,6 +302,12 @@ export const recipeManifestSchema = extensibleObject({
   version: semverVersionSchema,
   /** One-paragraph summary, shown by `sous repo search` and `sous repo list`. */
   description: z.string().optional(),
+  /**
+   * Whether this recipe takes proposed changes, winning over the repository's
+   * own `submissions` block. A recipe whose files are copied in from somewhere
+   * else sets `allowed: false` and says where to go instead.
+   */
+  submissions: submissionsSchema.optional(),
   /**
    * Build dependencies: fetched and addressable here, but not added to the
    * project. Each entry is a bare ref naming a sibling recipe in this same

package/src/lib/repos/formats/repo-manifest.ts

@@ -17,6 +17,7 @@ import {
   parseFormat,
   relativePathSchema,
   repoNameSchema,
+  submissionsSchema,
 } from "./common.js";
 
 /** A namespace declaration. Namespaces group recipes and are not versioned. */
@@ -48,6 +49,13 @@ export const repoManifestSchema = extensibleObject({
    * contributor is never left without a route.
    */
   contribute: z.string().min(1, "must not be empty").optional(),
+  /**
+   * Whether the repository's recipes take proposed changes. A recipe's own
+   * `submissions` block wins over this one. `sous repo submit` warns before
+   * proposing a change to a recipe that does not, and `sous repo release
+   * --check` fails a pull request that changes one.
+   */
+  submissions: submissionsSchema.optional(),
   /** Every namespace the repo publishes, keyed by namespace name. */
   namespaces: z.record(namespaceNameSchema, repoNamespaceSchema),
   /**

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

@@ -10,7 +10,8 @@
  * declare the `submit` feature (the local one, for instance) inherits four
  * methods that raise a ConfigError naming the provider and what was asked of
  * it, so a caller that skips the feature check gets a sentence rather than a
- * `TypeError`.
+ * `TypeError`. The three calls behind the `proposals` feature are refused the
+ * same way.
  */
 
 import { ConfigError } from "../../errors.js";
@@ -26,6 +27,10 @@ import type {
   ChangeProposal,
   FetchedIndex,
   ForkedRepo,
+  ProposalQuery,
+  ProposalStatus,
+  ProposalSummary,
+  ProposalUpdate,
   ProposedChange,
   ProviderCli,
   ProviderFeature,
@@ -187,6 +192,33 @@ export abstract class ProviderBase implements RepoProvider {
     throw this.unsupported("submit", "propose a change to it");
   }
 
+  // --- Proposals after the fact, refused unless a provider overrides them ----
+
+  async findProposal(
+    _repo: CanonicalRepo,
+    _query: ProposalQuery,
+    _options: ProviderOptions = {}
+  ): Promise<ProposalSummary | undefined> {
+    throw this.unsupported("proposals", "look for a proposal that is already open");
+  }
+
+  async proposalStatus(
+    _repo: CanonicalRepo,
+    _id: string,
+    _options: ProviderOptions = {}
+  ): Promise<ProposalStatus> {
+    throw this.unsupported("proposals", "report where a proposal stands");
+  }
+
+  async updateProposal(
+    _repo: CanonicalRepo,
+    _id: string,
+    _update: ProposalUpdate,
+    _options: ProviderOptions = {}
+  ): Promise<ProposedChange> {
+    throw this.unsupported("proposals", "change a proposal's title or body");
+  }
+
   /**
    * The refusal a provider gives when it is asked for something it never
    * claimed. It names the provider and the feature, so the caller learns why