@twarc_net/groundtruth 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -68,6 +68,23 @@ interface Report {
     verdicts: Verdict[];
     summary: ReportSummary;
 }
+/** Verdict levels that can cause a strict failure. */
+type FailLevel = "unsupported" | "unverifiable";
+/** User configuration, from `.groundtruthrc.json` or a `groundtruth` key in package.json. */
+interface Config {
+    /** Default for the hook: block the turn when claims fail. */
+    strict?: boolean;
+    /** Which verdict levels count as a failure in strict mode (default: ["unsupported"]). */
+    failOn?: FailLevel[];
+    /** Shadow mode: record to the ledger but never print or block. For gradual rollout. */
+    shadow?: boolean;
+    /** Claim targets to skip — case-insensitive substring, or a glob with `*`. */
+    ignore?: string[];
+    /** Whole claim kinds to skip (e.g. ["action", "command"]). */
+    ignoreKinds?: ClaimKind[];
+    /** Default output format for `verify`. */
+    output?: "terminal" | "json" | "markdown";
+}
 
 declare function parseTranscriptFile(path: string): Turn;
 declare function parseTranscript(raw: string): Turn;
@@ -84,12 +101,24 @@ declare function parseTranscript(raw: string): Turn;
  */
 declare function extractClaims(summary: string): Claim[];
 
+/**
+ * Loads config for a project, merging (in increasing precedence):
+ *   1. a `groundtruth` key in package.json
+ *   2. a `.groundtruthrc.json` file
+ * Unknown/malformed values are ignored — config never throws.
+ */
+declare function loadConfig(cwd: string): Config;
+/** Drops claims the config asks to ignore (by kind or by target pattern). */
+declare function applyConfig(claims: Claim[], config: Config): Claim[];
+/** How many verdicts count as a failure under the config's `failOn` policy. */
+declare function failingCount(report: Report, config: Config): number;
+
 /**
  * Builds the ground-truth evidence for a turn from two sources:
  *   1. The agent's own tool calls (precise, turn-scoped) — the primary signal.
  *   2. The git working tree (corroborating, catches non-tool edits) — optional.
  */
-declare function buildEvidence(toolUses: ToolUse[], cwd?: string): Evidence;
+declare function buildEvidence(toolUses: ToolUse[], cwd?: string, base?: string): Evidence;
 declare function emptyEvidence(): Evidence;
 declare function mergeEvidence(target: Evidence, extra: Evidence): void;
 
@@ -101,7 +130,7 @@ declare function mergeEvidence(target: Evidence, extra: Evidence): void;
  * If `cwd` is not a git repository (or git is unavailable) this returns empty
  * evidence rather than throwing — the pipeline degrades gracefully.
  */
-declare function collectGitEvidence(cwd: string): Evidence;
+declare function collectGitEvidence(cwd: string, base?: string): Evidence;
 
 /**
  * Checks each claim against the evidence and assigns a verdict.
@@ -127,6 +156,10 @@ interface PipelineInput {
     turn?: Turn;
     /** Working directory used to collect corroborating git evidence. */
     cwd?: string;
+    /** Base ref to diff against (PR mode: `base...HEAD`). Defaults to the working tree. */
+    base?: string;
+    /** Config (ignore rules etc.). If omitted, loaded from `cwd` when present. */
+    config?: Config;
 }
 /**
  * The full groundtruth pipeline:
@@ -134,4 +167,77 @@ interface PipelineInput {
  */
 declare function runPipeline(input: PipelineInput): Report;
 
-export { type Claim, type ClaimKind, type Evidence, type PipelineInput, type Polarity, type Report, type ReportSummary, type ToolUse, type Turn, type Verdict, type VerdictLevel, buildEvidence, buildReport, collectGitEvidence, emptyEvidence, extractClaims, mergeEvidence, parseTranscript, parseTranscriptFile, renderJson, renderMarkdown, renderTerminal, runPipeline, verifyClaims };
+/**
+ * OpenAI Codex CLI rollout transcripts: JSONL where each line is
+ * `{timestamp, type, payload}`. The `response_item` payloads carry assistant
+ * messages, `function_call`/`custom_tool_call` (incl. `apply_patch`), and
+ * `local_shell_call`. See `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`.
+ */
+declare function parseCodex(raw: string): Turn;
+
+/**
+ * Gemini CLI chat transcripts. Current versions write JSONL (one MessageRecord
+ * per line); older versions write a single `{messages: [...]}` JSON object.
+ * `type:"gemini"` messages carry assistant text + a `toolCalls[]` array.
+ * See `~/.gemini/tmp/<project_hash>/chats/`.
+ */
+declare function parseGemini(raw: string): Turn;
+
+/**
+ * Cursor agent transcripts (the newer `agent-transcripts/*.jsonl`, matching the
+ * `cursor-agent` stream-json format): `assistant` / `tool_call` / `result`
+ * lines. Tool inputs (path + content, command) are recorded; we don't need the
+ * cached outputs. See `~/.cursor/projects/<project>/agent-transcripts/`.
+ */
+declare function parseCursor(raw: string): Turn;
+
+interface Adapter {
+    name: string;
+    /** Locate the most recent transcript for a project, or null. Best-effort. */
+    locate(cwd: string): string | null;
+    /** Parse a transcript file into a Turn. */
+    parse(path: string): Turn;
+}
+declare const ADAPTERS: Record<string, Adapter>;
+declare const AGENT_NAMES: string[];
+declare function getAdapter(name: string): Adapter | null;
+/** Picks the adapter whose latest transcript is the most recently modified. */
+declare function autoDetect(cwd: string): {
+    adapter: Adapter;
+    path: string;
+} | null;
+
+/**
+ * A privacy-safe local tally of verdict counts per turn. It stores ONLY counts,
+ * timestamps, and the project path — never code, claims, or prompts. Powers the
+ * `statusline` and `stats` commands.
+ */
+interface LedgerEntry {
+    /** ISO timestamp. */
+    t: string;
+    /** Project working directory. */
+    cwd: string;
+    /** Session id, when known. */
+    session?: string;
+    /** verified / unsupported / review counts. */
+    v: number;
+    u: number;
+    r: number;
+}
+interface LedgerSummary {
+    runs: number;
+    verified: number;
+    unsupported: number;
+    unverifiable: number;
+}
+declare function ledgerPath(): string;
+/** Appends a turn's verdict counts. Best-effort — never throws into the hook. */
+declare function recordRun(report: Report, cwd: string, session?: string): void;
+declare function readLedger(): LedgerEntry[];
+declare function summarize(entries: LedgerEntry[], opts?: {
+    cwd?: string;
+    sinceDays?: number;
+    session?: string;
+}): LedgerSummary;
+
+export { ADAPTERS, AGENT_NAMES, type Adapter, type Claim, type ClaimKind, type Config, type Evidence, type FailLevel, type LedgerEntry, type LedgerSummary, type PipelineInput, type Polarity, type Report, type ReportSummary, type ToolUse, type Turn, type Verdict, type VerdictLevel, applyConfig, autoDetect, buildEvidence, buildReport, collectGitEvidence, emptyEvidence, extractClaims, failingCount, getAdapter, ledgerPath, loadConfig, mergeEvidence, parseCodex, parseCursor, parseGemini, parseTranscript, parseTranscriptFile, readLedger, recordRun, renderJson, renderMarkdown, renderTerminal, runPipeline, summarize, verifyClaims };