@twarc_net/groundtruth 0.1.0 → 0.3.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;
@@ -85,13 +102,16 @@ declare function parseTranscript(raw: string): Turn;
 declare function extractClaims(summary: string): Claim[];
 
 /**
- * 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.
+ * 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 buildEvidence(toolUses: ToolUse[], cwd?: string): Evidence;
-declare function emptyEvidence(): Evidence;
-declare function mergeEvidence(target: Evidence, extra: Evidence): void;
+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;
 
 /**
  * Collects corroborating evidence from git: the working-tree diff against HEAD
@@ -101,7 +121,22 @@ 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;
+interface GitOptions {
+    /** Diff against a base ref (PR/branch mode: `base...HEAD`). */
+    base?: string;
+    /** Use the staged index (`git diff --cached`) — for commit-msg checks. */
+    staged?: boolean;
+}
+declare function collectGitEvidence(cwd: string, opts?: GitOptions): Evidence;
+
+/**
+ * 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, git?: GitOptions): Evidence;
+declare function emptyEvidence(): Evidence;
+declare function mergeEvidence(target: Evidence, extra: Evidence): void;
 
 /**
  * Checks each claim against the evidence and assigns a verdict.
@@ -127,6 +162,12 @@ 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;
+    /** Use the staged index as evidence (commit-msg checks). */
+    staged?: boolean;
+    /** Config (ignore rules etc.). If omitted, loaded from `cwd` when present. */
+    config?: Config;
 }
 /**
  * The full groundtruth pipeline:
@@ -134,4 +175,94 @@ 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;
+
+/**
+ * OpenCode stores a session across many files under `storage/`:
+ *   message/<sessionID>/<messageID>.json  — message info (role, time)
+ *   part/<messageID>/<partID>.json        — text and tool parts
+ * `parseOpenCode` takes the storage root, finds the most recently active
+ * session, and reassembles it. See `~/.local/share/opencode/storage/`.
+ */
+declare function parseOpenCode(input: string): Turn;
+
+/**
+ * Aider chat history (`.aider.chat.history.md`) — best-effort. User turns are
+ * `#### ` lines; assistant turns are raw markdown; tool output is blockquoted.
+ * Edits appear inline as SEARCH/REPLACE blocks (default editblock coder); we
+ * recover the new content + the path from the line preceding the block.
+ */
+declare function parseAider(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, parseAider, parseCodex, parseCursor, parseGemini, parseOpenCode, parseTranscript, parseTranscriptFile, readLedger, recordRun, renderJson, renderMarkdown, renderTerminal, runPipeline, summarize, verifyClaims };