@sous-io/sous 0.2.16 → 0.2.18

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/git-clone.ts

@@ -227,6 +227,77 @@ export function cloneRepo(
   return { depth: 0, fellBackToFullClone: depth > 0 };
 }
 
+/** Work in a checkout that exists nowhere else, and would be lost with it. */
+export type UnsavedWork = {
+  /** Every changed or untracked path, as `git status --porcelain` prints it. */
+  uncommitted: string[];
+  /** Every commit on a local branch that no remote has, one line each. */
+  unpushed: string[];
+  /** Every stash entry, one line each. */
+  stashes: string[];
+  /**
+   * Why git could not be asked, when it could not. Nothing is known about the
+   * checkout then, which a caller must treat as possibly holding work.
+   */
+  unknown?: string;
+};
+
+/**
+ * What in a checkout would be lost if it were deleted: uncommitted changes,
+ * commits no remote has, and stashes.
+ *
+ * unsavedWork("/path/to/checkout")
+ * // -> { uncommitted: ["M README.md"], unpushed: [], stashes: [] }
+ *
+ * @param directory - The checkout to inspect.
+ * @param options - The git runner to use.
+ */
+export function unsavedWork(directory: string, options: GitOptions = {}): UnsavedWork {
+  const runner = options.runner ?? runGit;
+  const lines = (text: string): string[] =>
+    text
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+
+  const status = runner(["status", "--porcelain"], { cwd: directory });
+  if (status.status !== 0) {
+    return {
+      uncommitted: [],
+      unpushed: [],
+      stashes: [],
+      unknown:
+        `git could not read the checkout at ${directory}` +
+        (status.stderr.length > 0 ? `: ${status.stderr}` : "."),
+    };
+  }
+
+  const unpushed = runner(["log", "--branches", "--not", "--remotes", "--oneline"], {
+    cwd: directory,
+  });
+  const stashes = runner(["stash", "list"], { cwd: directory });
+
+  return {
+    uncommitted: lines(status.stdout),
+    unpushed: unpushed.status === 0 ? lines(unpushed.stdout) : [],
+    stashes: stashes.status === 0 ? lines(stashes.stdout) : [],
+  };
+}
+
+/**
+ * True when an inspection found nothing that would be lost.
+ *
+ * @param work - What `unsavedWork` found.
+ */
+export function hasNoUnsavedWork(work: UnsavedWork): boolean {
+  return (
+    work.unknown === undefined &&
+    work.uncommitted.length === 0 &&
+    work.unpushed.length === 0 &&
+    work.stashes.length === 0
+  );
+}
+
 /**
  * True when two remote URLs name the same repository, ignoring the differences
  * that never change what is fetched: a `.git` suffix, a trailing slash, the

package/src/lib/repos/links.ts

@@ -4,7 +4,8 @@
  * A link redirects one repository's resolution away from the store and at a
  * real working copy on disk, which is how a maintainer edits recipes: edits
  * happen in a checkout, never in the store. `sous repo link` writes an entry
- * here; `sous repo unlink` removes it and leaves the checkout alone.
+ * here; `sous repo unlink` removes it and leaves the checkout alone unless
+ * `--remove` asks it to delete one sous cloned.
  *
  * Two maps exist. The project's `.sous/sous.links.json` covers one project; the
  * machine-wide `$SOUS_HOME/sous.links.json` covers every project on the machine,

package/src/lib/repos/locked-recipes.ts

@@ -252,3 +252,25 @@ export function projectSubscriptionRefs(
   }
   return [...refs].sort();
 }
+
+/**
+ * Every locked recipe reachable from a set of keys through the lockfile's
+ * holder lists: the keys themselves, whatever they hold, and so on.
+ *
+ * @param lock - The lockfile.
+ * @param roots - The keys to start from.
+ */
+export function lockedClosure(lock: Lockfile, roots: string[]): string[] {
+  const reached = new Set(roots.filter((key) => Object.hasOwn(lock.recipes, key)));
+  const queue = [...reached];
+  while (queue.length > 0) {
+    const holder = queue.shift()!;
+    for (const [key, entry] of Object.entries(lock.recipes)) {
+      if (reached.has(key) || !entry.requestedBy.includes(holder)) continue;
+      reached.add(key);
+      queue.push(key);
+    }
+  }
+  return [...reached].sort();
+}
+

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

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

@@ -12,6 +12,8 @@
  * request opened by `gh pr create`, a contributor without push permission works
  * through a fork made by `gh repo fork`, and both are reported back as plain
  * data, so the service that sequences them never learns a GitHub-shaped fact.
+ * Finding a pull request again, reporting where it stands and replacing its
+ * text go through `gh pr list`, `gh pr view` and `gh pr edit` the same way.
  */
 
 import { ConfigError } from "../../errors.js";
@@ -28,6 +30,13 @@ import {
   type ChangeProposal,
   type FetchedIndex,
   type ForkedRepo,
+  type ProposalChecks,
+  type ProposalQuery,
+  type ProposalReview,
+  type ProposalState,
+  type ProposalStatus,
+  type ProposalSummary,
+  type ProposalUpdate,
   type ProposedChange,
   type ProviderCli,
   type ProviderFeature,
@@ -59,10 +68,10 @@ export class GithubProvider extends ProviderBase {
   readonly id = "github" as const;
 
   /**
-   * Reads the index and recipe subtrees, and proposes a change through
-   * the GitHub CLI ('gh').
+   * Reads the index and recipe subtrees, proposes a change through the GitHub
+   * CLI ('gh'), and finds, reports on and updates that pull request afterwards.
    */
-  readonly features: ProviderFeature[] = ["fetch", "submit"];
+  readonly features: ProviderFeature[] = ["fetch", "submit", "proposals"];
 
   /** The command line tool the write path is built on. */
   readonly cli: ProviderCli = {
@@ -292,4 +301,267 @@ export class GithubProvider extends ProviderBase {
     }
     return { url, detail: `The ${this.proposalNoun} is at ${url}.` };
   }
+
+  // --- Proposals after the fact ------------------------------------------------
+
+  /**
+   * The pull request a branch was pushed for. GitHub lists pull requests by
+   * head branch name alone, so the list is narrowed here by where the branch
+   * lives: the repository itself, or the contributor's fork. When a branch has
+   * had several, the open one wins, and otherwise the newest.
+   *
+   * @param repo - The canonicalized repository the proposal targets.
+   * @param query - The branch, and whether it lives on a fork.
+   * @param options - Subprocess runner and working directory overrides.
+   */
+  async findProposal(
+    repo: CanonicalRepo,
+    query: ProposalQuery,
+    options: ProviderOptions = {}
+  ): Promise<ProposalSummary | undefined> {
+    const forkOwner = query.fromFork
+      ? (query.forkOwner ?? (await this.signedInLogin(options)))
+      : undefined;
+
+    const listed = await this.ghJson<GhPullRequest[]>(
+      [
+        "pr",
+        "list",
+        "--repo",
+        `${repo.owner}/${repo.name}`,
+        "--head",
+        query.branch,
+        "--state",
+        "all",
+        "--limit",
+        "50",
+        "--json",
+        "number,url,state,title,isDraft,baseRefName,headRepositoryOwner,isCrossRepository",
+      ],
+      "pr list",
+      options
+    );
+
+    const mine = listed.filter((entry) =>
+      query.fromFork
+        ? entry.isCrossRepository === true && entry.headRepositoryOwner?.login === forkOwner
+        : entry.isCrossRepository !== true
+    );
+    if (mine.length === 0) return undefined;
+
+    const open = mine.find((entry) => entry.state === "OPEN");
+    const chosen = open ?? [...mine].sort((a, b) => b.number - a.number)[0]!;
+    return summarizePullRequest(chosen);
+  }
+
+  /**
+   * Where one pull request stands: its state, its review decision, and how
+   * its checks are going, counted.
+   *
+   * @param repo - The canonicalized repository the proposal targets.
+   * @param id - The pull request number.
+   * @param options - Subprocess runner and working directory overrides.
+   */
+  async proposalStatus(
+    repo: CanonicalRepo,
+    id: string,
+    options: ProviderOptions = {}
+  ): Promise<ProposalStatus> {
+    const viewed = await this.ghJson<GhPullRequest>(
+      [
+        "pr",
+        "view",
+        id,
+        "--repo",
+        `${repo.owner}/${repo.name}`,
+        "--json",
+        "number,url,state,title,isDraft,baseRefName,reviewDecision,statusCheckRollup,mergeable",
+      ],
+      "pr view",
+      options
+    );
+
+    const review = reviewFrom(viewed.reviewDecision);
+    const checks = checksFrom(viewed.statusCheckRollup);
+    const mergeable =
+      viewed.mergeable === "MERGEABLE"
+        ? true
+        : viewed.mergeable === "CONFLICTING"
+          ? false
+          : undefined;
+
+    return {
+      proposal: summarizePullRequest(viewed),
+      ...(review === undefined ? {} : { review }),
+      ...(checks === undefined ? {} : { checks }),
+      ...(mergeable === undefined ? {} : { mergeable }),
+    };
+  }
+
+  /**
+   * Replaces a pull request's title, its body, or both.
+   *
+   * @param repo - The canonicalized repository the proposal targets.
+   * @param id - The pull request number.
+   * @param update - What to replace.
+   * @param options - Subprocess runner and working directory overrides.
+   */
+  async updateProposal(
+    repo: CanonicalRepo,
+    id: string,
+    update: ProposalUpdate,
+    options: ProviderOptions = {}
+  ): Promise<ProposedChange> {
+    const args = ["pr", "edit", id, "--repo", `${repo.owner}/${repo.name}`];
+    if (update.title !== undefined) args.push("--title", update.title);
+    if (update.body !== undefined) args.push("--body", update.body);
+
+    const result = await this.runCommand(this.cli.command, args, options);
+    if (result.code !== 0) {
+      const reported = result.stderr.trim() || result.stdout.trim();
+      throw new ConfigError(
+        `'${this.cli.command} pr edit' did not succeed, so the ${this.proposalNoun} kept its ` +
+          `title and body.` +
+          (reported.length === 0 ? "" : `\n  ${reported}`)
+      );
+    }
+
+    const url = firstUrlIn(result.stdout);
+    return url === undefined
+      ? { detail: `The ${this.proposalNoun} was updated.` }
+      : { url, detail: `The ${this.proposalNoun} at ${url} was updated.` };
+  }
+
+  /**
+   * The login of the account `gh` is signed in as, which is the owner of any
+   * fork sous made for the contributor.
+   *
+   * @param options - Subprocess runner and working directory overrides.
+   */
+  private async signedInLogin(options: ProviderOptions): Promise<string> {
+    const who = await this.capturedOutput(
+      this.cli.command,
+      ["api", "user", "--jq", ".login"],
+      options
+    );
+    if (who === undefined || who.trim().length === 0) {
+      throw new ConfigError(
+        "Sous could not read your GitHub login from " +
+          `'${this.cli.command} api user', so it cannot tell which fork a ${this.proposalNoun} ` +
+          "would come from."
+      );
+    }
+    return who.trim();
+  }
+
+  /**
+   * Runs a `gh` command that prints JSON, and parses what it printed.
+   *
+   * @param args - The arguments, ending with the `--json` field list.
+   * @param what - The subcommand, as it is named in a failure.
+   * @param options - Subprocess runner and working directory overrides.
+   */
+  private async ghJson<T>(args: string[], what: string, options: ProviderOptions): Promise<T> {
+    const result = await this.runCommand(this.cli.command, args, options);
+    if (result.code !== 0) {
+      const reported = result.stderr.trim() || result.stdout.trim();
+      throw new ConfigError(
+        `'${this.cli.command} ${what}' did not succeed.` +
+          (reported.length === 0 ? "" : `\n  ${reported}`)
+      );
+    }
+    try {
+      return JSON.parse(result.stdout) as T;
+    } catch {
+      throw new ConfigError(
+        `'${this.cli.command} ${what}' printed something that is not JSON, so sous cannot read ` +
+          `the ${this.proposalNoun} it describes.`
+      );
+    }
+  }
+}
+
+// --- What gh prints, and how it maps onto plain data ---------------------------------------------
+
+/** The fields sous asks `gh` for, as it prints them. */
+type GhPullRequest = {
+  number: number;
+  url?: string;
+  state?: string;
+  title?: string;
+  isDraft?: boolean;
+  baseRefName?: string;
+  headRepositoryOwner?: { login?: string } | null;
+  isCrossRepository?: boolean;
+  reviewDecision?: string | null;
+  statusCheckRollup?: GhCheck[] | null;
+  mergeable?: string;
+};
+
+/** One entry of a pull request's status check rollup: a check run or a commit status. */
+type GhCheck = {
+  __typename?: string;
+  status?: string;
+  conclusion?: string | null;
+  state?: string;
+};
+
+/** A pull request's state, in the words every provider shares. */
+function stateFrom(state: string | undefined): ProposalState {
+  if (state === "MERGED") return "merged";
+  if (state === "CLOSED") return "closed";
+  return "open";
+}
+
+/**
+ * The plain summary of a pull request.
+ *
+ * @param entry - What `gh` printed for it.
+ */
+function summarizePullRequest(entry: GhPullRequest): ProposalSummary {
+  return {
+    id: String(entry.number),
+    ...(entry.url === undefined ? {} : { url: entry.url }),
+    state: stateFrom(entry.state),
+    title: entry.title ?? "",
+    draft: entry.isDraft === true,
+    ...(entry.baseRefName === undefined ? {} : { base: entry.baseRefName }),
+  };
+}
+
+/** GitHub's review decision, in the words every provider shares. */
+function reviewFrom(decision: string | null | undefined): ProposalReview | undefined {
+  if (decision === "APPROVED") return "approved";
+  if (decision === "CHANGES_REQUESTED") return "changes requested";
+  if (decision === "REVIEW_REQUIRED") return "review required";
+  return undefined;
+}
+
+/** Check runs whose conclusion counts as passing. */
+const PASSING_CONCLUSIONS = new Set(["SUCCESS", "NEUTRAL", "SKIPPED"]);
+
+/**
+ * Counts a status check rollup into passed, failed and pending. A check run
+ * that has not completed is pending; a commit status reports its state directly.
+ *
+ * @param rollup - What `gh` printed as the rollup, when it printed one.
+ */
+function checksFrom(rollup: GhCheck[] | null | undefined): ProposalChecks | undefined {
+  if (rollup === null || rollup === undefined || rollup.length === 0) return undefined;
+  const counts: ProposalChecks = { passed: 0, failed: 0, pending: 0 };
+  for (const check of rollup) {
+    const isStatus =
+      check.__typename === "StatusContext" ||
+      (check.status === undefined && check.state !== undefined);
+    if (isStatus) {
+      if (check.state === "SUCCESS") counts.passed += 1;
+      else if (check.state === "PENDING" || check.state === "EXPECTED") counts.pending += 1;
+      else counts.failed += 1;
+      continue;
+    }
+    if (check.status !== "COMPLETED") counts.pending += 1;
+    else if (PASSING_CONCLUSIONS.has(check.conclusion ?? "")) counts.passed += 1;
+    else counts.failed += 1;
+  }
+  return counts;
 }

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

@@ -27,10 +27,13 @@ import type { FetchLike } from "./http.js";
 
 /**
  * What a provider can do. `fetch` is the read path every provider implements;
- * `submit` is the propose-a-change path, which arrives in a later phase. A
- * provider declares the feature only once it genuinely supports it.
+ * `submit` is the propose-a-change path; `proposals` is looking a proposal up
+ * again afterwards (finding the one a branch already has, reporting its status,
+ * and replacing its title or body), which is what lets `sous repo submit`
+ * handle a proposal's whole life rather than only its first day. A provider
+ * declares a feature only once it genuinely supports it.
  */
-export type ProviderFeature = "fetch" | "submit";
+export type ProviderFeature = "fetch" | "submit" | "proposals";
 
 /**
  * The identifier a repo entry uses to name its provider explicitly. `local` is a
@@ -142,6 +145,70 @@ export type ProposedChange = {
   detail: string;
 };
 
+/** Where a proposal stands: still open, merged, or closed without merging. */
+export type ProposalState = "open" | "merged" | "closed";
+
+/** One proposal, as plain data every provider can describe. */
+export type ProposalSummary = {
+  /** How the provider identifies it, such as a pull request number. */
+  id: string;
+  /** Its address, when the provider reported one. */
+  url?: string;
+  /** Where it stands. */
+  state: ProposalState;
+  /** Its current title. */
+  title: string;
+  /** True when it is a draft. */
+  draft: boolean;
+  /** The branch it targets, when the provider reported it. */
+  base?: string;
+};
+
+/** Which proposal to look for: the one a branch was pushed for. */
+export type ProposalQuery = {
+  /** The branch the change is on. */
+  branch: string;
+  /**
+   * True when the branch lives on a fork rather than in the repository itself.
+   * A proposal from a fork is found by the fork's owner as well as the branch,
+   * so two contributors' branches of the same name are never confused.
+   */
+  fromFork: boolean;
+  /**
+   * The account the fork lives under, when the caller knows it. Left out, the
+   * provider asks the host which account is signed in.
+   */
+  forkOwner?: string;
+};
+
+/** How a proposal's review is going, in words every host can be mapped onto. */
+export type ProposalReview = "approved" | "changes requested" | "review required";
+
+/** How the automated checks on a proposal stand, counted. */
+export type ProposalChecks = {
+  passed: number;
+  failed: number;
+  pending: number;
+};
+
+/** Everything a status report says about one proposal. */
+export type ProposalStatus = {
+  /** The proposal itself. */
+  proposal: ProposalSummary;
+  /** How its review is going, when the host reports it. */
+  review?: ProposalReview;
+  /** How its checks stand, when it has any. */
+  checks?: ProposalChecks;
+  /** Whether it can be merged as it stands; undefined when the host is still working it out. */
+  mergeable?: boolean;
+};
+
+/** What to replace on an open proposal. A field left out is left as it is. */
+export type ProposalUpdate = {
+  title?: string;
+  body?: string;
+};
+
 /** One repository host sous knows how to read from. */
 export interface RepoProvider {
   /** The provider's stable identifier, as written in a repo config entry. */
@@ -196,6 +263,55 @@ export interface RepoProvider {
     proposal: ChangeProposal,
     options?: ProviderOptions
   ): Promise<ProposedChange>;
+
+  // --- Proposals after the fact, answered by a provider that declares `proposals`
+
+  /**
+   * The proposal a branch was pushed for, or undefined when it has none. When a
+   * branch has had several, the open one wins, and otherwise the newest.
+   */
+  findProposal?(
+    repo: CanonicalRepo,
+    query: ProposalQuery,
+    options?: ProviderOptions
+  ): Promise<ProposalSummary | undefined>;
+  /** Where one proposal stands: its state, its review and its checks. */
+  proposalStatus?(
+    repo: CanonicalRepo,
+    id: string,
+    options?: ProviderOptions
+  ): Promise<ProposalStatus>;
+  /** Replaces an open proposal's title, its body, or both. */
+  updateProposal?(
+    repo: CanonicalRepo,
+    id: string,
+    update: ProposalUpdate,
+    options?: ProviderOptions
+  ): Promise<ProposedChange>;
+}
+
+/**
+ * A provider that can find a proposal again, report on it and change its text.
+ * This is what declaring the `proposals` feature promises.
+ */
+export type ProposalCapableProvider = RepoProvider &
+  Required<Pick<RepoProvider, "findProposal" | "proposalStatus" | "updateProposal">>;
+
+/**
+ * True when a provider declares the `proposals` feature and really does answer
+ * all three calls behind it.
+ *
+ * @param provider - The provider to test.
+ */
+export function supportsProposals(
+  provider: RepoProvider
+): provider is ProposalCapableProvider {
+  return (
+    provider.features.includes("proposals") &&
+    typeof provider.findProposal === "function" &&
+    typeof provider.proposalStatus === "function" &&
+    typeof provider.updateProposal === "function"
+  );
 }
 
 /**