kaniscope 0.31.0 → 0.32.0

package/config.d.ts

@@ -105,6 +105,8 @@ export interface ReviewConfig {
   prBody?: boolean;
   /** Cap on the description handed to the reviewer. A clipped one is marked truncated, so absence is not read as out-of-scope. Default: `12000`. (`PR_BODY_MAX_CHARS`) */
   prBodyMaxChars?: number;
+  /** Cap on the stated change intent handed to the reviewer on a local review. A clipped one is marked truncated, so absence is not read as out-of-scope. Default: `12000`. (`CHANGE_INTENT_MAX_CHARS`) */
+  changeIntentMaxChars?: number;
   /** Snap a finding that drifted just off a diff line onto the nearest diff line sharing its code symbol, instead of folding it into the summary. Default: `true`. (`REANCHOR_FINDINGS`) */
   reanchorFindings?: boolean;
   /** Re-review automatically when a PR gets new commits. Off by default: pushing is the inner loop, and every round costs a full review. Default: `false`. (`REVIEW_ON_UPDATE`) */

package/config.js

@@ -53,6 +53,7 @@ const CONFIG_ENV = {
   prbotRunLog: ["PRBOT_RUN_LOG", "Path"],
   prBody: ["PR_BODY", "Bool"],
   prBodyMaxChars: ["PR_BODY_MAX_CHARS", "Int"],
+  changeIntentMaxChars: ["CHANGE_INTENT_MAX_CHARS", "Int"],
   reanchorFindings: ["REANCHOR_FINDINGS", "Bool"],
   reviewOnUpdate: ["REVIEW_ON_UPDATE", "Bool"],
   reviewSamples: ["REVIEW_SAMPLES", "Int"],

package/index.d.ts

@@ -1,6 +1,17 @@
-import type { RunReviewOutput } from "./types";
+import type {
+  RunReviewOutput,
+  FileReviewOutput,
+  EffectiveRules,
+  FindingsOutput,
+  ResolveOutput,
+  ExplainOutput,
+  ExplainInput,
+} from "./types";
 
-export type { RunReviewOutput, Finding, InlineComment, Usage } from "./types";
+// The WHOLE generated surface. A hand-kept list drifted from the Python
+// client's — 22 names here against 10 there — so the same generated type was
+// public in one language and private in the other. `export *` cannot fall behind.
+export * from "./types";
 
 export type { ReviewConfig } from "./config";
 
@@ -49,6 +60,17 @@ export interface ReviewOptions extends SpawnOptions {
   repoRoot?: string;
   /** With {@link local}: what to call this change. Defaults to the branch name. */
   label?: string;
+  /**
+   * With {@link local}: what this change is MEANT to do — the task, or the
+   * instruction given to a coding agent. The reviewer checks the diff against
+   * it, the way it checks a PR against its description.
+   *
+   * Treated as untrusted data: fenced and labelled before it reaches the model,
+   * and unable to direct the review. Mutually exclusive with {@link intentFile}.
+   */
+  intent?: string;
+  /** With {@link local}: read {@link intent} from this file instead. */
+  intentFile?: string;
   /** Also write the result as JSON to this path, atomically. */
   jsonOut?: string;
   /**
@@ -71,8 +93,91 @@ export interface ReviewOptions extends SpawnOptions {
  */
 export function review(options?: ReviewOptions): Promise<RunReviewOutput>;
 
-/** The JSON Schema of a {@link review} result. Needs no key and no network. */
-export function schema(options?: SpawnOptions): Promise<Record<string, unknown>>;
+/** Selects a checkout, or a pull request. Give one or the other, not both. */
+export interface ScopeOptions extends SpawnOptions {
+  /** The checkout to resolve against. Defaults to the current directory. */
+  repoRoot?: string;
+  /** `github` | `gitlab` | `bitbucket`. With {@link repo} and {@link pr}. */
+  provider?: string;
+  repo?: string;
+  pr?: number;
+}
+
+export interface ReviewFileOptions extends ScopeOptions {
+  /** Repository-relative path of the file to review. Required. */
+  path: string;
+}
+
+/**
+ * The effective review rules: merged settings, which `.prbot.toml` was read,
+ * what it overrode, and the exact instructions injected into the system prompt.
+ *
+ * Makes no model call, so it needs no `OPENROUTER_API_KEY`. Never includes
+ * credentials — the result is built from an explicit allowlist of settings.
+ */
+export function getRules(options?: ScopeOptions): Promise<EffectiveRules>;
+
+/**
+ * Deep-review one complete file, in a checkout or at a PR head.
+ *
+ * Posts nothing. A path excluded by the repository's review filters comes back
+ * as an `excluded` outcome rather than an error, so it can be reported without
+ * being retried.
+ */
+export function reviewFile(options: ReviewFileOptions): Promise<FileReviewOutput>;
+
+/** PR coordinates. All three are required. */
+export interface PrOptions extends SpawnOptions {
+  provider: string;
+  repo: string;
+  pr: number;
+}
+
+/**
+ * The findings currently on a pull request, with lifecycle state.
+ *
+ * Read-only. Check `outcome.status`: a provider that cannot track findings
+ * returns `unsupported` rather than an empty list, because "no open findings" is
+ * a conclusion and must never come from a question that was never asked.
+ */
+export function getFindings(options: PrOptions): Promise<FindingsOutput>;
+
+export interface ResolveOptions extends PrOptions {
+  /** Fingerprints to hand over. Omit for every active finding. */
+  fingerprints?: string[];
+}
+
+/**
+ * Package findings for your own edit loop.
+ *
+ * Changes nothing — no edits, no posts, no thread resolution. The name is the
+ * operation's, and the returned `disclaimer` says so in the payload.
+ */
+export function resolveFindings(options: ResolveOptions): Promise<ResolveOutput>;
+
+export interface ExplainOptions extends SpawnOptions {
+  /** The finding to investigate. */
+  finding: ExplainInput;
+  /** The checkout to read the file from. Defaults to the current directory. */
+  repoRoot?: string;
+  /** The commit the checkout is at, so a revision mismatch can be reported. */
+  headSha?: string;
+}
+
+/** Investigate one finding against a local checkout. Never posts. */
+export function explainFinding(options: ExplainOptions): Promise<ExplainOutput>;
+
+export interface SchemaOptions extends SpawnOptions {
+  /**
+   * Which operation's output schema to fetch — `review-file`, `get-rules`,
+   * `get-findings`, `resolve-findings`, `explain-finding`, `review-local`,
+   * `review-pr`. Omit for the review output's schema.
+   */
+  operation?: string;
+}
+
+/** The JSON Schema of an operation's result. Needs no key and no network. */
+export function schema(options?: SchemaOptions): Promise<Record<string, unknown>>;
 
 /** The engine version this package's binary was built from. */
 export function version(options?: SpawnOptions): Promise<string>;

package/index.js

@@ -24,6 +24,8 @@ const VALUE_FLAGS = {
   base: "--base",
   repoRoot: "--repo-root",
   label: "--label",
+  intent: "--intent",
+  intentFile: "--intent-file",
   jsonOut: "--json-out",
 };
 
@@ -218,11 +220,139 @@ async function review(options = {}) {
 /** The JSON Schema of a {@link review} result. Needs no key and no network. */
 async function schema(options = {}) {
   const bin = options.binary || binaryPath();
-  const result = await run(bin, ["--schema"], options);
-  if (result.code !== 0) throw new Error(`kaniscope --schema failed\n${tail(result.stderr)}`);
+  // `operation` selects a per-operation schema; without it, the review output's,
+  // which is what this function has always returned.
+  const args = options.operation ? ["schema", options.operation] : ["--schema"];
+  const result = await run(bin, args, options);
+  if (result.code !== 0) throw new Error(`kaniscope schema failed\n${tail(result.stderr)}`);
   return JSON.parse(result.stdout);
 }
 
+/**
+ * Run one explicit toolbox operation and parse its single JSON document.
+ *
+ * Shared by the operations below so they cannot diverge in how they report a
+ * crash or a non-JSON stdout — the two failures a caller most needs told apart.
+ */
+async function runOperation(op, args, options) {
+  const bin = options.binary || binaryPath();
+  const result = await run(bin, [op, ...args], options);
+  if (result.code !== 0) {
+    const how = result.signal ? `killed by ${result.signal}` : `exited ${result.code}`;
+    const err = new Error(`kaniscope ${op} ${how}\n${tail(result.stderr)}`);
+    err.exitCode = result.code;
+    err.signal = result.signal;
+    err.stderr = result.stderr;
+    throw err;
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch (cause) {
+    const err = new Error(
+      `kaniscope ${op} exited 0 but stdout was not JSON — is KANISCOPE_BINARY_PATH ` +
+        `pointing at a different program?\n${tail(result.stdout, 5)}`
+    );
+    err.cause = cause;
+    throw err;
+  }
+}
+
+/**
+ * Scope flags shared by the operations that take a checkout OR a pull request.
+ *
+ * A PARTIAL scope is a caller error and is refused here. It used to stringify
+ * whatever was missing into the argv — `--provider undefined --repo o/r` — which
+ * the binary then rejected with a message about a provider named "undefined",
+ * pointing at the wrong thing entirely. Worse, before the CLI required the full
+ * trio it would have been read as a local request and answered for the wrong
+ * scope without any error at all.
+ */
+function scopeArgs(options) {
+  const given = ["provider", "repo", "pr"].filter(
+    (k) => options[k] !== undefined && options[k] !== null
+  );
+  if (given.length === 0) {
+    return options.repoRoot ? ["--repo-root", String(options.repoRoot)] : [];
+  }
+  if (given.length !== 3) {
+    const missing = ["provider", "repo", "pr"].filter((k) => !given.includes(k));
+    throw new TypeError(
+      `kaniscope: a pull-request scope needs provider, repo and pr — missing ${missing.join(", ")}`
+    );
+  }
+  return ["--provider", String(options.provider), "--repo", String(options.repo), "--pr", String(options.pr)];
+}
+
+/**
+ * The effective review rules — merged settings, the repository's `.prbot.toml`,
+ * and the exact injected instructions.
+ *
+ * Makes no model call, so it needs no `OPENROUTER_API_KEY`. Credentials are
+ * never included in the result.
+ */
+async function getRules(options = {}) {
+  return runOperation("get-rules", scopeArgs(options), options);
+}
+
+/** PR coordinates, required by the findings operations. */
+function prArgs(options) {
+  for (const key of ["provider", "repo", "pr"]) {
+    if (options[key] === undefined || options[key] === null) {
+      throw new TypeError(`kaniscope: this operation needs \`${key}\``);
+    }
+  }
+  return ["--provider", String(options.provider), "--repo", String(options.repo), "--pr", String(options.pr)];
+}
+
+/**
+ * The findings currently on a pull request, with their lifecycle state.
+ *
+ * Read-only. Check `outcome.status` — a provider that cannot track findings
+ * returns `unsupported` rather than an empty list, because "no open findings" is
+ * a conclusion and must never come from a question that was never asked.
+ */
+async function getFindings(options = {}) {
+  return runOperation("get-findings", prArgs(options), options);
+}
+
+/**
+ * Package findings for your own edit loop. Changes nothing: Kaniscope does not
+ * edit code, post, or resolve provider threads.
+ *
+ * Omit `fingerprints` to take every active finding.
+ */
+async function resolveFindings(options = {}) {
+  const fps = (options.fingerprints || []).flatMap((fp) => ["--fingerprint", String(fp)]);
+  return runOperation("resolve-findings", [...prArgs(options), ...fps], options);
+}
+
+/**
+ * Investigate one finding against a local checkout. Never posts.
+ *
+ * The finding is passed as JSON on stdin rather than as a flag: a finding body
+ * is multi-line prose with quotes and backticks in it, which is exactly what an
+ * argv mangles.
+ */
+async function explainFinding(options = {}) {
+  if (!options.finding) throw new TypeError("kaniscope: explainFinding needs a `finding`");
+  const args = ["--finding", "@-"];
+  if (options.repoRoot) args.push("--repo-root", String(options.repoRoot));
+  if (options.headSha) args.push("--head-sha", String(options.headSha));
+  // `diff` is how `run` decides to open the child's stdin and what to write
+  // there; the name is historical and the content here is the finding, not a
+  // diff. The caller never sets it — `@-` above is what reads it.
+  return runOperation("explain-finding", args, {
+    ...options,
+    diff: JSON.stringify(options.finding),
+  });
+}
+
+/** Deep-review one complete file, locally or at a PR head. Never posts. */
+async function reviewFile(options = {}) {
+  if (!options.path) throw new TypeError("kaniscope: reviewFile needs a `path`");
+  return runOperation("review-file", ["--path", String(options.path), ...scopeArgs(options)], options);
+}
+
 /** The engine version this package's binary was built from. */
 async function version(options = {}) {
   const bin = options.binary || binaryPath();
@@ -231,4 +361,14 @@ async function version(options = {}) {
   return result.stdout.trim().replace(/^kaniscope\s+/, "");
 }
 
-module.exports = { review, schema, version, binaryPath };
+module.exports = {
+  review,
+  reviewFile,
+  getRules,
+  getFindings,
+  resolveFindings,
+  explainFinding,
+  schema,
+  version,
+  binaryPath,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaniscope",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "AI pull-request reviewer — line-anchored inline comments plus a summary, for GitHub, GitLab and Bitbucket. Ships a native binary; no Rust toolchain required.",
   "keywords": [
     "code-review",
@@ -34,10 +34,10 @@
     "README.md"
   ],
   "optionalDependencies": {
-    "@nhatvu148/kaniscope-darwin-arm64": "0.31.0",
-    "@nhatvu148/kaniscope-darwin-x64": "0.31.0",
-    "@nhatvu148/kaniscope-linux-arm64": "0.31.0",
-    "@nhatvu148/kaniscope-linux-x64": "0.31.0",
-    "@nhatvu148/kaniscope-win32-x64": "0.31.0"
+    "@nhatvu148/kaniscope-darwin-arm64": "0.32.0",
+    "@nhatvu148/kaniscope-darwin-x64": "0.32.0",
+    "@nhatvu148/kaniscope-linux-arm64": "0.32.0",
+    "@nhatvu148/kaniscope-linux-x64": "0.32.0",
+    "@nhatvu148/kaniscope-win32-x64": "0.32.0"
   }
 }

package/types.d.ts

@@ -46,3 +46,312 @@ export interface Usage {
   total_tokens?: number | null;
 }
 
+/** One file review. */
+export interface FileReviewOutput {
+  outcome: FileReviewOutcome;
+  path: string;
+  source: FileSource;
+  /** The result as a comment body — what the PR command posts, and what a CLI caller prints. */
+  summaryMarkdown: string;
+}
+
+/** The file was read and reviewed. */
+export interface FileReviewOutcomeReviewed {
+  /** After the confidence floor, severity sort and cap — the same policy a diff review applies, so a finding here means what it means there. */
+  findings: Finding[];
+  recommendation: string;
+  status: "reviewed";
+  summary: string;
+}
+
+/** The path is excluded by this repository's review file filters. */
+export interface FileReviewOutcomeExcluded {
+  reason: string;
+  status: "excluded";
+}
+
+/** No such file at the resolved source. */
+export interface FileReviewOutcomeNotFound {
+  reason: string;
+  status: "notFound";
+}
+
+/** What came of the request. */
+export type FileReviewOutcome = FileReviewOutcomeReviewed | FileReviewOutcomeExcluded | FileReviewOutcomeNotFound;
+
+/** A checkout on disk. */
+export interface FileSourceLocal {
+  kind: "local";
+  repoRoot: string;
+}
+
+/** A host, at a specific ref — named, because "the file" is meaningless without saying which revision of it was read. */
+export interface FileSourcePr {
+  gitRef: string;
+  kind: "pr";
+  pr: number;
+  provider: string;
+  repo: string;
+}
+
+/** Where the reviewed file was read from. */
+export type FileSource = FileSourceLocal | FileSourcePr;
+
+/** Everything that shapes one review, resolved and redacted. */
+export interface EffectiveRules {
+  /** The exact text appended to the backend's system prompt — calibration rules, the suggestion rules when enabled, and the consumer's `EXTRA_PROMPT` with any repository `instructions` already merged in. */
+  injectedRules: string;
+  repoConfig: RepoConfigSource;
+  scope: RulesScope;
+  settings: ReviewSettings;
+  /** Anything that failed open on the way here. */
+  warnings: string[];
+}
+
+/** Per-repo review overrides parsed from a `.prbot.toml`. */
+export interface RepoConfig {
+  agentic?: boolean | null;
+  /** Cap on the stated change intent handed to the reviewer on a local review, for this repo. */
+  change_intent_max_chars?: number | null;
+  /** Toggle fetching the head commit's CI results into the prompt for this repo. */
+  ci_status?: boolean | null;
+  /** Toggle the OSV.dev dependency vulnerability scan for this repo. */
+  cve_scan?: boolean | null;
+  /** Instructions shaping the `/describe` output specifically — a house PR description layout, release-notes sections, a contributor table. */
+  describe_instructions?: string | null;
+  exclude_globs?: string[] | null;
+  /** Toggle grouping related changed files (source + test, i18n siblings) when packing a large diff, for this repo. */
+  file_bundling?: boolean | null;
+  /** Let the agentic reviewer's `grep` return context lines around each match, for this repo. */
+  grep_context?: boolean | null;
+  include_globs?: string[] | null;
+  /** Extra review instructions in plain language, appended to the system prompt. */
+  instructions?: string | null;
+  max_findings?: number | null;
+  min_confidence?: number | null;
+  model?: string | null;
+  model_explore?: string | null;
+  /** Pass this repo's PR descriptions to the reviewer as a statement of intent to check the diff against. */
+  pr_body?: boolean | null;
+  /** Cap on the description handed to the reviewer, for this repo. */
+  pr_body_max_chars?: number | null;
+  /** Toggle re-anchoring a finding that drifted just off a diff line to the nearest matching diff line (else it folds to the summary), for this repo. */
+  reanchor_findings?: boolean | null;
+  self_critique?: boolean | null;
+  /** Toggle committable suggestion blocks on findings, for this repo. */
+  suggestions?: boolean | null;
+  /** Globs marking vendored third-party source (`thirdparty/**`, `vendor/**`, …). */
+  vendored?: string[] | null;
+}
+
+/** Nothing to read against — no checkout, or a PR with no ref to fetch from. */
+export interface RepoConfigSourceUnavailable {
+  reason: string;
+  status: "unavailable";
+}
+
+/** Looked, and the repository ships no `.prbot.toml`. */
+export interface RepoConfigSourceAbsent {
+  location: string;
+  status: "absent";
+}
+
+/** Read, parsed, and merged over the environment config. */
+export interface RepoConfigSourceApplied {
+  location: string;
+  /** Exactly the keys the file set. */
+  overrides: RepoConfig;
+  status: "applied";
+}
+
+/** Read, but rejected — invalid TOML or an unknown key. */
+export interface RepoConfigSourceInvalid {
+  error: string;
+  location: string;
+  status: "invalid";
+}
+
+/** Where the per-repo configuration came from, and what it said. */
+export type RepoConfigSource = RepoConfigSourceUnavailable | RepoConfigSourceAbsent | RepoConfigSourceApplied | RepoConfigSourceInvalid;
+
+/** The review-relevant configuration, after merging repo overrides. */
+export interface ReviewSettings {
+  agentic: boolean;
+  blastMaxRefs: number;
+  blastMaxSymbols: number;
+  blastRadius: boolean;
+  changeIntentMaxChars: number;
+  ciStatus: boolean;
+  /** The signature appended to every comment this deployment posts. */
+  commentMarker: string;
+  complexityMetrics: boolean;
+  complexityMinCyclomatic: number;
+  cveMaxPackages: number;
+  cveScan: boolean;
+  diagram: boolean;
+  diagramMaxNodes: number;
+  excludeGlobs: string[];
+  fileBundling: boolean;
+  grepContext: boolean;
+  includeGlobs: string[];
+  maxDiffChars: number;
+  maxFindings: number;
+  maxHistoryChars: number;
+  maxTokens: number;
+  maxTurns: number;
+  minConfidence: number;
+  model: string;
+  modelExplore: string;
+  prBody: boolean;
+  prBodyMaxChars: number;
+  reanchorFindings: boolean;
+  reviewSamples: number;
+  sampleLineTolerance: number;
+  sampleMinAgreement: number;
+  selfCritique: boolean;
+  structuralContext: boolean;
+  structuralMaxFiles: number;
+  suggestions: boolean;
+  temperature: number;
+  vendoredGlobs: string[];
+  walkthrough: boolean;
+  walkthroughMaxSymbols: number;
+}
+
+/** A checkout on disk — the pre-PR path. */
+export interface RulesScopeLocal {
+  kind: "local";
+  /** The directory whose `.prbot.toml` was consulted. */
+  repoRoot: string;
+}
+
+/** A pull request on a host. */
+export interface RulesScopePr {
+  kind: "pr";
+  pr: number;
+  provider: string;
+  repo: string;
+}
+
+/** What the rules were resolved for. */
+export type RulesScope = RulesScopeLocal | RulesScopePr;
+
+/** The findings currently on one pull request. */
+export interface FindingsOutput {
+  /** The PR's head as of this call, when the provider reported one. */
+  headSha?: string | null;
+  outcome: FindingsOutcome;
+  pr: number;
+  provider: string;
+  repo: string;
+  /** Present when at least one active finding was written against a commit other than the current head. */
+  revisionWarning?: string | null;
+}
+
+/** Where a finding is in its lifecycle. */
+export type FindingState = "active" | "resolved" | "unparseable";
+
+/** The provider tracks finding lifecycle and this is what it holds. */
+export interface FindingsOutcomeListed {
+  /** Open findings — the ones worth acting on. */
+  active: OutstandingFinding[];
+  /** Findings the provider considers closed. */
+  resolved: OutstandingFinding[];
+  status: "listed";
+  /** Bot comments that carry no fingerprint and cannot be matched. */
+  unparseable: OutstandingFinding[];
+}
+
+/** This provider cannot answer the question, and why. */
+export interface FindingsOutcomeUnsupported {
+  reason: string;
+  status: "unsupported";
+}
+
+/** Whether the provider could answer at all. */
+export type FindingsOutcome = FindingsOutcomeListed | FindingsOutcomeUnsupported;
+
+/** One finding as it currently exists on the pull request. */
+export interface OutstandingFinding {
+  /** The comment body as posted, rendered markdown and all. */
+  body: string;
+  /** The provider's id for the comment, for a caller that wants to link to it. */
+  commentId: string;
+  /** The reconciliation fingerprint — stable across rewordings of the same finding, and the identity to pass back to `resolve-findings`. */
+  fingerprint?: string | null;
+  /** The line the provider currently tracks this thread at — which is not necessarily the line it was posted on, since a provider moves a thread as the file is edited beneath it. */
+  line?: number | null;
+  /** The commit this finding was first written against. */
+  originalCommit?: string | null;
+  path: string;
+  state: FindingState;
+  /** The provider's thread id, where it has threads. */
+  threadId?: string | null;
+}
+
+/** A bundle of findings handed over for investigation. */
+export interface ResolveOutput {
+  /** Stated in the payload, not left to the caller's memory. */
+  disclaimer: string;
+  handoffs: FindingHandoff[];
+  headSha?: string | null;
+  pr: number;
+  provider: string;
+  repo: string;
+  /** Set when the provider cannot track findings at all, with the reason. */
+  unsupported?: string | null;
+}
+
+/** One finding, packaged for a coding agent to act on. */
+export interface FindingHandoff {
+  action: HandoffAction;
+  /** Absent only for [`HandoffAction::NotFound`]. */
+  finding?: OutstandingFinding | null;
+  /** Why this action, in one sentence a caller can show a user. */
+  rationale: string;
+  /** The identity that was asked for — echoed back so a caller can match up a request that produced [`HandoffAction::NotFound`]. */
+  requested: string;
+}
+
+/** What a caller should do with one selected finding. */
+export type HandoffAction = "investigate" | "reverifyAgainstHead" | "alreadyResolved" | "notFound" | "needsHumanJudgement";
+
+/** One finding explained against a local checkout. */
+export interface ExplainOutput {
+  explanation: Explanation;
+  /** The finding as given. */
+  finding: ExplainInput;
+  /** Set when the finding names a revision that is not the one that was read. */
+  revisionWarning?: string | null;
+}
+
+/** The finding to explain. */
+export interface ExplainInput {
+  /** What the reviewer said. */
+  body: string;
+  file: string;
+  line?: number | null;
+  /** The commit the finding was written against, when known. */
+  originalCommit?: string | null;
+  severity?: string | null;
+}
+
+/** A structured explanation of one finding, checked against real code. */
+export interface Explanation {
+  /** What goes wrong if the claim holds, in terms of behaviour rather than style. */
+  affectedBehavior: string;
+  /** What the finding asserts, restated plainly. */
+  claim: string;
+  /** What in the code supports or contradicts it — file, line, and what is actually there. */
+  evidence: string;
+  /** How a person could confirm or refute this — a test to write, a command to run, a line to read. */
+  suggestedVerification: string;
+  /** What the explanation could not settle. */
+  uncertainty: string;
+  /** Whether the investigation found the finding to hold. */
+  verdict: ExplanationVerdict;
+}
+
+/** What the investigation concluded. */
+export type ExplanationVerdict = "holds" | "doesNotHold" | "inconclusive";
+