@sous-io/sous 0.2.15 → 0.2.17

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

@@ -11,7 +11,7 @@ import { ConfigError } from "../../errors.js";
 /** The shape of `fetch` this module needs; the global satisfies it. */
 export type FetchLike = (
   url: string,
-  init?: { headers?: Record<string, string> }
+  init?: { headers?: Record<string, string>; signal?: AbortSignal }
 ) => Promise<{
   ok: boolean;
   status: number;
@@ -36,6 +36,8 @@ export type FetchTextOptions = {
   fetchImpl?: FetchLike;
   /** What the URL is, named in error messages (for example "repo index"). */
   label?: string;
+  /** Cancels the request, for a caller that will not wait past a deadline. */
+  signal?: AbortSignal;
 };
 
 /**
@@ -67,7 +69,10 @@ export async function fetchText(
 
   let response: Awaited<ReturnType<FetchLike>>;
   try {
-    response = await fetchImpl(url, { headers });
+    response = await fetchImpl(
+      url,
+      options.signal === undefined ? { headers } : { headers, signal: options.signal }
+    );
   } catch (error) {
     throw new ConfigError(
       `Sous could not reach ${url} while fetching the ${label}.\n` +

package/src/lib/repos/providers/index-cache.ts

@@ -97,8 +97,13 @@ export type GetIndexOptions = {
    * shown; the identity is used when nothing supplies one.
    */
   label?: string;
+  /** Cancels the request, for a caller that will not wait past a deadline. */
+  signal?: AbortSignal;
 };
 
+/** Which repository to read from upstream, without touching the cache. */
+export type FetchUpstreamOptions = Pick<GetIndexOptions, "url" | "provider" | "signal">;
+
 /** How the cache is built. */
 export type IndexCacheOptions = {
   /** The store's root directory; the cache lives in a subdirectory of it. */
@@ -334,23 +339,7 @@ export class IndexCache {
    * @param options - The repository URL and its provider.
    */
   async refresh(identity: string, options: GetIndexOptions): Promise<IndexLookup> {
-    const provider = this.resolveProvider(options.url, options.provider);
-    const repo = provider.canonicalize(options.url);
-    const fetched = await provider.fetchIndex(repo, this.providerOptions);
-
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(fetched.text);
-    } catch (error) {
-      throw new ConfigError(
-        `The index that ${options.url} published is not valid JSON.\n` +
-          `  ${(error as Error).message}\n` +
-          `  A repository's index is written by 'sous repo release'; this one may be ` +
-          `damaged or may not be a sous repository at all.`
-      );
-    }
-
-    const index = parseIndexFile(parsed, `${options.url} (${fetched.ref})`);
+    const { index, fetched } = await this.fetchFromProvider(options);
     const timestamp = this.now().toISOString();
     const meta: IndexMeta = {
       fetchedAt: timestamp,
@@ -369,6 +358,56 @@ export class IndexCache {
     return { index: this.applyOverlay(identity, index), source: "network", meta };
   }
 
+  /**
+   * Reads a repository's index from upstream and returns it, WITHOUT writing
+   * anything: neither the cached copy nor its sidecar changes. This is what a
+   * browsing command reading upstream uses, because only a command that
+   * resolves versions should change what the cache holds. Any installed overlay
+   * is folded into the answer, as it is for a cached copy. A failure is raised;
+   * the caller decides whether a cached copy stands in for it.
+   *
+   * @param identity - The repository's canonical identity, for the overlay.
+   * @param options - The repository URL, its provider, and an optional cancel signal.
+   */
+  async fetchUpstream(identity: string, options: FetchUpstreamOptions): Promise<IndexFile> {
+    const { index } = await this.fetchFromProvider(options);
+    return this.applyOverlay(identity, index);
+  }
+
+  /**
+   * Fetches and validates a repository's index through its provider. Writes
+   * nothing; `refresh` and `fetchUpstream` decide what happens next.
+   *
+   * @param options - The repository URL, its provider, and an optional cancel signal.
+   */
+  private async fetchFromProvider(
+    options: FetchUpstreamOptions
+  ): Promise<{ index: IndexFile; fetched: { ref: string; etag?: string } }> {
+    const provider = this.resolveProvider(options.url, options.provider);
+    const repo = provider.canonicalize(options.url);
+    const fetched = await provider.fetchIndex(
+      repo,
+      options.signal === undefined
+        ? this.providerOptions
+        : { ...this.providerOptions, signal: options.signal }
+    );
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(fetched.text);
+    } catch (error) {
+      throw new ConfigError(
+        `The index that ${options.url} published is not valid JSON.\n` +
+          `  ${(error as Error).message}\n` +
+          `  A repository's index is written by 'sous repo release'; this one may be ` +
+          `damaged or may not be a sous repository at all.`
+      );
+    }
+
+    const index = parseIndexFile(parsed, `${options.url} (${fetched.ref})`);
+    return { index, fetched };
+  }
+
   /**
    * Forgets a repository's cached index and sidecar, which is what removing a
    * repository from a project does.

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
@@ -67,6 +70,8 @@ export type ProviderOptions = {
   fetchImpl?: FetchLike;
   /** How subprocesses are run. Defaults to spawning a real process. */
   run?: CommandRunner;
+  /** Cancels an index request, for a caller that will not wait past a deadline. */
+  signal?: AbortSignal;
 };
 
 /** What an index fetch returns. */
@@ -140,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. */
@@ -194,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"
+  );
 }
 
 /**