@framers/agentos-ext-github 0.7.0 → 0.8.0

package/README.md

@@ -351,7 +351,7 @@ Top-level pull request comments use the issues API. `github_pr_comment_list` ret
 
 The `./documents` entry reads repositories through a GitHub App instead of one personal token. Every call goes to GitHub's REST API over the `fetch` you pass (the global `fetch` by default) with `X-GitHub-Api-Version: 2026-03-10`, so tests point it at a stand-in with `{ fetchImpl, apiBase }`.
 
-A repository is read by its id, at `/repositories/<id>/branches/<branch>`, `/repositories/<id>/git/trees/<sha>` and `/repositories/<id>/contents/<path>`, the address GitHub's own redirects for a renamed or moved repository lead to, and never by its name. A name can come to mean another repository: a renamed repository's old name can be taken again, and an account's old login claimed by another account, which ends GitHub's redirects to it; and GitHub answers a public repository's branch, tree and files to any token, an installation token narrowed to other repositories included. The full name builds a read's attribution link and nothing else.
+A repository is read by its id, at `/repositories/<id>/branches/<branch>`, `/repositories/<id>/git/trees/<sha>`, `/repositories/<id>/contents/<path>` and `/repositories/<id>/git/matching-refs/heads/<name>`, the address GitHub's own redirects for a renamed or moved repository lead to, and never by its name. A name can come to mean another repository: a renamed repository's old name can be taken again, and an account's old login claimed by another account, which ends GitHub's redirects to it; and GitHub answers a public repository's branch, tree and files to any token, an installation token narrowed to other repositories included. The full name builds a read's attribution link and nothing else.
 
 ```ts
 import { readFileSync } from 'node:fs';
@@ -450,9 +450,11 @@ Every call runs under a deadline, 30 seconds by default (`GITHUB_TIMEOUT_MS`), i
 | `verifyWebhookSignature(body, header, secret)` | Checks `X-Hub-Signature-256` against the HMAC SHA-256 of the raw body in constant time; an empty or missing secret throws a `TypeError`, since anyone can sign a delivery under an empty key |
 | `readWebhookRequest(request, secret, { maxBytes })`, `readWebhookDelivery({ headers, body }, secret, { maxBytes })` | Read a delivery under a cap, check its signature and id, and answer it as a typed event, or throw `WebhookDeliveryRefused` with its reason |
 | `reconcileInstallations(credential, links, { since })` | Answers the linked installations GitHub no longer has (`gone`: missing from the listing and answered 404 at their own address, since an installation removed while the listing is read can move another past a page's end), those GitHub has suspended (`suspended`, whose repositories it does not read), the repositories whose default branch moved past the head last read, the repositories it could not read, and asks again for each event since `since` that no delivery attempt delivered, reporting GitHub's refusals of that step in `deliveries`; a rate limit ends it, with `retryAt` |
-| `GitHubDocumentsConnector` | An `AccountSourceConnector` of `@framers/agentos-ext-account-sources` over one installation's linked repositories |
+| `GitHubDocumentsConnector` | An `AccountSourceConnector` of `@framers/agentos-ext-account-sources` over one installation's linked repositories, at each one's default branch or at the branch or commit a selection's `at` names; `resolveRef(repositoryId, refAndPath)` settles where a link's branch name ends |
+| `parseGitHubLink(text)` | The repository, folder or file a GitHub address names, read without a request; `refused` for any other address on GitHub's hosts, `null` for another host's |
 | `readTree`, `pathFilter`, `TreeTooLarge` | A tree at a commit within a request budget, `readTree(fetchImpl, token, repositoryId, commit)` reading the repository by its id (a full name is taken too, and reads whatever repository holds that name; a number that is not a positive integer is a `TypeError` before any request), and the filter that keeps documentation, and code when asked (`includeCode`); `TreeTooLarge` carries `reason`, `budget` or `truncated` |
 | `CODE_EXTENSIONS`, `GENERATED_CODE_ENDINGS`, `isGeneratedCode(path)` | The source files a filter that includes code keeps, and the endings of the code files a tool writes (minified and bundled files, generated Protocol Buffers and Dart files), which it leaves out |
+| `planTree(blobs, options)`, `IMAGE_EXTENSIONS` | Every file of a tree with its outcome under `pathFilter`'s filter: a note, or skipped with the reason it is left out |
 | `GitHubApiError` | An answer outside 2xx; carries the status, `rateLimited` and `retryAt`, and nothing of the body |
 | `GitHubListingChanged` | An installation's repositories changed during each of three reads of their listing (its pages disagreed on `total_count`), so no read is whole; its message names nothing of the installation |
 | `GitHubNoAnswer` | A call that got no answer, by its `reason`: `timeout`, `cancelled` or `network` |
@@ -474,10 +476,38 @@ The connector's filter, `new GitHubDocumentsConnector(credential, installationId
 | `maxFileBytes` | `10485760` (10 MiB): larger files are left out of a listing, and a read past it is answered gone |
 | `maxTreeRequests` | `50` tree requests to list one commit |
 
-An item's id is `<repositoryId>:<path>` and its version `<blob>@<commit>`. A tree is asked for recursively; when GitHub answers it truncated (past 100,000 entries or 7 MB), its top level is read and each subtree is asked for the same way, never walking a skipped folder. `TreeTooLarge` is thrown rather than pass `maxTreeRequests` (`reason: 'budget'`), and at a level GitHub answers truncated when it is asked for alone as well (`reason: 'truncated'`), before any folder under it is asked for: no part of a tree is answered, since the files it left out would read as removed. Files are read through the contents endpoint's raw media type as a stream cut at `maxFileBytes`: PDF, Word and HTML as bytes with their media type, the rest as UTF-8 text, each with a `github` source reference whose `url` is the file at the commit, the commit or branch encoded segment by segment as the path is, so a branch named `docs#1` links as `docs%231`. An item whose version names no commit (none, or no `@<commit>` part) is read at the default branch, and its reference names the branch. `changesSince` takes the cursor it answered last (each documentation path's blob), never reads a push's commit list, so a force push is read like any other, and answers a push to another branch than the default with no change. `listing(repositoryId, commit)` lets a caller keep a commit's listing and pass it to `changesSince` as `listing`, with that commit as `after`; it then reads no tree. A cursor `changesSince` did not answer throws a `TypeError` that quotes none of it, whatever the push's branch. A file read GitHub refuses for a rate limit throws `GitHubApiError` with its `retryAt`, never an answer that the file is gone, and so does a refused installation token (404 for an installation GitHub no longer has): only the contents read's own 404 answers a file `removed`, so a lost installation never reads as every file gone.
+An item's id is `<repositoryId>:<path>` and its version `<blob>@<commit>`. A tree is asked for recursively; when GitHub answers it truncated (past 100,000 entries or 7 MB), its top level is read and each subtree is asked for the same way, never walking a skipped folder. `TreeTooLarge` is thrown rather than pass `maxTreeRequests` (`reason: 'budget'`), and at a level GitHub answers truncated when it is asked for alone as well (`reason: 'truncated'`), before any folder under it is asked for: no part of a tree is answered, since the files it left out would read as removed. Files are read through the contents endpoint's raw media type as a stream cut at `maxFileBytes`: PDF, Word and HTML as bytes with their media type, the rest as UTF-8 text, each with a `github` source reference whose `url` is the file at the commit, the commit or branch encoded segment by segment as the path is, so a branch named `docs#1` links as `docs%231`. An item whose version names no commit (none, or no `@<commit>` part) is read at the default branch, and its reference names the branch. `changesSince` takes the cursor it answered last (each documentation path's blob), never reads a push's commit list, so a force push is read like any other, and answers a push to another branch than the one it follows with no change. `listing(repositoryId, commit)` lets a caller keep a commit's listing and pass it to `changesSince` as `listing`, with that commit as `after`; it then reads no tree. A cursor `changesSince` did not answer throws a `TypeError` that quotes none of it, whatever the push's branch. A file read GitHub refuses for a rate limit throws `GitHubApiError` with its `retryAt`, never an answer that the file is gone, and so does a refused installation token (404 for an installation GitHub no longer has): only the contents read's own 404 answers a file `removed`, so a lost installation never reads as every file gone.
 
 The connector refuses, before any request, what it cannot answer whole, and no refusal quotes a cursor, an item id or a path. A repository id, in a selection or in an item id, is a positive integer in decimal (`77`; never `077`, `0x4d` or ` 77`), else a `TypeError`. `list` checks every id of its selection before it reads any repository, so a selection is listed whole or not at all: a repository named twice is a `TypeError`, and one outside the link an `Error` naming its number. `read` throws a `TypeError` for an item id that names no file: one without a path, or whose path has an empty, `.` or `..` segment. `changesSince` compares one repository a call: a selection of none or several, an empty `after`, or a `listing` without the `after` commit it was read at is a `TypeError`, so call it once per repository, each with that repository's own cursor. A call whose signal is already aborted throws `GitHubNoAnswer` (`cancelled`) before it checks anything else, so every aborted call answers alike, whatever its inputs.
 
+`list`, `changesSince` and `head` follow the default branch, or the branch or commit a selection's `at` names (`head(repositoryId, at, signal)`; `head(repositoryId, signal)` reads the default branch as before). A branch's head is read when the call is made; a commit, 40 hexadecimal characters in either case, is read as it is with no branch read, in lower case, and never changes. `list({ ids: [String(repositoryId)], at: 'release/1.0' })` lists one repository at that branch's head, each item's version `<blob>@<commit>` at it. `changesSince` compares at the followed branch's head when the call names no `after`, answers a push whose `ref` is not `refs/heads/<at>` with no change (the default branch's push included, while `at` names another branch), and answers any push with no change when `at` is a commit; without a push, an `after` naming another commit than `at`'s is a `TypeError`. An `at` that is neither a commit nor a branch name by [git's rules](https://git-scm.com/docs/git-check-ref-format) (no `..`, `@{`, space, control character, `~`, `^`, `:`, `?`, `*`, `[` or `\`; no part empty, starting with a dot or ending in `.lock`; not ending with a dot, not starting with a dash, neither `@` nor `HEAD`), and an `at` beside other than one repository in `list`, throw a `TypeError` before any request.
+
+`parseGitHubLink(text)` reads the GitHub address a person pastes, without a request:
+
+| Address | Answered as |
+| --- | --- |
+| `github.com/<owner>/<repo>`, with or without `.git`; `git@github.com:<owner>/<repo>.git` | `{ kind: 'github_repository', owner, repo }` |
+| `github.com/<owner>/<repo>/tree/<ref>/<path>`, and `/blob/<ref>` with no path, which GitHub shows as the folder | `{ kind: 'github_folder', owner, repo, refAndPath }` |
+| `github.com/<owner>/<repo>/blob/<ref>/<path>` and `/raw/<ref>/<path>`; `raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>` | `{ kind: 'github_file', owner, repo, refAndPath, raw }`, `raw` true for the two raw forms |
+| Any other address on `github.com`, `www.github.com`, `gist.github.com`, `api.github.com`, `codeload.github.com`, `uploads.github.com` or a host under `githubusercontent.com`: an account, an issue, a pull request, a wiki, a release, a commit, a tag (`refs/tags/`), a gist, GitHub's own pages, an address that carries credentials, with a scheme or without one (`<user>:<password>@github.com/...`, which a browser opens as an `https://` address) | `{ kind: 'refused' }` |
+| An address on any other host, an opaque address such as `mailto:someone@github.com`, and text that is no address | `null` |
+
+The scheme, or its absence, a port, the dots that end a host (`github.com.`, `github.com..`), a trailing slash, a query and a fragment are ignored; `www.github.com` is read as `github.com`, and GitHub's form of a branch by its full name, `refs/heads/<branch>`, as the branch. Each segment is decoded, and an address whose path has an empty segment, an escape that does not decode, or a `.` or `..` segment or a control character once decoded is refused. A folder's and a file's ref and path are one text, `refAndPath`, since a branch name may hold a slash. `connector.resolveRef(repositoryId, refAndPath)` settles it as `{ ref, path, commit }`: a first segment of 40 hexadecimal characters is a commit (`commit: true`, in lower case) and `HEAD` the default branch, with no request; otherwise one request to GitHub's [matching references](https://docs.github.com/en/rest/git/refs#list-matching-references), which answers every branch whose name starts with that segment, and the longest branch name that is the text or starts it at a slash is the ref, the rest the path (`''` for the ref's root). Git keeps no branch beside one under its name (`release` beside `release/1.0`), so at most one such branch exists. A first segment no branch has is answered as the ref all the same, and a listing at it throws GitHub's 404 as `GitHubApiError`; so does 409 for a repository with no commit. A `/blob/` address whose text has no slash (`/blob/main`) names its ref alone and is answered as the folder, since GitHub redirects it to `/tree/main`; one whose text has a slash is a file, and when `resolveRef` settles the whole text as the ref (`/blob/release/1.0` in a repository with a `release/1.0` branch), the path is `''`: the address names a ref and no file, which GitHub answers 404.
+
+```ts
+import { parseGitHubLink } from '@framers/agentos-ext-github/documents';
+
+const link = parseGitHubLink('https://github.com/acme-team/handbook/tree/release/1.0/docs');
+if (link?.kind === 'github_folder') {
+  // repositoryId: the linked repository whose full name is `${link.owner}/${link.repo}`.
+  const { ref, path } = await connector.resolveRef(repositoryId, link.refAndPath); // 'release/1.0' and 'docs'
+  const { items } = await connector.list({ ids: [String(repositoryId)], at: ref });
+  const inFolder = items.filter((item) => path === '' || item.title.startsWith(`${path}/`));
+}
+```
+
+`planTree(blobs, options)` answers every file of a tree (`readTree`'s blobs) in path order, each a new object with its `path`, `sha`, `size` and `outcome`: `'note'`, or `{ skipped }` with the first reason the file is left out. `folder` under a skipped folder; `kind` for a file that is neither documentation, code nor an image (data, configuration, a binary, a file with no extension); `image` for `IMAGE_EXTENSIONS`, or the `imageExtensions` given; `code` for code while `includeCode` is off; `generated` for code a tool wrote while `includeCode` is on; `size` past `maxFileBytes`, or past `maxCodeBytes` for a file of a code extension while `includeCode` is on, whatever `extensions` names (`maxFileBytes` when absent, a non-negative integer, else a `TypeError`); `count` past `maxFiles`, the documentation keeping its places first and the code taking the room left. The notes are exactly what `pathFilter` keeps under the same filter, a code file past `maxCodeBytes` aside, so a caller can show what is left out and why from one listing, and turn code on or off without reading the tree again. An extension the filter's `extensions` names is documentation, an image's included.
+
 ## License
 
 Apache-2.0

package/dist/__tests__/links.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview `parseGitHubLink` over the addresses a person pastes: a repository, a folder and a file on github.com and
+ * a file on raw.githubusercontent.com, each with and without `.git`, a trailing slash, a fragment and a query, under
+ * http, with a port and without a scheme; the GitHub addresses the pack does not read, each refused and never answered
+ * as another site's; and the addresses of other hosts, which are not GitHub's.
+ */
+export {};
+//# sourceMappingURL=links.test.d.ts.map

package/dist/__tests__/links.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/links.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/__tests__/links.test.js

@@ -0,0 +1,182 @@
+/**
+ * @fileoverview `parseGitHubLink` over the addresses a person pastes: a repository, a folder and a file on github.com and
+ * a file on raw.githubusercontent.com, each with and without `.git`, a trailing slash, a fragment and a query, under
+ * http, with a port and without a scheme; the GitHub addresses the pack does not read, each refused and never answered
+ * as another site's; and the addresses of other hosts, which are not GitHub's.
+ */
+import { describe, expect, it } from 'vitest';
+import { parseGitHubLink } from '../documents/index.js';
+const COMMIT = '9f2c4e6a'.repeat(5);
+const REPOSITORY = { kind: 'github_repository', owner: 'acme-team', repo: 'handbook' };
+const REFUSED = { kind: 'refused' };
+/** A folder of the handbook at `refAndPath`. */
+function folder(refAndPath) {
+    return { kind: 'github_folder', owner: 'acme-team', repo: 'handbook', refAndPath };
+}
+/** A file of the handbook at `refAndPath`, raw when the address served its bytes alone. */
+function file(refAndPath, raw = false) {
+    return { kind: 'github_file', owner: 'acme-team', repo: 'handbook', refAndPath, raw };
+}
+describe('parseGitHubLink', () => {
+    it('reads a repository whatever its scheme, port, .git, trailing slash, query or fragment', () => {
+        const forms = [
+            'https://github.com/acme-team/handbook',
+            'https://github.com/acme-team/handbook/',
+            'https://github.com/acme-team/handbook.git',
+            'https://github.com/acme-team/handbook.git/',
+            'https://github.com/acme-team/handbook#readme',
+            'https://github.com/acme-team/handbook?tab=readme-ov-file',
+            'http://github.com/acme-team/handbook',
+            'https://github.com:8443/acme-team/handbook',
+            'https://www.github.com/acme-team/handbook',
+            'HTTPS://GitHub.COM/acme-team/handbook',
+            '  https://github.com/acme-team/handbook\n',
+            'github.com/acme-team/handbook',
+            'github.com:8443/acme-team/handbook/',
+            '//github.com/acme-team/handbook',
+            'git://github.com/acme-team/handbook.git',
+            'ssh://git@github.com/acme-team/handbook.git',
+            'git@github.com:acme-team/handbook.git',
+            'https://github.com./acme-team/handbook',
+            // An address's host may end in more than one dot (https://url.spec.whatwg.org/#host-parsing keeps them all).
+            'https://github.com../acme-team/handbook',
+            'github.com...:8443/acme-team/handbook',
+        ];
+        for (const form of forms)
+            expect(parseGitHubLink(form), form).toEqual(REPOSITORY);
+    });
+    it("reads a folder's ref and path as one text, a branch's own slashes included, for the connector to settle", () => {
+        const forms = [
+            ['https://github.com/acme-team/handbook/tree/release/1.0/docs', folder('release/1.0/docs')],
+            ['https://github.com/acme-team/handbook/tree/release/1.0/docs/', folder('release/1.0/docs')],
+            ['https://github.com/acme-team/handbook/tree/release/1.0/docs#top', folder('release/1.0/docs')],
+            ['https://github.com/acme-team/handbook/tree/release/1.0/docs?plain=1', folder('release/1.0/docs')],
+            ['http://github.com:80/acme-team/handbook/tree/main/docs', folder('main/docs')],
+            ['github.com/acme-team/handbook/tree/main/docs', folder('main/docs')],
+            ['https://github.com/acme-team/handbook.git/tree/main/docs', folder('main/docs')],
+            ['https://github.com/acme-team/handbook/tree/main', folder('main')],
+            // GitHub's own form of a branch by its full name, read as the branch.
+            ['https://github.com/acme-team/handbook/tree/refs/heads/release/1.0/docs', folder('release/1.0/docs')],
+            // Each segment decoded: a branch holding a "#", a folder holding a space.
+            ['https://github.com/acme-team/handbook/tree/docs%231/guide%20one', folder('docs#1/guide one')],
+            [`https://github.com/acme-team/handbook/tree/${COMMIT}/docs`, folder(`${COMMIT}/docs`)],
+            // GitHub shows the folder for a blob address that names no path.
+            ['https://github.com/acme-team/handbook/blob/main', folder('main')],
+        ];
+        for (const [form, link] of forms)
+            expect(parseGitHubLink(form), form).toEqual(link);
+    });
+    it("reads a file on github.com and on raw.githubusercontent.com, GitHub's raw addresses marked raw", () => {
+        const forms = [
+            ['https://github.com/acme-team/handbook/blob/main/docs/agenda.md', file('main/docs/agenda.md')],
+            ['https://github.com/acme-team/handbook/blob/main/docs/agenda.md#L3-L4', file('main/docs/agenda.md')],
+            ['https://github.com/acme-team/handbook/blob/main/docs/agenda.md?plain=1', file('main/docs/agenda.md')],
+            ['http://www.github.com/acme-team/handbook/blob/main/docs/agenda.md', file('main/docs/agenda.md')],
+            [`https://github.com/acme-team/handbook/blob/${COMMIT}/docs/agenda.md`, file(`${COMMIT}/docs/agenda.md`)],
+            ['https://github.com/acme-team/handbook/blob/refs/heads/main/docs/agenda.md', file('main/docs/agenda.md')],
+            ['https://github.com/acme-team/handbook/raw/main/docs/agenda.md', file('main/docs/agenda.md', true)],
+            ['https://github.com/acme-team/handbook/raw/refs/heads/main/docs/agenda.md', file('main/docs/agenda.md', true)],
+            ['https://raw.githubusercontent.com/acme-team/handbook/main/docs/agenda.md', file('main/docs/agenda.md', true)],
+            ['https://raw.githubusercontent.com/acme-team/handbook/refs/heads/main/docs/agenda.md', file('main/docs/agenda.md', true)],
+            ['http://raw.githubusercontent.com:8443/acme-team/handbook/main/README.md', file('main/README.md', true)],
+            ['raw.githubusercontent.com/acme-team/handbook/main/README.md', file('main/README.md', true)],
+            // The text may be a branch alone (release/1.0): resolveRef settles it, answering an empty path for a ref alone.
+            ['https://github.com/acme-team/handbook/blob/release/1.0', file('release/1.0')],
+        ];
+        for (const [form, link] of forms)
+            expect(parseGitHubLink(form), form).toEqual(link);
+    });
+    it('refuses a GitHub address that names no repository, folder or file the pack reads', () => {
+        const forms = [
+            'https://github.com/acme-team/handbook/issues/12',
+            'https://github.com/acme-team/handbook/pull/3',
+            'https://github.com/acme-team/handbook/pulls',
+            'https://github.com/acme-team/handbook/wiki',
+            'https://github.com/acme-team/handbook/wiki/Home',
+            'https://github.com/acme-team/handbook/releases',
+            'https://github.com/acme-team/handbook/releases/tag/v1.0',
+            'https://github.com/acme-team/handbook/actions',
+            `https://github.com/acme-team/handbook/commit/${COMMIT}`,
+            'https://github.com/acme-team/handbook/compare/main...release',
+            'https://github.com/acme-team/handbook/discussions/4',
+            'https://github.com/acme-team/handbook/tree',
+            'https://github.com/acme-team/handbook/blob',
+            'https://github.com/acme-team/handbook/raw/main',
+            'https://github.com/acme-team/handbook/tree/refs/tags/v1.0/docs',
+            'https://github.com/acme-team/handbook/tree/refs/pull/3/head',
+            'https://github.com/acme-team/handbook/tree/main//docs',
+            'https://github.com/acme-team/handbook/tree/main/%2E%2E%2Fsecret',
+            'https://github.com/acme-team/handbook/tree/main/a%00b',
+            'https://github.com/acme-team/hand%ZZbook',
+            'https://github.com/acme-team/hand%20book',
+            'https://github.com/acme-team/.git',
+            'https://github.com/-acme/handbook',
+            'https://github.com/acme-team',
+            'https://github.com',
+            'https://github.com/',
+            'https://github.com/settings/profile',
+            'https://github.com/orgs/acme-team',
+            'https://github.com/topics/python',
+            'https://github.com/marketplace/actions',
+            'https://github.com/sponsors/someone',
+            'https://gist.github.com/someone/0123abcd',
+            'https://api.github.com/repos/acme-team/handbook',
+            'https://codeload.github.com/acme-team/handbook/zip/refs/heads/main',
+            'https://gist.githubusercontent.com/someone/0123abcd/raw/notes.md',
+            'https://objects.githubusercontent.com/github-production-release-asset/1',
+            'https://raw.githubusercontent.com/acme-team/handbook',
+            'https://raw.githubusercontent.com/acme-team/handbook/main',
+            'https://ghp_secret@github.com/acme-team/handbook',
+            'https://someone:secret@github.com/acme-team/handbook',
+            'https://git:secret@github.com/acme-team/handbook',
+            'someone@github.com:acme-team/handbook.git',
+            'git@gist.github.com:0123abcd.git',
+            // Credentials before a GitHub host with no scheme, which a browser opens as an https address.
+            'x-access-token:ghs_secret@github.com/acme-team/handbook',
+            'someone:secret@github.com/acme-team/handbook/tree/main/docs',
+            'someone:secret@www.github.com:443/acme-team/handbook',
+            'someone:secret@raw.githubusercontent.com/acme-team/handbook/main/README.md',
+        ];
+        for (const form of forms)
+            expect(parseGitHubLink(form), form).toEqual(REFUSED);
+    });
+    it('answers a GitHub host as a GitHub form or refused, never as another site, whatever the scheme, port, path or trailing dots', () => {
+        const hosts = ['github.com', 'www.github.com', 'gist.github.com', 'api.github.com', 'codeload.github.com', 'raw.githubusercontent.com', 'gist.githubusercontent.com'];
+        for (const host of hosts.flatMap((name) => [name, `${name}.`, `${name}..`])) {
+            for (const scheme of ['https://', 'http://', '']) {
+                for (const port of ['', ':8080']) {
+                    for (const path of ['/', '/x', '/a/b/c/d/e/f', '/a/b/unknown/x', '/a/b?x=1#y']) {
+                        const form = `${scheme}${host}${port}${path}`;
+                        expect(parseGitHubLink(form), form).not.toBeNull();
+                    }
+                }
+            }
+        }
+    });
+    it("answers null for an address that is not GitHub's, and for text that is no address", () => {
+        const forms = [
+            'https://example.com/acme-team/handbook',
+            'https://docs.github.com/en/rest/git/refs',
+            'https://acme-team.github.io/handbook/',
+            'https://github.blog/changelog/',
+            'https://notgithub.com/acme-team/handbook',
+            'https://evilgithub.com/acme-team/handbook',
+            'https://github.com.example.org/acme-team/handbook',
+            'https://githubusercontent.com.example.org/acme-team/handbook',
+            'https://drive.google.com/file/d/1AbC/view',
+            'git@gitlab.com:acme-team/handbook.git',
+            'mailto:someone@github.com',
+            'javascript:alert(1)',
+            'not a link',
+            '',
+            '   ',
+        ];
+        for (const form of forms)
+            expect(parseGitHubLink(form), form).toBeNull();
+    });
+    it('refuses a value that is not text with a TypeError', () => {
+        expect(() => parseGitHubLink(42)).toThrow(TypeError);
+        expect(() => parseGitHubLink(null)).toThrow(TypeError);
+    });
+});
+//# sourceMappingURL=links.test.js.map

package/dist/__tests__/links.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.test.js","sourceRoot":"","sources":["../../src/__tests__/links.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/refs.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview A link's ref settled through GitHub's matching references, a tree planned with what it leaves out and
+ * why, and a repository's documentation listed and compared at a named branch or commit, over a fetch stand-in that
+ * answers a repository's branches, references and trees and records each request.
+ */
+export {};
+//# sourceMappingURL=refs.test.d.ts.map

package/dist/__tests__/refs.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/refs.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}