sdkproof 0.1.0

package/dist/core/score.js

@@ -0,0 +1,37 @@
+import { classify } from "./classify.js";
+/** Aggregate verdicts into a per-model + overall score with ranked failures. */
+export function score(library, libraryVersion, generatedAt, verdicts, refusals = [], contextArms = [], lost = []) {
+    const models = [...new Set(verdicts.map((v) => v.model))].sort();
+    const perModel = models.map((model) => {
+        const forModel = verdicts.filter((v) => v.model === model);
+        const passed = forModel.filter((v) => v.passed).length;
+        const total = forModel.length;
+        return {
+            model,
+            passed,
+            total,
+            score: total ? Math.round((100 * passed) / total) : 0,
+        };
+    });
+    const passedAll = verdicts.filter((v) => v.passed).length;
+    const overallScore = verdicts.length
+        ? Math.round((100 * passedAll) / verdicts.length)
+        : 0;
+    // Deltas are computed against the bare score on the SAME task subset, in the
+    // CLI, where the per-arm verdicts live. Not recomputed here against the
+    // headline score — those cover different task sets whenever an arm lost one.
+    const arms = contextArms;
+    return {
+        library,
+        libraryVersion,
+        generatedAt,
+        overallScore,
+        perModel,
+        failurePatterns: classify(verdicts),
+        verdicts,
+        refusals,
+        ...(lost.length ? { lost } : {}),
+        ...(arms.length ? { contextArms: arms } : {}),
+    };
+}
+//# sourceMappingURL=score.js.map

package/dist/core/score.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.js","sourceRoot":"","sources":["../../src/core/score.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,gFAAgF;AAChF,MAAM,UAAU,KAAK,CACnB,OAAe,EACf,cAAsB,EACtB,WAAmB,EACnB,QAAmB,EACnB,QAAQ,GAAc,EAAE,EACxB,WAAW,GAAe,EAAE,EAC5B,IAAI,GAAe,EAAE;IAErB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACjE,MAAM,QAAQ,GAAiB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAClD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QAC3D,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;QACvD,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC9B,OAAO;YACL,KAAK;YACL,MAAM;YACN,KAAK;YACL,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;SACtD,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;IAC1D,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM;QAClC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,SAAS,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;QACjD,CAAC,CAAC,CAAC,CAAC;IAEN,6EAA6E;IAC7E,wEAAwE;IACxE,6EAA6E;IAC7E,MAAM,IAAI,GAAG,WAAW,CAAC;IAEzB,OAAO;QACL,OAAO;QACP,cAAc;QACd,WAAW;QACX,YAAY;QACZ,QAAQ;QACR,eAAe,EAAE,QAAQ,CAAC,QAAQ,CAAC;QACnC,QAAQ;QACR,QAAQ;QACR,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC"}

package/dist/core/stats.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The two things every rate on this site was missing (raised on dev.to,
+ * 2026-08-06, and both fair):
+ *
+ * 1. A rate with no interval invites the reader to treat 10/10 as certainty.
+ *    At n=10 it is not — Wilson puts 10/10 at ">=72%" and 0/10 at "up to 28%".
+ *    The refusal table had four 10/10 rows and three 0/10 rows presented as if
+ *    they were the same strength of evidence.
+ * 2. One score over one denominator hides which denominator it used. A Stripe
+ *    run is 100% of what it wrote and 67% of what it was asked — both true, and
+ *    publishing only the first hides the actual failure mode.
+ *
+ * Wilson rather than the normal approximation because every interesting cell
+ * here is at or near an edge (0/10, 10/10), where the textbook interval is
+ * either degenerate or runs outside [0,1].
+ */
+export interface Interval {
+    /** lower bound, 0-1 */
+    low: number;
+    /** upper bound, 0-1 */
+    high: number;
+    /** point estimate, 0-1 */
+    p: number;
+    /** the denominator the interval was computed over */
+    n: number;
+}
+/**
+ * Wilson score interval for a binomial proportion.
+ *
+ * Throws on an empty or impossible denominator rather than returning a
+ * confident-looking zero — the same rule exp-refusals.ts already applies when
+ * more than half its requests error out. A broken input must not render as a
+ * number.
+ */
+export declare function wilson(k: number, n: number, z?: number): Interval;
+/** "33.8–49.3%" — an en dash, so it never reads as a minus sign. */
+export declare function fmtInterval(ci: Interval): string;
+export interface RateSplit {
+    /** passes over usable, non-refused completions — "did it write the current API" */
+    conditional: {
+        passed: number;
+        n: number;
+        pct: number;
+        ci: Interval;
+    };
+    /** passes over every task asked — "did I get a usable answer at all" */
+    unconditional: {
+        passed: number;
+        n: number;
+        pct: number;
+        ci: Interval;
+    };
+    /** true when the two differ, i.e. something was refused and the split matters */
+    split: boolean;
+}
+/**
+ * Both top-line numbers for a run, side by side.
+ *
+ * `scored` is the count that produced code and reached the compiler; `refused`
+ * is the count that produced none. A refusal is not a failure of the library,
+ * which is why it stays out of the conditional denominator — and it is not a
+ * success either, which is why it stays in the unconditional one.
+ */
+export declare function rates(run: {
+    passed: number;
+    scored: number;
+    refused: number;
+}): RateSplit;
+export interface Delta {
+    /** point estimate of arm − baseline, -1 to 1 */
+    diff: number;
+    /** lower bound on the difference */
+    low: number;
+    /** upper bound on the difference */
+    high: number;
+    /** true iff the 95% interval excludes zero, i.e. the sign is supported */
+    significant: boolean;
+}
+/**
+ * 95% interval for the difference between a context arm and its baseline,
+ * by Newcombe's method — the two Wilson intervals combined, rather than a
+ * normal approximation on the difference.
+ *
+ * Why this exists (2026-08-08): every context arm on the site was published as
+ * a bare delta. React Router's skill-only arm is 42/45 against a 41/45
+ * baseline and was rendered as "+2", which is one generation out of
+ * forty-five. Prisma's best arm is +6, which is three. Neither survives a
+ * moment's arithmetic, and a site whose argument is that unmeasured numbers
+ * mislead cannot ship a delta without an interval on it.
+ *
+ * Newcombe rather than the textbook two-proportion interval for the same
+ * reason wilson() is used above: the interesting arms sit at the edges
+ * (0/10 -> 10/10), where the normal approximation runs outside [-1, 1].
+ *
+ * `significant` is deliberately the only boolean here. Everything downstream
+ * must branch on it rather than on the sign of `diff`, so a direction can
+ * never be reported from noise.
+ */
+export declare function armDelta(armPassed: number, armN: number, basePassed: number, baseN: number): Delta;

package/dist/core/stats.js

@@ -0,0 +1,121 @@
+/**
+ * The two things every rate on this site was missing (raised on dev.to,
+ * 2026-08-06, and both fair):
+ *
+ * 1. A rate with no interval invites the reader to treat 10/10 as certainty.
+ *    At n=10 it is not — Wilson puts 10/10 at ">=72%" and 0/10 at "up to 28%".
+ *    The refusal table had four 10/10 rows and three 0/10 rows presented as if
+ *    they were the same strength of evidence.
+ * 2. One score over one denominator hides which denominator it used. A Stripe
+ *    run is 100% of what it wrote and 67% of what it was asked — both true, and
+ *    publishing only the first hides the actual failure mode.
+ *
+ * Wilson rather than the normal approximation because every interesting cell
+ * here is at or near an edge (0/10, 10/10), where the textbook interval is
+ * either degenerate or runs outside [0,1].
+ */
+/** 95% two-sided normal quantile. */
+const Z95 = 1.959963984540054;
+/**
+ * Wilson score interval for a binomial proportion.
+ *
+ * Throws on an empty or impossible denominator rather than returning a
+ * confident-looking zero — the same rule exp-refusals.ts already applies when
+ * more than half its requests error out. A broken input must not render as a
+ * number.
+ */
+export function wilson(k, n, z = Z95) {
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new Error(`wilson: empty denominator (n=${n}) — no rate to report`);
+    }
+    if (!Number.isFinite(k) || k < 0 || k > n) {
+        throw new Error(`wilson: need 0 <= k <= n, got k=${k}, n=${n}`);
+    }
+    const p = k / n;
+    const z2 = z * z;
+    const denom = 1 + z2 / n;
+    const center = (p + z2 / (2 * n)) / denom;
+    const margin = (z / denom) * Math.sqrt((p * (1 - p)) / n + z2 / (4 * n * n));
+    return {
+        // Pinned at the edges rather than clamped: floating point leaves k===n at
+        // 0.9999999999999999, and an interval that excludes its own point estimate
+        // is worse than no interval.
+        low: k === 0 ? 0 : Math.max(0, center - margin),
+        high: k === n ? 1 : Math.min(1, center + margin),
+        p,
+        n,
+    };
+}
+const pct = (x) => {
+    const s = (100 * x).toFixed(1);
+    // 100.0% and 0.0% read as false precision; the bound is exact at the edges.
+    return s.endsWith(".0") ? s.slice(0, -2) : s;
+};
+/** "33.8–49.3%" — an en dash, so it never reads as a minus sign. */
+export function fmtInterval(ci) {
+    return `${pct(ci.low)}–${pct(ci.high)}%`;
+}
+/**
+ * Both top-line numbers for a run, side by side.
+ *
+ * `scored` is the count that produced code and reached the compiler; `refused`
+ * is the count that produced none. A refusal is not a failure of the library,
+ * which is why it stays out of the conditional denominator — and it is not a
+ * success either, which is why it stays in the unconditional one.
+ */
+export function rates(run) {
+    const attempted = run.scored + run.refused;
+    const conditional = wilson(run.passed, run.scored);
+    const unconditional = wilson(run.passed, attempted);
+    return {
+        conditional: {
+            passed: run.passed,
+            n: run.scored,
+            pct: Math.round(100 * conditional.p),
+            ci: conditional,
+        },
+        unconditional: {
+            passed: run.passed,
+            n: attempted,
+            pct: Math.round(100 * unconditional.p),
+            ci: unconditional,
+        },
+        split: run.refused > 0,
+    };
+}
+/**
+ * 95% interval for the difference between a context arm and its baseline,
+ * by Newcombe's method — the two Wilson intervals combined, rather than a
+ * normal approximation on the difference.
+ *
+ * Why this exists (2026-08-08): every context arm on the site was published as
+ * a bare delta. React Router's skill-only arm is 42/45 against a 41/45
+ * baseline and was rendered as "+2", which is one generation out of
+ * forty-five. Prisma's best arm is +6, which is three. Neither survives a
+ * moment's arithmetic, and a site whose argument is that unmeasured numbers
+ * mislead cannot ship a delta without an interval on it.
+ *
+ * Newcombe rather than the textbook two-proportion interval for the same
+ * reason wilson() is used above: the interesting arms sit at the edges
+ * (0/10 -> 10/10), where the normal approximation runs outside [-1, 1].
+ *
+ * `significant` is deliberately the only boolean here. Everything downstream
+ * must branch on it rather than on the sign of `diff`, so a direction can
+ * never be reported from noise.
+ */
+export function armDelta(armPassed, armN, basePassed, baseN) {
+    const a = wilson(armPassed, armN);
+    const b = wilson(basePassed, baseN);
+    const diff = a.p - b.p;
+    // Newcombe method 10: each side takes the far bound of one interval and the
+    // near bound of the other, so the result inherits Wilson's edge behaviour.
+    const low = diff - Math.sqrt((a.p - a.low) ** 2 + (b.high - b.p) ** 2);
+    const high = diff + Math.sqrt((a.high - a.p) ** 2 + (b.p - b.low) ** 2);
+    return {
+        diff,
+        low: Math.max(-1, low),
+        high: Math.min(1, high),
+        significant: low > 0 || high < 0,
+    };
+}
+//# sourceMappingURL=stats.js.map

package/dist/core/stats.js.map

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

package/dist/core/types.d.ts

@@ -0,0 +1,162 @@
+export type Difficulty = "easy" | "medium" | "hard";
+export interface Task {
+    id: string;
+    /** feature area, e.g. "crud" | "relations" | "transactions" | "pagination" */
+    area: string;
+    difficulty: Difficulty;
+    /** natural-language instruction given to the model */
+    prompt: string;
+    /** TS skeleton the solution must complete; forces real library usage */
+    skeleton: string;
+}
+/** model identifier, resolved to a concrete API model id at generation time */
+export type ModelId = string;
+export interface Candidate {
+    taskId: string;
+    model: ModelId;
+    /** full TypeScript source produced by the model */
+    code: string;
+}
+export interface TscError {
+    /** diagnostic code, e.g. "TS2339" */
+    code: string;
+    message: string;
+    line: number;
+    column: number;
+    /** true if the error references the target library's API surface */
+    libraryRelated: boolean;
+}
+export interface Verdict {
+    taskId: string;
+    model: ModelId;
+    /** true iff the candidate type-checks clean against the real installed package */
+    passed: boolean;
+    errors: TscError[];
+}
+export type FailureCategory = "hallucinated-member" | "wrong-arguments" | "bad-import" | "type-mismatch" | "deprecated-or-removed" | "other";
+export interface FailurePattern {
+    category: FailureCategory;
+    count: number;
+    example: {
+        taskId: string;
+        model: ModelId;
+        message: string;
+        snippet?: string;
+    };
+}
+export interface ModelScore {
+    model: ModelId;
+    passed: number;
+    total: number;
+    /** 0-100 */
+    score: number;
+}
+/**
+ * A task the model would not attempt. Refusals are stochastic on ordinary SDK
+ * tasks (measured 2026-08-04 on Stripe), and they are NOT library drift — the
+ * model never wrote code, so nothing was measured. They are excluded from the
+ * score and reported separately so a thin board is visibly thin.
+ */
+export interface Refusal {
+    taskId: string;
+    model: ModelId;
+    /** how many times the identical prompt was re-sampled before giving up */
+    attempts: number;
+}
+/** A context arm's outcome, alongside the bare score it is compared against. */
+export interface ArmScore {
+    name: string;
+    label: string;
+    passed: number;
+    total: number;
+    /** 0-100, over the comparable task subset */
+    score: number;
+    /** the bare score over that SAME subset — never the headline bare score */
+    baselineScore: number;
+    /** score minus baselineScore, the number a maintainer actually wants */
+    delta: number;
+    /** how many tasks every arm and the bare run all produced code for */
+    comparedOn: number;
+    /** trials per task; total = comparedOn x trials */
+    trials: number;
+    /** task ids this arm still fails — the list a maintainer's docs have not closed */
+    failed: string[];
+    /** task ids this arm fixes that the bare run got wrong — what the docs bought */
+    fixed: string[];
+}
+export interface Recommendation {
+    id: string;
+    severity: "high" | "medium" | "info";
+    title: string;
+    detail: string;
+    /** never empty — an item without a measurement behind it is not emitted */
+    evidence: string[];
+}
+export interface LostTask {
+    taskId: string;
+    model: string;
+    /** first line of the underlying error, e.g. a 529 overloaded_error */
+    reason: string;
+}
+export interface Result {
+    library: string;
+    libraryVersion: string;
+    /** ISO timestamp */
+    generatedAt: string;
+    /** 0-100 across all models */
+    overallScore: number;
+    perModel: ModelScore[];
+    failurePatterns: FailurePattern[];
+    verdicts: Verdict[];
+    /** tasks the model refused outright; excluded from every score above */
+    refusals: Refusal[];
+    /**
+     * Tasks that never produced a candidate because generation errored out —
+     * API overload, timeout, transport. NOT refusals: the model never said no,
+     * the request never landed. Recorded because a lost task silently shrinks
+     * the denominator, and a partial run that drops the HARD tasks scores
+     * higher than the real one. Seen 2026-08-05 (an overloaded arm scored high
+     * because overload took its hardest tasks away) and again 2026-08-18, when
+     * four react-table runs each lost half their tasks and the scorecard still
+     * printed "no task was refused, so both rates run over the same set".
+     */
+    lost?: LostTask[];
+    /** present only on a --with-context run: the same tasks scored with the library's own agent files */
+    contextArms?: ArmScore[];
+    /** derived changes a maintainer could make; every one carries its evidence */
+    recommendations?: Recommendation[];
+}
+/**
+ * What verify() needs to know about the thing being scored. The bench passes a
+ * full LibrarySpec (which is structurally assignable); the CLI passes a
+ * throwaway npm workspace it just built for an arbitrary package.
+ */
+export interface VerifyTarget {
+    /** the import name models are expected to use, e.g. "@prisma/client" */
+    packageName: string;
+    /** absolute path to the directory holding tsconfig.json and the candidate file */
+    fixtureDir: string;
+    /**
+     * The file the candidate is written to, default `candidate.ts`.
+     *
+     * A React-facing package needs `candidate.tsx`, because a model asked for a
+     * table or a form writes a component and JSX is a syntax error in a `.ts`
+     * file — 125 diagnostics on the first @tanstack/react-table run, none of them
+     * about the library. It is not the default: in a `.tsx` file `<T>(x) => x`
+     * parses as JSX, so a non-React package would break the other way.
+     */
+    candidateFile?: string;
+}
+/**
+ * What buildUserPrompt() needs about the thing being scored. Kept structural
+ * for the same reason as VerifyTarget: the bench passes a LibrarySpec, the CLI
+ * passes a description it assembled from the npm registry.
+ */
+export interface PromptTarget {
+    /** human name, e.g. "Prisma" */
+    displayName: string;
+    /** the import name models are expected to use, e.g. "@prisma/client" */
+    packageName: string;
+    /** one-line steer for generation — what the library is and what it covers */
+    docsHint: string;
+}

package/dist/core/types.js

@@ -0,0 +1,11 @@
+// Shared types for the SDKProof measurement core.
+// The pipeline flows: Task[] -> Candidate[] -> Verdict[] -> Result
+//
+// This file is the single source of truth for both the published CLI
+// (packages/cli) and the research bench at the repo root — the root's
+// src/types.ts re-exports it. Keeping one copy is not tidiness: the CLI and the
+// bench publish numbers that are compared against each other, and two drifting
+// copies of `API_SHAPE_CODES` or the pass rule would make those numbers
+// incomparable while still looking identical.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,mEAAmE;AACnE,EAAE;AACF,qEAAqE;AACrE,sEAAsE;AACtE,gFAAgF;AAChF,+EAA+E;AAC/E,wEAAwE;AACxE,8CAA8C"}

package/dist/core/verify.d.ts

@@ -0,0 +1,33 @@
+import type { Candidate, TscError, Verdict, VerifyTarget } from "./types.ts";
+export declare const API_SHAPE_CODES: Set<string>;
+export interface VerifyOptions {
+    /** JS entrypoint of the tsc compiler (see env.tscEntry) */
+    tscEntry: string;
+}
+/**
+ * Type-check a model-generated candidate against the real installed package,
+ * inside the library's sandbox fixture. A candidate "passes" iff it compiles
+ * clean under the fixture's strict tsconfig.
+ */
+export declare function verify(candidate: Candidate, spec: VerifyTarget, opts: VerifyOptions): Promise<Verdict>;
+/**
+ * Detect a candidate that augments the module it is supposed to be USING.
+ * Matches the package itself and any subpath entrypoint of it, so
+ * `declare module "@apollo/client/react"` is caught as well as
+ * `declare module "@apollo/client"`.
+ *
+ * Deliberately conservative: it fires on ANY augmentation of the library's own
+ * module, not only ones that redeclare a removed symbol. Telling those apart
+ * needs type introspection, and the cost of being wrong is asymmetric — a
+ * false positive costs one task, a false negative silently inflates a
+ * published score. Measured before shipping: `declare module` appears in 0 of
+ * 35 stored candidate files, so this fires on nothing that has ever been run.
+ */
+export declare function augmentsLibrary(code: string, packageName: string): string | null;
+/**
+ * Reject candidates that cannot possibly be an answer. Returns a reason string
+ * when the candidate is unusable, or null when it is worth compiling.
+ */
+export declare function emptyCandidate(code: string): string | null;
+/** Parse tsc "--pretty false" output into structured errors for the candidate. */
+export declare function parseDiagnostics(output: string, spec: VerifyTarget): TscError[];