@effected/github 0.2.2 → 0.2.3

package/PullRequest.js

@@ -16,6 +16,16 @@ const MergeMethod = Schema.Literals([
 /**
 * A pull request, projected to what callers read.
 *
+* @remarks
+* This is the **domain** shape, and the only pull-request type this package
+* exports. The wire shape GitHub actually answers with is the private
+* `RawPull` interface further down this module, and the two are deliberately
+* different: `RawPull` nests `head`/`base` as `{ ref, sha }` and spells the
+* link `html_url`, where this class flattens them to `head`/`headSha` and
+* spells it `url`. Reading the wrong one produces code that typechecks against
+* a member set the boundary will never hand it. If you are writing a test
+* double or a fixture, this is the type you build.
+*
 * @public
 */
 var PullRequestInfo = class extends Schema.Class("PullRequestInfo")({

package/index.d.ts

@@ -2067,6 +2067,17 @@ interface GitTagShape {
    * `Effect.result` per parse and another per comparison** to answer this. Both
    * are synchronous in `@effected/semver` (`parseResult`, `compare`), so this is
    * a single pass over the page stream with no round trips at all.
+   *
+   * **"Newest" means highest version, not most recent.** That is the right
+   * answer for a single-versioned repository and the wrong instrument for a
+   * **monorepo publishing independently versioned packages**, where version
+   * ordering and recency are unrelated: a `pkg-a@2.0.0` tag outranks a
+   * `pkg-b@1.4.0` cut yesterday, so the result can sit several releases behind
+   * the actual head and never move. Nothing about the failure is visible —
+   * a stale-but-plausible tag comes back, and one consumer pinned its release
+   * boundary two releases back, permanently. In a monorepo, filter by the
+   * package's tag prefix (see {@link LatestSemverOptions}) so the comparison
+   * runs within one version line, or order by tagged-commit date instead.
    */
   readonly latestSemver: (options?: LatestSemverOptions) => Effect.Effect<Option.Option<SemverTag>, GitHubError, Repo>;
 }
@@ -2123,6 +2134,16 @@ declare const PullRequestInfo_base: Schema.Class<PullRequestInfo, Schema.Struct<
 /**
  * A pull request, projected to what callers read.
  *
+ * @remarks
+ * This is the **domain** shape, and the only pull-request type this package
+ * exports. The wire shape GitHub actually answers with is the private
+ * `RawPull` interface further down this module, and the two are deliberately
+ * different: `RawPull` nests `head`/`base` as `{ ref, sha }` and spells the
+ * link `html_url`, where this class flattens them to `head`/`headSha` and
+ * spells it `url`. Reading the wrong one produces code that typechecks against
+ * a member set the boundary will never hand it. If you are writing a test
+ * double or a fixture, this is the type you build.
+ *
  * @public
  */
 declare class PullRequestInfo extends PullRequestInfo_base {}
@@ -2138,6 +2159,25 @@ interface UpsertedPullRequest {
  */
 interface PullRequestShape {
   readonly get: (number: number) => Effect.Effect<PullRequestInfo, GitHubError, Repo>;
+  /**
+   * Open, closed or all pull requests, optionally filtered.
+   *
+   * @remarks
+   * `head` accepts **either** the qualified `owner:ref` GitHub's filter wants
+   * or a bare `ref`, which is qualified with the current repo's owner on the
+   * way out. So for a pull request opened **from the current repository**,
+   * feeding this method `PullRequestInfo.head` — which is the bare
+   * `raw.head.ref` — round-trips correctly, and a consumer filtering the full
+   * list client-side because the raw REST route ignores an unqualified ref no
+   * longer needs to.
+   *
+   * **The round trip does not hold for a fork-originated pull request.**
+   * `PullRequestInfo` projects only the ref and drops the source owner, so
+   * qualifying it here prefixes the *current* repo's owner and names a branch
+   * in the wrong account — the filter then matches nothing, silently. When the
+   * head may live in a fork, pass a qualified `owner:ref` built from the source
+   * owner rather than from anything this projection carries.
+   */
   readonly list: (options?: {
     readonly head?: string | undefined;
     readonly base?: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github",
-	"version": "0.2.2",
+	"version": "0.2.3",
 	"private": false,
 	"description": "Typed GitHub REST and GraphQL services over the octokit core request surface, with app auth and resource helpers.",
 	"keywords": [
@@ -38,7 +38,7 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/semver": "^0.3.1",
+		"@effected/semver": "^0.3.2",
 		"@octokit/core": "^7.0.6",
 		"@octokit/plugin-paginate-rest": "^14.0.0",
 		"@octokit/types": "^16.0.0",