action.yml

name: umm-actually
description: LLM PR review via OpenRouter — one consolidated review, inline findings
author: aliasunder
branding:
  icon: eye
  color: purple

inputs:
  github_token:
    description: Token used to fetch the diff and submit the review (a GitHub App installation token keeps the bot identity)
    required: true
  openrouter_api_key:
    description: OpenRouter API key
    required: true
  model:
    description: OpenRouter model slug exactly as listed on openrouter.ai/models
    required: false
    default: anthropic/claude-sonnet-4-6
  fallback_model:
    description: Model tried after the primary model's attempts fail (up to two per model). A timed-out primary attempt moves to this model immediately, without retrying the primary. Auth and credit errors (HTTP 401/402/403) stop the review without trying it. Empty = no fallback
    required: false
    default: ""
  request_timeout_seconds:
    description: "Deadline for one model request, in seconds, capped by the time left in `review_timeout_seconds`. When it elapses, the attempt is recorded as `timeout` and the review moves to `fallback_model` if one is set; a timeout on the last model (the primary, when no fallback is set) may be retried once. The HTTP call is aborted best-effort: a request the provider keeps serving is still billed, and its cost-summary row shows `n/a`. Empty = 900"
    required: false
    default: "900"
  review_timeout_seconds:
    description: Shared model-work budget from action start, in seconds, including context preparation, all phases, retries, fallbacks and cost lookups. Completed phases post when it expires, with incomplete coverage identified; the run fails if none completed. Leave room below the workflow job timeout for setup and GitHub publication. External cancellation stops the run at once; unlike the deadline, it does not post completed phases. Empty = 1500
    required: false
    default: "1500"
  max_findings:
    description: Cap on posted findings, highest severity first. Empty = uncapped (all validated findings post)
    required: false
    default: ""
  severity_threshold:
    description: "Minimum severity to post: low | medium | high | critical"
    required: false
    default: low
  conventions_file:
    description: Repo-relative path to the conventions file included in the prompt (truncated at `conventions_budget_tokens`). When the PR also changes the file, its full text is sent at most once, never twice
    required: false
    default: AGENTS.md
  conventions_budget_tokens:
    description: Approximate token budget for the conventions file section of the prompt. A file over the budget is truncated to its beginning, with a notice in the prompt. To send the whole file, also list it in priority_docs, which reads it in full when the context budget allows. The job summary reports every truncation. The status comment and the check run's details page also report it when the whole file never reached the model, or when it reached the model only because this PR changes the file (or, for a JavaScript/TypeScript conventions file, a file it imports) and the file is not listed in priority_docs, since later PRs will see just the truncated beginning. A listed file that stops fitting is reported on the PR where it does not fit. Empty = the 8000 default
    required: false
    default: "8000"
  phases:
    description: "How the review dimensions are split across model calls: `combined` (one call carrying every dimension), `parallel` (three focused calls at once — each reads deeper, wall-clock time is the slowest call, and prompt tokens roughly triple), or `sequential` (the same three calls in order, each seeing the earlier calls' findings). When two calls report findings on overlapping lines of the same file, only the higher-severity finding is kept. Empty = `combined`"
    required: false
    default: combined
  context_budget_tokens:
    description: Approximate token budget for the diff plus every file sent in the prompt. A diff over half the budget skips the review. The conventions file has its own budget, `conventions_budget_tokens`
    required: false
    default: "300000"
  trace_related_files:
    description: "Add files beyond the diff to the prompt: JavaScript/TypeScript files that import a changed file by relative path (to catch caller regressions) and `.md`/`.json` files that mention a changed file (to catch stale docs). Does not affect `priority_docs`"
    required: false
    default: "true"
  priority_docs:
    description: >-
      Comma-separated repo-relative paths sent to the model in full, with 10%
      of `context_budget_tokens` reserved for them, independent of
      `trace_related_files`. Docs not changed in the PR are read first, then
      changed ones, each in listed order, before changed files can use the
      budget. Reserved space they don't use goes back to changed files. A doc
      that doesn't fit the reserve is retried at the end with any budget left,
      and left out if it still doesn't fit. A doc already sent in full by
      another part of the prompt is not read again; a changed doc the prompt
      shows only as a diff can still be read here in full. A changed file
      excluded from the review diff stays excluded — `diff_exclude_paths` and
      linguist rules win over this list. Empty = disabled
    required: false
    default: "README.md"
  max_scan_files:
    description: "Maximum files each repo scan collects before stopping. There are two scans, both run only when `trace_related_files` is on: JavaScript/TypeScript files for import tracing and `.md`/`.json` files for doc mentions. Files of other types or over `max_scan_bytes` don't count"
    required: false
    default: "5000"
  max_scan_bytes:
    description: Maximum byte size of a single file in the repo scans; larger files are skipped. It also caps the root `.gitattributes`; a larger one is ignored, so none of its `linguist-generated` rules apply
    required: false
    default: "524288"
  max_related_files:
    description: Maximum import-traced related files to include in review context
    required: false
    default: "15"
  max_related_docs:
    description: Maximum mention-matched documentation files to include in review context. `priority_docs` entries are never mention-matched and don't count toward this cap
    required: false
    default: "10"
  exclude_paths:
    description: >-
      Comma-separated folder paths, relative to the repo root, excluded from
      the repo scans (see `max_scan_files`). Files under these folders are
      invisible to import-tracing and doc-mention matching. Entries match
      folders only, by full path: `fixtures` skips the top-level `fixtures/`
      but not `src/fixtures/`. The scans also always skip folders whose names
      start with `.` and any folder named `node_modules`, `dist`, `build`,
      `out`, or `coverage`. Changed files in the PR diff and `priority_docs`
      are never excluded. Empty = no exclusions. Example: `evals, fixtures,
      test/fixtures`
    required: false
    default: ""
  diff_exclude_paths:
    description: >-
      Comma-separated folder prefixes or globs removed from the review diff
      before the token budget check — excluded files are listed by name in
      the review output but their content is not reviewed (excluded is not
      vetted). Supplied patterns EXTEND a built-in default list of
      generated artifacts (ecosystem lockfiles, *.min.js, *.min.css,
      *.map — the classes GitHub's linguist auto-collapses); a leading
      "none" drops the defaults, so "none" alone disables the built-in
      list (linguist-generated exclusions are governed separately by
      respect_linguist_generated) and "none, evals/**" replaces the list
      outright. Empty = the default
      list (unlike exclude_paths, where empty means no exclusions). Patterns with
      more than 2 "*" in one path segment are rejected ("**" segments are
      exempt) — glob matching backtracks exponentially on such shapes.
      Example: none, **/__snapshots__/**
    required: false
    default: ""
  respect_linguist_generated:
    description: >-
      Also exclude changed files the repo's root .gitattributes marks
      linguist-generated=true (nested .gitattributes files are not read).
      Negated entries (-linguist-generated) keep a file reviewable even
      when the default diff_exclude_paths list matches it; explicitly
      supplied diff_exclude_paths patterns always win. Rules are read from
      the PR head, so a PR changing .gitattributes reviews under its own
      rules — exclusions are always named in the review output
    required: false
    default: "true"
  cost_summary:
    description: Write a per-run cost report (model, prompt/completion tokens, USD) to the workflow job summary and the check run's details page
    required: false
    default: "true"
  pr_number:
    description: PR number override — required only when the triggering event does not identify a PR directly. Empty = taken from the event
    required: false
    default: ""

outputs:
  findings_count:
    description: Number of new findings posted this run. Non-findings, findings on files the model never saw or that diff exclusion removed, duplicates, findings already posted on an earlier run, and findings below `severity_threshold` are removed before `max_findings` applies; a finding whose post failed is not counted
  review_url:
    description: URL of the submitted review; empty when no review was posted
  model_used:
    description: Model(s) that answered, as named in OpenRouter's response for each completed phase (the routed model, so a phase that fell back reports the fallback model), comma-separated when phases used different models. Empty when the review was skipped
  skipped_reason:
    description: Non-empty when the review was skipped (e.g. diff too large)

runs:
  using: docker
  image: Dockerfile