co-maintainer 0.4.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Murat Kirazkaya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# co-maintainer
+
+`co-maintainer` analyzes a GitHub repository and writes repository-specific
+`SKILL.md` guidance that helps developers contribute changes more reliably.
+
+It collects current code and workflows, selected pull requests and diffs, and
+default-branch commits. A low-cost model extracts evidence-bound observations; a
+higher-reasoning model turns them into concise contribution guidance for
+implementation, testing, review, and release decisions.
+
+## Installation
+
+```sh
+npm install -g co-maintainer
+```
+
+Requires Node.js 24 or newer.
+
+> **Migrating from JSR:** co-maintainer used to be published as
+> `jsr:@murat/co-maintainer` for Deno. JSR is deprecated and no longer updated;
+> install the npm package instead.
+
+On a Linux VPS, persist npm's global bin directory if the installer prints a
+PATH notice:
+
+```sh
+grep -qxF 'export PATH="$(npm prefix -g)/bin:$PATH"' ~/.bashrc || printf '\nexport PATH="$(npm prefix -g)/bin:$PATH"\n' >> ~/.bashrc
+source ~/.bashrc
+```
+
+## Usage
+
+```sh
+co-maintainer probe owner/repo --auth=gh
+```
+
+```sh
+co-maintainer probe owner/repo --auth=gh
+
+co-maintainer init owner/repo --auth=gh --ai=openrouter --token=... \
+  --low-model=openai/gpt-oss-120b \
+  --high-model=openai/gpt-5.6-luna \
+  --include-codebase --include-pull-requests \
+  --include-pull-request-changes --include-commit-history \
+  --include-how-repo-works
+
+co-maintainer review owner/repo 123 --improve-matrix=2 --debug
+
+co-maintainer review              # local branch (staged, unstaged, untracked)
+co-maintainer review --json       # machine-readable stdout; logs on stderr
+
+npm run review-local-e2e        # fake-AI local loop (developers, from repo root)
+```
+
+Documentation: [Getting started](docs/getting-started.html) (install → first
+review), [full docs site](docs/index.html), sources in [`docs/md/`](docs/md/).
+
+Use `co-maintainer help`, `co-maintainer -h`, or `co-maintainer --help` for the
+full CLI help.
+
+## Compared to other tools
+
+co-maintainer is a newly tool so not compared a lot of other tools. But did
+benchmarks with [OCR](https://open-codereview.ai/). Although I cannot offer any
+guarantees because I am working with very small datasets, but it shows promise.
+
+In core_v2 benchmarks:
+
+- **2-3x better results** than OCR
+- **2-8x faster** than OCR
+- **70-200x fewer tokens** than OCR
+- **60-270x cheaper** than
+
+```mermaid
+xychart-beta
+    title "Monthly PR Review Cost by Developer Count"
+    x-axis [1, 5, 10, 20, 30, 40, 50, 60, 70, 80, 100]
+    y-axis "Monthly Cost ($)" 0 --> 13000
+    line "OCR" [129.6, 648, 1296, 2592, 3888, 5184, 6480, 7776, 9072, 10368, 12960]
+    line "co-maintainer" [2, 10, 20, 40, 60, 80, 100, 120, 140, 160, 200]
+```
+
+_Calculated based on co-maintainer's `core_v2` benchmark, which reports co-maintainer as 65x cheaper per review than OCR ($0.025/review vs. $1.62/review). Assumes 80 PR reviews per developer per month (40 PRs merged, avg. ~2 reviews each)._
+
+## Benchmarks
+
+We recommend consider core_v3 benchmark results because of more suits for
+co-maintainer use cases. It is a much more meaningful metric than other
+benchmarks. core_v3 is co-maintainer only benchmark.
+
+Unlike the OCR comparison above (real human review comments as gold, see
+`benchmark/swe-prbench`), `bench core v3` scores against deliberately seeded,
+hand-verified defects in a dedicated target repo, half of the PRs kept as
+defect-free controls so precision is measurable too, not just recall. Full
+breakdown, per-PR results, and methodology:
+[`benchmark/core_v3/README.md`](benchmark/core_v3/README.md).
+
+| metric        | value                         |
+| ------------- | ----------------------------- |
+| PRs reviewed  | 30 (14 defective, 16 control) |
+| F1            | 0.500                         |
+| Precision     | 0.353                         |
+| Recall        | 0.857                         |
+| Avg cost / PR | $0.0045                       |
+| Avg time / PR | 28.9s                         |

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from "./src/cli/main.js";
+try {
+    await run(process.argv.slice(2));
+}
+catch (error) {
+    console.error(`[error] ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+}

package/dist/mod.d.ts

@@ -0,0 +1,4 @@
+import { run } from "./src/cli/main.ts";
+export { run };
+export type { AiProvider, AiRequest, AiResponse, GitHubClient, Json, Options, } from "./src/types.ts";
+export type { Fact, PullRequest, Source, State, } from "./src/knowledge/types.ts";

package/dist/mod.js

@@ -0,0 +1,2 @@
+import { run } from "./src/cli/main.js";
+export { run };

package/dist/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "co-maintainer",
+    "version": "0.4.0-beta.1",
+    "description": "Analyzes a GitHub repository and writes repository-specific contribution guidance.",
+    "license": "MIT",
+    "bin": {
+        "co-maintainer": "./dist/main.js"
+    },
+    "files": [
+        "dist/",
+        "LICENSE",
+        "README.md"
+    ],
+    "type": "module",
+    "exports": {
+        ".": "./dist/mod.js"
+    },
+    "scripts": {
+        "build": "npm run assets:embed && tsc -p tsconfig.build.json",
+        "assets:embed": "node scripts/embed_assets.mjs",
+        "prepack": "npm run build",
+        "test": "node --test \"src/**/*.test.ts\" \"benchmark/**/*.test.ts\"",
+        "check": "tsc --noEmit",
+        "lint": "oxlint",
+        "fmt": "oxfmt --write .",
+        "fmt:check": "oxfmt --check .",
+        "dev": "node --watch main.ts",
+        "probe": "node main.ts probe",
+        "init": "node main.ts init",
+        "remake": "node main.ts remake",
+        "review": "node main.ts review",
+        "serve": "node main.ts serve",
+        "bench": "node benchmark/core_v2/run.ts",
+        "bench-rereview": "node benchmark/core_v2/run_rereview.ts",
+        "bench-swe-prbench": "node benchmark/swe-prbench/run.ts",
+        "bench-core-v3": "node benchmark/core_v3/run.ts",
+        "swe-prbench-prepare": "node benchmark/swe-prbench/prepare_dataset.ts",
+        "e2e": "node scripts/e2e.ts",
+        "review-local-e2e": "node scripts/review_local_e2e.ts",
+        "docs:build": "node scripts/build_docs.ts"
+    },
+    "dependencies": {
+        "marked": "^15.0.7"
+    },
+    "devDependencies": {
+        "@types/node": "^24.0.0",
+        "oxfmt": "^0.68.0",
+        "oxlint": "^1.83.0",
+        "typescript": "^5.7.0"
+    },
+    "engines": {
+        "node": ">=24"
+    }
+}

package/dist/src/ai/batch.d.ts

@@ -0,0 +1,16 @@
+import type { AiProvider, AiRequest, AiResponse } from "../types.ts";
+type UsageSink = (job: string, response: AiResponse) => Promise<void>;
+export declare class AiBatch {
+    private records;
+    private loaded;
+    private saveChain;
+    private readonly provider;
+    private readonly repo;
+    private readonly concurrency;
+    private readonly profile;
+    constructor(provider: AiProvider, repo: string, concurrency: number, profile: string);
+    run(requests: AiRequest[], usage?: UsageSink): Promise<(AiResponse | undefined)[]>;
+    private load;
+    private persist;
+}
+export {};

package/dist/src/ai/batch.js

@@ -0,0 +1,117 @@
+import { cacheGet, cacheSet } from "../store/cache_db.js";
+import { isNotFound, readTextFile } from "../util/runtime.js";
+async function digest(value) {
+    const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+    return [...new Uint8Array(bytes)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+export class AiBatch {
+    records = {};
+    loaded = false;
+    saveChain = Promise.resolve();
+    provider;
+    repo;
+    concurrency;
+    profile;
+    constructor(provider, repo, concurrency, profile) {
+        this.provider = provider;
+        this.repo = repo;
+        this.concurrency = concurrency;
+        this.profile = profile;
+    }
+    async run(requests, usage) {
+        await this.load();
+        const results = new Array(requests.length);
+        const pending = [];
+        for (let index = 0; index < requests.length; index++) {
+            const request = requests[index];
+            const id = await digest(JSON.stringify({
+                profile: this.profile,
+                job: request.job,
+                system: request.system,
+                prompt: request.prompt,
+                maxTokens: request.maxTokens,
+            }));
+            const cached = this.records[id];
+            if (cached?.status === "done" && cached.response) {
+                results[index] = cached.response;
+                console.log(`[ai] cache hit ${request.job} ${id.slice(0, 8)}`);
+            }
+            else if (cached?.status === "quarantine") {
+                console.log(`[ai] quarantined job skipped: ${request.job} ${id.slice(0, 8)}`);
+            }
+            else {
+                pending.push({ index, id, request });
+            }
+        }
+        let cursor = 0;
+        console.log(`[ai] queue ${requests.length} jobs · ${pending.length} pending · concurrency ${this.concurrency}`);
+        const worker = async () => {
+            while (cursor < pending.length) {
+                const item = pending[cursor++];
+                const startedAt = Date.now();
+                console.log(`[ai] start ${item.request.job} ${item.id.slice(0, 8)}`);
+                const heartbeat = setInterval(() => {
+                    const seconds = Math.round((Date.now() - startedAt) / 1000);
+                    console.log(`[ai] still running ${item.request.job} ${item.id.slice(0, 8)} · ${seconds}s`);
+                }, 15_000);
+                try {
+                    const response = await this.provider.complete(item.request);
+                    this.records[item.id] = {
+                        status: "done",
+                        response,
+                        updatedAt: new Date().toISOString(),
+                    };
+                    results[item.index] = response;
+                    await this.persist();
+                    if (usage)
+                        await usage(item.request.job, response);
+                    console.log(`[ai] done ${item.request.job} ${item.id.slice(0, 8)} · ${Math.round((Date.now() - startedAt) / 1000)}s`);
+                }
+                catch (error) {
+                    this.records[item.id] = {
+                        status: "quarantine",
+                        error: String(error),
+                        updatedAt: new Date().toISOString(),
+                    };
+                    await this.persist();
+                    console.log(`[ai] quarantined ${item.request.job} ${item.id.slice(0, 8)}: ${String(error)}`);
+                }
+                finally {
+                    clearInterval(heartbeat);
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(this.concurrency, Math.max(1, pending.length)) }, () => worker()));
+        await this.saveChain;
+        return results;
+    }
+    async load() {
+        if (this.loaded)
+            return;
+        const key = `${this.repo}:${this.profile}`;
+        const cached = await cacheGet("ai-jobs", key);
+        if (cached) {
+            this.records = JSON.parse(cached);
+            this.loaded = true;
+            return;
+        }
+        try {
+            this.records = JSON.parse(await readTextFile(`.cache/${this.repo}/ai-jobs.json`));
+            await cacheSet("ai-jobs", key, JSON.stringify(this.records));
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                throw error;
+        }
+        this.loaded = true;
+    }
+    async persist() {
+        const snapshot = JSON.stringify(this.records, null, 2) + "\n";
+        this.saveChain = this.saveChain.then(async () => {
+            await cacheSet("ai-jobs", `${this.repo}:${this.profile}`, snapshot);
+        });
+        await this.saveChain;
+    }
+}

package/dist/src/ai/fake.d.ts

@@ -0,0 +1,7 @@
+import type { AiProvider, AiRequest, AiResponse } from "../types.ts";
+export declare const FAKE_REVIEW_MARKDOWN = "## Findings\n\n### [P2 \u00B7 non-blocking] `src/app.ts` \u2014 `helper()`\nLocation: `src/app.ts:4`\n\nThe helper ignores its argument, so the new behavior is never applied.\n\nThe helper accepts an argument but returns the same result without reading it.\n\nIf you'd like me to explain it in more detail, please ask.\n";
+export declare class FakeAiProvider implements AiProvider {
+    private readonly text;
+    constructor(text?: string);
+    complete(_request: AiRequest): Promise<AiResponse>;
+}

package/dist/src/ai/fake.js

@@ -0,0 +1,40 @@
+import { getEnv, readTextFileSync } from "../util/runtime.js";
+export const FAKE_REVIEW_MARKDOWN = `## Findings
+
+### [P2 · non-blocking] \`src/app.ts\` — \`helper()\`
+Location: \`src/app.ts:4\`
+
+The helper ignores its argument, so the new behavior is never applied.
+
+The helper accepts an argument but returns the same result without reading it.
+
+If you'd like me to explain it in more detail, please ask.
+`;
+function fakeReviewText() {
+    const path = getEnv("CM_FAKE_REVIEW_FILE");
+    if (path) {
+        try {
+            return readTextFileSync(path);
+        }
+        catch {
+            // fall through
+        }
+    }
+    return FAKE_REVIEW_MARKDOWN;
+}
+export class FakeAiProvider {
+    text;
+    constructor(text = fakeReviewText()) {
+        this.text = text;
+    }
+    complete(_request) {
+        return Promise.resolve({
+            text: this.text,
+            tokensIn: 10,
+            tokensOut: 20,
+            cost: 0,
+            model: "fake",
+            provider: "openrouter",
+        });
+    }
+}

package/dist/src/ai/hetzner.d.ts

@@ -0,0 +1,16 @@
+import type { AiProvider, AiRequest, AiResponse } from "../types.ts";
+declare const sleep: (milliseconds: number) => Promise<void>;
+export declare class HetznerProvider implements AiProvider {
+    readonly supportsTools = false;
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly model;
+    private readonly sleeper;
+    private nextRequest;
+    private spacing;
+    constructor(apiKey: string, model: string, endpoint?: string, sleeper?: typeof sleep);
+    complete(request: AiRequest): Promise<AiResponse>;
+    private waitForQuota;
+    private jitter;
+}
+export {};

package/dist/src/ai/hetzner.js

@@ -0,0 +1,69 @@
+import { chatBody, parseChatResponse } from "./provider.js";
+const sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+export class HetznerProvider {
+    supportsTools = false;
+    endpoint;
+    apiKey;
+    model;
+    sleeper;
+    nextRequest = 0;
+    spacing = 8_000;
+    constructor(apiKey, model, endpoint = "https://inference.hetzner.com/api/v1/chat/completions", sleeper = sleep) {
+        if (!apiKey)
+            throw new Error("Hetzner requires HETZNER_API_KEY");
+        if (!model)
+            throw new Error("Hetzner requires HETZNER_MODEL");
+        this.apiKey = apiKey;
+        this.model = model;
+        this.sleeper = sleeper;
+        this.endpoint = endpoint;
+    }
+    async complete(request) {
+        let attempt = 0;
+        for (;;) {
+            attempt++;
+            await this.waitForQuota();
+            const response = await fetch(this.endpoint, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(chatBody(this.model, request)),
+            });
+            this.nextRequest = Date.now() + this.spacing;
+            if (response.ok) {
+                this.spacing = Math.max(8_000, this.spacing * 0.9);
+                return parseChatResponse((await response.json()), "hetzner", this.model);
+            }
+            if ([401, 403, 404].includes(response.status)) {
+                throw new Error(`Hetzner fatal ${response.status}: ${await response.text()}`);
+            }
+            if (response.status === 429) {
+                this.spacing = Math.min(180_000, this.spacing * 1.5);
+                const wait = this.jitter(this.spacing);
+                console.log(`[ai] hetzner 429 on attempt ${attempt}; retrying in ${Math.round(wait / 1000)}s`);
+                await this.sleeper(wait);
+                continue;
+            }
+            if (response.status >= 500 || response.status === 408) {
+                const wait = this.jitter(Math.min(180_000, this.spacing * 1.5));
+                console.log(`[ai] hetzner ${response.status} on attempt ${attempt}; retrying in ${Math.round(wait / 1000)}s`);
+                await this.sleeper(wait);
+                continue;
+            }
+            throw new Error(`Hetzner ${response.status}: ${await response.text()}`);
+        }
+    }
+    async waitForQuota() {
+        const wait = this.nextRequest - Date.now();
+        if (wait > 0) {
+            const jittered = this.jitter(wait);
+            console.log(`[ai] hetzner quota spacing; waiting ${Math.round(jittered / 1000)}s`);
+            await this.sleeper(jittered);
+        }
+    }
+    jitter(milliseconds) {
+        return Math.max(250, Math.round(milliseconds * (0.8 + Math.random() * 0.4)));
+    }
+}

package/dist/src/ai/mermaid.d.ts

@@ -0,0 +1,27 @@
+import type { Json } from "../types.ts";
+export declare const MERMAID_TYPES: readonly ["flowchart", "swimlane-beta", "sequenceDiagram", "classDiagram", "stateDiagram-v2", "erDiagram", "requirementDiagram", "usecase-beta", "C4Context", "zenuml", "packet", "architecture-beta", "eventmodeling", "treeView-beta"];
+export type MermaidType = (typeof MERMAID_TYPES)[number];
+export declare const MERMAID_TOOL: {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "read-mermaid-syntaxes";
+        readonly description: "Read the LLM-friendly syntax, configuration, and examples for selected Mermaid diagram types.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly tools: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly enum: readonly ["flowchart", "swimlane-beta", "sequenceDiagram", "classDiagram", "stateDiagram-v2", "erDiagram", "requirementDiagram", "usecase-beta", "C4Context", "zenuml", "packet", "architecture-beta", "eventmodeling", "treeView-beta"];
+                    };
+                    readonly uniqueItems: true;
+                    readonly maxItems: 5;
+                };
+            };
+            readonly required: readonly ["tools"];
+            readonly additionalProperties: false;
+        };
+    };
+};
+export declare function readMermaidSyntaxes(args: Json, maxTools: number): string;