@sdods/integrations 0.7.1 → 0.8.0

package/dist/evidence.d.ts

@@ -0,0 +1,150 @@
+import type { Octokit } from '@octokit/rest';
+import type { EvidenceFile, IntegrationLogger, PublishedEvidence, SkippedEvidence } from './types.js';
+/**
+ * Issue evidence committed to a branch (#82). Screenshots in an issue render inline in a private
+ * repository only when GitHub serves them to the reader's session; `blob/<branch>/<path>?raw=true`
+ * does, release assets and Actions artifacts do not.
+ *
+ * Everything goes through the git data API, so no clone is needed:
+ * - the branch is an orphan (a root commit with only a README) created on first use;
+ * - one commit per run adds `runs/<runId>/<scenario>/<file>` and updates `runs/index.json` on top of
+ *   the current head, and the ref moves with `force: false`. When another job moved it first, GitHub
+ *   answers 422 (not a fast-forward); the tree and commit are rebuilt on the new head and retried.
+ * - `prune` rewrites the branch as a new orphan commit holding only the runs to keep.
+ *
+ * Traces are never passed here: they carry credentials (#101).
+ */
+export declare const EVIDENCE_INDEX = "runs/index.json";
+export interface EvidenceIndex {
+    runs: Record<string, {
+        uploadedAt: string;
+        project?: string;
+        files: number;
+        bytes: number;
+    }>;
+}
+export interface EvidenceCaps {
+    maxFileBytes: number;
+    maxRunBytes: number;
+}
+export interface GitHubBranchEvidenceOptions {
+    octokit: Octokit;
+    owner: string;
+    repo: string;
+    branch: string;
+    /** web origin for links, e.g. `https://github.com` */
+    serverUrl?: string;
+    logger?: IntegrationLogger;
+    /** bounded attempts for the ref update (default 5) */
+    maxAttempts?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => Date;
+    /** uploads log a reminder to prune when the branch holds runs older than this */
+    retainDays?: number;
+}
+export interface PruneOptions {
+    olderThanMs: number;
+    dryRun?: boolean;
+}
+export interface PruneResult {
+    branch: string;
+    removed: Array<{
+        runId: string;
+        uploadedAt: string;
+    }>;
+    kept: string[];
+    /** run directories missing from `runs/index.json`; kept, since their age is unknown */
+    unknown: string[];
+    commitSha?: string;
+    dryRun: boolean;
+}
+export interface EvidenceCheckResult {
+    ok: boolean;
+    detail: string;
+}
+/**
+ * Apply the size caps. Screenshots go first, then GIF previews, then videos, so a few large
+ * videos never crowd out the images that render inline.
+ */
+export declare function planEvidence(files: EvidenceFile[], caps: EvidenceCaps): {
+    upload: EvidenceFile[];
+    skipped: SkippedEvidence[];
+};
+export declare class GitHubBranchEvidence {
+    readonly owner: string;
+    readonly repo: string;
+    readonly branch: string;
+    private readonly octokit;
+    private readonly serverUrl;
+    private readonly maxAttempts;
+    private readonly sleep;
+    private readonly now;
+    /** replaced per run with the integration context's logger */
+    logger?: IntegrationLogger;
+    private readonly retainDays?;
+    constructor(opts: GitHubBranchEvidenceOptions);
+    get fullName(): string;
+    /** A link that renders inline for anyone who can read the repository. */
+    url(path: string): string;
+    /** Commit a run's files in one commit and return their links. Files over the caps are skipped. */
+    publishRun(run: {
+        id: string;
+        projectSlug?: string;
+    }, files: EvidenceFile[], caps: EvidenceCaps): Promise<PublishedEvidence>;
+    private staleRuns;
+    /**
+     * Build a commit on the current head and move the ref with `force: false`. A 422 means another
+     * job moved the branch in between: re-read the head and rebuild, with backoff, a bounded number
+     * of times.
+     */
+    private commitWithRetry;
+    /** The branch head, creating the orphan branch when it does not exist. */
+    ensureBranch(): Promise<string>;
+    private defaultBranch?;
+    /** The repository's default branch, read once. */
+    private repoDefaultBranch;
+    private defaultBranchMessage;
+    /** Uploads and prune never touch the default branch: prune would erase its history. */
+    private assertNotDefaultBranch;
+    /**
+     * Prune force-rewrites the branch, so it only runs on a branch SDODS created: one whose root
+     * README.md is the one written with the orphan commit.
+     */
+    private assertCreatedBySdods;
+    private isEmptyRepo;
+    private emptyRepoMessage;
+    private headSha;
+    private blob;
+    /** Root entries, `runs/` entries and the parsed index of a tree. */
+    private readLayout;
+    private listTree;
+    /**
+     * Rewrite the branch as a new orphan commit without the runs uploaded before the cutoff.
+     * Kept run directories are reused by tree sha, so nothing is uploaded again. Just before the
+     * force update the head is compared with the one the new tree was built from, and the rewrite is
+     * rebuilt when it moved. That narrows the race with a concurrent upload but cannot close it: a
+     * force update has no compare-and-swap, so a run pushed between that check and the update is
+     * lost. Prune when CI is quiet. GitHub garbage-collects the dropped objects later, and issues
+     * that linked them stop rendering those images.
+     */
+    prune(opts: PruneOptions): Promise<PruneResult>;
+    /**
+     * For `sdods integrations test`: the token can push to the evidence repository, and the branch
+     * exists or will be created on the first upload. Nothing is created here, except that a token
+     * whose repository response has no `permissions` is checked by writing one unreferenced blob.
+     */
+    check(issueRepoPrivate?: boolean): Promise<EvidenceCheckResult>;
+}
+/**
+ * `90min`, `36h`, `14d`, `2w` or a bare number of days → milliseconds. A bare `m` is refused: it
+ * reads as months to some people and minutes to others, and `3m` meant as months prunes nearly
+ * everything.
+ */
+export declare function parseAge(text: string): number;
+/** A path segment safe in a git tree and a URL. */
+export declare function safeSegment(text: string): string;
+/** `runs/<id>/<scenario-slug>/`: readable, and unique through the fingerprint. */
+export declare function scenarioSlug(scenarioName: string, fingerprint: string): string;
+export declare function evidenceKey(fingerprint: string, relPath: string): string;
+export declare function formatBytes(bytes: number): string;
+//# sourceMappingURL=evidence.d.ts.map