@volter/twin-github 0.1.0

package/src/github-conformance.ts

@@ -0,0 +1,94 @@
+// 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 { specConformance } from '@volter/twin-tooling';
+import { githubState, toGithubComment, toGithubRest, toGithubReview } from './github-twin.ts';
+
+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;
+};
+
+const isTwinExtra = (f: string): boolean => f.startsWith('_');
+const fixturePath = (name: string): string => new URL(`../test-fixtures/${name}`, import.meta.url).pathname;
+
+/** Load the vendored full GitHub pull-request JSON Schema (dereferenced OpenAPI). */
+export async function loadGithubPrSchema(): Promise<JsonSchema> {
+  return JSON.parse(await Bun.file(fixturePath('github-pull-schema.json')).text()) as JsonSchema;
+}
+
+/** Load the vendored GitHub pull-request-review JSON Schema. */
+export async function loadGithubReviewSchema(): Promise<JsonSchema> {
+  return JSON.parse(await Bun.file(fixturePath('github-review-schema.json')).text()) as JsonSchema;
+}
+
+/** Load the vendored GitHub issue-comment JSON Schema. */
+export async function loadGithubCommentSchema(): Promise<JsonSchema> {
+  return JSON.parse(await Bun.file(fixturePath('github-comment-schema.json')).text()) as JsonSchema;
+}
+
+/** Load the declared evidence-twin scope (fields deliberately not modeled, + reasons). */
+export async function loadGithubKnownDeviations(): Promise<KnownDeviation[]> {
+  const doc = JSON.parse(await Bun.file(fixturePath('github-known-deviations.json')).text()) as { deviations: KnownDeviation[] };
+  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: JsonSchema, opts: { root?: string; known?: KnownDeviation[] } = {}): GithubConformanceReport {
+  const state = githubState(opts.root);
+  const violations: GithubViolation[] = [];
+  let fieldsChecked = 0;
+  let knownIgnored = 0;
+  for (const pr of state.prs) {
+    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: state.prs.length, fieldsChecked, violations, knownIgnored };
+}
+
+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 function githubCoverage(schema: JsonSchema): GithubCoverageReport {
+  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: JsonSchema): GithubCoverageReport {
+  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: JsonSchema): GithubCoverageReport {
+  return specConformance.specCoverage(schema, toGithubComment({ id: 1, repository: 'o/r', number: 1, body: 'hi', at: '2026-01-01T00:00:00Z' }), { exemptKey: isTwinExtra });
+}