@framers/agentos-ext-github 0.8.0 → 0.9.0

package/dist/documents/GitHubDocumentsConnector.d.ts

@@ -1,9 +1,9 @@
 /**
  * @fileoverview A repository's documentation as account sources, read through a GitHub App's installation: each
- * repository read by its id at its default branch or at a named branch or commit, its tree read once a commit within a
- * request budget, the documentation kept by a filter, each file read as raw bytes under a cap, a push compared by the
- * tree at its `after` commit, and a link's ref settled where a branch name holds a slash. A selection, an item or a
- * call it cannot answer whole is refused before any request.
+ * repository read by its id at its default branch or at a named branch or commit, whole or within a folder, its tree
+ * read once a commit within a request budget, the documentation kept by a filter, each file read as raw bytes under a
+ * cap, a push compared by the tree at its `after` commit, and a link's ref settled as a branch (where its name holds a
+ * slash), a tag or a commit. A selection, an item or a call it cannot answer whole is refused before any request.
  * @module agentos-ext-github/documents/GitHubDocumentsConnector
  */
 import { type AccountSourceConnector, type SourceChanges, type SourceGone, type SourceItem, type SourceRead, type SourceSelection } from '@framers/agentos-ext-account-sources';
@@ -17,13 +17,27 @@ export interface LinkedRepository {
     fullName: string;
     defaultBranch: string;
 }
-/** What `list` reads: the repositories (`ids`), and the branch or commit a listing is made at. */
+/** What `list` reads: the repositories (`ids`), the branch or commit a listing is made at, and a folder or a file. */
 export interface GitHubListSelection extends SourceSelection {
     /**
      * A branch name, or a commit as 40 hexadecimal characters in either case, the listing is made at: the branch's head,
-     * or the commit itself. The default branch's head when absent. Given, the selection names one repository.
+     * or the commit itself. A tag or a short commit is followed by the commit `resolveRef` settles it to. The default
+     * branch's head when absent. Given, the selection names one repository.
      */
     at?: string;
+    /**
+     * A folder of the repository, or a file, by its path with no leading or trailing slash (`resolveRef`'s `path`): the
+     * listing keeps the files at it or under it before `maxFiles` counts them, so a folder's files are listed whatever
+     * sorts before them, and a `/tree/` address that names a file lists that file. The whole repository when absent or
+     * `''`. Given, the selection names one repository.
+     */
+    path?: string;
+}
+/** What `listing` reads within, and its abort signal. */
+export interface GitHubListingOptions {
+    /** A folder or a file, as a selection's `path` names it; the whole repository when absent or `''`. */
+    path?: string;
+    signal?: AbortSignal;
 }
 /**
  * What `changesSince` compares: one repository (`ids` holds its id alone), the branch or commit the comparison follows
@@ -45,12 +59,19 @@ export interface GitHubChangesSelection extends GitHubListSelection {
 }
 /** The ref and the path a link's `<ref>/<path>` text names, as `resolveRef` settles them. */
 export interface ResolvedRef {
-    /** The branch's name, or the commit in lower case. */
+    /**
+     * The branch's name, or a commit of 40 hexadecimal characters in lower case: the commit the link names, whole or by
+     * its first characters, or the commit a tag names. `list`, `head` and `changesSince` take it as `at`.
+     */
     ref: string;
     /** The path under the ref, with no leading or trailing slash; `''` for the ref's root. */
     path: string;
-    /** True when `ref` is a commit, which never moves. */
+    /** True when `ref` is a commit, which never moves: for a commit, and for a tag, read at its commit. */
     commit: boolean;
+    /** What the link's ref names: a branch (`HEAD` the default branch), a tag or a commit. */
+    kind: 'branch' | 'tag' | 'commit';
+    /** The ref as the link writes it: the branch's or the tag's name, `HEAD`, or the commit, whole or short, as written. */
+    name: string;
 }
 /**
  * A repository's documentation as account sources: an item's id is `<repositoryId>:<path>`, its version
@@ -59,12 +80,14 @@ export interface ResolvedRef {
  * `GitHubNoAnswer` (`cancelled`) before it checks anything else. What a call cannot answer whole then throws before any
  * request: a `TypeError` for an id that is not a repository id, a repository named twice, an item id that names no
  * file, a change set of other than one repository, an `at` that is neither a branch name nor a commit or that names
- * other than one repository, and a link's text with an empty, `.` or `..` segment, and an `Error` for a repository
- * outside the link. An installation is removed by the app's own call (`uninstallInstallation`), never by a link's
- * connector.
+ * other than one repository, a `path` with an empty, `.` or `..` segment or beside other than one repository, a link's
+ * text with an empty, `.` or `..` segment, and a link's ref that no ref name can begin with, and an `Error` for a
+ * repository outside the link. An installation is removed by the app's own call (`uninstallInstallation`), never by a
+ * link's connector.
  *
  * A listing and a comparison follow the default branch, or the branch or commit a selection's `at` names: a branch's
- * head is read when the call is made, a commit is read as it is and never changes.
+ * head is read when the call is made, a commit is read as it is and never changes. A selection's `path` narrows them to
+ * a folder, or a file, before `maxFiles` counts the files.
  *
  * Every read addresses a linked repository by its id (`/repositories/<id>/...`, where GitHub's own redirects for a
  * renamed or moved repository lead), never by its name. A name can come to mean another repository (a renamed
@@ -112,13 +135,22 @@ export declare class GitHubDocumentsConnector implements AccountSourceConnector
      * as `after`.
      */
     listing(repositoryId: number, commit: string, signal?: AbortSignal): Promise<TreeBlob[]>;
+    /**
+     * The documentation files of a repository at a commit within a folder, or the one file a path names
+     * (`options.path`), kept before `maxFiles` counts them, under `options.signal`; the whole repository for no path or
+     * `''`. A path with an empty, `.` or `..` segment, or one that is not text, throws a `TypeError` before any request.
+     * A caller keeps it for that commit and hands it to `changesSince` with that commit as `after` and the same `path`.
+     */
+    listing(repositoryId: number, commit: string, options: GitHubListingOptions): Promise<TreeBlob[]>;
     /**
      * The documentation of each selected repository (its id in `ids`) at its default branch's head, or of one repository
-     * at the branch or commit `at` names: the branch's head, or the commit itself with no branch read. Every id and `at`
-     * are checked before any repository is read, so a selection is listed whole or not at all: an id that is not a
-     * repository id, a repository named twice, an `at` that is neither a branch name nor a commit, and an `at` beside
-     * other than one repository throw a `TypeError`, and a repository outside the link an `Error`. A selection's other
-     * fields are `changesSince`'s, and a listing reads none of them.
+     * at the branch or commit `at` names: the branch's head, or the commit itself with no branch read. With a `path`, the
+     * files of one repository at that folder or under it, or the one file it names, kept before `maxFiles` counts them.
+     * Every id, `at` and `path` are checked before any repository is read, so a selection is listed whole or not at all:
+     * an id that is not a repository id, a repository named twice, an `at` that is neither a branch name nor a commit, a
+     * `path` with an empty, `.` or `..` segment or that is not text, and an `at` or a `path` beside other than one
+     * repository throw a `TypeError`, and a repository outside the link an `Error`. A selection's other fields are
+     * `changesSince`'s, and a listing reads none of them.
      */
     list(selection: GitHubListSelection, signal?: AbortSignal): Promise<{
         items: SourceItem[];
@@ -148,21 +180,60 @@ export declare class GitHubDocumentsConnector implements AccountSourceConnector
      * followed branch's head, or at the commit. A push to another branch than the one followed answers no change and the
      * cursor it was given, and so does any push when `at` is a commit, which never changes; without a push, an `after`
      * naming another commit than `at`'s throws a `TypeError` before any request.
+     *
+     * With a `path` the comparison is made within that folder, or of the one file it names: the listing at `after` keeps
+     * the files there before `maxFiles` counts them, so the folder's files are never answered gone for the files sorting
+     * before it, and a `listing` handed in is narrowed to the path (read it with `listing(repositoryId, after, { path })`
+     * so the count is the folder's). A listing handed in that holds `maxFiles` files may have been cut before the folder's
+     * files, so with a path the folder is read afresh instead of it. A cursor is compared under the path it was answered under: a path in it outside the
+     * one given is answered gone.
      */
     changesSince(cursor: string | null, selection: GitHubChangesSelection, signal?: AbortSignal): Promise<SourceChanges>;
     /**
      * The ref and the path of a folder's or a file's `<ref>/<path>` text (`parseGitHubLink`'s `refAndPath`), whose
-     * branch name may hold a slash. A first segment of 40 hexadecimal characters is a commit, in lower case, and `HEAD`
-     * the default branch (git names no branch `HEAD`), each settled with no request. Otherwise one request to GitHub's
-     * matching references (`/repositories/<id>/git/matching-refs/heads/<first segment>`, under an installation token
-     * narrowed to the repository), which answers every branch whose name starts with that segment
-     * (https://docs.github.com/en/rest/git/refs#list-matching-references): the longest branch name that is the text, or
-     * starts it at a slash, is the ref and the rest the path, and the first segment alone when none is longer. A first
-     * segment no branch has is answered as the ref all the same, and a listing at it then answers GitHub's 404. A text
-     * with an empty, `.` or `..` segment throws a `TypeError` that quotes none of it, before any request; GitHub's
-     * refusal of the read, such as 409 for a repository with no commit, throws `GitHubApiError`.
+     * branch or tag name may hold a slash, answered with what the ref is (`kind`) and the name the text writes it by
+     * (`name`). A first segment of 40 hexadecimal characters is a commit, in lower case, and `HEAD` the default branch
+     * (git names no branch `HEAD`), each settled with no request. Otherwise, under an installation token narrowed to the
+     * repository, GitHub's matching references (https://docs.github.com/en/rest/git/refs#list-matching-references), which
+     * answer every reference whose name starts with the first segment, are read in turn until one settles it:
+     *
+     * 1. The branches (`/repositories/<id>/git/matching-refs/heads/<first segment>`) and the tags
+     *    (`.../matching-refs/tags/<first segment>`): the longest name of either that is the text, or starts it at a slash,
+     *    is the ref and the rest the path, a branch and a tag of one name settling as the branch. Git keeps a tag under a
+     *    branch's name beside the branch (`release/2.0` beside `release`), and the longer name is the more of the link it
+     *    names. The tags are not read when a branch's name is the whole text, since no name is longer. A tag is answered
+     *    at the commit it names (`commit: true`), as GitHub serves a `/tree/<tag>/` address: a lightweight tag names it,
+     *    and an annotated tag's object is read for it (https://docs.github.com/en/rest/git/tags#get-a-tag). A tag that
+     *    names no commit is read as no tag, and the branch, if one matched, settles it.
+     * 2. A first segment of 4 to 39 hexadecimal characters, a short commit, through GitHub's commits under its sha media
+     *    type (https://docs.github.com/en/rest/commits/commits#get-a-commit), which answers the whole commit, or 422 for
+     *    a prefix no commit has or several have.
+     *
+     * A first segment neither settles is answered as a branch all the same, and a listing at it then throws GitHub's
+     * 404 as `GitHubApiError`; one that is no branch name by git's rules (such as `-x`, `@` or `end.`) throws a
+     * `TypeError` instead. A text with an empty, `.` or `..` segment, and one whose first segment no ref name can begin
+     * (a control character, a space, `~`, `^`, `:`, `?`, `*`, `[`, `\`, `..` or `@{`, a leading dot or a trailing
+     * `.lock`), throw a `TypeError` that quotes none of it, before any request; GitHub's refusal of a read, such as 409 for
+     * a repository with no commit, throws `GitHubApiError`.
      */
     resolveRef(repositoryId: number, refAndPath: string, signal?: AbortSignal): Promise<ResolvedRef>;
+    /**
+     * The longest branch or tag (`space`) whose name is `text` or starts it at a slash, from GitHub's matching references
+     * for `first`, the text's first segment, with the reference's fields; null for none.
+     */
+    private longestRef;
+    /**
+     * The commit a tag's reference names: a lightweight tag's own object, or the object an annotated tag names, read
+     * through GitHub's tags and followed through a tag of a tag up to {@link MAX_TAG_DEPTH}, in lower case. Null for a
+     * tag that names a tree or a blob, or a longer chain of tags.
+     */
+    private tagCommit;
+    /**
+     * The whole commit a short commit names, in lower case, through GitHub's commits under the sha media type, which
+     * answers the commit's sha alone; null when GitHub answers 422 or 404, as it does for a prefix no commit has or
+     * several have. An answer that is not a commit starting with the prefix throws.
+     */
+    private commitOf;
     /** Nothing to end here: an installation is removed by the app's own call (`uninstallInstallation`). */
     revoke(): Promise<void>;
 }

package/dist/documents/GitHubDocumentsConnector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GitHubDocumentsConnector.d.ts","sourceRoot":"","sources":["../../src/documents/GitHubDocumentsConnector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GitHubDocumentsConnector.d.ts","sourceRoot":"","sources":["../../src/documents/GitHubDocumentsConnector.ts"],"names":[],"mappings":"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"}

package/dist/documents/GitHubDocumentsConnector.js

@@ -1,16 +1,24 @@
 /**
  * @fileoverview A repository's documentation as account sources, read through a GitHub App's installation: each
- * repository read by its id at its default branch or at a named branch or commit, its tree read once a commit within a
- * request budget, the documentation kept by a filter, each file read as raw bytes under a cap, a push compared by the
- * tree at its `after` commit, and a link's ref settled where a branch name holds a slash. A selection, an item or a
- * call it cannot answer whole is refused before any request.
+ * repository read by its id at its default branch or at a named branch or commit, whole or within a folder, its tree
+ * read once a commit within a request budget, the documentation kept by a filter, each file read as raw bytes under a
+ * cap, a push compared by the tree at its `after` commit, and a link's ref settled as a branch (where its name holds a
+ * slash), a tag or a commit. A selection, an item or a call it cannot answer whole is refused before any request.
  * @module agentos-ext-github/documents/GitHubDocumentsConnector
  */
 import { ReadCapExceeded, } from '@framers/agentos-ext-account-sources';
 import { arrayOf, GITHUB_API_BASE, GitHubApiError, githubFetch, GitHubNoAnswer, githubSend, objectOf, repositoryPath, stringIn } from '../app/http.js';
-import { DEFAULT_MAX_FILE_BYTES, extensionOf, pathFilter, readTree, SKIPPED_FOLDERS } from './tree.js';
+import { DEFAULT_MAX_FILE_BYTES, DEFAULT_MAX_FILES, extensionOf, pathFilter, pathOf, readTree, SKIPPED_FOLDERS, withinPath, } from './tree.js';
 /** A commit as a link or a caller names it: 40 hexadecimal characters, in either case. */
 const COMMIT = /^[0-9a-f]{40}$/i;
+/** A commit named by its first characters, as git shortens it: 4 to 39 hexadecimal characters, in either case. */
+const SHORT_COMMIT = /^[0-9a-f]{4,39}$/i;
+/** GitHub's media type for a commit's sha alone (https://docs.github.com/en/rest/commits/commits#get-a-commit). */
+const COMMIT_SHA_MEDIA_TYPE = 'application/vnd.github.sha';
+/** The most bytes read of a commit's sha alone: 40 characters, and room to spare. */
+const COMMIT_SHA_BYTES = 1_024;
+/** The most annotated tags followed from a tag to the commit it names: a tag of a tag is rare. */
+const MAX_TAG_DEPTH = 8;
 /** The characters no branch name holds, beside the control characters and the space (`git check-ref-format`). */
 const NOT_IN_BRANCH = '~^:?*[\\';
 /**
@@ -30,6 +38,22 @@ function isBranchName(name) {
     }
     return name.split('/').every((part) => part !== '' && !part.startsWith('.') && !part.endsWith('.lock'));
 }
+/**
+ * True for a text that may begin a ref's name by git's rules (https://git-scm.com/docs/git-check-ref-format): no
+ * control character, space, `~`, `^`, `:`, `?`, `*`, `[` or `\`, no `..` or `@{`, not starting with a dot and not
+ * ending in `.lock`. A part of a longer name may end with a dot, and a tag's may start with a dash, which a branch's
+ * whole name may not: `isBranchName` reads those.
+ */
+function mayBeginRef(segment) {
+    if (segment.includes('..') || segment.includes('@{') || segment.startsWith('.') || segment.endsWith('.lock'))
+        return false;
+    for (let index = 0; index < segment.length; index += 1) {
+        const code = segment.charCodeAt(index);
+        if (code <= 0x20 || code === 0x7f || NOT_IN_BRANCH.includes(segment[index]))
+            return false;
+    }
+    return true;
+}
 /**
  * The branch or the commit a caller's `at` names, a commit in lower case. Anything else throws a `TypeError` that
  * quotes none of it, before any request.
@@ -97,6 +121,10 @@ function itemPathOf(id) {
     }
     return { repositoryId: repositoryIdOf(id.slice(0, colon)), path };
 }
+/** True for an abort signal, as `listing` tells it from its options: a signal carries `aborted`, an options object does not. */
+function isSignal(value) {
+    return typeof value.aborted === 'boolean';
+}
 /**
  * Throws `GitHubNoAnswer` (`cancelled`) for a call whose signal is already aborted. Each call runs it first, before it
  * checks its inputs or makes any request, so an aborted call answers alike whatever its inputs, as the DOM standard
@@ -113,12 +141,14 @@ function notCancelled(signal) {
  * `GitHubNoAnswer` (`cancelled`) before it checks anything else. What a call cannot answer whole then throws before any
  * request: a `TypeError` for an id that is not a repository id, a repository named twice, an item id that names no
  * file, a change set of other than one repository, an `at` that is neither a branch name nor a commit or that names
- * other than one repository, and a link's text with an empty, `.` or `..` segment, and an `Error` for a repository
- * outside the link. An installation is removed by the app's own call (`uninstallInstallation`), never by a link's
- * connector.
+ * other than one repository, a `path` with an empty, `.` or `..` segment or beside other than one repository, a link's
+ * text with an empty, `.` or `..` segment, and a link's ref that no ref name can begin with, and an `Error` for a
+ * repository outside the link. An installation is removed by the app's own call (`uninstallInstallation`), never by a
+ * link's connector.
  *
  * A listing and a comparison follow the default branch, or the branch or commit a selection's `at` names: a branch's
- * head is read when the call is made, a commit is read as it is and never changes.
+ * head is read when the call is made, a commit is read as it is and never changes. A selection's `path` narrows them to
+ * a folder, or a file, before `maxFiles` counts the files.
  *
  * Every read addresses a linked repository by its id (`/repositories/<id>/...`, where GitHub's own redirects for a
  * renamed or moved repository lead), never by its name. A name can come to mean another repository (a renamed
@@ -182,28 +212,28 @@ export class GitHubDocumentsConnector {
             return followed.commit;
         return this.branchHead(repository, followed?.branch ?? repository.defaultBranch, signal);
     }
-    /**
-     * The documentation files of a repository at a commit: its tree read once within the request budget, never walking
-     * a skipped folder, then filtered. A caller keeps it for that commit and hands it to `changesSince` with that commit
-     * as `after`.
-     */
-    async listing(repositoryId, commit, signal) {
+    async listing(repositoryId, commit, signalOrOptions) {
+        const options = signalOrOptions === undefined || signalOrOptions === null || isSignal(signalOrOptions) ? { signal: signalOrOptions ?? undefined } : signalOrOptions;
+        const { signal } = options;
         notCancelled(signal);
+        const path = pathOf(options.path);
         const repository = this.repository(repositoryId);
         const tree = await readTree(this.fetchImpl, await this.token(repositoryId, signal), repository.id, commit, this.apiBase, {
             maxRequests: this.filter.maxTreeRequests,
             skipFolders: this.filter.skipFolders ?? SKIPPED_FOLDERS,
             signal,
         });
-        return pathFilter(this.filter)(tree);
+        return pathFilter(this.filter)(withinPath(tree, path));
     }
     /**
      * The documentation of each selected repository (its id in `ids`) at its default branch's head, or of one repository
-     * at the branch or commit `at` names: the branch's head, or the commit itself with no branch read. Every id and `at`
-     * are checked before any repository is read, so a selection is listed whole or not at all: an id that is not a
-     * repository id, a repository named twice, an `at` that is neither a branch name nor a commit, and an `at` beside
-     * other than one repository throw a `TypeError`, and a repository outside the link an `Error`. A selection's other
-     * fields are `changesSince`'s, and a listing reads none of them.
+     * at the branch or commit `at` names: the branch's head, or the commit itself with no branch read. With a `path`, the
+     * files of one repository at that folder or under it, or the one file it names, kept before `maxFiles` counts them.
+     * Every id, `at` and `path` are checked before any repository is read, so a selection is listed whole or not at all:
+     * an id that is not a repository id, a repository named twice, an `at` that is neither a branch name nor a commit, a
+     * `path` with an empty, `.` or `..` segment or that is not text, and an `at` or a `path` beside other than one
+     * repository throw a `TypeError`, and a repository outside the link an `Error`. A selection's other fields are
+     * `changesSince`'s, and a listing reads none of them.
      */
     async list(selection, signal) {
         notCancelled(signal);
@@ -213,12 +243,15 @@ export class GitHubDocumentsConnector {
         const followed = selection.at === undefined ? undefined : followedOf(selection.at);
         if (followed !== undefined && ids.length !== 1)
             throw new TypeError('a listing at a named branch or commit is of one repository');
+        const path = pathOf(selection.path);
+        if (path !== '' && ids.length !== 1)
+            throw new TypeError('a listing of a folder or a file is of one repository');
         for (const id of ids)
             this.repository(id);
         const items = [];
         for (const id of ids) {
             const commit = followed === undefined ? await this.head(id, signal) : 'commit' in followed ? followed.commit : await this.head(id, followed.branch, signal);
-            for (const blob of await this.listing(id, commit, signal)) {
+            for (const blob of await this.listing(id, commit, { path, signal })) {
                 items.push({ id: `${id}:${blob.path}`, title: blob.path, size: blob.size, version: `${blob.sha}@${commit}` });
             }
         }
@@ -286,6 +319,13 @@ export class GitHubDocumentsConnector {
      * followed branch's head, or at the commit. A push to another branch than the one followed answers no change and the
      * cursor it was given, and so does any push when `at` is a commit, which never changes; without a push, an `after`
      * naming another commit than `at`'s throws a `TypeError` before any request.
+     *
+     * With a `path` the comparison is made within that folder, or of the one file it names: the listing at `after` keeps
+     * the files there before `maxFiles` counts them, so the folder's files are never answered gone for the files sorting
+     * before it, and a `listing` handed in is narrowed to the path (read it with `listing(repositoryId, after, { path })`
+     * so the count is the folder's). A listing handed in that holds `maxFiles` files may have been cut before the folder's
+     * files, so with a path the folder is read afresh instead of it. A cursor is compared under the path it was answered under: a path in it outside the
+     * one given is answered gone.
      */
     async changesSince(cursor, selection, signal) {
         notCancelled(signal);
@@ -299,6 +339,7 @@ export class GitHubDocumentsConnector {
             throw new TypeError('a listing is compared only with the after commit it was read at');
         }
         const named = selection.at === undefined ? undefined : followedOf(selection.at);
+        const folder = pathOf(selection.path);
         const repository = this.repository(id);
         const followed = named ?? { branch: repository.defaultBranch };
         if (selection.ref !== undefined && ('commit' in followed || selection.ref !== `refs/heads/${followed.branch}`)) {
@@ -308,7 +349,10 @@ export class GitHubDocumentsConnector {
             throw new TypeError('after names another commit than at');
         }
         const after = 'commit' in followed ? followed.commit : (selection.after ?? (await this.branchHead(repository, followed.branch, signal)));
-        const blobs = selection.listing ?? (await this.listing(id, after, signal));
+        // a listing at the file count may have been cut before the folder's files: narrowed, it would answer them gone
+        const handed = selection.listing;
+        const cut = handed !== undefined && folder !== '' && handed.length >= (this.filter.maxFiles ?? DEFAULT_MAX_FILES);
+        const blobs = handed === undefined || cut ? await this.listing(id, after, { path: folder, signal }) : withinPath(handed, folder);
         const now = new Map(blobs.map((blob) => [blob.path, blob.sha]));
         const changed = blobs
             .filter((blob) => before.get(blob.path) !== blob.sha)
@@ -318,15 +362,30 @@ export class GitHubDocumentsConnector {
     }
     /**
      * The ref and the path of a folder's or a file's `<ref>/<path>` text (`parseGitHubLink`'s `refAndPath`), whose
-     * branch name may hold a slash. A first segment of 40 hexadecimal characters is a commit, in lower case, and `HEAD`
-     * the default branch (git names no branch `HEAD`), each settled with no request. Otherwise one request to GitHub's
-     * matching references (`/repositories/<id>/git/matching-refs/heads/<first segment>`, under an installation token
-     * narrowed to the repository), which answers every branch whose name starts with that segment
-     * (https://docs.github.com/en/rest/git/refs#list-matching-references): the longest branch name that is the text, or
-     * starts it at a slash, is the ref and the rest the path, and the first segment alone when none is longer. A first
-     * segment no branch has is answered as the ref all the same, and a listing at it then answers GitHub's 404. A text
-     * with an empty, `.` or `..` segment throws a `TypeError` that quotes none of it, before any request; GitHub's
-     * refusal of the read, such as 409 for a repository with no commit, throws `GitHubApiError`.
+     * branch or tag name may hold a slash, answered with what the ref is (`kind`) and the name the text writes it by
+     * (`name`). A first segment of 40 hexadecimal characters is a commit, in lower case, and `HEAD` the default branch
+     * (git names no branch `HEAD`), each settled with no request. Otherwise, under an installation token narrowed to the
+     * repository, GitHub's matching references (https://docs.github.com/en/rest/git/refs#list-matching-references), which
+     * answer every reference whose name starts with the first segment, are read in turn until one settles it:
+     *
+     * 1. The branches (`/repositories/<id>/git/matching-refs/heads/<first segment>`) and the tags
+     *    (`.../matching-refs/tags/<first segment>`): the longest name of either that is the text, or starts it at a slash,
+     *    is the ref and the rest the path, a branch and a tag of one name settling as the branch. Git keeps a tag under a
+     *    branch's name beside the branch (`release/2.0` beside `release`), and the longer name is the more of the link it
+     *    names. The tags are not read when a branch's name is the whole text, since no name is longer. A tag is answered
+     *    at the commit it names (`commit: true`), as GitHub serves a `/tree/<tag>/` address: a lightweight tag names it,
+     *    and an annotated tag's object is read for it (https://docs.github.com/en/rest/git/tags#get-a-tag). A tag that
+     *    names no commit is read as no tag, and the branch, if one matched, settles it.
+     * 2. A first segment of 4 to 39 hexadecimal characters, a short commit, through GitHub's commits under its sha media
+     *    type (https://docs.github.com/en/rest/commits/commits#get-a-commit), which answers the whole commit, or 422 for
+     *    a prefix no commit has or several have.
+     *
+     * A first segment neither settles is answered as a branch all the same, and a listing at it then throws GitHub's
+     * 404 as `GitHubApiError`; one that is no branch name by git's rules (such as `-x`, `@` or `end.`) throws a
+     * `TypeError` instead. A text with an empty, `.` or `..` segment, and one whose first segment no ref name can begin
+     * (a control character, a space, `~`, `^`, `:`, `?`, `*`, `[`, `\`, `..` or `@{`, a leading dot or a trailing
+     * `.lock`), throw a `TypeError` that quotes none of it, before any request; GitHub's refusal of a read, such as 409 for
+     * a repository with no commit, throws `GitHubApiError`.
      */
     async resolveRef(repositoryId, refAndPath, signal) {
         notCancelled(signal);
@@ -335,23 +394,102 @@ export class GitHubDocumentsConnector {
         }
         const repository = this.repository(repositoryId);
         const first = refAndPath.split('/')[0];
-        const pathAfter = (ref) => refAndPath.slice(ref.length + 1);
+        const settled = (name, ref, kind) => ({
+            ref,
+            path: refAndPath.slice(name.length + 1),
+            commit: kind !== 'branch',
+            kind,
+            name,
+        });
         if (COMMIT.test(first))
-            return { ref: first.toLowerCase(), path: pathAfter(first), commit: true };
+            return settled(first, first.toLowerCase(), 'commit');
         if (first === 'HEAD')
-            return { ref: repository.defaultBranch, path: pathAfter(first), commit: false };
-        const url = `${this.address(repository)}/git/matching-refs/heads/${encodeURIComponent(first)}`;
-        const references = arrayOf(await githubFetch(this.fetchImpl, url, { token: await this.token(repository.id, signal), signal }), 'a list of references');
-        let ref = first;
+            return settled(first, repository.defaultBranch, 'branch');
+        if (!mayBeginRef(first))
+            throw new TypeError('the ref of a link holds what no branch, tag or commit holds');
+        const token = await this.token(repository.id, signal);
+        const branch = await this.longestRef(repository, 'heads', first, refAndPath, token, signal);
+        // a tag names more of the text than the branch when its name is longer; a branch named by the whole text has no longer
+        const tag = branch !== null && branch.name === refAndPath ? null : await this.longestRef(repository, 'tags', first, refAndPath, token, signal);
+        const longer = tag !== null && (branch === null || tag.name.length > branch.name.length) ? tag : null;
+        const tagged = longer === null ? null : await this.tagCommit(repository, longer.fields, token, signal);
+        if (longer !== null && tagged !== null)
+            return settled(longer.name, tagged, 'tag');
+        if (branch !== null)
+            return settled(branch.name, branch.name, 'branch');
+        const commit = SHORT_COMMIT.test(first) ? await this.commitOf(repository, first, token, signal) : null;
+        if (commit !== null)
+            return settled(first, commit, 'commit');
+        if (!isBranchName(first))
+            throw new TypeError('the ref of a link names no branch, tag or commit of the repository');
+        return settled(first, first, 'branch');
+    }
+    /**
+     * The longest branch or tag (`space`) whose name is `text` or starts it at a slash, from GitHub's matching references
+     * for `first`, the text's first segment, with the reference's fields; null for none.
+     */
+    async longestRef(repository, space, first, text, token, signal) {
+        const url = `${this.address(repository)}/git/matching-refs/${space}/${encodeURIComponent(first)}`;
+        const references = arrayOf(await githubFetch(this.fetchImpl, url, { token, signal }), 'a list of references');
+        const prefix = `refs/${space}/`;
+        let found = null;
         for (const reference of references) {
-            const name = stringIn(objectOf(reference, 'a reference'), 'ref', 'a reference');
-            if (!name.startsWith('refs/heads/'))
+            const fields = objectOf(reference, 'a reference');
+            const full = stringIn(fields, 'ref', 'a reference');
+            if (!full.startsWith(prefix))
                 continue;
-            const branch = name.slice('refs/heads/'.length);
-            if (branch.length > ref.length && (refAndPath === branch || refAndPath.startsWith(`${branch}/`)))
-                ref = branch;
+            const name = full.slice(prefix.length);
+            if ((found === null || name.length > found.name.length) && (text === name || text.startsWith(`${name}/`)))
+                found = { name, fields };
+        }
+        return found;
+    }
+    /**
+     * The commit a tag's reference names: a lightweight tag's own object, or the object an annotated tag names, read
+     * through GitHub's tags and followed through a tag of a tag up to {@link MAX_TAG_DEPTH}, in lower case. Null for a
+     * tag that names a tree or a blob, or a longer chain of tags.
+     */
+    async tagCommit(repository, reference, token, signal) {
+        let object = objectOf(reference.object, "a reference's object");
+        for (let depth = 0; stringIn(object, 'type', "a reference's object") === 'tag'; depth += 1) {
+            if (depth === MAX_TAG_DEPTH)
+                return null;
+            const url = `${this.address(repository)}/git/tags/${encodeURIComponent(stringIn(object, 'sha', "a reference's object"))}`;
+            object = objectOf(objectOf(await githubFetch(this.fetchImpl, url, { token, signal }), 'a tag').object, "a tag's object");
+        }
+        const sha = stringIn(object, 'sha', "a reference's object");
+        return stringIn(object, 'type', "a reference's object") === 'commit' && COMMIT.test(sha) ? sha.toLowerCase() : null;
+    }
+    /**
+     * The whole commit a short commit names, in lower case, through GitHub's commits under the sha media type, which
+     * answers the commit's sha alone; null when GitHub answers 422 or 404, as it does for a prefix no commit has or
+     * several have. An answer that is not a commit starting with the prefix throws.
+     */
+    async commitOf(repository, prefix, token, signal) {
+        const short = prefix.toLowerCase();
+        const url = `${this.address(repository)}/commits/${encodeURIComponent(short)}`;
+        let answer;
+        try {
+            answer = await githubSend(this.fetchImpl, url, { token, accept: COMMIT_SHA_MEDIA_TYPE, signal });
+        }
+        catch (error) {
+            if (error instanceof GitHubApiError && (error.status === 404 || error.status === 422))
+                return null;
+            throw error;
+        }
+        let bytes;
+        try {
+            bytes = await answer.bytes(COMMIT_SHA_BYTES);
+        }
+        catch (error) {
+            if (error instanceof ReadCapExceeded)
+                throw new Error('GitHub answered a commit that is not one');
+            throw error;
         }
-        return { ref, path: pathAfter(ref), commit: false };
+        const commit = new TextDecoder().decode(bytes).trim().toLowerCase();
+        if (!COMMIT.test(commit) || !commit.startsWith(short))
+            throw new Error('GitHub answered a commit that is not one');
+        return commit;
     }
     /** Nothing to end here: an installation is removed by the app's own call (`uninstallInstallation`). */
     async revoke() {