@contextrail/code-review-agent 0.1.1-alpha.0

package/dist/reviewers/tool-call-tracker.js

@@ -0,0 +1,40 @@
+export const collectToolCalls = (toolCalls) => {
+    const collected = [];
+    const contextIds = [];
+    if (!Array.isArray(toolCalls)) {
+        return { toolCalls: collected, contextIds };
+    }
+    for (const call of toolCalls) {
+        collected.push({ tool: call.toolName, input: call.input });
+        if (call.toolName === 'get_context' && call.input && typeof call.input === 'object') {
+            const maybeId = call.input.contextId;
+            if (maybeId) {
+                contextIds.push(maybeId);
+            }
+        }
+    }
+    return { toolCalls: collected, contextIds };
+};
+export const mergeIterationTracking = (current, iteration) => {
+    current.toolCalls.push(...iteration.toolCalls);
+    for (const id of iteration.contextIds) {
+        if (!current.contextIds.includes(id)) {
+            current.contextIds.push(id);
+        }
+    }
+};
+/**
+ * Merge token usage from multiple sources.
+ * Sums promptTokens, completionTokens, and totalTokens.
+ */
+export const mergeTokenUsage = (usages) => {
+    const validUsages = usages.filter((u) => u !== undefined);
+    if (validUsages.length === 0) {
+        return undefined;
+    }
+    return {
+        promptTokens: validUsages.reduce((sum, u) => sum + u.promptTokens, 0),
+        completionTokens: validUsages.reduce((sum, u) => sum + u.completionTokens, 0),
+        totalTokens: validUsages.reduce((sum, u) => sum + u.totalTokens, 0),
+    };
+};

package/dist/reviewers/types.d.ts

@@ -0,0 +1,12 @@
+import type { ReviewerFindings, TokenUsage } from '../output/schema.js';
+export type { TokenUsage };
+export type ToolCallEntry = {
+    tool: string;
+    input?: unknown;
+};
+export type ReviewerIterationResult = {
+    findings: ReviewerFindings;
+    toolCalls: ToolCallEntry[];
+    contextIds: string[];
+    usage?: TokenUsage;
+};

package/dist/reviewers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/reviewers/validation-rules.d.ts

@@ -0,0 +1,27 @@
+import type { Finding } from '../output/schema.js';
+export type ValidationResult = {
+    passed: Finding[];
+    rejected: Array<{
+        finding: Finding;
+        reason: string;
+    }>;
+};
+/**
+ * Apply non-negotiable attribution guardrails.
+ * These run on every iteration to prevent unsupported ContextRail claims.
+ */
+export declare const applyAttributionGuardrails: (findings: Finding[]) => ValidationResult;
+/**
+ * Apply deterministic validation rules to findings.
+ * These rules run before the LLM critic pass to filter out obvious issues.
+ *
+ * Rules:
+ * 1. Reject findings where file is empty or line is undefined (unless it's a general finding)
+ * 2. Reject findings where severity is "critical" but description lacks security/integrity keywords
+ * 3. Reject findings that duplicate another finding's file:line:title
+ * 4. Reject findings where rationale is empty or <20 characters
+ *
+ * @param findings - Findings to validate
+ * @returns Validation result with passed and rejected findings
+ */
+export declare const applyDeterministicValidationRules: (findings: Finding[]) => ValidationResult;

package/dist/reviewers/validation-rules.js

@@ -0,0 +1,189 @@
+const CONTEXT_ID_PREFIX = 'context://';
+/**
+ * Security/integrity keywords that should be present in critical findings.
+ * Critical findings without these keywords may be downgraded.
+ */
+const CRITICAL_KEYWORDS = [
+    'exploit',
+    'vulnerability',
+    'security',
+    'injection',
+    'bypass',
+    'unauthorized',
+    'secret',
+    'credential',
+    'password',
+    'token',
+    'authentication',
+    'authorization',
+    'corruption',
+    'integrity',
+    'data loss',
+    'breach',
+    'attack',
+    'malicious',
+    'xss',
+    'csrf',
+    'sql injection',
+    'command injection',
+    'path traversal',
+    'hardcoded',
+];
+/**
+ * Check if a finding's description/rationale contains security/integrity keywords.
+ */
+const hasSecurityKeywords = (finding) => {
+    const text = `${finding.description} ${finding.rationale}`.toLowerCase();
+    return CRITICAL_KEYWORDS.some((keyword) => text.includes(keyword));
+};
+/**
+ * Generate a unique key for a finding based on file, line, and title.
+ * Used for duplicate detection.
+ */
+const getFindingKey = (finding) => {
+    const file = finding.file ?? '';
+    const line = finding.line ?? '';
+    const title = finding.title.toLowerCase().trim();
+    return `${file}:${line}:${title}`;
+};
+/**
+ * Check if an attribution field is effectively empty (null or empty array).
+ * Empty arrays are treated as equivalent to null since cleanFinding normalizes them.
+ */
+const isEmptyAttributionField = (value) => {
+    return value === null || value === undefined || (Array.isArray(value) && value.length === 0);
+};
+const hasRetrievedContextAttribution = (finding) => !isEmptyAttributionField(finding.contextIdsUsed) || !isEmptyAttributionField(finding.contextIdsViolated);
+const mentionsContextRailInText = (finding) => {
+    const text = `${finding.title} ${finding.description} ${finding.rationale}`.toLowerCase();
+    return text.includes('contextrail') || text.includes(CONTEXT_ID_PREFIX);
+};
+const hasInvalidContextIdFormat = (finding) => {
+    const ids = [
+        ...(isEmptyAttributionField(finding.contextIdsUsed) ? [] : (finding.contextIdsUsed ?? [])),
+        ...(isEmptyAttributionField(finding.contextIdsViolated) ? [] : (finding.contextIdsViolated ?? [])),
+    ];
+    return ids.some((id) => !id.startsWith(CONTEXT_ID_PREFIX));
+};
+const hasAnyContextIds = (finding) => !isEmptyAttributionField(finding.contextIdsUsed) ||
+    !isEmptyAttributionField(finding.contextIdsViolated) ||
+    hasRetrievedContextAttribution(finding);
+const hasContextTitles = (finding) => !isEmptyAttributionField(finding.contextTitles);
+const getAttributionInconsistencyReason = (finding) => {
+    // Treat empty arrays as equivalent to null (matches cleanFinding normalization behavior).
+    const hasIds = hasRetrievedContextAttribution(finding);
+    const hasTitles = hasContextTitles(finding);
+    if (hasTitles && !hasIds) {
+        return 'contextTitles provided without corresponding contextIdsUsed/contextIdsViolated';
+    }
+    if (hasIds && !hasTitles) {
+        return 'Context IDs provided without contextTitles';
+    }
+    // Empty arrays are normalized to null by cleanFinding, so validation accepts them.
+    // This ensures validation is aligned with schema normalization behavior.
+    return null;
+};
+/**
+ * Apply non-negotiable attribution guardrails.
+ * These run on every iteration to prevent unsupported ContextRail claims.
+ */
+export const applyAttributionGuardrails = (findings) => {
+    const passed = [];
+    const rejected = [];
+    for (const finding of findings) {
+        let shouldReject = false;
+        let rejectReason = '';
+        // Guardrail 1: ContextRail claims require retrieved attribution IDs.
+        if (mentionsContextRailInText(finding) && !hasRetrievedContextAttribution(finding)) {
+            shouldReject = true;
+            rejectReason = 'ContextRail claim without retrieved contextIds attribution';
+        }
+        // Guardrail 2: Context attribution fields must be internally consistent.
+        if (!shouldReject) {
+            const inconsistency = getAttributionInconsistencyReason(finding);
+            if (inconsistency) {
+                shouldReject = true;
+                rejectReason = inconsistency;
+            }
+        }
+        // Guardrail 3: Context IDs must use context:// format.
+        if (!shouldReject && hasInvalidContextIdFormat(finding)) {
+            shouldReject = true;
+            rejectReason = `Context ID format invalid; expected prefix "${CONTEXT_ID_PREFIX}"`;
+        }
+        if (shouldReject) {
+            rejected.push({ finding, reason: rejectReason });
+        }
+        else {
+            passed.push(finding);
+        }
+    }
+    return { passed, rejected };
+};
+/**
+ * Apply deterministic validation rules to findings.
+ * These rules run before the LLM critic pass to filter out obvious issues.
+ *
+ * Rules:
+ * 1. Reject findings where file is empty or line is undefined (unless it's a general finding)
+ * 2. Reject findings where severity is "critical" but description lacks security/integrity keywords
+ * 3. Reject findings that duplicate another finding's file:line:title
+ * 4. Reject findings where rationale is empty or <20 characters
+ *
+ * @param findings - Findings to validate
+ * @returns Validation result with passed and rejected findings
+ */
+export const applyDeterministicValidationRules = (findings) => {
+    const passed = [];
+    const rejected = [];
+    const seenKeys = new Set();
+    for (const finding of findings) {
+        let shouldReject = false;
+        let rejectReason = '';
+        // Rule 1: Reject findings missing file+line (unless it's a general/architectural finding)
+        // Allow findings without file/line only if they're architectural or general concerns
+        const hasFileButNoLine = finding.file && !finding.line;
+        if (hasFileButNoLine) {
+            shouldReject = true;
+            rejectReason = 'Missing line number for file-specific finding';
+        }
+        // Rule 2: Reject critical findings without security/integrity keywords
+        if (!shouldReject && finding.severity === 'critical' && !hasSecurityKeywords(finding)) {
+            shouldReject = true;
+            rejectReason =
+                'Critical finding lacks security/integrity keywords (exploit path, vulnerability, data corruption, etc.)';
+        }
+        // Rule 3: Reject duplicate findings (same file:line:title)
+        if (!shouldReject) {
+            const key = getFindingKey(finding);
+            if (seenKeys.has(key)) {
+                shouldReject = true;
+                rejectReason = `Duplicate finding: same file:line:title as another finding`;
+            }
+            else {
+                seenKeys.add(key);
+            }
+        }
+        // Rule 4: Reject findings with empty or very short rationale
+        if (!shouldReject && (!finding.rationale || finding.rationale.trim().length < 20)) {
+            shouldReject = true;
+            rejectReason = `Rationale too short (${finding.rationale?.length ?? 0} chars, minimum 20)`;
+        }
+        // Rule 5: Reject malformed attribution payloads when attribution fields are present.
+        // Check both context IDs and titles to catch inconsistencies (e.g., titles without IDs).
+        if (!shouldReject && (hasAnyContextIds(finding) || hasContextTitles(finding))) {
+            const inconsistency = getAttributionInconsistencyReason(finding);
+            if (inconsistency) {
+                shouldReject = true;
+                rejectReason = inconsistency;
+            }
+        }
+        if (shouldReject) {
+            rejected.push({ finding, reason: rejectReason });
+        }
+        else {
+            passed.push(finding);
+        }
+    }
+    return { passed, rejected };
+};

package/package.json

@@ -0,0 +1,79 @@
+{
+    "name": "@contextrail/code-review-agent",
+    "version": "0.1.1-alpha.0",
+    "description": "CLI tool for orchestrating ContextRail-powered code reviews",
+    "homepage": "https://contextrail.app",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/contextrail/contextrail-monorepo.git",
+        "directory": "packages/code-review-agent"
+    },
+    "bugs": {
+        "url": "https://github.com/contextrail/contextrail/issues"
+    },
+    "main": "dist/index.js",
+    "type": "module",
+    "bin": {
+        "code-review-agent": "dist/index.js"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "MODEL_RECOMMENDATIONS.md",
+        "LICENSE"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "clean": "node --eval \"const fs=require('node:fs');fs.rmSync('dist',{recursive:true,force:true});\"",
+        "build": "pnpm run clean && tsc",
+        "start": "node dist/index.js",
+        "dev": "pnpm run build && pnpm run start",
+        "prepublishOnly": "pnpm run build",
+        "pack:preview": "pnpm run build && pnpm pack --pack-destination ./.pack",
+        "typecheck": "tsc --noEmit",
+        "lint": "eslint src",
+        "lint:fix": "eslint src --fix",
+        "test": "vitest run",
+        "test:watch": "vitest watch",
+        "test:coverage": "vitest run --coverage",
+        "check": "pnpm run typecheck && pnpm run lint && pnpm run test",
+        "format": "prettier . --write",
+        "format:check": "prettier . --check",
+        "publish:alpha": "pnpm run check && npm version prerelease --preid=alpha && npm publish --tag alpha --access public",
+        "publish:patch": "pnpm run check && npm version patch && npm publish --access public",
+        "publish:minor": "pnpm run check && npm version minor && npm publish --access public",
+        "publish:major": "pnpm run check && npm version major && npm publish --access public"
+    },
+    "keywords": [
+        "cli",
+        "ai",
+        "code-review",
+        "standards",
+        "contextrail"
+    ],
+    "author": "ContextRail",
+    "license": "SEE LICENSE IN LICENSE",
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.24.3",
+        "@openrouter/ai-sdk-provider": "^2.1.1",
+        "ai": "^6.0.67",
+        "dedent": "^1.7.1",
+        "dotenv": "^16.6.1",
+        "jose": "^6.1.3",
+        "minimatch": "^10.1.1",
+        "simple-git": "^3.30.0",
+        "zod": "^3.23.8"
+    },
+    "devDependencies": {
+        "@types/node": "^22.10.2",
+        "@vitest/coverage-v8": "^4.0.16",
+        "tsx": "^4.20.6",
+        "typescript": "^5.7.2",
+        "vitest": "^4.0.16"
+    },
+    "engines": {
+        "node": ">=20"
+    }
+}