@johnhenry/sitefile 0.0.0-stage → 0.0.0

package/lib/src/resources/git.d.ts

@@ -0,0 +1,103 @@
+import { type SourceSpan } from '../errors.js';
+import type { ArchiveLimits, FetchPolicy } from './types.js';
+/**
+ * Git sources over smart HTTP (issue #91): `IMPORT name FROM git+https://host/repo.git#ref:path` and
+ * `sitefile build https://host/repo.git#ref:dir`.
+ *
+ * This is a small client for Git's protocol v2 (gitprotocol-v2, gitprotocol-http), written against
+ * the build's HTTPS client so it inherits its network policy unchanged (https only unless
+ * --allow-http, no credentials in URLs, the SSRF address check at connect time, redirects re-checked
+ * hop by hop, the download cap and the timeout). No `git` binary runs, so there are no hooks, no
+ * config, no credential helpers and no filters:
+ *
+ *   1. GET  <repo>/info/refs?service=git-upload-pack  (Git-Protocol: version=2): capabilities
+ *   2. POST <repo>/git-upload-pack  command=ls-refs    (only when the ref is not a commit)
+ *   3. POST <repo>/git-upload-pack  command=fetch      want <commit>, deepen 1, done
+ *
+ * The packfile is parsed here (zlib objects, OFS_DELTA and REF_DELTA), every object's SHA-1 is
+ * recomputed, and the pack checksum is verified, so the tree that is imported is the one the commit
+ * names. Only SHA-1 repositories are supported. Submodules (gitlinks) are refused; symbolic links are
+ * resolved inside the imported tree with the same rules as local symlinks (see `walkGitTree`).
+ */
+export declare const GIT_COMMIT_RE: RegExp;
+/** A parsed `git+https://…#ref:path` location. */
+export interface GitLocation {
+    /** The URI as written (after interpolation): the lockfile and vendor key. */
+    readonly url: string;
+    /** The repository URL (`https://host/repo.git`), without `git+` and the fragment. */
+    readonly repo: string;
+    /** The ref as written: a branch, a tag, `refs/…`, a 40-hex commit, or '' for the remote HEAD. */
+    readonly ref: string;
+    /** The path inside the repository ('' for its root), `/`-separated, no `.` or `..`. */
+    readonly path: string;
+    /** The commit, when `ref` is a full 40-hex commit id (a pin). */
+    readonly commit?: string;
+}
+/** True for URIs with a `git+` scheme (`git+https:`, `git+http:`, `git+ssh:`, …). */
+export declare function isGitUri(uri: string): boolean;
+/** Git's ref name rules (git check-ref-format), applied to the ref in a Git URL. */
+export declare function checkRefName(ref: string, span?: SourceSpan): void;
+/**
+ * Parse `git+https://host/repo[.git][#ref[:path]]` (`git+http:` too; plain http still needs
+ * --allow-http when fetched). `scheme` errors are E_PROTOCOL, a bad ref E_VALIDATION, a path with
+ * `..` E_PATH_ESCAPE.
+ */
+export declare function parseGitUri(uri: string, span?: SourceSpan): GitLocation;
+/** The URL of a location with the ref replaced by the commit it resolved to (provenance). */
+export declare function pinnedGitUrl(loc: GitLocation, commit: string): string;
+/** What a fetch needs: the build's network policy and extra headers for the repository's origin. */
+export interface GitTransport {
+    readonly policy: FetchPolicy;
+    /** Sent only to the repository's origin (IMPORT … SECRET). */
+    readonly originHeaders?: Readonly<Record<string, string>>;
+    readonly span?: SourceSpan | undefined;
+}
+/**
+ * The commit `ref` names on the server: '' is the remote HEAD; `refs/…` is exact; otherwise
+ * `refs/tags/<ref>` then `refs/heads/<ref>` (Git's own order). Annotated tags are peeled.
+ */
+export declare function resolveRef(repo: string, ref: string, t: GitTransport): Promise<string>;
+/** A fetched commit: its objects, by hex id. */
+export interface GitObjects {
+    readonly commit: string;
+    readonly objects: ReadonlyMap<string, GitObject>;
+    /** The packfile as received (for size accounting). */
+    readonly packBytes: number;
+}
+export interface GitObject {
+    readonly type: 'commit' | 'tree' | 'blob' | 'tag';
+    readonly data: Uint8Array;
+}
+/**
+ * Fetch `commit` (when given) or the commit `ref` names now: one shallow fetch (`deepen 1`) of that
+ * commit alone. The pack is checked as described in the module comment.
+ */
+export declare function fetchGitCommit(repo: string, ref: string, commit: string | undefined, t: GitTransport, limits: ArchiveLimits): Promise<GitObjects>;
+/** The SHA-1 object id of `data` as a loose object of `type`. */
+export declare function gitObjectId(type: GitObject['type'], data: Uint8Array): string;
+/**
+ * Parse a version 2 or 3 packfile into objects by id. Every object is inflated at most to its
+ * declared size, deltas are applied (bases must be in the pack: thin packs are not requested), and
+ * the total inflated size is bounded by `limits.maxTotalBytes`.
+ */
+export declare function parsePack(pack: Uint8Array, repo: string, limits: ArchiveLimits, span?: SourceSpan): Map<string, GitObject>;
+/** Selected content of a commit: a tree's files, or one file. */
+export type GitSelection = {
+    readonly kind: 'tree';
+    readonly files: ReadonlyArray<readonly [string, {
+        readonly bytes: Uint8Array;
+        readonly mode: number;
+    }]>;
+} | {
+    readonly kind: 'file';
+    readonly bytes: Uint8Array;
+    readonly mode: number;
+    readonly basename: string;
+};
+/**
+ * The content of `loc.path` in a fetched commit: a tree's files (symlinks resolved, like a local
+ * directory walk: a link must stay inside the imported tree, directory links back to an ancestor
+ * are skipped) or one file. Entry names are checked like archive entries; the file count and total
+ * size are bounded by `limits`.
+ */
+export declare function selectGitPath(objs: GitObjects, loc: Pick<GitLocation, 'repo' | 'path'>, limits: ArchiveLimits, span?: SourceSpan): GitSelection;