kaniscope 0.26.0

package/README.md

@@ -0,0 +1,75 @@
+# kaniscope
+
+AI pull-request reviewer: fetches a PR's diff, reviews it, and posts line-anchored inline comments plus a summary. Works with **GitHub**, **GitLab** and **Bitbucket**.
+
+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
+npx kaniscope --provider github --repo me/app --pr 12 --dry-run
+```
+
+## As a library
+
+Build a bot in TypeScript and drive the engine from it:
+
+```ts
+import { review } from "kaniscope";
+
+const out = await review({
+  provider: "github",
+  repo: "me/app",
+  pr: 12,
+  dryRun: true,
+  env: { OPENROUTER_API_KEY: key, GH_TOKEN: token, MODEL: "anthropic/claude-sonnet-5" },
+  onLog: (line) => console.error(line),
+});
+
+console.log(out.recommendation, `${out.findings} finding(s)`);
+for (const f of out.findingsDetail ?? []) {
+  console.log(`${f.severity} ${f.file}:${f.line ?? "-"} — ${f.body}`);
+}
+```
+
+`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.
+
+## 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`).
+
+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.
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `review(options)` | Review a PR, or a local diff with `{ local: true }`. |
+| `schema()` | The JSON Schema of a review result. No key, no network. |
+| `version()` | The engine version this package's binary was built from. |
+| `binaryPath()` | Absolute path to the bundled binary. |
+
+`RunReviewOutput`, `Finding`, `InlineComment` and `Usage` are exported as types. They are **generated** from the binary's own `--schema`, so they cannot drift from what the engine actually emits.
+
+## Reviewing without a PR
+
+```bash
+kaniscope --local --base main          # the working tree against a ref
+git diff --staged | kaniscope --local  # any diff, from anywhere
+```
+
+Through the API, `base` picks the ref and `diff` is the stdin form:
+
+```ts
+await review({ local: true, base: "main" });
+await review({ local: true, diff: await readFile("change.patch", "utf8") });
+```
+
+Same reviewer, same prompts, same anchoring — it just has nowhere to post.
+
+## Why a subprocess and not native bindings
+
+The engine takes five scalars, reads its configuration from the environment, and returns one JSON document after minutes of network and git work. A native addon would buy nothing a pipe does not already give, and would cost an ABI-pinned build per Node release plus a second declaration of every wire type. `uv` and `ruff` reach this ecosystem the same way.
+
+## License
+
+MIT OR Apache-2.0. Source: [nhatvu148/pr-review-core](https://github.com/nhatvu148/pr-review-core).

package/bin/kaniscope.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+"use strict";
+
+// The CLI entry point: hand this process straight to the native binary.
+//
+// `spawnSync` with stdio inherited rather than `execFileSync`, so stdin still
+// pipes (`git diff | kaniscope --local`) and the child's exit code is this
+// process's exit code — a review that fails must not exit 0 through a wrapper.
+
+const { spawnSync } = require("node:child_process");
+const { binaryPath } = require("../binary.js");
+
+let bin;
+try {
+  bin = binaryPath();
+} catch (err) {
+  console.error(err.message);
+  process.exit(1);
+}
+
+const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
+
+// A child killed by a signal has a null status. Reporting that as 0 would tell a
+// CI job that a review which was OOM-killed had passed.
+if (result.error) {
+  console.error(`kaniscope: could not run ${bin}: ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status === null ? 1 : result.status);

package/binary.js

@@ -0,0 +1,90 @@
+"use strict";
+
+// Where the native `kaniscope` binary is, for this host.
+//
+// The binary is not in this package. It ships in one small per-platform package
+// each declaring `os`/`cpu`, listed here as `optionalDependencies` — so npm
+// installs exactly the one matching the host and skips the rest, and a Windows
+// developer never downloads a Linux binary. This is esbuild's arrangement, and it
+// is the reason this package works without a postinstall script that downloads
+// from the network (blocked in a lot of CI, and a supply-chain surface besides).
+
+const path = require("node:path");
+
+/** npm's `process.platform`-`process.arch` pair, as it appears in the package name. */
+function platformKey() {
+  return `${process.platform}-${process.arch}`;
+}
+
+const SUPPORTED = new Set([
+  "darwin-arm64",
+  "darwin-x64",
+  "linux-arm64",
+  "linux-x64",
+  "win32-x64",
+]);
+
+/**
+ * Absolute path to the `kaniscope` executable.
+ *
+ * Throws with the actual reason rather than letting a spawn fail later with
+ * ENOENT: by far the most common cause is an install with
+ * `--no-optional`/`--omit=optional`, which silently skips every platform package
+ * and leaves this one intact but inert. That produces a package that is present
+ * and unusable, and "ENOENT: kaniscope" points at nothing.
+ */
+function binaryPath() {
+  // An explicit override wins, always, and is therefore checked FIRST — before
+  // the supported-platform test below. The unsupported-platform error tells you
+  // to build from source and set this variable, so reading it only after that
+  // check makes the advertised escape hatch unreachable on precisely the
+  // platforms it exists for. It is also how you point at a locally built binary
+  // or an air-gapped vendored copy without editing inside node_modules.
+  const override = process.env.KANISCOPE_BINARY_PATH;
+  if (override) return override;
+
+  const key = platformKey();
+  if (!SUPPORTED.has(key)) {
+    throw new Error(
+      `kaniscope has no prebuilt binary for ${key}. Supported: ${[...SUPPORTED].join(", ")}. ` +
+        `Build from source with \`cargo install pr-review-core --features cli\`, and set ` +
+        `KANISCOPE_BINARY_PATH to the result.`
+    );
+  }
+
+  // Scoped, matching what the generator publishes — see the note there on npm's
+  // spam detection. The wrapper itself stays unscoped.
+  const pkg = `@nhatvu148/kaniscope-${key}`;
+  const exe = process.platform === "win32" ? "kaniscope.exe" : "kaniscope";
+
+  // Resolve the package's manifest, not the binary: `bin/` is not an export, and
+  // `require.resolve` on a bare non-JS path fails under some resolvers.
+  //
+  // Two search roots, in this order. Normally the first is the only one that
+  // matters — a real install puts this package and its platform package side by
+  // side in one `node_modules`, and pnpm's layout resolves the same way. The
+  // second covers the case where this package is a SYMLINK: `npm link`, a
+  // `file:` dependency, or a monorepo workspace. Resolution then starts from the
+  // link target — outside the tree that holds the binary — and the first attempt
+  // fails on a perfectly good install. Version skew is not a risk in the
+  // fallback, because the wrapper pins its platform packages to one exact
+  // version rather than a range.
+  for (const from of [null, process.cwd()]) {
+    try {
+      const manifest = from
+        ? require.resolve(`${pkg}/package.json`, { paths: [from] })
+        : require.resolve(`${pkg}/package.json`);
+      return path.join(path.dirname(manifest), "bin", exe);
+    } catch {
+      // Try the next root; the throw below reports the failure once.
+    }
+  }
+
+  throw new Error(
+    `kaniscope could not find its native binary (package ${pkg} is not installed). ` +
+      `If you installed with --no-optional or --omit=optional, reinstall without it: ` +
+      `the binary ships in an optional per-platform package.`
+  );
+}
+
+module.exports = { binaryPath, platformKey };

package/index.d.ts

@@ -0,0 +1,70 @@
+import type { RunReviewOutput } from "./types";
+
+export type { RunReviewOutput, Finding, InlineComment, Usage } from "./types";
+
+/** Options common to every call: how the binary is found and run. */
+export interface SpawnOptions {
+  /**
+   * Environment overrides, merged over `process.env` (see {@link inheritEnv}).
+   * This is where the engine's configuration lives — `OPENROUTER_API_KEY`,
+   * `GH_TOKEN`, `MODEL`, `BOT_NAME`, globs, confidence floors — exactly as it
+   * does for a Rust consumer.
+   */
+  env?: Record<string, string | undefined>;
+  /** Set `false` to pass only {@link env}, ignoring `process.env`. Default `true`. */
+  inheritEnv?: boolean;
+  /** Kill the review after this many milliseconds and reject. */
+  timeoutMs?: number;
+  /** Called once per line the engine logs to stderr, as it happens. */
+  onLog?: (line: string) => void;
+  /** Override the binary to run. Defaults to the bundled per-platform one. */
+  binary?: string;
+}
+
+export interface ReviewOptions extends SpawnOptions {
+  /** `github` | `gitlab` | `bitbucket`. Required unless {@link local}. */
+  provider?: string;
+  /** `owner/repo` (GitHub, GitLab) or `workspace/repo` (Bitbucket). */
+  repo?: string;
+  /** PR / MR number. */
+  pr?: number;
+  /** Produce the review but post nothing. */
+  dryRun?: boolean;
+  /** Review a diff instead of a PR. Nothing is posted; there is nowhere to post. */
+  local?: boolean;
+  /** With {@link local}: diff the working tree against this ref. */
+  base?: string;
+  /** With {@link local}: the checkout to read files from. Defaults to cwd. */
+  repoRoot?: string;
+  /** With {@link local}: what to call this change. Defaults to the branch name. */
+  label?: string;
+  /** Also write the result as JSON to this path, atomically. */
+  jsonOut?: string;
+  /**
+   * A unified diff to feed the engine on stdin — the way to use
+   * `{ local: true }` without a {@link base}, matching
+   * `git diff --staged | kaniscope --local`.
+   *
+   * Without it the child's stdin is closed rather than inherited: a server has
+   * no diff on its own stdin, so inheriting would block on a read that never
+   * returns.
+   */
+  diff?: string;
+}
+
+/**
+ * Review a pull request, or a local diff with `{ local: true }`.
+ *
+ * Rejects when the engine exits non-zero; the error carries `exitCode`,
+ * `signal` and the full `stderr`.
+ */
+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>>;
+
+/** The engine version this package's binary was built from. */
+export function version(options?: SpawnOptions): Promise<string>;
+
+/** Absolute path to the bundled native binary. Throws if none matches the host. */
+export function binaryPath(): string;

package/index.js

@@ -0,0 +1,225 @@
+"use strict";
+
+// The programmatic API: what a bot written in TypeScript actually calls.
+//
+// Under it is a subprocess, and that is the point rather than a compromise. The
+// engine's entry point takes five scalars, reads the rest of its configuration
+// from the environment, and returns one JSON-serializable struct after minutes of
+// network and git work. Binding that across an FFI boundary would buy nothing a
+// pipe does not already give, and would cost an ABI-pinned build matrix, a
+// tokio<->libuv bridge, and a second declaration of every wire type that can
+// drift from the first. The types below are generated from the binary's own
+// `--schema`, so they cannot.
+
+const { spawn } = require("node:child_process");
+const { StringDecoder } = require("node:string_decoder");
+const { binaryPath } = require("./binary.js");
+
+/** Flags that take a value, mapped from the camelCase option name. */
+const VALUE_FLAGS = {
+  provider: "--provider",
+  repo: "--repo",
+  pr: "--pr",
+  base: "--base",
+  repoRoot: "--repo-root",
+  label: "--label",
+  jsonOut: "--json-out",
+};
+
+/** Boolean flags, mapped from the camelCase option name. */
+const BOOL_FLAGS = {
+  local: "--local",
+  dryRun: "--dry-run",
+};
+
+/**
+ * Turn an options object into an argv for the binary.
+ *
+ * Unknown keys are rejected rather than dropped. A silently ignored `dry_run`
+ * (snake_case, the natural typo when porting from the Python client) would post a
+ * live review to someone's PR while the caller believed it was a dry run — the
+ * 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"]);
+  for (const key of Object.keys(options)) {
+    if (!known.has(key)) {
+      throw new TypeError(`kaniscope: unknown option ${JSON.stringify(key)}`);
+    }
+  }
+
+  const args = ["--json"];
+  for (const [key, flag] of Object.entries(VALUE_FLAGS)) {
+    const value = options[key];
+    if (value === undefined || value === null) continue;
+    args.push(flag, String(value));
+  }
+  for (const [key, flag] of Object.entries(BOOL_FLAGS)) {
+    if (options[key]) args.push(flag);
+  }
+  return args;
+}
+
+/**
+ * Run the binary and return its stdout, stderr and exit code.
+ *
+ * Accumulates rather than using a buffered helper on purpose: `execFile` caps
+ * stdout at 1 MB by default, and a review of a large PR — every finding, every
+ * rendered inline comment body — goes past that. The failure mode there is a
+ * truncated JSON parse error on exactly the big PRs you most wanted reviewed.
+ */
+function run(bin, args, options) {
+  return new Promise((resolve, reject) => {
+    // stdin is `pipe` only when a diff was supplied. The CLI's most general door
+    // is `git diff | kaniscope --local`, and with stdin hard-wired to "ignore"
+    // that mode was unreachable through this API: the child saw EOF immediately
+    // and bailed with "empty diff". Inheriting the parent's stdin instead — what
+    // the Python client used to do by omission — is worse, because a server has
+    // 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 },
+      stdio: [wantsStdin ? "pipe" : "ignore", "pipe", "pipe"],
+    });
+
+    if (wantsStdin) {
+      // A child that exits before reading it all (bad flags, missing key) makes
+      // this write fail with EPIPE. That is the child's error to report, not a
+      // crash in the parent, so swallow it and let the exit code speak.
+      child.stdin.on("error", () => {});
+      child.stdin.end(options.diff);
+    }
+
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (c) => stdout.push(c));
+
+    // The engine logs progress here (tool calls, warnings). A caller that wants
+    // to surface them live gets them line by line; otherwise they are still
+    // kept, because they are what makes a failure diagnosable.
+    //
+    // `carry` holds the incomplete tail of the last chunk. A `data` event is a
+    // chunk of a byte stream, NOT a line: a log line straddling two events was
+    // being delivered as two fragments, which breaks the "called once per line"
+    // contract in index.d.ts and, worse, hands a caller half a message to log.
+    // The StringDecoder is the same bug one level down — it holds a partial
+    // UTF-8 sequence split across chunks instead of turning it into U+FFFD.
+    const decoder = new StringDecoder("utf8");
+    let carry = "";
+    const emitLines = (text, flush) => {
+      if (!options.onLog) return;
+      carry += text;
+      const lines = carry.split("\n");
+      carry = lines.pop(); // the incomplete tail; more bytes may still be coming
+      for (const line of lines) if (line.trim()) options.onLog(line);
+      // At EOF nothing more is coming, so the tail is a whole line after all —
+      // which is the common case, since the last log line has no trailing \n.
+      if (flush && carry.trim()) {
+        options.onLog(carry);
+        carry = "";
+      }
+    };
+
+    child.stderr.on("data", (c) => {
+      stderr.push(c);
+      emitLines(decoder.write(c), false);
+    });
+    child.stderr.on("end", () => emitLines(decoder.end(), true));
+
+    let timer;
+    if (options.timeoutMs) {
+      timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        // Carry the same diagnostics as every other rejection from this file.
+        // A review that ran the full timeout usually printed the reason it was
+        // stuck, and dropping stderr here threw away the only evidence of it —
+        // on the one failure path where there is no exit code to look at either.
+        // `timedOut` because "was it killed by the timeout, or did it die on its
+        // own?" is otherwise only answerable by matching on the message string.
+        const err = new Error(`kaniscope: timed out after ${options.timeoutMs}ms`);
+        err.timedOut = true;
+        err.exitCode = null;
+        err.signal = "SIGKILL";
+        err.stderr = Buffer.concat(stderr).toString();
+        reject(err);
+      }, options.timeoutMs);
+    }
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(new Error(`kaniscope: could not run ${bin}: ${err.message}`));
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      resolve({
+        code,
+        signal,
+        stdout: Buffer.concat(stdout).toString(),
+        stderr: Buffer.concat(stderr).toString(),
+      });
+    });
+  });
+}
+
+/** Trim stderr for an error message — the tail is where the cause is. */
+function tail(text, lines = 20) {
+  const all = text.trimEnd().split("\n");
+  return all.slice(-lines).join("\n");
+}
+
+/**
+ * Review a pull request, or a local diff with `{ local: true }`.
+ *
+ * Configuration beyond these flags — the API key, the model, globs, confidence
+ * floors, bot identity — comes from the environment, exactly as it does for a
+ * Rust consumer. Pass overrides in `env`; they are merged over `process.env`.
+ *
+ * @param {import("./index").ReviewOptions} options
+ * @returns {Promise<import("./types").RunReviewOutput>}
+ */
+async function review(options = {}) {
+  const args = buildArgs(options);
+  const bin = options.binary || binaryPath();
+  const result = await run(bin, args, options);
+
+  if (result.code !== 0) {
+    const how = result.signal ? `killed by ${result.signal}` : `exited ${result.code}`;
+    const err = new Error(`kaniscope ${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) {
+    // Distinguish "the review failed" from "the wrapper and the binary disagree
+    // about the protocol". They need different fixes, and a bare SyntaxError
+    // pointing at position 0 reads as neither.
+    const err = new Error(
+      `kaniscope 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;
+  }
+}
+
+/** 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)}`);
+  return JSON.parse(result.stdout);
+}
+
+/** The engine version this package's binary was built from. */
+async function version(options = {}) {
+  const bin = options.binary || binaryPath();
+  const result = await run(bin, ["--version"], options);
+  if (result.code !== 0) throw new Error(`kaniscope --version failed\n${tail(result.stderr)}`);
+  return result.stdout.trim().replace(/^kaniscope\s+/, "");
+}
+
+module.exports = { review, schema, version, binaryPath };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "kaniscope",
+  "version": "0.26.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",
+    "pull-request",
+    "ai",
+    "github",
+    "gitlab",
+    "bitbucket"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nhatvu148/pr-review-core.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "kaniscope": "bin/kaniscope.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "types.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"
+  }
+}

package/types.d.ts

@@ -0,0 +1,48 @@
+// GENERATED by packaging/generate-types.mjs — do not edit.
+// Regenerate with: node packaging/generate-types.mjs
+
+/** Result of one review run (serialized as the HTTP/CLI response). */
+export interface RunReviewOutput {
+  commentUrl?: string | null;
+  findings: number;
+  /** The post-processed findings that were posted (after self-critique, confidence floor, sort, and cap). */
+  findingsDetail?: Finding[];
+  /** The inline comments exactly as they were built — path, line, and the rendered body, committable suggestion block and all. */
+  inlineDetail?: InlineComment[];
+  inlinePosted: number;
+  model: string;
+  posted: boolean;
+  pr: number;
+  provider: string;
+  recommendation: string;
+  repo: string;
+  summaryMarkdown: string;
+  usage?: Usage | null;
+}
+
+/** One review finding from the model. */
+export interface Finding {
+  body: string;
+  /** Model's confidence (0–100) that this is a real, actionable issue a senior reviewer would flag. */
+  confidence?: number | null;
+  file?: string;
+  line?: number | null;
+  severity?: string;
+  /** Replacement text for the anchored line, ready to render as a committable suggestion — or `None` whenever the fix is not expressible as an exact line replacement, which is most of the time. */
+  suggestion?: string | null;
+}
+
+/** One inline comment anchored to a file + line on the new side of the diff. */
+export interface InlineComment {
+  body: string;
+  line: number;
+  path: string;
+}
+
+/** Token accounting echoed back by OpenRouter. */
+export interface Usage {
+  completion_tokens?: number | null;
+  prompt_tokens?: number | null;
+  total_tokens?: number | null;
+}
+