@orion-agents/orion-code 0.3.26 → 0.3.28

package/dist/services/code-review/contract.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FINDING_TEXT_LIMITS = exports.DEFAULT_REVIEW_BUDGETS = void 0;
+exports.validateReviewFinding = validateReviewFinding;
+exports.resolveReviewConclusion = resolveReviewConclusion;
+exports.resolveReviewBudgets = resolveReviewBudgets;
+exports.reviewApplicability = reviewApplicability;
+exports.computeReceiptDigest = computeReceiptDigest;
+exports.verifyReceiptDigest = verifyReceiptDigest;
+/**
+ * v0.3.27 PR0 — the shared code-review contract, frozen before any runtime
+ * wiring. This module is the single source of truth for review selectors,
+ * states, conclusions, findings, budgets and receipt digests; CLI and Web both
+ * consume it and neither may redefine the semantics locally (goal G3: one
+ * engine, one contract).
+ *
+ * Design sources: docs/plan/v0.3.27-plan.md §4 (identity, state, conclusions),
+ * §4.3 (bounded resources), §5 (read-only execution). The conclusion mapping
+ * encodes the plan's rule that tool success is not review success: a partial,
+ * failed, cancelled or untrustworthy output can never surface as a green
+ * "no findings".
+ */
+const canonical_1 = require("../../runtime/protocol/canonical");
+exports.DEFAULT_REVIEW_BUDGETS = Object.freeze({
+    maxFiles: 50,
+    maxBodyBytes: 2 * 1024 * 1024,
+    maxDiffBytes: 1024 * 1024,
+    maxReadToolCalls: 50,
+    maxDurationMs: 5 * 60 * 1000,
+    maxFindings: 100,
+    maxResultBytes: 256 * 1024,
+});
+/** Text size caps for finding fields, in characters. Chosen so 100 maximal
+ *  findings stay well inside the 256 KiB result bound. */
+exports.FINDING_TEXT_LIMITS = Object.freeze({
+    title: 200,
+    trigger: 2000,
+    impact: 2000,
+    evidence: 4000,
+    fileKey: 1024,
+});
+const FINDING_ID_PATTERN = /^[0-9a-f]{8,64}$/iu;
+const DIGEST_PATTERN = /^[0-9a-f]{64}$/;
+/** Validates one model-produced finding against the frozen shape. Returns the
+ *  finding unchanged when valid; a typed reason when not. Membership against
+ *  the snapshot manifest is a separate Host check (PR1+). */
+function validateReviewFinding(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return { valid: false, reason: 'not_an_object' };
+    }
+    const candidate = value;
+    const text = (field) => typeof candidate[field] === 'string' ? candidate[field] : '';
+    if (typeof candidate.findingId !== 'string' || !FINDING_ID_PATTERN.test(candidate.findingId)) {
+        return { valid: false, reason: 'finding_id_invalid' };
+    }
+    if (candidate.priority !== 'P0' &&
+        candidate.priority !== 'P1' &&
+        candidate.priority !== 'P2' &&
+        candidate.priority !== 'P3') {
+        return { valid: false, reason: 'priority_invalid' };
+    }
+    const title = text('title').trim();
+    if (!title || title.length > exports.FINDING_TEXT_LIMITS.title) {
+        return { valid: false, reason: 'title_invalid' };
+    }
+    const trigger = text('trigger').trim();
+    if (!trigger || trigger.length > exports.FINDING_TEXT_LIMITS.trigger) {
+        return { valid: false, reason: 'trigger_invalid' };
+    }
+    const impact = text('impact').trim();
+    if (!impact || impact.length > exports.FINDING_TEXT_LIMITS.impact) {
+        return { valid: false, reason: 'impact_invalid' };
+    }
+    const fileKey = text('fileKey');
+    if (!fileKey ||
+        fileKey.length > exports.FINDING_TEXT_LIMITS.fileKey ||
+        fileKey.startsWith('/') ||
+        fileKey.includes('\0') ||
+        fileKey.split('/').includes('..')) {
+        return { valid: false, reason: 'file_key_invalid' };
+    }
+    if (candidate.side !== 'old' && candidate.side !== 'new') {
+        return { valid: false, reason: 'side_invalid' };
+    }
+    const startLine = candidate.startLine;
+    const endLine = candidate.endLine;
+    if (!Number.isSafeInteger(startLine) ||
+        startLine < 1 ||
+        !Number.isSafeInteger(endLine) ||
+        endLine < startLine) {
+        return { valid: false, reason: 'line_range_invalid' };
+    }
+    const evidence = text('evidence').trim();
+    if (!evidence || evidence.length > exports.FINDING_TEXT_LIMITS.evidence) {
+        return { valid: false, reason: 'evidence_invalid' };
+    }
+    return {
+        valid: true,
+        finding: Object.freeze({
+            findingId: candidate.findingId,
+            priority: candidate.priority,
+            title,
+            trigger,
+            impact,
+            fileKey,
+            side: candidate.side,
+            startLine: startLine,
+            endLine: endLine,
+            evidence,
+        }),
+    };
+}
+/**
+ * v0.3.27 §4.1 — the conclusion mapping, frozen as code so CLI and Web cannot
+ * diverge. The invariants:
+ * - `queued`/`running` results carry no conclusion (callers must not call this).
+ * - A state that is not `completed` can never conclude `no_findings`.
+ * - Invalid findings make the output untrustworthy: zero valid findings with
+ *   invalid ones present is `inconclusive`, never a green pass.
+ * - Zero findings without complete coverage is `inconclusive`, never a green
+ *   pass ("不静默截断后宣布全部完成").
+ */
+function resolveReviewConclusion(input) {
+    if (input.state === 'queued' || input.state === 'running') {
+        throw new Error('A queued or running review cannot have a terminal conclusion.');
+    }
+    if (input.state === 'failed' || input.state === 'cancelled') {
+        return 'inconclusive';
+    }
+    if (input.validFindingCount > 0) {
+        return 'findings';
+    }
+    if (input.state === 'partial') {
+        return 'inconclusive';
+    }
+    // state === 'completed'
+    if (input.invalidFindingCount > 0) {
+        return 'inconclusive';
+    }
+    return input.coverageComplete ? 'no_findings' : 'inconclusive';
+}
+/** Applies the budgets with the tighten-only rule: every override must be a
+ *  safe integer at or below the frozen default, otherwise the run is refused
+ *  rather than silently widened. */
+function resolveReviewBudgets(overrides = {}) {
+    const resolved = {};
+    for (const [field, ceiling] of Object.entries(exports.DEFAULT_REVIEW_BUDGETS)) {
+        const requested = overrides[field];
+        if (requested === undefined) {
+            resolved[field] = ceiling;
+            continue;
+        }
+        if (!Number.isSafeInteger(requested) || requested < 1 || requested > ceiling) {
+            return { ok: false, field };
+        }
+        resolved[field] = requested;
+    }
+    return {
+        ok: true,
+        budgets: Object.freeze(resolved),
+    };
+}
+/** Marks a stored result's applicability against the current input snapshot and
+ *  rules digests. The receipt itself is never rewritten. */
+function reviewApplicability(result, current) {
+    return result.inputSnapshotDigest === current.inputSnapshotDigest &&
+        result.rulesDigest === current.rulesDigest
+        ? 'current'
+        : 'stale';
+}
+/** The receipt digest covers the canonical form of the result with the digest
+ *  field itself excluded, so verification is a recomputation, not a lookup. */
+function computeReceiptDigest(result) {
+    const content = { ...result };
+    delete content.receiptDigest;
+    const digest = (0, canonical_1.digestRuntimeValue)(content);
+    return DIGEST_PATTERN.test(digest) ? digest : digest.toLowerCase();
+}
+/** Verifies a stored receipt by recomputing its digest. */
+function verifyReceiptDigest(result) {
+    const { receiptDigest, ...content } = result;
+    return computeReceiptDigest(content) === receiptDigest;
+}
+//# sourceMappingURL=contract.js.map

package/dist/services/code-review/format.d.ts

@@ -0,0 +1,12 @@
+/**
+ * v0.3.28 — TUI rendering of a code-review receipt (docs/plan/v0.3.28-plan.md
+ * S3). The formatter is deliberately honest about state: a partial, failed,
+ * cancelled or inconclusive run never renders as a green "no findings" pass,
+ * and an empty scope is reported as "no changes under review", distinct from a
+ * completed review that found nothing (v0.3.27 plan §4.1).
+ */
+import type { CodeReviewResultV1 } from './contract';
+/** Renders the full report shown after `/review` finishes. `fileLabels` maps
+ *  snapshot fileKeys to human paths when the caller still holds the manifest. */
+export declare function formatReviewReport(result: CodeReviewResultV1, fileLabels?: ReadonlyMap<string, string>): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/services/code-review/format.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatReviewReport = formatReviewReport;
+const PRIORITY_ORDER = ['P0', 'P1', 'P2', 'P3'];
+const STATE_BANNERS = {
+    queued: 'Review queued.',
+    running: 'Review running.',
+    completed: 'Review completed.',
+    partial: 'Review PARTIAL — coverage was incomplete; findings below are valid but not exhaustive.',
+    failed: 'Review FAILED — no conclusions can be drawn from this run.',
+    cancelled: 'Review CANCELLED — no conclusions can be drawn from this run.',
+};
+function formatScope(result) {
+    const selector = result.requestedSelector;
+    if (selector.kind === 'base') {
+        const paths = selector.paths?.length ? ` paths: ${selector.paths.join(', ')}` : '';
+        return `base ${selector.ref} (${result.resolvedTarget.baseOid?.slice(0, 12) ?? '?'}..${result.resolvedTarget.headOid?.slice(0, 12) ?? '?'})${paths}`;
+    }
+    const paths = selector.paths?.length ? ` paths: ${selector.paths.join(', ')}` : '';
+    return `worktree (snapshot ${result.resolvedTarget.snapshotId})${paths}`;
+}
+/** Renders the full report shown after `/review` finishes. `fileLabels` maps
+ *  snapshot fileKeys to human paths when the caller still holds the manifest. */
+function formatReviewReport(result, fileLabels) {
+    const lines = [];
+    lines.push(`Code review ${result.reviewId} — ${formatScope(result)}`);
+    lines.push(`Model: ${result.model.provider}/${result.model.model} · input snapshot ${result.inputSnapshotDigest.slice(0, 12)}`);
+    const emptyScope = result.limits.includes('empty_scope_no_changes');
+    if (emptyScope) {
+        lines.push('');
+        lines.push('No changes under the selected scope — nothing to review.');
+        return lines.join('\n');
+    }
+    lines.push('');
+    lines.push(STATE_BANNERS[result.state]);
+    if (result.findings.length > 0) {
+        lines.push('');
+        lines.push(`Findings (${result.findings.length}):`);
+        for (const priority of PRIORITY_ORDER) {
+            const group = result.findings.filter(finding => finding.priority === priority);
+            if (group.length === 0)
+                continue;
+            for (const finding of group) {
+                lines.push('');
+                lines.push(`[${priority}] ${finding.title}`);
+                lines.push(`  Location: ${fileLabels?.get(finding.fileKey) ?? finding.fileKey.slice(0, 12)} ${finding.side}:${finding.startLine}-${finding.endLine}`);
+                lines.push(`  Trigger: ${finding.trigger}`);
+                lines.push(`  Impact: ${finding.impact}`);
+                lines.push(`  Evidence: ${finding.evidence}`);
+            }
+        }
+    }
+    else if (result.state === 'completed' && result.conclusion === 'no_findings') {
+        lines.push('No findings within the reviewed scope.');
+    }
+    if (result.invalidFindingCount > 0) {
+        lines.push('');
+        lines.push(`${result.invalidFindingCount} finding(s) from the model were invalid or outside the frozen snapshot and are not shown.`);
+    }
+    lines.push('');
+    const coverage = result.coverage;
+    lines.push(`Coverage: ${coverage.inspectedFiles.length} file(s) inspected, ${coverage.skipped.length} skipped${coverage.truncated ? ', output truncated' : ''}`);
+    for (const skip of coverage.skipped) {
+        lines.push(`  skipped: ${skip.fileKey} (${skip.reason})`);
+    }
+    if (coverage.budgetExhausted.length > 0) {
+        lines.push(`Budget exhausted: ${coverage.budgetExhausted.join(', ')}`);
+    }
+    for (const limit of result.limits) {
+        if (limit !== 'empty_scope_no_changes')
+            lines.push(`Limit: ${limit}`);
+    }
+    if (!result.coverageAssertion.complete && result.state === 'completed') {
+        lines.push(`Coverage incomplete: ${result.coverageAssertion.reason ?? 'not all changed files were reviewed'}`);
+    }
+    lines.push(`Receipt digest: ${result.receiptDigest.slice(0, 16)}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=format.js.map

package/dist/services/code-review/runner.d.ts

@@ -0,0 +1,71 @@
+import { DEFAULT_REVIEW_BUDGETS, type CodeReviewResultV1, type ReviewBudgetsV1, type ReviewSelectorV1 } from './contract';
+import { type ReviewGitRunner } from './snapshot';
+/** One bounded model completion. CLI wiring adapts `LLMService.chat`. */
+export interface ReviewModelAdapterV1 {
+    complete(messages: readonly {
+        readonly role: 'system' | 'user';
+        readonly content: string;
+    }[]): Promise<{
+        readonly content: string;
+        readonly model: string;
+        readonly usage?: {
+            readonly inputTokens: number;
+            readonly outputTokens: number;
+        };
+    }>;
+}
+export interface ReviewRunIdentityV1 {
+    readonly workspaceIdentity: string;
+    readonly sessionId: string;
+    readonly threadId: string;
+    readonly turnId: string;
+}
+export interface ReviewRunOptionsV1 {
+    readonly cwd: string;
+    readonly selector: ReviewSelectorV1;
+    readonly adapter: ReviewModelAdapterV1;
+    readonly identity: ReviewRunIdentityV1;
+    readonly budgets?: Partial<ReviewBudgetsV1>;
+    readonly abortSignal?: AbortSignal;
+    readonly runGit?: ReviewGitRunner;
+    readonly now?: () => number;
+}
+export type ReviewRunFailureV1 = {
+    readonly kind: 'budget';
+    readonly field: string;
+} | {
+    readonly kind: 'snapshot';
+    readonly code: string;
+    readonly message: string;
+} | {
+    readonly kind: 'cancelled';
+} | {
+    readonly kind: 'model_error';
+    readonly message: string;
+} | {
+    readonly kind: 'unparsable_output';
+    readonly message: string;
+};
+export type ReviewRunOutcomeV1 = {
+    readonly ok: true;
+    readonly result: CodeReviewResultV1;
+} | {
+    readonly ok: false;
+    readonly failure: ReviewRunFailureV1;
+};
+/** Production git runner: argument arrays, no shell, read-only profile is the
+ *  caller's responsibility (the runner only issues read commands). */
+export declare function createProcessGitRunner(cwd: string): ReviewGitRunner;
+/** Rules provenance: AGENTS.md contents from cwd up to the filesystem root
+ *  (bounded to 16 levels), combined with the frozen read-only constraints
+ *  digest. Changing the rules or the policy invalidates applicability. */
+export declare function computeReviewRulesDigest(cwd: string): Promise<string>;
+/** The frozen review instruction set assembled for the model. */
+export declare function buildReviewSystemPrompt(rulesDigest: string): string;
+/**
+ * Runs one bounded review. Never throws for expected review failures — the
+ * outcome is typed; unexpected internal errors surface as `model_error`.
+ */
+export declare function runCodeReview(options: ReviewRunOptionsV1): Promise<ReviewRunOutcomeV1>;
+export { DEFAULT_REVIEW_BUDGETS };
+//# sourceMappingURL=runner.d.ts.map