@effected/github 0.5.0 → 0.6.1

package/CheckRun.js

@@ -1,5 +1,6 @@
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
+import { numericId } from "./internal/ids.js";
 import { Cause, Context, Effect, Exit, Layer, Ref, Schema } from "effect";
 
 //#region src/CheckRun.ts
@@ -197,7 +198,7 @@ const concludeFor = (name, id, exit, recorded, complete) => {
 	return Exit.isSuccess(exit) ? write : Effect.ignore(write);
 };
 const refOf = (raw) => CheckRunRef.make({
-	id: raw.id,
+	id: numericId(raw.id),
 	name: raw.name,
 	url: raw.html_url ?? "",
 	status: raw.status

package/GitHubApp.js

@@ -1,6 +1,7 @@
 import { GitHubError } from "./GitHubError.js";
 import { GitHubGraphQLError } from "./GraphQL.js";
 import { GitHubClient, makeClientShape } from "./GitHubClient.js";
+import { numericId } from "./internal/ids.js";
 import { Clock, Context, DateTime, Duration, Effect, Layer, Option, Redacted, Ref, Schema, Stream } from "effect";
 import githubAppJwt from "universal-github-app-jwt";
 
@@ -261,7 +262,7 @@ function makeApp(options) {
 	return Effect.sync(() => {
 		const installations = Effect.fn("GitHubApp.installations")(function* (credentials) {
 			return (yield* (yield* asApp(credentials, options)).paginate("GET /app/installations", {}).pipe(Effect.catch(appFailure("installation")))).map((entry) => Installation.make({
-				id: entry.id,
+				id: numericId(entry.id),
 				...entry.account !== null && entry.account !== void 0 && "login" in entry.account ? { account: entry.account.login } : {}
 			}));
 		});
@@ -304,7 +305,7 @@ function makeApp(options) {
 				return AppIdentity.make({
 					slug,
 					name,
-					...Option.isSome(user) ? { userId: user.value.id } : {}
+					...Option.isSome(user) ? { userId: numericId(user.value.id) } : {}
 				});
 			}),
 			installations

package/GitHubIssue.js

@@ -1,6 +1,8 @@
 import { GraphQLDocument } from "./GraphQL.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
+import { numericId } from "./internal/ids.js";
+import { CommentRecord } from "./PullRequestComment.js";
 import { Context, Effect, Layer, Schema } from "effect";
 
 //#region src/GitHubIssue.ts
@@ -42,6 +44,22 @@ var LinkedIssue = class extends Schema.Class("LinkedIssue")({
 	*/
 	userLinked: Schema.Boolean
 }) {};
+/**
+* What {@link GitHubIssueShape.commentOnce} found or wrote.
+*
+* @remarks
+* `wrote` is the field the caller branches on: `true` means this call created
+* the comment, `false` means the marker was already on the issue and nothing
+* was posted. Either way `comment` is the marked comment itself.
+*
+* @public
+*/
+var CommentOnceResult = class extends Schema.Class("CommentOnceResult")({
+	/** Did this call post the comment (`true`), or find it already there (`false`)? */
+	wrote: Schema.Boolean,
+	/** The marked comment — the one created, or the one that made us skip. */
+	comment: CommentRecord
+}) {};
 const IssueNodes = Schema.Struct({
 	id: Schema.String,
 	number: Schema.Int,
@@ -98,6 +116,7 @@ var GitHubIssue = class GitHubIssue extends Context.Service()("@effected/github/
 		list: overrides.list ?? (() => unstubbed("list")),
 		close: overrides.close ?? (() => unstubbed("close")),
 		comment: overrides.comment ?? (() => unstubbed("comment")),
+		commentOnce: overrides.commentOnce ?? (() => unstubbed("commentOnce")),
 		linkedIssues: overrides.linkedIssues ?? (() => unstubbed("linkedIssues")),
 		isCrossReferencedBy: overrides.isCrossReferencedBy ?? (() => unstubbed("isCrossReferencedBy"))
 	});
@@ -194,13 +213,52 @@ const make = (client) => ({
 			repo,
 			number
 		});
-		return (yield* client.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", {
+		const created = yield* client.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", {
 			owner,
 			repo,
 			issue_number: number,
 			body,
 			headers: API_VERSION_HEADERS
-		})).id;
+		});
+		return numericId(created.id);
+	}),
+	commentOnce: Effect.fn("GitHubIssue.commentOnce")(function* (issueNumber, marker, body) {
+		const { owner, repo } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({
+			owner,
+			repo,
+			issueNumber,
+			marker: marker.key
+		});
+		const existing = (yield* client.paginate("GET /repos/{owner}/{repo}/issues/{issue_number}/comments", {
+			owner,
+			repo,
+			issue_number: issueNumber,
+			headers: API_VERSION_HEADERS
+		})).find((comment) => marker.matches(comment.body ?? ""));
+		if (existing !== void 0) return CommentOnceResult.make({
+			wrote: false,
+			comment: CommentRecord.make({
+				id: numericId(existing.id),
+				body: existing.body ?? "",
+				url: existing.html_url
+			})
+		});
+		const created = yield* client.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", {
+			owner,
+			repo,
+			issue_number: issueNumber,
+			body: `${body}\n\n${marker.html}`,
+			headers: API_VERSION_HEADERS
+		});
+		return CommentOnceResult.make({
+			wrote: true,
+			comment: CommentRecord.make({
+				id: numericId(created.id),
+				body: created.body ?? "",
+				url: created.html_url
+			})
+		});
 	}),
 	linkedIssues: Effect.fn("GitHubIssue.linkedIssues")(function* (prNumber) {
 		const { owner, repo } = yield* Repo;
@@ -241,4 +299,4 @@ const make = (client) => ({
 });
 
 //#endregion
-export { GitHubIssue, IssueInfo, LinkedIssue };
+export { CommentOnceResult, GitHubIssue, IssueInfo, LinkedIssue };

package/IssueReferences.js

@@ -0,0 +1,126 @@
+import { Option } from "effect";
+
+//#region src/IssueReferences.ts
+/**
+* GitHub's closing-keyword issue-reference grammar, as pure functions.
+*
+* @remarks
+* GitHub links an issue to a pull request when the PR's description carries
+* `<keyword> #<number>` for one of nine documented keywords. Consumers speak
+* that grammar in two distinct dialects, and this module models exactly those
+* two — no service, no layer, nothing but strings in and values out:
+*
+* - **Inline-in-prose** ({@link harvestIssueReferences}): a reference may appear anywhere in
+*   running text — `"fixes #12 and closes #13"` — with mandatory whitespace
+*   and **no colon**, because that is the spelling GitHub itself scans PR
+*   bodies for. This is the dialect a release pipeline harvests from commit
+*   subjects and PR descriptions.
+* - **Bare-line** ({@link parseBareLineReference}): the whole line, after trimming, *is*
+*   the reference — `"Closes: #12"` — with an **optional colon**, because a
+*   generated references region writes one reference per line and a colon
+*   reads better there. GitHub does not require the colon; the region format
+*   allows it, so the parser must too. The dialects differ because their
+*   producers do: prose is written by humans for GitHub's scanner, the region
+*   is written by tooling for humans.
+*
+* Deliberately out of scope this round: cross-repo references
+* (`owner/repo#N`) and full-URL references
+* (`https://github.com/owner/repo/issues/N`). Both are real GitHub spellings;
+* neither dialect's consumers emit them yet, and guessing at their shape here
+* would freeze an API nobody has driven.
+*/
+/**
+* The nine closing keywords GitHub documents, lowercased.
+*
+* @public
+*/
+const CLOSING_KEYWORDS = [
+	"close",
+	"closes",
+	"closed",
+	"fix",
+	"fixes",
+	"fixed",
+	"resolve",
+	"resolves",
+	"resolved"
+];
+/**
+* Both patterns derive from {@link CLOSING_KEYWORDS} so the constant and the
+* grammar cannot drift. Alternation order is safe: the regex engine backtracks
+* through alternatives, so `close` matching inside `closes` fails at the
+* mandatory `#`-introducer and retries the longer keyword.
+*/
+const KEYWORDS = CLOSING_KEYWORDS.join("|");
+/** Inline-in-prose: mandatory whitespace, no colon. */
+const INLINE_PATTERN = new RegExp(`\\b(${KEYWORDS})\\s+#(\\d+)`, "gi");
+/**
+* Bare-line: optional colon, then mandatory same-line whitespace. `[ \t]`
+* rather than `\s`, so an embedded newline cannot smuggle two lines past a
+* parser whose contract is one.
+*/
+const BARE_LINE_PATTERN = new RegExp(`^(${KEYWORDS}):?[ \\t]+#(\\d+)$`, "i");
+/**
+* `#<digits>` parsed to a number — or `undefined` when the digits exceed
+* `Number.MAX_SAFE_INTEGER`, because a silently rounded issue number is worse
+* than a skipped match. Callers skip such matches; they do not fail.
+*/
+const safeIssueNumber = (digits) => {
+	const value = Number(digits);
+	return Number.isSafeInteger(value) ? value : void 0;
+};
+/**
+* Every inline closing reference in `text`, in document order.
+*
+* @remarks
+* The **inline-in-prose** dialect: case-insensitive `<keyword> #<number>`
+* anywhere in the text, whitespace mandatory, colon not accepted — a colon
+* spelling belongs to the bare-line dialect and {@link parseBareLineReference}.
+* Duplicates are preserved: whether `fixes #1, fixes #1` means one reference
+* or two is the caller's business, not a parser's.
+*
+* A match whose digits exceed `Number.MAX_SAFE_INTEGER` is skipped, not
+* misparsed — see the module remarks for the scope boundary.
+*
+* @public
+*/
+const harvestIssueReferences = (text) => {
+	const references = [];
+	for (const match of text.matchAll(INLINE_PATTERN)) {
+		const issueNumber = safeIssueNumber(match[2] ?? "");
+		if (issueNumber === void 0) continue;
+		references.push({
+			issueNumber,
+			keyword: (match[1] ?? "").toLowerCase(),
+			start: match.index,
+			end: match.index + match[0].length
+		});
+	}
+	return references;
+};
+/**
+* The reference a whole line carries, or `Option.none()`.
+*
+* @remarks
+* The **bare-line** dialect: after trimming, the entire line must be
+* `<keyword>[:] #<number>` — keyword case-insensitive, colon optional,
+* whitespace before the `#` mandatory. Trailing prose, a missing keyword, or
+* anything else at all is a rejection, never a partial parse; a line carries
+* one reference or none. Digits past `Number.MAX_SAFE_INTEGER` reject too,
+* for the same reason {@link harvestIssueReferences} skips them.
+*
+* @public
+*/
+const parseBareLineReference = (line) => {
+	const match = BARE_LINE_PATTERN.exec(line.trim());
+	if (match === null) return Option.none();
+	const issueNumber = safeIssueNumber(match[2] ?? "");
+	if (issueNumber === void 0) return Option.none();
+	return Option.some({
+		issueNumber,
+		keyword: (match[1] ?? "").toLowerCase()
+	});
+};
+
+//#endregion
+export { CLOSING_KEYWORDS, harvestIssueReferences, parseBareLineReference };

package/PullRequestComment.js

@@ -1,5 +1,6 @@
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
+import { numericId } from "./internal/ids.js";
 import { Context, Effect, Layer, Option, Schema } from "effect";
 
 //#region src/PullRequestComment.ts
@@ -61,7 +62,7 @@ const unstubbed = (member) => {
 	throw new Error(`PullRequestComment.makeTest: ${member}() was called but not stubbed — pass an override.`);
 };
 const recordOf = (raw) => CommentRecord.make({
-	id: raw.id,
+	id: numericId(raw.id),
 	body: raw.body ?? "",
 	url: raw.html_url
 });

package/README.md

@@ -101,6 +101,45 @@ const program = Effect.gen(function* () {
 
 `GitTag.latestSemver` walks tags and picks the newest version-shaped one in a single pass, over `@effected/semver`'s synchronous comparator — no round trip per candidate. `PullRequest.upsert` and `PullRequestComment.upsert` (a marker-tagged sticky comment) follow the same one-call-one-intent shape.
 
+## Issues and closing references
+
+`GitHubIssue` covers issues: read, list, create, close, comment, and the GraphQL side that answers which issues a pull request closes. `commentOnce` is the create-or-skip counterpart to `PullRequestComment.upsert` — it posts a marked comment and never edits one, which is what you want for an announcement that would read as a rewrite of history if it changed after the fact:
+
+```ts
+import { CommentMarker, GitHubIssue } from "@effected/github";
+import { Effect } from "effect";
+
+const marker = CommentMarker.make({ namespace: "release-bot", key: "shipped" });
+
+const program = Effect.gen(function* () {
+  const issues = yield* GitHubIssue;
+  return yield* issues.commentOnce(1873, marker, "Shipped in the release just published.");
+});
+// CommentOnceResult — `wrote: true` when this call posted the comment,
+// `wrote: false` when the marker was already there and nothing was sent.
+// `comment` is the marked comment either way.
+```
+
+The existence check pages the issue's comments to the end and matches the marker in `upsert`'s exact spelling, so a comment either member writes stays findable by the other. It is a look-before-write: two runs racing on the same issue can both see no marker and both post, so treat the marker as the record rather than the check as a lock.
+
+Whether a run should comment at all usually turns on which issues a pull request closes, and that is a grammar rather than an API call. `IssueReferences` is that grammar as plain functions — no service, no layer, nothing but strings in — in the two dialects consumers actually write:
+
+```ts
+import { harvestIssueReferences, parseBareLineReference } from "@effected/github";
+
+console.log(harvestIssueReferences("Fixes #12 and closes #13."));
+// [ { issueNumber: 12, keyword: "fixes", start: 0, end: 9 },
+//   { issueNumber: 13, keyword: "closes", start: 14, end: 24 } ]
+
+console.log(parseBareLineReference("Closes: #12"));
+// Option.some({ issueNumber: 12, keyword: "closes" })
+
+console.log(parseBareLineReference("closes #12 for real"));
+// Option.none() — the bare-line dialect takes the whole line or nothing
+```
+
+`harvestIssueReferences` reads the **inline-in-prose** dialect: one of the nine closing keywords (`CLOSING_KEYWORDS`) followed by whitespace and `#<number>`, anywhere in the text, no colon — the spelling GitHub itself scans a pull request body for. Duplicates come back as written, because whether `fixes #1, fixes #1` means one intent or two is the caller's question. `parseBareLineReference` reads the **bare-line** dialect, where the whole trimmed line is the reference and the colon is optional — the shape a generated references block writes, one per line. Cross-repo (`owner/repo#12`) and full-URL references are out of scope.
+
 ## Repository configuration
 
 Six services cover the half of a repository that is policy rather than content: `RepositorySecret`, `RepositoryVariable`, `Ruleset`, `DeploymentEnvironment`, `RepositorySecurity` and `CodeScanning`. They are shaped for a program applying the same configuration across a fleet, so every list read paginates to the end and a truncated page never becomes a wrong decision.
@@ -233,6 +272,8 @@ const TestClient = GitHubClient.layerFixture(fixtures);
 - `GitBranch` / `GitTag` — Git Database API refs, with `upsert` collapsing the create-or-reset dance to one call and `GitTag.latestSemver` picking the newest version-shaped tag in one pass.
 - `CheckRun` — `withCheckRun` concludes on every exit path; `CheckRunOutput.truncated()` cuts rendered output to GitHub's byte limits.
 - `PullRequest` / `PullRequestComment` — upserts for both, `listFiles` answering with the same full `CommitFile` records a commit read returns, `headSha`/`baseSha` on `PullRequestInfo`, plus `CommentMarker` for finding a sticky comment again.
+- `GitHubIssue` — issues and their comments, including `commentOnce` for a marked comment that is posted exactly once and never edited, and `linkedIssues` for what a pull request closes.
+- `IssueReferences` — GitHub's nine closing keywords as pure functions: `harvestIssueReferences` for references inline in prose, `parseBareLineReference` for one-per-line generated ones.
 - `GitHubRelease` — releases and asset uploads, including the one route (`uploadAsset`, with the endpoint's optional display label) outside GitHub's generated endpoint map.
 - `RepositorySecret` / `RepositoryVariable` — repository and environment secrets and variables, with the sealed-box encryption GitHub's secrets API demands kept in one module nothing else imports.
 - `Ruleset` / `DeploymentEnvironment` / `RepositorySecurity` / `CodeScanning` — the rest of the configuration tier: rulesets matched by name and scope, idempotent environment writes, the three security toggles GitHub keeps off the repository endpoint, and CodeQL default setup with the language detection that gates it.

package/index.d.ts

@@ -1945,6 +1945,85 @@ declare class GitHubContent extends GitHubContent_base {
   static readonly layerTest: (overrides?: Partial<GitHubContentShape>) => Layer.Layer<GitHubContent>;
 }
 //#endregion
+//#region src/PullRequestComment.d.ts
+declare const CommentMarker_base: Schema.Class<CommentMarker, Schema.Struct<{
+  /** Whose comments these are, e.g. your action's name. */
+  readonly namespace: Schema.NonEmptyString;
+  /** Which comment, within that namespace. */
+  readonly key: Schema.NonEmptyString;
+}>, {}>;
+/**
+ * The hidden marker that makes a comment findable again.
+ *
+ * @remarks
+ * A pure class, not a hardcoded string. The surface this replaces baked
+ * `<!-- savvy-web:${key} -->` into the library — one vendor's name, inside a
+ * package meant to be general. Here the namespace is the caller's, the marker is
+ * testable without a client, and the library has no opinion about whose comments
+ * these are.
+ *
+ * @public
+ */
+declare class CommentMarker extends CommentMarker_base {
+  /** The HTML comment appended to a body so the comment can be found again. */
+  get html(): string;
+  /** Does this body carry the marker? */
+  matches(body: string): boolean;
+}
+declare const CommentRecord_base: Schema.Class<CommentRecord, Schema.Struct<{
+  readonly id: Schema.Int;
+  readonly body: Schema.String;
+  readonly url: Schema.String;
+}>, {}>;
+/**
+ * A comment this package wrote or found.
+ *
+ * @public
+ */
+declare class CommentRecord extends CommentRecord_base {}
+/**
+ * Sticky comments on a pull request or issue.
+ *
+ * @public
+ */
+interface PullRequestCommentShape {
+  /** Post a new comment. */
+  readonly create: (issueNumber: number, body: string) => Effect.Effect<CommentRecord, GitHubError, Repo>;
+  /**
+   * Update the marked comment if there is one, or post it.
+   *
+   * @remarks
+   * The marker is appended to the body, so a comment written by `upsert` is
+   * always findable by the same marker afterwards.
+   */
+  readonly upsert: (issueNumber: number, marker: CommentMarker, body: string) => Effect.Effect<CommentRecord, GitHubError, Repo>;
+  /**
+   * Find the marked comment.
+   *
+   * @remarks
+   * **Paginates.** The version this replaces requested a single page of 100 and
+   * stopped, so on a busy pull request the marker silently vanished and every
+   * update posted a new comment instead.
+   */
+  readonly find: (issueNumber: number, marker: CommentMarker, options?: {
+    readonly page?: PageOptions | undefined;
+  }) => Effect.Effect<Option.Option<CommentRecord>, GitHubError, Repo>;
+  readonly delete: (commentId: number) => Effect.Effect<void, GitHubError, Repo>;
+}
+declare const PullRequestComment_base: Context.ServiceClass<PullRequestComment, "@effected/github/PullRequestComment", PullRequestCommentShape>;
+/**
+ * Sticky comments.
+ *
+ * @public
+ */
+declare class PullRequestComment extends PullRequestComment_base {
+  static readonly layer: Layer.Layer<PullRequestComment, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<PullRequestCommentShape>) => PullRequestCommentShape;
+  /** {@link PullRequestComment.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<PullRequestCommentShape>) => Layer.Layer<PullRequestComment>;
+}
+//#endregion
 //#region src/GitHubIssue.d.ts
 declare const IssueInfo_base: Schema.Class<IssueInfo, Schema.Struct<{
   readonly number: Schema.Int;
@@ -1986,6 +2065,23 @@ declare const LinkedIssue_base: Schema.Class<LinkedIssue, Schema.Struct<{
  * @public
  */
 declare class LinkedIssue extends LinkedIssue_base {}
+declare const CommentOnceResult_base: Schema.Class<CommentOnceResult, Schema.Struct<{
+  /** Did this call post the comment (`true`), or find it already there (`false`)? */
+  readonly wrote: Schema.Boolean;
+  /** The marked comment — the one created, or the one that made us skip. */
+  readonly comment: typeof CommentRecord;
+}>, {}>;
+/**
+ * What {@link GitHubIssueShape.commentOnce} found or wrote.
+ *
+ * @remarks
+ * `wrote` is the field the caller branches on: `true` means this call created
+ * the comment, `false` means the marker was already on the issue and nothing
+ * was posted. Either way `comment` is the marked comment itself.
+ *
+ * @public
+ */
+declare class CommentOnceResult extends CommentOnceResult_base {}
 /**
  * Issues.
  *
@@ -2001,6 +2097,28 @@ interface GitHubIssueShape {
   readonly close: (number: number, reason?: "completed" | "not_planned") => Effect.Effect<void, GitHubError, Repo>;
   /** Post a comment. */
   readonly comment: (number: number, body: string) => Effect.Effect<number, GitHubError, Repo>;
+  /**
+   * Post a marked comment once: create it, or skip if it already exists.
+   *
+   * @remarks
+   * Create-or-skip, **never edit** — the counterpart to
+   * `PullRequestComment.upsert`, which edits in place. The marker is appended
+   * to the body exactly as `upsert` formats it, so a comment either member
+   * writes stays findable by the other.
+   *
+   * The check-then-create is **not atomic** — GitHub offers no conditional
+   * create, so two callers racing the same issue can both observe no marker
+   * and both post. The guard is idempotence across *sequential* invocations
+   * (a re-run workflow, the motivating case), not mutual exclusion across
+   * concurrent ones; a caller needing the latter must serialize externally.
+   *
+   * The existence check is the comment itself: the issue's comments are
+   * paginated and the first body carrying the marker means skip. That is the
+   * guard {@link GitHubIssueShape.isCrossReferencedBy}'s docstring tells you
+   * to build — an issue reached via `linkedIssues` is cross-referenced from
+   * the outset, so only the marker answers "have I commented yet?".
+   */
+  readonly commentOnce: (issueNumber: number, marker: CommentMarker, body: string) => Effect.Effect<CommentOnceResult, GitHubError, Repo>;
   /** The issues a pull request closes, with `userLinked` telling you who linked them. */
   readonly linkedIssues: (prNumber: number) => Effect.Effect<ReadonlyArray<LinkedIssue>, GitHubGraphQLError, Repo>;
   /**
@@ -2431,6 +2549,108 @@ declare class GitTag extends GitTag_base {
   static readonly layerTest: (overrides?: Partial<GitTagShape>) => Layer.Layer<GitTag>;
 }
 //#endregion
+//#region src/IssueReferences.d.ts
+/**
+ * GitHub's closing-keyword issue-reference grammar, as pure functions.
+ *
+ * @remarks
+ * GitHub links an issue to a pull request when the PR's description carries
+ * `<keyword> #<number>` for one of nine documented keywords. Consumers speak
+ * that grammar in two distinct dialects, and this module models exactly those
+ * two — no service, no layer, nothing but strings in and values out:
+ *
+ * - **Inline-in-prose** ({@link harvestIssueReferences}): a reference may appear anywhere in
+ *   running text — `"fixes #12 and closes #13"` — with mandatory whitespace
+ *   and **no colon**, because that is the spelling GitHub itself scans PR
+ *   bodies for. This is the dialect a release pipeline harvests from commit
+ *   subjects and PR descriptions.
+ * - **Bare-line** ({@link parseBareLineReference}): the whole line, after trimming, *is*
+ *   the reference — `"Closes: #12"` — with an **optional colon**, because a
+ *   generated references region writes one reference per line and a colon
+ *   reads better there. GitHub does not require the colon; the region format
+ *   allows it, so the parser must too. The dialects differ because their
+ *   producers do: prose is written by humans for GitHub's scanner, the region
+ *   is written by tooling for humans.
+ *
+ * Deliberately out of scope this round: cross-repo references
+ * (`owner/repo#N`) and full-URL references
+ * (`https://github.com/owner/repo/issues/N`). Both are real GitHub spellings;
+ * neither dialect's consumers emit them yet, and guessing at their shape here
+ * would freeze an API nobody has driven.
+ */
+/**
+ * The nine closing keywords GitHub documents, lowercased.
+ *
+ * @public
+ */
+declare const CLOSING_KEYWORDS: readonly ["close", "closes", "closed", "fix", "fixes", "fixed", "resolve", "resolves", "resolved"];
+/**
+ * One of the nine documented closing keywords, in canonical lowercase form.
+ *
+ * @public
+ */
+type ClosingKeyword = (typeof CLOSING_KEYWORDS)[number];
+/**
+ * One closing reference found in prose by {@link harvestIssueReferences}.
+ *
+ * @public
+ */
+interface IssueReference {
+  /** The referenced issue number. */
+  readonly issueNumber: number;
+  /** The matched keyword, lowercased to its canonical form. */
+  readonly keyword: ClosingKeyword;
+  /** Offset of the first character of the whole match (`keyword` through digits). */
+  readonly start: number;
+  /** Offset one past the last character of the whole match. */
+  readonly end: number;
+}
+/**
+ * The closing reference a bare line carries, per {@link parseBareLineReference}.
+ *
+ * @remarks
+ * No offsets: in the bare-line dialect the whole line is the reference, so
+ * positions within it locate nothing a caller acts on.
+ *
+ * @public
+ */
+interface BareLineReference {
+  /** The referenced issue number. */
+  readonly issueNumber: number;
+  /** The matched keyword, lowercased to its canonical form. */
+  readonly keyword: ClosingKeyword;
+}
+/**
+ * Every inline closing reference in `text`, in document order.
+ *
+ * @remarks
+ * The **inline-in-prose** dialect: case-insensitive `<keyword> #<number>`
+ * anywhere in the text, whitespace mandatory, colon not accepted — a colon
+ * spelling belongs to the bare-line dialect and {@link parseBareLineReference}.
+ * Duplicates are preserved: whether `fixes #1, fixes #1` means one reference
+ * or two is the caller's business, not a parser's.
+ *
+ * A match whose digits exceed `Number.MAX_SAFE_INTEGER` is skipped, not
+ * misparsed — see the module remarks for the scope boundary.
+ *
+ * @public
+ */
+declare const harvestIssueReferences: (text: string) => ReadonlyArray<IssueReference>;
+/**
+ * The reference a whole line carries, or `Option.none()`.
+ *
+ * @remarks
+ * The **bare-line** dialect: after trimming, the entire line must be
+ * `<keyword>[:] #<number>` — keyword case-insensitive, colon optional,
+ * whitespace before the `#` mandatory. Trailing prose, a missing keyword, or
+ * anything else at all is a rejection, never a partial parse; a line carries
+ * one reference or none. Digits past `Number.MAX_SAFE_INTEGER` reject too,
+ * for the same reason {@link harvestIssueReferences} skips them.
+ *
+ * @public
+ */
+declare const parseBareLineReference: (line: string) => Option.Option<BareLineReference>;
+//#endregion
 //#region src/PullRequest.d.ts
 /** How a pull request is merged. @public */
 declare const MergeMethod: Schema.Literals<readonly ["merge", "squash", "rebase"]>;
@@ -2602,85 +2822,6 @@ declare class PullRequest extends PullRequest_base {
   static readonly layerTest: (overrides?: Partial<PullRequestShape>) => Layer.Layer<PullRequest>;
 }
 //#endregion
-//#region src/PullRequestComment.d.ts
-declare const CommentMarker_base: Schema.Class<CommentMarker, Schema.Struct<{
-  /** Whose comments these are, e.g. your action's name. */
-  readonly namespace: Schema.NonEmptyString;
-  /** Which comment, within that namespace. */
-  readonly key: Schema.NonEmptyString;
-}>, {}>;
-/**
- * The hidden marker that makes a comment findable again.
- *
- * @remarks
- * A pure class, not a hardcoded string. The surface this replaces baked
- * `<!-- savvy-web:${key} -->` into the library — one vendor's name, inside a
- * package meant to be general. Here the namespace is the caller's, the marker is
- * testable without a client, and the library has no opinion about whose comments
- * these are.
- *
- * @public
- */
-declare class CommentMarker extends CommentMarker_base {
-  /** The HTML comment appended to a body so the comment can be found again. */
-  get html(): string;
-  /** Does this body carry the marker? */
-  matches(body: string): boolean;
-}
-declare const CommentRecord_base: Schema.Class<CommentRecord, Schema.Struct<{
-  readonly id: Schema.Int;
-  readonly body: Schema.String;
-  readonly url: Schema.String;
-}>, {}>;
-/**
- * A comment this package wrote or found.
- *
- * @public
- */
-declare class CommentRecord extends CommentRecord_base {}
-/**
- * Sticky comments on a pull request or issue.
- *
- * @public
- */
-interface PullRequestCommentShape {
-  /** Post a new comment. */
-  readonly create: (issueNumber: number, body: string) => Effect.Effect<CommentRecord, GitHubError, Repo>;
-  /**
-   * Update the marked comment if there is one, or post it.
-   *
-   * @remarks
-   * The marker is appended to the body, so a comment written by `upsert` is
-   * always findable by the same marker afterwards.
-   */
-  readonly upsert: (issueNumber: number, marker: CommentMarker, body: string) => Effect.Effect<CommentRecord, GitHubError, Repo>;
-  /**
-   * Find the marked comment.
-   *
-   * @remarks
-   * **Paginates.** The version this replaces requested a single page of 100 and
-   * stopped, so on a busy pull request the marker silently vanished and every
-   * update posted a new comment instead.
-   */
-  readonly find: (issueNumber: number, marker: CommentMarker, options?: {
-    readonly page?: PageOptions | undefined;
-  }) => Effect.Effect<Option.Option<CommentRecord>, GitHubError, Repo>;
-  readonly delete: (commentId: number) => Effect.Effect<void, GitHubError, Repo>;
-}
-declare const PullRequestComment_base: Context.ServiceClass<PullRequestComment, "@effected/github/PullRequestComment", PullRequestCommentShape>;
-/**
- * Sticky comments.
- *
- * @public
- */
-declare class PullRequestComment extends PullRequestComment_base {
-  static readonly layer: Layer.Layer<PullRequestComment, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
-  static readonly makeTest: (overrides?: Partial<PullRequestCommentShape>) => PullRequestCommentShape;
-  /** {@link PullRequestComment.makeTest} behind a `Layer`. */
-  static readonly layerTest: (overrides?: Partial<PullRequestCommentShape>) => Layer.Layer<PullRequestComment>;
-}
-//#endregion
 //#region src/RepositorySecret.d.ts
 /**
  * Which secret store an operation acts on.
@@ -3239,5 +3380,5 @@ declare class WorkflowDispatch extends WorkflowDispatch_base {
   static readonly layerTest: (overrides?: Partial<WorkflowDispatchShape>) => Layer.Layer<WorkflowDispatch>;
 }
 //#endregion
-export { Annotation, AnnotationLevel, type AppCredentials, AppIdentity, type AppliedSettings, ArtifactMetadata, type ArtifactMetadataShape, Attestation, AttestationListEntry, AttestationRecord, type AttestationShape, BotIdentity, type BranchOutcome, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, type CheckRunShape, CodeScanning, type CodeScanningSetup, type CodeScanningShape, CommentMarker, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, type ConcludeCheckRun, DeploymentEnvironment, type DeploymentEnvironmentInfo, type DeploymentEnvironmentShape, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GRAPHQL_ONLY_SETTINGS, GitBranch, type GitBranchShape, GitCommit, type GitCommitShape, GitHubApp, GitHubAppError, type GitHubAppOptions, type GitHubAppShape, GitHubClient, type GitHubClientOptions, type GitHubClientShape, GitHubCommit, type GitHubCommitShape, GitHubContent, type GitHubContentShape, GitHubError, GitHubErrorKind, type GitHubFixtures, GitHubGraphQLError, GitHubIssue, type GitHubIssueShape, GitHubRelease, type GitHubReleaseShape, GitHubRepository, type GitHubRepositoryShape, GitTag, type GitTagShape, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InvalidRepoRefError, IssueInfo, type LatestSemverOptions, LinkedIssue, MergeMethod, type OwnerType, PageOptions, PermissionGap, PermissionLevel, PermissionResult, type PollOptions, PullRequest, PullRequestComment, type PullRequestCommentShape, PullRequestInfo, type PullRequestShape, RateLimitSnapshot, type RecordedCall, ReleaseAsset, ReleaseInfo, Repo, RepoRef, type RepositoryPatch, RepositorySecret, type RepositorySecretShape, RepositorySecurity, type RepositorySecurityShape, type RepositorySettings, RepositoryVariable, type RepositoryVariableShape, type Data as RestData, type RequestExtras as RestExtras, type Item as RestItem, type PaginatingRoute as RestPaginatingRoute, type Params as RestParams, type Response as RestResponse, type Route as RestRoute, RetryPolicy, type RetryableFailure, Ruleset, type RulesetInfo, type RulesetPayload, type RulesetShape, SECURITY_ANALYSIS_STATUS_FIELDS, type SecretInfo, type SecretScope, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, type TokenRequest, type UpsertedPullRequest, type VariableInfo, type VersionFromTag, WorkflowDispatch, type WorkflowDispatchShape, type WorkflowInfo, WorkflowRunStatus, transformSecurityAndAnalysis, versionFromTag };
+export { Annotation, AnnotationLevel, type AppCredentials, AppIdentity, type AppliedSettings, ArtifactMetadata, type ArtifactMetadataShape, Attestation, AttestationListEntry, AttestationRecord, type AttestationShape, type BareLineReference, BotIdentity, type BranchOutcome, CLOSING_KEYWORDS, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, type CheckRunShape, type ClosingKeyword, CodeScanning, type CodeScanningSetup, type CodeScanningShape, CommentMarker, CommentOnceResult, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, type ConcludeCheckRun, DeploymentEnvironment, type DeploymentEnvironmentInfo, type DeploymentEnvironmentShape, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GRAPHQL_ONLY_SETTINGS, GitBranch, type GitBranchShape, GitCommit, type GitCommitShape, GitHubApp, GitHubAppError, type GitHubAppOptions, type GitHubAppShape, GitHubClient, type GitHubClientOptions, type GitHubClientShape, GitHubCommit, type GitHubCommitShape, GitHubContent, type GitHubContentShape, GitHubError, GitHubErrorKind, type GitHubFixtures, GitHubGraphQLError, GitHubIssue, type GitHubIssueShape, GitHubRelease, type GitHubReleaseShape, GitHubRepository, type GitHubRepositoryShape, GitTag, type GitTagShape, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InvalidRepoRefError, IssueInfo, type IssueReference, type LatestSemverOptions, LinkedIssue, MergeMethod, type OwnerType, PageOptions, PermissionGap, PermissionLevel, PermissionResult, type PollOptions, PullRequest, PullRequestComment, type PullRequestCommentShape, PullRequestInfo, type PullRequestShape, RateLimitSnapshot, type RecordedCall, ReleaseAsset, ReleaseInfo, Repo, RepoRef, type RepositoryPatch, RepositorySecret, type RepositorySecretShape, RepositorySecurity, type RepositorySecurityShape, type RepositorySettings, RepositoryVariable, type RepositoryVariableShape, type Data as RestData, type RequestExtras as RestExtras, type Item as RestItem, type PaginatingRoute as RestPaginatingRoute, type Params as RestParams, type Response as RestResponse, type Route as RestRoute, RetryPolicy, type RetryableFailure, Ruleset, type RulesetInfo, type RulesetPayload, type RulesetShape, SECURITY_ANALYSIS_STATUS_FIELDS, type SecretInfo, type SecretScope, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, type TokenRequest, type UpsertedPullRequest, type VariableInfo, type VersionFromTag, WorkflowDispatch, type WorkflowDispatchShape, type WorkflowInfo, WorkflowRunStatus, harvestIssueReferences, parseBareLineReference, transformSecurityAndAnalysis, versionFromTag };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -13,13 +13,14 @@ import { CommitRef, FileChange, FileContent, FileDeletion, FileMode, GitCommit }
 import { AppIdentity, BotIdentity, GitHubApp, GitHubAppError, Installation, InstallationToken } from "./GitHubApp.js";
 import { CommitComparison, CommitFile, CommitSummary, FileStatus, GitHubCommit } from "./GitHubCommit.js";
 import { GitHubContent } from "./GitHubContent.js";
-import { GitHubIssue, IssueInfo, LinkedIssue } from "./GitHubIssue.js";
+import { CommentMarker, CommentRecord, PullRequestComment } from "./PullRequestComment.js";
+import { CommentOnceResult, GitHubIssue, IssueInfo, LinkedIssue } from "./GitHubIssue.js";
 import { GitHubRelease, ReleaseAsset, ReleaseInfo } from "./GitHubRelease.js";
 import { GRAPHQL_ONLY_SETTINGS, GitHubRepository, SECURITY_ANALYSIS_STATUS_FIELDS, transformSecurityAndAnalysis } from "./GitHubRepository.js";
 import { GitTag, SemverTag, TagRef, versionFromTag } from "./GitTag.js";
+import { CLOSING_KEYWORDS, harvestIssueReferences, parseBareLineReference } from "./IssueReferences.js";
 import { PageOptions } from "./Rest.js";
 import { MergeMethod, PullRequest, PullRequestInfo } from "./PullRequest.js";
-import { CommentMarker, CommentRecord, PullRequestComment } from "./PullRequestComment.js";
 import { RepositorySecret } from "./RepositorySecret.js";
 import { RepositorySecurity } from "./RepositorySecurity.js";
 import { RepositoryVariable } from "./RepositoryVariable.js";
@@ -27,4 +28,4 @@ import { Ruleset } from "./Ruleset.js";
 import { ExtraPermission, PermissionGap, PermissionLevel, PermissionResult, TokenPermissionError, TokenPermissions } from "./TokenPermissions.js";
 import { WorkflowDispatch, WorkflowRunStatus } from "./WorkflowDispatch.js";
 
-export { Annotation, AnnotationLevel, AppIdentity, ArtifactMetadata, Attestation, AttestationListEntry, AttestationRecord, BotIdentity, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, CodeScanning, CommentMarker, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, DeploymentEnvironment, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GRAPHQL_ONLY_SETTINGS, GitBranch, GitCommit, GitHubApp, GitHubAppError, GitHubClient, GitHubCommit, GitHubContent, GitHubError, GitHubErrorKind, GitHubGraphQLError, GitHubIssue, GitHubRelease, GitHubRepository, GitTag, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InvalidRepoRefError, IssueInfo, LinkedIssue, MergeMethod, PageOptions, PermissionGap, PermissionLevel, PermissionResult, PullRequest, PullRequestComment, PullRequestInfo, RateLimitSnapshot, ReleaseAsset, ReleaseInfo, Repo, RepoRef, RepositorySecret, RepositorySecurity, RepositoryVariable, RetryPolicy, Ruleset, SECURITY_ANALYSIS_STATUS_FIELDS, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, WorkflowDispatch, WorkflowRunStatus, transformSecurityAndAnalysis, versionFromTag };
+export { Annotation, AnnotationLevel, AppIdentity, ArtifactMetadata, Attestation, AttestationListEntry, AttestationRecord, BotIdentity, CLOSING_KEYWORDS, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, CodeScanning, CommentMarker, CommentOnceResult, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, DeploymentEnvironment, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GRAPHQL_ONLY_SETTINGS, GitBranch, GitCommit, GitHubApp, GitHubAppError, GitHubClient, GitHubCommit, GitHubContent, GitHubError, GitHubErrorKind, GitHubGraphQLError, GitHubIssue, GitHubRelease, GitHubRepository, GitTag, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InvalidRepoRefError, IssueInfo, LinkedIssue, MergeMethod, PageOptions, PermissionGap, PermissionLevel, PermissionResult, PullRequest, PullRequestComment, PullRequestInfo, RateLimitSnapshot, ReleaseAsset, ReleaseInfo, Repo, RepoRef, RepositorySecret, RepositorySecurity, RepositoryVariable, RetryPolicy, Ruleset, SECURITY_ANALYSIS_STATUS_FIELDS, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, WorkflowDispatch, WorkflowRunStatus, harvestIssueReferences, parseBareLineReference, transformSecurityAndAnalysis, versionFromTag };

package/internal/ids.js

@@ -0,0 +1,17 @@
+//#region src/internal/ids.ts
+/**
+* Narrows the `number | bigint` resource ids `@octokit/types` v17 declares
+* back to `number`.
+*
+* GitHub's REST payloads arrive through `JSON.parse`, which never produces a
+* bigint, so at runtime the value is always a number today — the union is
+* upstream future-proofing for ids beyond 2^53. If GitHub ever crosses that
+* line, the `id: number` fields on this package's public records have to be
+* redesigned; a runtime coercion here could not paper over it.
+*
+* Leaf module: imports nothing.
+*/
+const numericId = (id) => Number(id);
+
+//#endregion
+export { numericId };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github",
-	"version": "0.5.0",
+	"version": "0.6.1",
 	"private": false,
 	"description": "Typed GitHub REST and GraphQL services over the octokit core request surface, with app auth and resource helpers.",
 	"keywords": [
@@ -40,8 +40,8 @@
 	"dependencies": {
 		"@effected/semver": "^0.5.0",
 		"@octokit/core": "^7.0.6",
-		"@octokit/plugin-paginate-rest": "^14.0.0",
-		"@octokit/types": "^16.0.0",
+		"@octokit/plugin-paginate-rest": "^15.0.0",
+		"@octokit/types": "^17.0.0",
 		"blakejs": "1.2.1",
 		"tweetnacl": "1.0.3",
 		"universal-github-app-jwt": "^2.2.2"