@volter/twin-github 0.1.2 → 2.0.0

package/dist/src/github-conformance.d.ts

@@ -0,0 +1,43 @@
+import { specConformance } from '@volter/world-tooling';
+type JsonSchema = specConformance.JsonSchema;
+type KnownDeviation = specConformance.KnownDeviation;
+type SpecViolation = specConformance.SpecViolation;
+export type GithubViolation = SpecViolation & {
+    prId: string;
+};
+export type GithubConformanceReport = {
+    ok: boolean;
+    prsChecked: number;
+    fieldsChecked: number;
+    violations: GithubViolation[];
+    knownIgnored: number;
+};
+/** Load the vendored full GitHub pull-request JSON Schema (dereferenced OpenAPI). */
+export declare function loadGithubPrSchema(): Promise<JsonSchema>;
+/** Load the vendored GitHub pull-request-review JSON Schema. */
+export declare function loadGithubReviewSchema(): Promise<JsonSchema>;
+/** Load the vendored GitHub issue-comment JSON Schema. */
+export declare function loadGithubCommentSchema(): Promise<JsonSchema>;
+/** Load the declared evidence-twin scope (fields deliberately not modeled, + reasons). */
+export declare function loadGithubKnownDeviations(): Promise<KnownDeviation[]>;
+/**
+ * Validate every PR the twin serves against the real GitHub PR schema. A wrong
+ * type, an undeclared missing-required field, a fabricated field, or an enum
+ * violation fails the report.
+ */
+export declare function checkGithubConformance(schema: JsonSchema, opts?: {
+    root?: string;
+    known?: KnownDeviation[];
+}): GithubConformanceReport;
+export type GithubCoverageReport = specConformance.SpecCoverageReport;
+/**
+ * Top-level coverage: of the fields the GitHub PR schema declares, which does the
+ * twin emit? The "what we emulate / what we're missing" report — computed from the
+ * spec, not probed live. Uses a representative content-bearing PR sample.
+ */
+export declare function githubCoverage(schema: JsonSchema): GithubCoverageReport;
+/** Coverage of the pull-request-review object the twin emits on review submission. */
+export declare function githubReviewCoverage(schema: JsonSchema): GithubCoverageReport;
+/** Coverage of the issue-comment object the twin emits on comment creation. */
+export declare function githubCommentCoverage(schema: JsonSchema): GithubCoverageReport;
+export {};

package/dist/src/github-conformance.js

@@ -0,0 +1,76 @@
+// GitHub twin conformance (scorecard R2) — spec-conformance against GitHub's
+// PUBLISHED pull-request schema, not a hand-authored field-name list. Offline, no
+// token: for every PR the twin serves, validate the REST response against the real
+// schema (types, required, enums, fabricated extras) vendored from GitHub's OpenAPI
+// (test-fixtures/github-pull-schema.json). Twin-namespaced extras (keys starting
+// `_`) are skipped. Fields the evidence twin deliberately does not model are DECLARED
+// in github-known-deviations.json with reasons — a missing-required field that is
+// NOT declared fails CI. The companion coverage report says what we emit vs what the
+// vendor declares. Standing gate: wrong types, undeclared omissions, fabricated
+// surface, or enum violations all fail.
+import { readFile } from 'node:fs/promises';
+import { specConformance } from '@volter/world-tooling';
+import { githubState, toGithubComment, toGithubRest, toGithubReview } from "./github-twin.js";
+const isTwinExtra = (f) => f.startsWith('_');
+const fixturePath = (name) => new URL(`../test-fixtures/${name}`, import.meta.url).pathname;
+/** Load the vendored full GitHub pull-request JSON Schema (dereferenced OpenAPI). */
+export async function loadGithubPrSchema() {
+    return JSON.parse(await readFile(fixturePath('github-pull-schema.json'), 'utf8'));
+}
+/** Load the vendored GitHub pull-request-review JSON Schema. */
+export async function loadGithubReviewSchema() {
+    return JSON.parse(await readFile(fixturePath('github-review-schema.json'), 'utf8'));
+}
+/** Load the vendored GitHub issue-comment JSON Schema. */
+export async function loadGithubCommentSchema() {
+    return JSON.parse(await readFile(fixturePath('github-comment-schema.json'), 'utf8'));
+}
+/** Load the declared evidence-twin scope (fields deliberately not modeled, + reasons). */
+export async function loadGithubKnownDeviations() {
+    const doc = JSON.parse(await readFile(fixturePath('github-known-deviations.json'), 'utf8'));
+    return doc.deviations;
+}
+/**
+ * Validate every PR the twin serves against the real GitHub PR schema. A wrong
+ * type, an undeclared missing-required field, a fabricated field, or an enum
+ * violation fails the report.
+ */
+export function checkGithubConformance(schema, opts = {}) {
+    const state = githubState(opts.root);
+    const violations = [];
+    let fieldsChecked = 0;
+    let knownIgnored = 0;
+    // "Every PR the twin SERVES" — which is the rows marked as pull-request evidence, not the
+    // counter shells `ensure()` materializes for issue numbers. Checking a shell measures an
+    // object no door answers with, and its emptiness would read as the twin's conformance.
+    const served = state.prs.filter((p) => p.is_pull_request);
+    for (const pr of served) {
+        const rest = toGithubRest(pr);
+        const rep = specConformance.checkSpecConformance(rest, schema, { exemptKey: isTwinExtra, known: opts.known ?? [] });
+        fieldsChecked += rep.fieldsChecked;
+        knownIgnored += rep.knownIgnored;
+        for (const v of rep.violations)
+            violations.push({ ...v, prId: pr.id });
+    }
+    return { ok: violations.length === 0, prsChecked: served.length, fieldsChecked, violations, knownIgnored };
+}
+/**
+ * Top-level coverage: of the fields the GitHub PR schema declares, which does the
+ * twin emit? The "what we emulate / what we're missing" report — computed from the
+ * spec, not probed live. Uses a representative content-bearing PR sample.
+ */
+export function githubCoverage(schema) {
+    const sample = toGithubRest({
+        id: 'o/r#1', number: 1, repository: 'o/r', base_ref: 'main', head_sha: 'abc123',
+        changed_files: 3, commits: 2, review_count: 0, comment_count: 0, title: 'Sample', state: 'open',
+    });
+    return specConformance.specCoverage(schema, sample, { exemptKey: isTwinExtra });
+}
+/** Coverage of the pull-request-review object the twin emits on review submission. */
+export function githubReviewCoverage(schema) {
+    return specConformance.specCoverage(schema, toGithubReview({ id: 1, repository: 'o/r', number: 1, state: 'APPROVED', body: 'lgtm' }), { exemptKey: isTwinExtra });
+}
+/** Coverage of the issue-comment object the twin emits on comment creation. */
+export function githubCommentCoverage(schema) {
+    return specConformance.specCoverage(schema, toGithubComment({ id: 1, repository: 'o/r', number: 1, body: 'hi', at: '2026-01-01T00:00:00Z' }), { exemptKey: isTwinExtra });
+}

package/dist/src/github-connector.d.ts

@@ -0,0 +1,307 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { GithubBudget, type GithubBudgetOptions } from './github-budget.js';
+/**
+ * The minimal real-GitHub REST surface the connector needs. A real `@octokit/rest`
+ * client is structurally adaptable to this (its `request(route, params)` returns
+ * `{ status, data }`) — the consumer wires it; this pack never imports it. `request`
+ * is the single credentialed boundary: in tests it's a fake, live it's the user's
+ * token-bound octokit. It maps a REST `route` ("METHOD /path") + params to a result.
+ */
+export interface GithubExecute {
+    request(route: string, params?: Record<string, unknown>): Promise<{
+        status: number;
+        data: any;
+    }>;
+}
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveGithubOptions = {
+    /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+    budget?: GithubBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: GithubBudgetOptions;
+};
+/**
+ * A live executor against the real GitHub REST API (token = the user's own PAT).
+ * Constructed with the real @octokit/rest in PROD by the CALLER and passed in; this
+ * helper shows the shape without importing the SDK. Kept tiny + dependency-free: it
+ * uses `fetch`, so the pack pulls in no network client. Live runs may instead pass a
+ * real `new Octokit({ auth }).request` bound into a `{ request }` object.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.github.com` request, and therefore the one
+ * place the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE the
+ * request goes out (`checkBudget`, which THROWS `GithubBudgetError` instead of returning when the
+ * ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a `Retry-After` /
+ * 403-or-429 / `x-ratelimit-remaining: 0` signal becomes a persisted cooldown that makes every
+ * later call fail fast WITHOUT touching GitHub. The weights ARE GitHub's own published point costs
+ * (1 for a read, 5 for a write) — see `github-budget.ts`. There is deliberately NO option to
+ * disable the guard, and no value a caller can pass for `budget` that yields an unguarded client —
+ * but NOT immunity from a caller who WANTS one (a fresh `budgetOptions.path` or an injected clock
+ * restores the allowance; the kernel header states that limit and this does not upgrade it).
+ */
+export declare function liveGithubExecute(token: string, baseUrl?: string, opts?: LiveGithubOptions): GithubExecute;
+type ObservedReviewComment = {
+    id: string;
+    /** WHO wrote THIS finding, from the comment's own `user` — the row the vendor sent, not
+     *  the review that wraps it. A review is a join key, not an authorship claim: a scanner
+     *  App's finding rides a review a human submitted, a threaded reply rides the root's
+     *  review, and the phantom bucket has no author at all. The pull BOUGHT this field and
+     *  used to throw it away, so a bot finding was served under the human reviewer's login —
+     *  the exact fact a consumer triaging findings reads. Absent when the vendor named nobody
+     *  (`user: null`, a deleted account); the wrapper's author is then the only evidence
+     *  there is, and the fold falls back to it rather than inventing one. */
+    authorLogin?: string;
+    authorType?: 'bot' | 'user';
+    path?: string;
+    line?: number;
+    body?: string;
+    inReplyTo?: string;
+    createdAt?: string;
+};
+type ObservedReview = {
+    id?: string;
+    /** True for a review NOBODY SHOWED US — one the reviews page never returned. Two shapes
+     *  wear it: the PHANTOM bucket (`unattached`), holding inline comments whose review id was
+     *  missing, and a NAMED orphan, whose id an inline comment gave us but whose row never
+     *  arrived (a review deleted between the two reads, a page boundary). Both carry comments
+     *  and NOTHING ELSE — no state, no author, no verdict — and a consumer must be able to tell
+     *  either from a real review it merely has no state for yet, so both say so. */
+    partial?: boolean;
+    authorLogin?: string;
+    authorType?: 'bot' | 'user';
+    state?: string;
+    body?: string;
+    submittedAt?: string;
+    commitId?: string;
+    comments: ObservedReviewComment[];
+};
+type ObservedComment = {
+    id?: string;
+    authorLogin?: string;
+    authorType?: 'bot' | 'user';
+    body?: string;
+    createdAt?: string;
+    updatedAt?: string;
+};
+type ObservedPr = {
+    id: string;
+    number: number;
+    repository: string;
+    title?: string;
+    body?: string;
+    state?: string;
+    draft?: boolean;
+    merged?: boolean;
+    mergeCommit?: string;
+    baseRef?: string;
+    headSha?: string;
+    changedFiles?: number;
+    commitsCount?: number;
+    authorLogin?: string | null;
+    authorType?: string;
+    /** The PR's own `updated_at` — the provider instant that dates its delta AND the stamp
+     *  the next pull compares against to decide whether its conversation is worth buying. */
+    updatedAt?: string;
+    /** False when the budget skipped this PR's reviews/comments (its `updated_at` had not
+     *  moved). The counts and the conversation subjects are then OMITTED rather than
+     *  reported as zero — an unbought fact is not an observation of absence. */
+    detailsFetched: boolean;
+    /** How many reviews this PR has — counted over exactly the set `latestReview` is drawn
+     *  from (submitted, non-PENDING), so the count and the newest verdict can never disagree. */
+    reviewCount?: number;
+    /** How many issue comments the conversation read bought. Emitted onto the subject beside
+     *  `reviewCount` (it used to be computed here and dropped on the floor). */
+    commentCount?: number;
+    reviews?: ObservedReview[];
+    comments?: ObservedComment[];
+};
+type ObservedIssue = {
+    id: string;
+    number: number;
+    repository: string;
+    title?: string;
+    body?: string;
+    state?: string;
+    created_at?: string;
+    updated_at?: string;
+};
+export declare function pullGithubPrs(execute: GithubExecute, opts: {
+    owner: string;
+    repo: string;
+    state?: 'open' | 'closed' | 'all';
+    perPage?: number;
+    /** How many recently-updated CLOSED PRs an open-only pull also sweeps (default 20). */
+    closedPerPage?: number;
+    /** `owner/repo#n` → the `updated_at` last observed for it. */
+    lastUpdatedAt?: Record<string, string>;
+}): Promise<ObservedPr[]>;
+/**
+ * Pull OBSERVED ISSUES for a repo via the injected executor (GET /repos/:o/:r/issues),
+ * EXCLUDING pull requests — the issues endpoint returns PRs too (each PR is an issue),
+ * distinguished by a `pull_request` field, which we filter out so PRs only flow through
+ * pullGithubPrs. Folds each issue's content (title/body/state). Numbers share the
+ * per-repo PR/issue space (real GitHub).
+ */
+export declare function pullGithubIssues(execute: GithubExecute, opts: {
+    owner: string;
+    repo: string;
+    state?: 'open' | 'closed' | 'all';
+    perPage?: number;
+}): Promise<ObservedIssue[]>;
+export declare function observedPrsToResources(prs: ObservedPr[]): SyncResource[];
+/**
+ * The `updated_at` this world last observed per PR — the budget's memory, read from the
+ * SHADOW (the fold of the world's own event log) rather than a cache beside it, so it
+ * survives a restart, is per-world like every other pulled fact, and cannot disagree with
+ * what was actually folded. A PR nobody has pulled yet is simply absent, and its
+ * conversation gets bought.
+ */
+export declare function lastObservedPrUpdates(root?: string): Record<string, string>;
+export declare function observedIssuesToResources(issues: ObservedIssue[]): SyncResource[];
+/**
+ * A push this connector DECLINES to make, as opposed to one the vendor rejected. It is
+ * raised when enacting the local write faithfully is impossible — the only case today is a
+ * threaded reply whose root has no id on the real repo — and the alternative (posting it
+ * somewhere else, or forwarding a twin-minted id) would write the wrong thing to a real
+ * account. A refusal is ledgered and the sweep continues; the action stays PENDING, so it
+ * pushes on a later sweep once the root is known.
+ */
+export declare class GithubPushRefused extends Error {
+    constructor(message: string);
+}
+/**
+ * PULL + FOLD: pull a repo's OBSERVED PRs AND issues and fold them into the twin (mirror
+ * seeding). Folds CONTENT (PR/issue title/body/state, review state/body, comment body)
+ * plus metadata (counts/refs + review/comment existence) — only the Non-goal (repo file
+ * CONTENTS) is excluded. Also threads the same resources through `syncPull` so the generic
+ * shadow-diff dedup path is exercised (the Linear/Slack-shared contract); the github fold
+ * carries the counts/content the generic delta path drops. PRs and issues share ONE
+ * per-repo number space (real GitHub). Re-pulling identical observations appends nothing.
+ *
+ * Per-row conflict tolerance: if a stored event has DIVERGED from what a resource now
+ * folds to (a `Conflicting duplicate` — e.g. a post-append line mutation raced the live
+ * writer), that ONE row is skipped and its stable id recorded, rather than aborting the
+ * whole repo's fold — one row's integrity question must not become a total observation
+ * outage for the ~dozens of other resources in the same pull (peak-internal PH-216). The
+ * result exposes `conflictsSkipped` + `conflictingIds` so a poller can log the integrity
+ * problem loudly instead of it being swallowed. Every OTHER append error stays fatal.
+ */
+export declare function syncGithubFromReal(execute: GithubExecute, opts: {
+    owner: string;
+    repo: string;
+    root?: string;
+    occurredAt: string;
+    state?: 'open' | 'closed' | 'all';
+    perPage?: number;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+    eventsAppended: number;
+    issues: number;
+    conflictsSkipped: number;
+    conflictingIds: string[];
+}>;
+/**
+ * Push ONE pending GitHub action to the real vendor via the injected executor. Maps
+ * the twin's local write (recorded by applyGithubWrite as an action with an
+ * `operation` + `fields`) to the matching REST call. The injected `execute.request`
+ * is the SOLE credentialed boundary. Returns the real external id when the API gives
+ * one (PR/issue/milestone number, review/comment/status/check id, merge sha). Throws
+ * on a non-2xx so a failure is never silent.
+ *
+ * Covers EVERY write operation applyGithubWrite emits, each faithfully mapped to its
+ * GitHub REST call (method/path/body):
+ *   pull_request.create                       POST   .../pulls
+ *   pull_request.update                       PATCH  .../pulls/:n (+ PATCH .../issues/:n
+ *                                             for label/assignee/milestone fields)
+ *   pull_request.merge                        PUT    .../pulls/:n/merge
+ *   pull_request.request_reviewers            POST   .../pulls/:n/requested_reviewers
+ *   pull_request.remove_requested_reviewers   DELETE .../pulls/:n/requested_reviewers
+ *   pull_request_review.submit                POST   .../pulls/:n/reviews
+ *   pull_request_review_comment.create        POST   .../pulls/:n/comments
+ *   issue.create                              POST   .../issues
+ *   issue.update                              PATCH  .../issues/:n
+ *   issue_comment.create                      POST   .../issues/:n/comments
+ *   commit_status.create                      POST   .../statuses/:sha
+ *   check_run.create                          POST   .../check-runs
+ *   milestone.create                          POST   .../milestones
+ *   milestone.update                          PATCH  .../milestones/:n
+ * Pushing sends the LOCAL content (titles/bodies/diffs the fork authored) — that is
+ * legitimate (only PULL must not fabricate content). Unknown ops FAIL LOUDLY (throw).
+ */
+export declare function pushGithubAction(execute: GithubExecute, action: {
+    operation?: string;
+    subject: {
+        type: string;
+        id: string;
+    };
+    fields?: Record<string, unknown>;
+}, opts?: {
+    /** Twin comment id → the id that row has on the REAL repo (pulled from GitHub, or
+     *  returned by an earlier push in this sweep). A reply resolves its root here. */
+    externalIds?: Record<string, string>;
+}): Promise<{
+    externalId: string;
+}>;
+/**
+ * THE R14 PUSH ADAPTER for github (jira's `pushJiraToRemote` is the reference; this
+ * transcribes its METHOD): pending local actions cross to the remote through the kernel's
+ * ONE RemoteExecute seam under a sealed credential the pack never sees, and each pushed
+ * action is confirmed in the local log. Anchored naming: `createGithubTwinFetch` pairs
+ * with `syncGithubFromRemote` and `pushGithubToRemote`. Push-plane only — a read refuses
+ * loudly. The route grammar is the one `pushGithubAction` speaks (`METHOD /path/{param}`,
+ * templated params in the path, the rest as the JSON body).
+ */
+/** This pack's vendor executor over the kernel's ONE RemoteExecute (push plane). */
+export declare function githubPushExecutor(execute: RemoteExecute): GithubExecute;
+/** THE ANCHORED PUSH SEAM (contract "The push arm is the kernel's transaction; a pack performs one
+ *  action"): perform ONE pending action against GitHub over the kernel executor; the vendor's id comes back. */
+/** The vendor's id in the pack's own subject grammar: a number replaces the trailing number of the
+ *  local id (`acme/web#issue:1` → `acme/web#issue:57`, `acme/web#3` → `acme/web#9`, `comment:2` →
+ *  `comment:184`); anything else (a sha, a ref, a path, an owner/name) leaves the address as it is
+ *  and rides on the receipt as `vendorId`. The kernel rebinds the subject to what comes back
+ *  (contract "A pushed write adopts the vendor's id"). */
+export declare function adoptGithubId(localId: string, vendorId: string | undefined): string;
+export declare function performGithubAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome>;
+/**
+ * THE REPOSITORY AND ITS BRANCHES are observed with the PRs and issues: a working copy's
+ * confirmed writes (a branch it cut, the repo it declared) survive only as what reality
+ * shows back, so the pull says what reality holds — the repo and every branch head.
+ */
+export declare function observeRepositoryAndBranches(execute: GithubExecute, owner: string, repo: string): Promise<SyncResource[]>;
+/**
+ * THE R14 SCHEDULED-PULL ADAPTER (jira is the reference; this transcribes its METHOD):
+ * adapts this pack's executor onto the kernel's ONE RemoteExecute seam, so the twins
+ * service can schedule pulls with a sealed credential the pack never sees. Anchored
+ * naming: `createGithubTwinFetch` pairs with `syncGithubFromRemote`.
+ *
+ * The link's origin names the REPO, not just the API host — a link is a git remote:
+ *   https://api.github.com/repos/{owner}/{repo}
+ * Egress still anchors at the origin's HOST (the service's RemoteExecute discards the
+ * path when routing), so the path here is pure identity. Pull-plane only — every
+ * non-read request refuses loudly.
+ *
+ * Rate note, counted over the routes this pull actually calls: 2 list reads (the repo and
+ * its branches) + 1 PR list + 1 issue list, and then, per PR whose `updated_at` MOVED since
+ * the last pull, three PAGED conversation reads — the reviews, the issue comments and the
+ * inline comments — at 1 request each for a PR under 100 rows and up to 10 each beyond
+ * that. So a poll costs 4 + 3·CHANGED at the floor and 4 + 30·CHANGED at the ceiling; an
+ * unchanged PR costs nothing beyond the list. The link's sync interval still carries the
+ * budget — 60s at the default page floods a PAT's 5000/hr the first time it walks a busy
+ * repo; schedule github links at ≥120s.
+ */
+export declare function syncGithubFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    state?: 'open' | 'closed' | 'all';
+    perPage?: number;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+    eventsAppended: number;
+    issues: number;
+    conflictsSkipped: number;
+    conflictingIds: string[];
+}>;
+export {};