@shivaedev/github 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.11.0 - 2026-11-03
+
+### Added
+
+- Add `details(summary, text)` to render raw text with escaped HTML and Markdown in both the summary and body.
+- Add `renderSections` to share one UTF-8 byte budget across row lists, reserving headers and an `and N more` paragraph for each truncated section.
+- Export `parseRepositoryAddress` from `repositoryAddress.ts`, returning an Effect `Result` with the address form, repository identity, a pull-request number when present, or a typed `GitHubAddressInvalid` failure.
+
+### Fixed
+
+- Preserve each pagination pacing callback's failure type through raw, decoded, bounded and repository lists.
+- Keep cached pagination links when GitHub omits them from a 304 response, so repeated reads return every page.
+
+### Breaking
+
+- `renderRows` now returns `Result<string, MarkdownBudgetTooSmall>` instead of a string or a thrown `RangeError`. Match the native Effect `Result` with `Result.match`, or convert it with `Effect.fromResult`. Budget failures carry the requested `byteLimit`; import `MarkdownBudgetTooSmall` from `@shivaedev/github/errors.ts`.
+- Initialize the low-level request cache with `yield* requests(rates)` instead of `requests(client, token, rates, refresh)`. Provide `HttpClient`, `GitHubToken` and, when needed, `TokenRefresh` through the Effect environment. The `GitHub` service API is unchanged.
+
+## 0.10.0 - 2026-11-02
+
+### Added
+
+- Add typed, byte-capped issue, user, collaborator-permission, commit, comparison and tree reads, plus paged issue, pull-request-file and commit lists on the GitHub service.
+- Let Schema-aware lists select arrays inside envelopes, pace each request and opt into skipping undecodable items. `listPages` reports decoded items and skipped counts for each page; `listBounded` includes the total `skipped` count alongside `items` and `truncated`. Existing numeric byte-limit arguments remain supported, and decoding still fails by default.
+- `GitHubApp.viewerRepositories(account)` accepts a GitHub account ID or login and returns readable and administrable installed repositories, with access results cached for 60 seconds across at most 100 accounts.
+
+### Fixed
+
+- Preserve configured GitHub API path prefixes in representation reads, lists and writes, App installation discovery and token exchange, and artifact API requests. API origins without a path keep their existing behavior.
+- Keep shared App clients independent of a single-installation Layer's repository and permission scope.
+
+### Breaking
+
+- `downloadArtifactArchive` now returns an array of `{ path, bytes }` files instead of raw ZIP bytes. Install the optional `@zip.js/zip.js` peer and consume these validated files instead of passing the result to an application ZIP reader. Extraction refuses unsafe paths, symlinks, duplicate paths and file/directory conflicts, with distinct typed errors. The default caps are 100 MiB of extracted contents and a per-entry compression ratio of 100:1; set `totalSizeLimit` and `compressionRatioLimit` to change them. The existing `byteLimit` still caps the downloaded ZIP.
+- The low-level `artifacts` constructor now takes `(apiUrl, rates)` and returns an Effect. Yield it with `HttpClient`, `GitHubToken` and `TokenRefresh` provided instead of passing those services as arguments.
+
 ## 0.9.0 - 2026-11-02
 
 ### Added

package/README.md

@@ -16,6 +16,8 @@ const repository = read("/repos/acme/widgets", Repository);
 
 ## Using the client
 
+`parseRepositoryAddress` from `@shivaedev/github/repositoryAddress.ts` parses repository shorthand (`owner/name` or `github:owner/name`), GitHub HTTP(S), Git, SCP-style SSH and `ssh://git@github.com/` remotes, including `git+` prefixes and `.git` suffixes. It trims surrounding whitespace and returns an Effect `Result` containing `{ kind, owner, name, repository, number }`. `kind` distinguishes `remote`, `shorthand` and `pull-request`, so a Git remote reader can reject shorthand that Git treats as a local path. `repository` is `owner/name`; `number` is undefined for repositories and a positive safe integer for canonical `https://github.com/owner/name/pull/number` addresses. Unsupported hosts, malformed addresses and invalid PR numbers return the string-tagged `GitHubAddressInvalid` error from `@shivaedev/github/errors.ts`. PR subpages, queries and fragments are rejected.
+
 `GitHub` is a native Context service declared with `defineService`. Its Layer owns the conditional response cache and resource observations. Provide an Effect `HttpClient` and a `GitHubToken` once, then use the Schema-aware `read`, `list` and `write` functions. Schema decoding services remain visible in their requirements.
 
 ```ts
@@ -76,7 +78,7 @@ const diff = Effect.gen(function* () {
 
 The service's `read(path)` and `write(method, path, body)` return a representation with a generic `decode(schema)` method. Its `list(path)` returns an Effect containing a Stream of page representations. These methods accept the same trailing byte limit: `read(path, byteLimit)`, `write(method, path, body, byteLimit)` and `list(path, beforeRequest, byteLimit)`; pass `undefined` for `beforeRequest` when no pacing callback is needed. Prefer the exported functions for Schema-decoded items. Each page representation exposes `hasNext`, which reports whether its Link header names a next page without fetching it. A caller with a pacing policy can pass `github.list(path, beforeRequest)`: the callback receives the resource name before each page request, and its typed failure stops the stream. `github.resource(path)` returns the observed resource for that path, defaulting to core or search before the first response.
 
-Use `listBounded(path, itemSchema, pageCap, byteLimit?)` to collect a prefix within a positive page cap. It returns `{ items, truncated }`; `truncated` is true exactly when the last fetched page names a next page. It never requests or decodes a page beyond the cap, and uses the same pagination and per-page byte limits as `list`.
+Use `listBounded(path, itemSchema, pageCap, options?)` to collect a prefix within a positive page cap. It returns `{ items, skipped, truncated }`; `truncated` is true exactly when the last fetched page names a next page. It never requests or decodes a page beyond the cap, and uses the same pagination and per-page byte limits as `list`.
 
 ```ts
 import { listBounded } from "@shivaedev/github/GitHub.ts";
@@ -84,6 +86,55 @@ import { listBounded } from "@shivaedev/github/GitHub.ts";
 const issues = listBounded("/repos/acme/widgets/issues", Issue, 2);
 ```
 
+### Enveloped lists and partial decoding
+
+`list`, `listPages` and `listBounded` accept either the existing numeric byte cap or a `ListOptions` object (from `@shivaedev/github/pagedLists.ts`) as their last argument. Set `arrayKey` to read an array inside an envelope, such as `check_runs` or `artifacts`. The options also accept `responseByteLimit` and the service's `beforeRequest` pacing callback. Item Schemas retain their decoding service requirements.
+
+```ts
+const checks = listBounded("/repos/acme/widgets/commits/main/check-runs", CheckRun, 2, {
+	arrayKey: "check_runs",
+	onDecodeError: "skip",
+	responseByteLimit: 2 * 1024 * 1024,
+});
+```
+
+Import `CheckRun` from `@shivaedev/github/checkRuns.ts`. Decoding fails at the first invalid item by default. With `onDecodeError: "skip"`, valid items keep their order and `skipped` counts rejected items across the fetched pages. Invalid JSON, a missing envelope key, a non-array value, HTTP failures and byte-limit failures still fail the read. A page containing only rejected items still follows its next Link. The page cap counts fetched pages, including empty pages, and never counts pages beyond the cap.
+
+`listPages(path, itemSchema, options?)` returns a Stream of `{ items, skipped, hasNext }` pages for consumers that need streaming counts. `list` flattens those pages into items. Both fetch only while consumed.
+
+### Daily repository reads
+
+The `GitHub` service includes Schema-decoded reads for common repository work:
+
+| Method                                                         | Result                                                             |
+| -------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `getIssue(owner, repo, number, byteLimit?)`                    | `Issue`                                                            |
+| `getUser(username, byteLimit?)`                                | `User`                                                             |
+| `getCollaboratorPermission(owner, repo, username, byteLimit?)` | `CollaboratorPermission`                                           |
+| `getCommit(owner, repo, ref, byteLimit?)`                      | `CommitDetail`, including stats and optional files                 |
+| `compareCommits(owner, repo, base, head, byteLimit?)`          | `Comparison`, including commits, optional files and `totalCommits` |
+| `getTree(owner, repo, ref, options?)`                          | `GitTree`, including GitHub's `truncated` flag                     |
+| `listIssues(owner, repo, options?)`                            | Effect containing a Stream of decoded issue pages                  |
+| `listPullRequestFiles(owner, repo, number, options?)`          | Effect containing a Stream of decoded file pages                   |
+| `listCommits(owner, repo, options?)`                           | Effect containing a Stream of decoded commit pages                 |
+
+The Schemas live in `@shivaedev/github/repositorySchemas.ts` and `@shivaedev/github/gitSchemas.ts`. Results use camelCase field names. Commit authors can be null, file patches can be absent for binary files, and renamed files expose `previousFilename`.
+
+```ts
+const review = Effect.gen(function* () {
+	const github = yield* GitHub;
+	const issue = yield* github.getIssue("acme", "widgets", 3);
+	const pages = yield* github.listPullRequestFiles("acme", "widgets", 3, { responseByteLimit: 2 * 1024 * 1024 });
+	const files = yield* pages.pipe(
+		Stream.flatMap((page) => Stream.fromIterable(page.items)),
+		Stream.runCollect,
+	);
+	return { issue, files };
+});
+```
+
+These reads share the client's authentication, conditional representations and body caps. List options accept `query` for GitHub filters such as issue `state` or commit `sha`, along with the decoding and pacing options above. Lists request `per_page=100` unless overridden in `query`. Tree options accept `recursive` and `responseByteLimit`. Refs containing slashes are encoded as path segments. Compare and single-commit reads return one GitHub response; use `totalCommits` and GitHub's endpoint limits when choosing whether the response is sufficient for your application.
+
 ### Acting as a GitHub App
 
 Provide `githubApp` as the `GitHubToken` Layer. With just the App ID and a PEM private key wrapped in `Redacted`, the client signs App JWTs for App-level requests. Add an installation ID for installation requests. Both use the same Schema-aware `read` and paginated `list` functions.
@@ -135,6 +186,24 @@ Provide `app(privateKey)` once around `bothInstallations` or the application. Ea
 
 The shared cache holds at most 100 installation clients and evicts the least recently used client when full. Selecting a client renews its 30-minute idle lifetime; a client idle for that interval is replaced on its next selection. Expiry is lazy, with no background timer. Eviction discards the client's token and request state, and its next request exchanges a new token. Keep operations inside `withInstallation` so each selection uses the cache's current client.
 
+### Repositories visible to an account
+
+Pass the GitHub account from your application's session to `GitHubApp.viewerRepositories(account)`. A number is a GitHub account ID; a string is a login. Provide the same `githubApp(credentials)` Layer as above. The package has no dependency on your session or identity service.
+
+```ts
+import { Effect } from "effect";
+import { GitHubApp } from "@shivaedev/github/installationClients.ts";
+
+const access = Effect.gen(function* () {
+	const app = yield* GitHubApp;
+	return yield* app.viewerRepositories(12345);
+});
+```
+
+The result contains `readable` and `administrable` arrays. Each entry has `id`, `name`, `owner.login`, `htmlUrl`, `private` and `installationId`. Only repositories installed for this App are included, across all installation and repository pages. Public repositories are readable even without a collaborator grant. Private repositories require GitHub's `read`, `triage`, `write`, `maintain` or `admin` permission; only `admin` grants administration. A permission lookup returning 404 means no collaborator grant. Other lookup failures fail the operation instead of returning partial access. The App needs repository Metadata read permission for these lookups.
+
+Successful results are cached for 60 seconds, across at most 100 account keys, evicting the least recently used key when full. Login casing shares a key. Reads do not extend the lifetime. After expiry, the next call revalidates installation lists, repository lists and permissions, so revoked access, changed roles and removed repositories remain cached for at most that interval. Failed lookups are immediately eligible for another attempt. These are cached observations of GitHub access; the application chooses its authorization policy.
+
 `scope` accepts `repositoryIds` or `repositories` (repository names), and a `permissions` record of GitHub permission names to `"read"`, `"write"` or `"admin"`. Omit `scope` for the installation's full access. Explicit `{ permissions: { metadata: "read" } }` requests a metadata-only token for access checks. GitHub decides whether the requested scope is allowed.
 
 Alternatively, pass `{ appId, privateKey, owner: "acme", repository: "widgets", scope? }`. The Layer resolves the installation through `GET /repos/{owner}/{repo}/installation` before exchanging the App JWT for an installation token. Signing uses Node's built-in crypto. The RS256 JWT carries the App ID as `iss`, `iat` 60 seconds before the current time, and `exp` ten minutes ahead.
@@ -147,26 +216,49 @@ Installation lookups and token exchanges follow the same primary and secondary r
 
 Other App authentication failures use `GitHubAppError` from `errors.ts`. Its string `reason` distinguishes `"sign"` (JWT signing), `"encode"` (request body encoding), `"transport"` (sending or reading the response), `"status"` (an HTTP refusal) and `"response"` (invalid or oversized response data). A refused exchange or installation lookup with HTTP 401 has `{ reason: "status", status: 401 }`. Caught failures remain available as a non-enumerable `cause`, excluded from JSON serialization; causes can contain credentials from the underlying HTTP request, so keep them in trusted diagnostics. The serialized errors, logs and spans exclude the private key, App JWT and installation token.
 
-### Downloading workflow-artifact archives
+### Downloading and extracting workflow artifacts
+
+Install the optional ZIP reader to extract artifacts:
+
+```sh
+pnpm add @zip.js/zip.js
+```
 
-Call `downloadArtifactArchive` with the artifact ID and a byte cap. It requests GitHub's ZIP endpoint with the current installation token, reads the 302 Location explicitly, and issues a fresh request to storage without the GitHub Authorization or API-version headers. Fetch requests use manual redirects and omit ambient credentials; provide an HTTP client without automatic redirect middleware.
+Call `downloadArtifactArchive` with the artifact ID and a download byte cap. It requests GitHub's ZIP endpoint with the current installation token, reads the 302 Location explicitly, and issues a fresh request to storage without the GitHub Authorization or API-version headers. Fetch requests use manual redirects and omit ambient credentials; provide an HTTP client without automatic redirect middleware.
 
 ```ts
 import { Effect } from "effect";
 import { GitHub } from "@shivaedev/github/GitHub.ts";
 
-const archive = Effect.gen(function* () {
+const files = Effect.gen(function* () {
 	const github = yield* GitHub;
 	return yield* github.downloadArtifactArchive({
 		owner: "acme",
 		repo: "widgets",
 		artifactId: 7,
 		byteLimit: 10 * 1024 * 1024,
+		totalSizeLimit: 100 * 1024 * 1024,
+		compressionRatioLimit: 100,
 	});
 });
 ```
 
-Provide an installation client such as `clients(privateKey).background` from the GitHub App example above. The result is a `Uint8Array` of archive bytes. The package counts bytes while streaming, independently of transport limits, and stops on overflow with `GitHubArtifactTooLarge({ limit })` from `errors.ts`. This replaces application-owned redirect handling and archive body limits. It does not extract the ZIP.
+Provide an installation client such as `clients(privateKey).background` from the GitHub App example above. The result is an array of `{ path, bytes }` files (`ArtifactFile` from `artifactExtraction.ts`), with relative POSIX paths and `Uint8Array` contents. Directory entries are validated and omitted from the result. Extraction happens in memory and writes no files. The ZIP reader loads on demand; other GitHub operations do not need it.
+
+`byteLimit` caps the downloaded ZIP while streaming and fails with `GitHubArtifactTooLarge({ limit })` from `errors.ts`. Extraction defaults to a `totalSizeLimit` of 100 MiB across all entries and a per-entry `compressionRatioLimit` of 100:1. Both caps are inclusive. The total limit must be a non-negative safe integer; the ratio must be finite and positive. Limits check declared sizes before decompression and emitted bytes before retaining them. No partial file list is returned after a refusal.
+
+Extraction failures come from `artifactErrors.ts`:
+
+| Error                                             | Refusal                                                                                                           |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `GitHubArtifactPathTraversal({ path })`           | Absolute paths, drive paths, backslashes, colons, NUL, empty or dot path components, and parent traversal         |
+| `GitHubArtifactSymlink({ path })`                 | Symbolic links                                                                                                    |
+| `GitHubArtifactDuplicateEntry({ path })`          | Duplicate paths and file/directory conflicts                                                                      |
+| `GitHubArtifactCompressionRatio({ path, limit })` | An entry exceeds the ratio cap                                                                                    |
+| `GitHubArtifactExtractedTooLarge({ limit })`      | Combined extracted contents exceed the total cap                                                                  |
+| `GitHubArtifactExtractionError({ reason })`       | Missing reader (`"reader-unavailable"`), malformed ZIP (`"invalid-archive"`) or invalid caps (`"invalid-limits"`) |
+
+Paths remain case-sensitive.
 
 A missing (404) or expired (410) artifact fails with `GitHubArtifactError({ stage: "redirect", status })`. A storage HTTP failure uses the same error with `stage: "download"`. Transport and GitHub rate-limit failures retain their usual typed errors.
 
@@ -261,6 +353,8 @@ const check = (headSha: string) =>
 
 Use the pure helpers from `markdown.ts` for test names and error messages. `plainText` encodes ASCII punctuation as HTML entities, including HTML delimiters and link syntax, and adds a zero-width separator after `@` and `#` to prevent mentions and issue references. `codeSpan` chooses a backtick fence longer than any run in the input and flattens line endings to spaces. `tableCell` flattens line endings and protects pipes; pass `"code"` for a code span inside a table cell. Emoji are preserved.
 
+`details(summary, text)` wraps raw text in `<details>` and `<summary>`, escaping both inputs with `plainText`. Closing tags, HTML and Markdown in either input remain literal text. Pass raw text rather than rendered Markdown; body line endings and Unicode are preserved.
+
 ```ts
 import { tableCell } from "@shivaedev/github/markdown.ts";
 import { renderRows } from "@shivaedev/github/markdownRows.ts";
@@ -272,9 +366,23 @@ const summary = renderRows(rows, {
 });
 ```
 
-`renderRows` accepts already-rendered rows and a trusted Markdown header. It counts UTF-8 bytes, keeps a prefix of complete rows and, when rows are dropped, appends one `and N more` paragraph. The header and notice count toward the budget; rows, emoji and escapes are never sliced. The default budget is 60,000 bytes. A budget too small for the header and notice throws `RangeError`.
+`renderRows` accepts already-rendered rows and a trusted Markdown header. It counts UTF-8 bytes, keeps a prefix of complete rows and, when rows are dropped, appends one `and N more` paragraph. The header and notice count toward the budget; rows, emoji and escapes are never sliced. The default budget is 60,000 bytes. It returns `Result<string, MarkdownBudgetTooSmall>`; a budget too small for the header and notice is a typed failure. `MarkdownBudgetTooSmall` is exported from `errors.ts` and carries the requested `byteLimit`.
+
+For several lists in one comment, `renderSections` takes sections with `rows` and an optional trusted Markdown `header`, plus one `{ byteLimit }` option for the whole result. It joins sections with blank lines and counts those separators, headers and notices in the shared budget, defaulting to 60,000 bytes. Earlier sections receive spare space first while later sections retain room for their headers and either all their rows or an `and N more` paragraph. Each truncated section has its own omitted-row count. Empty sections without headers are omitted; header-only sections remain. If the total budget cannot fit the required headers and notices or complete shorter lists, it returns a `MarkdownBudgetTooSmall` failure carrying the total requested `byteLimit`.
+
+```ts
+import { renderSections } from "@shivaedev/github/markdownRows.ts";
+
+const report = renderSections(
+	[
+		{ header: "## Failures", rows: failureRows },
+		{ header: "## Warnings", rows: warningRows },
+	],
+	{ byteLimit: 8_000 },
+);
+```
 
-Use the result as a sticky comment body or check-run summary. The budget covers the rendered body; account for any surrounding text, including the sticky comment marker, when choosing a lower total limit.
+Both row helpers return native Effect `Result` values. Match them with `Result.match`, or convert them with `Effect.fromResult` to pass budget failures through the error channel. Use the successful string as a sticky comment body or check-run summary. The budget covers the rendered body; account for any surrounding text, including the sticky comment marker, when choosing a lower total limit.
 
 ### Rate limits and failures