@mrkaran/hodor 0.4.1

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+type Platform = "github" | "gitlab";
+interface ParsedPrUrl {
+    owner: string;
+    repo: string;
+    prNumber: number;
+    host: string;
+}
+interface MrMetadata {
+    title?: string;
+    description?: string;
+    source_branch?: string;
+    target_branch?: string;
+    changes_count?: number;
+    labels?: Array<string | {
+        name?: string;
+    }>;
+    label_details?: Array<string | {
+        name?: string;
+    }>;
+    author?: {
+        username?: string;
+        name?: string;
+    };
+    pipeline?: {
+        status?: string;
+        web_url?: string;
+    };
+    Notes?: Array<NoteEntry>;
+    state?: string;
+}
+interface NoteEntry {
+    body?: string;
+    author?: {
+        username?: string;
+        name?: string;
+    };
+    created_at?: string;
+    system?: boolean;
+}
+interface ReviewMetrics {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+    cost: number;
+    turns: number;
+    toolCalls: number;
+    durationSeconds: number;
+}
+type ReviewPriority = 0 | 1 | 2 | 3;
+type ReviewCorrectness = "patch is correct" | "patch is incorrect";
+interface ReviewFinding {
+    title: string;
+    body: string;
+    priority: ReviewPriority;
+    code_location: {
+        absolute_file_path: string;
+        line_range: {
+            start: number;
+            end: number;
+        };
+    };
+}
+interface ReviewOutput {
+    findings: ReviewFinding[];
+    overall_correctness: ReviewCorrectness;
+    overall_explanation: string;
+}
+interface PostCommentResult {
+    success: boolean;
+    platform?: Platform;
+    prNumber?: number;
+    mrNumber?: number;
+    error?: string;
+}
+
+interface AgentProgressEvent {
+    type: "tool_start" | "tool_end" | "thinking" | "turn_start" | "turn_end" | "agent_start" | "agent_end" | "text_delta" | "thinking_delta" | "tool_result";
+    toolName?: string;
+    toolArgs?: string;
+    isError?: boolean;
+    turnIndex?: number;
+    delta?: string;
+    result?: string;
+}
+declare function detectPlatform(prUrl: string): Platform;
+declare function parsePrUrl(prUrl: string): ParsedPrUrl;
+declare function postReviewComment(opts: {
+    prUrl: string;
+    reviewText: string;
+    model?: string | null;
+    metricsFooter?: string | null;
+    headSha?: string | null;
+}): Promise<PostCommentResult>;
+declare function reviewPr(opts: {
+    prUrl?: string;
+    model?: string;
+    reasoningEffort?: string;
+    customPrompt?: string | null;
+    promptFile?: string | null;
+    cleanup?: boolean;
+    workspaceDir?: string | null;
+    includeMetricsFooter?: boolean;
+    onEvent?: (event: AgentProgressEvent) => void;
+    bedrockTags?: Record<string, string> | null;
+    localMode?: boolean;
+    diffAgainst?: string;
+}): Promise<{
+    review: ReviewOutput;
+    metricsFooter: string | null;
+    headSha: string | null;
+    metrics: ReviewMetrics;
+}>;
+
+declare function buildPrReviewPrompt(opts: {
+    prUrl: string;
+    platform: Platform;
+    targetBranch?: string;
+    diffBaseSha?: string | null;
+    mrMetadata?: MrMetadata | null;
+    customInstructions?: string | null;
+    customPromptFile?: string | null;
+    embeddedDiff?: string | null;
+    previousReviewSha?: string | null;
+    localMode?: boolean;
+}): string;
+
+interface ParsedModel {
+    provider: string;
+    modelId: string;
+}
+/**
+ * Parse a model string like "anthropic/claude-sonnet-4-5" into { provider, modelId }.
+ * Handles bare names like "claude-sonnet-4-5" or "gpt-5" via auto-detection.
+ */
+declare function parseModelString(model: string): ParsedModel;
+/**
+ * Map reasoning effort strings to pi-ai thinking levels.
+ * Returns undefined for no reasoning.
+ */
+declare function mapReasoningEffort(effort: string | undefined): "low" | "medium" | "high" | undefined;
+/**
+ * Get API key with provider-aware selection.
+ *
+ * Priority:
+ * 1. LLM_API_KEY (universal override)
+ * 2. Provider-specific key (ANTHROPIC_API_KEY, OPENAI_API_KEY)
+ * 3. Fallback to any available key
+ *
+ * Returns null for bedrock (uses AWS credentials).
+ */
+declare function getApiKey(model?: string): string | null;
+
+declare function formatMetricsMarkdown(metrics: ReviewMetrics): string;
+declare function printMetrics(metrics: ReviewMetrics, stream?: NodeJS.WritableStream): void;
+/**
+ * Push review metrics to a Prometheus Pushgateway.
+ * Failures are logged as warnings and never thrown.
+ */
+declare function pushMetrics(opts: {
+    pushgatewayUrl: string;
+    metrics: ReviewMetrics;
+    labels?: Record<string, string>;
+}): Promise<void>;
+
+declare function validateReviewOutput(review: ReviewOutput): ReviewOutput;
+
+/**
+ * Render structured review output into clean markdown for PR/MR comments.
+ */
+
+/**
+ * Render a ReviewOutput into clean markdown for posting as a PR/MR comment.
+ */
+declare function renderMarkdown(review: ReviewOutput): string;
+
+export { type AgentProgressEvent, type MrMetadata, type NoteEntry, type ParsedPrUrl, type Platform, type PostCommentResult, type ReviewCorrectness, type ReviewFinding, type ReviewMetrics, type ReviewOutput, type ReviewPriority, buildPrReviewPrompt, detectPlatform, formatMetricsMarkdown, getApiKey, mapReasoningEffort, parseModelString, parsePrUrl, postReviewComment, printMetrics, pushMetrics, renderMarkdown, reviewPr, validateReviewOutput };

package/dist/index.js

@@ -0,0 +1,31 @@
+import {
+  buildPrReviewPrompt,
+  detectPlatform,
+  formatMetricsMarkdown,
+  getApiKey,
+  mapReasoningEffort,
+  parseModelString,
+  parsePrUrl,
+  postReviewComment,
+  printMetrics,
+  pushMetrics,
+  renderMarkdown,
+  reviewPr,
+  validateReviewOutput
+} from "./chunk-QGUJENIG.js";
+export {
+  buildPrReviewPrompt,
+  detectPlatform,
+  formatMetricsMarkdown,
+  getApiKey,
+  mapReasoningEffort,
+  parseModelString,
+  parsePrUrl,
+  postReviewComment,
+  printMetrics,
+  pushMetrics,
+  renderMarkdown,
+  reviewPr,
+  validateReviewOutput
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@mrkaran/hodor",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.4.1",
+  "description": "AI-powered code review agent that finds bugs, security issues, and logic errors in pull requests",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "hodor": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "keywords": [
+    "ai",
+    "code-review",
+    "github",
+    "gitlab",
+    "pr",
+    "automation",
+    "agent",
+    "hodor"
+  ],
+  "author": "Karan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mr-karan/hodor"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.48",
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@mariozechner/pi-ai": "^0.62.0",
+    "@mariozechner/pi-coding-agent": "^0.62.0",
+    "chalk": "^5.4.0",
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/tool-review.md

@@ -0,0 +1,125 @@
+# Code Review Task
+
+You are an automated code reviewer analyzing {pr_url}. The PR branch is checked out at the workspace.
+
+## Your Mission
+
+Identify production bugs in the PR's diff only. You are in READ-ONLY mode - analyze code, do not modify files.
+
+{mr_context_section}
+
+{mr_notes_section}
+
+{mr_reminder_section}
+
+{incremental_section}
+
+{embedded_diff_section}
+
+{diff_fetch_instructions}
+
+## Tools Available
+
+**Disable git pager to avoid interactive sessions:**
+```bash
+export GIT_PAGER=cat
+```
+
+**Available commands:**
+- `{pr_diff_cmd}` - List changed files ONLY (run this FIRST, not full diff)
+- `{git_diff_cmd} -- path/to/file` - See changes for ONE specific file at a time
+- `read` - Read full file with context (use sparingly, only when needed)
+- `grep` - Search for patterns across multiple files efficiently
+- `submit_review` - Submit the final structured review when analysis is complete
+
+## Review Guidelines
+
+You are acting as a reviewer for a proposed code change made by another engineer.
+
+### Bug Criteria (ALL must apply)
+
+1. It meaningfully impacts the accuracy, performance, security, or maintainability of the code.
+2. The bug is discrete and actionable (not a general issue with the codebase or combination of multiple issues).
+3. Fixing the bug does not demand a level of rigor that is not present in the rest of the codebase.
+4. The bug was introduced in this PR's diff (pre-existing bugs should not be flagged).
+5. The author of the PR would likely fix the issue if they were made aware of it.
+6. The bug does not rely on unstated assumptions about the codebase or author's intent.
+7. It is not enough to speculate that a change may disrupt another part of the codebase - you must identify the other parts of the code that are provably affected.
+8. The bug is clearly not just an intentional design choice by the author.
+
+### Comment Guidelines
+
+1. The comment should be clear about why the issue is a bug.
+2. The comment should appropriately communicate the severity of the issue. Do not claim an issue is more severe than it actually is.
+3. The comment should be brief. The body should be at most 1 paragraph. Do not introduce line breaks within natural language flow unless necessary for code fragments.
+4. The comment should not include any chunks of code longer than 3 lines. Any code chunks should be wrapped in markdown inline code tags or code blocks.
+5. The comment should clearly and explicitly communicate the scenarios, environments, or inputs necessary for the bug to arise. The comment should immediately indicate that the issue's severity depends on these factors.
+6. The comment's tone should be matter-of-fact and not accusatory or overly positive. It should read as a helpful AI assistant suggestion without sounding too much like a human reviewer.
+7. The comment should be written such that the author can immediately grasp the idea without close reading.
+8. The comment should avoid excessive flattery and comments that are not helpful to the author. Avoid phrasing like "Great job...", "Thanks for...".
+
+### Priority Levels
+
+Tag each finding in the title with a priority level:
+- **[P0] Critical**: Drop everything to fix. Blocking release, operations, or major usage. Only use for universal issues that do not depend on any assumptions about the inputs. Examples: Race conditions, null derefs, SQL injection, XSS, auth bypasses, data corruption.
+- **[P1] High**: Urgent. Should be addressed in the next cycle. Will break in production under specific conditions. Examples: Logic errors, resource leaks, memory leaks.
+- **[P2] Important**: Normal. To be fixed eventually. Performance or maintainability issues. Examples: N+1 queries, O(n²) algorithms, missing validation, incorrect error handling.
+- **[P3] Low**: Nice to have. Code quality concerns. Examples: Code smells, magic numbers, overly complex logic, missing error messages.
+
+Always include the matching numeric priority field in the `submit_review` payload: set `"priority"` to 0 for P0, 1 for P1, 2 for P2, or 3 for P3. The title tag and numeric priority must agree.
+
+### How Many Findings to Return
+
+Output all findings that the original author would fix if they knew about it. If there is no finding that a person would definitely love to see and fix, prefer outputting no findings. Do not stop at the first qualifying finding. Continue until you've listed every qualifying finding.
+
+### Additional Guidelines
+
+- Ignore trivial style unless it obscures meaning or violates documented standards.
+- Use one comment per distinct issue (or a multi-line range if necessary).
+- Always keep the line range as short as possible for interpreting the issue. Avoid ranges longer than 5–10 lines; instead, choose the most suitable subrange that pinpoints the problem.
+- The code location should overlap with the diff.
+- Stay on-branch: Never file bugs that only exist because the feature branch is missing commits already present on `{target_branch}`.
+
+{review_process_section}
+
+**Analysis Focus:**
+- Check edge cases: empty inputs, null values, boundary conditions, error paths
+- Think: What user input or race condition breaks this?
+- Focus on the changes (+ and - lines), use full file context sparingly
+
+## Final Submission
+
+When you are done, call `submit_review` exactly once with the final structured review.
+
+### submit_review payload
+
+```json
+{
+  "findings": [
+    {
+      "title": "<≤ 80 chars, imperative, with [P0]/[P1]/[P2]/[P3] prefix>",
+      "body": "<valid Markdown explaining why this is a problem; max 1 paragraph>",
+      "priority": 0 | 1 | 2 | 3,
+      "code_location": {
+        "absolute_file_path": "<absolute file path>",
+        "line_range": {"start": <int>, "end": <int>}
+      }
+    }
+  ],
+  "overall_correctness": "patch is correct" | "patch is incorrect",
+  "overall_explanation": "<1-3 sentence explanation justifying the verdict>"
+}
+```
+
+### Critical Submission Requirements
+
+* Call `submit_review` exactly once after analysis is complete.
+* Do not print the review as normal assistant text.
+* Do not wrap the payload in markdown fences when calling the tool.
+* If there are no findings, submit `"findings": []`.
+* Every finding must include `title`, `body`, `priority`, and `code_location`.
+* Use absolute file paths (for example, `/workspace/path/to/file.py`) not relative paths.
+* The title must start with a priority tag: `[P0]`, `[P1]`, `[P2]`, or `[P3]`.
+* `overall_correctness` must be exactly `"patch is correct"` or `"patch is incorrect"`.
+
+{start_instruction}