@open-cr-agent/cli 0.2.0 → 0.4.0

package/dist/review/config.js

@@ -1,9 +1,13 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { RISK_TIERS, } from "@open-cr-agent/core";
+import { OcraError, } from "@open-cr-agent/core";
+import { AGENT_ROLES, EFFORT_LEVELS, RISK_TIERS } from "@open-cr-agent/core/internal";
 import { z } from "zod";
 import { fetchRemoteConfig, mergeConfig } from "./remote-config.js";
 export const CONFIG_PATH = ".ocra/config.json";
+// How much a model reasons before answering (ADR-0025); unset leaves the
+// provider's default.
+const effort = z.enum(EFFORT_LEVELS);
 const modelChain = z
     .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
     .transform((value) => (typeof value === "string" ? [value] : value));
@@ -39,15 +43,27 @@ const providerSchema = z
     models: z
         .record(z.string().regex(/^[\w./:@-]{1,200}$/), z.object({ input: price, output: price, cachedInput: price.optional() }).strict())
         .refine((models) => Object.keys(models).length > 0, "must list at least one model"),
+    // How the endpoint takes a reasoning effort: "openai" sends
+    // reasoning_effort (the default), "openrouter" sends reasoning.effort.
+    effort: z.enum(["openai", "openrouter"]).optional(),
 })
     .strict();
+// The runtimes ocra ships; a plugin may register another name, so the
+// schema lists these for editors and still accepts any other string.
+const BUILTIN_RUNTIMES = ["opencode", "direct"];
 const configSchema = z
     .object({
+    $schema: z.string().optional(),
     models: z
         .object({ top: modelChain, standard: modelChain, light: modelChain })
         .partial()
         .strict()
         .default({}),
+    effort: z
+        .object({ top: effort, standard: effort, light: effort })
+        .partial()
+        .strict()
+        .default({}),
     concurrency: z.number().int().min(1).max(32).optional(),
     taskTimeoutMinutes: z.number().positive().optional(),
     runTimeoutMinutes: z.number().positive().optional(),
@@ -55,6 +71,20 @@ const configSchema = z
     judge: z.boolean().optional(),
     maxCostUsd: z.number().positive().optional(),
     maxTasks: z.number().int().min(1).max(1_000).optional(),
+    // Unset: each provider's default. A seed makes sampling repeatable only
+    // where the provider supports it.
+    sampling: z
+        .object({
+        temperature: z.number().min(0).max(2),
+        seed: z
+            .number()
+            .int()
+            .min(0)
+            .max(2 ** 31 - 1),
+    })
+        .partial()
+        .strict()
+        .optional(),
     github: z
         .object({ requestChanges: z.boolean(), botLogin: z.string().min(1) })
         .partial()
@@ -62,36 +92,65 @@ const configSchema = z
         .default({}),
     include: z.array(z.string().min(1)).default([]),
     exclude: z.array(z.string().min(1)).default([]),
-    runtime: z.string().min(1).default("opencode"),
+    runtime: z.enum(BUILTIN_RUNTIMES).or(z.string().min(1)).default("opencode"),
     plugins: z.array(z.string().min(1)).default([]),
     reviewers: z
         .record(z.string(), z
         .object({
         enabled: z.boolean(),
         minTier: z.enum(RISK_TIERS),
+        effort,
     })
         .partial()
         .strict())
         .default({}),
+    roles: z
+        .partialRecord(z.enum(AGENT_ROLES), z.object({ effort }).partial().strict())
+        .default({}),
     pluginSettings: z.record(z.string(), z.unknown()).default({}),
     providers: z.record(z.string().regex(/^[a-z][a-z0-9-]{0,39}$/), providerSchema).default({}),
     extends: z.string().min(1).optional(),
 })
     .strict();
+export const CONFIG_SCHEMA_ID = "https://ocra.majincheng.com/schema/config.v1.json";
+// JSON Schema (draft 2020-12) of .ocra/config.json, for editors: what a
+// file may say, so defaults are optional and model chains take either form.
+export function configJsonSchema() {
+    const generated = z.toJSONSchema(configSchema, { target: "draft-2020-12", io: "input" });
+    const { $schema, ...rest } = generated;
+    return {
+        $schema,
+        $id: CONFIG_SCHEMA_ID,
+        title: "ocra configuration",
+        description: "The .ocra/config.json file of a repository, or a file passed with --config. Unknown keys are rejected.",
+        ...rest,
+    };
+}
 const MODEL_ENV = {
     top: "OCRA_MODEL_TOP",
     standard: "OCRA_MODEL_STANDARD",
     light: "OCRA_MODEL_LIGHT",
 };
-export class ConfigError extends Error {
+const EFFORT_ENV = {
+    top: "OCRA_EFFORT_TOP",
+    standard: "OCRA_EFFORT_STANDARD",
+    light: "OCRA_EFFORT_LIGHT",
+};
+export class ConfigError extends OcraError {
+    constructor(message, options) {
+        super("CONFIG_INVALID", message, options);
+        this.name = "ConfigError";
+    }
 }
 // Without the repository's file, only defaults and environment variables
 // apply: that file can name plugins, and plugins run code.
 export async function loadConfig(root, env, options = { repository: true }) {
     const read = options.read ?? ((path) => readConfigFromDisk(root, path));
-    const { config: parsed, rules } = options.repository
-        ? await readConfigFile(read, options)
-        : { config: configSchema.parse({}), rules: [] };
+    const { config: parsed, rules } = options.file
+        ? await readConfigFile(ownFile(options.file), options, options.file)
+        : options.repository
+            ? await readConfigFile(read, options, CONFIG_PATH)
+            : { config: configSchema.parse({}), rules: [] };
     const models = {};
     for (const [tier, chain] of Object.entries(parsed.models)) {
         if (chain)
@@ -105,10 +164,29 @@ export async function loadConfig(root, env, options = { repository: true }) {
         if (chain.length > 0)
             models[tier] = chain;
     }
+    const efforts = {
+        ...parsed.effort,
+    };
+    for (const [tier, name] of Object.entries(EFFORT_ENV)) {
+        const value = env[name]?.trim();
+        if (!value)
+            continue;
+        const level = effort.safeParse(value);
+        if (!level.success) {
+            throw new ConfigError(`${name} must be one of ${EFFORT_LEVELS.join(", ")}`);
+        }
+        efforts[tier] = level.data;
+    }
     for (const model of unpriced(parsed.providers, models)) {
         options.warn?.(`${model} has a price of 0: reported cost and --max-cost-usd do not count its tokens`);
     }
-    return { ...parsed, models, providers: toProviders(parsed.providers), rules };
+    return {
+        ...parsed,
+        models,
+        effort: efforts,
+        providers: toProviders(parsed.providers),
+        rules,
+    };
 }
 function toProviders(declared) {
     return Object.fromEntries(Object.entries(declared).map(([id, p]) => [
@@ -116,6 +194,7 @@ function toProviders(declared) {
         {
             baseUrl: p.baseUrl,
             ...(p.apiKeyEnv ? { apiKeyEnv: p.apiKeyEnv } : {}),
+            ...(p.effort ? { effort: p.effort } : {}),
             models: Object.fromEntries(Object.entries(p.models).map(([model, price]) => [
                 model,
                 {
@@ -139,6 +218,16 @@ function unpriced(providers, models) {
 // The user's own checkout, read like any local file (links followed): unlike
 // the review's reads, which never follow links (vcs-local), this is trusted
 // configuration, and --no-repo-config skips it for code that is not.
+function ownFile(file) {
+    return async () => {
+        try {
+            return await readFile(file, "utf8");
+        }
+        catch (error) {
+            throw new ConfigError(`cannot read ${file}: ${error.message}`, { cause: error });
+        }
+    };
+}
 async function readConfigFromDisk(root, path) {
     try {
         return await readFile(join(root, path), "utf8");
@@ -149,7 +238,7 @@ async function readConfigFromDisk(root, path) {
         throw error;
     }
 }
-async function readConfigFile(read, options) {
+async function readConfigFile(read, options, label) {
     const text = await read(CONFIG_PATH);
     if (text === undefined)
         return { config: configSchema.parse({}), rules: [] };
@@ -158,11 +247,13 @@ async function readConfigFile(read, options) {
         data = JSON.parse(text);
     }
     catch (error) {
-        throw new ConfigError(`${CONFIG_PATH} is not valid JSON: ${error.message}`);
+        throw new ConfigError(`${label} is not valid JSON: ${error.message}`, {
+            cause: error,
+        });
     }
     const local = configSchema.safeParse(data);
     if (!local.success)
-        throw new ConfigError(`${CONFIG_PATH} is invalid: ${z.prettifyError(local.error)}`);
+        throw new ConfigError(`${label} is invalid: ${z.prettifyError(local.error)}`);
     if (!local.data.extends)
         return { config: local.data, rules: [] };
     // A shared configuration that cannot be loaded costs its defaults, not the

package/dist/review/plan-render.d.ts

@@ -1,3 +1,3 @@
-import type { ReviewPreview } from "@open-cr-agent/core";
+import type { ReviewPreview } from "@open-cr-agent/core/internal";
 export declare function renderPlan(preview: ReviewPreview): string;
 //# sourceMappingURL=plan-render.d.ts.map

package/dist/review/plan-render.js

@@ -20,7 +20,7 @@ export function renderPlan(preview) {
     lines.push("", `Review tasks: ${preview.tasks.length}`);
     const width = Math.max(0, ...preview.tasks.map((t) => t.taskId.length));
     for (const t of preview.tasks) {
-        lines.push(`  ${t.taskId.padEnd(width)}  ~${number.format(t.promptTokens)} prompt tokens${t.planPromptTokens === undefined ? "" : ` + plan ~${number.format(t.planPromptTokens)}`}  ${t.bundle}`);
+        lines.push(`  ${t.taskId.padEnd(width)}  ~${number.format(t.promptTokens)} prompt tokens${t.planPromptTokens === undefined ? "" : ` + plan ~${number.format(t.planPromptTokens)}`}${t.effort === undefined ? "" : `  effort ${t.effort}`}  ${t.bundle}`);
     }
     if (preview.skipped.length > 0) {
         lines.push("", "Skipped by the review matrix:");

package/dist/review/progress.js

@@ -33,7 +33,7 @@ export class ProgressPrinter {
 function describe(event) {
     switch (event.type) {
         case "run_started":
-            return `Reviewing: ${event.changeRequest.title}`;
+            return `Reviewing: ${event.changeRequest.title} · run ${event.runId}`;
         case "files_selected":
             return `${event.selected} file(s) selected, ${event.excluded} excluded · risk tier: ${event.tier}`;
         case "files_bundled":

package/dist/review/provenance.d.ts

@@ -0,0 +1,6 @@
+import type { Sampling } from "@open-cr-agent/core";
+import type { ReviewArgs } from "./args.js";
+import type { CliConfig } from "./config.js";
+export declare function requestedSampling(config: CliConfig, args: ReviewArgs): Sampling;
+export declare function configHash(config: CliConfig, args: ReviewArgs): string;
+//# sourceMappingURL=provenance.d.ts.map

package/dist/review/provenance.js

@@ -0,0 +1,41 @@
+import { stableHash } from "@open-cr-agent/core/internal";
+// The sampling a review asks for: the configuration's, with --temperature
+// and --seed on top.
+export function requestedSampling(config, args) {
+    const temperature = args.temperature ?? config.sampling?.temperature;
+    const seed = args.seed ?? config.sampling?.seed;
+    return {
+        ...(temperature === undefined ? {} : { temperature }),
+        ...(seed === undefined ? {} : { seed }),
+    };
+}
+// The effective configuration and the flags that change what is reviewed
+// and how, so two runs can tell they were set up alike. Keys are names of
+// environment variables, never their values; a password written into a
+// URL is dropped. Sampling is recorded on its own. Effort is covered; left
+// unset it adds nothing, so configurations that set none keep their hash.
+export function configHash(config, args) {
+    const { sampling: _, providers, extends: shared, effort, roles, ...rest } = config;
+    return stableHash({
+        ...rest,
+        ...(Object.keys(effort).length > 0 ? { effort } : {}),
+        ...(Object.keys(roles).length > 0 ? { roles } : {}),
+        ...(shared === undefined ? {} : { extends: withoutCredentials(shared) }),
+        providers: Object.fromEntries(Object.entries(providers).map(([id, p]) => [
+            id,
+            { ...p, baseUrl: withoutCredentials(p.baseUrl) },
+        ])),
+        flags: { reviewers: args.reviewers, ultra: args.ultra, maxCostUsd: args.maxCostUsd },
+    });
+}
+function withoutCredentials(value) {
+    if (!URL.canParse(value))
+        return value;
+    const url = new URL(value);
+    if (url.username === "" && url.password === "")
+        return value;
+    url.username = "";
+    url.password = "";
+    return url.toString();
+}
+//# sourceMappingURL=provenance.js.map

package/dist/review/remote-config.d.ts

@@ -1,10 +1,16 @@
 import { z } from "zod";
 export declare const remoteConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
     models: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
         light: "light";
         standard: "standard";
         top: "top";
     }>, z.ZodUnknown>>;
+    effort: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        light: "light";
+        standard: "standard";
+        top: "top";
+    }> & z.core.$partial, z.ZodUnknown>>;
     concurrency: z.ZodOptional<z.ZodUnknown>;
     taskTimeoutMinutes: z.ZodOptional<z.ZodUnknown>;
     runTimeoutMinutes: z.ZodOptional<z.ZodUnknown>;
@@ -15,6 +21,7 @@ export declare const remoteConfigSchema: z.ZodObject<{
     include: z.ZodOptional<z.ZodArray<z.ZodString>>;
     exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
     reviewers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    roles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     github: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     providers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     rules: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/dist/review/remote-config.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { repoRuleSchema } from "@open-cr-agent/core";
+import { OcraError } from "@open-cr-agent/core";
+import { repoRuleSchema } from "@open-cr-agent/core/internal";
 import { z } from "zod";
 const MAX_BYTES = 256 * 1024;
 const TIMEOUT_MS = 10_000;
@@ -8,7 +9,9 @@ const TIMEOUT_MS = 10_000;
 // is fetched from outside the repository.
 export const remoteConfigSchema = z
     .object({
+    $schema: z.string().optional(),
     models: z.record(z.enum(["top", "standard", "light"]), z.unknown()).optional(),
+    effort: z.partialRecord(z.enum(["top", "standard", "light"]), z.unknown()).optional(),
     concurrency: z.unknown().optional(),
     taskTimeoutMinutes: z.unknown().optional(),
     runTimeoutMinutes: z.unknown().optional(),
@@ -19,6 +22,7 @@ export const remoteConfigSchema = z
     include: z.array(z.string()).optional(),
     exclude: z.array(z.string()).optional(),
     reviewers: z.record(z.string(), z.unknown()).optional(),
+    roles: z.record(z.string(), z.unknown()).optional(),
     github: z.record(z.string(), z.unknown()).optional(),
     providers: z.record(z.string(), z.unknown()).optional(),
     rules: z.array(repoRuleSchema).max(500).optional(),
@@ -29,7 +33,7 @@ export async function fetchRemoteConfig(spec, fetchImpl = fetch) {
     const [address = "", fragment] = spec.split("#", 2);
     const url = new URL(address);
     if (url.protocol !== "https:")
-        throw new Error(`extends must be an https URL, got ${url.protocol}`);
+        throw new OcraError("CONFIG_INVALID", `extends must be an https URL, got ${url.protocol}`);
     const pinned = fragment?.startsWith("sha256=")
         ? fragment.slice("sha256=".length).toLowerCase()
         : undefined;
@@ -39,21 +43,21 @@ export async function fetchRemoteConfig(spec, fetchImpl = fetch) {
         redirect: "error",
     });
     if (!response.ok)
-        throw new Error(`${url.href} answered ${response.status}`);
+        throw new OcraError("CONFIG_INVALID", `${url.href} answered ${response.status}`);
     const body = await readLimited(response, MAX_BYTES, url.href);
     if (pinned !== undefined) {
         const actual = createHash("sha256").update(body).digest("hex");
         if (actual !== pinned)
-            throw new Error(`${url.href} does not match its pinned sha256`);
+            throw new OcraError("CONFIG_INVALID", `${url.href} does not match its pinned sha256`);
     }
     const parsed = remoteConfigSchema.safeParse(JSON.parse(body));
     if (!parsed.success)
-        throw new Error(`${url.href} is invalid: ${z.prettifyError(parsed.error)}`);
+        throw new OcraError("CONFIG_INVALID", `${url.href} is invalid: ${z.prettifyError(parsed.error)}`);
     // A provider decides where the code under review goes: unpinned, whoever
     // serves the file could send it to an endpoint of their choosing.
     if (pinned === undefined && Object.keys(parsed.data.providers ?? {}).length > 0) {
         const digest = createHash("sha256").update(body).digest("hex");
-        throw new Error(`${url.href} declares providers, which a shared configuration may do only when pinned; check its content, then extend "${address}#sha256=${digest}"`);
+        throw new OcraError("CONFIG_INVALID", `${url.href} declares providers, which a shared configuration may do only when pinned; check its content, then extend "${address}#sha256=${digest}"`);
     }
     return parsed.data;
 }
@@ -71,7 +75,7 @@ async function readLimited(response, limit, name) {
         size += value.byteLength;
         if (size > limit) {
             await reader.cancel();
-            throw new Error(`${name} is larger than 256 KB`);
+            throw new OcraError("CONFIG_INVALID", `${name} is larger than 256 KB`);
         }
         chunks.push(value);
     }
@@ -81,7 +85,7 @@ async function readLimited(response, limit, name) {
 export function mergeConfig(remote, local) {
     const { rules: _rules, ...settings } = remote;
     const merged = { ...settings, ...local };
-    for (const key of ["models", "reviewers", "github", "providers"]) {
+    for (const key of ["models", "effort", "reviewers", "roles", "github", "providers"]) {
         const a = settings[key];
         const b = local[key];
         if (a !== undefined || b !== undefined)

package/dist/review/render.d.ts

@@ -1,4 +1,5 @@
-import { type ReviewReport, serializeOutput } from "@open-cr-agent/core";
+import { type ReviewReport } from "@open-cr-agent/core";
+import { serializeOutput } from "@open-cr-agent/core/internal";
 export declare function renderJson(report: ReviewReport): string;
 export declare const safeJson: typeof serializeOutput;
 export declare function renderText(report: ReviewReport, sessionDir?: string): string;

package/dist/review/render.js

@@ -1,4 +1,5 @@
-import { coverageGaps, serializeOutput, toReportOutput, } from "@open-cr-agent/core";
+import { coverageGaps, toReportOutput, } from "@open-cr-agent/core";
+import { serializeOutput } from "@open-cr-agent/core/internal";
 import { forTerminal } from "./terminal.js";
 const SEVERITIES = ["critical", "warning", "suggestion"];
 const VERIFICATION = {
@@ -86,8 +87,7 @@ export function renderText(report, sessionDir) {
     }
     for (const warning of report.warnings)
         lines.push(`Warning: ${warning}`);
-    if (sessionDir)
-        lines.push(`Session: ${sessionDir}`);
+    lines.push(`Run: ${report.runId}${sessionDir ? ` (${sessionDir})` : ""}`);
     return forTerminal(`${lines.join("\n")}\n`);
 }
 function emptyMessage(report, nothingReviewed, notReviewed) {

package/dist/review/runtimes.d.ts

@@ -0,0 +1,5 @@
+import { type OcraPlugin } from "@open-cr-agent/core";
+export type RuntimeLoaders = Readonly<Record<string, () => Promise<OcraPlugin>>>;
+export declare const BUILTIN_RUNTIMES: RuntimeLoaders;
+export declare function loadRuntime(runtime: string, packageName: string, load: () => Promise<OcraPlugin>): Promise<OcraPlugin>;
+//# sourceMappingURL=runtimes.d.ts.map

package/dist/review/runtimes.js

@@ -0,0 +1,29 @@
+import { OcraError } from "@open-cr-agent/core";
+import { VERSION } from "../version.js";
+export const BUILTIN_RUNTIMES = {
+    opencode: () => loadRuntime("opencode", "@open-cr-agent/runtime-opencode", async () => (await import("@open-cr-agent/runtime-opencode")).opencodeRuntimePlugin),
+    direct: () => loadRuntime("direct", "@open-cr-agent/runtime-direct", async () => (await import("@open-cr-agent/runtime-direct")).directRuntimePlugin),
+};
+export async function loadRuntime(runtime, packageName, load) {
+    try {
+        return await load();
+    }
+    catch (error) {
+        if (!isMissingPackage(error, packageName))
+            throw error;
+        const other = runtime === "direct" ? "opencode" : "direct";
+        throw new OcraError("RUNTIME_START_FAILED", `The ${runtime} runtime needs ${packageName}, which is not installed ` +
+            "(an optional dependency of @open-cr-agent/cli, left out by --omit=optional). " +
+            `Install it next to ocra with npm install ${packageName}@${VERSION} (-g for a global ocra), ` +
+            `or set "runtime": "${other}" in the configuration.`, { cause: error });
+    }
+}
+// Node reports a bare specifier it cannot resolve as ERR_MODULE_NOT_FOUND,
+// naming the package; a module missing inside the package names another.
+function isMissingPackage(error, packageName) {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code;
+    return code === "ERR_MODULE_NOT_FOUND" && error.message.includes(`'${packageName}'`);
+}
+//# sourceMappingURL=runtimes.js.map

package/dist/review/sarif-input.d.ts

@@ -0,0 +1,4 @@
+import { type SarifLog } from "@open-cr-agent/core";
+export declare const MAX_SARIF_BYTES: number;
+export declare function loadSarifLogs(paths: readonly string[], cwd: string): Promise<SarifLog[]>;
+//# sourceMappingURL=sarif-input.d.ts.map

package/dist/review/sarif-input.js

@@ -0,0 +1,34 @@
+import { readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseSarifLog } from "@open-cr-agent/core";
+import { ConfigError } from "./config.js";
+// A log is untrusted input like everything else that reaches the review; it
+// is bounded before it is parsed.
+export const MAX_SARIF_BYTES = 20 * 1024 * 1024;
+export async function loadSarifLogs(paths, cwd) {
+    const logs = [];
+    for (const path of paths) {
+        const file = resolve(cwd, path);
+        let text;
+        try {
+            const { size } = await stat(file);
+            if (size > MAX_SARIF_BYTES) {
+                throw new ConfigError(`--import-sarif ${path}: larger than ${MAX_SARIF_BYTES} bytes`);
+            }
+            text = await readFile(file, "utf8");
+        }
+        catch (error) {
+            if (error instanceof ConfigError)
+                throw error;
+            throw new ConfigError(`--import-sarif ${path}: ${error.message}`);
+        }
+        try {
+            logs.push(parseSarifLog(text));
+        }
+        catch (error) {
+            throw new ConfigError(`--import-sarif ${path}: ${error.message}`);
+        }
+    }
+    return logs;
+}
+//# sourceMappingURL=sarif-input.js.map

package/dist/review/sarif.js

@@ -1,4 +1,5 @@
-import { coverageGaps, serializeOutput, } from "@open-cr-agent/core";
+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
@@ -26,17 +27,20 @@ export function renderSarif(report, version) {
         version: "2.1.0",
         runs: [
             {
+                automationDetails: { id: `ocra/${report.runId}` },
                 tool: {
                     driver: {
                         name: "ocra",
-                        informationUri: "https://ocra.majincheng.com",
+                        informationUri: "https://ocracloud.com",
                         version,
                         semanticVersion: version,
                         rules: categories.map((id) => ({
                             id,
                             name: id,
                             shortDescription: {
-                                text: id === CARRIED ? CARRIED_DESCRIPTION : `Findings of ocra's ${id} reviewer`,
+                                text: id === CARRIED
+                                    ? CARRIED_DESCRIPTION
+                                    : `Findings of the ${id} reviewer or analyzer`,
                             },
                             properties: { tags: [id] },
                         })),
@@ -100,6 +104,8 @@ function fromFinding(f, index) {
             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 }),
         },
     };
 }

package/dist/review/target.d.ts

@@ -1,4 +1,4 @@
-import type { OcraPlugin, PluginRegistry, VcsAdapter } from "@open-cr-agent/core";
+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 {
@@ -11,7 +11,7 @@ export interface ReviewTarget {
 }
 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 mergeRequestTarget(mr: MergeRequestTarget, 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,17 +1,21 @@
-import { DEFAULT_BOT_LOGIN, GitHubApi } from "@open-cr-agent/vcs-github";
-import { GitLabApi } from "@open-cr-agent/vcs-gitlab";
-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,
@@ -29,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);
@@ -43,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,
@@ -81,10 +87,10 @@ const GITLAB_API = "https://gitlab.com/api/v4";
 // 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) {
+export async function mergeRequestTarget(mr, cwd, root, env, warn, fetchImpl, ignoreRepoConfig = false, configFile) {
     const token = env.GITLAB_TOKEN;
     if (!token) {
-        throw new ConfigError("--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)");
+        throw new OcraError("CONFIG_CREDENTIALS_MISSING", "--mr needs a GitLab token in GITLAB_TOKEN with the api scope and the Developer role: a project access token, or on GitLab.com Free a personal access token of a dedicated account (CI_JOB_TOKEN cannot post comments)");
     }
     const origin = await originUrl(root);
     const project = mr.project ?? env.CI_PROJECT_ID ?? gitlabProject(origin);
@@ -96,19 +102,21 @@ export async function mergeRequestTarget(mr, cwd, root, env, warn, fetchImpl, ig
     });
     const merge = await api.getMergeRequest(mr.iid);
     const refs = merge.diff_refs;
-    if (!refs)
-        throw new ConfigError(`merge request !${mr.iid} has no diff yet; try again shortly`);
+    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 .ocra/config.json are not loaded for merge requests");
+        warn("plugins in the configuration are not loaded for merge requests");
     }
     const code = new LocalGitAdapter({
         cwd,

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