@open-cr-agent/cli 0.1.2 → 0.3.0

package/dist/review/sarif.js

@@ -0,0 +1,153 @@
+import { coverageGaps, } from "@open-cr-agent/core";
+import { serializeOutput } from "@open-cr-agent/core/internal";
+// `--format sarif`: the review as a SARIF 2.1.0 log, for code scanning and
+// security dashboards. One rule per reviewer category, one result per
+// finding. Findings an earlier review reported in files this run did not
+// review again stay open, so they are results too, marked unchanged.
+// https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+const SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+const LEVEL = {
+    critical: "error",
+    warning: "warning",
+    suggestion: "note",
+};
+export function renderSarif(report, version) {
+    const open = [
+        ...(report.rereview?.unchanged ?? []),
+        ...(report.rereview?.notReproduced ?? []),
+        ...(report.rereview?.notRechecked ?? []),
+    ];
+    const categories = [
+        ...new Set([...report.findings.map((f) => f.category), ...(open.length > 0 ? [CARRIED] : [])]),
+    ].sort();
+    const index = new Map(categories.map((c, i) => [c, i]));
+    const { notReviewed } = coverageGaps(report);
+    const log = {
+        $schema: SCHEMA,
+        version: "2.1.0",
+        runs: [
+            {
+                automationDetails: { id: `ocra/${report.runId}` },
+                tool: {
+                    driver: {
+                        name: "ocra",
+                        informationUri: "https://ocra.majincheng.com",
+                        version,
+                        semanticVersion: version,
+                        rules: categories.map((id) => ({
+                            id,
+                            name: id,
+                            shortDescription: {
+                                text: id === CARRIED
+                                    ? CARRIED_DESCRIPTION
+                                    : `Findings of the ${id} reviewer or analyzer`,
+                            },
+                            properties: { tags: [id] },
+                        })),
+                    },
+                },
+                invocations: [
+                    {
+                        executionSuccessful: notReviewed === 0 && report.unverifiedCriticals === 0,
+                        toolExecutionNotifications: [
+                            ...(notReviewed > 0
+                                ? [
+                                    {
+                                        level: "warning",
+                                        message: { text: `${notReviewed} selected file(s) were not reviewed` },
+                                    },
+                                ]
+                                : []),
+                            ...report.warnings.map((w) => ({
+                                level: "warning",
+                                message: { text: plainText(w) },
+                            })),
+                        ],
+                    },
+                ],
+                results: [
+                    ...report.findings.map((f) => fromFinding(f, index)),
+                    ...open.map((f) => fromPrior(f, index)),
+                ],
+                properties: {
+                    verdict: report.verdict,
+                    tier: report.tier,
+                    baseSha: report.changeRequest.baseSha,
+                    headSha: report.changeRequest.headSha,
+                    notReviewed: report.coverage
+                        .filter((c) => c.status === "failed" || c.status === "unreviewed")
+                        .map((c) => c.path),
+                    unverifiedCriticals: report.unverifiedCriticals,
+                    costUsd: report.usage.costUsd,
+                },
+            },
+        ],
+    };
+    return `${serializeOutput(log)}\n`;
+}
+// Open findings an earlier review reported, carried over under their own
+// rule: their reviewer category is not recorded in the review state.
+const CARRIED = "ocra-carried-over";
+const CARRIED_DESCRIPTION = "Findings an earlier review reported that are still open in files this run did not review again";
+function fromFinding(f, index) {
+    const text = [f.title, f.body, ...(f.suggestion ? [`Suggestion: ${f.suggestion}`] : [])].join("\n\n");
+    return {
+        ruleId: f.category,
+        ruleIndex: index.get(f.category) ?? 0,
+        level: LEVEL[f.severity],
+        message: { text: plainText(text) },
+        locations: [location(f.file, f.lineRange)],
+        partialFingerprints: { "ocra/v1": f.fingerprint },
+        properties: {
+            reviewer: f.reviewer,
+            severity: f.severity,
+            verification: f.verification ?? "unchecked",
+            status: f.status === "unfixed" ? "unfixed" : "new",
+            ...(f.lowConfidence ? { lowConfidence: true } : {}),
+            task: f.provenance.task,
+            ...(f.provenance.model === undefined ? {} : { model: f.provenance.model }),
+        },
+    };
+}
+function fromPrior(f, index) {
+    return {
+        ruleId: CARRIED,
+        ruleIndex: index.get(CARRIED) ?? 0,
+        level: LEVEL[f.severity],
+        message: { text: plainText(f.title) },
+        // The review state keeps no lines for them, so they apply to the file.
+        locations: [location(f.file)],
+        partialFingerprints: { "ocra/v1": f.fingerprint },
+        baselineState: "unchanged",
+        properties: { severity: f.severity, verification: f.verification ?? "unchecked" },
+    };
+}
+function location(file, lines) {
+    return {
+        physicalLocation: {
+            // Each segment percent-encoded: a path may hold "#", "?" or spaces,
+            // which a URI would read as a fragment, a query or an error.
+            artifactLocation: {
+                uri: file.split("/").map(encodeURIComponent).join("/"),
+                uriBaseId: "%SRCROOT%",
+            },
+            ...(lines ? { region: { startLine: lines.start, endLine: lines.end } } : {}),
+        },
+    };
+}
+// SARIF viewers turn "[text](target)" in a message into a link (SARIF
+// 3.11.6), and some turn bare web addresses into links too. Text from a
+// reviewed change or a model must do neither: every backslash and bracket is
+// escaped, backslashes first so a planted "\[" cannot undo the escape, and
+// web addresses get a zero-width space in their scheme or after "www", as in
+// pull request comments (vcs-platform's safeMarkdown, which also handles
+// markup SARIF text does not have). Braces are doubled, since "{0}" is a
+// placeholder (SARIF 3.11.5); GitHub shows "{{" as "{".
+export function plainText(text) {
+    return text
+        .replace(/[\\[\]]/g, (c) => `\\${c}`)
+        .replace(/[{}]/g, (c) => c + c)
+        .replace(/\b(https?|ftp)(?=:\/\/)/gi, "$1​")
+        .replace(/\bwww(?=\.)/gi, "www​");
+}
+//# sourceMappingURL=sarif.js.map

package/dist/review/target.d.ts

@@ -1,5 +1,5 @@
-import type { OcraPlugin, PluginRegistry, VcsAdapter } from "@open-cr-agent/core";
-import type { PullRequestTarget, ReviewArgs } from "./args.js";
+import { type OcraPlugin, type PluginRegistry, type VcsAdapter } from "@open-cr-agent/core";
+import type { MergeRequestTarget, PullRequestTarget, ReviewArgs } from "./args.js";
 import { type CliConfig } from "./config.js";
 export interface ReviewTarget {
     config: CliConfig;
@@ -7,9 +7,11 @@ export interface ReviewTarget {
     createVcs(registry: PluginRegistry): VcsAdapter;
     readTrusted?: (path: string) => Promise<string | undefined>;
     publish: boolean;
+    publishesTo?: string;
 }
 type Env = Readonly<Record<string, string | undefined>>;
 export declare function localTarget(args: ReviewArgs, cwd: string, root: string, env: Env, warn: (message: string) => void, fetchImpl?: typeof fetch): Promise<ReviewTarget>;
-export declare function pullRequestTarget(pr: PullRequestTarget, cwd: string, root: string, env: Env, warn: (message: string) => void, fetchImpl?: typeof fetch, ignoreRepoConfig?: boolean): Promise<ReviewTarget>;
+export declare function pullRequestTarget(pr: PullRequestTarget, cwd: string, root: string, env: Env, warn: (message: string) => void, fetchImpl?: typeof fetch, ignoreRepoConfig?: boolean, configFile?: string): Promise<ReviewTarget>;
+export declare function mergeRequestTarget(mr: MergeRequestTarget, cwd: string, root: string, env: Env, warn: (message: string) => void, fetchImpl?: typeof fetch, ignoreRepoConfig?: boolean, configFile?: string): Promise<ReviewTarget>;
 export {};
 //# sourceMappingURL=target.d.ts.map

package/dist/review/target.js

@@ -1,16 +1,21 @@
-import { DEFAULT_BOT_LOGIN, GitHubApi } from "@open-cr-agent/vcs-github";
-import { ensureCommits, filesChangedSince, LocalGitAdapter } from "@open-cr-agent/vcs-local";
+import { dirname } from "node:path";
+import { OcraError, } from "@open-cr-agent/core";
+import { DEFAULT_BOT_LOGIN, GitHubApi } from "@open-cr-agent/vcs-github/internal";
+import { GitLabApi } from "@open-cr-agent/vcs-gitlab/internal";
+import { ensureCommits, filesChangedSince, LocalGitAdapter, } from "@open-cr-agent/vcs-local/internal";
 import { ConfigError, loadConfig } from "./config.js";
 import { loadExternalPlugins } from "./plugins.js";
 export async function localTarget(args, cwd, root, env, warn, fetchImpl) {
     const config = await loadConfig(root, env, {
         repository: !args.ignoreRepoConfig,
+        ...(args.configFile ? { file: args.configFile } : {}),
         warn,
         ...(fetchImpl ? { fetch: fetchImpl } : {}),
     });
     return {
         config,
-        plugins: await loadExternalPlugins(config.plugins, root),
+        // Plugins named by the user's own file are resolved from where it is.
+        plugins: await loadExternalPlugins(config.plugins, args.configFile ? dirname(args.configFile) : root),
         createVcs: (registry) => registry.createVcs("local", { cwd, target: args.target }),
         ...(args.ignoreRepoConfig ? { readTrusted: untrustedTreeReader(args, cwd) } : {}),
         publish: false,
@@ -28,10 +33,11 @@ function untrustedTreeReader(args, cwd) {
 }
 // The pull request's own files are untrusted: configuration, guidelines and
 // rules come from its base commit, and repository plugins never load.
-export async function pullRequestTarget(pr, cwd, root, env, warn, fetchImpl, ignoreRepoConfig = false) {
+export async function pullRequestTarget(pr, cwd, root, env, warn, fetchImpl, ignoreRepoConfig = false, configFile) {
     const token = env.GITHUB_TOKEN ?? env.GH_TOKEN;
-    if (!token)
-        throw new ConfigError("--pr needs a GitHub token in GITHUB_TOKEN or GH_TOKEN");
+    if (!token) {
+        throw new OcraError("CONFIG_CREDENTIALS_MISSING", "--pr needs a GitHub token in GITHUB_TOKEN or GH_TOKEN");
+    }
     const [owner = "", repo = ""] = (pr.repo ?? (await repositoryName(root, env))).split("/");
     const apiOptions = { token, ...(env.GITHUB_API_URL ? { baseUrl: env.GITHUB_API_URL } : {}) };
     const api = new GitHubApi({ owner, repo }, fetchImpl ? { ...apiOptions, fetch: fetchImpl } : apiOptions);
@@ -42,11 +48,12 @@ export async function pullRequestTarget(pr, cwd, root, env, warn, fetchImpl, ign
     const config = await loadConfig(root, env, {
         repository: !ignoreRepoConfig,
         read: readTrusted,
+        ...(configFile ? { file: configFile } : {}),
         warn,
         ...(fetchImpl ? { fetch: fetchImpl } : {}),
     });
     if (config.plugins.length > 0) {
-        warn("plugins in .ocra/config.json are not loaded for pull requests");
+        warn("plugins in the configuration are not loaded for pull requests");
     }
     const code = new LocalGitAdapter({
         cwd,
@@ -72,8 +79,119 @@ export async function pullRequestTarget(pr, cwd, root, env, warn, fetchImpl, ign
         }),
         readTrusted,
         publish: pr.publish,
+        publishesTo: "pull request",
     };
 }
+const GITLAB_API = "https://gitlab.com/api/v4";
+// Like a pull request: configuration, guidelines and rules come from the
+// target branch the merge request was based on, and repository plugins never
+// load. GitLab CI sets CI_API_V4_URL and CI_PROJECT_ID; GITLAB_TOKEN must be
+// a token that may write notes, which CI_JOB_TOKEN may not.
+export async function mergeRequestTarget(mr, cwd, root, env, warn, fetchImpl, ignoreRepoConfig = false, configFile) {
+    const token = env.GITLAB_TOKEN;
+    if (!token) {
+        throw new OcraError("CONFIG_CREDENTIALS_MISSING", "--mr needs a GitLab token in GITLAB_TOKEN: a project access token with the api scope and the Developer role (CI_JOB_TOKEN cannot post comments)");
+    }
+    const origin = await originUrl(root);
+    const project = mr.project ?? env.CI_PROJECT_ID ?? gitlabProject(origin);
+    const apiUrl = gitlabApi(env.CI_API_V4_URL, remoteHost(origin), warn);
+    const api = new GitLabApi(project, {
+        token,
+        baseUrl: apiUrl,
+        ...(fetchImpl ? { fetch: fetchImpl } : {}),
+    });
+    const merge = await api.getMergeRequest(mr.iid);
+    const refs = merge.diff_refs;
+    if (!refs) {
+        throw new OcraError("VCS_NOT_READY", `merge request !${mr.iid} has no diff yet; try again shortly`);
+    }
+    await ensureCommits(root, [refs.start_sha, refs.head_sha], [`refs/merge-requests/${mr.iid}/head`]);
+    const base = new LocalGitAdapter({ cwd, target: { mode: "commit", commit: refs.start_sha } });
+    const readTrusted = (path) => base.readFile(path);
+    const config = await loadConfig(root, env, {
+        repository: !ignoreRepoConfig,
+        read: readTrusted,
+        ...(configFile ? { file: configFile } : {}),
+        warn,
+        ...(fetchImpl ? { fetch: fetchImpl } : {}),
+    });
+    if (config.plugins.length > 0) {
+        warn("plugins in the configuration are not loaded for merge requests");
+    }
+    const code = new LocalGitAdapter({
+        cwd,
+        target: { mode: "range", from: refs.start_sha, to: refs.head_sha },
+    });
+    return {
+        config,
+        plugins: [],
+        createVcs: (registry) => registry.createVcs("gitlab", {
+            project: /^\d+$/.test(project) ? Number(project) : project,
+            iid: mr.iid,
+            token,
+            apiUrl,
+            code,
+            snapshot: merge,
+            history: {
+                filesChangedSince: (from, to) => filesChangedSince(root, from, to),
+            },
+            ...(fetchImpl ? { fetch: fetchImpl } : {}),
+        }),
+        readTrusted,
+        publish: mr.publish,
+        publishesTo: "merge request",
+    };
+}
+function originUrl(root) {
+    return new LocalGitAdapter({ cwd: root, target: { mode: "workspace" } })
+        .remoteUrl("origin")
+        .catch(() => undefined);
+}
+// Where GITLAB_TOKEN goes: to CI_API_V4_URL, which GitLab CI sets, or else
+// to gitlab.com, but only when origin is there too or is no remote host. A
+// token for a self-managed instance must not travel to gitlab.com because
+// the address was left out.
+function gitlabApi(configured, origin, warn) {
+    if (configured) {
+        const api = remoteHost(configured);
+        if (api && origin && site(api) !== site(origin)) {
+            warn(`CI_API_V4_URL is on ${api} but origin is on ${origin}; GITLAB_TOKEN goes to ${api}`);
+        }
+        return configured;
+    }
+    if (origin && site(origin) !== "gitlab.com") {
+        throw new ConfigError(`origin is on ${origin}, not gitlab.com: set CI_API_V4_URL to its API, such as https://${origin}/api/v4, so that GITLAB_TOKEN goes only there`);
+    }
+    return GITLAB_API;
+}
+// GitLab.com answers on subdomains too, such as altssh.gitlab.com for SSH.
+function site(host) {
+    return host === "gitlab.com" || host.endsWith(".gitlab.com") ? "gitlab.com" : host;
+}
+// The host of https://host/…, ssh://user@host:port/… or user@host:path; none
+// for a local path, including C:\ on Windows.
+function remoteHost(url) {
+    if (!url)
+        return undefined;
+    if (/^[\w+.-]+:\/\//.test(url)) {
+        try {
+            const parsed = new URL(url);
+            return parsed.protocol === "file:" ? undefined : parsed.hostname.toLowerCase() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return /^(?:[^@\s/]+@)?([^:/\s\\]+):(?![\\/])/.exec(url)?.[1]?.toLowerCase();
+}
+// The project behind the origin remote: any host, since GitLab runs on many.
+function gitlabProject(url) {
+    const match = url && /^(?:[\w+.-]+:\/\/[^/]+\/|[^@\s]+@[^:]+:)(.+?)(?:\.git)?\/?$/.exec(url);
+    if (!match?.[1]) {
+        throw new ConfigError("Cannot tell which GitLab project this is; pass --project <id|path>");
+    }
+    return match[1];
+}
 async function repositoryName(root, env) {
     if (env.GITHUB_REPOSITORY)
         return env.GITHUB_REPOSITORY;

package/dist/review/terminal.js

@@ -1,4 +1,4 @@
-import { isUnsafeCodePoint } from "@open-cr-agent/core";
+import { isUnsafeCodePoint } from "@open-cr-agent/core/internal";
 // Findings, commit messages and errors can carry text a diff planted; none of
 // it may drive the user's terminal. C0 and C1 controls (ANSI and OSC escapes
 // start with ESC or a C1 code) except tab and newline, carriage returns, and

package/dist/run.d.ts

@@ -1,6 +1,5 @@
 import { type ReviewDeps } from "./review/command.js";
 import type { Output } from "./review/progress.js";
-export declare const VERSION: string;
 export declare function defaultDeps(): ReviewDeps;
 export declare function run(argv: string[], out: Output, err: Output, deps?: ReviewDeps): Promise<number>;
 //# sourceMappingURL=run.d.ts.map

package/dist/run.js

@@ -1,18 +1,20 @@
 import { writeFile } from "node:fs/promises";
-import { createRequire } from "node:module";
 import { parseArgs } from "node:util";
-import { errorMessage } from "@open-cr-agent/core";
+import { isOcraError } from "@open-cr-agent/core";
+import { errorMessage } from "@open-cr-agent/core/internal";
 import { memoryCommand } from "./memory.js";
+import { metricsCommand } from "./metrics.js";
 import { parseReviewArgs, REVIEW_USAGE, UsageError } from "./review/args.js";
 import { BUILTIN_PLUGINS, EXIT, reviewCommand } from "./review/command.js";
+import { BUILTIN_RUNTIMES } from "./review/runtimes.js";
 import { forTerminal } from "./review/terminal.js";
-// src/ and dist/ both sit one level below the package root.
-export const VERSION = createRequire(import.meta.url)("../package.json").version;
+import { VERSION } from "./version.js";
 const USAGE = `Usage: ocra <command> [options]
 
 Commands:
   review      Review code changes (run "ocra review --help" for options)
   memory      Remember findings the team accepts (run "ocra memory --help")
+  metrics     Counts over past reviews: runs, cost, findings, per reviewer (run "ocra metrics --help")
 
 Options:
   -h, --help     Show help
@@ -23,6 +25,7 @@ export function defaultDeps() {
         cwd: process.cwd(),
         env: process.env,
         builtinPlugins: BUILTIN_PLUGINS,
+        runtimes: BUILTIN_RUNTIMES,
         writeFile: (path, content) => writeFile(path, content, "utf8"),
         now: Date.now,
         heartbeatMs: 30_000,
@@ -47,12 +50,14 @@ export async function run(argv, out, err, deps = defaultDeps()) {
     const [command, ...rest] = argv;
     if (command === "review")
         return review(rest, out, err, deps);
-    if (command === "memory") {
+    if (command === "memory" || command === "metrics") {
         try {
-            return await memoryCommand(rest, out, deps.cwd);
+            return command === "memory"
+                ? await memoryCommand(rest, out, deps.cwd)
+                : await metricsCommand(rest, out, deps.cwd);
         }
         catch (error) {
-            err.write(`ocra: ${forTerminal(errorMessage(error))}\n`);
+            err.write(failure(error));
             return EXIT.error;
         }
     }
@@ -93,9 +98,14 @@ async function review(argv, out, err, deps) {
             err.write(`${error.message}\n\n${REVIEW_USAGE}`);
         }
         else {
-            err.write(`ocra: ${forTerminal(errorMessage(error))}\n`);
+            err.write(failure(error));
         }
         return EXIT.error;
     }
 }
+// The code is what a script may match on; the message is for people.
+function failure(error) {
+    const code = isOcraError(error) ? ` [${error.code}]` : "";
+    return `ocra${code}: ${forTerminal(errorMessage(error))}\n`;
+}
 //# sourceMappingURL=run.js.map

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from "node:module";
+// src/ and dist/ both sit one level below the package root.
+export const VERSION = createRequire(import.meta.url)("../package.json").version;
+//# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-cr-agent/cli",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "ocra: open-source multi-agent code review for local changes and GitHub pull requests",
   "keywords": [
     "code-review",
@@ -23,9 +23,11 @@
   "type": "module",
   "exports": {
     ".": {
+      "@open-cr-agent/source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "ocra": "./dist/main.js"
@@ -35,12 +37,16 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@open-cr-agent/core": "0.1.2",
-    "@open-cr-agent/runtime-opencode": "0.1.2",
-    "@open-cr-agent/vcs-github": "0.1.2",
-    "@open-cr-agent/vcs-local": "0.1.2",
+    "@open-cr-agent/core": "0.3.0",
+    "@open-cr-agent/runtime-direct": "0.3.0",
+    "@open-cr-agent/vcs-github": "0.3.0",
+    "@open-cr-agent/vcs-gitlab": "0.3.0",
+    "@open-cr-agent/vcs-local": "0.3.0",
     "zod": "^4.6.5"
   },
+  "optionalDependencies": {
+    "@open-cr-agent/runtime-opencode": "0.3.0"
+  },
   "publishConfig": {
     "access": "public"
   }