kaniscope 0.26.0 → 0.27.0

package/README.md

@@ -5,10 +5,19 @@ AI pull-request reviewer: fetches a PR's diff, reviews it, and posts line-anchor
 This package ships a native binary — there is no Rust toolchain to install, no compile step, and no postinstall download. The binary lives in a small per-platform package that npm picks by `os`/`cpu`, so you download one, not five.
 
 ```bash
-npm install kaniscope
+npm install -g kaniscope                 # want the `kaniscope` command on PATH
+kaniscope --provider github --repo me/app --pr 12 --dry-run
+```
+
+```bash
+npm install kaniscope                    # building a bot? this is the one you want
 npx kaniscope --provider github --repo me/app --pr 12 --dry-run
 ```
 
+A plain `npm install kaniscope` is a **local** install, so it does not put `kaniscope` on your `PATH` — running it bare gives `command not found`. That is ordinary npm behaviour, not a broken install: reach it with `npx kaniscope`, or `./node_modules/.bin/kaniscope`, or install with `-g`.
+
+For a bot, the local install is the right one anyway — `require("kaniscope")` works from it immediately and never touches `PATH`.
+
 ## As a library
 
 Build a bot in TypeScript and drive the engine from it:
@@ -33,9 +42,24 @@ for (const f of out.findingsDetail ?? []) {
 
 `review()` runs the binary and parses its JSON. It rejects when the engine exits non-zero, with `exitCode`, `signal` and the full `stderr` on the error.
 
+## A complete bot
+
+[`packaging/examples/node-bot`](https://github.com/nhatvu148/pr-review-core/tree/main/packaging/examples/node-bot) is a working GitHub review bot on this package — an HTTP server, webhook signature verification, and one `review()` call. It ships with tests that run against a fake engine, so they need no API key and no pull request.
+
 ## Configuration
 
-Everything beyond the flags above — the model, the API key, provider tokens, file globs, confidence floors, bot identity — is read from the environment, exactly as it is for the Rust library. Pass overrides in `env` (merged over `process.env`, unless `inheritEnv: false`).
+Everything beyond the flags above — the model, provider tokens, file globs, confidence floors, bot identity — is engine configuration. Pass it typed:
+
+```ts
+await review({
+  provider: "github", repo, pr,
+  config: { openrouterModel: "anthropic/claude-sonnet-5", minConfidence: 70, agentic: true },
+});
+```
+
+`ReviewConfig` is **generated from the engine's own spec** — every option with its type, default and documentation — so it cannot drift from what the binary actually reads, and your editor completes them.
+
+`env` still takes raw strings and is applied *after* `config`, so it wins. That is deliberate: it stays the escape hatch for anything the typed layer does not model.
 
 The essentials: `OPENROUTER_API_KEY`, plus `GH_TOKEN` / `GITLAB_TOKEN` / Bitbucket credentials for the provider you use. See the [engine README](https://github.com/nhatvu148/pr-review-core#injecting-identity-and-prompt) for the full list, and `.prbot.toml` for per-repo settings.
 

package/config.d.ts

@@ -0,0 +1,130 @@
+// GENERATED by packaging/generate-types.mjs — do not edit.
+// Regenerate with: node packaging/generate-types.mjs
+
+/**
+ * Typed overrides for the engine's environment-driven configuration.
+ *
+ * Every field maps to one environment variable. Passing `config` is exactly
+ * equivalent to setting those variables, and `env` still wins over it — the raw
+ * escape hatch stays authoritative for anything not modelled here.
+ */
+export interface ReviewConfig {
+  /** Clone the repo and let the model investigate cross-file context (grep / read_file / list_dir) before writing findings. Default: `false`. (`AGENTIC`) */
+  agentic?: boolean;
+  /** Atlassian API token for Bitbucket. (`BB_API_TOKEN`) */
+  bbApiToken?: string;
+  /** Atlassian account email, paired with BB_API_TOKEN for Bitbucket basic auth. (`BB_EMAIL`) */
+  bbEmail?: string;
+  /** HMAC secret for Bitbucket webhook deliveries. (`BITBUCKET_WEBHOOK_SECRET`) */
+  bitbucketWebhookSecret?: string;
+  /** References reported per symbol by the blast-radius scan. Default: `8`. (`BLAST_MAX_REFS`) */
+  blastMaxRefs?: number;
+  /** Changed symbols the blast-radius scan will follow. Default: `12`. (`BLAST_MAX_SYMBOLS`) */
+  blastMaxSymbols?: number;
+  /** Precompute callers, tests and type uses of changed symbols and seed the agentic reviewer with them. Measured no recall gain on well-named repos; may help on large monorepos. Default: `true`. (`BLAST_RADIUS`) */
+  blastRadius?: boolean;
+  /** Fetch the head commit's CI results so the reviewer cannot assert a broken build CI already decided. One extra API call per review. Default: `true`. (`CI_STATUS`) */
+  ciStatus?: boolean;
+  /** Signature appended to every comment, and the dedupe key for finding the bot's own comments on re-review. Default: `🤖 ai-pr-review`. (`COMMENT_MARKER`) */
+  commentMarker?: string;
+  /** Report cyclomatic and cognitive complexity (A-F) for touched functions. Deterministic; no model call. Default: `true`. (`COMPLEXITY_METRICS`) */
+  complexityMetrics?: boolean;
+  /** Only surface functions at or above this cyclomatic complexity. Default: `8`. (`COMPLEXITY_MIN_CYCLOMATIC`) */
+  complexityMinCyclomatic?: number;
+  /** Distinct packages queried against OSV per review. Default: `100`. (`CVE_MAX_PACKAGES`) */
+  cveMaxPackages?: number;
+  /** Check added lockfile entries against OSV.dev for known vulnerabilities. Default: `true`. (`CVE_SCAN`) */
+  cveScan?: boolean;
+  /** Free-form instructions shaping /describe output. Outranks the built-in layout. (`DESCRIBE_INSTRUCTIONS`) */
+  describeInstructions?: string;
+  /** Append the mermaid change diagram. Skipped on Bitbucket, and whenever there are no edges to draw. Default: `false`. (`DIAGRAM`) */
+  diagram?: boolean;
+  /** Symbols considered for edge linking, and so the diagram's node budget. Default: `12`. (`DIAGRAM_MAX_NODES`) */
+  diagramMaxNodes?: number;
+  /** Globs skipped before the model call. Setting this REPLACES the lockfile/generated/vendored/minified defaults. (`EXCLUDE_GLOBS`) */
+  excludeGlobs?: string[];
+  /** Appended to the built-in system prompts. Your conventions, in plain language. Set but empty is the same as unset: EXTRA_SYSTEM_PROMPT_FILE is consulted either way. (`EXTRA_SYSTEM_PROMPT`) */
+  extraSystemPrompt?: string;
+  /** Path whose contents are used when EXTRA_SYSTEM_PROMPT is unset OR empty. For baking a large conventions block into an image. (`EXTRA_SYSTEM_PROMPT_FILE`) */
+  extraSystemPromptFile?: string;
+  /** Keep related files (a source and its test, i18n siblings) adjacent when packing, so the model reviews them together. Default: `true`. (`FILE_BUNDLING`) */
+  fileBundling?: boolean;
+  /** GitHub API base. Point at a GitHub Enterprise host. Default: `https://api.github.com`. (`GH_API_BASE`) */
+  ghApiBase?: string;
+  /** GitHub token used to read the PR and post comments. (`GH_TOKEN`) */
+  ghToken?: string;
+  /** HMAC secret GitHub signs webhook deliveries with. (`GITHUB_WEBHOOK_SECRET`) */
+  githubWebhookSecret?: string;
+  /** GitLab API base. Point at a self-hosted instance. Default: `https://gitlab.com/api/v4`. (`GITLAB_API_BASE`) */
+  gitlabApiBase?: string;
+  /** GitLab token used to read the MR and post notes. (`GITLAB_TOKEN`) */
+  gitlabToken?: string;
+  /** Token GitLab sends as X-Gitlab-Token on webhook deliveries. (`GITLAB_WEBHOOK_SECRET`) */
+  gitlabWebhookSecret?: string;
+  /** Let the agentic reviewer's grep request 1-8 lines of context per match, so it can judge a second site without a read_file round trip. Default: `true`. (`GREP_CONTEXT`) */
+  grepContext?: boolean;
+  /** If set, ONLY files matching these globs are reviewed. (`INCLUDE_GLOBS`) */
+  includeGlobs?: string[];
+  /** OpenAI-compatible endpoint, e.g. http://localhost:11434/v1 for Ollama. Default: `https://openrouter.ai/api/v1`. (`LLM_BASE_URL`) */
+  llmBaseUrl?: string;
+  /** Size budget for the packed diff. Beyond it, whole files are ranked and dropped rather than truncated mid-hunk. Default: `200000`. (`MAX_DIFF_CHARS`) */
+  maxDiffChars?: number;
+  /** Cap findings per PR, ranked by severity then confidence. Default: `20`. (`MAX_FINDINGS`) */
+  maxFindings?: number;
+  /** Cap on the agentic conversation carried between turns. Default: `45000`. (`MAX_HISTORY_CHARS`) */
+  maxHistoryChars?: number;
+  /** Tool-call turns the agentic reviewer may take before it must conclude. Default: `6`. (`MAX_TURNS`) */
+  maxTurns?: number;
+  /** Drop findings below this confidence (0-100). Default: `0`. (`MIN_CONFIDENCE`) */
+  minConfidence?: number;
+  /** API key for the OpenAI-compatible endpoint. Required for every review. (`OPENROUTER_API_KEY`) */
+  openrouterApiKey?: string;
+  /** HTTP-Referer sent to OpenRouter, for its dashboard attribution. Default: `https://github.com/nhatvu148/pr-review-core`. (`OPENROUTER_HTTP_REFERER`) */
+  openrouterHttpReferer?: string;
+  /** Retries on a failed or rate-limited model call. Default: `3`. (`OPENROUTER_MAX_RETRIES`) */
+  openrouterMaxRetries?: number;
+  /** Cap on completion tokens per model call. Default: `4000`. (`OPENROUTER_MAX_TOKENS`) */
+  openrouterMaxTokens?: number;
+  /** Model that writes the review, and the synthesis half of the agentic split. Default: `anthropic/claude-sonnet-4.5`. (`OPENROUTER_MODEL`) */
+  openrouterModel?: string;
+  /** Cheaper model for the agentic explore turns, before synthesis. Default: `moonshotai/kimi-k2-0905`. (`OPENROUTER_MODEL_EXPLORE`) */
+  openrouterModelExplore?: string;
+  /** Sampling temperature. Low on purpose: a review should be reproducible. Default: `0.2`. (`OPENROUTER_TEMPERATURE`) */
+  openrouterTemperature?: number;
+  /** Per-request timeout for a model call. Default: `120`. (`OPENROUTER_TIMEOUT_SECS`) */
+  openrouterTimeoutSecs?: number;
+  /** X-Title sent to OpenRouter, for its dashboard attribution. Default: `pr-review`. (`OPENROUTER_X_TITLE`) */
+  openrouterXTitle?: string;
+  /** OSV API base. Override for a mirror or a test double. Default: `https://api.osv.dev`. (`OSV_API_BASE`) */
+  osvApiBase?: string;
+  /** HTTP port for a bot serving webhooks. 8088 locally to dodge the usual Docker Desktop clash on 8080. Default: `8088`. (`PORT`) */
+  port?: number;
+  /** Path to append one JSON record per review to. `-` means stdout; empty means off, so a line in an env file can disable it without being deleted. (`PRBOT_RUN_LOG`) */
+  prbotRunLog?: string;
+  /** Give the reviewer the PR's own description as a statement of intent to check the diff against. Rendered inside an untrusted fence, so it can never direct the review. Default: `true`. (`PR_BODY`) */
+  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;
+  /** 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`) */
+  reviewOnUpdate?: boolean;
+  /** Second skeptical pass that removes false positives and low-value nits. Default: `true`. (`SELF_CRITIQUE`) */
+  selfCritique?: boolean;
+  /** Name the enclosing function or symbol of each changed line, via tree-sitter, with no clone. Default: `true`. (`STRUCTURAL_CONTEXT`) */
+  structuralContext?: boolean;
+  /** Files fetched for structural context before it stops. Default: `15`. (`STRUCTURAL_MAX_FILES`) */
+  structuralMaxFiles?: number;
+  /** Attach a committable suggestion block when the model proposed replacement text that validates against the anchored line. Never on a re-anchored finding. Default: `true`. (`SUGGESTIONS`) */
+  suggestions?: boolean;
+  /** User-Agent sent to provider APIs. Default: `pr-review-core`. (`USER_AGENT`) */
+  userAgent?: string;
+  /** Globs marking third-party source: hygiene findings are suppressed inside them and the reviewer is told not to edit there. Setting this REPLACES the defaults. (`VENDORED_GLOBS`) */
+  vendoredGlobs?: string[];
+  /** Append the per-file walkthrough table to the summary comment. Default: `false`. (`WALKTHROUGH`) */
+  walkthrough?: boolean;
+  /** Symbols listed per file before the cell collapses to (+N more). Default: `4`. (`WALKTHROUGH_MAX_SYMBOLS`) */
+  walkthroughMaxSymbols?: number;
+  /** Shared secret authenticating a bot's own async worker callback. (`WORKER_TOKEN`) */
+  workerToken?: string;
+}

package/config.js

@@ -0,0 +1,94 @@
+// GENERATED by packaging/generate-types.mjs — do not edit.
+// Regenerate with: node packaging/generate-types.mjs
+
+// Option name -> [environment variable, kind]. The kind drives coercion: the
+// engine reads strings, so a boolean has to arrive as "true", a glob list as a
+// comma-separated string, and a number as its decimal form.
+const CONFIG_ENV = {
+  agentic: ["AGENTIC", "Bool"],
+  bbApiToken: ["BB_API_TOKEN", "Secret"],
+  bbEmail: ["BB_EMAIL", "Str"],
+  bitbucketWebhookSecret: ["BITBUCKET_WEBHOOK_SECRET", "Secret"],
+  blastMaxRefs: ["BLAST_MAX_REFS", "Int"],
+  blastMaxSymbols: ["BLAST_MAX_SYMBOLS", "Int"],
+  blastRadius: ["BLAST_RADIUS", "Bool"],
+  ciStatus: ["CI_STATUS", "Bool"],
+  commentMarker: ["COMMENT_MARKER", "Str"],
+  complexityMetrics: ["COMPLEXITY_METRICS", "Bool"],
+  complexityMinCyclomatic: ["COMPLEXITY_MIN_CYCLOMATIC", "Int"],
+  cveMaxPackages: ["CVE_MAX_PACKAGES", "Int"],
+  cveScan: ["CVE_SCAN", "Bool"],
+  describeInstructions: ["DESCRIBE_INSTRUCTIONS", "Str"],
+  diagram: ["DIAGRAM", "Bool"],
+  diagramMaxNodes: ["DIAGRAM_MAX_NODES", "Int"],
+  excludeGlobs: ["EXCLUDE_GLOBS", "Globs"],
+  extraSystemPrompt: ["EXTRA_SYSTEM_PROMPT", "Str"],
+  extraSystemPromptFile: ["EXTRA_SYSTEM_PROMPT_FILE", "Path"],
+  fileBundling: ["FILE_BUNDLING", "Bool"],
+  ghApiBase: ["GH_API_BASE", "Str"],
+  ghToken: ["GH_TOKEN", "Secret"],
+  githubWebhookSecret: ["GITHUB_WEBHOOK_SECRET", "Secret"],
+  gitlabApiBase: ["GITLAB_API_BASE", "Str"],
+  gitlabToken: ["GITLAB_TOKEN", "Secret"],
+  gitlabWebhookSecret: ["GITLAB_WEBHOOK_SECRET", "Secret"],
+  grepContext: ["GREP_CONTEXT", "Bool"],
+  includeGlobs: ["INCLUDE_GLOBS", "Globs"],
+  llmBaseUrl: ["LLM_BASE_URL", "Str"],
+  maxDiffChars: ["MAX_DIFF_CHARS", "Int"],
+  maxFindings: ["MAX_FINDINGS", "Int"],
+  maxHistoryChars: ["MAX_HISTORY_CHARS", "Int"],
+  maxTurns: ["MAX_TURNS", "Int"],
+  minConfidence: ["MIN_CONFIDENCE", "Int"],
+  openrouterApiKey: ["OPENROUTER_API_KEY", "Secret"],
+  openrouterHttpReferer: ["OPENROUTER_HTTP_REFERER", "Str"],
+  openrouterMaxRetries: ["OPENROUTER_MAX_RETRIES", "Int"],
+  openrouterMaxTokens: ["OPENROUTER_MAX_TOKENS", "Int"],
+  openrouterModel: ["OPENROUTER_MODEL", "Str"],
+  openrouterModelExplore: ["OPENROUTER_MODEL_EXPLORE", "Str"],
+  openrouterTemperature: ["OPENROUTER_TEMPERATURE", "Float"],
+  openrouterTimeoutSecs: ["OPENROUTER_TIMEOUT_SECS", "Int"],
+  openrouterXTitle: ["OPENROUTER_X_TITLE", "Str"],
+  osvApiBase: ["OSV_API_BASE", "Str"],
+  port: ["PORT", "Int"],
+  prbotRunLog: ["PRBOT_RUN_LOG", "Path"],
+  prBody: ["PR_BODY", "Bool"],
+  prBodyMaxChars: ["PR_BODY_MAX_CHARS", "Int"],
+  reanchorFindings: ["REANCHOR_FINDINGS", "Bool"],
+  reviewOnUpdate: ["REVIEW_ON_UPDATE", "Bool"],
+  selfCritique: ["SELF_CRITIQUE", "Bool"],
+  structuralContext: ["STRUCTURAL_CONTEXT", "Bool"],
+  structuralMaxFiles: ["STRUCTURAL_MAX_FILES", "Int"],
+  suggestions: ["SUGGESTIONS", "Bool"],
+  userAgent: ["USER_AGENT", "Str"],
+  vendoredGlobs: ["VENDORED_GLOBS", "Globs"],
+  walkthrough: ["WALKTHROUGH", "Bool"],
+  walkthroughMaxSymbols: ["WALKTHROUGH_MAX_SYMBOLS", "Int"],
+  workerToken: ["WORKER_TOKEN", "Secret"],
+};
+
+/** Turn a `config` object into the environment variables the engine reads. */
+function configToEnv(config) {
+  const env = {};
+  for (const [key, value] of Object.entries(config || {})) {
+    // `hasOwnProperty`, not a bare lookup: `CONFIG_ENV["toString"]` finds
+    // Object.prototype's method, which is truthy, so the unknown-key check below
+    // passes and the destructuring then fails with "entry is not iterable" —
+    // a confusing error for what is simply a typo.
+    if (!Object.prototype.hasOwnProperty.call(CONFIG_ENV, key)) {
+      // Unknown keys are rejected rather than dropped, for the same reason
+      // unknown review options are: a silently ignored `dryRun` posts a live
+      // review, and a silently ignored `minConfidence` ships every nit.
+      throw new TypeError(`kaniscope: unknown config option ${JSON.stringify(key)}`);
+    }
+    const entry = CONFIG_ENV[key];
+    if (value === undefined || value === null) continue;
+    const [name, kind] = entry;
+    env[name] =
+      kind === "Bool" ? (value ? "true" : "false")
+      : kind === "Globs" ? (Array.isArray(value) ? value.join(",") : String(value))
+      : String(value);
+  }
+  return env;
+}
+
+module.exports = { CONFIG_ENV, configToEnv };

package/index.d.ts

@@ -2,8 +2,19 @@ import type { RunReviewOutput } from "./types";
 
 export type { RunReviewOutput, Finding, InlineComment, Usage } from "./types";
 
+export type { ReviewConfig } from "./config";
+
 /** Options common to every call: how the binary is found and run. */
 export interface SpawnOptions {
+  /**
+   * Typed overrides for the engine's configuration — the same variables `env`
+   * carries, with names, types and documentation generated from the engine's
+   * own spec.
+   *
+   * `env` is applied *after* this and therefore wins, so the raw escape hatch
+   * stays authoritative for anything not modelled.
+   */
+  config?: import("./config").ReviewConfig;
   /**
    * Environment overrides, merged over `process.env` (see {@link inheritEnv}).
    * This is where the engine's configuration lives — `OPENROUTER_API_KEY`,

package/index.js

@@ -14,6 +14,7 @@
 const { spawn } = require("node:child_process");
 const { StringDecoder } = require("node:string_decoder");
 const { binaryPath } = require("./binary.js");
+const { configToEnv } = require("./config.js");
 
 /** Flags that take a value, mapped from the camelCase option name. */
 const VALUE_FLAGS = {
@@ -41,7 +42,7 @@ const BOOL_FLAGS = {
  * one mistake in this API with consequences that cannot be undone.
  */
 function buildArgs(options) {
-  const known = new Set([...Object.keys(VALUE_FLAGS), ...Object.keys(BOOL_FLAGS), "env", "inheritEnv", "timeoutMs", "onLog", "binary", "diff"]);
+  const known = new Set([...Object.keys(VALUE_FLAGS), ...Object.keys(BOOL_FLAGS), "env", "inheritEnv", "timeoutMs", "onLog", "binary", "diff", "config"]);
   for (const key of Object.keys(options)) {
     if (!known.has(key)) {
       throw new TypeError(`kaniscope: unknown option ${JSON.stringify(key)}`);
@@ -78,7 +79,15 @@ function run(bin, args, options) {
     // no diff on stdin and would block or read junk. Explicit both ways.
     const wantsStdin = options.diff !== undefined && options.diff !== null;
     const child = spawn(bin, args, {
-      env: options.inheritEnv === false ? { ...options.env } : { ...process.env, ...options.env },
+      // Order is the contract: inherited, then `config`, then raw `env`. The
+      // typed layer is a convenience over the same variables, so anything it
+      // does not model — or models wrongly — must remain reachable, and the
+      // escape hatch is only an escape hatch if it wins.
+      env: {
+        ...(options.inheritEnv === false ? {} : process.env),
+        ...configToEnv(options.config),
+        ...options.env,
+      },
       stdio: [wantsStdin ? "pipe" : "ignore", "pipe", "pipe"],
     });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaniscope",
-  "version": "0.26.0",
+  "version": "0.27.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",
@@ -27,15 +27,17 @@
     "index.js",
     "index.d.ts",
     "types.d.ts",
+    "config.js",
+    "config.d.ts",
     "binary.js",
     "bin/kaniscope.js",
     "README.md"
   ],
   "optionalDependencies": {
-    "@nhatvu148/kaniscope-darwin-arm64": "0.26.0",
-    "@nhatvu148/kaniscope-darwin-x64": "0.26.0",
-    "@nhatvu148/kaniscope-linux-arm64": "0.26.0",
-    "@nhatvu148/kaniscope-linux-x64": "0.26.0",
-    "@nhatvu148/kaniscope-win32-x64": "0.26.0"
+    "@nhatvu148/kaniscope-darwin-arm64": "0.27.0",
+    "@nhatvu148/kaniscope-darwin-x64": "0.27.0",
+    "@nhatvu148/kaniscope-linux-arm64": "0.27.0",
+    "@nhatvu148/kaniscope-linux-x64": "0.27.0",
+    "@nhatvu148/kaniscope-win32-x64": "0.27.0"
   }
 }